knodin 0.12.2 → 0.13.1

package/dist/src/storage-inventory.js

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+import { listBackups } from "./backup-retention.js";
+import { resolveDbPath, resolveStateDir } from "./engine/state-paths.js";
+import { measureDatabaseFamily } from "./storage-budget.js";
+const EXACT_BACKUP = /^db\.sqlite\.backup\.\d{13}\.[0-9a-f]{8}$/;
+function category() {
+    return {
+        count: 0,
+        fileCount: 0,
+        apparentBytes: 0,
+        allocatedBytes: 0,
+        measuredApparentBytes: 0,
+        truncated: false,
+        errors: [],
+    };
+}
+function unknown(target, error, truncated = false) {
+    target.apparentBytes = null;
+    target.allocatedBytes = null;
+    target.errors.push(error);
+    target.truncated ||= truncated;
+}
+function sum(left, right) {
+    if (left === null || right === null)
+        return null;
+    const total = left + right;
+    return Number.isSafeInteger(total) && total >= 0 ? total : null;
+}
+function regularMetadata(target, root) {
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink() || path.dirname(fs.realpathSync(target)) !== root)
+        throw new Error(`unsafe/nonregular file: ${target}`);
+    return {
+        path: target,
+        apparentBytes: Number.isSafeInteger(stat.size) && stat.size >= 0 ? stat.size : null,
+        allocatedBytes: Number.isSafeInteger(stat.blocks) &&
+            stat.blocks >= 0 &&
+            Number.isSafeInteger(stat.blocks * 512)
+            ? stat.blocks * 512
+            : null,
+        modifiedAtMs: stat.mtimeMs,
+    };
+}
+function add(target, file) {
+    target.fileCount++;
+    target.apparentBytes = sum(target.apparentBytes, file.apparentBytes);
+    target.allocatedBytes = sum(target.allocatedBytes, file.allocatedBytes);
+    target.measuredApparentBytes =
+        sum(target.measuredApparentBytes, file.apparentBytes) ?? target.measuredApparentBytes;
+    if (file.apparentBytes === null || file.allocatedBytes === null)
+        target.errors.push(`unknown size/allocation: ${file.path}`);
+}
+function safeDirectory(target, parent) {
+    const stat = fs.lstatSync(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error(`unsafe/non-directory: ${target}`);
+    const real = fs.realpathSync(target);
+    if (parent && path.dirname(real) !== parent)
+        throw new Error(`directory escapes inventory root: ${target}`);
+    return real;
+}
+function boundedEntries(directory, limit) {
+    const stream = fs.opendirSync(directory);
+    const entries = [];
+    try {
+        for (let index = 0; index < limit; index++) {
+            const entry = stream.readSync();
+            if (!entry)
+                return { entries, truncated: false };
+            entries.push(entry);
+        }
+        return { entries, truncated: stream.readSync() !== null };
+    }
+    finally {
+        stream.closeSync();
+    }
+}
+/** Repository-local metadata only. Never indexes, hashes, follows links, creates or deletes files. */
+export function inventoryRepositoryStorage(repository, dependencies = {}) {
+    const requestedRepository = path.resolve(repository);
+    let repo = requestedRepository;
+    try {
+        repo = fs.realpathSync(repo);
+    }
+    catch {
+        /* Missing roots retain unknown metadata results. */
+    }
+    const state = resolveStateDir(repo);
+    const categories = {
+        active: category(),
+        backups: category(),
+        candidates: category(),
+        cacheAndOther: category(),
+    };
+    const files = [];
+    const candidates = [];
+    const result = {
+        schemaVersion: 1,
+        repository: requestedRepository,
+        stateDirectory: state,
+        scope: state === path.join(repo, ".knodin")
+            ? "repository-local"
+            : "mirror-state",
+        categories,
+        files,
+        candidates,
+        outOfScope: {
+            classification: "external-not-backups",
+            mirrors: null,
+            harnessDirectories: null,
+            count: null,
+            allocatedBytes: null,
+            reason: "External mirrors, harnesses, sibling projects and worktrees are not scanned; this is not a whole-system count.",
+        },
+    };
+    let root;
+    try {
+        root = safeDirectory(state);
+    }
+    catch (error) {
+        for (const target of Object.values(categories))
+            unknown(target, String(error));
+        return result;
+    }
+    try {
+        const measured = (dependencies.measureFamily ?? measureDatabaseFamily)(state, resolveDbPath(repo));
+        Object.assign(categories.active, {
+            count: measured.fileCount > 0 ? 1 : 0,
+            fileCount: measured.fileCount,
+            apparentBytes: measured.apparentBytes,
+            allocatedBytes: measured.allocatedBytes,
+            measuredApparentBytes: measured.apparentBytes,
+        });
+        if (measured.allocatedBytes === null)
+            categories.active.errors.push("active database allocation unavailable");
+    }
+    catch (error) {
+        unknown(categories.active, String(error));
+    }
+    let stateEntries;
+    try {
+        stateEntries = boundedEntries(state, 1024);
+    }
+    catch (error) {
+        for (const target of [categories.backups, categories.candidates, categories.cacheAndOther])
+            unknown(target, String(error));
+        return result;
+    }
+    if (stateEntries.truncated) {
+        unknown(categories.backups, "state directory exceeds 1024-entry inventory bound; backup listing skipped", true);
+        unknown(categories.cacheAndOther, "state directory exceeds 1024-entry inventory bound", true);
+        unknown(categories.candidates, "candidate root may be outside bounded state entries", true);
+    }
+    else {
+        try {
+            if (state !== path.join(repo, ".knodin")) {
+                for (const entry of stateEntries.entries) {
+                    if (!EXACT_BACKUP.test(entry.name))
+                        continue;
+                    try {
+                        add(categories.backups, regularMetadata(path.join(state, entry.name), root));
+                        categories.backups.count++;
+                    }
+                    catch (error) {
+                        unknown(categories.backups, String(error));
+                    }
+                }
+            }
+            else {
+                const backups = (dependencies.listBackups ?? listBackups)([repo], {
+                    depth: 0,
+                    includeRegistry: false,
+                });
+                categories.backups.count = backups.count;
+                for (const backup of backups.backups)
+                    add(categories.backups, {
+                        path: backup.path,
+                        apparentBytes: backup.bytes,
+                        allocatedBytes: backup.allocatedBytes,
+                        modifiedAtMs: backup.modifiedAtMs,
+                    });
+                for (const skipped of backups.skipped)
+                    unknown(categories.backups, `${skipped.reason}: ${skipped.path ?? skipped.repository}`);
+            }
+        }
+        catch (error) {
+            unknown(categories.backups, String(error));
+        }
+    }
+    for (const entry of stateEntries.entries) {
+        if (["db.sqlite", "db.sqlite-wal", "db.sqlite-shm"].includes(entry.name) ||
+            EXACT_BACKUP.test(entry.name))
+            continue;
+        const target = path.join(state, entry.name);
+        if (entry.name === "candidates") {
+            try {
+                const candidateRoot = safeDirectory(target, root);
+                const listed = boundedEntries(target, 256);
+                if (listed.truncated)
+                    unknown(categories.candidates, "candidate directory exceeds 256-entry bound", true);
+                for (const candidate of listed.entries) {
+                    const candidatePath = path.join(target, candidate.name);
+                    try {
+                        if (!/^candidate-[A-Za-z0-9_-]+$/.test(candidate.name))
+                            throw new Error(`unexpected candidate entry: ${candidatePath}`);
+                        const candidateDirectory = safeDirectory(candidatePath, candidateRoot);
+                        categories.candidates.count++;
+                        const record = { path: candidatePath, files: [] };
+                        candidates.push(record);
+                        // At most five named metadata probes; never traverse candidate contents.
+                        for (const name of [
+                            "db.sqlite",
+                            "db.sqlite-wal",
+                            "db.sqlite-shm",
+                            "status-audit-v1.json",
+                            "candidate-owner.json",
+                        ]) {
+                            try {
+                                const file = regularMetadata(path.join(candidatePath, name), candidateDirectory);
+                                add(categories.candidates, file);
+                                record.files.push(file);
+                            }
+                            catch (error) {
+                                if (error.code !== "ENOENT")
+                                    unknown(categories.candidates, String(error));
+                            }
+                        }
+                        const contents = boundedEntries(candidatePath, 5);
+                        if (contents.truncated ||
+                            contents.entries.some((child) => ![
+                                "db.sqlite",
+                                "db.sqlite-wal",
+                                "db.sqlite-shm",
+                                "status-audit-v1.json",
+                                "candidate-owner.json",
+                            ].includes(child.name)))
+                            unknown(categories.candidates, `unmeasured unexpected candidate contents: ${candidatePath}`, contents.truncated);
+                    }
+                    catch (error) {
+                        unknown(categories.candidates, String(error));
+                    }
+                }
+            }
+            catch (error) {
+                unknown(categories.candidates, String(error));
+            }
+            continue;
+        }
+        categories.cacheAndOther.count++;
+        try {
+            const file = regularMetadata(target, root);
+            add(categories.cacheAndOther, file);
+            files.push(file);
+        }
+        catch (error) {
+            unknown(categories.cacheAndOther, `nested, unsafe or unmeasured entry (not a backup): ${target}: ${String(error)}`);
+        }
+    }
+    return result;
+}
+/** Compact CLI-compatible name for the same repository-bounded inventory. */
+export const inventoryStorage = inventoryRepositoryStorage;

package/dist/src/storage-management.js

@@ -0,0 +1,204 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { maintainPromotionBackups, pruneBackups, retentionAppliesToRepository, retentionStatus, } from "./backup-retention.js";
+import { acquireRepairLease } from "./repair-lease.js";
+import { assertStoragePolicyWritable, DEFAULT_STORAGE_POLICY as DEFAULT_POLICY, readLocalStoragePolicy as localPolicy, STORAGE_POLICY_NAME as POLICY_NAME, storagePolicyStateDirectory as stateDirectory, validateStoragePolicy as validatePolicy, } from "./storage-policy-contract.js";
+/** Read only. Legacy stores remain unmanaged; malformed/unsafe policy fails closed. */
+export function resolveStoragePolicy(repository, options = {}) {
+    const local = localPolicy(repository);
+    if (local)
+        return local;
+    const installed = retentionStatus(options);
+    if (installed.status === "attention-required")
+        throw new Error(`storage-policy: unhealthy global retention (${installed.issues.join(", ")})`);
+    const global = installed.policy;
+    if (!global || installed.status !== "healthy")
+        return null;
+    const applies = retentionAppliesToRepository(repository, global);
+    // Existing age-only consent is not consent for aggressive count/byte eviction.
+    if (!applies || global.maxCount === undefined || global.maxAllocatedBytes === undefined)
+        return null;
+    return validatePolicy({
+        ...DEFAULT_POLICY,
+        dryRun: global.dryRun,
+        retentionDays: global.retentionDays,
+        keepNewest: Math.max(1, global.keepNewest),
+        maxCount: global.maxCount,
+        maxAllocatedBytes: global.maxAllocatedBytes,
+    });
+}
+function writePolicy(repository, policy, overwrite) {
+    assertStoragePolicyWritable(repository);
+    const state = stateDirectory(repository, true);
+    fs.mkdirSync(state, { mode: 0o700, recursive: true });
+    stateDirectory(repository);
+    const before = fs.lstatSync(state);
+    const target = path.join(state, POLICY_NAME);
+    const temporary = path.join(state, `.${POLICY_NAME}.${crypto.randomUUID()}.tmp`);
+    try {
+        const descriptor = fs.openSync(temporary, "wx", 0o600);
+        try {
+            fs.writeFileSync(descriptor, `${JSON.stringify(policy)}\n`);
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+        const current = fs.lstatSync(state);
+        if (current.isSymbolicLink() || current.dev !== before.dev || current.ino !== before.ino)
+            throw new Error("storage-policy: state directory changed during write");
+        // Re-read before an explicitly consented replacement; malformed or symlink
+        // policies must not silently become defaults even on an apply request.
+        if (overwrite) {
+            localPolicy(repository);
+            fs.renameSync(temporary, target);
+        }
+        else
+            fs.linkSync(temporary, target); // atomic no-overwrite publication
+        try {
+            const directory = fs.openSync(state, "r");
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+        }
+        catch (error) {
+            // Windows cannot open/fsync directories on every supported filesystem.
+            // Keep actual I/O failures visible; the policy file itself is already synced.
+            if (process.platform !== "win32" ||
+                !["EPERM", "EINVAL", "ENOTSUP", "EISDIR"].includes(error.code ?? ""))
+                throw error;
+        }
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch {
+            // Temporary residue must not mask the original error or turn an
+            // already published policy into a failed transaction.
+        }
+    }
+}
+/** Caller must know this was a first successful index/promotion, never a legacy upgrade. */
+export function initializeStoragePolicy(repository, options = {}) {
+    assertStoragePolicyWritable(repository);
+    const existing = resolveStoragePolicy(repository, options);
+    if (existing)
+        return { status: "existing", policy: existing };
+    const global = retentionStatus(options).policy;
+    // New stores get bounded defaults, but an applicable older explicit global
+    // dry-run is still a user's safety preference, not permission to apply.
+    const policy = {
+        ...DEFAULT_POLICY,
+        dryRun: Boolean(global?.dryRun && retentionAppliesToRepository(repository, global)),
+    };
+    writePolicy(repository, policy, false);
+    return { status: "initialized", policy };
+}
+export function configureStoragePolicy(repository, options, globalOptions = {}) {
+    if (options.apply) {
+        assertStoragePolicyWritable(repository);
+        // Reject unsafe state routing before the lease writes coordination metadata.
+        // The policy is resolved again under the lease before publication.
+        resolveStoragePolicy(repository, globalOptions);
+        const lease = acquireRepairLease(repository, "storage-policy-configuration");
+        try {
+            return configureStoragePolicyUnderLease(repository, options, globalOptions);
+        }
+        finally {
+            lease.release();
+        }
+    }
+    return configureStoragePolicyUnderLease(repository, options, globalOptions);
+}
+function configureStoragePolicyUnderLease(repository, options, globalOptions) {
+    const current = resolveStoragePolicy(repository, globalOptions);
+    const { apply, ...changes } = options;
+    const global = retentionStatus(globalOptions).policy;
+    const defaults = {
+        ...DEFAULT_POLICY,
+        dryRun: Boolean(global?.dryRun && retentionAppliesToRepository(repository, global)),
+    };
+    const policy = validatePolicy({ ...(current ?? defaults), ...changes, schemaVersion: 1 });
+    const classification = current ? "managed" : "legacy-unmanaged";
+    if (!apply)
+        return { status: "preview", classification, consentNeeded: true, current, policy };
+    writePolicy(repository, policy, true);
+    return { status: "configured", classification, consentNeeded: false, current, policy };
+}
+/** Call after releasing the lifecycle lease. Cleanup cannot invalidate durable promotion. */
+export function postOperationStorageMaintenance(repository, options = {}) {
+    try {
+        assertStoragePolicyWritable(repository);
+        const policy = resolveStoragePolicy(repository, options);
+        if (!policy)
+            return {
+                status: "legacy-preview",
+                warnings: [
+                    "Storage is unmanaged; run `knodin backups policy preview <repo>`, then explicitly consent with `knodin backups policy apply <repo>` before automatic cleanup.",
+                ],
+                policy: null,
+            };
+        const result = maintainPromotionBackups(repository, policy, (repo) => resolveStoragePolicy(repo, options));
+        const overQuota = "result" in result && result.result?.quotas.some((quota) => quota.overQuota !== false);
+        const cleanupWarnings = "result" in result && result.result
+            ? result.result.skipped.map((entry) => entry.reason)
+            : "reason" in result
+                ? [result.reason]
+                : [];
+        return {
+            ...result,
+            policy,
+            warnings: [
+                ...cleanupWarnings,
+                ...(overQuota
+                    ? [
+                        "Protected or unmeasured storage remains over budget; refuse unsafe future allocation until space is established.",
+                    ]
+                    : []),
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            status: "failed",
+            warnings: [error instanceof Error ? error.message : String(error)],
+            policy: null,
+        };
+    }
+}
+/** Read-only allocation fence: protected/unknown quotas cannot be hand-waved away. */
+export function assertManagedStorageAllocation(repository, options = {}) {
+    const policy = resolveStoragePolicy(repository, options);
+    if (!policy?.enabled)
+        return policy;
+    // A safely absent state directory is a known-empty first store, not a
+    // successful empty discovery of an existing (possibly external) store.
+    try {
+        fs.lstatSync(stateDirectory(repository, true));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return policy;
+        throw error;
+    }
+    const preview = pruneBackups([fs.realpathSync(repository)], {
+        depth: 0,
+        includeRegistry: false,
+        apply: false,
+        protectRecoverable: true,
+        retentionDays: policy.retentionDays,
+        keepNewest: policy.keepNewest,
+        maxCount: policy.maxCount,
+        maxAllocatedBytes: policy.maxAllocatedBytes,
+    });
+    if (preview.quotas.some((quota) => quota.overQuota !== false) ||
+        preview.skipped.length > 0 ||
+        preview.quotas.length !== 1)
+        throw new Error("knodin storage: protected backup storage exceeds its budget or allocated bytes are unknown; preview `knodin backups prune <repo>` and explicitly resolve the quota before allocating another candidate. Active and recoverable databases were preserved.");
+    return policy;
+}

package/dist/src/storage-policy-contract.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import { lookupMirror, resolveStateDir } from "./engine/state-paths.js";
+export const MANAGED_BACKUP_DEFAULTS = Object.freeze({
+    enabled: true,
+    dryRun: false,
+    retentionDays: 3,
+    keepNewest: 1,
+    maxCount: 1,
+    maxAllocatedBytes: 1_073_741_824,
+    minFreeBytes: 536_870_912,
+});
+export const STORAGE_POLICY_NAME = "storage-policy.json";
+export const DEFAULT_STORAGE_POLICY = {
+    schemaVersion: 1,
+    ...MANAGED_BACKUP_DEFAULTS,
+};
+const KEYS = [
+    "schemaVersion",
+    "enabled",
+    "dryRun",
+    "retentionDays",
+    "keepNewest",
+    "maxCount",
+    "maxAllocatedBytes",
+    "minFreeBytes",
+];
+function missing(error) {
+    return error.code === "ENOENT";
+}
+function policyRepository(repository) {
+    const canonical = fs.realpathSync(repository);
+    const mirror = lookupMirror(repository);
+    return { path: mirror?.path ?? canonical, mirror: Boolean(mirror) };
+}
+export function storagePolicyStateDirectory(repository, allowMissing = false) {
+    const repo = fs.realpathSync(repository);
+    if (!fs.lstatSync(repo).isDirectory())
+        throw new Error("storage-policy: repository is not a directory");
+    const state = resolveStateDir(policyRepository(repository).path);
+    try {
+        const stat = fs.lstatSync(state);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error("storage-policy: unsafe state directory");
+    }
+    catch (error) {
+        if (!allowMissing || !missing(error))
+            throw error;
+    }
+    return state;
+}
+export function assertStoragePolicyWritable(repository) {
+    if (policyRepository(repository).mirror)
+        throw new Error("storage-policy: mirror repositories are read-only");
+}
+export function validateStoragePolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("storage-policy: malformed policy");
+    const record = value;
+    if (Object.keys(record).length !== KEYS.length ||
+        Object.keys(record).some((key) => !KEYS.includes(key)) ||
+        record.schemaVersion !== 1 ||
+        typeof record.enabled !== "boolean" ||
+        typeof record.dryRun !== "boolean")
+        throw new Error("storage-policy: invalid policy schema");
+    for (const key of [
+        "retentionDays",
+        "keepNewest",
+        "maxCount",
+        "maxAllocatedBytes",
+        "minFreeBytes",
+    ])
+        if (!Number.isSafeInteger(record[key]) || record[key] < 0)
+            throw new Error(`storage-policy: invalid ${key}`);
+    if (record.retentionDays > 3650 ||
+        record.keepNewest < 1 ||
+        record.keepNewest > 1000)
+        throw new Error("storage-policy: invalid retention bounds");
+    return record;
+}
+/** Shared bounded, no-follow parser; importing this module has no cleanup side effects. */
+export function readLocalStoragePolicy(repository) {
+    const target = path.join(storagePolicyStateDirectory(repository, true), STORAGE_POLICY_NAME);
+    let stat;
+    try {
+        stat = fs.lstatSync(target);
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size <= 0 || stat.size > 16_384)
+        throw new Error("storage-policy: unsafe policy file");
+    const descriptor = fs.openSync(target, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+        const opened = fs.fstatSync(descriptor);
+        if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size)
+            throw new Error("storage-policy: policy changed during read");
+        const buffer = Buffer.alloc(stat.size + 1);
+        const read = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+        const final = fs.fstatSync(descriptor);
+        const current = fs.lstatSync(target);
+        if (read !== stat.size ||
+            final.size !== stat.size ||
+            final.mtimeMs !== stat.mtimeMs ||
+            final.ctimeMs !== stat.ctimeMs ||
+            !current.isFile() ||
+            current.isSymbolicLink() ||
+            current.dev !== stat.dev ||
+            current.ino !== stat.ino ||
+            current.size !== stat.size ||
+            current.mtimeMs !== stat.mtimeMs ||
+            current.ctimeMs !== stat.ctimeMs)
+            throw new Error("storage-policy: policy changed during read");
+        return validateStoragePolicy(JSON.parse(buffer.subarray(0, read).toString("utf8")));
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}