Skip to content
ContractSpec
Start here

Package manual · domains

·Company, work and service operations

lib.work-runtime

Pure Work Graph reducers, event processing, recurrence, idempotency, and sync conflict decisions.

domainslibraryv3.0.4experimentalservernode
@lssm-tech/lib.work-runtime
bun add @lssm-tech/lib.work-runtime
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Pure, provider-neutral Work Graph runtime behavior.

It reduces immutable Work events, enforces aggregate revision order, expands recurrence, applies native/remote/merge field authority, detects three-way scalar conflicts, and exposes storage/projection ports. Concrete PostgreSQL, queue, search, realtime, connector, and object-store adapters belong in integrations. Unknown event types, revision gaps, open merge conflicts, and aggregate identity or scope drift are rejected fail-closed.

./outbox-dispatch supplies the provider-neutral worker boundary for projection, authorized realtime, and OPA reoptimization delivery. It requires destination-specific leased records and owner-fenced acknowledgements from the durable adapter; unknown destinations or missing consumers fail closed.

Durable command ports expose optional lookupCommitted so services can resolve an authorized retry before object-existence or revision validation. The PostgreSQL adapter fences the request identity and returns its persisted receipt, or an idempotency conflict for changed input. Managed hosts keep lookup, projection reads and commit in one outer authority transaction, so concurrent identical creates return one committed event. Other adapters must implement this receipt lookup to qualify equivalent retry behavior.

Work outbox lease contract v2 requires deliveryAttempt on acknowledge/release, copied from the claimed record's deliveryAttempts. The dispatcher supplies it automatically. Matching a worker name and future expiry is insufficient: settlement also checks the exact persisted attempt. Old or missing attempt values fail closed. Update custom callers before upgrading; no database migration or stored-record reset is required.

./task-status holds the pure task status transition used by managed hosts: planWorkTaskStatusMutation builds the work.object.transition@2.0.0 envelope and request fingerprint from an injected digest, and transitionWorkTaskStatus applies the change to the current task at the displayed revision (category change clears the custom status id, completion uses server time and keeps an earlier completion, reopening clears it). Both fail closed with WorkTaskStatusConflict. Hosts keep authority, the store and the transaction.

Relationships

THIS PACKAGElib.work-runtime8 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

1 declarations

Declared capabilities

Lib Work Runtime

Pure Work Graph reducers, event processing, recurrence, idempotency, and sync conflict decisions.

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • devcontractspec-bun-build dev
  • cleanrimraf dist .turbo
  • lintbun lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit