@omgbase/core 0.21.0 → 0.23.0

package/dist/src/core/store/gc.js

@@ -1,9 +1,13 @@
-// Collect the set of tree-node hashes reachable from every revision root, and
-// the blob hashes referenced by those nodes (raw + trivia) plus frontmatter.
-function markReachable(store) {
+/**
+ * The mark (spec/store §7): every tree node reachable from a live revision's
+ * `root_tree` (walking `child_tree_hash_hex`) and every blob those nodes name
+ * (raw + trivia) plus every live `frontmatter_blob`. An archived revision
+ * (`root_tree IS NULL`, 15.0) contributes nothing — its bodies live in its
+ * segment.
+ */
+export function markReachable(store) {
     const trees = new Set();
     const blobs = new Set();
-    // Frontmatter blobs referenced by revisions.
     const fmRows = store.db.prepare("SELECT DISTINCT frontmatter_blob FROM revisions WHERE frontmatter_blob IS NOT NULL").all();
     for (const r of fmRows)
         blobs.add(r.frontmatter_blob.toString("hex"));
@@ -24,21 +28,50 @@ function markReachable(store) {
                 walk(childHashHex);
         }
     };
-    const roots = store.db.prepare("SELECT DISTINCT root_tree FROM revisions").all();
+    const roots = store.db.prepare("SELECT DISTINCT root_tree FROM revisions WHERE root_tree IS NOT NULL").all();
     for (const r of roots)
         walk(r.root_tree.toString("hex"));
     return { trees, blobs };
 }
+/**
+ * The sweep: delete every `tree_nodes` and `blobs` row the mark did not reach
+ * (count only when `dry`). Runs in the caller's transaction — `runGc` and the
+ * retention squash both call it.
+ */
+export function sweepUnreachable(store, dry = false) {
+    const db = store.db;
+    const { trees, blobs } = markReachable(store);
+    let treeNodesSwept = 0;
+    const allTrees = db.prepare("SELECT hash FROM tree_nodes").all();
+    const delTree = db.prepare("DELETE FROM tree_nodes WHERE hash = ?");
+    for (const t of allTrees)
+        if (!trees.has(t.hash.toString("hex"))) {
+            if (!dry)
+                delTree.run(t.hash);
+            treeNodesSwept++;
+        }
+    let blobsSwept = 0;
+    const allBlobs = db.prepare("SELECT hash FROM blobs").all();
+    const delBlob = db.prepare("DELETE FROM blobs WHERE hash = ?");
+    for (const b of allBlobs)
+        if (!blobs.has(b.hash.toString("hex"))) {
+            if (!dry)
+                delBlob.run(b.hash);
+            blobsSwept++;
+        }
+    return { blobsSwept, treeNodesSwept };
+}
 /** The `same` rows a store through 14.1 persisted (spec/store §7, 14.2). */
 export function countSameDispositions(store) {
     return store.db.prepare("SELECT count(*) AS c FROM dispositions WHERE kind = 'same'").get().c;
 }
 /**
  * Mark-and-sweep GC (flag-gated; enabled must be true to run — v1.0 ships it
- * off). Removes blobs/tree_nodes unreachable from any revision root. Because
- * revisions are append-only and never pruned in v1, nothing is actually
- * unreachable unless revision pruning ran first — so that half is a no-op in a
- * default v1 repo, exactly as specified. Rebuild-equivalence is preserved.
+ * off). Removes blobs/tree_nodes unreachable from any live revision root. In a
+ * store that never archived, nothing is unreachable — revisions are append-only
+ * — so that half is a no-op; after a retention squash (15.0) the squash has
+ * already swept, so it is a no-op again unless a crash interrupted one.
+ * Rebuild-equivalence is preserved.
  *
  * spec/store §7 (14.2): the same sweep deletes every `same` row of
  * `dispositions` and `block_changes` — what a 14.1 store wrote for every
@@ -51,26 +84,8 @@ export function runGc(store, opts = {}) {
     if (!opts.enabled)
         return { blobsSwept: 0, treeNodesSwept: 0, sameDispositionsSwept: 0 };
     return store.write((db) => {
-        const { trees, blobs } = markReachable(store);
         const dry = Boolean(opts.dryRun);
-        let treeNodesSwept = 0;
-        const allTrees = db.prepare("SELECT hash FROM tree_nodes").all();
-        const delTree = db.prepare("DELETE FROM tree_nodes WHERE hash = ?");
-        for (const t of allTrees)
-            if (!trees.has(t.hash.toString("hex"))) {
-                if (!dry)
-                    delTree.run(t.hash);
-                treeNodesSwept++;
-            }
-        let blobsSwept = 0;
-        const allBlobs = db.prepare("SELECT hash FROM blobs").all();
-        const delBlob = db.prepare("DELETE FROM blobs WHERE hash = ?");
-        for (const b of allBlobs)
-            if (!blobs.has(b.hash.toString("hex"))) {
-                if (!dry)
-                    delBlob.run(b.hash);
-                blobsSwept++;
-            }
+        const { blobsSwept, treeNodesSwept } = sweepUnreachable(store, dry);
         const sameDispositionsSwept = countSameDispositions(store);
         if (!dry && sameDispositionsSwept > 0) {
             db.prepare("DELETE FROM block_changes WHERE kind = 'same'").run();

package/dist/src/core/store/rebuild.d.ts

@@ -1,3 +1,5 @@
 import type { Store } from "./store.js";
 export type RebuildTarget = "sections" | "edges" | "fts" | "block_changes" | "all";
+/** The commit ids every revision of which is archived (spec/store §7 "Retention", 15.0): a commit with at least one revision and no live one. */
+export declare const ARCHIVED_COMMITS_SQL = "SELECT c.commit_id FROM commits c WHERE EXISTS (SELECT 1 FROM revisions r WHERE r.commit_id = c.commit_id) AND NOT EXISTS (SELECT 1 FROM revisions r WHERE r.commit_id = c.commit_id AND r.archive IS NULL)";
 export declare function rebuildIndex(store: Store, target?: RebuildTarget): void;

package/dist/src/core/store/rebuild.js

@@ -1,6 +1,8 @@
 import { rebuildSections } from "./sections.js";
 import { rebuildDocEdges } from "./edges.js";
 import { ftsRebuild } from "./fts.js";
+/** The commit ids every revision of which is archived (spec/store §7 "Retention", 15.0): a commit with at least one revision and no live one. */
+export const ARCHIVED_COMMITS_SQL = "SELECT c.commit_id FROM commits c WHERE EXISTS (SELECT 1 FROM revisions r WHERE r.commit_id = c.commit_id) AND NOT EXISTS (SELECT 1 FROM revisions r WHERE r.commit_id = c.commit_id AND r.archive IS NULL)";
 export function rebuildIndex(store, target = "all") {
     store.write((db) => {
         const docIds = db.prepare("SELECT doc_id FROM docs WHERE deleted_commit IS NULL").all().map((r) => r.doc_id);
@@ -21,8 +23,12 @@ export function rebuildIndex(store, target = "all") {
         }
         if (target === "block_changes" || target === "all") {
             // block_changes is a projection of dispositions across commits: rebuild
-            // it verbatim from the dispositions table (which is durable).
-            db.prepare("DELETE FROM block_changes").run();
+            // it verbatim from the dispositions table (which is durable) — for every
+            // commit that still has dispositions. A wholly archived commit (spec/store
+            // §7 "Retention", 15.0: every revision of it carries `archive`) has none;
+            // its surviving block_changes rows are each block's earliest, kept for the
+            // mint oracle, and are left exactly as they are.
+            db.exec(`DELETE FROM block_changes WHERE commit_id NOT IN (${ARCHIVED_COMMITS_SQL})`);
             db.exec("INSERT OR IGNORE INTO block_changes (block_id, commit_id, kind) SELECT block_id, commit_id, kind FROM dispositions");
         }
     });

package/dist/src/core/store/retention.d.ts

@@ -0,0 +1,138 @@
+import type { Store } from "./store.js";
+/** `one per <period>`: the ladder's thinning grain. */
+export type LadderKeep = "one per day" | "one per week" | "one per month" | "one per year";
+export declare const LADDER_KEEPS: readonly LadderKeep[];
+export interface LadderRung {
+    /** The rung applies to a revision whose age in whole days is at least this. */
+    after_days: number;
+    keep: LadderKeep;
+}
+/** A per-path override: the keys given replace the base policy's for the documents the glob matches. */
+export interface RetentionOverride {
+    glob: string;
+    keep_days?: number;
+    per_doc_max?: number;
+    ladder?: LadderRung[];
+    keep_origins?: string[];
+}
+export interface RetentionPolicy {
+    /** Every revision younger than this many days is kept. */
+    keep_days: number;
+    /** Beyond `keep_days`, one revision per period per rung (sorted by `after_days`). */
+    ladder: LadderRung[];
+    /** The newest N revisions of a document are kept regardless of age. */
+    per_doc_max: number;
+    /** A revision whose commit has one of these origins AND a non-empty reason is kept. */
+    keep_origins: string[];
+    overrides: RetentionOverride[];
+}
+/** The defaults (spec/store §7): a month hot, then one a day for a year, then one a month; 200 per document; api commits with a reason. */
+export declare const DEFAULT_RETENTION: RetentionPolicy;
+/** The settings key the policy lives under (`history.retention`, deep-merged over the defaults). */
+export declare const RETENTION_SETTINGS_KEY = "history";
+/** The repo-settings key naming the last segment this repo recorded (`history.last_segment`). */
+export declare const LAST_SEGMENT_SETTINGS_KEY = "last_segment";
+export declare class RetentionPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * A partial policy (a settings blob, a `--policy` argument) over `base`: every
+ * key given replaces the base's; a malformed value is `RetentionPolicyError`.
+ */
+export declare function mergeRetentionPolicy(base: RetentionPolicy, partial: unknown, at?: string): RetentionPolicy;
+/** A settings blob as stored (`workspace_settings.settings`, `repos.settings`): an object, or `{}` for anything else. */
+export declare function parseSettingsJson(json: string | undefined | null): Record<string, unknown>;
+/**
+ * The repo's effective settings (`spec/sync` settings: the workspace layer
+ * with the repo's own deep-merged over it at the leaf). Inlined here rather
+ * than imported from `sync/settings.ts` — `core/` does not import its
+ * siblings — and kept to the rule that module states.
+ */
+export declare function effectiveSettings(store: Store, repoId: string): Record<string, unknown>;
+/** The repo's effective policy: the defaults, the settings' `history.retention` over them, then `override` (a CLI `--policy`). */
+export declare function retentionPolicy(store: Store, repoId: string, override?: unknown): RetentionPolicy;
+/**
+ * An override glob against a reference path: `**` any run of characters,
+ * `*` any run without `/`, `?` one character, everything else literal; a glob
+ * without a leading `/` is rooted (`projects/**` ≡ `/projects/**`).
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/** The policy for one document: the first matching override's keys over the base. */
+export declare function policyFor(base: RetentionPolicy, referencePathOfDoc: string): RetentionPolicy;
+/** Whole days between a commit's `ts` and `now` (negative when the commit is in the future). */
+export declare function ageDays(ts: string, nowMs: number): number;
+/** The period key of a timestamp under a rung's grain (UTC; a week starts on Monday). */
+export declare function periodKey(ts: string, keep: LadderKeep): string;
+export interface RetentionDocPlan {
+    id: string;
+    /** The document's current path, reference form. */
+    path: string;
+    /** Live (non-archived) revisions of the document before the plan. */
+    revisions: number;
+    /** Revision ids kept, oldest first. */
+    keep: string[];
+    /** Revision ids to archive, oldest first. */
+    archive: string[];
+    /** Bytes of blobs and tree nodes reachable from the archived revisions and from no kept revision of the store. */
+    bytes: number;
+}
+export interface RetentionTotals {
+    /** Documents with at least one revision to archive. */
+    docs: number;
+    /** Live revisions of the repository before the plan. */
+    revisions: number;
+    keep: number;
+    archive: number;
+    /** Bytes reachable only from the archived revisions, over their union. */
+    bytes: number;
+}
+export interface RetentionPlan {
+    policy: RetentionPolicy;
+    now: string;
+    before: string | null;
+    /** Only the documents with something to archive, by path. */
+    docs: RetentionDocPlan[];
+    totals: RetentionTotals;
+}
+export interface EvaluateOptions {
+    /** The clock; `new Date()` when absent (the spec seam pins it). */
+    now?: string;
+    /** Only revisions committed strictly before this instant are candidates. */
+    before?: string;
+    /** The policy in effect; `retentionPolicy(store, repoId)` when absent. */
+    policy?: RetentionPolicy;
+}
+/**
+ * The sizes of the blobs and tree nodes of a store, and the walk that marks
+ * what a set of revisions reaches (spec/store §7: the GC mark, run twice — once
+ * from what stays, once from what goes — to cost a plan).
+ */
+export declare class ReachMarker {
+    private readonly store;
+    private readonly treeNode;
+    private readonly blobSize;
+    private readonly treeSizes;
+    private readonly blobSizes;
+    constructor(store: Store);
+    /** Mark every tree node and blob reachable from the given roots and frontmatter blobs into `trees`/`blobs` (hex). */
+    mark(revs: {
+        root_tree: Buffer | null;
+        frontmatter_blob: Buffer | null;
+    }[], trees: Set<string>, blobs: Set<string>): void;
+    /** Bytes of the given tree nodes (their `entries`) and blobs (`size`). */
+    bytesOf(trees: Iterable<string>, blobs: Iterable<string>): number;
+}
+/**
+ * The plan (spec/store §7 "Retention", the policy as an exact rule). Per
+ * document, over its live revisions oldest → newest: a revision is KEPT when
+ * any rule keeps it — it is the document's current revision (a tombstoned
+ * document's last revision is its current one), a `pending_materializations`
+ * row names it, it is younger than `keep_days`, it is among the newest
+ * `per_doc_max`, its commit's origin is in `keep_origins` with a non-empty
+ * reason, it is not before `before`, no ladder rung applies to its age (the
+ * gap below the first rung keeps everything), or it is the newest revision of
+ * its rung's period; every other revision is ARCHIVED. Bytes are the GC mark
+ * from the archived revisions minus the mark from every revision that stays
+ * live in the store (all repositories — blobs and tree nodes are shared).
+ */
+export declare function evaluateRetention(store: Store, repoId: string, opts?: EvaluateOptions): RetentionPlan;