@segmentstream-cloud/ontology 0.9.0 → 0.11.0

package/dist/service/operations.d.ts

@@ -0,0 +1,114 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { PermissionDenied } from "../errors.js";
+import type { Query, QueryResult } from "../query.js";
+import { CurrentPrincipal } from "./authentication.js";
+import type { AfterCommitHook } from "./config.js";
+import { type ConnectionTransportFactory } from "./connections.js";
+import { InvalidActionInput, RequestId } from "./errors.js";
+import type { ApiPlan, PlannedAction, PlannedEntity, Traversal } from "./plan.js";
+import type { OntologyBackend } from "./runtime-contract.js";
+/**
+ * What the service does for a caller, whatever the transport: the reads and actions of every entity
+ * and the caller's own account. The HTTP routes and the MCP tools both call these, so a permission
+ * check, a validation or a history row never depends on how the request arrived. Each requires the
+ * caller, as {@link CurrentPrincipal}, and the request id.
+ */
+/** The query the runtime receives: every key present only when set, and no empty `include`. */
+export declare function toQuery(decoded: Query): Query;
+/**
+ * Requires `<entity>:read` on every entity a request reads. A missing one fails the whole request,
+ * before anything is read: nothing is silently left out.
+ */
+export declare function requireRead(entities: ReadonlyArray<string>): Effect.Effect<undefined, PermissionDenied, CurrentPrincipal>;
+/** The deployment's OIDC token: Vercel sets it on each request, and in the environment of builds. */
+export declare function identityToken(request: HttpServerRequest.HttpServerRequest): string | undefined;
+/** An action call, as a transport decoded it. */
+export interface ActionCall {
+    /** The input as the caller sent it; the runtime validates it against the action's input schema. */
+    readonly input: unknown;
+    readonly validateOnly: boolean;
+    /** The request's other action options: the idempotency key and create intent of an upload. */
+    readonly options?: {
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
+    };
+    /** The deployment's OIDC token, which authorizes the action's connection calls. */
+    readonly identityToken: string | undefined;
+}
+/** What an action answers: `{ result, validation, edits }`. */
+export interface ActionAnswer {
+    readonly result: unknown;
+    readonly validation: {
+        readonly ok: boolean;
+        readonly issues: ReadonlyArray<unknown>;
+    };
+    readonly edits: ReadonlyArray<unknown>;
+}
+/** The caller, as `GET /api/ontology/me` answers. */
+export interface Caller {
+    readonly user: {
+        readonly id: string;
+        readonly name: string;
+        readonly email: string | null;
+        readonly kind: string;
+        readonly active: boolean;
+    };
+    readonly roles: ReadonlyArray<string>;
+    readonly permissions: ReadonlyArray<string>;
+}
+type Backend = OntologyBackend["Service"];
+/** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
+export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory): {
+    /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
+    find: (planned: PlannedEntity, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../index.js").InvalidQuery, CurrentPrincipal>;
+    /** One record. Requires `read` on the entity. */
+    get: (planned: PlannedEntity, id: string) => Effect.Effect<Readonly<Record<string, unknown>>, PermissionDenied | import("../errors.js").NotFound, CurrentPrincipal>;
+    /** A page of a record's history, newest first. Requires `read` on the entity. */
+    history: (planned: PlannedEntity, id: string, params: {
+        readonly after?: string;
+        readonly limit?: number;
+    }) => Effect.Effect<QueryResult<{
+        readonly id: string;
+        readonly recordId: string;
+        readonly action: string;
+        readonly actionId: string;
+        readonly kind: "create" | "update" | "delete" | "link" | "unlink";
+        readonly principalId: string | null;
+        readonly at: string;
+        readonly changes: {
+            readonly [x: string]: {
+                readonly before: import("effect/Schema").Json;
+                readonly after: import("effect/Schema").Json;
+            };
+        };
+    }>, PermissionDenied | import("../errors.js").NotFound | import("../index.js").InvalidQuery, CurrentPrincipal>;
+    /** The records a relationship reaches from one record, as a page of the target entity. */
+    traverse: (planned: PlannedEntity, traversal: Traversal, id: string, query: Query) => Effect.Effect<QueryResult<Readonly<Record<string, unknown>>>, PermissionDenied | import("../errors.js").NotFound | import("../index.js").InvalidQuery, CurrentPrincipal>;
+    /** Runs an action as the caller, with the action's after-commit hook and connections. */
+    runAction: (planned: PlannedEntity, { name, generated }: PlannedAction, call: ActionCall) => Effect.Effect<{
+        result: {} | null;
+        validation: {
+            ok: boolean;
+            issues: readonly {
+                readonly path: readonly (string | number)[];
+                readonly message: string;
+            }[];
+        };
+        edits: readonly {
+            readonly entity: string;
+            readonly id: string;
+            readonly kind: "create" | "update" | "delete" | "link" | "unlink";
+            readonly changes: {
+                readonly [x: string]: {
+                    readonly before: import("effect/Schema").Json;
+                    readonly after: import("effect/Schema").Json;
+                };
+            };
+        }[];
+    }, import("../connection.js").ConnectionError | import("../errors.js").ActionRejected | PermissionDenied | import("../errors.js").Conflict | import("../errors.js").NotFound | InvalidActionInput, RequestId | CurrentPrincipal>;
+    /** The caller's user, roles and permissions. It needs no permission. */
+    caller: Effect.Effect<Caller, never, CurrentPrincipal>;
+};
+export type Operations = ReturnType<typeof makeOperations>;
+export {};

package/dist/service/operations.js

@@ -0,0 +1,218 @@
+import { Effect } from "effect";
+import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
+import { nameToWire } from "../authoring-names.js";
+import { principalFromWire } from "../authoring.js";
+import { PermissionDenied } from "../errors.js";
+import { toCamelCase } from "../names.js";
+import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { OIDC_TOKEN_HEADER } from "./connections.js";
+import { InvalidActionInput, RequestId } from "./errors.js";
+/**
+ * What the service does for a caller, whatever the transport: the reads and actions of every entity
+ * and the caller's own account. The HTTP routes and the MCP tools both call these, so a permission
+ * check, a validation or a history row never depends on how the request arrived. Each requires the
+ * caller, as {@link CurrentPrincipal}, and the request id.
+ */
+/** The query the runtime receives: every key present only when set, and no empty `include`. */
+export function toQuery(decoded) {
+    const { include, ...rest } = decoded;
+    return include !== undefined && Object.keys(include).length > 0 ? { ...rest, include } : rest;
+}
+function page(result) {
+    return { items: result.items, nextCursor: result.nextCursor ?? null };
+}
+function relationshipTargets(plan) {
+    return new Map(plan.entities.map((planned) => [
+        planned.name,
+        new Map(planned.traversals.map((traversal) => [traversal.name, traversal.target])),
+    ]));
+}
+/** Adds the entities a `where` looks into through relationship filters, at any combinator depth. */
+function filterReads(where, targets, reads) {
+    for (const [key, condition] of Object.entries(where ?? {})) {
+        if (key === "and" || key === "or") {
+            for (const part of condition) {
+                filterReads(part, targets, reads);
+            }
+        }
+        else if (key === "not") {
+            filterReads(condition, targets, reads);
+        }
+        else {
+            const target = targets.get(key);
+            if (target !== undefined) {
+                reads.add(target);
+            }
+        }
+    }
+}
+/**
+ * The entities a query on `entity` reads: the entity, the entity of every relationship it includes,
+ * and the entity of every relationship its filter looks into.
+ */
+function queryReads(entity, query, targets) {
+    const own = targets.get(entity) ?? new Map();
+    const reads = new Set([entity]);
+    for (const name of Object.keys(query.include ?? {})) {
+        const target = own.get(name);
+        if (target !== undefined) {
+            reads.add(target);
+        }
+    }
+    filterReads(query.where, own, reads);
+    return [...reads];
+}
+/**
+ * Requires `<entity>:read` on every entity a request reads. A missing one fails the whole request,
+ * before anything is read: nothing is silently left out.
+ */
+export function requireRead(entities) {
+    return Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const missing = missingPermission(entities.map((entity) => permissionOf(entity, READ_VERB)), principal);
+        if (missing !== undefined) {
+            return yield* new PermissionDenied({
+                permission: missing,
+                message: `Reading requires ${missing}, which the principal's roles do not grant.`,
+            });
+        }
+    });
+}
+/**
+ * The configured hook as `runAction` runs it after the commit. A failure is logged with the request
+ * id here, so the action's caller still gets the committed result.
+ */
+function afterCommitOf(hook, request, ontology) {
+    return (committed) => {
+        const definition = ontology.config.entities.find((entity) => nameToWire(entity.name) === committed.entity)?.definition;
+        return Effect.tryPromise(async () => hook({
+            entity: toCamelCase(committed.entity),
+            action: toCamelCase(committed.action),
+            principal: principalFromWire(committed.principal),
+            input: request.generated ? recordFromWire(committed.input, definition) : committed.input,
+            result: request.generated
+                ? generatedResultFromWire(committed.result, committed.action, definition)
+                : committed.result,
+            edits: editsFromWire(committed.edits, ontology.config.entities),
+            requestId: request.requestId,
+        })).pipe(Effect.catchCause((cause) => Effect.logError("ontology.after_commit.failed", cause).pipe(Effect.annotateLogs({
+            requestId: request.requestId,
+            action: `${committed.entity}.${committed.action}`,
+        }))));
+    };
+}
+/** The deployment's OIDC token: Vercel sets it on each request, and in the environment of builds. */
+export function identityToken(request) {
+    const header = request.headers[OIDC_TOKEN_HEADER];
+    return typeof header === "string" && header !== "" ? header : process.env.VERCEL_OIDC_TOKEN;
+}
+function findOf(backend, targets, entity, query) {
+    // Every read checks the caller's permissions first; the backend is called only afterwards.
+    return requireRead(queryReads(entity, query, targets)).pipe(Effect.andThen(() => backend.find({ entity, query })), Effect.map(page));
+}
+function getOf(backend, entity, id) {
+    return requireRead([entity]).pipe(Effect.andThen(() => backend.get({ entity, id })));
+}
+function historyOf(backend, entity, id, params) {
+    return requireRead([entity]).pipe(Effect.andThen(() => backend.history({ entity, id, ...params })), Effect.map(page));
+}
+/**
+ * Follows a relationship from one record with the query language: the record's own
+ * `<relationship>_id` for a `rel.one`, and for everything to-many a relationship path from the
+ * target back to the record (`lead.notes` is notes whose `lead` is the lead, `lead.tags` is tags
+ * some of whose `leads` is the lead), combined with the caller's query and paged like any find.
+ */
+function traverseOf(backend, targets, planned, traversal, id, query) {
+    return Effect.gen(function* () {
+        yield* requireRead([planned.name, ...queryReads(traversal.target, query, targets)]);
+        const source = yield* backend.get({ entity: planned.name, id });
+        if (traversal.kind === "one") {
+            const targetId = source[`${traversal.name}_id`];
+            if (typeof targetId !== "string") {
+                return { items: [], nextCursor: null };
+            }
+            return page(yield* backend.find({
+                entity: traversal.target,
+                query: { ...query, where: { id: { eq: targetId } }, limit: 1 },
+            }));
+        }
+        const match = { id: { eq: id } };
+        const related = traversal.kind === "inverseOfOne"
+            ? { [traversal.opposite]: match }
+            : { [traversal.opposite]: { some: match } };
+        const where = query.where === undefined ? related : { and: [related, query.where] };
+        return page(yield* backend.find({ entity: traversal.target, query: { ...query, where } }));
+    });
+}
+function runActionOf(backend, ontology, hooks, connections) {
+    return (planned, { name, generated }, call) => Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const requestId = yield* RequestId;
+        const hook = hooks.get(`${planned.name}.${name}`);
+        const outcome = yield* backend.runAction({
+            entity: planned.name,
+            action: name,
+            input: call.input,
+            principal,
+            options: { ...call.options, validateOnly: call.validateOnly },
+            requestId,
+            connections: connections({
+                identityToken: call.identityToken,
+                audit: { action: `${planned.name}.${name}`, principalId: principal.id, requestId },
+            }),
+            ...(hook === undefined
+                ? {}
+                : { afterCommit: afterCommitOf(hook, { requestId, generated }, ontology) }),
+        });
+        const { issues } = outcome.validation;
+        if (!outcome.validation.ok && !call.validateOnly) {
+            return yield* new InvalidActionInput({ issues });
+        }
+        return {
+            result: outcome.result ?? null,
+            validation: { ok: outcome.validation.ok, issues },
+            edits: outcome.edits,
+        };
+    });
+}
+/**
+ * The caller: their user record and the roles and permissions authentication resolved. Anyone may
+ * learn who they are and what they may do.
+ */
+function callerOf(backend) {
+    return Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        // Authentication resolved the principal from this user a moment ago; its absence is a defect.
+        const user = yield* backend.get({ entity: "user", id: principal.id }).pipe(Effect.orDie);
+        return {
+            user: {
+                id: principal.id,
+                name: String(user.name),
+                email: typeof user.email === "string" ? user.email : null,
+                kind: principal.kind,
+                active: user.active === true,
+            },
+            roles: principal.roles,
+            permissions: principal.permissions,
+        };
+    });
+}
+/** The operations of a planned ontology, bound to its backend, after-commit hooks and connections. */
+export function makeOperations(backend, plan, hooks, connections) {
+    const targets = relationshipTargets(plan);
+    return {
+        /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
+        find: (planned, query) => findOf(backend, targets, planned.name, query),
+        /** One record. Requires `read` on the entity. */
+        get: (planned, id) => getOf(backend, planned.name, id),
+        /** A page of a record's history, newest first. Requires `read` on the entity. */
+        history: (planned, id, params) => historyOf(backend, planned.name, id, params),
+        /** The records a relationship reaches from one record, as a page of the target entity. */
+        traverse: (planned, traversal, id, query) => traverseOf(backend, targets, planned, traversal, id, query),
+        /** Runs an action as the caller, with the action's after-commit hook and connections. */
+        runAction: runActionOf(backend, plan.ontology, hooks, connections),
+        /** The caller's user, roles and permissions. It needs no permission. */
+        caller: callerOf(backend),
+    };
+}

package/dist/service/runtime-contract.d.ts

@@ -1,4 +1,6 @@
 import { Context, Schema, type Effect, type Layer, type Redacted } from "effect";
+import type { BlobRuntime } from "../storage/sessions.js";
+import type { BlobStorageBinding } from "../storage/provider.js";
 import type { AnyAction } from "../action.js";
 import type { ResolvedEntity } from "../analyze.js";
 import type { ConnectionError, ConnectionTransport } from "../connection.js";
@@ -23,6 +25,8 @@ export interface RunActionInput {
     readonly principal: Principal;
     readonly options: {
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
     /**
      * Runs once the action has committed, outside its transaction, before `runAction` returns. It
@@ -62,7 +66,98 @@ declare const NotInvited_base: Schema.Class<NotInvited, Schema.TaggedStruct<"Not
  */
 export declare class NotInvited extends NotInvited_base {
 }
+/** How a client proves itself at the token endpoint; `none` for a public client, with PKCE only. */
+export type OAuthClientAuthMethod = "none" | "client_secret_post" | "client_secret_basic";
+/** A client that registered itself to connect an agent (RFC 7591 dynamic registration). */
+export interface OAuthClient {
+    readonly id: string;
+    readonly name: string;
+    readonly redirectUris: ReadonlyArray<string>;
+    readonly authMethod: OAuthClientAuthMethod;
+    /** SHA-256 of a confidential client's secret; null for a public client. */
+    readonly secretHash: string | null;
+    readonly clientUri: string | null;
+}
+/** An authorization request waiting, for a few minutes, for a member's consent. */
+export interface OAuthRequest {
+    readonly id: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly state: string | null;
+    /** The PKCE S256 challenge the token request must answer. */
+    readonly codeChallenge: string;
+    readonly scope: string;
+    /** The MCP server the tokens are for (RFC 8707). */
+    readonly resource: string;
+    readonly expiresAt: Date;
+}
+/** What a member allowed a client to do. Its tokens stop working once it is revoked. */
+export interface OAuthGrant {
+    readonly id: string;
+    readonly clientId: string;
+    readonly userId: string;
+    readonly scope: string;
+    readonly resource: string;
+}
+export type OAuthTokenKind = "code" | "access" | "refresh";
+/** A code or token of a grant, stored only as the SHA-256 of its value. */
+export interface OAuthToken {
+    readonly hash: string;
+    readonly grantId: string;
+    readonly kind: OAuthTokenKind;
+    readonly expiresAt: Date;
+    /** For a code: the redirect URI it was sent to, which the token request must repeat. */
+    readonly redirectUri?: string;
+    /** For a code: the PKCE challenge the token request's verifier must answer. */
+    readonly codeChallenge?: string;
+}
+/**
+ * A code or refresh token presented once more: `reused` when it was used before, which means it
+ * leaked, and the caller revokes its grant.
+ */
+export type UsedOAuthToken = {
+    readonly status: "valid";
+    readonly token: OAuthToken;
+    readonly grant: OAuthGrant;
+} | {
+    readonly status: "reused";
+    readonly grant: OAuthGrant;
+} | {
+    readonly status: "invalid";
+};
+/**
+ * Where the MCP server's authorization server keeps clients, pending requests, grants and tokens:
+ * the runtime's OAuth tables in the workspace database. Expiry is checked against the database's
+ * clock; failures are defects.
+ */
+export interface OAuthStore {
+    readonly saveClient: (client: OAuthClient) => Effect.Effect<void>;
+    readonly findClient: (id: string) => Effect.Effect<OAuthClient | undefined>;
+    /** Stores a request, and forgets the expired ones. */
+    readonly saveRequest: (request: OAuthRequest) => Effect.Effect<void>;
+    /** A request that has not expired. */
+    readonly findRequest: (id: string) => Effect.Effect<OAuthRequest | undefined>;
+    /** Removes a request that has not expired and returns it: a request is decided once. */
+    readonly takeRequest: (id: string) => Effect.Effect<OAuthRequest | undefined>;
+    /** Records a grant with its authorization code. */
+    readonly saveGrant: (grant: OAuthGrant, code: OAuthToken) => Effect.Effect<void>;
+    /** Uses a code or refresh token, once, before it expires and while its grant stands. */
+    readonly useToken: (hash: string, kind: "code" | "refresh") => Effect.Effect<UsedOAuthToken>;
+    /** Stores new tokens, and forgets the expired ones. */
+    readonly saveTokens: (tokens: ReadonlyArray<OAuthToken>) => Effect.Effect<void>;
+    /** The grant of an access token that has not expired, unless the grant was revoked. */
+    readonly findAccess: (hash: string) => Effect.Effect<OAuthGrant | undefined>;
+    /** The grant of a token of any kind, revoked or not. */
+    readonly findGrantOfToken: (hash: string) => Effect.Effect<OAuthGrant | undefined>;
+    readonly revokeGrant: (id: string) => Effect.Effect<void>;
+    /** The member a grant acts for, with the roles they hold now; undefined once they may not sign in. */
+    readonly memberPrincipal: (userId: string) => Effect.Effect<Principal | undefined>;
+}
 declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segmentstream-cloud/ontology/OntologyBackend", {
+    readonly blobs?: BlobRuntime;
+    readonly maintainBlobs?: Effect.Effect<{
+        readonly removed: number;
+    }, unknown>;
     readonly runAction: (input: RunActionInput) => Effect.Effect<ActionOutcome, PermissionDenied | ActionRejected | Conflict | NotFound | ConnectionError>;
     readonly get: (input: {
         readonly entity: string;
@@ -94,6 +189,8 @@ declare const OntologyBackend_base: Context.ServiceClass<OntologyBackend, "@segm
     readonly resolveApiKey: (key: Redacted.Redacted<string>) => Effect.Effect<Principal | undefined>;
     /** The manifest hash recorded in the `_ontology` catalog table, or `undefined` before the first. */
     readonly appliedHash: Effect.Effect<string | undefined>;
+    /** The OAuth tables, for members who connect agents; without it, agents use API keys. */
+    readonly oauth?: OAuthStore;
 }>;
 /**
  * The runtime as the HTTP service sees it, with its database and ontology already bound. Failures
@@ -111,6 +208,7 @@ export interface OntologyServiceRuntime {
     readonly connect: (input: {
         readonly ontology: Ontology;
         readonly databaseUrl: Redacted.Redacted<string>;
+        readonly blobStorage?: Redacted.Redacted<BlobStorageBinding>;
     }) => Layer.Layer<OntologyBackend, unknown>;
 }
 export {};

package/dist/service/schemas.d.ts

@@ -124,6 +124,8 @@ export declare const ActionEnvelope: Schema.Codec<{
     readonly input: unknown;
     readonly options?: {
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
 }>;
 export declare const ActionResponse: Schema.Struct<{
@@ -151,7 +153,7 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -163,6 +165,8 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -171,6 +175,7 @@ export declare const Catalog: Schema.decodeTo<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<{
@@ -223,6 +228,10 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -259,7 +268,7 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -271,6 +280,8 @@ export declare const Catalog: Schema.decodeTo<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;
@@ -279,6 +290,7 @@ export declare const Catalog: Schema.decodeTo<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<{
@@ -331,6 +343,10 @@ export declare const Catalog: Schema.decodeTo<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/service/schemas.js

@@ -1,3 +1,4 @@
+import { BlobValue } from "../blob.js";
 import { Schema, SchemaTransformation } from "effect";
 import { wireStruct } from "../wire.js";
 import { OntologyManifestWire } from "../manifest.js";
@@ -68,6 +69,8 @@ function propertyValue(definition) {
         }
         case "json":
             return Schema.Json.annotate(documentation);
+        case "blob":
+            return BlobValue.annotate(documentation);
     }
 }
 function recordFields(entity) {
@@ -226,11 +229,20 @@ export const HistoryPage = Schema.Struct({
 })
     .pipe(Schema.encodeKeys({ nextCursor: "next_cursor" }))
     .annotate({ identifier: "HistoryPage" });
+const uploadOptions = {
+    idempotencyKey: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    createIntent: Schema.optionalKey(Schema.String.check(Schema.isUUID())),
+};
 const ActionOptions = wireStruct({
+    ...uploadOptions,
     validateOnly: Schema.optionalKey(Schema.Boolean.annotate({
         description: "Validate the input and report issues without a write.",
     })),
-}, { validateOnly: "validate_only" });
+}, {
+    validateOnly: "validate_only",
+    idempotencyKey: "idempotency_key",
+    createIntent: "create_intent",
+});
 /** The body of `POST /<entity>/actions/<action>`, as documented. */
 export function actionRequest(input) {
     return Schema.Struct({ input, options: Schema.optionalKey(ActionOptions) });
@@ -238,7 +250,11 @@ export function actionRequest(input) {
 /** The body of `POST /<entity>/actions/<action>`, as decoded: `runAction` validates the input. */
 export const ActionEnvelope = closedStruct({
     input: Schema.Unknown,
-    options: Schema.optionalKey(wireStruct({ validateOnly: Schema.optionalKey(Schema.Boolean) }, { validateOnly: "validate_only" })),
+    options: Schema.optionalKey(wireStruct({ validateOnly: Schema.optionalKey(Schema.Boolean), ...uploadOptions }, {
+        validateOnly: "validate_only",
+        idempotencyKey: "idempotency_key",
+        createIntent: "create_intent",
+    })),
 }, "Unknown key; use input and options");
 export const ActionResponse = Schema.Struct({
     result: Schema.Unknown.annotate({ description: "What the action returned." }),

package/dist/service/service.d.ts

@@ -13,8 +13,8 @@ export interface OntologyService {
     readonly dispose: () => Promise<void>;
 }
 /**
- * The ontology service: the derived HttpApi, wired to the runtime, behind Neon Auth, app-token and
- * API-key authentication. Every response carries `x-ontology-hash` and `x-request-id`; failures
- * answer with a JSON error and never a stack or SQL.
+ * The ontology service: the derived HttpApi and the MCP server at `/mcp`, wired to the runtime,
+ * behind Neon Auth, app-token and API-key authentication. Every response carries `x-ontology-hash`
+ * and `x-request-id`; failures answer with a JSON error and never a stack or SQL.
  */
 export declare function createOntologyService(ontology: Ontology, config: OntologyServiceConfig): OntologyService;