Runner Traceability and Implementation Record

August 23, 2026 · View on GitHub

1. Status and ownership

FieldValue
StatusNON_NORMATIVE_SUPPORTING_RECORD
Semantic authorityRunner Module Detailed Design, effective only with its parent Execution System candidate
System placementRunner is Execution module M02; it is not a System, subsystem, or implementation behind another M02 module
CompanionChinese non-normative companion
ProvenanceRepository history; this record makes no claim against an unresolvable external commit

Execution owns the Core boundary and the meaning of M01–M03. Runner owns M02 behavior and its private submodules. This record owns no behavior: it only indexes design IDs, implementation selections, evidence state, and open work.

The current architecture has one Runner. There is no Runner-selection abstraction. The historical TypeScript name ExecutionRuntimeAdapter denotes the current Core-to-Runner seam only. If multiple Runner implementations become necessary, M02 may be promoted into a Runner abstraction and each concrete implementation must receive a distinct name.

2. Current implementation selection

These are replaceable implementation selections, not stable architecture identities or conformance claims.

ConcernCurrent selection
Workflow HostLangGraph 1.4.12, @langchain/core 1.2.9
Checkpoint storage@langchain/langgraph-checkpoint-sqlite 1.0.4, better-sqlite3 12.11.1
Managed Agent ProviderDeepSeek Harness 0.1.1-rc.2
ValidationZod 4.2.0
Workspace/publicationGit 2.52.0

3. ID namespace and ownership

ID familyMeaning
runner.driver.001..010design drivers
runner.scenario.01..12scenarios
runner.flow.001..010end-to-end flows and their step IDs
runner.view.001..011bounded data views
runner.interface.001..005private capability interfaces
runner.acceptance.001..014acceptance register
runner.decision.001..015decision register
runner.open-work.003.1..4, .006..013remaining evidence and implementation work
runner.submodule.001..005Runner-internal submodules
runner.settlement.001immutable terminal settlement record

The parent families execution.scenario.*, execution.fixture.*, execution.decision.*, execution.open-work.*, and execution.module.* belong to the Execution System Design. The former Runner-level module-ID family is retired because it obscured the M02-to-submodule hierarchy.

Runner submodules

IDSubmoduleDetailed design
runner.submodule.001Lifecycle Coordinatorlifecycle-coordinator.md
runner.submodule.002Workflow Hostworkflow-host.md
runner.submodule.003Managed Agent Invocationmanaged-agent-invocation.md
runner.submodule.004Custodycustody.md
runner.submodule.005Interpreterinterpreter.md

Design-driver definitions

IDDriver
runner.driver.001independent qualification of the current Runner implementation
runner.driver.002immutable admitted Delivery binding at the Runner boundary
runner.driver.003typed, statically wired Provider integration
runner.driver.004serialized workspace mutation safety
runner.driver.005durable control truth rather than inferred progress
runner.driver.006semantic recovery without blind replay
runner.driver.007owner-scoped retirement with preserved settlement evidence
runner.driver.008factual, minimized, non-controlling Observation
runner.driver.009local operational fit for the current preview
runner.driver.010the smallest justified deep structure: five private submodules

Scenario, flow, and view landing map

ConcernScenarioFlowViewInterfaces
authority and qualificationrunner.scenario.01runner.flow.001runner.view.001runner.interface.001
activation and version bindingrunner.scenario.02, runner.scenario.12runner.flow.002 (runner.flow.002.1..3)runner.view.003runner.interface.001, runner.interface.004, runner.interface.002
managed invocation and mutationrunner.scenario.03, runner.scenario.04runner.flow.003runner.view.011, runner.view.004runner.interface.004, runner.interface.003, runner.interface.002
bounded read fanoutrunner.scenario.05runner.flow.004runner.view.005runner.interface.004, runner.interface.003
wait and interventionrunner.scenario.06runner.flow.005 (runner.flow.005.1..3)runner.view.006runner.interface.001, runner.interface.002
crash and recoveryrunner.scenario.07runner.flow.006 (runner.flow.006.1..2)runner.view.007runner.interface.002, runner.interface.003, runner.interface.004
cancellationrunner.scenario.08runner.flow.007 (runner.flow.007.1..3)runner.view.008runner.interface.001, runner.interface.003, runner.interface.002, runner.interface.004
publication and settlementrunner.scenario.09runner.flow.008 (runner.flow.008.1..3)runner.view.009runner.interface.002, runner.interface.004
Observation outagerunner.scenario.10runner.flow.009runner.interface.005
retirementrunner.scenario.11runner.flow.010 (runner.flow.010.1..4)runner.view.010runner.interface.001, runner.interface.002, runner.interface.003, runner.interface.004

runner.view.002 records the static dependency direction shared by runner.interface.001..005. The Interpreter compiles the admitted activation before Host execution; it is deliberately internal and does not create another Core-facing interface ID.

Interface definitions

IDMeaning
runner.interface.001current Core-to-Runner execute / inspect / cancel seam for an already admitted activation
runner.interface.002Workflow Host capability owned inside Runner
runner.interface.003Managed Agent Invocation capability
runner.interface.004Custody capability for savepoint, git-tree, scope, result, publication, and settlement state
runner.interface.005one-way non-controlling Observation port

4. Acceptance register

IDRequired outcomeEvidence state
runner.acceptance.001Execution remains sole Delivery assessor and failures stay fail-closeddesign evidence available
runner.acceptance.002exact admitted Package/thread; no fabricated progressIteration 2 implementation and test evidence
runner.acceptance.003typed managed result; bypass rejectedIteration 2 implementation and test evidence
runner.acceptance.004DSH concrete path; unsupported Providers fail without fallbackIteration 2 implementation and test evidence
runner.acceptance.005bounded stable reads; mutation invalidates the viewIteration 2 implementation and test evidence
runner.acceptance.006correlated resume; stale input rejectedIteration 2 implementation and test evidence
runner.acceptance.007continue, restart, or intervene without blind replayIteration 2 implementation and test evidence
runner.acceptance.008cancellation converges without inventing a terminal outcomeIteration 2 implementation and test evidence
runner.acceptance.009result is preserved and publication is guardedIteration 2 implementation and test evidence
runner.acceptance.010Observation remains non-controlling and provenance-boundvalidator evidence only
runner.acceptance.011authorized retirement preserves settlement evidenceIteration 2 implementation and test evidence
runner.acceptance.012later Deliveries may adopt new configuration; in-flight Deliveries cannotIteration 2 implementation and test evidence
runner.acceptance.013English/Chinese structure and ID sets remain aligneddeterministic documentation check
runner.acceptance.014every claim routes to applicable evidence and no unsupported proof is impliedopen evidence review

5. Decision register

IDDecision
runner.decision.001Runner is Execution module M02, not a peer System or subsystem.
runner.decision.002Runner accepts only a fully admitted activation.
runner.decision.003Runner contains five private submodules with single-writer ownership.
runner.decision.004Workflow and invocation suspension remain distinct.
runner.decision.005Provider execution crosses a typed managed seam with no fallback.
runner.decision.006Workspace views are bounded and publication is guarded.
runner.decision.007Recovery is three-way and never fabricates an outcome.
runner.decision.008Retirement follows one authorization and produces immutable settlement.
runner.decision.009Observation is factual, minimized, and non-controlling.
runner.decision.010Credentials are action-scoped and excluded from durable content.
runner.decision.011LangGraph and DSH are replaceable implementation selections.
runner.decision.012In-flight implementation identity cannot be substituted.
runner.decision.013The historical ExecutionRuntimeAdapter name does not create a current Runner abstraction.
runner.decision.014English and Chinese companions keep structural and ID parity.
runner.decision.015Published contract semantics are distinguished from incomplete implementation proof.

6. Contract and open-work register

Workflow DSL 1.1.0 and Delivery Admission 1.0.0 are current inputs. Observation Catalog, OTel Observation Profile, and Execution–Evidence Interaction Contract 1.0.0 are frozen and published. Their machine package is validator-only: production mapping and cross-implementation conformance remain unproven.

IDCurrent disposition
runner.open-work.003.1Runner-side evidence for parent execution.open-work.001: prove Workflow DSL compatibility at the admitted-activation boundary
runner.open-work.003.2Runner-side evidence for parent execution.open-work.002: prove Delivery Admission and Manifest binding in implementation
runner.open-work.003.3Runner-side evidence for parent execution.open-work.003: prove the current Core-to-Runner seam; legacy runtime-profile SPI names are historical only
runner.open-work.003.4Runner-side evidence for parent execution.open-work.004: prove production Observation mapping and cross-implementation conformance
runner.open-work.006canonical-identity representation-binding spike; retain the original ID and evidence meaning
runner.open-work.007OTel semantic-carrier spike; retain the original ID and evidence meaning
runner.open-work.008post-MVP Provider work beyond the DSH-only MVP
runner.open-work.009complete fault and recovery fixture corpus
runner.open-work.010complete supported-substrate qualification evidence
runner.open-work.011replace operational defaults with measured values where required
runner.open-work.012prove exact submodule interfaces and static dependency direction
runner.open-work.013prove Observation mapping and outage isolation in production integration

Legacy uppercase profile identifiers and agent-ops.runtime-profile-spi@1.0.0 are historical Git evidence only. They are not current authority, readiness state, or active dependency names.

7. Iteration 2 evidence routing

The implementation evidence is the pinned execution-system submodule, especially src/interpreter, src/coordinator, src/host, src/invocation, src/custody, and src/composition. Tests under execution-system/test/{interpreter,coordinator,host,invocation,custody,integration,providers,contracts} cover the implemented Runner boundary and private collaboration. This evidence proves the checked Iteration 2 implementation only; it does not prove M01 Delivery, production Observation integration, or cross-implementation conformance.