Evidence documents

An evidence document (EvidenceDocument) is a document a third party acts on, such as an adjuster, a carrier’s claims desk or a court. FACE attaches one to an ActionCard in evidence_document. The contract is strict about what these documents are and are not:

These documents assemble a file, show what was read, and propose one next step for a person entitled to take it. They do not underwrite, bind, settle, or satisfy an obligation on anyone’s behalf.

Determination, then expression

Every field above narrative is determination. Derivers compute it as fixed, testable arithmetic over cited records, and no model is involved. narrative is expression. A model may draft it, but only after the determination is frozen, and only using figures that are already set.

Citations

A Citation has everything a reader needs to go and check a figure:

• source_kind, source_id (the record’s id in the customer’s system), and the field read.
• value: the value exactly as read, never reformatted. This makes “no invented figures” something a test can check: every headline figure is either a cited value or documented arithmetic over cited values.
• connection_id, plus lineage_record_id pointing at the extraction record in the append-only lineage log.
• observed_at: taken from the lineage record, never from the wall clock, so re-deriving a document produces the same bytes.
• perception: set only when a model read the value off a scanned document image. It records an outcome (READ, NOT_PRESENT_ON_DOCUMENT, ILLEGIBLE or EXTRACTION_FAILED) and the model’s own confidence. That confidence is never used as a truth threshold. If perception is absent, the value came from a structured record.

Sealing

A seal (sha256-chain-v1) is written when an operator approves the card, never before:

• content_hash covers the canonical bytes of fields 1 to 14.
• prev_hash chains the seal to the previous seal for the same subject_id.
• The seal record goes into the append-only lineage log. It carries hashes and ids only, never document content.
• signature and key_id are filled in only when a signing key is configured.

A rejected card is deliberately left unsealed, because sealing a refused document would assert a state nobody adopted. If the seal can’t be written, the approval still stands, and the document is recorded as approved and unsealed.

The vocabulary: 15 produced, 3 deliberately not built

EvidenceDocumentKind is a closed vocabulary of 18 kinds. Nothing on the model path can invent a new one. A build-time test (cmd/evidence_kind_coverage_test.go) enforces two things:

• Every kind is either constructed by a deriver, or marked NOT BUILT in face.proto with its reasoning written beside it. There is no third state.
• A “not built” marker with no reasoning fails the test.

The kind names above drop the EVIDENCE_DOCUMENT_KIND_ prefix. The charging rule is explained on Action cards & money.

Why three kinds are not built

Each of these has a reserved number in the enum and a written reason. Keeping the slot records that the question was asked and answered.

PRE_DEPARTURE_RISK_BINDING would put a price on risk. A pre-departure binding prices risk and commits cover before a shipment moves. Every other kind is fixed arithmetic over records the customer already holds. This one would need a rating basis, loss history and an underwriting appetite that nothing in the platform holds, and no arithmetic over a telemetry feed produces a premium. Deriving it would mean inventing a price someone is quoted.

CLAUSED_EBOL would forge an annotation. A claused bill of lading carries the exceptions a driver or receiver wrote on it at pickup or delivery, such as “3 cartons crushed”. The OS&D feed carries counts after the fact, and a count is not a clause. Deriving “3 cartons crushed” from a shortage of three would write an exception into a carrier’s transport document that no driver signed. Building it needs a source of scanned or structured BOL remarks mapped to the shipment each one clauses.

PROCEDURE_DEVIATION_LOG would be an accusation with no standard behind it. A deviation log measures what was done against what the procedure said to do. No feed carries a customer’s written SOPs, and no record says which procedure governed a given move. Treating any anomaly as a deviation would attribute a norm that FACE inferred to the operator’s own procedure. Building it needs a per-tenant SOP corpus and a way to bind each procedure to the movements it governs.

Names chosen to avoid over-claiming

EQUIPMENT_LIMIT_APPROACH is deliberately not called “predictive maintenance”. The deriver measures a channel’s trend against a limit the feed itself states, and reports when a straight line through the first and last readings reaches that limit. Nothing is fitted and nothing is forecast, so no failure probability is ever produced. A real forecast would get its own kind.

CHAIN_OF_CUSTODY_AUDIT keeps one rule: an unrecorded handoff is not a break in custody. Every finding is a statement about the record, never about the goods or the people handling them.

The underwriting documents never decide coverage. No finding code says VOID, DECLINED, REPUDIATED or anything like it. Those are an underwriter’s words.

What this does not establish

• A document is a file, not a decision. It proposes one next step for a person entitled to take it. It doesn’t serve notice, file a claim or settle anything.
• A computed deadline is an input, not legal advice. It doesn’t preserve a right on anyone’s behalf. The document carries due_unix and no “days remaining” figure; the client computes the countdown at render time.
• A citation proves provenance, not correctness. It shows exactly which record a figure came from. It doesn’t show that the record was right.
• A seal proves the bytes haven’t changed since approval. It doesn’t prove who approved them. For that, see the decision trail on Action cards & money.
• Coverage tests prove that a producer exists, not that it’s correct. Each deriver’s own tests cover correctness.