deepline 0.3.275 → 0.3.277

package/dist/bundling-sources/sdk/src/client.ts

@@ -841,7 +841,7 @@ export type RunsLogsResult = {
   logsTruncated?: boolean;
 };
 
-/** Read existing events in the authenticated organization/runtime scope, newest first by occurrence time and event ID. See the complete catalog and field contract in `deepline runs logs --help`. */
+/** Search existing events in your organization, newest first. Discover kinds and filters with `deepline runs logs --help`. */
 export type RunsEventSearchOptions = {
   /** Inclusive UTC timestamp; defaults to one hour before the request. */
   since?: string;
@@ -853,9 +853,9 @@ export type RunsEventSearchOptions = {
   playName?: string;
   /** Exact dotted event kind, such as `step.failed`. The catalog is discoverable with `runs logs --help`; future stored kinds are accepted too. */
   kind?: string;
-  /** Equality joined with `&&`, at most eight predicates and 512 bytes. Fields: orgId, runId, playName, runtimeScope, producerAttempt, kind, status, source, stepId, stepKind, datasetId, phase, provider, operation and scalar `context.<key>`. Missing fields do not match; status is not inferred from kind. No body, message, level, nested payload, range or OR search. HTTP `jsonpath`, CLI `--where`. */
+  /** JSONPath equality joined with `&&`, at most eight predicates and 512 bytes. See `runs logs --help` for fields and examples. Missing fields do not match; status is not inferred from kind. HTTP `jsonpath`, CLI `--where`. */
   jsonpath?: string;
-  /** Add stored canonical `eventPayload` and, for receipt matches, retained `payload`. At most ten events and 16 MiB; unavailable receipts return null. HTTP `payloads=true`, CLI `--payloads`. Does not execute tools. */
+  /** Include available `eventPayload` details and receipt `payload` results; maximum ten events and 16 MiB. HTTP `payloads=true`, CLI `--payloads`. */
   includePayloads?: boolean;
   /** Page size: default 100, maximum 200; with payloads, default and maximum ten. */
   limit?: number;
@@ -865,7 +865,7 @@ export type RunsEventSearchOptions = {
   runtime?: PlayRuntimeSelection;
 };
 
-/** One indexed observation; optional indexed fields and payloads depend on what its producer recorded. */
+/** One matching event. Optional fields and details are present only when recorded. */
 export type RunsEventSearchEntry = {
   /** Stable event identity; also breaks ties in newest-first pagination. */
   eventId: string;
@@ -877,15 +877,15 @@ export type RunsEventSearchEntry = {
   runId: string;
   /** Recorded Play name. */
   playName: string;
-  /** Exact indexed kind; canonical payloads use `type` for this dotted name. */
+  /** Exact dotted event kind, such as `step.failed`. */
   kind: string;
   /** Recorded log severity, or null; not a JSONPath filter field. */
   level: string | null;
   /** Log message preview of at most 2,048 characters, or null. Use text logs/export for the full retained line. */
   message: string | null;
-  /** Indexed identity and recorded scalar fields. SDK/API keep this nested; CLI search flattens it onto each event. Provider/operation describe typed activity observations, not every provider call. */
+  /** Recorded filter fields. SDK/API keep this nested; the CLI places these fields directly on each event. */
   searchDoc: Record<string, unknown>;
-  /** Stored canonical event details, only when payloads are requested and available. Lifecycle/activity/dataset payloads are observations, not complete tool responses or dataset rows. */
+  /** Available event details when requested with `includePayloads`; dataset events contain metadata, not dataset rows. */
   eventPayload?: Record<string, unknown>;
   /** Retained work result for a receipt match when payloads are requested; null if unavailable. Other events need not carry this field. */
   payload?: RunsEventPayload | null;
@@ -903,7 +903,7 @@ export type RunsEventSearchResult = {
   until: string;
 };
 
-/** Retained work outcome hydrated for a receipt event; not a new execution, billing receipt or guarantee of a raw HTTP response. */
+/** Saved work result returned for a receipt event. Reading it does not execute the work again. */
 export type RunsEventPayload = {
   /** Recorded terminal work outcome. */
   status: 'completed' | 'failed' | 'skipped';

package/dist/bundling-sources/sdk/src/release.ts

@@ -200,7 +200,7 @@ export const SDK_RELEASE = {
   // getters keep their established compatibility behavior.
   // 0.3.1 deprecated the legacy `deepline enrich` command in favor of Plays.
   // 0.3.90 is the first deliberately versioned SDK release for API v3.
-  version: '0.3.275',
+  version: '0.3.277',
   updateSummary:
     'Play grep now returns concise results with the matched fields and terms. Automatic CLI updates are enabled by default; use `deepline settings autoupdate off` to opt out, `deepline settings autoupdate on` to re-enable updates, or `deepline settings autoupdate pin <version>` to hold an exact release.',
   packageCapabilities: {

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

@@ -17391,6 +17391,22 @@ function runLedgerOrderSql(alias: string): string {
   return `CASE ${alias}.event_type WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runCreated} THEN 0 WHEN ${RUN_EVENT_KIND_SQL_LITERAL.runStarted} THEN 1 ELSE 2 END, ${alias}.created_at, ${alias}.event_id`;
 }
 
+/** Prioritize a terminal's causal head without skipping its predecessors. */
+function runLedgerTerminalPendingSql(
+  alias: string,
+  options?: Pick<PostgresSchedulerOptions, 'schema'>,
+): string {
+  return `EXISTS (
+    SELECT 1 FROM ${tableName('outbox', options)} AS terminal_event
+    WHERE terminal_event.event_id = 'run-terminal:' || ${alias}.run_id
+      AND terminal_event.run_id = ${alias}.run_id
+      AND terminal_event.event_type IN (${RUN_EVENT_KIND_SQL_LITERAL.runCompleted}, ${RUN_EVENT_KIND_SQL_LITERAL.runFailed}, ${RUN_EVENT_KIND_SQL_LITERAL.runCancelled})
+      AND terminal_event.delivered_at IS NULL
+      AND terminal_event.failed_at IS NULL
+      AND coalesce(terminal_event.next_attempt_at, terminal_event.created_at) <= now()
+  )`;
+}
+
 /**
  * Claim a causal prefix, preserving the v33 adapter while the additive batch
  * marker is absent. An enclosing transaction uses a savepoint so the missing
@@ -17463,16 +17479,14 @@ export async function readPendingPostgresSchedulerOutboxEvents(
         -- terminal facts. Project it first so a lifecycle backlog cannot make
         -- an accepted run invisible; per-run predecessor checks above retain
         -- strict ordering within each run.
-        -- A terminal head comes next: it is a run's last fact (one per run, so
-        -- it cannot starve anything), its predecessors are already delivered
-        -- (checked above), and it is what a caller is waiting on. Under a
-        -- lifecycle backlog, FIFO left a committed terminal queued behind other
-        -- runs' progress for seconds (live-run-observation-e2e: 4.9 s from
-        -- commit to first claim while the projector drained continuously).
+        -- A run with a pending terminal comes next, including its causal
+        -- predecessors. Giving priority only to a terminal head leaves a
+        -- finished run's earlier progress behind unrelated progress. The
+        -- predecessor checks still forbid skipping any fact within the run.
         ORDER BY
           CASE
             WHEN candidate.event_type = ${RUN_EVENT_KIND_SQL_LITERAL.runCreated} THEN 0
-            WHEN candidate.event_id LIKE 'run-terminal:%' THEN 1
+            WHEN ${runLedgerTerminalPendingSql('candidate', options)} THEN 1
             ELSE 2
           END,
           coalesce(candidate.next_attempt_at, candidate.created_at),
@@ -18892,6 +18906,7 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
   input: RunLedgerOutboxDispatchInput & { waitForRunLock?: boolean },
   options?: Pick<PostgresSchedulerOptions, 'schema'>,
 ): Promise<PostgresSchedulerOutboxProjectionResult> {
+  const dispatchStartedAtMs = Date.now();
   const leaseOwner =
     input.leaseOwner?.trim() || `run-ledger-outbox-dispatch:${randomUUID()}`;
   const events = await withClient(async (client) => {
@@ -18986,16 +19001,16 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
                   AND active.lease_owner IS NOT NULL
                   AND active.lease_expires_at > now()
               )
-            -- admission_first: admission, then a run whose head is its
-            -- terminal (its last fact; see
-            -- readPendingPostgresSchedulerOutboxEvents), then the FIFO
-            -- backlog. oldest_ready: pure age order, the anti-starvation turn.
+            -- admission_first: admission, then the causal head of a run with
+            -- a pending terminal, then FIFO progress. oldest_ready keeps its
+            -- pure age order so continuous admissions/terminals cannot starve
+            -- ordinary progress.
             ORDER BY ${
               input.headPriority === 'oldest_ready'
                 ? ''
                 : `CASE
                        WHEN head.event_type = ${RUN_EVENT_KIND_SQL_LITERAL.runCreated} THEN 0
-                       WHEN head.event_id LIKE 'run-terminal:%' THEN 1
+                       WHEN ${runLedgerTerminalPendingSql('head', options)} THEN 1
                        ELSE 2
                      END,`
             }
@@ -19035,6 +19050,10 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
     };
   }
 
+  const claimedAtMs = Date.now();
+  let authorityReadyAtMs: number | null = null;
+  let appendFinishedAtMs: number | null = null;
+  let acknowledgedAtMs: number | null = null;
   try {
     const first = events[0]!;
     const tokenAuthority = input.tokenAuthority ?? 'local_mint';
@@ -19091,6 +19110,7 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
       // The caller-owned admission deadline (see `signal` above) wins.
       ...(input.signal ? { signal: input.signal } : {}),
     };
+    authorityReadyAtMs = Date.now();
     const renewDelivery = () =>
       withClient((client) =>
         renewPostgresRunLedgerDelivery(
@@ -19155,6 +19175,7 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
         });
       }
     }
+    appendFinishedAtMs = Date.now();
     const deliveredRows = await withClient((client) =>
       markPostgresSchedulerOutboxDeliveredRows(
         client,
@@ -19162,6 +19183,7 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
         { ...options, leaseOwner },
       ),
     );
+    acknowledgedAtMs = Date.now();
     const markedDelivered = deliveredRows.length;
     if (input.onDelivered && deliveredRows.length > 0) {
       try {
@@ -19253,6 +19275,37 @@ export async function dispatchRunLedgerOutboxToLedgerBatchOnceWithClientScope(
       retrying: settlement.retrying.length,
       retryingEventIds: settlement.retrying,
     };
+  } finally {
+    const settledAtMs = Date.now();
+    const headAgeAtClaimMs = Math.max(
+      0,
+      claimedAtMs - events[0]!.createdAt.getTime(),
+    );
+    if (
+      settledAtMs - dispatchStartedAtMs >= 1_000 ||
+      headAgeAtClaimMs >= 1_000
+    ) {
+      console.info('[run-ledger-outbox.slow_delivery]', {
+        runId: events[0]!.runId,
+        headEventId: events[0]!.eventId,
+        eventCount: events.length,
+        headAgeAtClaimMs,
+        claimMs: claimedAtMs - dispatchStartedAtMs,
+        authorityMs:
+          authorityReadyAtMs === null ? null : authorityReadyAtMs - claimedAtMs,
+        appendMs:
+          appendFinishedAtMs === null || authorityReadyAtMs === null
+            ? null
+            : appendFinishedAtMs - authorityReadyAtMs,
+        acknowledgeMs:
+          acknowledgedAtMs === null || appendFinishedAtMs === null
+            ? null
+            : acknowledgedAtMs - appendFinishedAtMs,
+        continuationMs:
+          acknowledgedAtMs === null ? null : settledAtMs - acknowledgedAtMs,
+        durationMs: settledAtMs - dispatchStartedAtMs,
+      });
+    }
   }
 }
 

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

@@ -51,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-v12-scheduler-wait-logs';
+  'runtime-event-search-log-context-v13-index-first-position';
 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;
@@ -1018,7 +1018,6 @@ export async function attachRuntimeEventSearchTriggers(
             doc jsonb; line_doc jsonb; line_context jsonb;
             eid text; existing_digest text; digest text; assigned_seq bigint; terminal_progress_identity boolean;
             log_channel text; log_position bigint; matched_event_id text; matched_doc jsonb;
-            previous_plan_cache_mode text;
             legacy_position_prefix text; position_event_ids text[];
             log_alias jsonb; position_alias jsonb; envelope_attempt jsonb;
             line_count bigint; fresh_event_ids text[] := ARRAY[]::text[];
@@ -1297,23 +1296,29 @@ export async function attachRuntimeEventSearchTriggers(
                   -- A transport may already be aliased onto an event whose
                   -- primary key belongs to another channel. Find that alias
                   -- independently of content so changed bytes still fail the
-                  -- immutable-position check below. PL/pgSQL's generic plan
-                  -- underestimates large runs and scans every row in the run;
-                  -- plan this lookup with its concrete position so the scoped
-                  -- GIN index can seek directly to the alias.
-                  previous_plan_cache_mode := current_setting('plan_cache_mode');
-                  PERFORM set_config('plan_cache_mode', 'force_custom_plan', true);
+                  -- immutable-position check below. Materialize the scoped
+                  -- position lookup before applying run filters: otherwise
+                  -- the planner can choose the run-history index and inspect
+                  -- every old log for each incoming position, even with a
+                  -- custom plan. The indexed document already binds scope,
+                  -- org, run, attempt and channel position; retain the outer
+                  -- identity checks as defense in depth.
+                  WITH position_matches AS MATERIALIZED (
+                    SELECT event.event_id, event.source_digest, event.search_doc,
+                           event.runtime_scope, event.org_id, event.run_id, event.log_seq
+                      FROM runtime_observability.events AS event
+                     WHERE 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
+                  )
                   SELECT event.event_id, event.source_digest, event.search_doc
                     INTO matched_event_id, existing_digest, matched_doc
-                    FROM runtime_observability.events AS event
+                    FROM position_matches AS event
                    WHERE event.runtime_scope = ${quoteLiteral(scope)} AND event.org_id = run_org
-                     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
+                     AND event.run_id = observation.run_id
                    ORDER BY event.log_seq NULLS LAST, event.event_id
                    LIMIT 1;
-                  PERFORM set_config('plan_cache_mode', previous_plan_cache_mode, true);
                 END IF;
                 IF matched_event_id IS NOT NULL THEN
                   IF existing_digest IS DISTINCT FROM digest THEN
@@ -2015,20 +2020,22 @@ type RuntimeEventIndexExpectation = {
   opclasses?: string[];
 };
 
-const RUNTIME_EVENT_QUERY_INDEXES: RuntimeEventIndexExpectation[] = [
-  {
-    name: RUNTIME_EVENT_LOG_POSITION_INDEX,
-    method: 'gin',
-    opclasses: ['jsonb_path_ops'],
-    keys: [
-      "jsonb_set(jsonb_set(jsonb_set(jsonb_set(COALESCE(search_doc -> 'logPositions'::text, '{}'::jsonb), ARRAY['producerAttempt'::text], search_doc -> 'producerAttempt'::text, true), ARRAY['_runtimeScope:'::text || runtime_scope], 'true'::jsonb, true), ARRAY['_orgId:'::text || org_id], 'true'::jsonb, true), ARRAY['_runId:'::text || run_id], 'true'::jsonb, true)",
-    ],
-    predicate: RUNTIME_EVENT_LOG_POSITION_PREDICATE,
-    createSql: `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${RUNTIME_EVENT_LOG_POSITION_INDEX}
+const RUNTIME_EVENT_LOG_POSITION_INDEX_SPEC: RuntimeEventIndexExpectation = {
+  name: RUNTIME_EVENT_LOG_POSITION_INDEX,
+  method: 'gin',
+  opclasses: ['jsonb_path_ops'],
+  keys: [
+    "jsonb_set(jsonb_set(jsonb_set(jsonb_set(COALESCE(search_doc -> 'logPositions'::text, '{}'::jsonb), ARRAY['producerAttempt'::text], search_doc -> 'producerAttempt'::text, true), ARRAY['_runtimeScope:'::text || runtime_scope], 'true'::jsonb, true), ARRAY['_orgId:'::text || org_id], 'true'::jsonb, true), ARRAY['_runId:'::text || run_id], 'true'::jsonb, true)",
+  ],
+  predicate: RUNTIME_EVENT_LOG_POSITION_PREDICATE,
+  createSql: `CREATE INDEX CONCURRENTLY IF NOT EXISTS ${RUNTIME_EVENT_LOG_POSITION_INDEX}
       ON runtime_observability.events USING gin
         ((${RUNTIME_EVENT_LOG_POSITION_EXPRESSION}) jsonb_path_ops)
       WHERE ${RUNTIME_EVENT_LOG_POSITION_PREDICATE}`,
-  },
+};
+
+const RUNTIME_EVENT_QUERY_INDEXES: RuntimeEventIndexExpectation[] = [
+  RUNTIME_EVENT_LOG_POSITION_INDEX_SPEC,
   {
     name: RUNTIME_EVENT_LOG_DEDUPE_INDEX,
     keys: [
@@ -2062,92 +2069,126 @@ const RUNTIME_EVENT_QUERY_INDEXES: RuntimeEventIndexExpectation[] = [
   },
 ];
 
-/** Build only operator-owned indexes, concurrently and outside a transaction. */
-export async function prepareRuntimeEventQueryIndexes(
+async function hasRuntimeEventQueryIndex(
   client: PostgresSchedulerQueryClient,
-): Promise<void> {
-  for (const expected of RUNTIME_EVENT_QUERY_INDEXES) {
-    type IndexShape = {
-      valid: boolean;
-      ready: boolean;
-      is_unique: boolean;
-      table_matches: boolean;
-      key_count: number;
-      attribute_count: number;
-      method: string;
-      keys: string[];
-      opclasses: string[];
-      predicate: string | null;
-    };
-    const inspect = () =>
-      client.query<IndexShape>(
-        `SELECT index_row.indisvalid AS valid,
-                index_row.indisready AS ready,
-                index_row.indisunique AS is_unique,
-                index_row.indrelid = to_regclass('runtime_observability.events') AS table_matches,
-                index_row.indnkeyatts AS key_count,
-                index_row.indnatts AS attribute_count,
-                method.amname AS method,
-                ARRAY(
-                  SELECT pg_get_indexdef(index_row.indexrelid, key_number.position, true)
-                    FROM generate_series(1, index_row.indnkeyatts) AS key_number(position)
-                   ORDER BY key_number.position
-                ) AS keys,
-                (
-                  SELECT coalesce(json_agg(operator_class.opcname ORDER BY classes.position), '[]'::json)
-                    FROM unnest(index_row.indclass) WITH ORDINALITY AS classes(opclass_oid, position)
-                    JOIN pg_opclass AS operator_class ON operator_class.oid = classes.opclass_oid
-                ) AS opclasses,
-                pg_get_expr(index_row.indpred, index_row.indrelid) AS predicate
-           FROM pg_index AS index_row
-           JOIN pg_class AS index_class ON index_class.oid = index_row.indexrelid
-           JOIN pg_am AS method ON method.oid = index_class.relam
-          WHERE index_class.oid = to_regclass($1)`,
-        [`runtime_observability.${expected.name}`],
+  expected: RuntimeEventIndexExpectation,
+): Promise<boolean> {
+  type IndexShape = {
+    valid: boolean;
+    ready: boolean;
+    is_unique: boolean;
+    table_matches: boolean;
+    key_count: number;
+    attribute_count: number;
+    method: string;
+    keys: string[];
+    opclasses: string[];
+    predicate: string | null;
+  };
+  const inspect = () =>
+    client.query<IndexShape>(
+      `SELECT index_row.indisvalid AS valid,
+            index_row.indisready AS ready,
+            index_row.indisunique AS is_unique,
+            index_row.indrelid = to_regclass('runtime_observability.events') AS table_matches,
+            index_row.indnkeyatts AS key_count,
+            index_row.indnatts AS attribute_count,
+            method.amname AS method,
+            ARRAY(
+              SELECT pg_get_indexdef(index_row.indexrelid, key_number.position, true)
+                FROM generate_series(1, index_row.indnkeyatts) AS key_number(position)
+               ORDER BY key_number.position
+            ) AS keys,
+            (
+              SELECT coalesce(json_agg(operator_class.opcname ORDER BY classes.position), '[]'::json)
+                FROM unnest(index_row.indclass) WITH ORDINALITY AS classes(opclass_oid, position)
+                JOIN pg_opclass AS operator_class ON operator_class.oid = classes.opclass_oid
+            ) AS opclasses,
+            pg_get_expr(index_row.indpred, index_row.indrelid) AS predicate
+       FROM pg_index AS index_row
+       JOIN pg_class AS index_class ON index_class.oid = index_row.indexrelid
+       JOIN pg_am AS method ON method.oid = index_class.relam
+      WHERE index_class.oid = to_regclass($1)`,
+      [`runtime_observability.${expected.name}`],
+    );
+  const assertShape = (shape: IndexShape): void => {
+    if (!shape.valid || !shape.ready) {
+      throw new Error(
+        `Runtime event index ${expected.name} is invalid or incomplete; inspect and repair the failed build explicitly.`,
       );
-    const assertShape = (shape: IndexShape): void => {
-      if (!shape.valid || !shape.ready) {
-        throw new Error(
-          `Runtime event index ${expected.name} is invalid or incomplete; inspect and repair the failed build explicitly.`,
-        );
-      }
-      if (
-        !shape.table_matches ||
-        shape.is_unique ||
-        shape.method !== (expected.method ?? 'btree') ||
-        (expected.opclasses !== undefined &&
-          (shape.opclasses.length !== expected.opclasses.length ||
-            shape.opclasses.some(
-              (name, index) => name !== expected.opclasses![index],
-            ))) ||
-        shape.key_count !== expected.keys.length ||
-        shape.attribute_count !== expected.keys.length ||
-        shape.keys.length !== expected.keys.length ||
-        shape.keys.some(
-          (key, index) =>
-            normalizedRetentionPredicate(key) !==
-            normalizedRetentionPredicate(expected.keys[index]!),
-        ) ||
-        shape.predicate === null ||
-        normalizedQueryIndexPredicate(shape.predicate) !==
-          normalizedQueryIndexPredicate(expected.predicate)
-      ) {
-        throw new Error(
-          `Runtime event index ${expected.name} differs from its expected table, keys, method, uniqueness or predicate. Actual catalog shape: ${JSON.stringify(shape)}. Inspect and repair it explicitly.`,
-        );
-      }
-    };
-
-    const existing = (await inspect()).rows[0];
-    if (existing) assertShape(existing);
-    await client.query(expected.createSql);
-    const built = (await inspect()).rows[0];
-    if (!built) {
+    }
+    if (
+      !shape.table_matches ||
+      shape.is_unique ||
+      shape.method !== (expected.method ?? 'btree') ||
+      (expected.opclasses !== undefined &&
+        (shape.opclasses.length !== expected.opclasses.length ||
+          shape.opclasses.some(
+            (name, index) => name !== expected.opclasses![index],
+          ))) ||
+      shape.key_count !== expected.keys.length ||
+      shape.attribute_count !== expected.keys.length ||
+      shape.keys.length !== expected.keys.length ||
+      shape.keys.some(
+        (key, index) =>
+          normalizedRetentionPredicate(key) !==
+          normalizedRetentionPredicate(expected.keys[index]!),
+      ) ||
+      shape.predicate === null ||
+      normalizedQueryIndexPredicate(shape.predicate) !==
+        normalizedQueryIndexPredicate(expected.predicate)
+    ) {
       throw new Error(
-        `Runtime event index ${expected.name} was not found after preparation.`,
+        `Runtime event index ${expected.name} differs from its expected table, keys, method, uniqueness or predicate. Actual catalog shape: ${JSON.stringify(shape)}. Inspect and repair it explicitly.`,
       );
     }
-    assertShape(built);
+  };
+
+  const existing = (await inspect()).rows[0];
+  if (!existing) return false;
+  assertShape(existing);
+  return true;
+}
+
+async function prepareRuntimeEventQueryIndex(
+  client: PostgresSchedulerQueryClient,
+  expected: RuntimeEventIndexExpectation,
+): Promise<void> {
+  if (await hasRuntimeEventQueryIndex(client, expected)) return;
+  await client.query(expected.createSql);
+  if (!(await hasRuntimeEventQueryIndex(client, expected))) {
+    throw new Error(
+      `Runtime event index ${expected.name} was not found after preparation.`,
+    );
+  }
+}
+
+/** Deployment-only check; does not gate requests or worker admission. */
+export async function hasRuntimeEventLogPositionIndex(
+  client: PostgresSchedulerQueryClient,
+): Promise<boolean> {
+  return hasRuntimeEventQueryIndex(
+    client,
+    RUNTIME_EVENT_LOG_POSITION_INDEX_SPEC,
+  );
+}
+
+/** Prepare the existing position index before replacing the projection body. */
+export async function prepareRuntimeEventLogPositionIndex(
+  client: PostgresSchedulerQueryClient,
+): Promise<void> {
+  await prepareRuntimeEventQueryIndex(
+    client,
+    RUNTIME_EVENT_LOG_POSITION_INDEX_SPEC,
+  );
+}
+
+/** Build only operator-owned indexes, concurrently and outside a transaction. */
+export async function prepareRuntimeEventQueryIndexes(
+  client: PostgresSchedulerQueryClient,
+): Promise<void> {
+  for (const expected of RUNTIME_EVENT_QUERY_INDEXES) {
+    await prepareRuntimeEventQueryIndex(client, expected);
   }
 }