Glossary

pit names a number of things precisely. Each term below is defined once here; pages elsewhere link to this list on first use.

Code and its forms

module — a .cm source file. It runs once per actor and returns one value.

program — a .ce source file. It is an entry point and returns no value.

mcode — the portable compiler IR for one source file. It carries instructions, literals, import requests, claims, stable function and site IDs, and source spans. Mcode is target-neutral: the same mcode serves every target.

link group — the set of mcode units lowered and linked together into one pool. Choosing the group is choosing how much code gets optimized as a unit — and, because a pool is the unit of replacement, how finely the result can be hot-reloaded.

Mach pool — the target-final immutable execution artifact produced from one link group: bytecode, constants, stone text, record shapes, and function descriptors, laid out for one exact profile. It is mapped and read where it sits, with no per-load materialized constant or object tree. Any number of actors may share one. It carries stable mcode function IDs, which exist for matching — reload, profiles — and never for lookup. Portability ends at mcode: a pool is finished, for one profile, and a different profile gets its own pool pressed from the same mcode. Often just “pool”.

image — a pool mapped into a running system. The pool is the artifact at rest; the image is that pool made addressable, pinned by the actors that hold anything from it.

profile — the complete record of a target’s axes: system, arch, endian, value width, object layout, numeric and text representation, GC, wota width, Mach ABI. The emitter reads every target fact from it; nothing interprets a target’s name. The scheduler arrangement is a build lever rather than an axis here — it selects provider files and moves no byte.

stamp — a profile’s canonical hash, carried in artifact headers and compared at mount. The comparison is done before any parsing: a stamp mismatch is refused by naming both sides.

native image — an ahead-of-time compiled sibling of a Mach pool, produced through a host toolchain. It runs with C-floor authority.

executable manifest — the logical identity of a program: one root, its resolved unit bindings, the exact mcode closure, initialization order, and claims. Content-addressed. It holds one identity arm per canonical package, so <package>::<file> occurs once in a closure, and it is the border table where locators stop and content hashes begin.

target realization — the startable artifact, and the only thing a runner reads. It joins an executable manifest to one target profile, one execution form, exact pool hashes, and a start plan explicit enough that starting is following rows: which pools to open, which imports to bind, which name gets which value, and which slot each entry’s result goes in.

entry — one row of a realization’s ordered array, producing one value into one slot. There are three kinds and no more: {value} — a constant the shop resolved, or a token the runtime injects at start; {unit, entry} — bytecode to run, whose return value is the result; {native} — a compiled-in provider to load by key. An endowment is not a fourth kind: it is an entry whose result binds to a $name instead of a def name.

result array — the actor-heap array those entries fill, one slot per entry, with indices assigned when the executable was finalized. A unit’s bytecode names only what is inside its own image, relatively; references that cross an image boundary are binding rows resolved against these slots, which is what lets one image be instantiated in many actors at once.

placement group — the set of pools made addressable together, deciding what is resident and for how long. Independent of the link group.

Values and memory

stone — immutable. stone(value) freezes a value permanently, and stone values are what may be sent between actors.

antestone — mutable; the state a value is in before it is stoned. This is a layout distinction, not only a semantic one: stone text uses its length field to hold a hash, while antestone text uses that field for the letter count.

pretext — the internal name for text that is not yet stone. It appears in implementation discussion; in ordinary prose such text is antestone.

fit — a whole number the build represents exactly. The range is target-selected; is_fit tests membership. Also the name of the module for fixed-width integer and bit operations.

disruption — the structural failure signal. An operation whose operands are the wrong kind of thing disrupts; a disruption block handles it. Arithmetic that has no answer yields null instead.

Actors

actor — an independent unit of execution with its own heap. Actors communicate by sending values.

turn — one message processed to completion. A turn may be suspended and resumed.

letter — a serialized message in an actor’s mailbox, owned by the runtime.

endowment — a named capability an actor holds: a file provider, a socket, a clock. All authority arrives as an endowment.

claim — a declaration by a module or program that it requires a particular endowment, global, or native provider.

overling — the actor that created another. A child is automatically coupled to its overling, meaning the overling’s death takes the child with it. The runtime reclaims and kills; it never restarts or supervises: an actor idle past its ar timer is reaped, a turn that repeatedly overruns its slow budget is halted, a pending reply resolves by an answer, by the counterparty’s death, or by the holder’s own death — and that is the whole of it. No restart, no health check, no supervision policy. Supervision trees are application-level and belong in a library someone writes. See Actors and Memory.

couple / monitor — the two ways to care that an actor died, over one mechanism. A couple is a death pact: the coupler stops at the end of the turn that observes the death, and that is what makes stopping an overling stop everything below it. A monitor is the same notice with no lifetime binding — what a reply route registers, so it can hear the death and stay alive to report it.

ar timer — the idle countdown every actor carries: it runs whenever the actor has nothing to do (empty mailbox, not queued, not mid-turn) and reaps the actor when it fires. Pending delays, parks, and signals are not liveness — waiting buys no time; only $unneeded does. Default from the recipe’s budgets; -1 is never.

$unneeded — how an actor sets its own ar timer: $unneeded(fn, seconds) arms the countdown and a callback that gets one final turn when it fires — to clean up, re-arm, or let the reap proceed. An actor that knows how long its waits should be encodes that knowledge here, which is why no other timeout exists in the system. A long-lived service is the case that must say so: quiet is its normal state, not a sign that nothing wants it.

slow timer — the per-turn budget: a turn that exceeds it is frozen mid-turn and goes to the back of the line, resuming when its turn comes again; a turn that repeatedly overruns accrues strikes and is halted at the strike limit. Slowness is throttled, then killed — silence means dead; slowness does not.

lane — the execution context an actor is pinned to, used where a target needs certain work on a particular thread or frame.

park / signal — the runtime structures that hold a callback while asynchronous work is outstanding and deliver its completion.

Building and shipping

shop — the collection of actors that decides how programs are found, built, and started: boot, the clerk, an mcode compiler, fetchers, a policy actor. Not one program — a shipped binary may carry only boot and a clerk with nothing behind it.

boot — the first pit actor, and deliberately stupid. It starts the clerk, asks it for the entry, starts that, and is the root overling — which is what makes stopping it stop everything. It holds $image. Nothing addresses boot afterwards except to ask for a genuine decision — mount, fetch, evict — and there is no $boot endowment.

$image — the endowment over the image provider, held by boot: open a pool by content hash, pin its placement, bind its declared cross-image imports, resolve an entry function, unpin, close. C keeps the mechanics — mapping, validation, the pin table — and pit decides which image and when, following realization rows. A pool’s bytes are ordinary store content anything may read; what $image gates is executable placement. Eviction is the absence of traced references: closures trace their binding, bindings retain their pin, and a pin is a refcount over an immutable pool.

clerk — the actor that knows what a package is. It mounts, answers <package>::<path> requests literally, and reports what it has mounted, what files a package holds, and what aliases a package declares. It holds the shop’s lists. $start goes here, because the clerk is what walks the resolution chain: it looks in its mounts, starts a compile actor if there is source but no mcode, and starts git or fetch actors if there is no source — eventually answering that it could not. All of those are ordinary actors it starts, so a clerk is exactly as powerful as its binary and mounted bundles allow. Everything about naming lives here, which is why a different shop can supply a different one; the core knows only that use() takes a text literal and $start takes a literal or a variable.

the shop’s lists — the shop’s whole configuration, each a list of package names and nothing else: endowments (which packages provide endowments), endowments_whole (which of those are linked whole, claimed or not), c_native (which packages may compile C — a real gate that blesses by naming, so absence is never permission), fallback (what an unqualified use means), bin (which packages a start searches for a tool). Bin paths and library paths, applied to importing, endowing, and starting.

the chain — how a name without :: becomes a module: the caller’s own package, its aliases, the shop’s aliases, then the fallback packages in order. That is the whole of use — an import that misses the chain has missed, full stop. One chain serves $start and the command line, which are the same thing: the CLI resolves nothing itself, it forwards what you typed to a $start, with the shell’s cwd as the calling package. A start continues past a chain miss into the bin packages, then the whole text as a locator, then the text as a script — three steps no import ever takes. fallback and bin are separate lists for that reason: fallback says what a bare use means, bin says which packages supply top-level programs to a start. Locator-shaped text never reaches that last step: text made only of identifiers, /, ::, dots and dashes is resolution-only, and a miss reports the chain.

recipe — a named bundle of build lever settings for the runtime binary: a platform package, the stamp levers, the build levers, and the shop’s lists, committed as a JSON file. A target is a recipe. The name is something the recipe declares and nothing interprets — no component takes a target name to mean “these things”, and the only place one appears outside a recipe is a package’s own modules arms. Committed recipes are suggestions, not permissions: whether a combination works is answered by compiling it.

build description — the composer’s invocation of forge or the bundling tools: which actors ride in a binary or bundle (--with), which payload form (--payload), which assets. Arguments, not a schema — everything they decide is recorded in the product’s own manifest, and the committed defaults are the makefiles and scripts that invoke the tools. Per build, never per target. A recipe describes the runtime; a build description describes what runs on it. Not to be confused with a build manifest, which is cake’s rendered per-recipe output for the runtime builder.

policy — the small actor, written per build, that answers whether a particular executable may have an endowment. The shop answers whether it exists at all; policy answers whether you may have it. Permissive on a development machine, restrictive toward mods in a shipped game.

locator — the text a use() or $start names. Its whole meaning belongs to the shop. This shop writes <package>::<path> — :: being the package boundary, which is load-bearing because package-private code cannot be defined without it — resolves aliases through package.json, and treats the canonical form as the identity that decides whether two imports are the same module. None of that is intrinsic. A shop that made every name global, or canonical from the start, or something else entirely, would be a different shop and the same language.

package — content rooted at a directory with a package.json, selected under an identity the shop resolves through its installed store or explicit links. The manifest has no name or source-membership list: a C file’s package-relative path is its module name; internal/ is private; source/ is support C. Nested manifests are not discovered by a checkout walk.

mount — attaching a bundle or store to a shop, and therefore the trust decision that admits it. Because a shop draws whatever it needs from its mounts, mounting decides what may enter. It is not an endowment: the clerk mounts using the provider modules and endowments the binary carries — a directory, its own .pit store, a git repository, an archive.

alias — a short name for a package, so a module can write a brief locator instead of the full one, together with the version selector for it. A package’s aliases are its dependency pins; the shop’s are shop-wide naming. An alias whose key equals its value must not exist: if no alias claims a name, the name is the package.

content hash — the name of an artifact, computed from its bytes. Identity, dedup, verification.

derivation key — the name of a computation, computed from every semantic input. It resolves to the content hash of that computation’s output.

freshness index — a local accelerator mapping paths and mtimes to the last known source content hash. Deleting it costs re-hashing and changes no artifact identity.

guest code — the flag an executable carries when it calls $start on a computed name. Its closure of startable actors is not knowable at build time, so a policy that requires literal-only starts — the right setting for a sealed binary — refuses it.

cake — the C compiler driver: one file in, one object out, with the flags its package declares. It holds no mapping manifests and reads no meaning out of a target name.

runtime builder / forge — cake’s assembler counterpart and the only binary producer. It reads a recipe, derives the translation-unit list from the platform package and the lists, drives cake once per unit, injects the boot image through .incbin, links and gates a candidate, and atomically promotes only a clean fixpoint result.

extension spec — the set of C modules and endowment providers a boot closure can reach, emitted by the boot-image build as (package, file, full symbol, facts) rows. A ship runtime links exactly it; a dev runtime links from the whole lists and takes no spec.

binary — C plus its read-only boot section, produced and clean-fixpoint-gated by forge. It is the cold floor and the only shippable executable object.

pool — fused target-final Mach, the only executable payload. See Mach pool above.

bundle — an external container of pools, mcode units, assets, or any combination of them, with a manifest naming its contents. Bundles are opened only after Pit is running; mount is the trust decision that admits one. boot.qop is the development bundle.

qop — the archive container format used for offline and installable representations.

Encodings

kim — the character encoding. Every Unicode character is carried whole, in at most three bytes.

wota — the fast, profile-specific value encoding used within one runtime, including actor mailboxes.

nota — the compact, runtime-independent value encoding used across runtime boundaries. Numbers travel as a decimal coefficient and exponent, so runtimes with different numeric representations agree on what a number is.

Tooling

origin map — a sidecar keyed by pool hash, mapping ranges of a final pool back to {mcode hash, function ID, site ID, source hash, span}. Content hashes and stable IDs the whole way; no name mapping anywhere in the path. Debugging and profile-guided optimization both read it, and it ships in a bundle’s debug slice.

$inspect — the endowment for read-only views of a running actor: the actor registry, frames, locals and closures, a function’s bytecode. Costs nothing while unused.

$hook — the endowment for the VM’s call and return hook, and so for breakpoints, stepping, and tracing. Costs a hook check at every call and every return. Not to be confused with $trace, which carries the distributed trace id across a send.

$runtime — the endowment for acting on the runtime: setting which actor receives the log stream, which routes off-node traffic, and this node’s identity; stopping an actor you did not start; and shutdown, which stops the root actor and lets the couple cascade do the rest. Held chiefly by boot. $inspect observes, $runtime acts. Reading node identity, runtime_info(), needs no endowment.

$vm — the endowment for memory: VM-wide and per-actor totals, walking an actor’s heap, the footprint of a value. Costs the allocation and GC accounting behind those numbers.

$pgo — the endowment for draining an actor’s live per-call-site execution counters. Costs the counters.

realization catalog — the mapping from an actor locator to the target realizations that can serve it.