Telemetry

The telemetry module models what the player reports about a played deal: a closed vocabulary of event types, and a compact trace of every game fact with its timing. The API ingests batches sent by the player, attaches them to the client session, and lands each referenced serve on the owner's quota. The decoder rebuilds a replay from the stored chunks. Rollups and analytics over these events live in Usage analytics.

Import from @workspace/training/domain/telemetry and @workspace/training/application/telemetry. The signed client session a batch is attached to comes from the SessionTokenService port, documented on the Ports page.

Domain

Event types and payloads

Every boundary validates against these unions; unknown values are rejected, never stored.

Every payload may carry the structural references serveId?: string and code?: string, never free text.

TraceStep is a tuple [token, deltaMs] or [token, deltaMs, 1]: a closed-vocabulary token, the milliseconds since the previous step of the run (the first step counts from the run start), and 1 when the engine played the seat instead of the learner (bids and cards only). Seats, bid indexes and completed tricks are derivable, so never sent.

LegacyTraceStep and LegacyTraceChunkPayload are the verbose format shipped before the compact one. They are still accepted at ingestion while stale player bundles age out, never emitted, and carry seats and trick outcomes inline.

Trace tokens

One string per game fact, whose shape alone names the fact kind.

ParsedTraceToken is { kind: "bid-placed"; bid }, { kind: "card-played"; card }, { kind: "hint" }, { kind: "play-error"; error }, { kind: "bid-rejected"; error; bid }, { kind: "play-claimed"; side; tricks } or { kind: "state-replaced"; reason; plays }.

parseTraceToken("1NT"); // => { kind: "bid-placed", bid: "1NT" }
parseTraceToken("SA"); // => { kind: "card-played", card: "SA" }
parseTraceToken(TRACE_HINT_TOKEN); // => { kind: "hint" }
parseTraceToken(playErrorToken("follow-suit")); // => { kind: "play-error", error: "follow-suit" }
parseTraceToken(bidRejectedToken("wrong-bid", "1NT")); // => { kind: "bid-rejected", error: "wrong-bid", bid: "1NT" }
parseTraceToken(playClaimedToken("NS", { NS: 9, EW: 4 })); // => { kind: "play-claimed", side: "NS", tricks: { NS: 9, EW: 4 } }
parseTraceToken(stateReplacedToken("undo", 12)); // => { kind: "state-replaced", reason: "undo", plays: 12 }
parseTraceToken("whatever"); // => null: outside the closed vocabulary

isTracePlayToken("Pass"); // => true: only bids and cards may carry the `auto` flag
isTraceMarkerToken("undo:3"); // => true

Decoding a trace

The decoder is the replay's input format. It rebuilds what the wire leaves out (seats, bid indexes, completed tricks and their winners) from the token sequence and the deal, with the same rules the player's engine applies.

DecodedTraceStep is { offsetMs } plus one of: bid-placed (player, bid, index, auto), card-played (player, card, auto), trick-completed (winner, trickNumber), state-replaced (reason, plays), play-error (error), bid-rejected (player, bid, error, seated like the bid it refused without moving the table), play-claimed (side, tricks per partnership), hint. TraceDecodeError extends Error and is not an AppError.

The contract is derived from the traced auction when there is one, else taken from context.contract. Trump precedence follows the play phase: the contract's trump, then the deal's. The recorded lead prevails; otherwise the declarer's left-hand opponent leads.

const auctionPart: TraceChunkPayload = {
  seq: 1,
  part: 0,
  steps: [["1NT", 2000], ["Pass", 800, 1], ["Pass", 300], ["Pass", 300, 1]],
};
const playPart: TraceChunkPayload = { seq: 2, part: 1, steps: [["SA", 1500], ["S2", 400, 1]] };
const chunks = [playPart, auctionPart];

const steps = decodeTraceRun(chunks, { opener: "N" });
// Parts are reordered, deltas accumulate across them, seats and tricks are recomputed:
// steps[0] => { kind: "bid-placed", player: "N", bid: "1NT", index: 0, auto: false, offsetMs: 2000 }
// steps[1] => { kind: "bid-placed", player: "E", bid: "Pass", index: 1, auto: true, offsetMs: 2800 }
// steps[4] => { kind: "card-played", player: "E", card: "SA", auto: false, offsetMs: 4900 }

try {
  decodeTraceRun([playPart], { opener: "N" });
} catch (error) {
  error instanceof TraceDecodeError; // => true: "trace part 0 is missing"
}

// A serve replayed twice carries several runs; `part: 0` opens each one.
splitTraceRuns([
  { seq: 1, part: 0, steps: [] },
  { seq: 2, part: 1, steps: [] },
  { seq: 3, part: 0, steps: [] },
]).length; // => 2

Application

TelemetryIngestService

createTelemetryIngestService(deps: TelemetryIngestServiceDeps): TelemetryIngestService

Stores a validated batch under its session and lands every distinct serve the batch references. Every event type counts: the first one received is the serve's landing. A debit that throws never fails the batch; the serve stays unconsumed so a later event retries it.

ServeDebit is { serveId; outcome: ServeDebitOutcome } where ServeDebitOutcome is the DiffusionDebitOutcome of Entitlements plus "failed": the landing transaction threw and rolled back.

export async function landBatch(deps: TelemetryIngestServiceDeps, sessionId: string) {
  const telemetry = createTelemetryIngestService(deps);
  const batch: TelemetryIngestInput = {
    sessionId,
    events: [
      { type: "deal-loaded", serveId: "serve-1", payload: {}, occurredAt: new Date() },
      {
        type: "play-finished",
        serveId: "serve-1",
        payload: { tricks: 9 },
        occurredAt: new Date(),
      },
      { type: "result", serveId: null, payload: { stars: 3 }, occurredAt: new Date() },
    ],
  };
  const result = await telemetry.ingest(batch);
  result.accepted; // => 3: every event is stored, with or without a serve
  result.debits; // => [{ serveId: "serve-1", outcome }]: one debit per distinct serve
  return result;
}

TelemetryRetentionService

createTelemetryRetentionService(deps: TelemetryRetentionServiceDeps): TelemetryRetentionService

Deletes the raw events past their retention span. An event is identified when it carries the signed-in player's account, copied from its serve at ingestion; every other event, those without a serve included, is anonymous. Both spans outlast every reader of raw events, which looks back a few days at most, so they only bound what a later replay or re-rollup can still see. The API runs it nightly after the rollup, with both spans overridable by environment.

Ports

TelemetryEventsRepository

The append-only raw event log, on the canonical surface of Queries: writeMany and a bounded delete. It has no read side; rollups and usage read the table through their own ports.

TelemetryEventCriteria.pastRetention(cutoffs) matches the events received before anonymousBefore that carry no account, and those received before identifiedBefore whatever they carry. createFakeTelemetryEventsRepository() from @workspace/training/testing is its in-memory fake.

SessionTokenService (cross-cutting): mints, verifies and renews the signed anonymous client session token whose sid becomes the batch's sessionId. It throws SessionTokenVerificationError from the package root. See Ports.

Errors

The service throws nothing of its own: a debit failure is reported through onDebitError and surfaces as the failed outcome. TraceDecodeError (domain) is a plain Error thrown by decodeTraceRun.