@world-engines/project-host 0.1.0-alpha.0

package/dist/project-writer-lease.js

@@ -0,0 +1,430 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { open, realpath, rm, stat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { resolve } from "node:path";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { assertSafeExistingProjectPath, assertSafeProjectParent, ensureSafeProjectDirectory, safeProjectPath, } from "./safe-project-path.js";
+const WINDOWS_HELPER_TIMEOUT_MS = 15_000;
+const cleaningRoots = new Set();
+const WINDOWS_LEASE_HELPER = String.raw `
+$ErrorActionPreference = "Stop"
+Add-Type -TypeDefinition @'
+using System;
+using System.ComponentModel;
+using System.IO;
+using System.Runtime.InteropServices;
+using Microsoft.Win32.SafeHandles;
+
+public static class WorldEngineWriterLeaseNative {
+    private const uint GENERIC_READ = 0x80000000u;
+    private const uint GENERIC_WRITE = 0x40000000u;
+    private const uint DELETE = 0x00010000u;
+    private const uint FILE_SHARE_READ = 0x00000001u;
+    private const uint FILE_SHARE_WRITE = 0x00000002u;
+    private const uint CREATE_NEW = 1u;
+    private const uint FILE_ATTRIBUTE_NORMAL = 0x00000080u;
+    private const uint DUPLICATE_SAME_ACCESS = 0x00000002u;
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct BY_HANDLE_FILE_INFORMATION {
+        public uint FileAttributes;
+        public System.Runtime.InteropServices.ComTypes.FILETIME CreationTime;
+        public System.Runtime.InteropServices.ComTypes.FILETIME LastAccessTime;
+        public System.Runtime.InteropServices.ComTypes.FILETIME LastWriteTime;
+        public uint VolumeSerialNumber;
+        public uint FileSizeHigh;
+        public uint FileSizeLow;
+        public uint NumberOfLinks;
+        public uint FileIndexHigh;
+        public uint FileIndexLow;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    private struct FILE_DISPOSITION_INFO {
+        [MarshalAs(UnmanagedType.Bool)] public bool DeleteFile;
+    }
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    private static extern SafeFileHandle CreateFileW(
+        string fileName,
+        uint desiredAccess,
+        uint shareMode,
+        IntPtr securityAttributes,
+        uint creationDisposition,
+        uint flagsAndAttributes,
+        IntPtr templateFile);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool DuplicateHandle(
+        IntPtr sourceProcess,
+        SafeFileHandle sourceHandle,
+        IntPtr targetProcess,
+        out SafeFileHandle targetHandle,
+        uint desiredAccess,
+        bool inheritHandle,
+        uint options);
+
+    [DllImport("kernel32.dll")]
+    private static extern IntPtr GetCurrentProcess();
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool GetFileInformationByHandle(
+        SafeFileHandle handle,
+        out BY_HANDLE_FILE_INFORMATION information);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    private static extern bool SetFileInformationByHandle(
+        SafeFileHandle handle,
+        int informationClass,
+        ref FILE_DISPOSITION_INFO information,
+        uint bufferSize);
+
+    public static SafeFileHandle CreateExclusive(string path) {
+        SafeFileHandle handle = CreateFileW(
+            path,
+            GENERIC_READ | GENERIC_WRITE | DELETE,
+            FILE_SHARE_READ | FILE_SHARE_WRITE,
+            IntPtr.Zero,
+            CREATE_NEW,
+            FILE_ATTRIBUTE_NORMAL,
+            IntPtr.Zero);
+        if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
+        return handle;
+    }
+
+    public static SafeFileHandle Duplicate(SafeFileHandle source) {
+        SafeFileHandle duplicate;
+        IntPtr process = GetCurrentProcess();
+        if (!DuplicateHandle(process, source, process, out duplicate, 0u, false, DUPLICATE_SAME_ACCESS)) {
+            throw new Win32Exception(Marshal.GetLastWin32Error());
+        }
+        return duplicate;
+    }
+
+    public static string Identity(SafeFileHandle handle) {
+        BY_HANDLE_FILE_INFORMATION information;
+        if (!GetFileInformationByHandle(handle, out information)) {
+            throw new Win32Exception(Marshal.GetLastWin32Error());
+        }
+        return String.Format("{0:x8}:{1:x8}{2:x8}", information.VolumeSerialNumber, information.FileIndexHigh, information.FileIndexLow);
+    }
+
+    public static void MarkDelete(SafeFileHandle handle) {
+        FILE_DISPOSITION_INFO information = new FILE_DISPOSITION_INFO { DeleteFile = true };
+        uint size = (uint)Marshal.SizeOf(typeof(FILE_DISPOSITION_INFO));
+        // FileDispositionInfo = 4。删除绑定当前已获取的 file identity，而不是重新解析 path。
+        if (!SetFileInformationByHandle(handle, 4, ref information, size)) {
+            throw new Win32Exception(Marshal.GetLastWin32Error());
+        }
+    }
+}
+'@
+
+function Send-ProtocolLine([string] $kind, [string] $value = "") {
+  if ($value.Length -eq 0) { [Console]::Out.WriteLine($kind) }
+  else { [Console]::Out.WriteLine($kind + [char]9 + $value) }
+  [Console]::Out.Flush()
+}
+
+function Send-ProtocolError([System.Exception] $exception) {
+  while ($null -ne $exception.InnerException) { $exception = $exception.InnerException }
+  $bytes = [Text.Encoding]::UTF8.GetBytes($exception.Message)
+  Send-ProtocolLine "ERROR" ([Convert]::ToBase64String($bytes))
+}
+
+$mutex = $null
+$ownsMutex = $false
+$primary = $null
+$cleanup = $null
+$stream = $null
+try {
+  $mutex = [Threading.Mutex]::new($false, $env:WORLDENGINE_LEASE_MUTEX)
+  try { $ownsMutex = $mutex.WaitOne(0) }
+  catch [Threading.AbandonedMutexException] { $ownsMutex = $true }
+  if (-not $ownsMutex) {
+    Send-ProtocolLine "BUSY"
+    exit 0
+  }
+
+  try {
+    $primary = [WorldEngineWriterLeaseNative]::CreateExclusive($env:WORLDENGINE_LEASE_PATH)
+    $cleanup = [WorldEngineWriterLeaseNative]::Duplicate($primary)
+    $identity = [WorldEngineWriterLeaseNative]::Identity($primary)
+    $stream = [IO.FileStream]::new($primary, [IO.FileAccess]::ReadWrite)
+    $metadata = [Convert]::FromBase64String($env:WORLDENGINE_LEASE_METADATA)
+    $stream.Write($metadata, 0, $metadata.Length)
+    $stream.Flush($true)
+  } catch {
+    $leaf = $_.Exception
+    while ($null -ne $leaf.InnerException) { $leaf = $leaf.InnerException }
+    if (($leaf -is [ComponentModel.Win32Exception]) -and (($leaf.NativeErrorCode -eq 80) -or ($leaf.NativeErrorCode -eq 183))) {
+      Send-ProtocolLine "BUSY"
+      exit 0
+    }
+    throw
+  } finally {
+    if ($ownsMutex) { $mutex.ReleaseMutex(); $ownsMutex = $false }
+  }
+
+  Send-ProtocolLine "READY" $identity
+  while ($null -ne ($command = [Console]::In.ReadLine())) {
+    if ($command -eq "RELEASE") { break }
+  }
+
+  try { $ownsMutex = $mutex.WaitOne() }
+  catch [Threading.AbandonedMutexException] { $ownsMutex = $true }
+  $stream.Dispose()
+  $stream = $null
+  $primary = $null
+  [WorldEngineWriterLeaseNative]::MarkDelete($cleanup)
+  $cleanup.Dispose()
+  $cleanup = $null
+  if ($ownsMutex) { $mutex.ReleaseMutex(); $ownsMutex = $false }
+  Send-ProtocolLine "RELEASED"
+} catch {
+  Send-ProtocolError $_.Exception
+  exit 1
+} finally {
+  if ($null -ne $stream) { $stream.Dispose() }
+  elseif ($null -ne $primary) { $primary.Dispose() }
+  if ($null -ne $cleanup) { $cleanup.Dispose() }
+  if ($ownsMutex) { $mutex.ReleaseMutex() }
+  if ($null -ne $mutex) { $mutex.Dispose() }
+}
+`;
+function busyError() {
+    return new AuthoringBridgeError("E_PROJECT_BUSY", "另一个 GUI、CLI 或 MCP writer 持有项目 lease");
+}
+function uncertainError(message) {
+    return new AuthoringBridgeError("E_OPERATION_UNCERTAIN", message);
+}
+async function leaseLocation(root) {
+    const canonicalRoot = await realpath(resolve(root));
+    await assertSafeExistingProjectPath(canonicalRoot, canonicalRoot);
+    for (;;) {
+        try {
+            await ensureSafeProjectDirectory(canonicalRoot, ".worldengine/lock");
+            break;
+        }
+        catch (error) {
+            // 两个首次 opener 可能分别创建 .worldengine 与 lock；只在输掉 mkdir
+            // race 后重新从 canonical root 验证整条父路径。
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                await assertSafeExistingProjectPath(canonicalRoot, resolve(canonicalRoot, ".worldengine", "lock"));
+                break;
+            }
+            catch (readbackError) {
+                if (readbackError.code !== "ENOENT")
+                    throw readbackError;
+            }
+        }
+    }
+    const path = await safeProjectPath(canonicalRoot, ".worldengine/lock/writer.lock");
+    await assertSafeProjectParent(canonicalRoot, path);
+    return {
+        canonicalRoot,
+        path,
+        rootKey: process.platform === "win32" ? canonicalRoot.toLocaleLowerCase("en-US") : canonicalRoot,
+    };
+}
+function helperExecutable() {
+    const systemRoot = process.env.SystemRoot ?? process.env.WINDIR;
+    return systemRoot === undefined
+        ? "powershell.exe"
+        : resolve(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+}
+function protocolError(encoded) {
+    if (encoded === undefined || encoded === "")
+        return uncertainError("Windows writer lease helper 返回未知错误");
+    try {
+        return uncertainError(`Windows writer lease helper 失败：${Buffer.from(encoded, "base64").toString("utf8")}`);
+    }
+    catch {
+        return uncertainError("Windows writer lease helper 返回了无效错误信息");
+    }
+}
+async function acquireWindowsLease(path, rootKey, metadata) {
+    const encodedCommand = Buffer.from(WINDOWS_LEASE_HELPER, "utf16le").toString("base64");
+    const mutexDigest = createHash("sha256").update(rootKey).digest("hex");
+    const child = spawn(helperExecutable(), ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodedCommand], {
+        env: {
+            ...process.env,
+            WORLDENGINE_LEASE_PATH: path,
+            WORLDENGINE_LEASE_METADATA: Buffer.from(metadata).toString("base64"),
+            WORLDENGINE_LEASE_MUTEX: `Local\\WorldEngine.ProjectWriter.${mutexDigest}`,
+        },
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    let stderr = "";
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk}`.slice(-4096); });
+    let readySettled = false;
+    let releaseRequested = false;
+    let releaseSettled = false;
+    let terminalError;
+    let resolveReady;
+    let rejectReady;
+    let resolveRelease;
+    let rejectRelease;
+    const ready = new Promise((resolvePromise, rejectPromise) => { resolveReady = resolvePromise; rejectReady = rejectPromise; });
+    const released = new Promise((resolvePromise, rejectPromise) => { resolveRelease = resolvePromise; rejectRelease = rejectPromise; });
+    const fail = (error) => {
+        if (!readySettled) {
+            readySettled = true;
+            rejectReady(error);
+        }
+        if (releaseRequested && !releaseSettled) {
+            releaseSettled = true;
+            rejectRelease(error);
+        }
+    };
+    const timeout = setTimeout(() => {
+        const error = uncertainError("Windows writer lease helper 启动超时");
+        fail(error);
+        child.kill();
+    }, WINDOWS_HELPER_TIMEOUT_MS);
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    lines.on("line", (line) => {
+        const [kind, value] = line.split("\t", 2);
+        if (kind === "READY" && value !== undefined && !readySettled) {
+            clearTimeout(timeout);
+            readySettled = true;
+            resolveReady(value);
+            return;
+        }
+        if (kind === "BUSY" && !readySettled) {
+            clearTimeout(timeout);
+            readySettled = true;
+            rejectReady(busyError());
+            return;
+        }
+        if (kind === "RELEASED" && releaseRequested && !releaseSettled) {
+            releaseSettled = true;
+            resolveRelease();
+            return;
+        }
+        if (kind === "ERROR")
+            fail(protocolError(value));
+    });
+    child.stdin.once("error", (error) => {
+        terminalError = uncertainError(`Windows writer lease helper stdin 失败：${error.message}`);
+        fail(terminalError);
+    });
+    child.once("error", (error) => {
+        terminalError = uncertainError(`无法启动 Windows writer lease helper：${error.message}`);
+        fail(terminalError);
+    });
+    child.once("exit", (code) => {
+        clearTimeout(timeout);
+        if (!readySettled || (releaseRequested && !releaseSettled)) {
+            const detail = stderr.trim() === "" ? `exit=${String(code)}` : stderr.trim();
+            terminalError = uncertainError(`Windows writer lease helper 提前退出：${detail}`);
+            fail(terminalError);
+        }
+        else if (!releaseSettled) {
+            terminalError = uncertainError(`Windows writer lease helper 在 release 前退出：exit=${String(code)}`);
+        }
+    });
+    const fileIdentity = await ready;
+    let releasePromise;
+    return {
+        fileIdentity,
+        release() {
+            if (releasePromise !== undefined)
+                return releasePromise;
+            if (terminalError !== undefined) {
+                releasePromise = Promise.reject(terminalError);
+                return releasePromise;
+            }
+            releaseRequested = true;
+            releasePromise = new Promise((resolvePromise, rejectPromise) => {
+                const releaseTimeout = setTimeout(() => {
+                    child.kill();
+                    rejectPromise(uncertainError("Windows writer lease helper 清理超时"));
+                }, WINDOWS_HELPER_TIMEOUT_MS);
+                released.then(() => { clearTimeout(releaseTimeout); resolvePromise(); }, (error) => { clearTimeout(releaseTimeout); rejectPromise(error); });
+                child.stdin.end("RELEASE\n");
+            });
+            return releasePromise;
+        },
+    };
+}
+async function acquirePortableLease(path, metadata) {
+    let handle;
+    try {
+        handle = await open(path, "wx");
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw busyError();
+        throw error;
+    }
+    try {
+        await handle.writeFile(metadata);
+        await handle.sync();
+        const acquired = await handle.stat();
+        const fileIdentity = `${String(acquired.dev)}:${String(acquired.ino)}`;
+        let releasePromise;
+        return {
+            fileIdentity,
+            release() {
+                if (releasePromise !== undefined)
+                    return releasePromise;
+                releasePromise = (async () => {
+                    await handle.close();
+                    const current = await stat(path);
+                    if (`${String(current.dev)}:${String(current.ino)}` !== fileIdentity) {
+                        throw uncertainError("writer lease cleanup identity 不匹配");
+                    }
+                    await rm(path);
+                })();
+                return releasePromise;
+            },
+        };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+/**
+ * 获取 canonical project root 下的唯一 writer lease。
+ *
+ * 普通 acquire 绝不猜测或删除 stale lock；崩溃恢复必须先由独立的 owner/ledger
+ * 协议验证。Windows helper 持有不共享 DELETE 的 handle，并用同一 file identity
+ * 的 duplicate handle 完成删除，避免 path-based cleanup 误删后来者。
+ */
+export async function acquireProjectWriterLease(root, owner = {}) {
+    const location = await leaseLocation(root);
+    if (cleaningRoots.has(location.rootKey))
+        throw busyError();
+    const leaseId = randomUUID();
+    const metadata = new TextEncoder().encode(`${JSON.stringify({
+        schema_version: 1,
+        lease_id: leaseId,
+        pid: process.pid,
+        acquired_at_ms: Date.now(),
+        owner,
+    })}\n`);
+    await assertSafeProjectParent(location.canonicalRoot, location.path);
+    const native = process.platform === "win32"
+        ? await acquireWindowsLease(location.path, location.rootKey, metadata)
+        : await acquirePortableLease(location.path, metadata);
+    let releasePromise;
+    return Object.freeze({
+        path: location.path,
+        leaseId,
+        fileIdentity: native.fileIdentity,
+        release() {
+            if (releasePromise !== undefined)
+                return releasePromise;
+            cleaningRoots.add(location.rootKey);
+            releasePromise = native.release().finally(() => { cleaningRoots.delete(location.rootKey); });
+            return releasePromise;
+        },
+    });
+}

package/dist/public-error.d.ts

@@ -0,0 +1,7 @@
+/** 对 CLI 和 MCP 公开的错误永远不携带底层异常、路径或认证材料。 */
+export interface PublicError {
+    readonly code: string;
+    readonly details: Readonly<Record<string, never>>;
+}
+export declare function toPublicError(error: unknown, fallback?: string): PublicError;
+export declare function writeCliPublicError(write: (text: string) => void, error: unknown): void;

package/dist/public-error.js

@@ -0,0 +1,61 @@
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { AuthoringModelConnectionError } from "./authoring-model-connection.js";
+const PUBLIC_CODES = new Set([
+    "E_PROJECT_NOT_OPEN",
+    "E_PROJECT_BUSY",
+    "E_PATH_OUTSIDE_PROJECT",
+    "E_STALE_PROJECT_REVISION",
+    "E_SCHEMA_INVALID",
+    "E_VALIDATION_FAILED",
+    "E_REFERENCE_MISSING",
+    "E_OPERATION_ID_CONFLICT",
+    "E_OPERATION_UNCERTAIN",
+    "E_PREVIEW_NOT_RUNNING",
+    "E_PREVIEW_NOT_READY",
+    "E_AUTH_REQUIRED",
+    "E_REMOTE_FORBIDDEN",
+    "E_CONFIRMATION_REQUIRED",
+    "E_ROLLBACK_FAILED",
+    "E_GUI_UNAVAILABLE",
+    "E_GUI_PORT_IN_USE",
+    "E_HANDLER_UNAVAILABLE",
+    "E_CAPABILITY_UNAVAILABLE",
+    "E_REVIEW_PREPARE_REQUIRED",
+    "E_BALANCE_REQUIRED",
+    "E_ACCOUNT_CHANGED",
+    "E_RATE_LIMITED",
+    "E_ACCOUNT_MODEL_PROXY_PORT_IN_USE",
+    "E_ACCOUNT_MODEL_PROXY_UNAVAILABLE",
+]);
+const INTERNAL_AUTH_CODES = new Set([
+    "embedding_credentials_missing",
+    "structured_credentials_missing",
+]);
+export function toPublicError(error, fallback = "E_OPERATION_UNCERTAIN") {
+    if (error instanceof AuthoringModelConnectionError) {
+        if (error.status === 402)
+            return { code: "E_BALANCE_REQUIRED", details: {} };
+        if (error.status === 429)
+            return { code: "E_RATE_LIMITED", details: {} };
+        if (error.status === 409 && error.code === "embedding_credentials_missing")
+            return { code: "E_ACCOUNT_CHANGED", details: {} };
+    }
+    const typedFailure = error instanceof AuthoringBridgeError && typeof error.details?.failure === "string"
+        ? error.details.failure
+        : undefined;
+    const candidate = typedFailure !== undefined && PUBLIC_CODES.has(typedFailure)
+        ? typedFailure
+        : error instanceof AuthoringBridgeError
+            ? error.code
+            : error instanceof Error && "code" in error && typeof error.code === "string"
+                ? error.code
+                : fallback;
+    return {
+        code: INTERNAL_AUTH_CODES.has(candidate) ? "E_AUTH_REQUIRED" : PUBLIC_CODES.has(candidate) ? candidate : fallback,
+        details: {},
+    };
+}
+export function writeCliPublicError(write, error) {
+    const publicError = toPublicError(error);
+    write(`${publicError.code}: 请求失败\n`);
+}

package/dist/retrieval-benchmark.d.ts

@@ -0,0 +1,46 @@
+import type { DocumentEvidenceBundle, DocumentEvidenceRequest } from "./document-query.js";
+export interface DocumentRetrievalBenchmarkEdge {
+    readonly src: string;
+    readonly dst: string;
+    readonly kind: string;
+    readonly qualifiers?: Readonly<Record<string, unknown>>;
+}
+export interface DocumentRetrievalBenchmarkCase {
+    readonly id: string;
+    readonly request: DocumentEvidenceRequest;
+    readonly evidenceAtK: Readonly<{
+        k: number;
+        expectedEvidenceIds: readonly string[];
+    }>;
+    readonly expectedPaths?: readonly Readonly<{
+        nodeIds: readonly string[];
+        edges: readonly DocumentRetrievalBenchmarkEdge[];
+    }>[];
+    readonly expectedRefutations?: readonly DocumentRetrievalBenchmarkEdge[];
+    readonly expectIrrelevantRejection?: boolean;
+}
+export interface DocumentRetrievalBenchmarkCount {
+    readonly passed: number;
+    readonly total: number;
+}
+export interface DocumentRetrievalBenchmarkResult {
+    readonly cases: readonly Readonly<{
+        id: string;
+        evidenceHits: number;
+        evidenceTotal: number;
+        candidateIds: readonly string[];
+        observedEvidenceIds: readonly string[];
+        graphPathCount: number;
+        closedPathHits: number;
+        closedPathTotal: number;
+        refutationHits: number;
+        refutationTotal: number;
+        irrelevantRejected: boolean | null;
+    }>[];
+    readonly evidenceAtK: DocumentRetrievalBenchmarkCount;
+    readonly pathClosure: DocumentRetrievalBenchmarkCount;
+    readonly refutation: DocumentRetrievalBenchmarkCount;
+    readonly irrelevantRejection: DocumentRetrievalBenchmarkCount;
+}
+/** 只计 ground truth 命中；不根据答案文本、模型判断或关键词启发式补分。 */
+export declare function runDocumentRetrievalBenchmark(cases: readonly DocumentRetrievalBenchmarkCase[], retrieve: (request: DocumentEvidenceRequest) => Promise<DocumentEvidenceBundle>): Promise<DocumentRetrievalBenchmarkResult>;

package/dist/retrieval-benchmark.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+function pathOrientation(actual, expected) {
+    if (actual.length !== expected.length)
+        return null;
+    if (actual.every((id, index) => id === expected[index]))
+        return "forward";
+    if (actual.every((id, index) => id === expected[expected.length - index - 1]))
+        return "reverse";
+    return null;
+}
+/** 只计 ground truth 命中；不根据答案文本、模型判断或关键词启发式补分。 */
+export async function runDocumentRetrievalBenchmark(cases, retrieve) {
+    const results = [];
+    for (const fixture of cases) {
+        const bundle = await retrieve(fixture.request);
+        const evidenceIdentityCounts = new Map();
+        for (const item of bundle.evidence)
+            evidenceIdentityCounts.set(item.evidenceId, (evidenceIdentityCounts.get(item.evidenceId) ?? 0) + 1);
+        const validEvidenceIds = new Set(bundle.evidence.filter((item) => item.evidenceId.length > 0 && item.documentId.length > 0
+            && item.startOffset >= 0 && item.endOffset > item.startOffset && item.text.length > 0
+            && item.endOffset - item.startOffset === item.text.length && evidenceIdentityCounts.get(item.evidenceId) === 1
+            && createHash("sha256").update(item.text, "utf8").digest("hex") === item.contentSha256).map((item) => item.evidenceId));
+        const observedEvidence = new Set(bundle.evidence.slice(0, fixture.evidenceAtK.k)
+            .filter((item) => validEvidenceIds.has(item.evidenceId)).map((item) => item.evidenceId));
+        const evidenceClosed = (ids) => ids !== undefined && ids.length > 0
+            && ids.every((id) => validEvidenceIds.has(id));
+        const evidenceHits = fixture.evidenceAtK.expectedEvidenceIds.filter((id) => observedEvidence.has(id)).length;
+        const expectedPaths = fixture.expectedPaths ?? [];
+        const closedPathHits = expectedPaths.filter((expected) => bundle.graphPaths.some((path) => {
+            const orientation = pathOrientation(path.nodeIds, expected.nodeIds);
+            return orientation !== null && path.edges.length === expected.edges.length
+                && path.edges.every((edge, index) => {
+                    const physical = orientation === "forward" ? expected.edges[index] : expected.edges[expected.edges.length - index - 1];
+                    return physical !== undefined && edge.src === physical.src && edge.dst === physical.dst && edge.kind === physical.kind
+                        && isDeepStrictEqual(edge.qualifiers, physical.qualifiers) && evidenceClosed(edge.evidenceIds);
+                });
+        })).length;
+        const expectedRefutations = fixture.expectedRefutations ?? [];
+        const refutationHits = expectedRefutations.filter((expected) => bundle.graphPaths.some((path) => path.edges.some((edge) => edge.src === expected.src && edge.dst === expected.dst && edge.kind === expected.kind
+            && isDeepStrictEqual(edge.qualifiers, expected.qualifiers) && evidenceClosed(edge.evidenceIds)))).length;
+        const irrelevantRejected = fixture.expectIrrelevantRejection === true
+            ? bundle.evidence.length === 0 && bundle.graphPaths.length === 0
+            : null;
+        results.push(Object.freeze({ id: fixture.id, evidenceHits, evidenceTotal: fixture.evidenceAtK.expectedEvidenceIds.length,
+            candidateIds: Object.freeze([...new Set(bundle.candidates.map((candidate) => candidate.id))]),
+            observedEvidenceIds: Object.freeze(bundle.evidence.map((item) => item.evidenceId)), graphPathCount: bundle.graphPaths.length,
+            closedPathHits, closedPathTotal: expectedPaths.length, refutationHits, refutationTotal: expectedRefutations.length, irrelevantRejected }));
+    }
+    const count = (passed, total) => Object.freeze({ passed, total });
+    return Object.freeze({
+        cases: Object.freeze(results),
+        evidenceAtK: count(results.reduce((sum, result) => sum + result.evidenceHits, 0), results.reduce((sum, result) => sum + result.evidenceTotal, 0)),
+        pathClosure: count(results.reduce((sum, result) => sum + result.closedPathHits, 0), results.reduce((sum, result) => sum + result.closedPathTotal, 0)),
+        refutation: count(results.reduce((sum, result) => sum + result.refutationHits, 0), results.reduce((sum, result) => sum + result.refutationTotal, 0)),
+        irrelevantRejection: count(results.filter((result) => result.irrelevantRejected === true).length, results.filter((result) => result.irrelevantRejected !== null).length),
+    });
+}

package/dist/safe-project-path.d.ts

@@ -0,0 +1,8 @@
+/** 逐段验证已存在路径，随后 realpath 回读确认仍位于 canonical project root。 */
+export declare function assertSafeExistingProjectPath(root: string, candidate: string): Promise<string>;
+/** 解析一个控制路径；所有已存在父段均须是普通目录，最终文件可尚未创建。 */
+export declare function safeProjectPath(root: string, projectRelativePath: string): Promise<string>;
+/** 创建控制目录时逐段拒绝 reparse，并在每一次创建后 realpath 回读。 */
+export declare function ensureSafeProjectDirectory(root: string, projectRelativePath: string): Promise<string>;
+/** rename 前必须重新验证目标父目录，抵御检查与替换之间的链接交换。 */
+export declare function assertSafeProjectParent(root: string, path: string): Promise<void>;