@matatbread/matbot-core 0.4.3 → 0.4.4

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.3",
+  "version": "0.4.4",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.3"
+    "@matatbread/matbot-plugin-api": "^0.4.4"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/index.ts

@@ -28,13 +28,13 @@ export {
   unifyServices, forwardingProxy, makeSwappable, singleTurnRequest, createMountTable,
   createBroadcaster, subscribable, createNotifier, scopedNotifier,
   installPrincipalCarrier, enterPrincipal, createConstantPrincipalCarrier,
-  contextSwitch, onContextQuiesce, flushIfQuiescent,
+  contextSwitch, machineBusy, quiesced, onContextQuiesce, flushIfQuiescent,
   installUsageCarrier, createSerialUsageCarrier, recordUsage, recordSpan, currentUsageSink,
   currentUsageScope, currentUsageSite, withUsageScope, withUsageSite,
 } from '@matatbread/matbot-plugin-api/host';
 export type {
   Subscribable, Broadcaster, Routed, RoutedFilter, SwapFn, MountTable, PrincipalCarrier, UsageCarrier,
-  UsageScope,
+  UsageScope, Quiescer,
 } from '@matatbread/matbot-plugin-api/host';
 export * from './session.js';
 export * from './usage.js';

package/src/session-runner.ts

@@ -8,8 +8,8 @@ import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
 import type { ToolTypeIndex, ToolPresenter } from '@matatbread/matbot-plugin-api';
 import { appendMessage, createMessage } from './session.js';
-import { isReadOnlyError, foldOntoUserTurn, lastUserIndex } from '@matatbread/matbot-plugin-api';
-import { contextSwitch, withUsageScope } from '@matatbread/matbot-plugin-api/host';
+import { isReadOnlyError, foldOntoUserTurn, lastUserIndex, runAs } from '@matatbread/matbot-plugin-api';
+import { machineBusy, quiesced, withUsageScope } from '@matatbread/matbot-plugin-api/host';
 import { runSession } from './runner.js';
 
 export interface SessionRunnerDeps {
@@ -255,6 +255,21 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
   const pump = async (id: string, s: SessionState): Promise<void> => {
     if (s.running) return;
     s.running = true;
+    // Hold the machine for the WHOLE queue, not per turn. A deferred machine mutation (the
+    // StorageBackend swap, a plugin's deferred edit of this very session) may only land where no
+    // operation spans it — and the pump's own store work does not stop at a turn's end: it reads the
+    // committed document back for followup, appends markers to it, rewrites it for a retract, and
+    // persists the next turn's user message before that turn opens. All of that sits between turns,
+    // and a per-turn hold declared it idle. The queue draining is the real boundary — the same one
+    // usage flushes at, for the same reason. `machineBusy` releases on every exit including a throw,
+    // so no early return out of the loop below can leave the machine held.
+    //
+    // Wait out any deferred work still settling BEFORE holding: a flusher that rewrites this very
+    // session (a `session_edit` deferred out of the last turn) must finish before this turn reads its
+    // copy, or the read would take the pre-edit document and the write-back below would put it back.
+    // The edge is only reachable while nothing holds the machine, so the wait comes first and the
+    // hold second — the reverse would deadlock on an edge this pump is itself preventing.
+    return quiesced().then(() => machineBusy(async () => {
     try {
       while (s.queue.length > 0) {
         // Per-submission concat: the head always runs; if the head is a concat submission it absorbs
@@ -350,8 +365,8 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // turn's async root. Everything downstream (hooks, tools, and any Store/FileStore/Vault
           // access they trigger) reads it via currentPrincipal(). The consumption MUST happen inside
           // the callback: an async iterator returned out of the scope would lose it before it pulls.
-          // contextSwitch (not bare runAs): a turn is the transactional unit, so a StorageBackend swap
-          // deferred during it lands at this scope's quiescent edge — never mid-CAS.
+          // runAs, not a context switch of its own: the pump holds the machine across the whole queue
+          // (see above), so a turn declares only its owner. Each item carries its own submitter.
           // The terminal event this turn ended on. `followup` is post-COMMIT, and only `done` is a
           // commit: an `aborted` turn was cut short (a steer, a user cancel, a screen/toolcall hook
           // refusing it, a provider round ceiling) and an `error` turn produced no response at all, so
@@ -367,7 +382,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // in something already tracked and needs no coordination of its own.
           await withUsageScope(async usage => {
           s.pendingUsage.push(usage.entries);
-          await contextSwitch(head.principal, async () => {
+          await runAs(head.principal, async () => {
             for await (const ev of runSession({
               session,
               config:         { provider: head.provider, traceId: head.traceId },
@@ -403,7 +418,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
             const committed = await deps.store.get(id);
             if (committed && head.resubmitDepth < MAX_RESUBMIT_DEPTH) {
               let followup: { resubmits: MessageContent[][]; markers: MessageContent[]; retract?: { context: MessageContent[]; durable: MessageContent[] } } = { resubmits: [], markers: [] };
-              await contextSwitch(head.principal, async () => {
+              await runAs(head.principal, async () => {
                 followup = await hooks.runFollowup({
                   session:       committed,
                   resubmitDepth: head.resubmitDepth,
@@ -530,6 +545,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
       notify(s, { type: 'idle', sessionId: id });
       maybeCleanup(id, s);
     }
+    }));
   };
 
   return {

package/src/storage-base/caching-backend.ts

@@ -138,9 +138,22 @@ export class CachingStorageBackend implements StorageBackend {
   private readonly ttlMs:  number | undefined;
   private readonly stores = new Map<string, CachingStore<{ id: string; version: string }>>();
 
+  /**
+   * Forwarded only when the wrapped backend has it. `namespaces` is optional, and its ABSENCE is the
+   * signal a caller reads ("this backend cannot be enumerated") — so a decorator that always declared
+   * the method would answer for backends that cannot, turning a degradable capability into a runtime
+   * failure. Assigned per instance rather than declared as a method so `'namespaces' in backend` stays
+   * truthful through the wrapper.
+   *
+   * Not cached: the cache is per-namespace and populated by reads, so it knows only what has been
+   * asked for — never the set of namespaces that exist.
+   */
+  readonly namespaces?: () => Promise<string[]>;
+
   constructor(inner: StorageBackend, options: CachingOptions = {}) {
     this.inner = inner;
     this.ttlMs = options.ttlMs;
+    if (inner.namespaces !== undefined) this.namespaces = () => inner.namespaces!();
   }
 
   createStore<T extends { id: string; version: string }>(namespace: string): Store<T> {

package/src/storage-base/index.ts

@@ -1,2 +1,3 @@
 export * from './query/index.js';
 export { CachingStorageBackend, type CachingOptions, type CacheNamespaceStats } from './caching-backend.js';
+export { mediumGuard } from './medium-guard.js';

package/src/storage-base/medium-guard.ts

@@ -0,0 +1,114 @@
+import type { Store, CASResult, StoreQuery, QueryResult } from '@matatbread/matbot-plugin-api';
+
+/**
+ * Fail a write whose read came from a different storage medium.
+ *
+ * Exactly one `StorageBackend` is active, nothing is migrated between them, and a swap repoints every
+ * store proxy at once. A caller that read a document before the swap and writes it after is therefore
+ * addressing two different media with one read-modify-write, and neither end can tell: `cas` asks
+ * "did this document change?", which the new backend answers about a document it never issued — most
+ * often "there is nothing here", at which point an unconditional `set` writes the old backend's
+ * document into the new one and the session has silently migrated. Compare-and-swap cannot see this,
+ * because the medium is not what it compares.
+ *
+ * The fix belongs here rather than at whatever happened to be running: the exposure is not particular
+ * to the quiescent edge's deferred work — an HTTP tool call has always been able to straddle a swap
+ * the same way — so pushing the check up to every caller would be asking each of them to know
+ * something only storage knows.
+ *
+ * The version is the only token tying a read to its write, so it carries the medium: stamped on the
+ * way out, checked and stripped on the way in. Stripping is what keeps it invisible — a caller that
+ * writes a document straight back (`store.set(id, { ...doc, title })`, which does not bump the
+ * version) must not persist a stamp, or the next read would stamp it twice.
+ *
+ * An UNstamped version is always accepted: that is a document the caller minted rather than read, and
+ * a create has no earlier medium to disagree with.
+ */
+
+const STAMP = /^m(\d+)~([\s\S]*)$/;
+
+interface Stamped { id: string; version: string }
+
+function stamp<T extends Stamped>(doc: T, generation: number): T {
+  return { ...doc, version: `m${generation}~${doc.version}` };
+}
+
+type Checked =
+  | { ok: true; version: string }
+  | { ok: false; from: number };
+
+function check(version: string, generation: number): Checked {
+  const m = STAMP.exec(version);
+  if (m === null)                      return { ok: true, version };            // minted, not read
+  if (Number(m[1]) === generation)     return { ok: true, version: m[2]! };
+  return { ok: false, from: Number(m[1]) };
+}
+
+/** Strip a stamp wherever one appears, so nothing a caller hands back is persisted with one. */
+function strip<T extends Stamped>(doc: T): T {
+  const m = STAMP.exec(doc.version);
+  return m === null ? doc : { ...doc, version: m[2]! };
+}
+
+/**
+ * Wrap `inner` so every document it hands out is stamped with the medium generation it came from, and
+ * every write is checked against the generation current at the time of the write. `generation` must
+ * increase on every backend swap; the wrapper is placed OUTSIDE the swap proxy, so it is one stable
+ * object across every swap and a captured store reference keeps working.
+ */
+export function mediumGuard<T extends { id: string; version: string }>(
+  inner:      Store<T>,
+  generation: () => number,
+  namespace:  string,
+): Store<T> {
+  const stale = (op: string, id: string, from: number): string =>
+    `${op} on "${namespace}/${id}" read from storage backend generation ${from}, but generation ${generation()} is now active. ` +
+    'Nothing is migrated between backends, so this write would put a document from the previous one into its replacement. Re-read and retry.';
+
+  return {
+    async get(id) {
+      const doc = await inner.get(id);
+      return doc === null ? null : stamp(doc, generation());
+    },
+
+    async query(q: StoreQuery): Promise<QueryResult<T>> {
+      const page = await inner.query(q);
+      const gen  = generation();
+      return { ...page, items: page.items.map(d => stamp(d, gen)) };
+    },
+
+    async set(id, value) {
+      const seen = check(value.version, generation());
+      // `set` has no failure channel, and silence is what makes the migration invisible — so it
+      // throws. It is reachable only after a swap, holding a document read before it.
+      if (!seen.ok) throw new Error(stale('set', id, seen.from));
+      await inner.set(id, strip(value));
+    },
+
+    async cas(id, expected, next): Promise<CASResult<T>> {
+      const seen = check(expected, generation());
+      // Reported as a lost CAS rather than thrown: the caller already has a path for "someone else got
+      // there first", and this is that, with the medium in the role of the other writer. `current` is
+      // read from the backend now in force — the document the caller must reconcile against.
+      if (!seen.ok) {
+        console.warn(`[matbot] ${stale('cas', id, seen.from)}`);
+        const current = await inner.get(id);
+        return { ok: false, current: current === null ? null : stamp(current, generation()) };
+      }
+      const res = await inner.cas(id, seen.version, strip(next));
+      const gen = generation();
+      if (res.ok) return { ok: true, doc: stamp(res.doc, gen) };
+      return { ok: false, current: res.current === null ? null : stamp(res.current, gen) };
+    },
+
+    async delete(id, expectedVersion) {
+      if (expectedVersion === undefined) return inner.delete(id);
+      const seen = check(expectedVersion, generation());
+      if (!seen.ok) {
+        console.warn(`[matbot] ${stale('delete', id, seen.from)}`);
+        return false;
+      }
+      return inner.delete(id, seen.version);
+    },
+  };
+}