Seal prepared request capabilities for v0.4.4 (#29)

Author: 0xmrma

CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes are documented here. MRMA follows semantic versioning for the CLI and uses an
 independent version in each machine-readable evidence schema.
 
+## 0.4.4 - 2026-08-07
+
+### Prepared Request Boundary
+
+- Replace the public raw HTTPX request field with an opaque prepared capability that preserves the
+  existing import name while exposing only reservation metadata. An adapter-local HMAC seal binds
+  request identity, authorization identity, mutation delta, arm, round, and accounting values.
+- Recompute the final method, URL, ordered raw fields, buffered content and send stream, extensions,
+  effective `Host`, and represented size immediately before network I/O. Mutation, malformed
+  buffering, cross-adapter use, and capability metadata changes fail before `ATTEMPT_STARTED`.
+- Require the buffered content and actual HTTPX send stream to have identical lengths and digests
+  before a request can be reserved.
+- Bind each prepared capability to one observation session and consume it before the network call,
+  preventing stale-session and repeated-lease replay.
+
+### Mutation And Evidence Precision
+
+- Enforce one-dimensional header experiments: method, target, declared HTTP version, target form,
+  and body must remain identical. Unsupported mutation families fail closed instead of receiving a
+  generic fingerprint binding, while unchanged exploratory control sends remain valid.
+- Add `changed_dimensions` to mutation validation and bind it into the deterministic local delta
+  digest under `authorization-policy/2.1`.
+- Replace deterministic mutation-delta values in journals with adapter-local HMAC fingerprints and
+  declare those identifiers as run-local in v8 evidence without changing the frozen schema.
+
+### Validation And Governance
+
+- Synchronize architecture, budget, API, evidence, and validation documentation with the
+  prepare-reserve-revalidate-send capability boundary.
+- Require the `semantic-mutation` and `benchmark` jobs in the protected `main` ruleset alongside the
+  existing matrix, audit, distribution, container, evidence-quality, and CodeQL checks.
+- Expand the suite to 348 tests and the committed critical-policy catalog to 39 mutants, all killed.
+
 ## 0.4.3 - 2026-08-07
 
 ### Authorization Precision

README.md

@@ -16,7 +16,7 @@
   verifiable evidence.
 </p>
 
-> **Current release: v0.4.3.** MRMA uses semantic HTTP through HTTPX. It does not claim wire-exact
+> **Current release: v0.4.4.** MRMA uses semantic HTTP through HTTPX. It does not claim wire-exact
 > replay, prove exploitability, assign severity, or identify a proprietary component from
 > black-box behavior.
 
@@ -74,7 +74,7 @@ Comparison + fixed-sample conclusion
 ## Install
 
 ```bash
-python -m pip install mrma==0.4.3
+python -m pip install mrma==0.4.4
 mrma --version
 ```
 
@@ -83,8 +83,8 @@ MRMA is tested on Python 3.10 and 3.13 across Linux, Windows, and macOS.
 The published container supports Linux AMD64 and ARM64:
 
 ```bash
-docker pull ghcr.io/0xmrma/mrma:0.4.3
-docker run --rm ghcr.io/0xmrma/mrma:0.4.3 --version
+docker pull ghcr.io/0xmrma/mrma:0.4.4
+docker run --rm ghcr.io/0xmrma/mrma:0.4.4 --version
 ```
 
 ## Start without network traffic

docs/API.md

@@ -75,6 +75,12 @@ declared aggregate capacity, target/mutation/hook authorization, and request bou
 consuming repetition or budget. `PlanSummary.approval_plan_digest` is a deterministic local identity;
 `PlanSummary.to_dict()` deliberately excludes it from shared evidence.
 
+`SemanticHttpAdapter.prepare()` returns an opaque adapter-issued capability exposing reservation
+metadata such as `represented_bytes`; it does not expose the mutable HTTPX request. Pass that
+capability directly to `send_prepared()` after reserving its exact represented size. Capabilities
+are bound to one adapter and observation session, are single-use, and are revalidated immediately
+before network I/O.
+
 ## Evidence APIs
 
 - `build_experiment_v8`: convert an `OracleRunResult` plus provenance into strict evidence.

docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 ## Product boundary
 
-MRMA v0.4.3 has one confirmatory engine and one shared network policy kernel. The CLI parses input,
+MRMA v0.4.4 has one confirmatory engine and one shared network policy kernel. The CLI parses input,
 selects workflow policy, and renders output. It does not own transport authorization decisions.
 
 ```text
@@ -14,7 +14,9 @@ ExperimentPlan + ComparisonPolicy
         v
 ExperimentOracle
   | authorization -> AuthorizedRequestContext
-  | budget        -> BudgetLease
+  | prepare       -> opaque, adapter-sealed request capability
+  | budget        -> BudgetLease for the prepared representation
+  | revalidate    -> authorization + prepared capability
   | journal       -> EvidenceContext
         |
         v
@@ -26,10 +28,19 @@ CapturedResponse -> experiment analysis -> v8 evidence -> bundle
 
 ## Enforced boundaries
 
-`SemanticHttpAdapter.send()` requires all three unforgeable-in-normal-use capability objects:
-an accepted `AuthorizedRequestContext`, an active `BudgetLease`, and an `EvidenceContext`. The
-adapter revalidates context identity, records `ATTEMPT_STARTED`, performs one semantic HTTP
-attempt, commits actual bounded cost, and records completion. It cannot be called with only a URL.
+`SemanticHttpAdapter.prepare()` builds the final HTTPX request and returns an opaque capability with
+safe accounting metadata; the mutable HTTPX object is not exported. The capability is sealed with
+an adapter-local key over the authorization identity, arm, round, accounting values, mutation
+delta, and a digest of the final method, URL, ordered raw fields, buffered content and stream,
+extensions, effective `Host`, and represented size.
+
+`SemanticHttpAdapter.send_prepared()` requires that capability plus an accepted
+`AuthorizedRequestContext`, active `BudgetLease`, and matching `EvidenceContext`. Immediately before
+network I/O it recomputes the request digest, verifies the adapter seal, repeats method/URL/`Host`
+authorization checks, and compares actual body and representation sizes with the reservation. A
+changed, stale-session, or already-consumed capability fails before `ATTEMPT_STARTED`. `send()` is
+the single-call convenience path through the same prepare and send-prepared boundary; neither
+method can be called with only a URL.
 
 `ExperimentOracle` owns retries, redirect traversal, setup/reset hooks, schedules, observations,
 and partial-run conversion. One observation session owns redirect/retry cookie state and its
@@ -41,7 +52,8 @@ HTTPX-built request so eligible cookie-jar state cannot bypass raw-field filteri
 
 - `mrma.engine`: typed plan and confirmatory oracle.
 - `mrma.policy`: authorization, budgets, comparison, method risk, and protocol interfaces.
-- `mrma.transport`: semantic HTTP adapter and request-byte estimator.
+- `mrma.transport`: semantic HTTP adapter, opaque prepared capability, and request-byte estimator.
+  The capability preserves the public type name but does not expose a public HTTPX request field.
 - `mrma.evidence`: append-only journal, v8 model, schema validation, bundles, and verification.
 - `mrma.workflows`: candidate manifests and guarded legacy exploratory dispatch.
 - `mrma.core`: comparison, statistical experiment, HTTP semantics, request model, and retained

docs/BUDGET_MODEL.md

@@ -13,10 +13,11 @@ For each network attempt MRMA:
 
 1. authorizes the immutable request and any declared mutation delta;
 2. asks HTTPX to build the final request, including cookie-jar and generated fields;
-3. measures that prepared representation and checks effective method, target, and `Host` again;
+3. measures and seals that prepared representation after checking method, target, and `Host`;
 4. atomically reserves counters, bytes, timeout, and concurrency;
 5. revalidates authorization and records `BUDGET_RESERVED` plus `ATTEMPT_STARTED`;
-6. sends the exact prepared request object once;
+6. recomputes the prepared digest, verifies the adapter seal and authorization fields, then sends
+   the exact request object once;
 7. commits bounded actual bytes and elapsed duration, or releases the lease;
 8. records `BUDGET_UPDATED`.
 

docs/EVIDENCE_MODEL.md

@@ -47,7 +47,9 @@ summary and digest, not the executable authorization manifest. Raw credentials,
 authorization tokens, environment values, mutation secrets, and local paths are forbidden by model
 and tests. Version 8 declares cross-run correlation as partial because authorization digests,
 original-source digests, and journal target, origin, address-set, and effective-authority
-identifiers are deterministic.
+identifiers are deterministic. Mutation-delta identifiers written to the journal are run-local
+HMAC fingerprints; the deterministic local delta digest remains inside the authorization and
+transport capability boundary.
 
 ## Bundle
 

docs/RELEASE_SECURITY.md

@@ -22,20 +22,20 @@ Install a current GitHub CLI, authenticate it, download both distributions, and
 GitHub-signed build provenance before installation:
 
 ```bash
-gh release verify v0.4.3 -R 0xmrma/mrma
-gh release download v0.4.3 -R 0xmrma/mrma \
-  --pattern 'mrma-0.4.3-py3-none-any.whl' \
-  --pattern 'mrma-0.4.3.tar.gz'
-gh release verify-asset v0.4.3 ./mrma-0.4.3-py3-none-any.whl -R 0xmrma/mrma
-gh release verify-asset v0.4.3 ./mrma-0.4.3.tar.gz -R 0xmrma/mrma
-gh attestation verify ./mrma-0.4.3-py3-none-any.whl \
+gh release verify v0.4.4 -R 0xmrma/mrma
+gh release download v0.4.4 -R 0xmrma/mrma \
+  --pattern 'mrma-0.4.4-py3-none-any.whl' \
+  --pattern 'mrma-0.4.4.tar.gz'
+gh release verify-asset v0.4.4 ./mrma-0.4.4-py3-none-any.whl -R 0xmrma/mrma
+gh release verify-asset v0.4.4 ./mrma-0.4.4.tar.gz -R 0xmrma/mrma
+gh attestation verify ./mrma-0.4.4-py3-none-any.whl \
   -R 0xmrma/mrma \
   --signer-workflow 0xmrma/mrma/.github/workflows/release.yml \
-  --source-ref refs/tags/v0.4.3
-gh attestation verify ./mrma-0.4.3.tar.gz \
+  --source-ref refs/tags/v0.4.4
+gh attestation verify ./mrma-0.4.4.tar.gz \
   -R 0xmrma/mrma \
   --signer-workflow 0xmrma/mrma/.github/workflows/release.yml \
-  --source-ref refs/tags/v0.4.3
+  --source-ref refs/tags/v0.4.4
 ```
 
 Release v0.4.0 predates repository release-immutability enablement. Its protected signed tag and
@@ -47,18 +47,18 @@ release-level attestation when published.
 Verify the container's GitHub-signed provenance and require the publishing workflow and tag ref:
 
 ```bash
-gh attestation verify oci://ghcr.io/0xmrma/mrma:0.4.3 \
+gh attestation verify oci://ghcr.io/0xmrma/mrma:0.4.4 \
   -R 0xmrma/mrma \
   --signer-workflow 0xmrma/mrma/.github/workflows/package.yml \
-  --source-ref refs/tags/v0.4.3
+  --source-ref refs/tags/v0.4.4
 ```
 
 The image also carries BuildKit provenance and SBOM manifests. Resolve the immutable OCI index
 digest and pin deployments to `ghcr.io/0xmrma/mrma@sha256:...` rather than relying only on a
 mutable semantic-version tag:
 
 ```bash
-docker buildx imagetools inspect ghcr.io/0xmrma/mrma:0.4.3
+docker buildx imagetools inspect ghcr.io/0xmrma/mrma:0.4.4
 ```
 
 Verification establishes artifact identity and build origin. It does not replace source review,

docs/RESEARCH_POSITION.md

@@ -38,7 +38,7 @@ MRMA should treat every finding as an experiment, not an anomaly row:
 7. Minimize the responsible input using the same repeated oracle.
 8. Export a versioned evidence object that another engineer can replay and audit.
 
-Version 0.4.3 implements steps 1-6 for a single mutation in `mrma experiment`, including explicit
+Version 0.4.4 implements steps 1-6 for a single mutation in `mrma experiment`, including explicit
 state and connection modes, fixed-sample confidence decisions, canonical redirect and field-aware
 header semantics, ambiguity-preserving cache comparison, typed retry subtypes, multidimensional
 assurance, bounded observations, authorization, central budgets, recoverable evidence, and manual

docs/ROADMAP.md

@@ -112,7 +112,16 @@ adding more mutation families.
 - [x] Add a deterministic local approval-plan digest without exposing it in shared evidence
 - [x] Disable new v7 generation while retaining verification of existing v7 documents
 
-Version 0.4.3 is the maintained 0.4 baseline. The items below are optional research directions,
+## 0.4.4 - SDK boundary freeze
+
+- [x] Seal prepared HTTPX request identity and capability metadata; bind capabilities to one session
+- [x] Recompute request, stream, extension, authority, and accounting identity before send
+- [x] Restrict header experiments to header-only deltas and reject unsupported families
+- [x] Make journal mutation-delta identifiers run-local
+- [x] Require benchmark and semantic-mutation checks on protected `main`
+- [x] Synchronize SDK, architecture, budget, evidence, and validation contracts
+
+Version 0.4.4 is the maintained 0.4 baseline. The items below are optional research directions,
 not commitments or current product claims.
 
 ## Possible 0.5 - Product-wide evidence oracle

docs/VALIDATION.md

@@ -2,7 +2,7 @@
 
 ## Exact claim
 
-MRMA v0.4.3 is an authorization-enforcing, budgeted, recoverable HTTP trust-influence
+MRMA v0.4.4 is an authorization-enforcing, budgeted, recoverable HTTP trust-influence
 tool. It uses semantic HTTP replay and fixed-sample differential experiments.
 
 ## Non-claims
@@ -56,7 +56,10 @@ may vary; conclusions must all pass. See [BENCHMARKS.md](BENCHMARKS.md).
 - No stable connected-address, peer-certificate, cipher, or ALPN evidence on the supported adapter.
 - `impact` and other legacy workflows are policy guarded but remain statistically exploratory.
 - The CLI is not fully decomposed; the stable engine/policy/evidence APIs are separate.
-- Request sent-byte accounting is conservative estimation, not wire telemetry.
+- Plan request bytes are a conservative preflight estimate. Every attempt reserves the measured
+  final HTTPX request representation, including generated and cookie fields, after preparation and
+  verifies the sealed representation again immediately before sending. Neither value is wire
+  telemetry.
 - Hash chains provide integrity detection, not organizational identity.
 - No signed authorization grants, encrypted evidence store, distributed budgets, or multi-user
   governance.