deepline 0.3.461 → 0.3.462

package/dist/bundling-sources/shared_libs/play-runtime/runtime-array-input-receipts.ts

@@ -0,0 +1,920 @@
+import { createHash } from 'node:crypto';
+import {
+  stableStringify,
+  normalizeTableNamespace,
+} from '../plays/row-identity';
+import { stringifyPostgresJson } from './postgres-json';
+import { buildScopedWorkReceiptKey } from './work-receipts';
+import {
+  RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+  RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+  RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND,
+  RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+  WORK_RECEIPT_STATUS_CODE,
+} from './work-receipt-storage-contract';
+import type {
+  RuntimeArrayInputScope,
+  RuntimeArrayInputOccurrence,
+  RuntimeArrayInputManifest,
+} from './array-input-store';
+
+/**
+ * Array sources are immutable internal receipts in the existing customer Neon
+ * receipt table. A retained run guard fences terminal retirement, while the
+ * existing terminal outbox owns bounded removal of page payloads.
+ * Every lookup uses the scoped bytea primary key. Replay hydrates one page at
+ * a time; seal verification fetches a fixed bounded group per checkout.
+ */
+
+export type RuntimeArrayInputQueryClient = {
+  query<T extends Record<string, unknown> = Record<string, unknown>>(
+    sql: string,
+    params?: unknown[],
+  ): Promise<{ rows: T[] }>;
+};
+
+export type RuntimeArrayInputReceiptPort = {
+  orgId: string;
+  playName: string;
+  runId: string;
+  table: string;
+  /** A customer execution role already opened a transaction around withClient. */
+  outerTransaction: boolean;
+  /** Internal native-benchmark candidates; never selected by a runtime request. */
+  sealPageBatchSize?: 1 | 4 | 8;
+  withClient<T>(
+    operation: (client: RuntimeArrayInputQueryClient) => Promise<T>,
+  ): Promise<T>;
+};
+
+/** Trusted tenant connection supplied by the terminal-outbox cleanup owner. */
+export type RuntimeArrayInputRetirementPort = RuntimeArrayInputReceiptPort;
+
+function arrayInputKeyHex(key: string): string {
+  return Array.from(new TextEncoder().encode(key), (byte) =>
+    byte.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+const RUNTIME_ARRAY_INPUT_MAX_PAGE_BYTES = 1024 * 1024;
+const RUNTIME_ARRAY_INPUT_MAX_PAGE_ROWS = 1_000;
+const RUNTIME_ARRAY_INPUT_RETIRE_BATCH_ROWS = 128;
+
+export type RuntimeArrayInputBegin = RuntimeArrayInputScope & {
+  sourceFingerprint: string;
+  sourceRows: number;
+  hasSourceIdentities: boolean;
+};
+export type RuntimeArrayInputPutPage = RuntimeArrayInputScope & {
+  sourceFingerprint: string;
+  ordinal: number;
+  offset: number;
+  rows: RuntimeArrayInputOccurrence[];
+};
+export type RuntimeArrayInputSeal = Omit<
+  RuntimeArrayInputBegin,
+  'hasSourceIdentities'
+> & { pageCount: number };
+
+function runtimeArrayInputScope(
+  port: RuntimeArrayInputReceiptPort,
+  input: RuntimeArrayInputScope,
+): RuntimeArrayInputScope & { orgId: string } {
+  const orgId = port.orgId?.trim();
+  const playName = input.playName?.trim();
+  const runId = input.runId?.trim();
+  const tableNamespace = input.tableNamespace?.trim();
+  const mapInvocationId = input.mapInvocationId?.trim();
+  if (!orgId || !playName || !runId || !tableNamespace || !mapInvocationId) {
+    throw new Error(
+      'Runtime array input requires exact org/play/run/map scope.',
+    );
+  }
+  if (
+    (port.playName && port.playName !== playName) ||
+    (port.runId && port.runId !== runId)
+  ) {
+    throw new Error('Runtime array input is outside the execution scope.');
+  }
+  return { orgId, playName, runId, tableNamespace, mapInvocationId };
+}
+
+function runtimeArrayInputKey(
+  scope: ReturnType<typeof runtimeArrayInputScope>,
+  kind: string,
+  ordinal?: number,
+): string {
+  return buildScopedWorkReceiptKey({
+    orgId: scope.orgId,
+    playName: scope.playName,
+    key: JSON.stringify([
+      kind,
+      scope.runId,
+      normalizeTableNamespace(scope.tableNamespace),
+      scope.mapInvocationId,
+      ...(ordinal === undefined ? [] : [ordinal]),
+    ]),
+  });
+}
+
+function validArrayInputCount(
+  value: unknown,
+  label: string,
+): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error(
+      `Runtime array input ${label} must be a nonnegative safe integer.`,
+    );
+  }
+}
+
+function validArrayInputFingerprint(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !/^[0-9a-f]{64}$/.test(value)) {
+    throw new Error(
+      'Runtime array input source fingerprint must be a SHA-256 hex digest.',
+    );
+  }
+}
+
+function runtimeArrayInputKeys(
+  scope: ReturnType<typeof runtimeArrayInputScope>,
+) {
+  return {
+    begin: runtimeArrayInputKey(scope, RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND),
+    seal: runtimeArrayInputKey(scope, RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND),
+  };
+}
+
+type ArrayInputReceiptRow = {
+  status: number;
+  run_id: string | null;
+  output: Record<string, unknown> | null;
+};
+
+function arrayInputRowsHaveSourceIdentities(rows: unknown[]): boolean {
+  let hasSourceIdentities = false;
+  for (const row of rows) {
+    if (!row || typeof row !== 'object' || Array.isArray(row))
+      throw new Error('Runtime array input page occurrence is corrupt.');
+    const occurrence = row as RuntimeArrayInputOccurrence;
+    if (
+      !occurrence.data ||
+      typeof occurrence.data !== 'object' ||
+      Array.isArray(occurrence.data)
+    )
+      throw new Error('Runtime array input page row data must be an object.');
+    const identity = occurrence.sourceIdentity;
+    if (identity !== undefined) {
+      if (
+        !identity ||
+        typeof identity.datasetId !== 'string' ||
+        !identity.datasetId ||
+        !Number.isSafeInteger(identity.rowIndex) ||
+        identity.rowIndex < 0
+      )
+        throw new Error('Runtime array input source identity is corrupt.');
+      hasSourceIdentities = true;
+    }
+  }
+  return hasSourceIdentities;
+}
+
+async function readArrayInputFact(
+  client: RuntimeArrayInputQueryClient,
+  session: string,
+  key: string,
+  lock = false,
+): Promise<ArrayInputReceiptRow | null> {
+  const { rows } = await client.query<ArrayInputReceiptRow>(
+    `SELECT status, run_id, output FROM ${session} WHERE k = decode($1, 'hex')${lock ? ' FOR UPDATE' : ''}`,
+    [arrayInputKeyHex(key)],
+  );
+  return rows[0] ?? null;
+}
+
+function requireArrayInputFact(
+  row: ArrayInputReceiptRow | null,
+  runId: string,
+  kind: string,
+): Record<string, unknown> {
+  if (
+    row?.status !== WORK_RECEIPT_STATUS_CODE.completed ||
+    row.run_id !== runId ||
+    row.output?.kind !== kind
+  ) {
+    throw new Error(`Runtime array input ${kind} fact is missing or corrupt.`);
+  }
+  return row.output;
+}
+
+async function putArrayInputFact(
+  client: RuntimeArrayInputQueryClient,
+  session: string,
+  key: string,
+  runId: string,
+  outputJson: string,
+): Promise<void> {
+  await client.query(
+    `INSERT INTO ${session} (k, status, output, run_id)
+     VALUES (decode($1, 'hex'), $2::smallint, $3::jsonb, $4)
+     ON CONFLICT (k) DO NOTHING`,
+    [
+      arrayInputKeyHex(key),
+      WORK_RECEIPT_STATUS_CODE.completed,
+      outputJson,
+      runId,
+    ],
+  );
+}
+
+async function withArrayInputTransaction<T>(
+  client: RuntimeArrayInputQueryClient,
+  outerTransaction: boolean,
+  work: () => Promise<T>,
+): Promise<T> {
+  const savepoint = 'runtime_array_input_fact';
+  await client.query(outerTransaction ? `SAVEPOINT ${savepoint}` : 'BEGIN');
+  try {
+    const result = await work();
+    await client.query(
+      outerTransaction ? `RELEASE SAVEPOINT ${savepoint}` : 'COMMIT',
+    );
+    return result;
+  } catch (error) {
+    await client.query(
+      outerTransaction ? `ROLLBACK TO SAVEPOINT ${savepoint}` : 'ROLLBACK',
+    );
+    throw error;
+  }
+}
+
+function arrayInputRunGuardKey(
+  port: RuntimeArrayInputReceiptPort,
+  runId: string,
+): string {
+  if (
+    !port.orgId?.trim() ||
+    !port.playName?.trim() ||
+    !runId?.trim() ||
+    port.runId !== runId
+  ) {
+    throw new Error(
+      'Runtime array input retirement requires exact org/play/run scope.',
+    );
+  }
+  return buildScopedWorkReceiptKey({
+    orgId: port.orgId,
+    playName: port.playName,
+    key: JSON.stringify([RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND, runId]),
+  });
+}
+
+async function lockedArrayInputRunGuard(
+  client: RuntimeArrayInputQueryClient,
+  port: RuntimeArrayInputReceiptPort,
+  runId: string,
+  create: boolean,
+): Promise<{ key: string; retired: boolean }> {
+  const key = arrayInputRunGuardKey(port, runId);
+  if (create) {
+    await putArrayInputFact(
+      client,
+      port.table,
+      key,
+      runId,
+      stringifyPostgresJson({
+        kind: RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND,
+        retired: false,
+      })!,
+    );
+  }
+  const guard = requireArrayInputFact(
+    await readArrayInputFact(client, port.table, key, true),
+    runId,
+    RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND,
+  );
+  if (typeof guard.retired !== 'boolean') {
+    throw new Error('Runtime array input run guard is corrupt.');
+  }
+  return { key, retired: guard.retired };
+}
+
+async function requireActiveArrayInputRun(
+  client: RuntimeArrayInputQueryClient,
+  port: RuntimeArrayInputReceiptPort,
+  runId: string,
+  create = false,
+): Promise<void> {
+  const guard = await lockedArrayInputRunGuard(client, port, runId, create);
+  if (guard.retired) {
+    throw new Error('Runtime array input run is retired.');
+  }
+}
+
+/** Read-only scans never acquire the writer/retirement row lock. */
+async function requireActiveArrayInputRunForRead(
+  client: RuntimeArrayInputQueryClient,
+  port: RuntimeArrayInputReceiptPort,
+  runId: string,
+): Promise<void> {
+  const guard = requireArrayInputFact(
+    await readArrayInputFact(
+      client,
+      port.table,
+      arrayInputRunGuardKey(port, runId),
+    ),
+    runId,
+    RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND,
+  );
+  if (guard.retired !== false) {
+    throw new Error('Runtime array input run is retired.');
+  }
+}
+
+function arrayInputRunFactPrefixHex(
+  port: RuntimeArrayInputRetirementPort,
+  runId: string,
+  kind: string,
+): string {
+  const key = buildScopedWorkReceiptKey({
+    orgId: port.orgId,
+    playName: port.playName,
+    key: `${JSON.stringify([kind, runId]).slice(0, -1)},`,
+  });
+  return arrayInputKeyHex(key);
+}
+
+/**
+ * The existing terminal outbox retries this bounded batch before ACK. The
+ * retained guard serializes with every writer, then refuses all later writes.
+ * PK prefix ranges delete only this org/play/run's internal array facts.
+ */
+export async function retireRuntimeArrayInputRun(
+  port: RuntimeArrayInputRetirementPort,
+  input: { runId: string },
+): Promise<{ done: boolean; deleted: number }> {
+  const guardKey = arrayInputRunGuardKey(port, input.runId);
+  const factPrefixes = [
+    RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+    RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+    RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+  ].map((kind) => arrayInputRunFactPrefixHex(port, input.runId, kind));
+  return await port.withClient((client) =>
+    withArrayInputTransaction(client, port.outerTransaction, async () => {
+      const guard = await lockedArrayInputRunGuard(
+        client,
+        port,
+        input.runId,
+        true,
+      );
+      if (!guard.retired) {
+        await client.query(
+          `UPDATE ${port.table} SET output = $2::jsonb WHERE k = decode($1, 'hex') AND run_id = $3`,
+          [
+            arrayInputKeyHex(guardKey),
+            stringifyPostgresJson({
+              kind: RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND,
+              retired: true,
+            }),
+            input.runId,
+          ],
+        );
+      }
+      const { rows } = await client.query<{ k: Uint8Array }>(
+        `WITH candidates AS (
+           (SELECT k FROM ${port.table}
+             WHERE k >= decode($2, 'hex') AND k < (decode($2, 'hex') || decode('ff', 'hex'))
+               AND run_id = $1
+             ORDER BY k LIMIT ${RUNTIME_ARRAY_INPUT_RETIRE_BATCH_ROWS})
+           UNION ALL
+           (SELECT k FROM ${port.table}
+             WHERE k >= decode($3, 'hex') AND k < (decode($3, 'hex') || decode('ff', 'hex'))
+               AND run_id = $1
+             ORDER BY k LIMIT ${RUNTIME_ARRAY_INPUT_RETIRE_BATCH_ROWS})
+           UNION ALL
+           (SELECT k FROM ${port.table}
+             WHERE k >= decode($4, 'hex') AND k < (decode($4, 'hex') || decode('ff', 'hex'))
+               AND run_id = $1
+             ORDER BY k LIMIT ${RUNTIME_ARRAY_INPUT_RETIRE_BATCH_ROWS})
+         ), doomed AS (
+           SELECT k FROM candidates ORDER BY k LIMIT ${RUNTIME_ARRAY_INPUT_RETIRE_BATCH_ROWS}
+         )
+         DELETE FROM ${port.table} AS receipt USING doomed
+          WHERE receipt.k = doomed.k
+          RETURNING receipt.k`,
+        [input.runId, ...factPrefixes],
+      );
+      // A full batch may have drained the last page. A false answer is safe:
+      // the durable outbox retries and the guard prevents any re-growth.
+      return {
+        done: rows.length < RUNTIME_ARRAY_INPUT_RETIRE_BATCH_ROWS,
+        deleted: rows.length,
+      };
+    }),
+  );
+}
+
+export async function getRuntimeArrayInputManifest(
+  port: RuntimeArrayInputReceiptPort,
+  input: RuntimeArrayInputScope,
+): Promise<RuntimeArrayInputManifest> {
+  const scope = runtimeArrayInputScope(port, input);
+  const keys = runtimeArrayInputKeys(scope);
+  return await port.withClient(async (client) => {
+    const guard = await readArrayInputFact(
+      client,
+      port.table,
+      arrayInputRunGuardKey(port, scope.runId),
+    );
+    if (guard) {
+      const state = requireArrayInputFact(
+        guard,
+        scope.runId,
+        RUNTIME_ARRAY_INPUT_RUN_GUARD_RECEIPT_KIND,
+      );
+      if (state.retired !== false) {
+        throw new Error('Runtime array input run is retired.');
+      }
+    }
+    const begin = await readArrayInputFact(client, port.table, keys.begin);
+    if (!begin) return { state: 'absent' };
+    const manifest = requireArrayInputFact(
+      begin,
+      scope.runId,
+      RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+    );
+    validArrayInputFingerprint(manifest.sourceFingerprint);
+    validArrayInputCount(manifest.sourceRows, 'sourceRows');
+    if (typeof manifest.hasSourceIdentities !== 'boolean') {
+      throw new Error('Runtime array input begin identity flag is corrupt.');
+    }
+    const seal = await readArrayInputFact(client, port.table, keys.seal);
+    if (!seal)
+      return {
+        state: 'staging',
+        sourceFingerprint: manifest.sourceFingerprint,
+        sourceRows: manifest.sourceRows,
+        hasSourceIdentities: manifest.hasSourceIdentities,
+      };
+    const sealed = requireArrayInputFact(
+      seal,
+      scope.runId,
+      RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+    );
+    if (
+      sealed.sourceFingerprint !== manifest.sourceFingerprint ||
+      sealed.sourceRows !== manifest.sourceRows ||
+      sealed.hasSourceIdentities !== manifest.hasSourceIdentities
+    ) {
+      throw new Error('Runtime array input seal disagrees with begin.');
+    }
+    validArrayInputCount(sealed.pageCount, 'pageCount');
+    return {
+      state: 'sealed',
+      sourceFingerprint: manifest.sourceFingerprint,
+      sourceRows: manifest.sourceRows,
+      hasSourceIdentities: manifest.hasSourceIdentities,
+      pageCount: sealed.pageCount,
+    };
+  });
+}
+
+export async function beginRuntimeArrayInput(
+  port: RuntimeArrayInputReceiptPort,
+  input: RuntimeArrayInputBegin,
+): Promise<void> {
+  const scope = runtimeArrayInputScope(port, input);
+  validArrayInputFingerprint(input.sourceFingerprint);
+  validArrayInputCount(input.sourceRows, 'sourceRows');
+  if (typeof input.hasSourceIdentities !== 'boolean') {
+    throw new Error('Runtime array input identity flag is required.');
+  }
+  const key = runtimeArrayInputKeys(scope).begin;
+  const expected = {
+    kind: RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+    sourceFingerprint: input.sourceFingerprint,
+    sourceRows: input.sourceRows,
+    hasSourceIdentities: input.hasSourceIdentities,
+  };
+  await port.withClient((client) =>
+    withArrayInputTransaction(client, port.outerTransaction, async () => {
+      await requireActiveArrayInputRun(client, port, scope.runId, true);
+      await putArrayInputFact(
+        client,
+        port.table,
+        key,
+        scope.runId,
+        stringifyPostgresJson(expected)!,
+      );
+      const stored = requireArrayInputFact(
+        await readArrayInputFact(client, port.table, key),
+        scope.runId,
+        RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+      );
+      if (
+        stored.sourceFingerprint !== expected.sourceFingerprint ||
+        stored.sourceRows !== expected.sourceRows ||
+        stored.hasSourceIdentities !== expected.hasSourceIdentities
+      ) {
+        throw new Error(
+          'Runtime array input source changed after staging began.',
+        );
+      }
+    }),
+  );
+}
+
+export async function putRuntimeArrayInputPage(
+  port: RuntimeArrayInputReceiptPort,
+  input: RuntimeArrayInputPutPage,
+): Promise<void> {
+  const scope = runtimeArrayInputScope(port, input);
+  validArrayInputFingerprint(input.sourceFingerprint);
+  validArrayInputCount(input.ordinal, 'ordinal');
+  validArrayInputCount(input.offset, 'offset');
+  if (
+    !Array.isArray(input.rows) ||
+    input.rows.length < 1 ||
+    input.rows.length > RUNTIME_ARRAY_INPUT_MAX_PAGE_ROWS
+  ) {
+    throw new Error('Runtime array input page requires 1-1000 rows.');
+  }
+  arrayInputRowsHaveSourceIdentities(input.rows);
+  // JSON normalization matches the value actually persisted in JSONB. Never
+  // stringify an entire source: this object is bounded to one page.
+  const rows = JSON.parse(
+    stringifyPostgresJson(input.rows)!,
+  ) as RuntimeArrayInputOccurrence[];
+  arrayInputRowsHaveSourceIdentities(rows);
+  const digest = createHash('sha256')
+    .update(
+      stableStringify({
+        sourceFingerprint: input.sourceFingerprint,
+        ordinal: input.ordinal,
+        offset: input.offset,
+        rows,
+      }),
+    )
+    .digest('hex');
+  const output = {
+    kind: RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+    sourceFingerprint: input.sourceFingerprint,
+    ordinal: input.ordinal,
+    offset: input.offset,
+    rowCount: rows.length,
+    rows,
+    digest,
+  };
+  const serialized = stringifyPostgresJson(output)!;
+  const requestBytes = Buffer.byteLength(
+    JSON.stringify({ action: 'runtime_array_input_put_page', input }),
+    'utf8',
+  );
+  if (
+    Buffer.byteLength(serialized, 'utf8') >
+      RUNTIME_ARRAY_INPUT_MAX_PAGE_BYTES ||
+    requestBytes > RUNTIME_ARRAY_INPUT_MAX_PAGE_BYTES
+  ) {
+    throw new Error(
+      'Runtime array input page exceeds its 1 MiB JSON envelope limit.',
+    );
+  }
+  const keys = runtimeArrayInputKeys(scope);
+  const pageKey = runtimeArrayInputKey(
+    scope,
+    RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+    input.ordinal,
+  );
+  await port.withClient((client) =>
+    withArrayInputTransaction(client, port.outerTransaction, async () => {
+      await requireActiveArrayInputRun(client, port, scope.runId);
+      const begin = requireArrayInputFact(
+        await readArrayInputFact(client, port.table, keys.begin, true),
+        scope.runId,
+        RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+      );
+      if (
+        begin.sourceFingerprint !== input.sourceFingerprint ||
+        input.offset + rows.length > Number(begin.sourceRows)
+      ) {
+        throw new Error(
+          'Runtime array input page disagrees with admitted source.',
+        );
+      }
+      if (await readArrayInputFact(client, port.table, keys.seal)) {
+        const existing = requireArrayInputFact(
+          await readArrayInputFact(client, port.table, pageKey),
+          scope.runId,
+          RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+        );
+        if (existing.digest !== digest)
+          throw new Error('Runtime array input sealed page conflict.');
+        return;
+      }
+      await putArrayInputFact(
+        client,
+        port.table,
+        pageKey,
+        scope.runId,
+        serialized,
+      );
+      // The put validates only immutable scalar headers. Leave the payload in
+      // PostgreSQL here; seal and readPage still fetch and verify every byte.
+      const { rows: stored } = await client.query<ArrayInputReceiptRow>(
+        `SELECT page.status, page.run_id,
+           jsonb_build_object('kind', header.kind,
+             'sourceFingerprint', header."sourceFingerprint", 'ordinal', header.ordinal,
+             'offset', header."offset", 'rowCount', header."rowCount", 'digest', header.digest) AS output
+         FROM ${port.table} AS page
+         CROSS JOIN LATERAL jsonb_to_record(page.output) AS header(
+           kind jsonb, "sourceFingerprint" jsonb, ordinal jsonb,
+           "offset" jsonb, "rowCount" jsonb, digest jsonb)
+         WHERE page.k = decode($1, 'hex')`,
+        [arrayInputKeyHex(pageKey)],
+      );
+      const existing = requireArrayInputFact(
+        stored[0] ?? null,
+        scope.runId,
+        RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+      );
+      if (
+        existing.digest !== digest ||
+        existing.offset !== input.offset ||
+        existing.rowCount !== rows.length ||
+        existing.sourceFingerprint !== input.sourceFingerprint ||
+        existing.ordinal !== input.ordinal
+      ) {
+        throw new Error('Runtime array input immutable page conflict.');
+      }
+    }),
+  );
+}
+
+export async function sealRuntimeArrayInput(
+  port: RuntimeArrayInputReceiptPort,
+  input: RuntimeArrayInputSeal,
+): Promise<void> {
+  const scope = runtimeArrayInputScope(port, input);
+  validArrayInputFingerprint(input.sourceFingerprint);
+  validArrayInputCount(input.sourceRows, 'sourceRows');
+  validArrayInputCount(input.pageCount, 'pageCount');
+  if (input.pageCount > input.sourceRows) {
+    throw new Error('Runtime array input seal has invalid cardinality.');
+  }
+  const keys = runtimeArrayInputKeys(scope);
+  const readBegin = async (client: RuntimeArrayInputQueryClient) => {
+    await requireActiveArrayInputRun(client, port, scope.runId);
+    const begin = requireArrayInputFact(
+      await readArrayInputFact(client, port.table, keys.begin, true),
+      scope.runId,
+      RUNTIME_ARRAY_INPUT_BEGIN_RECEIPT_KIND,
+    );
+    if (
+      begin.sourceFingerprint !== input.sourceFingerprint ||
+      begin.sourceRows !== input.sourceRows ||
+      typeof begin.hasSourceIdentities !== 'boolean'
+    ) {
+      throw new Error(
+        'Runtime array input seal disagrees with admitted source.',
+      );
+    }
+    return begin.hasSourceIdentities;
+  };
+  const readCompletedSeal = async (
+    client: RuntimeArrayInputQueryClient,
+    hasSourceIdentities: boolean,
+  ): Promise<boolean> => {
+    const fact = await readArrayInputFact(client, port.table, keys.seal);
+    if (!fact) return false;
+    const seal = requireArrayInputFact(
+      fact,
+      scope.runId,
+      RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+    );
+    if (
+      seal.sourceFingerprint !== input.sourceFingerprint ||
+      seal.sourceRows !== input.sourceRows ||
+      seal.pageCount !== input.pageCount ||
+      seal.hasSourceIdentities !== hasSourceIdentities ||
+      typeof seal.digestChain !== 'string' ||
+      !/^[a-f0-9]{64}$/.test(seal.digestChain)
+    )
+      throw new Error('Runtime array input immutable seal conflict.');
+    return true;
+  };
+  const initial = await port.withClient((client) =>
+    withArrayInputTransaction(client, port.outerTransaction, async () => {
+      const hasSourceIdentities = await readBegin(client);
+      return {
+        hasSourceIdentities,
+        sealed: await readCompletedSeal(client, hasSourceIdentities),
+      };
+    }),
+  );
+  // A completed seal is the durable proof of the same immutable pages. Reuse
+  // that proof on retries rather than repeating a whole-source verification.
+  if (initial.sealed) return;
+  const expectedHasSourceIdentities = initial.hasSourceIdentities;
+  const batchSize = port.sealPageBatchSize ?? 4;
+  if (![1, 4, 8].includes(batchSize))
+    throw new Error('Invalid array input seal page batch size.');
+  const digestChain = createHash('sha256');
+  let nextOffset = 0;
+  let hasSourceIdentities = false;
+  for (
+    let batchStart = 0;
+    batchStart < input.pageCount;
+    batchStart += batchSize
+  ) {
+    const ordinals = Array.from(
+      { length: Math.min(batchSize, input.pageCount - batchStart) },
+      (_, index) => batchStart + index,
+    );
+    // At most eight already-bounded 1 MiB pages cross this checkout. Release
+    // both the role transaction and receipt permit before hashing any payload.
+    const batch = await port.withClient(async (client) => {
+      await requireActiveArrayInputRunForRead(client, port, scope.runId);
+      // A peer may have finished while this attempt yielded between batches.
+      // Reuse completed proof; never wait for another in-progress attempt.
+      if (await readCompletedSeal(client, expectedHasSourceIdentities))
+        return null;
+      const params = ordinals.map((ordinal) =>
+        arrayInputKeyHex(
+          runtimeArrayInputKey(
+            scope,
+            RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+            ordinal,
+          ),
+        ),
+      );
+      const { rows } = await client.query<
+        ArrayInputReceiptRow & { scan_ordinal: number }
+      >(
+        ordinals
+          .map(
+            (ordinal, index) =>
+              `SELECT status, run_id, output, ${ordinal} AS scan_ordinal FROM ${port.table} WHERE k = decode($${index + 1}, 'hex')`,
+          )
+          .join(' UNION ALL '),
+        params,
+      );
+      return rows;
+    });
+    if (batch === null) return;
+    for (const ordinal of ordinals) {
+      const fact = batch.find((row) => row.scan_ordinal === ordinal) ?? null;
+      const page = requireArrayInputFact(
+        fact,
+        scope.runId,
+        RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+      );
+      if (
+        page.sourceFingerprint !== input.sourceFingerprint ||
+        page.ordinal !== ordinal ||
+        page.offset !== nextOffset ||
+        !Number.isSafeInteger(page.rowCount) ||
+        Number(page.rowCount) < 1 ||
+        Number(page.rowCount) > RUNTIME_ARRAY_INPUT_MAX_PAGE_ROWS ||
+        !Array.isArray(page.rows) ||
+        page.rows.length !== page.rowCount ||
+        typeof page.digest !== 'string'
+      ) {
+        throw new Error(
+          'Runtime array input seal found a missing or misordered page.',
+        );
+      }
+      const verifiedDigest = createHash('sha256')
+        .update(
+          stableStringify({
+            sourceFingerprint: input.sourceFingerprint,
+            ordinal,
+            offset: nextOffset,
+            rows: page.rows,
+          }),
+        )
+        .digest('hex');
+      if (verifiedDigest !== page.digest) {
+        throw new Error('Runtime array input page digest mismatch.');
+      }
+      const pageHasSourceIdentities = arrayInputRowsHaveSourceIdentities(
+        page.rows,
+      );
+      hasSourceIdentities ||= pageHasSourceIdentities;
+      digestChain.update(page.digest);
+      nextOffset += Number(page.rowCount);
+      // Keep other requests runnable between bounded canonicalization turns.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+    }
+  }
+
+  if (nextOffset !== input.sourceRows) {
+    throw new Error('Runtime array input seal row count mismatch.');
+  }
+  if (hasSourceIdentities !== expectedHasSourceIdentities) {
+    throw new Error(
+      'Runtime array input seal source identities disagree with begin.',
+    );
+  }
+  const output = {
+    kind: RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+    sourceFingerprint: input.sourceFingerprint,
+    sourceRows: input.sourceRows,
+    hasSourceIdentities: expectedHasSourceIdentities,
+    pageCount: input.pageCount,
+    digestChain: digestChain.digest('hex'),
+  };
+  // Pages are write-if-absent and immutable. Retirement first marks the run
+  // guard, so this final fence rejects any retirement during the released scan.
+  await port.withClient((client) =>
+    withArrayInputTransaction(client, port.outerTransaction, async () => {
+      if ((await readBegin(client)) !== expectedHasSourceIdentities) {
+        throw new Error(
+          'Runtime array input seal disagrees with admitted source.',
+        );
+      }
+      await putArrayInputFact(
+        client,
+        port.table,
+        keys.seal,
+        scope.runId,
+        stringifyPostgresJson(output)!,
+      );
+      const stored = requireArrayInputFact(
+        await readArrayInputFact(client, port.table, keys.seal),
+        scope.runId,
+        RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+      );
+      if (
+        stored.sourceFingerprint !== output.sourceFingerprint ||
+        stored.sourceRows !== output.sourceRows ||
+        stored.hasSourceIdentities !== output.hasSourceIdentities ||
+        stored.pageCount !== output.pageCount ||
+        stored.digestChain !== output.digestChain
+      ) {
+        throw new Error('Runtime array input immutable seal conflict.');
+      }
+    }),
+  );
+}
+
+export async function readRuntimeArrayInputPage(
+  port: RuntimeArrayInputReceiptPort,
+  input: RuntimeArrayInputScope & { ordinal: number },
+): Promise<{ offset: number; rows: RuntimeArrayInputOccurrence[] }> {
+  const scope = runtimeArrayInputScope(port, input);
+  validArrayInputCount(input.ordinal, 'ordinal');
+  const keys = runtimeArrayInputKeys(scope);
+  return await port.withClient(async (client) => {
+    await requireActiveArrayInputRunForRead(client, port, scope.runId);
+    const seal = requireArrayInputFact(
+      await readArrayInputFact(client, port.table, keys.seal),
+      scope.runId,
+      RUNTIME_ARRAY_INPUT_SEAL_RECEIPT_KIND,
+    );
+    validArrayInputFingerprint(seal.sourceFingerprint);
+    validArrayInputCount(seal.pageCount, 'pageCount');
+    if (input.ordinal >= seal.pageCount) {
+      throw new Error(
+        'Runtime array input page ordinal exceeds sealed manifest.',
+      );
+    }
+    const page = requireArrayInputFact(
+      await readArrayInputFact(
+        client,
+        port.table,
+        runtimeArrayInputKey(
+          scope,
+          RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+          input.ordinal,
+        ),
+      ),
+      scope.runId,
+      RUNTIME_ARRAY_INPUT_PAGE_RECEIPT_KIND,
+    );
+    if (
+      !Array.isArray(page.rows) ||
+      !Number.isSafeInteger(page.offset) ||
+      page.ordinal !== input.ordinal ||
+      page.sourceFingerprint !== seal.sourceFingerprint ||
+      page.rowCount !== page.rows.length
+    ) {
+      throw new Error('Runtime array input sealed page is corrupt.');
+    }
+    const digest = createHash('sha256')
+      .update(
+        stableStringify({
+          sourceFingerprint: seal.sourceFingerprint,
+          ordinal: input.ordinal,
+          offset: page.offset,
+          rows: page.rows,
+        }),
+      )
+      .digest('hex');
+    if (page.digest !== digest)
+      throw new Error('Runtime array input sealed page digest mismatch.');
+    return {
+      offset: page.offset as number,
+      rows: page.rows as RuntimeArrayInputOccurrence[],
+    };
+  });
+}