rea-agents 6.4.0 → 6.7.0

package/dist/providers/AnalysisClientFailure.js

@@ -0,0 +1,191 @@
+import { HopperRemoteError, HopperTimeoutError, HopperProcessError, } from "../domain/hopperErrors.js";
+import { AnalysisError, } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisResourceConstraintError, AnalysisOutputError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { bindArtifactFileCleanup } from "../artifacts/ArtifactFileOperation.js";
+/** Copy authored outcome facts; semantic attribution never inspects a later signal. */
+export const analysisClientFailureContext = (cause, providerId, operation) => {
+    const providerRequest = cause instanceof HopperRemoteError ||
+        cause instanceof HopperTimeoutError ||
+        cause instanceof HopperProcessError
+        ? {
+            ...(cause.operation === undefined
+                ? {}
+                : { operation: cause.operation }),
+            ...(cause.requestId === undefined
+                ? {}
+                : { request_id: cause.requestId }),
+            ...(cause instanceof HopperRemoteError
+                ? {
+                    provider_code: cause.code,
+                    diagnostic_type: cause.diagnosticType,
+                }
+                : {}),
+        }
+        : undefined;
+    const diagnostics = providerRequest === undefined
+        ? cause.diagnostics
+        : {
+            provider_request: providerRequest,
+            ...(cause.diagnostics === undefined
+                ? {}
+                : { provider_diagnostics: cause.diagnostics }),
+        };
+    return {
+        cause,
+        ...(cause.cleanupPrimary === undefined
+            ? {}
+            : {
+                cleanupPrimary: analysisClientFailureForOperation(cause.cleanupPrimary, providerId, operation),
+            }),
+        ...(cause.partialObservation === undefined
+            ? {}
+            : { partialObservation: cause.partialObservation }),
+        ...(cause.capturedOutput === undefined
+            ? {}
+            : { capturedOutput: cause.capturedOutput }),
+        ...(diagnostics === undefined ? {} : { diagnostics }),
+        ...(cause.cleanupIncomplete
+            ? {
+                cleanup: {
+                    reason: cause.cleanup?.reason ?? cause.message,
+                    resources: cause.cleanupResources,
+                },
+            }
+            : {}),
+    };
+};
+/** Attribute producer-owned failure facts without inferring interruption. */
+export const analysisClientFailureForOperation = (cause, providerId, operation, callerDiagnostics) => {
+    if (!(cause instanceof AnalysisError)) {
+        const failure = new ProviderAdapterError(providerId, operation, {
+            cause,
+            ...(callerDiagnostics === undefined
+                ? {}
+                : { diagnostics: callerDiagnostics }),
+            ...(cause instanceof ArtifactReaderFailure && cause.cleanup !== undefined
+                ? { cleanup: cause.cleanup }
+                : {}),
+        });
+        bindArtifactFileCleanup(cause, failure);
+        return failure;
+    }
+    if (!(cause instanceof HopperRemoteError) &&
+        !(cause instanceof HopperTimeoutError) &&
+        !(cause instanceof HopperProcessError) &&
+        !(cause instanceof AnalysisCancelledError) &&
+        !(cause instanceof ProviderAdapterError) &&
+        !(cause instanceof AnalysisCapabilityUnavailableError) &&
+        !(cause instanceof AnalysisAccessDeniedError) &&
+        !(cause instanceof AnalysisArtifactChangedError) &&
+        !(cause instanceof AnalysisTimeoutError) &&
+        !(cause instanceof AnalysisOutputError) &&
+        !(cause instanceof AnalysisResourceConstraintError))
+        return cause;
+    const sourceContext = analysisClientFailureContext(cause, providerId, operation);
+    const context = {
+        ...sourceContext,
+        ...(callerDiagnostics === undefined
+            ? {}
+            : {
+                diagnostics: { ...sourceContext.diagnostics, ...callerDiagnostics },
+            }),
+    };
+    let result;
+    if (cause instanceof HopperRemoteError)
+        result = new HopperRemoteError(cause.code, cause.safeMessage, {
+            ...context,
+            operation,
+            requestId: cause.requestId,
+            diagnosticType: cause.diagnosticType,
+        });
+    else if (cause instanceof HopperTimeoutError)
+        result = new HopperTimeoutError(cause.timeoutMs, operation, cause.requestId, cause.providerState, cause.stage, cause.launcherOutcome, context);
+    else if (cause instanceof HopperProcessError)
+        result = new HopperProcessError(cause.exitCode, {
+            ...context,
+            operation,
+            requestId: cause.requestId,
+            providerState: cause.providerState,
+            stage: cause.stage,
+            ...(cause.diagnostic === undefined
+                ? {}
+                : { diagnostic: cause.diagnostic }),
+            ...(cause.launcherFailure === undefined
+                ? {}
+                : { launcherFailure: cause.launcherFailure }),
+        });
+    else if (cause instanceof ProviderCleanupError) {
+        const { diagnostics, ...outcomeContext } = context;
+        result = new ProviderCleanupError(cause.providerId, cause.cleanupResources, diagnostics ?? {}, {
+            ...outcomeContext,
+            operation,
+            ...(cause.remediationAction === undefined
+                ? {}
+                : { remediationAction: cause.remediationAction }),
+        });
+    }
+    else if (cause instanceof AnalysisTimeoutError)
+        result = new AnalysisTimeoutError(operation, cause.timeoutMs, {
+            ...context,
+            ...(cause.userMessage === undefined
+                ? {}
+                : { userMessage: cause.userMessage }),
+            ...(cause.remediationAction === undefined
+                ? {}
+                : { remediationAction: cause.remediationAction }),
+        });
+    else if (cause instanceof AnalysisOutputError)
+        result = new AnalysisOutputError(operation, cause.reason, {
+            ...context,
+            cleanupOnly: cause.cleanupOnly,
+            ...(cause.userMessage === undefined
+                ? {}
+                : { userMessage: cause.userMessage }),
+            ...(cause.remediationAction === undefined
+                ? {}
+                : { remediationAction: cause.remediationAction }),
+        });
+    else if (cause instanceof AnalysisCancelledError)
+        result = new AnalysisCancelledError(operation, {
+            ...context,
+            cause: cause.cause,
+        });
+    else if (cause instanceof AnalysisCapabilityUnavailableError)
+        result = new AnalysisCapabilityUnavailableError(cause.providerId, operation, cause.reason, {
+            ...context,
+            ...(cause.userMessage === undefined
+                ? {}
+                : { userMessage: cause.userMessage }),
+            retryable: cause.retryable,
+        });
+    else if (cause instanceof AnalysisAccessDeniedError)
+        result = new AnalysisAccessDeniedError(operation, cause.path, cause.systemCode, context);
+    else if (cause instanceof AnalysisArtifactChangedError)
+        result = new AnalysisArtifactChangedError(operation, cause.path, cause.reason, context);
+    else if (cause instanceof AnalysisResourceConstraintError)
+        result = new AnalysisResourceConstraintError(operation, cause.resource, cause.reason, cause.reportedLimits, {
+            ...context,
+            ...(cause.retryable === undefined
+                ? {}
+                : { retryable: cause.retryable }),
+            ...(cause.remediationAction === undefined
+                ? {}
+                : { remediationAction: cause.remediationAction }),
+        });
+    else
+        result = new ProviderAdapterError(providerId, operation, {
+            ...context,
+            ...(cause.userMessage === undefined
+                ? {}
+                : { userMessage: cause.userMessage }),
+            ...(cause.remediationAction === undefined
+                ? {}
+                : { remediationAction: cause.remediationAction }),
+        });
+    return cause.cleanupIncomplete
+        ? result.bindCleanupDependencies([cause])
+        : result.resolveCleanup();
+};

package/dist/providers/DeferredAnalysisClient.js

@@ -0,0 +1,48 @@
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { err } from "../domain/result.js";
+import { AnalysisClientCreation } from "./AnalysisClientCreation.js";
+/** Expose a closeable client before deferred prerequisite work starts. */
+export class DeferredAnalysisClient {
+    #creation;
+    #providerId;
+    executeIfReady = (operation, parameters, options) => this.#creation.readyClient?.executeIfReady?.(operation, parameters, options) ?? Promise.resolve(undefined);
+    constructor(loadClient, providerId) {
+        this.#creation = new AnalysisClientCreation(providerId, loadClient);
+        this.#providerId = providerId;
+    }
+    execute = async (operation, parameters, options) => {
+        try {
+            const loaded = await this.#creation.acquire(operation, options?.signal);
+            if (!loaded.ok)
+                return loaded;
+            if (this.#creation.readyClient !== loaded.value)
+                return err(new ProviderAdapterError(this.#providerId, operation, {
+                    diagnostics: { reason: "client_closed" },
+                }));
+            return await loaded.value.execute(operation, parameters, options);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            return err(new ProviderAdapterError(this.#providerId, operation, {
+                cause,
+            }));
+        }
+    };
+    runtimeLineageSnapshots() {
+        return this.#creation.ownedClient?.runtimeLineageSnapshots?.() ?? [];
+    }
+    requestActivitySnapshots() {
+        return this.#creation.ownedClient?.requestActivitySnapshots?.() ?? [];
+    }
+    reuseReadiness() {
+        if (!this.#creation.reusable || this.#creation.readyClient === undefined)
+            return "blocked";
+        return this.#creation.readyClient.reuseReadiness?.() ?? "unknown";
+    }
+    operationHealthSnapshot() {
+        return this.#creation.ownedClient?.operationHealthSnapshot?.();
+    }
+    close = (options) => this.#creation.close(options);
+}

package/dist/providers/OwnedCommandCleanup.js

@@ -0,0 +1,65 @@
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { DarwinProcessOwnershipInspectionError } from "../process/DarwinProcessRunTokenReader.js";
+import { OwnedCommandFailure } from "../process/OwnedCommand.js";
+/** Transfer exact helper and command cleanup capabilities to the caller's scope. */
+export const retainOwnedCommandCleanup = (cause, resourceOwner, providerId, operation) => {
+    const commandFailure = cause instanceof OwnedCommandFailure ? cause : undefined;
+    const preparation = commandFailure?.preparationFailure ??
+        (cause instanceof DarwinProcessOwnershipInspectionError
+            ? cause
+            : undefined);
+    const cleanups = [];
+    if (preparation?.cleanupFailure !== undefined) {
+        const cleanup = preparation.cleanupFailure;
+        const lease = new AnalysisCleanupLease(async () => {
+            if (!cleanup.cleanupIncomplete)
+                return;
+            if (preparation.cleanupOwner === undefined)
+                throw cleanup;
+            await preparation.cleanupOwner.close();
+            if (cleanup.cleanupIncomplete)
+                throw cleanup;
+        }, cleanup);
+        resourceOwner.retain({
+            close: () => lease.release(),
+            get cleanupResources() {
+                return cleanup.cleanupResources;
+            },
+        }, cleanup.cleanupResources[0] ??
+            "Provider prerequisite ownership preparation");
+        cleanups.push(cleanup);
+    }
+    if (commandFailure !== undefined &&
+        (commandFailure.cleanupOwner !== undefined ||
+            commandFailure.cleanupFailure !== null)) {
+        const supervisor = commandFailure.cleanupOwner;
+        const cleanup = new ProviderCleanupError(providerId, commandFailure.resources, {
+            reason: commandFailure.cleanupFailure ??
+                "Provider prerequisite cleanup remains incomplete",
+            ...(commandFailure.cleanupResult === undefined
+                ? {}
+                : {
+                    process_cleanup: jsonValueSchema.parse(commandFailure.cleanupResult),
+                }),
+        }, { cause, operation });
+        const lease = new AnalysisCleanupLease(async () => {
+            if (supervisor === undefined)
+                throw cleanup;
+            const stopped = await supervisor.stop();
+            if (stopped.status === "incomplete")
+                throw cleanup;
+        }, commandFailure.resources);
+        cleanup.bindCleanupResourceOwner(lease);
+        lease.bindCleanupError(cleanup);
+        resourceOwner.retain({
+            close: () => lease.release(),
+            get cleanupResources() {
+                return cleanup.cleanupResources;
+            },
+        }, commandFailure.resources[0] ?? "Provider prerequisite process");
+        cleanups.push(cleanup);
+    }
+    return cleanups;
+};

package/dist/providers/ProviderInspectionScope.js

@@ -0,0 +1,10 @@
+/** Lifetime of one task's prerequisite observations, distinct from resource ownership. */
+export class ProviderInspectionScope {
+    #active = true;
+    get active() {
+        return this.#active;
+    }
+    close() {
+        this.#active = false;
+    }
+}

package/dist/recordedCatalogDigests.js

@@ -0,0 +1,2 @@
+/** Recorded from the compiled default catalog by scripts/record-catalog-digests.mjs; do not edit. */
+export const RECORDED_CATALOG_DIGESTS = Object.freeze({"tools_sha256":"af39310c9591bb981893ec0d2188b1bcf6e9cc8ba3ac513d5bbefc8ddcb85639","prompts_sha256":"7152916ab48bd2a9677a5ad9cdbde0a51dc53c113934952ad096e93f5f18aa7e","combined_sha256":"96d8f6e6ea1b1ba13557216624a3461c738729d53c79b4b0100d1f3a3a32441c"});

package/dist/reference/ReferenceSourceReader.js

@@ -1,8 +1,9 @@
+import { posix } from "node:path";
 import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { createReferenceSourcePathLookup } from "../domain/referenceSourcePathIdentity.js";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { traverseDirectory } from "./ReferenceSourceReaderEntries.js";
-import {} from "./ReferenceSourceReaderTypes.js";
 import { isAborted, noFollowOpenSupported, prepareRoot, } from "./ReferenceSourceReaderValidate.js";
 const PATH_RACE_LIMITATION = "Path identity is revalidated around operations; Node lacks portable descriptor-relative openat traversal, so a syscall-boundary pathname race remains.";
 /** Read a source tree without intentionally following symbolic links. */
@@ -42,10 +43,14 @@ const readSource = async (root, resources, options) => {
             ? {}
             : { shouldExclude: options.shouldExclude }),
         entries: [],
+        exclusions: [],
         pending: [{ path: canonicalRoot }],
         bytesRead: 0,
     };
     const traversal = await traverse(state);
+    if (!isAborted(state.signal) &&
+        (traversal.ok || traversal.error.code !== "cancelled"))
+        reconcileUnobservedSymlinkTargets(state.entries, state.exclusions, state.signal);
     state.entries.sort((left, right) => compareUnicodeCodePoints(left.path, right.path));
     const read = {
         root: canonicalRoot,
@@ -55,6 +60,64 @@ const readSource = async (root, resources, options) => {
     };
     return traversal.ok ? ok(read) : err({ ...traversal.error, partial: read });
 };
+/**
+ * Resolve internal link observations against the completed reader inventory.
+ * If the closest containing directory failed before enumeration completed,
+ * the target remains unknown; a broader failed ancestor cannot override a
+ * successfully enumerated directory or a recorded exclusion.
+ */
+export const reconcileUnobservedSymlinkTargets = (entries, exclusions = [], signal) => {
+    const failedDirectories = new Map(entries.flatMap((entry) => entry.status === "failed" &&
+        entry.kind === "directory" &&
+        entry.code !== "cancelled"
+        ? [[entry.path, entry]]
+        : []));
+    if (failedDirectories.size === 0 || isAborted(signal))
+        return;
+    const directoryEntries = entries.filter((entry) => entry.kind === "directory");
+    const directoryPaths = createReferenceSourcePathLookup(directoryEntries.map(({ path }) => path));
+    const observedPaths = createReferenceSourcePathLookup(entries.map(({ path }) => path));
+    const excludedPaths = createReferenceSourcePathLookup(exclusions.map(({ path }) => path));
+    for (const [index, entry] of entries.entries()) {
+        if (isAborted(signal))
+            return;
+        if (entry.status !== "read" ||
+            entry.kind !== "symlink" ||
+            entry.targetState !== "internal" ||
+            observedPaths.resolve(entry.target) !== undefined ||
+            excludedPaths.resolve(entry.target) !== undefined)
+            continue;
+        const ancestor = nearestFailedAncestor(entry.target, directoryPaths, failedDirectories, excludedPaths, signal);
+        if (ancestor === undefined)
+            continue;
+        entries[index] = {
+            status: "failed",
+            kind: "symlink",
+            path: entry.path,
+            code: ancestor.code,
+            message: `Symbolic link target ${JSON.stringify(entry.target)} was not inventoried because directory ${JSON.stringify(ancestor.path)} could not be enumerated: ${ancestor.message}`,
+        };
+    }
+};
+const nearestFailedAncestor = (target, directoryPaths, failedDirectories, excludedPaths, signal) => {
+    for (let candidate = posix.dirname(target); candidate !== "." && candidate !== "/"; candidate = posix.dirname(candidate)) {
+        if (isAborted(signal))
+            return undefined;
+        if (excludedPaths.resolve(candidate) !== undefined)
+            return undefined;
+        const observedDirectory = directoryPaths.resolve(candidate);
+        if (observedDirectory !== undefined)
+            return failedDirectories.get(observedDirectory);
+    }
+    if (isAborted(signal))
+        return undefined;
+    if (excludedPaths.resolve(".") !== undefined)
+        return undefined;
+    const observedRoot = directoryPaths.resolve(".");
+    return observedRoot === undefined
+        ? undefined
+        : failedDirectories.get(observedRoot);
+};
 const traverse = async (state) => {
     while (state.pending.length > 0) {
         if (isAborted(state.signal))

package/dist/reference/ReferenceSourceReaderEntries.js

@@ -8,7 +8,6 @@ import { isPathWithinRoot } from "../domain/localPath.js";
 import { pathFromRoot } from "./ReferenceSourceReaderPaths.js";
 import { readStableFile } from "./ReferenceSourceReaderFile.js";
 import { isAborted, sameFile, validateDirectory, bigLstat, } from "./ReferenceSourceReaderValidate.js";
-import {} from "./ReferenceSourceReaderTypes.js";
 export const traverseDirectory = async (state, current) => {
     const before = await validateDirectory(state.root, state.rootIdentity, current.path, state.signal);
     if (isAborted(state.signal))
@@ -85,6 +84,7 @@ export const traverseDirectory = async (state, current) => {
         return { ok: false, error: cancelled() };
     if (readFailure !== undefined) {
         state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "io", readFailure));
+        scheduleObservedDirectories(state, directories);
         return { ok: true, value: undefined };
     }
     const after = await validateDirectory(state.root, state.rootIdentity, current.path, state.signal);
@@ -92,6 +92,7 @@ export const traverseDirectory = async (state, current) => {
         return { ok: false, error: cancelled() };
     if (!after.ok || !sameFile(before.stats, after.stats)) {
         state.entries.push(entryFailure(pathFromRoot(state.root, current.path), "directory", "changed", "Directory changed while it was read"));
+        scheduleObservedDirectories(state, directories);
         return { ok: true, value: undefined };
     }
     if (current.path !== state.root)
@@ -100,9 +101,12 @@ export const traverseDirectory = async (state, current) => {
             kind: "directory",
             path: pathFromRoot(state.root, current.path),
         });
+    scheduleObservedDirectories(state, directories);
+    return { ok: true, value: undefined };
+};
+const scheduleObservedDirectories = (state, directories) => {
     directories.reverse();
     state.pending.push(...directories);
-    return { ok: true, value: undefined };
 };
 const directoryReadFailure = (cause) => {
     const message = filesystemFailureDetail(cause, "Directory could not be read");
@@ -130,6 +134,16 @@ const processEntry = async (state, current, name, directories) => {
     if (isAborted(state.signal))
         return { ok: false, error: cancelled() };
     if (!metadata.ok) {
+        const excluded = applyExclusion(state.shouldExclude, path, "unknown");
+        if (!excluded.ok)
+            return {
+                ok: false,
+                error: failure("io", "Reference source exclusion check failed"),
+            };
+        if (excluded.value) {
+            state.exclusions.push({ path, kind: "unknown" });
+            return { ok: true, value: undefined };
+        }
         state.entries.push(entryFailure(path, "unknown", "io", metadata.message));
         return { ok: true, value: undefined };
     }
@@ -150,12 +164,14 @@ const processEntry = async (state, current, name, directories) => {
                 message: "Reference source exclusion check failed",
             },
         };
-    if (excluded.value)
+    if (excluded.value) {
+        state.exclusions.push({ path, kind });
         return { ok: true, value: undefined };
+    }
     if (isAborted(state.signal))
         return { ok: false, error: cancelled() };
     if (kind === "symlink")
-        state.entries.push(await describeSymlink(state.root, absolute, path, state.signal));
+        state.entries.push(await readStableSymlinkTarget(absolute, path, metadata.value, state.signal, () => readSymlinkTarget(state.root, absolute, path)));
     else if (kind === "directory") {
         directories.push({ path: absolute });
     }
@@ -192,67 +208,74 @@ const processFileEntry = async (state, absolute, path, metadata) => {
         });
     return ok(undefined);
 };
-const describeSymlink = async (root, absolute, path, signal) => {
+/** Bracket target observation with the symlink identity captured at enumeration. */
+export const readStableSymlinkTarget = async (absolute, path, expected, signal, readTarget) => {
     try {
-        const rawTarget = await readlink(absolute);
-        const lexicalTarget = resolve(dirname(absolute), rawTarget);
-        if (!isPathWithinRoot(root, lexicalTarget))
-            return {
-                status: "read",
-                kind: "symlink",
-                path,
-                target: lexicalTarget,
-                targetState: "external",
-            };
-        try {
-            const canonicalTarget = await realpath(lexicalTarget);
-            return isPathWithinRoot(root, canonicalTarget)
-                ? {
-                    status: "read",
-                    kind: "symlink",
-                    path,
-                    target: pathFromRoot(root, canonicalTarget),
-                    targetState: "internal",
-                }
-                : {
-                    status: "read",
-                    kind: "symlink",
-                    path,
-                    target: canonicalTarget,
-                    targetState: "external",
-                };
-        }
-        catch (cause) {
-            if (isAborted(signal))
-                return entryFailure(path, "symlink", "cancelled", "Symlink inspection cancelled");
-            const code = cause instanceof Error ? Reflect.get(cause, "code") : undefined;
-            if (code !== "ENOENT") {
-                const message = filesystemFailureDetail(cause, "Symbolic link target could not be resolved");
-                if (message === undefined)
-                    throw cause;
-                return entryFailure(path, "symlink", "io", message);
-            }
-            const missingOutsideRoot = !isPathWithinRoot(root, lexicalTarget);
-            return {
-                status: "read",
-                kind: "symlink",
-                path,
-                target: missingOutsideRoot
-                    ? lexicalTarget
-                    : pathFromRoot(root, lexicalTarget),
-                targetState: "missing",
-            };
-        }
+        const before = await bigLstat(absolute);
+        if (isAborted(signal))
+            return cancelledSymlink(path);
+        if (!before.isSymbolicLink() || !sameFile(expected, before))
+            return changedSymlink(path);
+        const observed = await readTarget();
+        if (isAborted(signal))
+            return cancelledSymlink(path);
+        const after = await bigLstat(absolute);
+        if (isAborted(signal))
+            return cancelledSymlink(path);
+        if (!after.isSymbolicLink() || !sameFile(expected, after))
+            return changedSymlink(path);
+        return observed;
     }
     catch (cause) {
         if (isAborted(signal))
-            return entryFailure(path, "symlink", "cancelled", "Symlink inspection cancelled");
-        const message = filesystemFailureDetail(cause, "Symbolic link target could not be read");
+            return cancelledSymlink(path);
+        const code = cause instanceof Error ? Reflect.get(cause, "code") : undefined;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return changedSymlink(path);
+        const message = filesystemFailureDetail(cause, "Symbolic link target could not be read safely");
         if (message === undefined)
             throw cause;
         return entryFailure(path, "symlink", "io", message);
     }
 };
+const cancelledSymlink = (path) => entryFailure(path, "symlink", "cancelled", "Symlink inspection cancelled");
+const changedSymlink = (path) => entryFailure(path, "symlink", "changed", "Symbolic link changed while its target was read");
+const readSymlinkTarget = async (root, absolute, path) => {
+    const rawTarget = await readlink(absolute);
+    const lexicalTarget = resolve(dirname(absolute), rawTarget);
+    if (!isPathWithinRoot(root, lexicalTarget))
+        return {
+            status: "read",
+            kind: "symlink",
+            path,
+            target: lexicalTarget,
+            targetState: "external",
+        };
+    let canonicalTarget;
+    try {
+        canonicalTarget = await realpath(lexicalTarget);
+    }
+    catch (cause) {
+        const code = cause instanceof Error ? Reflect.get(cause, "code") : undefined;
+        if (code !== "ENOENT" && code !== "ENOTDIR")
+            throw cause;
+        return {
+            status: "read",
+            kind: "symlink",
+            path,
+            target: pathFromRoot(root, lexicalTarget),
+            targetState: "missing",
+        };
+    }
+    const internal = isPathWithinRoot(root, canonicalTarget);
+    return {
+        status: "read",
+        kind: "symlink",
+        path,
+        target: internal ? pathFromRoot(root, canonicalTarget) : canonicalTarget,
+        targetState: internal ? "internal" : "external",
+    };
+};
 const applyExclusion = (shouldExclude, path, kind) => {
     try {
         return { ok: true, value: shouldExclude?.(path, kind) === true };

package/dist/reference/ReferenceSourceReaderErrors.js

@@ -1,4 +1,3 @@
-import {} from "./ReferenceSourceReaderTypes.js";
 export const failure = (code, message) => ({
     tag: "reference-source-reader",
     code,
@@ -17,6 +16,9 @@ const FILESYSTEM_ERROR_CODES = new Set([
     "EISDIR",
     "ELOOP",
     "EMFILE",
+    // A traversed child can exceed the platform's absolute path limit even
+    // though the selected root and every component are valid.
+    "ENAMETOOLONG",
     "ENFILE",
     "ENOENT",
     "ENOTDIR",
@@ -29,6 +31,8 @@ export const filesystemFailureDetail = (cause, operation) => {
     if (!(cause instanceof Error))
         return undefined;
     const code = Reflect.get(cause, "code");
+    if (code === "ENAMETOOLONG")
+        return `${operation}: ENAMETOOLONG (entry path exceeds the operating system path limit)`;
     return typeof code === "string" && FILESYSTEM_ERROR_CODES.has(code)
         ? `${operation}: ${cause.message}`
         : undefined;

package/dist/reference/ReferenceSourceReaderFile.js

@@ -1,10 +1,10 @@
+import { regularFileCancellation } from "../filesystem/OwnedRegularFile.js";
 import { dirname } from "node:path";
 import { NonRegularFileReadError, RegularFileAdmissionFailure, openRegularFile, } from "../filesystem/RegularFile.js";
 import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
 import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { entryFailure, filesystemFailureDetail, safeSize, } from "./ReferenceSourceReaderErrors.js";
 import { isAborted, sameFile, validateDirectory, } from "./ReferenceSourceReaderValidate.js";
-import {} from "./ReferenceSourceReaderTypes.js";
 const READ_CHUNK_BYTES = 64 * 1024;
 const prepareFileRead = async (request, handle) => {
     const { path, expected, signal } = request;
@@ -136,7 +136,7 @@ const readStableFileEntry = async (request, retain) => {
             retain(cause.owner);
             cause = cause.cause;
         }
-        if (isAborted(signal))
+        if (regularFileCancellation(cause) !== undefined || isAborted(signal))
             return entryFailure(path, "file", "cancelled", "File read cancelled", safeSize(expected.size));
         if (cause instanceof NonRegularFileReadError)
             return entryFailure(path, "file", "changed", "File is no longer a regular file", safeSize(expected.size));

package/dist/reference/ReferenceSourceReaderTypes.js

@@ -1,2 +1 @@
-import {} from "node:fs";
-import {} from "../domain/result.js";
+export {};

package/dist/reference/ReferenceSourceReaderValidate.js

@@ -3,7 +3,6 @@ import { lstat, realpath } from "node:fs/promises";
 import { err, ok } from "../domain/result.js";
 import { cancelled, failure, filesystemFailureDetail, rootFilesystemFailure, } from "./ReferenceSourceReaderErrors.js";
 import { isPathWithinRoot } from "../domain/localPath.js";
-import {} from "./ReferenceSourceReaderTypes.js";
 export const bigLstat = (path) => lstat(path, { bigint: true });
 export const sameFile = (left, right) => left.dev === right.dev &&
     left.ino === right.ino &&