@octaviaflow/flow-rules

The flow action catalog and the rules engine behind Flow Doctor — the two things that decide what a step accepts and whether a flow works.

Why this exists

Both lived in octaviaflow-ui, so both were reachable only from a browser. That was fine while the editor was the only thing building flows. It stopped being fine when an AI agent became a second author (DEV-391):

• an agent that cannot read an action's inputSchema guesses at the config, and a guessed config is a flow that fails at run time on the customer's live systems;
• an agent that cannot run the rules cannot tell whether what it built works, so it reports success and hands over a broken flow.

Copying either into Backend would have produced two rule sets that agree on the day they are written — the same failure mode as a duplicated permission predicate, and the copy that drifts would be the one the agent trusts.

So they live here, and both the editor and the server import them. The editor keeps validating in-process on every structural canvas change; Backend gets the identical verdict for check_flow.

What is and is not here

Here: the ActionDefinition catalog (ids, descriptions, inputSchema, outputSchema), the workflow validator, node config status, and the id generators, so a caller building a flow makes ids the editor recognises.

Not here: React. The config panels stay in octaviaflow-ui — a component in this package would make it unusable from Backend, which is the whole point. ActionDefinition.icon is a string key the consumer's catalog adapter resolves; this package never names a component.

Usage

import {
  getAllActions,
  getActionById,
  validateWorkflow,
  getNodeConfigStatus,
} from "@octaviaflow/flow-rules";

// What may this step be configured with?
const action = getActionById("http_request");
const required = action?.inputSchema.fields.filter((f) => f.validation?.required);

// Does this flow work?
const { isValid, errors, warnings } = validateWorkflow(nodes, edges);

The severity contract

Unchanged from rules-v2 (DEV-220, ADR-flow-pause-and-rules-v2):

| | | |---|---| | error | the flow cannot work as built. Blocks activation. | | warning | it will run, but probably not the way the author thinks. Blocks nothing. |

Saving is never blocked. A caller that treats a warning as a failure will refuse flows the editor accepts.

One field name worth knowing

A node names its action with actionDefinitionId, not actionId. The latter looks right and silently matches nothing — which is exactly the kind of mistake this package exists to stop an agent making.

Commands

bun install
bun test
bun run typecheck
bun run build      # tsc → dist (ESM + .d.ts), which is what consumers get

It ships built ESM plus declarations rather than raw TypeScript (@octaviaflow/connector-crypto ships source, but that package is only consumed by Bun services — octaviaflow-ui is Next.js and would need transpilePackages for source).

Consumers

| Repo | Uses | |---|---| | octaviaflow-ui | the editor: catalog, live validation, node status badges | | Octaviaflow-Backend | check_flow and the agent authoring routes it serves | | Octaviaflow-MCP | indirectly, through Backend |

A change to a rule or an action schema changes what the agent may build. Run both consumers' suites before publishing.