Skip to content
ContractSpec
Start here

lib.agent-runtime-conformance

Cross-runtime lifecycle conformance suite for ContractSpec agent runtime adapters

toolslibraryv2.0.4experimentalservernode
@lssm-tech/lib.agent-runtime-conformance
bun add @lssm-tech/lib.agent-runtime-conformance
Package source ↗Manifest ↗

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

Package guide

Cross-runtime lifecycle conformance suite for ContractSpec agent runtime adapters. Makes "portable across runtimes" falsifiable instead of asserted: any adapter that claims compatibility must pass this suite.

Usage

ts
import { runAgentRuntimeConformanceSuite } from '@lssm-tech/lib.agent-runtime-conformance';
import { createSqliteWorkflowDevkitTarget } from '@lssm-tech/lib.agent-runtime-conformance/fixtures';

const report = await runAgentRuntimeConformanceSuite(
  createSqliteWorkflowDevkitTarget({ file: './agent.db' })
);

console.log(report.summary.single_adapter_lifecycle_conformance_rate); // 16/19

The 19 cases (spec 04)

Cases 1-15 plus the mandatory case 5b (effect-replay safety) are testable for every durable target. Cases 16-17 remain NOT_APPLICABLE_THIS_RELEASE; case 18 becomes mandatory when an integration-local two-adapter target supplies runtime-probed portable evidence.

  • 1-3 create session, stream lifecycle events, invoke an operation-backed tool
  • 4 checkpoint round-trip through AgentCheckpointPort
  • 5 survive forced process death (real SIGKILL child; durable backing only)
  • 5b effect-replay safety on resume — the recorded result is replayed via the (nonce, stepInstanceId) key so an approval-gated sendMessage is never double-sent. Its inverse sub-case (5b-inverse) proves two distinct approval-authorized identical-input sends both fire (nonce-scoped, not input-scoped).
  • 6 resume from durable recovery
  • 7-8 suspend for human input / approval
  • 9-12 reject missing / wrong-input / replayed approval; resume with valid approval
  • 13 cancel (side effect must not fire once cancelled)
  • 14-15 emit artifacts and evidence refs
  • 16-17 execution receipt / outcome linkage — NOT_APPLICABLE_THIS_RELEASE
  • 18 cross-adapter portability — compares runtime-probed lifecycle, approval, effect replay, artifact/evidence, replay, and explicitly contracted loss diagnostics

Metric

single_adapter_lifecycle_conformance_rate = passing / 19. Target this release is 16/19 ≈ 0.84 for the Phase-1 Workflow DevKit gate. Integration-local EVE and Workflow DevKit targets additionally run case 18, producing 17/19 with cases 16-17 explicitly not applicable.

Targets

  • createInMemoryWorkflowDevkitTarget() — baseline; cannot survive process death, so cases 5/5b/6 report NOT_APPLICABLE.
  • createSqliteWorkflowDevkitTarget({ file }) — durable; the canonical gate.

Vendor-specific targets remain in their integration packages. Case 18 uses runPortableAdapterProbe() and fails on any unclassified field or declared-loss difference; integrations must supply an exact expected-loss contract.

Relationships

THIS PACKAGElib.agent-runtime-conformance20 import paths

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

6 declarations

Declared capabilities

Lib Agent Runtime Conformance

Cross-runtime lifecycle conformance suite for ContractSpec agent runtime adapters

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 --unsafe --only=nursery/useSortedClasses . && node ../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit