Flow

One coherent way to inspect, plan, transform, validate, and explain content.

Flow is the developing orchestration library and suite architecture for Ego Hygiene's independently useful Rust tools:

Holon	Owns	Does not own
Aniflow	Time-based video decomposition, ordered processing, reconstruction, and temporal validation	Collection optimization or general document rendering
Optiflow	Local inventory, evidence-backed relationships, safe optimization plans, and collection normalization	Video-frame processing or transform-graph execution
Renderflow	Spec-driven transform graphs and publication-ready document, image, and audio derivatives	Collection policy or temporal video reconstruction
Flow	Cross-holon planning, compatibility, execution state, provenance, validation, recovery, and suite experience	Reimplementing a holon's specialized engine

Each holon remains usable as both a Rust library and a standalone CLI. Flow may 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 executable checkpoints provide 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. Flow can also launch one exact authorized trusted-unconfined local provider with bounded stdio, deadline/cancellation 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. The first released-provider library adapter pins Optiflow v0.1.1 read-only inspection 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 with immutable plans, atomic snapshots, verified checkpoints, status inspection, explicit recovery decisions, and fresh dependency-graph assessment before caller-selected downstream execution. Stale prerequisites invalidate their descendants for reuse while unrelated valid branches retain their eligibility.

Start with the current continuation handoff and live roadmap issue #11. The maintained suite dependency map and completion diagram preserve the October 6, 2026 issue atlas; the linked October 15 provider note is another dated observation. Their counts, draft states and next-up text are historical, and should be re-queried before execution.

Executable checkpoint

The executable contract surface remains library-led. The only repository binary is a synthetic conformance provider; it is not a public Flow CLI:

• closed Rust models and semantic validation cover the six extension-v1 documents;
• 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;
• the process seam deterministically encodes one JSON Lines invocation and requires a fresh opaque match for the exact locked package and executable, checks bounded caller-supplied stdout/stderr plus process completion evidence, then routes decoded stdout through the same event/result gate;
• flow.execution-subject-lock/v1 and flow.execution-subject-observations/v1 keep content equality, lock match, publisher declaration, operator trust, cryptographic verification, and transparency-log status as separate claims;
• flow.process-authority-profile/v1 and flow.process-enforcement-evidence/v1 bind exact requested/granted authority, trust, isolation, and caller-attested enforcement to the matched subjects;
• LocalProcessRunner freshly re-observes and directly launches the exact trusted-unconfined executable, clears and reconstructs its environment, manages bounded stdio workers, enforces timeout/cancellation grace and escalation, reaps the direct child, and reuses the transcript validator;
• artifact bindings map immutable input and candidate-output IDs to portable root-relative locators; Flow observes file/directory bytes beneath one root and returns an accepted set only after exact host/provider correlation;
• RunStore persists prepared intent and authority before launch, records accepted checkpoints after validation, and reopens with typed stale/corrupt-state refusal;
• flow.scenario-manifest/v1 pins synthetic inputs, providers, topology, expectations, resource budgets, coverage gaps, and cross-language canonical digests without defining plans or runs; and
• a no-effects, no-artifacts hermetic port and example prove the seam without a provider binary, filesystem output, network access, or external service;
• a separately compiled hermetic provider fixture freezes four synthetic capability IDs and proves a real deterministic process-to-artifact success path plus bounded resolution, lifecycle, and protocol outcomes without sibling source, ambient environment, network access, or an external service.

Run the reference example with:

cargo run --example hermetic_extension --locked
cargo run --example hermetic_process_transport --locked
cargo run --example scenario_manifest --locked
cargo test --test hermetic_provider_kit --locked
cargo test --test durable_state --locked

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 terminal-consistency checks. It does not authenticate the caller-issued configuration digest, authorization ID, or grants digest; the caller still owns configuration canonicalization and authorization issuance. Diagnostics marked redacted: false and other invalid provider evidence are retained only on ExecutionError and never reach the caller's EventSink or a ValidatedExecution. A redacted: true value remains a provider assertion; this checkpoint does not content-scan diagnostics or sanitize unrestricted contract strings.

ValidatedExecution does not imply artifact acceptance. observe_artifacts returns an opaque Flow-observation token after root, path, link, node, digest, and directory-manifest checks. accept_artifacts then requires a complete produced/reused result and exact agreement among the resolution, invocation, bindings, host observations, result IDs, and artifact-produced events before it returns AcceptedArtifactSet.

Process-mode ValidatedExecution additionally requires MatchedExecutionSubjects, an opaque token created only after Flow observes the locked package directory and executable file and both SHA-256 identities match exactly. This proves content equality to the supplied operator lock for that invocation. It does not prove a publisher signature, authentic publisher identity, transparency-log inclusion, trustworthy operator policy, or that a later launcher opened the same unchanged file object.

Process mode also requires AuthorizedProcess, an opaque token constructed only after an exact authority profile and host-enforcement statement agree with the resolution, invocation, operator grants, trust, and freshly matched subjects. The profile makes argv, secret handles, resource allowlists, denied ambient authority, and isolation explicit. For sandboxed, every dimension must be reported enforced exactly as requested. This evidence is caller-attested; it does not prove that a sandbox ran.

Only trusted candidates may use the unconfined in-process seam. A sandboxed process candidate may resolve only to the downstream authority/isolation gate. Orchestrator either executes a caller-injected in-process port or validates a caller-supplied process transcript. In-process limits remain correlated metadata only. The pure process-transcript seam checks caller-supplied stdout/stderr byte counts and completion evidence. LocalProcessRunner supplies the real bounded direct-child lifecycle for trusted-unconfined only. It does not provide filesystem/network containment, descendant cleanup, descriptor-bound launch, or a sandbox.

Architecture

• Architecture map
• Suite system model
• Suite structural architecture
• Decision index
• Suite boundaries
• Federated extension contract
• Process transport contract
• Bounded local process runner
• Execution-subject integrity
• Process authority and isolation
• Artifact binding contract
• Scenario fixture contract
• Executable acceptance matrix
• Durable lifecycle scenarios and recovery evidence
• Hermetic provider kit
• Versioned contracts
• Roadmap

The .agents/ directory contains the repository-local Aether specifications, skills, agents, templates, and validators used to maintain these documents.

Status

As inspected on October 22, 2026, at source aadf053d48ce8826ee5b9ca4a134985f4e7910e3, Flow has a merged durable library kernel, synthetic acceptance/lifecycle infrastructure, and a native read-only Optiflow v0.1.1 adapter. The saved-receipt repair is complete in #81 / PR #84.

The supported product CLI (#53), released Aniflow/Renderflow adapters (#51, #52), installed workflows and Flow's first release (#54) remain separate work. Cargo.toml is not publishable; its only binary is the synthetic conformance provider. There is no published Flow GitHub release at this observation. The capability matrix distinguishes provider source, immutable releases and platform qualification.

Use the current handoff for one continuation route; after this documentation checkpoint, the roadmap's next issue is #15 — observability, privacy and streams. The first installed candidate, stable audited suite and optional product backlog remain different finish lines. The proposed temporal restore-and-assess workflow is not delivered by the library foundations alone.

The #81 validation receipt records focused Linux/Rust 1.85.0 checks and actual pinned native execution. Full-suite and moving-stable qualification remain in #34. Synthetic providers do not qualify the remaining real integrations. The process seam still lacks publisher authentication, an operating-system sandbox, authenticated host evidence, descriptor-bound launch and process-tree containment. The scenario contract is not a general runtime executor. ADR-0011/0012/0013 remain proposed pending human review in the decision index.

License

MIT