@namzu/sdk 20.4.0 → 21.1.0

package/dist/runtime/query/resume-run.d.ts

@@ -1,6 +1,8 @@
 import type { PendingDecision } from '../../types/hitl/index.js';
 import type { CheckpointStore, ClaimFence } from '../../types/run/checkpoint-store.js';
 import type { Run } from '../../types/run/entity.js';
+import type { RunEventReplay } from '../../types/run/event-cursor.js';
+import type { RunEventListener } from '../../types/run/events.js';
 import type { RunState } from '../../types/run/state.js';
 import { type QueryParams } from './index.js';
 import { type RunStateScope } from './run-state.js';
@@ -26,6 +28,16 @@ export type ResumeOutcome = {
     readonly resumed: true;
     readonly run: Run;
     readonly state: RunState;
+    /**
+     * What became of {@link ResumeRunParams.eventCursor}. Absent when no
+     * cursor was supplied.
+     *
+     * Reported rather than thrown: a stale cursor is the client's
+     * problem and the run still had to be resumed. A caller that sees
+     * `unavailable` re-derives its view from the run's transcript
+     * instead of folding a hole into it.
+     */
+    readonly replay?: RunEventReplay;
 };
 /**
  * The half of a run that cannot be serialized, plus where to look.
@@ -52,6 +64,19 @@ export interface ResumeRunParams extends Omit<QueryParams, 'messages' | 'runId'
      * Absent means the parked checkpoint if there is one, else the newest.
      */
     readonly checkpointId?: RunState['checkpointId'];
+    /**
+     * Where to send the resumed run's events.
+     *
+     * This call had none, and the consequence was total: it drains the run to
+     * completion and every event the run emits — every tool call, every park,
+     * every token update — was discarded, because `drainQuery` forwards to a
+     * listener and none was ever passed. So the one API for continuing a run
+     * another process started could not show anybody what the run was doing.
+     *
+     * It is also what makes {@link ResumeRunParams.eventCursor} mean anything:
+     * a catch-up delivered into a stream nobody receives is not a catch-up.
+     */
+    readonly listener?: RunEventListener;
 }
 /**
  * Continue a run that a different process started.

package/dist/runtime/query/resume-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resume-run.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/resume-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,YAAY,CAAA;AACzD,OAAO,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAA;AAEjE;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC7D;IACA,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CACvB,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAA;AAE1E;;;;;;GAMG;AACH,MAAM,WAAW,eAChB,SAAQ,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,GAAG,sBAAsB,CAAC;IACxE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;CAChD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAyB/E"}
+{"version":3,"file":"resume-run.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/resume-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,2BAA2B,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,YAAY,CAAA;AACzD,OAAO,EAAE,KAAK,aAAa,EAAgB,MAAM,gBAAgB,CAAA;AAEjE;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACtB;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC7D;IACA,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAA;IACpC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;CACvB,GACD;IACA,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IACjB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAA;CAC/B,CAAA;AAEJ;;;;;;GAMG;AACH,MAAM,WAAW,eAChB,SAAQ,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,OAAO,GAAG,sBAAsB,CAAC;IACxE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAA;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAA;IAEhD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAkD/E"}

package/dist/runtime/query/resume-run.js

@@ -22,7 +22,7 @@ import { loadRunState } from './run-state.js';
  * resumed past without the answer it is waiting for.
  */
 export async function resumeRun(params) {
-    const { scope, checkpointStore, checkpointId, pendingDecision, claimFence, ...rest } = params;
+    const { scope, checkpointStore, checkpointId, pendingDecision, claimFence, listener, onEventReplay, ...rest } = params;
     const state = await loadRunState(checkpointStore, scope, checkpointId);
     if (!state?.checkpointId)
         return { resumed: false, reason: 'no-checkpoint' };
@@ -33,15 +33,27 @@ export async function resumeRun(params) {
     if (outstanding && !pendingDecision) {
         return { resumed: false, reason: 'awaiting-decision', pending: outstanding, state };
     }
+    let replay;
     const run = await drainQuery({
         ...rest,
         messages: [],
         runId: state.runId,
+        // Forwarded, and it is not cosmetic: the run store nests a sub-run's
+        // evidence under `<parent>/children/<run>`, so resuming a sub-run
+        // without this binds `<base>/<run>` instead — a second, empty
+        // transcript under a run id that already has one, a sequence that
+        // restarts at 1, and a catch-up that reports a live run as having
+        // produced nothing.
+        ...(state.parentRunId !== undefined ? { parentRunId: state.parentRunId } : {}),
         resumeFromCheckpoint: state.checkpointId,
         checkpointStore,
         ...(claimFence !== undefined ? { claimFence } : {}),
         ...(pendingDecision ? { pendingDecision } : {}),
-    });
-    return { resumed: true, run, state };
+        onEventReplay: (verdict) => {
+            replay = verdict;
+            onEventReplay?.(verdict);
+        },
+    }, listener);
+    return { resumed: true, run, state, ...(replay !== undefined ? { replay } : {}) };
 }
 //# sourceMappingURL=resume-run.js.map

package/dist/runtime/query/resume-run.js.map

@@ -1 +1 @@
-{"version":3,"file":"resume-run.js","sourceRoot":"","sources":["../../../src/runtime/query/resume-run.ts"],"names":[],"mappings":"AAIA,OAAO,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAA;AACzD,OAAO,EAAsB,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAmDjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAuB;IACtD,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAA;IAE7F,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,eAAe,EAAE,KAAK,EAAE,YAAY,CAAC,CAAA;IACtE,IAAI,CAAC,KAAK,EAAE,YAAY;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAA;IAE5E,yEAAyE;IACzE,0EAA0E;IAC1E,sDAAsD;IACtD,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1F,IAAI,WAAW,IAAI,CAAC,eAAe,EAAE,CAAC;QACrC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;IACpF,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC;QAC5B,GAAG,IAAI;QACP,QAAQ,EAAE,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,oBAAoB,EAAE,KAAK,CAAC,YAAY;QACxC,eAAe;QACf,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChC,CAAC,CAAA;IAEjB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAA;AACrC,CAAC"}
+{"version":3,"file":"resume-run.js","sourceRoot":"","sources":["../../../src/runtime/query/resume-run.ts"],"names":[],"mappings":"AAMA,OAAO,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAA;AACzD,OAAO,EAAsB,YAAY,EAAE,MAAM,gBAAgB,CAAA;AA+EjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAuB;IACtD,MAAM,EACL,KAAK,EACL,eAAe,EACf,YAAY,EACZ,eAAe,EACf,UAAU,EACV,QAAQ,EACR,aAAa,EACb,GAAG,IAAI,EACP,GAAG,MAAM,CAAA;IAEV,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,eAAe,EAAE,KAAK,EAAE,YAAY,CAAC,CAAA;IACtE,IAAI,CAAC,KAAK,EAAE,YAAY;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,CAAA;IAE5E,yEAAyE;IACzE,0EAA0E;IAC1E,sDAAsD;IACtD,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1F,IAAI,WAAW,IAAI,CAAC,eAAe,EAAE,CAAC;QACrC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,CAAA;IACpF,CAAC;IAED,IAAI,MAAkC,CAAA;IAEtC,MAAM,GAAG,GAAG,MAAM,UAAU,CAC3B;QACC,GAAG,IAAI;QACP,QAAQ,EAAE,EAAE;QACZ,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,qEAAqE;QACrE,kEAAkE;QAClE,8DAA8D;QAC9D,kEAAkE;QAClE,kEAAkE;QAClE,oBAAoB;QACpB,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,oBAAoB,EAAE,KAAK,CAAC,YAAY;QACxC,eAAe;QACf,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,aAAa,EAAE,CAAC,OAAuB,EAAE,EAAE;YAC1C,MAAM,GAAG,OAAO,CAAA;YAChB,aAAa,EAAE,CAAC,OAAO,CAAC,CAAA;QACzB,CAAC;KACc,EAChB,QAAQ,CACR,CAAA;IAED,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AAClF,CAAC"}

package/dist/store/index.d.ts

@@ -1,6 +1,6 @@
 export { InMemoryStore } from './InMemoryStore.js';
 export type { Identifiable, Timestamped } from './InMemoryStore.js';
-export { RunDiskStore } from './run/disk.js';
+export { RunDiskStore, readRunEventsIn } from './run/disk.js';
 export { InMemoryRunStore } from './run/memory.js';
 export { DiskCheckpointStore } from './run/checkpoint-disk.js';
 export type { DiskCheckpointStoreAttribution } from './run/checkpoint-disk.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAWpE,OAAO,EACN,4BAA4B,EAC5B,QAAQ,EACR,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEnE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAC9D,YAAY,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AAWpE,OAAO,EACN,4BAA4B,EAC5B,QAAQ,EACR,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/store/index.js

@@ -1,5 +1,5 @@
 export { InMemoryStore } from './InMemoryStore.js';
-export { RunDiskStore } from './run/disk.js';
+export { RunDiskStore, readRunEventsIn } from './run/disk.js';
 export { InMemoryRunStore } from './run/memory.js';
 export { DiskCheckpointStore } from './run/checkpoint-disk.js';
 export { InMemoryCheckpointStore } from './run/checkpoint-memory.js';

package/dist/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AACpE,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,kEAAkE;AAClE,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,qEAAqE;AACrE,OAAO,EACN,4BAA4B,EAC5B,QAAQ,EACR,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAG9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGlD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AAE9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAA;AACpE,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,kEAAkE;AAClE,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,qEAAqE;AACrE,OAAO,EACN,4BAA4B,EAC5B,QAAQ,EACR,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,iBAAiB,GACjB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAG9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/store/run/conformance.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The checkpoint-store contract, as a suite a host can run against its own
+ * backend.
+ *
+ * ## Why this ships rather than staying a test
+ *
+ * {@link import('./checkpoint-memory.js').InMemoryCheckpointStore} says in its
+ * own doc comment that it is "the reference a host reads when writing a
+ * backend of its own". That claim was unbacked, and the cost of it was not
+ * hypothetical: the two shipped stores disagreed at the enforcement point —
+ * the in-memory one accepted a write from a holder that had been superseded
+ * and then released around, the disk one refused it — and the class documented
+ * as the reference was the one carrying the defect. Reading a reference cannot
+ * tell you that. Running it can.
+ *
+ * The rules below are the ones a claim depends on and no type can state:
+ * exclusivity, expiry, that a superseded write is refused, and that a listing
+ * answers for the tenant it was asked about and no other. Those are exactly
+ * the points at which the two built-in implementations already diverged.
+ *
+ * ## Why it takes its runner as an argument
+ *
+ * `describe`, `it` and `expect` come in through
+ * {@link CheckpointStoreConformanceOptions}. The suite therefore imports no
+ * test framework, `@namzu/sdk` gains no test dependency from publishing it,
+ * and a host on a different runner can still run it by handing over three
+ * functions of the shapes below.
+ *
+ * It also buys the one property that separates this file from decoration: a
+ * caller can pass a *recording* `describe`/`it` and run the whole contract as
+ * ordinary code, which is how `conformance-fails-a-wrong-store.test.ts`
+ * establishes that a deliberately broken store fails it.
+ *
+ * ## Consuming it
+ *
+ * See `docs/sdk/runtime/checkpoint-store-conformance.md`. In short:
+ *
+ * ```typescript
+ * import { describe, expect, it } from 'your-runner'
+ * import { defineCheckpointStoreConformance } from '@namzu/sdk/testing'
+ *
+ * defineCheckpointStoreConformance({
+ *   describe, it, expect,
+ *   label: 'my-backend',
+ *   contractVersion: 1,
+ *   capabilities: { claims: true, listing: true, multiTenant: true },
+ *   makeStore: (binding) => ({ store: new MyStore(binding) }),
+ * })
+ * ```
+ *
+ * ## The assertions are public API
+ *
+ * Once a host wires this in, every assertion below is something their build
+ * fails on. Adding one is therefore a breaking change for them even though it
+ * adds no export — so a new rule arrives behind a raised
+ * {@link CHECKPOINT_STORE_CONTRACT_VERSION} and a `major`, and the version
+ * check is what turns "your backend silently satisfies an older, smaller
+ * contract" into a named failure.
+ */
+import type { ProjectId, SessionId, TenantId } from '../../types/ids/index.js';
+import type { CheckpointStore } from '../../types/run/checkpoint-store.js';
+/**
+ * Which revision of the contract the assertions in this file express.
+ *
+ * A host DECLARES the version it wrote its backend against, as a literal in
+ * its own test file, and the suite's first case compares the two. Re-exporting
+ * this constant into that slot defeats the check — the point is that the
+ * number is frozen in the host's source at the moment they wrote the backend,
+ * so upgrading `@namzu/sdk` past a contract revision fails with a sentence
+ * naming both numbers instead of a scatter of assertion failures whose common
+ * cause is not obvious.
+ *
+ * Raised only together with a `major`, and only when an assertion is ADDED or
+ * TIGHTENED. Adding a case behind a new optional capability flag does not
+ * raise it: a host that does not declare the capability never runs the case.
+ */
+export declare const CHECKPOINT_STORE_CONTRACT_VERSION = 1;
+/**
+ * What a backend can do, so the suite runs the cases it is answerable for and
+ * no others.
+ *
+ * Every field is required rather than defaulted. A capability that defaults to
+ * `false` lets a host skip a whole section by forgetting a key, and a suite you
+ * can opt out of by omission is a suite that reports a pass it did not
+ * establish.
+ */
+export interface CheckpointStoreCapabilities {
+    /**
+     * The store implements `claimRun` / `releaseRun` and enforces the fence at
+     * `writeCheckpoint`. `false` skips every claim case — appropriate only for
+     * a single-writer backend, which is a deployment shape, not a shortcut.
+     */
+    readonly claims: boolean;
+    /** The store implements `listDurableRuns`. */
+    readonly listing: boolean;
+    /**
+     * One instance can hold more than one tenant's runs.
+     *
+     * `false` for a store whose addressing fixes the tenant — the built-in disk
+     * layout has no tenant segment in it, so a second tenant is a second store.
+     * Such a backend still answers the isolation case that CAN be put to it: a
+     * listing for a tenant it does not hold returns nothing.
+     */
+    readonly multiTenant: boolean;
+}
+/** The attribution the suite addresses its runs under. */
+export interface CheckpointStoreBinding {
+    readonly tenantId: TenantId;
+    readonly projectId: ProjectId;
+    readonly sessionId: SessionId;
+}
+/** A store to test, plus whatever teardown producing it required. */
+export interface CheckpointStoreHandle {
+    readonly store: CheckpointStore;
+    /** Called after each case, pass or fail. */
+    dispose?(): void | Promise<void>;
+}
+/**
+ * Build a store bound to `binding`. Called once per case, so no case can be
+ * affected by another's writes — the suite never assumes a shared instance and
+ * never cleans one.
+ */
+export type MakeCheckpointStore = (binding: CheckpointStoreBinding) => CheckpointStoreHandle | Promise<CheckpointStoreHandle>;
+/** The assertions the suite uses, and nothing more. */
+export interface ConformanceAssertion {
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toBeGreaterThan(expected: number): void;
+    toMatch(expected: RegExp): void;
+}
+/** Shape of the `expect` a runner supplies. */
+export type ConformanceExpect = (actual: unknown) => ConformanceAssertion;
+/** Shape of the `it` a runner supplies. */
+export type ConformanceIt = (name: string, body: () => Promise<void>) => unknown;
+/** Shape of the `describe` a runner supplies. */
+export type ConformanceDescribe = (name: string, body: () => void) => unknown;
+/** Everything {@link defineCheckpointStoreConformance} needs. */
+export interface CheckpointStoreConformanceOptions {
+    readonly describe: ConformanceDescribe;
+    readonly it: ConformanceIt;
+    readonly expect: ConformanceExpect;
+    /**
+     * The contract revision this backend was written against, written as a
+     * literal. See {@link CHECKPOINT_STORE_CONTRACT_VERSION}.
+     */
+    readonly contractVersion: number;
+    readonly capabilities: CheckpointStoreCapabilities;
+    readonly makeStore: MakeCheckpointStore;
+    /** Names the backend in test output. Defaults to `checkpoint store`. */
+    readonly label?: string;
+}
+/**
+ * Register the checkpoint-store contract against one backend.
+ *
+ * Call it once per backend. It registers cases through the supplied `describe`
+ * and `it`; it does not run them.
+ */
+export declare function defineCheckpointStoreConformance(options: CheckpointStoreConformanceOptions): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/store/run/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../../src/store/run/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAIH,OAAO,KAAK,EAAgB,SAAS,EAAS,SAAS,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAG1E;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAA;AAElD;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC7B;AAED,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;IAC/B,4CAA4C;IAC5C,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CACjC,OAAO,EAAE,sBAAsB,KAC3B,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAE3D,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACpC,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,+CAA+C;AAC/C,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,oBAAoB,CAAA;AACzE,2CAA2C;AAC3C,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAA;AAChF,iDAAiD;AACjD,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,CAAA;AAE7E,iEAAiE;AACjE,MAAM,WAAW,iCAAiC;IACjD,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC;;;OAGG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,YAAY,EAAE,2BAA2B,CAAA;IAClD,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAA;IACvC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACvB;AAuED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,iCAAiC,GAAG,IAAI,CA+cjG"}