BUILD
BUILD
SERVICE CONTRACT · VIEW: GOV
Axiom
Build is governed DAG traversal. Phases are nodes. Dependencies are edges. Parallelism is discovered, not hardcoded. GOV is the only hardcoded path.
Constraints
MUST: Hardcode only CANONIC_GOV — discover repos, fleet, scopes, phases, DAG edges MUST: Gate GOV boundary at compile time — build FAILS if runtime files exist in GOV MUST: Gate .gitignore at compile time — build FAILS if GOV .gitignore is missing required patterns MUST: Discover phases via glob (build_phases/[0-9][0-9]*-*) MUST: Discover DAG edges from PIPELINE.toml (GOV-governed, not hardcoded in orchestrator code) MUST: Use GovGraph (galaxy BFS) for all cross-scope INTEL and LEARNING discovery MUST: Register all build tools in PIPELINE.toml with reads/writes/depends declarations MUST: Carry _generated marker on .md files written back to GOV (CLAUDE.md, books, scaffolds) MUST: Auto-scaffold missing closure artifacts (INTEL, LEARNING, COVERAGE, ROADMAP, VOCAB, README) from CANON.md MUST: Scaffold before attest — 255 compliance is the default, not the goal MUST: Never overwrite hand-authored files — only scaffold when missing or _generated MUST NOT: Require _generated marker on .json — the extension itself declares runtime MUST: Preserve BUILD_ENV audit trail (LEDGER/build/) MUST: Fail fast if PIPELINE.toml is missing or drifted from discovered phases MUST: Use DAG-parallel runner as sole entry point — no sequential fallback MUST NOT: Use inherits-chain-only INTEL discovery (deleted, replaced by graph BFS) MUST NOT: Maintain fallback paths for missing galaxy.json (fail fast) MUST NOT: Hardcode scope paths, fleet paths, repo paths, or phase paths MUST NOT: Write runtime artifacts (.json, .css, .js, .pyc, .pptx, caches) into GOV tree MUST NOT: Write GOV source (.md contracts) into runtime except via _generated compile outputs MUST NOT: Rely on .gitignore as primary boundary defense — compiler gate is primary, .gitignore is governed secondary
COVERAGE:
SPEC
Pipeline
| Phase | Name | Dependencies | Purpose |
|---|---|---|---|
| 00 | toolchain | — | Compile GOV contracts to TOOLCHAIN JSON |
| 01 | galaxy | 00 | Build galaxy.json (graph topology) |
| 02 | services | 00 | Service attestation |
| 03 | surfaces | 00 | Compile GOV → Jekyll surfaces (ProcessPoolExecutor) |
| 04 | figures | 03 | Compile figure specs |
| 05 | shop | 03 | Compile SHOP products + Jekyll excludes |
| 06 | validate-content | 00 | INTEL wiring, VOCAB normalization, hygiene |
| 07 | structure | 00 | GOV boundary gate + fleet structure |
| 08 | learning | 00 | LEDGER sync, learning ingest, STAR timeline |
| 08a | claude | 01 | Compile CLAUDE.md via galaxy BFS |
| 09 | econ | 00 | Stripe sync, VAULT publish, COIN wiring |
| 10 | federation | 09 | Digest, witness, threshold |
| 11 | validate | 03,04,05,06,07,10 | Frontend validate, design gate, 255 gate |
Boundary
~/CANONIC/ = GOV pure .md contracts, human-readable
~/.canonic/ = RUNTIME compiled .json, scripts, caches, fleet sites
Optimizations
| Feature | Mechanism | Location |
|---|---|---|
| DAG parallelism | Kahn’s topological sort + ProcessPoolExecutor | build-dag |
| Scope parallelism | ProcessPoolExecutor per scope | build-surfaces |
| Fleet parallelism | Parallel subprocesses per fleet site | 03-surfaces |
| Catalog parallelism | ThreadPoolExecutor (7 emitters) | build-surfaces |
| Galaxy enrichment | ThreadPoolExecutor per node | build-galaxy-json |
| Graph-native discovery | GovGraph BFS (gov_graph.py) | all compilers |
| Inheritance cache | functools.lru_cache (mtime-keyed) | magic_lib.py |
| Incremental galaxy | SHA-256 mtime hash-skip | build-galaxy-json |
| Incremental scopes | Per-scope mtime cache | build-surfaces |
| Wallet parallelism | ThreadPoolExecutor (user×site) | 09-econ |
INTEL
Compiler Architecture
| Component | Location | Purpose |
|---|---|---|
| DAG orchestrator | ~/.canonic/bin/build | Kahn’s sort + ProcessPoolExecutor |
| Pipeline manifest | ~/.canonic/PIPELINE.toml | 17 phases, reads/writes/depends declarations |
| Galaxy compiler | ~/.canonic/bin/build-galaxy-json | GOV tree → galaxy.json (755 nodes) |
| Surface compiler | ~/.canonic/bin/build-surfaces | CANON.md → CANON.json + index.md per scope |
| CLAUDE compiler | ~/.canonic/bin/compile-claude-md | BFS from galaxy → CLAUDE.md |
| Graph kernel | ~/.canonic/bin/gov_graph.py | GovGraph class, BFS, budget-controlled extraction |
| Shared discovery | ~/.canonic/bin/magic_lib.py | discover_all(), load_gov_repos(), parse_axiom() |
| Intake promote | ~/.canonic/bin/intake-promote | Ad hoc memory → governed LEARNING |
Phase Inventory (17 phases)
| Phase | Name | Layer | Purpose |
|---|---|---|---|
| 00 | toolchain | L0 | GOV contracts → TOOLCHAIN JSON |
| 01 | galaxy | L0 | GOV tree → galaxy.json |
| 02 | galaxy-enrich | L1 | Backfill COIN, TALK, LEARNING, SCORE |
| 03 | services | L0 | GOV completeness attestation |
| 04 | surfaces | L1 | CANON.md → CANON.json + index.md |
| 05 | figures | L2 | Figures → _data/*.json + deck exports |
| 06 | shop | L2 | SHOP.md → SHOP.json |
| 07 | validate | L2 | INTEL, VOCAB, hygiene, compliance gates |
| 08 | structure | L0 | CNAME, .gitignore generation |
| 09 | learning | L0 | Ledger sync + intake promote |
| 10 | claude | L1 | BFS compile CLAUDE.md |
| 11 | econ | L0 | Stripe sync + wallet publish |
| 12 | close | L1 | VAULT close |
| 13 | merkle | L2 | Merkle root of ledger |
| 14 | federation | L2 | Federation state publish |
| 15 | validate | L3 | Final gate (bits=255, coverage, schema) |
| 16 | timeline | L0 | Contacts + timeline surfaces |
Validation Gates
| Gate | Phase | Blocking |
|---|---|---|
| GOV boundary (runtime files in GOV) | 08-structure | YES |
| .gitignore governance | 08-structure | YES |
| INTEL wiring | 07-validate | YES |
| VOCAB normalization | 07-validate | YES |
| Compliance scan (banned patterns) | 07-validate | YES |
| Fleet bits=255 | 15-validate | YES |
| Galaxy schema | 15-validate | YES |
| Coverage gates | 15-validate | NO (tracked, non-blocking) |
Caching
| Mechanism | Scope | Invalidation |
|---|---|---|
| .build-cache.json | Per-scope mtime tracking | Source file change or toolchain hash change |
| Galaxy mtime hash | All CANON.md mtimes | Any CANON.md modification |
| CLAUDE source hash | SHA-256 of all inputs | Any input file change |
Deploy Chain
| Stage | Location | Purpose |
|---|---|---|
| Source | hadleylab-canonic | Governed content |
| Bare | ~/Canonic.repos/hadleylab-canonic | Intermediate (bare repo) |
| Deploy | ~/.canonic/hadleylab-canonic.github.io | GitHub Pages (serves hadleylab.org) |
_data/anddecks/are gitignored in source (generated by build)- Builds take 8-12 minutes
- Cloudflare lowercases URLs; GitHub Pages serves case-insensitively
Known Gotchas
- ThreadPoolExecutor is correct for galaxy enrichment (I/O-bound, not CPU-bound)
- Blog/paper format oscillation traced to freshness cache skipping compiled.add() and stale cleanup
- BFS non-determinism traced to unsorted neighbor iteration (fixed: sorted())
- SKIP_INCREMENTAL=1 forces full galaxy rebuild
- Runtime (~/.canonic/bin/) is not versioned in GitHub (RUNTIME_GOVERNED gap)
LEARNING
ROADMAP
Now
- [x] DAG-parallel phase orchestrator (build-dag)
- [x] ProcessPoolExecutor scope compilation (build-surfaces)
- [x] Parallel fleet site compilation (03-surfaces)
- [x] Parallel catalog emitters (7 concurrent)
- [x] Parallel galaxy enrichment (ThreadPoolExecutor)
- [x] Inheritance chain caching (lru_cache)
- [x] Incremental galaxy (mtime hash-skip)
- [x] Parallel wallet publishing (09-econ)
- [x] Graph-native discovery kernel (gov_graph.py — shared GovGraph + BFS extractors)
- [x] PIPELINE.toml (GOV-governed pipeline manifest, replaces DAG.json)
- [x] Delete extract_intel_chain/extract_learning_chain (replaced by BFS)
- [x] Graph-native system prompts and catalog emitters
- [x] gorunner.pro fleet migration (Cloudflare Pages → GitHub Pages pipeline)
- [x] PIPELINE.toml dependency fix (build-surfaces depends on build-galaxy-json)
- [x] Build telemetry dashboard (phase timings over time)
- [x] Pure DAG Compiler: legacy sequential runner deleted, build-dag promoted to build, PIPELINE.toml 17/17 phases
- [x] Metalearning dependency: compile-claude-md depends on build-learning (intake-promote → CLAUDE.md closure)
Later
- [ ] ProcessPoolExecutor for galaxy enrichment (currently ThreadPool, I/O-bound — ThreadPool is correct for now)
- [ ] Scope partitioning for large fleet sites (ProcessPoolExecutor 8 workers already active)
- [ ] ACCESSIBILITY_AUDIT — lighthouse_audit emits accessibility.json per page, color contrast validation against design tokens
- [ ] DEPENDENCY_GRAPH — export galaxy as DOT/JSON for external visualization, circular dependency detection as artifact
VOCAB
| Term | Definition |
|---|---|
| DAG | Directed acyclic graph of build phases with dependency edges |
| PHASE | A numbered build step discovered by glob, executed by the orchestrator |
| GOV | Pure governance tree (`~/CANONIC/`), contains only `.md` files |
| RUNTIME | Compiled output tree (`~/.canonic/`), contains `.json`, scripts, caches |
| BOUNDARY | The compile-time enforced separation between GOV and RUNTIME |
| FRESHNESS | Mtime-based per-scope cache that skips unchanged scopes |
INHERITANCE CHAIN
SERVICES
SERVICES compose primitives — INTEL + CHAT + COIN. Every service governed. Every scope discovered.
MUST: Maintain TRIAD integrity (CANON.md + VOCAB.md + README.md)
MUST: Treat SPEC as scope identity (`{SCOPE}` directory), not as a file
MUST: Every SERVICE scope include ROADMAP.md, COVERAGE.md, LEARNING.md, and `{SCOPE}.md` as governed content surfaces
MUST: Discover SERVICE scopes from filesystem only (no manual catalog)
MUST: Keep http:// and magic:// on the same namespace (transport differs, scope path matches)
MUST: CANON.md = axiom + universal constraints (no service names, no paths, no implementation)
MUST: README.md = how to run the CANON (nothing else)
MUST: {SCOPE}.md = SPEC — the interface (purpose, routes, projections, ecosystem)
MUST: SHOP.md = public projection file (per scope, filesystem-discoverable)
MUST: VAULT.md = private projection file (per scope, filesystem-discoverable)
MUST: Runtime implementation remains under ~/.canonic; this workspace is governance-first
MUST NOT: Hardcode service names in CANON constraints (law speaks universals)
MUST NOT: Define ungoverned terms outside VOCAB.md
MUST NOT: Treat `{SCOPE}.md` as SPEC identity
MUST NOT: Move architecture/lifecycle into README
MUST NOT: Leak private projections to public surfaces
MUST NOT: Maintain duplicate mapping tables outside generated manifest outputs
MUST NOT: Add runtime jargon to governance contracts
MUST: Ledger-consuming services declare source ledgers, scope filters, and closure gates
MUST: Learning governance remains live — closure claims require fresh DISCOVER → GENERATE → RELINK evidence
hadleylab-canonic
HADLEYLAB ships software. Every app, book, paper, deal, and patent is PROOF that MAGIC works. COIN = WORK. LEARNING = COMPUTE.
MUST: Every app, book, paper, deal, or patent is evidence of MAGIC MUST: All scopes inherit canonic-canonic/CANONIC.md governance MUST: All users governed under USERS/ via SERVICES/USER MUST: Cross-index INTEL across users (INTEL.md) MUST: Shared events propagate to ALL affected user dashboards MUST: Maintain governance workspace purity (.md files only) MUST: Ledger all COIN (validated work) through MAGIC 255 MUST: Compile all INTEL from governed sources MUST: Keep frontend/runtime implementation under ~/.canonic (hidden runtime) MUST: Surface governed TALK, Library, and SERVICES scopes (no orphan content) MUST: Derive nav labels from governed scope names (no hardcoded strings) MUST NOT: Publish without governance (CANON.md required) MUST NOT: Duplicate primitives — compose from INTEL, CHAT, COIN MUST NOT: Silo intelligence inside a single user when multiple are affected MUST NOT: Expose VAULT contents outside NDA scope MUST NOT: Store runtime artifacts in governance workspace
canonic-canonic
SPEC is governance. `canonic-canonic/` is the spec root.
MUST: Keep this repo governance-only (.md/.pdf) MUST: Publish workspace mapping in CANONIC.git (no hardcoded repo lists) MUST: Preserve three primary lanes: FOUNDATION, INDUSTRIES, MAGIC MUST NOT: Commit runtime artifacts here (runtime belongs in ~/.canonic/) MUST: Sell MAGIC tiers — the product, not the proof (proof is hadleylab-canonic) MUST NOT: Embed beta-test app URLs in platform page content
BUILD · SERVICE CONTRACT · CANONIC ∩