@substrate-ai/factory 0.19.54

package/dist/convergence/dual-signal.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Dual-signal coordinator — evaluates code review and scenario signals together.
+ *
+ * Code review is the authoritative Phase 2 decision-maker.
+ * Scenario score is a parallel signal used for monitoring and agreement tracking.
+ *
+ * Story 46-5.
+ */
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+/**
+ * Code review verdict union.
+ * Mirrors CodeReviewResult.verdict from story 43-5 without importing from @substrate-ai/sdlc
+ * (ADR-003: factory must not compile-time-depend on sdlc).
+ */
+export type DualSignalVerdict = 'SHIP_IT' | 'NEEDS_MINOR_FIXES' | 'NEEDS_MAJOR_REWORK' | 'LGTM_WITH_NOTES';
+/** Whether the two signals agree on the pass/fail outcome. */
+export type DualSignalAgreement = 'AGREE' | 'DISAGREE';
+/**
+ * Quality mode determines which signal is authoritative for goal gate decisions.
+ * Story 46-6.
+ */
+export type QualityMode = 'code-review' | 'dual-signal' | 'scenario-primary' | 'scenario-only';
+/**
+ * Context key under which code review handlers store their verdict.
+ * Used by the executor to read the verdict when emitting advisory events.
+ * Story 46-6.
+ */
+export declare const CONTEXT_KEY_CODE_REVIEW_VERDICT = "factory.codeReviewVerdict";
+/**
+ * Combined result of evaluating the code review verdict and scenario score.
+ */
+export interface DualSignalResult {
+    codeReviewPassed: boolean;
+    scenarioPassed: boolean;
+    agreement: DualSignalAgreement;
+    /** Code review is always the authoritative decision in Phase 2. */
+    authoritativeDecision: DualSignalVerdict;
+    score: number;
+    threshold: number;
+}
+/**
+ * Options for constructing a DualSignalCoordinator.
+ */
+export interface DualSignalCoordinatorOptions {
+    eventBus: TypedEventBus<FactoryEvents>;
+    threshold: number;
+    /** Quality mode — when 'scenario-primary', also emits scenario:advisory-computed. Story 46-6. */
+    qualityMode?: QualityMode;
+}
+/**
+ * Evaluates the dual signal on each story iteration and emits telemetry.
+ */
+export interface DualSignalCoordinator {
+    evaluate(codeReviewVerdict: DualSignalVerdict, scenarioScore: number, runId: string): DualSignalResult;
+}
+/**
+ * Evaluate dual signals without side effects.
+ *
+ * `SHIP_IT` and `LGTM_WITH_NOTES` are treated as code review passes.
+ * Code review verdict is always the authoritative decision.
+ */
+export declare function evaluateDualSignal(verdict: DualSignalVerdict, score: number, threshold: number): DualSignalResult;
+/**
+ * Create a DualSignalCoordinator that evaluates signals and emits
+ * `scenario:score-computed` events on each call.
+ *
+ * When `options.qualityMode === 'scenario-primary'`, also emits
+ * `scenario:advisory-computed` with the code review verdict as advisory info.
+ * Story 46-6.
+ */
+export declare function createDualSignalCoordinator(options: DualSignalCoordinatorOptions): DualSignalCoordinator;
+//# sourceMappingURL=dual-signal.d.ts.map

package/dist/convergence/dual-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-signal.d.ts","sourceRoot":"","sources":["../../src/convergence/dual-signal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAMjD;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,mBAAmB,GACnB,oBAAoB,GACpB,iBAAiB,CAAA;AAErB,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,UAAU,CAAA;AAEtD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,aAAa,GAAG,kBAAkB,GAAG,eAAe,CAAA;AAE9F;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,8BAA8B,CAAA;AAE1E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,OAAO,CAAA;IACzB,cAAc,EAAE,OAAO,CAAA;IACvB,SAAS,EAAE,mBAAmB,CAAA;IAC9B,mEAAmE;IACnE,qBAAqB,EAAE,iBAAiB,CAAA;IACxC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAA;CACvG;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAalB;AAMD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,qBAAqB,CA6BxG"}

package/dist/convergence/dual-signal.js

@@ -0,0 +1,78 @@
+/**
+ * Dual-signal coordinator — evaluates code review and scenario signals together.
+ *
+ * Code review is the authoritative Phase 2 decision-maker.
+ * Scenario score is a parallel signal used for monitoring and agreement tracking.
+ *
+ * Story 46-5.
+ */
+/**
+ * Context key under which code review handlers store their verdict.
+ * Used by the executor to read the verdict when emitting advisory events.
+ * Story 46-6.
+ */
+export const CONTEXT_KEY_CODE_REVIEW_VERDICT = 'factory.codeReviewVerdict';
+// ---------------------------------------------------------------------------
+// Pure function
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate dual signals without side effects.
+ *
+ * `SHIP_IT` and `LGTM_WITH_NOTES` are treated as code review passes.
+ * Code review verdict is always the authoritative decision.
+ */
+export function evaluateDualSignal(verdict, score, threshold) {
+    const codeReviewPassed = verdict === 'SHIP_IT' || verdict === 'LGTM_WITH_NOTES';
+    const scenarioPassed = score >= threshold;
+    const agreement = codeReviewPassed === scenarioPassed ? 'AGREE' : 'DISAGREE';
+    return {
+        codeReviewPassed,
+        scenarioPassed,
+        agreement,
+        authoritativeDecision: verdict,
+        score,
+        threshold,
+    };
+}
+// ---------------------------------------------------------------------------
+// Coordinator factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a DualSignalCoordinator that evaluates signals and emits
+ * `scenario:score-computed` events on each call.
+ *
+ * When `options.qualityMode === 'scenario-primary'`, also emits
+ * `scenario:advisory-computed` with the code review verdict as advisory info.
+ * Story 46-6.
+ */
+export function createDualSignalCoordinator(options) {
+    return {
+        evaluate(verdict, score, runId) {
+            const result = evaluateDualSignal(verdict, score, options.threshold);
+            options.eventBus.emit('scenario:score-computed', {
+                runId,
+                score: result.score,
+                threshold: result.threshold,
+                passes: result.scenarioPassed,
+                agreement: result.agreement,
+                codeReviewPassed: result.codeReviewPassed,
+                scenarioPassed: result.scenarioPassed,
+                authoritativeDecision: result.authoritativeDecision,
+            });
+            // In scenario-primary mode, emit code review verdict as advisory — story 46-6.
+            // The advisory event does not affect the gate decision; it is informational only.
+            if (options.qualityMode === 'scenario-primary') {
+                options.eventBus.emit('scenario:advisory-computed', {
+                    runId,
+                    verdict: result.authoritativeDecision,
+                    codeReviewPassed: result.codeReviewPassed,
+                    score: result.score,
+                    threshold: result.threshold,
+                    agreement: result.agreement,
+                });
+            }
+            return result;
+        },
+    };
+}
+//# sourceMappingURL=dual-signal.js.map

package/dist/convergence/dual-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-signal.js","sourceRoot":"","sources":["../../src/convergence/dual-signal.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA6BH;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,2BAA2B,CAAA;AAgC1E,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA0B,EAC1B,KAAa,EACb,SAAiB;IAEjB,MAAM,gBAAgB,GAAG,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,iBAAiB,CAAA;IAC/E,MAAM,cAAc,GAAG,KAAK,IAAI,SAAS,CAAA;IACzC,MAAM,SAAS,GAAwB,gBAAgB,KAAK,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAA;IAEjG,OAAO;QACL,gBAAgB;QAChB,cAAc;QACd,SAAS;QACT,qBAAqB,EAAE,OAAO;QAC9B,KAAK;QACL,SAAS;KACV,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAqC;IAC/E,OAAO;QACL,QAAQ,CAAC,OAA0B,EAAE,KAAa,EAAE,KAAa;YAC/D,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;YACpE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,yBAAyB,EAAE;gBAC/C,KAAK;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,MAAM,EAAE,MAAM,CAAC,cAAc;gBAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;aACpD,CAAC,CAAA;YACF,+EAA+E;YAC/E,kFAAkF;YAClF,IAAI,OAAO,CAAC,WAAW,KAAK,kBAAkB,EAAE,CAAC;gBAC/C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,4BAA4B,EAAE;oBAClD,KAAK;oBACL,OAAO,EAAE,MAAM,CAAC,qBAAqB;oBACrC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;oBACzC,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;iBAC5B,CAAC,CAAA;YACJ,CAAC;YACD,OAAO,MAAM,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/convergence/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Convergence subsystem barrel exports.
+ * Story 42-16.
+ */
+export type { ConvergenceController, ConvergenceControllerConfig, GoalGateResult, CheckGoalGatesOptions } from './controller.js';
+export { createConvergenceController } from './controller.js';
+export type { BudgetCheckResult, BackoffOptions } from './budget.js';
+export { checkNodeBudget, computeBackoffDelay } from './budget.js';
+export { checkPipelineBudget, PipelineBudgetManager } from './budget.js';
+export { checkSessionBudget, SessionBudgetManager } from './budget.js';
+export type { PlateauDetectorOptions, PlateauDetector, PlateauCheckContext, PlateauCheckResult } from './plateau.js';
+export { createPlateauDetector, checkPlateauAndEmit } from './plateau.js';
+export { REMEDIATION_CONTEXT_KEY, buildRemediationContext, formatScenarioDiff, deriveFixScope, injectRemediationContext, getRemediationContext } from './remediation.js';
+export type { RemediationContext, BuildRemediationContextParams } from './remediation.js';
+export type { DualSignalVerdict, DualSignalAgreement, DualSignalResult, DualSignalCoordinator, DualSignalCoordinatorOptions, QualityMode } from './dual-signal.js';
+export { evaluateDualSignal, createDualSignalCoordinator, CONTEXT_KEY_CODE_REVIEW_VERDICT } from './dual-signal.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/convergence/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AAChI,OAAO,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAG7D,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGlE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAGxE,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAGtE,YAAY,EAAE,sBAAsB,EAAE,eAAe,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACpH,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGzE,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AACxK,YAAY,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,kBAAkB,CAAA;AAGzF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAClK,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/convergence/index.js

@@ -0,0 +1,11 @@
+export { createConvergenceController } from './controller.js';
+export { checkNodeBudget, computeBackoffDelay } from './budget.js';
+// Per-pipeline budget enforcement — story 45-4
+export { checkPipelineBudget, PipelineBudgetManager } from './budget.js';
+// Per-session budget enforcement — story 45-5
+export { checkSessionBudget, SessionBudgetManager } from './budget.js';
+export { createPlateauDetector, checkPlateauAndEmit } from './plateau.js';
+// Remediation context injection — story 45-7
+export { REMEDIATION_CONTEXT_KEY, buildRemediationContext, formatScenarioDiff, deriveFixScope, injectRemediationContext, getRemediationContext } from './remediation.js';
+export { evaluateDualSignal, createDualSignalCoordinator, CONTEXT_KEY_CODE_REVIEW_VERDICT } from './dual-signal.js';
+//# sourceMappingURL=index.js.map

package/dist/convergence/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/convergence/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAI7D,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAElE,+CAA+C;AAC/C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExE,8CAA8C;AAC9C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAItE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAEzE,6CAA6C;AAC7C,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,cAAc,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAKxK,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/convergence/plateau.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Plateau detection for the convergence loop.
+ * Story 45-6: provides pure plateau detection primitives — no I/O, no side effects.
+ *
+ * Algorithm: Track the last N satisfaction scores (N = `window`, default 3).
+ * If max−min of the window falls strictly below threshold, declare plateau.
+ *
+ * Consumed by:
+ *   - Story 45-8 (convergence controller integration)
+ */
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+/**
+ * Options for configuring a PlateauDetector.
+ * Both fields are optional; defaults are window=3 and threshold=0.05.
+ */
+export interface PlateauDetectorOptions {
+    /** Number of most-recent scores to consider. Default: 3. */
+    window?: number;
+    /** Minimum spread (max−min) required to NOT declare a plateau. Default: 0.05. */
+    threshold?: number;
+}
+/**
+ * Tracks the last N satisfaction scores. If max−min of the window falls
+ * strictly below threshold, declare plateau.
+ *
+ * Pure in-memory data structure — no I/O, no event emission, no global state.
+ * Event emission is isolated to `checkPlateauAndEmit`.
+ */
+export interface PlateauDetector {
+    /**
+     * Record a new satisfaction score for the given iteration.
+     * After recording, only the last `window` scores are retained.
+     */
+    recordScore(iteration: number, score: number): void;
+    /**
+     * Return `true` when the current window of scores qualifies as a plateau:
+     * - The window is full (at least `window` scores recorded), AND
+     * - `Math.max(...scores) - Math.min(...scores) < threshold` (strictly less than)
+     *
+     * Returns `false` when insufficient data or when the spread meets/exceeds the threshold.
+     */
+    isPlateaued(): boolean;
+    /**
+     * Return the configured window size.
+     * Used by `checkPlateauAndEmit` to construct the event payload.
+     */
+    getWindow(): number;
+    /**
+     * Return a defensive copy of the current score window.
+     * Callers cannot mutate the detector's internal array via this method.
+     */
+    getScores(): number[];
+}
+/**
+ * Context passed to `checkPlateauAndEmit`.
+ */
+export interface PlateauCheckContext {
+    runId: string;
+    nodeId: string;
+    /** Optional event bus. When provided and a plateau is detected, emits `convergence:plateau-detected`. */
+    eventBus?: TypedEventBus<FactoryEvents>;
+}
+/**
+ * Result returned by `checkPlateauAndEmit`.
+ */
+export interface PlateauCheckResult {
+    plateaued: boolean;
+    scores: number[];
+}
+/**
+ * Create a new PlateauDetector with the given options.
+ *
+ * **Defaults:** `window=3`, `threshold=0.05` — matching `FactoryConfigSchema.plateau_window`
+ * and `FactoryConfigSchema.plateau_threshold`. Story 45-8 will read these values from
+ * `FactoryConfig` and pass them in.
+ *
+ * **Insufficient-data guard:** `isPlateaued()` always returns `false` when fewer than
+ * `window` scores have been recorded. A plateau can only be declared once the window is full.
+ *
+ * @param options - Optional configuration for window size and threshold.
+ */
+export declare function createPlateauDetector(options?: PlateauDetectorOptions): PlateauDetector;
+/**
+ * Check whether the detector has reached a plateau and, if so, emit the
+ * `convergence:plateau-detected` event on the provided event bus.
+ *
+ * This mirrors the `checkGoalGates()` pattern:
+ * - Pure detection is isolated in `PlateauDetector` (no side effects).
+ * - Event emission is isolated here in this wrapper.
+ * - Callers may omit `eventBus` for pure check behavior (no event is emitted).
+ *
+ * @param detector - A `PlateauDetector` instance.
+ * @param context  - Run/node identifiers and an optional event bus.
+ * @returns `{ plateaued: true, scores }` with event emitted when plateaued;
+ *          `{ plateaued: false, scores }` with no event emitted otherwise.
+ */
+export declare function checkPlateauAndEmit(detector: PlateauDetector, context: PlateauCheckContext): PlateauCheckResult;
+//# sourceMappingURL=plateau.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plateau.d.ts","sourceRoot":"","sources":["../../src/convergence/plateau.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAMjD;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAEnD;;;;;;OAMG;IACH,WAAW,IAAI,OAAO,CAAA;IAEtB;;;OAGG;IACH,SAAS,IAAI,MAAM,CAAA;IAEnB;;;OAGG;IACH,SAAS,IAAI,MAAM,EAAE,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,yGAAyG;IACzG,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,OAAO,CAAA;IAClB,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CA2BvF;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAepB"}

package/dist/convergence/plateau.js

@@ -0,0 +1,83 @@
+/**
+ * Plateau detection for the convergence loop.
+ * Story 45-6: provides pure plateau detection primitives — no I/O, no side effects.
+ *
+ * Algorithm: Track the last N satisfaction scores (N = `window`, default 3).
+ * If max−min of the window falls strictly below threshold, declare plateau.
+ *
+ * Consumed by:
+ *   - Story 45-8 (convergence controller integration)
+ */
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+const DEFAULT_WINDOW = 3;
+const DEFAULT_THRESHOLD = 0.05;
+/**
+ * Create a new PlateauDetector with the given options.
+ *
+ * **Defaults:** `window=3`, `threshold=0.05` — matching `FactoryConfigSchema.plateau_window`
+ * and `FactoryConfigSchema.plateau_threshold`. Story 45-8 will read these values from
+ * `FactoryConfig` and pass them in.
+ *
+ * **Insufficient-data guard:** `isPlateaued()` always returns `false` when fewer than
+ * `window` scores have been recorded. A plateau can only be declared once the window is full.
+ *
+ * @param options - Optional configuration for window size and threshold.
+ */
+export function createPlateauDetector(options) {
+    const window = options?.window ?? DEFAULT_WINDOW;
+    const threshold = options?.threshold ?? DEFAULT_THRESHOLD;
+    let scores = [];
+    return {
+        recordScore(_iteration, score) {
+            scores.push(score);
+            scores = scores.slice(-window);
+        },
+        isPlateaued() {
+            if (scores.length < window) {
+                return false;
+            }
+            const delta = Math.max(...scores) - Math.min(...scores);
+            return delta < threshold;
+        },
+        getWindow() {
+            return window;
+        },
+        getScores() {
+            return [...scores];
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Event emission helper
+// ---------------------------------------------------------------------------
+/**
+ * Check whether the detector has reached a plateau and, if so, emit the
+ * `convergence:plateau-detected` event on the provided event bus.
+ *
+ * This mirrors the `checkGoalGates()` pattern:
+ * - Pure detection is isolated in `PlateauDetector` (no side effects).
+ * - Event emission is isolated here in this wrapper.
+ * - Callers may omit `eventBus` for pure check behavior (no event is emitted).
+ *
+ * @param detector - A `PlateauDetector` instance.
+ * @param context  - Run/node identifiers and an optional event bus.
+ * @returns `{ plateaued: true, scores }` with event emitted when plateaued;
+ *          `{ plateaued: false, scores }` with no event emitted otherwise.
+ */
+export function checkPlateauAndEmit(detector, context) {
+    const { runId, nodeId, eventBus } = context;
+    const scores = detector.getScores();
+    if (detector.isPlateaued()) {
+        eventBus?.emit('convergence:plateau-detected', {
+            runId,
+            nodeId,
+            scores,
+            window: detector.getWindow(),
+        });
+        return { plateaued: true, scores };
+    }
+    return { plateaued: false, scores };
+}
+//# sourceMappingURL=plateau.js.map

package/dist/convergence/plateau.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plateau.js","sourceRoot":"","sources":["../../src/convergence/plateau.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0EH,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,MAAM,cAAc,GAAG,CAAC,CAAA;AACxB,MAAM,iBAAiB,GAAG,IAAI,CAAA;AAE9B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgC;IACpE,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,cAAc,CAAA;IAChD,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,iBAAiB,CAAA;IACzD,IAAI,MAAM,GAAa,EAAE,CAAA;IAEzB,OAAO;QACL,WAAW,CAAC,UAAkB,EAAE,KAAa;YAC3C,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAClB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;QAED,WAAW;YACT,IAAI,MAAM,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;gBAC3B,OAAO,KAAK,CAAA;YACd,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAA;YACvD,OAAO,KAAK,GAAG,SAAS,CAAA;QAC1B,CAAC;QAED,SAAS;YACP,OAAO,MAAM,CAAA;QACf,CAAC;QAED,SAAS;YACP,OAAO,CAAC,GAAG,MAAM,CAAC,CAAA;QACpB,CAAC;KACF,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAyB,EACzB,OAA4B;IAE5B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAA;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE,CAAA;IAEnC,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC;QAC3B,QAAQ,EAAE,IAAI,CAAC,8BAA8B,EAAE;YAC7C,KAAK;YACL,MAAM;YACN,MAAM;YACN,MAAM,EAAE,QAAQ,CAAC,SAAS,EAAE;SAC7B,CAAC,CAAA;QACF,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IACpC,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACrC,CAAC"}

package/dist/convergence/remediation.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Remediation context injection for the convergence loop.
+ * Story 45-7: builds structured remediation context from failure data and
+ * injects it into a retried node's IGraphContext.
+ *
+ * Architecture reference: Section 6.5 — Remediation Context fields
+ *
+ * Pure functions (`formatScenarioDiff`, `deriveFixScope`, `buildRemediationContext`)
+ * have no I/O and no side effects.
+ * Only `injectRemediationContext` mutates state (the IGraphContext).
+ *
+ * Consumed by:
+ *   - Story 45-8 (convergence controller integration with executor)
+ *   - CodergenBackend handlers (via `getRemediationContext`)
+ */
+import type { ScenarioRunResult } from '../events.js';
+import type { IGraphContext } from '../graph/types.js';
+/**
+ * The agreed key under which remediation context is stored in `IGraphContext`.
+ * Namespaced under `convergence.` to avoid collision with user-defined context keys.
+ * Story 45-8 writes this key; CodergenBackend handlers read it via `getRemediationContext()`.
+ */
+export declare const REMEDIATION_CONTEXT_KEY = "convergence.remediation";
+/**
+ * Structured remediation context injected into a retried node's IGraphContext.
+ *
+ * Architecture reference: Section 6.5 — the five fields below match the
+ * factory convergence spec exactly. No additional fields should be added
+ * without updating the architecture document.
+ *
+ * Fields:
+ * - `previousFailureReason` — why the goal gate was not satisfied
+ * - `scenarioDiff` — which scenarios failed and why (formatted from ScenarioRunResult)
+ * - `iterationCount` — which retry attempt this is (starts at 1 on first retry)
+ * - `satisfactionScoreHistory` — satisfaction scores from each previous iteration (oldest first)
+ * - `fixScope` — focused instruction for the retried agent derived from failing scenario names
+ */
+export interface RemediationContext {
+    previousFailureReason: string;
+    scenarioDiff: string;
+    iterationCount: number;
+    satisfactionScoreHistory: number[];
+    fixScope: string;
+}
+/**
+ * Input parameters for `buildRemediationContext()`.
+ *
+ * `scenarioResults` is optional because the first retry in a pipeline may occur
+ * before any scenario validation has run.
+ */
+export interface BuildRemediationContextParams {
+    previousFailureReason: string;
+    scenarioResults?: ScenarioRunResult;
+    iterationCount: number;
+    satisfactionScoreHistory: number[];
+}
+/**
+ * Formats a human-readable diff of failed scenarios from a ScenarioRunResult.
+ *
+ * This is a pure formatting function with no side effects. For each failed
+ * scenario it produces a line `"- {name}: {stderr || stdout || '(no output)'}"`,
+ * preferring stderr (most useful for debugging), falling back to stdout
+ * (some tools write errors to stdout), then to the literal `'(no output)'`.
+ *
+ * Returns `"All scenarios passed"` when there are no failures.
+ */
+export declare function formatScenarioDiff(results: ScenarioRunResult): string;
+/**
+ * Derives a focused fix instruction string from failed scenarios.
+ *
+ * This function produces human-readable fix instructions for the retried agent.
+ * Returns `"Fix {n} failing scenario{s}: {name1}, {name2}, ..."` when there are
+ * failures, or `""` when all scenarios pass.
+ *
+ * Pluralization: singular "scenario" when n === 1, plural "scenarios" otherwise.
+ */
+export declare function deriveFixScope(results: ScenarioRunResult): string;
+/**
+ * Builds a complete `RemediationContext` from the provided parameters.
+ *
+ * `scenarioResults` is optional — first-iteration retries may not have scenario
+ * data yet. When omitted, `scenarioDiff` defaults to
+ * `"No scenario results available"` and `fixScope` defaults to `""`.
+ *
+ * Stores `satisfactionScoreHistory` as a defensive copy (`[...params.satisfactionScoreHistory]`)
+ * so external mutation of the caller's array does not corrupt the stored history.
+ */
+export declare function buildRemediationContext(params: BuildRemediationContextParams): RemediationContext;
+/**
+ * Injects a `RemediationContext` into an `IGraphContext` under `REMEDIATION_CONTEXT_KEY`.
+ *
+ * Called by the executor's retry loop before dispatching to the retried node —
+ * story 45-8 wires this call into the graph executor.
+ */
+export declare function injectRemediationContext(context: IGraphContext, remediation: RemediationContext): void;
+/**
+ * Retrieves the `RemediationContext` previously injected via `injectRemediationContext`.
+ *
+ * Returns `undefined` when no remediation context has been injected yet.
+ *
+ * This is the accessor for `CodergenBackend` and other handlers that need to
+ * read remediation context in their `generate()` methods.
+ */
+export declare function getRemediationContext(context: IGraphContext): RemediationContext | undefined;
+//# sourceMappingURL=remediation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remediation.d.ts","sourceRoot":"","sources":["../../src/convergence/remediation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAMtD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,4BAA4B,CAAA;AAMhE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,kBAAkB;IACjC,qBAAqB,EAAE,MAAM,CAAA;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,cAAc,EAAE,MAAM,CAAA;IACtB,wBAAwB,EAAE,MAAM,EAAE,CAAA;IAClC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC5C,qBAAqB,EAAE,MAAM,CAAA;IAC7B,eAAe,CAAC,EAAE,iBAAiB,CAAA;IACnC,cAAc,EAAE,MAAM,CAAA;IACtB,wBAAwB,EAAE,MAAM,EAAE,CAAA;CACnC;AAMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAUrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CASjE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,6BAA6B,GACpC,kBAAkB,CAcpB;AAMD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,kBAAkB,GAC9B,IAAI,CAEN;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAE5F"}

package/dist/convergence/remediation.js

@@ -0,0 +1,117 @@
+/**
+ * Remediation context injection for the convergence loop.
+ * Story 45-7: builds structured remediation context from failure data and
+ * injects it into a retried node's IGraphContext.
+ *
+ * Architecture reference: Section 6.5 — Remediation Context fields
+ *
+ * Pure functions (`formatScenarioDiff`, `deriveFixScope`, `buildRemediationContext`)
+ * have no I/O and no side effects.
+ * Only `injectRemediationContext` mutates state (the IGraphContext).
+ *
+ * Consumed by:
+ *   - Story 45-8 (convergence controller integration with executor)
+ *   - CodergenBackend handlers (via `getRemediationContext`)
+ */
+// ---------------------------------------------------------------------------
+// Constant
+// ---------------------------------------------------------------------------
+/**
+ * The agreed key under which remediation context is stored in `IGraphContext`.
+ * Namespaced under `convergence.` to avoid collision with user-defined context keys.
+ * Story 45-8 writes this key; CodergenBackend handlers read it via `getRemediationContext()`.
+ */
+export const REMEDIATION_CONTEXT_KEY = 'convergence.remediation';
+// ---------------------------------------------------------------------------
+// Pure formatting functions
+// ---------------------------------------------------------------------------
+/**
+ * Formats a human-readable diff of failed scenarios from a ScenarioRunResult.
+ *
+ * This is a pure formatting function with no side effects. For each failed
+ * scenario it produces a line `"- {name}: {stderr || stdout || '(no output)'}"`,
+ * preferring stderr (most useful for debugging), falling back to stdout
+ * (some tools write errors to stdout), then to the literal `'(no output)'`.
+ *
+ * Returns `"All scenarios passed"` when there are no failures.
+ */
+export function formatScenarioDiff(results) {
+    const failed = results.scenarios.filter((s) => s.status === 'fail');
+    if (failed.length === 0) {
+        return 'All scenarios passed';
+    }
+    const lines = failed.map((s) => {
+        const output = s.stderr || s.stdout || '(no output)';
+        return `- ${s.name}: ${output}`;
+    });
+    return lines.join('\n');
+}
+/**
+ * Derives a focused fix instruction string from failed scenarios.
+ *
+ * This function produces human-readable fix instructions for the retried agent.
+ * Returns `"Fix {n} failing scenario{s}: {name1}, {name2}, ..."` when there are
+ * failures, or `""` when all scenarios pass.
+ *
+ * Pluralization: singular "scenario" when n === 1, plural "scenarios" otherwise.
+ */
+export function deriveFixScope(results) {
+    const failed = results.scenarios.filter((s) => s.status === 'fail');
+    if (failed.length === 0) {
+        return '';
+    }
+    const n = failed.length;
+    const plural = n === 1 ? 'scenario' : 'scenarios';
+    const names = failed.map((s) => s.name).join(', ');
+    return `Fix ${n} failing ${plural}: ${names}`;
+}
+// ---------------------------------------------------------------------------
+// Builder function
+// ---------------------------------------------------------------------------
+/**
+ * Builds a complete `RemediationContext` from the provided parameters.
+ *
+ * `scenarioResults` is optional — first-iteration retries may not have scenario
+ * data yet. When omitted, `scenarioDiff` defaults to
+ * `"No scenario results available"` and `fixScope` defaults to `""`.
+ *
+ * Stores `satisfactionScoreHistory` as a defensive copy (`[...params.satisfactionScoreHistory]`)
+ * so external mutation of the caller's array does not corrupt the stored history.
+ */
+export function buildRemediationContext(params) {
+    const scenarioDiff = params.scenarioResults
+        ? formatScenarioDiff(params.scenarioResults)
+        : 'No scenario results available';
+    const fixScope = params.scenarioResults ? deriveFixScope(params.scenarioResults) : '';
+    return {
+        previousFailureReason: params.previousFailureReason,
+        scenarioDiff,
+        iterationCount: params.iterationCount,
+        satisfactionScoreHistory: [...params.satisfactionScoreHistory],
+        fixScope,
+    };
+}
+// ---------------------------------------------------------------------------
+// IGraphContext inject / retrieve helpers
+// ---------------------------------------------------------------------------
+/**
+ * Injects a `RemediationContext` into an `IGraphContext` under `REMEDIATION_CONTEXT_KEY`.
+ *
+ * Called by the executor's retry loop before dispatching to the retried node —
+ * story 45-8 wires this call into the graph executor.
+ */
+export function injectRemediationContext(context, remediation) {
+    context.set(REMEDIATION_CONTEXT_KEY, remediation);
+}
+/**
+ * Retrieves the `RemediationContext` previously injected via `injectRemediationContext`.
+ *
+ * Returns `undefined` when no remediation context has been injected yet.
+ *
+ * This is the accessor for `CodergenBackend` and other handlers that need to
+ * read remediation context in their `generate()` methods.
+ */
+export function getRemediationContext(context) {
+    return context.get(REMEDIATION_CONTEXT_KEY);
+}
+//# sourceMappingURL=remediation.js.map

package/dist/convergence/remediation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remediation.js","sourceRoot":"","sources":["../../src/convergence/remediation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,yBAAyB,CAAA;AAyChE,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA0B;IAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAA;IACnE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,sBAAsB,CAAA;IAC/B,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,IAAI,aAAa,CAAA;QACpD,OAAO,KAAK,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAA;IACjC,CAAC,CAAC,CAAA;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,OAA0B;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAA;IACnE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,CAAA;IACX,CAAC;IACD,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAA;IACvB,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAA;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClD,OAAO,OAAO,CAAC,YAAY,MAAM,KAAK,KAAK,EAAE,CAAA;AAC/C,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAqC;IAErC,MAAM,YAAY,GAAG,MAAM,CAAC,eAAe;QACzC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,eAAe,CAAC;QAC5C,CAAC,CAAC,+BAA+B,CAAA;IAEnC,MAAM,QAAQ,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAErF,OAAO;QACL,qBAAqB,EAAE,MAAM,CAAC,qBAAqB;QACnD,YAAY;QACZ,cAAc,EAAE,MAAM,CAAC,cAAc;QACrC,wBAAwB,EAAE,CAAC,GAAG,MAAM,CAAC,wBAAwB,CAAC;QAC9D,QAAQ;KACT,CAAA;AACH,CAAC;AAED,8EAA8E;AAC9E,0CAA0C;AAC1C,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAsB,EACtB,WAA+B;IAE/B,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAAA;AACnD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAsB;IAC1D,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAmC,CAAA;AAC/E,CAAC"}