diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c20a7e7..08e5dc9 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/README.md b/README.md index 43e2335..adf9e53 100644 --- a/README.md +++ b/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,7 +33,10 @@ 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. @@ -41,14 +44,16 @@ 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 diff --git a/ROADMAP.md b/ROADMAP.md index 5150542..ee8bd7a 100644 --- a/ROADMAP.md +++ b/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,9 +38,9 @@ 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. @@ -48,9 +48,10 @@ adapters. **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,7 +83,7 @@ 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 @@ -90,7 +91,8 @@ issues: [7, 23] **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:** @@ -98,21 +100,26 @@ then a minimal orchestrator executes a fixture through one provider seam in CI. 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.