@amerged/ohmyhost-cli 0.1.44 → 0.1.46

package/src/apps/product-cli/src/product-api.ts

@@ -20,6 +20,13 @@ import {
   type ProjectDatabaseWriteReceipt,
 } from "@ohmyhost/contracts/database-access";
 import { assertDatabaseCompute, type DatabaseCompute } from "@ohmyhost/contracts/database-compute";
+import {
+  DATABASE_TABLE_COLUMN_TYPES,
+  DATABASE_TABLE_DEFAULTS,
+  isDatabaseTableIdentifier,
+  type DatabaseTableColumnType,
+  type DatabaseTableDefault,
+} from "@ohmyhost/contracts/database-tables";
 import {
   assertDatabaseExecutionUsagePage,
   assertDatabaseSchedule,
@@ -33,6 +40,9 @@ import {
   assertDatabaseWebhookDeliveryPage,
   assertDatabaseWebhookPage,
   assertDatabaseWebhookReplayAccepted,
+  assertDatabaseWatch,
+  assertDatabaseWatchDeleted,
+  assertDatabaseWatchPage,
   assertDatabaseWebhookTest,
   type DatabaseExecutionUsagePage,
   type DatabaseSchedule,
@@ -45,7 +55,11 @@ import {
   type DatabaseWebhookCreated,
   type DatabaseWebhookDeleted,
   type DatabaseWebhookDeliveryPage,
-  type DatabaseWebhookEventType,
+  type DatabaseWatch,
+  type DatabaseWatchDeleted,
+  type DatabaseWatchPage,
+  type DatabaseWatchRequest,
+  type DatabaseWebhookEventPattern,
   type DatabaseWebhookPage,
   type DatabaseWebhookReplayAccepted,
   type DatabaseWebhookTestResult,
@@ -152,6 +166,10 @@ import {
   getProjectDatabaseWebhook,
   deleteProjectDatabaseWebhook,
   testProjectDatabaseWebhook,
+  createProjectDatabaseWatch,
+  listProjectDatabaseWatches,
+  deleteProjectDatabaseWatch,
+  createProjectDatabaseTable,
   listProjectDatabaseWebhookDeliveries,
   replayProjectDatabaseWebhookDelivery,
   setProjectDatabaseSchedule,
@@ -205,6 +223,39 @@ export interface ProjectCreateInput {
   readonly idempotencyKey: string;
 }
 
+/** One column of a table to create; nullable, identity and default are optional as the REST body allows. */
+export interface DatabaseTableColumnInput {
+  readonly name: string;
+  readonly type: DatabaseTableColumnType;
+  readonly nullable?: boolean;
+  readonly identity?: boolean;
+  readonly default?: DatabaseTableDefault;
+}
+
+export interface DatabaseTableCreateInput {
+  readonly table: string;
+  readonly columns: readonly DatabaseTableColumnInput[];
+  readonly primaryKey: readonly string[];
+}
+
+/** The created or identical existing table, every column with its concrete nullability and default. */
+export interface DatabaseTableAnswer {
+  readonly table: {
+    readonly environment: "dev" | "prod";
+    readonly schema: "public";
+    readonly table: string;
+    readonly columns: readonly {
+      readonly name: string;
+      readonly type: DatabaseTableColumnType;
+      readonly nullable: boolean;
+      readonly identity: boolean;
+      readonly default: DatabaseTableDefault | null;
+    }[];
+    readonly primary_key: readonly string[];
+    readonly created: boolean;
+  };
+}
+
 export interface ProductApi {
   readonly managedSource?: ManagedSourceApi;
   planProjectDataChange(input: {
@@ -328,7 +379,7 @@ export interface ProductApi {
     readonly environment: "dev" | "prod";
     readonly idempotencyKey: string;
     readonly url: string;
-    readonly eventTypes: readonly DatabaseWebhookEventType[];
+    readonly eventTypes: readonly DatabaseWebhookEventPattern[];
     readonly headers: Readonly<Record<string, string>>;
   }): Promise<DatabaseWebhookCreated>;
   listProjectDatabaseWebhooks(input: {
@@ -350,6 +401,28 @@ export interface ProductApi {
     readonly environment: "dev" | "prod";
     readonly webhookId: string;
   }): Promise<DatabaseWebhookTestResult>;
+  createProjectDatabaseWatch(input: {
+    readonly projectId: string;
+    readonly environment: "dev" | "prod";
+    readonly idempotencyKey: string;
+    readonly request: DatabaseWatchRequest;
+  }): Promise<DatabaseWatch>;
+  listProjectDatabaseWatches(input: {
+    readonly projectId: string;
+    readonly environment: "dev" | "prod";
+  }): Promise<DatabaseWatchPage>;
+  deleteProjectDatabaseWatch(input: {
+    readonly projectId: string;
+    readonly environment: "dev" | "prod";
+    readonly idempotencyKey: string;
+    readonly watchId: string;
+  }): Promise<DatabaseWatchDeleted>;
+  createProjectDatabaseTable(input: {
+    readonly projectId: string;
+    readonly environment: "dev" | "prod";
+    readonly idempotencyKey: string;
+    readonly request: DatabaseTableCreateInput;
+  }): Promise<DatabaseTableAnswer>;
   listProjectDatabaseWebhookDeliveries(input: {
     readonly projectId: string;
     readonly environment: "dev" | "prod";
@@ -566,9 +639,55 @@ export interface ProductApi {
 
 /** A webhook answer that names another environment, webhook or delivery than the request did. */
 const WEBHOOK_SCOPE_MISMATCH = "Webhook response scope mismatch";
+const WATCH_SCOPE_MISMATCH = "Watch response scope mismatch";
+const TABLE_SCOPE_MISMATCH = "Table response scope mismatch";
 /** A schedule answer that names another environment or schedule than the request did. */
 const SCHEDULE_SCOPE_MISMATCH = "Schedule response scope mismatch";
 
+/** The REST answer read exactly: no extra keys, closed column types and defaults, keys among the columns. */
+export function assertDatabaseTableAnswer(value: unknown): asserts value is DatabaseTableAnswer {
+  const table = isRecordValue(value) ? value["table"] : undefined;
+  const columns = isRecordValue(table) ? table["columns"] : undefined;
+  const primaryKey = isRecordValue(table) ? table["primary_key"] : undefined;
+  if (
+    !isRecordValue(table) ||
+    !hasExactKeys(table, ["environment", "schema", "table", "columns", "primary_key", "created"]) ||
+    (table["environment"] !== "dev" && table["environment"] !== "prod") ||
+    table["schema"] !== "public" ||
+    !isDatabaseTableIdentifier(table["table"]) ||
+    typeof table["created"] !== "boolean" ||
+    !Array.isArray(columns) ||
+    columns.length < 1 ||
+    !columns.every(isDatabaseTableAnswerColumn) ||
+    !Array.isArray(primaryKey) ||
+    !primaryKey.every((name: unknown) =>
+      columns.some((column: Record<string, unknown>) => column["name"] === name),
+    )
+  )
+    throw new TypeError("Invalid database table answer");
+}
+
+function isDatabaseTableAnswerColumn(value: unknown): boolean {
+  return (
+    isRecordValue(value) &&
+    hasExactKeys(value, ["name", "type", "nullable", "identity", "default"]) &&
+    isDatabaseTableIdentifier(value["name"]) &&
+    (DATABASE_TABLE_COLUMN_TYPES as readonly unknown[]).includes(value["type"]) &&
+    typeof value["nullable"] === "boolean" &&
+    typeof value["identity"] === "boolean" &&
+    (value["default"] === null ||
+      (DATABASE_TABLE_DEFAULTS as readonly unknown[]).includes(value["default"]))
+  );
+}
+
+function isRecordValue(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).sort().join(",") === [...keys].sort().join(",");
+}
+
 export class GeneratedSdkProductApi implements ProductApi {
   readonly #client: OhMyHostClient;
   public readonly managedSource: ManagedSourceApi;
@@ -889,6 +1008,87 @@ export class GeneratedSdkProductApi implements ProductApi {
     return value;
   }
 
+  public async createProjectDatabaseWatch(
+    input: Parameters<ProductApi["createProjectDatabaseWatch"]>[0],
+  ): Promise<DatabaseWatch> {
+    const value = await createProjectDatabaseWatch(
+      {
+        project_id: input.projectId,
+        "Idempotency-Key": input.idempotencyKey,
+        databaseWatchCreateRequest: {
+          environment: input.environment,
+          schema: input.request.schema,
+          table: input.request.table,
+          columns: [...input.request.columns],
+          operations: [...input.request.operations],
+        },
+      },
+      { client: this.#client },
+    );
+    assertDatabaseWatch(value);
+    if (
+      value.environment !== input.environment ||
+      value.schema !== input.request.schema ||
+      value.table !== input.request.table
+    )
+      throw new TypeError(WATCH_SCOPE_MISMATCH);
+    return value;
+  }
+
+  public async listProjectDatabaseWatches(
+    input: Parameters<ProductApi["listProjectDatabaseWatches"]>[0],
+  ): Promise<DatabaseWatchPage> {
+    const value = await listProjectDatabaseWatches(
+      { project_id: input.projectId, environment: input.environment },
+      { client: this.#client },
+    );
+    assertDatabaseWatchPage(value);
+    if (value.items.some((item) => item.environment !== input.environment))
+      throw new TypeError(WATCH_SCOPE_MISMATCH);
+    return value;
+  }
+
+  public async deleteProjectDatabaseWatch(
+    input: Parameters<ProductApi["deleteProjectDatabaseWatch"]>[0],
+  ): Promise<DatabaseWatchDeleted> {
+    const value = await deleteProjectDatabaseWatch(
+      {
+        project_id: input.projectId,
+        environment: input.environment,
+        "Idempotency-Key": input.idempotencyKey,
+        watch_id: input.watchId,
+      },
+      { client: this.#client },
+    );
+    assertDatabaseWatchDeleted(value);
+    if (value.id !== input.watchId) throw new TypeError(WATCH_SCOPE_MISMATCH);
+    return value;
+  }
+
+  public async createProjectDatabaseTable(
+    input: Parameters<ProductApi["createProjectDatabaseTable"]>[0],
+  ): Promise<DatabaseTableAnswer> {
+    const value = await createProjectDatabaseTable(
+      {
+        project_id: input.projectId,
+        "Idempotency-Key": input.idempotencyKey,
+        databaseTableCreateRequest: {
+          environment: input.environment,
+          table: input.request.table,
+          columns: [...input.request.columns],
+          ...(input.request.primaryKey.length === 0
+            ? {}
+            : { primary_key: [...input.request.primaryKey] }),
+        },
+      },
+      { client: this.#client },
+    );
+    assertDatabaseTableAnswer(value);
+    if (value.table.environment !== input.environment || value.table.table !== input.request.table)
+      throw new TypeError(TABLE_SCOPE_MISMATCH);
+    return value;
+  }
+
   /** The signing secret exists only in this answer; the CLI prints it once and stores nothing. */
   public async createProjectDatabaseWebhook(
     input: Parameters<ProductApi["createProjectDatabaseWebhook"]>[0],

package/src/packages/contracts/package.json

@@ -132,6 +132,11 @@
       "types": "./dist/database-events.d.ts",
       "import": "./dist/database-events.js"
     },
+    "./database-tables": {
+      "source": "./src/database-tables.ts",
+      "types": "./dist/database-tables.d.ts",
+      "import": "./dist/database-tables.js"
+    },
     "./functions": {
       "source": "./src/functions.ts",
       "types": "./dist/functions.d.ts",

package/src/packages/contracts/src/database-events.ts

@@ -11,6 +11,13 @@ export const DATABASE_WEBHOOK_EVENT_TYPES = [
   "database.deleted",
 ] as const;
 export type DatabaseWebhookEventType = (typeof DATABASE_WEBHOOK_EVENT_TYPES)[number];
+/** Row-change events of a watched table; the topic is derived from the table name by dataEventTopic. */
+export type DatabaseDataEventType = `data.${string}`;
+export type DatabaseWebhookEventPattern = DatabaseWebhookEventType | DatabaseDataEventType;
+export const DATABASE_WATCH_OPERATIONS = ["insert", "update", "delete"] as const;
+export type DatabaseWatchOperation = (typeof DATABASE_WATCH_OPERATIONS)[number];
+export const DATABASE_WATCH_MAX_COLUMNS = 32;
+export const DATABASE_WATCH_DEFAULT_SCHEMA = "public";
 /** Per environment; the platform-wide provider cap is shared by every customer. */
 export const DATABASE_WEBHOOK_LIMIT = 5;
 export const DATABASE_WEBHOOK_MAX_EVENT_TYPES = 16;
@@ -66,9 +73,41 @@ export type DatabaseWebhookDeliveryState = "pending" | "delivered" | "dead_lette
 export type DatabaseWebhookDeliveryError = "timeout" | "network" | "http" | "expired" | "permanent";
 export type DatabaseWebhookTestError = "timeout" | "network" | "http";
 
+export interface DatabaseWatchRequest {
+  readonly schema: string;
+  readonly table: string;
+  readonly columns: readonly string[];
+  readonly operations: readonly DatabaseWatchOperation[];
+}
+
+export interface DatabaseWatchTarget {
+  readonly schema: string;
+  readonly table: string;
+}
+
+export interface DatabaseWatch {
+  readonly id: string;
+  readonly environment: DatabaseEnvironment;
+  readonly schema: string;
+  readonly table: string;
+  readonly columns: readonly string[];
+  readonly operations: readonly DatabaseWatchOperation[];
+  readonly topic: string;
+  readonly event_type: DatabaseDataEventType;
+}
+
+export interface DatabaseWatchPage {
+  readonly items: readonly DatabaseWatch[];
+}
+
+export interface DatabaseWatchDeleted {
+  readonly id: string;
+  readonly deleted: true;
+}
+
 export interface DatabaseWebhookCreateRequest {
   readonly url: string;
-  readonly event_types: readonly DatabaseWebhookEventType[];
+  readonly event_types: readonly DatabaseWebhookEventPattern[];
   readonly headers: Readonly<Record<string, string>>;
 }
 
@@ -90,7 +129,7 @@ export interface DatabaseWebhook {
   readonly id: string;
   readonly environment: DatabaseEnvironment;
   readonly url: string;
-  readonly event_types: readonly DatabaseWebhookEventType[];
+  readonly event_types: readonly DatabaseWebhookEventPattern[];
   readonly header_names: readonly string[];
   readonly created_at: string;
 }
@@ -112,7 +151,7 @@ export interface DatabaseWebhookDeleted {
 export interface DatabaseWebhookDelivery {
   readonly id: string;
   readonly event_id: string;
-  readonly event_type: DatabaseWebhookEventType;
+  readonly event_type: DatabaseWebhookEventType | DatabaseDataEventType;
   readonly webhook_id: string;
   readonly state: DatabaseWebhookDeliveryState;
   readonly attempts: number;
@@ -197,7 +236,23 @@ export interface DatabaseExecutionUsagePage {
 const WEBHOOK_KEYS = ["id", "environment", "url", "event_types", "header_names", "created_at"];
 const WEBHOOK_ID_PATTERN = /^whk_[a-z0-9]{20}$/u;
 const DELIVERY_ID_PATTERN = /^dlv_[0-9a-f]{20}$/u;
-const EVENT_ID_PATTERN = /^evt_[0-9a-f]{20}$/u;
+const EVENT_ID_PATTERN =
+  /^(?:evt_[0-9a-f]{20}|[a-z][a-z0-9]{19}:[1-9][0-9]{0,15}:[1-9][0-9]{0,15})$/u;
+const DATA_SUBSCRIPTION_PATTERN = /^data\.(?:\*|[a-z][a-z0-9_]{0,47})$/u;
+const DATA_EVENT_TYPE_PATTERN = /^data\.[a-z][a-z0-9_]{0,47}$/u;
+const DATABASE_WATCH_ID_PATTERN = /^pgcf_watch_[0-9a-f]{8}$/u;
+const DATABASE_WATCH_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/u;
+const DATABASE_WATCH_FORBIDDEN_SCHEMAS = ["information_schema", "pgcf", "ohmyhost"];
+const DATABASE_WATCH_KEYS = [
+  "id",
+  "environment",
+  "schema",
+  "table",
+  "columns",
+  "operations",
+  "topic",
+  "event_type",
+];
 const SCHEDULE_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,62}$/u;
 const CURSOR_PATTERN = /^[A-Za-z0-9._|:=+/-]{1,200}$/u;
 const HEADER_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,63}$/u;
@@ -225,11 +280,79 @@ export function parseDatabaseWebhookId(value: unknown): string {
   return value;
 }
 
+export function parseDatabaseWatchId(value: unknown): string {
+  if (!isDatabaseWatchTriggerName(value)) throw new TypeError("Invalid database watch id");
+  return value;
+}
+
 export function parseDatabaseDeliveryId(value: unknown): string {
   if (!matches(value, DELIVERY_ID_PATTERN)) throw new TypeError("Invalid database delivery id");
   return value;
 }
 
+/** The trigger names of the watch service; migrations may not create them, so the watch count stays exact. */
+export function isDatabaseWatchTriggerName(value: unknown): value is string {
+  return matches(value, DATABASE_WATCH_ID_PATTERN);
+}
+
+/** Identifiers are plain SQL names: no quotes, dots or spaces; the caller quotes them. */
+export function isDatabaseWatchIdentifier(value: unknown): value is string {
+  return matches(value, DATABASE_WATCH_IDENTIFIER_PATTERN);
+}
+
+/** Reserved platform schemas stay out of reach; the check ignores case like PostgreSQL does. */
+export function isDatabaseWatchSchema(value: unknown): value is string {
+  if (!isDatabaseWatchIdentifier(value)) return false;
+  const lower = value.toLowerCase();
+  return !lower.startsWith("pg_") && !DATABASE_WATCH_FORBIDDEN_SCHEMAS.includes(lower);
+}
+
+/**
+ * The topic of a watched table, the same rule pgcf.capture applies in SQL: lower-case, every
+ * character outside [a-z0-9_] becomes '_', 't_' before a name that does not start with a letter,
+ * at most 48 characters. Lower-casing is per character, like PostgreSQL's simple lower() of the
+ * builtin C.UTF-8 locale that PGCF's initdb uses (SELECT lower(U&'\0130'), lower(U&'\212A') answers 'i' and 'k').
+ */
+export function dataEventTopic(tableName: string): string {
+  const mapped = Array.from(tableName, (character) => {
+    const lower = Array.from(character.toLowerCase())[0] ?? "_";
+    return /^[a-z0-9_]$/u.test(lower) ? lower : "_";
+  }).join("");
+  const topic = /^[a-z]/u.test(mapped) ? mapped : `t_${mapped}`;
+  return topic.slice(0, 48);
+}
+
+export function parseDatabaseWatchCreateRequest(value: unknown): DatabaseWatchRequest {
+  if (
+    !record(value) ||
+    !onlyKeys(value, ["schema", "table", "columns", "operations"]) ||
+    !isDatabaseWatchIdentifier(value["table"]) ||
+    !Array.isArray(value["columns"]) ||
+    value["columns"].length < 1 ||
+    value["columns"].length > DATABASE_WATCH_MAX_COLUMNS ||
+    !value["columns"].every(isDatabaseWatchIdentifier) ||
+    new Set(value["columns"]).size !== value["columns"].length
+  )
+    throw new TypeError("Invalid database watch request");
+  return {
+    ...parseDatabaseWatchTarget({ schema: value["schema"], table: value["table"] }),
+    columns: value["columns"] as string[],
+    operations: parseWatchOperations(value["operations"]),
+  };
+}
+
+export function parseDatabaseWatchTarget(value: unknown): DatabaseWatchTarget {
+  if (
+    !record(value) ||
+    !onlyKeys(value, ["schema", "table"]) ||
+    !isDatabaseWatchIdentifier(value["table"])
+  )
+    throw new TypeError("Invalid database watch target");
+  const schema = value["schema"] === undefined ? DATABASE_WATCH_DEFAULT_SCHEMA : value["schema"];
+  if (!isDatabaseWatchSchema(schema)) throw new TypeError("Invalid database watch target");
+  return { schema, table: value["table"] };
+}
+
 export function parseDatabaseScheduleName(value: unknown): string {
   if (!matches(value, SCHEDULE_NAME_PATTERN)) throw new TypeError("Invalid database schedule name");
   return value;
@@ -307,6 +430,41 @@ export function assertDatabaseWebhook(value: unknown): asserts value is Database
   assertWebhookFields(value);
 }
 
+export function assertDatabaseWatch(value: unknown): asserts value is DatabaseWatch {
+  if (
+    !record(value) ||
+    !exact(value, DATABASE_WATCH_KEYS) ||
+    !matches(value["id"], DATABASE_WATCH_ID_PATTERN) ||
+    !oneOf(["dev", "prod"] as const, value["environment"]) ||
+    !isDatabaseWatchSchema(value["schema"]) ||
+    !isDatabaseWatchIdentifier(value["table"]) ||
+    !Array.isArray(value["columns"]) ||
+    value["columns"].length < 1 ||
+    value["columns"].length > DATABASE_WATCH_MAX_COLUMNS ||
+    !value["columns"].every(isDatabaseWatchIdentifier) ||
+    !isCanonicalOperations(value["operations"]) ||
+    value["topic"] !== dataEventTopic(value["table"]) ||
+    value["event_type"] !== `data.${value["topic"]}`
+  )
+    throw new TypeError("Invalid database watch");
+}
+
+export function assertDatabaseWatchPage(value: unknown): asserts value is DatabaseWatchPage {
+  if (!record(value) || !exact(value, ["items"]) || !pageItems(value["items"]))
+    throw new TypeError("Invalid database watch page");
+  for (const item of value["items"]) assertDatabaseWatch(item);
+}
+
+export function assertDatabaseWatchDeleted(value: unknown): asserts value is DatabaseWatchDeleted {
+  if (
+    !record(value) ||
+    !exact(value, ["id", "deleted"]) ||
+    !matches(value["id"], DATABASE_WATCH_ID_PATTERN) ||
+    value["deleted"] !== true
+  )
+    throw new TypeError("Invalid database watch deletion");
+}
+
 export function assertDatabaseWebhookCreated(
   value: unknown,
 ): asserts value is DatabaseWebhookCreated {
@@ -358,7 +516,7 @@ export function assertDatabaseWebhookDelivery(
     ]) ||
     !matches(value["id"], DELIVERY_ID_PATTERN) ||
     !matches(value["event_id"], EVENT_ID_PATTERN) ||
-    !oneOf(DATABASE_WEBHOOK_EVENT_TYPES, value["event_type"]) ||
+    !isDeliveredEventType(value["event_type"]) ||
     !matches(value["webhook_id"], WEBHOOK_ID_PATTERN) ||
     !oneOf(["pending", "delivered", "dead_lettered"] as const, value["state"]) ||
     !nonNegativeInteger(value["attempts"]) ||
@@ -538,7 +696,7 @@ function assertWebhookFields(value: Record<string, unknown>): void {
     !Array.isArray(value["event_types"]) ||
     value["event_types"].length < 1 ||
     value["event_types"].length > DATABASE_WEBHOOK_MAX_EVENT_TYPES ||
-    !value["event_types"].every((type) => oneOf(DATABASE_WEBHOOK_EVENT_TYPES, type)) ||
+    !value["event_types"].every(isDatabaseWebhookEventPattern) ||
     !Array.isArray(value["header_names"]) ||
     value["header_names"].length > DATABASE_WEBHOOK_MAX_HEADERS ||
     !value["header_names"].every((name) => matches(name, HEADER_NAME_PATTERN)) ||
@@ -561,16 +719,55 @@ function isHttpsUrl(value: unknown): value is string {
   }
 }
 
-function parseEventTypes(value: unknown): readonly DatabaseWebhookEventType[] {
+export function isDatabaseWebhookEventPattern(
+  value: unknown,
+): value is DatabaseWebhookEventPattern {
+  return oneOf(DATABASE_WEBHOOK_EVENT_TYPES, value) || matches(value, DATA_SUBSCRIPTION_PATTERN);
+}
+
+/** A delivery names one concrete event: a platform type or one data topic, never a wildcard. */
+function isDeliveredEventType(
+  value: unknown,
+): value is DatabaseWebhookEventType | DatabaseDataEventType {
+  return oneOf(DATABASE_WEBHOOK_EVENT_TYPES, value) || matches(value, DATA_EVENT_TYPE_PATTERN);
+}
+
+/** Event types of one webhook: 1 to 16 distinct patterns; a bare `*` is not among them. */
+export function isDatabaseWebhookEventTypes(
+  value: unknown,
+): value is readonly DatabaseWebhookEventPattern[] {
+  return (
+    Array.isArray(value) &&
+    value.length >= 1 &&
+    value.length <= DATABASE_WEBHOOK_MAX_EVENT_TYPES &&
+    value.every(isDatabaseWebhookEventPattern) &&
+    new Set(value).size === value.length
+  );
+}
+
+function parseEventTypes(value: unknown): readonly DatabaseWebhookEventPattern[] {
+  if (!isDatabaseWebhookEventTypes(value))
+    throw new TypeError("Invalid database webhook event types");
+  return value;
+}
+
+function parseWatchOperations(value: unknown): readonly DatabaseWatchOperation[] {
+  if (value === undefined) return DATABASE_WATCH_OPERATIONS;
   if (
     !Array.isArray(value) ||
     value.length < 1 ||
-    value.length > DATABASE_WEBHOOK_MAX_EVENT_TYPES ||
-    !value.every((type) => oneOf(DATABASE_WEBHOOK_EVENT_TYPES, type)) ||
+    !value.every((operation) => oneOf(DATABASE_WATCH_OPERATIONS, operation)) ||
     new Set(value).size !== value.length
   )
-    throw new TypeError("Invalid database webhook event types");
-  return value as DatabaseWebhookEventType[];
+    throw new TypeError("Invalid database watch request");
+  return DATABASE_WATCH_OPERATIONS.filter((operation) => value.includes(operation));
+}
+
+/** Operations are stored and asserted in the canonical order insert, update, delete. */
+function isCanonicalOperations(value: unknown): value is DatabaseWatchOperation[] {
+  if (!Array.isArray(value) || value.length < 1) return false;
+  const canonical = DATABASE_WATCH_OPERATIONS.filter((operation) => value.includes(operation));
+  return canonical.length === value.length && canonical.every((op, index) => op === value[index]);
 }
 
 function parseHeaders(value: unknown): Record<string, string> {

package/src/packages/contracts/src/database-migration-admission.ts

@@ -1,4 +1,9 @@
+import { isDatabaseWatchTriggerName } from "./database-events.js";
 import { DatabaseMigrationAdmissionError } from "./database-migration-errors.js";
+import {
+  readMigrationCaptureTrigger,
+  type DatabaseMigrationCaptureTrigger,
+} from "./database-migration-capture.js";
 import {
   readMigrationSql,
   rejectMigrationSqlReferences,
@@ -11,6 +16,7 @@ import {
 
 export { DatabaseMigrationAdmissionError } from "./database-migration-errors.js";
 export type { DatabaseMigrationAdmissionReason } from "./database-migration-errors.js";
+export type { DatabaseMigrationCaptureTrigger } from "./database-migration-capture.js";
 export type { DatabaseMigrationRlsTarget } from "./database-migration-policies.js";
 
 const MAX_MIGRATION_COUNT = 128;
@@ -68,6 +74,16 @@ export function admitExpandOnlyMigrations(
       throw new DatabaseMigrationAdmissionError("invalid");
     }
     const statements = parseDatabaseMigrationStatements(sql);
+    // The watch service alone creates triggers under its reserved names, so the watch count stays exact.
+    if (
+      statements.some(
+        (statement) =>
+          statement.captureTrigger !== undefined &&
+          isDatabaseWatchTriggerName(statement.captureTrigger.trigger),
+      )
+    ) {
+      throw new DatabaseMigrationAdmissionError("unsupported");
+    }
     statementCount += statements.length;
     return Object.freeze({ path: migration.path, statementCount: statements.length });
   });
@@ -77,6 +93,7 @@ export function admitExpandOnlyMigrations(
 export interface DatabaseMigrationStatement {
   readonly sql: string;
   readonly rlsTarget?: DatabaseMigrationRlsTarget;
+  readonly captureTrigger?: DatabaseMigrationCaptureTrigger;
 }
 
 export function parseDatabaseMigrationStatements(
@@ -94,6 +111,11 @@ export function parseDatabaseMigrationStatements(
   if (statements.length === 0) throw new DatabaseMigrationAdmissionError("invalid");
   return Object.freeze(
     statements.map((statement) => {
+      const capture = readMigrationCaptureTrigger(statement.tokens);
+      if (capture !== undefined) {
+        rejectMigrationSqlReferences(capture.header);
+        return Object.freeze({ sql: statement.sql, captureTrigger: capture.target });
+      }
       // Provider references are forbidden throughout executable policy SQL, while
       // the native helper exception is narrowed by the policy reader below.
       rejectMigrationSqlReferences(statement.tokens, true);