Crate omgbase_mutate 

omgbase-mutate

The omgbase mutation kernel, Rust implementation of spec/mutate: a document loaded from the store as a mutable block tree (MutDoc), the six kernel operations over it with placement addressing and compare-and-swap expectations (ops), the splice renderer with its dirty rules ([render]), changeset placeholder resolution (changeset), the whole-document lowering (lower), the opset (opset) and the public effect vocabulary with its plan shape, conflict rules and digest (effects, 2.3). Every function here is pure: the store loads, applies, commits, and hosts the macros and document operations.

use omgbase_mutate::{MutBlock, MutDoc, At, Parent, To, op_insert, render};
use omgbase_reconcile::SequentialMinter;

let mut doc = MutDoc::new("d_0", "a.md", vec![MutBlock::new("b_0", "heading", "# Title", "\n")]);
let mut minter = SequentialMinter::new("b");
let to = To { parent: Parent::Doc, at: At::End };
let result = op_insert(&mut doc, &to, "A paragraph.", 0, None, &mut minter).unwrap();
assert_eq!(result.ids, ["b_0"]);
assert_eq!(render(&doc), "# Title\n\nA paragraph.\n");

Re-exports

pub use changeset::Op;

pub use changeset::parse_placeholder;

pub use changeset::resolve_op;

pub use changeset::resolve_placeholder;

pub use changeset::resolve_to;

pub use effects::Admission;

pub use effects::ConflictTracker;

pub use effects::Effect;

pub use effects::EffectExpect;

pub use effects::ExpectMap;

pub use effects::Field;

pub use effects::Focus;

pub use effects::FocusInfo;

pub use effects::FocusTarget;

pub use effects::IdentityOp;

pub use effects::IdentityPreview;

pub use effects::NewId;

pub use effects::NewIdKind;

pub use effects::PLAN_VERSION;

pub use effects::PLANNER_V;

pub use effects::ParentRow;

pub use effects::Plan;

pub use effects::PlanCreate;

pub use effects::PlanFrontmatter;

pub use effects::PlanMove;

pub use effects::PlanOpset;

pub use effects::PlanPreview;

pub use effects::PlanRevision;

pub use effects::PlanTombstone;

pub use effects::Preconditions;

pub use effects::Repair;

pub use effects::RetargetHitPreview;

pub use effects::RetargetPairPreview;

pub use effects::RetargetPreview;

pub use effects::SELECTION_CEILING;

pub use effects::ScalarWrite;

pub use effects::Selection;

pub use effects::SelectionExpect;

pub use effects::ShapeError;

pub use effects::ShapeFixContext;

pub use effects::Target;

pub use effects::canonical_json;

pub use effects::classify_field;

pub use effects::map_block_ids;

pub use effects::parse_new_symbol;

pub use effects::shift_placeholders;

pub use error::ErrorCode;

pub use error::MutationError;

pub use error::Result;

pub use lower::LowerResult;

pub use lower::body_of;

pub use lower::lcs;

pub use lower::lower_replace;

pub use lower::lower_top_level;

pub use lower::strip_frontmatter;

pub use ops::At;

pub use ops::Expect;

pub use ops::OpResult;

pub use ops::Parent;

pub use ops::To;

pub use ops::UpdateArgs;

pub use ops::check_content_hash;

pub use ops::check_parent_children_hash;

pub use ops::cross_doc_move;

pub use ops::default_trivia;

pub use ops::op_insert;

pub use ops::op_merge;

pub use ops::op_move;

pub use ops::op_remove;

pub use ops::op_split;

pub use ops::op_update;

pub use ops::parse_content;

pub use ops::parse_document;

pub use ops::resolve_target;

pub use ops::separates_blocks;

pub use opset::Opset;

pub use opset::OpsetPrecondition;

pub use opset::OpsetSummary;

pub use opset::PlanDisposition;

pub use opset::PlanOp;

pub use opset::summarize;

pub use render::render;

pub use render::render_block;

pub use summary::NoLookup;

pub use summary::SummaryLookup;

pub use summary::block_count;

pub use summary::plural;

pub use summary::summarize_effect;

pub use summary::visible_text_of;

pub use tree::BlockPath;

pub use tree::MutBlock;

pub use tree::MutDoc;

pub use tree::child_ids;

pub use tree::parent_children_hash;

pub use tree::raw_hash_hex;

Modules

changeset

Changesets (spec/mutate/README.md §4): the op shapes, their JSON wire form, and placeholder resolution ($<n>.ids[<i>] naming an earlier op’s result). Applying a changeset needs a store (loading, commit) and lives in omgbase-store; the pure pieces are here.

effects

Effects and plans (spec/mutate/README.md §11, mutate 2.3; ADR-021): the public intentional-write vocabulary — nine effects over document, block, node and section targets — as a planner tier over the six kernel ops. Everything here is pure: the effect and plan shapes with their JSON forms, the $new.<n> symbols a plan uses for identities it creates, the shape validator (§11.1), the focus bookkeeping the conflict rules run on (ConflictTracker, §11.3), the canonical JSON the plan digest is computed over (§11.5), and the Plan with its digest. The store resolves targets, lowers under a symbolic minter, pins the preconditions and commits a plan (omgbase-store’s effects_plan).

error

The mutation error (spec/mutate/README.md §8): a code and a data object whose listed fields (op_index, block, current, retriable, …) the fixtures compare; the message is not pinned.

lower

Lowering (spec/mutate/README.md §7.1): the matcher’s assignment over a proposed body becomes kernel ops at top-level granularity — removes, content updates with child_ids, LCS placement, retile — and the guaranteed full-replace fallback.

ops

The six operations (spec/mutate/README.md §1.1, §1.2, §2) over a MutDoc, plus the cross-document move (§2.3). Every op mutates the tree in place; an error leaves the tree partially mutated, which is fine because a changeset aborts as a whole on the first error (§4 step 3).

opset

The opset (spec/mutate/README.md §7): an inspectable plan — kernel ops annotated with the identity consequence of each — pinned to the state it was planned against, plus the summary.

render

Rendering (spec/mutate/README.md §3): the document by splice — leading trivia, the frontmatter, then every top-level block and its trivia — where a block with no dirty descendant emits its raw verbatim and a container with one is rebuilt from its children by type.

summary

preview.summary (spec/mutate/README.md §11.9, mutate 3.3): the plan as a worked example of itself — one line in words per resolved effect, in order, outside the digest, byte-identical across engines. The Receipt repeats the lines as its summary; the CLI prints them under the commit confirmation.

tree

The working tree (spec/mutate/README.md §1): a document loaded from the store into mutable blocks that carry their id, raw bytes, trailing trivia, attrs, children and a render flag. Blocks are addressed by path — the indices from the top level down — because Rust cannot hold a reference to a block while mutating its siblings; locate finds the path, the accessors resolve it.

Constants

SPEC_VERSION

The spec/mutate/VERSION this crate implements (major.minor).

VERSION

This crate’s own version (Cargo.toml), for the surface’s version tool.

Traits

Minter

A source of fresh ids. A store implements this over its CSPRNG (the reference mints b_ + 7 Crockford base32 characters) and collision-checks what it persists; runners and tests use SequentialMinter. Any FnMut() -> String is a minter too.