suaveplan/openspec/archive/2026-04-29-mime-spec-conformance/proposal.md

OpenSpec Change: mime-spec-conformance

• Change ID: mime-spec-conformance
• Package: @suaveplan/mime
• Status: PROPOSED
• Date: 2026-04-26

Summary

Add **Verified by:** lines to every requirement in openspec/specs/mime/spec.md, fix two pieces of real implementation drift inline (MIME-07: registerMimeEntry did not validate against MimeEntrySchema; MIME-12 / MIME-16: detect did not validate against DetectInputSchema), pin both fixes plus the MIME-20 benchmark layout with src/db/db.spec-conformance.test.ts, and annotate the schemas that describe wire-only / cross-process shapes with // schema: boundary-only.

Current state

@suaveplan/mime ships magic-byte detection, RFC 7231 Content-Type parsing/serialisation, the BUILTIN_DB registry, BOM/HTML/XML charset sniffers, the detect() orchestrator, the legacy getMimeType shim, OTel meter helpers, structured errors, and Zod schemas. 21 requirements, ~317 tests, 100% coverage. Three gaps blocked conformance:

1. registerMimeEntry accepted any object — spec said it MUST validate against MimeEntrySchema and throw ParseError.
2. detect had no schema invocation — spec said it MUST use DetectInputSchema for boundary validation.
3. No requirement carried a **Verified by:** annotation.

The // schema: boundary-only warns for the result schemas (MagicBytesResultSchema, ExtensionDetectionResultSchema, etc.) and the wire-form SignatureSchema are by-design — those schemas describe cross-process serialisation shapes and are exported for downstream consumers.

What changes

1. Wire MimeEntrySchema.safeParse into registerMimeEntry and throw ParseError on failure.
2. Wire DetectInputSchema.safeParse into detect and throw ParseError on failure (preserving the existing "empty input returns octet-stream default" behaviour by treating the at-least-one-source refinement as non-fatal).
3. Add // schema: boundary-only annotations to the wire-only result schemas.
4. Annotate every requirement (MIME-01 through MIME-21) in the folded spec with a **Verified by:** line.
5. Add src/db/db.spec-conformance.test.ts covering MIME-07 (ParseError on invalid entry shape), MIME-12/16 (ParseError on invalid DetectInput.extension), and MIME-20 (benchmark file existence).
6. bun scripts/openspec-conformance.ts @suaveplan/mime reports zero errors. Schema-at-boundaries warns remain by design (annotated).

Impact

• registerMimeEntry now throws ParseError on malformed input (was silently accepted).
• detect now throws ParseError on type-mismatched inputs (was silently coerced).
• One new test file (~50 lines).
• openspec/specs/mime/spec.md gains 21 **Verified by:** blocks.
• Coverage stays 100/100/100/100.