feat/subscription-gating

Payment-subscriber cron has no subscription gate for collect jobs

services/utility/bills/cfe/src/handlers/payment-subscriber.lambda.ts

filterBySubscriptionAccess was added to subscriber.lambda.ts (collect engine) but payment-subscriber.lambda.ts (the daily PS cron) has no equivalent guard. If PS jobs for canceled orgs are intentionally allowed (as the handler comments suggest), the omission should be explicitly documented in the payment-subscriber source to prevent accidental addition of a gate later.

UI call sites have no specific handling for 402 SUBSCRIPTION_INACTIVE

apps/platform/src/app/[locale]/(dashboard)/bills/_components/AddContractDrawer.tsx:265

Multiple UI call sites check err?.status === 409 but fall through to a generic error toast for 402. A canceled-org user will see a confusing generic message instead of a directed billing CTA. Affected: AddContractDrawer.tsx, StaleBillBadge.tsx, ContractServiceCell.tsx, contratos/page.tsx, BatchContractForm.tsx, BulkActionBar.tsx.

filterBySubscriptionAccess fail-open allows soft-deleted org groups

services/utility/bills/cfe/src/handlers/subscriber.lambda.ts:121

findManyByIds filters out soft-deleted orgs, so a soft-deleted org's RPU groups pass through as allowed (fail-open). In practice soft-deleted orgs should have cascaded subscription cleanup, but the timing window is undocumented.

SubscriptionBanner billingExempt check requires metadata in org API response

apps/platform/src/components/SubscriptionBanner.tsx:30

The banner reads metadata?.billingExempt from the org context. If the organization API response mapper does not expose the metadata field, exempt orgs with past_due/canceled status will see false-positive banners (though the server gate still correctly allows them through).

Fail-open on missing org bypasses subscription gate entirely

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

When findById returns null the guard returns ok(undefined) — any request with a JWT referencing a deleted or non-existent orgId is unconditionally permitted. The orgId must still come from a valid JWT claim, limiting the surface, but a safer pattern would be to block on not-found and only fail-open on genuine DB exceptions.

Subscription status field carried in SubscriptionInactiveError struct

domains/core/src/billing/feature-access.errors.ts:22

The error struct includes the raw subscriptionStatus field. Currently not surfaced in public API responses, but it is one property access away from a future logging/serialization slip. Consider removing status from the public-facing error or keeping it internal-only.

Internal org UUIDs logged in Lambda for blocked orgs

services/utility/bills/cfe/src/handlers/subscriber.lambda.ts:136

filterBySubscriptionAccess logs o.id (internal UUID PK) for blocked orgs. Prefer the public org.publicId (org_XXX) in operational logs.

Canceled-org user can create payment_status jobs at volume (no rate limit visible)

apps/platform/src/api/handlers/cfe-jobs.handler.ts:214

The payment_status carve-out is intentional. If these jobs have per-execution cost (Lambda/SFN), a canceled-org user could create them at volume. Rate limiting on the endpoint (not visible in this diff) would mitigate this.

SUBSCRIPTION_INACTIVE error code not registered in catalog

apps/platform/src/api/handlers/cfe-jobs.handler.ts:111

subscriptionInactiveResponse() emits error: "SUBSCRIPTION_INACTIVE" but this code has no entry in packages/api/src/responses/codes.ts. Per api-patterns.md every error code must be registered there; the internal JSendFailSchema in the contract is a local untyped copy that silently bypasses compile-time enforcement.

cfe-jobs contract uses local untyped JSendFailSchema shadow

apps/platform/src/api/contracts/cfe-jobs.contract.ts:33

The contract file re-declares a local JSendFailSchema that accepts any string as error, bypassing the catalog-typed factory in packages/api/src/schemas/jsend.schemas.ts. The missing SUBSCRIPTION_INACTIVE registration above is a direct consequence — the catalog-typed version would make it a compile error.

FeatureAccess and FeatureAccessLevel types in decisions file instead of type file

domains/core/src/billing/feature-access.decisions.ts:23

Canonical form requires domain types in {entity}.type.ts. FeatureAccess and FeatureAccessLevel are declared in feature-access.decisions.ts. No Drizzle mapping is needed, so a type file may be minimal, but placing return types in the decisions file deviates from the canonical pattern.

SubscriptionBanner.tsx duplicates SubscriptionStatus type instead of importing from domain

apps/platform/src/components/SubscriptionBanner.tsx:8

A local SubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'trialing' is declared locally. The comment cites avoiding server-only deps (drizzle), but SubscriptionStatus is a pure string-literal union — import type from @batu/core-domain is always elided by the bundler and never pulls drizzle into the client bundle.

No integration tests for handler subscription gates

apps/platform/src/__tests__/integration/cfe-jobs-subscription-gate.test.ts (new)

All three chokepoints in cfe-jobs.handler.ts (createCfeJob, retryCfeJob, createBatch) and one in public-v1/jobs.handler.ts have no integration tests. Missing scenarios: canceled org → 402; active org → pass; billingExempt=true overrides canceled → pass; payment_status type bypasses gate for canceled org.

No tests for requireActiveSubscription middleware fail-open and exempt paths

packages/api/src/middleware/__tests__/require-active-subscription.test.ts (new)

The middleware has two non-obvious behaviors: fail-open when org is not found (returns ok — untested), and billingExempt cast (stringified 'true' must NOT pass — untested). These are unit tests with mocked findById.

No tests for filterBySubscriptionAccess in subscriber Lambda

services/utility/bills/cfe/src/__tests__/subscriber-subscription-filter.test.ts (new)

The batch subscription filter is untested. Critical missing cases: mixed active/canceled batch; all-blocked returns empty array; missing org row is fail-open (not added to blocked set); billingExempt=true with canceled status is kept. A wrong blocked.has(g.orgId) check using mismatched ID fields would silently block everyone or no one.

No tests for findManyByIds query function

domains/core/src/organization/__tests__/organization.queries.test.ts (extend)

findManyByIds has a non-trivial early-return for empty ids array (guards Drizzle inArray edge case) and a soft-delete filter. Both are untested. Integration tests following the existing organization.queries.test.ts pattern.

No tests for SubscriptionBanner conditional rendering

apps/platform/src/components/__tests__/SubscriptionBanner.test.tsx (new)

The banner re-implements the gating policy (noted in its own comment). Without tests the server/client policy drift risk is undetected. Missing: active/trialing → null; past_due → amber warning; canceled → red blocker; billingExempt=true+canceled → null; CTA link locale.

No tests for cfe-job-client.ts error augmentation

apps/platform/src/app/[locale]/(dashboard)/bills/_lib/__tests__/cfe-job-client.test.ts (new)

The .status and .code fields on thrown errors are the mechanism callers use to detect 402 subscription errors. No test verifies a 402 response throws with e.status===402 and e.code==='SUBSCRIPTION_INACTIVE'.

SubscriptionInactiveError shape not pinned by test

domains/core/src/billing/__tests__/feature-access.decisions.test.ts

FeatureAccessErrors.subscriptionInactive() message is forwarded directly to the HTTP response body. No test pins the exact _tag, statusCode: 402, and message fields. A change to the message or statusCode would silently change API behavior.

No test for retry handler payment_status pipeline bypass

apps/platform/src/__tests__/integration/cfe-jobs-subscription-gate.test.ts (new)

The retry handler gates on job.pipeline !== 'payment_status'. A canceled org retrying a payment_status job must still pass — this exemption is untested. A regression here would block users from checking payment status during the exact moment they need it most.

Duplicated metadata billingExempt cast in two places

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

The pattern (org.metadata as Record<string,unknown> | null)?.billingExempt === true appears in both requireActiveSubscription and filterBySubscriptionAccess. Extract isBillingExempt(metadata: unknown): boolean into feature-access.decisions.ts.

Subscription gate block copy-pasted 3x in cfe-jobs.handler.ts

apps/platform/src/api/handlers/cfe-jobs.handler.ts

The guard check (type gate + requireActiveSubscription call + early return) is duplicated for create, retry, and batch with only the variable name differing. Extract into a helper to give the bypass rule a single location.

SubscriptionBanner.tsx uses pathname split instead of useLocale()

apps/platform/src/components/SubscriptionBanner.tsx

const locale = pathname.split('/')[1] || 'en' reimplements locale detection. Replace with useLocale() from next-intl — the pathname split breaks on root paths and routing changes.

SUBSCRIPTION_INACTIVE casing inconsistency between internal and public API

apps/platform/src/api/handlers/cfe-jobs.handler.ts

Internal surface emits SUBSCRIPTION_INACTIVE (uppercase SCREAMING_SNAKE) while public API uses subscription_inactive (lowercase). Even if intentional, derive from the same source to prevent future divergence.

findManyByIds fetches full org rows when only metadata + subscriptionStatus are needed

services/utility/bills/cfe/src/handlers/subscriber.lambda.ts

filterBySubscriptionAccess only reads metadata and subscriptionStatus but fetches full org rows. If the query layer supports projection, narrowing to those two fields reduces Lambda payload in cold paths.