@substrate-ai/factory 0.19.54

package/dist/convergence/budget.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Per-node retry budget enforcement for the convergence loop.
+ * Story 45-3: provides pure budget primitives — no I/O, no side effects.
+ *
+ * Consumed by:
+ *   - Story 45-4 (per-pipeline budget enforcement)
+ *   - Story 45-8 (convergence controller integration)
+ */
+/**
+ * Discriminated union returned by `checkNodeBudget`.
+ *
+ * - `{ allowed: true }` — the node may attempt another retry.
+ * - `{ allowed: false; reason: string }` — the budget is exhausted; the
+ *   executor should not schedule another attempt.
+ */
+export type BudgetCheckResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+/**
+ * Options controlling the exponential-backoff delay calculation.
+ *
+ * All fields are optional; the defaults produce delays of 200 ms, 400 ms,
+ * 800 ms … capped at 60 000 ms, with ±50 % jitter.
+ */
+export interface BackoffOptions {
+    /** Initial delay in milliseconds for attempt index 0. Default: 200. */
+    initialDelay?: number;
+    /** Multiplicative factor applied each attempt. Default: 2. */
+    factor?: number;
+    /** Maximum delay in milliseconds before jitter is applied. Default: 60000. */
+    maxDelay?: number;
+    /**
+     * Fraction of the capped delay used as the jitter amplitude.
+     * A value of 0.5 produces ±50 % variance; 0 disables jitter entirely.
+     * Default: 0.5.
+     */
+    jitterFactor?: number;
+}
+/**
+ * Determine whether a node is permitted to make another retry attempt.
+ *
+ * @param nodeId    - Identifier of the node (used only for future diagnostics;
+ *                    not examined by this function).
+ * @param retryCount - Number of retries already consumed (0 on first failure).
+ * @param maxRetries - Maximum number of retries allowed for the node.
+ * @returns `{ allowed: true }` when `retryCount < maxRetries`, otherwise
+ *          `{ allowed: false, reason: 'max retries exhausted' }`.
+ */
+export declare function checkNodeBudget(nodeId: string, retryCount: number, maxRetries: number): BudgetCheckResult;
+/**
+ * Compute the delay (in milliseconds) before the next retry attempt.
+ *
+ * Formula (before jitter):
+ *   `baseDelay = initialDelay * factor^attemptIndex`
+ *   `cappedDelay = Math.min(baseDelay, maxDelay)`
+ *
+ * Jitter:
+ *   `jitter = (Math.random() * 2 - 1) * jitterFactor * cappedDelay`
+ *   `delay = Math.max(0, Math.round(cappedDelay + jitter))`
+ *
+ * Passing `{ jitterFactor: 0 }` disables jitter for deterministic tests.
+ *
+ * @param attemptIndex - Zero-based index of the current attempt (0 = first retry).
+ * @param options      - Optional overrides for the backoff parameters.
+ */
+export declare function computeBackoffDelay(attemptIndex: number, options?: BackoffOptions): number;
+/**
+ * Determine whether a pipeline is permitted to dispatch the next node.
+ *
+ * **Unlimited mode:** When `cap === 0` the function returns `{ allowed: true }`
+ * immediately, regardless of `accumulatedCost`. This matches the
+ * `FactoryConfigSchema` default of `budget_cap_usd: 0` which means "no limit".
+ *
+ * **Strict greater-than boundary:** Enforcement triggers only when
+ * `accumulatedCost > cap`. A cost that exactly equals the cap is still allowed,
+ * consistent with the PRD wording "halts *before* dispatching further nodes
+ * when accumulated cost **exceeds** the cap."
+ *
+ * @param accumulatedCost - Total cost (USD) spent so far during this pipeline run.
+ * @param cap             - Maximum allowed cost (USD). `0` disables enforcement.
+ * @returns `{ allowed: true }` when the pipeline may continue, or
+ *          `{ allowed: false, reason: '...' }` when the budget is exhausted.
+ */
+export declare function checkPipelineBudget(accumulatedCost: number, cap: number): BudgetCheckResult;
+/**
+ * Tracks accumulated cost for a single pipeline run and enforces a configurable
+ * spending cap via `checkPipelineBudget`.
+ *
+ * **Lifecycle:** Create one instance per pipeline run. Story 45-8 will call
+ * `addCost()` after each node dispatch completes and `checkBudget()` before
+ * the next dispatch. Call `reset()` between pipeline runs or in tests to clear
+ * accumulated state.
+ */
+export declare class PipelineBudgetManager {
+    private totalCost;
+    /**
+     * Add `amount` USD to the running total for this pipeline run.
+     *
+     * @param amount - Cost (USD) for the just-completed node dispatch.
+     */
+    addCost(amount: number): void;
+    /**
+     * Return the total cost (USD) accumulated so far during this pipeline run.
+     */
+    getTotalCost(): number;
+    /**
+     * Reset the accumulated cost to zero.
+     * Useful for test isolation and future pipeline reuse scenarios.
+     */
+    reset(): void;
+    /**
+     * Determine whether the pipeline may dispatch the next node, delegating to
+     * `checkPipelineBudget` with the current accumulated cost.
+     *
+     * @param cap - Maximum allowed cost (USD). `0` disables enforcement.
+     */
+    checkBudget(cap: number): BudgetCheckResult;
+}
+/**
+ * Determine whether a pipeline session is permitted to dispatch the next node
+ * based on wall-clock elapsed time.
+ *
+ * **Unlimited mode:** When `capMs === 0` the function returns `{ allowed: true }`
+ * immediately, regardless of `elapsedMs`. This matches the `FactoryConfigSchema`
+ * default of `wall_clock_cap_seconds: 0` which means "no limit".
+ *
+ * **Strict greater-than boundary:** Enforcement triggers only when
+ * `elapsedMs > capMs`. An elapsed time that exactly equals the cap is still
+ * allowed, consistent with the PRD wording "halts *before* dispatching further
+ * nodes when elapsed time **exceeds** the cap."
+ *
+ * @param elapsedMs - Milliseconds elapsed since the pipeline session started.
+ * @param capMs     - Maximum allowed elapsed time in milliseconds. `0` disables
+ *                    enforcement (unlimited mode).
+ * @returns `{ allowed: true }` when the session may continue, or
+ *          `{ allowed: false, reason: 'wall clock budget exhausted' }` when the
+ *          cap has been exceeded.
+ */
+export declare function checkSessionBudget(elapsedMs: number, capMs: number): BudgetCheckResult;
+/**
+ * Tracks wall-clock elapsed time for a single pipeline session and enforces a
+ * configurable time cap via `checkSessionBudget`.
+ *
+ * **Lifecycle:** Create one instance per pipeline run, constructed at pipeline
+ * launch. Story 45-8 will call `checkBudget()` before each node dispatch as
+ * the highest-priority budget check (before `PipelineBudgetManager`).
+ * Call `reset()` between pipeline runs or in tests for
+ * isolation.
+ *
+ * **Cap 0 means unlimited:** A `capSeconds` value of `0` passed to `checkBudget`
+ * disables all wall-clock enforcement and always returns `{ allowed: true }`.
+ */
+export declare class SessionBudgetManager {
+    private startTime;
+    constructor();
+    /**
+     * Return the number of milliseconds elapsed since this manager was constructed
+     * (or since the last `reset()` call). Always returns a non-negative number.
+     */
+    getElapsedMs(): number;
+    /**
+     * Reset the session start timestamp to the current time. Subsequent calls to
+     * `getElapsedMs()` will measure from this new baseline. Useful for test
+     * isolation and future pipeline reuse scenarios.
+     */
+    reset(): void;
+    /**
+     * Determine whether the pipeline session may dispatch the next node, delegating
+     * to `checkSessionBudget` with the current elapsed time converted from seconds
+     * to milliseconds.
+     *
+     * @param capSeconds - Maximum allowed elapsed time in **seconds** (as stored in
+     *                     `FactoryConfig.wall_clock_cap_seconds`). A value of `0`
+     *                     disables enforcement.
+     */
+    checkBudget(capSeconds: number): BudgetCheckResult;
+}
+//# sourceMappingURL=budget.d.ts.map

package/dist/convergence/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/convergence/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtF;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAKnB;AAaD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAU1F;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAW3F;AAMD;;;;;;;;GAQG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,SAAS,CAAI;IAErB;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI7B;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB;CAG5C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAQtF;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,SAAS,CAAQ;;IAMzB;;;OAGG;IACH,YAAY,IAAI,MAAM;IAItB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;OAQG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB;CAGnD"}

package/dist/convergence/budget.js

@@ -0,0 +1,218 @@
+/**
+ * Per-node retry budget enforcement for the convergence loop.
+ * Story 45-3: provides pure budget primitives — no I/O, no side effects.
+ *
+ * Consumed by:
+ *   - Story 45-4 (per-pipeline budget enforcement)
+ *   - Story 45-8 (convergence controller integration)
+ */
+// ---------------------------------------------------------------------------
+// Budget check
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a node is permitted to make another retry attempt.
+ *
+ * @param nodeId    - Identifier of the node (used only for future diagnostics;
+ *                    not examined by this function).
+ * @param retryCount - Number of retries already consumed (0 on first failure).
+ * @param maxRetries - Maximum number of retries allowed for the node.
+ * @returns `{ allowed: true }` when `retryCount < maxRetries`, otherwise
+ *          `{ allowed: false, reason: 'max retries exhausted' }`.
+ */
+export function checkNodeBudget(nodeId, retryCount, maxRetries) {
+    if (retryCount < maxRetries) {
+        return { allowed: true };
+    }
+    return { allowed: false, reason: 'max retries exhausted' };
+}
+// ---------------------------------------------------------------------------
+// Exponential backoff
+// ---------------------------------------------------------------------------
+const DEFAULT_BACKOFF = {
+    initialDelay: 200,
+    factor: 2,
+    maxDelay: 60_000,
+    jitterFactor: 0.5,
+};
+/**
+ * Compute the delay (in milliseconds) before the next retry attempt.
+ *
+ * Formula (before jitter):
+ *   `baseDelay = initialDelay * factor^attemptIndex`
+ *   `cappedDelay = Math.min(baseDelay, maxDelay)`
+ *
+ * Jitter:
+ *   `jitter = (Math.random() * 2 - 1) * jitterFactor * cappedDelay`
+ *   `delay = Math.max(0, Math.round(cappedDelay + jitter))`
+ *
+ * Passing `{ jitterFactor: 0 }` disables jitter for deterministic tests.
+ *
+ * @param attemptIndex - Zero-based index of the current attempt (0 = first retry).
+ * @param options      - Optional overrides for the backoff parameters.
+ */
+export function computeBackoffDelay(attemptIndex, options) {
+    const { initialDelay, factor, maxDelay, jitterFactor } = {
+        ...DEFAULT_BACKOFF,
+        ...options,
+    };
+    const baseDelay = initialDelay * Math.pow(factor, attemptIndex);
+    const cappedDelay = Math.min(baseDelay, maxDelay);
+    const jitter = (Math.random() * 2 - 1) * jitterFactor * cappedDelay;
+    return Math.max(0, Math.round(cappedDelay + jitter));
+}
+// ---------------------------------------------------------------------------
+// Per-pipeline budget enforcement — story 45-4
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a pipeline is permitted to dispatch the next node.
+ *
+ * **Unlimited mode:** When `cap === 0` the function returns `{ allowed: true }`
+ * immediately, regardless of `accumulatedCost`. This matches the
+ * `FactoryConfigSchema` default of `budget_cap_usd: 0` which means "no limit".
+ *
+ * **Strict greater-than boundary:** Enforcement triggers only when
+ * `accumulatedCost > cap`. A cost that exactly equals the cap is still allowed,
+ * consistent with the PRD wording "halts *before* dispatching further nodes
+ * when accumulated cost **exceeds** the cap."
+ *
+ * @param accumulatedCost - Total cost (USD) spent so far during this pipeline run.
+ * @param cap             - Maximum allowed cost (USD). `0` disables enforcement.
+ * @returns `{ allowed: true }` when the pipeline may continue, or
+ *          `{ allowed: false, reason: '...' }` when the budget is exhausted.
+ */
+export function checkPipelineBudget(accumulatedCost, cap) {
+    if (cap === 0) {
+        return { allowed: true };
+    }
+    if (accumulatedCost > cap) {
+        return {
+            allowed: false,
+            reason: `pipeline budget exhausted: $${accumulatedCost.toFixed(2)} > $${cap.toFixed(2)}`,
+        };
+    }
+    return { allowed: true };
+}
+// ---------------------------------------------------------------------------
+// PipelineBudgetManager
+// ---------------------------------------------------------------------------
+/**
+ * Tracks accumulated cost for a single pipeline run and enforces a configurable
+ * spending cap via `checkPipelineBudget`.
+ *
+ * **Lifecycle:** Create one instance per pipeline run. Story 45-8 will call
+ * `addCost()` after each node dispatch completes and `checkBudget()` before
+ * the next dispatch. Call `reset()` between pipeline runs or in tests to clear
+ * accumulated state.
+ */
+export class PipelineBudgetManager {
+    totalCost = 0;
+    /**
+     * Add `amount` USD to the running total for this pipeline run.
+     *
+     * @param amount - Cost (USD) for the just-completed node dispatch.
+     */
+    addCost(amount) {
+        this.totalCost += amount;
+    }
+    /**
+     * Return the total cost (USD) accumulated so far during this pipeline run.
+     */
+    getTotalCost() {
+        return this.totalCost;
+    }
+    /**
+     * Reset the accumulated cost to zero.
+     * Useful for test isolation and future pipeline reuse scenarios.
+     */
+    reset() {
+        this.totalCost = 0;
+    }
+    /**
+     * Determine whether the pipeline may dispatch the next node, delegating to
+     * `checkPipelineBudget` with the current accumulated cost.
+     *
+     * @param cap - Maximum allowed cost (USD). `0` disables enforcement.
+     */
+    checkBudget(cap) {
+        return checkPipelineBudget(this.totalCost, cap);
+    }
+}
+// ---------------------------------------------------------------------------
+// Per-session budget enforcement — story 45-5
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether a pipeline session is permitted to dispatch the next node
+ * based on wall-clock elapsed time.
+ *
+ * **Unlimited mode:** When `capMs === 0` the function returns `{ allowed: true }`
+ * immediately, regardless of `elapsedMs`. This matches the `FactoryConfigSchema`
+ * default of `wall_clock_cap_seconds: 0` which means "no limit".
+ *
+ * **Strict greater-than boundary:** Enforcement triggers only when
+ * `elapsedMs > capMs`. An elapsed time that exactly equals the cap is still
+ * allowed, consistent with the PRD wording "halts *before* dispatching further
+ * nodes when elapsed time **exceeds** the cap."
+ *
+ * @param elapsedMs - Milliseconds elapsed since the pipeline session started.
+ * @param capMs     - Maximum allowed elapsed time in milliseconds. `0` disables
+ *                    enforcement (unlimited mode).
+ * @returns `{ allowed: true }` when the session may continue, or
+ *          `{ allowed: false, reason: 'wall clock budget exhausted' }` when the
+ *          cap has been exceeded.
+ */
+export function checkSessionBudget(elapsedMs, capMs) {
+    if (capMs === 0) {
+        return { allowed: true };
+    }
+    if (elapsedMs > capMs) {
+        return { allowed: false, reason: 'wall clock budget exhausted' };
+    }
+    return { allowed: true };
+}
+/**
+ * Tracks wall-clock elapsed time for a single pipeline session and enforces a
+ * configurable time cap via `checkSessionBudget`.
+ *
+ * **Lifecycle:** Create one instance per pipeline run, constructed at pipeline
+ * launch. Story 45-8 will call `checkBudget()` before each node dispatch as
+ * the highest-priority budget check (before `PipelineBudgetManager`).
+ * Call `reset()` between pipeline runs or in tests for
+ * isolation.
+ *
+ * **Cap 0 means unlimited:** A `capSeconds` value of `0` passed to `checkBudget`
+ * disables all wall-clock enforcement and always returns `{ allowed: true }`.
+ */
+export class SessionBudgetManager {
+    startTime;
+    constructor() {
+        this.startTime = Date.now();
+    }
+    /**
+     * Return the number of milliseconds elapsed since this manager was constructed
+     * (or since the last `reset()` call). Always returns a non-negative number.
+     */
+    getElapsedMs() {
+        return Date.now() - this.startTime;
+    }
+    /**
+     * Reset the session start timestamp to the current time. Subsequent calls to
+     * `getElapsedMs()` will measure from this new baseline. Useful for test
+     * isolation and future pipeline reuse scenarios.
+     */
+    reset() {
+        this.startTime = Date.now();
+    }
+    /**
+     * Determine whether the pipeline session may dispatch the next node, delegating
+     * to `checkSessionBudget` with the current elapsed time converted from seconds
+     * to milliseconds.
+     *
+     * @param capSeconds - Maximum allowed elapsed time in **seconds** (as stored in
+     *                     `FactoryConfig.wall_clock_cap_seconds`). A value of `0`
+     *                     disables enforcement.
+     */
+    checkBudget(capSeconds) {
+        return checkSessionBudget(this.getElapsedMs(), capSeconds * 1000);
+    }
+}
+//# sourceMappingURL=budget.js.map

package/dist/convergence/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/convergence/budget.ts"],"names":[],"mappings":"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"}

package/dist/convergence/controller.d.ts

@@ -0,0 +1,133 @@
+/**
+ * ConvergenceController — tracks node outcomes and evaluates goal gates.
+ *
+ * Implements the Attractor spec's convergence semantics: at the exit node,
+ * every node marked `goalGate=true` must have completed with either `SUCCESS`
+ * or `PARTIAL_SUCCESS` for the pipeline to exit normally.
+ *
+ * Story 42-16.
+ * Story 49-3: AutoSummarizer integration for long-running convergence loops.
+ */
+import type { Graph, GraphNode, IGraphContext, OutcomeStatus } from '../graph/types.js';
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+import type { AutoSummarizer, IterationContext, CompressedIterationContext } from '../context/auto-summarizer.js';
+/**
+ * Configuration for ConvergenceController.
+ * All fields are optional; defaults are applied in createConvergenceController().
+ */
+export interface ConvergenceControllerConfig {
+    /**
+     * Optional AutoSummarizer for compressing older iteration contexts before
+     * each iteration dispatch. When omitted, iteration context management is
+     * a no-op and no summarization occurs.
+     */
+    autoSummarizer?: AutoSummarizer;
+}
+/**
+ * Options for checkGoalGates() — enables score-based gate evaluation.
+ * Story 46-2.
+ */
+export interface CheckGoalGatesOptions {
+    /** Pipeline context for reading satisfaction_score. Required when satisfactionThreshold is set. */
+    context?: IGraphContext;
+    /** Threshold for satisfaction gate: gate passes when satisfaction_score >= satisfactionThreshold. */
+    satisfactionThreshold?: number;
+}
+/**
+ * Result of evaluating all goal gate nodes in a graph.
+ */
+export interface GoalGateResult {
+    satisfied: boolean;
+    failedGates: string[];
+}
+/**
+ * Tracks per-node outcomes and evaluates goal gate satisfaction.
+ */
+export interface ConvergenceController {
+    /**
+     * Record the final outcome status for a completed node.
+     * Called by the executor after the allowPartial demotion check.
+     */
+    recordOutcome(nodeId: string, status: OutcomeStatus): void;
+    /**
+     * Evaluate whether all `goalGate=true` nodes have been satisfied.
+     *
+     * A goal gate node is satisfied when its recorded outcome is `SUCCESS` or
+     * `PARTIAL_SUCCESS`. Nodes with no recorded outcome are treated as unsatisfied.
+     * Graphs with no goal gate nodes are vacuously satisfied.
+     *
+     * NOTE: This is the simpler, event-free predecessor to `checkGoalGates()`.
+     * The executor uses `checkGoalGates()` exclusively (which adds event emission
+     * and score-based evaluation). `evaluateGates()` is retained for direct
+     * controller unit tests and Attractor spec compliance tests (Section 3.4).
+     *
+     * @returns `{ satisfied: true, failingNodes: [] }` if all gates pass;
+     *          `{ satisfied: false, failingNodes: [id, ...] }` listing each
+     *          gate node that was not satisfied.
+     */
+    evaluateGates(graph: Graph): {
+        satisfied: boolean;
+        failingNodes: string[];
+    };
+    /**
+     * Evaluate all goal gate nodes and emit graph:goal-gate-checked for each.
+     * Returns satisfied=true only when every goalGate=true node recorded
+     * SUCCESS or PARTIAL_SUCCESS. Graphs with no goal gate nodes are vacuously satisfied.
+     *
+     * When options.satisfactionThreshold and options.context are both provided,
+     * satisfaction is determined by comparing satisfaction_score from context against
+     * the threshold (score >= threshold). Otherwise falls back to outcome-status evaluation.
+     */
+    checkGoalGates(graph: Graph, runId: string, eventBus?: TypedEventBus<FactoryEvents>, options?: CheckGoalGatesOptions): GoalGateResult;
+    /**
+     * Resolve the retry target after an unsatisfied goal gate by walking a
+     * 4-level priority chain:
+     *
+     *   1. `failedNode.retryTarget`         — node-level explicit target
+     *   2. `failedNode.fallbackRetryTarget`  — node-level fallback
+     *   3. `graph.retryTarget`               — graph-level default
+     *   4. `graph.fallbackRetryTarget`       — graph-level default fallback
+     *
+     * A candidate is valid only when the string is non-empty AND the node id
+     * exists in `graph.nodes`. Both empty strings and non-existent node ids are
+     * treated as absent and cause the resolution to fall through to the next level.
+     *
+     * @returns the first valid candidate node id, or `null` when no valid target
+     *          exists at any level (signalling that the pipeline must FAIL).
+     */
+    resolveRetryTarget(failedNode: GraphNode, graph: Graph): string | null;
+    /**
+     * Record an iteration's output as context for potential auto-summarization.
+     * Appends the context to the internal store.
+     * No-op if called with an empty content string (but still stores the context).
+     */
+    recordIterationContext(ctx: IterationContext): void;
+    /**
+     * Before dispatching the iteration at `currentIndex`, check if the accumulated
+     * iteration contexts have grown beyond the auto-summarizer's threshold. If so,
+     * all contexts with `index < currentIndex` are compressed, and the internal
+     * store is replaced with the compressed result.
+     *
+     * Purely opt-in: if no `autoSummarizer` was provided in the config, this method
+     * returns the current stored contexts without modification.
+     *
+     * @param currentIndex - The zero-based index of the iteration about to be dispatched
+     * @returns The (possibly compressed) stored iteration contexts
+     */
+    prepareForIteration(currentIndex: number): Promise<(IterationContext | CompressedIterationContext)[]>;
+    /**
+     * Return a snapshot of the currently stored iteration contexts.
+     * May include `CompressedIterationContext` objects if prepareForIteration()
+     * has triggered compression.
+     */
+    getStoredContexts(): (IterationContext | CompressedIterationContext)[];
+}
+/**
+ * Create a new `ConvergenceController` instance backed by an in-memory outcome map.
+ *
+ * @param config - Optional configuration. Pass `{ autoSummarizer }` to enable
+ *                 automatic context compression in long-running convergence loops.
+ */
+export declare function createConvergenceController(config?: ConvergenceControllerConfig): ConvergenceController;
+//# sourceMappingURL=controller.d.ts.map

package/dist/convergence/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/convergence/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAA;AAEjH;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,cAAc,CAAC,EAAE,cAAc,CAAA;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,OAAO,CAAC,EAAE,aAAa,CAAA;IACvB,qGAAqG;IACrG,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,OAAO,CAAA;IAClB,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IAE1D;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAE3E;;;;;;;;OAQG;IACH,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc,CAAA;IAErI;;;;;;;;;;;;;;;OAeG;IACH,kBAAkB,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAA;IAEtE;;;;OAIG;IACH,sBAAsB,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAEnD;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,gBAAgB,GAAG,0BAA0B,CAAC,EAAE,CAAC,CAAA;IAErG;;;;OAIG;IACH,iBAAiB,IAAI,CAAC,gBAAgB,GAAG,0BAA0B,CAAC,EAAE,CAAA;CACvE;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,CAAC,EAAE,2BAA2B,GAAG,qBAAqB,CA0GvG"}

package/dist/convergence/controller.js

@@ -0,0 +1,102 @@
+/**
+ * ConvergenceController — tracks node outcomes and evaluates goal gates.
+ *
+ * Implements the Attractor spec's convergence semantics: at the exit node,
+ * every node marked `goalGate=true` must have completed with either `SUCCESS`
+ * or `PARTIAL_SUCCESS` for the pipeline to exit normally.
+ *
+ * Story 42-16.
+ * Story 49-3: AutoSummarizer integration for long-running convergence loops.
+ */
+/**
+ * Create a new `ConvergenceController` instance backed by an in-memory outcome map.
+ *
+ * @param config - Optional configuration. Pass `{ autoSummarizer }` to enable
+ *                 automatic context compression in long-running convergence loops.
+ */
+export function createConvergenceController(config) {
+    const outcomes = new Map();
+    let storedContexts = [];
+    /** Returns true only when id is non-empty AND exists in graph.nodes. */
+    function isValidTarget(id, graph) {
+        return id !== '' && graph.nodes.has(id);
+    }
+    return {
+        recordOutcome(nodeId, status) {
+            outcomes.set(nodeId, status);
+        },
+        evaluateGates(graph) {
+            const failingNodes = [];
+            for (const [id, node] of graph.nodes) {
+                if (!node.goalGate)
+                    continue;
+                const status = outcomes.get(id);
+                if (status !== 'SUCCESS' && status !== 'PARTIAL_SUCCESS') {
+                    failingNodes.push(id);
+                }
+            }
+            return { satisfied: failingNodes.length === 0, failingNodes };
+        },
+        checkGoalGates(graph, runId, eventBus, options) {
+            const failedGates = [];
+            for (const [id, node] of graph.nodes) {
+                if (!node.goalGate)
+                    continue;
+                if (options?.satisfactionThreshold !== undefined && options?.context !== undefined) {
+                    const score = options.context.getNumber('satisfaction_score', 0);
+                    const satisfied = score >= options.satisfactionThreshold;
+                    eventBus?.emit('graph:goal-gate-checked', { runId, nodeId: id, satisfied, score });
+                    if (!satisfied)
+                        failedGates.push(id);
+                }
+                else {
+                    const status = outcomes.get(id);
+                    const satisfied = status === 'SUCCESS' || status === 'PARTIAL_SUCCESS';
+                    eventBus?.emit('graph:goal-gate-checked', { runId, nodeId: id, satisfied });
+                    if (!satisfied) {
+                        failedGates.push(id);
+                    }
+                }
+            }
+            return { satisfied: failedGates.length === 0, failedGates };
+        },
+        resolveRetryTarget(failedNode, graph) {
+            const candidates = [
+                failedNode.retryTarget,
+                failedNode.fallbackRetryTarget,
+                graph.retryTarget,
+                graph.fallbackRetryTarget,
+            ];
+            for (const candidate of candidates) {
+                if (isValidTarget(candidate, graph)) {
+                    return candidate;
+                }
+            }
+            return null;
+        },
+        recordIterationContext(ctx) {
+            storedContexts.push(ctx);
+        },
+        async prepareForIteration(currentIndex) {
+            if (!config?.autoSummarizer || storedContexts.length === 0) {
+                return storedContexts;
+            }
+            // Build an IterationContext[] from the stored plain contexts for the trigger check.
+            // CompressedIterationContext entries are excluded from the token sum (already compressed).
+            const uncompressedContexts = storedContexts.filter((c) => !('compressed' in c));
+            if (config.autoSummarizer.shouldTrigger(uncompressedContexts)) {
+                const compressionResult = await config.autoSummarizer.compress(uncompressedContexts, currentIndex);
+                // Merge compressed results back with any already-compressed contexts,
+                // maintaining index ordering.
+                const alreadyCompressed = storedContexts.filter((c) => 'compressed' in c);
+                const merged = [...alreadyCompressed, ...compressionResult.iterations].sort((a, b) => a.index - b.index);
+                storedContexts = merged;
+            }
+            return storedContexts;
+        },
+        getStoredContexts() {
+            return storedContexts;
+        },
+    };
+}
+//# sourceMappingURL=controller.js.map

package/dist/convergence/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../src/convergence/controller.ts"],"names":[],"mappings":"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"}