← all branches

feat/one-api

needs attentionviewing older commit
dc794a7 · incrementalpre-PRreviewed 2026-07-20 23:46 UTC0H · 5M · 5L · 2I
The branch
Purpose
Establish the One-API program on this codebase: one contract tree, one mount, audience as metadata.
Goal
Land U0 groundwork (rule encoding, route inventory, id-registry merge) that every later parity wave builds on.
Sub-goals
  • SG-1: Encode One-API rule + canonical-form SSOT rewording
  • SG-2: Route classifier script + committed 245-route inventory
  • SG-3: PublicIdPrefix registry merge; cjb/cfj resolves to cfj
The changes (whole branch)
What
New .claude/rules/one-api.md (125 lines); canonical-form.md precision; PublicIdPrefix in shared-kernel absorbs utility + metrics prefixes, adds ULID_BODY_PATTERN + publicIdRegex(); utility domain and api schemas become re-export shims; 7 hardcoded regex literals replaced with publicIdRegex(); CFE_JOB_PREFIX corrected cjb→cfj; registry integrity test; 445-line classifier script + 5400-line route inventory.
Why
Unify the scattered PublicIdPrefix registries (core in shared-kernel, utility in base.ts, each had different values including the cjb/cfj collision) and encode the One-API architectural decision as an auto-loaded .claude/rules file.
Areas
.claude/rules/+138−7packages/shared-kernel/+72−12packages/api/src/schemas/+72−97domains/utility/src/schema/+5−27packages/database/src/schema/+3−1scripts/one-api/+5845−0
Blast
16 files, +6162/-97 lines (5400 in generated JSON). Runtime change surface: shared-kernel types (new helpers), public schema regexes (7 sites, equivalent substitution), CFE_JOB_PREFIX value. No route behavior changes.
➖typecheck· node_modules not installed on runner➖tests· node_modules not installed on runner➖ci· no CI runs found for branch➖coderabbit· no .coderabbit.yaml

Findings · 12

correctness2

medium

Seed file uses retired cjb_ prefix — demo jobs unresolvable via public API

packages/database/src/seed-utility-demo.ts

Three demo CFE job rows use publicId: 'cjb_001_test_queued' etc. With publicIdRegex(PublicIdPrefix.CfeJob, 'i') now matching /^cfj_.../i, these IDs will never match a GET /v1/jobs/:id request.

low

Unit test fixtures still use cjb_ prefix strings

domains/utility/src/cfe-job/__tests__/cfe-job.decisions.test.ts

Test fixtures use cjb_... publicIds. Update to cfj_ for accuracy.

conventions5

medium

Two doc files still say cjb_ for CfeJob — will mislead future developers

.claude/rules/ontology.md:87

Both .claude/rules/ontology.md:87 and domains/utility/CLAUDE.md:20 list cfe-job/ | cjb_. Update both tables to cfj_.

medium

isValidPublicId and extractPrefix hardcode ULID pattern instead of using ULID_BODY_PATTERN

packages/shared-kernel/src/types/ids.ts:124

ULID_BODY_PATTERN was introduced in this diff but isValidPublicId (line 124) and extractPrefix (line 134) still embed the literal string. Fix: new RegExp('^[a-z]{3}_' + ULID_BODY_PATTERN + '$').test(id).

medium

route-inventory.json committed without CI staleness gate

scripts/one-api/route-inventory.json

No CI step re-runs classify-routes.ts and diffs the output. Add a CI check or move to .branch/reference/ per one-api.md §Knowledge conventions.

low

PublicIdSchema in common.schemas.ts hardcodes ULID pattern

packages/api/src/schemas/common.schemas.ts:22

Missed opportunity to reference ULID_BODY_PATTERN in this file that was changed in the diff.

info

isValidPublicId accepts any 3-char prefix — not constrained to the registry

packages/shared-kernel/src/types/ids.ts:123

Pre-existing limitation. Add a JSDoc note to guide callers toward publicIdRegex where prefix identity matters.

tests3

medium

Regression test covers only CfeJob; 12 other migrated regex literals untested for structural equivalence

packages/api/src/__tests__/schemas/public-id-prefix-registry.test.ts:63

The 'publicIdRegex equals the previously hand-written literal' test validates only the cfj case. A table-driven test would cover all 13 migrated literals.

low

No round-trip test verifying cfj_ ID would have failed old cjb pattern

packages/api/src/__tests__/schemas/public-id-prefix-registry.test.ts

A generate→validate round-trip using PublicIdPrefix.CfeJob would close this gap.

low

isValidPublicId and extractPrefix have no dedicated unit tests

packages/shared-kernel/src/types/ids.ts:123

isValidPublicId accepts any 3-char prefix (not constrained to registry); extractPrefix null-return path untested.

improvement2

low

classify-routes.ts imports 5 internal contract files individually — brittle to renames

scripts/one-api/classify-routes.ts:25

Individual imports instead of a barrel. If any file is renamed, the script silently breaks.

info

one-api.md says 'binary marker' but inventory uses op:'binary' + binary:true

.claude/rules/one-api.md

Cosmetic inconsistency between rule description and emitted inventory schema.

History · 47 commits

  1. 82bb5b9blockedincremental5H · 5M · 4L2026-08-12 01:48
  2. 90aa3d5needs attentionincremental1H · 5M · 3L2026-08-11 19:37
  3. 29d19a0needs attentionincremental1H · 5M · 9L2026-08-11 17:41
  4. 9bd8a0cneeds attentionfull0H · 5M · 9L2026-08-11 02:14
  5. 62ec3f7needs attentionincremental2H · 5M · 6L2026-08-10 22:51
  6. f93bca9needs attentionincremental2H · 5M · 8L2026-08-10 17:51
  7. 052db6fneeds attentionincremental1H · 3M · 4L2026-08-09 21:13
  8. 45699caneeds attentionincremental0H · 7M · 11L2026-08-09 17:44
  9. b843d8aneeds attentionincremental1H · 7M · 9L2026-08-09 04:05
  10. e1757b8needs attentionincremental0H · 3M · 6L2026-08-05 02:11
  11. 7a762faneeds attentionincremental2H · 5M · 5L2026-08-05 01:25
  12. 3300a60needs attentionincremental2H · 4M · 7L2026-08-04 19:06
  13. 0c8a7f5needs attentionincremental0H · 4M · 9L2026-08-04 18:15
  14. 345f42eneeds attentionincremental2H · 6M · 9L2026-08-04 17:28
  15. 8338a9aneeds attentionincremental5H · 14M · 14L2026-08-04 00:33
  16. 41be4c3needs attentionincremental0H · 5M · 7L2026-08-03 23:49
  17. 5ed593dneeds attentionincremental1H · 6M · 6L2026-08-03 21:32
  18. b333e25needs attentionincremental4H · 9M · 8L2026-08-03 21:00
  19. 5642cccneeds attentionincremental2H · 3M · 2L2026-08-03 20:17
  20. 73b0b39needs attentionincremental3H · 10M · 13L2026-07-31 18:29
  21. b19852eneeds attentionincremental0H · 1M · 5L2026-07-29 05:04
  22. 3845205needs attentionincremental3H · 6M · 4L2026-07-29 04:47
  23. eb8eb50needs attentionincremental0H · 1M · 2L2026-07-29 03:03
  24. f4720a3needs attentionincremental6H · 8M · 7L2026-07-29 02:54
  25. f8d341ablockedincremental2H · 2M · 5L2026-07-29 00:00
  26. a7f1a64needs attentionincremental2H · 8M · 8L2026-07-28 18:41
  27. 738b60bblockedincremental3H · 6M · 5L2026-07-28 00:46
  28. 2c248b6needs attentionincremental8H · 12M · 8L2026-07-27 23:23
  29. 1346cc0needs attentionincremental2H · 8M · 6L2026-07-27 20:15
  30. 0716018needs attentionincremental2H · 11M · 12L2026-07-27 19:22
  31. 215cd2dneeds attentionincremental3H · 6M · 5L2026-07-27 17:04
  32. ec46958needs attentionincremental0H · 3M · 5L2026-07-27 16:51
  33. de7b337blockedincremental4H · 9M · 14L2026-07-27 06:36
  34. b1bb9c0needs attentionincremental1H · 2M · 4L2026-07-27 05:09
  35. 4701d11needs attentionincremental0H · 4M · 3L2026-07-27 04:44
  36. e1626c4needs attentionincremental3H · 9M · 10L2026-07-27 03:21
  37. 195f198needs attentionincremental3H · 3M · 3L2026-07-25 01:22
  38. 42c7358safeincremental0H · 0M · 0L2026-07-22 20:46
  39. 85b9018needs attentionincremental0H · 1M · 6L2026-07-21 23:51
  40. a7b2a9aneeds attentionincremental0H · 9M · 12L2026-07-21 18:49
  41. c2ee0daneeds attentionincremental4H · 7M · 7L2026-07-21 02:17
  42. e8ffa5eneeds attentionincremental4H · 7M · 5L2026-07-21 01:33
  43. a2d2a54needs attentionincremental2H · 7M · 3L2026-07-21 00:51
  44. 576fbd6needs attentionfull1H · 6M · 7L2026-07-21 00:35
  45. d3465e8needs attentionincremental1H · 7M · 10L2026-07-21 00:23
  46. dc794a7needs attentionincremental0H · 5M · 5L2026-07-20 23:46current
  47. 9082773needs attentionfull1H · 3M · 3L2026-07-20 23:13