@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/manifest.d.ts

@@ -21,7 +21,7 @@ export declare const PropertyManifest: Schema.Struct<{
     readonly column: Schema.optionalKey<Schema.String>;
     readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
     readonly name: Schema.String;
-    readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+    readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
     readonly label: Schema.String;
     readonly description: Schema.optionalKey<Schema.String>;
     readonly optional: Schema.Boolean;
@@ -33,6 +33,8 @@ export declare const PropertyManifest: Schema.Struct<{
     readonly min: Schema.optionalKey<Schema.Number>;
     readonly max: Schema.optionalKey<Schema.Number>;
     readonly maxLength: Schema.optionalKey<Schema.Number>;
+    readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly maxBytes: Schema.optionalKey<Schema.Number>;
     readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
         readonly value: Schema.String;
         readonly label: Schema.String;
@@ -83,6 +85,14 @@ export declare const ActionManifest: Schema.Struct<{
      * when there are some; absent reads as none.
      */
     readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    /**
+     * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+     * declares hints; absent reads as destructive and not idempotent.
+     */
+    readonly hints: Schema.optionalKey<Schema.Struct<{
+        readonly destructive: Schema.optionalKey<Schema.Boolean>;
+        readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+    }>>;
 }>;
 export type ActionManifest = typeof ActionManifest.Type;
 /**
@@ -126,7 +136,7 @@ export declare const EntityManifest: Schema.Struct<{
         readonly column: Schema.optionalKey<Schema.String>;
         readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
         readonly name: Schema.String;
-        readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+        readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
         readonly label: Schema.String;
         readonly description: Schema.optionalKey<Schema.String>;
         readonly optional: Schema.Boolean;
@@ -138,6 +148,8 @@ export declare const EntityManifest: Schema.Struct<{
         readonly min: Schema.optionalKey<Schema.Number>;
         readonly max: Schema.optionalKey<Schema.Number>;
         readonly maxLength: Schema.optionalKey<Schema.Number>;
+        readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly maxBytes: Schema.optionalKey<Schema.Number>;
         readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
             readonly value: Schema.String;
             readonly label: Schema.String;
@@ -182,6 +194,14 @@ export declare const EntityManifest: Schema.Struct<{
          * when there are some; absent reads as none.
          */
         readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        /**
+         * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+         * declares hints; absent reads as destructive and not idempotent.
+         */
+        readonly hints: Schema.optionalKey<Schema.Struct<{
+            readonly destructive: Schema.optionalKey<Schema.Boolean>;
+            readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+        }>>;
     }>>;
     /** Always written; absent from version 1 manifests. */
     readonly permissions: Schema.optionalKey<Schema.Struct<{
@@ -227,7 +247,7 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -239,6 +259,8 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -247,6 +269,7 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
         }>, {
             readonly renamedFrom: "renamed_from";
             readonly maxLength: "max_length";
+            readonly maxBytes: "max_bytes";
         }>>;
         readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
             readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
@@ -311,6 +334,14 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
              * when there are some; absent reads as none.
              */
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            /**
+             * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+             * declares hints; absent reads as destructive and not idempotent.
+             */
+            readonly hints: Schema.optionalKey<Schema.Struct<{
+                readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+            }>>;
         }>>;
         /** Always written; absent from version 1 manifests. */
         readonly permissions: Schema.optionalKey<Schema.Struct<{
@@ -359,7 +390,7 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -371,6 +402,8 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -379,6 +412,7 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
         }>, {
             readonly renamedFrom: "renamed_from";
             readonly maxLength: "max_length";
+            readonly maxBytes: "max_bytes";
         }>>;
         readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
             readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
@@ -443,6 +477,14 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
              * when there are some; absent reads as none.
              */
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            /**
+             * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+             * declares hints; absent reads as destructive and not idempotent.
+             */
+            readonly hints: Schema.optionalKey<Schema.Struct<{
+                readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+            }>>;
         }>>;
         /** Always written; absent from version 1 manifests. */
         readonly permissions: Schema.optionalKey<Schema.Struct<{
@@ -514,7 +556,7 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly column: Schema.optionalKey<Schema.String>;
             readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly name: Schema.String;
-            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+            readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
             readonly label: Schema.String;
             readonly description: Schema.optionalKey<Schema.String>;
             readonly optional: Schema.Boolean;
@@ -526,6 +568,8 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly min: Schema.optionalKey<Schema.Number>;
             readonly max: Schema.optionalKey<Schema.Number>;
             readonly maxLength: Schema.optionalKey<Schema.Number>;
+            readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly maxBytes: Schema.optionalKey<Schema.Number>;
             readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                 readonly value: Schema.String;
                 readonly label: Schema.String;
@@ -570,6 +614,14 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
              * when there are some; absent reads as none.
              */
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            /**
+             * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+             * declares hints; absent reads as destructive and not idempotent.
+             */
+            readonly hints: Schema.optionalKey<Schema.Struct<{
+                readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+            }>>;
         }>>;
         /** Always written; absent from version 1 manifests. */
         readonly permissions: Schema.optionalKey<Schema.Struct<{
@@ -617,13 +669,17 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             };
             readonly permission?: string | undefined;
             readonly connections?: readonly string[] | undefined;
+            readonly hints?: {
+                readonly destructive?: boolean | undefined;
+                readonly idempotent?: boolean | undefined;
+            } | undefined;
         }[];
         readonly title: string;
         readonly properties: readonly {
             readonly optional: boolean;
             readonly name: string;
             readonly label: string;
-            readonly type: "number" | "boolean" | "text" | "integer" | "date" | "timestamp" | "select" | "email" | "url" | "json";
+            readonly type: "number" | "boolean" | "text" | "integer" | "date" | "timestamp" | "select" | "email" | "url" | "json" | "blob";
             readonly unique: boolean;
             readonly managed: boolean;
             readonly column?: string | undefined;
@@ -640,6 +696,8 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             }[] | undefined;
             readonly renamedFrom?: string | undefined;
             readonly display?: string | undefined;
+            readonly accept?: readonly string[] | undefined;
+            readonly maxBytes?: number | undefined;
         }[];
         readonly relationships: readonly {
             readonly name: string;
@@ -715,13 +773,17 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             };
             readonly permission?: string | undefined;
             readonly connections?: readonly string[] | undefined;
+            readonly hints?: {
+                readonly destructive?: boolean | undefined;
+                readonly idempotent?: boolean | undefined;
+            } | undefined;
         }[];
         readonly title: string;
         readonly properties: readonly {
             readonly optional: boolean;
             readonly name: string;
             readonly label: string;
-            readonly type: "number" | "boolean" | "text" | "integer" | "date" | "timestamp" | "select" | "email" | "url" | "json";
+            readonly type: "number" | "boolean" | "text" | "integer" | "date" | "timestamp" | "select" | "email" | "url" | "json" | "blob";
             readonly unique: boolean;
             readonly managed: boolean;
             readonly column?: string | undefined;
@@ -738,6 +800,8 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             }[] | undefined;
             readonly renamedFrom?: string | undefined;
             readonly display?: string | undefined;
+            readonly accept?: readonly string[] | undefined;
+            readonly maxBytes?: number | undefined;
         }[];
         readonly relationships: readonly {
             readonly name: string;

package/dist/manifest.js

@@ -36,6 +36,8 @@ export const PropertyManifest = Schema.Struct({
     min: Schema.optionalKey(Schema.Number),
     max: Schema.optionalKey(Schema.Number),
     maxLength: Schema.optionalKey(Schema.Number),
+    accept: Schema.optionalKey(Schema.Array(Schema.String)),
+    maxBytes: Schema.optionalKey(Schema.Number),
     options: Schema.optionalKey(Schema.Array(SelectOptionManifest)),
 });
 /**
@@ -77,6 +79,14 @@ export const ActionManifest = Schema.Struct({
      * when there are some; absent reads as none.
      */
     connections: Schema.optionalKey(Schema.Array(Schema.String)),
+    /**
+     * How the action behaves, as MCP tool annotations tell agents. Written only when the action
+     * declares hints; absent reads as destructive and not idempotent.
+     */
+    hints: Schema.optionalKey(Schema.Struct({
+        destructive: Schema.optionalKey(Schema.Boolean),
+        idempotent: Schema.optionalKey(Schema.Boolean),
+    })),
 });
 /**
  * The permissions of an entity's reads and generated actions, so that readers need not rebuild the
@@ -160,7 +170,11 @@ const OntologyManifestModel = Schema.Struct({
     /** The connections the actions call. Written only when there are some; absent reads as none. */
     connections: Schema.optionalKey(Schema.Array(ConnectionManifest)),
 });
-const PropertyManifestWire = PropertyManifest.pipe(Schema.encodeKeys({ renamedFrom: "renamed_from", maxLength: "max_length" }));
+const PropertyManifestWire = PropertyManifest.pipe(Schema.encodeKeys({
+    renamedFrom: "renamed_from",
+    maxLength: "max_length",
+    maxBytes: "max_bytes",
+}));
 const OnDeleteWire = Schema.Literals(["set_null", "cascade", "restrict"]).pipe(Schema.decodeTo(Schema.Literals(ON_DELETE), SchemaTransformation.transform({
     decode: (value) => (value === "set_null" ? "setNull" : value),
     encode: (value) => (value === "setNull" ? "set_null" : value),
@@ -265,6 +279,8 @@ function propertyManifest({ name, definition }) {
         ...(definition.min !== undefined ? { min: definition.min } : {}),
         ...(definition.max !== undefined ? { max: definition.max } : {}),
         ...(definition.maxLength !== undefined ? { maxLength: definition.maxLength } : {}),
+        ...(definition.accept !== undefined ? { accept: definition.accept } : {}),
+        ...(definition.maxBytes !== undefined ? { maxBytes: definition.maxBytes } : {}),
         ...(definition.options !== undefined
             ? {
                 options: definition.options.map((option) => ({
@@ -344,6 +360,7 @@ function entityManifest(resolved) {
             permission: action.permission,
             input: action.input ?? {},
             ...(action.connections.length > 0 ? { connections: [...action.connections] } : {}),
+            ...(action.hints !== undefined ? { hints: { ...action.hints } } : {}),
         })),
         permissions: { ...resolved.permissions },
     };

package/dist/migrate/apply.d.ts

@@ -54,6 +54,13 @@ export declare const applyMigration: (plan: MigrationPlan, options: ApplyMigrati
  * workspace database first as a dry run, then on production: the plan is made against each database's
  * own catalog.
  */
+/** The runtime's tables, beside the catalog and the entity tables. */
+export declare const RUNTIME_TABLES: ReadonlyArray<string>;
+/**
+ * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an
+ * earlier SDK migrated lacks the tables added since.
+ */
+export declare const readRuntimeTables: (input: CatalogInput) => Effect.Effect<ReadonlySet<string>, SqlError>;
 export declare const migrate: (input: MigrateInput) => Effect.Effect<{
     readonly plan: MigrationPlan;
     readonly result: MigrationResult;

package/dist/migrate/apply.js

@@ -3,7 +3,7 @@ import { canonicalJson, decodeManifestDocument, encodeManifest, manifestHash, }
 import { CatalogInvalid, CatalogMismatch, MigrationFailed, MigrationRefused } from "./errors.js";
 import { isNoopMigration } from "./model.js";
 import { planMigration } from "./plan.js";
-import { CATALOG_TABLE, quoteIdentifier } from "./storage.js";
+import { API_KEYS_TABLE, CATALOG_TABLE, OAUTH_TABLES, USER_ROLES_TABLE, quoteIdentifier, quoteLiteral, } from "./storage.js";
 const CATALOG = quoteIdentifier(CATALOG_TABLE);
 /** Serializes migrations of one database; transaction-scoped, so it ends with the transaction. */
 const MIGRATION_LOCK = "segmentstream.ontology.migration";
@@ -133,11 +133,28 @@ export const applyMigration = (plan, options) => Effect.gen(function* () {
  * workspace database first as a dry run, then on production: the plan is made against each database's
  * own catalog.
  */
+/** The runtime's tables, beside the catalog and the entity tables. */
+export const RUNTIME_TABLES = [
+    USER_ROLES_TABLE,
+    API_KEYS_TABLE,
+    ...OAUTH_TABLES,
+];
+/**
+ * The runtime tables the database has, for `planMigration`'s `existingTables`: a database that an
+ * earlier SDK migrated lacks the tables added since.
+ */
+export const readRuntimeTables = (input) => input.sql
+    .unsafe(`SELECT "tablename" AS "name" FROM "pg_catalog"."pg_tables" ` +
+    `WHERE "schemaname" = current_schema() ` +
+    `AND "tablename" IN (${RUNTIME_TABLES.map(quoteLiteral).join(", ")})`)
+    .pipe(Effect.map((rows) => new Set(rows.map((row) => row.name))));
 export const migrate = (input) => Effect.gen(function* () {
     const current = yield* readCatalog({ sql: input.sql });
+    const existingTables = yield* readRuntimeTables({ sql: input.sql });
     const plan = planMigration({
         current,
         target: input.target,
+        existingTables,
         ...(input.options === undefined ? {} : { options: input.options }),
     });
     const result = yield* applyMigration(plan, input);

package/dist/migrate/index.d.ts

@@ -1,4 +1,4 @@
-export { applyMigration, migrate, readCatalog } from "./apply.js";
+export { applyMigration, migrate, readCatalog, readRuntimeTables, RUNTIME_TABLES, } from "./apply.js";
 export type { ApplyMigrationError, ApplyMigrationOptions, CatalogInput, MigrateInput, MigrationResult, } from "./apply.js";
 export { CatalogInvalid, CatalogMismatch, MigrationFailed, MigrationRefused } from "./errors.js";
 export { isNoopMigration, MIGRATION_REFUSAL_CODES, MIGRATION_STEP_CLASSIFICATIONS, MIGRATION_STEP_KINDS, MigrationPlan, MigrationRefusal, MigrationStep, } from "./model.js";

package/dist/migrate/index.js

@@ -1,4 +1,4 @@
-export { applyMigration, migrate, readCatalog } from "./apply.js";
+export { applyMigration, migrate, readCatalog, readRuntimeTables, RUNTIME_TABLES, } from "./apply.js";
 export { CatalogInvalid, CatalogMismatch, MigrationFailed, MigrationRefused } from "./errors.js";
 export { isNoopMigration, MIGRATION_REFUSAL_CODES, MIGRATION_STEP_CLASSIFICATIONS, MIGRATION_STEP_KINDS, MigrationPlan, MigrationRefusal, MigrationStep, } from "./model.js";
 export { planMigration } from "./plan.js";

package/dist/migrate/model.d.ts

@@ -48,7 +48,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly column: Schema.optionalKey<Schema.String>;
                 readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly name: Schema.String;
-                readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+                readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
                 readonly label: Schema.String;
                 readonly description: Schema.optionalKey<Schema.String>;
                 readonly optional: Schema.Boolean;
@@ -60,6 +60,8 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly min: Schema.optionalKey<Schema.Number>;
                 readonly max: Schema.optionalKey<Schema.Number>;
                 readonly maxLength: Schema.optionalKey<Schema.Number>;
+                readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly maxBytes: Schema.optionalKey<Schema.Number>;
                 readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                     readonly value: Schema.String;
                     readonly label: Schema.String;
@@ -68,6 +70,7 @@ export declare const MigrationPlan: Schema.Struct<{
             }>, {
                 readonly renamedFrom: "renamed_from";
                 readonly maxLength: "max_length";
+                readonly maxBytes: "max_bytes";
             }>>;
             readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
                 readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
@@ -120,6 +123,10 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly permission: Schema.optionalKey<Schema.String>;
                 readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
                 readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly hints: Schema.optionalKey<Schema.Struct<{
+                    readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                    readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+                }>>;
             }>>;
             readonly permissions: Schema.optionalKey<Schema.Struct<{
                 readonly read: Schema.String;
@@ -182,7 +189,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly column: Schema.optionalKey<Schema.String>;
                 readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly name: Schema.String;
-                readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+                readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"]>;
                 readonly label: Schema.String;
                 readonly description: Schema.optionalKey<Schema.String>;
                 readonly optional: Schema.Boolean;
@@ -194,6 +201,8 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly min: Schema.optionalKey<Schema.Number>;
                 readonly max: Schema.optionalKey<Schema.Number>;
                 readonly maxLength: Schema.optionalKey<Schema.Number>;
+                readonly accept: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly maxBytes: Schema.optionalKey<Schema.Number>;
                 readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
                     readonly value: Schema.String;
                     readonly label: Schema.String;
@@ -225,6 +234,10 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly permission: Schema.optionalKey<Schema.String>;
                 readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
                 readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly hints: Schema.optionalKey<Schema.Struct<{
+                    readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                    readonly idempotent: Schema.optionalKey<Schema.Boolean>;
+                }>>;
             }>>;
             readonly permissions: Schema.optionalKey<Schema.Struct<{
                 readonly read: Schema.String;

package/dist/migrate/plan.d.ts

@@ -12,6 +12,12 @@ export interface PlanMigrationInput {
     readonly current: OntologyManifest | undefined;
     readonly target: OntologyManifest;
     readonly options?: MigrationOptions;
+    /**
+     * The runtime tables the database has, from `readRuntimeTables`. A database migrated by an earlier
+     * SDK lacks the tables added since, and the plan creates them. Without it, the plan assumes the
+     * database has every runtime table.
+     */
+    readonly existingTables?: ReadonlySet<string>;
 }
 /**
  * Plans the migration from the applied manifest to the target. It is pure: the same manifests always

package/dist/migrate/plan.js

@@ -1,5 +1,6 @@
+import { BLOB_TABLES_DDL } from "../storage/tables.js";
 import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
-import { CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
+import { CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, OAUTH_TABLES, OAUTH_TABLES_DDL, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, blobForeignKey, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
 function step(input) {
     return {
@@ -68,10 +69,27 @@ export function planMigration(input) {
         draft.runtimeTables.push(step({
             kind: "createCatalog",
             classification: "additive",
-            description: "Create the runtime's role assignment and API key tables.",
+            description: "Create the runtime's role assignment, API key and OAuth tables.",
             sql: RUNTIME_TABLES_DDL,
         }));
     }
+    else if (OAUTH_TABLES.some((table) => input.existingTables?.has(table) === false)) {
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the runtime's OAuth tables, which connect agents to the MCP server.",
+            sql: OAUTH_TABLES_DDL,
+        }));
+    }
+    if (storedTargets.some((entity) => entity.properties.some((property) => property.type === "blob")) &&
+        !current?.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))) {
+        draft.runtimeTables.push(step({
+            kind: "createCatalog",
+            classification: "additive",
+            description: "Create the ontology's file revision and upload tables.",
+            sql: BLOB_TABLES_DDL,
+        }));
+    }
     planDrops({ pairs, removedEntities, addedEntities, allowDrops, draft });
     const renamed = planRenames({ pairs, draft });
     const appliedNames = new Set(storageObjects(currentEntities)
@@ -573,6 +591,12 @@ function logicalRenames(pairs, refusals) {
                 path: `${pair.target.name}.properties.${to}`,
                 description: `Rename property ${pair.target.name}.${from} to ${to}.`,
                 apply: (model) => renameProperty(model, pair.target.id, from, to),
+                ...(pair.current.properties.some((property) => property.name === from && property.type === "blob")
+                    ? {
+                        metadataSql: ["_blobs", "_blob_uploads", "_blob_references"].map((table) => `UPDATE ${quoteIdentifier(table)} SET property_id = ${quoteLiteral(to)} ` +
+                            `WHERE entity_id = ${quoteLiteral(pair.target.id)} AND property_id = ${quoteLiteral(from)}`),
+                    }
+                    : {}),
             });
         }
     }
@@ -595,7 +619,7 @@ function planRenames(input) {
             kind: rename.kind,
             classification: "rename",
             description: rename.description,
-            sql: statements,
+            sql: [...statements, ...(rename.metadataSql ?? [])],
         }));
         model = next;
     }
@@ -893,6 +917,14 @@ function planEntityChanges(input) {
         }
     }
     for (const property of pair.addedProperties) {
+        if (property.type === "blob") {
+            draft.foreignKeys.push(step({
+                kind: "addProperty",
+                classification: "additive",
+                description: `Reference the file revision for ${entity}.${property.name}.`,
+                sql: [addConstraintStatement(table, blobForeignKey(entity, property))],
+            }));
+        }
         const enumStorage = propertyEnum(entity, property);
         const check = propertyCheck(entity, property);
         const column = propertyColumn(entity, property);

package/dist/migrate/storage.d.ts

@@ -30,6 +30,7 @@ export declare const COLUMN_TYPES: {
     readonly date: "date";
     readonly timestamp: "timestamptz";
     readonly json: "jsonb";
+    readonly blob: "uuid";
 };
 export interface ColumnStorage {
     readonly name: string;
@@ -130,6 +131,7 @@ export declare function checkExpression(property: PropertyManifest): string | un
 export declare function propertyColumn(entity: string, property: PropertyManifest): ColumnStorage;
 export declare function propertyCheck(entity: string, property: PropertyManifest): ConstraintStorage | undefined;
 export declare function propertyEnum(entity: string, property: PropertyManifest): EnumStorage | undefined;
+export declare function blobForeignKey(entity: string, property: PropertyManifest): ConstraintStorage;
 /** The key column of a `rel.one`. */
 export declare function relationshipColumn(relationship: RelationshipManifest): ColumnStorage;
 /** The foreign key of a `rel.one`, with its `onDelete` action. */
@@ -149,6 +151,18 @@ export declare const USER_ROLES_TABLE = "_user_roles";
  * secret only as a salted PBKDF2 hash.
  */
 export declare const API_KEYS_TABLE = "_api_keys";
+/** OAuth clients that registered themselves to connect agents to the MCP server. */
+export declare const OAUTH_CLIENTS_TABLE = "_oauth_clients";
+/** Authorization requests waiting for a member's consent, for a few minutes. */
+export declare const OAUTH_REQUESTS_TABLE = "_oauth_requests";
+/** What a member allowed a client to do: revoking a grant stops its tokens. */
+export declare const OAUTH_GRANTS_TABLE = "_oauth_grants";
+/** Authorization codes, access tokens and refresh tokens, stored only as SHA-256 hashes. */
+export declare const OAUTH_TOKENS_TABLE = "_oauth_tokens";
+/** The OAuth tables, in the order they are created. */
+export declare const OAUTH_TABLES: ReadonlyArray<string>;
+/** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
+export declare const OAUTH_TABLES_DDL: ReadonlyArray<string>;
 /**
  * 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.