@protoyard/flows 0.0.0-stage → 1.1.0

package/dist/model/flow.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { inspectPlainData } from "./data.js";
+import { FLOW_LIMITS } from "./limits.js";
+import { FlowIdSchema } from "./refs.js";
+import { StepSchema } from "./steps.js";
+import { TriggerSchema } from "./triggers.js";
+import { validateFlow } from "./validate.js";
+import { formatPath, listSteps } from "./walk.js";
+export const FLOW_FORMAT_VERSION = 1;
+export const FLOW_STATUSES = ['draft', 'active', 'paused'];
+export const CollectionSchema = z.strictObject({
+    id: FlowIdSchema,
+    noun: z.string().trim().min(1).max(60),
+    plural: z.string().trim().min(1).max(60).optional(),
+    states: z
+        .array(z.strictObject({
+        id: FlowIdSchema,
+        label: z.string().trim().min(1).max(60),
+        final: z.boolean().optional(),
+    }))
+        .max(FLOW_LIMITS.maxStates),
+});
+export const ListSchema = z.strictObject({
+    id: FlowIdSchema,
+    name: z.string().trim().min(1).max(80),
+    items: z.array(z.string().trim().min(1).max(200)).max(FLOW_LIMITS.maxListItems),
+});
+export const FlowSchema = z
+    .strictObject({
+    formatVersion: z.literal(FLOW_FORMAT_VERSION),
+    id: FlowIdSchema,
+    name: z.string().trim().min(1).max(80),
+    description: z.string().trim().max(500).optional(),
+    status: z.enum(FLOW_STATUSES),
+    triggers: z.array(TriggerSchema).min(1, 'Add a way to start').max(FLOW_LIMITS.maxTriggers),
+    steps: z.array(StepSchema).max(FLOW_LIMITS.maxSteps),
+    collections: z.array(CollectionSchema).max(FLOW_LIMITS.maxCollections).optional(),
+    lists: z.array(ListSchema).max(FLOW_LIMITS.maxLists).optional(),
+    labels: z.array(z.string().trim().min(1).max(40)).max(10).optional(),
+})
+    .superRefine((flow, ctx) => {
+    const all = listSteps(flow.steps);
+    if (all.length > FLOW_LIMITS.maxSteps) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['steps'],
+            message: `A flow holds at most ${FLOW_LIMITS.maxSteps} steps`,
+        });
+    }
+    for (const location of all) {
+        if (location.depth >= FLOW_LIMITS.maxStepDepth) {
+            ctx.addIssue({
+                code: 'custom',
+                path: location.path,
+                message: `Branches nest at most ${FLOW_LIMITS.maxStepDepth} levels`,
+            });
+            break;
+        }
+    }
+});
+/**
+ * Parses untrusted input into a flow: plain-data and size checks first (no
+ * recursion over hostile structures), then the strict schema, then the
+ * semantic checks of `validateFlow`. Errors fail the parse; warnings ride
+ * along with a successful one.
+ */
+export function parseFlow(input) {
+    const problem = inspectPlainData(input);
+    if (problem) {
+        return {
+            ok: false,
+            diagnostics: [
+                { severity: 'error', code: 'not_plain_data', path: problem.path, message: problem.message },
+            ],
+        };
+    }
+    const parsed = FlowSchema.safeParse(input);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            diagnostics: parsed.error.issues.map((issue) => ({
+                severity: 'error',
+                code: 'schema',
+                path: formatPath(issue.path.filter((s) => typeof s !== 'symbol')) || '$',
+                message: issue.message,
+            })),
+        };
+    }
+    const diagnostics = validateFlow(parsed.data);
+    if (diagnostics.some((d) => d.severity === 'error'))
+        return { ok: false, diagnostics };
+    return { ok: true, flow: parsed.data, diagnostics };
+}

package/dist/model/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@protoyard/flows/model` — the serializable workflow model: triggers,
+ * steps, data-only conditions, edit operations, recipes and validation
+ * (ADR-041). Pure data and pure functions; no Svelte, no clock, no network.
+ */
+export { COMPARE_OPERATORS, type CompareOperator, type Condition, type ConditionOutcome, ConditionSchema, conditionRefs, conditionStats, describeCondition, evaluateCondition, type FlowJudge, type JudgeRequest, type Operand, OperandSchema, type Scalar, VALUE_TESTS, type ValueTest, } from './conditions.ts';
+export { type DataProblem, FORBIDDEN_KEYS, inspectPlainData } from './data.ts';
+export { CollectionSchema, FLOW_FORMAT_VERSION, FLOW_STATUSES, type Flow, type FlowCollection, type FlowList, FlowSchema, type FlowStatus, ListSchema, type ParseFlowResult, parseFlow, } from './flow.ts';
+export { FLOW_ID_PATTERN, FLOW_LIMITS } from './limits.ts';
+export { type ApplyOperationsResult, applyOperations, type FlowOperation, OperationSchema, } from './ops.ts';
+export { FLOW_RECIPES, type FlowRecipe, findRecipe } from './recipes.ts';
+export { type DataRef, DataRefSchema, describeRef, FlowIdSchema, type RefScope, resolveRef, } from './refs.ts';
+export { type BranchStep, isStepEnabled, QUESTION_KINDS, type Question, QuestionSchema, STEP_KINDS, STEP_TYPES, type Step, type StepCategory, type StepKind, type StepOf, StepSchema, type StepType, stepKind, } from './steps.ts';
+export { AUDIENCE_TYPES, type AudienceItem, AudienceSchema, type FlowText, FlowTextSchema, textPreview, textRefs, } from './text.ts';
+export { DAYS, type Day, EVENT_SOURCES, SURFACES, TimeOfDaySchema, type Trigger, TriggerSchema, type TriggerType, } from './triggers.ts';
+export { diagnosticsByStep, type FlowDiagnostic, type FlowDiagnosticCode, validateFlow, } from './validate.ts';
+export { type BranchArm, childArms, findStep, formatPath, listSteps, type PathSegment, runsBefore, type StepLocation, stepsBefore, walkSteps, } from './walk.ts';

package/dist/model/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@protoyard/flows/model` — the serializable workflow model: triggers,
+ * steps, data-only conditions, edit operations, recipes and validation
+ * (ADR-041). Pure data and pure functions; no Svelte, no clock, no network.
+ */
+export { COMPARE_OPERATORS, ConditionSchema, conditionRefs, conditionStats, describeCondition, evaluateCondition, OperandSchema, VALUE_TESTS, } from "./conditions.js";
+export { FORBIDDEN_KEYS, inspectPlainData } from "./data.js";
+export { CollectionSchema, FLOW_FORMAT_VERSION, FLOW_STATUSES, FlowSchema, ListSchema, parseFlow, } from "./flow.js";
+export { FLOW_ID_PATTERN, FLOW_LIMITS } from "./limits.js";
+export { applyOperations, OperationSchema, } from "./ops.js";
+export { FLOW_RECIPES, findRecipe } from "./recipes.js";
+export { DataRefSchema, describeRef, FlowIdSchema, resolveRef, } from "./refs.js";
+export { isStepEnabled, QUESTION_KINDS, QuestionSchema, STEP_KINDS, STEP_TYPES, StepSchema, stepKind, } from "./steps.js";
+export { AUDIENCE_TYPES, AudienceSchema, FlowTextSchema, textPreview, textRefs, } from "./text.js";
+export { DAYS, EVENT_SOURCES, SURFACES, TimeOfDaySchema, TriggerSchema, } from "./triggers.js";
+export { diagnosticsByStep, validateFlow, } from "./validate.js";
+export { childArms, findStep, formatPath, listSteps, runsBefore, stepsBefore, walkSteps, } from "./walk.js";

package/dist/model/limits.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Hard bounds for flow documents. A flow can arrive from an agent, a share
+ * link or a snapshot, so every list, string and tree is capped, and the caps
+ * are checked before any recursive parse (see `inspectPlainData`).
+ */
+export declare const FLOW_LIMITS: {
+    /** Steps in the whole flow, nested branches included. */
+    readonly maxSteps: 200;
+    /** Branch nesting (a branch inside a branch counts 2). */
+    readonly maxStepDepth: 8;
+    readonly maxTriggers: 8;
+    /** Condition nesting through `all`, `any` and `not`. */
+    readonly maxConditionDepth: 6;
+    /** Nodes in one condition tree. */
+    readonly maxConditionNodes: 64;
+    readonly maxQuestions: 30;
+    readonly maxChoices: 20;
+    readonly maxAudience: 50;
+    readonly maxCollections: 10;
+    readonly maxStates: 20;
+    readonly maxLists: 10;
+    readonly maxListItems: 200;
+    readonly maxTextParts: 50;
+    readonly maxPathSegments: 8;
+    readonly maxOperations: 200;
+    /** Raw JSON structure, measured before zod sees it. */
+    readonly maxDataDepth: 48;
+    readonly maxDataNodes: 50000;
+    readonly maxStringLength: 4000;
+};
+/** Ids are short slugs, so they are safe in paths, URLs and DOM ids. */
+export declare const FLOW_ID_PATTERN: RegExp;

package/dist/model/limits.js

@@ -0,0 +1,32 @@
+/**
+ * Hard bounds for flow documents. A flow can arrive from an agent, a share
+ * link or a snapshot, so every list, string and tree is capped, and the caps
+ * are checked before any recursive parse (see `inspectPlainData`).
+ */
+export const FLOW_LIMITS = {
+    /** Steps in the whole flow, nested branches included. */
+    maxSteps: 200,
+    /** Branch nesting (a branch inside a branch counts 2). */
+    maxStepDepth: 8,
+    maxTriggers: 8,
+    /** Condition nesting through `all`, `any` and `not`. */
+    maxConditionDepth: 6,
+    /** Nodes in one condition tree. */
+    maxConditionNodes: 64,
+    maxQuestions: 30,
+    maxChoices: 20,
+    maxAudience: 50,
+    maxCollections: 10,
+    maxStates: 20,
+    maxLists: 10,
+    maxListItems: 200,
+    maxTextParts: 50,
+    maxPathSegments: 8,
+    maxOperations: 200,
+    /** Raw JSON structure, measured before zod sees it. */
+    maxDataDepth: 48,
+    maxDataNodes: 50_000,
+    maxStringLength: 4_000,
+};
+/** Ids are short slugs, so they are safe in paths, URLs and DOM ids. */
+export const FLOW_ID_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;

package/dist/model/ops.d.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { type Flow } from './flow.ts';
+import { type Step } from './steps.ts';
+import type { FlowDiagnostic } from './validate.ts';
+export declare const OperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"update_flow">;
+    patch: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"set_status">;
+    status: z.ZodEnum<{
+        draft: "draft";
+        active: "active";
+        paused: "paused";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"add_trigger">;
+    trigger: z.ZodType<import("./triggers.ts").Trigger, unknown, z.core.$ZodTypeInternals<import("./triggers.ts").Trigger, unknown>>;
+    index: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"replace_trigger">;
+    triggerId: z.ZodString;
+    trigger: z.ZodType<import("./triggers.ts").Trigger, unknown, z.core.$ZodTypeInternals<import("./triggers.ts").Trigger, unknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"remove_trigger">;
+    triggerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"add_step">;
+    step: z.ZodType<Step, unknown, z.core.$ZodTypeInternals<Step, unknown>>;
+    parentId: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodEnum<{
+        then: "then";
+        otherwise: "otherwise";
+    }>>;
+    index: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"update_step">;
+    stepId: z.ZodString;
+    patch: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"remove_step">;
+    stepId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"move_step">;
+    stepId: z.ZodString;
+    parentId: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodEnum<{
+        then: "then";
+        otherwise: "otherwise";
+    }>>;
+    index: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"duplicate_step">;
+    stepId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"add_question">;
+    stepId: z.ZodString;
+    question: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            choice: "choice";
+        }>;
+        prompt: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    index: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"remove_question">;
+    stepId: z.ZodString;
+    questionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"upsert_collection">;
+    collection: z.ZodObject<{
+        id: z.ZodString;
+        noun: z.ZodString;
+        plural: z.ZodOptional<z.ZodString>;
+        states: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            final: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"remove_collection">;
+    collectionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"upsert_list">;
+    list: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        items: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"remove_list">;
+    listId: z.ZodString;
+}, z.core.$strict>], "op">;
+export type FlowOperation = z.infer<typeof OperationSchema>;
+export type ApplyOperationsResult = {
+    ok: true;
+    flow: Flow;
+    diagnostics: FlowDiagnostic[];
+} | {
+    ok: false;
+    flow: Flow;
+    failedAt: number | null;
+    diagnostics: FlowDiagnostic[];
+};
+/**
+ * Applies a batch of edits atomically. Operations are untrusted input and
+ * validated first; each runs on a copy; the result must parse as a flow
+ * (schema and semantic errors). On any failure the original flow is returned
+ * untouched with the diagnostics and the failing operation index (null when
+ * only the final flow is invalid).
+ */
+export declare function applyOperations(flow: Flow, operations: unknown): ApplyOperationsResult;

package/dist/model/ops.js

@@ -0,0 +1,311 @@
+import { z } from 'zod';
+import { inspectPlainData } from "./data.js";
+import { CollectionSchema, FLOW_STATUSES, ListSchema, parseFlow } from "./flow.js";
+import { FLOW_ID_PATTERN, FLOW_LIMITS } from "./limits.js";
+import { FlowIdSchema } from "./refs.js";
+import { QuestionSchema, StepSchema } from "./steps.js";
+import { TriggerSchema } from "./triggers.js";
+import { childArms, listSteps } from "./walk.js";
+/*
+ * Edits on a flow. Direct manipulation, a composer and an agent all go
+ * through `applyOperations`, so there is one way to change a flow: the batch
+ * is validated, applied to a copy, and the result must parse as a flow, or
+ * nothing changes.
+ */
+const BranchArmSchema = z.enum(['then', 'otherwise']);
+const IndexSchema = z.number().int().min(0).max(FLOW_LIMITS.maxSteps);
+/** A shallow patch for a step: any step field except its id and type. */
+const StepPatchSchema = z
+    .record(z.string().regex(/^[a-zA-Z][a-zA-Z0-9]{0,40}$/), z.unknown())
+    .refine((patch) => !('id' in patch) && !('type' in patch), 'A patch cannot change id or type');
+export const OperationSchema = z.discriminatedUnion('op', [
+    z.strictObject({
+        op: z.literal('update_flow'),
+        patch: z.strictObject({
+            name: z.string().optional(),
+            description: z.string().optional(),
+            labels: z.array(z.string()).optional(),
+        }),
+    }),
+    z.strictObject({ op: z.literal('set_status'), status: z.enum(FLOW_STATUSES) }),
+    z.strictObject({
+        op: z.literal('add_trigger'),
+        trigger: TriggerSchema,
+        index: IndexSchema.optional(),
+    }),
+    z.strictObject({
+        op: z.literal('replace_trigger'),
+        triggerId: FlowIdSchema,
+        trigger: TriggerSchema,
+    }),
+    z.strictObject({ op: z.literal('remove_trigger'), triggerId: FlowIdSchema }),
+    z.strictObject({
+        op: z.literal('add_step'),
+        step: StepSchema,
+        parentId: FlowIdSchema.optional(),
+        branch: BranchArmSchema.optional(),
+        index: IndexSchema.optional(),
+    }),
+    z.strictObject({ op: z.literal('update_step'), stepId: FlowIdSchema, patch: StepPatchSchema }),
+    z.strictObject({ op: z.literal('remove_step'), stepId: FlowIdSchema }),
+    z.strictObject({
+        op: z.literal('move_step'),
+        stepId: FlowIdSchema,
+        parentId: FlowIdSchema.optional(),
+        branch: BranchArmSchema.optional(),
+        index: IndexSchema,
+    }),
+    z.strictObject({ op: z.literal('duplicate_step'), stepId: FlowIdSchema }),
+    z.strictObject({
+        op: z.literal('add_question'),
+        stepId: FlowIdSchema,
+        question: QuestionSchema,
+        index: IndexSchema.optional(),
+    }),
+    z.strictObject({
+        op: z.literal('remove_question'),
+        stepId: FlowIdSchema,
+        questionId: FlowIdSchema,
+    }),
+    z.strictObject({ op: z.literal('upsert_collection'), collection: CollectionSchema }),
+    z.strictObject({ op: z.literal('remove_collection'), collectionId: FlowIdSchema }),
+    z.strictObject({ op: z.literal('upsert_list'), list: ListSchema }),
+    z.strictObject({ op: z.literal('remove_list'), listId: FlowIdSchema }),
+]);
+class OperationError extends Error {
+}
+const fail = (message) => {
+    throw new OperationError(message);
+};
+/** The list a step lives in (top level or a branch arm), resolved by parent id. */
+function containerOf(flow, parentId, branch) {
+    if (parentId === undefined) {
+        if (branch !== undefined)
+            fail('A branch arm needs a parentId');
+        return flow.steps;
+    }
+    const parent = listSteps(flow.steps).find((l) => l.step.id === parentId)?.step;
+    if (!parent)
+        return fail(`No step has the id "${parentId}"`);
+    const arm = childArms(parent).find((a) => a.branch === (branch ?? 'then'));
+    if (!arm)
+        return fail(`Step "${parentId}" is not a branch`);
+    return arm.steps;
+}
+/** The list holding a step and its index there. */
+function locate(flow, stepId) {
+    const visit = (list) => {
+        for (const [index, step] of list.entries()) {
+            if (step.id === stepId)
+                return { list, index, step };
+            for (const arm of childArms(step)) {
+                const found = visit(arm.steps);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    };
+    return visit(flow.steps) ?? fail(`No step has the id "${stepId}"`);
+}
+/** A free id derived from `base`: `base-copy`, `base-copy-2`… within the slug pattern. */
+function freeId(base, taken) {
+    for (let n = 1; n < 10_000; n += 1) {
+        const suffix = n === 1 ? '-copy' : `-copy-${n}`;
+        const candidate = `${base.slice(0, 64 - suffix.length)}${suffix}`;
+        if (FLOW_ID_PATTERN.test(candidate) && !taken.has(candidate)) {
+            taken.add(candidate);
+            return candidate;
+        }
+    }
+    return fail('No free id for the copy');
+}
+/** Deep copy with every step id (nested ones too) renamed to a free id. */
+function copyWithFreshIds(step, taken) {
+    const copy = structuredClone(step);
+    const rename = (s) => {
+        s.id = freeId(s.id, taken);
+        for (const arm of childArms(s))
+            arm.steps.forEach(rename);
+    };
+    rename(copy);
+    return copy;
+}
+const insertAt = (list, item, index) => {
+    list.splice(index === undefined ? list.length : Math.min(index, list.length), 0, item);
+};
+function apply(flow, operation) {
+    switch (operation.op) {
+        case 'update_flow':
+            Object.assign(flow, operation.patch);
+            return;
+        case 'set_status':
+            flow.status = operation.status;
+            return;
+        case 'add_trigger':
+            insertAt(flow.triggers, operation.trigger, operation.index);
+            return;
+        case 'replace_trigger': {
+            const index = flow.triggers.findIndex((t) => t.id === operation.triggerId);
+            if (index < 0)
+                fail(`No start has the id "${operation.triggerId}"`);
+            flow.triggers[index] = operation.trigger;
+            return;
+        }
+        case 'remove_trigger': {
+            const index = flow.triggers.findIndex((t) => t.id === operation.triggerId);
+            if (index < 0)
+                fail(`No start has the id "${operation.triggerId}"`);
+            flow.triggers.splice(index, 1);
+            return;
+        }
+        case 'add_step':
+            insertAt(containerOf(flow, operation.parentId, operation.branch), operation.step, operation.index);
+            return;
+        case 'update_step': {
+            const { list, index, step } = locate(flow, operation.stepId);
+            const next = { ...step };
+            for (const [key, value] of Object.entries(operation.patch)) {
+                if (value === undefined)
+                    delete next[key];
+                else
+                    next[key] = value;
+            }
+            // The merged step is re-validated with the whole flow at the end.
+            list[index] = next;
+            return;
+        }
+        case 'remove_step': {
+            const { list, index } = locate(flow, operation.stepId);
+            list.splice(index, 1);
+            return;
+        }
+        case 'move_step': {
+            const { list, index, step } = locate(flow, operation.stepId);
+            if (operation.parentId !== undefined) {
+                const inside = listSteps([step]).some((l) => l.step.id === operation.parentId);
+                if (inside)
+                    fail('A step cannot move inside itself');
+            }
+            list.splice(index, 1);
+            insertAt(containerOf(flow, operation.parentId, operation.branch), step, operation.index);
+            return;
+        }
+        case 'duplicate_step': {
+            const { list, index, step } = locate(flow, operation.stepId);
+            const taken = new Set(listSteps(flow.steps).map((l) => l.step.id));
+            list.splice(index + 1, 0, copyWithFreshIds(step, taken));
+            return;
+        }
+        case 'add_question': {
+            const { step } = locate(flow, operation.stepId);
+            if (step.type !== 'ask') {
+                throw new OperationError(`Step "${operation.stepId}" does not ask questions`);
+            }
+            insertAt(step.questions, operation.question, operation.index);
+            return;
+        }
+        case 'remove_question': {
+            const { step } = locate(flow, operation.stepId);
+            if (step.type !== 'ask') {
+                throw new OperationError(`Step "${operation.stepId}" does not ask questions`);
+            }
+            const index = step.questions.findIndex((q) => q.id === operation.questionId);
+            if (index < 0)
+                fail(`No question has the id "${operation.questionId}"`);
+            step.questions.splice(index, 1);
+            return;
+        }
+        case 'upsert_collection': {
+            flow.collections ??= [];
+            const list = flow.collections;
+            const index = list.findIndex((c) => c.id === operation.collection.id);
+            if (index < 0)
+                list.push(operation.collection);
+            else
+                list[index] = operation.collection;
+            return;
+        }
+        case 'remove_collection': {
+            const list = flow.collections ?? [];
+            const index = list.findIndex((c) => c.id === operation.collectionId);
+            if (index < 0)
+                fail(`No collection has the id "${operation.collectionId}"`);
+            list.splice(index, 1);
+            return;
+        }
+        case 'upsert_list': {
+            flow.lists ??= [];
+            const list = flow.lists;
+            const index = list.findIndex((l) => l.id === operation.list.id);
+            if (index < 0)
+                list.push(operation.list);
+            else
+                list[index] = operation.list;
+            return;
+        }
+        case 'remove_list': {
+            const list = flow.lists ?? [];
+            const index = list.findIndex((l) => l.id === operation.listId);
+            if (index < 0)
+                fail(`No list has the id "${operation.listId}"`);
+            list.splice(index, 1);
+            return;
+        }
+    }
+}
+const opDiagnostic = (index, message, code = 'schema') => ({
+    severity: 'error',
+    code,
+    path: `operations[${index}]`,
+    message,
+});
+/**
+ * Applies a batch of edits atomically. Operations are untrusted input and
+ * validated first; each runs on a copy; the result must parse as a flow
+ * (schema and semantic errors). On any failure the original flow is returned
+ * untouched with the diagnostics and the failing operation index (null when
+ * only the final flow is invalid).
+ */
+export function applyOperations(flow, operations) {
+    const problem = inspectPlainData(operations);
+    if (problem) {
+        return {
+            ok: false,
+            flow,
+            failedAt: null,
+            diagnostics: [opDiagnostic(0, problem.message, 'not_plain_data')],
+        };
+    }
+    const parsed = z.array(OperationSchema).max(FLOW_LIMITS.maxOperations).safeParse(operations);
+    if (!parsed.success) {
+        const first = parsed.error.issues[0];
+        const index = typeof first?.path[0] === 'number' ? first.path[0] : 0;
+        return {
+            ok: false,
+            flow,
+            failedAt: index,
+            diagnostics: parsed.error.issues.map((issue) => opDiagnostic(typeof issue.path[0] === 'number' ? issue.path[0] : 0, issue.message)),
+        };
+    }
+    const draft = structuredClone(flow);
+    for (const [index, operation] of parsed.data.entries()) {
+        try {
+            apply(draft, operation);
+        }
+        catch (error) {
+            if (!(error instanceof OperationError))
+                throw error;
+            return {
+                ok: false,
+                flow,
+                failedAt: index,
+                diagnostics: [opDiagnostic(index, error.message)],
+            };
+        }
+    }
+    const result = parseFlow(draft);
+    if (!result.ok)
+        return { ok: false, flow, failedAt: null, diagnostics: result.diagnostics };
+    return { ok: true, flow: result.flow, diagnostics: result.diagnostics };
+}

package/dist/model/recipes.d.ts

@@ -0,0 +1,12 @@
+import type { Flow } from './flow.ts';
+export interface FlowRecipe {
+    id: string;
+    title: string;
+    summary: string;
+    build(overrides?: {
+        id?: string;
+        name?: string;
+    }): Flow;
+}
+export declare const FLOW_RECIPES: readonly FlowRecipe[];
+export declare function findRecipe(id: string): FlowRecipe | undefined;