Graph model

The model

In short: an entity has claims; every claim shows its evidence and scope; relationships connect the resulting knowledge. Schema returns these trustworthy building blocks so a person or agent can inspect where an answer came from and where it stops applying.

Why the supporting machinery exists

Provenance, version scope, and explicit coverage gaps are not extra domain concepts. They are assurance machinery that prevents an extracted statement from being presented as universally true. Review states, source-refresh states, and corpus history serve the same purpose internally; most users do not need to learn them to understand the product.

The reference below is exhaustive because the implementation is checked against it automatically. Its size should not be read as the number of concepts a customer must understand.

Technical reference

Expand a section when implementing against the corpus, reviewing a candidate extraction, or auditing a served result. These definitions are normative for their respective records.

Entities

An Entity is a stable, linkable handle for something operators name: it has an id, an entity_type, a title, alternate names (the alias surface lexical retrieval matches against), and a description. Entities carry no truth about behavior — that lives in claims about them.

Relationships

An EntityEdge is a directed, typed link between two entities with a human-readable description and — critically — claim_refs: the claims that establish the relationship. Edges are for traversal ("what observes this behavior?", "what bounds this parameter?"); claims are for truth. An edge without a grounding claim is a modeling error.

Claims, evidence, and applicability

A Claim is the unit of knowledge. Its core is a subject–predicate–object triple: the subject is an entity reference, the predicate is drawn from a controlled vocabulary, and the object is structured data (not prose) — a metric type, a default value, a formula. Around that core:

• statement — the canonical human-readable sentence. Statement fidelity is a hard rule: exact tokens, source specifics preserved, no attribution scaffolding (metadata carries attribution exactly once).
• evidence — pinned citations into snapshotted sources, each with a role, strength, kind, and extraction method, plus a locator (path and line range). Claims cite spans, not documents.
• applies_to — product, version range (tags, introduced_in/removed_in, channel), and conditions. Version applicability is deliberately distinct from freshness: a claim pinned to v0.23.0 does not decay because time passes; it stops applying when the version scope no longer matches.
• guards — structured applicability dimensions that make scope queryable rather than buried in prose.
• knowledge_time — when the fact was recorded and last verified, with explicit precision.
• freshness_policy — review and staleness windows driving the freshness state machine.
• does_not_establish — explicit negative scope: adjacent conclusions the claim must not be stretched to support. This is the anti-overreach field, and it is served, not internal. It is bounded by the claim's own statement — conclusions a reader could draw from this claim and the evidence does not support — so it never asserts a fact and never negates one. Guards influence which claims rank first, but a question only a guard addresses is never treated as answered.
• establishment_class, status, confidence — the epistemic triple: how the fact is established, how far verification has gotten, and how strong the evidence is.
• consumer_context — optional customer-facing "Why this matters" copy preserved from the candidate's catalog context at promotion. It is product-side interpretation (relevance, audience, safe use), never source-attributed fact, and it renders separately from the statement and evidence.

Events: the append-only corpus log

Records enter the corpus wrapped in events. Nothing is edited in place from a consumer's point of view: corrections arrive as supersede events, withdrawals as retract events, and the serving stores are projections of the event log at a pinned corpus snapshot id.

Coverage: topics, availability, gaps

Topics are the slice objects: named groupings of entities and claims that carry coverage meaning ("prefix cache effectiveness"). Topics declare gaps — known missing knowledge is a first-class record, not silence. Availability records inventory what exists on a surface at a version, independent of which members have promoted claims.

Topic identity is stable across versions. entity_refs declare its semantic members, scope_refs attribute knowledge produced by declared scope predicates, and surface_refs contribute availability only for those explicit members. The selected-version projection reports covered, partial,known_absent, or not_evaluated; legacy version tags describe evidence provenance rather than whether the topic exists. One claim or history record may support multiple topics.

Sources and snapshots

Every citation resolves to a pinned snapshot: a content-hashed copy of a source at a specific tag, commit, or retrieval date. Claims never cite live URLs. Source records carry type, authority, and relationship so consumers can weigh provenance.

The extraction and review pipeline

Claims are not written directly. A pinned snapshot goes through an isolated extraction run producing candidate claims — review substrate that never serves canonically. Candidates carry the same core anatomy plus a catalog_context: the extractor's categorization of what kind of claim this is and how consumers would reach it. Review decisions are recorded per candidate; accepted candidates are promoted into assertion events with full evidence locators.

Use cases: documented question shapes

Use cases (internally: query scenarios) are product records documenting an operator question shape end to end — verbatim phrasings, the nuance targeted, what Schema does with it, and refs into the claims, topics, and eval fixtures that ground it. Their canonical public URLs live under /use-cases.

Knowledge-graph mapping