@jarenjs/contract 0.83.3 → 0.85.0

package/README.md

@@ -21,7 +21,7 @@ task slot per operation and one registered effect; and the
 consumer wants beside the runtime — a browser-safe public subset that is
 itself a `$contract` document, a valid OpenAPI 3.1 document, TypeScript
 declarations with a typed operation map, Markdown reference docs and
-`@jarenjs/ai` tool definitions — with a `jaren-contract` CLI whose
+plain operation definitions — with a `jaren-contract` CLI whose
 `--check` fails CI the moment an artifact drifts. The contract knows its
 own identity: `contract.revision()` is the SHA-256 of the canonical
 public projection, served at the well-known path and carried in every
@@ -513,7 +513,7 @@ toTypeScript(contract);       // one .d.ts: CatalogLoadInput/Output per operatio
                               //   typed Client and Handlers — invoke('product.save', …) is fully typed
 toMarkdown(contract);         // reference docs: operations table, per-operation sections, the type tables
 contractTools(contract, client);
-                              // @jarenjs/ai ToolDefs (WebMCP for free) without importing that package:
+                              // plain ToolDefs for the shared WebMCP adapter:
                               //   name 'product_save', a self-contained inputSchema, execute → the outcome
 ```
 
@@ -738,6 +738,7 @@ Every subpath a consumer can import, derived from the manifest by
 | `@jarenjs/contract/package.json` | metadata | — |
 | `@jarenjs/contract/provider` | JavaScript | declared |
 | `@jarenjs/contract/command` | JavaScript | declared |
+| `@jarenjs/contract/webmcp` | JavaScript | declared |
 <!--/fact-->
 
 Author JSON template catalogs and MessageSpec references with the
@@ -780,3 +781,45 @@ finalizers remain part of the same end-to-end test.
 REST/GraphQL dialects and private run authority. Partial observations retain
 wire text and never become complete snapshots. See
 [provider descriptors and ingestion](docs/PROVIDER-FORMAT.md).
+
+## Browser operation registration
+
+`@jarenjs/contract/webmcp` exports `registerWebMcp` for plain invokable tool
+definitions. Its browser boundary needs no assistant, provider or model. Supply
+operations that already validate their inputs, for example projected contract
+operations. Importing the module does not inspect browser globals.
+
+```js
+import { registerWebMcp } from '@jarenjs/contract/webmcp';
+const binding = registerWebMcp(tools, { realm: window });
+const outcome = await binding.ready;
+// On host teardown:
+await binding.dispose();
+```
+
+An explicitly supplied `context` is authoritative, including null or undefined.
+Otherwise the adapter discovers a usable `document.modelContext`, then
+`navigator.modelContext`, preserving method receivers and registering through
+only one context. Missing/inaccessible objects and non-callable methods do not
+mask the other root. `registerTool` takes precedence over legacy `provideContext`
+on either root. Only the explicit `WEBMCP_UNSUPPORTED` sentinel permits fallback
+after invoking a method; an injected implementation may return it only before
+any mutation. Exceptions, permission refusals and partial registration never
+trigger a second registration attempt.
+
+The binding immediately exposes `ready`, `status` and `dispose`. `ready` resolves
+to `registered`, `unavailable`, `failed` or `disposed` with counts, the selected
+root/method and diagnostics; starting a promise does not report completion.
+Browser failures retain their original error and separate cleanup errors.
+Dispose deactivates callbacks immediately, then waits for pending registration
+and removes only owned successful registrations. Repeated disposal is harmless.
+
+Removal uses a returned cleanup handle or `unregisterTool` where available.
+Registration always receives an abort signal. Set `lifecycle: 'abort'` only for
+a host qualified to support it; otherwise native removal without a handle or
+unregister method is explicitly `unverified`, while owned callbacks are inert.
+Legacy `clearContext` is used only with `exclusiveLegacyContext: true`, a host
+guarantee that this binding owns the whole catalog, and only for its current
+owner. Shared legacy catalogs are never cleared. Later explicit mounts discover
+capabilities again. Unknown future method shapes fail visibly without breaking
+ordinary application operations.

package/dist/types/project/index.d.ts

@@ -3,7 +3,7 @@
  * `publicProjection` (the browser-safe subset — itself a `$contract`
  * document, and what the revision hashes), `toOpenApi` (OpenAPI 3.1
  * through a JSLT stylesheet), `toTypeScript` and `toMarkdown` (on
- * `@jarenjs/emit`'s type model), `contractTools` (`@jarenjs/ai` tool
+ * `@jarenjs/emit`'s type model), `contractTools` (plain operation
  * definitions, no import edge) and the same-document bundler they share.
  * This is the one subpath that imports `@jarenjs/emit` — the CLI loads
  * it lazily, only for `types` and `docs`; a consumer that never imports

package/dist/types/project/tools.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file `contractTools`: the public, invokable operations of a contract as
- * tool definitions for `@jarenjs/ai`'s toolbox — `{ name, description,
+ * tool definitions for host operation registries — `{ name, description,
  * inputSchema, execute }`, a plain object the toolbox and a WebMCP host
  * read, so this package never imports the ai package (the generated-
  * document rule). `execute` calls the client's `invoke` and answers the
@@ -50,8 +50,9 @@ export type ContractToolsOptions = {
  *   without `invoke`, `ops` naming an unknown or opaque operation, a tool
  *   name outside `^[a-zA-Z0-9_-]{1,64}$`, or two operations mapping to one name
  * @example
- * const toolbox = createToolbox();                    // @jarenjs/ai
- * for (const tool of contractTools(contract, client)) toolbox.add(tool);
- * await toolbox.execute('product_save', { id: 1, revision: 2, product: { … } }); // → an outcome
+ * const tools = contractTools(contract, client);
+ * const save = tools.find(tool => tool.name === 'product_save');
+ * await save.execute({ id: 1, revision: 2, product: { title: 'Example' } }); // → an outcome
+ * // registerWebMcp(tools) exposes the same definitions to a browser host.
  */
 export declare function contractTools(contract: Contract, client: ToolClient, options?: ContractToolsOptions): ToolDefinition[];

package/dist/types/webmcp.d.ts

@@ -0,0 +1,54 @@
+/** Browser registration of plain operations, with an owned asynchronous lifecycle. */
+/** An injected adapter may return this only when an operation had no side effects. */
+export declare const WEBMCP_UNSUPPORTED: unique symbol;
+export type WebMcpTool = {
+    name: string;
+    description: string;
+    inputSchema: object;
+    execute: (input: any, options?: {
+        signal?: AbortSignal;
+    }) => any;
+    annotations?: Record<string, boolean>;
+};
+export type WebMcpDiagnostic = {
+    code: string;
+    root?: string;
+    error?: unknown;
+};
+export type WebMcpResult = {
+    status: 'pending' | 'registered' | 'unavailable' | 'failed' | 'disposed';
+    registered: number;
+    root: string | null;
+    method: string | null;
+    error?: unknown;
+    diagnostics: WebMcpDiagnostic[];
+    cleanupErrors: unknown[];
+    nativeRemoval: 'none' | 'unregister' | 'abort' | 'handle' | 'legacy-clear' | 'unverified';
+};
+export type WebMcpOptions = {
+    context?: unknown;
+    realm?: object;
+    onError?: (error: unknown) => void;
+    signal?: AbortSignal;
+    lifecycle?: 'abort' | 'callback-only';
+    exclusiveLegacyContext?: boolean;
+};
+/**
+ * Register plain, already validated operations. Explicit context overrides are
+ * authoritative. Otherwise a usable document context precedes navigator.
+ * `ready` resolves after completion; dispose deactivates callbacks immediately
+ * and waits for pending registration and owned native cleanup. Neither promise
+ * rejects on browser failures. Each explicit call discovers capabilities again.
+ *
+ * `lifecycle: 'abort'` qualifies a host known to support registration signals.
+ * Without an unregister method, cleanup handle or that qualification, callbacks
+ * are deactivated and native removal is reported as unverified. A legacy clear
+ * requires the host's explicit exclusive-catalog guarantee.
+ * @param {WebMcpTool[]} definitions
+ * @param {WebMcpOptions} [options]
+ */
+export declare function registerWebMcp(definitions: WebMcpTool[], options?: WebMcpOptions): {
+    ready: Promise<WebMcpResult>;
+    dispose: () => Promise<WebMcpResult>;
+    readonly status: "disposed" | "failed" | "pending" | "registered" | "unavailable";
+};

package/docs/CONTRACT-FORMAT.md

@@ -1940,7 +1940,7 @@ rendered by emit's Markdown target over the **same** type model as
 
 `contractTools(contract, client, { ops?, name? })` → an array of
 `{ name, description, inputSchema, execute }` — the `ToolDef` shape
-`@jarenjs/ai`'s `createToolbox().add` takes and WebMCP's `registerTool`
+browser or host operation registries takes and WebMCP's `registerTool`
 reads, **without importing that package** (the generated-document rule:
 the shape is a plain object; the test suite registers them into a real
 toolbox). Per public, invokable operation (opaque and subscribe

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/contract",
   "private": false,
-  "version": "0.83.3",
+  "version": "0.85.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -67,6 +67,10 @@
     "./command": {
       "types": "./dist/types/command.d.ts",
       "default": "./src/command.js"
+    },
+    "./webmcp": {
+      "types": "./dist/types/webmcp.d.ts",
+      "default": "./src/webmcp.js"
     }
   },
   "files": [
@@ -110,9 +114,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.83.3",
-    "@jarenjs/json": "^0.83.3",
-    "@jarenjs/validate": "^0.83.3",
-    "@jarenjs/emit": "^0.83.3"
+    "@jarenjs/core": "^0.85.0",
+    "@jarenjs/json": "^0.85.0",
+    "@jarenjs/validate": "^0.85.0",
+    "@jarenjs/emit": "^0.85.0"
   }
 }

package/src/project/index.js

@@ -4,7 +4,7 @@
  * `publicProjection` (the browser-safe subset — itself a `$contract`
  * document, and what the revision hashes), `toOpenApi` (OpenAPI 3.1
  * through a JSLT stylesheet), `toTypeScript` and `toMarkdown` (on
- * `@jarenjs/emit`'s type model), `contractTools` (`@jarenjs/ai` tool
+ * `@jarenjs/emit`'s type model), `contractTools` (plain operation
  * definitions, no import edge) and the same-document bundler they share.
  * This is the one subpath that imports `@jarenjs/emit` — the CLI loads
  * it lazily, only for `types` and `docs`; a consumer that never imports

package/src/project/tools.js

@@ -1,7 +1,7 @@
 //@ts-check
 /**
  * @file `contractTools`: the public, invokable operations of a contract as
- * tool definitions for `@jarenjs/ai`'s toolbox — `{ name, description,
+ * tool definitions for host operation registries — `{ name, description,
  * inputSchema, execute }`, a plain object the toolbox and a WebMCP host
  * read, so this package never imports the ai package (the generated-
  * document rule). `execute` calls the client's `invoke` and answers the
@@ -23,7 +23,7 @@ import { bundleSameDocument } from '../bundle.js';
  */
 
 /**
- * A tool definition as `@jarenjs/ai`'s `createToolbox().add` takes it —
+ * A tool definition as browser or host operation registries takes it —
  * the same shape WebMCP's `registerTool` reads.
  * @typedef {Object} ToolDefinition
  * @property {string} name
@@ -92,9 +92,10 @@ function toolInputSchema(op, contract) {
  *   without `invoke`, `ops` naming an unknown or opaque operation, a tool
  *   name outside `^[a-zA-Z0-9_-]{1,64}$`, or two operations mapping to one name
  * @example
- * const toolbox = createToolbox();                    // @jarenjs/ai
- * for (const tool of contractTools(contract, client)) toolbox.add(tool);
- * await toolbox.execute('product_save', { id: 1, revision: 2, product: { … } }); // → an outcome
+ * const tools = contractTools(contract, client);
+ * const save = tools.find(tool => tool.name === 'product_save');
+ * await save.execute({ id: 1, revision: 2, product: { title: 'Example' } }); // → an outcome
+ * // registerWebMcp(tools) exposes the same definitions to a browser host.
  */
 export function contractTools(contract, client, options = {}) {
   if (!isJsonObject(options)) throw new ContractHostError('JC1008', 'contractTools: options must be an object');

package/src/webmcp.js

@@ -0,0 +1,193 @@
+//@ts-check
+/** Browser registration of plain operations, with an owned asynchronous lifecycle. */
+
+/** An injected adapter may return this only when an operation had no side effects. */
+export const WEBMCP_UNSUPPORTED = Symbol('WebMCP operation unsupported before registration');
+
+/**
+ * @typedef {{ name: string, description: string, inputSchema: object,
+ *   execute: (input: any, options?: { signal?: AbortSignal }) => any,
+ *   annotations?: Record<string, boolean> }} WebMcpTool
+ * @typedef {{ code: string, root?: string, error?: unknown }} WebMcpDiagnostic
+ * @typedef {{ status: 'pending'|'registered'|'unavailable'|'failed'|'disposed',
+ *   registered: number, root: string|null, method: string|null,
+ *   error?: unknown, diagnostics: WebMcpDiagnostic[], cleanupErrors: unknown[],
+ *   nativeRemoval: 'none'|'unregister'|'abort'|'handle'|'legacy-clear'|'unverified' }} WebMcpResult
+ * @typedef {{ context?: unknown, realm?: object,
+ *   onError?: (error: unknown) => void, signal?: AbortSignal,
+ *   lifecycle?: 'abort'|'callback-only', exclusiveLegacyContext?: boolean }} WebMcpOptions
+ */
+
+/** Only an explicitly exclusive legacy binding may clear its whole catalog. */
+const legacyOwners = new WeakMap();
+
+/**
+ * Register plain, already validated operations. Explicit context overrides are
+ * authoritative. Otherwise a usable document context precedes navigator.
+ * `ready` resolves after completion; dispose deactivates callbacks immediately
+ * and waits for pending registration and owned native cleanup. Neither promise
+ * rejects on browser failures. Each explicit call discovers capabilities again.
+ *
+ * `lifecycle: 'abort'` qualifies a host known to support registration signals.
+ * Without an unregister method, cleanup handle or that qualification, callbacks
+ * are deactivated and native removal is reported as unverified. A legacy clear
+ * requires the host's explicit exclusive-catalog guarantee.
+ * @param {WebMcpTool[]} definitions
+ * @param {WebMcpOptions} [options]
+ */
+export function registerWebMcp(definitions, options = {}) {
+  const names = new Set();
+  for (const tool of definitions) {
+    if (!tool || typeof tool.name !== 'string' || !tool.name || names.has(tool.name)
+      || typeof tool.description !== 'string' || typeof tool.execute !== 'function'
+      || !tool.inputSchema || typeof tool.inputSchema !== 'object')
+      throw new TypeError('WebMCP needs uniquely named, invokable tool definitions');
+    names.add(tool.name);
+  }
+  /** @type {WebMcpResult} */
+  const result = { status: 'pending', registered: 0, root: null, method: null,
+    diagnostics: [], cleanupErrors: [], nativeRemoval: 'none' };
+  let active = true, disposed = false;
+  const controller = new AbortController();
+  /** @type {Promise<WebMcpResult>|undefined} */
+  let disposal;
+  /** @type {Array<() => unknown>} */
+  const removals = [];
+  const token = {};
+  /** @type {object|undefined} */
+  let selected;
+  /** @param {unknown} error */
+  function report(error) {
+    try { options.onError?.(error); }
+    catch (hookError) { result.diagnostics.push({ code: 'error-handler-failed', error: hookError }); }
+  }
+  /** Read accessors inside the failure boundary, including method accessors. */
+  function member(object, key, root) {
+    try { return object?.[key]; }
+    catch (error) { result.diagnostics.push({ code: 'inaccessible', root, error }); return undefined; }
+  }
+  function candidates() {
+    if (Object.hasOwn(options, 'context')) return [{ value: options.context, root: 'explicit' }];
+    const realm = options.realm ?? globalThis;
+    return ['document', 'navigator'].map(root => ({
+      root, value: member(member(realm, root, root), 'modelContext', root),
+    }));
+  }
+  /** @type {WebMcpTool[]} */
+  const tools = definitions.map(tool => ({ ...tool, execute(input, execution) {
+    if (!active) return { error: 'WebMCP registration is inactive' };
+    return tool.execute(input, execution);
+  } }));
+  async function cleanup() {
+    active = false;
+    controller.abort();
+    for (const remove of removals.splice(0).reverse()) {
+      try { await remove(); }
+      catch (error) { result.cleanupErrors.push(error); report(error); }
+    }
+    if (selected && legacyOwners.get(selected) === token) legacyOwners.delete(selected);
+  }
+  function removal(context, method, name, handle, root) {
+    if (typeof handle === 'function') {
+      result.nativeRemoval = 'handle';
+      removals.push(handle);
+      return;
+    }
+    const handleDispose = member(handle, 'dispose', root);
+    if (typeof handleDispose === 'function') {
+      result.nativeRemoval = 'handle';
+      removals.push(() => handleDispose.call(handle));
+      return;
+    }
+    const unregister = member(context, 'unregisterTool', root);
+    if (method === 'registerTool' && typeof unregister === 'function') {
+      result.nativeRemoval = 'unregister';
+      removals.push(() => unregister.call(context, name));
+      return;
+    }
+    const clear = member(context, 'clearContext', root);
+    if (method === 'provideContext' && options.exclusiveLegacyContext && typeof clear === 'function') {
+      result.nativeRemoval = 'legacy-clear';
+      removals.push(() => legacyOwners.get(context) === token ? clear.call(context) : undefined);
+      return;
+    }
+    result.nativeRemoval = options.lifecycle === 'abort' ? 'abort' : 'unverified';
+    if (result.nativeRemoval === 'unverified' && !result.diagnostics.some(d => d.code === 'native-removal-unverified'))
+      result.diagnostics.push({ code: 'native-removal-unverified', root });
+  }
+  async function register() {
+    const seen = new Set();
+    for (const { value: context, root } of candidates()) {
+      if (disposed) break;
+      if (context == null || (typeof context !== 'object' && typeof context !== 'function')) {
+        result.diagnostics.push({ code: context == null ? 'absent' : 'incompatible', root });
+        continue;
+      }
+      if (seen.has(context)) continue;
+      seen.add(context);
+      let usable = false;
+      for (const method of ['registerTool', 'provideContext']) {
+        const invoke = member(context, method, root);
+        if (typeof invoke !== 'function') continue;
+        usable = true;
+        selected = context;
+        result.root = root;
+        result.method = method;
+        const batch = method === 'registerTool' ? tools : [{ tools }];
+        let unsupported = false;
+        try {
+          for (const item of batch) {
+            if (disposed) break;
+            const handle = await invoke.call(context, item, { signal: controller.signal });
+            if (handle === WEBMCP_UNSUPPORTED) {
+              if (result.registered) throw new Error('WebMCP became unsupported after partial registration');
+              unsupported = true;
+              result.diagnostics.push({ code: 'unsupported-before-registration', root });
+              break;
+            }
+            result.registered += method === 'registerTool' ? 1 : tools.length;
+            if (method === 'provideContext') legacyOwners.set(context, token);
+            removal(context, method, 'name' in item ? item.name : undefined, handle, root);
+          }
+          if (unsupported) continue;
+          result.status = disposed ? 'disposed' : 'registered';
+          if (disposed) await cleanup();
+          return result;
+        }
+        catch (error) {
+          result.error = error;
+          result.status = disposed ? 'disposed' : 'failed';
+          report(error);
+          await cleanup();
+          return result;
+        }
+      }
+      if (!usable) result.diagnostics.push({ code: 'incompatible', root });
+    }
+    active = false;
+    result.status = disposed ? 'disposed' : 'unavailable';
+    return result;
+  }
+  /** Stop callbacks now, including while the browser is still registering. */
+  function dispose() {
+    if (disposal) return disposal;
+    disposed = true;
+    active = false;
+    controller.abort();
+    options.signal?.removeEventListener('abort', onAbort);
+    disposal = ready.then(async () => { await cleanup(); result.status = 'disposed'; return result; });
+    return disposal;
+  }
+  function onAbort() { void dispose(); }
+  /** @type {(value: WebMcpResult) => void} */
+  let complete;
+  /** @type {Promise<WebMcpResult>} */
+  const ready = new Promise(resolve => { complete = resolve; });
+  if (options.signal?.aborted) { disposed = true; active = false; controller.abort(); }
+  else options.signal?.addEventListener('abort', onAbort, { once: true });
+  void register().then(complete, error => {
+    result.error = error; result.status = 'failed'; active = false; report(error);
+    complete(result);
+  });
+  return { ready, dispose, get status() { return result.status; } };
+}