Implementation Guide

Implementation Guide

Version: 1.0.0
Last Updated: 2026-01-03

---

Decision Framework

How Decisions Are Made

Conflict Resolution

1. Charter wins: If conflicting with implementation detail, charter governs
2. Invariants win: If violating invariant, implementation must change
3. Glossary wins: If term is ambiguous, glossary definition governs
4. IR wins: If N'Ko surface conflicts with IR structure, adjust surface

What Constitutes "Done"

A task is complete when:
- [ ] Code compiles without warnings
- [ ] Tests pass (`cargo test`)
- [ ] Documentation matches implementation
- [ ] Checklist item is marked complete with artifact reference

What Constitutes "Blocked"

A task is blocked when:
- Missing dependency (another task must complete first)
- Ambiguous requirement (needs clarification)
- External service unavailable (Graph Kernel, DELL)
- Resource constraint (memory, compute)

---

Decomposition Rules

Atomic Unit Definition

The smallest unit of work:
- Has a single, verifiable output (one file, one struct, one test)
- Can be validated independently
- Does not require context from unfinished sibling tasks
- Can be rolled back without affecting other units

Maximum Scope Per Task

Required Depth Before Implementation

Before writing code:
1. Phase is defined in checklist
2. Step is broken into substeps
3. Substep has clear artifact output
4. Dependencies are identified and ordered

---

Validation Rules

Per-Step Validation

Blocking Validations

These MUST pass before moving forward:
- `cargo check` (compilation)
- `cargo test` (unit tests)
- `cargo clippy` (lint)
- Doc comments on public items

Validation Artifacts

Each validation produces:
- Test output (cargo test log)
- Lint output (cargo clippy log)
- Checklist update (marked complete with timestamp)

---

Crate Structure

core/cc-inscription/
├── Cargo.toml
├── src/
│   ├── lib.rs                    # Crate root, re-exports
│   ├── claims/                   # 10 claim IR types
│   │   ├── mod.rs               # Claim enum, shared types
│   │   ├── stabilize.rs         # Claim 1: ߛ
│   │   ├── disperse.rs          # Claim 2: ߜ
│   │   ├── transition.rs        # Claim 3: ߕ
│   │   ├── return_.rs           # Claim 4: ߙ
│   │   ├── dwell.rs             # Claim 5: ߡ
│   │   ├── oscillate.rs         # Claim 6: ߚ
│   │   ├── recover.rs           # Claim 7: ߞ
│   │   ├── novel.rs             # Claim 8: ߣ
│   │   ├── place_shift.rs       # Claim 9: ߠ
│   │   └── echo.rs              # Claim 10: ߥ
│   ├── basin/                    # Basin lifecycle
│   │   ├── mod.rs
│   │   ├── proto.rs             # Proto-basin state
│   │   ├── lifecycle.rs         # Birth/split/merge/retire
│   │   ├── graduation.rs        # Proto → Basin criteria
│   │   └── constitution.rs      # Basin invariants
│   ├── lexicon/                  # Vocabulary versioning
│   │   ├── mod.rs
│   │   ├── version.rs           # Lexicon versioning
│   │   ├── tokens.rs            # Basin/Place tokens
│   │   └── changelog.rs         # Change tracking
│   ├── surface/                  # N'Ko rendering
│   │   ├── mod.rs
│   │   ├── renderer.rs          # Claim → N'Ko line
│   │   ├── grammar.rs           # Grammar skeletons
│   │   └── slots.rs             # Slot renderers
│   ├── phrase/                   # Higher-order motifs
│   │   ├── mod.rs
│   │   ├── detection.rs         # Mine recurrent sequences
│   │   ├── compression.rs       # Test description length
│   │   └── registration.rs      # Phrase → grammar extension
│   ├── detector/                 # Claim detection
│   │   ├── mod.rs
│   │   ├── dynamics.rs          # z-trajectory metrics
│   │   └── per_claim/           # Detection logic per claim type
│   └── integration/              # External system bridges
│       ├── mod.rs
│       ├── graph_kernel.rs      # Slice boundary + admissibility
│       ├── rag.rs               # Evidence retrieval
│       └── dell.rs              # z-trajectory source
├── lexicons/                     # Versioned lexicon files
│   └── v1.0.json                # Initial controlled-register lexicon
├── docs/                         # Documentation
│   ├── 00-PROJECT_CHARTER.md
│   ├── 01-GLOSSARY.md
│   ├── 02-INVARIANTS_LEDGER.md
│   ├── 03-IMPLEMENTATION_GUIDE.md
│   ├── 04-IMPLEMENTATION_CHECKLIST.md
│   └── DESIGN.md
└── tests/                        # Integration tests
    ├── claim_detection.rs
    ├── basin_lifecycle.rs
    ├── surface_rendering.rs
    └── phrase_emergence.rs

---

Implementation Order

### Phase 1: Foundation (Current)
1. [x] Create crate with Cargo.toml
2. [x] Define all 10 claim IR structs
3. [x] Define core types (BasinId, PlaceClass, TimeWindow, Confidence)
4. [x] Define Claim enum with sigil() method
5. [ ] Create v1.0 lexicon JSON
6. [ ] Create remaining module stubs

### Phase 2: Basin Lifecycle
1. [ ] Implement ProtoBasin state machine
2. [ ] Implement GraduationCriteria checks
3. [ ] Implement BasinSplit with historical classifier
4. [ ] Implement BasinMerge with absorption table
5. [ ] Implement RetirementType variants
6. [ ] Add Graph Kernel governance for ontology ops

### Phase 3: Claim Detection
1. [ ] Implement dynamics metrics (velocity, acceleration, coherence, variance)
2. [ ] Implement detector for each claim type (10 detectors)
3. [ ] Add tests with synthetic z-trajectories

### Phase 4: Surface Rendering
1. [ ] Implement GrammarSkeleton for all 10 claim types
2. [ ] Implement SurfaceRenderer
3. [ ] Implement slot renderers
4. [ ] Implement lexicon-aware token lookup
5. [ ] Add RTL composition
6. [ ] Test IR → N'Ko round-trip

### Phase 5: Lexicon Versioning
1. [ ] Implement LexiconChange enum
2. [ ] Implement changelog tracking
3. [ ] Implement MultiVersionRenderer
4. [ ] Implement reinterpretation layer

### Phase 6: Phrase Emergence
1. [ ] Implement sequence mining
2. [ ] Implement compression ratio calculation
3. [ ] Implement predictive gain test
4. [ ] Implement phrase registration

### Phase 7: Integration
1. [ ] Wire Graph Kernel slice verification
2. [ ] Wire RAG++ evidence retrieval
3. [ ] Wire DELL trajectory subscription
4. [ ] End-to-end test

---

Coding Standards

Naming Conventions

Documentation Requirements

• All public items have doc comments
• Doc comments include:
• One-line summary
• Canonical N'Ko form (for claims)
• Example usage (for complex methods)

Test Requirements

• Every struct has at least one test
• Edge cases are documented with tests
• Integration tests cover module boundaries