Furth FortuneM9 reference

Mission foundation / System overview

MerBuf

Typed bytes with schema identity

MerBuf encodes declared values into compact bytes. The payload carries enough type and schema identity for a receiver to check it before use.

Inside the system

Architecture plates

Each plate preserves the internal layout, paths, boundaries, and highlighted decisions. Use the short label first, then follow the lines through the system.

Plate 01

Two shapes, one format, and no JSON in the middle

the one test · two shapes · what refuses

SOURCE a value to persistapp state, record, message THE ONE TEST is the schema known?declared columns exist SHAPE defined entity db.entity.draft(type) db.entity.save, typed MerDB dynamic MerBuf merbuf.new() merbuf.encode / merbuf.decode ONE CODEC merbuf_col.h wire version 3 schema-order, positional never reordered WHAT REFUSES merbuf.new("Type") removed, raises BadRequest construct with db.entity.draft json.stringify, json.parse the external interop edge only never the save format THE GATE THAT CHOOSES thalassa.scripts.tool-serialize one .tri drives BOTH branches WHAT THAT GATE ASSERTS the data tools Wake, Spindrift, Conch, Shoal model -> encode -> decode == model Chart lower() emits db.entity.define* the typed store, not a blob and no json anywhere the lowered source carries no json substring; exact-output gated
Plate 02

One spelling per type, and the spellings that refuse

one table, four views · the spelling grammar · the drift gate

1 · ONE TABLE, FOUR VIEWS OF ONE TYPE canonical spellingi32 · f64 · text · decimal(N) MertekTypethe durable MdColumn id MB_* wire typewhat the codec writes Trident accessorthe runtime value kind, for codegen 2 · THE SPELLING GRAMMAR IS FAIL-CLOSED <base> ['(' scale ')' | '<' dim '>'] ['?'] ['[]'] mertek_find parses it; anything else returns -1 WHAT THE SUFFIXES MEAN ? the scalar, or each element, may be null [] an array; i32?[] adds a presence bitmap ACCEPTED i32 i32? i32[] i32?[] decimal(2) measure<mass> REFUSED i32[]? array-level null decimal() no scale digit measure<> no dimension int long float double string bytes struct timestamp 20 retired spellings in all 3 · FOUR REPRESENTATIONS THAT MUST AGREE, AND THE GATE THAT PINS THEM merbufMB_* codes, codec sizing merTekCoreTypeMERTEK_TYPES, mertek_* tridentis_type lexer, parse tables merdbcolumnar sizing, admission merbuf.tests.type-drift asserts every pair. Its exception lists start empty, so a drift is a real bug by default.
Plate 03

The encoded form: four sections, and a decoder that refuses first

the four sections · the validation cascade · the frozen corpus

THE PAYLOAD · SCHEMA-ORDER, UNCOMPRESSED, POSITIONAL HEADER 36 bytes, 40 with metadata "AKM" + version byte 3 flags · totalLen · colCount schemaHash u64 then section descriptors SCHEMA SECTION per column, in declared order nameLen u8 · name type u8 · options u8 defLen u8 · default mertype u8 · type_param u8 DATA SECTION rowCount u32 per col [absOff u64][effLen u64] then the column payloads null mask · bit-packed bool var width: [len u32][bytes] METADATA SECTION optional count u32, then per entry [keyLen u16][key] [valLen u32][val] keys ordinal-sorted EVERY DECODE VALIDATES BEFORE IT ALLOCATES magic "AKM" and version byte 3 totalLen fits, colCount within 4096 every section span fits the buffer the sections sum to exactly totalLen recompute the schema fingerprint row count and cell footprint plausible REFUSE, FAIL-CLOSED Any stage that does not hold returns NULL with one named message. 43 distinct refusal messages. No partial document is returned, and nothing is allocated past the stage that refused. THE FROZEN CORPUS 7 good fixtures decode byte-exactly 12 malformed fixtures must all refuse plus fuzz: truncation, per-offset corruption, 100000 random buffers THE ENCODER REFUSES FIRST a name or default over 255 bytes a decimal scale over 38 a column count over 4096 a declared cell of the wrong width a nested doc whose own encode refused DECODE an arena-owned MbDoc payloads are copied, so the input buffer may be freed after mbcol_valid is the probe form
Plate 04

Schema identity: the fingerprint, and why a rolling fleet is safe

fingerprint composition · self-describing and hash-only · mixed-version interop

1 · WHAT THE FINGERPRINT IS COMPUTED OVER mb_schema_hash streaming, allocation-free "MBF3" + u32 column count then per column IN DECLARED ORDER: u8 nameLen · name type · options · mertype · type_param u8 defLen · default SHA-256 not CRC: this is an identity key across a trust boundary first 8 bytes, LE the u64 schemaHash on the wire EACH MINTS A NEW IDENTITY a column REORDER add · remove · rename · retype a nullable flip, i32 vs i32? a decimal scale change guid vs u128 on the SAME wire 2 · TWO PAYLOAD FORMS, AND HOW A HASH-ONLY ONE RESOLVES self-describing HasSchema set carries its full column schema the default form of merbuf.encode hash-only schema section dropped carries only the u64 fingerprint a repeated shape ships once TridentRuntime.schema_reg per-runtime, fingerprint-keyed versioned · LRU cache window host-installed miss resolver the client opts in with {hashOnly:1} in its sys.connect hello, or never decodes ONLY against an exact resolved schema; else it refuses Fathom strips from frame two onward, per fingerprint, per connection 3 · A ROLLING NODE REPLACEMENT: BOTH GENERATIONS SERVE AT ONCE V2 writer[ id, tag, extra ] self-describing container the schema travels with the bytes V1 reader reads id and tag the appended column is simply never looked up V1 writer[ id, tag ] self-describing container a fingerprint distinct from V2 V2 reader detects extra ABSENT the column is missing, not silently read back as a zero
Plate 05

The graph snapshot: keys, not pointers, inside a declared scope

snapshot pipeline · the identity oracle · declared scope and its refusals

SNAPSHOT · ONE MerBuf FOR A WHOLE DECLARED SUBGRAPH live MerDB graph entities plus declared defineRelation FK columns db.graphSnapshot(scope) range-walk each root's declared ordered index, ascending id the snapshot doc nodes[] { id, type } edges[] { from, rel, to } merbuf.encode one self-describing MerBuf payload THE ROUND-TRIP IDENTITY ORACLE snapshot, encode db.graphRestore re-snapshot, encode byte-identical to the original bytes WHY IT CAN BE BYTE-IDENTICAL A reference is a stable id KEY, never a raw pointer. Restore binds each edge to the target's node index, so sharing aliases ONE node and a cycle closes. AND NOTHING IS INLINED Nodes and edges are FLAT keyed rows, so the circular-reference guard has nothing to trip on. The walk is ordered and has no RNG, so bytes repeat. THE SCOPE IS DECLARED DATA WITH NO DEFAULT scope roots [ { type, index }, ... ] required. index names a DECLARED ordered index; there is no scan. refs [ relation, ... ] optional included-kind allowlist FAIL-CLOSED REFUSALS · NO IMPLICIT DEFAULT AT SNAPSHOT a root with no ordered index an UNDECLARED boundary on a reference that actually crosses a crossing edge under "error" AT RESTORE a dangling target key a duplicate node id a boundary flag that resolves a scope fingerprint mismatch

Key parts

What the system does

These are the main boundaries, inputs, outputs, and failure rules. The examples show a specific use of each part.

Typed encoding

Values keep their declared meaning when stored or sent. A receiver does not have to guess whether a field is text, time, an identifier, or a measurement.

Specific example

A maintenance message can preserve the exact type and unit expected by the receiving system.

Schema identity

Each data shape carries a stable identity. A node can check compatibility before using the data.

Specific example

During a phased update, an older node can refuse a new message shape instead of reading it incorrectly.

Safe graph snapshots

Related objects are saved with stable keys rather than temporary memory links. The data can move between processes and machines.

Specific example

A mission plan with linked tasks and assets can be saved, transferred, and restored without losing its relationships.

Uses

Example uses

Pilot questions

What the team must decide

Which data must survive software upgrades

What compatibility rules apply across the fleet

Which relationships must remain intact after transfer

Request a technical briefing

Connected references

Mission foundation MerDB Open reference Mission foundation MerFS Open reference Assurance fabric Persistence Open reference
Return to the M9 reference library