Retrieval pipeline

flowchart LR
  BOOT(["START: the daemon boots<br/>(writ serve)"]) --> LOAD
  NEO[("Neo4j")] --> LOAD["_load_candidates<br/>non-mandatory Rules<br/>+ 5 methodology types"]
  LOAD --> KI["KeywordIndex.build (Tantivy)<br/>trigger boosted x2, statement, tags,<br/>body diluted to x0.5"]
  LOAD --> TXT["Corpus text per candidate:<br/>trigger + statement"]
  TXT --> HASH["SHA-256 corpus hash<br/>over id + text pairs"]
  HASH --> CHK{"Disk cache<br/>hash match?"}
  CHK -->|"hit"| LOADIDX["Load hnswlib index<br/>from ~/.cache/writ/hnsw<br/>encode skipped entirely"]
  CHK -->|"miss"| ENC["ONNX encode_batch<br/>all-MiniLM-L6-v2, CPU<br/>about 84% of cold start"]
  ENC --> BUILDIDX["Build + persist hnswlib index<br/>cosine, 384-dim, atomic writes"]
  NEO --> AC["AdjacencyCache<br/>every edge except BELONGS_TO,<br/>stored in both directions"]
  NEO --> ABSL["Abstraction nodes<br/>loaded for summary mode"]
  KI --> READY
  LOADIDX --> READY
  BUILDIDX --> READY
  AC --> READY
  ABSL --> READY
  READY(["READY: all indexes warm,<br/>the query path is pure in-memory"])
  classDef entry fill:#0B5E55,stroke:#083F39,color:#FFFFFF,font-weight:bold
  classDef finish fill:#F6EEDF,stroke:#B4560F,color:#6B3D14,font-weight:bold
  classDef hub fill:#DCE9E5,stroke:#0B5E55,stroke-width:2px
  class BOOT entry
  class READY finish

flowchart TD
  Q(["START: a query arrives<br/>query(text, domain, budget_tokens,<br/>exclude, prefer, mode, project)"])
  S2["Stage 2: BM25 keyword search<br/>top 50 candidates"]
  S3["Stage 3: vector search<br/>top 10 candidates<br/>query embedding LRU-cached"]
  F["Stage 1 filter, pure AND chain:<br/>already-loaded ids excluded,<br/>domain match, node-type whitelist,<br/>project scope (project + _shared)"]
  MG["Merge both lists<br/>reciprocal-rank normalize each signal:<br/>1 / (rank + 1)"]
  S4["Stage 4: adjacency enrichment<br/>each candidate's neighbors attached<br/>from the in-memory edge cache"]
  Q --> S2 --> F
  Q --> S3 --> F
  F --> MG --> S4
  S4 --> NEXT(["NEXT: Stage 5 ranking<br/>(Figure 2.3)"])
  classDef entry fill:#0B5E55,stroke:#083F39,color:#FFFFFF,font-weight:bold
  classDef finish fill:#F6EEDF,stroke:#B4560F,color:#6B3D14,font-weight:bold
  classDef hub fill:#DCE9E5,stroke:#0B5E55,stroke-width:2px
  class Q entry
  class NEXT finish

flowchart TD
  FROM(["START: the merged candidate pool<br/>from Figure 2.2"]) --> FP
  FP["Stage 5a: first-pass score<br/>bm25 + vector + severity + confidence<br/>weights renormalized, graph term held at zero"]
  SEED["Top-3 proximity seeds<br/>ai-provisional rules excluded"]
  PROX["Stage 5b: graph proximity per candidate<br/>1-hop neighbor of a seed = 1.0<br/>2-hop = 0.5, otherwise 0.0<br/>seeds themselves score 0 (no self-boost)"]
  FINAL["Stage 5c: final weighted fusion<br/>all five terms, sorted descending"]
  STICKY["Sticky tiebreak<br/>adjacent scores within 0.02 reorder<br/>to match last-injected order<br/>(keeps prompt caches warm)<br/>requires descending input"]
  AUTH["Authority preference pass<br/>human outranks ai-provisional within a threshold<br/>(config: [retrieval] authority_preference_threshold, default 0.0 = off)<br/>runs LAST so the hard preference is final"]
  BUDGET["Context budget<br/>summary / standard / full projection"]
  OUT["rules, mode, total_candidates, latency_ms"]
  FP --> SEED --> PROX --> FINAL --> STICKY --> AUTH --> BUDGET --> OUT
  classDef entry fill:#0B5E55,stroke:#083F39,color:#FFFFFF,font-weight:bold
  classDef finish fill:#F6EEDF,stroke:#B4560F,color:#6B3D14,font-weight:bold
  classDef hub fill:#DCE9E5,stroke:#0B5E55,stroke-width:2px
  class FROM entry
  class OUT finish