gnomonlearn

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) ranked Claim / 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 the ClaimStatus flow (pending → confirmed → disputed → superseded → retracted).
  • RFC-0008 §6.11 specifies the language-level claim file 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

TermMeaning
Claim<T>A value-type wrapper that pairs a value T with provenance, confidence, an epistemic status, and zero or more evidence links.
EvidenceA reference to a supporting document, statement, or rule output that justifies a claim.
ProvenanceThe actor (human, AI agent FQN, importer, rule) and timestamp that asserted a claim.
ConfidenceA numeric score in [0, 1] or a labeled interval (low, medium, high) that estimates the assertion’s reliability.
ClaimStatusThe normative flow declaration governing an epistemic state machine over claims (RFC-0006 §4.5).
SubflowA user-declared flow that is ClaimStatus, restricting transitions to a subset (e.g., PlanRecommendationStatus).
Evidence linkA typed reference (document:, statement:, rule:) to a corroborating artifact.
Bare TA 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:

VariantMeaning
humanAsserted by a named human user. asserted_by is their identifier.
agentAsserted by an AI agent. asserted_by is the agent’s FQN. RFC-0009 §6 specifies the additional obligations (prompt, model, confidence floor).
importImported from an external system. asserted_by is the importer’s FQN.
ruleDerived from a rule evaluation. asserted_by is the rule’s FQN; evidence_links MUST cite the rule’s input statements.
systemAsserted by the runtime itself (e.g., audit values). MUST set confidence: 1.0 and status: confirmed.

3.2 Confidence

Confidence is either:

  • A Decimal in [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 claim declaration it governs, OR explicitly imported and named in the claim’s status_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.

CodeSeverityDescription
M55010ErrorClaim<T> is missing value, source, asserted_by, asserted_at, or status at evaluation time.
M55011ErrorClaim<T> from agent source missing confidence (RFC-0009 §6.3).
M55012ErrorClaim<T> from system source has confidence < 1.0 or status != confirmed.
M55013ErrorAn assertion omits every evidence_links entry of a kind named by its declaration’s evidence_required policy.
M55020ErrorSubflow is ClaimStatus declares a state outside the canonical five.
M55021WarningSubflow declares no confirmed transition; claims will never become authoritative.
M55030ErrorRecursive wrapping detected: Claim<Claim<T>> is prohibited.
M55040Warningclaim declaration with evidence_required: [] and agent source — unevidenced AI claim.
M55050Errorevidence_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:

  1. Compiler: enforce RFC-0006’s M06520 error for unwrapped AI fields and this RFC’s M55010–M55030 conditions for Claim values and flows.
  2. Documentation: align RFC-0006 §4.5 and RFC-0008 §6.11 with this contract before accepting this draft as normative.
  3. Tooling: the IDE (RFC-0017 LSP) MUST recognize both diagnostic ranges.

9. Invariants

  1. Every Claim<T> MUST carry value, source, asserted_by, asserted_at, and status at evaluation time (M55010). confidence is conditionally required by source, and at least one evidence_links entry of each required kind is required by the declaration’s policy (M55013).
  2. Claim<Claim<T>> is rejected at type-check time (M55030).
  3. Subflows of ClaimStatus MUST NOT introduce new states (M55020).
  4. AI-agent claims MUST carry numeric confidence (M55011, RFC-0009 §6.3).
  5. system-source claims MUST be confirmed with confidence: 1.0 (M55012).
  6. Unevidenced agent claims 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 — claim file 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.