lib.execution-lanes

@lssm-tech/lib.execution-lanes

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, and team.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.
• ./quality exposes QualityExecutionRegistry and executeQualityPlan. 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 typed executionRef and command digests from an immutable QualityPlanV1; dependency-ready checks run in parallel and emit one exact QualityRunReceiptV1. 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 AgentRuntimeSessionPort bridge 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 requiredEvidence completes 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 without writePaths; membership changes on an already persisted run skip that creation-only rule. When the verification lane is required, finalization needs a verifier approval whose decidedBy is not a task participant: no current or reclaimed claimant (each claim is kept in claimHistory), and no principal that claimed, attached work evidence to, or completed (completedBy) a task. evaluateLaneReadiness applies the same independence rule to every run with team state, so it never reports ready for a run finalization would reject: a lane that names its policy by key resolves it through policyRegistry (also a LaneRuntimeOptions field) and otherwise uses the default team.coordinated policy, and unresolved evidence ids are listed as unresolved_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 passes createTeamRun(store, adapter, { delegation }) with a TeamDelegationAuthorityV1 (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 fails closed, so 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. respondToHelp records the canonical AgentHelpResponseV1 under 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 injected helpResponseAuthority (TeamHelpResponseAuthorityPortV1, called outside the team lock with the response digest and required evidence) authorizes. listHelp reads the durable team_help_request records.
• Worker lifecycle calls (start, membership changes, pause, resume, nudge and shutdown) use a bounded two-phase work-order/outbox protocol: team_work_order records are written inside the team transaction, the backend runs with no team lock held (bounded by workOrderTimeoutMs, 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 as indeterminate (reconcileWorkOrders settles expired orders; it does not query the backend), and a failed start marks the worker failed and throws TeamWorkOrderFailureError. Failures persist only the error class name (and a short code), 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
• ./types resolves through ./src/types/index.ts
• ./defaults resolves through ./src/defaults/index.ts
• ./interop resolves through ./src/interop/index.ts
• ./launch resolves through ./src/launch/index.ts
• ./quality resolves 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.
• ./launch owns 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), createLaneRunState and requiredSignoffRoles. createDefaultRoleRegistry and createDefaultLaneRegistry build 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 /team live in the typed ./interop surface rather than in prompt prose alone.
• CoordinatedProgramSpecV1 embeds the existing TeamRunSpec and 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.
• serializeCoordinatedProgramSpecV1 and coordinatedProgramDigestV1 provide a deterministic review/replay representation without introducing another orchestration or evidence runtime.