@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/workflow-diagnostics.js

@@ -0,0 +1,263 @@
+import { captureRuntimeFailure } from "../internal/diagnostics.js";
+/** The largest page accepted by the Vercel world. */
+export const WORLD_PAGE_SIZE = 100;
+export const MAX_LISTED_WORKFLOW_EVENTS = 10_000;
+// Correlation queries may return empty filtered pages. Bound reads as well as returned events.
+const MAX_DIAGNOSTIC_PAGES = Math.ceil(MAX_LISTED_WORKFLOW_EVENTS / WORLD_PAGE_SIZE) + WORLD_PAGE_SIZE + 1;
+function record(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : undefined;
+}
+/** Current errors are bytes; spec-version 1 stored flattened devalue arrays. */
+export function isSerializedWorkflowError(value) {
+    return value instanceof Uint8Array || Array.isArray(value);
+}
+/** Lazy world-vercel errorRef descriptors are opaque, never public error objects. */
+export function hasWorkflowError(value) {
+    const item = record(value);
+    return (!isSerializedWorkflowError(value) &&
+        item !== undefined &&
+        item.code !== "workflow_error_unavailable" &&
+        (typeof item.name === "string" ||
+            typeof item._tag === "string" ||
+            typeof item.code === "string"));
+}
+function unavailable(reference) {
+    return {
+        code: "workflow_error_unavailable",
+        ...(reference === undefined ? {} : { reference }),
+    };
+}
+function report(error, runId, operation) {
+    return captureRuntimeFailure(error, {
+        service: "ontology",
+        boundary: "ontology.workflow.diagnostics.failed",
+        workflowRunId: runId,
+        operation,
+    }).errorId;
+}
+/** Resolve only an error, retaining readable metadata when decryption/provider access fails. */
+export async function hydrateWorkflowError(value, run, kind, hydrate) {
+    if (value === undefined || value === null || hasWorkflowError(value)) {
+        return value;
+    }
+    if (!isSerializedWorkflowError(value)) {
+        return unavailable();
+    }
+    try {
+        // @legacy ontology.workflow-run-legacy-encodings
+        // Numeric JSON byte arrays are distinct from legacy flattened devalue arrays.
+        const bytes = Array.isArray(value) &&
+            value.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255) &&
+            ["devl", "encr", "gzip", "zstd"].includes(String.fromCharCode(...value.slice(0, 4)))
+            ? new Uint8Array(value)
+            : value;
+        const result = await hydrate(bytes, run, kind);
+        return hasWorkflowError(result) ? result : unavailable();
+    }
+    catch (error) {
+        return unavailable(report(error, run.runId, `hydrate_${kind}_error`));
+    }
+}
+export async function hydrateWorkflowStepPage(world, runId, page, hydrate) {
+    let run = { runId };
+    if (page.data.some((step) => isSerializedWorkflowError(step.error))) {
+        try {
+            run = await world.runs.get(runId, { resolveData: "none" });
+        }
+        catch (cause) {
+            const reference = report(cause, runId, "read_error_encryption_context");
+            // Without the creating deployment, a runtime could derive the current deployment's key.
+            // Keep every step's status and any already-readable error, and leave encrypted data alone.
+            return {
+                ...page,
+                data: page.data.map((step) => ({
+                    ...step,
+                    error: hasWorkflowError(step.error)
+                        ? step.error
+                        : step.error == null
+                            ? step.error
+                            : unavailable(reference),
+                })),
+            };
+        }
+    }
+    return {
+        ...page,
+        data: await Promise.all(page.data.map(async (step) => ({
+            ...step,
+            error: await hydrateWorkflowError(step.error, run, "step", hydrate),
+        }))),
+    };
+}
+/**
+ * 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 async function readWorkflowDiagnostics(world, run, steps, hydrate) {
+    const attempts = new Map();
+    let error = await hydrateWorkflowError(run.error, run, "run", hydrate);
+    let truncated = false;
+    let count = 0;
+    let pages = 0;
+    const events = world.events;
+    if (events === undefined) {
+        return {
+            error: error ?? (run.status === "failed" ? unavailable() : error),
+            attempts,
+            truncated: true,
+        };
+    }
+    const failure = async (event, kind) => {
+        try {
+            // In lazy mode error can be a descriptor (or absent in world-local). Read the failure event
+            // through the provider, rather than guessing ref URLs or resolving a run's entire I/O.
+            const stored = event.eventData?.error;
+            const value = isSerializedWorkflowError(stored) || hasWorkflowError(stored)
+                ? stored
+                : (await events.get(run.runId, event.eventId, { resolveData: "all" })).eventData?.error;
+            const result = await hydrateWorkflowError(value, run, kind, hydrate);
+            if (!hasWorkflowError(result)) {
+                truncated = true;
+            }
+            return result ?? unavailable();
+        }
+        catch (cause) {
+            truncated = true;
+            return unavailable(report(cause, run.runId, `read_${kind}_failure`));
+        }
+    };
+    const consume = async (event) => {
+        // Correlation IDs belong to a run. Defend against providers that ignore runId filtering.
+        if (event.runId !== undefined && event.runId !== run.runId) {
+            return;
+        }
+        if (event.eventType === "run_failed" && !hasWorkflowError(error)) {
+            const resolved = await failure(event, "run");
+            if (hasWorkflowError(resolved) || !hasWorkflowError(error)) {
+                error = resolved;
+            }
+        }
+        const stepId = event.correlationId;
+        if (!stepId ||
+            !event.eventType.startsWith("step_") ||
+            (steps !== undefined && !steps.some((step) => step.stepId === stepId))) {
+            return;
+        }
+        if (event.eventType === "step_created") {
+            return;
+        }
+        const history = attempts.get(stepId) ?? [];
+        const explicit = event.eventData?.attempt;
+        const number = typeof explicit === "number" && Number.isInteger(explicit) && explicit > 0
+            ? explicit
+            : undefined;
+        attempts.set(stepId, history);
+        if (event.eventType === "step_started") {
+            history.push({
+                attempt: number ?? (history.at(-1)?.attempt ?? 0) + 1,
+                status: "running",
+                startedAt: event.createdAt,
+            });
+        }
+        else if (["step_failed", "step_retrying", "step_completed"].includes(event.eventType)) {
+            const last = history.at(-1);
+            if (last === undefined) {
+                truncated = true;
+            }
+            history[history.length === 0 ? 0 : history.length - 1] = {
+                ...(last ?? {
+                    attempt: number ?? steps?.find((step) => step.stepId === stepId)?.attempt ?? 1,
+                }),
+                status: event.eventType === "step_completed" ? "completed" : "failed",
+                completedAt: event.createdAt,
+                ...(event.eventType === "step_completed" ? {} : { error: await failure(event, "step") }),
+            };
+        }
+    };
+    const scan = async (list, onlyRunFailure = false) => {
+        let cursor;
+        const seen = new Set();
+        try {
+            while (count < MAX_LISTED_WORKFLOW_EVENTS && pages < MAX_DIAGNOSTIC_PAGES) {
+                pages++;
+                const page = await list(cursor);
+                for (const event of page.data) {
+                    if (count >= MAX_LISTED_WORKFLOW_EVENTS) {
+                        truncated = true;
+                        return;
+                    }
+                    count++;
+                    if (!onlyRunFailure || event.eventType === "run_failed") {
+                        await consume(event);
+                    }
+                    if (onlyRunFailure && event.eventType === "run_failed") {
+                        return;
+                    }
+                }
+                if (!page.hasMore) {
+                    return;
+                }
+                if (page.cursor === null || seen.has(page.cursor)) {
+                    truncated = true;
+                    return;
+                }
+                seen.add(page.cursor);
+                cursor = page.cursor;
+            }
+            truncated = true;
+        }
+        catch (cause) {
+            truncated = true;
+            report(cause, run.runId, "list_events");
+        }
+    };
+    // Retrieve the primary failure before a large attempt history can consume the read budget.
+    // Failed-run events are at the end of the log; this scan never reads step payloads.
+    if (run.status === "failed" && !hasWorkflowError(error)) {
+        await scan((cursor) => events.list({
+            runId: run.runId,
+            resolveData: "none",
+            pagination: {
+                limit: WORLD_PAGE_SIZE,
+                sortOrder: "desc",
+                ...(cursor ? { cursor } : {}),
+            },
+        }), true);
+    }
+    if (steps !== undefined && events.listByCorrelationId !== undefined) {
+        for (let offset = 0; offset < steps.length; offset += 8) {
+            await Promise.all(steps.slice(offset, offset + 8).map((step) => scan((cursor) => events.listByCorrelationId({
+                runId: run.runId,
+                correlationId: step.stepId,
+                resolveData: "none",
+                pagination: {
+                    limit: WORLD_PAGE_SIZE,
+                    sortOrder: "asc",
+                    ...(cursor ? { cursor } : {}),
+                },
+            }))));
+        }
+    }
+    else {
+        await scan((cursor) => events.list({
+            runId: run.runId,
+            resolveData: "none",
+            pagination: { limit: WORLD_PAGE_SIZE, sortOrder: "asc", ...(cursor ? { cursor } : {}) },
+        }));
+    }
+    for (const step of steps ?? []) {
+        const history = attempts.get(step.stepId);
+        if ((step.attempt ?? 0) > (history?.length ?? 0) ||
+            (step.status === "failed" && history?.at(-1)?.status !== "failed")) {
+            truncated = true;
+        }
+    }
+    if (run.status === "failed" && !hasWorkflowError(error)) {
+        truncated = true;
+        error ??= unavailable();
+    }
+    return { error, attempts, truncated };
+}

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

@@ -0,0 +1,26 @@
+import { Cause } from "effect";
+import type { WorkflowStepContext } from "../workflow-runtime.js";
+/** Public diagnostics contain declared safe messages, never the operator report or inputs. */
+export interface WorkflowErrorView {
+    readonly tag: string | null;
+    readonly message: string | null;
+    readonly code: string | null;
+    readonly reason?: string;
+    readonly requestId?: string;
+    readonly reference?: string;
+    readonly category?: "deployment_switching" | "deployment_interrupted";
+    readonly servedHash?: string;
+    readonly appliedHash?: string;
+    readonly servedDeploymentId?: string;
+    readonly appliedDeploymentId?: string;
+    readonly generation?: string;
+}
+/** The SDK preserves Error.cause; custom Error properties are otherwise discarded. */
+export declare class WorkflowStepFailed extends Error {
+    readonly fatal: boolean;
+    readonly retryAfter?: Date;
+    constructor(name: string, message: string, fatal?: boolean, cause?: unknown, retryAfter?: Date);
+}
+export declare function stepFailure(cause: Cause.Cause<unknown>, requestId: string, step: WorkflowStepContext, workflow: string, credentials: readonly (string | undefined)[]): WorkflowStepFailed;
+/** Find our envelope through retry-exhaustion/run wrappers, with bounded cycle-safe traversal. */
+export declare function workflowErrorView(value: unknown): WorkflowErrorView | null;

package/dist/service/workflow-errors.js

@@ -0,0 +1,181 @@
+import { Cause } from "effect";
+import { captureRuntimeFailure, environmentSecrets, makeRedactor, } from "../internal/diagnostics.js";
+const SAFE_FAILURES = new Set([
+    "TriggerInputInvalid",
+    "WorkflowRecoveryUnavailable",
+    "ActionRejected",
+    "PermissionDenied",
+    "ScopeViolated",
+    "Conflict",
+    "NotFound",
+    "ConnectionError",
+    "InvalidActionInput",
+    "AgentTaskUnanswered",
+    "AgentTaskRefused",
+]);
+const DEPLOYMENT_FAILURES = new Set(["DeploymentSwitching", "DeploymentInterrupted"]);
+const DETERMINISTIC_FAILURES = new Set([
+    "TriggerInputInvalid",
+    "PermissionDenied",
+    "ScopeViolated",
+    "ActionRejected",
+    "InvalidActionInput",
+    "AgentTaskRefused",
+    "DeploymentInterrupted",
+]);
+const TAG = /^[A-Za-z][A-Za-z0-9_]{0,99}$/;
+const ID = /^[A-Za-z0-9_.:-]{1,200}$/;
+function record(value) {
+    return value !== null && typeof value === "object"
+        ? value
+        : undefined;
+}
+/** The SDK preserves Error.cause; custom Error properties are otherwise discarded. */
+export class WorkflowStepFailed extends Error {
+    fatal;
+    retryAfter;
+    constructor(name, message, fatal = false, cause, retryAfter) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = name;
+        this.fatal = fatal;
+        if (retryAfter !== undefined) {
+            // The pinned Workflow SDK's RetryableError.is guard recognizes this name and Date field.
+            this.name = "RetryableError";
+            this.retryAfter = retryAfter;
+        }
+    }
+}
+export function stepFailure(cause, requestId, step, workflow, credentials) {
+    const failure = record(Cause.squash(cause));
+    const tag = typeof failure?._tag === "string" && TAG.test(failure._tag)
+        ? failure._tag
+        : "WorkflowStepFailed";
+    const redact = makeRedactor([...environmentSecrets(process.env), ...credentials]);
+    const report = captureRuntimeFailure(cause, {
+        service: "ontology",
+        boundary: "ontology.workflow.step.failed",
+        requestId,
+        workflowRunId: step.workflowRunId,
+        stepId: step.stepId,
+        stepAttempt: step.attempt,
+        workflow,
+    }, process.env, credentials);
+    const publicMessage = SAFE_FAILURES.has(tag) || tag === "SchemaError"
+        ? report.nodes.find((node) => node.type === tag)?.message
+        : undefined;
+    const error = {
+        tag,
+        code: tag,
+        message: publicMessage === undefined ? null : redact(publicMessage),
+        reference: requestId,
+        ...deploymentFields(tag, failure),
+        ...(tag === "ConnectionError" && typeof failure?.reason === "string" && TAG.test(failure.reason)
+            ? { reason: failure.reason }
+            : {}),
+        ...(tag === "ConnectionError" &&
+            typeof failure?.requestId === "string" &&
+            ID.test(failure.requestId)
+            ? { requestId: failure.requestId }
+            : {}),
+    };
+    const switching = tag === "DeploymentSwitching";
+    const delay = typeof failure?.retryAfter === "number" && Number.isFinite(failure.retryAfter)
+        ? Math.max(1, failure.retryAfter)
+        : 5;
+    return new WorkflowStepFailed(tag, error.message ?? tag, DETERMINISTIC_FAILURES.has(tag), { _tag: "OntologyWorkflowFailure", version: 2, error, report }, switching
+        ? new Date(Date.now() +
+            Math.min(60, delay * 2 ** Math.min(Math.max(step.attempt - 1, 0), 6)) * 1_000)
+        : undefined);
+}
+/** Deployment provenance is identifiers only; the operator journal retains the complete cause. */
+function deploymentFields(tag, item) {
+    if (tag !== "DeploymentInterrupted" && tag !== "DeploymentSwitching") {
+        return {};
+    }
+    const fields = {
+        category: tag === "DeploymentInterrupted" ? "deployment_interrupted" : "deployment_switching",
+    };
+    for (const field of [
+        "servedHash",
+        "appliedHash",
+        "servedDeploymentId",
+        "appliedDeploymentId",
+        "generation",
+    ]) {
+        const value = item?.[field];
+        if (typeof value === "string" && ID.test(value)) {
+            fields[field] = value;
+        }
+    }
+    return fields;
+}
+function publicError(item, tag) {
+    const redact = makeRedactor(environmentSecrets(process.env));
+    const code = typeof item.code === "string" && ID.test(item.code) ? item.code : tag;
+    const legacyMismatch = tag === "PermissionDenied" &&
+        (item.updating === true ||
+            item.message === "The deployed ontology no longer matches the database catalog.");
+    return {
+        tag,
+        code: code ?? "workflow_error_unavailable",
+        message: tag !== null &&
+            (SAFE_FAILURES.has(tag) || tag === "SchemaError") &&
+            typeof item.message === "string"
+            ? redact(item.message)
+            : null,
+        ...(typeof item.reason === "string" && TAG.test(item.reason) ? { reason: item.reason } : {}),
+        ...(typeof item.requestId === "string" && ID.test(item.requestId)
+            ? { requestId: item.requestId }
+            : {}),
+        ...(typeof item.reference === "string" && ID.test(item.reference)
+            ? { reference: item.reference }
+            : {}),
+        ...deploymentFields(tag, item),
+        // @legacy ontology.workflow-run-legacy-encodings
+        // Old deployments stored this persistent mismatch as a fatal permission error. Preserve its
+        // original tag/code and explain the interruption; reading history must never retry the run.
+        ...(legacyMismatch
+            ? { category: "deployment_interrupted", reason: "legacy_catalog_mismatch" }
+            : {}),
+    };
+}
+/** Find our envelope through retry-exhaustion/run wrappers, with bounded cycle-safe traversal. */
+export function workflowErrorView(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const seen = new Set();
+    const pending = [value];
+    let legacy;
+    while (pending.length > 0 && seen.size < 64) {
+        const current = pending.shift();
+        if (current === undefined || seen.has(current)) {
+            continue;
+        }
+        seen.add(current);
+        const item = record(current);
+        const name = item?._tag ?? item?.name;
+        if (!legacy &&
+            typeof name === "string" &&
+            (SAFE_FAILURES.has(name) || DEPLOYMENT_FAILURES.has(name))) {
+            legacy = item;
+        }
+        if (item?._tag === "OntologyWorkflowFailure" && (item.version === 1 || item.version === 2)) {
+            const error = record(item.error);
+            if (error) {
+                const tag = typeof error.tag === "string" && TAG.test(error.tag) ? error.tag : null;
+                return publicError(error, tag);
+            }
+        }
+        pending.push(item?.cause, item?.error);
+        if (Array.isArray(item?.errors)) {
+            pending.push(...item.errors.slice(0, 64 - seen.size));
+        }
+    }
+    // @legacy ontology.workflow-run-legacy-encodings
+    // Older deployments stored safe tagged errors without the structured envelope.
+    const item = legacy ?? record(value);
+    const name = item?._tag ?? item?.name;
+    const tag = typeof name === "string" && TAG.test(name) ? name : null;
+    return publicError(item ?? {}, tag);
+}

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

@@ -0,0 +1,2 @@
+/** Only active Workflow steps receive correlation. Operator reports retain their own framing. */
+export declare function installWorkflowLogging(): void;

package/dist/service/workflow-logging.js

@@ -0,0 +1,50 @@
+import { formatWithOptions } from "node:util";
+import { environmentSecrets, makeRedactor } from "../internal/diagnostics.js";
+import { currentWorkflowStep } from "../workflow-runtime.js";
+import { callbackIdentityToken } from "./workflow-callback.js";
+const INSTALLED = Symbol.for("@segmentstream/ontology/workflow-logging");
+function runtimeEvent(value) {
+    if (typeof value !== "string") {
+        return false;
+    }
+    const start = value.indexOf("{");
+    if (start < 0) {
+        return false;
+    }
+    try {
+        const event = JSON.parse(value.slice(start))?.event;
+        return (typeof event === "string" &&
+            (event.startsWith("diagnostics.") || event.startsWith("ontology.workflow.")));
+    }
+    catch {
+        // diagnostics-recovery: Ordinary console text is not a structured runtime event.
+        return false;
+    }
+}
+/** Only active Workflow steps receive correlation. Operator reports retain their own framing. */
+export function installWorkflowLogging() {
+    const globals = globalThis;
+    if (globals[INSTALLED]) {
+        return;
+    }
+    globals[INSTALLED] = true;
+    for (const method of ["log", "info", "warn", "error", "debug"]) {
+        const write = console[method].bind(console);
+        console[method] = (...args) => {
+            const step = currentWorkflowStep();
+            if (!step || runtimeEvent(args[0])) {
+                write(...args);
+                return;
+            }
+            const redact = makeRedactor([...environmentSecrets(process.env), callbackIdentityToken()]);
+            write(JSON.stringify({
+                event: "ontology.workflow.console",
+                workflowRunId: step.workflowRunId,
+                stepId: step.stepId,
+                attempt: step.attempt,
+                level: method === "warn" ? "warning" : method === "log" ? "info" : method,
+                message: redact(formatWithOptions({ depth: 6 }, ...args)),
+            }));
+        };
+    }
+}

package/dist/service/workflow-queue-fence.d.ts

@@ -0,0 +1,6 @@
+import type { World } from "@workflow/world";
+/**
+ * Guard authenticated, decoded deliveries. The world's handler retains signature validation,
+ * CBOR/JSON decoding, acknowledgements and retries. Production keeps the SDK's existing path.
+ */
+export declare function fenceWorkflowQueue(world: World): World;

package/dist/service/workflow-queue-fence.js

@@ -0,0 +1,66 @@
+import { deploymentFromEnv, requireDeploymentCapability } from "../deployment.js";
+import { workflowBinding } from "../workflow-runtime.js";
+import { ONTOLOGY_QUEUE_PREFIX } from "../workflow-topics.js";
+import { workflowRunBelongsToDeployment } from "./workflow-deployment.js";
+/**
+ * Guard authenticated, decoded deliveries. The world's handler retains signature validation,
+ * CBOR/JSON decoding, acknowledgements and retries. Production keeps the SDK's existing path.
+ */
+export function fenceWorkflowQueue(world) {
+    return {
+        ...world,
+        createQueueHandler: (prefix, handler) => world.createQueueHandler(prefix, async (payload, metadata) => {
+            const deployment = deploymentFromEnv();
+            if (deployment.target === "preview" &&
+                metadata.queueName.startsWith(ONTOLOGY_QUEUE_PREFIX)) {
+                requireDeploymentCapability(deployment, "workflows");
+                const message = payload;
+                const runId = message?.runId;
+                if (typeof runId !== "string") {
+                    // Health checks carry no run and must never invoke workspace code in a preview.
+                    return;
+                }
+                const workflowName = metadata.queueName.slice(ONTOLOGY_QUEUE_PREFIX.length);
+                const admit = workflowBinding()?.admitWorkflow;
+                if (!admit) {
+                    throw new Error("WorkflowDeploymentAdmissionUnavailable");
+                }
+                admit(workflowName);
+                const validate = (run) => {
+                    if (run.workflowName !== workflowName ||
+                        !workflowRunBelongsToDeployment(deployment, run) ||
+                        (run.environment !== undefined && run.environment !== "preview") ||
+                        run.dynamicWorkflowCode !== undefined ||
+                        run.dynamicWorkflowCodeRef !== undefined) {
+                        throw new Error("WorkflowDeploymentMismatch");
+                    }
+                };
+                // A first delivery may execute directly from this seed (including SDK turbo starts).
+                // Validate it even when a persisted run also exists; neither can override the other.
+                if (message.runInput) {
+                    validate(message.runInput);
+                }
+                let recorded;
+                try {
+                    recorded = await world.runs.get(runId, { resolveData: "none" });
+                }
+                catch (error) {
+                    const failure = error;
+                    if (failure?.name !== "WorkflowRunNotFoundError" && failure?.status !== 404) {
+                        throw error;
+                    }
+                }
+                if (recorded) {
+                    validate(recorded);
+                }
+                else if (!message.runInput) {
+                    throw new Error("WorkflowRunUnknown");
+                }
+                // A missing record with a verified seed is the SDK's resilient-start path. Its handler
+                // validates the full payload and creates the run; this guard never writes run state.
+                requireDeploymentCapability(deployment, "workflows");
+            }
+            return handler(payload, metadata);
+        }),
+    };
+}