[FLO-3.2a] Freeze stdio process framing and transcript validation

.github/workflows/ci.yml

@@ -52,6 +52,9 @@ jobs:
       - name: Run hermetic extension example
         run: cargo run --example hermetic_extension --locked
 
+      - name: Run hermetic process transport example
+        run: cargo run --example hermetic_process_transport --locked
+
       - name: Verify package contents
         run: cargo package --locked
 

README.md

@@ -17,12 +17,12 @@ compose them through stable public library interfaces or versioned CLI
 contracts, without introducing direct dependencies between sibling holons.
 
 The repository remains architecture-led, but it is no longer documentation
-only. The current FLO-Q02 candidate adds a small Rust library that validates the
-federated extension contracts, resolves one capability deterministically, and
-executes one caller-injected in-process extension through a seam proven by a
-hermetic reference port. It does not copy holon source or claim a product
-orchestrator, CLI, external process adapter, durable run state, or resume
-support.
+only. FLO-Q02 provides a small Rust library that validates the federated
+extension contracts, resolves one capability deterministically, executes one
+caller-injected in-process extension, and validates a provider-neutral process
+transcript without launching a child process. It does not copy holon source or
+claim a product orchestrator, CLI, production process adapter, durable run
+state, or resume support.
 
 ## Executable checkpoint
 
@@ -33,22 +33,27 @@ The first executable checkpoint is deliberately library-only:
 - `ExtensionCatalog` inspection and resolution retain deterministic selection
   and rejection evidence;
 - `Orchestrator` invokes a matching `ExtensionPort` and returns an execution
-  only after Flow validates event and terminal-result correlation; and
+  only after Flow validates event and terminal-result correlation;
+- the process seam deterministically encodes one JSON Lines invocation and
+  checks bounded, caller-supplied stdout/stderr plus process completion
+  evidence, then routes decoded stdout through the same event/result gate; and
 - a no-effects, no-artifacts hermetic port and example prove the seam without a
   provider binary, filesystem output, network access, or external service.
 
 Run the reference example with:
 
 ```console
 cargo run --example hermetic_extension --locked
+cargo run --example hermetic_process_transport --locked
 ```
 
-`EventSink` is the observation boundary for this checkpoint. A future logging
-or OpenTelemetry adapter can attach there, but observations do not influence
-provider selection or execution identity. `emit` is fallible and its error is
-visible to the provider; rejection makes `Orchestrator` return
-`ExecutionError`. A sink cannot directly mutate provider evidence or grant
-authority. No logging backend or telemetry exporter ships in this slice.
+`EventSink` is a fallible, authoritative execution observer, not a best-effort
+telemetry exporter. Observations do not influence provider selection or
+execution identity, but `emit` rejection makes `Orchestrator` return
+`ExecutionError` and never triggers fallback. A sink cannot directly mutate
+provider evidence or grant authority. The separate observability roadmap owns
+any future non-authoritative logging or OpenTelemetry seam; no such backend or
+exporter ships here.
 
 `ValidatedExecution` means the provider evidence passed Flow's contract,
 identity-correlation, ordering, diagnostic redaction-flag, and
@@ -62,11 +67,12 @@ this checkpoint does not content-scan diagnostics or sanitize unrestricted
 contract strings.
 
 Only `trusted` candidates are resolution-eligible in this checkpoint;
-`Orchestrator` executes only a caller-injected in-process port. `sandboxed`
-candidates fail closed because no sandbox backend exists. Declared execution
-limits are validated and correlated as metadata, not enforced. The injected
-code has no Flow-owned timeout, cancellation, stdout/stderr bound, panic
-isolation, filesystem or network containment, or other side-effect enforcement.
+`Orchestrator` either executes a caller-injected in-process port or validates a
+caller-supplied process transcript. `sandboxed` candidates fail closed because
+no sandbox backend exists. In-process limits remain correlated metadata only.
+The process-transcript seam checks already captured stdout/stderr byte counts
+and completion evidence, but it does not launch, time out, cancel, signal, reap,
+or isolate a process. Neither seam provides filesystem or network containment.
 
 ## Architecture
 
@@ -76,6 +82,7 @@ isolation, filesystem or network containment, or other side-effect enforcement.
 - [Decision index](docs/architecture/governance/DECISIONS.md)
 - [Suite boundaries](docs/integrations/suite-boundaries.md)
 - [Federated extension contract](docs/integrations/extension-contract.md)
+- [Process transport contract](docs/integrations/process-transport.md)
 - [Versioned contracts](contracts/README.md)
 - [Roadmap](ROADMAP.md)
 
@@ -84,13 +91,15 @@ skills, agents, templates, and validators used to maintain these documents.
 
 ## Status
 
-Flow is in the **executable contract seam** phase. Issue #23 supplies the
-candidate library implementation and CI definition for the remaining FLO-Q02
-evidence; FLO-Q02 stays active until that change is merged and exercised by
-default-branch CI. Current descriptions of Aniflow, Optiflow, and Renderflow are
-grounded in their default branches as inspected on 2026-08-13. The holons
-remain independently released repositories; real provider adapters and the
-restore-and-assess workflow remain follow-up work.
+Flow is in the **executable contract seam** phase. Issue #23 / PR #24 is merged,
+and default-branch CI passed at
+`979e033409c823b38591b59eca820522efabfa12`. Issue #26 adds the first bounded
+external-process contract over injected evidence; it does not yet implement a
+runner, artifact binding, executable verification, or host isolation. Current
+descriptions of Aniflow, Optiflow, and Renderflow are grounded in their default
+branches as inspected on 2026-08-13. The holons remain independently released
+repositories; real provider adapters and the restore-and-assess workflow remain
+follow-up work.
 
 ## License
 

ROADMAP.md

@@ -3,7 +3,7 @@ schema: aether.architecture-document/v1
 id: flow-roadmap
 title: Flow Roadmap
 kind: architecture-document
-version: 0.4.0
+version: 0.5.0
 status: draft
 owners:
   - egohygiene
@@ -38,19 +38,20 @@ updated: 2026-09-16
 
 **Lifecycle:** executable contract prototype
 
-**Current gate:** Merge Flow #23's library-only execution seam and observe its
-success and adversarial cases on default-branch CI before expanding provider
-adapters.
+**Current gate:** Finish Flow #26's deterministic process framing and transcript
+validation, then observe its success and adversarial cases on default-branch CI
+before implementing a real provider adapter.
 
 **North-star outcome:** Federated orchestration across holons with stable provider seams, resumable work, and explicit evidence.
 
 ### Visual roadmap publication
 
 **Mode:** `central`  
 **Route:** `/roadmap/flow/`  
-**Current publication evidence:** Architecture, contract source, and the Flow
-#23 executable-core candidate; no executable release or Pages publication
-observed.
+**Current publication evidence:** Architecture, contract source, merged Flow
+#23 / PR #24, and successful default-branch CI at
+`979e033409c823b38591b59eca820522efabfa12`; no executable release or Pages
+publication observed.
 
 Publish the public-safe projection through egohygiene.io at /roadmap/flow/. This repository owns intent and acceptance evidence; it does not add a second site deployment.
 
@@ -82,37 +83,43 @@ issues: []
 id: FLO-Q02
 status: active
 depends_on: [FLO-Q01]
-issues: [7, 23]
+issues: [7, 23, 26]
 -->
 #### FLO-Q02 — Freeze extension seams and create a tested executable core
 
 **State:** `active`  
 **Depends on:** `FLO-Q01`
 
 **Outcome:** Versioned extension/trust envelopes constrain provider SDK mappings,
-then a minimal orchestrator executes a fixture through one provider seam in CI.
+a minimal orchestrator executes a fixture through one provider seam, and the
+same acceptance gate validates a deterministic external-process transcript.
 
 **Exit criteria:**
 
 - [x] Provider declarations and operator authority are separated by versioned
   manifest and lock contracts.
 - [x] Invocation, event, result, and resolution schemas cover both execution
   modes and compatibility failures.
-- [x] A runnable library path and hermetic example exist in the Flow #23
-  candidate revision.
-- [ ] Default-branch CI proves success and failure behavior.
+- [x] A runnable library path and hermetic example exist in merged Flow #23 /
+  PR #24.
+- [x] Default-branch CI proves the in-process success and failure behavior.
+- [ ] A deterministic process request/transcript seam reuses Flow-owned event
+  and result validation without claiming a production runner or sandbox.
 
 **Current evidence:**
 
 - Flow #7 defines the extension/trust schemas, synthetic fixtures, and
   compatibility outcomes.
-- Flow #23 supplies a Rust 1.85 library candidate for deterministic resolution,
-  injected in-process execution, Flow-owned event/result validation, and a
-  no-effects hermetic example. Its CI definition covers Rust 1.85, stable Rust,
-  and every repository validator.
-- FLO-Q02 remains active until #23 is merged and a default-branch CI run proves
-  both success and adversarial behavior. This evidence does not claim a public
-  CLI, process execution, real provider adapters, durable state, or resume.
+- Flow #23 / PR #24 supplies deterministic resolution, injected in-process
+  execution, Flow-owned event/result validation, and a no-effects hermetic
+  example.
+- Default-branch CI run 35094682274 passed on Rust 1.85, stable Rust, and every
+  repository validator at `979e033409c823b38591b59eca820522efabfa12`.
+- Flow #26 is the focused next slice. FLO-Q02 remains active until its
+  host-neutral process framing and transcript conformance are merged and proven
+  on default-branch CI. This evidence does not claim a public CLI, a production
+  child-process runner, artifact acceptance, executable verification, sandbox
+  enforcement, real provider adapters, durable state, or resume.
 
 <!-- roadmap-step
 id: FLO-Q03
@@ -193,8 +200,9 @@ issues: []
 ## Strategic context
 
 Flow begins with three independently released Rust tools. Its first executable
-checkpoint is a bounded, library-only extension resolution and execution seam;
-it is not yet a product orchestrator or provider integration. Flow will
+checkpoint is a bounded extension resolution and execution seam: merged
+in-process evidence plus host-neutral process transcript validation. It is not
+yet a product orchestrator, process runner, or provider integration. Flow will
 integrate named releases through public libraries or versioned CLI contracts.
 It will not consolidate repositories, copy sibling source, or hide missing
 provider capabilities inside the facade.
@@ -237,16 +245,28 @@ outside selection and result identity so future logging and OpenTelemetry
 adapters cannot rewrite provider evidence. A sink failure rejects the
 checkpoint execution.
 
-**Candidate evidence:** Flow #23 includes a no-effects, no-artifacts hermetic
-port and executable library example, success and adversarial tests, and CI for
-Rust 1.85, stable Rust, and the existing Python validators. Default-branch CI
-after merge remains the final FLO-Q02 gate. Process transport, real provider
-adapters, durable state, cancellation, checkpoints, and resume are deferred.
-Only trusted candidates are resolution-eligible in this checkpoint;
-`Orchestrator` executes only a caller-injected in-process port. Declared limits
-are correlated metadata rather than runtime enforcement. Caller-issued
-configuration and authorization identities are correlated but not
-authenticated.
+**Delivered evidence:** Flow #23 / PR #24 includes a no-effects, no-artifacts
+hermetic port and executable library example, success and adversarial tests,
+and CI for Rust 1.85, stable Rust, and the existing Python validators.
+Default-branch CI passed at
+`979e033409c823b38591b59eca820522efabfa12`. Only trusted candidates are
+resolution-eligible. The in-process seam treats declared limits as correlated
+metadata, and caller-issued configuration and authorization identities are
+correlated but not authenticated.
+
+### Freeze external-process framing
+
+Encode one compact, LF-terminated invocation document and validate a bounded,
+caller-supplied JSON Lines provider transcript containing ordered events and one
+terminal result. Reuse the existing Flow-owned correlation, redaction-flag,
+terminal-consistency, and observer checks. Treat stdout as protocol-only,
+stderr as opaque operational evidence, and exit zero as transport evidence
+rather than semantic success.
+
+**Candidate evidence:** Flow #26 adds the pure framing decoder, hermetic
+transcript example, typed framing/output/completion failures, and adversarial
+tests. It does not launch or isolate a process, bind filesystem artifacts,
+verify executable bytes, deliver cancellation, or authenticate a publisher.
 
 ### Pin the capability matrix
 

contracts/README.md

@@ -26,6 +26,12 @@ The extension contracts are described in
 Provider manifests request behavior; only the operator-controlled lock grants
 authority, precedence, or fallback.
 
+Process framing reuses the existing invocation, event, and result documents
+rather than introducing a wrapper contract. The provisional JSON Lines wire
+rules and host-neutral acceptance boundary are specified in
+[`docs/integrations/process-transport.md`](../docs/integrations/process-transport.md).
+Wire whitespace and caller read chunking are not contract identity.
+
 `compatibility.flow_version_requirement` is parsed with Rust's `semver`
 `VersionReq` grammar and must use comma-separated comparators. For example,
 `>=0.1.0, <0.2.0` is a bounded range; `>=0.1.0 <0.2.0` is invalid. Invalid or
@@ -40,16 +46,18 @@ downgrade.
 
 The current Rust checkpoint maps the six extension-v1 documents into closed
 library models and adds semantic checks that JSON Schema alone does not express.
-Its hermetic reference execution is not a provider adapter and does not prove
-process transport, filesystem artifact handling, sandboxing, checkpoints, or
-resume.
+Its hermetic in-process reference and host-neutral process transcript are not
+provider adapters and do not prove process launch/capture enforcement,
+filesystem artifact handling, executable verification, sandboxing,
+checkpoints, or resume.
 
 For this checkpoint, the caller owns configuration canonicalization and digest
 generation plus authorization issuance, authorization ID, and grants digest.
 Flow shape-checks these values and correlates the identities repeated by the
-provider; `ValidatedExecution` does not authenticate them. Execution-limit
-fields are likewise validated and correlated metadata, not timeout,
-cancellation, output-bound, panic, sandbox, or side-effect enforcement.
+provider; `ValidatedExecution` does not authenticate them. The process
+transcript validator checks already captured stdout/stderr lengths and a caller
+completion observation. That is not runtime timeout, cancellation, capture,
+panic, sandbox, or side-effect enforcement.
 
 Validate the set with:
 

docs/architecture/foundation/ARCHITECTURE.md

@@ -3,7 +3,7 @@ schema: aether.architecture-document/v1
 id: flow-architecture
 title: Flow Architecture
 kind: architecture-document
-version: 0.3.1
+version: 0.4.0
 status: draft
 owners:
   - egohygiene
@@ -70,9 +70,17 @@ are constructed as executable plus argv, never as shell strings.
 
 Pinned in-process adapters and bounded process adapters share the same
 invocation, event, result, validation, and provenance semantics. Process
-adapters additionally enforce declared time, output, cancellation, filesystem,
-environment, subprocess, network, AI, GPU, and side-effect limits outside the
-provider process.
+adapters must additionally enforce every time, output, cancellation,
+filesystem, environment, subprocess, network, AI, GPU, and side-effect
+guarantee they claim outside the provider process. A declaration, grant,
+transcript check, or adapter policy is not by itself sandbox enforcement.
+
+The first process boundary is host-neutral: Flow deterministically encodes one
+versioned invocation and validates a caller-supplied JSON Lines stdout
+transcript, bounded stderr length, and completion observation. That seam reuses
+the same Flow-owned event and result validation as in-process execution. It does
+not spawn, signal, time out, cancel, reap, inspect files from, or isolate a child
+process.
 
 ### Extension lifecycle
 
@@ -154,14 +162,16 @@ structure without overriding suite dependency rules.
 
 ## Current implementation boundary
 
-Flow issue #23 supplies a candidate Rust library with closed extension-v1
-models, deterministic single-capability resolution, one caller-injected
-in-process extension port, Flow-owned event/result validation, and a hermetic
-no-effects reference implementation. It does not yet supply the public CLI,
-process adapters, real holon adapters, artifact locators, durable run state,
-checkpoints, cancellation, or resume described elsewhere in this document.
-Structural units beyond that library seam remain constraints for later adapter
-and orchestration work, not claims about current source layout.
+Flow issue #23 / merged PR #24 supplies closed extension-v1 models,
+deterministic single-capability resolution, one caller-injected in-process
+extension port, Flow-owned event/result validation, and a hermetic no-effects
+reference implementation. Issue #26 adds deterministic process request framing
+and host-neutral transcript validation through that same acceptance gate. It
+does not yet supply the public CLI, a production child-process runner, real
+holon adapters, artifact locators, executable verification, enforceable
+isolation, durable run state, checkpoints, interruption, or resume. Structural
+units beyond these library seams remain constraints for later adapter and
+orchestration work, not claims about current source layout.
 
 ## Open questions
 
@@ -171,8 +181,11 @@ and orchestration work, not claims about current source layout.
 
 ## Validation
 
-The issue #23 candidate CI validates the Rust 1.85 and stable library builds,
-closed contract models, deterministic resolution, the hermetic in-process seam,
-and repository architecture metadata. Default-branch evidence remains pending
-merge. Forbidden dependency-edge checks, CLI-thinness, and subprocess adapter
-contract tests remain later gates for the corresponding runtime surfaces.
+Default-branch CI run 35094682274 validates PR #24's Rust 1.85 and stable
+library builds, closed contract models, deterministic resolution, hermetic
+in-process seam, and repository architecture metadata at
+`979e033409c823b38591b59eca820522efabfa12`. Issue #26 adds deterministic
+request/transcript conformance tests and a hermetic process-transport example
+to the same matrix. Forbidden dependency-edge checks, CLI-thinness, real
+launcher enforcement, artifact acceptance, and sandbox conformance remain
+later gates for their corresponding runtime surfaces.