deepline 0.3.89 → 0.3.91

package/dist/bundling-sources/shared_libs/play-runtime/integration-operation-reader-fence/job.ts

@@ -0,0 +1,145 @@
+import {
+  INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY,
+  type IntegrationOperationStorageMode,
+  type ReaderFenceApplyOutcome,
+  type ReaderFenceWriterMode,
+  type RuntimeGatewayReaderFence,
+  type RuntimeGatewayReaderFenceCandidate,
+  type RuntimeGatewayReaderFenceJob,
+} from '../integration-operation-reader-fence/contracts';
+import type { RuntimeGatewayReaderFencePorts } from '../integration-operation-reader-fence/ports';
+
+/**
+ * Decides which Integration Operation storage format a gateway may write.
+ *
+ * This job intentionally has no environment variable, deployment lookup, or
+ * fallback-to-canonical path. The durable, schema-scoped mirror is the only
+ * authority. A missing, malformed, or unreadable mirror therefore continues
+ * to select the old byte-response writer.
+ */
+export function createRuntimeGatewayReaderFenceJob(
+  ports: RuntimeGatewayReaderFencePorts,
+): RuntimeGatewayReaderFenceJob {
+  return {
+    async writerMode(input): Promise<ReaderFenceWriterMode> {
+      validateSchema(input.schema);
+      let fence: RuntimeGatewayReaderFence | null;
+      try {
+        fence = await ports.store.read({ schema: input.schema });
+      } catch {
+        return {
+          mode: 'legacy_byte_reader',
+          source: 'fail_closed',
+          epoch: null,
+          failure: 'store_unavailable',
+        };
+      }
+
+      if (!fence) {
+        return { mode: 'legacy_byte_reader', source: 'absent', epoch: null };
+      }
+      if (
+        !isValidRuntimeGatewayReaderFence(fence) ||
+        fence.schema !== input.schema
+      ) {
+        return {
+          mode: 'legacy_byte_reader',
+          source: 'fail_closed',
+          epoch: null,
+          failure: 'invalid_record',
+        };
+      }
+      return { mode: fence.mode, source: 'fence', epoch: fence.epoch };
+    },
+
+    async apply(
+      candidate: RuntimeGatewayReaderFenceCandidate,
+    ): Promise<ReaderFenceApplyOutcome> {
+      validateRuntimeGatewayReaderFence(candidate);
+      return await ports.store.apply(candidate);
+    },
+  };
+}
+
+export function isValidRuntimeGatewayReaderFence(
+  fence: unknown,
+): fence is RuntimeGatewayReaderFence {
+  try {
+    validateRuntimeGatewayReaderFence(fence as RuntimeGatewayReaderFence);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function validateRuntimeGatewayReaderFence(
+  fence: RuntimeGatewayReaderFenceCandidate,
+): void {
+  validateSchema(fence.schema);
+  if (!Number.isSafeInteger(fence.epoch) || fence.epoch <= 0) {
+    throw new Error(
+      'Runtime Gateway Reader Fence requires a positive safe epoch.',
+    );
+  }
+  if (!isStorageMode(fence.mode)) {
+    throw new Error(
+      'Runtime Gateway Reader Fence has an unknown storage mode.',
+    );
+  }
+
+  if (fence.mode === 'legacy_byte_reader') {
+    if (fence.canonicalReaderProof !== null) {
+      throw new Error(
+        'Legacy byte-reader fences must not carry canonical reader proof.',
+      );
+    }
+    return;
+  }
+
+  const proof = fence.canonicalReaderProof;
+  if (!proof) {
+    throw new Error(
+      'Canonical reader fences require verified gateway reader proof.',
+    );
+  }
+  if (proof.capability !== INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY) {
+    throw new Error(
+      'Canonical reader fence has an unsupported gateway capability.',
+    );
+  }
+  if (!proof.sourceSha.trim()) {
+    throw new Error('Canonical reader fence requires a source SHA.');
+  }
+  for (const role of ['receipt', 'execution'] as const) {
+    const ids = proof.machineIds[role];
+    if (!Array.isArray(ids) || ids.length === 0) {
+      throw new Error(
+        `Canonical reader fence requires a verified ${role} gateway Machine.`,
+      );
+    }
+    if (ids.some((id) => typeof id !== 'string' || !id.trim())) {
+      throw new Error(
+        `Canonical reader fence has an invalid ${role} gateway Machine id.`,
+      );
+    }
+    if (new Set(ids).size !== ids.length) {
+      throw new Error(
+        `Canonical reader fence repeats a ${role} gateway Machine id.`,
+      );
+    }
+  }
+}
+
+function validateSchema(schema: string): void {
+  if (!schema?.trim()) {
+    throw new Error(
+      'Runtime Gateway Reader Fence requires a non-empty schema.',
+    );
+  }
+}
+
+function isStorageMode(
+  value: unknown,
+): value is IntegrationOperationStorageMode {
+  return value === 'legacy_byte_reader' || value === 'canonical_v1';
+}

package/dist/bundling-sources/shared_libs/play-runtime/integration-operation-reader-fence/memory-store.ts

@@ -0,0 +1,114 @@
+import type {
+  ReaderFenceApplyOutcome,
+  RuntimeGatewayReaderFence,
+  RuntimeGatewayReaderFenceCandidate,
+} from '../integration-operation-reader-fence/contracts';
+import type { RuntimeGatewayReaderFenceStore } from '../integration-operation-reader-fence/ports';
+
+/**
+ * Recording adapter for contract tests and local assembly. It implements the
+ * same atomic compare-and-advance law required of the Runtime Postgres mirror.
+ */
+export function createMemoryRuntimeGatewayReaderFenceStore(
+  initial: readonly RuntimeGatewayReaderFence[] = [],
+): RuntimeGatewayReaderFenceStore {
+  const fences = new Map(
+    initial.map((fence) => [fence.schema, copyFence(fence)]),
+  );
+
+  return {
+    async read({ schema }) {
+      const fence = fences.get(schema);
+      return fence ? copyFence(fence) : null;
+    },
+
+    async apply(candidate): Promise<ReaderFenceApplyOutcome> {
+      const next = copyFence(candidate);
+      const current = fences.get(next.schema);
+      if (!current) {
+        fences.set(next.schema, next);
+        return { kind: 'advanced', fence: copyFence(next) };
+      }
+      if (next.epoch < current.epoch) {
+        return {
+          kind: 'rejected',
+          reason: 'stale_epoch',
+          current: copyFence(current),
+        };
+      }
+      if (next.epoch === current.epoch) {
+        if (sameFence(next, current)) {
+          return { kind: 'already_applied', fence: copyFence(current) };
+        }
+        return {
+          kind: 'rejected',
+          reason: 'epoch_conflict',
+          current: copyFence(current),
+        };
+      }
+      if (current.mode === 'canonical_v1' && next.mode !== 'canonical_v1') {
+        return {
+          kind: 'rejected',
+          reason: 'unsafe_mode_downgrade',
+          current: copyFence(current),
+        };
+      }
+      fences.set(next.schema, next);
+      return { kind: 'advanced', fence: copyFence(next) };
+    },
+  };
+}
+
+function sameFence(
+  left: RuntimeGatewayReaderFence,
+  right: RuntimeGatewayReaderFence,
+): boolean {
+  if (
+    left.schema !== right.schema ||
+    left.epoch !== right.epoch ||
+    left.mode !== right.mode
+  ) {
+    return false;
+  }
+  if (!left.canonicalReaderProof || !right.canonicalReaderProof) {
+    return left.canonicalReaderProof === right.canonicalReaderProof;
+  }
+  return (
+    left.canonicalReaderProof.capability ===
+      right.canonicalReaderProof.capability &&
+    left.canonicalReaderProof.sourceSha ===
+      right.canonicalReaderProof.sourceSha &&
+    sameMachineSet(
+      left.canonicalReaderProof.machineIds.receipt,
+      right.canonicalReaderProof.machineIds.receipt,
+    ) &&
+    sameMachineSet(
+      left.canonicalReaderProof.machineIds.execution,
+      right.canonicalReaderProof.machineIds.execution,
+    )
+  );
+}
+
+function sameMachineSet(
+  left: readonly string[],
+  right: readonly string[],
+): boolean {
+  return left.length === right.length && left.every((id) => right.includes(id));
+}
+
+function copyFence(
+  fence: RuntimeGatewayReaderFenceCandidate,
+): RuntimeGatewayReaderFence {
+  return {
+    ...fence,
+    canonicalReaderProof: fence.canonicalReaderProof
+      ? {
+          ...fence.canonicalReaderProof,
+          machineIds: {
+            receipt: [...fence.canonicalReaderProof.machineIds.receipt],
+            execution: [...fence.canonicalReaderProof.machineIds.execution],
+          },
+        }
+      : null,
+  };
+}

package/dist/bundling-sources/shared_libs/play-runtime/integration-operation-reader-fence/ports.ts

@@ -0,0 +1,21 @@
+import type {
+  ReaderFenceApplyOutcome,
+  RuntimeGatewayReaderFence,
+  RuntimeGatewayReaderFenceCandidate,
+} from '../integration-operation-reader-fence/contracts';
+
+/**
+ * Durable, schema-keyed mirror port. `apply` must perform its comparison and
+ * update atomically: read-then-write in the job would let two operators reuse
+ * an epoch with different reader contracts.
+ */
+export type RuntimeGatewayReaderFenceStore = {
+  read(input: { schema: string }): Promise<RuntimeGatewayReaderFence | null>;
+  apply(
+    candidate: RuntimeGatewayReaderFenceCandidate,
+  ): Promise<ReaderFenceApplyOutcome>;
+};
+
+export type RuntimeGatewayReaderFencePorts = {
+  store: RuntimeGatewayReaderFenceStore;
+};

package/dist/bundling-sources/shared_libs/play-runtime/integration-operation-reader-fence/postgres-store.ts

@@ -0,0 +1,170 @@
+import { stringifyPostgresJson } from '../postgres-json';
+
+import type { PostgresSchedulerQueryClient } from '../scheduler-backends/postgres';
+
+import {
+  isValidRuntimeGatewayReaderFence,
+  validateRuntimeGatewayReaderFence,
+} from '../integration-operation-reader-fence/job';
+import type {
+  ReaderFenceApplyOutcome,
+  RuntimeGatewayReaderFence,
+  RuntimeGatewayReaderFenceCandidate,
+} from '../integration-operation-reader-fence/contracts';
+import type { RuntimeGatewayReaderFenceStore } from '../integration-operation-reader-fence/ports';
+
+const DEFAULT_SCHEMA = 'runtime_scheduler';
+const TABLE = 'runtime_gateway_reader_fences';
+
+type Row = {
+  scheduler_schema: string;
+  epoch: number | string;
+  mode: unknown;
+  canonical_reader_proof: unknown;
+};
+
+function quoteIdent(value: string): string {
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+function tableName(schema: string): string {
+  return `${quoteIdent(schema)}.${quoteIdent(TABLE)}`;
+}
+
+function parseRow(row: Row): RuntimeGatewayReaderFence {
+  const fence: RuntimeGatewayReaderFence = {
+    schema: row.scheduler_schema,
+    epoch: Number(row.epoch),
+    mode: row.mode as RuntimeGatewayReaderFence['mode'],
+    canonicalReaderProof:
+      row.canonical_reader_proof === null
+        ? null
+        : (row.canonical_reader_proof as RuntimeGatewayReaderFence['canonicalReaderProof']),
+  };
+  if (!isValidRuntimeGatewayReaderFence(fence)) {
+    throw new Error('Runtime Gateway Reader Fence row is invalid.');
+  }
+  return fence;
+}
+
+function sameMachineSet(left: readonly string[], right: readonly string[]) {
+  return left.length === right.length && left.every((id) => right.includes(id));
+}
+
+function sameFence(
+  left: RuntimeGatewayReaderFence,
+  right: RuntimeGatewayReaderFence,
+): boolean {
+  if (
+    left.schema !== right.schema ||
+    left.epoch !== right.epoch ||
+    left.mode !== right.mode
+  ) {
+    return false;
+  }
+  const leftProof = left.canonicalReaderProof;
+  const rightProof = right.canonicalReaderProof;
+  if (!leftProof || !rightProof) return leftProof === rightProof;
+  return (
+    leftProof.capability === rightProof.capability &&
+    leftProof.sourceSha === rightProof.sourceSha &&
+    sameMachineSet(
+      leftProof.machineIds.receipt,
+      rightProof.machineIds.receipt,
+    ) &&
+    sameMachineSet(
+      leftProof.machineIds.execution,
+      rightProof.machineIds.execution,
+    )
+  );
+}
+
+/**
+ * Runtime Postgres mirror adapter. The gateway reads this local record on its
+ * hot path; Convex remains the deployment control-plane source of truth.
+ */
+export function createPostgresRuntimeGatewayReaderFenceStore(input: {
+  client: PostgresSchedulerQueryClient;
+  schema?: string;
+}): RuntimeGatewayReaderFenceStore {
+  const schema = input.schema?.trim() || DEFAULT_SCHEMA;
+  const table = tableName(schema);
+  const returning = `scheduler_schema, epoch, mode, canonical_reader_proof`;
+  const read = async ({
+    schema: schedulerSchema,
+  }: {
+    schema: string;
+  }): Promise<RuntimeGatewayReaderFence | null> => {
+    const row = (
+      await input.client.query<Row>(
+        `SELECT ${returning}
+           FROM ${table}
+          WHERE scheduler_schema = $1
+          LIMIT 1`,
+        [schedulerSchema],
+      )
+    ).rows[0];
+    return row ? parseRow(row) : null;
+  };
+
+  return {
+    read,
+
+    async apply(candidate): Promise<ReaderFenceApplyOutcome> {
+      validateRuntimeGatewayReaderFence(candidate);
+      const before = await read({ schema: candidate.schema });
+      const result = await input.client.query<Row>(
+        `INSERT INTO ${table} AS fence
+           (scheduler_schema, epoch, mode, canonical_reader_proof)
+         VALUES ($1, $2, $3, $4::jsonb)
+         ON CONFLICT (scheduler_schema) DO UPDATE
+           SET epoch = EXCLUDED.epoch,
+               mode = EXCLUDED.mode,
+               canonical_reader_proof = EXCLUDED.canonical_reader_proof,
+               updated_at = now()
+         WHERE (
+           fence.epoch < EXCLUDED.epoch
+           AND NOT (
+             fence.mode = 'canonical_v1'
+             AND EXCLUDED.mode <> 'canonical_v1'
+           )
+         ) OR (
+           fence.epoch = EXCLUDED.epoch
+           AND fence.mode = EXCLUDED.mode
+           AND fence.canonical_reader_proof IS NOT DISTINCT FROM EXCLUDED.canonical_reader_proof
+         )
+         RETURNING ${returning}`,
+        [
+          candidate.schema,
+          candidate.epoch,
+          candidate.mode,
+          candidate.canonicalReaderProof
+            ? stringifyPostgresJson(candidate.canonicalReaderProof)
+            : null,
+        ],
+      );
+      const applied = result.rows[0];
+      if (applied) {
+        const fence = parseRow(applied);
+        return before && sameFence(before, candidate)
+          ? { kind: 'already_applied', fence }
+          : { kind: 'advanced', fence };
+      }
+
+      const current = await read({ schema: candidate.schema });
+      if (!current) {
+        throw new Error('Runtime Gateway Reader Fence apply lost its row.');
+      }
+      if (candidate.epoch < current.epoch) {
+        return { kind: 'rejected', reason: 'stale_epoch', current };
+      }
+      if (
+        current.mode === 'canonical_v1' &&
+        candidate.mode !== 'canonical_v1'
+      ) {
+        return { kind: 'rejected', reason: 'unsafe_mode_downgrade', current };
+      }
+      return { kind: 'rejected', reason: 'epoch_conflict', current };
+    },
+  };
+}