@emilia-protocol/gate 0.11.0 → 0.13.0

package/action-escrow-postgres.js

@@ -1,338 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
-/**
- * Durable Postgres backend for the Action Escrow state-machine store contract.
- *
- * Each transition compares the exact prior serialized snapshot and installs
- * the exact replacement in one SQL statement. Backend errors propagate; the
- * state machine must refuse rather than treating an outage as absent state.
- */
-import crypto from 'node:crypto';
-import { strictJsonGate } from './strict-json.js';
-
-export const ACTION_ESCROW_PG_STORE_VERSION = 'EP-ACTION-ESCROW-PG-STORE-v1';
-export const ACTION_ESCROW_STATE_TABLE = 'ep_action_escrow_state';
-export const ACTION_ESCROW_EVENT_TABLE = 'ep_action_escrow_state_events';
-export const ACTION_ESCROW_MAX_STATE_BYTES = 4 * 1024 * 1024;
-
-export const ACTION_ESCROW_STATE_DDL = `CREATE TABLE IF NOT EXISTS ${ACTION_ESCROW_STATE_TABLE} (
-  agreement_key TEXT PRIMARY KEY,
-  revision      BIGINT NOT NULL CHECK (revision >= 0),
-  record_json   TEXT NOT NULL,
-  updated_at    BIGINT NOT NULL,
-CHECK (octet_length(record_json) <= ${ACTION_ESCROW_MAX_STATE_BYTES})
-);
-CREATE TABLE IF NOT EXISTS ${ACTION_ESCROW_EVENT_TABLE} (
-  agreement_key     TEXT NOT NULL,
-  revision          BIGINT NOT NULL CHECK (revision >= 0),
-  previous_revision BIGINT NULL,
-  record_json       TEXT NOT NULL,
-  record_digest     TEXT NOT NULL CHECK (record_digest ~ '^sha256:[0-9a-f]{64}$'),
-  recorded_at       BIGINT NOT NULL,
-  PRIMARY KEY (agreement_key, revision),
-  CHECK (
-    (revision = 0 AND previous_revision IS NULL)
-    OR previous_revision = revision - 1
-  ),
-  CHECK (octet_length(record_json) <= ${ACTION_ESCROW_MAX_STATE_BYTES})
-);
-REVOKE ALL ON ${ACTION_ESCROW_STATE_TABLE} FROM PUBLIC;
-REVOKE ALL ON ${ACTION_ESCROW_EVENT_TABLE} FROM PUBLIC;
-REVOKE UPDATE, DELETE, TRUNCATE ON ${ACTION_ESCROW_EVENT_TABLE} FROM PUBLIC;`;
-
-export function actionEscrowRuntimeGrantDdl(roleName) {
-  if (typeof roleName !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(roleName)) {
-    throw new TypeError('action-escrow runtime role name is invalid');
-  }
-  const role = `"${roleName}"`;
-  return `REVOKE ALL ON ${ACTION_ESCROW_STATE_TABLE} FROM ${role};
-REVOKE ALL ON ${ACTION_ESCROW_EVENT_TABLE} FROM ${role};
-GRANT SELECT, INSERT, UPDATE ON ${ACTION_ESCROW_STATE_TABLE} TO ${role};
-GRANT SELECT, INSERT ON ${ACTION_ESCROW_EVENT_TABLE} TO ${role};
-REVOKE DELETE, TRUNCATE ON ${ACTION_ESCROW_STATE_TABLE} FROM ${role};
-REVOKE UPDATE, DELETE, TRUNCATE ON ${ACTION_ESCROW_EVENT_TABLE} FROM ${role};`;
-}
-
-export const ACTION_ESCROW_STATE_SQL = Object.freeze({
-  health: `SELECT
-  to_regclass('public.${ACTION_ESCROW_STATE_TABLE}') IS NOT NULL AS table_ready,
-  to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}') IS NOT NULL AS event_table_ready,
-  CASE WHEN to_regclass('public.${ACTION_ESCROW_STATE_TABLE}') IS NULL THEN FALSE
-    ELSE has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_STATE_TABLE}'), 'SELECT')
-      AND has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_STATE_TABLE}'), 'INSERT')
-      AND has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_STATE_TABLE}'), 'UPDATE') END AS can_use,
-  CASE WHEN to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}') IS NULL THEN FALSE
-    ELSE has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}'), 'SELECT')
-      AND has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}'), 'INSERT') END AS can_append_history,
-  CASE WHEN to_regclass('public.${ACTION_ESCROW_STATE_TABLE}') IS NULL THEN TRUE
-    ELSE (SELECT relowner = (SELECT oid FROM pg_roles WHERE rolname = current_user)
-      FROM pg_class WHERE oid = to_regclass('public.${ACTION_ESCROW_STATE_TABLE}')) END AS owns_state_table,
-  CASE WHEN to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}') IS NULL THEN TRUE
-    ELSE (SELECT relowner = (SELECT oid FROM pg_roles WHERE rolname = current_user)
-      FROM pg_class WHERE oid = to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}')) END AS owns_event_table,
-  CASE WHEN to_regclass('public.${ACTION_ESCROW_STATE_TABLE}') IS NULL THEN TRUE
-    ELSE has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_STATE_TABLE}'), 'DELETE')
-      OR has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_STATE_TABLE}'), 'TRUNCATE') END AS can_destroy_state,
-  CASE WHEN to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}') IS NULL THEN TRUE
-    ELSE has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}'), 'UPDATE')
-      OR has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}'), 'DELETE')
-      OR has_table_privilege(current_user, to_regclass('public.${ACTION_ESCROW_EVENT_TABLE}'), 'TRUNCATE') END AS can_mutate_history`,
-  read: `SELECT revision, record_json FROM ${ACTION_ESCROW_STATE_TABLE} WHERE agreement_key = $1`,
-  history: `SELECT revision, previous_revision, record_json, record_digest, recorded_at
-FROM ${ACTION_ESCROW_EVENT_TABLE}
-WHERE agreement_key = $1
-ORDER BY revision ASC`,
-  create: `WITH installed AS (
-  INSERT INTO ${ACTION_ESCROW_STATE_TABLE} (agreement_key, revision, record_json, updated_at)
-  VALUES ($1, 0, $2, $3)
-  ON CONFLICT (agreement_key) DO NOTHING
-  RETURNING agreement_key, revision, record_json, updated_at
-), journaled AS (
-  INSERT INTO ${ACTION_ESCROW_EVENT_TABLE}
-    (agreement_key, revision, previous_revision, record_json, record_digest, recorded_at)
-  SELECT agreement_key, revision, NULL, record_json, $4, updated_at
-  FROM installed
-  RETURNING revision
-)
-SELECT revision FROM journaled`,
-  compareAndSwap: `WITH installed AS (
-UPDATE ${ACTION_ESCROW_STATE_TABLE}
-SET revision = $3, record_json = $4, updated_at = $5
-WHERE agreement_key = $1 AND revision = $2 AND updated_at <= $5
-RETURNING agreement_key, revision, record_json, updated_at
-), journaled AS (
-  INSERT INTO ${ACTION_ESCROW_EVENT_TABLE}
-    (agreement_key, revision, previous_revision, record_json, record_digest, recorded_at)
-  SELECT agreement_key, revision, $2, record_json, $6, updated_at
-  FROM installed
-  RETURNING revision
-)
-SELECT revision FROM journaled`,
-});
-
-function validKey(value) {
-  return typeof value === 'string'
-    && value.length >= 1
-    && value.length <= 512
-    && !/[\u0000-\u001f\u007f]/.test(value);
-}
-
-function parsedState(value) {
-  if (typeof value !== 'string'
-    || Buffer.byteLength(value, 'utf8') > ACTION_ESCROW_MAX_STATE_BYTES
-    || !strictJsonGate(value).ok) {
-    return null;
-  }
-  try {
-    const parsed = JSON.parse(value);
-    return parsed !== null
-      && typeof parsed === 'object'
-      && !Array.isArray(parsed)
-      && Object.getPrototypeOf(parsed) === Object.prototype
-      ? parsed
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-function recordDigest(value) {
-  return `sha256:${crypto.createHash('sha256').update(value, 'utf8').digest('hex')}`;
-}
-
-function assertResult(result, operation) {
-  if (!result || typeof result.rowCount !== 'number' || !Number.isSafeInteger(result.rowCount)
-    || result.rowCount < 0) {
-    throw new Error(`${operation}: malformed Postgres result`);
-  }
-  return result;
-}
-
-/**
- * @param {object} options
- * @param {(text:string, params:any[]) => Promise<{rowCount:number,rows?:any[]}>} options.query
- * @param {number|Function} [options.now=Date.now]
- */
-export function createActionEscrowPostgresStore({
-  query,
-  now = Date.now,
-} = {}) {
-  if (typeof query !== 'function') {
-    throw new TypeError('createActionEscrowPostgresStore requires an async pg-style query function');
-  }
-  let lastNow = Number.NEGATIVE_INFINITY;
-
-  function nowMs() {
-    const value = typeof now === 'function' ? now() : now;
-    if (!Number.isSafeInteger(value) || value < 0) {
-      throw new Error('action-escrow store clock must be a non-negative safe-integer epoch millisecond');
-    }
-    if (value < lastNow) {
-      throw new Error(`action-escrow store clock regression refused: ${value} < ${lastNow}`);
-    }
-    lastNow = value;
-    return value;
-  }
-
-  function assertKey(key) {
-    if (!validKey(key)) throw new TypeError('action-escrow agreement key is invalid');
-  }
-
-  function assertState(value, revision) {
-    const parsed = parsedState(value);
-    if (!parsed) {
-      throw new TypeError('action-escrow state must be bounded strict JSON text');
-    }
-    if (!Number.isSafeInteger(parsed.revision)
-      || parsed.revision < 0
-      || parsed.revision !== revision) {
-      throw new TypeError('action-escrow state revision must match the CAS revision');
-    }
-  }
-
-  async function loadHistory(key) {
-    const result = assertResult(
-      await query(ACTION_ESCROW_STATE_SQL.history, [key]),
-      'action-escrow history',
-    );
-    if (!Array.isArray(result.rows) || result.rows.length !== result.rowCount) {
-      throw new Error('action-escrow history: malformed Postgres result');
-    }
-    let previousRecordedAt = Number.NEGATIVE_INFINITY;
-    const history = result.rows.map((row, index) => {
-      const revision = Number(row?.revision);
-      const previousRevision = row?.previous_revision === null
-        ? null
-        : Number(row?.previous_revision);
-      const recordedAt = Number(row?.recorded_at);
-      if (!Number.isSafeInteger(revision)
-        || revision !== index
-        || previousRevision !== (revision === 0 ? null : revision - 1)
-        || !Number.isSafeInteger(recordedAt)
-        || recordedAt < 0
-        || recordedAt < previousRecordedAt
-        || !parsedState(row?.record_json)
-        || row?.record_digest !== recordDigest(row.record_json)) {
-        throw new Error('action-escrow history: invalid or non-contiguous event');
-      }
-      assertState(row.record_json, revision);
-      previousRecordedAt = recordedAt;
-      return Object.freeze({
-        revision,
-        previous_revision: previousRevision,
-        record_json: row.record_json,
-        record_digest: row.record_digest,
-        recorded_at: recordedAt,
-      });
-    });
-    return Object.freeze(history);
-  }
-
-  async function read(key) {
-    assertKey(key);
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-      const result = assertResult(
-        await query(ACTION_ESCROW_STATE_SQL.read, [key]),
-        'action-escrow read',
-      );
-      if (result.rowCount > 1
-        || !Array.isArray(result.rows)
-        || result.rows.length !== result.rowCount) {
-        throw new Error('action-escrow read: database returned malformed or ambiguous state');
-      }
-      const history = await loadHistory(key);
-      if (result.rowCount === 0) {
-        if (history.length === 0) return null;
-        continue;
-      }
-      if (!Number.isSafeInteger(Number(result.rows[0]?.revision))
-        || Number(result.rows[0].revision) < 0
-        || !parsedState(result.rows[0]?.record_json)) {
-        throw new Error('action-escrow read: database returned malformed or ambiguous state');
-      }
-      const revision = Number(result.rows[0].revision);
-      assertState(result.rows[0].record_json, revision);
-      const tail = history.at(-1);
-      if (tail?.revision === revision
-        && tail.record_json === result.rows[0].record_json
-        && tail.record_digest === recordDigest(result.rows[0].record_json)) {
-        return { revision, value: result.rows[0].record_json };
-      }
-    }
-    throw new Error('action-escrow read: state and append-only journal do not agree');
-  }
-
-  return Object.freeze({
-    version: ACTION_ESCROW_PG_STORE_VERSION,
-    durable: true,
-    atomicExpectedRevisionCas: true,
-    linearizableReads: true,
-    monotonicRevisions: true,
-    nonExpiring: true,
-    maxStateBytes: ACTION_ESCROW_MAX_STATE_BYTES,
-    async health() {
-      const result = assertResult(
-        await query(ACTION_ESCROW_STATE_SQL.health, []),
-        'action-escrow health',
-      );
-      if (result.rowCount !== 1 || !Array.isArray(result.rows) || result.rows.length !== 1) {
-        throw new Error('action-escrow health: malformed Postgres result');
-      }
-      return {
-        ok: result.rows[0].table_ready === true
-          && result.rows[0].event_table_ready === true
-          && result.rows[0].can_use === true
-          && result.rows[0].can_append_history === true
-          && result.rows[0].owns_state_table === false
-          && result.rows[0].owns_event_table === false
-          && result.rows[0].can_destroy_state === false
-          && result.rows[0].can_mutate_history === false,
-        version: ACTION_ESCROW_PG_STORE_VERSION,
-      };
-    },
-    read,
-    async readHistory(key) {
-      assertKey(key);
-      return loadHistory(key);
-    },
-    async compareAndSwap(key, expectedRevision, value) {
-      assertKey(key);
-      if (expectedRevision !== null
-        && (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0)) {
-        throw new TypeError('action-escrow expected revision is invalid');
-      }
-      const nextRevision = expectedRevision === null ? 0 : expectedRevision + 1;
-      assertState(value, nextRevision);
-      const sql = expectedRevision === null
-        ? ACTION_ESCROW_STATE_SQL.create
-        : ACTION_ESCROW_STATE_SQL.compareAndSwap;
-      const params = expectedRevision === null
-        ? [key, value, nowMs(), recordDigest(value)]
-        : [key, expectedRevision, nextRevision, value, nowMs(), recordDigest(value)];
-      const result = assertResult(
-        await query(sql, params),
-        'action-escrow compareAndSwap',
-      );
-      if (result.rowCount > 1) {
-        throw new Error('action-escrow compareAndSwap affected multiple rows');
-      }
-      if (result.rowCount === 0) return { applied: false, revision: null };
-      if (!Array.isArray(result.rows)
-        || result.rows.length !== 1
-        || Number(result.rows[0]?.revision) !== nextRevision) {
-        throw new Error('action-escrow compareAndSwap returned a malformed revision');
-      }
-      return { applied: true, revision: nextRevision };
-    },
-  });
-}
-
-export default {
-  ACTION_ESCROW_PG_STORE_VERSION,
-  ACTION_ESCROW_STATE_TABLE,
-  ACTION_ESCROW_EVENT_TABLE,
-  ACTION_ESCROW_MAX_STATE_BYTES,
-  ACTION_ESCROW_STATE_DDL,
-  actionEscrowRuntimeGrantDdl,
-  ACTION_ESCROW_STATE_SQL,
-  createActionEscrowPostgresStore,
-};
+// Compatibility entry point for the TypeScript action-escrow-postgres module.
+export * from './dist/action-escrow-postgres.js';
+export { default } from './dist/action-escrow-postgres.js';