@fnndsc/salsa 3.5.1 → 3.6.0

package/dist/retrieve/watch.js

@@ -0,0 +1,360 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieveTask_make = retrieveTask_make;
+exports.retrieveProgress_classify = retrieveProgress_classify;
+exports.retrieveTasks_skipComplete = retrieveTasks_skipComplete;
+exports.retrieveTasks_fire = retrieveTasks_fire;
+exports.retrieve_fireAndWatch = retrieve_fireAndWatch;
+exports.retrieve_confirmLoop = retrieve_confirmLoop;
+/**
+ * @file PACS retrieve engine: fire, watch, confirm.
+ *
+ * The single implementation of "make DICOM series land in CUBE and know when
+ * they have": synthetic query+retrieve firing with bounded concurrency and
+ * per-step retry, a LONK WebSocket watch with stall/timeout/no-activity
+ * detection, storage-side confirmation across registration lag, and an
+ * optional refire loop for unconfirmed series. Both consumers (the `pull`
+ * builtin in brasa and the PACS VFS provider's `cp`) previously solved this
+ * independently — LONK push versus 5-second polling — with different
+ * semantics; this module is the convergence (docs/code-audit-2026-08.adoc,
+ * decisions section).
+ *
+ * The engine is presentation-free: progress is reported through the
+ * {@link RetrieveWatchEvents} callbacks and consumers render it however their
+ * surface renders (structured sink progress, plain console lines).
+ *
+ * @module
+ */
+const ws_1 = __importDefault(require("ws"));
+const cumin_1 = require("@fnndsc/cumin");
+/** Concurrent retrieve creations; more overloads CUBE and loses retrieves. */
+const FIRE_CONCURRENCY = 4;
+/** Retry attempts for one retrieve creation, with backoff between them. */
+const FIRE_ATTEMPTS = 3;
+const FIRE_BACKOFF_MS = [250, 500];
+const STALL_TIMEOUT_MS = 30_000;
+const NO_ACTIVITY_TIMEOUT_MS = 15_000;
+const SERIES_TIMEOUT_MS = 5 * 60 * 1_000;
+const CHECKER_INTERVAL_MS = 2_000;
+/**
+ * Builds a fresh retrieve task from series identity facts.
+ *
+ * @param info - Label, UIDs, PACS name, and expected file count.
+ * @returns A pending task ready for {@link retrieve_fireAndWatch}.
+ */
+function retrieveTask_make(info) {
+    return {
+        ...info,
+        syntheticQueryId: null,
+        retrieveId: null,
+        status: 'pending',
+        actualFiles: 0,
+        lastProgressFiles: 0,
+        lastProgressTime: Date.now(),
+        startTime: 0,
+        lonkConfirmed: false,
+        cubePathDir: null,
+    };
+}
+/**
+ * Classifies a task's state for progress reporting.
+ *
+ * @param task - The task to classify.
+ * @returns The progress status consumers render.
+ */
+function retrieveProgress_classify(task) {
+    if (task.status === 'pulled')
+        return task.lonkConfirmed ? 'done' : 'unconfirmed';
+    if (task.status === 'pending' || task.status === 'pulling')
+        return 'running';
+    if (task.status === 'unfired')
+        return 'error';
+    return task.status;
+}
+/**
+ * Marks tasks whose series are already fully registered in CUBE as pulled,
+ * so firing skips them. This is what makes a retrieve idempotent: re-running
+ * the same request after a partial failure fetches only the missing series.
+ *
+ * @param tasks - All tasks; complete ones are mutated to pulled.
+ * @returns How many tasks were marked complete and skipped.
+ */
+async function retrieveTasks_skipComplete(tasks) {
+    let skipped = 0;
+    await Promise.all(tasks.map(async (task) => {
+        const stateResult = await (0, cumin_1.seriesStorage_resolve)(task.seriesUID);
+        if (!stateResult.ok)
+            return;
+        const state = stateResult.value;
+        if (task.expectedFiles > 0 && state.fileCount >= task.expectedFiles && state.folderPath !== null) {
+            task.status = 'pulled';
+            task.lonkConfirmed = true;
+            task.actualFiles = state.fileCount;
+            task.cubePathDir = state.folderPath;
+            skipped++;
+        }
+    }));
+    return skipped;
+}
+/**
+ * Creates a synthetic PACSQuery + PACSRetrieve for a single series, with
+ * bounded retry: creation failures during a server brown-out are permanent
+ * data loss for the run (nothing ever retrieves), so each series gets a few
+ * attempts before it is declared unfired.
+ *
+ * @param task - The task to fire (mutated: syntheticQueryId, retrieveId, startTime, status).
+ * @param pacsserver - Resolved PACS server ID string.
+ */
+async function task_fire(task, pacsserver) {
+    const fired = await (0, cumin_1.retry_untilValue)(FIRE_ATTEMPTS, FIRE_BACKOFF_MS, async () => {
+        const queryData = {
+            // CUBE rejects duplicate query titles per user; a timestamp keeps
+            // re-pull titles unique.
+            title: `pull_${task.seriesUID}_${Date.now().toString(36)}`,
+            query: JSON.stringify({
+                SeriesInstanceUID: task.seriesUID,
+                StudyInstanceUID: task.studyUID,
+            }),
+            execute: false,
+        };
+        const queryResult = await (0, cumin_1.pacsQueries_create)(pacsserver, queryData);
+        if (!queryResult.ok)
+            return null;
+        const retrieveResult = await (0, cumin_1.pacsRetrieve_create)(queryResult.value.id);
+        if (!retrieveResult.ok)
+            return null;
+        return { queryId: queryResult.value.id, retrieveId: retrieveResult.value.id };
+    });
+    if (fired === null) {
+        task.status = 'unfired';
+        return;
+    }
+    task.syntheticQueryId = fired.queryId;
+    task.retrieveId = fired.retrieveId;
+    task.startTime = Date.now();
+}
+/**
+ * Fires retrieves with bounded concurrency, so a large study does not
+ * stampede CUBE with parallel creations (the overload that loses retrieves
+ * in the first place).
+ *
+ * @param tasks - Tasks to fire.
+ * @param pacsserver - Resolved PACS server identifier.
+ */
+async function tasks_fireBounded(tasks, pacsserver) {
+    let next = 0;
+    const worker = async () => {
+        while (next < tasks.length) {
+            const task = tasks[next++];
+            await task_fire(task, pacsserver);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(FIRE_CONCURRENCY, tasks.length) }, () => worker()));
+}
+/**
+ * Fires retrieves for tasks (bounded, retried) without watching: the
+ * fire-and-exit path (`pull --nowait`). Tasks that could not fire are left
+ * in the `unfired` state.
+ *
+ * @param tasks - Tasks to fire.
+ * @param pacsserver - Resolved PACS server identifier.
+ */
+async function retrieveTasks_fire(tasks, pacsserver) {
+    await tasks_fireBounded(tasks, pacsserver);
+}
+/**
+ * Constructs a LONK WebSocket URL from a download token response.
+ *
+ * @param tokenUrl - The download token resource URL.
+ * @param token - The actual download token string.
+ * @returns WebSocket URL for the LONK endpoint.
+ */
+function lonkWsUrl_build(tokenUrl, token) {
+    return tokenUrl
+        .replace(/^http(s?):\/\//, (_m, s) => `ws${s}://`)
+        .replace(/v1\/downloadtokens\/\d+\//, `v1/pacs/ws/?token=${token}`);
+}
+/**
+ * Opens a LONK WebSocket, fires retrieves for the tasks, and blocks until
+ * every task reaches a terminal state. Mutates each task's status,
+ * actualFiles, and lonkConfirmed; reports progress through the events.
+ *
+ * @param tasks - Tasks to subscribe, fire, and watch.
+ * @param pacsserver - Resolved PACS server identifier.
+ * @param client - Authenticated ChRIS API client (for the LONK token).
+ * @param events - Progress callbacks.
+ * @param phase - Phase tag passed through to task events.
+ * @returns Number of tasks whose retrieve could not be fired.
+ */
+async function retrieve_fireAndWatch(tasks, pacsserver, client, events = {}, phase = 'watching') {
+    const emit = (task, status) => {
+        events.task?.(task, status ?? retrieveProgress_classify(task), phase);
+    };
+    const tokenClient = client;
+    const downloadToken = await tokenClient.createDownloadToken();
+    const tokenStr = String(downloadToken.data.token ?? '');
+    const ws = new ws_1.default(lonkWsUrl_build(downloadToken.url, tokenStr));
+    await new Promise((openResolve, openReject) => {
+        ws.once('open', openResolve);
+        ws.once('error', (err) => openReject(err));
+    });
+    for (const t of tasks) {
+        ws.send(JSON.stringify({ SeriesInstanceUID: t.seriesUID, pacs_name: t.pacsName, action: 'subscribe' }));
+    }
+    await tasks_fireBounded(tasks, pacsserver);
+    const fired = tasks.filter((t) => t.status !== 'unfired');
+    const firingErrors = tasks.length - fired.length;
+    if (fired.length === 0) {
+        for (const t of tasks) {
+            if (t.status === 'unfired')
+                emit(t, 'error');
+        }
+        ws.close();
+        return firingErrors;
+    }
+    for (const t of tasks) {
+        emit(t, t.status === 'unfired' ? 'error' : 'running');
+    }
+    const taskByUID = new Map(tasks.map((t) => [t.seriesUID, t]));
+    await new Promise((resolve) => {
+        let resolved = false;
+        const done = () => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearInterval(checker);
+            try {
+                ws.close();
+            }
+            catch { /* best-effort socket cleanup */ }
+            resolve();
+        };
+        const checker = setInterval(() => {
+            const now = Date.now();
+            let allTerminal = true;
+            for (const t of fired) {
+                if (t.status === 'pulled' || t.status === 'error' || t.status === 'unfired' || t.status === 'stalled' || t.status === 'timeout') {
+                    continue;
+                }
+                allTerminal = false;
+                if (t.startTime > 0 && now - t.startTime > SERIES_TIMEOUT_MS) {
+                    t.status = 'timeout';
+                    emit(t, 'timeout');
+                    continue;
+                }
+                if (t.actualFiles > 0 && now - t.lastProgressTime > STALL_TIMEOUT_MS) {
+                    t.status = 'stalled';
+                    emit(t, 'stalled');
+                    continue;
+                }
+                if (t.startTime > 0 && t.actualFiles === 0 && now - t.startTime > NO_ACTIVITY_TIMEOUT_MS) {
+                    t.status = 'pulled';
+                    t.lonkConfirmed = false;
+                    emit(t, 'unconfirmed');
+                    continue;
+                }
+            }
+            if (allTerminal)
+                done();
+        }, CHECKER_INTERVAL_MS);
+        ws.on('message', (data) => {
+            try {
+                const outer = JSON.parse(data.toString());
+                const seriesUID = outer.SeriesInstanceUID;
+                const message = outer.message;
+                if (!seriesUID || !message)
+                    return;
+                const t = taskByUID.get(seriesUID);
+                if (!t)
+                    return;
+                if ('ndicom' in message && typeof message.ndicom === 'number') {
+                    const n = message.ndicom;
+                    t.actualFiles = n;
+                    t.lastProgressFiles = n;
+                    t.lastProgressTime = Date.now();
+                    if (t.status === 'pending')
+                        t.status = 'pulling';
+                    emit(t, 'running');
+                }
+                else if ('done' in message && message.done === true) {
+                    t.status = 'pulled';
+                    t.lonkConfirmed = true;
+                    if (t.actualFiles < t.expectedFiles)
+                        t.actualFiles = t.expectedFiles;
+                    emit(t, 'done');
+                }
+                else if ('error' in message && typeof message.error === 'string') {
+                    t.status = 'error';
+                    emit(t, 'error');
+                }
+            }
+            catch {
+                // Deliberate absorption: a malformed LONK frame carries no correlation
+                // to fail; the checker's stall/timeout guards still bound the watch.
+            }
+        });
+        ws.on('error', () => {
+            for (const t of fired) {
+                if (t.status === 'pending' || t.status === 'pulling') {
+                    t.status = 'error';
+                    emit(t, 'error');
+                }
+            }
+            done();
+        });
+        ws.on('close', () => { done(); });
+    });
+    return firingErrors;
+}
+/**
+ * Confirms unconfirmed series against CUBE storage and refires the rest, up
+ * to `retryMax` rounds; series still unconfirmed afterwards are marked
+ * errored. This closes the gap between a lost LONK confirmation (cosmetic)
+ * and a retrieve that genuinely never delivered (real loss).
+ *
+ * @param allTasks - All tasks from the initial watch.
+ * @param retryMax - Maximum refire rounds.
+ * @param pacsserver - The PACS server identifier.
+ * @param client - The connected ChRIS client.
+ * @param events - Progress callbacks.
+ * @returns The number of additional firing errors incurred.
+ */
+async function retrieve_confirmLoop(allTasks, retryMax, pacsserver, client, events = {}) {
+    let extraFiringErrors = 0;
+    let retryCandidates = allTasks.filter((t) => t.status === 'pulled' && !t.lonkConfirmed);
+    for (let attempt = 1; attempt <= retryMax && retryCandidates.length > 0; attempt++) {
+        await Promise.all(retryCandidates.map(async (t) => {
+            const stateResult = await (0, cumin_1.seriesStorage_resolve)(t.seriesUID);
+            if (stateResult.ok && stateResult.value.folderPath !== null) {
+                t.lonkConfirmed = true;
+                t.cubePathDir = stateResult.value.folderPath;
+            }
+        }));
+        retryCandidates = retryCandidates.filter((t) => !t.lonkConfirmed);
+        if (retryCandidates.length === 0)
+            break;
+        events.retryRound?.(attempt, retryMax, retryCandidates.length);
+        for (const t of retryCandidates) {
+            t.status = 'pending';
+            t.actualFiles = 0;
+            t.lastProgressFiles = 0;
+            t.lastProgressTime = Date.now();
+            t.startTime = 0;
+            t.lonkConfirmed = false;
+            t.syntheticQueryId = null;
+            t.retrieveId = null;
+            events.task?.(t, 'running', 'retrying');
+        }
+        extraFiringErrors += await retrieve_fireAndWatch(retryCandidates, pacsserver, client, events, 'retrying');
+        retryCandidates = retryCandidates.filter((t) => t.status === 'pulled' && !t.lonkConfirmed);
+    }
+    for (const t of retryCandidates) {
+        t.status = 'error';
+        events.task?.(t, 'error', 'retrying');
+    }
+    return extraFiringErrors;
+}
+//# sourceMappingURL=watch.js.map

package/dist/retrieve/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/retrieve/watch.ts"],"names":[],"mappings":"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"}

package/dist/store/index.d.ts

@@ -1,15 +1,28 @@
+/**
+ * @file Store operations.
+ *
+ * Logic for interacting with the peer ChRIS store (listing, searching).
+ * Failures propagate as Err rather than an empty array, so a store outage is
+ * distinguishable from a store with no plugins; the underlying fetch has
+ * already pushed its reason onto the error stack.
+ *
+ * @module
+ */
+import { Result } from '@fnndsc/cumin';
 /**
  * Lists plugins from the peer store.
  *
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with raw plugin objects (possibly empty), or Err when the store
+ *   fetch failed (reason already on the error stack).
  */
-export declare function store_list(storeUrl?: string): Promise<Record<string, unknown>[]>;
+export declare function store_list(storeUrl?: string): Promise<Result<Record<string, unknown>[]>>;
 /**
  * Searches plugins in the peer store.
  *
  * @param query - Search query (e.g. plugin name substring).
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with matching raw plugin objects (possibly empty), or Err when
+ *   the store fetch failed (reason already on the error stack).
  */
-export declare function store_search(query: string, storeUrl?: string): Promise<Record<string, unknown>[]>;
+export declare function store_search(query: string, storeUrl?: string): Promise<Result<Record<string, unknown>[]>>;

package/dist/store/index.js

@@ -6,6 +6,9 @@ exports.store_search = store_search;
  * @file Store operations.
  *
  * Logic for interacting with the peer ChRIS store (listing, searching).
+ * Failures propagate as Err rather than an empty array, so a store outage is
+ * distinguishable from a store with no plugins; the underlying fetch has
+ * already pushed its reason onto the error stack.
  *
  * @module
  */
@@ -14,24 +17,26 @@ const cumin_1 = require("@fnndsc/cumin");
  * Lists plugins from the peer store.
  *
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with raw plugin objects (possibly empty), or Err when the store
+ *   fetch failed (reason already on the error stack).
  */
 async function store_list(storeUrl) {
     const chrisPlugin = new cumin_1.ChRISPlugin();
     const plugins = await chrisPlugin.plugin_listPeerStore(storeUrl);
-    return plugins || [];
+    return plugins === null ? (0, cumin_1.Err)() : (0, cumin_1.Ok)(plugins);
 }
 /**
  * Searches plugins in the peer store.
  *
  * @param query - Search query (e.g. plugin name substring).
  * @param storeUrl - Optional URL of the peer store.
- * @returns Promise resolving to array of raw plugin objects.
+ * @returns Ok with matching raw plugin objects (possibly empty), or Err when
+ *   the store fetch failed (reason already on the error stack).
  */
 async function store_search(query, storeUrl) {
     const chrisPlugin = new cumin_1.ChRISPlugin();
     // Search by name
     const plugins = await chrisPlugin.plugin_listPeerStore(storeUrl, { name: query });
-    return plugins || [];
+    return plugins === null ? (0, cumin_1.Err)() : (0, cumin_1.Ok)(plugins);
 }
 //# sourceMappingURL=index.js.map

package/dist/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":";;AAeA,gCAIC;AASD,oCAKC;AAjCD;;;;;;GAMG;AACH,yCAA4C;AAE5C;;;;;GAKG;AACI,KAAK,UAAU,UAAU,CAAC,QAAiB;IAChD,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACnG,OAAO,OAAO,IAAI,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,YAAY,CAAC,KAAa,EAAE,QAAiB;IACjE,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,iBAAiB;IACjB,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpH,OAAO,OAAO,IAAI,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":";;AAmBA,gCAIC;AAUD,oCAKC;AAtCD;;;;;;;;;GASG;AACH,yCAA6D;AAE7D;;;;;;GAMG;AACI,KAAK,UAAU,UAAU,CAAC,QAAiB;IAChD,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACnG,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAA,WAAG,GAAE,CAAC,CAAC,CAAC,IAAA,UAAE,EAAC,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,YAAY,CAAC,KAAa,EAAE,QAAiB;IACjE,MAAM,WAAW,GAAgB,IAAI,mBAAW,EAAE,CAAC;IACnD,iBAAiB;IACjB,MAAM,OAAO,GAAqC,MAAM,WAAW,CAAC,oBAAoB,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpH,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,IAAA,WAAG,GAAE,CAAC,CAAC,CAAC,IAAA,UAAE,EAAC,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/dist/users/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file CUBE-local account operation facade.
+ * @module
+ */
+import { type LocalAccount, type LocalAccountAction, type Result } from '@fnndsc/cumin';
+export type { LocalAccount, LocalAccountAction, Result };
+/**
+ * Verifies that the current identity may use local-account administration.
+ *
+ * @returns Success when the active CUBE identity has account-admin access.
+ */
+export declare function localAccount_adminAccessEnsure(): Promise<Result<void>>;
+/**
+ * Creates one CUBE-local account.
+ *
+ * @param username - New local username.
+ * @param email - Account email address.
+ * @param password - Initial local-login password.
+ * @returns The created account or an operation error.
+ */
+export declare function localAccount_create(username: string, email: string, password: string): Promise<Result<LocalAccount>>;
+/**
+ * Finds one CUBE-local account by exact username.
+ *
+ * @param username - Exact local username.
+ * @returns The matching account or an operation error.
+ */
+export declare function localAccount_find(username: string): Promise<Result<LocalAccount>>;
+/**
+ * Changes the lifecycle state of one CUBE-local account.
+ *
+ * @param accountID - Stable local-account record identifier.
+ * @param action - Lifecycle transition to apply.
+ * @returns The updated account or an operation error.
+ */
+export declare function localAccount_action(accountID: number, action: LocalAccountAction): Promise<Result<LocalAccount>>;

package/dist/users/index.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localAccount_adminAccessEnsure = localAccount_adminAccessEnsure;
+exports.localAccount_create = localAccount_create;
+exports.localAccount_find = localAccount_find;
+exports.localAccount_action = localAccount_action;
+/**
+ * @file CUBE-local account operation facade.
+ * @module
+ */
+const cumin_1 = require("@fnndsc/cumin");
+/**
+ * Verifies that the current identity may use local-account administration.
+ *
+ * @returns Success when the active CUBE identity has account-admin access.
+ */
+async function localAccount_adminAccessEnsure() {
+    return await (0, cumin_1.localAccount_adminAccessEnsure)();
+}
+/**
+ * Creates one CUBE-local account.
+ *
+ * @param username - New local username.
+ * @param email - Account email address.
+ * @param password - Initial local-login password.
+ * @returns The created account or an operation error.
+ */
+async function localAccount_create(username, email, password) {
+    return await (0, cumin_1.localAccount_create)(username, email, password);
+}
+/**
+ * Finds one CUBE-local account by exact username.
+ *
+ * @param username - Exact local username.
+ * @returns The matching account or an operation error.
+ */
+async function localAccount_find(username) {
+    return await (0, cumin_1.localAccount_find)(username);
+}
+/**
+ * Changes the lifecycle state of one CUBE-local account.
+ *
+ * @param accountID - Stable local-account record identifier.
+ * @param action - Lifecycle transition to apply.
+ * @returns The updated account or an operation error.
+ */
+async function localAccount_action(accountID, action) {
+    return await (0, cumin_1.localAccount_action)(accountID, action);
+}
+//# sourceMappingURL=index.js.map

package/dist/users/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/users/index.ts"],"names":[],"mappings":";;AAqBA,wEAEC;AAUD,kDAIC;AAQD,8CAEC;AASD,kDAIC;AA5DD;;;GAGG;AACH,yCAQuB;AAIvB;;;;GAIG;AACI,KAAK,UAAU,8BAA8B;IAClD,OAAO,MAAM,IAAA,sCAAoC,GAAE,CAAC;AACtD,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,mBAAmB,CACvC,QAAgB,EAAE,KAAa,EAAE,QAAgB;IAEjD,OAAO,MAAM,IAAA,2BAAyB,EAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IACtD,OAAO,MAAM,IAAA,yBAAuB,EAAC,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,mBAAmB,CACvC,SAAiB,EAAE,MAA0B;IAE7C,OAAO,MAAM,IAAA,2BAAyB,EAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC"}

package/dist/vfs/dispatcher.d.ts

@@ -78,6 +78,17 @@ export declare class VFSDispatcher {
      * @returns A Promise resolving to a Result containing the file contents as a Buffer.
      */
     readBinary(pathStr: string): Promise<Result<Buffer>>;
+    /**
+     * Resolves a lazy link through the provider that owns it.
+     *
+     * This is deliberately distinct from {@link list}: a structural traversal
+     * can display an unresolved link without causing its provider to fetch the
+     * target from a remote service.
+     *
+     * @param pathStr - Absolute path of the provider-defined link.
+     * @returns The resolved target path, or an error if unsupported or absent.
+     */
+    linkTarget_resolve(pathStr: string): Promise<Result<string>>;
 }
 /** Global instance of VFSDispatcher singleton. */
 export declare const vfsDispatcher: VFSDispatcher;

package/dist/vfs/dispatcher.js

@@ -105,7 +105,9 @@ class VFSDispatcher {
                         resolvedPathStr = await this.pathResolver(pathStr);
                     }
                     catch (e) {
-                        // Fall back cleanly to the original path on failure
+                        // Deliberate absorption: for a read-only listing, the logical
+                        // path is a valid fallback (the provider lists what it can);
+                        // contrast cp(), where a guessed path could write wrongly.
                     }
                 }
                 const nativeResult = await this.defaultProvider.list(resolvedPathStr, options);
@@ -127,7 +129,7 @@ class VFSDispatcher {
                 return provider.list(resolvedPath, options);
             }
             catch (e) {
-                // Fall back cleanly to the original path on failure
+                // Deliberate absorption: same read-only-listing rationale as above.
             }
         }
         return provider.list(pathStr, options);
@@ -143,16 +145,27 @@ class VFSDispatcher {
     async cp(src, dest, options) {
         const provider = this.provider_get(src);
         if (provider === this.defaultProvider && this.pathResolver) {
-            let resolvedSrc = src;
-            let resolvedDest = dest;
+            // A copy must never proceed on a guessed path: an unresolved source
+            // copies the wrong thing, an unresolved destination writes to the wrong
+            // place. Resolution failure fails the copy.
+            let resolvedSrc;
+            let resolvedDest;
             try {
                 resolvedSrc = await this.pathResolver(src);
             }
-            catch (e) { }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                cumin_1.errorStack.stack_push("error", `cp: cannot resolve source path ${src}: ${msg}`);
+                return false;
+            }
             try {
                 resolvedDest = await this.pathResolver(dest);
             }
-            catch (e) { }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                cumin_1.errorStack.stack_push("error", `cp: cannot resolve destination path ${dest}: ${msg}`);
+                return false;
+            }
             return provider.cp(resolvedSrc, resolvedDest, options);
         }
         return provider.cp(src, dest, options);
@@ -185,6 +198,24 @@ class VFSDispatcher {
         cumin_1.errorStack.stack_push("error", `Binary file read not supported for path: ${pathStr}`);
         return (0, cumin_1.Err)();
     }
+    /**
+     * Resolves a lazy link through the provider that owns it.
+     *
+     * This is deliberately distinct from {@link list}: a structural traversal
+     * can display an unresolved link without causing its provider to fetch the
+     * target from a remote service.
+     *
+     * @param pathStr - Absolute path of the provider-defined link.
+     * @returns The resolved target path, or an error if unsupported or absent.
+     */
+    async linkTarget_resolve(pathStr) {
+        const provider = this.provider_get(pathStr);
+        if (provider.linkTarget_resolve) {
+            return provider.linkTarget_resolve(pathStr);
+        }
+        cumin_1.errorStack.stack_push('error', `Link resolution not supported for path: ${pathStr}`);
+        return (0, cumin_1.Err)();
+    }
 }
 exports.VFSDispatcher = VFSDispatcher;
 /** Global instance of VFSDispatcher singleton. */