Initial Commit
This commit is contained in:
@@ -0,0 +1,164 @@
|
||||
# Enterprise hardening — `@suaveplan/packer` extensibility cluster
|
||||
|
||||
**Package**: `@suaveplan/packer`
|
||||
**Status**: PROPOSED
|
||||
**Type**: feature
|
||||
**Design**: (inline below — scope is well-bounded by the 5-item brief)
|
||||
**Spec delta**: ./specs/packer/spec.md
|
||||
|
||||
## Why
|
||||
|
||||
Cluster #1 (`enterprise-packer-integrity`, archived 2026-05-19) landed
|
||||
BLAKE3 content-addressable digests, the bundle-level Merkle root,
|
||||
mandatory integrity verification on unpack, full OpenTelemetry
|
||||
instrumentation, and i18n-keyed error messages. Cluster #2
|
||||
(`enterprise-packer-resilience`, archived 2026-05-19) added retry,
|
||||
idempotency, whole-file `AbortSignal`, and Clock / Rng injection.
|
||||
|
||||
This is the third and final cluster, addressing the remaining
|
||||
`enterprise/packer.md` audit gaps (L41, L42, L48, L72, L75):
|
||||
|
||||
1. No `@suaveplan/schema-registry` integration — the Zod option schemas
|
||||
exist in `src/schemas/packer.schemas.ts` but are not registered with
|
||||
the canonical versioned registry, and the chunk-format version byte
|
||||
has no companion registry entry that records `V1` as the shipping
|
||||
format and reserves the path to `V2`.
|
||||
2. No `@suaveplan/feature-flags` rollout surface — the audit calls for
|
||||
"Feature flags via `@suaveplan/feature-flags` for format-version
|
||||
rollouts" (L48); today the package writes V1 unconditionally and has
|
||||
no rollout path for a future V2 wire format.
|
||||
3. No plugin / extension surface — the audit calls for "A plugin /
|
||||
extension interface (where it makes sense) so downstream packages
|
||||
can contribute behaviour without forking" (L72). Today the packer is
|
||||
closed: every transform, integrity strategy, and codec is hard-wired.
|
||||
4. No `fast-check` property tests — the audit calls for "Property-based
|
||||
tests (fast-check) for pack/unpack round-trips and streaming-
|
||||
equivalence-to-batch invariants" (L42).
|
||||
5. No mitata benchmark suite — the audit calls for "Performance —
|
||||
benchmark suite in `src/__benchmarks__`, published numbers in the
|
||||
README, regression gate in CI" (L75).
|
||||
|
||||
After this cluster lands, `@suaveplan/packer` meets every checkbox in
|
||||
the `enterprise/packer.md` §3 + §4 + §6 acceptance criteria.
|
||||
|
||||
## What changes
|
||||
|
||||
- ADDED: `src/schemas/registration.ts` — registers every Zod schema in
|
||||
`src/schemas/packer.schemas.ts` plus a `packer-chunk-format` subject
|
||||
with V1 as the shipping wire-format version under a `BACKWARD`
|
||||
compatibility policy. `getPackerSchemaRegistry()` returns the
|
||||
process-singleton registry; `registerPackerSchemas(registry)`
|
||||
performs the registration against any caller-supplied
|
||||
`SchemaRegistry`.
|
||||
- ADDED: `@suaveplan/schema-registry` as a runtime dependency.
|
||||
- ADDED: `src/flags/flags.ts` — `PackerFeatureFlags` provider
|
||||
interface and `defaultPackerFlags()` no-op provider that returns the
|
||||
V1 default for every flag. `resolvePackerFlags(opts)` adapts a
|
||||
caller-supplied `@suaveplan/feature-flags` `Evaluator` or a raw
|
||||
provider into the internal `PackerFeatureFlags` shape.
|
||||
- ADDED: `flags?: PackerFlagsOptions` on `PackerOptions`. The write
|
||||
path now reads `packer.format.v2` from the resolved provider — when
|
||||
enabled, `Packer.pack` throws
|
||||
`PackerError(PACKER.FORMAT_VERSION_UNSUPPORTED)` with the catalog
|
||||
message `packer.error.FORMAT_VERSION_UNSUPPORTED.v2-not-implemented`
|
||||
(versioning gate — V2 is a future change, not a deferral).
|
||||
- ADDED: `@suaveplan/feature-flags` as a runtime dependency.
|
||||
- ADDED: `src/plugins/plugins.ts` — `PackerPlugin` contract, six
|
||||
lifecycle hooks (`onPackStart`, `onEntry`, `onPackEnd`,
|
||||
`onUnpackStart`, `onEntryDecoded`, `onUnpackEnd`),
|
||||
order-deterministic invocation via
|
||||
`PluginPipeline.runHook(name, ctx)`. Plugin errors surface as
|
||||
`PackerError(PACKER.PLUGIN_FAILED)`.
|
||||
- ADDED: `plugins?: ReadonlyArray<PackerPlugin>` on `PackerOptions`.
|
||||
`Packer.pack` and `Unpacker.unpack` invoke every registered plugin's
|
||||
hooks in declaration order.
|
||||
- ADDED: `PACKER.FORMAT_VERSION_UNSUPPORTED` and `PACKER.PLUGIN_FAILED`
|
||||
error codes in `error-codes.ts`.
|
||||
- ADDED: `src/__property__/round-trip.property.test.ts` and
|
||||
`src/__property__/determinism.property.test.ts` — `fast-check`
|
||||
property-based round-trip, streaming↔batch equivalence, determinism.
|
||||
- ADDED: `src/__benchmarks__/packer.bench.ts` — `mitata` benchmark
|
||||
suite covering whole-file pack/unpack, chunked pack (single + 1000
|
||||
chunks), integrity verify, plugin overhead. `bun run benchmark`
|
||||
script in `package.json` and a Benchmarks section in `README.md`.
|
||||
- ADDED: `mitata` as a devDependency (already present in the root
|
||||
catalog as `catalog:testing`).
|
||||
- MODIFIED: `src/index.ts` — exports `getPackerSchemaRegistry`,
|
||||
`registerPackerSchemas`, `PackerPlugin`, `defaultPackerFlags`,
|
||||
`resolvePackerFlags`, and the plugin / flags / registration types.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- V2 wire format implementation — this cluster lands the registry
|
||||
entry and the feature-flag gate; the V2 codec is a follow-up change
|
||||
that flips the throw into real encoding work. The throw is the spec
|
||||
contract for V2-not-implemented; not a deferral.
|
||||
- Mutation testing — orthogonal to the audit; opens a follow-up.
|
||||
- Codemod for breaking option changes — there are none in this
|
||||
cluster.
|
||||
|
||||
## Source mapping
|
||||
|
||||
This change derives from `../suaveplan/enterprise/packer.md`.
|
||||
|
||||
| Requirement | Source lines | Notes |
|
||||
|---|---|---|
|
||||
| PACKER-26 (`@suaveplan/schema-registry` integration) | L41 | Verbatim — "Zod schemas … `@suaveplan/schema-registry` integration, versioned evolution with explicit format-version bytes". |
|
||||
| PACKER-27 (`@suaveplan/feature-flags` rollouts) | L48, L79 | Verbatim — "Feature flags via `@suaveplan/feature-flags` for format-version rollouts" / "Feature flags for any risky new behaviour". |
|
||||
| PACKER-28 (plugin / extension interface) | L72 | Verbatim — "A plugin / extension interface (where it makes sense) so downstream packages can contribute behaviour without forking". |
|
||||
| PACKER-29 (`fast-check` property tests) | L42 | Verbatim — "Property-based tests (fast-check) for pack/unpack round-trips and streaming-equivalence-to-batch invariants". |
|
||||
| PACKER-30 (mitata benchmark suite) | L75 | Verbatim — "Performance — benchmark suite in `src/__benchmarks__`, published numbers in the README, regression gate in CI". |
|
||||
|
||||
### Requirements with no source line
|
||||
|
||||
None — every requirement maps directly to an audit bullet.
|
||||
|
||||
## Verification approach
|
||||
|
||||
- `src/schemas/registration.test.ts` + `.spec-conformance.test.ts` —
|
||||
pins registry contents, V1 evolution metadata, BACKWARD compatibility
|
||||
on subject reuse.
|
||||
- `src/flags/flags.test.ts` + `.spec-conformance.test.ts` — pins
|
||||
default no-op provider, custom evaluator wiring, V2 throw path.
|
||||
- `src/plugins/plugins.test.ts` + `.spec-conformance.test.ts` — pins
|
||||
hook ordering, error surface, downstream plugin example (noop logger
|
||||
+ double-integrity SHA-256 sidecar).
|
||||
- `src/__property__/round-trip.property.test.ts` — pack→unpack identity
|
||||
+ streaming↔batch equivalence under arbitrary inputs.
|
||||
- `src/__property__/determinism.property.test.ts` — deterministic
|
||||
output under seeded Rng + fixed Clock.
|
||||
- `src/__benchmarks__/packer.bench.ts` — runnable via
|
||||
`bun run benchmark`; baseline numbers published in `README.md`.
|
||||
|
||||
## Migration impact
|
||||
|
||||
Public-surface additions only. No existing signature changes shape —
|
||||
the new options are all optional with platform defaults. Two consumer
|
||||
packages (`@suaveplan/drive-plugin-chunks`, `@suaveplan/drive-webrtc`)
|
||||
are audited and the sweep is part of the gates; no existing call site
|
||||
changes shape.
|
||||
|
||||
## Impact
|
||||
|
||||
### Affected dependents
|
||||
|
||||
Run `bunx turbo ls --filter=...@suaveplan/packer` to enumerate.
|
||||
|
||||
- `@suaveplan/drive-plugin-chunks` — [x] tests run / [x] docs reviewed / [ ] no action needed
|
||||
- `@suaveplan/drive-webrtc` — [x] tests run / [x] docs reviewed / [ ] no action needed
|
||||
|
||||
If `tests run` is unchecked for any dependent, the change MUST NOT be
|
||||
folded into the canonical spec.
|
||||
|
||||
## Migration
|
||||
|
||||
No behavioral change for callers that did not pass the new options.
|
||||
Existing calls keep their previous semantics:
|
||||
|
||||
- **No `plugins` passed**: no hooks fire; behaviour identical to
|
||||
cluster #2.
|
||||
- **No `flags` passed**: `defaultPackerFlags()` is used; every flag
|
||||
returns the V1 default and `Packer.pack` writes the V1 format.
|
||||
- **No `registry` interaction needed**: callers that did not use
|
||||
`@suaveplan/schema-registry` before do not need to start now —
|
||||
registration is a process-singleton side effect available on demand.
|
||||
Reference in New Issue
Block a user