@segmentstream-cloud/ontology 0.10.0 → 0.11.0

package/dist/action.d.ts

@@ -17,6 +17,17 @@ export interface ActionContext<Input, Prepared = undefined> extends PrepareConte
 }
 /** What `prepare` may fail with: the action errors, and connection calls that failed. */
 export type PrepareError = ActionError | ConnectionError;
+/**
+ * How an action behaves, as MCP tool annotations tell agents. Clients such as Claude ask the user
+ * before they run a destructive tool. Without hints an action is taken as destructive and not
+ * idempotent.
+ */
+export interface ActionHints {
+    /** Whether the action may overwrite or remove what someone decided. Default true. */
+    readonly destructive?: boolean;
+    /** Whether running it again with the same input changes nothing more. Default false. */
+    readonly idempotent?: boolean;
+}
 /** A described, typed, permissioned Effect function: the only way to change records. */
 export interface Action<Input extends Schema.Top = Schema.Top, Result = unknown> {
     readonly [ActionTypeId]: typeof ActionTypeId;
@@ -27,6 +38,8 @@ export interface Action<Input extends Schema.Top = Schema.Top, Result = unknown>
      * is not set, the action requires `<entity>:<action name>`, for example `lead:changeStatus`.
      */
     readonly permission: string | undefined;
+    /** How the action behaves, as `action({ hints })` set it; see {@link ActionHints}. */
+    readonly hints: ActionHints | undefined;
     /** The connections `prepare` may call; empty for an action without `prepare`. */
     readonly connections: ReadonlyArray<AnyConnectionHandle>;
     /**
@@ -64,6 +77,12 @@ interface ActionOptions<Input extends Schema.Top> {
      * Roles grant it in their `permissions`.
      */
     readonly permission?: string;
+    /**
+     * How the action behaves, for the agents that run it over MCP. Set `destructive: false` for an
+     * action that only adds or that history makes easy to reverse, and `idempotent: true` for one
+     * that a repeated call leaves as it was.
+     */
+    readonly hints?: ActionHints;
 }
 export interface ActionConfig<Input extends Schema.Top, Result> extends ActionOptions<Input> {
     /**

package/dist/action.js

@@ -11,6 +11,7 @@ export function action(config) {
         description: config.description,
         input: config.input,
         permission: config.permission,
+        hints: config.hints,
         connections: config.connections ?? [],
         ...(config.prepare === undefined ? {} : { prepare: config.prepare }),
         // A prepare-only action answers with what prepare returned; it writes nothing.

package/dist/analyze.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import { type Action } from "./action.js";
+import { type Action, type ActionHints } from "./action.js";
 import { type AnyConnectionHandle } from "./connection.js";
 import type { Diagnostic } from "./diagnostics.js";
 import { type AnyEntity } from "./entity.js";
@@ -67,6 +67,8 @@ export interface ResolvedAction {
     readonly input: JsonSchemaObject | undefined;
     /** The keys of the connections the action's `prepare` calls, in declaration order. */
     readonly connections: ReadonlyArray<string>;
+    /** The hints the action declares, or `undefined` when it declares none. */
+    readonly hints: ActionHints | undefined;
 }
 /** A connection the ontology declares. */
 export interface ResolvedConnection {

package/dist/analyze.js

@@ -5,7 +5,7 @@ import { BLOB_CONTENT_TYPES, MAX_BLOB_BYTES } from "./blob.js";
 import { isAction } from "./action.js";
 import { CONNECTION_KEY, isConnection } from "./connection.js";
 import { isEntity } from "./entity.js";
-import { LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MEMBER_ROLE, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
+import { LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MCP_READ_TOOLS, MCP_TOOL_NAME_MAX_LENGTH, MEMBER_ROLE, mcpToolName, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
 import { REFERENCE_ANNOTATION, propertyDefinition, referenceTarget, } from "./property.js";
 import { generatedActionPermissions, parsePermission, permissionOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";
 import { ON_DELETE, isRelationship } from "./relationship.js";
@@ -58,6 +58,7 @@ export function analyze(config, options = {}) {
     const resolved = entities.map((candidate) => resolveEntity(candidate, scope));
     checkEntityIdentities(resolved, report);
     checkMemberNames(resolved, report);
+    checkToolNames(resolved, report);
     checkWarehouseSource(resolved, report);
     checkConnectionsUsed(resolved, connections, config.connections ?? [], report);
     if (options.checkPermissions !== false) {
@@ -65,6 +66,58 @@ export function analyze(config, options = {}) {
     }
     return { entities: resolved, roles, signIn, connections, diagnostics };
 }
+/**
+ * The operations of a stored entity that become MCP tools, each with the path a problem is reported
+ * at: the reads, the generated actions and the authored actions.
+ */
+function toolOperations(candidate) {
+    const { permissions } = candidate;
+    const generated = [
+        ...(permissions.create !== undefined ? ["create", "update", "delete"] : []),
+        ...(permissions.create !== undefined
+            ? candidate.properties
+                .filter(({ definition }) => definition.unique)
+                .map(({ name }) => `${GENERATED_UPSERT_PREFIX}${name}`)
+            : []),
+        ...(permissions.link !== undefined ? ["link", "unlink"] : []),
+    ];
+    return [
+        ...[...MCP_READ_TOOLS, ...generated].map((operation) => ({ operation, path: candidate.name })),
+        // An authored action with a generated action's name is already refused as a reserved name.
+        ...candidate.actions
+            .filter(({ name }) => !GENERATED_ACTIONS.includes(name) && !GENERATED_UPSERT.test(name))
+            .map(({ name }) => ({ operation: name, path: `${candidate.name}.actions.${name}` })),
+    ];
+}
+/**
+ * Every MCP tool needs a name of its own, at most 64 characters long. A tool's name joins the
+ * entity's and the operation's with an underscore, so entity `pilot` with an action `request_find`
+ * would take the name of entity `pilot_request`'s `find`.
+ */
+function checkToolNames(entities, report) {
+    const owners = new Map();
+    const seen = new Set();
+    for (const candidate of entities) {
+        // A second entity with the same name is already refused as a duplicate.
+        if (candidate.entity.definition.source !== undefined || seen.has(candidate.name)) {
+            continue;
+        }
+        seen.add(candidate.name);
+        for (const { operation, path } of toolOperations(candidate)) {
+            const name = mcpToolName(candidate.name, operation);
+            const owner = owners.get(name);
+            if (owner !== undefined) {
+                report("invalid-tool-name", path, `its MCP tool ${name} is already the tool of ${owner}; rename one of them.`);
+                continue;
+            }
+            owners.set(name, `${candidate.name}'s ${operation}`);
+            if (name.length > MCP_TOOL_NAME_MAX_LENGTH) {
+                report("invalid-tool-name", path, `its MCP tool ${name} is ${name.length} characters long; agents accept at most ` +
+                    `${MCP_TOOL_NAME_MAX_LENGTH}. Shorten the entity or the action name.`);
+            }
+        }
+    }
+}
 /** The handles `defineOntology({ connections })` lists, each with a valid key and a description. */
 function collectConnections(config, report) {
     const declared = config.connections;
@@ -546,10 +599,37 @@ function resolveActions(candidate, scope) {
             permission: resolvePermission(path, permissionOf(candidate.name, name), action, scope),
             input: resolveInput(path, action.input, scope),
             connections: resolveActionConnections(path, action, scope),
+            hints: resolveHints(path, action, report),
         });
     }
     return actions;
 }
+const HINT_NAMES = ["destructive", "idempotent"];
+/** The action's `hints`: an object of booleans, `destructive` and `idempotent`. */
+function resolveHints(path, action, report) {
+    const declared = action.hints;
+    if (declared === undefined) {
+        return undefined;
+    }
+    const at = `${path}.hints`;
+    if (!isPlainObject(declared)) {
+        report("invalid-action", at, "hints is an object such as { destructive: false }.");
+        return undefined;
+    }
+    const hints = {};
+    for (const [key, value] of Object.entries(declared)) {
+        if (!HINT_NAMES.includes(key)) {
+            report("invalid-action", `${at}.${key}`, `is not a hint; use ${HINT_NAMES.join(" or ")}.`);
+        }
+        else if (typeof value !== "boolean") {
+            report("invalid-action", `${at}.${key}`, "is true or false.");
+        }
+        else {
+            hints[key] = value;
+        }
+    }
+    return hints;
+}
 /** The action's own `permission`, which names an entity and a verb without wildcards. */
 function resolvePermission(path, fallback, action, scope) {
     const declared = action.permission;

package/dist/bin/migrate.js

@@ -2,7 +2,7 @@ import * as PgClient from "@effect/sql-pg/PgClient";
 import { Cause, Effect, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
-import { applyMigration, readCatalog } from "../migrate/apply.js";
+import { applyMigration, readCatalog, readRuntimeTables, } from "../migrate/apply.js";
 import { MigrationRefused } from "../migrate/errors.js";
 import { isNoopMigration } from "../migrate/model.js";
 import { planMigration } from "../migrate/plan.js";
@@ -88,7 +88,8 @@ function migrateDatabase(input) {
     return Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const current = yield* readCatalog({ sql });
-        const plan = planMigration({ current, target });
+        const existingTables = yield* readRuntimeTables({ sql });
+        const plan = planMigration({ current, target, existingTables });
         output.stdout(formatPlan(plan, { sql: input.planOnly }));
         if (plan.refusals.length > 0) {
             output.stderr(formatRefusals(plan.refusals));

package/dist/diagnostics.d.ts

@@ -1,10 +1,10 @@
 import { Schema } from "effect";
-export declare const DIAGNOSTIC_CODES: readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "source-with-actions", "source-with-index", "invalid-measure", "unknown-measure", "circular-measure", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "invalid-guide", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "unknown-connection", "unused-connection", "invalid-prepare"];
+export declare const DIAGNOSTIC_CODES: readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "source-with-actions", "source-with-index", "invalid-measure", "unknown-measure", "circular-measure", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "invalid-guide", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "unknown-connection", "unused-connection", "invalid-prepare", "invalid-tool-name"];
 export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
 /** A problem `check` found in an ontology definition. */
 export declare const Diagnostic: Schema.Struct<{
     readonly severity: Schema.Literals<readonly ["error", "warning"]>;
-    readonly code: Schema.Literals<readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "source-with-actions", "source-with-index", "invalid-measure", "unknown-measure", "circular-measure", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "invalid-guide", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "unknown-connection", "unused-connection", "invalid-prepare"]>;
+    readonly code: Schema.Literals<readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "source-with-actions", "source-with-index", "invalid-measure", "unknown-measure", "circular-measure", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "invalid-guide", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "unknown-connection", "unused-connection", "invalid-prepare", "invalid-tool-name"]>;
     /** Where the problem is, for example `lead.properties.status.options[1]`. */
     readonly path: Schema.String;
     readonly message: Schema.String;
@@ -14,7 +14,7 @@ declare const InvalidOntology_base: Schema.Class<InvalidOntology, Schema.TaggedS
     readonly message: Schema.String;
     readonly diagnostics: Schema.$Array<Schema.Struct<{
         readonly severity: Schema.Literals<readonly ["error", "warning"]>;
-        readonly code: Schema.Literals<readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "source-with-actions", "source-with-index", "invalid-measure", "unknown-measure", "circular-measure", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "invalid-guide", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "unknown-connection", "unused-connection", "invalid-prepare"]>;
+        readonly code: Schema.Literals<readonly ["invalid-source", "missing-column", "invalid-column", "invalid-scope", "source-with-actions", "source-with-index", "invalid-measure", "unknown-measure", "circular-measure", "invalid-join", "missing-join", "invalid-entity", "invalid-property", "invalid-relationship", "invalid-actions", "invalid-action", "invalid-action-input", "invalid-role", "invalid-name", "reserved-name", "duplicate-name", "invalid-entity-id", "duplicate-entity-id", "missing-label", "missing-description", "invalid-title", "invalid-options", "invalid-default", "invalid-constraint", "unknown-relationship-target", "inverse-collision", "invalid-on-delete", "invalid-phrase", "invalid-index", "unknown-reference", "invalid-renamed-from", "invalid-guide", "managed-without-effect", "missing-permissions", "invalid-permission", "unknown-permission", "removed-allow", "unreachable-action", "wildcard-permission", "invalid-sign-in", "invalid-connection", "unknown-connection", "unused-connection", "invalid-prepare", "invalid-tool-name"]>;
         /** Where the problem is, for example `lead.properties.status.options[1]`. */
         readonly path: Schema.String;
         readonly message: Schema.String;

package/dist/diagnostics.js

@@ -49,6 +49,7 @@ export const DIAGNOSTIC_CODES = [
     "unknown-connection",
     "unused-connection",
     "invalid-prepare",
+    "invalid-tool-name",
 ];
 /** A problem `check` found in an ontology definition. */
 export const Diagnostic = Schema.Struct({

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { WarehouseSource } from "./source.js";
 export { m } from "./measure.js";
 export type { Measure, Measures, MeasureExpression, MeasureOptions } from "./measure.js";
 export { action, isAction } from "./action.js";
-export type { Action, ActionConfig, ActionConfigWithConnections, ActionContext, ActionEncodedInput, ActionInput, ActionResult, Actions, AnyAction, PrepareContext, PrepareError, } from "./action.js";
+export type { Action, ActionConfig, ActionConfigWithConnections, ActionContext, ActionEncodedInput, ActionHints, ActionInput, ActionResult, Actions, AnyAction, PrepareContext, PrepareError, } from "./action.js";
 export { CONNECTION_ERROR_REASONS, CONNECTION_KEY, CONNECTION_METHODS, connection, ConnectionError, Connections, ConnectionTransport, isConnection, MAXIMUM_CONNECTION_BODY_BYTES, } from "./connection.js";
 export type { AnyConnectionHandle, Connection, ConnectionCall, ConnectionClient, ConnectionErrorReason, ConnectionHandle, ConnectionHeaders, ConnectionMethod, ConnectionOptions, ConnectionReply, ConnectionRequest, ConnectionRequestOptions, ConnectionResponse, ConnectionsOf, ConnectionStub, StubRequest, StubResponse, } from "./connection.js";
 export type { EntityPermissions, JsonSchemaObject, MemberOptions, OntologyConfig, ResolvedAction, ResolvedConnection, ResolvedEntity, ResolvedIndex, ResolvedProperty, ResolvedRelationship, } from "./analyze.js";
@@ -55,10 +55,12 @@ export type { ConnectionAudit, ConnectionTransportFactory, LocalConnection, Loca
 export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, } from "./service/config.js";
 export type { ActionCommitted, AfterCommitHook, NeonAuthEnvironment, OntologyEnvironment, OntologyServiceConfig, } from "./service/config.js";
 export { NotInvited, OntologyBackend } from "./service/runtime-contract.js";
-export type { GeneratedActionsProvider, IdentityProvider, OntologyServiceRuntime, RunActionInput, SignInIdentity, } from "./service/runtime-contract.js";
+export type { GeneratedActionsProvider, IdentityProvider, OAuthClient, OAuthClientAuthMethod, OAuthGrant, OAuthRequest, OAuthStore, OAuthToken, OAuthTokenKind, OntologyServiceRuntime, RunActionInput, SignInIdentity, UsedOAuthToken, } from "./service/runtime-contract.js";
 export { createOntologyService, ONTOLOGY_HASH_HEADER, REQUEST_ID_HEADER, } from "./service/service.js";
+export { MCP_PATH, MCP_PROTOCOL_VERSIONS } from "./service/mcp/server.js";
+export { MCP_TOOL_NAME_MAX_LENGTH, mcpToolName } from "./names.js";
 export type { OntologyService } from "./service/service.js";
-export { applyMigration, CatalogInvalid, CatalogMismatch, isNoopMigration, migrate, MIGRATION_REFUSAL_CODES, MIGRATION_STEP_CLASSIFICATIONS, MIGRATION_STEP_KINDS, MigrationFailed, MigrationPlan, MigrationRefusal, MigrationRefused, MigrationStep, OntologyStorage, planMigration, readCatalog, } from "./migrate/index.js";
+export { applyMigration, CatalogInvalid, CatalogMismatch, isNoopMigration, migrate, MIGRATION_REFUSAL_CODES, MIGRATION_STEP_CLASSIFICATIONS, MIGRATION_STEP_KINDS, MigrationFailed, MigrationPlan, MigrationRefusal, MigrationRefused, MigrationStep, OntologyStorage, planMigration, readCatalog, readRuntimeTables, } from "./migrate/index.js";
 export type { ApplyMigrationError, ApplyMigrationOptions, CatalogInput, MigrateInput, MigrationOptions, MigrationRefusalCode, MigrationResult, MigrationStepClassification, MigrationStepKind, PlanMigrationInput, } from "./migrate/index.js";
 export type { BlobStorageBinding } from "./storage/provider.js";
 export { runBlobStorageMaintenance } from "./storage/operator.js";

package/dist/index.js

@@ -34,6 +34,9 @@ export { deployedConnections, LocalConnectionContextError, localConnections, OID
 export { configFromEnv, ENVIRONMENT_VARIABLES, NEON_AUTH_ENVIRONMENT_VARIABLES, OntologyServiceConfigError, } from "./service/config.js";
 export { NotInvited, OntologyBackend } from "./service/runtime-contract.js";
 export { createOntologyService, ONTOLOGY_HASH_HEADER, REQUEST_ID_HEADER, } from "./service/service.js";
+// The MCP server the service serves beside the HTTP API.
+export { MCP_PATH, MCP_PROTOCOL_VERSIONS } from "./service/mcp/server.js";
+export { MCP_TOOL_NAME_MAX_LENGTH, mcpToolName } from "./names.js";
 // Migrations: the planner, the applier and the physical mapping they share with the runtime.
-export { applyMigration, CatalogInvalid, CatalogMismatch, isNoopMigration, migrate, MIGRATION_REFUSAL_CODES, MIGRATION_STEP_CLASSIFICATIONS, MIGRATION_STEP_KINDS, MigrationFailed, MigrationPlan, MigrationRefusal, MigrationRefused, MigrationStep, OntologyStorage, planMigration, readCatalog, } from "./migrate/index.js";
+export { applyMigration, CatalogInvalid, CatalogMismatch, isNoopMigration, migrate, MIGRATION_REFUSAL_CODES, MIGRATION_STEP_CLASSIFICATIONS, MIGRATION_STEP_KINDS, MigrationFailed, MigrationPlan, MigrationRefusal, MigrationRefused, MigrationStep, OntologyStorage, planMigration, readCatalog, readRuntimeTables, } from "./migrate/index.js";
 export { runBlobStorageMaintenance } from "./storage/operator.js";

package/dist/manifest.d.ts

@@ -85,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;
 /**
@@ -186,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<{
@@ -318,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<{
@@ -453,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<{
@@ -582,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<{
@@ -629,6 +669,10 @@ 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 {
@@ -729,6 +773,10 @@ 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 {

package/dist/manifest.js

@@ -79,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
@@ -352,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

@@ -123,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;
@@ -230,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,6 +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, blobForeignKey, 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 {
@@ -69,10 +69,18 @@ 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({

package/dist/migrate/storage.d.ts

@@ -151,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.