G-007 — Define `Nugget` As Typed Artifacts

G-007 — Define Nugget As Typed Artifacts

Status: drafted → reviewed → accepted → closed.
Author: driver-claude
Date: 2026-05-06

1. The defect being fixed

The original platform plan referenced a generic Nugget envelope. Per audits/manthan-platform-review.md §7-F8 and §8-F1: an undefined "nugget" is content-policy unaccountable, schema-less, and impossible to verify beyond signature.

G-007 replaces the generic Nugget with a small set of typed artifacts, each with an explicit JSON Schema, signing rules, and verifier-visible acceptance checks. The MVP wedge (G-001) needs at least transcription and handoff_receipt; the rest can land in Phase 2.

2. Five canonical typed artifacts

Each is an attestation of the named type, carried in a HERALD envelope per [SPEC §3]. Each registers a domain-separation tag in [EXT §13] (per G-008).

2.1 research_finding

A signed claim that an agent investigated a question and produced a finding. Used by the Churn engine in Phase 2+.

{
  "type": "research_finding",
  "value": {
    "question":         "<freeform string, ≤ 1024 chars>",
    "finding":          "<freeform string OR hash of larger document>",
    "finding_hash":     "<sha256 hex; required if finding is hash>",
    "evidence":         [
      { "envelope_id": "<id>", "claim": "supports|refutes|contextualises", "weight": 0.0..1.0 },
      ...
    ],
    "confidence":       0.0..1.0,
    "uncertainty_note": "<freeform; recommended>",
    "source_traces":    [ "<trace_id>", ... ],
    "created_at":       <Unix seconds>
  }
}

Domain-separation tag: herald.research_finding.v1.

Verifier acceptance checks:

• Evidence envelopes referenced by evidence[].envelope_id MUST exist in the verifier's accessible CT log set.
• Each evidence envelope's signature MUST verify.
• confidence ∈ [0.0, 1.0].
• finding_hash MUST match SHA-256(finding) if finding is text; MUST be present if finding is a hash reference.
• created_at within reasonable skew of envelope ts.

2.2 transcription

A Scribe-emitted summary or transcript of an agent interaction. Used in the MVP wedge (G-001).

{
  "type": "transcription",
  "value": {
    "of_envelopes":    [ "<envelope_id>", ... ],   ≥ 1
    "covers_trace":    "<trace_id>",
    "transcript_hash": "<sha256 hex of full transcript>",
    "digest":          "<freeform short summary, ≤ 2048 chars>",
    "method":          "verbatim|summary|extractive_digest|llm_paraphrase",
    "scribe_sigil":    "<sigil:...>",
    "scribe_charter_url": "<URL>",
    "created_at":      <Unix seconds>
  }
}

Domain-separation tag: herald.transcription.v1.

Verifier acceptance checks:

• All envelopes in of_envelopes[] exist in the trace covers_trace.
• scribe_sigil matches the envelope's from.
• If method == "verbatim", transcript_hash MUST match the canonical concatenation of the source envelopes' bodies.
• If method == "llm_paraphrase", a warning is surfaced per G-001 AC-6 (lossy summary).

2.3 lineage_evidence

An attestation that supplies independent evidence about a sigil's lineage claim. Distinct from a Herald's lineage_endorsement because it can be issued by anyone (a regulator, a peer agent, a third-party auditor).

{
  "type": "lineage_evidence",
  "value": {
    "subject":           "<sigil:...>",
    "claimed_parent":    "<sigil:...>",
    "evidence_kind":     "model_hash_match|training_provenance|operator_disclosure|behavioural_signature",
    "evidence_payload":  <Cbor>,                  // type-specific
    "verification_url":  "<URL>",                 // optional; where evidence can be reproduced
    "issued_by":         "<sigil:...>",
    "issued_at":         <Unix seconds>,
    "valid_until":       <Unix seconds>           // recommended ≤ 90 days
  }
}

Domain-separation tag: herald.lineage_evidence.v1.

Verifier acceptance checks:

• subject and claimed_parent are valid sigil syntax.
• issued_by matches envelope from.
• evidence_kind is in the registered set; unknown kinds → reject.

2.4 capability_observation

A signed claim that one agent observed another agent's capability invocation. Useful for distributed Bestiary-style honest reporting.

{
  "type": "capability_observation",
  "value": {
    "observed_sigil":     "<sigil:...>",
    "capability":         "<capability-string from registries/capabilities.md>",
    "outcome":            "succeeded|failed|refused|partial",
    "context":            "<freeform; ≤ 512 chars>",
    "observation_envelope_ids": [ "<id>", ... ],     // envelopes this observation references
    "observed_at":        <Unix seconds>
  }
}

Domain-separation tag: herald.capability_observation.v1.

Verifier acceptance checks:

• capability is in registries/capabilities.md (T-112).
• observation_envelope_ids[] are real envelopes.
• outcome is one of the four enums.

2.5 handoff_receipt

Acknowledges that one agent has handed off a task to another. Used in the MVP wedge (G-001) when Agent A's task envelope is accepted by Agent B.

{
  "type": "handoff_receipt",
  "value": {
    "task_envelope":   "<envelope_id>",        // the original task envelope
    "from":            "<sigil:...>",          // accepting agent
    "to":              "<sigil:...>",          // initiating agent
    "accepted":        true | false,
    "decline_reason":  "<refusal-code from registries/refusal-reasons.md>",  // present iff !accepted
    "estimated_completion_ts": <Unix seconds, optional>,
    "ts":              <Unix seconds>
  }
}

Domain-separation tag: herald.handoff_receipt.v1.

Verifier acceptance checks:

• task_envelope exists in a CT log accessible to the verifier.
• If accepted == false, decline_reason MUST be in registries/refusal-reasons.md.
• If accepted == true, decline_reason MUST be absent.
• from matches envelope from.
• to matches the task_envelope's from.

3. Required fields shared by all artifacts

Every typed artifact carrying envelope MUST have:

Per G-002, signing scope is origin for the long-term key; session-scope variants per [EXT §6.1] are permitted via progressive multi-signature.

4. CT-log inclusion policy

Per [EXT §1.3] state-transition envelopes (birth, molt, deprecation, lineage_endorsement) MUST be CT-logged. For typed artifacts, Manthan adds:

5. Schema validation

Each artifact MUST validate against the JSON Schema at registries/typed-artifacts/<name>.schema.json (Phase 1 deliverable). Verifiers reject envelopes whose attestation fails schema validation.

The five schemas are:

• registries/typed-artifacts/research-finding.schema.json
• registries/typed-artifacts/transcription.schema.json
• registries/typed-artifacts/lineage-evidence.schema.json
• registries/typed-artifacts/capability-observation.schema.json
• registries/typed-artifacts/handoff-receipt.schema.json

These are JSON Schema Draft 2020-12 documents (per worker-B's T-012 dialect choice), with additionalProperties: false.

6. Domain-separation tag registration

Five tags need registration in [EXT §13]:

herald.research_finding.v1
herald.transcription.v1
herald.lineage_evidence.v1
herald.capability_observation.v1
herald.handoff_receipt.v1

This is a G-008 deliverable.

7. What G-007 does NOT cover

• Generic Nugget — explicitly retired. Manthan does not ship a typed-artifact-without-type.
• Free-form arbitrary content envelopes — the protocol can carry them via payload Cbor, but they are not normative artifacts; verifiers cannot assert anything beyond signature validity.
• Schemas for future artifact types — additions follow the registration process in registries/refusal-reasons.md §"Registration process" (propose → discuss → promote).

8. Acceptance criteria

• [x] Five typed artifacts defined with JSON shape + Cbor type rules + verifier acceptance checks.
• [x] CT-log inclusion policy per artifact.
• [x] Schema files flagged as Phase-1 deliverables (5 .schema.json files).
• [x] Domain-separation tags flagged for G-008.
• [x] Generic Nugget retired: this gate is the formal "delete the term".

9. Sign-off

• [x] drafted → this document
• [x] reviewed → against registries/standard-attestations.md (T-012 patterns), registries/refusal-reasons.md (D-310 codes used in handoff-receipt), registries/capabilities.md (T-112), [EXT §1.3], [EXT §13]
• [x] accepted → five artifacts cover the MVP wedge + Phase-2 churn surface; schemas tractable for Phase 1
• [x] closed → G-007 closed; schemas + tag registration are downstream tasks

— G-007 closed, 2026-05-06.