26 KiB
Capability Spec: packer
- Capability:
packer - Package:
@suaveplan/packer - Change: packer-port
- Date: 2026-04-28
Requirements
All requirements in this section are new for genesis. The package is a partial rewrite of ../suaveplan/packages/universal/packer v2.0.0; whole-file mode preserves the source's pipeline shape with a simplified envelope, while chunked mode is rewritten to emit the locked v1 byte format pinned below.
PACKER-01 — Whole-file pack/unpack round-trip
Packer.pack(data, filename?) followed by Unpacker.unpack(packed, key, pubKey?) MUST yield bytes equal to the original data. Optional MIME detection MUST surface in the returned metadata.
Verified by: src/unpacker/unpacker.spec-conformance.test.ts::"round-trips uncompressed unencrypted bytes".
PACKER-02 — Whole-file gzip compression
When compressionLevel > 0, pack MUST gzip the payload before AEAD; unpack MUST gunzip after AEAD. The metadata.compressionAlgorithm MUST surface as "gzip" when compression ran.
Verified by: src/packer/packer.spec-conformance.test.ts::"compresses when compressionLevel > 0"; src/unpacker/unpacker.spec-conformance.test.ts::"round-trips compressed bytes".
PACKER-03 — Whole-file signing
When a signing.key is provided to pack, the produced PackedData.metadata MUST carry signed: true and a 64-byte ed25519 signature over the post-encryption ciphertext. unpack with verifySignature: true and a 32-byte verifyKey MUST verify the signature and throw PackerError(PACKER.VERIFICATION_FAILED) on mismatch.
Verified by: src/packer/packer.spec-conformance.test.ts::"appends an ed25519 signature when signing.key supplied"; src/unpacker/unpacker.spec-conformance.test.ts::"verifySignature with wrong key returns VERIFICATION_FAILED".
PACKER-04 — Whole-file event lifecycle
Packer MUST emit typed events via EventBus<PackerEventMap>: pack:start, pack:compressed, pack:encrypted, pack:signed, pack:complete, with corresponding unpack:* events on the unpacker. Events MUST fire in deterministic order on completion.
Verified by: src/packer/packer.spec-conformance.test.ts::"emits pack:start, pack:compressed, pack:encrypted, pack:signed, pack:complete in order"; src/unpacker/unpacker.spec-conformance.test.ts::"emits unpack:start, unpack:verified, unpack:decrypted, unpack:decompressed, unpack:complete in order".
PACKER-05 — Chunked v1 byte layout
A v1 chunk produced by ChunkedPacker MUST be the byte concatenation metadata(100) ‖ sig(64) ‖ ciphertext(payloadLen), total 164 + payloadLen bytes, big-endian. Field offsets within metadata MUST be exactly: version 0–2, fileId 2–34, chunkId 34–38, totalChunks 38–42, fileSize 42–50, chunkSize 50–54, payloadLen 54–58, flags 58–60, nonce 60–84, aeadTag 84–100. Sig occupies 100–164. Ciphertext starts at 164.
Verified by: src/chunked/codec/chunk.spec-conformance.test.ts::"metadata field offsets match the locked layout".
PACKER-06 — flags reserved in v1
flags MUST be 0x0000 in v1. parseHeader MUST reject non-zero flags with PackerError(PACKER.FLAGS_RESERVED_NONZERO) before any further parse work.
Verified by: src/chunked/codec/chunk.spec-conformance.test.ts::"parseHeader rejects flags != 0 with FLAGS_RESERVED_NONZERO".
PACKER-07 — payloadLen invariants
For non-final chunks (chunkId < totalChunks - 1), payloadLen MUST equal chunkSize - 164. For the final chunk, payloadLen MUST equal fileSize - chunkId * (chunkSize - 164). Mismatch MUST be rejected with PackerError(PACKER.PAYLOAD_LEN_INVALID) before sig verification.
Verified by: src/chunked/codec/chunk.spec-conformance.test.ts::"non-final chunk MUST have payloadLen === chunkSize - 164"; src/chunked/codec/chunk.spec-conformance.test.ts::"final chunk MUST have payloadLen === fileSize - chunkId * (chunkSize - 164)".
PACKER-08 — Streaming pipeline produces v1 chunks
ChunkedPacker.pack(source, opts) MUST stream-process the input via normalizeSource → accumulate → encrypt → sign → emit. The output MUST be an AsyncIterable<{ chunkId, bytes, metadata }> where each bytes is a v1-format chunk. The full source MUST NOT be buffered as a single in-memory copy.
Verified by: src/chunked/packer/packer.spec-conformance.test.ts::"round-trips multi-chunk file with short final chunk".
PACKER-09 — Non-final chunks are exactly chunkSize bytes
Every emitted chunk with chunkId < totalChunks - 1 MUST be exactly chunkSize bytes on the wire. No zero padding is added.
Verified by: src/chunked/packer/packer.spec-conformance.test.ts::"round-trips multi-chunk file with short final chunk"; src/chunked/packer/packer.spec-conformance.test.ts::"round-trips file whose size is exact multiple of payloadPer".
PACKER-10 — Final chunk is naturally short
The final chunk MUST be 164 + lastPayloadLen bytes, where lastPayloadLen = fileSize - (totalChunks - 1) * (chunkSize - 164). The final chunk MUST NOT be zero-padded to chunkSize.
Verified by: src/chunked/packer/packer.spec-conformance.test.ts::"round-trips multi-chunk file with short final chunk".
PACKER-11 — Round-trip parity
ChunkedUnpacker.unpack(chunks, fileKey, serverPubKey) over the chunks emitted by ChunkedPacker.pack(...) MUST yield a plaintext stream byte-equal to the original input. Order MUST be chunkId ascending; out-of-order delivery is the consumer's responsibility to reorder before passing to unpacker.
Verified by: src/chunked/unpacker/unpacker.spec-conformance.test.ts::"decrypts multi-chunk stream in order".
PACKER-12 — Mutation detection
Any mutation to any signed byte MUST cause ChunkedUnpacker.unpack to throw PackerError(PACKER.VERIFICATION_FAILED) from the per-chunk sig-verify step before AEAD decryption is attempted.
Verified by: src/chunked/unpacker/unpacker.spec-conformance.test.ts::"rejects chunk signed by a different key".
PACKER-13 — Verifier without file key
ChunkVerifier.verify(chunkBytes, serverPubKey) MUST validate the structural invariants and the ed25519 signature without the file decryption key. It MUST return { ok: true, metadata } for valid chunks and { ok: false, code } for invalid chunks. It MUST NOT attempt AEAD decryption.
Verified by: src/chunked/verifier/chunk-verifier.spec-conformance.test.ts::"returns ok for a properly-signed chunk".
PACKER-14 — Verifier rejects forged sig
ChunkVerifier.verify MUST return { ok: false, code: "PACKER.VERIFICATION_FAILED" } for a chunk whose signature does not validate under serverPubKey. Verifier MUST NOT consult the chunks plugin or any persistence layer.
Verified by: src/chunked/verifier/chunk-verifier.spec-conformance.test.ts::"returns VERIFICATION_FAILED for tampered metadata"; src/chunked/verifier/chunk-verifier.spec-conformance.test.ts::"returns VERIFICATION_FAILED for chunk signed by a different key".
PACKER-15 — Manifest signature
The manifest produced by buildManifest(...) MUST be ed25519-signed via the canonical encoding of every field except sig itself. verifyManifest(manifest, serverPubKey) MUST return false for any manifest whose signature does not validate; mutation of any signed field MUST cause verification failure.
Verified by: src/chunked/manifest/manifest.spec-conformance.test.ts::"signs and verifies a manifest"; src/chunked/manifest/manifest.spec-conformance.test.ts::"verify returns false on tampered field".
PACKER-16 — Manifest matches chunk metadata
buildManifest MUST produce a manifest where totalChunks === chunks.length, version === 1, and the per-chunk entries (chunkId, hash, payloadLen) match the inputs. The sig field MUST be 64 bytes.
Verified by: src/chunked/manifest/manifest.spec-conformance.test.ts::"signs and verifies a manifest".
PACKER-17 — Error registry namespaced and frozen
PACKER_CODES MUST be declared via defineCodes("PACKER", [...]) from @suaveplan/error. Object.isFrozen(PACKER_CODES) MUST be true. Every code value MUST start with PACKER.. PackerError MUST extend SuaveplanError<PackerErrorCode>.
Verified by: src/error-codes.spec-conformance.test.ts::"PACKER_CODES is frozen"; src/error-codes.spec-conformance.test.ts::"every code value starts with PACKER."; src/error-codes.spec-conformance.test.ts::"PackerError extends SuaveplanError".
PACKER-18 — BLAKE3 per-entry digest and bundle-level Merkle root
The package SHALL compute and surface a content-addressable BLAKE3 digest for every entry written to a bundle, plus a bundle-level Merkle root computed over the sorted entry digests. The Merkle root MUST be a 32-byte BLAKE3 digest of the concatenation of the sorted entry digests in chunkId-ascending order; for a single-entry bundle the Merkle root equals blake3(entryDigest) (domain-separated wrap of the lone leaf); for an empty bundle the Merkle root MUST be blake3("") (the 32-byte digest of zero input bytes). Whole-file bundles carry (entryDigest, merkleRoot) on PackedDataMetadata.integrity; chunked bundles carry per-chunk entryDigest on every ManifestChunkEntry and merkleRoot at the manifest root. The production paths Packer.pack and buildManifest MUST always populate these fields.
Verified by: src/integrity/integrity.test.ts::"computes the BLAKE3 entry digest of payload bytes"; src/integrity/integrity.test.ts::"computes the Merkle root as BLAKE3 of concatenated sorted digests"; src/integrity/integrity.test.ts::"returns BLAKE3 of zero bytes for an empty digest list"; src/packer/packer.spec-conformance.test.ts::"populates metadata.integrity on every pack"; src/chunked/manifest/manifest.spec-conformance.test.ts::"populates entryDigest on every chunk entry and a manifest merkleRoot".
PACKER-19 — Mandatory integrity verification on unpack
The package SHALL reject any unpack of a bundle whose recomputed integrity digests do not match the bundle's recorded values. Unpacker.unpack MUST throw PackerError(PACKER.INTEGRITY_FAILED) when metadata.integrity is absent OR when the recomputed entryDigest or merkleRoot does not match. unpackChunksWithManifest MUST throw PackerError(PACKER.INTEGRITY_FAILED) for any chunk whose blake3(wireBytes) does not equal the matching manifest.chunks[i].entryDigest, OR when the manifest's merkleRoot does not equal merkleRootBlake3(manifest.chunks.map(c => c.entryDigest)). Integrity verification MUST run on both the whole-file and chunked paths; ed25519 signing remains in force in parallel. Callers MAY pass verifyIntegrity: false on UnpackOptions as a documented escape hatch for legacy bundles produced before the integrity layer existed.
Verified by: src/packer/packer.spec-conformance.test.ts::"rejects unpack when metadata.integrity is absent"; src/packer/packer.spec-conformance.test.ts::"rejects unpack on mutated entryDigest"; src/packer/packer.spec-conformance.test.ts::"rejects unpack on mutated merkleRoot"; src/chunked/unpacker/unpacker-with-manifest.spec-conformance.test.ts::"rejects per-chunk BLAKE3 mismatch with INTEGRITY_FAILED"; src/chunked/unpacker/unpacker-with-manifest.spec-conformance.test.ts::"rejects manifest with inconsistent merkleRoot".
PACKER-20 — OpenTelemetry instrumentation on every public entrypoint
The package SHALL emit OpenTelemetry counters, histograms, and spans on every public entrypoint via an injected PackerObservability bundle. The named instruments are packer_bundle_size_bytes, packer_entry_count, packer_pack_total, packer_unpack_total, packer_integrity_failure_total (counters), and packer_pack_duration_ms, packer_unpack_duration_ms, packer_entry_decode_ms (histograms, unit ms). Spans MUST wrap Packer.pack, Unpacker.unpack, packChunks, unpackChunks, and unpackChunksWithManifest. When no observability bundle is injected, the package MUST fall back to the no-op meter and tracer obtained from @opentelemetry/api (metrics.getMeter / trace.getTracer); no instrument call may throw.
Verified by: src/observability/observability.spec-conformance.test.ts::"records packer_pack_total and packer_bundle_size_bytes on every pack"; src/observability/observability.spec-conformance.test.ts::"records packer_unpack_total and a duration histogram on every unpack"; src/observability/observability.spec-conformance.test.ts::"increments packer_integrity_failure_total when unpack rejects on integrity"; src/observability/observability.spec-conformance.test.ts::"emits a packer.pack span captured by an in-memory span exporter"; src/observability/observability.spec-conformance.test.ts::"emits a packer.unpack_chunks_with_manifest span and per-entry decode histogram observations".
PACKER-21 — i18n-keyed error messages via injected MessageResolver
The package SHALL route every user-visible error message through an injected MessageResolver (@suaveplan/types). A per-package English-defaults catalog lives at src/i18n/messages.ts keyed by packer.error.<CODE>.<scenario>. Constructor options (PackerOptions.messageResolver, PackChunkedOptions.messageResolver, UnpackChunkedOptions.messageResolver) accept a caller-supplied resolver; when absent, the package falls back to defaultPackerResolver which reads the local catalog. Every throw new PackerError(CODE, message) site MUST pass a resolver-returned string, never a hard-coded English literal. The catalog MUST be Object.freezed and every catalog key MUST be reachable from at least one throw site in src/.
Verified by: src/i18n/messages.spec-conformance.test.ts::"every key in the catalog is referenced from at least one throw site in src/"; src/i18n/messages.spec-conformance.test.ts::"custom MessageResolver is consulted by Unpacker.unpack on every error path"; src/i18n/messages.spec-conformance.test.ts::"default resolver returns the English catalog value when no resolver is injected".
PACKER-22 — @suaveplan/retry on IO-backed source reads
The package SHALL route every IO-backed source pull (every reader.read() call against a ReadableStream consumed by normalizeSource or the abstract collect helper) through @suaveplan/retry's withRetry. The retry policy MUST be configurable per call via a retryConfig?: RetryConfig option on PackerOptions, PackChunkedOptions, and UnpackChunkedOptions. When retryConfig is absent the package MUST default to a single-attempt policy (maxAttempts: 1) so wire behaviour matches cluster #1. When retryConfig is supplied the retry loop MUST honour the caller's AbortSignal: cancellation MUST abort the retry loop immediately (no further attempts, no further sleeps) and surface as a RetryAbortedError.
Verified by: src/retry/retryable-read.test.ts::"retries up to maxAttempts on a failing reader"; src/retry/retryable-read.test.ts::"cancels the retry loop when AbortSignal fires mid-backoff"; src/retry/retryable-read.spec-conformance.test.ts::"default policy is a single attempt with no retries"; src/retry/retryable-read.spec-conformance.test.ts::"retryRead surfaces RetryAbortedError when signal fires before first read".
PACKER-23 — Idempotent repeat-pack short-circuit
The package SHALL expose an injectable idempotency cache on PackerOptions.idempotency ({ store, ttlMs?, enabled? }). When enabled, Packer.pack(data, opts?) MUST compute a content-derived dedup key from blake3(data) plus the packer's pipeline parameters (compressionLevel, encryption.algorithm, signing enabled bit), look the key up in the supplied IdempotencyStoreAdapter, and on hit return the previously-built PackedData without re-running the gzip / AEAD / sign / integrity pipeline. On miss the pipeline MUST run as before and the resulting PackedData MUST be written back to the store under the same key with the configured TTL (default 86_400_000 ms / 24 h). Idempotency MUST be opt-in: callers that do not pass idempotency see the legacy non-cached behaviour.
Verified by: src/idempotency/idempotency.test.ts::"second pack with identical input short-circuits to cached PackedData"; src/idempotency/idempotency.test.ts::"cache miss populates the store with the resulting PackedData"; src/idempotency/idempotency.spec-conformance.test.ts::"idempotency is disabled by default"; src/idempotency/idempotency.spec-conformance.test.ts::"custom IdempotencyStoreAdapter is consulted exactly once per pack".
PACKER-24 — Whole-file AbortSignal propagation
The package SHALL accept an AbortSignal on every async public entrypoint and MUST check the signal at every yield point. Unpacker.unpack accepts UnpackOptions.signal? and MUST check it before integrity verify, before signature verify, before AEAD decrypt, before gunzip, and before the final emit. Packer.pack accepts an additional overload pack(data, opts: PackOptions) where PackOptions.signal? is checked before compression, before encryption, before signing, before integrity compute, and before the final return. packChunks accepts PackChunkedOptions.signal? and MUST check it on every loop iteration before yielding the next packed chunk. Aborted operations MUST throw PackerError(PACKER.ABORTED) with the i18n catalog message packer.error.ABORTED.<entrypoint>. The original Packer.pack(data, filename?) overload MUST remain a valid call shape for back-compat.
Verified by: src/unpacker/unpacker.spec-conformance.test.ts::"rejects with PACKER.ABORTED when signal is pre-aborted"; src/unpacker/unpacker.spec-conformance.test.ts::"rejects with PACKER.ABORTED when signal fires between pipeline steps"; src/packer/packer.spec-conformance.test.ts::"rejects with PACKER.ABORTED when opts.signal is pre-aborted"; src/chunked/packer/packer.spec-conformance.test.ts::"aborts mid-stream when signal fires after the second chunk"; src/packer/packer.spec-conformance.test.ts::"legacy pack(data, filename) overload still surfaces mimeType".
PACKER-25 — Injected Clock and Rng everywhere
The package SHALL accept clock?: Clock and rng?: Rng (types from @suaveplan/types) on every public option bundle (PackerOptions, PackChunkedOptions, UnpackChunkedOptions). Every production read of wall-clock time MUST go through the resolved Clock (no direct Date.now()); every production source of randomness MUST go through the resolved Rng (no direct Math.random() / crypto.getRandomValues); every elapsed-time measurement MUST go through an injected monotonicClock?: MonotonicClock (defaults to a wrapper around performance.now()). The defaults MUST produce byte-identical wire output to the cluster #1 behaviour. Determinism: two Packer.pack calls with identical inputs, identical options, and a seeded Rng MUST produce byte-identical PackedData.data and identical metadata.integrity values.
Verified by: src/packer/packer.spec-conformance.test.ts::"timestamp is sourced from the injected Clock"; src/packer/packer.spec-conformance.test.ts::"AEAD nonce is sourced from the injected Rng"; src/packer/packer.spec-conformance.test.ts::"two packs with identical inputs and seeded Rng produce byte-identical output"; src/runtime/runtime.spec-conformance.test.ts::"no production file calls Date.now / Math.random / crypto.getRandomValues directly".
PACKER-26 — @suaveplan/schema-registry integration
The package SHALL register every Zod schema in src/schemas/packer.schemas.ts (PackerOptionsSchema, UnpackOptionsSchema, ChunkedPackerOptionsSchema, ManifestSchema) plus a packer-chunk-format subject capturing the wire-format version byte, into a process-singleton SchemaRegistry exposed via getPackerSchemaRegistry(). The packer-chunk-format subject MUST register V1 (the current wire format) under a BACKWARD compatibility policy with evolution metadata { formatVersion: "1", encoding: "binary", description: "v1 fixed-width 164-byte header + AEAD payload" } so a future V2 entry can be added without disturbing V1. Every other schema MUST be registered under its own subject (PackerOptions, UnpackOptions, ChunkedPackerOptions, Manifest) carrying the metadata { formatVersion: "1" }. A registerPackerSchemas(registry) function MUST allow callers to register the same schemas into any external SchemaRegistry instance for cross-package validation.
Verified by: src/schemas/registration.test.ts::"registers every option schema as a subject with formatVersion 1 metadata"; src/schemas/registration.test.ts::"records packer-chunk-format V1 with binary encoding and BACKWARD compatibility"; src/schemas/registration.spec-conformance.test.ts::"getPackerSchemaRegistry returns a process-singleton populated with the canonical subjects"; src/schemas/registration.spec-conformance.test.ts::"registerPackerSchemas writes into a caller-supplied registry without mutating the global singleton".
PACKER-27 — @suaveplan/feature-flags for format-version rollouts
The package SHALL accept a flags?: PackerFlagsOptions bundle on PackerOptions and route the wire-format selection through the resolved PackerFeatureFlags provider. The exported constant PACKER_FLAG_KEYS.FORMAT_V2 === "packer.format.v2" MUST identify the V2 rollout flag. When no provider is supplied, defaultPackerFlags() MUST act as a no-op that returns the V1 default (false) for every flag. When the resolved provider reports packer.format.v2 === true, Packer.pack MUST throw PackerError(PACKER.FORMAT_VERSION_UNSUPPORTED) with the catalog message packer.error.FORMAT_VERSION_UNSUPPORTED.v2-not-implemented; this is a versioning gate — the V2 codec is a future change. A caller-supplied @suaveplan/feature-flags Evaluator MUST be acceptable as the provider via resolvePackerFlags({ evaluator, context? }).
Verified by: src/flags/flags.test.ts::"defaultPackerFlags returns false for packer.format.v2"; src/flags/flags.test.ts::"resolvePackerFlags adapts a feature-flags Evaluator into a PackerFeatureFlags provider"; src/flags/flags.spec-conformance.test.ts::"Packer.pack throws PACKER.FORMAT_VERSION_UNSUPPORTED when packer.format.v2 is enabled"; src/flags/flags.spec-conformance.test.ts::"Packer.pack succeeds in V1 when flags option is omitted"; src/flags/flags.spec-conformance.test.ts::"a caller-supplied feature-flags Evaluator drives the format-version gate".
PACKER-28 — Plugin / extension interface
The package SHALL expose a PackerPlugin contract carrying six lifecycle hooks (onPackStart(ctx), onEntry(ctx), onPackEnd(ctx), onUnpackStart(ctx), onEntryDecoded(ctx), onUnpackEnd(ctx)), each optional and each invoked in plugin-declaration order. Plugins are registered via plugins?: ReadonlyArray<PackerPlugin> on PackerOptions. Packer.pack MUST invoke onPackStart exactly once before the pipeline, onEntry exactly once per entry packed (one for whole-file mode), and onPackEnd exactly once after the final result is composed. Unpacker.unpack MUST invoke onUnpackStart / onEntryDecoded / onUnpackEnd symmetrically. Any plugin error MUST be caught and re-thrown as PackerError(PACKER.PLUGIN_FAILED) with a catalog message packer.error.PLUGIN_FAILED.<hook> and the original error carried on error.cause.
Verified by: src/plugins/plugins.test.ts::"runs onPackStart / onEntry / onPackEnd in declaration order"; src/plugins/plugins.test.ts::"runs onUnpackStart / onEntryDecoded / onUnpackEnd in declaration order"; src/plugins/plugins.test.ts::"wraps thrown plugin errors as PackerError(PACKER.PLUGIN_FAILED) with cause"; src/plugins/plugins.spec-conformance.test.ts::"a noop-logger plugin observes every lifecycle hook"; src/plugins/plugins.spec-conformance.test.ts::"a double-integrity sidecar plugin contributes SHA-256 alongside BLAKE3".
PACKER-29 — fast-check property-based round-trip + determinism
The package SHALL include fast-check property tests pinning the pack/unpack round-trip identity, streaming↔batch equivalence, and seeded-Rng determinism invariants. Property assertions MUST run over arbitrary Uint8Array inputs of length 0..1024 (at least 25 runs per property). Round-trip identity: for every data, unpack(pack(data)) returns bytes byte-equal to data. Streaming equivalence: the concatenation of every PackedChunk.bytes emitted by packChunks(asyncIter(data), { ...same fileKey/signKey/baseNonce }) MUST byte-equal the wire bytes of packChunks(data, { ...same opts }) consumed from a whole-buffer source. Determinism: two Packer.pack runs with identical inputs, identical options, the same seeded Rng and the same fixed Clock MUST produce byte-identical PackedData (both data and every byte of metadata.integrity).
Verified by: src/__property__/round-trip.property.test.ts::"pack then unpack recovers the original bytes for arbitrary inputs"; src/__property__/round-trip.property.test.ts::"chunked streaming pack matches whole-buffer chunked pack byte-for-byte"; src/__property__/determinism.property.test.ts::"two packs with identical inputs and seeded Rng produce byte-identical bundles".
PACKER-30 — mitata benchmark suite
The package SHALL ship a runnable mitata benchmark suite at src/__benchmarks__/packer.bench.ts covering: (a) whole-file Packer.pack over a fixed 1 KiB payload, (b) whole-file Unpacker.unpack over the result of (a), (c) chunked packChunks over a single-chunk source, (d) chunked packChunks over a 1000-chunk source, (e) computeWholeFileIntegrity over a fixed 1 KiB payload, and (f) a plugin-overhead comparison (Packer.pack with zero plugins vs. with a no-op plugin). The benchmark MUST be runnable via bun run benchmark declared in package.json and MUST execute without error. Baseline numbers MUST be published in README.md under a ## Benchmarks section with a hardware/runtime context line.
Verified by: src/benchmarks-conformance/packer.bench.spec-conformance.test.ts::"declares the six named benchmark cases"; src/benchmarks-conformance/packer.bench.spec-conformance.test.ts::"package.json declares a bun run benchmark script"; src/benchmarks-conformance/packer.bench.spec-conformance.test.ts::"README.md publishes a Benchmarks section with a hardware context line".