diff --git a/README.adoc b/README.adoc deleted file mode 100644 index cc272e6..0000000 --- a/README.adoc +++ /dev/null @@ -1,101 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// SPDX-FileCopyrightText: 2025-2026 Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> - -= git-reticulator -:toc: preamble -:icons: font -:revdate: 2026-06-03 - -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/git-reticulator"] -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: MPL-2.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://img.shields.io/badge/CRG-C-yellow?style=flat-square[CRG C,link="https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades"] - -Semantic-lattice + embedding builder for git repositories — the **symbolic -half of a neuro-symbolic retrieval stack**. It lifts a repo from raw -commits/blobs to a typed, hierarchical, embeddable structure you can *zoom* -into, so an LLM gets the minimal relevant context instead of the whole tree. - -[IMPORTANT] -==== -**Maturity: experimental / early skeleton.** The Rust host is ~237 LOC of -`println!` stubs; the lattice core lives in `src/lattice/affine/*.affine` -(AffineScript) which *cannot compile yet* and, as written, calls Rust crates -AffineScript cannot bind. `git2`/`postgres`/embeddings are feature-gated **off**. -There are **no proofs** — the word "lattice" is not yet earned (it is currently -a typed digraph; see link:PROOF-NEEDS.md[PROOF-NEEDS.md]). Read -`.machine_readable/6a2/STATE.a2ml` for the honest status before relying on -anything here. -==== - -== Why this exists - -Existing git-analysis tools work at the raw commit/blob level. `git-reticulator` -lifts the analysis to a **navigable semantic structure** with two faculties -fused at every node: an *order position* (symbolic) and an *embedding* (neural). -That fusion is the basis for: - -* **Token-bounded retrieval** — `zoom_to_node(node, level)` returns the minimal - relevant sub-structure (Level-of-Detail) for an LLM prompt. -* **Refactoring-impact / blast-radius** — weighted reachability (pgRouting - Dijkstra/A*) over typed edges. -* **Authorship + time queries** — "who owns this concept", "when did it enter - the codebase" (maps onto verisim's provenance + temporal modalities). - -== The neuro-symbolic picture (where this is headed) - -[source] ----- - [git-reticulator] [RAG] [verisim octad] [vcl-ut] - symbolic lattice -> embeddings -> 8-modal substrate -> proof-carrying - + per-node vector similarity (graph=lattice, queries - (LOD zoom) search vector=embeddings, (FRESHNESS, - provenance=authorship) PROVENANCE…) ----- - -The payoff is **proof-carrying retrieval**: neural search *proposes* context; -the symbolic lattice + verisim + vcl-ut *dispose*, so a retrieved snippet can -carry a machine-checked certificate that it really exists at HEAD (FRESHNESS), -was authored by X (PROVENANCE), and isn't hallucinated (EXISTENCE). See -`.machine_readable/6a2/NEUROSYM.a2ml` and `.machine_readable/6a2/PLAYBOOK.a2ml`. - -== Quickstart - -[source,bash] ----- -just build # cargo build (default features; no git2/db/embeddings) - -# CLI binary is `reticulate` (subcommands: build | query | api): -./target/debug/reticulate build --repo /path/to/repo --db postgres://localhost/gr -./target/debug/reticulate query --zoom auth --db postgres://localhost/gr -./target/debug/reticulate --help ----- - -NOTE: these run today but are **stubs** — `build` prints and returns; it does -not yet read the repo or write the DB. - -== Architecture - -* `src/lib.rs`, `src/cli/main.rs`, `src/api/app.rs` — Rust host (CLI + REST shell). -* `src/lattice/affine/*.affine` — intended lattice core (AffineScript; aspirational). -* `benches/`, `tests/` — criterion + smoke/contract tests. -* `.machine_readable/6a2/` — canonical project state, ecosystem, neuro-symbolic design, playbooks. - -== Status & honesty - -* **Licence**: MPL-2.0. -* **Maturity**: research / skeleton. API not stable. -* **Formal status**: zero proofs; see link:PROOF-NEEDS.md[PROOF-NEEDS.md] for the obligations the "lattice" claim incurs. -* **Honest state**: `.machine_readable/6a2/STATE.a2ml` (IMPLEMENTED|SKELETON|ASPIRATIONAL legend). - -== Contributing - -See link:CONTRIBUTING.md[CONTRIBUTING.md]. Commits must be GPG-signed; -conventional-commits required (CHANGELOG generated via `standards` `changelog-reusable.yml`). - -== Companion repositories - -* link:https://github.com/hyperpolymath/affinescript[`affinescript`] — the intended core language (compiles to Wasm). -* link:https://github.com/hyperpolymath/verisimdb[`verisimdb`] — the octad substrate this can feed. -* link:https://github.com/hyperpolymath/vcl-ut[`vcl-ut`] — proof-carrying query layer over verisim. -* link:https://github.com/hyperpolymath/standards[`standards`] — canonical estate standards. -* link:https://github.com/hyperpolymath/k9[`k9`] — metadata-extraction tooling (`k9iser.toml` consumed here). diff --git a/README.md b/README.md new file mode 100644 index 0000000..24a2fde --- /dev/null +++ b/README.md @@ -0,0 +1,124 @@ + + +[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/git-reticulator) +[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license) +[![CRG C](https://img.shields.io/badge/CRG-C-yellow?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) + +Semantic-lattice + embedding builder for git repositories — the +**symbolic half of a neuro-symbolic retrieval stack**. It lifts a repo +from raw commits/blobs to a typed, hierarchical, embeddable structure +you can **zoom** into, so an LLM gets the minimal relevant context +instead of the whole tree. + +> [!IMPORTANT] +> **Maturity: experimental / early skeleton.** The Rust host is ~237 LOC +> of `println!` stubs; the lattice core lives in +> `src/lattice/affine/*.affine` (AffineScript) which **cannot compile +> yet** and, as written, calls Rust crates AffineScript cannot bind. +> `git2`/`postgres`/embeddings are feature-gated **off**. There are **no +> proofs** — the word "lattice" is not yet earned (it is currently a +> typed digraph; see +> PROOF-NEEDS). Read +> `.machine_readable/6a2/STATE.a2ml` for the honest status before +> relying on anything here. + +# Why this exists + +Existing git-analysis tools work at the raw commit/blob level. +`git-reticulator` lifts the analysis to a **navigable semantic +structure** with two faculties fused at every node: an **order +position** (symbolic) and an **embedding** (neural). That fusion is the +basis for: + +- **Token-bounded retrieval** — `zoom_to_node(node,` `level)` returns + the minimal relevant sub-structure (Level-of-Detail) for an LLM + prompt. + +- **Refactoring-impact / blast-radius** — weighted reachability + (pgRouting Dijkstra/A\*) over typed edges. + +- **Authorship + time queries** — "who owns this concept", "when did it + enter the codebase" (maps onto verisim’s provenance + temporal + modalities). + +# The neuro-symbolic picture (where this is headed) + + [git-reticulator] [RAG] [verisim octad] [vcl-ut] + symbolic lattice -> embeddings -> 8-modal substrate -> proof-carrying + + per-node vector similarity (graph=lattice, queries + (LOD zoom) search vector=embeddings, (FRESHNESS, + provenance=authorship) PROVENANCE…) + +The payoff is **proof-carrying retrieval**: neural search **proposes** +context; the symbolic lattice + verisim + vcl-ut **dispose**, so a +retrieved snippet can carry a machine-checked certificate that it really +exists at HEAD (FRESHNESS), was authored by X (PROVENANCE), and isn’t +hallucinated (EXISTENCE). See `.machine_readable/6a2/NEUROSYM.a2ml` and +`.machine_readable/6a2/PLAYBOOK.a2ml`. + +# Quickstart + +```bash +just build # cargo build (default features; no git2/db/embeddings) + +# CLI binary is `reticulate` (subcommands: build | query | api): +./target/debug/reticulate build --repo /path/to/repo --db postgres://localhost/gr +./target/debug/reticulate query --zoom auth --db postgres://localhost/gr +./target/debug/reticulate --help +``` + +> [!NOTE] +> these run today but are **stubs** — `build` prints and returns; it +> does not yet read the repo or write the DB. + +# Architecture + +- `src/lib.rs`, `src/cli/main.rs`, `src/api/app.rs` — Rust host (CLI + + REST shell). + +- `src/lattice/affine/*.affine` — intended lattice core (AffineScript; + aspirational). + +- `benches/`, `tests/` — criterion + smoke/contract tests. + +- `.machine_readable/6a2/` — canonical project state, ecosystem, + neuro-symbolic design, playbooks. + +# Status & honesty + +- **Licence**: MPL-2.0. + +- **Maturity**: research / skeleton. API not stable. + +- **Formal status**: zero proofs; see + PROOF-NEEDS for the + obligations the "lattice" claim incurs. + +- **Honest state**: `.machine_readable/6a2/STATE.a2ml` + (IMPLEMENTED\|SKELETON\|ASPIRATIONAL legend). + +# Contributing + +See CONTRIBUTING. Commits must +be GPG-signed; conventional-commits required (CHANGELOG generated via +`standards` `changelog-reusable.yml`). + +# Companion repositories + +- [`affinescript`](https://github.com/hyperpolymath/affinescript) — the + intended core language (compiles to Wasm). + +- [`verisimdb`](https://github.com/hyperpolymath/verisimdb) — the octad + substrate this can feed. + +- [`vcl-ut`](https://github.com/hyperpolymath/vcl-ut) — proof-carrying + query layer over verisim. + +- [`standards`](https://github.com/hyperpolymath/standards) — canonical + estate standards. + +- [`k9`](https://github.com/hyperpolymath/k9) — metadata-extraction + tooling (`k9iser.toml` consumed here).