feat/discovery

Hub deep-links silently break on 768–1023 px (tablet gap)

apps/platform/src/components/discovery/DescubreMenu.tsx:71

DescubreMenu renders at md+ (≥768 px) via `hidden md:block`, but FeatureSpotlight only fires at isDesktop (≥1024 px). A 768–1023 px user sees the badge, clicks, navigates with ?descubre=<key>, but the coachmark never appears. Component comment claims 'Same gating as the spotlight surface' but the CSS and JS breakpoints diverge by 256 px.

createSecret restore-then-update not atomic — partial failure leaves restored secret with stale value

packages/secrets/src/client/secrets-manager.client.ts:123

If RestoreSecret succeeds but UpdateSecret throws, the secret is live with the old value. On retry ResourceExistsException fires and UpdateSecret is retried — recoverable, but inconsistent window. Should be documented.

getGapHandler maps errors via mapGetSpotlightError — shared error type risks non-exhaustive switch on divergence

apps/platform/src/api/handlers/discovery.handler.ts:116

Works today because both shells share GetDiscoverySpotlightError. If getDiscoveryGapShell ever adds a distinct variant, TypeScript only catches it if the gap shell declares a different return type.

DescubreMenu fires /gap query on mobile even though button is CSS-hidden

apps/platform/src/components/discovery/DescubreMenu.tsx:54

enabled flag does not gate on viewport size. `hidden md:block` hides the render but the TanStack Query hook still runs on mobile, unlike FeatureSpotlight which guards with isDesktop.

Raw DB error messages leaked to callers via serverError()

domains/cross-domain/src/feature-discovery.shells.ts:110

Caught exceptions (postgres errors with table/column/constraint names) are forwarded verbatim into FeatureDiscoveryErrors.databaseError() → mapGetSpotlightError → serverError(message) → HTTP 500 body. Fix: log server-side, return a generic string.

relaxDailyBudget spoofable via forged Host header

apps/platform/src/api/handlers/discovery.handler.ts:71

An authenticated user can send Host: anything.vercel.app to bypass the ≤1/day spotlight budget, corrupting analytics signals. Not an access-control bypass. Fix: derive from VERCEL_ENV server-side env var.

requestedKey validated by closed Zod enum — no injection risk

packages/api/src/schemas/discovery.schemas.ts:40

?descubre= param parsed by DiscoveryFeatureKeySchema (strict z.enum of 7 known keys). Values outside the enum are rejected before the handler.

getGapHandler IDOR absent — requireOrgAccess enforces membership before any read

apps/platform/src/api/handlers/discovery.handler.ts:103

orgId validated as PublicId. requireOrgAccess does DB-backed membership check. Shell receives org.id from DB result, not URL. Runs inside createRLSDb. No IDOR.

createSecret TOCTOU race is benign — org-scoped deterministic paths

packages/secrets/src/client/secrets-manager.client.ts:123

Two concurrent first-time saves for the same org converge to the same credential value. No cross-org restoration risk. Matches AWS recommended idempotency pattern.

FeatureDiscoveryErrors defined in .shells.ts — canonical-form requires .errors.ts

domains/cross-domain/src/feature-discovery.shells.ts:62

canonical-form.md prescribes a dedicated {entity}.errors.ts for discriminated union errors. FeatureDiscoveryErrors, FeatureDiscoveryDatabaseError, GetDiscoverySpotlightError are co-located in the shell module.

getGapHandler omitted from file-level handler list comment

apps/platform/src/api/handlers/discovery.handler.ts:4

The file-level comment lists getSpotlight and recordOutcome but omits getGap.

add_contract signal not covered in listEligibleSpotlights gap tests

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:597

All 3 listEligibleSpotlights tests use baseSignals (hasContracts=true), so add_contract is never eligible. No test verifies add_contract appears in the gap when hasCfeCredential=true && hasContracts=false. Hub badge count for the new signal is uncovered.

listEligibleSpotlights count/ordering contract never asserted — toContain() only

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:598

Tests only use toContain() — never assert total count or uniqueness. A bug doubling a page's candidates or duplicating a key across pages would be invisible.

cfe_setup priority 0 blocks add_contract for non-admins — no explicit test

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:95

When hasCfeCredential=false and isAdmin=false, cfe_setup is filtered by adminOnly and add_contract is suppressed by CFE suppression. No test covers this interaction for the new signal. Covered accidentally but not intentionally.

requestedKey + relaxDailyBudget combination untested

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:571

No test covers both requestedKey and relaxDailyBudget set simultaneously. Current code short-circuits at requestedKey; a refactor could silently change semantics.

getDiscoveryGapShell has zero integration tests

domains/cross-domain/src/__tests__/feature-discovery.integration.test.ts

getDiscoverySpotlightShell has 5 integration tests (RLS isolation, consumer gate, cross-org probe). getDiscoveryGapShell has zero. Missing: consumer org returns empty, cross-org probe (RLS safety), providers org with CFE credential + no contracts returns add_contract.

pathForPage has no unit tests — fallback is silent misdirection

apps/platform/src/components/discovery/spotlight-catalog.ts:40

No tests verify each known page maps to the correct path or that unknown key returns the fallback without throwing. A new page added to DISCOVERY_PAGES but not PAGE_BY_PATH would silently deep-link to the wrong page.

relaxDailyBudget: same-page budget-spent exposure not tested

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:552

Existing test uses a different-page exposure. A monitoring exposure (same page, lastSeenAt=NOW) + relaxDailyBudget=true is not verified.

add_contract non-admin eligibility not explicitly tested

domains/cross-domain/src/__tests__/feature-discovery.decisions.test.ts:535

adminOnly=false for add_contract. Only coincidental coverage via default input() factory. An explicit assertion protects against an accidental adminOnly=true change.

createSecret InvalidRequestException text-match brittleness untested

packages/secrets/src/client/secrets-manager.client.ts:117

The pending-deletion branch is triggered by error.message.includes('scheduled for deletion'). AWS copy is not a stable interface. Unit tests would pin the string check and verify re-throw for other InvalidRequestException messages.

getDiscoveryGapShell duplicates the fetch from getDiscoverySpotlightShell

domains/cross-domain/src/feature-discovery.shells.ts:137

Both shells call getDiscoverySignalState + discoveryQueries.findByProfileId in Promise.all. A shared fetchDiscoveryInputs(db, input) helper would eliminate duplication and make FCIS fetch→decide→write explicit.

providers-only guard appears 4 times across the call stack

domains/cross-domain/src/feature-discovery.shells.ts:86

The `orgSegment !== 'providers'` check is in both shells and both pure decision functions. Shell-level short-circuits are the canonical location; the guard inside decisions is redundant given shell enforcement.

DescubreMenu casts response body to a local type alias instead of the schema-derived type

apps/platform/src/components/discovery/DescubreMenu.tsx:64

The `as ReadonlyArray<{key: SpotlightFeatureKey; page: SpotlightPage}>` cast hides future schema drift. ts-rest client infers from DiscoveryGapResponseSchema which already has the right shape.

isAdmin derivation duplicated inline in both discovery handlers

apps/platform/src/api/handlers/discovery.handler.ts:79

`membership.role === 'admin' || membership.role === 'owner'` appears in both handlers. A shared isAdminRole(role) helper in org-auth middleware would prevent divergence if a new role is added.

createSecret: RestoreSecret → UpdateSecret race window not documented

packages/secrets/src/client/secrets-manager.client.ts:123

If a concurrent process completes deletion between RestoreSecret and UpdateSecret, UpdateSecret throws ResourceNotFoundException — unhandled at this level. The AWS message-text check is also an undocumented unstable string. Both should be commented, or UpdateSecret should be wrapped in a retry.

pathForPage uses a linear scan on every Descubre menu render

apps/platform/src/components/discovery/spotlight-catalog.ts:40

PAGE_BY_PATH.find() is O(N) per item per render. A pre-built reverse Map<SpotlightPage, string> constant would be O(1). Trivial at 3 entries; worth doing when adding the 4th page.

Gap and spotlight endpoints fetch the same DB data independently on the Descubre click flow

apps/platform/src/components/discovery/DescubreMenu.tsx:56

When a user clicks a Descubre item and navigates to a page with a spotlight, two network fetches go out in parallel for the same underlying data. The gap response is a superset of the spotlight response.