feat/discovery

Non-providers debug path: getDiscoverySignalState outside try/catch — breaks Result<T,E>

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

The getDiscoverySignalState call inside `if (input.includeDebug)` for non-providers orgs sits OUTSIDE the try/catch block that wraps the providers path. If the DB query throws, the exception propagates uncaught out of getDiscoveryGapShell instead of returning err(FeatureDiscoveryErrors.databaseError()). Breaks the Result<T,E> contract and causes an unhandled promise rejection in the handler. Move the call inside a try/catch or wrap the entire non-providers debug branch.

Zod signals schema is open z.record — should mirror closed DiscoverySignalState interface

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

signals is typed as z.record(z.string(), z.union([z.boolean(), z.number()])) — an open map. DiscoverySignalState is a fixed-key interface. A z.object({ hasCfeCredential: z.boolean(), ... }) would catch field-name drift at the schema boundary and satisfy the project pattern of hand-written Zod schemas that satisfies z.ZodType<ApiType>. New fields of other types added to the interface will silently pass the current open record.

Local dev: VERCEL_ENV unset means includeDebug=false (debug path untestable locally without manual env)

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

On a local dev machine where VERCEL_ENV is not set, process.env.VERCEL_ENV === 'preview' evaluates to false, so the debug path cannot be exercised locally without manually setting VERCEL_ENV=preview. Not a bug, but worth documenting for team members trying to test this feature.

Debug signals visible to all authenticated preview users, not just admins

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

DiscoveryGapDebug.signals contains live boolean state about an org's integrations. On preview, any authenticated org member — not just admins — receives this in the gap response. VERCEL_ENV gating is reliable so prod is safe. Consider restricting debug=true to isAdmin===true on preview if the debug block is only needed by the dev team.

VERCEL_ENV gating is server-side only — reliable, no client bypass

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

process.env.VERCEL_ENV in the Next.js API handler is a real server-side env var (not inlined into the client bundle like NEXT_PUBLIC_VERCEL_ENV). The gating is reliable — clients cannot spoof it. No action required.

process.env.VERCEL_ENV read twice in same handler file

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

The handler already reads process.env.VERCEL_ENV === 'preview' earlier (for relaxDailyBudget). The new includeDebug check repeats the raw env access inline. A shared const IS_PREVIEW = process.env.VERCEL_ENV === 'preview' at file scope (or module top) would keep the condition in one place.

DiscoveryGapDebug defined in shell file — canonical form prefers a types file

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

Per canonical form, view/result types used across the handler↔shell boundary belong in a .type.ts file. DiscoveryGapDebug and updated DiscoveryGapView are defined in feature-discovery.shells.ts. Low priority for a debug-only type.

includeDebug=true path (both branches) has no test coverage

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

Neither the non-providers+includeDebug=true path nor the providers+includeDebug=true path has integration test coverage. The non-providers debug branch calls getDiscoverySignalState and could fail or return wrong shapes silently. The providers branch spread is also unverified. A test asserting: (a) debug is absent when includeDebug=false, (b) debug.signals, debug.orgSegment, debug.isAdmin match expected values when includeDebug=true, for both org segments, would cover the new behavior.

getDiscoveryGapShell has no integration tests at all

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

The existing integration suite covers getDiscoverySpotlightShell but not getDiscoveryGapShell. The non-providers short-circuit (items:[], tourSeen:true) is a production code path that affects every non-providers org; a regression there would silently return empty results with no test catching it. This gap predates this commit but is worth addressing given the new nested branch now touching that exact code path.

No test verifying debug field is absent on non-preview

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

A handler-level or contract test asserting that debug is absent when VERCEL_ENV !== 'preview' would be a useful guard against accidental prod leakage. Given this is the first preview-env-gated diagnostic on this endpoint, a guard test is worth adding.

Debug object literal duplicated in two shell branches — extract helper

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

{ orgSegment: input.orgSegment, isAdmin: input.isAdmin, signals } is constructed identically in the non-providers early-return branch and the providers happy-path spread. Extract a const buildDebug = (signals: DiscoverySignalState): DiscoveryGapDebug => ({ orgSegment: input.orgSegment, isAdmin: input.isAdmin, signals }) and use it in both places. Prevents drift if DiscoveryGapDebug gains fields.

Unnecessary conditional spread — debug: result.value.debug is simpler

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

...(result.value.debug ? { debug: result.value.debug } : {}) is more complex than needed. debug: result.value.debug (typed DiscoveryGapDebug | undefined) produces identical JSON output since JSON.stringify omits undefined values. If explicit key-omission is intentional, add a comment explaining why.

Same conditional spread redundancy in shell providers path

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

...(input.includeDebug ? { debug: { ... } } : {}) could be debug: input.includeDebug ? buildDebug(signals) : undefined once a buildDebug helper is extracted. Cleaner and consistent with the handler simplification above.

Signal query asymmetry between non-providers (debug only) and providers (always) paths

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

Non-providers path only fetches signals when includeDebug=true; providers path always fetches them. The paths are mutually exclusive so no double-call occurs, but the structural asymmetry is worth noting if the non-providers guard is ever relaxed.