Discovery measurement and scale implementation plan

For agentic workers: Use subagent-driven-development for the bounded store, client and offline-data tasks. The controller owns server attribution and integration. Continue within the approved scope without a new execution-choice prompt.

Goal: Produce trustworthy, versioned discovery observations and confirmed outcomes, bounded serving state, and reproducible temporal evaluation tooling before promoting a new recommendation model.

Architecture: Keep Neon/pgvector, Redis, ClickHouse and PostHog. A signed page receipt binds each opportunity to the server's actor, visit, world/group, position, time and policy. Append canonical events in PostgreSQL; mirror only allowlisted columns through existing ClickPipes. Snapshot ranking inputs when candidates are ordered, including queued candidates, and retain them on retries. Client intent is distinct from server-confirmed state changes. Evaluation uses immutable snapshots and matured, post-exposure outcomes.

Tech stack: Existing TypeScript/Hono/Drizzle/Redis/React; Python standard-library offline tooling; existing ClickHouse CDC.

Contract

type DiscoveryAttribution = { token: string; worldId: string };
// Cursor responses add attributionToken?: string. Original card identity is
// retained when selecting a translated sibling for a save or new session.
// POST /api/feed/events extends each event with immutable eventId, occurredAt,
// attributionToken and optional foreground durationMs.
// POST /api/library/:id and /api/sessions accept discoveryAttribution.
// Canonical discovery_events has id,eventType,occurredAt,receivedAt,actorId,
// userId,visitId,feedRequestId,opportunityId,worldId,languageGroupId,position,
// policyVersion,featureVersion,modelId,payload. Legacy feed_events stays separate.

Tasks and verification

• [x] Store worker: tests first for concurrent admission, expiry, replay and revision CAS; implement shared Redis per-actor/global admission and bounded cleanup without silently truncating valid streams. Preserve the session-store interface. Document defaults, measurements and load limits.
• [x] Controller: test receipt tampering, actor binding, guest-to-user transition, event-time bounds, page membership and idempotency. Implement DB-free receipt/event validation, append-only schema and explicit migration, and opt-in ingestion. DISCOVERY_MEASUREMENT_ENABLED defaults off until the migration is applied.
• [x] Controller: test immutable features across delayed pages/retries. Preserve ranking-time snapshots in the bounded pending queue and committed pages; never reconstruct yesterday's features from today's metadata. Log per-world served opportunities before returning an attributable response.
• [x] Client worker: tests first for immutable occurrence IDs/time, bounded retries, byte limits, foreground impressions/dwell, per-card receipt propagation and language/session-picker flows. Legacy behavior remains usable when no receipt is available.
• [x] Controller: record saves and new consumer sessions from actual mutation success, exclude creator/ephemeral play and existing Library/group membership, validate selected-language group against receipt. Failed or duplicate mutations cannot become a fresh success. Canonical guest events retain their original identity; linkage is explicit.
• [x] Offline worker: tests first for duplicate events, future-feature rejection, intent versus success, interval union, distinct UTC return days, D7 censoring and temporal split gaps. Build a credential-free JSONL dataset/manifest command. Do not modify or promote the legacy trainer using invalid historical labels.
• [x] Controller: prepare additive source/warehouse CDC SQL and reconciliation queries; no production DDL or new subscription is needed for implementation. Keep snapshots/content-free events on a declared retention policy.
• [x] Integration: inspect independent changes, run focused tests, hosted typecheck/build and full generated OSS verification; independent spec/quality review and fix findings. Keep source/test export boundaries correct. See the verification report for pre-existing full-hosted-suite failures and the serial Windows exported-test command.
• [x] Release: update draft PR(s) with evidence, deployment/migration order, rollback and remaining live-load/observation gates. Research paid alternatives from official sources and document upgrade triggers rather than purchasing speculatively. Measurement draft PR #177 is stacked on foundation PR #172; deployment gates remain open.

Decisions

• Continuation work starts from foundation commit 49eec145a in the same isolated worktree, on codex/discovery-measurement; the foundation PR remains separately reviewable.
• The user explicitly authorized continuing and has flexible budget. No paid service is provisioned merely because it might be useful. Private chat bodies remain unnecessary.
• Guest history before identification is unknown, not proof that a story is new. Serving snapshots retain authoritative first-known evidence and continuous-history coverage; confirmed outcomes preserve that exposure-time classification. Deleted Library/chat history remains in a durable ledger. Offline coverage reports unknown cohorts separately.
• Exact serving feature collection applies to the opt-in cursor stream. Legacy/CDN events are not silently upgraded into trustworthy observations.
• Real D7 outcomes require deployment plus follow-up time. Neither unit tests nor offline metrics can establish causal user uplift.