@protoyard/flows 0.0.0-stage → 1.1.0

package/dist/model/steps.js

@@ -0,0 +1,206 @@
+import { z } from 'zod';
+import { ConditionSchema } from "./conditions.js";
+import { FLOW_ID_PATTERN, FLOW_LIMITS } from "./limits.js";
+import { DataRefSchema, FlowIdSchema } from "./refs.js";
+import { AudienceSchema, FlowTextSchema } from "./text.js";
+import { TimeOfDaySchema } from "./triggers.js";
+/*
+ * The step catalog. Every step is plain data that a runtime turns into a
+ * proposed effect for a service adapter (ADR-041): there is no step that
+ * holds code, a URL, headers or credentials, so a flow can never execute
+ * JavaScript or reach a network on its own.
+ */
+const MINUTES_PER_YEAR = 525_600;
+const common = {
+    id: FlowIdSchema,
+    /** A display name that wins over the derived sentence. */
+    label: z.string().trim().min(1).max(120).optional(),
+    /** Absent means enabled. */
+    enabled: z.boolean().optional(),
+    /** "Only if": the step is skipped when this fails. */
+    only: ConditionSchema.optional(),
+    /** Simulated minutes to wait before the step starts. */
+    delayMinutes: z.number().int().min(0).max(MINUTES_PER_YEAR).optional(),
+};
+export const QUESTION_KINDS = ['text', 'choice', 'boolean', 'number'];
+export const QuestionSchema = z.strictObject({
+    id: FlowIdSchema,
+    kind: z.enum(QUESTION_KINDS),
+    prompt: z.string().trim().min(1).max(500),
+    required: z.boolean().optional(),
+    choices: z.array(z.string().trim().min(1).max(120)).max(FLOW_LIMITS.maxChoices).optional(),
+});
+const fieldsSchema = z
+    .record(z.string().regex(FLOW_ID_PATTERN, 'Field names are lowercase slugs'), FlowTextSchema)
+    .refine((fields) => Object.keys(fields).length <= 30, 'At most 30 fields');
+const LEAF_STEP_SCHEMAS = [
+    z.strictObject({
+        ...common,
+        type: z.literal('ask'),
+        audience: AudienceSchema.min(1, 'Ask someone'),
+        questions: z.array(QuestionSchema).min(1, 'Add a question').max(FLOW_LIMITS.maxQuestions),
+        deadlineMinutes: z.number().int().min(1).max(MINUTES_PER_YEAR).optional(),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('approval'),
+        approvers: AudienceSchema.min(1, 'Choose who approves'),
+        prompt: FlowTextSchema,
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('wait'),
+        minutes: z.number().int().min(1).max(MINUTES_PER_YEAR),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('wait_until'),
+        until: z.enum(['replies', 'approval', 'event', 'time']),
+        time: TimeOfDaySchema.optional(),
+        event: z
+            .string()
+            .regex(/^[a-z][a-z0-9_.:-]{0,63}$/)
+            .optional(),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('message'),
+        channel: z.enum(['chat', 'email', 'inbox', 'notification']),
+        to: AudienceSchema.min(1, 'Choose who gets it'),
+        subject: z.string().trim().min(1).max(200).optional(),
+        text: FlowTextSchema,
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('reply'),
+        text: FlowTextSchema,
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('assistant'),
+        task: z.enum(['summarize', 'classify', 'extract', 'draft', 'check']),
+        input: DataRefSchema.optional(),
+        instructions: FlowTextSchema.optional(),
+        labels: z.array(z.string().trim().min(1).max(60)).max(20).optional(),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('save_record'),
+        collection: FlowIdSchema,
+        title: FlowTextSchema.optional(),
+        fields: fieldsSchema.optional(),
+        state: FlowIdSchema.optional(),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('get_records'),
+        collection: FlowIdSchema,
+        sinceDays: z.number().int().min(1).max(366),
+        limit: z.number().int().min(1).max(500),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('set_state'),
+        state: FlowIdSchema,
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('pick_from_list'),
+        list: FlowIdSchema,
+        order: z.enum(['next_unused', 'seeded']),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('update_list'),
+        list: FlowIdSchema,
+        action: z.enum(['add', 'remove']),
+        value: FlowTextSchema,
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('group_people'),
+        from: AudienceSchema.min(1, 'Choose who to group'),
+        mode: z.enum(['pairs', 'groups', 'pick_one']),
+        size: z.number().int().min(2).max(20).optional(),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('call_tool'),
+        /** A tool the prototype registers with its service adapter, by id. */
+        tool: FlowIdSchema,
+        action: FlowIdSchema,
+        input: fieldsSchema.optional(),
+    }),
+    z.strictObject({
+        ...common,
+        type: z.literal('start_flow'),
+        flowId: FlowIdSchema,
+    }),
+];
+export const StepSchema = z.lazy(() => z.discriminatedUnion('type', [
+    ...LEAF_STEP_SCHEMAS,
+    z.strictObject({
+        ...common,
+        type: z.literal('branch'),
+        when: ConditionSchema,
+        // biome-ignore lint/suspicious/noThenProperty: a branch arm, not a thenable
+        then: z.array(StepSchema).max(FLOW_LIMITS.maxSteps),
+        otherwise: z.array(StepSchema).max(FLOW_LIMITS.maxSteps),
+    }),
+]));
+/** One entry per step type, in editor order. */
+export const STEP_KINDS = [
+    { type: 'ask', label: 'Ask questions', category: 'people', output: 'replies', effect: true },
+    {
+        type: 'approval',
+        label: 'Ask for approval',
+        category: 'people',
+        output: 'decision',
+        effect: true,
+    },
+    {
+        type: 'group_people',
+        label: 'Group people',
+        category: 'people',
+        output: 'group',
+        effect: false,
+    },
+    { type: 'wait', label: 'Wait', category: 'timing', output: 'none', effect: false },
+    { type: 'wait_until', label: 'Wait until', category: 'timing', output: 'none', effect: false },
+    { type: 'branch', label: 'If / otherwise', category: 'logic', output: 'none', effect: false },
+    { type: 'message', label: 'Send a message', category: 'messages', output: 'none', effect: true },
+    { type: 'reply', label: 'Reply', category: 'messages', output: 'none', effect: true },
+    { type: 'assistant', label: 'Assistant task', category: 'tools', output: 'text', effect: false },
+    {
+        type: 'save_record',
+        label: 'Save a record',
+        category: 'data',
+        output: 'records',
+        effect: true,
+    },
+    { type: 'get_records', label: 'Get records', category: 'data', output: 'records', effect: false },
+    { type: 'set_state', label: 'Change state', category: 'data', output: 'none', effect: true },
+    {
+        type: 'pick_from_list',
+        label: 'Pick from a list',
+        category: 'data',
+        output: 'item',
+        effect: true,
+    },
+    { type: 'update_list', label: 'Update a list', category: 'data', output: 'none', effect: true },
+    { type: 'call_tool', label: 'Use a tool', category: 'tools', output: 'text', effect: true },
+    {
+        type: 'start_flow',
+        label: 'Start another flow',
+        category: 'tools',
+        output: 'none',
+        effect: true,
+    },
+];
+export const STEP_TYPES = STEP_KINDS.map((kind) => kind.type);
+export function stepKind(type) {
+    return STEP_KINDS.find((kind) => kind.type === type);
+}
+export function isStepEnabled(step) {
+    return step.enabled !== false;
+}

package/dist/model/text.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { type DataRef } from './refs.ts';
+/** Text people read: a string, or parts where a part is a string or a reference. */
+export type FlowText = string | (string | {
+    ref: DataRef;
+})[];
+export declare const FlowTextSchema: z.ZodType<FlowText>;
+/** Every reference a text interpolates. */
+export declare function textRefs(value: FlowText | undefined): DataRef[];
+/** The text with each reference shown as `{label}`, for editors and previews. */
+export declare function textPreview(value: FlowText | undefined): string;
+export declare const AUDIENCE_TYPES: readonly ["person", "team", "role", "channel", "list", "everyone"];
+/** Who a step addresses. Names are display copy; ids point at fictional data. */
+export interface AudienceItem {
+    type: (typeof AUDIENCE_TYPES)[number];
+    id: string;
+    name: string;
+}
+export declare const AudienceSchema: z.ZodArray<z.ZodObject<{
+    type: z.ZodEnum<{
+        person: "person";
+        team: "team";
+        role: "role";
+        channel: "channel";
+        list: "list";
+        everyone: "everyone";
+    }>;
+    id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>>;

package/dist/model/text.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { FLOW_ID_PATTERN, FLOW_LIMITS } from "./limits.js";
+import { DataRefSchema, describeRef } from "./refs.js";
+export const FlowTextSchema = z.union([
+    z.string().max(2_000),
+    z
+        .array(z.union([z.string().max(2_000), z.strictObject({ ref: DataRefSchema })]))
+        .max(FLOW_LIMITS.maxTextParts),
+]);
+/** Every reference a text interpolates. */
+export function textRefs(value) {
+    if (value === undefined || typeof value === 'string')
+        return [];
+    return value.flatMap((part) => (typeof part === 'string' ? [] : [part.ref]));
+}
+/** The text with each reference shown as `{label}`, for editors and previews. */
+export function textPreview(value) {
+    if (value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    return value
+        .map((part) => (typeof part === 'string' ? part : `{${describeRef(part.ref)}}`))
+        .join('');
+}
+export const AUDIENCE_TYPES = ['person', 'team', 'role', 'channel', 'list', 'everyone'];
+export const AudienceSchema = z
+    .array(z.strictObject({
+    type: z.enum(AUDIENCE_TYPES),
+    id: z.string().regex(FLOW_ID_PATTERN),
+    name: z.string().trim().min(1).max(120),
+}))
+    .max(FLOW_LIMITS.maxAudience);

package/dist/model/triggers.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { type Condition } from './conditions.ts';
+import { type AudienceItem } from './text.ts';
+export declare const DAYS: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+export type Day = (typeof DAYS)[number];
+/** `HH:MM` on a 24-hour clock. */
+export declare const TimeOfDaySchema: z.ZodString;
+export declare const SURFACES: readonly ["app", "chat", "command", "link"];
+export declare const EVENT_SOURCES: readonly ["records", "people", "app", "integration"];
+/**
+ * How a run starts. Every start is simulated: a schedule fires from the
+ * simulated clock, a manual start from a button, an event or a webhook from a
+ * scenario. A webhook carries a sample payload, never a secret.
+ */
+export type Trigger = {
+    id: string;
+    type: 'schedule';
+    days: Day[];
+    time: string;
+    timezone: string;
+    everyWeeks?: number;
+} | {
+    id: string;
+    type: 'manual';
+    label: string;
+    who?: AudienceItem[];
+    surfaces?: (typeof SURFACES)[number][];
+    command?: string;
+} | {
+    id: string;
+    type: 'event';
+    event: string;
+    source?: (typeof EVENT_SOURCES)[number];
+    filter?: Condition;
+} | {
+    id: string;
+    type: 'webhook';
+    eventType: string;
+    samplePayload?: Record<string, unknown>;
+};
+export type TriggerType = Trigger['type'];
+export declare const TriggerSchema: z.ZodType<Trigger>;

package/dist/model/triggers.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { ConditionSchema } from "./conditions.js";
+import { FORBIDDEN_KEYS } from "./data.js";
+import { FlowIdSchema } from "./refs.js";
+import { AudienceSchema } from "./text.js";
+export const DAYS = [
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+    'sunday',
+];
+/** `HH:MM` on a 24-hour clock. */
+export const TimeOfDaySchema = z.string().regex(/^(?:[01]\d|2[0-3]):[0-5]\d$/, 'Use HH:MM');
+/** `local`, `utc` or an IANA-style zone name such as `America/Bogota`. */
+const TimezoneSchema = z
+    .string()
+    .regex(/^(?:local|utc|[A-Z][A-Za-z_]+(?:\/[A-Za-z0-9_+-]+){1,2})$/, 'Use local, utc or a zone name');
+export const SURFACES = ['app', 'chat', 'command', 'link'];
+export const EVENT_SOURCES = ['records', 'people', 'app', 'integration'];
+const EventNameSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9_.:-]{0,63}$/, 'Use a lowercase event name such as record.created');
+export const TriggerSchema = z.discriminatedUnion('type', [
+    z.strictObject({
+        id: FlowIdSchema,
+        type: z.literal('schedule'),
+        days: z
+            .array(z.enum(DAYS))
+            .min(1, 'Pick at least one day')
+            .max(7)
+            .refine((days) => new Set(days).size === days.length, 'Each day appears once'),
+        time: TimeOfDaySchema,
+        timezone: TimezoneSchema,
+        everyWeeks: z.number().int().min(1).max(12).optional(),
+    }),
+    z.strictObject({
+        id: FlowIdSchema,
+        type: z.literal('manual'),
+        label: z.string().trim().min(1).max(80),
+        who: AudienceSchema.optional(),
+        surfaces: z.array(z.enum(SURFACES)).min(1).max(SURFACES.length).optional(),
+        command: z
+            .string()
+            .regex(/^[a-z0-9][a-z0-9_-]{0,30}$/, 'Commands use lowercase letters, digits, - and _')
+            .optional(),
+    }),
+    z.strictObject({
+        id: FlowIdSchema,
+        type: z.literal('event'),
+        event: EventNameSchema,
+        source: z.enum(EVENT_SOURCES).optional(),
+        filter: ConditionSchema.optional(),
+    }),
+    z.strictObject({
+        id: FlowIdSchema,
+        type: z.literal('webhook'),
+        eventType: EventNameSchema,
+        samplePayload: z
+            .record(z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,64}$/)
+            .refine((key) => !FORBIDDEN_KEYS.has(key), 'This key is not allowed'), z.unknown())
+            .optional(),
+    }),
+]);

package/dist/model/validate.d.ts

@@ -0,0 +1,19 @@
+import type { Flow } from './flow.ts';
+export type FlowDiagnosticCode = 'not_plain_data' | 'schema' | 'duplicate_id' | 'unknown_step_ref' | 'ref_not_before' | 'record_ref_without_collection' | 'unknown_collection' | 'unknown_state' | 'unknown_list' | 'choice_without_options' | 'options_on_non_choice' | 'missing_wait_detail' | 'empty_branch' | 'starts_itself' | 'nothing_to_run';
+export interface FlowDiagnostic {
+    severity: 'error' | 'warning';
+    code: FlowDiagnosticCode;
+    /** Where it applies: `steps[0].then[1].only`, `triggers[0]` or `$`. */
+    path: string;
+    message: string;
+    stepId?: string;
+}
+/**
+ * The semantic checks a schema cannot express: unique ids, references that
+ * point at steps which have certainly run, collections, states and lists that
+ * exist, and shapes that parse but cannot work. Pure and deterministic; the
+ * result is ordered by where each problem sits.
+ */
+export declare function validateFlow(flow: Flow): FlowDiagnostic[];
+/** Diagnostics grouped by step id (`$flow` for the ones that belong to no step). */
+export declare function diagnosticsByStep(diagnostics: readonly FlowDiagnostic[]): Record<string, FlowDiagnostic[]>;

package/dist/model/validate.js

@@ -0,0 +1,207 @@
+import { conditionRefs } from "./conditions.js";
+import { isStepEnabled } from "./steps.js";
+import { textRefs } from "./text.js";
+import { formatPath, listSteps, runsBefore } from "./walk.js";
+/** Every reference a step reads, with where it sits inside the step. */
+function stepRefs(step) {
+    const out = [];
+    const add = (refs, at) => {
+        for (const ref of refs)
+            out.push({ ref, at });
+    };
+    if (step.only)
+        add(conditionRefs(step.only), ['only']);
+    switch (step.type) {
+        case 'branch':
+            add(conditionRefs(step.when), ['when']);
+            break;
+        case 'approval':
+            add(textRefs(step.prompt), ['prompt']);
+            break;
+        case 'message':
+        case 'reply':
+            add(textRefs(step.text), ['text']);
+            break;
+        case 'assistant':
+            if (step.input)
+                add([step.input], ['input']);
+            add(textRefs(step.instructions), ['instructions']);
+            break;
+        case 'save_record':
+            add(textRefs(step.title), ['title']);
+            for (const [field, value] of Object.entries(step.fields ?? {}))
+                add(textRefs(value), ['fields', field]);
+            break;
+        case 'update_list':
+            add(textRefs(step.value), ['value']);
+            break;
+        case 'call_tool':
+            for (const [field, value] of Object.entries(step.input ?? {}))
+                add(textRefs(value), ['input', field]);
+            break;
+        default:
+            break;
+    }
+    return out;
+}
+function duplicates(ids) {
+    const seen = new Set();
+    const dup = new Set();
+    for (const id of ids)
+        (seen.has(id) ? dup : seen).add(id);
+    return dup;
+}
+/**
+ * The semantic checks a schema cannot express: unique ids, references that
+ * point at steps which have certainly run, collections, states and lists that
+ * exist, and shapes that parse but cannot work. Pure and deterministic; the
+ * result is ordered by where each problem sits.
+ */
+export function validateFlow(flow) {
+    const out = [];
+    const push = (d) => out.push(d);
+    const all = listSteps(flow.steps);
+    const order = new Map();
+    const byId = new Map();
+    for (const [i, location] of all.entries()) {
+        if (!order.has(location.step.id))
+            order.set(location.step.id, i);
+        if (!byId.has(location.step.id))
+            byId.set(location.step.id, location);
+    }
+    const dupSteps = duplicates(all.map((l) => l.step.id));
+    const reported = new Set();
+    for (const location of all) {
+        if (dupSteps.has(location.step.id) && reported.has(location.step.id)) {
+            push({
+                severity: 'error',
+                code: 'duplicate_id',
+                path: formatPath(location.path),
+                stepId: location.step.id,
+                message: `Another step already uses the id "${location.step.id}"`,
+            });
+        }
+        reported.add(location.step.id);
+    }
+    for (const id of duplicates(flow.triggers.map((t) => t.id))) {
+        const index = flow.triggers.findLastIndex((t) => t.id === id);
+        push({
+            severity: 'error',
+            code: 'duplicate_id',
+            path: `triggers[${index}]`,
+            message: `Another start already uses the id "${id}"`,
+        });
+    }
+    for (const [key, list] of [
+        ['collections', flow.collections ?? []],
+        ['lists', flow.lists ?? []],
+    ]) {
+        for (const id of duplicates(list.map((item) => item.id))) {
+            const index = list.findLastIndex((item) => item.id === id);
+            push({
+                severity: 'error',
+                code: 'duplicate_id',
+                path: `${key}[${index}]`,
+                message: `The id "${id}" is used twice`,
+            });
+        }
+    }
+    const collections = new Map((flow.collections ?? []).map((c) => [c.id, c]));
+    const states = new Set((flow.collections ?? []).flatMap((c) => c.states.map((s) => s.id)));
+    const lists = new Set((flow.lists ?? []).map((l) => l.id));
+    const recordTrigger = flow.triggers.some((t) => t.type === 'event' && t.source === 'records');
+    for (const location of all) {
+        const { step } = location;
+        const at = (...rest) => formatPath([...location.path, ...rest]);
+        const stepDiag = (severity, code, path, message) => push({ severity, code, path, message, stepId: step.id });
+        for (const { ref, at: inner } of stepRefs(step)) {
+            if (ref.from === 'step') {
+                const source = byId.get(ref.stepId);
+                if (!source) {
+                    stepDiag('error', 'unknown_step_ref', at(...inner), `No step has the id "${ref.stepId}"`);
+                }
+                else if (!runsBefore(source, location, order)) {
+                    stepDiag('error', 'ref_not_before', at(...inner), `Step "${ref.stepId}" has not certainly run before this step`);
+                }
+            }
+            else if (ref.from === 'record' && collections.size === 0 && !recordTrigger) {
+                stepDiag('warning', 'record_ref_without_collection', at(...inner), 'This reads a record, but the flow keeps no records');
+            }
+        }
+        switch (step.type) {
+            case 'ask':
+                for (const [i, question] of step.questions.entries()) {
+                    if (question.kind === 'choice' && (question.choices?.length ?? 0) < 2) {
+                        stepDiag('error', 'choice_without_options', at('questions', i), 'A choice question needs at least two options');
+                    }
+                    if (question.kind !== 'choice' && question.choices?.length) {
+                        stepDiag('warning', 'options_on_non_choice', at('questions', i, 'choices'), 'Options only apply to choice questions');
+                    }
+                }
+                for (const id of duplicates(step.questions.map((q) => q.id))) {
+                    stepDiag('error', 'duplicate_id', at('questions'), `Two questions use the id "${id}"`);
+                }
+                break;
+            case 'save_record':
+            case 'get_records':
+                if (!collections.has(step.collection)) {
+                    stepDiag('error', 'unknown_collection', at('collection'), `No collection has the id "${step.collection}"`);
+                }
+                else if (step.type === 'save_record' && step.state) {
+                    const known = collections.get(step.collection)?.states.some((s) => s.id === step.state);
+                    if (!known)
+                        stepDiag('error', 'unknown_state', at('state'), `"${step.collection}" has no state "${step.state}"`);
+                }
+                break;
+            case 'set_state':
+                if (!states.has(step.state)) {
+                    stepDiag('error', 'unknown_state', at('state'), `No collection has the state "${step.state}"`);
+                }
+                break;
+            case 'pick_from_list':
+            case 'update_list':
+                if (!lists.has(step.list)) {
+                    stepDiag('error', 'unknown_list', at('list'), `No list has the id "${step.list}"`);
+                }
+                break;
+            case 'wait_until':
+                if (step.until === 'time' && !step.time) {
+                    stepDiag('error', 'missing_wait_detail', at('time'), 'Choose the time to wait for');
+                }
+                if (step.until === 'event' && !step.event) {
+                    stepDiag('error', 'missing_wait_detail', at('event'), 'Choose the event to wait for');
+                }
+                break;
+            case 'branch':
+                if (step.then.length === 0 && step.otherwise.length === 0) {
+                    stepDiag('warning', 'empty_branch', at(), 'Neither side of this branch does anything');
+                }
+                break;
+            case 'start_flow':
+                if (step.flowId === flow.id) {
+                    stepDiag('warning', 'starts_itself', at('flowId'), 'This flow starts itself; runs may repeat');
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    if (flow.status === 'active' && !all.some((l) => isStepEnabled(l.step))) {
+        push({
+            severity: 'warning',
+            code: 'nothing_to_run',
+            path: 'steps',
+            message: 'An active flow has no enabled step',
+        });
+    }
+    return out;
+}
+/** Diagnostics grouped by step id (`$flow` for the ones that belong to no step). */
+export function diagnosticsByStep(diagnostics) {
+    const map = {};
+    for (const d of diagnostics) {
+        const key = d.stepId ?? '$flow';
+        map[key] = [...(map[key] ?? []), d];
+    }
+    return map;
+}

package/dist/model/walk.d.ts

@@ -0,0 +1,40 @@
+import type { Step } from './steps.ts';
+export type BranchArm = 'then' | 'otherwise';
+export type PathSegment = string | number;
+/** Where a step sits in the tree. */
+export interface StepLocation {
+    step: Step;
+    /** From the flow root, for diagnostics: `['steps', 0, 'then', 1]`. */
+    path: PathSegment[];
+    parentId: string | null;
+    branch: BranchArm | null;
+    index: number;
+    /** 0 for a top-level step. */
+    depth: number;
+    /** The branch arms the step is inside, outermost first (`branchId:arm`). */
+    arms: string[];
+}
+/** The arms of a step, empty for anything but a branch. */
+export declare function childArms(step: Step): {
+    branch: BranchArm;
+    steps: Step[];
+}[];
+/** Visits every step in document (pre-)order, which is also run order. */
+export declare function walkSteps(steps: readonly Step[], visit: (location: StepLocation) => void, parent?: {
+    id: string;
+    branch: BranchArm;
+    path: PathSegment[];
+    depth: number;
+    arms: string[];
+} | null): void;
+export declare function listSteps(steps: readonly Step[]): StepLocation[];
+export declare function findStep(steps: readonly Step[], stepId: string): StepLocation | null;
+/**
+ * True when `earlier` has certainly run by the time `later` starts: it comes
+ * first in run order and is not inside a branch arm that `later` is outside of.
+ */
+export declare function runsBefore(earlier: StepLocation, later: StepLocation, order: Map<string, number>): boolean;
+/** The steps whose output a step may reference. */
+export declare function stepsBefore(steps: readonly Step[], stepId: string): Step[];
+/** `['steps', 0, 'then', 1]` → `steps[0].then[1]`. */
+export declare function formatPath(path: readonly PathSegment[]): string;