@protoyard/flows 0.0.0-stage → 1.1.0

package/dist/runtime/seed.js

@@ -0,0 +1,45 @@
+/** Small deterministic helpers (no Math.random, no Date.now). */
+export function hashSeed(seed) {
+    if (typeof seed === 'number' && Number.isFinite(seed)) {
+        return seed >>> 0;
+    }
+    const text = seed === undefined ? 'flows' : String(seed);
+    let h = 2166136261;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/** Mulberry32 — same stream for the same seed. */
+export function createRng(seed) {
+    let state = hashSeed(seed) || 1;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+export function createIdFactory(seed) {
+    const prefixSeed = hashSeed(seed).toString(36);
+    let n = 0;
+    return (prefix) => {
+        n += 1;
+        return `${prefix}_${prefixSeed}_${String(n).padStart(4, '0')}`;
+    };
+}
+/** Fisher–Yates with an injected rng. */
+export function shuffleInPlace(items, rng) {
+    for (let i = items.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(rng() * (i + 1));
+        const left = items[i];
+        const right = items[j];
+        if (left === undefined || right === undefined)
+            continue;
+        items[i] = right;
+        items[j] = left;
+    }
+    return items;
+}

package/dist/runtime/signals.d.ts

@@ -0,0 +1,4 @@
+import type { Signal } from './types.ts';
+export declare function openSignals(signals: readonly Signal[], flowId?: string): Signal[];
+/** Open signals for attention UI: failures first, then approvals, blockers, waits. */
+export declare function attentionOf(signals: readonly Signal[], flowId?: string): Signal[];

package/dist/runtime/signals.js

@@ -0,0 +1,13 @@
+export function openSignals(signals, flowId) {
+    return signals.filter((signal) => !signal.resolved && (!flowId || signal.flowId === flowId));
+}
+/** Open signals for attention UI: failures first, then approvals, blockers, waits. */
+export function attentionOf(signals, flowId) {
+    const order = {
+        failed: 0,
+        approval: 1,
+        blocker: 2,
+        waiting: 3,
+    };
+    return openSignals(signals, flowId).sort((a, b) => order[a.kind] - order[b.kind] || b.at.localeCompare(a.at) || b.id.localeCompare(a.id));
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Mock flow runtime types. Everything a run produces stays in-memory as
+ * proposed effects, keeps, signals and a masked outbox — never a network call.
+ */
+export type FlowRunStatus = 'running' | 'waiting' | 'done' | 'failed' | 'cancelled';
+export type OutboxKind = 'dm' | 'channel' | 'thread' | 'email' | 'inbox' | 'notification' | 'reply' | 'tool' | 'http';
+export type SignalKind = 'blocker' | 'waiting' | 'approval' | 'failed';
+export interface FlowPerson {
+    id: string;
+    name: string;
+    role?: string;
+    team?: string;
+}
+export interface FlowKeepRecord {
+    id: string;
+    collection: string;
+    title: string;
+    state: string | null;
+    fields: Record<string, string>;
+    runId: string;
+    createdAt: string;
+    history: {
+        to: string;
+        at: string;
+        by: string | null;
+    }[];
+}
+export interface FlowListState {
+    items: string[];
+    used: string[];
+    history: string[][];
+}
+export interface OutboxItem {
+    id: string;
+    at: string;
+    kind: OutboxKind;
+    text: string;
+    flowId: string;
+    runId: string;
+    stepId: string;
+    to?: string[];
+    channel?: string;
+    subject?: string;
+    /** Masked when kind is http. */
+    url?: string;
+    method?: string;
+    tool?: string;
+    action?: string;
+}
+export interface ProposedEffect {
+    type: string;
+    stepId: string;
+    payload: Readonly<Record<string, unknown>>;
+}
+export interface Signal {
+    id: string;
+    kind: SignalKind;
+    at: string;
+    resolved: boolean;
+    flowId: string;
+    runId: string;
+    stepId?: string;
+    title: string;
+    detail: string;
+}
+export interface FlowRun {
+    id: string;
+    flowId: string;
+    status: FlowRunStatus;
+    startedAt: string;
+    finishedAt: string | null;
+    trigger: Readonly<Record<string, unknown>>;
+    error: string | null;
+    /** Step ids visited in order (including skipped branches' chosen arm). */
+    path: string[];
+}
+export interface FlowRunResult {
+    run: FlowRun;
+    /** Step outputs keyed by step id. */
+    outputs: Readonly<Record<string, unknown>>;
+    /** Proposed side effects for a service adapter (messages, tools, records…). */
+    effects: readonly ProposedEffect[];
+    /** Masked delivery log — nothing left the browser. */
+    outbox: readonly OutboxItem[];
+    /** Records and list mutations the run kept. */
+    keeps: {
+        records: readonly FlowKeepRecord[];
+        lists: Readonly<Record<string, FlowListState>>;
+    };
+    signals: readonly Signal[];
+    /** Simulated clock after the run (ISO). */
+    now: string;
+}
+export interface FlowRuntimeOptions {
+    /** Simulated instant (ISO string, Date, or epoch ms). Default: fixed epoch. */
+    now?: string | number | Date;
+    /** Deterministic seed for picks, groups and assistant labels. */
+    seed?: number | string;
+    /** Payload that started the run (manual form, event, webhook sample). */
+    trigger?: Readonly<Record<string, unknown>>;
+    /** Record the run is about (event triggers). */
+    record?: unknown;
+    /** Directory for audience resolution (fictional people only). */
+    people?: readonly FlowPerson[];
+    /** Existing keeps the run may read. */
+    records?: Readonly<Record<string, readonly FlowKeepRecord[]>>;
+    lists?: Readonly<Record<string, FlowListState>>;
+    /**
+     * Answers for `ask` steps: step id → field map, or a single value applied to
+     * the first question.
+     */
+    answers?: Readonly<Record<string, unknown>>;
+    /** Decisions for `approval` steps: step id → approved | declined. */
+    decisions?: Readonly<Record<string, 'approved' | 'declined'>>;
+    /** Tool handlers by tool id. Must be pure and local — never fetch. */
+    tools?: Readonly<Record<string, (input: Readonly<Record<string, unknown>>) => unknown>>;
+    /** Optional judge for `judge` conditions (`undecided` leaves the run waiting). */
+    judge?: (request: {
+        phrase: string;
+        judge: string;
+    }) => boolean | 'undecided';
+    /**
+     * When true (default), `ask` / `approval` without answers leave the run
+     * `waiting`. When false, missing answers fail the run.
+     */
+    waitForPeople?: boolean;
+}

package/dist/runtime/types.js

@@ -0,0 +1,5 @@
+/**
+ * Mock flow runtime types. Everything a run produces stays in-memory as
+ * proposed effects, keeps, signals and a masked outbox — never a network call.
+ */
+export {};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@protoyard/flows",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.0",
+  "description": "Framework-agnostic workflow engine for Protoyard: a serializable flow model with triggers, steps, data-only conditions, edit operations, recipes and validation (no Svelte, no executable expressions).",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./model": {
+      "types": "./dist/model/index.d.ts",
+      "import": "./dist/model/index.js",
+      "default": "./dist/model/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "protoyard": {
+    "build": {
+      "group": "engine",
+      "assets": []
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DailybotHQ/protoyard",
+    "directory": "packages/flows"
+  },
+  "homepage": "https://protoyard.app",
+  "bugs": {
+    "url": "https://github.com/DailybotHQ/protoyard/issues"
+  },
+  "keywords": [
+    "protoyard",
+    "workflow",
+    "automation",
+    "typescript"
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "types": "./dist/index.d.ts"
 }