Tracer Bullet 01 — document to cited answer #15

Retired — consolidated into #30. This map and #30 (the /to-spec output) restated the same architecture, assertions and decisions in two places. #30 is now the single tracker issue for Tracer Bullet 01: all 14 child stories (NU-001…NU-014, #16–#28, #31) have been reparented from here to #30, and #30 has absorbed this issue's Frontier/blocking table. docs/tracer-bullet-01.md remains the long-form rationale document, unaffected by this consolidation.

The fixture-corpus source text preserved in the comment thread below remains the source of truth for NU-002/#31 — nothing there has moved; it's just reached via #30 now instead of here.

Everything below this line is the original map body, kept for history.

Part of #14.

Wayfinding map for the first vertical slice of Nuron. Design is in docs/tracer-bullet-01.md; this map carries the scope, the assertions, and the frontier.

Superseded by #30, which now carries the full Frontier/blocking table.

Scope

A document lands (watched directory or upload) → original preserved in object storage → format extraction → deterministic parse → human review and approval → LLM compile → human merge confirmation → property graph → a query returns a grounded answer citing a Decision node reached by graph traversal.

Single user. No auth, no users, no roles, no config UI, no audit log, no rate limiting, no tenancy, no supersession, no connectors, no write-back.

What this proves: given human-verified input, does graph persistence plus vector-entry/graph-expand retrieval produce a cited answer that a chunk store could not have produced — and does human merge confirmation make the entity matcher improve over time?

What it does not prove: whether an LLM could extract Decisions accurately without a human (the gate answers that by fiat); whether the pipeline scales (a human gate on every file is the bottleneck by design); which edge-type vocabulary reviewers actually need.

Architecture

Six containers. RabbitMQ is deliberately not among them.

Arrows point one way: web → api → ai → {postgres, neo4j, rustfs}. nuron-ai never calls upward. Schema isolation is enforced by DB roles, not convention — if nuron-api could read nuron_ai tables it eventually would, and the one-way layering would become a comment rather than a constraint.

Pipeline states: landed → extracted → parsed → awaiting_review → content_approved → compiled → awaiting_merge_confirm → persisted. One Postgres table. The review queue is the work queue — claimed with FOR UPDATE SKIP LOCKED, which is why there is no broker. Both blocking states are real persisted states, not UI steps: a reviewer may close the browser between them and restart-safety requires resuming where it paused.

Two agents

Compiler and query agent. The parser and format extractors are code, not agents. The Curator is out of scope. "Default Agent" is retired as a name — the ingest pipeline is a state machine.

Fixture

Five files in fixtures/watched/. A one-file graph sits entirely within vector reach and would let the bullet pass without traversing anything. Authoring and committing these files is NU-002/#31 — until it closes, the corpus exists only as text in the comment below.

• A auth-token-decision.md — the decision, attributed in prose (— Basuru, 2026-05-14).
• B rate-limiter.md — "the limiter keys off the session store". Never mentions JWT, sessions being dropped, or the decision.
• C cdn-token-caching.md — noise. Superficially about tokens/auth/performance, semantically unrelated.
• D sessions-table-replication.md — the alias case (sessions table).
• E a one-page PDF of the same decision as A. Used only by A11.

Query under test: "what did the auth change affect?" The answer is the rate limiter, in B, reachable only via Decision(A) → Entity(session store) → Entity(rate limiter).

Assertions

Why these carry weight:

• A2's author_source="extracted" stops A2 passing by copying a config value into a node property.
• A3 converts "it worked" into "it worked because of the graph".
• A7 is the reference-counting bug a one-file fixture would never catch.
• A9 proves the cross-document join: the shared entity name is the join, produced by the natural key with no human involvement.
• A10 proves the compounding property. Every confirmed merge extends normalize(name) → node to many-names-per-node, so the matcher improves monotonically from human input — no threshold, no tuning, no regression. This is the only part of the system that gets better as it is used.
• A11 is deliberately non-blocking so a LlamaCloud timeout can never invalidate a graph finding.
• A12 proves two entry points converge on one identity. Without it, uploading an already-ingested file silently duplicates the whole chain.

Decisions

Full rationale in docs/tracer-bullet-01.md §3. Load-bearing ones:

1. Citation is a Decision node with author, timestamp and resolving Evidence edge — not a filename. A filename citation passes with a plain chunk store and proves nothing.
2. Compiler emits structured output with an explicit decisions[], not a Markdown document.
3. author is extracted from content with a configured fallback, plus author_source: extracted | default | unknown. The config value is named source_owner, never author.
4. Pass 1 is deterministic code: format extractor → common markdown form → header parse.
5. Every file blocks for human review. Reviewers may edit body content, not just metadata.
6. Reviewed Source is the Evidence root, not the raw file. Human-vouched content is better evidence than raw.
7. nuron-ai owns the pipeline and its state; nuron-api owns the user-facing surface.
8. RabbitMQ deleted — Postgres is the queue. The review queue is the work queue, so a broker would be a second copy of the same state.
9. "Reply" means v1.1 write-back, not query answering. Query answering is synchronous end to end.
10. Retrieval is HNSW entry → graph expand (VectorContextRetriever(path_depth=1)). No BM25, RRF or LLMRerank yet.
11. Embeddings live in Neo4j on the graph nodes, not pgvector — no dual-write between stores.
12. Content hash is identity, and the hash is the object key. Not a UUID, which would break dedupe.
13. Re-approve replaces the document's provenance slice. Provenance is a set, refcounted.
14. Node identity across compiles is a natural key normalize(name) + label, extended by human-confirmed aliases. Under-merges by design; a human resolves rather than a tuned threshold.
15. Human confirms merges, not links. Auto-joins are shown as information, never asked. Link creation deferred.
16. Originals in RustFS, content-addressed, read back and re-hashed before acking a write.
17. v1 formats .md .txt .docx .pdf. No .doc, no OCR — near-empty extraction fails loudly rather than reaching a reviewer as an empty item.
18. LlamaParse is configurable and off by default. It is third-party cloud; PRD §5.1 promises no data leaves the customer network.

Known gaps, deliberately deferred

• Local PDF extraction is on the critical path to shipping. LlamaParse is dev/test only under §5.1, so no customer deployment can parse PDFs until a local path exists.
• Reviewer's edits are lost on re-ingest — mitigated by showing a diff, not a three-way merge. This is the workflow that decides whether reviewers engage or start rubber-stamping.
• Automatic near-duplicate merge, OCR, .doc, multipart upload, page-anchored citations, typed link creation, gate-on-low-confidence, supersession, Curator re-curation, BM25/RRF/LLMRerank, write-back.
• Uploaded documents have no second copy — RustFS is Beta and holds the only one. The read-back-and-re-hash check is the only thing between a silent write failure and permanent loss of an original.

Frontier

Children are listed as sub-issues and ordered by dependency. A child is workable when every blocker is closed.

Order and blockers

Every "half" split is intentional, not an ownership gap: each half is independently real risk
— a correct primitive in one story cannot make the observable behavior correct if the story that
exercises it end-to-end is wrong, and vice versa. A5/A6/A7/A10 previously read as claimed in full
by two stories with no qualifier; they're relabeled above to match the pattern A4/A12 already used
correctly.

Open frontier: NU-001, NU-002, NU-014. Everything else has an open blocker.

Nothing is implemented. A first pass at NU-001 and (old) NU-002 was written before these stories
existed and has been deleted — code ahead of the tracker was the wrong way to start. The repo
currently holds only docs/tracer-bullet-01.md and the pre-existing planning artifacts.

The fixture corpus text is preserved in a comment on this issue as the source of truth for exact
wording; NU-002/#31 is the story that turns it into committed files. The constraints on it (B must
never mention JWT; C must be plausible noise; A must carry attribution in prose, not frontmatter)
are what make A1 and A2 test anything.