@omgbase/core 0.1.0

package/dist/src/mutate/ops.js

@@ -0,0 +1,513 @@
+import { mintId } from "../core/ids.js";
+import { parseTree } from "../core/parse/tree.js";
+import { adapterForFormat } from "../format/index.js";
+import { MutationError, locate, rawHashHex, parentChildrenHash, markContainerDirty, ownerOf } from "./tree.js";
+function defaultTrivia(format) {
+    if (format === "json")
+        return ",\n";
+    if (format === "yaml")
+        return "\n";
+    return "\n\n";
+}
+// Parse op-supplied content into MutBlocks (ids minted). Uses the format's
+// adapter when available; falls back to markdown. The parsed blocks are CLEAN:
+// a freshly parsed block's raw is the byte-exact source for its whole subtree,
+// so renderDoc must emit it verbatim. Marking it dirty would make renderBlock
+// rebuild the container from its children, which cannot reproduce a blockquote
+// (`> ` markers live only in the container raw) or a table (the delimiter row
+// is not a child node) — the op that splices these blocks in is responsible
+// for invalidating the CONTAINER it lands in (markContainerDirty).
+function parseContentToBlocks(content, format) {
+    const adapter = adapterForFormat(format);
+    const normalized = content.endsWith("\n") ? content : content + "\n";
+    const tree = adapter ? adapter.parse(normalized) : parseTree(normalized);
+    const trivia = defaultTrivia(format);
+    const toMut = (b) => ({
+        id: mintId("b"),
+        type: b.type,
+        raw: b.raw,
+        trivia: b.trivia || trivia,
+        attrs: b.attrs,
+        children: b.children.map(toMut),
+        dirty: false,
+    });
+    return tree.children.filter((b) => b.type !== "frontmatter").map(toMut);
+}
+// Resolve a To into a target sibling list + insertion index.
+function resolveTarget(doc, to) {
+    let siblings;
+    if (to.parent === null || (typeof to.parent === "object" && "doc" in to.parent)) {
+        siblings = doc.children;
+    }
+    else if (typeof to.parent === "object" && "heading" in to.parent) {
+        // scope:section — resolve the section's range at top level: insert before
+        // the next peer/higher heading (04 §1.1). Section blocks live at top level.
+        return resolveSection(doc, to.parent.heading, to.at);
+    }
+    else {
+        const found = locate(doc, to.parent);
+        if (!found)
+            throw new MutationError("parent_missing", `parent ${String(to.parent)} not found`);
+        siblings = found.block.children;
+    }
+    return { siblings, index: resolveIndex(siblings, to.at) };
+}
+function resolveIndex(siblings, at) {
+    if (at === "start")
+        return 0;
+    if (at === "end")
+        return siblings.length;
+    if ("before" in at) {
+        const i = siblings.findIndex((b) => b.id === at.before);
+        if (i < 0)
+            throw new MutationError("target_missing", `anchor ${at.before} not found`);
+        return i;
+    }
+    const i = siblings.findIndex((b) => b.id === at.after);
+    if (i < 0)
+        throw new MutationError("target_missing", `anchor ${at.after} not found`);
+    return i + 1;
+}
+// A section runs from its heading to the block before the next heading of equal
+// or higher level. Blocks are top-level (flat containment, 01 §3.2).
+function resolveSection(doc, headingId, at) {
+    const hIdx = doc.children.findIndex((b) => b.id === headingId);
+    if (hIdx < 0)
+        throw new MutationError("target_missing", `heading ${headingId} not found`);
+    const level = Number(doc.children[hIdx].attrs.level ?? 1);
+    let end = doc.children.length;
+    for (let i = hIdx + 1; i < doc.children.length; i++) {
+        const b = doc.children[i];
+        if (b.type === "heading" && Number(b.attrs.level ?? 1) <= level) {
+            end = i;
+            break;
+        }
+    }
+    if (at === "end")
+        return { siblings: doc.children, index: end };
+    if (at === "start")
+        return { siblings: doc.children, index: hIdx + 1 };
+    return { siblings: doc.children, index: resolveIndex(doc.children, at) };
+}
+function checkContentHash(block, expect, opIndex) {
+    if (!expect?.content_hash) {
+        // Hand back the current hash + bytes so the caller can retry immediately
+        // (same actionable shape as a hash MISMATCH below) instead of a separate
+        // hydration read — an agent may hold fresh ids yet lack the CAS token.
+        throw new MutationError("stale_expectation", "expect.content_hash required", {
+            op_index: opIndex,
+            block: block.id,
+            current: { content_hash: rawHashHex(block.raw), markdown: block.raw },
+            retriable: true,
+        });
+    }
+    const current = rawHashHex(block.raw);
+    if (current !== expect.content_hash) {
+        throw new MutationError("stale_expectation", "content hash mismatch", {
+            op_index: opIndex,
+            block: block.id,
+            expected_content_hash: expect.content_hash,
+            current: { content_hash: current, markdown: block.raw },
+            retriable: true,
+        });
+    }
+}
+// Assign known ids onto a freshly-parsed subtree by positional key (parentKey +
+// '/' + index), the same convention flatten()/known-ids use. Keys absent from
+// the map leave the block's minted id in place (a genuinely new child).
+function assignChildIds(children, childIds, parentKey) {
+    children.forEach((c, i) => {
+        const key = `${parentKey}/${i}`;
+        const id = childIds[key];
+        if (id)
+            c.id = id;
+        if (c.children.length > 0)
+            assignChildIds(c.children, childIds, key);
+    });
+}
+// Wrap a non-list parsed block as a list_item (marker prepended) so it can be
+// inserted into a list. The marker is normalized on render (renderItem strips
+// and re-applies it, renumbering ordered lists), so `- ` here is just a seed.
+function wrapAsItem(b) {
+    return { id: mintId("b"), type: "list_item", raw: `- ${b.raw}`, trivia: "", attrs: {}, children: [], dirty: true };
+}
+// Mark a block and its whole subtree clean (dirty=false), so renderDoc emits the
+// block's retained raw verbatim rather than rebuilding it from children.
+function markSubtreeClean(b) {
+    b.dirty = false;
+    for (const c of b.children)
+        markSubtreeClean(c);
+}
+// ---- the six ops ------------------------------------------------------------
+export function opInsert(doc, to, markdown) {
+    const { siblings, index } = resolveTarget(doc, to);
+    let blocks = parseContentToBlocks(markdown, doc.format);
+    // Inserting into a list: the content must land as list ITEMS, not a nested
+    // list. Markdown `- x` parses to a `list` wrapping a `list_item`; unwrap it to
+    // its items (a bare block is wrapped as one item). Then mark the list dirty so
+    // it re-renders from its new items. (04 §1 / lists_insert_item.)
+    const container = ownerOf(doc, siblings);
+    if (container?.type === "list" && doc.format === "markdown") {
+        blocks = blocks.flatMap((b) => (b.type === "list" ? b.children : [wrapAsItem(b)]));
+        siblings.splice(index, 0, ...blocks);
+        container.dirty = true;
+        return { ids: blocks.map((b) => b.id) };
+    }
+    // Trivia is document tiling rendered independently of a block's raw, so the
+    // separators fixed up here set no `dirty` flag — no block content changed.
+    // Only the top-level list is rendered from trivia (nested containers are
+    // re-emitted from children with single-newline joins, so their trivia is
+    // inert); confine separator normalization to that list.
+    if (siblings === doc.children) {
+        const sep = defaultTrivia(doc.format);
+        // Separator BEFORE the run: the block now preceding it must end at a real
+        // block boundary, or the two render jammed together — e.g. appending a
+        // heading at the end of a section whose last paragraph carried only a
+        // single trailing "\n" glued "…text\n## Heading" with no blank line.
+        if (index > 0) {
+            const prev = siblings[index - 1];
+            if (!separatesBlocks(prev.trivia, doc.format))
+                prev.trivia = sep;
+        }
+        // Separator AFTER the run: a mid-document insert leaves a following block,
+        // and the parsed run's last block ends in a lone "\n" — bump it too.
+        if (blocks.length > 0 && index < siblings.length) {
+            const last = blocks[blocks.length - 1];
+            if (!separatesBlocks(last.trivia, doc.format))
+                last.trivia = sep;
+        }
+    }
+    siblings.splice(index, 0, ...blocks);
+    // A nested insert (into a blockquote/table/list item) changes the owning
+    // container's children, so its cached raw is stale — rebuild it from children.
+    if (siblings !== doc.children)
+        markContainerDirty(doc, siblings);
+    return { ids: blocks.map((b) => b.id) };
+}
+// Does this trailing trivia hold a real block boundary? Markdown block-level
+// content needs a blank line between blocks (a lone "\n" renders as a soft
+// continuation, jamming an ATX heading onto the previous paragraph); other
+// formats only need the separator to be non-empty.
+function separatesBlocks(trivia, format) {
+    return format === "markdown" ? trivia.includes("\n\n") : trivia !== "";
+}
+export function opUpdate(doc, blockId, opIndex, markdown, attrs, expect, trivia, childIds) {
+    const found = locate(doc, blockId);
+    if (!found)
+        throw new MutationError("block_missing", `block ${blockId} not found`, { op_index: opIndex, block: blockId });
+    // Content CAS is required only for a content edit (`markdown`). Attr- and
+    // trivia-only updates change no block content, so they follow the placement
+    // convention (no content CAS); a supplied `expect.content_hash` is still
+    // honored when present (CAS honesty, README invariant 6). This lets the
+    // whole-doc planner set exact trailing trivia after structural ops without
+    // juggling post-op content hashes across the changeset.
+    if (markdown !== undefined || expect?.content_hash !== undefined)
+        checkContentHash(found.block, expect, opIndex);
+    // Blocks minted from MULTI-block content: the target takes the first parsed
+    // block (keeping its id); the rest become fresh siblings right after it.
+    const extra = [];
+    if (markdown !== undefined) {
+        if (doc.format === "markdown" && found.block.type === "list_item") {
+            // A list item can't be re-parsed as a standalone block (`- x` parses to a
+            // list, `x` loses the marker). Unwrap: accept a list (its first item
+            // replaces this one, further items become following siblings) or a bare
+            // block (wrap it), keep this block a list_item, and mark the containing
+            // list dirty so it re-renders from its items.
+            const parsed = parseContentToBlocks(markdown, doc.format);
+            if (parsed.length !== 1) {
+                throw new MutationError("type_mismatch", "list-item update content must be ONE list (`- a\\n- b`: first item replaces, the rest follow as siblings) or ONE bare block", {
+                    op_index: opIndex, block: blockId, hint: "to put mixed content under an item, update the item then blocks_insert the rest with `to` = the item",
+                });
+            }
+            const only = parsed[0];
+            if (only.type === "list") {
+                if (only.children.length === 0)
+                    throw new MutationError("type_mismatch", "list-item update must yield at least one item", { op_index: opIndex, block: blockId });
+                found.block.raw = only.children[0].raw;
+                found.block.children = only.children[0].children;
+                extra.push(...only.children.slice(1));
+            }
+            else {
+                found.block.raw = `- ${only.raw}`;
+                found.block.children = [];
+            }
+            found.block.dirty = true;
+            markContainerDirty(doc, found.siblings);
+        }
+        else if (doc.format === "markdown") {
+            const parsed = parseContentToBlocks(markdown, doc.format);
+            if (parsed.length === 0)
+                throw new MutationError("type_mismatch", "update content must contain at least one block", { op_index: opIndex, block: blockId });
+            if (parsed.length > 1 && childIds !== undefined)
+                throw new MutationError("type_mismatch", "update with childIds must be a single block", { op_index: opIndex, block: blockId });
+            extra.push(...parsed.slice(1));
+            const nb = parsed[0];
+            found.block.raw = nb.raw;
+            found.block.type = nb.type;
+            found.block.attrs = nb.attrs;
+            found.block.children = nb.children;
+            // Thread known child identities onto the re-parsed subtree, positionally
+            // (mirroring flatten()/known-ids keys, relative to this block's children).
+            // A whole-container update (e.g. a list) re-parses its children, minting
+            // fresh ids by default; supplying childIds lets the whole-document update
+            // planner preserve reconcile-carried identity for the container's items
+            // (nested identity) — the commit re-parse threads exactly these ids.
+            if (childIds !== undefined && found.block.children.length > 0) {
+                assignChildIds(found.block.children, childIds, "");
+            }
+            // Render the block VERBATIM from its op-supplied raw (the exact target
+            // bytes) rather than rebuilding from children — the splice renderer's
+            // child rebuild can't reproduce nested/loose list formatting, blockquote
+            // markers, or a table's delimiter row. The re-parsed children remain
+            // (clean) only to carry ids for the commit re-parse. The block's OWN raw
+            // is fresh, so it is not dirty; what is stale is the raw of the container
+            // it lives in (a nested update), which is invalidated instead.
+            markSubtreeClean(found.block);
+            markContainerDirty(doc, found.siblings);
+        }
+        else {
+            // Non-markdown: raw swap preserves the block's type and attrs. Fragments
+            // like JSON properties aren't valid standalone documents, so re-parsing
+            // would corrupt the block kind (e.g. json:property → json:scalar).
+            found.block.raw = markdown;
+            found.block.children = [];
+            found.block.dirty = true;
+        }
+    }
+    if (attrs) {
+        found.block.attrs = { ...found.block.attrs, ...attrs };
+        // attr-only edits (e.g. task checkbox) re-render the marker: mark dirty and
+        // rewrite the raw checkbox if present.
+        if ("checked" in attrs && (found.block.type === "task" || found.block.type === "list_item")) {
+            found.block.raw = found.block.raw.replace(/\[[ xX]\]/, attrs.checked ? "[x]" : "[ ]");
+            found.block.type = "task";
+            found.block.dirty = true;
+        }
+    }
+    // Trailing trivia (positional tiling): set verbatim. No content change, no
+    // dirty flag — renderDoc emits a top-level block's trivia unconditionally.
+    if (trivia !== undefined)
+        found.block.trivia = trivia;
+    if (extra.length > 0) {
+        // Splice the surplus blocks in after the target. The target's trailing
+        // trivia is the document's tiling AFTER the whole run, so it moves to the
+        // last new block; every seam inside the run must separate blocks (top level
+        // only — nested containers re-render from their children).
+        const tail = found.block.trivia;
+        if (found.siblings === doc.children) {
+            const sep = defaultTrivia(doc.format);
+            if (!separatesBlocks(found.block.trivia, doc.format))
+                found.block.trivia = sep;
+            for (const b of extra.slice(0, -1))
+                if (!separatesBlocks(b.trivia, doc.format))
+                    b.trivia = sep;
+        }
+        extra[extra.length - 1].trivia = tail;
+        found.siblings.splice(found.index + 1, 0, ...extra);
+        markContainerDirty(doc, found.siblings);
+    }
+    return { ids: [blockId, ...extra.map((b) => b.id)] };
+}
+export function opMove(doc, blockIds, to, opIndex) {
+    if (blockIds.length === 0)
+        throw new MutationError("not_contiguous", "move requires ≥1 block");
+    // Locate all; assert contiguous siblings.
+    const located = blockIds.map((id) => {
+        const f = locate(doc, id);
+        if (!f)
+            throw new MutationError("block_missing", `block ${id} not found`, { op_index: opIndex, block: id });
+        return f;
+    });
+    const siblings = located[0].siblings;
+    const indices = located.map((l) => l.index).sort((a, b) => a - b);
+    for (let i = 1; i < indices.length; i++) {
+        if (located[i].siblings !== siblings || indices[i] !== indices[i - 1] + 1) {
+            throw new MutationError("not_contiguous", "move blocks must be a contiguous sibling run", { op_index: opIndex });
+        }
+    }
+    // cycle_move: target parent must not be inside the moved subtree.
+    const movedIds = new Set();
+    const collect = (b) => { movedIds.add(b.id); b.children.forEach(collect); };
+    located.forEach((l) => collect(l.block));
+    if (typeof to.parent === "string" && movedIds.has(to.parent)) {
+        throw new MutationError("cycle_move", "target is inside the moved subtree", { op_index: opIndex });
+    }
+    // Extract (preserve order) then re-insert at the target.
+    const moving = located.map((l) => l.block);
+    for (const m of moving) {
+        const idx = siblings.indexOf(m);
+        if (idx >= 0)
+            siblings.splice(idx, 1);
+    }
+    const { siblings: dstSiblings, index } = resolveTarget(doc, to);
+    dstSiblings.splice(index, 0, ...moving);
+    // A move within/into a nested container invalidates that container's cached
+    // raw (and the source's) — mark them so they re-render from children. No-op
+    // for the top-level list, which renders directly and is healed below.
+    markContainerDirty(doc, siblings);
+    markContainerDirty(doc, dstSiblings);
+    // Heal top-level seams so relocated blocks never render jammed together.
+    // Trivia is positional tiling (03 §2.2), not owned by the block: a block that
+    // was last in the source list carried a lone "\n" that, once interior, would
+    // soft-merge with its new neighbour (two paragraphs → one). Both the source
+    // gap and the destination seam are re-tiled. Only the top-level list renders
+    // from trivia (nested containers re-emit from children), so confine to it.
+    if (siblings === doc.children)
+        healTopLevelSeams(doc.children, doc.format);
+    if (dstSiblings === doc.children && dstSiblings !== siblings)
+        healTopLevelSeams(doc.children, doc.format);
+    return { ids: blockIds };
+}
+// Ensure every non-last top-level block ends at a real block boundary. Leaves
+// already-separating trivia untouched (idempotent, byte-preserving where the
+// document is already well-formed) and never touches the last block's trailing
+// trivia (that is the document's trailing bytes). Exact target trivia is the
+// planner's job via `update { trivia }`; this only guarantees well-formedness.
+function healTopLevelSeams(children, format) {
+    const sep = defaultTrivia(format);
+    for (let i = 0; i < children.length - 1; i++) {
+        const b = children[i];
+        if (!separatesBlocks(b.trivia, format))
+            b.trivia = sep;
+    }
+}
+export function opRemove(doc, blockIds, opIndex, expectPer) {
+    // Pass 1 — validate while every block is still in place: a genuinely unknown
+    // id is block_missing, and each CAS expectation is checked against the block's
+    // current bytes. Then collapse the set to its TOP-MOST members: a block whose
+    // ancestor is also being removed goes with that ancestor's subtree. A caller
+    // holding a flat id list (docs_read include_ids) can hand over a container
+    // and its children together without the child's lookup failing after the
+    // container has already taken it. Duplicates collapse too.
+    const set = new Set(blockIds);
+    const tops = [];
+    const seen = new Set();
+    for (const id of blockIds) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const found = locate(doc, id);
+        if (!found) {
+            throw new MutationError("block_missing", `block ${id} not found in this document`, {
+                op_index: opIndex,
+                block: id,
+                hint: "the id is not a live block of the targeted document — it may have been removed by an earlier op in this changeset (removing a block removes its whole subtree), or never existed",
+            });
+        }
+        if (expectPer?.[id])
+            checkContentHash(found.block, expectPer[id], opIndex);
+        if (!hasAncestorIn(doc, found.siblings, set))
+            tops.push(id);
+    }
+    // Pass 2 — remove the top-most blocks; `removed` reports every block that
+    // actually left the tree (each subtree walked), so the caller sees the
+    // collapsed descendants too.
+    const removed = [];
+    for (const id of tops) {
+        const found = locate(doc, id);
+        const collect = (b) => { removed.push(b.id); b.children.forEach(collect); };
+        collect(found.block);
+        found.siblings.splice(found.index, 1);
+        // Removing a nested block invalidates its container's cached raw; a container
+        // emptied by the removal is itself removed (an empty list would render blank).
+        pruneOrDirty(doc, found.siblings);
+    }
+    return { ids: blockIds, removed };
+}
+// Does any block owning `siblings` (walking up to the document root) have an id
+// in `set`? I.e. is a block found in `siblings` a descendant of a block in `set`.
+function hasAncestorIn(doc, siblings, set) {
+    let cur = siblings;
+    for (;;) {
+        const owner = ownerOf(doc, cur);
+        if (!owner)
+            return false;
+        if (set.has(owner.id))
+            return true;
+        const f = locate(doc, owner.id);
+        if (!f)
+            return false;
+        cur = f.siblings;
+    }
+}
+// After removing from `siblings`: if that list is now empty, remove the empty
+// container from its own parent (recursing); otherwise mark it dirty so it
+// re-renders from its remaining children.
+function pruneOrDirty(doc, siblings) {
+    const owner = ownerOf(doc, siblings);
+    if (!owner)
+        return; // top-level list: renderDoc renders it directly
+    if (owner.children.length === 0) {
+        const f = locate(doc, owner.id);
+        if (f) {
+            f.siblings.splice(f.index, 1);
+            pruneOrDirty(doc, f.siblings);
+        }
+    }
+    else {
+        owner.dirty = true;
+    }
+}
+export function opSplit(doc, blockId, at, opIndex, expect) {
+    const found = locate(doc, blockId);
+    if (!found)
+        throw new MutationError("block_missing", `block ${blockId} not found`, { op_index: opIndex, block: blockId });
+    checkContentHash(found.block, expect, opIndex);
+    const raw = found.block.raw;
+    const cuts = [0, ...at, raw.length].sort((a, b) => a - b);
+    const pieces = [];
+    for (let i = 1; i < cuts.length; i++)
+        pieces.push(raw.slice(cuts[i - 1], cuts[i]));
+    const nonEmpty = pieces.filter((p) => p.trim().length > 0);
+    if (nonEmpty.length < 2)
+        throw new MutationError("type_mismatch", "split must yield ≥2 non-empty fragments");
+    // First fragment carries the id (authored intent, 04 §1); rest minted.
+    found.block.raw = nonEmpty[0];
+    found.block.dirty = true;
+    const newBlocks = nonEmpty.slice(1).map((p) => ({
+        id: mintId("b"), type: found.block.type, raw: p, trivia: "\n\n", attrs: { ...found.block.attrs }, children: [], dirty: true,
+    }));
+    found.siblings.splice(found.index + 1, 0, ...newBlocks);
+    return { ids: [blockId, ...newBlocks.map((b) => b.id)] };
+}
+export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
+    if (blockIds.length < 2)
+        throw new MutationError("not_contiguous", "merge requires ≥2 blocks");
+    const located = blockIds.map((id) => {
+        const f = locate(doc, id);
+        if (!f)
+            throw new MutationError("block_missing", `block ${id} not found`, { op_index: opIndex, block: id });
+        return f;
+    });
+    const siblings = located[0].siblings;
+    const type = located[0].block.type;
+    const indices = located.map((l) => l.index).sort((a, b) => a - b);
+    for (let i = 0; i < located.length; i++) {
+        if (located[i].siblings !== siblings)
+            throw new MutationError("not_contiguous", "merge blocks must share a parent", { op_index: opIndex });
+        if (located[i].block.type !== type)
+            throw new MutationError("type_mismatch", "merge blocks must share a type", { op_index: opIndex });
+        if (expectPer?.[blockIds[i]])
+            checkContentHash(located[i].block, expectPer[blockIds[i]], opIndex);
+    }
+    for (let i = 1; i < indices.length; i++)
+        if (indices[i] !== indices[i - 1] + 1)
+            throw new MutationError("not_contiguous", "merge blocks must be contiguous", { op_index: opIndex });
+    const ordered = indices.map((i) => siblings[i]);
+    const first = ordered[0];
+    first.raw = ordered.map((b) => b.raw).join(separator);
+    first.dirty = true;
+    const mergedInto = ordered.slice(1).map((b) => b.id);
+    // remove the others (highest index first)
+    for (let i = indices.length - 1; i >= 1; i--)
+        siblings.splice(indices[i], 1);
+    return { ids: [first.id], mergedInto };
+}
+export function checkParentChildrenHash(doc, parentId, expected, opIndex) {
+    const list = parentId ? locate(doc, parentId)?.block.children ?? doc.children : doc.children;
+    const current = parentChildrenHash(list);
+    if (current !== expected) {
+        throw new MutationError("stale_expectation", "parent_children_hash mismatch", { op_index: opIndex, current: { parent_children_hash: current }, retriable: true });
+    }
+}
+//# sourceMappingURL=ops.js.map

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

@@ -0,0 +1,92 @@
+import type { Op } from "./apply.js";
+export type OpsetKind = "doc_update";
+/**
+ * The identity consequence of one planned op, in the reconciler's vocabulary
+ * (03 §4). Kept as a string so mutate/ carries no runtime dependency on
+ * reconcile/; the values mirror reconcile/types.ts DispositionKind plus the
+ * synthetic `retiled` for a trailing-trivia-only fixup the planner emits to
+ * reproduce the proposed bytes exactly.
+ */
+export type PlanDisposition = "same" | "edited" | "moved" | "edited_moved" | "inserted" | "deleted" | "split_from" | "merged_into" | "copied_from" | "resurrected" | "bulk_rewrite" | "retiled";
+/** State the opset was planned against; applying against different state fails. */
+export interface OpsetPrecondition {
+    /** doc id the plan targets */
+    doc: string;
+    path: string;
+    /** the document's current revision id at plan time (null for a doc with no committed revision yet) */
+    baseRevision: string | null;
+    /** sha256 hex of the document's current rendered bytes (docs.file_hash) at plan time */
+    baseContentHash: string;
+}
+/** One kernel op plus the identity consequence the planner attributes to it. */
+export interface PlanOp {
+    /** the executable kernel op (unchanged semantics) */
+    op: Op;
+    /** identity disposition this op realizes (planning metadata) */
+    disposition: PlanDisposition;
+    /**
+     * subject block ids for human/agent inspection: the carried id(s) an
+     * update/move/remove acts on, the survivor for merge, the origin for split.
+     * Empty for an insert of genuinely new structure (its id is minted at apply).
+     */
+    blocks: string[];
+    confidence: number | null;
+    reason: string | null;
+    detail?: Record<string, unknown>;
+}
+/** Identity accounting over the reconciliation (for dry-run summaries). */
+export interface OpsetSummary {
+    /** blocks carried with unchanged content and position */
+    preserved: number;
+    updated: number;
+    moved: number;
+    created: number;
+    removed: number;
+    split: number;
+    merged: number;
+    /** low-confidence carries / recorded near-misses the matcher flagged */
+    ambiguous: number;
+}
+export interface Opset {
+    version: 1;
+    kind: OpsetKind;
+    target: {
+        doc: string;
+        path: string;
+    };
+    precondition: OpsetPrecondition;
+    /** matcher version that produced the identity decisions (reproducibility) */
+    matcherV: string;
+    /** the planned ops, each annotated with its identity consequence */
+    ops: PlanOp[];
+    /**
+     * 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.
+     */
+    frontmatter?: {
+        raw: string | null;
+    };
+    summary: OpsetSummary;
+    /**
+     * Verified by the planner: replaying `ops` from the base state renders to
+     * exactly the proposed content. When false, `apply(opset)` refuses (a plan
+     * that cannot reproduce the intended bytes is never applied silently); the
+     * caller inspects `diagnostics` and re-plans or edits.
+     */
+    converges: boolean;
+    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. */
+export declare function summarizeOps(ops: PlanOp[], counts: {
+    preserved: number;
+    ambiguous: number;
+}): OpsetSummary;
+/** Serialize an opset to a stable JSON string (ops are plain JSON). */
+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;