@theford/runly 0.0.0-stage → 0.20.0

package/dist/core/retention.js

@@ -0,0 +1,322 @@
+/**
+ * Disk retention: nothing runly writes may grow forever. Called from the
+ * daemon sweeper (~10 min cadence); every function is idempotent, best-effort,
+ * and unit-testable in isolation.
+ */
+import { readdirSync, statSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { templatesRoot, envsRoot, worktreesRoot } from './paths.js';
+import { logEvent } from './events.js';
+import { cmdTimeoutS, runBounded } from './exec.js';
+import { rotateIfOver } from './logs.js';
+import { hasOtherTemplateOwner, isPrivateTemplateFile, isSharedTemplateDir, parseBakedMarker, sharedTemplateDir, templateProject, withBakeLock } from '../drivers/datastores.js';
+import { readWorktreeTemplates } from './tree-ledger.js';
+const entriesOf = (dir) => {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Service logs past the cap are rotated once (decision 0038): `<name>.log`
+ * becomes `<name>.log.1`, replacing the previous rotation. The writer rotates
+ * as it writes; this is the backstop for a file it never reached (a writer
+ * from an older daemon, or a log that grew between restarts). Only `*.log`
+ * files are touched.
+ */
+export function truncateLogs(p, root = envsRoot()) {
+    let rotated = 0;
+    for (const envDir of entriesOf(root)) {
+        const logDir = join(root, envDir, 'logs');
+        for (const logFile of entriesOf(logDir)) {
+            if (!logFile.endsWith('.log'))
+                continue;
+            if (rotateIfOver(join(logDir, logFile), p.logCapBytes))
+                rotated++;
+        }
+    }
+    return rotated;
+}
+/** The group a template file belongs to: `<datastore>-<preset>` before the content key. */
+const templateGroup = (file) => {
+    const at = file.lastIndexOf('@');
+    return at > 0 ? file.slice(0, at) : '';
+};
+/**
+ * What retention (and `pool doctor`, without the grace) does with each
+ * template in one templates dir (decisions 0037, 0044):
+ *
+ * - per datastore and preset, the newest `keep` are current — in a stack dir
+ *   that can be bound again, or in a `<name>@shared` dir while any worktree of
+ *   that name can;
+ * - a template a row or a live worktree's record references stays;
+ * - a private (`--pristine`) template is never "current": it stays only while
+ *   referenced;
+ * - a per-worktree template whose file name the shared dir also holds is a
+ *   duplicate of it (the migration adopted it), never "current" either;
+ * - anything else goes once older than `grace`.
+ */
+export function templateVerdicts(dir, files, refs, keepNewest, graceMs, sharedFiles = new Set()) {
+    const alive = refs.stackAlive(dir);
+    const keep = alive ? keepNewest : 0;
+    const seen = new Map();
+    const out = [];
+    for (const { f, mtime } of [...files].sort((a, b) => b.mtime - a.mtime)) {
+        const priv = isPrivateTemplateFile(f);
+        const duplicate = !priv && !isSharedTemplateDir(dir) && sharedFiles.has(f);
+        let current = false;
+        if (!priv && !duplicate) {
+            const group = templateGroup(f);
+            const rank = seen.get(group) ?? 0;
+            seen.set(group, rank + 1);
+            current = rank < keep;
+        }
+        if (current)
+            out.push({ f, keep: true, why: 'current' });
+        else if (refs.referenced.has(`${dir}/${f}`))
+            out.push({ f, keep: true, why: 'referenced' });
+        else if (Date.now() - mtime < graceMs)
+            out.push({ f, keep: true, why: 'grace' });
+        else
+            out.push({ f, keep: false, why: priv ? 'private' : duplicate ? 'duplicate' : alive ? 'superseded' : 'dead' });
+    }
+    return out;
+}
+/** The template files of one dir with their mtimes (dot-files — `.root` — excluded). */
+export function templateFiles(dir) {
+    return entriesOf(dir)
+        .filter((f) => !f.startsWith('.'))
+        .map((f) => {
+        try {
+            return { f, mtime: statSync(join(dir, f)).mtimeMs };
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((x) => x !== null);
+}
+/** The file names in the shared dir of `dir`'s project (empty for a shared dir itself). */
+export function sharedFilesFor(dir, root = templatesRoot()) {
+    if (isSharedTemplateDir(dir))
+        return new Set();
+    return new Set(entriesOf(join(root, sharedTemplateDir(templateProject(dir)))));
+}
+/**
+ * Templates are collected by reference (decisions 0037, 0044): see
+ * `templateVerdicts`. A marker for a server-side template is dropped WITH its
+ * database (its persisted drop command), unless another marker still names it.
+ */
+export async function pruneTemplates(p, root = templatesRoot(), refs = { referenced: new Set(), stackAlive: () => true }) {
+    let pruned = 0;
+    const grace = p.templateGraceMs ?? 0;
+    for (const stackDir of entriesOf(root)) {
+        const dir = join(root, stackDir);
+        if (!existsSync(dir))
+            continue;
+        // The dir-scoped bake lock (the dir name IS the lock key — a stack id or
+        // `<name>@shared`): pruning was the one remaining writer mutating this
+        // dir outside it, reopening the deleted-mid-restore race the lock exists
+        // to close.
+        pruned += await withBakeLock(stackDir, async () => {
+            let count = 0;
+            for (const v of templateVerdicts(stackDir, templateFiles(dir), refs, p.templatesKeep, grace, sharedFilesFor(stackDir, root))) {
+                if (v.keep)
+                    continue;
+                const f = v.f;
+                const full = join(dir, f);
+                if (f.endsWith('.baked')) {
+                    try {
+                        const marker = parseBakedMarker(readFileSync(full, 'utf8'));
+                        // Another marker naming the same database (an adopted template's
+                        // other copy): only this marker goes, the database stays.
+                        if (!hasOtherTemplateOwner(full, marker.ns) && marker.drop) {
+                            // This command came from a manifest that may no longer exist on
+                            // disk. Re-executing it silently is the part that deserves a
+                            // record, so the state dir stays auditable.
+                            logEvent({ level: 'info', kind: 'retention', detail: `dropping baked template via persisted command from ${f}` });
+                            const r = await runBounded(marker.drop, refs.dropCwd?.(stackDir) ?? root, Math.min(60, cmdTimeoutS()));
+                            if (r.code !== 0 || r.timedOut) {
+                                // The marker is the only record that names the database: keep it
+                                // for the next sweep, and for 'runly pool doctor' to show.
+                                logEvent({ level: 'warn', kind: 'retention', detail: `the drop of template ${marker.ns} (${f}) did not confirm (${r.timedOut ? 'timed out' : `exit ${r.code}`}) — its marker stays: ${r.output.slice(-200)}` });
+                                continue;
+                            }
+                        }
+                    }
+                    catch {
+                        /* unreadable marker — still prune the file */
+                    }
+                }
+                rmSync(full, { force: true });
+                count++;
+            }
+            // A stack dir with nothing left goes too (its `.root` record with it).
+            if (entriesOf(dir).every((f) => f.startsWith('.')))
+                rmSync(dir, { recursive: true, force: true });
+            return count;
+        });
+    }
+    return pruned;
+}
+/**
+ * Per-worktree state (decision 0032 — the trigger-file hash cache and the upkeep
+ * ledger) for a worktree that no longer exists. It must outlive every
+ * environment, because `runly warm` writes it for a worktree with none; so it
+ * goes only when its recorded root is gone AND no environment still names the
+ * stack. A missing or unreadable record is left alone: it proves nothing.
+ */
+export function pruneWorktreeState(journal, root = worktreesRoot()) {
+    let pruned = 0;
+    for (const stackId of entriesOf(root)) {
+        const dir = join(root, stackId);
+        try {
+            const recordedRoot = ['ledger.json', 'triggers.json', 'builds.json', 'templates.json']
+                .map((f) => {
+                try {
+                    return JSON.parse(readFileSync(join(dir, f), 'utf8')).root;
+                }
+                catch {
+                    return undefined;
+                }
+            })
+                .find((r) => typeof r === 'string');
+            if (recordedRoot === undefined || existsSync(recordedRoot))
+                continue;
+            if (journal.envsForStack(stackId).length > 0)
+                continue;
+            rmSync(dir, { recursive: true, force: true });
+            pruned++;
+        }
+        catch {
+            /* no readable ledger — leave it */
+        }
+    }
+    return pruned;
+}
+/**
+ * What the journal says about templates (decision 0037): the ones rows
+ * reference, and which stacks are alive. A stack no row names is alive while
+ * the worktree it was recorded for exists — recorded by its worktree state
+ * (`worktrees/<stack>/*.json`) or by the `.root` its first bake wrote next to
+ * its templates. A stack with no record at all is NOT alive (0.19): its
+ * worktree records were pruned because the worktree was gone, and treating it
+ * as alive kept the templates of every pruned worktree forever.
+ *
+ * Shared templates (decision 0044): `<name>@shared` is alive while any stack
+ * of that name is; a live worktree's `templates.json` (the template each of
+ * its datastores was last restored from) counts as a reference.
+ */
+export function templateRefs(journal, root = worktreesRoot(), templates = templatesRoot()) {
+    const referenced = new Set();
+    const named = new Set();
+    for (const env of journal.allEnvs()) {
+        named.add(env.stack);
+        for (const ref of Object.values(env.templates ?? {}))
+            referenced.add(ref);
+    }
+    for (const copy of journal.allDbCopies()) {
+        named.add(copy.stack);
+        if (copy.template)
+            referenced.add(copy.template);
+    }
+    const recordedRootOf = (stackId) => {
+        try {
+            const r = readFileSync(join(templates, stackId, '.root'), 'utf8').trim();
+            if (r)
+                return r;
+        }
+        catch {
+            /* not recorded at bake time (an older runly) */
+        }
+        for (const f of ['ledger.json', 'triggers.json', 'builds.json', 'templates.json']) {
+            try {
+                const r = JSON.parse(readFileSync(join(root, stackId, f), 'utf8')).root;
+                if (typeof r === 'string')
+                    return r;
+            }
+            catch {
+                /* next */
+            }
+        }
+        return undefined;
+    };
+    const stackAliveOne = (stackId) => {
+        if (named.has(stackId))
+            return true;
+        // No row names it: alive while the worktree it describes exists. No
+        // record at all means that worktree's records were pruned: not alive.
+        const recorded = recordedRootOf(stackId);
+        return recorded !== undefined && existsSync(recorded);
+    };
+    // A live worktree's current templates (decision 0044).
+    for (const stackId of entriesOf(root)) {
+        const rec = readWorktreeTemplates(stackId);
+        if (!rec || !existsSync(rec.root))
+            continue;
+        for (const ref of Object.values(rec.refs))
+            referenced.add(ref);
+    }
+    const projectStacks = (project) => {
+        const ids = new Set();
+        for (const id of named)
+            if (templateProject(id) === project)
+                ids.add(id);
+        for (const d of [root, templates])
+            for (const id of entriesOf(d))
+                if (!isSharedTemplateDir(id) && templateProject(id) === project)
+                    ids.add(id);
+        return [...ids];
+    };
+    const stackAlive = (stackId) => {
+        if (!isSharedTemplateDir(stackId))
+            return stackAliveOne(stackId);
+        return projectStacks(templateProject(stackId)).some(stackAliveOne);
+    };
+    const ownRoot = (stackId) => {
+        for (const env of journal.allEnvs())
+            if (env.stack === stackId)
+                return env.stackRoot;
+        try {
+            const r = readFileSync(join(templates, stackId, '.root'), 'utf8').trim();
+            if (r)
+                return r;
+        }
+        catch { /* none recorded */ }
+        return undefined;
+    };
+    const dropCwd = (stackId) => {
+        const own = ownRoot(stackId);
+        if (own !== undefined && existsSync(own))
+            return own;
+        // Stack ids are `<manifest name>-<8-char hash of the root>`; a shared dir is `<name>@shared`.
+        const project = templateProject(stackId);
+        for (const env of journal.allEnvs())
+            if (templateProject(env.stack) === project && existsSync(env.stackRoot))
+                return env.stackRoot;
+        for (const copy of journal.allDbCopies())
+            if (templateProject(copy.stack) === project && existsSync(copy.stackRoot))
+                return copy.stackRoot;
+        for (const sibling of entriesOf(templates)) {
+            if (sibling === stackId || templateProject(sibling) !== project)
+                continue;
+            const r = ownRoot(sibling);
+            if (r !== undefined && existsSync(r))
+                return r;
+        }
+        return templates;
+    };
+    return { referenced, stackAlive, dropCwd };
+}
+export async function retentionSweep(journal, p) {
+    // Templates first: they read the worktree records pruneWorktreeState removes.
+    const templates = await pruneTemplates(p, templatesRoot(), templateRefs(journal));
+    return {
+        worktrees: pruneWorktreeState(journal),
+        logs: truncateLogs(p),
+        templates,
+    };
+}
+//# sourceMappingURL=retention.js.map

package/dist/core/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../../src/core/retention.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAClF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACjL,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAKzD,MAAM,SAAS,GAAG,CAAC,GAAW,EAAY,EAAE;IAC1C,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS,EAAE,IAAI,GAAG,QAAQ,EAAE;IACvD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC1C,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,SAAS;YACxC,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC;gBAAE,OAAO,EAAE,CAAC;QACpE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAuBD,2FAA2F;AAC3F,MAAM,aAAa,GAAG,CAAC,IAAY,EAAU,EAAE;IAC7C,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACzC,CAAC,CAAC;AAMF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,KAA0C,EAC1C,IAAkB,EAClB,UAAkB,EAClB,OAAe,EACf,cAAmC,IAAI,GAAG,EAAE;IAE5C,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,SAAS,GAAG,CAAC,IAAI,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC;YAC1B,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;QACxB,CAAC;QACD,IAAI,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;aACpD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;aACvF,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;;YAC5E,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACrH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,OAAO,SAAS,CAAC,GAAG,CAAC;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACT,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;SACD,MAAM,CAAC,CAAC,CAAC,EAAqC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,IAAI,GAAG,aAAa,EAAE;IAChE,IAAI,mBAAmB,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAC/C,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,iBAAiB,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,CAA2E,EAC3E,IAAI,GAAG,aAAa,EAAE,EACtB,OAAqB,EAAE,UAAU,EAAE,IAAI,GAAG,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE;IAEtE,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,KAAK,GAAG,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC;IACrC,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAC/B,yEAAyE;QACzE,uEAAuE;QACvE,yEAAyE;QACzE,YAAY;QACZ,MAAM,IAAI,MAAM,YAAY,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;YAChD,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,KAAK,MAAM,CAAC,IAAI,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,aAAa,EAAE,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;gBAC7H,IAAI,CAAC,CAAC,IAAI;oBAAE,SAAS;gBACrB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBACd,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC1B,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACzB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,gBAAgB,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;wBAC5D,iEAAiE;wBACjE,0DAA0D;wBAC1D,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;4BAC3D,gEAAgE;4BAChE,6DAA6D;4BAC7D,4CAA4C;4BAC5C,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,sDAAsD,CAAC,EAAE,EAAE,CAAC,CAAC;4BAClH,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;4BACvG,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;gCAC/B,iEAAiE;gCACjE,2DAA2D;gCAC3D,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,wBAAwB,MAAM,CAAC,EAAE,KAAK,CAAC,sBAAsB,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;gCAChN,SAAS;4BACX,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,8CAA8C;oBAChD,CAAC;gBACH,CAAC;gBACD,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC9B,KAAK,EAAE,CAAC;YACV,CAAC;YACD,uEAAuE;YACvE,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBAAE,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAClG,OAAO,KAAK,CAAC;QACf,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,IAAI,GAAG,aAAa,EAAE;IACzE,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,CAAC,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,CAAC;iBACnF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACT,IAAI,CAAC;oBACH,OAAQ,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC,IAAI,CAAC;gBACrF,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,SAAS,CAAC;gBACnB,CAAC;YACH,CAAC,CAAC;iBACD,IAAI,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;YACnD,IAAI,YAAY,KAAK,SAAS,IAAI,UAAU,CAAC,YAAY,CAAC;gBAAE,SAAS;YACrE,IAAI,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YACvD,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,MAAM,EAAE,CAAC;QACX,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,IAAI,GAAG,aAAa,EAAE,EAAE,SAAS,GAAG,aAAa,EAAE;IAChG,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QACpC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5E,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;QACzC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,QAAQ;YAAE,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,cAAc,GAAG,CAAC,OAAe,EAAsB,EAAE;QAC7D,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACzE,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,gDAAgD;QAClD,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,CAAC,aAAa,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,CAAC,EAAE,CAAC;YAClF,IAAI,CAAC;gBACH,MAAM,CAAC,GAAI,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC,IAAI,CAAC;gBAChG,IAAI,OAAO,CAAC,KAAK,QAAQ;oBAAE,OAAO,CAAC,CAAC;YACtC,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU;YACZ,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IACF,MAAM,aAAa,GAAG,CAAC,OAAe,EAAW,EAAE;QACjD,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,oEAAoE;QACpE,sEAAsE;QACtE,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACzC,OAAO,QAAQ,KAAK,SAAS,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC,CAAC;IACF,uDAAuD;IACvD,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,aAAa,GAAG,CAAC,OAAe,EAAY,EAAE;QAClD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,KAAK,MAAM,EAAE,IAAI,KAAK;YAAE,IAAI,eAAe,CAAC,EAAE,CAAC,KAAK,OAAO;gBAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzE,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;YAAE,KAAK,MAAM,EAAE,IAAI,SAAS,CAAC,CAAC,CAAC;gBAAE,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC,IAAI,eAAe,CAAC,EAAE,CAAC,KAAK,OAAO;oBAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/I,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,OAAe,EAAW,EAAE;QAC9C,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC;YAAE,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;QACjE,OAAO,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrE,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,OAAe,EAAsB,EAAE;QACtD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE;YAAE,IAAI,GAAG,CAAC,KAAK,KAAK,OAAO;gBAAE,OAAO,GAAG,CAAC,SAAS,CAAC;QACrF,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACzE,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAClB,CAAC;QAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,OAAe,EAAU,EAAE;QAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,GAAG,KAAK,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACrD,8FAA8F;QAC9F,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACzC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE;YAAE,IAAI,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC;gBAAE,OAAO,GAAG,CAAC,SAAS,CAAC;QACnI,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE;YAAE,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;gBAAE,OAAO,IAAI,CAAC,SAAS,CAAC;QAC3I,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,IAAI,OAAO,KAAK,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,KAAK,OAAO;gBAAE,SAAS;YAC1E,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;YAC3B,IAAI,CAAC,KAAK,SAAS,IAAI,UAAU,CAAC,CAAC,CAAC;gBAAE,OAAO,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAgB,EAChB,CAAS;IAET,8EAA8E;IAC9E,MAAM,SAAS,GAAG,MAAM,cAAc,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAClF,OAAO;QACL,SAAS,EAAE,kBAAkB,CAAC,OAAO,CAAC;QACtC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;QACrB,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/core/sleep.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cap on a kernel-reported sleep gap. A pardon shifts EVERY lease and idle
+ * deadline by the gap, so a corrupt or absurd record (bad clock at sleep time,
+ * garbage sysctl) must not push deadlines out by years. Past the cap we prefer
+ * letting deadlines lapse — losing a lease is designed to be worthless (§10):
+ * the env returns warm and the next verb rebinds.
+ */
+export declare const MAX_KERNEL_PARDON_MS: number;
+/**
+ * Parse one sysctl timeval line — `{ sec = 1784497430, usec = 123456 } Sat
+ * Jul 19 23:43:50 2026` — to milliseconds since the epoch. Returns null on
+ * anything else: a missing or garbage sysctl must never break the sweep.
+ */
+export declare function parseSysctlTimeval(line: string | null | undefined): number | null;
+export interface KernelSleepArgs {
+    /** kern.sleeptime as epoch ms, or null when unreadable. */
+    sleeptime: number | null;
+    /** kern.waketime as epoch ms, or null when unreadable. */
+    waketime: number | null;
+    /** waketime of the last sleep this daemon already pardoned (0 = none yet). */
+    lastPardonedWake: number;
+    /** Wall-clock instant of the PREVIOUS sweep tick. */
+    lastSweepWall: number;
+}
+/**
+ * The pardon decision: did the kernel record a wake that happened since the
+ * previous sweep tick, for a sleep this daemon has not pardoned yet? Returns
+ * the gap to pardon (waketime − sleeptime) or null.
+ *
+ * Guards, in order:
+ *  - unreadable record → null (fall back to the wall-vs-monotonic detector);
+ *  - wake already pardoned → null (the two detectors must not double-pardon
+ *    one sleep — the caller tracks the last pardoned waketime);
+ *  - wake at/before the previous sweep tick → null (a stale record: the
+ *    machine's last wake predates this daemon's current sweep window, e.g.
+ *    the boot-era record seen on daemon start, or a sleep the wall-vs-mono
+ *    detector already pardoned on an earlier sweep);
+ *  - sleeptime not strictly before waketime → null (mid-transition/corrupt);
+ *  - gap beyond MAX_KERNEL_PARDON_MS → null (absurd value).
+ */
+export declare function kernelSleepGap(a: KernelSleepArgs): number | null;
+/**
+ * Read the kernel's sleep/wake record. Synchronous and cheap (~1 ms) at the
+ * 15 s sweep cadence; darwin-only callers. Any failure — missing binary,
+ * unknown OID, timeout — returns null legs: the sweep falls back to the
+ * wall-vs-monotonic detector and must never be broken by sysctl.
+ */
+export declare function readKernelSleepRecord(): {
+    sleeptime: number | null;
+    waketime: number | null;
+};

package/dist/core/sleep.js

@@ -0,0 +1,99 @@
+/**
+ * Kernel-record sleep detection (macOS).
+ *
+ * The sweeper's original sleep pardon inferred suspend from wall-clock
+ * outrunning performance.now(). That is correct on Linux, where
+ * CLOCK_MONOTONIC halts through suspend — but INERT on Apple Silicon, where
+ * mach_absolute_time keeps advancing through real sleep: a genuine lid-close
+ * test (2026-07-19) produced no divergence, no pardon, no event of any kind,
+ * and a dead lease. On darwin the daemon therefore reads the kernel's OWN
+ * record of the last sleep/wake transition instead:
+ *
+ *   $ sysctl -n kern.sleeptime kern.waketime
+ *   { sec = 1784497430, usec = 123456 } Sat Jul 19 23:43:50 2026
+ *   { sec = 1784499830, usec = 654321 } Sun Jul 20 00:23:50 2026
+ *
+ * The parsing and the pardon decision are pure exported functions (the
+ * policy() pattern) because a real lid close cannot be
+ * automated and this repo forbids test-only interleaving hooks — the unit
+ * tests in tests/sleep-pardon.test.ts encode the confirmed scenario; the
+ * end-to-end proof remains the manual lid-close protocol (docs/soak.md).
+ */
+import { execFileSync } from 'node:child_process';
+/**
+ * Cap on a kernel-reported sleep gap. A pardon shifts EVERY lease and idle
+ * deadline by the gap, so a corrupt or absurd record (bad clock at sleep time,
+ * garbage sysctl) must not push deadlines out by years. Past the cap we prefer
+ * letting deadlines lapse — losing a lease is designed to be worthless (§10):
+ * the env returns warm and the next verb rebinds.
+ */
+export const MAX_KERNEL_PARDON_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+/**
+ * Parse one sysctl timeval line — `{ sec = 1784497430, usec = 123456 } Sat
+ * Jul 19 23:43:50 2026` — to milliseconds since the epoch. Returns null on
+ * anything else: a missing or garbage sysctl must never break the sweep.
+ */
+export function parseSysctlTimeval(line) {
+    if (typeof line !== 'string')
+        return null;
+    const m = /\{\s*sec\s*=\s*(\d+)\s*,\s*usec\s*=\s*(\d+)\s*\}/.exec(line);
+    if (!m)
+        return null;
+    const sec = Number(m[1]);
+    const usec = Number(m[2]);
+    if (!Number.isFinite(sec) || !Number.isFinite(usec))
+        return null;
+    return sec * 1000 + Math.floor(usec / 1000);
+}
+/**
+ * The pardon decision: did the kernel record a wake that happened since the
+ * previous sweep tick, for a sleep this daemon has not pardoned yet? Returns
+ * the gap to pardon (waketime − sleeptime) or null.
+ *
+ * Guards, in order:
+ *  - unreadable record → null (fall back to the wall-vs-monotonic detector);
+ *  - wake already pardoned → null (the two detectors must not double-pardon
+ *    one sleep — the caller tracks the last pardoned waketime);
+ *  - wake at/before the previous sweep tick → null (a stale record: the
+ *    machine's last wake predates this daemon's current sweep window, e.g.
+ *    the boot-era record seen on daemon start, or a sleep the wall-vs-mono
+ *    detector already pardoned on an earlier sweep);
+ *  - sleeptime not strictly before waketime → null (mid-transition/corrupt);
+ *  - gap beyond MAX_KERNEL_PARDON_MS → null (absurd value).
+ */
+export function kernelSleepGap(a) {
+    if (a.sleeptime === null || a.waketime === null)
+        return null;
+    if (a.waketime <= a.lastPardonedWake)
+        return null;
+    if (a.waketime <= a.lastSweepWall)
+        return null;
+    if (a.sleeptime >= a.waketime)
+        return null;
+    const gap = a.waketime - a.sleeptime;
+    if (gap > MAX_KERNEL_PARDON_MS)
+        return null;
+    return gap;
+}
+/**
+ * Read the kernel's sleep/wake record. Synchronous and cheap (~1 ms) at the
+ * 15 s sweep cadence; darwin-only callers. Any failure — missing binary,
+ * unknown OID, timeout — returns null legs: the sweep falls back to the
+ * wall-vs-monotonic detector and must never be broken by sysctl.
+ */
+export function readKernelSleepRecord() {
+    try {
+        const out = execFileSync('/usr/sbin/sysctl', ['-n', 'kern.sleeptime', 'kern.waketime'], {
+            encoding: 'utf8',
+            // Never the daemon's stderr: that is daemon.log.
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2_000,
+        });
+        const [sleepLine, wakeLine] = out.split('\n');
+        return { sleeptime: parseSysctlTimeval(sleepLine), waketime: parseSysctlTimeval(wakeLine) };
+    }
+    catch {
+        return { sleeptime: null, waketime: null };
+    }
+}
+//# sourceMappingURL=sleep.js.map

package/dist/core/sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../src/core/sleep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,UAAU;AAExE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,MAAM,CAAC,GAAG,kDAAkD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,OAAO,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AAC9C,CAAC;AAaD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,CAAkB;IAC/C,IAAI,CAAC,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,aAAa;QAAE,OAAO,IAAI,CAAC;IAC/C,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,SAAS,CAAC;IACrC,IAAI,GAAG,GAAG,oBAAoB;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,kBAAkB,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,eAAe,CAAC,EAAE;YACtF,QAAQ,EAAE,MAAM;YAChB,iDAAiD;YACjD,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,KAAK;SACf,CAAC,CAAC;QACH,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,EAAE,SAAS,EAAE,kBAAkB,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC9F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC7C,CAAC;AACH,CAAC"}

package/dist/core/tree-ledger.d.ts

@@ -0,0 +1,39 @@
+export interface TreeLedgerFile {
+    /** The physical worktree this ledger describes — retention reads it. */
+    root: string;
+    fingerprints: Record<string, string>;
+}
+export declare const worktreeStateDir: (stackId: string) => string;
+export declare function readTreeLedger(stackId: string): Record<string, string>;
+export declare function writeTreeLedger(stackId: string, root: string, fingerprints: Record<string, string>): void;
+/**
+ * `runly destroy`: forget the command rules that declare no `outputs:` — the
+ * pool that destroys an environment usually resets the worktree next
+ * (`git clean -fdx`), which removes what they produced, and nothing else could
+ * tell. Rules with `outputs:` stay: their outputs are checked at every bind.
+ */
+export declare function forgetRulesWithoutOutputs(stackId: string, root: string, keep: (key: string) => boolean): number;
+/**
+ * The template each datastore and preset of this worktree was last restored
+ * from (`worktrees/<stack>/templates.json`, decision 0044). Templates are
+ * shared by every worktree of a manifest name, so "the newest per datastore
+ * and preset" no longer says which one a given worktree uses; retention keeps
+ * every template a live worktree recorded here, with or without an
+ * environment — an `up` after `destroy` stays a restore, not a bake (0039).
+ * Written synchronously (no await between read and write), so the daemon's
+ * parallel datastore restores cannot lose each other's entries.
+ */
+export interface WorktreeTemplatesFile {
+    root: string;
+    /** `<datastore>/<preset>` → `<templates dir>/<file>`. */
+    refs: Record<string, string>;
+}
+export declare function readWorktreeTemplates(stackId: string): WorktreeTemplatesFile | undefined;
+export declare function recordWorktreeTemplate(stackId: string, root: string, key: string, ref: string): void;
+/** `--pristine`: forget what was applied, so every rule runs again. */
+export declare function clearTreeLedger(stackId: string): void;
+/** Which ledger a key belongs to: command rules are the worktree's, `@` keys the environment's. */
+export declare function isTreeKey(key: string): boolean;
+export declare const pickTreeKeys: (fps: Record<string, string>) => Record<string, string>;
+/** The environment's half: `@`-built-in rules only (`@source`/`@built:` stamps are gone). */
+export declare const pickEnvKeys: (fps: Record<string, string>) => Record<string, string>;

package/dist/core/tree-ledger.js

@@ -0,0 +1,92 @@
+/**
+ * The worktree's upkeep ledger (decision 0032): which command upkeep rule was
+ * last applied for which content of its `when:` files.
+ *
+ * Upkeep commands (an install, a codegen) write into the caller's worktree, so
+ * whether one is due is a fact about the worktree, not about an environment;
+ * `runly warm` reads and writes the same ledger a bind does. It is kept in the
+ * state root, keyed by stack id (one stack = one physical worktree = one
+ * environment), never in the worktree. The `@`-built-in rules act on an
+ * environment's data and stay on the environment row. Writers hold the
+ * engine's per-worktree lock; the file is replaced atomically.
+ *
+ * Builds are NOT recorded here or anywhere: a service's `build:` runs on every
+ * bind that starts it, and the build tool decides what is up to date.
+ */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { worktreesRoot } from './paths.js';
+export const worktreeStateDir = (stackId) => join(worktreesRoot(), stackId);
+const ledgerPath = (stackId) => join(worktreeStateDir(stackId), 'ledger.json');
+export function readTreeLedger(stackId) {
+    try {
+        const raw = JSON.parse(readFileSync(ledgerPath(stackId), 'utf8'));
+        return raw.fingerprints && typeof raw.fingerprints === 'object' ? { ...raw.fingerprints } : {};
+    }
+    catch {
+        return {}; // absent or torn: every rule and build counts as not yet applied
+    }
+}
+export function writeTreeLedger(stackId, root, fingerprints) {
+    const dir = worktreeStateDir(stackId);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `ledger.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ root, fingerprints }));
+    renameSync(tmp, ledgerPath(stackId));
+}
+/**
+ * `runly destroy`: forget the command rules that declare no `outputs:` — the
+ * pool that destroys an environment usually resets the worktree next
+ * (`git clean -fdx`), which removes what they produced, and nothing else could
+ * tell. Rules with `outputs:` stay: their outputs are checked at every bind.
+ */
+export function forgetRulesWithoutOutputs(stackId, root, keep) {
+    const fps = readTreeLedger(stackId);
+    const kept = Object.fromEntries(Object.entries(fps).filter(([k]) => keep(k)));
+    const dropped = Object.keys(fps).length - Object.keys(kept).length;
+    if (dropped > 0)
+        writeTreeLedger(stackId, root, kept);
+    return dropped;
+}
+const templatesPath = (stackId) => join(worktreeStateDir(stackId), 'templates.json');
+export function readWorktreeTemplates(stackId) {
+    try {
+        const raw = JSON.parse(readFileSync(templatesPath(stackId), 'utf8'));
+        if (typeof raw.root !== 'string' || !raw.refs || typeof raw.refs !== 'object')
+            return undefined;
+        return { root: raw.root, refs: { ...raw.refs } };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function recordWorktreeTemplate(stackId, root, key, ref) {
+    const cur = readWorktreeTemplates(stackId);
+    if (cur?.root === root && cur.refs[key] === ref)
+        return;
+    const refs = { ...(cur?.root === root ? cur.refs : {}), [key]: ref };
+    const dir = worktreeStateDir(stackId);
+    try {
+        mkdirSync(dir, { recursive: true });
+        const tmp = join(dir, `templates.json.${process.pid}.tmp`);
+        writeFileSync(tmp, JSON.stringify({ root, refs }));
+        renameSync(tmp, templatesPath(stackId));
+    }
+    catch {
+        /* best effort: the template is then kept only while a row references it */
+    }
+}
+/** `--pristine`: forget what was applied, so every rule runs again. */
+export function clearTreeLedger(stackId) {
+    rmSync(ledgerPath(stackId), { force: true });
+}
+/** Which ledger a key belongs to: command rules are the worktree's, `@` keys the environment's. */
+export function isTreeKey(key) {
+    if (key.startsWith('@'))
+        return false; // a leftover stamp from an older runly
+    return !key.includes(' -> @');
+}
+export const pickTreeKeys = (fps) => Object.fromEntries(Object.entries(fps).filter(([k]) => isTreeKey(k)));
+/** The environment's half: `@`-built-in rules only (`@source`/`@built:` stamps are gone). */
+export const pickEnvKeys = (fps) => Object.fromEntries(Object.entries(fps).filter(([k]) => !k.startsWith('@') && k.includes(' -> @')));
+//# sourceMappingURL=tree-ledger.js.map

package/dist/core/tree-ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-ledger.js","sourceRoot":"","sources":["../../src/core/tree-ledger.ts"],"names":[],"mappings":"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"}