> ## Documentation Index
> Fetch the complete documentation index at: https://doc.blueapi.ir/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Provenance Record and Verification Chain

> Specification for model provenance in EMEP, covering provenance record schema, signed provenance chains, and the verification algorithm with flowchart.

Model provenance records the complete history of how a model was created, including all inputs, transformations, and approvals. EMEP uses cryptographically signed provenance chains to guarantee integrity. This page specifies the provenance record schema, signing protocol, and verification algorithm.

## Provenance Record Schema

| Field                   | Type          | Description                                     |
| ----------------------- | ------------- | ----------------------------------------------- |
| provenance\_id          | string        | Unique identifier                               |
| model\_id               | string        | Model this record describes                     |
| timestamp               | ISO8601       | Record creation time                            |
| creator                 | string        | User or system component that created the model |
| parent\_provenance\_ids | List\[string] | References to parent provenance records         |
| experiment\_id          | string        | Experiment that produced the model              |
| inputs                  | object        | Hashes of all input artifacts                   |
| transformations         | List\[object] | Merge operations, fine-tuning, quantization     |
| approvals               | List\[object] | Signatures from reviewers or automated checks   |
| signature               | string        | Cryptographic signature of this record          |

## Inputs Block

```json theme={null}
{
  "parent_models": [
    {"model_id": "model_a", "hash": "sha256:abc..."},
    {"model_id": "model_b", "hash": "sha256:def..."}
  ],
  "datasets": [
    {"dataset_id": "dataset_v1", "hash": "sha256:ghi..."}
  ],
  "code": {
    "git_commit": "abc123",
    "hash": "sha256:jkl..."
  }
}
```

## Transformations Block

Each transformation records:

| Field         | Description                         |
| ------------- | ----------------------------------- |
| type          | merge, finetune, quantize, evaluate |
| parameters    | Operation-specific parameters       |
| input\_hashes | Artifacts consumed                  |
| output\_hash  | Artifact produced                   |
| timestamp     | Execution time                      |

## Approvals Block

```json theme={null}
{
  "approvals": [
    {
      "approver": "automated_safety_check",
      "timestamp": "2024-01-15T10:00:00Z",
      "result": "pass",
      "signature": "sig:..."
    },
    {
      "approver": "human_reviewer_1",
      "timestamp": "2024-01-15T11:00:00Z",
      "result": "approved",
      "signature": "sig:..."
    }
  ]
}
```

## Signing Protocol

Each provenance record is signed using the creator's private key. The signature covers the canonical JSON serialization of the record (excluding the signature field itself).

```text theme={null}
canonical_json = canonicalize(record_without_signature)
signature = sign(private_key, sha256(canonical_json))
record.signature = signature
```

## Verification Algorithm

```mermaid theme={null}
flowchart TD
    START([START]) --> LOAD[Load Provenance Record]
    LOAD --> CANON[Canonicalize JSON]
    CANON --> HASH[Compute SHA-256]
    HASH --> VERIFY[Verify Signature]
    VERIFY -->|Invalid| FAIL1[Fail: Signature Invalid]
    VERIFY -->|Valid| INPUTS[Verify Input Hashes]
    INPUTS -->|Mismatch| FAIL2[Fail: Input Tampered]
    INPUTS -->|Match| PARENTS[Verify Parent Provenance]
    PARENTS -->|Invalid| FAIL3[Fail: Parent Chain Broken]
    PARENTS -->|Valid| APPROVALS[Verify Approvals]
    APPROVALS -->|Invalid| FAIL4[Fail: Approval Missing]
    APPROVALS -->|Valid| SUCCESS[Provenance Verified]
    FAIL1 --> END1([END])
    FAIL2 --> END1
    FAIL3 --> END1
    FAIL4 --> END1
    SUCCESS --> END2([END])
```

## Verification Steps

1. **Signature verification**: confirm the record was signed by the claimed creator
2. **Input hash verification**: confirm all input artifacts match their recorded hashes by querying the ArtifactStore
3. **Parent provenance verification**: recursively verify all parent provenance records
4. **Approval verification**: confirm all required approvals are present and valid

## Trust Anchor

Base models (models with no parents) have self-signed provenance records. Their trust is established by:

* Download source verification (for example HuggingFace repository)
* Hash matching against known good values
* Manual audit for internal base models

## Integration

| Component         | Role                                     |
| ----------------- | ---------------------------------------- |
| ModelRegistry     | Stores provenance\_id in model records   |
| ArtifactStore     | Stores provenance records and signatures |
| ExperimentTracker | Logs transformation events               |
| Security system   | Manages signing keys and verification    |

<Info>
  Provenance verification is recursive. Verifying a model requires verifying all ancestors. The verification algorithm caches results to avoid redundant computation.
</Info>

<Warning>
  A broken signature, mismatched input hash, or missing approval invalidates the entire provenance chain. The model cannot be released or deployed until the chain is repaired or manually overridden with full audit logging.
</Warning>