@matatbread/matbot-plugin-api 0.3.7 → 0.4.0

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.3.7",
+  "version": "0.4.0",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -22,7 +22,8 @@
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./host": "./src/host.ts"
   },
   "repository": {
     "type": "git",

package/src/hooks.ts

@@ -1,11 +1,12 @@
 import type {
-  Hook, HookPoint, Message, MessageContent, Session, DeferredScreen,
+  Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
 } from './types.js';
+import { foldOntoUserTurn } from './session.js';
 
 const HOOK_ERROR_CREATOR = 'matbot-hooks';
 
-export class HookRegistry {
+export class HookRegistry implements HookRegistrar {
   private readonly hooks = new Map<HookPoint, Hook[]>();
 
   // A hook handler that *throws* is a failure, not an intentional stop (which is a return value:
@@ -111,11 +112,10 @@ export class HookRegistry {
     // so a user message is present in practice; this is defensive).
     const durable: MessageContent[] = [];
     const foldDurable = (blocks: MessageContent[]): void => {
-      const idx = session.messages.findLastIndex(m => m.role === 'user');
-      if (idx < 0) return;
+      const folded = foldOntoUserTurn(session, blocks);
+      if (folded === session) return;      // no user message to attach to — dropped, not orphaned
       durable.push(...blocks);
-      session = { ...session, messages: session.messages.map((m, i) =>
-        i === idx ? { ...m, content: [...m.content, ...blocks] } : m) };
+      session = folded;
     };
     for (const hook of this.hooks.get('screen') ?? []) {
       if (hook.on !== 'screen') continue;

package/src/host-machine.ts

@@ -0,0 +1,191 @@
+import type {
+  CompletionRequest, MatbotMachine, MatbotServices, Mounted, MountConsumeOptions, SingleTurnRequest,
+} from './plugin.js';
+
+/*
+ * Host-side machine assembly — the wiring an *embedder* does once at boot, not API a plugin author
+ * writes against. It lives behind `@matatbread/matbot-plugin-api/host` so the package root can answer
+ * exactly one question: what does a plugin need in order to be a plugin? Publishing these at the root
+ * made boot mechanics look like stable author-facing surface, and no plugin in this repo imports one.
+ *
+ * Split out of plugin.ts as a *file* boundary rather than an export list, so the distinction cannot
+ * quietly erode the next time something is added. The plugin-facing halves of the same subsystems stay
+ * where they are: `Mounted`/`MountConsumeOptions` (the contract of `services.mounted`) in plugin.ts,
+ * `runAs`/`currentPrincipal` in principal-context.ts.
+ */
+
+/**
+ * Wrap a services object so every registered service is reachable as a member (`services.InterfaceName`),
+ * not only via `services.get('InterfaceName')` — one access surface for base members and plugin-registered
+ * services alike. A member read of a key the object doesn't carry falls back to its own `get()` (the
+ * registry), so the augmentation that declares `InterfaceName?: InterfaceName` is also the access path;
+ * the optional `?` is the single call-site signal of "may be absent, null-check it". Assignment throws,
+ * directing callers to `register()` (the swap-aware write path). Applied to both the host services object
+ * and the per-plugin scoped object, so plugins see the same surface the host does.
+ *
+ * Only `get` and `set` are trapped. `has` used to fall through to the registry too, which made the plain
+ * language construct `'Foo' in services` perform a registry lookup — no side effect, but a surprise, and
+ * inconsistent with `ownKeys`, which never listed registered services. `in` is therefore structural, and
+ * the presence check remains the documented one: `services.Foo !== undefined`, or `?.`.
+ */
+export function unifyServices(services: MatbotMachine): MatbotMachine {
+  return new Proxy(services, {
+    get(target, key, receiver) {
+      if (Reflect.has(target, key)) return Reflect.get(target, key, receiver);
+      return typeof key === 'string' ? target.get(key as keyof MatbotServices) : undefined;
+    },
+    set(_target, key) {
+      throw new Error(
+        `Cannot assign services.${String(key)} directly — use services.register('${String(key)}', impl) to register or replace a service.`,
+      );
+    },
+  });
+}
+// ── Capture-safe swap proxies ───────────────────────────────────────────────────
+
+export type SwapFn<T extends object> = (next: T) => void;
+
+/**
+ * A capture-safe forwarding proxy: every trap routes to whatever `getCurrent()` returns *now*, so a
+ * reference captured before a register()-driven swap keeps resolving to the live impl. getPrototypeOf
+ * is forwarded so `instanceof` sees the real impl (the StorageBackend identity checks depend on it);
+ * ownKeys + getOwnPropertyDescriptor keep object spread faithful. Methods bind to the current impl,
+ * not the proxy. A nullish current (an optional service with nothing registered yet) reads as empty.
+ */
+export function forwardingProxy<T extends object>(getCurrent: () => T | undefined): T {
+  return new Proxy({} as T, {
+    get(_t, prop) {
+      const cur = getCurrent();
+      if (cur === undefined) return undefined;
+      const val = Reflect.get(cur, prop, cur);
+      return typeof val === 'function' ? (val as (...a: unknown[]) => unknown).bind(cur) : val;
+    },
+    has(_t, prop)    { const cur = getCurrent(); return cur !== undefined && Reflect.has(cur, prop); },
+    getPrototypeOf() { const cur = getCurrent(); return cur === undefined ? null : Reflect.getPrototypeOf(cur); },
+    ownKeys()        { const cur = getCurrent(); return cur === undefined ? [] : Reflect.ownKeys(cur); },
+    getOwnPropertyDescriptor(_t, prop) {
+      const cur = getCurrent();
+      if (cur === undefined) return undefined;
+      const d = Reflect.getOwnPropertyDescriptor(cur, prop);
+      if (d !== undefined) d.configurable = true; // Proxy invariant: props absent from the {} target must be configurable.
+      return d;
+    },
+  });
+}
+
+/**
+ * Returns [proxy, swap]: the Store/FileStore handle plugins capture, plus the fn register() calls to
+ * repoint it at a new backend's store. Built on forwardingProxy so capture-safety is uniform.
+ */
+export function makeSwappable<T extends object>(initial: T): [T, SwapFn<T>] {
+  let current = initial;
+  return [forwardingProxy<T>(() => current), (next: T) => { current = next; }];
+}
+
+// ── Mount table (host half) ──────────────────────────────────
+
+/** The host-side mount table: {@link Mounted} for plugins, plus the producer half the host drives from
+ *  its register/unregister and quiescent-edge flush. */
+export interface MountTable {
+  readonly mounted: Mounted;
+  /** Record that a key's presence may have changed since the last edge (called by register/unregister). */
+  markDirty(key: keyof MatbotServices): void;
+  /** At a quiescent edge, compute each dirty key's net presence transition and multicast it. */
+  flush(): void;
+}
+
+interface MountInterest {
+  readonly handler:   (machine: MatbotMachine) => void | Promise<void>;
+  readonly onUnmount: ((machine: MatbotMachine) => void | Promise<void>) | undefined;
+  readonly signal:    AbortSignal | undefined;
+}
+
+function reportMountHandlerError(e: unknown): void {
+  console.error('[matbot] mounted handler threw:', e instanceof Error ? e.message : e);
+}
+
+/**
+ * Build a {@link MountTable} over a lazily-read machine. Notifications batch to the quiescent edge
+ * ({@link flush}), where each dirty key's net presence (absent→present = mount, present→present =
+ * remount, present→absent = committed unload) is multicast to that key's subscribers. The clock holds
+ * the last-committed presence per key, so a reload collapses to one remount and a committed unload is
+ * well-defined. Presence is read by member access on the unified machine, which resolves both the core
+ * getters (StorageBackend/Vault/KnowledgeIndex) and the registry-backed augmented keys.
+ */
+export function createMountTable(getMachine: () => MatbotMachine): MountTable {
+  const interests = new Map<string, Set<MountInterest>>();
+  const committed = new Map<string, boolean>();   // last-committed presence per key (the clock)
+  const dirty     = new Set<string>();
+
+  const present = (key: string): boolean => (getMachine() as unknown as Record<string, unknown>)[key] !== undefined;
+
+  const run = (fn: (machine: MatbotMachine) => void | Promise<void>, machine: MatbotMachine): void => {
+    try {
+      const r = fn(machine);
+      if (r instanceof Promise) r.catch(reportMountHandlerError);
+    } catch (e) { reportMountHandlerError(e); }
+  };
+
+  const mounted: Mounted = {
+    observe(options, handler) {
+      const { key, replay, signal, onUnmount } = options;
+      if (signal?.aborted === true) return;
+      const interest: MountInterest = {
+        handler:   handler as MountInterest['handler'],
+        onUnmount: onUnmount as MountInterest['onUnmount'],
+        signal,
+      };
+      let set = interests.get(key);
+      if (set === undefined) { set = new Set(); interests.set(key, set); }
+      const subs = set;
+      subs.add(interest);
+      signal?.addEventListener('abort', () => { subs.delete(interest); }, { once: true });
+      // Replay on the next microtask (async-iterator parity — never inline in the consume() frame).
+      // Reads the live machine, not `committed`: replay is "current state", separate from the clock.
+      if (replay === true) queueMicrotask(() => {
+        if (signal?.aborted === true) return;
+        if (present(key as string)) run(interest.handler, getMachine());
+      });
+    },
+  };
+
+  return {
+    mounted,
+    markDirty(key) { dirty.add(key as string); },
+    flush() {
+      if (dirty.size === 0) return;
+      const keys = [...dirty];
+      dirty.clear();
+      const machine = getMachine();
+      for (const key of keys) {
+        const before = committed.get(key) ?? false;
+        const after  = present(key);
+        committed.set(key, after);
+        const subs = interests.get(key);
+        if (subs === undefined) continue;
+        if (after) {
+          for (const i of subs) run(i.handler, machine);                                  // mount / remount
+        } else if (before) {
+          for (const i of subs) if (i.onUnmount !== undefined) run(i.onUnmount, machine);  // committed unload
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Build the one-message CompletionRequest for a {@link MatbotRuntime.singleTurn} call, hiding the
+ * otherwise-mandatory and meaningless Message fields (id/traceId/createdAt) an out-of-band one-shot
+ * has no use for. Pure; the host invokes its own complete() with the result.
+ */
+export function singleTurnRequest(req: SingleTurnRequest): CompletionRequest {
+  return {
+    provider: req.provider,
+    messages: [{
+      id: '', traceId: '', createdAt: new Date().toISOString(), role: 'user',
+      content: [{ type: 'text', text: req.prompt }],
+    }],
+    ...(req.system !== undefined ? { system: req.system } : {}),
+    ...(req.signal !== undefined ? { signal: req.signal } : {}),
+  };
+}

package/src/host.ts

@@ -0,0 +1,43 @@
+/*
+ * `@matatbread/matbot-plugin-api/host` — the boot-time wiring an *embedder* performs to stand a machine
+ * up, as opposed to what a *plugin* is written against.
+ *
+ * The package root used to export both, which made carrier installers, swap proxies, the mount table and
+ * the hook registry implementation look like stable author-facing API. They are not: no plugin in this
+ * repo imports one, and only `apps/*` and `core` ever did. Splitting them here lets the root answer one
+ * question — what does a plugin need in order to be a plugin? — and lets these change without it being a
+ * plugin-API break.
+ *
+ * Three of these subsystems are deliberately *split* rather than moved whole, because each has a genuine
+ * author-facing half that stays at the root:
+ *   - principal: `runAs` / `currentPrincipal` / `tryCurrentPrincipal` are read and established by plugins
+ *     (a frontend scopes each inbound message); only *installing the carrier* is the host's job.
+ *   - notifications: every plugin publishes and consumes; only *minting* the process notifier is the host's.
+ *   - mount table: `services.mounted` (`Mounted`, `MountConsumeOptions`) is the plugin contract; the
+ *     producer half (`MountTable`, `markDirty`/`flush`) is driven by the host's register/quiescent edge.
+ *
+ * `core` re-exports everything here, so a host that already depends on `@matatbread/matbot-core` needs no
+ * direct import of this subpath.
+ */
+
+// Machine assembly: member-access unification, capture-safe swap proxies, the mount table's producer
+// half, and the one-shot CompletionRequest builder behind MatbotRuntime.singleTurn.
+export * from './host-machine.js';
+
+// Ambient scope carriers. The host installs a platform impl once at boot (node: AsyncLocalStorage;
+// browser/single-principal: a constant carrier) and never touches them again.
+export { installPrincipalCarrier, enterPrincipal, createConstantPrincipalCarrier } from './principal-context.js';
+export type { PrincipalCarrier } from './principal-context.js';
+export * from './usage-context.js';
+
+// The machine half of a context switch: quiescent-edge flushers and the deferred-swap application point.
+export * from './context-switch.js';
+
+// Hook dispatch implementation. Plugins register hooks through `services.hooks`; only the host constructs
+// the registry that backs it.
+export { HookRegistry } from './hooks.js';
+
+// The multi-subscriber fan-out primitive under `Notifier`. A plugin that wants to publish an event uses
+// the Notifier — that is the sanctioned path, and the reason this stays host-side.
+export * from './broadcast.js';
+export { createNotifier, scopedNotifier } from './notify.js';

package/src/index.ts

@@ -1,13 +1,32 @@
+/*
+ * `@matatbread/matbot-plugin-api` — everything a plugin author needs, and nothing a host needs to *build*
+ * a machine. Boot wiring (carrier installers, swap proxies, the mount table's producer half, the hook
+ * registry impl, the broadcaster) lives behind the `/host` subpath; see host.ts for the reasoning.
+ *
+ * Star-exported where a file is wholly plugin-facing; enumerated where a file is deliberately split. The
+ * two enumerated cases use `export type *` for the shapes plus a named list of runtime values, so a new
+ * *type* flows out automatically and a new *value* is a decision someone has to make here.
+ */
+
 export type * from './types.js';
-export { CONFIRM_YES, CONFIRM_NO } from './types.js';
+export { CONFIRM_YES, CONFIRM_NO, isTruncatedToolResult } from './types.js';
+
 export * from './store-query.js';
-export * from './vault.js';
 export * from './errors.js';
-export * from './principal-context.js';
-export * from './usage-context.js';
+export * from './vault.js';
 export * from './session.js';
-export * from './context-switch.js';
-export * from './hooks.js';
-export * from './plugin.js';
-export * from './broadcast.js';
 export * from './invoke-tool.js';
+
+// The plugin half of the machine: MatbotPlugin/MatbotServices/MatbotRuntime, the mount-table *consumer*
+// contract, and the API version a plugin declares. Host assembly is in ./host-machine.ts.
+export type * from './plugin.js';
+export { PLUGIN_API_VERSION } from './plugin.js';
+
+// Ambient principal: read it, or establish one for an inbound request/message. Installing the carrier is
+// the host's job (`/host`).
+export { currentPrincipal, tryCurrentPrincipal, runAs } from './principal-context.js';
+
+// Notifications: publish, consume, and the two kinds plugin-api itself defines. Minting the process
+// notifier is the host's job (`/host`).
+export type * from './notify.js';
+export { ItemChangeKind, RegistryChangeKind, notifyingStore } from './notify.js';

package/src/invoke-tool.ts

@@ -1,6 +1,29 @@
-import type { MatbotMachine } from './plugin.js';
+import type { MatbotMachine, MatbotPlugin } from './plugin.js';
 import type { ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField } from './types.js';
 
+/** The host's plugin hot-load ops, as both the runner and {@link invokeTool} hold them. */
+export interface PluginOps {
+  loadPlugin(specifier: string, prompt?: PromptFn, refresh?: boolean): Promise<MatbotPlugin>;
+  unloadPlugin(specifier: string): Promise<boolean>;
+}
+
+/**
+ * Bind the plugin hot-load ops for a {@link ToolContext}, closing over the turn's `prompt`.
+ *
+ * That closure is the whole point of `ToolContext.loadPlugin` existing alongside
+ * `MatbotRuntime.loadPlugin`: a tool cannot forget to pass the prompt, so an interactive load cannot
+ * silently become non-interactive at one call site out of six — the same reasoning that makes the
+ * principal ambient rather than threaded. What it should not be is written out twice, once in the runner
+ * and once here, since the injected middle argument is exactly the shape a signature change breaks
+ * quietly.
+ */
+export function bindPluginOps(host: PluginOps, prompt: PromptFn): Pick<ToolContext, 'loadPlugin' | 'unloadPlugin'> {
+  return {
+    loadPlugin:   (specifier, refresh) => host.loadPlugin(specifier, prompt, refresh),
+    unloadPlugin: (specifier)          => host.unloadPlugin(specifier),
+  };
+}
+
 /**
  * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
  * forwarding a call to another tool should pass its own {@link ToolContext} straight through as
@@ -41,8 +64,7 @@ export function invokeTool<K extends string, const P>(
     signal:       opts.signal,
     vault:        machine.Vault,
     prompt,
-    loadPlugin:   (specifier, refresh) => machine.loadPlugin(specifier, prompt, refresh),
-    unloadPlugin: (specifier) => machine.unloadPlugin(specifier),
+    ...bindPluginOps(machine, prompt),
     ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
     ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),
     ...(machine.configPath !== undefined ? { configPath: machine.configPath } : {}),

package/src/notify.ts

@@ -0,0 +1,242 @@
+import type { Principal, Store } from './types.js';
+import { createBroadcaster } from './broadcast.js';
+import { tryCurrentPrincipal } from './principal-context.js';
+
+/**
+ * What every notification carries, whoever produced it and however it arrived.
+ *
+ * Two independent axes ride here, and conflating them is the mistake this shape exists to prevent:
+ *
+ *   - **attribution** — `instance`/`plugin`/`source`: who *produced* the fact. Drives per-producer
+ *     filtering, and lets a bridge suppress its own echo.
+ *   - **ownership** — `principal`: whose *data* the fact is about. This is the visibility axis, the
+ *     input to `WatchVisibility.visible`. A notification with no principal is a global fact.
+ *
+ * A producer never sets `instance`: undefined means "this matbot". A bridge stamps it on ingress, so a
+ * forwarded event stays attributable to the server that produced it and never loops back out.
+ *
+ * `kind` is deliberately absent here: it is not something an arm declares but something its
+ * {@link Notifications} key *is*, grafted on by {@link Notification}. Declaring it on the arm as well
+ * would be the same string written twice with nothing keeping the two honest.
+ */
+export interface NotificationBase {
+  /** Producing plugin's name; `core` is reserved for the host and core itself. Defaulted from the
+   *  emitting plugin's scope, so an ordinary producer never sets it. It stays overridable rather than
+   *  enforced because relaying another producer's event is a legitimate act — that is exactly what a
+   *  bridge does with a notification it received from another instance. */
+  readonly plugin:     string;
+  /** Producer-defined sub-channel within that plugin (`tools`, `save`, `job-output`, …). Opaque to core. */
+  readonly source:     string;
+  /** Originating matbot instance. Undefined ⇒ produced locally. Set only by a bridge, on ingress. */
+  readonly instance?:  string;
+  /** Whose data this is about — the visibility axis, NOT attribution. Undefined ⇒ a global fact. */
+  readonly principal?: Principal;
+}
+
+/**
+ * The thing addressed by `(namespace, id)` is no longer what you last read — re-read it.
+ *
+ * Deliberately named for that contract and not for a medium: this is published by `Store` writes
+ * (via {@link notifyingStore}), by `FileStore` writes, and by a share/unshare that passes through
+ * neither. **Use it whenever the change is an invalidation of an addressable item**, wherever the item
+ * lives — including a plugin watching something matbot doesn't own. Define a `kind` of your own only
+ * when you carry information a consumer *cannot* get by re-reading (progress, a measurement, an
+ * external event); squeezing that in here as `detail` is the mistake this note exists to prevent.
+ *
+ * Carries identity, never the value: an event is queued per subscriber and is stale the moment a
+ * concurrent writer lands, so a consumer that acts on a payload races the source it is mirroring.
+ *
+ * `namespace` is the ROUTING namespace (`files`, `skills`, `sessions`, a document namespace) — the axis
+ * a profile isolates and `visible` routes on — not a content sub-namespace. `detail` is advisory only:
+ * a cheap payload for an in-place UI update (a file's size) that a consumer may render but must never
+ * treat as authoritative.
+ */
+export interface ItemChange extends NotificationBase {
+  readonly namespace: string;
+  readonly id:        string;
+  readonly operation: 'saved' | 'deleted';
+  readonly detail?:   unknown;
+}
+
+/** A process-global registry gained or lost a member (tools, plugins). No owner, no item identity. */
+export interface RegistryChange extends NotificationBase {
+  readonly registry:  string;
+  readonly name:      string;
+  readonly operation: 'added' | 'removed';
+}
+
+/**
+ * The wire tags for the two kinds defined here. A `kind` is a globally-scoped token — unlike a type
+ * name, which an importer can rename out of a clash — so these exist to give one back: import the const
+ * under whatever local name suits (`import { ItemChangeKind as Changed }`) and use it as a `case` label
+ * or in a filter. `satisfies` ties each to a real key, so a typo fails the build here instead of
+ * becoming a predicate that silently never matches.
+ */
+export const ItemChangeKind     = '@matatbread/matbot-plugin-api#ItemChange'     satisfies keyof Notifications;
+export const RegistryChangeKind = '@matatbread/matbot-plugin-api#RegistryChange' satisfies keyof Notifications;
+
+/**
+ * The registry of notification shapes, keyed by `kind` — augment it exactly like `MatbotServices` /
+ * `MarkerData` / `ToolContracts` to add your own:
+ *
+ *   export interface JobProgress extends NotificationBase { done: number; total: number }
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface Notifications { '@fnarr/jobs#JobProgress': JobProgress }
+ *   }
+ *
+ * **The key is `<package-name>#<InterfaceName>` — no translation, no invention.** As with the service
+ * registry, the string is the erasure-time stand-in for a type identity; unlike a type name, it is
+ * globally scoped and an importer cannot rename it out of a collision, so the package name (already
+ * unique, npm guarantees it) qualifies it. The prefix names the package that *defines* the shape, never
+ * the one emitting it — `plugin` is the emitter, and four different plugins emit `ItemChange`. The rule
+ * is enforced by {@link Qualified} at the `notify` call; export the key as a const beside the interface
+ * (see {@link ItemChangeKind}) so consumers get a renameable handle back.
+ *
+ * **The set is open at runtime.** A kind can arrive from a plugin that isn't in this build, or bridged
+ * from another server — so a `switch (n.kind)` over notifications must always have a `default`, and
+ * exhaustiveness checking is unsound here (unlike a closed discriminated union). A bridge that wants a
+ * foreign kind typed augments this itself; otherwise it validates at its own boundary, like any other
+ * system edge.
+ *
+ * One of matbot's five open-registry augmentation points — same technique at each; see
+ * docs/DEVELOPING.md *Open-registry augmentation* for the shared shape and the rules that follow from it.
+ */
+export interface Notifications {
+  '@matatbread/matbot-plugin-api#ItemChange':    ItemChange;
+  '@matatbread/matbot-plugin-api#RegistryChange': RegistryChange;
+}
+
+/** A notification as a consumer sees it: the arm, plus the `kind` its registry key supplies. Grafting
+ *  `kind` on here rather than declaring it per-arm is what makes "the tag equals the key" unrepresentable
+ *  rather than a convention to police. */
+export type Notification = {
+  [K in keyof Notifications]: Notifications[K] & { readonly kind: K };
+}[keyof Notifications];
+
+/** One arm as a standalone type, for the rare annotation that wants a single kind rather than the union. */
+export type Notified<K extends keyof Notifications> = Notifications[K] & { readonly kind: K };
+
+/** Fails an arm whose key isn't `<package>#<Name>`. Intersected into {@link NotifyInput}, so a malformed
+ *  key surfaces at the `notify` call — in the compilation that declared the augmentation, since the
+ *  mapped type is resolved at the use site. Nothing at runtime; see `createNotifier` for the producers
+ *  TypeScript can't see. */
+type Qualified<K> = K extends `${string}#${string}` ? unknown
+  : { 'ERROR — notification kind must be `<package-name>#<InterfaceName>`': K };
+
+/** What a producer passes to {@link Notifier.notify}: any registered arm, plus its key as `kind`, minus
+ *  the `plugin` the runtime stamps. Mapped over the registry (not `Omit<Notification, …>`) so it
+ *  distributes across arms and picks up augmentations. `plugin` stays settable for the one caller that
+ *  legitimately relays another's event — a bridge replaying a remote notification. */
+export type NotifyInput = {
+  [K in keyof Notifications]: Qualified<K> & Omit<Notifications[K], 'plugin'> & { readonly kind: K; plugin?: string };
+}[keyof Notifications];
+
+/** Per-subscriber predicate. Applied at emit time, so a subscriber never queues what it didn't ask for. */
+export type NotificationFilter = (notification: Notification) => boolean;
+
+/**
+ * The notification bus: one fan-out for every "something changed" fact a frontend, cache, or bridge
+ * needs, replacing the per-kind bespoke streams each producer used to hand out.
+ *
+ * A swappable {@link MatbotServices} member, not fixed runtime plumbing. The host boots an in-process
+ * broadcaster; `register('Notifier', …)` swaps in a distributed one (Redis, NATS, a matbot-to-matbot
+ * bridge) behind the usual capture-safe proxy, and unloading that plugin reverts to the host's default.
+ * Matbot owns the envelope and the registration surface; it does not own delivery.
+ *
+ * **What matbot guarantees, and an alternative implementation must preserve:**
+ *   - `notify` never throws and never blocks — enqueue and return; a slow subscriber blocks nobody.
+ *   - Ordered per producer to each subscriber. No ordering across producers.
+ *   - Local delivery is at-most-once, in-memory. **No persistence, no replay, no delivery guarantee.**
+ *     A sink attaching mid-flight has missed whatever preceded it — so a sink re-queries on attach and
+ *     treats notifications purely as invalidation. Never put current state in the bus.
+ *   - Filters are applied before queueing.
+ *   - An implementation that forwards off-box MUST stamp `instance` on ingress and MUST NOT forward a
+ *     notification that already carries a foreign `instance` — that is the loop break.
+ */
+export interface Notifier {
+  /** Publish. `plugin` is stamped from the calling plugin's scope unless explicitly relayed. */
+  notify(notification: NotifyInput): void;
+  subscribe(signal?: AbortSignal, filter?: NotificationFilter): AsyncIterable<Notification>;
+  /** Detached observation loop: awaits each handler before pulling the next, isolates a throwing
+   *  handler, ends when `signal` aborts. The fire-and-forget form of the for-await every sink writes. */
+  consume(handler: (notification: Notification) => void | Promise<void>, signal?: AbortSignal, filter?: NotificationFilter): void;
+}
+
+/**
+ * The host's boot default: in-process fan-out over the shared broadcaster, one queue per subscriber.
+ * `defaultPlugin` is stamped on anything published without one — the host passes `core`, and the
+ * per-plugin scope built in setupPlugin passes the plugin's own name.
+ */
+export function createNotifier(defaultPlugin: string): Notifier {
+  const events = createBroadcaster<Notification>();
+  return {
+    notify(notification) {
+      const plugin = notification.plugin ?? defaultPlugin;
+      // The type-level rule is erased by the time this runs, and TypeScript never saw the producers that
+      // matter most here: a plain-JS plugin, or a bridge injecting another instance's traffic. Warn, don't
+      // throw — `notify` is contractually non-throwing, and a badly-named kind is a hygiene fault, not a
+      // delivery failure. Only the shape is checkable; that the prefix names the *definer* is not, since
+      // the emitter legitimately differs from it.
+      if (!notification.kind.includes('#')) {
+        console.warn(`[matbot] ${plugin} published unqualified notification kind "${notification.kind}" — expected <package-name>#<InterfaceName>`);
+      }
+      events.emit({ ...notification, plugin } as Notification);
+    },
+    async *subscribe(signal?: AbortSignal, filter?: NotificationFilter) {
+      for await (const event of events.subscribe(signal, filter ? e => filter(e.value) : undefined)) yield event.value;
+    },
+    consume(handler, signal?, filter?) {
+      events.consume(e => handler(e.value), signal, filter ? e => filter(e.value) : undefined);
+    },
+  };
+}
+
+/** Re-scope a notifier so everything published through it is attributed to `plugin`. */
+export function scopedNotifier(notifier: Notifier, plugin: string): Notifier {
+  return {
+    notify(notification) { notifier.notify({ ...notification, plugin: notification.plugin ?? plugin } as NotifyInput); },
+    subscribe: (signal, filter) => notifier.subscribe(signal, filter),
+    consume:   (handler, signal, filter) => notifier.consume(handler, signal, filter),
+  };
+}
+
+/**
+ * Wrap a store so every successful write announces itself. For a namespace with ONE writer, an explicit
+ * `notify` at that writer is clearer; use this where a namespace has many — `sessions` is written by the
+ * turn pump (title derivation, persist-at-turn-start, the assistant commit), the `session_action` tool
+ * (rename/hide/unhide), `session_edit` (fork/split), and the frontend (a session minted over HTTP). One
+ * wrapper covers them all and cannot be forgotten by the next writer to arrive.
+ *
+ * It sits ABOVE the backend, so it is storage-independent (no backend implements anything) and profile-
+ * independent (the principal is read ambiently at write time, which is also what makes it the correct
+ * partition for visibility filtering). It observes writes made THROUGH it — a second process, or a
+ * writer that bypassed this store, is not seen; that is what a backend's own watch, where one exists,
+ * is for.
+ */
+export function notifyingStore<T extends { id: string; version: string }>(
+  store: Store<T>, notifier: Notifier, namespace: string, source: string,
+): Store<T> {
+  const announce = (operation: 'saved' | 'deleted', id: string): void => {
+    const principal = tryCurrentPrincipal();
+    notifier.notify({
+      kind: ItemChangeKind, source, operation, namespace, id,
+      ...(principal !== undefined ? { principal } : {}),
+    });
+  };
+  return {
+    get:   id => store.get(id),
+    query: q  => store.query(q),
+    async set(id, value)          { await store.set(id, value); announce('saved', id); },
+    async cas(id, expected, next) {
+      const res = await store.cas(id, expected, next);
+      if (res.ok) announce('saved', id);
+      return res;
+    },
+    async delete(id, expectedVersion) {
+      const deleted = await store.delete(id, expectedVersion);
+      if (deleted) announce('deleted', id);
+      return deleted;
+    },
+  };
+}