sica-fondt/core/docs/plans/M6-provenance-chain.md

M6 — Provenance chain

1. Component

The chain of custody through the stomach: tracks where input came from and what the stomach did to it, so that digested content is never mistaken for original content and Ada (D1) can enforce S1/S2 with full information. Solves the provenance question from the economy organ review: the stomach transforms external input into organ-secretion output, but the origin must not be lost.

2. Status / certainty

DESIGN-FIRST · ABSENT. The current smoke test sets OrganSecretion provenance on stomach output (main.pony:29) with no record of the original input's provenance. This is the gap that risks S1/S2 violation. Role C4 (the need is clear); implementation C1.

3. Language & location

TBD · part of src/economy/. Likely a data structure carried alongside digested context, not a separate service. Must be representable in both Pony (bus side) and Ada (border side).

4. Does / does-not

• Does: create a ProvenanceChain for each input entering the stomach; record each transformation step (ingestion, classification, digestion, yield); attach the chain to the yielded envelope (M5) so Ada sees the full history; enable Ada to distinguish "organ-processed external input" from "organ-generated internal content".
• Does-not: decide trust (Ada does); authenticate sources (the bus provenance system does); filter or reject based on provenance (M0-L2 — digestion doesn't suppress).

5. Interface contract

• chain_start(original_provenance: Provenance, source: OrganId, input_hash: str) -> ProvenanceChain.
• chain_step(chain: ProvenanceChain, step: TransformStep) -> ProvenanceChain. TransformStep { stage, transformer, timestamp }. stage ∈ { ingested, classified, digested, yielded }.
• The final ProvenanceChain is:

  { original_provenance: Provenance,   -- what the input was before the stomach
    original_source: OrganId,           -- who sent it (World, MoRAG, etc.)
    input_hash: str,                    -- hash of raw input for audit
    steps: [TransformStep],             -- what the stomach did, in order
    is_external_origin: bool }          -- convenience flag for Ada: TRUE if
                                        --   original_provenance ∈ {External, UserInput}
  

• is_external_origin lets Ada apply S1 screening to digested-but-originally-external content without parsing the full chain.

6. Dependencies & stubs

• Ichor Provenance / OrganId (existing) — input types.
• M1 ingestion — creates the chain at ingested step.
• M2 digestion — adds the digested step.
• M5 context yield — attaches the chain to the envelope; stub: pass-through.
• Ada D1 Trust_Guard — consumer of the chain; stub: print chain on receipt.

7. Invariants / laws

• L1 (C5): the chain is immutable once created — steps are appended, never modified or removed. Like the COBOL invariant vault (S3), the provenance record doesn't get rewritten.
• L2 (C5): S2 compliance — the original provenance is never reclassified. The bus transport field may say OrganSecretion (because the stomach is an organ emitting output), but original_provenance in the chain preserves the true origin. This is not reclassification; it's layered provenance.
• L3 (C4): S1 compliance — content with is_external_origin = TRUE tells Ada that this traffic originated externally even though it arrives as organ output. Ada applies its full external-traffic screening (rate, blocklist, trust) to such content.
• L4 (C3): the input_hash allows audit verification — given the original input and the hash, you can confirm the chain refers to the right content.

8. Build steps

1. Define ProvenanceChain and TransformStep shapes.
2. Wire chain creation in M1 (ingestion) and step-append in M2 (digestion).
3. Wire chain attachment in M5 (yield → envelope metadata).
4. Extend Ada's Trust_Guard (or its stub) to read is_external_origin and apply S1 screening.

9. Tests

Chain integrity: steps accumulate in order; no mutation. S2: original provenance survives all transforms. S1: is_external_origin = TRUE for external/user input; FALSE for organ-to-organ. Hash: chain's input_hash matches hash of the raw input.

10. Open items

• Hash algorithm (SHA-256? lightweight alternative for performance?).
• Whether Ada needs the full chain or just is_external_origin + original_provenance (start with the full chain; Ada can ignore what it doesn't need).
• Cross-seam representation (Pony chain → C/Fortran seam → Ada record).