@jini-ai/daemon 0.3.8 → 0.5.0

package/dist/legacy-data-migration.d.ts

@@ -1,3 +1,23 @@
+/**
+ * @module legacy-data-migration
+ *
+ * A one-shot, idempotent, host-configured migrator for moving a daemon's
+ * data root from one location to another (e.g. a pre-packaging install that
+ * ran out of a repo checkout, moved to a per-namespace directory under an
+ * OS user-data location). The mechanism — refuse-if-missing-proof,
+ * refuse-if-destination-populated, refuse-if-already-migrated, reject
+ * symlinks, stage-then-atomically-promote, rollback-on-any-failure — is
+ * product-neutral; the *shape* of a data root's payload (which files/dirs
+ * constitute "real data", and which single entry proves a directory holds
+ * real payload rather than an empty scaffold) is host-supplied via
+ * {@link LegacyDataMigrationConfig}, never hardcoded here.
+ *
+ * Sync by design: intended to run at daemon startup before any database
+ * connection opens, so it can't race a concurrent open of the destination.
+ */
+import * as nodeFilesystem from 'node:fs';
+/** Node filesystem ABI, injected so migration can run against a host-owned adapter. */
+export type LegacyFilesystemPort = Pick<typeof nodeFilesystem, 'statSync' | 'lstatSync' | 'existsSync' | 'readdirSync' | 'mkdirSync' | 'cpSync' | 'renameSync' | 'rmSync' | 'writeFileSync'>;
 /** Which files/dirs constitute a data root's migratable payload, host-supplied. */
 export interface LegacyDataMigrationConfig {
     /** Every file/dir under a data root that is part of the migratable payload. */
@@ -19,8 +39,11 @@ export interface MigrateLegacyDataDirOptions extends LegacyDataMigrationConfig {
     dataDir: string;
     /** Optional logger. Defaults to console.log. */
     logger?: {
-        info(message: string): void;
+        info(args: {
+            message: string;
+        }): void;
     };
+    filesystem?: LegacyFilesystemPort;
     /**
      * Test seam. The default writes the JSON marker with fs.writeFileSync;
      * tests inject a function that throws so the rollback path (which removes
@@ -29,7 +52,11 @@ export interface MigrateLegacyDataDirOptions extends LegacyDataMigrationConfig {
      * pass this.
      * @internal
      */
-    writeMarker?: (dataDir: string, legacyDir: string, markerFile: string) => void;
+    writeMarker?: (args: {
+        dataDir: string;
+        legacyDir: string;
+        markerFile: string;
+    }) => void;
 }
 export type MigrateStatus = 'noop' | 'migrated' | 'skipped';
 export interface MigrateLegacyDataDirResult {
@@ -45,7 +72,10 @@ export interface MigrateLegacyDataDirResult {
  */
 export declare class LegacyMigrationError extends Error {
     readonly code: string;
-    constructor(code: string, message: string);
+    constructor({ code, message }: {
+        readonly code: string;
+        readonly message: string;
+    });
 }
 /**
  * Returns true when `dataDir` looks like a fresh / never-used data root:
@@ -58,7 +88,12 @@ export declare class LegacyMigrationError extends Error {
  * @param dataDir - The data root to check.
  * @param config - The host's payload/proof-entry configuration.
  */
-export declare function dataDirIsEmptyOrFresh(dataDir: string, config: LegacyDataMigrationConfig): boolean;
+export declare function dataDirIsEmptyOrFresh({ dataDir, config }: {
+    readonly dataDir: string;
+    readonly config: LegacyDataMigrationConfig;
+}, { filesystem: fs }?: {
+    filesystem?: LegacyFilesystemPort;
+}): boolean;
 /**
  * Returns true when `legacyDir` contains a payload worth migrating: it
  * exists and its configured `proofEntry` exists as a file.
@@ -66,7 +101,12 @@ export declare function dataDirIsEmptyOrFresh(dataDir: string, config: LegacyDat
  * @param legacyDir - The candidate legacy data directory.
  * @param config - The host's payload/proof-entry configuration.
  */
-export declare function legacyDirHasPayload(legacyDir: string, config: LegacyDataMigrationConfig): boolean;
+export declare function legacyDirHasPayload({ legacyDir, config }: {
+    readonly legacyDir: string;
+    readonly config: LegacyDataMigrationConfig;
+}, { filesystem: fs }?: {
+    filesystem?: LegacyFilesystemPort;
+}): boolean;
 /**
  * Returns the list of configured payload entries that already exist under
  * `dataDir`. Migration refuses to merge on top of any of them — a database
@@ -76,7 +116,12 @@ export declare function legacyDirHasPayload(legacyDir: string, config: LegacyDat
  * @param dataDir - The data root to check.
  * @param config - The host's payload/proof-entry configuration.
  */
-export declare function dataDirHasExistingPayload(dataDir: string, config: LegacyDataMigrationConfig): string[];
+export declare function dataDirHasExistingPayload({ dataDir, config }: {
+    readonly dataDir: string;
+    readonly config: LegacyDataMigrationConfig;
+}, { filesystem: fs }?: {
+    filesystem?: LegacyFilesystemPort;
+}): string[];
 /**
  * Move staged payload entries into the final `dataDir`. Each entry is moved
  * with `renameSync` (atomic on the same filesystem); a cross-device rename
@@ -89,7 +134,13 @@ export declare function dataDirHasExistingPayload(dataDir: string, config: Legac
  * @param entries - The payload entries to promote.
  * @returns The entries that were placed into `dataDir` before any failure.
  */
-export declare function promoteStaged(stagingDir: string, dataDir: string, entries: readonly string[]): readonly string[];
+export declare function promoteStaged({ stagingDir, dataDir, entries }: {
+    readonly stagingDir: string;
+    readonly dataDir: string;
+    readonly entries: readonly string[];
+}, { filesystem: fs }?: {
+    filesystem?: LegacyFilesystemPort;
+}): readonly string[];
 /**
  * One-shot, idempotent legacy data migrator. Synchronous so it can run at
  * module import time before a database connection opens. Throws
@@ -100,5 +151,5 @@ export declare function promoteStaged(stagingDir: string, dataDir: string, entri
  * @returns The migration outcome (`noop` when unconfigured, `skipped` when
  *   already migrated, `migrated` with the copied entry list otherwise).
  */
-export declare function migrateLegacyDataDirSync(options: MigrateLegacyDataDirOptions): MigrateLegacyDataDirResult;
+export declare function migrateLegacyDataDirSync(requiredArgs: Pick<MigrateLegacyDataDirOptions, "legacyDir" | "dataDir" | "payloadEntries" | "proofEntry">, optionalArgs?: Pick<MigrateLegacyDataDirOptions, "logger" | "writeMarker" | "markerFile" | "filesystem">): MigrateLegacyDataDirResult;
 //# sourceMappingURL=legacy-data-migration.d.ts.map

package/dist/legacy-data-migration.js

@@ -15,7 +15,7 @@
  * Sync by design: intended to run at daemon startup before any database
  * connection opens, so it can't race a concurrent open of the destination.
  */
-import * as fs from 'node:fs';
+import * as nodeFilesystem from 'node:fs';
 import * as path from 'node:path';
 const DEFAULT_MARKER_FILE = '.migrated-from';
 /**
@@ -26,13 +26,13 @@ const DEFAULT_MARKER_FILE = '.migrated-from';
  */
 export class LegacyMigrationError extends Error {
     code;
-    constructor(code, message) {
+    constructor({ code, message }) {
         super(message);
         this.code = code;
         this.name = 'LegacyMigrationError';
     }
 }
-function isExistingDir(p) {
+function isExistingDir(p, fs) {
     try {
         return fs.statSync(p).isDirectory();
     }
@@ -40,7 +40,7 @@ function isExistingDir(p) {
         return false;
     }
 }
-function isExistingFile(p) {
+function isExistingFile(p, fs) {
     try {
         return fs.statSync(p).isFile();
     }
@@ -59,10 +59,10 @@ function isExistingFile(p) {
  * @param dataDir - The data root to check.
  * @param config - The host's payload/proof-entry configuration.
  */
-export function dataDirIsEmptyOrFresh(dataDir, config) {
-    if (!isExistingDir(dataDir))
+export function dataDirIsEmptyOrFresh({ dataDir, config }, { filesystem: fs = nodeFilesystem } = {}) {
+    if (!isExistingDir(dataDir, fs))
         return true;
-    return !isExistingFile(path.join(dataDir, config.proofEntry));
+    return !isExistingFile(path.join(dataDir, config.proofEntry), fs);
 }
 /**
  * Returns true when `legacyDir` contains a payload worth migrating: it
@@ -71,10 +71,10 @@ export function dataDirIsEmptyOrFresh(dataDir, config) {
  * @param legacyDir - The candidate legacy data directory.
  * @param config - The host's payload/proof-entry configuration.
  */
-export function legacyDirHasPayload(legacyDir, config) {
-    if (!isExistingDir(legacyDir))
+export function legacyDirHasPayload({ legacyDir, config }, { filesystem: fs = nodeFilesystem } = {}) {
+    if (!isExistingDir(legacyDir, fs))
         return false;
-    return isExistingFile(path.join(legacyDir, config.proofEntry));
+    return isExistingFile(path.join(legacyDir, config.proofEntry), fs);
 }
 /**
  * Returns the list of configured payload entries that already exist under
@@ -85,8 +85,8 @@ export function legacyDirHasPayload(legacyDir, config) {
  * @param dataDir - The data root to check.
  * @param config - The host's payload/proof-entry configuration.
  */
-export function dataDirHasExistingPayload(dataDir, config) {
-    if (!isExistingDir(dataDir))
+export function dataDirHasExistingPayload({ dataDir, config }, { filesystem: fs = nodeFilesystem } = {}) {
+    if (!isExistingDir(dataDir, fs))
         return [];
     return config.payloadEntries.filter((entry) => fs.existsSync(path.join(dataDir, entry)));
 }
@@ -95,26 +95,26 @@ export function dataDirHasExistingPayload(dataDir, config) {
  * preserved symlink would let a downstream reader escape the data root.
  * @internal
  */
-function assertNoSymlinks(srcRoot, displayPath = srcRoot) {
+function assertNoSymlinks(srcRoot, fs, displayPath = srcRoot) {
     const stat = fs.lstatSync(srcRoot);
     if (stat.isSymbolicLink()) {
-        throw new LegacyMigrationError('symlink_in_payload', `legacy payload contains a symlink at "${displayPath}"; refusing to migrate`);
+        throw new LegacyMigrationError({ code: 'symlink_in_payload', message: `legacy payload contains a symlink at "${displayPath}"; refusing to migrate` });
     }
     if (!stat.isDirectory())
         return;
     for (const child of fs.readdirSync(srcRoot)) {
-        assertNoSymlinks(path.join(srcRoot, child), path.join(displayPath, child));
+        assertNoSymlinks(path.join(srcRoot, child), fs, path.join(displayPath, child));
     }
 }
 /** Stage every present payload entry into `stagingDir`. Returns the entries actually copied. @internal */
-function stagePayload(legacyDir, stagingDir, payloadEntries) {
+function stagePayload(legacyDir, stagingDir, payloadEntries, fs) {
     fs.mkdirSync(stagingDir, { recursive: true });
     const copied = [];
     for (const entry of payloadEntries) {
         const src = path.join(legacyDir, entry);
         if (!fs.existsSync(src))
             continue;
-        assertNoSymlinks(src);
+        assertNoSymlinks(src, fs);
         const dst = path.join(stagingDir, entry);
         fs.cpSync(src, dst, { recursive: true, force: true, errorOnExist: false });
         copied.push(entry);
@@ -133,7 +133,7 @@ function stagePayload(legacyDir, stagingDir, payloadEntries) {
  * @param entries - The payload entries to promote.
  * @returns The entries that were placed into `dataDir` before any failure.
  */
-export function promoteStaged(stagingDir, dataDir, entries) {
+export function promoteStaged({ stagingDir, dataDir, entries }, { filesystem: fs = nodeFilesystem } = {}) {
     fs.mkdirSync(dataDir, { recursive: true });
     const promoted = [];
     try {
@@ -157,17 +157,17 @@ export function promoteStaged(stagingDir, dataDir, entries) {
         }
     }
     catch (err) {
-        rollbackPromoted(dataDir, promoted);
+        rollbackPromoted(dataDir, promoted, fs);
         throw err;
     }
     return promoted;
 }
-function rollbackPromoted(dataDir, promoted) {
+function rollbackPromoted(dataDir, promoted, fs) {
     for (const entry of promoted) {
         fs.rmSync(path.join(dataDir, entry), { recursive: true, force: true });
     }
 }
-function writeMarkerDefault(dataDir, legacyDir, markerFile) {
+function writeMarkerDefault({ dataDir, legacyDir, markerFile }, fs) {
     const marker = path.join(dataDir, markerFile);
     const temp = `${marker}.tmp-${process.pid}-${Date.now()}`;
     const payload = JSON.stringify({ legacyDir: path.resolve(legacyDir), migratedAt: new Date().toISOString() }, null, 2);
@@ -190,8 +190,10 @@ function writeMarkerDefault(dataDir, legacyDir, markerFile) {
  * @returns The migration outcome (`noop` when unconfigured, `skipped` when
  *   already migrated, `migrated` with the copied entry list otherwise).
  */
-export function migrateLegacyDataDirSync(options) {
-    const log = options.logger ?? { info: (m) => console.log(`[jini-migrate] ${m}`) };
+export function migrateLegacyDataDirSync(requiredArgs, optionalArgs = {}) {
+    const options = { ...requiredArgs, ...optionalArgs };
+    const fs = options.filesystem ?? nodeFilesystem;
+    const log = options.logger ?? { info: ({ message }) => console.log(`[jini-migrate] ${message}`) };
     const markerFile = options.markerFile ?? DEFAULT_MARKER_FILE;
     const raw = options.legacyDir;
     if (raw === undefined || raw.length === 0) {
@@ -209,31 +211,34 @@ export function migrateLegacyDataDirSync(options) {
     if (fs.existsSync(markerPath)) {
         return { status: 'skipped', reason: 'migration marker already present' };
     }
-    if (!legacyDirHasPayload(legacyDir, options)) {
-        throw new LegacyMigrationError('legacy_dir_invalid', `legacy data dir "${legacyDir}" is not a usable legacy data dir (expected "${options.proofEntry}" directly inside it).`);
+    if (!legacyDirHasPayload({ legacyDir: legacyDir, config: options }, { filesystem: fs })) {
+        throw new LegacyMigrationError({ code: 'legacy_dir_invalid', message: `legacy data dir "${legacyDir}" is not a usable legacy data dir (expected "${options.proofEntry}" directly inside it).` });
     }
-    const existing = dataDirHasExistingPayload(dataDir, options);
+    const existing = dataDirHasExistingPayload({ dataDir: dataDir, config: options }, { filesystem: fs });
     if (existing.length > 0) {
-        throw new LegacyMigrationError('data_dir_not_empty', `data dir "${dataDir}" already contains payload entries (${existing.join(', ')}); refusing to merge legacy data on top. Move the existing data aside or pick a fresh data root before retrying.`);
+        throw new LegacyMigrationError({ code: 'data_dir_not_empty', message: `data dir "${dataDir}" already contains payload entries (${existing.join(', ')}); refusing to merge legacy data on top. Move the existing data aside or pick a fresh data root before retrying.` });
     }
-    log.info(`migrating legacy data from "${legacyDir}" to "${dataDir}"`);
+    log.info({ message: `migrating legacy data from "${legacyDir}" to "${dataDir}"` });
     fs.mkdirSync(path.dirname(dataDir), { recursive: true });
     const stagingDir = path.join(path.dirname(dataDir), `${path.basename(dataDir)}.migrate-${process.pid}-${Date.now()}`);
     let copied;
     let promoted = [];
     try {
-        copied = stagePayload(legacyDir, stagingDir, options.payloadEntries);
-        promoted = promoteStaged(stagingDir, dataDir, copied);
-        (options.writeMarker ?? writeMarkerDefault)(dataDir, legacyDir, markerFile);
+        copied = stagePayload(legacyDir, stagingDir, options.payloadEntries, fs);
+        promoted = promoteStaged({ stagingDir: stagingDir, dataDir: dataDir, entries: copied }, { filesystem: fs });
+        if (options.writeMarker)
+            options.writeMarker({ dataDir, legacyDir, markerFile });
+        else
+            writeMarkerDefault({ dataDir, legacyDir, markerFile }, fs);
     }
     catch (err) {
-        rollbackPromoted(dataDir, promoted);
+        rollbackPromoted(dataDir, promoted, fs);
         fs.rmSync(markerPath, { force: true });
         fs.rmSync(stagingDir, { recursive: true, force: true });
         throw err;
     }
     fs.rmSync(stagingDir, { recursive: true, force: true });
-    log.info(`migration complete: copied ${copied.length} entr${copied.length === 1 ? 'y' : 'ies'} (${copied.join(', ')})`);
+    log.info({ message: `migration complete: copied ${copied.length} entr${copied.length === 1 ? 'y' : 'ies'} (${copied.join(', ')})` });
     return { status: 'migrated', reason: 'copied legacy payload', copied };
 }
 //# sourceMappingURL=legacy-data-migration.js.map

package/dist/read-only-tools.d.ts

@@ -0,0 +1,130 @@
+import { type Principal, type ToolRegistry } from '@jini-ai/core';
+import type { ToolExecutor } from './tool-executor.js';
+import type { IdGenerator } from '@jini-ai/core/primitives';
+/**
+ * A `Principal` narrowed to tools that only read.
+ *
+ * An HTTP route preflight only ever validates the OUTER `toolId` — the one the caller
+ * named in the HTTP request. It cannot see what a consumer's own `ToolExecutor` composition does
+ * once `bridge.execute()` hands control to `deps.toolExecutor`: a decorator that composition
+ * stacks on top of the bare executor (a recovery loop that retries through a different tool id
+ * after a failure, for instance) can dispatch a tool the caller never named, using the exact same
+ * `principal` the outer call carried — one hop past the only check the HTTP route ever ran. Adding a
+ * second request-shaped flag would not close that gap either: it would have to be threaded, by
+ * hand, through every decorator between here and the handler, and a decorator that forgot would
+ * fail open silently. `principal` is the one value every layer already passes unchanged, so the
+ * constraint travels as an ATTENUATED IDENTITY instead — a principal permitted to invoke only
+ * read-only tools, checkable by {@link refuseNonReadOnlyDispatch} at any depth a consumer's own
+ * composition cares to ask.
+ *
+ * A distinct field rather than a `Principal.roles` entry: `roles` is what a `ToolPolicy` branches
+ * on, and a synthetic role would silently join that decision for every registration in the
+ * process. This field is inert to everything except {@link refuseNonReadOnlyDispatch}.
+ */
+export interface ReadOnlyConstrainedPrincipal extends Principal {
+    readonly toolAccess: 'read-only';
+}
+/**
+ * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
+ * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
+ * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
+ */
+export declare const defaultDaemonMessages: {
+    readOnly: {
+        unverifiableMessage: string;
+        toolRefusalMessage: ({ toolId }: {
+            toolId: string;
+        }) => string;
+    };
+};
+/** Required host wording; absent metadata is always a refusal. */
+export interface ReadOnlyToolMessages {
+    readonly unverifiableMessage: string;
+    toolRefusalMessage(required: {
+        toolId: string;
+    }): string;
+}
+export interface ReadOnlyToolCheckRequired {
+    readonly toolId: string;
+    readonly registry: Pick<ToolRegistry, 'list'> | undefined;
+    readonly messages: ReadOnlyToolMessages;
+}
+export interface ReadOnlyToolConstraintRequired {
+    readonly inner: ToolExecutor;
+    readonly registry: Pick<ToolRegistry, 'list'> | undefined;
+    readonly idGenerator: IdGenerator;
+    readonly messages: ReadOnlyToolMessages;
+}
+/** @returns A copied, attenuated principal; its roles are unchanged. */
+export declare function constrainPrincipalToReadOnlyTools({ principal }: {
+    principal: Principal;
+}, _optional?: Record<string, never>): ReadOnlyConstrainedPrincipal;
+/** @returns Whether attenuation survived the executor/decorator boundary. */
+export declare function principalIsReadOnlyConstrained({ principal }: {
+    principal: Principal;
+}, _optional?: Record<string, never>): boolean;
+/** @returns Required host wording for an unknown or non-read-only tool. */
+export declare function readOnlyToolRefusalMessage({ toolId, messages }: {
+    toolId: string;
+    messages: ReadOnlyToolMessages;
+}, _optional?: Record<string, never>): string;
+/**
+ * Single read-only registration decision, shared by routes and inner dispatch.
+ * @returns Null for an explicitly read-only registration, otherwise host refusal text.
+ */
+export declare function checkReadOnlyTool({ toolId, registry, messages }: ReadOnlyToolCheckRequired, _optional?: Record<string, never>): string | null;
+/**
+ * THE read-only dispatch decision for any tool id a consumer's own `ToolExecutor` composition is
+ * about to invoke — the outer call the route already checked, or a nested one a decorator issues
+ * one or more hops in. Every consumer's own composition should ask this before dispatching on
+ * behalf of a principal it did not itself resolve; none should re-implement the check, so changing
+ * what the constraint means stays one edit.
+ *
+ * @param required.principal - The principal the dispatch would run under. Unconstrained ⇒ always
+ *   `null` — this is a no-op for every pre-existing caller that never attenuates a principal.
+ * @param required.toolId - The id actually about to be dispatched, which is not necessarily the id
+ *   named in the original request — that difference is the whole reason this function exists.
+ * @param required.registry - Descriptors to resolve `toolId` against; `undefined` ⇒ refuse (an
+ *   unverifiable constrained dispatch is refused, never waived, matching `checkReadOnlyTool`).
+ * @returns `null` when the dispatch may proceed, otherwise the refusal text to report.
+ * @complexity O(1) for an unconstrained principal; O(n) in registered tool count for a constrained
+ *   one, since `ToolRegistry` exposes enumeration rather than lookup by id.
+ */
+export declare function refuseNonReadOnlyDispatch(required: ReadOnlyToolCheckRequired & {
+    readonly principal: Principal;
+}, _optional?: Record<string, never>): string | null;
+/** @returns Caller-formatted recovery refusal, preserving the original refusal verbatim as input. */
+export declare function readOnlyRemedyRefusalMessage({ refusal, formatMessage }: {
+    refusal: string;
+    formatMessage: (required: {
+        refusal: string;
+    }) => string;
+}, _optional?: Record<string, never>): string;
+/**
+ * Wraps `inner` so a read-only-constrained principal (one {@link constrainPrincipalToReadOnlyTools}
+ * attenuated) cannot dispatch a tool that isn't registered read-only — whichever layer chose the
+ * id. This is what turns the attenuation into an actual gate rather than a field nobody reads:
+ * {@link refuseNonReadOnlyDispatch} is the decision, this is its enforcement point.
+ *
+ * **Compose this as close to the bare `ToolExecutor` as your own stack allows** — directly around
+ * `@jini-ai/daemon`'s `createToolExecutor` output, beneath any decorator of your own that might
+ * dispatch a tool id the caller never named (a retry, a recovery loop that calls a different tool
+ * as a remedy, ...). Every such decorator's own `inner.execute` call still has to come through here
+ * to reach a handler, which is what makes this a gate on the CLASS of defect (an unnamed nested
+ * dispatch) rather than on one instance of it.
+ *
+ * `delegatedToolExecuteRoute`'s own `handle` additionally composes this around whatever
+ * `ToolExecutor` a host supplies, whenever a call attenuates its principal. That outer composition
+ * only re-covers the SAME outer `toolId` the route preflight already checked — it
+ * cannot see a nested dispatch a host's own inner decorator issues, because that decorator holds a
+ * reference to whatever `ToolExecutor` IT was built with, not to the HTTP route's wrapped one. Closing
+ * the nested case for a given host's stack requires that host to compose this decorator itself,
+ * innermost, in its own `ToolExecutor` construction — this export exists so it can, without having
+ * to rediscover or reimplement the mechanism.
+ *
+ * @returns A drop-in `ToolExecutor`; `resumeConfirmation`/`cancel`/`getAuditRecord` delegate
+ *   straight through.
+ * @complexity One extra property read per unconstrained call; one registry scan per constrained one.
+ */
+export declare function withReadOnlyToolConstraint({ inner, registry, idGenerator, messages }: ReadOnlyToolConstraintRequired, _optional?: Record<string, never>): ToolExecutor;
+//# sourceMappingURL=read-only-tools.d.ts.map

package/dist/read-only-tools.js

@@ -0,0 +1,115 @@
+import { isReadOnlyTool } from '@jini-ai/core';
+/**
+ * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
+ * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
+ * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
+ */
+export const defaultDaemonMessages = {
+    readOnly: {
+        unverifiableMessage: 'this host cannot verify read-only tools — POST /api/delegated-tool-calls was mounted without DelegatedToolsHttpDeps.toolRegistry, so a requireReadOnly call cannot be checked and is refused',
+        toolRefusalMessage: ({ toolId }) => `tool "${toolId}" is not registered as read-only — this gateway executes only tools whose registration declares readOnly; call it through execute_delegated_tool instead`,
+    },
+};
+/** @returns A copied, attenuated principal; its roles are unchanged. */
+export function constrainPrincipalToReadOnlyTools({ principal }, _optional = {}) {
+    return { ...principal, toolAccess: 'read-only' };
+}
+// Read structurally so passing through layers typed as the base Principal cannot erase the
+// execution's authority constraint.
+/** @returns Whether attenuation survived the executor/decorator boundary. */
+export function principalIsReadOnlyConstrained({ principal }, _optional = {}) {
+    return 'toolAccess' in principal && principal.toolAccess === 'read-only';
+}
+/** @returns Required host wording for an unknown or non-read-only tool. */
+export function readOnlyToolRefusalMessage({ toolId, messages }, _optional = {}) {
+    return messages.toolRefusalMessage({ toolId });
+}
+// Unknown registrations and omitted read-only classification both lack evidence of safety.
+// Every dispatch/preflight consults this decision; recovery preflight prevents asking a human
+// for form input that the innermost gate would refuse after submission.
+/**
+ * Single read-only registration decision, shared by routes and inner dispatch.
+ * @returns Null for an explicitly read-only registration, otherwise host refusal text.
+ */
+export function checkReadOnlyTool({ toolId, registry, messages }, _optional = {}) {
+    if (registry === undefined)
+        return messages.unverifiableMessage;
+    const descriptor = registry.list({}).find((candidate) => candidate.id === toolId);
+    if (isReadOnlyTool({ descriptor }))
+        return null;
+    return readOnlyToolRefusalMessage({ toolId, messages });
+}
+/**
+ * THE read-only dispatch decision for any tool id a consumer's own `ToolExecutor` composition is
+ * about to invoke — the outer call the route already checked, or a nested one a decorator issues
+ * one or more hops in. Every consumer's own composition should ask this before dispatching on
+ * behalf of a principal it did not itself resolve; none should re-implement the check, so changing
+ * what the constraint means stays one edit.
+ *
+ * @param required.principal - The principal the dispatch would run under. Unconstrained ⇒ always
+ *   `null` — this is a no-op for every pre-existing caller that never attenuates a principal.
+ * @param required.toolId - The id actually about to be dispatched, which is not necessarily the id
+ *   named in the original request — that difference is the whole reason this function exists.
+ * @param required.registry - Descriptors to resolve `toolId` against; `undefined` ⇒ refuse (an
+ *   unverifiable constrained dispatch is refused, never waived, matching `checkReadOnlyTool`).
+ * @returns `null` when the dispatch may proceed, otherwise the refusal text to report.
+ * @complexity O(1) for an unconstrained principal; O(n) in registered tool count for a constrained
+ *   one, since `ToolRegistry` exposes enumeration rather than lookup by id.
+ */
+export function refuseNonReadOnlyDispatch(required, _optional = {}) {
+    if (!principalIsReadOnlyConstrained({ principal: required.principal }))
+        return null;
+    return checkReadOnlyTool(required);
+}
+// Report the original failure alongside the refused remedy; silently hiding an automatic
+// recovery attempt would mislead the caller even when the constraint correctly prevents writes.
+/** @returns Caller-formatted recovery refusal, preserving the original refusal verbatim as input. */
+export function readOnlyRemedyRefusalMessage({ refusal, formatMessage }, _optional = {}) {
+    return formatMessage({ refusal });
+}
+// A route can validate the caller's read-only tool and still miss a recovery decorator choosing
+// a writing remedy afterward. Enforce on every actual dispatch at the innermost executor to
+// close that class of authority laundering, including dispatchers introduced later.
+/**
+ * Wraps `inner` so a read-only-constrained principal (one {@link constrainPrincipalToReadOnlyTools}
+ * attenuated) cannot dispatch a tool that isn't registered read-only — whichever layer chose the
+ * id. This is what turns the attenuation into an actual gate rather than a field nobody reads:
+ * {@link refuseNonReadOnlyDispatch} is the decision, this is its enforcement point.
+ *
+ * **Compose this as close to the bare `ToolExecutor` as your own stack allows** — directly around
+ * `@jini-ai/daemon`'s `createToolExecutor` output, beneath any decorator of your own that might
+ * dispatch a tool id the caller never named (a retry, a recovery loop that calls a different tool
+ * as a remedy, ...). Every such decorator's own `inner.execute` call still has to come through here
+ * to reach a handler, which is what makes this a gate on the CLASS of defect (an unnamed nested
+ * dispatch) rather than on one instance of it.
+ *
+ * `delegatedToolExecuteRoute`'s own `handle` additionally composes this around whatever
+ * `ToolExecutor` a host supplies, whenever a call attenuates its principal. That outer composition
+ * only re-covers the SAME outer `toolId` the route preflight already checked — it
+ * cannot see a nested dispatch a host's own inner decorator issues, because that decorator holds a
+ * reference to whatever `ToolExecutor` IT was built with, not to the HTTP route's wrapped one. Closing
+ * the nested case for a given host's stack requires that host to compose this decorator itself,
+ * innermost, in its own `ToolExecutor` construction — this export exists so it can, without having
+ * to rediscover or reimplement the mechanism.
+ *
+ * @returns A drop-in `ToolExecutor`; `resumeConfirmation`/`cancel`/`getAuditRecord` delegate
+ *   straight through.
+ * @complexity One extra property read per unconstrained call; one registry scan per constrained one.
+ */
+export function withReadOnlyToolConstraint({ inner, registry, idGenerator, messages }, _optional = {}) {
+    return {
+        execute: async (requiredArgs, optionalArgs = {}) => {
+            const { principal, toolId } = requiredArgs;
+            const refusal = refuseNonReadOnlyDispatch({ principal, toolId, registry, messages });
+            // Deny before inner: no handler or kernel audit record exists. Use the authorization result
+            // union instead of throwing, and mint a denial ID because there is no inner execution ID.
+            if (refusal !== null)
+                return { executionId: idGenerator.newId(), status: 'denied', error: refusal };
+            return inner.execute(requiredArgs, optionalArgs);
+        },
+        resumeConfirmation: (requiredArgs) => inner.resumeConfirmation(requiredArgs),
+        cancel: (requiredArgs) => inner.cancel(requiredArgs),
+        getAuditRecord: (requiredArgs) => inner.getAuditRecord(requiredArgs),
+    };
+}
+//# sourceMappingURL=read-only-tools.js.map

package/dist/remote-tool-bridge.d.ts

@@ -7,11 +7,11 @@
  * This exists because `DelegatedToolBridge.execute()` (this package's `delegated-tool-bridge.ts`)
  * calls `lifecycle.emit()` directly, in-process — there was previously no way for a caller that
  * executed a tool somewhere else to report the outcome back into this run's log. That absence is
- * what forced `ToolExecutor`/`ToolRegistry`/`RunLifecycle` to all live in one process per run (see
- * this repo's own `tovu-learnings.md` §1a). This module is the missing half: the same two event
+ * what forced `ToolExecutor`/`ToolRegistry`/`RunLifecycle` to live in one process per run: only an
+ * in-process lifecycle could append those events. This module supplies the same two event
  * shapes `DelegatedToolBridge.execute()` already emits (`tool_use` then `tool_result`), exposed as
  * a small, explicit recording API a *transport* (this package does not itself expose one — see
- * `@jini-ai/http-kit`'s `remote-run-events.ts`) can wrap with authentication and call remotely.
+ * `@jini-ai/daemon/http`'s `remote-run-events.ts`) can wrap with authentication and call remotely.
  *
  * This does not change how tool execution is authorized. A caller of `recordToolUse`/
  * `recordToolResult` has, by definition, already run the tool through its OWN `ToolExecutor` (with
@@ -34,9 +34,15 @@ export interface RemoteToolResultRecord {
 }
 export interface RemoteToolEventRecorder {
     /** Records that a tool call started. Throws (matching `RunLifecycle.emit`) if `runId` is unknown or already terminal. */
-    recordToolUse(runId: string, record: RemoteToolUseRecord): Promise<RunProtocolEvent>;
+    recordToolUse(args: {
+        readonly runId: string;
+        readonly record: RemoteToolUseRecord;
+    }): Promise<RunProtocolEvent>;
     /** Records that a tool call finished (or failed) — mirrors `DelegatedToolBridge.execute()`'s own `tool_result` shape exactly. */
-    recordToolResult(runId: string, record: RemoteToolResultRecord): Promise<RunProtocolEvent>;
+    recordToolResult(args: {
+        readonly runId: string;
+        readonly record: RemoteToolResultRecord;
+    }): Promise<RunProtocolEvent>;
 }
 export interface CreateRemoteToolEventRecorderOptions {
     readonly lifecycle: RunLifecycle;

package/dist/remote-tool-bridge.js

@@ -1,22 +1,22 @@
 export function createRemoteToolEventRecorder(options) {
     const { lifecycle } = options;
     return {
-        recordToolUse(runId, record) {
-            return lifecycle.emit(runId, {
-                event: 'agent',
-                data: { type: 'tool_use', id: record.toolUseId, name: record.toolId, input: record.input },
-            });
+        recordToolUse({ runId, record }) {
+            return lifecycle.emit({ runId: runId, input: {
+                    event: 'agent',
+                    data: { type: 'tool_use', id: record.toolUseId, name: record.toolId, input: record.input },
+                } });
         },
-        recordToolResult(runId, record) {
-            return lifecycle.emit(runId, {
-                event: 'agent',
-                data: {
-                    type: 'tool_result',
-                    toolUseId: record.toolUseId,
-                    content: record.content,
-                    ...(record.isError ? { isError: true } : {}),
-                },
-            });
+        recordToolResult({ runId, record }) {
+            return lifecycle.emit({ runId: runId, input: {
+                    event: 'agent',
+                    data: {
+                        type: 'tool_result',
+                        toolUseId: record.toolUseId,
+                        content: record.content,
+                        ...(record.isError ? { isError: true } : {}),
+                    },
+                } });
         },
     };
 }

package/dist/routines/index.d.ts

@@ -3,7 +3,7 @@
  *
  * The routine scheduler ({@link ./scheduler.js}'s `RoutineService`, `./schedule.js`'s DST-safe
  * wall-clock math) plus its HTTP-facing CRUD + run-history counterpart ({@link ./routine-store.js}'s
- * `RoutineStore`). See `../../source-map.md`'s dated routines section for full provenance.
+ * `RoutineStore`). See `../../archived provenance ledger`'s dated routines section for full provenance.
  */
 export * from './types.js';
 export * from './schedule.js';

package/dist/routines/index.js

@@ -3,7 +3,7 @@
  *
  * The routine scheduler ({@link ./scheduler.js}'s `RoutineService`, `./schedule.js`'s DST-safe
  * wall-clock math) plus its HTTP-facing CRUD + run-history counterpart ({@link ./routine-store.js}'s
- * `RoutineStore`). See `../../source-map.md`'s dated routines section for full provenance.
+ * `RoutineStore`). See `../../archived provenance ledger`'s dated routines section for full provenance.
  */
 export * from './types.js';
 export * from './schedule.js';