MiCyte10 — L1 core engine
BuiltRendered from 10-l1-core-engine.md in the public repository. Edits belong there.
micyte/core/ defines what a datum is, how addresses form SAMRAS trees, how a document reduces to one version hash, and how a sandbox is edited as a Workbook and compiled into a checked migration plan.
Nothing in micyte/core/ opens a database, reads a file or writes datum state. The MOS database is canonical. Persistence is done by the L2 executor micyte/adapters/sql/datum_workbook_apply.py. YAML is transport only.
Packages
| Package | Contents |
|---|---|
datum_semantics/ | The address, hyphae and MSS engine: parse_datum_address, build_document_version_identity, compile_hyphae_value, build_minimum_complete_path (engine.py) |
datum_io/ | The YAML transport codec: to_yaml / from_yaml for one document, workbook_to_yaml / workbook_from_yaml for a sandbox |
datum_ops/ | The edit library: Workbook, row ops, node ops, the reference index, the compiler, the migration planner, the rule checks |
mss/ | compute_mss_hash and derive_hyphae_chain (both delegate to the engine), row-order canonicalization, the binary document codec and the transport encoding (61) |
document_naming/ | Canonical document ids: format_canonical_document_id, parse_canonical_document_id, is_canonical_document_id, derive_canonical_id_from_legacy |
structures/samras/ | The SAMRAS structure codec, validation, mutation, and reconstruction from datum rows |
structures/hops/, hops/ | HOPS coordinate and time-address codecs, chronology, polygon-group assembly |
datum_rules/ | classify_row / validate_row: row shape and arity (rudi, scalar, pairs, record) |
datum_refs/ | parse_datum_ref / normalize_datum_ref: the <msn_id>.<datum_address> reference grammar |
datum_templates/ | Archetype templates: scaffold, recognize, column map for CSV intake |
archetypes/, hyphae_flags/ | Archetype shapes and the flag registry (60) |
Addresses
Two address kinds are written as hyphenated integers and mean different things.
- A datum address is the three-segment row key
layer-value_group-iteration, for example4-2-17.(layer, value_group)is a row family.ReorderRowrefuses a move that leaves the family. - A node address is a variable-depth position in a SAMRAS tree, for example
4,4-9,1-3-2-5-1, stored as a magnitude inside a row. Every segment is a positive integer.micyte/core/datum_ops/node_addrs.pyholds its algebra;remove_subtree_remapandrelocate_subtree_remapcompute the renumbering when a subtree moves.
Rudi datums and the hyphae chain
Rudi datums are at layer 0, value group 0 (0-0-*). A datum's full transitive dependency set is its hyphae value. derive_hyphae_chain walks a datum's reference closure and returns [0-0-1 … 0-0-K], where K is the highest rudi iteration reached; every position from 1 to K is included.
Version identity
build_document_version_identity computes a document's version hash. It is the only implementation; compute_mss_hash calls it.
- Default policy
mos.mss_sha256_v1: SHA-256 over canonical JSON (sorted keys, no whitespace) ofsource_kind,document_metadata, and every row's{datum_address, raw}in address order. - With
MOS_CANONICAL_HASH=mss_binary_v4in the environment: the MSS-DOC.v4 transport hash over the rows.
The store refuses a write whose policy differs from the policy it holds. 61 specifies the forms.
SAMRAS and HOPS codecs
A SAMRAS magnitude encodes the prefix closure of a node set as a canonical bitstream rooted at 0-0-5. encode_canonical_structure_from_addresses writes a unary address-width field, a unary stop-count-width field, the stop count, the stop addresses, then the value tokens. decode_canonical_bitstream reverses it and re-encodes to confirm the input was canonical.
Which anchor row holds which structure is read from the row's own label (lcl-SAMRAS is the structure of the sheet named lcl), by discover_samras_structures in micyte/core/datum_ops/samras_deps.py. check_denotation checks that a stored magnitude still matches its sheet's node set.
HOPS encodes geospatial and temporal positions. decode_hops_coordinate_token reads a numeric-hyphen token as a mixed-radix longitude/latitude partition; structures/hops/ also holds the time-address helpers.
Document ids
A canonical id is <prefix>.<msn_id>.[<sandbox>.]<name>.<hash>, where the hash is the document's version hash. lv. (live datum) ids carry a sandbox segment; stl. (payload), cptr. (cache pointer) and art. (artifact) ids do not. The id is not part of the hashed content, so re-minting an unchanged document gives the same id. The SQL adapters call parse_canonical_document_id before persisting.
Editing a sandbox
- Load.
load_workbookin the L2 executor reads a sandbox into aWorkbook(named sheets). - Edit. The UI returns edited WORKBOOK-YAML.
- Compile.
compile_workbookdiffs the baseline and the edit, tracks node definitions by title, and infersRelocateNode,RenameNode,MintNodeandDropNode, followed byRecompileMagnitudeandRebuildCollectionwhen a node set changed. A reference re-point with no node move is not inferred; it is expressed withRepointNodeorRewriteRefs. - Apply ops.
apply_sequencethreads each op'sWorkbookDeltaforward. Node ops cascade to every sheet that references a moved node, found withbuild_reference_index. - Plan.
plan_migrationruns the ops, runscheck_step(a hard issue aborts), checks each SAMRAS magnitude against its sheet's node set, re-mints the id of every sheet whose content hash changed, and returns aMigrationPlan(touched sheets, write order, verification expectations, advisories). - Apply to the store.
execute_migrationbacks up, writes in plan order, and verifies against the plan.
Reference checks use the node-reference markers of the document's own namespace (node_ref_markers_for), because the same marker address means different fields in different namespaces.
Read path and write path
The write path above goes through WORKBOOK-YAML. The read path does not: the workbench service (micyte/tools/workbench_ui/service.py) reads the catalog from SQL and projects it to a render model directly. A single YAML-materialized surface for both reading and writing is not built.