suaveplan/openspec/archive/2026-05-26-api-host-reserved-prefix/tasks.md

Tasks — Host Reserved-Prefix Contract

1. Implementation

• 1.1 Add src/reserved-prefix/reserved-prefix.types.ts with ReservedPrefix branded type and ReservedPrefixError<TCode> shape.
• 1.2 Add src/reserved-prefix/reserved-prefix.ts exporting:
  • HOST_RESERVED_PREFIXES: ReadonlyArray<string> (frozen, deduped, lowercase, slash-normalised).
  • isReservedPrefix(prefix: string): boolean.
  • normalisePrefix(prefix: string): string.
  • assertPrefixAvailable<TCode extends string>(prefix: string, codeFactory: (collision: string) => Error): void.
• 1.3 Add sibling reserved-prefix.md (≥200 words, Purpose/Features/Usage:Basic/Usage:Advanced/API Reference/Implementation Notes).
• 1.4 Add src/reserved-prefix/index.ts barrel (named re-exports only — rule 10).
• 1.5 Wire ./reserved-prefix subpath into package.json exports.
• 1.6 Re-export from top-level barrel src/index.ts.

2. Tests

• 2.1 Unit: reserved-prefix.test.ts — coverage of every predicate path (exact match, normalised match, child path, sibling path, unrelated prefix). 100% istanbul on touched modules.
• 2.2 Conformance scenarios: prefix normalisation (/Internal ↔ /internal, trailing slash, missing leading slash), assertion throws when reserved, no-op when free.

3. Pre-publish gate

• 3.1 bunx turbo lint typecheck test --filter=@suaveplan/api-host green.
• 3.2 bunx turbo test:coverage --filter=@suaveplan/api-host 100% on touched modules.

4. Archive

• 4.1 Fold delta into openspec/specs/api-host/spec.md.
• 4.2 Move folder to openspec/archive/2026-05-26-api-host-reserved-prefix/.