FrankenRobotics

Workspace, crates, formats

6,855 words14 subsections8 tables1 listingPlan version 1.1

On this page14
34.1 Repository layout34.2 Crate map34.3 Layer and dependency rules34.4 Unsafe code34.5 Contracts34.6 The six checks34.7 Working rules inherited from the machine and the suite34.8 What ships with the first commit34.9 The format registry34.10 The rule for creating a new crate34.11 The independent auditor34.12 Suite conventions this project adopts34.13 Invariants, gates and open questions34.14 The canonical reader and writer, and JSON features that unify across the build

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-layers fails 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] layer in frankensim/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-fsim names types from FrankenSim's volatile crates. The bedrock-direct list is the only exception, and fs-qty is named only through frob_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 std and Franken foundations. serde and serde_json at 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 except bindings/frob-gymnasium.
  • L-6 No bare f64 physical quantity in a public signature above layer 1. Quantities are frob_core::qty types 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-generated regenerates and compares.
  • L-9 frob-cert has an empty dependency table, and only frob-verbs, frob-cli and frob-conformance may 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 in frob-core, implemented in frob-chronicle); the job context for cancellation and budgets (defined in frob-core, supplied by the daemon); and the certificate sink (defined in frob-core, implemented in frob-lemma). This is what lets a layer-5 crate such as frob-autopsy fork 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-model is a pure cache keyed by identity with a fixed bound, not a policy; the memo graph for results sits in front of verb executors in frob-verbs, with its bytes in frob-chronicle.
  • L-12 Features that select a tier of ambition are named and off by default: frontier-* and moonshot-* 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.
  • ubs runs on changed files before a commit. Formatting, lints and tests run before a commit. Beads are managed with br and triaged with bv --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-stack runs. 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):

  1. 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-cert reads 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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-foundry is the plain case: the structure group 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-derive is another: FrankenSymPy, which no runtime crate may link.
  • A distinct device target: the code compiles for a different processor, runtime or host. The two spark annexes, frob-tui and bindings/frob-gymnasium are of this kind.
  • A proof boundary: the code states or checks something whose trust must not depend on the code around it. frob-cert is the plain case. frob-spec is one because certificates and qualification verdicts quantify over its sentences. frob-phylum is one because the statement "a world's trajectory does not depend on the batch it ran in" is tested at its boundary. frob-nemesis is one because the discovery lane may not read confirmation worlds (§24), and a crate boundary lets check-deps enforce 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:

  1. crates/frob-cert/Cargo.toml has an empty [dependencies] table: no frob-* crate, no FrankenSim crate (so no fs-qty and no nightly feature), no asupersync, no serde. It inherits nothing from the workspace manifest.
  2. It carries its own toolchain file naming a stable release. A copy of the directory alone builds with cargo build --release on that compiler. This also frees the auditor from the risk of §33.12.
  3. 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.
  4. 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.
  5. No crate that produces a claim or a certificate depends on it. Only frob-verbs (to expose the check as a verb), frob-cli and frob-conformance may (rule L-9). The bundle writer lives in frob-lemma and is written against the schema, sharing no code with the reader.
  6. A FrankenSymPy-based re-check of the same bundles runs in frob-conformance as 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_id that resolves to the evidence_ids of the records supporting it, the policy_id of the rule and thresholds in force, and the trace_id of the run. FACT: franken-kernel 0.6.0 defines TraceId, DecisionId, PolicyId and SchemaVersion and has no claim or evidence identifier (asupersync/franken_kernel/src/lib.rs). DESIGN: frob-core mirrors the text form of the three it has, adds ClaimId and EvidenceId in the same form, and adds them upstream (FD-FKER-01). Rows of registries/gates.toml carry their claim_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 inside check-contracts.
  • A demo file linked to claims for every release path. demos/<demo_id>/demo.yaml lists the demo_id, the claim_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-cert has 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-* or moonshot-* feature (check-deps).
  • INV-WS-05 xtask has 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.

  1. 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.
  2. 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.
  3. Integers above 2⁵³ and exact decimals are strings (§32.8, §14.4), so no value depends on a float parser.
  4. 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_order feature of serde_json switches its maps from sorted to insertion order, and Cargo unifies features across a build graph. frankensqlite/Cargo.toml records 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:59 enables preserve_order and float_roundtrip. FrankenSim's bedrock depends on FrankenSciPy (fs-la on fsci-linalg, fs-math on fsci-special), and frankensim/Cargo.lock resolves serde_json 1.0.154 with indexmap among its dependencies, which only preserve_order adds.
  • fastmcp_rust/Cargo.toml:54 enables arbitrary_precision, which changes how numbers are represented.
  • franken_textiles/Cargo.toml records that without float_roundtrip a 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.