Cookpit v3.2 Schema — How It Works
Subject: A component-by-component architectural walkthrough of the cookpit v3.2 system, explaining how each file in the schema, bundle, scripts, tests, and docs collaborates across the four-stage lifecycle (generate → validate → attest → consume). Audience: Engineers, schema designers, validator implementers, Chef-app builders, and reviewers who need to understand what each file does, why it is necessary, what it depends on, and what it produces. Scope: Architecture only. The recipe corpus is deliberately ignored.
1. The Big Picture
Cookpit v3.2 is not a single file format — it is a four-stage pipeline with strict separation of concerns. A source recipe (typically a PDF or text web page) is converted into a deterministic, source-faithful, audit-grade JSON-LD plan, then validated, then cryptographically attested, then consumed by a runtime cooking application.
┌─────────────────────────────────────────────────────────────────────┐
│ COOKPIT v3.2 LIFECYCLE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Source recipe (PDF / text) │
│ │ │
│ ▼ │
│ ┌──────────────┐ Stage 1: Generation │
│ │ AI Chef │ Inputs: prompt + rules + lexicon + schema │
│ │ LLM │ + canonical-id + canonical-fingerprint │
│ └──────────────┘ Output: <slug>.v3.2.cpt.U.jsonld │
│ │ │
│ ▼ │
│ ┌──────────────┐ Stage 2: Validation │
│ │ Validator │ Inputs: U file + validation.md spec │
│ │ (script .py) │ + schema.json + canonical profiles + source │
│ └──────────────┘ Output: pass/fail verdict + per-criterion log │
│ │ │
│ hard-pass │
│ ▼ │
│ ┌──────────────┐ Stage 3: Attestation │
│ │ Validator │ Inputs: U file + signing key │
│ │ (signing) │ Output: <slug>.v3.2.cpt.A.jsonld │
│ └──────────────┘ (file fingerprint + Ed25519 signature) │
│ │ │
│ ▼ │
│ ┌──────────────┐ Stage 4: Consumption │
│ │ Chef app │ Inputs: A file + trusted public key │
│ │ (consumer) │ Output: live cooking experience │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
The files in the repository fall into five layers that map onto this pipeline:
| Layer | Files | Role |
|---|---|---|
| Schema (contract) | schema/cookpit-cooking-file-v3.2.json, docs/schema-v3.2.md | Defines the shape every file must satisfy. |
| Authoring bundle (stage 1 inputs) | bundle/v3.2/{README, prompt, rules, lexicon, glossary}.md | Tells the AI Chef how to generate a file. |
| Canonical profiles (deterministic algorithms) | bundle/v3.2/canonical-{id-derivation, fingerprint-normalisation, units, patterns}.md, source-content-handling.md | Pin the algorithms that must produce identical output across implementations. |
| Validation (stage 2/3 enforcement) | bundle/v3.2/validation.md, scripts/validate_cookpit_v3.2.py, scripts/lib/source_tokeniser.py, tests/test_source_tokeniser.py | Specifies and executes the gate; signs files that pass. |
| Consumer (stage 4 spec) | docs/chef-app-spec.md | Describes how a Chef app should turn a signed file into a live cooking session. |
The remainder of this document walks through each layer in turn, explains what every file does and why it is necessary, then traces a single recipe end-to-end through the lifecycle.
2. The Schema Layer — The Contract
schema/cookpit-cooking-file-v3.2.json
Purpose. A JSON Schema (Draft 2020-12) document that defines the executable structural contract for every v3.2 cooking file. Every file in the corpus must validate against it.
What it contains. Definitions for the top-level Recipe shape, the cookpit block extension, the three phaseBlock types (prepCook, preCook, liveCook), the task and process shapes, the lane-second if/then rules, the timingBasis enum, the quantitativeFingerprint shape, the generation metadata block, and the attestation block (oneOf between unauthenticated and authenticated forms).
Who reads it. The AI Chef (as response-shape constraint during generation), the validator (as the V-SCHEMA hard criterion), and any third-party tooling that wants generic JSON-Schema validation.
Why it is necessary. Without it, every consumer would have to re-derive the file shape from prose. With it, any standard JSON-Schema validator can perform a first-pass shape check; structural mismatches are caught before any cookpit-specific logic runs.
What it does not do. It enforces only the structural contract (types, enums, required fields, if/then rules). Cross-reference closure (every ingredientRef must resolve), determinism of IDs, source-faithfulness of fingerprints, and lifecycle invariants are not expressible in JSON Schema and therefore live in the validator and bundle rules instead.
docs/schema-v3.2.md
Purpose. A long-form, human-readable companion to the JSON Schema that explains why the schema looks the way it does. It introduces the three central principles (Optimal, Closed, Static), the four lifecycle stages, the three-phase model, the lane model, the orchestration semantics, and walks each field with design rationale.
Who reads it. New developers, documentarians, reviewers, and anyone who wants to understand the narrative behind the schema rather than just its grammar.
Why it is necessary. A JSON Schema document is a grammar; it does not explain choices. schema-v3.2.md is where decisions like "why three phases?", "why fixed lanes per course?", "why two fingerprints?" are reasoned about so that downstream consumers and future schema authors can extend the format coherently.
3. The Authoring Bundle — Inputs to the AI Chef
The bundle is the set of documents the AI Chef reads during stage 1. It is portable: any LLM that can follow markdown system messages and emit JSON can be paired with this bundle to produce v3.2 output.
bundle/v3.2/README.md
Purpose. A directory manifest and entry point. It introduces the persona, lists every bundle file with its role, summarises the four-stage lifecycle, and articulates the three central principles (Optimal, Closed, Static).
Who reads it. Human authors and the LLM at the start of any generation task. It is the orientation document.
Why it is necessary. Without it, the bundle is a folder of nine markdown files with no apparent reading order. The README's role table and "how they relate" section give a coherent first read.
bundle/v3.2/prompt.md
Purpose. The system message used to drive the AI Chef. It defines the rebel-chef-detective persona, the AI's role in the four-stage lifecycle (specifically, that it produces stage-1 unauthenticated output only), the Phase 0 decomposition decision tree (which phase a piece of work belongs to), the Phase 1 resource-selection method, the Phase 2 deductive working order, the timingBasis.basis enum with worked examples, the style-and-tone guidance, the explicit "what never appears in the file" negative space, and the output-format pinning to a single JSON object.
Who reads it. The LLM, as the system message at generation time.
Works with. lexicon.md (paired voice input), rules.md (referenced for normative rules), schema/cookpit-cooking-file-v3.2.json (response shape), canonical-id-derivation.md (Phase 2 ID generation), canonical-fingerprint-normalisation.md (Phase 2 fingerprint computation).
Why it is necessary. It is the only document that tells the LLM how to think about a recipe: where the work is, when each step happens, which voice to use, what to never invent. Without it, the LLM is given a schema and no method.
bundle/v3.2/rules.md
Purpose. Nineteen normatively-numbered rule sections (A through R) that govern every aspect of a v3.2 file: the lifecycle (§A0), the three principles (§A1–A3), file identity (§B), timing and phases (§C), the lane model (§D), global alarms (§E), prep and phase composition (§F), deterministic IDs (§G), resource closure (§H), tasks (§I), processes (§J), the source fingerprint (§K), forbidden runtime fields (§L), generation metadata (§M), optional fields (§N), filename (§O), lexicon and persona (§P), phase blocks (§Q), and attestation (§R).
Who reads it. The LLM (as a self-check before emitting), the validator (every hard validation criterion maps to a rule by number), human reviewers and QA.
Works with. Almost every other file in the bundle. It is the spine that the rest hang off. validation.md references rule numbers; prompt.md references rule sections by name; the canonical profile documents are pointed to from §G3 (IDs) and §K3–K5 (fingerprint).
Why it is necessary. It is the contract. The schema enforces shape; rules.md enforces semantics. Without it, "what counts as a valid cookpit file" beyond mere JSON-Schema compliance is undefined.
bundle/v3.2/lexicon.md
Purpose. The chef-language and voice guide. It defines the rebel-chef persona by negative space (not Jamie, not Mary Berry, not brigade, not blogger), specifies the imperative-fragment register, the heat-level mapping (gas marks, °C, stovetop levels), the time-language constraints (exact only — no "for a few minutes"), the sensory-cue vocabulary across visual / aural / tactile / olfactory modalities, the forbidden tokens (hedgers, warmth, filler), the explicitly-allowed informalisms ("low and slow", "off heat", "tent it"), and a 50-row translation table that anchors the rebel voice between brigade and recipe-blog.
Who reads it. The LLM, as paired input alongside prompt.md and rules.md.
Works with. prompt.md (the persona is referenced from there), rules.md §P (which makes the lexicon normative), and downstream validation.md (V-LEX-* soft criteria).
Why it is necessary. Without the lexicon, action text drifts toward generic recipe-blog warmth or sterile robot-prose. The lexicon is what makes a v3.2 file sound like a chef rather than like an ML model.
bundle/v3.2/glossary.md
Purpose. A field-by-field reference for every field in the v3.2 schema. It is structured as a comprehensive index that points each field to its canonical authority — rules.md for normative behaviour, canonical-*.md for algorithms, schema-v3.2.md for design rationale.
Who reads it. Developers building tooling, reviewers checking field semantics, schema authors evolving v3.3.
Why it is necessary. The information about each field exists scattered across the schema, the rules, and the canonical profiles. The glossary collapses that into one alphabetised index so that a reader who needs to know "what does cookpit.attestation.audit mean?" has a single place to look first.
4. Canonical Profiles — Deterministic Algorithms
The canonical-* documents are the bundle's executable specifications. They define algorithms that must produce byte-identical output across any conformant implementation.
bundle/v3.2/canonical-id-derivation.md
Purpose. Specifies the canonical generation profile cookpit-ai-canonical-v3.2: every entity ID in a v3.2 file is derived as <typePrefix> + first-10-hex(SHA-256("v3.2|<entityType>|<canonicalContent>|<canonicalPosition>")). The document defines per-entity-type rules for what canonicalContent and canonicalPosition mean (file, ingredient, equipment, utensil, sundry, prereq, hotspot, process, task, prepCook, preCook, liveCook), the type-prefix table (f / i / e / u / s / q / p / t / h), the Unicode normalisation rules (NFC, diacritics preserved), and a self-test vector set so independent implementations can prove conformance.
Works with. rules.md §G3 (which makes the profile normative), the LLM at stage 1, the validator at stage 2 (V-IDS-DETERMINISTIC re-derives every ID and compares).
Why it is necessary. Determinism is what makes the closed-world resource graph trustworthy. If two implementations produced different IDs for the same recipe, cross-references would break, deduplication would fail, caching would invalidate. The profile turns ID generation into a verifiable computation rather than a convention.
bundle/v3.2/canonical-fingerprint-normalisation.md
Purpose. Specifies the canonical profile cookpit-active-number-sequence-v3.2.0 for computing the source-faithfulness fingerprint. It defines a six-stage pipeline:
- Stage A — Extraction: PDF/text → UTF-8 with ligature expansion, curly-quote folding, soft-hyphen stripping, whitespace normalisation, diacritic preservation.
- Stage B — Segmentation: identify header / ingredients / method / tips blocks.
- Stage C — Filtering: remove sponsored content, paywall chrome, step markers, header noise (using
source-content-handling.mdcategories). - Stage D — Tokenisation: apply eight numeric patterns + Unicode-fraction map + cooking-context heuristics to extract every active number.
- Stage E — Rendering: dash-join tokens into a deterministic sequence string.
- Stage F — Hashing: SHA-256 the sequence; store the digest.
The document includes a worked example (spaghetti carbonara, 17 tokens) and a nine-source-PDF tokeniser self-test corpus.
Works with. rules.md §K3–K5, source-content-handling.md (Stage C uses its categories), scripts/lib/source_tokeniser.py (the executable embodiment), tests/test_source_tokeniser.py (the conformance gate), and the validator's V-FINGERPRINT-A (shape) and V-FINGERPRINT-B (re-extraction) criteria.
Why it is necessary. The fingerprint is the format's defence against numerical hallucination. If the LLM invents a temperature, a quantity, or a duration absent from the source, the fingerprint computed from the source will not match the fingerprint stored in the file, and V-FINGERPRINT-B will fail. This document is what makes that check independently reproducible.
bundle/v3.2/canonical-units.md
Purpose. Defines the seven canonical unit classes — metric mass (g, kg, mg), metric volume (ml, cl, l), UK measure (tbsp, tsp, dsp), imperial mass (oz, lb), imperial volume (fl oz, pint, cup), count/structural (count, clove, sprig, bunch, slice, head, pod, stick, leaf, pinch, dash, knob, handful, cm, inch), and semantic (toTaste, toServe, asNeeded, forGreasing). Each entry has a canonical token; mixing across classes is permitted but must use canonical tokens only.
Works with. glossary.md §8 (referenced for ingredient-unit definition), chef-app-spec.md (shopping lists, scaling), the LLM during ingredient generation.
Why it is necessary. Without a canonical vocabulary, "tbsp" and "tablespoon" and "Tbsp" and "TBSP" would all appear, and tooling could not reliably parse units for shopping lists, dietary calculations, or scaling arithmetic. The document collapses the chaos to a single allowed spelling per concept.
bundle/v3.2/canonical-patterns.md
Purpose. A walk-confirmed catalogue of structural patterns that recur across the corpus — six concurrency patterns (parallel workstreams, intra-minute clusters, cross-lane processes, shared-boundary chains, serial-vessel chains, fully-concurrent passive), the lane-model dual reading (parallel vs tight-sequence), the leadTime vocabulary (P1D overnight, PT8H multi-hour, PT15M oven preheat), process-label phase qualifiers, detective-inserted check tasks for 6-hour-plus cooks, filename slug conventions, and phase-composition patterns (liveCook-only, preCook+liveCook, prepCook+liveCook, full three-phase).
Works with. rules.md §J, §D, §N4, §Q, §O; prompt.md (Phase 0 decomposition); chef-app-spec.md (which displays these patterns at runtime).
Why it is necessary. Patterns are the implementation playbook. Without them, the AI must re-derive the same structural decisions for every recipe and the Chef app has no canonical reference for interpreting concurrency. The patterns are a shared vocabulary that keeps the corpus internally consistent.
bundle/v3.2/source-content-handling.md
Purpose. Categorises source content into five kinds — sponsored content, paywall chrome, culinary explanation, structurally-actionable tip, source typo — and specifies how each is handled in both the file body (recipeInstructions[], tasks[].action, prereq notes) and the source fingerprint (Stage C filtering).
Works with. canonical-fingerprint-normalisation.md (Stage C filtering uses these categories); prompt.md and rules.md (which point to it for filtering decisions); scripts/lib/source_tokeniser.py (which implements the filtering).
Why it is necessary. Real-world source recipes carry significant non-recipe content — adverts, paywall banners, chef commentary, step markers, occasional typos. Without an explicit categorisation, two implementations would filter inconsistently and their fingerprints would diverge. This document is the rosetta stone between messy source content and the canonical fingerprint sequence.
5. The Validation Layer — Stage 2 and Stage 3 Enforcement
bundle/v3.2/validation.md
Purpose. The validator's executable specification. It enumerates ~46 criteria — roughly 26 hard (must pass for the file to advance to Stage 3) and ~20 soft (advisory, surfaced in the report). Each criterion has an ID (V-PARSE, V-SCHEMA, V-LIFECYCLE-AI-EMITS-U, V-IDS-DETERMINISTIC, V-REFS-CLOSED, V-FINGERPRINT-A, V-FINGERPRINT-B, V-FILE-FINGERPRINT, V-SIGNATURE, etc.), a severity (hard/soft), a check description, and a back-reference to the rule it enforces.
Who reads it. The validator implementer, the LLM (knows what will be checked), reviewers triaging validator output.
Works with. rules.md (every criterion references a rule), schema/cookpit-cooking-file-v3.2.json (V-SCHEMA), canonical-id-derivation.md (V-IDS-DETERMINISTIC), canonical-fingerprint-normalisation.md (V-FINGERPRINT-B), scripts/validate_cookpit_v3.2.py (the implementation).
Why it is necessary. Without a normative validation specification, the validator and the AI would drift apart. validation.md keeps them in lockstep: the LLM knows what to satisfy; the validator knows what to check; the rules document says why.
scripts/validate_cookpit_v3.2.py
Purpose. The executable validator. It implements every criterion from validation.md as a Python function. It also performs the Stage-3 cryptographic attestation: on hard-pass, it canonicalises the file body with the signature and fileFingerprint fields cleared, computes the SHA-256 file fingerprint, signs the canonical bytes with an Ed25519 private key, embeds the authenticated attestation block, renames the file from .U.jsonld to .A.jsonld, and writes it.
CLI surface. --validate-only (dry-run, no signing), --verify (Stage-4 consumer-style verification of an existing .A.jsonld), --source <pdf|text> (input for V-FINGERPRINT-B), --key, --gen-key, --in-place.
Works with. Every canonical profile and every rule in the bundle (transitively); scripts/lib/source_tokeniser.py (V-FINGERPRINT-B); the file system (input U file, output A file).
Why it is necessary. It is the single point at which the format's correctness is enforced. Without it, all rules in the bundle are advisory.
scripts/lib/source_tokeniser.py
Purpose. The executable embodiment of canonical-fingerprint-normalisation.md. It runs the full six-stage pipeline (extraction → segmentation → filtering → tokenisation → rendering → hashing) and produces both the rendered active-number sequence and its SHA-256 digest.
Who calls it. scripts/validate_cookpit_v3.2.py from V-FINGERPRINT-B; the test suite; any tool that needs to compute a source fingerprint.
Why it is necessary. Without it, V-FINGERPRINT-B is unimplementable and source-faithfulness is unverifiable. The tokeniser is what turns the prose specification into a deterministic computation.
tests/test_source_tokeniser.py
Purpose. Unit tests organised stage-by-stage (TestStageA ligatures and quotes, TestStageB segmentation, TestStageC filtering, TestStageD tokenisation patterns and Unicode fractions, TestStageE rendering, TestStageF hashing) plus a conformance gate that runs the §9 worked example (carbonara) and the §11 tokeniser self-test corpus of source PDFs, checking SHA-256 equality byte-for-byte.
Why it is necessary. Without the tests, regressions in the tokeniser would silently change every fingerprint in the corpus. The carbonara conformance gate is the canary that catches this.
6. The Consumer Layer — Stage 4 Specification
docs/chef-app-spec.md
Purpose. Defines the runtime experience that a Chef app must deliver when consuming a .A.jsonld file. It specifies screen layout (top third identity and timer; bottom two-thirds prerequisites then live banners), action banners with checkboxes, pending tasks as stacked black banners, the colour-state machine (black pending, blue outstanding, navy complete, orange overdue, red urgent), the runtime time-management contract (the app owns the timer, urgency, progress, and pending state — the file is static), and the explicit separation of concerns between the cookpit JSON-LD file and the dynamic app state.
Who reads it. Chef-app developers, UX designers, and v3.2 schema authors who want to know which runtime behaviours the schema must support and which it deliberately delegates.
Why it is necessary. A static file format alone does not deliver a real-time cooking experience; an app does. chef-app-spec.md is the contract between the format (what the file guarantees) and the runtime (what the app must add). Without it, "what should an app do with a v3.2 file" is undefined and every implementation diverges.
7. End-to-End Walkthrough: One Recipe Through Four Stages
A worked trace of how the pieces collaborate on a single recipe.
Stage 1 — Generation
- Operator hands the LLM the bundle (
prompt.mdas system message, plusrules.md,lexicon.md, the canonical profiles, the schema, and the source recipe). - LLM reads
prompt.mdfor persona and method. - Phase 0 (decomposition): classifies each piece of work into prepCook / preCook / liveCook per the
prompt.mddecision tree, cross-checked againstcanonical-patterns.md§8 phase-composition patterns. - Phase 1 (resources): declares ingredients, equipment, utensils, sundries, skills, hotspots — using
canonical-units.mdfor unit selection andrules.md§H for closure. - Phase 2 (deduction): assigns tasks to lanes per
canonical-patterns.md§1–2; chooses atimingBasis.basisperprompt.mdworked examples andrules.md§I8; generates IDs percanonical-id-derivation.md; computes the source fingerprint percanonical-fingerprint-normalisation.mdandsource-content-handling.md. - LLM emits a single JSON object with
cookpit.attestation.status: "unauthenticated"and writes it as<slug>.v3.2.cpt.U.jsonld.
Stage 2 — Validation
- Operator runs
scripts/validate_cookpit_v3.2.py <slug>.v3.2.cpt.U.jsonld --source <slug>.pdf. - The validator parses the file (V-PARSE), validates against the schema (V-SCHEMA), inspects the attestation block (V-LIFECYCLE-AI-EMITS-U / V-ATTESTATION-CONSISTENCY), then runs all hard criteria — re-deriving every ID via
canonical-id-derivation.md(V-IDS-DETERMINISTIC), enforcing closed-world references (V-REFS-CLOSED), checking source coverage and source temperatures (V-SOURCE-COVERAGE / V-SOURCE-TEMPS), and re-extracting the source fingerprint viascripts/lib/source_tokeniser.py(V-FINGERPRINT-B). - Soft criteria (V-LEX-FORBIDDEN, V-LEX-IMPERATIVE, V-DURATION-B, etc.) are surfaced as warnings.
- The validator returns a verdict and a per-criterion report. On any hard failure, the file does not advance.
Stage 3 — Attestation
- On hard-pass, the validator clears
cookpit.attestation.signatureandcookpit.attestation.fileFingerprint. - Canonicalises the JSON body (deterministic key ordering, no insignificant whitespace).
- Computes
SHA-256(canonical bytes)→fileFingerprint(V-FILE-FINGERPRINT). - Signs the same canonical bytes with the validator's Ed25519 private key (V-SIGNATURE).
- Replaces the attestation block with the authenticated form (
status: "authenticated",issuer,validatorVersion,issuedAt,keyId,fileFingerprint,signature,audit). - Verifies the signature against its own public key as a self-check.
- Renames the file to
<slug>.v3.2.cpt.A.jsonldand writes it.
Stage 4 — Consumption
- Chef app loads
<slug>.v3.2.cpt.A.jsonld. - Parses the attestation block; refuses to proceed unless
status === "authenticated". - Confirms
issueragainst a pinned trusted validator URL. - Resolves
keyIdto a trusted public key. - Re-canonicalises the body with
signaturecleared, recomputes SHA-256, verifies it matchesfileFingerprint. - Verifies the signature over the canonical bytes against the public key.
- (Optionally) checks revocation list and minimum
validatorVersion. - On success, loads the cooking plan into the runtime per
chef-app-spec.md— confirms prerequisites, starts the live timer, posts banners, manages pending state, colour-codes overruns. The file itself is never modified.
8. Cross-Reference Graph (condensed)
schema/cookpit-cooking-file-v3.2.json
▲
│ structural shape
│
prompt.md ─────► rules.md ◄───┴──── validation.md ────► validate_cookpit_v3.2.py
│ │ │ │
│ │ ▼ │
├────► lexicon.md schema-v3.2.md │
│ │
├────► canonical-id-derivation.md ◄───────────────── (V-IDS-DETERMINISTIC)
│ │
├────► canonical-fingerprint-normalisation.md ◄──── (V-FINGERPRINT-B)
│ │ │
│ └────► scripts/lib/source_tokeniser.py ◄──────────┘
│ ▲
│ │
│ tests/test_source_tokeniser.py
│
├────► canonical-units.md ────────► glossary.md
├────► canonical-patterns.md ─────► glossary.md
└────► source-content-handling.md ─► canonical-fingerprint-normalisation.md (Stage C)
glossary.md ──── indexes every field across schema + bundle
README.md ────── orients readers to all of the above
chef-app-spec.md ──── stage-4 consumer contract
Three observations about this graph:
rules.mdis the spine. Every other normative file either references it or is referenced from it. Removing it leaves the bundle without a contract.- Canonical profiles are fan-in points.
canonical-id-derivation.mdandcanonical-fingerprint-normalisation.mdare each consumed by at least three other components (the prompt, the rules, the validator, and — for the fingerprint — the tokeniser library and tests). They are the load-bearing algorithms. - The schema is consumed but does not reach back out. It is the structural contract; everyone references it; it references no one. This is correct for a bottom-of-stack contract.
9. Why Each File is Necessary — Consequence of Removal
| File | What breaks if removed |
|---|---|
schema/cookpit-cooking-file-v3.2.json | All structural validation. Every consumer must re-derive the shape from prose. |
docs/schema-v3.2.md | Design rationale becomes inaccessible. Future schema authors lose continuity. |
bundle/v3.2/README.md | Bundle has no entry point or reading order. |
bundle/v3.2/prompt.md | The LLM has no method. Files become incoherent or refused. |
bundle/v3.2/rules.md | No semantic contract. validation.md becomes unanchored; every criterion loses its rule reference. |
bundle/v3.2/lexicon.md | Action text drifts to generic recipe-blog or robot-prose; persona is undefined. |
bundle/v3.2/glossary.md | Field documentation is scattered across nine documents. |
bundle/v3.2/validation.md | Validator has no specification; criteria become ad-hoc. |
bundle/v3.2/canonical-id-derivation.md | ID generation is non-deterministic; the closed-world graph cannot be verified. |
bundle/v3.2/canonical-fingerprint-normalisation.md | Source-faithfulness is unverifiable; V-FINGERPRINT-B cannot run. |
bundle/v3.2/canonical-units.md | Units become unvalidated; shopping/scaling tooling cannot rely on them. |
bundle/v3.2/canonical-patterns.md | AI re-derives structural decisions per recipe; consumers have no canonical reference for concurrency. |
bundle/v3.2/source-content-handling.md | Stage C filtering becomes inconsistent; fingerprints diverge between implementations. |
scripts/validate_cookpit_v3.2.py | No validation gate; no Stage-3 signing; the lifecycle stops at Stage 1. |
scripts/lib/source_tokeniser.py | V-FINGERPRINT-B is unimplementable. |
tests/test_source_tokeniser.py | Tokeniser regressions go unnoticed; the corpus's fingerprint conformance is unenforced. |
docs/chef-app-spec.md | Runtime behaviour is undefined; every Chef app diverges. |
10. Summary
Cookpit v3.2 is a deliberately layered architecture. The schema is a structural contract; the bundle is a composable set of authoring inputs; the canonical profiles are deterministic algorithms; the validator enforces and signs; the chef-app spec defines the runtime. Every file has a single, well-defined role; cross-references are explicit and traceable; the four-stage lifecycle ties the pieces together end-to-end.
The architectural strength is the separation between specification and implementation: every algorithm exists first as a markdown profile (testable by humans), then as code (testable by machines), and the validator's checks point back to the profile by reference rather than re-stating it. This is what allows third-party implementations to plausibly conform — the contract is inspectable independent of the reference code.
A reader who has worked through this document should now be able to look at any v3.2 file, identify which lifecycle stage produced it, name which bundle file specifies each of its sections, and trace which validation criterion would catch any given malformation.