@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/names.js

@@ -0,0 +1,110 @@
+/** Ontology names: lowercase snake_case. */
+export const SNAKE_CASE_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+/** TypeScript names are converted only at the ontology's serialization boundary. */
+function isUppercase(letter) {
+    return letter !== undefined && letter >= "A" && letter <= "Z";
+}
+function isLowercase(letter) {
+    return letter !== undefined && letter >= "a" && letter <= "z";
+}
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export function toSnakeCase(name) {
+    if (name.toLowerCase() === name) {
+        return name;
+    }
+    const characters = [];
+    for (let index = 0; index < name.length; index++) {
+        const current = name[index];
+        const previous = name[index - 1];
+        const next = name[index + 1];
+        const followsWord = isLowercase(previous) || (previous !== undefined && previous >= "0" && previous <= "9");
+        const endsAcronym = isUppercase(previous) && isLowercase(next);
+        if (isUppercase(current) && (followsWord || endsAcronym)) {
+            characters.push("_");
+        }
+        characters.push(current);
+    }
+    return characters.join("").toLowerCase();
+}
+export function toCamelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+// @legacy ontology.camelcase-member-names
+/** Historical property names accepted only as explicit rename sources. */
+export const LEGACY_MEMBER_NAME = /^(?:[a-z][a-zA-Z0-9]*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
+/** Stable entity identities, for example `ent_01J9Q4M8ZK`. */
+export const ENTITY_ID = /^ent_[A-Za-z0-9_]+$/;
+/** Properties every entity has. They are never declared and cannot be redeclared. */
+export const SYSTEM_PROPERTIES = [
+    "id",
+    "created_at",
+    "updated_at",
+    "created_by",
+    "updated_by",
+];
+/** Actions the platform generates for every entity; authored actions cannot use these names. */
+export const GENERATED_ACTIONS = ["create", "update", "delete", "link", "unlink"];
+/** Prefix of the generated `upsert_by_<property>` actions. */
+export const GENERATED_UPSERT_PREFIX = "upsert_by_";
+/** The built-in role every active app user holds. */
+export const MEMBER_ROLE = "member";
+/** Implicit human feedback authority; never a stored or assignable role. */
+export const FEEDBACK_REPORTER_ROLE = "feedback_reporter";
+/** Suffix reserved for the history table each entity gets. */
+export const HISTORY_SUFFIX = "_history";
+/** The combinators of the query language, which take the place of field names in a `where`. */
+export const RESERVED_MEMBER_NAMES = ["and", "or", "not"];
+/**
+ * The ontology service's route for metric queries across entities, `/api/ontology/query_metrics`,
+ * named as the MCP tool is. Each entity with metrics has `/api/ontology/<entity>/query_metrics`.
+ */
+export const QUERY_METRICS_ROUTE = "query_metrics";
+/** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
+export const RESERVED_ENTITY_NAMES = [
+    "chat",
+    QUERY_METRICS_ROUTE,
+    "graph",
+    "status",
+    "describe",
+    "openapi",
+    "docs",
+    "mcp",
+    "me",
+    "oauth",
+    "agent",
+    "workflows",
+];
+/** The MCP tools of every stored entity's reads: `lead_find`, `lead_get` and `lead_history`. */
+export const MCP_READ_TOOLS = ["find", "get", "history"];
+/** The MCP tools of the ontology as a whole. No entity tool can take them: they have no underscore. */
+export const MCP_GLOBAL_TOOLS = ["discover", "me"];
+/**
+ * The metric tools, named as dbt names its MCP tools. Their names have an underscore, so `check`
+ * refuses an entity tool that takes one, such as entity `list`'s action `metrics`.
+ */
+export const MCP_METRIC_TOOLS = [
+    "list_metrics",
+    "get_dimensions",
+    "get_dimension_values",
+    "query_metrics",
+];
+/** The longest tool name that Claude and OpenAI accept. */
+export const MCP_TOOL_NAME_MAX_LENGTH = 64;
+/** The MCP tool of an entity's read or action: `lead_find`, `lead_change_status`. */
+export function mcpToolName(entity, operation) {
+    return `${entity}_${operation}`;
+}
+/** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
+export const RESERVED_RELATIONSHIP_NAMES = ["history"];
+export function isSystemProperty(name) {
+    return SYSTEM_PROPERTIES.includes(name);
+}
+/** `created_at` → `Created at`, `pilot_request` → `Pilot request`. */
+export function humanize(name) {
+    const words = name
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[_-]+/g, " ")
+        .trim()
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}

package/dist/navigation-artifact.d.ts

@@ -0,0 +1,13 @@
+import { type PageCatalogV1 } from "./navigation-catalog.js";
+declare global {
+    interface ImportMeta {
+        readonly segmentstreamNavigationCatalog?: unknown;
+    }
+}
+/** Capability gate for immutable catalog transport; independent of SDK release numbering. */
+export declare const NAVIGATION_ARTIFACT_VERSION = 1;
+/**
+ * Nitro replaces this import-meta property with validated catalog JSON at build time. There is no
+ * runtime file, environment variable, or Cloud row to change the deployment's navigation catalog.
+ */
+export declare function bundledNavigationCatalog(): PageCatalogV1 | undefined;

package/dist/navigation-artifact.js

@@ -0,0 +1,11 @@
+import { parsePageCatalog } from "./navigation-catalog.js";
+/** Capability gate for immutable catalog transport; independent of SDK release numbering. */
+export const NAVIGATION_ARTIFACT_VERSION = 1;
+/**
+ * Nitro replaces this import-meta property with validated catalog JSON at build time. There is no
+ * runtime file, environment variable, or Cloud row to change the deployment's navigation catalog.
+ */
+export function bundledNavigationCatalog() {
+    const value = import.meta.segmentstreamNavigationCatalog;
+    return value === undefined ? undefined : parsePageCatalog(value);
+}

package/dist/navigation-catalog.d.ts

@@ -0,0 +1,55 @@
+/** Workspace-authored metadata beside an ordinary UI page. Routes are generated, never authored. */
+export interface PageMetadata {
+    readonly title: string;
+    readonly entities: readonly string[];
+    readonly description: string;
+    readonly parameters?: Readonly<Record<string, string>>;
+    readonly query?: Readonly<Record<string, string>>;
+}
+export interface PageEntry {
+    readonly ref: string;
+    readonly route: string;
+    readonly title: string;
+    readonly description: string;
+    readonly entities: readonly string[];
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly kind: "segment" | "catch_all";
+        readonly required: boolean;
+        readonly description?: string;
+    }[];
+    readonly query: Readonly<Record<string, string>>;
+}
+export interface PageCatalogV1 {
+    readonly version: 1;
+    readonly revision: string;
+    readonly pages: readonly PageEntry[];
+}
+export declare const NAVIGATION_CATALOG_LIMITS: Readonly<{
+    pages: 1000;
+    bytes: number;
+    title: 120;
+    description: 2000;
+    hint: 512;
+    associations: 32;
+    hints: 32;
+    responseBytes: number;
+}>;
+/**
+ * Whether a generated page and a routing source can share a path. Compare complete segment
+ * shapes for ordinary parameters, optional parameters and catch-alls; custom regex sources
+ * remain conservative when their static prefixes cannot prove disjointness.
+ */
+export declare function navigationRoutesMayOverlap(route: string, source: string): boolean;
+export declare class NavigationCatalogError extends Error {
+    readonly code: "invalid_page_catalog" | "page_catalog_too_large";
+    readonly name = "NavigationCatalogError";
+    constructor(code: "invalid_page_catalog" | "page_catalog_too_large", message: string);
+}
+/** Validate and copy an untrusted artifact. Entity existence is checked against the serving ontology. */
+export declare function parsePageCatalog(value: unknown): PageCatalogV1;
+/** Generate an immutable catalog identity from normalized metadata, ontology, and source identity. */
+export declare function createPageCatalog(pages: readonly PageEntry[], context: {
+    readonly ontologyHash: string;
+    readonly sourceHash: string;
+}): PageCatalogV1;

package/dist/navigation-catalog.js

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+export const NAVIGATION_CATALOG_LIMITS = Object.freeze({
+    pages: 1_000,
+    bytes: 1024 * 1024,
+    title: 120,
+    description: 2_000,
+    hint: 512,
+    associations: 32,
+    hints: 32,
+    responseBytes: 32 * 1024,
+});
+function routeShape(path, source) {
+    if (!path.startsWith("/")) {
+        return undefined;
+    }
+    const result = [];
+    for (const segment of path.split("/").filter(Boolean)) {
+        const parameter = source
+            ? /^:[A-Za-z0-9_]+([?*+]?)$/u.exec(segment)
+            : /^(?:\[\[\.\.\.[^\[\]]+\]\]|\[\.\.\.[^\[\]]+\]|\[[^\[\]]+\])$/u.exec(segment);
+        if (parameter) {
+            result.push({
+                literal: undefined,
+                optional: source ? ["?", "*"].includes(parameter[1]) : segment.startsWith("[["),
+                repeat: source ? ["*", "+"].includes(parameter[1]) : segment.includes("..."),
+            });
+        }
+        else if (/[:()*+?{}\\\[\]%]/u.test(segment)) {
+            return undefined;
+        }
+        else {
+            result.push({ literal: segment.toLowerCase(), optional: false, repeat: false });
+        }
+    }
+    return result;
+}
+/**
+ * Whether a generated page and a routing source can share a path. Compare complete segment
+ * shapes for ordinary parameters, optional parameters and catch-alls; custom regex sources
+ * remain conservative when their static prefixes cannot prove disjointness.
+ */
+export function navigationRoutesMayOverlap(route, source) {
+    const page = routeShape(route, false);
+    const rule = routeShape(source, true);
+    if (page === undefined || rule === undefined) {
+        const pagePrefix = route.split("[")[0].toLowerCase();
+        const rulePrefix = source.split(/[:(*?+{\\]/u)[0].toLowerCase();
+        return (pagePrefix.includes("%") ||
+            rulePrefix.includes("%") ||
+            pagePrefix.startsWith(rulePrefix) ||
+            rulePrefix.startsWith(pagePrefix));
+    }
+    const pending = [[0, 0]];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const [left, right] = pending.pop();
+        const key = `${left}:${right}`;
+        if (visited.has(key)) {
+            continue;
+        }
+        visited.add(key);
+        if (left === page.length && right === rule.length) {
+            return true;
+        }
+        const a = page[left];
+        const b = rule[right];
+        if (a?.optional) {
+            pending.push([left + 1, right]);
+        }
+        if (b?.optional) {
+            pending.push([left, right + 1]);
+        }
+        if (a && b && (a.literal === undefined || b.literal === undefined || a.literal === b.literal)) {
+            pending.push([left + 1, right + 1]);
+            if (a.repeat) {
+                pending.push([left, right + 1]);
+            }
+            if (b.repeat) {
+                pending.push([left + 1, right]);
+            }
+        }
+    }
+    return false;
+}
+export class NavigationCatalogError extends Error {
+    code;
+    name = "NavigationCatalogError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function invalid(message) {
+    throw new NavigationCatalogError("invalid_page_catalog", message);
+}
+function bounded(condition, message) {
+    if (!condition) {
+        throw new NavigationCatalogError("page_catalog_too_large", message);
+    }
+}
+function object(value, fields) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return invalid("Navigation metadata must be a JSON object.");
+    }
+    if (fields !== undefined && Object.keys(value).some((key) => !fields.includes(key))) {
+        return invalid("Navigation metadata contains an unknown field.");
+    }
+    return value;
+}
+function text(value, maximum, field) {
+    if (typeof value !== "string" ||
+        value.trim() === "" ||
+        /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(value)) {
+        return invalid(`${field} must be nonblank text without control characters.`);
+    }
+    bounded(Array.from(value).length <= maximum, `${field} exceeds ${maximum} Unicode code points.`);
+    return value;
+}
+function hints(value) {
+    const entries = Object.entries(object(value));
+    bounded(entries.length <= NAVIGATION_CATALOG_LIMITS.hints, "A page has more than 32 query hints.");
+    return Object.freeze(Object.fromEntries(entries
+        .sort(([a], [b]) => compare(a, b))
+        .map(([key, hint]) => [
+        text(key, NAVIGATION_CATALOG_LIMITS.responseBytes, "Query name"),
+        text(hint, NAVIGATION_CATALOG_LIMITS.hint, "Query hint"),
+    ])));
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function entry(value) {
+    const page = object(value, [
+        "ref",
+        "route",
+        "title",
+        "description",
+        "entities",
+        "parameters",
+        "query",
+    ]);
+    const route = text(page.route, NAVIGATION_CATALOG_LIMITS.responseBytes, "Page route");
+    if (!route.startsWith("/") || /[?#\\\s\u007f]/u.test(route) || route.includes("//")) {
+        return invalid("A page route must be a normalized absolute path without an origin or query.");
+    }
+    const segments = route.slice(1).split("/").filter(Boolean);
+    const routeParameters = [];
+    for (const [index, segment] of segments.entries()) {
+        const match = /^(?:\[\[\.\.\.([^\[\]/]+)\]\]|\[\.\.\.([^\[\]/]+)\]|\[([^\[\]/]+)\])$/u.exec(segment);
+        if (match) {
+            const name = match[1] ?? match[2] ?? match[3];
+            const kind = match[3] === undefined ? "catch_all" : "segment";
+            text(name, NAVIGATION_CATALOG_LIMITS.responseBytes, "Parameter name");
+            if (routeParameters.some((parameter) => parameter.name === name) ||
+                (kind === "catch_all" && index !== segments.length - 1)) {
+                return invalid("Route parameters must be unique and catch-all parameters must be last.");
+            }
+            routeParameters.push({ name, kind, required: match[1] === undefined });
+        }
+        else {
+            let decoded;
+            try {
+                decoded = decodeURIComponent(segment);
+            }
+            catch {
+                return invalid("Page route has invalid percent encoding.");
+            }
+            if (decoded === "." || decoded === ".." || /[\[\]\/\\\u0000-\u0020\u007f]/u.test(decoded)) {
+                return invalid("Page route has an unsupported or unsafe segment.");
+            }
+        }
+    }
+    if (page.ref !== `page:${route}`) {
+        return invalid("Page references must be page: followed by the normalized route.");
+    }
+    if (!Array.isArray(page.entities) || !Array.isArray(page.parameters)) {
+        return invalid("Page entities and parameters must be arrays.");
+    }
+    bounded(page.entities.length <= NAVIGATION_CATALOG_LIMITS.associations, "A page has more than 32 entities.");
+    const entities = Array.from(page.entities, (name) => {
+        if (typeof name !== "string" || !/^[a-z][a-z0-9_]*$/u.test(name)) {
+            return invalid("Page entity associations must be canonical ontology names.");
+        }
+        return name;
+    });
+    if (new Set(entities).size !== entities.length) {
+        return invalid("A page repeats an entity association.");
+    }
+    if (page.parameters.length !== routeParameters.length) {
+        return invalid("Page parameters must exactly describe their route.");
+    }
+    const declaredParameters = page.parameters;
+    const parameters = routeParameters.map((expected, index) => {
+        const parameter = object(declaredParameters[index], [
+            "name",
+            "kind",
+            "required",
+            "description",
+        ]);
+        if (parameter.name !== expected.name ||
+            parameter.kind !== expected.kind ||
+            parameter.required !== expected.required) {
+            return invalid("Page parameters must match their route in path order.");
+        }
+        return Object.freeze({
+            ...expected,
+            ...(parameter.description === undefined
+                ? {}
+                : {
+                    description: text(parameter.description, NAVIGATION_CATALOG_LIMITS.hint, "Parameter hint"),
+                }),
+        });
+    });
+    bounded(parameters.filter((parameter) => parameter.description !== undefined).length <=
+        NAVIGATION_CATALOG_LIMITS.hints, "A page has more than 32 parameter hints.");
+    const normalized = Object.freeze({
+        ref: `page:${route}`,
+        route,
+        title: text(page.title, NAVIGATION_CATALOG_LIMITS.title, "Page title"),
+        description: text(page.description, NAVIGATION_CATALOG_LIMITS.description, "Page description"),
+        entities: Object.freeze(entities.sort(compare)),
+        parameters: Object.freeze(parameters),
+        query: hints(page.query),
+    });
+    // An entry must fit even when more results follow. Runtime checks the actual origin/envelope too.
+    const revision = `sha256:${"0".repeat(64)}`;
+    const result = {
+        revision,
+        pages: [
+            {
+                ...normalized,
+                [parameters.length === 0 ? "url" : "url_pattern"]: `https://navigation.invalid${route}`,
+            },
+        ],
+        next_cursor: Buffer.from(JSON.stringify({
+            revision,
+            scope: "0".repeat(64),
+            request: "0".repeat(64),
+            last: normalized.ref,
+        })).toString("base64url"),
+    };
+    bounded(Buffer.byteLength(JSON.stringify({
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: result,
+    })) <= NAVIGATION_CATALOG_LIMITS.responseBytes, "A complete page entry exceeds the MCP response budget.");
+    return normalized;
+}
+/** Canonical JSON is independent of insertion order, process locale, and object prototypes. */
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => compare(a, b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Validate and copy an untrusted artifact. Entity existence is checked against the serving ontology. */
+export function parsePageCatalog(value) {
+    const catalog = object(value, ["version", "revision", "pages"]);
+    if (catalog.version !== 1 ||
+        typeof catalog.revision !== "string" ||
+        !/^sha256:[a-f0-9]{64}$/u.test(catalog.revision) ||
+        !Array.isArray(catalog.pages)) {
+        return invalid("Expected a version-1 page catalog with a SHA-256 revision and pages array.");
+    }
+    bounded(catalog.pages.length <= NAVIGATION_CATALOG_LIMITS.pages, "A catalog has more than 1,000 pages.");
+    const pages = Array.from(catalog.pages, entry).sort((a, b) => compare(a.ref, b.ref));
+    if (new Set(pages.map((page) => page.ref)).size !== pages.length) {
+        return invalid("Page catalog contains duplicate routes.");
+    }
+    const normalized = {
+        version: 1,
+        revision: catalog.revision,
+        pages: Object.freeze(pages),
+    };
+    bounded(Buffer.byteLength(canonical(normalized)) <= NAVIGATION_CATALOG_LIMITS.bytes, "Page catalog exceeds 1 MiB.");
+    return Object.freeze(normalized);
+}
+/** Generate an immutable catalog identity from normalized metadata, ontology, and source identity. */
+export function createPageCatalog(pages, context) {
+    text(context.ontologyHash, NAVIGATION_CATALOG_LIMITS.bytes, "Ontology hash");
+    text(context.sourceHash, NAVIGATION_CATALOG_LIMITS.bytes, "Source hash");
+    const normalized = parsePageCatalog({ version: 1, revision: `sha256:${"0".repeat(64)}`, pages });
+    const revision = `sha256:${createHash("sha256")
+        .update(canonical({
+        version: 1,
+        pages: normalized.pages,
+        ontologyHash: context.ontologyHash,
+        sourceHash: context.sourceHash,
+    }))
+        .digest("hex")}`;
+    return Object.freeze({ ...normalized, revision });
+}

package/dist/nitro-navigation.d.ts

@@ -0,0 +1,3 @@
+import type { Nitro } from "nitro/types";
+/** Called by the SDK's Nitro module, before independently compiling the ontology service. */
+export declare function setupNavigationCatalog(nitro: Nitro): Promise<void>;

package/dist/nitro-navigation.js

@@ -0,0 +1,64 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parsePageCatalog } from "./navigation-catalog.js";
+async function optionalFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/** Called by the SDK's Nitro module, before independently compiling the ontology service. */
+export async function setupNavigationCatalog(nitro) {
+    const directory = resolve(nitro.options.rootDir, ".segmentstream/navigation");
+    const enabled = await optionalFile(resolve(directory, "enabled.json"));
+    const contents = await optionalFile(resolve(directory, "catalog.json"));
+    const receipt = resolve(directory, "build-binding.json");
+    let replacement = "undefined";
+    await rm(receipt, { force: true });
+    if (enabled !== undefined) {
+        const marker = JSON.parse(enabled);
+        if (marker === null ||
+            typeof marker !== "object" ||
+            Array.isArray(marker) ||
+            Object.keys(marker).length !== 1 ||
+            !("version" in marker) ||
+            marker.version !== 1) {
+            throw new Error("navigation_artifact_marker_invalid");
+        }
+        if (contents === undefined) {
+            throw new Error("navigation_artifact_missing");
+        }
+        const catalog = parsePageCatalog(JSON.parse(contents));
+        replacement = JSON.stringify(catalog);
+        nitro.hooks.hook("compiled", async () => {
+            const temporary = `${receipt}.${randomUUID()}.tmp`;
+            try {
+                await writeFile(temporary, JSON.stringify({ version: 1, revision: catalog.revision }), {
+                    flag: "wx",
+                });
+                await rename(temporary, receipt);
+            }
+            finally {
+                await rm(temporary, { force: true });
+            }
+        });
+        // The replacement must reach the SDK accessor instead of leaving it in node_modules.
+        if (nitro.options.noExternals !== true) {
+            nitro.options.noExternals = [
+                ...(Array.isArray(nitro.options.noExternals) ? nitro.options.noExternals : []),
+                "@segmentstream/ontology",
+            ];
+        }
+    }
+    else if (contents !== undefined) {
+        throw new Error("navigation_artifact_marker_missing");
+    }
+    nitro.options.replace ??= {};
+    nitro.options.replace["import.meta.segmentstreamNavigationCatalog"] = replacement;
+}

package/dist/nitro-workflows.d.ts

@@ -0,0 +1,108 @@
+import { BaseBuilder } from "@workflow/builders";
+import type { Nitro } from "nitro/types";
+/**
+ * The build side of `ontologyWorkflows()` (see `./nitro.ts`), loaded only while Nitro builds.
+ */
+interface Settings {
+    readonly dirs: Array<string>;
+    readonly basePath: string;
+    readonly namespace: string;
+    readonly route: string;
+    readonly trigger: object;
+}
+/** The directory, inside Nitro's build directory, that holds the generated bundles. */
+export declare function workflowBuildDir(buildDir: string): string;
+/**
+ * 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 declare function platformWorkflowDir(rootDir: string): string;
+/** The platform workflow file the builder writes, and the name of its workflow function. */
+export declare const PLATFORM_WORKFLOW_FILE = "recover-starts.ts";
+export declare const PLATFORM_RECOVERY_WORKFLOW = "recoverStarts";
+/** Where the generated platform workflow takes the SDK from; tests point it at the sources. */
+export interface PlatformWorkflowImports {
+    /** The module that exports `recoverWorkflowStarts`: the `workflows` entry. */
+    readonly workflows: string;
+    /**
+     * Modules imported for their steps alone. The SDK's step discovery reads `./start-recovery.js`
+     * in the package's sources literally and finds no such file beside `start-recovery.ts`; the
+     * built package has it. Tests name the source module here.
+     */
+    readonly steps?: ReadonlyArray<string>;
+}
+/** The platform's workflow files: where they are written, and how they import the SDK. */
+export interface PlatformWorkflowsSettings {
+    /** The directory the files are written to, included in the build. */
+    readonly dir: string;
+    readonly imports?: PlatformWorkflowImports;
+    /** Shorter sleeps for the recovery run; tests only, production builds set none. */
+    readonly delays?: {
+        readonly firstSweepMs: number;
+        readonly confirmMs: number;
+    };
+}
+/**
+ * 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 declare function platformWorkflowSource(settings?: Pick<PlatformWorkflowsSettings, "imports" | "delays">): string;
+/**
+ * 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 declare function platformPluginSource(input: {
+    readonly file: string;
+    /** The module that exports `registerPlatformWorkflows`: the `server` entry. */
+    readonly server?: string;
+}): string;
+/**
+ * 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 declare class OntologyWorkflowBuilder extends BaseBuilder {
+    #private;
+    constructor(input: {
+        readonly workingDir: string;
+        readonly projectRoot?: string;
+        readonly dirs: Array<string>;
+        readonly basePath: string;
+        readonly namespace: string;
+        readonly outDir: string;
+        readonly watch?: boolean;
+        /** The platform's workflow files, compiled with the workspace's; none when absent. */
+        readonly platform?: PlatformWorkflowsSettings;
+    });
+    get outDir(): string;
+    /** The platform workflow file this build compiles, when it has one. */
+    get platformWorkflowFile(): string | undefined;
+    build(): Promise<void>;
+}
+/** Where the generated handler takes its runtime from; tests point them elsewhere. */
+export interface CallbackImports {
+    /** The module that exports `serveWorkflowCallback`. */
+    readonly ontology: string;
+    /** The module that exports Nitro's `serverFetch`. */
+    readonly nitroApp: string;
+}
+/**
+ * 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 declare function callbackHandlerSource(input: {
+    readonly file: string;
+    readonly dev: boolean;
+    readonly route: string;
+    readonly namespace: string;
+    readonly statusPath: string;
+    readonly imports?: CallbackImports;
+}): string;
+export declare function setupOntologyWorkflows(nitro: Nitro, settings: Settings): Promise<void>;
+export {};