Usage analytics

The usage module counts what the player did with a teacher's deals. A serve is one deal resolved by the public API; it counts once the player's first telemetry event lands it. Plays, results and graded difficulty are rolled up per owner, deal code and UTC day by a nightly job, and every usage read sums rollups up to the job's watermark then counts raw telemetry live after it. The API records serves, the jobs runtime runs the rollups, the standings and the perseverance snapshots, and the teacher app reads the usage tile and the detail view.

Import from @workspace/training/domain/usage and @workspace/training/application/usage. Reads reuse UsagePeriod from @workspace/training/domain/entitlements.

Domain

Perceived difficulty

The perceived difficulty of one play is a 0 to 100 index from the stars earned, the auction errors n and the minutes of card play t. k = 10 × (n + t − 2) grades the 2- and 3-star plays: 0 and 1 star score 100, 2 stars score 50 + k clamped to [50, 100], 3 stars score k clamped to [0, 50]. A play whose auction was never the learner's to bid counts no error. Plays longer than the outlier bound leave the aggregate.

derivePerceivedDifficulty({ stars: 1, auctionErrors: 0, playSeconds: 30 }); // => 100
derivePerceivedDifficulty({ stars: 2, auctionErrors: 1, playSeconds: 120 }); // => 60 (50 + 10 × (1 + 2 − 2))
derivePerceivedDifficulty({ stars: 3, auctionErrors: 0, playSeconds: 240 }); // => 20 (10 × (0 + 4 − 2))
derivePerceivedDifficulty({ stars: 3, auctionErrors: 0, playSeconds: 60 }); // => 0 (floored)

isDifficultyOutlier(DIFFICULTY_OUTLIER_SECONDS + 1); // => true: longer than 15 minutes
parseDifficultyStars(4); // => null: not a verdict

aggregatePerceivedDifficulty([
  { stars: 3, auctionErrors: null, playSeconds: 240 }, // auction never bid: counts no error => 20
  { stars: 2, auctionErrors: 1, playSeconds: null }, // never finished: graded as instant => 50
  { stars: 3, auctionErrors: 0, playSeconds: 20 * 60 }, // outlier, dropped
  { stars: 5, auctionErrors: 0, playSeconds: 10 }, // not a verdict, dropped
]); // => { difficultySum: 70, gradedCount: 2 }

Analytics windows

The detail view reads over a rolling window that always ends with today, half-open so the current UTC day is included, unlike the calendar-month entitlement period.

const now = new Date("2026-10-08T15:30:00Z");

resolveUsageAnalyticsWindow("last7", now);
// => { start: 2026-10-02T00:00:00Z, end: 2026-10-09T00:00:00Z } (today included, half-open)
resolveUsageAnalyticsWindow("season", now).start; // => 2026-07-01T00:00:00Z
getSeasonStart(new Date("2026-03-01T00:00:00Z")); // => 2025-07-01T00:00:00Z

Application

ServesService

createServesService(deps: ServesServiceDeps): ServesService, with deps = { serves: ServesRepository }

Records a serve for every deal resolved by the public API, the anchor for telemetry and billing. No actor context: the resolve path is public. The best-effort policy belongs to the caller; repository failures propagate.

// Public resolve path: no ServiceContext, the deal may be anonymous.
export function mintServe(serves: ServesRepository, code: string) {
  const service = createServesService({ serves });
  return service.recordServe({
    sessionId: null, // SSR bootstrap: no client session yet
    code,
    boardId: null,
    ownerAccountId: null,
    diffusionDecidedAt: null,
    adsSponsorshipId: null,
    viewerAccountId: null,
    playerAccountId: null, // an ad_free player would pay the serve instead
  }); // => { id }: carried to the player as `serveId`
}

UsageStatsService

createUsageStatsService(deps: UsageStatsServiceDeps): UsageStatsService

Read-only view of the subject's current-period play activity and diffusions_per_period entitlement, for the usage tile. Not an enforcement path: quota debit happens at action time, never here. The read is about one grid of plans, the one the asking app sells: the period shown is the quota month of that grid's active subscription grant, else the UTC calendar month. quotaUsed and diffusionsLimit add up the counters and caps of every active grant whatever its grid, since the debit draws on all of them. The ad-served count uses the period's exact bounds; the play counts come from daily rollups, so a window opening mid-day counts that whole UTC day.

export async function usageTile(deps: UsageStatsServiceDeps, subjectId: string) {
  const stats = createUsageStatsService(deps);
  try {
    const usage = await stats.getForSubject(subjectId, "teachers");
    usage.servesCount; // rolled-up days + live count since the watermark
    usage.diffusionsLimit; // Number.POSITIVE_INFINITY when unlimited
    usage.ranking; // null until the daily job has placed the subject
    return usage;
  } catch (error) {
    if (isAppError(error)) {
      error.code; // => "PLAN_GRID_NOT_FOUND"
    }
    throw error;
  }
}

UsageAnalyticsService

createUsageAnalyticsService(deps: UsageAnalyticsServiceDeps): UsageAnalyticsService

Read-only detail view of the subject's authored deals over a rolling window: serves per UTC day and the most-served deals, each with its mean stars, its serves per student and its perceived difficulty. Same split as the usage stats: rollups up to the watermark, live telemetry after it, so the curve never shows a hole. The ranking is cut by the read over both spans at once, and the per-deal metrics are then read for its head alone, never for the whole catalogue. Perseverance is the exception: a distinct count of students cannot be summed across days, so it is read from the snapshot the nightly job precomputes at the three preset windows, fresh up to the last closed UTC day.

The view is a plan feature, usage_analytics: a subject without it is refused before anything of its activity is read. A session or a collection narrows the whole view to its deals and numbers them by their slot in it; a scope the subject does not own reads exactly like an unknown one.

export async function usageDetail(
  deps: UsageAnalyticsServiceDeps,
  subjectId: string,
  sessionId: string
) {
  const analytics = createUsageAnalyticsService(deps);
  try {
    const detail = await analytics.getForSubject(subjectId, {
      period: "last30",
      scope: { kind: "session", id: sessionId }, // only that session's deals, numbered by slot
    });
    detail.daily; // one zero-filled point per UTC day, today included
    detail.topDeals; // at most USAGE_ANALYTICS_TOP_DEALS, with meanStars, servesPerStudent, scopePosition
    detail.difficulty; // same deals, ungraded ones dropped
    return detail;
  } catch (error) {
    if (error instanceof FeatureDisabledError) {
      error.code; // => "FEATURE_DISABLED": the subject's plan lacks `usage_analytics`
    } else if (isAppError(error)) {
      error.code; // => "GROUP_SESSION_NOT_FOUND" (unknown, foreign or empty session)
    }
    throw error;
  }
}

Rollup boundary

Where a usage read stops summing daily rollups and starts counting raw telemetry. The cut is a watermark, not the calendar: the first UTC day of the window no execution ever covered. The last covered day would jump over a hole and a middle day the job missed would vanish from every figure; the first uncovered one hands that day and everything after it to the live count. Today is never covered, so the watermark is at most today, and a healthy job leaves the boundary exactly where the calendar cut used to be. Both sides slice time the same way (first_event_at for serves, received_at for events), so nothing is counted twice, and the live side has no upper bound: an outage widens it, it never drops a day.

export async function whereLiveStarts(coverage: PlayRollupRunsReadRepository) {
  const boundary = await resolveRollupBoundary(coverage, "2026-10-01", now);
  // Every closed day covered   => rolledUp: 2026-10-01 → 2026-10-08, liveSince: 2026-10-08T00:00Z
  // 2026-10-04 never computed  => rolledUp: 2026-10-01 → 2026-10-04, liveSince: 2026-10-04T00:00Z
  return boundary;
}

PlayRollupsService

createPlayRollupsService(deps: PlayRollupsServiceDeps): PlayRollupsService

Computes one UTC day of the daily usage rollups from serves and telemetry events, and replaces that day's rows atomically. Idempotent: re-running a day over the same source rows yields identical output. The perceived difficulty of a play is graded here by the domain rule and stored as a sum plus a count. Every execution leaves a trace, so a day with no activity never reads like a day the job never reached.

The nightly job (apps/api/src/worker/rollup-daily.ts) and the backfill-play-rollups command of apps/cli call the same rollupDay; the command passes "backfill" as the source. StoredPlayRollupRows is { rows: number; graded: number }; the service reads it through the stored dependency, a PlayRollupsReadRepository.

DEFAULT_ROLLUP_TOPICS is { rollupDaily: "telemetry.rollup-daily" }.

utcDayWindow("2026-10-07"); // => { start: 2026-10-07T00:00:00Z, end: 2026-10-08T00:00:00Z }
previousUtcDay(now); // => "2026-10-07"
lookbackDayRange(now, 3); // => { fromDay: "2026-10-05", toDayExclusive: "2026-10-08" }
uncoveredDays(
  { fromDay: "2026-10-05", toDayExclusive: "2026-10-09" },
  new Set(["2026-10-05", "2026-10-07"]),
  "2026-10-08"
); // => ["2026-10-06"]: today and later are never due

DEFAULT_ROLLUP_TOPICS.rollupDaily; // => "telemetry.rollup-daily"

export async function nightlyRollup(deps: PlayRollupsServiceDeps, lookbackDays: number) {
  const rollups = createPlayRollupsService(deps);
  const today = new Date();
  // Yesterday first, then any closed day a previous run never covered.
  await rollups.rollupDay(previousUtcDay(today), "cron"); // => { day, rows }
  for (const day of await rollups.findMissingDays(lookbackDayRange(today, lookbackDays), today)) {
    await rollups.rollupDay(day, "retry");
  }
}

UsagePerseveranceWindowsService

createUsagePerseveranceWindowsService(deps: UsagePerseveranceWindowsServiceDeps): UsagePerseveranceWindowsService

Precomputes distinct-student counts per owner, deal and window for the three presets. One atomic replacement per day, so readers never see a partial table. Coverage ends at the last closed UTC day: the current day is excluded, so a serve on today is never double-counted between two runs.

OwnerPeriodActivityService

createOwnerPeriodActivityService(deps: OwnerPeriodActivityServiceDeps): OwnerPeriodActivityService

Ranks every active owner by serves over the current period and replaces that period's standings. Ranking is a cross-account scan, so it runs once a day here and no read path performs it. Runs after the daily rollup and only over closed days, so a replay the same day converges on the same rows.

rankOwnersByServes([
  { ownerAccountId: "b", served: 10 },
  { ownerAccountId: "a", served: 10 },
  { ownerAccountId: "c", served: 4 },
  { ownerAccountId: "d", served: 0 },
]);
// => [ { a, served 10, rank 1, position 1 }, { b, served 10, rank 1, position 2 },
//      { c, served 4, rank 3, position 3 } ]: owners without a serve are not ranked

resolvePerseveranceWindows(now).last7;
// => { start: 2026-10-01T00:00:00Z, end: 2026-10-08T00:00:00Z }: ends at the last closed day

export async function nightlyJobs(
  activity: OwnerPeriodActivityServiceDeps,
  perseverance: UsagePerseveranceWindowsServiceDeps
) {
  const standings = createOwnerPeriodActivityService(activity);
  const windows = createUsagePerseveranceWindowsService(perseverance);
  const today = new Date();
  await standings.previewPeriodToDate(today); // => { range, owners }: writes nothing
  await standings.rankPeriodToDate(today); // => { periodStart, owners }
  await windows.recomputeAll(today); // => { throughDay, rows }
}

Ports

The ports split along the tables. The read model the job writes, the rollups, their execution trace and the perseverance snapshot, is read through canonical repositories; the serves are written through one. The jobs that build a snapshot from raw telemetry and the reads that assemble one result from several tables keep a bespoke surface, ratified in Bespoke by design.

ServesRepository: append-only, writeOne only.

PlayRollupsReadRepository: aggregate over the daily rollups, scoped by a PlayRollupCriteria.

export async function rolledUpCurve(
  rollups: PlayRollupsReadRepository,
  ownerAccountId: string,
  sessionCodes: string[] | undefined
) {
  const scope = PlayRollupCriteria.ofOwner(ownerAccountId, {
    fromDay: "2026-10-01",
    toDayExclusive: "2026-10-08",
  }).withCodes(sessionCodes); // undefined keeps every deal of the owner
  const daily = await rollups.aggregate(PlayRollupAggregations.servesByDay(scope));
  // => [{ day: "2026-10-02", served: 4 }, …]: oldest first, empty days absent
  const metrics = await rollups.aggregate(PlayRollupAggregations.metricsByCode(scope));
  // => [{ code, starsSum, resultsCount, difficultySum, gradedCount }, …]
  return { daily, metrics };
}

PlayRollupRunsReadRepository and PlayRollupRunsRepository: the trace of the rollup executions. A day with no succeeded execution was never computed, which is not a day computed and found empty. A succeeded execution is traced by replaceDay, in the transaction that replaces its day; writeOne traces a failed one, outside the transaction it rolled back.

UsagePerseveranceReadRepository: findMany over the precomputed perseverance snapshot. UsagePerseveranceQuery.empty().byOwner(id).inWindow(kind).withCodes(codes) with the UsagePerseveranceProjections.perDeal() projection returns UsageDealPerseverance[]; an empty code list matches nothing and costs no round trip. A deal absent from the snapshot has nothing to report.

PlayRollupsRepository: the nightly computation of a day, bespoke. Daily aggregates over serves and telemetry events, one row per (owner account, deal code, UTC day). A serve counts once it was displayed, never at resolve; every other counter counts plays, and replaying a deal counts again. Aggregates outlive their sources: no foreign keys, permanent retention.

PlayRollupKey is { ownerAccountId: string | null; code: string }; ServeDailyCount, PlayEventDailyCount, ResultStarsDailyCount and DifficultySample (the key plus a PerceivedDifficultyPlay) extend it. PlayRollupRunSource is "cron" | "retry" | "backfill"; PlayRollupRun is { source; durationMs } and FailedPlayRollupRun adds day and reason. UtcDayWindow is { start: Date; end: Date }, half-open.

PlayUsageReader: the reads of the usage views that span several tables, bespoke. Days the job covered come from the rollups; everything after the watermark is counted live from displayed serves and raw telemetry, on the same rule as the rollups. Reads that share a table, a key and a window are one method, not several.

UtcDayRange is { fromDay: string; toDayExclusive: string }, both YYYY-MM-DD. UsageDealCodes is string[] | undefined: the codes a read is restricted to, undefined reading every deal of the owner.

UsagePerseveranceWindowsRepository: the nightly computation of the perseverance snapshot, for the job alone, bespoke; the rows are read through UsagePerseveranceReadRepository.

OwnerPeriodActivityRepository: write side of the precomputed standings, one row per (owner, period), filled by the daily job, bespoke. The serves it ranks are read through PlayRollupsReadRepository, the active accounts through the accounts' aggregate.

Errors

utcDayWindow, lookbackDayRange and resolveRollupBoundary throw a plain Error on malformed day inputs. See Errors for the base classes.