86%

Root closure + arbitrary-depth invocation

Goal

Define the durable execution model before engine implementation: one immutable root closure owns an arbitrary-depth workflow invocation tree, the transitive workset, and terminal closeout. Descendants perform local acceptance, return typed results, and delegate aggregate closure obligations to the root.

Implementation sketch

  • Persist EntryEnvelope, RootClosure, InvocationFrame, ChildCapability, ReturnContract, WorksetEvent, EvidenceReceipt, ClosureObligation, TerminalReceipt, and freeze generation schemas. This section through w-4bb72d45 is the SOLE TerminalReceipt schema owner; engine core imports/emits it and client transports consume/observe it without redefining it.
  • Derive every child capability during generic push from immutable parent/root authority plus declared workflow scope and optional target; reject raw tokens from classifiers, LLMs, or Actions.
  • Separate immutable root identity from active frame target and authorized child scope.
  • Allocate roots idempotently by request ID; require an explicit parent capability for child entry.
  • Implement generic push, suspend, return, fold-once, resume, cancel-subtree, compensation, and tombstone transitions.
  • Fold a child cancelled/abandoned receipt exactly once: settle compensation, tombstone the subtree, transfer surviving obligations to root, then resume, propagate cancellation, or block by the parent ReturnContract policy.
  • Classify gates as child admission, local acceptance, activation safety, or root-only aggregate integration/review, domain finalization, publication, and presentation.
  • Derive the union workset from mutation events and repository reconciliation; invalidate evidence after overlapping changes.
  • Close against frozen repository/tracker/queue revisions. Use one CAS reopen-generation action to invalidate aggregate receipts, increment generation, lift admission fencing, and register a cure child atomically.
  • Pin root engine bundles as typed StoreReference values into the harness_dist release store (scripts/harness_dist/release_store.py owns the bytes; the engine persists only references per the ai_os_contracts StoreReference contract).
  • Emit the sealed TerminalReceipt only after authoritative workflow truth is terminal (plan/tracker projection for domain roots; frozen batch projection for explicit virtual roots) and the root’s child folds, evidence, finalizers, and publication/presentation obligations are current. It is the state machine’s completed report; clients may observe it but cannot author or weaken it.
  • Define execution_state_digest as the digest of the canonical terminal root-protocol projection used by root_closure_ready: root/bundle identity, closure generation and fencing epoch, terminal frame tree, child folds/tombstones, frozen workset/evidence/obligation state, and finalizer receipt references. Exclude leases, timestamps, client lifecycle, scratch, and presentation fields. Root closeout produces it; sealed-receipt resolution recomputes and verifies it before any transport may observe the receipt.

Test strategy / acceptance

Property and fault tests cover arbitrary depth, ancestry, idempotency, cross-root rejection, accepted/stopped return folding, parent resume/propagate/block cancellation policies, gates, stale children, evidence, freeze/reopen, compensation, revisions, bundles, crash recovery, and frame-cursor disagreement repaired/rejected with plan/tracker state unchanged.

Work Items

  • Solely own and define EntryEnvelope, RootClosure, InvocationFrame, ChildCapability, state-authority-bound TerminalReceipt, and immutable bundle schemas with request-idempotent root creation, immutable ancestry, active frame, return target, attempt/fencing epochs, and durable execution store; define authoritative_state_digest plus canonical terminal root-protocol execution_state_digest production/recomputation; allow a frame node cursor only with an unresolved effect/wait/finalizer receipt, clear it on settlement, and never let it override plan/tracker workflow state
  • Solely own and define EntryEnvelope, RootClosure, InvocationFrame, ChildCapability, state-authority-bound TerminalReceipt, and typed StoreReference pinning (bundle bytes live solely in the harness_dist release store per the ai_os_contracts StoreReference contract; the engine persists only references and never materializes bundle bytes) with request-idempotent root creation, immutable ancestry, active frame, return target, attempt/fencing epochs, and durable execution store; define authoritative_state_digest plus canonical terminal root-protocol execution_state_digest production/recomputation; allow a frame node cursor only with an unresolved effect/wait/finalizer receipt, clear it on settlement, and never let it override plan/tracker workflow state
  • Implement engine-issued ChildCapability plus generic push/suspend/return/fold-once/resume protocol for arbitrary-depth workflows
  • Define append-only WorksetEvent and content-bound EvidenceReceipt aggregation with overlap-based invalidation
  • Classify every gate as admission, local acceptance, activation safety, aggregate integration/review, domain finalization, publication, or presentation; require folded children to run all three child classes
  • Implement frozen-generation closeout with external revision fencing, once-per-generation aggregate gates, atomic reopen-and-register on findings, stale-child reactivation, idempotent global finalizers, and a sealed state-machine-issued TerminalReceipt after every required closeout receipt is current
  • Implement root and child cancellation/abandonment compensation, stopped-child fold-once parent resume/propagate/block policy, tombstones, concurrency fencing, crash recovery, bundle inheritance, and standalone versus child entry

Fresh intel (regenerated)

This section is NOT greenfield and NOT unstarted-in-code. scripts/workflow_engine/ already carries a substantial, architecturally-clean scaffold of the exact schema surface this section owns — 6 core modules (root_closure.py 497L, execution_store.py 490L, terminal_protocol.py 199L, contract_validation.py, capability_authority.py, store_references.py) plus 11 on-disk test files — while plan.json still reports the section not-started, 0/7 work items. The graph has real symbols for RootClosure, InvocationFrame, TerminalReceipt, EntryEnvelope, ChildCapability, ExecutionStore, and execution_state_digest. The work is formalize + harden + spec-reconcile the existing scaffold, not write from scratch.

Three decisive facts the recon forces before any work:

  1. The schema-owner work item w-4bb72d45 is abandoned; the LIVE owner is w-0a83510d — the variant that pins engine bundles as a typed StoreReference into the harness_dist release store. That is a cross-plan dependency on plans/ai-os-platform section s-08f4833c (which owns StoreReference in scripts/harness_dist/ai_os_contracts.py:179). The plan HISTORY (2026-07-17, INV-21) already logged this section as hard-deferred on s-08f4833c (not-started). [JOIN] the abandoned-WI swap + the cross-plan defer + the already-scaffolded store_references.py consumer seam → the schema shape is settled; the section is BLOCKED on the ai-os-platform contract landing, and the consumer seam is written and waiting.

  2. The as-built scaffold ALREADY practices clean SSOT delegation — a positive constraint, not a defect. terminal_protocol.py is the SSOT for the terminal projection/digest/seal path; execution_store.py re-exposes those as thin one-line delegates (execution_store.py:447-490). capability_authority.py is the SSOT for capability minting; execution_store.mint_child_capability (:295) delegates to it. contract_validation.py owns the closed value-sets (STATE_AUTHORITIES=("domain_artifact","virtual_root"), PROTOCOL_LIFECYCLES, SETTLED_LIFECYCLES, OPEN_RECEIPT_KINDS, SHADOW_DOMAIN_STATE_KEYS) + validate_engine_contract + canonical_digest. The design’s dominant hygiene exposure is therefore NOT duplication-inside-the-package; it is (a) spec/impl vocabulary reconciliation and (b) the write_atomic scatter across the wider repo (§5, §3H).

  3. There is a spec/impl field-vocabulary divergence the schema-owner MUST reconcile. Spec sec 1.7 declares RootClosure{ ..., original_directive_digest, mode, authority, baseline_by_repo, external_revision_set, finalization_journal, publication_receipt }; the as-built RootClosure (root_closure.py:236) carries state_authority, engine_bundle, workset_digest, evidence_digest, finalizer_receipt_refs and NONE of the spec’s mode/baseline_by_repo/external_revision_set/finalization_journal/publication_receipt. Per CLAUDE.md (spec is SSOT for the workflow spec here — the plan’s own spec/workflow-state-machines.md), the schema owner reconciles the two, records the mapping, and freezes ONE canonical field set in schemas/root_closure.schema.json.

Constrained-symbols (genuine EXTERNAL do-not-touch hazards — NOT this section’s own schema deliverable):

["StoreReference", "resolve_release", "publish_release", "gc_release_store", "serve_next_v7", "route_walk", "run_state_machine"]
  • StoreReference / resolve_release / publish_release / gc_release_store — owned by plans/ai-os-platform s-08f4833c (scripts/harness_dist/); this section CONSUMES them through the store_references.py seam and NEVER redefines or re-materializes the byte store (spec sec 1.7: “the engine never materializes its own bundle store”).
  • serve_next_v7 / route_walk / run_state_machine — the LIVE serve path executing THIS plan (self-hosting strangler-fig constraint); scripts/workflow_engine/ imports nothing from and is imported by nothing on it.
  • EXCLUDED as work-SUBJECT (not constraints): RootClosure, InvocationFrame, TerminalReceipt, EntryEnvelope, ChildCapability, ExecutionStore, execution_state_digest, seal_terminal_receipt — these ARE what this section owns/hardens.

DIG DEEPER

python -m scripts.plan_corpus.read --summary plans/workflow-engine-rework
sed -n '1,32p' plans/workflow-engine-rework/content/root-closure-arbitrary-depth-invocation--s-be712e10.md
sed -n '1068,1160p' plans/workflow-engine-rework/spec/workflow-state-machines.md   # spec sec 1.7

(full dossier: root-closure-arbitrary-depth-invocation—s-be712e10.intel.md)