Furth FortuneM9 reference

Mission foundation / System overview

MerFS

One byte-store contract across storage systems

MerFS stores and retrieves opaque bytes by stable key. Local disk, remote object storage, and memory-backed storage implement the same narrow contract.

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

The seam: typed above, opaque below

layer stack · the call shapes that cross in · the boundary rule

LAYERS WHAT CROSSES INTO MERFS THE BOUNDARY RULE Trident db.* · t.device.storage.* MerDB entities · schema · indexes relations · MerBuf rows MerFS native/merfs · 21 headers MerFsStore · 4 record adapters MdBlobTable · tagged values MdKSparse · hot + cold runs MdSegStore · append-only log MdChunk · immutable chunks MerFsBlobStore · path keys merfs_host_platform.h host filesystem POSIX · Win32 file-backed tiers block lanes BenthOS extent no filesystem MerFsStore.put (table_key, id, bytes, len) table_key is opaque: data/<slug> MerFS stores it, never reads it merfs_bt_put (key, version, value, vlen) byte key · LWW by that version MerFsBlobStore.put (key, bytes, len) UTF-8 path key · see plate 03 merfs_host_platform.h 17 provider functions mechanics only, no semantics INCLUDE DIRECTION 6 files outside native/merfs include a MerFS header. No MerFS header includes a Trident, Thalassa or Fathom one. ONE include still points up: merfs_runset.h reaches merdb_residency.h MerFS NEVER SEES an entity or a column name a MerTek type or a default a declared index or a relation a strict or open table mode a Trident value which column deserves an index how a relation resolves MerFS OWNS bytes, keys, offsets, ranges append, point get, prefix scan compaction, GC, flush, fsync crash recovery and reopen the backend geometry underneath a test on generated byte keys with no entity declaration THE PROOF 12 gate leaves cover a runner under native/merfs/tests. No DIRECT include in the 15 drivers leaves native/merfs; 6 reach MerDB via merfs_runset.h.
Plate 02

One value, three shapes, one tag byte

the tag cascade · the chunk record · the bounded read

1 · WRITE · THE TAG DECIDES WHERE THE BYTES LIVE merfs_bt_put key, version, value, vlen one shot, value held in RAM vlen <= inline_max MerDB opens at 256 the only branch point merfs_bt_writer_* open · append · finalize · abort each append is its own chunk the value is never held whole MBT_TAG_INLINE payload = the value bytes; the leaf IS the value MBT_TAG_BLOB payload = one MdChunkRef, 32 bytes; the bytes go to a chunk MBT_TAG_SEGMENTED payload = [MdChunkRef of an index chunk][u64 total] index body = MBSG magic, count, then [u64 start][ref] per segment 2 · DURABILITY · THE CHUNK RECORD AND THE HOST PROVIDER <dir>/chunk-<NNNN>.seg append-only, write-once [u32 magic][u32 kind][u64 len][u64 hash][ len bytes ] MERFS_CHUNK_HDR is 24 bytes; magic CNK1 refuses a foreign file 4 kinds: blob leaf, tree node, tree leaf, zero-value leaf FNV-1a 64 sits in hash and is verified on every read SHA-256 over the body is the dedup key, not that hash roll at 1 GiB; 2 lanes keep tree pages apart from blobs merfs_host_platform.h 17 provider functions mkdir · mkpath · dir open, next, close · rmtree rename · file sync · truncate · seek · tell · size one #if per call: _WIN32, __EMSCRIPTEN__, POSIX an atomic put writes a temp file, syncs it, renames it Windows renames with MoveFileExA, because the CRT rename refuses an existing target and would break that pattern 3 · READ · ONE BOUNDED WINDOW AT A TIME merfs_bcur_open resolves len and genfp faults no value bytes fetch(cap) a window of at most cap offset · remaining · done bounded by cap, not by the value a value of any size streams on a small node; the db.blob bridge clamps a caller maxMB to half the arena cap before it calls fetch generation check on EVERY fetch delete or overwrite mid-stream: valid = 0, fetch returns 0 all(cap) is fail-closed a value over cap returns 0 and sets toobig, never a partial
Plate 03

The device storage plane: the one surface Trident reaches

host bind · the refusal cascade · key validity · the reachability census

A HOST BINDS IT · AN APP CANNOT EVERY CALL FALLS THROUGH THIS merfs_key_valid · 8 REFUSALS trident_rt_bind_device_store (rt, dir, scope) · host only refuses once provisioning is sealed an open failure leaves the plane denied sets TRIDENT_RT_CAP_DEVICE_STORE TWO BACKENDS, ONE VTABLE merfs_blob_store_host.h key K maps to <root>/K.mb merfs_blob_store_wasm.h Module.deviceKv: OPFS or IndexedDB MerFsBlobStore · 6 MEMBERS put(key, bytes, len) get(key) fills a malloc'd buffer del(key) · len(key) list(prefix, ctx, cb) close(self) THE .mb SUFFIX IS NOT DECORATION A leaf file carries .mb so key "a" (file a.mb) and key "a/b" (directory a plus b.mb) coexist without a file and directory clash. t.device.storage.<verb>(...) capability bit clear: CapabilityDenied no store bound: DeviceStoreUnavailable key = <scope>/<caller key> the scope is host-set and app-immutable list() strips it back off the join overflows: key too long 5 VERBS REACH THE STORE upsert(key, bytes or text) to bool get(key) to a buffer or nil len(key) to a count or nil delete(key) to bool list(prefix) to an array of keys merfs_key_valid, in the backend put, get, del, len · list walks and compares an empty key a leading / more than 512 bytes more than 32 components an empty component a backslash or a colon a . component a .. component Both backends share this check, so a traversal escape or an absolute path is refused before any file call, and independent of the caller's scope. THE REACHABILITY CENSUS 12 leaves cover a runner under native/merfs/tests, and all 12 declare exerciseLayer c-kernel. One leaf declares trident: trident.device-storage 4 checks: a round trip on the tree walker, the same round trip on the bytecode VM, scope isolation, and a denial with no store bound.

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.

Clean separation

Typed meaning stays above MerFS. The storage layer focuses on keeping, finding, and moving the bytes it is given.

Specific example

A sensor application can change its storage device without changing the meaning of its records.

Several storage shapes

The same value can live inline, in a larger object, or in content-addressed storage. The platform selects a suitable form through declared policy.

Specific example

A small status value can stay with its record while a large terrain tile is stored separately.

Device-ready access

Trident applications reach storage through a narrow, consistent surface. Device details do not spread into application code.

Specific example

A field tablet can save local work during a network outage and reconnect through the same application interface.

Uses

Example uses

Pilot questions

What the team must decide

Which data must work offline

What must be durable after power loss

How large objects should move between locations

Request a technical briefing

Connected references

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