Furth FortuneM9 reference

Mission foundation / System overview

Fathom

The host boundary from edge node to service

Fathom connects MerTek applications to files, networks, processes, and deployed nodes through a small host interface. Transport, trust, and rollout choices are declared policy.

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 host is the narrow trusted edge, and the OS is a vtable

what a host owns · the six vtables · what it must never own

A fathom_host_* FILE OWNS THIS main()one process, one Application HostConfigflag, then env, then declared the OS handlessockets, files, signals, the GPU the wiringengine, worker pool, providers then it hands overthe Trident program serves THE OS ARRIVES AS SIX VTABLES FathomTransportOpstcp listen, accept, recv FathomDatagramOpsudp bind, sendto, recv FathomEventOpsepoll, kqueue, IOCP, poll FathomDrainOpsannounce, shutdown signal FathomLifecycleOpssignals, arm shutdown FathomResourceOpsfacts, 0 = unavailable One contract header and one native provider header for each seam. Six of each, and no OS call between. AND MUST NEVER OWN THIS Application logican app is config plus .tri a scenario constantthe value is Trident-declared a policy defaultan undeclared case refuses file-scope mutable statestate is runtime-scoped BEFORE YOU TOUCH ONE Ask the user first. Name the host file and the capability you think is missing, then wait. TWO LOOP-OWNERSHIP ADAPTERS, ONE COMPOSED APPLICATION HOST fathom_host_fathom_dataplane.c C owns the readiness loop fathom_host_fathom_cluster.c a Trident program owns accept ThHostSupervisor th_host_new, then th_init registry, scheduler, host verbs, boot ONE host C body under both adapters
Plate 02

Three tags, one string key, and two separate namespaces

the frame bytes · the three tags · wire name to language verb

RAW TCP FRAME u32 len LEbody size tagC, E or H u8 keyLen0 to 255 keythe wire route name payloadone typed MerBuf the outer u32 delimits a message on a byte stream WS BINARY FRAME CARRIES THE INNER MESSAGE droppedno length prefix tag u8 keyLen key payload WebSocket already delimits, so the prefix is redundant THE ONLY THREE TAGS 'C' callclient to server, by route name 'E' eventserver to client, by event name 'H' handshakeserver to client, per connection any other tagce_tag_valid refuses it TWO NAMESPACES, ONE EXPLICIT BRIDGE wire route name db.entity.count a polyglot key, bare the .tri handler callKey == that key the explicit bridge language verb t.db.entity.count the Trident surface WHY THE WIRE KEY STAYS BARE A t. prefix would break every client that is not written in Trident. It also cannot spell a route with no verb behind it: echo, call.error, db.entity.count.ok. The t. umbrella reserves the LANGUAGE surface only. RESERVED WIRE NAMES sys.connect elicits this connection's H frame with its session seed. sys.frameCap negotiates a larger inbound frame for ONE connection. call.error carries the structured fault; call.slow carries backpressure.
Plate 03

The transport ladder, and a posture that is declared rather than guessed

two lanes · transport_policy_verdict · the capability probe

STREAM LANE call and event framesce_frame, ce_msg WebSocket RFC 6455fathom_net_ws.h TLSfathom_net_tls.h, mbedTLS FathomTransportOpsthe stream vtable native providerPOSIX sockets or WinSock DATAGRAM LANE typed payloadsnapshot, input, voice reliability channel3 declared modes DTLScookie exchange, retransmit FathomDatagramOpsthe datagram vtable native providerPOSIX sockets or WinSock THE POSTURE IS DECLARED, NOT READ OFF A CERTIFICATE transport_policy_verdict the declared string, plus this lane's credential set secure, with the complete credential set TP_SECURE: arm the listener local-dev, with no credential at all TP_PLAINTEXT: plaintext by explicit declaration secure, but no certificate TP_REFUSE: the host exits, it never serves plaintext local-dev, but a certificate is supplied TP_REFUSE: the contradiction is not resolved for you AN ABSENT LIBRARY IS A TYPED SKIP, NEVER A FALSE FAILURE embedder_mbedtls_probe compiles and links mbedtls/ssl.h the probe leaf publishes toolchain.mbedtls armed the 27 declaring leaves run absent one SKIPPED line, unavailable WHY IT MATTERS A gate that COMPILE- FAILS on a missing library reports a defect that does not exist, and the next agent spends the day on it.
Plate 04

Ingress: every stage refuses before it accepts

accept → detect → bound → throttle → worker → frame

INGRESS WHAT REFUSES, AND WHAT THE CLIENT SEES accept one Conn record, its own read and write buffers no shared scratch, so no connection can clobber another Buffers are allocated lazily and per connection. A larger inbound cap is negotiated for ONE connection, and only that connection pays for the heap it asked for. detect the carriage four bytes decide: an HTTP method, or a u32 length M_DETECT to M_RAW or M_HTTP, and Upgrade to M_WS a malformed request line or header http1_parse returns -1 and the connection closes. A Transfer-Encoding header is refused, never decoded. bound the frame the declared length is read first, then judged default inbound cap FA_REQ_CAP = 16384 bytes a length above the cap, or below 2 The connection closes before one payload byte is read, so a frame that declares 2^63 bytes costs the host nothing. throttle the app-wide rate first, then the per-source-IP rate a repeat budget trip escalates the same source to a strike over the declared rate A call.slow event, and the connection stays open. The client backs off on the event name; nothing else is shed. run one pooled stateless worker exclusive checkout of a worker runtime for this one call the durable engine persists across calls; the runtime does not every worker is busy A call.error event. The host answers rather than queueing the request behind a worker that may never come free. dispatch on callKey, then frame the events the handler if-chain sets handled and emits its result push entities first, then the control event, in order no branch claimed the key call.error with code unknown_endpoint and the endpoint name. An unregistered edge denies; it never falls through.
Plate 05

One Application across many nodes: the map declares, the node never invents

declared topology · cr_resolve · the epoch fence · the moving parts

THE CONTROL PLANE DECLARES, THE NODE CONSUMES MerTekStak declares fathom_node: name, role, endpoint shard_map: path prefix to node set fathom_node_membership.h identity, liveness TTL, drain state the live table this node holds fathom_cluster_route.h the versioned ownership map prefix to node set, at any depth ONE DECISION PER REQUEST PATH cr_resolve(path) owners, crossed with membership, crossed with liveness and drain CR_SERVE_LOCALowner, live, serving CR_ROUTE_PEERa live peer owns it CR_SCATTER_READseveral owners, merge LWW CR_MISSno live owner, named nm_build_target one primary plus ordered backups a dead node is excluded outright a draining node is marked, not used FIVE MEMBERSHIP DENIALS NM_DENY_NO_PROFILEunknown node NM_DENY_STALE_CONFIGbehind the map NM_DENY_DEADheartbeat aged out NM_DENY_DRAINED / _IDENTITY ONE MASTER PER SCENE INSTANCE, FENCED BY EPOCH master runtime one lead node, adaptive tick SaStamp on every payload node, master epoch, sceneFrame sa_admit the fence, on every message SA_ACCEPT SA_DENY_EPOCH a deposed master, fenced SA_DENY_STALE, _FUTURE fathom_replica_predict.h a replica proxies its users to the master and predicts between master frames, inside a DECLARED divergence bound. An undeclared bound forces a resync. fathom_portal_handoff.h prepare, accept, dual, commit, abort, release. A dead band with commit above revert stops the flap at the seam, and at most two masters ever hold a subject. fathom_cluster_reshard.h announce, copy, dual-serve, catchup, cutover, retire. The subtree is visible on BOTH nodes for the whole window, so no read can fall between them. AND THE MATRIX fathom_net_matrix.h fails over on a dead primary, and migrates before a drain.
Plate 06

An Application is config plus Trident, and the host compiles none of it

declared inputs · the .tri Application · the delivery closure

WHAT THE DEPLOYMENT DECLARES FATHOM_APPLICATION_MODEverified, or trusted-raw ..._ENVELOPEthe verified provisioning envelope ..._ADMISSIONthe deployer-owned handler entry ..._SCHEMA_ADMISSIONan INDEPENDENT schema admission FATHOM_STORE, FATHOM_PROFILEthe durable root, the profile PROFILE production REFUSES an undeclared app id an in-memory store the bundled demo handler and schema an undeclared transport posture AN APPLICATION IS CONFIG PLUS .tri boot_*.triapp scope only, no system tables system/sys_*.trithe system tier, immutable to users the handler .triendpoint key to behaviour the schema .trityped MerDB entities configand no Application C compiles DOGFOOD MerTekStak and MerTek.io are Applications on this substrate. A capability an app lacks becomes a generic primitive, never app C. WHAT A CLIENT MAY PULL audience CLIENTdelivered to the client audience BOTHdelivered, and runs on the server audience SERVERnever ships, and it is the DEFAULT merdb_modules_shippable A full scan of the small control- plane table, never a discriminator index. A module outside the admitted generation is not denied, it is not ENUMERABLE. No generation means no key, so every read refuses. THE HOST COMPILES NO APPLICATION CODE one process, one Application the request-oriented host path the handler and schema arrive as verified entries, not as source th_host_new, then th_init the composed ThHostSupervisor the schema entry installs once, before the durable store opens the pooled stateless worker exclusive runtime per call the durable engine persists across calls; the runtime resets
Plate 07

Mixed-version operation: both fleets serve at once, so the wire must hold

two update paths · the rolling window · the three mechanisms

TWO UPDATE PATHS, AND THEY ARE NOT THE SAME Application .tri live-edited in the module store generations plus rollback, validate before commit no redeploy, no node replacement, the daily driver compiled-core C the runtime, the engine, the renderer, the hosts a new golden image, rolled or blue-green durable state is decoupled, so nodes drain and retire MID-ROLL, BOTH FLEETS SERVE THE SAME APPLICATION old-image node the previous wire build draining, still answering peer matrix, MerDB wire, and the call/event protocol new-image node the new wire build taking over the traffic A BREAKING WIRE CHANGE forces a version-gated drain of the whole fleet. Avoid it. THREE MECHANISMS KEEP A MIXED FLEET TALKING capability negotiation sys.connect carries the client's advertised capabilities as a self- describing MerBuf. hashOnly opts this ONE connection into stripped frames. An omitted flag, an empty hello, or a full fingerprint set all keep the self-describing form. Fail-closed at both levels. the MerBuf fingerprint wire version 3. The fingerprint is the first 8 bytes of SHA-256 over MBF3, the column count, and every column in declared order: name, wire type, options, mertype, type_param, default. A divergent schema REFUSES at a hash-only decode; it never mis-reads. the graceful drain SIGTERM stops the accept, flushes the in-flight responses, and flushes the durable store, so the last acked write survives the restart. A peer learns the drain from the DURABLE signal bus and migrates while the node is still reachable, so a late poller still learns it.

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.

Narrow host boundary

The application uses a small, defined surface to reach the operating system. That reduces hidden dependencies and makes platform review easier.

Specific example

The same workflow can run on a field computer and a data-center node through approved host adapters.

Declared communication posture

Transport, identity, and trust choices are stated as policy. Nodes do not invent a security posture at run time.

Specific example

A disconnected team can use a local path, then move to an approved network path when contact returns.

Mixed-version service

Older and newer releases can operate during a controlled rollout. Shared message rules protect the mission while nodes change over time.

Specific example

A fleet can update in waves without taking every operational node offline at once.

Uses

Example uses

Pilot questions

What the team must decide

Which environments must host the application

What communication paths are approved

How long mixed releases must work together

Request a technical briefing

Connected references

Assurance fabric Controlled Deployment Open reference Assurance fabric Security and Tenancy Open reference Mission foundation BenthOS Open reference
Return to the M9 reference library