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

package/src/durableState.ts

@@ -0,0 +1,281 @@
+import type { TaskDefinition } from "@loomwork/core";
+import { ToolEffect } from "@loomwork/effect-runtime";
+import { z } from "zod";
+import { canonicalEqual } from "./canonical";
+import { RevisionConflictError, StateContractMismatchError } from "./errors";
+import type {
+  ClearInput,
+  ClearResult,
+  DurableStateConfig,
+  DurableStateHandle,
+  DurableStateRecord,
+  EffectRegistry,
+  LoadInput,
+  LoadResult,
+  SaveInput,
+  SaveResult,
+  TaskExecutor,
+} from "./types";
+
+/**
+ * DS-3 — bring a stored envelope to the current contract: apply the
+ * version-to-version migration chain, then validate against the current
+ * schema. Every failure mode is a loud, typed {@link StateContractMismatchError}
+ * (DS-2: a run never proceeds on unvalidated state).
+ */
+function migrateRecord<T>(
+  config: DurableStateConfig<T>,
+  key: string,
+  record: DurableStateRecord
+): { value: T; migrated: { from: number; to: number } | null } {
+  const from = record.contractVersion;
+  if (from > config.version) {
+    throw new StateContractMismatchError(
+      config.id,
+      "future-version",
+      from,
+      config.version,
+      `key "${key}" was written by a newer deployment`
+    );
+  }
+  let payload = record.payload;
+  for (let v = from; v < config.version; v++) {
+    const step = config.migrations?.[v];
+    if (step === undefined) {
+      throw new StateContractMismatchError(
+        config.id,
+        "no-migration-path",
+        from,
+        config.version,
+        `key "${key}": no migration registered for v${v} → v${v + 1}`
+      );
+    }
+    try {
+      payload = step(payload);
+    } catch (err) {
+      throw new StateContractMismatchError(
+        config.id,
+        "migration-failed",
+        from,
+        config.version,
+        `key "${key}": migration v${v} → v${v + 1} threw: ${String(err)}`
+      );
+    }
+  }
+  const parsed = config.schema.safeParse(payload);
+  if (!parsed.success) {
+    throw new StateContractMismatchError(
+      config.id,
+      "validation-failed",
+      from,
+      config.version,
+      `key "${key}": ${parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`
+    );
+  }
+  return {
+    value: parsed.data,
+    migrated: from < config.version ? { from, to: config.version } : null,
+  };
+}
+
+function isRevisionConflict(err: unknown): err is RevisionConflictError {
+  return (
+    err instanceof RevisionConflictError ||
+    (typeof err === "object" && err !== null && (err as Error).name === "RevisionConflictError")
+  );
+}
+
+/**
+ * ADR 0051 D2 — typed, versioned, migratable keyed state as RECORDED effects.
+ * `load`/`save` run through `ctx.execute`, so results land in STEP_COMPLETED:
+ * replay folds the recorded value and never touches the backing store —
+ * replay-correct by construction (DS-1). This is deliberately NOT `memory$`,
+ * which is a non-replayable agent-layer side channel.
+ */
+export function durableState<T>(config: DurableStateConfig<T>): DurableStateHandle<T> {
+  if (config.id.length === 0) {
+    throw new TypeError("durableState: config.id must be a non-empty string");
+  }
+  if (!Number.isInteger(config.version) || config.version < 1) {
+    throw new TypeError(`durableState "${config.id}": version must be an integer ≥ 1`);
+  }
+
+  const toolIds = {
+    load: `${config.id}.load`,
+    save: `${config.id}.save`,
+    clear: `${config.id}.clear`,
+  } as const;
+
+  const loadOutputSchema = z.object({
+    found: z.boolean(),
+    value: config.schema.nullable(),
+    revision: z.number().int().nonnegative(),
+    contractVersion: z.number().int().positive(),
+    migrated: z
+      .object({ from: z.number().int().positive(), to: z.number().int().positive() })
+      .nullable(),
+  }) as unknown as z.ZodSchema<LoadResult<T>>;
+
+  const tasks: DurableStateHandle<T>["tasks"] = {
+    load: {
+      _tag: "TaskDefinition",
+      kind: "memory",
+      id: toolIds.load,
+      toolId: toolIds.load,
+      name: `${config.id} load`,
+      inputSchema: z.object({ key: z.string() }) as z.ZodSchema<LoadInput>,
+      outputSchema: loadOutputSchema,
+    },
+    save: {
+      _tag: "TaskDefinition",
+      kind: "memory",
+      id: toolIds.save,
+      toolId: toolIds.save,
+      name: `${config.id} save`,
+      outputSchema: z.object({ revision: z.number().int().positive() }) as z.ZodSchema<SaveResult>,
+    },
+    clear: {
+      _tag: "TaskDefinition",
+      kind: "memory",
+      id: toolIds.clear,
+      toolId: toolIds.clear,
+      name: `${config.id} clear`,
+      outputSchema: z.object({ cleared: z.literal(true) }) as z.ZodSchema<ClearResult>,
+    },
+  };
+
+  const loadEffect = new ToolEffect<LoadInput, LoadResult<T>>(
+    async ({ key }) => {
+      const record = await config.store.load(key);
+      if (record === null) {
+        return {
+          found: false,
+          value: null,
+          revision: 0,
+          contractVersion: config.version,
+          migrated: null,
+        };
+      }
+      const { value, migrated } = migrateRecord(config, key, record);
+      return {
+        found: true,
+        value,
+        revision: record.revision,
+        contractVersion: config.version,
+        migrated,
+      };
+    },
+    // ADR 0073 — deliberately NO `mode`. `load` is genuinely dual-seam: journaled
+    // inside a flow (where the recorded value is what replay folds), and a
+    // perfectly reasonable ambient read outside one — an operator dashboard
+    // peeking at a sentinel's carry state changes nothing and should not have to
+    // start an execution to look. Pinning it to either seam would forbid a
+    // legitimate caller, which is why the marker is opt-in rather than required.
+    { idempotent: true }
+  );
+
+  // K9 — declared idempotent: the CAS makes a crash-recovery re-run safe. If the
+  // prior attempt committed, the re-run's expectedRevision now trails by exactly
+  // one; when the stored envelope is byte-equal to what we tried to write, adopt
+  // it as our own committed write. A genuinely concurrent writer either lands at
+  // a different revision or a different payload — both still conflict loudly.
+  const saveEffect = new ToolEffect<SaveInput<T>, SaveResult>(
+    async ({ key, value, expectedRevision }) => {
+      const parsed = config.schema.safeParse(value);
+      if (!parsed.success) {
+        throw new StateContractMismatchError(
+          config.id,
+          "validation-failed",
+          config.version,
+          config.version,
+          `key "${key}" (save): ${parsed.error.issues.map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`).join("; ")}`
+        );
+      }
+      try {
+        const record = await config.store.save(
+          key,
+          { contractVersion: config.version, payload: parsed.data },
+          expectedRevision
+        );
+        return { revision: record.revision };
+      } catch (err) {
+        if (isRevisionConflict(err) && err.actualRevision === expectedRevision + 1) {
+          const current = await config.store.load(key);
+          if (
+            current !== null &&
+            current.revision === expectedRevision + 1 &&
+            current.contractVersion === config.version &&
+            canonicalEqual(current.payload, parsed.data)
+          ) {
+            return { revision: current.revision };
+          }
+        }
+        throw err;
+      }
+    },
+    {
+      idempotent: true,
+      // ADR 0073 — a mutation that MUST be recorded. The whole contract of this
+      // plugin is "RECORDED effects: replay folds the recorded value, never the
+      // store" (ADR 0053). A transient write would mutate the store while the log
+      // learns nothing, so replay would fold a state the run never produced —
+      // exactly the split-brain the recorded-effect design exists to prevent.
+      mode: "journaled",
+    }
+  );
+
+  const clearEffect = new ToolEffect<ClearInput, ClearResult>(
+    async ({ key }) => {
+      await config.store.clear(key);
+      return { cleared: true };
+    },
+    {
+      idempotent: true,
+      // ADR 0073 — a mutation that MUST be recorded. The whole contract of this
+      // plugin is "RECORDED effects: replay folds the recorded value, never the
+      // store" (ADR 0053). A transient write would mutate the store while the log
+      // learns nothing, so replay would fold a state the run never produced —
+      // exactly the split-brain the recorded-effect design exists to prevent.
+      mode: "journaled",
+    }
+  );
+
+  const effects: DurableStateHandle<T>["effects"] = {
+    load: loadEffect,
+    save: saveEffect,
+    clear: clearEffect,
+  };
+
+  const taskWith = <TIn, TOut>(
+    task: TaskDefinition<TIn, TOut>,
+    stepId: string | undefined
+  ): TaskDefinition<TIn, TOut> => (stepId === undefined ? task : { ...task, id: stepId });
+
+  return {
+    id: config.id,
+    version: config.version,
+    toolIds,
+    tasks,
+    effects,
+    register(runtime: EffectRegistry): void {
+      runtime.register(toolIds.load, loadEffect);
+      runtime.register(toolIds.save, saveEffect);
+      runtime.register(toolIds.clear, clearEffect);
+    },
+    load(ctx: TaskExecutor, key: string, opts?: { stepId?: string }): Promise<LoadResult<T>> {
+      return ctx.execute(taskWith(tasks.load, opts?.stepId), { key });
+    },
+    save(
+      ctx: TaskExecutor,
+      key: string,
+      value: T,
+      expectedRevision: number,
+      opts?: { stepId?: string }
+    ): Promise<SaveResult> {
+      return ctx.execute(taskWith(tasks.save, opts?.stepId), { key, value, expectedRevision });
+    },
+    clear(ctx: TaskExecutor, key: string, opts?: { stepId?: string }): Promise<ClearResult> {
+      return ctx.execute(taskWith(tasks.clear, opts?.stepId), { key });
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 class RevisionConflictError extends Error {
+  constructor(
+    readonly key: string,
+    readonly expectedRevision: number,
+    readonly actualRevision: number
+  ) {
+    super(
+      `durable-state CAS conflict on "${key}": expected revision ${expectedRevision}, found ${actualRevision}`
+    );
+    this.name = "RevisionConflictError";
+    Object.setPrototypeOf(this, RevisionConflictError.prototype);
+  }
+}
+
+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 class StateContractMismatchError extends Error {
+  constructor(
+    readonly contractId: string,
+    readonly reason: StateContractMismatchReason,
+    readonly storedVersion: number,
+    readonly expectedVersion: number,
+    detail?: string
+  ) {
+    super(
+      `durable-state contract mismatch for "${contractId}" (${reason}): stored v${storedVersion}, contract v${expectedVersion}${detail ? ` — ${detail}` : ""}`
+    );
+    this.name = "StateContractMismatchError";
+    Object.setPrototypeOf(this, StateContractMismatchError.prototype);
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+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";

package/src/sentinel.ts

@@ -0,0 +1,62 @@
+import type { ScheduleDefinition } from "@loomwork/core";
+import type { ZodSchema } from "zod";
+import { durableState } from "./durableState";
+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 function sentinelState<T>(config: SentinelStateConfig<T>): SentinelStateHandle<T> {
+  const state = durableState<T>({
+    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),
+  };
+}

package/src/types.ts

@@ -0,0 +1,122 @@
+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>;
+}