knodin 0.13.0 → 0.14.0

package/dist/src/engine/seal.js

@@ -140,14 +140,38 @@ export function readSealAttestation(db) {
  * which is exactly the silent false negative the consumer needs to be able to
  * detect in order to fall back.
  */
-export function readSealedSource(db, filePath) {
+export function readSealedSource(db, filePath, maxBytes) {
+    if (maxBytes !== undefined) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+            throw new RangeError("Invalid sealed source byte limit");
+        const bounded = db
+            .query("SELECT s.bytes, s.compressed, s.rawBytes, s.storedBytes, s.sha256 FROM sealed_file f JOIN sealed_source s ON s.sha256=f.sha256 WHERE f.filePath=? AND length(s.bytes)<=?")
+            .get(filePath, maxBytes);
+        if (!bounded)
+            return null;
+        if (![0, 1].includes(bounded.compressed) ||
+            !Number.isSafeInteger(bounded.rawBytes) ||
+            bounded.rawBytes < 0 ||
+            bounded.rawBytes > maxBytes ||
+            bounded.storedBytes !== bounded.bytes.byteLength)
+            throw new Error("Invalid bounded sealed source metadata");
+        const raw = bounded.compressed
+            ? zlib.zstdDecompressSync(bounded.bytes, { maxOutputLength: maxBytes })
+            : Buffer.from(bounded.bytes);
+        if (raw.byteLength !== bounded.rawBytes ||
+            crypto.createHash("sha256").update(raw).digest("hex") !== bounded.sha256)
+            throw new Error("Sealed source integrity mismatch");
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+    }
     const row = db
-        .query("SELECT s.bytes bytes, s.compressed compressed FROM sealed_file f JOIN sealed_source s ON s.sha256 = f.sha256 WHERE f.filePath = ?")
-        .get(filePath);
+        .query("SELECT s.bytes bytes, s.compressed compressed FROM sealed_file f JOIN sealed_source s ON s.sha256 = f.sha256 WHERE f.filePath = ? AND length(s.bytes) <= ?")
+        .get(filePath, maxBytes ?? Number.MAX_SAFE_INTEGER);
     if (!row)
         return null;
     const raw = Buffer.from(row.bytes);
-    return (row.compressed ? zlib.zstdDecompressSync(raw) : raw).toString("utf8");
+    return (row.compressed
+        ? zlib.zstdDecompressSync(raw, maxBytes === undefined ? undefined : { maxOutputLength: maxBytes })
+        : raw).toString("utf8");
 }
 /**
  * Every path the sealed artifact carries source for.

package/dist/src/engine/state-paths.js

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -32,6 +33,28 @@ export const MIRROR_STATE_DIR = "state";
 /** In-tree state directory name for a normal checkout. */
 export const IN_TREE_STATE_DIR = ".knodin";
 const REGISTRY_VERSION = 1;
+const MIRROR_IDENTITY = /^repo_[0-9a-f]{20}$/;
+function assertMirrorIdentity(identity) {
+    if (!MIRROR_IDENTITY.test(identity))
+        throw new Error("mirror registry: invalid repository identity");
+}
+function containedMirrorDirectory(parent, name) {
+    const target = path.join(parent, name);
+    for (const directory of [parent, target]) {
+        try {
+            const stat = fs.lstatSync(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error("mirror registry: unsafe state directory");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    if (fs.existsSync(target) && path.dirname(fs.realpathSync(target)) !== fs.realpathSync(parent))
+        throw new Error("mirror registry: escaped state directory");
+    return target;
+}
 const EMPTY_REGISTRY = { version: REGISTRY_VERSION, mirrors: [] };
 /**
  * Root for all mirror storage. Defaults to `~/.knodin/mirrors` rather than an
@@ -49,19 +72,20 @@ export function mirrorRegistryPath() {
 }
 /** Root for in-progress clones, renamed into place only once complete. */
 export function mirrorStagingRoot() {
-    return path.join(mirrorRoot(), ".staging");
+    return containedMirrorDirectory(mirrorRoot(), ".staging");
 }
 /** Entry root for one mirror: the parent of both `source/` and `state/`. */
 export function mirrorEntryPath(identity) {
-    return path.join(mirrorRoot(), identity);
+    assertMirrorIdentity(identity);
+    return containedMirrorDirectory(mirrorRoot(), identity);
 }
 /** Absolute path to a mirror's shallow clone. */
 export function mirrorSourcePath(identity) {
-    return path.join(mirrorEntryPath(identity), MIRROR_SOURCE_DIR);
+    return containedMirrorDirectory(mirrorEntryPath(identity), MIRROR_SOURCE_DIR);
 }
 /** Absolute path to a mirror's graph state directory. */
 export function mirrorStatePath(identity) {
-    return path.join(mirrorEntryPath(identity), MIRROR_STATE_DIR);
+    return containedMirrorDirectory(mirrorEntryPath(identity), MIRROR_STATE_DIR);
 }
 let cache = null;
 function isMirrorRecord(value) {
@@ -69,10 +93,13 @@ function isMirrorRecord(value) {
         return false;
     const record = value;
     return (typeof record.identity === "string" &&
+        MIRROR_IDENTITY.test(record.identity) &&
         typeof record.url === "string" &&
         typeof record.path === "string" &&
         typeof record.fetchedAt === "string" &&
-        typeof record.sha === "string");
+        typeof record.sha === "string" &&
+        record.readOnly === true &&
+        path.isAbsolute(record.path));
 }
 function indexByPath(registry) {
     const byPath = new Map();
@@ -80,57 +107,172 @@ function indexByPath(registry) {
         byPath.set(path.resolve(record.path), record);
     return byPath;
 }
+function assertMirrorRecordPath(record) {
+    const expected = mirrorSourcePath(record.identity);
+    try {
+        if (fs.realpathSync(record.path) !== fs.realpathSync(expected))
+            throw new Error("mirror registry: clone path does not match repository identity");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        // A missing clone remains registered for actionable recovery, but only at
+        // its deterministic managed location. A missing alias cannot be verified.
+        if (path.resolve(record.path) !== path.resolve(expected))
+            throw new Error("mirror registry: missing clone path does not match repository identity");
+    }
+}
 /**
  * Reads the mirror registry, memoized against the file's mtime and size so a
  * mirror added by a concurrent `knodin remote add` is picked up without paying a
  * JSON parse on every path resolution.
  *
- * The memo key is (mtimeMs, size), which is a heuristic rather than a guarantee:
- * an out-of-process write landing in the same millisecond AND producing the same
- * byte length would not invalidate it. Accepted deliberately — that requires a
- * concurrent edit of identical length within one millisecond, the in-process
- * writer drops the memo explicitly, and the cost of being wrong is one stale
- * read, not corruption. Recorded so it reads as a decision, not an oversight.
+ * The metadata memo includes inode/device, ctime, mtime and size. Registry reads
+ * use a bounded no-follow descriptor and verify file identity before caching.
+ * This is substitution detection, not atomic isolation from hostile filesystem
+ * writers; every derived mirror-state path also checks directory containment.
  *
- * A missing or corrupt registry reads as empty. That is deliberate too: it
- * degrades to "no mirrors configured", which routes every repository to its
- * in-tree state — the pre-existing behaviour — rather than failing a query
- * outright.
+ * Only a genuinely absent registry reads as empty. Corrupt, unsafe or unreadable
+ * registries fail closed: fallback could redirect a mirror into its source tree.
  */
 export function readMirrorRegistry() {
     const file = mirrorRegistryPath();
     let stat;
     try {
-        stat = fs.statSync(file);
+        stat = fs.lstatSync(file);
     }
-    catch {
+    catch (error) {
+        cache = null;
+        if (error.code === "ENOENT")
+            return EMPTY_REGISTRY;
+        throw new Error("mirror registry: unavailable registry", { cause: error });
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1_048_576) {
         cache = null;
-        return EMPTY_REGISTRY;
+        throw new Error("mirror registry: unsafe or oversized registry");
     }
-    if (cache?.mtimeMs === stat.mtimeMs && cache?.size === stat.size)
+    if (cache?.device === stat.dev &&
+        cache.inode === stat.ino &&
+        cache.ctimeMs === stat.ctimeMs &&
+        cache.mtimeMs === stat.mtimeMs &&
+        cache.size === stat.size)
         return cache.registry;
     try {
-        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-        const mirrors = typeof parsed === "object" &&
-            parsed !== null &&
-            Array.isArray(parsed.mirrors)
-            ? parsed.mirrors.filter(isMirrorRecord)
-            : [];
+        const descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        let parsed;
+        try {
+            const opened = fs.fstatSync(descriptor);
+            if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size)
+                throw new Error("registry changed during open");
+            const bytes = Buffer.alloc(stat.size + 1);
+            const count = fs.readSync(descriptor, bytes, 0, bytes.length, 0);
+            const final = fs.fstatSync(descriptor);
+            const current = fs.lstatSync(file);
+            if (count !== stat.size ||
+                final.size !== stat.size ||
+                final.ctimeMs !== stat.ctimeMs ||
+                current.dev !== stat.dev ||
+                current.ino !== stat.ino ||
+                current.ctimeMs !== stat.ctimeMs)
+                throw new Error("registry changed during read");
+            parsed = JSON.parse(bytes.subarray(0, count).toString("utf8"));
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        if (!parsed ||
+            typeof parsed !== "object" ||
+            parsed.version !== REGISTRY_VERSION ||
+            !Array.isArray(parsed.mirrors) ||
+            !parsed.mirrors.every(isMirrorRecord))
+            throw new Error("invalid mirror registry records");
+        const mirrors = parsed.mirrors;
+        if (new Set(mirrors.map((record) => record.identity)).size !== mirrors.length)
+            throw new Error("duplicate mirror identity");
+        for (const record of mirrors) {
+            mirrorStatePath(record.identity);
+            assertMirrorRecordPath(record);
+        }
+        const canonicalPaths = mirrors.map((record) => fs.existsSync(record.path) ? fs.realpathSync(record.path) : path.resolve(record.path));
+        if (new Set(canonicalPaths).size !== canonicalPaths.length)
+            throw new Error("duplicate mirror clone path");
         const registry = { version: REGISTRY_VERSION, mirrors };
-        cache = { mtimeMs: stat.mtimeMs, size: stat.size, registry, byPath: indexByPath(registry) };
+        cache = {
+            device: stat.dev,
+            inode: stat.ino,
+            ctimeMs: stat.ctimeMs,
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+            registry,
+            byPath: indexByPath(registry),
+        };
         return registry;
     }
-    catch {
+    catch (error) {
         cache = null;
-        return EMPTY_REGISTRY;
+        throw new Error("mirror registry: invalid or unsafe registry; restore it before graph access", {
+            cause: error,
+        });
     }
 }
 /** Persists the registry and drops the memo so the next read reloads it. */
 export function writeMirrorRegistry(registry) {
+    if (!registry.mirrors.every(isMirrorRecord))
+        throw new Error("mirror registry: invalid records");
+    for (const record of registry.mirrors) {
+        mirrorStatePath(record.identity);
+        assertMirrorRecordPath(record);
+    }
     const file = mirrorRegistryPath();
-    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const parent = path.dirname(file);
+    containedMirrorDirectory(parent, ".staging");
+    fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const parentIdentity = fs.lstatSync(parent);
+    const canonicalParent = fs.realpathSync(parent);
+    const verifyDestination = () => {
+        const current = fs.lstatSync(parent);
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            current.dev !== parentIdentity.dev ||
+            current.ino !== parentIdentity.ino ||
+            fs.realpathSync(parent) !== canonicalParent)
+            throw new Error("mirror registry: parent identity changed");
+        try {
+            const target = fs.lstatSync(file);
+            if (!target.isFile() || target.isSymbolicLink())
+                throw new Error("mirror registry: unsafe registry destination");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    };
+    verifyDestination();
     const document = { version: REGISTRY_VERSION, mirrors: registry.mirrors };
-    fs.writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`);
+    const bytes = Buffer.from(`${JSON.stringify(document, null, 2)}\n`);
+    if (bytes.length > 1_048_576)
+        throw new Error("mirror registry: oversized registry");
+    const temporary = path.join(parent, `.registry-${process.pid}-${crypto.randomUUID()}.tmp`);
+    try {
+        const descriptor = fs.openSync(temporary, "wx", 0o600);
+        try {
+            fs.writeFileSync(descriptor, bytes);
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        verifyDestination();
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        // Only remove the exclusive temporary name while its parent is unchanged.
+        const current = fs.lstatSync(parent);
+        if (current.dev === parentIdentity.dev &&
+            current.ino === parentIdentity.ino &&
+            !current.isSymbolicLink())
+            fs.rmSync(temporary, { force: true });
+    }
     cache = null;
 }
 /** Clears the in-process registry memo. Test seam. */
@@ -144,7 +286,26 @@ export function __resetMirrorRegistryCache() {
  */
 export function lookupMirror(repoPath) {
     readMirrorRegistry();
-    return cache?.byPath.get(path.resolve(repoPath));
+    const exact = cache?.byPath.get(path.resolve(repoPath));
+    if (exact)
+        return exact;
+    let canonical;
+    try {
+        canonical = fs.realpathSync(repoPath);
+    }
+    catch {
+        return undefined;
+    }
+    for (const record of cache?.byPath.values() ?? []) {
+        try {
+            if (fs.realpathSync(record.path) === canonical)
+                return record;
+        }
+        catch {
+            /* Missing clones do not match. */
+        }
+    }
+    return undefined;
 }
 /** True when `repoPath` is a registered read-only mirror clone. */
 export function isMirror(repoPath) {

package/dist/src/init.js

@@ -27,7 +27,8 @@ export class InitializationHealthError extends Error {
         const condition = indexResult.verification.issueCount > 0
             ? `${indexResult.verification.issueCount.toLocaleString()} graph issue(s) remain`
             : `graph verification reported status "${indexResult.verification.status}"`;
-        super(`knodin init: lifecycle hooks were installed, but ${condition}.${detail} Run \`knodin repair\`.`);
+        const remedy = indexResult.verification.repairSteps?.[0] ?? "Run `knodin repair`.";
+        super(`knodin init: lifecycle hooks were installed, but ${condition}.${detail} ${remedy}`);
         this.name = "InitializationHealthError";
         this.indexResult = indexResult;
     }
@@ -543,6 +544,13 @@ while :; do
   KIND="$(sed -n '1p' "$EVENT")"
   ARG1="$(sed -n '2p' "$EVENT")"
   ARG2="$(sed -n '3p' "$EVENT")"
+  # Hand the event sequence to the CLI so its JSON record carries it. indexer.log
+  # stays one JSON object per line (pack-install smoke and diagnostics parse it
+  # that way); the record's own "at"/"event" fields tie a refresh back to the Git
+  # event that queued it. Without that, a refresh that "succeeded" while the
+  # graph stayed 33 commits behind could not be correlated (KNODIN-49).
+  KNODIN_HOOK_EVENT_SEQUENCE="$(sed -n 's/^sequence=//p' "$EVENT" | head -n 1)"
+  export KNODIN_HOOK_EVENT_SEQUENCE
   if [ "$KIND" = "commit" ]; then
     ${invocation} --repo "$REPO_ROOT" hook-refresh commit --json >> "$LOG_PATH" 2>> "$LOG_PATH.stderr"
   elif [ "$KIND" = "checkout" ] || [ "$KIND" = "merge" ]; then
@@ -558,8 +566,12 @@ while :; do
     cp "$EVENT" "$LAST_EVENT_PATH"
     rm -f "$EVENT" "$FAILURE_PATH"
   else
+    # The CLI's --json error envelope already landed on the log line; name the
+    # cause in the failure file too so knodin status can say what broke instead
+    # of only that something did.
+    DETAIL="$(tail -n 1 "$LOG_PATH.stderr" 2>/dev/null)"
     {
-      printf 'knodin background refresh failed with exit code %s.\n' "$STATUS"
+      printf 'knodin background refresh failed at %s with exit code %s: %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$STATUS" "$DETAIL"
       printf 'Pending event retained at %s.\n' "$EVENT"
       printf 'See .knodin/indexer.log for details.\n'
     } > "$FAILURE_TMP"

package/dist/src/manager-update.js

@@ -328,6 +328,13 @@ async function boundedChannelJson(url, options) {
         clearTimeout(timeout);
     }
 }
+function compatibilityBreaking(value) {
+    if (value === "breaking")
+        return true;
+    if (value === "compatible" || value === "compatible-with-additions" || value === "non-breaking")
+        return false;
+    return null;
+}
 function npmReleases(value) {
     const versions = value.versions;
     const times = value.time;
@@ -341,11 +348,7 @@ function npmReleases(value) {
             version,
             publishedAt: times[version] ?? "",
             yanked: manifest.deprecated === true || typeof manifest.deprecated === "string",
-            breaking: policy?.compatibility === "non-breaking"
-                ? false
-                : policy?.compatibility === "breaking"
-                    ? true
-                    : null,
+            breaking: compatibilityBreaking(policy?.compatibility),
             channel: "npm",
         };
     })
@@ -362,11 +365,7 @@ function homebrewReleases(value) {
         version: String(entry.version),
         publishedAt: typeof entry.publishedAt === "string" ? entry.publishedAt : "",
         yanked: entry.yanked === true,
-        breaking: entry.compatibility === "non-breaking"
-            ? false
-            : entry.compatibility === "breaking"
-                ? true
-                : null,
+        breaking: compatibilityBreaking(entry.compatibility),
         channel: "homebrew",
     }))
         .sort((left, right) => compareVersion(right.version, left.version));

package/dist/src/mirror.js

@@ -278,6 +278,8 @@ export function refreshMirror(identity) {
     const source = record.path;
     if (!fs.existsSync(source))
         throw new MirrorError("unknown", `knodin remote: mirror ${identity} is registered but its clone is missing; remove and re-add it`);
+    if (fs.realpathSync(source) !== fs.realpathSync(mirrorSourcePath(identity)))
+        throw new MirrorError("unknown", "knodin remote: registered clone is outside its managed source directory; restore the registry before refresh");
     runGit(["fetch", "--depth", "1", "origin"], record.url, source);
     runGit(["reset", "--hard", "FETCH_HEAD"], record.url, source);
     const sha = runGit(["rev-parse", "HEAD"], record.url, source).trim();

package/dist/src/response-budget.js

@@ -36,6 +36,9 @@ function collectStrings(value, path = "$") {
 }
 const PROTECTED_CONTRACT_KEYS = new Set([
     "identity",
+    "chainIdentity",
+    "candidateReason",
+    "partialScope",
     "symbol",
     "file",
     "filePath",
@@ -70,7 +73,10 @@ function coveragePreviews(value) {
     return found;
 }
 function isTruncatableDetail(entry) {
-    return (!entry.path.startsWith("$/flowAnalysis/limitations/") &&
+    return (!entry.path.startsWith("$/platformEntry/") &&
+        !entry.path.startsWith("$/deadCodeAnalysis/rootReachability/") &&
+        !entry.path.startsWith("$/deadCodeAnalysis/platformEntries/") &&
+        !entry.path.startsWith("$/flowAnalysis/limitations/") &&
         !entry.path.startsWith("$/sharedIndex/") &&
         !COVERAGE_SCALAR_PATH.test(entry.path) &&
         !IMPACT_CONTRACT_PATH.test(entry.path) &&
@@ -154,6 +160,9 @@ function truncatePayloadToBytes(root, byteLimit) {
         const candidate = collectArrays(root)
             .filter((entry) => !entry.path.startsWith("$/responseBudget") &&
             !PROTECTED_CONTRACT_ARRAY_PATHS.has(entry.path) &&
+            !entry.path.startsWith("$/platformEntry/") &&
+            !entry.path.startsWith("$/deadCodeAnalysis/rootReachability/") &&
+            !entry.path.startsWith("$/deadCodeAnalysis/platformEntries/") &&
             entry.value.length > 0)
             .sort((a, b) => bytes(b.value) - bytes(a.value))[0];
         if (!candidate)
@@ -273,7 +282,10 @@ export function applyResponseBudget(value, operation, request, defaults) {
     for (const entry of reportedTotals)
         totals[entry.path] = entry.value.length;
     for (const entry of initialArrays) {
-        if (entry.value.length > itemLimit) {
+        if (!entry.path.startsWith("$/platformEntry/") &&
+            !entry.path.startsWith("$/deadCodeAnalysis/rootReachability/") &&
+            !entry.path.startsWith("$/deadCodeAnalysis/platformEntries/") &&
+            entry.value.length > itemLimit) {
             entry.value.splice(itemLimit);
             truncated = true;
         }

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

@@ -195,15 +195,25 @@ export async function restoreSharedIndex(options) {
         };
     }
     finally {
-        lease?.release();
-        if (candidate && !promoted) {
+        try {
+            lease?.release();
+            if (candidate && !promoted) {
+                try {
+                    await options.engine.discardCandidate(candidate);
+                }
+                catch {
+                    // Candidate cleanup never justifies touching the active graph.
+                }
+            }
+        }
+        finally {
             try {
-                await options.engine.discardCandidate(candidate);
+                lifecycleLease?.release();
             }
-            catch {
-                // Candidate cleanup never justifies touching the active graph.
+            finally {
+                if (promoted)
+                    options.engine.finalizePromotedStorage?.(options.repo);
             }
         }
-        lifecycleLease?.release();
     }
 }

package/dist/src/storage-budget.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+/** Additional free space kept beyond scratch: 512 MiB, including for empty graphs. */
+export const DEFAULT_STORAGE_RESERVE_BYTES = 512 * 1024 * 1024;
+/** Conservative scratch allowance; allocation is not a promise of reclaimable APFS extents. */
+export const DEFAULT_STORAGE_SCRATCH_FACTOR = 2;
+export class StorageBudgetError extends Error {
+    constructor(message, options) {
+        super(`Storage capacity preflight refused: ${message}. Free disk space or resolve the measurement error, then retry.`, options);
+        this.name = "StorageBudgetError";
+    }
+}
+function safeBytes(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new StorageBudgetError(`${label} is unknown or outside safe integer bounds`);
+    return value;
+}
+function stateRoot(directory) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new StorageBudgetError("state directory must be a regular nonsymlink directory");
+    return fs.realpathSync(directory);
+}
+/** At most 32 ancestor metadata probes; never creates a directory to measure capacity. */
+function capacityDirectory(directory) {
+    let current = path.resolve(directory);
+    for (let attempts = 0; attempts < 32; attempts++) {
+        try {
+            // The state directory itself must not be a symlink. For a new state,
+            // existing ancestors may be repository aliases: capacity is measured
+            // on their canonical filesystem without creating or trusting state.
+            const root = stateRoot(attempts === 0 ? current : fs.realpathSync(current));
+            return root;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+    }
+    throw new StorageBudgetError("no safe existing capacity directory within 32 ancestors");
+}
+/** Bounded metadata-only measurement of exactly DB, WAL and SHM; missing members are allowed. */
+export function measureDatabaseFamily(stateDirectory, databasePath) {
+    try {
+        let root;
+        try {
+            root = stateRoot(stateDirectory);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            capacityDirectory(stateDirectory);
+            if (path.dirname(path.resolve(databasePath)) !== path.resolve(stateDirectory))
+                throw new StorageBudgetError("database family is outside its state directory");
+            return { apparentBytes: 0, allocatedBytes: 0, fileCount: 0 };
+        }
+        const target = path.resolve(databasePath);
+        if (fs.realpathSync(path.dirname(target)) !== root)
+            throw new StorageBudgetError("database family is outside its state directory");
+        let apparentBytes = 0;
+        let allocatedBytes = 0;
+        let fileCount = 0;
+        for (const suffix of ["", "-wal", "-shm"]) {
+            const member = `${target}${suffix}`;
+            let stat;
+            try {
+                stat = fs.lstatSync(member);
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            if (!stat.isFile() || stat.isSymbolicLink() || path.dirname(fs.realpathSync(member)) !== root)
+                throw new StorageBudgetError("database family must contain only contained regular nonsymlink files");
+            apparentBytes = safeBytes(apparentBytes + safeBytes(stat.size, "file size"), "family size");
+            if (typeof stat.blocks !== "number" || !Number.isSafeInteger(stat.blocks) || stat.blocks < 0)
+                allocatedBytes = null;
+            else if (allocatedBytes !== null)
+                allocatedBytes = safeBytes(allocatedBytes + safeBytes(stat.blocks * 512, "allocated file size"), "allocated family size");
+            fileCount++;
+        }
+        return { apparentBytes, allocatedBytes, fileCount };
+    }
+    catch (error) {
+        if (error instanceof StorageBudgetError)
+            throw error;
+        throw new StorageBudgetError("cannot measure database family", { cause: error });
+    }
+}
+/** bavail reflects blocks usable by this process, unlike privileged free-block totals. */
+export function measureAvailableBytes(stateDirectory, statfs = (directory) => fs.statfsSync(directory, { bigint: true })) {
+    try {
+        const result = statfs(capacityDirectory(stateDirectory));
+        if (typeof result.bavail !== "bigint" ||
+            typeof result.bsize !== "bigint" ||
+            result.bavail < 0n ||
+            result.bsize <= 0n)
+            throw new StorageBudgetError("filesystem available capacity is unknown");
+        const bytes = result.bavail * result.bsize;
+        if (bytes > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new StorageBudgetError("filesystem capacity exceeds safe integer bounds");
+        return Number(bytes);
+    }
+    catch (error) {
+        if (error instanceof StorageBudgetError)
+            throw error;
+        throw new StorageBudgetError("filesystem free-space measurement failed or is unsupported", {
+            cause: error,
+        });
+    }
+}
+/** Read-only preflight, not a reservation: callers must still handle ENOSPC and races. */
+export function assertStorageCapacity(options, dependencies = {}) {
+    try {
+        const reserveBytes = safeBytes(options.reserveBytes ?? DEFAULT_STORAGE_RESERVE_BYTES, "reserve bytes");
+        const scratchFactor = options.scratchFactor ?? DEFAULT_STORAGE_SCRATCH_FACTOR;
+        if (!Number.isSafeInteger(scratchFactor) || scratchFactor < 1)
+            throw new StorageBudgetError("scratch factor must be a positive safe integer");
+        const family = (dependencies.measureFamily ?? measureDatabaseFamily)(options.stateDirectory, options.databasePath);
+        if (family.allocatedBytes === null)
+            throw new StorageBudgetError("allocated family size is unknown on this filesystem");
+        const base = Math.max(safeBytes(family.apparentBytes, "family size"), safeBytes(family.allocatedBytes, "allocated family size"));
+        const requiredBytes = safeBytes(safeBytes(base * scratchFactor, "scratch bytes") + reserveBytes, "required bytes");
+        const availableBytes = safeBytes((dependencies.measureFree ?? measureAvailableBytes)(options.stateDirectory), "available bytes");
+        if (availableBytes < requiredBytes)
+            throw new StorageBudgetError(`${options.operation} requires ${requiredBytes} additional bytes but only ${availableBytes} bytes are available`);
+        return {
+            operation: options.operation,
+            family,
+            availableBytes,
+            requiredBytes,
+            reserveBytes,
+            scratchFactor,
+        };
+    }
+    catch (error) {
+        if (error instanceof StorageBudgetError)
+            throw error;
+        throw new StorageBudgetError("capacity measurement failed", { cause: error });
+    }
+}