feat(schema): Pattern template v2 — structured CROPS context, I2U enforcement, meta-pattern type

[Meyanis95]

Motivation

Two unrelated streams converged on the same set of template issues:

Stream 1 — Guide rendering. The iptf-web Guide renders all ~60 pattern files as structured pages (CROPS badges, persona-tabbed content, sidebar cross-references). The frontmatter held up well. The body sections didn't:

• Trade-offs is a grab-bag of four content types in one bullet list (performance notes, labelled trade-offs, CROPS context narrative, post-quantum exposure). Currently disambiguated with regex.
• Ingredients mixes standards, on-chain code, and off-chain services under bold labels. Hard to render distinctly.
• dependencies frontmatter overlaps with ingredients.standards and sometimes contains other patterns. See also overlaps too.
• Meta-patterns like Network-Level Anonymity are forced into the single-protocol schema with placeholder sections and misleading aggregate CROPS.

Stream 2 — Open issues. Four open issues independently asked for things the current schema can't cleanly support:

• feat(schema): add meta-pattern type for umbrella patterns #147 — meta-patterns have no real CROPS profile and no step-by-step protocol, but the schema forces one.
• chore(patterns): Enforce I2U coverage (per existing template) #134 — ~48 context: both patterns need substantive I2U coverage, but the current template only asks authors to "mention" it in Guarantees. Easy to satisfy with a one-liner.
• feat(patterns): Add common I2U protection patterns #135 — new I2U protection patterns (network-level privacy, user-controlled viewing keys) need real I2U depth from day one. The current template doesn't enforce that.
• chore: Content QA audit #140 — v0.3.0 QA audit requires verifying CROPS profiles match prose and that I2U coverage is real. Easier to run against a schema that makes the I2U story explicit.

The fix for both streams is the same: restructure body sections into typed frontmatter fields so the render/validation layer can enforce them.

---

Proposed schema changes

1. Simplify maturity to four states

maturity: research | concept | testnet | production

• research — academic paper or theoretical work, no concrete design yet
• concept — design spec exists, no running code
• testnet — running on testnet or in a PoC environment (absorbs current PoC and pilot)
• production — deployed on mainnet with real institutional usage

Migration mapping:

• PoC|pilot → testnet (scripted rename)
• production|prod → production (scripted rename)
• experimental → manual review — could be research, concept, or testnet depending on the pattern; flag as a human call rather than default

2. type flag for meta-patterns (resolves #147)

type: standard | meta   # optional, defaults to standard

When type: meta:

• crops_profile optional — CROPS lives on sub-patterns
• standards, ## Protocol, ## Example optional
• New required sub_patterns field:

sub_patterns:
  - name: "Onion routing (Tor-style)"
    pattern: pattern-onion-routing       # slug; validator resolves to patterns/pattern-onion-routing.md and checks the file exists
    crops_summary: "High CR, high privacy, high latency"
  - name: "Mixnet"
    pattern: pattern-mixnet
    crops_summary: "Medium CR, full privacy, high latency"
  - name: "TEE-assisted anonymity"
    pattern: pattern-tee-network-anonymity
    crops_summary: "Medium CR, full privacy, low latency"

The pattern field is a filename slug (matching the existing pattern-<slug>.md naming convention). The schema validator resolves it to patterns/pattern-<slug>.md and errors if the file is missing — prevents broken references.

Renders as a comparison table with links to each sub-pattern. Rationale for a flag vs a separate template: less file proliferation, additive tooling change, authors don't pick a template up front.

3. Split Trade-offs into typed sub-sections

Move CROPS context and post-quantum out of the bullet list:

crops_context:
  cr: "Reaches `high` on L1 permissionless pools. Drops to `low` on permissioned L2s with operator-controlled exit."
  os: "..."
  privacy: "..."
  security: "..."
post_quantum:
  risk: high | medium | low
  vector: "EC-based commitments (Groth16, PLONK/KZG) broken by CRQC; HNDL risk for encrypted notes"
  mitigation: "STARK-based pools with hash commitments"

Keep ## Trade-offs for generic performance / cost / DX notes. This also makes the CROPS-profile-vs-prose check explicit — crops_context.cr either matches crops_profile.cr or the gap is visible to reviewers.

4. context_differentiation — enforce I2U coverage at schema level (resolves #134)

Keep context for the badge. Add:

context_differentiation:
  i2i: "Symmetric trust; both parties have legal recourse"
  i2u: "Asymmetric; CROPS must protect the user. Forced withdrawal is critical"

Schema rule: if context: both, both i2i and i2u strings must be non-empty. Renders as a two-column callout on the Guarantees section.

This is what converts #134 from a perpetual audit into a migration concern — you cannot merge a context: both pattern with stub I2U.

5. Unified related_patterns — drop dependencies

Current dependencies overlaps with standards (both hold ERC/EIP IDs) and sometimes contains other patterns. See also overlaps too.

related_patterns:
  requires: [pattern-shielding]          # hard dependency — can't implement this without it
  composes_with: [pattern-stealth-addresses]   # works well together, optional
  alternative_to: [pattern-tee-based-privacy]  # competing approach to the same problem
  see_also: [pattern-forced-withdrawal]        # related for context

All four slots use the same pattern-<slug> form as sub_patterns. Validator checks target files exist.

6. open_source_implementations (plural, neutral)

Renamed from "reference implementation" — that phrase has a specific meaning in standards contexts (the blessed/canonical version). Neutral wording allows multiple entries:

open_source_implementations:
  - url: https://github.com/Railgun-Privacy/contract
    description: "Railgun shielded pool (L1, production)"
    language: Solidity
  - url: https://github.com/ethereum/iptf-pocs/tree/master/pocs/private-payment
    description: "IPTF PoC (UltraHonk/Noir, research)"
    language: Noir
  - url: https://github.com/AztecProtocol/aztec-packages
    description: "Aztec Network (privacy L2)"
    language: Noir

Renders as a short list in the sidebar. Strong maturity signal.

7. Replace ingredients with top-level standards + ## Components body section

Drop the ingredients container. Promote standards to a top-level frontmatter field:

standards: [ERC-20, ERC-5564]

Replace ## Ingredients with ## Components — a bullet list of what makes up this pattern, each item with a short note on its role. Primitives, on-chain code, and off-chain services all belong here:

## Components

- Commitment scheme (Pedersen or Poseidon-based) — hides note contents on-chain
- Nullifier set — prevents double-spends
- Shielded pool contract — anchors commitments
- ZK prover — produces spend authorization proofs client-side
- Relayer (optional) — submits shielded txs for gas abstraction

If a component is also a standalone map pattern, link via related_patterns rather than duplicating here.

8. Visibility matrix (audit first, optional)

Proposed optional 4-slot model:

visibility:
  counterparty: [amounts, identities]
  chain: [commitments, nullifiers]
  regulator: [full_tx with viewing key]
  public: []

Infrastructure/primitive patterns (network-level anonymity, forced withdrawal, attestation verification) likely don't fit this model. Prerequisite: 15-pattern audit across categories. If ≥ 80% fit, add as optional. If not, gate on a kind: transaction-level | infrastructure | primitive field so the matrix only applies where it makes sense.

Deferred pending audit.

9. Protocol step role tags (optional, lowest priority)

## Protocol
1. [user] Deposit ERC-20 tokens into shielded pool contract
2. [contract] Emit commitment on-chain
3. [user] Execute shielded transfer (generate ZK proof client-side)
4. [auditor] Verify via viewing key

Roles render as small tags next to each step. Helps CTO personas assess operational complexity. Drop if anyone pushes back.

---

Scope and non-goals

• Don't add new body sections. Every change either types up existing content (Trade-offs → crops_context + post_quantum), narrows an existing section (Ingredients → Components), or removes a field (dependencies).
• Don't force machine-readable fields authors can't fill. Every new field has a human-authorable shape.
• Don't migrate to TOML at current scale. Nested structures (crops_context, sub_patterns, related_patterns) read better in YAML, and the wins don't justify rewriting ~60 patterns plus tooling. Revisit at ~300 patterns.
• crops_profile, works-best-when, avoid-when, context, last_reviewed keep their current shape.

---

Related

• Closes feat(schema): add meta-pattern type for umbrella patterns #147
• Absorbs chore(patterns): Enforce I2U coverage (per existing template) #134 into the schema migration
• Unblocks feat(patterns): Add common I2U protection patterns #135 (new patterns authored in the new schema)
• Feeds chore: Content QA audit #140 (structural audit runs alongside the QA pass)

[oskarth]

A bit too much to review in detail; a tldr at top would be useful to get input. Skimming looks fine!