@segmentstream-cloud/ontology 0.10.0 → 0.11.0

package/dist/service/descriptions.js

@@ -0,0 +1,15 @@
+/** `Requires lead:read.`, `Requires lead:create and lead:update.` */
+export function requires(permissions) {
+    return `Requires ${permissions.join(" and ")}.`;
+}
+/**
+ * What an action's route and its MCP tool say about it: its description, whether it is generated,
+ * the permissions it requires and the connections it calls.
+ */
+export function actionDescription({ action, generated, permissions }) {
+    const origin = generated ? "Generated action." : "Action.";
+    const calls = action.connections.length > 0
+        ? ` Calls ${action.connections.map((handle) => handle.key).join(", ")} before its transaction.`
+        : "";
+    return `${action.description}\n\n${origin} ${requires(permissions)}${calls}`;
+}

package/dist/service/errors.d.ts

@@ -45,7 +45,11 @@ export declare function toServerResponse(response: ErrorResponse): HttpServerRes
 export declare function errorBodyForWire(body: ErrorBody): Readonly<Record<string, unknown>>;
 /** Issues of a schema failure, as `[{ path, message }]`. */
 export declare function schemaIssues(issue: SchemaIssue.Issue): Array<ValidationIssue>;
-export declare function unauthorized(requestId: string, detail: string): ErrorResponse;
+/**
+ * `challenge` is the `WWW-Authenticate` value; the MCP server's names its OAuth metadata, which is
+ * how a client learns where members authorize it.
+ */
+export declare function unauthorized(requestId: string, detail: string, challenge?: string): ErrorResponse;
 /**
  * The token is valid but the `invited` sign-in policy turns its holder away: nobody invited them.
  * The detail is written for the person, since the app shows it.

package/dist/service/errors.js

@@ -50,11 +50,15 @@ const REQUEST_PARTS = {
 function isJsonParseFailure(issue) {
     return (issue._tag === "InvalidValue" && issue.annotations?.message === "Expected a valid JSON body");
 }
-export function unauthorized(requestId, detail) {
+/**
+ * `challenge` is the `WWW-Authenticate` value; the MCP server's names its OAuth metadata, which is
+ * how a client learns where members authorize it.
+ */
+export function unauthorized(requestId, detail, challenge = 'Bearer realm="ontology"') {
     return {
         status: 401,
         body: { error: "unauthorized", detail, requestId },
-        headers: { "www-authenticate": 'Bearer realm="ontology"' },
+        headers: { "www-authenticate": challenge },
     };
 }
 /**

package/dist/service/handlers.d.ts

@@ -1,13 +1,10 @@
 import { Layer } from "effect";
 import { type HttpApiGroup } from "effect/unstable/httpapi";
-import type { Query } from "../query.js";
 import { type BuiltApi } from "./api.js";
 import type { AfterCommitHook } from "./config.js";
-import { type ConnectionTransportFactory } from "./connections.js";
+import type { ConnectionTransportFactory } from "./connections.js";
 import { type RateLimit } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
-/** The query the runtime receives: every key present only when set, and no empty `include`. */
-export declare function toQuery(decoded: Query): Query;
 /**
  * Sign-in checks one client may make per minute. A person checks once per sign-in, a few times at
  * most; the limit slows down anyone testing addresses to learn who the app's members are.

package/dist/service/handlers.js

@@ -3,19 +3,13 @@ import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
 import { STORAGE_GROUP } from "../storage/api.js";
 import { Conflict } from "../errors.js";
-import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
-import { nameToWire } from "../authoring-names.js";
-import { principalFromWire } from "../authoring.js";
-import { toCamelCase } from "../names.js";
-import { PermissionDenied } from "../errors.js";
-import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
 import { EMAIL_PATTERN } from "../property.js";
 import { renderCatalog } from "../render.js";
 import { SERVICE_GROUP } from "./api.js";
 import { CurrentPrincipal } from "./authentication.js";
 import { catalogFor, graphOf } from "./catalog.js";
-import { OIDC_TOKEN_HEADER } from "./connections.js";
-import { InvalidActionInput, InvalidRequestBody, RequestId, SignInCheckLimited, schemaIssues, } from "./errors.js";
+import { InvalidRequestBody, SignInCheckLimited, schemaIssues } from "./errors.js";
+import { identityToken, makeOperations, requireRead, toQuery, } from "./operations.js";
 import { clientAddress, fixedWindowLimiter, } from "./rate-limit.js";
 import { OntologyBackend } from "./runtime-contract.js";
 import { ActionEnvelope } from "./schemas.js";
@@ -23,102 +17,6 @@ function dynamicGroup(api, identifier, build) {
     const group = HttpApiBuilder.group;
     return group(api, identifier, build);
 }
-/** 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 answers 403 for the whole
- * request, before anything is read: nothing is silently left out.
- */
-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.`,
-            });
-        }
-    });
-}
-/**
- * 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 traverse(planned, traversal, request, targets) {
-    return Effect.gen(function* () {
-        const backend = yield* OntologyBackend;
-        const { id } = request.params;
-        const query = toQuery(request.query);
-        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 isJsonMediaType(contentType) {
     if (contentType === undefined || contentType.trim() === "") {
         return true;
@@ -143,68 +41,7 @@ function readEnvelope(request) {
         return yield* Schema.decodeUnknownEffect(ActionEnvelope)(body, { errors: "all" }).pipe(Effect.mapError((error) => new InvalidRequestBody({ reason: "invalid_request", issues: schemaIssues(error.issue) })));
     });
 }
-/**
- * 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. */
-function identityToken(request) {
-    const header = request.headers[OIDC_TOKEN_HEADER];
-    return typeof header === "string" && header !== "" ? header : process.env.VERCEL_OIDC_TOKEN;
-}
-function runAction(planned, { name, generated }, ontology, hook, connections) {
-    return ({ request }) => Effect.gen(function* () {
-        const backend = yield* OntologyBackend;
-        const principal = yield* CurrentPrincipal;
-        const requestId = yield* RequestId;
-        const envelope = yield* readEnvelope(request);
-        const validateOnly = envelope.options?.validateOnly === true;
-        const outcome = yield* backend.runAction({
-            entity: planned.name,
-            action: name,
-            input: envelope.input,
-            principal,
-            options: { ...envelope.options, validateOnly },
-            requestId,
-            connections: connections({
-                identityToken: identityToken(request),
-                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 && !validateOnly) {
-            return yield* new InvalidActionInput({ issues });
-        }
-        return {
-            result: outcome.result ?? null,
-            validation: { ok: outcome.validation.ok, issues },
-            edits: outcome.edits,
-        };
-    });
-}
-function entityHandlers(built, planned, hooks, targets, connections) {
+function entityHandlers(built, planned, operationsOf) {
     return dynamicGroup(built.api, planned.name, (handlers) => Effect.gen(function* () {
         if (planned.resolved.entity.definition.source !== undefined) {
             return handlers.handleRaw("sourceCollection", () => requireRead([planned.name]).pipe(Effect.andThen(() => HttpServerResponse.json({
@@ -213,14 +50,12 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             }, { status: 404 }))));
         }
         const backend = yield* OntologyBackend;
-        // Every read checks the caller's permissions first; the backend is called only afterwards.
-        const find = (query) => requireRead(queryReads(planned.name, query, targets)).pipe(Effect.andThen(() => backend.find({ entity: planned.name, query })), Effect.map(page));
-        const readOwn = requireRead([planned.name]);
+        const operations = operationsOf(backend);
         let registered = handlers
-            .handle("find", (request) => find(toQuery(request.query)))
-            .handle("query", (request) => find(toQuery(request.payload)))
-            .handle("get", (request) => readOwn.pipe(Effect.andThen(() => backend.get({ entity: planned.name, id: request.params.id }))))
-            .handle("history", (request) => readOwn.pipe(Effect.andThen(() => backend.history({ entity: planned.name, id: request.params.id, ...request.query })), Effect.map(page)));
+            .handle("find", (request) => operations.find(planned, toQuery(request.query)))
+            .handle("query", (request) => operations.find(planned, toQuery(request.payload)))
+            .handle("get", (request) => operations.get(planned, request.params.id))
+            .handle("history", (request) => operations.history(planned, request.params.id, request.query));
         for (const property of planned.resolved.properties.filter((property) => property.definition.type === "blob")) {
             registered = registered.handle(`blobs.${property.name}`, (request) => Effect.gen(function* () {
                 const principal = yield* CurrentPrincipal;
@@ -234,37 +69,19 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             }));
         }
         for (const traversal of planned.traversals) {
-            registered = registered.handle(`related.${traversal.name}`, (request) => traverse(planned, traversal, request, targets).pipe(Effect.provideService(OntologyBackend, backend)));
+            registered = registered.handle(`related.${traversal.name}`, (request) => operations.traverse(planned, traversal, request.params.id, toQuery(request.query)));
         }
         for (const action of planned.actions) {
-            const handler = runAction(planned, action, built.plan.ontology, hooks.get(`${planned.name}.${action.name}`), connections);
-            registered = registered.handleRaw(`actions.${action.name}`, (request) => handler(request).pipe(Effect.provideService(OntologyBackend, backend)));
+            registered = registered.handleRaw(`actions.${action.name}`, ({ request }) => readEnvelope(request).pipe(Effect.flatMap((envelope) => operations.runAction(planned, action, {
+                input: envelope.input,
+                validateOnly: envelope.options?.validateOnly === true,
+                ...(envelope.options === undefined ? {} : { options: envelope.options }),
+                identityToken: identityToken(request),
+            }))));
         }
         return registered;
     }));
 }
-/**
- * The caller, as `GET /api/ontology/me` answers: their user record and the roles and permissions
- * authentication resolved. It needs no permission: 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,
-        };
-    });
-}
 /**
  * Sign-in checks one client may make per minute. A person checks once per sign-in, a few times at
  * most; the limit slows down anyone testing addresses to learn who the app's members are.
@@ -291,7 +108,7 @@ function checkSignIn(backend, limiter) {
         return yield* backend.checkSignIn(email);
     });
 }
-function serviceHandlers(built) {
+function serviceHandlers(built, operationsOf) {
     const { manifest } = built.plan.ontology;
     const graph = graphOf(manifest);
     const signInLimiter = fixedWindowLimiter(SIGN_IN_CHECK_LIMIT);
@@ -309,7 +126,7 @@ function serviceHandlers(built) {
         return handlers
             .handle("catalog", (request) => Effect.map(permissionsFor(request.query.as), (permissions) => catalogFor(manifest, permissions)))
             .handle("graph", () => Effect.succeed(graph))
-            .handle("me", () => callerOf(backend))
+            .handle("me", () => operationsOf(backend).caller)
             .handle("openapi", () => Effect.sync(() => {
             if (openApi === undefined) {
                 openApi = OpenApi.fromApi(built.api);
@@ -362,13 +179,13 @@ function storageHandlers(built) {
 }
 /** The handlers of every group of the API; they require {@link OntologyBackend}. */
 export function handlersLayer(built, hooks, connections) {
-    const targets = relationshipTargets(built.plan);
+    const operationsOf = (backend) => makeOperations(backend, built.plan, hooks, connections);
     const layers = [
-        serviceHandlers(built),
+        serviceHandlers(built, operationsOf),
         ...(built.plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
             ? [storageHandlers(built)]
             : []),
-        ...built.plan.entities.map((planned) => entityHandlers(built, planned, hooks, targets, connections)),
+        ...built.plan.entities.map((planned) => entityHandlers(built, planned, operationsOf)),
     ];
     const [first, ...rest] = layers;
     return Layer.mergeAll(first, ...rest);

package/dist/service/mcp/server.d.ts

@@ -0,0 +1,24 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import type { BuiltApi } from "../api.js";
+import { type TokenVerifier } from "../authentication.js";
+import type { AfterCommitHook } from "../config.js";
+import type { ConnectionTransportFactory } from "../connections.js";
+import { RequestId } from "../errors.js";
+import { OntologyBackend } from "../runtime-contract.js";
+/** The URL path of the ontology's MCP server, outside `/api/ontology`: one per app. */
+export declare const MCP_PATH = "/mcp";
+/** The MCP revisions the server speaks, newest first. */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18"];
+export interface McpServerOptions {
+    readonly built: BuiltApi;
+    readonly hooks: ReadonlyMap<string, AfterCommitHook>;
+    readonly connections: ConnectionTransportFactory;
+    readonly verifyToken: TokenVerifier;
+}
+/**
+ * The ontology's MCP server at `POST /mcp`: Streamable HTTP without sessions, so any instance can
+ * answer any request. Its tools run the same operations as the HTTP routes, behind the same
+ * authentication. `GET` and `DELETE`, which open a server stream and end a session, answer 405.
+ */
+export declare function mcpLayer(options: McpServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;