Archive — history, not state. Kept for its reasoning and its evidence; its plan is closed.

Worklist — endowment, gate, and boot model

Generated 2026-07-24 from a design review of docs/ against John’s rulings. This is a work ledger, not target design: the target lives in docs/. Every row cites both sides.

The rulings this implements, in one paragraph: an endowment is a name a program requests that the shop may deny — nothing about power level, $self and $cores qualify. Globals are the same delivery path without the deniability. A granted name arrives in exactly two ways — a constant the shop knows, or the return value of a unit in the realization — and the runtime holds no recipes. Compilation is the gate: built here means it runs, nothing is checked at start, and the boot cart is trusted by ruling. A mount is the trust decision. Minimal C is a prime edict: C is the audit surface, Pit is safe by construction.

Applicability: this ledger was written against 9466791a, we build from a3184e5e

The worklist below was drawn up against the 47k-line tip. This branch starts from the last green commit instead, so a good part of it describes code that was never written here. Surveyed on the base:

Two consequences worth stating plainly. First, section A evaporates — the single largest cleanup on the list is work we now simply decline to do. Second, most of what remains is forward work rather than deletion, so the ledger’s framing (“delete X at file:line”) only fits rows G, K, L, and B1; everywhere else the line references point into a commit this branch does not contain and must be re-derived before use.

source/cache_profile_test.c, which proved caches-off correctness, also came with the 47k. Until it is rewritten, make check (vm suite, language suite, baseline, fuzz) is the gate for row G.

A. Delete the start-time authorization ceremony — N/A on this branch

The runner has exactly two callers — the shop, which holds the decision, and the C floor at cold boot, which mounts a medium trusted by ruling. Re-deriving the decision proves nothing (the checking code arrives in the same cart) and costs every actor start.

B. Uniform endowment delivery

No recipes in the runtime. Two cases only: a constant, or a unit’s return value.

C. The realization becomes fully explicit

“The runner should do no thinking” means the realization is a program in a very small language and the runner is its interpreter.

D. Minimal C

C is the audit surface. The Pit half of this already exists and is complete.

E. The boot actor

F. Split engine_lite

The runtime owns engine_lite (intrinsic, no realization names it) — so everything in it is paid for by every target, Gameboy included. It is 119 KB today.

G. Memory

H. Documentation — done

The site builds clean with no dead links. docs/ now describes the model above.

Correction recorded: deny_c was described in an older audit as wholly unbuilt. It is built — pit-shop/executable_manifest.cm:410 walks the extension bindings, traces the import path back to the root, and fails the build, with tests at tests/executable_artifacts.cm:239. The docs describe it accurately.

Still open in docs: docs/shop/spec.md — see section J.

J. Split docs/shop/spec.md — done

The page is mined and deleted.

K. Delete shop modes — capability is cart composition

Ruled: what a shop can do is decided by which actors its boot cart carries, not by a mode. No compiler actor means it cannot compile; no cake means it cannot build C; no realizer means it resolves nothing it was not shipped. The absence is structural and therefore checkable — the same argument the docs already make for omitting $runtime. If no combination fits, write a bespoke boot actor and put that on the cart.

docs/shop/compilation.md already described exactly this (“you choose which actors to include”); spec.md’s mode table contradicted it. The doc side is now fixed.

L. No hardcoded targets — docs done, code to audit

Edict: a target name is a label for a set of lever positions, not something the system knows. Nothing in the VM, compiler, shop, or runtime branches on “is this a PS1”. A build script sets levers — word width, numeric rep, collector, scheduler, powers, and which actors the cart carries — and that combination is the build. Two components legitimately know target names because they straddle the C boundary: cake (per-platform sources, flags, toolchains) and raw endowments (thin wrappers over one OS’s real surface).

Docs updated: target-profiles.md is now explicitly normative and says a target name is a label; its axis table no longer enumerates a closed target list. targets.md is reframed as a catalog of settings that have been built, plus how to add one. consoles.md reads as hardware rationale for lever positions. extensions.md names cake as the exception.

M. Retiring the ABI crossing — measured on the green base

The crossing exists because boot/root.cart carries the engine as a finalized pool. Bump the Mach ABI and the runtime refuses its own engine, so it cannot run the Pit code that would re-cement the cart. Four agents lost a session to that circle.

Three things were established by experiment on a3184e5e, not by reading:

1. The Pit step and the ABI step are cleanly separable (pit-shop/shop_build.cm:2244). compiler.compile_result(source) produces streamlined mcode in Pit and is ABI-neutral; mach.mach_compile_mcode_bin(mcode) produces the stamped pool and is C. Recompiling internal/engine_lite.cm from source and serializing reproduces the committed boot/engine_lite.mach byte for byte — blake2 e9162acb…, 119,684 bytes both sides. Round-tripping the mcode through JSON and re-serializing yields the identical pool, so the mcode alone is a sufficient input.

2. A loose engine on disk is never consulted at boot — hypothesis disproven. boot_mach_data is fed only from pit_cart_engine_image() (source/scheduler.c:3851, :3879); the engine always rides inside a mounted cart. With both carts moved aside and boot/engine_lite.mach + boot.qop present, a cold bare binary refuses outright: “no root cartridge: none appended, no boot/root.cart, and PIT_ROOT_CART is unset.” So “boot the engine plus the qop with no cart” is not a path. boot/engine_lite.mach is a cementing input, not a boot input.

3. The C serialize step costs 7.5 ms. Measured five runs: 37.6 ms total, 7.5 ms each, against 1.16 s for the Pit compile. Caching it is unnecessary.

The fix

Let the cart’s engine section carry mcode rather than a finalized pool, with one header bit saying which form it is. C serializes at mount when it is mcode — 7.5 ms — and runs the result at whatever ABI the binary was built for. The same dev cart then boots on a v2 or a v3 binary, and an ABI bump requires no re-cementing at all.

This is the rule the system already applies to payloads, applied to the engine: dev ships mcode because mcode survives VM edits, ship cements the finalized pool. A shipped cart is unchanged — finalized engine, zero serialize cost.

The engine is one translation unit — a standing constraint

Two steps make images, and only one of them is C:

At the green base nothing fuses units at all: an executable is a record whose modules array carries one blob each (pit-shop/shop_build.cm:347, :383, :456), and the cart cements those N blobs into sections. The link group is the new idea.

So M1 is viable only because internal/engine_lite.cm has no use() imports and is therefore a single mcode unit that C’s 1:1 serializer can rebuild. Were the engine ever several units, C would need the pool emitter, and porting 958 lines of Pit into the audit surface is exactly what the minimal-C edict forbids.

This constrains F2. Splitting the ~1,870 lines of standard library out of the engine must be done by removing code from engine_lite.cm into ordinary modules that go through the normal N:1 path — never by having the engine use() its pieces. An import would make the engine multi-unit and silently break C’s ability to rebuild it, which would surface only as a failed ABI bump much later. Done the right way F2 helps M: a smaller engine means less mcode in the cart than the 955 KB measured today.

Corroboration that this is the grain of the system rather than a new invention: payload_mode already has mcode / mach / mixed arms with a matching engine_abi (pit-shop/shop_build.cm:278-298). Dev-ships-mcode is implemented one level up already; M extends it to the engine.

L1 findings — audited on the green base

The codebase is not uniformly leaky. It is clean where the levers already exist and target-keyed where they do not. pit-compiler/ branches only on rep names, never on target names (rep_fold.cm:301-312); pitlib/ has zero hits; the shop’s source resolver does target arms by data lookup with no hardcoded names (shop_source.cm:694-716); and internal/sysfacts.c / source/pit.c:12-16 publish PIT_TARGET_* as build-injected facts with "unknown" defaults, which is the right plumbing. Two places already demonstrate the correct pattern: rep-keyed folding in pit-compiler/rep_fold.cm, and lever-keyed sizing in source/capacity_harness.c (contrast adder_harness.c, which does the same job by being the PS1).

There is one structural spine and nearly everything hangs off it. source/pit_profile.h is an eight-arm #if/#elif chain — one per console, at lines 13, 26, 41, 57, 146, 177, 275, #else 305 — and each arm sets profile name, value-word bits, object ABI, numeric rep, region defaults, and image cap together, indivisibly. Because a cart’s stamp must match that bundle byte for byte, pit-shop/rep_profile.cm:60-69 was forced to grow a mirror-image TARGET_AXES = {psp, dc, n64, ps1} table in the shop, which internal/cement.ce:250,360,412 then threads through as --target. Adding a console today means editing pit_profile.h, sys_thread.h, rep_profile.cm, three package.json manifests, and pit-linker/toolchains.cm — runtime enums that grow, which is what the edict forbids. Fixing pit_profile.h collapses most of the rest in one move.

Four axes do not exist and are required:

Three more removals need no new axis, only routing: the profile name as a build-supplied string rather than a chain output; default content path as a startup fact (shop_actor.ce:138-139 hardcodes playdate/emscripten); and provider set discovered from linked providers rather than declared by hand in internal/policy.ce:13-27, which enumerates every platform’s raw endowments by name.

Platform-fact leaks — portable code doing OS-specific work. Well-scoped, no new axis, each belongs in platform/<os>/: internal/vm.c:82-89 (Playdate memory stats called from the portable VM-stats endowment), source/runtime.c:2589,2617 (pit_web_log_tee inside Pit_Log), source/host.c:242-249 (macOS .app path sniffing), source/crash.c:159-165 (Win32 pipe shim), internal/bundle.ce:238-249 (hardcoded macOS .app layout).

Build-system work outside cake. pit-linker/build.cm selects IO backends, link flags, Objective-C source lists, and executable suffixes by tc.system (lines 526-528, 546-557, 859-873, 2032, 2156-2161), and pit-linker/toolchains.cm carries the canonical 22-target supported list plus a hardcoded developer path at line 14. Legitimate kind of work in the wrong folder — cake already owns plan.link_flags(tc).

Roughly 410 further target-name mentions are non-branching: comments, log strings, help text, test fixture names. Not worth touching.

RULING NEEDED — endian

docs/architecture/target-profiles.md lists endian in the axes table, but the profile string it documents carries no endian= field, and source/pit_profile.h:58-70 says the omission is deliberate, with a stated reason: adding it “would change every existing little-endian stamp and break the desktop cart’s byte-identity.” Endian instead travels three ways — the distinct profile name (n64-nan32-v1), the mach header’s endian byte, and the cart header’s endian byte.

That decision is exactly what forces rep_profile.cm:60-69 to recover byte order from the literal name n64, which is a target-name branch in the shop and precisely what the edict forbids. The two positions cannot both stand:

• Add endian= to the profile string. The name stops being semantically load-bearing and the shop’s target table dies. Cost: every existing stamp changes. That cost is near zero right now — the Mach ABI is being bumped anyway, so stamps are already moving. It will not be near zero later.
• Keep it out. The profile name stays load-bearing, and the shop keeps a name-to-endian table that the edict has to carve out an exception for.

The doc currently asserts the first and the code implements the second, so one of them is wrong either way. Recommend adding the axis while stamps are already in motion.

Source: plans/archive/worklist.md