From 7a50da55d9f9490ddc5be40839669ca0599bed9f Mon Sep 17 00:00:00 2001
From: Alan Szmyt <szmyty@gmail.com>
Date: Wed, 16 Sep 2026 07:58:37 -0400
Subject: [PATCH 1/2] feat(core): bootstrap deterministic extension seam

Add closed v1 extension models, deterministic catalog resolution, and a hermetic injected execution port with CI coverage.

Roadmap-Step: FLO-Q02

Closes #23
---
 .github/workflows/ci.yml                      |   80 +
 .gitignore                                    |    1 +
 Cargo.lock                                    |  135 ++
 Cargo.toml                                    |   24 +
 README.md                                     |   67 +-
 ROADMAP.md                                    |   70 +-
 contracts/README.md                           |   21 +-
 .../extension-manifest.v1.example.json        |    2 +-
 docs/architecture/foundation/ARCHITECTURE.md  |   21 +-
 docs/integrations/README.md                   |   28 +
 docs/integrations/extension-contract.md       |  154 +-
 examples/hermetic_extension.rs                |  173 ++
 rust-toolchain.toml                           |    4 +
 src/catalog.rs                                |  895 +++++++++
 src/contracts.rs                              | 1788 +++++++++++++++++
 src/execution.rs                              |  494 +++++
 src/hermetic.rs                               |  179 ++
 src/lib.rs                                    |   21 +
 tests/catalog.rs                              |  650 ++++++
 tests/common/mod.rs                           |  105 +
 tests/contracts.rs                            |  238 +++
 tests/execution.rs                            |  456 +++++
 22 files changed, 5547 insertions(+), 59 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 Cargo.lock
 create mode 100644 Cargo.toml
 create mode 100644 examples/hermetic_extension.rs
 create mode 100644 rust-toolchain.toml
 create mode 100644 src/catalog.rs
 create mode 100644 src/contracts.rs
 create mode 100644 src/execution.rs
 create mode 100644 src/hermetic.rs
 create mode 100644 src/lib.rs
 create mode 100644 tests/catalog.rs
 create mode 100644 tests/common/mod.rs
 create mode 100644 tests/contracts.rs
 create mode 100644 tests/execution.rs

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..9363cde
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  rust:
+    name: Rust ${{ matrix.toolchain }}
+    runs-on: ubuntu-latest
+    env:
+      RUSTUP_TOOLCHAIN: ${{ matrix.toolchain }}
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain:
+          - "1.85.0"
+          - stable
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ matrix.toolchain }}
+          components: clippy, rustfmt
+
+      - name: Cache Cargo data
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.toolchain }}
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Lint all targets
+        run: cargo clippy --all-targets --all-features --locked -- -D warnings
+
+      - name: Test all targets
+        run: cargo test --all-targets --locked
+
+      - name: Test documentation
+        run: cargo test --doc --locked
+
+      - name: Run hermetic extension example
+        run: cargo run --example hermetic_extension --locked
+
+      - name: Verify package contents
+        run: cargo package --locked
+
+  repository-validators:
+    name: Repository validators
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Validate contracts
+        run: python3 tools/validate_contracts.py
+
+      - name: Validate architecture specifications
+        run: python3 .agents/specs/validate-specs.py
+
+      - name: Validate repository skills
+        run: python3 .agents/skills/validate-skills.py
+
+      - name: Validate repository agents
+        run: python3 .agents/agents/validate-agents.py
diff --git a/.gitignore b/.gitignore
index f5576b2..d6a442f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@ __MACOSX/
 __pycache__/
 *.pyc
 dist/
+/target/
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..a56c262
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,135 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "flow"
+version = "0.1.0"
+dependencies = [
+ "semver",
+ "serde",
+ "serde_json",
+ "thiserror",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12df2e0110f65b775f769bb17ef989067a1d931b2eb822bd4346631eeada89f9"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..077af1e
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,24 @@
+[package]
+name = "flow"
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.85"
+description = "Deterministic orchestration contracts and extension seams for the Ego Hygiene suite"
+license = "MIT"
+repository = "https://github.com/egohygiene/flow"
+publish = false
+
+[dependencies]
+semver = "1.0.26"
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.140"
+thiserror = "2.0.12"
+
+[dev-dependencies]
+
+[lints.rust]
+unsafe_code = "forbid"
+
+[lints.clippy]
+all = "warn"
+pedantic = "warn"
diff --git a/README.md b/README.md
index 1850b26..43e2335 100644
--- a/README.md
+++ b/README.md
@@ -16,10 +16,57 @@ 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.
 
-This repository is currently architecture-first. It intentionally contains no
-copied holon source or working orchestrator yet. The approved suite boundaries,
-dependency directions, and first orchestration slice are recorded in the
-[roadmap](ROADMAP.md) and [integration contracts](docs/integrations/README.md).
+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.
+
+## Executable checkpoint
+
+The first executable checkpoint is deliberately library-only:
+
+- 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; 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
+```
+
+`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.
+
+`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.
+
+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.
 
 ## Architecture
 
@@ -37,11 +84,13 @@ skills, agents, templates, and validators used to maintain these documents.
 
 ## Status
 
-Flow is in the **contract and adapter definition** phase. 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;
-Flow will compose named releases through public libraries or versioned CLI
-contracts and will not import sibling source.
+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.
 
 ## License
 
diff --git a/ROADMAP.md b/ROADMAP.md
index dd9e257..5150542 100644
--- 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: 0.3.0
+version: 0.4.0
 status: draft
 owners:
   - egohygiene
 created: 2026-08-13
-updated: 2026-09-12
+updated: 2026-09-16
 governed_by:
   - architecture-roadmap
 depends_on:
@@ -30,22 +30,27 @@ repository: egohygiene/flow
 visibility: public
 publication: central
 route: /roadmap/flow/
-updated: 2026-09-12
+updated: 2026-09-16
 -->
-## 2026-09-12 execution snapshot
+## 2026-09-16 execution snapshot
 
 > This evidence-reconciled snapshot is the issue-generation and visual-roadmap handoff. The longer-horizon strategy below remains canonical context; generated HTML, JSON, progress, issue plans, and commit lists are projections.
 
-**Lifecycle:** contract and architecture prototype  
-**Current gate:** Freeze Flow #7's federated extension contract before final
-provider SDK mappings, then add CI and a minimal executable orchestrator.
+**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.
+
 **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 and contract source only; no executable release or Pages publication observed.
+**Current publication evidence:** Architecture, contract source, and the Flow
+#23 executable-core candidate; 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.
 
@@ -77,7 +82,7 @@ issues: []
 id: FLO-Q02
 status: active
 depends_on: [FLO-Q01]
-issues: [7]
+issues: [7, 23]
 -->
 #### FLO-Q02 — Freeze extension seams and create a tested executable core
 
@@ -93,13 +98,21 @@ 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.
-- [ ] A runnable command or library path exists.
+- [x] A runnable library path and hermetic example exist in the Flow #23
+  candidate revision.
 - [ ] Default-branch CI proves success and failure behavior.
 
 **Current evidence:**
 
 - Flow #7 defines the extension/trust schemas, synthetic fixtures, and
-  compatibility outcomes. No executable orchestrator or CI is claimed.
+  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.
 
 <!-- roadmap-step
 id: FLO-Q03
@@ -179,10 +192,12 @@ issues: []
 
 ## Strategic context
 
-Flow begins with three independently released Rust tools and no suite
-orchestrator implementation. 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.
+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
+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.
 
 This roadmap advances on capability evidence rather than dates.
 
@@ -205,13 +220,34 @@ sibling dependency is permitted.
 
 Use provider-owned manifests plus Flow-owned locks, invocation/event/result
 envelopes, and deterministic resolution evidence. In-process libraries and
-bounded processes share semantic contracts; only the operator lock grants
-permissions, precedence, or fallback.
+future bounded process adapters share semantic contracts; only the operator
+lock grants permissions, precedence, or fallback.
 
 **Exit evidence:** the contract set validates compatible, incompatible,
 over-permissioned, duplicate, malformed, and fallback fixtures; content-changing
 hooks produce immutable artifacts; observer hooks remain read-only.
 
+### Bootstrap the executable library seam
+
+Implement deterministic inspection and resolution from explicit manifests,
+operator locks, and caller observations. Invoke only a matching,
+caller-injected in-process port and return success only after Flow validates the
+ordered events and terminal result. Keep observation through `EventSink`
+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.
+
 ### Pin the capability matrix
 
 Reinspect each provider at named released revisions. Record available public
diff --git a/contracts/README.md b/contracts/README.md
index bdbfcd7..03757b1 100644
--- a/contracts/README.md
+++ b/contracts/README.md
@@ -11,7 +11,7 @@ family. Provisional means versioned and testable, not stable for production.
 | `flow.compatibility/v1` | deterministic compatibility decision and evidence |
 | `flow.extension-manifest/v1` | provider identity, integrity, compatibility, capabilities, requested permissions, hooks, and checkpoint behavior |
 | `flow.extension-lock/v1` | operator-controlled discovery pins, trust, grants, precedence, and fallback |
-| `flow.extension-invocation/v1` | immutable inputs, effective authorization, execution bounds, and resume references |
+| `flow.extension-invocation/v1` | immutable inputs, authorization identity, declared execution-limit metadata, and resume references |
 | `flow.extension-event/v1` | ordered lifecycle progress, diagnostics, artifacts, checkpoints, and state |
 | `flow.extension-result/v1` | partial/final outcomes, failures, validation, provenance, and explanation |
 | `flow.extension-resolution/v1` | deterministic selection, rejection, conflict, and fallback evidence |
@@ -26,12 +26,31 @@ The extension contracts are described in
 Provider manifests request behavior; only the operator-controlled lock grants
 authority, precedence, or fallback.
 
+`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
+unsatisfied requirements are explicit compatibility failures and are never
+silently weakened.
+
 Flow adapters translate provider-native documents into these contracts. Provider
 repositories do not depend on this directory. Breaking changes require a new
 major schema identifier; additive compatible changes increment the contract-set
 semantic version. Consumers reject unknown major identifiers and never silently
 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.
+
+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.
+
 Validate the set with:
 
 ```console
diff --git a/contracts/examples/extension-manifest.v1.example.json b/contracts/examples/extension-manifest.v1.example.json
index 7c01060..a6f36af 100644
--- a/contracts/examples/extension-manifest.v1.example.json
+++ b/contracts/examples/extension-manifest.v1.example.json
@@ -11,7 +11,7 @@
     "value": "1111111111111111111111111111111111111111111111111111111111111111"
   },
   "compatibility": {
-    "flow_version_requirement": ">=0.1.0 <0.2.0",
+    "flow_version_requirement": ">=0.1.0, <0.2.0",
     "contract_families": [
       "flow.artifact/v1",
       "flow.extension-invocation/v1",
diff --git a/docs/architecture/foundation/ARCHITECTURE.md b/docs/architecture/foundation/ARCHITECTURE.md
index 58d0174..07fe21d 100644
--- 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.3.0
+version: 0.3.1
 status: draft
 owners:
   - egohygiene
 created: 2026-08-13
-updated: 2026-09-12
+updated: 2026-09-16
 governed_by:
   - architecture-architecture
 depends_on:
@@ -152,9 +152,15 @@ not require a shared workspace toolchain.
 arrangement that realizes it. Holon architecture files refine their private
 structure without overriding suite dependency rules.
 
-## Assumptions and evidence gaps
+## Current implementation boundary
 
-No Flow implementation exists yet. Proposed units are constraints for adapter
+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.
 
 ## Open questions
@@ -165,5 +171,8 @@ and orchestration work, not claims about current source layout.
 
 ## Validation
 
-CI will eventually enforce forbidden dependency edges, CLI-thinness, schema
-compatibility, and contract tests for both library and subprocess integration.
+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.
diff --git a/docs/integrations/README.md b/docs/integrations/README.md
index d377718..7fb655f 100644
--- a/docs/integrations/README.md
+++ b/docs/integrations/README.md
@@ -16,3 +16,31 @@ implementations.
 
 These documents are governed by
 [ADR-0004](../architecture/governance/decisions/ADR-0004-federated-suite-contracts.md).
+
+## Implementation status
+
+The FLO-Q02 candidate implements only the in-process library seam described by
+the extension contract. It validates closed extension-v1 models, resolves one
+capability from explicit caller input, invokes a caller-supplied
+`ExtensionPort`, and validates correlated events and the terminal result. The
+included reference port is hermetic and produces no effects or artifacts.
+
+Only lock entries with `trusted` trust are resolution-eligible, and
+`Orchestrator` executes only a caller-injected in-process port. `sandboxed`
+entries fail closed because this checkpoint has no enforceable sandbox backend.
+A `ValidatedExecution` proves closed-contract and correlation checks, not the
+authenticity of a caller-issued configuration digest, authorization ID, or
+grants digest. The caller owns configuration canonicalization and authorization
+issuance.
+
+Declared limits are validated and identity-correlated metadata only: the
+injected in-process code has no Flow-owned timeout, cancellation, output-bound,
+panic-isolation, filesystem/network, or other side-effect enforcement.
+
+The following remain deferred: provider discovery from the filesystem, dynamic
+loading, process transport and sandboxing, real Aniflow/Optiflow/Renderflow
+adapters, artifact locator and domain-output validation, a public CLI, durable
+plans and run state, cancellation, checkpoints, and resume. `EventSink` is an
+observation attachment point for future logging and OpenTelemetry adapters; it
+is not a shipped telemetry backend and cannot affect resolution or execution
+identity. Its fallible `emit` can reject the checkpoint execution.
diff --git a/docs/integrations/extension-contract.md b/docs/integrations/extension-contract.md
index dc36b8d..16a23e5 100644
--- a/docs/integrations/extension-contract.md
+++ b/docs/integrations/extension-contract.md
@@ -4,8 +4,11 @@
 
 This contract defines how Flow discovers, resolves, authorizes, invokes, and
 records independently released extensions. It is the reusable substrate for
-Flow issue #7. Product orchestration, a real two-holon vertical slice, and
-runtime CLI commands belong to Flow issue #3.
+Flow issue #7. Flow issue #23 implements a bounded subset as a Rust library:
+deterministic resolution plus one injected, trusted in-process execution seam
+proven with a hermetic reference port. Product orchestration, real provider
+adapters, a two-holon vertical slice, and runtime CLI commands remain work for
+Flow issue #3 and its later children.
 
 An extension is an independently versioned provider package. It can expose one
 or more Aniflow, Optiflow, Renderflow, Flow, or third-party domain capabilities
@@ -26,7 +29,7 @@ locations and never executes a binary merely because it is on `PATH`.
 
 ## Lifecycle
 
-The normative lifecycle is:
+The target lifecycle is:
 
 `discover → inspect → plan → authorize → execute → validate → commit evidence`
 
@@ -49,8 +52,14 @@ success field is evidence, not suite completion.
 - `extension_id`, semantic version, and publisher identify the package.
 - SHA-256 identifies the exact installed package bytes.
 - Required Flow versions and contract families are explicit.
+- `flow_version_requirement` uses the Rust `semver` crate's comma-separated
+  comparator syntax. For example, `>=0.1.0, <0.2.0` is valid; the
+  whitespace-separated form `>=0.1.0 <0.2.0` is not.
 - Unknown major contracts and invalid version ranges are rejected without
   downgrade.
+- The executable checkpoint requires the
+  `flow.extension-invocation/v1`, `flow.extension-event/v1`, and
+  `flow.extension-result/v1` runtime families.
 - Capability IDs are globally qualified and name one primary domain owner.
 - The lock must match the inspected identity, version, publisher, and digest.
 
@@ -63,6 +72,12 @@ requested effects. The invocation records the effective configuration digest.
 Provider-native domain types remain authoritative inside the holon; Flow
 adapters translate only the released boundary.
 
+In issue #23, the caller constructs the invocation and owns configuration
+canonicalization, its digest, authorization issuance, the authorization ID, and
+the grants digest. Flow validates their shape and correlates fields repeated in
+provider evidence; it does not recompute or authenticate those caller-issued
+identities.
+
 Inputs and outputs cross the suite boundary as immutable artifact references.
 Any content-changing operation produces a new artifact identity and lineage.
 
@@ -70,15 +85,47 @@ Any content-changing operation produces a new artifact identity and lineage.
 
 - **In-process:** a version-pinned public library entry point. Flow still binds
   it to the invocation, event, result, authorization, and provenance contracts.
-- **Process:** a version-pinned executable invoked directly with argv. Flow
-  independently captures stdout/stderr, enforces timeout, output bounds,
-  cancellation grace, permissions, and declared outputs, and never parses human
-  console text as a contract.
+- **Process (future target):** a version-pinned executable invoked directly
+  with argv. A future process adapter must independently capture stdout/stderr,
+  enforce timeout, output bounds, cancellation grace, permissions, and declared
+  outputs, and never parse human console text as a contract.
 
 Both modes must produce the same structured semantic result. Flow may choose
 process isolation when toolchains, licensing, trust, or failure containment make
 an in-process edge unsuitable.
 
+The current executable checkpoint resolves only `trusted` candidates and proves
+only a caller-injected in-process library port. It performs no filesystem
+discovery, dynamic loading, external process invocation, executable integrity
+verification, or sandbox enforcement. `sandboxed` candidates fail closed.
+Declared limits are validated and correlated with the resolved mode as policy
+metadata only; Flow does not enforce a timeout, cancellation, stdout/stderr
+bound, panic isolation, filesystem/network containment, or any other side
+effect on the injected code. The process behavior above remains a future
+contract target, not a claim about the implemented runtime.
+
+## Observation and telemetry
+
+The orchestrator wraps the caller's `EventSink` with Flow-owned validation.
+Only provider events whose schema, identities, unique event ID, and strictly
+increasing sequence pass validation reach the caller sink. The sink is the
+intended attachment point for future human logging, structured logging,
+tracing, metrics, or OpenTelemetry adapters.
+
+Diagnostics marked `redacted: false` in events or terminal results are
+rejected. A `redacted: true` value remains a provider assertion: this
+checkpoint does not content-scan diagnostics or sanitize unrestricted contract
+strings such as result explanations, validation evidence, provenance values,
+or artifact, checkpoint, and event references. Rejected raw evidence remains
+available through `ExecutionError`, but it is never forwarded to the caller
+sink or returned in `ValidatedExecution`.
+
+Observations are deliberately outside resolution and execution identity. A
+sink cannot select an extension, directly mutate provider evidence, or grant
+authority. `EventSink::emit` is fallible and its error is visible to the
+provider; rejection makes `Orchestrator` return `ExecutionError`. This
+checkpoint includes neither a logging backend nor an OpenTelemetry exporter.
+
 ## Permissions and trust
 
 The manifest requests filesystem reads/writes, environment names, subprocesses,
@@ -87,23 +134,57 @@ signing, and publication. The lock grants a subset and selects `trusted`,
 `sandboxed`, or `disabled` operation. No grant is implied by capability
 selection.
 
-Secrets are referenced through runtime handles and never serialized. Absolute
-paths, credentials, tokens, prompts containing private content, and raw
-unredacted diagnostics do not enter portable evidence.
+Issue #23 makes only `trusted` candidates resolution-eligible, while
+`Orchestrator` accepts only a caller-injected in-process port. It marks
+`sandboxed` candidates unauthorized and unavailable because it has no
+enforceable sandbox backend; `disabled` candidates also fail closed.
+
+Secrets are referenced through runtime handles. Providers and callers are
+responsible for keeping credentials, tokens, private prompt content, and other
+sensitive values out of portable evidence. `discovery.location` is arbitrary
+and may be absolute, so manifests, locks, and resolution inputs must be handled
+according to their actual sensitivity. Issue #23 checks the diagnostic
+`redacted` flag only; it does not verify the provider's `true` assertion,
+inspect diagnostic content, or sanitize other contract strings. Raw
+`ExecutionError` events and results are sensitive, nonportable evidence and
+must not be exported without caller-controlled inspection and redaction.
 
 ## Replacement, conflict, and fallback
 
 An extension may declare replacement intent or fallback eligibility, but the
 lock owns effective precedence. Resolution is deterministic:
 
-1. Reject malformed, incompatible, disabled, integrity-mismatched, and
-   over-permissioned candidates.
-2. Apply domain ownership and capability compatibility.
-3. Apply operator precedence.
-4. Fail unresolved equal-precedence conflicts.
-5. Record every rejected candidate and reason.
-6. Use fallback only when the selected provider is unavailable and the plan
-   explicitly permits fallback; never silently after partial side effects.
+1. Fail resolution atomically when a manifest is semantically malformed, with
+   top-level reasons because resolution-v1 cannot represent that candidate
+   without fabricating required evidence.
+2. For each well-formed candidate, retain compatibility, authorization,
+   availability, precedence, and failed-check reasons.
+3. Apply domain ownership and capability compatibility.
+4. Apply operator precedence.
+5. Fail unresolved equal-precedence conflicts.
+6. Use fallback only when a higher-priority or preferred provider is
+   unavailable before invocation and the plan explicitly permits fallback;
+   never after `ExtensionPort::invoke` begins.
+
+When fallback policy forbids an otherwise technically compatible lower
+candidate, resolution retains `compatible: true` and records
+`authorized: false`; operator policy does not rewrite technical compatibility.
+
+Selection uses a unique highest numeric precedence. `fallback_order` preserves
+the lock's `ordered_extensions` policy order as resolution evidence; it does
+not enable fallback after `ExtensionPort::invoke` begins.
+
+Rust semantic validation requires each lock `ordered_extensions` list to follow
+non-increasing locked precedence. JSON Schema alone does not express this
+ordering invariant.
+
+An entirely empty manifest catalog produces `no-compatible-provider`. If at
+least one enabled, `trusted` lock entry listed by the requested policy is
+represented by a manifest with exactly matching extension ID, version,
+publisher, and integrity, every such entry must have an exact lock-matching
+manifest. A partial or substituted set produces an atomic `malformed` outcome
+with no candidate evidence. This prevents caller omission or pin substitution
+from bypassing preferred-provider or fallback policy.
 
 ## Hooks
 
@@ -138,10 +219,33 @@ Synthetic examples and compatibility fixtures cover all three holon domains and
 explicit compatible, incompatible, over-permissioned, duplicate, and malformed
 outcomes. They contain no Ego Hygiene publication content.
 
-## Deferred runtime proof
-
-This issue freezes the reusable data and policy boundary. `extensions list`,
-`extensions inspect`, `doctor`, provider adapters, interruption/resume execution,
-and the cross-holon vertical slice are implementation work for Flow #3 after the
-required holon contracts are available as releases or versioned process
-envelopes.
+## Current proof and deferred runtime
+
+Issue #23 adds a library-only proof: closed extension-v1 models, semantic
+validation, deterministic single-capability resolution, one injected
+`ExtensionPort`, correlated event/result validation, and a no-effects,
+no-artifacts hermetic reference port. The proof does not promote an extension's
+terminal success report to a validated execution until Flow-owned checks pass.
+
+Those checks prove contract validity and correlation only. They do not prove
+the authenticity of the caller-issued configuration digest, authorization ID,
+or grants digest, nor do they enforce the declared execution limits or contain
+side effects from the trusted injected code.
+
+For terminal evidence, `produced` and `reused` require every reported
+validation to be `passed`; `skipped` permits `passed` or `not-run` but rejects
+`failed`. Outcome, failure classification, and failure payload must also be
+coherent.
+
+Artifact handling is identifier self-consistency only. Invocation input IDs
+must be unique, result `consumed_artifacts` must be a subset of those IDs, and
+references on `artifact-produced` events must appear in terminal
+`produced_artifacts`; generic event references remain unrestricted. This does
+not bind identifiers to locators, recompute or verify artifact digests or
+bytes, establish artifact existence, or perform domain-output validation.
+
+`extensions list`, `extensions inspect`, `doctor`, process transport, sandbox
+enforcement, real provider adapters, interruption/cancellation, durable run
+state, checkpoints/resume, and the cross-holon vertical slice remain deferred
+work for Flow #3 after the required holon contracts are available as releases
+or versioned process envelopes.
diff --git a/examples/hermetic_extension.rs b/examples/hermetic_extension.rs
new file mode 100644
index 0000000..d3990a1
--- /dev/null
+++ b/examples/hermetic_extension.rs
@@ -0,0 +1,173 @@
+use std::collections::BTreeMap;
+
+use flow::{
+    Authorization, Configuration, Domain, EXTENSION_INVOCATION_V1, ExecutionModeKind,
+    ExtensionCatalog, ExtensionInvocation, ExtensionLock, ExtensionManifest, ExtensionObservation,
+    HermeticExtension, InvocationExtension, InvocationInterface, InvocationPhase, Orchestrator,
+    PortIdentity, ResolutionRequest,
+};
+
+const CONFIG_DIGEST: &str = "2222222222222222222222222222222222222222222222222222222222222222";
+const GRANTS_DIGEST: &str = "3333333333333333333333333333333333333333333333333333333333333333";
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let manifest: ExtensionManifest = serde_json::from_str(MANIFEST)?;
+    let lock: ExtensionLock = serde_json::from_str(LOCK)?;
+    let observation = ExtensionObservation::new(
+        manifest.extension_id.clone(),
+        manifest.version.clone(),
+        manifest.publisher.id.clone(),
+        manifest.integrity.clone(),
+        true,
+    );
+    let catalog = ExtensionCatalog::inspect([manifest], lock, [observation])?;
+    let resolution = catalog.resolve(&ResolutionRequest::new(
+        "hermetic-example",
+        "flow/hermetic-check",
+        Domain::Flow,
+        "hermetic-library",
+        ExecutionModeKind::InProcess,
+    ));
+    let resolved = resolution
+        .resolved()
+        .ok_or("the hermetic extension did not resolve")?;
+    let invocation = ExtensionInvocation {
+        schema_version: EXTENSION_INVOCATION_V1.to_owned(),
+        invocation_id: "invocation:hermetic-example".to_owned(),
+        run_id: "run:hermetic-example".to_owned(),
+        phase: InvocationPhase::Execute,
+        extension: InvocationExtension {
+            extension_id: resolved.extension_id().to_owned(),
+            version: resolved.version().to_owned(),
+            publisher_id: resolved.publisher_id().to_owned(),
+            integrity: resolved.integrity().value.clone(),
+        },
+        capability_id: resolved.capability().capability_id.clone(),
+        interface: InvocationInterface {
+            kind: resolved.execution_mode().kind,
+            name: resolved.execution_mode().name.clone(),
+            protocol: EXTENSION_INVOCATION_V1.to_owned(),
+        },
+        input_artifacts: Vec::new(),
+        expected_output_types: Vec::new(),
+        configuration: Configuration {
+            schema_id: resolved.capability().configuration_schema.clone(),
+            digest: CONFIG_DIGEST.to_owned(),
+            values: BTreeMap::new(),
+        },
+        authorization: Authorization {
+            authorization_id: "authorization:hermetic-example".to_owned(),
+            lock_id: resolved.lock_id().to_owned(),
+            grants_digest: GRANTS_DIGEST.to_owned(),
+        },
+        limits: resolved.execution_mode().limits.clone(),
+        checkpoint_refs: Vec::new(),
+        secret_handles: Vec::new(),
+        cancellation_id: "cancel:hermetic-example".to_owned(),
+    };
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved));
+    let mut observed = Vec::new();
+    let execution = Orchestrator::execute(resolved, &invocation, &port, &mut observed)?;
+    println!(
+        "{} selected {}; validated {} events with outcome {:?}",
+        resolution.evidence().case_id,
+        resolved.extension_id(),
+        execution.events().len(),
+        execution.result().outcome
+    );
+    Ok(())
+}
+
+const MANIFEST: &str = r#"
+{
+  "schema_version": "flow.extension-manifest/v1",
+  "extension_id": "org.egohygiene.hermetic",
+  "version": "0.1.0",
+  "publisher": { "id": "org.egohygiene", "display_name": "Ego Hygiene" },
+  "integrity": { "algorithm": "sha256", "value": "1111111111111111111111111111111111111111111111111111111111111111" },
+  "compatibility": {
+    "flow_version_requirement": ">=0.1.0, <0.2.0",
+    "contract_families": [
+      "flow.extension-invocation/v1",
+      "flow.extension-event/v1",
+      "flow.extension-result/v1"
+    ]
+  },
+  "inspection": {
+    "version_source": "manifest",
+    "capability_source": "manifest",
+    "health_mode": "manifest-only",
+    "health_capability_ids": []
+  },
+  "domain_ownership": ["flow"],
+  "capabilities": [{
+    "capability_id": "flow/hermetic-check",
+    "domain": "flow",
+    "configuration_schema": "flow.hermetic/v1",
+    "accepts": [],
+    "produces": [],
+    "preconditions": [],
+    "postconditions": [],
+    "deterministic": true,
+    "cacheable": false,
+    "loss": "none",
+    "content_changes": false,
+    "effects": []
+  }],
+  "execution_modes": [{
+    "name": "hermetic-library",
+    "kind": "in-process",
+    "protocol": "flow.extension-invocation/v1",
+    "entrypoint": "flow::HermeticExtension",
+    "limits": {
+      "timeout_ms": 1000,
+      "max_stdout_bytes": 0,
+      "max_stderr_bytes": 0,
+      "cancellation_grace_ms": 0
+    }
+  }],
+  "requested_permissions": {
+    "filesystem_read": [], "filesystem_write": [], "environment_read": [],
+    "subprocesses": [], "network_hosts": [], "ai_providers": [],
+    "gpu": false, "source_mutation": false, "destructive": false,
+    "sign": false, "publish": false
+  },
+  "checkpoint": {
+    "mode": "none",
+    "contract_family": "flow.extension-result/v1",
+    "compatibility_keys": []
+  },
+  "replacement": { "replaces": [], "fallbacks_for": [] },
+  "observer_hooks": [],
+  "transform_hooks": []
+}
+"#;
+
+const LOCK: &str = r#"
+{
+  "schema_version": "flow.extension-lock/v1",
+  "flow_version": "0.1.0",
+  "lock_id": "lock:hermetic-example",
+  "extensions": [{
+    "extension_id": "org.egohygiene.hermetic",
+    "version": "0.1.0",
+    "publisher_id": "org.egohygiene",
+    "integrity": { "algorithm": "sha256", "value": "1111111111111111111111111111111111111111111111111111111111111111" },
+    "discovery": { "kind": "embedded", "location": "flow::HermeticExtension" },
+    "enabled": true,
+    "trust": "trusted",
+    "granted_permissions": {
+      "filesystem_read": [], "filesystem_write": [], "environment_read": [],
+      "subprocesses": [], "network_hosts": [], "ai_providers": [],
+      "gpu": false, "source_mutation": false, "destructive": false,
+      "sign": false, "publish": false
+    },
+    "precedence": 100
+  }],
+  "capability_resolution": [{
+    "capability_id": "flow/hermetic-check",
+    "ordered_extensions": ["org.egohygiene.hermetic"],
+    "fallback": "forbidden"
+  }]
+}
+"#;
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
new file mode 100644
index 0000000..7e18c85
--- /dev/null
+++ b/rust-toolchain.toml
@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.85.0"
+components = ["clippy", "rustfmt"]
+profile = "minimal"
diff --git a/src/catalog.rs b/src/catalog.rs
new file mode 100644
index 0000000..67692f2
--- /dev/null
+++ b/src/catalog.rs
@@ -0,0 +1,895 @@
+//! Deterministic inspection and resolution of explicitly supplied extensions.
+
+use std::cmp::Reverse;
+use std::collections::{BTreeMap, HashSet};
+
+use semver::Version;
+use serde::{Deserialize, Serialize};
+use thiserror::Error;
+
+use crate::contracts::{
+    Capability, Domain, EXTENSION_RESOLUTION_V1, ExecutionMode, ExecutionModeKind, ExtensionLock,
+    ExtensionManifest, ExtensionResolution, FallbackPolicy, Integrity, LockedExtension,
+    ResolutionCandidate, ResolutionResult, Trust, ValidationError, contract_family_major,
+    parse_flow_version_requirement,
+};
+
+/// Caller-supplied observation of installed bytes and pre-invocation availability.
+///
+/// Observations never grant authority. They are compared with both the provider
+/// declaration and the operator lock.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionObservation {
+    pub extension_id: String,
+    pub version: String,
+    pub publisher_id: String,
+    pub integrity: Integrity,
+    pub available: bool,
+}
+
+impl ExtensionObservation {
+    #[must_use]
+    pub fn new(
+        extension_id: impl Into<String>,
+        version: impl Into<String>,
+        publisher_id: impl Into<String>,
+        integrity: Integrity,
+        available: bool,
+    ) -> Self {
+        Self {
+            extension_id: extension_id.into(),
+            version: version.into(),
+            publisher_id: publisher_id.into(),
+            integrity,
+            available,
+        }
+    }
+
+    fn key(&self) -> IdentityKey<'_> {
+        IdentityKey {
+            extension_id: &self.extension_id,
+            version: &self.version,
+            publisher_id: &self.publisher_id,
+        }
+    }
+}
+
+/// A fully explicit resolution request.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ResolutionRequest {
+    pub case_id: String,
+    pub capability_id: String,
+    pub domain: Domain,
+    pub execution_mode_name: String,
+    pub execution_mode_kind: ExecutionModeKind,
+}
+
+impl ResolutionRequest {
+    #[must_use]
+    pub fn new(
+        case_id: impl Into<String>,
+        capability_id: impl Into<String>,
+        domain: Domain,
+        execution_mode_name: impl Into<String>,
+        execution_mode_kind: ExecutionModeKind,
+    ) -> Self {
+        Self {
+            case_id: case_id.into(),
+            capability_id: capability_id.into(),
+            domain,
+            execution_mode_name: execution_mode_name.into(),
+            execution_mode_kind,
+        }
+    }
+}
+
+/// An inspected catalog whose inputs have been normalized without executing code.
+#[derive(Clone, Debug)]
+pub struct ExtensionCatalog {
+    manifests: Vec<InspectedManifest>,
+    lock: ExtensionLock,
+    observations: BTreeMap<OwnedIdentityKey, ExtensionObservation>,
+    flow_version: Version,
+}
+
+#[derive(Clone, Debug)]
+struct InspectedManifest {
+    manifest: ExtensionManifest,
+    validation_error: Option<ValidationError>,
+}
+
+#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
+struct OwnedIdentityKey {
+    extension_id: String,
+    version: String,
+    publisher_id: String,
+}
+
+#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
+struct IdentityKey<'a> {
+    extension_id: &'a str,
+    version: &'a str,
+    publisher_id: &'a str,
+}
+
+impl From<IdentityKey<'_>> for OwnedIdentityKey {
+    fn from(key: IdentityKey<'_>) -> Self {
+        Self {
+            extension_id: key.extension_id.to_owned(),
+            version: key.version.to_owned(),
+            publisher_id: key.publisher_id.to_owned(),
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+pub enum CatalogError {
+    #[error("invalid extension lock: {0}")]
+    InvalidLock(ValidationError),
+    #[error("duplicate extension manifest identity: {identity}")]
+    DuplicateManifest { identity: String },
+    #[error("duplicate extension observation identity: {identity}")]
+    DuplicateObservation { identity: String },
+}
+
+impl ExtensionCatalog {
+    /// Inspect inert inputs. This function never loads or invokes provider code.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error when the operator lock is invalid, an extension ID has
+    /// more than one manifest, or an exact observation identity is repeated.
+    pub fn inspect(
+        manifests: impl IntoIterator<Item = ExtensionManifest>,
+        lock: ExtensionLock,
+        observations: impl IntoIterator<Item = ExtensionObservation>,
+    ) -> Result<Self, CatalogError> {
+        lock.validate().map_err(CatalogError::InvalidLock)?;
+        let flow_version = Version::parse(&lock.flow_version).map_err(|error| {
+            CatalogError::InvalidLock(ValidationError::new(
+                "lock.flow_version",
+                format!("invalid semantic version: {error}"),
+            ))
+        })?;
+
+        let mut manifests: Vec<ExtensionManifest> = manifests.into_iter().collect();
+        manifests.sort_by(|left, right| manifest_sort_key(left).cmp(&manifest_sort_key(right)));
+        for pair in manifests.windows(2) {
+            if pair[0].extension_id == pair[1].extension_id {
+                return Err(CatalogError::DuplicateManifest {
+                    identity: pair[0].extension_id.clone(),
+                });
+            }
+        }
+        let manifests = manifests
+            .into_iter()
+            .map(|manifest| InspectedManifest {
+                validation_error: manifest.validate().err(),
+                manifest,
+            })
+            .collect();
+
+        let mut observations: Vec<ExtensionObservation> = observations.into_iter().collect();
+        observations.sort_by(|left, right| left.key().cmp(&right.key()));
+        for pair in observations.windows(2) {
+            if pair[0].key() == pair[1].key() {
+                return Err(CatalogError::DuplicateObservation {
+                    identity: display_identity(
+                        &pair[0].extension_id,
+                        &pair[0].version,
+                        &pair[0].publisher_id,
+                    ),
+                });
+            }
+        }
+        let normalized_observations = observations
+            .into_iter()
+            .map(|observation| {
+                let key = OwnedIdentityKey::from(observation.key());
+                (key, observation)
+            })
+            .collect();
+
+        Ok(Self {
+            manifests,
+            lock,
+            observations: normalized_observations,
+            flow_version,
+        })
+    }
+
+    /// Resolve one capability and retain complete, versioned decision evidence.
+    #[must_use]
+    #[allow(clippy::too_many_lines)]
+    pub fn resolve(&self, request: &ResolutionRequest) -> ResolutionOutcome {
+        if request.case_id.is_empty()
+            || request.capability_id.is_empty()
+            || request.execution_mode_name.is_empty()
+        {
+            return ResolutionOutcome::rejected(ExtensionResolution {
+                schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+                case_id: if request.case_id.is_empty() {
+                    "invalid-request".to_owned()
+                } else {
+                    request.case_id.clone()
+                },
+                requested_capability: if request.capability_id.is_empty() {
+                    "invalid-capability".to_owned()
+                } else {
+                    request.capability_id.clone()
+                },
+                candidates: Vec::new(),
+                result: ResolutionResult::Malformed,
+                selected_extension_ids: Vec::new(),
+                fallback_order: Vec::new(),
+                reasons: vec!["The resolution request is missing a required identity.".to_owned()],
+            });
+        }
+
+        let malformed: Vec<(&ExtensionManifest, &ValidationError)> = self
+            .manifests
+            .iter()
+            .filter_map(|candidate| {
+                candidate
+                    .validation_error
+                    .as_ref()
+                    .map(|error| (&candidate.manifest, error))
+            })
+            .collect();
+        if !malformed.is_empty() {
+            let reasons = malformed
+                .into_iter()
+                .enumerate()
+                .map(|(index, (_, error))| {
+                    format!(
+                        "Catalog resolution is atomic because resolution-v1 cannot represent a malformed candidate without fabricating evidence; candidate ordinal {} failed semantic validation at {}.",
+                        index + 1,
+                        error.path
+                    )
+                })
+                .collect();
+            return ResolutionOutcome::rejected(ExtensionResolution {
+                schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+                case_id: request.case_id.clone(),
+                requested_capability: request.capability_id.clone(),
+                candidates: Vec::new(),
+                result: ResolutionResult::Malformed,
+                selected_extension_ids: Vec::new(),
+                fallback_order: Vec::new(),
+                reasons,
+            });
+        }
+
+        let policy = self.lock.resolution_for(&request.capability_id);
+        if self.policy_is_partially_materialized(policy) {
+            return ResolutionOutcome::rejected(ExtensionResolution {
+                schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+                case_id: request.case_id.clone(),
+                requested_capability: request.capability_id.clone(),
+                candidates: Vec::new(),
+                result: ResolutionResult::Malformed,
+                selected_extension_ids: Vec::new(),
+                fallback_order: Vec::new(),
+                reasons: vec![
+                    "The requested operator policy is only partially represented by supplied manifests."
+                        .to_owned(),
+                ],
+            });
+        }
+        let mut assessed: Vec<AssessedCandidate<'_>> = self
+            .manifests
+            .iter()
+            .map(|candidate| self.assess(&candidate.manifest, request, policy))
+            .collect();
+        assessed.sort_by(|left, right| assessment_sort_key(left).cmp(&assessment_sort_key(right)));
+
+        let fallback_precedence = fallback_precedence(policy, &assessed);
+        let is_fallback = fallback_precedence.is_some();
+        let fallback_allowed =
+            policy.is_some_and(|policy| policy.fallback == FallbackPolicy::BeforeEffects);
+
+        if is_fallback && !fallback_allowed {
+            if let Some(unavailable_precedence) = fallback_precedence {
+                for candidate in &mut assessed {
+                    if candidate.eligible()
+                        && candidate.evidence.precedence <= unavailable_precedence
+                    {
+                        candidate.evidence.authorized = false;
+                        candidate.evidence.reasons.push(
+                            "Operator fallback policy forbids selecting this candidate after pre-invocation unavailability."
+                                .to_owned(),
+                        );
+                    }
+                }
+            }
+        }
+
+        let eligible: Vec<&AssessedCandidate<'_>> = assessed
+            .iter()
+            .filter(|candidate| candidate.eligible())
+            .collect();
+        let max_precedence = eligible
+            .iter()
+            .map(|candidate| candidate.evidence.precedence)
+            .max();
+        let leaders: Vec<&AssessedCandidate<'_>> =
+            max_precedence.map_or_else(Vec::new, |maximum| {
+                eligible
+                    .iter()
+                    .copied()
+                    .filter(|candidate| candidate.evidence.precedence == maximum)
+                    .collect()
+            });
+
+        let fallback_order = if is_fallback && fallback_allowed && leaders.len() == 1 {
+            fallback_order(policy, &assessed, &leaders[0].evidence.extension_id)
+        } else {
+            Vec::new()
+        };
+
+        let evidence_candidates = assessed
+            .iter()
+            .map(|candidate| candidate.evidence.clone())
+            .collect::<Vec<_>>();
+
+        if leaders.len() > 1 {
+            return ResolutionOutcome::rejected(ExtensionResolution {
+                schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+                case_id: request.case_id.clone(),
+                requested_capability: request.capability_id.clone(),
+                candidates: evidence_candidates,
+                result: ResolutionResult::Conflict,
+                selected_extension_ids: Vec::new(),
+                fallback_order: Vec::new(),
+                reasons: vec![
+                    "Multiple eligible candidates share the highest operator precedence."
+                        .to_owned(),
+                ],
+            });
+        }
+
+        if let Some(selected) = leaders.first() {
+            let (Some(locked), Some(capability), Some(execution_mode)) = (
+                selected.locked,
+                selected.capability,
+                selected.execution_mode,
+            ) else {
+                return ResolutionOutcome::rejected(ExtensionResolution {
+                    schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+                    case_id: request.case_id.clone(),
+                    requested_capability: request.capability_id.clone(),
+                    candidates: Vec::new(),
+                    result: ResolutionResult::Malformed,
+                    selected_extension_ids: Vec::new(),
+                    fallback_order: Vec::new(),
+                    reasons: vec![
+                        "An eligible candidate lacks required inspected resolution state."
+                            .to_owned(),
+                    ],
+                });
+            };
+            let resolved = ResolvedExtension {
+                manifest: selected.manifest.clone(),
+                locked: locked.clone(),
+                capability: capability.clone(),
+                execution_mode: execution_mode.clone(),
+                lock_id: self.lock.lock_id.clone(),
+                fallback_policy: policy.map_or(FallbackPolicy::Forbidden, |entry| entry.fallback),
+            };
+            let reason = if fallback_order.is_empty() {
+                "Selected the unique eligible candidate with highest operator precedence."
+            } else {
+                "The preferred provider was unavailable before invocation; selected the authorized fallback."
+            };
+            return ResolutionOutcome::selected(
+                ExtensionResolution {
+                    schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+                    case_id: request.case_id.clone(),
+                    requested_capability: request.capability_id.clone(),
+                    candidates: evidence_candidates,
+                    result: ResolutionResult::Selected,
+                    selected_extension_ids: vec![resolved.extension_id().to_owned()],
+                    fallback_order,
+                    reasons: vec![reason.to_owned()],
+                },
+                resolved,
+            );
+        }
+
+        let any_compatible = assessed
+            .iter()
+            .any(|candidate| candidate.evidence.compatible);
+        let (result, reason) = if any_compatible {
+            (
+                ResolutionResult::Blocked,
+                "Compatible candidates exist, but none is authorized and available under operator policy.",
+            )
+        } else if assessed.is_empty() {
+            (
+                ResolutionResult::NoCompatibleProvider,
+                "No manifest candidates were supplied for the requested capability.",
+            )
+        } else {
+            (
+                ResolutionResult::NoCompatibleProvider,
+                "No candidate satisfies the requested capability, domain, contract, and execution mode.",
+            )
+        };
+        ResolutionOutcome::rejected(ExtensionResolution {
+            schema_version: EXTENSION_RESOLUTION_V1.to_owned(),
+            case_id: request.case_id.clone(),
+            requested_capability: request.capability_id.clone(),
+            candidates: evidence_candidates,
+            result,
+            selected_extension_ids: Vec::new(),
+            fallback_order: Vec::new(),
+            reasons: vec![reason.to_owned()],
+        })
+    }
+
+    fn policy_is_partially_materialized(
+        &self,
+        policy: Option<&crate::contracts::CapabilityResolution>,
+    ) -> bool {
+        if self.manifests.is_empty() {
+            return false;
+        }
+        let Some(policy) = policy else {
+            return false;
+        };
+        let required_entries: Vec<&LockedExtension> = policy
+            .ordered_extensions
+            .iter()
+            .filter_map(|extension_id| self.lock.extension(extension_id))
+            .filter(|entry| entry.enabled && entry.trust == Trust::Trusted)
+            .collect();
+        let represented = required_entries
+            .iter()
+            .filter(|entry| {
+                self.manifests.iter().any(|candidate| {
+                    candidate.manifest.extension_id == entry.extension_id
+                        && candidate.manifest.version == entry.version
+                        && candidate.manifest.publisher.id == entry.publisher_id
+                        && candidate.manifest.integrity == entry.integrity
+                })
+            })
+            .count();
+        represented > 0 && represented < required_entries.len()
+    }
+
+    #[allow(clippy::too_many_lines)]
+    fn assess<'a>(
+        &'a self,
+        manifest: &'a ExtensionManifest,
+        request: &ResolutionRequest,
+        policy: Option<&crate::contracts::CapabilityResolution>,
+    ) -> AssessedCandidate<'a> {
+        let locked = self.lock.extension(&manifest.extension_id);
+        let observation = self
+            .observations
+            .get(&OwnedIdentityKey::from(manifest_identity(manifest)));
+        let mut compatible = true;
+        let mut authorized = true;
+        let mut available = true;
+        let mut reasons = Vec::new();
+
+        let flow_requirement =
+            parse_flow_version_requirement(&manifest.compatibility.flow_version_requirement);
+        match flow_requirement {
+            Ok(requirement) if requirement.matches(&self.flow_version) => {}
+            Ok(_) => {
+                compatible = false;
+                reasons.push(format!(
+                    "Flow {} does not satisfy {}.",
+                    self.flow_version, manifest.compatibility.flow_version_requirement
+                ));
+            }
+            Err(error) => {
+                compatible = false;
+                reasons.push(format!("Invalid Flow version requirement: {error}."));
+            }
+        }
+        for family in &manifest.compatibility.contract_families {
+            match contract_family_major(family) {
+                Some(1) if is_known_contract_family(family) => {}
+                Some(major) => {
+                    compatible = false;
+                    reasons.push(format!(
+                        "Unsupported or unknown contract family {family} (major {major})."
+                    ));
+                }
+                None => {
+                    compatible = false;
+                    reasons.push(format!("Malformed contract family {family}."));
+                }
+            }
+        }
+        for required_family in [
+            "flow.extension-invocation/v1",
+            "flow.extension-event/v1",
+            "flow.extension-result/v1",
+        ] {
+            if !manifest
+                .compatibility
+                .contract_families
+                .iter()
+                .any(|family| family == required_family)
+            {
+                compatible = false;
+                reasons.push(format!(
+                    "Missing required runtime contract family {required_family}."
+                ));
+            }
+        }
+
+        let capability = manifest.capability(&request.capability_id);
+        if let Some(capability) = capability {
+            if capability.domain != request.domain {
+                compatible = false;
+                reasons.push(format!(
+                    "Capability domain {} does not match requested domain {}.",
+                    capability.domain.as_str(),
+                    request.domain.as_str()
+                ));
+            }
+        } else {
+            compatible = false;
+            reasons.push("The manifest does not declare the requested capability.".to_owned());
+        }
+        let execution_mode =
+            manifest.execution_mode(&request.execution_mode_name, request.execution_mode_kind);
+        if execution_mode.is_none() {
+            compatible = false;
+            reasons.push("The requested execution mode name and kind are not declared.".to_owned());
+        }
+
+        if let Some(entry) = locked {
+            if entry.version != manifest.version {
+                compatible = false;
+                authorized = false;
+                reasons.push("Manifest and lock versions do not agree.".to_owned());
+            }
+            if entry.publisher_id != manifest.publisher.id {
+                compatible = false;
+                authorized = false;
+                reasons.push("Manifest and lock publishers do not agree.".to_owned());
+            }
+            if entry.integrity != manifest.integrity {
+                compatible = false;
+                authorized = false;
+                available = false;
+                reasons.push("Manifest and lock integrity values do not agree.".to_owned());
+            }
+            if !entry.enabled {
+                authorized = false;
+                available = false;
+                reasons.push("The operator lock disables this extension.".to_owned());
+            }
+            match entry.trust {
+                Trust::Trusted => {}
+                Trust::Sandboxed => {
+                    authorized = false;
+                    available = false;
+                    reasons.push(
+                        "Sandboxed trust requires an enforceable backend that this checkpoint does not provide."
+                            .to_owned(),
+                    );
+                }
+                Trust::Disabled => {
+                    authorized = false;
+                    available = false;
+                    reasons.push("The operator trust mode disables this extension.".to_owned());
+                }
+            }
+            if !entry
+                .granted_permissions
+                .allows(&manifest.requested_permissions)
+            {
+                authorized = false;
+                reasons
+                    .push("Requested permissions exceed the explicit operator grants.".to_owned());
+            }
+            if let Some(capability) = capability {
+                if capability
+                    .effects
+                    .iter()
+                    .any(|effect| !entry.granted_permissions.allows_effect(*effect))
+                {
+                    authorized = false;
+                    reasons
+                        .push("Capability effects exceed the explicit operator grants.".to_owned());
+                }
+            }
+        } else {
+            authorized = false;
+            available = false;
+            reasons.push("No operator lock entry authorizes this extension.".to_owned());
+        }
+
+        match policy {
+            Some(policy) if policy.ordered_extensions.contains(&manifest.extension_id) => {}
+            Some(_) => {
+                authorized = false;
+                reasons.push(
+                    "The operator capability policy does not list this extension.".to_owned(),
+                );
+            }
+            None => {
+                authorized = false;
+                reasons.push("No operator capability policy exists for this request.".to_owned());
+            }
+        }
+
+        if let Some(observation) = observation {
+            if observation.integrity != manifest.integrity
+                || locked.is_some_and(|entry| observation.integrity != entry.integrity)
+            {
+                available = false;
+                reasons.push(
+                    "Observed integrity does not match the manifest and operator lock.".to_owned(),
+                );
+            }
+            if !observation.available {
+                available = false;
+                reasons.push(
+                    "The caller reports the extension unavailable before invocation.".to_owned(),
+                );
+            }
+        } else {
+            available = false;
+            reasons.push(
+                "No caller-supplied availability and integrity observation matches this extension."
+                    .to_owned(),
+            );
+        }
+
+        let precedence = locked.map_or(0, |entry| entry.precedence);
+        AssessedCandidate {
+            manifest,
+            locked,
+            capability,
+            execution_mode,
+            evidence: ResolutionCandidate {
+                extension_id: manifest.extension_id.clone(),
+                version: manifest.version.clone(),
+                publisher_id: manifest.publisher.id.clone(),
+                integrity: manifest.integrity.value.clone(),
+                precedence,
+                compatible,
+                authorized,
+                available,
+                reasons,
+            },
+        }
+    }
+}
+
+#[derive(Clone, Debug)]
+struct AssessedCandidate<'a> {
+    manifest: &'a ExtensionManifest,
+    locked: Option<&'a LockedExtension>,
+    capability: Option<&'a Capability>,
+    execution_mode: Option<&'a ExecutionMode>,
+    evidence: ResolutionCandidate,
+}
+
+impl AssessedCandidate<'_> {
+    fn eligible(&self) -> bool {
+        self.evidence.compatible && self.evidence.authorized && self.evidence.available
+    }
+}
+
+/// A successful decision token. It cannot be deserialized or constructed by callers.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ResolvedExtension {
+    manifest: ExtensionManifest,
+    locked: LockedExtension,
+    capability: Capability,
+    execution_mode: ExecutionMode,
+    lock_id: String,
+    fallback_policy: FallbackPolicy,
+}
+
+impl ResolvedExtension {
+    #[must_use]
+    pub fn extension_id(&self) -> &str {
+        &self.manifest.extension_id
+    }
+
+    #[must_use]
+    pub fn version(&self) -> &str {
+        &self.manifest.version
+    }
+
+    #[must_use]
+    pub fn publisher_id(&self) -> &str {
+        &self.manifest.publisher.id
+    }
+
+    #[must_use]
+    pub fn integrity(&self) -> &Integrity {
+        &self.manifest.integrity
+    }
+
+    #[must_use]
+    pub fn capability(&self) -> &Capability {
+        &self.capability
+    }
+
+    #[must_use]
+    pub fn execution_mode(&self) -> &ExecutionMode {
+        &self.execution_mode
+    }
+
+    #[must_use]
+    pub fn lock_id(&self) -> &str {
+        &self.lock_id
+    }
+
+    #[must_use]
+    pub const fn fallback_policy(&self) -> FallbackPolicy {
+        self.fallback_policy
+    }
+
+    #[must_use]
+    pub fn granted_permissions(&self) -> &crate::contracts::Permissions {
+        &self.locked.granted_permissions
+    }
+}
+
+/// Versioned resolution evidence plus an opaque successful decision, if any.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ResolutionOutcome {
+    evidence: ExtensionResolution,
+    resolved: Option<ResolvedExtension>,
+}
+
+impl ResolutionOutcome {
+    fn selected(evidence: ExtensionResolution, resolved: ResolvedExtension) -> Self {
+        debug_assert!(evidence.validate().is_ok());
+        Self {
+            evidence,
+            resolved: Some(resolved),
+        }
+    }
+
+    fn rejected(evidence: ExtensionResolution) -> Self {
+        debug_assert!(evidence.validate().is_ok());
+        Self {
+            evidence,
+            resolved: None,
+        }
+    }
+
+    #[must_use]
+    pub fn evidence(&self) -> &ExtensionResolution {
+        &self.evidence
+    }
+
+    #[must_use]
+    pub fn resolved(&self) -> Option<&ResolvedExtension> {
+        self.resolved.as_ref()
+    }
+
+    #[must_use]
+    pub fn into_resolved(self) -> Option<ResolvedExtension> {
+        self.resolved
+    }
+}
+
+fn manifest_identity(manifest: &ExtensionManifest) -> IdentityKey<'_> {
+    IdentityKey {
+        extension_id: &manifest.extension_id,
+        version: &manifest.version,
+        publisher_id: &manifest.publisher.id,
+    }
+}
+
+fn manifest_sort_key(manifest: &ExtensionManifest) -> (&str, &str, &str, &str) {
+    (
+        &manifest.extension_id,
+        &manifest.version,
+        &manifest.publisher.id,
+        &manifest.integrity.value,
+    )
+}
+
+fn assessment_sort_key<'a>(
+    candidate: &'a AssessedCandidate<'_>,
+) -> (Reverse<u64>, &'a str, &'a str, &'a str, &'a str) {
+    (
+        Reverse(candidate.evidence.precedence),
+        &candidate.evidence.extension_id,
+        &candidate.evidence.version,
+        &candidate.evidence.publisher_id,
+        &candidate.evidence.integrity,
+    )
+}
+
+fn display_identity(extension_id: &str, version: &str, publisher_id: &str) -> String {
+    format!("{extension_id}@{version} by {publisher_id}")
+}
+
+fn fallback_order(
+    policy: Option<&crate::contracts::CapabilityResolution>,
+    assessed: &[AssessedCandidate<'_>],
+    selected_extension_id: &str,
+) -> Vec<String> {
+    let Some(policy) = policy else {
+        return Vec::new();
+    };
+    let by_id: BTreeMap<&str, &AssessedCandidate<'_>> = assessed
+        .iter()
+        .map(|candidate| (candidate.manifest.extension_id.as_str(), candidate))
+        .collect();
+    let mut ids = Vec::new();
+    let mut seen = HashSet::new();
+    for extension_id in &policy.ordered_extensions {
+        if let Some(candidate) = by_id.get(extension_id.as_str()) {
+            if candidate.evidence.compatible
+                && candidate.evidence.authorized
+                && seen.insert(candidate.manifest.extension_id.as_str())
+            {
+                ids.push(candidate.manifest.extension_id.clone());
+            }
+        }
+        if extension_id == selected_extension_id {
+            break;
+        }
+    }
+    ids
+}
+
+fn fallback_precedence(
+    policy: Option<&crate::contracts::CapabilityResolution>,
+    assessed: &[AssessedCandidate<'_>],
+) -> Option<u64> {
+    let policy = policy?;
+    let highest_available = assessed
+        .iter()
+        .filter(|candidate| candidate.eligible())
+        .map(|candidate| candidate.evidence.precedence)
+        .max()?;
+    let leader_ids: HashSet<&str> = assessed
+        .iter()
+        .filter(|candidate| {
+            candidate.eligible() && candidate.evidence.precedence == highest_available
+        })
+        .map(|candidate| candidate.evidence.extension_id.as_str())
+        .collect();
+    let by_id: BTreeMap<&str, &AssessedCandidate<'_>> = assessed
+        .iter()
+        .map(|candidate| (candidate.manifest.extension_id.as_str(), candidate))
+        .collect();
+    let first_leader = policy
+        .ordered_extensions
+        .iter()
+        .position(|extension_id| leader_ids.contains(extension_id.as_str()))?;
+    policy.ordered_extensions[..first_leader]
+        .iter()
+        .filter_map(|extension_id| by_id.get(extension_id.as_str()).copied())
+        .filter(|candidate| {
+            candidate.evidence.compatible
+                && candidate.evidence.authorized
+                && !candidate.evidence.available
+                && candidate.evidence.precedence >= highest_available
+        })
+        .map(|candidate| candidate.evidence.precedence)
+        .max()
+}
+
+fn is_known_contract_family(family: &str) -> bool {
+    matches!(
+        family,
+        "flow.artifact/v1"
+            | "flow.capability/v1"
+            | "flow.compatibility/v1"
+            | "flow.extension-manifest/v1"
+            | "flow.extension-lock/v1"
+            | "flow.extension-invocation/v1"
+            | "flow.extension-event/v1"
+            | "flow.extension-result/v1"
+            | "flow.extension-resolution/v1"
+    )
+}
diff --git a/src/contracts.rs b/src/contracts.rs
new file mode 100644
index 0000000..fc8cd75
--- /dev/null
+++ b/src/contracts.rs
@@ -0,0 +1,1788 @@
+//! Closed Rust models for the six `flow.extension-*/v1` contracts.
+
+use std::collections::{BTreeMap, HashSet};
+use std::fmt::Debug;
+use std::hash::Hash;
+
+use semver::{Version, VersionReq};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use thiserror::Error;
+
+pub const EXTENSION_MANIFEST_V1: &str = "flow.extension-manifest/v1";
+pub const EXTENSION_LOCK_V1: &str = "flow.extension-lock/v1";
+pub const EXTENSION_INVOCATION_V1: &str = "flow.extension-invocation/v1";
+pub const EXTENSION_EVENT_V1: &str = "flow.extension-event/v1";
+pub const EXTENSION_RESULT_V1: &str = "flow.extension-result/v1";
+pub const EXTENSION_RESOLUTION_V1: &str = "flow.extension-resolution/v1";
+
+/// A schema or cross-field invariant violation.
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+#[error("{path}: {message}")]
+pub struct ValidationError {
+    pub path: String,
+    pub message: String,
+}
+
+impl ValidationError {
+    pub(crate) fn new(path: impl Into<String>, message: impl Into<String>) -> Self {
+        Self {
+            path: path.into(),
+            message: message.into(),
+        }
+    }
+}
+
+/// Provider-owned extension declaration.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionManifest {
+    pub schema_version: String,
+    pub extension_id: String,
+    pub version: String,
+    pub publisher: Publisher,
+    pub integrity: Integrity,
+    pub compatibility: Compatibility,
+    pub inspection: Inspection,
+    pub domain_ownership: Vec<Domain>,
+    pub capabilities: Vec<Capability>,
+    pub execution_modes: Vec<ExecutionMode>,
+    pub requested_permissions: Permissions,
+    pub checkpoint: Checkpoint,
+    pub replacement: Replacement,
+    pub observer_hooks: Vec<ObserverHook>,
+    pub transform_hooks: Vec<TransformHook>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Publisher {
+    pub id: String,
+    pub display_name: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Integrity {
+    pub algorithm: IntegrityAlgorithm,
+    pub value: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum IntegrityAlgorithm {
+    Sha256,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Compatibility {
+    pub flow_version_requirement: String,
+    pub contract_families: Vec<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Inspection {
+    pub version_source: VersionSource,
+    pub capability_source: CapabilitySource,
+    pub health_mode: HealthMode,
+    pub health_capability_ids: Vec<String>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum VersionSource {
+    Manifest,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum CapabilitySource {
+    Manifest,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum HealthMode {
+    ManifestOnly,
+    Invocation,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Domain {
+    Flow,
+    Aniflow,
+    Optiflow,
+    Renderflow,
+    ThirdParty,
+}
+
+impl Domain {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Flow => "flow",
+            Self::Aniflow => "aniflow",
+            Self::Optiflow => "optiflow",
+            Self::Renderflow => "renderflow",
+            Self::ThirdParty => "third-party",
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Capability {
+    pub capability_id: String,
+    pub domain: Domain,
+    pub configuration_schema: String,
+    pub accepts: Vec<String>,
+    pub produces: Vec<String>,
+    pub preconditions: Vec<String>,
+    pub postconditions: Vec<String>,
+    pub deterministic: bool,
+    pub cacheable: bool,
+    pub loss: Loss,
+    pub content_changes: bool,
+    pub effects: Vec<Effect>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Loss {
+    None,
+    Declared,
+    Unknown,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Effect {
+    FilesystemRead,
+    FilesystemWrite,
+    EnvironmentRead,
+    Subprocess,
+    Network,
+    Ai,
+    Gpu,
+    SourceMutation,
+    Destructive,
+    Sign,
+    Publish,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExecutionMode {
+    pub name: String,
+    pub kind: ExecutionModeKind,
+    pub protocol: String,
+    pub entrypoint: String,
+    pub limits: ExecutionLimits,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ExecutionModeKind {
+    InProcess,
+    Process,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+/// Declared execution policy metadata.
+///
+/// The current injected in-process seam correlates these values with the
+/// resolved declaration but does not enforce time, cancellation, or output
+/// bounds.
+pub struct ExecutionLimits {
+    pub timeout_ms: u64,
+    pub max_stdout_bytes: u64,
+    pub max_stderr_bytes: u64,
+    pub cancellation_grace_ms: u64,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+#[allow(clippy::struct_excessive_bools)]
+pub struct Permissions {
+    pub filesystem_read: Vec<String>,
+    pub filesystem_write: Vec<String>,
+    pub environment_read: Vec<String>,
+    pub subprocesses: Vec<String>,
+    pub network_hosts: Vec<String>,
+    pub ai_providers: Vec<String>,
+    pub gpu: bool,
+    pub source_mutation: bool,
+    pub destructive: bool,
+    pub sign: bool,
+    pub publish: bool,
+}
+
+impl Permissions {
+    /// A permission value must be explicitly included in the operator grant.
+    #[must_use]
+    pub fn allows(&self, requested: &Self) -> bool {
+        is_subset(&requested.filesystem_read, &self.filesystem_read)
+            && is_subset(&requested.filesystem_write, &self.filesystem_write)
+            && is_subset(&requested.environment_read, &self.environment_read)
+            && is_subset(&requested.subprocesses, &self.subprocesses)
+            && is_subset(&requested.network_hosts, &self.network_hosts)
+            && is_subset(&requested.ai_providers, &self.ai_providers)
+            && (!requested.gpu || self.gpu)
+            && (!requested.source_mutation || self.source_mutation)
+            && (!requested.destructive || self.destructive)
+            && (!requested.sign || self.sign)
+            && (!requested.publish || self.publish)
+    }
+
+    #[must_use]
+    pub fn allows_effect(&self, effect: Effect) -> bool {
+        match effect {
+            Effect::FilesystemRead => !self.filesystem_read.is_empty(),
+            Effect::FilesystemWrite => !self.filesystem_write.is_empty(),
+            Effect::EnvironmentRead => !self.environment_read.is_empty(),
+            Effect::Subprocess => !self.subprocesses.is_empty(),
+            Effect::Network => !self.network_hosts.is_empty(),
+            Effect::Ai => !self.ai_providers.is_empty(),
+            Effect::Gpu => self.gpu,
+            Effect::SourceMutation => self.source_mutation,
+            Effect::Destructive => self.destructive,
+            Effect::Sign => self.sign,
+            Effect::Publish => self.publish,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Checkpoint {
+    pub mode: CheckpointMode,
+    pub contract_family: String,
+    pub compatibility_keys: Vec<String>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum CheckpointMode {
+    None,
+    Provider,
+    Flow,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Replacement {
+    pub replaces: Vec<String>,
+    pub fallbacks_for: Vec<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ObserverHook {
+    pub hook_id: String,
+    pub lifecycle_points: Vec<LifecyclePoint>,
+    pub read_only: bool,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum LifecyclePoint {
+    Discover,
+    Inspect,
+    Plan,
+    Authorize,
+    Execute,
+    Validate,
+    CommitEvidence,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct TransformHook {
+    pub hook_id: String,
+    pub lifecycle_points: Vec<TransformLifecyclePoint>,
+    pub capability_id: String,
+    pub accepts: Vec<String>,
+    pub produces: Vec<String>,
+    pub content_changes: bool,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum TransformLifecyclePoint {
+    Inspect,
+    Execute,
+    Validate,
+}
+
+/// Operator-owned trust, grant, and precedence policy.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionLock {
+    pub schema_version: String,
+    pub flow_version: String,
+    pub lock_id: String,
+    pub extensions: Vec<LockedExtension>,
+    pub capability_resolution: Vec<CapabilityResolution>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct LockedExtension {
+    pub extension_id: String,
+    pub version: String,
+    pub publisher_id: String,
+    pub integrity: Integrity,
+    pub discovery: Discovery,
+    pub enabled: bool,
+    pub trust: Trust,
+    pub granted_permissions: Permissions,
+    pub precedence: u64,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Discovery {
+    pub kind: DiscoveryKind,
+    pub location: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum DiscoveryKind {
+    ConfiguredPath,
+    Package,
+    Embedded,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Trust {
+    Trusted,
+    Sandboxed,
+    Disabled,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct CapabilityResolution {
+    pub capability_id: String,
+    pub ordered_extensions: Vec<String>,
+    pub fallback: FallbackPolicy,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum FallbackPolicy {
+    Forbidden,
+    BeforeEffects,
+    ExplicitResume,
+}
+
+/// Flow-owned request envelope for one extension call.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionInvocation {
+    pub schema_version: String,
+    pub invocation_id: String,
+    pub run_id: String,
+    pub phase: InvocationPhase,
+    pub extension: InvocationExtension,
+    pub capability_id: String,
+    pub interface: InvocationInterface,
+    pub input_artifacts: Vec<InputArtifact>,
+    pub expected_output_types: Vec<String>,
+    pub configuration: Configuration,
+    pub authorization: Authorization,
+    pub limits: ExecutionLimits,
+    pub checkpoint_refs: Vec<String>,
+    pub secret_handles: Vec<String>,
+    pub cancellation_id: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum InvocationPhase {
+    Inspect,
+    Plan,
+    Execute,
+    Validate,
+}
+
+impl InvocationPhase {
+    #[must_use]
+    pub const fn lifecycle_point(self) -> LifecyclePoint {
+        match self {
+            Self::Inspect => LifecyclePoint::Inspect,
+            Self::Plan => LifecyclePoint::Plan,
+            Self::Execute => LifecyclePoint::Execute,
+            Self::Validate => LifecyclePoint::Validate,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct InvocationExtension {
+    pub extension_id: String,
+    pub version: String,
+    pub publisher_id: String,
+    pub integrity: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct InvocationInterface {
+    pub kind: ExecutionModeKind,
+    pub name: String,
+    pub protocol: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct InputArtifact {
+    pub artifact_id: String,
+    pub digest: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Configuration {
+    pub schema_id: String,
+    pub digest: String,
+    pub values: BTreeMap<String, Value>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Authorization {
+    pub authorization_id: String,
+    pub lock_id: String,
+    pub grants_digest: String,
+}
+
+/// Provider-contributed lifecycle observation.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionEvent {
+    pub schema_version: String,
+    pub event_id: String,
+    pub run_id: String,
+    pub invocation_id: String,
+    pub sequence: u64,
+    pub phase: LifecyclePoint,
+    pub kind: EventKind,
+    pub state: EventState,
+    pub progress: Progress,
+    pub diagnostics: Vec<Diagnostic>,
+    pub artifact_refs: Vec<String>,
+    pub checkpoint_refs: Vec<String>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EventKind {
+    PhaseStarted,
+    Progress,
+    Diagnostic,
+    ArtifactProduced,
+    Checkpoint,
+    PhaseCompleted,
+    PhaseFailed,
+    Cancelled,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum EventState {
+    Planned,
+    Running,
+    Validating,
+    Produced,
+    Reused,
+    Skipped,
+    Blocked,
+    Unavailable,
+    Failed,
+    Cancelled,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Progress {
+    pub completed: u64,
+    pub total: u64,
+    pub unit: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Diagnostic {
+    pub severity: Severity,
+    pub code: String,
+    pub message: String,
+    pub redacted: bool,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Severity {
+    Info,
+    Warning,
+    Error,
+}
+
+/// Provider-contributed terminal evidence.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionResult {
+    pub schema_version: String,
+    pub run_id: String,
+    pub invocation_id: String,
+    pub extension_id: String,
+    pub extension_version: String,
+    pub extension_integrity: String,
+    pub capability_id: String,
+    pub configuration_digest: String,
+    pub authorization_id: String,
+    pub outcome: Outcome,
+    pub partial_result: bool,
+    pub consumed_artifacts: Vec<String>,
+    pub produced_artifacts: Vec<String>,
+    pub validations: Vec<ValidationEvidence>,
+    pub provenance: Vec<ProvenanceEvidence>,
+    pub diagnostics: Vec<Diagnostic>,
+    pub failure: Failure,
+    pub checkpoint_refs: Vec<String>,
+    pub explanation: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Outcome {
+    Produced,
+    Reused,
+    Skipped,
+    Blocked,
+    Unavailable,
+    Failed,
+    Cancelled,
+}
+
+impl Outcome {
+    #[must_use]
+    pub const fn event_state(self) -> EventState {
+        match self {
+            Self::Produced => EventState::Produced,
+            Self::Reused => EventState::Reused,
+            Self::Skipped => EventState::Skipped,
+            Self::Blocked => EventState::Blocked,
+            Self::Unavailable => EventState::Unavailable,
+            Self::Failed => EventState::Failed,
+            Self::Cancelled => EventState::Cancelled,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ValidationEvidence {
+    pub validator: String,
+    pub status: ValidationStatus,
+    pub evidence: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ValidationStatus {
+    Passed,
+    Failed,
+    NotRun,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ProvenanceEvidence {
+    pub kind: ProvenanceKind,
+    pub value: String,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ProvenanceKind {
+    Extension,
+    Configuration,
+    Authorization,
+    Process,
+    Artifact,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Failure {
+    pub classification: FailureClassification,
+    pub code: String,
+    pub message: String,
+    pub retryable: bool,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum FailureClassification {
+    None,
+    Malformed,
+    Incompatible,
+    Unauthorized,
+    Unavailable,
+    Timeout,
+    Cancelled,
+    Provider,
+    Validation,
+    Contract,
+    Internal,
+}
+
+/// Versioned Flow-owned explanation of a resolution decision.
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ExtensionResolution {
+    pub schema_version: String,
+    pub case_id: String,
+    pub requested_capability: String,
+    pub candidates: Vec<ResolutionCandidate>,
+    pub result: ResolutionResult,
+    pub selected_extension_ids: Vec<String>,
+    pub fallback_order: Vec<String>,
+    pub reasons: Vec<String>,
+}
+
+#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct ResolutionCandidate {
+    pub extension_id: String,
+    pub version: String,
+    pub publisher_id: String,
+    pub integrity: String,
+    pub precedence: u64,
+    pub compatible: bool,
+    pub authorized: bool,
+    pub available: bool,
+    pub reasons: Vec<String>,
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum ResolutionResult {
+    Selected,
+    NoCompatibleProvider,
+    Blocked,
+    Conflict,
+    Malformed,
+}
+
+impl ExtensionManifest {
+    /// Validate schema-level shapes and manifest cross-field invariants.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first deterministic schema or cross-field violation.
+    #[allow(clippy::too_many_lines)]
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        expect_schema(
+            "manifest.schema_version",
+            &self.schema_version,
+            EXTENSION_MANIFEST_V1,
+        )?;
+        ensure(
+            is_extension_id(&self.extension_id),
+            "manifest.extension_id",
+            "must be a lowercase qualified extension identifier",
+        )?;
+        validate_strict_version("manifest.version", &self.version)?;
+        ensure(
+            is_publisher_id(&self.publisher.id),
+            "manifest.publisher.id",
+            "must be a lowercase publisher identifier",
+        )?;
+        nonempty(
+            "manifest.publisher.display_name",
+            &self.publisher.display_name,
+        )?;
+        validate_integrity("manifest.integrity", &self.integrity)?;
+        parse_flow_version_requirement(&self.compatibility.flow_version_requirement)?;
+        ensure(
+            !self.compatibility.contract_families.is_empty(),
+            "manifest.compatibility.contract_families",
+            "must contain at least one contract family",
+        )?;
+        unique(
+            "manifest.compatibility.contract_families",
+            &self.compatibility.contract_families,
+        )?;
+        for (index, family) in self.compatibility.contract_families.iter().enumerate() {
+            ensure(
+                contract_family_major(family).is_some(),
+                format!("manifest.compatibility.contract_families[{index}]"),
+                "must use flow.<family>/v<positive-major> syntax",
+            )?;
+        }
+
+        unique(
+            "manifest.inspection.health_capability_ids",
+            &self.inspection.health_capability_ids,
+        )?;
+        ensure(
+            !self.domain_ownership.is_empty(),
+            "manifest.domain_ownership",
+            "must contain at least one domain",
+        )?;
+        unique("manifest.domain_ownership", &self.domain_ownership)?;
+        ensure(
+            !self.capabilities.is_empty(),
+            "manifest.capabilities",
+            "must contain at least one capability",
+        )?;
+        unique_by(
+            "manifest.capabilities",
+            &self.capabilities,
+            |capability| &capability.capability_id,
+            "capability identifiers must be unique",
+        )?;
+        for (index, capability) in self.capabilities.iter().enumerate() {
+            validate_capability(capability, index)?;
+            ensure(
+                self.domain_ownership.contains(&capability.domain),
+                format!("manifest.capabilities[{index}].domain"),
+                "capability uses an undeclared domain",
+            )?;
+            for effect in &capability.effects {
+                ensure(
+                    self.requested_permissions.allows_effect(*effect),
+                    format!("manifest.capabilities[{index}].effects"),
+                    format!("effect {effect:?} has no matching permission request"),
+                )?;
+            }
+        }
+
+        match self.inspection.health_mode {
+            HealthMode::ManifestOnly => ensure(
+                self.inspection.health_capability_ids.is_empty(),
+                "manifest.inspection.health_capability_ids",
+                "manifest-only health cannot invoke capabilities",
+            )?,
+            HealthMode::Invocation => {
+                ensure(
+                    !self.inspection.health_capability_ids.is_empty(),
+                    "manifest.inspection.health_capability_ids",
+                    "invocation health must reference declared capabilities",
+                )?;
+                for capability_id in &self.inspection.health_capability_ids {
+                    ensure(
+                        self.capability(capability_id).is_some(),
+                        "manifest.inspection.health_capability_ids",
+                        format!("unknown health capability {capability_id}"),
+                    )?;
+                }
+            }
+        }
+
+        ensure(
+            !self.execution_modes.is_empty(),
+            "manifest.execution_modes",
+            "must contain at least one execution mode",
+        )?;
+        unique_by(
+            "manifest.execution_modes",
+            &self.execution_modes,
+            |mode| &mode.name,
+            "execution mode names must be unique",
+        )?;
+        for (index, mode) in self.execution_modes.iter().enumerate() {
+            validate_execution_mode(mode, index)?;
+        }
+        validate_permissions(
+            "manifest.requested_permissions",
+            &self.requested_permissions,
+        )?;
+        nonempty(
+            "manifest.checkpoint.contract_family",
+            &self.checkpoint.contract_family,
+        )?;
+        unique(
+            "manifest.checkpoint.compatibility_keys",
+            &self.checkpoint.compatibility_keys,
+        )?;
+        for (index, key) in self.checkpoint.compatibility_keys.iter().enumerate() {
+            nonempty(
+                format!("manifest.checkpoint.compatibility_keys[{index}]"),
+                key,
+            )?;
+        }
+        validate_string_list("manifest.replacement.replaces", &self.replacement.replaces)?;
+        validate_string_list(
+            "manifest.replacement.fallbacks_for",
+            &self.replacement.fallbacks_for,
+        )?;
+
+        let mut hook_ids = HashSet::new();
+        for (index, hook) in self.observer_hooks.iter().enumerate() {
+            nonempty(
+                format!("manifest.observer_hooks[{index}].hook_id"),
+                &hook.hook_id,
+            )?;
+            ensure(
+                hook_ids.insert(hook.hook_id.as_str()),
+                "manifest.observer_hooks",
+                "hook identifiers must be unique",
+            )?;
+            ensure(
+                !hook.lifecycle_points.is_empty(),
+                format!("manifest.observer_hooks[{index}].lifecycle_points"),
+                "must contain at least one lifecycle point",
+            )?;
+            unique(
+                format!("manifest.observer_hooks[{index}].lifecycle_points"),
+                &hook.lifecycle_points,
+            )?;
+            ensure(
+                hook.read_only,
+                format!("manifest.observer_hooks[{index}].read_only"),
+                "observer hooks must be read-only",
+            )?;
+        }
+        for (index, hook) in self.transform_hooks.iter().enumerate() {
+            nonempty(
+                format!("manifest.transform_hooks[{index}].hook_id"),
+                &hook.hook_id,
+            )?;
+            ensure(
+                hook_ids.insert(hook.hook_id.as_str()),
+                "manifest.transform_hooks",
+                "hook identifiers must be unique",
+            )?;
+            ensure(
+                !hook.lifecycle_points.is_empty(),
+                format!("manifest.transform_hooks[{index}].lifecycle_points"),
+                "must contain at least one lifecycle point",
+            )?;
+            unique(
+                format!("manifest.transform_hooks[{index}].lifecycle_points"),
+                &hook.lifecycle_points,
+            )?;
+            ensure(
+                hook.content_changes,
+                format!("manifest.transform_hooks[{index}].content_changes"),
+                "transform hooks must change content",
+            )?;
+            ensure(
+                !hook.accepts.is_empty() && !hook.produces.is_empty(),
+                format!("manifest.transform_hooks[{index}]"),
+                "transform hooks must declare accepted and produced types",
+            )?;
+            validate_string_list(
+                &format!("manifest.transform_hooks[{index}].accepts"),
+                &hook.accepts,
+            )?;
+            validate_string_list(
+                &format!("manifest.transform_hooks[{index}].produces"),
+                &hook.produces,
+            )?;
+            let capability = self.capability(&hook.capability_id).ok_or_else(|| {
+                ValidationError::new(
+                    format!("manifest.transform_hooks[{index}].capability_id"),
+                    "transform hook references an unknown capability",
+                )
+            })?;
+            ensure(
+                capability.content_changes,
+                format!("manifest.transform_hooks[{index}].capability_id"),
+                "transform hook capability must declare content changes",
+            )?;
+            ensure(
+                hook.accepts == capability.accepts && hook.produces == capability.produces,
+                format!("manifest.transform_hooks[{index}]"),
+                "transform hook artifact types must match its capability",
+            )?;
+        }
+        Ok(())
+    }
+
+    #[must_use]
+    pub fn capability(&self, capability_id: &str) -> Option<&Capability> {
+        self.capabilities
+            .iter()
+            .find(|capability| capability.capability_id == capability_id)
+    }
+
+    #[must_use]
+    pub fn execution_mode(&self, name: &str, kind: ExecutionModeKind) -> Option<&ExecutionMode> {
+        self.execution_modes
+            .iter()
+            .find(|mode| mode.name == name && mode.kind == kind)
+    }
+}
+
+impl ExtensionLock {
+    /// Validate lock shapes, identities, and policy references.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first deterministic schema or cross-field violation.
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        expect_schema(
+            "lock.schema_version",
+            &self.schema_version,
+            EXTENSION_LOCK_V1,
+        )?;
+        validate_strict_version("lock.flow_version", &self.flow_version)?;
+        ensure(
+            has_prefixed_id(&self.lock_id, "lock:"),
+            "lock.lock_id",
+            "must be a lowercase lock identifier",
+        )?;
+        ensure(
+            !self.extensions.is_empty(),
+            "lock.extensions",
+            "must contain at least one locked extension",
+        )?;
+        unique_by(
+            "lock.extensions",
+            &self.extensions,
+            |extension| &extension.extension_id,
+            "locked extension identifiers must be unique",
+        )?;
+        for (index, extension) in self.extensions.iter().enumerate() {
+            nonempty(
+                format!("lock.extensions[{index}].extension_id"),
+                &extension.extension_id,
+            )?;
+            nonempty(
+                format!("lock.extensions[{index}].version"),
+                &extension.version,
+            )?;
+            nonempty(
+                format!("lock.extensions[{index}].publisher_id"),
+                &extension.publisher_id,
+            )?;
+            validate_integrity(
+                &format!("lock.extensions[{index}].integrity"),
+                &extension.integrity,
+            )?;
+            nonempty(
+                format!("lock.extensions[{index}].discovery.location"),
+                &extension.discovery.location,
+            )?;
+            validate_permissions(
+                &format!("lock.extensions[{index}].granted_permissions"),
+                &extension.granted_permissions,
+            )?;
+        }
+        unique_by(
+            "lock.capability_resolution",
+            &self.capability_resolution,
+            |resolution| &resolution.capability_id,
+            "capability resolution identifiers must be unique",
+        )?;
+        let known: HashSet<&str> = self
+            .extensions
+            .iter()
+            .map(|extension| extension.extension_id.as_str())
+            .collect();
+        let precedence_by_id: BTreeMap<&str, u64> = self
+            .extensions
+            .iter()
+            .map(|extension| (extension.extension_id.as_str(), extension.precedence))
+            .collect();
+        for (index, resolution) in self.capability_resolution.iter().enumerate() {
+            nonempty(
+                format!("lock.capability_resolution[{index}].capability_id"),
+                &resolution.capability_id,
+            )?;
+            ensure(
+                !resolution.ordered_extensions.is_empty(),
+                format!("lock.capability_resolution[{index}].ordered_extensions"),
+                "must contain at least one extension",
+            )?;
+            unique(
+                format!("lock.capability_resolution[{index}].ordered_extensions"),
+                &resolution.ordered_extensions,
+            )?;
+            for extension_id in &resolution.ordered_extensions {
+                ensure(
+                    known.contains(extension_id.as_str()),
+                    format!("lock.capability_resolution[{index}].ordered_extensions"),
+                    format!("references unlocked extension {extension_id}"),
+                )?;
+            }
+            let mut previous_precedence = None;
+            for extension_id in &resolution.ordered_extensions {
+                let Some(precedence) = precedence_by_id.get(extension_id.as_str()).copied() else {
+                    continue;
+                };
+                ensure(
+                    previous_precedence.is_none_or(|previous| previous >= precedence),
+                    format!("lock.capability_resolution[{index}].ordered_extensions"),
+                    "must be ordered by non-increasing locked precedence",
+                )?;
+                previous_precedence = Some(precedence);
+            }
+        }
+        Ok(())
+    }
+
+    #[must_use]
+    pub fn extension(&self, extension_id: &str) -> Option<&LockedExtension> {
+        self.extensions
+            .iter()
+            .find(|extension| extension.extension_id == extension_id)
+    }
+
+    #[must_use]
+    pub fn resolution_for(&self, capability_id: &str) -> Option<&CapabilityResolution> {
+        self.capability_resolution
+            .iter()
+            .find(|resolution| resolution.capability_id == capability_id)
+    }
+}
+
+impl ExtensionInvocation {
+    /// Validate the invocation envelope before any extension code runs.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first deterministic schema or field violation.
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        expect_schema(
+            "invocation.schema_version",
+            &self.schema_version,
+            EXTENSION_INVOCATION_V1,
+        )?;
+        ensure(
+            has_prefixed_id(&self.invocation_id, "invocation:"),
+            "invocation.invocation_id",
+            "must be a lowercase invocation identifier",
+        )?;
+        ensure(
+            has_prefixed_id(&self.run_id, "run:"),
+            "invocation.run_id",
+            "must be a lowercase run identifier",
+        )?;
+        nonempty(
+            "invocation.extension.extension_id",
+            &self.extension.extension_id,
+        )?;
+        nonempty("invocation.extension.version", &self.extension.version)?;
+        nonempty(
+            "invocation.extension.publisher_id",
+            &self.extension.publisher_id,
+        )?;
+        validate_digest("invocation.extension.integrity", &self.extension.integrity)?;
+        nonempty("invocation.capability_id", &self.capability_id)?;
+        nonempty("invocation.interface.name", &self.interface.name)?;
+        expect_schema(
+            "invocation.interface.protocol",
+            &self.interface.protocol,
+            EXTENSION_INVOCATION_V1,
+        )?;
+        for (index, artifact) in self.input_artifacts.iter().enumerate() {
+            nonempty(
+                format!("invocation.input_artifacts[{index}].artifact_id"),
+                &artifact.artifact_id,
+            )?;
+            validate_digest(
+                &format!("invocation.input_artifacts[{index}].digest"),
+                &artifact.digest,
+            )?;
+        }
+        unique_by(
+            "invocation.input_artifacts",
+            &self.input_artifacts,
+            |artifact| artifact.artifact_id.as_str(),
+            "input artifact identifiers must be unique",
+        )?;
+        validate_string_list(
+            "invocation.expected_output_types",
+            &self.expected_output_types,
+        )?;
+        nonempty(
+            "invocation.configuration.schema_id",
+            &self.configuration.schema_id,
+        )?;
+        validate_digest(
+            "invocation.configuration.digest",
+            &self.configuration.digest,
+        )?;
+        nonempty(
+            "invocation.authorization.authorization_id",
+            &self.authorization.authorization_id,
+        )?;
+        nonempty(
+            "invocation.authorization.lock_id",
+            &self.authorization.lock_id,
+        )?;
+        validate_digest(
+            "invocation.authorization.grants_digest",
+            &self.authorization.grants_digest,
+        )?;
+        validate_limits("invocation.limits", &self.limits)?;
+        validate_string_list("invocation.checkpoint_refs", &self.checkpoint_refs)?;
+        unique("invocation.secret_handles", &self.secret_handles)?;
+        for (index, handle) in self.secret_handles.iter().enumerate() {
+            ensure(
+                has_prefixed_id(handle, "secret:"),
+                format!("invocation.secret_handles[{index}]"),
+                "must be a lowercase secret handle",
+            )?;
+        }
+        nonempty("invocation.cancellation_id", &self.cancellation_id)?;
+        Ok(())
+    }
+}
+
+impl ExtensionEvent {
+    /// Validate one event independently of stream correlation.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first deterministic schema or field violation.
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        expect_schema(
+            "event.schema_version",
+            &self.schema_version,
+            EXTENSION_EVENT_V1,
+        )?;
+        nonempty("event.event_id", &self.event_id)?;
+        nonempty("event.run_id", &self.run_id)?;
+        nonempty("event.invocation_id", &self.invocation_id)?;
+        ensure(
+            self.progress.completed <= self.progress.total,
+            "event.progress",
+            "completed work cannot exceed total work",
+        )?;
+        nonempty("event.progress.unit", &self.progress.unit)?;
+        for (index, diagnostic) in self.diagnostics.iter().enumerate() {
+            validate_diagnostic(diagnostic, &format!("event.diagnostics[{index}]"))?;
+        }
+        validate_string_list("event.artifact_refs", &self.artifact_refs)?;
+        validate_string_list("event.checkpoint_refs", &self.checkpoint_refs)?;
+        Ok(())
+    }
+}
+
+impl ExtensionResult {
+    /// Validate terminal evidence, including outcome/failure consistency.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first deterministic schema or cross-field violation.
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        expect_schema(
+            "result.schema_version",
+            &self.schema_version,
+            EXTENSION_RESULT_V1,
+        )?;
+        nonempty("result.run_id", &self.run_id)?;
+        nonempty("result.invocation_id", &self.invocation_id)?;
+        nonempty("result.extension_id", &self.extension_id)?;
+        nonempty("result.extension_version", &self.extension_version)?;
+        validate_digest("result.extension_integrity", &self.extension_integrity)?;
+        nonempty("result.capability_id", &self.capability_id)?;
+        validate_digest("result.configuration_digest", &self.configuration_digest)?;
+        nonempty("result.authorization_id", &self.authorization_id)?;
+        validate_string_list("result.consumed_artifacts", &self.consumed_artifacts)?;
+        validate_string_list("result.produced_artifacts", &self.produced_artifacts)?;
+        for (index, validation) in self.validations.iter().enumerate() {
+            nonempty(
+                format!("result.validations[{index}].validator"),
+                &validation.validator,
+            )?;
+            nonempty(
+                format!("result.validations[{index}].evidence"),
+                &validation.evidence,
+            )?;
+        }
+        if matches!(self.outcome, Outcome::Produced | Outcome::Reused) {
+            ensure(
+                self.validations
+                    .iter()
+                    .all(|validation| validation.status == ValidationStatus::Passed),
+                "result.validations",
+                "produced or reused outcomes require every reported validation to pass",
+            )?;
+        } else if self.outcome == Outcome::Skipped {
+            ensure(
+                self.validations
+                    .iter()
+                    .all(|validation| validation.status != ValidationStatus::Failed),
+                "result.validations",
+                "a skipped outcome cannot contain failed validation evidence",
+            )?;
+        }
+        for (index, evidence) in self.provenance.iter().enumerate() {
+            nonempty(format!("result.provenance[{index}].value"), &evidence.value)?;
+        }
+        for (index, diagnostic) in self.diagnostics.iter().enumerate() {
+            validate_diagnostic(diagnostic, &format!("result.diagnostics[{index}]"))?;
+        }
+        validate_string_list("result.checkpoint_refs", &self.checkpoint_refs)?;
+        nonempty("result.explanation", &self.explanation)?;
+        validate_outcome_failure(self.outcome, &self.failure)?;
+        Ok(())
+    }
+}
+
+impl ExtensionResolution {
+    /// Validate versioned selection or rejection evidence.
+    ///
+    /// # Errors
+    ///
+    /// Returns the first deterministic schema or cross-field violation.
+    #[allow(clippy::too_many_lines)]
+    pub fn validate(&self) -> Result<(), ValidationError> {
+        expect_schema(
+            "resolution.schema_version",
+            &self.schema_version,
+            EXTENSION_RESOLUTION_V1,
+        )?;
+        nonempty("resolution.case_id", &self.case_id)?;
+        nonempty(
+            "resolution.requested_capability",
+            &self.requested_capability,
+        )?;
+        for (index, candidate) in self.candidates.iter().enumerate() {
+            nonempty(
+                format!("resolution.candidates[{index}].extension_id"),
+                &candidate.extension_id,
+            )?;
+            nonempty(
+                format!("resolution.candidates[{index}].version"),
+                &candidate.version,
+            )?;
+            nonempty(
+                format!("resolution.candidates[{index}].publisher_id"),
+                &candidate.publisher_id,
+            )?;
+            validate_digest(
+                &format!("resolution.candidates[{index}].integrity"),
+                &candidate.integrity,
+            )?;
+            for (reason_index, reason) in candidate.reasons.iter().enumerate() {
+                nonempty(
+                    format!("resolution.candidates[{index}].reasons[{reason_index}]"),
+                    reason,
+                )?;
+            }
+        }
+        unique_by(
+            "resolution.candidates",
+            &self.candidates,
+            |candidate| &candidate.extension_id,
+            "candidate extension identifiers must be unique",
+        )?;
+        unique(
+            "resolution.selected_extension_ids",
+            &self.selected_extension_ids,
+        )?;
+        unique("resolution.fallback_order", &self.fallback_order)?;
+        let candidate_ids: HashSet<&str> = self
+            .candidates
+            .iter()
+            .map(|candidate| candidate.extension_id.as_str())
+            .collect();
+        for extension_id in &self.fallback_order {
+            ensure(
+                candidate_ids.contains(extension_id.as_str()),
+                "resolution.fallback_order",
+                format!("references unknown candidate {extension_id}"),
+            )?;
+        }
+        ensure(
+            !self.reasons.is_empty(),
+            "resolution.reasons",
+            "must contain at least one reason",
+        )?;
+        for (index, reason) in self.reasons.iter().enumerate() {
+            nonempty(format!("resolution.reasons[{index}]"), reason)?;
+        }
+
+        let eligible: Vec<&ResolutionCandidate> = self
+            .candidates
+            .iter()
+            .filter(|candidate| candidate.compatible && candidate.authorized && candidate.available)
+            .collect();
+        if self.result != ResolutionResult::Selected {
+            ensure(
+                self.fallback_order.is_empty(),
+                "resolution.fallback_order",
+                "non-selected resolution cannot record fallback order",
+            )?;
+        }
+        match self.result {
+            ResolutionResult::Selected => {
+                ensure(
+                    self.selected_extension_ids.len() == 1,
+                    "resolution.selected_extension_ids",
+                    "selected resolution must name exactly one extension",
+                )?;
+                let selected_id = &self.selected_extension_ids[0];
+                let selected = eligible
+                    .iter()
+                    .find(|candidate| candidate.extension_id == *selected_id)
+                    .ok_or_else(|| {
+                        ValidationError::new(
+                            "resolution.selected_extension_ids",
+                            "selected extension must be compatible, authorized, and available",
+                        )
+                    })?;
+                let max_precedence = eligible
+                    .iter()
+                    .map(|candidate| candidate.precedence)
+                    .max()
+                    .unwrap_or_default();
+                ensure(
+                    selected.precedence == max_precedence,
+                    "resolution.selected_extension_ids",
+                    "selected extension must have the highest eligible precedence",
+                )?;
+                ensure(
+                    eligible
+                        .iter()
+                        .filter(|candidate| candidate.precedence == max_precedence)
+                        .count()
+                        == 1,
+                    "resolution.selected_extension_ids",
+                    "selected extension precedence must be unique",
+                )?;
+                ensure(
+                    self.fallback_order
+                        .last()
+                        .is_none_or(|extension_id| extension_id == selected_id),
+                    "resolution.fallback_order",
+                    "selected fallback evidence must end with the selected extension",
+                )?;
+                if !self.fallback_order.is_empty() {
+                    ensure(
+                        self.fallback_order.len() >= 2,
+                        "resolution.fallback_order",
+                        "fallback evidence must include an unavailable predecessor and the selected extension",
+                    )?;
+                    let by_id: BTreeMap<&str, &ResolutionCandidate> = self
+                        .candidates
+                        .iter()
+                        .map(|candidate| (candidate.extension_id.as_str(), candidate))
+                        .collect();
+                    for extension_id in
+                        &self.fallback_order[..self.fallback_order.len().saturating_sub(1)]
+                    {
+                        let candidate = by_id.get(extension_id.as_str()).ok_or_else(|| {
+                            ValidationError::new(
+                                "resolution.fallback_order",
+                                "fallback order references an unknown candidate",
+                            )
+                        })?;
+                        ensure(
+                            candidate.compatible && candidate.authorized && !candidate.available,
+                            "resolution.fallback_order",
+                            "every fallback predecessor must be compatible, authorized, and unavailable",
+                        )?;
+                    }
+                    for pair in self.fallback_order.windows(2) {
+                        let left = by_id.get(pair[0].as_str()).ok_or_else(|| {
+                            ValidationError::new(
+                                "resolution.fallback_order",
+                                "fallback order references an unknown candidate",
+                            )
+                        })?;
+                        let right = by_id.get(pair[1].as_str()).ok_or_else(|| {
+                            ValidationError::new(
+                                "resolution.fallback_order",
+                                "fallback order references an unknown candidate",
+                            )
+                        })?;
+                        ensure(
+                            left.precedence >= right.precedence,
+                            "resolution.fallback_order",
+                            "fallback precedence must be non-increasing",
+                        )?;
+                    }
+                }
+            }
+            ResolutionResult::NoCompatibleProvider => {
+                ensure(
+                    self.selected_extension_ids.is_empty(),
+                    "resolution.selected_extension_ids",
+                    "non-selected resolution cannot name an extension",
+                )?;
+                ensure(
+                    !self.candidates.iter().any(|candidate| candidate.compatible),
+                    "resolution.result",
+                    "no-compatible-provider requires every candidate to be incompatible",
+                )?;
+            }
+            ResolutionResult::Blocked => {
+                ensure(
+                    self.selected_extension_ids.is_empty(),
+                    "resolution.selected_extension_ids",
+                    "non-selected resolution cannot name an extension",
+                )?;
+                ensure(
+                    self.candidates.iter().any(|candidate| candidate.compatible)
+                        && eligible.is_empty(),
+                    "resolution.result",
+                    "blocked requires compatible but ineligible candidates",
+                )?;
+            }
+            ResolutionResult::Conflict => {
+                ensure(
+                    self.selected_extension_ids.is_empty(),
+                    "resolution.selected_extension_ids",
+                    "non-selected resolution cannot name an extension",
+                )?;
+                let max_precedence = eligible.iter().map(|candidate| candidate.precedence).max();
+                ensure(
+                    max_precedence.is_some_and(|precedence| {
+                        eligible
+                            .iter()
+                            .filter(|candidate| candidate.precedence == precedence)
+                            .count()
+                            > 1
+                    }),
+                    "resolution.result",
+                    "conflict requires equal-precedence eligible candidates",
+                )?;
+            }
+            ResolutionResult::Malformed => {
+                ensure(
+                    self.selected_extension_ids.is_empty() && self.candidates.is_empty(),
+                    "resolution.result",
+                    "malformed resolution cannot expose executable candidates",
+                )?;
+            }
+        }
+        Ok(())
+    }
+}
+
+/// Parse the documented Rust-semver comparator grammar.
+///
+/// Multiple comparators must be comma-separated, for example
+/// `>=0.1.0, <0.2.0`.
+///
+/// # Errors
+///
+/// Returns an error when the requirement is empty or is not accepted by the
+/// Rust `semver` comparator grammar.
+pub fn parse_flow_version_requirement(requirement: &str) -> Result<VersionReq, ValidationError> {
+    nonempty(
+        "manifest.compatibility.flow_version_requirement",
+        requirement,
+    )?;
+    VersionReq::parse(requirement).map_err(|error| {
+        ValidationError::new(
+            "manifest.compatibility.flow_version_requirement",
+            format!("invalid comma-separated semver requirement: {error}"),
+        )
+    })
+}
+
+/// Return the positive contract major for a syntactically valid Flow family.
+#[must_use]
+pub fn contract_family_major(family: &str) -> Option<u64> {
+    let rest = family.strip_prefix("flow.")?;
+    let (name, major) = rest.rsplit_once("/v")?;
+    if name.is_empty()
+        || !name
+            .bytes()
+            .all(|byte| byte.is_ascii_lowercase() || byte == b'-')
+        || major.starts_with('0')
+        || major.is_empty()
+        || !major.bytes().all(|byte| byte.is_ascii_digit())
+    {
+        return None;
+    }
+    major.parse().ok()
+}
+
+fn validate_capability(capability: &Capability, index: usize) -> Result<(), ValidationError> {
+    ensure(
+        is_capability_id(&capability.capability_id),
+        format!("manifest.capabilities[{index}].capability_id"),
+        "must be a qualified capability identifier",
+    )?;
+    nonempty(
+        format!("manifest.capabilities[{index}].configuration_schema"),
+        &capability.configuration_schema,
+    )?;
+    validate_string_list(
+        &format!("manifest.capabilities[{index}].accepts"),
+        &capability.accepts,
+    )?;
+    validate_string_list(
+        &format!("manifest.capabilities[{index}].produces"),
+        &capability.produces,
+    )?;
+    validate_string_list(
+        &format!("manifest.capabilities[{index}].preconditions"),
+        &capability.preconditions,
+    )?;
+    validate_string_list(
+        &format!("manifest.capabilities[{index}].postconditions"),
+        &capability.postconditions,
+    )?;
+    unique(
+        format!("manifest.capabilities[{index}].effects"),
+        &capability.effects,
+    )
+}
+
+fn validate_execution_mode(mode: &ExecutionMode, index: usize) -> Result<(), ValidationError> {
+    nonempty(
+        format!("manifest.execution_modes[{index}].name"),
+        &mode.name,
+    )?;
+    expect_schema(
+        &format!("manifest.execution_modes[{index}].protocol"),
+        &mode.protocol,
+        EXTENSION_INVOCATION_V1,
+    )?;
+    nonempty(
+        format!("manifest.execution_modes[{index}].entrypoint"),
+        &mode.entrypoint,
+    )?;
+    validate_limits(
+        &format!("manifest.execution_modes[{index}].limits"),
+        &mode.limits,
+    )
+}
+
+fn validate_limits(path: &str, limits: &ExecutionLimits) -> Result<(), ValidationError> {
+    ensure(
+        limits.timeout_ms > 0,
+        format!("{path}.timeout_ms"),
+        "must be greater than zero",
+    )
+}
+
+fn validate_permissions(path: &str, permissions: &Permissions) -> Result<(), ValidationError> {
+    validate_string_list(
+        &format!("{path}.filesystem_read"),
+        &permissions.filesystem_read,
+    )?;
+    validate_string_list(
+        &format!("{path}.filesystem_write"),
+        &permissions.filesystem_write,
+    )?;
+    unique(
+        format!("{path}.environment_read"),
+        &permissions.environment_read,
+    )?;
+    for (index, variable) in permissions.environment_read.iter().enumerate() {
+        ensure(
+            is_environment_name(variable),
+            format!("{path}.environment_read[{index}]"),
+            "must be an uppercase environment variable name",
+        )?;
+    }
+    validate_string_list(&format!("{path}.subprocesses"), &permissions.subprocesses)?;
+    validate_string_list(&format!("{path}.network_hosts"), &permissions.network_hosts)?;
+    validate_string_list(&format!("{path}.ai_providers"), &permissions.ai_providers)
+}
+
+fn validate_diagnostic(diagnostic: &Diagnostic, path: &str) -> Result<(), ValidationError> {
+    nonempty(format!("{path}.code"), &diagnostic.code)?;
+    nonempty(format!("{path}.message"), &diagnostic.message)
+}
+
+fn validate_outcome_failure(outcome: Outcome, failure: &Failure) -> Result<(), ValidationError> {
+    let classification = failure.classification;
+    let consistent = match outcome {
+        Outcome::Produced | Outcome::Reused | Outcome::Skipped => {
+            classification == FailureClassification::None
+        }
+        Outcome::Unavailable => classification == FailureClassification::Unavailable,
+        Outcome::Cancelled => classification == FailureClassification::Cancelled,
+        Outcome::Blocked => matches!(
+            classification,
+            FailureClassification::Unauthorized
+                | FailureClassification::Incompatible
+                | FailureClassification::Validation
+                | FailureClassification::Contract
+        ),
+        Outcome::Failed => matches!(
+            classification,
+            FailureClassification::Malformed
+                | FailureClassification::Timeout
+                | FailureClassification::Provider
+                | FailureClassification::Validation
+                | FailureClassification::Contract
+                | FailureClassification::Internal
+        ),
+    };
+    ensure(
+        consistent,
+        "result.failure.classification",
+        "failure classification is inconsistent with the terminal outcome",
+    )?;
+    if classification == FailureClassification::None {
+        ensure(
+            failure.code.is_empty() && failure.message.is_empty() && !failure.retryable,
+            "result.failure",
+            "a none classification requires empty code/message and retryable false",
+        )
+    } else {
+        nonempty("result.failure.code", &failure.code)?;
+        nonempty("result.failure.message", &failure.message)
+    }
+}
+
+fn validate_integrity(path: &str, integrity: &Integrity) -> Result<(), ValidationError> {
+    validate_digest(&format!("{path}.value"), &integrity.value)
+}
+
+fn validate_digest(path: &str, digest: &str) -> Result<(), ValidationError> {
+    ensure(
+        digest.len() == 64
+            && digest
+                .bytes()
+                .all(|byte| byte.is_ascii_digit() || (b'a'..=b'f').contains(&byte)),
+        path,
+        "must be 64 lowercase hexadecimal characters",
+    )
+}
+
+fn validate_strict_version(path: &str, version: &str) -> Result<Version, ValidationError> {
+    let parsed = Version::parse(version).map_err(|error| {
+        ValidationError::new(path, format!("invalid semantic version: {error}"))
+    })?;
+    ensure(
+        parsed.pre.is_empty() && parsed.build.is_empty() && parsed.to_string() == version,
+        path,
+        "must use strict major.minor.patch syntax",
+    )?;
+    Ok(parsed)
+}
+
+fn validate_string_list(path: &str, values: &[String]) -> Result<(), ValidationError> {
+    unique(path, values)?;
+    for (index, value) in values.iter().enumerate() {
+        nonempty(format!("{path}[{index}]"), value)?;
+    }
+    Ok(())
+}
+
+fn expect_schema(path: &str, actual: &str, expected: &str) -> Result<(), ValidationError> {
+    ensure(actual == expected, path, format!("must equal {expected}"))
+}
+
+fn ensure(
+    condition: bool,
+    path: impl Into<String>,
+    message: impl Into<String>,
+) -> Result<(), ValidationError> {
+    if condition {
+        Ok(())
+    } else {
+        Err(ValidationError::new(path, message))
+    }
+}
+
+fn nonempty(path: impl Into<String>, value: &str) -> Result<(), ValidationError> {
+    ensure(!value.is_empty(), path, "must not be empty")
+}
+
+fn unique<T>(path: impl Into<String>, values: &[T]) -> Result<(), ValidationError>
+where
+    T: Eq + Hash,
+{
+    let unique: HashSet<&T> = values.iter().collect();
+    ensure(unique.len() == values.len(), path, "items must be unique")
+}
+
+fn unique_by<'a, T, K, F>(
+    path: impl Into<String>,
+    values: &'a [T],
+    key: F,
+    message: impl Into<String>,
+) -> Result<(), ValidationError>
+where
+    K: Eq + Hash + ?Sized + 'a,
+    F: Fn(&'a T) -> &'a K,
+{
+    let unique: HashSet<&K> = values.iter().map(key).collect();
+    ensure(unique.len() == values.len(), path, message)
+}
+
+fn is_subset<T>(requested: &[T], granted: &[T]) -> bool
+where
+    T: Eq,
+{
+    requested.iter().all(|item| granted.contains(item))
+}
+
+fn is_extension_id(value: &str) -> bool {
+    let mut segments = value.split('.');
+    let Some(first) = segments.next() else {
+        return false;
+    };
+    let remaining: Vec<&str> = segments.collect();
+    is_identifier_segment(first, false)
+        && !remaining.is_empty()
+        && remaining
+            .iter()
+            .all(|segment| is_identifier_segment(segment, true))
+}
+
+fn is_publisher_id(value: &str) -> bool {
+    let mut bytes = value.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_lowercase())
+        && bytes.clone().next().is_some()
+        && bytes
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || b".-".contains(&byte))
+}
+
+fn is_identifier_segment(value: &str, allow_hyphen: bool) -> bool {
+    let mut bytes = value.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_lowercase())
+        && bytes.all(|byte| {
+            byte.is_ascii_lowercase() || byte.is_ascii_digit() || (allow_hyphen && byte == b'-')
+        })
+}
+
+fn is_capability_id(value: &str) -> bool {
+    let Some((owner, name)) = value.split_once('/') else {
+        return false;
+    };
+    !name.contains('/') && is_capability_segment(owner) && is_capability_segment(name)
+}
+
+fn is_capability_segment(value: &str) -> bool {
+    let mut bytes = value.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_lowercase())
+        && bytes.clone().next().is_some()
+        && bytes
+            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || b".-".contains(&byte))
+}
+
+fn is_environment_name(value: &str) -> bool {
+    let mut bytes = value.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_uppercase())
+        && bytes.all(|byte| byte.is_ascii_uppercase() || byte.is_ascii_digit() || byte == b'_')
+}
+
+fn has_prefixed_id(value: &str, prefix: &str) -> bool {
+    let Some(identifier) = value.strip_prefix(prefix) else {
+        return false;
+    };
+    let mut bytes = identifier.bytes();
+    matches!(bytes.next(), Some(byte) if byte.is_ascii_lowercase() || byte.is_ascii_digit())
+        && bytes.all(|byte| {
+            byte.is_ascii_lowercase()
+                || byte.is_ascii_digit()
+                || byte == b'.'
+                || byte == b'_'
+                || byte == b'-'
+        })
+}
diff --git a/src/execution.rs b/src/execution.rs
new file mode 100644
index 0000000..db34d40
--- /dev/null
+++ b/src/execution.rs
@@ -0,0 +1,494 @@
+//! Flow-owned validation around one caller-injected in-process extension port.
+
+use std::collections::HashSet;
+
+use thiserror::Error;
+
+use crate::ResolvedExtension;
+use crate::contracts::{
+    EventKind, ExecutionModeKind, ExtensionEvent, ExtensionInvocation, ExtensionResult,
+    InvocationPhase, Outcome, ValidationError,
+};
+
+/// Exact identity advertised by an injected in-process port.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct PortIdentity {
+    pub extension_id: String,
+    pub version: String,
+    pub publisher_id: String,
+    pub integrity: String,
+    pub execution_mode_name: String,
+    pub execution_mode_kind: ExecutionModeKind,
+}
+
+impl PortIdentity {
+    #[must_use]
+    pub fn from_resolved(resolved: &ResolvedExtension) -> Self {
+        Self {
+            extension_id: resolved.extension_id().to_owned(),
+            version: resolved.version().to_owned(),
+            publisher_id: resolved.publisher_id().to_owned(),
+            integrity: resolved.integrity().value.clone(),
+            execution_mode_name: resolved.execution_mode().name.clone(),
+            execution_mode_kind: resolved.execution_mode().kind,
+        }
+    }
+}
+
+/// A destination for individually validated, correlated provider events.
+pub trait EventSink {
+    /// Consume one already schema-validated and invocation-correlated event.
+    ///
+    /// # Errors
+    ///
+    /// Returns an observer-specific error. Flow stops forwarding subsequent
+    /// events and rejects the execution evidence.
+    fn emit(&mut self, event: &ExtensionEvent) -> Result<(), EventSinkError>;
+}
+
+impl EventSink for Vec<ExtensionEvent> {
+    fn emit(&mut self, event: &ExtensionEvent) -> Result<(), EventSinkError> {
+        self.push(event.clone());
+        Ok(())
+    }
+}
+
+impl<F> EventSink for F
+where
+    F: FnMut(&ExtensionEvent) -> Result<(), EventSinkError>,
+{
+    fn emit(&mut self, event: &ExtensionEvent) -> Result<(), EventSinkError> {
+        self(event)
+    }
+}
+
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+#[error("{message}")]
+pub struct EventSinkError {
+    pub message: String,
+}
+
+impl EventSinkError {
+    #[must_use]
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+        }
+    }
+}
+
+/// The only runtime seam in this checkpoint.
+///
+/// Implementations are supplied by the caller. Flow performs no dynamic loading
+/// and starts no process here.
+pub trait ExtensionPort {
+    fn identity(&self) -> &PortIdentity;
+
+    /// Invoke the provider with a Flow-owned request and event boundary.
+    ///
+    /// # Errors
+    ///
+    /// Returns a provider failure. Once this method is entered, Flow will not
+    /// fall back to another provider.
+    fn invoke(
+        &self,
+        invocation: &ExtensionInvocation,
+        events: &mut dyn EventSink,
+    ) -> Result<ExtensionResult, PortError>;
+}
+
+#[derive(Clone, Debug, Eq, Error, PartialEq)]
+#[error("{message}")]
+pub struct PortError {
+    pub message: String,
+}
+
+impl PortError {
+    #[must_use]
+    pub fn new(message: impl Into<String>) -> Self {
+        Self {
+            message: message.into(),
+        }
+    }
+}
+
+/// Execution failed before or after invocation. Provider evidence is retained
+/// for inspection but is never converted into `ValidatedExecution` on error.
+#[derive(Debug, Error)]
+pub enum ExecutionError {
+    #[error("invalid invocation: {source}")]
+    InvalidInvocation {
+        #[source]
+        source: ValidationError,
+    },
+    #[error("execution preflight mismatch: {message}")]
+    Preflight { message: String },
+    #[error("provider invocation failed: {source}")]
+    Provider {
+        #[source]
+        source: PortError,
+        events: Vec<ExtensionEvent>,
+    },
+    #[error("provider emitted invalid event evidence: {message}")]
+    InvalidEvent {
+        message: String,
+        events: Vec<ExtensionEvent>,
+        result: Option<Box<ExtensionResult>>,
+    },
+    #[error("event observer rejected provider evidence: {source}")]
+    EventSink {
+        #[source]
+        source: EventSinkError,
+        events: Vec<ExtensionEvent>,
+        result: Option<Box<ExtensionResult>>,
+    },
+    #[error("provider returned invalid terminal evidence: {message}")]
+    InvalidResult {
+        message: String,
+        events: Vec<ExtensionEvent>,
+        result: Box<ExtensionResult>,
+    },
+}
+
+impl ExecutionError {
+    /// Raw events attempted by the provider, including the rejected event.
+    #[must_use]
+    pub fn events(&self) -> &[ExtensionEvent] {
+        match self {
+            Self::InvalidInvocation { .. } | Self::Preflight { .. } => &[],
+            Self::Provider { events, .. }
+            | Self::InvalidEvent { events, .. }
+            | Self::EventSink { events, .. }
+            | Self::InvalidResult { events, .. } => events,
+        }
+    }
+
+    /// Raw terminal provider evidence, when invocation returned one.
+    #[must_use]
+    pub fn provider_result(&self) -> Option<&ExtensionResult> {
+        match self {
+            Self::InvalidEvent { result, .. } | Self::EventSink { result, .. } => result.as_deref(),
+            Self::InvalidResult { result, .. } => Some(result.as_ref()),
+            Self::InvalidInvocation { .. } | Self::Preflight { .. } | Self::Provider { .. } => None,
+        }
+    }
+}
+
+/// Evidence that passed Flow-owned contract and correlation checks.
+///
+/// This type does not authenticate caller-issued configuration, authorization,
+/// or grant digests; canonicalization and authorization builders are outside
+/// this checkpoint. Artifact checks correlate provider-reported identifiers
+/// only; they do not resolve locators, verify bytes, or perform domain-output
+/// validation.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ValidatedExecution {
+    events: Vec<ExtensionEvent>,
+    result: ExtensionResult,
+}
+
+impl ValidatedExecution {
+    #[must_use]
+    pub fn events(&self) -> &[ExtensionEvent] {
+        &self.events
+    }
+
+    #[must_use]
+    pub fn result(&self) -> &ExtensionResult {
+        &self.result
+    }
+
+    #[must_use]
+    pub fn into_parts(self) -> (Vec<ExtensionEvent>, ExtensionResult) {
+        (self.events, self.result)
+    }
+}
+
+/// Stateless coordinator for one already-resolved in-process invocation.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Orchestrator;
+
+impl Orchestrator {
+    /// Invoke exactly one injected port and validate all returned evidence.
+    ///
+    /// The API deliberately accepts no alternate port, making post-invocation
+    /// fallback impossible at this seam. The port is trusted in-process code;
+    /// this checkpoint does not enforce declared time/output limits, cancel it,
+    /// isolate panics, sandbox it, or constrain its side effects.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error for preflight mismatches, provider failures, rejected
+    /// event observations, observer failures, or invalid terminal evidence.
+    pub fn execute(
+        resolved: &ResolvedExtension,
+        invocation: &ExtensionInvocation,
+        port: &dyn ExtensionPort,
+        event_sink: &mut dyn EventSink,
+    ) -> Result<ValidatedExecution, ExecutionError> {
+        invocation
+            .validate()
+            .map_err(|source| ExecutionError::InvalidInvocation { source })?;
+        validate_preflight(resolved, invocation, port.identity())?;
+
+        let mut validating_sink = ValidatingEventSink::new(invocation, event_sink);
+        let provider_result = port.invoke(invocation, &mut validating_sink);
+        let (events, issue) = validating_sink.finish();
+        match issue {
+            Some(EventIssue::Invalid(message)) => {
+                return Err(ExecutionError::InvalidEvent {
+                    message,
+                    events,
+                    result: provider_result.ok().map(Box::new),
+                });
+            }
+            Some(EventIssue::Downstream(source)) => {
+                return Err(ExecutionError::EventSink {
+                    source,
+                    events,
+                    result: provider_result.ok().map(Box::new),
+                });
+            }
+            None => {}
+        }
+        let result = provider_result.map_err(|source| ExecutionError::Provider {
+            source,
+            events: events.clone(),
+        })?;
+
+        validate_result(invocation, &events, &result).map_err(|message| {
+            ExecutionError::InvalidResult {
+                message,
+                events: events.clone(),
+                result: Box::new(result.clone()),
+            }
+        })?;
+        Ok(ValidatedExecution { events, result })
+    }
+}
+
+fn validate_preflight(
+    resolved: &ResolvedExtension,
+    invocation: &ExtensionInvocation,
+    port: &PortIdentity,
+) -> Result<(), ExecutionError> {
+    if resolved.execution_mode().kind != ExecutionModeKind::InProcess {
+        return preflight("the resolved execution mode is not in-process");
+    }
+    if invocation.phase != InvocationPhase::Execute {
+        return preflight("the execution seam requires invocation phase execute");
+    }
+    if invocation.extension.extension_id != resolved.extension_id()
+        || invocation.extension.version != resolved.version()
+        || invocation.extension.publisher_id != resolved.publisher_id()
+        || invocation.extension.integrity != resolved.integrity().value
+    {
+        return preflight("the invocation extension identity does not match resolution");
+    }
+    if invocation.capability_id != resolved.capability().capability_id {
+        return preflight("the invocation capability does not match resolution");
+    }
+    if invocation.interface.name != resolved.execution_mode().name
+        || invocation.interface.kind != resolved.execution_mode().kind
+    {
+        return preflight("the invocation interface does not match resolution");
+    }
+    if invocation.authorization.lock_id != resolved.lock_id() {
+        return preflight("the invocation authorization does not reference the resolved lock");
+    }
+    if invocation.configuration.schema_id != resolved.capability().configuration_schema {
+        return preflight("the invocation configuration schema does not match the capability");
+    }
+    if invocation.expected_output_types != resolved.capability().produces {
+        return preflight("the invocation expected outputs do not match the capability");
+    }
+    if invocation.limits != resolved.execution_mode().limits {
+        return preflight("the invocation limits do not match the resolved execution mode");
+    }
+    if port.extension_id != resolved.extension_id()
+        || port.version != resolved.version()
+        || port.publisher_id != resolved.publisher_id()
+        || port.integrity != resolved.integrity().value
+        || port.execution_mode_name != resolved.execution_mode().name
+        || port.execution_mode_kind != resolved.execution_mode().kind
+    {
+        return preflight("the injected port identity or execution mode does not match resolution");
+    }
+    Ok(())
+}
+
+fn validate_result(
+    invocation: &ExtensionInvocation,
+    events: &[ExtensionEvent],
+    result: &ExtensionResult,
+) -> Result<(), String> {
+    result.validate().map_err(|error| error.to_string())?;
+    if result
+        .diagnostics
+        .iter()
+        .any(|diagnostic| !diagnostic.redacted)
+    {
+        return Err("result contains an unredacted diagnostic".to_owned());
+    }
+    if result.run_id != invocation.run_id {
+        return Err("result run_id does not match the invocation".to_owned());
+    }
+    if result.invocation_id != invocation.invocation_id {
+        return Err("result invocation_id does not match the invocation".to_owned());
+    }
+    if result.extension_id != invocation.extension.extension_id
+        || result.extension_version != invocation.extension.version
+        || result.extension_integrity != invocation.extension.integrity
+    {
+        return Err("result extension identity does not match the invocation".to_owned());
+    }
+    if result.capability_id != invocation.capability_id {
+        return Err("result capability_id does not match the invocation".to_owned());
+    }
+    if result.configuration_digest != invocation.configuration.digest {
+        return Err("result configuration digest does not match the invocation".to_owned());
+    }
+    if result.authorization_id != invocation.authorization.authorization_id {
+        return Err("result authorization_id does not match the invocation".to_owned());
+    }
+    let input_artifact_ids: HashSet<&str> = invocation
+        .input_artifacts
+        .iter()
+        .map(|artifact| artifact.artifact_id.as_str())
+        .collect();
+    if result
+        .consumed_artifacts
+        .iter()
+        .any(|artifact_id| !input_artifact_ids.contains(artifact_id.as_str()))
+    {
+        return Err("result consumed_artifacts contains an undeclared input identifier".to_owned());
+    }
+    let produced_artifact_ids: HashSet<&str> = result
+        .produced_artifacts
+        .iter()
+        .map(String::as_str)
+        .collect();
+    if events
+        .iter()
+        .filter(|event| event.kind == EventKind::ArtifactProduced)
+        .flat_map(|event| &event.artifact_refs)
+        .any(|artifact_id| !produced_artifact_ids.contains(artifact_id.as_str()))
+    {
+        return Err(
+            "artifact-produced event references an identifier absent from the result".to_owned(),
+        );
+    }
+    let terminal = events
+        .last()
+        .ok_or_else(|| "provider emitted no terminal event".to_owned())?;
+    let expected_kind = match result.outcome {
+        Outcome::Produced | Outcome::Reused | Outcome::Skipped => EventKind::PhaseCompleted,
+        Outcome::Blocked | Outcome::Unavailable | Outcome::Failed => EventKind::PhaseFailed,
+        Outcome::Cancelled => EventKind::Cancelled,
+    };
+    if terminal.kind != expected_kind || terminal.state != result.outcome.event_state() {
+        return Err("terminal event kind/state does not match the result outcome".to_owned());
+    }
+    Ok(())
+}
+
+fn preflight<T>(message: impl Into<String>) -> Result<T, ExecutionError> {
+    Err(ExecutionError::Preflight {
+        message: message.into(),
+    })
+}
+
+#[derive(Debug)]
+enum EventIssue {
+    Invalid(String),
+    Downstream(EventSinkError),
+}
+
+struct ValidatingEventSink<'a> {
+    invocation: &'a ExtensionInvocation,
+    downstream: &'a mut dyn EventSink,
+    raw_events: Vec<ExtensionEvent>,
+    event_ids: HashSet<String>,
+    last_sequence: Option<u64>,
+    terminal_seen: bool,
+    issue: Option<EventIssue>,
+}
+
+impl<'a> ValidatingEventSink<'a> {
+    fn new(invocation: &'a ExtensionInvocation, downstream: &'a mut dyn EventSink) -> Self {
+        Self {
+            invocation,
+            downstream,
+            raw_events: Vec::new(),
+            event_ids: HashSet::new(),
+            last_sequence: None,
+            terminal_seen: false,
+            issue: None,
+        }
+    }
+
+    fn finish(self) -> (Vec<ExtensionEvent>, Option<EventIssue>) {
+        (self.raw_events, self.issue)
+    }
+
+    fn reject(&mut self, message: impl Into<String>) -> Result<(), EventSinkError> {
+        let message = message.into();
+        if self.issue.is_none() {
+            self.issue = Some(EventIssue::Invalid(message.clone()));
+        }
+        Err(EventSinkError::new(message))
+    }
+}
+
+impl EventSink for ValidatingEventSink<'_> {
+    fn emit(&mut self, event: &ExtensionEvent) -> Result<(), EventSinkError> {
+        self.raw_events.push(event.clone());
+        if self.issue.is_some() {
+            return Err(EventSinkError::new(
+                "an earlier event was rejected for this invocation",
+            ));
+        }
+        if let Err(error) = event.validate() {
+            return self.reject(error.to_string());
+        }
+        if event
+            .diagnostics
+            .iter()
+            .any(|diagnostic| !diagnostic.redacted)
+        {
+            return self.reject("event contains an unredacted diagnostic");
+        }
+        if event.run_id != self.invocation.run_id
+            || event.invocation_id != self.invocation.invocation_id
+        {
+            return self.reject("event run/invocation identity does not match the invocation");
+        }
+        if event.phase != self.invocation.phase.lifecycle_point() {
+            return self.reject("event phase does not match the invocation phase");
+        }
+        if self.terminal_seen {
+            return self.reject("provider emitted an event after a terminal event");
+        }
+        if !self.event_ids.insert(event.event_id.clone()) {
+            return self.reject("provider emitted a duplicate event_id");
+        }
+        if self
+            .last_sequence
+            .is_some_and(|previous| event.sequence <= previous)
+        {
+            return self.reject(
+                "event sequences must be unique and strictly increasing; gaps are allowed",
+            );
+        }
+        self.last_sequence = Some(event.sequence);
+        self.terminal_seen = matches!(
+            event.kind,
+            EventKind::PhaseCompleted | EventKind::PhaseFailed | EventKind::Cancelled
+        );
+        if let Err(source) = self.downstream.emit(event) {
+            self.issue = Some(EventIssue::Downstream(source.clone()));
+            return Err(source);
+        }
+        Ok(())
+    }
+}
diff --git a/src/hermetic.rs b/src/hermetic.rs
new file mode 100644
index 0000000..934eab0
--- /dev/null
+++ b/src/hermetic.rs
@@ -0,0 +1,179 @@
+//! A deterministic, no-effects, no-artifacts reference extension port.
+
+use crate::contracts::{
+    Diagnostic, EXTENSION_EVENT_V1, EXTENSION_RESULT_V1, EventKind, EventState, ExtensionEvent,
+    ExtensionInvocation, ExtensionResult, Failure, FailureClassification, Outcome, Progress,
+    Severity,
+};
+use crate::execution::{EventSink, ExtensionPort, PortError, PortIdentity};
+
+/// Deterministic modes used to prove both accepted and adversarial evidence.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub enum HermeticBehavior {
+    #[default]
+    Success,
+    DuplicateSequence,
+    MismatchedEventInvocation,
+    MismatchedResultCapability,
+    InconsistentOutcomeFailure,
+    UnredactedEventDiagnostic,
+    UnredactedResultDiagnostic,
+    PortFailure,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct HermeticExtension {
+    identity: PortIdentity,
+    behavior: HermeticBehavior,
+}
+
+impl HermeticExtension {
+    #[must_use]
+    pub fn new(identity: PortIdentity) -> Self {
+        Self {
+            identity,
+            behavior: HermeticBehavior::Success,
+        }
+    }
+
+    #[must_use]
+    pub const fn with_behavior(mut self, behavior: HermeticBehavior) -> Self {
+        self.behavior = behavior;
+        self
+    }
+}
+
+impl ExtensionPort for HermeticExtension {
+    fn identity(&self) -> &PortIdentity {
+        &self.identity
+    }
+
+    fn invoke(
+        &self,
+        invocation: &ExtensionInvocation,
+        events: &mut dyn EventSink,
+    ) -> Result<ExtensionResult, PortError> {
+        let started = event(
+            invocation,
+            "started",
+            0,
+            EventKind::PhaseStarted,
+            EventState::Running,
+            0,
+        );
+        events
+            .emit(&started)
+            .map_err(|error| PortError::new(error.to_string()))?;
+
+        if self.behavior == HermeticBehavior::PortFailure {
+            return Err(PortError::new("deterministic hermetic provider failure"));
+        }
+
+        let mut completed = event(
+            invocation,
+            "completed",
+            if self.behavior == HermeticBehavior::DuplicateSequence {
+                0
+            } else {
+                2
+            },
+            EventKind::PhaseCompleted,
+            EventState::Produced,
+            1,
+        );
+        if self.behavior == HermeticBehavior::MismatchedEventInvocation {
+            "invocation:adversarial-mismatch".clone_into(&mut completed.invocation_id);
+        }
+        if self.behavior == HermeticBehavior::UnredactedEventDiagnostic {
+            completed.diagnostics.push(unredacted_diagnostic());
+        }
+        events
+            .emit(&completed)
+            .map_err(|error| PortError::new(error.to_string()))?;
+
+        let mut result = ExtensionResult {
+            schema_version: EXTENSION_RESULT_V1.to_owned(),
+            run_id: invocation.run_id.clone(),
+            invocation_id: invocation.invocation_id.clone(),
+            extension_id: invocation.extension.extension_id.clone(),
+            extension_version: invocation.extension.version.clone(),
+            extension_integrity: invocation.extension.integrity.clone(),
+            capability_id: invocation.capability_id.clone(),
+            configuration_digest: invocation.configuration.digest.clone(),
+            authorization_id: invocation.authorization.authorization_id.clone(),
+            outcome: Outcome::Produced,
+            partial_result: false,
+            consumed_artifacts: Vec::new(),
+            produced_artifacts: Vec::new(),
+            validations: Vec::new(),
+            provenance: Vec::new(),
+            diagnostics: Vec::new(),
+            failure: Failure {
+                classification: FailureClassification::None,
+                code: String::new(),
+                message: String::new(),
+                retryable: false,
+            },
+            checkpoint_refs: Vec::new(),
+            explanation: "The hermetic extension completed without effects or artifacts."
+                .to_owned(),
+        };
+        match self.behavior {
+            HermeticBehavior::MismatchedResultCapability => {
+                "flow/adversarial-mismatch".clone_into(&mut result.capability_id);
+            }
+            HermeticBehavior::InconsistentOutcomeFailure => {
+                result.failure.classification = FailureClassification::Provider;
+                "adversarial".clone_into(&mut result.failure.code);
+                "provider-reported success with failure evidence"
+                    .clone_into(&mut result.failure.message);
+            }
+            HermeticBehavior::UnredactedResultDiagnostic => {
+                result.diagnostics.push(unredacted_diagnostic());
+            }
+            HermeticBehavior::Success
+            | HermeticBehavior::DuplicateSequence
+            | HermeticBehavior::MismatchedEventInvocation
+            | HermeticBehavior::UnredactedEventDiagnostic
+            | HermeticBehavior::PortFailure => {}
+        }
+        Ok(result)
+    }
+}
+
+fn unredacted_diagnostic() -> Diagnostic {
+    Diagnostic {
+        severity: Severity::Error,
+        code: "hermetic.unredacted".to_owned(),
+        message: "synthetic private diagnostic".to_owned(),
+        redacted: false,
+    }
+}
+
+fn event(
+    invocation: &ExtensionInvocation,
+    suffix: &str,
+    sequence: u64,
+    kind: EventKind,
+    state: EventState,
+    completed: u64,
+) -> ExtensionEvent {
+    ExtensionEvent {
+        schema_version: EXTENSION_EVENT_V1.to_owned(),
+        event_id: format!("event:{}-{suffix}", invocation.invocation_id),
+        run_id: invocation.run_id.clone(),
+        invocation_id: invocation.invocation_id.clone(),
+        sequence,
+        phase: invocation.phase.lifecycle_point(),
+        kind,
+        state,
+        progress: Progress {
+            completed,
+            total: 1,
+            unit: "invocation".to_owned(),
+        },
+        diagnostics: Vec::new(),
+        artifact_refs: Vec::new(),
+        checkpoint_refs: Vec::new(),
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..cde5925
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,21 @@
+//! Deterministic extension resolution and an injected in-process execution seam.
+//!
+//! Flow treats extension manifests as declarations, operator locks as authority,
+//! and provider events and results as untrusted evidence until validation has
+//! completed.
+
+pub mod catalog;
+pub mod contracts;
+pub mod execution;
+pub mod hermetic;
+
+pub use catalog::{
+    CatalogError, ExtensionCatalog, ExtensionObservation, ResolutionOutcome, ResolutionRequest,
+    ResolvedExtension,
+};
+pub use contracts::*;
+pub use execution::{
+    EventSink, EventSinkError, ExecutionError, ExtensionPort, Orchestrator, PortError,
+    PortIdentity, ValidatedExecution,
+};
+pub use hermetic::{HermeticBehavior, HermeticExtension};
diff --git a/tests/catalog.rs b/tests/catalog.rs
new file mode 100644
index 0000000..e5fe056
--- /dev/null
+++ b/tests/catalog.rs
@@ -0,0 +1,650 @@
+mod common;
+
+use flow::{
+    Domain, ExtensionCatalog, ExtensionLock, ExtensionManifest, ExtensionObservation,
+    FallbackPolicy, ResolutionResult, Trust,
+};
+
+use common::{lock, manifest, observation, request, variant};
+
+type CatalogMutation = Box<dyn Fn(&mut ExtensionManifest, &mut ExtensionLock)>;
+
+fn lock_for(
+    manifests: &[ExtensionManifest],
+    precedences: &[u64],
+    fallback: FallbackPolicy,
+) -> ExtensionLock {
+    assert_eq!(manifests.len(), precedences.len());
+    let mut result = lock();
+    let template = result.extensions[0].clone();
+    result.extensions = manifests
+        .iter()
+        .zip(precedences)
+        .map(|(manifest, precedence)| {
+            let mut entry = template.clone();
+            entry.extension_id.clone_from(&manifest.extension_id);
+            entry.version.clone_from(&manifest.version);
+            entry.publisher_id.clone_from(&manifest.publisher.id);
+            entry.integrity = manifest.integrity.clone();
+            entry.precedence = *precedence;
+            entry
+        })
+        .collect();
+    let ids = manifests
+        .iter()
+        .map(|manifest| manifest.extension_id.clone())
+        .collect::<Vec<_>>();
+    for policy in &mut result.capability_resolution {
+        policy.ordered_extensions.clone_from(&ids);
+        if policy.capability_id == "optiflow/inspect-collection" {
+            policy.fallback = fallback;
+        }
+    }
+    result
+}
+
+#[test]
+fn resolution_is_independent_of_manifest_and_observation_order() {
+    let base = manifest();
+    let high = variant(&base, "org.example.high-adapter", 'a');
+    let low = variant(&base, "org.example.low-adapter", 'b');
+    let lock = lock_for(
+        &[high.clone(), low.clone()],
+        &[100, 50],
+        FallbackPolicy::Forbidden,
+    );
+    let high_observation = observation(&high, true);
+    let low_observation = observation(&low, true);
+
+    let forward = ExtensionCatalog::inspect(
+        [high.clone(), low.clone()],
+        lock.clone(),
+        [high_observation.clone(), low_observation.clone()],
+    )
+    .unwrap()
+    .resolve(&request());
+    let reverse = ExtensionCatalog::inspect([low, high], lock, [low_observation, high_observation])
+        .unwrap()
+        .resolve(&request());
+
+    assert_eq!(forward.evidence(), reverse.evidence());
+    assert_eq!(
+        forward.resolved().unwrap().extension_id(),
+        "org.example.high-adapter"
+    );
+    forward.evidence().validate().unwrap();
+}
+
+#[test]
+fn equal_highest_precedence_is_an_explicit_conflict() {
+    let base = manifest();
+    let left = variant(&base, "org.example.left-adapter", 'c');
+    let right = variant(&base, "org.example.right-adapter", 'd');
+    let lock = lock_for(
+        &[left.clone(), right.clone()],
+        &[50, 50],
+        FallbackPolicy::Forbidden,
+    );
+    let outcome = ExtensionCatalog::inspect(
+        [left.clone(), right.clone()],
+        lock,
+        [observation(&right, true), observation(&left, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Conflict);
+    assert!(outcome.resolved().is_none());
+    outcome.evidence().validate().unwrap();
+}
+
+#[test]
+fn before_effects_fallback_selects_only_after_observed_unavailability() {
+    let base = manifest();
+    let preferred = variant(&base, "org.example.preferred-adapter", 'e');
+    let fallback = variant(&base, "org.example.local-fallback", 'f');
+    let lock = lock_for(
+        &[preferred.clone(), fallback.clone()],
+        &[100, 50],
+        FallbackPolicy::BeforeEffects,
+    );
+    let outcome = ExtensionCatalog::inspect(
+        [fallback.clone(), preferred.clone()],
+        lock,
+        [observation(&preferred, false), observation(&fallback, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Selected);
+    assert_eq!(
+        outcome.evidence().fallback_order,
+        [
+            "org.example.preferred-adapter",
+            "org.example.local-fallback"
+        ]
+    );
+    assert_eq!(
+        outcome.resolved().unwrap().extension_id(),
+        "org.example.local-fallback"
+    );
+    outcome.evidence().validate().unwrap();
+}
+
+#[test]
+fn forbidden_and_resume_only_policies_do_not_fallback() {
+    for policy in [FallbackPolicy::Forbidden, FallbackPolicy::ExplicitResume] {
+        let base = manifest();
+        let preferred = variant(&base, "org.example.preferred-adapter", 'e');
+        let fallback = variant(&base, "org.example.local-fallback", 'f');
+        let lock = lock_for(&[preferred.clone(), fallback.clone()], &[100, 50], policy);
+        let outcome = ExtensionCatalog::inspect(
+            [preferred.clone(), fallback.clone()],
+            lock,
+            [observation(&preferred, false), observation(&fallback, true)],
+        )
+        .unwrap()
+        .resolve(&request());
+
+        assert_eq!(outcome.evidence().result, ResolutionResult::Blocked);
+        assert!(outcome.resolved().is_none());
+        assert!(outcome.evidence().fallback_order.is_empty());
+        assert!(outcome.evidence().candidates.iter().any(|candidate| {
+            candidate.extension_id == "org.example.local-fallback"
+                && candidate.compatible
+                && !candidate.authorized
+                && candidate
+                    .reasons
+                    .iter()
+                    .any(|reason| reason.contains("fallback policy forbids"))
+        }));
+        outcome.evidence().validate().unwrap();
+    }
+}
+
+#[test]
+fn equal_precedence_unavailability_obeys_fallback_policy() {
+    for (policy, expected) in [
+        (FallbackPolicy::Forbidden, ResolutionResult::Blocked),
+        (FallbackPolicy::BeforeEffects, ResolutionResult::Selected),
+    ] {
+        let base = manifest();
+        let unavailable = variant(&base, "org.example.equal-unavailable", 'e');
+        let available = variant(&base, "org.example.equal-available", 'f');
+        let lock = lock_for(&[unavailable.clone(), available.clone()], &[50, 50], policy);
+        let outcome = ExtensionCatalog::inspect(
+            [available.clone(), unavailable.clone()],
+            lock,
+            [
+                observation(&unavailable, false),
+                observation(&available, true),
+            ],
+        )
+        .unwrap()
+        .resolve(&request());
+
+        assert_eq!(outcome.evidence().result, expected);
+        outcome.evidence().validate().unwrap();
+        if policy == FallbackPolicy::BeforeEffects {
+            assert_eq!(
+                outcome.resolved().unwrap().extension_id(),
+                "org.example.equal-available"
+            );
+            assert_eq!(
+                outcome.evidence().fallback_order,
+                [
+                    "org.example.equal-unavailable",
+                    "org.example.equal-available"
+                ]
+            );
+        } else {
+            assert!(outcome.resolved().is_none());
+        }
+    }
+}
+
+#[test]
+fn lock_rejects_policy_order_that_increases_precedence() {
+    let base = manifest();
+    let low = variant(&base, "org.example.policy-first-low", 'f');
+    let high = variant(&base, "org.example.policy-second-high", 'e');
+    let lock = lock_for(
+        &[low.clone(), high.clone()],
+        &[50, 100],
+        FallbackPolicy::BeforeEffects,
+    );
+    assert!(
+        ExtensionCatalog::inspect(
+            [high.clone(), low.clone()],
+            lock,
+            [observation(&high, false), observation(&low, true)],
+        )
+        .is_err()
+    );
+}
+
+#[test]
+fn equal_precedence_unavailable_after_selected_does_not_trigger_fallback() {
+    let base = manifest();
+    let available = variant(&base, "org.example.equal-first-available", 'f');
+    let unavailable = variant(&base, "org.example.equal-second-unavailable", 'e');
+    let lock = lock_for(
+        &[available.clone(), unavailable.clone()],
+        &[50, 50],
+        FallbackPolicy::Forbidden,
+    );
+    let outcome = ExtensionCatalog::inspect(
+        [unavailable.clone(), available.clone()],
+        lock,
+        [
+            observation(&unavailable, false),
+            observation(&available, true),
+        ],
+    )
+    .unwrap()
+    .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Selected);
+    assert_eq!(
+        outcome.resolved().unwrap().extension_id(),
+        "org.example.equal-first-available"
+    );
+    assert!(outcome.evidence().fallback_order.is_empty());
+}
+
+#[test]
+fn disabled_high_precedence_candidate_does_not_trigger_fallback_policy() {
+    let base = manifest();
+    let disabled = variant(&base, "org.example.disabled-high", 'd');
+    let enabled = variant(&base, "org.example.enabled-low", 'e');
+    let mut lock = lock_for(
+        &[disabled.clone(), enabled.clone()],
+        &[100, 50],
+        FallbackPolicy::Forbidden,
+    );
+    lock.extensions
+        .iter_mut()
+        .find(|entry| entry.extension_id == disabled.extension_id)
+        .unwrap()
+        .enabled = false;
+    let outcome = ExtensionCatalog::inspect(
+        [disabled.clone(), enabled.clone()],
+        lock,
+        [observation(&disabled, true), observation(&enabled, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Selected);
+    assert_eq!(
+        outcome.resolved().unwrap().extension_id(),
+        "org.example.enabled-low"
+    );
+    let rejected = outcome
+        .evidence()
+        .candidates
+        .iter()
+        .find(|candidate| candidate.extension_id == disabled.extension_id)
+        .unwrap();
+    assert!(!rejected.authorized);
+    assert!(!rejected.available);
+    assert!(outcome.evidence().fallback_order.is_empty());
+}
+
+#[test]
+fn malformed_manifest_makes_catalog_resolution_atomic() {
+    let valid = manifest();
+    let mut malformed = variant(&valid, "org.example.malformed-local", 'a');
+    malformed.capabilities[0].domain = Domain::ThirdParty;
+    let outcome = ExtensionCatalog::inspect(
+        [malformed.clone(), valid.clone()],
+        lock(),
+        [observation(&valid, true), observation(&malformed, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Malformed);
+    assert!(outcome.evidence().candidates.is_empty());
+    assert!(outcome.resolved().is_none());
+    assert!(outcome.evidence().reasons[0].contains("resolution-v1 cannot represent"));
+    outcome.evidence().validate().unwrap();
+}
+
+#[test]
+fn malformed_manifest_values_do_not_leak_into_portable_reasons() {
+    let mut malformed = manifest();
+    malformed.inspection.health_mode = flow::HealthMode::Invocation;
+    malformed.inspection.health_capability_ids =
+        vec!["/private/customer/path?token=sentinel-secret".to_owned()];
+    let outcome =
+        ExtensionCatalog::inspect([malformed.clone()], lock(), [observation(&malformed, true)])
+            .unwrap()
+            .resolve(&request());
+
+    let evidence = serde_json::to_string(outcome.evidence()).unwrap();
+    assert_eq!(outcome.evidence().result, ResolutionResult::Malformed);
+    assert!(!evidence.contains("private/customer"));
+    assert!(!evidence.contains("sentinel-secret"));
+}
+
+#[test]
+fn all_malformed_manifests_fail_as_malformed_resolution() {
+    let mut malformed = manifest();
+    malformed.capabilities[0].domain = Domain::ThirdParty;
+    let outcome =
+        ExtensionCatalog::inspect([malformed.clone()], lock(), [observation(&malformed, true)])
+            .unwrap()
+            .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Malformed);
+    assert!(outcome.resolved().is_none());
+}
+
+#[test]
+fn empty_catalog_reports_no_compatible_provider() {
+    let outcome = ExtensionCatalog::inspect([], lock(), [])
+        .unwrap()
+        .resolve(&request());
+
+    assert_eq!(
+        outcome.evidence().result,
+        ResolutionResult::NoCompatibleProvider
+    );
+    assert!(outcome.evidence().candidates.is_empty());
+    outcome.evidence().validate().unwrap();
+}
+
+#[test]
+fn partially_materialized_trusted_policy_fails_closed() {
+    for fallback_policy in [FallbackPolicy::Forbidden, FallbackPolicy::BeforeEffects] {
+        let base = manifest();
+        let preferred = variant(&base, "org.example.configured-preferred", 'a');
+        let fallback = variant(&base, "org.example.configured-fallback", 'b');
+        let lock = lock_for(&[preferred, fallback.clone()], &[100, 50], fallback_policy);
+        let outcome =
+            ExtensionCatalog::inspect([fallback.clone()], lock, [observation(&fallback, true)])
+                .unwrap()
+                .resolve(&request());
+
+        assert_eq!(outcome.evidence().result, ResolutionResult::Malformed);
+        assert!(outcome.evidence().candidates.is_empty());
+        assert!(outcome.resolved().is_none());
+        outcome.evidence().validate().unwrap();
+    }
+}
+
+#[test]
+fn substituted_preferred_pin_cannot_bypass_fallback_policy() {
+    let substitutions: [fn(&mut ExtensionManifest); 3] = [
+        |manifest| manifest.version = "0.1.1".to_owned(),
+        |manifest| manifest.publisher.id = "org.example.substitute".to_owned(),
+        |manifest| manifest.integrity.value = "c".repeat(64),
+    ];
+
+    for fallback_policy in [FallbackPolicy::Forbidden, FallbackPolicy::BeforeEffects] {
+        for substitute in substitutions {
+            let base = manifest();
+            let preferred = variant(&base, "org.example.pinned-preferred", 'a');
+            let fallback = variant(&base, "org.example.pinned-fallback", 'b');
+            let lock = lock_for(
+                &[preferred.clone(), fallback.clone()],
+                &[100, 50],
+                fallback_policy,
+            );
+            let mut substituted = preferred;
+            substitute(&mut substituted);
+            let outcome = ExtensionCatalog::inspect(
+                [substituted.clone(), fallback.clone()],
+                lock,
+                [
+                    observation(&substituted, false),
+                    observation(&fallback, true),
+                ],
+            )
+            .unwrap()
+            .resolve(&request());
+
+            assert_eq!(outcome.evidence().result, ResolutionResult::Malformed);
+            assert!(outcome.evidence().candidates.is_empty());
+            assert!(outcome.resolved().is_none());
+            outcome.evidence().validate().unwrap();
+        }
+    }
+}
+
+#[test]
+fn identity_integrity_contract_and_flow_version_fail_closed() {
+    let cases: Vec<CatalogMutation> = vec![
+        Box::new(|_, lock| lock.extensions[0].version = "9.9.9".to_owned()),
+        Box::new(|_, lock| lock.extensions[0].publisher_id = "org.someone-else".to_owned()),
+        Box::new(|_, lock| lock.extensions[0].integrity.value = "a".repeat(64)),
+        Box::new(|manifest, _| {
+            manifest
+                .compatibility
+                .contract_families
+                .push("flow.extension-result/v2".to_owned());
+        }),
+        Box::new(|manifest, _| {
+            manifest.compatibility.flow_version_requirement = ">=9.0.0".to_owned();
+        }),
+    ];
+
+    for mutate in cases {
+        let mut manifest = manifest();
+        let mut lock = lock();
+        mutate(&mut manifest, &mut lock);
+        let outcome =
+            ExtensionCatalog::inspect([manifest.clone()], lock, [observation(&manifest, true)])
+                .unwrap()
+                .resolve(&request());
+        assert_eq!(
+            outcome.evidence().result,
+            ResolutionResult::NoCompatibleProvider
+        );
+        assert!(outcome.resolved().is_none());
+        outcome.evidence().validate().unwrap();
+    }
+}
+
+#[test]
+fn all_three_runtime_contract_families_are_required() {
+    let mut manifest = manifest();
+    manifest.compatibility.contract_families = vec!["flow.artifact/v1".to_owned()];
+    let outcome =
+        ExtensionCatalog::inspect([manifest.clone()], lock(), [observation(&manifest, true)])
+            .unwrap()
+            .resolve(&request());
+
+    assert_eq!(
+        outcome.evidence().result,
+        ResolutionResult::NoCompatibleProvider
+    );
+    assert!(
+        outcome.evidence().candidates[0]
+            .reasons
+            .iter()
+            .any(|reason| reason.contains("flow.extension-invocation/v1"))
+    );
+}
+
+#[test]
+fn permission_denial_is_blocked_with_complete_candidate_evidence() {
+    let manifest = manifest();
+    let mut lock = lock();
+    lock.extensions[0]
+        .granted_permissions
+        .filesystem_write
+        .clear();
+    let outcome =
+        ExtensionCatalog::inspect([manifest.clone()], lock, [observation(&manifest, true)])
+            .unwrap()
+            .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Blocked);
+    let candidate = &outcome.evidence().candidates[0];
+    assert!(candidate.compatible);
+    assert!(!candidate.authorized);
+    assert!(candidate.available);
+    assert!(
+        candidate
+            .reasons
+            .iter()
+            .any(|reason| reason.contains("permissions exceed"))
+    );
+}
+
+#[test]
+fn missing_lock_entry_is_compatible_but_blocked_by_missing_authority() {
+    let unlocked = variant(&manifest(), "org.example.unlocked-adapter", 'a');
+    let outcome =
+        ExtensionCatalog::inspect([unlocked.clone()], lock(), [observation(&unlocked, true)])
+            .unwrap()
+            .resolve(&request());
+
+    assert_eq!(outcome.evidence().result, ResolutionResult::Blocked);
+    let candidate = &outcome.evidence().candidates[0];
+    assert!(candidate.compatible);
+    assert!(!candidate.authorized);
+    assert!(!candidate.available);
+    assert!(
+        candidate
+            .reasons
+            .iter()
+            .any(|reason| reason.contains("No operator lock entry authorizes"))
+    );
+}
+
+#[test]
+fn disabled_missing_and_integrity_mismatched_observations_are_unavailable() {
+    let base_manifest = manifest();
+
+    let mut disabled_lock = lock();
+    disabled_lock.extensions[0].enabled = false;
+    let disabled = ExtensionCatalog::inspect(
+        [base_manifest.clone()],
+        disabled_lock,
+        [observation(&base_manifest, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+    assert!(!disabled.evidence().candidates[0].available);
+
+    let mut trust_lock = lock();
+    trust_lock.extensions[0].trust = Trust::Disabled;
+    let trust_disabled = ExtensionCatalog::inspect(
+        [base_manifest.clone()],
+        trust_lock,
+        [observation(&base_manifest, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+    assert!(!trust_disabled.evidence().candidates[0].available);
+
+    let mut sandboxed_lock = lock();
+    sandboxed_lock.extensions[0].trust = Trust::Sandboxed;
+    let sandboxed = ExtensionCatalog::inspect(
+        [base_manifest.clone()],
+        sandboxed_lock,
+        [observation(&base_manifest, true)],
+    )
+    .unwrap()
+    .resolve(&request());
+    assert_eq!(sandboxed.evidence().result, ResolutionResult::Blocked);
+    assert!(!sandboxed.evidence().candidates[0].authorized);
+    assert!(!sandboxed.evidence().candidates[0].available);
+    assert!(
+        sandboxed.evidence().candidates[0]
+            .reasons
+            .iter()
+            .any(|reason| reason.contains("Sandboxed trust"))
+    );
+
+    let missing = ExtensionCatalog::inspect([base_manifest.clone()], lock(), []).unwrap();
+    assert!(!missing.resolve(&request()).evidence().candidates[0].available);
+
+    let mut mismatched = observation(&base_manifest, true);
+    mismatched.integrity.value = "a".repeat(64);
+    let mismatch = ExtensionCatalog::inspect([base_manifest], lock(), [mismatched])
+        .unwrap()
+        .resolve(&request());
+    assert!(!mismatch.evidence().candidates[0].available);
+}
+
+#[test]
+fn duplicate_observations_are_rejected_not_last_wins() {
+    let manifest = manifest();
+    let first = observation(&manifest, true);
+    let second = ExtensionObservation {
+        available: false,
+        ..first.clone()
+    };
+    assert!(ExtensionCatalog::inspect([manifest], lock(), [first, second]).is_err());
+}
+
+#[test]
+fn duplicate_observation_error_is_independent_of_input_order() {
+    let base = manifest();
+    let alpha = variant(&base, "org.example.alpha", 'a');
+    let beta = variant(&base, "org.example.beta", 'b');
+    let alpha_available = observation(&alpha, true);
+    let alpha_unavailable = observation(&alpha, false);
+    let beta_available = observation(&beta, true);
+    let beta_unavailable = observation(&beta, false);
+    let lock = lock_for(
+        &[alpha.clone(), beta.clone()],
+        &[100, 50],
+        FallbackPolicy::Forbidden,
+    );
+
+    let forward = ExtensionCatalog::inspect(
+        [alpha.clone(), beta.clone()],
+        lock.clone(),
+        [
+            beta_available.clone(),
+            beta_unavailable.clone(),
+            alpha_available.clone(),
+            alpha_unavailable.clone(),
+        ],
+    )
+    .unwrap_err();
+    let reverse = ExtensionCatalog::inspect(
+        [beta, alpha],
+        lock,
+        [
+            alpha_unavailable,
+            alpha_available,
+            beta_unavailable,
+            beta_available,
+        ],
+    )
+    .unwrap_err();
+
+    assert_eq!(forward, reverse);
+}
+
+#[test]
+fn caller_free_form_unavailability_text_cannot_enter_resolution_evidence() {
+    let manifest = manifest();
+    let mut encoded = serde_json::to_value(observation(&manifest, false)).unwrap();
+    encoded["unavailable_reason"] = serde_json::json!("/private/path?token=secret");
+    assert!(serde_json::from_value::<ExtensionObservation>(encoded).is_err());
+
+    let outcome =
+        ExtensionCatalog::inspect([manifest.clone()], lock(), [observation(&manifest, false)])
+            .unwrap()
+            .resolve(&request());
+    let evidence = serde_json::to_string(outcome.evidence()).unwrap();
+    assert!(!evidence.contains("private"));
+    assert!(!evidence.contains("secret"));
+}
+
+#[test]
+fn duplicate_extension_ids_are_rejected_even_when_versions_differ() {
+    let first = manifest();
+    let mut second = first.clone();
+    second.version = "0.1.1".to_owned();
+    let observations = [observation(&first, true), observation(&second, true)];
+
+    assert!(ExtensionCatalog::inspect([first, second], lock(), observations).is_err());
+}
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
new file mode 100644
index 0000000..27c6939
--- /dev/null
+++ b/tests/common/mod.rs
@@ -0,0 +1,105 @@
+#![allow(dead_code)]
+
+use std::collections::BTreeMap;
+
+use flow::{
+    Authorization, Configuration, Domain, EXTENSION_INVOCATION_V1, ExecutionModeKind,
+    ExtensionCatalog, ExtensionInvocation, ExtensionLock, ExtensionManifest, ExtensionObservation,
+    InvocationExtension, InvocationInterface, InvocationPhase, ResolutionRequest,
+    ResolvedExtension,
+};
+
+pub const CONFIG_DIGEST: &str = "3333333333333333333333333333333333333333333333333333333333333333";
+pub const GRANTS_DIGEST: &str = "4444444444444444444444444444444444444444444444444444444444444444";
+
+pub fn manifest() -> ExtensionManifest {
+    serde_json::from_str(include_str!(
+        "../../contracts/examples/extension-manifest.v1.example.json"
+    ))
+    .expect("checked-in manifest example must deserialize")
+}
+
+pub fn lock() -> ExtensionLock {
+    let mut lock: ExtensionLock = serde_json::from_str(include_str!(
+        "../../contracts/examples/extension-lock.v1.example.json"
+    ))
+    .expect("checked-in lock example must deserialize");
+    lock.extensions[0].trust = flow::Trust::Trusted;
+    lock
+}
+
+pub fn observation(manifest: &ExtensionManifest, available: bool) -> ExtensionObservation {
+    ExtensionObservation::new(
+        manifest.extension_id.clone(),
+        manifest.version.clone(),
+        manifest.publisher.id.clone(),
+        manifest.integrity.clone(),
+        available,
+    )
+}
+
+pub fn request() -> ResolutionRequest {
+    ResolutionRequest::new(
+        "test-case",
+        "optiflow/inspect-collection",
+        Domain::Optiflow,
+        "synthetic-library",
+        ExecutionModeKind::InProcess,
+    )
+}
+
+pub fn resolved_fixture() -> (ExtensionCatalog, ResolutionRequest) {
+    let manifest = manifest();
+    let observation = observation(&manifest, true);
+    let catalog = ExtensionCatalog::inspect([manifest], lock(), [observation])
+        .expect("fixture catalog must inspect");
+    (catalog, request())
+}
+
+pub fn invocation(resolved: &ResolvedExtension) -> ExtensionInvocation {
+    ExtensionInvocation {
+        schema_version: EXTENSION_INVOCATION_V1.to_owned(),
+        invocation_id: "invocation:test".to_owned(),
+        run_id: "run:test".to_owned(),
+        phase: InvocationPhase::Execute,
+        extension: InvocationExtension {
+            extension_id: resolved.extension_id().to_owned(),
+            version: resolved.version().to_owned(),
+            publisher_id: resolved.publisher_id().to_owned(),
+            integrity: resolved.integrity().value.clone(),
+        },
+        capability_id: resolved.capability().capability_id.clone(),
+        interface: InvocationInterface {
+            kind: resolved.execution_mode().kind,
+            name: resolved.execution_mode().name.clone(),
+            protocol: EXTENSION_INVOCATION_V1.to_owned(),
+        },
+        input_artifacts: Vec::new(),
+        expected_output_types: resolved.capability().produces.clone(),
+        configuration: Configuration {
+            schema_id: resolved.capability().configuration_schema.clone(),
+            digest: CONFIG_DIGEST.to_owned(),
+            values: BTreeMap::new(),
+        },
+        authorization: Authorization {
+            authorization_id: "authorization:test".to_owned(),
+            lock_id: resolved.lock_id().to_owned(),
+            grants_digest: GRANTS_DIGEST.to_owned(),
+        },
+        limits: resolved.execution_mode().limits.clone(),
+        checkpoint_refs: Vec::new(),
+        secret_handles: Vec::new(),
+        cancellation_id: "cancel:test".to_owned(),
+    }
+}
+
+pub fn variant(
+    base: &ExtensionManifest,
+    extension_id: &str,
+    digest_character: char,
+) -> ExtensionManifest {
+    let mut variant = base.clone();
+    extension_id.clone_into(&mut variant.extension_id);
+    variant.integrity.value = digest_character.to_string().repeat(64);
+    variant
+}
diff --git a/tests/contracts.rs b/tests/contracts.rs
new file mode 100644
index 0000000..a970995
--- /dev/null
+++ b/tests/contracts.rs
@@ -0,0 +1,238 @@
+use flow::{
+    ExtensionEvent, ExtensionInvocation, ExtensionLock, ExtensionManifest, ExtensionResolution,
+    ExtensionResult, FailureClassification, Outcome, ValidationEvidence, ValidationStatus,
+    parse_flow_version_requirement,
+};
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+
+fn roundtrip_and_validate<T>(source: &str, validate: impl FnOnce(&T))
+where
+    T: DeserializeOwned + Serialize,
+{
+    let value: serde_json::Value = serde_json::from_str(source).expect("fixture JSON must parse");
+    let typed: T = serde_json::from_value(value.clone()).expect("fixture must deserialize");
+    validate(&typed);
+    assert_eq!(serde_json::to_value(typed).expect("must serialize"), value);
+}
+
+#[test]
+fn six_checked_in_examples_roundtrip_and_validate() {
+    roundtrip_and_validate::<ExtensionManifest>(
+        include_str!("../contracts/examples/extension-manifest.v1.example.json"),
+        |value| value.validate().unwrap(),
+    );
+    roundtrip_and_validate::<ExtensionLock>(
+        include_str!("../contracts/examples/extension-lock.v1.example.json"),
+        |value| value.validate().unwrap(),
+    );
+    roundtrip_and_validate::<ExtensionInvocation>(
+        include_str!("../contracts/examples/extension-invocation.v1.example.json"),
+        |value| value.validate().unwrap(),
+    );
+    roundtrip_and_validate::<ExtensionEvent>(
+        include_str!("../contracts/examples/extension-event.v1.example.json"),
+        |value| value.validate().unwrap(),
+    );
+    roundtrip_and_validate::<ExtensionResult>(
+        include_str!("../contracts/examples/extension-result.v1.example.json"),
+        |value| value.validate().unwrap(),
+    );
+    roundtrip_and_validate::<ExtensionResolution>(
+        include_str!("../contracts/examples/extension-resolution.v1.example.json"),
+        |value| value.validate().unwrap(),
+    );
+}
+
+#[test]
+fn resolution_fixtures_remain_semantically_valid() {
+    for source in [
+        include_str!("../contracts/fixtures/extensions/incompatible-version.v1.fixture.json"),
+        include_str!("../contracts/fixtures/extensions/over-permissioned.v1.fixture.json"),
+        include_str!("../contracts/fixtures/extensions/duplicate-conflict.v1.fixture.json"),
+        include_str!("../contracts/fixtures/extensions/malformed.v1.fixture.json"),
+        include_str!("../contracts/fixtures/extensions/fallback.v1.fixture.json"),
+    ] {
+        let resolution: ExtensionResolution = serde_json::from_str(source).unwrap();
+        resolution.validate().unwrap();
+    }
+}
+
+#[test]
+fn closed_models_reject_unknown_root_and_nested_fields() {
+    let source = include_str!("../contracts/examples/extension-manifest.v1.example.json");
+    let mut root: serde_json::Value = serde_json::from_str(source).unwrap();
+    root.as_object_mut()
+        .unwrap()
+        .insert("surprise".to_owned(), serde_json::json!(true));
+    assert!(serde_json::from_value::<ExtensionManifest>(root).is_err());
+
+    let mut nested: serde_json::Value = serde_json::from_str(source).unwrap();
+    nested["publisher"]["surprise"] = serde_json::json!(true);
+    assert!(serde_json::from_value::<ExtensionManifest>(nested).is_err());
+}
+
+#[test]
+fn semver_requirements_require_comma_separated_comparators() {
+    assert!(parse_flow_version_requirement(">=0.1.0, <0.2.0").is_ok());
+    assert!(parse_flow_version_requirement(">=0.1.0 <0.2.0").is_err());
+    assert!(parse_flow_version_requirement("not-a-range").is_err());
+}
+
+#[test]
+fn manifest_semantics_reject_undeclared_domains_duplicate_ids_and_bad_hooks() {
+    let source = include_str!("../contracts/examples/extension-manifest.v1.example.json");
+    let mut manifest: ExtensionManifest = serde_json::from_str(source).unwrap();
+    manifest.capabilities[0].domain = flow::Domain::ThirdParty;
+    assert!(manifest.validate().is_err());
+
+    let mut manifest: ExtensionManifest = serde_json::from_str(source).unwrap();
+    manifest.capabilities[1].capability_id = manifest.capabilities[0].capability_id.clone();
+    assert!(manifest.validate().is_err());
+
+    let mut manifest: ExtensionManifest = serde_json::from_str(source).unwrap();
+    manifest.transform_hooks[0].accepts = vec!["application/mismatch".to_owned()];
+    assert!(manifest.validate().is_err());
+}
+
+#[test]
+fn result_outcome_and_failure_must_be_consistent() {
+    let source = include_str!("../contracts/examples/extension-result.v1.example.json");
+    let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+    result.failure.classification = FailureClassification::Provider;
+    assert!(result.validate().is_err());
+
+    result.outcome = Outcome::Failed;
+    result.failure.code = "provider.failed".to_owned();
+    result.failure.message = "The provider failed.".to_owned();
+    assert!(result.validate().is_ok());
+    result.failure.classification = FailureClassification::None;
+    assert!(result.validate().is_err());
+
+    for classification in [
+        FailureClassification::Unavailable,
+        FailureClassification::Cancelled,
+        FailureClassification::Unauthorized,
+        FailureClassification::Incompatible,
+    ] {
+        result.failure.classification = classification;
+        assert!(result.validate().is_err());
+    }
+}
+
+#[test]
+fn result_failure_payload_matches_its_classification() {
+    let source = include_str!("../contracts/examples/extension-result.v1.example.json");
+    let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+    result.failure.code = "unexpected".to_owned();
+    assert!(result.validate().is_err());
+
+    let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+    result.failure.message = "unexpected".to_owned();
+    assert!(result.validate().is_err());
+
+    let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+    result.failure.retryable = true;
+    assert!(result.validate().is_err());
+
+    let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+    result.outcome = Outcome::Failed;
+    result.failure.classification = FailureClassification::Provider;
+    assert!(result.validate().is_err());
+
+    result.failure.code = "provider.failed".to_owned();
+    assert!(result.validate().is_err());
+    result.failure.code.clear();
+    result.failure.message = "The provider failed.".to_owned();
+    assert!(result.validate().is_err());
+    result.failure.code = "provider.failed".to_owned();
+    assert!(result.validate().is_ok());
+}
+
+#[test]
+fn success_like_result_cannot_contain_failed_validation_evidence() {
+    let source = include_str!("../contracts/examples/extension-result.v1.example.json");
+    for outcome in [Outcome::Produced, Outcome::Reused, Outcome::Skipped] {
+        let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+        result.outcome = outcome;
+        result.validations.push(ValidationEvidence {
+            validator: "synthetic.adversarial/v1".to_owned(),
+            status: ValidationStatus::Failed,
+            evidence: "fixture:validation-failed".to_owned(),
+        });
+        assert!(result.validate().is_err());
+    }
+
+    for outcome in [Outcome::Produced, Outcome::Reused] {
+        let mut result: ExtensionResult = serde_json::from_str(source).unwrap();
+        result.outcome = outcome;
+        result.validations[0].status = ValidationStatus::NotRun;
+        assert!(result.validate().is_err());
+    }
+
+    let mut skipped: ExtensionResult = serde_json::from_str(source).unwrap();
+    skipped.outcome = Outcome::Skipped;
+    skipped.validations[0].status = ValidationStatus::NotRun;
+    assert!(skipped.validate().is_ok());
+}
+
+#[test]
+fn resolution_evidence_rejects_ambiguous_or_dangling_ids() {
+    let source = include_str!("../contracts/examples/extension-resolution.v1.example.json");
+
+    let mut duplicate: ExtensionResolution = serde_json::from_str(source).unwrap();
+    duplicate.candidates.push(duplicate.candidates[0].clone());
+    assert!(duplicate.validate().is_err());
+
+    let mut dangling: ExtensionResolution = serde_json::from_str(source).unwrap();
+    dangling.fallback_order = vec![
+        "org.example.unknown".to_owned(),
+        dangling.selected_extension_ids[0].clone(),
+    ];
+    assert!(dangling.validate().is_err());
+
+    let mut non_selected: ExtensionResolution = serde_json::from_str(include_str!(
+        "../contracts/fixtures/extensions/over-permissioned.v1.fixture.json"
+    ))
+    .unwrap();
+    non_selected.fallback_order = vec![non_selected.candidates[0].extension_id.clone()];
+    assert!(non_selected.validate().is_err());
+
+    let mut wrong_terminal: ExtensionResolution = serde_json::from_str(source).unwrap();
+    let mut other = wrong_terminal.candidates[0].clone();
+    "org.example.other-adapter".clone_into(&mut other.extension_id);
+    other.available = false;
+    wrong_terminal.candidates.push(other);
+    wrong_terminal.fallback_order = vec![
+        wrong_terminal.selected_extension_ids[0].clone(),
+        "org.example.other-adapter".to_owned(),
+    ];
+    assert!(wrong_terminal.validate().is_err());
+
+    let mut singleton: ExtensionResolution = serde_json::from_str(source).unwrap();
+    singleton.fallback_order = singleton.selected_extension_ids.clone();
+    assert!(singleton.validate().is_err());
+
+    let mut available_predecessor: ExtensionResolution = serde_json::from_str(source).unwrap();
+    let mut predecessor = available_predecessor.candidates[0].clone();
+    "org.example.available-predecessor".clone_into(&mut predecessor.extension_id);
+    predecessor.precedence = 50;
+    available_predecessor.candidates.push(predecessor);
+    available_predecessor.fallback_order = vec![
+        "org.example.available-predecessor".to_owned(),
+        available_predecessor.selected_extension_ids[0].clone(),
+    ];
+    assert!(available_predecessor.validate().is_err());
+
+    let mut increasing: ExtensionResolution = serde_json::from_str(source).unwrap();
+    let mut lower_unavailable = increasing.candidates[0].clone();
+    "org.example.lower-unavailable".clone_into(&mut lower_unavailable.extension_id);
+    lower_unavailable.precedence = 50;
+    lower_unavailable.available = false;
+    increasing.candidates.push(lower_unavailable);
+    increasing.fallback_order = vec![
+        "org.example.lower-unavailable".to_owned(),
+        increasing.selected_extension_ids[0].clone(),
+    ];
+    assert!(increasing.validate().is_err());
+}
diff --git a/tests/execution.rs b/tests/execution.rs
new file mode 100644
index 0000000..f1f59f5
--- /dev/null
+++ b/tests/execution.rs
@@ -0,0 +1,456 @@
+mod common;
+
+use std::cell::Cell;
+
+use flow::{
+    EventKind, EventSink, EventSinkError, EventState, ExecutionError, ExtensionEvent,
+    ExtensionInvocation, ExtensionPort, ExtensionResult, HermeticBehavior, HermeticExtension,
+    InputArtifact, Orchestrator, Outcome, PortError, PortIdentity, ValidationEvidence,
+    ValidationStatus,
+};
+
+use common::{invocation, resolved_fixture};
+
+#[test]
+fn hermetic_success_accepts_strictly_increasing_sequences_with_gaps() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved));
+    let mut observed = Vec::new();
+
+    let validated = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap();
+
+    assert_eq!(
+        validated
+            .events()
+            .iter()
+            .map(|event| event.sequence)
+            .collect::<Vec<_>>(),
+        [0, 2]
+    );
+    assert_eq!(validated.result().outcome, Outcome::Produced);
+    assert_eq!(observed, validated.events());
+}
+
+#[test]
+fn duplicate_or_decreasing_event_sequence_is_rejected_and_retained() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::DuplicateSequence);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidEvent { .. }));
+    assert_eq!(error.events().len(), 2);
+    assert_eq!(observed.len(), 1, "invalid event is not forwarded");
+}
+
+#[test]
+fn cross_invocation_event_is_rejected_and_retained() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::MismatchedEventInvocation);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidEvent { .. }));
+    assert_eq!(
+        error.events()[1].invocation_id,
+        "invocation:adversarial-mismatch"
+    );
+    assert_eq!(observed.len(), 1);
+}
+
+#[test]
+fn provider_reported_success_remains_unaccepted_evidence_on_identity_mismatch() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::MismatchedResultCapability);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+    let raw_result = error.provider_result().expect("raw result is retained");
+    assert_eq!(raw_result.outcome, Outcome::Produced);
+    assert_eq!(raw_result.capability_id, "flow/adversarial-mismatch");
+    assert_eq!(error.events().len(), 2);
+}
+
+#[test]
+fn outcome_failure_inconsistency_is_rejected_after_invoke() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::InconsistentOutcomeFailure);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+    assert_eq!(error.provider_result().unwrap().outcome, Outcome::Produced);
+}
+
+#[test]
+fn provider_failure_after_invoke_never_attempts_fallback() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::PortFailure);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::Provider { .. }));
+    assert_eq!(error.events().len(), 1);
+}
+
+#[test]
+fn mismatched_port_is_rejected_before_invocation() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let mut identity = PortIdentity::from_resolved(resolved);
+    identity.integrity = "a".repeat(64);
+    let port = CountingPort {
+        identity,
+        calls: Cell::new(0),
+    };
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::Preflight { .. }));
+    assert_eq!(port.calls.get(), 0);
+    assert!(observed.is_empty());
+}
+
+#[test]
+fn invocation_identity_mismatch_is_rejected_before_invocation() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let mut invocation = invocation(resolved);
+    invocation.extension.version = "9.9.9".to_owned();
+    let port = CountingPort {
+        identity: PortIdentity::from_resolved(resolved),
+        calls: Cell::new(0),
+    };
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::Preflight { .. }));
+    assert_eq!(port.calls.get(), 0);
+}
+
+#[test]
+fn every_terminal_result_identity_is_correlated() {
+    let mutations: [fn(&mut ExtensionResult); 8] = [
+        |result| "run:mismatch".clone_into(&mut result.run_id),
+        |result| "invocation:mismatch".clone_into(&mut result.invocation_id),
+        |result| "org.example.mismatch".clone_into(&mut result.extension_id),
+        |result| "9.9.9".clone_into(&mut result.extension_version),
+        |result| result.extension_integrity = "a".repeat(64),
+        |result| "flow/mismatch".clone_into(&mut result.capability_id),
+        |result| result.configuration_digest = "a".repeat(64),
+        |result| "authorization:mismatch".clone_into(&mut result.authorization_id),
+    ];
+
+    for mutate in mutations {
+        let (catalog, request) = resolved_fixture();
+        let outcome = catalog.resolve(&request);
+        let resolved = outcome.resolved().unwrap();
+        let invocation = invocation(resolved);
+        let port = MutatingResultPort {
+            inner: HermeticExtension::new(PortIdentity::from_resolved(resolved)),
+            mutate,
+        };
+        let mut observed = Vec::new();
+
+        let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+        assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+        assert_eq!(error.provider_result().unwrap().outcome, Outcome::Produced);
+    }
+}
+
+#[test]
+fn downstream_event_sink_rejection_fails_execution_without_losing_raw_event() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved));
+    let mut sink = RejectingSink;
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut sink).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::EventSink { .. }));
+    assert_eq!(error.events().len(), 1);
+    assert!(error.provider_result().is_none());
+}
+
+#[test]
+fn unredacted_event_diagnostic_is_rejected_before_observation() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::UnredactedEventDiagnostic);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidEvent { .. }));
+    assert_eq!(error.events().len(), 2);
+    assert!(!error.events()[1].diagnostics[0].redacted);
+    assert_eq!(observed.len(), 1, "unredacted event is not forwarded");
+}
+
+#[test]
+fn unredacted_result_diagnostic_is_retained_but_never_validated() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = HermeticExtension::new(PortIdentity::from_resolved(resolved))
+        .with_behavior(HermeticBehavior::UnredactedResultDiagnostic);
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+    assert!(!error.provider_result().unwrap().diagnostics[0].redacted);
+}
+
+#[test]
+fn provider_success_with_failed_validation_is_retained_but_not_accepted() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+    let port = MutatingResultPort {
+        inner: HermeticExtension::new(PortIdentity::from_resolved(resolved)),
+        mutate: |result| {
+            result.validations.push(ValidationEvidence {
+                validator: "synthetic.adversarial/v1".to_owned(),
+                status: ValidationStatus::Failed,
+                evidence: "fixture:validation-failed".to_owned(),
+            });
+        },
+    };
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+    assert_eq!(
+        error.provider_result().unwrap().validations[0].status,
+        ValidationStatus::Failed
+    );
+}
+
+#[test]
+fn consumed_artifact_identifiers_must_name_invocation_inputs() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let mut invocation = invocation(resolved);
+    invocation.input_artifacts.push(InputArtifact {
+        artifact_id: "artifact:declared-input".to_owned(),
+        digest: "5".repeat(64),
+    });
+
+    let matching_port = MutatingResultPort {
+        inner: HermeticExtension::new(PortIdentity::from_resolved(resolved)),
+        mutate: |result| {
+            result
+                .consumed_artifacts
+                .push("artifact:declared-input".to_owned());
+        },
+    };
+    let mut observed = Vec::new();
+    Orchestrator::execute(resolved, &invocation, &matching_port, &mut observed).unwrap();
+
+    let unknown_port = MutatingResultPort {
+        inner: HermeticExtension::new(PortIdentity::from_resolved(resolved)),
+        mutate: |result| {
+            result
+                .consumed_artifacts
+                .push("artifact:undeclared-input".to_owned());
+        },
+    };
+    let mut observed = Vec::new();
+    let error =
+        Orchestrator::execute(resolved, &invocation, &unknown_port, &mut observed).unwrap_err();
+    assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+}
+
+#[test]
+fn duplicate_invocation_artifact_identifiers_are_rejected_before_invocation() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let mut invocation = invocation(resolved);
+    invocation.input_artifacts = vec![
+        InputArtifact {
+            artifact_id: "artifact:ambiguous".to_owned(),
+            digest: "5".repeat(64),
+        },
+        InputArtifact {
+            artifact_id: "artifact:ambiguous".to_owned(),
+            digest: "6".repeat(64),
+        },
+    ];
+    let port = CountingPort {
+        identity: PortIdentity::from_resolved(resolved),
+        calls: Cell::new(0),
+    };
+    let mut observed = Vec::new();
+
+    let error = Orchestrator::execute(resolved, &invocation, &port, &mut observed).unwrap_err();
+
+    assert!(matches!(error, ExecutionError::InvalidInvocation { .. }));
+    assert_eq!(port.calls.get(), 0);
+}
+
+#[test]
+fn artifact_produced_events_correlate_with_terminal_result_identifiers() {
+    let (catalog, request) = resolved_fixture();
+    let outcome = catalog.resolve(&request);
+    let resolved = outcome.resolved().unwrap();
+    let invocation = invocation(resolved);
+
+    let matching_port = ArtifactEventPort {
+        inner: HermeticExtension::new(PortIdentity::from_resolved(resolved)),
+        declare_in_result: true,
+    };
+    let mut observed = Vec::new();
+    let validated =
+        Orchestrator::execute(resolved, &invocation, &matching_port, &mut observed).unwrap();
+    assert_eq!(validated.events().len(), 3);
+
+    let missing_port = ArtifactEventPort {
+        inner: HermeticExtension::new(PortIdentity::from_resolved(resolved)),
+        declare_in_result: false,
+    };
+    let mut observed = Vec::new();
+    let error =
+        Orchestrator::execute(resolved, &invocation, &missing_port, &mut observed).unwrap_err();
+    assert!(matches!(error, ExecutionError::InvalidResult { .. }));
+    assert_eq!(error.events().len(), 3);
+}
+
+struct CountingPort {
+    identity: PortIdentity,
+    calls: Cell<u64>,
+}
+
+impl ExtensionPort for CountingPort {
+    fn identity(&self) -> &PortIdentity {
+        &self.identity
+    }
+
+    fn invoke(
+        &self,
+        _invocation: &ExtensionInvocation,
+        _events: &mut dyn EventSink,
+    ) -> Result<ExtensionResult, PortError> {
+        self.calls.set(self.calls.get() + 1);
+        Err(PortError::new("counting port should not have been invoked"))
+    }
+}
+
+struct MutatingResultPort {
+    inner: HermeticExtension,
+    mutate: fn(&mut ExtensionResult),
+}
+
+impl ExtensionPort for MutatingResultPort {
+    fn identity(&self) -> &PortIdentity {
+        self.inner.identity()
+    }
+
+    fn invoke(
+        &self,
+        invocation: &ExtensionInvocation,
+        events: &mut dyn EventSink,
+    ) -> Result<ExtensionResult, PortError> {
+        let mut result = self.inner.invoke(invocation, events)?;
+        (self.mutate)(&mut result);
+        Ok(result)
+    }
+}
+
+struct RejectingSink;
+
+impl EventSink for RejectingSink {
+    fn emit(&mut self, _event: &ExtensionEvent) -> Result<(), EventSinkError> {
+        Err(EventSinkError::new("observer rejected event"))
+    }
+}
+
+struct ArtifactEventPort {
+    inner: HermeticExtension,
+    declare_in_result: bool,
+}
+
+impl ExtensionPort for ArtifactEventPort {
+    fn identity(&self) -> &PortIdentity {
+        self.inner.identity()
+    }
+
+    fn invoke(
+        &self,
+        invocation: &ExtensionInvocation,
+        events: &mut dyn EventSink,
+    ) -> Result<ExtensionResult, PortError> {
+        let mut injecting_sink = ArtifactInjectingSink { downstream: events };
+        let mut result = self.inner.invoke(invocation, &mut injecting_sink)?;
+        if self.declare_in_result {
+            result
+                .produced_artifacts
+                .push("artifact:synthetic-output".to_owned());
+        }
+        Ok(result)
+    }
+}
+
+struct ArtifactInjectingSink<'a> {
+    downstream: &'a mut dyn EventSink,
+}
+
+impl EventSink for ArtifactInjectingSink<'_> {
+    fn emit(&mut self, event: &ExtensionEvent) -> Result<(), EventSinkError> {
+        if event.kind == EventKind::PhaseCompleted {
+            let mut artifact_event = event.clone();
+            artifact_event.event_id.push_str(":artifact");
+            artifact_event.sequence = event.sequence.saturating_sub(1);
+            artifact_event.kind = EventKind::ArtifactProduced;
+            artifact_event.state = EventState::Running;
+            artifact_event.progress.completed = 0;
+            artifact_event.artifact_refs = vec!["artifact:synthetic-output".to_owned()];
+            self.downstream.emit(&artifact_event)?;
+        }
+        self.downstream.emit(event)
+    }
+}

From f3769e004621de4d62dfbbf5cedb48ea9d2a7a5f Mon Sep 17 00:00:00 2001
From: Alan Szmyt <szmyty@gmail.com>
Date: Wed, 16 Sep 2026 08:02:08 -0400
Subject: [PATCH 2/2] ci: install validator dependency

Install the pinned PyYAML dependency before running the repository specification validator.

Roadmap-Step: FLO-Q02
---
 .github/workflows/ci.yml | 3 +++
 requirements-ci.txt      | 1 +
 2 files changed, 4 insertions(+)
 create mode 100644 requirements-ci.txt

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9363cde..c20a7e7 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -67,6 +67,9 @@ jobs:
         with:
           python-version: "3.x"
 
+      - name: Install validator dependencies
+        run: python3 -m pip install --disable-pip-version-check --requirement requirements-ci.txt
+
       - name: Validate contracts
         run: python3 tools/validate_contracts.py
 
diff --git a/requirements-ci.txt b/requirements-ci.txt
new file mode 100644
index 0000000..f62ce0c
--- /dev/null
+++ b/requirements-ci.txt
@@ -0,0 +1 @@
+PyYAML==6.0.3