diff --git a/.github/workflows/casket-pages.yml b/.github/workflows/casket-pages.yml index 29e7dd2..c252302 100644 --- a/.github/workflows/casket-pages.yml +++ b/.github/workflows/casket-pages.yml @@ -18,6 +18,7 @@ concurrency: jobs: build: runs-on: ubuntu-latest + timeout-minutes: 10 steps: - name: Checkout uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4 @@ -36,6 +37,7 @@ jobs: url: ${{ steps.deployment.outputs.page_url }} runs-on: ubuntu-latest needs: build + timeout-minutes: 10 steps: - name: Deploy to GitHub Pages id: deployment diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml new file mode 100644 index 0000000..2083ca6 --- /dev/null +++ b/.github/workflows/mirror.yml @@ -0,0 +1,15 @@ +# SPDX-License-Identifier: MPL-2.0 +name: Mirror to Git Forges + +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +jobs: + mirror: + uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@e6b2884722350515934d443daf23442f2195796f + secrets: inherit diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml new file mode 100644 index 0000000..410f84b --- /dev/null +++ b/.github/workflows/scorecard.yml @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: MPL-2.0 +name: Scorecards supply-chain security + +on: + branch_protection_rule: + schedule: + - cron: '23 4 * * 1' + push: + branches: [main] + +# Workflow-level permissions are read-only. The job that calls the reusable +# upgrades to the writes `ossf/scorecard-action` requires. Job-level +# permissions REPLACE workflow-level for that job, so `contents: read` here +# plus the writes below yields the correct effective set and avoids the +# `read-all` startup_failure seen estate-wide. Matches the canonical caller in +# hyperpolymath/standards/.github/workflows/scorecard-reusable.yml. +permissions: + contents: read + +jobs: + analysis: + permissions: + security-events: write + id-token: write + uses: hyperpolymath/standards/.github/workflows/scorecard-reusable.yml@e03686486e11b662834d7090dffae54c3e96fd59 + secrets: inherit diff --git a/.github/workflows/secret-scanner.yml b/.github/workflows/secret-scanner.yml new file mode 100644 index 0000000..097d2af --- /dev/null +++ b/.github/workflows/secret-scanner.yml @@ -0,0 +1,19 @@ +# SPDX-License-Identifier: MPL-2.0 +name: Secret Scanner + +on: + pull_request: + push: + branches: [main] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + scan: + uses: hyperpolymath/standards/.github/workflows/secret-scanner-reusable.yml@3e4bd4c93911750727e2e4c66dff859e00079da0 + secrets: inherit diff --git a/.machine_readable/6a2/AGENTIC.a2ml b/.machine_readable/6a2/AGENTIC.a2ml new file mode 100644 index 0000000..b23e2c2 --- /dev/null +++ b/.machine_readable/6a2/AGENTIC.a2ml @@ -0,0 +1,48 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# AGENTIC.a2ml — AI agent interaction patterns for git-reticulator. + +[metadata] +version = "0.2.0" +last-updated = "2026-06-03" + +[agent-permissions] +can-edit-source = true +can-edit-tests = true +can-edit-docs = true +can-edit-config = true +can-create-files = true + +[agent-constraints] +rules = [ + "HONESTY FIRST: never document a SKELETON/println stub as a working feature. Use the NEUROSYM status legend (IMPLEMENTED|SKELETON|ASPIRATIONAL).", + "Do not assert 'lattice' algebra (meet/join) anywhere unless PROOF-NEEDS.md P1 is discharged — otherwise say 'typed graph/DAG'.", + "Never reintroduce template placeholders ({{...}}, [YOUR-REPO-NAME]).", + "Never commit secrets; SPDX header on every file; MPL-2.0 only.", + "State files live in .machine_readable/6a2/ ONLY (not repo root, not .machine_readable/ root).", + "Banned languages per estate policy (TypeScript, Python (non-Salt), Go, Node/npm/Bun).", +] + +# ════════════════════════════════════════════════════════════════════════════ +# THE AGENT-FACING ROLE OF THIS REPO +# ════════════════════════════════════════════════════════════════════════════ +# git-reticulator exists largely TO SERVE AI agents: it is a RAG context +# provider. Agents are both maintainers of, and consumers of, this repo. + +[agent-as-consumer] +primary-call = "zoom_to_node(node, level) -> token-bounded sub-lattice for the prompt" +token-discipline = "request the SMALLEST level that answers the question; widen only on miss" +trust-model = "when layers 3-4 are present, prefer context that carries FRESHNESS/PROVENANCE proofs; drop context that fails them rather than showing it" + +[maintenance-integrity] +fail-closed = true +require-evidence-per-step = true +allow-silent-skip = false +require-rerun-after-fix = true +release-claim-requires-hard-pass = true + +[automation-hooks] +on-enter = "Read 0-AI-MANIFEST.a2ml, then .machine_readable/6a2/STATE.a2ml, then PROOF-NEEDS.md" +on-exit = "Update 6a2/STATE.a2ml [honest-status] + [critical-next-actions] with session outcomes" +on-commit = "just must-check && just trust-verify" diff --git a/.machine_readable/6a2/ECOSYSTEM.a2ml b/.machine_readable/6a2/ECOSYSTEM.a2ml new file mode 100644 index 0000000..e419081 --- /dev/null +++ b/.machine_readable/6a2/ECOSYSTEM.a2ml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# ECOSYSTEM.a2ml — git-reticulator's position and relationships. + +[metadata] +version = "0.2.0" +last-updated = "2026-06-03" + +[project] +name = "git-reticulator" +purpose = "Symbolic-lattice + embedding extractor for git repos; layer 1 of the neuro-symbolic retrieval stack." +role = "library + cli (structure extractor / RAG context provider)" + +[position-in-ecosystem] +tier = "2" # 1 = foundational language/proof; 2 = tooling/application; infrastructure = scaffolding +neuro-symbolic-layer = 1 + +# relationship types: dependency, dependent, sibling, substrate, proof-layer, +# potential-consumer, inspiration +[[related-projects.project]] +name = "affinescript" +relationship = "core-language + sibling" +contract = "intended implementation language of the lattice core (src/lattice/affine/*.affine); compiles to Wasm. NOTE: not yet a working compiler, and the current .affine calls Rust crates it cannot bind." + +[[related-projects.project]] +name = "verisimdb" +relationship = "substrate (downstream)" +contract = "the octad (8 modalities) is a superset of reticulator's needs: Graph<-lattice, Vector<-embeddings, Document<-source, Temporal<-history, Provenance<-authorship, Semantic<-type tags. reticulator is, in effect, a specialised ingester producing verisim octads." + +[[related-projects.project]] +name = "vcl-ut" +relationship = "proof-layer (downstream)" +contract = "typed, proof-carrying query language over verisim. Turns reticulator retrieval into PROPOSITIONS carrying PROVENANCE/FRESHNESS/EXISTENCE certificates — the basis of proof-carrying retrieval (NEUROSYM stack layer 4)." + +[[related-projects.project]] +name = "k9" +relationship = "dependency (metadata tooling)" +contract = "k9iser.toml is consumed here; K9 contracts machine-check MUST constraints." + +[[related-projects.project]] +name = "hypatia / panic-attack" +relationship = "potential-consumer" +contract = "security/quality scanners; PB-4 feeds them a reachable-set (blast radius) from the lattice. Hypatia also scans this repo (hypatia-scan.yml)." + +[[related-projects.project]] +name = "standards" +relationship = "sibling-standard" +contract = "estate standards, CRG grading, changelog-reusable.yml, contractile/RSR conventions." + +[[related-projects.project]] +name = "LLM / RAG agents" +relationship = "primary-consumer" +contract = "consume zoom_to_node sub-lattices as token-bounded, (eventually) proof-carrying context." + +[integration-points] +# system, direction, protocol +points = [ + { system = "verisimdb-data", direction = "outbound", protocol = "git-backed flat-file / repository_dispatch (PB-5)" }, + { system = "postgres+pgRouting", direction = "outbound", protocol = "SQL (ASPIRATIONAL, feature-gated)" }, + { system = "REST consumers", direction = "inbound", protocol = "actix-web /build /zoom /health (stub responses today)" }, +] diff --git a/.machine_readable/6a2/META.a2ml b/.machine_readable/6a2/META.a2ml new file mode 100644 index 0000000..cc23def --- /dev/null +++ b/.machine_readable/6a2/META.a2ml @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# META.a2ml — Architecture decisions and design rationale for git-reticulator. + +[metadata] +version = "0.2.0" +last-updated = "2026-06-03" + +[project-info] +type = "library + cli" # library (git_reticulator) + binary (reticulate) +languages = ["rust", "affinescript"] +license = "MPL-2.0" +author = "Jonathan D.A. Jewell (hyperpolymath)" + +[development-practices] +build-tool = "just" +container-runtime = "podman" +ci-platform = "github-actions" +package-manager = "cargo" # guix.scm / flake.nix also present for reproducible shells + +# ════════════════════════════════════════════════════════════════════════════ +# ARCHITECTURE DECISIONS (ADRs) — status: proposed | accepted | superseded | rejected +# ════════════════════════════════════════════════════════════════════════════ + +[[adr]] +id = "ADR-001" +title = "Rust host, AffineScript core" +status = "accepted-but-under-review" +date = "2026-04" +decision = "CLI/REST/IO in Rust; lattice algorithms in AffineScript (.affine) for affine-typed safe traversal." +consequence = "Today the core cannot compile (no AffineScript compiler) and is written against Rust crates AffineScript cannot bind. STATE.honest-status flags this; ADR may be superseded by a Rust-native core." + +[[adr]] +id = "ADR-002" +title = "Level-of-Detail (LOD) lattice over four semantic levels" +status = "accepted" +date = "2026-04" +decision = "Nodes carry a SemanticLevel (Module>File>Definition>Block) and a parent_id, so zoom_to_node can return a token-bounded sub-lattice." +rationale = "The product is a RETRIEVAL GEOMETRY for LLMs — minimal relevant context, not a full dump. This is the feature that justifies the project over `git log`." + +[[adr]] +id = "ADR-003" +title = "Per-node embedding (neuro-symbolic fusion at the data model)" +status = "accepted" +date = "2026-04" +decision = "Keyword carries an optional embedding vector alongside its order position." +rationale = "One identity = one lattice element + one vector. This is the seam where symbolic and neural meet (see NEUROSYM.a2ml)." + +[[adr]] +id = "ADR-004" +title = "PostgreSQL + pgRouting for persistence and pathfinding" +status = "accepted" +date = "2026-04" +decision = "Store nodes/edges in Postgres; use pgRouting (Dijkstra/A*) for reachability and blast-radius queries." +rationale = "Weighted reachability is a first-class query (refactoring impact, security blast-radius — PLAYBOOK PB-4). pgRouting gives it for free." +caveat = "feature-gated off; not yet wired." + +[[adr]] +id = "ADR-005" +title = "'Lattice' must be earned, not asserted" +status = "accepted" +date = "2026-06-03" +decision = "The structure is currently a typed weighted DAG/digraph (TOPOLOGY even notes cycle detection). To call it a lattice we must (a) SCC-condense to a DAG, (b) define a partial order, (c) prove meet/join exist + the lattice laws." +rationale = "Honesty + the formal-methods estate norm (cf. vcl-ut). Tracked in PROOF-NEEDS.md." + +[design-rationale] +why-this-exists = "Existing git tools work at raw commit/blob level; git-reticulator lifts analysis to a semantic, navigable, embeddable structure suited to feeding LLMs cheaply and provably." +positioning = "layer 1 of a four-layer neuro-symbolic stack (reticulator -> RAG -> verisim octad -> vcl-ut proofs); see NEUROSYM.a2ml" + +[maintenance-axes] +scoping-first = true +axis-1 = "must > intend > like" +axis-2 = "corrective > adaptive > perfective" +axis-3 = "systems > compliance > effects" diff --git a/.machine_readable/6a2/NEUROSYM.a2ml b/.machine_readable/6a2/NEUROSYM.a2ml new file mode 100644 index 0000000..8ba727b --- /dev/null +++ b/.machine_readable/6a2/NEUROSYM.a2ml @@ -0,0 +1,111 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# NEUROSYM.a2ml — Neurosymbolic integration metadata for git-reticulator +# +# This file is NOT a generic template. It records the specific role +# git-reticulator plays in a neurosymbolic (neuro-symbolic) system and the +# invariants that make that role trustworthy. Status markers are honest: +# IMPLEMENTED | SKELETON | ASPIRATIONAL. + +[metadata] +version = "0.2.0" +last-updated = "2026-06-03" +status-legend = "IMPLEMENTED = working in Rust on main; SKELETON = stub/println; ASPIRATIONAL = designed in .affine, not yet compilable" + +# ════════════════════════════════════════════════════════════════════════════ +# THESIS +# ════════════════════════════════════════════════════════════════════════════ +# git-reticulator is the SYMBOLIC half of a neuro-symbolic retrieval system. +# It turns an unstructured git repository into a typed, hierarchical, navigable +# structure (the "lattice"): nodes are semantic keywords at four levels of +# detail (Module > File > Definition > Block); edges are typed relationships +# (calls/contains/inherits/depends_on) with weights. The NEURAL half is an +# embedding attached to each node (models.affine: `Keyword.embedding`). +# +# The two halves are fused at the data-model level — every node is +# simultaneously a lattice element (symbolic, ordered, provable) and a vector +# (neural, similarity-searchable). That fusion is the whole point. + +[thesis] +symbolic-substrate = "typed keyword lattice + weighted relationship graph (src/lattice/affine/models.affine)" +neural-layer = "per-node embedding vector (Keyword.embedding: Option>)" +fusion-point = "the Keyword node — one identity carries both an order position and an embedding" +headline-capability = "proof-carrying retrieval: neural search PROPOSES context, the symbolic lattice + proofs DISPOSE" + +# ════════════════════════════════════════════════════════════════════════════ +# THE FOUR-LAYER NEURO-SYMBOLIC STACK +# ════════════════════════════════════════════════════════════════════════════ +# git-reticulator is layer 1. It is designed to feed layers 2-4. Layers 2-4 are +# OPTIONAL — git-reticulator + a plain vector store is already a useful +# Graph-RAG. The verisim/vcl-ut layers are what make retrieval *provable*. + +[stack.layer-1-reticulator] +role = "structure extractor + retrieval geometry" +status = "SKELETON (Rust host 237 LOC of println stubs) + ASPIRATIONAL (.affine core)" +produces = "lattice nodes (keywords w/ embeddings) + typed weighted edges" +key-operation = "zoom_to_node(node, level) — level-of-detail subgraph for token-bounded LLM context" + +[stack.layer-2-rag] +role = "neural retrieval over the lattice" +status = "ASPIRATIONAL (embeddings feature-gated: Cargo.toml `embeddings`/tch off by default)" +mechanism = "vector similarity finds candidate nodes; lattice edges expand/constrain/explain them (Graph-RAG)" +token-discipline = "LOD zoom returns the minimal relevant sub-lattice, not the whole repo — bounds prompt size" + +[stack.layer-3-verisim] +role = "the substrate at scale — the octad IS a superset of what reticulator needs" +status = "EXTERNAL (hyperpolymath/verisimdb); integration ASPIRATIONAL" +modality-mapping = [ + "Graph modality <- the reticulator lattice", + "Vector modality <- the node embeddings", + "Document modality <- source text of each unit", + "Temporal modality <- commit history (when a concept entered the codebase)", + "Provenance modality <- authorship attribution at semantic-unit granularity", + "Semantic modality <- type/category tags", +] +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" + +[stack.layer-4-vcl-ut] +role = "typed, proof-carrying query layer over verisim" +status = "EXTERNAL (hyperpolymath/vcl-ut — REAL: machine-checked Idris2 corpus, %default total, zero proof-escape)" +mechanism = "retrieval is a PROPOSITION to a consonance engine with up to 10 levels of type safety + optional PROOF clause" +differentiator = "ordinary RAG retrieves text and hopes; here a retrieved context item can CARRY a machine-checked certificate" +proofs-that-matter-for-rag = [ + "PROVENANCE -> 'this snippet was authored by X at commit Y' (auditable citation)", + "FRESHNESS -> 'this line still exists at HEAD' (kills stale-context bugs)", + "EXISTENCE -> 'this entity is real, not hallucinated' (kills fabricated citations)", + "INTEGRITY -> 'the retrieved text matches the stored hash'", +] + +# ════════════════════════════════════════════════════════════════════════════ +# CONSISTENCY INVARIANT (the neuro-symbolic seam — the genuinely novel proof target) +# ════════════════════════════════════════════════════════════════════════════ +# When neural similarity and symbolic proximity disagree, ONE of them is stale. +# We do not assume they agree; we make the disagreement observable and either +# repair it (re-reticulate) or DISCLOSE it. See PROOF-NEEDS.md obligation P6. + +[consistency-invariant] +statement = "for nodes a,b: high embedding-cosine(a,b) without a short lattice path is a DRIFT SIGNAL, not an error" +action-on-drift = "re-extract (re-reticulate) the affected sub-lattice; or surface as verisim drift event" +honest-position = "neural and symbolic layers are INDEPENDENT by default; any claimed correlation must be proven or disclosed, never assumed" + +# ════════════════════════════════════════════════════════════════════════════ +# HYPATIA SCANNER CONFIG (estate neurosym CI) +# ════════════════════════════════════════════════════════════════════════════ +[hypatia-config] +scan-enabled = true +scan-depth = "standard" # quick | standard | deep +report-format = "logtalk" + +[symbolic-rules] +# Project-specific symbolic rules Hypatia should enforce here. +rules = [ + { 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" }, + { name = "no-stub-passed-as-done", pattern = "println!\\(\"", note = "build_lattice/query_lattice are SKELETON; do not document them as working", severity = "warning" }, +] + +[neural-config] +# Embedding model selection is deferred until the `embeddings` feature is wired. +# candidate-model = "code-embedding (local, deno/rust-hosted) — NOT a cloud call" +# confidence-threshold = 0.85 +embedding-source = "ASPIRATIONAL (Cargo feature `embeddings` = tch/PyTorch, off by default)" diff --git a/.machine_readable/6a2/PLAYBOOK.a2ml b/.machine_readable/6a2/PLAYBOOK.a2ml new file mode 100644 index 0000000..d47c717 --- /dev/null +++ b/.machine_readable/6a2/PLAYBOOK.a2ml @@ -0,0 +1,118 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# PLAYBOOK.a2ml — Operational playbook for git-reticulator +# +# Two parts: +# 1. NEURO-SYMBOLIC PLAYBOOKS — the use-cases this repo exists to enable. +# Each is marked with the layers it needs (see NEUROSYM.a2ml stack). +# 2. OPS RUNBOOK — build/test/release/incident procedures (concrete, today). + +[metadata] +version = "0.2.0" +last-updated = "2026-06-03" + +# ════════════════════════════════════════════════════════════════════════════ +# PART 1 — NEURO-SYMBOLIC PLAYBOOKS +# ════════════════════════════════════════════════════════════════════════════ +# Status: all five are ASPIRATIONAL until layer-1 (.affine core) compiles and +# git2 is wired. They are listed so design work has a target, not because they +# run today. + +[[playbook]] +id = "PB-1" +name = "Repo archaeology / onboarding" +question = "When did this concept enter the codebase, and who owns it?" +needs-layers = ["reticulator", "verisim(temporal+provenance)", "vcl-ut(PROVENANCE proof)"] +flow = [ + "reticulate the repo -> lattice with temporal + provenance modalities populated", + "vcl-ut query: INSPECT concept WITH temporal trajectory PROOF PROVENANCE", + "LLM explains the history with citations that each carry a provenance certificate", +] +value = "an onboarding dev (or an auditor reconstructing a decision) gets answers that are checkable, not vibes" + +[[playbook]] +id = "PB-2" +name = "Proof-carrying Graph-RAG code assistant" +question = "Answer my question about this codebase without hallucinating or citing dead code." +needs-layers = ["reticulator(LOD zoom)", "rag(embeddings)", "vcl-ut(FRESHNESS+EXISTENCE proof)"] +flow = [ + "embedding search finds candidate nodes", + "zoom_to_node bounds the context to the relevant sub-lattice (token budget)", + "vcl-ut attaches FRESHNESS proof: every cited line provably exists at HEAD", + "assistant answers; any context that fails FRESHNESS is dropped, not shown", +] +value = "neutralises RAG's two killers — hallucinated citations and stale context — the things that block RAG in regulated domains" +this-is-the-flagship = true + +[[playbook]] +id = "PB-3" +name = "Drift / staleness sentinel" +question = "Has the index gone stale relative to the code?" +needs-layers = ["reticulator", "verisim(drift detection + self-normalization)"] +flow = [ + "verisim watches (lattice <-> embeddings <-> current HEAD)", + "code changes but index lags -> drift event fires", + "self-normalization re-runs reticulate on the affected sub-lattice only", +] +value = "keeps every downstream RAG honest over time; maps directly onto verisim's existing drift machinery" + +[[playbook]] +id = "PB-4" +name = "Refactoring-impact / security blast-radius" +question = "What is reachable from this function / this vulnerability?" +needs-layers = ["reticulator(pgRouting Dijkstra/A* over weighted edges)"] +flow = [ + "pgr_createTopology builds the routable graph (storage.affine already calls it)", + "shortest/all-paths from the changed (or vulnerable) node", + "feed the reachable set to Hypatia / panic-attack for targeted scanning", +] +value = "explainable impact analysis; ties into the estate's existing security scanners" + +[[playbook]] +id = "PB-5" +name = "Cross-repo estate intelligence" +question = "Where else in the ~290 repos does this pattern live?" +needs-layers = ["reticulator(batch)", "verisim(verisimdb-data flat-file store)"] +flow = [ + "run reticulate over each repo in CI", + "push lattices to verisimdb-data (the git-backed store already designed in verisimdb)", + "query the union for 'this pattern, with provenance, across the estate'", +] +value = "dovetails with verisimdb's documented GitHub-CI flat-file architecture" + +# ════════════════════════════════════════════════════════════════════════════ +# PART 2 — OPS RUNBOOK (concrete, today) +# ════════════════════════════════════════════════════════════════════════════ + +[deployment] +method = "library + CLI binary" # not a long-running service yet +target = "binary" # `reticulate` (src/cli/main.rs) +notes = "the actix `api` subcommand exists but serves stub responses; do not deploy as a service yet" + +[build] +commands = [ + "just build # cargo build (default features only — no git2/postgres/tch)", + "just test # cargo test (27 smoke/contract tests over the Rust host)", + "cargo build --features full # ASPIRATIONAL: pulls git2/postgres/tch/affinescript — currently will not resolve (affinescript path dep absent)", +] + +[incident-response] +steps = [ + "1. Read .machine_readable/6a2/STATE.a2ml for current honest status", + "2. Review recent commits and CI (rust-ci.yml, governance.yml, hypatia-scan.yml)", + "3. just doctor # toolchain health", + "4. just must-check && just trust-verify # contractile gates", +] + +[release-process] +steps = [ + "1. Update version + last-updated in 6a2/STATE.a2ml and 6a2/META.a2ml", + "2. just must-check && just trust-verify", + "3. just assail # panic-attack scan (if installed)", + "4. Tag and push (GPG-signed commits required per CONTRIBUTING.md)", +] + +[maintenance-operations] +crg-grade = "just crg-grade # reads READINESS.md '**Current Grade:** X'" +contractile-checks = "just must-check ; just trust-verify ; just intend-list ; just dust-status" diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml new file mode 100644 index 0000000..51ae4fb --- /dev/null +++ b/.machine_readable/6a2/STATE.a2ml @@ -0,0 +1,73 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# STATE.a2ml — Honest project state checkpoint for git-reticulator. +# Canonical location is .machine_readable/6a2/ (supersedes the former +# .machine_readable/STATE.a2ml S-expr file, removed 2026-06-03). + +[metadata] +project = "git-reticulator" +version = "0.1.0" +last-updated = "2026-06-03" +status = "paused-resumed" # was on backburner; resumed 2026-06-03 for a tidy-up pass + +[project-context] +name = "git-reticulator" +purpose = "Semantic-lattice builder for git repositories: the symbolic half of a neuro-symbolic (Graph-RAG, proof-carrying retrieval) stack." +primary-language = "rust" # host: CLI + REST shell +core-language = "affinescript" # intended lattice core (src/lattice/affine/*.affine) +completion-percentage = 15 + +[position] +phase = "design+skeleton" # design | skeleton | implementation | testing | maintenance +maturity = "experimental" # experimental | alpha | beta | production | lts + +# ════════════════════════════════════════════════════════════════════════════ +# HONEST STATUS — what is real vs. what is claimed +# ════════════════════════════════════════════════════════════════════════════ +[honest-status] +rust-host-loc = 237 # src/{lib.rs,cli/main.rs,api/app.rs} +rust-host-reality = "build_lattice/query_lattice are println! stubs; actix routes return canned JSON" +affine-core-loc = "~100 (models/storage/lattice.affine)" +affine-core-reality = "ASPIRATIONAL — AffineScript has no working compiler yet; these files cannot build, and as written they call Rust crates (git2/postgres) which AffineScript does not bind" +git-parsing = "NOT WIRED (git2 feature off by default; .affine calls git2 but cannot run)" +embeddings = "NOT WIRED (tch/PyTorch feature off by default)" +persistence = "NOT WIRED (postgres feature off by default)" +proofs = "ZERO (no .idr/.v/.lean/.agda). The 'lattice' noun is currently unearned — see PROOF-NEEDS.md" +test-reality = "27 tests pass but they assert 'does not panic' over println stubs; honest as smoke tests, overstated as a 7-category pyramid" + +[crg] +grade = "C" +achieved = "2026-04-04" +caveat = "Grade C reflects test-CATEGORY presence, not behavioural coverage of real lattice logic (none exists yet). See READINESS.md + TEST-NEEDS.md." +next = "Grade B requires 6 quality targets (lint/fmt/doc-coverage/etc.)" + +[blockers-and-issues] +blockers = [ + "affinescript-runtime path dep unresolvable without sibling repo (severity: low; feature-gated off)", + "the .affine core cannot compile (AffineScript compiler not ready) AND is written against Rust crates it cannot bind (severity: high; design rethink needed)", + "'lattice' is currently a typed DAG with no proven meet/join (severity: medium; see PROOF-NEEDS.md)", +] +template-debt = [ + "RESOLVED 2026-06-03: 0-AI-MANIFEST.a2ml had [YOUR-REPO-NAME]/{{AUTHOR}} placeholders", + "RESOLVED 2026-06-03: 6a2 metadata set created (was missing entirely)", + "RESOLVED 2026-06-03: NEUROSYM.a2ml/PLAYBOOK.a2ml were empty commented stubs", + "RESOLVED 2026-06-03: methodology.a2ml had {{...}} placeholders (would reject itself)", + "RESOLVED 2026-06-03: TOPOLOGY.md described non-existent .as files", + "RESOLVED 2026-06-03: READINESS.md missing though Justfile reads CRG grade from it", + "OPEN: two parallel contractile systems (.machine_readable/*.contractile vs contractiles/) — consolidate to one canonical location as follow-up", + "OPEN (cosmetic): CHANGELOG line 'replace casket-pages with Jekyll' is a stale wart; the actual workflow casket-pages.yml is estate-correct", +] + +[critical-next-actions] +actions = [ + "DECIDE the core-language question: either (a) make the lattice core real in Rust (wire git2, drop the un-compilable .affine), or (b) wait for AffineScript and rewrite the .affine to compile to Wasm without Rust-crate calls", + "Earn the 'lattice' word: implement SCC-condensation + a partial order, then discharge PROOF-NEEDS.md P1-P2 (Idris2)", + "Wire git2 behind the default feature so reticulate actually reads a repo", + "Replace println stubs with a real (even in-memory) lattice build + a test that asserts a lattice PROPERTY, not just no-panic", +] + +[ecosystem] +part-of = ["RSR Framework", "hyperpolymath neuro-symbolic stack"] +feeds = ["verisimdb (octad substrate)", "vcl-ut (proof-carrying queries)", "LLM/RAG consumers"] +sibling-language = "affinescript" diff --git a/.machine_readable/INTENT.contractile b/.machine_readable/INTENT.contractile index 48b89f6..de5229b 100644 --- a/.machine_readable/INTENT.contractile +++ b/.machine_readable/INTENT.contractile @@ -35,38 +35,34 @@ ; === Purpose (what this repo IS) === (purpose - "{{ONE_PARAGRAPH_PURPOSE}}" + "git-reticulator turns a git repo into a typed, hierarchical, embeddable structure (LOD lattice of keyword nodes + typed weighted edges) for token-bounded, eventually proof-carrying LLM retrieval. Layer 1 of a neuro-symbolic stack: reticulator -> RAG -> verisim octad -> vcl-ut proofs." ) ; === Anti-Purpose (what this repo is NOT — prevents scope creep) === (anti-purpose - "{{ONE_PARAGRAPH_ANTI_PURPOSE}}" - ; Examples: - ; "This is NOT a general-purpose database — it solves one specific problem." - ; "This is NOT a framework — it is a library with a focused API." - ; "This does NOT handle authentication — that is delegated to [other repo]." + "NOT a git-statistics/blame tool (it is a retrieval geometry, not analytics). NOT a vector database (vectors at scale are verisim's Vector modality). NOT a proof system (proofs, when they land, are Idris2 per PROOF-NEEDS.md). NOT a fork/wrapper; NOT a monorepo." ) ; === Key Architectural Decisions That Must Not Be Reversed === (architectural-invariants - ; *REMINDER: List the foundational decisions* - ; ("Idris2 for ABI definitions — dependent types prove interface correctness") - ; ("Zig for FFI — zero-cost C ABI compatibility") - ; ("Elixir for supervision — OTP fault tolerance") + ("LOD lattice over four SemanticLevels with parent_id (META ADR-002)") + ("Per-node embedding — the neuro-symbolic fusion point (META ADR-003)") + ("'lattice' is earned, not asserted — see PROOF-NEEDS.md P1/P2 (META ADR-005)") + ("Honesty legend IMPLEMENTED|SKELETON|ASPIRATIONAL in all docs") ) ; === Sensitive Areas (if in doubt, ask) === (ask-before-touching - ; *REMINDER: List areas where LLMs should check before modifying* - ; "src/abi/ — formal proofs, changes require re-verification" - ; "ffi/zig/ — C ABI boundary, changes affect all language bindings" - ; ".machine_readable/ — checkpoint files, format is specified" + "src/lattice/affine/ — core model; changes ripple into every downstream layer and PROOF-NEEDS obligations" + "Cargo.toml features — git-integration/db/embeddings gate real behaviour" + ".machine_readable/6a2/ — canonical state, format specified" + "CI workflows, license headers" ) ; === Ecosystem Position === (ecosystem - (belongs-to "{{MONOREPO_OR_STANDALONE}}") - (depends-on ("{{DEP1}}" "{{DEP2}}")) - (depended-on-by ("{{CONSUMER1}}" "{{CONSUMER2}}")) + (belongs-to "standalone (hyperpolymath neuro-symbolic stack)") + (depends-on ("affinescript" "k9")) + (depended-on-by ("verisim" "vcl-ut" "LLM/RAG consumers")) ) ) diff --git a/.machine_readable/STATE.a2ml b/.machine_readable/STATE.a2ml deleted file mode 100644 index 870926d..0000000 --- a/.machine_readable/STATE.a2ml +++ /dev/null @@ -1,44 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) -; -; .machine_readable/STATE.a2ml -; Machine-readable project state for git-reticulator. - -(state - (metadata - (repo "git-reticulator") - (version "0.1.0") - (language "rust") - (last-updated "2026-04-04")) - - (project-context - (description "Semantic lattice builder for git repositories using AffineScript") - (primary-language "rust") - (secondary-language "affinescript")) - - (crg - (grade "C") - (achieved-date "2026-04-04") - (test-categories - (unit "yes" (location "src/lib.rs#unit_tests") (count 7)) - (smoke "yes" (location "src/lib.rs#unit_tests") (count 2)) - (property "yes" (location "tests/property_tests.rs") (count 5)) - (e2e "yes" (location "tests/integration_tests.rs") (count 2)) - (reflexive "yes" (location "tests/integration_tests.rs") (count 2)) - (contract "yes" (location "tests/integration_tests.rs") (count 3)) - (aspect "yes" (location "tests/integration_tests.rs") (count 6)) - (benchmarks "yes" (location "benches/git_reticulator_bench.rs") (count 6)))) - - (current-position - (milestone "CRG Grade C achieved") - (next-milestone "CRG Grade B (requires 6 quality targets)")) - - (blockers-and-issues - (blocker "affinescript-runtime path dep not resolvable without nextgen-languages present" - (severity "low") - (workaround "Feature gated; default features exclude it"))) - - (critical-next-actions - (action "Implement actual AffineScript engine integration behind feature flag") - (action "Add real git2-based lattice building") - (action "Upgrade to CRG Grade B: 6 quality targets"))) diff --git a/.machine_readable/agent_instructions/README.adoc b/.machine_readable/agent_instructions/README.adoc index 6f7b429..9bc2e24 100644 --- a/.machine_readable/agent_instructions/README.adoc +++ b/.machine_readable/agent_instructions/README.adoc @@ -1,5 +1,5 @@ // SPDX-License-Identifier: MPL-2.0 -// Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) = Agent Instructions :toc: preamble diff --git a/.machine_readable/agent_instructions/coverage.a2ml b/.machine_readable/agent_instructions/coverage.a2ml index 1bd30fa..7c652f5 100644 --- a/.machine_readable/agent_instructions/coverage.a2ml +++ b/.machine_readable/agent_instructions/coverage.a2ml @@ -1,5 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # coverage.a2ml — Session coverage tracking # Updated at the end of each AI agent session. @@ -9,7 +9,7 @@ [metadata] version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" +last-updated = "2026-06-03" # ============================================================================ # COVERAGE STATE @@ -18,9 +18,20 @@ last-updated = "{{CURRENT_DATE}}" # visited and which have known MUSTs that were skipped. [coverage] -total-components = 0 -visited-components = 0 -coverage-percent = 0 +total-components = 1 +visited-components = 1 +coverage-percent = 100 + +[coverage.visited.metadata-and-docs] +date = "2026-06-03" +ring = 1 +fixes = 14 +notes = "Tidy-up pass: created 6a2/* (6 files) + PROOF-NEEDS.md + READINESS.md; de-templated 0-AI-MANIFEST, methodology, INTENT.contractile, agent_instructions/*; corrected TOPOLOGY/README/EXPLAINME; filled contractiles/intend; removed stale .machine_readable/STATE.a2ml; fixed Cargo readme path." + +[coverage.cherry-picking] +easy-high-completed = 10 +hard-high-deferred = 1 +assessment = "Docs/config/metadata tidy completed. The one hard item (core-language decision, META ADR-001) is correctly deferred to the maintainer — it needs a design call, not a doc edit." # ============================================================================ # VISITED COMPONENTS diff --git a/.machine_readable/agent_instructions/debt.a2ml b/.machine_readable/agent_instructions/debt.a2ml index 3289cbe..b47afa6 100644 --- a/.machine_readable/agent_instructions/debt.a2ml +++ b/.machine_readable/agent_instructions/debt.a2ml @@ -1,5 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # debt.a2ml — Meander debt list # Things found but not fixed. Carried between sessions. @@ -9,7 +9,7 @@ [metadata] version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" +last-updated = "2026-06-03" # ============================================================================ # DEBT ITEMS @@ -47,3 +47,47 @@ last-updated = "{{CURRENT_DATE}}" # effort = "easy" # impact = "low" # discovered = "2026-03-23" + +# --- Live debt carried from the 2026-06-03 tidy-up pass --- + +[[debt.should]] +component = "src/lattice/affine" +issue = "Core .affine cannot compile and calls Rust crates AffineScript can't bind — decide Rust-native core vs wait-for-AffineScript (META ADR-001)." +effort = "hard" +impact = "high" +discovered = "2026-06-03" + +[[debt.should]] +component = "contractiles" +issue = "Two parallel contractile systems: .machine_readable/*.contractile (S-expr, non-load-bearing) vs contractiles/ (load-bearing, generates contractile.just). Consolidate to one canonical location per 0-AI-MANIFEST." +effort = "medium" +impact = "medium" +discovered = "2026-06-03" + +[[debt.could]] +component = "CHANGELOG.md" +issue = "Line 'replace casket-pages with standard Jekyll Pages workflow' is a stale wart contradicting estate policy; actual workflow casket-pages.yml is correct." +effort = "easy" +impact = "low" +discovered = "2026-06-03" + +[[debt.could]] +component = "contractile.just" +issue = "DUST section references contractiles/dust/Dustfile.a2ml which does not exist; add it then regenerate via `contractile gen-just --dir contractiles`." +effort = "easy" +impact = "low" +discovered = "2026-06-03" + +[[debt.could]] +component = ".github/workflows (reusable-caller wrappers)" +issue = "Hypatia flags missing_timeout_minutes on governance.yml/hypatia-scan.yml/rust-ci.yml, but these are reusable-callers (uses:) where timeout-minutes is not a legal job key — the timeout must be set inside the hyperpolymath/standards reusables (out of this repo's scope). casket-pages.yml (real steps) was fixed in PR #23." +effort = "medium" +impact = "low" +discovered = "2026-06-03" + +[[debt.could]] +component = "governance.yml" +issue = "Hypatia flags unpinned_action: governance-reusable.yml@main is floated on @main not a SHA. Left intentionally (maintainer: estate may want first-party reusables to auto-update); revisit if the estate standardises on SHA-pinned reusables." +effort = "easy" +impact = "low" +discovered = "2026-06-03" diff --git a/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/agent_instructions/methodology.a2ml index a88ab49..3dd36ca 100644 --- a/.machine_readable/agent_instructions/methodology.a2ml +++ b/.machine_readable/agent_instructions/methodology.a2ml @@ -1,5 +1,5 @@ # SPDX-License-Identifier: MPL-2.0 -# Copyright (c) {{CURRENT_YEAR}} {{AUTHOR}} ({{OWNER}}) <{{AUTHOR_EMAIL}}> +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) # # methodology.a2ml — AI agent methodology configuration # Declares how agents should approach work in this repository. @@ -9,7 +9,7 @@ [metadata] version = "1.0.0" -last-updated = "{{CURRENT_DATE}}" +last-updated = "2026-06-03" spec = "https://github.com/hyperpolymath/standards/blob/main/agentic-a2ml/docs/ADR-002-methodology-layer.adoc" # ============================================================================ @@ -55,7 +55,7 @@ perfective = 10 # % for SPDX headers, doc updates, formatting, style # Customise this per project — the template default is generic. [methodology.unique-strength] -description = "{{PROJECT_UNIQUE_STRENGTH}}" +description = "The neuro-symbolic seam: one node = one lattice element + one embedding. Deepen the symbolic retrieval geometry (LOD lattice, provable zoom), not breadth of git statistics." deepen-not-broaden = true # ============================================================================ @@ -71,10 +71,10 @@ deepen-not-broaden = true [methodology.divergent-invariants] rules = [ - # Customise per project. Examples: - # "Idris2 only for formal verification — no Lean4, Coq, Agda", - # "believe_me count must remain zero", - # "FFI architecture: Idris2 → RefC → Zig → C ABI (no shortcuts)", + "Never claim 'lattice' algebra (meet/join) without discharging PROOF-NEEDS.md P1/P2 — otherwise say 'typed graph/DAG'", + "Never document a println/SKELETON stub as a working feature", + "Idris2 is the proof language if/when proofs land (estate spine; matches vcl-ut)", + "Retrieval geometry (LOD zoom) is the core strength — deepen it, do not add unrelated git analytics", ] # Optional: language invariant for the core strength @@ -89,9 +89,10 @@ rules = [ [methodology.known-constraints] constraints = [ - # Customise per project. Examples: - # "End-to-end build has never been verified", - # "libproject.so does not exist yet — all bindings call stubs", + "The .affine lattice core cannot compile (no AffineScript compiler) AND calls Rust crates it cannot bind — design rethink owed (STATE.a2ml ADR-001)", + "git2/postgres/tch are all feature-gated OFF — reticulate reads nothing real yet", + "build_lattice/query_lattice are println! stubs; the 27 tests assert no-panic, not behaviour", + "'lattice' is currently a typed digraph with cycles — not yet a partial order", ] # ============================================================================ diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index a7bad66..a5aab44 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -1,128 +1,104 @@ -# ⚠️ STOP - CRITICAL READING REQUIRED +# ⚠️ READ THIS FIRST (all AI agents) -**THIS FILE MUST BE READ FIRST BY ALL AI AGENTS** +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ## WHAT IS THIS? -This is the AI manifest for **[YOUR-REPO-NAME]**. It declares: -- Canonical file locations (where things MUST be, and nowhere else) -- Critical invariants (rules that must NEVER be violated) -- Repository structure and organization +AI manifest for **git-reticulator** — a semantic-lattice + embedding builder +for git repositories, and the symbolic (layer-1) half of a neuro-symbolic +retrieval stack (see `.machine_readable/6a2/NEUROSYM.a2ml`). -## CANONICAL LOCATIONS (UNIVERSAL RULE) +It declares canonical file locations, critical invariants, and — importantly — +the **honesty rule** for this repo: distinguish what is IMPLEMENTED from what is +SKELETON (stub) from what is ASPIRATIONAL (designed, not buildable). -### Machine-Readable Metadata: `.machine_readable/` ONLY +## HONESTY RULE (specific to this repo) -These 6 a2ml files MUST exist in `.machine_readable/` directory ONLY: -1. **STATE.a2ml** - Project state, progress, blockers -2. **META.a2ml** - Architecture decisions, governance -3. **ECOSYSTEM.a2ml** - Position in ecosystem, relationships -4. **AGENTIC.a2ml** - AI agent interaction patterns -5. **NEUROSYM.a2ml** - Neurosymbolic integration config -6. **PLAYBOOK.a2ml** - Operational runbook +git-reticulator is early. Much of the "core" lives in `.affine` files that +**cannot compile** (AffineScript has no working compiler yet) and that, as +written, call Rust crates AffineScript cannot bind. The Rust host is ~237 LOC +of `println!` stubs. Therefore: -**CRITICAL:** If ANY of these files exist in the root directory, this is an ERROR. +- Never document a stub as a working feature. +- Never assert "lattice" algebra (meet/join) — the structure is a typed DAG + until `PROOF-NEEDS.md` P1/P2 are discharged. Say "typed graph" / "DAG". +- Status legend everywhere: **IMPLEMENTED | SKELETON | ASPIRATIONAL**. -### Anchor File: `.machine_readable/anchors/ANCHOR.a2ml` ONLY +## CANONICAL LOCATIONS -Canonical authority and semantic-boundary declaration MUST exist at: +### Machine-readable metadata: `.machine_readable/6a2/` ONLY +The six a2ml files live here (NOT repo root, NOT `.machine_readable/` root): +1. `STATE.a2ml` — honest project state, blockers, next actions +2. `META.a2ml` — architecture decisions (ADRs), rationale +3. `ECOSYSTEM.a2ml` — relationships (affinescript, verisim, vcl-ut, k9, Hypatia) +4. `AGENTIC.a2ml` — AI agent permissions/constraints + RAG-provider role +5. `NEUROSYM.a2ml` — the neuro-symbolic architecture (the thesis of this repo) +6. `PLAYBOOK.a2ml` — neuro-symbolic playbooks + ops runbook -` .machine_readable/anchors/ANCHOR.a2ml ` +### Proof obligations: `PROOF-NEEDS.md` (repo root) +What must be proved to earn the word "lattice" and to make retrieval provable. -Do not place `ANCHOR.a2ml` at repository root. +### Agent instructions: `.machine_readable/agent_instructions/` +`methodology.a2ml`, `coverage.a2ml`, `debt.a2ml` (ADR-002 methodology layer). -### Maintenance Policies: `.machine_readable/policies/` ONLY +### Contractiles: `contractiles/` (load-bearing) — see note below +The root `contractiles/{intend,must,trust}/*.a2ml` are the canonical, generating +source: `contractile.just` is generated from them and imported by the Justfile. +A second, NON-load-bearing set exists at `.machine_readable/*.contractile` +(documentation-style); consolidating the two is tracked in STATE.a2ml. -Canonical maintenance/governance files MUST exist under: - -` .machine_readable/policies/ ` - -Minimum required files: -- `MAINTENANCE-AXES.a2ml` -- `MAINTENANCE-CHECKLIST.a2ml` -- `SOFTWARE-DEVELOPMENT-APPROACH.a2ml` - -Do not place maintenance policy files in repository root. - -### Bot Directives: `.machine_readable/bot_directives/` ONLY - -Bot-specific instructions for your automated agents. - -### Contractiles: `.machine_readable/contractiles/` ONLY - -Policy enforcement contracts (k9, dust, lust, must, trust). - -### AI Configuration & Guides: `.machine_readable/ai/` ONLY - -- `AI.a2ml` - Language-specific or LLM-specific patterns -- `PLACEHOLDERS.md` - Bootstrap guide - -### Community & Forge Metadata: `.github/` ONLY - -- `CODEOWNERS` - Review assignments -- `MAINTAINERS` - Machine-readable contact list -- `SUPPORT` - Support channels -- `SECURITY.md` - Technical security policy -- `CONTRIBUTING.md` - Technical contribution manual -- `CODE_OF_CONDUCT.md` - Conduct rules - -### Agent Instructions: `.machine_readable/agent_instructions/` ONLY - -Methodology-aware AI agent configuration (ADR-002): -- `methodology.a2ml` - Mode, invariants, ring ceiling, priority weights -- `coverage.a2ml` - Session coverage tracking (visited, skipped, MUSTs) -- `debt.a2ml` - Meander debt carried between sessions - -Entry points: -- `0-AI-MANIFEST.a2ml` - THIS FILE (universal entry point, read FIRST) +### Community/forge metadata: `.github/`, plus root `SECURITY.md`, `CONTRIBUTING.md`. ## CORE INVARIANTS -1. **No state file duplication** - Root must NOT contain STATE.a2ml, META.a2ml, etc. -2. **Single source of truth** - `.machine_readable/` is authoritative -3. **No stale metadata** - If root state files exist, they are OUT OF DATE -4. **License consistency** - All code MPL-2.0 unless platform requires MPL-2.0 -5. **Author attribution** - Always "{{AUTHOR}} <{{AUTHOR_EMAIL}}>" -6. **Container images** - MUST use Chainguard base (`cgr.dev/chainguard/wolfi-base:latest` or `cgr.dev/chainguard/static:latest`) -7. **Container runtime** - Podman, never Docker. Files are `Containerfile`, never `Dockerfile` -8. **Container orchestration** - `selur-compose`, never `docker-compose` - -## REPOSITORY STRUCTURE +1. State files in `.machine_readable/6a2/` only — no duplication in root. +2. `.machine_readable/6a2/` is the single source of truth for project state. +3. All code MPL-2.0; SPDX header on every file. +4. Author attribution: "Jonathan D.A. Jewell (hyperpolymath) ". +5. Container images use Chainguard base; runtime Podman (Containerfile, not Dockerfile); + orchestration selur-compose (not docker-compose). +6. No template placeholders ever committed (`{{...}}`, `[YOUR-REPO-NAME]`). -This repo follows the **Dual-Track** architecture: +## ACTUAL REPOSITORY STRUCTURE (as built, 2026-06-03) ``` -[YOUR-REPO-NAME]/ -├── 0-AI-MANIFEST.a2ml # THIS FILE (start here) -├── README.adoc # High-level pitch — excitement and awe (Rich Human) -├── EXPLAINME.adoc # Developer deep-dive — how it works (Rich Nerd) -├── ROADMAP.adoc # Future direction -├── CONTRIBUTING.adoc # Human contribution guide -├── GOVERNANCE.adoc # Decision-making model -├── Justfile # Task runner -├── Containerfile # OCI build -├── LICENSE # Primary license -├── src/ # Source code -│ └── interface/ # Verified Interface Seams -│ ├── abi/ # Idris2 ABI (The Spec) -│ ├── ffi/ # Zig FFI (The Bridge) -│ └── generated/ # C Headers (The Result) -├── container/ # Stapeln container ecosystem -├── docs/ # Technical depths -│ ├── attribution/ # Citations, owners, maintainers (adoc) -│ ├── architecture/ # Topology, diagrams -│ ├── theory/ # Domain theory -│ └── practice/ # Manuals -├── docs/legal/ # Legal exhibits and full texts -└── .machine_readable/ # ALL machine-readable metadata +git-reticulator/ +├── 0-AI-MANIFEST.a2ml # THIS FILE +├── README.adoc # pitch + honest status +├── EXPLAINME.adoc # developer deep-dive +├── PROOF-NEEDS.md # formal obligations (the 'lattice' debt) +├── TEST-NEEDS.md # test inventory (smoke-level today) +├── READINESS.md # CRG grade source (read by `just crg-grade`) +├── TOPOLOGY.md # accurate module map + data flow +├── Cargo.toml / Justfile # Rust build + task runner +├── src/ +│ ├── lib.rs # host library (SKELETON: println stubs) +│ ├── cli/main.rs # `reticulate` CLI (clap) +│ ├── api/app.rs # actix-web REST shell (stub responses) +│ └── lattice/affine/ # ASPIRATIONAL core (cannot compile yet) +│ ├── models.affine # data model (Keyword/Relationship/Lattice) +│ ├── storage.affine # Postgres + pgRouting persistence +│ └── lattice.affine # build_lattice / zoom_to_node (LOD) +├── tests/ # *.rs smoke/contract + lattice_tests.affine +├── benches/ # criterion harness +├── contractiles/ # load-bearing contractile sources +├── docs/ # setup + tech-debt audit +└── .machine_readable/ + ├── 6a2/ # the six a2ml files (canonical state) + ├── agent_instructions/ # methodology/coverage/debt + └── *.contractile # secondary (non-load-bearing) contractile docs ``` ## SESSION STARTUP CHECKLIST -✅ Read THIS file (0-AI-MANIFEST.a2ml) first -✅ Understand canonical location: `.machine_readable/` -✅ State understanding of canonical locations +1. Read THIS file. +2. Read `.machine_readable/6a2/STATE.a2ml` (honest status). +3. Read `PROOF-NEEDS.md` before touching anything that claims "lattice". +4. Respect the IMPLEMENTED/SKELETON/ASPIRATIONAL legend in all edits. -## ATTESTATION PROOF +## ATTESTATION -**"I have read the AI manifest. All machine-readable content (state files, anchors, policies, bot directives, contractiles, AI guides) is located in `.machine_readable/` ONLY, and community metadata is in `.github/`. I will not create duplicate files in the root directory."** +"I have read the manifest. State lives in `.machine_readable/6a2/` only. I will +mark SKELETON/ASPIRATIONAL honestly, will not claim 'lattice' algebra without +discharging PROOF-NEEDS.md P1/P2, and will not commit template placeholders." diff --git a/Cargo.toml b/Cargo.toml index 35e6649..853e8f5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,7 +6,7 @@ description = "Semantic lattice builder for git repositories in AffineScript" license = "MPL-2.0" authors = ["Jonathan D.A. Jewell (hyperpolymath) "] repository = "https://github.com/hyperpolymath/git-reticulator" -readme = "README.md" +readme = "README.adoc" [dependencies] # Core dependencies (always required) diff --git a/EXPLAINME.adoc b/EXPLAINME.adoc index 3cafd8c..c734fd1 100644 --- a/EXPLAINME.adoc +++ b/EXPLAINME.adoc @@ -1,34 +1,77 @@ // SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell = git-reticulator -- EXPLAINME -== Semantic lattice builder for git repositories in AffineScript +== Developer deep-dive -[quote, Cargo.toml] -____ -Semantic lattice builder for git repositories in AffineScript. -____ +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. -git-reticulator builds a lattice (partial order) over commits and refs in a -git repository, using AffineScript's affine-type semantics for safe traversal. -See `src/lattice/` for the lattice construction and `src/api/` for the REST -interface. +[IMPORTANT] +==== +Honest status (legend: IMPLEMENTED | SKELETON | ASPIRATIONAL): -**Caveat:** The README is currently empty beyond the title. The claim above -comes from `Cargo.toml` -- the lattice module exists but the project is early. +* 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 + +. *Ingest* (`git2`) — list files/units in the repo. +. *Multilevel keyword extraction* — emit `Keyword` nodes at four `SemanticLevel`s + (Module > File > Definition > Block), each with `parent_id` and an optional + `embedding`. +. *Relationship discovery* — typed weighted edges (`calls`, `contains`, + `inherits`, `depends_on`). +. *Persist* — Postgres + `pgr_createTopology` for Dijkstra/A* reachability. +. *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 [cols="1,2", options="header"] |=== -| Path | Proves +| 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). -| `Cargo.toml` -| Declares the project, its description, and Rust dependencies (actix-web, tokio, clap) +| `src/lib.rs` +| Host library bridging CLI/API to the (future) core. SKELETON (println stubs) + the 27 smoke tests. -| `src/lattice/` -| Lattice construction module (affine sub-module for AffineScript integration) +| `src/lattice/affine/models.affine` +| Data model: `SemanticLevel`, `Keyword` (with `embedding`), `Relationship`, `Lattice`. ASPIRATIONAL. -| `src/api/` -| REST API surface (actix-web) +| `src/lattice/affine/lattice.affine` +| `build_lattice` + `zoom_to_node` (LOD). ASPIRATIONAL. -| `src/cli/` -| CLI entry point (clap) +| `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`): + +. Decide the core-language question (Rust-native core now, vs. wait for AffineScript). +. Wire `git2` behind the default feature so `reticulate build` reads a real repo. +. SCC-condense + define the order, then discharge `PROOF-NEEDS.md` P2→P1 to earn "lattice". +. Replace a `println!` with a real lattice build + a test asserting a *property*. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md new file mode 100644 index 0000000..db0c6ad --- /dev/null +++ b/PROOF-NEEDS.md @@ -0,0 +1,107 @@ +# PROOF-NEEDS.md + + + +## Current State + +- **LOC**: ~237 Rust (host) + ~100 AffineScript (`.affine`, not compilable). +- **Existing proofs**: **NONE.** No `*.idr`, `*.v`, `*.lean`, `*.agda`, `*.fst`, + `*.tla`, `*.ads`. The 2026-05-26 estate tech-debt audit recorded + "Proof debt: none / Recommended next move: none" — that verdict is **wrong** + for a project whose headline noun is *lattice*. A lattice is a mathematical + claim with discharge obligations; asserting it without proof is exactly the + kind of overstatement this file exists to retire. +- **Status**: the structure git-reticulator builds today is a *typed, weighted + digraph* with a hierarchical containment sub-relation — **not** (yet) a + lattice, not even a partial order (TOPOLOGY.md itself mentions detecting + *circular* dependencies, i.e. cycles, which a partial order forbids). + +> The point of this document is to make the gap between the noun ("lattice") +> and the artifact (a digraph) explicit, and to list precisely what must be +> proved to close it. Until then, prose should say "typed graph" / "DAG". + +## Recommended Prover + +- **Idris2** — to match the estate's existing formal-methods spine (`vcl-ut` + ships a machine-checked Idris2 corpus, `%default total`, zero proof-escape). + Reusing it means shared CI (`proof-corpus.yml`-style gate) and shared + reviewer muscle. Lean4 or Coq would also serve; Idris2 is the path of least + estate friction. The order-theory here is elementary; the value is in + *connecting the proofs to the running code*, not in their depth. + +## What Needs Proving + +### P1 — It is actually a lattice (or: rename it) — **HIGH** +The relation `≤` derived from the structure must be shown to be a lattice: +- **P1a** `≤` is a partial order: reflexive, antisymmetric, transitive. +- **P1b** For every pair of nodes a **meet** (greatest lower bound) and a + **join** (least upper bound) exist and are unique. +- **P1c** The lattice laws hold: idempotence, commutativity, associativity of + `∧`/`∨`, and absorption. + +If P1b cannot be met for the real structure (likely — sibling nodes generally +have no unique join), then **honesty demands one of**: +- downgrade the claim to **meet-semilattice** (containment hierarchy with a top), or +- rename to "semantic **graph**" and drop "lattice" from the API/docs. + +### P2 — Cycles must be quotiented before any order claim — **HIGH** +The dependency graph has cycles. A partial order has none. The standard fix: +- **P2a** Compute the **strongly-connected-component condensation**; prove the + condensation is acyclic (a DAG). +- **P2b** Prove the order induced on the condensation is well-defined + (independent of SCC member choice). Only on the condensation does P1 even + get a chance. + +### P3 — Faithful abstraction of git history (monotonicity) — **HIGH** +The commit DAG → lattice mapping must not invent or lose ordering: +- **P3a** *Soundness*: if the lattice orders `a ≤ b`, then `a`'s git origin is + an ancestor of (or contained by) `b`'s — no spurious orderings. +- **P3b** *Completeness*: ancestry present in the commit DAG is reflected. +- Together: the construction is a **monotone (order-preserving) map** from the + commit DAG to the lattice. + +### P4 — LOD `zoom_to_node` is sound AND complete — **HIGH (the RAG trust anchor)** +This is the property that makes retrieval trustworthy — the bridge between the +symbolic guarantee and the neural/LLM consumer. +- **P4a** *Soundness*: every node returned by `zoom_to_node(n, L)` is a genuine + descendant of `n` at level `L` — no spurious context. +- **P4b** *Completeness*: every such descendant is returned — no silently + dropped context. +- Formally: `zoom(n, L) = { m | m ≤ n ∧ level(m) = L }`, exactly. + Get this wrong and the LLM is fed context that is incomplete (missing the + relevant bit) or padded (wasting the token budget the feature exists to save). + +### P5 — Construction is deterministic / confluent — **MEDIUM** +- Building the lattice twice from the same repo state yields the same lattice + (up to node identity). Without this, caching is unsound and any downstream + proof is meaningless because the object it refers to is unstable. + +### P6 — Neuro-symbolic consistency invariant — **MEDIUM (the novel target)** +The genuinely new obligation, and the one that matters for the neuro-symbolic +claim (see `.machine_readable/6a2/NEUROSYM.a2ml`): +- Do **not** prove "embedding proximity ⇒ lattice proximity" (false in general). +- **Do** prove the *drift predicate* is well-defined and decidable: given a + threshold, `drift(a,b) := cosine(emb a, emb b) high ∧ lattice-distance(a,b) high` + is a total, computable signal. This is what lets verisim's drift detector + treat neuro-symbolic disagreement as an observable event rather than a + silent inconsistency. + +### P7 — `pgRouting` reachability matches lattice reachability — **LOW** +- The Dijkstra/A* paths used for blast-radius (PB-4) range over the same edge + relation the lattice is built from — prove the stored `cost`/`weight` + topology is a faithful image of the in-memory `Relationship` set, so + "reachable in the DB" ⇔ "reachable in the lattice". + +## Priority + +**MEDIUM-HIGH.** git-reticulator is early and stubbed, so this is not blocking +a shipping product. But it is *cheap, high-signal* work: P1+P2 together either +earn the central noun or correctly retire it, and P4 is the precondition for +the proof-carrying-retrieval story that makes the whole neuro-symbolic stack +worth building. Do P2 → P1 → P4 first; the rest can follow the implementation. + +## Cross-references + +- `.machine_readable/6a2/NEUROSYM.a2ml` — where these proofs pay off (proof-carrying retrieval). +- `hyperpolymath/vcl-ut` `PROOF-NEEDS.md` + `verification/proofs/` — the estate template for "PROOF-NEEDS + Idris2 corpus + VERIFICATION-STANCE" done well. +- `TEST-NEEDS.md` — the testing counterpart (currently smoke-level over stubs). diff --git a/READINESS.md b/READINESS.md new file mode 100644 index 0000000..23aa025 --- /dev/null +++ b/READINESS.md @@ -0,0 +1,36 @@ + + + +# Readiness — git-reticulator + +**Current Grade:** C + +> This file is the source of truth read by `just crg-grade` / `just crg-badge` +> (they grep for `**Current Grade:** X`). It was missing before 2026-06-03 even +> though the Justfile referenced it — created as part of the tidy-up pass. + +## CRG (Component Readiness Grade) + +| Grade | Meaning | Status | +|-------|---------|--------| +| D | Builds | ✅ | +| **C** | **All test categories present + passing** | ✅ **(current)** | +| B | 6 quality targets (lint, fmt, doc-coverage, …) | ☐ next | +| A | Production-ready | ☐ | + +See `hyperpolymath/standards` → component-readiness-grades for the rubric. + +## Honest caveat + +Grade C here reflects test **category presence**, not behavioural coverage. The +27 tests assert "does not panic" over `println!` stubs (see +`.machine_readable/6a2/STATE.a2ml [honest-status]` and `TEST-NEEDS.md`). The +grade is technically correct against the rubric and simultaneously **overstates +functional maturity** — both facts are recorded so neither surprises a reader. + +## To reach Grade B + +1. Replace ≥1 stub with a real (even in-memory) lattice build. +2. Add a test that asserts a structural **property**, not just no-panic. +3. Lint/fmt/doc-coverage clean. +4. Discharge `PROOF-NEEDS.md` P2→P1 (earn the "lattice" noun) — bonus, not required for B. diff --git a/README.adoc b/README.adoc index 79bd228..b6c3477 100644 --- a/README.adoc +++ b/README.adoc @@ -4,68 +4,98 @@ = git-reticulator :toc: preamble :icons: font -:revdate: 2026-05-26 +: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://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] - -Semantic-lattice builder for git repositories — derives a lattice -representation of a repo's history (commits, files, semantic edits) and -exposes it via a Rust API. AffineScript is the eventual frontend target. +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 **semantic lattice** — meet/join operations over -commits, file-trajectories, and (eventually) AST-level semantic edits. -The output is suitable for: +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) -* Refactoring-impact analysis (what changes propagate where). -* Authorship attribution at semantic-unit granularity. -* Time-aware queries ("when did this concept enter the codebase"). +[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] ---- -# Build: -just build # or: cargo build --release - -# Run against a local repo: -./target/release/git-reticulator scan /path/to/repo +just build # cargo build (default features; no git2/db/embeddings) -# See available commands: -./target/release/git-reticulator --help +# 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 ---- -== Architecture +NOTE: these run today but are **stubs** — `build` prints and returns; it does +not yet read the repo or write the DB. -Written in Rust. AffineScript bindings planned in a future phase -(currently a Rust-only library + CLI). +== Architecture -* `src/` — core library + CLI. -* `benches/` — benchmark harness. -* `configs/` — example configurations for typical scan profiles. -* `docs/` — design notes and ADRs. +* `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 +== Status & honesty -* **Licence**: MPL-2.0. (Previously declared PMPL-1.0-or-later — migrated - 2026-05-26 per the estate licence-debt audit, hyperpolymath/standards#196.) -* **Maturity**: research / iteration. API not stable. -* **Audit findings**: see `docs/tech-debt-2026-05-26.md` if present - (added by the 2026-05-26 estate tech-debt scan). +* **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]. All commits must be GPG-signed. -Conventional-commits required (CHANGELOG is generated by -link:https://github.com/hyperpolymath/standards/pull/206[standards#206]'s -`changelog-reusable.yml`). +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/standards[`hyperpolymath/standards`] — canonical estate standards. -* link:https://github.com/hyperpolymath/affinescript[`hyperpolymath/affinescript`] — the language whose bindings will become this repo's eventual frontend. -* link:https://github.com/hyperpolymath/k9[`hyperpolymath/k9`] — the related metadata-extraction tooling (`k9iser.toml` is consumed here). +* 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/TEST-NEEDS.md b/TEST-NEEDS.md index 88c45c4..6c2f01a 100644 --- a/TEST-NEEDS.md +++ b/TEST-NEEDS.md @@ -4,6 +4,14 @@ All required test categories for CRG Grade C are present and passing. +> **Honest caveat (2026-06-03):** these 27 tests are *smoke-level* — they call +> `build_lattice`/`query_lattice` (which are `println!` stubs) and assert "does +> not panic". They verify the host compiles and the API surface is reachable; +> they do **not** exercise real lattice logic (there is none yet). The +> property/contract/aspect/e2e labels describe test *categories*, not +> behavioural depth. Behavioural + property tests over a real lattice are owed +> alongside `PROOF-NEEDS.md` P1–P4. + ### Test Inventory | Category | Status | Location | Count | @@ -35,4 +43,4 @@ cargo bench ### Next: CRG Grade B Requires 6 quality targets (linting, formatting, documentation coverage, etc.). -See `.machine_readable/STATE.a2ml` for details. +See `.machine_readable/6a2/STATE.a2ml` for details. diff --git a/TOPOLOGY.md b/TOPOLOGY.md index fe842c6..b0164ea 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.md @@ -5,33 +5,62 @@ ## Purpose -Semantic lattice builder for git repositories written in AffineScript. Constructs dependency graphs and semantic relationships from commit histories, code structure, and metadata to enable advanced repository analysis and visualization. +Semantic-lattice + embedding builder for git repositories. Turns a repo into a +typed, hierarchical, embeddable structure suited to feeding LLMs cheaply and +(eventually) provably — layer 1 of a neuro-symbolic retrieval stack +(see `.machine_readable/6a2/NEUROSYM.a2ml`). -## Module Map +> Status legend: **IMPLEMENTED** (Rust on main) · **SKELETON** (stub/println) · +> **ASPIRATIONAL** (designed in `.affine`, not compilable yet). + +## Module Map (as actually built, 2026-06-03) ``` git-reticulator/ ├── src/ -│ ├── main.as # AffineScript core (compiled to binary) -│ ├── lattice.as # Lattice construction algorithms -│ ├── git_parser.as # Git history parsing -│ └── semantic.as # Semantic relationship inference -├── Cargo.toml # Rust package wrapper -├── build.sh # Build orchestration -└── examples/ - └── ... (example repositories) +│ ├── lib.rs # host library — SKELETON (println stubs) +│ ├── cli/main.rs # `reticulate` CLI (clap): build|query|api +│ ├── api/app.rs # actix-web REST shell — SKELETON (canned JSON) +│ └── lattice/affine/ # ASPIRATIONAL core (AffineScript, cannot compile) +│ ├── models.affine # Keyword / Relationship / Lattice + SemanticLevel +│ ├── storage.affine # Postgres + pgRouting persistence +│ └── lattice.affine # build_lattice / zoom_to_node (LOD) +├── tests/ +│ ├── integration_tests.rs # contract/aspect/e2e (smoke-level) +│ ├── property_tests.rs # proptest (over stubs) +│ ├── api_tests.rs +│ └── lattice_tests.affine # ASPIRATIONAL (cannot run) +├── benches/git_reticulator_bench.rs # criterion +├── Cargo.toml # Rust package (features: git-integration, db, embeddings…) +└── Justfile # task runner ``` -## Data Flow +There are **no `.as` files** and no `build.sh`; earlier versions of this doc +listed `src/main.as`, `src/git_parser.as`, `src/semantic.as` — those never +existed. The core lives in `src/lattice/affine/*.affine`. + +## Data Flow (intended; ASPIRATIONAL end-to-end) ``` -[Git Repository] ──► [History Parser] ──► [Commit Graph] ──► [Semantic Lattice] - ↓ - [Dependency Inference] +[Git repo] ─►(git2)─► [files] ─► [multilevel keyword extraction] ─► [Keyword nodes + embeddings] + │ + [typed relationship discovery (calls/contains/…)] + │ + [Postgres + pgRouting topology] ◄── persistence + │ + [zoom_to_node(level)] ─► token-bounded sub-lattice ─► LLM/RAG ``` +Today only the dashed CLI/REST shell exists; every box downstream of `git2` is a +stub or unbuildable. See `.machine_readable/6a2/STATE.a2ml [honest-status]`. + ## Key Invariants -- Written in AffineScript for memory-safe concurrent analysis -- Produces semantic lattice that preserves commit relationships -- Can detect unstable or circular dependencies +- **Honesty**: stubs are documented as stubs; the "lattice" claim is unearned + until `PROOF-NEEDS.md` P1/P2 are discharged (the structure is a typed digraph + with cycles — not yet a partial order). +- **LOD is the point**: `zoom_to_node` must return the *minimal* relevant + sub-lattice (token discipline), and must be sound + complete (PROOF-NEEDS P4). +- **Neuro-symbolic fusion at the node**: every `Keyword` carries both an order + position and an optional embedding (`models.affine`). +``` diff --git a/contractiles/intend/Intentfile.a2ml b/contractiles/intend/Intentfile.a2ml index 2b3acc1..f7b4198 100644 --- a/contractiles/intend/Intentfile.a2ml +++ b/contractiles/intend/Intentfile.a2ml @@ -1,22 +1,51 @@ # SPDX-License-Identifier: MPL-2.0 # Intentfile (A2ML Canonical) -# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) @abstract: -Declared intent and purpose for Git Reticulator. +Declared intent and scope for git-reticulator. Defines what this repo IS, what +it is NOT, and which decisions are load-bearing. Prevents agents from drifting +into scope creep or reversing key decisions. @end ## Purpose -Git Reticulator — A hyperpolymath project. +git-reticulator turns a git repository into a **typed, hierarchical, embeddable +structure** — semantic keyword nodes at four levels of detail (Module > File > +Definition > Block), connected by typed weighted relationships, each node +optionally carrying an embedding. Its reason to exist is the **retrieval +geometry**: `zoom_to_node` returns a token-bounded sub-structure so an LLM gets +the *minimal relevant* context, not a whole-repo dump. It is layer 1 of a +neuro-symbolic stack (reticulator → RAG → verisim octad → vcl-ut proofs). -## Anti-Purpose +## Anti-Purpose (prevents scope creep) This project is NOT: -- A fork or wrapper around another tool -- A monorepo (unless explicitly structured as one) +- A general git statistics / blame / churn tool — it is a retrieval geometry, + not an analytics dashboard. Deepen the lattice; do not broaden into metrics. +- A vector database — embeddings are *attached to* nodes; storage/search of + vectors at scale is verisim's job (Vector modality). +- A proof system — formal guarantees are owed (PROOF-NEEDS.md) and, when they + land, are written in Idris2; do not invent a bespoke prover here. +- A fork or wrapper around another tool; not a monorepo. -## If In Doubt +## Architectural Invariants (do not reverse without an ADR) -If you are unsure whether a change is in scope, ask. -Sensitive areas: ABI definitions, license headers, CI workflows. +- LOD lattice over four SemanticLevels with `parent_id` (META ADR-002). +- Per-node embedding — the neuro-symbolic fusion point (META ADR-003). +- The word "lattice" is **earned, not asserted** (META ADR-005 / PROOF-NEEDS). +- Honesty legend IMPLEMENTED|SKELETON|ASPIRATIONAL applies to all docs. + +## Sensitive Areas (if in doubt, ask) + +- `src/lattice/affine/` — the (aspirational) core model; changes ripple into + every downstream layer and into PROOF-NEEDS obligations. +- `Cargo.toml` features — git-integration/db/embeddings gate real behaviour. +- `.machine_readable/6a2/` — canonical state; format is specified. +- CI workflows, license headers. + +## Ecosystem Position + +- belongs-to: standalone (part of the hyperpolymath neuro-symbolic stack) +- depends-on: affinescript (core language, future), k9 (metadata) +- depended-on-by: verisim (substrate), vcl-ut (proof layer), LLM/RAG consumers