Finding Records

Proposed chio.finding.v1 Record

The design defines four companion schemas: chio.finding.challenge.v1 for a challenge filed against a finding, chio.finding.status-epoch.v1 for the epoch-scoped record status_feed_ref points at, and a generic and finding-specific delivery pair, chio.delivery-contract.v1 and its chio.finding.delivery.v1 overlay. The rows below specify fields for the signed chio.finding.v1 body.

Illustrative Null Result

This illustrative record represents a metered, attested scan that ruled out a class of exploit.

{
  "schema": "chio.finding.v1",
  "finding_id": "3f8a1c9e2b47d605f8a1c4b7e0d3f6a9c2b5e8f1a4d7c0b3e6f9a2c5b8e1d4f7",
  "descriptor": {
    "topic": "vuln-scan/openssl-3.x/heap-overflow",
    "context_sha256": "9c2b5e8f1a4d7c0b3e6f9a2c5b8e1d4f3f8a1c9e2b47d605f8a1c4b7e0d3f6a9",
    "outcome_class": "null_result"
  },
  "guarantee_class": "metered_attested",
  "payload_sha256": "7d605f8a1c4b7e0d3f6a9c2b5e8f1a4d3f8a1c9e2b47d0c3e6f9a2c5b8e1d4f7",
  "payload_media_type": "application/json",
  "evidence_receipt_ids": [
    "7c1e5a2b9d34f60e8a1b4c7d0e3f6a9b2c5d8e1f4a7b0c3d6e9f2a5b8c1d4e70",
    "b8d2f47a06c19e35d7a0b3c6e9f2a5b8c1d4e70f3a6b9c2d5e8f1a4b7c0d3e69"
  ],
  "evidence_checkpoint_ref": "chk_2f6a9c2b5e8f1a4d7c0b3e6f9a2c5b8e",
  "evidence_cost": {
    "units": 4200,
    "currency": "USD"
  },
  "runtime_assurance_tier": "attested",
  "evidence_class": "observed",
  "bond_ref": "bond_5e8f1a4d7c0b3e6f9a2c5b8e1d4f73f8",
  "status_feed_ref": "feed_finding_3f8a1c9e2b47d605",
  "license_ref": "lic_research-use-only-v1",
  "price_hint_ref": "price_finding-null-result-tier2",
  "issuer": "ts-acme-vuln-scan-01",
  "issued_at": 1784581200,
  "expires_at": 1787173200,
  "signature": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6"
}

Two fields are absent on purpose: replay_recipe_sha256, because guarantee_class here is metered_attested, not deterministic_replay, and intent_commitment_receipt_id, because this seller made no pre-outcome commitment. Both are legal omissions, not missing data.

Outcome Class

descriptor.outcome_class takes one of three values: null_result, verified_fix, or positive_result. A negative result, an approach an agent has shown not to work, uses the value null_result on the exact same chio.finding.v1 record.

Guarantee Class vs. Evidence Class

guarantee_class and evidence_class look alike and answer different questions. guarantee_class (deterministic_replay / metered_attested / asserted) is the re-checkability tier: how far a buyer can re-derive or re-check the result after paying. evidence_class (asserted / observed / verified) is the claim-to-evidence taxonomy: what kind of process stands behind the underlying claim in the first place. They are distinct fields; one does not determine the other.

The Reveal Commitment

payload_sha256 is not a hash of the raw payload bytes. It is the digest of the canonical reveal envelope delivered to a buyer. The envelope shape and settlement binding are specified on Reveal & Settlement; this page; this page defines the field commitment.

Evidence, Cost, and Runtime Assurance

evidence_receipt_ids and evidence_checkpoint_ref point at the backing signed receipts and the Merkle checkpoint that covers them, so a buyer can confirm the receipts existed at a specific, provable point in time. evidence_cost, an object with units and currency, is verifiable against those receipts only in full-receipt mode; outside it, evidence_cost is a seller assertion standing until the finding is audited.

replay_recipe_sha256 is required exactly when guarantee_class is deterministic_replay, and absent otherwise. runtime_assurance_tier is optional and shares its closed, four-tier vocabulary with runtime assurance elsewhere in chio: none / basic / attested / verified.

bond_ref names the slashable bond (slashable: true) backing the finding, sized against the audit regime on Pricing, Bonds & Audits. status_feed_ref names its retraction and status feed.

Actor Kind

Findings do not add a new subject kind to the marketplace. GenericListingActorKind (see Discovery) is closed and wire-frozen at four variants: ToolServer, CredentialIssuer, CredentialVerifier, and LiabilityProvider. A finding lists under the existing ToolServer kind: the seller's tool server is what gets listed, with metadata_url and resolution_url on that listing pointing at the Finding record itself.

The finding identity is in the listing pricing hint at a capability_scope of finding:<finding_id>. price_hint_ref on the finding record points back at that same pricing hint.

Planned Schema Registration

Implementing chio.finding.v1or a companion schema would require these updates:

1. The schema. A JSON Schema file under spec/schemas/chio-finding/v1/.
2. The registry. A row in spec/schemas/registry.json, plus the matching update to MANIFEST.sha256.
3. The typed constant. A CHIO_FINDING_*_SCHEMA const and a SIGNED_ARTIFACT_SPECS row in chio-core-types.
4. The protocol doc. A PROTOCOL.md section describing the record.

The planned intake path validates raw JSON against the registered schema before verify_finding runs at all; a payload that fails schema validation does not reach semantic verification. See Schemas and Errors for the registry and manifest requirements used by Chio schemas.

Next Steps

• The Cognition Market · the market a finding is the priced, governed good inside
• Reveal & Settlement · the exact reveal-envelope definition payload_sha256 commits to
• Pricing, Bonds & Audits · how evidence_cost, bond_ref, and audits price and back a finding
• Receipts · the signed receipts evidence_receipt_ids reference
• Schemas and Errors · the registration and validation discipline behind every Chio schema