deepline 0.3.246 → 0.3.248

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

@@ -0,0 +1,1347 @@
+/**
+ * The customer-visible, append-only search projection of durable Play facts.
+ *
+ * Outbox and receipt triggers write small rows in their authoritative SQL
+ * transaction. They never deliver work, replay a Play, or copy receipt output.
+ * The API may read only through fixed, tenant-scoped queries in this module.
+ */
+import { normalizeRuntimeSchedulerSchema } from '../runtime-scheduler-topology';
+import type { PostgresSchedulerQueryClient } from './postgres';
+
+const EVENTS_TABLE = 'runtime_observability.events';
+// 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-v7-terminal-progress-counts-auto-scope-log-mutex-channel-aliases';
+export const RUNTIME_EVENTS_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_SEARCH_WINDOW_MS = RUNTIME_EVENTS_RETENTION_MS;
+const MAX_SEARCH_RESULTS = 200;
+const MAX_JSONPATH_BYTES = 512;
+
+/** Explicit input validation; arbitrary TypeErrors are never public errors. */
+export class RuntimeEventInputError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RuntimeEventInputError';
+  }
+}
+
+export type RuntimeSearchEvent = {
+  eventId: string;
+  occurredAt: string;
+  ingestedAt: string;
+  runId: string;
+  playName: string;
+  kind: string;
+  level: string | null;
+  message: string | null;
+  receiptRef: string | null;
+  searchDoc: Record<string, unknown>;
+};
+
+export type RuntimeSearchCursor = { occurredAt: string; eventId: string };
+
+export type RuntimeEventSearchInput = {
+  runtimeScope: string;
+  orgId: string;
+  since: Date;
+  until: Date;
+  limit: number;
+  runId?: string;
+  playName?: string;
+  kind?: string;
+  jsonpath?: string;
+  cursor?: RuntimeSearchCursor;
+};
+
+export type RuntimeEventReceipt = {
+  /** Server-only; never serialize this physical key into a customer response. */
+  receiptKey: string;
+  status: 'completed' | 'failed' | 'skipped';
+  output: unknown | null;
+  outputRef: unknown | null;
+  error: string | null;
+  errorPayload: unknown | null;
+};
+
+export type RuntimeRunLogPage = {
+  totalLogCount: number;
+  logsTruncated: boolean;
+  lastStoredSeq: number;
+  firstStoredSeq: number | null;
+  entries: Array<{ seq: number; line: string }>;
+};
+
+function requiredScope(value: string): string {
+  const scope = normalizeRuntimeSchedulerSchema(value);
+  if (!scope)
+    throw new RuntimeEventInputError(
+      'Runtime event search requires a valid runtime scope.',
+    );
+  return scope;
+}
+
+function requiredOrg(value: string): string {
+  const org = value?.trim();
+  if (!org || org.length > 256) {
+    throw new RuntimeEventInputError(
+      'Runtime event search requires an organization.',
+    );
+  }
+  return org;
+}
+
+function quoteIdent(value: string): string {
+  return `"${value.replaceAll('"', '""')}"`;
+}
+
+function quoteLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+/**
+ * Native PostgreSQL JSONPath equality, restricted to flat indexed fields or
+ * one scalar key under the bounded `context` object.
+ * No recursive paths, filters, methods, regex, comparisons or wildcards can
+ * turn an org-wide bounded search into an arbitrary JSON scan.
+ */
+export function validateRuntimeEventJsonpath(value: string): string {
+  parseRuntimeEventJsonpath(value);
+  return value;
+}
+
+type RuntimeEventPredicate = {
+  path: string;
+  literal: string;
+  value: string | number | boolean;
+};
+
+function parseRuntimeEventJsonpath(value: string): RuntimeEventPredicate[] {
+  if (!value || Buffer.byteLength(value, 'utf8') > MAX_JSONPATH_BYTES) {
+    throw new RuntimeEventInputError(
+      'Runtime event JSONPath is empty or exceeds 512 bytes.',
+    );
+  }
+  const clause =
+    /\$\.(orgId|runId|playName|runtimeScope|producerAttempt|kind|status|source|stepId|stepKind|datasetId|phase|provider|operation|context\.[A-Za-z_][A-Za-z0-9_]{0,63})\s*==\s*("(?:\\.|[^"\\])*"|true|false|-?\d+(?:\.\d+)?)/y;
+  let position = 0;
+  let clauses = 0;
+  const predicates: RuntimeEventPredicate[] = [];
+  while (position < value.length) {
+    clause.lastIndex = position;
+    const match = clause.exec(value);
+    if (!match)
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath supports flat equality predicates only.',
+      );
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(match[2]);
+    } catch {
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath requires a valid JSON scalar.',
+      );
+    }
+    if (match[2].startsWith('"')) {
+      if (typeof parsed !== 'string' || parsed.length > 256) {
+        throw new RuntimeEventInputError(
+          'Runtime event JSONPath string value is too long.',
+        );
+      }
+    }
+    if (
+      (typeof parsed !== 'string' &&
+        typeof parsed !== 'number' &&
+        typeof parsed !== 'boolean') ||
+      (typeof parsed === 'number' && !Number.isFinite(parsed))
+    ) {
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath requires a finite scalar.',
+      );
+    }
+    if (
+      ['orgId', 'runId', 'playName', 'runtimeScope'].includes(match[1]) &&
+      typeof parsed !== 'string'
+    ) {
+      throw new RuntimeEventInputError(
+        'Runtime event identity predicates require strings.',
+      );
+    }
+    if (
+      match[1] === 'producerAttempt' &&
+      (typeof parsed !== 'number' ||
+        !Number.isSafeInteger(parsed) ||
+        parsed < 1)
+    ) {
+      throw new RuntimeEventInputError(
+        'Runtime event producerAttempt requires a positive integer.',
+      );
+    }
+    predicates.push({ path: match[1], literal: match[2], value: parsed });
+    if (
+      match[1].startsWith('context.') &&
+      ['__proto__', 'constructor', 'prototype'].includes(
+        match[1].slice('context.'.length),
+      )
+    ) {
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath has an unsupported context key.',
+      );
+    }
+    clauses += 1;
+    if (clauses > 8)
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath has too many predicates.',
+      );
+    position = clause.lastIndex;
+    if (position === value.length) break;
+    const separator = /\s*&&\s*/y;
+    separator.lastIndex = position;
+    if (!separator.exec(value)) {
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath supports conjunctions only.',
+      );
+    }
+    position = separator.lastIndex;
+    if (position === value.length) {
+      throw new RuntimeEventInputError(
+        'Runtime event JSONPath ends with a conjunction.',
+      );
+    }
+  }
+  return predicates;
+}
+
+type EventRow = {
+  event_id: string;
+  occurred_at: Date | string;
+  ingested_at: Date | string;
+  run_id: string;
+  play_name: string;
+  kind: string;
+  level: string | null;
+  message: string | null;
+  receipt_ref: string | null;
+  search_doc: Record<string, unknown>;
+};
+
+function iso(value: Date | string): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime()))
+    throw new Error('Runtime event has invalid timestamp.');
+  return date.toISOString();
+}
+
+/** Client must be a dedicated reader in a transaction with SET LOCAL scope. */
+export async function searchRuntimeEvents(
+  client: PostgresSchedulerQueryClient,
+  input: RuntimeEventSearchInput,
+): Promise<{
+  events: RuntimeSearchEvent[];
+  nextCursor: RuntimeSearchCursor | null;
+}> {
+  const scope = requiredScope(input.runtimeScope);
+  const org = requiredOrg(input.orgId);
+  const since = input.since.getTime();
+  const until = input.until.getTime();
+  if (
+    !Number.isFinite(since) ||
+    !Number.isFinite(until) ||
+    since >= until ||
+    until - since > MAX_SEARCH_WINDOW_MS
+  ) {
+    throw new RuntimeEventInputError(
+      'Runtime event search requires a window of at most seven days.',
+    );
+  }
+  if (
+    !Number.isSafeInteger(input.limit) ||
+    input.limit < 1 ||
+    input.limit > MAX_SEARCH_RESULTS
+  ) {
+    throw new RuntimeEventInputError(
+      'Runtime event search limit must be between 1 and 200.',
+    );
+  }
+  const params: unknown[] = [
+    scope,
+    org,
+    input.since.toISOString(),
+    input.until.toISOString(),
+  ];
+  const predicates = [
+    'runtime_scope = $1',
+    'org_id = $2',
+    'occurred_at >= $3::timestamptz',
+    'occurred_at < $4::timestamptz',
+    "ingested_at >= clock_timestamp() - interval '7 days'",
+  ];
+  const addExact = (
+    column: 'run_id' | 'play_name' | 'kind',
+    value: string | undefined,
+  ) => {
+    if (value === undefined) return;
+    if (!value.trim() || value.length > 256)
+      throw new RuntimeEventInputError(
+        `Invalid runtime event ${column} filter.`,
+      );
+    params.push(value);
+    predicates.push(`${column} = $${params.length}`);
+  };
+  addExact('run_id', input.runId);
+  addExact('play_name', input.playName);
+  addExact('kind', input.kind);
+  if (input.jsonpath !== undefined) {
+    const identityColumns = {
+      orgId: 'org_id',
+      runId: 'run_id',
+      playName: 'play_name',
+      runtimeScope: 'runtime_scope',
+    } as const;
+    const documentPredicates: string[] = [];
+    for (const predicate of parseRuntimeEventJsonpath(input.jsonpath)) {
+      const column =
+        identityColumns[predicate.path as keyof typeof identityColumns];
+      if (column) {
+        params.push(predicate.value);
+        predicates.push(`${column} = $${params.length}`);
+      } else {
+        documentPredicates.push(`$.${predicate.path} == ${predicate.literal}`);
+      }
+    }
+    if (documentPredicates.length > 0) {
+      params.push(documentPredicates.join(' && '));
+      predicates.push(`search_doc @@ $${params.length}::jsonpath`);
+    }
+  }
+  if (input.cursor) {
+    const cursorAt = new Date(input.cursor.occurredAt);
+    if (
+      !Number.isFinite(cursorAt.getTime()) ||
+      !input.cursor.eventId ||
+      input.cursor.eventId.length > 512
+    ) {
+      throw new RuntimeEventInputError('Invalid runtime event cursor.');
+    }
+    params.push(cursorAt.toISOString(), input.cursor.eventId);
+    predicates.push(
+      `(occurred_at, event_id) < ($${params.length - 1}::timestamptz, $${params.length})`,
+    );
+  }
+  params.push(input.limit + 1);
+  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
+              left(CASE WHEN search_doc->>'source' = 'terminal' THEN
+                regexp_replace(log_body,
+                  '^' || chr(1) || 'prov:[^' || chr(1) || ']*' || chr(1), '')
+                ELSE log_body END, 2048)
+              END) AS message,
+            receipt_ref, search_doc
+       FROM ${EVENTS_TABLE}
+      WHERE ${predicates.join(' AND ')}
+      ORDER BY occurred_at DESC, event_id DESC
+      LIMIT $${params.length}::integer`,
+    params,
+  );
+  const hasMore = result.rows.length > input.limit;
+  const events = result.rows.slice(0, input.limit).map((row) => ({
+    eventId: row.event_id,
+    occurredAt: iso(row.occurred_at),
+    ingestedAt: iso(row.ingested_at),
+    runId: row.run_id,
+    playName: row.play_name,
+    kind: row.kind,
+    level: row.level,
+    message: row.message,
+    receiptRef: row.receipt_ref,
+    searchDoc: {
+      ...row.search_doc,
+      orgId: org,
+      runId: row.run_id,
+      playName: row.play_name,
+      runtimeScope: scope,
+    },
+  }));
+  const last = events.at(-1);
+  return {
+    events,
+    nextCursor:
+      hasMore && last
+        ? { occurredAt: last.occurredAt, eventId: last.eventId }
+        : null,
+  };
+}
+
+/**
+ * Reads a receipt through a narrow SECURITY DEFINER function. The reader has
+ * no direct grant on any scheduler receipt table, and the function checks both
+ * the RLS transaction context and the event reference before dynamic SQL.
+ */
+export async function getRuntimeEventReceipt(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    runtimeScope: string;
+    orgId: string;
+    runId: string;
+    receiptRef: string;
+  },
+): Promise<RuntimeEventReceipt | null> {
+  const scope = requiredScope(input.runtimeScope);
+  const org = requiredOrg(input.orgId);
+  if (
+    !input.runId ||
+    input.runId.length > 256 ||
+    !/^[0-9a-f]{8}-[0-9a-f-]{27,}$/i.test(input.receiptRef)
+  ) {
+    throw new RuntimeEventInputError(
+      'Invalid runtime event receipt reference.',
+    );
+  }
+  const result = await client.query<{ receipt: RuntimeEventReceipt | null }>(
+    `SELECT runtime_observability.fetch_receipt($1, $2, $3, $4::uuid) AS receipt`,
+    [scope, org, input.runId, input.receiptRef],
+  );
+  return result.rows[0]?.receipt ?? null;
+}
+
+/** Read the existing per-run log contract from the tenant-scoped event index. */
+export async function getRuntimeRunLogPage(
+  client: PostgresSchedulerQueryClient,
+  input: {
+    runtimeScope: string;
+    orgId: string;
+    runId: string;
+    afterSeq: number;
+    limit: number;
+    /** Return the newest bounded window for a stream's initial connection. */
+    tail?: boolean;
+  },
+): Promise<RuntimeRunLogPage> {
+  const scope = requiredScope(input.runtimeScope);
+  const org = requiredOrg(input.orgId);
+  if (!input.runId || input.runId.length > 256) {
+    throw new RuntimeEventInputError(
+      'Runtime run log read requires a valid run id.',
+    );
+  }
+  if (!Number.isSafeInteger(input.afterSeq) || input.afterSeq < 0) {
+    throw new RuntimeEventInputError(
+      'Runtime run log cursor must be a non-negative integer.',
+    );
+  }
+  if (
+    !Number.isSafeInteger(input.limit) ||
+    input.limit < 1 ||
+    input.limit > 1000
+  ) {
+    throw new RuntimeEventInputError(
+      'Runtime run log page limit must be between 1 and 1000.',
+    );
+  }
+  const tail = input.tail === true;
+  const pageWhere = tail ? '' : 'AND log_seq > $4';
+  const pageOrder = tail ? 'DESC' : 'ASC';
+  const pageLimit = tail ? '$4::integer' : '$5::integer';
+  const pageParams = tail
+    ? [scope, org, input.runId, input.limit]
+    : [scope, org, input.runId, input.afterSeq, input.limit];
+  const result = await client.query<{
+    total_log_count: string | number | null;
+    first_stored_seq: string | number | null;
+    last_stored_seq: string | number | null;
+    entries: Array<{ seq: string | number; line: string }>;
+  }>(
+    // Match the event-then-cursor relation lock order used by migrations and
+    // log projection. Cursor-first reads can deadlock a schema expansion.
+    `WITH retained AS (
+       SELECT min(log_seq) AS first_seq, max(log_seq) AS last_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 ingested_at >= clock_timestamp() - interval '7 days'
+     ), run_cursor AS (
+       SELECT last_seq
+         FROM runtime_observability.run_log_cursors
+        WHERE runtime_scope = $1 AND org_id = $2 AND run_id = $3
+     ), page AS (
+       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 ingested_at >= clock_timestamp() - interval '7 days'
+          ${pageWhere}
+        ORDER BY log_seq ${pageOrder}
+        LIMIT ${pageLimit}
+     )
+     SELECT (SELECT last_seq FROM run_cursor) AS total_log_count,
+            retained.first_seq AS first_stored_seq,
+            retained.last_seq AS last_stored_seq,
+            coalesce((SELECT jsonb_agg(jsonb_build_object('seq', seq, 'line', line)
+                                       ORDER BY seq) FROM page), '[]'::jsonb) AS entries
+       FROM retained`,
+    pageParams,
+  );
+  const row = result.rows[0];
+  const totalLogCount = Number(row?.total_log_count ?? 0);
+  const firstStoredSeq =
+    row?.first_stored_seq == null ? null : Number(row.first_stored_seq);
+  const lastStoredSeq =
+    row?.last_stored_seq == null ? 0 : Number(row.last_stored_seq);
+  if (
+    !Number.isSafeInteger(totalLogCount) ||
+    !Number.isSafeInteger(lastStoredSeq) ||
+    (firstStoredSeq !== null && !Number.isSafeInteger(firstStoredSeq))
+  ) {
+    throw new Error(
+      'Runtime run log cursor is outside the safe integer range.',
+    );
+  }
+  const rawEntries = Array.isArray(row?.entries) ? row.entries : [];
+  const entries = rawEntries.map((entry) => ({
+    seq: Number(entry.seq),
+    line: entry.line,
+  }));
+  if (
+    entries.some(
+      (entry) =>
+        !Number.isSafeInteger(entry.seq) || typeof entry.line !== 'string',
+    )
+  ) {
+    throw new Error('Runtime run log page contains an invalid row.');
+  }
+  return {
+    totalLogCount,
+    logsTruncated:
+      totalLogCount > 0 &&
+      (firstStoredSeq !== 1 || lastStoredSeq < totalLogCount),
+    lastStoredSeq,
+    firstStoredSeq,
+    entries,
+  };
+}
+
+/** Attach only on the explicit migration/bootstrap path, never on a hot read. */
+export async function ensureRuntimeEventSearchSchema(
+  client: PostgresSchedulerQueryClient,
+): Promise<void> {
+  await client.query('CREATE SCHEMA IF NOT EXISTS runtime_observability');
+  await client.query(`
+    CREATE TABLE IF NOT EXISTS runtime_observability.events (
+      runtime_scope text NOT NULL,
+      org_id text NOT NULL,
+      event_id text NOT NULL,
+      log_seq bigint,
+      occurred_at timestamptz NOT NULL,
+      ingested_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+      run_id text NOT NULL,
+      play_name text NOT NULL,
+      kind text NOT NULL,
+      level text,
+      message text,
+      log_body text,
+      receipt_ref uuid,
+      receipt_key text,
+      source_digest text,
+      search_doc jsonb NOT NULL DEFAULT '{}'::jsonb,
+      PRIMARY KEY (runtime_scope, org_id, event_id),
+      CONSTRAINT runtime_events_doc_size CHECK (octet_length(search_doc::text) <= 4096),
+      CONSTRAINT runtime_events_message_size CHECK (message IS NULL OR octet_length(message) <= 8192)
+    )
+  `);
+  await client.query(
+    `ALTER TABLE runtime_observability.events ADD COLUMN IF NOT EXISTS log_seq bigint`,
+  );
+  await client.query(
+    `ALTER TABLE runtime_observability.events ADD COLUMN IF NOT EXISTS log_body text`,
+  );
+  // Compact replay evidence survives body expiry. No writer uses it until the
+  // reader-first storage expansion has completed its deployment.
+  await client.query(
+    `ALTER TABLE runtime_observability.events ADD COLUMN IF NOT EXISTS log_text_digest text`,
+  );
+  await client.query(`CREATE TABLE IF NOT EXISTS runtime_observability.run_log_cursors (
+      runtime_scope text NOT NULL,
+      org_id text NOT NULL,
+      run_id text NOT NULL,
+      last_seq bigint NOT NULL CHECK (last_seq >= 1),
+      updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+      PRIMARY KEY (runtime_scope, org_id, run_id)
+    )`);
+  await client.query(
+    `ALTER TABLE runtime_observability.run_log_cursors ENABLE ROW LEVEL SECURITY`,
+  );
+  await client.query(
+    `DROP POLICY IF EXISTS runtime_run_log_read_scope ON runtime_observability.run_log_cursors`,
+  );
+  await client.query(`CREATE POLICY runtime_run_log_read_scope ON runtime_observability.run_log_cursors
+    FOR SELECT TO PUBLIC USING (
+      org_id = current_setting('app.org_id', true)
+      AND runtime_scope = current_setting('app.runtime_scope', true)
+    )`);
+  await client.query(
+    `REVOKE ALL ON runtime_observability.run_log_cursors FROM PUBLIC`,
+  );
+  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`);
+  await client.query(
+    `DROP INDEX IF EXISTS runtime_observability.runtime_run_log_cursors_retention_idx`,
+  );
+  await client.query(`CREATE INDEX IF NOT EXISTS runtime_events_org_time_idx
+    ON runtime_observability.events (runtime_scope, org_id, occurred_at DESC, event_id DESC)`);
+  await client.query(`CREATE INDEX IF NOT EXISTS runtime_events_run_time_idx
+    ON runtime_observability.events (runtime_scope, org_id, run_id, occurred_at DESC, event_id DESC)`);
+  await client.query(`CREATE INDEX IF NOT EXISTS runtime_events_doc_idx
+    ON runtime_observability.events USING gin (search_doc jsonb_path_ops)`);
+  await client.query(`CREATE INDEX IF NOT EXISTS runtime_events_retention_idx
+    ON runtime_observability.events (ingested_at, event_id)`);
+  await client.query(`CREATE UNIQUE INDEX IF NOT EXISTS runtime_events_receipt_ref_idx
+    ON runtime_observability.events (runtime_scope, org_id, receipt_ref)
+    WHERE receipt_ref IS NOT NULL`);
+  await client.query(
+    `ALTER TABLE runtime_observability.events ENABLE ROW LEVEL SECURITY`,
+  );
+  await client.query(
+    `DROP POLICY IF EXISTS runtime_events_read_scope ON runtime_observability.events`,
+  );
+  await client.query(`CREATE POLICY runtime_events_read_scope ON runtime_observability.events
+    FOR SELECT TO PUBLIC USING (
+      org_id = current_setting('app.org_id', true)
+      AND runtime_scope = current_setting('app.runtime_scope', true)
+    )`);
+  await client.query(`REVOKE ALL ON SCHEMA runtime_observability FROM PUBLIC`);
+  await client.query(`REVOKE ALL ON runtime_observability.events FROM PUBLIC`);
+  await client.query(`
+    CREATE OR REPLACE FUNCTION runtime_observability.fetch_receipt(
+      p_scope text, p_org text, p_run text, p_ref uuid
+    ) RETURNS jsonb
+    LANGUAGE plpgsql SECURITY DEFINER
+    SET search_path = pg_catalog
+    AS $function$
+    DECLARE answer jsonb; receipt_key_value text;
+    BEGIN
+      IF p_scope !~ '^[a-z_][a-z0-9_]{0,62}$'
+        OR p_org IS NULL OR p_run IS NULL OR p_ref IS NULL
+        OR p_org IS DISTINCT FROM current_setting('app.org_id', true)
+        OR p_scope IS DISTINCT FROM current_setting('app.runtime_scope', true)
+      THEN RETURN NULL; END IF;
+      SELECT event.receipt_key INTO receipt_key_value
+        FROM runtime_observability.events AS event
+         WHERE event.runtime_scope = p_scope AND event.org_id = p_org
+           AND event.run_id = p_run AND event.receipt_ref = p_ref
+           AND event.ingested_at >= clock_timestamp() - interval '7 days';
+      IF receipt_key_value IS NULL THEN RETURN NULL; END IF;
+      EXECUTE format(
+        'SELECT jsonb_build_object(''receiptKey'', k, ''status'', status, ''output'', output_json, ''outputRef'', output_ref, ''error'', error, ''errorPayload'', error_payload) FROM %I.receipts WHERE org_id = $1 AND run_id = $2 AND k = $3 AND status IN (''completed'', ''failed'', ''skipped'')',
+        p_scope
+      ) INTO answer USING p_org, p_run, receipt_key_value;
+      RETURN answer;
+    END
+    $function$
+  `);
+  await client.query(
+    `REVOKE ALL ON FUNCTION runtime_observability.fetch_receipt(text,text,text,uuid) FROM PUBLIC`,
+  );
+}
+
+/** The exact provisioned PlanetScale reader role; never grant to a guessed role. */
+export async function grantRuntimeEventReader(
+  client: PostgresSchedulerQueryClient,
+  readerRole: string,
+): Promise<void> {
+  if (!readerRole || !/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/.test(readerRole)) {
+    throw new RuntimeEventInputError(
+      'Invalid provisioned runtime event reader role.',
+    );
+  }
+  const role = quoteIdent(readerRole);
+  await client.query(`GRANT USAGE ON SCHEMA runtime_observability TO ${role}`);
+  await client.query(`GRANT SELECT (
+    runtime_scope, org_id, event_id, occurred_at, ingested_at, run_id,
+    log_seq, log_body, play_name, kind, level, message, receipt_ref, search_doc
+  ) ON runtime_observability.events TO ${role}`);
+  await client.query(`GRANT SELECT (runtime_scope, org_id, run_id, last_seq)
+    ON runtime_observability.run_log_cursors TO ${role}`);
+  await client.query(
+    `GRANT EXECUTE ON FUNCTION runtime_observability.fetch_receipt(text,text,text,uuid) TO ${role}`,
+  );
+}
+
+export async function hasRuntimeEventReaderGrant(
+  client: PostgresSchedulerQueryClient,
+  readerRole: string,
+  runtimeScope: string,
+): Promise<boolean> {
+  if (!readerRole || !/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/.test(readerRole)) {
+    throw new RuntimeEventInputError(
+      'Invalid provisioned runtime event reader role.',
+    );
+  }
+  const scope = requiredScope(runtimeScope);
+  const result = await client.query<{ ready: boolean }>(
+    `SELECT coalesce(roles.rolcanlogin AND NOT roles.rolsuper AND NOT roles.rolbypassrls
+      AND has_schema_privilege(roles.oid, 'runtime_observability', 'USAGE')
+      AND has_column_privilege(roles.oid, 'runtime_observability.events', 'event_id', 'SELECT')
+      AND has_column_privilege(roles.oid, 'runtime_observability.events', 'log_seq', 'SELECT')
+      AND has_column_privilege(roles.oid, 'runtime_observability.events', 'log_body', 'SELECT')
+      AND NOT has_column_privilege(roles.oid, 'runtime_observability.events', 'receipt_key', 'SELECT')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.events', 'INSERT')
+      AND NOT has_any_column_privilege(roles.oid, 'runtime_observability.events', 'INSERT')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.events', 'UPDATE')
+      AND NOT has_any_column_privilege(roles.oid, 'runtime_observability.events', 'UPDATE')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.events', 'DELETE')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.events', 'TRUNCATE')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.events', 'REFERENCES')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.events', 'TRIGGER')
+      AND has_column_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'runtime_scope', 'SELECT')
+      AND has_column_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'org_id', 'SELECT')
+      AND has_column_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'run_id', 'SELECT')
+      AND has_column_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'last_seq', 'SELECT')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'INSERT')
+      AND NOT has_any_column_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'INSERT')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'UPDATE')
+      AND NOT has_any_column_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'UPDATE')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'DELETE')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'TRUNCATE')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'REFERENCES')
+      AND NOT has_table_privilege(roles.oid, 'runtime_observability.run_log_cursors', 'TRIGGER')
+      AND NOT has_schema_privilege(roles.oid, $2, 'USAGE')
+      AND NOT has_schema_privilege(roles.oid, $2, 'CREATE')
+      AND NOT EXISTS (SELECT 1 FROM pg_auth_members AS membership
+        WHERE pg_has_role(roles.oid, membership.roleid, 'MEMBER'))
+      AND NOT EXISTS (SELECT 1 FROM pg_class AS events
+        JOIN pg_namespace AS event_schema ON event_schema.oid = events.relnamespace
+        WHERE event_schema.nspname = 'runtime_observability'
+          AND events.relname = 'events'
+          AND pg_has_role(roles.oid, events.relowner, 'USAGE'))
+      AND NOT EXISTS (SELECT 1 FROM pg_class AS log_cursors
+        JOIN pg_namespace AS event_schema ON event_schema.oid = log_cursors.relnamespace
+        WHERE event_schema.nspname = 'runtime_observability'
+          AND log_cursors.relname = 'run_log_cursors'
+          AND pg_has_role(roles.oid, log_cursors.relowner, 'USAGE'))
+      AND (SELECT relrowsecurity FROM pg_class
+            WHERE oid = 'runtime_observability.events'::regclass)
+      AND (SELECT relrowsecurity FROM pg_class
+            WHERE oid = 'runtime_observability.run_log_cursors'::regclass)
+      AND NOT EXISTS (SELECT 1 FROM pg_class AS scoped_relation
+        JOIN pg_namespace AS scoped_schema ON scoped_schema.oid = scoped_relation.relnamespace
+        WHERE scoped_schema.nspname = $2
+          AND scoped_relation.relkind IN ('r', 'p', 'v', 'm', 'f')
+          AND (has_table_privilege(roles.oid, scoped_relation.oid, 'SELECT')
+            OR has_any_column_privilege(roles.oid, scoped_relation.oid, 'SELECT')))
+      AND NOT pg_has_role(roles.oid,
+        (SELECT receipt_function.proowner FROM pg_proc AS receipt_function
+          WHERE receipt_function.oid = 'runtime_observability.fetch_receipt(text,text,text,uuid)'::regprocedure),
+        'USAGE')
+      AND has_function_privilege(roles.oid, 'runtime_observability.fetch_receipt(text,text,text,uuid)', 'EXECUTE'), false) AS ready
+      FROM pg_roles AS roles WHERE roles.rolname = $1`,
+    [readerRole, scope],
+  );
+  return result.rows[0]?.ready === true;
+}
+
+/**
+ * Triggers are attached to each scheduler namespace by the explicit migration.
+ * Search writes are atomic with the already-durable outbox/receipt write. A
+ * trigger failure is loud so no authoritative write can silently lose its
+ * corresponding search history after enablement.
+ */
+export async function attachRuntimeEventSearchTriggers(
+  client: PostgresSchedulerQueryClient,
+  runtimeScope: string,
+): Promise<void> {
+  const scope = requiredScope(runtimeScope);
+  const schema = quoteIdent(scope);
+  await client.query(`
+    CREATE OR REPLACE FUNCTION ${schema}.search_receipt_event() RETURNS trigger
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog AS $function$
+    DECLARE play text; ref uuid;
+    BEGIN
+      IF NEW.status NOT IN ('completed', 'failed', 'skipped') THEN RETURN NEW; END IF;
+      IF TG_OP = 'UPDATE' THEN
+        IF NEW.status IS NOT DISTINCT FROM OLD.status
+          AND NEW.output_json IS NOT DISTINCT FROM OLD.output_json
+          AND NEW.output_ref IS NOT DISTINCT FROM OLD.output_ref
+          AND NEW.error IS NOT DISTINCT FROM OLD.error
+        THEN RETURN NEW; END IF;
+      END IF;
+      IF NEW.run_id IS NULL OR NEW.org_id IS NULL THEN
+        RAISE EXCEPTION 'Terminal receipt search projection requires run and organization';
+      END IF;
+      SELECT play_name INTO play FROM ${schema}.runs
+       WHERE run_id = NEW.run_id AND org_id = NEW.org_id;
+      IF play IS NULL THEN
+        RAISE EXCEPTION 'Terminal receipt search projection has no matching run';
+      END IF;
+      ref := gen_random_uuid();
+      INSERT INTO runtime_observability.events (
+        runtime_scope, org_id, event_id, occurred_at, run_id, play_name,
+        kind, receipt_ref, receipt_key, search_doc
+      ) VALUES (
+        ${quoteLiteral(scope)}, NEW.org_id, 'receipt:' || ref::text,
+        NEW.updated_at, NEW.run_id, play, 'receipt.' || NEW.status,
+        ref, NEW.k, jsonb_strip_nulls(jsonb_build_object(
+          'kind', 'receipt.' || NEW.status, 'status', NEW.status,
+          'source', 'receipt', 'producerAttempt', NEW.lease_owner_attempt
+        ))
+      );
+      RETURN NEW;
+    END
+    $function$
+  `);
+  await client.query(`DO $create$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = '${schema}.receipts'::regclass
+      AND tgname = 'runtime_receipt_event_v1') THEN
+      CREATE TRIGGER runtime_receipt_event_v1 AFTER INSERT OR UPDATE ON ${schema}.receipts
+        FOR EACH ROW EXECUTE FUNCTION ${schema}.search_receipt_event();
+    END IF;
+  END $create$`);
+  await client.query(`
+    CREATE OR REPLACE FUNCTION ${schema}.search_outbox_event() RETURNS trigger
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog AS $function$
+    DECLARE run_org text; play text; item jsonb; line jsonb; event_batch jsonb;
+            ordinal bigint; line_ordinal bigint; kind text; at_time timestamptz;
+            doc jsonb; line_doc jsonb; line_context jsonb;
+            eid text; existing_digest text; digest text; assigned_seq bigint;
+            log_channel text; log_position bigint; matched_event_id text; matched_doc jsonb;
+            legacy_position_prefix text; log_alias jsonb; envelope_attempt jsonb;
+            line_count bigint; fresh_event_ids text[] := ARRAY[]::text[];
+            recent_log_keys jsonb := '{}'::jsonb; dedupe_key text;
+            terminal_overlap_counts jsonb := '{}'::jsonb;
+            recent_log_keys_loaded boolean := false;
+    BEGIN
+      -- Serialize log ordering without taking scheduler Run/attempt row locks.
+      -- Completion writers can own an attempt before updating its Run.
+      PERFORM pg_advisory_xact_lock(hashtext(${quoteLiteral(scope)}), hashtext(NEW.run_id));
+      SELECT org_id, play_name INTO run_org, play FROM ${schema}.runs WHERE run_id = NEW.run_id;
+      IF run_org IS NULL OR play IS NULL THEN
+        RAISE EXCEPTION 'Outbox search projection has no matching run';
+      END IF;
+      IF NEW.event_type = 'run.events' THEN
+        event_batch := NEW.payload_json->'events';
+        IF jsonb_typeof(event_batch) IS DISTINCT FROM 'array' THEN
+          RAISE EXCEPTION 'Search projection requires run.events array';
+        END IF;
+        IF jsonb_array_length(event_batch) = 0 THEN
+          RAISE EXCEPTION 'Search projection requires nonempty run.events array';
+        END IF;
+      ELSIF NEW.event_type IN ('run.completed', 'run.failed')
+        AND NEW.payload_json ? 'terminalProgressEvents' THEN
+        event_batch := NEW.payload_json->'terminalProgressEvents';
+        IF jsonb_typeof(event_batch) IS DISTINCT FROM 'array' THEN
+          RAISE EXCEPTION 'Search projection requires terminalProgressEvents array';
+        END IF;
+      END IF;
+      -- Ordinary terminal SQL already binds the attempt in its counter
+      -- segment; compact carriers also name it at the top level.
+      envelope_attempt := coalesce(NULLIF(NEW.payload_json->'producerAttempt', 'null'::jsonb),
+        NEW.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 NEW.event_type IN ('run.completed', 'run.failed')
+        AND NEW.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', NEW.run_id, 'source', 'terminal',
+            'producerAttempt', envelope_attempt, 'channelOffset', 0,
+            'lines', NEW.payload_json->'terminalLogLines',
+            'lineContexts', NEW.payload_json->'terminalLogContexts'
+          ))
+        );
+      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
+          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')
+              AND left(event.event_id, length('log:' || NEW.run_id || ':' || (event.search_doc->>'producerAttempt') || ':')) =
+                'log:' || NEW.run_id || ':' || (event.search_doc->>'producerAttempt') || ':'
+              AND substring(event.event_id FROM length('log:' || NEW.run_id || ':' || (event.search_doc->>'producerAttempt') || ':') + 1) ~ '^[0-9]{1,12}$'
+              THEN jsonb_build_object('logPositions', jsonb_build_object(
+                CASE WHEN event.search_doc->>'source' = 'coordinator' THEN 'replay' ELSE 'worker' END,
+                substring(event.event_id FROM length('log:' || NEW.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 = NEW.run_id AND event.kind = 'log.appended'
+             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;
+        FOR item, ordinal IN SELECT value, ordinality FROM jsonb_array_elements(event_batch) WITH ORDINALITY LOOP
+          IF jsonb_typeof(item) IS DISTINCT FROM 'object'
+            OR item->>'runId' IS DISTINCT FROM NEW.run_id THEN
+            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'
+          ) THEN
+            kind := 'runtime.event';
+          END IF;
+          at_time := CASE WHEN (item->>'occurredAt') ~ '^[0-9]{12,14}$'
+            THEN to_timestamp((item->>'occurredAt')::double precision / 1000)
+            ELSE NEW.created_at END;
+          doc := jsonb_strip_nulls(jsonb_build_object(
+            'kind', kind, 'source', left(item->>'source', 64),
+            'producerAttempt', CASE WHEN (item->>'producerAttempt') ~ '^[0-9]{1,6}$'
+              THEN CASE WHEN (item->>'producerAttempt')::integer > 0
+                THEN (item->>'producerAttempt')::integer END END,
+            'stepId', left(coalesce(item->>'stepId', item->'observation'->>'stepId'), 256),
+            'stepKind', left(item->>'kind', 64),
+            'status', left(coalesce(item->>'status', item->'observation'->'state'->>'kind'), 64),
+            'datasetId', left(item->>'datasetId', 256),
+            'phase', left(item->>'phase', 64),
+            'provider', CASE WHEN item->'observation'->'target'->>'kind' = 'provider'
+              THEN left(item->'observation'->'target'->>'provider', 64) END,
+            '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
+            RAISE EXCEPTION 'Search projection requires log.appended lines';
+          END IF;
+          IF kind = 'log.appended' 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
+            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';
+              END IF;
+              IF (item->>'source' IS DISTINCT FROM 'coordinator')
+                AND NOT coalesce((item->>'channelOffset') ~ '^[0-9]{1,12}$', false) THEN
+                IF NOT recent_log_keys_loaded THEN
+                  SELECT coalesce(jsonb_object_agg(recent.dedupe_key, true), '{}'::jsonb)
+                    INTO recent_log_keys
+                    FROM (
+                      SELECT 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 = NEW.run_id AND event.kind = 'log.appended'
+                         AND event.log_seq IS NOT NULL AND event.log_body IS NOT NULL
+                       ORDER BY event.log_seq DESC
+                       LIMIT 256
+                    ) AS recent;
+                  recent_log_keys_loaded := true;
+                END IF;
+                dedupe_key := encode(
+                  sha256(convert_to(btrim(line #>> '{}'), 'UTF8')), 'hex'
+                );
+                IF recent_log_keys ? dedupe_key THEN
+                  CONTINUE;
+                END IF;
+                recent_log_keys := recent_log_keys || jsonb_build_object(dedupe_key, true);
+              END IF;
+              line_context := NULL;
+              IF item ? 'lineContexts' THEN
+                line_context := item->'lineContexts'->((line_ordinal - 1)::int);
+                IF jsonb_typeof(line_context) = 'null' THEN
+                  line_context := NULL;
+                ELSIF jsonb_typeof(line_context) IS DISTINCT FROM 'object' THEN
+                  RAISE EXCEPTION 'Search projection log context must be an object';
+                ELSIF (SELECT count(*) FROM jsonb_object_keys(line_context)) > 8
+                  -- jsonb::text adds at most one formatting space per key
+                  -- separator; leave that small allowance above the compact
+                  -- 2 KiB runtime JSON encoding limit.
+                  OR octet_length(line_context::text) > 2064 THEN
+                  RAISE EXCEPTION 'Search projection log context exceeds its object limits';
+                END IF;
+                IF line_context IS NOT NULL AND EXISTS (
+                  SELECT 1 FROM jsonb_each(line_context) AS field(key, value)
+                   WHERE field.key !~ '^[A-Za-z_][A-Za-z0-9_]{0,63}$'
+                     OR field.key IN ('__proto__', 'constructor', 'prototype')
+                     OR jsonb_typeof(field.value) NOT IN ('string', 'number', 'boolean')
+                     OR (jsonb_typeof(field.value) = 'string'
+                         AND octet_length(field.value #>> '{}') > 256)
+                     OR (jsonb_typeof(field.value) = 'number'
+                         AND octet_length(field.value #>> '{}') > 32)
+                ) THEN
+                  RAISE EXCEPTION 'Search projection log context has an unsupported key or value';
+                END IF;
+              END IF;
+              line_doc := CASE WHEN line_context IS NULL THEN doc
+                ELSE doc || jsonb_build_object('context', line_context) END;
+              eid := CASE WHEN (item->>'channelOffset') ~ '^[0-9]{1,12}$'
+                AND (item->>'producerAttempt') ~ '^[0-9]{1,6}$'
+                THEN 'log:' || NEW.run_id || ':' || (item->>'producerAttempt') || ':' ||
+                     ((item->>'channelOffset')::bigint + line_ordinal - 1)::text
+                ELSE NEW.event_id || ':' || ordinal || ':' || line_ordinal END;
+              digest := CASE WHEN line_context IS NULL
+                THEN encode(sha256(convert_to(line #>> '{}', 'UTF8')), 'hex')
+                ELSE encode(sha256(convert_to(jsonb_build_array(line #>> '{}', line_context)::text, 'UTF8')), 'hex') END;
+              IF (item->>'channelOffset') ~ '^[0-9]{1,12}$'
+                AND (item->>'producerAttempt') ~ '^[1-9][0-9]{0,5}$' THEN
+                -- These transports retain different buffers. Their offsets
+                -- are immutable within a channel, never interchangeable.
+                log_channel := CASE item->>'source'
+                  WHEN 'coordinator' THEN 'replay' WHEN 'terminal' THEN 'envelope'
+                  ELSE 'worker' END;
+                log_position := (item->>'channelOffset')::bigint + line_ordinal - 1;
+                legacy_position_prefix := 'log:' || NEW.run_id || ':' || (item->>'producerAttempt') || ':';
+                eid := CASE WHEN log_channel = 'worker' THEN legacy_position_prefix
+                  ELSE 'log-' || log_channel || ':' || NEW.run_id || ':' || (item->>'producerAttempt') || ':' END
+                  || log_position::text;
+                -- Older coordinator replays used the worker-shaped primary
+                -- key. Do not overwrite it when a delayed worker owns a
+                -- different line at that number; aliases remain authoritative.
+                IF log_channel = 'worker' AND EXISTS (
+                  SELECT 1 FROM runtime_observability.events
+                   WHERE runtime_scope = ${quoteLiteral(scope)} AND org_id = run_org AND event_id = eid
+                     AND search_doc->>'source' = 'coordinator'
+                     AND NOT (coalesce(search_doc->'logPositions', '{}'::jsonb) ? 'worker')
+                ) THEN
+                  eid := 'log-worker:' || NEW.run_id || ':' || (item->>'producerAttempt') || ':' || log_position::text;
+                END IF;
+                log_alias := jsonb_build_object('producerAttempt', (item->>'producerAttempt')::integer,
+                  'logPositions', jsonb_build_object(log_channel, log_position));
+                matched_event_id := NULL;
+                -- A channel position names one canonical occurrence. Sorting
+                -- here makes cached plans scan the primary key on a miss.
+                SELECT event.event_id, event.source_digest, event.search_doc
+                  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 = NEW.run_id AND event.kind = 'log.appended'
+                   AND event.search_doc @> log_alias;
+                IF matched_event_id IS NOT NULL THEN
+                  IF existing_digest IS DISTINCT FROM digest THEN
+                    RAISE EXCEPTION 'Positional log event identity changed its content';
+                  END IF;
+                  CONTINUE;
+                END IF;
+                -- Bind one equal occurrence from another channel. Aliases
+                -- are checked first, so retries cannot consume another copy.
+                -- Full digests include context; repeated text is not a set.
+                SELECT event.event_id, event.search_doc
+                  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 = NEW.run_id AND event.kind = 'log.appended'
+                   AND event.search_doc @> jsonb_build_object(
+                     'producerAttempt', (item->>'producerAttempt')::integer, 'logContentDigest', digest)
+                   AND event.source_digest = digest
+                   AND NOT (coalesce(event.search_doc->'logPositions', '{}'::jsonb) ? log_channel)
+                   AND (event.search_doc ? 'logPositions' OR log_channel <>
+                     CASE WHEN event.search_doc->>'source' = 'coordinator' THEN 'replay' ELSE 'worker' END)
+                 ORDER BY event.log_seq NULLS LAST, event.event_id LIMIT 1;
+                IF matched_event_id IS NOT NULL THEN
+                  UPDATE runtime_observability.events SET search_doc = matched_doc ||
+                    jsonb_build_object('logContentDigest', digest, 'logPositions',
+                      coalesce(matched_doc->'logPositions', '{}'::jsonb) || jsonb_build_object(log_channel, log_position))
+                   WHERE runtime_scope = ${quoteLiteral(scope)} AND org_id = run_org AND event_id = matched_event_id;
+                  CONTINUE;
+                END IF;
+                line_doc := line_doc || log_alias || jsonb_build_object('logContentDigest', digest);
+              END IF;
+              INSERT INTO runtime_observability.events (
+                runtime_scope, org_id, event_id, occurred_at, run_id, play_name,
+                kind, level, message, log_body, source_digest, search_doc
+              ) VALUES (
+                ${quoteLiteral(scope)}, run_org, eid, at_time, NEW.run_id, play,
+                'log.appended', NULL, left(line #>> '{}', 2048), line #>> '{}', digest, line_doc
+              ) ON CONFLICT DO NOTHING;
+              IF FOUND THEN
+                fresh_event_ids := array_append(fresh_event_ids, eid);
+              ELSE
+                SELECT source_digest INTO existing_digest FROM runtime_observability.events
+                 WHERE runtime_scope = ${quoteLiteral(scope)} AND org_id = run_org
+                   AND event_id = eid;
+                IF existing_digest IS DISTINCT FROM digest THEN
+                  RAISE EXCEPTION 'Positional log event identity changed its content';
+                END IF;
+              END IF;
+            END LOOP;
+          ELSE
+            INSERT INTO runtime_observability.events (
+              runtime_scope, org_id, event_id, occurred_at, run_id, play_name,
+              kind, search_doc
+            ) VALUES (
+              ${quoteLiteral(scope)}, run_org, NEW.event_id || ':' || ordinal,
+              at_time, NEW.run_id, play, kind, doc
+            );
+          END IF;
+        END LOOP;
+      END IF;
+      IF NEW.event_type IN (
+        'run.created', 'run.started', 'run.waiting', 'run.resumed',
+        'run.completed', 'run.failed', 'run.cancelled'
+      ) AND NOT (NEW.event_type IN ('run.waiting', 'run.resumed')
+                 AND NEW.payload_json->>'kind' = 'detached_runner') THEN
+        INSERT INTO runtime_observability.events (
+          runtime_scope, org_id, event_id, occurred_at, run_id, play_name,
+          kind, search_doc
+        ) VALUES (
+          ${quoteLiteral(scope)}, run_org, NEW.event_id, NEW.created_at,
+          NEW.run_id, play, NEW.event_type, jsonb_build_object('kind', NEW.event_type, 'source', 'system')
+        );
+        -- 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.
+        IF NEW.event_type IN ('run.completed', 'run.failed')
+          AND NEW.payload_json ? 'terminalLogContexts'
+          AND NOT (NEW.payload_json ? 'terminalLogLines') THEN
+          RAISE EXCEPTION 'Search projection requires terminalLogLines for terminalLogContexts';
+        END IF;
+        IF NEW.event_type IN ('run.completed', 'run.failed')
+          AND NEW.payload_json ? 'terminalLogLines'
+          AND NOT coalesce((envelope_attempt #>> '{}') ~ '^[1-9][0-9]{0,5}$', false) THEN
+          IF jsonb_typeof(NEW.payload_json->'terminalLogLines') IS DISTINCT FROM 'array' THEN
+            RAISE EXCEPTION 'Search projection requires terminalLogLines array';
+          END IF;
+          IF NEW.payload_json ? 'terminalLogContexts'
+            AND (jsonb_typeof(NEW.payload_json->'terminalLogContexts') IS DISTINCT FROM 'array'
+                 OR jsonb_array_length(NEW.payload_json->'terminalLogContexts') <> jsonb_array_length(NEW.payload_json->'terminalLogLines')) THEN
+            RAISE EXCEPTION 'Search projection requires terminalLogContexts aligned to terminalLogLines';
+          END IF;
+          -- Count matching bodies already projected, including progress lines
+          -- inserted earlier in this trigger (which do not have log_seq yet).
+          -- Consume one count per overlap so repeated identical log lines in
+          -- the terminal tail remain distinct events after the overlap ends.
+          SELECT coalesce(
+            jsonb_object_agg(counted.dedupe_key, to_jsonb(counted.occurrences)),
+            '{}'::jsonb
+          )
+            INTO terminal_overlap_counts
+            FROM (
+              SELECT candidate.dedupe_key, count(*) AS occurrences
+                FROM (
+                  SELECT encode(sha256(convert_to(btrim(recent.log_body), 'UTF8')), 'hex') AS dedupe_key
+                    FROM (
+                      SELECT event.log_body
+                        FROM runtime_observability.events AS event
+                       WHERE event.runtime_scope = ${quoteLiteral(scope)}
+                         AND event.org_id = run_org AND event.run_id = NEW.run_id
+                         AND event.kind = 'log.appended'
+                         AND event.log_seq IS NOT NULL AND event.log_body IS NOT NULL
+                       ORDER BY event.log_seq DESC
+                       LIMIT 256
+                    ) AS recent
+                  UNION ALL
+                  SELECT encode(sha256(convert_to(btrim(event.log_body), 'UTF8')), 'hex')
+                    FROM runtime_observability.events AS event
+                   WHERE event.runtime_scope = ${quoteLiteral(scope)}
+                     AND event.org_id = run_org AND event.run_id = NEW.run_id
+                     AND event.kind = 'log.appended' AND event.log_body IS NOT NULL
+                     AND event.event_id = ANY(fresh_event_ids)
+                ) AS candidate
+               GROUP BY candidate.dedupe_key
+            ) AS counted;
+          FOR line, line_ordinal IN
+            SELECT value, ordinality
+              FROM jsonb_array_elements(NEW.payload_json->'terminalLogLines') WITH ORDINALITY
+          LOOP
+            IF jsonb_typeof(line) IS DISTINCT FROM 'string' THEN
+              RAISE EXCEPTION 'Search projection requires terminal log strings';
+            END IF;
+            dedupe_key := encode(
+              sha256(convert_to(btrim(line #>> '{}'), 'UTF8')), 'hex'
+            );
+            IF coalesce((terminal_overlap_counts->>dedupe_key)::bigint, 0) > 0 THEN
+              terminal_overlap_counts := terminal_overlap_counts || jsonb_build_object(
+                dedupe_key,
+                (terminal_overlap_counts->>dedupe_key)::bigint - 1
+              );
+              CONTINUE;
+            END IF;
+            line_context := NULL;
+            IF NEW.payload_json ? 'terminalLogContexts' THEN
+              line_context := NEW.payload_json->'terminalLogContexts'->((line_ordinal - 1)::int);
+              IF jsonb_typeof(line_context) = 'null' THEN
+                line_context := NULL;
+              ELSIF jsonb_typeof(line_context) IS DISTINCT FROM 'object' THEN
+                RAISE EXCEPTION 'Search projection terminal log context must be an object';
+              ELSIF (SELECT count(*) FROM jsonb_object_keys(line_context)) > 8
+                -- Allow jsonb::text's bounded separator spaces above the
+                -- runtime's compact 2 KiB context limit.
+                OR octet_length(line_context::text) > 2064 THEN
+                RAISE EXCEPTION 'Search projection terminal log context exceeds its object limits';
+              END IF;
+              IF line_context IS NOT NULL AND EXISTS (
+                SELECT 1 FROM jsonb_each(line_context) AS field(key, value)
+                 WHERE field.key !~ '^[A-Za-z_][A-Za-z0-9_]{0,63}$'
+                   OR field.key IN ('__proto__', 'constructor', 'prototype')
+                   OR jsonb_typeof(field.value) NOT IN ('string', 'number', 'boolean')
+                   OR (jsonb_typeof(field.value) = 'string'
+                       AND octet_length(field.value #>> '{}') > 256)
+                   OR (jsonb_typeof(field.value) = 'number'
+                       AND octet_length(field.value #>> '{}') > 32)
+              ) THEN
+                RAISE EXCEPTION 'Search projection terminal log context has an unsupported key or value';
+              END IF;
+            END IF;
+            line_doc := jsonb_build_object('kind', 'log.appended', 'source', 'terminal');
+            IF line_context IS NOT NULL THEN
+              line_doc := line_doc || jsonb_build_object('context', line_context);
+            END IF;
+            INSERT INTO runtime_observability.events (
+              runtime_scope, org_id, event_id, occurred_at, run_id, play_name,
+              kind, level, message, log_body, source_digest, search_doc
+            ) VALUES (
+              ${quoteLiteral(scope)}, run_org, NEW.event_id || ':log:' || line_ordinal,
+              NEW.created_at, NEW.run_id, play, 'log.appended', NULL,
+              left(regexp_replace(line #>> '{}',
+                '^' || chr(1) || 'prov:[^' || chr(1) || ']*' || chr(1), ''), 2048),
+              line #>> '{}',
+              CASE WHEN line_context IS NULL
+                THEN encode(sha256(convert_to(line #>> '{}', 'UTF8')), 'hex')
+                ELSE encode(sha256(convert_to(jsonb_build_array(line #>> '{}', line_context)::text, 'UTF8')), 'hex') END,
+              line_doc
+            ) ON CONFLICT DO NOTHING;
+            IF FOUND THEN
+              fresh_event_ids := array_append(
+                fresh_event_ids,
+                NEW.event_id || ':log:' || line_ordinal
+              );
+            END IF;
+          END LOOP;
+        END IF;
+      END IF;
+      line_count := cardinality(fresh_event_ids);
+      IF line_count > 0 THEN
+        INSERT INTO runtime_observability.run_log_cursors (
+          runtime_scope, org_id, run_id, last_seq
+        ) VALUES (${quoteLiteral(scope)}, run_org, NEW.run_id, line_count)
+        ON CONFLICT (runtime_scope, org_id, run_id)
+        DO UPDATE SET last_seq = runtime_observability.run_log_cursors.last_seq + EXCLUDED.last_seq,
+                      updated_at = clock_timestamp()
+        RETURNING last_seq INTO assigned_seq;
+        UPDATE runtime_observability.events AS event
+           SET log_seq = assigned_seq - line_count + fresh.ordinality
+          FROM unnest(fresh_event_ids) WITH ORDINALITY AS fresh(event_id, ordinality)
+         WHERE event.runtime_scope = ${quoteLiteral(scope)}
+           AND event.org_id = run_org
+           AND event.event_id = fresh.event_id;
+      END IF;
+      RETURN NEW;
+    END
+    $function$
+  `);
+  await client.query(
+    `COMMENT ON FUNCTION ${schema}.search_outbox_event() IS ${quoteLiteral(RUNTIME_EVENT_SEARCH_OUTBOX_PROJECTION_MARKER)}`,
+  );
+  await client.query(`DO $create$ BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = '${schema}.outbox'::regclass
+      AND tgname = 'runtime_outbox_event_v1') THEN
+      CREATE TRIGGER runtime_outbox_event_v1 AFTER INSERT ON ${schema}.outbox
+        FOR EACH ROW EXECUTE FUNCTION ${schema}.search_outbox_event();
+    END IF;
+  END $create$`);
+}
+
+export async function hasRuntimeEventSearchShape(
+  client: PostgresSchedulerQueryClient,
+  runtimeScope: string,
+): Promise<boolean> {
+  const schema = quoteIdent(requiredScope(runtimeScope));
+  const result = await client.query<{ ready: boolean }>(
+    `SELECT to_regclass('runtime_observability.events') IS NOT NULL
+      AND to_regclass('runtime_observability.run_log_cursors') IS NOT NULL
+      AND EXISTS (SELECT 1 FROM pg_attribute
+        WHERE attrelid = to_regclass('runtime_observability.events')
+          AND attname = 'log_seq' AND NOT attisdropped)
+      AND EXISTS (SELECT 1 FROM pg_attribute
+        WHERE attrelid = to_regclass('runtime_observability.events')
+          AND attname = 'log_body' AND NOT attisdropped)
+      AND EXISTS (SELECT 1 FROM pg_class
+        WHERE oid = to_regclass('runtime_observability.events') AND relrowsecurity)
+      AND EXISTS (SELECT 1 FROM pg_class
+        WHERE oid = to_regclass('runtime_observability.run_log_cursors') AND relrowsecurity)
+      AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = '${schema}.receipts'::regclass
+        AND tgname = 'runtime_receipt_event_v1' AND NOT tgisinternal)
+      AND EXISTS (SELECT 1 FROM pg_trigger WHERE tgrelid = '${schema}.outbox'::regclass
+        AND tgname = 'runtime_outbox_event_v1' AND NOT tgisinternal)
+      AND EXISTS (SELECT 1 FROM pg_proc AS proc
+        JOIN pg_namespace AS namespace ON namespace.oid = proc.pronamespace
+        WHERE namespace.nspname = $1 AND proc.proname = 'search_outbox_event'
+          AND proc.pronargs = 0
+          AND obj_description(proc.oid, 'pg_proc') = ${quoteLiteral(RUNTIME_EVENT_SEARCH_OUTBOX_PROJECTION_MARKER)})
+      AS ready`,
+    [runtimeScope],
+  );
+  return result.rows[0]?.ready === true;
+}
+
+/** One bounded operator-owned TTL pass. Never called by a customer request. */
+export async function pruneRuntimeEvents(
+  client: PostgresSchedulerQueryClient,
+  input: { before: Date; limit: number },
+): Promise<number> {
+  const before = input.before.getTime();
+  if (!Number.isFinite(before) || before > Date.now() - 60 * 60 * 1000) {
+    throw new RuntimeEventInputError(
+      'Runtime event cleanup cutoff must be at least one hour old.',
+    );
+  }
+  if (
+    !Number.isSafeInteger(input.limit) ||
+    input.limit < 1 ||
+    input.limit > 5_000
+  ) {
+    throw new RuntimeEventInputError(
+      'Runtime event cleanup limit must be between 1 and 5000.',
+    );
+  }
+  const result = await client.query<{ event_id: string }>(
+    `WITH candidates AS (
+       SELECT ctid FROM runtime_observability.events
+        WHERE ingested_at < $1::timestamptz
+        ORDER BY ingested_at, event_id
+        LIMIT $2::integer FOR UPDATE SKIP LOCKED
+     )
+     DELETE FROM runtime_observability.events AS event USING candidates
+      WHERE event.ctid = candidates.ctid
+     RETURNING event.event_id`,
+    [input.before.toISOString(), input.limit],
+  );
+  // Keep the small per-run high-water marks after log bodies expire. A delayed
+  // accepted batch must not restart that run at sequence 1 and break cursors.
+  return result.rows.length;
+}
+
+/** Read-only bounded estimate for the same operator TTL cutoff. */
+export async function inspectRuntimeEventRetention(
+  client: PostgresSchedulerQueryClient,
+  input: { before: Date },
+): Promise<{
+  oldestIngestedAt: string | null;
+  expiredCountAtLeast: number;
+  countCapped: boolean;
+}> {
+  const before = input.before.getTime();
+  if (!Number.isFinite(before))
+    throw new RuntimeEventInputError('Invalid runtime event retention cutoff.');
+  const result = await client.query<{
+    oldest: Date | string | null;
+    count: number | string;
+  }>(
+    `WITH oldest AS (
+       SELECT ingested_at FROM runtime_observability.events
+        ORDER BY ingested_at, event_id LIMIT 1
+     ), bounded AS (
+       SELECT 1 FROM runtime_observability.events
+        WHERE ingested_at < $1::timestamptz
+        ORDER BY ingested_at, event_id LIMIT 10001
+     )
+     SELECT (SELECT ingested_at FROM oldest) AS oldest,
+            (SELECT count(*) FROM bounded) AS count`,
+    [input.before.toISOString()],
+  );
+  const count = Number(result.rows[0]?.count ?? 0);
+  return {
+    oldestIngestedAt: result.rows[0]?.oldest
+      ? iso(result.rows[0].oldest)
+      : null,
+    expiredCountAtLeast: Math.min(count, 10_000),
+    countCapped: count > 10_000,
+  };
+}