@jini-ai/core 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,7 +1,13 @@
 # @jini-ai/core
 
+## 0.4.4 — 2026-10-12
+
+- New `./records` subpath exports `isRecord` and `isNonArrayRecord` without loading the core barrel; the root and `registration-kit` keep re-exporting both.
+
 ## 0.4.2 — pending release
 
+- Add source-backed `./plugin-directory` publisher identity and live metadata lookup. Warn and omit invalid advisory keywords; scope legacy `unknown/<name>` IDs to each plugin family, with optional family selection for ambiguous lookups.
+
 - Own generic settings at `./settings` and its optional Express adapter at `./settings/express`; keep both out of the root runtime closure. Move the existing permission helper into core, preserving the CMS command denial class through re-export.
 
 - Own the shared surface-exchange interfaces and reserved parameter constants, formerly declared in daemon. Add the `SurfaceAskThenReport` port so UI can consume the existing daemon lifecycle without depending on its runtime.

package/README.md

@@ -94,6 +94,7 @@ Tool handlers receive required execution context first and optional `{ emitSurfa
 
 | subpath | what's behind it |
 |---|---|
+| `./fetch` | Framework-neutral query contracts and `FetchQueryCache`; inject transport callbacks, `Clock`, scheduler and connectivity/focus ports. No React, DOM or TanStack dependency. |
 | `.` | The public surface above: tokens, packs, daemon composition, tool registry (descriptors only), principal, redact, auth primitives. |
 | `./composition` | **Not part of the public contract.** Exposes `authorizeToolInvocation` (resolves a registry's tool and runs its authorization gate — a security-sensitive value export, but one that only ever hands back a handler alongside an `'allow'` decision) plus type-only `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` re-derivation helpers. Its sole intended consumers are `@jini-ai/daemon`'s `ToolExecutor` and `@jini-ai/server`'s `createLocalNodeDaemon`. Node's resolver will happily let any consumer import it — the boundary is enforced by `scripts/check-engine-boundaries.ts`, not by the exports map — so external adopters should treat it as off-limits regardless. |
 

package/dist/fetch/cache.d.ts

@@ -0,0 +1,129 @@
+import type { Clock } from '../primitives/time.js';
+import type { QueryKey } from './types.js';
+/**
+ * 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 declare const DEFAULT_STALE_TIME = 10000;
+/** Minimum time an unobserved entry is kept; both adapters retain max(this, staleTime). */
+export declare const IDLE_RETENTION: number;
+export interface QueryCacheSchedulerPort {
+    schedule(required: {
+        callback: () => void;
+        delayMs: number;
+    }): unknown;
+    cancel(required: {
+        handle: unknown;
+    }): void;
+}
+/** Host connectivity and focus signals; the cache itself has no DOM dependency. */
+export interface FetchQueryEnvironmentPort {
+    isOnline(): boolean;
+    subscribeOnline(required: {
+        listener: (online: boolean) => void;
+    }): () => void;
+    subscribeFocus(required: {
+        listener: () => void;
+    }): () => void;
+}
+export interface FetchQueryCacheOptions {
+    clock?: Clock;
+    scheduler?: QueryCacheSchedulerPort;
+    environment?: FetchQueryEnvironmentPort;
+}
+export interface QueryState {
+    data: unknown;
+    error: Error | null;
+    status: 'pending' | 'success' | 'error';
+    isFetching: boolean;
+}
+export interface QueryObserver {
+    fetch: () => Promise<unknown>;
+    staleTime: number;
+    focus: boolean;
+}
+export interface CacheEntry {
+    key: QueryKey;
+    state: QueryState;
+    updatedAt: number;
+    invalidated: boolean;
+    replacement: number;
+    pending: Promise<unknown> | undefined;
+    pendingRead: {
+        fetch: () => Promise<unknown>;
+        staleTime: number;
+    } | undefined;
+    refreshAfterPending: boolean;
+    listeners: Set<() => void>;
+    observers: Set<QueryObserver>;
+    retention: number;
+    eviction: unknown;
+}
+export declare function toQueryError(value: unknown): Error;
+/** 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 declare class FetchQueryCache {
+    private readonly entries;
+    private disposed;
+    private readonly clock;
+    private readonly scheduler;
+    private readonly environment;
+    private online;
+    private readonly onlineWaiters;
+    private releaseEnvironment;
+    constructor(_required?: Record<string, never>, { clock, scheduler, environment }?: FetchQueryCacheOptions);
+    entry({ key }: {
+        key: QueryKey;
+    }, { staleTime }?: {
+        staleTime?: number;
+    }): CacheEntry;
+    fresh({ entry, staleTime }: {
+        entry: CacheEntry;
+        staleTime: number;
+    }): boolean;
+    subscribe({ entry, listener }: {
+        entry: CacheEntry;
+        listener: () => void;
+    }): () => void;
+    observe({ entry, observer }: {
+        entry: CacheEntry;
+        observer: QueryObserver;
+    }): () => void;
+    /** Cache hits respect freshness; explicit refreshes restart background reads.
+     * Initial reads still deduplicate because no earlier successful data exists to refresh. */
+    load<T>({ entry, fetch, staleTime }: {
+        entry: CacheEntry;
+        fetch: () => Promise<T>;
+        staleTime: number;
+    }, { force }?: {
+        force?: boolean;
+    }): Promise<T>;
+    replace({ entry, data }: {
+        entry: CacheEntry;
+        data: unknown;
+    }): void;
+    invalidate({ prefix }: {
+        prefix: QueryKey;
+    }): void;
+    onFocus(): void;
+    /** 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<T>({ run }: {
+        run: () => Promise<T>;
+    }): Promise<T>;
+    /** Stop timers on provider disposal; reactivate for React's effect replay. */
+    activate(): void;
+    dispose(): void;
+    private onOnline;
+    private refresh;
+    private publish;
+    private cancelEviction;
+    private scheduleEviction;
+}
+//# sourceMappingURL=cache.d.ts.map

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

@@ -12,7 +12,7 @@ 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';

package/dist/index.js

@@ -9,7 +9,7 @@ export * from './api-token-auth.js';
 export * from './origin-validation.js';
 export * from './principal.js';
 export * from './surface-exchanges.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';

package/dist/records.d.ts

@@ -0,0 +1,24 @@
+/** @file Pure object-shape predicates shared by tool input readers and render-time decoders. */
+/** Accept any non-null object, including arrays; never sanitizes or reads properties.
+ * @complexity O(1) time and space.
+ * @example isRecord({ value: [] }); // true
+ */
+export declare function isRecord(required: {
+    value: unknown;
+}, _optional?: Record<string, never>): required is {
+    value: Record<string, unknown>;
+};
+/**
+ * Accepts non-null, non-array objects, including class instances and null-prototype records.
+ * This is a shape check, not plain-object validation or sanitization. Keep `isRecord`'s
+ * broader contract: existing tool readers deliberately continue to accept arrays.
+ * @param required.value - The untrusted value whose object shape is checked.
+ * @complexity O(1) time and space.
+ * @example isNonArrayRecord({ value: [] }); // false
+ */
+export declare function isNonArrayRecord(required: {
+    value: unknown;
+}, _optional?: Record<string, never>): required is {
+    value: Record<string, unknown>;
+};
+//# sourceMappingURL=records.d.ts.map

package/dist/records.js

@@ -0,0 +1,21 @@
+/** @file Pure object-shape predicates shared by tool input readers and render-time decoders. */
+/** Accept any non-null object, including arrays; never sanitizes or reads properties.
+ * @complexity O(1) time and space.
+ * @example isRecord({ value: [] }); // true
+ */
+export function isRecord(required, _optional = {}) {
+    const { value } = required;
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Accepts non-null, non-array objects, including class instances and null-prototype records.
+ * This is a shape check, not plain-object validation or sanitization. Keep `isRecord`'s
+ * broader contract: existing tool readers deliberately continue to accept arrays.
+ * @param required.value - The untrusted value whose object shape is checked.
+ * @complexity O(1) time and space.
+ * @example isNonArrayRecord({ value: [] }); // false
+ */
+export function isNonArrayRecord(required, _optional = {}) {
+    return isRecord(required) && !Array.isArray(required.value);
+}
+//# sourceMappingURL=records.js.map

package/dist/registration-kit.d.ts

@@ -1,3 +1,4 @@
+export { isRecord, isNonArrayRecord } from "./records.js";
 /**
  * @file The cross-domain half of the agent-tool wiring split: everything a domain's own
  * `tool-registrations.ts` needs that is NOT specific to that domain.
@@ -134,22 +135,6 @@ export declare function indexCatalogById<T extends {
 }>(required: {
     catalog: readonly T[];
 }, _optional?: Record<string, never>): ReadonlyMap<string, T>;
-export declare function isRecord(required: {
-    value: unknown;
-}, _optional?: Record<string, never>): required is {
-    value: Record<string, unknown>;
-};
-/**
- * Accepts non-null, non-array objects, including class instances and null-prototype records.
- * This is a shape check, not plain-object validation or sanitization. Keep `isRecord`'s
- * broader contract: existing tool readers deliberately continue to accept arrays.
- * @param required.value - The untrusted value whose object shape is checked.
- */
-export declare function isNonArrayRecord(required: {
-    value: unknown;
-}, _optional?: Record<string, never>): required is {
-    value: Record<string, unknown>;
-};
 /** Narrows `ctx.input` to a record, refusing anything else. The first line of most handlers. */
 export declare function requireInputRecord(required: {
     input: unknown;

package/dist/registration-kit.js

@@ -1,3 +1,5 @@
+import { isRecord } from "./records.js";
+export { isRecord, isNonArrayRecord } from "./records.js";
 /**
  * @file The cross-domain half of the agent-tool wiring split: everything a domain's own
  * `tool-registrations.ts` needs that is NOT specific to that domain.
@@ -100,19 +102,6 @@ export function indexCatalogById(required, _optional = {}) {
 // ---------------------------------------------------------------------------
 // Input readers — the vocabulary every handler uses to read `ctx.input`.
 // ---------------------------------------------------------------------------
-export function isRecord(required, _optional = {}) {
-    const { value } = required;
-    return typeof value === "object" && value !== null;
-}
-/**
- * Accepts non-null, non-array objects, including class instances and null-prototype records.
- * This is a shape check, not plain-object validation or sanitization. Keep `isRecord`'s
- * broader contract: existing tool readers deliberately continue to accept arrays.
- * @param required.value - The untrusted value whose object shape is checked.
- */
-export function isNonArrayRecord(required, _optional = {}) {
-    return isRecord(required) && !Array.isArray(required.value);
-}
 /** Narrows `ctx.input` to a record, refusing anything else. The first line of most handlers. */
 export function requireInputRecord(required, _optional = {}) {
     const { input } = required;

package/dist/text/escape.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file The one HTML/XML text escaper. A leaf module with NO imports, on purpose: the old copies
+ * lived inside `render.ts`, `form-render.ts` and `static-render.ts` and were duplicated rather than
+ * shared because importing them would have closed a runtime import cycle. A module that imports
+ * nothing can be imported from anywhere.
+ *
+ * `&` is replaced first: it is the escape character for every entity after it, so replacing any
+ * other character first would double-escape the `&` that replacement introduced. The apostrophe
+ * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
+ */
+/** Escapes `& < > " '` for HTML text or a quoted attribute value. @complexity O(text length). */
+export declare function escapeHtml({ text }: {
+    text: string;
+}, _optional?: {}): string;
+/** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
+ *  @complexity O(text length). */
+export declare function escapeXml({ text }: {
+    text: string;
+}, _optional?: {}): string;
+//# sourceMappingURL=escape.d.ts.map

package/dist/text/escape.js

@@ -0,0 +1,23 @@
+/**
+ * @file The one HTML/XML text escaper. A leaf module with NO imports, on purpose: the old copies
+ * lived inside `render.ts`, `form-render.ts` and `static-render.ts` and were duplicated rather than
+ * shared because importing them would have closed a runtime import cycle. A module that imports
+ * nothing can be imported from anywhere.
+ *
+ * `&` is replaced first: it is the escape character for every entity after it, so replacing any
+ * other character first would double-escape the `&` that replacement introduced. The apostrophe
+ * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
+ */
+const HTML_ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+const XML_ENTITIES = { ...HTML_ENTITIES, "'": "&apos;" };
+const SPECIAL = /[&<>"']/g;
+/** Escapes `& < > " '` for HTML text or a quoted attribute value. @complexity O(text length). */
+export function escapeHtml({ text }, _optional = {}) {
+    return text.replace(SPECIAL, (char) => HTML_ENTITIES[char] ?? char);
+}
+/** {@link escapeHtml} with the XML named entity `&apos;` for the apostrophe (sitemap and feed XML).
+ *  @complexity O(text length). */
+export function escapeXml({ text }, _optional = {}) {
+    return text.replace(SPECIAL, (char) => XML_ENTITIES[char] ?? char);
+}
+//# sourceMappingURL=escape.js.map

package/dist/text/index.d.ts

@@ -1,3 +1,4 @@
 export { sanitizeUntrustedText, stripControlSequences } from './sanitize-untrusted-text.js';
 export type { SanitizeTextOptions } from './sanitize-untrusted-text.js';
+export { escapeHtml, escapeXml } from "./escape.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/text/index.js

@@ -1,2 +1,3 @@
 export { sanitizeUntrustedText, stripControlSequences } from './sanitize-untrusted-text.js';
+export { escapeHtml, escapeXml } from "./escape.js";
 //# sourceMappingURL=index.js.map

package/dist/tool-registry.d.ts

@@ -4,7 +4,7 @@
  * `{descriptor, handler, policy}` triples; the registry's *public* surface
  * (this file's `ToolRegistry` interface, and everything re-exported from
  * this package's root `index.ts`) exposes only `ToolDescriptor`s —
- * `register`/`has`/`list`. It never exposes a way to retrieve a `handler`
+ * `register`/`has`/`list`. Revocable host scopes add replacement without retrieval. It never exposes a way to retrieve a `handler`
  * or `policy` back out.
  *
  * That's the load-bearing invariant this task is named after: "handlers
@@ -199,6 +199,21 @@ export interface ToolRegistry {
     /** Descriptors only, in registration order. Never the underlying handlers/policies. */
     list(_required: Record<string, never>): readonly ToolDescriptor[];
 }
+/** A host can invalidate its disposable discovery snapshot without exposing handlers. */
+export declare function toolRegistryRevision(required: {
+    registry: object;
+}, _optional?: Record<string, never>): number | undefined;
+/** Revocable registration scope on the SAME registry the executor owns. Collision validation
+ * completes before mutation, so a failed replacement cannot lose the working generation.
+ * Only this closure may remove its own registrations; native and other scopes remain protected.
+ * Already-authorized closures are revoked too: confirmation can await a human across disable. */
+export declare function createToolRegistrationScope(required: {
+    registry: ToolRegistry;
+}, _optional?: Record<string, never>): {
+    replace({ registrations: next }: {
+        registrations: readonly ToolRegistration[];
+    }, _optional?: Record<string, never>): void;
+};
 /**
  * Creates an empty, append-only `ToolRegistry`.
  *

package/dist/tool-registry.js

@@ -33,6 +33,48 @@ export class ToolInputError extends Error {
     }
 }
 const registrationsByRegistry = new WeakMap();
+// Static register() remains append-only; scoped host contributions below explicitly own removal.
+const registryRevisions = new WeakMap();
+/** A host can invalidate its disposable discovery snapshot without exposing handlers. */
+export function toolRegistryRevision(required, _optional = {}) {
+    return registryRevisions.get(required.registry);
+}
+/** Revocable registration scope on the SAME registry the executor owns. Collision validation
+ * completes before mutation, so a failed replacement cannot lose the working generation.
+ * Only this closure may remove its own registrations; native and other scopes remain protected.
+ * Already-authorized closures are revoked too: confirmation can await a human across disable. */
+export function createToolRegistrationScope(required, _optional = {}) {
+    const registrations = registrationsByRegistry.get(required.registry);
+    if (!registrations)
+        throw new Error('registration scopes require a core ToolRegistry');
+    let owned = new Set();
+    let generation = 0;
+    return {
+        replace({ registrations: next }, _optional = {}) {
+            const ids = new Set();
+            for (const registration of next) {
+                const id = registration.descriptor.id;
+                if (ids.has(id) || (registrations.has(id) && !owned.has(id)))
+                    throw new Error(`ToolRegistry: tool "${id}" is already registered`);
+                ids.add(id);
+            }
+            generation++;
+            const current = generation;
+            for (const id of owned)
+                registrations.delete(id);
+            for (const registration of next)
+                registrations.set(registration.descriptor.id, { ...registration,
+                    handler: (input, options) => {
+                        if (generation !== current)
+                            throw new Error('tool registration was revoked');
+                        return registration.handler(input, options);
+                    },
+                });
+            owned = ids;
+            registryRevisions.set(required.registry, (registryRevisions.get(required.registry) ?? 0) + 1);
+        },
+    };
+}
 /**
  * Creates an empty, append-only `ToolRegistry`.
  *
@@ -51,6 +93,7 @@ export function createToolRegistry(_required) {
                 throw new Error(`ToolRegistry: tool "${registration.descriptor.id}" is already registered`);
             }
             registrations.set(registration.descriptor.id, registration);
+            registryRevisions.set(registry, (registryRevisions.get(registry) ?? 0) + 1);
         },
         has({ toolId }) {
             return registrations.has(toolId);
@@ -60,6 +103,7 @@ export function createToolRegistry(_required) {
         },
     };
     registrationsByRegistry.set(registry, registrations);
+    registryRevisions.set(registry, 0);
     return registry;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {
@@ -19,24 +19,32 @@
       "./model-facing-tool-errors": "universal",
       "./contribution-registry": "universal",
       "./naming": "universal",
+      "./records": "universal",
       "./primitives": "universal",
+      "./fetch": "universal",
       "./text": "universal",
       "./settings": "universal",
-      "./settings/express": "node"
+      "./settings/express": "node",
+      "./plugin-directory": "universal"
     },
     "isolation": {
       "entries": {
         "./primitives": "core",
+        "./fetch": "fetch",
         "./settings": "settings",
         "./settings/express": "settings"
       },
       "domains": {
+        "fetch": [
+          "src/fetch"
+        ],
         "settings": [
           "src/settings"
         ]
       },
       "shared": [
-        "src/tool-permissions.ts"
+        "src/tool-permissions.ts",
+        "src/records.ts"
       ],
       "forbidden": {
         "universal": [
@@ -95,11 +103,21 @@
       "import": "./dist/naming.js",
       "default": "./dist/naming.js"
     },
+    "./records": {
+      "types": "./dist/records.d.ts",
+      "import": "./dist/records.js",
+      "default": "./dist/records.js"
+    },
     "./primitives": {
       "types": "./dist/primitives/index.d.ts",
       "import": "./dist/primitives/index.js",
       "default": "./dist/primitives/index.js"
     },
+    "./fetch": {
+      "types": "./dist/fetch/index.d.ts",
+      "import": "./dist/fetch/index.js",
+      "default": "./dist/fetch/index.js"
+    },
     "./text": {
       "types": "./dist/text/index.d.ts",
       "import": "./dist/text/index.js",
@@ -114,6 +132,11 @@
       "types": "./dist/settings/express/index.d.ts",
       "import": "./dist/settings/express/index.js",
       "default": "./dist/settings/express/index.js"
+    },
+    "./plugin-directory": {
+      "types": "./plugin-directory.d.ts",
+      "import": "./plugin-directory.js",
+      "default": "./plugin-directory.js"
     }
   },
   "files": [
@@ -127,7 +150,9 @@
     "!dist/**/*.test.d.ts.map",
     "!dist/**/__tests__/**",
     "!dist/**/*.typecheck.*",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "plugin-directory.js",
+    "plugin-directory.d.ts"
   ],
   "publishConfig": {
     "access": "public",

package/plugin-directory.d.ts

@@ -0,0 +1,32 @@
+/** Identical identity metadata for portable agent packages and host site plugins. */
+export interface PluginIdentityExtension {
+  readonly id?: string;
+  readonly provides?: readonly string[];
+  readonly [key: string]: unknown;
+}
+export interface PluginIdentity {
+  readonly id: string;
+  readonly keywords: readonly string[];
+  readonly provides: readonly string[];
+  readonly warnings: readonly string[];
+}
+export interface PluginProvider {
+  readonly id: string;
+  readonly version: string | null;
+  readonly enabled: boolean;
+  readonly family: string;
+  /** Stable storage/activation key; publisher identity never becomes a filesystem path. */
+  readonly localId: string;
+  readonly keywords: readonly string[];
+  readonly provides: readonly string[];
+}
+export interface PluginLookupPort {
+  getPlugin(required: { readonly id: string; readonly family?: string }, optional?: Record<string, never>): Promise<PluginProvider | null>;
+  findProviders(required: { readonly capability: string }, optional?: { readonly enabledOnly?: boolean }): Promise<readonly PluginProvider[]>;
+}
+export type PluginIdentityCandidate = Pick<PluginProvider, 'id' | 'family' | 'localId'>;
+export function assertPluginIdentityAvailable(required: { readonly candidate: PluginIdentityCandidate; readonly installed: readonly PluginProvider[] }, optional?: Record<string, never>): void;
+export function createPluginLookupFacade(required: { readonly lookup: PluginLookupPort }, optional?: Record<string, never>): PluginLookupPort;
+export function validatePluginIdentity(required: { readonly manifest: unknown; readonly namespace: string }, optional?: Record<string, never>): { readonly errors: readonly string[] };
+export function readPluginIdentity(required: { readonly manifest: Readonly<Record<string, unknown>>; readonly namespace: string; readonly name?: string }, optional?: Record<string, never>): PluginIdentity;
+export function createPluginLookup(required: { readonly listPlugins: (required: Record<string, never>, optional?: Record<string, never>) => Promise<readonly PluginProvider[]> }, optional?: { readonly warn?: (message: string) => void }): PluginLookupPort;

package/plugin-directory.js

@@ -0,0 +1,140 @@
+/** Shared publisher identity and live plugin lookup. Source-backed, like persistent-state:
+ * hosts can adopt the additive entry without replacing a running server's compiled packages. */
+const SEGMENT = '[a-z0-9]+(?:[.-][a-z0-9]+)*';
+const ID_PATTERN = new RegExp(`^${SEGMENT}/${SEGMENT}$`);
+// Legacy site ids used a looser grammar than portable Agent Plugin names. Preserve those keys
+// in unknown/<name>; only explicitly declared publisher ids use the new strict grammar.
+const LEGACY_NAME_PATTERN = /^[a-z0-9.-]+$/;
+const CAPABILITY_PATTERN = new RegExp(`^${SEGMENT}(?::${SEGMENT})?$`);
+const object = value => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Collects identity errors without mutating the portable manifest. Absent metadata is legacy.
+ * @param {{manifest: unknown, namespace: string}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {{errors: string[]}}
+ * @complexity O(k + p) in keyword and provides entries; no I/O.
+ */
+export function validatePluginIdentity({ manifest, namespace }, optional = {}) {
+  const errors = [];
+  if (!object(manifest)) return { errors: ['Plugin manifest must be an object.'] };
+  if (manifest.extensions !== undefined && !object(manifest.extensions)) return { errors: [...errors, 'Plugin extensions must be an object.'] };
+  const extension = manifest.extensions?.[namespace];
+  if (extension === undefined) return { errors };
+  if (!object(extension)) return { errors: [...errors, 'Plugin identity extension must be an object.'] };
+  if (extension.id !== undefined && (typeof extension.id !== 'string' || extension.id.length > 129 || !ID_PATTERN.test(extension.id))) {
+    errors.push('Plugin id must have the form publisher/name (lowercase letters, digits, dots and hyphens).');
+  } else if (typeof extension.id === 'string' && extension.id.startsWith('unknown/')) {
+    // Only the host may infer a legacy identity; a publisher cannot claim its upgrade exemption.
+    errors.push("Plugin publisher 'unknown' is reserved for legacy identities.");
+  }
+  if (extension.provides !== undefined && (!Array.isArray(extension.provides) || !extension.provides.every(p => typeof p === 'string' && p.length <= 129 && CAPABILITY_PATTERN.test(p)))) {
+    errors.push('Plugin provides must be an array of capability names.');
+  }
+  return { errors };
+}
+
+/** Resolves one identity; warns on missing ids and refuses malformed declarations.
+ * @param {{manifest: Record<string, unknown>, namespace: string, name?: string}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {{id: string, keywords: string[], provides: string[], warnings: string[]}}
+ * @throws {TypeError} Malformed identity metadata or missing legacy name.
+ * @example readPluginIdentity({ manifest: { name: 'example' }, namespace: 'host' })
+ * @complexity O(k + p), copying arrays so a caller cannot mutate manifest metadata.
+ */
+export function readPluginIdentity({ manifest, namespace, name }, optional = {}) {
+  const { errors } = validatePluginIdentity({ manifest, namespace });
+  if (errors.length) throw new TypeError(errors.join(' '));
+  const extension = manifest.extensions?.[namespace];
+  const localName = name ?? manifest.name;
+  if (extension?.id === undefined && (typeof localName !== 'string' || !LEGACY_NAME_PATTERN.test(localName))) {
+    throw new TypeError('A valid plugin name is required for a legacy identity.');
+  }
+  const id = extension?.id ?? `unknown/${localName}`;
+  // Keywords are advisory portable metadata: older manifests accepted mixed or non-array values.
+  // The portable parser's coercion (non-string entries dropped, non-arrays ignored) lives here
+  // so validation and lookup normalize advisory metadata through the same owner.
+  const keywords = Array.isArray(manifest.keywords) ? manifest.keywords.filter(k => typeof k === 'string' && k.trim().length > 0) : [];
+  const warnings = extension?.id === undefined ? [`Plugin '${localName}' has no publisher-qualified id; using '${id}'.`] : [];
+  if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || keywords.length !== manifest.keywords.length)) {
+    warnings.push('Plugin keywords must be an array of nonempty strings; invalid keywords were ignored.');
+  }
+  return { id, keywords, provides: [...(extension?.provides ?? [])], warnings };
+}
+
+/** Rejects id reuse and publisher changes at an existing storage slot. Legacy metadata may
+ * acquire its first publisher id during an upgrade; a declared publisher can never be replaced.
+ * @param {{candidate: {id: string, family: string, localId: string}, installed: import('./plugin-directory.js').PluginProvider[]}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {void}
+ * @throws {Error} Conflicting publisher identity.
+ * @complexity O(n) for n installed providers.
+ */
+export function assertPluginIdentityAvailable({ candidate, installed }, optional = {}) {
+  for (const plugin of installed) {
+    const sameSlot = plugin.family === candidate.family && plugin.localId === candidate.localId;
+    if (sameSlot) {
+      if (plugin.id !== candidate.id && plugin.id !== `unknown/${candidate.localId}`) {
+        throw new Error(`Plugin '${candidate.localId}' belongs to a different publisher identity.`);
+      }
+    } else if (plugin.id === candidate.id && !(plugin.family !== candidate.family && candidate.id === `unknown/${candidate.localId}` && plugin.id === `unknown/${plugin.localId}`)) {
+      throw new Error(`Duplicate plugin id '${candidate.id}'.`);
+    }
+  }
+}
+
+/** Restricts an SDK handle at runtime, not just through a TypeScript interface. A host may carry
+ * lifecycle mutation ports, but a plugin's discovery surface exposes only these metadata reads.
+ * @param {{lookup: import('./plugin-directory.js').PluginLookupPort}} required
+ * @param {Record<string, never>} [optional]
+ * @returns {import('./plugin-directory.js').PluginLookupPort}
+ * @complexity O(1); delegates live reads without copying host methods.
+ */
+export function createPluginLookupFacade({ lookup }, optional = {}) {
+  return {
+    getPlugin: (required, options = {}) => lookup.getPlugin(required, options),
+    findProviders: (required, options = {}) => lookup.findProviders(required, options),
+  };
+}
+
+/** Live, metadata-only directory over injected workspace-scoped sources. No plugin imports.
+ * Later duplicate providers are omitted with a warning, preserving the source's incumbent order.
+ * Admission checks the unfiltered installs separately, including disabled/cross-family collisions.
+ * Legacy fallback ids are family-scoped; an unscoped ambiguous get returns null.
+ * @param {{listPlugins: (required: {}, optional?: {}) => Promise<import('./plugin-directory.js').PluginProvider[]>}} required
+ * @param {{warn?: (message: string) => void}} [optional]
+ * @returns {import('./plugin-directory.js').PluginLookupPort}
+ * @example createPluginLookup({ listPlugins: async () => [] })
+ * @complexity O(n log n) per lookup, n installed plugins. Fresh reads preserve revocation.
+ */
+export function createPluginLookup({ listPlugins }, optional = {}) {
+  const warn = optional.warn ?? console.warn;
+  async function snapshot() {
+    const plugins = await listPlugins({}, {});
+    const seen = new Set();
+    const unique = [];
+    for (const plugin of plugins) {
+      const key = plugin.id === `unknown/${plugin.localId}` ? `${plugin.family}:${plugin.id}` : plugin.id;
+      if (seen.has(key)) {
+        warn(`Duplicate plugin id '${plugin.id}'; later provider omitted from metadata lookup.`);
+        continue;
+      }
+      seen.add(key);
+      unique.push(plugin);
+    }
+    // Project metadata explicitly: host paths, services and additional source properties never
+    // leave this boundary, and a consumer cannot mutate the source's discovery arrays.
+    return unique.map(plugin => ({
+      id: plugin.id, version: plugin.version, enabled: plugin.enabled, family: plugin.family,
+      localId: plugin.localId, keywords: [...plugin.keywords], provides: [...plugin.provides],
+    })).sort((a, b) => a.id.localeCompare(b.id));
+  }
+  return {
+    async getPlugin({ id, family }, options = {}) {
+      const matches = (await snapshot()).filter(plugin => plugin.id === id && (family === undefined || plugin.family === family));
+      return matches.length === 1 ? matches[0] : null;
+    },
+    async findProviders({ capability }, { enabledOnly = false } = {}) {
+      return (await snapshot()).filter(plugin => (!enabledOnly || plugin.enabled) && plugin.provides.includes(capability));
+    },
+  };
+}