@protoyard/flows 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dailybot, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# @protoyard/flows
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The framework-agnostic workflow engine for Protoyard
+([ADR-041](../../docs/DECISIONS.md)). A flow is plain, serializable data: how
+a run starts, the steps it takes and what it keeps. Conditions are a closed,
+data-only rule AST. No flow can hold executable JavaScript, a URL, headers or
+a credential, so a flow can never run code or reach a network on its own.
+
+> **Status:** the model (`@protoyard/flows/model`) and the deterministic mock
+> runtime (`@protoyard/flows/runtime`) are available. The Svelte editor and
+> run panels are in [`@protoyard/flows-ui`](../flows-ui/README.md).
+
+## The model
+
+```ts
+import { applyOperations, findRecipe, parseFlow } from '@protoyard/flows';
+
+const flow = findRecipe('approval-request')!.build({ id: 'expense-approvals' });
+const parsed = parseFlow(JSON.parse(untrustedJson)); // { ok, flow?, diagnostics }
+const edited = applyOperations(flow, [{ op: 'set_status', status: 'active' }]);
+```
+
+| Part | What it holds |
+| --- | --- |
+| `Flow` | `{ formatVersion: 1, id, name, description?, status, triggers, steps, collections?, lists?, labels? }` |
+| Triggers | `schedule` (days, `HH:MM`, zone, every N weeks), `manual` (label, who, surfaces, command), `event` (name, source, filter condition), `webhook` (event type and a sample payload; never a secret) |
+| Steps | `ask`, `approval`, `group_people`, `wait`, `wait_until`, `branch` (`when` / `then` / `otherwise`), `message`, `reply`, `assistant`, `save_record`, `get_records`, `set_state`, `pick_from_list`, `update_list`, `call_tool` (a tool id the prototype registers with its service adapter), `start_flow`. Every step can carry `label`, `enabled`, an `only` condition and `delayMinutes`. `STEP_KINDS` lists each type's label, category, output and whether it produces an effect. |
+| References | `DataRef`: `{ from: 'trigger' \| 'record', path? }` or `{ from: 'step', stepId, path? }`. A path is a list of plain segments, and only own properties are read. Text is a string or parts mixing strings and `{ ref }`. |
+| Conditions | `compare` (`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `not_contains`, `starts_with`, `ends_with`, `in`, `not_in`), `test` (`exists`, `missing`, `empty`, `not_empty`, `true`, `false`), `all` / `any` / `not`, and `judge` (a phrase decided by an injected `FlowJudge`) |
+| Operations | `update_flow`, `set_status`, `add_trigger`, `replace_trigger`, `remove_trigger`, `add_step`, `update_step`, `remove_step`, `move_step`, `duplicate_step`, `add_question`, `remove_question`, `upsert_collection`, `remove_collection`, `upsert_list`, `remove_list` |
+| Recipes | `daily-check-in`, `approval-request`, `incoming-triage`, `weekly-digest`, `rotating-host` (`FLOW_RECIPES`, `findRecipe`) |
+
+### Evaluating conditions
+
+`evaluateCondition(condition, { trigger, outputs, record }, { judge? })` is
+pure. It returns `pass`, `fail` or `needs_judgment` with the undecided
+phrases. The logic is three-valued: `all` fails on any failure and `any`
+passes on any pass, whatever the undecided parts say. Numbers and numeric
+strings compare as numbers, and text compares case-insensitively unless
+`caseSensitive` is set. `describeCondition` reads a condition as plain English.
+
+### Validation
+
+`parseFlow(input)` runs three stages:
+
+1. `inspectPlainData` walks the input without recursion. It rejects functions,
+   symbols, class instances, accessors, non-finite numbers and
+   `__proto__` / `constructor` / `prototype` keys, along with anything over the
+   size caps.
+2. The strict zod schema runs next, and unknown keys fail.
+3. `validateFlow` reports what a schema cannot express. Each diagnostic has a
+   severity, a code, a path such as `steps[1].then[0].text` and a step id. The
+   checks:
+   - duplicate ids;
+   - references to unknown steps, or to steps that have not certainly run yet
+     (a step inside a branch arm is not available after the branch);
+   - unknown collections, states and lists;
+   - choice questions with fewer than two options;
+   - `wait_until` with no time or event.
+
+   Warnings cover empty branches, a flow that starts itself, record reads with
+   no collection, and an active flow with nothing enabled.
+
+`applyOperations` is atomic. It validates the operations as untrusted input,
+applies them to a copy, and keeps the result only if the result parses. On
+failure it returns the original flow, the diagnostics and the failing
+operation index. Copies get deterministic ids (`step-copy`, `step-copy-2`, …).
+
+### Limits (`FLOW_LIMITS`)
+
+| Limit | Value |
+| --- | --- |
+| Steps (nested included) | 200 |
+| Branch depth | 8 |
+| Triggers | 8 |
+| Condition depth / parts | 6 / 64 |
+| Questions / choices | 30 / 20 |
+| Audience entries | 50 |
+| Collections / states / lists / list items | 10 / 20 / 10 / 200 |
+| Path segments | 8 |
+| Operations per batch | 200 |
+| Raw depth / values / string length | 48 / 50,000 / 4,000 |
+
+## Mock runtime
+
+```ts
+import { findRecipe, runFlow } from '@protoyard/flows';
+// or: import { runFlow } from '@protoyard/flows/runtime';
+
+const flow = findRecipe('approval-request')!.build({ id: 'expense-approvals' });
+const result = runFlow(flow, {
+  now: '2026-03-15T10:00:00.000Z',
+  seed: 1,
+  trigger: { summary: 'Laptop for Ada Example' },
+  decisions: { approve: 'approved' },
+});
+// result.run.status === 'done'
+// result.effects  → proposed writes for a service adapter
+// result.outbox   → masked delivery log (no network)
+// result.keeps    → records + lists the run produced
+// result.signals  → waiting / approval / failed attention items
+```
+
+| Piece | Role |
+| --- | --- |
+| `runFlow(flow, options)` | One-shot execution; pure w.r.t. inputs (same flow + options → identical result) |
+| `createFlowRuntime(defaults)` | Binds people, tools, seed; each `.run` still takes overrides |
+| `now` / `seed` | Injected clock and deterministic picks (no `Date.now` / `Math.random`) |
+| `answers` / `decisions` | Mock people replies for `ask` / `approval`; missing values leave `waiting` |
+| `tools` | Local handlers only — never `fetch` |
+| `maskUrl` | Host kept; deep path segments and query values become `••••` |
+| `attentionOf` | Open signals ordered for a runs/attention UI |
+
+`wait` advances the mock clock; `wait_until` (except `time`) leaves the run
+waiting. Branch arms use `evaluateCondition`. Assistant steps return scripted
+local results from the task + seed. Nothing is sent to a network.
+
+## Honest limits
+
+- Every trigger and effect is a simulation. A schedule fires from the simulated
+  clock, and `message`, `assistant` and `call_tool` steps become proposed
+  effects for a service adapter. Nothing is sent anywhere.
+- `judge` conditions are never decided by the model itself. Without an
+  injected judge they stay `needs_judgment`.
+- The runtime does not persist rows. A prototype service carries `effects` and
+  `keeps` through `session.assert` → zod → `environment.run` → `db.transaction`.
+
+## Tests
+
+```bash
+pnpm vitest run packages/flows/tests/model.test.ts
+pnpm vitest run packages/flows/tests/runtime.test.ts
+pnpm --filter @protoyard/flows typecheck
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './model/index.ts';
+export * from './runtime/index.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./model/index.js";
+export * from "./runtime/index.js";

package/dist/model/conditions.d.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { type DataRef, type RefScope } from './refs.ts';
+export type Scalar = string | number | boolean | null;
+export type Operand = {
+    ref: DataRef;
+} | {
+    value: Scalar;
+} | {
+    values: Scalar[];
+};
+export declare const COMPARE_OPERATORS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "contains", "not_contains", "starts_with", "ends_with", "in", "not_in"];
+export type CompareOperator = (typeof COMPARE_OPERATORS)[number];
+export declare const VALUE_TESTS: readonly ["exists", "missing", "empty", "not_empty", "true", "false"];
+export type ValueTest = (typeof VALUE_TESTS)[number];
+export type Condition = {
+    type: 'compare';
+    left: Operand;
+    op: CompareOperator;
+    right: Operand;
+    caseSensitive?: boolean;
+} | {
+    type: 'test';
+    subject: DataRef;
+    test: ValueTest;
+} | {
+    type: 'all' | 'any';
+    conditions: Condition[];
+} | {
+    type: 'not';
+    condition: Condition;
+} | {
+    type: 'judge';
+    phrase: string;
+    judge?: string;
+};
+export declare const OperandSchema: z.ZodType<Operand>;
+/** Depth (a leaf is 1) and node count of a condition tree. */
+export declare function conditionStats(condition: Condition): {
+    depth: number;
+    nodes: number;
+};
+/** A condition within the depth and node caps. */
+export declare const ConditionSchema: z.ZodType<Condition>;
+/** Every data reference a condition reads, in document order. */
+export declare function conditionRefs(condition: Condition): DataRef[];
+export interface JudgeRequest {
+    phrase: string;
+    judge: string;
+    scope: RefScope;
+}
+/**
+ * Decides a `judge` node: `true` or `false`, or `null` to leave it undecided.
+ * Must be pure and deterministic for a given request (a simulation, never a
+ * network call).
+ */
+export type FlowJudge = (request: JudgeRequest) => boolean | null;
+export type ConditionOutcome = {
+    status: 'pass';
+} | {
+    status: 'fail';
+} | {
+    status: 'needs_judgment';
+    phrases: string[];
+};
+/**
+ * Evaluates a condition against a run scope with three-valued logic: `all`
+ * fails on any failure, `any` passes on any pass, and an undecided `judge`
+ * leaves the result `needs_judgment` (listing its phrases) only when the
+ * other parts cannot settle it. Pure: no clock, randomness or I/O.
+ */
+export declare function evaluateCondition(condition: Condition, scope?: RefScope, options?: {
+    judge?: FlowJudge;
+}): ConditionOutcome;
+/** A plain-English reading of a condition, for editors and run logs. */
+export declare function describeCondition(condition: Condition): string;

package/dist/model/conditions.js

@@ -0,0 +1,297 @@
+import { z } from 'zod';
+import { FLOW_ID_PATTERN, FLOW_LIMITS } from "./limits.js";
+import { DataRefSchema, describeRef, resolveRef } from "./refs.js";
+export const COMPARE_OPERATORS = [
+    'eq',
+    'neq',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'contains',
+    'not_contains',
+    'starts_with',
+    'ends_with',
+    'in',
+    'not_in',
+];
+export const VALUE_TESTS = ['exists', 'missing', 'empty', 'not_empty', 'true', 'false'];
+const ScalarSchema = z.union([z.string().max(500), z.number().finite(), z.boolean(), z.null()]);
+export const OperandSchema = z.union([
+    z.strictObject({ ref: DataRefSchema }),
+    z.strictObject({ value: ScalarSchema }),
+    z.strictObject({ values: z.array(ScalarSchema).min(1).max(50) }),
+]);
+const ConditionShapeSchema = z.lazy(() => z.discriminatedUnion('type', [
+    z.strictObject({
+        type: z.literal('compare'),
+        left: OperandSchema,
+        op: z.enum(COMPARE_OPERATORS),
+        right: OperandSchema,
+        caseSensitive: z.boolean().optional(),
+    }),
+    z.strictObject({ type: z.literal('test'), subject: DataRefSchema, test: z.enum(VALUE_TESTS) }),
+    z.strictObject({
+        type: z.enum(['all', 'any']),
+        conditions: z.array(ConditionShapeSchema).min(1).max(16),
+    }),
+    z.strictObject({ type: z.literal('not'), condition: ConditionShapeSchema }),
+    z.strictObject({
+        type: z.literal('judge'),
+        phrase: z.string().trim().min(1).max(280),
+        judge: z.string().regex(FLOW_ID_PATTERN).optional(),
+    }),
+]));
+/** Depth (a leaf is 1) and node count of a condition tree. */
+export function conditionStats(condition) {
+    let nodes = 0;
+    const visit = (node, depth) => {
+        nodes += 1;
+        if (node.type === 'all' || node.type === 'any') {
+            return Math.max(depth, ...node.conditions.map((child) => visit(child, depth + 1)));
+        }
+        if (node.type === 'not')
+            return visit(node.condition, depth + 1);
+        return depth;
+    };
+    return { depth: visit(condition, 1), nodes };
+}
+/** A condition within the depth and node caps. */
+export const ConditionSchema = ConditionShapeSchema.superRefine((condition, ctx) => {
+    const { depth, nodes } = conditionStats(condition);
+    if (depth > FLOW_LIMITS.maxConditionDepth) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `Conditions nest at most ${FLOW_LIMITS.maxConditionDepth} levels`,
+        });
+    }
+    if (nodes > FLOW_LIMITS.maxConditionNodes) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `A condition holds at most ${FLOW_LIMITS.maxConditionNodes} parts`,
+        });
+    }
+});
+/** Every data reference a condition reads, in document order. */
+export function conditionRefs(condition) {
+    switch (condition.type) {
+        case 'compare':
+            return [condition.left, condition.right].flatMap((o) => ('ref' in o ? [o.ref] : []));
+        case 'test':
+            return [condition.subject];
+        case 'all':
+        case 'any':
+            return condition.conditions.flatMap(conditionRefs);
+        case 'not':
+            return conditionRefs(condition.condition);
+        case 'judge':
+            return [];
+    }
+}
+const PASS = { status: 'pass' };
+const FAIL = { status: 'fail' };
+function operandValue(operand, scope) {
+    if ('ref' in operand)
+        return resolveRef(operand.ref, scope);
+    if ('value' in operand)
+        return operand.value;
+    return operand.values;
+}
+const isScalar = (value) => value === null || ['string', 'number', 'boolean'].includes(typeof value);
+function asNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+        return Number(value);
+    }
+    return null;
+}
+function same(a, b, caseSensitive) {
+    if (!isScalar(a) || !isScalar(b))
+        return false;
+    const na = asNumber(a);
+    const nb = asNumber(b);
+    if (na !== null && nb !== null)
+        return na === nb;
+    if (typeof a === 'string' && typeof b === 'string' && !caseSensitive) {
+        return a.toLowerCase() === b.toLowerCase();
+    }
+    return a === b;
+}
+const text = (value, caseSensitive) => typeof value === 'string' ? (caseSensitive ? value : value.toLowerCase()) : null;
+function contains(left, right, caseSensitive) {
+    if (Array.isArray(left))
+        return left.some((item) => same(item, right, caseSensitive));
+    const haystack = text(left, caseSensitive);
+    const needle = isScalar(right) && right !== null ? text(String(right), caseSensitive) : null;
+    return haystack !== null && needle !== null && haystack.includes(needle);
+}
+function compare(op, left, right, caseSensitive) {
+    switch (op) {
+        case 'eq':
+            return same(left, right, caseSensitive);
+        case 'neq':
+            return !same(left, right, caseSensitive);
+        case 'gt':
+        case 'gte':
+        case 'lt':
+        case 'lte': {
+            const a = asNumber(left);
+            const b = asNumber(right);
+            if (a === null || b === null)
+                return false;
+            if (op === 'gt')
+                return a > b;
+            if (op === 'gte')
+                return a >= b;
+            if (op === 'lt')
+                return a < b;
+            return a <= b;
+        }
+        case 'contains':
+            return contains(left, right, caseSensitive);
+        case 'not_contains':
+            return !contains(left, right, caseSensitive);
+        case 'starts_with':
+        case 'ends_with': {
+            const a = text(left, caseSensitive);
+            const b = isScalar(right) && right !== null ? text(String(right), caseSensitive) : null;
+            if (a === null || b === null)
+                return false;
+            return op === 'starts_with' ? a.startsWith(b) : a.endsWith(b);
+        }
+        case 'in':
+        case 'not_in': {
+            const list = Array.isArray(right) ? right : [right];
+            const found = list.some((item) => same(left, item, caseSensitive));
+            return op === 'in' ? found : !found;
+        }
+    }
+}
+function isEmpty(value) {
+    if (value === undefined || value === null || value === '')
+        return true;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length === 0;
+    return false;
+}
+function runTest(test, value) {
+    switch (test) {
+        case 'exists':
+            return value !== undefined && value !== null;
+        case 'missing':
+            return value === undefined || value === null;
+        case 'empty':
+            return isEmpty(value);
+        case 'not_empty':
+            return !isEmpty(value);
+        case 'true':
+            return value === true;
+        case 'false':
+            return value === false;
+    }
+}
+/**
+ * Evaluates a condition against a run scope with three-valued logic: `all`
+ * fails on any failure, `any` passes on any pass, and an undecided `judge`
+ * leaves the result `needs_judgment` (listing its phrases) only when the
+ * other parts cannot settle it. Pure: no clock, randomness or I/O.
+ */
+export function evaluateCondition(condition, scope = {}, options = {}) {
+    switch (condition.type) {
+        case 'compare': {
+            const left = operandValue(condition.left, scope);
+            const right = operandValue(condition.right, scope);
+            return compare(condition.op, left, right, condition.caseSensitive === true) ? PASS : FAIL;
+        }
+        case 'test':
+            return runTest(condition.test, resolveRef(condition.subject, scope)) ? PASS : FAIL;
+        case 'not': {
+            const inner = evaluateCondition(condition.condition, scope, options);
+            if (inner.status === 'needs_judgment')
+                return inner;
+            return inner.status === 'pass' ? FAIL : PASS;
+        }
+        case 'all':
+        case 'any': {
+            const decisive = condition.type === 'all' ? 'fail' : 'pass';
+            const phrases = [];
+            for (const child of condition.conditions) {
+                const outcome = evaluateCondition(child, scope, options);
+                if (outcome.status === decisive)
+                    return outcome;
+                if (outcome.status === 'needs_judgment')
+                    phrases.push(...outcome.phrases);
+            }
+            if (phrases.length > 0)
+                return { status: 'needs_judgment', phrases };
+            return condition.type === 'all' ? PASS : FAIL;
+        }
+        case 'judge': {
+            const decided = options.judge?.({
+                phrase: condition.phrase,
+                judge: condition.judge ?? 'assistant',
+                scope,
+            });
+            if (decided === true)
+                return PASS;
+            if (decided === false)
+                return FAIL;
+            return { status: 'needs_judgment', phrases: [condition.phrase] };
+        }
+    }
+}
+/* ---------- reading ---------- */
+const OPERATOR_LABELS = {
+    eq: 'is',
+    neq: 'is not',
+    gt: 'is more than',
+    gte: 'is at least',
+    lt: 'is less than',
+    lte: 'is at most',
+    contains: 'contains',
+    not_contains: 'does not contain',
+    starts_with: 'starts with',
+    ends_with: 'ends with',
+    in: 'is one of',
+    not_in: 'is not one of',
+};
+const TEST_LABELS = {
+    exists: 'is set',
+    missing: 'is not set',
+    empty: 'is empty',
+    not_empty: 'has something in it',
+    true: 'is yes',
+    false: 'is no',
+};
+function describeOperand(operand) {
+    if ('ref' in operand)
+        return describeRef(operand.ref);
+    if ('value' in operand)
+        return JSON.stringify(operand.value);
+    return operand.values.map((v) => JSON.stringify(v)).join(', ');
+}
+/** A plain-English reading of a condition, for editors and run logs. */
+export function describeCondition(condition) {
+    switch (condition.type) {
+        case 'compare':
+            return `${describeOperand(condition.left)} ${OPERATOR_LABELS[condition.op]} ${describeOperand(condition.right)}`;
+        case 'test':
+            return `${describeRef(condition.subject)} ${TEST_LABELS[condition.test]}`;
+        case 'all':
+        case 'any': {
+            const joiner = condition.type === 'all' ? ' and ' : ' or ';
+            const parts = condition.conditions.map((child) => {
+                const inner = describeCondition(child);
+                return child.type === 'all' || child.type === 'any' ? `(${inner})` : inner;
+            });
+            return parts.join(joiner);
+        }
+        case 'not':
+            return `not (${describeCondition(condition.condition)})`;
+        case 'judge':
+            return condition.phrase;
+    }
+}

package/dist/model/data.d.ts

@@ -0,0 +1,14 @@
+/** Keys that could reach an object prototype if a consumer ever merged them. */
+export declare const FORBIDDEN_KEYS: ReadonlySet<string>;
+export interface DataProblem {
+    path: string;
+    message: string;
+}
+/**
+ * Walks untrusted input without recursion and reports the first problem: a
+ * value JSON cannot hold (function, symbol, bigint, class instance, non-finite
+ * number), a forbidden key, a string over the cap, or a structure too deep or
+ * too large. A flow that passes holds plain data only, so nothing in it can
+ * ever be called.
+ */
+export declare function inspectPlainData(input: unknown): DataProblem | null;

package/dist/model/data.js

@@ -0,0 +1,73 @@
+import { FLOW_LIMITS } from "./limits.js";
+/** Keys that could reach an object prototype if a consumer ever merged them. */
+export const FORBIDDEN_KEYS = new Set([
+    '__proto__',
+    'constructor',
+    'prototype',
+]);
+const pointer = (path) => path.length === 0
+    ? '$'
+    : `$${path.map((p) => (typeof p === 'number' ? `[${p}]` : `.${p}`)).join('')}`;
+const isPlainObject = (value) => {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+};
+/**
+ * Walks untrusted input without recursion and reports the first problem: a
+ * value JSON cannot hold (function, symbol, bigint, class instance, non-finite
+ * number), a forbidden key, a string over the cap, or a structure too deep or
+ * too large. A flow that passes holds plain data only, so nothing in it can
+ * ever be called.
+ */
+export function inspectPlainData(input) {
+    const stack = [
+        { value: input, path: [], depth: 0 },
+    ];
+    let nodes = 0;
+    while (stack.length > 0) {
+        const { value, path, depth } = stack.pop();
+        nodes += 1;
+        if (nodes > FLOW_LIMITS.maxDataNodes) {
+            return { path: pointer(path), message: `More than ${FLOW_LIMITS.maxDataNodes} values` };
+        }
+        if (depth > FLOW_LIMITS.maxDataDepth) {
+            return { path: pointer(path), message: `Nested deeper than ${FLOW_LIMITS.maxDataDepth}` };
+        }
+        if (value === null || typeof value === 'boolean')
+            continue;
+        if (typeof value === 'string') {
+            if (value.length > FLOW_LIMITS.maxStringLength) {
+                return { path: pointer(path), message: `Text longer than ${FLOW_LIMITS.maxStringLength}` };
+            }
+            continue;
+        }
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                return { path: pointer(path), message: 'Not a finite number' };
+            continue;
+        }
+        if (typeof value !== 'object') {
+            return { path: pointer(path), message: `A ${typeof value} is not plain data` };
+        }
+        if (Array.isArray(value)) {
+            for (const [i, item] of value.entries()) {
+                stack.push({ value: item, path: [...path, i], depth: depth + 1 });
+            }
+            continue;
+        }
+        if (!isPlainObject(value))
+            return { path: pointer(path), message: 'Not a plain object' };
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key === 'symbol')
+                return { path: pointer(path), message: 'Symbol keys are not data' };
+            if (FORBIDDEN_KEYS.has(key))
+                return { path: pointer([...path, key]), message: `Key "${key}" is not allowed` };
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor && !('value' in descriptor)) {
+                return { path: pointer([...path, key]), message: 'Accessors are not data' };
+            }
+            stack.push({ value: descriptor?.value, path: [...path, key], depth: depth + 1 });
+        }
+    }
+    return null;
+}

package/dist/model/flow.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { type Step } from './steps.ts';
+import { type Trigger } from './triggers.ts';
+import { type FlowDiagnostic } from './validate.ts';
+export declare const FLOW_FORMAT_VERSION = 1;
+export declare const FLOW_STATUSES: readonly ["draft", "active", "paused"];
+export type FlowStatus = (typeof FLOW_STATUSES)[number];
+export declare const CollectionSchema: 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>;
+export type FlowCollection = z.infer<typeof CollectionSchema>;
+export declare const ListSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    items: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type FlowList = z.infer<typeof ListSchema>;
+/** A serializable workflow: how it starts, what it does, and what it keeps. */
+export interface Flow {
+    formatVersion: 1;
+    id: string;
+    name: string;
+    description?: string;
+    status: FlowStatus;
+    triggers: Trigger[];
+    steps: Step[];
+    collections?: FlowCollection[];
+    lists?: FlowList[];
+    labels?: string[];
+}
+export declare const FlowSchema: z.ZodType<Flow>;
+export type ParseFlowResult = {
+    ok: true;
+    flow: Flow;
+    diagnostics: FlowDiagnostic[];
+} | {
+    ok: false;
+    diagnostics: FlowDiagnostic[];
+};
+/**
+ * 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 declare function parseFlow(input: unknown): ParseFlowResult;