@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/migrate/storage.js

@@ -0,0 +1,774 @@
+import { CONFIRMATION_TABLE, CONFIRMATION_DDL } from "../runtime/confirmations.js";
+import { isValueMatched, } from "../manifest.js";
+import { FEDERATION_TABLES_DDL } from "../runtime/federation-tables.js";
+/**
+ * The physical mapping of an ontology onto Postgres. The planner creates exactly these objects and the
+ * runtime reads and writes them, so every name here is part of the storage contract.
+ */
+/** Postgres silently truncates longer identifiers; the planner refuses names that would be truncated. */
+export const MAX_IDENTIFIER_LENGTH = 63;
+/** The one-row table that records the applied manifest. */
+export const CATALOG_TABLE = "_ontology";
+/** The built-in user entity's table. System columns and history principals refer to it. */
+export const USER_TABLE = "user";
+/** System properties and their columns, present on every entity table. */
+export const SYSTEM_COLUMNS = {
+    id: "id",
+    created_at: "created_at",
+    updated_at: "updated_at",
+    created_by: "created_by",
+    updated_by: "updated_by",
+};
+/** The kinds of change a history row records. */
+export const HISTORY_KINDS = ["create", "update", "delete", "link", "unlink"];
+/**
+ * Column types of every property type except `select`, which gets an enum type of its own, and
+ * `list`, which has no column: the runtime reads it from the platform's tables.
+ */
+export const COLUMN_TYPES = {
+    text: "text",
+    email: "text",
+    url: "text",
+    integer: "bigint",
+    number: "double precision",
+    boolean: "boolean",
+    date: "date",
+    timestamp: "timestamptz",
+    json: "jsonb",
+    blob: "uuid",
+};
+/** Whether a property has a column: every type but `list`. */
+export function isStoredProperty(property) {
+    return property.type !== "list";
+}
+/** The entity with only the properties that have a column, as storage and migrations see it. */
+export function storedEntity(entity) {
+    return entity.properties.every(isStoredProperty)
+        ? entity
+        : { ...entity, properties: entity.properties.filter(isStoredProperty) };
+}
+const ON_DELETE_ACTIONS = {
+    setNull: "SET NULL",
+    cascade: "CASCADE",
+    restrict: "RESTRICT",
+};
+/** `"name"`, with embedded quotes doubled. */
+export function quoteIdentifier(name) {
+    return `"${name.replaceAll('"', '""')}"`;
+}
+/** `'value'`, with embedded quotes doubled (standard_conforming_strings is on). */
+export function quoteLiteral(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+// @legacy ontology.camelcase-member-names
+/** `fitScore` → `fit_score`. New property names already use snake_case; conversion remains for historical manifests. */
+export function snakeCase(name) {
+    return name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+/** An entity's table is named after the entity: `lead`, `user`. */
+export function tableName(entity) {
+    return entity;
+}
+export function historyTableName(entity) {
+    return `${entity}_history`;
+}
+/** The column of a property: `fitScore` → `fit_score`. */
+export function columnName(property) {
+    return snakeCase(property);
+}
+/** The key column of a `rel.one`: `owner` → `owner_id`. */
+export function relationshipColumnName(relationship) {
+    return `${snakeCase(relationship)}_id`;
+}
+/** The join table of a `rel.many`: `lead` + `tags` → `lead_tags`. */
+export function joinTableName(entity, relationship) {
+    return `${entity}_${snakeCase(relationship)}`;
+}
+/**
+ * The two key columns of a join table: `<entity>_id` and `<target>_id`. A relationship from an entity to
+ * itself names the target column after the relationship instead (`lead_id`, `related_id`).
+ */
+export function joinColumnNames(input) {
+    const source = `${input.entity}_id`;
+    const target = input.target === input.entity
+        ? relationshipColumnName(input.relationship)
+        : `${input.target}_id`;
+    return { source, target };
+}
+/** The enum type of a `select` property: `lead` + `status` → `lead_status`. */
+export function enumTypeName(entity, property) {
+    return `${entity}_${snakeCase(property)}`;
+}
+/** The unique index of a `unique: true` property. */
+export function uniqueIndexName(entity, property) {
+    return `${entity}_${snakeCase(property)}_key`;
+}
+/** The `CHECK` constraint holding a property's `maxLength`, `min` and `max`. */
+export function checkConstraintName(entity, property) {
+    return `${entity}_${snakeCase(property)}_check`;
+}
+export function foreignKeyName(table, column) {
+    return `${table}_${column}_fkey`;
+}
+export function primaryKeyName(table) {
+    return `${table}_pkey`;
+}
+/** An index over columns: `lead` + `status, created_at` → `lead_status_created_at_idx`. */
+export function indexName(table, columns) {
+    return `${table}_${columns.join("_")}_idx`;
+}
+/**
+ * The column of an index field: a system property (`created_at` → `created_at`), a property, or a
+ * stored `rel.one` (`owner` → `owner_id`). Returns undefined for anything else, value-matched
+ * relationships included: they have no column.
+ */
+export function fieldColumnName(entity, field) {
+    // @legacy ontology.camelcase-member-names
+    // Applied manifests may still name system fields in camelCase.
+    const historical = {
+        createdAt: "created_at",
+        updatedAt: "updated_at",
+        createdBy: "created_by",
+        updatedBy: "updated_by",
+    };
+    if (Object.hasOwn(historical, field)) {
+        return historical[field];
+    }
+    if (Object.hasOwn(SYSTEM_COLUMNS, field)) {
+        return SYSTEM_COLUMNS[field];
+    }
+    if (entity.properties.some((property) => property.name === field && isStoredProperty(property))) {
+        return columnName(field);
+    }
+    if (entity.relationships.some((relationship) => relationship.name === field &&
+        relationship.cardinality === "one" &&
+        !isValueMatched(relationship))) {
+        return relationshipColumnName(field);
+    }
+    return undefined;
+}
+/** The SQL default of a property, or undefined when it declares none. */
+export function defaultExpression(property) {
+    if (!("default" in property) || property.default === undefined) {
+        return undefined;
+    }
+    const value = property.default;
+    if (property.type === "json") {
+        return `${quoteLiteral(JSON.stringify(value))}::jsonb`;
+    }
+    if (value === null) {
+        return "NULL";
+    }
+    if (typeof value === "boolean" || typeof value === "number") {
+        return String(value);
+    }
+    return quoteLiteral(String(value));
+}
+/** The body of a property's `CHECK` constraint, or undefined when it has no bounds. */
+export function checkExpression(property) {
+    const column = quoteIdentifier(columnName(property.name));
+    const conditions = [];
+    if (property.type === "text" || property.type === "email" || property.type === "url") {
+        if (property.maxLength !== undefined) {
+            conditions.push(`char_length(${column}) <= ${property.maxLength}`);
+        }
+    }
+    if (property.type === "integer" || property.type === "number") {
+        if (property.min !== undefined) {
+            conditions.push(`${column} >= ${property.min}`);
+        }
+        if (property.max !== undefined) {
+            conditions.push(`${column} <= ${property.max}`);
+        }
+    }
+    return conditions.length === 0 ? undefined : conditions.join(" AND ");
+}
+export function propertyColumn(entity, property) {
+    if (property.type === "list") {
+        throw new Error(`${entity}.${property.name} is a list, which has no column.`);
+    }
+    const type = property.type === "select"
+        ? quoteIdentifier(enumTypeName(entity, property.name))
+        : COLUMN_TYPES[property.type];
+    const defaultValue = defaultExpression(property);
+    return {
+        name: columnName(property.name),
+        type,
+        notNull: !property.optional,
+        ...(defaultValue !== undefined ? { default: defaultValue } : {}),
+    };
+}
+export function propertyCheck(entity, property) {
+    const expression = checkExpression(property);
+    if (expression === undefined) {
+        return undefined;
+    }
+    return {
+        name: checkConstraintName(entity, property.name),
+        kind: "check",
+        definition: `CHECK (${expression})`,
+    };
+}
+export function propertyEnum(entity, property) {
+    if (property.type !== "select") {
+        return undefined;
+    }
+    return {
+        name: enumTypeName(entity, property.name),
+        values: (property.options ?? []).map((option) => option.value),
+    };
+}
+function foreignKeyDefinition(input) {
+    const reference = `FOREIGN KEY (${quoteIdentifier(input.column)}) ` +
+        `REFERENCES ${quoteIdentifier(input.references)} (${quoteIdentifier(SYSTEM_COLUMNS.id)})`;
+    return input.onDelete === undefined ? reference : `${reference} ON DELETE ${input.onDelete}`;
+}
+export function blobForeignKey(entity, property) {
+    const column = columnName(property.name);
+    return {
+        name: foreignKeyName(entity, column),
+        kind: "foreignKey",
+        definition: foreignKeyDefinition({ column, references: "_blobs" }),
+        references: "_blobs",
+    };
+}
+function userReference(table, column) {
+    return {
+        name: foreignKeyName(table, column),
+        kind: "foreignKey",
+        definition: foreignKeyDefinition({ column, references: USER_TABLE }),
+        references: USER_TABLE,
+    };
+}
+/** The key column of a `rel.one`. */
+export function relationshipColumn(relationship) {
+    return {
+        name: relationshipColumnName(relationship.name),
+        type: "uuid",
+        notNull: relationship.optional !== true,
+    };
+}
+/** The foreign key of a `rel.one`, with its `onDelete` action. */
+export function relationshipForeignKey(entity, relationship) {
+    const column = relationshipColumnName(relationship.name);
+    const onDelete = ON_DELETE_ACTIONS[relationship.onDelete ?? "restrict"];
+    return {
+        name: foreignKeyName(tableName(entity), column),
+        kind: "foreignKey",
+        definition: foreignKeyDefinition({ column, references: tableName(relationship.to), onDelete }),
+        references: tableName(relationship.to),
+    };
+}
+/** The join table of a `rel.many`: both keys cascade, and the target key is indexed. */
+export function joinTable(entity, relationship) {
+    const name = joinTableName(entity, relationship.name);
+    const keys = joinColumnNames({
+        entity,
+        relationship: relationship.name,
+        target: relationship.to,
+    });
+    return {
+        name,
+        columns: [
+            { name: keys.source, type: "uuid", notNull: true },
+            { name: keys.target, type: "uuid", notNull: true },
+            { name: SYSTEM_COLUMNS.created_at, type: "timestamptz", notNull: true, default: "now()" },
+            { name: SYSTEM_COLUMNS.created_by, type: "uuid", notNull: false },
+        ],
+        primaryKey: { name: primaryKeyName(name), columns: [keys.source, keys.target] },
+        constraints: [
+            {
+                name: foreignKeyName(name, keys.source),
+                kind: "foreignKey",
+                definition: foreignKeyDefinition({
+                    column: keys.source,
+                    references: tableName(entity),
+                    onDelete: "CASCADE",
+                }),
+                references: tableName(entity),
+            },
+            {
+                name: foreignKeyName(name, keys.target),
+                kind: "foreignKey",
+                definition: foreignKeyDefinition({
+                    column: keys.target,
+                    references: tableName(relationship.to),
+                    onDelete: "CASCADE",
+                }),
+                references: tableName(relationship.to),
+            },
+            userReference(name, SYSTEM_COLUMNS.created_by),
+        ],
+        indexes: [
+            {
+                name: indexName(name, [keys.target]),
+                table: name,
+                columns: [keys.target],
+                unique: false,
+                origin: `relationship ${entity}.${relationship.name}`,
+            },
+        ],
+    };
+}
+/** Covers rolling activity counts without reading the JSON history payloads. */
+export function historyActivityIndex(entity) {
+    const table = historyTableName(entity);
+    return {
+        name: `${table}_activity_idx`,
+        table,
+        columns: ["at", "principal_id"],
+        unique: false,
+        origin: `activity of ${entity}`,
+    };
+}
+/** `<entity>_history`: one row per change to a record, written by the runtime. */
+export function historyTable(entity) {
+    const name = historyTableName(entity);
+    const kinds = HISTORY_KINDS.map(quoteLiteral).join(", ");
+    return {
+        name,
+        columns: [
+            { name: "id", type: "uuid", notNull: true, default: "gen_random_uuid()" },
+            { name: "record_id", type: "uuid", notNull: true },
+            { name: "action", type: "text", notNull: true },
+            { name: "action_id", type: "uuid", notNull: true },
+            { name: "kind", type: "text", notNull: true },
+            { name: "principal_id", type: "uuid", notNull: false },
+            { name: "at", type: "timestamptz", notNull: true, default: "now()" },
+            { name: "changes", type: "jsonb", notNull: true },
+        ],
+        primaryKey: { name: primaryKeyName(name), columns: ["id"] },
+        constraints: [
+            {
+                name: `${name}_kind_check`,
+                kind: "check",
+                definition: `CHECK (${quoteIdentifier("kind")} IN (${kinds}))`,
+            },
+        ],
+        indexes: [
+            historyActivityIndex(entity),
+            {
+                name: indexName(name, ["record_id", "at"]),
+                table: name,
+                columns: ["record_id", "at"],
+                unique: false,
+                origin: `history of ${entity}`,
+            },
+            {
+                name: indexName(name, ["action_id"]),
+                table: name,
+                columns: ["action_id"],
+                unique: false,
+                origin: `history of ${entity}`,
+            },
+        ],
+    };
+}
+function systemColumns() {
+    return [
+        { name: SYSTEM_COLUMNS.id, type: "uuid", notNull: true, default: "gen_random_uuid()" },
+        { name: SYSTEM_COLUMNS.created_at, type: "timestamptz", notNull: true, default: "now()" },
+        { name: SYSTEM_COLUMNS.updated_at, type: "timestamptz", notNull: true, default: "now()" },
+        { name: SYSTEM_COLUMNS.created_by, type: "uuid", notNull: false },
+        { name: SYSTEM_COLUMNS.updated_by, type: "uuid", notNull: false },
+    ];
+}
+/**
+ * The indexes of an entity table: a unique index per unique property, an index per `rel.one` key and
+ * the declared indexes. A declared index over exactly one `rel.one` key has the key index's name and
+ * replaces it.
+ */
+function entityIndexes(entity) {
+    const table = tableName(entity.name);
+    const declared = entity.indexes.map((index) => {
+        const columns = index.properties.map((field) => fieldColumnName(entity, field) ?? field);
+        return {
+            name: indexName(table, columns),
+            table,
+            columns,
+            unique: index.unique,
+            origin: `declared index (${index.properties.join(", ")})`,
+        };
+    });
+    const declaredNames = new Set(declared.map((index) => index.name));
+    const unique = entity.properties
+        .filter((property) => property.unique)
+        .map((property) => ({
+        name: uniqueIndexName(entity.name, property.name),
+        table,
+        columns: [columnName(property.name)],
+        unique: true,
+        origin: `${entity.name}.${property.name} is unique`,
+    }));
+    const keys = keyedRelationships(entity)
+        .map((relationship) => ({
+        name: indexName(table, [relationshipColumnName(relationship.name)]),
+        table,
+        columns: [relationshipColumnName(relationship.name)],
+        unique: false,
+        origin: `relationship ${entity.name}.${relationship.name}`,
+    }))
+        .filter((index) => !declaredNames.has(index.name));
+    return [...unique, ...keys, ...declared];
+}
+/**
+ * The `rel.one` relationships that have a key column and a foreign key: those between stored
+ * entities. A value-matched relationship is stored as the ordinary property its `on` names.
+ */
+function keyedRelationships(entity) {
+    return entity.relationships.filter((relationship) => relationship.cardinality === "one" && !isValueMatched(relationship));
+}
+/** The table, history table, enum types and join tables of an entity. */
+export function entityStorage(declared) {
+    const entity = storedEntity(declared);
+    const table = tableName(entity.name);
+    const ones = keyedRelationships(entity);
+    const manys = entity.relationships.filter((relationship) => relationship.cardinality === "many");
+    const checks = entity.properties.flatMap((property) => {
+        const check = propertyCheck(entity.name, property);
+        return check === undefined ? [] : [check];
+    });
+    return {
+        entity: entity.name,
+        table: {
+            name: table,
+            columns: [
+                ...systemColumns(),
+                ...entity.properties.map((property) => propertyColumn(entity.name, property)),
+                ...ones.map(relationshipColumn),
+            ],
+            primaryKey: { name: primaryKeyName(table), columns: [SYSTEM_COLUMNS.id] },
+            constraints: [
+                userReference(table, SYSTEM_COLUMNS.created_by),
+                userReference(table, SYSTEM_COLUMNS.updated_by),
+                ...checks,
+                ...entity.properties
+                    .filter((property) => property.type === "blob")
+                    .map((property) => blobForeignKey(entity.name, property)),
+                ...ones.map((relationship) => relationshipForeignKey(entity.name, relationship)),
+            ],
+            indexes: entityIndexes(entity),
+        },
+        history: historyTable(entity.name),
+        enums: entity.properties.flatMap((property) => {
+            const storage = propertyEnum(entity.name, property);
+            return storage === undefined ? [] : [storage];
+        }),
+        joins: manys.map((relationship) => joinTable(entity.name, relationship)),
+    };
+}
+/** The `_ontology` catalog table. */
+export const CATALOG_TABLE_DDL = [
+    `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(CATALOG_TABLE)} (`,
+    `  "id" boolean NOT NULL DEFAULT true,`,
+    `  "version" integer NOT NULL,`,
+    `  "hash" text NOT NULL,`,
+    `  "manifest" jsonb NOT NULL,`,
+    `  "applied_at" timestamptz NOT NULL DEFAULT now(),`,
+    `  CONSTRAINT "${CATALOG_TABLE}_pkey" PRIMARY KEY ("id"),`,
+    `  CONSTRAINT "${CATALOG_TABLE}_id_check" CHECK ("id")`,
+    `)`,
+].join("\n");
+/** Role assignments: the roles a user holds beyond the `member` every active member has. */
+export const USER_ROLES_TABLE = "_user_roles";
+/**
+ * API keys. A key is `ssk_<key id>.<secret>`: the key id is stored in clear to find the row, the
+ * secret only as a salted PBKDF2 hash.
+ */
+export const API_KEYS_TABLE = "_api_keys";
+/** OAuth clients that registered themselves to connect agents to the MCP server. */
+export const OAUTH_CLIENTS_TABLE = "_oauth_clients";
+/** Authorization requests waiting for a member's consent, for a few minutes. */
+export const OAUTH_REQUESTS_TABLE = "_oauth_requests";
+/** What a member allowed a client to do: revoking a grant stops its tokens. */
+export const OAUTH_GRANTS_TABLE = "_oauth_grants";
+/** Authorization codes, access tokens and refresh tokens, stored only as SHA-256 hashes. */
+export const OAUTH_TOKENS_TABLE = "_oauth_tokens";
+/** The OAuth tables, in the order they are created. */
+export const OAUTH_TABLES = [
+    OAUTH_CLIENTS_TABLE,
+    OAUTH_REQUESTS_TABLE,
+    OAUTH_GRANTS_TABLE,
+    OAUTH_TOKENS_TABLE,
+    "_oauth_devices",
+    "_oauth_device_attempts",
+];
+/** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
+export const OAUTH_TABLES_DDL = [
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} (`,
+        `  "id" text NOT NULL,`,
+        `  "name" text NOT NULL,`,
+        `  "redirect_uris" jsonb NOT NULL,`,
+        `  "auth_method" text NOT NULL,`,
+        `  "secret_hash" text,`,
+        `  "client_uri" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  CONSTRAINT "${OAUTH_CLIENTS_TABLE}_pkey" PRIMARY KEY ("id")`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_REQUESTS_TABLE)} (`,
+        `  "id" text NOT NULL,`,
+        `  "client_id" text NOT NULL,`,
+        `  "redirect_uri" text NOT NULL,`,
+        `  "state" text,`,
+        `  "code_challenge" text NOT NULL,`,
+        `  "scope" text NOT NULL,`,
+        `  "resource" text NOT NULL,`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  CONSTRAINT "${OAUTH_REQUESTS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${OAUTH_REQUESTS_TABLE}_client_id_fkey" FOREIGN KEY ("client_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_GRANTS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "client_id" text NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "scope" text NOT NULL,`,
+        `  "resource" text NOT NULL,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_client_id_fkey" FOREIGN KEY ("client_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_CLIENTS_TABLE)} ("id") ON DELETE CASCADE,`,
+        `  CONSTRAINT "${OAUTH_GRANTS_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${OAUTH_GRANTS_TABLE}_user_id_idx" ` +
+        `ON ${quoteIdentifier(OAUTH_GRANTS_TABLE)} ("user_id")`,
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(OAUTH_TOKENS_TABLE)} (`,
+        `  "hash" text NOT NULL,`,
+        `  "grant_id" uuid NOT NULL,`,
+        `  "kind" text NOT NULL,`,
+        `  "redirect_uri" text,`,
+        `  "code_challenge" text,`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  "used_at" timestamptz,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_pkey" PRIMARY KEY ("hash"),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_kind_check" CHECK ("kind" IN ('code', 'access', 'refresh')),`,
+        `  CONSTRAINT "${OAUTH_TOKENS_TABLE}_grant_id_fkey" FOREIGN KEY ("grant_id") ` +
+            `REFERENCES ${quoteIdentifier(OAUTH_GRANTS_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${OAUTH_TOKENS_TABLE}_grant_id_idx" ` +
+        `ON ${quoteIdentifier(OAUTH_TOKENS_TABLE)} ("grant_id")`,
+    `ALTER TABLE "${OAUTH_GRANTS_TABLE}" ADD COLUMN IF NOT EXISTS "identity_id" uuid`,
+    `ALTER TABLE "_oauth_tokens" ADD COLUMN IF NOT EXISTS "replay" text`,
+    `ALTER TABLE "_oauth_tokens" ADD COLUMN IF NOT EXISTS "successor_hash" text`,
+    `CREATE TABLE IF NOT EXISTS "_oauth_devices" (
+    "hash" text PRIMARY KEY,
+    "user_code_hash" text NOT NULL UNIQUE,
+    "client_id" text NOT NULL REFERENCES "_oauth_clients" ("id") ON DELETE CASCADE,
+    "scope" text NOT NULL,
+    "resource" text NOT NULL,
+    "expires_at" timestamptz NOT NULL,
+    "interval" integer NOT NULL,
+    "next_poll_at" timestamptz NOT NULL DEFAULT now(),
+    "status" text NOT NULL DEFAULT 'pending',
+    "user_id" uuid REFERENCES "user" ("id") ON DELETE CASCADE
+  )`,
+    `CREATE TABLE IF NOT EXISTS "_oauth_device_attempts" (
+    "member_id" uuid PRIMARY KEY REFERENCES "user" ("id") ON DELETE CASCADE,
+    "window_at" timestamptz NOT NULL DEFAULT now(),
+    "attempts" integer NOT NULL DEFAULT 1
+  )`,
+];
+/** Channel accounts waiting, for ten minutes, for a member to claim them with a short code. */
+export const AGENT_PAIRINGS_TABLE = "_agent_pairings";
+/**
+ * Channel accounts paired with members, as SDKs before `user_identity` read them. The built-in
+ * `user_identity` entity holds them now, with the same ids; this table is still written beside it
+ * so that an earlier SDK deployed again finds them. See docs/workspace-user-identities.md.
+ */
+export const AGENT_IDENTITIES_TABLE = "_agent_identities";
+/**
+ * When a provisioned channel account was last shown the first-contact notice, keyed by its
+ * `user_identity` id: operational state, not identity data. It has no foreign key, so that an
+ * earlier SDK may still drop the `user_identity` table it does not know.
+ */
+export const IDENTITY_NOTICES_TABLE = "_identity_notices";
+/** Durable fixed-window admission and turn counters. */
+export const AGENT_COUNTERS_TABLE = "_agent_counters";
+/** User-scoped channel lifecycle and trusted effective limits shared across entry points. */
+export const CHANNEL_USERS_TABLE = "_channel_users";
+export const CHANNEL_LIMITS_TABLE = "_channel_limits";
+/** The agent's tables, in the order they are created. */
+export const AGENT_TABLES = [
+    AGENT_PAIRINGS_TABLE,
+    AGENT_IDENTITIES_TABLE,
+    AGENT_COUNTERS_TABLE,
+    CHANNEL_USERS_TABLE,
+    CHANNEL_LIMITS_TABLE,
+    CONFIRMATION_TABLE,
+    IDENTITY_NOTICES_TABLE,
+];
+/**
+ * The tables of the app's agent: pairing codes, stored only as SHA-256 hashes, the legacy channel
+ * identities they create, and the first-contact notices of `user_identity` channel accounts. An
+ * account and a member each have at most one live identity per provider. Every statement is
+ * idempotent.
+ */
+export const AGENT_TABLES_DDL = [
+    ...CONFIRMATION_DDL,
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(AGENT_PAIRINGS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "code_hash" text NOT NULL,`,
+        `  "provider" text NOT NULL,`,
+        `  "external_id" text NOT NULL,`,
+        `  "display" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "expires_at" timestamptz NOT NULL,`,
+        `  "consumed_at" timestamptz,`,
+        `  CONSTRAINT "${AGENT_PAIRINGS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${AGENT_PAIRINGS_TABLE}_code_hash_key" UNIQUE ("code_hash")`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "provider" text NOT NULL,`,
+        `  "external_id" text NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "display" text,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${AGENT_IDENTITIES_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${AGENT_IDENTITIES_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `ALTER TABLE "${AGENT_IDENTITIES_TABLE}" ADD COLUMN IF NOT EXISTS "origin" text NOT NULL DEFAULT 'paired'`,
+    `ALTER TABLE "${AGENT_IDENTITIES_TABLE}" ADD COLUMN IF NOT EXISTS "noticed_at" timestamptz`,
+    `ALTER TABLE "${AGENT_IDENTITIES_TABLE}" ADD COLUMN IF NOT EXISTS "notice_sha256" text`,
+    `CREATE TABLE IF NOT EXISTS "${AGENT_COUNTERS_TABLE}" (
+    "key" text NOT NULL,
+    "window_start" timestamptz NOT NULL,
+    "count" integer NOT NULL,
+    PRIMARY KEY ("key", "window_start")
+  )`,
+    `ALTER TABLE "${AGENT_COUNTERS_TABLE}" ADD COLUMN IF NOT EXISTS "notification_claim" uuid`,
+    `ALTER TABLE "${AGENT_COUNTERS_TABLE}" ADD COLUMN IF NOT EXISTS "notification_claimed_until" timestamptz`,
+    `ALTER TABLE "${AGENT_IDENTITIES_TABLE}" ADD COLUMN IF NOT EXISTS "username" text`,
+    `ALTER TABLE "${AGENT_IDENTITIES_TABLE}" ADD COLUMN IF NOT EXISTS "notice_version" text`,
+    `CREATE TABLE IF NOT EXISTS "${CHANNEL_USERS_TABLE}" (
+    "user_id" uuid PRIMARY KEY REFERENCES "${USER_TABLE}" ("id") ON DELETE CASCADE,
+    "created_via" text NOT NULL,
+    "blocked_at" timestamptz,
+    "on_new_user_completed_at" timestamptz
+  )`,
+    `INSERT INTO "${CHANNEL_USERS_TABLE}" ("user_id", "created_via")
+   SELECT DISTINCT ON ("user_id") "user_id", "provider" FROM "${AGENT_IDENTITIES_TABLE}"
+   WHERE "origin" = 'provisioned' ORDER BY "user_id", "created_at", "id"
+   ON CONFLICT ("user_id") DO NOTHING`,
+    `CREATE TABLE IF NOT EXISTS "${CHANNEL_LIMITS_TABLE}" (
+    "id" boolean PRIMARY KEY DEFAULT true CHECK ("id"),
+    "limits" jsonb NOT NULL
+  )`,
+    `CREATE INDEX IF NOT EXISTS "${AGENT_COUNTERS_TABLE}_window_idx" ` +
+        `ON "${AGENT_COUNTERS_TABLE}" ("window_start")`,
+    `CREATE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_user_idx" ` +
+        `ON "${AGENT_IDENTITIES_TABLE}" ("user_id")`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_account_key" ` +
+        `ON ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} ("provider", "external_id") ` +
+        `WHERE "revoked_at" IS NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS "${AGENT_IDENTITIES_TABLE}_member_key" ` +
+        `ON ${quoteIdentifier(AGENT_IDENTITIES_TABLE)} ("user_id", "provider") ` +
+        `WHERE "revoked_at" IS NULL`,
+    `CREATE TABLE IF NOT EXISTS "${IDENTITY_NOTICES_TABLE}" (
+    "identity_id" uuid PRIMARY KEY,
+    "noticed_at" timestamptz NOT NULL,
+    "notice_sha256" text,
+    "notice_version" text
+  )`,
+];
+/**
+ * The runtime's own tables beside the catalog. They are created with it, after the entity tables
+ * because they refer to the built-in user table, and every statement is idempotent.
+ */
+export const ACTION_ATTRIBUTION_TABLE = "_ontology_action_attribution";
+/** Runtime audit metadata deliberately has no foreign key: deleted records retain their history. */
+export const ACTION_ATTRIBUTION_DDL = [
+    `CREATE TABLE IF NOT EXISTS "${ACTION_ATTRIBUTION_TABLE}" (
+    "action_id" uuid PRIMARY KEY,
+    "execution" jsonb NOT NULL,
+    "at" timestamptz NOT NULL DEFAULT now()
+  )`,
+];
+export const RUNTIME_TABLES_DDL = [
+    ...FEDERATION_TABLES_DDL,
+    ...ACTION_ATTRIBUTION_DDL,
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(USER_ROLES_TABLE)} (`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "role" text NOT NULL,`,
+        `  CONSTRAINT "${USER_ROLES_TABLE}_pkey" PRIMARY KEY ("user_id", "role"),`,
+        `  CONSTRAINT "${USER_ROLES_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    [
+        `CREATE TABLE IF NOT EXISTS ${quoteIdentifier(API_KEYS_TABLE)} (`,
+        `  "id" uuid NOT NULL,`,
+        `  "user_id" uuid NOT NULL,`,
+        `  "key_id" text NOT NULL,`,
+        `  "salt" text NOT NULL,`,
+        `  "hash" text NOT NULL,`,
+        `  "label" text NOT NULL,`,
+        `  "created_at" timestamptz NOT NULL DEFAULT now(),`,
+        `  "revoked_at" timestamptz,`,
+        `  CONSTRAINT "${API_KEYS_TABLE}_pkey" PRIMARY KEY ("id"),`,
+        `  CONSTRAINT "${API_KEYS_TABLE}_key_id_key" UNIQUE ("key_id"),`,
+        `  CONSTRAINT "${API_KEYS_TABLE}_user_id_fkey" FOREIGN KEY ("user_id") ` +
+            `REFERENCES ${quoteIdentifier(USER_TABLE)} ("id") ON DELETE CASCADE`,
+        `)`,
+    ].join("\n"),
+    `CREATE INDEX IF NOT EXISTS "${API_KEYS_TABLE}_user_id_idx" ON ${quoteIdentifier(API_KEYS_TABLE)} ("user_id")`,
+    ...OAUTH_TABLES_DDL,
+    ...AGENT_TABLES_DDL,
+];
+export function columnDefinition(column) {
+    const parts = [quoteIdentifier(column.name), column.type];
+    if (column.notNull) {
+        parts.push("NOT NULL");
+    }
+    if (column.default !== undefined) {
+        parts.push(`DEFAULT ${column.default}`);
+    }
+    return parts.join(" ");
+}
+export function constraintDefinition(constraint) {
+    return `CONSTRAINT ${quoteIdentifier(constraint.name)} ${constraint.definition}`;
+}
+/** `CREATE TABLE` with every column, the primary key and the given constraints. */
+export function createTableStatement(table, constraints = table.constraints) {
+    const primaryKey = {
+        name: table.primaryKey.name,
+        definition: `PRIMARY KEY (${table.primaryKey.columns.map(quoteIdentifier).join(", ")})`,
+    };
+    const lines = [
+        ...table.columns.map(columnDefinition),
+        ...[primaryKey, ...constraints].map(constraintDefinition),
+    ];
+    return `CREATE TABLE ${quoteIdentifier(table.name)} (\n  ${lines.join(",\n  ")}\n)`;
+}
+export function createIndexStatement(index, options = {}) {
+    const unique = index.unique ? "UNIQUE " : "";
+    const concurrently = options.concurrently === true ? "CONCURRENTLY " : "";
+    const columns = index.columns.map(quoteIdentifier).join(", ");
+    return (`CREATE ${unique}INDEX ${concurrently}${quoteIdentifier(index.name)} ` +
+        `ON ${quoteIdentifier(index.table)} (${columns})`);
+}
+export function createEnumStatement(storage) {
+    const values = storage.values.map(quoteLiteral).join(", ");
+    return `CREATE TYPE ${quoteIdentifier(storage.name)} AS ENUM (${values})`;
+}
+export function addConstraintStatement(table, constraint) {
+    return `ALTER TABLE ${quoteIdentifier(table)} ADD ${constraintDefinition(constraint)}`;
+}