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

The v1 plan/cart format — complete writer/reader map (recon, 2026-07-28)

SUPERSEDED 2026-07-28 by landing 4b. The step/binding layout mapped below no longer exists: the PLANS section (kind 10) is retired and the executable is an ordered ENTRIES array (kind 11) plus the NAMES each entry binds. Kept because the reader inventory and the coupling notes were what made the landing cheap, and because the phase-1/phase-2 crossing it predicted is recorded against it in plans/next-arc.md. The Discrepancy below is FIXED: the three comments no longer cite sections that do not exist. Everything else here is history.

Produced by the keystone recon sweep for landing 4b. This is the COMPLETE baked-caller surface of the plan format the entries-array conversion replaces. Key facts up top; the full line-level map is in the recon report (session transcript) — the essentials that must survive are here.

The essentials

  • ONE writer: pit-shop/cement.cm (build_exec_plan :330-445, build_one_plan :655-717, build_plans :719-734). Row layouts: 40-byte head, 40-byte step, 16-byte import, 8-byte provide, 16-byte binding. Vocabulary: STEP_ENGINE=3/SCRIPT=0/STATIC=1/NATIVE=2/ NATIVE_PROGRAM=4; BIND_ENGINE=0/ENDOWMENT=1/BOOT_GLOBAL=2 (+3 reserved); flags packed high-16. ENGINE_NAMES (:83-96, 36 names) is the build-time membership set 4a’s resolution lane replaces.
  • FOUR reader files: source/start_plan.c (the walk, :308-743; row sizes mirrored :45-50), cart/cart.cm (a SECOND FULL decoder :389-478 + verifier :1181-1241 + the ship extension spec via claims_closure :767-803 harvesting endowment-class binding rows), source/cart_boot.c (BOOT head only: engine module index + root_exec_plus1), and engine/engine_lite.cm’s build_engine_record (:1743-60, the BIND_ENGINE runtime half).
  • THE load-bearing coupling: plan SCRIPT-STEP ORDER == EXECS module-row order (cart.cm:1212 asserts text-equality of the index lists). Step rows carry an EXPLICIT MODULES index — “step index == module index” is NOT the invariant.
  • Engine-is-step-0 is written (cement:349), refused otherwise (start_plan:508), offsets both walker loops (i=1), and verified (cart.cm:1188). Step 0’s module_index is written 0 and NEVER READ — the engine’s bytes come from BOOT→MODULES→CODE via pit_cart_engine_image, not from the step.
  • (image_id, exec_index) selection: root = (0, BOOT.root_exec_plus1-1); cart lane = (0, LOCATORS arm’s exec field); scratch lane = (register_image’s id, 0). No realization field carries these.
  • EXECRECS ↔ EXECS ↔ PLANS are parallel-indexed (one row each per exec).
  • Cement’s realization reads: the field table lives in tests/executable_cache_round_trip.ce:49-55 (CEMENT_READS) + GRAFTED (endowments_by_module, program_dylib_path). static_bindings is the ONLY source of plan import rows (cement:389-409).
  • Scratch lane: shop_actor.ce:586-640 (image_from_executable → register_image → start_via_plan with plan_exec=0); shop_actor is the module that calls cement at runtime (use(‘cement’) :24).
  • Row layouts are pinned only transitively — no unit test decodes a plan window and asserts sizes/kinds directly; the pins are cart-verify over a real cart + the byte-identity cache test. 4b’s deletion should not need to add such a test; the new format gets its own.

Discrepancy (fix rides 4b)

cement.cm:2-3/:654, cart/cart.cm:10, cart_boot.c:59 all cite docs/spec/artifact-formats.md "Cartridges (pit.cart@1)"/"PLANS" — sections that DO NOT EXIST. The spec documents only the incompatible v2 (pcr2). The v1 format cement writes is specified ONLY by its three implementations (cement.cm:19 and cart.cm:73-74 carry keep-in-sync comments naming each other). 4b either deletes the format (making this moot) or the comments say so honestly.

Source: plans/archive/plan-format-map.md