lib.execution-lanes
Execution lanes orchestration contracts and runtime for ContractSpec.
@lssm-tech/lib.execution-lanesbun add @lssm-tech/lib.execution-lanesManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Website: https://contractspec.io
Typed execution-lane contracts, registries, runtimes, evidence gating, and backend adapter ports for ContractSpec.
Lane, plan, evidence and identifier declarations now forward to the existing pure @lssm-tech/lib.orchestration-spec/execution-lanes owner. Runtime behavior and supported execution-lanes exports remain here; consumers requiring only those declaration models can use the canonical orchestration entries.
What It Provides
- Lane contracts for
clarify,plan.consensus,complete.persistent, andteam.coordinated. - Typed handoff artifacts including clarification artifacts, plan packs, completion records, team snapshots, and lane runtime state.
- Generic collaboration primitives for work claims, leases, mailbox traffic, handoffs, and evidence attachments that compose with legacy
TeamRunSpec. - Additive coordinated-program V1 contracts for checkpointed multi-lane work, dirty-worktree preservation, frozen contract dependencies, exclusive path leases, integration handoffs, and exact-SHA integration receipts.
- Runtime primitives for consensus planning, persistent completion loops, coordinated team runs, lane selection, evidence gating, and in-memory persistence.
./qualityexposesQualityExecutionRegistryandexecuteQualityPlan. Canonical quality models and supplied-receipt validation come from@lssm-tech/lib.assurance-spec/quality; this runtime no longer imports the ContractSpec compatibility facade. Execution capabilities bind typedexecutionRefand command digests from an immutableQualityPlanV1; dependency-ready checks run in parallel and emit one exactQualityRunReceiptV1. The executor reports failures but never decides which proof is required.- Quality profiles may bind an explicit
QualityEnvironmentV1. The derived plan retains prerequisite checks even when they belong to another gate. Before executing an environment-bound check, the runner verifies the exact environment digest, fixture/network boundary, and every readiness dependency. A mismatch, missing dependency, exception or deadline produces an error receipt without invoking the test. Hosts implement the actual boundary and dependency probes; the generic executor does not provision infrastructure. - An optional
AgentRuntimeSessionPortbridge that links a lane run to portable agent sessions, turns, steps, checkpoints, pending approvals, evidence, and cancellation without replacing the canonical agent runtime contract. - Backend-neutral adapter ports for in-process, subagent, tmux, queue, and workflow-engine execution.
- Coordinated teams enforce the Protocol V1 defaults of eight participants and 32 acyclic task nodes. Claims require an eligible declared worker, and task completion requires an active matching lease plus attached evidence. Evidence is resolved against the lane store: attaching a task or run bundle id that is not recorded for the run is refused, every attached id must still resolve when the task completes, at least one attached bundle must be fresh, and a task that declares
requiredEvidencecompletes only when fresh, same-run bundles cover every declared class. Finalization and readiness refuse run or completed-task evidence ids missing from the store. Every new run must enable the verification lane, with or withoutwritePaths; membership changes on an already persisted run skip that creation-only rule. When the verification lane is required, finalization needs a verifier approval whosedecidedByis not a task participant: no current or reclaimed claimant (each claim is kept inclaimHistory), and no principal that claimed, attached work evidence to, or completed (completedBy) a task.evaluateLaneReadinessapplies the same independence rule to every run with team state, so it never reportsreadyfor a run finalization would reject: a lane that names its policy by key resolves it throughpolicyRegistry(also aLaneRuntimeOptionsfield) and otherwise uses the defaultteam.coordinatedpolicy, and unresolved evidence ids are listed asunresolved_evidence:<id>. - Team workers receive bounded, least-privileged delegation (
TeamWorkerDelegationV1,getWorkerDelegation): a principal derived from the lead, delegation depth lead + 1 (at most two) with no further delegation, a context of the run objective and only the tasks the worker may claim (tasks hinted for its role, then unhinted tasks), its role's tools within the lead's tools, only the grants its role requires, a wall-clock bound for every lease, inherited approval requirements, completion criteria, evidence obligations and a typed-help channel. No mailbox, handoff or parent history and no credentials are projected. A host passescreateTeamRun(store, adapter, { delegation })with aTeamDelegationAuthorityV1(or a per-run resolver, called again for every operation so revocations apply to active work); creation, start and membership changes fail closed when a worker would need a tool, grant or depth the lead lacks. A run created under an authority stays bound: a resolver that later returns nothing, or a reopened runtime with no source, fails closed. Only runs that were never bound retain the legacy authority-free behavior. Revoke access by returning an authority with fewer tools or grants. Under that authority, claims, lease renewals, task-evidence attachments, completions, heartbeats and help requests must be made by the worker's derived principal. Without one, workers derive from a run-local lead, receive no grant, and actor ids stay informational. Every lease is positive and bounded by the worker's wall clock (maxWorkerWallClockSeconds, one hour by default). Run and worker ids are percent-encoded (%and/) inside derived principals. - Workers ask for help with the canonical
AgentHelpRequestV1(requestHelp), routed to the lead mailbox and bound to the worker's derived principal and task; a retried identical request returns the existing record.respondToHelprecords the canonicalAgentHelpResponseV1under the agent-protocol help rules: the selected option must be one of the request's safe options, the response must be created between the request's creation and expiry, and no worker of the run (worker id or derived principal) may answer. Under a delegation authority the responder is the lead the request was routed to, or a responder the injectedhelpResponseAuthority(TeamHelpResponseAuthorityPortV1, called outside the team lock with the response digest and required evidence) authorizes.listHelpreads the durableteam_help_requestrecords. - Worker lifecycle calls (start, membership changes, pause, resume, nudge and shutdown) use a bounded two-phase work-order/outbox protocol:
team_work_orderrecords are written inside the team transaction, the backend runs with no team lock held (bounded byworkOrderTimeoutMs, with the order id and deadline passed to the backend), and the outcome is settled in a second transaction. Every order of a call is checked before any is written, so a refused call leaves no order behind. A worker has at most one open order; orders that outlive their deadline settle asindeterminate(reconcileWorkOrderssettles expired orders; it does not query the backend), and a failed start marks the workerfailedand throwsTeamWorkOrderFailureError. Failures persist only the error class name (and a shortcode), never the backend message. A retry gets a new order id, so backends deduplicate by run and worker. A worker the backend stopped or removed releases the tasks it still leased. - Terminal snapshots preserve failure truth: failed, blocked, or cancelled task graphs become failed, blocked, or aborted runs instead of optimistic completion. The optional store-owned team transaction boundary serializes claims, evidence, mailbox, recovery, and finalization across replicas; backends without it retain the per-store compatibility mutex. Terminal replay returns the one persisted snapshot rather than manufacturing another.
Public Entry Points
.resolves through./src/index.ts./typesresolves through./src/types/index.ts./defaultsresolves through./src/defaults/index.ts./interopresolves through./src/interop/index.ts./launchresolves through./src/launch/index.ts./qualityresolves through./src/quality/index.ts
Notes
- The package stays runtime- and backend-neutral; storage-backed operator persistence belongs in integration and app layers.
- Evidence normalization and replay references align with
@lssm-tech/lib.harness; this package does not introduce a second proof model. - Role semantics live in typed role profiles, not prompt prose.
./launchowns lane launch policy:buildExecutionPlanPack(deliberate mode raises scope to high-risk and requires verifier, architect and human approvals),buildCompletionLoopSpecFromPlanPack(approvals drive the signoff flags and delegate roles),buildTeamRunSpecFromPlanPack(default workers from plan step role hints),createLaneRunStateandrequiredSignoffRoles.createDefaultRoleRegistryandcreateDefaultLaneRegistrybuild the default registries.- Canonical artifact and evidence identifiers use spec-style snake_case names; readers normalize older hyphenated aliases for persisted compatibility.
- Command semantics for
/clarify,/plan,/plan --consensus,/complete, and/teamlive in the typed./interopsurface rather than in prompt prose alone. CoordinatedProgramSpecV1embeds the existingTeamRunSpecand references existing evidence bundles. Its validators fail closed for overlapping exclusive leases, unresolved dependency/freeze refs, stale checkpoints or evidence, incomplete dirty-path preservation metadata, and integration proof that is not bound to the exact integration SHA.serializeCoordinatedProgramSpecV1andcoordinatedProgramDigestV1provide a deterministic review/replay representation without introducing another orchestration or evidence runtime.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
6 declarations
@lssm-tech/lib.agent-protocol-specworkspace:^
Read the package manual ↗@lssm-tech/lib.crypto-utilsworkspace:^
Read the package manual ↗@lssm-tech/lib.harnessworkspace:^
Read the package manual ↗@lssm-tech/lib.assurance-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.orchestration-specworkspace:^
Read the package manual ↗
Declared capabilities
Execution lanes orchestration contracts and runtime for ContractSpec.
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit