PERMIT_V2 §4.3 PR 2 (keel-permit): spec + schema + failure codes

[sftimeless]

Summary

Phase 2 of the PERMIT_V2 §4.3 multi-party signature envelope implementation arc (doctrine locked 2026-05-23, captured in feedback_permit_v2_signature_envelope_doctrine.md in local memory).

This PR ships the keel-permit half of Phase 2:

• spec/permit-v2.md — the v2 spec covering the 5-slot signature envelope architecture
• schemas/permit-v2.schema.json — strict schema with additionalProperties: false at top level AND on each signature sub-object
• spec/failure-codes.md — new failure code lexicon for the three new slots

The 5-slot architecture (one existing + three new in §4.3 + one reserved)

PERMIT_V2 {
  ...v1 fields preserved byte-faithfully...
  permit_format_version: "v2"
  signature                  ← Issuer (existing, unchanged from v1)
  operator_approval?         ← Issuer-org dual control (NEW)
  counter_signature?         ← Buyer pre-dispatch execution authorization (NEW)
  audit_attestation?         ← Buyer post-hoc historical-existence attestation (NEW)
  // provider_attestation?      ← RESERVED for separate design pass
}

Each slot has its own claim namespace, signed payload type, failure code prefix, and canonical helper. No semantic muddling between slots.

Companion PR

This PR's keel-api companion (https://github.com/keelapi/keel-api/pull/NEW — to be opened separately as a stacked PR against PR #140) implements:

• Three new canonical payload helpers in app/services/permit_v2_canonical.py
• Explicit-key sign/verify primitives in app/services/permit_v2_signing.py
• verify_at_signing_time integration with PR 1's key registry

Both must merge for §4.3 to be functional.

Dependency chain

• PR 1 (key registry foundation): keel-api PR #140 — must merge first (provides as-of-signing-time key lookup)
• PR 2 (this PR + keel-api companion): spec + canonical helpers
• PR 3 (verifier predicates): keel-verifier — depends on PR 2's spec
• PR 4 (emission API): keel-api — depends on PR 2's helpers

Doctrine locks honored

• payload_type as cryptographic domain separator (per §XII multi-model convergence)
• counter_signature is buyer pre-dispatch ONLY (not post-hoc)
• audit_attestation is a SEPARATE slot for post-hoc batch existence-and-inclusion
• No generic third_party_attestations array
• Procurement framing: governance moat, NOT compliance ("Existing audit standards verify controls, logs, and authorization processes, but do not standardize cryptographically verifiable buyer assent at the individual AI-action level. Keel introduces this as a higher-granularity governance primitive.")

Test plan

• All 3 commits have both co-author trailers in proper case
• Schema validates against inline v2 permit fixture
• Schema rejects forbidden field injection (e.g., operator_approval.unexpected field)
• Schema rejects top-level provider_attestation (reserved, not yet active)
• python3 tools/check_repo_integrity.py --require-jsonschema passes

🤖 Generated with Claude Code