rea-agents 0.2.1 → 0.4.0

package/dist/application/ProcessSampling.js

@@ -0,0 +1,284 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const PROC_READ_CONCURRENCY = 64;
+const isExpectedProcReadFailure = (cause) => cause instanceof Error &&
+    "code" in cause &&
+    (cause.code === "ENOENT" ||
+        cause.code === "ESRCH" ||
+        cause.code === "EACCES" ||
+        cause.code === "EPERM");
+const handleProcReadFailure = (cause) => {
+    if (isExpectedProcReadFailure(cause))
+        return undefined;
+    throw cause;
+};
+const parseProcStat = (identifier, stat) => {
+    const commandEnd = stat.lastIndexOf(")");
+    if (commandEnd < 0)
+        return undefined;
+    const fields = stat
+        .slice(commandEnd + 2)
+        .trim()
+        .split(/\s+/);
+    const pid = Number(identifier);
+    const parentPid = Number(fields[1]);
+    const startTime = fields[19];
+    if (!Number.isSafeInteger(pid) ||
+        pid <= 0 ||
+        !Number.isSafeInteger(parentPid) ||
+        parentPid < 0 ||
+        startTime === undefined ||
+        !/^\d+$/.test(startTime))
+        return undefined;
+    return {
+        pid,
+        parent_pid: parentPid,
+        command: "",
+        startTime,
+    };
+};
+const readProcessStat = async (pid, signal) => {
+    try {
+        const stat = await readFile(`/proc/${String(pid)}/stat`, {
+            encoding: "utf8",
+            signal,
+        });
+        return parseProcStat(String(pid), stat);
+    }
+    catch (cause) {
+        return handleProcReadFailure(cause);
+    }
+};
+const readProcessCommand = async (pid, signal) => {
+    try {
+        return await readFile(`/proc/${String(pid)}/cmdline`, { signal });
+    }
+    catch (cause) {
+        return handleProcReadFailure(cause);
+    }
+};
+const readLinuxChildren = async (pid, signal) => {
+    let text;
+    try {
+        text = await readFile(`/proc/${String(pid)}/task/${String(pid)}/children`, {
+            encoding: "utf8",
+            signal,
+        });
+    }
+    catch (cause) {
+        return handleProcReadFailure(cause);
+    }
+    return text
+        .trim()
+        .split(/\s+/)
+        .filter((value) => /^\d+$/.test(value))
+        .map(Number)
+        .filter((child) => Number.isSafeInteger(child) && child > 0);
+};
+const inspectProcess = async (pid, expectedParent, signal, identities) => {
+    const before = await readProcessStat(pid, signal);
+    if (before === undefined || before.startTime === undefined)
+        return undefined;
+    const existing = identities.get(pid);
+    if (existing !== undefined && existing !== before.startTime)
+        return undefined;
+    if (expectedParent !== undefined && before.parent_pid !== expectedParent)
+        return undefined;
+    const [commandBuffer, children] = await Promise.all([
+        readProcessCommand(pid, signal),
+        readLinuxChildren(pid, signal),
+    ]);
+    const after = await readProcessStat(pid, signal);
+    if (after === undefined || after.startTime === undefined)
+        return undefined;
+    if (before.startTime !== after.startTime ||
+        before.parent_pid !== after.parent_pid)
+        return undefined;
+    if (expectedParent !== undefined && after.parent_pid !== expectedParent)
+        return undefined;
+    const command = commandBuffer === undefined
+        ? ""
+        : commandBuffer.toString().replaceAll("\0", " ").trim();
+    return {
+        pid: before.pid,
+        parent_pid: before.parent_pid,
+        startTime: before.startTime,
+        command,
+        children: children ?? [],
+    };
+};
+const sampleLinux = async (context) => {
+    const { rootPid, limit, signal, sampledPids, identities } = context;
+    if (limit <= 0)
+        return [];
+    const rootStat = await readProcessStat(rootPid, signal);
+    if (rootStat === undefined)
+        return [];
+    const rootChildren = await readLinuxChildren(rootPid, signal);
+    if (rootChildren === undefined)
+        return samplePs(context);
+    const rows = [];
+    const visited = new Set([rootPid]);
+    let level = [{ pid: rootPid, expectedParent: undefined }];
+    while (level.length > 0 && rows.length < limit) {
+        const batchSize = Math.min(level.length, PROC_READ_CONCURRENCY);
+        const batch = level.slice(0, batchSize);
+        level = level.slice(batchSize);
+        const batchResults = await Promise.all(batch.map((item) => inspectProcess(item.pid, item.expectedParent, signal, identities)));
+        const nextLevel = [];
+        for (const node of batchResults) {
+            if (node === undefined)
+                continue;
+            if (!sampledPids.has(node.pid)) {
+                if (rows.length >= limit)
+                    break;
+                rows.push(node);
+            }
+            if (rows.length >= limit)
+                break;
+            for (const child of node.children) {
+                if (visited.has(child))
+                    continue;
+                visited.add(child);
+                nextLevel.push({ pid: child, expectedParent: node.pid });
+            }
+            if (rows.length >= limit)
+                break;
+        }
+        level.push(...nextLevel);
+    }
+    return rows;
+};
+const readPsRows = async (signal) => {
+    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,ppid=,command="], { signal });
+    return stdout
+        .split("\n")
+        .map((line) => /\s*(\d+)\s+(\d+)\s+(.*)/u.exec(line))
+        .filter((match) => match !== null)
+        .map((match) => ({
+        pid: Number(match[1]),
+        parent_pid: Number(match[2]),
+        command: match[3] ?? "",
+        startTime: undefined,
+    }))
+        .filter((row) => Number.isSafeInteger(row.pid) &&
+        row.pid > 0 &&
+        Number.isSafeInteger(row.parent_pid) &&
+        row.parent_pid >= 0)
+        .sort((left, right) => left.pid - right.pid);
+};
+const samplePs = async (context) => {
+    const { rootPid, limit, signal, sampledPids } = context;
+    if (limit <= 0)
+        return [];
+    const rows = await readPsRows(signal);
+    const rowByPid = new Map(rows.map((row) => [row.pid, row]));
+    const childrenByParent = new Map();
+    for (const row of rows) {
+        const siblings = childrenByParent.get(row.parent_pid) ?? [];
+        siblings.push(row);
+        childrenByParent.set(row.parent_pid, siblings);
+    }
+    const result = [];
+    const visited = new Set();
+    const queue = [rootPid];
+    let index = 0;
+    while (index < queue.length && result.length < limit) {
+        const pid = queue[index];
+        if (pid === undefined)
+            break;
+        index += 1;
+        if (visited.has(pid))
+            continue;
+        visited.add(pid);
+        const row = rowByPid.get(pid);
+        if (row !== undefined && !sampledPids.has(row.pid)) {
+            result.push(row);
+        }
+        if (result.length >= limit)
+            break;
+        for (const child of childrenByParent.get(pid) ?? []) {
+            if (!visited.has(child.pid))
+                queue.push(child.pid);
+        }
+    }
+    return result;
+};
+const sampleProcesses = async (context) => {
+    if (process.platform === "win32" || context.limit <= 0)
+        return [];
+    const rows = process.platform === "linux"
+        ? await sampleLinux(context)
+        : await samplePs(context);
+    const { elapsedMs, sampledPids, identities } = context;
+    const samples = [];
+    for (const row of rows) {
+        if (sampledPids.has(row.pid))
+            continue;
+        if (row.startTime !== undefined) {
+            const existing = identities.get(row.pid);
+            if (existing !== undefined && existing !== row.startTime)
+                continue;
+            identities.set(row.pid, row.startTime);
+        }
+        samples.push({
+            at_ms: elapsedMs,
+            pid: row.pid,
+            parent_pid: row.parent_pid,
+            command: row.command,
+        });
+    }
+    return samples;
+};
+/** Start bounded process-tree sampling and expose an awaited stop. */
+export const startProcessSampler = (rootPid, started, limit, samples) => {
+    const identities = new Map();
+    const sampledPids = new Set(samples.map(({ pid }) => pid));
+    let pending;
+    let stopped = false;
+    let abortCurrent;
+    let partial = false;
+    const sample = () => {
+        if (stopped || pending !== undefined || sampledPids.size >= limit)
+            return;
+        const controller = new AbortController();
+        abortCurrent = () => controller.abort();
+        pending = sampleProcesses({
+            rootPid,
+            elapsedMs: Date.now() - started,
+            limit: limit - sampledPids.size,
+            sampledPids,
+            identities,
+            signal: controller.signal,
+        })
+            .then((values) => {
+            for (const value of values) {
+                if (sampledPids.size >= limit)
+                    break;
+                if (sampledPids.has(value.pid))
+                    continue;
+                sampledPids.add(value.pid);
+                samples.push(value);
+            }
+        })
+            .catch((cause) => {
+            if (!(cause instanceof Error && cause.name === "AbortError"))
+                partial = true;
+        })
+            .then(() => {
+            abortCurrent = undefined;
+            pending = undefined;
+        });
+    };
+    const timer = setInterval(sample, 50);
+    sample();
+    return async () => {
+        stopped = true;
+        clearInterval(timer);
+        abortCurrent?.();
+        await pending;
+        return { partial };
+    };
+};

package/dist/application/RealHopperAssertions.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+const addressSchema = z.string().regex(/^0x[0-9a-f]+$/iu);
+const identitySchema = z.object({ address: addressSchema, name: z.string() });
+const collectionSchema = z.object({
+    items: z.array(z.unknown()),
+    total: z.number().int().min(0).nullable(),
+    returned: z.number().int().min(0),
+    truncated: z.boolean(),
+    next_offset: z.number().int().min(0).nullable(),
+});
+/** Extract a real address from the provider's exact procedure page. */
+export const firstProcedureAddress = (input) => {
+    const page = z
+        .object({
+        items: z.array(z.object({ address: addressSchema })).min(1),
+        offset: z.number().int().min(0),
+        limit: z.number().int().min(1),
+        total: z.number().int().min(1),
+        next_offset: z.number().int().min(0).nullable(),
+        has_more: z.boolean(),
+    })
+        .parse(input);
+    const first = page.items[0];
+    if (first === undefined)
+        throw new TypeError("Procedure page was empty");
+    return first.address;
+};
+/** Reject empty and success-shaped embedded decompilation failures. */
+export const requirePseudocode = (input, operation) => {
+    if (typeof input !== "string" || input.trim().length === 0)
+        throw new TypeError(`${operation} returned empty pseudocode`);
+    if (input === "No output" || input.startsWith("Error:"))
+        throw new TypeError(`${operation} returned an embedded failure: ${input}`);
+    return input;
+};
+/** Validate an exact bounded Hopper function dossier semantically. */
+export const requireFunctionDossier = (input, expectedAddress) => {
+    const value = objectValue(input, "analyze_function returned no function dossier");
+    const procedure = identitySchema.parse(value.procedure);
+    if (procedure.address !== expectedAddress)
+        throw new TypeError("analyze_function returned the wrong procedure");
+    if (procedure.name.trim().length === 0)
+        throw new TypeError("analyze_function omitted the procedure name");
+    validatePseudocodeBounds(value.pseudocode);
+    for (const field of COLLECTION_FIELDS)
+        validateCollection(value[field], field);
+    for (const field of ["callers", "callees"])
+        z.array(identitySchema).parse(collectionSchema.parse(value[field]).items);
+    validateBlocks(collectionSchema.parse(value.basic_blocks).items);
+    validateInstructionScan(value.instruction_scan);
+    return value;
+};
+/** Require every relationship to be an actual hexadecimal address. */
+export const requireAddressArray = (input, operation) => {
+    const parsed = z.array(addressSchema).parse(input);
+    if (parsed.some((address) => address.length === 0))
+        throw new TypeError(`${operation} returned an invalid address list`);
+    return parsed;
+};
+const COLLECTION_FIELDS = [
+    "comments",
+    "callers",
+    "callees",
+    "incoming_references",
+    "outgoing_references",
+    "referenced_strings",
+    "referenced_names",
+    "basic_blocks",
+];
+const validatePseudocodeBounds = (input) => {
+    const pseudocode = z
+        .object({
+        text: z.string(),
+        returned_chars: z.number().int().min(0),
+        total_chars: z.number().int().min(0),
+    })
+        .parse(input);
+    const text = requirePseudocode(pseudocode.text, "analyze_function");
+    if (pseudocode.returned_chars !== [...text].length ||
+        pseudocode.total_chars < pseudocode.returned_chars)
+        throw new TypeError("analyze_function returned inconsistent pseudocode bounds");
+};
+const validateCollection = (input, field) => {
+    const collection = collectionSchema.parse(input);
+    if (collection.returned !== collection.items.length)
+        throw new TypeError(`analyze_function returned an invalid ${field} result`);
+};
+const validateBlocks = (items) => {
+    for (const block of items)
+        if (!Array.isArray(objectValue(block, "Invalid basic block").successors))
+            throw new TypeError("analyze_function omitted CFG successor evidence");
+};
+const validateInstructionScan = (input) => {
+    const scan = z
+        .object({ scanned: z.number().int().min(0), truncated: z.boolean() })
+        .parse(input);
+    if (scan.scanned === 0 && !scan.truncated)
+        throw new TypeError("analyze_function omitted instruction scan limitations");
+};
+const objectValue = (input, message) => {
+    const parsed = z.record(z.string(), z.unknown()).safeParse(input);
+    if (!parsed.success)
+        throw new TypeError(message);
+    return parsed.data;
+};

package/dist/application/ReferenceSourceImport.js

@@ -0,0 +1,182 @@
+import { isSecretLikePath } from "../domain/referenceSourceClassification.js";
+import { createHistoricalSourceGraph, } from "../domain/referenceSourceGraph.js";
+import { err, ok } from "../domain/result.js";
+import { readReferenceSource } from "../reference/ReferenceSourceReader.js";
+import { parseReferenceSourceEntries } from "./ReferenceSourceImportEntries.js";
+import { readReferenceSourceVcs } from "./ReferenceSourceVcsAdapter.js";
+import {} from "./ReferenceSourceImportTypes.js";
+import { prepareReferenceSourceImport } from "./ReferenceSourceImportPolicy.js";
+const compareCodePoints = (left, right) => {
+    const leftPoints = [...left].map((value) => value.codePointAt(0) ?? 0);
+    const rightPoints = [...right].map((value) => value.codePointAt(0) ?? 0);
+    const length = Math.min(leftPoints.length, rightPoints.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = (leftPoints[index] ?? 0) - (rightPoints[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return leftPoints.length - rightPoints.length;
+};
+const byCodePoint = (left, right) => compareCodePoints(left, right);
+const failure = (code, message) => ({
+    tag: "reference-source-import",
+    code,
+    message,
+});
+const cancelled = () => failure("cancelled", "Reference source import cancelled");
+const isAborted = (signal) => signal?.aborted === true;
+const relationshipKey = (relationship) => `${relationship.from_path}\u0000${relationship.to}\u0000${relationship.kind}\u0000${relationship.resolution}\u0000${relationship.parse_state}`;
+const deduplicateRelationships = (relationships) => {
+    const seen = new Set();
+    const result = [];
+    for (const relationship of relationships) {
+        const key = relationshipKey(relationship);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(relationship);
+    }
+    return result;
+};
+const buildProvenance = (options) => ({
+    importer: options.importer ?? "rea-reference-source-import",
+    importer_version: options.importerVersion ?? null,
+    caller: options.caller,
+});
+const deriveLanguages = (entries) => [
+    ...new Set(entries.flatMap((entry) => entry.kind === "file" && entry.language !== null
+        ? [entry.language]
+        : [])),
+].sort(byCodePoint);
+const deriveManifests = (entries) => entries
+    .flatMap((entry) => entry.kind === "file" && entry.classifications.includes("manifest")
+    ? [entry.path]
+    : [])
+    .sort(byCodePoint);
+const deriveInventoryState = (input) => {
+    if (input.limitations.length > 0)
+        return "partial";
+    if (input.exclusions.length > 0)
+        return "partial";
+    if (input.parse_failures.length > 0)
+        return "partial";
+    const partialEntry = input.entries.some((entry) => entry.limitations.length > 0 ||
+        (entry.kind === "file" && entry.content_state !== "hashed") ||
+        (entry.kind === "directory" && entry.tree_state !== "enumerated") ||
+        (entry.kind === "symlink" && entry.target_state !== "internal"));
+    if (partialEntry)
+        return "partial";
+    const partialRelationship = input.relationships.some(({ parse_state, resolution }) => parse_state !== "parsed" ||
+        ["unresolved", "unknown"].includes(resolution));
+    if (partialRelationship)
+        return "partial";
+    return "complete";
+};
+const sortAndLimit = (exclusions, maxExclusions) => {
+    const sorted = [...exclusions].sort((left, right) => {
+        const byPath = byCodePoint(left.path, right.path);
+        if (byPath !== 0)
+            return byPath;
+        return byCodePoint(left.reason, right.reason);
+    });
+    if (sorted.length <= maxExclusions)
+        return sorted;
+    return sorted.slice(0, maxExclusions);
+};
+/**
+ * Import a reference source directory into a committed historical source graph.
+ *
+ * The import is deterministic, parallel-safe, and never executes source, hooks,
+ * git subprocesses, or network requests. Secret-like paths are redacted before
+ * they are committed to the graph.
+ */
+export const importReferenceSource = async (options) => {
+    if (isAborted(options.signal))
+        return err(cancelled());
+    const prepared = await prepareReferenceSourceImport(options);
+    if (!prepared.ok)
+        return prepared;
+    const { ignored, limits, root, secrets } = prepared.value;
+    if (isAborted(options.signal))
+        return err(cancelled());
+    const exclusions = [];
+    const shouldExclude = (path) => {
+        if (isSecretLikePath(path) || secrets.ignores(path)) {
+            exclusions.push({ path, reason: "configured-secret" });
+            return true;
+        }
+        if (ignored.ignores(path)) {
+            exclusions.push({ path, reason: "caller-excluded" });
+            return true;
+        }
+        return false;
+    };
+    const [readResult, vcs] = await Promise.all([
+        readReferenceSource(root, limits, {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            shouldExclude,
+        }),
+        readReferenceSourceVcs(root, options.signal),
+    ]);
+    if (!readResult.ok) {
+        const error = readResult.error;
+        if (error.code === "cancelled")
+            return err(cancelled());
+        return err(failure(error.code === "invalid-limits" ? "invalid-limits" : "io", error.message));
+    }
+    if (isAborted(options.signal))
+        return err(cancelled());
+    const read = readResult.value;
+    const filePaths = new Set(read.entries
+        .filter((entry) => entry.status === "read" && entry.kind === "file")
+        .map((entry) => entry.path));
+    const { entries, relationships, parseFailures, limitations } = parseReferenceSourceEntries(read, filePaths, options.signal);
+    if (isAborted(options.signal))
+        return err(cancelled());
+    const uniqueRelationships = deduplicateRelationships(relationships);
+    const uniqueFailures = [...parseFailures]
+        .sort((left, right) => {
+        const byPath = byCodePoint(left.path, right.path);
+        if (byPath !== 0)
+            return byPath;
+        return byCodePoint(left.parser, right.parser);
+    })
+        .filter((value, index, array) => {
+        if (index === 0)
+            return true;
+        const previous = array[index - 1];
+        if (previous === undefined)
+            return true;
+        return value.path !== previous.path || value.parser !== previous.parser;
+    });
+    const sortedEntries = [...entries].sort((left, right) => byCodePoint(left.path, right.path));
+    const sortedExclusions = sortAndLimit(exclusions, limits.maxEntries);
+    const sortedLimitations = [...limitations].sort(byCodePoint);
+    const input = {
+        schema: "HistoricalSourceGraph/v1",
+        authority: "historical-reference",
+        root_alias: "$REFERENCE_ROOT",
+        inventory_state: deriveInventoryState({
+            entries: sortedEntries,
+            relationships: uniqueRelationships,
+            parse_failures: uniqueFailures,
+            exclusions: sortedExclusions,
+            limitations: sortedLimitations,
+        }),
+        entries: sortedEntries,
+        relationships: uniqueRelationships.sort((left, right) => byCodePoint(relationshipKey(left), relationshipKey(right))),
+        parse_failures: uniqueFailures,
+        exclusions: sortedExclusions,
+        languages: deriveLanguages(sortedEntries),
+        manifests: deriveManifests(sortedEntries),
+        vcs,
+        provenance: buildProvenance(options),
+        limitations: sortedLimitations,
+    };
+    try {
+        return ok(createHistoricalSourceGraph(input));
+    }
+    catch (error) {
+        return err(failure("parse", error instanceof Error ? error.message : "Graph failed validation"));
+    }
+};

package/dist/application/ReferenceSourceImportEntries.js

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+import { classifyReferenceSourcePath, detectReferenceSourceLanguage, } from "../domain/referenceSourceClassification.js";
+import { parseReferenceSourceImports } from "../domain/referenceSourceImportParsing.js";
+import { PARSEABLE_REFERENCE_SOURCE_LANGUAGES } from "./ReferenceSourceImportTypes.js";
+const hashBytes = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const failedEntry = (entry) => {
+    const classifications = classifyReferenceSourcePath(entry.path);
+    if (entry.kind === "directory")
+        return {
+            path: entry.path,
+            kind: "directory",
+            classifications,
+            tree_state: entry.code === "limit" ? "partial" : "unreadable",
+            limitations: [entry.message],
+        };
+    if (entry.kind === "symlink")
+        return {
+            path: entry.path,
+            kind: "symlink",
+            target: "<unreadable>",
+            target_state: "unreadable",
+            classifications,
+            limitations: [entry.message],
+        };
+    return {
+        path: entry.path,
+        kind: "file",
+        sha256: null,
+        size: entry.size ?? null,
+        language: null,
+        classifications: entry.kind === "file" ? classifications : ["unknown"],
+        content_state: entry.code === "limit" ? "too-large" : "unreadable",
+        limitations: [entry.message],
+    };
+};
+const resolveInternalSpecifier = (fromPath, specifier, filePaths) => {
+    const normalized = posix.normalize(posix.join(posix.dirname(fromPath), specifier));
+    if (normalized.startsWith("../") || normalized === "..")
+        return { to: normalized, resolution: "unresolved" };
+    const suffixes = ["", ".ts", ".js", ".mjs", ".cjs", ".tsx", ".jsx"];
+    const candidates = suffixes.flatMap((suffix) => [
+        `${normalized}${suffix}`,
+        `${normalized}/index${suffix}`,
+    ]);
+    const match = candidates.find((candidate) => filePaths.has(candidate));
+    return match === undefined
+        ? { to: normalized, resolution: "unresolved" }
+        : { to: match, resolution: "internal" };
+};
+const appendFile = (entry, filePaths, output) => {
+    const language = detectReferenceSourceLanguage(entry.path);
+    output.entries.push({
+        path: entry.path,
+        kind: "file",
+        sha256: hashBytes(entry.bytes),
+        size: entry.size,
+        language,
+        classifications: classifyReferenceSourcePath(entry.path),
+        content_state: "hashed",
+        limitations: [],
+    });
+    if (language === null || !PARSEABLE_REFERENCE_SOURCE_LANGUAGES.has(language))
+        return;
+    const parsed = parseReferenceSourceImports(entry.path, entry.bytes, language);
+    for (const relationship of parsed.relationships) {
+        if (relationship.resolution !== "internal") {
+            output.relationships.push(relationship);
+            continue;
+        }
+        const resolved = resolveInternalSpecifier(relationship.from_path, relationship.to, filePaths);
+        output.relationships.push({
+            ...relationship,
+            to: resolved.to,
+            resolution: resolved.resolution,
+        });
+    }
+    output.parseFailures.push(...parsed.parse_failures);
+};
+const appendReadEntry = (entry, filePaths, output) => {
+    if (entry.kind === "file") {
+        appendFile(entry, filePaths, output);
+        return;
+    }
+    const classifications = classifyReferenceSourcePath(entry.path);
+    if (entry.kind === "directory") {
+        output.entries.push({
+            path: entry.path,
+            kind: "directory",
+            classifications,
+            tree_state: "enumerated",
+            limitations: [],
+        });
+        return;
+    }
+    output.entries.push({
+        path: entry.path,
+        kind: "symlink",
+        target: entry.target,
+        target_state: entry.targetState,
+        classifications,
+        limitations: [],
+    });
+};
+/** Convert bounded reader observations into graph entries and parsed edges. */
+export const parseReferenceSourceEntries = (read, filePaths, signal) => {
+    const output = {
+        entries: [],
+        relationships: [],
+        parseFailures: [],
+        limitations: [...read.limitations],
+    };
+    for (const entry of read.entries) {
+        if (signal?.aborted === true)
+            break;
+        if (entry.status === "failed")
+            output.entries.push(failedEntry(entry));
+        else
+            appendReadEntry(entry, filePaths, output);
+    }
+    return output;
+};