deepline 0.3.271 → 0.3.273

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/runtime-event-search.ts

@@ -7,6 +7,16 @@
  */
 import { normalizeRuntimeSchedulerSchema } from '../runtime-scheduler-topology';
 import type { PostgresSchedulerQueryClient } from './postgres';
+import {
+  RUN_EVENT_CONVEX_INTERNAL_KIND_SQL_LITERAL,
+  RUN_EVENT_KIND_SQL_LITERAL,
+  RUN_EVENT_KNOWN_KIND_SQL_LIST,
+  RUN_EVENT_LIFECYCLE_KIND_SQL_LIST,
+  RUN_EVENT_SNAPSHOT_KIND_SQL_LIST,
+  RUN_EVENT_SEARCH_FALLBACK_KIND_SQL_LITERAL,
+  RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST,
+  RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL,
+} from '../run-event-catalog';
 
 const EVENTS_TABLE = 'runtime_observability.events';
 const RUNTIME_EVENT_LOG_DEDUPE_INDEX = 'runtime_events_log_attempt_digest_idx';
@@ -15,18 +25,18 @@ const RUNTIME_EVENT_LOG_POSITION_INDEX =
 const RUNTIME_EVENT_LOG_LEGACY_INDEX =
   'runtime_events_legacy_log_normalize_idx';
 const RUNTIME_EVENT_LOG_BODY_PAGE_INDEX = 'runtime_events_run_log_body_seq_idx';
-const RUNTIME_EVENT_LOG_LEGACY_PREDICATE = `kind = 'log.appended'
+const RUNTIME_EVENT_LOG_LEGACY_PREDICATE = `kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
   AND source_digest IS NOT NULL
   AND NOT (search_doc ? 'logContentDigest')
   AND (search_doc->>'producerAttempt') ~ '^[1-9][0-9]{0,5}$'`;
-const RUNTIME_EVENT_LOG_BODY_PAGE_PREDICATE = `kind = 'log.appended'
+const RUNTIME_EVENT_LOG_BODY_PAGE_PREDICATE = `kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
   AND log_seq IS NOT NULL
   AND (log_body IS NOT NULL OR message IS NOT NULL)`;
-const RUNTIME_EVENT_LOG_DEDUPE_PREDICATE = `kind = 'log.appended'
+const RUNTIME_EVENT_LOG_DEDUPE_PREDICATE = `kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
   AND source_digest IS NOT NULL
   AND search_doc ? 'producerAttempt'
   AND search_doc ? 'logContentDigest'`;
-const RUNTIME_EVENT_LOG_POSITION_PREDICATE = `kind = 'log.appended'
+const RUNTIME_EVENT_LOG_POSITION_PREDICATE = `kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
   AND search_doc ? 'producerAttempt'
   AND search_doc ? 'logPositions'`;
 const RUNTIME_EVENT_LOG_POSITION_EXPRESSION = `jsonb_set(
@@ -41,7 +51,7 @@ const RUNTIME_EVENT_LOG_POSITION_EXPRESSION = `jsonb_set(
 // Migration readiness tracks this projection body independently of scheduler
 // wire and schema versions. Bump when a changed trigger must be reinstalled.
 export const RUNTIME_EVENT_SEARCH_OUTBOX_PROJECTION_MARKER =
-  'runtime-event-search-log-context-v11-unified-event-journal';
+  'runtime-event-search-log-context-v12-scheduler-wait-logs';
 export const RUNTIME_EVENT_CANONICAL_RETENTION_INDEX_READY_MARKER =
   'runtime-event-canonical-retention-v1';
 export const RUNTIME_EVENTS_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
@@ -369,7 +379,7 @@ export async function searchRuntimeEvents(
   params.push(input.includePayloads === true);
   const result = await client.query<EventRow>(
     `SELECT event_id, occurred_at, ingested_at, run_id, play_name, kind, level,
-            coalesce(message, CASE WHEN kind = 'log.appended' THEN
+            coalesce(message, CASE WHEN kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} THEN
               left(CASE WHEN search_doc->>'source' = 'terminal' THEN
                 regexp_replace(log_body,
                   '^' || chr(1) || 'prov:[^' || chr(1) || ']*' || chr(1), '')
@@ -515,14 +525,14 @@ export async function getRuntimeRunLogPage(
          (SELECT log_seq
             FROM runtime_observability.events
            WHERE runtime_scope = $1 AND org_id = $2 AND run_id = $3
-             AND kind = 'log.appended' AND log_seq IS NOT NULL
+             AND kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND log_seq IS NOT NULL
              AND (log_body IS NOT NULL OR message IS NOT NULL)
              AND ingested_at >= clock_timestamp() - interval '7 days'
            ORDER BY log_seq ASC LIMIT 1) AS first_seq,
          (SELECT log_seq
             FROM runtime_observability.events
            WHERE runtime_scope = $1 AND org_id = $2 AND run_id = $3
-             AND kind = 'log.appended' AND log_seq IS NOT NULL
+             AND kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND log_seq IS NOT NULL
              AND (log_body IS NOT NULL OR message IS NOT NULL)
              AND ingested_at >= clock_timestamp() - interval '7 days'
            ORDER BY log_seq DESC LIMIT 1) AS last_seq
@@ -534,7 +544,7 @@ export async function getRuntimeRunLogPage(
        SELECT log_seq AS seq, coalesce(log_body, message) AS line
          FROM runtime_observability.events
         WHERE runtime_scope = $1 AND org_id = $2 AND run_id = $3
-          AND kind = 'log.appended' AND log_seq IS NOT NULL
+          AND kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND log_seq IS NOT NULL
           AND (log_body IS NOT NULL OR message IS NOT NULL)
           AND ingested_at >= clock_timestamp() - interval '7 days'
           ${pageWhere}
@@ -806,7 +816,7 @@ export async function ensureRuntimeEventSearchSchema(
   );
   await client.query(`CREATE INDEX IF NOT EXISTS runtime_events_run_log_seq_idx
     ON runtime_observability.events (runtime_scope, org_id, run_id, log_seq)
-    WHERE kind = 'log.appended' AND log_seq IS NOT NULL`);
+    WHERE kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND log_seq IS NOT NULL`);
   await client.query(
     `DROP INDEX IF EXISTS runtime_observability.runtime_run_log_cursors_retention_idx`,
   );
@@ -1027,7 +1037,7 @@ export async function attachRuntimeEventSearchTriggers(
       IF run_org IS NULL OR play IS NULL THEN
         RAISE EXCEPTION 'Outbox search projection has no matching run';
       END IF;
-      IF observation.event_type = 'run.events' THEN
+      IF observation.event_type = ${RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL.runEvents} THEN
         event_batch := observation.payload_json->'events';
         IF jsonb_typeof(event_batch) IS DISTINCT FROM 'array' THEN
           RAISE EXCEPTION 'Search projection requires run.events array';
@@ -1036,7 +1046,7 @@ export async function attachRuntimeEventSearchTriggers(
           AND observation.payload_json->>'logBodyStore' IS DISTINCT FROM 'planet_scale' THEN
           RAISE EXCEPTION 'Search projection requires nonempty run.events array';
         END IF;
-      ELSIF observation.event_type IN ('run.completed', 'run.failed', 'runner.logs')
+      ELSIF observation.event_type IN (${RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST})
         AND observation.payload_json ? 'terminalProgressEvents' THEN
         event_batch := observation.payload_json->'terminalProgressEvents';
         IF jsonb_typeof(event_batch) IS DISTINCT FROM 'array' THEN
@@ -1049,24 +1059,65 @@ export async function attachRuntimeEventSearchTriggers(
         observation.payload_json->'terminalWorkCounterSegment'->'attempt');
       -- The retained envelope has its own position space: it can contain
       -- diagnostics absent from both live delivery and ctx-only replay.
-      IF observation.event_type IN ('run.completed', 'run.failed', 'runner.logs')
+      IF observation.event_type IN (${RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST})
         AND observation.payload_json ? 'terminalLogLines'
         AND (envelope_attempt #>> '{}') ~ '^[1-9][0-9]{0,5}$' THEN
         event_batch := coalesce(event_batch, '[]'::jsonb) || jsonb_build_array(
           jsonb_strip_nulls(jsonb_build_object(
-            'type', 'log.appended', 'runId', observation.run_id, 'source', 'terminal',
+            'type', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, 'runId', observation.run_id, 'source', 'terminal',
             'producerAttempt', envelope_attempt, 'channelOffset', 0,
             'lines', observation.payload_json->'terminalLogLines',
             'lineContexts', observation.payload_json->'terminalLogContexts'
           ))
         );
       END IF;
+      IF observation.event_type = ${RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL.runWaitTimeout} THEN
+        event_batch := jsonb_build_array(jsonb_build_object(
+          'type', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended},
+          'runId', observation.run_id,
+          'occurredAt', floor(extract(epoch FROM observation.created_at) * 1000)::bigint,
+          'source', 'system',
+          'lines', jsonb_build_array(
+            'Timed out waiting for integration_event:' ||
+            CASE WHEN jsonb_typeof(observation.payload_json->'eventKey') = 'string'
+              THEN observation.payload_json->>'eventKey' ELSE 'event' END || '.'
+          )
+        ));
+      ELSIF observation.event_type IN (
+          ${RUN_EVENT_KIND_SQL_LITERAL.runWaiting},
+          ${RUN_EVENT_KIND_SQL_LITERAL.runResumed}
+        )
+        AND (
+          jsonb_typeof(observation.payload_json->'kind') IS DISTINCT FROM 'string'
+          OR observation.payload_json->>'kind' IN ('integration_event', 'integration_event_batch')
+        )
+        AND (
+          jsonb_typeof(observation.payload_json->'kind') IS DISTINCT FROM 'string'
+          OR (
+            jsonb_typeof(observation.payload_json->'eventKey') = 'string'
+            AND observation.payload_json->>'eventKey' <> ''
+          )
+        ) THEN
+        event_batch := jsonb_build_array(jsonb_build_object(
+          'type', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended},
+          'runId', observation.run_id,
+          'occurredAt', floor(extract(epoch FROM observation.created_at) * 1000)::bigint,
+          'source', 'system',
+          'lines', jsonb_build_array(
+            CASE WHEN observation.event_type = ${RUN_EVENT_KIND_SQL_LITERAL.runWaiting}
+              THEN 'Waiting for integration_event:'
+              ELSE 'Resumed integration_event:' END ||
+            CASE WHEN jsonb_typeof(observation.payload_json->'eventKey') = 'string'
+              THEN observation.payload_json->>'eventKey' ELSE 'event' END || '.'
+          )
+        ));
+      END IF;
       IF event_batch IS NOT NULL THEN
         -- Normalize old positional writers once per batch under the run mutex.
         -- Per-line lookups must remain digest-selective: an OR fallback for
         -- unmarked rows otherwise scans the whole attempt for every new line.
         IF EXISTS (SELECT 1 FROM jsonb_array_elements(event_batch) AS entry
-          WHERE entry->>'type' = 'log.appended') THEN
+          WHERE entry->>'type' = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}) THEN
           UPDATE runtime_observability.events AS event SET search_doc = event.search_doc ||
             jsonb_build_object('logContentDigest', event.source_digest) ||
             CASE WHEN NOT (event.search_doc ? 'logPositions')
@@ -1078,7 +1129,7 @@ export async function attachRuntimeEventSearchTriggers(
                 substring(event.event_id FROM length('log:' || observation.run_id || ':' || (event.search_doc->>'producerAttempt') || ':') + 1)::bigint))
               ELSE '{}'::jsonb END
            WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-             AND event.run_id = observation.run_id AND event.kind = 'log.appended'
+             AND event.run_id = observation.run_id AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
              AND event.source_digest IS NOT NULL AND NOT (event.search_doc ? 'logContentDigest')
              AND (event.search_doc->>'producerAttempt') ~ '^[1-9][0-9]{0,5}$';
         END IF;
@@ -1088,14 +1139,8 @@ export async function attachRuntimeEventSearchTriggers(
             RAISE EXCEPTION 'Search projection event has invalid run identity';
           END IF;
           kind := coalesce(item->>'type', item->>'key');
-          IF kind NOT IN (
-            'run.created', 'run.started', 'run.waiting', 'run.resumed',
-            'run.completed', 'run.failed', 'run.cancelled',
-            'step.started', 'step.progress', 'step.completed',
-            'step.failed', 'step.skipped', 'log.appended',
-            'dataset.lifecycle', 'activity.observed', 'work.counters'
-          ) THEN
-            kind := 'runtime.event';
+          IF kind NOT IN (${RUN_EVENT_KNOWN_KIND_SQL_LIST}) THEN
+            kind := ${RUN_EVENT_SEARCH_FALLBACK_KIND_SQL_LITERAL};
           END IF;
           at_time := CASE WHEN (item->>'occurredAt') ~ '^[0-9]{12,14}$'
             THEN to_timestamp((item->>'occurredAt')::double precision / 1000)
@@ -1115,15 +1160,15 @@ export async function attachRuntimeEventSearchTriggers(
             'operation', CASE WHEN item->'observation'->'target'->>'kind' = 'provider'
               THEN left(item->'observation'->'target'->>'operation', 256) END
           ));
-          IF kind = 'log.appended' AND jsonb_typeof(item->'lines') IS DISTINCT FROM 'array' THEN
+          IF kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND jsonb_typeof(item->'lines') IS DISTINCT FROM 'array' THEN
             RAISE EXCEPTION 'Search projection requires log.appended lines';
           END IF;
-          IF kind = 'log.appended' AND item ? 'lineContexts'
+          IF kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND item ? 'lineContexts'
             AND (jsonb_typeof(item->'lineContexts') IS DISTINCT FROM 'array'
                  OR jsonb_array_length(item->'lineContexts') <> jsonb_array_length(item->'lines')) THEN
             RAISE EXCEPTION 'Search projection requires lineContexts aligned to log lines';
           END IF;
-          IF kind = 'log.appended' THEN
+          IF kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} THEN
             FOR line, line_ordinal IN SELECT value, ordinality FROM jsonb_array_elements(item->'lines') WITH ORDINALITY LOOP
               IF jsonb_typeof(line) IS DISTINCT FROM 'string' THEN
                 RAISE EXCEPTION 'Search projection requires log line strings';
@@ -1137,7 +1182,7 @@ export async function attachRuntimeEventSearchTriggers(
                       SELECT coalesce(event.log_text_digest, encode(sha256(convert_to(btrim(event.log_body), 'UTF8')), 'hex')) AS dedupe_key
                         FROM runtime_observability.events AS event
                        WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-                         AND event.run_id = observation.run_id AND event.kind = 'log.appended'
+                         AND event.run_id = observation.run_id AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
                          AND event.log_seq IS NOT NULL AND (event.log_text_digest IS NOT NULL OR event.log_body IS NOT NULL)
                          AND (item->>'producerAttempt' IS NULL
                            OR event.search_doc->>'producerAttempt' = item->>'producerAttempt')
@@ -1237,7 +1282,7 @@ export async function attachRuntimeEventSearchTriggers(
                   INTO matched_event_id, existing_digest, matched_doc
                   FROM runtime_observability.events AS event
                  WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-                   AND event.run_id = observation.run_id AND event.kind = 'log.appended'
+                   AND event.run_id = observation.run_id AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
                    AND event.event_id = ANY(position_event_ids)
                    AND (
                      event.search_doc->'logPositions'->>log_channel = log_position::text
@@ -1262,7 +1307,7 @@ export async function attachRuntimeEventSearchTriggers(
                     INTO matched_event_id, existing_digest, matched_doc
                     FROM runtime_observability.events AS event
                    WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-                     AND event.run_id = observation.run_id AND event.kind = 'log.appended'
+                     AND event.run_id = observation.run_id AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
                      AND event.search_doc ? 'producerAttempt'
                      AND event.search_doc ? 'logPositions'
                      AND (${RUNTIME_EVENT_LOG_POSITION_EXPRESSION.replaceAll('search_doc', 'event.search_doc')}) @> position_alias
@@ -1283,7 +1328,7 @@ export async function attachRuntimeEventSearchTriggers(
                   INTO matched_event_id, matched_doc
                   FROM runtime_observability.events AS event
                  WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-                   AND event.run_id = observation.run_id AND event.kind = 'log.appended'
+                   AND event.run_id = observation.run_id AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
                    AND event.source_digest IS NOT NULL
                    AND event.search_doc ? 'producerAttempt'
                    AND event.search_doc ? 'logContentDigest'
@@ -1306,7 +1351,7 @@ export async function attachRuntimeEventSearchTriggers(
               -- Serialize with terminal acceptance on the log mutex. A late
               -- retry of an accepted position is harmless; a new position
               -- after terminal closure must never recreate expired history.
-              IF compact_logs AND observation.event_type = 'run.events'
+              IF compact_logs AND observation.event_type = ${RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL.runEvents}
                 AND run_status IN ('completed', 'failed', 'cancelled')
                 AND NOT EXISTS (SELECT 1 FROM runtime_observability.events
                   WHERE runtime_scope = ${quoteLiteral(scope)} AND org_id = run_org
@@ -1322,13 +1367,13 @@ export async function attachRuntimeEventSearchTriggers(
                 CASE WHEN canonical_events THEN nextval('runtime_observability.runtime_event_order_seq') END,
                 CASE WHEN canonical_events THEN jsonb_strip_nulls(
                   (item - 'lines' - 'lineContexts') || jsonb_build_object(
-                    'type', 'log.appended', 'runId', observation.run_id,
+                    'type', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, 'runId', observation.run_id,
                     'occurredAt', floor(extract(epoch FROM at_time) * 1000)::bigint,
                     'lineOrdinal', line_ordinal,
                     'context', line_context
                   )) END,
                 at_time, observation.run_id, play,
-                'log.appended', NULL, CASE WHEN compact_logs THEN NULL ELSE left(line #>> '{}', 2048) END,
+                ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, NULL, CASE WHEN compact_logs THEN NULL ELSE left(line #>> '{}', 2048) END,
                 line #>> '{}', digest,
                 encode(sha256(convert_to(btrim(line #>> '{}'), 'UTF8')), 'hex'), line_doc
               ) ON CONFLICT DO NOTHING;
@@ -1346,7 +1391,7 @@ export async function attachRuntimeEventSearchTriggers(
           ELSE
             -- Final progress may arrive in the first terminal receipt and
             -- again in completion. One attempt/ordinal owns one immutable fact.
-            terminal_progress_identity := observation.event_type IN ('runner.logs', 'run.completed', 'run.failed')
+            terminal_progress_identity := observation.event_type IN (${RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST})
               AND coalesce((observation.payload_json->>'producerAttempt') ~ '^[1-9][0-9]{0,5}$', false);
             eid := CASE WHEN terminal_progress_identity
               THEN 'terminal-progress:' || observation.run_id || ':' ||
@@ -1374,10 +1419,11 @@ export async function attachRuntimeEventSearchTriggers(
           END IF;
         END LOOP;
       END IF;
-      IF observation.event_type IN (
-        'run.created', 'run.started', 'run.waiting', 'run.resumed',
-        'run.completed', 'run.failed', 'run.cancelled'
-      ) AND NOT (observation.event_type IN ('run.waiting', 'run.resumed')
+      IF observation.event_type IN (${RUN_EVENT_LIFECYCLE_KIND_SQL_LIST})
+         AND NOT (observation.event_type IN (
+           ${RUN_EVENT_KIND_SQL_LITERAL.runWaiting},
+           ${RUN_EVENT_KIND_SQL_LITERAL.runResumed}
+         )
                  AND observation.payload_json->>'kind' = 'detached_runner') THEN
         INSERT INTO runtime_observability.events (
           runtime_scope, org_id, event_id, event_seq, event_payload,
@@ -1399,7 +1445,7 @@ export async function attachRuntimeEventSearchTriggers(
           observation.run_id, play, observation.event_type, jsonb_build_object('kind', observation.event_type, 'source', 'system')
         ) ON CONFLICT DO NOTHING;
       END IF;
-      IF observation.event_type IN ('run.completed', 'run.failed', 'runner.logs') THEN
+      IF observation.event_type IN (${RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST}) THEN
         -- Detached runners deliver their retained ctx.log tail in the terminal
         -- outbox fact rather than a run.events batch. Project it from that
         -- authoritative write so search and the existing log stream agree.
@@ -1407,7 +1453,7 @@ export async function attachRuntimeEventSearchTriggers(
           AND NOT (observation.payload_json ? 'terminalLogLines') THEN
           RAISE EXCEPTION 'Search projection requires terminalLogLines for terminalLogContexts';
         END IF;
-        IF observation.event_type IN ('run.completed', 'run.failed', 'runner.logs')
+        IF observation.event_type IN (${RUN_EVENT_TERMINAL_LOG_CARRIER_SQL_LIST})
           AND observation.payload_json ? 'terminalLogLines'
           AND NOT coalesce((envelope_attempt #>> '{}') ~ '^[1-9][0-9]{0,5}$', false) THEN
           IF jsonb_typeof(observation.payload_json->'terminalLogLines') IS DISTINCT FROM 'array' THEN
@@ -1436,7 +1482,7 @@ export async function attachRuntimeEventSearchTriggers(
                         FROM runtime_observability.events AS event
                        WHERE event.runtime_scope = ${quoteLiteral(scope)}
                          AND event.org_id = run_org AND event.run_id = observation.run_id
-                         AND event.kind = 'log.appended'
+                         AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
                          AND (observation.payload_json->>'producerAttempt' IS NULL
                            OR event.search_doc->>'producerAttempt' = observation.payload_json->>'producerAttempt')
                          AND event.log_seq IS NOT NULL AND (event.log_text_digest IS NOT NULL OR event.log_body IS NOT NULL)
@@ -1448,7 +1494,7 @@ export async function attachRuntimeEventSearchTriggers(
                     FROM runtime_observability.events AS event
                    WHERE event.runtime_scope = ${quoteLiteral(scope)}
                      AND event.org_id = run_org AND event.run_id = observation.run_id
-                     AND event.kind = 'log.appended' AND (event.log_text_digest IS NOT NULL OR event.log_body IS NOT NULL)
+                     AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND (event.log_text_digest IS NOT NULL OR event.log_body IS NOT NULL)
                      AND event.event_id = ANY(fresh_event_ids)
                      AND (observation.payload_json->>'producerAttempt' IS NULL
                        OR event.search_doc->>'producerAttempt' = observation.payload_json->>'producerAttempt')
@@ -1499,7 +1545,7 @@ export async function attachRuntimeEventSearchTriggers(
               END IF;
             END IF;
             line_doc := jsonb_strip_nulls(jsonb_build_object(
-              'kind', 'log.appended', 'source', 'terminal',
+              'kind', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, 'source', 'terminal',
               'producerAttempt', observation.payload_json->'producerAttempt'
             ));
             IF line_context IS NOT NULL THEN
@@ -1513,12 +1559,12 @@ export async function attachRuntimeEventSearchTriggers(
               ${quoteLiteral(scope)}, run_org, observation.event_id || ':log:' || line_ordinal,
               CASE WHEN canonical_events THEN nextval('runtime_observability.runtime_event_order_seq') END,
               CASE WHEN canonical_events THEN jsonb_strip_nulls(jsonb_build_object(
-                'type', 'log.appended', 'runId', observation.run_id,
+                'type', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, 'runId', observation.run_id,
                 'occurredAt', floor(extract(epoch FROM observation.created_at) * 1000)::bigint,
                 'source', 'terminal', 'producerAttempt', observation.payload_json->'producerAttempt',
                 'lineOrdinal', line_ordinal, 'context', line_context
               )) END,
-              observation.created_at, observation.run_id, play, 'log.appended', NULL,
+              observation.created_at, observation.run_id, play, ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, NULL,
               CASE WHEN compact_logs THEN NULL ELSE left(regexp_replace(line #>> '{}',
                 '^' || chr(1) || 'prov:[^' || chr(1) || ']*' || chr(1), ''), 2048) END,
               line #>> '{}',
@@ -1562,7 +1608,7 @@ export async function attachRuntimeEventSearchTriggers(
     LANGUAGE sql IMMUTABLE SET search_path = pg_catalog AS $function$
       SELECT coalesce(jsonb_agg(item.value ORDER BY item.ordinality), '[]'::jsonb)
       FROM jsonb_array_elements(batch) WITH ORDINALITY AS item(value, ordinality)
-      WHERE coalesce(item.value->>'type', item.value->>'key') IS DISTINCT FROM 'log.appended'
+      WHERE coalesce(item.value->>'type', item.value->>'key') IS DISTINCT FROM ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
     $function$
   `);
   await client.query(`
@@ -1572,61 +1618,59 @@ export async function attachRuntimeEventSearchTriggers(
         SELECT coalesce(value->>'type', value->>'key') AS kind
       )
       SELECT CASE
-        WHEN event.kind IN ('rollup.membership.added', 'rollup.membership.removed')
+        WHEN event.kind IN (
+          ${RUN_EVENT_CONVEX_INTERNAL_KIND_SQL_LITERAL.rollupMembershipAdded},
+          ${RUN_EVENT_CONVEX_INTERNAL_KIND_SQL_LITERAL.rollupMembershipRemoved}
+        )
           AND value->>'opaque' = 'true' THEN jsonb_strip_nulls(jsonb_build_object(
             'type', event.kind, 'runId', value->'runId',
             'occurredAt', value->'occurredAt', 'source', value->'source',
             'opaque', true, 'payload', value->'payload'))
-        WHEN event.kind IN (
-          'run.created', 'run.started', 'run.waiting', 'run.resumed',
-          'run.completed', 'run.failed', 'run.cancelled',
-          'step.started', 'step.progress', 'step.completed',
-          'step.failed', 'step.skipped', 'dataset.lifecycle',
-          'activity.observed', 'work.counters'
-        ) THEN jsonb_strip_nulls(jsonb_build_object(
+        WHEN event.kind IN (${RUN_EVENT_SNAPSHOT_KIND_SQL_LIST})
+          THEN jsonb_strip_nulls(jsonb_build_object(
           'type', event.kind, 'runId', value->'runId',
           'occurredAt', value->'occurredAt', 'source', value->'source'
         ) || CASE event.kind
-          WHEN 'run.created' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runCreated} THEN jsonb_build_object(
             'playName', value->'playName', 'status', value->'status',
             'runtimeBackend', value->'runtimeBackend')
-          WHEN 'run.started' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runStarted} THEN jsonb_build_object(
             'playName', value->'playName', 'runtimeBackend', value->'runtimeBackend')
-          WHEN 'run.waiting' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runWaiting} THEN jsonb_build_object(
             'waitKind', value->'waitKind', 'waitUntil', value->'waitUntil')
-          WHEN 'run.completed' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runCompleted} THEN jsonb_build_object(
             'result', value->'result', 'resultSummary', value->'resultSummary',
             'terminalWorkCounterSegment', value->'terminalWorkCounterSegment')
-          WHEN 'run.failed' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runFailed} THEN jsonb_build_object(
             'error', value->'error', 'result', value->'result',
             'resultSummary', value->'resultSummary',
             'terminalWorkCounterSegment', value->'terminalWorkCounterSegment')
-          WHEN 'run.cancelled' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runCancelled} THEN jsonb_build_object(
             'error', value->'error', 'result', value->'result')
-          WHEN 'step.started' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.stepStarted} THEN jsonb_build_object(
             'stepId', value->'stepId', 'label', value->'label',
             'kind', value->'kind', 'artifactTableNamespace', value->'artifactTableNamespace')
-          WHEN 'step.progress' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.stepProgress} THEN jsonb_build_object(
             'stepId', value->'stepId', 'label', value->'label',
             'kind', value->'kind', 'status', value->'status', 'progress', value->'progress')
-          WHEN 'step.completed' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.stepCompleted} THEN jsonb_build_object(
             'stepId', value->'stepId', 'label', value->'label',
             'kind', value->'kind', 'artifactTableNamespace', value->'artifactTableNamespace')
-          WHEN 'step.failed' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.stepFailed} THEN jsonb_build_object(
             'stepId', value->'stepId', 'label', value->'label', 'kind', value->'kind',
             'error', value->'error', 'artifactTableNamespace', value->'artifactTableNamespace')
-          WHEN 'step.skipped' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.stepSkipped} THEN jsonb_build_object(
             'stepId', value->'stepId', 'label', value->'label',
             'kind', value->'kind', 'artifactTableNamespace', value->'artifactTableNamespace')
-          WHEN 'dataset.lifecycle' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.datasetLifecycle} THEN jsonb_build_object(
             'datasetId', value->'datasetId', 'path', value->'path',
             'tableNamespace', value->'tableNamespace', 'phase', value->'phase',
             'persistedRows', value->'persistedRows', 'succeededRows', value->'succeededRows',
             'failedRows', value->'failedRows', 'complete', value->'complete',
             'bornFrom', value->'bornFrom')
-          WHEN 'activity.observed' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.activityObserved} THEN jsonb_build_object(
             'observation', value->'observation')
-          WHEN 'work.counters' THEN jsonb_build_object(
+          WHEN ${RUN_EVENT_KIND_SQL_LITERAL.workCounters} THEN jsonb_build_object(
             'attempt', value->'attempt', 'invocationSeq', value->'invocationSeq',
             'segmentId', value->'segmentId', 'logicalCalls', value->'logicalCalls',
             'providerRequests', value->'providerRequests', 'provider429s', value->'provider429s',
@@ -1689,7 +1733,7 @@ export async function attachRuntimeEventSearchTriggers(
         FROM ${schema}.runs WHERE run_id = NEW.run_id;
       IF compact_logs OR canonical_events THEN
         NEW.payload_json := NEW.payload_json - 'terminalLogLines' - 'terminalLogContexts';
-        IF NEW.event_type = 'run.events' THEN
+        IF NEW.event_type = ${RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL.runEvents} THEN
           NEW.payload_json := jsonb_set(NEW.payload_json, '{events}',
             ${schema}.without_log_events(NEW.payload_json->'events'))
             || jsonb_build_object('logBodyStore', 'planet_scale');
@@ -1698,17 +1742,17 @@ export async function attachRuntimeEventSearchTriggers(
           NEW.payload_json := jsonb_set(NEW.payload_json, '{terminalProgressEvents}',
             ${schema}.without_log_events(NEW.payload_json->'terminalProgressEvents'));
         END IF;
-        IF NEW.event_type = 'run.failed' AND NEW.payload_json ? 'result' THEN
+        IF NEW.event_type = ${RUN_EVENT_KIND_SQL_LITERAL.runFailed} AND NEW.payload_json ? 'result' THEN
           NEW.payload_json := jsonb_set(NEW.payload_json, '{result}',
             ${schema}.compact_runner_log_envelope(NEW.payload_json->'result'));
         END IF;
-        IF NEW.event_type = 'run.completed' AND NEW.payload_json ? 'output' THEN
+        IF NEW.event_type = ${RUN_EVENT_KIND_SQL_LITERAL.runCompleted} AND NEW.payload_json ? 'output' THEN
           NEW.payload_json := jsonb_set(NEW.payload_json, '{output}',
             ${schema}.without_runtime_log_tail(NEW.payload_json->'output'));
         END IF;
       END IF;
       IF canonical_events THEN
-        IF NEW.event_type = 'run.events' THEN
+        IF NEW.event_type = ${RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL.runEvents} THEN
           NEW.payload_json := jsonb_set(NEW.payload_json, '{events}',
             ${schema}.convex_projection_events(NEW.payload_json->'events'));
         END IF;
@@ -1737,12 +1781,12 @@ export async function attachRuntimeEventSearchTriggers(
           sha256(convert_to(NEW.runner_result_json::text, 'UTF8')), 'hex');
         observation.event_id := 'runner-terminal-logs:' || NEW.run_id || ':' || NEW.attempt;
         observation.run_id := NEW.run_id;
-        observation.event_type := 'runner.logs';
+        observation.event_type := ${RUN_SCHEDULER_OUTBOX_EVENT_TYPE_SQL_LITERAL.runnerLogs};
         observation.created_at := coalesce(NEW.runner_terminal_received_at, clock_timestamp());
         observation.payload_json := jsonb_set(NEW.runner_log_payload_json,
           '{terminalProgressEvents}', (
             SELECT coalesce(jsonb_agg(
-              CASE WHEN event->>'type' = 'log.appended' THEN event
+              CASE WHEN event->>'type' = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} THEN event
                 ELSE event || jsonb_build_object('_runtimeProgressOrdinal', position) END
               ORDER BY position), '[]'::jsonb)
             FROM jsonb_array_elements(CASE
@@ -1894,12 +1938,12 @@ export async function hasRuntimeEventSearchShape(
   return result.rows[0]?.ready === true;
 }
 
-const RUNTIME_EVENT_BODY_RETENTION_PREDICATE = `kind <> 'log.appended' OR log_body IS NOT NULL
+const RUNTIME_EVENT_BODY_RETENTION_PREDICATE = `kind <> ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} OR log_body IS NOT NULL
   OR message IS NOT NULL OR search_doc ? 'context'`;
-const RUNTIME_EVENT_CANONICAL_RETENTION_PREDICATE = `(kind <> 'log.appended' AND event_payload IS NULL)
+const RUNTIME_EVENT_CANONICAL_RETENTION_PREDICATE = `(kind <> ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND event_payload IS NULL)
   OR (substr(kind, 1, 8) = 'receipt.' AND event_payload IS NOT NULL
       AND (receipt_ref IS NOT NULL OR receipt_key IS NOT NULL))
-  OR (kind = 'log.appended' AND (log_body IS NOT NULL OR message IS NOT NULL OR search_doc ? 'context'))`;
+  OR (kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended} AND (log_body IS NOT NULL OR message IS NOT NULL OR search_doc ? 'context'))`;
 
 // pg_get_expr adds grouping and text casts. Preserve quoted literals exactly;
 // this known OR-only predicate rejects other operators, keys and literal values.
@@ -2230,11 +2274,11 @@ export async function pruneRuntimeEvents(
               event_payload = CASE WHEN event.event_payload IS NULL THEN NULL
                                    ELSE event.event_payload - 'context' END,
               search_doc = jsonb_strip_nulls(jsonb_build_object(
-                'kind', 'log.appended', 'source', event.search_doc->'source',
+                'kind', ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}, 'source', event.search_doc->'source',
                 'producerAttempt', event.search_doc->'producerAttempt',
                 'logPositions', event.search_doc->'logPositions',
                 'logContentDigest', event.search_doc->'logContentDigest'))
-         FROM candidates WHERE event.ctid = candidates.ctid AND event.kind = 'log.appended'
+         FROM candidates WHERE event.ctid = candidates.ctid AND event.kind = ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
          RETURNING event.event_id
      ), scrubbed_receipts AS (
        UPDATE runtime_observability.events AS event
@@ -2247,7 +2291,7 @@ export async function pruneRuntimeEvents(
          RETURNING event.event_id
      ), deleted AS (
        DELETE FROM runtime_observability.events AS event USING candidates
-        WHERE event.ctid = candidates.ctid AND event.kind <> 'log.appended'
+        WHERE event.ctid = candidates.ctid AND event.kind <> ${RUN_EVENT_KIND_SQL_LITERAL.logAppended}
           AND event.event_payload IS NULL
         RETURNING event.event_id
      )

package/dist/bundling-sources/shared_libs/plays/authoring-contract.ts

@@ -1607,13 +1607,14 @@ export interface PlayAuthoringRuntimeContext {
   ): Promise<AsyncPlayRunRef>;
 
   /**
-   * Write a customer-safe line to the durable Run Log Stream. Omitting level
-   * preserves the historical info-level behavior.
+   * Write a customer-safe retained log line, searchable as `log.appended` in the unified event journal. Default severity is info; runtime sampling and retention limits apply. Use `runs.logs` for retained text and `runs.searchEvents` for indexed context; see `deepline runs logs --help` for the complete read contract.
    */
   log(
     message: string,
     options?: {
+      /** Defaults to info. Warn/error lines are not subject to info/debug sampling. */
       level?: 'debug' | 'info' | 'warn' | 'error';
+      /** At most eight flat scalar fields and 2,048 UTF-8 bytes total. Keys match [A-Za-z_][A-Za-z0-9_]{0,63}; __proto__, constructor and prototype are forbidden. String values are at most 256 UTF-8 bytes. Search with `$.context.<key> == literal`; context cannot override run/event identity. */
       context?: Readonly<Record<string, string | number | boolean>>;
     },
   ): void;