Orchestrator handoff

Last updated: 2026-09-12, Asia/Manila. Open this file first. Backend dev is at d937bfe with #86/#87 landed; frontend dev is at e4b5f5c with #31 landed. #88–#90 merged only into stale feature/review-transition-command and are absent from dev; corrected #91–#93 and dependent #95/#96 remain open.

Task and constraints carried forward

Own completion of backend #63: correct creator campaign/submission financial figures and payout history, campaign funding/CPM spend/RPM expense/remaining/payouts, staff review/fraud/groups, overlapping sponsor consistency, and persisted-observation filters/time series. Work in the main worktrees. Deliver small, reviewable PRs rather than a feature bundle. Do not silently implement other MVP families; accept their minimal producer contracts under the existing issues.

RBAC is separately owned. Keep current route protection, add precise TODO(RBAC) markers, and never choose speculative Whop permissions or edit central mappings for analytics. No issue closure without code/test/manual evidence. Preserve unrelated local changes. Use Conventional Commit subjects and a concise explanatory body when justified.

Canonical docs/ remains unversioned and has not been initialized or published. No issue was closed, no production data changed, and nothing was deployed. The pre-existing backend sponsor-report documentation modification and scraper observability work remain preserved outside analytics commits.

Current implementation wave

• A01 is backend PR #78, merged at f4ba2c3.
• The PR adds only src/utils/analytics/{contracts,fixtures}{,.test}.ts: additive contract v2, producer fact interfaces, exact reconciliation, and the independent two-campaign fixture. It changes no route, schema, migration, writer, provider integration, or RBAC mapping.
• Validation: 13 contract tests and 10 fixture tests passed; existing exact-rate domain/history/migration suites passed; targeted strict TypeScript passed; full backend build passed after the ignored generated Prisma client was refreshed from the sibling main worktree with identical schema/package-lock hashes.
• A02's pure projection slice is backend PR #79, merged at 40b3263. It adds deterministic observation baselines/deltas, explicit current and historical cohorts, coverage/provenance, bounded ranking, and a labelled legacy adapter without changing routes, schema, writers, or legacy payloads.
• A02 validation before merge: 17 projection/legacy tests, 23 A01 tests, and 11 rate tests passed; strict targeted TypeScript and full backend build passed.
• A07's pure committed-review projection and current-event adapter are backend PR #80, merged at 216fd63. They add bounded event-flow filters, actor/outcome/day reconciliation, stable pagination, and a strict adapter for the existing direct canonical event. The adapter preserves known successes while marking history and mixed legacy actor identity partial; it does not consume generic audit payloads or claim the producer is atomic.
• A07 validation before merge: 17 projection/adapter tests, 23 A01 tests, and 11 rate tests passed; strict targeted TypeScript and full backend build passed.
• Scraper prerequisite backend PR #81 merged at 00497d2, but it does not yet provide the normalized tracking observation source required by #37.
• The narrow #37 producer backend PR #82 merged at 5f7c88b. It adds the prospective immutable MetricObservation stream and atomic dual writes; its guarded PostgreSQL migration suite remains unrun until an explicit disposable loopback _test database is supplied.
• A02's normalized reader continuation backend PR #83 merged at c3568c4 after #82. It adds a strict raw-row adapter and one capped query with per-submission pre-window baselines, UTC [from,to), asOf, caller/scope checks, and separate prospective coverage. It never unions dual-written legacy snapshots. Build and four focused suites passed; its guarded PostgreSQL behavior test remains unrun for the same missing disposable database.
• A01, A02 projection/producer/reader, and the pure A07 slice are landed. A02 protected API #85 is landed at 9ae45d7; A07 protected API work is now in #95 (4a08fe3) stacked on #93, and A02 historical status is active on feature/performance-historical-status stacked on #95. #37/#41/#42/#51/#52/#63 remain OPEN; landed or review-ready code is not issue completion. #41/#42 still block historical status filters and #68 blocks normalized review accountability.
• Review-transition foundations frontend #31 and backend #86/#87 are landed. #88/#89/#90 merged only into a stale feature branch and do not provide dev coverage; corrected dev-targeted #91/#92/#93 remain open. A07 #95 is stacked on #93, A02 historical status #96 is stacked on #95, and frontend A14 #33 depends on #95.
• Backend payout adapter PR #89 (1ff5a50) is open as a sibling atop #87, with four focused tests and build validation; it makes no migration and calls no payment provider. Backend history reader PR #90 (31da155) is open as a sibling atop #87, with four reader tests, three route tests, and build validation; it reads normalized v1/v2 newest-first by (occurredAt,recordedAt,eventId), reports legacy/malformed diagnostics as partial, preserves the current SUBMISSION_MODERATION guard and exact TODO(RBAC), and introduces no migration or backfill. The protected ordered history reader branch is feature/review-history-reader. Known #42 producer coverage remains pending #87/#88/#89 merge, so #42 is not complete.
• Merged #85 adds strict protected creator/staff routes, date-only UTC normalization, a repeatable-snapshot current-accepted cohort and bounded top ranking. It also corrects normalized raw-observation coverage so it never claims legacy budget clamping or missing source time. Legacy routes and central RBAC mappings are unchanged.

Exact evidence baseline

Workspace: /home/kirbysmashyeet/Source/BloxClips.

Repository / directory	Inspected branch and state
Bloxclips-backend	Main worktree is on feature/analytics-performance-api from c3568c4; dev = origin/dev = c3568c4. Pre-existing modified docs/campaign-sponsor-reports.md remains unstaged and untouched.
BloxClips-frontend	Main worktree dev = origin/dev, 907963f; clean.
metric-scraper	Main worktree main = origin/main, 7fedb34; no dev branch exists. Pre-existing untracked src/observability/ left untouched; not baseline product evidence.
docs/mvp/operational-financial-analytics	This project brain: 10 Markdown overview/plan files, one issue snapshot JSON, 17 workstream Markdown files. Canonical docs/README.md has one navigation link added.

Refs were fetched. No applicable filesystem AGENTS.md was found in ancestor/main repository searches; session-supplied Git conventions were retained. Check for newly added instructions next session. Other worktrees/open branches are not landed evidence. Full pinned source anchors and merge provenance: evidence-index.

Issue hierarchy: do not repeat the summarized-count mistake

Native #63 tree = 3 issues / 2 leaves, all OPEN: #63 → #51 and #52. Both leaf sub_issues API responses were empty and neither body contains another child section. The user's expectation of nested descendants is not reflected in current GitHub. Dependencies do lead through other MVP trees.

Material backend dependency-family closure = 48 issues, including those 3, with 35 native leaves / 13 native parents; 43 OPEN / 5 CLOSED. The other 45 are dependencies/context families, not #63 descendants. All 51 backend non-PR issue bodies/native child endpoints were inventoried to check completeness. Historical #2/#23 and external frontend #29/scraper #8 are separate from the core count. #29 body-links #68 but lacks that native child edge. The complete issue tree and machine-readable snapshot retain exact nodes/states/edges and per-node implementation findings.

Already implemented versus remaining

Verified landed	Remaining implication
#70 exact immutable CPM/RPM versions, highest-applicable resolver, provenance and existing-policy backfill; #60/#61 CLOSED.	Do not rebuild rates. Group rate storage/loader #26/#27 and attributable earnings #53/#54 are missing. Current consumers still revalue totals.
#71 creation-based tracking for all moderation states; scraper #1 YouTube executor alongside TikTok/Instagram.	#36 worker recovery/deployment and #37 source-time/identity/correction history remain incomplete. Snapshots currently use recording time and may be budget-clamped.
#69 canonical append-only AuditEvent infrastructure and legacy-store retirement; #30 CLOSED.	#68 feature producers/contextual history incomplete; status review event is still best effort after non-atomic mutation. #76 CUID-versus-UUID validation defect blocks valid group membership audit writes.
#74 sponsor grant/report, frontend #28 and #30 expiry UI; #67 CLOSED.	Reuse it. Report has current accepted performance and recorded completed gross allocations, with limited legacy coverage. Shared admin/sponsor projection is not yet implemented.
#73 hybrid staff capability foundation and frontend #27 panel.	#75 business mappings, #77 old owner-check defect, frontend #29 browser acceptance remain. Preserve current guards; do not implement old custom-role design.
Creator/admin screens, public campaign metrics, groups/membership history, legacy payout request/review/send/history.	Missing funding, earning/spend journals, durable holds and exact payout allocations/Whop operations; financial and operational totals cannot yet reconcile fully.

Concrete current gaps to retain in review: overview uses paidOut; creator campaign route adds once (no verified duplicate addition); campaign list spent uses CPM while staff detail spent uses RPM; historical charts infer missing days and clamp negative corrections; creator summary totals only loaded page; overview sparklines are synthetic; some creator RPM labels say CPM; payout balance audiences use different clipper/referral scopes; public campaign routes remain unauthenticated. System map identifies sources/guards for every relevant displayed family.

Settled architecture

Read financial-contract before touching code. Key requirements:

• Analytics reads exact facts owned by funding/history/earnings/fraud/payout domains; it does not calculate or write new entitlements during a query.
• CPM spend, RPM gross expense, gross/net earnings, unfinalized/held/available/reserved/paid, and recovery are distinct. remainingCommitted = committedFunding - cpmSpend; payouts do not debit campaign CPM budget again.
• Paid means finalized allocation with provider success; current approval counters are not paid. Unknown operations retain reservation. Cross-campaign operations allocate amounts, never repeat their whole total in each campaign.
• Decimal-string v2 amounts, explicit scope/currency/basis/asOf/coverage; old numeric fields preserved during backend-first rollout. Missing historical attribution/time stays partial/unavailable.
• UTC half-open windows and signed recorded observation changes with pre-window baseline. No upload-day/current-state inference. Legacy snapshot recording time and budget clamping remain labelled.
• Group membership-at-fact-time cohorts can overlap. Member sums reconcile within each group; de-duplicated group union plus unattributed facts reconciles to campaign. A rate-winning-source breakdown is a different measure.
• Public report privacy/token controls remain; no new sensitive financial fields on currently public /api/campaigns. New staff navigation waits for the separate RBAC owner's approved attachment, not speculative changes.

Proposed PR order and parallelism

17 analytics PRs in execution-plan, each with a workstream document. Prerequisite PRs remain in their existing MVP groups and are not included in this count.

1. A01 contracts/fixtures.
2. A02 query/legacy-adapter tests can start after A01; its completed API needs #37 and reliable #41/#42 events for historical status filters. A07 review analytics can run independently once those review events are reliable. A14 review UI follows A07.
3. Separately owned funding/history/rate integration → earnings/budget → holds → payout reservation/operation/completion contracts unlock A03 financial projections.
4. A04 creator finance API, A05 payout history API, A06 staff/campaign finance API in parallel with explicit route hunk ownership; then A08 risk, A09 groups, A10 sponsor consistency as their facts land.
5. A11 creator overview/campaign UI and shared formatter; A12 creator history/payout UI, A13 staff/campaign UI, A15 risk UI, A16 group UI can then run in parallel as APIs land. A14 remains independent.
6. A17 cross-surface regression, migration/cutover evidence and manual acceptance.

At this snapshot #31/#78/#79/#80/#82/#83/#85/#86/#87 are landed. Corrected review carry-forwards #91/#92/#93 and dependent #95/#96 remain open; frontend A14 #33 is open. A03 and its downstream financial units remain gated on named upstream facts. #41/#42/#68 and database evidence still bound review completion. The sponsor's explicitly named current-accepted cohort remains a distinct compatibility scope. No unit is blocked on inventing an RBAC mapping.

Next implementation wave

1. Land corrected dev-targeted #91/#92/#93 before their dependent #95/#96, then run disposable PostgreSQL behavioral evidence for transition and history ordering. Deploy backend #95 before frontend #33. Do not mark #41/#42 complete until the corrected PRs merge and database evidence passes. There is no active Discord review writer because the dashboard owns that path.
2. Retain the unrun fresh/upgrade PostgreSQL migration and reader behavior gates for an explicitly selected disposable loopback _test database.
3. Keep A03 blocked until authoritative financial readers land: A01 already owns the pure reconciliation arithmetic, so another adapter now would duplicate it. Reassess other pure units only where they add a nonduplicative contract.
4. Preserve creator ownership and the current staff ANALYTICS guard in the route unit, with the documented TODO(RBAC) on protected cross-creator data. When #41/#42/#68 land, complete historical status and A07's normalized reader/protected route using the reviewer-accountability TODO(RBAC).
5. Preserve the backend sponsor documentation change and scraper observability work; do not stage either into analytics commits. Do not close #37/#51/#52/#63 from draft code or partial tests.

The mixed-version rollout for the review-transition wave is frontend-first: deploy frontend #31 before backend #87. Rollback retains v2 facts and disables/reverts the reader or writer behavior as needed; it does not delete committed audit facts.

Decisions requiring owner input later

None blocks A01 or this execution plan. D-01 requires owner confirmation of tentative seven-day finality and its anchor/grace before shipping #55. D-02 needs finance/product tax/fee/threshold/referral policy before new payout promises/dispatch. D-03 needs upstream economic posting rules across approval/rate/cap/cutoff changes, with owner input only where economics remain unspecified. D-05 needs evidenced legacy-data/cutover treatment; never assume old rows disposable. D-06 requires provider/account sandbox evidence. D-04 needs a product answer only if additive group totals are requested beyond cohort/union reporting. RBAC mapping/owner-access checks stay with #75/#77. Exact evidence/owners/gates are in decisions.

Validation and limits

For #82, the five focused tracking/performance suites, Prisma schema validation, build, and diff checks passed. For #83, the adapter/reader/performance/legacy suites and build passed. For #85, the build and eight focused suites pass; the full backend offline run reported 43 passing / 5 failing; the five failures are the pre-existing database-dependent capability/staff/report suites running against the intentionally unreachable offline URL, and no analytics/tracking suite failed. The guarded integration runner correctly refused to run without TEST_DATABASE_URL.

No database, provider, browser, worker, or deployment action ran. The configured database was inspected only enough to determine it is remote and named bloxclips_dev, so it was not used. Fresh and upgrade migration tests, replay/concurrency behavior, reader query behavior, and rollback rehearsal still require an explicitly supplied loopback database ending in _test. #76's historically reported group integration failures remain unrerun.

The updated project-brain files have no trailing whitespace. The earlier full documentation validation remains the baseline; link/source counts were not rerun after adding #82/#83 references. Backend git diff --check passed and the only uncommitted product change is the preserved sponsor-report documentation edit. #85 merged with an 11-file diff that excluded the preserved sponsor-report documentation edit. Future unit completion records still need actual merge/manual and migration evidence.

Merge-topology correction and next ready units

Backend dev is d937bfe with #86/#87 landed; frontend dev is e4b5f5c with #31 landed. Backend #88 (614120f), #89 (1ff5a50), and #90 (31da155) merged only into stale feature/review-transition-command and are absent from dev. Open carry-forward PRs are scraper #91 (eaee854), payout #92 (9f38877), and history #93 (151a80f), all based on the corrected dev target. A07 #95 is stacked on #93 and A02 historical status #96 is stacked on #95.

The next review units are to land corrected #91/#92/#93, then #95/#96, and run disposable PostgreSQL behavioral evidence for transition and history ordering. No TEST_DATABASE_URL is configured, configured databases are remote/non-test, and local PostgreSQL is down; this evidence remains blocked until an explicit loopback _test database exists. Deploy backend #95 before frontend #33. Do not mark #41/#42 complete until the dev-targeted merges and database evidence pass.

Latest wave record (2026-09-12)

Backend PR #96 (d113a4e) is the active A02 historical-status slice on feature/performance-historical-status, stacked on #95. Historical cohorts are evaluated per submission from committed review history ordered by (occurredAt, recordedAt, eventId): the first event before the observation is the baseline; if no such event exists, status is unknown. Any malformed event, campaign-conflicting event, or discontinuity in the affected submission's event sequence makes that submission's historical status unknown. Historical mode does not issue a current-accepted query or use current state as a fallback. Validation passed across 11 analytics/routes suites, creator-route checks, the backend build, and git diff --check. No migration or RBAC mapping changed.

Keep #41/#42 incomplete and #91/#92/#93/#95/#96 open. The missing disposable loopback PostgreSQL _test evidence remains a blocker, as does #68's normalized reviewer-accountability coverage. PR #96 is review-ready evidence and freezes the historical cohort contract; it does not complete A02, A07, #41, #42, #51, #52, or #63.

A07 protected review analytics is backend PR #95 (4a08fe3), stacked on #93. It protects GET /api/admin/analytics/reviews, runs the canonical bounded event query, normalizes v1/v2 events, returns partial diagnostics, aggregates before pagination, and orders ties with recordedAt. Conflicting campaign attribution is excluded as malformed. It adds no platform filter, current-state inference, schema or migration and preserves the exact SUBMISSION_MODERATION TODO. Six review-related suites passed, plus build and diff checks. This is review-ready progress, not A07 completion.

A02's current branch is feature/performance-historical-status, stacked on #95, with historical cohort scope frozen. #91/#92/#93 remain OPEN and are not on dev; #41/#42 remain incomplete. #68 normalized accountability coverage and disposable loopback _test database evidence remain blockers. Preserve these blockers in status, owner, PR, tests and unlock records; do not claim A02/A07 completion.

Frontend A14 review analytics is PR #33, commit 97f7662, on feature/review-analytics-ui targeting frontend dev, with backend #95 (4a08fe3) stacked on #93 as its dependency. PR #33 is OPEN, CLEAN and MERGEABLE. It keeps committed-event summaries separate from queue state; applies UTC exclusive-to/campaign/status filters; supports aggregate/day buckets, lazy submission history and stable asOf pagination; preserves partial/unavailable/unknown actor labels and full reasons; and invalidates analytics after successful moderation. The backend contract does not expose reviewer filtering, and the PR adds no reviewer filter, permission mapping, or current-status inference; it retains the exact TODO(RBAC).

A14 validation covered focused analytics and command tests, changed lint, TypeScript, production build and git diff --check. Database, manual and browser evidence remain outstanding, so A14 is in review/open and unlocks A17 only after those gates and review complete. Backend #41/#42/#51/#52/#63/#68 were revalidated OPEN and unassigned on 2026-09-12; backend #95/#96 and frontend #33 remain OPEN, CLEAN and MERGEABLE. Do not mark these issues or A14 complete from branch evidence alone.

Files and maintenance

Created: README, issue-tree, system-map, financial-contract, execution-plan, verification-plan, decisions, handoff, readiness-matrix, evidence-index; issue-snapshot.json; workstreams A01–A17. Updated only the canonical docs README navigation outside this folder. Temporary inventories under /tmp are noncanonical and unnecessary to continue.

Update workstream status/assignee/PR/evidence as work proceeds. After a source contract or policy changes, update decisions, financial-contract, readiness and handoff together. Keep this folder concise; link domain docs and pinned code instead of copying audit history or raw payloads. Do not initialize/publish a docs repository to make a commit.