@zhivex-ai/harness 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to Zhivex Harness are documented in this file.
 
 The project follows Semantic Versioning. During `0.x`, minor releases may change user-facing contracts when the change is documented with a migration note. Patch releases remain backwards compatible bug fixes.
 
+## 0.9.0 - 2026-08-20
+
+### Added
+
+- `ChangeEnvelope v1`, a deterministic, agent-agnostic and offline-verifiable change-admission document that binds base/tree identity, exact patch bytes, harness/policy/environment fingerprints, redacted check evidence, expiry, approval references, and optional external attestation references.
+- `zhx changes create` and `zhx changes verify` for binding an exact patch artifact and validating integrity, expiry, and caller-supplied preconditions without loading a provider or contacting a network service.
+- Bounded `read_files` and `search_many` tools so independent repository lookups share one model/tool round trip and multi-query search reads each candidate file once.
+- A reproducible `bun run benchmark:workspace` fixture plus workspace-index and OCI I/O diagnostics.
+- A reproducible `bun run benchmark:oci` fixture for first-command, warm no-op, mutation, and snapshot latency.
+
+### Changed
+
+- Workspace pagination now reuses a topology-only, freshness-checked index with binary path lookup. File contents and digests are still read through the race-sensitive stable-read path; structural changes invalidate active cursors.
+- OCI snapshots retain metadata rather than the full repository contents in memory, write the immutable base once, and use copy-on-write cloning with a portable copy fallback for the mutable workspace. Patch inspection rereads content only for changed files.
+- OCI commands now reuse one paused container per acquired run. Unchanged canonical workspace seals skip export, changed workspaces still publish through a validated atomic staging directory, and failures, background processes, or host-snapshot divergence destroy and reseed the warm session.
+
+### Performance
+
+- On the local 5,000-file benchmark, listing all 25 pages of 200 files decreased from about 3.02 seconds to 0.38 seconds, and the first page decreased from about 118 ms to 42 ms. These figures are development-machine observations, not cross-platform release guarantees.
+- On the local 1,001-file Docker benchmark, warm no-op OCI commands decreased from about 838 ms to roughly 0.31–0.37 seconds median. Commands that change the workspace retain the full validation/export path. These figures are development-machine observations, not cross-platform release guarantees.
+
+### Migration from 0.8.x
+
+- Complete or deny paused `0.8.x` approvals with the matching `0.8.x` artifact. The workspace tool contract fingerprint changed to include the new batch tools, so `0.9.x` intentionally refuses to resume those approvals under a different tool surface.
+- Configuration schema `4`, the durable store, existing single-file tools, and both CLI executable aliases remain compatible. The OCI policy fingerprint advances because isolation changes from per-tool-call containers to a paused per-run container; complete or deny paused OCI approvals with the matching older artifact. Callers can adopt `read_files`, `search_many`, and change envelopes incrementally.
+
+### Security
+
+- Change-envelope verification proves canonical integrity, rejects future creation/check evidence, enforces expiration, exact patch binding, and explicit preconditions only. Approval and external-attestation authenticity is reported as `not-verified` and requires an external trust verifier.
+- The workspace index never caches file contents or content digests. It validates directory and ignore-rule fingerprints before reuse, rejects stale topology-bound cursors, and invalidates after every harness mutation and declared check.
+- Warm OCI reuse never mounts the durable host snapshot writable. Commands are serialized; background processes fail closed; `/tmp` is cleared after success; and any failed or divergent session is destroyed before a later command reseeds from the last published snapshot.
+
 ## 0.8.0 - 2026-08-20
 
 ### Changed

package/README.md

@@ -13,7 +13,7 @@ Zhivex Harness runs coding agents against real repositories with conflict-safe e
 
 The model provides capability. The harness controls what it may inspect, execute, change, resume, and prove. Every provider uses the same bounded tool and approval contract.
 
-Version `0.8.0` is the source release candidate for the coordinated SDK refresh and GPT-5.6-first OpenAI integration. The latest public npm release is `0.7.0`; local validation does not imply that `0.8.0` has been published or release-certified. See [ROADMAP.md](./ROADMAP.md), [CHANGELOG.md](./CHANGELOG.md), the [CLI contract](./docs/CLI.md), the [extensibility guide](./docs/EXTENSIBILITY.md), and the [durable-operations guide](./docs/DURABLE_OPERATIONS.md).
+Version `0.9.0` is the source candidate for faster governed repository inspection and the agent-agnostic `ChangeEnvelope v1` admission contract. The latest public npm release is `0.8.0`; local validation does not imply that `0.9.0` has been published or release-certified. See [ROADMAP.md](./ROADMAP.md), [CHANGELOG.md](./CHANGELOG.md), the [change-envelope guide](./docs/CHANGE_ENVELOPES.md), the [CLI contract](./docs/CLI.md), the [extensibility guide](./docs/EXTENSIBILITY.md), and the [durable-operations guide](./docs/DURABLE_OPERATIONS.md).
 
 ## Why Zhivex Harness
 
@@ -40,7 +40,15 @@ bun run demo:hostile
 
 The expected result is a schema-versioned JSON proof with `secretExcluded`, `networkDenied`, `exactlyOnceJournal`, and `staleHostImportBlocked` all set to `true`. Pass `--keep` to retain the disposable workspace for inspection. The complete scenario and evidence limits are documented in [docs/HOSTILE_REPOSITORY_DEMO.md](./docs/HOSTILE_REPOSITORY_DEMO.md).
 
-## What 0.8 changes
+## What 0.9 changes
+
+- reuses a freshness-checked topology index across file-list and search pages while reading current file bytes for every digest;
+- adds bounded `read_files` and `search_many` tools that reduce model/tool round trips without parallelizing writes;
+- reuses a paused OCI container within an acquired run, skips exports for unchanged workspace seals, and reseeds after failures or host-snapshot changes without weakening the reviewed host-import boundary;
+- adds a reproducible workspace benchmark and observable index/OCI I/O counters; and
+- introduces deterministic, offline-verifiable `ChangeEnvelope v1` documents bound to exact patch bytes, base identity, runtime policy, redacted checks, expiry, and optional approval/attestation references.
+
+## What 0.8 changed
 
 - updates the coordinated Zhivex SDK batch while retaining a single Core runtime identity;
 - makes `gpt-5.6-luna` the OpenAI default, with Terra and Sol available through explicit model selection; and
@@ -68,7 +76,7 @@ The expected result is a schema-versioned JSON proof with `secretExcluded`, `net
 - governed MCP over bounded HTTPS/loopback HTTP with explicit server/tool allowlists, permissions, timeouts, approvals, output limits, and environment-backed credentials;
 - named explorer, implementer, tester, and reviewer subagents with independent durable budgets and promoted approvals;
 - deterministic application-owned parallel read-only review groups with child progress, hierarchy, usage, and cost evidence;
-- optional enforced Docker/Podman execution with no container network, a read-only root filesystem, non-root execution, dropped capabilities, bounded CPU/memory/PIDs/time/output, and an ephemeral secret-free workspace snapshot;
+- optional enforced Docker/Podman execution with a paused per-run container, no container network, a read-only root filesystem, non-root execution, dropped capabilities, bounded CPU/memory/PIDs/time/output, and an ephemeral secret-free workspace snapshot;
 - argv-only allowlisted environment commands, isolated package checks, deterministic patch inspection, and a separate durable approval before importing changes into the host workspace;
 - environment/image/policy fingerprint binding, cancellation cleanup, labeled orphan cleanup, retained audit artifacts, and installed-package plus real-runtime smoke gates;
 - protection against path traversal, symlink escapes, unsafe state targets, secret-file reads, special files, concurrent non-overwrite races, and unbounded output;
@@ -90,7 +98,7 @@ bun add @zhivex-ai/harness
 bunx --package @zhivex-ai/harness zhx --version
 ```
 
-To exercise the `0.8.0` source checkout:
+To exercise the `0.9.0` source checkout:
 
 ```bash
 bun install --frozen-lockfile
@@ -169,7 +177,7 @@ zhx run --provider openai --route explorer=qwen --route reviewer=gemini \
   "implement the change, then review it independently"
 ```
 
-Routing with `--max-cost-usd` is rejected in `0.8.0`: aggregate usage cannot yet be priced correctly when roles use different models.
+Routing with `--max-cost-usd` remains rejected in `0.9.0`: aggregate usage cannot yet be priced correctly when roles use different models.
 
 Writes and checks pause for approval. In a non-interactive execution, state is saved in `.zhivex-harness/runs/operations.sqlite`:
 
@@ -221,6 +229,15 @@ zhx run --provider gemini --jsonl "analyze the issue without modifying files"
 
 The JSON shapes and exit codes are documented in [docs/CLI.md](./docs/CLI.md).
 
+Create a portable change-admission envelope from structured, redacted evidence and the exact patch bytes, then verify it without provider credentials or network access:
+
+```bash
+zhx changes create examples/change-envelope-input.json --patch examples/change.patch > change-envelope.json
+zhx changes verify change-envelope.json --patch examples/change.patch
+```
+
+The verifier proves integrity, expiry, and explicit preconditions; it deliberately reports approval and external-attestation authenticity as `not-verified`. See [docs/CHANGE_ENVELOPES.md](./docs/CHANGE_ENVELOPES.md).
+
 Repository edits use digest-bound proposals. Discovery returns `nextCursor` when another deterministic page is available; mutating tools reject stale content instead of merging or overwriting it. Deletions move files into harness-owned quarantine and return a recovery identifier. The complete contract and migration from `0.2.x` are documented in [docs/REPOSITORY_EDITING.md](./docs/REPOSITORY_EDITING.md).
 
 The default check allowlist is `test`, `typecheck`, `lint`, and `build`. Replace it with repeatable CLI flags when a repository uses different declared scripts:
@@ -250,7 +267,7 @@ zhivex-harness run --execution oci --yes "inspect, implement, test, review the e
 
 Override any model with `--model`. Optional provider overrides are `META_BASE_URL`, `QWEN_BASE_URL`, `QWEN_WORKSPACE_ID`, `QWEN_REGION`, `OPENAI_BASE_URL`, and `GEMINI_BASE_URL`. Non-credential transport settings are hash-bound to durable resumes without persisting their values.
 
-Meta and Qwen retain the published support conclusion for the unchanged approval/restart, delegation/persistence, and enforced-execution paths. OpenAI is GPT-5.6-first in `0.8.0`: Luna is the default, while Terra and Sol remain explicit `--model` selections. All three passed the local base approval/restart gate, but delegation, OCI execution, and release-artifact certification still require the release-candidate matrix. Controlled and official-SDK MCP interoperability are verified separately and do not imply compatibility with every server or protocol feature. Provider capability claims remain artifact- and date-bound under the [live certification contract](./docs/LIVE_CERTIFICATION.md); credential detection and deterministic tests do not replace real provider evidence.
+Meta and Qwen retain the published support conclusion for the unchanged approval/restart, delegation/persistence, and enforced-execution paths. OpenAI remains GPT-5.6-first from `0.8.0`: Luna is the default, while Terra and Sol remain explicit `--model` selections. All three passed the local base approval/restart gate, but delegation, OCI execution, and `0.9.0` release-artifact certification still require the release-candidate matrix. Controlled and official-SDK MCP interoperability are verified separately and do not imply compatibility with every server or protocol feature. Provider capability claims remain artifact- and date-bound under the [live certification contract](./docs/LIVE_CERTIFICATION.md); credential detection and deterministic tests do not replace real provider evidence.
 
 ## Security boundaries
 
@@ -282,6 +299,7 @@ bun run typecheck
 bun test
 bun run build
 bun run evaluate
+bun run benchmark:workspace
 bun run smoke:package
 bun run pack:inspect
 bun run check

package/ROADMAP.md

@@ -3,7 +3,7 @@
 - Status: active
 - Baseline date: 2026-08-20
 
-This roadmap takes the harness from its `0.1.0` MVP to a stable CLI and library contract. The `0.2.0` source baseline is tagged locally, `0.3.0` and `0.4.0` are private checkpoints, and `0.5.0` through `0.7.0` are published on npm. `0.8.0` is the source release candidate for the coordinated SDK refresh and GPT-5.6-first OpenAI integration; publication and release certification remain separate operations. Releases are ordered by dependency and safety risk, not by calendar date. A version ships only when its exit criteria are satisfied.
+This roadmap takes the harness from its `0.1.0` MVP to a stable CLI and library contract. The `0.2.0` source baseline is tagged locally, `0.3.0` and `0.4.0` are private checkpoints, and `0.5.0` through `0.8.0` are published on npm. `0.9.0` is the source candidate for faster governed repository inspection and portable change-admission evidence; publication and release certification remain separate operations. Releases are ordered by dependency and safety risk, not by calendar date. A version ships only when its exit criteria are satisfied.
 
 ## Planning principles
 
@@ -41,7 +41,8 @@ The `0.6.0` dependency batch pins and overrides `@zhivex-ai/core@1.6.0`, retaini
 | `0.6.0` | Enforced execution | Shell and checks inside a real isolation boundary | Published on npm | XL |
 | `0.6.1` | Positioning and proof | Reproducible hostile-repository control evidence | Published on npm | S |
 | `0.7.0` | Multi-provider agent console | Durable sessions, extensible providers, safe role routing, and automation events | Published on npm | L |
-| `0.8.0` | SDK refresh and GPT-5.6 | One Core runtime, current adapters, and a GPT-5.6-first OpenAI path | Source release candidate | M |
+| `0.8.0` | SDK refresh and GPT-5.6 | One Core runtime, current adapters, and a GPT-5.6-first OpenAI path | Published on npm | M |
+| `0.9.0` | Fast governed change admission | Lower repository/OCI overhead plus portable offline evidence bound to exact patch bytes | Source candidate | L |
 | `1.0.0` | Stable contract | Supported compatibility and release guarantees | Planned | L |
 
 Relative size is for sequencing only; dates require a capacity decision.
@@ -195,7 +196,7 @@ Exit criteria:
 
 Implementation summary:
 
-- the SDK execution-environment contract is implemented with a Docker/Podman adapter, immutable image identity, per-tool-call isolation, manifest authorization, and run fingerprint binding;
+- the SDK execution-environment contract is implemented with a Docker/Podman adapter, immutable image identity, paused per-run isolation, transactional command publication, manifest authorization, and run fingerprint binding;
 - the enforced policy denies network and undeclared tools, uses a non-root identity, read-only root, dropped capabilities, no-new-privileges, and bounded memory, CPU, PIDs, time, output, snapshot, imported-file, and tmpfs resources;
 - repository tools and subagents share an ephemeral secret-free snapshot; package checks and argv-only commands run inside OCI, while network MCP fails closed under the no-network policy;
 - content- and run-bound patch inspection plus a separate durable import approval are the only environment-to-host mutation path; deletes remain recoverable through quarantine;
@@ -246,7 +247,7 @@ Deferred after `0.7.0`:
 
 ## 0.8.0 — SDK refresh and GPT-5.6-first OpenAI
 
-Status: source release candidate. Deterministic, installed-artifact, live-provider, and publication evidence remain separate gates.
+Status: published on npm with registry provenance. Provider evidence remains date- and model-bound.
 
 Goal: adopt the coordinated SDK release batch without duplicating Core contracts, make the current GPT-5.6 family the primary OpenAI experience, and keep approval pauses reliable across provider behavior changes.
 
@@ -263,6 +264,29 @@ Exit criteria:
 - Luna, Terra, and Sol pass the base proposal/approval/restart/exactly-once live gate with date-bound evidence.
 - The exact release artifact, annotated tag, registry integrity, and provenance are verified independently before claiming publication.
 
+## 0.9.0 — fast governed change admission
+
+Status: source candidate. Deterministic tests and the local performance fixture pass; real-OCI, installed-artifact, live-provider, tag, registry, and provenance gates remain separate.
+
+Goal: reduce the cost of inspecting large repositories and materialize the harness's change-control evidence as a portable, agent-agnostic admission contract.
+
+Scope:
+
+- Reuse a freshness-checked, topology-only workspace index across pages while keeping file contents and digests on the stable anti-race read path.
+- Add bounded batch reads and multi-query search without enabling unsafe global tool parallelism.
+- Reduce OCI snapshot memory and duplicate patch-comparison reads without introducing a long-lived container or weakening transactional publication.
+- Expose reproducible workspace benchmarks plus workspace-index and OCI I/O diagnostics.
+- Add deterministic `ChangeEnvelope v1` creation and offline verification bound to exact patch bytes, base identity, policy/environment fingerprints, redacted check evidence, expiry, approval references, and external-attestation references.
+- Keep authenticity explicit: built-in verification checks integrity, expiration, and preconditions; external signatures and attestations require their native verifier.
+
+Exit criteria:
+
+- Workspace index invalidation, external-change freshness, cursor staleness, batch bounds, duplicate reads, and multi-query single-pass behavior have deterministic regression coverage.
+- The 5,000-file benchmark reports one index build and materially improves complete pagination against the pre-`0.9` baseline without setting a flaky CI wall-time threshold.
+- OCI deterministic tests prove independent base/workspace copies, bounded inventory pages, changed-file-only patch reads, and unchanged import/stale-host guarantees; a real daemon gate remains mandatory for release.
+- Change-envelope tests cover canonical determinism, exact patch tampering, base/policy/evidence changes, expiry, strict redaction schemas, and explicit authenticity limits.
+- Documentation, typecheck, full tests, evaluation, build, package inspection, and installed-tarball smoke pass from a clean release commit before any tag or publication.
+
 ## 1.0.0 — Stable CLI and library contract
 
 Goal: freeze a supportable public contract after the pre-1.0 safety and operational surfaces have been exercised in real repositories.
@@ -275,7 +299,7 @@ Scope:
 - Complete threat model, security review, dependency audit, provenance, integrity, and rollback documentation.
 - Run a representative repository evaluation matrix across every supported provider and publish date-bound evidence.
 - Add full installation, operations, policy, MCP, isolation, troubleshooting, migration, and release documentation.
-- Require release candidates before `latest`; no direct `0.6.x` to untested GA promotion.
+- Require release candidates before `latest`; no direct pre-1.0 source checkpoint to untested GA promotion.
 
 Exit criteria:
 
@@ -308,7 +332,8 @@ These can become separate post-1.0 tracks after the CLI/runtime contract and sec
 
 ## Immediate next actions
 
-1. Finish the `0.8.0` deterministic, real-OCI, and installed-artifact gates from a clean release commit.
-2. Complete the remaining GPT-5.6 and provisional-provider live matrices; keep uncertified paths provisional on any failure or missing evidence.
-3. Dogfood the GPT-5.6 default, durable `zhx` sessions, provider handoff, role routing, and JSONL consumption on representative repositories.
-4. Only after those gates, complete the reviewed release workflow and verify registry integrity and provenance against the exact artifact.
+1. Review and commit the `0.9.0` workspace-index, batch-tool, OCI I/O, and ChangeEnvelope contracts from a clean branch.
+2. Run the required real-OCI and installed-artifact gates; keep the current local benchmark as comparative evidence rather than a cross-machine latency promise.
+3. Dogfood exact-patch envelope creation/verification and batch repository inspection on representative repositories, including external workspace mutations between pages.
+4. Complete the remaining GPT-5.6 and provisional-provider live matrices; keep uncertified paths provisional on any failure or missing evidence.
+5. Only after those gates, create the annotated tag, dispatch the reviewed release workflow, and verify registry integrity and provenance against the exact artifact.

package/SECURITY.md

@@ -2,7 +2,7 @@
 
 ## Supported versions
 
-Security fixes are provided for the latest published `0.6.x` version. Pre-release source snapshots and older private checkpoints are not supported release channels.
+Security fixes are provided for the latest published `0.8.x` version. The `0.9.x` source candidate and older private checkpoints are not supported release channels until their exact artifacts are published and verified.
 
 ## Reporting a vulnerability
 
@@ -21,3 +21,9 @@ Private vulnerability reporting must be enabled before the repository is made pu
 Reports are in scope when they affect packaged runtime code, workspace or state isolation, approval enforcement, secret handling, MCP boundaries, provider communication, dependency integrity, or the build and release pipeline.
 
 The absence of an OS sandbox is a documented product boundary rather than a vulnerability by itself. The harness does not expose generic host shell or permanent-delete model tools.
+
+`ChangeEnvelope v1` verifies canonical integrity, expiration, exact patch binding, and caller-supplied preconditions. It is not a signature or identity system; approval and external-attestation authenticity are explicitly reported as `not-verified`. A bypass in the documented built-in checks is in scope, while failure to validate an external trust bundle that the application never configured is outside that boundary.
+
+The `0.9.x` workspace index caches topology only. File contents and content digests are reread through the stable anti-race path. Reports showing stale content returned as current, ignored files becoming discoverable after an ignore-policy change, or an accepted topology cursor after a structural mutation are in scope.
+
+The `0.9.x` OCI backend may reuse one paused container inside an acquired run, but every command remains a separate publication transaction. Reports showing concurrent command execution, a failed/background command surviving into a later command, host-snapshot divergence not forcing reseed, `/tmp` state crossing a successful command boundary, or an unvalidated workspace reaching the durable snapshot are in scope.

package/SUPPORT.md

@@ -1,6 +1,6 @@
 # Support
 
-Zhivex Harness `0.8.x` is a pre-1.0 CLI and TypeScript library for Bun. Observable contracts may change in a later minor release when the change and migration path are documented in [CHANGELOG.md](./CHANGELOG.md). The source checkout may be a release candidate newer than the latest public npm artifact.
+Zhivex Harness `0.9.x` is a pre-1.0 CLI and TypeScript library for Bun. Observable contracts may change in a later minor release when the change and migration path are documented in [CHANGELOG.md](./CHANGELOG.md). The source checkout may be a release candidate newer than the latest public npm artifact.
 
 ## Supported baseline
 

package/dist/change-envelope.d.ts

@@ -0,0 +1,271 @@
+import { z } from "zod";
+import { type FileDigest } from "./edit-contracts.js";
+export declare const CHANGE_ENVELOPE_SCHEMA_VERSION: 1;
+export declare const CHANGE_ENVELOPE_DIGEST_ALGORITHM: "sha256";
+export declare const MAX_CHANGE_ENVELOPE_CHECKS = 100;
+export declare const MAX_CHANGE_ENVELOPE_APPROVALS = 100;
+export declare const MAX_CHANGE_ENVELOPE_APPROVAL_SCOPES = 32;
+export declare const MAX_CHANGE_ENVELOPE_ATTESTATIONS = 32;
+export declare const changeEnvelopeCheckSchema: z.ZodObject<{
+    checkId: z.ZodString;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+        skipped: "skipped";
+    }>;
+    redacted: z.ZodLiteral<true>;
+    startedAt: z.ZodISODateTime;
+    completedAt: z.ZodISODateTime;
+    durationMs: z.ZodNumber;
+    exitCode: z.ZodOptional<z.ZodNumber>;
+    redactedOutputDigest: z.ZodOptional<z.ZodString>;
+    runnerFingerprint: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ChangeEnvelopeCheck = z.infer<typeof changeEnvelopeCheckSchema>;
+export declare const changeEnvelopeApprovalSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"approval-reference">;
+    approvalId: z.ZodString;
+    approvalDigest: z.ZodString;
+    approverDigest: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    approvedAt: z.ZodISODateTime;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type ChangeEnvelopeApproval = z.infer<typeof changeEnvelopeApprovalSchema>;
+export declare const externalAttestationReferenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"external-attestation-reference">;
+    attestationId: z.ZodString;
+    format: z.ZodString;
+    mediaType: z.ZodString;
+    bundleDigest: z.ZodString;
+}, z.core.$strict>;
+export type ExternalAttestationReference = z.infer<typeof externalAttestationReferenceSchema>;
+export declare const changeEnvelopeBaseSchema: z.ZodObject<{
+    workspaceDigest: z.ZodString;
+    treeDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const changeEnvelopePatchSchema: z.ZodObject<{
+    patchId: z.ZodString;
+    patchDigest: z.ZodString;
+}, z.core.$strict>;
+export declare const changeEnvelopeFingerprintsSchema: z.ZodObject<{
+    harness: z.ZodString;
+    policy: z.ZodString;
+    environment: z.ZodString;
+}, z.core.$strict>;
+export declare const changeEnvelopeEvidenceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"check-evidence-summary">;
+    digestAlgorithm: z.ZodLiteral<"sha256">;
+    evidenceDigest: z.ZodString;
+    checks: z.ZodArray<z.ZodObject<{
+        checkId: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            skipped: "skipped";
+        }>;
+        redacted: z.ZodLiteral<true>;
+        startedAt: z.ZodISODateTime;
+        completedAt: z.ZodISODateTime;
+        durationMs: z.ZodNumber;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        redactedOutputDigest: z.ZodOptional<z.ZodString>;
+        runnerFingerprint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ChangeEnvelopeEvidence = z.infer<typeof changeEnvelopeEvidenceSchema>;
+export declare const changeEnvelopeInputSchema: z.ZodObject<{
+    createdAt: z.ZodISODateTime;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    base: z.ZodObject<{
+        workspaceDigest: z.ZodString;
+        treeDigest: z.ZodString;
+    }, z.core.$strict>;
+    patch: z.ZodObject<{
+        patchId: z.ZodString;
+        patchDigest: z.ZodString;
+    }, z.core.$strict>;
+    fingerprints: z.ZodObject<{
+        harness: z.ZodString;
+        policy: z.ZodString;
+        environment: z.ZodString;
+    }, z.core.$strict>;
+    checks: z.ZodArray<z.ZodObject<{
+        checkId: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+            skipped: "skipped";
+        }>;
+        redacted: z.ZodLiteral<true>;
+        startedAt: z.ZodISODateTime;
+        completedAt: z.ZodISODateTime;
+        durationMs: z.ZodNumber;
+        exitCode: z.ZodOptional<z.ZodNumber>;
+        redactedOutputDigest: z.ZodOptional<z.ZodString>;
+        runnerFingerprint: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    approvals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"approval-reference">;
+        approvalId: z.ZodString;
+        approvalDigest: z.ZodString;
+        approverDigest: z.ZodString;
+        scopes: z.ZodArray<z.ZodString>;
+        approvedAt: z.ZodISODateTime;
+        expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>>>;
+    externalAttestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"external-attestation-reference">;
+        attestationId: z.ZodString;
+        format: z.ZodString;
+        mediaType: z.ZodString;
+        bundleDigest: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type CreateChangeEnvelopeInput = z.infer<typeof changeEnvelopeInputSchema>;
+export declare const changeEnvelopeSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"change-envelope">;
+    digestAlgorithm: z.ZodLiteral<"sha256">;
+    envelopeId: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    base: z.ZodObject<{
+        workspaceDigest: z.ZodString;
+        treeDigest: z.ZodString;
+    }, z.core.$strict>;
+    patch: z.ZodObject<{
+        patchId: z.ZodString;
+        patchDigest: z.ZodString;
+    }, z.core.$strict>;
+    fingerprints: z.ZodObject<{
+        harness: z.ZodString;
+        policy: z.ZodString;
+        environment: z.ZodString;
+    }, z.core.$strict>;
+    evidence: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        kind: z.ZodLiteral<"check-evidence-summary">;
+        digestAlgorithm: z.ZodLiteral<"sha256">;
+        evidenceDigest: z.ZodString;
+        checks: z.ZodArray<z.ZodObject<{
+            checkId: z.ZodString;
+            status: z.ZodEnum<{
+                passed: "passed";
+                failed: "failed";
+                skipped: "skipped";
+            }>;
+            redacted: z.ZodLiteral<true>;
+            startedAt: z.ZodISODateTime;
+            completedAt: z.ZodISODateTime;
+            durationMs: z.ZodNumber;
+            exitCode: z.ZodOptional<z.ZodNumber>;
+            redactedOutputDigest: z.ZodOptional<z.ZodString>;
+            runnerFingerprint: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    approvals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"approval-reference">;
+        approvalId: z.ZodString;
+        approvalDigest: z.ZodString;
+        approverDigest: z.ZodString;
+        scopes: z.ZodArray<z.ZodString>;
+        approvedAt: z.ZodISODateTime;
+        expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>>>;
+    externalAttestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodLiteral<"external-attestation-reference">;
+        attestationId: z.ZodString;
+        format: z.ZodString;
+        mediaType: z.ZodString;
+        bundleDigest: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ChangeEnvelope = z.infer<typeof changeEnvelopeSchema>;
+/** Content-addresses exact artifact bytes for patch/base inputs without parsing them. */
+export declare const digestChangeEnvelopeArtifact: (value: string | Uint8Array) => FileDigest;
+/**
+ * Creates a content-addressed envelope. The caller supplies all timestamps, so
+ * repeated calls with semantically identical input return the same envelope.
+ * Raw command output, prompts, reasons, and credentials are intentionally not
+ * representable by this contract.
+ */
+export declare const createChangeEnvelope: (input: unknown) => ChangeEnvelope;
+/** Returns the canonical, whitespace-free JSON representation of a valid envelope. */
+export declare const canonicalizeChangeEnvelope: (input: unknown) => string;
+/** Recomputes the envelope identifier without trusting its embedded envelopeId. */
+export declare const computeChangeEnvelopeDigest: (input: unknown) => FileDigest;
+/** Recomputes the independently addressable digest of the redacted check summary. */
+export declare const computeChangeEnvelopeEvidenceDigest: (input: unknown) => FileDigest;
+export declare const changeEnvelopePreconditionsSchema: z.ZodObject<{
+    envelopeId: z.ZodOptional<z.ZodString>;
+    baseWorkspaceDigest: z.ZodOptional<z.ZodString>;
+    baseTreeDigest: z.ZodOptional<z.ZodString>;
+    patchId: z.ZodOptional<z.ZodString>;
+    patchDigest: z.ZodOptional<z.ZodString>;
+    harnessFingerprint: z.ZodOptional<z.ZodString>;
+    policyFingerprint: z.ZodOptional<z.ZodString>;
+    environmentFingerprint: z.ZodOptional<z.ZodString>;
+    evidenceDigest: z.ZodOptional<z.ZodString>;
+    requiredPassedChecks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requiredApprovalDigests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requiredApprovalScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    requiredAttestationDigests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ChangeEnvelopePreconditions = z.infer<typeof changeEnvelopePreconditionsSchema>;
+export interface ChangeEnvelopeVerificationOptions {
+    now?: Date | string | number;
+    preconditions?: ChangeEnvelopePreconditions;
+}
+export type ChangeEnvelopeVerificationIssueCode = "invalid-schema" | "envelope-digest-mismatch" | "evidence-digest-mismatch" | "envelope-not-yet-valid" | "envelope-expired" | "approval-expired" | "precondition-mismatch" | "missing-passed-check" | "missing-approval-digest" | "missing-approval-scope" | "missing-attestation-digest";
+export interface ChangeEnvelopeVerificationIssue {
+    code: ChangeEnvelopeVerificationIssueCode;
+    path: readonly (string | number)[];
+    message: string;
+    expected?: string;
+    actual?: string;
+}
+export interface ChangeEnvelopeVerificationResult {
+    valid: boolean;
+    verificationScope: "integrity-expiration-and-preconditions-only";
+    envelope?: ChangeEnvelope;
+    issues: ChangeEnvelopeVerificationIssue[];
+    integrity: {
+        envelopeDigestValid: boolean;
+        evidenceDigestValid: boolean;
+    };
+    expiration: {
+        checkedAt: string;
+        envelopeNotYetValid: boolean;
+        envelopeExpired: boolean;
+        expiredApprovalIds: string[];
+    };
+    checks: {
+        recorded: number;
+        passed: string[];
+        failed: string[];
+        skipped: string[];
+        requiredPassed: string[];
+        missingPassed: string[];
+    };
+    approvals: {
+        recorded: number;
+        requiredScopes: string[];
+        missingScopes: string[];
+        authenticity: "not-verified";
+    };
+    externalAttestations: {
+        referenced: number;
+        requiredDigests: FileDigest[];
+        missingDigests: FileDigest[];
+        authenticity: "not-verified";
+    };
+}
+/**
+ * Verifies schema, content digests, expiry, and caller-supplied preconditions
+ * without network access. Approval and attestation references are integrity
+ * bound only: their issuer/signature authenticity must be checked by an
+ * external Sigstore/in-toto (or equivalent) verifier.
+ */
+export declare const verifyChangeEnvelope: (input: unknown, options?: ChangeEnvelopeVerificationOptions) => ChangeEnvelopeVerificationResult;