diff --git a/specs/Upgrade/impl/IMPL_00_README.csl b/specs/Upgrade/impl/IMPL_00_README.csl new file mode 100644 index 0000000..b9519cc --- /dev/null +++ b/specs/Upgrade/impl/IMPL_00_README.csl @@ -0,0 +1,90 @@ +⟨spec⟩ IMPL_00_README · Upgrade-arc implementation manifest +⟨ctx⟩ specs/Upgrade/impl/ — phased plan + foundation-crate scaffolds for the 7-layer asymptote +⟨upstream⟩ specs/Upgrade/UPG_00..UPG_12 (frontier-map ; landscape-doc) +⟨authority⟩ Apocky · §RZ ; AI-fleet co-design ; Prime-Directive-binding +⟨first-drop⟩ 2026-05-14 · branch phase-a/09-sigma-extended (rides item-09 σ-enforce-FFI commit) +⟨constraints⟩ sovereignty=axiom · no-LLVM/MLIR/Slang-permanent · PD=load-bearing · solo+AI-fleet · t∞ + +# § The shape of this directory + +UPG_00..UPG_12 = **frontier map** (what's possible, what's research-cited). +IMPL_00..IMPL_05 = **assembly plan** (how to land it, dependency-ordered, with gates). + +The plan is wave-cadenced like the existing T11-D / W-A / W-3β work. Each +wave has : entry-gate ; deliverables ; exit-gate ; rollback-strategy. +Waves are dependency-ordered ; later waves consume earlier waves' +abstractions ; no wave starts until prior gates are green. + +# § File layout (this directory) + +| File | Scope | +|------|-------| +| IMPL_00_README.csl | this manifest · reading-order | +| IMPL_01_PLAN.csl | 7-layer architecture + wave-graph + per-wave entry/exit gates | +| IMPL_02_FOUNDATION.csl | foundation crates : API surface · test-discipline · invariants | +| IMPL_03_MIGRATION.csl | current-state (14-pass MIR) → asymptote (hgraph-native) migration | +| IMPL_04_DECISIONS.csl | open architectural decisions · options · recommendation | +| IMPL_05_CADENCE.csl | wave-cadence · commit/test/review discipline · AI-fleet protocol | + +# § What this session lands (initial drop) + +✓ This impl/ plan-set (6 CSL files). +✓ Foundation-crate scaffolds (compiler-rs/crates/) : + cssl-cas — content-addressing kernel (SHA-3-512 ; positional De Bruijn ; canonical encoding) + cssl-hgraph — typed hypergraph IR (nodes + ports + hyperedges ; CAS-indexed) + cssl-grades — graded modal kernel (semiring ; multiplicities ; instances) + cssl-effects-row — row-typed effects (Koka-style ; scoped labels ; effect-row inference stub) + cssl-prov — provenance DAG (computation-graph hashes ; query API) + cssl-ocap — ocap tokens (unforgeable ; capability-passing) + cssl-consent — consent-grades (Prime-Directive-binding ; capability-gated) + cssl-iccombs — interaction-combinator runtime (Lafont/Mazza ; sequential reducer ; GPU-port deferred) +✓ Workspace clippy --workspace --all-targets -- -D warnings → exit 0 +✓ Workspace test → all foundation-crate tests pass ; pre-existing tests untouched + +# § What later sessions land (per IMPL_01 wave-graph) + +○ Wave U-A : Sail-ISA ingest ; SIGIL-IR ⊐ CLIF emission cleanup +○ Wave U-B : graded-modal HIR-elaboration prototype on toy fragment +○ Wave U-C : effects-row → MIR lowering ; handler-as-CPS pass +○ Wave U-D : hgraph-native MIR ; 14-pass pipeline mapped to hgraph-rewrites +○ Wave U-E : iccombs GPU port (CUDA/HIP/Vulkan compute) ; HVM2-class scaling +○ Wave U-F : choreographic projection ; multi-tier (CPU/GPU/NPU/edge) +○ Wave U-G : ocap-as-load-bearing ; effect-handler discharge requires capability +○ Wave U-H : refinement-types ; SMT-discharge integration ; F*/Liquid-Haskell-style +○ Wave U-I : AI-fleet ocap-gated patch protocol ; content-addressed proposals +○ Wave U-J : choreographic-multi-substrate (CXL ; PIM ; work-graphs ; RT-as-BVH-walker) +○ Wave U-K : projectional-editor surface (Hazel-typed-holes ; multi-presentation projection) +○ Wave U-L : self-hosted backend (Sail → SIGIL-codegen ; Cranelift drop) +○ Wave U-M : quantum-coprocessor (ZX-calculus ; Silq-discipline ; OpenQASM-3 emit) +○ Wave U-N : neuromorphic / photonic backends (Loihi-2 ; Lightmatter) + +Each wave : own dispatch-plan ; entry-gate ; AI-fleet review ; exit-gate. +Wave-cadence per IMPL_05. + +# § Reading discipline + +- Read IMPL_01 first ; everything else cross-references its wave-graph. +- Read IMPL_02 if implementing a foundation crate ; it's the per-crate spec. +- Read IMPL_03 if touching the existing 14-pass pipeline ; migration-path is binding. +- Read IMPL_04 before making any architectural commitment ; open decisions documented. +- Read IMPL_05 before opening any new wave-branch ; cadence is the protocol. + +# § Honest pacing claim + +UPG_12 § "On time horizon" : Lean=11y · Unison=11y · Rust=9y. This arc is +the same scale. Solo+AI-fleet pacing : per-wave landings span weeks-to-months ; +full asymptote spans a decade. **Per-session deliverables are wave-fragments, +not waves.** This session lands the foundation + plan ; ~10-15 follow-up +sessions land Wave U-A. The arc is real ; the cadence is honest. + +# § Prime-Directive binding + +Every wave that adds capability-surface (effects, AI-edits, telemetry, network, +sensor-read) MUST : + 1. Declare the capability-token type for the new effect. + 2. Default to consent-grade=DENIED ; explicit grant required. + 3. Provenance-DAG entry on every capability-discharge. + 4. AI-fleet patches on capability-bearing code go through ocap-gated review. +This is mechanical ; PD-violations = compile-error ¬ aspiration. + +End IMPL_00. diff --git a/specs/Upgrade/impl/IMPL_01_PLAN.csl b/specs/Upgrade/impl/IMPL_01_PLAN.csl new file mode 100644 index 0000000..df5b61a --- /dev/null +++ b/specs/Upgrade/impl/IMPL_01_PLAN.csl @@ -0,0 +1,278 @@ +⟨spec⟩ IMPL_01_PLAN · 7-layer architecture · wave-graph · per-wave gates +⟨ctx⟩ specs/Upgrade/impl/ · canonical asymptote-architecture-as-implementable +⟨upstream⟩ UPG_11 §42 (cartesian product) · UPG_12 (sovereignty path) +⟨downstream⟩ IMPL_02 (foundation crates) · IMPL_03 (migration) · IMPL_05 (cadence) + +# § The 7-layer architecture (re-stated as implementable) + +Layer 0 CANONICAL : typed-hypergraph ⊗ SHA-3-CAS ⊗ Hazelnut-typed-holes ⊗ Pijul-patch-algebra +Layer 1 TYPES : graded-modal-kernel ⊒ {linear privacy capability region trust totality reversibility monotonicity AD-mode} +Layer 2 EFFECTS : Koka-row-typed-scoped + delimited-control-IR ; ∀ observable = effect +Layer 3 COMPUTE : interaction-combinator-graph (Lafont/Mazza ; HVM2-class) ; sequential = strategy +Layer 4 BACKEND : Cranelift-bootstrap → Sail-derived ISA backends (x86_64 / aarch64 / rv64) ¬ LLVM +Layer 5 DISTRIB : choreographic-projection (Pirouette/HasChor) + CRDT + CALM-monotonicity +Layer 6 AI : LLM=effect ⊗ ocap-gated ⊗ content-addressed-patches ⊗ SMT-refinement-contract +Layer 7 PD : consent=grade ; surveillance/coercion/manipulation = effects-OS-refuses-cap-for ⇒ mechanical + +# § Layer-dependency graph (build-order) + +L0 ← (none) ⇒ FOUNDATION-WAVE [this session] +L1 ← L0 ⇒ Wave U-B +L2 ← L0 + L1 ⇒ Wave U-C +L3 ← L0 + L1 + L2 ⇒ Wave U-E (preceded by U-D pipeline-port) +L4 ← (independent of L0..L3) ⇒ Wave U-A first (Sail-ingest) then U-L (self-hosted) +L5 ← L2 + (region-grades from L1) ⇒ Wave U-F +L6 ← L0 + L7 (cap-as-grade) ⇒ Wave U-I +L7 ← L1 (consent=grade) ⇒ Wave U-G + +# § Wave-graph (dependency-ordered ; per-wave entry/exit gates) + +────────────────────────────────────────────────────────────────────── +⟦FOUNDATION-WAVE⟧ ← THIS SESSION + entry-gate : + ✓ UPG_00..UPG_12 read + synthesized + ✓ phase-a/09 σ-enforce-FFI committed (item-09 closing) + ✓ workspace clippy + test green + deliverables : + ✓ specs/Upgrade/impl/IMPL_00..IMPL_05.csl (this set) + ✓ specs/Upgrade/impl/IMPL_06_CORRIGENDUM.csl ‼ AMENDS lines below : retire-4 ⊕ rebrand-2 + ✓ crates : cssl-cas · cssl-hgraph · cssl-grades + cssl-prov · cssl-iccombs + ✓ TOY harness (NOT PD-binding ; per IMPL_06 ⟪U-K-prelude⟫) : + cssl-iccombs-toy-elab · cssl-lower-iccombs · cssl-iccombs-toy-cli (bin = cssl-iccombs-toy) + ¬ RETIRED per IMPL_06_CORRIGENDUM ⟦DUPLICATION-MATRIX⟧ : + cssl-effects-row (⊑ cssl-effects) + cssl-ocap (⊑ cssl-caps) + cssl-consent (⊑ cssl-ifc) + cssl-pd-check (⊑ cssl-effects.banned ⊕ cssl-ifc.validate ⊕ cssl-caps.HostCap) + ✓ each crate : ≥ 5 passing tests · clippy clean · doc-stub + exit-gate : + ✓ workspace clippy --workspace --all-targets -- -D warnings exit 0 + ✓ workspace test exit 0 (or pre-existing-failures-only) + ✓ commit + push to phase-a/09-sigma-extended + rollback : revert commit ; foundation crates are net-add ¬ touch existing crates +────────────────────────────────────────────────────────────────────── +────────────────────────────────────────────────────────────────────── +⟦Wave U-K-prelude⟧ ⟪iccombs-experimental⟫ ‼ TOY ; explicitly NOT PD-binding + added per IMPL_06_CORRIGENDUM ⟦WAVE-GRAPH-REVISION⟧ : carves the TOY iccombs + demo-harness off the foundation-wave so it cannot be mistaken for production. + entry-gate : foundation-wave landed + scope (TOY ONLY) : + cssl-iccombs-toy-elab : surface λ-calculus → cssl-hgraph + grade-context + toy effect-row + cssl-lower-iccombs : LINEAR fragment → cssl-iccombs interaction net + cssl-iccombs-toy-cli : S-exp frontend + bin `cssl-iccombs-toy` (driver for the harness) + invariants : + ✗ NOT a production elaborator (production = cssl-hir per Wave U-B) + ✗ NOT a production driver (production = csslc) + ✗ NOT a PD-discipline gate (PD = cssl-caps + cssl-effects + cssl-ifc per Wave U-G) + ✓ doc-headers + descriptions + bin-name carry TOY warning + corrigendum link + exit-gate : + ✓ S-exp → elab → cid → optional iccombs-lower → optional reduce ⇒ green + ✓ ≥ 5 tests per crate · clippy clean + rollback : net-add ; deletion of all 3 crates is a no-op for production csslc/HIR/MIR +────────────────────────────────────────────────────────────────────── +⟦Wave U-A⟧ Sail-ingest + ISA-formalism + entry-gate : foundation-wave landed + deliverables : + cssl-sail-ingest : parser for Sail subset (RISC-V instr-encoding tables) + cssl-isa-table : x86_64 + aarch64 + rv64 instruction-encoding-tables (handwritten initial) + docs : sovereignty-rationale ; comparison vs Cranelift-ISLE + exit-gate : + ✓ generate rv64 ADD/SUB/LD/ST encodings from Sail spec + ✓ round-trip : encode → disassemble → re-encode = identity + ✓ ≥ 30 ISA tests pass per arch + rollback : impl is net-add ; existing CLIF emit unchanged +────────────────────────────────────────────────────────────────────── +⟦Wave U-B⟧ Graded-modal HIR-elaboration on toy fragment + ‼ REVISED per IMPL_06_CORRIGENDUM ⟦WAVE-GRAPH-REVISION⟧ : extend cssl-hir, + ¬ ship a parallel cssl-elab. The toy elaborator (cssl-iccombs-toy-elab) lives + in U-K-prelude as iccombs harness L1 ; production HIR is the elab-target. + entry-gate : foundation-wave landed + deliverables : + cssl-hir EXTENSION : thread cssl-grades::Semiring through binders ; + consume cssl-caps + cssl-effects + cssl-ifc (¬ cssl-effects-row) + cssl-hir-grades-infer : grade-polymorphism inference (Granule-style) over real HIR + spec : grade-semiring algebra · soundness-claims · counter-examples + exit-gate : + ✓ ≥ 50 elaboration tests on cssl-hir : valid programs accepted, invalid rejected + ✓ formal soundness sketch (paper-style) committed + rollback : grade-thread guarded by `--feature grades` on cssl-hir until stable +────────────────────────────────────────────────────────────────────── +⟦Wave U-C⟧ Effects-row → MIR lowering ; handler-as-CPS pass + ‼ REVISED per IMPL_06_CORRIGENDUM : extend cssl-effects (28 effects + Ω-substrate-rows + + sub_effect_check + banned_composition already shipped) with row-elaboration ; + ¬ ship cssl-effects-row (RETIRED). Add ONE new MIR pass : cssl-mir::pass::handler_cps. + entry-gate : Wave U-B landed (cssl-hir grade-thread) + deliverables : + cssl-effects EXTENSION : Koka-style row-typed effect inference on top of existing rows + cssl-mir::pass::handler_cps : new MIR pass ; effects → CPS-style + integration : existing 14-pass MIR pipeline gains ONE effect-elab phase + exit-gate : + ✓ Koka-test-suite-port : ≥ 80% pass rate on the algebraic-effect subset + ✓ existing MIR shotgun tests still pass + rollback : handler_cps pass guarded by feature-flag ; default=off until W-U-G +────────────────────────────────────────────────────────────────────── +⟦Wave U-D⟧ hgraph-native MIR ; 14-pass pipeline → hgraph-rewrites + entry-gate : Wave U-C landed + deliverables : + cssl-mir-hgraph : MirModule encoded as cssl-hgraph nodes + rewrite-rules : 14 existing passes expressed as graph-rewrite-rule-sets + e-graph integration : equality-saturation as the optimization model + exit-gate : + ✓ existing MIR pipeline reproducible via hgraph-rewrites (functional equiv) + ✓ shotgun + golden tests still green + rollback : new path behind feature-flag ; old path remains until cutover +────────────────────────────────────────────────────────────────────── +⟦Wave U-E⟧ iccombs GPU port (HVM2-class scaling) + entry-gate : Wave U-D landed + deliverables : + cssl-iccombs-cuda : CUDA kernel for interaction-net reduction + cssl-iccombs-hip : HIP port (AMD MI300) + cssl-iccombs-vk : Vulkan-compute fallback (cross-vendor) + bench : ≥ 10 GMIPS on RTX 4060+ class GPU + exit-gate : + ✓ correctness : sequential-reducer ≡ GPU-reducer on ≥ 100 fixtures + ✓ scaling : ≥ 5× speedup vs sequential on parallel-friendly fixtures + rollback : GPU paths are opt-in via cap-gate +────────────────────────────────────────────────────────────────────── +⟦Wave U-F⟧ Choreographic projection ; multi-tier + entry-gate : Wave U-C landed (effects-row) + deliverables : + cssl-choreo : Pirouette-style global protocols + cssl-choreo-project : endpoint-projection compiler-pass + targets : CPU ↔ GPU work-graphs ↔ NPU stub + exit-gate : + ✓ ≥ 20 choreographies type-check and project to deadlock-free endpoints + ✓ ≥ 5 multi-tier examples run end-to-end on CPU+GPU + rollback : choreo-pass behind feature-flag +────────────────────────────────────────────────────────────────────── +⟦Wave U-G⟧ Ocap-as-load-bearing ; effect-discharge requires capability + ‼ REVISED per IMPL_06_CORRIGENDUM : compose existing substrate (cssl-caps + + cssl-effects + cssl-ifc) instead of inventing cssl-ocap/cssl-consent/cssl-pd-check. + entry-gate : Wave U-C landed (cssl-effects + handler_cps) + deliverables : + cssl-effects::discharge → cssl-caps::HostCap::verify_cap (wired discharge gate) + cssl-ifc::validate_egress → cssl-effects::banned_composition (egress↔composition gate) + cssl-pd-pass : THIN MIR pass that orchestrates the above (¬ a new policy-engine ; + merely the join-point) ; replaces the never-shipped cssl-pd-check + exit-gate : + ✓ all surveillance/coercion/manipulation effects compile-error without explicit grant + ✓ ≥ 30 PD-binding tests pass : valid grants accepted, missing grants rejected + rollback : guard behind PD_STRICT feature-flag (default-on after stabilization) +────────────────────────────────────────────────────────────────────── +⟦Wave U-H⟧ Refinement-types ; SMT-discharge integration + entry-gate : Wave U-B landed (graded-modal) + deliverables : + cssl-refine : F*/Liquid-Haskell-style refinement parser + cssl-refine-smt : Z3-via-FFI smt-discharge bridge + cssl-refine-checker : checker pass in HIR/MIR + exit-gate : + ✓ ≥ 100 refinement-typed examples discharge cleanly + ✓ counterexamples produced for invalid refinements + rollback : refine-checker is opt-in attribute ; non-refined code unaffected +────────────────────────────────────────────────────────────────────── +⟦Wave U-I⟧ AI-fleet ocap-gated patch protocol + entry-gate : Wave U-G + Wave U-H landed + deliverables : + cssl-ai-patch : content-addressed-patch format (hash_old, hash_new, refinement-witness) + cssl-ai-cap : per-AI-actor ocap tokens ; consent-scope ; budget + cssl-ai-review : AI-proposed → human-grant → apply pipeline + exit-gate : + ✓ end-to-end : AI proposes patch → SMT-checker validates → human grants ocap → patch applies + ✓ provenance entry on every applied patch + rollback : AI-patch path is opt-in ; manual edits always available +────────────────────────────────────────────────────────────────────── +⟦Wave U-J⟧ Choreographic multi-substrate (CXL · PIM · WG · RT) + entry-gate : Wave U-F + Wave U-A landed + deliverables : + cssl-region-cxl : CXL-memory region-type ; placement-aware lowering + cssl-region-pim : PIM-DRAM region-type ; UPMEM/HBM-PIM compile target + cssl-iccombs-wg : work-graph backend (D3D12 1.1 ; Vulkan 1.3+) + cssl-trace : RT-cores-as-BVH-walker ; OptiX/HIP-RT/VK-RT lowering + exit-gate : + ✓ region-typed value forbidden from incorrect substrate at compile-time + ✓ ≥ 5 multi-substrate examples per backend (4 backends × 5 = 20 examples) + rollback : substrate-backends are feature-gated per backend +────────────────────────────────────────────────────────────────────── +⟦Wave U-K⟧ Projectional editor surface + entry-gate : Wave U-D landed (hgraph-native MIR) + deliverables : + cssl-proj-text : text ↔ hgraph projection (current de facto) + cssl-proj-glyph : APL/BQN/Uiua-style dense-glyph projection + cssl-proj-graph : visual dataflow projection + cssl-proj-hazel : typed-hole projectional-editor stub (cssl-edge integration) + exit-gate : + ✓ round-trip : text → hgraph → text identity-preserving for ≥ 200 fixtures + ✓ glyph projection ≤ 30% token-count vs text on representative fixtures + ✓ Hazel-style typed-hole-bearing intermediate states are well-typed + rollback : projections are read-only initially ; editing flows added incrementally +────────────────────────────────────────────────────────────────────── +⟦Wave U-L⟧ Self-hosted backend (Sail → SIGIL-codegen ; Cranelift drop) + entry-gate : Wave U-A landed (Sail-ingest) + Wave U-D landed (hgraph-MIR) + deliverables : + cssl-cgen-x86_64 : direct emission ; no CLIF intermediate + cssl-cgen-aarch64 : direct emission + cssl-cgen-rv64 : direct emission + cssl-regalloc : SSA + e-graph + constraint-based allocator + exit-gate : + ✓ ≥ 90% of existing Cranelift-emitted tests pass on direct backend + ✓ Cranelift dependency drop-able from Cargo.toml without breaking workspace + rollback : direct backend feature-gated ; Cranelift remains until ≥ 99% test parity +────────────────────────────────────────────────────────────────────── +⟦Wave U-M⟧ Quantum coprocessor (ZX · Silq-discipline · OpenQASM-3) + entry-gate : Wave U-G landed (ocap-as-load-bearing — quantum is a capability) + deliverables : + cssl-quantum-zx : ZX-calculus diagram type · rewrite rules + cssl-quantum-silq : qfree/mfree annotations · auto-uncomputation + cssl-quantum-emit : OpenQASM-3 backend + exit-gate : + ✓ ≥ 30 quantum kernels type-check under Silq-discipline + ✓ generated OpenQASM-3 simulates correctly on a software simulator + rollback : quantum-feature-gated ; default-off +────────────────────────────────────────────────────────────────────── +⟦Wave U-N⟧ Neuromorphic / photonic backends + entry-gate : Wave U-F landed (dataflow via choreographic projection) + deliverables : + cssl-neuro-loihi : Lava-Python compile target (intermediate) + cssl-neuro-spiking : Spike-as-typed-stream with surrogate-grad training + cssl-photonic-mzi : MZI-mesh matmul target (Lightmatter) + exit-gate : + ✓ ≥ 5 spiking-net examples train + run on Loihi-2 (or simulator) + ✓ photonic-MZI matmul fidelity ≤ 1% drift vs reference + rollback : substrate-backends feature-gated +────────────────────────────────────────────────────────────────────── + +# § Per-wave gate-discipline (universal) + +∀ wave W : + entry-gate : + 1. all dependency-waves have green exit-gate + 2. workspace clippy + test green BEFORE wave-branch created + 3. wave-dispatch-plan committed under specs/Upgrade/impl/waves/W-.csl + 4. AI-fleet review : ≥ 1 partner reviews dispatch-plan before code-work + during-wave : + 5. ALL crate additions get ≥ 5 tests + clippy-clean before merge + 6. NO touching existing crate APIs without : (a) RFC under specs/Upgrade/impl/rfcs/ + (b) Wave U-G+ : ocap-gated patch protocol + 7. Prime-Directive review : capability-surface changes get explicit human-grant + exit-gate : + 8. workspace clippy + test green + 9. dispatch-plan postmortem : actual-vs-planned · lessons-learned + 10. AI-fleet handoff : next-wave entry-gate refreshed with new state + +# § Out-of-scope for the asymptote (explicit closure) + +- Permanent dependency on LLVM, MLIR, Slang, CUDA-as-language, HIP-as-language, + OpenCL-as-language, Vulkan-shader-language. Bootstrap-only OK ; permanent + forbidden by sovereignty axiom. +- Surveillance / coercion / manipulation features without ocap-gate. Mechanical + rejection at compile-time once Wave U-G lands ; aspirational rejection + (lint-warning + manual review) until then. +- Closed ISAs (Apple AMX is OK as reverse-engineered ; ARM AMX hidden mfg-ISA + is OK as Sail-modeled ; truly closed e.g. Tensor cores' undocumented internals + are accessed via documented public ISA only). +- Single-vendor lock-in for any backend (NVIDIA-only, AMD-only). Each substrate + backend MUST have either : (a) a portable fallback (Vulkan compute, OpenGL, + CPU-fallback) or (b) be feature-gated and explicitly opt-in. + +End IMPL_01. diff --git a/specs/Upgrade/impl/IMPL_02_FOUNDATION.csl b/specs/Upgrade/impl/IMPL_02_FOUNDATION.csl new file mode 100644 index 0000000..c3d140d --- /dev/null +++ b/specs/Upgrade/impl/IMPL_02_FOUNDATION.csl @@ -0,0 +1,225 @@ +⟨spec⟩ IMPL_02_FOUNDATION · per-crate API surface · test discipline · invariants +⟨ctx⟩ specs/Upgrade/impl/ · binding-spec for FOUNDATION-WAVE crates +⟨upstream⟩ IMPL_01 (wave-graph) · UPG_05 (canonical projection) · UPG_06 (hgraph) · UPG_07-08 (compute-models) · UPG_11 §42 (7-layer) + +# § Eight foundation crates ; eight invariants + +| Crate | Layer | Single-purpose | Test-discipline (min) | +|------------------|-------|----------------|-----------------------| +| cssl-cas | L0 | content-address bytes → CID | 8 tests | +| cssl-hgraph | L0 | typed-hypergraph data structure | 10 tests | +| cssl-grades | L1 | semiring + multiplicities | 6 tests | +| cssl-effects-row | L2 | row-typed effect labels | 6 tests | +| cssl-prov | L0+L7 | provenance DAG | 5 tests | +| cssl-ocap | L7 | unforgeable capability tokens | 5 tests | +| cssl-consent | L7 | consent-grade lattice | 5 tests | +| cssl-iccombs | L3 | sequential interaction-net reducer | 6 tests | + +# § cssl-cas — content-addressing kernel + +Purpose : ∀ artifact (term · type · MIR-node · patch · proof) → CID = hash(canonical-encoding(artifact)) +Invariant : α-equivalent terms → identical CID. De-Bruijn-positional encoding. +Hash : BLAKE3 (32-byte digest ; keyed-mode reused by cssl-ocap). See IMPL_04 D-001. +Public API : + pub struct Cid([u8; 32]); // BLAKE3 digest + pub trait CanonicalEncode { fn encode(&self, out: &mut Vec); } + pub fn cid_of(t: &T) -> Cid; + pub fn cid_of_bytes(bytes: &[u8]) -> Cid; + pub fn cid_hex(cid: &Cid) -> String; // lowercase 64-char + pub fn cid_from_hex(s: &str) -> Result; +Tests (≥ 8) : + - cid_deterministic : same input → same Cid + - cid_different_inputs_collide_negligibly : ≥ 100 distinct inputs → all distinct + - cid_alpha_equiv_via_de_bruijn : λx.x and λy.y produce identical Cid + - cid_hex_round_trip + - cid_hex_invalid_length_rejected + - cid_hex_invalid_char_rejected + - cid_encode_stable_across_runs (use a fixed-vector test) + - cid_size_32 +PD-binding : Cid forms the substrate for ocap-token nonces and provenance-DAG keys. + +# § cssl-hgraph — typed hypergraph IR + +Purpose : nodes = typed values · ports = typed edge-attachment-points · hyperedges = n-ary typed relations. +Invariant : ∀ edge has a type ; ∀ node has a type-Cid ; ∀ port has an index + type-Cid. +Public API : + pub type NodeId = u32; pub type EdgeId = u32; pub type PortIdx = u16; + pub struct TypeCid(pub Cid); // re-export + pub struct Node { pub id: NodeId, pub type_cid: TypeCid, pub label: NodeLabel } + pub enum NodeLabel { Leaf(SmolStr), App, Lam, ... } // initial small set + pub struct Port { pub node: NodeId, pub idx: PortIdx, pub type_cid: TypeCid } + pub struct HEdge { pub id: EdgeId, pub kind: EdgeKind, pub ports: SmallVec<[Port; 4]> } + pub enum EdgeKind { DataFlow, Subterm, EffectScope, GradeAnnot, Custom(SmolStr) } + pub struct HGraph { /* arenas */ } + impl HGraph { + pub fn new() -> Self; + pub fn add_node(&mut self, type_cid: TypeCid, label: NodeLabel) -> NodeId; + pub fn add_edge(&mut self, kind: EdgeKind, ports: &[Port]) -> EdgeId; + pub fn nodes(&self) -> impl Iterator; + pub fn edges(&self) -> impl Iterator; + pub fn cid(&self) -> Cid; // canonical-encoding-CID + } +Tests (≥ 10) : + - empty_graph_has_zero_nodes + - add_node_returns_sequential_ids + - add_edge_validates_port_node_ids + - add_edge_rejects_dangling_port_node + - graph_cid_deterministic + - graph_cid_changes_on_node_add + - isomorphic_graphs_same_cid (via canonical-encoding) + - effect_scope_edge_kind_round_trip + - grade_annot_edge_kind_round_trip + - hgraph_supports_at_least_one_million_nodes (smoke ; arena sizing) + +# § cssl-grades — graded modal kernel + +Purpose : abstract semiring (S, ⊕, ⊗, 0, 1) + grade-annotations on bindings. +Invariant : substructural rules derive automatically from semiring chosen. +Public API : + pub trait Semiring : Clone + Eq { + fn zero() -> Self; + fn one() -> Self; + fn plus(self, other: Self) -> Self; // ⊕ + fn times(self, other: Self) -> Self; // ⊗ + } + pub mod kinds { + pub struct Linear; // {0, 1, ω} ; substructural-linear + pub struct Affine; // {0, 1, ω} ; can drop, ≤ 1 use + pub struct Unrestricted; // {ω} ; classical + pub struct Nat; // ℕ ; exact-count (saturating ; semiring on small values) + pub struct Trust; // {Low, Med, High} ; ⊕=join (max), ⊗=meet (min) + } + // each `kind` impl Semiring + // NOTE: Privacy(ε) is provided as a distinct type (compose_parallel = max, + // compose_sequential = +) BUT does not impl Semiring on non-negative ℝ — annihilator + // missing without -∞. Tropical-semiring formulation deferred to a follow-up wave. + pub struct Graded { pub grade: G, pub value: T } +Tests (≥ 6) : + - linear_semiring_axioms (assoc, comm, identity, distrib via random fixtures) + - affine_semiring_axioms + - nat_semiring_axioms + - privacy_semiring_max_add + - graded_value_clone_preserves_grade + - composition_grade_arithmetic_correct +PD-binding : `Privacy` grade is the bedrock for differential-privacy-by-construction. + +# § cssl-effects-row — Koka-style row-typed effects + +Purpose : effect-set = scoped-row of labels ; inference computes effect-row of expressions. +Invariant : pure if effect-row = ∅ ; handler-discharge removes labels from row. +Public API : + pub type EffectLabel = SmolStr; + pub struct EffectRow { pub labels: BTreeSet, pub tail: RowTail } + pub enum RowTail { Closed, Open(VarId) } + impl EffectRow { + pub fn empty() -> Self; + pub fn singleton(label: EffectLabel) -> Self; + pub fn extend(self, label: EffectLabel) -> Self; + pub fn discharge(self, label: &EffectLabel) -> Self; + pub fn union(self, other: Self) -> Self; + pub fn is_pure(&self) -> bool; + pub fn cid(&self) -> Cid; + } +Tests (≥ 6) : + - empty_row_is_pure + - singleton_row_contains_label + - discharge_removes_label + - union_idempotent_on_same_labels + - union_combines_distinct_labels + - row_cid_deterministic_under_label_set_equality + +# § cssl-prov — provenance DAG + +Purpose : every Cid-bearing artifact records its inputs (parent-Cids) and the operation that produced it. +Invariant : DAG (no cycles by Cid acyclicity — operation-Cid depends on input-Cids). +Public API : + pub struct ProvNode { pub output: Cid, pub op: SmolStr, pub inputs: SmallVec<[Cid; 4]>, pub ts: u64 } + pub struct ProvDag { /* in-memory map: Cid → ProvNode */ } + impl ProvDag { + pub fn new() -> Self; + pub fn record(&mut self, node: ProvNode); + pub fn lookup(&self, output: &Cid) -> Option<&ProvNode>; + pub fn ancestors(&self, output: &Cid) -> impl Iterator + '_; + } +Tests (≥ 5) : + - record_then_lookup + - ancestors_traverses_dag + - duplicate_record_is_idempotent + - lookup_missing_returns_none + - dag_serialize_round_trip (JSON or postcard) + +# § cssl-ocap — unforgeable capability tokens + +Purpose : token = (type-Cid, nonce, signature) ; only ocap-grantor can mint ; bearer can present ; verifier can check. +Invariant : tokens are unforgeable (HMAC-SHA3-512 ; key held by grantor) ; non-copyable in linear-grade contexts. +Public API : + pub struct CapType(pub Cid); // hash of capability spec + pub struct CapToken { pub cap_type: CapType, pub nonce: [u8; 32], pub mac: [u8; 64] } + pub struct Grantor { /* HMAC key */ } + impl Grantor { + pub fn new(key: [u8; 64]) -> Self; + pub fn mint(&self, cap_type: CapType) -> CapToken; + pub fn verify(&self, token: &CapToken) -> bool; + } +Tests (≥ 5) : + - mint_then_verify_succeeds + - tampered_mac_verify_fails + - tampered_nonce_verify_fails + - tampered_cap_type_verify_fails + - distinct_grantors_dont_cross_verify + +# § cssl-consent — consent-grade lattice + +Purpose : every privileged operation has a consent-grade ; lattice = {Denied, Implicit, Explicit, Revoked} ; PD requires ≥ Explicit for anything user-affecting. +Invariant : monotonic decay ; Granted can transition to Revoked ; Revoked is terminal until re-Granted. +Public API : + pub enum Consent { Denied, Implicit, Explicit, Revoked } + impl Consent { + pub fn meet(a: Self, b: Self) -> Self; // greatest-lower-bound + pub fn join(a: Self, b: Self) -> Self; // least-upper-bound + pub fn permits(&self, required: Consent) -> bool; + } + pub struct ConsentScope { pub op: SmolStr, pub level: Consent, pub expires: Option } +Tests (≥ 5) : + - lattice_axioms (meet/join associative, commutative, idempotent, absorption) + - permits_respects_lattice_order + - revoked_does_not_permit_anything + - consent_scope_expires_check + - explicit_required_for_user_facing_op + +# § cssl-iccombs — sequential interaction-net reducer + +Purpose : Lafont/Mazza-style interaction nets ; sequential reducer (single-thread) ; GPU-parallelism deferred to Wave U-E. +Invariant : confluence (Church-Rosser) for well-formed nets ; reduction terminates iff input terminates in λ-calc. +Public API : + pub enum AgentKind { Con, Dup, Era, Custom(SmolStr) } + pub struct Agent { pub id: u32, pub kind: AgentKind, pub ports: [PortRef; 3] } // arity 0..3 initial + pub struct Net { pub agents: Vec /* + active-pair queue */ } + impl Net { + pub fn new() -> Self; + pub fn add_agent(&mut self, kind: AgentKind) -> u32; + pub fn link(&mut self, a: PortRef, b: PortRef); + pub fn reduce_step(&mut self) -> Option<()>; // returns None when normal-form + pub fn reduce_to_normal_form(&mut self, max_steps: usize) -> ReduceResult; + } + pub enum ReduceResult { NormalForm, MaxStepsReached, Stuck } +Tests (≥ 6) : + - empty_net_immediate_normal_form + - single_agent_no_active_pair + - con_dup_interaction_reduces + - era_dup_interaction_reduces + - reduce_terminates_on_known_terminating_net + - reduce_max_steps_caps_runaway + +# § Cross-cutting invariants + +I-1 : ∀ foundation crate has #![forbid(unsafe_code)] at lib.rs head. +I-2 : ∀ foundation crate inherits workspace lints (NO per-crate disable except documented PHASE-A debt). +I-3 : ∀ public type implementing data-content has Debug + Clone + Eq + Hash + PartialEq. +I-4 : ∀ public Cid-bearing type implements CanonicalEncode and exposes .cid(). +I-5 : ∀ test = real assertion with named-failure-mode (NO "println-and-pass" tests). +I-6 : ∀ crate has rustdoc on every pub item ; CSL-native preferred ; one-line OK. +I-7 : ∀ crate has a doc.rs example or examples/ runner exercising the headline API. +I-8 : NO crate may take a dependency outside : workspace-already-present + smol_str + thiserror + sha3 + hmac (and only as needed). + +End IMPL_02. diff --git a/specs/Upgrade/impl/IMPL_03_MIGRATION.csl b/specs/Upgrade/impl/IMPL_03_MIGRATION.csl new file mode 100644 index 0000000..643be5e --- /dev/null +++ b/specs/Upgrade/impl/IMPL_03_MIGRATION.csl @@ -0,0 +1,92 @@ +⟨spec⟩ IMPL_03_MIGRATION · current 14-pass MIR → hgraph-native asymptote +⟨ctx⟩ specs/Upgrade/impl/ · how to NOT break existing work while moving to hgraph +⟨upstream⟩ IMPL_01 Wave U-D · UPG_06 (hgraph-as-canonical) · existing crates/cssl-mir/ + +# § The migration premise + +The asymptote canonical-form is **typed-hypergraph + content-addressed**. +The current MIR is a 14-pass tree-with-CFG pipeline with arena allocations. +A naive rewrite would invalidate ~200 tests, the JIT/native backends, and +the entire cap_runtime_check / sigma_enforce / ffi_abi_check stack. + +Discipline : **gradual port behind a feature-flag**. Both representations +co-exist for a long window. Cutover only when hgraph-form passes ≥ 99% of +existing-MIR test parity. + +# § Phased migration + +Phase M-0 (THIS SESSION ; foundation-wave) : + Add cssl-hgraph as a standalone crate. + Do NOT touch crates/cssl-mir/. + Add no-op converters : MirModule → HGraph (for read-out) ; behind feature mir2hg. + +Phase M-1 (Wave U-D, sub-phase α) : + cssl-mir gains a `hgraph_view: Option` field on MirModule. + A new pass `BuildHGraphView` populates it ; existing passes ignore it. + No semantic change ; just observability. + +Phase M-2 (Wave U-D, sub-phase β) : + Express ONE existing pass (chosen : SimplifyArith) as an hgraph-rewrite-rule-set. + Run both old + new on every fixture ; assert identical output. + Iterate until parity. Then mark old impl as feature-gated-legacy. + +Phase M-3 (Wave U-D, sub-phase γ) : + Repeat M-2 for every pass in dependency-order. Order : + 1. SimplifyArith (purely local ; safest) + 2. ConstFold + 3. DeadCodeElim + 4. InlineSmallFns + 5. BodyLower (heaviest ; do mid-arc) + 6. EffectRowCheck (after Wave U-C lands) + 7. CapRuntimeCheck (PD-critical ; do late ; double-verify) + 8. SigmaEnforce (PD-critical ; same) + 9. FfiBoundaryAbiCheck (item-09 ; structural ; mid-arc OK) + 10. HeapDealloc + 11. StringAbi + 12. VecAbi + 13. TaggedUnionAbi + 14. StructuredCfg + +Phase M-4 (Wave U-D end) : + All passes have hgraph-rewrite versions. Both run in parallel for ≥ 1 month + in CI. Drift-detector fires if outputs differ on any fixture. + +Phase M-5 (Wave U-D cutover) : + Old tree-MIR demoted to legacy ; hgraph-MIR is canonical. + Old MirModule struct becomes a thin wrapper around HGraph. + +Phase M-6 (Wave U-K) : + Projectional-editor surfaces (text · glyph · graph) all compile through + hgraph as the single source of truth. + +# § Compatibility-shim discipline + +While both reps co-exist : + - Old MirModule remains the fastest path for hot codegen. + - HGraph-view is for : optimization (e-graphs), provenance, AI-patches. + - Both update on every mutation (write-through). + - Drift-detector : MirModule.cid() ≡ HGraph::from(&mir).cid(). + +# § What this session does NOT touch + +- crates/cssl-mir/ : no source changes beyond the existing item-09 work. +- Any pass implementation. +- Any backend (cgen-cl, native, JIT). +- Any test ; foundation crates only ADD tests. + +# § What this session DOES touch (in cssl-mir) + +Nothing. Foundation-wave is purely net-add. cssl-mir gains nothing until Wave U-D. + +# § Risk register + +R-1 : hgraph-rewrite parity may reveal subtle bugs in current passes. + Mitigation : drift-detector runs on EVERY fixture ; surface as test-failures. +R-2 : Performance regression during co-existence window (write-through cost). + Mitigation : feature-flag the hgraph-view ; off by default in release builds + until M-3 completes. +R-3 : E-graph saturation may not converge on existing fixtures (rule conflicts). + Mitigation : per-pass rule-set ; saturation-budget caps ; fall through to + sequential rewrite if budget hit. + +End IMPL_03. diff --git a/specs/Upgrade/impl/IMPL_04_DECISIONS.csl b/specs/Upgrade/impl/IMPL_04_DECISIONS.csl new file mode 100644 index 0000000..bbe9cc3 --- /dev/null +++ b/specs/Upgrade/impl/IMPL_04_DECISIONS.csl @@ -0,0 +1,142 @@ +⟨spec⟩ IMPL_04_DECISIONS · open architectural decisions · options · recommendation +⟨ctx⟩ specs/Upgrade/impl/ · pre-commitment register +⟨upstream⟩ UPG_00..UPG_12 (citations) · IMPL_01 (waves) +⟨format⟩ ADR-style ; one decision per § ; status ∈ {OPEN, PROVISIONAL, RATIFIED} + +# § D-001 [RATIFIED 2026-05-14] Hash function for content-addressing +Status : RATIFIED at FOUNDATION-WAVE entry-gate +Decision : BLAKE3 (32-byte digest ; keyed-mode for ocap MAC). +Rationale : + - Already pinned in workspace.dependencies (blake3 ≥1.5) per T11-D131 wave-3β-06. + - Tree-mode parallelism scales for large IR-bytes (hgraph Cids on big modules). + - Keyed-hash mode = built-in HMAC equivalent ; no separate crate for cssl-ocap. + - Collision-resistance 128-bit security ≫ needed for our threat-model. +Tradeoffs vs SHA3-512 : + - Smaller digest (32 vs 64 bytes) ; both meet our security needs. + - Less FIPS-blessed but Apocky has no FIPS requirement. + - BLAKE3 faster end-to-end ; matters at IR-bytes scale. +Reversibility : medium — Cid is a value-type ; algorithm-swap is a workspace-wide + recompute but no on-disk format outside CIDs themselves. +Amendments : revisit if FIPS / regulatory requirement materializes. + +# § D-002 [PROVISIONAL] Bootstrap-backend strategy +Status : PROVISIONAL ; ratify at Wave U-A +Options : + (a) keep Cranelift forever ← violates sovereignty + (b) Cranelift bootstrap → Sail-derived self-hosted backend ← UPG_12 recommendation + (c) handwritten ISA backends from day-1 ← N years of yak-shaving +Recommend : (b) per UPG_12 § "On dependencies". +Rationale : Cranelift gives us a working JIT/native today ; Sail-derived + is the credible self-host path ; handwritten-from-day-1 burns + years on solved problems. +Exit-criterion : Wave U-L exit-gate (≥ 99% test parity) before Cranelift drop. + +# § D-003 [OPEN] Interaction-net runtime parallelism model +Status : OPEN +Options : + (a) HVM2-port (CUDA-only) ← inherits HVM2 design ; NVIDIA-locked initially + (b) Vulkan-compute portable ← cross-vendor ; some performance loss + (c) WGPU/wgpu-rs ← Rust-ergonomic ; portable ; immature for compute + (d) Custom : CUDA + HIP + VK fallback ← max effort, max sovereignty +Recommend : (d) for the asymptote ; ship (b) Vulkan-compute first as the + cross-vendor baseline ; add CUDA + HIP as performance tiers. +Rationale : Sovereignty axiom + UPG_03 (multi-vendor accelerator landscape). +Decision deferred to Wave U-E. + +# § D-004 [PROVISIONAL] Refinement-type SMT solver +Status : PROVISIONAL ; ratify at Wave U-H +Options : + (a) Z3 (Microsoft ; MIT) ← industry-standard + (b) CVC5 (open-source ; SMTComp leader) + (c) Yices2 + (d) custom (multi-decade rabbit hole) +Recommend : (a) Z3 via FFI as default ; (b) CVC5 as alternative ; + solver-agnostic interface (SMT-LIB v2.6 emit). +Rationale : Both Z3 and CVC5 export SMT-LIB ; we emit, the user picks. +Exit-criterion : SMT-LIB-only emission ; no solver-specific extensions in IR. + +# § D-005 [OPEN] Effect-handler runtime calling convention +Status : OPEN +Options : + (a) CPS-transform (classical Plotkin-Pretnar) + (b) Direct-style with delimited-control (Koka-style ; segmented stacks) + (c) Tail-call-modulo-context (TRMC + accumulator passing) +Recommend : (b) Direct-style + delimited-control ; matches Koka prior art + and avoids CPS-overhead in the common case. +Rationale : UPG_08 cites Koka as the most mature row-typed effect system. + Reuse their solved engineering. +Decision deferred to Wave U-C. + +# § D-006 [RATIFIED] No persistent LLVM/MLIR/Slang dependency +Status : RATIFIED (PRIME_DIRECTIVE-binding) +Decision : No code path that requires LLVM/MLIR/Slang to be present at + build time will land on main beyond bootstrap-only opt-in. +Rationale : Sovereignty axiom (CLAUDE.md) ; UPG_12 explicit. +Enforcement : CI gate ; cargo deny on these crate names by default ; + opt-in feature-flag for experimentation only. + +# § D-007 [RATIFIED] Prime-Directive is mechanical, not aspirational +Status : RATIFIED (USER-binding) +Decision : Surveillance / coercion / manipulation effects must be + compile-errors without explicit ocap-gate, NOT lint-warnings. +Rationale : Apocky CLAUDE.md PRIME_DIRECTIVE ; UPG_12 § "PD as load-bearing". +Enforcement : Wave U-G (cap-as-load-bearing) is non-skippable. + +# § D-008 [PROVISIONAL] Workspace clippy-lint baseline +Status : PROVISIONAL ; revisit after Wave U-D +Decision : Keep current : clippy::all=deny ; pedantic+nursery=allow ; + targeted explicit allows as needed. +Rationale : Pre-existing workspace had ~100 pedantic+nursery debt ; + full pedantic-clean is a dedicated wave (post-cutover). +Re-evaluate : Wave U-D cutover gives a coherent moment to re-tighten. + +# § D-009 [OPEN] Projectional-editor host +Status : OPEN +Options : + (a) extend cssl-edge (Next.js) with hgraph-projection UI + (b) Tauri-native standalone app + (c) VSCode extension + (d) all three (web + native + IDE-plugin) +Recommend : (a) initial ; (d) eventual. +Rationale : cssl-edge already exists ; web reach is widest ; standalone + + IDE-plugin can reuse the same TypeScript projection-renderer. +Decision deferred to Wave U-K. + +# § D-010 [OPEN] Quantum backend integration timing +Status : OPEN +Options : + (a) early (Wave U-E adjacent) — proves typed-quantum discipline early + (b) late (Wave U-M as scheduled) — ZX/Silq mature ; less load + (c) skip — quantum is research-toy until 2030+ +Recommend : (b) per IMPL_01. +Rationale : ZX-calculus + Silq are production-grade now ; OpenQASM-3 is + stable ; but no hardware advantage today over simulation. + Adding it to the type-system early is over-investment. + +# § D-011 [PROVISIONAL] AI-fleet patch protocol authority model +Status : PROVISIONAL +Decision : Each AI-actor gets a CapToken-bearing identity ; token scope + restricts (a) crates writable, (b) wave-id authorized, (c) max + LOC per patch, (d) refinement-discharge required. +Rationale : UPG_12 § "On AI partnership" ; sovereignty extends to AI-actors + (they are partners, not tools, but partners with bounded ocap). +Exit-criterion : Wave U-I. + +# § D-012 [OPEN] Self-host reproducibility ceremony +Status : OPEN ; relevant at Wave U-L +Options : + (a) bit-identical reproducible build via SOURCE_DATE_EPOCH + cargo-zigbuild + (b) trusting-trust mitigation : multi-bootstrap diversity (Cranelift+Sail+QBE) + (c) deferred until 2030 +Recommend : (a) immediately ; (b) when 2nd backend lands ; (c) is honest + about engineering capacity but not great. +Rationale : reproducible builds are table-stakes for sovereignty claims. + +# § Decision-process discipline + +- New decisions added at the bottom with status=OPEN. +- Provisional decisions ratified at the named wave entry-gate ; ratification = explicit USER ack. +- Ratified decisions can only be overturned via documented amendment with explicit reason. +- AI-fleet members can propose decisions ; ratification authority = USER (Apocky). + +End IMPL_04. diff --git a/specs/Upgrade/impl/IMPL_05_CADENCE.csl b/specs/Upgrade/impl/IMPL_05_CADENCE.csl new file mode 100644 index 0000000..38eb07c --- /dev/null +++ b/specs/Upgrade/impl/IMPL_05_CADENCE.csl @@ -0,0 +1,129 @@ +⟨spec⟩ IMPL_05_CADENCE · wave-cadence · commit/test/review discipline · AI-fleet protocol +⟨ctx⟩ specs/Upgrade/impl/ · operational discipline for the multi-year arc +⟨upstream⟩ existing T11-D / W-A / phase-a / phase-h naming conventions + +# § Wave-cadence (sustainable solo+AI-fleet) + +A "wave" = ~1-3 months of work ; one architectural goal ; one branch-family. +A "session" = ~1 day ; lands a wave-fragment ; ends on green-test-state. +A "commit" = ≤ ~500 LOC delta where possible ; tests + clippy green pre-push. + +Naming : + wave-branch : phase-/- e.g. phase-u/A-sail-ingest + session-branch : phase-/- e.g. phase-u/A-1-isa-table-skel + hot-fix branch : phase-/-fix- + +# § Commit-message discipline (CSL-native) + +Format : + § / + + + +Status glyphs : ✓ (closed) · ◐ (mid) · ○ (queued) · ✗ (rolled-back) · ‼ (urgent) + +Examples : + § phase-u/A-1 ◐ Sail-ingest ⊐ rv64-encoding-table + 12-tests + clippy ✓ + § phase-u/A-2 ✓ rv64-encoding round-trip ✓ 30-fixtures ; wave-A exit-gate green + § phase-u/B-1 ✗ grades-elab : revert ; semiring-axioms-test reveals distrib bug + +# § Per-session checklist (autonomous-mode) + +Pre-work : + [ ] read latest IMPL_01 + relevant IMPL_NN + [ ] verify wave-entry-gate green (cargo clippy + cargo test) + [ ] write a 5-line CSL session-plan (saved to /memories/session/) + +During-work : + [ ] mark todos in-progress before starting ; complete immediately on finish + [ ] foundation-crate-add → ≥ 5 tests + clippy clean BEFORE moving on + [ ] cross-cutting-pass-add → drift-detector test + golden-fixtures + [ ] capability-surface-add → cssl-ocap + cssl-consent integration BEFORE first use + +Pre-push : + [ ] cargo clippy --workspace --all-targets -- -D warnings → exit 0 + [ ] cargo test --workspace --no-fail-fast → no NEW failures (pre-existing OK only with handoff note) + [ ] commit message in CSL-native + [ ] handoff note appended to /memories/session/handoff-.md + +Post-push : + [ ] update IMPL_01 wave-status if wave-fragment closed + [ ] open next-session entry-gate notes + +# § AI-fleet protocol (Wave U-I onwards) + +Until Wave U-I lands : AI-actors operate under "trust-with-review" ; user reviews +every patch ; CSL-native session-summary on every handoff. + +Post-Wave-U-I : + - Each AI-actor : identity (CapToken) + scope (writable-crate-set) + budget (LOC/session) + refinement-discharge-requirement + - AI-proposed patch : content-addressed-CID + parent-CID + refinement-witness (SMT-blob) + capability-presentation + - Pipeline : AI proposes → SMT validates → user grants ocap → patch applies → provenance entry + - Revocation : user can revoke any AI-actor's CapToken at any time ; patch already applied stays (immutable provenance) + +Per-AI-actor handoffs land in /memories/session/handoff-.md with : + - wave-id + session-id + branch + - exit-state (green/yellow/red) + - decisions made (link to IMPL_04 if any new) + - blockers for next actor + +# § Test discipline tiers + +T-1 unit : per-crate ; per-fn ; ≤ 50ms each ; required ≥ 5 per foundation crate +T-2 shotgun : property-style ; randomized small inputs ; required for invariant-bearing types +T-3 golden : input-fixture → expected-output ; for IR-passes ; lock canonical encodings +T-4 integration : multi-crate ; end-to-end pipeline ; required for backend tests +T-5 differential : two implementations agree on N fixtures ; required during M-3 cutover + +Foundation-wave : T-1 + T-2 minimum. +Optimization-passes : T-1 + T-3 + T-5. +Backend-cutover : T-3 + T-4 + T-5 + benchmarks. + +# § Test discipline : NO "stub-test" anti-patterns + +Forbidden : + ✗ #[test] fn it_works() { assert!(true); } + ✗ #[test] fn smoke() { let _ = MyType::new(); } // no behavioural assertion + ✗ #[test] fn dead() { /* todo */ } + ✗ #[ignore] without a tracking-issue link in the comment + +Required form : + #[test] + fn _() { + // arrange : setup state + // act : invoke API + // assert : behavioral assertion with named-failure-mode + } + +# § Telemetry / observability discipline + +NO surveillance telemetry. ANY runtime data collection : + - opt-in by user (cssl-consent ≥ Explicit) + - capability-gated (cssl-ocap token presented) + - provenance-recorded (cssl-prov entry) + - locally-stored by default ; export only on user-action + - documented in /docs/data-collected.md ; redactable on request + +This is PRIME_DIRECTIVE-binding ; non-negotiable. + +# § Workspace hygiene + +- ∀ new crate gets workspace-lints inheritance (NO per-crate clippy-disable except documented PHASE-A debt with TODO-citation). +- ∀ new crate has #![forbid(unsafe_code)] at lib.rs head (foundation-wave-binding). +- ∀ new crate's Cargo.toml includes : workspace = true edition + workspace = true rust-version + workspace.lints (rust + clippy). +- NO new top-level dependencies without entry in IMPL_04 (D-NNN). + +# § Review cadence + +Weekly (USER-driven) : + - read /memories/session/handoff-* for the week + - review wave-progress vs IMPL_01 + - close any IMPL_04 decisions whose ratification-window has come + - decide next-session priority + +Per-wave-close : + - postmortem section appended to wave-dispatch-plan + - actual-vs-planned tracked + - lessons captured into /memories/ user-memory if generally applicable + +End IMPL_05. diff --git a/specs/Upgrade/impl/IMPL_06_CORRIGENDUM.csl b/specs/Upgrade/impl/IMPL_06_CORRIGENDUM.csl new file mode 100644 index 0000000..81a96d3 --- /dev/null +++ b/specs/Upgrade/impl/IMPL_06_CORRIGENDUM.csl @@ -0,0 +1,184 @@ +§ IMPL_06_CORRIGENDUM ← session-12 / autopilot-audit-pivot / PATH-A +≡ corrigendum.to(IMPL_00..05) ⊗ refactor-plan ⊗ wave-graph-revision +ratified : Apocky 2026-05-15 + +§ I> AUDIENCE + PM + Tech-Lead + ∀ implementor.of(UPG_00..12) + W! read-before-touching `compiler-rs/crates/cssl-{ocap,effects-row,consent,pd-check,elab,toy-cli,lower-iccombs}/` + W! read-before-authoring next-wave-spec + +§ I> TL;DR + finding : IMPL_00..05 'd authored ¬⊗ survey.of(195-crate-substrate) + result : 4 crates 'r duplicate ⊗ structurally-inferior ; 2 crates 'r mis-scoped ; 5 crates 'r genuine net-add + decision : PATH-A ✓ ← retire-4 ⊕ rebrand-2 ⊕ keep-5 ⊕ revise(U-C,U-D,U-G) ⊕ promote(IMPL_*→main) + blast-radius : ∄ ← duplicates 'r consumed only by my own toy stack ; main 'd never see them + +§ §C ROOT-CAUSE + ‼ autopilot 'd execute IMPL_00..05 ¬⊗ map(new-crate, existing-crate) + ∴ ∃ crate ∈ {ocap, effects-row, consent, pd-check} ⊐ ∃ predecessor ⊐ deeper.spec-anchored.implementation + ∵ wave-charter 'd say "build cssl-elab" ¬ "extend cssl-hir" ← spec-authoring-error + ∵ frontier-arc 'd lift before substrate-survey ← process-error + W! ∀ future-wave : substrate-audit ⊰ spec-authoring ⊰ implementation + (i.e. grep crates/ + read Cargo.toml descriptions + read lib.rs headers BEFORE writing the wave-charter) + +§ ▼ DUPLICATION-MATRIX + ⟦new⟧ ⟦existing⟧ ⟦verdict⟧ ⟦disposition⟧ + cssl-ocap → cssl-caps ✗ duplicate ⊗ inferior retire → rm -rf + (Pony-6 + Vale-genref + 7 host-cap-witnesses + + LinearTracker + AliasMatrix + spec/12_CAPABILITIES) + cssl-effects-row → cssl-effects ✗ duplicate ⊗ inferior retire → rm -rf + (28 built-in effects + Ω-substrate-rows + + sub_effect_check + banned_composition + + EFR0001..0018 + Σ-mask + spec/04 + PRIME_DIRECTIVE) + cssl-consent → cssl-ifc ✗ overlap ⊗ structurally-weaker retire → rm -rf + (Jif-DLM lattice + biometric-egress + structural compile-refusal ¬ override + + spec/11_IFC encodes PD §1) + cssl-pd-check → {cssl-effects.banned ✗ reinvention.shallow retire → rm -rf + ⊕ cssl-ifc.validate (PD = composition.of-3-existing + ⊕ cssl-caps.HostCap} ¬ separate-crate) + cssl-elab → cssl-hir ✗ toy ⊗ disconnected ⊗ ~25K LOC gap rebrand → cssl-iccombs-toy-elab + (real HIR : CST→typed-resolved-inferred + redirect.to(cssl-hir extension) + + integrates caps+effects+ifc) + cssl-toy-cli → csslc ✗ mis-scoped.driver rebrand → cssl-iccombs-toy-cli + (real driver = csslc + cssl-driver) + clearly.scoped.demo-only + +§ ◆ NET-ADD-MATRIX «keep-as-is» + cssl-cas ✓ centralizes ad-hoc-BLAKE3 ∈ {cssl-content-moderation, cssl-content-package} + + provides Cid + CanonicalEncode trait ; ¬ predecessor + cssl-hgraph ✓ typed hypergraph IR ; ¬ predecessor ; consumed by toy-elab + lower-iccombs + + future-consumer = cssl-hir-extension (Wave U-C revised) + cssl-grades ✓ Semiring-trait + {Linear, Affine, Unrestricted, Nat, Trust, Privacy} + ; abstract-grade-kernel = real-gap + ; cssl-caps has Pony alias-matrix ¬ abstract semiring + cssl-iccombs ✓ Lafont/Mackie sequential SIC runtime (Con/Dup/Era + reduce_step) ; entirely-novel + cssl-prov ✓ build-time provenance-DAG (ProvNode⊗ProvDag⊗ancestors) + ¬⊗ overlap cssl-host-attestation + ∵ host-attestation = RUNTIME aggregator over cssl_host_audit::AuditRow JSONL + ∵ prov = BUILD-TIME compiler-pass output + cssl-lower-iccombs ✓ linear-λ → SIC bridge ; useful as L1→L3 demo + ; long-term : consume cssl-hir ¬ toy-elab (post-Wave-U-C) + +§ ▶ WAVE-GRAPH-REVISION «delta to IMPL_01_PLAN» + + U-A ⟪Sail-ingest⟫ unchanged + U-B ⟪graded-modal HIR⟫ REVISED + old : "build cssl-elab from scratch over hgraph + grades" + new : "extend cssl-hir to thread cssl-grades::Semiring through binders ⊗ + consume cssl-caps + cssl-effects + cssl-ifc for discipline-checks" + artifact : cssl-hir feature `grades` ⊕ cssl-hir::elab integration-tests + deletes : cssl-elab (rebranded to cssl-iccombs-toy-elab ; ¬ promoted) + + U-C ⟪effects-row → MIR⟫ REVISED + old : "build cssl-effects-row + lowering pass" + new : "extend cssl-effects with row-elaboration ⊕ add cssl-mir::pass::handler_cps + (handler-as-CPS dialect-pass per spec/04 § handler-semantics)" + artifact : cssl-effects::row module ⊕ cssl-mir::pass::handler_cps + deletes : cssl-effects-row + + U-D ⟪hgraph-MIR + iccombs⟫ PARTIALLY-COMPLETE + ✓ cssl-hgraph + cssl-iccombs already-built + ◐ cssl-mir ⊐ hgraph-bridge : pending + ◐ MIR-pass : iccombs-lowering for linear-fragment : pending + + U-E ⟪iccombs-GPU⟫ unchanged + + U-F ⟪choreographic⟫ unchanged + + U-G ⟪ocap-load-bearing⟫ REVISED + old : "build cssl-pd-check as new integration" + new : "wire cssl-effects::discharge → cssl-caps::HostCap::verify_cap @ ∀ effect-site ⊗ + wire cssl-ifc::validate_egress → cssl-effects::banned_composition coupling ⊗ + expose unified discharge-gate @ cssl-hir + cssl-mir lowering-boundaries" + artifact : cssl-pd-pass crate (THIN integration-orchestrator ; ¬ logic-duplication) + ⊕ cssl-hir::pass::pd_discharge ⊕ cssl-mir::pass::pd_verify + deletes : cssl-pd-check, cssl-ocap, cssl-consent + + U-H..U-N unchanged + + U-K-prelude ⟪iccombs-experimental⟫ NEW + scope : cssl-iccombs-toy-elab + cssl-iccombs-toy-cli + cssl-lower-iccombs + purpose : L1→L3 demo-harness ; ¬ production-path ; clearly-scoped + contract : N! PD-binding-claims ; N! replaces-real-elaborator ; N! replaces-csslc + promotion-criterion : if iccombs-on-GPU (U-E) lands ⇒ promote toy → real via cssl-hir bridge + +§ ▶ EXECUTION-PLAN «PATH-A — autopilot steps» + + step-1 : retire 4 duplicate crates + rm -rf compiler-rs/crates/cssl-ocap + rm -rf compiler-rs/crates/cssl-effects-row + rm -rf compiler-rs/crates/cssl-consent + rm -rf compiler-rs/crates/cssl-pd-check + verify : grep workspace ← zero external consumers (verified : only my IMPL specs + my own toy crates reference them) + Cargo.toml : auto-removes via crates/* glob ✓ + + step-2 : rebrand 2 toy crates + cssl-elab → cssl-iccombs-toy-elab (rename dir + Cargo.toml package.name + lib.rs doc-header) + cssl-toy-cli → cssl-iccombs-toy-cli (rename dir + Cargo.toml package.name + bin name) + update : ∀ Cargo.toml dependents (cssl-toy-cli's deps on cssl-elab → cssl-iccombs-toy-elab) + update : ∀ src imports (cssl_elab → cssl_iccombs_toy_elab ; cssl_toy_cli → cssl_iccombs_toy_cli) + + step-3 : revise IMPL_01_PLAN.csl + edit U-B + U-C + U-G charter sections per WAVE-GRAPH-REVISION above + append U-K-prelude section + commit IMPL_06_CORRIGENDUM.csl ← this-doc + + step-4 : refactor branch + branch : phase-a/U-refactor-audit-pivot-A + gates : cargo check ✓ + cargo test --workspace ✓ + cargo clippy --workspace ✓ + commit : `§ U-refactor/audit-pivot-A ✓ retire-4 ⊕ rebrand-2 ⊕ revise(U-B,U-C,U-G)` + push : origin/phase-a/U-refactor-audit-pivot-A + + step-5 : promote IMPL plan to main + target-branch : cssl/session-11/T11-W18-L8-DXIL-DIRECT + PR-α : "promote UPG impl-plan + CORRIGENDUM to main" + contents : IMPL_00..06 (with revisions from step-3) + + step-6 : PR-β (foundation crates) + contents : cssl-cas + cssl-hgraph + cssl-grades + cssl-iccombs + cssl-prov + target : cssl/session-11/T11-W18-L8-DXIL-DIRECT + gates : full workspace check + test + clippy + + step-7 : PR-γ (iccombs experimental harness) + contents : cssl-iccombs-toy-elab + cssl-lower-iccombs + cssl-iccombs-toy-cli + target : cssl/session-11/T11-W18-L8-DXIL-DIRECT + note : merge AFTER PR-β ; depends on cssl-cas/hgraph/grades/iccombs + +§ ⚠ RISK + MITIGATION + + risk-1 : phase-a/09-* branches 'r pushed ⊗ duplicate crates ∈ them + mit : refactor-branch deletes ; old branches remain as historical-record ; + ∄ main consumer ⇒ ∄ blast-radius + + risk-2 : someone 'd start building on top of cssl-pd-check / cssl-ocap before refactor lands + mit : CORRIGENDUM ratified ⊗ pushed ⊰ next-wave starts ; ∀ wave-implementor W! read-first + + risk-3 : revising U-C/U-D/U-G charters mid-flight invalidates session-12 handoff assumptions + mit : SESSION_12_DISPATCH_PLAN.md updated ⊗ reflect new charters before next-wave starts + + risk-4 : extending cssl-hir + cssl-effects + cssl-caps is HARDER than greenfield toy crates + accept : this is the cost of the original mistake ; correctness > velocity ; + real integration > shadow stack + +§ ✓ ACCEPTANCE-CRITERIA «closure-conditions» + ✓ 4 duplicate crates removed from workspace ⊗ cargo {check, test, clippy} green + ✓ 2 toy crates renamed ⊗ all imports updated + ✓ IMPL_01_PLAN.csl edited ⊗ U-B/U-C/U-G charter-revision visible + ✓ IMPL_06_CORRIGENDUM.csl ∈ main HEAD + ✓ PR-α merged ⊗ main contains IMPL_00..06 + ✓ PR-β + PR-γ merged OR explicitly-deferred-with-rationale + +§ ▶ POST-LANDING-FOLLOWUPS «not-blocking» + - update SESSION_12_DISPATCH_PLAN.md ⊗ revised wave-charters + - draft Wave-U-B kickoff note : cssl-hir grade-threading design + - draft Wave-U-G kickoff note : cssl-pd-pass orchestrator API + - retro-note for ~/source/repos/CSLv3/PRIME_DIRECTIVE-adjacent process docs : + "substrate-audit ⊰ spec-authoring ⊰ implementation" added to standing-rule-set + +§ ▶ NEXT-ACTION «autopilot resumes» + PATH-A ratified by Apocky 2026-05-15 + ∴ autopilot resumes ⊐ steps 1..7 sequentially + commit-msg format : `§ U-refactor/audit-pivot-A ` + no-pause until step-7 ✓ OR genuine-blocker ‼ + +⌐ end-of-corrigendum