egohygiene · szmyty · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -15,6 +15,8 @@ test = false
 bench = false
 
 [dependencies]
+base64 = "0.22.1"
+blake3 = "1.8.2"
 fs2 = "0.4.3"
 semver = "1.0.26"
 serde = { version = "1.0.219", features = ["derive"] }

diff --git a/README.md b/README.md
@@ -25,8 +25,10 @@ neutral process transcript. Flow can also launch one exact authorized
 control, and direct-child reaping; observe exact locked package/executable
 subjects; require exact correlated process authority/isolation evidence; accept
 explicitly bound artifacts; and validate a closed scenario manifest for
-synthetic orchestration fixtures. It does not copy holon source or claim a
-product orchestrator, CLI, real provider adapter, operating-system sandbox,
+synthetic orchestration fixtures. The first released-provider library adapter
+pins [Optiflow v0.1.1 read-only inspection](docs/integrations/optiflow-v0.1.1-read-only.md)
+and retains a separate durable attempt receipt. It does not copy holon source
+or claim a product orchestrator, public Flow CLI, mutation adapter, operating-system sandbox,
 general scenario executor, automatic recovery scheduler, or public resume CLI.
 Prepared process execution now has [durable run state](docs/integrations/durable-state.md)
 with immutable plans, atomic snapshots, verified checkpoints, status inspection,
@@ -175,10 +177,9 @@ FLO-Q03. The process seam still does not implement authenticity verification,
 operating-system sandbox enforcement, authenticated host evidence,
 descriptor-bound launch, or process-tree containment, and the scenario contract
 is not an executor.
-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.
+The holons remain independently released repositories. Optiflow v0.1.1 is
+the first pinned real provider adapter; Aniflow and Renderflow adapters and
+the restore-and-assess workflow remain follow-up work.
 
 ## License
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -3,12 +3,12 @@ schema: aether.architecture-document/v1
 id: flow-roadmap
 title: Flow Roadmap
 kind: architecture-document
-version: 1.3.5
+version: 1.3.6
 status: draft
 owners:
   - egohygiene
 created: 2026-08-13
-updated: 2026-09-26
+updated: 2026-09-27
 governed_by:
   - architecture-roadmap
 depends_on:
@@ -23,6 +23,22 @@ supersedes: []
 
 # Flow Roadmap
 
+## 2026-09-27 Optiflow read-only adapter handoff
+
+Flow #50 now proposes a pinned Optiflow v0.1.1 native CLI library adapter for
+read-only scan, report, and exact-duplicate review planning. The
+[compatibility receipt](docs/integrations/optiflow-v0.1.1-read-only.md)
+records source revision, archive/executable digests, contract schemas,
+declared effects, Linux synthetic proof, and macOS native-execution gap. The
+adapter writes versioned local evidence; dry-run, quarantine, restore, and
+finalization remain explicitly unsupported. The maintainer owns PR merge.
+
+After review/merge, Flow #53 may compose this read-only capability into the
+suite CLI alongside other released-provider adapters. Flow #73 separately
+qualifies a v0.2 mutation release after Optiflow #93; Flow #74 owns the later
+PNG integration after Optiflow #95. Older queue snapshots below are historical
+where they conflict with this handoff and the live Flow #11 issue.
+
 ## 2026-09-26 live suite handoff
 
 > [!IMPORTANT]

diff --git a/docs/architecture/foundation/ARCHITECTURE.md b/docs/architecture/foundation/ARCHITECTURE.md
@@ -3,12 +3,12 @@ schema: aether.architecture-document/v1
 id: flow-architecture
 title: Flow Architecture
 kind: architecture-document
-version: 0.13.2
+version: 0.13.3
 status: draft
 owners:
   - egohygiene
 created: 2026-08-13
-updated: 2026-09-26
+updated: 2026-09-27
 governed_by:
   - architecture-architecture
 depends_on:
@@ -188,6 +188,26 @@ This runner is not a sandbox. It does not authenticate host evidence, constrain
 filesystem/network/subprocess authority, contain descendants, or bind the
 fresh digest observation to the host's later executable file object.
 
+The first released-provider adapter pins the immutable Optiflow v0.1.1
+executable and consumes its native `optiflow.command-result.v1` single JSON
+document. It does not translate native stdout into a synthetic Flow JSON Lines
+transcript. Its public library API probes the exact release, exposes only
+read-only scan, report, and exact-duplicate review-plan capabilities, and
+rejects mutation capabilities individually. It clears the child environment,
+disables configuration discovery and media probing, constrains traversal, and
+checks source root and filesystem identity between steps. Flow independently
+verifies each committed provider artifact set, its member bytes and schema
+bindings, and the review-only plan safety fields.
+
+The adapter records a separate `flow.optiflow-read-only-receipt/v1` local
+attempt before launch and after scan, report, and plan. A reopened intermediate
+attempt requires review; a completed receipt must still match its retained
+artifact bytes. This receipt is local audit evidence, not an execution grant,
+checkpoint in the generic durable graph, provider signature, sandbox claim, or
+approval. The existing Flow JSONL runner and durable graph contracts remain
+unchanged. ADR-0013 owns this native-protocol exception and the staged handoff
+to later composition.
+
 ### Extension lifecycle
 
 Flow coordinates extensions through the ordered lifecycle `discover → inspect →

diff --git a/docs/architecture/governance/DECISIONS.md b/docs/architecture/governance/DECISIONS.md
@@ -3,12 +3,12 @@ schema: aether.architecture-document/v1
 id: flow-decisions
 title: Flow Decisions
 kind: architecture-document
-version: 0.10.0
+version: 0.10.1
 status: draft
 owners:
   - egohygiene
 created: 2026-08-13
-updated: 2026-09-26
+updated: 2026-09-27
 governed_by:
   - architecture-decisions
 depends_on:
@@ -66,12 +66,14 @@ justifies separate ADRs.
 | [ADR-0010](decisions/ADR-0010-bounded-direct-process-supervision.md) | Bound direct provider launch and supervision | Accepted | 2026-09-21 | None | Sandbox enforcement, descriptor-bound launch, process-tree containment, or durable interruption changes the runner boundary |
 | [ADR-0011](decisions/ADR-0011-durable-run-state.md) | Persist prepared intent and acceptance in immutable local snapshots | Proposed | Pending review | None | Migration, distributed writers, automatic recovery, authenticated state, or stronger durability changes the boundary |
 | [ADR-0012](decisions/ADR-0012-fresh-graph-assessment.md) | Require fresh prerequisite evidence for durable graph execution | Proposed | Pending review | None | Scheduling, cross-plan reuse, or concurrent artifact mutation changes the assessment boundary |
+| [ADR-0013](decisions/ADR-0013-optiflow-native-read-only-adapter.md) | Pin Optiflow v0.1.1 behind a native read-only adapter | Proposed | Pending review | None | A released mutation contract, native protocol revision, or generic graph composition changes this boundary |
 
 ## Active decisions
 
 ADR-0011 is proposed with Flow #49 and remains subject to maintainer review.
 Its implementation merged in PR #63. ADR-0012 is proposed with Flow #64, the
-first bounded checkpoint under #31.
+first bounded checkpoint under #31. ADR-0013 is proposed with Flow #50 for
+the first independently verified released-provider integration.
 
 The indexed ADRs are authoritative. Summaries in other documents must link back
 to them rather than recreate rationale.

diff --git a/...architecture/governance/decisions/ADR-0013-optiflow-native-read-only-adapter.md b/...architecture/governance/decisions/ADR-0013-optiflow-native-read-only-adapter.md
@@ -0,0 +1,72 @@
+---
+schema: aether.architecture-document/v1
+id: flow-adr-0013
+title: Pin Optiflow v0.1.1 behind a native read-only adapter
+kind: architecture-document
+version: 0.1.0
+status: proposed
+owners:
+  - egohygiene
+created: 2026-09-27
+updated: 2026-09-27
+governed_by:
+  - architecture-decisions
+depends_on:
+  - flow-architecture
+related:
+  - flow-decisions
+  - flow-roadmap
+supersedes: []
+---
+
+# ADR-0013: Pin Optiflow v0.1.1 behind a native read-only adapter
+
+## Context
+
+Flow's generic process contract uses a Flow JSON Lines invocation, event, and
+result protocol. Immutable Optiflow v0.1.1 exposes a different released CLI:
+direct argv and one `optiflow.command-result.v1` stdout document with
+provider-owned committed artifact sets. An invented JSONL transcript would
+confuse provider evidence with Flow's own validation claims. The release
+qualifies read-only scan, report, and review planning. Later mutation code is
+not part of that immutable release.
+
+## Decision
+
+The initial adapter is a public Flow library API with a strict native-protocol
+translator. It pins exact target-specific release archives and executable
+digests, probes `--version`, launches the binary with bounded output/time and
+literal argv, and validates exit, coverage, native schema, source identity,
+artifact-set marker, member digests, and plan safety. It records a separate
+versioned local receipt before and after each step; partial coverage remains
+partial. Dry-run, quarantine, restore, and finalization are explicit
+unsupported capabilities. No review plan grants mutation authority.
+
+This local receipt does not enter `flow.run-state/v1` as an accepted generic
+checkpoint. The provider's native CLI cannot satisfy the existing generic
+Flow process invocation contract without a separate wrapper and authority
+mapping. The suite CLI and cross-provider graph composition will consume the
+read-only adapter in later Flow work. A mutation adapter requires a separately
+qualified release and a new authority/recovery contract.
+
+## Consequences and review triggers
+
+The adapter writes only local provider and Flow evidence outside the selected
+source root. It does not sandbox the trusted pinned binary or prove a
+race-free executable open. Root identity is rechecked between commands;
+individual source observations are the provider's read-only evidence, not
+apply-time authorization. An interrupted receipt requires inspection and no
+artifact file alone implies Flow completion. Receipt integrity is local
+content verification, not an authenticated signature.
+
+Review this decision when a released mutation protocol is qualified, when the
+native CLI contract changes, or when Flow's generic graph accepts a
+provider-native adapter through an explicitly versioned authority boundary.
+
+## Validation
+
+The synthetic release fixture calls the public Flow API, verifies source bytes
+remain unchanged, checks the three committed artifact sets and receipt reopen,
+and exercises release mismatch, path overlap, escape, interruption, and
+post-run artifact corruption refusals. macOS binaries are pinned by digest but
+need native execution verification.
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
@@ -7,6 +7,8 @@ implementations.
   directions.
 - [Capability matrix](capability-matrix.md) records the evidence baseline and
   gates future adapter claims.
+- [Optiflow v0.1.1 read-only adapter](optiflow-v0.1.1-read-only.md) pins the
+  immutable native CLI, effects, receipt, clean-room fixture, and refusal scope.
 - [First slice](first-slice-restore-and-assess.md) bounds the initial executable
   orchestration outcome.
 - [Federated extension contract](extension-contract.md) defines extension
@@ -46,6 +48,8 @@ and
 [ADR-0009](../architecture/governance/decisions/ADR-0009-process-authority-isolation.md).
 The bounded runner is governed by
 [ADR-0010](../architecture/governance/decisions/ADR-0010-bounded-direct-process-supervision.md).
+The native Optiflow adapter is proposed under
+[ADR-0013](../architecture/governance/decisions/ADR-0013-optiflow-native-read-only-adapter.md).
 
 ## Implementation status
 

diff --git a/docs/integrations/capability-matrix.md b/docs/integrations/capability-matrix.md
@@ -7,7 +7,7 @@ Implementation work must reinspect named provider releases and replace each
 | Provider snapshot | Observed domain capability | Current integration evidence | First-slice role | Adapter decision |
 | --- | --- | --- | --- | --- |
 | Aniflow `20783d7374298e5fd44c782348a3c944c9318656` / package v0.2.0 | temporal inspection, decomposition, ordered processing, reconstruction, validation | single-crate behavior documented on 2026-08-13; final public library contract not yet proven | create and validate a new temporal master | pending release reinspection; library if stable, otherwise CLI |
-| Optiflow v0.1.0 snapshot documented on 2026-08-13 | read-only collection discovery, identity/relationship evidence, reporting | mutation is explicitly outside the v0.1 safety boundary | scan source before processing; rescan source plus output | pending release reinspection; prefer structured read-only CLI if library is not stable |
+| Optiflow immutable v0.1.1 (`b82599a2231e997d42fd9f26f4b59587f4ae14cf`) | scan, report, exact-duplicate review plan; dry-run/quarantine/restore/finalize unsupported | [release adapter and synthetic Linux fixture](optiflow-v0.1.1-read-only.md) pin binary/contract/schema/effects; macOS archive digests pinned but native run pending | read-only source inventory and later rescan | native `optiflow.command-result.v1` direct CLI adapter; Flow-owned receipt, no mutation authority |
 | Renderflow v0.2.1 snapshot documented on 2026-08-13 | transform DAGs, documents, image/audio conversion, plugins and build caching | existing core/CLI/plugin-SDK split; suite result compatibility unproven | none | defer until restore-and-assess passes |
 
 An adapter is compatible only when a fixture records the provider version,