docs/ARCHITECTURE.md

PhillNet Recall 1.1: evidence paths and read contracts

Two different read results

recall(question) first tries nine anchored English query productions. Supported questions become explicit relational paths. Other questions use literal matching plus 36 authored topic groups. A topic hit is related evidence, not a semantic answer. There is no embedding encoder or unrestricted natural-language parser.

follow(entity, steps) executes a typed relational join over supplied entity/predicate/value claims. Each step is forward or explicitly inverse. It does not invent edges, assume every relation is transitive, parse factual triples from arbitrary prose, or treat a topic association as equivalence of values. Unknown predicate names remain literal identifiers. Entity matching normalizes Unicode and ignores letter case but preserves punctuation; claim values preserve case and punctuation. Applications needing case-sensitive entity identity should use distinct opaque identifiers and the legacy exact-match read path.

Data path

Explicit write -> scoped SQLite evidence -> one eligibility snapshot -> conflict groups and adjacency -> bounded query execution -> complete supporting paths -> live revalidation -> atomic evidence packet -> separate host model.

The original storage schema and 22-record policy bank remain unchanged. Evidence stays outside the host's parameters and KV cache. All decision logic is not inside the rankers: parsers, SQL, joins, time gates, integrity checks and prompt assembly remain ordinary executable software.

Path semantics and limits

A path has one to eight steps. Each valid, positive assertion or measurement is an edge. Quotations, hypotheses, negative-only claims and records matching the limited instruction heuristic cannot supply an edge. Explicit conflicting claims stop a touched path before ranking. A many-valued branch must complete on every branch; otherwise the result is incomplete or unknown, never a guessed exhaustive list.

Explicit alias_of claims are scope-local dependencies. They are not automatically derived from similar spelling. Alias cycles and multivalued aliases stop as ambiguous. Alias support IDs are included in the resulting evidence. An alias can be revised, expired or forgotten exactly like other evidence.

Default bounds: 10,000 eligible scope records, 4,096 edge expansions, 128 paths. Exceeding a bound returns budget_exceeded without a partial answer. Raising one bound does not disable the others. These are not unbounded graph reasoning claims.

Two time axes and retention

valid_from and valid_to describe supplied world validity. recorded_at describes when memory learned a claim. as_of and known_at independently constrain every hop and alias. Current-clock TTL always applies, even for historical queries. Revision tombstones prevent a deleted correction from resurrecting superseded content. These properties are inherited from the 1.0 store and extended across the whole path.

Two new policies; no new training

The original rankers.ugr is 11,064 bytes (22 complete records plus its header). evidence.ugr adds two complete 500-byte records plus a 64-byte header: 1,064 bytes. Combined: 24 records, 12,128 serialized bytes, 10,584 numeric parameters.

Each new record has 20 inputs, 20 ReLU hidden units and one scalar output. Named feature coordinates include literal/topic coverage, explicit anchors, provenance, uncertain wording, dependency completeness and proof cost. The weights implement published utility coefficients; they were not gradient-trained. provenance/evidence_policy.json and scripts/reproduce.py reproduce the exact bytes. evidence.safetensors mirrors the extra parameters; it is not a separate language model. Neural/conventional equality is reported, not presented as superiority.

Cached graph views

The first read collects a bounded consistent scope snapshot and builds forward/reverse adjacency and conflict indexes. Warm relational reads reuse it. A view is bound to this memory instance, its query time mode and scan bound, SQLite data_version, and this connection's total_changes. It expires at the next validity, knowledge or retention boundary. Local writes clear it immediately; external writes invalidate it before the next read. A version change racing a read prevents that view from being retained. A separate-connection race regression exercises this behavior.

Only one scope view and its adjacency are cached per instance. It contains source text and costs substantially more memory than the 12 KB checkpoint. Any write can make the next read cold. The cache is not a claim of sub-millisecond uncached retrieval or constant-time ingestion. An in-flight read can legitimately return its earlier database snapshot; the caller must independently authorize consequential actions.

Evidence certificates and prompt packets

A supported result includes the explicit plan, answer values, supporting record IDs, per-record fingerprints, time axes, scope, policy/lexicon hashes and an integrity checksum. verify_evidence recomputes the plan from storage. Current mode rejects changed support; historical mode preserves the specified time interpretation but never bypasses deletion/TTL. A checksum is not a signature or external fact verification.

pack_evidence reconstructs content from storage, so tampering with the caller's returned item text cannot inject it into a valid packet. It chooses one complete proof per distinct answer and includes all dependencies. When the whole set does not fit, it emits no partial answer. This is a deterministic per-answer size heuristic, not globally optimal set cover.

compile_context handles either proof packets or related-note packets. Related notes explicitly contain no inferred answer. Conflicts and incomplete paths do not silently fall back to lexical snippets. Budgets count exact UTF-8 bytes without a tokenizer, or actual caller-tokenizer IDs when provided. Full rendered prompts are checked again. The host context window is not enlarged.

Migration and loading

Database schema 1 remains compatible; no automatic content rewrite occurs. New snapshots use phillnet.recall.snapshot.v2, binding both original and new policy/lexicon contracts. Legacy snapshots require explicit migrate_snapshot_v1 followed by restore; restoration validates before mutation. Hub loading downloads data files only, never remote Python or native libraries. The extra checkpoint files must accompany a 1.1 configuration.