@jini-ai/daemon 0.6.7 → 0.6.9

package/dist/http/terminals.js

@@ -33,15 +33,13 @@ import { guardSameOrigin } from '@jini-ai/http-kit';
 import { validationError } from '@jini-ai/http-kit';
 import { sendApiError, statusForError } from '@jini-ai/http-kit';
 import { createSseChannel, requestedAfterCursor } from '@jini-ai/http-kit';
-import { denyAllWorkspaceRoots, resolveWorkspaceRoot, WorkspaceRootDeniedError } from './workspace-root.js';
+import { denyAllWorkspaceRoots } from './workspace-root.js';
+import { isRecord, readOptionalNonEmptyString, readOptionalNumber, resolveResourceRoot, withoutUndefined } from './resource-request.js';
 import { err, ok } from '@jini-ai/http-kit';
 function defaultTerminalsInternalErrorSink(context) {
     // eslint-disable-next-line no-console
     console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 /** Every one-off `terminal.create` tool call gets its own opaque `RunRef` — matching `db-ops.ts`'s `freshRun()`: these are single requests, not steps of a longer-lived agent run. */
 function freshRun() {
     return { id: randomUUID() };
@@ -65,37 +63,27 @@ function toolResultToApiResult(deps, result) {
     }
 }
 function parseTerminalCreate(input) {
-    if (!isRecord(input.body))
+    const body = input.body;
+    if (!isRecord(body))
         return err({ error: validationError({ message: 'body must be a JSON object' }) });
-    const resourceRef = input.body.resourceRef;
+    const resourceRef = body.resourceRef;
     if (typeof resourceRef !== 'string' || resourceRef.length === 0) {
         return err({ error: validationError({ message: 'resourceRef is required' }, { issues: [{ path: 'resourceRef', message: 'required non-empty string' }] }) });
     }
-    const detail = input.body.detail;
-    if (detail !== undefined && (typeof detail !== 'string' || detail.length === 0)) {
-        return err({ error: validationError({ message: 'detail must be a non-empty string when provided' }) });
-    }
-    const cols = input.body.cols;
-    if (cols !== undefined && typeof cols !== 'number') {
-        return err({ error: validationError({ message: 'cols must be a number when provided' }) });
-    }
-    const rows = input.body.rows;
-    if (rows !== undefined && typeof rows !== 'number') {
-        return err({ error: validationError({ message: 'rows must be a number when provided' }) });
-    }
-    const shell = input.body.shell;
-    if (shell !== undefined && (typeof shell !== 'string' || shell.length === 0)) {
-        return err({ error: validationError({ message: 'shell must be a non-empty string when provided' }) });
-    }
-    return ok({
-        value: {
-            resourceRef,
-            ...(detail === undefined ? {} : { detail }),
-            ...(cols === undefined ? {} : { cols }),
-            ...(rows === undefined ? {} : { rows }),
-            ...(shell === undefined ? {} : { shell }),
-        }
-    });
+    // Checked in this fixed order: the first invalid field is the one reported.
+    const detail = readOptionalNonEmptyString({ body, field: 'detail' });
+    if (!detail.ok)
+        return detail;
+    const cols = readOptionalNumber({ body, field: 'cols' });
+    if (!cols.ok)
+        return cols;
+    const rows = readOptionalNumber({ body, field: 'rows' });
+    if (!rows.ok)
+        return rows;
+    const shell = readOptionalNonEmptyString({ body, field: 'shell' });
+    if (!shell.ok)
+        return shell;
+    return ok({ value: { resourceRef, ...withoutUndefined({ detail: detail.value, cols: cols.value, rows: rows.value, shell: shell.value }) } });
 }
 /**
  * `POST /api/terminals` — the one gated call (see module doc). Resolves
@@ -105,23 +93,10 @@ function parseTerminalCreate(input) {
  */
 export const terminalCreateRoute = defineJsonRoute({
     method: 'post', path: '/api/terminals', parse: parseTerminalCreate, handle: async ({ input, deps }) => {
-        let cwd;
-        try {
-            cwd = await resolveWorkspaceRoot({ request: { resourceRef: input.resourceRef, ...(input.detail === undefined ? {} : { detail: input.detail }) } }, { resolver: deps.resolveRoot ?? denyAllWorkspaceRoots });
-        }
-        catch (error) {
-            if (error instanceof WorkspaceRootDeniedError) {
-                return err({ error: createApiError({ code: 'NOT_FOUND', message: `resource "${input.resourceRef}" was not found` }) });
-            }
-            throw error;
-        }
-        const toolInput = {
-            resourceRef: input.resourceRef,
-            cwd,
-            ...(input.cols === undefined ? {} : { cols: input.cols }),
-            ...(input.rows === undefined ? {} : { rows: input.rows }),
-            ...(input.shell === undefined ? {} : { shell: input.shell }),
-        };
+        const root = await resolveResourceRoot({ resourceRef: input.resourceRef, detail: input.detail }, { resolver: deps.resolveRoot ?? denyAllWorkspaceRoots });
+        if (!root.ok)
+            return root;
+        const toolInput = { resourceRef: input.resourceRef, cwd: root.value, ...withoutUndefined({ cols: input.cols, rows: input.rows, shell: input.shell }) };
         const result = await deps.toolExecutor.execute({ principal: deps.principal, run: freshRun(), toolId: TERMINAL_CREATE_TOOL_ID, input: toolInput });
         return toolResultToApiResult(deps, result);
     }

package/dist/http/tool-catalog.d.ts

@@ -18,15 +18,20 @@
  * gate is still `ToolExecutor`, reached only via `execute_delegated_tool`
  * (`packages/daemon/src/delegated-tool-bridge.ts`) — finding a tool id here grants nothing.
  */
+import type { AgentToolSideEffect } from '@jini-ai/core';
 import type { Express } from 'express';
 import { type AdapterContext } from '@jini-ai/http-kit';
 export interface ToolCatalogSearchHit {
+    readonly readOnly?: boolean;
+    readonly sideEffects?: AgentToolSideEffect | 'unknown';
     readonly id: string;
     readonly description: string;
     readonly source: string;
     readonly score: number;
 }
 export interface ToolCatalogEntry {
+    readonly readOnly?: boolean;
+    readonly sideEffects?: AgentToolSideEffect | 'unknown';
     readonly id: string;
     readonly description: string;
     readonly inputSchema?: unknown;

package/dist/http/xai.d.ts

@@ -1,5 +1,5 @@
 import type { Express } from 'express';
-import { PendingAuthCache, startOAuthCallbackListener, type OAuthCallbackListener, type OAuthPkceProviderConfig } from '@jini-ai/agent-runtime';
+import { PendingAuthCache, startOAuthCallbackListener, type OAuthCallbackListener, type OAuthPkceProviderConfig, type OAuthTokenResponse, type StoredOAuthToken } from '@jini-ai/agent-runtime';
 import { type AdapterContext } from '@jini-ai/http-kit';
 export interface XaiInternalErrorContext {
     readonly source: 'oauth-start' | 'oauth-complete' | 'oauth-disconnect' | 'auth-status' | 'search';
@@ -37,6 +37,16 @@ export interface XaiHttpDeps {
     /** Host-owned sink for the real exception behind a generic `INTERNAL_ERROR` response (SEC-005). Defaults to `console.error`. */
     readonly onInternalError?: (context: XaiInternalErrorContext) => void;
 }
+/**
+ * Maps a token-endpoint response onto the persisted record. Pure (the save instant is a parameter)
+ * so the mapping is testable on its own. `token_type` is optional on the wire type; today's
+ * exchange path always supplies it (openid-client rejects a response without one), and an absent
+ * value is stored as RFC 6750's `Bearer`. Exported for this module's tests; not re-exported.
+ */
+export declare function toStoredOAuthToken({ tokenResp, nowMs }: {
+    tokenResp: OAuthTokenResponse;
+    nowMs: number;
+}): StoredOAuthToken;
 export interface XaiOauthStartResponse {
     readonly authorizeUrl: string;
     readonly state: string;

package/dist/http/xai.js

@@ -138,9 +138,11 @@ function defaultInternalErrorSink(context) {
 }
 /** Resolves every optional `XaiHttpDeps` field to a concrete value. Idempotent — calling this again on an already-resolved object (e.g. `registerXaiRoutes`'s own single resolution, passed through to each route's `handle`) is a harmless pass-through. See module doc on why stateful fields (`pending`/`listenerRef`) must be resolved once per registration, not once per request. */
 function resolveXaiHttpDeps(deps) {
+    return { ...resolveOAuthFlowDeps(deps), ...resolveStorageAndSearchDeps(deps) };
+}
+/** The OAuth dance's provider, loopback-callback and in-flight state defaults. */
+function resolveOAuthFlowDeps(deps) {
     return {
-        dataDir: deps.dataDir ?? process.cwd(),
-        tokenFileName: deps.tokenFileName ?? DEFAULT_TOKEN_FILE_NAME,
         providerConfig: deps.providerConfig ?? XAI_OAUTH_PROVIDER_CONFIG,
         callbackHost: deps.callbackHost ?? XAI_OAUTH_REDIRECT_HOST,
         callbackPort: deps.callbackPort ?? XAI_OAUTH_REDIRECT_PORT,
@@ -148,6 +150,13 @@ function resolveXaiHttpDeps(deps) {
         pending: deps.pending ?? new PendingAuthCache({}, { ttlMs: DEFAULT_PENDING_AUTH_TTL_MS }),
         listenerRef: deps.listenerRef ?? { current: null },
         startCallbackListener: deps.startCallbackListener ?? startOAuthCallbackListener,
+    };
+}
+/** Token storage, search transport and error-sink defaults. */
+function resolveStorageAndSearchDeps(deps) {
+    return {
+        dataDir: deps.dataDir ?? process.cwd(),
+        tokenFileName: deps.tokenFileName ?? DEFAULT_TOKEN_FILE_NAME,
         searchBaseUrl: deps.searchBaseUrl ?? DEFAULT_SEARCH_BASE_URL,
         searchDefaultModel: deps.searchDefaultModel ?? DEFAULT_SEARCH_MODEL,
         fetchImpl: deps.fetchImpl ?? fetch,
@@ -201,19 +210,29 @@ function redactError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return new Error(redactSecrets({ input: message }));
 }
-async function persistToken(resolved, tokenResp) {
+/**
+ * Maps a token-endpoint response onto the persisted record. Pure (the save instant is a parameter)
+ * so the mapping is testable on its own. `token_type` is optional on the wire type; today's
+ * exchange path always supplies it (openid-client rejects a response without one), and an absent
+ * value is stored as RFC 6750's `Bearer`. Exported for this module's tests; not re-exported.
+ */
+export function toStoredOAuthToken({ tokenResp, nowMs }) {
     const stored = {
         accessToken: tokenResp.access_token,
         tokenType: tokenResp.token_type ?? 'Bearer',
-        savedAt: Date.now(),
+        savedAt: nowMs,
     };
     if (tokenResp.refresh_token)
         stored.refreshToken = tokenResp.refresh_token;
     if (tokenResp.scope)
         stored.scope = tokenResp.scope;
     if (typeof tokenResp.expires_in === 'number') {
-        stored.expiresAt = Date.now() + tokenResp.expires_in * 1000;
+        stored.expiresAt = nowMs + tokenResp.expires_in * 1000;
     }
+    return stored;
+}
+async function persistToken(resolved, tokenResp) {
+    const stored = toStoredOAuthToken({ tokenResp, nowMs: Date.now() });
     await setStoredOAuthToken({ dataDir: resolved.dataDir, fileName: resolved.tokenFileName, token: stored });
 }
 /** Invoked when the loopback listener actually receives xAI's redirect (the real-browser path, as opposed to `oauth/complete`'s manual paste-back path — xAI's own docs note the loopback redirect commonly shows the user a code to paste rather than following the redirect). No HTTP response to write here; failures are only reported through the internal-error sink. */
@@ -448,107 +467,69 @@ function parseXaiSearch(input) {
     const query = nonEmptyString(body.query);
     if (!query)
         return err({ error: validationError({ message: 'query must be a non-empty string' }, { issues: [{ path: 'query', message: 'required non-empty string' }] }) });
-    const allowedXHandles = parseOptionalStringArray(body, 'allowedXHandles');
-    if (!allowedXHandles.ok)
-        return allowedXHandles;
-    const excludedXHandles = parseOptionalStringArray(body, 'excludedXHandles');
-    if (!excludedXHandles.ok)
-        return excludedXHandles;
-    const fromDate = parseOptionalString(body, 'fromDate');
-    if (!fromDate.ok)
-        return fromDate;
-    const toDate = parseOptionalString(body, 'toDate');
-    if (!toDate.ok)
-        return toDate;
-    const enableImageUnderstanding = parseOptionalBoolean(body, 'enableImageUnderstanding');
-    if (!enableImageUnderstanding.ok)
-        return enableImageUnderstanding;
-    const enableVideoUnderstanding = parseOptionalBoolean(body, 'enableVideoUnderstanding');
-    if (!enableVideoUnderstanding.ok)
-        return enableVideoUnderstanding;
-    const model = parseOptionalString(body, 'model');
-    if (!model.ok)
-        return model;
-    return ok({
-        value: {
-            query,
-            ...(allowedXHandles.value?.length ? { allowedXHandles: allowedXHandles.value } : {}),
-            ...(excludedXHandles.value?.length ? { excludedXHandles: excludedXHandles.value } : {}),
-            ...(fromDate.value ? { fromDate: fromDate.value } : {}),
-            ...(toDate.value ? { toDate: toDate.value } : {}),
-            ...(enableImageUnderstanding.value !== undefined ? { enableImageUnderstanding: enableImageUnderstanding.value } : {}),
-            ...(enableVideoUnderstanding.value !== undefined ? { enableVideoUnderstanding: enableVideoUnderstanding.value } : {}),
-            ...(model.value ? { model: model.value } : {}),
-        }
-    });
+    const fields = {};
+    for (const [key, parse] of XAI_SEARCH_OPTIONAL_FIELDS) {
+        const parsed = parse(body, key);
+        if (!parsed.ok)
+            return parsed;
+        if (isProvidedSearchValue(parsed.value))
+            fields[key] = parsed.value;
+    }
+    return ok({ value: { query, ...fields } });
+}
+/** Table order is the validation order: the first failing field is the one a caller sees. */
+const XAI_SEARCH_OPTIONAL_FIELDS = [
+    ['allowedXHandles', parseOptionalStringArray],
+    ['excludedXHandles', parseOptionalStringArray],
+    ['fromDate', parseOptionalString],
+    ['toDate', parseOptionalString],
+    ['enableImageUnderstanding', parseOptionalBoolean],
+    ['enableVideoUnderstanding', parseOptionalBoolean],
+    ['model', parseOptionalString],
+];
+/** An empty string or empty handle list counts as not provided (dropped from the request); `false` is kept. */
+function isProvidedSearchValue(value) {
+    if (Array.isArray(value))
+        return value.length > 0;
+    return value !== undefined && value !== '';
+}
+/** Every well-formed `output[].content[]` block of a Responses-API payload, skipping malformed items and blocks. */
+function outputContentBlocks(data) {
+    const output = data.output;
+    if (!Array.isArray(output))
+        return [];
+    return output.filter(isRecord).flatMap((item) => (Array.isArray(item.content) ? item.content.filter(isRecord) : []));
 }
-/** Pulls the assistant's main text out of an xAI Responses-API payload — the convenience `output_text` field, or the structured `output[].content[].text` form. Ported verbatim from OD's `extractAnswerText`. */
+/** Pulls the assistant's main text out of an xAI Responses-API payload — the convenience `output_text` field, or the structured `output[].content[].text` form. Ported from OD's `extractAnswerText` (same behaviour; the walk is shared with `extractUrlCitations` via `outputContentBlocks`). */
 function extractAnswerText(data) {
     if (!isRecord(data))
         return '';
     const direct = data.output_text;
     if (typeof direct === 'string' && direct.trim())
         return direct;
-    const output = data.output;
-    if (!Array.isArray(output))
-        return '';
-    const chunks = [];
-    for (const item of output) {
-        if (!isRecord(item))
-            continue;
-        const content = item.content;
-        if (!Array.isArray(content))
-            continue;
-        for (const block of content) {
-            if (!isRecord(block))
-                continue;
-            const t = block.text;
-            if (typeof t === 'string' && t)
-                chunks.push(t);
-        }
-    }
+    const chunks = outputContentBlocks(data)
+        .map((block) => block.text)
+        .filter((text) => typeof text === 'string' && text.length > 0);
     return chunks.join('\n').trim();
 }
-/** Walks every annotation in the Responses-API output and returns the unique URL citations (`type: 'url_citation'`). Ported verbatim from OD's `extractUrlCitations`. */
+/** The trimmed URL of one `url_citation` annotation, or `''` for anything else. */
+function urlCitationOf(annotation) {
+    if (!isRecord(annotation) || annotation.type !== 'url_citation')
+        return '';
+    return typeof annotation.url === 'string' ? annotation.url.trim() : '';
+}
+/** Walks every annotation in the Responses-API output and returns the unique URL citations (`type: 'url_citation'`). Ported from OD's `extractUrlCitations` (same behaviour, first-seen order). */
 function extractUrlCitations(data) {
     if (!isRecord(data))
         return [];
-    const output = data.output;
-    if (!Array.isArray(output))
-        return [];
-    const urls = new Set();
-    for (const item of output) {
-        if (!isRecord(item))
-            continue;
-        const content = item.content;
-        if (!Array.isArray(content))
-            continue;
-        for (const block of content) {
-            if (!isRecord(block))
-                continue;
-            const annotations = block.annotations;
-            if (!Array.isArray(annotations))
-                continue;
-            for (const ann of annotations) {
-                if (!isRecord(ann))
-                    continue;
-                if (ann.type !== 'url_citation')
-                    continue;
-                const url = typeof ann.url === 'string' ? ann.url.trim() : '';
-                if (url)
-                    urls.add(url);
-            }
-        }
-    }
-    return [...urls];
+    const urls = outputContentBlocks(data)
+        .flatMap((block) => (Array.isArray(block.annotations) ? block.annotations : []))
+        .map(urlCitationOf)
+        .filter((url) => url.length > 0);
+    return [...new Set(urls)];
 }
-/** Calls xAI's real `POST {searchBaseUrl}/responses` endpoint with the `x_search` native tool, using `accessToken` as the bearer credential. Throws (never a `Result`) on any failure — `xaiSearchRoute.handle` is the one place that converts a thrown error into this package's SEC-005 response shape. Any thrown message is pre-redacted of `accessToken` here so the sink never even logs it unredacted. */
-async function callXaiSearch(resolved, accessToken, request) {
-    const baseUrlCheck = validateBaseUrl({ baseUrl: resolved.searchBaseUrl });
-    if (baseUrlCheck.error)
-        throw new Error(baseUrlCheck.error);
-    const base = resolved.searchBaseUrl.replace(/\/+$/, '');
-    const model = request.model ?? resolved.searchDefaultModel;
+/** Builds the `x_search` native tool payload, translating only the provided fields to xAI's snake_case names. */
+function buildXSearchTool(request) {
     const xSearchTool = { type: 'x_search' };
     if (request.allowedXHandles?.length)
         xSearchTool.allowed_x_handles = request.allowedXHandles;
@@ -562,10 +543,53 @@ async function callXaiSearch(resolved, accessToken, request) {
         xSearchTool.enable_image_understanding = true;
     if (request.enableVideoUnderstanding === true)
         xSearchTool.enable_video_understanding = true;
+    return xSearchTool;
+}
+/** A thrown fetch/body-read failure as the timeout message when the deadline fired, else as a `prefix: message` with `accessToken` redacted. */
+function xaiCallFailure(guard, prefix, error) {
+    if (guard.signal.aborted)
+        return new Error(guard.timedOutMessage);
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(redactSecrets({ input: `${prefix}: ${message}` }, { exactSecrets: [guard.accessToken] }));
+}
+async function postXaiResponses({ fetchImpl, url, requestBody, guard }) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${guard.accessToken}`, 'content-type': 'application/json' },
+            body: JSON.stringify(requestBody),
+            signal: guard.signal,
+        });
+    }
+    catch (error) {
+        throw xaiCallFailure(guard, 'xAI request failed', error);
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(redactSecrets({ input: `xAI ${response.status}: ${text.slice(0, 240) || 'no body'}` }, { exactSecrets: [guard.accessToken] }));
+    }
+    return response;
+}
+async function readXaiJson(response, guard) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        throw xaiCallFailure(guard, 'xAI response could not be read', error);
+    }
+}
+/** Calls xAI's real `POST {searchBaseUrl}/responses` endpoint with the `x_search` native tool, using `accessToken` as the bearer credential. Throws (never a `Result`) on any failure — `xaiSearchRoute.handle` is the one place that converts a thrown error into this package's SEC-005 response shape. Any thrown message is pre-redacted of `accessToken` here so the sink never even logs it unredacted. */
+async function callXaiSearch(resolved, accessToken, request) {
+    const baseUrlCheck = validateBaseUrl({ baseUrl: resolved.searchBaseUrl });
+    if (baseUrlCheck.error)
+        throw new Error(baseUrlCheck.error);
+    const base = resolved.searchBaseUrl.replace(/\/+$/, '');
+    const model = request.model ?? resolved.searchDefaultModel;
     const requestBody = {
         model,
         input: [{ role: 'user', content: request.query }],
-        tools: [xSearchTool],
+        tools: [buildXSearchTool(request)],
         store: false,
     };
     // One deadline covering the request *and* the body read, mirroring `research.ts`'s Tavily call.
@@ -575,37 +599,14 @@ async function callXaiSearch(resolved, accessToken, request) {
     // does not leave one armed.
     const timeoutController = new AbortController();
     const timeoutHandle = setTimeout(() => timeoutController.abort(), resolved.searchTimeoutMs);
-    const timedOutMessage = `xAI request timed out after ${resolved.searchTimeoutMs}ms`;
+    const guard = {
+        signal: timeoutController.signal,
+        timedOutMessage: `xAI request timed out after ${resolved.searchTimeoutMs}ms`,
+        accessToken,
+    };
     try {
-        let response;
-        try {
-            response = await resolved.fetchImpl(`${base}/responses`, {
-                method: 'POST',
-                headers: { authorization: `Bearer ${accessToken}`, 'content-type': 'application/json' },
-                body: JSON.stringify(requestBody),
-                signal: timeoutController.signal,
-            });
-        }
-        catch (error) {
-            if (timeoutController.signal.aborted)
-                throw new Error(timedOutMessage);
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(redactSecrets({ input: `xAI request failed: ${message}` }, { exactSecrets: [accessToken] }));
-        }
-        if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new Error(redactSecrets({ input: `xAI ${response.status}: ${text.slice(0, 240) || 'no body'}` }, { exactSecrets: [accessToken] }));
-        }
-        let data;
-        try {
-            data = await response.json();
-        }
-        catch (error) {
-            if (timeoutController.signal.aborted)
-                throw new Error(timedOutMessage);
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(redactSecrets({ input: `xAI response could not be read: ${message}` }, { exactSecrets: [accessToken] }));
-        }
+        const response = await postXaiResponses({ fetchImpl: resolved.fetchImpl, url: `${base}/responses`, requestBody, guard });
+        const data = await readXaiJson(response, guard);
         return { answer: extractAnswerText(data), citations: extractUrlCitations(data), model };
     }
     finally {

package/dist/legacy-data-migration.js

@@ -180,27 +180,13 @@ function writeMarkerDefault({ dataDir, legacyDir, markerFile }, fs) {
         throw err;
     }
 }
-/**
- * One-shot, idempotent legacy data migrator. Synchronous so it can run at
- * module import time before a database connection opens. Throws
- * {@link LegacyMigrationError} on operator-actionable failures (env set but
- * path invalid; `dataDir` already populated; symlink in payload).
- *
- * @param options - Legacy/current dir paths plus the host's payload config.
- * @returns The migration outcome (`noop` when unconfigured, `skipped` when
- *   already migrated, `migrated` with the copied entry list otherwise).
- */
-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;
+/** Resolve both roots and decide the no-op/skip outcomes; a plan means migration must proceed. */
+function planMigration({ legacyDir: raw, dataDir: rawDataDir, markerFile }, fs) {
     if (raw === undefined || raw.length === 0) {
         return { status: 'noop', reason: 'legacy data dir not configured' };
     }
     const legacyDir = path.resolve(raw);
-    const dataDir = path.resolve(options.dataDir);
+    const dataDir = path.resolve(rawDataDir);
     if (legacyDir === dataDir) {
         return { status: 'noop', reason: 'legacy data dir equals current data dir' };
     }
@@ -211,23 +197,30 @@ export function migrateLegacyDataDirSync(requiredArgs, optionalArgs = {}) {
     if (fs.existsSync(markerPath)) {
         return { status: 'skipped', reason: 'migration marker already present' };
     }
-    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).` });
+    return { legacyDir, dataDir, markerPath };
+}
+/** Refuse loudly when the legacy source is unusable or the destination already holds payload. */
+function assertMigratable({ legacyDir, dataDir, config }, fs) {
+    if (!legacyDirHasPayload({ legacyDir: legacyDir, config }, { filesystem: fs })) {
+        throw new LegacyMigrationError({ code: 'legacy_dir_invalid', message: `legacy data dir "${legacyDir}" is not a usable legacy data dir (expected "${config.proofEntry}" directly inside it).` });
     }
-    const existing = dataDirHasExistingPayload({ dataDir: dataDir, config: options }, { filesystem: fs });
+    const existing = dataDirHasExistingPayload({ dataDir: dataDir, config }, { filesystem: fs });
     if (existing.length > 0) {
         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({ message: `migrating legacy data from "${legacyDir}" to "${dataDir}"` });
+}
+/** Stage, promote and mark; any failure removes promoted entries, the marker and the staging dir. */
+function stagePromoteAndMark({ plan, markerFile, payloadEntries, writeMarker }, fs) {
+    const { legacyDir, dataDir, markerPath } = plan;
     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, fs);
+        copied = stagePayload(legacyDir, stagingDir, payloadEntries, fs);
         promoted = promoteStaged({ stagingDir: stagingDir, dataDir: dataDir, entries: copied }, { filesystem: fs });
-        if (options.writeMarker)
-            options.writeMarker({ dataDir, legacyDir, markerFile });
+        if (writeMarker)
+            writeMarker({ dataDir, legacyDir, markerFile });
         else
             writeMarkerDefault({ dataDir, legacyDir, markerFile }, fs);
     }
@@ -238,6 +231,30 @@ export function migrateLegacyDataDirSync(requiredArgs, optionalArgs = {}) {
         throw err;
     }
     fs.rmSync(stagingDir, { recursive: true, force: true });
+    return copied;
+}
+/**
+ * One-shot, idempotent legacy data migrator. Synchronous so it can run at
+ * module import time before a database connection opens. Throws
+ * {@link LegacyMigrationError} on operator-actionable failures (env set but
+ * path invalid; `dataDir` already populated; symlink in payload).
+ *
+ * @param options - Legacy/current dir paths plus the host's payload config.
+ * @returns The migration outcome (`noop` when unconfigured, `skipped` when
+ *   already migrated, `migrated` with the copied entry list otherwise).
+ */
+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 plan = planMigration({ legacyDir: options.legacyDir, dataDir: options.dataDir, markerFile }, fs);
+    if ('status' in plan)
+        return plan;
+    const { legacyDir, dataDir } = plan;
+    assertMigratable({ legacyDir, dataDir, config: options }, fs);
+    log.info({ message: `migrating legacy data from "${legacyDir}" to "${dataDir}"` });
+    const copied = stagePromoteAndMark({ plan, markerFile, payloadEntries: options.payloadEntries, writeMarker: options.writeMarker }, fs);
     log.info({ message: `migration complete: copied ${copied.length} entr${copied.length === 1 ? 'y' : 'ies'} (${copied.join(', ')})` });
     return { status: 'migrated', reason: 'copied legacy payload', copied };
 }