@sapiom/tools 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @sapiom/tools
 
+## 0.4.0
+
+### Minor Changes
+
+- e17b2d1: **BREAKING (`@sapiom/tools`):** align the coding-run resume payload with the shape a resumed step actually receives. `CodingResultPayload` now carries `executionEnvironment: { type, id } | null` instead of `sandbox: { name, workspaceRoot }`. Re-attach a resumed run's sandbox with `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (for a `blaxel_sandbox`).
+
+  Adds `codingResultSchema` (runtime validation of the resume payload), `toResumePayload`, `ExecutionEnvironmentRef`, and `EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX`. The stub client now emits the same payload shape a resumed step receives, so a step written against the local loop runs identically once deployed.
+
+  The `coding-pause` template and its guidance are updated to the new shape.
+
+## 0.3.0
+
+### Minor Changes
+
+- 704c9ac: Make the local development loop (`run_local`) production-faithful and trustworthy for the dispatch/pause pattern (`agent.coding.launch` + `pauseUntilSignal`).
+
+  - Stub capability handles now survive JSON serialization, so a paused/resumed coding workflow runs end-to-end locally instead of failing with an opaque `'sandbox.toJSON' is not a method or field` error.
+  - The payload a paused step resumes with is delivered as plain JSON — the same shape production sends over the wire — so authors re-attach handles by name (`sandboxes.attach(...)`) locally exactly as they would in prod.
+  - `@sapiom/tools` exports `CodingResultPayload`: the shape a step resumed from `pauseUntilSignal(codingHandle, …)` receives, so resumed steps can be annotated instead of hand-rolling the type.
+  - Stubbing a handle-returning capability with plain JSON no longer strips the handle's instance methods (e.g. `repo.pushFromSandbox`), and `repositories.list` stubs are coerced and shape-checked.
+  - A dispatched `launch()` accepts the `agent.coding.launch` stub key as well as the shared `agent.coding.run` (ordered candidate resolution), so the stub key matching the call the author wrote takes effect.
+  - `run_local` now reports `unusedStubs` (a supplied key that matched no call) and `stubWarnings` (a key that matched but carried the wrong shape), surfacing stubs that silently didn't take effect; the MCP `run_local` also serializes its result defensively.
+  - New `coding-pause` scaffold template for the launch + pause + resume pattern, and AGENTS docs documenting the resume-input contract, list stub item shape, failure-branch stubbing, and step determinism under replay.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/cjs/agent/index.d.ts

@@ -76,6 +76,61 @@ export interface CodingRunResult {
     /** Live handle to the sandbox the run executed in. */
     sandbox: Sandbox;
 }
+/** Execution-environment `type` for a remote cloud sandbox; its `id` is the sandbox name. */
+export declare const EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX = "blaxel_sandbox";
+/**
+ * The execution environment a coding run used. For a `"blaxel_sandbox"`, `id` is
+ * the sandbox NAME — the value `ctx.sapiom.sandboxes.attach(id)` takes.
+ */
+export interface ExecutionEnvironmentRef {
+    /** Environment kind (today: `"blaxel_sandbox"` | `"local_host"`). */
+    type: string;
+    /** Type-specific id; for `"blaxel_sandbox"`, the sandbox name. */
+    id: string;
+}
+/**
+ * The coding run's terminal result as it arrives at a step **resumed** from
+ * `pauseUntilSignal(runHandle, { resumeStep })` — the signal payload delivered as
+ * that step's `input`. It crossed a wire boundary, so there are no live handles:
+ * to act on the run's sandbox, re-attach one from `executionEnvironment` —
+ * `ctx.sapiom.sandboxes.attach(result.executionEnvironment.id)` (when its `type`
+ * is `"blaxel_sandbox"`). `executionEnvironment` is `null` when the run never
+ * provisioned one (e.g. a launch-stage failure).
+ *
+ * Annotate a resumed step's input with this so you don't have to hand-roll the
+ * shape:
+ *
+ *   const finalize = defineStep({
+ *     name: "finalize", terminal: true,
+ *     async run(result: CodingResultPayload, ctx) { … },
+ *   });
+ */
+export interface CodingResultPayload {
+    runId: string;
+    status: RunStatus;
+    summary: string | null;
+    result: CodingRunOutcome | null;
+    error: CodingRunError | null;
+    executionEnvironment: ExecutionEnvironmentRef | null;
+}
+/**
+ * Map a live, awaited {@link CodingRunResult} to the plain {@link CodingResultPayload}
+ * a resumed step receives across the wire boundary (live handles become an
+ * `executionEnvironment` reference).
+ */
+export declare function toResumePayload(run: CodingRunResult): CodingResultPayload;
+/** Thrown by {@link codingResultSchema}.parse on a malformed resume payload. */
+export declare class CodingResultSchemaError extends Error {
+}
+/**
+ * Runtime validator for {@link CodingResultPayload}. `parse` returns the value typed
+ * on success and throws a {@link CodingResultSchemaError} on any divergence. The
+ * `executionEnvironment` key is required (use `null` when no environment was
+ * provisioned).
+ */
+export declare const codingResultSchema: {
+    parse(value: unknown): CodingResultPayload;
+};
 /**
  * A launched-but-not-awaited run. Satisfies {@link DispatchHandle}, so it can be
  * handed straight to `pauseUntilSignal(handle, { resumeStep })` to suspend a

package/dist/cjs/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAK3D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,wBAAwB,CAAC;AAE1D,oEAAoE;AACpE,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,CAAC;AAGb,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,cAAc;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7B,4DAA4D;IAC5D,IAAI,CAAC,IAAI,CAAC,EAAE;QACV,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC9B;AAyED,wBAAsB,MAAM,CAC1B,IAAI,EAAE,aAAa,EACnB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,SAAS,CAAC,CAmDpB;AAED,wBAAsB,GAAG,CACvB,IAAI,EAAE,aAAa,EACnB,SAAS,GAAE,SAA8B,EACzC,OAAO,SAAmB,GACzB,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED,8CAA8C;AAC9C,eAAO,MAAM,MAAM;;;CAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agent/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/agent/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.coding = exports.CODING_RESULT_SIGNAL = void 0;
+exports.coding = exports.codingResultSchema = exports.CodingResultSchemaError = exports.EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX = exports.CODING_RESULT_SIGNAL = void 0;
+exports.toResumePayload = toResumePayload;
 exports.launch = launch;
 exports.run = run;
 /**
@@ -36,6 +37,97 @@ const DEFAULT_BASE_URL = process.env.SAPIOM_AGENTS_URL || "https://agents.servic
  */
 exports.CODING_RESULT_SIGNAL = "agent.coding.result";
 const TERMINAL = new Set(["completed", "failed"]);
+/** Execution-environment `type` for a remote cloud sandbox; its `id` is the sandbox name. */
+exports.EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX = "blaxel_sandbox";
+/**
+ * Map a live, awaited {@link CodingRunResult} to the plain {@link CodingResultPayload}
+ * a resumed step receives across the wire boundary (live handles become an
+ * `executionEnvironment` reference).
+ */
+function toResumePayload(run) {
+    return {
+        runId: run.runId,
+        status: run.status,
+        summary: run.summary,
+        result: run.result,
+        error: run.error,
+        executionEnvironment: {
+            type: exports.EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX,
+            id: run.sandbox.name,
+        },
+    };
+}
+/** Thrown by {@link codingResultSchema}.parse on a malformed resume payload. */
+class CodingResultSchemaError extends Error {
+}
+exports.CodingResultSchemaError = CodingResultSchemaError;
+const RUN_STATUSES = [
+    "pending",
+    "queued",
+    "running",
+    "completed",
+    "failed",
+];
+/**
+ * Runtime validator for {@link CodingResultPayload}. `parse` returns the value typed
+ * on success and throws a {@link CodingResultSchemaError} on any divergence. The
+ * `executionEnvironment` key is required (use `null` when no environment was
+ * provisioned).
+ */
+exports.codingResultSchema = {
+    parse(value) {
+        const fail = (msg) => {
+            throw new CodingResultSchemaError(`invalid coding result payload: ${msg}`);
+        };
+        if (!value || typeof value !== "object")
+            fail("not an object");
+        const v = value;
+        if (typeof v.runId !== "string")
+            fail("runId must be a string");
+        if (!RUN_STATUSES.includes(v.status))
+            fail(`status must be one of ${RUN_STATUSES.join(", ")}`);
+        if (v.summary !== null && typeof v.summary !== "string")
+            fail("summary must be a string or null");
+        if (v.result !== null) {
+            const r = v.result;
+            if (!r || typeof r !== "object")
+                fail("result must be an object or null");
+            if (typeof r.success !== "boolean")
+                fail("result.success must be a boolean");
+            if (typeof r.turns !== "number")
+                fail("result.turns must be a number");
+            if (r.modelUsed !== null && typeof r.modelUsed !== "string")
+                fail("result.modelUsed must be a string or null");
+            if (typeof r.durationMs !== "number")
+                fail("result.durationMs must be a number");
+            if (typeof r.toolCallCount !== "number")
+                fail("result.toolCallCount must be a number");
+            if (!r.usage || typeof r.usage !== "object")
+                fail("result.usage must be an object");
+        }
+        if (v.error !== null) {
+            const e = v.error;
+            if (!e || typeof e !== "object")
+                fail("error must be an object or null");
+            if (typeof e.stage !== "string")
+                fail("error.stage must be a string");
+            if (typeof e.message !== "string")
+                fail("error.message must be a string");
+        }
+        if (!("executionEnvironment" in v))
+            fail("executionEnvironment is required (use null when no environment was provisioned)");
+        if (v.executionEnvironment !== null) {
+            const env = v.executionEnvironment;
+            if (!env || typeof env !== "object")
+                fail("executionEnvironment must be an object or null");
+            if (typeof env.type !== "string")
+                fail("executionEnvironment.type must be a string");
+            if (typeof env.id !== "string")
+                fail("executionEnvironment.id must be a string");
+        }
+        return value;
+    },
+};
 /**
  * When launched from inside a Sapiom workflow step, the engine injects an opaque
  * per-execution resume token into the sandbox env. Forwarding it as a header — NOT

package/dist/cjs/agent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/index.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.d.ts

@@ -21,6 +21,8 @@ export * as repositories from "./repositories/index.js";
 export { Repository } from "./repositories/index.js";
 export * as agent from "./agent/index.js";
 export { CODING_RESULT_SIGNAL } from "./agent/index.js";
+export type { CodingResultPayload, ExecutionEnvironmentRef, } from "./agent/index.js";
+export { codingResultSchema, CodingResultSchemaError, toResumePayload, EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX, } from "./agent/index.js";
 export * as fileStorage from "./file-storage/index.js";
 export { FileStorageHttpError } from "./file-storage/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIvE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIvE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD,OAAO,KAAK,SAAS,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,KAAK,YAAY,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC;AAE1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAGxD,YAAY,EACV,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,eAAe,EACf,oCAAoC,GACrC,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/cjs/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileStorageHttpError = exports.fileStorage = exports.CODING_RESULT_SIGNAL = exports.agent = exports.Repository = exports.repositories = exports.Sandbox = exports.sandboxes = exports.createClientFromEnv = exports.createClient = void 0;
+exports.FileStorageHttpError = exports.fileStorage = exports.EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX = exports.toResumePayload = exports.CodingResultSchemaError = exports.codingResultSchema = exports.CODING_RESULT_SIGNAL = exports.agent = exports.Repository = exports.repositories = exports.Sandbox = exports.sandboxes = exports.createClientFromEnv = exports.createClient = void 0;
 /**
  * `@sapiom/tools` — the typed Sapiom capability client.
  *
@@ -60,7 +60,14 @@ exports.agent = __importStar(require("./agent/index.js"));
 // Surfaced top-level for the static `pause: { signal }` decl on a workflow step.
 var index_js_3 = require("./agent/index.js");
 Object.defineProperty(exports, "CODING_RESULT_SIGNAL", { enumerable: true, get: function () { return index_js_3.CODING_RESULT_SIGNAL; } });
+// Validate / build a `CodingResultPayload`, and the env `type` whose `id` is a
+// sandbox name for `sandboxes.attach(id)`.
+var index_js_4 = require("./agent/index.js");
+Object.defineProperty(exports, "codingResultSchema", { enumerable: true, get: function () { return index_js_4.codingResultSchema; } });
+Object.defineProperty(exports, "CodingResultSchemaError", { enumerable: true, get: function () { return index_js_4.CodingResultSchemaError; } });
+Object.defineProperty(exports, "toResumePayload", { enumerable: true, get: function () { return index_js_4.toResumePayload; } });
+Object.defineProperty(exports, "EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX", { enumerable: true, get: function () { return index_js_4.EXECUTION_ENVIRONMENT_BLAXEL_SANDBOX; } });
 exports.fileStorage = __importStar(require("./file-storage/index.js"));
-var index_js_4 = require("./file-storage/index.js");
-Object.defineProperty(exports, "FileStorageHttpError", { enumerable: true, get: function () { return index_js_4.FileStorageHttpError; } });
+var index_js_5 = require("./file-storage/index.js");
+Object.defineProperty(exports, "FileStorageHttpError", { enumerable: true, get: function () { return index_js_5.FileStorageHttpError; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;GAYG;AACH,yCAAgE;AAAvD,yGAAA,YAAY,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAQ1C,kEAAkD;AAClD,iDAA+C;AAAtC,mGAAA,OAAO,OAAA;AAEhB,wEAAwD;AACxD,oDAAqD;AAA5C,sGAAA,UAAU,OAAA;AAEnB,0DAA0C;AAC1C,iFAAiF;AACjF,6CAAwD;AAA/C,gHAAA,oBAAoB,OAAA;AAE7B,uEAAuD;AACvD,oDAA+D;AAAtD,gHAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;GAYG;AACH,yCAAgE;AAAvD,yGAAA,YAAY,OAAA;AAAE,gHAAA,mBAAmB,OAAA;AAQ1C,kEAAkD;AAClD,iDAA+C;AAAtC,mGAAA,OAAO,OAAA;AAEhB,wEAAwD;AACxD,oDAAqD;AAA5C,sGAAA,UAAU,OAAA;AAEnB,0DAA0C;AAC1C,iFAAiF;AACjF,6CAAwD;AAA/C,gHAAA,oBAAoB,OAAA;AAO7B,+EAA+E;AAC/E,2CAA2C;AAC3C,6CAK0B;AAJxB,8GAAA,kBAAkB,OAAA;AAClB,mHAAA,uBAAuB,OAAA;AACvB,2GAAA,eAAe,OAAA;AACf,gIAAA,oCAAoC,OAAA;AAGtC,uEAAuD;AACvD,oDAA+D;AAAtD,gHAAA,oBAAoB,OAAA"}

package/dist/cjs/stub/index.d.ts

@@ -1,4 +1,4 @@
-import type { Sapiom } from '../client.js';
+import type { Sapiom } from "../client.js";
 /** Per-capability overrides, keyed by capability path (see module docs). */
 export type StubOverrides = Record<string, unknown | ((...args: unknown[]) => unknown)>;
 export interface StubClientOptions {
@@ -10,6 +10,21 @@ export interface StubClientOptions {
      * signal would have carried.
      */
     signals?: Map<string, unknown>;
+    /**
+     * When provided, every override key that is actually matched by a capability
+     * call is added here. A local runner diffs this against the keys the author
+     * supplied to warn about stub keys that matched nothing (a typo'd path, or the
+     * wrong plural/singular form) — which otherwise fail silently.
+     */
+    usedKeys?: Set<string>;
+    /**
+     * When provided, collects human-readable warnings about stub *values* that are
+     * present but malformed for the capability they override (e.g. a
+     * `repositories.list` stub that isn't an array of repositories). Catches the
+     * silent-wrong-data trap that `usedKeys` can't — a key that matched but carried
+     * the wrong shape.
+     */
+    warnings?: Set<string>;
 }
 /**
  * Create a stub `Sapiom` client. Runs every capability against built-in defaults;

package/dist/cjs/stub/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stub/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAK3C,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC;AAExF,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAkID;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAuFrE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/stub/index.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAU3C,4EAA4E;AAC5E,MAAM,MAAM,aAAa,GAAG,MAAM,CAChC,MAAM,EACN,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAC5C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AA0TD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAmJrE"}