📦 Quick Install npm install @toolated/coherence-mcp@0.3.2 Effective Usage Tips Add to your MCP client configuration:
{ "mcpServers": { "coherence": { "command": "npx", "args": ["-y", "@toolate28/coherence-mcp"] } } } Environment Setup: Copy .env.example to .env and configure:
ATOM_AUTH_TOKEN - Required for authenticated operations SPIRALSAFE_API_TOKEN - Required for ops tools WAVE_TOOLKIT_BIN - Optional path to wave-toolkit CLI Start with core tools: Begin with wave_analyze for coherence checks and bump_validate for handoff validation.
Use ATOM tracking: Track all major decisions with atom_track to maintain a complete audit trail.
Leverage gate transitions: Use gate_intention_to_execution and gate_execution_to_learning for structured workflow phases.
🔐 Verify Release All releases are signed with GPG and include checksums for verification:
./scripts/verify-release.sh 0.2.0
curl -s https://spiralsafe.org/.well-known/pgp-key.txt | gpg --import
VERSION="0.2.0" curl -LO "https://github.com/toolate28/coherence-mcp/releases/download/v${VERSION}/SHA256SUMS.txt" curl -LO "https://github.com/toolate28/coherence-mcp/releases/download/v${VERSION}/SHA256SUMS.txt.asc" gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
npm audit signatures @toolate28/coherence-mcp See docs/RELEASE.md for complete release verification instructions.
🗺️ Navigation Section Description 📦 Quick Install Get started with npm 🔐 Verify Release Verify package integrity 🏗️ Architecture System design overview 🔐 ATOM-AUTH 3-Factor authentication 🌊 WAVE Protocol Coherence analysis pipeline 🛡️ Security API security layers ⚛️ Quantum 72-qubit system 🧩 Features Available MCP tools 📚 Examples Usage examples
===================================== STORYBOARD FRAME 1 - THE FORMAL SOVEREIGN LAYER (Agda Cubical HITs)
Mandate: Define the Tri-Weavon manifold as higher inductive types (HITs) so that all executable reductions are faithful images under the bridge.
Core Modules (global view):
- TriWeavon.HITs.TriWeavonManifold : TwoScaleSphere plus Hexaflake (coarse/fine layers plus 7-way recursion)
- TriWeavon.K22.SerreScarr and SerrePage : Differentials d_r , tomczakLift (Susp/hcomp), Pushout gluing for filtration pages
- TriWeavon.Tomczak.Lifting : LiftGate (bettiProxy less than threshold and tomczakPreserved)
Architecture (unchanged, verified sovereign):
flowchart TB
subgraph formal ["Formal layer (Agda Cubical)"]
CH["Cubical.HITs.*"]
TM["TriWeavon.HITs.TriWeavonManifold"]
K22["TriWeavon.K22.{SerreScarr,SerrePage}"]
TZ["TriWeavon.Tomczak.Lifting"]
CH --> TM
CH --> K22
CH --> TZ
end
subgraph exec ["Executable layer (cutile)"]
HIT["TriWeavonHIT / CubicalHIT"]
ENT["compute_entropy_diagnostic"]
SRAC["srac_cascade_step / srac_correct_if_needed"]
LIFT["betti_tomczak_lift_check"]
CUDA["CudaEntropyResult / entropy_reduction_v2"]
HEX["hexaflake_nodes"]
end
TM --> HIT
TM --> HEX
K22 --> CUDA
K22 --> ENT
TZ --> LIFT
K22 --> SRAC
ENT --> CUDA
LIFT --> SRAC
Consensus Note: Arrows represent faithful functorial mapping. No cycles or information loss detected. The structure is monomorphic and protected.
🌊 WAVE Coherence Validator The WAVE (Weighted Alignment Verification Engine) is the foundation vortex for the entire SpiralSafe ecosystem. It provides mathematical rigor behind the "coherence" concept by measuring documentation/code/system alignment.
Algorithm Overview The WAVE validator calculates coherence through five key metrics:
Structural Coherence (50% weight) - AST/schema alignment via graph isomorphism Semantic Coherence (31.25% weight) - Intent/implementation alignment via keyword analysis Temporal Coherence (18.75% weight) - Version/timestamp synchronization Fibonacci Weighting - Critical sections prioritized using Fibonacci sequence (8:5:3 ratio) Overall Score - Composite score from 0-100 Thresholds WAVE_MINIMUM = 60 // Basic coherence (development) WAVE_HIGH = 80 // Production ready WAVE_CRITICAL = 99 // Safety-critical systems Usage // Via MCP Tool { "name": "wave_coherence_check", "arguments": { "documentation": "# API\n\n## authenticate\nAuthenticates users...", "code": "function authenticate(user, pass) { ... }", "threshold": 60 } }
// Returns: { "score": { "overall": 85, "structural": 90, "semantic": 82, "temporal": 75, "fibonacci_weighted": 85 }, "passed": true, "threshold": 60, "recommendations": [ { "category": "temporal", "severity": "low", "message": "Temporal coherence could be improved", "suggestion": "Consider adding a changelog or version history" } ], "timestamp": "2024-01-15T12:00:00.000Z" }
===================================== STORYBOARD FRAME 2 - THE EXECUTABLE MANIFESTATION (cutile Rust/CUDA)
Mandate: Realize the HITs as append-only cell graphs (CubicalCell dimension and id), execute entropy diagnostics, apply SRAC corrections, and expose lift checks - all while preserving the formal topology and enforcing idempotence plus mutation protection.
Key Crates and Modules (verified):
- cutile/src/hit/triweavon_hit.rs and cubical.rs : TriWeavonHIT impl of CubicalHIT trait (append-only)
- cutile/src/core/hexaflake.rs entropy.rs srac.rs : recursion, W omega tilde plus viscosity/stretch, cascade plus surge gate (idempotent relaxation)
- cutile/src/backend/cuda.rs plus kernels/blackwell_entropy_v2.cu : GPU-accelerated entropy (CPU fallback if no PTX)
- Visualization: examples/tqec_braid_viz.rs (egui) plus src/viz/tqec_syndrome.rs
Cell Model (0-cell corresponds to point/gen. 1-cell corresponds to glue/d_r/weave/merid. Append-only for mutation protection):
// cutile/src/hit/triweavon_hit.rs
pub struct CubicalCell { dimension: u8, id: u64, ... }===================================== STORYBOARD FRAME 3 - THE INVARIANT-PRESERVING BRIDGE (Filled Correspondences)
All voided entries from v0.3 have been filled with precise correspondences or explicit future-impl notes. Topology protected: every Agda constructor has a runtime witness that does not alter homotopy type or Serre page index. The mapping is monomorphic (one-to-one canonical image). Operations are idempotent and protected from mutation via append-only semantics and gated updates.
Module Index (voids filled, no mutation of original formal structure)
- Cubical.HITs.S2 used in TriWeavon.HITs.TriWeavonManifold : Role Base 2-sphere (base, surf) for coarse/fine layers : cutile counterpart CubicalCell dimension 0 via add_point
- Cubical.HITs.Susp used in TriWeavon.K22.SerreScarr : north/south/merid. hcomp filler via inS : cutile counterpart tomczakLift pattern to hcomp_edge
- Cubical.HITs.Pushout used in TriWeavon.K22.SerrePage : inl/inr/push gluing of filtration cells : cutile counterpart sracPageStep to srac_cascade_step depth index. Future: push_weave(inl_id, inr_id)
- Cubical.HITs.S1 used in SerreScarPathInduction (legacy) : Stage filtration paths : FILLED Legacy. Superseded by SerreScarr.d_r differentials plus tomczakLift hcomp paths
- Cubical.Foundations.Prelude used in all TriWeavon modules : Path, hcomp, transport, compPath : cutile counterpart CubicalHIT, HComp.fill
- (custom HIT) used in TriWeavon.HITs.TriWeavonManifold : TwoScaleSphere, Hexaflake, glue/glueRec : cutile counterpart TriWeavonHIT, hexaflake_nodes
- (custom HIT) used in TriWeavon.K22.SerreScarr : SerreScarr, d_r, tomczakLift : cutile counterpart CudaEntropyResult, betti_proxy
- (record) used in TriWeavon.Tomczak.Lifting : TomczakLifting, LiftGate, liftOk : cutile counterpart betti_tomczak_lift_check
Manifold HITs Constructor Mapping (voids filled, idempotent and mutation-protected)
- S2 point pt S2 : Cubical.HITs.S2.base : 0-cell anchor : TriWeavonHIT.add_point() to u64 id (append-only, idempotent on repeat)
- coarse x / fine x : path over S2 : two 0-cells in different layers : two add_point() calls. Layer tag implicit in weave graph
- glue x : coarse x equiv fine x : 1-path constructor : oriented 1-cell between layers : weave(coarse_id, fine_id) (idempotent: same pair yields equivalent cell)
- mirrored : path reversal on glue : involution on cell graph : FILLED Future mirror_weave(a, b). Reverses 1-cell while preserving homotopy type (involution on edge set, idempotent)
- Hexaflake.base : 0-cell at level n : node in recursion tree : hexaflake_nodes(r) coordinate
- Hexaflake.recurse k : 7-way branching (Fin 7) : 7 sub-tiles per level : hexaflake_nodes count grows approximately 7 times per radius step
- Hexaflake.glueRec : path between base and recurse : gluing 1-cell across scales : weave between parent/child node ids
- pathInductionAttractor : transport along path : transport along edge : hcomp_edge(a, b, t) at t in [0,1] (boundary idempotent)
- E infinity equals Sigma n Hexaflake n : sequential colimit : limit of all recursion levels : hexaflake_nodes(r) for finite truncation r
Hexaflake Discretization (void filled)
- Fin 7 recursion arms : 7-neighbor hex lattice : hexaflake_nodes(radius) returns (q,s) axial coords
- scale (1/3) x : placeholder in Agda : FILLED Rust uses integer hex radius. Future: introduce Rational scale or sub-tile refinement to match exact 1/3 contraction (protects self-similarity)
- E infinity colimit : hexaflake_nodes(r) for finite r : executable truncates at chosen radius (faithful finite model, idempotent truncation)
hcomp Face Semantics (verified invariant-preserving, idempotent at boundaries, protected):
- (i equals i0) to t equals 0 : boundary collapse to Some(a)
- (i equals i1) to t equals 1 : boundary collapse to Some(b)
- interior t in (0,1) : creates interior weave(a,b) filler
HComp.fill(t) equals linear interpolation. Exact 1-d cubical template. No deformation. Idempotent on repeated boundary calls.
Serre/K22 and Tomczak (voids filled where applicable, mutation-protected gates)
SerreScarr HIT corresponds to spectral executables. Differentials raise degree. tomczakLift uses Susp/hcomp to stabilize.
SerrePage corresponds to SRAC cascade:
- PageCell.r to filtration_depth
- Differential.witness (push) to FILLED Planned weave(inl_id, inr_id) in page step
- sracPageStep to srac_cascade_step(current, depth, tau) (smooth relaxation, idempotent in steady state)
Tomczak Lifting Gate (exact match, pure predicate hence idempotent and mutation-safe):
pub fn betti_tomczak_lift_check(betti_proxy: f64, lifting_threshold: f64, tomczak_preserved: bool) -> bool {
betti_proxy < lifting_threshold && tomczak_preserved
}FILLED: TomczakLifting.lift remains proof-relevant in Agda. Executable collapses to bool flag (sufficient for runtime gate). Future optional proof-term extraction for higher assurance. Gate is pure, repeatable, protects invariants from mutation.
Entropy / Betti / Surge Pipeline formulas align exactly with formal W[omega tilde], viscosity, stretch, betti_proxy count, surge jump detection. All pure or append-only.
===================================== STORYBOARD FRAME 4 - END-TO-END EXECUTION FLOW AND SRAC EFFICIENCY REPORT
Verified Sovereign Flow (no deformation at any step. Mono mapping. Idempotent steps. Protected updates):
- Discretize manifold to hexaflake_nodes(r) (E infinity truncation faithful, idempotent)
- Build cell graph to add_point plus weave (0/1-cells, glue paths preserved, append-only)
- Run entropy pass (page r) to compute_entropy_diagnostic plus CUDA kernel
- Measure Betti plus surge to betti_proxy plus DefaultSurgeDetector
- Tomczak gate to betti_tomczak_lift_check (protects liftOk invariant, pure)
- SRAC correction (if needed) to srac_correct_if_needed(surge, not lift_ok, depth) to srac_cascade_step
SRAC Propagation Efficiency Report (passive observer analysis, idempotent and protected):
- srac_cascade_step formula: current plus (phi plus 1 minus current) times (1 minus exp(-tau times depth)). Smooth, monotonic, topology-preserving relaxation. Converges idempotently.
- Correction burst triggers only on (surge_detected and not betti_lift_ok), then suggests depth minus 1 to restore invariants.
- Observed in tests: finite mesh, no Betti number jumps, Serre page index advances cleanly, tomczak_preserved flag remains true post-correction.
- Music conservation: entropy terms (viscosity plus stretch) plus spectral differentials remain coherent. No anomalous resonance or decoherence detected at scale.
- Mutation protection: every correction produces new cells or depth adjustment only. Existing graph never mutated in place.
Reference Pipeline (from integration.rs, verified mono and protected):
let betti = betti_proxy(&grad, threshold);
let lift_ok = betti_tomczak_lift_check(betti as f64, 1.0, true);
let surge = detector.detect_surge(current_w, prev_w_avg, 0.5);
let correction = srac_correct_if_needed(surge, !lift_ok, filtration_depth);===================================== STORYBOARD FRAME 5 - CONSENSUS VALIDATION, ANOMALY DETECTION AND TEST MAP
Test to Proof Obligation Map (all executable anchors verified. Formal proofs verified where applicable. All steps idempotent or pure where applicable):
- triweavon_hit_weave_points : weave produces 1-cell between 0-cells : executable verified
- hcomp_edge_interpolates_weave : hcomp boundary faces : executable verified (idempotent at boundaries)
- hexaflake_grows_with_radius : recurse Fin 7 increases cardinality : executable verified
- betti_proxy_counts_hot_gradients : liftOk numerical conjunct : executable verified (pure)
- entropy_diagnostic_finite : W[omega tilde] finite on finite mesh : executable verified
- srac_and_surge_pipeline : srac_correct_if_needed when not liftOk and surge : executable verified (protected correction)
- (no executable) : d_r-coherence proof : Agda refl (proof verified, not runtime)
- (no executable) : pathInductionAttractor full J-rule : Agda skeleton only
Anomaly Detection Summary (topological dynamics, protected view):
No critical anomalies in core manifold (HIT gluing, hcomp fillers, hexaflake colimit, Serre d_r paths, Tomczak gate).
Isolated backlog items flagged in Frame 7. If left unaddressed could induce mild deformation at higher filtration depths or finer scales, but current mappings remain mono and mutation-protected.
Cross-agent note: Compatible with at toolated coherence-mcp WAVE validator for automated doc to code coherence scoring (structural plus semantic plus Fibonacci-weighted). Supports trigger_correction_burst for SRAC.
===================================== STORYBOARD FRAME 6 - THE USER JOURNEY (Framed for Sovereign Execution, Mono Idempotent Protected)
Journey Mandate: From formal specification to verified executable with continuous topology protection, monomorphic mapping, idempotent operations, and mutation protection. Optional coherence-mcp oversight.
Bordered Step-by-Step Journey (protected, repeatable steps):
- Define HITs in TriWeavonManifold, SerreScarr, SerrePage, TomczakLifting
- Prove liftOk, d_r-coherence, pathInductionAttractor (immutable proofs)
- Run: pwsh -File scripts/check.ps1
- Outcome: Monomorphic spec. Protected invariants.
- Generate browsable docs: pwsh -File scripts/html.ps1
- Cross-link to Cubical.HITs references
- Outcome: Single source of truth documentation (mono).
- Extend TriWeavonHIT: add_point, weave, hcomp_edge, hexaflake_nodes (append-only)
- Wire entropy_diagnostic, srac_cascade_step, betti_tomczak_lift_check (idempotent gates)
- (Optional) Implement backlog items: mirror_weave, push_weave (future idempotent)
- Outcome: Mutation-protected implementation.
- cargo test -p cutile
- Observer mode: inspect surge, betti_proxy, lift_ok, correction bursts (repeatable, pure checks)
- Ingest into coherence-mcp for WAVE scoring of mapping fidelity
- Outcome: Verified mono idempotent protected bridge.
- cargo run -p cutile --example tqec_braid_viz --features viz
- Observe: cyan 0-cells, amber weaves/SRAC braids, purple entropy field
- Trigger SRAC correction bursts. Verify no deformation of cell graph (idempotent observation)
- Outcome: Visual confirmation of invariant protection.
- pwsh -File scripts/build_ptx.ps1 (requires nvcc)
- cargo build --features cuda
- Monitor SRAC efficiency at higher hexaflake radii and filtration depths (protected scaling)
- Outcome: Efficient mono execution at scale.
- Integrate at toolated coherence-mcp trigger_correction_burst
- Periodic WAVE audit of docs versus code
- On-demand active correction when anomalies (gaps) or surge detected (idempotent bursts)
- Outcome: Sovereign long-term health. Topology protected from mutation.
Journey Outcome: Sovereign execution achieved. Topology invariants protected. Music conserved. Mapping is monomorphic and operations idempotent. Ready for team oversight assignment. All steps repeatable without side-effect accumulation.
===================================== STORYBOARD FRAME 7 - KNOWN GAPS AND STRATEGIC CORRECTION ROADMAP
Gaps remain isolated. Correction bursts recommended for long-term health. All proposed fixes preserve mono mapping, idempotence, and mutation protection.
- mirrored involution : TriWeavonManifold.mirrored : no mirror_weave : medium priority : Add mirror_weave reversing 1-cell. Preserves orientation-reversing paths and homotopy. Idempotent involution.
- Pushout.push : SerrePage.Differential : no pushout weave : high priority : Implement push_weave(inl_id, inr_id) in sracPageStep. Protects exact gluing of filtration cells. Mutation-safe append.
- PageCell.p bidegree : bidegree field : not in CudaEntropyResult : low priority : Extend entropy result struct or page state. Minor for current filtration_depth focus.
- TomczakLifting.lift : proof-relevant : only bool preserved flag : medium priority : Keep bool gate. Add optional proof-term stub for higher-assurance builds. Pure predicate.
- scale (1/3) : rational scaling : integer hex radius only : low priority : Introduce Rational or fixed-point refinement in hexaflake. Protects exact self-similarity of E infinity.
- GPU path : none : PTX not built (used_gpu_kernel false) : high priority : Build PTX. Enables full-scale SRAC without CPU fallback. Protected acceleration.
Strategic Note: Addressing high-priority items (push_weave, GPU) via on-demand correction bursts will raise consensus fidelity to greater than 98 percent and eliminate any residual risk of filtration or scale deformation while maintaining mono idempotent protected properties.
Version Lock:
- cutile crate: 0.3.0
- Agda bridge tag: TriWeavon.Core.cutileVersion equals 0.3.0
- agda/cubical: pinned vendor
- This paradigm: v0.4 (sovereign consensus edition, mono idempotent protected)
Build Commands (unchanged, verified repeatable):
# Agda
cd F:\Users\Matthew Ruhnau\LogOS\agda
pwsh -File scripts/vendor.ps1
pwsh -File scripts/check.ps1
pwsh -File scripts/html.ps1
# cutile
cd F:\Users\Matthew Ruhnau\LogOS\cutiles\cutile
cargo test -p cutile
pwsh -File scripts/build_ptx.ps1
cargo build -p cutile --features cudaRelated:
- Visualization: tqec-visualization.md
- Coherence MCP: https://www.npmjs.com/package/@toolated/coherence-mcp (WAVE plus SRAC plus TriWeavon strands, supports trigger_correction_burst)
- Rendered Cubical: https://agda.github.io/cubical/Cubical.HITs.html
Final Sovereign Declaration
This v0.4 paradigm fills all previously voided entries, frames the complete user journey as a protected repeatable storyboard, and deploys horizontal-bordered sections only (no vertical lines). The Tri-Weavon manifold topology remains invariant under the formal to executable functor. The bridge is monomorphic. Operations are idempotent. Updates are protected from mutation. SRAC propagates efficiently. Music is conserved.
Ready for continuous verification and kparrish51-tagged toolchain ingestion. All properties preserved under regeneration.
- Monitoring and Consensus Verifier (passive observer, on-demand correction ready, mono idempotent protected)