@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/runtime/validation.d.ts

@@ -0,0 +1,16 @@
+import { Schema } from "effect";
+import type { ValidationIssue } from "./errors.js";
+/** The issues of a schema failure, flattened to `{ path, message }`. */
+export declare function schemaIssues(error: Schema.SchemaError): ReadonlyArray<ValidationIssue>;
+export type Validated<A> = {
+    readonly ok: true;
+    readonly value: A;
+} | {
+    readonly ok: false;
+    readonly issues: ReadonlyArray<ValidationIssue>;
+};
+/**
+ * Decodes an input, reporting every issue and rejecting unknown keys. The schemas validated here
+ * need no services; a schema that does is a defect in the definition.
+ */
+export declare function validate<A>(schema: Schema.Top, input: unknown): Validated<A>;

package/dist/runtime/validation.js

@@ -0,0 +1,26 @@
+import { Result, Schema, SchemaIssue } from "effect";
+const formatter = SchemaIssue.makeFormatterStandardSchemaV1();
+function pathSegment(segment) {
+    const key = typeof segment === "object" ? segment.key : segment;
+    return typeof key === "number" ? key : String(key);
+}
+/** The issues of a schema failure, flattened to `{ path, message }`. */
+export function schemaIssues(error) {
+    return formatter(error.issue).issues.map((issue) => ({
+        path: (issue.path ?? []).map(pathSegment),
+        message: issue.message,
+    }));
+}
+/**
+ * Decodes an input, reporting every issue and rejecting unknown keys. The schemas validated here
+ * need no services; a schema that does is a defect in the definition.
+ */
+export function validate(schema, input) {
+    const result = Schema.decodeUnknownResult(schema)(input, {
+        errors: "all",
+        onExcessProperty: "error",
+    });
+    return Result.isSuccess(result)
+        ? { ok: true, value: result.success }
+        : { ok: false, issues: schemaIssues(result.failure) };
+}

package/dist/runtime/where.d.ts

@@ -0,0 +1,57 @@
+import { type PermissionHolder, type ScopeWhere } from "../permissions.js";
+import { type FieldFilter, type Where } from "../query.js";
+import { type EntityModel, type FieldModel, type OntologyModel } from "./model.js";
+import { Aliases, Params } from "./statement.js";
+/** Whose scoped permissions a statement honours: the principal's user id and its grants. */
+export interface ScopeReader extends PermissionHolder {
+    /** The id of the principal's `user` record: `me` in a scope. */
+    readonly id: string;
+}
+/** A scope and the principal whose `me` it means. */
+export interface RowScope {
+    readonly reader: ScopeReader;
+    readonly where: ScopeWhere;
+}
+/**
+ * Compiles a `where` that the entity's query schema accepted into a SQL condition on the table
+ * aliased `alias`. Every value is a parameter cast to its column's type.
+ */
+export interface WhereContext {
+    readonly model: OntologyModel;
+    readonly params: Params;
+    readonly aliases: Aliases;
+    /**
+     * The caller of a scoped read. A relationship filter then also requires the related records to
+     * be inside the caller's read scope of their entity, so that a filter cannot probe hidden rows.
+     * Absent for reads with the action's authority, and for callers that hold no scoped permission.
+     */
+    readonly reader?: ScopeReader;
+}
+export declare function compileWhere(context: WhereContext, entity: EntityModel, alias: string, where: Where | undefined): string;
+/**
+ * Compiles the `where` of a scoped permission on the table aliased `alias`, with `me` as the
+ * reader's user id and a path as the set of ids it reaches. A scope is compiled with the platform's
+ * authority: its own relationship filters and paths read every row. Anything `check` would have
+ * refused (an unknown field, operator or hop, an operand of the wrong type, `me` where a set is
+ * expected, or the reverse) matches nothing, and so does a scope the compiler fails on for any
+ * other reason: a scope never widens and never fails the statement.
+ */
+export declare function compileScope(context: WhereContext, entity: EntityModel, alias: string, scope: RowScope): string;
+/**
+ * Whether a scope is a valid `where` of its entity, as {@link compileScope} reads it: `false` for
+ * anything that would compile to FALSE as a whole, such as `me` on a field that is not a key or an
+ * operand of the wrong type. A scope that leaves the service, such as a metric query's row scope, is
+ * checked here first, so that it never means more there than it does to the service's own reads.
+ */
+export declare function isWellFormedScope(model: OntologyModel, entity: EntityModel, scope: RowScope): boolean;
+/**
+ * The reader's read scope of `entity` as a condition on `alias`, or `undefined` when it reads every
+ * record of it.
+ */
+export declare function readCondition(context: WhereContext, entity: EntityModel, alias: string): string | undefined;
+/** The reader's read scope of `entity`, or `undefined` without a reader or a scope on it. */
+export declare function readScopeOf(reader: ScopeReader | undefined, entity: EntityModel): RowScope | undefined;
+/** A bare value is `eq`, `null` is `isNull`. JSON values are filters only when every key is one. */
+export declare function fieldFilter(field: FieldModel, condition: unknown): FieldFilter;
+/** The conditions of one field filter, joined with AND. */
+export declare function fieldCondition(params: Params, column: string, field: FieldModel, condition: unknown): string;

package/dist/runtime/where.js

@@ -0,0 +1,404 @@
+import { MAX_ME_HOPS, mePathOf } from "../me.js";
+import { readScope } from "../permissions.js";
+import { FILTER_OPERATORS, isFieldFilterOf, MANY_QUANTIFIERS, } from "../query.js";
+import { quoteIdentifier } from "../migrate/storage.js";
+import { User } from "../user.js";
+import { entityModel, } from "./model.js";
+import { bindValue, isRecordId } from "./records.js";
+import { Aliases, columnOf, escapeLike, Params } from "./statement.js";
+import { userHoldsRoleCondition } from "./user-roles.js";
+/** The wire names of filter operators, as scopes are written in the manifest. */
+const WIRE_OPERATORS = {
+    is_null: "isNull",
+    starts_with: "startsWith",
+    has_any: "hasAny",
+};
+const OPERATORS = new Set(FILTER_OPERATORS);
+const QUANTIFIERS = new Set(MANY_QUANTIFIERS);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function and(parts) {
+    return parts.length === 0 ? "TRUE" : parts.map((part) => `(${part})`).join(" AND ");
+}
+function or(parts) {
+    return parts.length === 0 ? "FALSE" : parts.map((part) => `(${part})`).join(" OR ");
+}
+export function compileWhere(context, entity, alias, where) {
+    return compile(context, entity, alias, where, false);
+}
+/**
+ * Compiles the `where` of a scoped permission on the table aliased `alias`, with `me` as the
+ * reader's user id and a path as the set of ids it reaches. A scope is compiled with the platform's
+ * authority: its own relationship filters and paths read every row. Anything `check` would have
+ * refused (an unknown field, operator or hop, an operand of the wrong type, `me` where a set is
+ * expected, or the reverse) matches nothing, and so does a scope the compiler fails on for any
+ * other reason: a scope never widens and never fails the statement.
+ */
+export function compileScope(context, entity, alias, scope) {
+    const bound = context.params.values.length;
+    try {
+        return compile({ ...context, reader: scope.reader }, entity, alias, scope.where, true);
+    }
+    catch {
+        // The whole scope matches nothing, whatever `not` would have made of its malformed part.
+        context.params.values.length = bound;
+        return "FALSE";
+    }
+}
+/**
+ * Whether a scope is a valid `where` of its entity, as {@link compileScope} reads it: `false` for
+ * anything that would compile to FALSE as a whole, such as `me` on a field that is not a key or an
+ * operand of the wrong type. A scope that leaves the service, such as a metric query's row scope, is
+ * checked here first, so that it never means more there than it does to the service's own reads.
+ */
+export function isWellFormedScope(model, entity, scope) {
+    try {
+        compile({ model, params: new Params(), aliases: new Aliases(), reader: scope.reader }, entity, "t", scope.where, true);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A scope `check` would have refused: it compiles to FALSE as a whole. */
+class MalformedScope extends Error {
+}
+function malformed() {
+    throw new MalformedScope("The scope is not a valid where of its entity.");
+}
+/**
+ * The reader's read scope of `entity` as a condition on `alias`, or `undefined` when it reads every
+ * record of it.
+ */
+export function readCondition(context, entity, alias) {
+    const scope = readScopeOf(context.reader, entity);
+    return scope === undefined ? undefined : compileScope(context, entity, alias, scope);
+}
+/** The reader's read scope of `entity`, or `undefined` without a reader or a scope on it. */
+export function readScopeOf(reader, entity) {
+    const where = reader === undefined ? undefined : readScope(entity.name, reader);
+    return where === undefined || reader === undefined ? undefined : { reader, where };
+}
+function compile(context, entity, alias, where, inScope) {
+    if (where === undefined) {
+        return inScope ? malformed() : "TRUE";
+    }
+    // In a scope, an empty where would match every record while counting as scoped.
+    if (inScope &&
+        (!isPlainObject(where) || mePathOf(where) !== undefined || Object.keys(where).length === 0)) {
+        return malformed();
+    }
+    const parts = [];
+    for (const [key, condition] of Object.entries(where)) {
+        if (condition === undefined) {
+            if (inScope) {
+                return malformed();
+            }
+            continue;
+        }
+        if ((key === "and" || key === "or") &&
+            inScope &&
+            (!Array.isArray(condition) || (key === "and" && condition.length === 0))) {
+            parts.push(malformed());
+        }
+        else if (key === "and") {
+            parts.push(and(subWheres(condition).map((sub) => compile(context, entity, alias, sub, inScope))));
+        }
+        else if (key === "or") {
+            parts.push(or(subWheres(condition).map((sub) => compile(context, entity, alias, sub, inScope))));
+        }
+        else if (key === "not") {
+            // IS NOT TRUE, so that a condition on an empty field counts as not matching.
+            parts.push(`(${compile(context, entity, alias, condition, inScope)}) IS NOT TRUE`);
+        }
+        else {
+            parts.push(memberCondition(context, entity, alias, key, condition, inScope));
+        }
+    }
+    return and(parts);
+}
+function subWheres(condition) {
+    return condition;
+}
+function memberCondition(context, entity, alias, key, condition, inScope) {
+    const field = entity.fieldsByName.get(key);
+    if (field !== undefined) {
+        return inScope
+            ? scopeFieldCondition(context, columnOf(alias, field.column), field, condition)
+            : fieldCondition(context.params, columnOf(alias, field.column), field, condition);
+    }
+    const link = entity.links.get(key);
+    if (link === undefined) {
+        if (inScope) {
+            return malformed();
+        }
+        throw new Error(`${entity.name}.${key} is neither a field nor a relationship.`);
+    }
+    if (inScope && (mePathOf(condition) !== undefined || isOperators(condition))) {
+        // A scope compares a to-one relationship by its key: `{ division: { in: me.… } }`.
+        const keyField = entity.fieldsByName.get(`${key}_id`);
+        return link.via === "key" && keyField !== undefined
+            ? scopeFieldCondition(context, columnOf(alias, keyField.column), keyField, condition)
+            : malformed();
+    }
+    if (inScope && !isPlainObject(condition)) {
+        return malformed();
+    }
+    return linkCondition(context, alias, link, condition, inScope);
+}
+/** Whether a condition is an object of filter operators, by their query or wire names. */
+function isOperators(condition) {
+    if (!isPlainObject(condition)) {
+        return false;
+    }
+    const keys = Object.keys(condition);
+    return (keys.length > 0 && keys.every((key) => OPERATORS.has(key) || Object.hasOwn(WIRE_OPERATORS, key)));
+}
+/** Whether `me` or a path appears anywhere in a value. */
+function holdsMe(value) {
+    if (mePathOf(value) !== undefined) {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.some(holdsMe);
+    }
+    return isPlainObject(value) && Object.values(value).some(holdsMe);
+}
+/**
+ * A field condition of a scope: as in a query, with wire operator names, plus `me` compared with
+ * `eq` or `ne` (or bare) and a path compared with `in`. A marker anywhere else, an operator the
+ * field does not take and an operand of the wrong type are malformed: the field's query filter
+ * schema validates the conditions without a marker before they compile.
+ */
+function scopeFieldCondition(context, column, field, condition) {
+    const bare = mePathOf(condition);
+    if (bare !== undefined) {
+        return meCondition(context, column, field, "eq", bare);
+    }
+    if (condition === undefined ||
+        (isPlainObject(condition) && Object.keys(condition).length === 0)) {
+        return malformed();
+    }
+    const renamed = isPlainObject(condition)
+        ? Object.fromEntries(Object.entries(condition).map(([key, value]) => [
+            Object.hasOwn(WIRE_OPERATORS, key) ? WIRE_OPERATORS[key] : key,
+            value,
+        ]))
+        : condition;
+    const plain = {};
+    const parts = [];
+    for (const [operator, operand] of Object.entries(fieldFilter(field, renamed))) {
+        const hops = mePathOf(operand);
+        if (hops !== undefined) {
+            parts.push(meCondition(context, column, field, operator, hops));
+        }
+        else if (holdsMe(operand) || operand === undefined) {
+            parts.push(malformed());
+        }
+        else {
+            plain[operator] = operand;
+        }
+    }
+    if (Object.keys(plain).length > 0) {
+        if (!isFieldFilterOf(field, plain)) {
+            return malformed();
+        }
+        parts.unshift(fieldCondition(context.params, column, field, plain));
+    }
+    return and(parts);
+}
+/**
+ * `me` compared with a key column (`eq`, `ne`), or a path's set of ids (`in`). The reader's id is
+ * one parameter; a path is a chain of `IN (SELECT …)` subqueries walking the relationships from it.
+ */
+function meCondition(context, column, field, operator, hops) {
+    const reader = context.reader;
+    if (field.storage !== "uuid" || reader === undefined || !isRecordId(reader.id)) {
+        return malformed();
+    }
+    if (hops.length === 0) {
+        if (operator === "eq") {
+            return `${column} = ${context.params.add(reader.id.toLowerCase(), "uuid")}`;
+        }
+        return operator === "ne"
+            ? `${column} IS DISTINCT FROM ${context.params.add(reader.id.toLowerCase(), "uuid")}`
+            : malformed();
+    }
+    if (operator !== "in" || hops.length > MAX_ME_HOPS) {
+        return malformed();
+    }
+    const ids = mePath(context, reader.id.toLowerCase(), hops);
+    return ids === undefined ? malformed() : `${column} IN (${ids})`;
+}
+/**
+ * The ids a path of relationship names reaches from the reader's `user` record, as a subquery: each
+ * hop selects the next entity's ids from the previous hop's. `undefined` when a hop is not a
+ * relationship of the entity it starts from.
+ */
+function mePath(context, readerId, hops) {
+    // Resolve every hop before binding anything: an unused parameter would fail the statement.
+    const steps = [];
+    let entity = context.model.entities.get(User.name);
+    for (const hop of hops) {
+        const link = entity?.links.get(hop);
+        const target = link === undefined ? undefined : context.model.entities.get(link.target);
+        if (entity === undefined || link === undefined || target === undefined) {
+            return undefined;
+        }
+        steps.push({ from: entity, link, to: target });
+        entity = target;
+    }
+    let ids = context.params.add(readerId, "uuid");
+    for (const { from, link, to } of steps) {
+        const alias = context.aliases.take("m");
+        const as = quoteIdentifier(alias);
+        if (link.via === "key") {
+            ids =
+                `SELECT ${columnOf(alias, link.column)} FROM ${quoteIdentifier(from.table)} AS ${as} ` +
+                    `WHERE ${columnOf(alias, "id")} IN (${ids})`;
+        }
+        else if (link.via === "inverse-key") {
+            ids =
+                `SELECT ${columnOf(alias, "id")} FROM ${quoteIdentifier(to.table)} AS ${as} ` +
+                    `WHERE ${columnOf(alias, link.column)} IN (${ids})`;
+        }
+        else {
+            ids =
+                `SELECT ${columnOf(alias, link.otherColumn)} FROM ${quoteIdentifier(link.table)} AS ${as} ` +
+                    `WHERE ${columnOf(alias, link.selfColumn)} IN (${ids})`;
+        }
+    }
+    return ids;
+}
+/** A bare value is `eq`, `null` is `isNull`. JSON values are filters only when every key is one. */
+export function fieldFilter(field, condition) {
+    if (condition === null) {
+        return { isNull: true };
+    }
+    const isFilter = isPlainObject(condition) &&
+        (field.storage !== "json" || Object.keys(condition).every((key) => OPERATORS.has(key)));
+    return isFilter ? condition : { eq: condition };
+}
+/**
+ * The conditions of a list filter, joined with AND. The only list, the user's `roles`, is an
+ * `EXISTS` on the role assignments of the row whose id `column` holds.
+ */
+function listCondition(params, column, filter) {
+    const bind = (value) => params.add(value, "text");
+    const parts = [];
+    if (filter.has !== undefined) {
+        parts.push(userHoldsRoleCondition(column, [bind(filter.has)]));
+    }
+    if (filter.hasAny !== undefined) {
+        parts.push(userHoldsRoleCondition(column, filter.hasAny.map(bind)));
+    }
+    return and(parts);
+}
+/** The conditions of one field filter, joined with AND. */
+export function fieldCondition(params, column, field, condition) {
+    const filter = fieldFilter(field, condition);
+    if (field.storage === "list") {
+        return listCondition(params, column, filter);
+    }
+    const bind = (value) => params.add(bindValue(field, value), field.sqlType);
+    const parts = [];
+    for (const [operator, operand] of Object.entries(filter)) {
+        if (operand === undefined) {
+            continue;
+        }
+        switch (operator) {
+            case "eq":
+                parts.push(`${column} = ${bind(operand)}`);
+                break;
+            case "ne":
+                parts.push(`${column} IS DISTINCT FROM ${bind(operand)}`);
+                break;
+            case "in": {
+                const values = operand;
+                parts.push(values.length === 0 ? "FALSE" : `${column} IN (${values.map(bind).join(", ")})`);
+                break;
+            }
+            case "isNull":
+                parts.push(operand === true ? `${column} IS NULL` : `${column} IS NOT NULL`);
+                break;
+            case "contains":
+                parts.push(`${column} ILIKE ${params.add(`%${escapeLike(operand)}%`, "text")} ESCAPE '\\'`);
+                break;
+            case "startsWith":
+                parts.push(`${column} ILIKE ${params.add(`${escapeLike(operand)}%`, "text")} ESCAPE '\\'`);
+                break;
+            case "gt":
+                parts.push(`${column} > ${bind(operand)}`);
+                break;
+            case "gte":
+                parts.push(`${column} >= ${bind(operand)}`);
+                break;
+            case "lt":
+                parts.push(`${column} < ${bind(operand)}`);
+                break;
+            case "lte":
+                parts.push(`${column} <= ${bind(operand)}`);
+                break;
+            case "between": {
+                const [low, high] = operand;
+                parts.push(`${column} BETWEEN ${bind(low)} AND ${bind(high)}`);
+                break;
+            }
+            default:
+                throw new Error(`Unknown filter operator ${operator}.`);
+        }
+    }
+    return and(parts);
+}
+function linkCondition(context, alias, link, condition, inScope) {
+    const target = entityModel(context.model, link.target);
+    // The caller's own filter sees only the related records the caller may read; a scope's does not.
+    const visible = (targetAlias, sub) => {
+        const scope = inScope ? undefined : readCondition(context, target, targetAlias);
+        return scope === undefined ? sub : `(${sub}) AND (${scope})`;
+    };
+    if (link.via === "key") {
+        const targetAlias = context.aliases.take();
+        const sub = compile(context, target, targetAlias, condition, inScope);
+        return (`EXISTS (SELECT 1 FROM ${quoteIdentifier(target.table)} AS ${quoteIdentifier(targetAlias)} ` +
+            `WHERE ${columnOf(targetAlias, "id")} = ${columnOf(alias, link.column)} AND (${visible(targetAlias, sub)}))`);
+    }
+    const filter = condition;
+    if (inScope &&
+        (Object.keys(filter).length === 0 ||
+            Object.entries(filter).some(([key, value]) => !QUANTIFIERS.has(key) || value === undefined))) {
+        return malformed();
+    }
+    const parts = [];
+    const related = (where, negate) => {
+        const targetAlias = context.aliases.take();
+        // In a scope, `some: {}` and `none: {}` ask whether any related record exists; `every: {}`,
+        // which every record meets, is malformed as any other empty where.
+        const anyRecord = inScope && !negate && isPlainObject(where) && Object.keys(where).length === 0;
+        const sub = anyRecord ? "TRUE" : compile(context, target, targetAlias, where, inScope);
+        return relatedRows(context, alias, link, target, targetAlias, visible(targetAlias, negate ? `(${sub}) IS NOT TRUE` : sub));
+    };
+    if (filter.some !== undefined) {
+        parts.push(`EXISTS (${related(filter.some, false)})`);
+    }
+    if (filter.none !== undefined) {
+        parts.push(`NOT EXISTS (${related(filter.none, false)})`);
+    }
+    if (filter.every !== undefined) {
+        parts.push(`NOT EXISTS (${related(filter.every, true)})`);
+    }
+    return and(parts);
+}
+/** `SELECT 1` from the records related to the row aliased `alias` that meet `condition`. */
+function relatedRows(context, alias, link, target, targetAlias, condition) {
+    const targetTable = `${quoteIdentifier(target.table)} AS ${quoteIdentifier(targetAlias)}`;
+    if (link.via === "inverse-key") {
+        return (`SELECT 1 FROM ${targetTable} ` +
+            `WHERE ${columnOf(targetAlias, link.column)} = ${columnOf(alias, "id")} AND (${condition})`);
+    }
+    const joinAlias = context.aliases.take("j");
+    return (`SELECT 1 FROM ${quoteIdentifier(link.table)} AS ${quoteIdentifier(joinAlias)} ` +
+        `JOIN ${targetTable} ON ${columnOf(targetAlias, "id")} = ${columnOf(joinAlias, link.otherColumn)} ` +
+        `WHERE ${columnOf(joinAlias, link.selfColumn)} = ${columnOf(alias, "id")} AND (${condition})`);
+}

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

@@ -0,0 +1,49 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import { DeploymentInterrupted } from "../errors.js";
+import { type OntologyManifest } from "../manifest.js";
+import type { Ontology } from "../ontology.js";
+import { WorkflowRecoveryUnavailable } from "./errors.js";
+export interface WorkflowReservation {
+    readonly admissionId?: string;
+    readonly runId: string;
+    readonly deploymentId: string;
+    readonly namespace: string;
+    readonly region?: string;
+}
+export interface WorkflowAdmissionKey {
+    readonly trigger: string;
+    readonly actionId: string;
+    readonly recordId: string | null;
+}
+export interface AdmittedWorkflowStart extends WorkflowAdmissionKey {
+    readonly commitBy?: number;
+    readonly workflow: string;
+    readonly workflowId: string;
+    readonly input: unknown;
+    readonly arguments: ReadonlyArray<unknown>;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly reservation: WorkflowReservation;
+}
+/** A short transaction reserves immutable submission input/routing before any provider I/O. */
+export declare function reserveWorkflowStart(sql: SqlClient.SqlClient, ontology: Ontology, proposed: AdmittedWorkflowStart): Effect.Effect<{
+    reservation: WorkflowReservation;
+    arguments: unknown[];
+    workflowId: string;
+    attributes: Readonly<Record<string, string>>;
+    commitBy?: number;
+    workflow: string;
+    input: unknown;
+    trigger: string;
+    actionId: string;
+    recordId: string | null;
+}, DeploymentInterrupted | import("effect/unstable/sql/SqlError").SqlError | WorkflowRecoveryUnavailable, never>;
+/** Acceptance is journaled after the provider call, in its own short transaction. */
+export declare function recordWorkflowSubmission(sql: SqlClient.SqlClient, start: AdmittedWorkflowStart): import("effect/unstable/sql/Statement").Statement<object>;
+/**
+ * Ontology SDKs 0.86.0 to 0.88.0 refuse every workflow start and step unless `_workflow_admission`
+ * holds one row in the `open` phase. Later SDKs do not read it. The migration that publishes a
+ * catalog keeps the row open, so a workspace still deployed on those SDKs keeps running and one
+ * left closed by their deploy guard opens again.
+ */
+export declare function recordWorkflowCatalog(sql: SqlClient.SqlClient, manifest: OntologyManifest): import("effect/unstable/sql/Statement").Statement<object>;

package/dist/runtime/workflow-admission.js

@@ -0,0 +1,92 @@
+import { Effect } from "effect";
+import { randomUUID } from "node:crypto";
+import { DeploymentInterrupted } from "../errors.js";
+import { canonicalJson } from "../manifest.js";
+import { WorkflowRecoveryUnavailable } from "./errors.js";
+import { decodeWorkflowArguments, encodeWorkflowArguments } from "./workflow-arguments.js";
+/** A short transaction reserves immutable submission input/routing before any provider I/O. */
+export function reserveWorkflowStart(sql, ontology, proposed) {
+    return sql.withTransaction(Effect.gen(function* () {
+        const checkDeadline = Effect.gen(function* () {
+            if (proposed.commitBy !== undefined &&
+                (!Number.isFinite(proposed.commitBy) || Date.now() >= proposed.commitBy)) {
+                return yield* new WorkflowRecoveryUnavailable({
+                    message: "Workflow recovery coverage expired before admission committed.",
+                });
+            }
+        });
+        yield* checkDeadline;
+        if (proposed.commitBy !== undefined) {
+            yield* sql.unsafe("SELECT set_config('transaction_timeout',$1,true)", [
+                String(Math.max(1, Math.floor(proposed.commitBy - Date.now()))),
+            ]);
+        }
+        yield* sql.unsafe(`INSERT INTO _workflow_starts (trigger,action_id,record_id,workflow,input)
+       VALUES ($1,$2::uuid,$3::uuid,$4,$5::jsonb)
+       ON CONFLICT DO NOTHING`, [
+            proposed.trigger,
+            proposed.actionId,
+            proposed.recordId,
+            proposed.workflow,
+            canonicalJson(proposed.input),
+        ]);
+        const [row] = yield* sql.unsafe(`SELECT workflow,input,reservation,arguments,provider_workflow_id,admission_attributes FROM _workflow_starts
+       WHERE trigger=$1 AND action_id=$2::uuid AND record_id IS NOT DISTINCT FROM $3::uuid FOR UPDATE`, [proposed.trigger, proposed.actionId, proposed.recordId]);
+        if (!row ||
+            row.workflow !== proposed.workflow ||
+            canonicalJson(row.input) !== canonicalJson(proposed.input)) {
+            return yield* new DeploymentInterrupted({
+                message: "The workflow admission identity was reused with different immutable input.",
+                servedHash: ontology.manifest.hash,
+            });
+        }
+        if (row.reservation && row.arguments && row.provider_workflow_id) {
+            yield* checkDeadline;
+            return {
+                ...proposed,
+                reservation: row.reservation,
+                arguments: decodeWorkflowArguments(row.arguments),
+                workflowId: row.provider_workflow_id,
+                attributes: row.admission_attributes ?? {},
+            };
+        }
+        const encodedArguments = encodeWorkflowArguments(proposed.arguments);
+        const admitted = {
+            ...proposed,
+            arguments: decodeWorkflowArguments(encodedArguments),
+            reservation: { ...proposed.reservation, admissionId: randomUUID() },
+        };
+        yield* sql.unsafe(`UPDATE _workflow_starts SET reservation=$4::jsonb, arguments=$5::jsonb,
+        provider_workflow_id=$6,admission_attributes=$7::jsonb
+       WHERE trigger=$1 AND action_id=$2::uuid AND record_id IS NOT DISTINCT FROM $3::uuid`, [
+            proposed.trigger,
+            proposed.actionId,
+            proposed.recordId,
+            canonicalJson(admitted.reservation),
+            canonicalJson(encodedArguments),
+            proposed.workflowId,
+            canonicalJson(proposed.attributes),
+        ]);
+        yield* checkDeadline;
+        return admitted;
+    }));
+}
+/** Acceptance is journaled after the provider call, in its own short transaction. */
+export function recordWorkflowSubmission(sql, start) {
+    return sql.unsafe(`UPDATE _workflow_starts SET run_id=$4,started_at=COALESCE(started_at,now())
+     WHERE trigger=$1 AND action_id=$2::uuid AND record_id IS NOT DISTINCT FROM $3::uuid
+       AND reservation->>'runId'=$4`, [start.trigger, start.actionId, start.recordId, start.reservation.runId]);
+}
+// @legacy ontology.workflow-cutover-artifacts
+/**
+ * Ontology SDKs 0.86.0 to 0.88.0 refuse every workflow start and step unless `_workflow_admission`
+ * holds one row in the `open` phase. Later SDKs do not read it. The migration that publishes a
+ * catalog keeps the row open, so a workspace still deployed on those SDKs keeps running and one
+ * left closed by their deploy guard opens again.
+ */
+export function recordWorkflowCatalog(sql, manifest) {
+    return sql.unsafe(`INSERT INTO _workflow_admission(id,contract_hash,catalog_hash)
+     VALUES(true,$1,$1) ON CONFLICT(id) DO UPDATE SET catalog_hash=$1,contract_hash=$1,
+       phase='open',owner=NULL,target_hash=NULL,deadline=NULL,drained_generation=NULL,
+       resume_phase=NULL`, [manifest.hash]);
+}

package/dist/runtime/workflow-argument-codec.d.ts

@@ -0,0 +1,10 @@
+import type { parse, stringify } from "devalue";
+/** Synchronous value codecs only: admission calls these inside its SQL transaction. */
+export interface WorkflowArgumentCodecs {
+    readonly reducers: NonNullable<Parameters<typeof stringify>[1]>;
+    readonly revivers: NonNullable<Parameters<typeof parse>[1]>;
+}
+/** Server setup supplies the installed SDK's codecs; all bundled copies share the first one. */
+export declare function setWorkflowArgumentCodecs(codecs: WorkflowArgumentCodecs): void;
+/** Resolves locally, without loading the Workflow SDK or consulting a provider. */
+export declare function workflowArgumentCodecs(): WorkflowArgumentCodecs;