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

[szmyty]

Parent checkpoint: #25
Product parent: #3
Suite roadmap: #11
Depends on: #23 / merged PR #24

Outcome

Freeze and prove the first dependency-unlocking slice of Flow's external-process boundary: deterministic stdio framing and transcript validation that reuse the existing extension invocation, event, result, and ValidatedExecution semantics.

This child exists because #25 combines several independently reviewable trust boundaries. This issue covers framing and host-neutral transcript validation only. Later children retain artifact binding, executable/package verification, authority profiles, and actual process enforcement.

Wire contract

• Flow writes exactly one compact UTF-8 JSON flow.extension-invocation/v1 document followed by LF to provider stdin.
• Provider stdout contains zero or more UTF-8 JSON Lines flow.extension-event/v1 documents, followed by exactly one flow.extension-result/v1 document and LF.
• The terminal result is the final stdout frame. EOF is required after it.
• schema_version is the discriminator; unknown or missing versions fail closed.
• LF and CRLF input are accepted deterministically. Blank frames, BOMs, invalid UTF-8, pretty-printed multiline JSON, and an unterminated final frame are invalid.
• Provider stdout is protocol-only. Stderr is opaque, bounded operational evidence and never parsed as authoritative output.
• JSON whitespace and stream chunking are transport details, not execution identity.
• Process fallback remains forbidden after invocation begins.

Scope

• Add a pure framing/decoding module over caller-supplied transcript bytes; do not spawn a process.
• Add deterministic request encoding after process-mode preflight.
• Add transcript validation that:
  • enforces stdout/stderr limits;
  • requires normal exit code zero;
  • classifies timeout and cancellation distinctly;
  • rejects malformed ordering, missing/duplicate results, frames after the result, and partial frames;
  • feeds decoded events through the existing Flow-owned event validator and caller EventSink;
  • applies the existing terminal-result validation; and
  • constructs ValidatedExecution only after every check passes.
• Refactor common preflight/evidence validation narrowly so in-process and process paths share identity, capability, configuration, authorization, limit, event, result, and telemetry-neutral semantics.
• Add a hermetic process-transcript example and deterministic adversarial tests.
• Update architecture, integration, contract, README, CI example coverage, and roadmap evidence honestly.

Typed failures

Represent at least:

• protocol/framing;
• stdout or stderr limit;
• nonzero exit or missing portable exit code;
• timeout;
• cancellation;
• invalid event;
• event-sink rejection; and
• invalid terminal result.

Do not include raw stdout/stderr bytes in error display, portable evidence, or telemetry automatically. The caller retains the original transcript.

Acceptance criteria

• Request encoding is deterministic, compact UTF-8 JSON plus exactly one LF, and does not define execution identity.
• Decoding is independent of caller read-chunk boundaries.
• LF and CRLF transcripts with equivalent documents validate identically.
• Blank, malformed, invalid UTF-8, unknown/missing-schema, invocation-on-stdout, partial, duplicate-result, post-result, and missing-result transcripts fail explicitly.
• Exact stdout/stderr limits pass and one-byte-over limits fail before semantic acceptance.
• Nonzero exit, signal/no portable exit code, timeout, and forced cancellation cannot produce ValidatedExecution, even with a provider-reported success.
• A graceful provider-cancelled event/result followed by exit zero remains valid provider evidence.
• Duplicate/decreasing events and mismatched terminal identities fail through the existing Flow-owned validators.
• Observer configuration cannot change selection, process preflight, or result identity. A rejecting fallible EventSink rejects execution without fallback.
• ValidatedExecution remains privately constructible and no malformed transcript can obtain it.
• No new runtime dependency, sibling dependency, filesystem dependency, network access, process spawning, or sandbox claim is introduced.
• Documentation states stdout/stderr ownership, EOF/exit behavior, sensitive raw-evidence handling, and all deferred enforcement honestly.
• Rust 1.85, stable Rust, examples, packaging, and repository validators pass.

Validation

cargo fmt --all -- --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-targets --locked
cargo test --doc --locked
cargo run --example hermetic_extension --locked
cargo run --example hermetic_process_transport --locked
cargo package --locked
python3 tools/validate_contracts.py
python3 .agents/specs/validate-specs.py
python3 .agents/skills/validate-skills.py
python3 .agents/agents/validate-agents.py
git diff --check

Non-goals

• A production child-process launcher or signal implementation.
• Artifact locators, directory canonicalization, or output acceptance.
• Executable/package hashing, signature verification, publisher authentication, or transparency logs.
• Enforceable sandbox, authority backend, or host filesystem/network/process isolation.
• A real holon adapter or public Flow CLI.
• Durable state, retry, checkpoints, interruption, or resume.
• Logging or OpenTelemetry implementation.
• Cross-repository source imports or unrelated cleanup.

Follow-up ordering

1. Add immutable artifact bindings and Flow-owned output acceptance.
2. Add exact package/executable subjects plus digest verification and trust evidence.
3. Add authority/execution-profile contracts and a bounded process runner.
4. Add the first real Aniflow adapter.

Roadmap-Step: FLO-Q02