@adastracomputing/ink 0.1.0-alpha.2 → 0.1.0-alpha.5

package/dist/models/key-entry.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+export declare const KeyStatusSchema: z.ZodEnum<{
+    active: "active";
+    retired: "retired";
+    revoked: "revoked";
+}>;
+export type KeyStatus = z.infer<typeof KeyStatusSchema>;
+export declare const KeyRoleSchema: z.ZodEnum<{
+    signing: "signing";
+    encryption: "encryption";
+}>;
+export type KeyRole = z.infer<typeof KeyRoleSchema>;
+export declare const KeyEntrySchema: z.ZodObject<{
+    keyId: z.ZodString;
+    algorithm: z.ZodEnum<{
+        Ed25519: "Ed25519";
+        X25519: "X25519";
+    }>;
+    publicKeyMultibase: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        retired: "retired";
+        revoked: "revoked";
+    }>;
+    validFrom: z.ZodString;
+    validUntil: z.ZodOptional<z.ZodString>;
+    revokedAt: z.ZodOptional<z.ZodString>;
+    revokeReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type KeyEntry = z.infer<typeof KeyEntrySchema>;
+export interface CandidateKey {
+    keyId: string;
+    publicKey: Uint8Array;
+    status: KeyStatus;
+    /** ISO 8601 timestamp the key becomes usable. Verifier rejects messages
+     * whose `body.timestamp` falls outside [validFrom, validUntil]. Optional
+     * for backward compat with legacy callers that don't track windows. */
+    validFrom?: string;
+    /** ISO 8601 timestamp the key stops being usable. Typically set when a
+     * key transitions to `retired`. A retired key with no validUntil keeps
+     * verifying indefinitely (legacy behavior); set validUntil to bound it. */
+    validUntil?: string;
+    /** ISO 8601 timestamp the key was revoked. Defensive: status === "revoked"
+     * already blocks verification; this field documents the moment. */
+    revokedAt?: string;
+}
+export interface StoredKey {
+    keyId: string;
+    agentId: string;
+    role: KeyRole;
+    algorithm: string;
+    publicKeyMultibase: string;
+    privateKey: Uint8Array | null;
+    status: KeyStatus;
+    validFrom: string;
+    validUntil: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/models/key-entry.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const KeyStatusSchema = z.enum(["active", "retired", "revoked"]);
+export const KeyRoleSchema = z.enum(["signing", "encryption"]);
+export const KeyEntrySchema = z.object({
+    keyId: z.string().min(1),
+    algorithm: z.enum(["Ed25519", "X25519"]),
+    publicKeyMultibase: z.string().startsWith("z"),
+    status: KeyStatusSchema,
+    validFrom: z.string().datetime(),
+    validUntil: z.string().datetime().optional(),
+    revokedAt: z.string().datetime().optional(),
+    revokeReason: z.string().optional(),
+});

package/dist/models/profile.d.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+export declare const AvailabilityConfigSchema: z.ZodObject<{
+    timezone: z.ZodString;
+    meetingHours: z.ZodOptional<z.ZodString>;
+    responseSla: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const ProfileSnapshotSchema: z.ZodObject<{
+    headline: z.ZodString;
+    skills: z.ZodArray<z.ZodString>;
+    interests: z.ZodArray<z.ZodString>;
+    availability: z.ZodOptional<z.ZodObject<{
+        timezone: z.ZodString;
+        meetingHours: z.ZodOptional<z.ZodString>;
+        responseSla: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    openTo: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const ProfileSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    handle: z.ZodString;
+    displayName: z.ZodString;
+    bio: z.ZodString;
+    snapshots: z.ZodObject<{
+        public: z.ZodObject<{
+            headline: z.ZodString;
+            skills: z.ZodArray<z.ZodString>;
+            interests: z.ZodArray<z.ZodString>;
+            availability: z.ZodOptional<z.ZodObject<{
+                timezone: z.ZodString;
+                meetingHours: z.ZodOptional<z.ZodString>;
+                responseSla: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            openTo: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        connected: z.ZodObject<{
+            headline: z.ZodString;
+            skills: z.ZodArray<z.ZodString>;
+            interests: z.ZodArray<z.ZodString>;
+            availability: z.ZodOptional<z.ZodObject<{
+                timezone: z.ZodString;
+                meetingHours: z.ZodOptional<z.ZodString>;
+                responseSla: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            openTo: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        custom: z.ZodRecord<z.ZodString, z.ZodObject<{
+            headline: z.ZodString;
+            skills: z.ZodArray<z.ZodString>;
+            interests: z.ZodArray<z.ZodString>;
+            availability: z.ZodOptional<z.ZodObject<{
+                timezone: z.ZodString;
+                meetingHours: z.ZodOptional<z.ZodString>;
+                responseSla: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            openTo: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AvailabilityConfig = z.infer<typeof AvailabilityConfigSchema>;
+export type ProfileSnapshot = z.infer<typeof ProfileSnapshotSchema>;
+export type Profile = z.infer<typeof ProfileSchema>;

package/dist/models/profile.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export const AvailabilityConfigSchema = z.object({
+    timezone: z.string(),
+    meetingHours: z.string().optional(),
+    responseSla: z.string().optional(),
+});
+export const ProfileSnapshotSchema = z.object({
+    headline: z.string().max(500),
+    skills: z.array(z.string().max(100)).max(50),
+    interests: z.array(z.string().max(100)).max(50),
+    availability: AvailabilityConfigSchema.optional(),
+    openTo: z.array(z.string().max(100)).max(20),
+});
+export const ProfileSchema = z.object({
+    agentId: z.string(),
+    handle: z.string(),
+    displayName: z.string().max(200),
+    bio: z.string().max(2000),
+    snapshots: z.object({
+        public: ProfileSnapshotSchema,
+        connected: ProfileSnapshotSchema,
+        custom: z.record(z.string(), ProfileSnapshotSchema),
+    }),
+});

package/docs/maturity.md

@@ -17,7 +17,7 @@
   implementations should report discrepancies as issues.
 - The protocol is in use by one production integrator (Tulpa). That is
   one data point, not a guarantee of robustness at scale.
-- The reference implementation in `src/` runs on any runtime providing
+- The library in `src/` runs on any runtime providing
   standard Web Crypto (`crypto.subtle`) and `fetch`, modern Node, Deno,
   Bun, and edge runtimes. Browser use is feasible but not exercised by
   the maintainers.
@@ -55,7 +55,7 @@ Pre-1.0 releases follow `0.Y.Z` semantics:
 
 - `0.Y.0`, Minor version bump indicates a wire-format change. Receivers
   must support at least one prior minor during a transition window.
-- `0.Y.Z` (Z > 0), Patch bumps fix bugs in the reference implementation
+- `0.Y.Z` (Z > 0), Patch bumps fix bugs in the library
   and update test vectors where needed. They do not change wire format.
 
 Breaking changes before v1.0 will be announced in the repository
@@ -71,7 +71,7 @@ be a real incident:
    falls inside the in-scope protections and you accept the out-of-scope
    limits.
 2. Run `../test-vectors/*` against your implementation.
-3. Fuzz your envelope parser. The reference implementation's tests are
+3. Fuzz your envelope parser. The library's tests are
    not a substitute.
 4. Pen-test the rotation and revocation flows specifically. The
    authority rule is the single most security-sensitive piece and the

package/docs/threat-model.md

@@ -80,7 +80,7 @@ bounds the damage window but does not eliminate it. Key custody is out of
 scope.
 
 ### Malicious marketplace extensions (if you integrate one)
-The reference implementation does not include an extension/marketplace
+The library does not include an extension/marketplace
 layer. A product that integrates INK and adds a delegation-token layer
 (for third-party agents to act on behalf of users) must design its own
 trust model for the marketplace, manifest review, and capability

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adastracomputing/ink",
-  "version": "0.1.0-alpha.2",
-  "description": "Reference implementation and specification of the INK (Inter-agent Networking Kernel) protocol",
+  "version": "0.1.0-alpha.5",
+  "description": "Library and specification for the INK (Inter-agent Networking Kernel) protocol",
   "license": "MIT OR Apache-2.0",
   "author": "Ad Astra Computing Inc.",
   "repository": {
@@ -13,24 +13,24 @@
     "url": "https://github.com/Ad-Astra-Computing/ink/issues"
   },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "bin": {
     "ink": "./bin/ink.mjs"
   },
   "files": [
-    "src/",
+    "dist/",
     "bin/",
     "specs/",
     "docs/",
@@ -43,21 +43,25 @@
     "CODE_OF_CONDUCT.md"
   ],
   "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/ test/ scripts/",
-    "check:surface": "tsx scripts/check-public-surface.ts"
+    "check:surface": "tsx scripts/check-public-surface.ts",
+    "check:pack": "./scripts/check-pack.sh",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@noble/curves": "^2.2.0",
     "@noble/ed25519": "^3.1.0",
-    "@noble/hashes": "^1.8.0",
+    "@noble/hashes": "^2.2.0",
     "canonicalize": "^2.1.0",
-    "zod": "^3.23.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260418.1",
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.12.4",
     "@typescript-eslint/eslint-plugin": "^8.60.0",
     "@typescript-eslint/parser": "^8.60.0",
     "eslint": "^10.4.0",
@@ -71,6 +75,6 @@
     "ed25519",
     "atproto",
     "agent-to-agent",
-    "reference-implementation"
+    "transparency-log"
   ]
 }

package/specs/ink-auditability.md

@@ -461,9 +461,9 @@ The audit service:
 1. Accepts signed `InkAuditEvent` submissions from agents
 2. Appends them to a **Merkle tree** (not just a hash chain, enables efficient inclusion proofs)
 3. Returns a **signed inclusion receipt** proving the event was recorded at a specific tree position and timestamp
-4. Serves **inclusion proofs** and **consistency proofs** on demand
+4. Serves **inclusion proofs** on demand (per-submission via the inclusion receipt and per-query via the signed `audit_query_response` envelope). **Consistency proofs** between two arbitrary checkpoints are not in scope for alpha.3; consistency-proof verification against external `tlog-witness` cosigners (§7.0) is the alpha.3 mitigation against split-view attacks.
 
-The service CANNOT forge events (they carry the submitting agent's Ed25519 signature). It CAN prove:
+The service CANNOT forge events that verifiers will accept, because every returned event carries the submitting agent's Ed25519 `agentSignature` and §7.3 verifiers re-check it against the agent's published keys. A witness that commits a fabricated event_json into its Merkle tree can produce a valid inclusion proof, but verifiers will reject the response when the agent signature fails to validate. (Verifiers that walk Merkle proofs without checking `agentSignature` lose this guarantee; see §7.5.) The service CAN prove:
 - That a specific event was submitted at a specific time (inclusion)
 - That the log is append-only and no events have been removed (consistency)
 - That two parties submitted conflicting events for the same message (conflict detection)
@@ -531,41 +531,66 @@ Authorization: INK-Ed25519 <signature>
 }
 ```
 
-**Response includes Merkle inclusion proofs:**
+**Response includes Merkle inclusion proofs and is signed by the witness:**
 
 ```json
 {
   "protocol": "ink/0.1",
-  "type": "network.tulpa.audit_response",
+  "type": "network.tulpa.audit_query_response",
+  "serviceDid": "did:web:witness.example.com",
   "messageId": "msg-123",
-  "events": [ /* InkAuditEvent[] from all agents */ ],
+  "requester": "did:plc:requester",
+  "events": [ /* InkAuditEvent[] visible to the requester */ ],
   "proofs": [
     {
       "eventId": "01JBTEST0001",
       "leafIndex": 48290,
-      "inclusionPath": ["<hash>", "<hash>", "..."],
-      "treeSize": 48291,
-      "rootHash": "<SHA-256 hex>"
+      "inclusionProof": ["<hash>", "<hash>", "..."]
     }
   ],
-  "serviceSignature": "<Ed25519 over JCS(response)>"
+  "treeSize": 48291,
+  "rootHash": "<SHA-256 hex of Merkle tree root at response time>",
+  "timestamp": "2026-03-19T13:00:01Z",
+  "serviceSignature": "<Ed25519, see canonical format below>"
 }
 ```
 
+**Canonical signature format.** `serviceSignature` is an Ed25519 signature over the bytes:
+
+```
+"ink/audit-query-response/v1\n" || JCS(response-fields-without-serviceSignature)
+```
+
+The signed payload binds the witness's `serviceDid`, the `messageId` requested, the authenticated `requester` whose access-control scope produced the result, every returned event, every inclusion proof, the witness's `treeSize` and `rootHash` at response time and the `timestamp`. The `proofs` array has one entry per event, keyed by `eventId`; verifiers MUST reject if proofs do not match events one-to-one. `treeSize` and `rootHash` apply uniformly to every proof. The `requester` binding prevents cross-requester replay: a witness response generated for Alice cannot be presented to Bob as Bob's authoritative view of the same `messageId`. Verifiers MUST check `requester` equals the locally authenticated requester before treating the response as their own scoped view.
+
+Per-event scope: a signed envelope binds `messageId` and `requester` but says nothing about the event objects until verifiers look inside them. To prevent a witness or a tampering intermediary from smuggling out-of-scope events into a signed response, verifiers MUST reject any response where, for any returned event, `event.messageId` differs from the envelope `messageId`, OR the envelope `requester` is neither `event.agentId` nor `event.counterpartyId`. Witnesses SHOULD reject the same conditions at signing time as defense in depth against storage corruption.
+
+Empty-log responses: a witness that has not yet committed any leaves reports `treeSize: 0` and `rootHash` equal to SHA-256 of the empty string (`e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`). A signed response with `treeSize: 0` is legitimate but MUST also have empty `events`, empty `proofs` and the empty-tree `rootHash`. Verifiers MUST reject any `treeSize: 0` response that deviates from this shape.
+
+Per-event agent signatures: Merkle validity alone does NOT prove a returned event was produced by the agent named in `event.agentId`. A witness could in principle commit a fabricated event_json that is not a real `InkAuditEvent`. Every returned event MUST therefore include its `agentSignature` field. Verifiers MUST resolve the submitting agent's published Ed25519 keys (via Agent Card §2) and verify `agentSignature` on every event in addition to walking the Merkle proof. A response that omits `agentSignature` on any event MUST be rejected as structurally invalid.
+
+Truncation: witnesses MUST NOT silently sign a partial result. If the requester's visible event set for a `messageId` exceeds the witness's response cap, the witness MUST return an unsigned error response (HTTP 413). A signed response is, by definition, a complete enumeration of the requester's visible events for that `messageId` at `(treeSize, rootHash)`.
+
+Determinism: witnesses MUST emit `events` and matching `proofs` in a stable, deterministic order so verifiers can reproduce the signed bytes from the underlying records.
+
+Leaf hash: each event's Merkle leaf hash is `SHA-256(0x00 || JCS(event-without-agentSignature))`. The leading `0x00` byte is the RFC 6962 leaf-domain-separation tag; internal Merkle nodes use `0x01 || left || right`. Verifiers MUST rehash the returned `event` object themselves (stripping `agentSignature`, then JCS, then SHA-256 with the `0x00` prefix) and use that hash as the leaf input to `inclusionProof`. They MUST NOT trust any leaf-hash value supplied by the witness alongside the event. Walking the proof from this computed leaf hash up through `inclusionProof` MUST reach the top-level `rootHash` per the proof construction in §7.2. The INK library exposes this exact computation as `computeAuditMerkleLeafHash`; it is distinct from `computeEventHash`, which is the unprefixed SHA-256 used for `previousEventHash` chain linkage and MUST NOT be used as the Merkle leaf input.
+
 #### 7.4 Access Control
 
 The audit service operates under **access-controlled transparency** (per SCITT):
 - Events are tagged with the `messageId` and the DIDs of sender/recipient
-- Only the sender, recipient or a party with a valid delegation chain (§ INK Authorization Chain) can query events for a given `messageId`
+- Only the sender or recipient (i.e. an event's own `agentId` or `counterpartyId`) can query events for a given `messageId`. The witness MUST refuse to serve a row to any other requester
 - The service verifies the requester's identity via INK auth (§3.3) before serving events
-- The Merkle tree structure is public (anyone can verify consistency proofs) but event contents are access-controlled
+- The Merkle tree structure is public: anyone can verify inclusion proofs against signed checkpoints and, where consistency-proof endpoints are deployed, cross-check that checkpoints are append-only. Event contents remain access-controlled
+
+Delegated queries (where a third-party agent queries events on behalf of a principal via an INK Authorization Chain) are not in scope for alpha.3. A future revision will define the additional envelope fields the witness signs to bind the effective principal alongside the immediate requester, and verifiers will be updated accordingly. Until then, conformant witnesses MUST treat the per-event scope rule in §7.3 as authoritative: a returned event's `agentId` or `counterpartyId` MUST equal the response `requester`.
 
 This follows SCITT's model: the transparency guarantee (append-only, no suppression) is public, but the data itself is private.
 
 #### 7.5 Trust Model
 
 The audit service is a **semi-trusted witness**, not an arbiter:
-- It CANNOT forge events (Ed25519 signatures from agents)
+- It CANNOT forge events that verifiers will accept, because verifiers re-check `event.agentSignature` against the agent's published Ed25519 keys (§7.3). A witness that commits a fabricated event_json into its Merkle tree can produce a valid inclusion proof, but the per-event agent-signature check fails and the response is rejected. Verifiers that walk the proof without checking `agentSignature` lose this guarantee.
 - It CANNOT modify events without breaking Merkle proofs
 - It CAN suppress events by refusing to include them (detectable via consistency proofs between submissions)
 - It CAN be unavailable (agents fall back to bilateral exchange)

package/specs/ink-compliance-checklist.md

@@ -16,7 +16,7 @@ This checklist lets an independent implementer verify INK conformance without re
 - **SHOULD**, recommended; deviations require justification
 - **MAY**, truly optional; advertised via capability
 
-**Status column** applies to the Tulpa reference implementation:
+**Status column** applies to the Tulpa implementation:
 - **Required**, part of the v1 wire contract
 - **Optional**, capability-gated, not assumed
 - **Extension**, defined but not required for base interop
@@ -145,6 +145,14 @@ This checklist lets an independent implementer verify INK conformance without re
 | W6 | Checkpoint: C2SP tlog-checkpoint format at `GET /ink/v1/checkpoint` | SHOULD | Optional | Auditability §7 |, | `witness/witness/test/endpoints.test.ts (witness repo)` |
 | W7 | Transport auth on submit: dual signature (transport + event) | MUST | Optional | Auditability §7 | `witness.json` | `witness/witness/test/endpoints.test.ts (witness repo)` |
 | W8 | Submit includes `signingKeyId` in transport auth | SHOULD | Required | Key Rotation Phase 3 |, | `test/ink-key-rotation.test.ts` |
+| W9 | Query response is the signed `network.tulpa.audit_query_response` envelope binding `serviceDid`, `messageId`, `requester`, `events`, `proofs`, `treeSize`, `rootHash`, `timestamp` | MUST | Optional | Auditability §7.3 | `witness.json` | `test/audit-query-response.test.ts`, `test/verify-audit-query-response.test.ts` |
+| W10 | Per-event Merkle proof rule: leaf = `SHA-256(0x00 \|\| JCS(event-without-agentSignature))` (RFC 6962) | MUST | Optional | Auditability §7.3 | `witness.json` | `test/merkle-leaf-hash.test.ts` |
+| W11 | Per-event scope: `event.messageId == envelope.messageId` AND `envelope.requester ∈ {event.agentId, event.counterpartyId}` | MUST | Optional | Auditability §7.3, §7.4 |, | `test/verify-audit-query-response.test.ts` |
+| W12 | Deterministic result-set ordering so signed bytes are reproducible | MUST | Optional | Auditability §7.3 |, | `witness/witness/test/security-round12.test.ts (witness repo)` |
+| W13 | Fail-closed on truncation: refuse to sign a partial result; return unsigned 413 | MUST | Optional | Auditability §7.3 |, | `witness/witness/test/security-round12.test.ts (witness repo)` |
+| W14 | Fail-closed on storage integrity (event_hash mismatch, missing Merkle node, column-vs-event_json drift): HTTP 500, no signed response | MUST | Optional | Auditability §7.3 |, | `witness/witness/test/security-round12.test.ts (witness repo)` |
+| W15 | Empty-log response: `treeSize == 0` MUST have empty `events`, empty `proofs` and canonical empty-tree `rootHash` | MUST | Optional | Auditability §7.3 |, | `test/verify-audit-query-response.test.ts` |
+| W16 | Every returned event MUST include `agentSignature`; verifiers MUST verify it against the agent's published keys (witness Merkle validity does not prove agent provenance) | MUST | Optional | Auditability §7.3, §7.5 |, | `test/verify-audit-query-response.test.ts` |
 
 ---
 

package/src/audit/inclusion-receipt.ts

@@ -1,268 +0,0 @@
-/**
- * INK Auditability Section 7 inclusion-receipt verification.
- *
- * A witness returns a signed inclusion receipt when an agent submits
- * an audit event. The receipt commits the witness to a specific
- * (leafIndex, treeSize, rootHash) for the submitted event.
- *
- * To verify a receipt independently:
- *  1. Check the witness's serviceSignature against its published
- *     Ed25519 public key. The signed bytes are
- *     `ink/audit-inclusion/v1\n` + JCS({eventId, leafIndex, treeSize,
- *     rootHash, timestamp}).
- *  2. (Optional) Re-hash the audit event to derive the leaf hash and
- *     walk the inclusion proof up to the witness's claimed rootHash.
- *  3. (Optional) Cross-check the receipt against a later signed
- *     checkpoint: the tree only grew (treeSize >= receipt.treeSize)
- *     and if equal, the rootHash matches.
- *
- * This module ships the pure verification logic. The bin/verify-inclusion
- * CLI is a thin wrapper that fetches the witness DID document + a
- * current checkpoint and calls verifyInclusionReceipt.
- */
-import * as ed from "@noble/ed25519";
-import { base64urlDecode, jcsCanonicalize, hexToBytes, bytesToHex } from "../crypto/ink.js";
-
-export interface InclusionReceipt {
-  eventId: string;
-  leafIndex: number;
-  treeSize: number;
-  rootHash: string;
-  inclusionProof: string[];
-  /** ISO 8601 timestamp at which the witness committed the leaf. */
-  timestamp: string;
-  /** Base64url Ed25519 signature over the canonical bytes. */
-  serviceSignature: string;
-}
-
-export interface VerifyStep {
-  name: string;
-  pass: boolean;
-  detail?: string;
-}
-
-export interface InclusionReceiptVerifyResult {
-  valid: boolean;
-  steps: VerifyStep[];
-}
-
-/**
- * Verify an INK inclusion receipt.
- *
- * Always performs:
- *  - Structural validation of the receipt object
- *  - Service signature verification against `witnessPublicKey`
- *
- * Optionally performs (when the corresponding input is provided):
- *  - Leaf-to-root proof walk (`eventHash`)
- *  - Cross-check against a later signed checkpoint (`laterCheckpoint`)
- */
-export async function verifyInclusionReceipt(opts: {
-  receipt: InclusionReceipt;
-  /** Raw 32-byte Ed25519 public key of the witness service. */
-  witnessPublicKey: Uint8Array;
-  /** Optional leaf hash (SHA-256 of JCS(audit event without agentSignature),
-   *  hex-encoded). When provided, the inclusion proof is walked from
-   *  the leaf up to the claimed rootHash. */
-  eventHash?: string;
-  /** Optional later checkpoint to cross-check the receipt against.
-   *  Must come from a `/ink/v1/checkpoint` response that the verifier
-   *  has separately validated as authentic. */
-  laterCheckpoint?: { treeSize: number; rootHash: string };
-}): Promise<InclusionReceiptVerifyResult> {
-  const steps: VerifyStep[] = [];
-  const { receipt, witnessPublicKey, eventHash, laterCheckpoint } = opts;
-
-  // ── Step 1: structural validation ──
-  const structuralProblem = checkReceiptShape(receipt);
-  if (structuralProblem) {
-    steps.push({ name: "structure", pass: false, detail: structuralProblem });
-    return { valid: false, steps };
-  }
-  steps.push({ name: "structure", pass: true });
-
-  // ── Step 2: signature ──
-  const signedPayload = {
-    eventId: receipt.eventId,
-    leafIndex: receipt.leafIndex,
-    treeSize: receipt.treeSize,
-    rootHash: receipt.rootHash,
-    timestamp: receipt.timestamp,
-  };
-  const sigBase = `ink/audit-inclusion/v1\n${jcsCanonicalize(signedPayload)}`;
-  let sigValid = false;
-  try {
-    const sig = base64urlDecode(receipt.serviceSignature);
-    sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey);
-  } catch (e) {
-    steps.push({
-      name: "signature",
-      pass: false,
-      detail: e instanceof Error ? e.message : "signature decode failed",
-    });
-    return { valid: false, steps };
-  }
-  if (!sigValid) {
-    steps.push({ name: "signature", pass: false, detail: "Ed25519 verification failed" });
-    return { valid: false, steps };
-  }
-  steps.push({ name: "signature", pass: true });
-
-  // ── Step 3: inclusion-proof walk (optional) ──
-  if (eventHash !== undefined) {
-    if (!/^[0-9a-f]{64}$/.test(eventHash)) {
-      steps.push({ name: "proof", pass: false, detail: "eventHash must be 64 lowercase hex chars" });
-      return { valid: false, steps };
-    }
-    const verified = await verifyInclusionProof(
-      eventHash,
-      receipt.inclusionProof,
-      receipt.leafIndex,
-      receipt.treeSize,
-      receipt.rootHash,
-    );
-    if (!verified) {
-      steps.push({ name: "proof", pass: false, detail: "leaf-to-root walk did not reach claimed rootHash" });
-      return { valid: false, steps };
-    }
-    steps.push({ name: "proof", pass: true });
-  }
-
-  // ── Step 4: later-checkpoint cross-check (optional) ──
-  if (laterCheckpoint !== undefined) {
-    const cpShape = checkCheckpointShape(laterCheckpoint);
-    if (cpShape) {
-      steps.push({ name: "checkpoint", pass: false, detail: cpShape });
-      return { valid: false, steps };
-    }
-    if (laterCheckpoint.treeSize < receipt.treeSize) {
-      steps.push({
-        name: "checkpoint",
-        pass: false,
-        detail: `checkpoint treeSize ${laterCheckpoint.treeSize} < receipt treeSize ${receipt.treeSize} (witness rewound the tree)`,
-      });
-      return { valid: false, steps };
-    }
-    if (laterCheckpoint.treeSize === receipt.treeSize && laterCheckpoint.rootHash !== receipt.rootHash) {
-      steps.push({
-        name: "checkpoint",
-        pass: false,
-        detail: "checkpoint rootHash differs from receipt rootHash at same treeSize (fork)",
-      });
-      return { valid: false, steps };
-    }
-    steps.push({ name: "checkpoint", pass: true });
-  }
-
-  return { valid: true, steps };
-}
-
-// ── Internal helpers ──
-
-/** Generous upper bound on inclusion-proof length. Real proofs are
- *  ceil(log2(treeSize)) entries; a treeSize > 2^60 is implausible for
- *  any real log, so capping at 64 entries bounds memory + walker depth
- *  without rejecting legitimate input. The signed payload binds
- *  treeSize but not the proof array itself, so an attacker could
- *  otherwise append unbounded garbage to a valid receipt. */
-const MAX_PROOF_LENGTH = 64;
-
-function checkReceiptShape(receipt: InclusionReceipt): string | null {
-  if (receipt === null || typeof receipt !== "object") return "receipt is not an object";
-  if (typeof receipt.eventId !== "string" || receipt.eventId.length === 0) return "eventId missing";
-  if (!Number.isInteger(receipt.leafIndex) || receipt.leafIndex < 0) return "leafIndex must be non-negative integer";
-  if (!Number.isInteger(receipt.treeSize) || receipt.treeSize < 1) return "treeSize must be positive integer";
-  if (receipt.leafIndex >= receipt.treeSize) return "leafIndex must be < treeSize";
-  if (typeof receipt.rootHash !== "string" || !/^[0-9a-f]{64}$/.test(receipt.rootHash)) {
-    return "rootHash must be 64 lowercase hex chars";
-  }
-  if (!Array.isArray(receipt.inclusionProof)) return "inclusionProof must be an array";
-  if (receipt.inclusionProof.length > MAX_PROOF_LENGTH) {
-    return `inclusionProof exceeds max length of ${MAX_PROOF_LENGTH} entries`;
-  }
-  for (const p of receipt.inclusionProof) {
-    if (typeof p !== "string" || !/^[0-9a-f]{64}$/.test(p)) {
-      return "every inclusionProof entry must be 64 lowercase hex chars";
-    }
-  }
-  if (typeof receipt.timestamp !== "string" || receipt.timestamp.length === 0) return "timestamp missing";
-  if (typeof receipt.serviceSignature !== "string" || receipt.serviceSignature.length === 0) {
-    return "serviceSignature missing";
-  }
-  return null;
-}
-
-function checkCheckpointShape(cp: { treeSize: number; rootHash: string }): string | null {
-  if (cp === null || typeof cp !== "object") return "laterCheckpoint must be an object";
-  if (!Number.isInteger(cp.treeSize) || cp.treeSize < 0) {
-    return "laterCheckpoint.treeSize must be a non-negative integer";
-  }
-  if (typeof cp.rootHash !== "string" || !/^[0-9a-f]{64}$/.test(cp.rootHash)) {
-    return "laterCheckpoint.rootHash must be 64 lowercase hex chars";
-  }
-  return null;
-}
-
-async function hashPair(left: string, right: string): Promise<string> {
-  const l = hexToBytes(left);
-  const r = hexToBytes(right);
-  const buf = new Uint8Array(1 + l.length + r.length);
-  buf[0] = 0x01;
-  buf.set(l, 1);
-  buf.set(r, 1 + l.length);
-  const out = new Uint8Array(await crypto.subtle.digest("SHA-256", buf));
-  return bytesToHex(out);
-}
-
-function largestPowerOf2LessThan(n: number): number {
-  if (n <= 1) return 0;
-  let p = 1;
-  while (p * 2 < n) p *= 2;
-  return p;
-}
-
-async function recomputeRoot(
-  currentHash: string,
-  proof: string[],
-  proofIdx: number,
-  leafIndex: number,
-  start: number,
-  size: number,
-): Promise<string> {
-  if (size === 1) {
-    // Reached the leaf. Any proof entries left over mean the proof was
-    // padded with extras; reject it as malformed.
-    if (proofIdx !== proof.length) throw new Error("inclusion proof has unused entries");
-    return currentHash;
-  }
-  if (proofIdx >= proof.length) {
-    // Proof exhausted before walking down to the leaf. Without this,
-    // an attacker can present a short proof against a tree > 1 leaf
-    // and the walker returns currentHash (the leaf), which a verifier
-    // might mistakenly equate to rootHash.
-    throw new Error("inclusion proof too short for declared treeSize");
-  }
-  const split = largestPowerOf2LessThan(size);
-  if (leafIndex - start < split) {
-    const leftResult = await recomputeRoot(currentHash, proof, proofIdx + 1, leafIndex, start, split);
-    return hashPair(leftResult, proof[proofIdx]!);
-  }
-  const rightResult = await recomputeRoot(currentHash, proof, proofIdx + 1, leafIndex, start + split, size - split);
-  return hashPair(proof[proofIdx]!, rightResult);
-}
-
-async function verifyInclusionProof(
-  leafHash: string,
-  proof: string[],
-  leafIndex: number,
-  treeSize: number,
-  expectedRootHash: string,
-): Promise<boolean> {
-  if (leafIndex < 0 || leafIndex >= treeSize) return false;
-  try {
-    const computed = await recomputeRoot(leafHash, proof, 0, leafIndex, 0, treeSize);
-    return computed === expectedRootHash;
-  } catch {
-    return false;
-  }
-}