suaveplan/openspec/archive/2026-05-23-enterprise-streams-metadata/tasks.md

Tasks — @suaveplan/streams-metadata

• Change ID: enterprise-streams-metadata
• Package: @suaveplan/streams-metadata
• Target path: packages/foundation/flow/streams-metadata

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 Worktree under .claude/worktrees/agent-a9864414c72f2d392 is the active migration worktree branched off genesis@ea6e6df5d; branch renamed to feat/streams-metadata before any code was written
• 0.3 Confirm the package set in MANIFEST.md matches the actual package tree; regenerate via bun scripts/folder-reorg/generate-manifest.ts before archive

1. Spec authoring

• 1.1 Read upstream source at /mnt/s/web/suaveplan/packages/universal/streams-metadata/ end to end
• 1.2 Read upstream enterprise audit /mnt/s/web/suaveplan/enterprise/streams-metadata.md
• 1.3 Read genesis reference packages: @suaveplan/streams (parent BaseTransform), @suaveplan/mime (detection API), @suaveplan/exif (readMetadata semantics)
• 1.4 Draft proposal.md with parity checklist + design upgrades
• 1.5 Draft specs/streams-metadata/spec.md — every requirement carries a **Verified by:** line at authoring time

2. Implementation — scaffold

• 2.1 Create packages/foundation/flow/streams-metadata/ with package.json (@suaveplan/streams-metadata, version 0.1.0, sideEffects: false)
• 2.2 Workspace deps: @suaveplan/error workspace:^, @suaveplan/events workspace:^, @suaveplan/exif workspace:^, @suaveplan/mime workspace:^, @suaveplan/streams workspace:^, @suaveplan/types workspace:^, tslib catalog:build
• 2.3 Dev deps: @suaveplan/testing workspace:^, @types/node catalog:, @vitest/coverage-istanbul catalog:testing, typescript catalog:, vite catalog:build, vite-plugin-dts catalog:build, vitest catalog:testing
• 2.4 tsconfig.lib.json extends ../../../../tsconfig.base.json; vite.config.ts mirrors @suaveplan/streams; vitest.config.ts enforces 100/100/100/100 thresholds (provider: 'istanbul')
• 2.5 All test files import runner primitives from @suaveplan/testing/runner per CLAUDE.md §11

3. Implementation — features

• 3.1 src/errors/errors.ts — defineCodes("STREAMS_METADATA", [...]) registry + StreamsMetadataError base + factory subclasses
• 3.2 src/types/payload.ts — MetadataMode, MetadataPayload, MimeDetectionResult, EnrichedPayload
• 3.3 src/types/process-options.ts — ProcessOptions shape (signal + clock + logger) structurally compatible with BaseTransform
• 3.4 src/events/events.ts — StreamsMetadataEvents type alias
• 3.5 src/mime/mime.ts — MimeTransform extends BaseTransform<{}, StreamsMetadataEvents> + MimeTransformOptions; module-load registration of JPEG / PNG signatures via @suaveplan/mime::registerSignature to defeat the upstream mime dist tree-shake
• 3.6 src/exif/exif.ts — ExifTransform extends BaseTransform<{}, StreamsMetadataEvents> + ExifTransformOptions (with read?: ReadOptions pass-through)
• 3.7 src/metadata/metadata.ts — MetadataTransform extends BaseTransform<{}, StreamsMetadataEvents> composing children; forwards mime:detected + exif:detected; emits metadata:complete or metadata:error

4. Tests

• 4.1 Sibling .test.ts for every implementation file under src/; every it(...) carries { timeout: 5000 }
• 4.2 errors.test.ts — every code resolves through the registry, error chain preserves cause
• 4.3 mime.test.ts — magic-bytes wins over extension, extension fallback, octet-stream fallback, event emission, passthrough, listener errors swallowed
• 4.4 exif.test.ts — JPEG / PNG happy path, gibberish raises ExifFailedError, read options forwarded, passthrough, abort handling
• 4.5 metadata.test.ts — happy path composes, child failure emits metadata:error + returns original input, event forwarding, passthrough, dispose chains children

5. Documentation

• 5.1 Sibling .md per implementation .ts with all six required sections
• 5.2 Root README.md linking every co-located .md

6. Pre-publish gate

• 6.1 bunx biome check src/ exits clean
• 6.2 bunx tsc --noEmit --composite false -p tsconfig.lib.json exits clean
• 6.3 bunx vitest run --coverage at 100/100/100/100
• 6.4 bun ../../../../scripts/docs-check.ts . exits clean
• 6.5 Zero direct vitest / bun:test imports in src/

7. Archive

• 7.1 Fold specs/streams-metadata/spec.md into openspec/specs/streams-metadata/spec.md
• 7.2 git mv openspec/changes/enterprise-streams-metadata openspec/archive/2026-05-23-enterprise-streams-metadata
• 7.3 Regenerate MANIFEST.md (bun scripts/folder-reorg/generate-manifest.ts)