The Knowledge Graph Build Standard

1. What this standard covers

Any body of material a business will later ask an assistant to speak from, where being wrong has a cost somebody else carries. Lender panels, tenancy legislation, a trade price book, safe work method statements and codes of practice, a franchisor operations manual, the credit policy a licensee issued.

It does not cover a personal notes database, a marketing content lake, or a chat log treated as training data. Client interviews become an advice file, not nodes in this graph, until a person promotes a claim into the library. “We do not lend on this product in Western Australia” is a policy node. “This client said they are comfortable” is not.

The failure this prevents is specific. It is the answer that cites “the knowledge base” the way a student cites “the internet”. Retrieval appeared to work. Nothing in the system can show which clause, which edition, which date, or which other node will break when that file is replaced.

The phase before this one. Check 2 registers a source as an instrument as if the source were to hand. For most businesses it is in somebody’s email. The Knowledge Base standard is that phase: one register with an owner per source, on the Microsoft 365 or Workspace tenant the business already runs, and a watch that notices a changed edition. The graph takes its sources from that register, never from a fresh upload. It is the long, foundational part, and it is measured in weeks for a network.

What this is not. Pointing a copilot at a document library. Fine-tuning on “all our data” and naming the weights. A wiki with backlinks. An ontology slide in a deck. Those can sit beside a graph. They are not one.

2. Pile, index, graph

Three layers. Only the third is this standard. The first two are allowed as plumbing.

An implementation may use the index to propose nodes. The graph is what production reads. Cited Answer retrieves clauses, not chunks. Advice File writes field keys, not summaries. If production reads the index, you have not implemented this.

3. The key contract

The same shape as the Multi-Site Conformance standard. A small set of types, named once, versioned. Departments may add types. They may not rename or fork the shared ones. An unwritten convention about “what we usually link” is a fork.

Node types, a closed list at version 1

Edge types, a closed list at version 1

Add types by bumping the contract version. Do not silently invent a RELATED_TO edge. That edge is how a pile sneaks back in.

4. The objects, and what is in them

Nine objects the build actually stores. The acceptance and the supersession are the two most retrieval builds leave out, because search appears to function without them.

KeyContract
  - version, effective_from
  - node_types[], edge_types[], required_fields per type
  - closed_lists (predicate, kind, jurisdiction, queue)
  - extension_rule: add freely, never rename or fork

Source                            # plus the fields in the node table
  - queue (proposed | accepted | retired | rejected)
  - accepted_by, accepted_on      # required before any child can answer
  - checksum, previous_source_id

Passage
  - locator must be replayable: page and section, offsets in a stable
    file version, or start and end seconds. "Chunk 47" is not a locator.

Node                              # Clause, Concept, Entity, Fact are subtypes
  - type, key, body
  - valid_from, valid_to (null while live)
  - provenance { source_ids[], passage_ids[], extract_run_id }
  - accepted_by, accepted_on
  - queue (proposed | live | conflict | change_pending | retired)

Edge
  - type (from the contract), from_id, to_id
  - valid_from, valid_to
  - accepted_by, when the edge can change who an answer may name

ExtractRun
  - id, source_id, started_at, finished_at
  - method (rules | model | person), model_id, prompt_hash
  - proposed_node_ids[], proposed_edge_ids[]
  - accepted_count, rejected_count

Conflict
  - id, node_ids[], detected_on, reason
  - status (open | accepted_as_scoped | resolved)
  - decided_by, decided_on        # never "the model picked one"

QueryRecord                       # written when something READS the graph
  - id, asked_on, asked_about_date, jurisdiction
  - hit_node_ids[], missed (bool)
  - consumer (cited_answer | advice_file | pack | other)

ChangeDelta
  - id, source_id, old_checksum, new_checksum
  - affected_node_ids[]           # computed, not guessed
  - status (pending | accepted | rejected), decided_by, decided_on

A Node with queue live and empty provenance is the defect, and it should not be writable. A Source with queue accepted and no checksum is the same defect on the next replacement.

5. The checks, in order

The order is the claim. Chunk, then embed, then hope is a different order, and it fails the pass test.

1. The key contract is written and versioned before the first extract. Node types, edge types, predicates and required fields are a closed list at each version. An extract that invents a type has forked the graph and is refused.
2. Every source is registered as an instrument, not a file path. Title, issuer, edition, jurisdiction, effective dates, checksum and retrieved_at. A drive link with no edition is a pile entry, not a Source.
3. No node is live without a named acceptance and a replayable locator. Ingestion is not production. A node reaches live only when a named person accepts it, and only when its provenance names a passage with a locator that can be opened and highlighted.
4. Production reads live nodes, and a card names a node, never a file. Cited Answer and Advice File attach source cards from live nodes. An answer that cites a passage hash, a chunk id or a filename has not used the graph.
5. Entity identity comes from a system of record, or SAME_AS is an accepted edge. A lender, a product, a site or a person carries the id the CRM, the panel or the register already uses. Two labels that look alike are two things until a person accepts SAME_AS. An embedding that thinks they match is not identity.
6. Scope is an APPLIES_TO edge, and an unscoped clause cannot answer a scoped question. A clause with no jurisdiction, product, work type or entity on it can decline or sit in conflict. It cannot answer a question asked about one state or one product.
7. Supersession and conflict are written edges, and the model never picks a winner. A new node retires the old through SUPERSEDES and the old cannot answer. Two live nodes that disagree get a CONFLICTS edge and a named person, never an average and never a confidence score.
8. Replacing a source produces a delta with a computed list of affected nodes. When the checksum moves, the graph lists every node built from that source and every historic answer that used them. If you cannot produce that list, you have an index.
9. Proposed, live, conflict, change_pending and retired are states, not labels. A retired node must not appear on a new source card. It must remain findable for the answers that used it.
10. The index can propose and rank. Emptying it does not empty the graph and does not invent an answer. Detach the vector index and the model weights. The live nodes are unchanged. A question the graph covers still answers from the same node; a question it does not cover declines.
11. Customer files and interviews are not sources unless a person promotes a claim. A claim from an interview becomes a Fact only when a named person promotes it, and the Fact still needs provenance. A crawler finding it in the same drive does not make it policy.
12. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
13. The pass test passes. Load, ask, move, identity, the forbidden path and one-fact-two-places, on a corpus the business controls with at least one system-of-record id, as the pass test describes.

6. The four queues for a node

Declining to extract is a success. A run that forces a fact out of a passage that is only colour commentary has polluted the graph. Rejected proposals stay on the extract run so you can see the model getting keen.

7. What the index is allowed to do

The index is a proposer and a finder. It is not the store.

Allowed: propose passages from a new source; propose SAME_AS candidates for a person to accept; find candidate clauses for a query, which the graph then filters by date, jurisdiction and queue; embed node bodies to rank live hits.

Not allowed: answer; be the only copy of the text; hold a type the contract does not name; survive as the production path when the graph is empty.

If a vendor’s architecture diagram reads embeddings, then model, then answer, with the graph as a side box, they have not implemented this. The arrow goes embeddings, to proposed nodes, to a person, to the live graph, to a source card.

8. What stays with a person

• ✓Accepting a source into the library.
• ✓Accepting a proposed node or edge as live.
• ✓Resolving a conflict between two live nodes.
• ✓Accepting a change delta so affected nodes may answer again.
• ✓Declaring two entities the same thing when the systems disagree.
• ✓Any statement that the graph is complete, compliant, or approved for client use.

The extractor may propose. It may not occupy accepted_by or decided_by. Client material does not become a source because it was sitting in the same drive. Promoting an interview claim into a fact is a person, and the fact still needs provenance.

9. Provider: what to stub, and what not to hand-roll

Three steps not to hand-roll, and they are the same three the Rejected Pack standard already named in other words. Extraction, embedding, the interface and the first cut of types, an agent can build against the stub in an afternoon.

provider:
  stub:       local.mock_graph
  production: none                       # no hosted step; runs on your own systems

do not hand-roll
  - identity. Entity nodes take their id from the system of record:
    the accounting contact, the CRM lender id, the ABN, the product
    code on the panel. A second identifier invented by the extractor
    is a shadow register.
  - the change. Replacing a file without a checksum diff, an
    affected-node list and a person on the delta is how last year's
    rule keeps answering. This is the binding layer.
  - acceptance. A nightly job that promotes proposed to live because
    the model was confident is how a wrong PDF becomes policy.
    accepted_by is a person, always.

storage is not the standard
  - lists, Postgres, or a graph database. The objects are the standard.

There is no hosted product for this standard. The production check runs over the business's own corpus, its own register ids and the library a named person accepted. A vendor selling the embedding and the chat is selling the plumbing, and is usually silent about who accepts a replaced edition. Ask them that first.

10. Conformance checklist

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. The key contract is written and versioned before the first extract. Node types, edge types, predicates and required fields are a closed list at each version. An extract that invents a type has forked the graph and is refused.
• ✓2. Every source is registered as an instrument, not a file path. Title, issuer, edition, jurisdiction, effective dates, checksum and retrieved_at. A drive link with no edition is a pile entry, not a Source.
• ✓3. No node is live without a named acceptance and a replayable locator. Ingestion is not production. A node reaches live only when a named person accepts it, and only when its provenance names a passage with a locator that can be opened and highlighted.
• ✓4. Production reads live nodes, and a card names a node, never a file. Cited Answer and Advice File attach source cards from live nodes. An answer that cites a passage hash, a chunk id or a filename has not used the graph.
• ✓5. Entity identity comes from a system of record, or SAME_AS is an accepted edge. A lender, a product, a site or a person carries the id the CRM, the panel or the register already uses. Two labels that look alike are two things until a person accepts SAME_AS. An embedding that thinks they match is not identity.
• ✓6. Scope is an APPLIES_TO edge, and an unscoped clause cannot answer a scoped question. A clause with no jurisdiction, product, work type or entity on it can decline or sit in conflict. It cannot answer a question asked about one state or one product.
• ✓7. Supersession and conflict are written edges, and the model never picks a winner. A new node retires the old through SUPERSEDES and the old cannot answer. Two live nodes that disagree get a CONFLICTS edge and a named person, never an average and never a confidence score.
• ✓8. Replacing a source produces a delta with a computed list of affected nodes. When the checksum moves, the graph lists every node built from that source and every historic answer that used them. If you cannot produce that list, you have an index.
• ✓9. Proposed, live, conflict, change_pending and retired are states, not labels. A retired node must not appear on a new source card. It must remain findable for the answers that used it.
• ✓10. The index can propose and rank. Emptying it does not empty the graph and does not invent an answer. Detach the vector index and the model weights. The live nodes are unchanged. A question the graph covers still answers from the same node; a question it does not cover declines.
• ✓11. Customer files and interviews are not sources unless a person promotes a claim. A claim from an interview becomes a Fact only when a named person promotes it, and the Fact still needs provenance. A crawler finding it in the same drive does not make it policy.
• ✓12. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓13. The pass test passes. Load, ask, move, identity, the forbidden path and one-fact-two-places, on a corpus the business controls with at least one system-of-record id, as the pass test describes.