Module document

Expand description

The document root and the index derived from it. Rationale: docs/doc-ng-design-notes.md.

Structs§

BlockIndex
Content: Everything the document is, and exactly what a file holds: the entity tables keyed by id, the title block flattened over them, and the artwork payloads. BTreeMap rather than a hash map so the file is written in id order without a sorting pass to forget.
DocIndex: The derived index over the whole document — never authoritative. A child whose owner has been deleted is indexed nowhere (its owner has no entry).
Document: Authored state only — the derived index is built beside it (DocIndex). The document is the implicit root of the containment tree: not an element, cannot be deleted, moved, or raced. Blocks whose parent is Id::NULL live at document level.
FormatVersion: The version a file declares. A version from the future is refused at the decode boundary rather than guessed at — the field exists precisely because a newer writer may have used syntax this build would otherwise misread as something else.
IndexedDocument: A document and the index over it, bundled so they cannot be mismatched.
RouteIndex
TitleBlock: The document’s own registers — a mechanical drawing’s title block, expected to grow fields (author, revision notes, …). The singleton exception: never created by an op, no id, no lifecycle — OpCodes::Document is update-only.
UnsupportedVersion

CURRENT_VERSION: The format version this build writes, and the guard against reading a file from a newer one. Bumped whenever a change would make an older reader misinterpret a file rather than fail on it.

apply 🔒
apply_crud_to_entity 🔒: None means the id is invalid for the op: unknown for Update/Delete, already taken for Create — the allocator never re-mints a number the document has held, so a duplicate create is a replay or a bug, never a merge.
chronological: One order, every consumer (docs/doc-ng-design-notes.md, “Draw order is a derived policy”): ascending id — which is creation order, ids being monotonic counters — so painting in this order puts the newest entity on top. Hit-testing walks it back-to-front and the router places first-come-first-served, so the three cannot disagree.
dangling_endpoints 🔒: A route’s endpoints are the one reference the index cannot quietly drop: an orphaned route is still indexed and still drawn, whereas a child whose owner is gone leaves the index with its scope. So a pin may not leave under a route — the delete cascade emits the dependent route deletes itself, which is what keeps this refusal unreachable from the editor.
validate 🔒: Run against the folded document, so an op’s position within the commit never matters: a cascade may delete a pin before or after the route hanging off it and be judged the same either way.