@fluxpointstudios/orynq-sdk-process-trace 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -105,10 +105,106 @@ interface CustomEvent extends BaseTraceEvent {
     eventType: string;
     data: Record<string, unknown>;
 }
+/**
+ * Signature scheme used by a governance attestor.
+ * - "sr25519" / "ed25519": Substrate/Materios wallets (verified in-package)
+ * - "eip712": EVM typed-data signatures (verified via a pluggable verifier)
+ */
+type GovernanceSignatureScheme = "sr25519" | "ed25519" | "eip712";
+/**
+ * EIP-712 typed-data binding, required to verify an `eip712` governance
+ * signature. Mirrors the shape consumed by viem's `verifyTypedData`.
+ */
+interface GovernanceEip712Binding {
+    domain: Record<string, unknown>;
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    primaryType: string;
+    message?: Record<string, unknown>;
+}
+/**
+ * Governance attestation event — a verifiable, role-scoped sign-off recorded
+ * inside a trace (compliance review, release approval, data-steward sign-off).
+ *
+ * The signature is computed over a canonical, domain-separated preimage of
+ * `(runId || role || policyRef || decisionRef || signedAt)` (see
+ * `governanceAttestationPreimage`), so an auditor can verify *who* governed a
+ * decision without trusting the wrapper that recorded it, and a genuine
+ * attestation cannot be replayed into a different trace.
+ *
+ * Default visibility: "public" (governance provenance is meant to be auditable).
+ */
+interface GovernanceAttestationEvent extends BaseTraceEvent {
+    kind: "governance-attestation";
+    /** Governance role; common values plus free-form extension. */
+    role: "compliance" | "release-authority" | "data-steward" | (string & {});
+    /** Hash or URI of the policy being attested to. */
+    policyRef: string;
+    /** Hash or id of the decision/event being governed. */
+    decisionRef: string;
+    /** The signing identity and scheme. */
+    attestor: {
+        address: string;
+        signatureScheme: GovernanceSignatureScheme;
+    };
+    /** Signature over the canonical preimage (hex, optionally `0x`-prefixed). */
+    signature: string;
+    /** ISO 8601 timestamp; part of the signed preimage. */
+    signedAt: string;
+    /** EIP-712 binding — required only when `attestor.signatureScheme === "eip712"`. */
+    eip712?: GovernanceEip712Binding;
+}
+/**
+ * Signature scheme for a tool-call receipt.
+ * - "http-message-signatures": RFC 9421 signed HTTP responses
+ * - "stripe-webhook" / "github-webhook": SaaS webhook HMAC signatures
+ * - "jws": generic JWS/JWT-signed responses
+ * - (string): forward-compatible custom schemes
+ */
+type ToolReceiptScheme = "http-message-signatures" | "stripe-webhook" | "github-webhook" | "jws" | (string & {});
+/**
+ * Verifiable tool-call receipt event — proves "the tool actually returned this
+ * response", not merely "the agent says the tool returned this response".
+ *
+ * The wrapper records a signed receipt produced by (or about) the external
+ * system; a verifier independently re-checks `receipt.signature` over
+ * `receipt.signedPayload` against `receipt.signer`.
+ *
+ * Default visibility: "private" (responses may contain PII / secrets — only the
+ * hashes and signature are needed for verification).
+ */
+interface ToolReceiptEvent extends BaseTraceEvent {
+    kind: "tool-receipt";
+    /** Identifier of the tool/endpoint that was called. */
+    toolId: string;
+    /** Commitment to the request (SHA-256 hex). */
+    request: {
+        hash: string;
+    };
+    /** Commitment to the response, with an optional retained payload. */
+    response: {
+        hash: string;
+        payload?: unknown;
+    };
+    /** The independently-verifiable signed receipt. */
+    receipt: {
+        scheme: ToolReceiptScheme;
+        /** Verifier-resolvable identity: URL, DID, on-chain address, or keyId. */
+        signer: string;
+        /** Signature bytes (encoding depends on scheme: base64/hex/0x-hex). */
+        signature: string;
+        /** Canonicalized signed bytes the signature is computed over. */
+        signedPayload: string;
+        /** Scheme-specific verification material (headers, keyId, components, ...). */
+        params?: Record<string, unknown>;
+    };
+}
 /**
  * Discriminated union of all trace event types.
  */
-type TraceEvent = CommandEvent | OutputEvent | DecisionEvent | ObservationEvent | ErrorTraceEvent | CustomEvent;
+type TraceEvent = CommandEvent | OutputEvent | DecisionEvent | ObservationEvent | ErrorTraceEvent | CustomEvent | GovernanceAttestationEvent | ToolReceiptEvent;
 /**
  * Event kind string literals for type guards.
  */
@@ -146,6 +242,36 @@ interface TraceSpan {
     metadata?: Record<string, unknown>;
     hash?: string;
 }
+/**
+ * Fingerprint of the model/data state used during a trace run.
+ *
+ * Distinct from {@link TraceManifest} (which describes off-chain *storage*
+ * chunks). A `ModelManifest` is pinned at {@link CreateTraceOptions} time —
+ * *before* execution — and frozen, so the resulting trace can prove that
+ * "neither the data nor the model was altered" for a given inference.
+ *
+ * Two traces of "the same model" should produce the same `modelManifestHash`,
+ * so the field values must be deterministic fingerprints (see the
+ * `manifestFrom*` builders).
+ */
+interface ModelManifest {
+    /** Model checkpoint fingerprint, e.g. "sha256:..." */
+    modelHash: string;
+    /** Tokenizer fingerprint. */
+    tokenizerHash?: string;
+    /** System-prompt fingerprint. */
+    systemPromptHash?: string;
+    /** Training-dataset manifest fingerprint. */
+    trainingDataManifest?: string;
+    /** Producing framework, e.g. "huggingface" | "openai" | "anthropic" | "checkpoint". */
+    framework?: string;
+    /** Model identifier (e.g. HF repo id, OpenAI/Anthropic model name). */
+    modelId?: string;
+    /** Revision / snapshot id, when applicable. */
+    revision?: string;
+    /** Free-form additional fingerprint inputs (hashed into manifestHash). */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Complete trace run containing all events and spans.
  *
@@ -174,6 +300,18 @@ interface TraceRun {
     rootHash?: string;
     nextSeq: number;
     nextSpanSeq: number;
+    /**
+     * Model/data manifest pinned at createTrace() time (frozen). When present,
+     * `modelManifestHash` is the cryptographic commitment to it.
+     */
+    modelManifest?: ModelManifest;
+    /** H("poi-trace:model-manifest:v1|" + canonical(modelManifest)), pinned at creation. */
+    modelManifestHash?: string;
+    /**
+     * Strict-mode flag (pinned at creation). When true, finalizeTrace() throws
+     * if no manifest was pinned. Default false (warn-only) for v0.x.
+     */
+    strict?: boolean;
 }
 /**
  * State for incremental rolling hash computation.
@@ -246,6 +384,10 @@ interface TraceBundlePublicView {
     }>;
     redactionPolicyId?: string;
     redactionRulesHash?: string;
+    /** Model-state commitment (public-safe: it is only a hash). */
+    modelManifestHash?: string;
+    /** Pinned model manifest (hashes only — public-safe). */
+    modelManifest?: ModelManifest;
 }
 /**
  * Complete trace bundle with cryptographic commitments.
@@ -267,6 +409,14 @@ interface TraceBundle {
     merkleRoot: string;
     rootHash: string;
     manifestHash?: string;
+    /**
+     * Model/data manifest commitment pinned at createTrace() time. Distinct from
+     * `manifestHash` (the off-chain storage-manifest hash). Place this in on-chain
+     * anchor metadata to make model drift cryptographically detectable.
+     */
+    modelManifestHash?: string;
+    /** The pinned model manifest (hashes only — public-safe). */
+    modelManifest?: ModelManifest;
     signerId?: string;
     signature?: string;
 }
@@ -366,6 +516,22 @@ interface TraceVerificationResult {
         spanHashesValid: boolean;
         eventHashesValid: boolean;
         sequenceValid: boolean;
+        /**
+         * Model-manifest pin binding (#59): the pinned manifest hashes to its
+         * recorded commitment AND that commitment is folded into the committed
+         * root. True when no manifest is pinned (nothing to bind).
+         */
+        modelManifestValid?: boolean;
+        /**
+         * Set only when governance verification is requested via
+         * verifyBundle(bundle, { governance }). Undefined means "not checked".
+         */
+        governanceValid?: boolean;
+        /**
+         * Set only when tool-receipt verification is requested via
+         * verifyBundle(bundle, { toolReceipts }). Undefined means "not checked".
+         */
+        toolReceiptsValid?: boolean;
     };
 }
 /**
@@ -389,6 +555,17 @@ interface CreateTraceOptions {
     agentId: string;
     description?: string;
     metadata?: Record<string, unknown>;
+    /**
+     * Model/data manifest to pin *before* execution. Its hash is computed and
+     * frozen at createTrace() time; mutating the manifest afterwards throws.
+     */
+    manifest?: ModelManifest;
+    /**
+     * Strict mode. When true, createTrace() requires a `manifest` and
+     * finalizeTrace() refuses to finalize an unpinned trace. Default false
+     * (warn-only) for v0.x; planned strict-by-default in v1.0.
+     */
+    strict?: boolean;
 }
 /**
  * Options for creating a new span.
@@ -418,6 +595,10 @@ declare const HASH_DOMAIN_PREFIXES: {
     readonly node: "poi-trace:node:v1|";
     readonly manifest: "poi-trace:manifest:v1|";
     readonly root: "poi-trace:root:v1|";
+    /** Model/data manifest commitment (pre-execution pinning). */
+    readonly modelManifest: "poi-trace:model-manifest:v1|";
+    /** Governance-attestation signing preimage. */
+    readonly governance: "poi-trace:governance:v1|";
 };
 /**
  * Type for domain prefix keys.
@@ -1127,28 +1308,31 @@ declare function computeRollingHash(events: TraceEvent[]): Promise<string>;
  */
 declare function verifyRollingHash(events: TraceEvent[], expectedHash: string): Promise<boolean>;
 /**
- * Compute the final root hash from rolling hash and span hashes.
+ * Compute the final root hash from rolling hash, span hashes, and (when pinned)
+ * the model-manifest commitment.
  *
  * The root hash is computed as:
- * `H("poi-trace:root:v1|" + rollingHash + "|" + spanHash1 + "|" + spanHash2 + ...)`
+ * `H("poi-trace:root:v1|" + rollingHash + "|" + spanHash1 + "|" + ... [+ "|manifest:" + modelManifestHash])`
  *
  * Spans are sorted by their `spanSeq` field before joining to ensure
- * deterministic ordering. This creates a single commitment that covers
- * both the event sequence (via rolling hash) and the span structure.
+ * deterministic ordering. Folding `modelManifestHash` in binds the pinned
+ * model/data manifest to the committed root (issue #59): swapping the manifest
+ * after commitment changes the recomputed root and fails verification.
  *
  * @param rollingHash - The final rolling hash from all events
  * @param spans - Array of trace spans (must have hash field populated)
+ * @param modelManifestHash - Optional pre-execution model-manifest commitment to bind
  * @returns Promise resolving to the root hash as a hex string
  *
  * @example
  * ```typescript
  * const rollingHash = await computeRollingHash(events);
- * const rootHash = await computeRootHash(rollingHash, spans);
+ * const rootHash = await computeRootHash(rollingHash, spans, run.modelManifestHash);
  *
  * // rootHash can now be published as the trace commitment
  * ```
  */
-declare function computeRootHash(rollingHash: string, spans: TraceSpan[]): Promise<string>;
+declare function computeRootHash(rollingHash: string, spans: TraceSpan[], modelManifestHash?: string): Promise<string>;
 /**
  * Compute event hashes for multiple events in batch.
  * Useful for pre-computing hashes before building a Merkle tree.
@@ -1273,6 +1457,262 @@ declare function verifyMerkleProof(proof: MerkleProof): Promise<boolean>;
  */
 declare function verifySpanInclusion(proof: MerkleProof, span: TraceSpan, events: TraceEvent[]): Promise<boolean>;
 
+/**
+ * @fileoverview Governance attestations (issue #58).
+ *
+ * Location: packages/process-trace/src/governance.ts
+ *
+ * A `governance-attestation` event records a verifiable, role-scoped sign-off
+ * inside a trace (compliance review, release approval, data-steward sign-off),
+ * so an auditor can answer "who governed this decision?" without trusting the
+ * wrapper that recorded it.
+ *
+ * Signing model:
+ * - The signature covers a canonical, domain-separated preimage of
+ *   `(role || policyRef || decisionRef || signedAt)` — see
+ *   {@link governanceAttestationPreimage}.
+ * - `sr25519` and `ed25519` are verified in-package via the OPTIONAL peer
+ *   dependencies `@polkadot/util-crypto` + `@polkadot/util` (loaded with a
+ *   dynamic `import()` so base installs stay lean).
+ * - `eip712` is verified via a pluggable {@link GovernanceVerifier} so this
+ *   package never needs a hard dependency on viem. See
+ *   {@link createEip712GovernanceVerifier}.
+ *
+ * @example
+ * ```typescript
+ * const signer = await createSr25519GovernanceSigner({ seed: "0x" + "11".repeat(32) });
+ * await addGovernanceAttestation(run, span.id, {
+ *   role: "compliance",
+ *   policyRef: "sha256:...",
+ *   decisionRef: eventId,
+ *   signer,
+ * });
+ * // ...later, during audit: the attestor identity comes from the untrusted
+ * // trace, so the caller MUST allow-list the authorized signer(s) — a valid
+ * // self-signed attestation from an arbitrary key is not a real sign-off.
+ * const summary = await verifyGovernanceAttestations(bundle, {
+ *   authorizedAttestors: [signer.address],
+ * });
+ * // [{ role: "compliance", attestor: "5...", scheme: "sr25519", verified: true, authorized: true }]
+ * ```
+ */
+
+/** The fields that are bound by a governance signature. */
+interface GovernanceAttestationFields {
+    role: string;
+    policyRef: string;
+    decisionRef: string;
+    signedAt: string;
+    /**
+     * Trace run id this attestation is scoped to. Binding it prevents replaying a
+     * genuine attestation from trace X into an unrelated trace Y (#58).
+     */
+    runId: string;
+}
+/**
+ * Build the canonical, domain-separated preimage signed by sr25519/ed25519
+ * governance signers. Deterministic — a verifier reconstructs identical bytes
+ * from the recorded event fields plus the enclosing run id.
+ *
+ * Each field is LENGTH-PREFIXED (4-byte big-endian byte length) rather than
+ * delimiter-joined: a raw `\n` separator let two different tuples produce
+ * identical bytes when a field value (role/policyRef/decisionRef are
+ * attacker-supplied) itself contained `\n`, so one signature re-sliced to bind
+ * a different claim. Length-prefixing makes field boundaries unambiguous
+ * regardless of the field contents.
+ */
+declare function governanceAttestationPreimage(fields: GovernanceAttestationFields): Uint8Array;
+/** Context passed to a {@link GovernanceSigner}. */
+interface GovernanceSignContext {
+    /** Canonical preimage bytes (sr25519/ed25519 signers sign these). */
+    preimage: Uint8Array;
+    /** The raw fields, for signers (e.g. eip712) that build their own payload. */
+    fields: GovernanceAttestationFields;
+    /** Present iff the caller supplied an eip712 binding. */
+    eip712?: GovernanceEip712Binding;
+}
+/**
+ * A governance signer. Consumers provide an implementation (HSM, KMS, wallet,
+ * or one of the built-in {@link createSr25519GovernanceSigner} /
+ * {@link createEd25519GovernanceSigner} factories).
+ */
+interface GovernanceSigner {
+    /** Verifier-resolvable identity (SS58 address for substrate, 0x-address for evm). */
+    address: string;
+    signatureScheme: GovernanceSignatureScheme;
+    /** Return the signature as a hex string (with or without `0x`). */
+    sign(ctx: GovernanceSignContext): Promise<string> | string;
+}
+interface AddGovernanceAttestationOptions {
+    role: GovernanceAttestationEvent["role"];
+    policyRef: string;
+    decisionRef: string;
+    signer: GovernanceSigner;
+    /** ISO 8601 timestamp; defaults to now. Included in the signed preimage. */
+    signedAt?: string;
+    /** Event visibility; defaults to "public" (governance is auditable). */
+    visibility?: Visibility;
+    /** EIP-712 binding — required when the signer scheme is "eip712". */
+    eip712?: GovernanceEip712Binding;
+}
+/**
+ * Sign and append a `governance-attestation` event to a span.
+ *
+ * @returns the recorded {@link GovernanceAttestationEvent} (with runtime fields).
+ */
+declare function addGovernanceAttestation(run: TraceRun, spanId: string, opts: AddGovernanceAttestationOptions): Promise<GovernanceAttestationEvent>;
+/** Default SS58 prefix used across the Orynq/Materios ecosystem. */
+declare const SS58_PREFIX = 42;
+interface SubstrateGovernanceSignerOptions {
+    /** 32-byte seed as bytes or 0x-hex. Provide this OR (secretKey + publicKey). */
+    seed?: Uint8Array | string;
+    /** Expanded secret key (with publicKey). */
+    secretKey?: Uint8Array;
+    publicKey?: Uint8Array;
+    /** Override the derived SS58 address. */
+    address?: string;
+    /** SS58 format for the derived address (default 42). */
+    ss58Format?: number;
+}
+/**
+ * Create an sr25519 governance signer backed by `@polkadot/util-crypto`.
+ * Pass a 32-byte `seed` (bytes or 0x-hex) or an explicit `secretKey`+`publicKey`.
+ */
+declare function createSr25519GovernanceSigner(opts: SubstrateGovernanceSignerOptions): Promise<GovernanceSigner>;
+/**
+ * Create an ed25519 governance signer backed by `@polkadot/util-crypto`.
+ * Pass a 32-byte `seed` (bytes or 0x-hex) or an explicit `secretKey`+`publicKey`.
+ */
+declare function createEd25519GovernanceSigner(opts: SubstrateGovernanceSignerOptions): Promise<GovernanceSigner>;
+/** Context passed to a {@link GovernanceVerifier} alongside the event. */
+interface GovernanceVerifyContext {
+    /** Canonical preimage bytes bound to this trace's run id (#58). */
+    preimage: Uint8Array;
+    /** The enclosing trace run id — verifiers MUST bind signatures to it. */
+    runId: string;
+}
+/** A pluggable verifier for a single governance signature scheme. */
+type GovernanceVerifier = (event: GovernanceAttestationEvent, context: GovernanceVerifyContext) => Promise<boolean> | boolean;
+interface VerifyGovernanceOptions {
+    /**
+     * Per-scheme verifier overrides. An `eip712` verifier MUST be supplied here
+     * (e.g. via {@link createEip712GovernanceVerifier}); sr25519/ed25519 fall back
+     * to the built-in @polkadot verifiers when not overridden.
+     */
+    verifiers?: Partial<Record<GovernanceSignatureScheme, GovernanceVerifier>>;
+    /**
+     * The set of attestor identities (SS58 / 0x-address, case-insensitive) that
+     * are authorized to sign governance attestations. The attestor identity comes
+     * from the untrusted trace, so a cryptographically valid self-signed
+     * attestation from an arbitrary key is NOT a real sign-off — only a key on
+     * this list counts. When OMITTED, governance verification FAILS CLOSED: every
+     * attestation is `authorized: false` / `verified: false`, so an
+     * "anyone can sign" attestation can never fold into a passing bundle verdict.
+     * Optionally scope keys to a role via {@link authorizedAttestorsByRole}.
+     */
+    authorizedAttestors?: string[];
+    /**
+     * Per-role authorized attestors (case-insensitive). When present for an
+     * attestation's role, the signer must be listed under THAT role — a
+     * data-steward key cannot pass off a release-authority sign-off. Falls back to
+     * {@link authorizedAttestors} for roles not present here.
+     */
+    authorizedAttestorsByRole?: Record<string, string[]>;
+}
+/** Per-attestation verification result. */
+interface GovernanceAttestationSummary {
+    eventId: string;
+    role: string;
+    attestor: string;
+    scheme: GovernanceSignatureScheme;
+    policyRef: string;
+    decisionRef: string;
+    /** The signature cryptographically verifies AND the signer is authorized. */
+    verified: boolean;
+    /** The attestor is on the caller-supplied authorized-signer allow-list. */
+    authorized: boolean;
+    error?: string;
+}
+/**
+ * Verify every `governance-attestation` event in a bundle and return a summary
+ * tuple per attestation. Auditors get governance provenance "for free" — this
+ * is also invoked by `verifyBundle(bundle, { governance: true })`.
+ */
+declare function verifyGovernanceAttestations(bundle: TraceBundle, opts?: VerifyGovernanceOptions): Promise<GovernanceAttestationSummary[]>;
+/**
+ * Build an `eip712` {@link GovernanceVerifier} from an injected
+ * `verifyTypedData` (e.g. viem's). Keeps viem out of this package's deps.
+ *
+ * The schema pins (`expectedDomain`/`expectedPrimaryType`/`expectedTypes`) are
+ * MANDATORY: the event's `eip712.{domain,primaryType,types}` are attacker-
+ * controlled, so without pins an attacker signs an EMPTY struct
+ * (`types:{Attestation:[]}`) with their own key and smuggles the claim fields as
+ * untyped message extras the signature never commits to. The pinned primaryType
+ * must also declare `role`, `policyRef`, `decisionRef`, `runId`, and `signedAt`
+ * so the signature provably binds them. `signedAt` is then cross-checked against
+ * the recorded event and held to a freshness window so a signed sign-off cannot
+ * be replayed or backdated.
+ *
+ * @example
+ * ```typescript
+ * import { verifyTypedData } from "viem";
+ * const summary = await verifyGovernanceAttestations(bundle, {
+ *   verifiers: {
+ *     eip712: createEip712GovernanceVerifier({
+ *       verifyTypedData,
+ *       expectedDomain: { name: "Orynq", version: "1" },
+ *       expectedPrimaryType: "Attestation",
+ *       expectedTypes: {
+ *         Attestation: [
+ *           { name: "role", type: "string" },
+ *           { name: "policyRef", type: "string" },
+ *           { name: "decisionRef", type: "string" },
+ *           { name: "runId", type: "string" },
+ *           { name: "signedAt", type: "string" },
+ *         ],
+ *       },
+ *     }),
+ *   },
+ *   authorizedAttestors: ["0x<release-authority>"],
+ * });
+ * ```
+ */
+declare function createEip712GovernanceVerifier(deps: {
+    verifyTypedData: (args: {
+        address: `0x${string}`;
+        domain: Record<string, unknown>;
+        types: Record<string, Array<{
+            name: string;
+            type: string;
+        }>>;
+        primaryType: string;
+        message: Record<string, unknown>;
+        signature: `0x${string}`;
+    }) => Promise<boolean> | boolean;
+    /**
+     * Expected EIP-712 domain (name/version/chainId/verifyingContract). The
+     * event's `eip712.domain` is attacker-controlled, so the verifier requires an
+     * EXACT match on every field — a swapped verifyingContract/chainId/name is
+     * rejected before the signature is trusted.
+     */
+    expectedDomain: Record<string, unknown>;
+    /** Expected `primaryType`; a mismatch is rejected. */
+    expectedPrimaryType: string;
+    /** Expected `types` map; the event's must deep-equal it. */
+    expectedTypes: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    /**
+     * Max age of an attestation, in ms, before it is rejected as stale — measured
+     * from `signedAt` to `nowMs`. Also rejects far-future timestamps beyond the
+     * same window (clock-skew tolerance). Defaults to {@link DEFAULT_EIP712_FRESHNESS_MS}.
+     */
+    freshnessToleranceMs?: number;
+    /** Epoch-ms clock override (testing). Defaults to `Date.now()`. */
+    nowMs?: number;
+}): GovernanceVerifier;
+
 /**
  * @fileoverview Bundle creation, extraction, verification, and signing for trace bundles.
  *
@@ -1320,6 +1760,31 @@ declare function verifySpanInclusion(proof: MerkleProof, span: TraceSpan, events
  * ```
  */
 
+/**
+ * Outcome shape returned by an injected tool-receipt verifier (provided by
+ * `@fluxpointstudios/orynq-sdk-tool-receipts` — passed in to avoid a circular
+ * dependency on that package from process-trace).
+ */
+interface ToolReceiptVerifyOutcome {
+    valid: boolean;
+    errors: string[];
+}
+/** Options for {@link verifyBundle}. */
+interface VerifyBundleOptions {
+    /**
+     * Verify `governance-attestation` events. `true` uses the built-in
+     * sr25519/ed25519 verifiers; pass {@link VerifyGovernanceOptions} to register
+     * a pluggable verifier (e.g. eip712). Any unverified attestation fails the
+     * bundle.
+     */
+    governance?: boolean | VerifyGovernanceOptions;
+    /**
+     * Verify `tool-receipt` events with an injected verifier from
+     * `@fluxpointstudios/orynq-sdk-tool-receipts`. Any failed receipt fails the
+     * bundle.
+     */
+    toolReceipts?: (bundle: TraceBundle) => Promise<ToolReceiptVerifyOutcome> | ToolReceiptVerifyOutcome;
+}
 /**
  * Check if a span should be included in public view.
  *
@@ -1448,7 +1913,7 @@ declare function extractPublicView(bundle: TraceBundle): TraceBundlePublicView;
  * }
  * ```
  */
-declare function verifyBundle(bundle: TraceBundle): Promise<TraceVerificationResult>;
+declare function verifyBundle(bundle: TraceBundle, options?: VerifyBundleOptions): Promise<TraceVerificationResult>;
 /**
  * Sign a bundle using the provided signature provider.
  *
@@ -1715,6 +2180,105 @@ declare function parseChunkContent(content: string): {
     events: TraceEvent[];
 };
 
+/**
+ * @fileoverview Pre-execution model/data manifest pinning (issue #59).
+ *
+ * Location: packages/process-trace/src/model-manifest.ts
+ *
+ * A {@link ModelManifest} fingerprints the model/data state used for an
+ * inference. It is pinned at `createTrace()` time — *before* execution — and
+ * frozen, so the finalized trace can prove that "neither the data nor the model
+ * was altered" for that run. This is distinct from the off-chain *storage*
+ * manifest in `manifest.ts` ({@link TraceManifest}).
+ *
+ * The `manifestFrom*` builders compute a model's fingerprint deterministically
+ * so two traces of "the same model" produce the same `modelManifestHash`.
+ *
+ * @example
+ * ```typescript
+ * const manifest = await manifestFromHuggingFace({
+ *   modelId: "meta-llama/Llama-3.1-8B",
+ *   revision: "0e9e39f249a16976918f6564b8830bc894c89659",
+ * });
+ * const run = await createTrace({ agentId: "agent-1", manifest, strict: true });
+ * ```
+ */
+
+/**
+ * Compute the cryptographic commitment to a model manifest:
+ * `H("poi-trace:model-manifest:v1|" + canonical(manifest))`.
+ *
+ * Deterministic: the same manifest fields always produce the same hash, so two
+ * traces pinning the same model state share a `modelManifestHash`.
+ */
+declare function computeModelManifestHash(manifest: ModelManifest): Promise<string>;
+/**
+ * Validate the shape of a model manifest. Throws on the only hard requirement —
+ * a non-empty `modelHash` — and otherwise returns the manifest unchanged.
+ */
+declare function validateModelManifest(manifest: ModelManifest): ModelManifest;
+/**
+ * Deep-freeze a model manifest so that mutating it after pinning throws (in ESM
+ * strict mode). Returns the same object, frozen.
+ */
+declare function freezeModelManifest(manifest: ModelManifest): Readonly<ModelManifest>;
+/** Common optional inputs shared across the API-model builders. */
+interface CommonManifestInputs {
+    tokenizerHash?: string;
+    systemPrompt?: string;
+    systemPromptHash?: string;
+    trainingDataManifest?: string;
+    metadata?: Record<string, unknown>;
+}
+interface HuggingFaceManifestOptions extends CommonManifestInputs {
+    /** Hugging Face repo id, e.g. "meta-llama/Llama-3.1-8B". */
+    modelId: string;
+    /** Commit sha / branch / tag. A 40-hex commit sha gives the strongest guarantee. */
+    revision?: string;
+}
+/**
+ * Build a manifest for a Hugging Face model. The fingerprint binds the repo id
+ * and revision; pass a commit sha as `revision` for an immutable pin.
+ */
+declare function manifestFromHuggingFace(opts: HuggingFaceManifestOptions): Promise<ModelManifest>;
+interface OpenAIManifestOptions extends CommonManifestInputs {
+    /** Model name, e.g. "gpt-4o". */
+    model: string;
+    /** Dated snapshot id, e.g. "gpt-4o-2024-08-06". Strongly recommended for pinning. */
+    snapshotId?: string;
+}
+/**
+ * Build a manifest for an OpenAI model. Pass a dated `snapshotId` (not just the
+ * floating alias) so the pin is immutable.
+ */
+declare function manifestFromOpenAI(opts: OpenAIManifestOptions): Promise<ModelManifest>;
+interface AnthropicManifestOptions extends CommonManifestInputs {
+    /** Model name, e.g. "claude-opus-4-8". */
+    model: string;
+    /** Dated snapshot id, e.g. "claude-3-5-sonnet-20241022". Strongly recommended. */
+    snapshotId?: string;
+}
+/**
+ * Build a manifest for an Anthropic model. Pass a dated `snapshotId` so the pin
+ * is immutable.
+ */
+declare function manifestFromAnthropic(opts: AnthropicManifestOptions): Promise<ModelManifest>;
+interface CheckpointManifestOptions extends CommonManifestInputs {
+    /** Optional override for the recorded model id (defaults to the file path). */
+    modelId?: string;
+    /** Optional revision/label for the checkpoint. */
+    revision?: string;
+}
+/**
+ * Build a manifest for a local checkpoint file by hashing its bytes. The
+ * `modelHash` is `sha256:<sha256(file bytes)>`, so any change to the checkpoint
+ * changes the manifest.
+ *
+ * Node-only: dynamically imports `node:fs/promises` so the module stays
+ * bundler-safe for non-Node consumers that never call this builder.
+ */
+declare function manifestFromCheckpoint(filepath: string, opts?: CheckpointManifestOptions): Promise<ModelManifest>;
+
 /**
  * @summary Main entry point for @fluxpointstudios/orynq-sdk-process-trace package.
  *
@@ -1755,4 +2319,4 @@ declare function parseChunkContent(content: string): {
  */
 declare const VERSION = "0.1.0";
 
-export { type AnnotatedSpan, type BaseTraceEvent, type Chunk, type ChunkInfo, type CommandEvent, type CreateManifestOptions, type CreateSpanOptions, type CreateTraceOptions, type CustomEvent, DEFAULT_EVENT_VISIBILITY, type DecisionEvent, type DisclosureMode, type DisclosureRequest, type DisclosureResult, type ErrorTraceEvent, HASH_DOMAIN_PREFIXES, type HashDomain, type ManifestVerificationResult, type MerkleProof, type ObservationEvent, type OutputEvent, type RollingHashState, type SchemaVersion, type SignatureProvider, type TraceBundle, type TraceBundlePublicView, type TraceEvent, type TraceEventKind, type TraceManifest, type TraceMerkleTree, type TraceRun, type TraceSpan, type TraceStatus, type TraceVerificationResult, VERSION, type Visibility, addEvent, addSpan, buildSpanMerkleTree, canDisclose, closeSpan, computeEventHash, computeEventHashes, computeManifestHash, computeRollingHash, computeRootHash, computeSpanHash, countEventsByVisibility, countSpansByVisibility, createBundle, createDisclosureRequest, createManifest, createTrace, extractPublicView, filterPublicEvents, finalizeTrace, generateMerkleProof, getSpanEvents as getBundleSpanEvents, getChildSpans, getChunkPath, getEvent, getEventCount, getEventsByKind, getGenesisHash, getRootSpans, getSpan, getSpanCount, getSpanEvents$1 as getSpanEvents, getSpanIndex, initRollingHash, isFinalized, isPublicEvent, isPublicSpan, parseChunkContent, reconstructBundleFromManifest, selectiveDisclose, signBundle, updateRollingHash, verifyBundle, verifyBundleSignature, verifyDisclosure, verifyManifest, verifyMerkleProof, verifyRollingHash, verifySpanDisclosure, verifySpanInclusion };
+export { type AddGovernanceAttestationOptions, type AnnotatedSpan, type AnthropicManifestOptions, type BaseTraceEvent, type CheckpointManifestOptions, type Chunk, type ChunkInfo, type CommandEvent, type CreateManifestOptions, type CreateSpanOptions, type CreateTraceOptions, type CustomEvent, DEFAULT_EVENT_VISIBILITY, type DecisionEvent, type DisclosureMode, type DisclosureRequest, type DisclosureResult, type ErrorTraceEvent, type GovernanceAttestationEvent, type GovernanceAttestationFields, type GovernanceAttestationSummary, type GovernanceEip712Binding, type GovernanceSignContext, type GovernanceSignatureScheme, type GovernanceSigner, type GovernanceVerifier, type GovernanceVerifyContext, HASH_DOMAIN_PREFIXES, type HashDomain, type HuggingFaceManifestOptions, type ManifestVerificationResult, type MerkleProof, type ModelManifest, type ObservationEvent, type OpenAIManifestOptions, type OutputEvent, type RollingHashState, SS58_PREFIX, type SchemaVersion, type SignatureProvider, type SubstrateGovernanceSignerOptions, type ToolReceiptEvent, type ToolReceiptScheme, type ToolReceiptVerifyOutcome, type TraceBundle, type TraceBundlePublicView, type TraceEvent, type TraceEventKind, type TraceManifest, type TraceMerkleTree, type TraceRun, type TraceSpan, type TraceStatus, type TraceVerificationResult, VERSION, type VerifyBundleOptions, type VerifyGovernanceOptions, type Visibility, addEvent, addGovernanceAttestation, addSpan, buildSpanMerkleTree, canDisclose, closeSpan, computeEventHash, computeEventHashes, computeManifestHash, computeModelManifestHash, computeRollingHash, computeRootHash, computeSpanHash, countEventsByVisibility, countSpansByVisibility, createBundle, createDisclosureRequest, createEd25519GovernanceSigner, createEip712GovernanceVerifier, createManifest, createSr25519GovernanceSigner, createTrace, extractPublicView, filterPublicEvents, finalizeTrace, freezeModelManifest, generateMerkleProof, getSpanEvents as getBundleSpanEvents, getChildSpans, getChunkPath, getEvent, getEventCount, getEventsByKind, getGenesisHash, getRootSpans, getSpan, getSpanCount, getSpanEvents$1 as getSpanEvents, getSpanIndex, governanceAttestationPreimage, initRollingHash, isFinalized, isPublicEvent, isPublicSpan, manifestFromAnthropic, manifestFromCheckpoint, manifestFromHuggingFace, manifestFromOpenAI, parseChunkContent, reconstructBundleFromManifest, selectiveDisclose, signBundle, updateRollingHash, validateModelManifest, verifyBundle, verifyBundleSignature, verifyDisclosure, verifyGovernanceAttestations, verifyManifest, verifyMerkleProof, verifyRollingHash, verifySpanDisclosure, verifySpanInclusion };