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

# Transparency Log Schema

> Canonical row shape for the append-only canonical-card transparency log (v1). Sigstore-Rekor-compatible mapping documented.

The canonical row shape for the [transparency log](/concepts/transparency-log).

## Row shape

JSON object conforming to JSON Schema 2020-12. All required fields below; `additionalProperties: false`.

| Field | Type | Description |
| - | - | - |
| `log_index` | integer (≥ 1) | Monotone log position. Determines leaf ordering for the Merkle tree. |
| `agent_id` | string | Mnemom agent identifier. Matches `agents.agent_id`. |
| `card_kind` | enum `"alignment" \| "protection"` | Which canonical card kind this row attests to. |
| `content_hash` | string (`^[0-9a-f]{64}$`) | SHA-256 hex of the canonical card body at composition time. |
| `version` | integer (≥ 1) | Canonical-card version at composition time. |
| `composed_at` | string (date-time) | ISO-8601 UTC composition timestamp. |
| `signed_attestation` | string | Full [AAP attestation token](/specifications/attestation-token) (JWS Compact). |
| `signing_key_id` | string | Foreign key into `signing_keys.key_id`. Identifies which key signed `signed_attestation`. |
| `merkle_leaf_hash` | string (`^[0-9a-f]{64}$`) | SHA-256 hex of `0x00 \|\| canonical_json({agent_id, card_kind, content_hash, version, composed_at})`. |
| `tree_size_after` | integer (≥ 1) | Size of the Merkle tree immediately after this row's inclusion. |
| `integrated_time` | string (date-time) | Wall-clock time at which this row was appended (server-side). Distinct from `composed_at` for backfill rows. |

## Inclusion proof shape

Returned by the by-index + at-timestamp endpoints alongside the row:

```jsonc theme={null}
{
  "entry": { /* row above */ },
  "inclusion_proof": {
    "leaf_hash": "<sha256-hex>",
    "log_index": 4711,
    "tree_size": 12345,
    "hashes": [
      { "sibling": "<sha256-hex>", "position": "right" },
      { "sibling": "<sha256-hex>", "position": "left" }
    ]
  }
}
```

`position` describes which side of the pair the sibling occupies — `right` means `H(0x01 || current || sibling)`, `left` means `H(0x01 || sibling || current)`. The verifier walks the proof bottom-up and compares the result against the [signed root](/concepts/transparency-log#endpoints).

## Merkle tree construction

| Property | Value |
| - | - |
| **Leaf hash** | `SHA-256(0x00 \|\| canonical_json(...))` |
| **Internal hash** | `SHA-256(0x01 \|\| left \|\| right)` |
| **Leaf ordering** | by `log_index ASC` |
| **Odd-count** | last unpaired hash promoted unchanged — this bottom-up rule is root-equivalent to RFC 6962 §2.1's `MTH` recursion for every tree size, so RFC 6962 consistency proofs apply as-written. (RFC 6962 does **not** duplicate the last node; *duplicate*-last is Bitcoin's convention, and the source of Bitcoin's CVE-2012-2459 duplicate-txid malleability — don't conflate the two.) |
| **Persistence** | none; rebuilt on demand from rows. Layer arrays are cached for 60s; cache busts on every append. |

The offline CLI verifier (`mnemom verify-card`) mirrors the server-side implementation byte-for-byte.

## Append discipline

| Property | Detail |
| - | - |
| DB-level append-only | Service role has `SELECT + INSERT` only (no `UPDATE`/`DELETE`/`TRUNCATE`), **and** a `BEFORE UPDATE OR DELETE` row trigger + `BEFORE TRUNCATE` statement trigger additionally block mutation at the table level — including for the table owner, which a `REVOKE` alone doesn't cover. See [Append discipline](/concepts/transparency-log#append-discipline). |
| Tamper detection | The signed-tree-head monitor stores each signed root and proves the next one is an append-only RFC 6962 consistency-proof extension of it, so a rewrite becomes evident on the next monitor tick even in the (unenforceable) case of a superuser disabling the trigger. |
| Idempotent | UNIQUE INDEX on `(agent_id, card_kind, content_hash, version)` |
| Compose hook | Best-effort post-commit; 5-minute reconciler closes gaps |
| Backfill | One-shot script for canonical rows that pre-date the log; marks tokens with `historic_backfill: true` |

## Rekor mapping

The row shape is intentionally [Sigstore Rekor](https://www.sigstore.dev/rekor)-shaped so the future migration is a data move rather than a schema rewrite:

| Mnemom column | Rekor entry field |
| - | - |
| `log_index` | `LogIndex` |
| `integrated_time` | `IntegratedTime` (RFC 3339 → Unix epoch) |
| `signing_key_id` | `Body.spec.signature.publicKey.content` |
| `signed_attestation` | `Body.spec.envelope` (DSSE envelope wrap) |
| `merkle_leaf_hash` | `Verification.InclusionProof.LeafHash` |
| `tree_size_after` | `Verification.InclusionProof.TreeSize` |
| (computed on demand) | `Verification.InclusionProof.Hashes` |
| (computed on demand) | `Verification.InclusionProof.RootHash` |

Rekor's entry-kind closest to our shape is [DSSE](https://github.com/secure-systems-lab/dsse).

## Editorial source

Issued, appended, and served server-side by the Mnemom API's transparency-log service, and independently re-verifiable offline with the `mnemom verify-card` command (see the [CLI reference](/gateway/cli)), which mirrors the server-side Merkle implementation byte-for-byte.

## See also

* [Transparency log concept](/concepts/transparency-log)
* [Attestation token schema](/specifications/attestation-token)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.