@jini-ai/core 0.4.1 → 0.4.3

package/dist/fetch/cache.js

@@ -0,0 +1,243 @@
+/**
+ * Ten seconds covers reading, closing and reopening a record or bouncing between screens
+ * without paying for another identical request. Five seconds was too short for that read
+ * cycle; thirty seconds exposed more other-operator staleness than the conservative initial
+ * shared default should allow. There is no default polling/focus refresh, so this bounds
+ * the extra exposure on a quick revisit. Write invalidation bypasses freshness; reads that
+ * must be fresh on every mount can choose staleTime: 0 without lowering every query default.
+ */
+export const DEFAULT_STALE_TIME = 10_000;
+/** Minimum time an unobserved entry is kept; both adapters retain max(this, staleTime). */
+export const IDLE_RETENTION = 5 * 60_000;
+const browserScheduler = {
+    schedule: ({ callback, delayMs }) => setTimeout(callback, delayMs),
+    cancel: ({ handle }) => clearTimeout(handle),
+};
+// Normalize unknown promise rejections once so consumers receive Error without repeating
+// the same narrowing boilerplate at every read and write call site.
+export function toQueryError(value) {
+    return value instanceof Error ? value : new Error(typeof value === 'string' && value.trim() ? value : 'request failed');
+}
+/** One provider-owned cache. Requests are shared by structural primitive keys.
+ * Failed reads retain earlier data; replacement writes supersede older requests.
+ * Idle entries live for at least five minutes or their declared freshness period. */
+export class FetchQueryCache {
+    entries = new Map();
+    disposed = false;
+    clock;
+    scheduler;
+    environment;
+    online;
+    onlineWaiters = new Set();
+    releaseEnvironment;
+    constructor(_required = {}, { clock = { nowMs: () => Date.now() }, scheduler = browserScheduler, environment } = {}) {
+        this.clock = clock;
+        this.scheduler = scheduler;
+        this.environment = environment;
+        this.online = environment?.isOnline() ?? true;
+    }
+    entry({ key }, { staleTime = DEFAULT_STALE_TIME } = {}) {
+        const hash = JSON.stringify(key);
+        let entry = this.entries.get(hash);
+        if (!entry) {
+            entry = {
+                key: [...key], state: { data: undefined, error: null, status: 'pending', isFetching: false },
+                updatedAt: 0, invalidated: false, replacement: 0, pending: undefined, pendingRead: undefined,
+                refreshAfterPending: false, listeners: new Set(), observers: new Set(),
+                retention: IDLE_RETENTION, eviction: undefined,
+            };
+            this.entries.set(hash, entry);
+        }
+        // An imperative load has no standing observer: idle eviction must not drop a value
+        // earlier than its declared freshness and unexpectedly force another network request.
+        entry.retention = Math.max(entry.retention, staleTime);
+        return entry;
+    }
+    fresh({ entry, staleTime }) {
+        return entry.state.data !== undefined && !entry.invalidated && this.clock.nowMs() - entry.updatedAt < staleTime;
+    }
+    subscribe({ entry, listener }) {
+        this.cancelEviction(entry);
+        entry.listeners.add(listener);
+        return () => { entry.listeners.delete(listener); this.scheduleEviction(entry); };
+    }
+    observe({ entry, observer }) {
+        entry.observers.add(observer);
+        return () => { entry.observers.delete(observer); this.scheduleEviction(entry); };
+    }
+    /** Cache hits respect freshness; explicit refreshes restart background reads.
+     * Initial reads still deduplicate because no earlier successful data exists to refresh. */
+    load({ entry, fetch, staleTime }, { force = false } = {}) {
+        this.cancelEviction(entry);
+        if (entry.pending && (!force || entry.state.data === undefined))
+            return entry.pending;
+        if (!force && this.fresh({ entry: entry, staleTime: staleTime })) {
+            this.scheduleEviction(entry);
+            return Promise.resolve(entry.state.data);
+        }
+        // Shared per key across loader instances: a replacement while this request is out
+        // must win over its older answer, not just protect the instance that issued the write.
+        const replacement = entry.replacement;
+        const run = () => {
+            // A queued offline refresh may have been superseded before reconnection.
+            if (entry.pending !== pending)
+                return (entry.pending ?? Promise.resolve(entry.state.data));
+            this.publish(entry, { ...entry.state, isFetching: true });
+            return fetch();
+        };
+        const pending = Promise.resolve().then(() => {
+            if (this.online)
+                return run();
+            this.publish(entry, { ...entry.state, isFetching: false });
+            return this.runOnline({ run });
+        }).then(value => {
+            const data = replacement === entry.replacement ? value : entry.state.data;
+            // Undefined is never successful query data, including an initial or background read.
+            if (data === undefined)
+                throw new Error(`${JSON.stringify(entry.key)} data is undefined`);
+            return data;
+        }).then(data => {
+            // Only the current request may publish or clear invalidation. An older transport
+            // need not support abort: its callers follow the replacement request instead.
+            if (entry.pending !== pending)
+                return (entry.pending ?? entry.state.data);
+            entry.updatedAt = this.clock.nowMs();
+            entry.invalidated = false;
+            this.publish(entry, { data, error: null, status: 'success', isFetching: false });
+            return data;
+        }, error => {
+            if (entry.pending !== pending)
+                return (entry.pending ?? entry.state.data);
+            // A replacement write is newer than this read's failure as well as its data.
+            // Keep the write's timestamp and freshness; only settle the obsolete fetch flag.
+            if (replacement !== entry.replacement) {
+                this.publish(entry, { ...entry.state, isFetching: false });
+                return entry.state.data;
+            }
+            entry.invalidated = true;
+            this.publish(entry, { ...entry.state, error: toQueryError(error), status: 'error', isFetching: false });
+            throw error;
+        }).finally(() => {
+            if (entry.pending !== pending)
+                return;
+            entry.pending = undefined;
+            entry.pendingRead = undefined;
+            if (entry.refreshAfterPending) {
+                entry.refreshAfterPending = false;
+                this.refresh(entry);
+            }
+            this.scheduleEviction(entry);
+        });
+        entry.pending = pending;
+        entry.pendingRead = { fetch, staleTime };
+        // Mark handled even when a UI caller deliberately discards the promise.
+        void pending.catch(() => { });
+        // Like TanStack's background refetches, retain the last error until success clears it
+        // or another failure replaces it. Extend that rule to retries without cached data:
+        // starting a request is not evidence of recovery; isFetching reports its progress.
+        const state = entry.state.data === undefined ? { ...entry.state, status: 'pending' } : entry.state;
+        this.publish(entry, { ...state, isFetching: this.online });
+        return pending;
+    }
+    replace({ entry, data }) {
+        entry.replacement += 1;
+        entry.updatedAt = this.clock.nowMs();
+        entry.invalidated = false;
+        this.publish(entry, { data, error: null, status: 'success', isFetching: entry.state.isFetching });
+        this.scheduleEviction(entry);
+    }
+    invalidate({ prefix }) {
+        for (const entry of this.entries.values()) {
+            if (!prefix.every((part, index) => entry.key[index] === part))
+                continue;
+            entry.invalidated = true;
+            // Revoke loader-only requests too: an active parent may read this child after
+            // the write. Its next load must start after invalidation, never join old bytes.
+            const pendingRead = entry.pendingRead;
+            entry.pending = undefined;
+            entry.pendingRead = undefined;
+            if (entry.observers.size)
+                this.refresh(entry);
+            // An awaiting loader still needs an answer even if no observer is mounted.
+            else if (pendingRead)
+                void this.load({ entry, ...pendingRead });
+        }
+    }
+    onFocus() {
+        for (const entry of this.entries.values()) {
+            const observer = [...entry.observers].find(value => value.focus && !this.fresh({ entry: entry, staleTime: value.staleTime }));
+            // Environmental refreshes share a request already underway, unlike an explicit gesture.
+            if (observer && !entry.pending)
+                void this.load({ entry: entry, fetch: observer.fetch, staleTime: observer.staleTime });
+        }
+    }
+    /** Execute a read/write once connectivity returns; failures are not retried.
+     * @param required.run Operation to invoke online.
+     * @returns The operation's original result or rejection. */
+    runOnline({ run }) {
+        if (this.online)
+            return Promise.resolve().then(() => {
+                // Connectivity may change between queuing the operation and its invocation.
+                if (!this.online)
+                    return this.runOnline({ run });
+                return run();
+            });
+        return new Promise(resolve => { this.onlineWaiters.add(resolve); }).then(() => this.runOnline({ run }));
+    }
+    /** Stop timers on provider disposal; reactivate for React's effect replay. */
+    activate() {
+        this.disposed = false;
+        if (!this.environment || this.releaseEnvironment)
+            return;
+        const releaseOnline = this.environment.subscribeOnline({ listener: online => this.onOnline({ online }) });
+        const releaseFocus = this.environment.subscribeFocus({ listener: () => this.onFocus() });
+        this.releaseEnvironment = () => { releaseOnline(); releaseFocus(); };
+        this.onOnline({ online: this.environment.isOnline() });
+    }
+    dispose() {
+        this.disposed = true;
+        this.releaseEnvironment?.();
+        this.releaseEnvironment = undefined;
+        for (const entry of this.entries.values())
+            this.cancelEviction(entry);
+    }
+    onOnline({ online }) {
+        const reconnect = online && !this.online;
+        this.online = online;
+        if (!online)
+            return;
+        for (const resume of this.onlineWaiters)
+            resume();
+        this.onlineWaiters.clear();
+        if (!reconnect)
+            return;
+        for (const entry of this.entries.values()) {
+            const observer = [...entry.observers].find(value => !this.fresh({ entry, staleTime: value.staleTime }));
+            // A paused request already owns its resumption; restarting it here would double-fetch.
+            if (observer && !entry.pending)
+                void this.load({ entry, fetch: observer.fetch, staleTime: observer.staleTime });
+        }
+    }
+    refresh(entry) {
+        const observer = entry.observers.values().next().value;
+        if (observer)
+            void this.load({ entry: entry, fetch: observer.fetch, staleTime: observer.staleTime }, { force: true });
+    }
+    publish(entry, state) {
+        entry.state = state;
+        for (const listener of entry.listeners)
+            listener();
+    }
+    cancelEviction(entry) {
+        if (entry.eviction !== undefined)
+            this.scheduler.cancel({ handle: entry.eviction });
+        entry.eviction = undefined;
+    }
+    scheduleEviction(entry) {
+        this.cancelEviction(entry);
+        if (this.disposed || entry.listeners.size || entry.observers.size || entry.pending || !Number.isFinite(entry.retention))
+            return;
+        entry.eviction = this.scheduler.schedule({ callback: () => this.entries.delete(JSON.stringify(entry.key)), delayMs: entry.retention });
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/fetch/index.d.ts

@@ -0,0 +1,5 @@
+/** Framework-neutral query contracts and cache; hosts supply transport callbacks and environment ports. */
+export { DEFAULT_STALE_TIME, IDLE_RETENTION, FetchQueryCache, toQueryError } from './cache.js';
+export type { QueryCacheSchedulerPort, FetchQueryEnvironmentPort, FetchQueryCacheOptions, QueryState, QueryObserver, CacheEntry } from './cache.js';
+export type { QueryKey, QueryStatus, QueryResult, FetchQueryOptions, MutationStatus, MutationResult, FetchMutationOptions, CachedLoaderOptions, CachedLoader, FetchQueryAdapter } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/fetch/index.js

@@ -0,0 +1,3 @@
+/** Framework-neutral query contracts and cache; hosts supply transport callbacks and environment ports. */
+export { DEFAULT_STALE_TIME, IDLE_RETENTION, FetchQueryCache, toQueryError } from './cache.js';
+//# sourceMappingURL=index.js.map

package/dist/fetch/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Keep the contract independent of any query library so an adapter swap does not require
+ * rewriting callers. Add narrow required capabilities here rather than exporting library
+ * result/client types that would bypass this boundary.
+ */
+/**
+ * Keys contain primitive array parts so parameterised resources compose without fragile
+ * string formatting or object-identity mismatches. Invalidation matches by PREFIX: a list
+ * key also refreshes its derived child keys. Exact-key equality would compile while quietly
+ * breaking that guarantee; avoid a shared prefix for resources that merely sound related,
+ * or writes will fan out unnecessary refetches.
+ * Stay primitive-only: the built-in cache matches each part with === while TanStack deep-matches,
+ * so an object part would invalidate under one adapter and silently not under the other.
+ */
+export type QueryKey = readonly (string | number)[];
+export type QueryStatus = "loading" | "success" | "error";
+export interface QueryResult<T> {
+    data: T | undefined;
+    error: Error | null;
+    status: QueryStatus;
+    isFetching: boolean;
+    refetch: () => void;
+}
+export interface FetchQueryOptions<T> {
+    key: QueryKey;
+    fetch: () => Promise<T>;
+    /**
+     * Gate on user intent or prerequisites to avoid fetching an undefined id. Disabling does
+     * not erase cached failures: without any successful data, report loading/error:null so
+     * a gesture-gated read cannot show an old failure before the user asks for it. With
+     * earlier data, report success but retain a later background error so known-stale data
+     * need not be presented as an unqualified success.
+     */
+    enabled?: boolean;
+    staleTime?: number;
+    refetchOnWindowFocus?: boolean;
+}
+export type MutationStatus = "idle" | "pending" | "success" | "error";
+export interface MutationResult<TInput, TOutput> {
+    /**
+     * Awaiting the write receives its result or rejection; discarding the same promise and
+     * reading state is safe because it already has a rejection handler. Returning a bare
+     * rejecting promise would make only the awaiting form safe. Node unhandledRejection
+     * can verify this contract even where a DOM unhandledrejection event does not fire.
+     */
+    mutate: (required: {
+        input: TInput;
+    }) => Promise<TOutput>;
+    status: MutationStatus;
+    error: Error | null;
+    reset: () => void;
+}
+export interface FetchMutationOptions<TInput, TOutput> {
+    run: (required: {
+        input: TInput;
+    }) => Promise<TOutput>;
+    invalidates?: readonly QueryKey[];
+}
+/**
+ * Keep key and fetch references stable: they are memo dependencies of the loader handle.
+ * Failed fetches reject and are not cached, so the next load retries instead of replaying
+ * a failure as data. Retain an idle value at least as long as its declared freshness: an
+ * imperative loader has no persistent observer to keep it alive.
+ */
+export interface CachedLoaderOptions<T> {
+    key: QueryKey;
+    fetch: () => Promise<T>;
+    staleTime?: number;
+}
+/**
+ * A plain promise loader serves components that own their loading UI rather than consuming
+ * a hook result. It shares the provider cache, including one in-flight request per key.
+ */
+export interface CachedLoader<T> {
+    peek: () => T | undefined;
+    load: (required?: Pick<CachedLoaderOptions<T>, "key" | "fetch">) => Promise<T>;
+    replace: (required: {
+        value: T;
+    }) => void;
+}
+/**
+ * Keep the provider-facing hooks, loader and invalidator behind one binding so replacing
+ * the cache implementation does not leave different consumers on different adapters.
+ */
+export interface FetchQueryAdapter {
+    useFetchQuery: <T>(required: Pick<FetchQueryOptions<T>, "key" | "fetch">, optional?: Omit<FetchQueryOptions<T>, "key" | "fetch">) => QueryResult<T>;
+    useFetchMutation: <TInput, TOutput>(required: Pick<FetchMutationOptions<TInput, TOutput>, "run">, optional?: Omit<FetchMutationOptions<TInput, TOutput>, "run">) => MutationResult<TInput, TOutput>;
+    useInvalidate: () => (required: {
+        key: QueryKey;
+    }) => void;
+    useCachedLoader: <T>(required: Pick<CachedLoaderOptions<T>, "key" | "fetch">, optional?: Omit<CachedLoaderOptions<T>, "key" | "fetch">) => CachedLoader<T>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/fetch/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './token.js';
+export * from './tool-metadata.js';
 export * from './pack.js';
 export * from './bindings.js';
 export type { Daemon, DaemonConfig, DaemonOptions } from './daemon.js';
@@ -9,8 +10,9 @@ export * from './redact.js';
 export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
+export * from './surface-exchanges.js';
 export type { AuthorizationDecision, RunRef, SurfaceEmission, SurfaceEmitter, ToolAuthorizationContext, ToolDescriptor, ToolExecutionContext, ToolExecutionOptions, ToolHandler, ToolPolicy, ToolRegistration, ToolRegistry, } from './tool-registry.js';
-export { createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
+export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
@@ -18,4 +20,7 @@ export * from './contribution-registry.js';
 export * from './naming.js';
 export type { AgentToolSideEffect, AgentToolActorClassRule, AgentToolDefinition } from './agent-tools.js';
 export * from "./registration-kit.js";
+export * from "./approval.js";
+export * from "./native-regexp.js";
+export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, type LegacyToolAuthorizeFn, type AuthorizationPort as ToolPermissionAuthorizationPort, type RequireToolPermissionRequired, type RequireToolPermissionOptional, } from "./tool-permissions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './token.js';
+export * from './tool-metadata.js';
 export * from './pack.js';
 export * from './bindings.js';
 export { createDaemon } from './daemon.js';
@@ -7,11 +8,15 @@ export * from './redact.js';
 export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
-export { createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
+export * from './surface-exchanges.js';
+export { createToolRegistrationScope, toolRegistryRevision, createToolRegistry, isReadOnlyTool, ToolInputError } from './tool-registry.js';
 export * from './tool-tokens.js';
 export * from './gated-mutations.js';
 export * from './model-facing-tool-errors.js';
 export * from './contribution-registry.js';
 export * from './naming.js';
 export * from "./registration-kit.js";
+export * from "./approval.js";
+export * from "./native-regexp.js";
+export { ForbiddenError as ToolPermissionDeniedError, requireToolPermission, adaptLegacyAuthorize, } from "./tool-permissions.js";
 //# sourceMappingURL=index.js.map

package/dist/model-facing-tool-errors.d.ts

@@ -3,35 +3,187 @@
  * Rule evaluation is O(r); container wrapping O(n), with no I/O or reporting dependencies.
  */
 import { type ToolHandler, type ToolRegistration } from "./tool-registry.js";
+/**
+ * One entry in a domain's allowlist: an error class, and the stable code prefix its message is
+ * published to the model under.
+ *
+ * The code is prepended before a `: ` separator (`MEMBERS_NOT_FOUND: member 'x' was not found`) so
+ * a model — and a test — can match on a stable token without parsing prose, mirroring the prefix
+ * convention `features/widgets/tool-registrations.ts` already shipped.
+ *
+ * `guidance`, when present, is appended after the message. Use it only for a failure where the
+ * caller's next action is not obvious from the message alone (a version conflict that needs a
+ * re-read, say); a not-found needs no coaching.
+ */
 export interface ModelFacingErrorRule {
+    /** The class to match with `instanceof`. Declared to accept any constructor shape so a domain can
+     *  list an error class whose constructor takes extra fields. */
     readonly error: abstract new (...args: never[]) => Error;
+    /** The stable code published before `: `. Conventionally `<DOMAIN>_<REASON>`, SCREAMING_SNAKE. */
     readonly code: string;
+    /** Published INSTEAD of the error's own message. Set it for a class whose KIND is the actionable
+     *  reason a caller needs but whose TEXT is not safe to publish — one that wraps another
+     *  component's error (a sealer's, a driver's, a keyring's), which can carry plaintext, an internal
+     *  address, an env var name or an absolute path. Omit it to publish the class's own message
+     *  verbatim, which is only correct when every construction site builds that message from fixed
+     *  text and the caller's own input.
+     *
+     *  The same field, for the same reason, as {@link CallerSafeErrorRule.message} — these two
+     *  allowlists are the RETURNED-result and THROWN-rejection halves of one policy, and a class whose
+     *  kind is safe to name on one half is safe to name on the other. They drifted until 2026-09-18:
+     *  `features/custom-credentials` listed `CustomCredentialSecretStoreUnconfiguredError` with a fixed
+     *  message in its `CallerSafeErrorRule` allowlist, but could not list it here at all, because the
+     *  only thing this shape could publish was the very text that had to stay in. A missing site root
+     *  key — the one operator-fixable failure in that domain — therefore reached the model as a bare
+     *  `INTERNAL_ERROR` on every credential-using tool. */
     readonly message?: string;
+    /** Optional recovery guidance appended after the message. */
     readonly guidance?: string;
 }
+/**
+ * The code every domain publishes an authorization refusal under, parameterized by domain prefix.
+ *
+ * Exists because `ForbiddenError` is the ONE class in this ladder that no domain declares: the kit's
+ * `requireToolPermission` throws it on every domain's behalf. Deriving the rule here rather than
+ * retyping `{ error: ForbiddenError, code: "X_FORBIDDEN" }` in six files means a later decision to
+ * reconcile this code with the HTTP arm's own `FORBIDDEN` is a one-line change here, not a sweep.
+ *
+ * NOTE (2026-09-16): the model-facing and HTTP arms disagree on this code today — the HTTP mappers
+ * return `FORBIDDEN` while the model-facing arm returns `<DOMAIN>_FORBIDDEN`. That drift predates
+ * this file (see `features/widgets/tool-registrations.ts`'s `toModelFacingWidgetsError` doc, which
+ * documented it for Widgets) and is owned elsewhere. This helper deliberately matches the SHIPPED
+ * model-facing convention rather than inventing a third spelling.
+ *
+ * The refusal message `requireToolPermission` builds names the principal, the permission, and the
+ * `authorize()` reason — no data, no internals. Surfacing it tells a model whether to stop asking
+ * or to ask a human for access; redacting it tells it only that something broke.
+ *
+ * @param required.domainPrefix - The domain's SCREAMING_SNAKE prefix, e.g. `MEMBERS`.
+ * @param required.error - The consumer's permission-error class; core has no CMS dependency.
+ * @returns The rule to place in that domain's allowlist.
+ * @complexity O(1).
+ */
 export declare function forbiddenRule(required: {
     domainPrefix: string;
     error: ModelFacingErrorRule["error"];
 }): ModelFacingErrorRule;
+/**
+ * Re-classifies one rejection against a domain's allowlist, so a listed domain error reaches the
+ * model as a `ToolInputError` carrying its real message instead of a redacted `INTERNAL_ERROR`.
+ *
+ * Rules are evaluated IN ORDER and the first `instanceof` match wins, so a domain listing both a
+ * subclass and its superclass must place the subclass first — the same ordering discipline any
+ * hand-written `instanceof` ladder carries, made explicit here because an array hides it less than
+ * a chain of `if`s does.
+ *
+ * A matched rule publishes the error's own message, or {@link ModelFacingErrorRule.message} instead
+ * when the rule sets one — see that field for which classes need it and why.
+ *
+ * An already-`ToolInputError` rejection is returned untouched: it is already correctly classified,
+ * and re-wrapping it would double a code prefix that a `withSchemaOnRejection` wrap may have
+ * already attached.
+ *
+ * @param required.err - The rejection, of unknown type — anything a handler can throw.
+ * @param required.rules - The domain's allowlist. Anything unmatched is returned UNCHANGED and stays
+ * redacted; see this file's header for why that default is the security-relevant half.
+ * @returns The value to re-throw: a `ToolInputError` for a matched rule, otherwise `err` itself.
+ * @complexity O(r) in the rule count, on the failure path only.
+ */
 export declare function reclassifyToolError(required: {
     err: unknown;
     rules: readonly ModelFacingErrorRule[];
 }): unknown;
+/**
+ * Wraps EVERY handler in a domain's map with {@link reclassifyToolError}, returning a new map.
+ *
+ * Wrapping the whole map once — rather than reclassifying at each call site — is the point. This
+ * codebase's dominant defect is a correct primitive with an unwired call site, and a per-call-site
+ * reshape is exactly that defect waiting to happen: `features/post/tool-registrations.ts` had a
+ * correct `toModelFacingUpdateError` wired into ONE of its handlers while its siblings kept
+ * throwing the same class straight through to the redactor. A map-level wrap cannot have a missed
+ * arm, because it has no arms.
+ *
+ * The wrap is transparent on the success path: the handler's own return value is passed through
+ * untouched, and only the `catch` does work.
+ *
+ * @param required.handlers - The domain's handler map, keyed by tool id.
+ * @param rules - The domain's allowlist, applied identically to every handler.
+ * @returns A new map with the same keys; the input map is not mutated.
+ * @complexity O(h) handlers wrapped once at build time; O(r) per failed call, none per successful one.
+ */
 export declare function withModelFacingErrors(required: {
     handlers: Readonly<Record<string, ToolHandler>>;
     rules: readonly ModelFacingErrorRule[];
 }): Record<string, ToolHandler>;
+/**
+ * Wraps EVERY registration's handler in a domain's `ToolRegistration[]` with
+ * {@link reclassifyToolError}, returning a new array. The `ToolRegistration[]`-shaped sibling of
+ * {@link withModelFacingErrors} — for the registry-converted domains whose `build*Registrations`
+ * returns an array of `{descriptor, handler, policy}` (see `assistant/tool-contribution-registry.ts`'s
+ * `ToolContributor.build`) rather than a `Record<toolId, handler>`. `features/entries`,
+ * `features/content-types`, `features/navigation` and `features/workspace` are re-exported Jini
+ * builders of exactly this shape — see each one's `contribute*Tools`.
+ *
+ * Same transparency guarantee as {@link withModelFacingErrors}: only the `catch` arm does work, and
+ * every other field of each registration (`descriptor`, `policy`) passes through unchanged.
+ *
+ * @param required.registrations - The domain's registrations, in whatever order `build*Registrations`
+ * returned them.
+ * @param rules - The domain's allowlist, applied identically to every registration.
+ * @returns A new array with the same length and order; the input array is not mutated.
+ * @complexity O(n) registrations wrapped once at build time; O(r) per failed call, none per successful one.
+ */
 export declare function withModelFacingRegistrationErrors(required: {
     registrations: readonly ToolRegistration[];
     rules: readonly ModelFacingErrorRule[];
 }): ToolRegistration[];
+/**
+ * One entry in a structured-result allowlist — see {@link callerSafeErrorMessage}.
+ *
+ * No `code`: a structured result already carries its own `reason` discriminant, and its message is
+ * often rendered to a human as-is, so no prefix is added.
+ */
 export interface CallerSafeErrorRule {
+    /** The class to match with `instanceof`. Same constructor shape as {@link ModelFacingErrorRule.error}. */
     readonly error: abstract new (...args: never[]) => Error;
+    /** Published INSTEAD of the error's own message. Set it for a class whose KIND is safe and worth
+     *  naming but whose message is not — one that embeds another error's text. Omit it to publish the
+     *  class's own message verbatim, which is only correct when every construction site builds that
+     *  message from fixed text and the caller's own input. */
     readonly message?: string;
 }
+/**
+ * The message a RETURNED failure result may carry for `err`: a listed class's message (or its fixed
+ * replacement), otherwise `fallback`.
+ *
+ * Unknown means redacted. An error class added tomorrow, a raw driver error, or a non-`Error` throw
+ * all get `fallback`, never their own text. Rules are evaluated in order; the first `instanceof`
+ * match wins.
+ *
+ * @param required.err - The caught value, of unknown type.
+ * @param required.rules - The allowlist.
+ * @param required.fallback - Fixed text for everything unlisted. Must not be built from `err`.
+ * @returns The message to publish.
+ * @complexity O(r) in the rule count.
+ */
 export declare function callerSafeErrorMessage(required: {
     err: unknown;
     rules: readonly CallerSafeErrorRule[];
     fallback: string;
 }): string;
+/**
+ * What a server-side log line may say about an error whose message is NOT known to be safe: its class
+ * name, a constant-token `code`, and the same for its direct `cause`. Never the message, which can
+ * quote a secret — `JSON.parse` quotes its input, and a sealer is handed plaintext.
+ *
+ * Use it wherever the raw message could carry a credential. Where a class's message is designed for
+ * logs (`EgressRefusedError.message`), log that instead.
+ *
+ * @param required.err - The caught value.
+ * @returns e.g. `SqliteError(SQLITE_BUSY)`, or `TypeError cause=Error(ECONNREFUSED)`.
+ * @complexity O(1).
+ */
+export declare function describeErrorForLog(required: {
+    err: unknown;
+}, _optional?: Record<string, never>): string;
 //# sourceMappingURL=model-facing-tool-errors.d.ts.map