deepline 0.3.88 → 0.3.90

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

@@ -0,0 +1,66 @@
+/**
+ * The storage format a gateway may write for one Runtime Postgres schema.
+ *
+ * `canonical_v1` is deliberately a reader capability, not a deploy toggle:
+ * every gateway which can encounter the schema must be able to materialize
+ * canonical operation outcomes before this mode is recorded.
+ */
+export type IntegrationOperationStorageMode =
+  | 'legacy_byte_reader'
+  | 'canonical_v1';
+
+export const INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY =
+  'integration-operation-canonical-v1' as const;
+
+export type RuntimeGatewayRole = 'receipt' | 'execution';
+
+/**
+ * Operator-verified evidence that both durable gateway reader fleets can
+ * understand canonical Integration Operation rows. The control-plane verifier
+ * collects this evidence; this module records and validates its shape.
+ */
+export type CanonicalReaderProof = {
+  capability: typeof INTEGRATION_OPERATION_CANONICAL_READER_CAPABILITY;
+  sourceSha: string;
+  machineIds: Readonly<Record<RuntimeGatewayRole, readonly string[]>>;
+};
+
+/**
+ * The local Runtime Postgres mirror of the control-plane reader fence.
+ * `schema` is the scheduler schema/namespace, never an application or lane.
+ */
+export type RuntimeGatewayReaderFence = {
+  schema: string;
+  /** Strictly positive, monotonically increasing within a schema. */
+  epoch: number;
+  mode: IntegrationOperationStorageMode;
+  canonicalReaderProof: CanonicalReaderProof | null;
+};
+
+export type RuntimeGatewayReaderFenceCandidate = RuntimeGatewayReaderFence;
+
+export type ReaderFenceWriterMode = {
+  mode: IntegrationOperationStorageMode;
+  /** `absent` and unavailable storage are intentionally legacy-only. */
+  source: 'fence' | 'absent' | 'fail_closed';
+  epoch: number | null;
+  failure?: 'store_unavailable' | 'invalid_record';
+};
+
+export type ReaderFenceApplyOutcome =
+  | { kind: 'advanced'; fence: RuntimeGatewayReaderFence }
+  | { kind: 'already_applied'; fence: RuntimeGatewayReaderFence }
+  | {
+      kind: 'rejected';
+      reason: 'stale_epoch' | 'epoch_conflict' | 'unsafe_mode_downgrade';
+      current: RuntimeGatewayReaderFence;
+    };
+
+export type RuntimeGatewayReaderFenceJob = {
+  /** Resolve the only format this gateway may write. Never returns canonical on uncertainty. */
+  writerMode(input: { schema: string }): Promise<ReaderFenceWriterMode>;
+  /** Advance the mirror only with a strictly newer epoch, or retry the exact same fence. */
+  apply(
+    candidate: RuntimeGatewayReaderFenceCandidate,
+  ): Promise<ReaderFenceApplyOutcome>;
+};

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/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 };
+    },
+  };
+}