suaveplan/openspec/archive/2026-05-18-add-api-plugin-search/tasks.md

Tasks — Add @suaveplan/api-plugin-search

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/api-plugin-search.md end-to-end
• 1.2 Verify no prior openspec/specs/api-plugin-search/spec.md exists
• 1.3 Read openspec/AGENTS.md Sections 13 and 14
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill ## Source mapping with line references to upstream
• 1.6 Draft specs/api-plugin-search/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 error-codes/error-codes.ts — 10 SEARCH.* codes + SearchError class
• 2.2 otel/instruments.ts — meter + 5 instruments (counters + histogram)
• 2.3 schemas/schemas.ts — all 13 Zod schemas (formerly upstream types.ts)
• 2.4 schemas/options.ts — SearchPluginOptionsSchema factory-options schema
• 2.5 analyzer/analyzer.ts — tokenize / stem / stop-words / 4 analyzers / getAnalyzer / listAnalyzers
• 2.6 service/service.ts — full in-memory engine (TF-IDF, facets, filters, sort, highlights, suggest); throws SearchError and emits OTel
• 2.7 routes/build-routes.ts — 9 OpenAPIHono routes
• 2.8 types/types.ts carries the typed event payloads (SearchQueryExecutedEvent, SearchIndexUpdatedEvent, SearchEventMap); the routes/build-routes.ts SearchRouteEvent discriminated union is the emitter contract — no as any casts
• 2.9 plugin/plugin.ts — createSearchPlugin factory (@suaveplan/api-plugin-shaped)
• 2.10 services/registry-augmentation.ts — searchIndexes slot on canonical ServiceRegistry
• 2.11 types/types.ts — internal types (SearchIndex, IndexedDocument, SearchPluginConfig)
• 2.12 index.ts — explicit named barrel + side-effect imports for the error-codes registry and the registry augmentation

3. Tests

• 3.1 Unit tests per feature module
• 3.2 api-plugin-search.spec-conformance.test.ts — type-level + barrel pins
• 3.3 Every it(...) carries { timeout: 5000 }

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 4.2 README links every co-located .md
• 4.3 STATUS.md row updated post-archival (other-session-owned; skipped per guidance)

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

• 5.1 bun run check — Biome 0/0/0
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-search
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-search
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-search
• 5.5 bunx turbo build --filter=@suaveplan/api-plugin-search

6. Pre-archive 9-row checklist

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary
• 6.3 Every error code in error-codes.ts thrown by at least one production path
• 6.4 Strict-mode behaviours tested both on and off
• 6.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup tested where claimed
• 6.7 No retroactive tick
• 6.8 No export * in any feature barrel
• 6.9 No direct vitest / bun:test imports in any test file

7. Archive

• 7.1 Fold spec delta into openspec/specs/api-plugin-search/spec.md
• 7.2 Move openspec/changes/add-api-plugin-search/ → openspec/archive/2026-05-18-add-api-plugin-search/