@sequenceholdings/studio-cli 0.1.9

package/dist/process/discover.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Find and load process definitions from disk. seq-studio runs from
+ * inside an external process repo, so the default discovery strategy is
+ * "walk the cwd for any folder containing a `process.ts` and import it."
+ * It relies on `LATTICE_PROCESSES_ROOT` (env override) or a flat cwd
+ * walk so it works in any external repo without hardcoded monorepo paths.
+ *
+ * The published binary runs under plain Node, which can't import `.ts`
+ * files directly (ERR_UNKNOWN_FILE_EXTENSION on Node 20). We use the
+ * `tsx` programmatic API (`tsImport`) to transpile + load process.ts on
+ * the fly — same loader the user would get from `npx tsx`, with no
+ * `node --loader` flag or precompile step required.
+ */
+import type { ProcessDefinition } from '@sequenceholdings/lattice/define';
+export interface LoadedProcess {
+    file: string;
+    process: ProcessDefinition;
+}
+/**
+ * Resolve the root directory to scan for `<id>/process.ts` folders.
+ *
+ * Precedence:
+ *   1. `LATTICE_PROCESSES_ROOT` env var (absolute or relative to cwd)
+ *   2. The current working directory (the typical case in an external repo)
+ */
+export declare function findProcessRoot(): Promise<string>;
+/**
+ * Load every `<dir>/process.ts` under the configured root. Each module
+ * must `export default defineProcess(...)`. Process ids must be unique
+ * across the set — duplicates throw.
+ */
+export declare function loadProcessDefinitions(): Promise<readonly LoadedProcess[]>;

package/dist/process/discover.js

@@ -0,0 +1,131 @@
+/**
+ * Find and load process definitions from disk. seq-studio runs from
+ * inside an external process repo, so the default discovery strategy is
+ * "walk the cwd for any folder containing a `process.ts` and import it."
+ * It relies on `LATTICE_PROCESSES_ROOT` (env override) or a flat cwd
+ * walk so it works in any external repo without hardcoded monorepo paths.
+ *
+ * The published binary runs under plain Node, which can't import `.ts`
+ * files directly (ERR_UNKNOWN_FILE_EXTENSION on Node 20). We use the
+ * `tsx` programmatic API (`tsImport`) to transpile + load process.ts on
+ * the fly — same loader the user would get from `npx tsx`, with no
+ * `node --loader` flag or precompile step required.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { tsImport } from 'tsx/esm/api';
+async function isDir(path) {
+    try {
+        const st = await stat(path);
+        return st.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the root directory to scan for `<id>/process.ts` folders.
+ *
+ * Precedence:
+ *   1. `LATTICE_PROCESSES_ROOT` env var (absolute or relative to cwd)
+ *   2. The current working directory (the typical case in an external repo)
+ */
+export async function findProcessRoot() {
+    const envRoot = process.env['LATTICE_PROCESSES_ROOT']?.trim();
+    if (envRoot) {
+        const resolved = resolve(envRoot);
+        if (!(await isDir(resolved))) {
+            throw new Error(`LATTICE_PROCESSES_ROOT is not a directory: ${resolved}`);
+        }
+        return resolved;
+    }
+    return process.cwd();
+}
+/**
+ * Load every `<dir>/process.ts` under the configured root. Each module
+ * must `export default defineProcess(...)`. Process ids must be unique
+ * across the set — duplicates throw.
+ */
+export async function loadProcessDefinitions() {
+    const root = await findProcessRoot();
+    const entries = await readdir(root);
+    const found = [];
+    const seenIds = new Set();
+    // Group dirs (e.g. `crm-email/`) have no `process.ts` of their own but
+    // contain `<group>/<id>/process.ts`. Discovery is one level deep, so they're
+    // silently skipped from this root — warn so a dev doesn't believe they
+    // linted/applied everything (run from inside the group dir, or set
+    // LATTICE_PROCESSES_ROOT to it).
+    const skippedGroupDirs = [];
+    for (const entry of entries) {
+        const procDir = join(root, entry);
+        if (!(await isDir(procDir)))
+            continue;
+        const candidate = join(procDir, 'process.ts');
+        if (!(await fileExists(candidate))) {
+            if (await dirContainsNestedProcess(procDir))
+                skippedGroupDirs.push(entry);
+            continue;
+        }
+        // tsImport returns a Promise<Module> and handles `.ts` + `.tsx` +
+        // ESM/CJS interop. The second arg is the parent URL for relative
+        // resolution; we use this module's own URL so the user's
+        // process.ts can `import '@sequenceholdings/lattice'` against the
+        // package they installed in their own node_modules.
+        const mod = (await tsImport(pathToFileURL(candidate).href, import.meta.url));
+        const def = mod.default;
+        if (!def || typeof def !== 'object' || !('nodes' in def)) {
+            throw new Error(`${relative(process.cwd(), candidate)}: default export must be a ProcessDefinition (from defineProcess)`);
+        }
+        const processDef = def;
+        if (seenIds.has(processDef.id)) {
+            throw new Error(`duplicate process id "${processDef.id}" — found in ${relative(process.cwd(), candidate)} and an earlier file`);
+        }
+        seenIds.add(processDef.id);
+        found.push({ file: candidate, process: processDef });
+    }
+    if (skippedGroupDirs.length > 0) {
+        console.warn(`[seq-studio] Skipped ${skippedGroupDirs.length} group dir(s) with nested ` +
+            `process trees (discovery is one level deep): ${skippedGroupDirs.join(', ')}. ` +
+            `Run from inside the group dir, or set LATTICE_PROCESSES_ROOT, to lint/apply them.`);
+    }
+    if (found.length === 0) {
+        throw new Error(`No lattice process definitions found under ${root}. ` +
+            `Each process lives in a subfolder with a "process.ts" file that ` +
+            `exports defineProcess(...). Set LATTICE_PROCESSES_ROOT to ` +
+            `point at a different directory.`);
+    }
+    return found;
+}
+/**
+ * True if `dir` is a group dir: it has no `process.ts` of its own but at least
+ * one immediate child `<dir>/<sub>/process.ts`. Used only to warn that such
+ * trees are skipped by the one-level-deep walk.
+ */
+async function dirContainsNestedProcess(dir) {
+    let children;
+    try {
+        children = await readdir(dir);
+    }
+    catch {
+        return false;
+    }
+    for (const child of children) {
+        const childDir = join(dir, child);
+        if (!(await isDir(childDir)))
+            continue;
+        if (await fileExists(join(childDir, 'process.ts')))
+            return true;
+    }
+    return false;
+}

package/dist/process/lint.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Production-grade lint for v2 process definitions — the single source
+ * of truth for process lint checks.
+ *
+ *   - Graph integrity (already enforced by defineProcess at import time)
+ *   - Reachability (BFS from start_node_id; orphans are warnings)
+ *   - Agent output contract — load the agent definition, walk its
+ *     JSON Schema, confirm edge_id enum matches outgoing_edges
+ *   - Human timeout edge — if timeout is set and outgoing_edges.length > 0
+ *     but on_timeout_edge_id is unset, warn
+ */
+import type { ProcessDefinition } from '@sequenceholdings/lattice/define';
+export interface LintIssue {
+    process_id: string;
+    node_id?: string;
+    message: string;
+}
+export interface LintResult {
+    errors: readonly LintIssue[];
+    warnings: readonly LintIssue[];
+}
+export interface LintInput {
+    defs: readonly {
+        file: string;
+        process: ProcessDefinition;
+    }[];
+    /**
+     * Optional async hook to validate an agent node against its real
+     * agent-builder definition. The CLI wires this to
+     * `GET /api/agents/agents/:id`; for unit tests or offline use, leave
+     * undefined and a warning is emitted instead of failing the build.
+     */
+    loadAgentSchemaEdgeIdEnum?: (agentId: string) => Promise<string[] | null | 'not-found'>;
+}
+export declare function lintProcesses(input: LintInput): Promise<LintResult>;
+export declare function formatLintResult(result: LintResult): {
+    text: string;
+    hasErrors: boolean;
+};

package/dist/process/lint.js

@@ -0,0 +1,485 @@
+/**
+ * Production-grade lint for v2 process definitions — the single source
+ * of truth for process lint checks.
+ *
+ *   - Graph integrity (already enforced by defineProcess at import time)
+ *   - Reachability (BFS from start_node_id; orphans are warnings)
+ *   - Agent output contract — load the agent definition, walk its
+ *     JSON Schema, confirm edge_id enum matches outgoing_edges
+ *   - Human timeout edge — if timeout is set and outgoing_edges.length > 0
+ *     but on_timeout_edge_id is unset, warn
+ */
+import { readFileSync } from 'node:fs';
+import { parallelSubNodes, validateEmailReminders } from '@sequenceholdings/lattice/define';
+export async function lintProcesses(input) {
+    const errors = [];
+    const warnings = [];
+    for (const { file, process: p } of input.defs) {
+        const nodeIds = new Set(p.nodes.map((n) => n.id));
+        if (!nodeIds.has(p.start_node_id)) {
+            errors.push({
+                process_id: p.id,
+                message: `start_node_id "${p.start_node_id}" is not in nodes`,
+            });
+            continue;
+        }
+        for (const node of p.nodes) {
+            const seen = new Set();
+            for (const edge of node.outgoing_edges) {
+                if (seen.has(edge.id)) {
+                    errors.push({
+                        process_id: p.id,
+                        node_id: node.id,
+                        message: `duplicate outgoing edge id "${edge.id}"`,
+                    });
+                }
+                seen.add(edge.id);
+                if (!nodeIds.has(edge.to)) {
+                    errors.push({
+                        process_id: p.id,
+                        node_id: node.id,
+                        message: `outgoing edge "${edge.id}" targets non-existent node "${edge.to}"`,
+                    });
+                }
+            }
+        }
+        const reachable = new Set([p.start_node_id]);
+        const queue = [p.start_node_id];
+        while (queue.length > 0) {
+            const id = queue.shift();
+            const node = p.nodes.find((n) => n.id === id);
+            if (!node)
+                continue;
+            for (const edge of node.outgoing_edges) {
+                if (!reachable.has(edge.to)) {
+                    reachable.add(edge.to);
+                    queue.push(edge.to);
+                }
+            }
+        }
+        for (const node of p.nodes) {
+            if (!reachable.has(node.id)) {
+                warnings.push({
+                    process_id: p.id,
+                    node_id: node.id,
+                    message: `node "${node.id}" is unreachable from start_node_id "${p.start_node_id}"`,
+                });
+            }
+        }
+        for (const node of p.nodes) {
+            await lintNodeContract(p.id, node, errors, warnings, input.loadAgentSchemaEdgeIdEnum);
+        }
+        // Closure-scope check: mappers / fn / join / fan_out / output are
+        // serialized via `.toString()` and run in a vm with NOTHING from the
+        // module in scope. A reference to an imported binding therefore throws
+        // ReferenceError at runtime (the classic "helper refs are not in bundle
+        // scope" bug). Cross-check each serialized function against the module's
+        // imports. Warn (not error) — high-signal but heuristic, and we don't want
+        // to break an existing process on a regex edge case.
+        const importedNames = readImportedNames(file);
+        if (importedNames.size > 0) {
+            for (const node of p.nodes) {
+                lintSandboxClosures(p.id, node, importedNames, warnings);
+            }
+        }
+    }
+    return { errors, warnings };
+}
+/**
+ * Module-scope binding names introduced by `import` statements in the process
+ * file. These are exactly the names a serialized (vm-executed) function must
+ * NOT reference. Best-effort regex parse; returns empty when the file can't be
+ * read (e.g. unit tests passing a synthetic path) so the check simply no-ops.
+ */
+function readImportedNames(file) {
+    let source;
+    try {
+        source = readFileSync(file, 'utf8');
+    }
+    catch {
+        return new Set();
+    }
+    const names = new Set();
+    const importRe = /import\s+(type\s+)?([^'";]+?)\s+from\s*['"][^'"]+['"]/g;
+    let m;
+    while ((m = importRe.exec(source)) !== null) {
+        if (m[1])
+            continue; // `import type ...` is erased at runtime — never a free-var bug
+        const clause = m[2].trim();
+        const named = clause.match(/\{([^}]*)\}/);
+        if (named) {
+            for (const raw of named[1].split(',')) {
+                const part = raw.trim();
+                if (!part || part.startsWith('type '))
+                    continue;
+                const asParts = part.split(/\s+as\s+/);
+                const local = (asParts[1] ?? asParts[0]).trim();
+                if (local)
+                    names.add(local);
+            }
+        }
+        const ns = clause.match(/\*\s+as\s+([A-Za-z_$][\w$]*)/);
+        if (ns)
+            names.add(ns[1]);
+        // default import: the bare leading identifier before any `,`/`{`/`*`
+        const def = clause.match(/^([A-Za-z_$][\w$]*)\s*(?:,|$)/);
+        if (def)
+            names.add(def[1]);
+    }
+    return names;
+}
+/** Serialized (vm-executed) function sources declared on a node. */
+function nodeSerializedFns(node) {
+    const out = [];
+    const add = (field, fn) => {
+        if (typeof fn === 'function')
+            out.push({ field, source: fn.toString() });
+    };
+    switch (node.kind) {
+        case 'automation':
+            // Native automation handlers run in-process from the Atlas image — their
+            // body is NOT serialized, so only the (serialized) input mapper is checked.
+            add('input', node.input);
+            break;
+        case 'agent':
+            add('input', node.input);
+            break;
+        case 'human': {
+            const human = node;
+            add('input', human.input);
+            if (typeof human.artifact_refs === 'function')
+                add('artifact_refs', human.artifact_refs);
+            if (typeof human.advance_allowed === 'function')
+                add('advance_allowed', human.advance_allowed);
+            if (typeof human.dueDate === 'function')
+                add('dueDate', human.dueDate);
+            break;
+        }
+        case 'parallel': {
+            const parallel = node;
+            add('join', parallel.join);
+            add('input', parallel.input);
+            if ('fan_out' in parallel)
+                add('fan_out', parallel.fan_out);
+            break;
+        }
+        case 'subprocess': {
+            const subprocess = node;
+            add('input', subprocess.input);
+            add('output', subprocess.output);
+            break;
+        }
+        case 'managed_function':
+            // The input mapper is serialized to `input_mapper_source` and runs in
+            // the same vm as every other mapper, so it's subject to the identical
+            // free-variable / imported-helper hazard.
+            add('input', node.input);
+            break;
+    }
+    return out;
+}
+/** True if `name` is referenced as a free identifier in `source` (not a
+ * property access, not a substring, not locally re-declared/shadowed). */
+function referencesFreeName(source, name) {
+    const esc = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (!new RegExp(`(?<![.\\w$])${esc}(?![\\w$])`).test(source))
+        return false;
+    // Locally declared inside the function → it shadows the import, not a bug.
+    if (new RegExp(`\\b(?:const|let|var|function|class)\\s+${esc}\\b`).test(source))
+        return false;
+    return true;
+}
+function lintSandboxClosures(processId, node, importedNames, warnings) {
+    for (const { field, source } of nodeSerializedFns(node)) {
+        for (const name of importedNames) {
+            if (referencesFreeName(source, name)) {
+                warnings.push({
+                    process_id: processId,
+                    node_id: node.id,
+                    message: `${field} references imported "${name}", which is NOT in scope when the function runs in the lattice vm — inline the value/helper inside the function (serialized via .toString(), module imports are not bundled)`,
+                });
+            }
+        }
+    }
+    if (node.kind === 'parallel') {
+        for (const { node: sub } of parallelSubNodes(node)) {
+            lintSandboxClosures(processId, sub, importedNames, warnings);
+        }
+    }
+}
+/**
+ * Per-node output-contract lint. For parallel nodes this recurses into every
+ * sub-node (so a sub-node automation/agent/human is held to the same
+ * edge_id-contract checks as a top-level node) and lints the `join` reducer's
+ * own edge_id returns against the parallel node's outgoing_edges.
+ */
+async function lintNodeContract(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum) {
+    switch (node.kind) {
+        case 'agent':
+            await lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum);
+            break;
+        case 'human':
+            lintHuman(processId, node, errors, warnings);
+            break;
+        case 'parallel': {
+            const parallel = node;
+            lintParallelJoin(processId, parallel, errors, warnings);
+            for (const { node: sub } of parallelSubNodes(parallel)) {
+                await lintNodeContract(processId, sub, errors, warnings, loadAgentSchemaEdgeIdEnum);
+            }
+            break;
+        }
+        case 'subprocess': {
+            const subprocess = node;
+            lintSubprocessOutput(processId, subprocess, errors, warnings);
+            break;
+        }
+        case 'managed_function': {
+            lintManagedFunctionNode(processId, node, errors);
+            break;
+        }
+        case 'automation': {
+            lintRouteRulesEdges(processId, node, errors);
+            break;
+        }
+    }
+}
+/**
+ * A node whose config declares `routeRules` (content-conditional routing —
+ * see `service-event-form-validate`) must declare EVERY rule's `edge_id` as an
+ * outgoing edge. This is the only place the hole can be closed: the native fn
+ * can't see the graph from its execution context, and the engine's edge router
+ * AUTO-TAKES a sole outgoing edge while silently discarding the returned
+ * edge_id — so a rule targeting a forgotten edge would route every submission
+ * down `ok` with zero signal. (With the edge declared, the node has ≥2 edges
+ * and the router's unknown-edge check is already fail-closed at runtime.)
+ * Generic by config shape, so any future function adopting the routeRules
+ * convention is covered.
+ */
+function lintRouteRulesEdges(processId, node, errors) {
+    const config = node.config;
+    const rules = config?.routeRules;
+    if (!Array.isArray(rules) || rules.length === 0)
+        return;
+    const edgeIds = new Set(node.outgoing_edges.map((e) => e.id));
+    // The fn returns 'ok' when no rule matches (hardcoded fallback in
+    // service-event-form-validate) — a routeRules node without an ok edge would
+    // pass the per-rule check below and then fail the FIRST non-matching
+    // submission at runtime (InvalidEdgeIdError). Catch it at lint time.
+    if (!edgeIds.has('ok')) {
+        errors.push({
+            process_id: processId,
+            node_id: node.id,
+            message: 'a node with routeRules must also declare the "ok" outgoing edge — it is the ' +
+                'fallback the function returns when no rule matches',
+        });
+    }
+    for (const rule of rules) {
+        const edgeId = rule?.edge_id;
+        if (typeof edgeId !== 'string')
+            continue; // shape errors are the fn's fail-closed job
+        if (!edgeIds.has(edgeId)) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `routeRules targets edge "${edgeId}" which is not a declared outgoing edge — ` +
+                    'with a sole outgoing edge the engine ignores the returned edge_id and every ' +
+                    'submission silently routes down it; declare the edge on the node',
+            });
+        }
+    }
+}
+function lintManagedFunctionNode(processId, node, errors) {
+    const edgeIds = new Set(node.outgoing_edges.map((e) => e.id));
+    for (const required of ['success', 'error']) {
+        if (!edgeIds.has(required)) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `managed_function node must declare outgoing edge "${required}"`,
+            });
+        }
+    }
+    if (!node.function?.trim()) {
+        errors.push({
+            process_id: processId,
+            node_id: node.id,
+            message: 'managed_function node must declare a non-empty `function` ref',
+        });
+    }
+}
+function lintSubprocessOutput(processId, node, errors, warnings) {
+    const outgoingIds = new Set(node.outgoing_edges.map((e) => e.id));
+    const source = node.output.toString();
+    let match;
+    EDGE_ID_LITERAL_RE.lastIndex = 0;
+    const found = new Set();
+    while ((match = EDGE_ID_LITERAL_RE.exec(source)) !== null) {
+        found.add(match[1]);
+    }
+    for (const literal of found) {
+        if (!outgoingIds.has(literal)) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `subprocess output returns edge_id "${literal}" which is not in outgoing_edges [${[...outgoingIds].join(', ')}]`,
+            });
+        }
+    }
+    if (node.outgoing_edges.length > 0 && found.size === 0) {
+        warnings.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `subprocess node has outgoing edges but no literal edge_id found in output mapper — confirm it selects edge_id correctly`,
+        });
+    }
+}
+const EDGE_ID_LITERAL_RE = /\bedge_id\s*:\s*['"`]([^'"`]+)['"`]/g;
+async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum) {
+    const allEdgeIds = node.outgoing_edges.map((e) => e.id);
+    // The reset edge (taken out-of-band by the reset intervention, never chosen
+    // by the agent) must exist on the node but is excluded from the agent's
+    // edge_id contract — same way a human node's on_timeout_edge_id is an
+    // orchestration-only edge. Validate membership, then verify the agent's
+    // edge_id enum against the REAL (non-reset) edges only.
+    if (node.on_reset_edge_id) {
+        if (!allEdgeIds.includes(node.on_reset_edge_id)) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `on_reset_edge_id "${node.on_reset_edge_id}" is not in outgoing_edges`,
+            });
+        }
+    }
+    const outgoingIds = allEdgeIds.filter((id) => id !== node.on_reset_edge_id);
+    if (!loadAgentSchemaEdgeIdEnum) {
+        if (outgoingIds.length > 1) {
+            warnings.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `agent node has ${outgoingIds.length} outgoing edges; agent output schema vs outgoing_edges contract not verified (no agent registry loader available)`,
+            });
+        }
+        return;
+    }
+    let enumValues;
+    try {
+        enumValues = await loadAgentSchemaEdgeIdEnum(node.agent.id);
+    }
+    catch (err) {
+        warnings.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `could not load agent definition "${node.agent.id}" to verify output contract: ${err instanceof Error ? err.message : String(err)} (run with DB access to enable full check)`,
+        });
+        return;
+    }
+    if (enumValues === 'not-found') {
+        errors.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `agent "${node.agent.id}" not found in the target env — sync/seed the agent registry before applying`,
+        });
+        return;
+    }
+    if (outgoingIds.length === 0)
+        return;
+    if (enumValues === null) {
+        // No edge_id enum is the generic-agent contract: one agent serving nodes
+        // with different edge sets declares edge_id as a plain string, the valid
+        // set rides the node's input mapper (prompt), and the runner validates
+        // the returned edge_id against the node's outgoing_edges at runtime. An
+        // agent that DOES declare an enum keeps the exact-match check below.
+        return;
+    }
+    const missing = outgoingIds.filter((id) => !enumValues.includes(id));
+    const extra = enumValues.filter((id) => !outgoingIds.includes(id));
+    if (missing.length > 0 || extra.length > 0) {
+        errors.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `agent "${node.agent.id}" edge_id enum mismatch — missing: [${missing.join(', ')}], extra: [${extra.join(', ')}]; expected exactly: [${outgoingIds.join(', ')}]`,
+        });
+    }
+}
+/**
+ * Lint a parallel node's `join` reducer the way we lint automation fns:
+ * scan the serialized source for literal `edge_id: '…'` returns and confirm
+ * each is in the parallel node's own outgoing_edges. The reducer chooses the
+ * parallel node's exit edge, so a typo there is a routing bug the orchestrator
+ * would only surface at run time.
+ */
+function lintParallelJoin(processId, node, errors, warnings) {
+    const join = node.join;
+    const source = typeof join === 'function' ? join.toString() : '';
+    const outgoingIds = new Set(node.outgoing_edges.map((e) => e.id));
+    const literals = new Set();
+    for (const match of source.matchAll(EDGE_ID_LITERAL_RE)) {
+        if (match[1])
+            literals.add(match[1]);
+    }
+    for (const literal of literals) {
+        if (!outgoingIds.has(literal)) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `parallel join returns edge_id "${literal}" which is not in outgoing_edges [${[...outgoingIds].join(', ')}]`,
+            });
+        }
+    }
+    if (node.outgoing_edges.length > 1 && literals.size === 0) {
+        warnings.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `parallel node has ${node.outgoing_edges.length} outgoing edges but no literal edge_id returns found in join source — confirm join selects edge_id correctly`,
+        });
+    }
+}
+function lintHuman(processId, node, errors, warnings) {
+    // Email reminders that can never fire (offset before the task is ready, or
+    // after it times out / past the cap) are author bugs the runner silently
+    // skips — catch them here. Only the object form carries reminders.
+    const email = node.emailNotification;
+    if (email && typeof email === 'object') {
+        const hasDueDate = typeof node.dueDate === 'function';
+        for (const issue of validateEmailReminders(email, node.timeout, hasDueDate)) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: issue.index === undefined
+                    ? `emailNotification.${issue.message}`
+                    : `emailNotification.reminders[${issue.index}]: ${issue.message}`,
+            });
+        }
+    }
+    if (node.on_timeout_edge_id) {
+        const ok = node.outgoing_edges.some((e) => e.id === node.on_timeout_edge_id);
+        if (!ok) {
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `on_timeout_edge_id "${node.on_timeout_edge_id}" is not in outgoing_edges`,
+            });
+        }
+        return;
+    }
+    if (node.timeout && node.outgoing_edges.length > 0) {
+        warnings.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `human node has timeout=${node.timeout} but no on_timeout_edge_id — run will fail with MissingEdgeIdError when the wait token times out`,
+        });
+    }
+}
+export function formatLintResult(result) {
+    const lines = [];
+    for (const e of result.errors) {
+        const where = e.node_id ? `${e.process_id}.${e.node_id}` : e.process_id;
+        lines.push(`ERROR [${where}] ${e.message}`);
+    }
+    for (const w of result.warnings) {
+        const where = w.node_id ? `${w.process_id}.${w.node_id}` : w.process_id;
+        lines.push(`WARN  [${where}] ${w.message}`);
+    }
+    return { text: lines.join('\n'), hasErrors: result.errors.length > 0 };
+}