# GridStamp → IETF COSE Merkle Tree Proofs terminology rename

**Scope:** `draft-ietf-cose-merkle-tree-proofs-18` terminology adoption inside `src/proof/`.
**Why:** Auditors + FAA Part 108 + insurance reviewers read IETF specs; our current field names force mental translation.
**Estimated effort:** 1 day.

## Target terminology map (ours → IETF)

| Current | IETF draft-18 | File(s) affected |
|---|---|---|
| `proof.leaf` | `inclusion_proof.leaf_hash` | `src/proof/tree.ts`, `src/proof/verify.ts` |
| `proof.path[]` | `inclusion_proof.audit_path[]` | `src/proof/tree.ts` |
| `proof.root` | `tree_head.root_hash` | `src/proof/tree.ts`, `src/mcp/tools/*` |
| `proof.index` | `inclusion_proof.leaf_index` | `src/proof/tree.ts` |
| `MerkleProof` type | `COSE_MerkleInclusionProof` | `src/proof/types.ts` |
| `chainHash` | `tree_head.timestamp` + `tree_head.tree_size` separation | `src/proof/chain.ts` |
| `SpatialReceipt` envelope | wrap in `COSE_Sign1` per RFC 9052 | `src/receipt/envelope.ts` |

## Step order (blast-radius-minimizing)

1. Add IETF type aliases as **new exports** next to existing ones (keep old names working)
2. Update internal `src/proof/*` to use new names
3. Update public `index.ts` exports — new names primary, legacy aliased with `@deprecated` JSDoc
4. Update `src/mcp/tools/proof_*` tool descriptions to use IETF language (auditor-facing surface)
5. Migration guide in `CHANGELOG.md` + `docs/migration-v1.3.md`
6. Bump to **v1.3.0-beta.1** (minor — additive, legacy still works)

## Tests

- Add `test/proof/ietf-alias.test.ts` — verify legacy names still resolve
- Regenerate existing Merkle fixture JSONs with new field names + keep old fixtures named `*-legacy.json` for compat test
- Run full suite: `npm test`

## Quarantine — do NOT touch

- Ed25519 signing (`src/crypto/*`)
- Spoof-detection scoring (`src/detect/*`)
- Fleet-sim stress harness
- Payment rail wiring (inherited from MnemoPay)

## Post-rename marketing hook

Update `README.md` + mnemopay.com GridStamp page: "COSE-Merkle compliant per RFC 9052 + draft-ietf-cose-merkle-tree-proofs-18." Auditor keyword-fit for AUVSI, TÜV SÜD, DIU Replicator-2 bid.

## Execution trigger

Only after Hindsight port on mnemopay-sdk lands green. Don't run two SDK-core refactors concurrently.