SilverSight/docs/SPECTRAL_CODEBOOK_GENERATOR.md

Spectral Codebook Generator

Date: 2026-07-01 Module: python/spectral_codebook.py Output: data/spectral_codebook.json Tests: tests/test_spectral_codebook.py (43 tests)

Implements the "Next Steps" of docs/SPECTRAL_CODEBOOK_ANALYSIS.md: a gap-aware spectral codebook over the 250 8×8 integer braid adjacency matrices in formal/SilverSight/PIST/Matrices250.lean, with an encode/decode round trip and an exact, float-free fingerprint per matrix.

Usage

python3 python/spectral_codebook.py                   # build + report + write JSON
python3 python/spectral_codebook.py --check-manifold  # also run the 278-row corpus
python3 python/spectral_codebook.py --gap-factor 3 --min-support 10 --no-write
python3 python/spectral_codebook.py --cartan-floor    # + Fisher/Δ=17/1792 floor report
python3 tests/test_spectral_codebook.py               # or python3 -m pytest tests/test_spectral_codebook.py

Pure stdlib (fractions.Fraction for exactness). NumPy is used only as an optional fast path for the spectral radius; without it, a Durand–Kerner root finder runs on the exact integer characteristic polynomial (verified to agree with NumPy to 4dp in the test suite).

API: build_codebook() returns a Codebook with encode(matrix) → (codeword, index), decode(codeword, index) → equation_id, codeword_of(equation_id), cluster_table(), and collision_report().

What changed vs. the original concept

1. Exact char-poly fingerprint replaces float λ as primary key. Each matrix gets the 8 exact integer coefficients of det(λI − M), computed by Faddeev–LeVerrier in exact rational arithmetic (integrality of every coefficient is asserted; Cayley–Hamilton p(M) = 0 is checked in integer arithmetic in the tests). This is strictly finer than 4dp λ — see the measured collision numbers below — and involves no floats at all.

2. Power-iteration λ is demoted to a traceability field. The analysis doc's 9 "mid band / edge-of-chaos" values in (0.5, 1) are power-iteration non-convergence artifacts: all 9 matrices have exact spectral radius ρ = 1.0 (peripheral spectra — several eigenvalues of modulus 1, including complex pairs). The C1 "edge-of-chaos" cluster of the analysis doc therefore does not exist; those matrices belong to the ρ = 1 class. spectral_radius in the new JSON is the exact max root modulus of the char poly; the legacy estimate is kept as lambda_power_iteration. Measured: 18 of 250 entries have |λ_pi − ρ| > 1e-3.

3. Dedupe before gap analysis. The corpus has only 238 distinct matrices over 250 ids (11 groups of byte-identical duplicates, 23 ids involved). Gap statistics and cluster support are computed over distinct matrices; duplicates are listed per entry (identical_matrix_ids) and in the collision report.

4. Sample-size guard on gap detection. Gaps > 3× median gap propose boundaries (30 candidates), but a segment must hold ≥ 10 distinct matrices to stand as a cluster; smaller segments merge into the neighbor across the smaller gap. Points isolated above a suppressed gap with < 10 occupancy are flagged sparse_tail: true (outliers, not clusters): the region above λ ≈ 7.66 holds only 10 ids (and only 4 above λ = 11 — {11.68, 16.56, 16.99, 16.99}), far too few to assert cluster structure.

Measured numbers (250 ids / 238 distinct matrices)

Fingerprint uniqueness / collisions

Fingerprint	Unique values	Ids uniquely identified	Collision groups (ids)
λ (exact, 4dp)	179	164 / 250	15 (86 ids)
char poly (exact ℤ⁸)	196	183 / 250	13 (67 ids)
raw matrix bytes	238	227 / 250	11 (23 ids)

• Exact duplicate matrices: 11 groups, 23 ids (12 ids are copies of another id's matrix). No encoder can separate these; encode returns the canonical (first-sorted) entry and the JSON lists the twins.
• Cospectral non-identical groups: 6 — same char poly, different matrices. The largest is the nilpotent class x⁸ (35 ids / 31 distinct matrices, all ρ = 0); the others are -1,0,… (5 ids), 0,0,-1,0,… (6 ids), -1,-1,0,-1,… (3 ids), and two pairs.
• The 4dp-λ count differs from the analysis doc's 190 because the 9 artifact values collapse onto ρ = 1.0 once computed exactly.
• Neither λ nor the char poly is injective — the round-trip decode key is the within-cluster rank index, and all collision classes are explicit in data/spectral_codebook.json (collisions.charpoly_collision_classes, collisions.duplicate_matrix_classes).

Cluster table (gap factor 3.0, min support 10)

Median gap 0.021671 → threshold 0.065013; 30 candidate boundaries, 8 kept: [0.5, 1.0744, 1.4599, 2.7251, 3.3598, 3.7311, 4.3264, 6.1266]; sparse-tail cutoff λ = 7.6568.

Codeword	Ids	Distinct	λ range	Note
C0	35	31	0.0	nilpotent class (char poly x⁸)
C1	20	20	[1.0, 1.000003]	peripheral-unit class (incl. the 9 mis-measured)
C2	13	13	[1.1487, 1.4253]
C3	79	77	[1.4945, 2.6919]	bulk
C4	29	28	[2.7583, 3.2910]
C5	15	14	[3.4287, 3.6970]
C6	22	20	[3.7651, 4.2889]
C7	19	18	[4.3639, 5.8789]
C8	18	17	[6.3743, 16.9915]	10 sparse-tail outliers above 7.6568

The three structurally defensible regions are ρ = 0 (nilpotent), ρ = 1 (peripheral unit), and the ρ > 1 bulk; the finer C2–C8 boundaries are gap-supported but data-driven, and the high tail is outlier territory.

Round trip

decode ∘ encode verified over all 250 equations: bijective on (codeword, index) pairs; encode(matrix) recovers the exact equation id for all 227 ids with unique matrices and a byte-identical matrix for the 23 duplicate-group ids.

278-row manifold (formal/SilverSight/RRC/Q16_16Manifold.lean)

278 rows resolve to 250 unique equation ids — the 28 extra rows are repeated ids reusing matrices already in the codebook (238 distinct matrices, no id lacks a matrix). Rerunning gap quantization on the 278-row corpus reproduces the 250-matrix boundaries exactly: no new gaps, no new clusters, all extra rows fall inside existing clusters.

Φ-corkscrew and Cartan layers (f/Cartan integration batch)

Four layers added on top of the fingerprints, each labelled exact (integer arithmetic, Lean-provable) or decorative (placement/reporting only, carries no information):

1. Integer spiral-index packing — EXACT

pack_spiral_index / unpack_spiral_index with corpus-wide parameters recorded in the JSON header (phi_corkscrew.packing): offset = max|c| over all fingerprint coefficients (164 234 on this corpus), base = 2·offset + 1 (328 469). Digits are offset-encoded (c + offset ∈ [0, base)), so spiral_index = Σ (cᵢ + offset)·baseⁱ is the base-B positional numeral of the fingerprint — injective on fingerprints by uniqueness of positional representation, inverted exactly by unpack_spiral_index, and verified by round trip over all 250 matrices in the test suite. It inherits charpoly's non-injectivity on matrices (cospectral classes share one index), so identity still requires the within-cluster index.

This supersedes the float phinary packing that integration_sprint.py used historically (phinary += c·φ⁻ⁱ then truncation — not injective). The integer path in integration_sprint.phi_corkscrew_index is fixed the same way (offset-encoded digits; its unoffset signed packing collapsed e.g. (-1, 1) with (1, 0) in base 2), but its base is per-call — for corpus-comparable indices use the codebook's recorded (base, offset).

2. f(n) layout — DECORATIVE

f(n) = (√n·cos(nψ), √n·sin(nψ)), ψ = 2π/φ². Injective because 1/φ² is irrational; low-discrepancy by the three-distance theorem; information-neutral (everything decodes from spiral_index alone). Each entry stores layout.radius_sq (= the spiral index, exact int) and layout.angle_frac (fraction of a full turn). Angles are computed in decimal arithmetic at full precision because spiral indices reach ~10⁴⁴ ≫ 2⁵², where float64 retains no fractional bits of n/φ². Verified against VERIFICATION_LOG.md V007: f(20121) = (−137.80079576, −33.64432624). Measured minimum pairwise angular separation across the corpus: ≈ 4.64 × 10⁻⁶ of a turn (positive, as irrationality requires).

3. Cartan ∆-floor quantization (--cartan-floor) — EXACT ∆, reported floor

∆ = 17/1792 exactly (λ_min of the Cartan crossing blocks, CartanConnection.lean:70, docs/cartan_fingerprint.md), adopted as the resolution floor on the Fisher metric of Δ₇: d_F(p, q) = 2·arccos(Σ√(pᵢqᵢ)) with pᵢ = |cᵢ|/Σ|cⱼ| (all-zero fingerprint → uniform, by convention). Measured on this corpus: 13 fingerprint pairs fall below ∆, merging 196 fingerprints into 187 ∆-resolution codewords, vs 9 clusters from the 3×-median-gap λ rule. Both rules are emitted side by side; neither replaces the other.

Caveat, asserted in the tests: the simplex projection destroys sign and scale, so distinct fingerprints can collide on Δ₇ (this corpus has a pair at Fisher distance exactly 0). The Fisher/∆ layer is a similarity metric, not an identity key.

4. Torus-winding saturation fix — EXACT

pist_braid_bridge.TorusWinding now carries a_exact/b_exact (plain ℤ, no clamp) alongside the legacy Q16.16 raws, which silently saturate above 32767 (i.e. for spiral_index > 65535 — and codebook indices reach ~10⁴⁴). torus_to_spiral_index prefers the exact fields, making the round trip lossless for every index (regression-tested at n = 10⁹); legacy windings without exact fields keep the old Q16 behaviour. The matching Lean type in BraidEigensolid.lean needs the same widening (Int fields alongside Q16_16) before this layer can be mirrored formally — noted in the dataclass docstring, Lean file intentionally untouched.

Notes for the Lean side

• Identity layer vs. similarity layer. ClassifyN.hashMatrix is a positional base-5 hash, but corpus entries reach 9, so injectivity is not provable (positional carries can collide). Using base ≥ max_entry + 1 (e.g. 10) makes injectivity trivial to prove. Recommended split: the positional hash (base ≥ 10) is the identity key; the exact char-poly fingerprint is the similarity/clustering key (invariant under permutation-relabelling of strands, unlike the hash).
• Threshold mismatch. ClassifyN.lean defines signalThreshold = 98304 (1.5 in Q16.16) and oberthHighThreshold = 262144 (4.0), but docs/SPECTRAL_CODEBOOK_ANALYSIS.md claims the post-fix thresholds are 0.5/1.0. The code and the analysis doc disagree; this generator matches neither silently — it emits the gap-derived boundaries above and flags the discrepancy here for resolution.

Neon data layer (neon-64gb)

python/spectral_codebook_db.py syncs the codebook into the ENE schema on the neon-64gb Postgres ($NEON_PG, default postgres://postgres:postgres@100.92.88.64:5432/research_stack — same convention as scripts/auto/auto_pipeline.py).

python3 python/spectral_codebook_db.py                  # DRY RUN (default): summary + sample SQL, writes nothing
python3 python/spectral_codebook.py --sync-db           # same dry run from the generator CLI
python3 python/spectral_codebook_db.py --verify-schema  # + READ-ONLY column check against the live DB
python3 python/spectral_codebook_db.py --emit-sql       # write data/spectral_codebook_sync.sql (no DB contact)
python3 python/spectral_codebook_db.py --apply          # actually upsert (psycopg2, or falls back to --emit-sql)

The default is always a dry run; only an explicit --apply writes to the database. --apply has not been run — ene.rrc_predictions is untouched as of this writing. Live-DB access (even read-only --verify-schema) requires the user's go-ahead per the standing "ask before any DB work" rule; schema compatibility was instead verified offline against scripts/auto/ene_schema.sql (tested).

Landing table: ene.rrc_predictions (empty — natural target)

One flat, SQL-typed row per equation (deterministic uuid5 ids, so reruns upsert idempotently):

Column	Value
id	uuid5(namespace, equation_id)
equation_id	e.g. rrc_eq_01ab6e9c32652d06
proxy_pred	gap-aware cluster codeword C0–C8
exact_pred	shape from exact λ under the current ClassifyN thresholds (1.5/4.0 Q16.16, integer semantics mirrored)
matrix_hash	charpoly=<c1..c8>;pos10=<n> — exact char-poly (similarity key) + base-10 positional hash (identity key; injective, entries ≤ 9)
confidence	1.0 for unique char-poly fingerprints; 1/k in a k-way collision class

Dry-run counts: 250 rows — per cluster C0=35, C1=20, C2=13, C3=79, C4=29, C5=15, C6=22, C7=19, C8=18; per shape LogogramProjection=69, SignalShapedRouteCompiler=131, CognitiveLoadField=50; confidence 1.0 for 183 rows, <1.0 for 67.

Spark path

The row shape is deliberately flat so the Spark cluster on neon-64gb (master spark://100.92.88.64:7077, podman spark-worker, JDBC postgresql-42.7.5) can read it directly, the same JDBC pattern the auto-pipeline Spark analysis uses for ene.scars (11 rows) and ene.routes (5 rows):

df = (spark.read.format("jdbc")
      .option("url", "jdbc:postgresql://100.92.88.64:5432/research_stack")
      .option("dbtable", "ene.rrc_predictions")
      .option("user", "postgres").option("password", "postgres")
      .option("driver", "org.postgresql.Driver")
      .load())
df.groupBy("proxy_pred", "exact_pred").count().orderBy("proxy_pred").show()

Table map & staleness findings

Table	Rows	Status
ene.rrc_classifications	120	STALE — all spectral_radius values are 0.3–0.85, i.e. old flat-regime power-iteration artifacts, classified 2026-07-01 05:11 before the exact-eigenvalue correction (this codebook shows real ρ ∈ {0} ∪ {1} ∪ (1, 17]; the corpus has nothing in (0, 1)). Equation ids there are lean:formal/... paths, not rrc_eq_* hashes. Recommend re-classification via this codebook and reconciling the id conventions.
ene.rrc_predictions	0	Empty — landing table for this sync (matrix_hash column already fits the fingerprint).
ene.shape_predictions	100	Existing shape model output; exact_pred here can serve as cross-check.
ene.shape_ground_truth	0	Empty.
ene.eigensolid_snapshots	0	Empty (root_hash, crossing_matrix, sidon_slack, residual_series, …) — future home for full spectral profiles.
ene.braid_strands, ene.receipts, ene.sidon_labels	0	Empty.
ene.scars / ene.routes	11 / 5	Read by the Spark cluster via JDBC (auto-pipeline --spark).

(Row counts and staleness ranges as enumerated by the coordinating agent on 2026-07-01; re-check with --verify-schema + read-only SELECTs before acting on them.)

arxiv-pg citation layer

A separate Postgres runs in the arxiv-pg container on neon-64gb (arxiv DB with pgvector, concept_citations). It has no published port — access is podman-exec only. It is the citation/grounding layer for equation provenance; this sync does not (and cannot) connect to it.

Gremlin graph layer (Cosmos DB mathblob/concepts)

python/spectral_codebook_gremlin.py loads the codebook into the Azure Cosmos DB Gremlin graph used by the Research Stack module/concept loaders (credentials in Research Stack/.env.gremlin, same conventions as load_module_graph.py). Dry-run by default; --apply upserts.

Model: 1 codebook provenance vertex, 9 codeword cluster vertices, 13 fingerprint vertices (cospectral collision classes only), 250 equation vertices (ids verbatim; spiral_index stored as string — it exceeds int64), with has_codeword / in_cluster / shares_fingerprint / within_cartan_floor(fisher_distance) edges. First applied 2026-07-02: 273 vertices + 339 edges, all ok; the 250 equation vertices already existed in the graph and were refreshed in place with exact values.

Spark-side availability of the synced rows was verified the same day by a client-mode PySpark 3.5.5 job (JDK 17 via nix, driver on the tailnet, spark.driver.host set) reading ene.rrc_predictions through JDBC from the spark://100.92.88.64:7077 cluster: 250 rows, C0–C8 and shape counts matching the sync exactly. CouchDB (:5984) remains unresponsive — nothing loaded there.

Output schema (data/spectral_codebook.json)

• header: schema (spectral_codebook_v2), phi_corkscrew (packing base/offset + layout semantics and measured min angular separation), quantization (factor, min support, median gap, kept/candidate/suppressed boundaries, sparse-tail cutoff), clusters (table above), collisions (all counts and explicit collision classes), manifold_278 (when --check-manifold), cartan_floor (when --cartan-floor: sub-Δ Fisher pairs, Δ-resolution codeword count, rule comparison).
• entries[]: equation_id, codeword, index, spectral_radius (exact), lambda_power_iteration (legacy), charpoly (8 exact ints), density, frobenius, trace, spiral_index (exact int packing of charpoly), layout (radius_sq, angle_frac), optional sparse_tail, optional identical_matrix_ids.