knodin 0.8.4 → 0.8.6

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

@@ -0,0 +1,224 @@
+import child_process from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocument, stringify } from "yaml";
+import { z } from "zod";
+import { canonicalRepositoryIdentity, sharedBranchMatches, } from "./contract.js";
+export const SHARED_INDEX_CONFIG_PATH = ".knodin/shared-index.yaml";
+const repositorySchema = z
+    .object({
+    host: z.string().min(1).max(253),
+    owner: z.string().min(1).max(255),
+    name: z.string().min(1).max(255),
+})
+    .strict();
+const canonicalHost = /^(?!.*\.\.)(?!.*(?:^|\.)-)(?!.*-(?:\.|$))[a-z0-9](?:[a-z0-9.-]{0,251}[a-z0-9])?$/;
+const canonicalOwner = /^[a-z0-9](?:[a-z0-9-]{0,253}[a-z0-9])?$/;
+const canonicalName = /^[a-z0-9](?:[a-z0-9._-]{0,253}[a-z0-9])?$/;
+const configSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    enabled: z.boolean(),
+    registrationId: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,127}$/),
+    aws: z
+        .object({
+        region: z.string().regex(/^[a-z]{2}(?:-gov)?-[a-z]+-\d$/),
+        bucket: z
+            .string()
+            .regex(/^(?!xn--)(?!.*\.\.)(?!.*\.-)(?!.*-\.)(?!\d{1,3}(?:\.\d{1,3}){3}$)[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/),
+    })
+        .strict(),
+    repository: repositorySchema,
+    branches: z.array(z.string().min(1).max(255)).min(1).max(64),
+    signing: z
+        .object({
+        algorithm: z.literal("RSASSA_PSS_SHA_256"),
+        keyId: z
+            .string()
+            .max(2048)
+            .regex(/^(?:arn:(?:aws|aws-us-gov|aws-cn):kms:[a-z0-9-]+:\d{12}:(?:key\/[A-Za-z0-9-]+|alias\/[A-Za-z0-9/_+=,.@-]+)|alias\/[A-Za-z0-9/_+=,.@-]+)$/),
+        publicKeySha256: z.string().regex(/^[a-f0-9]{64}$/),
+        publicKeyPem: z.string().min(1).max(16_384),
+    })
+        .strict(),
+})
+    .strict();
+function boundedError(error) {
+    if (error instanceof z.ZodError)
+        return error.issues
+            .slice(0, 16)
+            .map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`)
+            .join("; ");
+    if (error instanceof Error)
+        return error.message.slice(0, 512);
+    return "invalid shared-index configuration";
+}
+function validateBranchPattern(pattern) {
+    if (pattern.startsWith("/") ||
+        pattern.endsWith("/") ||
+        pattern.includes("//") ||
+        pattern.includes("..") ||
+        pattern.includes("@{") ||
+        /[~^:?[\\]/.test(pattern))
+        return false;
+    const stars = [...pattern].filter((character) => character === "*").length;
+    return stars === 0 || (stars === 1 && pattern.endsWith("/*"));
+}
+export function publicKeyFingerprint(publicKeyPem) {
+    const key = crypto.createPublicKey(publicKeyPem);
+    if (key.asymmetricKeyType !== "rsa" && key.asymmetricKeyType !== "rsa-pss")
+        throw new Error("signing public key must be RSA");
+    const bits = key.asymmetricKeyDetails?.modulusLength;
+    if (!bits || bits < 2048 || bits > 8192)
+        throw new Error("signing RSA public key must have a 2048-8192 bit modulus");
+    const der = key.export({ type: "spki", format: "der" });
+    return crypto.createHash("sha256").update(der).digest("hex");
+}
+function parseRemote(remote) {
+    const trimmed = remote.trim();
+    let host;
+    let pathname;
+    try {
+        if (/^[^@/\s]+@[^:/\s]+:.+$/.test(trimmed)) {
+            const match = /^[^@/\s]+@([^:/\s]+):(.+)$/.exec(trimmed);
+            if (!match)
+                return null;
+            host = match[1];
+            pathname = match[2];
+        }
+        else {
+            const parsed = new URL(trimmed);
+            host = parsed.hostname;
+            pathname = parsed.pathname.replace(/^\//, "");
+        }
+    }
+    catch {
+        return null;
+    }
+    const segments = pathname.split("/").filter(Boolean);
+    if (segments.length !== 2)
+        return null;
+    return canonicalRepositoryIdentity({ host, owner: segments[0], name: segments[1] });
+}
+export function repositoryRemoteIdentities(repo) {
+    let output;
+    try {
+        output = child_process.execFileSync("git", ["remote", "-v"], {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return [];
+    }
+    const identities = new Map();
+    for (const line of output.split("\n")) {
+        const remote = line.trim().split(/\s+/)[1];
+        if (!remote)
+            continue;
+        const identity = parseRemote(remote);
+        if (!identity)
+            continue;
+        identities.set(`${identity.host}/${identity.owner}/${identity.name}`, identity);
+    }
+    return [...identities.values()];
+}
+export function validateSharedIndexConfig(value, repo) {
+    const parsed = configSchema.parse(value);
+    const repository = canonicalRepositoryIdentity(parsed.repository);
+    if (!canonicalHost.test(repository.host))
+        throw new Error("repository host is not canonical DNS syntax");
+    if (!canonicalOwner.test(repository.owner))
+        throw new Error("repository owner is invalid");
+    if (!canonicalName.test(repository.name))
+        throw new Error("repository name is invalid");
+    if (new Set(parsed.branches).size !== parsed.branches.length)
+        throw new Error("branches must not contain duplicates");
+    if (parsed.branches.some((branch) => !validateBranchPattern(branch)))
+        throw new Error("branch must be an exact Git ref or a terminal slash-star prefix pattern");
+    // Exercise the frozen matcher for every accepted pattern so validation and
+    // selection cannot silently drift into two different glob languages.
+    for (const branch of parsed.branches)
+        if (!branch.endsWith("/*") && !sharedBranchMatches(branch, branch))
+            throw new Error("invalid exact branch pattern");
+    const fingerprint = publicKeyFingerprint(parsed.signing.publicKeyPem);
+    if (!crypto.timingSafeEqual(Buffer.from(fingerprint, "hex"), Buffer.from(parsed.signing.publicKeySha256, "hex")))
+        throw new Error("signing public-key fingerprint does not match reviewed configuration");
+    if (repo) {
+        const remotes = repositoryRemoteIdentities(repo);
+        if (remotes.length === 0)
+            throw new Error("repository identity cannot be verified because no supported Git remote exists");
+        if (!remotes.some((remote) => JSON.stringify(remote) === JSON.stringify(repository)))
+            throw new Error("configured repository identity does not match any local Git remote");
+    }
+    return { ...parsed, repository };
+}
+export function loadSharedIndexConfig(repo) {
+    const target = path.join(path.resolve(repo), SHARED_INDEX_CONFIG_PATH);
+    if (!fs.existsSync(target))
+        return { state: "not-configured", path: target };
+    try {
+        const document = parseDocument(fs.readFileSync(target, "utf8"), {
+            strict: true,
+            uniqueKeys: true,
+        });
+        if (document.errors.length > 0)
+            throw new Error(document.errors.map((error) => error.message).join("; "));
+        const raw = document.toJS({ maxAliasCount: 0 });
+        return { state: "configured", path: target, config: validateSharedIndexConfig(raw, repo) };
+    }
+    catch (error) {
+        return { state: "invalid", path: target, errors: [boundedError(error)] };
+    }
+}
+function assertWritableTarget(repo, target) {
+    const state = path.dirname(target);
+    if (fs.existsSync(state) && fs.lstatSync(state).isSymbolicLink())
+        throw new Error("shared-index configuration directory must not be a symbolic link");
+    if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink())
+        throw new Error("shared-index configuration must not be a symbolic link");
+    const relative = path.relative(path.resolve(repo), path.resolve(target));
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error("shared-index configuration must remain inside the repository");
+}
+export function writeSharedIndexConfig(repo, config) {
+    const resolved = path.resolve(repo);
+    const validated = validateSharedIndexConfig(config, resolved);
+    const target = path.join(resolved, SHARED_INDEX_CONFIG_PATH);
+    assertWritableTarget(resolved, target);
+    fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, stringify(validated, { lineWidth: 0 }), {
+            mode: 0o600,
+            flag: "wx",
+        });
+        const descriptor = fs.openSync(temporary, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        fs.renameSync(temporary, target);
+        try {
+            const directory = fs.openSync(path.dirname(target), "r");
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+        }
+        catch (error) {
+            if (process.platform !== "win32")
+                throw error;
+        }
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+    return target;
+}

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

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+export const SHARED_INDEX_SCHEMA_VERSION = 1;
+export const SHARED_INDEX_SIGNATURE = {
+    algorithm: "RSA-PSS",
+    hash: "sha256",
+    mgf1Hash: "sha256",
+    saltLength: 32,
+    input: "canonical-manifest-bytes",
+};
+export const SHARED_INDEX_LIMITS = {
+    pointerBytes: 64 * 1024,
+    manifestBytes: 256 * 1024,
+    signatureBytes: 16 * 1024,
+    compressedBytes: 8 * 1024 ** 3,
+    uncompressedBytes: 32 * 1024 ** 3,
+};
+function normalizedComponent(value) {
+    return value.normalize("NFC").toLocaleLowerCase("en-US");
+}
+/** Canonical identity used for remote comparison, signatures, and S3 prefixes. */
+export function canonicalRepositoryIdentity(identity) {
+    const host = identity.host
+        .replace(/^https?:\/\//i, "")
+        .replace(/^ssh:\/\/git@/i, "")
+        .replace(/\/$/, "")
+        .replace(/\.$/, "");
+    return {
+        host: normalizedComponent(host),
+        owner: normalizedComponent(identity.owner),
+        name: normalizedComponent(identity.name.replace(/\.git$/i, "")),
+    };
+}
+/** RFC 3986 component encoding (encodeURIComponent leaves five extra characters). */
+export function encodeSharedIndexComponent(value) {
+    return encodeURIComponent(value.normalize("NFC")).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+export function sharedRepositoryPrefix(identity) {
+    const canonical = canonicalRepositoryIdentity(identity);
+    return `v1/${encodeSharedIndexComponent(canonical.host)}/${encodeSharedIndexComponent(canonical.owner)}/${encodeSharedIndexComponent(canonical.name)}/`;
+}
+function parsedVersion(version) {
+    const match = /^(\d+)\.(\d+)\.\d+(?:-([0-9A-Za-z.-]+))?$/.exec(version);
+    if (!match)
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]), prerelease: match[3] };
+}
+/** Exact v1 compatibility decision; every rejection is bounded and source-free. */
+export function sharedIndexCompatibility(client, manifest) {
+    const reasons = [];
+    const clientVersion = parsedVersion(client.knodinVersion);
+    const manifestVersion = parsedVersion(manifest.knodinVersion);
+    if (!clientVersion || !manifestVersion)
+        reasons.push("invalid-knodin-version");
+    else if (clientVersion.prerelease || manifestVersion.prerelease) {
+        if (client.knodinVersion !== manifest.knodinVersion)
+            reasons.push("knodin-prerelease-mismatch");
+    }
+    else if (clientVersion.major !== manifestVersion.major ||
+        clientVersion.minor < manifestVersion.minor) {
+        reasons.push("knodin-version-incompatible");
+    }
+    const exactFields = [
+        "databaseSchemaVersion",
+        "modelId",
+        "modelDigest",
+        "parserBundleDigest",
+        "indexConfigDigest",
+        "prunePolicyDigest",
+    ];
+    for (const field of exactFields) {
+        if (client[field] !== manifest[field])
+            reasons.push(`${field}-mismatch`);
+    }
+    return { compatible: reasons.length === 0, reasons };
+}
+/** Exact v1 ref matching, including the terminal slash-star prefix form. */
+export function sharedBranchMatches(pattern, branch) {
+    const normalizedPattern = pattern.normalize("NFC");
+    const normalizedBranch = branch.normalize("NFC");
+    return normalizedPattern.endsWith("/*")
+        ? normalizedBranch.startsWith(normalizedPattern.slice(0, -1)) &&
+            normalizedBranch.length > normalizedPattern.length - 1
+        : normalizedBranch === normalizedPattern;
+}
+function canonicalValue(value) {
+    if (typeof value === "string" &&
+        /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(value))
+        throw new TypeError("canonical JSON forbids unpaired Unicode surrogates");
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("canonical JSON forbids non-finite numbers");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalValue).join(",")}]`;
+    if (typeof value === "object") {
+        const record = value;
+        const entries = Object.keys(record)
+            .sort((left, right) => left.localeCompare(right))
+            .map((key) => {
+            if (record[key] === undefined)
+                throw new TypeError("canonical JSON forbids undefined object values");
+            return `${JSON.stringify(key)}:${canonicalValue(record[key])}`;
+        });
+        return `{${entries.join(",")}}`;
+    }
+    throw new TypeError(`canonical JSON forbids ${typeof value} values`);
+}
+/** Exact UTF-8 bytes hashed and signed by shared-index v1. */
+export function canonicalManifestBytes(manifest) {
+    return Buffer.from(canonicalValue(manifest), "utf8");
+}
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}

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

@@ -0,0 +1,71 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { publicKeyFingerprint } from "./config.js";
+import { canonicalManifestBytes, canonicalRepositoryIdentity, encodeSharedIndexComponent, SHARED_INDEX_LIMITS, sha256Hex, sharedIndexCompatibility, sharedRepositoryPrefix, } from "./contract.js";
+import { SharedIndexError } from "./s3-client.js";
+function sameIdentity(left, right) {
+    return (JSON.stringify(canonicalRepositoryIdentity(left)) ===
+        JSON.stringify(canonicalRepositoryIdentity(right)));
+}
+export function branchPointerKey(config, branch) {
+    return `${sharedRepositoryPrefix(config.repository)}branches/${encodeSharedIndexComponent(branch)}.json`;
+}
+export function signatureKey(manifestKey) {
+    if (!manifestKey.endsWith("/manifest.json"))
+        throw new SharedIndexError("integrity", "shared-index manifest key has an invalid filename");
+    return `${manifestKey.slice(0, -"manifest.json".length)}manifest.sig`;
+}
+export function compatibilityFingerprint(compatibility) {
+    return sha256Hex(canonicalManifestBytes(compatibility));
+}
+export function validatePointerBinding(config, pointer) {
+    if (pointer.registrationId !== config.registrationId)
+        throw new SharedIndexError("integrity", "shared-index pointer registration does not match configuration");
+    if (!sameIdentity(pointer.repository, config.repository))
+        throw new SharedIndexError("integrity", "shared-index pointer repository does not match configuration");
+    const directory = `${sharedRepositoryPrefix(config.repository)}snapshots/${pointer.commit}/${pointer.inputFingerprint}/`;
+    if (pointer.manifestKey !== `${directory}manifest.json`)
+        throw new SharedIndexError("integrity", "shared-index manifest key escaped its immutable snapshot prefix");
+}
+function verifyConfiguredTrustRoot(config) {
+    let fingerprint;
+    try {
+        fingerprint = publicKeyFingerprint(config.signing.publicKeyPem);
+    }
+    catch {
+        throw new SharedIndexError("integrity", "shared-index configured signing key is invalid");
+    }
+    const expected = Buffer.from(config.signing.publicKeySha256, "hex");
+    const actual = Buffer.from(fingerprint, "hex");
+    if (expected.byteLength !== actual.byteLength || !crypto.timingSafeEqual(expected, actual))
+        throw new SharedIndexError("integrity", "shared-index configured signing-key fingerprint does not match");
+}
+export function verifyManifest(config, pointer, rawManifest, manifest, signature, clientCompatibility) {
+    if (signature.byteLength === 0 || signature.byteLength > SHARED_INDEX_LIMITS.signatureBytes)
+        throw new SharedIndexError("integrity", "shared-index signature exceeds its byte limit");
+    verifyConfiguredTrustRoot(config);
+    if (sha256Hex(rawManifest) !== pointer.manifestSha256)
+        throw new SharedIndexError("integrity", "shared-index manifest digest does not match pointer");
+    if (!Buffer.from(rawManifest).equals(canonicalManifestBytes(manifest)))
+        throw new SharedIndexError("integrity", "shared-index manifest bytes are not canonical JSON v1");
+    const verified = crypto.verify("sha256", rawManifest, {
+        key: config.signing.publicKeyPem,
+        padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
+        saltLength: 32,
+    }, signature);
+    if (!verified)
+        throw new SharedIndexError("integrity", "shared-index manifest signature is invalid");
+    if (manifest.registrationId !== config.registrationId ||
+        !sameIdentity(manifest.repository, config.repository))
+        throw new SharedIndexError("integrity", "shared-index signed identity does not match configuration");
+    if (manifest.commit !== pointer.commit)
+        throw new SharedIndexError("integrity", "shared-index signed commit does not match pointer");
+    if (compatibilityFingerprint(manifest.compatibility) !== pointer.inputFingerprint)
+        throw new SharedIndexError("integrity", "shared-index compatibility fingerprint does not match pointer");
+    const immutableDirectory = path.posix.dirname(pointer.manifestKey);
+    if (manifest.graph.key !== `${immutableDirectory}/graph.sqlite.zst`)
+        throw new SharedIndexError("integrity", "shared-index graph key escaped its immutable snapshot prefix");
+    const compatibility = sharedIndexCompatibility(clientCompatibility, manifest.compatibility);
+    if (!compatibility.compatible)
+        throw new SharedIndexError("compatibility", `shared-index snapshot is incompatible (${compatibility.reasons.join(",")})`);
+}

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

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import { resolveDbPath } from "../engine/state-paths.js";
+import { currentSharedIndexCompatibility } from "./compatibility.js";
+import { loadSharedIndexConfig } from "./config.js";
+import { readSharedIndexProvenance, readSharedRestoreAttempt } from "./provenance.js";
+import { restoreSharedIndex } from "./restore.js";
+import { createSharedObjectStore } from "./s3-client.js";
+const FAILURE_BACKOFF_MS = 15 * 60 * 1000;
+export function shouldAttemptOpportunisticRestore(repo, now = Date.now()) {
+    const configuration = loadSharedIndexConfig(repo);
+    if (configuration.state !== "configured" || !configuration.config.enabled)
+        return false;
+    if (fs.existsSync(resolveDbPath(repo)) && readSharedIndexProvenance(repo))
+        return false;
+    const last = readSharedRestoreAttempt(repo);
+    if (last?.outcome === "failed" && now - Date.parse(last.attemptedAt) < FAILURE_BACKOFF_MS)
+        return false;
+    return true;
+}
+/** Safe cold-start optimization: every failure returns to the caller for local fallback. */
+export async function attemptOpportunisticSharedRestore(repo, engine) {
+    if (!shouldAttemptOpportunisticRestore(repo))
+        return null;
+    const configuration = loadSharedIndexConfig(repo);
+    if (configuration.state !== "configured")
+        return null;
+    const store = createSharedObjectStore(configuration.config);
+    if (!store)
+        return null;
+    return restoreSharedIndex({
+        repo,
+        config: configuration.config,
+        store,
+        engine,
+        clientCompatibility: currentSharedIndexCompatibility(),
+    });
+}

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

@@ -0,0 +1,98 @@
+import child_process from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { compareBytes } from "../compare.js";
+import { isIndexableSourcePath } from "../engine/source-policy.js";
+import { SharedIndexError } from "./s3-client.js";
+function split(output) {
+    return output.split("\0").filter(Boolean);
+}
+function gitPaths(repo, args) {
+    try {
+        return split(child_process.execFileSync("git", args, {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 64 * 1024 * 1024,
+        }));
+    }
+    catch {
+        throw new SharedIndexError("unavailable", "shared-index could not derive the local overlay");
+    }
+}
+function safeRelativePath(repo, value) {
+    const normalized = value.replaceAll("\\", "/").normalize("NFC");
+    const resolved = path.resolve(repo, normalized);
+    const relative = path.relative(path.resolve(repo), resolved);
+    if (!relative ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative) ||
+        normalized.includes("\0"))
+        throw new SharedIndexError("integrity", "shared-index Git overlay contains an unsafe path");
+    return relative.replaceAll("\\", "/");
+}
+function digestFile(target) {
+    const hash = crypto.createHash("sha256");
+    const descriptor = fs.openSync(target, "r");
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    try {
+        for (;;) {
+            const bytes = fs.readSync(descriptor, buffer, 0, buffer.byteLength, null);
+            if (bytes === 0)
+                break;
+            hash.update(buffer.subarray(0, bytes));
+        }
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    return hash.digest("hex");
+}
+export function deriveSharedOverlay(repo, snapshotCommit) {
+    const resolved = path.resolve(repo);
+    const committed = new Set(gitPaths(resolved, [
+        "diff",
+        "--name-only",
+        "--no-renames",
+        "-z",
+        snapshotCommit,
+        "HEAD",
+        "--",
+    ]).map((file) => safeRelativePath(resolved, file)));
+    const staged = new Set(gitPaths(resolved, ["diff", "--cached", "--name-only", "--no-renames", "-z", "HEAD", "--"]).map((file) => safeRelativePath(resolved, file)));
+    const working = new Set(gitPaths(resolved, ["diff", "--name-only", "--no-renames", "-z", "--"]).map((file) => safeRelativePath(resolved, file)));
+    const untracked = new Set(gitPaths(resolved, ["ls-files", "--others", "--exclude-standard", "-z", "--"])
+        .map((file) => safeRelativePath(resolved, file))
+        .filter((file) => isIndexableSourcePath(file)));
+    const changedPaths = [...new Set([...committed, ...staged, ...working, ...untracked])].sort(compareBytes);
+    const deletedPaths = changedPaths.filter((file) => !fs.existsSync(path.join(resolved, file))).length;
+    const fingerprint = crypto.createHash("sha256");
+    fingerprint.update(`snapshot\0${snapshotCommit}\0`);
+    for (const file of changedPaths) {
+        const absolute = path.join(resolved, file);
+        let digest = "deleted";
+        try {
+            const stat = fs.lstatSync(absolute);
+            if (stat.isFile() && !stat.isSymbolicLink())
+                digest = digestFile(absolute);
+            else
+                digest = "ineligible";
+        }
+        catch {
+            // Final disk truth is deletion even when a path changed in several layers.
+        }
+        fingerprint.update(`${Buffer.byteLength(file)}:${file}\0${digest}\0`);
+    }
+    return {
+        changedPaths,
+        counts: {
+            committedPaths: committed.size,
+            stagedPaths: staged.size,
+            workingTreePaths: working.size,
+            deletedPaths,
+            untrackedPaths: untracked.size,
+        },
+        effectiveTreeFingerprint: fingerprint.digest("hex"),
+    };
+}