Developer mental model

The following describes the mental model for understanding how Nodlin behaves under large dependency closures.

Propagation of change follows the full dependency closure — but recomputation cost is controlled through deduplicated invalidation and hot-node coalescing.

1. Think of Nodes Like Spreadsheet Cells

A Nodlin node behaves like a spreadsheet cell.

It derives its value from related nodes.

E.g.

• Price -> Revenue
• Qty -> Revenue
• Revenue -> Profit
• Revenue -> Margin

When one value changes, dependent nodes recompute.

There are no ordered instructions, only dependencies.

2. Events do not carry data

Events are invalidation signals only.

They mean:

“Something related to you changed. Re-evaluate.”

Events contain no payload.

e.g.

• Price updated results in event to Revenue
• Revenue updated results in events to both Profit and Margin

When the Revenue is updated, the current state of Revenue, Price and Qty is obtained. The events between the nodes do not carry any data.

This design allows:

• event deduplication
• out-of-order execution
• horizontal scaling
• eventual convergence

3. Node execution

When a node recomputes it performs the following steps:

1. Read current state of neighbours
2. Compute derived result
3. Record neighbour versions used
4. Store result
5. Emit invalidation events

Important rule:

Nodes compute from state, not from events.

4. Propagation Follows the Dependency Graph

A change can propagate arbitrarily far through the graph.

Nodlin does not assume locality of impact.

Example:

• Leaf account posting
• Parent account total
• Division total
• Company total

In large organisational graphs, dependency chains can be long and shared.

This is expected.

5. Efficiency Comes From Coalescing, Not Locality

5.1 Deduplicate for single recomputation

Nodlin remains efficient because:

• events contain no payload
• invalidations can be deduplicated
• nodes recompute from current state
• heavily shared nodes naturally coalesce updates

When many updates affect the same upstream node, that node becomes hot.

Hot nodes introduce a small recomputation delay, which allows multiple invalidations to collapse into a single recomputation.

Example:

• 1000 leaf updates ->
• root node receives many invalidations ->
• deduplication occurs ->
• root recomputes once using the latest state

This reduces system load while preserving correctness.

5.2 Performance Characteristics

Nodlin prioritises correct propagation and scalability across large dependency graphs rather than minimising single-node execution latency.

Each recomputation involves:

• reading neighbour state
• scheduling execution
• publishing invalidation events
• persisting the resulting state

Because of this scheduling and messaging overhead, Nodlin should not be expected to evaluate long dependency chains as quickly as an in-memory spreadsheet calculation.

However, Nodlin is designed for distributed organisational workflows, where updates propagate asynchronously across many related entities and tools. In this environment the system performs efficiently, particularly as scale increases and invalidation events are deduplicated.

Developers should therefore think carefully about node granularity. Nodes should represent meaningful units of business state rather than excessively fine-grained computational steps.

Example Benchmark: Chart of Accounts Hierarchy

The following benchmark demonstrates Nodlin propagating updates through a financial hierarchy.

Each account node computes:

account_total = own_postings + sum(child_account_totals)

Transactions are posted randomly across leaf accounts and propagated through the hierarchy.

Test environment:

• Mac Mini (Apple M4)
• Nodlin runtime
• operations distributed through the NATS messaging platform

Test 1

Structure:

• 125 accounts
• hierarchy depth: 3

Workload:

• 100 transactions posted

Results:

• average execution time: 24.6 ms per operation

Test 2

Structure:

• 3,125 accounts
• hierarchy depth: 6

Workload:

• 20,000 transactions posted

Results:

• 56,812 node operations executed
• average execution time: 6.8 ms per operation

Interpretation

Performance improves at scale due to two key properties of the Nodlin execution model.

1. Event Deduplication

Events carry no payload and are therefore safely deduplicated.

If many upstream updates affect the same node, they collapse into a single recomputation.

Example:

many leaf updates
      ↓
root node receives many invalidations
      ↓
deduplication occurs
      ↓
root recomputes once

2. Hot Node Coalescing

Highly shared aggregation nodes (such as the root account in a hierarchy) become hot nodes.

Hot nodes introduce a small scheduling delay that allows multiple upstream updates to accumulate before recomputation occurs.

This behaviour reduces unnecessary recomputation and improves throughput under load.

Practical Guidance for Developers

Performance in Nodlin depends primarily on graph structure and node granularity.

Good design:

• nodes represent meaningful business entities
• dependency chains are stable
• recomputation produces a final answer immediately

Poor design:

• extremely fine-grained nodes
• long chains of purely computational nodes
• iterative convergence logic inside nodes

As a rule of thumb:

Nodes should represent derived business state, not individual arithmetic steps.

Summary

Nodlin trades some single-operation latency for scalability across large dependency graphs.

In practice:

• latency remains suitable for user-driven workflows
• throughput improves as graph scale increases
• invalidation deduplication reduces recomputation cost

This allows large organisational graphs to remain consistent without manual reconciliation.

6. Temporary Inconsistency Is Normal

During propagation the graph may be inconsistent.

Example:

• Leaf account updated ->
• Parent not yet recomputed
• Dashboard still old

Eventually:

• Leaf -> Parent -> Division -> Root

The system stabilises.

Nodlin guarantees consistency after propagation quiesces.

7. Cycles Are Allowed (But Must Stabilise)

Some real-world relationships are cyclic.

Example:

• parent Task state change results in event -> sub Task
• sub Task status and effort change results in event -> parent Task

These examples are typical in Nodlin where nodes represent detail in structured type (not just like a number in a spreadsheet).

These are acceptable if node logic stabilises.

If propagation repeatedly cycles through the same node, e.g., the same node appears many time in a single ’trace’ then:

• propagation is halted
• node is flagged (blocked), and
• manual resolution is required.

This prevents runaway propagation.

8. Developer Rule of Thumb

When writing node logic ask:

“If all neighbouring nodes suddenly recomputed, would my node immediately produce the correct answer?”

If yes, the design fits Nodlin.

If it requires multiple rounds of negotiation or oscillation, it is unsuitable.

9. What Nodes Should Do

Nodes should represent derived business state.

Examples:

Project progress = average(child task progress)

Account balance = own postings + child balances

Team workload = sum(task effort)

These stabilise quickly.

10. What Nodes Should NOT Do

Nodlin is not a simulation engine.

Avoid:

• iterative solvers
• oscillatory feedback loops
• physics-style convergence
• repeated threshold flipping between nodes

Bad example:

A sets value based on B
B sets value based on A

11. One Sentence to Remember

Nodlin is for reactive derivation of business state, not iterative simulation.