@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/nitro-workflows.js

@@ -0,0 +1,286 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { BaseBuilder, createBaseBuilderConfig } from "@workflow/builders";
+import { workflowTransformPlugin } from "@workflow/rollup";
+/** The directory, inside Nitro's build directory, that holds the generated bundles. */
+export function workflowBuildDir(buildDir) {
+    return join(buildDir, "ontology-workflows");
+}
+/**
+ * The directory that holds the platform's own workflow files, which the builder writes before
+ * every build and compiles with the workspace's. Beside the navigation artifact under the
+ * project's `.segmentstream/`, which the starter ignores in Git: the Workflow SDK's builder
+ * skips files under Nitro's `.nitro/` build directory, so they cannot live there.
+ */
+export function platformWorkflowDir(rootDir) {
+    return join(rootDir, ".segmentstream", "platform-workflows");
+}
+/** The platform workflow file the builder writes, and the name of its workflow function. */
+export const PLATFORM_WORKFLOW_FILE = "recover-starts.ts";
+export const PLATFORM_RECOVERY_WORKFLOW = "recoverStarts";
+/**
+ * The platform's start recovery workflow, as a workflow file of the workspace's build: its body is
+ * the SDK's, so an SDK upgrade changes what the run does without touching the workspace's code.
+ */
+export function platformWorkflowSource(settings = {}) {
+    const from = settings.imports?.workflows ?? "@segmentstream/ontology/workflows";
+    const delays = settings.delays === undefined ? "" : JSON.stringify(settings.delays);
+    return [
+        "// Written by @segmentstream/ontology's ontologyWorkflows() before every build; not part",
+        "// of the workspace's code. The platform's start recovery run: an action whose triggers may fire",
+        "// arms one before its transaction, and it sleeps, then starts the pending starts the request",
+        "// left; see the SDK's start-recovery.ts.",
+        `import { recoverWorkflowStarts } from ${JSON.stringify(from)};`,
+        ...(settings.imports?.steps ?? []).map((module) => `import ${JSON.stringify(module)};`),
+        "",
+        `export async function ${PLATFORM_RECOVERY_WORKFLOW}() {`,
+        '  "use workflow";',
+        "",
+        `  return recoverWorkflowStarts(${delays});`,
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * The Nitro plugin that registers the compiled platform workflow with the SDK at startup, so that
+ * the service starts it as it starts a declared workflow's `run`. The server build's transform
+ * compiles the imported function like the workspace's workflow files.
+ */
+export function platformPluginSource(input) {
+    const server = input.server ?? "@segmentstream/ontology/server";
+    return [
+        `import { registerPlatformWorkflows } from ${JSON.stringify(server)};`,
+        `import { ${PLATFORM_RECOVERY_WORKFLOW} } from ${JSON.stringify(pathToFileURL(input.file).href)};`,
+        "",
+        "export default function registerOntologyPlatformWorkflows() {",
+        `  registerPlatformWorkflows({ recoverStarts: ${PLATFORM_RECOVERY_WORKFLOW} });`,
+        "}",
+        "",
+    ].join("\n");
+}
+/** The generated entrypoint call the builder writes, before the namespace is added to it. */
+const ENTRYPOINT_CALL = "workflowEntrypoint(workflowCode, {";
+/**
+ * Bundles a folder's workflows and steps as the ontology service serves them, as the SDK's own
+ * Nitro integration does since version 5: `steps.mjs` registers the steps, and `workflows.mjs`
+ * imports it and exports the flow handler, `workflowEntrypoint(code, { namespace, basePath })`,
+ * which runs the steps. Bundles import the rest of the project and its packages, which the server
+ * build resolves.
+ */
+export class OntologyWorkflowBuilder extends BaseBuilder {
+    #outDir;
+    #namespace;
+    #platform;
+    constructor(input) {
+        super({
+            ...createBaseBuilderConfig({
+                workingDir: input.workingDir,
+                ...(input.projectRoot === undefined ? {} : { projectRoot: input.projectRoot }),
+                watch: input.watch ?? false,
+                dirs: input.platform === undefined ? input.dirs : [...input.dirs, input.platform.dir],
+            }),
+            // The builder only writes files here; no framework integration reads this target.
+            buildTarget: "next",
+            basePath: input.basePath,
+        });
+        this.#outDir = input.outDir;
+        this.#namespace = input.namespace;
+        this.#platform = input.platform;
+    }
+    get outDir() {
+        return this.#outDir;
+    }
+    /** The platform workflow file this build compiles, when it has one. */
+    get platformWorkflowFile() {
+        return this.#platform === undefined
+            ? undefined
+            : join(this.#platform.dir, PLATFORM_WORKFLOW_FILE);
+    }
+    async build() {
+        if (this.#platform !== undefined) {
+            await mkdir(this.#platform.dir, { recursive: true });
+            await writeFile(join(this.#platform.dir, PLATFORM_WORKFLOW_FILE), platformWorkflowSource(this.#platform));
+        }
+        const inputFiles = await this.getInputFiles();
+        const flowFile = join(this.#outDir, "workflows.mjs");
+        await mkdir(this.#outDir, { recursive: true });
+        const built = (await this.createCombinedBundle({
+            inputFiles,
+            stepsOutfile: join(this.#outDir, "steps.mjs"),
+            flowOutfile: flowFile,
+            format: "esm",
+            bundleFinalOutput: false,
+            externalizeNonSteps: true,
+            bundleTransitiveLocalStepDependencies: this.config.watch,
+        }));
+        await Promise.all([built.stepsContext?.dispose(), built.interimBundleCtx?.dispose()]);
+        // The builder takes the namespace only from the environment; it is written here instead, so
+        // that no build of the app or the agent in the same project picks it up.
+        const flow = await readFile(flowFile, "utf8");
+        if (flow.split(ENTRYPOINT_CALL).length !== 2) {
+            throw new Error(`The Workflow SDK's generated flow route no longer contains ${ENTRYPOINT_CALL} once; ` +
+                "the ontology's queue namespace cannot be set.");
+        }
+        await writeFile(flowFile, flow.replace(ENTRYPOINT_CALL, `workflowEntrypoint(workflowCode, { namespace: ${JSON.stringify(this.#namespace)},`));
+        await this.createManifest({
+            workflowBundlePath: flowFile,
+            manifestDir: this.#outDir,
+            manifest: built.manifest,
+        });
+    }
+}
+/** See `addNodeRequireBanner` in `workflow/nitro`: undici loads `node:http2` with `require`. */
+const REQUIRE_BANNER = "import { createRequire as __wkfCreateRequire } from 'node:module'; " +
+    "if (typeof globalThis.require === 'undefined') { " +
+    "globalThis.require = __wkfCreateRequire(import.meta.url); }";
+function addRequireBanner(config) {
+    const outputs = (Array.isArray(config.output) ? config.output : [(config.output ??= {})]);
+    for (const output of outputs) {
+        const existing = output.banner;
+        output.banner =
+            existing == null
+                ? REQUIRE_BANNER
+                : typeof existing === "function"
+                    ? async (chunk) => `${REQUIRE_BANNER}\n${await existing(chunk)}`
+                    : `${REQUIRE_BANNER}\n${String(existing)}`;
+    }
+}
+const DEFAULT_IMPORTS = {
+    ontology: "@segmentstream/ontology",
+    nitroApp: "nitro/app",
+};
+/**
+ * The flow handler module. It answers only a queue delivery at its exact route, warms the
+ * ontology service of this instance first, through Nitro's own fetch, so that `run(effect)` finds
+ * its runtime, and keeps the request's Vercel OIDC token for the steps' connection calls.
+ */
+export function callbackHandlerSource(input) {
+    const { file, dev, route, namespace, statusPath } = input;
+    const imports = input.imports ?? DEFAULT_IMPORTS;
+    const options = JSON.stringify({ route, queuePrefix: `__${namespace}_wkf_workflow_` });
+    const head = [
+        `import { serverFetch } from ${JSON.stringify(imports.nitroApp)};`,
+        `import { serveWorkflowCallback } from ${JSON.stringify(imports.ontology)};`,
+        `const options = { ...${options}, warm: () => serverFetch(${JSON.stringify(statusPath)}) };`,
+    ];
+    if (dev) {
+        // Load the bundle from disk on each change, outside Nitro's own module graph.
+        return [
+            'import { statSync } from "node:fs";',
+            'import { pathToFileURL } from "node:url";',
+            ...head,
+            `const handlerPath = ${JSON.stringify(file)};`,
+            'let version = "";',
+            "let loaded;",
+            "async function load() {",
+            "  const current = String(statSync(handlerPath).mtimeMs);",
+            "  if (current !== version || loaded === undefined) {",
+            "    version = current;",
+            '    loaded = (await import(pathToFileURL(handlerPath).href + "?t=" + current)).POST;',
+            "  }",
+            "  return loaded;",
+            "}",
+            "export default async ({ req }) => serveWorkflowCallback(req, await load(), options);",
+            "",
+        ].join("\n");
+    }
+    return [
+        `import { POST } from ${JSON.stringify(file)};`,
+        ...head,
+        "export default async ({ req }) => serveWorkflowCallback(req, POST, options);",
+        "",
+    ].join("\n");
+}
+export async function setupOntologyWorkflows(nitro, settings) {
+    const outDir = workflowBuildDir(nitro.options.buildDir);
+    const platformDir = platformWorkflowDir(nitro.options.rootDir);
+    const builder = new OntologyWorkflowBuilder({
+        workingDir: nitro.options.rootDir,
+        ...(nitro.options.workspaceDir === undefined
+            ? {}
+            : { projectRoot: nitro.options.workspaceDir }),
+        dirs: settings.dirs,
+        basePath: settings.basePath,
+        namespace: settings.namespace,
+        outDir,
+        watch: nitro.options.dev,
+        platform: { dir: platformDir },
+    });
+    const buildDirPrefix = `${nitro.options.buildDir.replace(/[\\/]+$/, "")}/`;
+    nitro.hooks.hook("rollup:before", ((_nitro, config) => {
+        // First, before other transforms rename classes; the generated bundles are already transformed.
+        // The platform workflow file, outside the build directory, is compiled here like the
+        // workspace's.
+        config.plugins.unshift(workflowTransformPlugin({ exclude: [buildDirPrefix] }));
+        if (!nitro.options.dev) {
+            addRequireBanner(config);
+        }
+    }));
+    // The SDK's runtime imports `debug`, which unenv would otherwise mock.
+    nitro.options.alias.debug ??= "debug";
+    let initial = true;
+    // Builds write one directory, and an editor's save can reload Nitro twice in a row: builds run
+    // one at a time, and reloads during a build share the one build that follows it.
+    let running = Promise.resolve();
+    let queued;
+    const build = () => {
+        queued ??= running
+            .catch(() => undefined)
+            .then(() => {
+            queued = undefined;
+            return builder.build();
+        });
+        running = queued;
+        return queued;
+    };
+    nitro.hooks.hook("build:before", build);
+    if (nitro.options.dev) {
+        // A failed rebuild is reported once and keeps the server on the previous bundle.
+        const reported = new WeakMap();
+        nitro.hooks.hook("dev:reload", (async () => {
+            if (initial) {
+                initial = false;
+                return;
+            }
+            const built = build();
+            let settled = reported.get(built);
+            if (settled === undefined) {
+                settled = built.catch((error) => {
+                    nitro.logger.error("The ontology's workflows failed to build.", error);
+                });
+                reported.set(built, settled);
+            }
+            await settled;
+        }));
+    }
+    const id = "#segmentstream-ontology/workflow-flow";
+    const platformPlugin = "#segmentstream-ontology/platform-workflows";
+    // At startup, before any request: the service refuses an action whose triggers may fire until
+    // the platform's recovery workflow is registered.
+    (nitro.options.plugins ??= []).push(platformPlugin);
+    nitro.options.virtual[platformPlugin] = platformPluginSource({
+        file: join(platformDir, PLATFORM_WORKFLOW_FILE),
+    });
+    nitro.options.handlers.push({ route: settings.route, handler: id, lazy: true });
+    nitro.options.virtual[id] = callbackHandlerSource({
+        file: join(outDir, "workflows.mjs"),
+        dev: nitro.options.dev,
+        route: settings.route,
+        namespace: settings.namespace,
+        statusPath: `${settings.basePath}/status`,
+    });
+    if (nitro.options.preset.startsWith("vercel")) {
+        const vercel = (nitro.options.vercel ??= {});
+        const rules = (vercel.functionRules ??= {});
+        const existing = rules[settings.route] ?? {};
+        rules[settings.route] = {
+            ...existing,
+            maxDuration: "max",
+            experimentalTriggers: [
+                ...(existing.experimentalTriggers ?? []),
+                settings.trigger,
+            ],
+        };
+    }
+}

package/dist/nitro.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The paths the ontology service answers, for the workspace's `ontology/nitro.config.ts`. They come
+ * from the SDK, so a path the service adds arrives with an upgrade and the config stays as it is.
+ * At its top level this entry imports only Nitro's types and `./workflow-topics.js`, which imports
+ * nothing; the build side loads when Nitro runs the module.
+ */
+import type { NitroModule } from "nitro/types";
+export declare const ONTOLOGY_SERVICE_PATHS: readonly ["/api/ontology", "/api/ontology/**", "/mcp", "/.well-known/oauth-protected-resource", "/.well-known/oauth-protected-resource/mcp", "/.well-known/oauth-authorization-server", "/api/webhooks/**"];
+/** A Nitro route to the service's handler, loaded on its first request. */
+export interface OntologyRoute {
+    readonly handler: string;
+    readonly lazy: true;
+}
+/** The Nitro routes that send every path of the ontology service to one handler. */
+export declare function ontologyRoutes(handler: string): Record<string, OntologyRoute>;
+export { ONTOLOGY_QUEUE_NAMESPACE, WORKFLOW_FLOW_ROUTE, WORKFLOW_QUEUE_TRIGGER, } from "./workflow-topics.js";
+export interface OntologyWorkflowsOptions {
+    /** The directories, relative to `ontology/`, that hold workflow files. Default `["./workflows"]`. */
+    readonly dirs?: ReadonlyArray<string>;
+}
+/** A Nitro module: `modules: [ontologyWorkflows()]` in `ontology/nitro.config.ts`. */
+export type OntologyWorkflowsModule = NitroModule & {
+    readonly name: string;
+};
+/**
+ * The Workflow SDK, compiled and served by the ontology service: list it in `modules` of
+ * `ontology/nitro.config.ts`, in place of `workflow/nitro`. It
+ *
+ * - adds the SDK's transform to the server build, so `start` finds the compiled workflows;
+ * - before every build, bundles the workflows (`"use workflow"`) and their steps (`"use step"`) of
+ *   `dirs` into Nitro's build directory, with the callback's base path `/api/ontology` and the
+ *   queue namespace `ontology` written into the generated entrypoint;
+ * - mounts the flow handler, which runs the steps, in the ontology service's own server bundle at
+ *   `/api/ontology/.well-known/workflow/v1/flow`, refusing anything but a queue delivery;
+ * - on Vercel, gives that route its own function with `maxDuration: "max"` and the queue trigger
+ *   `__ontology_wkf_workflow_*`.
+ *
+ * It never uses `workflow/nitro`, and it mounts no webhook route.
+ */
+export declare function ontologyWorkflows(options?: OntologyWorkflowsOptions): OntologyWorkflowsModule;

package/dist/nitro.js

@@ -0,0 +1,50 @@
+import { ONTOLOGY_QUEUE_NAMESPACE, WORKFLOW_BASE_PATH, WORKFLOW_FLOW_ROUTE, WORKFLOW_QUEUE_TRIGGER, } from "./workflow-topics.js";
+export const ONTOLOGY_SERVICE_PATHS = [
+    "/api/ontology",
+    "/api/ontology/**",
+    "/mcp",
+    // The MCP server's OAuth metadata, on the app's origin.
+    "/.well-known/oauth-protected-resource",
+    "/.well-known/oauth-protected-resource/mcp",
+    "/.well-known/oauth-authorization-server",
+    // Webhook deliveries; the deployment routes only the declared names here.
+    "/api/webhooks/**",
+];
+/** The Nitro routes that send every path of the ontology service to one handler. */
+export function ontologyRoutes(handler) {
+    return Object.fromEntries(ONTOLOGY_SERVICE_PATHS.map((path) => [path, { handler, lazy: true }]));
+}
+export { ONTOLOGY_QUEUE_NAMESPACE, WORKFLOW_FLOW_ROUTE, WORKFLOW_QUEUE_TRIGGER, } from "./workflow-topics.js";
+/**
+ * The Workflow SDK, compiled and served by the ontology service: list it in `modules` of
+ * `ontology/nitro.config.ts`, in place of `workflow/nitro`. It
+ *
+ * - adds the SDK's transform to the server build, so `start` finds the compiled workflows;
+ * - before every build, bundles the workflows (`"use workflow"`) and their steps (`"use step"`) of
+ *   `dirs` into Nitro's build directory, with the callback's base path `/api/ontology` and the
+ *   queue namespace `ontology` written into the generated entrypoint;
+ * - mounts the flow handler, which runs the steps, in the ontology service's own server bundle at
+ *   `/api/ontology/.well-known/workflow/v1/flow`, refusing anything but a queue delivery;
+ * - on Vercel, gives that route its own function with `maxDuration: "max"` and the queue trigger
+ *   `__ontology_wkf_workflow_*`.
+ *
+ * It never uses `workflow/nitro`, and it mounts no webhook route.
+ */
+export function ontologyWorkflows(options = {}) {
+    return {
+        name: "segmentstream-ontology-workflows",
+        async setup(nitro) {
+            const { setupNavigationCatalog } = await import("./nitro-navigation.js");
+            await setupNavigationCatalog(nitro);
+            // Loaded here, while Nitro builds: this entry imports nothing at its top level.
+            const { setupOntologyWorkflows } = await import("./nitro-workflows.js");
+            await setupOntologyWorkflows(nitro, {
+                dirs: [...(options.dirs ?? ["./workflows"])],
+                basePath: WORKFLOW_BASE_PATH,
+                namespace: ONTOLOGY_QUEUE_NAMESPACE,
+                route: WORKFLOW_FLOW_ROUTE,
+                trigger: WORKFLOW_QUEUE_TRIGGER,
+            });
+        },
+    };
+}

package/dist/ontology.d.ts

@@ -0,0 +1,41 @@
+import { type AnalyzeOptions, type OntologyConfig, type ResolvedConnection, type ResolvedEntity } from "./analyze.js";
+import { type Diagnostic } from "./diagnostics.js";
+import type { AnyEntity } from "./entity.js";
+import { type OntologyManifest, type WorkflowManifest } from "./manifest.js";
+import type { ModelMetrics } from "./metric.js";
+import type { Role } from "./role.js";
+import type { SignInOptions } from "./sign-in.js";
+/** A checked ontology: the resolved definitions and the manifest built from them. */
+export interface Ontology<Entities extends ReadonlyArray<AnyEntity> = ReadonlyArray<AnyEntity>, Metrics extends ModelMetrics = ModelMetrics> {
+    /** The definition as given to `defineOntology`. */
+    readonly config: OntologyConfig<Entities, Metrics>;
+    /** The built-in `User` first, then the declared entities in order. */
+    readonly entities: ReadonlyArray<ResolvedEntity>;
+    /** The workspace-owned `member` role first, declared roles, then the implicit reporter when enabled. */
+    readonly roles: ReadonlyArray<Role>;
+    /** Who may become a member by signing in, with the default policy when the definition sets none. */
+    readonly signIn: SignInOptions;
+    /** The connections the actions call, as `defineOntology({ connections })` lists them. */
+    readonly connections: ReadonlyArray<ResolvedConnection>;
+    /** The workflows, with wire names and their triggers' input in wire form, as the manifest lists them. */
+    readonly workflows: ReadonlyArray<WorkflowManifest>;
+    readonly manifest: OntologyManifest;
+    /** Warning-level diagnostics; any error makes `defineOntology` throw. */
+    readonly warnings: ReadonlyArray<Diagnostic>;
+}
+/**
+ * Checks an ontology definition and returns every problem found, without throwing. Accepts the
+ * input of `defineOntology` or its result.
+ */
+export declare function check(input: OntologyConfig | Ontology, options?: AnalyzeOptions): ReadonlyArray<Diagnostic>;
+/**
+ * `defineOntology` with analysis options. The SDK uses it to rebuild an ontology from a deployed
+ * manifest's roles, whose permissions name entities the rebuilt ontology does not have, and whose
+ * `user` table may predate properties this SDK added to the built-in `User`.
+ */
+export declare function buildOntology<const Entities extends ReadonlyArray<AnyEntity>, const Metrics extends ModelMetrics = ModelMetrics>(config: OntologyConfig<Entities, Metrics>, options: AnalyzeOptions): Ontology<Entities, Metrics>;
+/**
+ * Resolves and checks the ontology and builds its manifest. Throws {@link InvalidOntology}, carrying
+ * every diagnostic, when `check` reports an error.
+ */
+export declare function defineOntology<const Entities extends ReadonlyArray<AnyEntity>, const Metrics extends ModelMetrics = ModelMetrics>(config: OntologyConfig<Entities, Metrics>): Ontology<Entities, Metrics>;

package/dist/ontology.js

@@ -0,0 +1,46 @@
+import { analyze, } from "./analyze.js";
+import { formatDiagnostics, InvalidOntology } from "./diagnostics.js";
+import { buildManifest } from "./manifest.js";
+function isOntology(value) {
+    return "manifest" in value && "config" in value;
+}
+/**
+ * Checks an ontology definition and returns every problem found, without throwing. Accepts the
+ * input of `defineOntology` or its result.
+ */
+export function check(input, options = {}) {
+    return analyze(isOntology(input) ? input.config : input, options).diagnostics;
+}
+/**
+ * `defineOntology` with analysis options. The SDK uses it to rebuild an ontology from a deployed
+ * manifest's roles, whose permissions name entities the rebuilt ontology does not have, and whose
+ * `user` table may predate properties this SDK added to the built-in `User`.
+ */
+export function buildOntology(config, options) {
+    const analysis = analyze(config, options);
+    const errors = analysis.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0) {
+        const noun = errors.length === 1 ? "error" : "errors";
+        throw new InvalidOntology({
+            message: `The ontology has ${errors.length} ${noun}:\n${formatDiagnostics(analysis.diagnostics)}`,
+            diagnostics: analysis.diagnostics,
+        });
+    }
+    return {
+        config,
+        entities: analysis.entities,
+        roles: analysis.roles,
+        signIn: analysis.signIn,
+        connections: analysis.connections,
+        workflows: analysis.workflows,
+        manifest: buildManifest(analysis),
+        warnings: analysis.diagnostics,
+    };
+}
+/**
+ * Resolves and checks the ontology and builds its manifest. Throws {@link InvalidOntology}, carrying
+ * every diagnostic, when `check` reports an error.
+ */
+export function defineOntology(config) {
+    return buildOntology(config, {});
+}

package/dist/permissions.d.ts

@@ -0,0 +1,198 @@
+import type { Schema } from "effect";
+import type { MeReference } from "./me.js";
+/**
+ * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
+ * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
+ * the entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
+ * holds a wildcard. A wildcard entity does not cover the entities in {@link EXPLICIT_GRANT_ENTITIES},
+ * and covers only some verbs of those in {@link WILDCARD_ENTITY_VERBS}.
+ */
+/** Any entity or any verb, in a role's permissions. */
+export declare const WILDCARD = "*";
+/** The verb of every read: lists, queries, records, history, traversals and `include`. */
+export declare const READ_VERB = "read";
+/**
+ * Entities only a permission that names them covers: `*:read` or `*:*` grant nothing on them. The
+ * built-in agent chat is in every ontology, and member's default `*:read` would otherwise show anyone
+ * who signs in the workspace's chats and who is in them; `agent_chat:read` or `agent_chat:*` does.
+ * App feedback is a member's own message to the builders: a member reads theirs through a scoped
+ * `app_feedback:read`, and only the builders' roles name it unscoped. The built-in sign-in
+ * identities hold every member's external accounts, such as their Telegram id and username: only a
+ * role that names `user_identity` reads them.
+ */
+export declare const EXPLICIT_GRANT_ENTITIES: ReadonlySet<string>;
+/**
+ * The verbs of the built-in user's member management: inviting a member, granting and revoking
+ * roles, and deactivating and reactivating a member. Like every other verb on `user` but `read` and
+ * `update`, only `user:<verb>` or `user:*` grants them.
+ */
+export declare const USER_MEMBER_VERBS: readonly ["invite", "grant_roles", "revoke_roles", "deactivate", "reactivate"];
+export type UserMemberVerb = (typeof USER_MEMBER_VERBS)[number];
+/**
+ * Entities of which a wildcard entity (`*:*`, `*:<verb>`) covers only the listed verbs; any other
+ * verb needs a permission that names the entity. A role written for business data must not
+ * administer members by accident, and an API key holding `*:*` must not grant itself roles, so
+ * `*:*` reaches `user:read` and `user:update` but none of {@link USER_MEMBER_VERBS} or an authored
+ * action on `user`.
+ */
+export declare const WILDCARD_ENTITY_VERBS: ReadonlyMap<string, ReadonlySet<string>>;
+/** Whether a wildcard entity covers this verb of this entity, both in snake_case. */
+export declare function wildcardEntityCovers(entity: string, verb: string): boolean;
+/** What the built-in `member` role holds when `defineOntology` does not say: reading everything. */
+export declare const DEFAULT_MEMBER_PERMISSIONS: ReadonlyArray<string>;
+export interface ParsedPermission {
+    /** An entity name, or `*`. */
+    readonly entity: string;
+    /** A verb, or `*`. */
+    readonly verb: string;
+}
+/** The entity and verb of a permission, or `undefined` when the value is not one. */
+export declare function parsePermission(value: unknown): ParsedPermission | undefined;
+/** The scope of workflow permissions: `workflow:<workflow>:<verb>`. */
+export declare const WORKFLOW_PERMISSION_SCOPE = "workflow";
+/** The verbs of a workflow: starting a run and reading its runs. */
+export declare const WORKFLOW_VERBS: readonly ["start", "read"];
+export type WorkflowVerb = (typeof WORKFLOW_VERBS)[number];
+export interface ParsedWorkflowPermission {
+    /** A workflow name, or `*`. */
+    readonly workflow: string;
+    /** `start`, `read` or `*`. */
+    readonly verb: string;
+}
+/**
+ * The workflow and verb of `workflow:<workflow>:<verb>`, or `undefined` when the value is not one.
+ * Workflow permissions are a scope of their own: only a permission that starts with `workflow:`
+ * grants them, so `*:*` and `*:read` cover none.
+ */
+export declare function parseWorkflowPermission(value: unknown): ParsedWorkflowPermission | undefined;
+/** `workflow:remind_stale_leads:start`. */
+export declare function workflowPermission(workflow: string, verb: WorkflowVerb): string;
+/** `lead:changeStatus`. */
+export declare function permissionOf(entity: string, verb: string): string;
+/**
+ * Whether a granted permission, which may hold wildcards, covers the required one. A wildcard entity
+ * covers every entity but those in {@link EXPLICIT_GRANT_ENTITIES}, and of those in
+ * {@link WILDCARD_ENTITY_VERBS} only the listed verbs.
+ */
+export declare function grants(granted: string, required: string): boolean;
+/**
+ * A permission as {@link grants} compares it: entity, workflow and verb names in snake_case,
+ * wildcards kept. Two permissions that grant the same thing normalise to the same string; a value
+ * that is not a permission is returned as it is.
+ */
+export declare function normalizePermission(value: string): string;
+/** A value in a scope: JSON, as in any `where`, or `me` and paths from it. */
+export type ScopeValue = Schema.Json | MeReference;
+/** Conditions on one field in a scope: a {@link import("./query.js").FieldFilter} that may use `me`. */
+export interface ScopeFilter {
+    /** `me`, or a JSON value. */
+    readonly eq?: ScopeValue;
+    readonly ne?: ScopeValue;
+    /** A path from `me`, such as `me.staffMember.division`, or JSON values. */
+    readonly in?: ReadonlyArray<Schema.Json> | MeReference;
+    readonly isNull?: boolean;
+    readonly contains?: string;
+    readonly startsWith?: string;
+    readonly gt?: number | string;
+    readonly gte?: number | string;
+    readonly lt?: number | string;
+    readonly lte?: number | string;
+    readonly between?: readonly [number | string, number | string];
+}
+/**
+ * The `where` of a scoped permission: a {@link import("./query.js").Where} of the permission's
+ * entity, in which `me` stands for the caller. A relationship compared with `me` or a path compares
+ * its key: `{ owner: me }`, `{ division: { in: me.staffMember.division } }`.
+ */
+export interface ScopeWhere {
+    readonly and?: ReadonlyArray<ScopeWhere>;
+    readonly or?: ReadonlyArray<ScopeWhere>;
+    readonly not?: ScopeWhere;
+    readonly [field: string]: ScopeFilter | {
+        readonly some?: ScopeWhere;
+        readonly none?: ScopeWhere;
+        readonly every?: ScopeWhere;
+    } | ScopeWhere | ReadonlyArray<ScopeWhere> | ScopeValue | undefined;
+}
+/**
+ * A role permission limited to the records its `where` matches. A scoped read filters the rows the
+ * caller sees; a scoped write checks the record before and after the change.
+ */
+export interface ScopedPermission {
+    /** `<entity>:<verb>`, without wildcards. */
+    readonly permission: string;
+    /** The records the permission covers; it may use `me`. */
+    readonly where: ScopeWhere;
+    /**
+     * The role reads the entity unscoped on purpose, though it scopes a write of it: silences the
+     * `scope-reads-all` warning of `check`.
+     */
+    readonly readsAll?: true;
+}
+/** Anything that holds permissions: a principal, or the reader of a catalog. */
+export interface PermissionHolder {
+    readonly execution?: import("./runtime/workload.js").WorkloadExecution;
+    readonly permissions: ReadonlyArray<string>;
+    /**
+     * The scoped entries of the held roles. A permission in `permissions` that one of them names
+     * exactly is held only within the scopes; absent means none is scoped.
+     */
+    readonly scopes?: ReadonlyArray<ScopedPermission>;
+}
+/**
+ * Whether the principal may do what `required` names: one of its permissions equals it, or covers it
+ * through a wildcard. Workload wildcards exclude user administration, feedback and writes of sign-in
+ * identities.
+ */
+export declare function isAllowed(required: string, principal: PermissionHolder): boolean;
+/**
+ * Which records of `required` the principal's grants cover, once {@link isAllowed} said it holds
+ * it: `undefined` when some grant covers it unscoped, wildcards included; otherwise the `where` of
+ * the one scoped grant that names it, or the `or` of several. Without any grant the result is
+ * `{ or: [] }`, which matches no record.
+ */
+export declare function effectiveScope(required: string, principal: PermissionHolder): ScopeWhere | undefined;
+/**
+ * The records of `entity` a holder reads: `undefined` when it holds no scoped permission or reads
+ * the entity unscoped, else the {@link effectiveScope} of `<entity>:read`. A holder without the read
+ * permission gets `undefined` too: whether it may read at all is the permission check's decision.
+ */
+export declare function readScope(entity: string, holder: PermissionHolder): ScopeWhere | undefined;
+/** Expand workload authority for permission-only catalog and documentation readers. */
+export declare function effectivePermissions(principal: PermissionHolder): ReadonlyArray<string>;
+/** The first of the required permissions the principal lacks, or `undefined` when it holds all. */
+export declare function missingPermission(required: ReadonlyArray<string>, principal: PermissionHolder): string | undefined;
+/**
+ * What a generated action requires: `<entity>:<action>`, except `upsert_by_<property>`, which may
+ * create or update and so requires both `<entity>:create` and `<entity>:update`.
+ */
+export declare function generatedActionPermissions(entity: string, action: string): ReadonlyArray<string>;
+/** A role as permissions are computed from it: the declared role or its manifest entry. */
+export interface RolePermissions {
+    readonly name: string;
+    /** Every permission the role holds, scoped or not. */
+    readonly permissions?: ReadonlyArray<string> | undefined;
+    /** The scoped ones, with their `where`. A permission none of them names is held unscoped. */
+    readonly scopes?: ReadonlyArray<ScopedPermission> | undefined;
+}
+/**
+ * The union of the permissions of the roles a principal holds, in the order the ontology declares
+ * them. A held role the ontology does not declare grants nothing.
+ */
+export declare function permissionsOf(roles: ReadonlyArray<RolePermissions>, held: ReadonlyArray<string>): ReadonlyArray<string>;
+/**
+ * The scoped entries of the roles a principal holds, in the order the ontology declares them,
+ * without the dead ones: those a held role grants unscoped, by the same permission or through a
+ * wildcard, since an unscoped grant covers every record. With {@link permissionsOf}, what a
+ * principal's `scopes` holds; {@link effectiveScope} stays the authority either way.
+ */
+export declare function scopesOf(roles: ReadonlyArray<RolePermissions>, held: ReadonlyArray<string>): ReadonlyArray<ScopedPermission>;
+/**
+ * {@link scopesOf} as a principal carries it: absent when no held role scopes a permission, so that
+ * a principal of an ontology without scoped permissions is what it was before them.
+ */
+export declare function principalScopes(roles: ReadonlyArray<RolePermissions>, held: ReadonlyArray<string>): {
+    readonly scopes?: ReadonlyArray<ScopedPermission>;
+};
+/** The roles whose permissions cover `required`, by name. */
+export declare function rolesGranting(roles: ReadonlyArray<RolePermissions>, required: string): ReadonlyArray<string>;