N'Ko Inscription System - Phase 2 Implementation Report

┌─────────────────────────────────────────────────────────────────────────┐
│                     CC-INSCRIPTION ARCHITECTURE                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │   Claims     │    │    Basin     │    │   Lexicon    │               │
│  │  (10 types)  │───▶│  Lifecycle   │───▶│  Versioning  │               │
│  └──────────────┘    └──────────────┘    └──────────────┘               │
│         │                   │                   │                        │
│         ▼                   ▼                   ▼                        │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐               │
│  │   Phrase     │    │  Ontology    │    │   Surface    │               │
│  │  Detection   │◀───│  Operations  │───▶│  Renderer    │               │
│  └──────────────┘    └──────────────┘    └──────────────┘               │
│         │                   │                   │                        │
│         └───────────────────┼───────────────────┘                        │
│                             ▼                                            │
│                  ┌──────────────────────┐                               │
│                  │   Integration Layer   │                               │
│                  │  (Graph Kernel, RAG++) │                              │
│                  └──────────────────────┘                               │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

/// Slice declaration required for any ontology operation.
pub struct SliceDeclaration {
    pub slice_id: SliceFingerprint,
    pub [sensitive field redacted],
    pub policy_id: String,
    pub evidence_turns: Vec<String>,
}

/// Ontology operation with governance metadata.
pub struct OntologyOperation<T> {
    pub op_type: OntologyOperationType,
    pub slice: SliceDeclaration,
    pub predictability_assessment: PredictabilityAssessment,
    pub payload: T,
}

/// Operation types that can mutate the lexicon.
pub enum OntologyOperationType {
    ProposeSplit(BasinId),
    ProposeMerge(Vec<BasinId>),
    ProposeRetire(BasinId),
    GraduateProto(ProtoBasinId),
    RegisterPhrase(PhraseId),
}

/// Client for graph kernel slice governance.
pub struct GraphKernelClient {
    endpoint: Option<String>,
}

/// Request for an ontology-specific slice.
pub struct OntologySliceRequest {
    pub op_type: OntologyOperationType,
    pub basin_ids: Vec<BasinId>,
    pub time_window: TimeWindow,
    pub min_evidence_turns: usize,
}

/// Evidence sufficiency requirements.
pub struct EvidenceSufficiency {
    pub min_turns: usize,        // Default: 10
    pub min_time_span: f64,      // Default: 86400.0 (1 day)
    pub min_sessions: usize,     // Default: 3
}

/// Predictability assessment result.
pub struct PredictabilityAssessment {
    pub before: f64,
    pub after: f64,
    pub delta: f64,
    pub comparable_cases: Vec<ComparableCase>,
    pub confidence: f64,
}

/// Comparable historical case for evaluation.
pub struct ComparableCase {
    pub turn_id: String,
    pub similarity: f64,
    pub outcome: Option<String>,
}

/// Claim type distribution with Dirichlet smoothing.
pub struct ClaimTypeDistribution {
    pub counts: [u32; 10],
    pub alpha: QuantizedFloat,
}

/// Versioned lexicon with parent chain.
pub struct VersionedLexicon {
    pub lexicon: Lexicon,
    pub parent: Option<Box<VersionedLexicon>>,
    pub children: Vec<LexiconVersion>,
    pub created_at: f64,
    pub content_hash: [u8; 32],
}

/// Reinterpretation context with full provenance.
pub struct ReinterpretationContext {
    pub source_version: LexiconVersion,
    pub target_version: LexiconVersion,
    pub splits: Vec<SplitReinterpretation>,
    pub merges: Vec<MergeReinterpretation>,
    pub transform_hash: [u8; 32],
}

/// A reinterpreted claim preserves original provenance.
pub struct ReinterpretedClaim {
    pub original_id: InscriptionId,
    pub original_claim: Claim,
    pub reinterpreted_basin: Option<BasinId>,
    pub reason: ReinterpretationReason,
}

/// Why a claim was reinterpreted.
pub enum ReinterpretationReason {
    NoChange,
    SplitClassified { parent: BasinId, child: BasinId, classifier_hash: [u8; 32] },
    MergedInto { original: BasinId, merged_into: BasinId },
    Retired { original: BasinId, retirement_type: RetirementType },
}

/// Split classification result: ChildA, ChildB, or UNCERTAIN.
pub enum SplitAssignment {
    ChildA,      // Clearly belongs to child A
    ChildB,      // Clearly belongs to child B
    Uncertain,   // Too close to boundary
}

/// Whitening transform for dimensionality reduction.
pub struct WhiteningTransform {
    pub components: Vec<Vec<QuantizedFloat>>,
    pub mean: Vec<QuantizedFloat>,
    pub n_components: usize,
    pub variance_explained: QuantizedFloat,
    pub content_hash: [u8; 32],
}

/// Enhanced split classifier with tri-state output.
pub struct EnhancedSplitClassifier {
    pub normal: Vec<QuantizedFloat>,
    pub bias: QuantizedFloat,
    pub margin: QuantizedFloat,
    pub whitening: WhiteningTransform,
    pub content_hash: [u8; 32],
}

/// Split detection result.
pub struct SplitDetection {
    pub is_multimodal: bool,
    pub modality_score: QuantizedFloat,
    pub dynamics_divergent: bool,
    pub divergence_score: QuantizedFloat,
    pub proposed_separator: Option<EnhancedSplitClassifier>,
    pub cluster_centroids: Option<[Vec<QuantizedFloat>; 2]>,
    pub cluster_assignments: Vec<SplitAssignment>,
}

// Points within ±margin of hyperplane are UNCERTAIN
if signed_distance > margin {
    SplitAssignment::ChildA
} else if signed_distance < -margin {
    SplitAssignment::ChildB
} else {
    SplitAssignment::Uncertain  // Honest uncertainty
}

/// Merge detection result.
pub struct MergeDetection {
    pub is_indistinguishable: bool,
    pub distinguishability_score: QuantizedFloat,
    pub overlap_fraction: QuantizedFloat,
    pub reason: Option<MergeReason>,
}

/// Merge detector configuration with regularization.
pub struct MergeDetectorConfig {
    pub distinguishability_threshold: QuantizedFloat,
    pub min_overlap_fraction: QuantizedFloat,
    pub regularization_lambda: QuantizedFloat,  // λI for stability
    pub use_constitutional_bounds: bool,
}

/// Reason for basin merge.
pub enum MergeReason {
    SensorCoverageChanged,
    ContextsAbandoned,
    BehaviorConverged,
}

/// Pattern over claim types (stable 10-element vocabulary).
pub struct ClaimTypePattern {
    pub claim_types: Vec<ClaimType>,
    pub max_gap_micros: i64,
    pub content_hash: [u8; 32],
}

/// Candidate phrase with evidence provenance.
pub struct PhraseCandidate {
    pub pattern: ClaimTypePattern,
    pub frequency: u32,
    pub compression_ratio: QuantizedFloat,
    pub predictive_gain: QuantizedFloat,
    pub effect_size: QuantizedFloat,
    pub evidence_claim_ids: Vec<InscriptionId>,
}

/// Detection configuration.
pub struct PhraseDetectionConfig {
    pub min_frequency: u32,
    pub min_predictive_gain: QuantizedFloat,
    pub max_pattern_length: usize,
    pub entropy_prior_alpha: QuantizedFloat,  // Dirichlet smoothing
}

/// Entropy with Laplace smoothing (α=1.0).
pub fn entropy_from_claim_type_counts(
    counts: &ClaimTypeCounts,
    prior_alpha: QuantizedFloat,
) -> QuantizedFloat {
    let alpha = prior_alpha.to_f64();
    let total = counts.iter().sum::<u32>() as f64 + 10.0 * alpha;

    let mut h = 0.0;
    for &c in counts {
        let p = (c as f64 + alpha) / total;
        if p > 0.0 {
            h -= p * p.log2();
        }
    }
    QuantizedFloat::from_f64(h)
}

Claims → Mine N-grams → Filter by Frequency → Calculate Predictive Gain
       → Calculate Effect Size → Rank by Effect Size → Return Candidates

core/cc-inscription/
├── Cargo.toml
├── src/
│   ├── lib.rs                          # Module exports
│   ├── claims/
│   │   ├── mod.rs                      # Claim enum, 10 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/
│   │   ├── mod.rs
│   │   ├── proto.rs                    # Proto-basin state
│   │   ├── lifecycle.rs                # Split/merge/retire (Step 5-6)
│   │   ├── graduation.rs               # Proto → Basin criteria
│   │   └── constitution.rs             # Basin invariants
│   ├── lexicon/
│   │   ├── mod.rs
│   │   ├── version.rs                  # Version chain (Step 3)
│   │   ├── tokens.rs                   # Basin/Place tokens
│   │   ├── changelog.rs                # Change tracking
│   │   └── reinterpret.rs              # Reinterpretation layer (Step 4)
│   ├── ontology/
│   │   └── mod.rs                      # Ontology operations (Step 1)
│   ├── phrase/
│   │   ├── mod.rs
│   │   ├── detection.rs                # Phrase emergence (Step 7)
│   │   ├── compression.rs              # Description length
│   │   └── registration.rs             # Phrase → grammar
│   ├── integration/
│   │   ├── mod.rs
│   │   ├── graph_kernel.rs             # Slice governance (Step 2a)
│   │   ├── rag.rs                      # Predictability eval (Step 2b)
│   │   └── dell.rs                     # z-trajectory source
│   ├── surface/
│   │   ├── mod.rs
│   │   ├── renderer.rs                 # Claim → N'Ko line
│   │   ├── grammar.rs                  # Grammar skeletons
│   │   ├── slots.rs                    # Slot renderers
│   │   └── normalize.rs                # NFC + BiDi handling
│   ├── types/
│   │   ├── mod.rs                      # Public re-exports
│   │   ├── time.rs                     # Timestamp types
│   │   ├── quantized.rs                # QuantizedFloat + math
│   │   ├── basis.rs                    # BasisId, BasinConstitution
│   │   ├── evidence.rs                 # Evidence sum type
│   │   └── session.rs                  # Session segmentation
│   ├── canonical/
│   │   └── mod.rs                      # CBOR canonical serialization
│   └── provenance/
│       └── mod.rs                      # Provenance law verification
├── lexicons/
│   └── v1.0.json                       # Initial lexicon
├── docs/
│   └── PHASE2_IMPLEMENTATION.md        # This document
└── tests/
    └── (integrated in src/ as #[cfg(test)])

pub enum SplitAssignment {
    ChildA,      // Confident: distance > margin
    ChildB,      // Confident: distance < -margin
    Uncertain,   // Honest uncertainty: |distance| <= margin
}

// WRONG: Basin IDs evolve
fn divergence_old(basin_dist_a: &[BasinId], basin_dist_b: &[BasinId]) -> f64

// RIGHT: Claim types are stable
fn divergence_new(claim_dist_a: &ClaimTypeCounts, claim_dist_b: &ClaimTypeCounts) -> f64

let p = (count as f64 + alpha) / (total + 10.0 * alpha);

let regularized_var = variance + lambda;
let mahalanobis_component = diff_squared / regularized_var;

pub struct ReinterpretedClaim {
    pub original_id: InscriptionId,  // PRESERVED
    pub original_claim: Claim,       // PRESERVED
    pub reinterpreted_basin: Option<BasinId>,  // NEW VIEW
    pub reason: ReinterpretationReason,        // WHY
}

pub struct StreamingCanonicalSerializer {
    hasher: Sha256,
    writer: Vec<u8>,
}

pub struct LexiconEpoch {
    pub epoch_number: u64,
    pub lexicon_hash: [u8; 32],
    pub committed_at: Timestamp,
    pub parent_epoch_hash: [u8; 32],
}

pub struct CompressedSessionLog {
    pub base_timestamp: Timestamp,
    pub tick_deltas: Vec<u8>,  // Varint encoded
}