suaveplan/openspec/archive/2026-05-02-serialize-spec-conformance/tasks.md

Tasks: serialize-spec-conformance

1. New tests pinning implicit scenarios

• 1.1 Add src/codec/json/json-encode.spec-conformance.test.ts covering SZ-02 typed-array round-trip (Int8Array/Int16Array/Int32Array/Uint16Array/Uint32Array/Float32Array/Float64Array) and SZ-03 envelope-shape contract for Date.
• 1.2 Add src/codec/msgpack/msgpack-encode.spec-conformance.test.ts covering SZ-06 byte-identical output for the same structured input across two encode calls.

2. Spec annotations

• 2.1 Add **Verified by:** line under every ### SZ-NN — block in openspec/specs/serialization/spec.md (12 requirements).

3. Close in scope: SZ-10 wire-format + options validation

• 3.1 Add src/codec/wire/wire.schemas.ts with WireNodeSchema, TaggedEnvelopeSchema, and validateWireNode covering tagged-envelope and recursive plain-record shapes. Include strict envelope rejection (extra keys, non-string __t).
• 3.2 Tighten src/codec/json/json.schemas.ts to .strict() and add signal field validation (duck-typed AbortSignal).
• 3.3 Wire SerializeOptionsSchema / DeserializeOptionsSchema .safeParse into the public serialize / deserialize / encodeBinary / decodeBinary entry points; on rejection throw InvalidOptionsError (new code SERIALIZE.OPTIONS.INVALID).
• 3.4 Wire validateWireNode into the public deserialize and decodeBinary entry points; on rejection throw MalformedWireError (new code SERIALIZE.CODEC.MALFORMED_WIRE). Preserve __proto__ round-trip by re-using the original parsed value when validation passes.
• 3.5 Add MalformedWireError and InvalidOptionsError to src/errors/serialize-error.ts; register codes via defineCodes; export from src/index.ts.
• 3.6 Add src/codec/wire/wire.schemas.test.ts pinning rejection of malformed JSON / msgpack inputs, invalid options, and the schema acceptance set. Add __proto__ regression coverage.

4. Close in scope: SZ-11 OTel instrumentation

• 4.1 Add src/observability/metrics.ts exporting getSerializeMetrics() and resetSerializeMetrics() with the lazy metrics.getMeter('suaveplan.serialize') singleton pattern from @suaveplan/i18n / @suaveplan/logger.
• 4.2 Wire histograms (serialize.encode.bytes, serialize.decode.bytes, serialize.payload_bytes, serialize.encode.duration_ms, serialize.decode.duration_ms) and counter (serialize.error.total with code + format labels) into all four public entry points.
• 4.3 Add src/observability/metrics.test.ts using a real in-memory MeterProvider implementation (conforming class hierarchy, not vi.mock) that records all instrument creation + measurement calls.

5. Close in scope: generic threading on public deserialize entry points

• 5.1 Thread <T = unknown> through deserialize, decodeBinary, legacyDeserialize, and deserializeEvalSafe. Type-only change; runtime unchanged.
• 5.2 Add expectTypeOf assertions to wire.schemas.test.ts, legacy.test.ts, and eval-safe.test.ts.

6. Verify

• 6.1 bunx turbo lint typecheck test --filter=@suaveplan/serialize green.
• 6.2 bunx turbo test:coverage --filter=@suaveplan/serialize 100/100/100/100.
• 6.3 bun scripts/openspec-conformance.ts @suaveplan/serialize exits 0.