Progressive honesty in protocol design

The problem with “we’ll fix it in v2”

Privacy and identity protocols fail in two opposite ways. One team ships nothing until every cryptographic detail is perfect—users get no value for years. Another team ships slides and lets the implementation catch up quietly—users discover the gap from a breach or a fork.

HUMΛN’s third path is progressive honesty: ship the narrow, honest version that works in production, name where it diverges from Canon, and encode the upgrade path in schema and flags so the gap is visible in code and tests—not only in a roadmap PDF.

This essay is the pattern behind Passport relay-to-P2P sync, guardian server_assembly vs client_proof, SD-JWT plus BBS+ with issuer-issued predicates before full range proofs, and testnet vs mainnet anchoring. Same spine everywhere.

The three-part pattern

1. Name the deviation

Examples from shipped work:

Surface	Honest interim	Canon direction
Vault sync	DB-backed ciphertext relay (signal + store)	True P2P: server is signal-only
Recovery	Option A: server reconstructs S briefly	Option B: device reconstructs; proof only
Disclosure	Boolean predicates + SD-JWT	BBS+ unlinkability; full range ZK in a later phase
Anchoring	Testnet for pipelines	Mainnet for third-party durable verification

None of these is “we lied.” Each is “here is exactly what runs today, and here is the next gate.”

2. Ship the narrow version that is true

The interim must be security-honest: if the server can see vault ciphertext relayed through a row, say so. If recovery still uses server assembly for legacy clients, gate it with completion_mode and keep Option B from being downgradeable via plaintext shard posts (our downgrade tests exist for that reason).

3. Encode the upgrade in schema

Comments rot. Schema persists.

Examples:

completion_mode: 'server_assembly' | 'client_proof' — server rejects wrong mode with 409.
proof_type: 'sd-jwt' | 'bbs' on disclosure requests — verifiers know which verification path to run.
p2p_capable (or equivalent) — clients negotiate P2P without a flag day.
review_round on workforce tasks — stale reviewer outcomes do not satisfy a new quorum after escalation (see workforce service).

When the community audits your repo, they should grep the upgrade path, not parse your blog.

Why marketing teams hate this (and engineers should defend it)

Honest staging feels like admitting weakness. It is the opposite: silent gaps are weakness. Named gaps with tests are engineering discipline. Your most skeptical users are not fooled by undefined “ZK roadmap” language—they read types and migrations.

What “progressive” is not

Not a permanent excuse. @canon-deviation and TODO[canon-sync] exist to burn down to Canon-aligned behavior with tests, then remove markers via pnpm canon-deviations:catalog—not to decorate debt forever.
Not “MVP” as a synonym for “unsafe.” The narrow path must be honest about trust boundaries, not “ship fast and hope.”

Integration note for reviewers

When you review a PR that touches identity or disclosure:

Does it add or preserve a named mode / migration / flag for the honest interim?
Are there tests that prevent downgrade to a weaker mode without an explicit client choice?
Is the public story (docs or blog) updated in the same merge when behavior changes?

If any answer is no, send it back.

Checklist: progressive honesty PR

Deviation or staging choice is documented in code (comment block or ADR pointer), not only Slack.
Schema or config carries the mode or version relevant to upgrades.
Tests cover negative paths (wrong mode, wrong proof type, legacy client).
Canon debt markers updated only when behavior + tests justify removal.

Companion essays: The sovereignty spine. Narrative: Recovery where the math matches the marketing.