@lssm-tech/lib.lssm-os-runtime
Provider-neutral deterministic planning and execution kernel for LSSM OS.
The runtime compiles desired and observed revisions into canonical plans, binds them to SHA-256 digests, verifies exact non-stale Connect authorization, and executes idempotent steps under fenced leases. It also provides drift, reconciliation, rollback, decommission, recovery, receipt, and replay primitives.
Every compiled plan carries an exact/range/stale/unavailable minor-unit cost record. Unknown or stale costs add a mandatory economic review requirement. When a coordinated execution program is supplied, exact integration-SHA and evidence-bundle references are copied into the plan digest.
It does not call provider SDKs, own credentials, or issue authorization. Concrete providers and durable state backends implement injected ports.
Public entrypoints
@lssm-tech/lib.lssm-os-runtime@lssm-tech/lib.lssm-os-runtime/planning@lssm-tech/lib.lssm-os-runtime/execution@lssm-tech/lib.lssm-os-runtime/state@lssm-tech/lib.lssm-os-runtime/authorization@lssm-tech/lib.lssm-os-runtime/ports@lssm-tech/lib.lssm-os-runtime/runtime-node@lssm-tech/lib.lssm-os-runtime/runtime-node/scalability@lssm-tech/lib.lssm-os-runtime/runtime-node/v3-execution-service
Runtime Node V3 execution service
createRuntimeNodeV3ExecutionServiceV1 is the frozen exactly-once V3 execution composition over injected ports (dispatch authority, operation state, provider receipts, provider router, clock): an exact provider-receipt replay finishes without a new effect; otherwise authorizeDispatch gates one
executeProviderStepV2 call, the receipt is appended and verified, and the operation completes with a digest-bound receipt under version, attempt, claim and fencing CAS. Terminal replays return the existing receipt; any ambiguity moves the operation to indeterminate custody with a deterministic recovery ref. Result codes keep their existing agent_host.* valeurs.
Runtime Node V2 additive trust surface
The runtime-node subpath adds signed, node-bound and tenant-bound work orders without changing any V1 planning or execution API. It exposes canonical Zod schemas and digest helpers for node descriptors, registrations, heartbeats, attestations, qualification bindings, provider bindings, claims, provider receipts, and completions.
It also exports the provider-neutral LssmOsOperationClientV1 port and its scope, request, result, and error-surface types. UI libraries depend on this lower-layer port; HTTP clients implement it in integration packages.
Execution is fail-closed:
- Connect remains the only signed work-order issuer and verifier.
- Eligibility requires exact current registration, heartbeat, attestation, qualification, source, environment, provider, adapter, profile, and capability digests.
- The deterministic eligibility evaluator produces an unsigned proposal only. Claim persistence requires a signed, current authority decision through a mandatory injected
RuntimeNodeEligibilityVerifierPort.
- Provider routing is exact and deterministic; it never falls back to a nearby adapter or profile.
- Claims are atomic, leased, fenced, replay-bound, and safe across process restart when the injected state implementation is durable.
- Receipt V2 binds tenant, workspace, environment, node, provider, order, claim, lease, fence, attempt, plan, authorization, and effect identities.
- Durable receipt append requires a mandatory external
ProviderStepReceiptVerifierPort. Verification happens before mutation, followed by a fresh trusted-clock sample and exact authority-state recheck. Synchronous failures, invalid return values, hostile thenables, timeouts, and late settlements fail closed without mutating receipt state.
- Exact replay is offline only after the complete durable receipt/index tuple, stored order, and preserved claim snapshot revalidate. Takeover claims may continue a prerequisite DAG from those trusted historical receipts, while a stale claimant cannot append.
- Completion binds the exact ordered durable receipt digests and their deterministic unique evidence projection. Success requires every ordered step to succeed; other terminal statuses require exact partial evidence. Provider receipt time is nondecreasing across the step DAG, and completion cannot predate any durable receipt.
- Public wire schemas reject unknown fields, non-canonical timestamps, credential-shaped material, and raw secrets.
The included in-memory work-order and receipt ports are reference adapters for local use and tests. Their restart-sharing state is a frozen opaque token; durable maps and authority snapshots are adapter-private and cannot be caller-populated. The ports require eligibility/receipt verifiers and a trusted runtime clock; claim, receipt, renewal, and completion authority time never comes from caller or provider payloads. Production compositions must inject transactional durable implementations of RuntimeWorkOrderPort and
RuntimeWorkOrderReceiptPort.
The runtime-node entrypoint also exports a backend-neutral SQL state machine for those ports. It owns canonical serialization, hydration, verifier/clock TOCTOU checks, claim and receipt CAS behavior, and completion validation; concrete SQLite, PGlite, and Postgres adapters retain transaction and migration authority. SQL rows are never trusted merely because their digests can be recomputed.
The additive RuntimeNodeRegistryPortV2 scopes descriptor reads to the full tenant/workspace/environment/node tuple. Its SQL implementation stores registration, heartbeat, attestation, and provider-qualification histories as immutable evidence. Writes serialize through a per-scope lock, validate every canonical digest and cross-record binding, reject sequence or timestamp rewinds, and make evidence from an older registration unavailable until the new registration is freshly attested and qualified. V1 remains available for source compatibility but must not bypass tenant isolation in a multi-tenant durable adapter.
Every published entrypoint resolves only to files shipped under dist for Node, Bun, browser, and declaration consumers. Maintainers run
bun run pack:verify before publishing; it installs the real npm tarball and its strict dependency closure in a clean temporary consumer, requires a clean
npm ls --all, imports every entrypoint, compiles a clean consumer against every public declaration target, replays the canonical SHA-256 vector, and rejects workspace links, source exports, test artifacts, or private state/resolver declarations. The optional coordinated-program input is a minimal structural evidence view, so a complete
CoordinatedProgramSpecV1 remains assignable without pulling the agent runtime and evaluation peer graph into production installs.
Runtime Node V3 qualification authority
V3 is additive to V2 and introduces strict purpose: "standard" and
purpose: "emergency_cleanup" work orders for isolated live canaries. Standard orders bind one exact preallocated claim, lease, fence, attempt, provider binding, singleton step, plan, and Connect evidence tuple. Cleanup orders are decommission-only and bind the immutable provider resource identity, ownership, generation, creation observation, and separate cleanup reservation.
QualificationAuthorityStatePort is the single transactional seam for V3 reservation, permit, settlement, and custody transitions. Amounts are integer EUR micros with fixed daily caps of 800,000 normal, 200,000 cleanup, and 1,000,000 total. CleanupObservationAttestationV1 expires within 30 seconds; reservation digests identify immutable scope, operation, day, kind, amount, and pricing. Mutable held, dispatched, provisional, settled, evidence, and state fields evolve under that stable identity and are never part of the digest. observer and mutator trust keys must differ and its nonce is single-use.
LssmOsOperationStatePort creates durable operation records before fallible authority or queue I/O; indeterminate remains recoverable, never an error wire variant. The included in-memory authority is reference-only.
projectLssmOsOperationSurfacesV1 is the canonical F3 read projection for REST, CLI, MCP, SDK, and UI shells. Every nonterminal durable operation maps to HTTP 202 and CLI exit 5, carries the same request and receipt digests, and includes a scope-qualified operation URL. Terminal results and closed errors retain one canonical projection or error digest across every surface.
readLssmOsOperationSurfacesV1 bounds and validates the injected durable read, rejects substituted scope or operation identity, and contains missing, malformed, timed-out, and failed dependencies without inventing completion. Application shells remain responsible for authentication and transport; they must consume this projection rather than redefine status or error mappings. Transport clients must pass untrusted success and error bodies through
parseLssmOsOperationSurfaceV1 or
parseLssmOsOperationSurfaceErrorV1. These parsers revalidate the closed shape, canonical digest, terminal posture, retry posture, and exact scope-qualified operation URL before recreating the five surface wrappers.
QualificationAuthorityOrderReadPortV1 is the deliberately smaller runtime surface for loading an already-issued standard order by its full scope, operation, ID, and digest. Its additive V2 surface also dereferences the exact emergency cleanup order so restart/recovery does not depend on process memory. Agent Host may receive this reader, but never the issuer or mutable qualification authority.
Runtime scalability ports
The additive runtime-node/scalability subpath freezes nine provider-neutral ports for distributed cache, coordination, durable queues, event streams, ingress, topology state, capacity observation, scale planning, and one-step topology execution. Every stateful call repeats the exact topology generation, component/profile, and adapter/server/client digest binding. Queue claims and coordination fences are transport evidence only and can never authorize a Runtime Node effect.
Topology transition state begins only through
recordObservedTransition; later lifecycle movement uses exact-state CAS. This makes transition initialization an explicit durable operation instead of an adapter-specific method hidden outside the frozen port.
verifyAuthorizedTopologyIntentV1 rechecks the exact V3 operation tuple, signed work order, trusted deadline, and Connect decision before a controller may persist topology authorization evidence. It deliberately does not consume the dispatch fence; executeAuthorizedTopologyStepV1 rechecks the same authority and remains the only boundary that atomically consumes dispatch and invokes one observable effect.
TopologyExecutorPortV2 adds the exact prior transition receipt to that boundary, while retaining TopologyExecutorPortV1 for compatibility. The provided createProviderTopologyExecutorV1 implementation projects the signed V3 order into the existing exact provider router, accepts only the plan step's component, sequence, prerequisites, and compatible lifecycle action, and returns one digest-bound topology receipt that appends exactly that step. Provider failures and uncertain calls remain indeterminate provider evidence; they never become fabricated topology completion.
All adapters return a closed ok | already_applied | conflict | unavailable | indeterminate result. The operation-specific conformance wrappers own and freeze dependency outputs, verify canonical contract digests and exact scope bindings, contain synchronous errors and hostile thenables, and enforce a bounded deadline without returning upstream error text. Topology execution also reloads the durable running operation and verifies its existing Connect authority before and after the external verifier call. SQL remains authoritative; cache misses and transport uncertainty stay recoverable through durable state rather than being promoted to authority.
QueueClaimEnvelopeLookupPortV1 is the additive fenced read boundary for a consumer that already holds a current Queue Claim. It returns the immutable envelope only when the stored claim digest, queue fence, visibility lease, scope, topology, and capability binding still match. The envelope and queue claim remain transport context; neither authorizes an effect.
Authority flow
- Stamp and validate desired and observed state.
- Compile a deterministic plan and expose its exact digest for review.
- Obtain a decision from ContractSpec Connect outside this package.
- Apply only when decision, scope, revisions, expiry, and digest match.
- Persist append-only receipts and replay them to verify the outcome.
The ports surface owns ProviderDiscoveryPortV1, ProviderDiscoveryScopeV1, ProviderResourceSnapshotV1, and ProviderDiscoveryPageV1. These extract the existing provider-neutral discovery shape; typed provider adapters specialize family, scope and ownership without granting effect authority.
The additive QualificationAuthorityOrderReadPortV3 can discover the single issued standard order for an exact tenant/workspace/environment/operation tuple. This allows server recovery after issuance without accepting an authority digest from a member request. Absence, ambiguity and malformed or cross-scope payloads return no order. A recovered order still requires current Connect verification and dispatch authority before execution.
Connect-owned V3 lifecycle drafts
The runtime-node surface exports RuntimeV3LifecycleDraftV1 and
RuntimeV3IssuedLifecycleV1. A draft contains unsigned standard and cleanup orders, canonical reservations and the accepted operation. Connect supplies issuer, signature, authorization and issuance-time fields, including the standard step's bound authorization/effect digest. The provider-neutral Connect library implements issuance and verification; Runtime state remains the owner of budget, issued-order, claim and completion transactions. Cleanup custody has no standard-order expiry.
The additive ./planning-handoff-digest subpath supplies stable serialization, raw SHA-256 planning-payload digests and derived IDs for the metadata-only handoff protocol. Builder planning compatibility exports forward to these exact functions; these helpers perform no execution or authority resolution.
Generic control-plane services
The control-plane entry owns existing generic scheduling, workers, state ports, topology controllers and pure handoff acceptance. Its narrow subpaths preserve the original module surfaces. Builder candidate and governed patch orchestration belong to the Builder ControlPlane module; this runtime does not depend on that module or Builder/Connect implementations.
The canonical subpath forwards its existing synchronous JSON digest helpers to @lssm-tech/lib.crypto-utils/canonical, preserving runtime imports and digest meaning while allowing domain contracts to use the pure foundation implementation.
The ./catalog-locator-node subpath owns validateLssmCanonicalLocatorInWorkspace, which applies the spec's lexical locator gate and then confirms through realpath
that a catalog locator stays inside the supplied workspace root. Its browser condition returns locator.node_only. It moved here unchanged from
@lssm-tech/lib.lssm-os-spec/context/catalog-locator-node so the spec stays free of I/O.
Control-plane skill verification
The control-plane/skills entry and its signer and verifier leaves own the existing supplied-key WebCrypto signing and manifest trust verification. Canonicalization, publisher trust, version bounds, artifact digests and expiry checks are unchanged. Keys are caller supplied; verification does not issue an installation grant. Pure schemas and validators remain in lssm-os-spec.
Hook Authority
The four control-plane/hook-authority leaves (base, -digest, -validation and
-reference-adapter) own the original V1 protocol and supplied-port reference adapter. Legacy contracts-spec leaves forward these same objects, including the opaque in-process restart token. No registration or verification grants authority.
Build preparation bundles the four runtime entries, strips private Hook Authority JavaScript and limits declarations to the public closure plus records and opaque restart-token support. Mutable maps and test helpers cannot ship. Historical private development-only helper paths remain source-only and are omitted from publishConfig. Packed consumers must verify both canonical and facade identity.
