opencode-swarm 7.188.12 → 7.190.0

package/dist/tools/epic-record-divergence.d.ts

@@ -1,73 +0,0 @@
-/**
- * Epic Mode divergence-record tool (Capability D — capture leg).
- *
- * After the architect marks a task `completed` via `update_task_status`, it
- * calls this tool with `{ directory, taskId, sessionID }`. The tool:
- *
- *   1. Reads the task's DECLARED scope from `.swarm/scopes/scope-{taskId}.json`
- *      (the same on-disk record `readScopeFromDisk` consults).
- *   2. Reads the ACTUAL files attributed to this exact task by the guardrails
- *      write hook and background-completion ingestion.
- *   3. Appends one record to `.swarm/epic/divergence.jsonl` via
- *      `recordTaskDivergence`. The calibration engine reads that file on the
- *      next `epic_decide_phase` invocation (the architect-facing decide
- *      tool — `epic_run_phase` is the legacy unified path, retained as
- *      `executeEpicRunPhase` for composition users only).
- *
- * Best-effort by design — failure to record divergence is logged but never
- * surfaces as a task-blocking error. Worst case: a single observation is
- * missed and the calibration loop sees one fewer data point.
- *
- * Composition contract: this tool does NOT modify `update_task_status` or
- * any maintainer file. The architect is instructed to call it via the
- * `EPIC_MODE_BANNER` system-enhancer injection. If the architect forgets,
- * the only effect is missing calibration signal — Epic Mode keeps working.
- */
-import type { ToolDefinition } from '@opencode-ai/plugin/tool';
-import { loadPlanJsonOnly as loadPlanJsonOnly_import } from '../plan/manager.js';
-import { readScopeFromDisk as readScopeFromDisk_import } from '../scope/scope-persistence.js';
-import { getAgentSession as getAgentSession_import, getModifiedFilesForTask as getModifiedFilesForTask_import, hasActiveEpicMode as hasActiveEpicMode_import, resetModifiedFilesForTask as resetModifiedFilesForTask_import } from '../state.js';
-import { recordTaskDivergence as recordTaskDivergence_import } from '../turbo/epic/divergence-recorder.js';
-export interface EpicRecordDivergenceArgs {
-    directory: string;
-    taskId: string;
-    sessionID: string;
-}
-export interface EpicRecordDivergenceResult {
-    success: boolean;
-    /**
-     * Either:
-     *  - `'recorded'` — a record was appended to divergence.jsonl.
-     *  - `'epic-mode-not-active'` — session has not toggled Epic Mode; no-op.
-     *  - `'no-scope'` — no declared scope on disk for this task (could be a
-     *    pure verification task that bypassed `declare_scope`). Skipped.
-     *  - `'no-session'` — no agent session for `sessionID`; skipped.
-     *  - `'persist-failed'` — write to JSONL failed (logged); skipped.
-     */
-    reason: string;
-    /** When `reason === 'recorded'`, summarises the record without the full file lists. */
-    summary?: {
-        declaredCount: number;
-        actualCount: number;
-        undeclaredCount: number;
-        unusedCount: number;
-        divergenceRatio: number;
-        isClean: boolean;
-    };
-}
-/**
- * Test-only DI seam (AGENTS.md invariant 7). Mutating this object is
- * file-scoped and trivially restorable via afterEach, avoiding Bun's
- * cross-file `mock.module` leak.
- */
-export declare const _internals: {
-    hasActiveEpicMode: typeof hasActiveEpicMode_import;
-    getAgentSession: typeof getAgentSession_import;
-    getModifiedFilesForTask: typeof getModifiedFilesForTask_import;
-    resetModifiedFilesForTask: typeof resetModifiedFilesForTask_import;
-    readScopeFromDisk: typeof readScopeFromDisk_import;
-    loadPlanJsonOnly: typeof loadPlanJsonOnly_import;
-    recordTaskDivergence: typeof recordTaskDivergence_import;
-};
-export declare function executeEpicRecordDivergence(args: EpicRecordDivergenceArgs): Promise<EpicRecordDivergenceResult>;
-export declare const epic_record_divergence: ToolDefinition;

package/dist/tools/epic-run-phase.d.ts

@@ -1,179 +0,0 @@
-/**
- * Epic Mode run-phase tool (Capability C).
- *
- * The architect invokes this tool — instead of `lean_turbo_run_phase` —
- * when Epic Mode is active. It:
- *
- *   1. Verifies Epic Mode is on for the session (else fails closed).
- *   2. Loads the plan, resolves task scopes the same way the coupling
- *      report does, and queries the co-change signal.
- *   3. Runs `decideEpicActivation` over the WHOLE PLAN (per-plan
- *      activation per Q1) to get a `promote | demote` verdict.
- *   4. Appends one record to `.swarm/evidence/epic-promotions.jsonl`
- *      and updates `.swarm/epic-state.json` with the verdict.
- *   5. If promoted: invokes `LeanTurboRunner` for the given phase by
- *      composition (zero edits to `src/turbo/lean/`).
- *   6. If demoted: returns a structured "epic recommends serial"
- *      verdict so the caller can fall back to the standard serial
- *      flow.
- *
- * Composition contract: this tool is the only architect-facing entry
- * point Capability C adds. It does not modify `lean_turbo_run_phase`,
- * `LeanTurboRunner`, or any Lean Turbo file. Decision happens above
- * Lean Turbo; execution dispatches into Lean Turbo via import only.
- */
-import type { ToolDefinition } from '@opencode-ai/plugin/tool';
-import { loadPluginConfigWithMeta as loadPluginConfigWithMeta_import } from '../config/index.js';
-import { isGitRepo as isGitRepo_import } from '../git/branch.js';
-import { loadPlanJsonOnly as loadPlanJsonOnly_import } from '../plan/manager.js';
-import type { EpicActivationVerdict } from '../turbo/epic/activation.js';
-import { decideEpicActivation as decideEpicActivation_import } from '../turbo/epic/activation.js';
-import { loadCalibrationState as loadCalibrationState_import, saveCalibrationState as saveCalibrationState_import } from '../turbo/epic/calibration.js';
-import { applyCalibration as applyCalibration_import, effectiveActivationThreshold as effectiveActivationThreshold_import, effectiveHotModules as effectiveHotModules_import } from '../turbo/epic/calibration-engine.js';
-import { getCoChangeData as getCoChangeData_import } from '../turbo/epic/cochange-source.js';
-import { readDivergenceHistory as readDivergenceHistory_import } from '../turbo/epic/divergence-recorder.js';
-import { appendPromotionEvidence as appendPromotionEvidence_import } from '../turbo/epic/promotion-evidence.js';
-import { isEpicModeActive as isEpicModeActive_import, recordEpicDecision as recordEpicDecision_import } from '../turbo/epic/state.js';
-import { buildIsUpstreamCommitted as buildIsUpstreamCommitted_import, buildIsUpstreamCommittedWithStatus as buildIsUpstreamCommittedWithStatus_import } from '../turbo/epic/upstream-commits.js';
-import { readTaskScopes as readTaskScopes_import } from '../turbo/lean/conflicts.js';
-import type { LaneResult } from '../turbo/lean/runner.js';
-import { LeanTurboRunner as LeanTurboRunner_import } from '../turbo/lean/runner.js';
-export interface EpicRunPhaseArgs {
-    directory: string;
-    phase: number;
-    sessionID: string;
-}
-export interface EpicRunPhaseResult {
-    success: boolean;
-    /** The verdict for this run, persisted to evidence. */
-    verdict?: EpicActivationVerdict;
-    /** Set when the verdict was `promote` and Lean Turbo ran. */
-    lanes?: LaneResult[];
-    degradedTasks?: string[];
-    serializedTasks?: string[];
-    /**
-     * Either:
-     *  - `'demoted'` — epic chose serial; the caller should fall back.
-     *  - `'promoted'` — epic chose parallel and Lean Turbo ran.
-     *  - `'epic-mode-not-active'` — the session has not toggled Epic Mode.
-     *  - `'no-plan'` — `.swarm/plan.json` is missing.
-     *  - `'no-phase'` — the requested phase number isn't present in the
-     *    plan. Phase 12 (B11): without this, an unknown phase silently
-     *    produced `currentPhaseTasks = []` and vacuously-passed the
-     *    activation gate — promoting a phase that doesn't exist.
-     *  - `'phase-already-complete'` — every task in the requested phase
-     *    is already `status: 'completed'`. Phase 15 (B35): without this,
-     *    re-running an already-completed phase silently produced a
-     *    vacuous-pass `promote` verdict; the architect then called the
-     *    wave planner and got an empty plan with no diagnostic.
-     *  - `'phase-empty'` — the requested phase exists but its `tasks`
-     *    array is empty (architect created a phase header but never
-     *    populated it, or a council edit removed every task). Phase 17
-     *    (E.1): the Phase 15 B35 guard only fired when at least one
-     *    completed task existed; an empty `tasks: []` slipped through to
-     *    the same vacuous-pass `promote` B35 was supposed to prevent.
-     *  - `'lean-runner-error'` — Lean Turbo threw during promoted execution.
-     *  - `'scopes-missing'` — one or more pending tasks in the phase have
-     *    neither a declared scope file on disk nor `files_touched` in
-     *    plan.json. Lean Turbo's lane planner needs scope data to compute
-     *    parallel lanes; without it the dispatch returns empty lanes and
-     *    the parallelization promise is silently broken. The architect
-     *    must call `declare_scope` for each missing task and then
-     *    re-invoke `epic_decide_phase`.
-     */
-    reason: string;
-    /** Set when `reason === 'lean-runner-error'`. */
-    errors?: string[];
-    /** Set when `reason === 'scopes-missing'` — the task ids with no scope. */
-    missingScopes?: string[];
-    /** Set when `reason === 'scopes-missing'` — actionable message for the architect. */
-    message?: string;
-}
-/**
- * Test-only DI seam. Mutating this object is file-scoped and trivially
- * restorable via afterEach, avoiding Bun's cross-file `mock.module`
- * leak (AGENTS.md invariant 7).
- */
-export declare const _internals: {
-    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta_import;
-    loadPlanJsonOnly: typeof loadPlanJsonOnly_import;
-    getCoChangeData: typeof getCoChangeData_import;
-    decideEpicActivation: typeof decideEpicActivation_import;
-    isGitRepo: typeof isGitRepo_import;
-    appendPromotionEvidence: typeof appendPromotionEvidence_import;
-    recordEpicDecision: typeof recordEpicDecision_import;
-    isEpicModeActive: typeof isEpicModeActive_import;
-    readTaskScopes: typeof readTaskScopes_import;
-    loadCalibrationState: typeof loadCalibrationState_import;
-    saveCalibrationState: typeof saveCalibrationState_import;
-    applyCalibration: typeof applyCalibration_import;
-    effectiveActivationThreshold: typeof effectiveActivationThreshold_import;
-    effectiveHotModules: typeof effectiveHotModules_import;
-    readDivergenceHistory: typeof readDivergenceHistory_import;
-    LeanTurboRunner: typeof LeanTurboRunner_import;
-    buildIsUpstreamCommitted: typeof buildIsUpstreamCommitted_import;
-    buildIsUpstreamCommittedWithStatus: typeof buildIsUpstreamCommittedWithStatus_import;
-};
-/**
- * Decide-only path: runs stages 1-9 of the phase flow (preflight + calibration
- * + co-change + decision + evidence write + session state mirror) and returns
- * the verdict WITHOUT dispatching Lean Turbo.
- *
- * This is the shared helper between:
- *  - `epic_run_phase`: legacy unified tool (decide + dispatch in one call) —
- *    calls this then continues with dispatch when verdict is promote.
- *  - `epic_decide_phase`: transparent flow (decide only — architect then
- *    calls `epic_plan_waves` and dispatches each wave via Task for visibility).
- *
- * Returns the same EpicRunPhaseResult shape with:
- *  - reason: 'decided'  → verdict is promote, caller may dispatch.
- *  - reason: 'demoted'  → verdict is demote, caller falls back to serial.
- *
- * Error / non-decision reasons (all set success: false):
- *  - 'epic-mode-not-active' — the session has not toggled Epic Mode.
- *  - 'no-plan' — `.swarm/plan.json` is missing.
- *  - 'no-phase' (Phase 12 B11) — the requested phase number isn't in the plan.
- *  - 'phase-empty' (Phase 17 E.1) — phase exists but has zero tasks.
- *  - 'phase-already-complete' (Phase 15 B35) — every task already completed.
- *  - 'scopes-missing' — one or more pending tasks lack declared scope.
- *  - 'epic-state-unreadable' — `.swarm/epic-state.json` is corrupt.
- */
-export declare function executeEpicDecidePhase(args: EpicRunPhaseArgs): Promise<EpicRunPhaseResult>;
-/**
- * Full unified path: decide + dispatch in one call (legacy behavior).
- *
- * For transparent CLI-visible dispatch, prefer `epic_decide_phase` + lane
- * dispatch via the architect's Task tool — see EPIC_MODE_BANNER. This unified
- * path remains for back-compat and for callers that don't need visibility
- * into the parallel coder agents.
- */
-export declare function executeEpicRunPhase(args: EpicRunPhaseArgs): Promise<EpicRunPhaseResult>;
-/**
- * NOTE: `epic_run_phase` is intentionally NOT exposed as a tool to the
- * architect. The transparent decide-then-dispatch wave flow (`epic_decide_phase`
- * → `epic_plan_waves` → Task dispatch per wave) is the ONLY supported flow,
- * because it gives the user real-time visibility into each concurrent coder
- * agent. The legacy unified-path function `executeEpicRunPhase` remains
- * exported for tests and any composition users, but no ToolDefinition
- * wraps it — so the architect cannot call it and accidentally fall back
- * to the opaque path. This is a deliberate product decision: one flow,
- * unambiguous, always-visible.
- */
-/**
- * Transparent decide-only tool. Returns the verdict (promote/demote/error)
- * without dispatching coders. The architect should:
- *  1. Call this after declaring scopes for all pending tasks.
- *  2. Surface the verdict to the user.
- *  3. If verdict is `promote`, call `epic_plan_waves` to get the wave plan,
- *     then for each wave dispatch one `Task` per `taskId` in that wave —
- *     ALL in one assistant message so the wave runs concurrently. Wait for
- *     the wave to complete, then advance. Each Task is a visible subagent
- *     the user can click into for live progress.
- *  4. After each task completes (via `update_task_status`), call
- *     `epic_record_divergence` to feed the calibration loop.
- *
- * This is the CLI-visibility flow. The legacy `epic_run_phase` bundles
- * decide + dispatch into one opaque tool call where the user can't see
- * the concurrent coder agents.
- */
-export declare const epic_decide_phase: ToolDefinition;

package/dist/turbo/epic/activation.d.ts

@@ -1,193 +0,0 @@
-/**
- * Epic Mode activation decision (Capability C).
- *
- * `decideEpicActivation(...)` is the pure heart of M3: given a plan, a
- * co-change pair list, and the activation thresholds, it returns a
- * structured `promote | demote` verdict with the rationale fields a
- * caller can persist for audit. Pure function — no I/O.
- *
- * Three independent gates must all pass for promotion:
- *
- *   1. **p-threshold gate.** Compute the coupling coefficient `p` over
- *      the plan's task graph using Capability A's `epicPairConflict` (via
- *      Capability B's `computeCouplingReport`). Promote only when
- *      `p <= activation_threshold`.
- *
- *   2. **Hot-module gate.** No task in scope may touch a Lean Turbo
- *      "global" or "protected" path — these are the same lists Lean
- *      Turbo already maintains (reused by import; not duplicated).
- *      Touching a hot module forces serial regardless of `p`.
- *
- *   3. **Greenfield gate.** If the co-change history is sparse (fewer
- *      than `min_commits_for_signal` distinct commits across the
- *      analyzer output), the signal is too weak to trust per brief §4.2's
- *      greenfield rule. Force serial.
- *
- * Default-serial-promote-on-proof (brief §4.2): when any gate fails or
- * the data is missing, the decision is `demote`. Promotion requires
- * positive evidence on every gate.
- */
-import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
-import type { CouplingTask } from './coupling-report.js';
-/** Thresholds the caller supplies (typically derived from EpicConfigSchema). */
-export interface EpicActivationOptions {
-    /** Plan-wide p ceiling. Plans with p > activationThreshold are demoted. */
-    activationThreshold: number;
-    /** Greenfield floor on the analyzer's commit window. */
-    minCommitsForSignal: number;
-    /** NPMI floor for the co-change conflict signal — passed through to coupling. */
-    cochangeNpmiThreshold: number;
-    /** Minimum raw co-change count for the conflict signal. */
-    cochangeMinCoChanges: number;
-    /**
-     * Capability D (calibration) additions to the hot-module list. The static
-     * Lean Turbo predicates (`isGlobalFile` / `isProtectedPath`) always apply;
-     * these are normalised paths the calibration loop has promoted after
-     * observing divergent writes against the static set. Optional — falsy or
-     * empty means "no calibration overrides". Path matching is exact (post-
-     * `normalizePath`); callers compute that via `effectiveHotModules` in
-     * `./calibration-engine.ts`.
-     */
-    extraHotModules?: readonly string[];
-    /**
-     * Greenfield-smart Rule 1: whether the project is under git version control.
-     * The greenfield gate exists because co-change signals require git history
-     * to compute. When the project is not a git repo, there is no signal type
-     * to evaluate — the gate's premise is absent, so it passes trivially
-     * rather than fail-closed. Callers (typically `epic_run_phase`) resolve
-     * this via `isGitRepo(directory)` from `src/git/branch.ts`.
-     *
-     * Backward-compat: omitted or `undefined` reverts to legacy behavior
-     * (apply the `commitsObserved >= minCommitsForSignal` floor
-     * unconditionally). Callers should pass an explicit boolean.
-     */
-    isGitProject?: boolean;
-    /**
-     * Phase 13 (B20): task IDs the architect declared in `depends:` that
-     * don't resolve to ANY task in the plan. Typically an LLM typo. The
-     * gate fails closed with a dedicated `phantom dep` blocking reason so
-     * the architect sees the actual bad ID instead of being misled into
-     * hunting a non-existent cross-phase upstream. Pass alongside
-     * `crossPhaseUpstreams` (the two lists are disjoint).
-     */
-    phantomDeps?: readonly string[];
-    /**
-     * Phase 10 — predecessor-evidence gate redesign.
-     *
-     * Cross-phase upstream task IDs for the phase being decided: every
-     * task that lives in a strictly-prior phase AND is depended on by a
-     * task in the current phase. The gate verifies each one has a
-     * `swarm(task <id>):` marker in git log via `isUpstreamCommitted`.
-     *
-     * Empty array (the legacy default) ⇒ no cross-phase deps to check;
-     * predecessor evidence is vacuously satisfied. This is correct for
-     * Phase 1 (no prior phase), single-phase projects, and phases the
-     * architect explicitly declared as independent.
-     *
-     * Why this replaces the `commitsObserved >= minCommitsForSignal`
-     * floor: the floor was a statistical proxy for "do we have enough
-     * history to trust `p`?", but in small projects it permanently
-     * blocked parallelism (a 12-task project never reaches 20 commits).
-     * The structural check asks the actually-relevant question — "are
-     * the things this phase depends on actually in git?" — directly,
-     * regardless of project size. The architect's declared dep graph IS
-     * the parallelism specification (Lamport happens-before); Rule 2's
-     * commits ARE the synchronization point; this check ties them
-     * together.
-     *
-     * Callers (`epic_run_phase`) compute this from the plan's dep graph.
-     */
-    crossPhaseUpstreams?: readonly string[];
-    /**
-     * Predicate for the predecessor-evidence check above. Returns true
-     * when the given taskId has a `swarm(task <id>):` marker in git
-     * history. Same predicate Rule 3 uses at the lane planner — share
-     * one source of truth.
-     *
-     * Omitted ⇒ the gate treats every cross-phase upstream as
-     * uncommitted (fail-closed). Pair `crossPhaseUpstreams` with this
-     * predicate, or pass neither.
-     */
-    isUpstreamCommitted?: (taskId: string) => boolean;
-}
-/** Each gate's pass/fail outcome plus the evidence behind it. */
-export interface EpicActivationRationale {
-    pCheck: {
-        passed: boolean;
-        p: number;
-        threshold: number;
-    };
-    hotModuleCheck: {
-        passed: boolean;
-        touchedHotModules: string[];
-    };
-    greenfieldCheck: {
-        passed: boolean;
-        commitsObserved: number;
-        minCommits: number;
-        /**
-         * `true` when the caller flagged the project as non-git
-         * (`options.isGitProject === false`). In that case the gate is
-         * bypassed (`passed: true`) because the co-change signal does not
-         * apply — not because the history floor was met. Surfaced for audit
-         * so reviewers can distinguish "bypassed" from "satisfied".
-         */
-        bypassedNoGit?: boolean;
-        /**
-         * Phase 10: cross-phase upstream task IDs the gate consulted.
-         * Empty when the current phase has no cross-phase deps (Phase 1,
-         * single-phase plans, declared-independent phases).
-         *
-         * Phase 13 (B19): optional because pre-Phase-10 records on disk
-         * (`.swarm/evidence/epic-promotions.jsonl`) lack this field.
-         * Renderers MUST default to `[]` when reading historical records.
-         */
-        crossPhaseUpstreams?: string[];
-        /**
-         * Phase 10: cross-phase upstreams the predicate reported as NOT
-         * yet committed. Non-empty ⇒ the gate failed; the architect
-         * needs to wait for those tasks to commit before re-deciding.
-         *
-         * Phase 13 (B19): optional, same reason as above.
-         */
-        missingUpstreams?: string[];
-        /**
-         * Phase 13 (B20): dep IDs the architect declared that don't
-         * resolve to any task in the plan. Usually an LLM typo; the gate
-         * fails CLOSED so the architect can see the bad ID and fix the
-         * declaration. Distinct from `missingUpstreams` because phantom
-         * IDs aren't tasks that need to be "committed" — they don't
-         * exist at all, and the remediation is "fix the dep ID", not
-         * "wait for the upstream to land".
-         */
-        phantomDeps?: string[];
-    };
-}
-/** The verdict `decideEpicActivation` returns. */
-export interface EpicActivationVerdict {
-    decision: 'promote' | 'demote';
-    p: number;
-    rationale: EpicActivationRationale;
-    /** Plain-English reasons the verdict went the way it did — for logs and UI. */
-    blockingReasons: string[];
-}
-/**
- * Decide whether the given tasks should be promoted to parallel execution
- * via Lean Turbo's lane planner.
- *
- * Inputs are pre-resolved by the caller:
- *  - `tasks`: every task in scope (typically the whole plan), with the
- *    same `{ id, scope }` shape Capability B consumes. The caller
- *    handles `readTaskScopes` / `files_touched` resolution and any
- *    completed-task filtering.
- *  - `cochangePairs`: the analyzer's output (unfiltered) plus the
- *    `commitsObserved` count from `parseGitLog`. The greenfield gate
- *    consults the count directly so the function stays pure.
- *  - `options`: thresholds (typically read from
- *    `turbo.epic.mode.*` + `turbo.epic.cochange.*`).
- *
- * Output: structured verdict the caller persists to
- * `.swarm/evidence/epic-promotions.jsonl` and surfaces via
- * `/swarm epic status`.
- */
-export declare function decideEpicActivation(tasks: CouplingTask[], cochangePairs: CoChangeEntry[], commitsObserved: number, options: EpicActivationOptions): EpicActivationVerdict;

package/dist/turbo/epic/calibration-engine.d.ts

@@ -1,88 +0,0 @@
-/**
- * Calibration engine for Epic Mode Capability D.
- *
- * `applyCalibration(state, newRecords, options) → newState` is a pure
- * function that walks fresh divergence records (those not yet processed)
- * and produces an updated calibration state. The wiring code is responsible
- * for: (a) reading the prior state, (b) filtering history to the
- * unprocessed tail, (c) writing the new state.
- *
- * Hard design rules (brief §4.5-D + the user's ratified §20.3 defaults):
- *
- *   1. **Auto-tighten only on threshold.** A divergent task tightens
- *      `activationThresholdOverride` toward zero by `tightenStep`,
- *      bounded by `floorThreshold` (we never tighten below the floor —
- *      a value too small makes Epic Mode never promote anything).
- *
- *   2. **Hot-module list monotonically grows.** Files in a divergent
- *      task's `undeclared` set are added to `hotModuleAdditions`. The
- *      list is NEVER auto-shrunk; loosening a hot-module promotion
- *      requires manual intervention. This is a one-way ratchet.
- *
- *   3. **Loosen only after `loosenWindow` consecutive clean tasks.**
- *      Every clean (divergenceRatio === 0) task increments
- *      `consecutiveCleanCount`; every divergent task resets it to zero.
- *      When the counter reaches `loosenWindow`, the threshold is loosened
- *      by `loosenStep` toward the static config value (never past it) and
- *      the counter resets to zero. The hot-module list is NOT shrunk by
- *      loosening — only the threshold relaxes.
- *
- *   4. **No oscillation.** A clean-then-divergent-then-clean sequence
- *      cannot swing the threshold back and forth: every divergent task
- *      resets the clean-counter and tightens by `tightenStep`, so the
- *      threshold only moves toward zero in the divergent direction and
- *      toward the static value (with the clean-window gate) in the
- *      clean direction. Tests assert this invariant.
- */
-import type { CalibrationState } from './calibration.js';
-import type { DivergenceRecord } from './divergence-recorder.js';
-export interface ApplyCalibrationOptions {
-    /** Static config value — the absolute ceiling for the threshold. */
-    staticThreshold: number;
-    /**
-     * Floor for the threshold — calibration never tightens past this.
-     * Default 0.05 — below that, Epic Mode effectively never promotes
-     * even on highly-decoupled plans.
-     */
-    floorThreshold?: number;
-    /** Per-divergent-task tightening step. Default 0.02. */
-    tightenStep?: number;
-    /** Per-loosening-event step (toward static). Default 0.01. */
-    loosenStep?: number;
-    /** Consecutive-clean-tasks required before any loosening. Default 10. */
-    loosenWindow?: number;
-}
-/**
- * Apply the calibration rules to a chronological list of NEW divergence
- * records. Pure — no I/O, no side effects, deterministic for a given
- * (state, newRecords, options) triple.
- *
- * The caller is responsible for tracking which records are "new" (typically
- * by reading the full divergence history and slicing past the
- * `processedRecords` count from the current state). This function does
- * not deduplicate — feeding the same record twice will double-count its
- * effect.
- */
-export declare function applyCalibration(state: CalibrationState, newRecords: readonly DivergenceRecord[], options: ApplyCalibrationOptions): CalibrationState;
-/**
- * Resolve the effective activation threshold by combining the static config
- * value with the calibration override (if any). The override is always a
- * tighter or equal value to the static — calibration can never relax past
- * static. Returns the static value when calibration state is null
- * (fail-closed mode) or when no override is set.
- *
- * Belt-and-braces clamps:
- *  - upper bound: static ceiling (calibration never relaxes past it)
- *  - lower bound: 0 (a negative or absurdly small override — e.g. from a
- *    hand-edited calibration.json — would make Epic Mode never promote
- *    anything; treat 0 as the absolute floor here; callers that pass a
- *    higher `floor_threshold` to the engine get that bound at WRITE time,
- *    so this clamp only matters for corrupt on-disk values)
- */
-export declare function effectiveActivationThreshold(staticThreshold: number, state: CalibrationState | null): number;
-/**
- * Union the static hot-module list (Lean Turbo's globals + protected) with
- * the calibration's learned additions. Returns a fresh array; callers can
- * pass this to `decideEpicActivation`'s effective-hot-module check.
- */
-export declare function effectiveHotModules(staticHotModules: readonly string[], state: CalibrationState | null): string[];

package/dist/turbo/epic/calibration.d.ts

@@ -1,80 +0,0 @@
-/**
- * Durable calibration state for Epic Mode Capability D.
- *
- * Persists the LEARNED knob overrides that `decideEpicActivation` consults
- * at runtime — the activation-threshold override (tighter than the static
- * config when divergence has been observed) and the auto-added hot-module
- * list (monotonically grows; never auto-shrinks per design).
- *
- * Lives at `<projectRoot>/.swarm/epic/calibration.json`. Pattern mirrors
- * `src/turbo/epic/state.ts` exactly — atomic `tmp + rename`, per-directory
- * fail-closed marker on malformed file, repair seam.
- *
- * No imports from `src/turbo/lean/` — purely additive to the Epic namespace.
- */
-/** Persisted shape of `.swarm/epic/calibration.json`. */
-export interface CalibrationState {
-    version: 1;
-    updatedAt: string;
-    /**
-     * Effective activation threshold override. When set, supersedes the
-     * static `turbo.epic.mode.activation_threshold` config value (which is
-     * always the absolute ceiling — calibration can tighten, never loosen
-     * past, the static value). Range: same as the static config — [0, 1].
-     */
-    activationThresholdOverride?: number;
-    /**
-     * Modules promoted to the hot-module list by observed divergence.
-     * Monotonically grows — never auto-shrinks (loosening the hot-module
-     * list requires manual intervention; the calibration loop only adds).
-     * Sorted lexicographically for stable diffs. Bounded at
-     * {@link MAX_CALIBRATION_MODULES} on every save and load (issue #2483):
-     * once the cap binds, late-alphabet module paths are PERMANENTLY
-     * excluded from the list and — because additions are monotonic — can
-     * never re-enter (critic N5).
-     */
-    hotModuleAdditions: string[];
-    /**
-     * Running counter of consecutive clean (divergenceRatio === 0) task
-     * outcomes since the last divergent task or the last loosening event.
-     * Drives the loosen-rule (loosen only after `loosenWindow` consecutive
-     * clean tasks). Cleared by the engine after any loosening or divergence.
-     */
-    consecutiveCleanCount: number;
-    /** ISO 8601 timestamp of the most recent calibration-engine invocation. */
-    lastCalibrationAt?: string;
-    /** Number of divergence records processed by the engine so far. */
-    processedRecords: number;
-}
-/**
- * Global cap on the persisted `hotModuleAdditions` list (issue #2483 §2).
- * Enforcement (save AND load) keeps the lexicographically SMALLEST prefix of
- * the sorted list — deterministic and order-respecting, with no invented
- * score. N5 bias, stated plainly: once the cap binds, late-alphabet module
- * paths are permanently excluded from the list and — because additions are
- * monotonic — can never re-enter. The effective value resolves through
- * `resolveRetentionCap` so the #2483 acceptance checks can shrink the cap
- * below this default and prove the truncation clamps.
- */
-export declare const MAX_CALIBRATION_MODULES = 500;
-export declare function emptyCalibrationState(): CalibrationState;
-export declare function isCalibrationStateUnreadable(directory: string): boolean;
-export declare function repairCalibrationUnreadable(directory: string): void;
-/**
- * Read calibration state from disk. Seeds an empty file on first access so
- * subsequent writes do not race on directory creation. Returns null when
- * the file is malformed (fail-closed via `stateUnreadableMap`).
- *
- * Self-healing: when the in-memory unreadable marker is set, this function
- * first attempts to re-validate the on-disk file. If a user (or another
- * process) has repaired the file out-of-band, the marker auto-clears and the
- * normal read proceeds. Without this, a long-lived plugin process would keep
- * returning null until manually told to repair (adversarial review H2).
- */
-export declare function loadCalibrationState(directory: string): CalibrationState | null;
-/**
- * Atomic write of calibration state. `tmp + rename` pattern with random
- * suffix to avoid concurrent-collision; tmp file is best-effort cleaned up
- * on rename failure so a failed write does not leave orphans.
- */
-export declare function saveCalibrationState(directory: string, state: CalibrationState): void;