Skip to content

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.

FieldWhat it holds
kindOne value from the closed EvidenceDocumentKind vocabulary (below).
subject_idThe 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_damagedHeadline 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 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: 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.

KindCharges the headline?
Paralegal and claims recovery
STATEMENT_OF_POSITIONNo. States claimed_amount.
OSD_REPORTYes: the cargo value short or damaged.
NOTICE_OF_INTENT_TO_CLAIMNo. States exposure_amount.
SUBROGATION_DEMANDNo. States claimed_amount.
Cargo insurance and underwriting
FNOLYes: the reserve, only for claims no claims card already charges.
CARGO_LOSS_SURVEYNo. States exposure_amount.
WARRANTY_COMPLIANCE_AUDITNo. States exposure_amount.
Shipper contracts and liability
RATE_CON_ACCESSORIAL_AUDITYes: accessorials billed above the rate confirmation.
MSA_SLA_COMPLIANCE_AUDITYes: service credits owed under an SLA clause.
Field operations and cold chain
TEMPERATURE_EXCURSIONNo. 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_AUDITNo. Exposure is declared absent.
CUSTOMS_MANIFEST_EXCEPTIONNo. The customs twin owns the delay’s cost.
Reverse, reactive and equipment
RETURN_DISPOSITIONNo.
SERVICE_DISRUPTIONNo.
EQUIPMENT_LIMIT_APPROACHNo. An approaching limit is not a loss.
Recovery leakage and indicator review
CLAIMS_LEAKAGENo. States exposure_amount; the recovery card it points to owns the money.
FRAUD_INDICATOR_REVIEWNo. An indicator is not savings. States exposure_amount.
Revenue recovery
DEDUCTION_DISPUTENo. 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_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.
  • Each deriver has its own tests for correctness. The coverage test checks that every emitted kind has a producer.