Module preparation 

The engine-owned preparation registry — the one place that says which preparations exist, on which anchor grains, at which engine touchpoint, and what each grain’s PREPARED FORM is.

A source declares at most one preparation (crate::pipeline::Source::preparation, a string identifier). The engine refuses any identifier this registry does not know (crate::binding::CapabilityError::PreparationUnsupported, raised by crate::binding::validate_binding and mirrored on the brief-render path for a record that acquired one by hand) and consults the registry at exactly two touchpoints:

• Touchpoint A — prepared form. Anchor observation asks the registry for an artifact’s prepared form before hashing it (the engine’s one per-anchor observation site). The standalone verify-anchors operation and the binding-backed verify share that site, so both inherit every registered preparation without redesign.
• Touchpoint B — delivery units. The ingest delivery path asks the registry for a source’s unit sequence (unitize): one file can carry many delivery units, addressed <path>#<key>, and the units of a whole source form one deterministic total order derived from the units’ own keys (Touchpoint::DeliveryUnits, first entry DATED_ENTRIES). A source declaring no delivery preparation keeps file-granularity delivery unchanged.

Identity. crate::binding::PREPARATION_IMPL_VERSION is hashed into every binding’s hash(D) next to the declared identifier. Landing or changing an implementation bumps the constant, which invalidates every finding keyed on the old hash by construction (ingest::findings keys on hash(D) alone).

Prepared forms per grain. The path grains (span / file) hash their bytes through crate::anchor::prepared_content_hash (the minimal canonicalization: BOM, line endings, final newline). The url grain uses the same canonicalization over observation-supplied content — the engine never fetches, so whoever observed the URL supplies the bytes at write time (AnchorInput::content) — and defaults to hash_stability: unstable, a served page being a moving target. The entity grain’s prepared form is computed from the live graph, never from supplied bytes: the canonical rendered markdown by default, or — under ENTITY_LOAD_BEARING — the stable serialization of the type’s load-bearing sections.

Non-goal, by standing decision: PDF / DOCX / audio conversion. An agent with a capable read tool extracts; the raw-byte fallback of the prepared-content hash already drift-detects a binary artifact.

Structs

DeliveryUnit

One delivery unit of a file under a delivery preparation.

Preparation

One registered preparation.

Enums

PathPrepared

What a path-grain observation yields under a source’s preparation.

Touchpoint

The engine touchpoint a registered preparation plugs into.

UnitChange

How a unit changed between two states of its file.

Constants

CODE_MAP

Code-map preparation on path-shaped sources (touchpoint A): a scoped file’s prepared form is its interface digest — imports, exports and declarations with their signatures; comments, formatting and bodies are invisible. The digest is heuristic and language-family aware by file extension: C-like families (JS/TS, Rust, Go, Java, Kotlin, Swift, C#, C, C++, PHP, Dart, Scala) keep top-level declaration lines and class or object member signatures, cut at the body’s opening brace; Python keeps imports, def/class lines (top level and one level in), decorators and upper-case module constants; a Vue single-file component is its script block under the C-like rule; JSON is its canonical compact form; every other file is taken whole. A tree-grain anchor under this preparation hashes the digest of every scoped file under the tree (path and file hash, path order), which is what closes the tree grain’s recorded-but-unhashed residue for code sources. Values inside declarations (a config object’s members, an array literal’s contents beyond its first line, a scalar property value) are body, not interface: the digest sees names and signatures. A literal object restructured between one line and many reads as a shape change.

DATED_ENTRIES

Delivery preparation on path-shaped sources: a file is a sequence of dated entries. A unit begins at every line that opens with an ISO date or date-time (2026-08-24, 2026-08-24 10:05, 2026-08-24T10:05:00Z, after any leading markdown markers such as ## , - , > , [); it runs to the next such line. Text before the first entry folds into the first unit; a file with no dated line is one unit keyed WHOLE_FILE_UNIT. The unit key is the stamp normalized to YYYY-MM-DDTHH:MM:SS (missing time parts read 00), with .2, .3, … appended to the second, third, … entry carrying the same stamp in one file, in file order — so appending entries never renames an existing unit. The order key is the normalized stamp; across a whole source, units sort by stamp, then path, then key, which is what makes a chronological corpus deliver in its own order regardless of how files were discovered. Undated files (order key empty) come first, in path order. Fractional seconds and zone designators are accepted and ignored for ordering.

ENTITY_LOAD_BEARING

Content preparation on the entity grain: the prepared form is the stable serialization of the entity type’s load-bearing sections (see load_bearing_sections), so a dependent’s prepared hash breaks when a load-bearing sentence changes and holds when a comma lands in the notes.

REGISTRY

The registry — every preparation this engine implements. The refusal in crate::binding::validate_binding is exactly “not in this list”.

WHOLE_FILE_UNIT

The key of the single unit a file yields when a delivery preparation finds no unit boundary in it — the whole file, still addressable as <path>#whole.

Functions

applies_to_namespace

Whether a registered preparation can apply over a medium whose anchor namespace is anchor_namespace (see crate::binding::medium_capabilities): at least one of the preparation’s grains must be expressible there. entity-load-bearing over a codebase source would never meet an entity-grain anchor, so it is refused at declaration rather than silently never applying.

code_map_digest

The interface digest of one file’s text under CODE_MAP.

code_map_tree_digest

The code map of a tree: one line per scoped file under it, <file digest hash> <path>, in path order — hashed by the caller through prepared_content_hash. A file joining, leaving, or changing its interface changes the tree’s map; an implementation edit does not.

default_hash_stability

The medium-declared default hash stability per grain. A url anchor defaults to unstable — a served page is a moving target, so a hash break resolves recheck, never drifted, unless the author asserts stable explicitly. Every other grain keeps its stable default.

delivery_preparation

The delivery preparation a source declares, if its declared identifier is a registered touchpoint-B entry — None for no declaration, an unregistered identifier, or a prepared-form (touchpoint A) flavour.

diff_units

The units that differ between two states of one file, keyed by unit key: a key only in after is UnitChange::Added, a key in both whose hash differs is UnitChange::Modified (the after unit), a key only in before is UnitChange::Deleted (the before unit, so its order key still places it). Unchanged units are not delivered again.

entity_load_bearing_form

The entity-load-bearing prepared form: the entity’s load-bearing sections serialized stably — each as ## <key>, a blank line, the trimmed content, a blank line — in the type’s declared section order. Keyed by section KEY (not heading) so a heading rename in the schema does not read as a content change; a section the entity does not carry is skipped. Title, metadata, and relationships are outside the form: the anchor’s artifact is the entity id, and a rename orphans the anchor on its own. Without a type definition (a type the mem’s schema does not declare) every section the entity carries is load-bearing, in the entity’s own order.

entity_prepared_hash

Touchpoint A for the entity grain: the prepared-content hash of an entity under the source’s declared preparation. None declares nothing — the canonical rendered markdown, byte-for-byte today’s form. ENTITY_LOAD_BEARING hashes entity_load_bearing_form. An identifier the registry does not know yields None: the form cannot be computed, and observation reports the anchor unobserved rather than hashing a fabricated form (validation refuses such a record at every edit path; only a hand-edited file reaches here).

is_registered

Whether id names a registered preparation.

load_bearing_sections

The load-bearing sections of a type, in the type’s declared order:

lookup

Look a declared identifier up.

path_prepared_hash

The prepared-content hash of one path-grain artifact’s bytes under preparation — the one rule anchor observation and the write-time content path share, so a hash recorded at write time is the hash a later observation computes. No preparation (or one that does not prepare path grains): the file’s bytes under the minimal canonicalization for file/span. DATED_ENTRIES: a <path>#<key> span hashes its unit (PathPrepared::UnitAbsent when the key is gone), a bare file its bytes. CODE_MAP: file/span hash the interface digest. A tree needs its files enumerated, which is the caller’s job under every preparation (code_map_tree_digest / plain_tree_digest), so it answers NoHash here.

plain_tree_digest

The plain digest of a tree: one line per scoped file under it, <prepared-content hash> <path>, in path order — hashed by the caller through prepared_content_hash. Any byte change in any scoped file, and any file joining or leaving the tree, changes the digest — the same whole-content posture a file anchor has, lifted to the directory. This is the no-preparation counterpart of code_map_tree_digest; it is what lets a plain tree anchor adjudicate deterministically instead of resting in recheck forever.

registered_identifiers

The registered identifiers, in registry order — the recovery payload of the unknown-identifier refusal.

registry

Every registered preparation.

split_unit_id

Split an artifact id into its path and, when it addresses a unit, the unit key after the first #.

supplied_content_hash

The prepared-content hash of supplied content for a grain — the write-time observation an agent performs when it hands the engine what it read (AnchorInput::content). None for a grain whose prepared form is never computed from supplied bytes: entity (computed from the live graph, so a supplied rendering could disagree with the store) and tree (its prepared form is a digest over the enumerated scoped files — observation-side work no single supplied byte-string can represent).

unit_id

The addressed form of a unit: <path>#<key>.

unit_text

The text of one unit, lines start_line..=end_line of content.

unitize

Touchpoint B: the delivery units of one file’s content under a delivery preparation, in file order. None when preparation is not a registered delivery preparation (the caller keeps file-granularity delivery).

url_prepared_hash

The url grain’s canonicalization entry: the prepared form of a URL artifact is the observation-supplied content under the same minimal canonicalization the path grains use, so a url anchor’s recorded hash means the same thing a file anchor’s does. The engine never fetches; the observer supplies the bytes.