allaun/SilverSight
1
0
Fork 0
mirror of https://github.com/allaunthefox/SilverSight.git synced 2026-07-30 17:16:16 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
SilverSight/docs/RRC_REFACTOR_READINESS.md
allaun 4490dc28a7 feat(rrc): bare-minimum RRC refactor into SilverSight 
- Move canonical FixedPoint to Core/SilverSight/FixedPoint.lean
- Add SilverSightRRC library: RRC logogram gates, receipt bridge, AVM ISA
- Add AVMIsa.Emit as the sole top-level JSON output boundary
- Add rrc-emit-fixture executable and Python I/O shims
- Update AGENTS.md, glossary, project map, and build baseline

Build: 2981 jobs, 0 errors (lake build)
2026-06-21 09:08:48 -05:00

4.4 KiB
Raw Blame History

RRC Refactor Status

Date: 2026-06-21 Goal: Port the Research-Stack RRC (Receipt Routing Classifier) decision surface into SilverSight.

Status

Bare-minimum refactor is complete and building.

  • ✅ RRC logogram projection and admission gates
  • ✅ Receipt core with SilverSight.Core receipt bridge
  • ✅ RRC alignment gate (determineAlignment) + 6 canonical fixture rows
  • ✅ AVM ISA (Types, Value, Instr, State, Step, Run)
  • ✅ AVM canary bundle + top-level JSON emitter (AVMIsa.Emit)
  • ✅ AVM-stamped RRC fixture corpus emitter (emitFixtureCorpus)
  • ✅ Python raw-feature shims (pist_matrix_builder.py, validate_rrc_predictions.py)
  • ✅ Executable rrc-emit-fixture to extract the JSON bundle
  • ✅ Glossary entries for all new domain terms

Location

The RRC layer lives under formal/SilverSight/ (Lake module namespace SilverSight.*). User-facing symlinks are in formal/RRCLib/.

File Module Role
formal/SilverSight/RRCLogogramProjection.lean SilverSight.RRCLogogramProjection RRCShape, WitnessStatus, projection/merge gates
formal/SilverSight/ReceiptCore.lean SilverSight.ReceiptCore ReceiptKind, Receipt, ledger, core bridge
formal/SilverSight/RRC/Emit.lean SilverSight.RRC.Emit Alignment gate, FixtureRow, JSON emitter
formal/SilverSight/AVMIsa/Types.lean SilverSight.AVMIsa AvmTy closed-world type universe
formal/SilverSight/AVMIsa/Value.lean SilverSight.AVMIsa AvmVal typed values
formal/SilverSight/AVMIsa/Instr.lean SilverSight.AVMIsa Instr / Prim opcodes
formal/SilverSight/AVMIsa/State.lean SilverSight.AVMIsa AVM execution state
formal/SilverSight/AVMIsa/Step.lean SilverSight.AVMIsa step transition function
formal/SilverSight/AVMIsa/Run.lean SilverSight.AVMIsa Fuel-bounded run
formal/SilverSight/AVMIsa/Emit.lean SilverSight.AVMIsa.Emit Top-level JSON output boundary

Key architectural decisions

  1. Canonical fixed point moved to Core.

    • Core/SilverSight/FixedPoint.lean defines SilverSight.FixedPoint.Q16_16 / Q0_16.
    • formal/CoreFormalism/FixedPoint.lean is now a compatibility shim.
    • This lets SilverSightRRC import only Core/ + Mathlib, preserving the library method.

  2. Two receipt types with a bridge.

    • Core/SilverSightCore.lean keeps the external Receipt boundary.
    • formal/SilverSight/ReceiptCore.lean adds the internal validation receipt model and a toSilverSightReceipt bridge.

  3. Core AVM stays conceptual; concrete ISA lives in RRC.

    • Core/SilverSightCore.lean defines the abstract δ, Instruction, AVMState contract.
    • formal/SilverSight/AVMIsa/ implements the closed-world typed ISA.

Build commands

# All libraries
lake build

# Individual libraries
lake build SilverSightCore
lake build SilverSightFormal
lake build SilverSightRRC

# Emit and validate the fixture corpus JSON
lake build rrc-emit-fixture
.lake/build/bin/rrc-emit-fixture > /tmp/rrc_fixture_emitted.json
python3 python/validate_rrc_predictions.py /tmp/rrc_fixture_emitted.json

Verification results

Gate Result
lake build ✅ 2981 jobs, 0 errors
lake build SilverSightCore ✅ 3132 jobs, 0 errors
lake build SilverSightFormal ✅ 3132 jobs, 0 errors
lake build SilverSightRRC ✅ 2992 jobs, 0 errors
lake build rrc-emit-fixture ✅ green
python3 -m py_compile python/pist_matrix_builder.py python/validate_rrc_predictions.py tests/test_q16_canonical.py .github/scripts/check_doc_sync.py .github/scripts/glossary_lint.py ✅ green
python3 .github/scripts/glossary_lint.py ✅ no warnings
python3 .github/scripts/check_doc_sync.py ✅ OK
rrc-emit-fixture | validate_rrc_predictions.py ✅ OK: 6 rows
pytest tests/test_q16_canonical.py ⚠️ not run — pytest not installed in this environment

Out of scope (future work)

  • Full 250-equation Corpus250 (requires PIST.Classify, PIST.Matrices250, source JSON).
  • RRC.ReceiptDensity, RRC.PolyFactorIdentity, RRC.EntropyCandidates.
  • python/build_corpus250.py generator for the full corpus.
  • PIST classifier surface to populate pistProxyLabel / pistExactLabel from real matrices.

References

  • Research-Stack sources: 0-Core-Formalism/lean/Semantics/Semantics/{RRC,AVMIsa,RRCLogogramProjection,ReceiptCore}.lean
  • SilverSight project map: docs/PROJECT_MAP.md