@elytracms/studio 0.0.93 → 0.0.95

package/convex/analytics-cost.test.ts

@@ -0,0 +1,817 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { convexTest } from 'convex-test'
+import { internalMutationGeneric, makeFunctionReference } from 'convex/server'
+import type { GenericDatabaseWriter, MutationBuilder } from 'convex/server'
+import { getConvexSize, getDocumentSize, v } from 'convex/values'
+import type { Value } from 'convex/values'
+import { customCtx, customMutation } from 'convex-helpers/server/customFunctions'
+import { z } from 'zod'
+import { CONVEX_MAX_NESTING_DEPTH, measureMaxDepth } from '@elytracms/core/cms-core'
+import { createUuidIdFactory } from '@elytracms/core/determinism'
+import { INGEST_RECEIVER_PATH, signedIngestRequest } from '@elytracms/core/ingest'
+import type { IngestHandlerResult } from '@elytracms/core/ingest'
+import { defineRecordKind, redirectRecordKind, resolveRecordQuery } from '@elytracms/core/persistence'
+import schema from './schema'
+import type { DataModel, MutationCtx } from './functions'
+import { defineStudioHttp } from './http'
+import { ingestHandler, ingestHandlerArgs, parseIngestPayload } from './ingest'
+import type { IngestHandlers } from './ingest'
+import { findRecordDoc, queryRecordDocs, saveRecord } from './record-functions'
+import { triggers } from './triggers'
+
+/**
+ * EC-618 GATE 1 — what one pageview costs on Convex, MODELLED on convex-test against the
+ * engine's real receiver (`POST /elytra/ingest`, EC-617) and the real record store
+ * (`saveRecord` through the real `triggers.ts` write chokepoint, EC-616). No analytics code
+ * ships from here: the handlers below are TEST-ONLY models of the two storage designs the
+ * operator rules between — they are not the addon.
+ *
+ * - **(A) raw hit per pageview + a scheduled rollup** (the ruling's default): the handler
+ *   inserts one short-lived hit row; a batched rollup folds hits into daily per-document
+ *   rows and deletes them.
+ * - **(B) the receiver aggregates before writing** (the ruling's fallback): the handler
+ *   increments the day's per-document row in place.
+ *
+ * Both count uniques the one way the ruling allows ("a daily-rotating salted hash, never
+ * persisted"): the SITE turns the hash into HyperLogLog coordinates (`u: [bucket, rank]`)
+ * and only those travel; the day row carries a 1024-register sketch. The hash itself is
+ * never sent, never stored.
+ *
+ * What is MEASURED here (convex-test, Convex's own size formula `getDocumentSize` /
+ * `getConvexSize` from `convex/values` — "matches how Convex calculates document size for
+ * bandwidth tracking"): the function executions per hit (the receiver's `httpAction` + the
+ * `runMutation` it makes + any scheduled function), every document read and written per
+ * transaction INCLUDING the trigger wrapper's own reads (the meter sits below
+ * `triggers.wrapDB`), the stored rows' sizes and depth, and the contention shape. What is
+ * MODELLED: the index-entry bytes (key = indexed values + `_creationTime` + `_id`, inferred),
+ * that every `db.get`/document read is billed I/O (convex-test has no billing), and the
+ * prices (read below). The operator confirms the per-hit numbers on the dev deployment
+ * (`usage.database_io_*` / `database_write_index_rows` / `occ_info` in the function-execution
+ * log events) — EC-618 § Gate 1 has the commands.
+ */
+
+// --- Convex's published prices (read 2026-10-26) --------------------------------------------
+// https://www.convex.dev/pricing and https://docs.convex.dev/production/state/limits
+// ("Explicit client calls, scheduled executions, subscription updates, and file accesses count
+// as function calls"; Database I/O = "Document and index data transferred between Convex
+// functions and the underlying database"; storage "Includes database rows and indexes … Each
+// index is priced as another copy of the table"; query/mutation compute free on Serverless).
+// https://docs.convex.dev/functions/actions: runQuery/runMutation from an action — "you're
+// paying for multiple function calls".
+interface PlanPrices {
+  name: string
+  calls: { included: number; perMillion: number }
+  ioGB: { included: number; perGB: number }
+  storageGB: { included: number; perGB: number }
+  actionGBh: { included: number; perGBh: number }
+}
+const PLANS: PlanPrices[] = [
+  {
+    name: 'Starter',
+    calls: { included: 1_000_000, perMillion: 2.2 },
+    ioGB: { included: 1, perGB: 0.22 },
+    storageGB: { included: 0.5, perGB: 0.22 },
+    actionGBh: { included: 20, perGBh: 0.33 },
+  },
+  {
+    name: 'Professional',
+    calls: { included: 25_000_000, perMillion: 2 },
+    ioGB: { included: 50, perGB: 0.2 },
+    storageGB: { included: 50, perGB: 0.2 },
+    actionGBh: { included: 250, perGBh: 0.3 },
+  },
+]
+/** Convex runtime action memory (limits page: "Convex runtime: 64 MiB RAM"). */
+const ACTION_MEMORY_GB = 64 / 1024
+/** ASSUMED receiver wall time per hit (HMAC verify + one runMutation) — confirm on dev. */
+const ASSUMED_RECEIVER_MS = 50
+const GB = 1024 ** 3
+
+// --- The meter: every read and write of one transaction, below the trigger wrapper ----------
+
+type Doc = Record<string, Value | undefined> & { _id: string; _creationTime: number }
+
+interface TxMeter {
+  label: string
+  /** `db.get` + `db.query(…)` terminal calls — Convex's "index ranges read". */
+  ranges: number
+  readDocs: number
+  readBytes: number
+  readIds: string[]
+  writeDocs: number
+  writeBytes: number
+  /** MODELLED: index entries added, removed or changed by this transaction's writes. */
+  indexRows: number
+  indexBytes: number
+}
+
+const ledger: TxMeter[] = []
+
+type TableName = keyof typeof schema.tables & string
+const TABLES = Object.keys(schema.tables) as TableName[]
+
+/** Each index's key fields — the schema's own declaration, plus the two system indexes. */
+function indexKeys(table: TableName): string[][] {
+  // Convex appends `_creationTime` (then `_id`) to every index key (inferred from the docs).
+  const declared = schema.tables[table][' indexes']().map((index) => [...index.fields, '_creationTime'])
+  return [...declared, [] /* by_id */, ['_creationTime'] /* by_creation_time */]
+}
+
+function entryBytes(doc: Doc, fields: string[]): number {
+  return fields.reduce((sum, field) => sum + (doc[field] === undefined ? 1 : getConvexSize(doc[field])), 0) + getConvexSize(doc._id)
+}
+
+function entryKey(doc: Doc, fields: string[]): string {
+  return JSON.stringify([...fields.map((field) => doc[field] ?? null), doc._id])
+}
+
+interface RawDb {
+  get(...args: unknown[]): Promise<Doc | null>
+  query(table: string): object
+  insert(table: string, value: unknown): Promise<string>
+  patch(...args: unknown[]): Promise<void>
+  replace(...args: unknown[]): Promise<void>
+  delete(...args: unknown[]): Promise<void>
+  normalizeId(table: string, id: string): string | null
+}
+
+function meter(db: GenericDatabaseWriter<DataModel>, label: string): GenericDatabaseWriter<DataModel> {
+  const tx: TxMeter = {
+    label,
+    ranges: 0,
+    readDocs: 0,
+    readBytes: 0,
+    readIds: [],
+    writeDocs: 0,
+    writeBytes: 0,
+    indexRows: 0,
+    indexBytes: 0,
+  }
+  ledger.push(tx)
+  const raw = db as unknown as RawDb
+  const read = (doc: Doc | null): void => {
+    if (!doc) return
+    tx.readDocs += 1
+    tx.readBytes += getDocumentSize(doc as Record<string, Value>)
+    tx.readIds.push(doc._id)
+  }
+  const wrote = (table: TableName, before: Doc | null, after: Doc | null): void => {
+    if (after) {
+      tx.writeDocs += 1
+      tx.writeBytes += getDocumentSize(after as Record<string, Value>)
+    }
+    for (const fields of indexKeys(table)) {
+      const changed = !before || !after || entryKey(before, fields) !== entryKey(after, fields)
+      if (!changed) continue
+      tx.indexRows += 1
+      tx.indexBytes += entryBytes((after ?? before)!, fields)
+    }
+  }
+  const tableOf = (id: string): TableName => TABLES.find((table) => raw.normalizeId(table, id) !== null)!
+  /** `(table, id, …rest)` or `(id, …rest)` — the two call forms Convex accepts. */
+  const split = (args: unknown[], arity: number): { table: TableName; id: string } =>
+    args.length === arity + 1
+      ? { table: args[0] as TableName, id: args[1] as string }
+      : { table: tableOf(args[0] as string), id: args[0] as string }
+  const meterQuery = (query: object): object =>
+    new Proxy(query, {
+      get(target, prop) {
+        const value: unknown = Reflect.get(target, prop, target)
+        if (typeof value !== 'function') return value
+        const fn = value as (...args: unknown[]) => unknown
+        if (prop === 'first' || prop === 'unique') {
+          return async (...args: unknown[]) => {
+            tx.ranges += 1
+            const doc = (await fn.apply(target, args)) as Doc | null
+            read(doc)
+            return doc
+          }
+        }
+        if (prop === 'collect' || prop === 'take') {
+          return async (...args: unknown[]) => {
+            tx.ranges += 1
+            const docs = (await fn.apply(target, args)) as Doc[]
+            docs.forEach(read)
+            return docs
+          }
+        }
+        return (...args: unknown[]) => {
+          const out = fn.apply(target, args)
+          return out !== null && typeof out === 'object' && !(out instanceof Promise) ? meterQuery(out) : out
+        }
+      },
+    })
+  const metered = {
+    async get(...args: unknown[]) {
+      tx.ranges += 1
+      const doc = await raw.get(...args)
+      read(doc)
+      return doc
+    },
+    query(table: string) {
+      return meterQuery(raw.query(table))
+    },
+    async insert(table: TableName, value: unknown) {
+      const id = await raw.insert(table, value)
+      wrote(table, null, await raw.get(id))
+      return id
+    },
+    async patch(...args: unknown[]) {
+      const { table, id } = split(args, 2)
+      const before = await raw.get(id)
+      await raw.patch(...args)
+      wrote(table, before, await raw.get(id))
+    },
+    async replace(...args: unknown[]) {
+      const { table, id } = split(args, 2)
+      const before = await raw.get(id)
+      await raw.replace(...args)
+      wrote(table, before, await raw.get(id))
+    },
+    async delete(...args: unknown[]) {
+      const { table, id } = split(args, 1)
+      const before = await raw.get(id)
+      await raw.delete(...args)
+      wrote(table, before, null)
+    },
+    normalizeId: (table: string, id: string) => raw.normalizeId(table, id),
+    system: (db as unknown as { system: unknown }).system,
+  }
+  return metered as unknown as GenericDatabaseWriter<DataModel>
+}
+
+/** An internal-mutation builder whose db is metered BELOW the real trigger wrapper. */
+function metered(label: string, withTriggers = true) {
+  return customMutation(
+    internalMutationGeneric as MutationBuilder<DataModel, 'internal'>,
+    customCtx((ctx: MutationCtx) => {
+      const db = meter(ctx.db, label)
+      return { db: withTriggers ? triggers.wrapDB({ ...ctx, db }).db : db }
+    }),
+  )
+}
+
+// --- The two storage designs (TEST-ONLY models, not the addon) ------------------------------
+
+const MODEL_MODULE = 'analyticsCostModel'
+
+/** The beacon's pageview as the site route would forward it (`event.data`). */
+const pageviewSchema = z.strictObject({
+  name: z.literal('pageview'),
+  collection: z.string(),
+  path: z.string(),
+  locale: z.string(),
+  status: z.number().int(),
+  country: z.string().optional(),
+  referrer: z.string().optional(),
+  /** HyperLogLog coordinates of the day's salted visitor hash — the hash never leaves the site. */
+  u: z.tuple([z.number().int(), z.number().int()]),
+})
+type PageviewData = z.infer<typeof pageviewSchema>
+
+/** (A) one short-lived row per pageview. */
+const hitKind = defineRecordKind({
+  kind: 'analyticsHitModel',
+  module: MODEL_MODULE,
+  time: 'receivedAt',
+  fields: {
+    collection: z.string(),
+    documentId: z.string(),
+    path: z.string(),
+    locale: z.string(),
+    status: z.number().int(),
+    country: z.string().optional(),
+    referrer: z.string().optional(),
+    bucket: z.number().int(),
+    rank: z.number().int(),
+    receivedAt: z.string(),
+  },
+})
+
+/** The daily per-document aggregate — the same row in both designs. */
+const dayKind = defineRecordKind({
+  kind: 'analyticsDayModel',
+  module: MODEL_MODULE,
+  keys: ['day', 'documentId'],
+  time: 'day',
+  fields: {
+    day: z.string(),
+    collection: z.string(),
+    documentId: z.string(),
+    views: z.number().int(),
+    countries: z.record(z.string(), z.number()),
+    referrers: z.record(z.string(), z.number()),
+    sketch: z.string(),
+  },
+})
+type DayColumns = {
+  day: string
+  collection: string
+  documentId: string
+  views: number
+  countries: Record<string, number>
+  referrers: Record<string, number>
+  sketch: string
+}
+
+const SKETCH_REGISTERS = 1024
+const SKETCH_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_'
+const EMPTY_SKETCH = '0'.repeat(SKETCH_REGISTERS)
+
+function raise(sketch: string, bucket: number, rank: number): string {
+  const current = SKETCH_ALPHABET.indexOf(sketch[bucket]!)
+  return rank > current ? sketch.slice(0, bucket) + SKETCH_ALPHABET[rank]! + sketch.slice(bucket + 1) : sketch
+}
+
+/** The HyperLogLog estimate (with the small-range linear-counting correction). */
+function estimateUniques(sketch: string): number {
+  let sum = 0
+  let zeros = 0
+  for (const char of sketch) {
+    const register = SKETCH_ALPHABET.indexOf(char)
+    sum += 2 ** -register
+    if (register === 0) zeros += 1
+  }
+  const m = SKETCH_REGISTERS
+  const raw = ((0.7213 / (1 + 1.079 / m)) * m * m) / sum
+  return raw <= 2.5 * m && zeros > 0 ? m * Math.log(m / zeros) : raw
+}
+
+function bump(map: Record<string, number>, key: string): Record<string, number> {
+  return { ...map, [key]: (map[key] ?? 0) + 1 }
+}
+
+interface Pageview extends Omit<PageviewData, 'name' | 'u'> {
+  documentId: string
+  bucket: number
+  rank: number
+}
+
+function foldPageview(previous: DayColumns | undefined, pageview: Pageview, day: string): DayColumns {
+  const base: DayColumns = previous ?? {
+    day,
+    collection: pageview.collection,
+    documentId: pageview.documentId,
+    views: 0,
+    countries: {},
+    referrers: {},
+    sketch: EMPTY_SKETCH,
+  }
+  return {
+    ...base,
+    views: base.views + 1,
+    countries: bump(base.countries, pageview.country ?? '??'),
+    referrers: bump(base.referrers, pageview.referrer ?? '(direct)'),
+    sketch: raise(base.sketch, pageview.bucket, pageview.rank),
+  }
+}
+
+function pageviewOf(payload: unknown): Pageview | undefined {
+  const event = parseIngestPayload(payload)
+  if (event.kind !== 'event' || !event.target) return undefined
+  const data = pageviewSchema.parse(event.data)
+  const { name: _name, u, ...rest } = data
+  return { ...rest, documentId: event.target, bucket: u[0], rank: u[1] }
+}
+
+const dayId = (day: string, documentId: string) => `${day}|${documentId}`
+// Deterministic bytes for the one production id factory (EC-578) — same length, same shape.
+let idSeed = 1
+const newHitId = createUuidIdFactory((bytes) => {
+  for (let i = 0; i < bytes.length; i += 1) bytes[i] = (idSeed * 131 + i * 17) & 0xff
+  idSeed += 1
+})
+
+async function writeHitA(ctx: MutationCtx, payload: unknown, receivedAt: string): Promise<IngestHandlerResult> {
+  const pageview = pageviewOf(payload)
+  if (!pageview) return { ok: false, status: 422, message: 'Pageview events only.' }
+  const { bucket, rank, ...columns } = pageview
+  const id = `hit_${newHitId()}`
+  await saveRecord(ctx, hitKind, id, { ...columns, bucket, rank, receivedAt }, { createdAt: receivedAt, updatedAt: receivedAt })
+  return { ok: true, id }
+}
+
+async function upsertDay(ctx: MutationCtx, day: string, pageviews: readonly Pageview[], at: string): Promise<void> {
+  const id = dayId(day, pageviews[0]!.documentId)
+  const existing = await findRecordDoc(ctx, dayKind, id)
+  const folded = pageviews.reduce<DayColumns | undefined>(
+    (row, pageview) => foldPageview(row, pageview, day),
+    existing?.data as DayColumns | undefined,
+  )!
+  const write = existing
+    ? { views: folded.views, countries: folded.countries, referrers: folded.referrers, sketch: folded.sketch }
+    : folded
+  await saveRecord(ctx, dayKind, id, write, { createdAt: at, updatedAt: at })
+}
+
+const modelModule = {
+  /** (A) the receiver's handler: one insert. */
+  hitA: metered('A:hit')({
+    args: ingestHandlerArgs,
+    handler: (ctx, args): Promise<IngestHandlerResult> => writeHitA(ctx, args.payload, args.receivedAt),
+  }),
+  /** CONTROL for the meter: the same write with NO trigger wrapper. */
+  hitABare: metered('A:hit:no-triggers', false)({
+    args: ingestHandlerArgs,
+    handler: (ctx, args): Promise<IngestHandlerResult> => writeHitA(ctx, args.payload, args.receivedAt),
+  }),
+  /** (A) one rollup batch: fold up to `limit` hits before `before` into day rows, delete them. */
+  rollupA: metered('A:rollup')({
+    args: { before: v.string(), limit: v.number(), at: v.string() },
+    handler: async (ctx, { before, limit, at }) => {
+      const hits = await queryRecordDocs(ctx, hitKind, resolveRecordQuery(hitKind, { before, limit, order: 'asc' }))
+      const groups = new Map<string, { day: string; pageviews: Pageview[] }>()
+      for (const hit of hits) {
+        const columns = hit.data as unknown as Pageview & { receivedAt: string }
+        const day = columns.receivedAt.slice(0, 10)
+        const key = dayId(day, columns.documentId)
+        const group = groups.get(key) ?? { day, pageviews: [] }
+        group.pageviews.push(columns)
+        groups.set(key, group)
+      }
+      for (const { day, pageviews } of groups.values()) await upsertDay(ctx, day, pageviews, at)
+      for (const hit of hits) await ctx.db.delete(hit._id)
+      return { processed: hits.length }
+    },
+  }),
+  /** (B) the receiver's handler: read-modify-write of the day row. */
+  hitB: metered('B:hit')({
+    args: ingestHandlerArgs,
+    handler: async (ctx, args): Promise<IngestHandlerResult> => {
+      const pageview = pageviewOf(args.payload)
+      if (!pageview) return { ok: false, status: 422, message: 'Pageview events only.' }
+      await upsertDay(ctx, args.receivedAt.slice(0, 10), [pageview], args.receivedAt)
+      return { ok: true }
+    },
+  }),
+  /** CONTROL for the scheduled-work counter: a redirect write DOES schedule (EC-510). */
+  redirectControl: metered('control:redirect')({
+    args: {},
+    handler: async (ctx) => {
+      const at = '2026-10-26T12:00:00.000Z'
+      await saveRecord(ctx, redirectRecordKind, 'redirect_ec618', { from: '/old', to: '/new' }, { createdAt: at, updatedAt: at })
+    },
+  }),
+}
+
+const hitA = ingestHandler(`${MODEL_MODULE}:hitA`)
+const hitABare = ingestHandler(`${MODEL_MODULE}:hitABare`)
+const hitB = ingestHandler(`${MODEL_MODULE}:hitB`)
+const rollupA = makeFunctionReference<'mutation', { before: string; limit: number; at: string }, { processed: number }>(
+  `${MODEL_MODULE}:rollupA`,
+)
+const redirectControl = makeFunctionReference<'mutation'>(`${MODEL_MODULE}:redirectControl`)
+
+// --- Deterministic traffic (an SMB day: few pages, a long tail, mostly one country) ---------
+
+function mulberry32(seed: number): () => number {
+  let state = seed
+  return () => {
+    state = (state + 0x6d2b79f5) | 0
+    let t = Math.imul(state ^ (state >>> 15), 1 | state)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function pick<T>(random: () => number, weighted: readonly (readonly [T, number])[]): T {
+  const total = weighted.reduce((sum, [, weight]) => sum + weight, 0)
+  let roll = random() * total
+  for (const [value, weight] of weighted) {
+    roll -= weight
+    if (roll < 0) return value
+  }
+  return weighted[weighted.length - 1]![0]
+}
+
+const SLUGS = [
+  'sommerfest-im-garten-der-konditorei',
+  'unsere-torten-fuer-hochzeiten',
+  'ueber-uns',
+  'kontakt-und-anfahrt',
+  'saisonale-spezialitaeten-im-herbst',
+  'rezept-apfelstrudel-wie-bei-oma',
+  'oeffnungszeiten-an-feiertagen',
+  'catering-fuer-firmenfeiern',
+  'neue-filiale-in-der-altstadt',
+  'impressum',
+]
+const DOCUMENTS = SLUGS.map((slug, index) => ({
+  collection: index % 3 === 0 ? 'post' : 'page',
+  documentId: createUuidIdFactory((bytes) => bytes.fill(index + 1))(),
+  slug,
+}))
+const COUNTRIES = [['DE', 70], ['AT', 10], ['CH', 8], ['US', 5], ['NL', 3], ['FR', 2], ['GB', 1], ['IT', 1]] as const
+const REFERRERS = [
+  [undefined, 45],
+  ['www.google.com', 30],
+  ['www.instagram.com', 8],
+  ['l.facebook.com', 5],
+  ['duckduckgo.com', 3],
+  ['www.bing.com', 3],
+  ['www.ecosia.org', 2],
+  ['www.tripadvisor.de', 2],
+  ['maps.google.com', 2],
+] as const
+const VISITORS = 150
+
+/** `count` pageviews of one day; `onlyDocument` pins them all to one page (the hot row). */
+function traffic(count: number, seed: number, onlyDocument?: number): Pageview[] {
+  const random = mulberry32(seed)
+  const docWeights = DOCUMENTS.map((doc, index) => [index, 1 / (index + 1)] as const)
+  return Array.from({ length: count }, () => {
+    const doc = DOCUMENTS[onlyDocument ?? pick(random, docWeights)]!
+    const visitor = Math.floor(random() ** 1.5 * VISITORS)
+    // The visitor's daily hash → HLL coordinates (a good hash's distribution, per visitor).
+    const coords = mulberry32(10_000 + visitor)
+    const bucket = Math.floor(coords() * SKETCH_REGISTERS)
+    let rank = 1
+    while (rank < 54 && coords() < 0.5) rank += 1
+    const locale = random() < 0.8 ? 'de' : 'en'
+    const country = pick(random, COUNTRIES)
+    const referrer = pick(random, REFERRERS)
+    return {
+      collection: doc.collection,
+      documentId: doc.documentId,
+      path: `/${locale}/${doc.collection === 'post' ? 'blog/' : ''}${doc.slug}`,
+      locale,
+      status: 200,
+      country,
+      ...(referrer ? { referrer } : {}),
+      bucket,
+      rank,
+    }
+  })
+}
+
+// --- The deployment: configured exactly like a consumer (ingest secret + revalidation) -------
+
+const SECRET = 'ec618-cost-secret'
+const silentAuth = { addHttpRoutes: () => {} }
+function env(): Record<string, string | undefined> {
+  return (globalThis as { process: { env: Record<string, string | undefined> } }).process.env
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date('2026-10-26T12:00:00.000Z'))
+  ledger.length = 0
+  env()['ELYTRA_INGEST_SECRET'] = SECRET
+  // A revalidation-configured deployment: a trigger that WOULD schedule work does (the control).
+  env()['CANVAS_REVALIDATE_ENDPOINT'] = 'https://host.invalid/api/revalidate'
+  env()['CANVAS_REVALIDATE_SECRET'] = 'ec618-revalidate-secret'
+})
+afterEach(() => {
+  vi.useRealTimers()
+  for (const key of ['ELYTRA_INGEST_SECRET', 'CANVAS_REVALIDATE_ENDPOINT', 'CANVAS_REVALIDATE_SECRET']) delete env()[key]
+})
+
+function backend(ingest: IngestHandlers) {
+  return convexTest(schema, {
+    ...import.meta.glob(['./**/*.ts', '!./**/*.test.ts', '!./_generated/**']),
+    './_generated/api.ts': async () => ({}),
+    [`./${MODEL_MODULE}.ts`]: async () => modelModule,
+    './http.ts': async () => ({ default: defineStudioHttp({ auth: silentAuth, ingest }) }),
+  })
+}
+type Backend = ReturnType<typeof backend>
+
+function eventPayload(pageview: Pageview) {
+  const { documentId, bucket, rank, ...rest } = pageview
+  return { kind: 'event' as const, target: documentId, data: { name: 'pageview', ...rest, u: [bucket, rank] } }
+}
+
+/** One beacon through the receiver; returns the response and the signed body's bytes. */
+async function sendPageview(t: Backend, pageview: Pageview): Promise<{ status: number; bodyBytes: number }> {
+  const signed = await signedIngestRequest(eventPayload(pageview), SECRET)
+  const response = await t.fetch(INGEST_RECEIVER_PATH, { method: 'POST', headers: signed.headers, body: signed.body })
+  return { status: response.status, bodyBytes: new TextEncoder().encode(signed.body).byteLength }
+}
+
+async function scheduledCount(t: Backend): Promise<number> {
+  return t.run(async (ctx) => (await ctx.db.system.query('_scheduled_functions').collect()).length)
+}
+
+async function recordsOf(t: Backend, kind: string): Promise<Doc[]> {
+  return t.run(async (ctx) => (await ctx.db.query('records').collect()).filter((row) => row.kind === kind) as unknown as Doc[])
+}
+
+function sum(txs: readonly TxMeter[], field: 'ranges' | 'readDocs' | 'readBytes' | 'writeDocs' | 'writeBytes' | 'indexRows' | 'indexBytes') {
+  return txs.reduce((total, tx) => total + tx[field], 0)
+}
+
+const txs = (label: string) => ledger.filter((tx) => tx.label === label)
+
+// --- The tests ------------------------------------------------------------------------------
+
+describe('EC-618 gate 1 — function calls per pageview', () => {
+  it('either design: the receiver httpAction + ONE runMutation, and no scheduled work on a configured deployment', async () => {
+    const [pageview] = traffic(1, 7)
+    for (const [label, handler] of [['A:hit', hitA], ['B:hit', hitB]] as const) {
+      ledger.length = 0
+      const t = backend({ event: handler })
+      const sent = await sendPageview(t, pageview!)
+      expect(sent.status).toBe(200)
+      // The ledger holds one entry per metered mutation EXECUTION: the receiver ran one.
+      expect(ledger.map((tx) => tx.label)).toEqual([label])
+      expect(await scheduledCount(t)).toBe(0)
+
+      // CONTROL (the scheduled counter can see trigger-scheduled work): a redirect write on
+      // the same configured deployment schedules exactly one revalidation (EC-510).
+      await t.mutation(redirectControl, {})
+      expect(await scheduledCount(t)).toBe(1)
+    }
+
+    // CONTROL (the ledger can see "no execution"): with no `event` handler the receiver refuses
+    // the beacon (EC-617's 422) and runs no mutation; an unsigned beacon is refused before that.
+    ledger.length = 0
+    const closed = backend({})
+    expect((await sendPageview(closed, pageview!)).status).toBe(422)
+    const unsigned = await closed.fetch(INGEST_RECEIVER_PATH, { method: 'POST', body: JSON.stringify(eventPayload(pageview!)) })
+    expect(unsigned.status).toBe(401)
+    expect(ledger).toEqual([])
+  })
+})
+
+describe('EC-618 gate 1 — bytes per pageview, the trigger work, the rollup', () => {
+  it('measures (A) raw hit + batched rollup against (B) aggregate-before-write over the same day of traffic', { timeout: 120_000 }, async () => {
+    const N = 240
+    const ROLLUP_LIMIT = 100
+    const day = traffic(N, 42)
+
+    // ---- (A) raw hits, then the rollup ----
+    ledger.length = 0
+    const a = backend({ event: hitA })
+    let bodyBytes = 0
+    for (const pageview of day) {
+      const sent = await sendPageview(a, pageview)
+      expect(sent.status).toBe(200)
+      bodyBytes += sent.bodyBytes
+    }
+    const hitTxs = txs('A:hit')
+    expect(hitTxs).toHaveLength(N)
+    const hitRows = await recordsOf(a, hitKind.kind)
+    expect(hitRows).toHaveLength(N)
+    const hitRowBytes = hitRows.reduce((total, row) => total + getDocumentSize(row as Record<string, Value>), 0) / N
+    // Every hit transaction: one empty range (saveRecord's lookup of its fresh id), one insert,
+    // and ONE document read — the trigger wrapper's `get` of the new row (convex-helpers).
+    for (const tx of hitTxs) {
+      expect(tx).toMatchObject({ ranges: 2, readDocs: 1, writeDocs: 1, indexRows: indexKeys('records').length })
+    }
+    expect(await scheduledCount(a)).toBe(0)
+    const depthA = Math.max(...hitRows.map((row) => measureMaxDepth(row).depth))
+    expect(depthA).toBeLessThanOrEqual(CONVEX_MAX_NESTING_DEPTH)
+    // The hash never reaches storage: the row holds the HLL coordinates, no visitor column.
+    expect(Object.keys(hitRows[0]!['data'] as object).sort()).toEqual(
+      ['bucket', 'collection', 'country', 'documentId', 'locale', 'path', 'rank', 'receivedAt', 'status', ...(hitRows[0]!['data'] as { referrer?: string }).referrer ? ['referrer'] : []].sort(),
+    )
+
+    // CONTROL (the meter sees the trigger's work): the same write with NO trigger wrapper reads
+    // no document — so the one read above is the write chokepoint's, measured, not assumed.
+    ledger.length = 0
+    const bare = backend({ event: hitABare })
+    expect((await sendPageview(bare, day[0]!)).status).toBe(200)
+    expect(txs('A:hit:no-triggers')[0]).toMatchObject({ ranges: 1, readDocs: 0, writeDocs: 1 })
+
+    // The rollup: batches until a short batch says the period is drained.
+    ledger.length = 0
+    const before = '2026-10-27T00:00:00.000Z'
+    let batches = 0
+    for (;;) {
+      batches += 1
+      const { processed } = await a.mutation(rollupA, { before, limit: ROLLUP_LIMIT, at: before })
+      if (processed < ROLLUP_LIMIT) break
+    }
+    expect(batches).toBe(Math.floor(N / ROLLUP_LIMIT) + 1)
+    expect(await recordsOf(a, hitKind.kind)).toHaveLength(0)
+    const dayRowsA = await recordsOf(a, dayKind.kind)
+    const viewsA = dayRowsA.reduce((total, row) => total + (row['data'] as DayColumns).views, 0)
+    expect(viewsA).toBe(N)
+    const rollupTxs = txs('A:rollup')
+
+    // ---- (B) aggregate before writing ----
+    ledger.length = 0
+    const b = backend({ event: hitB })
+    for (const pageview of day) expect((await sendPageview(b, pageview)).status).toBe(200)
+    const hitBTxs = txs('B:hit')
+    expect(hitBTxs).toHaveLength(N)
+    expect(await scheduledCount(b)).toBe(0)
+    const dayRowsB = await recordsOf(b, dayKind.kind)
+    expect(dayRowsB.reduce((total, row) => total + (row['data'] as DayColumns).views, 0)).toBe(N)
+    // The same aggregates either way (A folds in batches, B per hit — the sketch merge is exact).
+    const byId = (rows: Doc[]) => Object.fromEntries(rows.map((row) => [row['recordId'] as string, row['data']]))
+    expect(byId(dayRowsB)).toEqual(byId(dayRowsA))
+    // An update of the day row: two lookups (the handler's, saveRecord's), the trigger's
+    // `get` before and after the patch, ONE document written, and no index entry changed.
+    // (A create reads one document too — the trigger's `get` of the row it just inserted.)
+    const creates = hitBTxs.filter((tx) => tx.indexRows > 0)
+    for (const tx of creates) expect(tx).toMatchObject({ ranges: 3, readDocs: 1, writeDocs: 1, indexRows: indexKeys('records').length })
+    const updates = hitBTxs.filter((tx) => tx.indexRows === 0)
+    expect(creates).toHaveLength(dayRowsB.length)
+    expect(updates).toHaveLength(N - dayRowsB.length)
+    for (const tx of updates) expect(tx).toMatchObject({ ranges: 4, readDocs: 4, writeDocs: 1, indexRows: 0 })
+    const depthB = Math.max(...dayRowsB.map((row) => measureMaxDepth(row).depth))
+    expect(depthB).toBeLessThanOrEqual(CONVEX_MAX_NESTING_DEPTH)
+    const dayRowBytes = Math.max(...dayRowsB.map((row) => getDocumentSize(row as Record<string, Value>)))
+    const distinct = new Set(day.map((pageview) => `${pageview.documentId}|${pageview.bucket}|${pageview.rank}`)).size
+    const estimated = dayRowsB.reduce((total, row) => total + estimateUniques((row['data'] as DayColumns).sketch), 0)
+
+    // ---- per hit ----
+    const perHit = (list: readonly TxMeter[], over = N) => ({
+      ranges: sum(list, 'ranges') / over,
+      readBytes: sum(list, 'readBytes') / over,
+      writeBytes: sum(list, 'writeBytes') / over,
+      indexRows: sum(list, 'indexRows') / over,
+      indexBytes: sum(list, 'indexBytes') / over,
+    })
+    const aHit = perHit(hitTxs)
+    const aRollup = perHit(rollupTxs)
+    const bHit = perHit(hitBTxs)
+    const io = (m: ReturnType<typeof perHit>) => m.readBytes + m.writeBytes + m.indexBytes
+    const ioA = io(aHit) + io(aRollup)
+    const ioB = io(bHit)
+    const userIndexes = schema.tables.records[' indexes']().length
+
+    const designs = [
+      {
+        name: 'A raw hit + rollup',
+        // 2 per hit + one rollup call per batch (+ one trigger call per period: daily cron or self-schedule)
+        calls: (pageviews: number) => 2 * pageviews + Math.ceil(pageviews / ROLLUP_LIMIT) + 30,
+        ioBytes: ioA,
+        // standing raw rows for a one-day rollup window, each priced as (1 + indexes) copies
+        storageBytes: (pageviews: number) => (pageviews / 30) * hitRowBytes * (1 + userIndexes),
+      },
+      { name: 'B aggregate before write', calls: (pageviews: number) => 2 * pageviews, ioBytes: ioB, storageBytes: () => 0 },
+    ]
+    const volumes = [10_000, 100_000, 1_000_000, 10_000_000]
+    const costLines: string[] = []
+    for (const plan of PLANS) {
+      for (const design of designs) {
+        const cells = volumes.map((pageviews) => {
+          const calls = design.calls(pageviews)
+          const ioGB = (pageviews * design.ioBytes) / GB
+          const storageGB = design.storageBytes(pageviews) / GB
+          const actionGBh = pageviews * ACTION_MEMORY_GB * (ASSUMED_RECEIVER_MS / 3_600_000)
+          const marginal =
+            (calls / 1e6) * plan.calls.perMillion + ioGB * plan.ioGB.perGB + storageGB * plan.storageGB.perGB + actionGBh * plan.actionGBh.perGBh
+          const standalone =
+            (Math.max(0, calls - plan.calls.included) / 1e6) * plan.calls.perMillion +
+            Math.max(0, ioGB - plan.ioGB.included) * plan.ioGB.perGB +
+            Math.max(0, storageGB - plan.storageGB.included) * plan.storageGB.perGB +
+            Math.max(0, actionGBh - plan.actionGBh.included) * plan.actionGBh.perGBh
+          return `$${standalone.toFixed(2)} / $${marginal.toFixed(2)}`
+        })
+        costLines.push(`${plan.name.padEnd(12)} ${design.name.padEnd(26)} ${cells.map((cell) => cell.padEnd(20)).join('')}`)
+      }
+    }
+
+    const round = (value: number) => Math.round(value)
+    console.info(
+      [
+        `[analytics-cost] ${N} pageviews, ${DOCUMENTS.length} documents, 1 day — MODELLED (convex-test + Convex's size formula)`,
+        `  signed beacon body: ${round(bodyBytes / N)} B/hit · hit row ${round(hitRowBytes)} B · day row ≤ ${dayRowBytes} B · depth A ${depthA} / B ${depthB} (≤ ${CONVEX_MAX_NESTING_DEPTH})`,
+        `  records indexes: ${userIndexes} declared + 2 system → ${indexKeys('records').length} index rows per insert`,
+        `  A hit    : ranges ${aHit.ranges} · read ${round(aHit.readBytes)} B · write ${round(aHit.writeBytes)} B · index rows ${aHit.indexRows} (${round(aHit.indexBytes)} B)`,
+        `  A rollup : ${batches} batches of ≤ ${ROLLUP_LIMIT} · per hit: ranges ${aRollup.ranges.toFixed(2)} · read ${round(aRollup.readBytes)} B · write ${round(aRollup.writeBytes)} B · index rows ${aRollup.indexRows.toFixed(2)} (${round(aRollup.indexBytes)} B)`,
+        `  B hit    : ranges ${bHit.ranges.toFixed(2)} · read ${round(bHit.readBytes)} B · write ${round(bHit.writeBytes)} B · index rows ${bHit.indexRows.toFixed(2)} (${round(bHit.indexBytes)} B)`,
+        `  I/O per hit: A ${round(ioA)} B · B ${round(ioB)} B (B at the largest day row: ${round(4 * dayRowBytes + dayRowBytes)} B)`,
+        `  uniques: ${distinct} distinct (document, visitor) pairs · sketch estimate ${estimated.toFixed(1)}`,
+        `  monthly $ (standalone vs included quota / marginal), pageviews ${volumes.map((volume) => String(volume).padEnd(20)).join('')}`,
+        ...costLines.map((line) => `  ${line}`),
+      ].join('\n'),
+    )
+  })
+})
+
+describe('EC-618 gate 1 — the contention shape (N concurrent hits on one page)', () => {
+  it('A writes N disjoint rows (no shared read); B serialises every hit on ONE row', { timeout: 60_000 }, async () => {
+    const K = 40
+    const burst = traffic(K, 99, 0)
+
+    ledger.length = 0
+    const a = backend({ event: hitA })
+    const sentA = await Promise.all(burst.map((pageview) => sendPageview(a, pageview)))
+    expect(sentA.every((sent) => sent.status === 200)).toBe(true)
+    expect(await recordsOf(a, hitKind.kind)).toHaveLength(K)
+    // No document is read by two hit transactions: under OCC nothing can conflict.
+    const readsA = txs('A:hit').flatMap((tx) => tx.readIds)
+    expect(new Set(readsA).size).toBe(readsA.length)
+
+    ledger.length = 0
+    const b = backend({ event: hitB })
+    const sentB = await Promise.all(burst.map((pageview) => sendPageview(b, pageview)))
+    expect(sentB.every((sent) => sent.status === 200)).toBe(true)
+    const [row] = await recordsOf(b, dayKind.kind)
+    // convex-test SERIALISES mutations, so this proves the merge (no lost update), not Convex's
+    // OCC retry; the shape is what matters: every hit after the first read AND wrote one row.
+    expect((row!['data'] as DayColumns).views).toBe(K)
+    // Every transaction reads the row (the first: the trigger's read of its own insert);
+    // K − 1 of them read it BEFORE writing it — the read-modify-write OCC retries.
+    const readers = txs('B:hit').filter((tx) => tx.readIds.includes(row!._id))
+    expect(readers).toHaveLength(K)
+    expect(readers.filter((tx) => tx.indexRows === 0)).toHaveLength(K - 1)
+    console.info(
+      `[analytics-cost] contention: ${K} concurrent hits on one page — A: ${K} rows, 0 shared reads · B: 1 row read+written by ${readers.length} transactions`,
+    )
+  })
+})