Skip to main content
HUMΛN
HUMΛN
←Community
Engineering
Engineering

Progressive honesty in protocol design

HUMΛN Team··16 min·Protocol engineers

A partner asks in the diligence call: “Is vault sync peer-to-peer yet?” Your deck says yes. Your schema says the server still stores relay ciphertext. The partner greps the repo. Diligence ends.

That gap—slides ahead of types—is how privacy protocols lose the people who would have trusted an honest interim.

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.

Scroll-stopper: If the upgrade path only exists in a PDF, you do not have a roadmap—you have a rumor.

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 previous-format 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.

When the community audits your repo, they should grep the upgrade path, not parse your blog. So that skeptical users—and diligent partners—can refuse undefined “ZK roadmap” language and still ship the honest interim.

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 fog—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:

  1. Does it add or preserve a named mode / migration / flag for the honest interim?
  2. Are there tests that prevent downgrade to a weaker mode without an explicit client choice?
  3. 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, previous-format client).
  • Canon debt markers updated only when behavior + tests justify removal.

Go deeper

— Part of