deepline 0.3.270 → 0.3.272

package/dist/bundling-sources/shared_libs/play-runtime/run-event-catalog.ts

@@ -0,0 +1,610 @@
+/**
+ * The persisted Play run event vocabulary and its storage/projection contract.
+ *
+ * For runs marked runEventStore=planet_scale, PlanetScale owns the complete
+ * accepted event and log history. Convex consumes only the projections named
+ * here. Unmarked legacy runs keep their existing Convex event/log history.
+ */
+export const RUN_EVENT_KIND = {
+  runCreated: 'run.created',
+  runStarted: 'run.started',
+  runWaiting: 'run.waiting',
+  runResumed: 'run.resumed',
+  runCompleted: 'run.completed',
+  runFailed: 'run.failed',
+  runCancelled: 'run.cancelled',
+  stepStarted: 'step.started',
+  stepProgress: 'step.progress',
+  stepCompleted: 'step.completed',
+  stepFailed: 'step.failed',
+  stepSkipped: 'step.skipped',
+  logAppended: 'log.appended',
+  datasetLifecycle: 'dataset.lifecycle',
+  activityObserved: 'activity.observed',
+  workCounters: 'work.counters',
+} as const;
+
+export type RunEventKind = (typeof RUN_EVENT_KIND)[keyof typeof RUN_EVENT_KIND];
+export type KnownRunEventKind = RunEventKind;
+
+export const RUN_EVENT_SOURCE = {
+  worker: 'worker',
+  convex: 'convex',
+  coordinator: 'coordinator',
+  system: 'system',
+} as const;
+
+export type RunEventSource =
+  (typeof RUN_EVENT_SOURCE)[keyof typeof RUN_EVENT_SOURCE];
+
+export type RunEventSearchField =
+  | 'kind'
+  | 'runId'
+  | 'playName'
+  | 'source'
+  | 'occurredAt';
+
+export type RunEventPlanetScaleContent = 'event_payload' | 'log_body';
+export type RunEventConvexProjection = 'run_snapshot' | null;
+export type RunEventLegacyConvexDestination =
+  | 'run_ledger_history'
+  | 'run_log_stream';
+export type RunEventConvexRetainedFact =
+  | 'admission_fence'
+  | 'saved_play_rollup_if_eligible';
+
+export type RunEventOutboxCarrier =
+  | 'run.events'
+  | 'run.created'
+  | 'run.started'
+  | 'run.waiting'
+  | 'run.resumed'
+  | 'run.completed'
+  | 'run.failed'
+  | 'run.cancelled'
+  | 'runner.logs'
+  | 'run.wait_timeout';
+
+export type RunEventDestination = {
+  /** Shared bounded runtime-event and log search read model. */
+  searchIndex: 'planet_scale_runtime_event_index';
+  /** Canonical history destination for a run explicitly marked PScale-backed. */
+  markedRunStore: 'planet_scale';
+  /** Which part of runtime_observability.events owns the original content. */
+  planetScaleContent: RunEventPlanetScaleContent;
+  /** Live control/UI projection delivered to Convex for marked runs. */
+  convexProjection: RunEventConvexProjection;
+  /** Small Convex facts retained alongside the snapshot for marked runs. */
+  convexRetainedFacts: readonly RunEventConvexRetainedFact[];
+  /** Existing destination for unmarked legacy runs. */
+  legacyConvexDestination: RunEventLegacyConvexDestination;
+  explanation: string;
+};
+
+export type RunEventKindDescriptor = {
+  description: string;
+  /** Trusted bounded search fields; event-specific detail stays in payload. */
+  searchableFields: readonly RunEventSearchField[];
+  /** Outbox transports that can produce this canonical kind. */
+  outboxCarriers: readonly RunEventOutboxCarrier[];
+  destination: RunEventDestination;
+  example: Readonly<Record<string, unknown>>;
+};
+
+const SEARCHABLE_EVENT_FIELDS = [
+  'kind',
+  'runId',
+  'playName',
+  'source',
+  'occurredAt',
+] as const satisfies readonly RunEventSearchField[];
+
+const RUN_SNAPSHOT_DESTINATION: RunEventDestination = {
+  searchIndex: 'planet_scale_runtime_event_index',
+  markedRunStore: 'planet_scale',
+  planetScaleContent: 'event_payload',
+  convexProjection: 'run_snapshot',
+  convexRetainedFacts: ['saved_play_rollup_if_eligible'],
+  legacyConvexDestination: 'run_ledger_history',
+  explanation:
+    'PlanetScale retains the complete event. Convex reduces it into bounded current run state and keeps only selected saved-Play rollup facts when eligible; unmarked legacy runs retain Convex event history.',
+};
+
+const RUN_CREATED_DESTINATION: RunEventDestination = {
+  ...RUN_SNAPSHOT_DESTINATION,
+  convexRetainedFacts: ['admission_fence', 'saved_play_rollup_if_eligible'],
+  explanation:
+    'PlanetScale retains the complete event. Convex uses it for the live run snapshot, retains the admission fence, and may retain a saved-Play rollup fact; unmarked legacy runs retain Convex event history.',
+};
+
+const RUN_LOG_DESTINATION: RunEventDestination = {
+  searchIndex: 'planet_scale_runtime_event_index',
+  markedRunStore: 'planet_scale',
+  planetScaleContent: 'log_body',
+  convexProjection: null,
+  convexRetainedFacts: [],
+  legacyConvexDestination: 'run_log_stream',
+  explanation:
+    'PlanetScale retains the canonical log line and its search metadata. Marked-run log bodies are not copied into Convex; unmarked legacy runs continue to use the Convex Run Log Stream.',
+};
+
+/**
+ * Adding a known kind requires naming its search fields, outbox carrier,
+ * PlanetScale content shape, Convex projection, and legacy destination here.
+ */
+export const RUN_EVENT_KIND_CATALOG = {
+  [RUN_EVENT_KIND.runCreated]: {
+    description: 'The run was admitted and received its run ID.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.created'],
+    destination: RUN_CREATED_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runCreated,
+      seq: 1,
+    },
+  },
+  [RUN_EVENT_KIND.runStarted]: {
+    description: 'The run began execution.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.started'],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runStarted,
+      seq: 2,
+    },
+  },
+  [RUN_EVENT_KIND.runWaiting]: {
+    description: 'The run entered a durable wait.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.waiting'],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runWaiting,
+      waitKind: 'sleep',
+    },
+  },
+  [RUN_EVENT_KIND.runResumed]: {
+    description: 'The run resumed after a durable wait.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.resumed'],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runResumed,
+    },
+  },
+  [RUN_EVENT_KIND.runCompleted]: {
+    description: 'The run completed successfully.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.completed', 'runner.logs'],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runCompleted,
+    },
+  },
+  [RUN_EVENT_KIND.runFailed]: {
+    description: 'The run ended with a failure.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.failed', 'runner.logs'],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runFailed,
+      error: 'Request timed out',
+    },
+  },
+  [RUN_EVENT_KIND.runCancelled]: {
+    description: 'The run was cancelled.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: ['run.cancelled'],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.runCancelled,
+    },
+  },
+  [RUN_EVENT_KIND.stepStarted]: {
+    description: 'A named step began execution.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.stepStarted,
+      stepId: 'lookup',
+    },
+  },
+  [RUN_EVENT_KIND.stepProgress]: {
+    description: 'A named step reported progress.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.stepProgress,
+      stepId: 'lookup',
+    },
+  },
+  [RUN_EVENT_KIND.stepCompleted]: {
+    description: 'A named step completed.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.stepCompleted,
+      stepId: 'lookup',
+    },
+  },
+  [RUN_EVENT_KIND.stepFailed]: {
+    description: 'A named step failed.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.stepFailed,
+      stepId: 'lookup',
+    },
+  },
+  [RUN_EVENT_KIND.stepSkipped]: {
+    description: 'A named step was skipped.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.stepSkipped,
+      stepId: 'lookup',
+    },
+  },
+  [RUN_EVENT_KIND.logAppended]: {
+    description:
+      'A text log line was appended to the unified run history and log view.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.waiting',
+      'run.resumed',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+      'run.wait_timeout',
+    ],
+    destination: RUN_LOG_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.logAppended,
+      lines: ['Waiting for integration_event:contact.updated.'],
+    },
+  },
+  [RUN_EVENT_KIND.datasetLifecycle]: {
+    description: 'A run dataset was registered, made available, or failed.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.datasetLifecycle,
+      phase: 'available',
+    },
+  },
+  [RUN_EVENT_KIND.activityObserved]: {
+    description: 'The runtime recorded an activity observation.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.activityObserved,
+    },
+  },
+  [RUN_EVENT_KIND.workCounters]: {
+    description:
+      'A work segment reported logical call, provider request, and rate-limit counters.',
+    searchableFields: SEARCHABLE_EVENT_FIELDS,
+    outboxCarriers: [
+      'run.events',
+      'run.completed',
+      'run.failed',
+      'runner.logs',
+    ],
+    destination: RUN_SNAPSHOT_DESTINATION,
+    example: {
+      runId: 'play/enrich/run/abc123',
+      type: RUN_EVENT_KIND.workCounters,
+      attempt: 1,
+      logicalCalls: 4,
+      providerRequests: 4,
+      provider429s: 0,
+      final: true,
+    },
+  },
+} satisfies Record<RunEventKind, RunEventKindDescriptor>;
+
+export const RUN_EVENT_KINDS = Object.freeze(
+  Object.keys(RUN_EVENT_KIND_CATALOG) as RunEventKind[],
+);
+
+export const RUN_EVENT_UNKNOWN_KIND_DESTINATION: RunEventDestination = {
+  searchIndex: 'planet_scale_runtime_event_index',
+  markedRunStore: 'planet_scale',
+  planetScaleContent: 'event_payload',
+  convexProjection: null,
+  convexRetainedFacts: [],
+  legacyConvexDestination: 'run_ledger_history',
+  explanation:
+    'An unknown kind inside a run.events batch is retained in PlanetScale and not projected to the marked-run Convex snapshot. Unmarked legacy runs keep their existing Convex opaque-event history.',
+};
+
+/** Scheduler transport envelopes; these are carriers, not ledger kinds. */
+export const RUN_SCHEDULER_OUTBOX_EVENT_TYPE = {
+  runCreated: RUN_EVENT_KIND.runCreated,
+  runStarted: RUN_EVENT_KIND.runStarted,
+  runWaiting: RUN_EVENT_KIND.runWaiting,
+  runResumed: RUN_EVENT_KIND.runResumed,
+  runCompleted: RUN_EVENT_KIND.runCompleted,
+  runFailed: RUN_EVENT_KIND.runFailed,
+  runCancelled: RUN_EVENT_KIND.runCancelled,
+  runEvents: 'run.events',
+  runnerLogs: 'runner.logs',
+  runWaitTimeout: 'run.wait_timeout',
+} as const;
+
+export const RUN_SCHEDULER_OUTBOX_EVENT_TYPES = Object.freeze(
+  Object.values(RUN_SCHEDULER_OUTBOX_EVENT_TYPE),
+);
+
+export const RUN_SCHEDULER_OUTBOX_START_EVENT_TYPES: readonly string[] = [
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCreated,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runStarted,
+];
+
+export const RUN_SCHEDULER_OUTBOX_PREFIX_STOP_EVENT_TYPES: readonly string[] = [
+  ...RUN_SCHEDULER_OUTBOX_START_EVENT_TYPES,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runEvents,
+];
+
+export const RUN_SCHEDULER_OUTBOX_TERMINAL_EVENT_TYPES: readonly string[] = [
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCompleted,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runFailed,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCancelled,
+];
+
+export type RunSchedulerOutboxEventType =
+  (typeof RUN_SCHEDULER_OUTBOX_EVENT_TYPES)[number];
+
+/** Convex-only facts used for saved-Play membership corrections. */
+export const RUN_EVENT_CONVEX_INTERNAL_KIND = {
+  rollupMembershipAdded: 'rollup.membership.added',
+  rollupMembershipRemoved: 'rollup.membership.removed',
+} as const;
+
+/** Receipt outcomes are searchable beside run events but are not run events. */
+export const RUN_RECEIPT_SEARCH_KIND = {
+  completed: 'receipt.completed',
+  failed: 'receipt.failed',
+  skipped: 'receipt.skipped',
+} as const;
+
+export const RUN_RECEIPT_SEARCH_KIND_CATALOG = {
+  [RUN_RECEIPT_SEARCH_KIND.completed]: {
+    description: 'A durable work receipt completed.',
+    searchIndex: 'planet_scale_runtime_event_index',
+    payloadStore: 'authoritative_work_receipt',
+  },
+  [RUN_RECEIPT_SEARCH_KIND.failed]: {
+    description: 'A durable work receipt failed.',
+    searchIndex: 'planet_scale_runtime_event_index',
+    payloadStore: 'authoritative_work_receipt',
+  },
+  [RUN_RECEIPT_SEARCH_KIND.skipped]: {
+    description: 'A durable work receipt was skipped.',
+    searchIndex: 'planet_scale_runtime_event_index',
+    payloadStore: 'authoritative_work_receipt',
+  },
+} as const;
+
+export const RUN_EVENT_SEARCH_FALLBACK_KIND = 'runtime.event' as const;
+
+/** Complete vocabulary accepted by the runtime-event search --kind filter. */
+export const RUN_EVENT_SEARCH_KIND_VALUES = Object.freeze([
+  ...RUN_EVENT_KINDS,
+  ...Object.keys(RUN_RECEIPT_SEARCH_KIND_CATALOG),
+  RUN_EVENT_SEARCH_FALLBACK_KIND,
+] as const);
+
+export const RUN_EVENT_TERMINAL_KIND_VALUES: readonly string[] = [
+  RUN_EVENT_KIND.runCompleted,
+  RUN_EVENT_KIND.runFailed,
+  RUN_EVENT_KIND.runCancelled,
+];
+
+/** Live UI timeline names are projections; persisted kinds stay canonical. */
+export const PLAY_RUN_TIMELINE_EVENT_TYPE = {
+  status: 'play.run.status',
+  snapshot: 'play.run.snapshot',
+  finalStatus: 'play.run.final_status',
+  stepStatus: 'play.step.status',
+  stepProgress: 'play.step.progress',
+  health: 'play.run.health',
+  log: 'play.run.log',
+  sheetSummary: 'play.sheet.summary',
+  sheetDelta: 'play.sheet.delta',
+} as const;
+
+export const RUN_EVENT_SEARCH_DEFAULT_WINDOW_HOURS = 24;
+export const RUN_EVENT_SEARCH_DEFAULT_LIMIT = 50;
+export const RUN_EVENT_SEARCH_MAX_LIMIT = 200;
+export const RUN_EVENT_SEARCH_MAX_RUNS = 50;
+export const RUN_EVENT_SEARCH_EVENTS_PER_RUN = 200;
+export const RUN_EVENT_SEARCH_MAX_SCANNED_EVENTS = 32;
+
+export const RUN_LOG_LINE_MAX_CHARS = 2_000;
+export const RUN_LOG_RETENTION_MAX_LINES = 25_000;
+export const RUN_LOG_RETENTION_MAX_BYTES = 5 * 1024 * 1024;
+export const RUN_LOG_PAGE_MAX_LIMIT = 1_000;
+export const RUN_LOG_PAGE_DEFAULT_LIMIT = RUN_LOG_PAGE_MAX_LIMIT;
+export const RUN_LOG_TAIL_DEFAULT_LIMIT = 200;
+export const RUN_LOG_FAILED_VIEW_MAX_LINES = 20;
+export const RUN_LOG_RATE_LIMIT_POLICY = {
+  debug: { first: 200, every: 100 },
+  info: { first: 1_000, every: 100 },
+} as const;
+export const RUN_LOG_RATE_LIMIT_MARKER_EVERY = 1_000;
+export const RUN_LOG_LEVELS = ['debug', 'info', 'warn', 'error'] as const;
+export type RunLogLevel = (typeof RUN_LOG_LEVELS)[number];
+
+function sqlStringLiteral(value: string): string {
+  return "'" + value.replaceAll("'", "''") + "'";
+}
+
+/** SQL fragments used by the generated PlanetScale event recorder. */
+export const RUN_EVENT_KNOWN_KIND_SQL_LIST =
+  RUN_EVENT_KINDS.map(sqlStringLiteral).join(', ');
+
+export const RUN_EVENT_LIFECYCLE_KIND_SQL_LIST = [
+  RUN_EVENT_KIND.runCreated,
+  RUN_EVENT_KIND.runStarted,
+  RUN_EVENT_KIND.runWaiting,
+  RUN_EVENT_KIND.runResumed,
+  RUN_EVENT_KIND.runCompleted,
+  RUN_EVENT_KIND.runFailed,
+  RUN_EVENT_KIND.runCancelled,
+]
+  .map(sqlStringLiteral)
+  .join(', ');
+
+export const RUN_EVENT_SNAPSHOT_KIND_SQL_LIST = RUN_EVENT_KINDS.filter(
+  (kind) => kind !== RUN_EVENT_KIND.logAppended,
+)
+  .map(sqlStringLiteral)
+  .join(', ');
+
+export const RUN_EVENT_KIND_SQL_LITERAL = {
+  runCreated: sqlStringLiteral(RUN_EVENT_KIND.runCreated),
+  runStarted: sqlStringLiteral(RUN_EVENT_KIND.runStarted),
+  runWaiting: sqlStringLiteral(RUN_EVENT_KIND.runWaiting),
+  runResumed: sqlStringLiteral(RUN_EVENT_KIND.runResumed),
+  runCompleted: sqlStringLiteral(RUN_EVENT_KIND.runCompleted),
+  runFailed: sqlStringLiteral(RUN_EVENT_KIND.runFailed),
+  runCancelled: sqlStringLiteral(RUN_EVENT_KIND.runCancelled),
+  stepStarted: sqlStringLiteral(RUN_EVENT_KIND.stepStarted),
+  stepProgress: sqlStringLiteral(RUN_EVENT_KIND.stepProgress),
+  stepCompleted: sqlStringLiteral(RUN_EVENT_KIND.stepCompleted),
+  stepFailed: sqlStringLiteral(RUN_EVENT_KIND.stepFailed),
+  stepSkipped: sqlStringLiteral(RUN_EVENT_KIND.stepSkipped),
+  logAppended: sqlStringLiteral(RUN_EVENT_KIND.logAppended),
+  datasetLifecycle: sqlStringLiteral(RUN_EVENT_KIND.datasetLifecycle),
+  activityObserved: sqlStringLiteral(RUN_EVENT_KIND.activityObserved),
+  workCounters: sqlStringLiteral(RUN_EVENT_KIND.workCounters),
+} as const;
+
+export const RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL = {
+  runCreated: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCreated),
+  runStarted: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runStarted),
+  runWaiting: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runWaiting),
+  runResumed: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runResumed),
+  runCompleted: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCompleted),
+  runFailed: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runFailed),
+  runCancelled: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCancelled),
+  runEvents: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runEvents),
+  runnerLogs: sqlStringLiteral(RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runnerLogs),
+  runWaitTimeout: sqlStringLiteral(
+    RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runWaitTimeout,
+  ),
+} as const;
+
+export const RUN_EVENT_CONVEX_INTERNAL_KIND_SQL_LITERAL = {
+  rollupMembershipAdded: sqlStringLiteral(
+    RUN_EVENT_CONVEX_INTERNAL_KIND.rollupMembershipAdded,
+  ),
+  rollupMembershipRemoved: sqlStringLiteral(
+    RUN_EVENT_CONVEX_INTERNAL_KIND.rollupMembershipRemoved,
+  ),
+} as const;
+
+export const RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST = [
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runCompleted,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runFailed,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE.runnerLogs,
+]
+  .map(sqlStringLiteral)
+  .join(', ');
+
+export const RUN_SCHEDULER_OUTBOX_TERMINAL_EVENT_TYPE_SQL_LIST = [
+  ...RUN_SCHEDULER_OUTBOX_TERMINAL_EVENT_TYPES,
+]
+  .map(sqlStringLiteral)
+  .join(', ');
+
+export const RUN_EVENT_SEARCH_FALLBACK_KIND_SQL_LITERAL = sqlStringLiteral(
+  RUN_EVENT_SEARCH_FALLBACK_KIND,
+);
+
+export function isKnownRunEventKind(value: string): value is RunEventKind {
+  return Object.prototype.hasOwnProperty.call(RUN_EVENT_KIND_CATALOG, value);
+}
+
+export function getRunEventDestination(kind: string): RunEventDestination {
+  if (!isKnownRunEventKind(kind)) return RUN_EVENT_UNKNOWN_KIND_DESTINATION;
+  return RUN_EVENT_KIND_CATALOG[kind].destination;
+}
+
+export function describeRunEventDestination(kind: string): string {
+  const destination = getRunEventDestination(kind);
+  const projection = destination.convexProjection
+    ? 'Convex live run snapshot'
+    : 'no marked-run Convex projection';
+  const legacy =
+    destination.legacyConvexDestination === 'run_log_stream'
+      ? 'legacy Convex Run Log Stream'
+      : 'legacy Convex event history';
+  return (
+    'PlanetScale ' +
+    destination.planetScaleContent +
+    '; ' +
+    projection +
+    '; ' +
+    legacy
+  );
+}

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger-event-transport.ts

@@ -1,3 +1,4 @@
+import { RUN_EVENT_KIND } from './run-event-catalog';
 import type { PlayRunLedgerIngressEvent } from './run-ledger';
 import type { PlayLogContext } from './log-context';
 import type { RunLedgerProjectionChunk } from './run-ledger-projection-contract';
@@ -26,7 +27,8 @@ function splitRunEventForAppRuntime(
   const lines = Array.isArray(rawLines)
     ? rawLines.filter((line): line is string => typeof line === 'string')
     : [];
-  if (eventType !== 'log.appended' || lines.length === 0) return [event];
+  if (eventType !== RUN_EVENT_KIND.logAppended || lines.length === 0)
+    return [event];
   const payloadOwnsLineContexts =
     payload !== null && Object.hasOwn(payload, 'lineContexts');
   const eventOwnsLineContexts = Object.hasOwn(event, 'lineContexts');

package/dist/bundling-sources/shared_libs/play-runtime/run-ledger-projection-diagnostics.ts

@@ -1,3 +1,4 @@
+import { RUN_EVENT_KIND } from './run-event-catalog';
 import { stableStringify } from '../plays/row-identity';
 import type {
   AcceptedPlayRunLedgerEvent,
@@ -31,8 +32,8 @@ function normalizeLegacyRunWaitingProjectionFields(
     const expected = expectedEvents[index];
     if (
       isPlayRunLedgerOpaqueEvent(event) ||
-      event.type !== 'run.waiting' ||
-      expected?.type !== 'run.waiting' ||
+      event.type !== RUN_EVENT_KIND.runWaiting ||
+      expected?.type !== RUN_EVENT_KIND.runWaiting ||
       ('opaque' in expected && expected.opaque === true)
     ) {
       return event;