rea-agents 4.1.0 → 6.0.0

package/dist/javascript/recovery/WakaruCommand.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, realpath } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
+import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../process/ProviderProcess.js";
+import { checkRecoveryDeadline, inventoryRecoveryFiles, fingerprintRecoveryFile, recoveryFailureMessage, } from "./RecoveryFiles.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+/** Resolve and fingerprint explicitly configured tools; acquire nothing at startup. */
+export const resolveWakaruCommand = async (environment) => {
+    const configured = environment.REA_WAKARU_COMMAND;
+    if (process.platform !== "linux" ||
+        process.arch !== "x64" ||
+        configured === undefined ||
+        !isAbsolute(configured))
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA");
+    try {
+        const command = await realpath(configured);
+        await access(command, constants.R_OK | constants.X_OK);
+        const fingerprint = await fingerprintRecoveryFile(command, RECOVERY_LIMITS.outputBytes);
+        const limiter = environment.REA_JAVASCRIPT_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+        if (!isAbsolute(limiter))
+            throw new TypeError("REA_JAVASCRIPT_PRLIMIT_COMMAND must be absolute");
+        await access(limiter, constants.X_OK);
+        return { command, limiter, ...fingerprint };
+    }
+    catch (cause) {
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`, { cause });
+    }
+};
+/** Run one bounded command and verify cleanup before consuming its output. */
+export const runWakaruCommand = async (context) => {
+    checkRecoveryDeadline(context.deadline, context.signal);
+    const runId = `rea-wakaru-${randomUUID()}`;
+    const spawned = await (context.launcher ?? spawnOwnedProviderProcess)({
+        command: context.limiter,
+        arguments: [
+            `--as=${String(RECOVERY_LIMITS.addressSpaceBytes)}`,
+            `--fsize=${String(RECOVERY_LIMITS.outputBytes)}`,
+            "--core=0",
+            "--cpu=120",
+            "--",
+            context.command,
+            ...context.arguments,
+        ],
+        expectedCommand: null,
+        runId,
+        cwd: context.cwd,
+        hostEnvironment: context.environment,
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+        env: { TMPDIR: context.cwd, RAYON_NUM_THREADS: "1", NO_COLOR: "1" },
+    }).catch((cause) => {
+        if (context.signal?.aborted === true)
+            throw new AnalysisCancelledError(OPERATION);
+        throw new ProviderAdapterError("wakaru", OPERATION, {
+            cause,
+            diagnostics: {
+                reason: "Failed to launch configured Wakaru through util-linux prlimit",
+                command: context.command,
+                detail: recoveryFailureMessage(cause),
+            },
+        });
+    });
+    let oversized = false;
+    const supervisor = new ProviderProcessSupervisor({
+        ...spawned,
+        ownsProcessLifetime: true,
+        cleanup: spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
+    }, {
+        onDiagnostic: (event) => {
+            if (event.type === "output" &&
+                event.totalBytes > RECOVERY_LIMITS.reportBytes)
+                oversized = true;
+        },
+    });
+    let failure;
+    try {
+        while (!(await supervisor.waitForOutputClose(100))) {
+            checkRecoveryDeadline(context.deadline, context.signal);
+            if (oversized)
+                throw new AnalysisOutputError(OPERATION, "Wakaru diagnostic stream exceeds 8 MiB");
+            if (context.staging !== undefined)
+                await inventoryRecoveryFiles(context.staging, context.signal);
+        }
+        checkRecoveryDeadline(context.deadline, context.signal);
+        if (oversized)
+            throw new AnalysisOutputError(OPERATION, "Wakaru diagnostic stream exceeds 8 MiB");
+    }
+    catch (cause) {
+        failure = cause;
+    }
+    const stopped = await supervisor.stop();
+    const snapshot = supervisor.snapshot();
+    supervisor.dispose();
+    if (stopped.status === "incomplete")
+        throw new ProviderCleanupError("wakaru", [runId, context.cwd], {
+            reason: stopped.reason,
+            previous_error: failure instanceof Error ? failure.message : null,
+            exit_code: snapshot.exitCode ?? null,
+            signal: snapshot.signal ?? null,
+        });
+    if (failure !== undefined)
+        throw failure;
+    if (context.signal?.aborted === true)
+        throw new AnalysisCancelledError(OPERATION);
+    return {
+        exit_code: snapshot.exitCode ?? null,
+        signal: snapshot.signal ?? null,
+        stdout: snapshot.stdout.text,
+        stderr: snapshot.stderr.text,
+        command: context.command,
+        arguments: [...context.arguments],
+        resource_limiter: context.limiter,
+    };
+};

package/dist/javascript/recovery/WakaruExecution.js

@@ -0,0 +1,100 @@
+import { join } from "node:path";
+import { createAnalysisExecution, } from "../../application/AnalysisProvider.js";
+import { AnalysisCapabilityUnavailableError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { jsonValueSchema } from "../../domain/jsonValue.js";
+import { fingerprintRecoveryFile, inventoryRecoveryFiles, readRecoveryFile, recoveryDigest, } from "./RecoveryFiles.js";
+import { runWakaruCommand, } from "./WakaruCommand.js";
+import { parseWakaruReports } from "./WakaruReport.js";
+import { publishWakaruArtifacts } from "./WakaruPublication.js";
+import { RECOVERY_LIMITS, WAKARU_RELEASE, WAKARU_PROVIDER_IDENTITY, } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+const MODES = {
+    structural: "strict",
+    heuristic: "auto",
+    inspection: "inspect",
+};
+/** Consume the pinned producer representation in a private workspace. */
+const executeWakaruRecovery = async (context) => {
+    const { root, input, source, engine, environment, launcher, options } = context;
+    const staging = join(root, "modules");
+    const commandContext = {
+        ...engine,
+        cwd: root,
+        deadline: context.deadline,
+        environment: environment,
+        ...(options?.signal === undefined ? {} : { signal: options.signal }),
+        ...(launcher === undefined ? {} : { launcher: launcher }),
+    };
+    const version = await runWakaruCommand({
+        ...commandContext,
+        arguments: ["--version"],
+    });
+    if (version.exit_code !== 0 ||
+        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`)
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}; stderr: ${version.stderr}`);
+    const run = await runWakaruCommand({
+        ...commandContext,
+        staging,
+        arguments: [
+            source.snapshot_path,
+            `--unpack=${MODES[input.extraction_mode]}`,
+            `--level=${input.rewrite_level}`,
+            "--provenance",
+            "--emit-source-map",
+            "--json",
+            "-o",
+            staging,
+        ],
+    });
+    const files = await inventoryRecoveryFiles(staging, options?.signal);
+    const snapshot = await readRecoveryFile(source.snapshot_path, RECOVERY_LIMITS.inputBytes, options?.signal);
+    const parsed = await parseWakaruReports({
+        execution: run,
+        provenancePath: join(staging, "provenance.json"),
+        snapshotPath: source.snapshot_path,
+        sourceBytes: snapshot,
+        files,
+    });
+    return { version, run, parsed };
+};
+/** Publish validated recovery and retain exact source and engine bindings. */
+export const prepareWakaruExecution = async (context) => {
+    const { root, tree, input, source, engine, options } = context;
+    const staging = join(root, "modules");
+    const { version, run, parsed } = await executeWakaruRecovery(context);
+    const result = await publishWakaruArtifacts({
+        tree,
+        staging,
+        input,
+        source,
+        engine,
+        parsed,
+        execution: run,
+        ...(options?.signal === undefined ? {} : { signal: options.signal }),
+    });
+    if (recoveryDigest(await readRecoveryFile(input.path, RECOVERY_LIMITS.inputBytes, options?.signal)) !== source.sha256)
+        throw new AnalysisOutputError(OPERATION, `Original input changed during recovery: ${input.path}`);
+    if ((await fingerprintRecoveryFile(engine.command, RECOVERY_LIMITS.outputBytes, options?.signal)).sha256 !== engine.sha256)
+        throw new AnalysisOutputError(OPERATION, "Configured engine bytes changed during recovery");
+    return createAnalysisExecution(result, WAKARU_PROVIDER_IDENTITY, {
+        rawResult: jsonValueSchema.parse({
+            version,
+            execution: run,
+            report: parsed.report,
+            provenance: parsed.provenance,
+        }),
+        subject: {
+            path: source.path,
+            sha256: source.sha256,
+            format: "javascript",
+        },
+        locations: [
+            { kind: "artifact-path", path: source.path },
+            ...result.modules.map((module) => ({
+                kind: "artifact-path",
+                path: module.artifact.path,
+            })),
+        ],
+        limitations: result.limitations,
+    });
+};

package/dist/javascript/recovery/WakaruProvider.js

@@ -0,0 +1,96 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {} from "../../application/AnalysisProvider.js";
+import { SafeOutputTree } from "../../artifacts/SafeOutputTree.js";
+import { AnalysisError } from "../../domain/analysisErrorBase.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { err, ok } from "../../domain/result.js";
+import { checkRecoveryCancellation, checkRecoveryDeadline, recoveryFailureMessage, recoveryInputFailure, snapshotRecoveryInput, } from "./RecoveryFiles.js";
+import { resolveWakaruCommand } from "./WakaruCommand.js";
+import { prepareWakaruExecution } from "./WakaruExecution.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const OPERATION = "recover_javascript_sources";
+/** Stateless adapter; each recovery owns its snapshot, process and publication. */
+export class WakaruProvider {
+    environment;
+    launcher;
+    constructor(environment = process.env, launcher) {
+        this.environment = environment;
+        this.launcher = launcher;
+    }
+    /** Recover one script using validated upstream reports and verified output bytes. */
+    async recover(input, options) {
+        let root;
+        let tree;
+        let failure;
+        let execution;
+        const deadline = Date.now() + RECOVERY_LIMITS.timeoutMs;
+        try {
+            checkRecoveryCancellation(options?.signal);
+            const engine = await resolveWakaruCommand(this.environment);
+            root = await mkdtemp(join(tmpdir(), "rea-wakaru-"));
+            const inputs = join(root, "inputs");
+            const staging = join(root, "modules");
+            await mkdir(inputs, { mode: 0o700 });
+            await mkdir(staging, { mode: 0o700 });
+            const source = await snapshotRecoveryInput(input.path, join(inputs, "bundle.js"), options?.signal);
+            tree = await SafeOutputTree.create(input.output_directory).catch((cause) => {
+                throw recoveryInputFailure("output_directory", `Cannot create new recovery directory ${input.output_directory}: ${recoveryFailureMessage(cause)}`, cause);
+            });
+            execution = await prepareWakaruExecution({
+                root,
+                tree,
+                input,
+                source,
+                engine,
+                environment: this.environment,
+                launcher: this.launcher,
+                options,
+                deadline,
+            });
+            checkRecoveryDeadline(deadline, options?.signal);
+            await rm(root, { recursive: true, force: true });
+            root = undefined;
+            checkRecoveryDeadline(deadline, options?.signal);
+            await tree.commit();
+        }
+        catch (cause) {
+            failure = cause;
+        }
+        if (failure !== undefined) {
+            const residuals = [];
+            try {
+                await tree?.rollback();
+            }
+            catch {
+                if (tree !== undefined)
+                    residuals.push(tree.outputRoot);
+            }
+            if (root !== undefined &&
+                !(failure instanceof AnalysisError && failure.cleanupIncomplete)) {
+                try {
+                    await rm(root, { recursive: true, force: true });
+                }
+                catch {
+                    residuals.push(root);
+                }
+            }
+            if (residuals.length > 0)
+                return err(new ProviderCleanupError("wakaru", residuals, {
+                    previous_error: recoveryFailureMessage(failure),
+                }));
+            return err(failure instanceof AnalysisError
+                ? failure
+                : new ProviderAdapterError("wakaru", OPERATION, {
+                    cause: failure,
+                    diagnostics: { reason: recoveryFailureMessage(failure) },
+                }));
+        }
+        return execution === undefined
+            ? err(new AnalysisOutputError(OPERATION, "Recovery returned no execution"))
+            : ok(execution);
+    }
+}

package/dist/javascript/recovery/WakaruPublication.js

@@ -0,0 +1,102 @@
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { javascriptRecoveryResultSchema, } from "../../domain/javascript/javascriptRecovery.js";
+import { readRecoveryFile, recoveryDigest } from "./RecoveryFiles.js";
+import { recoveryRanges, validateRecoverySourceMap, } from "./WakaruReport.js";
+import { RECOVERY_LIMITATIONS, RECOVERY_LIMITS, WAKARU_RELEASE, } from "./WakaruRelease.js";
+/** Write validated artifacts to one exclusively owned, rollback-capable tree. */
+export const publishWakaruArtifacts = async (context) => {
+    const { tree, source, parsed, staging, signal } = context;
+    const write = async (path, bytes) => {
+        const sha256 = recoveryDigest(bytes);
+        const file = await tree.write(path, Readable.from([bytes]), sha256, signal);
+        return {
+            path: join(tree.outputRoot, file.relativePath),
+            sha256: file.sha256,
+            bytes: file.bytesWritten,
+        };
+    };
+    const snapshot = await readRecoveryFile(source.snapshot_path, RECOVERY_LIMITS.inputBytes, signal);
+    if (recoveryDigest(snapshot) !== source.sha256)
+        throw new AnalysisOutputError("recover_javascript_sources", "The input snapshot changed during recovery");
+    const publishedCopy = await write("inputs/bundle.js", snapshot);
+    const modules = [];
+    for (const module of parsed.report.modules) {
+        modules.push(await publishModule(context, module, write));
+    }
+    const report = await write("reports/stdout.json", Buffer.from(context.execution.stdout));
+    const provenance = await write("reports/provenance.json", await readRecoveryFile(join(staging, "provenance.json"), RECOVERY_LIMITS.reportBytes, signal));
+    const details = {
+        source: { ...source, published_copy: publishedCopy },
+        engine: {
+            id: "wakaru",
+            version: WAKARU_RELEASE.version,
+            executable: {
+                path: context.engine.command,
+                sha256: context.engine.sha256,
+                bytes: context.engine.bytes,
+            },
+            audited_source_revision: WAKARU_RELEASE.revision,
+            executed_source_revision: null,
+        },
+        options: {
+            extraction_mode: context.input.extraction_mode,
+            rewrite_level: context.input.rewrite_level,
+        },
+        status: parsed.status,
+        detected_formats: parsed.report.detected_formats,
+        reported_safety: parsed.report.safety,
+        reported_strategy: parsed.provenance.strategy,
+        reported_format: parsed.provenance.format,
+        total: parsed.report.total,
+        failed: parsed.report.failed,
+        modules,
+        warnings: parsed.report.warnings,
+        report,
+        provenance,
+        analysis_input: modules.length === 0
+            ? null
+            : {
+                input_path: join(tree.outputRoot, "modules"),
+                format: "directory",
+            },
+        runtime_equivalence: "unknown",
+        limitations: [...RECOVERY_LIMITATIONS],
+    };
+    const manifest = await write("manifest.json", Buffer.from(`${JSON.stringify(details, null, 2)}\n`));
+    return javascriptRecoveryResultSchema.parse({ ...details, manifest });
+};
+const publishModule = async (context, module, write) => {
+    const { staging, source, parsed, signal } = context;
+    const artifact = await write(`modules/${module.filename}`, await readRecoveryFile(join(staging, module.filename), RECOVERY_LIMITS.outputBytes, signal));
+    const mapPath = join(staging, `${module.filename}.map`);
+    let sourceMap = null;
+    const map = await readRecoveryFile(mapPath, RECOVERY_LIMITS.outputBytes, signal).catch((cause) => {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return null;
+        throw cause;
+    });
+    if (map !== null) {
+        validateRecoverySourceMap(map, module.filename);
+        sourceMap = await write(`modules/${module.filename}.map`, map);
+    }
+    const provenance = parsed.provenance.modules[module.filename];
+    if (provenance === undefined)
+        throw new AnalysisOutputError("recover_javascript_sources", `Missing module provenance: ${module.filename}`);
+    return {
+        reported_filename: module.filename,
+        reported_status: module.status,
+        artifact,
+        source_map: sourceMap,
+        provenance: {
+            reported_input: provenance.input,
+            original_path: source.path,
+            original_sha256: source.sha256,
+            extraction: provenance.extraction,
+            byte_ranges: recoveryRanges(provenance.ranges),
+            context_byte_ranges: recoveryRanges(provenance.context_ranges ?? []),
+            range_semantics: "half-open-utf8-bytes",
+        },
+    };
+};

package/dist/javascript/recovery/WakaruRelease.js

@@ -0,0 +1,29 @@
+/** Unchanged upstream source pin; executed bytes are identified separately. */
+export const WAKARU_RELEASE = {
+    version: "1.13.0",
+    revision: "6070266d24b32951fa2fe1d2dad5b4313bd5c81b",
+    repository: "https://github.com/pionxzh/wakaru",
+};
+/** Exact provider identity shared by executions and the generated catalog. */
+export const WAKARU_PROVIDER_IDENTITY = {
+    id: "wakaru",
+    name: "Wakaru",
+    version: WAKARU_RELEASE.version,
+};
+/** Per-operation resource bounds for the verified Linux adapter. */
+export const RECOVERY_LIMITS = {
+    inputBytes: 64 * 1024 * 1024,
+    outputBytes: 128 * 1024 * 1024,
+    outputEntries: 10000,
+    reportBytes: 8 * 1024 * 1024,
+    addressSpaceBytes: 1024 * 1024 * 1024,
+    timeoutMs: 120000,
+};
+/** Public limitations for transformations and extraction provenance. */
+export const RECOVERY_LIMITATIONS = [
+    "Recovered sources are derived artifacts; original variable names and runtime equivalence are not established.",
+    "Extraction ranges refer to half-open UTF-8 byte offsets in the original input, not rewritten line positions or whole-bundle coverage.",
+    "Emitted source maps are preserved as reported by the engine; their mapping accuracy is not independently established.",
+    "Inspection mode may produce non-executable regions. No input or recovered application code is executed.",
+    "Linux adapter: one worker, 1 GiB address-space ceiling, 120-second deadline, 64 MiB input, 128 MiB output, 10000 output entries and 8 MiB per diagnostic/report stream. Resource limits are per operation, not aggregate host containment.",
+];

package/dist/javascript/recovery/WakaruReport.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { normalizeArtifactPath, ArtifactPathRegistry, } from "../../artifacts/ArtifactPaths.js";
+import { AnalysisOutputError } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { readRecoveryFile, recoveryFailureMessage } from "./RecoveryFiles.js";
+import { RECOVERY_LIMITS } from "./WakaruRelease.js";
+const warningSchema = z.strictObject({
+    filename: z.string(),
+    kind: z.string(),
+    is_error: z.boolean(),
+    message: z.string(),
+});
+const reportSchema = z.strictObject({
+    detected_formats: z.array(z.string()),
+    safety: z.string(),
+    modules: z.array(z.strictObject({
+        filename: z.string().min(1),
+        kind: z.literal("javascript"),
+        status: z.literal("decompiled"),
+    })),
+    warnings: z.array(warningSchema),
+    total: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    elapsed_ms: z.number().int().nonnegative(),
+});
+const rangeSchema = z.tuple([
+    z.number().int().nonnegative(),
+    z.number().int().nonnegative(),
+]);
+const provenanceSchema = z.strictObject({
+    format: z.string(),
+    strategy: z.string(),
+    modules: z.record(z.string(), z.strictObject({
+        input: z.string(),
+        ranges: z.array(rangeSchema),
+        extraction: z.string(),
+        context_ranges: z.array(rangeSchema).optional(),
+    })),
+});
+const OPERATION = "recover_javascript_sources";
+/** Parse exact pinned producer JSON before projecting provider-neutral artifacts. */
+export const parseWakaruReports = async (context) => {
+    const { execution, provenancePath } = context;
+    try {
+        if (execution.exit_code !== 0 && execution.exit_code !== 1)
+            throw new TypeError("Wakaru did not complete recovery (expected exit 0 or a reported partial exit 1)");
+        const report = reportSchema.parse(JSON.parse(execution.stdout));
+        const provenance = provenanceSchema.parse(JSON.parse((await readRecoveryFile(provenancePath, RECOVERY_LIMITS.reportBytes)).toString("utf8")));
+        if (report.total !== report.modules.length || report.failed > report.total)
+            throw new TypeError("Reported module totals disagree");
+        if (execution.exit_code === 1 &&
+            report.failed === 0 &&
+            !report.warnings.some((warning) => warning.is_error))
+            throw new TypeError("Wakaru exited 1 without a reported partial recovery reason");
+        validateModuleSet(report, provenance, context);
+        return {
+            report,
+            provenance,
+            status: report.failed > 0 ||
+                report.warnings.some((warning) => warning.is_error) ||
+                execution.exit_code === 1
+                ? "partial"
+                : "complete",
+        };
+    }
+    catch (cause) {
+        throw new ProviderAdapterError("wakaru", OPERATION, {
+            cause,
+            diagnostics: {
+                reason: `Unusable Wakaru recovery report: ${recoveryFailureMessage(cause)}`,
+                exit_code: execution.exit_code,
+                signal: execution.signal,
+                stdout: execution.stdout,
+                stderr: execution.stderr,
+            },
+        });
+    }
+};
+const validateModuleSet = (report, provenance, context) => {
+    const { files, snapshotPath, sourceBytes } = context;
+    const registry = new ArtifactPathRegistry();
+    const expected = new Set(["provenance.json"]);
+    const observed = new Set(files.map((file) => file.relativePath));
+    for (const module of report.modules) {
+        const path = normalizeArtifactPath(module.filename);
+        if (path !== module.filename || !/\.(?:js|mjs|cjs)$/u.test(path))
+            throw new TypeError(`Unsupported module path: ${module.filename}`);
+        registry.add(path, "file");
+        if (!observed.has(path))
+            throw new TypeError(`Missing reported module file: ${path}`);
+        expected.add(path);
+        if (observed.has(`${path}.map`))
+            expected.add(`${path}.map`);
+        const entry = provenance.modules[path];
+        if (entry === undefined || entry.input !== snapshotPath)
+            throw new TypeError(`Module provenance does not bind the selected input snapshot: ${path}`);
+        validateRanges([...entry.ranges, ...(entry.context_ranges ?? [])], sourceBytes, path);
+    }
+    if (Object.keys(provenance.modules).length !== report.modules.length)
+        throw new TypeError("Provenance and reported module sets disagree");
+    for (const path of observed)
+        if (!expected.has(path))
+            throw new TypeError(`Unreported recovery artifact: ${path}`);
+};
+const validateRanges = (ranges, bytes, filename) => {
+    for (const [start, end] of ranges) {
+        if (start > end ||
+            end > bytes.length ||
+            !utf8Boundary(bytes, start) ||
+            !utf8Boundary(bytes, end))
+            throw new TypeError(`Invalid half-open UTF-8 byte range [${String(start)},${String(end)}) for ${filename}`);
+    }
+};
+const utf8Boundary = (bytes, offset) => {
+    const value = bytes[offset];
+    return value === undefined || (value & 0xc0) !== 0x80;
+};
+/** Translate extraction byte ranges without claiming rewritten line positions. */
+export const recoveryRanges = (ranges) => ranges.map(([start, end]) => ({ start, end }));
+/** Validate a source map's representation; preserve its unverified mapping bytes. */
+export const validateRecoverySourceMap = (bytes, filename) => {
+    const schema = z.object({
+        version: z.literal(3),
+        sources: z.array(z.string()),
+        names: z.array(z.string()),
+        mappings: z.string(),
+    });
+    try {
+        schema.parse(JSON.parse(bytes.toString("utf8")));
+    }
+    catch (cause) {
+        throw new AnalysisOutputError(OPERATION, `Invalid emitted source map for ${filename}: ${recoveryFailureMessage(cause)}`, { cause });
+    }
+};

package/dist/javascript/sourceMaps/SourceMapCodecProcess.js

@@ -0,0 +1,37 @@
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { WEB_SOURCE_MAP_LIMITS } from "../../domain/webSourceLocation.js";
+import { traceSourceMap } from "./TraceSourceMap.js";
+import { SourceMapFormatFailure } from "./SourceMapFormat.js";
+import { sourceMapCodecInputSchema, sourceMapCodecReplySchema, } from "./SourceMapCodecProtocol.js";
+import { z } from "zod";
+/** Dedicated process entrypoint invoked only for an explicitly selected map. */
+const execute = async () => {
+    try {
+        const path = process.argv[2];
+        if (path === undefined)
+            throw new SourceMapFormatFailure("format", "Codec request path is missing.");
+        const data = await readStableArtifact(path, WEB_SOURCE_MAP_LIMITS.outputBytes);
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(data.bytes);
+        const value = JSON.parse(text);
+        const input = sourceMapCodecInputSchema.parse(value);
+        if (Buffer.byteLength(input.text) > WEB_SOURCE_MAP_LIMITS.mapBytes)
+            throw new SourceMapFormatFailure("limit", "Source map exceeds the 4 MiB codec input budget.");
+        const report = traceSourceMap(input.text, input.url, input.position);
+        const reply = JSON.stringify(sourceMapCodecReplySchema.parse({ state: "success", report }));
+        if (Buffer.byteLength(reply) > WEB_SOURCE_MAP_LIMITS.outputBytes)
+            throw new SourceMapFormatFailure("limit", "Complete source-map point evidence exceeds the 32 MiB output budget; no partial evidence was returned.");
+        return reply;
+    }
+    catch (cause) {
+        if (!(cause instanceof SourceMapFormatFailure ||
+            cause instanceof z.ZodError ||
+            cause instanceof SyntaxError))
+            throw cause;
+        return JSON.stringify({
+            state: "failure",
+            reason: cause instanceof SourceMapFormatFailure ? cause.reason : "format",
+            message: cause.message,
+        });
+    }
+};
+process.stdout.write(await execute());

package/dist/javascript/sourceMaps/SourceMapCodecProtocol.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { webSourceMapReportSchema, webSourcePositionSchema, } from "../../domain/webSourceLocation.js";
+/** Trusted codec process input; captured application code is never evaluated. */
+export const sourceMapCodecInputSchema = z.strictObject({
+    text: z.string(),
+    url: z.string().min(1),
+    position: webSourcePositionSchema,
+});
+/** Codec success or a specific producer/resource constraint. */
+export const sourceMapCodecReplySchema = z.discriminatedUnion("state", [
+    z.strictObject({
+        state: z.literal("success"),
+        report: webSourceMapReportSchema,
+    }),
+    z.strictObject({
+        state: z.literal("failure"),
+        reason: z.enum(["format", "unsupported", "limit"]),
+        message: z.string(),
+    }),
+]);