@causl/sync

Async resources and conflict registry on top of @causl/causl-wasm-ts. The package wires two of the orthogonal regions in Causl's composite lifecycle statechart: a per-resource ResourceFleet sub-statechart whose states are Idle | Loading | Loaded | Stale | Errored, and a per-conflict ConflictRegistry sub-statechart whose states are Open | Resolved | Ignored | Superseded. Conflicts are not a node kind; they are a derived view of the engine's own lifecycle.

Install

pnpm add @causl/sync @causl/causl-wasm-ts
Copy

Resource

import { createCausl } from '@causl/causl-wasm-ts'
import { resource } from '@causl/sync'

const graph = createCausl()
const items = resource<Item[]>(graph, 'items', {
  loader: async () => fetch('/api/items').then((r) => r.json()),
})

const result = await items.fetch()
const state = graph.read(items.node)
// state.state === 'idle' | 'loading' | 'loaded' | 'stale' | 'errored'
Copy

ResourceState<T> is a SPEC §9 discriminated union (idle, loading, loaded, stale, errored) tagged on state. Reading .value requires a tag check first, so the "reading a not-yet-loaded resource value" race is caught by tsc rather than left to runtime: every "X may or may not have Y" optional field is a state-machine-in-disguise we surface as a tag.

Staleness guard

The stale-async race: a fetch returns after its dependency changed; is real and the engine cannot avoid it. What the engine can do is guarantee a defined response: when another commit advances GraphTime between fetch() start and loader resolve, the resource transitions Loading → Stale rather than Loading → Loaded. The detection compares the originating GraphTime of the fetch to the current GraphTime at resolution; downstream consumers narrow on the tag before reading .value.

Opt out per-resource for last-writer-wins:

resource(graph, 'items', { loader, stalenessGuard: false })
Copy

Conflict registry

import { createConflictRegistry, singleConflictWhen } from '@causl/sync'

const conflicts = createConflictRegistry<Item[]>(graph, {
  id: 'conflicts',
  compute: singleConflictWhen(
    items.node,
    (s) => s.state === 'errored',
    () => ({ id: 'items-errored', target: items.key }),
  ),
})

conflicts.read(graph)
// [{ kind: 'open', id: 'items-errored', target: 'items', value, raisedAt }]

conflicts.resolve(graph, 'items-errored', { choice: 'use-cache' })
conflicts.read(graph)
// [{ kind: 'resolved', resolution: { choice: 'use-cache' }, resolvedAt, ... }]

conflicts.ignore(graph, 'items-errored')      // Open → Ignored
conflicts.supersede(graph, oldId, newId)      // Open → Superseded
Copy

Narrowing on kind

Conflict<T> is the SPEC §9 discriminated union landed in #354: the discriminator is kind, never status. Each variant carries exactly the fields the ConflictRegistry sub-statechart guarantees in that state, so the resolution, ignoredAt, and supersededBy slots are not optionals on a single shape but per-variant fields the type system proves are reachable:

for (const c of conflicts.read(graph)) {
  switch (c.kind) {
    case 'open':
      ui.show(c.target, c.value)
      break
    case 'resolved':
      ui.audit(c.id, c.resolution, c.resolvedAt)
      break
    case 'ignored':
      ui.dim(c.id, c.ignoredAt)
      break
    case 'superseded':
      ui.link(c.id, c.supersededBy, c.supersededAt)
      break
  }
}
Copy

The shape mirrors docs/lifecycle.md §1's ConflictRegistry chart: three legal transitions out of Open (resolve, ignore, supersede); the other three states are terminal. A mutator targeting a non-open conflict throws ForbiddenConflictTransitionError: no silent no-op, because shipping enum tags whose transitions aren't in the chart is the §17.7 anti-pattern this package was written against.

The target field on ConflictBase<T> is a NodeId identifying the node the conflict relates to; the application's domain payload lives on the per-conflict value: T.

The registry is not a node kind: it is a derived view over the engine's own lifecycle. The runtime universe contains only Inputs and Deriveds; "conflict" is a role, not a permanent kind. Resolutions are stored as a single Input<ReadonlyMap<...>> updated by the registry's mutator methods, and the public Conflict[] stream is a Derived that overlays the resolution map onto an application-supplied open-set compute.

Property tests

Property-based tests are this package's race-detection layer. The suite under test/properties/ covers the SPEC.async §15.1 / §15.2 predicates as runtime shapes: the chart invariants the type system can't ask about. Each property runs at the 1000-trial floor SPEC.md §15.2 names, routed through the tieredPropertyTrials seam so the nightly MODEL_CHECK_TIER=2 bump to 10,000 trials is structural (PR #1097 / #1073 shipped the tier-budget system; the conformance meta-test rejects raw { numRuns: N } literals so the floor can't silently slip).

The currently-shipped properties:

Failing inputs are shrunk and committed as regression cases; seeds are deterministic so a CI failure is reproducible.

Bundle budget (SPEC.async §14.2)

@causl/sync ships with per-primitive sub-imports so adopters who only need the resource primitive (or only the conflict registry) pay only for what they import. Three CI-gated size-limit ceilings in the root package.json:

Resource-only consumers:

import { resource } from '@causl/sync/resource'
Copy

Conflict-only consumers:

import { createConflictRegistry } from '@causl/sync/conflict'
Copy

The full barrel @causl/sync re-exports both surfaces. A PR that crosses one of the ceilings fails the size: bundle-size gate and must include the §14.2 written team consensus or the size-limit bump is rejected. The §14.2 narrative pins the trade-off: a smaller bundle buys a smaller install footprint; the ceiling rules out unilateral growth.