Workspace, crates, formats
6,855 words14 subsections8 tables1 listingPlan version 1.1
On this page14
This chapter fixes where code lives, what each crate is for and how large it may grow before someone asks why, which crate may depend on which, which artifact formats exist and who owns each, and the working rules. Its purpose is to keep a large program reviewable: a reader should be able to find the crate for any sentence of Parts III to V, and a tool should be able to refuse a dependency this chapter forbids.
34.1 Repository layout
franken_robotics/
Cargo.toml rust-toolchain.toml franken-stack.lock # core workspace; the one toolchain T (§33.13)
.cargo/config.toml # build-identity setting for path consumption (§33.2)
AGENTS.md README.md DEPENDENCY_ADMISSION.md COMPREHENSIVE_PLAN_FOR_FRANKEN_ROBOTICS.md
crates/frob-*/ # the core: 38 crates, unsafe denied, Franken-only runtime dependencies
crates/frob-cert/ # also builds alone, on a stable compiler, with no dependency (§34.11)
surface/frob-mcp/ # MCP server on fastmcp_rust; core workspace member; links frob-verbs (§32.12.2)
spark/frob-spark-cuda/ # annex workspace on T: cudarc, registered unsafe capsules
spark/frob-spark-metal/ # annex workspace on T: ft-kernel-metal gateway
apps/ # workspace that links core + annexes into frob, frobd
worker/ # workspace manifest for frob-fsim-worker (INT-FSIM-18; KILL-FSIM fallback (a))
derive/frob-derive/ # annex workspace on T: build-time derivation with FrankenSymPy
bindings/frob-gymnasium/ # optional Gymnasium-compatible adapter: a Rust shim and a Python package
lean/ # Lake project; outputs not committed
viewer/ # Three.js viewer and HTML export
kernels/ # shared-dialect sources and generated arithmetic, with digests
registries/ # verbs.toml, refusals.toml, kernels.toml, gates.toml, formats.toml, upstream.toml,
# lifts.toml, capsules.toml, cards/
schemas/ # generated from formats.toml and verbs.toml; never edited
demos/ # one demo.yaml per release path (§34.12)
receipts/ # resolution receipts (§33.5)
assets/ # templates, generic actuator and interface cards, license manifests
tests/fixtures/oracle/ # pinned oracle captures, never regenerated from the candidate
tools/oracle/ # capture scripts for development-time oracles
docs/delivery/ # the delivery log (never in this plan)
Six workspaces exist: the core, which includes surface/frob-mcp, the two GPU annexes, apps/, derive/ and
bindings/, with worker/ as a seventh that only re-targets an existing crate. All of them build on T, and no
annex carries a toolchain file of its own (§33.13); lean/ is not Rust. One exception is a fallback by design:
when KILL-FSIM's fallback (a) keeps the worker at an older pin, worker/ builds on that pin's toolchain
(§33.14). The reason for an annex boundary is never the compiler. It is the unsafe and foreign-interface policy:
a dependency the core's lockfile may not contain (a third-party driver binding, an FFI capsule, a Python
interpreter, FrankenSymPy at build time).
The two GPU annexes keep their own lockfiles for that reason, and it rests on FACTs of §21.2 and §33.13: the
suite keeps its working GPU code outside FrankenSim's workspace, cudarc is a third-party driver binding, and
ft-kernel-metal needs FrankenTorch's [patch.crates-io] block entry at the root of whichever workspace
resolves it. A separate lockfile keeps the driver bindings, the registered capsules and that patch out of the
core's resolution (rules L-3 and L-4, §34.4). surface/frob-mcp has no such reason: fastmcp_rust is a Franken
foundation that forbids unsafe code (FACT, §32.12.1), so the server is an ordinary member of the core workspace
and its directory name says only that it is a surface.
34.2 Crate map
Scope caps are in thousands of lines of Rust including tests (DESIGN). They are caps that trigger a scope conversation at 115%, not estimates of effort or schedule. The tier column gives the tiers of the crate's contents: a crate marked F or M alone contains no Solid mechanism, its mechanisms carry their pilots and kill gates in its chapter, and nothing marked M is on a critical path. Within a layer the rows are in dependency order (rule L-1). Each crate is specified by the chapter named in its row; this table is the index.
| Crate | Layer | Tier | Responsibility | Chapter | Cap |
|---|---|---|---|---|---|
frob-core |
0 | S | Identities and hashing; evidence classes and the claim-product type; refusals; schema versions and format-registry types; artifact-graph identifiers; the qty re-export; the no-authorization flags |
§8, §12, §35 | 8 |
frob-fsim |
0 | S | The airlock: adapters to FrankenSim's volatile crates in feature groups; the remote mode and the worker binary |
§33 | 20 |
frob-lie |
1 | S | Lie groups and algebras, subgroups, retractions, frame typing, conventions | §13 | 12 |
frob-algebra |
1 | S | Finite groups and representations, cones and the cone solver, posets, the inertia cone | §13 | 14 |
frob-kir |
1 | S, F | Straight-line programs with bounded loops and resource metadata, dimension checking, differentiation, emitters; the exact-integer kernel class | §21 | 14 |
frob-actuate |
2 | S | Actuator, transmission, battery, bus and thermal models; joint stiction and backlash parameters; cards | §15 | 12 |
frob-design |
2 | S | Design terms, constructors, typed edits, lints; modules with port contracts; archetypes; the S-expression view | §14 | 18 |
frob-model |
2 | S | The model compiler, functors, lowerings, compile memoization | §14 | 16 |
frob-io |
2 | S | URDF and MJCF import and export, loss reports, the XML reader, fuzz targets | §14 | 10 |
frob-scene |
2 | S, F | Scene packs, the scene compiler, terrain and interior generators, import and acceptance; optical and fixture properties; clearance complexes; the retrofit catalog; living-world state | §19 | 28 |
frob-kernels |
3 | S | The kernel library: manifests, Rust skeletons, generated arithmetic, exact and guarded predicates | §21 | 26 |
frob-contact |
3 | S, F | Collision geometry, detection, contact laws (convex compliant, the four-dimensional cone, joint rows, film friction, the hard-contact law), wheels, tracks, terrain mechanics | §18 | 22 |
frob-dyn |
3 | S, F | The batched step, integrators, tiers, the trust ladder; the transactional event-located step with witness migration; the variational lane | §16 | 20 |
frob-phylum |
3 | S, F | Model variants inside padded capacities, size buckets, design-family buckets; the batch-independence test | §17 | 10 |
frob-sense |
3 | S | Sensor models, the clock contract, packet queues, the observation service, observability | §20 | 14 |
frob-spec |
4 | S | The task and mission languages: terms, requirements, randomization, quantifiers | §24, §25 | 8 |
frob-control |
4 | S, F | The invariant filter, controller synthesis, control programs, skills | §22 | 16 |
frob-gait |
4 | F | Gait orbits, return maps, stability, continuation in morphology | §22 | 8 |
frob-analyze |
4 | S | Static analyses and preflight | §14, §28 | 20 |
frob-learn |
4 | S, F | The environment API and its reset semantics, learners, networks, family policies, inheritance, the FrankenTorch bridge | §23 | 18 |
frob-arena |
4 | S | Tasks, fixtures, metrics, scorecards, batteries; the two study types; the blinded qualification lane | §24 | 14 |
frob-opt |
4 | S, F | Comparison, lineage, optimization, the archive, predictions, the cascade, decision cores | §28 | 14 |
frob-shield |
5 | F | Energy budgets and runtime shields with a backup | §22 | 8 |
frob-autopsy |
5 | S | Counterfactual forks under interventions, attribution, the stability report | §27 | 8 |
frob-nemesis |
5 | S, F | Adversarial world search, shrinking to minimal counterexample worlds, bounded-weight rare-event estimation | §26 | 10 |
frob-ground |
5 | F | Calibration against measurements: clock fitting, identifiability, frozen predictions, reality bands | §30 | 10 |
frob-synth |
5 | F, M | Bounded exact linkage synthesis; trajectory optimization with design variables; continuation lanes | §25, §28 | 10 |
frob-foundry |
5 | F | Structure, fatigue, tolerance allocation, build packets | §31 | 12 |
frob-lifecycle |
5 | M | Lifecycle compression | §31 | 6 |
frob-mission |
5 | F | Mission queries, inner and outer design sets, region certificates, probe and experiment suggestion | §25 | 14 |
frob-cert |
6 | S | The certificate bundle reader and checkers; the frob-verify binary; standard library only |
§12 | 12 |
frob-chronicle |
6 | S | Telemetry, episode files, replay and forks, digests, the energy ledger, the job and chunk store, the memo store, summaries, stills | §29 | 18 |
frob-lemma |
6 | S, F | Claims, certificate production, bundle writing, theorem cards, the reflection route | §12 | 10 |
frob-verbs |
6 | S | The verb registry, envelope, schemas, verb implementations, the daemon's job engine, the memo graph in front of executors | §32, §28 | 22 |
surface/frob-mcp |
7 | S | The frob-mcp server on fastmcp_rust, generated from the registry; it links frob-verbs and runs verbs in process, and is the library frobd --mcp hosts |
§32 | 6 |
frob-cli |
7 | S | The frob and frobd binaries |
§32 | 8 |
frob-tui |
7 | F | The frob-tui dashboard on frankentui |
§32 | 6 |
frob-conformance |
7 | S | The Gauntlet harness, oracle fixtures, known answers, the counterexample catalogue, the ten-fold harness | §38, §39 | 24 |
xtask |
7 | S | Six checks (§34.6) | §34 | 3 |
spark/frob-spark-cuda |
annex | S | CUDA backend, arena lease, binary kernel cache | §21 | 8 |
spark/frob-spark-metal |
annex | S | Metal backend | §21 | 7 |
derive/frob-derive |
annex | F | Symbolic derivations, certificate production, the exact-synthesis subprocess | §21, §12 | 14 |
bindings/frob-gymnasium |
annex | S | A thin adapter that lets a Gymnasium-compatible learner drive the Rust VecEnv; the only place a Python interpreter may appear, and never in a production graph |
§23 | 3 |
| Total | 39 core crates (38 under crates/ and surface/frob-mcp) and 4 annex crates |
561 |
| Layer | Crates | Cap |
|---|---|---|
| 0 | 2 | 28 |
| 1 | 3 | 40 |
| 2 | 5 | 84 |
| 3 | 5 | 92 |
| 4 | 7 | 98 |
| 5 | 8 | 78 |
| 6 | 4 | 62 |
| 7 | 5 | 47 |
| Annexes | 4 | 32 |
| Total | 43 | 561 |
Reading the total. Eight core crates hold only Frontier or Moonshot content (frob-gait, frob-shield,
frob-ground, frob-synth, frob-foundry, frob-lifecycle, frob-mission, frob-tui); their caps sum to
74. The remaining 487 is the spine and the mixed crates. The total at the 115% trigger is 645. Additional and
not Rust: kernel sources in the shared dialect (cap 20 thousand lines), the viewer (cap 12 thousand lines of
JavaScript), the Lean project, and the Python half of the Gymnasium adapter (cap 1 thousand lines). Conditional
and not counted: frob-units (layer 0, cap 3), which exists only if INT-TOOLCHAIN-01 forces it (§33.12). The
binary frob-fsim-worker is a target of frob-fsim and frob-verify is a target of frob-cert; neither is a
crate.
A cap is a claim about scope that can be wrong in both directions. A crate that reaches 115% stops taking new mechanisms until an ADR either raises the cap with a reason or moves a mechanism out. A crate that ships its chapter in half its cap is not a problem to be fixed.
34.3 Layer and dependency rules
- L-1 A crate depends only on lower crates.
xtask check-layersfails a deliberate upward edge. Lower means a lower layer number, or the same layer and an earlier row of the crate map. Each crate declares both in its manifest ([package.metadata.frob] layer = 3,rank = 2), the convention FrankenSim uses for its own layers (FACT:[package.metadata.frankensim] layerinfrankensim/crates/fs-exec/Cargo.toml). A chapter that needs a different order inside a layer changes the rank by ADR; a cycle is never admitted. - L-2 Only
frob-fsimnames types from FrankenSim's volatile crates. The bedrock-direct list is the only exception, andfs-qtyis named only throughfrob_core::qty(§33.12). - L-3 The core never depends on an annex. Backends implement core traits.
- L-4 Each foundation is confined to the crates in its
FD-row. - L-5 Core runtime dependencies are
stdand Franken foundations.serdeandserde_jsonat exact pins are allowed in boundary crates only (frob-io,frob-verbs,frob-chronicle,frob-design,frob-spec,surface/frob-mcp), never in a hot path. Forbidden everywhere: tokio and its ecosystem, a direct Rayon pool, BLAS and LAPACK, C or C++ numerical libraries. A Python interpreter is forbidden everywhere exceptbindings/frob-gymnasium. - L-6 No bare
f64physical quantity in a public signature above layer 1. Quantities arefrob_core::qtytypes or group elements. - L-7 Library crates do not print. Hot loops emit no per-iteration JSON.
- L-8 Generated files are never edited.
xtask check-generatedregenerates and compares. - L-9
frob-certhas an empty dependency table, and onlyfrob-verbs,frob-cliandfrob-conformancemay depend on it (§34.11). - L-10 A lower crate reaches a service that lives above it only through a trait it defines itself, as
backends do under L-3. The standing inversions are five: the device backend (defined in
frob-dyn, implemented in the annexes); the evidence sink and the trace source (both defined infrob-core, implemented infrob-chronicle); the job context for cancellation and budgets (defined infrob-core, supplied by the daemon); and the certificate sink (defined infrob-core, implemented infrob-lemma). This is what lets a layer-5 crate such asfrob-autopsyfork a recorded run without depending on layer 6. - L-11 Two planes. Kernels and the step never depend on a dispatcher, a memo policy, an estimator or a
scheduler: no crate of layers 1 to 3 holds one. Decisions about what to run live at layer 4 and above and in
the daemon (§34.12). Compile memoization in
frob-modelis a pure cache keyed by identity with a fixed bound, not a policy; the memo graph for results sits in front of verb executors infrob-verbs, with its bytes infrob-chronicle. - L-12 Features that select a tier of ambition are named and off by default:
frontier-*andmoonshot-*features gate every F and M mechanism in a mixed crate, and no default build enables one.
Honesty about the closure: path dependencies on FrankenSim bring its transitive closure, which includes
third-party crates such as nalgebra and rayon through other siblings (FACT: 262 registry packages among the
479 in frankensim/Cargo.lock; nalgebra 0.35.0 and rayon 1.12.0 are among them). "Franken-only" describes
direct edges.
Counterexample for L-1's intra-layer clause. If rows inside a layer were unordered, frob-arena could depend on
frob-opt for comparison while frob-opt depends on frob-arena for batteries, and Cargo would reject the
cycle only after both were written. The rank makes the second edge a check-layers failure on the day it is
added.
34.4 Unsafe code
The core has unsafe_code = "deny" and plans zero capsules: SIMD comes from fs-simd, arenas from FrankenSim's
substrate. frob-cert goes further and forbids it at the crate root. The annexes may contain capsules, each
registered in registries/capsules.toml, under 300 lines, behind a safe API, with a SAFETY.md (FrankenSim's
capsule discipline, FACT: frankensim/unsafe-capsules.json and frankensim/AGENTS.md, "Unsafe Code"). No
total is promised for the annexes: a driver binding with pools, graphs and runtime compilation needs what it
needs, and the count is reported per capsule by check-unsafe. Unsafe is never used to work around a lifetime,
aliasing, cancellation or synchronization problem.
34.5 Contracts
Every crate ships CONTRACT.md with the ten sections of §0.2 and a tests/conformance.rs. A crate becomes a
dependency target only after its contract lands. Beside the prose sits a small machine-readable record,
contract.toml, with the crate's layer and rank, its determinism class, the evidence class of its outputs, its
budgets, its feature flags with their tiers, and its safe mode (§34.12). check-contracts validates the record
against the manifest and the registries; it does not grade the prose.
34.6 The six checks
xtask contains exactly: check-layers, check-deps, check-unsafe, check-generated, check-contracts,
check-stack. A seventh check needs a named defect class it would have caught and the owner's approval. This is
the guard against the process growth FrankenMining recorded. Everything this chapter and §33 ask a tool to
enforce is assigned to one of the six:
| Check | Enforces |
|---|---|
check-layers |
L-1 with layer and rank, L-3, L-10, L-11 |
check-deps |
L-2, L-4, L-5, L-9; one asupersync package per binary; no asupersync 0.5.0 anywhere; the forbidden frankentui feature; feature groups of frob-fsim enabled only by the crates listed for them; L-12's default-off rule |
check-unsafe |
The deny lint in the core; every annex capsule registered, under its line limit, with its SAFETY.md |
check-generated |
L-8 for schemas, the command-line and MCP surfaces generated from verbs.toml, generated kernel arithmetic, and the README status table |
check-contracts |
CONTRACT.md sections; contract.toml; every format row has an owner, a round-trip test and a refusal test; every release path has a demo file whose claims exist in gates.toml; every crate's line count against its cap, reported, with 115% as a failure that an ADR clears |
check-stack |
The stack lock, with T, against lockfiles, toolchain files and sibling heads; the resolution receipt; drift classification; the check itself writes nothing to a sibling checkout |
xtask runs no physics, records no gate and holds no policy. Its own cap is 3 thousand lines, and its test suite
asserts that the subcommand count is six.
34.7 Working rules inherited from the machine and the suite
FACT, from the machine-level agent instructions and from frankensim/AGENTS.md, adopted here:
- Cargo runs through the build-offload shim, which queues for a worker and never compiles locally; cargo is not
invoked by absolute path. Projects stay under
~/projects. Isolated target directories use${RCH_TARGET_BASE:-${TMPDIR:-/tmp}}/<name>, and large scratch uses${BIG_SCRATCH:-${TMPDIR:-/tmp}}/<name>. - A disk preflight precedes heavy lanes.
- The machine envelope. No run on any host uses more than 16 GiB of memory, 8 cores or one hour of wall time without the owner's written approval given before it starts; builds and tests count; a run longer than a few minutes starts under a timeout; when an agent stops, its jobs stop. Lanes of this plan that need more (the world bank on the M5 Ultra, training campaigns on the two RTX 4090, the tournament of §39) name their budget in their work package and wait for that approval. Until it is given, the envelope is the default of OPEN-SPARK-2.
- No file is deleted without explicit permission. No branches and no worktrees: work lands on
main, and file reservations through Agent Mail replace branches. ubsruns on changed files before a commit. Formatting, lints and tests run before a commit. Beads are managed withbrand triaged withbv --robot-*.- Source that was never compiled does not land. The commit message carries the commands and their results.
- Code is changed by focused patches, not by scripts or broad regular-expression rewrites. An existing file is revised in place; a new file must be new functionality or a required contract or test artifact.
- Before a build failure is attributed to this repository,
xtask check-stackruns. An off-pin sibling is classified as a fast-forward or a divergence before any remedy is proposed, and a sibling checkout is never moved back to its pin to make a check pass. - Process is never the product. Before non-product work an agent answers three questions: which capability, defect or blocker does this address, is it the smallest direct action, and is it worth its cost now. If any answer is unclear the work is not done.
- The machine-level rule on Apple Simulator audio applies to any use of a device simulator. This plan uses none.
34.8 What ships with the first commit
AGENTS.md, README.md with an honest-status table, this plan, franken-stack.lock, the first resolution
receipt, DEPENDENCY_ADMISSION.md, one rust-toolchain.toml for the whole build graph (it names candidate (a)
of §33.13 until INT-TOOLCHAIN-01 records T) and .cargo/config.toml, the registries (schema-valid, and empty
except formats.toml, which carries the thirteen rows of §34.9 with their owners), the schemas for demo.yaml
and contract.toml, and the initial beads, including the two P0 upstream work items FD-FMCP-01 and FD-ASUP-01.
FrankenTextiles shipped its companions with its plan and recorded that as worth repeating (FACT). The first
commit contains no crate that has not compiled (§34.7), so it may contain no crate at all; crates arrive with the
first implementation session (§46), each with its contract.
34.9 The format registry
ADR-WS-03: every artifact format has one identifier, one schema name with a version, one owner crate, and one canonical encoding. Everything else is a view. S
An artifact that agents exchange, cite and cache needs an identity that does not depend on who wrote the bytes.
The registry lives in registries/formats.toml; schemas/ is generated from it; the table below is its content.
A format is canonical when the hash of its canonical bytes is the artifact's identity. A view is a rendering for
a reader or another tool; it is never hashed, signed or cited.
| Identifier | Extension | Schema | Owner crate | Produced by | Consumed by | Canonical or view |
|---|---|---|---|---|---|---|
FMT-FBOT |
.fbot |
frob.design/1 |
frob-design |
Agents and people; typed edits; importers in frob-io; proposals from frob-opt, frob-synth, frob-mission |
frob-model, frob-analyze, exporters in frob-io, the viewer |
Canonical: canonical JSON. View: an S-expression text, lossless in both directions and optional |
FMT-FMODULE |
.fmodule |
frob.module/1 |
frob-design |
Authored; extracted from a design by a typed edit | frob-design (composition), frob-model |
Canonical. Carries its port contract |
FMT-FCARD |
.fcard |
frob.card/1 |
frob-actuate |
Authored from data sheets with per-field provenance; frob-ground as a new revision with fitted values |
frob-actuate, frob-model, frob-arena (randomization from stated uncertainty), frob-foundry |
Canonical. Kinds, a closed list in registries/formats.toml: actuator, transmission, battery, interface, material, soil, optical, sensor, payload |
FMT-FSCENE |
.fscene |
frob.scene/1 |
frob-scene |
Generators; importers and the scan adapter; authored | The scene compiler, then frob-contact and frob-sense; frob-nemesis; the viewer |
Canonical: the manifest. Cooked bricks and meshes are derived blobs addressed by hash |
FMT-FCLEAR |
.fclear |
frob.clearance/1 |
frob-scene |
frob-scene, from a scene and a footprint family |
frob-analyze, frob-mission, frob-lemma |
Canonical and derived: reproducible from the identities of its inputs |
FMT-FTASK |
.ftask |
frob.task/1 |
frob-spec |
Authored; fixtures in frob-arena |
frob-learn, frob-arena, frob-opt, frob-nemesis |
Canonical |
FMT-FMISSION |
.fmission |
frob.mission/1 |
frob-spec |
Agents | frob-mission, its only evaluator; frob-lemma |
Canonical |
FMT-FENERGY |
.fenergy |
frob.energy/1 |
frob-shield |
frob-shield |
frob-shield, frob-mission, frob-lemma |
Canonical |
FMT-FSKILL |
.fskill |
frob.skill/1 |
frob-control |
Controller synthesis; frob-learn, with weights by reference |
frob-control, frob-learn, frob-arena, frob-shield |
Canonical. Weights are blobs addressed by hash |
FMT-FMCW |
.fmcw |
frob.mcw/1 |
frob-nemesis |
The shrinker in frob-nemesis |
frob-arena (regression batteries), frob-autopsy, frob-mission, the viewer |
Canonical and derived |
FMT-FRUN |
.frun |
frob.run/1 |
frob-chronicle |
frob-chronicle, from the step's telemetry buffers |
Replay, frob-autopsy, frob-ground, frob-arena, the viewer |
Canonical: a manifest and chunked binary columns. Views: array files through fnp-io, summaries, stills |
FMT-FBUILD |
.fbuild |
frob.build/1 |
frob-foundry |
frob-foundry |
People and downstream tools; frob-ground for as-built comparison |
Canonical: the manifest. Views: STEP and mesh files through fs-io, bills of materials |
FMT-FROBCERT |
.frobcert |
frob.cert/1 |
frob-cert (schema and reader) |
frob-lemma (the writer, written against the schema and sharing no code with the reader) |
frob-cert and frob-verify; frob-verbs |
Canonical. One file, self-contained |
Why two formats are owned by frob-spec and not by their evaluators: a task's requirements and a mission's
quantified statement are written in one requirement language, and a certificate about a mission must quote that
statement exactly. One parser and one canonical form remove the question of whether the learner, the arena and
the mission evaluator read the same sentence.
Registry rules (DESIGN):
- One owner. The owner crate holds the schema, the canonicalization rule, the reference reader and the
version refusal. No other crate parses the bytes; a crate below the owner's layer receives typed values. The
one exception is deliberate:
frob-certreads only.frobcert, and a bundle embeds the canonical bytes and hashes of the statements it is about, so the auditor never needs another crate's reader. - Identity. The identity of an artifact is the BLAKE3 hash of its canonical bytes under a domain string equal to its schema name. A view has no identity.
- Versions. The schema name carries a major version. Adding an optional field keeps it. A reader refuses an unknown major version and an unknown required field, and never parses on a best-effort basis. Migration is a typed edit that produces a new artifact with a link to the old one; the old identity stays valid for citing old evidence.
- Numbers. Integers above 2⁵³ travel as strings. Not-a-number and infinity are not representable. Each owner names one rule for floating-point fields that bear identity (shortest round-trip decimal, or exact rationals) and tests it.
- Payloads. Large data are blobs addressed by hash and referenced from a canonical manifest. A manifest never embeds a path on the machine that wrote it.
- Provenance on export. An artifact that leaves the tool carries the no-authorization flags (§12, §37), the schema name, and the stack receipt of the binary that wrote it.
Refusals:
| Code | Name | When |
|---|---|---|
FROB-REF-891 |
format-version-unsupported |
Unknown major version, or an unknown required field |
FROB-REF-892 |
view-is-not-identity |
A view is offered where an identity is required: to hash, to sign, to cite as evidence, or as a cache key |
FROB-REF-893 |
format-owner-bypass |
A file with a registered extension reaches a verb through a path that did not go through its owner's reader |
Known answers and counterexamples:
- The objects
{"b":1,"a":2}and{"a":2,"b":1}have one identity. - Counterexample to "hash the file as written": two files that differ in key order or whitespace would be two designs, and every memoized analysis of the first would miss on the second.
- Counterexample to "hash the in-memory value": a hash of a debug rendering or of a struct's layout changes with the compiler, so the same design would change identity at a pin move and every cached result would be orphaned.
- Counterexample to "the view is lossless, so hash either": the S-expression and the JSON of one design are different bytes. A cache keyed on whichever arrived first would hold two entries for one design and, worse, two verdicts that a reader could cite as independent.
- Counterexample to "tolerate unknown fields": a reader that ignores an unknown required field such as a contact-law selector would simulate a different robot from the one described and report it under the same identity.
Gate (TARGET). GATE-WS-02, claim type Known answer: for each of the thirteen formats, 10,000 seeded round trips canonical → value → canonical with zero byte differences; where a view exists, 10,000 round trips view → canonical → view with zero differences; every one of 10,000 single-byte mutations either fails to parse or changes the identity; and each reader survives 10⁷ fuzz executions with zero panics before the format's first release. Negative control: a reader built with key-order canonicalization disabled must fail the first clause.
34.10 The rule for creating a new crate
ADR-WS-01: the crate list of §34.2 is closed. A new crate is created only for a distinct dependency, a distinct device target, or a proof boundary. S
- A distinct dependency: the code needs a foundation, a feature group of the airlock or a third-party crate that
its natural home must not link.
frob-foundryis the plain case: thestructuregroup adds 13 FrankenSim crates and about 412 thousand lines of library source beyond what M1 already compiles (FACT, counted as in §33.3), and no other crate needs them.derive/frob-deriveis another: FrankenSymPy, which no runtime crate may link. - A distinct device target: the code compiles for a different processor, runtime or host. The two
sparkannexes,frob-tuiandbindings/frob-gymnasiumare of this kind. - A proof boundary: the code states or checks something whose trust must not depend on the code around it.
frob-certis the plain case.frob-specis one because certificates and qualification verdicts quantify over its sentences.frob-phylumis one because the statement "a world's trajectory does not depend on the batch it ran in" is tested at its boundary.frob-nemesisis one because the discovery lane may not read confirmation worlds (§24), and a crate boundary letscheck-depsenforce that the qualification code does not link the searcher.
"It is getting long" is not a reason; a module is the unit of organization inside a crate. "A different person
owns it" is not a reason either. An ADR that proposes a crate names which of the three reasons applies, the edge
that check-deps or check-layers will then enforce, and the cap. The rule governs additions. The 43 crates of
§34.2 were fixed together with the subsystems of Parts III to V, one bounded context each, and are not
re-litigated by it.
The opposite pressure is handled the same way. Two crates are merged when no dependency, target or proof
boundary separates them any longer; frob-lifecycle, the one all-Moonshot crate, is the first candidate if its
pilot fails, and its fallback is deletion, not absorption.
34.11 The independent auditor
ADR-WS-02: frob-cert and its binary frob-verify depend on the Rust standard library and on nothing else,
and no proposer depends on them. S
A certificate is only as good as the independence of what checks it. If the checker shares a parser, a hash
implementation, an arithmetic library or a units crate with the code that produced the bundle, one defect can
make both agree. The rule is therefore structural, and check-deps enforces it:
crates/frob-cert/Cargo.tomlhas an empty[dependencies]table: nofrob-*crate, no FrankenSim crate (so nofs-qtyand no nightly feature), no asupersync, noserde. It inherits nothing from the workspace manifest.- It carries its own toolchain file naming a stable release. A copy of the directory alone builds with
cargo build --releaseon that compiler. This also frees the auditor from the risk of §33.12. - It forbids unsafe code at the crate root, reads only the files named on its command line, opens no socket, reads no environment variable and spawns no process.
- It implements for itself what it needs: a canonical JSON reader, BLAKE3 (checked against the published test vectors), exact integer and rational arithmetic, outward-rounded interval arithmetic, and the checkers for each certificate kind of §12. Its cap of 12 thousand lines accounts for that.
- No crate that produces a claim or a certificate depends on it. Only
frob-verbs(to expose the check as a verb),frob-cliandfrob-conformancemay (rule L-9). The bundle writer lives infrob-lemmaand is written against the schema, sharing no code with the reader. - A FrankenSymPy-based re-check of the same bundles runs in
frob-conformanceas a second opinion (§33.4). It is an oracle for the auditor, never a part of it.
Known answer: cargo tree -p frob-cert prints one line. Counterexample to the shortcut "reuse frob-core's
hashing in the checker": a canonicalization defect in frob-core that drops a field before hashing would be
reproduced by the checker, and a bundle whose statement differs from the one the proposer evaluated would pass.
With two implementations the hashes disagree and the bundle is rejected.
Gate (TARGET). GATE-WS-03, claim type Known answer: the dependency count of frob-cert is zero; the copied
directory builds on its stable compiler with no network access; the standalone binary and the in-daemon verb
return identical verdicts on the whole conformance corpus of §38; and a system-call trace of an audit shows no
network and no process creation. The behavioural gates of the auditor (what it must accept and reject) are in
§12 and §38.
34.12 Suite conventions this project adopts
Six conventions of the wider suite are adopted. Each replaces an ad hoc habit with something a tool can check, and each is assigned to one of the six checks so that adopting it adds no seventh.
- Artifact-graph identifiers. Every gate claim has a
claim_idthat resolves to theevidence_ids of the records supporting it, thepolicy_idof the rule and thresholds in force, and thetrace_idof the run. FACT:franken-kernel0.6.0 definesTraceId,DecisionId,PolicyIdandSchemaVersionand has no claim or evidence identifier (asupersync/franken_kernel/src/lib.rs). DESIGN:frob-coremirrors the text form of the three it has, addsClaimIdandEvidenceIdin the same form, and adds them upstream (FD-FKER-01). Rows ofregistries/gates.tomlcarry theirclaim_id. - Contracts as code. Each crate's
contract.toml(§34.5) states budgets and a safe mode: what the crate does when a budget is exhausted or a calibration check fails, which is always to fall back to its reference path or to refuse by name. It is validated insidecheck-contracts. - A demo file linked to claims for every release path.
demos/<demo_id>/demo.yamllists thedemo_id, theclaim_ids it demonstrates, commands that finish in under 60 seconds on the CPU tier (TARGET), and checksums of their outputs. A capability with no demo is not released (§47). A demo is evidence that a path runs; it is never evidence for the claim's numbers, which come from the gate. - Shadow-run as the adoption wedge. A mechanism that replaces a reference path first runs beside it: both results are reported and the old one is acted on. It is promoted when its agreement gate passes and demoted by one flag. The incumbent is always this plan's own reference path: full recomputation for the memo graph, one batch per job for shared batches, the paired e-process for a variance-reduced estimator, the CPU referee for a device tier.
- Two planes. Computation and decision are separate (rule L-11). A kernel can be replayed without the policy that chose to run it, and a policy can be replaced without touching a digest.
- The controller gate. No adaptive controller ships (a scheduler, an allocator, a racing rule, a cache policy) without a replay scenario, evidence records, a calibration report and a demonstrated fallback. Two controllers that read the same telemetry need an interference test before both are enabled.
34.13 Invariants, gates and open questions
Invariants, each enforced by the check named:
- INV-WS-01 The dependency graph respects layer and rank (
check-layers). - INV-WS-02
frob-certhas no dependency and no proposer depends on it (check-deps). - INV-WS-03 Every registered extension has exactly one owner crate, and no other crate contains a parser for
it (
check-contracts, by a search for the schema name outside the owner). - INV-WS-04 No default build enables a
frontier-*ormoonshot-*feature (check-deps). - INV-WS-05
xtaskhas six subcommands (its own test).
Gates (TARGET):
| Gate | Claim | Criterion |
|---|---|---|
| GATE-WS-01 | Known answer | A deliberate upward edge, a deliberate intra-layer edge against rank, a second asupersync package, an unregistered capsule, an edited generated file, a contract missing a section and a stale stack lock are each planted in a scratch copy; each plant is caught by the check that owns it and by no other: 7 of 7 plants caught, 0 failures on the clean tree |
| GATE-WS-02 | Known answer | The format registry round trips of §34.9 |
| GATE-WS-03 | Known answer | The auditor's independence, §34.11 |
| GATE-WS-04 | Performance | The six checks together finish in at most 60 seconds on a warm tree, so that they are run and not skipped |
Open questions:
| ID | Question | Default if undecided | Decided by |
|---|---|---|---|
| OPEN-WS-1 | The rank order inside layers 4 and 5, where the chapters of Part IV may need edges this table did not foresee | The order of §34.2; a change is an ADR | The first contract of each crate |
| OPEN-WS-2 | Whether frob-tui stays in the core workspace or becomes an annex |
Core. If INT-FTUI-01 shows frankentui does not build on T, the remedy is an upstream change in frankentui or the toolchain train, with no dashboard until it lands | INT-FTUI-01 |
| OPEN-WS-3 | The stable release named in frob-cert's toolchain file |
The newest stable release on the day of its first commit, then moved only by ADR | The first commit of frob-cert |
| OPEN-WS-4 | Whether .fmission is owned by frob-spec or by frob-mission |
frob-spec, for the reason in §34.9 |
The contract of frob-spec |
| OPEN-WS-5 | Whether the Gymnasium adapter binds in process or across a process boundary | Across a process boundary with shared array files, so that no interpreter is ever in a frob binary |
§23; the adapter's contract |
34.14 The canonical reader and writer, and JSON features that unify across the build
What it is. S The mechanism behind the rule "a duplicate key refuses" (§14.4), for every artifact format of §34.9, and a guard against a dependency feature changing canonical bytes.
The reader. DESIGN: admission validates the raw bytes before any map is built or any digest is computed.
- Member names are compared after escape decoding, at every nesting level, and a repeated name is refused.
Smallest case:
{"wheel_radius_mm": 60, "wheel_radius_mm": 75}names one member twice. A reader that keeps the first value simulates a 60 mm wheel, one that keeps the last simulates 75 mm, and both hash the same bytes. - An identifier in an envelope is a nonempty string of printable characters: no code point below 32, and not 127. An identifier therefore survives a round trip through a shell variable.
- Integers above 2⁵³ and exact decimals are strings (§32.8, §14.4), so no value depends on a float parser.
- The refusal is issued by the CLI and by the MCP server before a job is planned or a budget is charged (refusals: duplicate member name after escape decoding; identifier not printable).
The writer. Canonical bytes are produced by this project's writer from the typed term, with keys sorted by code point explicitly. No canonical byte is produced by serializing a library map or a library number.
Why the writer may not lean on the library. FACT, read 2026-11-21:
- The
preserve_orderfeature ofserde_jsonswitches its maps from sorted to insertion order, and Cargo unifies features across a build graph.frankensqlite/Cargo.tomlrecords that the feature "leaked into every downstream consumer via feature unification, silently switching serde_json maps to insertion order across their whole build", and removed it from its workspace for that reason. frankenscipy/Cargo.toml:59enablespreserve_orderandfloat_roundtrip. FrankenSim's bedrock depends on FrankenSciPy (fs-laonfsci-linalg,fs-mathonfsci-special), andfrankensim/Cargo.lockresolvesserde_json1.0.154 withindexmapamong its dependencies, which onlypreserve_orderadds.fastmcp_rust/Cargo.toml:54enablesarbitrary_precision, which changes how numbers are represented.franken_textiles/Cargo.tomlrecords that withoutfloat_roundtripa decimal may be read one unit in the last place off, which "flipped point-in-polygon verdicts" in its fixtures.
The feature set of the JSON library in a frob binary is therefore decided by whichever sibling is linked, and not
by this workspace. frob-mcp is a member of the core graph (§32.12.2), so fastmcp_rust's arbitrary_precision is
in the unified set of every binary that links it. Smallest case: {"b": 1, "a": 2} re-serialized through a library
map is {"a":2,"b":1} in one build and {"b":1,"a":2} in another, and a digest over those bytes changes when an
unrelated crate enters the graph.
The guard. xtask check-deps prints, for every binary, the resolved serde_json version and its unified
feature set, and fails when either differs from the stack lock. A conformance binary is built four ways, with and
without a dummy dependency that enables preserve_order and one that enables arbitrary_precision, and must
produce identical canonical bytes and digests on the golden corpus. Owner: frob-core (reader and writer),
frob-verbs (admission order), xtask.
| GATE-WS-05 | Known answer. A golden corpus of 10³ artifacts, including duplicates that differ only by escapes at depths 1 to 8, integers at 2⁵³ ± 1, non-printable identifiers, and decimals whose nearest double differs between parsers: every duplicate and every bad identifier is refused on both surfaces before a job identifier exists; canonical digests are identical across the four feature combinations; the mutant writer that serializes a library map fails under preserve_order. M0. |