suaveplan/openspec/archive/2026-05-03-chain-bundle-adopt-envelope-schema/tasks.md

Tasks — chain-bundle adopts EnvelopeSchema

Every checkbox MUST reflect work actually done in this change. No retroactive ticking. Implementation gated on user sign-off (§1.5).

1. Spec authoring & sign-off

• 1.1 Author proposal.md with Parity Checklist + Source mapping
• 1.2 Author this tasks.md
• 1.3 Author specs/crypto/spec.md ADDED Requirement pinning the byte-identical wire format
• 1.5 GATE — user sign-off on the API/wire-format invariants before any implementation work
• 1.6 openspec change validate chain-bundle-adopt-envelope-schema --strict exits clean

2. Package metadata

• 2.1 Add @suaveplan/bitpacker-crypto: workspace:^ to packages/crypto/crypto/package.json dependencies
• 2.2 Update packages/crypto/crypto/vite.config.ts externals: add "@suaveplan/bitpacker-crypto" and /^@suaveplan\/bitpacker-crypto\//
• 2.3 Run bun install — lockfile updates clean
• 2.4 Run bun scripts/folder-reorg/generate-manifest.ts — manifest regenerates clean (acyclic graph confirmed)

3. chain-bundle.ts refactor

• 3.1 Drop the inline HEADER_SCHEMA = defineBitSchema(...) declaration and the ChainBundleHeaderRaw interface
• 3.2 Add HEADER_BODY_SCHEMA = defineBitSchema<{ linkCount: number }>([{name: "linkCount", type: "uint", bits: 8}])
• 3.3 Add CHAIN_BUNDLE_ENVELOPE = defineEnvelopeSchema<{ linkCount: number }>({ magic: CHAIN_BUNDLE_MAGIC, formatVersion: CHAIN_BUNDLE_FORMAT_VERSION, bodyCodec: { pack: HEADER_BODY_SCHEMA.pack, unpack: HEADER_BODY_SCHEMA.unpack } })
• 3.4 Update CHAIN_BUNDLE_HEADER_BYTE_SIZE = CHAIN_BUNDLE_MAGIC.length + 1 + HEADER_BODY_SCHEMA.byteSize (must equal 6)
• 3.5 Refactor packChainBundle to use CHAIN_BUNDLE_ENVELOPE.pack({ linkCount }) for the header, then concat link bytes
• 3.6 Refactor parseChainBundle to use CHAIN_BUNDLE_ENVELOPE.parseStrict(headerBytes) for the header. Wrap in try/catch that maps BitpackerError CRYPTO_ENVELOPE_MAGIC_MISMATCH → CryptoError CHAIN.WRONG_FORMAT crypto.chain-bundle.bad-magic, and BitpackerError CRYPTO_ENVELOPE_VERSION_MISMATCH → CryptoError CHAIN.WRONG_FORMAT crypto.chain-bundle.unsupported-version (with context.version: actual).
• 3.7 Preserve all other code paths verbatim: linkCount range check, expectedTotal length check, verifyChain walk-and-verify.
• 3.8 No public API change — packChainBundle, parseChainBundle, verifyChain, CHAIN_BUNDLE_MAGIC, CHAIN_BUNDLE_FORMAT_VERSION, MAX_CHAIN_LINKS, CHAIN_BUNDLE_HEADER_BYTE_SIZE, ChainBundle, IsRevokedPredicate, VerifyChainOptions all remain identical.

4. Snapshot test for byte-identical wire format

• 4.1 Add a test in chain-bundle.test.ts that builds a fixed 1-link chain (deterministic keychain seed, deterministic nonce) and asserts the exact bytes of the resulting bundleBytes
• 4.2 The snapshot bytes MUST be captured BEFORE the refactor (so the test pins the pre-refactor format) and PASS unchanged AFTER the refactor

5. 5-gate verification

• 5.1 bunx turbo lint typecheck test --filter=@suaveplan/crypto — all existing 265 tests + the new snapshot test pass green
• 5.2 bunx turbo test:coverage --filter=@suaveplan/crypto — chain-bundle.ts coverage stays 100/100/100/100
• 5.3 bunx turbo build --filter=...@suaveplan/crypto — every dependent compiles green
• 5.4 Grep guard: ! grep -rE 'from "@suaveplan/crypto"' packages/bitpacker/bitpacker-crypto/src/ --include="*.ts" | grep -v "\\.test\\.ts" — zero matches (cycle did not regress)
• 5.5 bun scripts/folder-reorg/generate-manifest.ts — manifest regenerates clean

6. Pre-archive 7-row checklist (AGENTS.md §13)

• 6.1 Generics threaded — EnvelopeSchema<{ linkCount: number }> is properly typed
• 6.2 Zod schemas wired at every declared boundary — envelope validates options
• 6.3 No new error codes introduced (this is a pure-refactor change)
• 6.4 Strict-mode behaviors tested — all four error paths (bad magic, bad version, too short, length mismatch) covered by existing tests
• 6.5 OTel spans emitted from production paths — envelope-pack / envelope-parse spans inherit from EnvelopeSchema
• 6.6 Lifecycle dedup tested where claimed — N/A (pack is pure)
• 6.7 No retroactive tick — every box reflects work done in this change

7. Archive

• 7.1 Fold specs/crypto/spec.md ADDED Requirement into openspec/specs/crypto/spec.md
• 7.2 Move openspec/changes/chain-bundle-adopt-envelope-schema/ → openspec/archive/<yyyy-mm-dd>-chain-bundle-adopt-envelope-schema/
• 7.3 Update CLAUDE.md (if needed) — note that crypto now depends on bitpacker-crypto at runtime

8. Follow-up changes (queue, not done in this change)

• 8.1 public-bundle-adopt-envelope-schema — migrate crypto::PublicBundle to use EnvelopeSchema + SignedBitSchema (same pattern, larger because it does both signing and envelope framing)