peaks-loop 4.0.54 → 4.1.0

package/dist/services/workflow/workflow-graph-store-helpers.js

@@ -0,0 +1,111 @@
+/**
+ * Workflow graph store helpers (B wave-3 file-size split).
+ *
+ * Extracted verbatim from `workflow-graph-store.ts`: the canonical
+ * `PEAKS_*` error-code constants, the `GraphStoreError` shape +
+ * `makeError` factory, the session-root/path resolution helpers, the
+ * cycle detector, and the fresh-graph builder. The on-disk graph
+ * record layout is defined by `workflow-graph-types.ts` and is NOT
+ * altered by this move — `emptyGraph` emits the identical node/edge
+ * shape as before. `workflow-graph-store.ts` re-exports every public
+ * name from this module so all importers keep resolving the same path.
+ */
+import { join, resolve, sep } from 'node:path';
+import { WORKFLOW_ID_REGEX, isSafeRelativeGraphRef } from './workflow-graph-types.js';
+export const PEAKS_GRAPH_NOT_FOUND = 'PEAKS_GRAPH_NOT_FOUND';
+export const PEAKS_GRAPH_CORRUPTED = 'PEAKS_GRAPH_CORRUPTED';
+export const PEAKS_GRAPH_CYCLE = 'PEAKS_GRAPH_CYCLE';
+export const PEAKS_GRAPH_REF_BROKEN = 'PEAKS_GRAPH_REF_BROKEN';
+export const PEAKS_GRAPH_NODE_REQUIRED = 'PEAKS_GRAPH_NODE_REQUIRED';
+export const PEAKS_GRAPH_NODE_NOT_PREPARED = 'PEAKS_GRAPH_NODE_NOT_PREPARED';
+export const PEAKS_GRAPH_NODE_KIND_INVALID = 'PEAKS_GRAPH_NODE_KIND_INVALID';
+export const PEAKS_NODE_EXISTS = 'PEAKS_NODE_EXISTS';
+export const PEAKS_NODE_TRANSITION_INVALID = 'PEAKS_NODE_TRANSITION_INVALID';
+export const PEAKS_ENVELOPE_NOT_RECEIVED = 'PEAKS_ENVELOPE_NOT_RECEIVED';
+export const PEAKS_ENVELOPE_GRAPH_MISMATCH = 'PEAKS_ENVELOPE_GRAPH_MISMATCH';
+export const PEAKS_TERMINAL_REASON_INVALID = 'PEAKS_TERMINAL_REASON_INVALID';
+export const PEAKS_TERMINALIZE_ATOMICITY_FAILED = 'PEAKS_TERMINALIZE_ATOMICITY_FAILED';
+export const PEAKS_UNCONSUMED_ENVELOPE = 'PEAKS_UNCONSUMED_ENVELOPE';
+export const PEAKS_DEPENDENCY_NOT_CONSUMED = 'PEAKS_DEPENDENCY_NOT_CONSUMED';
+export const PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR = 'PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR';
+export const PEAKS_SESSION_NOT_BOUND = 'PEAKS_SESSION_NOT_BOUND';
+export const PEAKS_CALLER_NOT_RESOLVED = 'PEAKS_CALLER_NOT_RESOLVED';
+export function makeError(code, message, legacyFallback = false) {
+    const err = new Error(message);
+    err.name = 'GraphStoreError';
+    err.code = code;
+    err.legacyFallback = legacyFallback;
+    return err;
+}
+function safeSessionRuntimeRoot(projectRoot, sessionId) {
+    if (!WORKFLOW_ID_REGEX.test(sessionId)) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `invalid sessionId: ${sessionId}`);
+    }
+    const root = resolve(projectRoot);
+    return join(root, '.peaks', '_runtime', sessionId);
+}
+/** Compute the on-disk graph path. Validates `graphRef` stays under the session root. */
+export function graphPathFor(input) {
+    if (!isSafeRelativeGraphRef(input.graphRef, input.workflowId)) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef is not safe: ${input.graphRef}`);
+    }
+    if (!WORKFLOW_ID_REGEX.test(input.workflowId)) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `workflowId is not safe: ${input.workflowId}`);
+    }
+    const sessionRoot = safeSessionRuntimeRoot(input.projectRoot, input.sessionId);
+    const resolved = resolve(sessionRoot, input.graphRef);
+    if (!resolved.startsWith(sessionRoot + sep) && resolved !== sessionRoot) {
+        throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef escapes session root: ${input.graphRef}`);
+    }
+    return resolved;
+}
+/** Detect cycles in a node-dependency graph. */
+export function detectCycle(nodes) {
+    const map = new Map();
+    for (const n of nodes)
+        map.set(n.id, n);
+    const color = new Map();
+    const visiting = (id) => {
+        const c = color.get(id) ?? 0;
+        if (c === 1)
+            return true;
+        if (c === 2)
+            return false;
+        color.set(id, 1);
+        const node = map.get(id);
+        if (node) {
+            for (const dep of node.dependsOn) {
+                if (visiting(dep))
+                    return true;
+            }
+        }
+        color.set(id, 2);
+        return false;
+    };
+    for (const n of nodes) {
+        if (visiting(n.id))
+            return true;
+    }
+    return false;
+}
+/** Build a fresh empty graph with one terminal node. */
+export function emptyGraph(input) {
+    const graph = {
+        workflowId: input.workflowId,
+        rootSkill: input.rootSkill,
+        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+        nodes: [
+            {
+                id: 'terminal',
+                kind: 'terminal',
+                label: 'workflow complete',
+                status: 'prepared',
+                dependsOn: [],
+                ackStatus: 'not-required'
+            }
+        ],
+        edges: [],
+        schemaVersion: 1
+    };
+    return graph;
+}

package/dist/services/workflow/workflow-graph-store.d.ts

@@ -9,35 +9,8 @@
  * canonical corruption is surfaced with `PEAKS_GRAPH_CORRUPTED`.
  */
 import { type WorkflowGraph, type WorkflowId } from './workflow-graph-types.js';
-export declare const PEAKS_GRAPH_NOT_FOUND = "PEAKS_GRAPH_NOT_FOUND";
-export declare const PEAKS_GRAPH_CORRUPTED = "PEAKS_GRAPH_CORRUPTED";
-export declare const PEAKS_GRAPH_CYCLE = "PEAKS_GRAPH_CYCLE";
-export declare const PEAKS_GRAPH_REF_BROKEN = "PEAKS_GRAPH_REF_BROKEN";
-export declare const PEAKS_GRAPH_NODE_REQUIRED = "PEAKS_GRAPH_NODE_REQUIRED";
-export declare const PEAKS_GRAPH_NODE_NOT_PREPARED = "PEAKS_GRAPH_NODE_NOT_PREPARED";
-export declare const PEAKS_GRAPH_NODE_KIND_INVALID = "PEAKS_GRAPH_NODE_KIND_INVALID";
-export declare const PEAKS_NODE_EXISTS = "PEAKS_NODE_EXISTS";
-export declare const PEAKS_NODE_TRANSITION_INVALID = "PEAKS_NODE_TRANSITION_INVALID";
-export declare const PEAKS_ENVELOPE_NOT_RECEIVED = "PEAKS_ENVELOPE_NOT_RECEIVED";
-export declare const PEAKS_ENVELOPE_GRAPH_MISMATCH = "PEAKS_ENVELOPE_GRAPH_MISMATCH";
-export declare const PEAKS_TERMINAL_REASON_INVALID = "PEAKS_TERMINAL_REASON_INVALID";
-export declare const PEAKS_TERMINALIZE_ATOMICITY_FAILED = "PEAKS_TERMINALIZE_ATOMICITY_FAILED";
-export declare const PEAKS_UNCONSUMED_ENVELOPE = "PEAKS_UNCONSUMED_ENVELOPE";
-export declare const PEAKS_DEPENDENCY_NOT_CONSUMED = "PEAKS_DEPENDENCY_NOT_CONSUMED";
-export declare const PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR = "PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR";
-export declare const PEAKS_SESSION_NOT_BOUND = "PEAKS_SESSION_NOT_BOUND";
-export declare const PEAKS_CALLER_NOT_RESOLVED = "PEAKS_CALLER_NOT_RESOLVED";
-export interface GraphStoreError extends Error {
-    readonly code: string;
-    readonly legacyFallback: boolean;
-}
-/** Compute the on-disk graph path. Validates `graphRef` stays under the session root. */
-export declare function graphPathFor(input: {
-    projectRoot: string;
-    sessionId: string;
-    graphRef: string;
-    workflowId: WorkflowId;
-}): string;
+export { PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_GRAPH_CYCLE, PEAKS_GRAPH_REF_BROKEN, PEAKS_GRAPH_NODE_REQUIRED, PEAKS_GRAPH_NODE_NOT_PREPARED, PEAKS_GRAPH_NODE_KIND_INVALID, PEAKS_NODE_EXISTS, PEAKS_NODE_TRANSITION_INVALID, PEAKS_ENVELOPE_NOT_RECEIVED, PEAKS_ENVELOPE_GRAPH_MISMATCH, PEAKS_TERMINAL_REASON_INVALID, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_UNCONSUMED_ENVELOPE, PEAKS_DEPENDENCY_NOT_CONSUMED, PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR, PEAKS_SESSION_NOT_BOUND, PEAKS_CALLER_NOT_RESOLVED, graphPathFor, emptyGraph } from './workflow-graph-store-helpers.js';
+export type { GraphStoreError } from './workflow-graph-store-helpers.js';
 /** Validate a graph shape; throw `PEAKS_GRAPH_CORRUPTED` on any violation. */
 export declare function validateGraph(graph: unknown): WorkflowGraph;
 /** Read a graph from disk; never falls back to legacy. */
@@ -60,12 +33,6 @@ export declare function writeGraph(input: {
 }): {
     path: string;
 };
-/** Build a fresh empty graph with one terminal node. */
-export declare function emptyGraph(input: {
-    workflowId: WorkflowId;
-    rootSkill: string;
-    parentWorkflowId?: WorkflowId;
-}): WorkflowGraph;
 /** Validate a `graphRef` is well-formed without writing. */
 export declare function validateGraphRef(input: {
     graphRef: string;

package/dist/services/workflow/workflow-graph-store.js

@@ -9,55 +9,11 @@
  * canonical corruption is surfaced with `PEAKS_GRAPH_CORRUPTED`.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
-import { WORKFLOW_ID_REGEX, NODE_ID_REGEX, isSafeRelativeGraphRef, } from './workflow-graph-types.js';
-export const PEAKS_GRAPH_NOT_FOUND = 'PEAKS_GRAPH_NOT_FOUND';
-export const PEAKS_GRAPH_CORRUPTED = 'PEAKS_GRAPH_CORRUPTED';
-export const PEAKS_GRAPH_CYCLE = 'PEAKS_GRAPH_CYCLE';
-export const PEAKS_GRAPH_REF_BROKEN = 'PEAKS_GRAPH_REF_BROKEN';
-export const PEAKS_GRAPH_NODE_REQUIRED = 'PEAKS_GRAPH_NODE_REQUIRED';
-export const PEAKS_GRAPH_NODE_NOT_PREPARED = 'PEAKS_GRAPH_NODE_NOT_PREPARED';
-export const PEAKS_GRAPH_NODE_KIND_INVALID = 'PEAKS_GRAPH_NODE_KIND_INVALID';
-export const PEAKS_NODE_EXISTS = 'PEAKS_NODE_EXISTS';
-export const PEAKS_NODE_TRANSITION_INVALID = 'PEAKS_NODE_TRANSITION_INVALID';
-export const PEAKS_ENVELOPE_NOT_RECEIVED = 'PEAKS_ENVELOPE_NOT_RECEIVED';
-export const PEAKS_ENVELOPE_GRAPH_MISMATCH = 'PEAKS_ENVELOPE_GRAPH_MISMATCH';
-export const PEAKS_TERMINAL_REASON_INVALID = 'PEAKS_TERMINAL_REASON_INVALID';
-export const PEAKS_TERMINALIZE_ATOMICITY_FAILED = 'PEAKS_TERMINALIZE_ATOMICITY_FAILED';
-export const PEAKS_UNCONSUMED_ENVELOPE = 'PEAKS_UNCONSUMED_ENVELOPE';
-export const PEAKS_DEPENDENCY_NOT_CONSUMED = 'PEAKS_DEPENDENCY_NOT_CONSUMED';
-export const PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR = 'PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR';
-export const PEAKS_SESSION_NOT_BOUND = 'PEAKS_SESSION_NOT_BOUND';
-export const PEAKS_CALLER_NOT_RESOLVED = 'PEAKS_CALLER_NOT_RESOLVED';
-function makeError(code, message, legacyFallback = false) {
-    const err = new Error(message);
-    err.name = 'GraphStoreError';
-    err.code = code;
-    err.legacyFallback = legacyFallback;
-    return err;
-}
-function safeSessionRuntimeRoot(projectRoot, sessionId) {
-    if (!WORKFLOW_ID_REGEX.test(sessionId)) {
-        throw makeError(PEAKS_GRAPH_REF_BROKEN, `invalid sessionId: ${sessionId}`);
-    }
-    const root = resolve(projectRoot);
-    return join(root, '.peaks', '_runtime', sessionId);
-}
-/** Compute the on-disk graph path. Validates `graphRef` stays under the session root. */
-export function graphPathFor(input) {
-    if (!isSafeRelativeGraphRef(input.graphRef, input.workflowId)) {
-        throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef is not safe: ${input.graphRef}`);
-    }
-    if (!WORKFLOW_ID_REGEX.test(input.workflowId)) {
-        throw makeError(PEAKS_GRAPH_REF_BROKEN, `workflowId is not safe: ${input.workflowId}`);
-    }
-    const sessionRoot = safeSessionRuntimeRoot(input.projectRoot, input.sessionId);
-    const resolved = resolve(sessionRoot, input.graphRef);
-    if (!resolved.startsWith(sessionRoot + sep) && resolved !== sessionRoot) {
-        throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef escapes session root: ${input.graphRef}`);
-    }
-    return resolved;
-}
+import { dirname } from 'node:path';
+import { isArray } from '../../shared/array-guards.js';
+import { WORKFLOW_ID_REGEX, NODE_ID_REGEX } from './workflow-graph-types.js';
+import { detectCycle, graphPathFor, makeError, PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_GRAPH_REF_BROKEN } from './workflow-graph-store-helpers.js';
+export { PEAKS_GRAPH_NOT_FOUND, PEAKS_GRAPH_CORRUPTED, PEAKS_GRAPH_CYCLE, PEAKS_GRAPH_REF_BROKEN, PEAKS_GRAPH_NODE_REQUIRED, PEAKS_GRAPH_NODE_NOT_PREPARED, PEAKS_GRAPH_NODE_KIND_INVALID, PEAKS_NODE_EXISTS, PEAKS_NODE_TRANSITION_INVALID, PEAKS_ENVELOPE_NOT_RECEIVED, PEAKS_ENVELOPE_GRAPH_MISMATCH, PEAKS_TERMINAL_REASON_INVALID, PEAKS_TERMINALIZE_ATOMICITY_FAILED, PEAKS_UNCONSUMED_ENVELOPE, PEAKS_DEPENDENCY_NOT_CONSUMED, PEAKS_WORKFLOW_OWNS_PRESENCE_CLEAR, PEAKS_SESSION_NOT_BOUND, PEAKS_CALLER_NOT_RESOLVED, graphPathFor, emptyGraph } from './workflow-graph-store-helpers.js';
 /** Atomically write a graph: tmp + rename. */
 function writeAtomic(targetPath, body) {
     const dir = dirname(targetPath);
@@ -79,7 +35,9 @@ function acquireLock(lockPath, holder, ttlMs = 30_000) {
             try {
                 unlinkSync(lockPath);
             }
-            catch { /* swallow */ }
+            catch {
+                /* swallow */
+            }
         }
         else {
             throw makeError('PEAKS_GRAPH_LOCK_HELD', `graph lock held: ${lockPath}`);
@@ -92,36 +50,9 @@ function releaseLock(lockPath) {
         if (existsSync(lockPath))
             unlinkSync(lockPath);
     }
-    catch { /* swallow */ }
-}
-/** Detect cycles in a node-dependency graph. */
-function detectCycle(nodes) {
-    const map = new Map();
-    for (const n of nodes)
-        map.set(n.id, n);
-    const color = new Map();
-    const visiting = (id) => {
-        const c = color.get(id) ?? 0;
-        if (c === 1)
-            return true;
-        if (c === 2)
-            return false;
-        color.set(id, 1);
-        const node = map.get(id);
-        if (node) {
-            for (const dep of node.dependsOn) {
-                if (visiting(dep))
-                    return true;
-            }
-        }
-        color.set(id, 2);
-        return false;
-    };
-    for (const n of nodes) {
-        if (visiting(n.id))
-            return true;
+    catch {
+        /* swallow */
     }
-    return false;
 }
 /** Validate a graph shape; throw `PEAKS_GRAPH_CORRUPTED` on any violation. */
 export function validateGraph(graph) {
@@ -138,9 +69,16 @@ export function validateGraph(graph) {
     if (g.parentWorkflowId !== undefined && typeof g.parentWorkflowId !== 'string') {
         throw makeError(PEAKS_GRAPH_CORRUPTED, 'parentWorkflowId must be a string when present');
     }
-    if (!Array.isArray(g.nodes))
+    // `isArray` (not `Array.isArray`, which is typed `arg is any[]`): the guard
+    // here is the same runtime check, but the built-in would widen `g.nodes` /
+    // `g.edges` from `readonly WorkflowNode[]` / `readonly WorkflowEdge[]` to
+    // `any[]`, making every access in the loops below an `any` access. The
+    // `=== undefined` half is the explicit price of a `boolean` helper — it
+    // cannot narrow, so defined-ness is stated in the open. See
+    // `src/shared/array-guards.ts`.
+    if (g.nodes === undefined || !isArray(g.nodes))
         throw makeError(PEAKS_GRAPH_CORRUPTED, 'nodes missing');
-    if (!Array.isArray(g.edges))
+    if (g.edges === undefined || !isArray(g.edges))
         throw makeError(PEAKS_GRAPH_CORRUPTED, 'edges missing');
     if (g.schemaVersion !== 1)
         throw makeError(PEAKS_GRAPH_CORRUPTED, 'schemaVersion must be 1');
@@ -159,7 +97,7 @@ export function validateGraph(graph) {
         if (typeof n.label !== 'string' || n.label.length === 0) {
             throw makeError(PEAKS_GRAPH_CORRUPTED, 'label missing');
         }
-        if (!Array.isArray(n.dependsOn)) {
+        if (!isArray(n.dependsOn)) {
             throw makeError(PEAKS_GRAPH_CORRUPTED, 'dependsOn must be an array');
         }
         if (n.kind === 'terminal')
@@ -181,6 +119,11 @@ export function validateGraph(graph) {
             throw makeError(PEAKS_GRAPH_CORRUPTED, `edge to unknown node: ${String(e.to)}`);
         }
     }
+    // S10: the two `as WorkflowGraphNode[]` casts that used to be here are gone.
+    // They existed only to undo the `Array.isArray` widening above; with `isArray`
+    // the receiver is already `readonly WorkflowGraphNode[]`, `detectCycle`
+    // already accepts that, so the casts were `no-unnecessary-type-assertion`
+    // after the fix and are simply deleted.
     for (const n of g.nodes) {
         for (const dep of n.dependsOn) {
             if (!ids.has(dep)) {
@@ -203,7 +146,7 @@ export function readGraph(input) {
             projectRoot: input.projectRoot ?? '',
             sessionId: input.sessionId ?? '',
             graphRef: input.graphRef ?? '',
-            workflowId: input.workflowId ?? '',
+            workflowId: input.workflowId ?? ''
         });
     if (!existsSync(path)) {
         throw makeError(PEAKS_GRAPH_NOT_FOUND, `graph not found: ${path}`);
@@ -225,8 +168,10 @@ export function readGraph(input) {
     }
     // Confirm parsed graph's workflowId matches the supplied one (when provided);
     // otherwise it's a graphRef mismatch (e.g. stale graph swapped under the lease).
-    if (typeof input.workflowId === 'string' && input.workflowId.length > 0
-        && typeof parsed === 'object' && parsed !== null) {
+    if (typeof input.workflowId === 'string' &&
+        input.workflowId.length > 0 &&
+        typeof parsed === 'object' &&
+        parsed !== null) {
         const wf = parsed.workflowId;
         if (typeof wf === 'string' && wf !== input.workflowId) {
             throw makeError(PEAKS_GRAPH_REF_BROKEN, `graphRef points at foreign workflow: ${wf} vs ${input.workflowId}`, false);
@@ -248,31 +193,9 @@ export function writeGraph(input) {
     }
     return { path };
 }
-/** Build a fresh empty graph with one terminal node. */
-export function emptyGraph(input) {
-    const graph = {
-        workflowId: input.workflowId,
-        rootSkill: input.rootSkill,
-        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
-        nodes: [
-            {
-                id: 'terminal',
-                kind: 'terminal',
-                label: 'workflow complete',
-                status: 'prepared',
-                dependsOn: [],
-                ackStatus: 'not-required',
-            },
-        ],
-        edges: [],
-        schemaVersion: 1,
-    };
-    return graph;
-}
 /** Validate a `graphRef` is well-formed without writing. */
 export function validateGraphRef(input) {
     return { path: graphPathFor(input) };
 }
 /** Suppress unused import warnings. */
-void isAbsolute;
 void dirname;

package/dist/services/workflow/workflow-graph-types.js

@@ -16,13 +16,13 @@ export const TERMINAL_REASONS = [
     'outer-session-mismatch',
     'parent-acked-no-envelope',
     'graph-corrupted',
-    'unknown',
+    'unknown'
 ];
 export const LEASE_STATUSES = [
     'preparing',
     'running',
     'terminalized',
-    'lost',
+    'lost'
 ];
 export const GRAPH_NODE_STATUSES = [
     'prepared',
@@ -31,7 +31,7 @@ export const GRAPH_NODE_STATUSES = [
     'envelope-received',
     'consumed-by-parent',
     'terminalized',
-    'lost',
+    'lost'
 ];
 /**
  * `id` regex: ASCII letters, digits, dot, underscore, hyphen; 1-200 chars.

package/dist/services/workflow/workflow-inflight-probe.js

@@ -8,6 +8,7 @@
  * production replacement for the previous lease-age `inFlightBatch`
  * computation in `auto-compact-orchestrator.ts`.
  */
+import { isArray } from '../../shared/array-guards.js';
 export const FRESH_RUNNING_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
 export const PEAKS_HEARTBEAT_MISSING = 'PEAKS_HEARTBEAT_MISSING';
 export const PEAKS_GRAPH_REF_BROKEN = 'PEAKS_GRAPH_REF_BROKEN';
@@ -18,7 +19,7 @@ const NON_RUNNING = new Set([
     'envelope-received',
     'consumed-by-parent',
     'terminalized',
-    'lost',
+    'lost'
 ]);
 export function probeInFlightBatch(input) {
     const nowMs = new Date(input.now).getTime();
@@ -30,15 +31,19 @@ export function probeInFlightBatch(input) {
             errors.push({
                 code: PEAKS_GRAPH_REF_BROKEN,
                 message: 'corrupt or missing graph',
-                ...(graph.graphRef ? { graphRef: graph.graphRef } : {}),
+                ...(graph.graphRef ? { graphRef: graph.graphRef } : {})
             });
             continue;
         }
-        if (!graph.nodes || !Array.isArray(graph.nodes)) {
+        // `isArray` (not `Array.isArray`, typed `arg is any[]`), so `graph.nodes`
+        // keeps its declared `ReadonlyArray<{...}>` and the loop below reads typed
+        // `node` fields. The `!graph.nodes` half already covers undefined. See
+        // `src/shared/array-guards.ts`.
+        if (!graph.nodes || !isArray(graph.nodes)) {
             errors.push({
                 code: PEAKS_GRAPH_CORRUPTED,
                 message: 'graph.nodes missing',
-                ...(graph.graphRef ? { graphRef: graph.graphRef } : {}),
+                ...(graph.graphRef ? { graphRef: graph.graphRef } : {})
             });
             continue;
         }
@@ -49,7 +54,7 @@ export function probeInFlightBatch(input) {
                 warnings.push({
                     code: PEAKS_HEARTBEAT_MISSING,
                     message: 'running node missing lastHeartbeat',
-                    ...(node.id ? { nodeId: node.id } : {}),
+                    ...(node.id ? { nodeId: node.id } : {})
                 });
                 continue;
             }
@@ -58,7 +63,7 @@ export function probeInFlightBatch(input) {
                 warnings.push({
                     code: PEAKS_HEARTBEAT_MISSING,
                     message: 'heartbeat unparseable',
-                    ...(node.id ? { nodeId: node.id } : {}),
+                    ...(node.id ? { nodeId: node.id } : {})
                 });
                 continue;
             }
@@ -79,7 +84,9 @@ export function probeInFlightBatch(input) {
         errors,
         reason: inFlight
             ? 'fresh-running-node'
-            : (errors.length > 0 ? 'corrupt-graphs' : 'no-fresh-running-node'),
+            : errors.length > 0
+                ? 'corrupt-graphs'
+                : 'no-fresh-running-node'
     };
 }
 void NON_RUNNING;

package/dist/services/workflow/workflow-loader.js

@@ -53,7 +53,11 @@ export function resolveWorkflow(projectRoot, id) {
     return {
         source: { kind: 'missing' },
         spec: emptySpec(id),
-        lint: { ok: false, errors: [`workflow "${id}" not found in project, global, or bundled locations`], warnings: [] }
+        lint: {
+            ok: false,
+            errors: [`workflow "${id}" not found in project, global, or bundled locations`],
+            warnings: []
+        }
     };
 }
 export function planWorkflow(spec, source) {

package/dist/services/workflow/workflow-node-lifecycle.js

@@ -9,8 +9,8 @@
  * Anti-fake-green rule: this module never imports a vendor env var.
  * The vendor signal lives entirely in the IDE adapters.
  */
-import { TERMINAL_REASONS, } from './workflow-graph-types.js';
-import { PEAKS_NODE_TRANSITION_INVALID, PEAKS_NODE_EXISTS, PEAKS_DEPENDENCY_NOT_CONSUMED, PEAKS_GRAPH_CYCLE, PEAKS_GRAPH_NODE_REQUIRED, PEAKS_GRAPH_NODE_KIND_INVALID, PEAKS_GRAPH_CORRUPTED, PEAKS_GRAPH_REF_BROKEN, PEAKS_ENVELOPE_NOT_RECEIVED, PEAKS_ENVELOPE_GRAPH_MISMATCH, PEAKS_TERMINAL_REASON_INVALID, } from './workflow-graph-store.js';
+import { TERMINAL_REASONS } from './workflow-graph-types.js';
+import { PEAKS_NODE_TRANSITION_INVALID, PEAKS_NODE_EXISTS, PEAKS_DEPENDENCY_NOT_CONSUMED, PEAKS_GRAPH_CYCLE, PEAKS_GRAPH_NODE_REQUIRED, PEAKS_GRAPH_NODE_KIND_INVALID, PEAKS_GRAPH_CORRUPTED, PEAKS_GRAPH_REF_BROKEN, PEAKS_ENVELOPE_NOT_RECEIVED, PEAKS_ENVELOPE_GRAPH_MISMATCH, PEAKS_TERMINAL_REASON_INVALID } from './workflow-graph-store.js';
 function lifeError(code, message) {
     const err = new Error(message);
     err.name = 'LifecycleError';
@@ -22,7 +22,7 @@ const LEASE_FROM_BY_TO = {
     preparing: ['running', 'terminalized', 'lost'],
     running: ['terminalized', 'lost'],
     terminalized: [],
-    lost: [],
+    lost: []
 };
 export function transitionLease(from, to, input = {}) {
     const allowed = LEASE_FROM_BY_TO[from] ?? [];
@@ -44,7 +44,8 @@ export function transitionLease(from, to, input = {}) {
             throw lifeError(PEAKS_TERMINAL_REASON_INVALID, `terminalReason missing or invalid: ${String(reason)}`);
         }
         result.terminalReason = reason;
-        result.terminalAt = typeof input.terminalAt === 'string' ? input.terminalAt : new Date().toISOString();
+        result.terminalAt =
+            typeof input.terminalAt === 'string' ? input.terminalAt : new Date().toISOString();
         if (to === 'terminalized' && reason === 'unknown') {
             // `success` is the only valid success reason for terminalized; anything
             // else maps to `lost` per RD §3.
@@ -58,16 +59,15 @@ export function transitionLease(from, to, input = {}) {
         result.lastHeartbeat = input.lastHeartbeat;
     }
     else if (to === 'running') {
-        result.lastHeartbeat = typeof input.lastHeartbeat === 'string'
-            ? input.lastHeartbeat
-            : new Date().toISOString();
+        result.lastHeartbeat =
+            typeof input.lastHeartbeat === 'string' ? input.lastHeartbeat : new Date().toISOString();
     }
     // Caller-scoped terminalization: if expectedCallerId was supplied and
     // doesn't match the input's callerId, fail closed (caller cannot clear a
     // different caller's lease).
-    if (typeof input.expectedCallerId === 'string'
-        && typeof input.callerId === 'string'
-        && input.callerId !== input.expectedCallerId) {
+    if (typeof input.expectedCallerId === 'string' &&
+        typeof input.callerId === 'string' &&
+        input.callerId !== input.expectedCallerId) {
         throw lifeError(PEAKS_NODE_TRANSITION_INVALID, `callerId ${input.callerId} != expected ${input.expectedCallerId}`);
     }
     // ttl-expired requires both age thresholds to hold (RD §3).
@@ -92,7 +92,7 @@ const NODE_FROM_BY_TO = {
     'envelope-received': ['consumed-by-parent', 'lost'],
     'consumed-by-parent': ['terminalized'],
     terminalized: [],
-    lost: [],
+    lost: []
 };
 export function transitionNode(from, to, input = {}) {
     // Graph corruption fires BEFORE the transition guard so a caller
@@ -119,7 +119,9 @@ export function transitionNode(from, to, input = {}) {
     if (to === 'envelope-received') {
         const nodeDispatchRef = typeof input.dispatchRef === 'string' ? input.dispatchRef : null;
         const envelopeDispatchRef = typeof input.envelopeDispatchRef === 'string' ? input.envelopeDispatchRef : null;
-        if (nodeDispatchRef !== null && envelopeDispatchRef !== null && nodeDispatchRef !== envelopeDispatchRef) {
+        if (nodeDispatchRef !== null &&
+            envelopeDispatchRef !== null &&
+            nodeDispatchRef !== envelopeDispatchRef) {
             throw lifeError(PEAKS_ENVELOPE_GRAPH_MISMATCH, `dispatchRef mismatch: ${nodeDispatchRef} vs ${envelopeDispatchRef}`);
         }
     }
@@ -149,9 +151,8 @@ export function transitionNode(from, to, input = {}) {
         result.lastHeartbeat = input.lastHeartbeat;
     }
     else if (to === 'running' || to === 'dispatched') {
-        result.lastHeartbeat = typeof input.lastHeartbeat === 'string'
-            ? input.lastHeartbeat
-            : new Date().toISOString();
+        result.lastHeartbeat =
+            typeof input.lastHeartbeat === 'string' ? input.lastHeartbeat : new Date().toISOString();
     }
     return result;
 }
@@ -233,7 +234,7 @@ export function buildGraphNode(input) {
         ...(input.dispatchRef ? { dispatchRef: input.dispatchRef } : {}),
         ...(input.lastHeartbeat ? { lastHeartbeat: input.lastHeartbeat } : {}),
         ...(input.ackStatus ? { ackStatus: input.ackStatus } : {}),
-        dependsOn: input.dependsOn ?? [],
+        dependsOn: input.dependsOn ?? []
     };
 }
 export function resolveDispatchBinding(input) {
@@ -272,7 +273,7 @@ export function prepareNodeAction(input) {
         ...(input.dispatchRef ? { dispatchRef: input.dispatchRef } : {}),
         ...(input.lastHeartbeat ? { lastHeartbeat: input.lastHeartbeat } : {}),
         ...(input.graphNode?.ackStatus ? { ackStatus: input.graphNode.ackStatus } : {}),
-        dependsOn,
+        dependsOn
     });
 }
 export function dispatchNode(input) {
@@ -281,7 +282,7 @@ export function dispatchNode(input) {
     }
     return transitionNode('prepared', 'dispatched', {
         graphNode: input.graphNode,
-        dispatchRef: input.dispatchRef,
+        dispatchRef: input.dispatchRef
     });
 }
 export function heartbeatNode(input) {
@@ -291,7 +292,7 @@ export function heartbeatNode(input) {
             graphNode: input.graphNode,
             firstHeartbeat: true,
             lastHeartbeat: input.lastHeartbeat,
-            dispatchRef: input.dispatchRef,
+            dispatchRef: input.dispatchRef
         });
     }
     // Subsequent heartbeat — idempotent self-update, only bumps timestamp.
@@ -299,14 +300,14 @@ export function heartbeatNode(input) {
         graphNode: input.graphNode,
         firstHeartbeat: false,
         lastHeartbeat: input.lastHeartbeat,
-        probe: false,
+        probe: false
     });
 }
 export function writeEnvelope(input) {
     return transitionNode('running', 'envelope-received', {
         graphNode: input.graphNode,
         dispatchRef: input.dispatchRef,
-        envelopeDispatchRef: input.envelopeDispatchRef ?? input.dispatchRef,
+        envelopeDispatchRef: input.envelopeDispatchRef ?? input.dispatchRef
     });
 }
 export function ackNode(input) {

package/dist/services/workflow/workflow-presence-lifecycle-types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * workflow-presence-lifecycle-types.ts — input/result/error interfaces of
+ * the workflow presence lifecycle orchestrator.
+ *
+ * Extracted verbatim from `workflow-presence-lifecycle.ts` for the 300-line
+ * file-size cap (`.peaks/docs/lint-gate.md` §4 row 5). The original module
+ * re-exports every name below, so importers keep using that path unchanged.
+ */
+import { type WorkflowGraph, type WorkflowId, type TerminalReason } from './workflow-graph-types.js';
+import type { SkillPresenceLease, PresenceIndex } from '../skills/presence-lease-types.js';
+export interface InitWorkflowInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly callerId: string;
+    readonly skill: string;
+    readonly workflowId?: WorkflowId;
+    readonly parentWorkflowId?: WorkflowId;
+    readonly graphRef?: string;
+    readonly depth?: number;
+    readonly now?: string;
+}
+export interface InitWorkflowResult {
+    readonly workflowId: WorkflowId;
+    readonly graphRef: string;
+    readonly graph: WorkflowGraph;
+    readonly lease: SkillPresenceLease;
+    readonly index: PresenceIndex;
+    readonly events: ReadonlyArray<Record<string, unknown>>;
+}
+export interface TerminalizeWorkflowInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly callerId: string;
+    readonly workflowId: WorkflowId;
+    readonly graphRef: string;
+    readonly reason: TerminalReason;
+    readonly requireConsumed?: boolean;
+    readonly now?: string;
+}
+export interface TerminalizeWorkflowResult {
+    readonly lease: SkillPresenceLease;
+    readonly graph: WorkflowGraph;
+    readonly events: ReadonlyArray<Record<string, unknown>>;
+    readonly indexCleared: boolean;
+}
+export interface TerminalizeError extends Error {
+    readonly code: string;
+    readonly successEventCount?: number;
+    readonly consistent?: boolean;
+}

package/dist/services/workflow/workflow-presence-lifecycle-types.js

@@ -0,0 +1 @@
+export {};