Skip to content

EXPLAINME.adoc

Latest commit

 

History

History
77 lines (58 loc) · 3.08 KB

EXPLAINME.adoc

File metadata and controls

77 lines (58 loc) · 3.08 KB
Raw

git-reticulator — EXPLAINME

Developer deep-dive

git-reticulator builds a semantic structure over a git repository and exposes it for token-bounded, (eventually) proof-carrying retrieval. It is the symbolic layer of a neuro-symbolic stack — see .machine_readable/6a2/NEUROSYM.a2ml for the full architecture and PROOF-NEEDS.md for the formal obligations.

Important

Honest status (legend: IMPLEMENTED | SKELETON | ASPIRATIONAL):

  • The Rust host (src/lib.rs, src/cli/main.rs, src/api/app.rs) is SKELETON — build_lattice/query_lattice are println! stubs and the actix routes return canned JSON.

  • The core model (src/lattice/affine/*.affine) is ASPIRATIONAL — AffineScript has no working compiler, and the code calls git2/postgres crates AffineScript cannot bind. A design decision is owed (META ADR-001).

  • No proofs exist. "Lattice" is a typed digraph until PROOF-NEEDS.md P1/P2 are discharged.

How it is meant to work

  1. Ingest (git2) — list files/units in the repo.

  2. Multilevel keyword extraction — emit Keyword nodes at four SemanticLevel`s (Module > File > Definition > Block), each with `parent_id and an optional embedding.

  3. Relationship discovery — typed weighted edges (calls, contains, inherits, depends_on).

  4. Persist — Postgres + pgr_createTopology for Dijkstra/A* reachability.

  5. Retrieve — zoom_to_node(node, level) returns the minimal relevant sub-structure for an LLM (the Level-of-Detail discipline that justifies the project over git log).

Map: file → what it proves/does

Path Role

src/cli/main.rs

reticulate CLI (clap): build / query / api subcommands. IMPLEMENTED shell, SKELETON behaviour.

src/api/app.rs

actix-web REST shell: POST /build, GET /zoom/{id}, GET /health. SKELETON (canned responses).

src/lib.rs

Host library bridging CLI/API to the (future) core. SKELETON (println stubs) + the 27 smoke tests.

src/lattice/affine/models.affine

Data model: SemanticLevel, Keyword (with embedding), Relationship, Lattice. ASPIRATIONAL.

src/lattice/affine/lattice.affine

build_lattice + zoom_to_node (LOD). ASPIRATIONAL.

src/lattice/affine/storage.affine

Postgres + pgRouting persistence. ASPIRATIONAL.

PROOF-NEEDS.md

The obligations that turn "lattice" from a claim into a theorem (P1–P7).

.machine_readable/6a2/

Canonical state, architecture decisions, ecosystem, neuro-symbolic design, playbooks.

If you are here to make it real

The highest-leverage first moves (from .machine_readable/6a2/STATE.a2ml):

  1. Decide the core-language question (Rust-native core now, vs. wait for AffineScript).

  2. Wire git2 behind the default feature so reticulate build reads a real repo.

  3. SCC-condense + define the order, then discharge PROOF-NEEDS.md P2→P1 to earn "lattice".

  4. Replace a println! with a real lattice build + a test asserting a property.