@citeark/agent 0.3.20

package/scripts/deterministic-asset-preparation.py

@@ -0,0 +1,438 @@
+#!/usr/bin/env python3
+"""Prepare mechanically downloadable assets before asking a semantic Agent."""
+
+from __future__ import annotations
+
+import datetime
+import fnmatch
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import shutil
+import subprocess
+import sys
+import tarfile
+from urllib.parse import urlparse
+import zipfile
+
+
+FALLBACK_TO_AGENT = 86
+JOB_ROOT = Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+PLAN_PATH = JOB_ROOT / "input" / "asset-preparation-plan.json"
+MANIFEST_PATH = JOB_ROOT / "output" / "asset-preparation-manifest.json"
+LOG_ROOT = JOB_ROOT / "output" / "logs" / "asset-preparation" / "deterministic"
+
+
+def job_path(value: str) -> Path:
+    target = Path(value)
+    if target.is_absolute() and target.parts[:2] == ("/", "job"):
+        target = JOB_ROOT.joinpath(*target.parts[2:])
+    elif not target.is_absolute():
+        target = JOB_ROOT / target
+    resolved = target.resolve(strict=False)
+    if resolved != JOB_ROOT and JOB_ROOT not in resolved.parents:
+        raise ValueError(f"path escapes /job: {value}")
+    return resolved
+
+
+def digest_file(target: Path) -> str:
+    digest = hashlib.sha256()
+    with target.open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return "sha256:" + digest.hexdigest()
+
+
+def write_json(target: Path, value: object) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    temporary = target.with_suffix(target.suffix + ".tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(target)
+
+
+def evidence_path(target: Path) -> str:
+    return target.relative_to(JOB_ROOT / "output").as_posix()
+
+
+def safe_member(value: str) -> str | None:
+    normalized = value.replace("\\", "/").lstrip("./")
+    candidate = PurePosixPath(normalized)
+    if not normalized or candidate.is_absolute() or ".." in candidate.parts:
+        return None
+    return candidate.as_posix()
+
+
+def selected_relative(member: str, patterns: list[str], common_prefix: str | None) -> str | None:
+    candidates = [member]
+    if common_prefix and member.startswith(common_prefix + "/"):
+        candidates.insert(0, member[len(common_prefix) + 1 :])
+    for candidate in candidates:
+        if not patterns or any(fnmatch.fnmatchcase(candidate, pattern) for pattern in patterns):
+            return candidate
+    return None
+
+
+def extract_archive(
+    archive: Path,
+    destination: Path,
+    required: list[str],
+    excluded: list[str],
+    maximum_bytes: int,
+) -> list[str]:
+    destination.mkdir(parents=True, exist_ok=True)
+    members: list[tuple[str, object]] = []
+    archive_type = ""
+    if tarfile.is_tarfile(archive):
+        archive_type = "tar"
+        with tarfile.open(archive, "r:*") as handle:
+            members = [(safe_member(member.name), member) for member in handle.getmembers() if member.isfile()]
+            names = [name for name, _ in members if name]
+            prefix = common_prefix(names)
+            selected = [
+                member for name, member in members
+                if name
+                and selected_relative(name, required, prefix)
+                and not any(fnmatch.fnmatchcase(selected_relative(name, required, prefix), pattern) for pattern in excluded)
+            ]
+            if sum(member.size for member in selected) > maximum_bytes:
+                raise ValueError("tar archive exceeds the approved expanded-size budget")
+            written = []
+            for name, member in members:
+                if not name:
+                    continue
+                relative = selected_relative(name, required, prefix)
+                if not relative or any(fnmatch.fnmatchcase(relative, pattern) for pattern in excluded):
+                    continue
+                target = destination.joinpath(*PurePosixPath(relative).parts)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                source = handle.extractfile(member)
+                if source is None:
+                    continue
+                with source, target.open("wb") as output:
+                    shutil.copyfileobj(source, output)
+                written.append(relative)
+    elif zipfile.is_zipfile(archive):
+        archive_type = "zip"
+        with zipfile.ZipFile(archive) as handle:
+            names = [safe_member(item.filename) for item in handle.infolist() if not item.is_dir()]
+            names = [name for name in names if name]
+            prefix = common_prefix(names)
+            selected = [
+                item for item in handle.infolist()
+                if not item.is_dir()
+                and safe_member(item.filename)
+                and selected_relative(safe_member(item.filename), required, prefix)
+                and not any(
+                    fnmatch.fnmatchcase(
+                        selected_relative(safe_member(item.filename), required, prefix),
+                        pattern,
+                    )
+                    for pattern in excluded
+                )
+            ]
+            if sum(item.file_size for item in selected) > maximum_bytes:
+                raise ValueError("zip archive exceeds the approved expanded-size budget")
+            written = []
+            for item in handle.infolist():
+                name = safe_member(item.filename)
+                if item.is_dir() or not name:
+                    continue
+                relative = selected_relative(name, required, prefix)
+                if not relative or any(fnmatch.fnmatchcase(relative, pattern) for pattern in excluded):
+                    continue
+                target = destination.joinpath(*PurePosixPath(relative).parts)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                with handle.open(item) as source, target.open("wb") as output:
+                    shutil.copyfileobj(source, output)
+                written.append(relative)
+    else:
+        return []
+    return written
+
+
+def common_prefix(names: list[str]) -> str | None:
+    first = {PurePosixPath(name).parts[0] for name in names if len(PurePosixPath(name).parts) > 1}
+    return next(iter(first)) if len(first) == 1 else None
+
+
+def reset_directory(target: Path) -> None:
+    if target.exists():
+        shutil.rmtree(target)
+    target.mkdir(parents=True, exist_ok=True)
+
+
+def publish_content(source: Path, destination: Path) -> None:
+    reset_directory(destination)
+    for item in source.rglob("*"):
+        relative = item.relative_to(source)
+        target = destination / relative
+        if item.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+        elif item.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(item, target)
+
+
+def curl_download(url: str, destination: Path, log: Path, maximum_bytes: int) -> tuple[int, str]:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    before = destination.stat().st_size if destination.exists() else 0
+    command = [
+        "curl", "--location", "--fail", "--retry", "5", "--retry-all-errors",
+        "--connect-timeout", "30", "--max-time", "0", "--continue-at", "-",
+        "--max-filesize", str(maximum_bytes),
+        "--output", str(destination), url,
+    ]
+    result = subprocess.run(command, capture_output=True, text=True)
+    log.parent.mkdir(parents=True, exist_ok=True)
+    log.write_text(
+        json.dumps({
+            "url": url,
+            "exitCode": result.returncode,
+            "stderr": result.stderr[-8000:],
+            "resumedFromBytes": before,
+            "finishedAt": now(),
+        }, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    if result.returncode != 0 or not destination.is_file():
+        raise RuntimeError(f"curl failed for {url}: exit {result.returncode}")
+    if destination.stat().st_size > maximum_bytes:
+        raise ValueError(f"download exceeds the approved {maximum_bytes}-byte budget")
+    return destination.stat().st_size, digest_file(destination)
+
+
+def huggingface_identity(url: str) -> tuple[str, str] | None:
+    parsed = urlparse(url)
+    if parsed.hostname not in {"huggingface.co", "www.huggingface.co"}:
+        return None
+    parts = [part for part in parsed.path.split("/") if part]
+    if parts[:1] == ["datasets"] and len(parts) >= 3:
+        return "datasets", "/".join(parts[1:3])
+    if len(parts) >= 2:
+        return "models", "/".join(parts[:2])
+    return None
+
+
+def prepare_asset(asset: dict) -> dict:
+    action = asset["decision"]["action"]
+    if action in {"stream", "inspect", "blocked"}:
+        raise NotImplementedError(f"deterministic fast path does not handle {action}")
+    locators = asset.get("sourceLocators", [])
+    if not locators:
+        raise NotImplementedError("asset has no public locator")
+    local_root = job_path(asset["localPath"])
+    local_root.mkdir(parents=True, exist_ok=True)
+    asset_log = LOG_ROOT / asset["id"]
+    asset_log.mkdir(parents=True, exist_ok=True)
+    attempted: list[dict] = []
+    selected = None
+    downloaded = 0
+    source_digest = None
+    commands: list[str] = []
+    if action == "metadata":
+        for source in locators:
+            url = source["url"]
+            result = subprocess.run(
+                ["curl", "--head", "--location", "--fail", "--retry", "3", "--retry-all-errors", "--connect-timeout", "30", url],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                attempted.append({"url": url, "status": "succeeded", "finishedAt": now()})
+                selected = source
+                commands.append(f"curl --head --location {url}")
+                break
+            attempted.append({"url": url, "status": "failed", "reason": result.stderr[-500:], "finishedAt": now()})
+        if selected is None:
+            raise RuntimeError("all approved metadata sources failed")
+        audit = asset_log / "metadata.json"
+        write_json(audit, {"assetId": asset["id"], "attemptedSources": attempted, "finishedAt": now()})
+        return {
+            "assetId": asset["id"],
+            "identity": asset["identity"],
+            **({"revision": asset["revision"]} if asset.get("revision") else {}),
+            "sourceLocator": selected["url"],
+            "localPath": asset["localPath"],
+            "status": "metadata_verified",
+            "verification": {
+                "status": "passed",
+                "commands": commands,
+                "evidence": [evidence_path(audit)],
+            },
+        }
+    for source in locators:
+        url = source["url"]
+        try:
+            attempt_downloaded = 0
+            attempt_commands: list[str] = []
+            maximum_download = asset["maximumDownloadBytes"]
+            attempt_key = hashlib.sha256(url.encode()).hexdigest()[:16]
+            attempt_root = JOB_ROOT / "runtime-cache" / "deterministic-assets" / asset["id"] / attempt_key
+            content_root = attempt_root / "content"
+            hf = huggingface_identity(url)
+            required = asset.get("requiredPaths", [])
+            if hf:
+                if not required or any(any(token in pattern for token in "*?[") for pattern in required):
+                    raise NotImplementedError("Hugging Face fast path requires explicit file paths")
+                namespace, repository = hf
+                revision = asset.get("revision") or "main"
+                file_digests = []
+                for index, relative in enumerate(required, start=1):
+                    file_url = f"https://huggingface.co/{'datasets/' if namespace == 'datasets' else ''}{repository}/resolve/{revision}/{relative}?download=true"
+                    target = content_root.joinpath(*PurePosixPath(relative).parts)
+                    size, file_digest = curl_download(
+                        file_url,
+                        target,
+                        asset_log / f"transfer-{index}.json",
+                        maximum_download,
+                    )
+                    attempt_downloaded += size
+                    if attempt_downloaded > maximum_download:
+                        raise ValueError("selected Hugging Face files exceed the approved download budget")
+                    file_digests.append(f"{relative}\0{file_digest}")
+                    attempt_commands.append(f"curl --continue-at - {file_url}")
+                source_digest = "sha256:" + hashlib.sha256("\n".join(file_digests).encode()).hexdigest()
+            else:
+                filename = Path(urlparse(url).path).name or "download.bin"
+                archive = attempt_root / "download" / filename
+                attempt_downloaded, source_digest = curl_download(
+                    url,
+                    archive,
+                    asset_log / "transfer.json",
+                    maximum_download,
+                )
+                attempt_commands.append(f"curl --continue-at - {url}")
+                expected = source.get("expectedDigest")
+                if expected and source_digest != expected:
+                    raise ValueError(f"source digest mismatch: expected {expected}, got {source_digest}")
+                reset_directory(content_root)
+                written = extract_archive(
+                    archive,
+                    content_root,
+                    asset.get("requiredPaths", []),
+                    asset.get("excludedPaths", []),
+                    asset["maximumExpandedBytes"],
+                )
+                if not written:
+                    target_name = asset.get("requiredPaths", [filename])[0]
+                    if any(token in target_name for token in "*?["):
+                        target_name = filename
+                    target = content_root.joinpath(*PurePosixPath(target_name).parts)
+                    target.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copyfile(archive, target)
+            expected = source.get("expectedDigest")
+            if expected and source_digest != expected:
+                raise ValueError(f"source digest mismatch: expected {expected}, got {source_digest}")
+            expanded = sum(item.stat().st_size for item in content_root.rglob("*") if item.is_file())
+            if expanded > asset["maximumExpandedBytes"]:
+                raise ValueError("prepared content exceeds the approved expanded-size budget")
+            publish_content(content_root, local_root)
+            downloaded = attempt_downloaded
+            commands = attempt_commands
+            attempted.append({"url": url, "status": "succeeded", "finishedAt": now()})
+            selected = source
+            break
+        except NotImplementedError:
+            raise
+        except Exception as error:
+            attempted.append({
+                "url": url,
+                "status": "failed",
+                "reason": str(error)[:500],
+                "finishedAt": now(),
+            })
+    if selected is None:
+        raise RuntimeError("all approved sources failed")
+    audit = asset_log / "acquisition.json"
+    write_json(audit, {
+        "assetId": asset["id"],
+        "sourceLocator": selected["url"],
+        "sourceClass": selected.get("sourceClass"),
+        "sourceDigest": source_digest,
+        "downloadBytes": downloaded,
+        "attemptedSources": attempted,
+        "finishedAt": now(),
+    })
+    return {
+        "assetId": asset["id"],
+        "identity": asset["identity"],
+        **({"revision": asset["revision"]} if asset.get("revision") else {}),
+        "sourceLocator": selected["url"],
+        "localPath": asset["localPath"],
+        "status": "prepared" if action == "prepare" else "metadata_verified",
+        "verification": {
+            "status": "passed",
+            "commands": commands + [f"sha256sum prepared files for {asset['id']}"],
+            "evidence": [evidence_path(audit)],
+        },
+        **({
+            "acquisition": {
+                "downloadBytes": downloaded,
+                "sourceDigest": source_digest,
+                "attemptedSources": attempted,
+                "commands": commands,
+                "evidence": [evidence_path(audit)],
+            },
+        } if action == "prepare" else {}),
+    }
+
+
+def run_check(check: dict) -> dict:
+    command = check.get("command")
+    if not command:
+        raise NotImplementedError(f"check {check['id']} needs semantic planning")
+    log = LOG_ROOT / "checks" / f"{check['id']}.log"
+    log.parent.mkdir(parents=True, exist_ok=True)
+    with log.open("w", encoding="utf-8") as output:
+        result = subprocess.run(
+            ["/bin/bash", "-lc", command],
+            cwd=JOB_ROOT / "workspace" / "repository",
+            stdout=output,
+            stderr=subprocess.STDOUT,
+            text=True,
+        )
+    if result.returncode != 0:
+        raise RuntimeError(f"check {check['id']} failed with exit {result.returncode}")
+    return {
+        "checkId": check["id"],
+        "kind": check["kind"],
+        "status": "passed",
+        "commands": [command],
+        "evidence": [evidence_path(log)],
+    }
+
+
+def now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def main() -> int:
+    plan = json.loads(PLAN_PATH.read_text(encoding="utf-8"))
+    LOG_ROOT.mkdir(parents=True, exist_ok=True)
+    try:
+        records = [prepare_asset(asset) for asset in plan.get("assets", [])]
+        checks = [run_check(check) for check in plan.get("checks", [])]
+    except (NotImplementedError, RuntimeError, ValueError, OSError) as error:
+        write_json(LOG_ROOT / "fallback.json", {
+            "status": "agent_required",
+            "reason": str(error)[:1000],
+            "recordedAt": now(),
+        })
+        print(f"deterministic asset preparation handed off to Agent: {error}", file=sys.stderr)
+        return FALLBACK_TO_AGENT
+    manifest = {
+        "schemaVersion": "0.1",
+        "kind": "citeark.asset-preparation-manifest",
+        "planDigest": plan["planDigest"],
+        "preparationMode": "deterministic",
+        "assets": records,
+        "checks": checks,
+    }
+    write_json(MANIFEST_PATH, manifest)
+    print(json.dumps({"status": "prepared", "mode": "deterministic"}))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/package-cap.mjs

@@ -0,0 +1,23 @@
+import { build } from 'esbuild';
+import { mkdir, mkdtemp, writeFile, rm, copyFile } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+const root = fileURLToPath(new URL('..', import.meta.url));
+const out = path.resolve(process.argv[2] ?? path.join(root, 'dist'));
+const temporary = await mkdtemp(path.join(os.tmpdir(), 'citeark-cap-package-'));
+try {
+  const directory = path.join(temporary, 'package');
+  await mkdir(directory);
+  await mkdir(out, { recursive: true });
+  await build({ entryPoints: [path.join(root, 'src/public/cap.mjs')], outfile: path.join(directory, 'index.mjs'),
+    bundle: true, platform: 'node', format: 'esm', target: 'node22' });
+  await copyFile(path.join(root, 'src/public/cap.d.mts'), path.join(directory, 'index.d.mts'));
+  await copyFile(path.join(root, 'LICENSE'), path.join(directory, 'LICENSE'));
+  await writeFile(path.join(directory, 'package.json'), JSON.stringify({ name: 'citeark-cap', version: '2.0.0-alpha.2',
+    type: 'module', license: 'Apache-2.0', engines: { node: '>=22' },
+    exports: { '.': { types: './index.d.mts', default: './index.mjs' }, './package.json': './package.json' } }, null, 2)+'\n');
+  execFileSync('tar', ['-czf', path.join(out, 'cap.tgz'), '-C', temporary, 'package']);
+} finally { await rm(temporary, { recursive: true, force: true }); }
+console.log(`CAP protocol package: ${path.join(out, 'cap.tgz')}`);

package/scripts/package-local-agent.mjs

@@ -0,0 +1,23 @@
+import { execFile } from 'node:child_process';
+import { copyFile, mkdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outputDirectory = path.resolve(process.argv[2] ?? path.join(packageRoot, 'dist'));
+const manifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+const entries = ['package.json', 'package-lock.json', 'README.md', 'LICENSE', ...manifest.files];
+for (const entry of entries) await stat(path.join(packageRoot, entry));
+await mkdir(outputDirectory, { recursive: true });
+
+const run = promisify(execFile);
+// Keep the extracted-source archive for existing manual installs.
+await run('tar', ['--exclude=*/node_modules', '-czf', path.join(outputDirectory, 'citeark-agent.tgz'), '-C', packageRoot, ...entries]);
+// Website downloads and registry publishing use the same npm-generated bytes.
+if (!process.env.npm_execpath) throw Error('请通过 npm run package:local 构建安装包。');
+const { stdout } = await run(process.execPath, [process.env.npm_execpath, 'pack', '--json', '--ignore-scripts',
+  '--pack-destination', outputDirectory], { cwd: packageRoot });
+const [packed] = JSON.parse(stdout);
+await copyFile(path.join(outputDirectory, packed.filename), path.join(outputDirectory, 'cli.tgz'));
+console.log(`Agent ${manifest.version}: ${packed.filename} (${packed.entryCount} files), cli.tgz, citeark-agent.tgz`);

package/scripts/preview-arkgraph.mjs

@@ -0,0 +1,25 @@
+import {attachLocalSourcePreviews} from '../src/graph/source-preview.mjs';
+import {readFile,writeFile,mkdir,copyFile,cp,mkdtemp,rm} from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {createHash} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {readCapArchive} from '../src/cap/v2/read.mjs';
+import {createArkGraph} from '../src/graph/query.mjs';
+import {buildArkGraphPresentation} from '../src/graph/presentation.mjs';
+const [archive,output,paper]=process.argv.slice(2);
+if(!archive||!output)throw Error('Usage: node scripts/preview-arkgraph.mjs <signed.cap> <output-directory> [paper.pdf]');
+const root=path.resolve(path.dirname(fileURLToPath(import.meta.url)),'..'),dir=path.resolve(output),temp=await mkdtemp(path.join(os.tmpdir(),'arkgraph-preview-'));
+try{
+ const cap=await readCapArchive(path.resolve(archive),path.join(temp,'read'));
+ const view=buildArkGraphPresentation(createArkGraph([cap]));
+ await mkdir(dir,{recursive:true});
+ await cp(path.join(root,'dist/arkgraph'),dir,{recursive:true});
+ if(paper)await attachLocalSourcePreviews(view,path.resolve(paper),dir);
+ await writeFile(path.join(dir,'fold-data.json'),JSON.stringify(view));
+ const json=JSON.stringify(view).replaceAll('<','\\u003c');
+ const assetVersion=async name=>createHash('sha256').update(await readFile(path.join(dir,name))).digest('hex').slice(0,16);
+ const jsVersion=await assetVersion('viewer.js'),cssVersion=await assetVersion('viewer.css');
+ await writeFile(path.join(dir,'index.html'),`<!doctype html><html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ArkGraph</title><link rel="stylesheet" href="viewer.css?v=${cssVersion}"></head><body><div id="root"></div><script id="graphData" type="application/json">${json}</script><script src="viewer.js?v=${jsVersion}"></script></body></html>`);
+ console.log(JSON.stringify({output:dir,artifactDigest:view.digest,nodes:view.nodes.length,relations:view.edges.length}));
+}finally{await rm(temp,{recursive:true,force:true});}

package/scripts/replay-research-compiler-candidate.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+
+import {
+  attachCompilerAdvisories,
+  reviewCompilerCandidate,
+} from "../src/research/compiler.mjs";
+import {
+  compilerReconstructionRetryIssues,
+  normalizeCompilerResearchDraft,
+} from "../src/research/structure.mjs";
+import { CiteArkError, pathExists, readJson, writeJson } from "../src/util.mjs";
+
+const options = parseOptions(process.argv.slice(2));
+const runDirectory = path.resolve(options.run);
+const outputPath = path.resolve(
+  options.output ?? path.join(runDirectory, "output", "research.replayed.normalized.json"),
+);
+const reportPath = path.resolve(
+  options.report ?? path.join(runDirectory, "execution", "deterministic-replay.json"),
+);
+
+const [draft, task, runState, repositoryIdentityInput, datasetRegistryInput, beforeSnapshot] = await Promise.all([
+  readJson(path.join(runDirectory, "output", "research.json")),
+  readJson(path.join(runDirectory, "input", "compile-task.json")),
+  readOptionalJson(path.join(runDirectory, "run.json")),
+  readOptionalJson(path.join(runDirectory, "input", "repository-identity.json")),
+  readOptionalJson(path.join(runDirectory, "input", "dataset-source-registry.json")),
+  readJson(path.join(runDirectory, "execution", "workspace-before.json")),
+]);
+const fixedPaperSource = (Array.isArray(draft?.sources) ? draft.sources : [])
+  .find((source) => source?.kind === "paper");
+const repositoryIdentity = repositoryIdentityInput
+  ?? runState?.repository?.identity
+  ?? { available: false };
+const datasetRegistry = datasetRegistryInput ?? { datasets: [] };
+const repositorySnapshot = path.join(runDirectory, "snapshot", "repository");
+const replayFallbacks = [
+  ...(!repositoryIdentityInput && runState?.repository?.identity
+    ? ["repository identity recovered from run.json"]
+    : []),
+  ...(!datasetRegistryInput
+    ? ["dataset source registry absent; asset-source findings may be conservative"]
+    : []),
+  ...(!(await pathExists(repositorySnapshot))
+    ? ["repository snapshot absent; repository-source findings may be conservative"]
+    : []),
+];
+const context = {
+  taskName: task.name,
+  computeContext: task.computeContext,
+  paperTitle: task.paper?.title ?? draft?.title,
+  paperUri: task.paper?.sourceUrl ?? task.paper?.resolvedUrl ?? fixedPaperSource?.uri,
+  paperDigest: task.paper?.digest ?? fixedPaperSource?.digest,
+  paperPath: containerInputPath(runDirectory, task.paper?.path),
+  repositoryRoot: repositorySnapshot,
+  repositoryIdentity,
+  repositoryFiles: (beforeSnapshot?.entries ?? [])
+    .filter((entry) => entry?.type === "file" && typeof entry.path === "string")
+    .map((entry) => entry.path),
+  licensePolicy: task.licensePolicy,
+  continuation: task.continuation ?? null,
+};
+const normalized = normalizeCompilerResearchDraft(draft, context);
+const compilerIssues = compilerReconstructionRetryIssues(normalized.research, context);
+const review = await reviewCompilerCandidate({
+  candidate: normalized.research,
+  draftContext: context,
+  reconstructionIssues: compilerIssues,
+  datasetRegistry,
+});
+const normalizationWarnings = attachCompilerAdvisories(
+  normalized.research,
+  normalized.warnings,
+  review.advisoryIssues,
+);
+const report = {
+  schemaVersion: "0.1",
+  runDirectory,
+  input: path.join(runDirectory, "output", "research.json"),
+  output: review.blockingIssues.length ? null : outputPath,
+  status: review.blockingIssues.length ? "invalid" : "valid_with_advisories",
+  agentPlanned: review.agentPlanned,
+  coverage: review.coverage,
+  replayFallbacks,
+  warnings: normalizationWarnings,
+  compilerIssues,
+  blockingIssues: review.blockingIssues,
+  advisoryIssues: review.advisoryIssues,
+};
+await writeJson(reportPath, report);
+if (review.blockingIssues.length) {
+  throw new CiteArkError(`确定性回放仍有硬边界问题：\n- ${review.blockingIssues.join("\n- ")}`, { exitCode: 2 });
+}
+await writeJson(outputPath, normalized.research);
+console.log("Deterministic replay: valid with advisories");
+console.log(`Research: ${outputPath}`);
+console.log(`Report: ${reportPath}`);
+console.log(`Warnings: ${normalizationWarnings.length}`);
+console.log(`Advisories: ${review.advisoryIssues.length}`);
+
+function containerInputPath(runRoot, value) {
+  if (typeof value !== "string" || !value.startsWith("/job/input/")) {
+    throw new CiteArkError("编译任务没有固定的容器论文路径");
+  }
+  const relative = value.slice("/job/input/".length);
+  if (!relative || relative.split("/").includes("..")) {
+    throw new CiteArkError("编译任务论文路径越界");
+  }
+  return path.join(runRoot, "input", ...relative.split("/"));
+}
+
+async function readOptionalJson(target) {
+  return await pathExists(target) ? readJson(target) : null;
+}
+
+function parseOptions(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (!new Set(["--run", "--output", "--report"]).has(flag)) {
+      throw new CiteArkError(`未知参数：${flag}`);
+    }
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new CiteArkError(`${flag} 缺少值`);
+    result[flag.slice(2)] = value;
+    index += 1;
+  }
+  if (!result.run) {
+    throw new CiteArkError("用法：node scripts/replay-research-compiler-candidate.mjs --run <compiler-run-dir> [--output <research.json>] [--report <replay.json>]");
+  }
+  return result;
+}