@statewavedev/sdk 0.9.0 → 0.10.1

package/README.md

@@ -12,6 +12,12 @@ Official TypeScript SDK for [Statewave](https://github.com/smaramwbc/statewave)
 
 > ⚠️ **v0.9.0 is a breaking change.** The entire SDK surface — request params *and* response fields — is now idiomatic **camelCase** (`subjectId`, `maxTokens`, `createdAt`, `receiptId`, …). The wire protocol is unchanged; the client maps to/from the server's snake_case transparently. `payload`, `metadata`, and `provenance` are passed through verbatim — their inner keys are never rewritten. See [CHANGELOG](CHANGELOG.md#090) for the full rename table and migration steps.
 
+> **New to Statewave?** This SDK is a thin client for a running **Statewave
+> server**. If you don't have one yet, the
+> [Getting Started guide](https://github.com/smaramwbc/statewave-docs/blob/main/getting-started.md)
+> brings one up with Docker Compose in about 5 minutes. Every example below
+> assumes a server reachable at `http://localhost:8100`.
+
 ## Install
 
 ```bash
@@ -91,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";
@@ -134,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({
@@ -145,6 +184,59 @@ console.log(updated.sensitivityLabels); // → ["financial", "pii"]
 
 Receipts and the policy engine cooperate: every assembly call records its policy decisions into `receipt.policy.filtersApplied` (one entry per memory the policy fired on) and `receipt.policy.filtersSkipped` (per-rule summary of what didn't fire). In `log_only` mode (the tenant default) the receipt is the full audit trail without filtering; under `enforce` denied memories are dropped before they reach the assembly and the deny is still recorded. See [`receipts.md`](https://github.com/smaramwbc/statewave-docs/blob/main/receipts.md) and [`sensitivity-labels.md`](https://github.com/smaramwbc/statewave-docs/blob/main/sensitivity-labels.md) for the full schemas and policy YAML format.
 
+## Support-agent endpoints
+
+Statewave's support wedge — customer health scoring, SLA tracking, resolution state, and structured escalation briefs — is exposed through ergonomic SDK methods (server v0.6+).
+
+```typescript
+import { StatewaveClient } from "@statewavedev/sdk";
+
+const sw = new StatewaveClient("http://localhost:8100");
+
+// Customer health score (0–100) with the explainable factors behind it.
+const health = await sw.getHealth("customer:globex");
+console.log(`${health.score}/100 — ${health.state}`);
+for (const f of health.factors) {
+  console.log(`  ${f.signal}: ${f.impact >= 0 ? "+" : ""}${f.impact} (${f.detail})`);
+}
+
+// SLA metrics — first-response / resolution times and breach counts.
+// Thresholds are optional; they default server-side to 5 min / 24 h.
+const sla = await sw.getSLA({
+  subjectId: "customer:globex",
+  firstResponseThresholdMinutes: 10,
+  resolutionThresholdHours: 48,
+});
+console.log(`${sla.resolvedSessions}/${sla.totalSessions} resolved, ${sla.resolutionBreachCount} SLA breaches`);
+
+// Track resolution state for a session (upserts by subject + session).
+await sw.createResolution({
+  subjectId: "customer:globex",
+  sessionId: "ticket-8842",
+  status: "resolved",
+  resolutionSummary: "Issued refund for the duplicate charge",
+});
+
+// List resolutions, optionally filtered by status.
+const openItems = await sw.listResolutions({
+  subjectId: "customer:globex",
+  status: "open",
+});
+
+// Generate a handoff context pack for escalation or shift change.
+// `handoffNotes` is a pre-rendered markdown brief for human or LLM use.
+const handoff = await sw.createHandoff({
+  subjectId: "customer:globex",
+  sessionId: "ticket-8842",
+  reason: "escalation",
+  callerId: "agent-7",
+  callerType: "support_agent",
+});
+console.log(handoff.handoffNotes);
+```
+
+`getHealth`, `getSLA`, `createResolution`, `listResolutions`, and `createHandoff` respect the same auth, tenant-scoping, and retry behaviour as the rest of the client. `createHandoff` shares `getContext`'s caller-identity gate — when the tenant config sets `require_caller_identity: true`, both `callerId` and `callerType` are mandatory.
+
 ## Error handling
 
 ```typescript
@@ -187,10 +279,18 @@ 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
+- `Handoff` + `ResolutionSummaryItem` — handoff context pack and its prior-resolution items
+- `Resolution` — resolution tracking record
+- `HealthState` / `ResolutionStatus` — string-literal status unions
 
-Param types: `CreateEpisodeParams`, `SearchMemoriesParams`, `GetContextParams`, `ListReceiptsParams`, `SetMemoryLabelsParams`
+Param types: `CreateEpisodeParams`, `SearchMemoriesParams`, `GetContextParams`, `ListReceiptsParams`, `SetMemoryLabelsParams`, `GetSLAParams`, `CreateHandoffParams`, `CreateResolutionParams`, `ListResolutionsParams`
 
 ## Running tests
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BatchCreateResult, ClientOptions, CompileJob, CompileResult, ContextBundle, CreateEpisodeParams, DeleteResult, Episode, GetContextParams, ListReceiptsParams, ListSubjectsResult, Memory, Receipt, ReceiptList, 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,81 @@ 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.
+     */
+    getHealth(subjectId: string): Promise<Health>;
+    /**
+     * Compute SLA metrics for a subject — first-response and resolution
+     * times plus breach flags, aggregated across the subject's sessions.
+     * Both thresholds fall back to the server defaults (5 minutes /
+     * 24 hours) when omitted.
+     */
+    getSLA(params: GetSLAParams): Promise<SLASummary>;
+    /**
+     * Generate a handoff context pack — a structured escalation brief for
+     * shift change or agent transfer. Same caller-identity gate as
+     * `getContext`: when the tenant sets `require_caller_identity: true`,
+     * both `callerId` and `callerType` are mandatory.
+     */
+    createHandoff(params: CreateHandoffParams): Promise<Handoff>;
+    /**
+     * Create or update a resolution record for a support session.
+     * Upserts by `subjectId` + `sessionId`.
+     */
+    createResolution(params: CreateResolutionParams): Promise<Resolution>;
+    /**
+     * List resolution records for a subject, optionally filtered to a
+     * single status.
+     */
+    listResolutions(params: ListResolutionsParams): Promise<Resolution[]>;
     getTimeline(subjectId: string): Promise<Timeline>;
     deleteSubject(subjectId: string): Promise<DeleteResult>;
     listSubjects(params?: {

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,128 @@ 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
+     * explainable factors that drove it. Backs proactive risk triage.
+     */
+    async getHealth(subjectId) {
+        return this.get(`/v1/subjects/${encodeURIComponent(subjectId)}/health`);
+    }
+    /**
+     * Compute SLA metrics for a subject — first-response and resolution
+     * times plus breach flags, aggregated across the subject's sessions.
+     * Both thresholds fall back to the server defaults (5 minutes /
+     * 24 hours) when omitted.
+     */
+    async getSLA(params) {
+        const qs = new URLSearchParams();
+        if (params.firstResponseThresholdMinutes !== undefined) {
+            qs.set("first_response_threshold_minutes", String(params.firstResponseThresholdMinutes));
+        }
+        if (params.resolutionThresholdHours !== undefined) {
+            qs.set("resolution_threshold_hours", String(params.resolutionThresholdHours));
+        }
+        const query = qs.toString();
+        return this.get(`/v1/subjects/${encodeURIComponent(params.subjectId)}/sla${query ? `?${query}` : ""}`);
+    }
+    /**
+     * Generate a handoff context pack — a structured escalation brief for
+     * shift change or agent transfer. Same caller-identity gate as
+     * `getContext`: when the tenant sets `require_caller_identity: true`,
+     * both `callerId` and `callerType` are mandatory.
+     */
+    async createHandoff(params) {
+        return this.post("/v1/handoff", {
+            subjectId: params.subjectId,
+            sessionId: params.sessionId,
+            ...(params.reason !== undefined && { reason: params.reason }),
+            ...(params.maxTokens !== undefined && { maxTokens: params.maxTokens }),
+            ...(params.emitReceipt !== undefined && { emitReceipt: params.emitReceipt }),
+            ...(params.queryId !== undefined && { queryId: params.queryId }),
+            ...(params.taskId !== undefined && { taskId: params.taskId }),
+            ...(params.parentReceiptId !== undefined && {
+                parentReceiptId: params.parentReceiptId,
+            }),
+            ...(params.callerId !== undefined && { callerId: params.callerId }),
+            ...(params.callerType !== undefined && { callerType: params.callerType }),
+        });
+    }
+    /**
+     * Create or update a resolution record for a support session.
+     * Upserts by `subjectId` + `sessionId`.
+     */
+    async createResolution(params) {
+        return this.post("/v1/resolutions", {
+            subjectId: params.subjectId,
+            sessionId: params.sessionId,
+            ...(params.status !== undefined && { status: params.status }),
+            ...(params.resolutionSummary !== undefined && {
+                resolutionSummary: params.resolutionSummary,
+            }),
+            ...(params.metadata !== undefined && { metadata: params.metadata }),
+        });
+    }
+    /**
+     * List resolution records for a subject, optionally filtered to a
+     * single status.
+     */
+    async listResolutions(params) {
+        const qs = new URLSearchParams({ subject_id: params.subjectId });
+        if (params.status !== undefined)
+            qs.set("status", params.status);
+        return this.get(`/v1/resolutions?${qs}`);
+    }
     async getTimeline(subjectId) {
         return this.get(`/v1/timeline?subject_id=${encodeURIComponent(subjectId)}`);
     }
@@ -281,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[];
@@ -166,6 +275,95 @@ export interface CompileJob {
     memories?: Memory[];
     error?: string;
 }
+/** Support health-state bucket. */
+export type HealthState = "healthy" | "watch" | "at_risk";
+/** Resolution lifecycle status. */
+export type ResolutionStatus = "open" | "resolved" | "unresolved";
+/** One explainable factor behind a customer health score. */
+export interface HealthFactor {
+    /** Stable signal identifier, e.g. `sla_resolution_breaches`. */
+    signal: string;
+    /** Signed score contribution — a negative impact drags the score down. */
+    impact: number;
+    /** Human-readable explanation of the factor. */
+    detail: string;
+}
+/** Customer health score (0–100) with the factors that drove it. */
+export interface Health {
+    subjectId: string;
+    score: number;
+    state: HealthState;
+    factors: HealthFactor[];
+}
+/** SLA metrics for a single support session. */
+export interface SessionSLA {
+    sessionId: string;
+    /** `resolved` | `open`. */
+    status: string;
+    firstMessageAt: string | null;
+    firstResponseAt: string | null;
+    resolvedAt: string | null;
+    firstResponseSeconds: number | null;
+    resolutionSeconds: number | null;
+    openDurationSeconds: number | null;
+    firstResponseBreached: boolean;
+    resolutionBreached: boolean;
+}
+/** Aggregate SLA metrics for a subject across all of its sessions. */
+export interface SLASummary {
+    subjectId: string;
+    totalSessions: number;
+    resolvedSessions: number;
+    openSessions: number;
+    avgFirstResponseSeconds: number | null;
+    avgResolutionSeconds: number | null;
+    firstResponseBreachCount: number;
+    resolutionBreachCount: number;
+    sessions: SessionSLA[];
+}
+/** A prior resolution surfaced inside a handoff brief. */
+export interface ResolutionSummaryItem {
+    sessionId: string;
+    status: string;
+    summary: string | null;
+    resolvedAt: string | null;
+}
+/** Structured escalation brief — the handoff context pack. */
+export interface Handoff {
+    subjectId: string;
+    sessionId: string;
+    reason: string;
+    generatedAt: string;
+    customerSummary: string;
+    activeIssue: string;
+    attemptedSteps: string[];
+    keyFacts: string[];
+    resolutionHistory: ResolutionSummaryItem[];
+    recentContext: string[];
+    healthScore: number | null;
+    healthState: HealthState | null;
+    healthFactors: HealthFactor[];
+    /** Pre-rendered markdown brief, ready for human or LLM consumption. */
+    handoffNotes: string;
+    tokenEstimate: number;
+    provenance: Record<string, unknown>;
+    /** ULID of the state-assembly receipt, when one was emitted. */
+    receiptId?: string | null;
+    /** True iff a receipt was successfully written for this call. */
+    receiptEmitted?: boolean;
+}
+/** Resolution tracking record for a support session. */
+export interface Resolution {
+    id: string;
+    subjectId: string;
+    sessionId: string;
+    status: ResolutionStatus;
+    resolutionSummary: string | null;
+    resolvedAt: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
 export interface CreateEpisodeParams {
     subjectId: string;
     source: string;
@@ -213,6 +411,53 @@ export interface SetMemoryLabelsParams {
      */
     sensitivityLabels: string[];
 }
+export interface GetSLAParams {
+    subjectId: string;
+    /** First-response SLA threshold in minutes (server default: 5). */
+    firstResponseThresholdMinutes?: number;
+    /** Resolution SLA threshold in hours (server default: 24). */
+    resolutionThresholdHours?: number;
+}
+export interface CreateHandoffParams {
+    subjectId: string;
+    /** Session being handed off. */
+    sessionId: string;
+    /** Why the handoff is happening (server default: "escalation"). */
+    reason?: string;
+    /** Token budget for the assembled brief. */
+    maxTokens?: number;
+    /**
+     * Opt in to emitting a state-assembly receipt for this call. The
+     * tenant config can also force emission on or off independently of
+     * this flag.
+     */
+    emitReceipt?: boolean;
+    queryId?: string;
+    taskId?: string;
+    parentReceiptId?: string;
+    /**
+     * Caller identity consumed by the sensitivity-label policy layer
+     * (#50). When the tenant config sets `require_caller_identity: true`,
+     * both `callerId` and `callerType` are mandatory.
+     */
+    callerId?: string;
+    callerType?: string;
+}
+export interface CreateResolutionParams {
+    subjectId: string;
+    sessionId: string;
+    /** Lifecycle status (server default: "open"). */
+    status?: ResolutionStatus;
+    /** Short human summary of how the session was resolved. */
+    resolutionSummary?: string;
+    /** Free-form caller-owned bag; inner keys round-trip verbatim. */
+    metadata?: Record<string, unknown>;
+}
+export interface ListResolutionsParams {
+    subjectId: string;
+    /** Filter to a single status. Omit to list every resolution. */
+    status?: ResolutionStatus;
+}
 export interface ClientOptions {
     baseUrl?: string;
     apiKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statewavedev/sdk",
-  "version": "0.9.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",