@rocapine/rocalytics-sdk 0.0.0-stage → 0.3.0

package/docs/onboarding-run.examples.ts

@@ -0,0 +1,306 @@
+// Onboarding run contract, schema_version 1: the example runs.
+//
+// Every payload shown in onboarding-run-contract.md is produced here, and so is
+// every run behind its worked-example funnel tables. Being TypeScript typed
+// against onboarding-run.types.ts, the examples are checked by the compiler; a
+// test also validates them against onboarding-run.schema.json and recomputes the
+// doc's funnel tables from them. The only import is type-only, so a runtime
+// that strips types can load this file without resolving it.
+import type {
+  Answer,
+  Manifest,
+  OnboardingIdentity,
+  OnboardingRunSnapshot,
+  Properties,
+  RunContext,
+  StepEntry,
+  StudioLinks,
+} from "./onboarding-run.types";
+
+/** The moment the worked-example funnels are computed at. */
+export const AS_OF = "2026-01-12T00:00:00.000Z";
+/** An in_progress run with no snapshot received for this long counts as quit. */
+export const QUIT_AFTER_MS = 24 * 60 * 60 * 1000;
+/** The most entries a snapshot may hold (D8). Past it the tracker stops recording (D26). */
+export const MAX_ENTRIES = 500;
+
+export interface ExampleRun {
+  /** Server receive time of the run's first snapshot: the run's bucket. */
+  first_received_at: string;
+  /** Server receive time of the latest snapshot: what the quit threshold reads. */
+  last_received_at: string;
+  payload: OnboardingRunSnapshot;
+}
+
+const CONTEXT: RunContext = {
+  app_version: "2.4.0",
+  build: "412",
+  platform: "ios",
+  os_version: "18.1",
+  locale: "en-US",
+  timezone: "America/New_York",
+};
+
+type PathItem = string | { step: string; answers: Answer[] };
+
+const iso = (ms: number) => new Date(ms).toISOString();
+const STEP_MS = 10_000;
+const RECEIVE_LAG_MS = 300;
+
+/**
+ * Builds a run the way a tracker would record it: one entry per screen shown,
+ * each lasting ten seconds, one send per entry plus one on completion, and each
+ * send arriving 300 ms after it left the device. A step the flow passes over
+ * is simply absent from `path`. Past MAX_ENTRIES the tracker stops recording
+ * (no new entries, answers or property changes; it still closes the last kept
+ * entry and still sends the completion), and marks the snapshot `truncated` (D26).
+ */
+function run(opts: {
+  n: number;
+  start: string;
+  onboarding: OnboardingIdentity;
+  manifest: Manifest;
+  path: PathItem[];
+  completed: boolean;
+  studio?: StudioLinks;
+  properties?: Properties;
+  context?: RunContext;
+}): ExampleRun {
+  let t = Date.parse(opts.start);
+  const steps: StepEntry[] = [];
+  let sends = 0;
+  let lastEventAt = t;
+  let truncated = false;
+  for (const item of opts.path) {
+    const step = typeof item === "string" ? item : item.step;
+    const previous = steps[steps.length - 1];
+    if (previous && previous.exited_at === null) previous.exited_at = iso(t);
+    if (steps.length === MAX_ENTRIES) {
+      // The user is on a new screen, but recording it would break the limit.
+      if (!truncated) {
+        truncated = true;
+        sends += 1; // one send to report the closed last entry and the flag
+        lastEventAt = t;
+      }
+    } else {
+      steps.push({
+        step_key: step,
+        entered_at: iso(t),
+        exited_at: null,
+        answers: typeof item === "string" ? [] : item.answers,
+      });
+      sends += 1;
+      lastEventAt = t;
+    }
+    t += STEP_MS;
+  }
+
+  if (opts.completed) {
+    if (!truncated) steps[steps.length - 1].exited_at = iso(t);
+    lastEventAt = t;
+  }
+
+  // Spread in this order so the doc's JSON blocks read top-down. No cast: the
+  // compiler checks each branch against the snapshot type.
+  const head = {
+    schema_version: 1 as const,
+    run_id: `00000000-0000-4000-8000-${String(opts.n).padStart(12, "0")}`,
+  };
+  const tail = {
+    onboarding: opts.onboarding,
+    ...(opts.studio ? { studio: opts.studio } : {}),
+    context: opts.context ?? CONTEXT,
+    manifest: opts.manifest,
+    ...(opts.properties ? { properties: opts.properties } : {}),
+    ...(truncated ? { truncated: true as const } : {}),
+    steps,
+  };
+  const started_at = steps[0].entered_at;
+  const payload: OnboardingRunSnapshot = opts.completed
+    ? { ...head, seq: sends + 1, status: "completed", started_at, completed_at: iso(t), sent_at: iso(t), ...tail }
+    : { ...head, seq: sends, status: "in_progress", started_at, completed_at: null, sent_at: iso(lastEventAt), ...tail };
+
+  return {
+    first_received_at: iso(Date.parse(opts.start) + RECEIVE_LAG_MS),
+    last_received_at: iso(lastEventAt + RECEIVE_LAG_MS),
+    payload,
+  };
+}
+
+const single = (question_key: string, value: string): Answer => ({ question_key, kind: "single", value });
+const minutes = (n: number) => iso(Date.parse("2026-01-10T09:00:00.000Z") + n * 60_000);
+
+// ---------------------------------------------------------------------------
+// Kitchen sink: one Studio-served run, two snapshots of it (mid-flow, then
+// completed). Uses every optional part of the shape except `variant_key`, which
+// a Studio-served run does not carry: each Studio arm is its own onboarding key
+// (D25). IN_FLOW_VARIANT below covers `variant_key`.
+// ---------------------------------------------------------------------------
+
+const KITCHEN_MANIFEST: Manifest = {
+  steps: [
+    { step_key: "welcome" },
+    { step_key: "goal" },
+    { step_key: "experience" },
+    { step_key: "plan_quick", slot: "plan" },
+    { step_key: "plan_detailed", slot: "plan" },
+    { step_key: "permissions" },
+    { step_key: "summary" },
+  ],
+};
+
+const kitchenGoal: PathItem = {
+  step: "goal",
+  answers: [
+    single("goal", "practice"),
+    { question_key: "topics", kind: "multi", value: ["vocabulary", "listening"] },
+  ],
+};
+const kitchenExperience: PathItem = {
+  step: "experience",
+  answers: [{ question_key: "daily_time", kind: "numeric", value: 15, unit: "minute" }],
+};
+const kitchenPath: PathItem[] = [
+  "welcome",
+  kitchenGoal,
+  kitchenExperience,
+  kitchenGoal, // back navigation: a repeated entry
+  kitchenExperience,
+  "plan_detailed",
+  // `permissions` is not shown (already granted): no entry, derived as passed over.
+  { step: "summary", answers: [{ question_key: "feedback", kind: "text", value: "Looking forward to it" }] },
+];
+const kitchen = (path: PathItem[], completed: boolean) =>
+  run({
+    n: 1,
+    start: "2026-01-10T08:00:00.000Z",
+    // Studio-served: the key is the Studio onboarding id, the version the deployment id.
+    // A Studio-served draft or preview has no deployment id and sends version "draft".
+    onboarding: { key: "6f1c2b0e-3d4a-4f8e-9b7c-2a1d0e9f8c7b", version: "412" },
+    studio: {
+      onboarding_id: "6f1c2b0e-3d4a-4f8e-9b7c-2a1d0e9f8c7b",
+      deployment_id: "412",
+      audience_id: "7",
+    },
+    context: { ...CONTEXT, platform: "android", os_version: "15", build: "2040", locale: "fr-FR", timezone: "Europe/Paris", library_version: "0.1.0" },
+    manifest: KITCHEN_MANIFEST,
+    properties: { signup_source: "email", returning_user: false, cohort_week: 2 },
+    path,
+    completed,
+  });
+
+export const KITCHEN_SINK: ExampleRun[] = [kitchen(kitchenPath.slice(0, 3), false), kitchen(kitchenPath, true)];
+
+// ---------------------------------------------------------------------------
+// A hand-coded flow that runs its own in-flow variants under one key (D25).
+// ---------------------------------------------------------------------------
+
+export const IN_FLOW_VARIANT: ExampleRun = run({
+  n: 2,
+  start: "2026-01-10T08:30:00.000Z",
+  onboarding: { key: "main", version: "7", variant_key: "short-intro" },
+  manifest: { steps: [{ step_key: "welcome" }, { step_key: "goal" }, { step_key: "summary" }] },
+  path: ["welcome"],
+  completed: false,
+});
+
+// ---------------------------------------------------------------------------
+// Overflow (D26): a run that loops between two screens far past 500 entries.
+// The tracker keeps the first 500, stops recording (entries, answers and
+// property changes), and still completes.
+// ---------------------------------------------------------------------------
+
+const loop: PathItem[] = [];
+for (let i = 0; i < 300; i++) loop.push("question", "review");
+
+export const OVERFLOW: ExampleRun = run({
+  n: 401,
+  start: "2026-01-10T07:00:00.000Z",
+  onboarding: { key: "example-long", version: "1" },
+  manifest: {
+    steps: [{ step_key: "welcome" }, { step_key: "question" }, { step_key: "review" }, { step_key: "summary" }],
+  },
+  path: ["welcome", ...loop, "summary"],
+  completed: true,
+});
+
+// ---------------------------------------------------------------------------
+// Worked examples for the funnel measures.
+// ---------------------------------------------------------------------------
+
+const SKIP_MANIFEST: Manifest = {
+  steps: [
+    { step_key: "welcome" },
+    { step_key: "goal" },
+    { step_key: "experience" },
+    { step_key: "permissions" },
+    { step_key: "summary" },
+  ],
+};
+const skip = { onboarding: { key: "example-skip", version: "1" }, manifest: SKIP_MANIFEST };
+const learn: PathItem = { step: "goal", answers: [single("goal", "learn")] };
+const practice: PathItem = { step: "goal", answers: [single("goal", "practice")] };
+
+const SLOT_MANIFEST: Manifest = {
+  steps: [
+    { step_key: "welcome" },
+    { step_key: "goal" },
+    { step_key: "plan_quick", slot: "plan" },
+    { step_key: "plan_detailed", slot: "plan" },
+    { step_key: "summary" },
+  ],
+};
+const slot = { onboarding: { key: "example-slot", version: "1" }, manifest: SLOT_MANIFEST };
+const quick: PathItem = { step: "goal", answers: [single("pace", "quick")] };
+const detailed: PathItem = { step: "goal", answers: [single("pace", "detailed")] };
+
+const MERGE_MANIFEST: Manifest = {
+  steps: [
+    { step_key: "welcome" },
+    { step_key: "goal" },
+    { step_key: "routine_a1", slot: "routine" },
+    { step_key: "routine_b1", slot: "routine" },
+    { step_key: "routine_a2" },
+    { step_key: "summary" },
+  ],
+};
+const merge = { onboarding: { key: "example-merge", version: "1" }, manifest: MERGE_MANIFEST };
+const pathA: PathItem = { step: "goal", answers: [single("path", "a")] };
+const pathB: PathItem = { step: "goal", answers: [single("path", "b")] };
+
+export const WORKED_EXAMPLES: Record<string, { runs: ExampleRun[] }> = {
+  derived_skip: {
+    runs: [
+      run({ ...skip, n: 101, start: minutes(0), completed: true, path: ["welcome", learn, "permissions", "summary"] }),
+      run({
+        ...skip,
+        n: 102,
+        start: minutes(15),
+        completed: true,
+        path: ["welcome", practice, "experience", practice, "experience", "summary"],
+      }),
+      run({ ...skip, n: 103, start: minutes(30), completed: false, path: ["welcome", practice, "experience"] }),
+      run({ ...skip, n: 104, start: minutes(45), completed: false, path: ["welcome", learn, "permissions"] }),
+      run({ ...skip, n: 105, start: "2026-01-11T23:00:00.000Z", completed: false, path: ["welcome"] }),
+      run({ ...skip, n: 106, start: minutes(60), completed: false, path: ["welcome"] }),
+    ],
+  },
+  alternative_screens: {
+    runs: [
+      run({ ...slot, n: 201, start: minutes(0), completed: true, path: ["welcome", quick, "plan_quick", "summary"] }),
+      run({ ...slot, n: 202, start: minutes(15), completed: true, path: ["welcome", detailed, "plan_detailed", "summary"] }),
+      run({ ...slot, n: 203, start: minutes(30), completed: false, path: ["welcome", detailed, "plan_detailed"] }),
+      run({ ...slot, n: 204, start: minutes(45), completed: true, path: ["welcome", quick, "plan_quick", "summary"] }),
+      run({ ...slot, n: 205, start: minutes(60), completed: false, path: ["welcome", quick] }),
+    ],
+  },
+  merge_back: {
+    runs: [
+      run({ ...merge, n: 301, start: minutes(0), completed: true, path: ["welcome", pathA, "routine_a1", "routine_a2", "summary"] }),
+      run({ ...merge, n: 302, start: minutes(15), completed: false, path: ["welcome", pathA, "routine_a1"] }),
+      run({ ...merge, n: 303, start: minutes(30), completed: true, path: ["welcome", pathB, "routine_b1", "summary"] }),
+      run({ ...merge, n: 304, start: minutes(45), completed: false, path: ["welcome", pathB, "routine_b1"] }),
+      run({ ...merge, n: 305, start: minutes(60), completed: true, path: ["welcome", pathB, "routine_b1", "summary"] }),
+    ],
+  },
+};

package/docs/onboarding-run.schema.json

@@ -0,0 +1,224 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:rocalytics-sdk:onboarding-run:1",
+  "title": "Onboarding run snapshot, schema_version 1",
+  "description": "One send of an onboarding run. Each send replaces the run's previous snapshot. Normative text: onboarding-run-contract.md. The schema is closed: an unknown field is an error.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "run_id",
+    "seq",
+    "status",
+    "started_at",
+    "completed_at",
+    "sent_at",
+    "onboarding",
+    "context",
+    "manifest",
+    "steps"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "run_id": {
+      "description": "Client-minted, lowercase UUID. One per run.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+    },
+    "seq": {
+      "description": "Starts at 1 and increases with every send of this run. The server keeps the snapshot with the highest seq.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "status": { "enum": ["in_progress", "completed"] },
+    "started_at": { "$ref": "#/$defs/timestamp" },
+    "completed_at": { "type": ["string", "null"] },
+    "sent_at": { "$ref": "#/$defs/timestamp" },
+    "onboarding": {
+      "type": "object",
+      "required": ["key", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "key": { "$ref": "#/$defs/key" },
+        "version": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:+-]{0,63}$"
+        },
+        "variant_key": {
+          "anyOf": [{ "$ref": "#/$defs/key" }, { "type": "null" }]
+        }
+      }
+    },
+    "studio": {
+      "description": "Optional links to Studio records. Opaque strings.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "onboarding_id": { "$ref": "#/$defs/link" },
+        "deployment_id": { "$ref": "#/$defs/link" },
+        "audience_id": { "$ref": "#/$defs/link" }
+      }
+    },
+    "context": {
+      "description": "Captured once, when the run starts. Country is not sent: the server derives it.",
+      "type": "object",
+      "required": ["app_version", "build", "platform", "os_version", "locale", "timezone"],
+      "additionalProperties": false,
+      "properties": {
+        "app_version": { "$ref": "#/$defs/shortText" },
+        "build": { "anyOf": [{ "$ref": "#/$defs/shortText" }, { "type": "null" }] },
+        "platform": { "enum": ["ios", "android", "web"] },
+        "os_version": { "anyOf": [{ "$ref": "#/$defs/shortText" }, { "type": "null" }] },
+        "locale": {
+          "description": "BCP 47 language tag.",
+          "type": "string",
+          "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$"
+        },
+        "timezone": {
+          "description": "IANA time zone name.",
+          "type": "string",
+          "pattern": "^[A-Za-z][A-Za-z0-9_+-]*(/[A-Za-z0-9_+-]+)*$",
+          "maxLength": 64
+        },
+        "library_version": { "$ref": "#/$defs/shortText" }
+      }
+    },
+    "manifest": {
+      "type": "object",
+      "required": ["steps"],
+      "additionalProperties": false,
+      "properties": {
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 200,
+          "items": {
+            "type": "object",
+            "required": ["step_key"],
+            "additionalProperties": false,
+            "properties": {
+              "step_key": { "$ref": "#/$defs/key" },
+              "slot": { "$ref": "#/$defs/key" }
+            }
+          }
+        }
+      }
+    },
+    "properties": {
+      "type": "object",
+      "maxProperties": 20,
+      "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,39}$" },
+      "additionalProperties": {
+        "anyOf": [
+          { "type": "string", "maxLength": 256 },
+          { "type": "number" },
+          { "type": "boolean" },
+          { "type": "null" }
+        ]
+      }
+    },
+    "truncated": {
+      "description": "Present, and true, once the tracker has stopped recording (no new entries, answers or property changes) because recording more would break the 500-entry or 256 KiB limit. What was recorded is kept. Absent means not truncated.",
+      "const": true
+    },
+    "steps": {
+      "description": "Every screen shown so far, in the order shown. A step that was not shown has no entry: whether it was passed over is derived from the manifest at read time.",
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 500,
+      "items": { "$ref": "#/$defs/entry" }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "completed" } } },
+      "then": { "properties": { "completed_at": { "$ref": "#/$defs/timestamp" } } },
+      "else": { "properties": { "completed_at": { "type": "null" } } }
+    }
+  ],
+  "$defs": {
+    "timestamp": {
+      "description": "RFC 3339 in UTC with exactly three fractional digits and a Z suffix, e.g. 2026-01-10T09:00:00.000Z. A pattern rather than format: date-time, because format is annotation-only in draft 2020-12.",
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\\.[0-9]{3}Z$"
+    },
+    "key": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"
+    },
+    "link": {
+      "anyOf": [
+        { "type": "string", "minLength": 1, "maxLength": 128 },
+        { "type": "null" }
+      ]
+    },
+    "shortText": { "type": "string", "minLength": 1, "maxLength": 32 },
+    "entry": {
+      "type": "object",
+      "required": ["step_key", "entered_at", "exited_at", "answers"],
+      "additionalProperties": false,
+      "properties": {
+        "step_key": { "$ref": "#/$defs/key" },
+        "entered_at": { "$ref": "#/$defs/timestamp" },
+        "exited_at": {
+          "anyOf": [{ "$ref": "#/$defs/timestamp" }, { "type": "null" }]
+        },
+        "answers": {
+          "type": "array",
+          "maxItems": 50,
+          "items": { "$ref": "#/$defs/answer" }
+        }
+      }
+    },
+    "answer": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["question_key", "kind", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "question_key": { "$ref": "#/$defs/key" },
+            "kind": { "const": "single" },
+            "value": { "$ref": "#/$defs/key" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["question_key", "kind", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "question_key": { "$ref": "#/$defs/key" },
+            "kind": { "const": "multi" },
+            "value": {
+              "type": "array",
+              "maxItems": 50,
+              "uniqueItems": true,
+              "items": { "$ref": "#/$defs/key" }
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["question_key", "kind", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "question_key": { "$ref": "#/$defs/key" },
+            "kind": { "const": "numeric" },
+            "value": { "type": "number" },
+            "unit": { "$ref": "#/$defs/key" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["question_key", "kind", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "question_key": { "$ref": "#/$defs/key" },
+            "kind": { "const": "text" },
+            "value": { "type": "string", "maxLength": 1000 }
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/onboarding-run.types.ts

@@ -0,0 +1,144 @@
+// Onboarding run contract, schema_version 1: TypeScript types.
+//
+// The normative text is onboarding-run-contract.md; the machine-checkable shape
+// is onboarding-run.schema.json. These types mirror the schema. Where a rule is
+// a pattern or a limit (key characters, list lengths), the type says `string`
+// or `T[]` and the comment names the rule; the schema enforces it.
+//
+// This file has no imports, so it can be copied into any TypeScript project.
+
+/**
+ * RFC 3339 timestamp in UTC with exactly three fractional digits and a `Z`
+ * suffix, e.g. `2026-01-10T09:00:00.000Z`.
+ */
+export type Timestamp = string;
+
+/**
+ * An identifier chosen by the app: 1 to 128 characters from `A-Z a-z 0-9 _ . : -`,
+ * starting with a letter or digit. Case-sensitive. Used for onboarding, step,
+ * question, option, slot and variant keys.
+ */
+export type Key = string;
+
+export interface OnboardingIdentity {
+  /**
+   * Stable key for one flow. Never reused for a different flow. Each
+   * Studio-served A/B arm is its own onboarding, so it has its own key.
+   */
+  key: Key;
+  /**
+   * Revision of the flow. 1 to 64 characters from `A-Z a-z 0-9 _ . : + -`,
+   * starting with a letter or digit. Must change whenever the manifest changes,
+   * except for the reserved version `draft`, which a Studio-served draft or
+   * preview must send because it has no deployment id.
+   */
+  version: string;
+  /**
+   * In-flow variant, for an app that runs one flow (one key) with its own
+   * variants. Not set for a Studio-served run. Absent or null otherwise.
+   */
+  variant_key?: Key | null;
+}
+
+/** Optional links to Studio records. Opaque strings of 1 to 128 characters; numeric ids are sent in decimal. */
+export interface StudioLinks {
+  onboarding_id?: string | null;
+  deployment_id?: string | null;
+  audience_id?: string | null;
+}
+
+/** Captured once, at run start, and repeated unchanged in every snapshot. */
+export interface RunContext {
+  /** Marketing version, e.g. `2.4.0`. 1 to 32 characters. */
+  app_version: string;
+  /** Build number, 1 to 32 characters, or null on a platform with no such concept. */
+  build: string | null;
+  platform: "ios" | "android" | "web";
+  /** OS version, 1 to 32 characters, or null when the platform cannot report one. */
+  os_version: string | null;
+  /** BCP 47 language tag the onboarding is shown in, e.g. `fr-FR`. */
+  locale: string;
+  /** IANA time zone, e.g. `Europe/Paris`. At most 64 characters. */
+  timezone: string;
+  /** Version of the tracking library that produced the payload. 1 to 32 characters. */
+  library_version?: string;
+}
+
+export interface ManifestStep {
+  step_key: Key;
+  /** Steps sharing a slot are alternatives shown at one position. Must be contiguous. */
+  slot?: Key;
+}
+
+/** Declared once, at run start, and repeated unchanged in every snapshot. */
+export interface Manifest {
+  /** Every step the flow can show, in flow order. 1 to 200 entries. */
+  steps: ManifestStep[];
+}
+
+/** Run-level custom property value. Strings are at most 256 characters; numbers are finite. */
+export type PropertyValue = string | number | boolean | null;
+
+/** At most 20 keys, each matching `^[a-z][a-z0-9_]{0,39}$`. */
+export type Properties = Record<string, PropertyValue>;
+
+export type Answer =
+  | { question_key: Key; kind: "single"; value: Key }
+  /** At most 50 option keys, unique. */
+  | { question_key: Key; kind: "multi"; value: Key[] }
+  | { question_key: Key; kind: "numeric"; value: number; unit?: Key }
+  /** At most 1,000 characters. Never aggregated. */
+  | { question_key: Key; kind: "text"; value: string };
+
+/**
+ * One visit to a screen the user was shown. A step that was not shown has no
+ * entry; whether the run passed over it is derived from the manifest.
+ */
+export interface StepEntry {
+  step_key: Key;
+  entered_at: Timestamp;
+  /**
+   * Null only on the last entry of an in_progress run. In a truncated run the
+   * last kept entry may already be closed, and keeps its own exit on completion.
+   */
+  exited_at: Timestamp | null;
+  /** At most 50. `question_key` is unique within an entry. */
+  answers: Answer[];
+}
+
+interface RunSnapshotBase {
+  schema_version: 1;
+  /** Client-minted, lowercase UUID. One per run. */
+  run_id: string;
+  /** Starts at 1 and increases with every send of this run. A retry reuses it. */
+  seq: number;
+  started_at: Timestamp;
+  /** Client clock when this snapshot was sent. Advisory only. */
+  sent_at: Timestamp;
+  onboarding: OnboardingIdentity;
+  studio?: StudioLinks;
+  context: RunContext;
+  manifest: Manifest;
+  properties?: Properties;
+  /**
+   * Present once the tracker has stopped recording (no new entries, answers or
+   * property changes) because recording more would break the 500-entry or
+   * 256 KiB limit. What was recorded is kept.
+   */
+  truncated?: true;
+  /** Every entry so far, in the order they happened. 1 to 500 entries. */
+  steps: StepEntry[];
+}
+
+export interface InProgressRunSnapshot extends RunSnapshotBase {
+  status: "in_progress";
+  completed_at: null;
+}
+
+export interface CompletedRunSnapshot extends RunSnapshotBase {
+  status: "completed";
+  completed_at: Timestamp;
+}
+
+/** One send. Each send replaces the run's previous snapshot. */
+export type OnboardingRunSnapshot = InProgressRunSnapshot | CompletedRunSnapshot;