@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/operations.d.ts

@@ -0,0 +1,170 @@
+import type { ActionRuntime } from "../runtime-source.js";
+import { Effect, Schema } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import { PermissionDenied } from "../errors.js";
+import { type ScopedPermission } from "../permissions.js";
+import { type Query, type QueryResult } from "../query.js";
+import { InvalidQuery } from "../runtime/errors.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { type CallerContext } from "./caller-context.js";
+import type { ChatDeliveryFactory } from "./chat/delivery.js";
+import type { AfterCommitHook } from "./config.js";
+import type { ReplicationKick } from "./replication.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 {
+    /** In-process verified runtime boundary (for attachment promotion), never decoded from action input. */
+    readonly runtime?: ActionRuntime;
+    /** The input as the caller sent it; the runtime validates it against the action's input schema. */
+    readonly input: unknown;
+    readonly validateOnly: boolean;
+    /**
+     * Answer with what a person confirms before the action runs, in this chat language, as the
+     * action's `confirm` describes it, instead of running it; `null` for an action without one.
+     */
+    readonly confirm?: {
+        readonly locale: string;
+    };
+    /** 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>;
+    /**
+     * The permissions of `permissions` held only for the records their `where` matches, in the wire
+     * form of the manifest's `roles[].scopes`. Absent when none is scoped.
+     */
+    readonly scopes?: ReadonlyArray<{
+        readonly permission: string;
+        readonly where: ScopedPermission["where"];
+    }>;
+    readonly authentication: {
+        readonly kind: CallerContext["kind"];
+        readonly client: {
+            readonly id: string;
+            readonly name: string;
+        } | null;
+        readonly scope: string | null;
+    };
+    readonly attribution: string | null;
+    readonly attribution_separator?: string;
+}
+type Backend = OntologyBackend["Service"];
+/**
+ * The operations of a planned ontology, bound to its backend, after-commit hooks, connections and,
+ * on deployments with one, the workspace's agent.
+ */
+export declare function makeOperations(backend: Backend, plan: ApiPlan, hooks: ReadonlyMap<string, AfterCommitHook>, connections: ConnectionTransportFactory, replicate: ReplicationKick, chatDelivery?: ChatDeliveryFactory): {
+    /** 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("../errors.js").NotFound | InvalidQuery | import("./errors.js").WarehouseReadUnavailable, RequestId | CurrentPrincipal>;
+    /** One record. Requires `read` on the entity. */
+    get: (planned: PlannedEntity, id: string) => Effect.Effect<Readonly<Record<string, unknown>>, PermissionDenied | import("../errors.js").NotFound | InvalidQuery | import("./errors.js").WarehouseReadUnavailable, RequestId | 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 kind: "create" | "update" | "delete" | "link" | "unlink";
+        readonly id: string;
+        readonly at: string;
+        readonly action: string;
+        readonly changes: {
+            readonly [x: string]: {
+                readonly before: Schema.Json;
+                readonly after: Schema.Json;
+            };
+        };
+        readonly principalId: string | null;
+        readonly recordId: string;
+        readonly actionId: string;
+        readonly execution?: {
+            readonly issuer: string;
+            readonly audience: string;
+            readonly organizationId: string;
+            readonly workspaceId: string;
+            readonly subject: string;
+            readonly deploymentId: string;
+            readonly ontologyDeploymentId: string;
+            readonly servingOntologyDeploymentId: string;
+            readonly ontologyOrigin: string;
+            readonly environment: "production" | "preview";
+            readonly jobName: string | null;
+            readonly runId: string;
+            readonly executionId: string | null;
+            readonly attemptId: string;
+            readonly generation: number;
+            readonly tokenId: string;
+            readonly issuedAt: number;
+            readonly expiresAt: number;
+        } | undefined;
+    }>, PermissionDenied | import("../errors.js").NotFound | 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 | InvalidQuery | import("./errors.js").WarehouseReadUnavailable, RequestId | 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: Schema.Json;
+                    readonly after: Schema.Json;
+                };
+            };
+        }[];
+    }, import("../errors.js").ActionError | import("../connection.js").ConnectionError | import("../runtime/errors.js").WorkflowRecoveryUnavailable | import("../runtime/errors.js").TriggerInputInvalid | 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,392 @@
+import { Effect, Option, Schema } from "effect";
+import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
+import { nameToWire } from "../authoring-names.js";
+import { principalFromWire } from "../authoring.js";
+import { ActionRejected, PermissionDenied } from "../errors.js";
+import { toCamelCase } from "../names.js";
+import { missingPermission, permissionOf, READ_VERB, } from "../permissions.js";
+import { includedRelationships } from "../query.js";
+import { InvalidQuery } from "../runtime/errors.js";
+import { CurrentPrincipal } from "./authentication.js";
+import { currentCaller, CurrentCaller } from "./caller-context.js";
+import { chatAttribution } from "./chat/attribution.js";
+import { requireRuntimeOperation } from "./mcp/runtime-policy.js";
+import { ChatDelivery } from "../chat.js";
+import { withoutConfirmation } from "./mcp/confirmation.js";
+import { consumeChatEnvelope, CurrentChatCall } from "./chat/envelope.js";
+import { ChatPostWire, RuntimeChatPostWire } from "./chat/schemas.js";
+import { OIDC_TOKEN_HEADER } from "./connections.js";
+import { InvalidActionInput, RequestId } from "./errors.js";
+import { recordReads } from "./record-reads.js";
+import { AGENT_TASK_AUTHENTICATION } from "./agent/task-caller.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 includedRelationships(include).length > 0 ? { ...rest, include } : rest;
+}
+function page(result) {
+    return {
+        items: result.items,
+        nextCursor: result.nextCursor ?? null,
+        ...(result.projected === true ? { projected: true } : {}),
+    };
+}
+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 includedRelationships(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, run) {
+    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,
+            ...(run === undefined ? {} : { run }),
+        })).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;
+}
+/**
+ * The caller as the backend's reads take it: present only when it holds scoped permissions, whose
+ * read scopes then leave out the rows outside them. Other callers read as before.
+ */
+const scopedReader = Effect.gen(function* () {
+    const principal = yield* CurrentPrincipal;
+    return principal.scopes === undefined || principal.scopes.length === 0
+        ? {}
+        : { reader: principal };
+});
+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(() => scopedReader), Effect.flatMap((reader) => backend.find({ entity, query, ...reader })), Effect.map(page));
+}
+function getOf(backend, entity, id) {
+    return requireRead([entity]).pipe(Effect.andThen(() => scopedReader), Effect.flatMap((reader) => backend.get({ entity, id, ...reader })));
+}
+function historyOf(backend, entity, id, params) {
+    return requireRead([entity]).pipe(Effect.andThen(() => scopedReader), Effect.flatMap((reader) => backend.history({ entity, id, ...params, ...reader })), 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 reader = yield* scopedReader;
+        // A source outside the caller's read scope is not found, like any record they cannot read.
+        const source = yield* backend.get({ entity: planned.name, id, ...reader });
+        if (traversal.match !== undefined) {
+            const value = source[traversal.match.source];
+            if (value === null || value === undefined) {
+                return {
+                    items: [],
+                    nextCursor: null,
+                    ...(query.select === undefined ? {} : { projected: true }),
+                };
+            }
+            const related = { [traversal.match.target]: { eq: value } };
+            const relatedPage = yield* backend.find({
+                entity: traversal.target,
+                query: {
+                    ...query,
+                    where: query.where === undefined ? related : { and: [related, query.where] },
+                    ...(traversal.kind === "one" ? { limit: 2 } : {}),
+                },
+                ...reader,
+            });
+            if (traversal.kind === "one" &&
+                (relatedPage.items.length > 1 || relatedPage.nextCursor !== null)) {
+                return yield* new InvalidQuery({
+                    entity: planned.name,
+                    message: "The target key of a to-one relationship is not unique.",
+                    issues: [{ path: [], message: "The target key of a to-one relationship is not unique." }],
+                });
+            }
+            return page(relatedPage);
+        }
+        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 },
+                ...reader,
+            }));
+        }
+        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 }, ...reader }));
+    });
+}
+function runActionOf(backend, plan, hooks, connections, replicate, chatDelivery) {
+    const ontology = plan.ontology;
+    return (planned, { name, generated }, call) => Effect.gen(function* () {
+        yield* requireRuntimeOperation({ entity: planned.name, action: name });
+        const principal = yield* CurrentPrincipal;
+        const caller = yield* currentCaller;
+        const raw = typeof call.input === "object" && call.input !== null && !Array.isArray(call.input)
+            ? call.input
+            : {};
+        const consumed = yield* consumeChatEnvelope(withoutConfirmation(raw), caller);
+        const inherited = yield* Effect.serviceOption(CurrentChatCall);
+        const envelope = caller.kind === "runtime"
+            ? (consumed.envelope ?? Option.getOrUndefined(inherited))
+            : undefined;
+        let input = Object.hasOwn(raw, "_segmentstream") || Object.hasOwn(raw, "_confirmation")
+            ? consumed.input
+            : call.input;
+        // A chat post needs its requester's confirmation, and a task has none (spec decision 7).
+        if (planned.name === "agent_chat" &&
+            name === "post_message" &&
+            principal.authenticatedVia === AGENT_TASK_AUTHENTICATION) {
+            return yield* new ActionRejected({
+                message: "Agent tasks cannot post to chat in this release: agent_chat.post_message is refused " +
+                    "for a task whatever its workflow's role grants.",
+            });
+        }
+        if (planned.name === "agent_chat" && name === "post_message" && caller.kind === "runtime") {
+            const values = yield* Schema.decodeUnknownEffect(RuntimeChatPostWire)(consumed.input, {
+                onExcessProperty: "error",
+            }).pipe(Effect.mapError(() => new ActionRejected({
+                message: "Runtime chat keys are application-owned; only chat, text and reply_to are accepted.",
+            })));
+            if (!envelope?.operation_id) {
+                return yield* new ActionRejected({ message: "A confirmed runtime call is required." });
+            }
+            input = { ...values, idempotency_key: envelope.operation_id };
+        }
+        const requestId = yield* RequestId;
+        const delivery = planned.name === "agent_chat" && (name === "post_message" || name === "preview_message")
+            ? chatDelivery?.({
+                backend,
+                principal,
+                caller,
+                requestId,
+                identityToken: call.identityToken,
+                ...(envelope === undefined ? {} : { envelope }),
+            })
+            : undefined;
+        const hook = hooks.get(`${planned.name}.${name}`);
+        const run = backend.runAction({
+            entity: planned.name,
+            action: name,
+            input,
+            ...(call.runtime !== undefined
+                ? { runtime: call.runtime }
+                : caller.kind === "runtime" && envelope?.source !== undefined
+                    ? { runtime: { source: envelope.source } }
+                    : {}),
+            principal,
+            options: {
+                ...call.options,
+                validateOnly: call.validateOnly,
+                ...(call.confirm === undefined ? {} : { confirm: call.confirm }),
+            },
+            requestId,
+            connections: connections({
+                identityToken: call.identityToken,
+                audit: { action: `${planned.name}.${name}`, principalId: principal.id, requestId },
+            }),
+            ...(hook || backend.replicationEnabled
+                ? {
+                    afterCommit: (committed) => Effect.gen(function* () {
+                        if (hook) {
+                            const run = ontology.config.hooks === undefined
+                                ? undefined
+                                : async (target) => {
+                                    if (target.as !== "service" ||
+                                        backend.resolveHookService === undefined) {
+                                        throw new Error("Hook service execution is unavailable.");
+                                    }
+                                    const principal = await Effect.runPromise(backend.resolveHookService(nameToWire(ontology.config.hooks.role)));
+                                    const planned = plan.entities.find((entity) => entity.name === nameToWire(target.entity));
+                                    const action = planned?.actions.find((candidate) => candidate.name === nameToWire(target.action));
+                                    if (principal === undefined ||
+                                        planned === undefined ||
+                                        action === undefined) {
+                                        throw new Error("The hook principal or target action is unavailable.");
+                                    }
+                                    const answer = await Effect.runPromise(runActionOf(backend, plan, hooks, connections, replicate, chatDelivery)(planned, action, {
+                                        input: await Effect.runPromise(Schema.encodeUnknownEffect(action.action.input)(target.input)),
+                                        validateOnly: false,
+                                        identityToken: call.identityToken,
+                                    }).pipe(Effect.provideService(CurrentPrincipal, principal), Effect.provideService(CurrentCaller, {
+                                        kind: "service",
+                                        subjectId: principal.id,
+                                    }), Effect.provideService(RequestId, requestId)));
+                                    return answer.result;
+                                };
+                            yield* afterCommitOf(hook, { requestId, generated }, ontology, run)(committed);
+                        }
+                        if (committed.edits.length > 0 &&
+                            (yield* backend.replicationEnabled ?? Effect.succeed(false))) {
+                            yield* replicate(call.identityToken);
+                        }
+                    }).pipe(Effect.catchCause((cause) => Effect.logWarning("ontology.replication.deferred", cause))),
+                }
+                : {}),
+        });
+        const outcome = yield* delivery === undefined
+            ? run
+            : run.pipe(Effect.provideService(ChatDelivery, delivery));
+        if (call.validateOnly &&
+            outcome.validation.ok &&
+            planned.name === "agent_chat" &&
+            name === "post_message" &&
+            delivery) {
+            const decoded = yield* Schema.decodeUnknownEffect(ChatPostWire)(input).pipe(Effect.mapError(() => new ActionRejected({ message: "Invalid exact chat post input." })));
+            yield* delivery.validate(decoded);
+        }
+        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, ontology) {
+    return Effect.gen(function* () {
+        const principal = yield* CurrentPrincipal;
+        const caller = yield* currentCaller;
+        // 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,
+            ...(principal.scopes === undefined || principal.scopes.length === 0
+                ? {}
+                : {
+                    scopes: principal.scopes.map(({ permission, where }) => ({ permission, where })),
+                }),
+            authentication: {
+                kind: caller.kind,
+                client: caller.kind === "oauth" ? caller.client : null,
+                scope: caller.kind === "oauth" ? caller.scope : null,
+            },
+            attribution: chatAttribution(caller, String(user.name), ontology.config.chat?.attribution),
+            attribution_separator: ontology.config.chat?.attribution?.separator ?? "\n\n",
+        };
+    });
+}
+/**
+ * The operations of a planned ontology, bound to its backend, after-commit hooks, connections and,
+ * on deployments with one, the workspace's agent.
+ */
+export function makeOperations(backend, plan, hooks, connections, replicate, chatDelivery) {
+    const targets = relationshipTargets(plan);
+    const reads = recordReads(backend, plan);
+    return {
+        /** A page of records. Requires `read` on the entity and on every entity the query reaches. */
+        find: (planned, query) => findOf(reads, targets, planned.name, query),
+        /** One record. Requires `read` on the entity. */
+        get: (planned, id) => getOf(reads, 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(reads, targets, planned, traversal, id, query),
+        /** Runs an action as the caller, with the action's after-commit hook and connections. */
+        runAction: runActionOf(backend, plan, hooks, connections, replicate, chatDelivery),
+        /** The caller's user, roles and permissions. It needs no permission. */
+        caller: callerOf(backend, plan.ontology),
+    };
+}

package/dist/service/plan.d.ts

@@ -0,0 +1,57 @@
+import type { AnyAction } from "../action.js";
+import type { ResolvedEntity } from "../analyze.js";
+import type { Ontology } from "../ontology.js";
+import type { GeneratedActionsProvider } from "./runtime-contract.js";
+/**
+ * How a traversal reaches its records:
+ * - `one`: the record's own `rel.one` (`note → lead`), at most one record;
+ * - `many`: the record's own `rel.many` (`lead → tags`);
+ * - `inverseOfOne`: records whose `rel.one` points here (`lead → notes`);
+ * - `inverseOfMany`: records whose `rel.many` contains this record (`tag → leads`).
+ */
+export type TraversalKind = "one" | "many" | "inverseOfOne" | "inverseOfMany";
+/** `GET /api/ontology/<entity>/{id}/<name>`. */
+export interface Traversal {
+    readonly name: string;
+    readonly kind: TraversalKind;
+    /** The entity whose records the traversal returns. */
+    readonly target: string;
+    /** The name of the same relationship as seen from the target. */
+    readonly opposite: string;
+    /** The phrase from this entity's side, for example "is owned by" or "owns". */
+    readonly phrase: string;
+    readonly description: string;
+    /** A warehouse boundary is joined by these mapped properties, never by a fabricated foreign key. */
+    readonly match?: {
+        readonly source: string;
+        readonly target: string;
+    };
+}
+export interface PlannedAction {
+    readonly name: string;
+    readonly action: AnyAction;
+    readonly generated: boolean;
+    /** Every permission a principal needs to run it. */
+    readonly permissions: ReadonlyArray<string>;
+    /** The entities an authored action declares it writes, by name; absent when it declares none. */
+    readonly writes?: ReadonlyArray<string>;
+}
+export interface PlannedEntity {
+    readonly name: string;
+    readonly resolved: ResolvedEntity;
+    /** Declared relationships first, then the inverses that land on this entity. */
+    readonly traversals: ReadonlyArray<Traversal>;
+    /** Generated actions first, then the authored ones. */
+    readonly actions: ReadonlyArray<PlannedAction>;
+}
+/** The routes the service derives from an ontology, shared by the API definition and its handlers. */
+export interface ApiPlan {
+    readonly ontology: Ontology;
+    readonly entities: ReadonlyArray<PlannedEntity>;
+}
+/**
+ * Plans the routes of a checked ontology. `check` already refuses names that would shadow a route of
+ * the service; this throws {@link InvalidOntology} when a generated action would shadow an authored
+ * one.
+ */
+export declare function planApi(ontology: Ontology, generatedActions: GeneratedActionsProvider): ApiPlan;