|
| 1 | +# SPDX-License-Identifier: MPL-2.0 |
| 2 | +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> |
| 3 | +# |
| 4 | +# NEUROSYM.a2ml — Neurosymbolic integration metadata for git-reticulator |
| 5 | +# |
| 6 | +# This file is NOT a generic template. It records the specific role |
| 7 | +# git-reticulator plays in a neurosymbolic (neuro-symbolic) system and the |
| 8 | +# invariants that make that role trustworthy. Status markers are honest: |
| 9 | +# IMPLEMENTED | SKELETON | ASPIRATIONAL. |
| 10 | + |
| 11 | +[metadata] |
| 12 | +version = "0.2.0" |
| 13 | +last-updated = "2026-06-03" |
| 14 | +status-legend = "IMPLEMENTED = working in Rust on main; SKELETON = stub/println; ASPIRATIONAL = designed in .affine, not yet compilable" |
| 15 | + |
| 16 | +# ════════════════════════════════════════════════════════════════════════════ |
| 17 | +# THESIS |
| 18 | +# ════════════════════════════════════════════════════════════════════════════ |
| 19 | +# git-reticulator is the SYMBOLIC half of a neuro-symbolic retrieval system. |
| 20 | +# It turns an unstructured git repository into a typed, hierarchical, navigable |
| 21 | +# structure (the "lattice"): nodes are semantic keywords at four levels of |
| 22 | +# detail (Module > File > Definition > Block); edges are typed relationships |
| 23 | +# (calls/contains/inherits/depends_on) with weights. The NEURAL half is an |
| 24 | +# embedding attached to each node (models.affine: `Keyword.embedding`). |
| 25 | +# |
| 26 | +# The two halves are fused at the data-model level — every node is |
| 27 | +# simultaneously a lattice element (symbolic, ordered, provable) and a vector |
| 28 | +# (neural, similarity-searchable). That fusion is the whole point. |
| 29 | + |
| 30 | +[thesis] |
| 31 | +symbolic-substrate = "typed keyword lattice + weighted relationship graph (src/lattice/affine/models.affine)" |
| 32 | +neural-layer = "per-node embedding vector (Keyword.embedding: Option<Vec<f64>>)" |
| 33 | +fusion-point = "the Keyword node — one identity carries both an order position and an embedding" |
| 34 | +headline-capability = "proof-carrying retrieval: neural search PROPOSES context, the symbolic lattice + proofs DISPOSE" |
| 35 | + |
| 36 | +# ════════════════════════════════════════════════════════════════════════════ |
| 37 | +# THE FOUR-LAYER NEURO-SYMBOLIC STACK |
| 38 | +# ════════════════════════════════════════════════════════════════════════════ |
| 39 | +# git-reticulator is layer 1. It is designed to feed layers 2-4. Layers 2-4 are |
| 40 | +# OPTIONAL — git-reticulator + a plain vector store is already a useful |
| 41 | +# Graph-RAG. The verisim/vcl-ut layers are what make retrieval *provable*. |
| 42 | + |
| 43 | +[stack.layer-1-reticulator] |
| 44 | +role = "structure extractor + retrieval geometry" |
| 45 | +status = "SKELETON (Rust host 237 LOC of println stubs) + ASPIRATIONAL (.affine core)" |
| 46 | +produces = "lattice nodes (keywords w/ embeddings) + typed weighted edges" |
| 47 | +key-operation = "zoom_to_node(node, level) — level-of-detail subgraph for token-bounded LLM context" |
| 48 | + |
| 49 | +[stack.layer-2-rag] |
| 50 | +role = "neural retrieval over the lattice" |
| 51 | +status = "ASPIRATIONAL (embeddings feature-gated: Cargo.toml `embeddings`/tch off by default)" |
| 52 | +mechanism = "vector similarity finds candidate nodes; lattice edges expand/constrain/explain them (Graph-RAG)" |
| 53 | +token-discipline = "LOD zoom returns the minimal relevant sub-lattice, not the whole repo — bounds prompt size" |
| 54 | + |
| 55 | +[stack.layer-3-verisim] |
| 56 | +role = "the substrate at scale — the octad IS a superset of what reticulator needs" |
| 57 | +status = "EXTERNAL (hyperpolymath/verisimdb); integration ASPIRATIONAL" |
| 58 | +modality-mapping = [ |
| 59 | + "Graph modality <- the reticulator lattice", |
| 60 | + "Vector modality <- the node embeddings", |
| 61 | + "Document modality <- source text of each unit", |
| 62 | + "Temporal modality <- commit history (when a concept entered the codebase)", |
| 63 | + "Provenance modality <- authorship attribution at semantic-unit granularity", |
| 64 | + "Semantic modality <- type/category tags", |
| 65 | +] |
| 66 | +drift-payoff = "verisim drift detection becomes 'has the symbolic lattice drifted from the embedding space / from HEAD?' — i.e. stale-index detection for RAG, for free" |
| 67 | + |
| 68 | +[stack.layer-4-vcl-ut] |
| 69 | +role = "typed, proof-carrying query layer over verisim" |
| 70 | +status = "EXTERNAL (hyperpolymath/vcl-ut — REAL: machine-checked Idris2 corpus, %default total, zero proof-escape)" |
| 71 | +mechanism = "retrieval is a PROPOSITION to a consonance engine with up to 10 levels of type safety + optional PROOF clause" |
| 72 | +differentiator = "ordinary RAG retrieves text and hopes; here a retrieved context item can CARRY a machine-checked certificate" |
| 73 | +proofs-that-matter-for-rag = [ |
| 74 | + "PROVENANCE -> 'this snippet was authored by X at commit Y' (auditable citation)", |
| 75 | + "FRESHNESS -> 'this line still exists at HEAD' (kills stale-context bugs)", |
| 76 | + "EXISTENCE -> 'this entity is real, not hallucinated' (kills fabricated citations)", |
| 77 | + "INTEGRITY -> 'the retrieved text matches the stored hash'", |
| 78 | +] |
| 79 | + |
| 80 | +# ════════════════════════════════════════════════════════════════════════════ |
| 81 | +# CONSISTENCY INVARIANT (the neuro-symbolic seam — the genuinely novel proof target) |
| 82 | +# ════════════════════════════════════════════════════════════════════════════ |
| 83 | +# When neural similarity and symbolic proximity disagree, ONE of them is stale. |
| 84 | +# We do not assume they agree; we make the disagreement observable and either |
| 85 | +# repair it (re-reticulate) or DISCLOSE it. See PROOF-NEEDS.md obligation P6. |
| 86 | + |
| 87 | +[consistency-invariant] |
| 88 | +statement = "for nodes a,b: high embedding-cosine(a,b) without a short lattice path is a DRIFT SIGNAL, not an error" |
| 89 | +action-on-drift = "re-extract (re-reticulate) the affected sub-lattice; or surface as verisim drift event" |
| 90 | +honest-position = "neural and symbolic layers are INDEPENDENT by default; any claimed correlation must be proven or disclosed, never assumed" |
| 91 | + |
| 92 | +# ════════════════════════════════════════════════════════════════════════════ |
| 93 | +# HYPATIA SCANNER CONFIG (estate neurosym CI) |
| 94 | +# ════════════════════════════════════════════════════════════════════════════ |
| 95 | +[hypatia-config] |
| 96 | +scan-enabled = true |
| 97 | +scan-depth = "standard" # quick | standard | deep |
| 98 | +report-format = "logtalk" |
| 99 | + |
| 100 | +[symbolic-rules] |
| 101 | +# Project-specific symbolic rules Hypatia should enforce here. |
| 102 | +rules = [ |
| 103 | + { name = "no-lattice-claim-without-proof", pattern = "lattice", note = "if a module asserts lattice algebra (meet/join), PROOF-NEEDS.md P1 must cover it", severity = "info" }, |
| 104 | + { name = "no-stub-passed-as-done", pattern = "println!\\(\"", note = "build_lattice/query_lattice are SKELETON; do not document them as working", severity = "warning" }, |
| 105 | +] |
| 106 | + |
| 107 | +[neural-config] |
| 108 | +# Embedding model selection is deferred until the `embeddings` feature is wired. |
| 109 | +# candidate-model = "code-embedding (local, deno/rust-hosted) — NOT a cloud call" |
| 110 | +# confidence-threshold = 0.85 |
| 111 | +embedding-source = "ASPIRATIONAL (Cargo feature `embeddings` = tch/PyTorch, off by default)" |
0 commit comments