@omgbase/core 0.11.1 → 0.15.0

package/dist/src/mutate/materialize.d.ts

@@ -0,0 +1,49 @@
+import type { Database } from "better-sqlite3";
+import type { Store } from "../core/store/store.js";
+import type { DocStore } from "./doc-store.js";
+export type PendingKind = "write" | "rename" | "remove";
+/** One `pending_materializations` row (spec/store §3.1), hash as the 32 raw bytes. */
+export interface PendingRow {
+    path: string;
+    kind: PendingKind;
+    fromPath: string | null;
+    docId: string;
+    revId: string | null;
+    renderedHash: Buffer;
+    commitId: string;
+}
+/** The pending row at `(repo, path)`, or null. */
+export declare function readPending(db: Database, repoId: string, path: string): PendingRow | null;
+/** Every pending row of a repo, in insertion order (a replaced row moves to the end). */
+export declare function listPending(db: Database, repoId: string): PendingRow[];
+/** Record an intent (`INSERT OR REPLACE`: one row per path — a later request for the same path supersedes the earlier). */
+export declare function insertPending(db: Database, repoId: string, row: PendingRow): void;
+/** Drop the intent at `(repo, path)`: the file is as recorded, or a later observation superseded it. */
+export declare function deletePending(db: Database, repoId: string, path: string): void;
+/** The rendered hash of the revision BEFORE `revId` of the same document (what
+ *  the file held before the commit that recorded the row), or null for a first
+ *  revision / an unknown one. */
+export declare function priorRenderedHash(db: Database, revId: string | null): Buffer | null;
+export interface MaterializeOptions {
+    /** The hash of the bytes the materializer may overwrite at the row's path (the
+     *  engine's own previous bytes). Defaults to the rendered hash of the revision
+     *  before the row's `rev_id`. `null` = only an absent or already-equal file is
+     *  acceptable (a created document has no previous bytes). */
+    priorHash?: Buffer | null;
+}
+/**
+ * Materialize one row through `docStore` and, when the file is as recorded,
+ * delete the row. Returns true when the row was cleared, false when it was kept
+ * (the path holds foreign bytes — the next observation decides — or the bytes
+ * could not be rendered). Never throws for a foreign file; a doc store write
+ * failure propagates with the row intact.
+ */
+export declare function materializeRow(store: Store, repoId: string, row: PendingRow, docStore: DocStore, opts?: MaterializeOptions): boolean;
+/**
+ * Replay every pending row of a repo through `docStore`, in insertion order.
+ * Returns the paths whose rows were cleared (materialized or confirmed); rows
+ * kept for a foreign file are not listed. The recovery point of the freshness
+ * sweep (step 0) and of `recoverRepo`; the commit phase materializes its own
+ * rows per effect instead, interleaved with the stat-cache refreshes.
+ */
+export declare function materializePending(store: Store, repoId: string, docStore: DocStore): string[];

package/dist/src/mutate/materialize.js

@@ -0,0 +1,174 @@
+import { sha256 } from "../core/hash.js";
+import { readDocumentAtRevision } from "../core/read/document.js";
+const COLUMNS = "path, kind, from_path, doc_id, rev_id, rendered_hash, commit_id";
+function fromRaw(r) {
+    return { path: r.path, kind: r.kind, fromPath: r.from_path, docId: r.doc_id, revId: r.rev_id, renderedHash: r.rendered_hash, commitId: r.commit_id };
+}
+/** The pending row at `(repo, path)`, or null. */
+export function readPending(db, repoId, path) {
+    const r = db.prepare(`SELECT ${COLUMNS} FROM pending_materializations WHERE repo_id = ? AND path = ?`).get(repoId, path);
+    return r ? fromRaw(r) : null;
+}
+/** Every pending row of a repo, in insertion order (a replaced row moves to the end). */
+export function listPending(db, repoId) {
+    return db.prepare(`SELECT ${COLUMNS} FROM pending_materializations WHERE repo_id = ? ORDER BY rowid`).all(repoId).map(fromRaw);
+}
+/** Record an intent (`INSERT OR REPLACE`: one row per path — a later request for the same path supersedes the earlier). */
+export function insertPending(db, repoId, row) {
+    db.prepare(`INSERT OR REPLACE INTO pending_materializations (repo_id, ${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(repoId, row.path, row.kind, row.fromPath, row.docId, row.revId, row.renderedHash, row.commitId);
+}
+/** Drop the intent at `(repo, path)`: the file is as recorded, or a later observation superseded it. */
+export function deletePending(db, repoId, path) {
+    db.prepare("DELETE FROM pending_materializations WHERE repo_id = ? AND path = ?").run(repoId, path);
+}
+/** The rendered hash of the revision BEFORE `revId` of the same document (what
+ *  the file held before the commit that recorded the row), or null for a first
+ *  revision / an unknown one. */
+export function priorRenderedHash(db, revId) {
+    if (revId === null)
+        return null;
+    const r = db
+        .prepare("SELECT p.rendered_hash FROM revisions r JOIN revisions p ON p.doc_id = r.doc_id AND p.seq = r.seq - 1 WHERE r.rev_id = ?")
+        .get(revId);
+    return r?.rendered_hash ?? null;
+}
+// The bytes a `write`/`rename` row materializes: spec/store §6.2 reconstruct at
+// the row's revision, which must hash to `rendered_hash` (it does for the
+// current revision; a row always names the document's current revision because
+// a later commit to the same path replaces the row). Null when nothing can be
+// rendered — the row is then left for a later materializer rather than guessed.
+function renderedBytes(store, row) {
+    if (row.revId === null)
+        return null;
+    const at = readDocumentAtRevision(store, row.docId, row.revId);
+    if (!at || !sha256(at.raw).equals(row.renderedHash))
+        return null;
+    return at.raw;
+}
+/**
+ * Materialize one row through `docStore` and, when the file is as recorded,
+ * delete the row. Returns true when the row was cleared, false when it was kept
+ * (the path holds foreign bytes — the next observation decides — or the bytes
+ * could not be rendered). Never throws for a foreign file; a doc store write
+ * failure propagates with the row intact.
+ */
+export function materializeRow(store, repoId, row, docStore, opts = {}) {
+    const db = store.db;
+    const prior = opts.priorHash !== undefined ? opts.priorHash : priorRenderedHash(db, row.revId);
+    const own = (bytes) => {
+        const h = sha256(bytes);
+        return h.equals(row.renderedHash) || (prior !== null && h.equals(prior));
+    };
+    let done;
+    switch (row.kind) {
+        case "write": {
+            const current = docStore.read(row.path);
+            if (current !== null && sha256(current).equals(row.renderedHash))
+                done = true;
+            else if (current !== null && !own(current))
+                done = false;
+            else {
+                const bytes = renderedBytes(store, row);
+                if (bytes === null)
+                    done = false;
+                else {
+                    docStore.write(row.path, bytes);
+                    done = true;
+                }
+            }
+            break;
+        }
+        case "rename": {
+            const at = docStore.read(row.path);
+            if (at !== null) {
+                // The destination is occupied: by the moved bytes (done — a stale copy of
+                // the engine's own bytes left at `from` goes) or by a foreign file (the
+                // row stays; the sweep sees `to` win and `from` become untracked).
+                if (!sha256(at).equals(row.renderedHash))
+                    done = false;
+                else {
+                    const from = row.fromPath === null ? null : docStore.read(row.fromPath);
+                    if (from !== null && own(from))
+                        docStore.remove(row.fromPath);
+                    done = true;
+                }
+            }
+            else if (row.fromPath !== null && docStore.exists(row.fromPath)) {
+                let renamed = true;
+                try {
+                    docStore.rename(row.fromPath, row.path);
+                }
+                catch {
+                    // EXDEV, a destination that appeared, a vanished source: fall back
+                    // to writing the revision's bytes at `to` (below) when `to` is still
+                    // free; a foreign file that appeared keeps the row.
+                    renamed = false;
+                }
+                if (renamed) {
+                    // A self-linking moved document renders new bytes under its new path:
+                    // the renamed file holds the previous revision, so it is rewritten.
+                    const moved = docStore.read(row.path);
+                    if (moved !== null && !sha256(moved).equals(row.renderedHash) && own(moved)) {
+                        const bytes = renderedBytes(store, row);
+                        if (bytes !== null)
+                            docStore.write(row.path, bytes);
+                    }
+                    done = true;
+                }
+                else if (docStore.read(row.path) !== null) {
+                    done = false;
+                }
+                else {
+                    const bytes = renderedBytes(store, row);
+                    if (bytes === null)
+                        done = false;
+                    else {
+                        docStore.write(row.path, bytes);
+                        const from = docStore.read(row.fromPath);
+                        if (from !== null && own(from))
+                            docStore.remove(row.fromPath);
+                        done = true;
+                    }
+                }
+            }
+            else {
+                const bytes = renderedBytes(store, row);
+                if (bytes === null)
+                    done = false;
+                else {
+                    docStore.write(row.path, bytes);
+                    done = true;
+                }
+            }
+            break;
+        }
+        case "remove": {
+            // Unlink only the bytes the deleted revision rendered; a file a human
+            // rewrote meanwhile stays (untracked now — the next sweep re-creates it).
+            const at = docStore.read(row.path);
+            if (at !== null && sha256(at).equals(row.renderedHash))
+                docStore.remove(row.path);
+            done = true;
+            break;
+        }
+    }
+    if (done)
+        deletePending(db, repoId, row.path);
+    return done;
+}
+/**
+ * Replay every pending row of a repo through `docStore`, in insertion order.
+ * Returns the paths whose rows were cleared (materialized or confirmed); rows
+ * kept for a foreign file are not listed. The recovery point of the freshness
+ * sweep (step 0) and of `recoverRepo`; the commit phase materializes its own
+ * rows per effect instead, interleaved with the stat-cache refreshes.
+ */
+export function materializePending(store, repoId, docStore) {
+    const out = [];
+    for (const row of listPending(store.db, repoId)) {
+        if (materializeRow(store, repoId, row, docStore))
+            out.push(row.path);
+    }
+    return out;
+}
+//# sourceMappingURL=materialize.js.map

package/dist/src/mutate/opset.d.ts

@@ -65,8 +65,9 @@ export interface Opset {
     /**
      * Document-level frontmatter change, when the proposed content changes it.
      * `raw` is the new frontmatter incl. fences + trailing separator (null drops
-     * it). Frontmatter is a materialization unit, not a block op; apply sets it
-     * via ApplyRequest.setFrontmatter.
+     * it). Frontmatter is a materialization unit, not a block op; the `set
+     * content` lowering sets it as the document's file head (`setHead`,
+     * spec/mutate §11.3 — the kernel request's `set_frontmatter` through 2.x).
      */
     frontmatter?: {
         raw: string | null;
@@ -81,6 +82,28 @@ export interface Opset {
     converges: boolean;
     diagnostics: string[];
 }
+/**
+ * The identity consequences of a `set content` effect as a Plan surfaces them
+ * (spec/mutate §7/§11.4, 3.0: `preview.identity[<doc id>]`): the Opset's
+ * `matcher_v`, `summary`, `diagnostics`, and per planned op its position in
+ * the plan's `opset.ops` with the `PlanOp` annotation — what `docs_update`'s
+ * `{ opset, plan }` result carried through 3.x, minus the kernel ops (they are
+ * the plan's) and `converges` (a returned plan converges; the failure is
+ * `plan_not_convergent`).
+ */
+export interface IdentityPreview {
+    matcher_v: string;
+    summary: OpsetSummary;
+    ops: {
+        op_index: number;
+        disposition: PlanDisposition;
+        blocks: string[];
+        confidence: number | null;
+        reason: string | null;
+        detail?: Record<string, unknown>;
+    }[];
+    diagnostics: string[];
+}
 /** The bare kernel ops, in order — what `apply` actually replays. */
 export declare function opsetKernelOps(opset: Opset): Op[];
 /** Compute the summary from the planned ops + carried/ambiguous counts. */
@@ -93,3 +116,5 @@ export declare function serializeOpset(opset: Opset): string;
 /** Parse a serialized opset, validating the version tag. */
 export declare function parseOpset(text: string): Opset;
 export declare function renderOpsetPlan(opset: Opset): string;
+/** The same text over a Plan's `preview.identity[<doc>]` (3.0; `omg update --dry-run`): one line per op, an empty line, the summary. */
+export declare function renderIdentityPlan(identity: IdentityPreview): string;

package/dist/src/mutate/opset.js

@@ -60,20 +60,27 @@ const VERB = {
     copied_from: "COPY  ", resurrected: "RESURR", bulk_rewrite: "REWRITE", retiled: "RETILE",
 };
 export function renderOpsetPlan(opset) {
+    const lines = planLines(opset.ops, opset.summary);
+    if (!opset.converges)
+        lines.push(`WARNING: plan does not reproduce the proposed content exactly — will not apply.`);
+    return lines.join("\n");
+}
+/** The same text over a Plan's `preview.identity[<doc>]` (3.0; `omg update --dry-run`): one line per op, an empty line, the summary. */
+export function renderIdentityPlan(identity) {
+    return planLines(identity.ops, identity.summary).join("\n");
+}
+function planLines(ops, s) {
     const lines = [];
-    for (const p of opset.ops) {
+    for (const p of ops) {
         const subject = p.blocks[0] ?? "(new)";
         const conf = p.confidence !== null ? ` ~${p.confidence.toFixed(2)}` : "";
         const why = p.reason ? ` [${p.reason}]` : "";
         lines.push(`${VERB[p.disposition]} ${subject.padEnd(9)} ${p.disposition}${conf}${why}`);
     }
-    const s = opset.summary;
     lines.push("");
     lines.push(`preserved: ${s.preserved}  updated: ${s.updated}  moved: ${s.moved}  ` +
         `created: ${s.created}  removed: ${s.removed}  split: ${s.split}  ` +
         `merged: ${s.merged}  ambiguous: ${s.ambiguous}`);
-    if (!opset.converges)
-        lines.push(`WARNING: plan does not reproduce the proposed content exactly — will not apply.`);
-    return lines.join("\n");
+    return lines;
 }
 //# sourceMappingURL=opset.js.map

package/dist/src/mutate/plan-update.d.ts

@@ -1,7 +1,5 @@
 import type { Store } from "../core/store/store.js";
 import { type ReconcileConfig } from "../reconcile/types.js";
-import { type ApplyResult } from "./apply.js";
-import type { DocStore } from "./doc-store.js";
 import { type Opset } from "./opset.js";
 export interface PlanUpdateOptions {
     config?: ReconcileConfig;
@@ -9,49 +7,6 @@ export interface PlanUpdateOptions {
 /**
  * Plan a whole-document update. `docRef` is a doc id or repo-relative path;
  * `content` is the proposed complete document. Throws doc_missing if the
- * document does not exist (a create is docsCreate's job). Never writes.
+ * document does not exist (a create is the `create` effect's job). Never writes.
  */
 export declare function planUpdate(store: Store, repoId: string, rootPath: string, docRef: string, content: string, opts?: PlanUpdateOptions): Opset;
-export interface ApplyOpsetRequest {
-    repoId: string;
-    /** Working-tree root for the default filesystem write target; omit only with an explicit `docStore`. */
-    rootPath?: string;
-    /** Write target (ADR-014 §5); defaults to a filesystem store at `rootPath`. */
-    docStore?: DocStore;
-    opset: Opset;
-    origin: {
-        actor: string;
-        reason?: string;
-    };
-    dryRun?: boolean;
-    omgbaseDir?: string;
-    /** Commit timestamp (RFC 3339 UTC); defaults to now (see `ApplyRequest.ts`). */
-    ts?: string;
-}
-/**
- * Apply an opset through the kernel write path. Validates the plan's
- * preconditions against current state first (a stale plan fails, carrying
- * current truth, rather than silently reinterpreting) and refuses a plan that
- * did not verify byte-convergent.
- */
-export declare function applyOpset(store: Store, req: ApplyOpsetRequest): ApplyResult;
-export interface DocsUpdateContext {
-    repoId: string;
-    rootPath: string;
-    omgbaseDir?: string;
-    actor?: string;
-}
-export interface DocsUpdateResult {
-    opset: Opset;
-    /** null on dry_run (plan only) */
-    result: ApplyResult | null;
-}
-/**
- * Whole-document update convenience: plan then apply. `dryRun` returns the
- * opset without executing (the note's docs.update(..., dry_run=true)).
- */
-export declare function docsUpdate(store: Store, ctx: DocsUpdateContext, docRef: string, content: string, opts?: {
-    dryRun?: boolean;
-    config?: ReconcileConfig;
-    reason?: string;
-}): DocsUpdateResult;

package/dist/src/mutate/plan-update.js

@@ -8,9 +8,9 @@ import { DEFAULT_CONFIG } from "../reconcile/types.js";
 import { loadOldMatchBlocks } from "../sync/reconciling-ingest.js";
 import { loadMutDoc } from "./load.js";
 import { renderDoc, MutationError } from "./tree.js";
-import { apply } from "./apply.js";
+import { ChangesetPlanner } from "./apply.js";
 import { lowerTopLevel, lowerReplace } from "./lower.js";
-import { summarizeOps, opsetKernelOps } from "./opset.js";
+import { summarizeOps } from "./opset.js";
 function toFlatSource(b) {
     return { type: b.type, raw: b.raw, children: b.children.map(toFlatSource) };
 }
@@ -22,9 +22,10 @@ function extractFrontmatter(blocks) {
 /**
  * Plan a whole-document update. `docRef` is a doc id or repo-relative path;
  * `content` is the proposed complete document. Throws doc_missing if the
- * document does not exist (a create is docsCreate's job). Never writes.
+ * document does not exist (a create is the `create` effect's job). Never writes.
  */
 export function planUpdate(store, repoId, rootPath, docRef, content, opts = {}) {
+    void rootPath; // kept for the call shape; the planner never writes (3.0: the verify runs the in-memory planner, no doc store)
     const config = opts.config ?? DEFAULT_CONFIG;
     const info = findDocByRef(store, repoId, docRef);
     if (!info)
@@ -51,14 +52,15 @@ export function planUpdate(store, repoId, rootPath, docRef, content, opts = {})
     // builds frontmatterRaw as `bytes + separator`; mirror that for the target.
     const targetFm = fmBlock ? fmBlock.raw + fmBlock.trivia : null;
     const fmChanged = targetFm !== oldDoc.frontmatterRaw;
-    const setFrontmatter = fmChanged ? [{ doc: docId, raw: targetFm }] : undefined;
+    // The verify's file head (spec/mutate §11.3: `leading_trivia + raw`), when the frontmatter changes.
+    const head = fmChanged ? oldDoc.leadingTrivia + (targetFm ?? "") : undefined;
     const diagnostics = [];
     // Try lowerings in order of decreasing identity preservation; take the first
     // that reproduces the proposed content exactly.
     let chosen = null;
     let converges = false;
     const t2 = lowerTopLevel(oldDoc, rest, assignmentOf(result), dispositionsOf(result));
-    const v2 = verify(store, repoId, rootPath, path, opsOf(t2), setFrontmatter, content, currentContent);
+    const v2 = verify(store, repoId, docId, path, opsOf(t2), head, content, currentContent);
     if (v2.ok) {
         chosen = t2;
         converges = true;
@@ -66,7 +68,7 @@ export function planUpdate(store, repoId, rootPath, docRef, content, opts = {})
     else {
         diagnostics.push(`top-level lowering did not reproduce the proposed content byte-for-byte (${describeDivergence(v2, tree.children, content)}); falling back to full replace`);
         const t3 = lowerReplace(oldDoc, content);
-        const v3 = verify(store, repoId, rootPath, path, opsOf(t3), setFrontmatter, content, currentContent);
+        const v3 = verify(store, repoId, docId, path, opsOf(t3), head, content, currentContent);
         if (v3.ok) {
             chosen = t3;
             converges = true;
@@ -99,14 +101,20 @@ function dispositionsOf(r) {
     return r.dispositions;
 }
 function opsOf(l) { return l.ops.map((p) => p.op); }
-// Simulate a candidate op list and check the rendered result equals the exact
-// proposed content. An invalid script throws in apply → treated as non-convergent.
-function verify(store, repoId, rootPath, path, ops, setFrontmatter, expected, currentContent) {
+// Simulate a candidate op list (§4 steps 1–4 through the incremental planner,
+// the file head set first) and check the rendered result equals the exact
+// proposed content. An invalid script throws → treated as non-convergent.
+function verify(store, repoId, docId, path, ops, head, expected, currentContent) {
     try {
-        const res = apply(store, { repoId, rootPath, ops, origin: { actor: "plan:verify" }, dryRun: true, ...(setFrontmatter ? { setFrontmatter } : {}) });
+        const planner = new ChangesetPlanner(store, repoId);
+        if (head !== undefined)
+            planner.setHead(docId, head);
+        for (const op of ops)
+            planner.push(op);
+        const res = planner.finish();
         // A doc untouched by any op (e.g. an empty plan) is absent from diffs; its
         // effective result is the unchanged current content.
-        const after = res.diffs?.[path]?.after ?? currentContent;
+        const after = res.diffs[path]?.after ?? currentContent;
         return after === expected ? { ok: true } : { ok: false, actual: after, error: null };
     }
     catch (e) {
@@ -131,60 +139,4 @@ function describeDivergence(v, proposed, expected) {
     const snippet = (s) => JSON.stringify(s.slice(off, off + 24));
     return `first divergence at byte ${off} in ${where}: expected ${snippet(expected)}, rendered ${snippet(actual)}`;
 }
-/**
- * Apply an opset through the kernel write path. Validates the plan's
- * preconditions against current state first (a stale plan fails, carrying
- * current truth, rather than silently reinterpreting) and refuses a plan that
- * did not verify byte-convergent.
- */
-export function applyOpset(store, req) {
-    const { opset } = req;
-    if (!opset.converges) {
-        const why = opset.diagnostics.length > 0 ? ` — ${opset.diagnostics[opset.diagnostics.length - 1]}` : "";
-        throw new MutationError("plan_not_convergent", `opset does not reproduce the proposed content; re-plan${why}`, { diagnostics: opset.diagnostics });
-    }
-    // Precondition: the document must still be at the revision/content the plan
-    // was computed against.
-    const docId = opset.precondition.id;
-    const row = store.db.prepare("SELECT current_rev, lower(hex(file_hash)) fh FROM docs WHERE doc_id = ? AND deleted_commit IS NULL").get(docId);
-    if (!row)
-        throw new MutationError("doc_missing", `doc ${docId} not found`, { doc: docId });
-    const stale = (opset.precondition.baseRevision !== null && row.current_rev !== opset.precondition.baseRevision) || (row.fh !== null && row.fh !== opset.precondition.hash);
-    if (stale) {
-        throw new MutationError("stale_plan", "document changed since the plan was computed; re-plan", {
-            doc: docId,
-            expected_revision: opset.precondition.baseRevision,
-            current: { revision: row.current_rev, hash: row.fh },
-            retriable: true,
-        });
-    }
-    return apply(store, {
-        repoId: req.repoId,
-        ...(req.rootPath !== undefined ? { rootPath: req.rootPath } : {}),
-        ...(req.docStore !== undefined ? { docStore: req.docStore } : {}),
-        ops: opsetKernelOps(opset),
-        origin: req.origin,
-        ...(req.dryRun !== undefined ? { dryRun: req.dryRun } : {}),
-        ...(req.omgbaseDir !== undefined ? { omgbaseDir: req.omgbaseDir } : {}),
-        ...(req.ts !== undefined ? { ts: req.ts } : {}),
-        ...(opset.frontmatter ? { setFrontmatter: [{ doc: docId, raw: opset.frontmatter.raw }] } : {}),
-    });
-}
-/**
- * Whole-document update convenience: plan then apply. `dryRun` returns the
- * opset without executing (the note's docs.update(..., dry_run=true)).
- */
-export function docsUpdate(store, ctx, docRef, content, opts = {}) {
-    const opset = planUpdate(store, ctx.repoId, ctx.rootPath, docRef, content, opts.config ? { config: opts.config } : {});
-    if (opts.dryRun)
-        return { opset, result: null };
-    const result = applyOpset(store, {
-        repoId: ctx.repoId,
-        rootPath: ctx.rootPath,
-        opset,
-        origin: { actor: ctx.actor ?? "agent:update", ...(opts.reason !== undefined ? { reason: opts.reason } : {}) },
-        ...(ctx.omgbaseDir !== undefined ? { omgbaseDir: ctx.omgbaseDir } : {}),
-    });
-    return { opset, result };
-}
 //# sourceMappingURL=plan-update.js.map