@matatbread/matbot-plugin-api 0.3.8 → 0.4.0

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.3.8",
+  "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,14 +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 './notify.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

@@ -98,6 +98,9 @@ export const RegistryChangeKind = '@matatbread/matbot-plugin-api#RegistryChange'
  * 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;

package/src/plugin.ts

@@ -1,14 +1,26 @@
 import type {
-  FileStore, Principal, Vault, Message, ModelParameters,
+  FileStore, Principal, Vault, Message,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
-  Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
+  Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
   TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy,
 } from './types.js';
-import type { Routed } from './broadcast.js';
 import type { Notifier } from './notify.js';
-import type { HookRegistry } from './hooks.js';
 
-export const PLUGIN_API_VERSION = '0.1';
+/**
+ * The plugin API contract version: this package's `major.minor`, and nothing else. It sat at `'0.1'`
+ * while the package shipped 0.3.x, so it conveyed no information and could not be reasoned about at a
+ * version boundary — the point at which it is the only thing every third-party plugin hardcodes.
+ *
+ * The gate (`checkApiVersion`, in core's registry) reads it as: **major must match exactly** — a
+ * mismatch is a hard load failure — and a plugin declaring a *newer minor* than the runtime warns and
+ * loads, since it may reach for something absent. Declare it as `apiVersion: PLUGIN_API_VERSION` and it
+ * stays right for free; that is what every plugin in this repo does.
+ *
+ * Bumping 0.1 → 0.4 breaks nothing: at 0.x the major is `'0'` either way, and an older declared minor
+ * does not warn. It matters at 1.0.0, where a plugin still declaring `'0.x'` will fail the major check
+ * loudly instead of loading against a contract it was never built for.
+ */
+export const PLUGIN_API_VERSION = '0.4';
 
 // ── Sub-runner types ──────────────────────────────────────────────────────────
 
@@ -16,16 +28,6 @@ export interface CompletionRequest {
   provider:    string;
   messages:    Message[];
   system?:     string;
-  /**
-   * @deprecated Per-call parameter overrides, shallow-merged over the provider config (request wins).
-   * It DOES work — both hosts (CLI + web-bundle) honour it — but it is a speculative affordance whose
-   * obvious use is an anti-pattern: a caller clamping tokens / disabling thinking for one call takes
-   * control away from the provider config, where parameters belong and stay user-editable. Prefer a
-   * dedicated provider profile (e.g. a `-classify` provider) instead of reaching for this. Kept, not
-   * removed, only because the surface is tiny and a genuine per-call need may yet appear. If you found
-   * this because you set it and it worked — reconsider whether a provider profile is the right home.
-   */
-  parameters?: Partial<ModelParameters>;
   signal?:     AbortSignal;
 }
 
@@ -38,9 +40,6 @@ export interface SingleTurnRequest {
   provider: string;
   prompt:   string;
   system?:  string;
-  /** @deprecated Forwarded verbatim to {@link CompletionRequest.parameters}; same speculative
-   *  anti-pattern caveat — prefer a dedicated provider profile over per-call overrides. */
-  parameters?: Partial<ModelParameters>;
   signal?:  AbortSignal;
 }
 
@@ -99,11 +98,15 @@ export interface PluginSelf {
 // ── Services container ────────────────────────────────────────────────────────
 
 /**
+ * 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.
+ *
  * The registry bucket: the swappable, registerable services, keyed by interface name. This is the
  * `keyof` domain of {@link MatbotRuntime.register}/`get`, and the surface third-party plugins augment
  * (`declare module '@matatbread/matbot-plugin-api' { interface MatbotServices { Foo?: Foo } }`). The
- * core three carry a host boot default and revert to it when unregistered; an augmented service is
- * optional and simply drops. Read each as a member (`services.KnowledgeIndex`); swap with register().
+ * four swap-members (`StorageBackend`, `KnowledgeIndex`, `Vault`, `Notifier`) carry a host boot default
+ * and revert to it when unregistered; an augmented service is optional and simply drops. Read each as
+ * a member (`services.KnowledgeIndex`); swap with register().
  */
 export interface MatbotServices {
   readonly StorageBackend?: StorageBackend | undefined;
@@ -255,7 +258,7 @@ export interface MatbotRuntime {
    *  runSession directly, so concurrent submits queue instead of clobbering the session. */
   readonly run?:            SessionRunner | undefined;
   readonly files?:          FileStore;
-  readonly hooks:           HookRegistry;
+  readonly hooks:           HookRegistrar;
   readonly tools:           ToolRegistry;
   readonly systemContext:   SystemContextRegistry;
   /** Default working directory for tool execution. Plugins that create servers should forward this to tool contexts. */
@@ -274,74 +277,6 @@ export interface MatbotRuntime {
   isSubAgent(): boolean;
 }
 
-/**
- * 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.
- */
-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;
-    },
-    has(target, key) {
-      if (Reflect.has(target, key)) return true;
-      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 ─────────────────────────────────────────────────────────────────
 
 /** The machine with one registry key narrowed to present — what a keyed mount handler receives. */
@@ -355,7 +290,10 @@ export interface MountConsumeOptions<K extends keyof MatbotServices> {
    *  (then on each later remount). Off by default — a cacher that did its initial load in setup() wants
    *  only future transitions; a deferred dependency wants the latch. */
   readonly replay?:    boolean;
-  /** Ends the subscription (the consumer's own teardown). */
+  /** Ends the subscription *earlier* than the observing plugin's unload. Optional because it is a
+   *  narrowing convenience, not the cleanup path: the host binds every plugin-scoped observe() to that
+   *  plugin's load extent, so an interest can never outlive its owner. Pass one only when the
+   *  subscription's life is shorter than the plugin's (a per-session cache, a one-shot latch). */
   readonly signal?:    AbortSignal;
   /** The *dependency's* teardown: fired when `key` is committed-unloaded (removed and not replaced by
    *  the quiescent edge) while this consumer lives on. The stream continues — a later remount re-fires
@@ -373,112 +311,7 @@ export interface Mounted {
   ): void;
 }
 
-/** 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.parameters !== undefined ? { parameters: req.parameters } : {}),
-    ...(req.signal     !== undefined ? { signal: req.signal } : {}),
-  };
-}
 
 // ── Factory types ─────────────────────────────────────────────────────────────