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. You read it on the card on Actionable Twins, and
in full through the card’s View full decision artifact. It is sealed when a person
approves the card. 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.
| Field | What it holds |
|---|---|
kind | One value from the closed EvidenceDocumentKind vocabulary (below). |
subject_id | The customer’s own identifier for the shipment, claim or entry. It is also the key for the seal chain. |
facts (DocumentFact) | What the records say. Every fact carries at least one citation id. |
findings (DocumentFinding) | What was determined, as stable codes such as OSD_SHORT or SLA_BREACH_CONFIRMED, with a severity and the operands used. Never empty of citations. |
citations (Citation) | Where each figure came from (see below). |
deadlines (DocumentDeadline) | A date computed from a record date by a named rule (for example CARMACK_NOTICE_9M, COGSA_SUIT_1Y) with its authority, and the citation that supplied the start date. |
claimed_amount, exposure_amount, units_short, units_damaged | Headline figures. These are optional, so a measured zero and “not measured” are different on the wire. |
absent (AbsentFigure) | Why a figure is missing, from a closed set: NO_BACKING_RECORD, NOT_STATED_ON_DOCUMENT, ILLEGIBLE, EXTRACTION_FAILED, NOT_YET_DETERMINABLE, CURRENCY_NOT_STATED (a figure stated with no currency: not money, so not measured). |
narrative (DocumentNarrative) | Optional prose. authored_by is deterministic-template or the model id, and figure_ids lists every figure the prose mentions. |
seal (DocumentSeal) | Set at approval. Never set at derivation. |
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 thefieldread.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, pluslineage_record_idpointing 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,ILLEGIBLEorEXTRACTION_FAILED) and the model’s own confidence. That confidence is never used as a truth threshold. Ifperceptionis 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_hashcovers the canonical bytes of fields 1 to 14.prev_hashchains the seal to the previous seal for the samesubject_id.- The seal record goes into the append-only lineage log. It carries hashes and ids only, never document content.
signatureandkey_idare 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: 18 document kinds
EvidenceDocumentKind is a closed vocabulary. Nothing on the model path can invent
a new kind, and a build-time test checks that every kind FACE emits is constructed by
its own deriver over cited records. FACE emits the 18 kinds below. Three more numbers
are reserved and never emitted (PRE_DEPARTURE_RISK_BINDING, CLAUSED_EBOL and
PROCEDURE_DEVIATION_LOG), because no feed supplies the records they would need and
building them from what is on disk would mean inventing figures.
| Kind | Charges the headline? |
|---|---|
| Paralegal and claims recovery | |
STATEMENT_OF_POSITION | No. States claimed_amount. |
OSD_REPORT | Yes: the cargo value short or damaged. |
NOTICE_OF_INTENT_TO_CLAIM | No. States exposure_amount. |
SUBROGATION_DEMAND | No. States claimed_amount. |
| Cargo insurance and underwriting | |
FNOL | Yes: the reserve, only for claims no claims card already charges. |
CARGO_LOSS_SURVEY | No. States exposure_amount. |
WARRANTY_COMPLIANCE_AUDIT | No. States exposure_amount. |
| Shipper contracts and liability | |
RATE_CON_ACCESSORIAL_AUDIT | Yes: accessorials billed above the rate confirmation. |
MSA_SLA_COMPLIANCE_AUDIT | Yes: service credits owed under an SLA clause. |
| Field operations and cold chain | |
TEMPERATURE_EXCURSION | No. States exposure_amount only when the readings state load_value WITH a load_value_currency; otherwise it is absent as CURRENCY_NOT_STATED (“Not measured”). The cold-chain twin prices nothing. |
CHAIN_OF_CUSTODY_AUDIT | No. Exposure is declared absent. |
CUSTOMS_MANIFEST_EXCEPTION | No. The customs twin owns the delay’s cost. |
| Reverse, reactive and equipment | |
RETURN_DISPOSITION | No. |
SERVICE_DISRUPTION | No. |
EQUIPMENT_LIMIT_APPROACH | No. An approaching limit is not a loss. |
| Recovery leakage and indicator review | |
CLAIMS_LEAKAGE | No. States exposure_amount; the recovery card it points to owns the money. |
FRAUD_INDICATOR_REVIEW | No. An indicator is not savings. States exposure_amount. |
| Revenue recovery | |
DEDUCTION_DISPUTE | No. States claimed_amount: the part of a customer’s deduction that the run’s own purchase order, proof of delivery and invoice do not support. FACE sends it nowhere. |
The kind names above drop the EVIDENCE_DOCUMENT_KIND_ prefix. The charging rule is
explained on Action cards & money.
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.
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.
Reading the results
- 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_unixand 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.
- Each deriver has its own tests for correctness. The coverage test checks that every emitted kind has a producer.