feat/subscription-gating

Comment claims null is handled via isOrgAllowed, but it is not

packages/api/src/middleware/require-active-subscription.ts:34

The comment reads 'Fail-open (null org → allowed) + exempt override, both via isOrgAllowed.' After the refactor, the `!org` short-circuit handles null before isOrgAllowed is called at all — isOrgAllowed never sees null in this path. The behaviour is correct but the comment misleads: a future reader would expect isOrgAllowed to be the null gate. Should read: null handled by explicit `!org`; exempt check via isOrgAllowed.

Unreachable fallback '?? [unknown-org]' violates CLAUDE.md 'don't handle scenarios that can't happen'

services/utility/bills/cfe/src/domain/subscription-access.ts:43

The comment itself admits the fallback is unreachable ('Every blocked id was written to publicIdById in the same loop'). CLAUDE.md explicitly prohibits adding fallbacks or error handling for scenarios that cannot happen. The '?? "[unknown-org]"' branch, plus the three-line comment justifying it as a 'future refactor' guard, should be removed. Use a non-null assertion (publicIdById.get(id)!) or restructure to let TypeScript prove non-nullability, with no comment.

Comment misdescribes control flow: null is no longer handled via isOrgAllowed

packages/api/src/middleware/require-active-subscription.ts:34

The comment says 'Fail-open (null org → allowed) ... both via isOrgAllowed' but after the refactor the null case is caught by the explicit `!org` guard before isOrgAllowed is ever called. isOrgAllowed now handles only the exempt-override path for non-null orgs. The comment should reflect the actual split: `!org` → fail-open, `isOrgAllowed(org)` → exempt override.

Refactor preserves behavior — existing tests sufficient

packages/api/src/middleware/require-active-subscription.ts:34

The !org short-circuit is logically equivalent to the prior isOrgAllowed(null)===true path. Existing tests cover null-org, exempt, active, and inactive paths. No new tests needed.

PaymentRequiredCode is a pure type export — untestable at runtime

packages/api/src/responses/codes.ts:206

Type aliases have no runtime surface. No test needed.

Fallback sentinel '[unknown-org]' is on a structurally unreachable branch — no test needed

services/utility/bills/cfe/src/domain/subscription-access.ts:43

The blocked set and publicIdById map are populated in the same loop, so the ?? branch cannot fire with well-formed input.

Unreachable fallback should be an invariant assertion, not a silent sentinel

services/utility/bills/cfe/src/domain/subscription-access.ts:40

The comment admits the fallback '[unknown-org]' is unreachable. A silent sentinel will silently corrupt log data if the invariant is ever broken by a refactor. Replace with an explicit invariant throw: `const pub = publicIdById.get(id); if (!pub) throw new Error('invariant: no publicId for orgId ' + id); return pub;` — this is the correct pattern for an impossible-at-runtime branch.

Comment explains the TypeScript compiler, not the business rule

packages/api/src/middleware/require-active-subscription.ts:34

The new comment documents TypeScript narrowing mechanics ('The `!org` short-circuit narrows org to non-null') rather than the non-obvious WHY. Per conventions, comments should explain why, not what. A one-liner like `// Null org is allowed (fail-open); exempt orgs are also allowed.` is sufficient.