suaveplan/openspec/archive/2026-05-19-enterprise-packer-extensibility/tasks.md

Tasks — Enterprise hardening (extensibility cluster) for @suaveplan/packer

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/packer.md end-to-end
• 1.2 Read openspec/specs/packer/spec.md
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill in ## Source mapping table — every requirement cites a line range
• 1.6 Draft specs/packer/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles

2. Implementation — error codes (E-1 / E-2 / E-3)

• 2.1 Add FORMAT_VERSION_UNSUPPORTED and PLUGIN_FAILED codes to src/error-codes.ts with metadata.
• 2.2 Add catalog keys packer.error.FORMAT_VERSION_UNSUPPORTED.v2-not-implemented, packer.error.PLUGIN_FAILED.<hook> to src/i18n/messages.ts.

3. Implementation — schema registry (E-1)

• 3.1 Add @suaveplan/schema-registry to packer/package.json deps (workspace:^).
• 3.2 New src/schemas/registration.ts — registerPackerSchemas(registry) + getPackerSchemaRegistry(), registering every Zod schema in packer.schemas.ts plus a packer-chunk-format subject with V1 evolution metadata.
• 3.3 Sibling registration.md + registration.types.ts + index.ts barrel.
• 3.4 Subpath export ./schemas in package.json.

4. Implementation — feature flags (E-2)

• 4.1 Add @suaveplan/feature-flags to packer/package.json deps (workspace:^).
• 4.2 New src/flags/flags.ts — PackerFeatureFlags interface, defaultPackerFlags() no-op, resolvePackerFlags(opts) factory, PACKER_FLAG_KEYS constants.
• 4.3 Sibling flags.md + flags.types.ts + index.ts barrel.
• 4.4 Packer.pack reads packer.format.v2 from the resolved provider; when truthy, throws PackerError(PACKER.FORMAT_VERSION_UNSUPPORTED).
• 4.5 PackerOptions.flags?: PackerFlagsOptions threaded through AbstractPacker.resolvedOptions.
• 4.6 Subpath export ./flags in package.json.

5. Implementation — plugin interface (E-3)

• 5.1 New src/plugins/plugins.ts — PackerPlugin contract, PluginPipeline.runHook(name, ctx), error mapping to PACKER.PLUGIN_FAILED.
• 5.2 Sibling plugins.md + plugins.types.ts + index.ts barrel.
• 5.3 PackerOptions.plugins?: ReadonlyArray<PackerPlugin> threaded through AbstractPacker.
• 5.4 Packer.pack invokes onPackStart → per-entry onEntry → onPackEnd in declaration order around the pipeline.
• 5.5 Unpacker.unpack invokes onUnpackStart → onEntryDecoded → onUnpackEnd.
• 5.6 Subpath export ./plugins in package.json.

6. Tests — schema registry, flags, plugins

• 6.1 src/schemas/registration.test.ts + .spec-conformance.test.ts — every schema registered, V1 evolution metadata, BACKWARD compatibility, singleton invariant.
• 6.2 src/flags/flags.test.ts + .spec-conformance.test.ts — default provider returns V1 for every key, V2 throws PACKER.FORMAT_VERSION_UNSUPPORTED, custom evaluator wiring, integration with Packer.pack write path.
• 6.3 src/plugins/plugins.test.ts + .spec-conformance.test.ts — declaration-order hook fire, error → PACKER.PLUGIN_FAILED, noop-logger + double-integrity example plugins exercised against real Packer + Unpacker.

7. Tests — fast-check property (E-4)

• 7.1 src/__property__/round-trip.property.test.ts — pack→unpack identity over arbitrary Uint8Array inputs; streaming↔batch equivalence via chunked pack.
• 7.2 src/__property__/determinism.property.test.ts — same inputs + seeded Rng + fixed Clock ⇒ byte-identical bundles.

8. Benchmarks (E-5)

• 8.1 src/__benchmarks__/packer.bench.ts — mitata suite (whole-file pack/unpack, chunked single + 1000 chunks, integrity verify, plugin overhead).
• 8.2 bun run benchmark script in package.json.
• 8.3 README.md Benchmarks section with baseline numbers and hardware/runtime context line.

9. Documentation

• 9.1 Sibling .md for every new .ts (≥200 words, basic + advanced examples).
• 9.2 Update README.md Modules list with flags/, plugins/, schemas/registration.

10. Pre-archive verification (the 5-gate triple)

• 10.1 bun run check — Biome 0/0/0.
• 10.2 bunx turbo lint typecheck test --filter=@suaveplan/packer — green.
• 10.3 bunx turbo test:coverage --filter=@suaveplan/packer — 100/100/100/100.
• 10.4 bun scripts/openspec-conformance.ts @suaveplan/packer — exit 0.
• 10.5 bunx turbo build --filter=@suaveplan/packer — green.

11. Consumer sweep

• 11.1 bunx turbo lint typecheck test --filter=@suaveplan/drive-plugin-chunks --filter=@suaveplan/drive-webrtc — green.

12. Pre-archive 9-row checklist

• 12.1 Generics threaded; expectTypeOf assertions on every literal-type claim.
• 12.2 Zod schemas wired at every declared boundary.
• 12.3 Every error code in error-codes.ts thrown by at least one production path.
• 12.4 OTel instruments emitted from production paths.
• 12.5 No export * in feature barrels.
• 12.6 No direct vitest / bun:test imports.
• 12.7 No retroactive tick — every box above reflects work done in this change.
• 12.8 Sibling .md for every new .ts.
• 12.9 Items E-1, E-2, E-3, E-4, E-5 each have ≥1 production code path and ≥1 test pinning every named scenario.

13. Archive

• 13.1 Fold specs/packer/spec.md into openspec/specs/packer/spec.md.
• 13.2 Move openspec/changes/enterprise-packer-extensibility/ → openspec/archive/<yyyy-mm-dd>-enterprise-packer-extensibility/.
• 13.3 Refresh MANIFEST.md.