@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/workflow-argument-codec.js

@@ -0,0 +1,120 @@
+const CODECS = Symbol.for("@segmentstream/ontology/workflow-argument-codecs");
+const globals = globalThis;
+/** Server setup supplies the installed SDK's codecs; all bundled copies share the first one. */
+export function setWorkflowArgumentCodecs(codecs) {
+    globals[CODECS] ??= codecs;
+}
+const views = {
+    BigInt64Array,
+    BigUint64Array,
+    Float32Array,
+    Float64Array,
+    Int8Array,
+    Int16Array,
+    Int32Array,
+    Uint8Array,
+    Uint8ClampedArray,
+    Uint16Array,
+    Uint32Array,
+};
+const prototypes = new Set([
+    Object,
+    Array,
+    ArrayBuffer,
+    Date,
+    DataView,
+    Map,
+    Set,
+    RegExp,
+    URL,
+    URLSearchParams,
+    Headers,
+    ...Object.values(views),
+].map((ctor) => ctor.prototype));
+function getter(prototype, key) {
+    const read = Object.getOwnPropertyDescriptor(prototype, key).get;
+    return (value) => read.call(value);
+}
+// Read native internal slots, like the provider, rather than overridable instance properties.
+const viewReaders = [DataView.prototype, Object.getPrototypeOf(Uint8Array.prototype)].map((prototype) => ({
+    buffer: getter(prototype, "buffer"),
+    byteOffset: getter(prototype, "byteOffset"),
+    byteLength: getter(prototype, "byteLength"),
+}));
+const mapEntries = Map.prototype.entries;
+const setValues = Set.prototype.values;
+const headersForEach = Headers.prototype.forEach;
+const dateTime = Date.prototype.getTime;
+const dateIso = Date.prototype.toISOString;
+const regExpSource = getter(RegExp.prototype, "source");
+const regExpFlags = getter(RegExp.prototype, "flags");
+const urlHref = getter(URL.prototype, "href");
+const paramsToString = URLSearchParams.prototype.toString;
+function bytes(value) {
+    const reader = viewReaders[value instanceof DataView ? 0 : 1];
+    const view = value instanceof ArrayBuffer
+        ? new Uint8Array(value)
+        : new Uint8Array(reader.buffer(value), reader.byteOffset(value), reader.byteLength(value));
+    return view.byteLength === 0 ? "." : Buffer.from(view).toString("base64");
+}
+function buffer(value) {
+    return Uint8Array.from(Buffer.from(value === "." ? "" : value, "base64")).buffer;
+}
+// Standalone runtimes may inject a WorkflowStarter without installing a provider. This is the
+// native subset of the version-1 wire format, NOT devalue's different built-in Map/Set/byte format.
+// Unsupported prototypes (including custom serde classes) require the server-installed codecs.
+// Compatibility with the installed public serialization API is checked by the codec tests.
+const nativeCodecs = {
+    reducers: {
+        Unsupported: (value) => {
+            if (value !== null && typeof value === "object") {
+                const prototype = Object.getPrototypeOf(value);
+                if (prototype !== null && !prototypes.has(prototype)) {
+                    throw new TypeError("workflow_arguments_provider_codec_required");
+                }
+            }
+            return false;
+        },
+        ArrayBuffer: (value) => value instanceof ArrayBuffer && bytes(value),
+        BigInt: (value) => typeof value === "bigint" && String(value),
+        ...Object.fromEntries(Object.entries(views).map(([name, ctor]) => [
+            name,
+            (value) => value instanceof ctor && bytes(value),
+        ])),
+        DataViewBytes: (value) => value instanceof DataView && bytes(value),
+        Date: (value) => value instanceof Date && (Number.isNaN(dateTime.call(value)) ? "." : dateIso.call(value)),
+        Headers: (value) => {
+            if (!(value instanceof Headers)) {
+                return false;
+            }
+            const entries = [];
+            headersForEach.call(value, (entry, key) => entries.push([key, entry]));
+            return entries;
+        },
+        Map: (value) => value instanceof Map && Array.from(mapEntries.call(value)),
+        RegExp: (value) => value instanceof RegExp && { source: regExpSource(value), flags: regExpFlags(value) },
+        Set: (value) => value instanceof Set && Array.from(setValues.call(value)),
+        URL: (value) => value instanceof URL && urlHref(value),
+        URLSearchParams: (value) => value instanceof URLSearchParams && (paramsToString.call(value) || "."),
+    },
+    revivers: {
+        ArrayBuffer: buffer,
+        BigInt: (value) => BigInt(value),
+        ...Object.fromEntries(Object.entries(views).map(([name, ctor]) => [
+            name,
+            (value) => new ctor(buffer(value)),
+        ])),
+        DataViewBytes: (value) => new DataView(buffer(value)),
+        Date: (value) => new Date(value),
+        Headers: (value) => new Headers(value),
+        Map: (value) => new Map(value),
+        RegExp: (value) => new RegExp(value.source, value.flags),
+        Set: (value) => new Set(value),
+        URL: (value) => new URL(value),
+        URLSearchParams: (value) => new URLSearchParams(value === "." ? "" : value),
+    },
+};
+/** Resolves locally, without loading the Workflow SDK or consulting a provider. */
+export function workflowArgumentCodecs() {
+    return globals[CODECS] ?? nativeCodecs;
+}

package/dist/runtime/workflow-arguments.d.ts

@@ -0,0 +1,17 @@
+/** JSONB stores this object; historical rows stored the argument array directly. */
+export interface StoredWorkflowArguments {
+    readonly codec: "segmentstream.workflow-arguments";
+    readonly version: 1;
+    readonly data: string;
+}
+export declare class WorkflowArgumentsError extends TypeError {
+    readonly code: "workflow_arguments_unsupported" | "workflow_arguments_invalid_encoding";
+    readonly name = "WorkflowArgumentsError";
+    constructor(code: "workflow_arguments_unsupported" | "workflow_arguments_invalid_encoding", cause?: unknown);
+}
+/** Deterministic, type-sensitive graph encoding; no provider access or JSON coercion. */
+export declare function encodeWorkflowArguments(args: ReadonlyArray<unknown>): StoredWorkflowArguments;
+/** Read the persisted winner without consulting a newer workflow declaration. */
+export declare function decodeWorkflowArguments(stored: unknown): unknown[];
+/** Only lossless JSON trees may match the previous provider binding format. */
+export declare function legacyWorkflowArgumentsJson(args: ReadonlyArray<unknown>): string | undefined;

package/dist/runtime/workflow-arguments.js

@@ -0,0 +1,99 @@
+import { defaultStringifyOperations, parse, stringify } from "devalue";
+import { workflowArgumentCodecs } from "./workflow-argument-codec.js";
+export class WorkflowArgumentsError extends TypeError {
+    code;
+    name = "WorkflowArgumentsError";
+    constructor(code, cause) {
+        super(code, { cause });
+        this.code = code;
+    }
+}
+const options = {
+    operations: {
+        shapeOf(value) {
+            const shape = defaultStringifyOperations.shapeOf(value);
+            return "keys" in shape ? { ...shape, keys: shape.keys.sort() } : shape;
+        },
+    },
+};
+/** Deterministic, type-sensitive graph encoding; no provider access or JSON coercion. */
+export function encodeWorkflowArguments(args) {
+    try {
+        if (!Array.isArray(args)) {
+            throw new TypeError("workflow_arguments_array_required");
+        }
+        const { reducers, revivers } = workflowArgumentCodecs();
+        const data = stringify(args, reducers, options);
+        // Reject values the installed runtime cannot hydrate before journal commit
+        // (for example a custom-reviver cycle or an unregistered serde class).
+        if (stringify(parse(data, revivers), reducers, options) !== data) {
+            throw new TypeError("workflow_arguments_unstable_codec");
+        }
+        return { codec: "segmentstream.workflow-arguments", version: 1, data };
+    }
+    catch (cause) {
+        throw new WorkflowArgumentsError("workflow_arguments_unsupported", cause);
+    }
+}
+/** Read the persisted winner without consulting a newer workflow declaration. */
+export function decodeWorkflowArguments(stored) {
+    try {
+        // @legacy ontology.workflow-run-legacy-encodings
+        if (Array.isArray(stored)) {
+            return stored;
+        }
+        if (stored === null ||
+            typeof stored !== "object" ||
+            !("codec" in stored) ||
+            stored.codec !== "segmentstream.workflow-arguments" ||
+            !("version" in stored) ||
+            stored.version !== 1 ||
+            !("data" in stored) ||
+            typeof stored.data !== "string") {
+            throw new TypeError("workflow_arguments_envelope_required");
+        }
+        const { reducers, revivers } = workflowArgumentCodecs();
+        const args = parse(stored.data, revivers);
+        if (!Array.isArray(args)) {
+            throw new TypeError("workflow_arguments_array_required");
+        }
+        if (stringify(args, reducers, options) !== stored.data) {
+            throw new TypeError("workflow_arguments_codec_changed");
+        }
+        return args;
+    }
+    catch (cause) {
+        throw new WorkflowArgumentsError("workflow_arguments_invalid_encoding", cause);
+    }
+}
+// @legacy ontology.workflow-run-legacy-encodings
+/** Only lossless JSON trees may match the previous provider binding format. */
+export function legacyWorkflowArgumentsJson(args) {
+    const seen = new Set();
+    const encode = (value) => {
+        if (value === null || typeof value === "string" || typeof value === "boolean") {
+            return JSON.stringify(value);
+        }
+        if (typeof value === "number" && Number.isFinite(value) && !Object.is(value, -0)) {
+            return JSON.stringify(value);
+        }
+        if (typeof value !== "object" ||
+            seen.has(value) ||
+            (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype)) {
+            throw new TypeError("workflow_arguments_not_legacy_json");
+        }
+        seen.add(value);
+        return Array.isArray(value)
+            ? `[${Array.from(value, encode).join(",")}]`
+            : `{${Object.keys(value)
+                .sort()
+                .map((key) => `${JSON.stringify(key)}:${encode(value[key])}`)
+                .join(",")}}`;
+    };
+    try {
+        return encode(args);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runtime/workflow-starts.d.ts

@@ -0,0 +1,203 @@
+import { Context, Effect, Schema } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+import type { AnyAction } from "../action.js";
+import type { Ontology } from "../ontology.js";
+import type { Principal, StoredRecord } from "../runtime.js";
+import { type ActionEvent, type TriggerFunction, type WorkflowRunContext } from "../workflow.js";
+import type { StartRecoveryOutcome } from "../start-recovery-contract.js";
+import { TriggerInputInvalid } from "./errors.js";
+import type { Edit } from "./history.js";
+/** Starts that fail this many times are left for an operator: the automatic sweep skips them. */
+export declare const MAX_START_ATTEMPTS = 10;
+/** How long a pending row waits before a sweep takes it: its own request starts it first. */
+export declare const SWEEP_DELAY_SECONDS = 30;
+/** The most rows one sweep starts. */
+export declare const SWEEP_BATCH = 100;
+/** How long started rows are kept, for the starts listing, before the sweep deletes them. */
+export declare const STARTED_RETENTION_DAYS = 30;
+/** A start an action trigger decided: one row of `_workflow_starts`. */
+export interface PendingStart {
+    readonly reservation?: import("./workflow-admission.js").WorkflowReservation;
+    readonly arguments?: ReadonlyArray<unknown>;
+    readonly attributes?: Readonly<Record<string, string>>;
+    readonly workflowId?: string;
+    readonly deploymentId?: string;
+    /** `<workflow>.<trigger>`, in wire names. */
+    readonly trigger: string;
+    /** The workflow's wire name. */
+    readonly workflow: string;
+    readonly actionId: string;
+    /** The record the trigger was evaluated for; `null` when it fired once, for the record the input names. */
+    readonly recordId: string | null;
+    /** The workflow's input in its wire form, as the cron route receives it. */
+    readonly input: unknown;
+}
+declare const WorkflowStartFailed_base: Schema.Class<WorkflowStartFailed, Schema.TaggedStruct<"WorkflowStartFailed", {
+    readonly reason: Schema.Literals<readonly ["unknown_workflow", "not_compiled", "no_recovery_workflow", "invalid_input", "engine", "timeout"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, import("effect/Cause").YieldableError>;
+/** The Workflow SDK refused or did not answer a start; the row stays pending. */
+export declare class WorkflowStartFailed extends WorkflowStartFailed_base {
+}
+declare const WorkflowStarter_base: Context.ServiceClass<WorkflowStarter, "@segmentstream/ontology/WorkflowStarter", {
+    readonly recoveryHorizon?: () => number;
+    readonly allocateRun?: () => Promise<import("./workflow-admission.js").WorkflowReservation>;
+    /** The run id the Workflow SDK accepted. */
+    readonly start: (start: PendingStart) => Effect.Effect<string, WorkflowStartFailed>;
+    readonly prepare?: (start: PendingStart) => Effect.Effect<import("./workflow-admission.js").AdmittedWorkflowStart, WorkflowStartFailed>;
+    /** Pure code-derived binding; safe to capture in the action transaction before commit. */
+    readonly capture?: (start: PendingStart) => Omit<import("./workflow-admission.js").AdmittedWorkflowStart, "reservation">;
+    /**
+     * Makes sure a recovery run will sweep after `commitBy`, the latest instant (epoch ms) the
+     * calling action may commit at; it starts one unless an armed run already covers it. An action
+     * whose triggers may fire calls it before its transaction opens, and is refused when it fails.
+     */
+    readonly ensureRecovery: (input: {
+        readonly commitBy: number;
+        readonly submit?: (input: {
+            readonly workflowId: string;
+            readonly arguments: ReadonlyArray<unknown>;
+            readonly attributes: Readonly<Record<string, string>>;
+        }) => Promise<{
+            readonly runId: string;
+        }>;
+    }) => Effect.Effect<void, WorkflowStartFailed>;
+}>;
+/**
+ * Starts the run of a pending row through the Workflow SDK, on the ontology's queue, with
+ * `startedBy` naming the trigger, the action and the record, and arms the recovery run that starts
+ * what a request leaves pending. The ontology service provides it; a runtime without one leaves its
+ * rows pending for an operator's sweep.
+ */
+export declare class WorkflowStarter extends WorkflowStarter_base {
+}
+/** The `startedBy` of a run an action trigger started. */
+export declare function triggerContext(start: PendingStart): WorkflowRunContext;
+/** An action trigger as the runtime evaluates it: the manifest's names and the authored functions. */
+export interface ResolvedActionTrigger {
+    /** The workflow's wire name. */
+    readonly workflow: string;
+    /** `<workflow>.<trigger>`, in wire names. */
+    readonly trigger: string;
+    /** The entity's wire name. */
+    readonly entity: string;
+    /** The action's wire name; `undefined` for any action of the entity. */
+    readonly action: string | undefined;
+    readonly when: TriggerFunction<ActionEvent, unknown, boolean> | undefined;
+    readonly input: TriggerFunction<ActionEvent, unknown, unknown> | undefined;
+    /** The workflow's input codec, TypeScript names on the type side and wire names encoded. */
+    readonly codec: Schema.Top;
+}
+/**
+ * The action triggers of the workflows that passed `check`, paired with their declarations. Built
+ * once per ontology.
+ */
+export declare function actionTriggers(ontology: Ontology): ReadonlyArray<ResolvedActionTrigger>;
+/** Whether the ontology declares any action trigger, so that `_workflow_starts` exists. */
+export declare function hasActionTriggers(ontology: Ontology): boolean;
+/**
+ * The triggers that fire for an action of `entity` run by `principal`: on that action or on the
+ * entity, except the triggers of the workflow whose user runs it, so that a workflow never starts
+ * itself.
+ */
+export declare function matchingTriggers(ontology: Ontology, entity: string, action: string, principal: Principal): ReadonlyArray<ResolvedActionTrigger>;
+/** A record of the trigger's entity the action edited, as stored before and after it. */
+export interface HeldRecord {
+    readonly before: StoredRecord | undefined;
+    readonly after: StoredRecord | undefined;
+}
+/** What the action's transaction knows when its handler returned. */
+export interface TriggerEvaluation {
+    readonly ontology: Ontology;
+    /** The entity's wire name. */
+    readonly entity: string;
+    /** The action's wire name. */
+    readonly action: string;
+    readonly definition: AnyAction;
+    /** A generated action: its input and result are in wire names. */
+    readonly generated: boolean;
+    readonly actionId: string;
+    /** When the action ran: the transaction's time, as history records it. */
+    readonly at: string;
+    readonly principal: Principal;
+    /** The decoded input. */
+    readonly input: unknown;
+    readonly result: unknown;
+    readonly edits: ReadonlyArray<Edit>;
+    /** The before and after of each created, updated or deleted record of the entity, by id. */
+    readonly held: ReadonlyMap<string, HeldRecord>;
+    /** The current record, for a record the action only linked or unlinked. */
+    readonly load: (id: string) => Effect.Effect<StoredRecord | undefined, SqlError>;
+}
+/** A trigger function threw, or `when` answered something other than a boolean: a defect. */
+export declare class TriggerFunctionFailed extends Error {
+    constructor(trigger: string, part: "when" | "input", cause: unknown);
+}
+/**
+ * Evaluates the matching triggers inside the action's transaction: selects the records, runs
+ * `when`, maps and validates the input with the workflow's input schema. A function that throws is
+ * a defect, which rolls the action back; an input the workflow does not accept fails the action
+ * with {@link TriggerInputInvalid}. The starts it answers are in the wire form the rows store.
+ */
+export declare function evaluateTriggers(triggers: ReadonlyArray<ResolvedActionTrigger>, evaluation: TriggerEvaluation): Effect.Effect<ReadonlyArray<PendingStart>, TriggerInputInvalid, never>;
+/** Inserts the starts in the action's transaction, so they commit with its records and history. */
+export declare function insertStarts(sql: SqlClient.SqlClient, starts: ReadonlyArray<PendingStart>): Effect.Effect<void, SqlError>;
+/**
+ * Starts the rows an action's transaction inserted, after its commit, in the same request. A
+ * failure is logged and leaves the row pending for the sweep; nothing here fails the action.
+ */
+export declare function startCommitted(sql: SqlClient.SqlClient, starter: WorkflowStarter["Service"] | undefined, starts: ReadonlyArray<PendingStart>, requestId: string): Effect.Effect<void>;
+/**
+ * What one sweep did: runs started, starts that failed again, rows left for an operator, rows an
+ * automatic sweep still takes, and the database's clock. The same shape the recovery run's step
+ * answers with.
+ */
+export type SweepResult = StartRecoveryOutcome;
+/**
+ * The sweep: starts up to {@link SWEEP_BATCH} rows pending for more than
+ * {@link SWEEP_DELAY_SECONDS}, oldest first, locked with `SKIP LOCKED` so that concurrent sweeps
+ * take different rows, and records each outcome before the locks are released. Rows that failed
+ * {@link MAX_START_ATTEMPTS} times are taken only with `retryAbandoned`. Started rows older than
+ * {@link STARTED_RETENTION_DAYS} days are deleted. `waiting` counts the pending rows an automatic
+ * sweep still takes, young ones included, created before `before` when it is given: the recovery
+ * run's horizon.
+ */
+export declare function sweepStarts(sql: SqlClient.SqlClient, starter: WorkflowStarter["Service"] | undefined, options: {
+    readonly retryAbandoned: boolean;
+    readonly requestId: string;
+    /** ISO 8601; counts as waiting only the rows created before it. */
+    readonly before?: string | undefined;
+}): Effect.Effect<SweepResult, SqlError>;
+/** A row of the starts listing; the input stays in the database. */
+export interface WorkflowStartView {
+    readonly trigger: string;
+    readonly actionId: string;
+    readonly recordId: string | null;
+    readonly createdAt: string;
+    readonly runId: string | null;
+    readonly startedAt: string | null;
+    readonly attempts: number;
+}
+export interface WorkflowStartsPage {
+    readonly items: ReadonlyArray<WorkflowStartView>;
+    readonly nextCursor: string | null;
+}
+declare const InvalidStartsCursor_base: Schema.Class<InvalidStartsCursor, Schema.TaggedStruct<"InvalidStartsCursor", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The starts listing's cursor does not decode: it was not one this listing gave. */
+export declare class InvalidStartsCursor extends InvalidStartsCursor_base {
+}
+/**
+ * A page of a workflow's starts, newest first: all of them, or only the pending or the started
+ * ones. A database without `_workflow_starts` has none.
+ */
+export declare function listStarts(sql: SqlClient.SqlClient, input: {
+    readonly workflow: string;
+    readonly pending?: boolean | undefined;
+    readonly limit: number;
+    readonly after?: string | undefined;
+}): Effect.Effect<WorkflowStartsPage, InvalidStartsCursor | SqlError>;
+export {};