# @lssm-tech/lib.execution-lanes

Execution lanes orchestration contracts and runtime for ContractSpec.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `3.1.4`
- Package path: `packages/platform/agents/execution-lanes`
- Manifest path: `packages/platform/agents/execution-lanes/package.json`
- Manifest Git blob: `cc8a4fcc88cb7cba1260827d5c1fcd0252989909`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/lib.execution-lanes](https://lssm.co/docs/packages/lib.execution-lanes/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/lib.execution-lanes.txt)

## Package metadata

```json
{
  "layer": "platform",
  "physicalArea": "agents",
  "primaryArea": "agents-and-context",
  "classification": {
    "privateDeclared": null,
    "catalogFamily": "sharedLibs",
    "catalogKind": "library",
    "catalogStatus": "active",
    "adoptionMode": "adoptable",
    "stability": "stable"
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: not declared; publication is not verified.

Primary area: [Agents, execution and context](https://lssm.co/docs/areas/agents-and-context/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/platform/agents/execution-lanes/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/README.md",
  "blobSha": "dd6f2ea08a51d1ae1558df06f1556070fbc0498b",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# @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.


## Declared capabilities

### Lib Execution Lanes

Capability ID: `package.lssm.tech.lib.execution.lanes`

Execution lanes orchestration contracts and runtime for ContractSpec.

Use cases:

- Adopt execution lanes orchestration contracts and runtime for contractspec

Constraints:

```json
{
  "platforms": [
    "server"
  ],
  "runtimes": [
    "node"
  ],
  "avoidWhen": [
    "The @lssm-tech/lib.execution-lanes package constraints do not match the target runtime or platform."
  ],
  "requires": [
    "TypeScript"
  ]
}
```

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "contractspec",
    "execution",
    "lanes",
    "orchestration",
    "typescript",
    "lib"
  ],
  "pythonEquivalents": [],
  "alternatives": [],
  "relationships": [],
  "resolutionPriority": 50
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/lib.execution-lanes",
    "symbols": []
  },
  {
    "from": "@lssm-tech/lib.execution-lanes/defaults",
    "symbols": []
  },
  {
    "from": "@lssm-tech/lib.execution-lanes/interop",
    "symbols": []
  },
  {
    "from": "@lssm-tech/lib.execution-lanes/launch",
    "symbols": []
  },
  {
    "from": "@lssm-tech/lib.execution-lanes/quality",
    "symbols": [
      "QualityExecutionRegistry",
      "executeQualityPlan"
    ]
  },
  {
    "from": "@lssm-tech/lib.execution-lanes/types",
    "symbols": []
  }
]
```

## Catalogue metadata

```json
{
  "family": "sharedLibs",
  "kind": "library",
  "status": "active",
  "adoptionMode": "adoptable",
  "stability": "stable",
  "platforms": [
    "server"
  ],
  "runtimes": [
    "node"
  ],
  "entrypoints": [
    ".",
    "./defaults",
    "./interop",
    "./launch",
    "./quality",
    "./types"
  ],
  "examples": [],
  "replacements": []
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[
  {
    "capabilityId": "package.lssm.tech.lib.execution.lanes",
    "from": "@lssm-tech/lib.execution-lanes",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.lib.execution.lanes",
    "from": "@lssm-tech/lib.execution-lanes/defaults",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.lib.execution.lanes",
    "from": "@lssm-tech/lib.execution-lanes/interop",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.lib.execution.lanes",
    "from": "@lssm-tech/lib.execution-lanes/launch",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.lib.execution.lanes",
    "from": "@lssm-tech/lib.execution-lanes/quality",
    "symbols": [
      "QualityExecutionRegistry",
      "executeQualityPlan"
    ]
  },
  {
    "capabilityId": "package.lssm.tech.lib.execution.lanes",
    "from": "@lssm-tech/lib.execution-lanes/types",
    "symbols": []
  }
]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

- `@lssm-tech/lib.execution-lanes` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/src/index.ts); verified source file.

- `@lssm-tech/lib.execution-lanes/defaults` — subpath `./defaults`
  - `unconditional`: `./src/defaults/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/src/defaults/index.ts); verified source file.

- `@lssm-tech/lib.execution-lanes/interop` — subpath `./interop`
  - `unconditional`: `./src/interop/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/src/interop/index.ts); verified source file.

- `@lssm-tech/lib.execution-lanes/launch` — subpath `./launch`
  - `unconditional`: `./src/launch/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/src/launch/index.ts); verified source file.

- `@lssm-tech/lib.execution-lanes/quality` — subpath `./quality`
  - `unconditional`: `./src/quality/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/src/quality/index.ts); verified source file.

- `@lssm-tech/lib.execution-lanes/types` — subpath `./types`
  - `unconditional`: `./src/types/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/platform/agents/execution-lanes/src/types/index.ts); verified source file.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": "./dist/index.d.ts",
  "files": [
    "dist",
    "README.md"
  ],
  "publishExports": {
    ".": {
      "types": "./dist/index.d.ts",
      "browser": "./dist/browser/index.js",
      "bun": "./dist/index.js",
      "node": "./dist/node/index.js",
      "default": "./dist/index.js"
    },
    "./defaults": {
      "types": "./dist/defaults/index.d.ts",
      "browser": "./dist/browser/defaults/index.js",
      "bun": "./dist/defaults/index.js",
      "node": "./dist/node/defaults/index.js",
      "default": "./dist/defaults/index.js"
    },
    "./interop": {
      "types": "./dist/interop/index.d.ts",
      "browser": "./dist/browser/interop/index.js",
      "bun": "./dist/interop/index.js",
      "node": "./dist/node/interop/index.js",
      "default": "./dist/interop/index.js"
    },
    "./launch": {
      "types": "./dist/launch/index.d.ts",
      "bun": "./dist/launch/index.js",
      "node": "./dist/node/launch/index.js",
      "default": "./dist/launch/index.js"
    },
    "./quality": {
      "types": "./dist/quality/index.d.ts",
      "browser": "./dist/browser/quality/index.js",
      "bun": "./dist/quality/index.js",
      "node": "./dist/node/quality/index.js",
      "default": "./dist/quality/index.js"
    },
    "./types": {
      "types": "./dist/types/index.d.ts",
      "browser": "./dist/browser/types/index.js",
      "bun": "./dist/types/index.js",
      "node": "./dist/node/types/index.js",
      "default": "./dist/types/index.js"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.agent-protocol-spec](https://lssm.co/docs/packages/lib.agent-protocol-spec/): `workspace:^`
- [@lssm-tech/lib.assurance-spec](https://lssm.co/docs/packages/lib.assurance-spec/): `workspace:^`
- [@lssm-tech/lib.contracts-spec-core](https://lssm.co/docs/packages/lib.contracts-spec-core/): `workspace:^`
- [@lssm-tech/lib.crypto-utils](https://lssm.co/docs/packages/lib.crypto-utils/): `workspace:^`
- [@lssm-tech/lib.harness](https://lssm.co/docs/packages/lib.harness/): `workspace:^`
- [@lssm-tech/lib.orchestration-spec](https://lssm.co/docs/packages/lib.orchestration-spec/): `workspace:^`

### Peer dependencies

- [@lssm-tech/lib.ai-agent](https://lssm.co/docs/packages/lib.ai-agent/): `workspace:^`

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/lib.ai-agent](https://lssm.co/docs/packages/lib.ai-agent/): `workspace:*`
- [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{
  "@lssm-tech/lib.ai-agent": {
    "optional": true
  }
}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
  "publish:pkg:canary": "bun publish:pkg --tag canary",
  "build": "contractspec-bun-build build",
  "build:bundle": "contractspec-bun-build transpile",
  "build:types": "contractspec-bun-build types",
  "dev": "contractspec-bun-build dev",
  "clean": "rimraf dist .turbo",
  "lint": "bun lint:fix",
  "lint:fix": "node ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .",
  "lint:check": "node ../../../../scripts/biome.cjs check .",
  "test": "bun test",
  "prebuild": "contractspec-bun-build prebuild",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

- [Lib Execution Lanes documentation](https://www.npmjs.com/package/%40lssm-tech%2Flib.execution-lanes) — declared link; destination not verified.

```json
{
  "url": "https://www.npmjs.com/package/%40lssm-tech%2Flib.execution-lanes",
  "kind": "readme"
}
```

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/lib.execution-lanes.txt",
  "route": "/llms/lib.execution-lanes",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/lib.execution-lanes.txt",
  "blobSha": "dd6f2ea08a51d1ae1558df06f1556070fbc0498b",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```