@demlik/tea 0.1.0 → 0.1.2

package/dist/with-telemetry/index.d.ts

@@ -0,0 +1,149 @@
+import { C as Cmd, S as Sub, M as Machine } from '../core-BoB6t7dB.js';
+
+/**
+ * @demlik/tea/with-telemetry — the pattern-setting wrapper of the wrapper tier.
+ *
+ * `withTelemetry(base, config)` is a **pure function over machine data**: it
+ * takes any `Machine<S, M, C, U, Ctx>` and returns a NEW `Machine` over the
+ * composed Model `{ base, $telemetry }`. You `run()` / `replay()` the result
+ * exactly like any other machine — there is no new runtime, no privileged
+ * interception path.
+ *
+ * This is the SAFEST wrapper and the one every future wrapper (`withDeadline`,
+ * `withResilience`) copies: it is **OBSERVE-ONLY**. It observes every base Msg
+ * + transition, increments a monotonic counter, and emits a fire-and-forget
+ * telemetry Cmd whose interpret handler hands the event to a sink Port. It must
+ * NOT transform base Cmds or gate base Msgs — base behavior is byte-identical
+ * with or without it. The moment a telemetry wrapper alters the Msg/Cmd stream
+ * instead of observing it, it has become saga middleware (the betrayal the
+ * research warned of).
+ *
+ * ## The 5 rules it satisfies (from the wrapper-tier contract)
+ *
+ *   1. **Named, serializable slice.** Wrapper state lives at `model.$telemetry`,
+ *      a plain `{ seq: number }` — JSON-serializable, never a closure.
+ *   2. **Retag-and-re-emit, never swallow.** The merged `update` runs the base
+ *      reducer, passes its Cmds through UNCHANGED, and APPENDS its own
+ *      `$telemetry:emit` Cmd. No base Cmd ever vanishes; nothing is gated.
+ *   3. **Every decision is a Msg/Cmd.** Each telemetry emission is a
+ *      `$telemetry:emit` Cmd through the merged `update`, so "why did this fire"
+ *      is answerable from reducer + log alone, and `runtime.observe` sees it.
+ *   4. **Subs merge by id.** Telemetry has no timers — merged subs/subscribe are
+ *      the base's, verbatim.
+ *   5. **Clock out of update.** The default event carries no wall-clock read.
+ *      The optional `at` is stamped at the interpret boundary (the `clock`
+ *      port), never inside the merged `update`.
+ *
+ * ## Where the clock lives
+ *
+ * Inside the merged `update`: nowhere. The reducer is pure — it reads `seq` from
+ * the slice and projects the event from `(msg, prev, next)`. The ONLY clock read
+ * is at the interpret boundary: the `$telemetry:emit` handler stamps `event.at`
+ * from the injected `clock` port (if supplied and the projector left `at`
+ * unset), exactly as `resilient-call` reads `Date.now()` only inside `handlers`.
+ *
+ * ## Typical wiring
+ *
+ *   const observed = withTelemetry(baseMachine, {
+ *     event: (msg, _prev, next) => ({ seq: next.$telemetry.seq, msgType: msg.type }),
+ *   });
+ *   const runtime = run(observed, {
+ *     ctx: { ...baseCtx, telemetrySink: (e) => posthog.capture(e), clock: Date.now },
+ *   });
+ */
+
+/**
+ * The datum handed to the sink. The default projector emits `{ seq, msgType }`;
+ * a custom `event` projector may return any extra fields. `at` is OPTIONAL and
+ * plain data — it is stamped at the interpret boundary by the `clock` port, not
+ * inside the (pure, clock-free) merged `update`. Every field is JSON-round-trip
+ * serializable so a recorded telemetry stream stays durable.
+ */
+interface TelemetryEvent {
+    /** Monotonic event counter — equals `$telemetry.seq` after the transition. */
+    readonly seq: number;
+    /** The `Msg.type` discriminant that drove this transition. */
+    readonly msgType: string;
+    /**
+     * Wall-clock instant the event was emitted, ms since epoch. Absent until the
+     * interpret boundary stamps it (the `clock` port). Optional because the
+     * merged `update` is clock-free — a verb must never read `Date.now()`.
+     */
+    readonly at?: number;
+}
+/**
+ * The wrapper's Model slice. A monotonic event counter — minimal but real, so
+ * the named-slice mechanism is exercised for the richer-slice wrappers that
+ * follow. `seq` equals the number of base Msgs folded so far: after replaying
+ * `N` msgs, `$telemetry.seq === N`. Plain data → serializes into a `Store<S>`.
+ */
+interface TelemetrySlice {
+    readonly seq: number;
+}
+/**
+ * The composed Model. The base machine's state is nested under `base`; the
+ * wrapper's state lives in the NAMED `$telemetry` slice — never hidden in a
+ * closure. Both fields are plain data, so the whole composed Model round-trips
+ * through `JSON.parse(JSON.stringify(...))` iff the base state does.
+ */
+interface TelemetryModel<S> {
+    readonly base: S;
+    readonly $telemetry: TelemetrySlice;
+}
+/**
+ * The fire-and-forget Cmd the merged `update` appends after every base
+ * transition. It carries the projected `event` as plain data (invariant 3 —
+ * no closure). The interpret handler hands `event` to the sink and dispatches
+ * NOTHING back, so there is no feedback loop.
+ */
+type TelemetryEmitCmd = Cmd<"$telemetry:emit"> & {
+    readonly event: TelemetryEvent;
+};
+/**
+ * The side-effecting ports the wrapper adds to `Ctx`. The sink (PostHog / Sentry
+ * bridge) lives at the interpret boundary, never in a verb. `clock` is the
+ * optional wall-clock source used to stamp `event.at` at that same boundary —
+ * pass `Date.now` in production, a fixed `() => 1000` in tests; omit it to leave
+ * `at` unset.
+ */
+interface TelemetryPorts {
+    /** The side-effecting sink. Fire-and-forget — its result is never awaited into a Msg. */
+    readonly telemetrySink: (event: TelemetryEvent) => void | Promise<void>;
+    /** Optional clock for stamping `event.at` at the interpret boundary. */
+    readonly clock?: () => number;
+}
+/**
+ * The telemetry knob. `event` is an OPTIONAL projector mapping
+ * `(msg, prev, next)` to a `TelemetryEvent`; omit it and the default emits
+ * `{ seq, msgType }` where `seq` is the post-transition counter. The projector
+ * runs INSIDE the pure merged `update`, so it must not read the clock — stamp
+ * `at` at the sink boundary via the `clock` port instead.
+ */
+interface TelemetryConfig<S, M extends {
+    type: string;
+}> {
+    readonly event?: (msg: M, prev: TelemetryModel<S>, next: TelemetryModel<S>) => TelemetryEvent;
+}
+/**
+ * Wrap `base` with observe-only telemetry. Returns a NEW `Machine` over the
+ * composed Model `{ base, $telemetry }`, with the base's Msgs/Cmds/Subs/Ctx
+ * extended by the wrapper's own.
+ *
+ * The composed machine:
+ *   - `init` rehydrates the base (honoring the `[loaded, []]` contract) and
+ *     seeds `$telemetry: { seq: 0 }`. Base init Cmds pass through unchanged.
+ *   - `update` (Reducer form, keyed by every base `Msg.type`) runs the base
+ *     reducer, increments `seq`, and appends a `$telemetry:emit` Cmd carrying
+ *     the projected event. Base Cmds pass through UNCHANGED — the observe-only
+ *     property.
+ *   - `subscriptions` / `subscribe` are the base's, verbatim (no timers).
+ *   - `interpret` is `{ ...base.interpret, "$telemetry:emit": sink-handler }`.
+ *
+ * @param base   any `Machine<S, M, C, U, Ctx>`.
+ * @param config the telemetry knob (optional `event` projector).
+ */
+declare function withTelemetry<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(base: Machine<S, M, C, U, Ctx>, config?: TelemetryConfig<S, M>): Machine<TelemetryModel<S>, M, C | TelemetryEmitCmd, U, Ctx & TelemetryPorts>;
+
+export { type TelemetryConfig, type TelemetryEmitCmd, type TelemetryEvent, type TelemetryModel, type TelemetryPorts, type TelemetrySlice, withTelemetry };

package/dist/with-telemetry/index.js

@@ -0,0 +1,70 @@
+import '../chunk-MMH7CW5K.js';
+import { msgKeysOf, applyCell } from '../chunk-QLA76GIT.js';
+
+// src/with-telemetry/index.ts
+function withTelemetry(base, config = {}) {
+  const project = config.event;
+  const msgKeys = msgKeysOf(base);
+  const update = {};
+  for (const key of msgKeys) {
+    update[key] = (state, msg) => {
+      const [nextBase, baseCmds] = applyCell(base, state.base, msg);
+      const $telemetry = { seq: state.$telemetry.seq + 1 };
+      const next = { base: nextBase, $telemetry };
+      const event = project ? project(msg, state, next) : { seq: $telemetry.seq, msgType: msg.type };
+      const emit = { type: "$telemetry:emit", event };
+      return [next, [...baseCmds, emit]];
+    };
+  }
+  const baseInterpret = base.interpret ?? {};
+  if (Object.hasOwn(baseInterpret, "$telemetry:emit")) {
+    throw new Error(
+      'withTelemetry: the base machine declares a reserved "$telemetry:emit" interpret handler \u2014 the wrapper owns the "$telemetry:" Cmd namespace. Rename the base handler.'
+    );
+  }
+  const interpret = {
+    ...baseInterpret,
+    // OBSERVE-ONLY at the boundary: the sink is fire-and-forget. The runtime
+    // `await`s every interpret handler in its dispatch loop, so awaiting the
+    // sink here would let a SLOW sink backpressure the wrapped machine (its
+    // next dispatch waits) and a FAILING sink crash dispatch (the throw would
+    // propagate out of the transition). Both violate the contract: telemetry
+    // must never affect base behavior OR latency. So we DO NOT await — we hand
+    // the event to the sink, normalize its result to a Promise, swallow any
+    // rejection/throw, and return immediately. The handler resolves in the same
+    // microtask the dispatch loop reaches it; the machine never waits on the
+    // sink, and a rejected sink can never become an unhandled rejection.
+    "$telemetry:emit": (cmd, ctx) => {
+      const event = cmd.event.at === void 0 && ctx.clock !== void 0 ? { ...cmd.event, at: ctx.clock() } : cmd.event;
+      try {
+        Promise.resolve(ctx.telemetrySink(event)).catch(() => {
+        });
+      } catch {
+      }
+    }
+  };
+  const baseSubscriptions = base.subscriptions;
+  const baseSubscribe = base.subscribe;
+  return {
+    init: (loaded, ctx) => {
+      if (loaded !== null) {
+        return [loaded, []];
+      }
+      const [base0, cmds] = base.init(null, ctx);
+      const model = { base: base0, $telemetry: { seq: 0 } };
+      return [model, cmds];
+    },
+    update,
+    // Subs merge to the base's, verbatim — telemetry owns no timers. The base
+    // subscribes against its own nested slice.
+    ...baseSubscriptions ? {
+      subscriptions: (state) => baseSubscriptions(state.base)
+    } : {},
+    ...baseSubscribe ? { subscribe: baseSubscribe } : {},
+    interpret
+  };
+}
+
+export { withTelemetry };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/with-telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/with-telemetry/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/with-telemetry — the pattern-setting wrapper of the wrapper tier.\n *\n * `withTelemetry(base, config)` is a **pure function over machine data**: it\n * takes any `Machine<S, M, C, U, Ctx>` and returns a NEW `Machine` over the\n * composed Model `{ base, $telemetry }`. You `run()` / `replay()` the result\n * exactly like any other machine — there is no new runtime, no privileged\n * interception path.\n *\n * This is the SAFEST wrapper and the one every future wrapper (`withDeadline`,\n * `withResilience`) copies: it is **OBSERVE-ONLY**. It observes every base Msg\n * + transition, increments a monotonic counter, and emits a fire-and-forget\n * telemetry Cmd whose interpret handler hands the event to a sink Port. It must\n * NOT transform base Cmds or gate base Msgs — base behavior is byte-identical\n * with or without it. The moment a telemetry wrapper alters the Msg/Cmd stream\n * instead of observing it, it has become saga middleware (the betrayal the\n * research warned of).\n *\n * ## The 5 rules it satisfies (from the wrapper-tier contract)\n *\n *   1. **Named, serializable slice.** Wrapper state lives at `model.$telemetry`,\n *      a plain `{ seq: number }` — JSON-serializable, never a closure.\n *   2. **Retag-and-re-emit, never swallow.** The merged `update` runs the base\n *      reducer, passes its Cmds through UNCHANGED, and APPENDS its own\n *      `$telemetry:emit` Cmd. No base Cmd ever vanishes; nothing is gated.\n *   3. **Every decision is a Msg/Cmd.** Each telemetry emission is a\n *      `$telemetry:emit` Cmd through the merged `update`, so \"why did this fire\"\n *      is answerable from reducer + log alone, and `runtime.observe` sees it.\n *   4. **Subs merge by id.** Telemetry has no timers — merged subs/subscribe are\n *      the base's, verbatim.\n *   5. **Clock out of update.** The default event carries no wall-clock read.\n *      The optional `at` is stamped at the interpret boundary (the `clock`\n *      port), never inside the merged `update`.\n *\n * ## Where the clock lives\n *\n * Inside the merged `update`: nowhere. The reducer is pure — it reads `seq` from\n * the slice and projects the event from `(msg, prev, next)`. The ONLY clock read\n * is at the interpret boundary: the `$telemetry:emit` handler stamps `event.at`\n * from the injected `clock` port (if supplied and the projector left `at`\n * unset), exactly as `resilient-call` reads `Date.now()` only inside `handlers`.\n *\n * ## Typical wiring\n *\n *   const observed = withTelemetry(baseMachine, {\n *     event: (msg, _prev, next) => ({ seq: next.$telemetry.seq, msgType: msg.type }),\n *   });\n *   const runtime = run(observed, {\n *     ctx: { ...baseCtx, telemetrySink: (e) => posthog.capture(e), clock: Date.now },\n *   });\n */\n\nimport type { Cmd, Interpret, Machine, Reducer, Sub } from \"../index\";\nimport { applyCell, msgKeysOf } from \"../index\";\n\n// ===========================================================================\n// The event + the slice + the ports — the telemetry vocabulary.\n// ===========================================================================\n\n/**\n * The datum handed to the sink. The default projector emits `{ seq, msgType }`;\n * a custom `event` projector may return any extra fields. `at` is OPTIONAL and\n * plain data — it is stamped at the interpret boundary by the `clock` port, not\n * inside the (pure, clock-free) merged `update`. Every field is JSON-round-trip\n * serializable so a recorded telemetry stream stays durable.\n */\nexport interface TelemetryEvent {\n  /** Monotonic event counter — equals `$telemetry.seq` after the transition. */\n  readonly seq: number;\n  /** The `Msg.type` discriminant that drove this transition. */\n  readonly msgType: string;\n  /**\n   * Wall-clock instant the event was emitted, ms since epoch. Absent until the\n   * interpret boundary stamps it (the `clock` port). Optional because the\n   * merged `update` is clock-free — a verb must never read `Date.now()`.\n   */\n  readonly at?: number;\n}\n\n/**\n * The wrapper's Model slice. A monotonic event counter — minimal but real, so\n * the named-slice mechanism is exercised for the richer-slice wrappers that\n * follow. `seq` equals the number of base Msgs folded so far: after replaying\n * `N` msgs, `$telemetry.seq === N`. Plain data → serializes into a `Store<S>`.\n */\nexport interface TelemetrySlice {\n  readonly seq: number;\n}\n\n/**\n * The composed Model. The base machine's state is nested under `base`; the\n * wrapper's state lives in the NAMED `$telemetry` slice — never hidden in a\n * closure. Both fields are plain data, so the whole composed Model round-trips\n * through `JSON.parse(JSON.stringify(...))` iff the base state does.\n */\nexport interface TelemetryModel<S> {\n  readonly base: S;\n  readonly $telemetry: TelemetrySlice;\n}\n\n/**\n * The fire-and-forget Cmd the merged `update` appends after every base\n * transition. It carries the projected `event` as plain data (invariant 3 —\n * no closure). The interpret handler hands `event` to the sink and dispatches\n * NOTHING back, so there is no feedback loop.\n */\nexport type TelemetryEmitCmd = Cmd<\"$telemetry:emit\"> & {\n  readonly event: TelemetryEvent;\n};\n\n/**\n * The side-effecting ports the wrapper adds to `Ctx`. The sink (PostHog / Sentry\n * bridge) lives at the interpret boundary, never in a verb. `clock` is the\n * optional wall-clock source used to stamp `event.at` at that same boundary —\n * pass `Date.now` in production, a fixed `() => 1000` in tests; omit it to leave\n * `at` unset.\n */\nexport interface TelemetryPorts {\n  /** The side-effecting sink. Fire-and-forget — its result is never awaited into a Msg. */\n  readonly telemetrySink: (event: TelemetryEvent) => void | Promise<void>;\n  /** Optional clock for stamping `event.at` at the interpret boundary. */\n  readonly clock?: () => number;\n}\n\n/**\n * The telemetry knob. `event` is an OPTIONAL projector mapping\n * `(msg, prev, next)` to a `TelemetryEvent`; omit it and the default emits\n * `{ seq, msgType }` where `seq` is the post-transition counter. The projector\n * runs INSIDE the pure merged `update`, so it must not read the clock — stamp\n * `at` at the sink boundary via the `clock` port instead.\n */\nexport interface TelemetryConfig<S, M extends { type: string }> {\n  readonly event?: (\n    msg: M,\n    prev: TelemetryModel<S>,\n    next: TelemetryModel<S>,\n  ) => TelemetryEvent;\n}\n\n// ===========================================================================\n// withTelemetry — the wrapper.\n// ===========================================================================\n\n/**\n * Wrap `base` with observe-only telemetry. Returns a NEW `Machine` over the\n * composed Model `{ base, $telemetry }`, with the base's Msgs/Cmds/Subs/Ctx\n * extended by the wrapper's own.\n *\n * The composed machine:\n *   - `init` rehydrates the base (honoring the `[loaded, []]` contract) and\n *     seeds `$telemetry: { seq: 0 }`. Base init Cmds pass through unchanged.\n *   - `update` (Reducer form, keyed by every base `Msg.type`) runs the base\n *     reducer, increments `seq`, and appends a `$telemetry:emit` Cmd carrying\n *     the projected event. Base Cmds pass through UNCHANGED — the observe-only\n *     property.\n *   - `subscriptions` / `subscribe` are the base's, verbatim (no timers).\n *   - `interpret` is `{ ...base.interpret, \"$telemetry:emit\": sink-handler }`.\n *\n * @param base   any `Machine<S, M, C, U, Ctx>`.\n * @param config the telemetry knob (optional `event` projector).\n */\nexport function withTelemetry<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  base: Machine<S, M, C, U, Ctx>,\n  config: TelemetryConfig<S, M> = {},\n): Machine<\n  TelemetryModel<S>,\n  M,\n  C | TelemetryEmitCmd,\n  U,\n  Ctx & TelemetryPorts\n> {\n  const project = config.event;\n\n  // The merged update is a flat Reducer over the composed Model. The composed\n  // Model is NOT discriminated on `.type`, so the Transitions form is never an\n  // option here — every base Msg variant gets exactly one cell, enumerated via\n  // `msgKeysOf(base)` (keyed on the authoritative `__form` tag; #275).\n  const msgKeys = msgKeysOf(base);\n\n  const update = {} as Record<\n    string,\n    (\n      state: TelemetryModel<S>,\n      msg: M,\n    ) => readonly [TelemetryModel<S>, readonly (C | TelemetryEmitCmd)[]]\n  >;\n  for (const key of msgKeys) {\n    update[key] = (state, msg) => {\n      // 1) Run the base reducer — its result passes through UNCHANGED.\n      const [nextBase, baseCmds] = applyCell<S, M, C>(base, state.base, msg);\n      // 2) Advance the wrapper slice (monotonic counter). New object — no mutation.\n      const $telemetry: TelemetrySlice = { seq: state.$telemetry.seq + 1 };\n      const next: TelemetryModel<S> = { base: nextBase, $telemetry };\n      // 3) Project the event (pure — no clock). Default: { seq, msgType }.\n      const event: TelemetryEvent = project\n        ? project(msg, state, next)\n        : { seq: $telemetry.seq, msgType: msg.type };\n      // 4) Append the fire-and-forget emit Cmd. Base Cmds come FIRST, unchanged.\n      const emit: TelemetryEmitCmd = { type: \"$telemetry:emit\", event };\n      return [next, [...baseCmds, emit]];\n    };\n  }\n\n  // The base's interpret, extended with the one telemetry handler. The sink is\n  // the ONLY side effect, and it lives here at the interpret boundary — never in\n  // a verb. `clock` (if provided) stamps `event.at` here too, the one permitted\n  // clock read. The handler returns void synchronously — it dispatches NOTHING\n  // back (no feedback loop) AND it does NOT await the sink (no backpressure /\n  // crash from a slow or failing sink). See the fire-and-forget note below.\n  const baseInterpret =\n    (base as { interpret?: Interpret<M, C, Ctx> }).interpret ??\n    ({} as Interpret<M, C, Ctx>);\n  // Namespace guard (mirrors the substrate's SubId / definePort collision\n  // asserts). The spread below merges `$telemetry:emit` into the base's\n  // interpret map; if the base already declares that key, the spread would\n  // SILENTLY clobber the base handler. The `$telemetry:` Cmd namespace is the\n  // wrapper's — refuse to wrap a base that squats on it instead of stealing it.\n  if (Object.hasOwn(baseInterpret as object, \"$telemetry:emit\")) {\n    throw new Error(\n      'withTelemetry: the base machine declares a reserved \"$telemetry:emit\" ' +\n        'interpret handler — the wrapper owns the \"$telemetry:\" Cmd namespace. ' +\n        \"Rename the base handler.\",\n    );\n  }\n  const interpret = {\n    ...(baseInterpret as Record<string, unknown>),\n    // OBSERVE-ONLY at the boundary: the sink is fire-and-forget. The runtime\n    // `await`s every interpret handler in its dispatch loop, so awaiting the\n    // sink here would let a SLOW sink backpressure the wrapped machine (its\n    // next dispatch waits) and a FAILING sink crash dispatch (the throw would\n    // propagate out of the transition). Both violate the contract: telemetry\n    // must never affect base behavior OR latency. So we DO NOT await — we hand\n    // the event to the sink, normalize its result to a Promise, swallow any\n    // rejection/throw, and return immediately. The handler resolves in the same\n    // microtask the dispatch loop reaches it; the machine never waits on the\n    // sink, and a rejected sink can never become an unhandled rejection.\n    \"$telemetry:emit\": (\n      cmd: TelemetryEmitCmd,\n      ctx: Ctx & TelemetryPorts,\n    ): void => {\n      const event =\n        cmd.event.at === undefined && ctx.clock !== undefined\n          ? { ...cmd.event, at: ctx.clock() }\n          : cmd.event;\n      // `Promise.resolve(fn())` covers BOTH failure shapes: a sync `throw` is\n      // caught by `Promise.resolve` (the call is the argument, so a throw here\n      // would escape — guard it), and an async rejection is caught by `.catch`.\n      try {\n        Promise.resolve(ctx.telemetrySink(event)).catch(() => {});\n      } catch {\n        // A sink that throws SYNCHRONOUSLY (before returning a Promise) is\n        // swallowed here. Either way the slow/failing sink never reaches the\n        // dispatch loop's `await`.\n      }\n    },\n  } as Interpret<M, C | TelemetryEmitCmd, Ctx & TelemetryPorts>;\n\n  // Capture once so the narrowing survives into the spread (no non-null assert).\n  const baseSubscriptions = base.subscriptions;\n  const baseSubscribe = (base as { subscribe?: unknown }).subscribe;\n\n  return {\n    init: (loaded, ctx) => {\n      // Rehydrate path: `loaded !== null` MUST return `[loaded, []]` (no Cmds) —\n      // the substrate's replay enforces this. We split the composed loaded Model\n      // into its base slice and feed the base its own loaded snapshot, so the\n      // base's rehydrate contract is honored transitively.\n      if (loaded !== null) {\n        return [loaded, []];\n      }\n      const [base0, cmds] = base.init(null, ctx);\n      const model: TelemetryModel<S> = { base: base0, $telemetry: { seq: 0 } };\n      // Base init Cmds pass through unchanged; no telemetry Cmd on boot (boot is\n      // not a base Msg transition, so it does not advance `seq`).\n      return [model, cmds];\n    },\n    update: update as unknown as Reducer<\n      TelemetryModel<S>,\n      M,\n      C | TelemetryEmitCmd\n    >,\n    // Subs merge to the base's, verbatim — telemetry owns no timers. The base\n    // subscribes against its own nested slice.\n    ...(baseSubscriptions\n      ? {\n          subscriptions: (state: TelemetryModel<S>) =>\n            baseSubscriptions(state.base),\n        }\n      : {}),\n    ...(baseSubscribe ? { subscribe: baseSubscribe } : {}),\n    interpret,\n  } as Machine<\n    TelemetryModel<S>,\n    M,\n    C | TelemetryEmitCmd,\n    U,\n    Ctx & TelemetryPorts\n  >;\n}\n"]}

package/dist/work-queue/adapter.d.ts

@@ -0,0 +1,82 @@
+import { QueueItem } from './index.js';
+import '../index.js';
+import '../core-BoB6t7dB.js';
+
+/**
+ * @demlik/tea/work-queue/adapter — the verb seam over the pure queue ops.
+ *
+ * The pure ops in `./ops` are the BLESSED transitions, but their names and
+ * argument tuples (`enqueueOp(queue, input, now, id)`, `claimNextOp(queue,
+ * now)`, …) and their `{ next, item }` / `{ next, changed }` result shapes are
+ * the STORE's vocabulary, not the consumer's. An L2 composition that owns a
+ * `QueueItem<I>[]` slice (`monitored-run`, `saga`, `idempotent-intake`,
+ * `fan-out`) used to import those ops by name and call them directly, so a
+ * change to the op surface — or to `QueueItem`'s fields — cascaded to every
+ * call site.
+ *
+ * `QueueAdapter<I>` is the insulating interface: four VERBS (`enqueue` /
+ * `claim` / `markDone` / `patch`) that consumers depend on instead of the raw
+ * ops. The verbs keep the ops' pure `(queue, …) => { next, … }` contract — they
+ * are pure array transforms, no I/O, no `Date.now` (the clock is injected as
+ * `now`, exactly as the ops require it) — so a consumer folding the adapter
+ * through its reducer stays inside invariant 2 (pure transitions).
+ *
+ * `queueAdapter<I>()` is the canonical implementation, a thin binding of the
+ * blessed ops. Because the verbs are the only surface consumers touch, a
+ * `QueueItem` shape change (a new field, a renamed status, a different op
+ * signature) is now absorbed HERE — re-bind the verb once — rather than at the
+ * 4 consumer call sites. The `patch` verb deliberately takes the same
+ * `(item) => item` closure `patchItemOp` does, so the one place a `QueueItem`
+ * literal is spread stays the consumer's patch closure, never a re-rolled
+ * record.
+ *
+ * This is an INTERNAL seam (no public-API port): consumers import the adapter
+ * from this subpath the same way they imported the ops. The ops remain
+ * exported for the in-process `createQueue` adapter (`./index`) and for any
+ * call site that genuinely wants the op directly.
+ */
+
+/**
+ * The verb interface over a `QueueItem<I>[]` slice. Each verb mirrors a blessed
+ * op's pure contract but speaks the consumer's lifecycle vocabulary, so the
+ * consumer never names a `*Op` function or reaches into a `QueueItem` field it
+ * did not put there.
+ */
+interface QueueAdapter<I> {
+    /** Append a new `pending` item stamped `now` under `id`. */
+    enqueue(queue: readonly QueueItem<I>[], input: I, now: number, id: string): {
+        next: QueueItem<I>[];
+        item: QueueItem<I>;
+    };
+    /**
+     * Claim the first `pending` item — flip it `running`, stamp `startedAt` to
+     * `now` — or `null` if nothing is pending.
+     */
+    claim(queue: readonly QueueItem<I>[], now: number): {
+        next: QueueItem<I>[];
+        claimed: QueueItem<I>;
+    } | null;
+    /** Drop the item `id` from the queue (completed runs leave the queue). */
+    markDone(queue: readonly QueueItem<I>[], id: string): {
+        next: QueueItem<I>[];
+        changed: boolean;
+    };
+    /**
+     * Single-item transition: replace the item `id` with `patch(item)`. The
+     * closure is the only place a `QueueItem` literal is constructed, so the
+     * field shape stays out of the consumer's hands except through this verb.
+     */
+    patch(queue: readonly QueueItem<I>[], id: string, patch: (item: QueueItem<I>) => QueueItem<I>): {
+        next: QueueItem<I>[];
+        changed: boolean;
+    };
+}
+/**
+ * The canonical `QueueAdapter<I>`, binding each verb to its blessed op. Pure
+ * and stateless — call once at module scope in a consumer and fold its verbs
+ * through the reducer. A `QueueItem` shape change is absorbed by re-binding a
+ * verb here, not at the consumers.
+ */
+declare function queueAdapter<I>(): QueueAdapter<I>;
+
+export { type QueueAdapter, queueAdapter };

package/dist/work-queue/adapter.js

@@ -0,0 +1,4 @@
+export { queueAdapter } from '../chunk-HJO6VNQI.js';
+import '../chunk-TGG26XMK.js';
+//# sourceMappingURL=adapter.js.map
+//# sourceMappingURL=adapter.js.map

package/dist/work-queue/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"adapter.js"}

package/dist/work-queue/index.d.ts

@@ -1,11 +1,18 @@
 import { Store } from '../index.js';
+import '../core-BoB6t7dB.js';
 
 /**
  * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.
  *
- * The pure ops live in `./ops` and are NOT exported. Tests and consumers reach
- * them only through `createQueue(store)`. This mirrors `@demlik/tea/do`'s
- * one-shape-per-package rule: a single adapter is the public surface.
+ * Two public surfaces, one shape:
+ *   - `createQueue(store)` (this file) is the in-process adapter — it binds the
+ *     pure ops to an injected `Store` and runs `load → mutate → save`.
+ *   - `@demlik/tea/work-queue/ops` (`./ops`) is the BLESSED, importable surface
+ *     of those same pure ops. L2 compositions that own their own Model slice
+ *     (`monitored-run`, `idempotent-intake`, …) import the ops directly and
+ *     delegate status flips to them instead of re-rolling the transitions.
+ * Both routes call the identical ops, so the lifecycle rules live in exactly
+ * one place. This mirrors `@demlik/tea/do`'s one-shape-per-package rule.
  *
  * The package is generic in the input payload `I` (audit-specific fields go
  * here in apps/extension). `output` is a free-form side-channel correlation
@@ -15,15 +22,22 @@ import { Store } from '../index.js';
  */
 
 type QueueItemStatus = "pending" | "running" | "done" | "failed" | "cancelled";
+/**
+ * A single queue entry. Every field is `readonly`: a persisted slice is
+ * immutable, so a transition returns a NEW item (the ops always spread —
+ * `{ ...item, status: … }`) rather than mutating in place. This type-enforces
+ * the durability invariant the consumers already honor by convention, and
+ * keeps a slice round-trippable through JSON unchanged across a reload.
+ */
 interface QueueItem<I> {
-    id: string;
-    status: QueueItemStatus;
-    input: I;
-    enqueuedAt: number;
-    startedAt?: number;
-    finishedAt?: number;
-    output?: string;
-    error?: string;
+    readonly id: string;
+    readonly status: QueueItemStatus;
+    readonly input: I;
+    readonly enqueuedAt: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly output?: string;
+    readonly error?: string;
 }
 /**
  * Caller-facing enqueue payload. Just `I` today — kept named so future

package/dist/work-queue/index.js

@@ -1,49 +1,4 @@
-// src/work-queue/ops.ts
-function enqueueOp(queue, input, now, id) {
-  const item = {
-    id,
-    status: "pending",
-    input,
-    enqueuedAt: now
-  };
-  return { next: [...queue, item], item };
-}
-function claimNextOp(queue, now) {
-  const idx = queue.findIndex((i) => i.status === "pending");
-  if (idx === -1) return null;
-  const claimed = {
-    ...queue[idx],
-    status: "running",
-    startedAt: now
-  };
-  const next = queue.slice();
-  next[idx] = claimed;
-  return { next, claimed };
-}
-function markDoneOp(queue, id) {
-  const next = queue.filter((i) => i.id !== id);
-  return { next, changed: next.length !== queue.length };
-}
-function patchItemOp(queue, id, patch) {
-  const idx = queue.findIndex((i) => i.id === id);
-  if (idx === -1) return { next: queue.slice(), changed: false };
-  const next = queue.slice();
-  next[idx] = patch(queue[idx]);
-  return { next, changed: true };
-}
-function resetRunningOp(queue) {
-  let changed = false;
-  const next = queue.map((i) => {
-    if (i.status !== "running") return i;
-    changed = true;
-    return { ...i, status: "pending", startedAt: void 0 };
-  });
-  return { next, changed };
-}
-function removeOp(queue, id) {
-  const next = queue.filter((i) => i.id !== id);
-  return { next, changed: next.length !== queue.length };
-}
+import { enqueueOp, claimNextOp, markDoneOp, patchItemOp, resetRunningOp, removeOp } from '../chunk-TGG26XMK.js';
 
 // src/work-queue/index.ts
 function genId() {

package/dist/work-queue/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/work-queue/ops.ts","../../src/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Pure queue-lifecycle ops over `QueueItem<I>[]`.\n *\n * Each op is `(queue, ...args) => { next, result? }`. No I/O, no Date.now\n * indirection beyond a plain call site — the adapter in `./index.ts` injects\n * `Store<QueueItem<I>[]>` and orchestrates `load → mutate → save`.\n *\n * Substrate-agnostic by construction: nothing here references chrome.storage,\n * Cloudflare, or any concrete persistence layer. The audit-specific shape\n * (journeyId, projectId, ...) is lifted into the caller's `I` parameter.\n *\n * NOT exported from package root. Tests reach this file only through the\n * `createQueue(memoryStore(...))` adapter — same one-shape-per-package rule as\n * `@demlik/tea/do`.\n */\n\nimport type { QueueItem, QueueItemStatus } from \"./index\";\n\n/** Append a new pending item. Returns the new queue and the created item. */\nexport function enqueueOp<I>(\n  queue: readonly QueueItem<I>[],\n  input: I,\n  now: number,\n  id: string,\n): { next: QueueItem<I>[]; item: QueueItem<I> } {\n  const item: QueueItem<I> = {\n    id,\n    status: \"pending\",\n    input,\n    enqueuedAt: now,\n  };\n  return { next: [...queue, item], item };\n}\n\n/**\n * Claim the first pending item by flipping it to `running` and stamping\n * `startedAt`. Returns the new queue and the claimed item, or `null` if no\n * pending item exists.\n */\nexport function claimNextOp<I>(\n  queue: readonly QueueItem<I>[],\n  now: number,\n): { next: QueueItem<I>[]; claimed: QueueItem<I> } | null {\n  const idx = queue.findIndex((i) => i.status === \"pending\");\n  if (idx === -1) return null;\n  // `idx !== -1` guarantees the slot is present.\n  const claimed: QueueItem<I> = {\n    ...queue[idx]!,\n    status: \"running\",\n    startedAt: now,\n  };\n  const next = queue.slice();\n  next[idx] = claimed;\n  return { next, claimed };\n}\n\n/**\n * Done items leave the queue — completed runs live wherever the caller\n * persists their output. Returns the new queue (or the original reference if\n * no item matched, so the adapter can skip a save).\n */\nexport function markDoneOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n\n/**\n * Generic single-item status transition. Used by `markFailed`,\n * `markCancelled`, `retryItem`, `bindOutput`. The patch closure receives the\n * matched item and returns its replacement; returning the same reference is\n * fine (the adapter only saves on `changed`).\n */\nexport function patchItemOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n  patch: (item: QueueItem<I>) => QueueItem<I>,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const idx = queue.findIndex((i) => i.id === id);\n  if (idx === -1) return { next: queue.slice(), changed: false };\n  const next = queue.slice();\n  // `idx !== -1` guarantees the slot is present.\n  next[idx] = patch(queue[idx]!);\n  return { next, changed: true };\n}\n\n/** Reset every `running` item back to `pending`, clearing `startedAt`. */\nexport function resetRunningOp<I>(queue: readonly QueueItem<I>[]): {\n  next: QueueItem<I>[];\n  changed: boolean;\n} {\n  let changed = false;\n  const next = queue.map((i) => {\n    if (i.status !== \"running\") return i;\n    changed = true;\n    return { ...i, status: \"pending\" as QueueItemStatus, startedAt: undefined };\n  });\n  return { next, changed };\n}\n\n/** Hard-delete an item regardless of status. */\nexport function removeOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n","/**\n * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * The pure ops live in `./ops` and are NOT exported. Tests and consumers reach\n * them only through `createQueue(store)`. This mirrors `@demlik/tea/do`'s\n * one-shape-per-package rule: a single adapter is the public surface.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in apps/extension). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../index\";\nimport { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp } from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ?? `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\nexport type QueueItemStatus = \"pending\" | \"running\" | \"done\" | \"failed\" | \"cancelled\";\n\nexport interface QueueItem<I> {\n  id: string;\n  status: QueueItemStatus;\n  input: I;\n  enqueuedAt: number;\n  startedAt?: number;\n  finishedAt?: number;\n  output?: string;\n  error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — same wiring the substrate's `run()` uses at\n  // boot. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  async function loadParsed(): Promise<QueueItem<I>[] | null> {\n    const raw = await store.load();\n    return store.migrate(raw);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}
+{"version":3,"sources":["../../src/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * Two public surfaces, one shape:\n *   - `createQueue(store)` (this file) is the in-process adapter — it binds the\n *     pure ops to an injected `Store` and runs `load → mutate → save`.\n *   - `@demlik/tea/work-queue/ops` (`./ops`) is the BLESSED, importable surface\n *     of those same pure ops. L2 compositions that own their own Model slice\n *     (`monitored-run`, `idempotent-intake`, …) import the ops directly and\n *     delegate status flips to them instead of re-rolling the transitions.\n * Both routes call the identical ops, so the lifecycle rules live in exactly\n * one place. This mirrors `@demlik/tea/do`'s one-shape-per-package rule.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in apps/extension). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../index\";\nimport {\n  claimNextOp,\n  enqueueOp,\n  markDoneOp,\n  patchItemOp,\n  removeOp,\n  resetRunningOp,\n} from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ??\n    `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\nexport type QueueItemStatus =\n  | \"pending\"\n  | \"running\"\n  | \"done\"\n  | \"failed\"\n  | \"cancelled\";\n\n/**\n * A single queue entry. Every field is `readonly`: a persisted slice is\n * immutable, so a transition returns a NEW item (the ops always spread —\n * `{ ...item, status: … }`) rather than mutating in place. This type-enforces\n * the durability invariant the consumers already honor by convention, and\n * keeps a slice round-trippable through JSON unchanged across a reload.\n */\nexport interface QueueItem<I> {\n  readonly id: string;\n  readonly status: QueueItemStatus;\n  readonly input: I;\n  readonly enqueuedAt: number;\n  readonly startedAt?: number;\n  readonly finishedAt?: number;\n  readonly output?: string;\n  readonly error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — same wiring the substrate's `run()` uses at\n  // boot. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  async function loadParsed(): Promise<QueueItem<I>[] | null> {\n    const raw = await store.load();\n    return store.migrate(raw);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}

package/dist/work-queue/ops.d.ts

@@ -0,0 +1,69 @@
+import { QueueItem } from './index.js';
+import '../index.js';
+import '../core-BoB6t7dB.js';
+
+/**
+ * Pure queue-lifecycle ops over `QueueItem<I>[]` — the BLESSED delegation
+ * surface for this package.
+ *
+ * Each op is `(queue, ...args) => { next, result? }`. No I/O, no Date.now
+ * indirection beyond a plain call site — the adapter in `./index.ts` injects
+ * `Store<QueueItem<I>[]>` and orchestrates `load → mutate → save`.
+ *
+ * Substrate-agnostic by construction: nothing here references chrome.storage,
+ * Cloudflare, or any concrete persistence layer. The audit-specific shape
+ * (journeyId, projectId, ...) is lifted into the caller's `I` parameter.
+ *
+ * Importable two ways. The `createQueue(...)` adapter in `./index.ts` binds
+ * these ops to a `Store` for in-process use (same one-shape-per-package rule
+ * as `@demlik/tea/do`). L2 compositions that own their own Model slice
+ * (`monitored-run`, `idempotent-intake`, …) instead reach these ops directly
+ * via the `@demlik/tea/work-queue/ops` subpath, so a status flip is delegated
+ * here rather than re-rolled per call site.
+ */
+
+/** Append a new pending item. Returns the new queue and the created item. */
+declare function enqueueOp<I>(queue: readonly QueueItem<I>[], input: I, now: number, id: string): {
+    next: QueueItem<I>[];
+    item: QueueItem<I>;
+};
+/**
+ * Claim the first pending item by flipping it to `running` and stamping
+ * `startedAt`. Returns the new queue and the claimed item, or `null` if no
+ * pending item exists.
+ */
+declare function claimNextOp<I>(queue: readonly QueueItem<I>[], now: number): {
+    next: QueueItem<I>[];
+    claimed: QueueItem<I>;
+} | null;
+/**
+ * Done items leave the queue — completed runs live wherever the caller
+ * persists their output. Returns the new queue (or the original reference if
+ * no item matched, so the adapter can skip a save).
+ */
+declare function markDoneOp<I>(queue: readonly QueueItem<I>[], id: string): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+/**
+ * Generic single-item status transition. Used by `markFailed`,
+ * `markCancelled`, `retryItem`, `bindOutput`. The patch closure receives the
+ * matched item and returns its replacement; returning the same reference is
+ * fine (the adapter only saves on `changed`).
+ */
+declare function patchItemOp<I>(queue: readonly QueueItem<I>[], id: string, patch: (item: QueueItem<I>) => QueueItem<I>): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+/** Reset every `running` item back to `pending`, clearing `startedAt`. */
+declare function resetRunningOp<I>(queue: readonly QueueItem<I>[]): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+/** Hard-delete an item regardless of status. */
+declare function removeOp<I>(queue: readonly QueueItem<I>[], id: string): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+
+export { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp };

package/dist/work-queue/ops.js

@@ -0,0 +1,3 @@
+export { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp } from '../chunk-TGG26XMK.js';
+//# sourceMappingURL=ops.js.map
+//# sourceMappingURL=ops.js.map

package/dist/work-queue/ops.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"ops.js"}