@loomwork/plugin-durable-state 0.0.0-stage → 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DS-4 — compare-and-set failed: the stored revision was not the expected one.
+ * A genuinely concurrent writer got there first (or the key was created/cleared
+ * underneath the caller). The schedule-driven pattern makes this a
+ * misconfiguration signal, not a normal outcome — fail fast, never lost-update.
+ */
+export declare class RevisionConflictError extends Error {
+    readonly key: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+    constructor(key: string, expectedRevision: number, actualRevision: number);
+}
+export type StateContractMismatchReason = "no-migration-path" | "migration-failed" | "future-version" | "validation-failed";
+/**
+ * DS-2/DS-3 — stored state cannot be brought to the current contract: a
+ * migration step is missing or threw, the stored version is newer than the
+ * contract (rollback deploy), or the (migrated) payload fails schema
+ * validation. Loud and typed by design: a run never proceeds on unvalidated
+ * state, and state is never silently coerced. Alert on it, register the
+ * missing migration (or fix the deploy), and the next run resumes cleanly.
+ */
+export declare class StateContractMismatchError extends Error {
+    readonly contractId: string;
+    readonly reason: StateContractMismatchReason;
+    readonly storedVersion: number;
+    readonly expectedVersion: number;
+    constructor(contractId: string, reason: StateContractMismatchReason, storedVersion: number, expectedVersion: number, detail?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAE5C,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,gBAAgB,EAAE,MAAM;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM;gBAFtB,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM;CAQlC;AAED,MAAM,MAAM,2BAA2B,GACnC,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,CAAC;AAExB;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,MAAM,EAAE,2BAA2B;IAC5C,QAAQ,CAAC,aAAa,EAAE,MAAM;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM;gBAHvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,2BAA2B,EACnC,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EAChC,MAAM,CAAC,EAAE,MAAM;CAQlB"}

package/dist/errors.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateContractMismatchError = exports.RevisionConflictError = void 0;
+/**
+ * DS-4 — compare-and-set failed: the stored revision was not the expected one.
+ * A genuinely concurrent writer got there first (or the key was created/cleared
+ * underneath the caller). The schedule-driven pattern makes this a
+ * misconfiguration signal, not a normal outcome — fail fast, never lost-update.
+ */
+class RevisionConflictError extends Error {
+    key;
+    expectedRevision;
+    actualRevision;
+    constructor(key, expectedRevision, actualRevision) {
+        super(`durable-state CAS conflict on "${key}": expected revision ${expectedRevision}, found ${actualRevision}`);
+        this.key = key;
+        this.expectedRevision = expectedRevision;
+        this.actualRevision = actualRevision;
+        this.name = "RevisionConflictError";
+        Object.setPrototypeOf(this, RevisionConflictError.prototype);
+    }
+}
+exports.RevisionConflictError = RevisionConflictError;
+/**
+ * DS-2/DS-3 — stored state cannot be brought to the current contract: a
+ * migration step is missing or threw, the stored version is newer than the
+ * contract (rollback deploy), or the (migrated) payload fails schema
+ * validation. Loud and typed by design: a run never proceeds on unvalidated
+ * state, and state is never silently coerced. Alert on it, register the
+ * missing migration (or fix the deploy), and the next run resumes cleanly.
+ */
+class StateContractMismatchError extends Error {
+    contractId;
+    reason;
+    storedVersion;
+    expectedVersion;
+    constructor(contractId, reason, storedVersion, expectedVersion, detail) {
+        super(`durable-state contract mismatch for "${contractId}" (${reason}): stored v${storedVersion}, contract v${expectedVersion}${detail ? ` — ${detail}` : ""}`);
+        this.contractId = contractId;
+        this.reason = reason;
+        this.storedVersion = storedVersion;
+        this.expectedVersion = expectedVersion;
+        this.name = "StateContractMismatchError";
+        Object.setPrototypeOf(this, StateContractMismatchError.prototype);
+    }
+}
+exports.StateContractMismatchError = StateContractMismatchError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAEnC;IACA;IACA;IAHX,YACW,GAAW,EACX,gBAAwB,EACxB,cAAsB;QAE/B,KAAK,CACH,kCAAkC,GAAG,wBAAwB,gBAAgB,WAAW,cAAc,EAAE,CACzG,CAAC;QANO,QAAG,GAAH,GAAG,CAAQ;QACX,qBAAgB,GAAhB,gBAAgB,CAAQ;QACxB,mBAAc,GAAd,cAAc,CAAQ;QAK/B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,qBAAqB,CAAC,SAAS,CAAC,CAAC;IAC/D,CAAC;CACF;AAZD,sDAYC;AAQD;;;;;;;GAOG;AACH,MAAa,0BAA2B,SAAQ,KAAK;IAExC;IACA;IACA;IACA;IAJX,YACW,UAAkB,EAClB,MAAmC,EACnC,aAAqB,EACrB,eAAuB,EAChC,MAAe;QAEf,KAAK,CACH,wCAAwC,UAAU,MAAM,MAAM,cAAc,aAAa,eAAe,eAAe,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CACzJ,CAAC;QARO,eAAU,GAAV,UAAU,CAAQ;QAClB,WAAM,GAAN,MAAM,CAA6B;QACnC,kBAAa,GAAb,aAAa,CAAQ;QACrB,oBAAe,GAAf,eAAe,CAAQ;QAMhC,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,CAAC;IACpE,CAAC;CACF;AAdD,gEAcC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { durableState } from "./durableState";
+export { sentinelState } from "./sentinel";
+export type { SentinelStateConfig, SentinelStateHandle } from "./sentinel";
+export { InMemoryDurableStateStore } from "./InMemoryDurableStateStore";
+export { RevisionConflictError, StateContractMismatchError, type StateContractMismatchReason, } from "./errors";
+export { stableStringify, canonicalEqual } from "./canonical";
+export type { ClearInput, ClearResult, DurableStateConfig, DurableStateHandle, DurableStateRecord, DurableStateStore, EffectRegistry, LoadInput, LoadResult, Migration, SaveInput, SaveResult, TaskExecutor, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,2BAA2B,GACjC,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalEqual = exports.stableStringify = exports.StateContractMismatchError = exports.RevisionConflictError = exports.InMemoryDurableStateStore = exports.sentinelState = exports.durableState = void 0;
+var durableState_1 = require("./durableState");
+Object.defineProperty(exports, "durableState", { enumerable: true, get: function () { return durableState_1.durableState; } });
+var sentinel_1 = require("./sentinel");
+Object.defineProperty(exports, "sentinelState", { enumerable: true, get: function () { return sentinel_1.sentinelState; } });
+var InMemoryDurableStateStore_1 = require("./InMemoryDurableStateStore");
+Object.defineProperty(exports, "InMemoryDurableStateStore", { enumerable: true, get: function () { return InMemoryDurableStateStore_1.InMemoryDurableStateStore; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "RevisionConflictError", { enumerable: true, get: function () { return errors_1.RevisionConflictError; } });
+Object.defineProperty(exports, "StateContractMismatchError", { enumerable: true, get: function () { return errors_1.StateContractMismatchError; } });
+var canonical_1 = require("./canonical");
+Object.defineProperty(exports, "stableStringify", { enumerable: true, get: function () { return canonical_1.stableStringify; } });
+Object.defineProperty(exports, "canonicalEqual", { enumerable: true, get: function () { return canonical_1.canonicalEqual; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AACrB,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AAEtB,yEAAwE;AAA/D,sIAAA,yBAAyB,OAAA;AAClC,mCAIkB;AAHhB,+GAAA,qBAAqB,OAAA;AACrB,oHAAA,0BAA0B,OAAA;AAG5B,yCAA8D;AAArD,4GAAA,eAAe,OAAA;AAAE,2GAAA,cAAc,OAAA"}

package/dist/sentinel.d.ts

@@ -0,0 +1,33 @@
+import type { ScheduleDefinition } from "@loomwork/core";
+import type { ZodSchema } from "zod";
+import type { ClearResult, DurableStateHandle, DurableStateStore, EffectRegistry, LoadResult, Migration, SaveResult, TaskExecutor } from "./types";
+export interface SentinelStateConfig<T> {
+    /** The schedule whose occurrences share this state — the key derives from its id. */
+    schedule: Pick<ScheduleDefinition, "id">;
+    schema: ZodSchema<T>;
+    /** Current contract version; defaults to 1. */
+    version?: number;
+    migrations?: Readonly<Record<number, Migration>>;
+    store: DurableStateStore;
+    /** Contract id override; defaults to `<scheduleId>.state`. */
+    id?: string;
+}
+export interface SentinelStateHandle<T> {
+    /** The derived state key: `sentinel:<scheduleId>`. */
+    readonly key: string;
+    /** The underlying handle, for advanced use (extra keys, explicit step ids). */
+    readonly state: DurableStateHandle<T>;
+    register(runtime: EffectRegistry): void;
+    load(ctx: TaskExecutor): Promise<LoadResult<T>>;
+    save(ctx: TaskExecutor, value: T, expectedRevision: number): Promise<SaveResult>;
+    clear(ctx: TaskExecutor): Promise<ClearResult>;
+}
+/**
+ * DS-5 — the §2 P-1 sentinel pattern as one declaration: a `schedule$`-driven
+ * agent's carry state, keyed by the schedule id. Each occurrence loads at wake
+ * (recorded, validated, migrated), does its work, and saves with the loaded
+ * revision — T1's one-live-occurrence-per-schedule guarantee makes the CAS a
+ * misconfiguration tripwire rather than a contention point.
+ */
+export declare function sentinelState<T>(config: SentinelStateConfig<T>): SentinelStateHandle<T>;
+//# sourceMappingURL=sentinel.d.ts.map

package/dist/sentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAErC,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACb,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,qFAAqF;IACrF,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IACzC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACrB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IACjD,KAAK,EAAE,iBAAiB,CAAC;IACzB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjF,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAChD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAiBvF"}

package/dist/sentinel.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sentinelState = sentinelState;
+const durableState_1 = require("./durableState");
+/**
+ * DS-5 — the §2 P-1 sentinel pattern as one declaration: a `schedule$`-driven
+ * agent's carry state, keyed by the schedule id. Each occurrence loads at wake
+ * (recorded, validated, migrated), does its work, and saves with the loaded
+ * revision — T1's one-live-occurrence-per-schedule guarantee makes the CAS a
+ * misconfiguration tripwire rather than a contention point.
+ */
+function sentinelState(config) {
+    const state = (0, durableState_1.durableState)({
+        id: config.id ?? `${config.schedule.id}.state`,
+        version: config.version ?? 1,
+        schema: config.schema,
+        ...(config.migrations !== undefined && { migrations: config.migrations }),
+        store: config.store,
+    });
+    const key = `sentinel:${config.schedule.id}`;
+    return {
+        key,
+        state,
+        register: (runtime) => state.register(runtime),
+        load: (ctx) => state.load(ctx, key),
+        save: (ctx, value, expectedRevision) => state.save(ctx, key, value, expectedRevision),
+        clear: (ctx) => state.clear(ctx, key),
+    };
+}
+//# sourceMappingURL=sentinel.js.map

package/dist/sentinel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.js","sourceRoot":"","sources":["../src/sentinel.ts"],"names":[],"mappings":";;AA4CA,sCAiBC;AA3DD,iDAA8C;AAmC9C;;;;;;GAMG;AACH,SAAgB,aAAa,CAAI,MAA8B;IAC7D,MAAM,KAAK,GAAG,IAAA,2BAAY,EAAI;QAC5B,EAAE,EAAE,MAAM,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,QAAQ;QAC9C,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,CAAC;QAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,GAAG,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC;QACzE,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,YAAY,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;IAC7C,OAAO;QACL,GAAG;QACH,KAAK;QACL,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;QAC9C,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;QACnC,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,CAAC;QACrF,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+import type { ExecutableTask, TaskDefinition } from "@loomwork/core";
+import type { Effect } from "@loomwork/effect-runtime";
+import type { ZodSchema } from "zod";
+/** The stored envelope: what a backend persists per key. Revisions start at 1. */
+export interface DurableStateRecord {
+    contractVersion: number;
+    revision: number;
+    payload: unknown;
+}
+/**
+ * The durable-state store SPI. Backends are dumb keyed CAS stores — all
+ * contract knowledge (schemas, migrations) lives above, in {@link durableState}.
+ * `save` with `expectedRevision: 0` creates; any mismatch rejects with
+ * {@link RevisionConflictError} (`name: "RevisionConflictError"` for 3P
+ * backends that cannot share the class). Conformance:
+ * `runDurableStateStoreConformance` in `@loomwork/conformance`.
+ */
+export interface DurableStateStore {
+    load(key: string): Promise<DurableStateRecord | null>;
+    save(key: string, value: {
+        contractVersion: number;
+        payload: unknown;
+    }, expectedRevision: number): Promise<DurableStateRecord>;
+    /** Remove the key. Idempotent. */
+    clear(key: string): Promise<void>;
+    close?(): Promise<void>;
+}
+/** DS-3 — one migration step: payload at version N → payload at version N+1. */
+export type Migration = (value: unknown) => unknown;
+export interface DurableStateConfig<T> {
+    /** Contract id — namespaces the registered tool ids (`<id>.load` / `<id>.save` / `<id>.clear`). */
+    id: string;
+    /** Current contract version (integer ≥ 1). Stored envelopes carry the version they were written under. */
+    version: number;
+    /** The CURRENT version's schema. Every load validates against it after migration. */
+    schema: ZodSchema<T>;
+    /** `migrations[n]` migrates a payload from version n to n+1. Sparse maps stall loudly (DS-3). */
+    migrations?: Readonly<Record<number, Migration>>;
+    store: DurableStateStore;
+}
+export interface LoadInput {
+    key: string;
+}
+export interface LoadResult<T> {
+    found: boolean;
+    /** Validated, current-contract value — `null` when not found. */
+    value: T | null;
+    /** Pass back to `save` as `expectedRevision` (0 when not found → create). */
+    revision: number;
+    contractVersion: number;
+    /** Non-null when a stored older envelope was migrated on this load (recorded in the step output). */
+    migrated: {
+        from: number;
+        to: number;
+    } | null;
+}
+export interface SaveInput<T> {
+    key: string;
+    value: T;
+    expectedRevision: number;
+}
+export interface SaveResult {
+    revision: number;
+}
+export interface ClearInput {
+    key: string;
+}
+export interface ClearResult {
+    cleared: true;
+}
+/** Structural view of `EffectRuntime.register` — anything that accepts (toolId, effect). */
+export interface EffectRegistry {
+    register(toolId: string, effect: Effect): void;
+}
+/** Structural view of the execution context — `WorkflowContext.execute` satisfies it. */
+export interface TaskExecutor {
+    execute<TIn, TOut>(task: ExecutableTask<TIn, TOut>, input: TIn): Promise<TOut>;
+}
+export interface DurableStateHandle<T> {
+    readonly id: string;
+    readonly version: number;
+    readonly toolIds: {
+        load: string;
+        save: string;
+        clear: string;
+    };
+    /** `ctx.execute`-able task metadata (kind "memory"); ids default to the tool ids. */
+    readonly tasks: {
+        load: TaskDefinition<LoadInput, LoadResult<T>>;
+        save: TaskDefinition<SaveInput<T>, SaveResult>;
+        clear: TaskDefinition<ClearInput, ClearResult>;
+    };
+    /** The effects to register — or call {@link DurableStateHandle.register}. */
+    readonly effects: {
+        load: Effect<LoadInput, LoadResult<T>>;
+        save: Effect<SaveInput<T>, SaveResult>;
+        clear: Effect<ClearInput, ClearResult>;
+    };
+    register(runtime: EffectRegistry): void;
+    /**
+     * Recorded read (DS-1): the result folds from STEP_COMPLETED on replay — the
+     * store is never re-read. One call per default step id; pass `stepId` for
+     * additional loads in the same run.
+     */
+    load(ctx: TaskExecutor, key: string, opts?: {
+        stepId?: string;
+    }): Promise<LoadResult<T>>;
+    /** Recorded CAS write (DS-1/DS-4). `expectedRevision` comes from the prior load (0 = create). */
+    save(ctx: TaskExecutor, key: string, value: T, expectedRevision: number, opts?: {
+        stepId?: string;
+    }): Promise<SaveResult>;
+    clear(ctx: TaskExecutor, key: string, opts?: {
+        stepId?: string;
+    }): Promise<ClearResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@loomwork/plugin-durable-state",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Typed, versioned, migratable keyed state for Loom (ADR 0051 D2) — carry state across bounded runs as RECORDED effects: load/save results land in STEP_COMPLETED so replay folds the recorded value and never re-reads the store. Zod-validated envelopes, registered version-to-version migrations (loud StateContractMismatch when absent), compare-and-set revisions, and a sentinelState convenience for schedule-driven agents.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "@loomwork/core": "^0.1.0",
+    "@loomwork/effect-runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "@loomwork/conformance": "0.1.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "plugins/durable-state"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/InMemoryDurableStateStore.ts

@@ -0,0 +1,39 @@
+import { RevisionConflictError } from "./errors";
+import type { DurableStateRecord, DurableStateStore } from "./types";
+
+/**
+ * Reference in-memory backend — the conformance baseline, and the test/dev
+ * default. Deep-clones on both write and read so callers can never alias the
+ * stored record (matching the value semantics of the durable backends, where
+ * a JSON round-trip breaks aliasing anyway).
+ */
+export class InMemoryDurableStateStore implements DurableStateStore {
+  private readonly records = new Map<string, DurableStateRecord>();
+
+  async load(key: string): Promise<DurableStateRecord | null> {
+    const record = this.records.get(key);
+    return record === undefined ? null : structuredClone(record);
+  }
+
+  async save(
+    key: string,
+    value: { contractVersion: number; payload: unknown },
+    expectedRevision: number
+  ): Promise<DurableStateRecord> {
+    const actual = this.records.get(key)?.revision ?? 0;
+    if (expectedRevision !== actual) {
+      throw new RevisionConflictError(key, expectedRevision, actual);
+    }
+    const record: DurableStateRecord = {
+      contractVersion: value.contractVersion,
+      revision: actual + 1,
+      payload: structuredClone(value.payload),
+    };
+    this.records.set(key, record);
+    return structuredClone(record);
+  }
+
+  async clear(key: string): Promise<void> {
+    this.records.delete(key);
+  }
+}

package/src/canonical.ts

@@ -0,0 +1,33 @@
+/**
+ * Depth cap for canonicalization. JSON nesting beyond this is pathological
+ * (and could stack-overflow the save path — audit W8); exceeding it throws a
+ * loud RangeError rather than crashing the process.
+ */
+const MAX_DEPTH = 256;
+
+/**
+ * Canonical JSON serialization: object keys sorted, `undefined` properties
+ * skipped (JSON semantics). Used for the save effect's adopt-own-write check —
+ * value equality must not depend on property insertion order.
+ */
+export function stableStringify(value: unknown, depth = 0): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (depth >= MAX_DEPTH) {
+    throw new RangeError(`stableStringify: value nests deeper than ${MAX_DEPTH} levels`);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item, depth + 1)).join(",")}]`;
+  }
+  const entries = Object.keys(value as Record<string, unknown>)
+    .sort()
+    .map((key) => [key, (value as Record<string, unknown>)[key]] as const)
+    .filter(([, v]) => v !== undefined)
+    .map(([key, v]) => `${JSON.stringify(key)}:${stableStringify(v, depth + 1)}`);
+  return `{${entries.join(",")}}`;
+}
+
+export function canonicalEqual(a: unknown, b: unknown): boolean {
+  return stableStringify(a) === stableStringify(b);
+}