knodin 0.8.3 → 0.8.5

package/dist/src/engine/prune.js

@@ -43,6 +43,14 @@ export const PRUNE_DIR_NAMES = new Set([
     "vendor",
     "__pycache__",
 ]);
+/** Frozen input to shared-index compatibility; update with any pruning behavior change. */
+export function prunePolicyDescriptor() {
+    return {
+        version: 1,
+        directories: [...PRUNE_DIR_NAMES].sort((left, right) => left.localeCompare(right)),
+        patterns: [".claude/worktrees"],
+    };
+}
 /** True when a single path segment (one directory name) is a pruned directory. */
 export function isPrunedSegment(segment) {
     return PRUNE_DIR_NAMES.has(segment);

package/dist/src/file-metrics.js

@@ -0,0 +1,153 @@
+import { execFileSync } from "node:child_process";
+const SOURCE_EXTENSION = /\.(?:[cm]?[jt]sx?|py|java|cls|trigger|go|rs|rb|php|cs)$/i;
+const TEST_PATH = /(?:(?:^|\/)(?:__tests__|test|tests|spec|specs)(?:\/|$)|[._](?:test|spec)\.[^/]+$)/i;
+function git(repo, args, input) {
+    try {
+        return execFileSync("git", ["-C", repo, ...args], {
+            encoding: "buffer",
+            input,
+            maxBuffer: 512 * 1024 * 1024,
+            stdio: [input ? "pipe" : "ignore", "pipe", "pipe"],
+        });
+    }
+    catch (error) {
+        const stderr = error.stderr;
+        const message = Buffer.isBuffer(stderr) ? stderr.toString("utf8").trim() : String(stderr ?? "");
+        throw new Error(`knodin query file_metrics: git ${args[0]} failed${message ? `: ${message}` : ""}`);
+    }
+}
+function resolveCommit(repo, ref) {
+    try {
+        return git(repo, ["rev-parse", "--verify", `${ref}^{commit}`])
+            .toString("utf8")
+            .trim();
+    }
+    catch {
+        throw new Error(`knodin query file_metrics: invalid or unreachable Git ref ${ref}`);
+    }
+}
+function tree(repo, commit) {
+    const listing = git(repo, ["ls-tree", "-r", "-z", commit]);
+    const entries = listing
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean)
+        .flatMap((entry) => {
+        const match = /^(\d+) blob ([a-f0-9]+)\t([\s\S]+)$/.exec(entry);
+        if (!match || !SOURCE_EXTENSION.test(match[3]))
+            return [];
+        return [{ path: match[3], hash: match[2] }];
+    });
+    const hashes = [...new Set(entries.map((entry) => entry.hash))];
+    const batch = hashes.length
+        ? git(repo, ["cat-file", "--batch"], Buffer.from(`${hashes.join("\n")}\n`))
+        : Buffer.alloc(0);
+    const contents = new Map();
+    let offset = 0;
+    for (const expected of hashes) {
+        const newline = batch.indexOf(0x0a, offset);
+        if (newline < 0)
+            throw new Error("knodin query file_metrics: truncated git object batch");
+        const header = batch.subarray(offset, newline).toString("utf8");
+        const match = /^([a-f0-9]+) blob (\d+)$/.exec(header);
+        if (!match || match[1] !== expected)
+            throw new Error("knodin query file_metrics: unexpected git object batch response");
+        const size = Number(match[2]);
+        const start = newline + 1;
+        const end = start + size;
+        if (end >= batch.length || batch[end] !== 0x0a)
+            throw new Error("knodin query file_metrics: malformed git object batch response");
+        contents.set(expected, batch.subarray(start, end));
+        offset = end + 1;
+    }
+    return new Map(entries.map((entry) => {
+        const content = contents.get(entry.hash);
+        if (!content)
+            throw new Error("knodin query file_metrics: missing Git object content");
+        return [entry.path, { hash: entry.hash, content }];
+    }));
+}
+function text(buffer) {
+    if (buffer.includes(0))
+        return null;
+    const decoded = buffer.toString("utf8");
+    return Buffer.from(decoded, "utf8").equals(buffer) ? decoded : null;
+}
+export function measureFile(content) {
+    const lines = content.length === 0
+        ? 0
+        : content.split(/\r\n|\n|\r/).length - (/[\r\n]$/.test(content) ? 1 : 0);
+    const imports = (content.match(/^\s*(?:import\b|export\s+[^\n;]*\sfrom\b|(?:const|let|var)\s+[^=\n]+?=\s*require\s*\(|from\s+\S+\s+import\b|import\s+\S+)/gm) ?? []).length;
+    const routes = (content.match(/\b(?:app|router)\s*\.\s*(?:get|post|put|patch|delete|options|head|use)\s*\(|@(?:Get|Post|Put|Patch|Delete|RequestMapping|GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping)\b|@app\.(?:get|post|put|patch|delete|route)\s*\(/g) ?? []).length;
+    const effects = (content.match(/\b(?:fetch|axios\.(?:get|post|put|patch|delete)|console\.(?:log|warn|error)|(?:read|write|append|unlink|mkdir|rm)FileSync|(?:read|write|append|unlink|mkdir|rm)File|process\.env|\.query|\.execute|\.save|\.send|\.publish)\s*[[(]/g) ?? []).length;
+    return { lines, imports, routes, effects };
+}
+function subtract(head, base) {
+    return {
+        lines: head.lines - base.lines,
+        imports: head.imports - base.imports,
+        routes: head.routes - base.routes,
+        effects: head.effects - base.effects,
+    };
+}
+export function collectFileMetrics(repo, options = {}) {
+    const head = resolveCommit(repo, "HEAD");
+    let base;
+    if (options.base) {
+        resolveCommit(repo, options.base);
+        const mergeBase = git(repo, ["merge-base", "HEAD", options.base]).toString("utf8").trim();
+        if (!mergeBase)
+            throw new Error(`knodin query file_metrics: cannot resolve merge-base for ${options.base}`);
+        base = { requested: options.base, mergeBase };
+    }
+    const testScope = options.testScope ?? "all";
+    const headTree = tree(repo, head);
+    const baseTree = base ? tree(repo, base.mergeBase) : undefined;
+    const paths = [...new Set([...headTree.keys(), ...(baseTree?.keys() ?? [])])]
+        .filter((file) => testScope === "all" || (testScope === "test") === TEST_PATH.test(file))
+        .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+    const files = [];
+    for (const file of paths) {
+        const headEntry = headTree.get(file);
+        const baseEntry = baseTree?.get(file);
+        const headText = headEntry ? text(headEntry.content) : null;
+        const baseText = baseEntry ? text(baseEntry.content) : null;
+        // Binary or invalid UTF-8 inputs are explicitly skipped rather than reported as zero.
+        if ((headEntry && headText === null) || (baseEntry && baseText === null))
+            continue;
+        const headMetrics = headText === null ? null : measureFile(headText);
+        const baseMetrics = baseText === null ? null : measureFile(baseText);
+        const status = !headEntry
+            ? "removed"
+            : !baseTree
+                ? "unchanged"
+                : !baseEntry
+                    ? "added"
+                    : headEntry.hash === baseEntry.hash
+                        ? "unchanged"
+                        : "changed";
+        files.push({
+            file,
+            status,
+            head: headMetrics,
+            ...(baseTree
+                ? {
+                    base: baseMetrics,
+                    delta: status === "changed" && headMetrics && baseMetrics
+                        ? subtract(headMetrics, baseMetrics)
+                        : null,
+                }
+                : {}),
+        });
+    }
+    return {
+        schemaVersion: 1,
+        status: "ok",
+        head,
+        ...(base ? { base } : {}),
+        testScope,
+        files,
+        confidentiality: "paths-and-integer-counts-only",
+        policy: "measurements-only",
+    };
+}

package/dist/src/output-telemetry.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { encode } from "gpt-tokenizer/encoding/o200k_base";
 import { compareBytes } from "./compare.js";
 import { resolveDbPath } from "./engine/state-paths.js";
+import { summarizeAdoption } from "./session-telemetry.js";
 export const TELEMETRY_TOKENIZER = "gpt-tokenizer@3.4.0:o200k_base";
 export const countOutputTokens = (value) => encode(value).length;
 export const DEFAULT_TELEMETRY_RETENTION_DAYS = 30;
@@ -182,7 +183,7 @@ function telemetrySummary(records) {
         indexingMs: records.reduce((sum, record) => sum + (record.indexingMs ?? 0), 0),
     };
 }
-export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/telemetry-report.html") {
+export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/telemetry-report.html", sessionEvents = []) {
     const { repo, target: output } = privatePath(repoPath, outputPath, "report");
     const groups = new Map();
     for (const record of records) {
@@ -201,6 +202,7 @@ export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/te
     })
         .join("");
     const summary = telemetrySummary(records);
+    const adoption = summarizeAdoption(sessionEvents);
     const timeSeries = new Map();
     for (const record of records) {
         const day = typeof record.at === "string" ? record.at.slice(0, 10) : "unknown";
@@ -221,12 +223,13 @@ export function writeTelemetryReport(repoPath, records, outputPath = ".knodin/te
         .sort(([left], [right]) => compareBytes(left, right))
         .map(([id, calls]) => `<tr><td>${escapeHtml(id)}</td><td>${calls}</td></tr>`)
         .join("");
-    const html = `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><title>knodin telemetry</title><style>:root{color-scheme:light dark;--line:#d0d7de;--card:#f6f8fa}body{font:14px system-ui;margin:2rem;max-width:76rem}section{background:var(--card);padding:1rem;margin:1rem 0;border-radius:.5rem}table{border-collapse:collapse;width:100%}th,td{padding:.55rem;border-bottom:1px solid var(--line);text-align:left}@media(prefers-color-scheme:dark){:root{--line:#30363d;--card:#161b22}}</style><h1>knodin local telemetry</h1><p>Tokenizer: ${TELEMETRY_TOKENIZER}. Local, opt-in, metadata-only; source, raw output, command text, usernames, and paths are not persisted.</p><section><h2>Summary</h2><p>Total measured tokens avoided: ${summary.measuredTokensAvoided}</p><p>Calls: ${summary.calls}; successes: ${summary.successes}; errors: ${summary.errors}; measured baselines: ${summary.measuredBaselines}</p><p>Latency p50 / p95: ${summary.latencyP50Ms} / ${summary.latencyP95Ms} ms</p><p>Freshness failures: ${summary.freshnessFailures}; compression fidelity samples / p50: ${summary.compressionFidelitySamples} / ${summary.compressionFidelityP50}; indexing time: ${summary.indexingMs} ms; index storage: ${summary.indexStorageBytes} bytes</p></section><section><h2>Operation breakdown</h2><table><thead><tr><th>Operation</th><th>Calls</th><th>Errors</th><th>Measured baselines</th><th>Net tokens saved</th><th>p50 ms</th><th>p95 ms</th></tr></thead><tbody>${rows}</tbody></table></section><section><h2>Time series</h2><table><thead><tr><th>Day</th><th>Calls</th><th>Tokens avoided</th></tr></thead><tbody>${seriesRows}</tbody></table></section><section><h2>Repository breakdown</h2><table><thead><tr><th>Private repository id</th><th>Calls</th></tr></thead><tbody>${repositoryRows}</tbody></table></section><p>Use <code>knodin telemetry export</code> for the machine-readable evidence bundle and <code>knodin telemetry clear</code> to delete persisted records.</p>`;
+    const html = `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><title>knodin telemetry</title><style>:root{color-scheme:light dark;--line:#d0d7de;--card:#f6f8fa}body{font:14px system-ui;margin:2rem;max-width:76rem}section{background:var(--card);padding:1rem;margin:1rem 0;border-radius:.5rem}table{border-collapse:collapse;width:100%}th,td{padding:.55rem;border-bottom:1px solid var(--line);text-align:left}@media(prefers-color-scheme:dark){:root{--line:#30363d;--card:#161b22}}</style><h1>knodin local telemetry</h1><p>Tokenizer: ${TELEMETRY_TOKENIZER}. Local, opt-in, metadata-only; source, raw output, command text, prompts, usernames, and paths are not persisted.</p><section><h2>Summary</h2><p>Total measured tokens avoided: ${summary.measuredTokensAvoided}</p><p>Calls: ${summary.calls}; successes: ${summary.successes}; errors: ${summary.errors}; measured baselines: ${summary.measuredBaselines}</p><p>Latency p50 / p95: ${summary.latencyP50Ms} / ${summary.latencyP95Ms} ms</p><p>Freshness failures: ${summary.freshnessFailures}; compression fidelity samples / p50: ${summary.compressionFidelitySamples} / ${summary.compressionFidelityP50}; indexing time: ${summary.indexingMs} ms; index storage: ${summary.indexStorageBytes} bytes</p></section><section><h2>Adoption evidence</h2><p>Sessions: ${adoption.sessions}; context delivered / degraded: ${adoption.contextDelivered} / ${adoption.contextDegraded}; sessions using knodin: ${adoption.knodinSessions}; observed turns: ${adoption.turns}</p><p>Fallback traversal after knodin: ${adoption.fallbackTraversalAfterKnodin}; edits preceded by knodin evidence in the same turn: ${adoption.evidenceBeforeEdit}</p><p>Corrective round trips: unavailable. Ordinary hook events do not prove why a follow-up occurred.</p></section><section><h2>Operation breakdown</h2><table><thead><tr><th>Operation</th><th>Calls</th><th>Errors</th><th>Measured baselines</th><th>Net tokens saved</th><th>p50 ms</th><th>p95 ms</th></tr></thead><tbody>${rows}</tbody></table></section><section><h2>Time series</h2><table><thead><tr><th>Day</th><th>Calls</th><th>Tokens avoided</th></tr></thead><tbody>${seriesRows}</tbody></table></section><section><h2>Repository breakdown</h2><table><thead><tr><th>Private repository id</th><th>Calls</th></tr></thead><tbody>${repositoryRows}</tbody></table></section><p>Use <code>knodin telemetry export</code> for the machine-readable evidence bundle and <code>knodin telemetry clear</code> to delete persisted records.</p>`;
     atomicPrivateWrite(output, html);
     return {
         outputPath: path.relative(repo, output),
         records: records.length,
         operations: groups.size,
+        sessionEvents: sessionEvents.length,
     };
 }
 function sanitizeTelemetryRecord(record) {
@@ -335,7 +338,7 @@ export function telemetryStatus(repoPath, inputPath = DEFAULT_INPUT, retentionDa
         tokenizer: TELEMETRY_TOKENIZER,
     };
 }
-export function exportTelemetry(repoPath, records, outputPath = ".knodin/telemetry-export.json") {
+export function exportTelemetry(repoPath, records, outputPath = ".knodin/telemetry-export.json", sessionEvents = []) {
     const { repo, target } = privatePath(repoPath, outputPath, "export");
     const bundle = {
         schemaVersion: 1,
@@ -349,6 +352,8 @@ export function exportTelemetry(repoPath, records, outputPath = ".knodin/telemet
         },
         summary: telemetrySummary(records),
         records,
+        adoption: summarizeAdoption(sessionEvents),
+        sessionEvents,
     };
     atomicPrivateWrite(target, `${JSON.stringify(bundle, null, 2)}\n`);
     return {

package/dist/src/repair-lease.js

@@ -41,10 +41,13 @@ function writeLease(target, record) {
         mode: 0o600,
     });
 }
-function removeStaleLeaseOrThrow(target) {
+function removeStaleLeaseOrThrow(target, operation) {
     const current = readLease(target);
     if (current && processIsAlive(current.pid)) {
-        throw new Error(`knodin repair: another repair is already in progress (pid ${current.pid}, started ${current.startedAt}); wait for it to finish, then run \`knodin status\``);
+        const contention = operation === "repair"
+            ? "another repair is already in progress"
+            : "another lifecycle mutation is already in progress";
+        throw new Error(`knodin ${operation}: ${contention} (pid ${current.pid}, started ${current.startedAt}); wait for it to finish, then run \`knodin status\``);
     }
     try {
         fs.unlinkSync(target);
@@ -55,7 +58,7 @@ function removeStaleLeaseOrThrow(target) {
     }
 }
 /** Atomically serialize repair post-processing across independent CLI/MCP processes. */
-export function acquireRepairLease(repo) {
+export function acquireRepairLease(repo, operation = "repair") {
     const target = leasePath(repo);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const record = {
@@ -78,8 +81,8 @@ export function acquireRepairLease(repo) {
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
-            removeStaleLeaseOrThrow(target);
+            removeStaleLeaseOrThrow(target, operation);
         }
     }
-    throw new Error("knodin repair: could not acquire the repository repair lease; retry shortly");
+    throw new Error(`knodin ${operation}: could not acquire the repository lifecycle lease; retry shortly`);
 }

package/dist/src/response-budget.js

@@ -46,7 +46,8 @@ const PROTECTED_CONTRACT_KEYS = new Set([
     "to",
 ]);
 function isTruncatableDetail(entry) {
-    return typeof entry.key !== "string" || !PROTECTED_CONTRACT_KEYS.has(entry.key);
+    return (!entry.path.startsWith("$/sharedIndex/") &&
+        (typeof entry.key !== "string" || !PROTECTED_CONTRACT_KEYS.has(entry.key)));
 }
 function synchronizeNestedCapabilityBudget(root, metadata, operation) {
     const cross = root.crossSubstratePath;

package/dist/src/session-telemetry.js

@@ -0,0 +1,163 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG = ".knodin/telemetry-config.json";
+const EVENTS = ".knodin/session-events.jsonl";
+const KEY = ".knodin/telemetry-key";
+function target(repo, relative) {
+    const root = fs.realpathSync(repo);
+    const value = path.resolve(root, relative);
+    if (!value.startsWith(`${root}${path.sep}`))
+        throw new Error("knodin telemetry path escaped repository");
+    let candidate = root;
+    for (const segment of path.relative(root, value).split(path.sep)) {
+        candidate = path.join(candidate, segment);
+        try {
+            if (fs.lstatSync(candidate).isSymbolicLink())
+                throw new Error("knodin telemetry refuses symlinks");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return value;
+}
+function atomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, value, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, filePath);
+}
+function enabled(repo) {
+    try {
+        return JSON.parse(fs.readFileSync(target(repo, CONFIG), "utf8")).enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function enableSessionTelemetry(repo) {
+    atomic(target(repo, CONFIG), `${JSON.stringify({ schemaVersion: 1, enabled: true })}\n`);
+    const key = target(repo, KEY);
+    if (!fs.existsSync(key))
+        atomic(key, crypto.randomBytes(32).toString("hex"));
+    return { schemaVersion: 1, enabled: true, localOnly: true };
+}
+export function disableSessionTelemetry(repo) {
+    atomic(target(repo, CONFIG), `${JSON.stringify({ schemaVersion: 1, enabled: false })}\n`);
+    return { schemaVersion: 1, enabled: false, retained: readSessionEvents(repo).length };
+}
+function sessionHash(repo, sessionId) {
+    const secret = fs.readFileSync(target(repo, KEY), "utf8").trim();
+    return `session_${crypto.createHmac("sha256", secret).update(sessionId).digest("hex").slice(0, 20)}`;
+}
+export function appendSessionEvent(repo, input) {
+    if (!enabled(repo))
+        return false;
+    if (!input.sessionId || input.sessionId.length > 256)
+        return false;
+    const record = {
+        schemaVersion: 1,
+        event: input.event,
+        session: sessionHash(repo, input.sessionId),
+        at: input.at ?? new Date().toISOString(),
+        client: input.client ?? "claude",
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.toolCategory ? { toolCategory: input.toolCategory } : {}),
+        ...(input.operation && /^[a-z][a-z0-9_-]{0,63}$/.test(input.operation)
+            ? { operation: input.operation }
+            : {}),
+        ...(input.freshness ? { freshness: input.freshness } : {}),
+        ...(typeof input.latencyMs === "number" ? { latencyMs: input.latencyMs } : {}),
+        ...(typeof input.cacheHit === "boolean" ? { cacheHit: input.cacheHit } : {}),
+    };
+    const filePath = target(repo, EVENTS);
+    fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    return true;
+}
+export function readSessionEvents(repo, retentionDays, now = new Date()) {
+    const filePath = target(repo, EVENTS);
+    if (!fs.existsSync(filePath))
+        return [];
+    const cutoff = retentionDays === undefined ? undefined : now.getTime() - retentionDays * 24 * 60 * 60 * 1000;
+    return fs
+        .readFileSync(filePath, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const value = JSON.parse(line);
+            if (value.schemaVersion !== 1 || typeof value.session !== "string")
+                return [];
+            if (cutoff !== undefined) {
+                const timestamp = typeof value.at === "string" ? Date.parse(value.at) : Number.NaN;
+                if (!Number.isFinite(timestamp) || timestamp < cutoff)
+                    return [];
+            }
+            return [value];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function summarizeAdoption(events) {
+    const sessions = new Set(events.map(({ session }) => session));
+    const evidenceOperations = new Set(["context", "explain", "review", "map", "search", "query"]);
+    const knodinSessions = new Set(events
+        .filter(({ event, toolCategory, operation }) => event === "tool_success" &&
+        toolCategory === "knodin" &&
+        operation !== undefined &&
+        evidenceOperations.has(operation))
+        .map(({ session }) => session));
+    let fallbackTraversalAfterKnodin = 0;
+    let evidenceBeforeEdit = 0;
+    const seenKnodin = new Set();
+    for (const event of events) {
+        if (event.event === "turn_start")
+            seenKnodin.delete(event.session);
+        if (event.toolCategory === "knodin" &&
+            event.event === "tool_success" &&
+            event.operation !== undefined &&
+            evidenceOperations.has(event.operation))
+            seenKnodin.add(event.session);
+        if (event.event === "tool_success" &&
+            event.toolCategory === "manual_traversal" &&
+            seenKnodin.has(event.session))
+            fallbackTraversalAfterKnodin += 1;
+        if (event.event === "tool_success" &&
+            event.toolCategory === "edit" &&
+            seenKnodin.has(event.session))
+            evidenceBeforeEdit += 1;
+        if (event.event === "turn_end")
+            seenKnodin.delete(event.session);
+    }
+    return {
+        sessions: sessions.size,
+        contextDelivered: events.filter(({ event, context }) => event === "session_start" && context === "delivered").length,
+        contextDegraded: events.filter(({ event, context }) => event === "session_start" && context === "degraded").length,
+        knodinSessions: knodinSessions.size,
+        turns: events.filter(({ event }) => event === "turn_start").length,
+        fallbackTraversalAfterKnodin,
+        evidenceBeforeEdit,
+        correctiveRoundTrips: null,
+    };
+}
+export function sessionTelemetryStatus(repo, retentionDays) {
+    const records = readSessionEvents(repo, retentionDays);
+    return {
+        schemaVersion: 1,
+        enabled: enabled(repo),
+        localOnly: true,
+        records: records.length,
+        adoption: summarizeAdoption(records),
+    };
+}
+export function clearSessionTelemetry(repo) {
+    const filePath = target(repo, EVENTS);
+    const records = readSessionEvents(repo).length;
+    const bytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+    fs.rmSync(filePath, { force: true });
+    return { removed: bytes > 0, records, bytes };
+}

package/dist/src/shared-index/artifact.js

@@ -0,0 +1,65 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { createZstdDecompress } from "node:zlib";
+import { assertCandidate } from "../engine/candidate-database.js";
+import { SharedIndexError } from "./s3-client.js";
+const SQLITE_HEADER = Buffer.from("SQLite format 3\0", "binary");
+function writeAll(descriptor, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength)
+        offset += fs.writeSync(descriptor, bytes, offset, bytes.byteLength - offset);
+}
+export async function decompressArtifactToCandidate(options) {
+    assertCandidate(options.repo, options.candidate);
+    if (fs.existsSync(options.candidate.databasePath))
+        throw new SharedIndexError("integrity", "shared-index candidate database already exists");
+    const source = fs.createReadStream(options.artifact.path);
+    const decompressor = createZstdDecompress();
+    const output = fs.openSync(options.candidate.databasePath, "wx", 0o600);
+    const hash = crypto.createHash("sha256");
+    let received = 0;
+    try {
+        if (options.signal) {
+            if (options.signal.aborted)
+                throw new SharedIndexError("timeout", "shared-index decompression was cancelled");
+            options.signal.addEventListener("abort", () => decompressor.destroy(), { once: true });
+        }
+        source.pipe(decompressor);
+        for await (const chunk of decompressor) {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            received += bytes.byteLength;
+            if (received > options.manifest.graph.uncompressedBytes)
+                throw new SharedIndexError("integrity", "shared-index decompressed object exceeded manifest size");
+            hash.update(bytes);
+            writeAll(output, bytes);
+        }
+        if (decompressor.bytesWritten !== options.manifest.graph.compressedBytes)
+            throw new SharedIndexError("integrity", "shared-index compressed object contains trailing data");
+        fs.fsyncSync(output);
+        if (received !== options.manifest.graph.uncompressedBytes ||
+            hash.digest("hex") !== options.manifest.graph.uncompressedSha256)
+            throw new SharedIndexError("integrity", "shared-index decompressed object failed size or digest verification");
+    }
+    catch (error) {
+        fs.closeSync(output);
+        fs.rmSync(options.candidate.databasePath, { force: true });
+        if (options.signal?.aborted)
+            throw new SharedIndexError("timeout", "shared-index decompression was cancelled");
+        if (error instanceof SharedIndexError)
+            throw error;
+        throw new SharedIndexError("integrity", "shared-index compressed object is not valid zstd");
+    }
+    finally {
+        source.destroy();
+        decompressor.destroy();
+    }
+    fs.closeSync(output);
+    const descriptor = fs.openSync(options.candidate.databasePath, "r");
+    const header = Buffer.alloc(SQLITE_HEADER.byteLength);
+    const headerBytes = fs.readSync(descriptor, header, 0, header.byteLength, 0);
+    fs.closeSync(descriptor);
+    if (headerBytes !== header.byteLength || !header.equals(SQLITE_HEADER)) {
+        fs.rmSync(options.candidate.databasePath, { force: true });
+        throw new SharedIndexError("integrity", "shared-index artifact is not a SQLite database");
+    }
+}