@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/workflow-admission-provider.js

@@ -0,0 +1,205 @@
+import { createHash } from "node:crypto";
+import { importKey } from "@workflow/core/encryption";
+import { start } from "@workflow/core/runtime";
+import { hydrateWorkflowArguments } from "@workflow/core/serialization";
+import { EntityConflictError, WorkflowRunNotFoundError } from "@workflow/errors";
+import { getQueueTopicPrefix, isTerminalWorkflowRunStatus, workflowRunIdSchema, } from "@workflow/world";
+import { ulid } from "ulid";
+import { canonicalJson } from "../manifest.js";
+import { decodeWorkflowArguments, encodeWorkflowArguments, legacyWorkflowArgumentsJson, } from "../runtime/workflow-arguments.js";
+const ADMISSION = "$segmentstream.admission";
+const BINDING = "$segmentstream.binding";
+export class WorkflowAdmissionBindingError extends Error {
+    runId;
+    reason;
+    name = "WorkflowAdmissionBindingError";
+    constructor(runId, reason) {
+        super(`workflow_admission_binding_${reason}`);
+        this.runId = runId;
+        this.reason = reason;
+    }
+}
+/** Preserve class getters, private fields, optional capabilities and method receivers. */
+function override(target, replacements) {
+    return new Proxy(target, {
+        get(original, property) {
+            if (Object.hasOwn(replacements, property)) {
+                return Reflect.get(replacements, property);
+            }
+            const value = Reflect.get(original, property, original);
+            return typeof value === "function" ? value.bind(original) : value;
+        },
+    });
+}
+function validateTarget(target) {
+    if (!target.deploymentId || target.deploymentId === "latest") {
+        throw new TypeError("workflow_admission_exact_deployment_required");
+    }
+    if (!target.namespace) {
+        throw new TypeError("workflow_admission_namespace_required");
+    }
+    getQueueTopicPrefix("workflow", target.namespace);
+}
+/** Allocate once, then persist the entire result before any call to startReservedWorkflowRun. */
+export async function allocateWorkflowRun(world, options) {
+    validateTarget(options);
+    const target = {
+        deploymentId: options.deploymentId,
+        namespace: options.namespace,
+        ...(options.region !== undefined ? { region: options.region } : {}),
+    };
+    const runId = workflowRunIdSchema.parse(`wrun_${world.createRunId?.(target) ?? ulid()}`);
+    const description = await world.describeRun?.({ runId });
+    const region = description?.region ?? target.region;
+    if (description?.region === null || (target.region && region !== target.region)) {
+        throw new WorkflowAdmissionBindingError(runId, "region");
+    }
+    return { ...target, runId, ...(region ? { region } : {}) };
+}
+async function existingRun(world, runId) {
+    try {
+        return await world.runs.get(runId, { resolveData: "all" });
+    }
+    catch (error) {
+        if (WorkflowRunNotFoundError.is(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Dispatch the database's immutable reservation through the public World override.
+ * A failed acknowledgement is uncertain: callers must retry this same reservation.
+ * This helper supplies neither a reservation store nor permission to cross a cutover fence.
+ */
+export async function startReservedWorkflowRun(world, workflow, args, options) {
+    const reservation = {
+        runId: options.reservation.runId,
+        deploymentId: options.reservation.deploymentId,
+        namespace: options.reservation.namespace,
+        ...(options.reservation.region !== undefined ? { region: options.reservation.region } : {}),
+    };
+    const { runId } = reservation;
+    const workflowId = workflow.workflowId;
+    validateTarget(reservation);
+    workflowRunIdSchema.parse(runId);
+    if (!options.admissionId || !workflowId) {
+        throw new WorkflowAdmissionBindingError(runId, "identity");
+    }
+    const input = encodeWorkflowArguments(args);
+    const snapshot = decodeWorkflowArguments(input);
+    const attributes = { ...options.attributes };
+    if (Object.hasOwn(attributes, ADMISSION) || Object.hasOwn(attributes, BINDING)) {
+        throw new WorkflowAdmissionBindingError(runId, "reserved_attributes");
+    }
+    if (Object.values(attributes).some((value) => typeof value !== "string")) {
+        throw new WorkflowAdmissionBindingError(runId, "attributes");
+    }
+    const digest = createHash("sha256")
+        .update(canonicalJson({ version: 2, reservation, workflowId, input, attributes }))
+        .digest("hex");
+    const legacyInput = legacyWorkflowArgumentsJson(snapshot);
+    // @legacy ontology.workflow-run-legacy-encodings
+    const legacyDigest = legacyInput === undefined
+        ? undefined
+        : createHash("sha256")
+            .update(canonicalJson({ version: 1, reservation, workflowId, input: legacyInput, attributes }))
+            .digest("hex");
+    const expectedAttributes = {
+        ...attributes,
+        [ADMISSION]: options.admissionId,
+        [BINDING]: digest,
+    };
+    const verify = async (run) => {
+        const mismatch = run.runId !== runId ||
+            run.deploymentId !== reservation.deploymentId ||
+            run.workflowName !== workflowId ||
+            run.executionContext?.queueNamespace !== reservation.namespace ||
+            Object.entries(expectedAttributes).some(([key, value]) => run.attributes[key] !== value &&
+                !(key === BINDING && legacyDigest !== undefined && run.attributes[key] === legacyDigest));
+        if (mismatch) {
+            throw new WorkflowAdmissionBindingError(runId, "identity");
+        }
+        const rawKey = await world.getEncryptionKeyForRun?.(run);
+        const key = rawKey ? await importKey(rawKey) : undefined;
+        const hydrated = await hydrateWorkflowArguments(run.input, runId, key);
+        if (encodeWorkflowArguments(hydrated).data !== input.data) {
+            throw new WorkflowAdmissionBindingError(runId, "input");
+        }
+        return run;
+    };
+    const previous = await existingRun(world, runId);
+    if (previous) {
+        await verify(previous);
+        if (isTerminalWorkflowRunStatus(previous.status)) {
+            return { runId };
+        }
+    }
+    let creation;
+    const events = override(world.events, {
+        create: ((requestedId, event, parameters) => {
+            const operation = requestedId === runId && event.eventType === "run_created" && previous
+                ? Promise.reject(new EntityConflictError("workflow_admission_existing"))
+                : event.eventType === "run_created"
+                    ? world.events.create(requestedId, event, parameters)
+                    : world.events.create(requestedId, event, parameters);
+            if (requestedId === runId && event.eventType === "run_created") {
+                creation = operation.then(async () => {
+                    const persisted = await existingRun(world, runId);
+                    if (!persisted) {
+                        throw new WorkflowAdmissionBindingError(runId, "creation_unconfirmed");
+                    }
+                    return verify(persisted);
+                }, async (creationError) => {
+                    let persisted;
+                    try {
+                        persisted = await existingRun(world, runId);
+                    }
+                    catch (readError) {
+                        throw new AggregateError([creationError, readError], "workflow_admission_unconfirmed", { cause: readError });
+                    }
+                    if (!persisted) {
+                        throw creationError;
+                    }
+                    return verify(persisted);
+                });
+            }
+            return operation;
+        }),
+    });
+    const admitted = override(world, {
+        events,
+        createRunId: () => runId.slice("wrun_".length),
+        queue: async (queueName, message, queueOptions) => {
+            if ("runId" in message && message.runId === runId) {
+                if (!creation) {
+                    throw new WorkflowAdmissionBindingError(runId, "creation_unconfirmed");
+                }
+                const persisted = await creation;
+                if (isTerminalWorkflowRunStatus(persisted.status)) {
+                    return { messageId: null };
+                }
+                // A fresh runInput message enables core 5.2.2's optimistic first delivery,
+                // which can execute a step before checking existing/terminal history.
+                // Persistence was verified above: pointer-only dispatch forces history
+                // loading even when an ambiguous acknowledgement requires a new message.
+                const pointer = { ...message };
+                if ("runInput" in pointer) {
+                    delete pointer.runInput;
+                }
+                return world.queue(queueName, pointer, queueOptions);
+            }
+            return world.queue(queueName, message, queueOptions);
+        },
+    });
+    await start({ workflowId }, snapshot, {
+        world: admitted,
+        deploymentId: reservation.deploymentId,
+        namespace: reservation.namespace,
+        ...(reservation.region ? { region: reservation.region } : {}),
+        attributes: expectedAttributes,
+        allowReservedAttributes: true,
+        ...(previous?.specVersion !== undefined ? { specVersion: previous.specVersion } : {}),
+    });
+    return { runId };
+}

package/dist/service/workflow-argument-serialization.d.ts

@@ -0,0 +1,2 @@
+/** Only the server entry reaches the installed Workflow SDK's public serialization API. */
+export declare function installWorkflowArgumentCodecs(): void;

package/dist/service/workflow-argument-serialization.js

@@ -0,0 +1,14 @@
+import { getCommonRevivers, getExternalReducers } from "@workflow/core/serialization";
+import { setWorkflowArgumentCodecs } from "../runtime/workflow-argument-codec.js";
+/** Only the server entry reaches the installed Workflow SDK's public serialization API. */
+export function installWorkflowArgumentCodecs() {
+    const revivers = getCommonRevivers();
+    delete revivers.WorkflowFunction;
+    const external = getExternalReducers(globalThis, [], "", undefined);
+    // Runtime handles/functions have no common synchronous reviver. Never invoke their reducers:
+    // they can start provider I/O, and admission must reject them before its journal commits.
+    setWorkflowArgumentCodecs({
+        reducers: Object.fromEntries(Object.entries(external).filter(([name]) => Object.hasOwn(revivers, name))),
+        revivers,
+    });
+}

package/dist/service/workflow-callback.d.ts

@@ -0,0 +1,22 @@
+/** The OIDC token of the callback request whose step is running, if it carried one. */
+export declare function callbackIdentityToken(): string | undefined;
+/** The ontology service of this instance could not be started before a step. */
+export declare class WorkflowServiceUnavailable extends Error {
+    constructor(status: number, requestId: string | null);
+}
+export interface WorkflowCallbackOptions {
+    /** The handler's exact route; any other path, a trailing slash included, is refused. */
+    readonly route: string;
+    /** The topic prefix of the ontology's queue, such as `__ontology_wkf_workflow_`. */
+    readonly queuePrefix: string;
+    /** Builds this instance's ontology service when nothing has bound the runtime yet. */
+    readonly warm?: () => Promise<Response>;
+}
+/**
+ * Answers one Workflow SDK queue delivery with the SDK's flow handler, as `ontologyWorkflows()`
+ * mounts it. A request that is not a delivery of the ontology's queue to the exact route is
+ * answered 404 without reaching the SDK. Before the handler runs, `warm` builds this instance's
+ * ontology service if nothing has bound the runtime yet; a failure to start throws, so the
+ * delivery fails and the queue retries it. The request's OIDC token stays available to the steps.
+ */
+export declare function serveWorkflowCallback(request: Request, handler: (request: Request) => Promise<Response>, options: WorkflowCallbackOptions): Promise<Response>;

package/dist/service/workflow-callback.js

@@ -0,0 +1,75 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { deploymentFromEnv, DeploymentAdmissionError, requireDeploymentCapability, } from "../deployment.js";
+import { workflowBinding, workflowSdk } from "../workflow-runtime.js";
+import { OIDC_TOKEN_HEADER } from "./connections.js";
+const STORAGE = Symbol.for("@segmentstream/ontology/workflow-callback");
+/** One storage per process, whatever copies of this module a bundler makes. */
+const storage = (globalThis[STORAGE] ??= new AsyncLocalStorage());
+/** The OIDC token of the callback request whose step is running, if it carried one. */
+export function callbackIdentityToken() {
+    return storage.getStore()?.identityToken;
+}
+/**
+ * The queue a delivery came from: Vercel Queues name it in the CloudEvent header
+ * `ce-vqsqueuename`, the SDK's local world in `x-vqs-queue-name`.
+ */
+function deliveredQueue(request) {
+    return (request.headers.get("ce-vqsqueuename") ?? request.headers.get("x-vqs-queue-name") ?? undefined);
+}
+/** The ontology service of this instance could not be started before a step. */
+export class WorkflowServiceUnavailable extends Error {
+    constructor(status, requestId) {
+        super(`The ontology service did not start for a workflow step (status ${status}` +
+            `${requestId === null ? "" : `, request ${requestId}`}); the queue retries the delivery.`);
+        this.name = "WorkflowServiceUnavailable";
+    }
+}
+let warming;
+async function warmOnce(warm) {
+    warming ??= (async () => {
+        const response = await warm();
+        if (!response.ok) {
+            throw new WorkflowServiceUnavailable(response.status, response.headers.get("x-request-id"));
+        }
+    })().finally(() => {
+        warming = undefined;
+    });
+    await warming;
+}
+/**
+ * Answers one Workflow SDK queue delivery with the SDK's flow handler, as `ontologyWorkflows()`
+ * mounts it. A request that is not a delivery of the ontology's queue to the exact route is
+ * answered 404 without reaching the SDK. Before the handler runs, `warm` builds this instance's
+ * ontology service if nothing has bound the runtime yet; a failure to start throws, so the
+ * delivery fails and the queue retries it. The request's OIDC token stays available to the steps.
+ */
+export async function serveWorkflowCallback(request, handler, options) {
+    try {
+        requireDeploymentCapability(deploymentFromEnv(), "workflows");
+    }
+    catch (error) {
+        if (!(error instanceof DeploymentAdmissionError)) {
+            throw error;
+        }
+        return Response.json({ error: error.code }, { status: error.status, headers: { "cache-control": "no-store" } });
+    }
+    const queue = deliveredQueue(request);
+    if (request.method !== "POST" ||
+        new URL(request.url).pathname !== options.route ||
+        queue === undefined ||
+        !queue.startsWith(options.queuePrefix)) {
+        return new Response(null, { status: 404 });
+    }
+    if (options.warm !== undefined && workflowBinding() === undefined) {
+        await warmOnce(options.warm);
+    }
+    const prepare = workflowSdk()?.prepareCallback;
+    if (deploymentFromEnv().target === "preview" && prepare === undefined) {
+        throw new WorkflowServiceUnavailable(503, null);
+    }
+    await prepare?.();
+    // Warmup and provider reads may cross the deadline on a warm instance.
+    requireDeploymentCapability(deploymentFromEnv(), "workflows");
+    const token = request.headers.get(OIDC_TOKEN_HEADER) ?? undefined;
+    return storage.run({ identityToken: token === "" ? undefined : token }, () => handler(request));
+}

package/dist/service/workflow-deployment.d.ts

@@ -0,0 +1,8 @@
+import { type DeploymentObservation } from "../deployment.js";
+import type { WorkflowEngine, WorkflowRunRecord } from "./workflows.js";
+/** Immutable run provenance, separate from the Workflow SDK's provider deployment id. */
+export declare function workflowDeploymentAttributes(deployment: DeploymentObservation): Readonly<Record<string, string>>;
+/** Older production runs have no attributes; a preview never admits such a run. */
+export declare function workflowRunBelongsToDeployment(deployment: DeploymentObservation, run: Pick<WorkflowRunRecord, "attributes" | "deploymentId">): boolean;
+/** Fence injected engines as well as the default world, at every read and start. */
+export declare function deploymentWorkflowEngine(engine: WorkflowEngine, observe: DeploymentObservation | (() => DeploymentObservation)): WorkflowEngine;

package/dist/service/workflow-deployment.js

@@ -0,0 +1,131 @@
+import { DeploymentAdmissionError, requireDeploymentCapability, } from "../deployment.js";
+const TARGET = "segmentstream.deploymentTarget";
+const DEPLOYMENT = "segmentstream.deploymentId";
+/** The Workflow SDK's local world records every run under `dpl_local@<its version>`. */
+const LOCAL_WORLD_DEPLOYMENT = /^dpl_local@/;
+/**
+ * The physical deployment whose runs a preview admits. A hosted preview admits only its own
+ * Vercel deployment's runs. A local preview has no Vercel deployment: it must not claim one, and
+ * it admits only runs its machine's local world recorded, which the session id binds as well.
+ */
+function previewProviderDeployment(deployment) {
+    const id = process.env.VERCEL_DEPLOYMENT_ID?.trim();
+    if (deployment.host === "local") {
+        if (id) {
+            throw new DeploymentAdmissionError("preview_configuration_invalid");
+        }
+        return LOCAL_WORLD_DEPLOYMENT;
+    }
+    if (!id) {
+        throw new DeploymentAdmissionError("preview_configuration_invalid");
+    }
+    return id;
+}
+/** Immutable run provenance, separate from the Workflow SDK's provider deployment id. */
+export function workflowDeploymentAttributes(deployment) {
+    if (deployment.target === "production") {
+        return {};
+    }
+    return {
+        [TARGET]: deployment.target,
+        ...(deployment.deploymentId ? { [DEPLOYMENT]: deployment.deploymentId } : {}),
+    };
+}
+/** Older production runs have no attributes; a preview never admits such a run. */
+export function workflowRunBelongsToDeployment(deployment, run) {
+    requireDeploymentCapability(deployment, "workflows");
+    if (deployment.target === "production") {
+        return run.attributes?.[TARGET] !== "preview";
+    }
+    const providerDeployment = previewProviderDeployment(deployment);
+    return (run.attributes?.[TARGET] === "preview" &&
+        run.attributes[DEPLOYMENT] === deployment.deploymentId &&
+        (typeof providerDeployment === "string"
+            ? run.deploymentId === providerDeployment
+            : providerDeployment.test(run.deploymentId ?? "")));
+}
+/** Fence injected engines as well as the default world, at every read and start. */
+export function deploymentWorkflowEngine(engine, observe) {
+    const observation = () => (typeof observe === "function" ? observe() : observe);
+    const getRun = async (runId) => {
+        const deployment = observation();
+        requireDeploymentCapability(deployment, "workflows");
+        if (deployment.target === "preview") {
+            previewProviderDeployment(deployment);
+        }
+        const run = await engine.getRun(runId);
+        return run && workflowRunBelongsToDeployment(deployment, run) ? run : undefined;
+    };
+    const requireRun = async (runId) => {
+        const run = await getRun(runId);
+        if (!run) {
+            throw Object.assign(new Error("WorkflowRunNotFound"), { status: 404 });
+        }
+        return run;
+    };
+    return {
+        start: async (workflow, args, options) => {
+            const deployment = observation();
+            requireDeploymentCapability(deployment, "workflows");
+            if (deployment.target === "preview") {
+                previewProviderDeployment(deployment);
+            }
+            return engine.start(workflow, args, deployment.target === "production"
+                ? options
+                : {
+                    ...options,
+                    attributes: { ...options?.attributes, ...workflowDeploymentAttributes(deployment) },
+                });
+        },
+        ...(engine.allocateRun ? { allocateRun: engine.allocateRun } : {}),
+        getRun,
+        listRuns: async (input) => {
+            const deployment = observation();
+            requireDeploymentCapability(deployment, "workflows");
+            if (deployment.target === "preview") {
+                previewProviderDeployment(deployment);
+            }
+            const page = await engine.listRuns(input);
+            return {
+                ...page,
+                data: page.data.filter((run) => workflowRunBelongsToDeployment(deployment, run)),
+            };
+        },
+        listSteps: async (runId, options) => {
+            await requireRun(runId);
+            return engine.listSteps(runId, options);
+        },
+        ...(engine.diagnostics
+            ? {
+                diagnostics: async (run, steps) => engine.diagnostics(await requireRun(run.runId), steps),
+            }
+            : {}),
+        ...(engine.getHookRunId
+            ? {
+                getHookRunId: async (token) => {
+                    requireDeploymentCapability(observation(), "workflows");
+                    const runId = await engine.getHookRunId(token);
+                    return runId && (await getRun(runId)) ? runId : undefined;
+                },
+            }
+            : {}),
+        ...(engine.resumeHook
+            ? {
+                resumeHook: async (token, payload) => {
+                    const deployment = observation();
+                    requireDeploymentCapability(deployment, "workflows");
+                    if (deployment.target === "preview" && !engine.getHookRunId) {
+                        throw new DeploymentAdmissionError("preview_configuration_invalid");
+                    }
+                    if (engine.getHookRunId) {
+                        const runId = await engine.getHookRunId(token);
+                        if (!runId || !(await getRun(runId))) {
+                            return "not_found";
+                        }
+                    }
+                    return engine.resumeHook(token, payload);
+                },
+            }
+            : {}),
+    };
+}

package/dist/service/workflow-diagnostics.d.ts

@@ -0,0 +1,23 @@
+import type { WorkflowSdk } from "../workflow-runtime.js";
+import type { WorkflowDiagnostics, WorkflowPage, WorkflowRunRecord, WorkflowStepRecord, WorldLike } from "./workflows.js";
+/** The largest page accepted by the Vercel world. */
+export declare const WORLD_PAGE_SIZE = 100;
+export declare const MAX_LISTED_WORKFLOW_EVENTS = 10000;
+type HydrateError = NonNullable<WorkflowSdk["hydrateError"]>;
+/** Current errors are bytes; spec-version 1 stored flattened devalue arrays. */
+export declare function isSerializedWorkflowError(value: unknown): boolean;
+/** Lazy world-vercel errorRef descriptors are opaque, never public error objects. */
+export declare function hasWorkflowError(value: unknown): boolean;
+/** Resolve only an error, retaining readable metadata when decryption/provider access fails. */
+export declare function hydrateWorkflowError(value: unknown, run: {
+    readonly runId: string;
+    readonly deploymentId?: string;
+}, kind: "run" | "step", hydrate: HydrateError): Promise<unknown>;
+export declare function hydrateWorkflowStepPage(world: WorldLike, runId: string, page: WorkflowPage<WorkflowStepRecord>, hydrate: HydrateError): Promise<WorkflowPage<WorkflowStepRecord>>;
+/**
+ * Events are the attempt source of truth. Lazy references are resolved by reading ONLY failure
+ * events with resolveData:all: run_created/step_created/completed payloads are never hydrated.
+ * Each scan keeps partial results when a later page or individual error cannot be read.
+ */
+export declare function readWorkflowDiagnostics(world: WorldLike, run: WorkflowRunRecord, steps: ReadonlyArray<WorkflowStepRecord> | undefined, hydrate: HydrateError): Promise<WorkflowDiagnostics>;
+export {};