@statewavedev/sdk 0.10.0 → 0.10.1

package/README.md

@@ -97,9 +97,9 @@ console.log(`${timeline.episodes.length} episodes, ${timeline.memories.length} m
 await sw.deleteSubject("user-42");
 ```
 
-## Governance & audit (v0.8)
+## Governance & audit (v0.8+)
 
-The SDK surfaces the [state-assembly receipts](https://github.com/smaramwbc/statewave-docs/blob/main/receipts.md) and [sensitivity-labels / policy](https://github.com/smaramwbc/statewave-docs/blob/main/sensitivity-labels.md) layer added in server v0.8.
+The SDK surfaces the [state-assembly receipts](https://github.com/smaramwbc/statewave-docs/blob/main/receipts.md) and [sensitivity-labels / policy](https://github.com/smaramwbc/statewave-docs/blob/main/sensitivity-labels.md) layer added in server v0.8, plus the v0.9 [HMAC signing](https://github.com/smaramwbc/statewave/blob/main/docs/state-assembly-receipts.md) and [as-of replay](https://github.com/smaramwbc/statewave/blob/main/docs/replay.md) surfaces.
 
 ```typescript
 import { StatewaveClient } from "@statewavedev/sdk";
@@ -140,6 +140,39 @@ for (const r of receipts) {
   console.log(r.receiptId, r.task);
 }
 
+// Verify the HMAC signature on a stored receipt (v0.9+).
+// `valid` is true | false | null — see ReceiptVerifyResult for the
+// full reason vocabulary (no_signature / key_unavailable / etc.).
+if (bundle.receiptId) {
+  const verdict = await sw.verifyReceipt(bundle.receiptId);
+  if (verdict.valid === true) {
+    console.log(`signature OK — signed by ${verdict.keyId}`);
+  } else if (verdict.valid === false) {
+    console.log("signature mismatch — body may have been tampered with");
+  } else {
+    console.log(`verdict undetermined: ${verdict.reason}`);
+  }
+}
+
+// Replay the receipt against current memories using the original
+// policy bundle captured on the receipt (v0.9+). Returns a diff
+// envelope showing what changed since emission. Pre-v0.9 receipts
+// throw StatewaveUnreplayableError with reason="missing_policy_snapshot".
+import { StatewaveUnreplayableError } from "@statewavedev/sdk";
+try {
+  const replay = await sw.replayReceipt(bundle.receiptId!);
+  if (replay.diff.contextHash.changed) {
+    console.log(`replay differs from original: new id ${replay.replayReceiptId}`);
+  }
+} catch (err) {
+  if (err instanceof StatewaveUnreplayableError) {
+    // err.reason ∈ {"missing_policy_snapshot", "nested_replay", "invalid_snapshot"}
+    console.log(`replay refused: ${err.reason}`);
+  } else {
+    throw err;
+  }
+}
+
 // Set per-memory sensitivity labels (server normalizes — dedup, lowercase, trim).
 // Memories with labels become subject to any active policy bundle for the tenant.
 const updated = await sw.setMemoryLabels({
@@ -246,7 +279,10 @@ All response types are fully typed:
 - `BatchCreateResult` — batch ingestion response
 - `SubjectSummary` — subject with episode/memory counts
 - `ListSubjectsResult` — paginated subject listing
-- `Receipt` + `ReceiptSelectedEntry` + `ReceiptPolicy` + `ReceiptOutput` — state-assembly audit artifact (v0.8) and its nested shapes
+- `Receipt` + `ReceiptSelectedEntry` + `ReceiptPolicy` + `ReceiptOutput` — state-assembly audit artifact (v0.8+) and its nested shapes; v0.9 added HMAC signature fields (`receiptSignatureKeyId`, `receiptSignatureAlgorithm`), `policySnapshot` for replay, and `region` for residency
+- `ReceiptVerifyResult` — `valid` (true | false | null) + `keyId` + `algorithm` + `reason` for the v0.9 HMAC verify endpoint
+- `ReceiptReplayResult` / `ReceiptReplayDiff` — original + replay receipt ids plus the structural diff envelope from `POST /v1/receipts/{id}/replay` (v0.9)
+- `StatewaveUnreplayableError` — thrown by `replayReceipt(...)` on HTTP 422; `.reason` is a discriminated union of `"missing_policy_snapshot" | "nested_replay" | "invalid_snapshot"`
 - `ReceiptList` — cursor-paginated receipt listing
 - `Health` + `HealthFactor` — customer health score and its explainable factors
 - `SLASummary` + `SessionSLA` — SLA metrics, aggregate and per-session

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, CreateHandoffParams, CreateResolutionParams, DeleteResult, Episode, GetContextParams, GetSLAParams, Handoff, Health, ListReceiptsParams, ListResolutionsParams, ListSubjectsResult, Memory, Receipt, ReceiptList, Resolution, SLASummary, SearchMemoriesParams, SearchResult, SetMemoryLabelsParams, Timeline } from "./types.js";
+import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, CreateHandoffParams, CreateResolutionParams, DeleteResult, Episode, GetContextParams, GetSLAParams, Handoff, Health, ListReceiptsParams, ListResolutionsParams, ListSubjectsResult, Memory, Receipt, ReceiptList, ReceiptReplayResult, ReceiptVerifyResult, Resolution, SLASummary, SearchMemoriesParams, SearchResult, SetMemoryLabelsParams, Timeline, UnreplayableReason } from "./types.js";
 /** Structured error from the Statewave API. */
 export declare class StatewaveAPIError extends Error {
     readonly statusCode: number;
@@ -11,6 +11,26 @@ export declare class StatewaveAPIError extends Error {
 export declare class StatewaveConnectionError extends Error {
     constructor(message?: string);
 }
+/**
+ * Raised by `replayReceipt(...)` when the server refuses with HTTP 422.
+ * Subclass of `StatewaveAPIError` so generic handlers still catch it;
+ * adds a typed `reason` field so callers can branch on the structured
+ * refusal vocabulary without parsing the error code.
+ *
+ * `reason` is a discriminated union of:
+ * - `"missing_policy_snapshot"` — pre-v0.9 receipt. No
+ *   `policySnapshot` was captured at emission and the replay engine
+ *   cannot synthesise one retroactively.
+ * - `"nested_replay"` — the receipt is itself a replay
+ *   (`mode === "as_of_replay"`). v0.9 ships one level only; replay
+ *   the source receipt referenced by `parentReceiptId` instead.
+ * - `"invalid_snapshot"` — the snapshot's YAML failed to parse.
+ *   Tampering or corruption at the column level.
+ */
+export declare class StatewaveUnreplayableError extends StatewaveAPIError {
+    readonly reason: UnreplayableReason;
+    constructor(reason: UnreplayableReason, statusCode: number, code: string, message: string, details?: unknown, requestId?: string);
+}
 export declare class StatewaveClient {
     private baseUrl;
     private defaultHeaders;
@@ -47,6 +67,52 @@ export declare class StatewaveClient {
      * to fetch the next page.
      */
     listReceipts(params: ListReceiptsParams): Promise<ReceiptList>;
+    /**
+     * Verify the HMAC signature on a stored receipt (v0.9+ #157).
+     *
+     * Returns a `ReceiptVerifyResult` with `valid` ∈ `{true, false, null}`:
+     * - `true` — signature matches the canonical body (`reason === "ok"`).
+     * - `false` — signature does not cover the body
+     *   (`reason === "signature_mismatch"`).
+     * - `null` — verdict could not be determined; `reason` is one of
+     *   `"no_signature"` (unsigned receipt — pre-v0.9 or tenant didn't
+     *   opt in), `"key_unavailable"` (the keyId rotated out of operator
+     *   config), or `"unsupported_algorithm"` (forward-compat).
+     *
+     * Comparison is constant-time on the server side. The signing key
+     * bytes never appear on the response — only the public `keyId` is
+     * echoed.
+     *
+     * Throws `StatewaveAPIError` on 404 (receipt not found or belongs to
+     * a different tenant — indistinguishable on the wire) and other
+     * non-2xx responses.
+     */
+    verifyReceipt(receiptId: string): Promise<ReceiptVerifyResult>;
+    /**
+     * Re-run the original retrieval against current memories using the
+     * original policy bundle captured in the receipt's `policySnapshot`
+     * (v0.9+ #159).
+     *
+     * Emits a new `mode="as_of_replay"` receipt with `parentReceiptId`
+     * pointing at the source; the original receipt is **never**
+     * modified. Returns the new `replayReceiptId` plus a structural
+     * diff envelope (added/removed selected entries, filter changes,
+     * context-hash diff).
+     *
+     * Semantic: current code + original policy. Replay is *not*
+     * byte-for-byte reproduction; memories that were added, tombstoned,
+     * or supersession-resolved between the original emission and now
+     * will appear in the diff. See `docs/replay.md` in the server repo
+     * for the design rationale.
+     *
+     * Throws `StatewaveUnreplayableError` (HTTP 422) when:
+     * - `reason === "missing_policy_snapshot"` — pre-v0.9 receipt.
+     * - `reason === "nested_replay"` — the receipt is itself a replay.
+     * - `reason === "invalid_snapshot"` — snapshot YAML failed to parse.
+     *
+     * Throws `StatewaveAPIError` on 404 and other non-2xx responses.
+     */
+    replayReceipt(receiptId: string): Promise<ReceiptReplayResult>;
     /**
      * Compute the customer health score (0–100) for a subject, with the
      * explainable factors that drove it. Backs proactive risk triage.

package/dist/client.js

@@ -59,6 +59,40 @@ export class StatewaveConnectionError extends Error {
         this.name = "StatewaveConnectionError";
     }
 }
+/** The documented refusal vocabulary for the v0.9 replay endpoint.
+ *  Mirrors the `UnreplayableReason` type alias in `./types.ts`.
+ *  Auto-promotion to `StatewaveUnreplayableError` only happens when
+ *  the server returns a code with one of these reasons — a future
+ *  unknown reason stays on the generic `StatewaveAPIError` path. */
+const UNREPLAYABLE_REASONS = new Set([
+    "missing_policy_snapshot",
+    "nested_replay",
+    "invalid_snapshot",
+]);
+/**
+ * Raised by `replayReceipt(...)` when the server refuses with HTTP 422.
+ * Subclass of `StatewaveAPIError` so generic handlers still catch it;
+ * adds a typed `reason` field so callers can branch on the structured
+ * refusal vocabulary without parsing the error code.
+ *
+ * `reason` is a discriminated union of:
+ * - `"missing_policy_snapshot"` — pre-v0.9 receipt. No
+ *   `policySnapshot` was captured at emission and the replay engine
+ *   cannot synthesise one retroactively.
+ * - `"nested_replay"` — the receipt is itself a replay
+ *   (`mode === "as_of_replay"`). v0.9 ships one level only; replay
+ *   the source receipt referenced by `parentReceiptId` instead.
+ * - `"invalid_snapshot"` — the snapshot's YAML failed to parse.
+ *   Tampering or corruption at the column level.
+ */
+export class StatewaveUnreplayableError extends StatewaveAPIError {
+    reason;
+    constructor(reason, statusCode, code, message, details, requestId) {
+        super(statusCode, code, message, details, requestId);
+        this.name = "StatewaveUnreplayableError";
+        this.reason = reason;
+    }
+}
 export class StatewaveClient {
     baseUrl;
     defaultHeaders;
@@ -195,6 +229,56 @@ export class StatewaveClient {
             qs.set("limit", String(params.limit));
         return this.get(`/v1/receipts?${qs}`);
     }
+    /**
+     * Verify the HMAC signature on a stored receipt (v0.9+ #157).
+     *
+     * Returns a `ReceiptVerifyResult` with `valid` ∈ `{true, false, null}`:
+     * - `true` — signature matches the canonical body (`reason === "ok"`).
+     * - `false` — signature does not cover the body
+     *   (`reason === "signature_mismatch"`).
+     * - `null` — verdict could not be determined; `reason` is one of
+     *   `"no_signature"` (unsigned receipt — pre-v0.9 or tenant didn't
+     *   opt in), `"key_unavailable"` (the keyId rotated out of operator
+     *   config), or `"unsupported_algorithm"` (forward-compat).
+     *
+     * Comparison is constant-time on the server side. The signing key
+     * bytes never appear on the response — only the public `keyId` is
+     * echoed.
+     *
+     * Throws `StatewaveAPIError` on 404 (receipt not found or belongs to
+     * a different tenant — indistinguishable on the wire) and other
+     * non-2xx responses.
+     */
+    async verifyReceipt(receiptId) {
+        return this.get(`/v1/receipts/${encodeURIComponent(receiptId)}/verify`);
+    }
+    /**
+     * Re-run the original retrieval against current memories using the
+     * original policy bundle captured in the receipt's `policySnapshot`
+     * (v0.9+ #159).
+     *
+     * Emits a new `mode="as_of_replay"` receipt with `parentReceiptId`
+     * pointing at the source; the original receipt is **never**
+     * modified. Returns the new `replayReceiptId` plus a structural
+     * diff envelope (added/removed selected entries, filter changes,
+     * context-hash diff).
+     *
+     * Semantic: current code + original policy. Replay is *not*
+     * byte-for-byte reproduction; memories that were added, tombstoned,
+     * or supersession-resolved between the original emission and now
+     * will appear in the diff. See `docs/replay.md` in the server repo
+     * for the design rationale.
+     *
+     * Throws `StatewaveUnreplayableError` (HTTP 422) when:
+     * - `reason === "missing_policy_snapshot"` — pre-v0.9 receipt.
+     * - `reason === "nested_replay"` — the receipt is itself a replay.
+     * - `reason === "invalid_snapshot"` — snapshot YAML failed to parse.
+     *
+     * Throws `StatewaveAPIError` on 404 and other non-2xx responses.
+     */
+    async replayReceipt(receiptId) {
+        return this.post(`/v1/receipts/${encodeURIComponent(receiptId)}/replay`, undefined);
+    }
     // -- Support: health, SLA, handoff, resolutions ----------------------
     /**
      * Compute the customer health score (0–100) for a subject, with the
@@ -353,6 +437,17 @@ export class StatewaveClient {
             const body = await resp.json();
             const err = body?.error;
             if (err && typeof err.code === "string") {
+                // Promote unreplayable.<reason> refusals into a typed
+                // exception so callers can `catch (e) { if (e instanceof
+                // StatewaveUnreplayableError) ... e.reason }` without
+                // string-matching the error code. Forward-compat: an
+                // unrecognised future reason stays on the generic path.
+                if (resp.status === 422 && err.code.startsWith("unreplayable.")) {
+                    const reason = err.code.slice("unreplayable.".length);
+                    if (UNREPLAYABLE_REASONS.has(reason)) {
+                        throw new StatewaveUnreplayableError(reason, resp.status, err.code, err.message ?? resp.statusText, err.details, err.request_id);
+                    }
+                }
                 throw new StatewaveAPIError(resp.status, err.code, err.message ?? resp.statusText, err.details, err.request_id);
             }
         }

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { StatewaveClient, StatewaveAPIError, StatewaveConnectionError } from "./client.js";
+export { StatewaveClient, StatewaveAPIError, StatewaveConnectionError, StatewaveUnreplayableError, } from "./client.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1 +1 @@
-export { StatewaveClient, StatewaveAPIError, StatewaveConnectionError } from "./client.js";
+export { StatewaveClient, StatewaveAPIError, StatewaveConnectionError, StatewaveUnreplayableError, } from "./client.js";

package/dist/types.d.ts

@@ -101,14 +101,38 @@ export interface ReceiptOutput {
     canonicalizationVersion: number;
     tokenEstimate: number;
 }
+/**
+ * v0.9 (#159) — self-contained policy bundle envelope embedded on
+ * every v0.9+ receipt. Self-sufficient: the replay engine evaluates
+ * against this bundle even if the live `policy_bundles` row has
+ * since been deleted or overwritten.
+ *
+ * - A null inner pair (`bundleHash` AND `bundleYaml` both null)
+ *   records "no policy bundle was active at emission" — a valid,
+ *   replayable state.
+ * - The whole envelope being absent (`Receipt.policySnapshot ===
+ *   undefined`) marks "pre-v0.9 receipt, no snapshot was ever
+ *   captured" — the replay endpoint refuses those.
+ */
+export interface PolicySnapshot {
+    bundleHash: string | null;
+    bundleYaml: string | null;
+    /** ISO-8601 UTC timestamp captured at receipt emission. */
+    capturedAt: string;
+}
 /**
  * Immutable per-retrieval audit artifact for a single context assembly.
  * See `docs/state-assembly-receipts.md` in the server repository.
+ *
+ * The `mode` discriminator distinguishes:
+ * - `"retrieval"` — receipts emitted by `/v1/context` + `/v1/handoff`.
+ * - `"as_of_replay"` — receipts emitted by `POST /v1/receipts/{id}/replay`
+ *   (v0.9+); the `parentReceiptId` points at the source receipt.
  */
 export interface Receipt {
     receiptId: string;
     parentReceiptId: string | null;
-    mode: "retrieval" | string;
+    mode: "retrieval" | "as_of_replay" | string;
     queryId: string | null;
     taskId: string | null;
     tenantId: string | null;
@@ -119,8 +143,24 @@ export interface Receipt {
     selectedEntries: ReceiptSelectedEntry[];
     policy: ReceiptPolicy;
     output: ReceiptOutput;
+    /** Server region the receipt was emitted from (v0.9+ residency).
+     *  `null` in single-region deployments. */
     region: string | null;
+    /** HMAC-SHA256 hex digest over the canonical body (v0.9+ #157).
+     *  `null` for pre-v0.9 receipts or tenants without signing
+     *  configured — those verify cleanly as
+     *  `{valid: null, reason: "no_signature"}`. */
     receiptSignature: string | null;
+    /** Operator key id used to sign (v0.9+). `null`/`undefined` when unsigned. */
+    receiptSignatureKeyId?: string | null;
+    /** Algorithm + canonical-form version (e.g. "hmac-sha256-canonical-v1")
+     *  (v0.9+). `null`/`undefined` when unsigned. */
+    receiptSignatureAlgorithm?: string | null;
+    /** Embedded policy bundle YAML + hash + capture timestamp (v0.9+ #159).
+     *  See `PolicySnapshot`. `undefined` for pre-v0.9 receipts (the
+     *  replay endpoint refuses those with
+     *  `unreplayable.missing_policy_snapshot`). */
+    policySnapshot?: PolicySnapshot | null;
 }
 export interface ReceiptList {
     receipts: Receipt[];
@@ -134,6 +174,75 @@ export interface ListReceiptsParams {
     cursor?: string;
     limit?: number;
 }
+/**
+ * Result of `GET /v1/receipts/{id}/verify` (v0.9+ #157).
+ *
+ * `valid` is the verdict:
+ * - `true` — HMAC matches the canonical body. `reason === "ok"`.
+ * - `false` — math checked, signature does not cover the body.
+ *   `reason === "signature_mismatch"`.
+ * - `null` — verdict could not be determined. `reason` is one of:
+ *   - `"no_signature"` — receipt is unsigned (pre-v0.9 or tenant
+ *     didn't opt in).
+ *   - `"key_unavailable"` — the `keyId` rotated out of operator
+ *     config; receipt is no longer verifiable on this binary.
+ *   - `"unsupported_algorithm"` — receipt signed under a canonical
+ *     form / algorithm variant this binary doesn't implement.
+ *
+ * Comparison is constant-time on the server side; the signing key
+ * bytes never appear on the response.
+ */
+export interface ReceiptVerifyResult {
+    valid: boolean | null;
+    keyId: string | null;
+    algorithm: string | null;
+    reason: "ok" | "signature_mismatch" | "no_signature" | "key_unavailable" | "unsupported_algorithm" | string;
+}
+/**
+ * Structural diff envelope returned by `POST /v1/receipts/{id}/replay`.
+ * Entries are matched by their `memoryId` / `episodeId` so re-ranking
+ * the same entry is reported under `common`, not as add+remove.
+ */
+export interface ReceiptReplayDiff {
+    contextHash: {
+        original: string | null;
+        replay: string | null;
+        changed: boolean;
+    };
+    selectedEntries: {
+        added: ReceiptSelectedEntry[];
+        removed: ReceiptSelectedEntry[];
+        common: number;
+    };
+    filtersApplied: {
+        added: unknown[];
+        removed: unknown[];
+    };
+}
+/**
+ * Response from `POST /v1/receipts/{id}/replay` (v0.9+ #159).
+ *
+ * Semantic: current code + original policy. Replay re-runs the
+ * original retrieval against the *current* memory state but with
+ * the *original* policy bundle frozen on the receipt's
+ * `policySnapshot`. The original receipt is never modified;
+ * `replayReceiptId` points at a new `mode="as_of_replay"` receipt
+ * linked back to the source via `parentReceiptId`.
+ *
+ * `replayReceiptId` is `null` when the replay-receipt write itself
+ * failed (rare, fail-open path). The `diff` envelope is still
+ * authoritative in that case.
+ */
+export interface ReceiptReplayResult {
+    originalReceiptId: string;
+    replayReceiptId: string | null;
+    diff: ReceiptReplayDiff;
+}
+/** The set of refusal reasons the server returns from
+ *  `POST /v1/receipts/{id}/replay` when a receipt cannot be replayed.
+ *  Used by `StatewaveUnreplayableError.reason` so callers can switch
+ *  on the structured value without parsing error code strings. */
+export type UnreplayableReason = "missing_policy_snapshot" | "nested_replay" | "invalid_snapshot";
 export interface Timeline {
     subjectId: string;
     episodes: Episode[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewavedev/sdk",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Official TypeScript SDK for Statewave — the open-source memory runtime for AI agents.",
   "type": "module",
   "main": "dist/index.js",