How a verdict is produced.
Deterministic, reproducible, and explainable. This page describes exactly what happens between a vendor's claim and a line on a statement.
1. Objects
- Claim — one billed outcome from a vendor usage export or invoice: subject, outcome type, timestamp, unit price.
- Fact — one event from a customer system of record: helpdesk status change, assignee change, CSAT, refund, and so on. Facts are read, never written.
- Outcome contract — a YAML document that defines, per vendor and outcome type, which facts must (or must not) exist for a claim to be verified. It carries a source citation and a list of unknown fields.
- Lens — a rule set inside the contract. The vendor lens follows the vendor's published definition; the strict lens applies longer windows and additional checks.
- Verdict — the result of evaluating one claim under one lens.
2. Verdicts
Every claim receives exactly one verdict per lens:
- Verified — every rule is satisfied by at least one fact, and the claim is the first for its subject in the period.
- Not verified — facts exist for the subject, and at least one rule fails.
- Unverifiable — the facts needed to decide are unavailable: no connected source covers the subject, or the identity could not be matched. This is reported separately and is never treated as a finding against the vendor.
3. Reason codes
A not-verified or unverifiable verdict carries one primary reason code and may carry secondary codes.
| Code | Label | Meaning |
|---|---|---|
| precondition_unmet | Precondition not met | A fact the contract requires before the action may run was not observed in the system of record, or did not have the required value. |
| limit_exceeded | Limit exceeded | A parameter of the action was outside the limit set in the contract, for example a refund amount above the cap. |
| expected_effect_missing | Expected effect not observed | The contract expects a change in a system of record after the action, and no matching fact was observed inside the settlement window. |
| forbidden_effect_observed | Forbidden effect observed | A fact the contract forbids, for example a second refund on the same order, was observed inside the window. |
| duplicate_effect | Duplicate effect | The same effect was observed more than once for the subject, which suggests the action was executed twice. |
| effects_pending | Effects still within settlement window | Not every expected effect has been observed yet, and the settlement window has not closed. The verdict is UNKNOWN until it does. |
| customer_confirmed_resolved | Customer confirmed resolved | The customer confirmed the issue was resolved (positive rating, a confirming message, or closing the record) within the window after the claim. |
| no_customer_reply_within | No customer reply in window | The customer did not write again within the window after the claimed outcome. |
| reopened_within | Reopened after claim | The record was reopened inside the contract's reopen window, so the resolution did not hold. |
| escalated_to_human_within | Escalated to a human | The conversation was escalated or assigned to a human agent inside the window. |
| human_reply_within | Human agent replied | A human agent replied inside the window after the claim. |
| refund_or_credit_within | Refund or credit issued | A refund or credit was issued to the customer inside the window after the claim. |
| refund_posted_within | Refund posted | A refund was posted in the billing system inside the window. |
| csat_negative | Negative satisfaction rating | The customer left a negative satisfaction rating after the claim. |
| csat_missing | No satisfaction response | No satisfaction response was recorded for the conversation. |
| duplicate_claim_for_subject | Duplicate claim for subject | Another claim for the same subject exists in the same billing period; only the earliest counts. |
| status_at_claim_in | Status at claim time | The record's status at the time of the claim was not one the definition accepts. |
| record_status_in | Record reached status | The record reached a status the definition treats as decisive. |
| missing_fact_source | Required fact source not connected | A fact source the definition depends on is not connected, so there are no facts to verify against. |
| identity_unmatched | Subject not found in fact sources | The claim's subject could not be found in any connected fact source, so nothing can be verified either way. |
| no_structured_signal | No structured signal | The subject exists in the fact sources but none of the record types the definition depends on were observed. |
| verified_condition_not_met | Verified condition not met | None of the conditions that would verify the claim were satisfied. |
| channel_in | Channel | The claim's channel is excluded by the contract. |
| outside_billing_period | Outside billed period | The claimed outcome occurred outside the billing period on the invoice. |
| excluded_by_contract | Excluded by contract | The claim matches an exclusion rule in the contract. |
| opportunity_reached_stage_within | Opportunity reached stage | The linked opportunity reached the required stage inside the window. |
| meeting_occurred_within | Meeting occurred | A meeting was recorded inside the window. |
| transcript_label_is | Transcript label | A transcript-assist label matched the contract's override rule. Labels never produce a Verified verdict. |
| transcript_label:customer_indicated_unresolved | Transcript: customer indicated unresolved | A transcript-assist label (reviewed by sampling) indicated the customer did not consider the issue resolved. |
| transcript_label:abandoned | Transcript: customer abandoned | A transcript-assist label (reviewed by sampling) indicated the customer abandoned the conversation. |
4. Identity matching
Claims are matched to facts by the subject identifier named in the contract (for example a conversation ID). Cross-system links (helpdesk requester → billing customer) are only made on exact matches of a documented key, and every link is recorded on the claim's evidence page. Fuzzy matching is not used.
5. Windows and periods
Windows (for example "not reopened within 7 days") are evaluated from the anchoring fact's timestamp in UTC. A run for a period evaluates facts up to the run time, so a statement generated shortly after month end may show fewer reopen findings than one generated later; the statement records its generation time and the connection watermarks used.
6. Transcript assist
Optional, off by default, and cost-capped. When enabled, a sampled subset of verified claims is labeled by a language model (customer confirmed resolved / indicated unresolved / abandoned / unclear) using a redacted excerpt. Humans review a portion of the labels in the calibration queue; agreement is reported on the statement. Labels never change a verdict.
7. Integrity
Each verdict is serialised, hashed with SHA-256, and chained to the previous verdict's hash. The statement hash is the head of the chain. The public verification page confirms that a hash corresponds to a statement CommitLayer produced and that its chain is intact. Evidence pointers include the sha256 of the record consulted so a vendor can check them against their own copy.
8. Reproducibility
Statements record the contract version, engine version, and connection watermarks. Re-running the same contract version against the same facts produces the same verdicts and hash.
9. What this is not
CommitLayer does not judge whether a vendor's definition is fair, and it does not accuse anyone of anything. It reports what the facts support under each lens, and reports separately what it could not check.