Mental model

One-line mental model

Append-only SQLite ledger of typed claims (polarity + evidence grade + scope). A gate rejects under-evidenced writes. A dispersion-aware pipeline groups hits by scope at read time and annotates each result with whether its neighbors agree, disagree, or conflict.

Module map

What happens on add()

1. Validate user_id against the strict regex.
2. Lazily resolve storage path (constructor / ATLASO_PATH / ancestor walk / project marker / cwd).
3. Open or fetch the cached per-user FieldStore at <base>/users/<sha256(user_id)[:16]>/field.db.
4. Run the gate. If rejected, raise DepositRejectedError(gate_reason=...).
5. Insert into deposits + mirror into the contentless deposits_fts FTS5 virtual table.
6. Write one contradictions edge per id in contradicts=[...].
7. Re-read the row, translate to a public Deposit, return AddResult.

What happens on recall()

1. Sanitise the FTS5 query — strip :*"?@…, OR-join tokens. (Without this, "what kind of coffee?" returned zero hits.)
2. _engine.aware.query_aware fans out per polarity with freshness decay (positives 14d, negatives/cautionaries 90d).
3. Group every candidate into BagStats keyed by the six scope facets.
4. Compute bag_precision, is_single_sample, has_conflict, conflict_peers per bag.
5. Write one summary row to query_log — powers FMI Coverage.
6. Aggregate has_disagreement / is_confident across all bags before slicing.
7. Sort conflict bags first, flatten into per-deposit SearchResult rows, return SearchResults.

Dig deeper

• The gate — exact write-admission rules per polarity × scope-breadth × evidence.
• Retrieval pipeline — BM25 constants, half-lives, k-distribution.
• Storage layer — schema, FTS5 index, where the file lives.