@omgbase/core 0.21.0 → 0.23.0

package/dist/src/core/ids.d.ts

@@ -1,4 +1,4 @@
-export type IdPrefix = "d" | "b" | "c" | "r" | "x" | "col" | "cp" | "e" | "rp" | "v" | "src";
+export type IdPrefix = "d" | "b" | "c" | "r" | "x" | "col" | "cp" | "e" | "rp" | "v" | "src" | "s";
 export declare function randomSuffix(len?: number): string;
 /** A replacement id generator (spec/store §2.2): given a prefix, return the whole id. */
 export type IdMinter = (prefix: IdPrefix) => string;

package/dist/src/core/read/document.d.ts

@@ -106,7 +106,10 @@ export interface DocsReadAtResult {
  * IN ORDER — but sourced from the revision's Merkle `root_tree` instead of the
  * live `blocks` table. Returns null when the doc is missing, or when `revId`
  * does not name a revision of this document (so the caller can raise a clean
- * not-found error).
+ * not-found error). An ARCHIVED revision (spec/store §7 "Retention", 15.0)
+ * reads through its segment, attached on demand; when the segment is not
+ * recorded or not on disk this throws `RevisionArchived` (the surface's
+ * `revision_archived`).
  *
  * FIDELITY CAVEAT: `leading_trivia` and `frontmatter_trivia` are stored ONLY on
  * the current `docs` row, NOT per-revision (see schema.ts — the `docs` row is

package/dist/src/core/read/document.js

@@ -2,6 +2,7 @@ import { findDoc, findDocByRef, loadDocBlocks } from "./reader.js";
 import { docPropertiesGrouped } from "../store/properties.js";
 import { sha256 } from "../hash.js";
 import { referencePath } from "../paths.js";
+import { revisionBody } from "../store/archive.js";
 function blob(db, hash) {
     const row = db.prepare("SELECT bytes FROM blobs WHERE hash = ?").get(hash);
     return row ? row.bytes.toString("utf8") : "";
@@ -154,7 +155,10 @@ export function docsReadMany(store, repoId, refs, opts = {}) {
  * IN ORDER — but sourced from the revision's Merkle `root_tree` instead of the
  * live `blocks` table. Returns null when the doc is missing, or when `revId`
  * does not name a revision of this document (so the caller can raise a clean
- * not-found error).
+ * not-found error). An ARCHIVED revision (spec/store §7 "Retention", 15.0)
+ * reads through its segment, attached on demand; when the segment is not
+ * recorded or not on disk this throws `RevisionArchived` (the surface's
+ * `revision_archived`).
  *
  * FIDELITY CAVEAT: `leading_trivia` and `frontmatter_trivia` are stored ONLY on
  * the current `docs` row, NOT per-revision (see schema.ts — the `docs` row is
@@ -174,25 +178,33 @@ export function readDocumentAtRevision(store, docId, revId) {
         .get(docId);
     if (!doc)
         return null;
-    const rev = db.prepare("SELECT root_tree, frontmatter_blob, rendered_hash, path FROM revisions WHERE rev_id = ? AND doc_id = ?").get(revId, docId);
+    // The revision's bodies: the store's for a live revision, its segment's for
+    // an archived one (spec/store §6.2 "through a segment", 15.0 — `prefix` is
+    // the attached alias; an unavailable segment throws RevisionArchived).
+    const rev = revisionBody(store, revId, docId);
     if (!rev)
         return null;
+    const at = (table) => `${rev.prefix}${table}`;
+    const blobAt = (hash) => {
+        const row = db.prepare(`SELECT bytes FROM ${at("blobs")} WHERE hash = ?`).get(hash);
+        return row ? row.bytes.toString("utf8") : "";
+    };
     const out = [doc.leading_trivia];
     // Frontmatter blob for THIS revision (per-revision), then the doc-level
     // separator (best-effort — see fidelity caveat).
     if (rev.frontmatter_blob)
-        out.push(blob(db, rev.frontmatter_blob) + (doc.frontmatter_trivia ?? ""));
+        out.push(blobAt(rev.frontmatter_blob) + (doc.frontmatter_trivia ?? ""));
     // Top-level blocks in tree order, from THIS revision's Merkle root tree node.
     // A container's raw already holds its children verbatim, so we deliberately do
     // NOT recurse into childTreeHashHex (mirrors reconstructContent's
     // parent_block IS NULL walk). An absent tree node yields empty body bytes.
-    const node = db.prepare("SELECT entries FROM tree_nodes WHERE hash = ?").get(rev.root_tree);
+    const node = db.prepare(`SELECT entries FROM ${at("tree_nodes")} WHERE hash = ?`).get(rev.root_tree);
     if (node) {
         const entries = JSON.parse(node.entries);
         for (const [, rawHashHex, , , , triviaHashHex] of entries) {
-            out.push(blob(db, Buffer.from(rawHashHex, "hex")));
+            out.push(blobAt(Buffer.from(rawHashHex, "hex")));
             if (triviaHashHex)
-                out.push(blob(db, Buffer.from(triviaHashHex, "hex")));
+                out.push(blobAt(Buffer.from(triviaHashHex, "hex")));
         }
     }
     const content = out.join("");

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

@@ -0,0 +1,196 @@
+import type { Store } from "./store.js";
+import { type EvaluateOptions, type RetentionPlan, type RetentionPolicy } from "./retention.js";
+/** spec/store/archive.sql, verbatim — the segment's DDL. */
+export declare const ARCHIVE_DDL = "-- ---- an archive segment (spec/store \u00A77 \"Retention\", 15.0) --------------------\n-- One file per `history export`, never appended: the bodies of the revisions\n-- the retention policy squashed, self-contained (every blob and tree node\n-- reachable from them), plus copies of their revision, commit, disposition and\n-- block-change rows, and one manifest row. The same DDL subset as schema.sql\n-- minus the foreign keys (a segment holds no repos or docs rows).\nCREATE TABLE IF NOT EXISTS manifest (\n  segment_id          TEXT PRIMARY KEY,\n  repo_id             TEXT NOT NULL,\n  created_at          TEXT NOT NULL,\n  policy              TEXT NOT NULL,\n  seq_lo              INTEGER NOT NULL,\n  seq_hi              INTEGER NOT NULL,\n  revision_count      INTEGER NOT NULL,\n  previous_segment    TEXT,\n  schema_user_version INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS revisions (\n  rev_id           TEXT PRIMARY KEY,\n  doc_id           TEXT NOT NULL,\n  seq              INTEGER NOT NULL,\n  root_tree        BLOB NOT NULL,\n  frontmatter_blob BLOB,\n  rendered_hash    BLOB NOT NULL,\n  path             TEXT NOT NULL,\n  commit_id        TEXT NOT NULL,\n  UNIQUE (doc_id, seq)\n);\n\nCREATE TABLE IF NOT EXISTS commits (\n  commit_id     TEXT PRIMARY KEY,\n  repo_id       TEXT NOT NULL,\n  seq           INTEGER NOT NULL,\n  ts            TEXT NOT NULL,\n  origin        TEXT NOT NULL CHECK (origin IN ('api','observed','import','projection')),\n  actor         TEXT,\n  reason        TEXT,\n  checkpoint_id TEXT,\n  ops           TEXT\n);\n\nCREATE TABLE IF NOT EXISTS blobs (\n  hash  BLOB PRIMARY KEY,\n  bytes BLOB NOT NULL,\n  size  INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS tree_nodes (\n  hash    BLOB PRIMARY KEY,\n  entries TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS dispositions (\n  commit_id  TEXT NOT NULL,\n  block_id   TEXT NOT NULL,\n  kind       TEXT NOT NULL CHECK (kind IN\n             ('same','edited','moved','edited_moved','inserted','deleted',\n              'split_from','merged_into','copied_from','resurrected','bulk_rewrite')),\n  confidence REAL,\n  reason     TEXT,\n  matcher_v  TEXT,\n  detail     TEXT NOT NULL DEFAULT '{}',\n  PRIMARY KEY (commit_id, block_id, kind)\n);\n\nCREATE TABLE IF NOT EXISTS block_changes (\n  block_id  TEXT NOT NULL,\n  commit_id TEXT NOT NULL,\n  kind      TEXT NOT NULL,\n  PRIMARY KEY (block_id, commit_id, kind)\n);\n";
+/** The file suffix every segment carries. */
+export declare const ARCHIVE_SUFFIX = ".omgarchive.db";
+/** The default directory under `.omgbase/`. */
+export declare const ARCHIVE_DIR = "archives";
+/** `<repo_id>-<seq_lo>-<seq_hi>-<segment_id>.omgarchive.db` */
+export declare function segmentFileName(repoId: string, seqLo: number, seqHi: number, segmentId: string): string;
+/** The parts a segment file name carries, or null when the name is not one. */
+export declare function parseSegmentFileName(name: string): {
+    repoId: string;
+    seqLo: number;
+    seqHi: number;
+    segmentId: string;
+} | null;
+export interface Manifest {
+    segment_id: string;
+    repo_id: string;
+    created_at: string;
+    policy: RetentionPolicy;
+    seq_lo: number;
+    seq_hi: number;
+    revision_count: number;
+    previous_segment: string | null;
+    schema_user_version: number;
+}
+/** A read of an archived revision whose segment is not recorded, or recorded but not on disk (spec/surface: `revision_archived`). */
+export declare class RevisionArchived extends Error {
+    readonly rev: string;
+    readonly archive: string;
+    readonly path: string | null;
+    constructor(rev: string, archive: string, path: string | null);
+}
+/** Not an archive segment, or one of another repository. */
+export declare class NotASegment extends Error {
+    readonly path: string;
+    constructor(path: string, detail: string);
+}
+/** Open a segment read-only and return its manifest; `NotASegment` when the file is not one. */
+export declare function readManifest(path: string): Manifest;
+export interface ArchiveRow {
+    segment_id: string;
+    repo_id: string;
+    path: string;
+    seq_lo: number;
+    seq_hi: number;
+    created_at: string;
+    revision_count: number;
+    bytes: number;
+}
+export interface AttachedSegment {
+    segment_id: string;
+    path: string;
+    seq_lo: number;
+    seq_hi: number;
+    revision_count: number;
+    bytes: number;
+}
+export interface AttachResult {
+    attached: AttachedSegment[];
+    /** Files in a directory that are not this repository's segments. */
+    skipped: number;
+}
+/**
+ * `omg history attach <file|dir>`: record a segment (idempotent — a known
+ * segment's path is re-recorded) or every `.omgarchive.db` of a directory
+ * whose manifest `repo_id` is this repository's. A single file of another
+ * repository or a non-segment is `NotASegment`; in a directory they are skipped.
+ */
+export declare function attachArchive(store: Store, repoId: string, target: string): AttachResult;
+/**
+ * `omg history detach <segment_id|path>`: forget a segment. The revisions it
+ * holds keep their `archive` pointer; reading one is `revision_archived` until
+ * the segment is attached again. Returns the id, or null when nothing matched.
+ */
+export declare function detachArchive(store: Store, repoId: string, ref: string): string | null;
+/**
+ * A segment's state (spec/store §7 "Retention"): recorded and on disk
+ * (`attached`), recorded but not on disk (`missing`); or unrecorded under the
+ * archives directory — `pending` (complete, its revisions still live: the
+ * crash rule finishes it on the next `export --prune`), `detached` (complete
+ * and squashed: `attach` brings it back), `stale` (some of its revisions live,
+ * some not: it belongs to another store or predates a different squash).
+ */
+export type ArchiveState = "attached" | "missing" | "pending" | "detached" | "stale";
+export interface ArchiveListing extends AttachedSegment {
+    created_at: string;
+    state: ArchiveState;
+}
+/**
+ * `omg history list`: the repository's recorded segments by `seq_lo` then id,
+ * followed by the unrecorded complete segments found in `dest`, by file name.
+ */
+export declare function listArchives(store: Store, repoId: string, opts?: {
+    dest?: string;
+}): ArchiveListing[];
+export interface UnrecordedSegment {
+    path: string;
+    state: "pending" | "detached" | "stale";
+}
+/**
+ * The complete segments of this repository under `dest` that no `archives`
+ * row records, by file name, each classified by its revisions: all live →
+ * `pending` (the crash rule's input), all archived → `detached`, else `stale`.
+ */
+export declare function unrecordedSegments(store: Store, repoId: string, dest: string): UnrecordedSegment[];
+export declare function archiveAlias(segmentId: string): string;
+/**
+ * The table prefix a revision's bodies are read under: `""` for a live
+ * revision, `"<alias>."` for an archived one whose segment is attached on
+ * demand (and verified to be the segment it claims). `RevisionArchived` when
+ * the segment is not recorded or not on disk.
+ */
+export declare function archivePrefix(store: Store, rev: {
+    rev_id: string;
+    archive: string | null;
+}): string;
+export interface RevisionBody {
+    rev_id: string;
+    doc_id: string;
+    path: string;
+    rendered_hash: Buffer;
+    root_tree: Buffer;
+    frontmatter_blob: Buffer | null;
+    /** `""` or `"<alias>."` — where `tree_nodes` and `blobs` for this revision live. */
+    prefix: string;
+    archived: boolean;
+}
+/**
+ * A revision's row with its bodies resolved: a live revision's from the store,
+ * an archived one's from its segment (attached on demand). `undefined` when
+ * `revId` is not a revision (of `docId`, when given); `RevisionArchived` when
+ * its segment is unavailable.
+ */
+export declare function revisionBody(store: Store, revId: string, docId?: string): RevisionBody | undefined;
+export interface SegmentInfo {
+    id: string;
+    path: string;
+    seq_lo: number;
+    seq_hi: number;
+    created_at: string;
+    revision_count: number;
+    /** The file's size on disk. */
+    bytes: number;
+    previous_segment: string | null;
+}
+export interface SquashResult {
+    revisions: number;
+    /** Commits every revision of which is archived: their dispositions and block changes moved. */
+    commits: number;
+    dispositions: number;
+    block_changes: number;
+}
+export interface ExportResult {
+    plan: RetentionPlan;
+    /** null when nothing was to archive (no file written). */
+    segment: SegmentInfo | null;
+    /** An unrecorded complete segment was finished instead of writing a new one (the crash rule). */
+    reused: boolean;
+    /** null without `prune`. */
+    squashed: SquashResult | null;
+    /** null without `prune`. */
+    gc: {
+        blobs: number;
+        tree_nodes: number;
+    } | null;
+}
+export interface ExportOptions extends EvaluateOptions {
+    /** The directory the segment is written to (created when missing). */
+    dest: string;
+    /** Squash the store after the segment is durable. */
+    prune: boolean;
+}
+/** An unrecorded segment under `dest` names both live and non-live revisions (it predates another squash, or belongs elsewhere). */
+export declare class StaleSegment extends Error {
+    readonly path: string;
+    readonly rev: string;
+    constructor(path: string, rev: string);
+}
+/**
+ * `omg history export [--prune]`: evaluate the policy, write ONE new segment
+ * for the revisions to archive (or finish an unrecorded one — the crash
+ * rule), and with `prune` squash the store. Nothing to archive → no file,
+ * `segment: null`.
+ */
+export declare function exportHistory(store: Store, repoId: string, opts: ExportOptions): ExportResult;
+/** The archived-history figures the size report carries (spec/store §7 "Size", 15.0). */
+export declare function archivedSummary(store: Store): {
+    revisions: number;
+    segments: number;
+    bytes: number;
+};
+/** The file name of a segment path, for messages and fixtures. */
+export declare function segmentBasename(path: string): string;