RFC-0055 · Claim and Evidence Model
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
Read design questions and decisions →
Status: draft consolidation. This RFC pulls the
Claim<T>model out of RFC-0006 (where it lives in the type-system section) and the language-level claim-declaration form out of RFC-0008, into a single normative home. It adds the diagnostics taxonomy that has been implicit across the spec and formalizes the boundary with RFC-0009’s AI-actor obligations.The cross-cutting concern analyzer at
docs/analysis/cross-cutting.md(see spec source) rankedClaim/Claim<T>as #2 by score (30 claims across 6 RFCs, 23 distinct predicates). This RFC is the proposed consolidation.
1. Purpose
Claim<T> is Gnomon’s primary mechanism for distinguishing values from
assertions about values. Any field that may be produced or modified by an
AI actor MUST be typed as Claim<T> rather than bare T. A field extracted
from a document or inferred from a rule SHOULD use Claim<T> unless another
normative rule requires the wrapper. The wrapper carries provenance,
confidence, and epistemic status, and the type system propagates it through
composition and refinement.
Until now the model has been split:
- RFC-0006 §4.5 declares
Claim<T>as a value type and specifies theClaimStatusflow (pending → confirmed → disputed → superseded → retracted). - RFC-0008 §6.11 specifies the language-level
claimfile declaration (the authoring surface). - RFC-0009 specifies AI-actor obligations to produce
Claim<T>and populate evidence fields.
The split has worked, but it forces every reader interested in claims to
triangulate three RFCs. The cross-cutting analyzer flagged 23 distinct
predicates citing Claim across the corpus — a load-bearing concept whose
single-source-of-truth is unclear.
This RFC consolidates the model. It does not introduce new semantics; it reorganizes existing material under a single ownership boundary and adds the diagnostic taxonomy that was implicit.
2. Definitions
| Term | Meaning |
|---|---|
| Claim<T> | A value-type wrapper that pairs a value T with provenance, confidence, an epistemic status, and zero or more evidence links. |
| Evidence | A reference to a supporting document, statement, or rule output that justifies a claim. |
| Provenance | The actor (human, AI agent FQN, importer, rule) and timestamp that asserted a claim. |
| Confidence | A numeric score in [0, 1] or a labeled interval (low, medium, high) that estimates the assertion’s reliability. |
| ClaimStatus | The normative flow declaration governing an epistemic state machine over claims (RFC-0006 §4.5). |
| Subflow | A user-declared flow that is ClaimStatus, restricting transitions to a subset (e.g., PlanRecommendationStatus). |
| Evidence link | A typed reference (document:, statement:, rule:) to a corroborating artifact. |
| Bare T | A field typed as T without the Claim<T> wrapper; used for values whose authority is the system itself. |
3. The wrapper
The Claim<T> model has seven normative fields. At evaluation time, every
claim MUST carry value, source, asserted_by, asserted_at, and status.
confidence is required for agent and system sources; evidence_links
is required when the declaration’s evidence_required policy names one or
more kinds. Other sources MAY supply either field. Implementations MUST
surface all seven in their schema:
Claim<T> {
value: T // the asserted value
source: ClaimSource // who/what produced the assertion
confidence: Confidence // numeric or labeled reliability score
asserted_by: Identifier // actor FQN (human, agent, system)
asserted_at: Instant
status: ClaimStatus // see §4
evidence_links: List<EvidenceLink>
}
Serialization MAY omit fields that are not required for that claim’s source
and evidence policy. It MUST NOT omit a field required at evaluation time;
an agent claim without evidence links is permitted only when its declaration
does not require evidence and emits M55040. Diagnostic codes for missing
required fields are introduced in §7. A claim whose declaration requires
evidence MUST carry at least one link of each required kind (M55013).
3.1 ClaimSource
ClaimSource is a closed variant:
| Variant | Meaning |
|---|---|
human | Asserted by a named human user. asserted_by is their identifier. |
agent | Asserted by an AI agent. asserted_by is the agent’s FQN. RFC-0009 §6 specifies the additional obligations (prompt, model, confidence floor). |
import | Imported from an external system. asserted_by is the importer’s FQN. |
rule | Derived from a rule evaluation. asserted_by is the rule’s FQN; evidence_links MUST cite the rule’s input statements. |
system | Asserted by the runtime itself (e.g., audit values). MUST set confidence: 1.0 and status: confirmed. |
3.2 Confidence
Confidence is either:
- A
Decimalin[0.0, 1.0], OR - A labeled enum:
low | medium | high.
Mixing both forms within a single module is permitted but discouraged. Authorities published by AI agents MUST be numeric (RFC-0009 §6.3).
4. ClaimStatus and subflows
ClaimStatus is the normative flow declared in RFC-0006 §4.5. The
canonical states are pending, confirmed, disputed, superseded,
retracted. A module MAY declare a subflow (flow X is ClaimStatus) to
restrict transitions, but MUST NOT add new states outside the canonical
five.
Minimum required states: every implementation MUST support pending and
confirmed. The other three are normative but conditional on the module’s
domain.
4.1 Subflow rules
- A subflow MUST list all canonical states it admits.
- A subflow MUST NOT add states beyond the canonical five (M55020).
- A subflow MAY restrict transitions (e.g., disallow
confirmed → disputed). - A subflow MUST be declared in the same module as the
claimdeclaration it governs, OR explicitly imported and named in the claim’sstatus_flow:field.
5. Authoring surface
The .gnm language surface for declaring a claim type (RFC-0008 §6.11):
claim PlanRecommendation {
value: PlanProposal
status_flow: PlanRecommendationStatus
confidence: Decimal
evidence_required: [ document, statement ]
}
Compiles into a Claim<PlanProposal> wrapper with the named status flow
and the runtime requirement that every assertion carry at least one
document and one statement evidence link.
evidence_required is a list of EvidenceLink kinds; an empty list permits
unevidenced claims (allowed for system-source claims; warning for
agent-source).
These link kinds (document, statement, rule) govern references attached
to an assertion. They are distinct from the core.claims.EvidenceKind values
in RFC-0035, which classify stored EvidenceRecord instances.
6. Composition and refinement
Claim<T> is monotone in T: if T <: T', then Claim<T> <: Claim<T'>.
Recursive Claim<Claim<T>> is prohibited. Wrapping is one level deep —
the outer claim always supersedes the inner one for evidence purposes. This
is the rule formerly at RFC-0006 §4.5 / M06524, renumbered here as M55030.
Claim<Unit> is permitted as a “claim that an event happened” — useful for
audit-only assertions where the value is irrelevant.
7. Diagnostics
All diagnostics in this RFC occupy the M55000–M55099 range.
| Code | Severity | Description |
|---|---|---|
M55010 | Error | Claim<T> is missing value, source, asserted_by, asserted_at, or status at evaluation time. |
M55011 | Error | Claim<T> from agent source missing confidence (RFC-0009 §6.3). |
M55012 | Error | Claim<T> from system source has confidence < 1.0 or status != confirmed. |
M55013 | Error | An assertion omits every evidence_links entry of a kind named by its declaration’s evidence_required policy. |
M55020 | Error | Subflow is ClaimStatus declares a state outside the canonical five. |
M55021 | Warning | Subflow declares no confirmed transition; claims will never become authoritative. |
M55030 | Error | Recursive wrapping detected: Claim<Claim<T>> is prohibited. |
M55040 | Warning | claim declaration with evidence_required: [] and agent source — unevidenced AI claim. |
M55050 | Error | evidence_links references a statement whose subject is not the claim’s value. |
RFC-0006’s M06520 remains the error for an unwrapped AI field. This RFC’s M55010–M55030 diagnostics cover the distinct Claim value, flow, and nesting conditions described in this table. The first release has no deployed diagnostic consumers to migrate.
8. First-release alignment
This draft consolidates the Claim model for the first release:
- Compiler: enforce RFC-0006’s M06520 error for unwrapped AI fields and this RFC’s M55010–M55030 conditions for Claim values and flows.
- Documentation: align RFC-0006 §4.5 and RFC-0008 §6.11 with this contract before accepting this draft as normative.
- Tooling: the IDE (RFC-0017 LSP) MUST recognize both diagnostic ranges.
9. Invariants
- Every
Claim<T>MUST carryvalue,source,asserted_by,asserted_at, andstatusat evaluation time (M55010).confidenceis conditionally required by source, and at least oneevidence_linksentry of each required kind is required by the declaration’s policy (M55013). Claim<Claim<T>>is rejected at type-check time (M55030).- Subflows of
ClaimStatusMUST NOT introduce new states (M55020). - AI-agent claims MUST carry numeric
confidence(M55011, RFC-0009 §6.3). system-source claims MUST beconfirmedwithconfidence: 1.0(M55012).- Unevidenced
agentclaims emit warning M55040; the runtime MAY accept them but a published policy MAY reject them.
10. Open questions
These draft questions and their deferral triggers are tracked in the RFC-0055 companion Q&A.
11. Linked References
- RFC-0006 §4.5 — the original
Claim<T>declaration this RFC consolidates. - RFC-0008 §6.11 —
claimfile authoring surface; semantics defer here. - RFC-0009 §6 — AI-actor evidence obligations.
- RFC-0017 — LSP must handle the diagnostic-code remap.
- RFC-0047 §3 — audit observations record
Claim<T>provenance fields.