@ai-sdlc/orchestrator 0.6.0 → 0.9.0

package/dist/runtime/port-allocator.js

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { createServer } from 'node:net';
+export const DEFAULT_BASE_PORT = 3190;
+export const PORT_RANGE_OFFSET_MIN = 100;
+export const PORT_RANGE_OFFSET_MAX = 999;
+const PORT_RANGE_SPAN = PORT_RANGE_OFFSET_MAX - PORT_RANGE_OFFSET_MIN + 1;
+const COLLISION_PROBE_ATTEMPTS = 10;
+export class PortAllocationError extends Error {
+    worktreePath;
+    attemptedPorts;
+    constructor(message, worktreePath, attemptedPorts) {
+        super(message);
+        this.worktreePath = worktreePath;
+        this.attemptedPorts = attemptedPorts;
+        this.name = 'PortAllocationError';
+    }
+}
+export function deterministicPort(worktreePath, basePort = DEFAULT_BASE_PORT) {
+    const absolute = resolve(worktreePath);
+    const digest = createHash('md5').update(absolute).digest();
+    const offset = (((digest[0] << 8) | digest[1]) % PORT_RANGE_SPAN) + PORT_RANGE_OFFSET_MIN;
+    return basePort + offset;
+}
+export async function allocatePort(worktreePath, options = {}) {
+    const envValue = options.envOverride;
+    if (envValue !== undefined && envValue !== '') {
+        const parsed = Number.parseInt(envValue, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 65535) {
+            throw new PortAllocationError(`PORT environment override is not a valid TCP port: ${envValue}`, worktreePath, []);
+        }
+        return parsed;
+    }
+    const basePort = options.basePort ?? DEFAULT_BASE_PORT;
+    const start = deterministicPort(worktreePath, basePort);
+    const probe = options.isPortFree ?? isPortFree;
+    const attempted = [];
+    for (let i = 0; i < COLLISION_PROBE_ATTEMPTS; i++) {
+        const candidate = start + i;
+        attempted.push(candidate);
+        if (await probe(candidate)) {
+            return candidate;
+        }
+    }
+    throw new PortAllocationError(`No free port found after ${COLLISION_PROBE_ATTEMPTS} attempts starting at ${start}`, worktreePath, attempted);
+}
+export async function allocateContiguousPorts(worktreePath, options) {
+    if (options.count < 1 || options.count > 10) {
+        throw new PortAllocationError(`Contiguous port count must be between 1 and 10 (got ${options.count})`, worktreePath, []);
+    }
+    const first = await allocatePort(worktreePath, options);
+    return Array.from({ length: options.count }, (_, i) => first + i);
+}
+export function isPortFree(port) {
+    return new Promise((resolveProbe) => {
+        const server = createServer();
+        server.once('error', () => {
+            resolveProbe(false);
+        });
+        server.once('listening', () => {
+            server.close(() => resolveProbe(true));
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+//# sourceMappingURL=port-allocator.js.map

package/dist/runtime/worktree-pool.d.ts

@@ -0,0 +1,86 @@
+export declare const DEFAULT_POOL_ROOT = "~/.ai-sdlc/worktrees";
+export declare const DEFAULT_STALE_THRESHOLD_DAYS = 14;
+export interface WorktreePoolSpec {
+    rootDir?: string;
+    staleThresholdDays?: number;
+    ownershipGuard?: 'strict' | 'advisory';
+}
+export interface AllocateOptions {
+    /** Base branch to create from (default 'origin/main'). */
+    baseBranch?: string;
+}
+export interface WorktreeHandle {
+    branch: string;
+    slug: string;
+    path: string;
+    /** True when allocate() created the worktree fresh; false when it adopted an existing one. */
+    created: boolean;
+}
+export declare class WorktreePoolError extends Error {
+    readonly branch: string;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, branch: string, cause?: unknown | undefined);
+}
+export interface WorktreePoolManagerDeps {
+    /** Override `git` calls in tests. */
+    git?: (args: string[], opts?: {
+        cwd?: string;
+    }) => Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Override clock for stale-threshold tests. */
+    now?: () => Date;
+}
+/**
+ * Manages a pool of git worktrees rooted at `rootDir`. Each worktree is named after
+ * `slugifyBranch(branch)`. The pool enforces cross-clone ownership (RFC §7.2) and supports
+ * allocate / adopt / reclaim plus a stale-threshold sweep (RFC §7.3).
+ */
+export declare class WorktreePoolManager {
+    readonly rootDir: string;
+    private readonly clonePath;
+    private readonly staleThresholdDays;
+    private readonly ownershipGuard;
+    private readonly git;
+    private readonly now;
+    constructor(clonePath: string, spec?: WorktreePoolSpec, deps?: WorktreePoolManagerDeps);
+    /**
+     * Allocate a worktree for `branch`. If one already exists at the expected path:
+     *   - ownership-verified → adopted (returned with `created: false`)
+     *   - ownership mismatch → throws WorktreeOwnershipError (or warns when guard is advisory)
+     * Otherwise a fresh worktree is created via `git worktree add`.
+     */
+    allocate(branch: string, options?: AllocateOptions): Promise<WorktreeHandle>;
+    /**
+     * Adopt an existing worktree at the slug-derived path. Throws if no worktree exists or
+     * if ownership verification fails (when guard is strict).
+     */
+    adopt(branch: string): Promise<WorktreeHandle>;
+    /**
+     * Destroy the worktree for `branch`. By default refuses to remove a worktree with
+     * uncommitted changes; callers that need to force MUST pass `{ force: true }`.
+     */
+    reclaim(branch: string, options?: {
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * Convenience hook called by the merge-gate when a PR for `branch` lands. Equivalent
+     * to `reclaim(branch)` with the default safety check.
+     */
+    cleanupOnMerge(branch: string): Promise<void>;
+    /**
+     * Enumerate worktree slugs currently present in the pool root. Does not verify ownership.
+     */
+    list(): Promise<string[]>;
+    /**
+     * Reclaim worktrees whose mtime is older than `staleThresholdDays`. Dry-run by default;
+     * pass `{ apply: true }` to actually remove them. Returns the slugs considered stale.
+     */
+    reclaimStale(options?: {
+        apply?: boolean;
+    }): Promise<string[]>;
+    /** Forcibly remove a slug from the pool root without git involvement. Test/cleanup helper. */
+    _forceRemoveSlug(slug: string): Promise<void>;
+}
+//# sourceMappingURL=worktree-pool.d.ts.map

package/dist/runtime/worktree-pool.js

@@ -0,0 +1,204 @@
+import { mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { execFileAsync } from '../shared.js';
+import { assertOwnership, isExistingWorktree, slugifyBranch, verifyOwnership, WorktreeOwnershipError, } from './worktree.js';
+import { cleanGitEnv } from './git-env.js';
+export const DEFAULT_POOL_ROOT = '~/.ai-sdlc/worktrees';
+export const DEFAULT_STALE_THRESHOLD_DAYS = 14;
+export class WorktreePoolError extends Error {
+    branch;
+    cause;
+    constructor(message, branch, cause) {
+        super(message);
+        this.branch = branch;
+        this.cause = cause;
+        this.name = 'WorktreePoolError';
+    }
+}
+/**
+ * Manages a pool of git worktrees rooted at `rootDir`. Each worktree is named after
+ * `slugifyBranch(branch)`. The pool enforces cross-clone ownership (RFC §7.2) and supports
+ * allocate / adopt / reclaim plus a stale-threshold sweep (RFC §7.3).
+ */
+export class WorktreePoolManager {
+    rootDir;
+    clonePath;
+    staleThresholdDays;
+    ownershipGuard;
+    git;
+    now;
+    constructor(clonePath, spec = {}, deps = {}) {
+        this.clonePath = resolve(clonePath);
+        this.rootDir = expandHome(spec.rootDir ?? DEFAULT_POOL_ROOT);
+        this.staleThresholdDays = spec.staleThresholdDays ?? DEFAULT_STALE_THRESHOLD_DAYS;
+        this.ownershipGuard = spec.ownershipGuard ?? 'strict';
+        this.git =
+            deps.git ??
+                ((args, opts) => {
+                    // Strip leaked GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE so worktree
+                    // operations bind to `clonePath`'s repo rather than a husky hook's
+                    // env (AISDLC-72).
+                    const merged = { env: cleanGitEnv(), ...opts };
+                    return execFileAsync('git', args, merged);
+                });
+        this.now = deps.now ?? (() => new Date());
+    }
+    /**
+     * Allocate a worktree for `branch`. If one already exists at the expected path:
+     *   - ownership-verified → adopted (returned with `created: false`)
+     *   - ownership mismatch → throws WorktreeOwnershipError (or warns when guard is advisory)
+     * Otherwise a fresh worktree is created via `git worktree add`.
+     */
+    async allocate(branch, options = {}) {
+        const slug = slugifyBranch(branch);
+        const path = join(this.rootDir, slug);
+        if (await isExistingWorktree(path)) {
+            return this.adopt(branch);
+        }
+        await mkdir(this.rootDir, { recursive: true });
+        const baseBranch = options.baseBranch ?? 'origin/main';
+        try {
+            await this.git(['worktree', 'add', path, '-b', branch, baseBranch], {
+                cwd: this.clonePath,
+            });
+        }
+        catch (err) {
+            throw new WorktreePoolError(`git worktree add failed for branch ${branch}: ${err.message}`, branch, err);
+        }
+        return { branch, slug, path, created: true };
+    }
+    /**
+     * Adopt an existing worktree at the slug-derived path. Throws if no worktree exists or
+     * if ownership verification fails (when guard is strict).
+     */
+    async adopt(branch) {
+        const slug = slugifyBranch(branch);
+        const path = join(this.rootDir, slug);
+        if (!(await isExistingWorktree(path))) {
+            throw new WorktreePoolError(`No existing worktree at ${path} for branch ${branch}`, branch);
+        }
+        if (this.ownershipGuard === 'strict') {
+            try {
+                await assertOwnership(path, this.clonePath);
+            }
+            catch (err) {
+                if (err instanceof WorktreeOwnershipError)
+                    throw err;
+                throw err;
+            }
+        }
+        else {
+            const result = await verifyOwnership(path, this.clonePath);
+            if (!result.owned) {
+                // Advisory: log via console.warn so operators see drift without failing.
+                // In production this would route to the structured event stream.
+                console.warn(`[WorktreePool] advisory ownership mismatch on ${path}: expected ${result.expectedClone}, got ${result.actualClone}`);
+            }
+        }
+        return { branch, slug, path, created: false };
+    }
+    /**
+     * Destroy the worktree for `branch`. By default refuses to remove a worktree with
+     * uncommitted changes; callers that need to force MUST pass `{ force: true }`.
+     */
+    async reclaim(branch, options = {}) {
+        const slug = slugifyBranch(branch);
+        const path = join(this.rootDir, slug);
+        if (!(await isExistingWorktree(path))) {
+            // Nothing to reclaim is not an error — idempotent.
+            return;
+        }
+        if (!options.force) {
+            // Refuse if there are uncommitted changes.
+            try {
+                const { stdout } = await this.git(['status', '--porcelain'], { cwd: path });
+                if (stdout.trim().length > 0) {
+                    throw new WorktreePoolError(`Refusing to reclaim ${path}: uncommitted changes present. Use force: true to override.`, branch);
+                }
+            }
+            catch (err) {
+                if (err instanceof WorktreePoolError)
+                    throw err;
+                // git status failure on a worktree we know exists is a real error.
+                throw new WorktreePoolError(`git status failed inside ${path}: ${err.message}`, branch, err);
+            }
+        }
+        const args = ['worktree', 'remove', path];
+        if (options.force)
+            args.push('--force');
+        try {
+            await this.git(args, { cwd: this.clonePath });
+        }
+        catch (err) {
+            throw new WorktreePoolError(`git worktree remove failed for ${path}: ${err.message}`, branch, err);
+        }
+    }
+    /**
+     * Convenience hook called by the merge-gate when a PR for `branch` lands. Equivalent
+     * to `reclaim(branch)` with the default safety check.
+     */
+    cleanupOnMerge(branch) {
+        return this.reclaim(branch);
+    }
+    /**
+     * Enumerate worktree slugs currently present in the pool root. Does not verify ownership.
+     */
+    async list() {
+        try {
+            const entries = await readdir(this.rootDir, { withFileTypes: true });
+            const result = [];
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                if (await isExistingWorktree(join(this.rootDir, entry.name))) {
+                    result.push(entry.name);
+                }
+            }
+            return result;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+    /**
+     * Reclaim worktrees whose mtime is older than `staleThresholdDays`. Dry-run by default;
+     * pass `{ apply: true }` to actually remove them. Returns the slugs considered stale.
+     */
+    async reclaimStale(options = {}) {
+        const slugs = await this.list();
+        const cutoff = this.now().getTime() - this.staleThresholdDays * 24 * 60 * 60 * 1000;
+        const stale = [];
+        for (const slug of slugs) {
+            const path = join(this.rootDir, slug);
+            try {
+                const s = await stat(path);
+                if (s.mtimeMs < cutoff) {
+                    stale.push(slug);
+                    if (options.apply) {
+                        // Use git worktree prune-style remove; force because branch may have moved.
+                        await this.git(['worktree', 'remove', '--force', path], { cwd: this.clonePath });
+                    }
+                }
+            }
+            catch {
+                // Ignore missing or stat-failed paths.
+            }
+        }
+        return stale;
+    }
+    /** Forcibly remove a slug from the pool root without git involvement. Test/cleanup helper. */
+    async _forceRemoveSlug(slug) {
+        await rm(join(this.rootDir, slug), { recursive: true, force: true });
+    }
+}
+function expandHome(p) {
+    if (p.startsWith('~/'))
+        return join(homedir(), p.slice(2));
+    if (p === '~')
+        return homedir();
+    return p;
+}
+//# sourceMappingURL=worktree-pool.js.map

package/dist/runtime/worktree.d.ts

@@ -0,0 +1,25 @@
+export declare class WorktreeOwnershipError extends Error {
+    readonly worktreePath: string;
+    readonly expectedClone: string;
+    readonly actualClone: string | null;
+    constructor(message: string, worktreePath: string, expectedClone: string, actualClone: string | null);
+}
+export declare function slugifyBranch(branch: string): string;
+export declare function worktreePath(rootDir: string, branch: string): string;
+export interface OwnershipResult {
+    owned: boolean;
+    expectedClone: string;
+    actualClone: string | null;
+    reason?: 'pointer-missing' | 'pointer-malformed' | 'cross-clone' | 'ok';
+}
+/**
+ * Verify a worktree at `worktreePath` was created from the clone at `expectedClonePath`.
+ *
+ * A git worktree contains a `.git` *file* (not directory) that points at the parent clone's
+ * `.git/worktrees/<name>/` directory. We parse the pointer and confirm it resolves under
+ * `expectedClonePath/.git/worktrees/`. Any mismatch returns owned=false with a structured reason.
+ */
+export declare function verifyOwnership(worktreePathArg: string, expectedClonePath: string): Promise<OwnershipResult>;
+export declare function assertOwnership(worktreePathArg: string, expectedClonePath: string): Promise<void>;
+export declare function isExistingWorktree(worktreePathArg: string): Promise<boolean>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/runtime/worktree.js

@@ -0,0 +1,111 @@
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+const SLUG_INVALID = /[^a-zA-Z0-9._-]+/g;
+const SLUG_DEDUPE = /-+/g;
+export class WorktreeOwnershipError extends Error {
+    worktreePath;
+    expectedClone;
+    actualClone;
+    constructor(message, worktreePath, expectedClone, actualClone) {
+        super(message);
+        this.worktreePath = worktreePath;
+        this.expectedClone = expectedClone;
+        this.actualClone = actualClone;
+        this.name = 'WorktreeOwnershipError';
+    }
+}
+export function slugifyBranch(branch) {
+    if (!branch) {
+        throw new Error('Branch name cannot be empty');
+    }
+    const slug = branch
+        .replace(SLUG_INVALID, '-')
+        .replace(SLUG_DEDUPE, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug) {
+        throw new Error(`Branch name has no slug-safe characters: ${branch}`);
+    }
+    return slug;
+}
+export function worktreePath(rootDir, branch) {
+    return join(rootDir, slugifyBranch(branch));
+}
+/**
+ * Verify a worktree at `worktreePath` was created from the clone at `expectedClonePath`.
+ *
+ * A git worktree contains a `.git` *file* (not directory) that points at the parent clone's
+ * `.git/worktrees/<name>/` directory. We parse the pointer and confirm it resolves under
+ * `expectedClonePath/.git/worktrees/`. Any mismatch returns owned=false with a structured reason.
+ */
+export async function verifyOwnership(worktreePathArg, expectedClonePath) {
+    const expectedWorktreesDir = resolve(expectedClonePath, '.git', 'worktrees');
+    // Canonicalize the expected dir to follow symlinks (e.g., macOS /var → /private/var).
+    // realpath fails if the path doesn't exist; fall back to resolve() in that case.
+    let canonicalExpected = expectedWorktreesDir;
+    try {
+        canonicalExpected = await realpath(expectedWorktreesDir);
+    }
+    catch {
+        /* directory doesn't exist yet — keep the resolved (non-canonical) path */
+    }
+    const dotGitPath = join(worktreePathArg, '.git');
+    let pointer;
+    try {
+        const buf = await readFile(dotGitPath);
+        pointer = buf.toString('utf8').trim();
+    }
+    catch {
+        return {
+            owned: false,
+            expectedClone: canonicalExpected,
+            actualClone: null,
+            reason: 'pointer-missing',
+        };
+    }
+    // Pointer file format per git docs: `gitdir: <absolute-path>` or `gitdir: <relative-path>`.
+    const match = pointer.match(/^gitdir:\s*(.+)$/);
+    if (!match) {
+        return {
+            owned: false,
+            expectedClone: canonicalExpected,
+            actualClone: pointer || null,
+            reason: 'pointer-malformed',
+        };
+    }
+    const declared = match[1].trim();
+    const declaredAbs = isAbsolute(declared) ? declared : resolve(dirname(dotGitPath), declared);
+    // Canonicalize the declared path the same way; if it doesn't exist, the worktree is
+    // detached and we can fall back to the resolved string.
+    let canonicalDeclared = resolve(declaredAbs);
+    try {
+        canonicalDeclared = await realpath(declaredAbs);
+    }
+    catch {
+        /* declared dir doesn't exist — use the resolved string for comparison */
+    }
+    // The pointer should land inside `<expectedClone>/.git/worktrees/<name>/`.
+    const owned = canonicalDeclared === canonicalExpected ||
+        canonicalDeclared.startsWith(canonicalExpected + sep);
+    return {
+        owned,
+        expectedClone: canonicalExpected,
+        actualClone: canonicalDeclared,
+        reason: owned ? 'ok' : 'cross-clone',
+    };
+}
+export async function assertOwnership(worktreePathArg, expectedClonePath) {
+    const result = await verifyOwnership(worktreePathArg, expectedClonePath);
+    if (!result.owned) {
+        throw new WorktreeOwnershipError(`Worktree ownership verification failed for ${worktreePathArg}: ${result.reason}`, worktreePathArg, result.expectedClone, result.actualClone);
+    }
+}
+export async function isExistingWorktree(worktreePathArg) {
+    try {
+        const dotGit = await stat(join(worktreePathArg, '.git'));
+        return dotGit.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/sa-scoring/auto-calibrate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Phase 3 weight auto-calibration (RFC-0008 Addendum B §B.8).
+ *
+ * Reads trailing-90-day precision from `SAFeedbackStore`, shifts the
+ * Phase 3 (w_structural, w_llm) pair in the direction of the better-
+ * performing layer, and persists the result to `sa_phase_weights`.
+ *
+ * CR-2: `w_structural ≥ 0.20` floor enforced on the output, as is a
+ * symmetric `w_llm ≥ 0.20` floor — extreme single-layer dominance is
+ * never written.
+ *
+ * Idempotent: if the computed weights round-trip to the currently
+ * persisted pair, the row is not written and the caller's diff is
+ * empty. Rolling 90-day window by default.
+ */
+import type { SaDimension } from '../state/types.js';
+import type { StateStore } from '../state/store.js';
+import type { SAFeedbackStore } from './feedback-store.js';
+import type { PhaseWeights } from './composite.js';
+export declare const WEIGHT_FLOOR = 0.2;
+export declare const WEIGHT_CEILING: number;
+export declare const DEFAULT_SHIFT_SIZE = 0.05;
+export declare const PRECISION_DELTA_THRESHOLD = 0.1;
+/** Default calibration window — 90 days. */
+export declare const DEFAULT_WINDOW_DAYS = 90;
+/** Phase 2c default weights — used as starting point if none persisted. */
+export declare const DEFAULT_STARTING_WEIGHTS: PhaseWeights;
+export interface PrecisionPair {
+    structural: number;
+    llm: number;
+}
+export interface CalibrationDecision {
+    /** 'toward-structural' | 'toward-llm' | 'hold' */
+    direction: 'toward-structural' | 'toward-llm' | 'hold';
+    /** Magnitude of the LLM−structural precision difference. */
+    delta: number;
+}
+export declare function decideCalibrationDirection(precision: PrecisionPair): CalibrationDecision;
+export interface ComputePhase3WeightsInput {
+    current: PhaseWeights;
+    precision: PrecisionPair;
+    shiftSize?: number;
+}
+export declare function computePhase3Weights(input: ComputePhase3WeightsInput): PhaseWeights;
+export interface AutoCalibrateDeps {
+    feedback: SAFeedbackStore;
+    stateStore: StateStore;
+    /** Clock injection for deterministic tests. */
+    now?: () => number;
+    /** Override the window (default 90d). */
+    windowDays?: number;
+    /** Starting weights when none are persisted. */
+    startingWeights?: PhaseWeights;
+    /** Adjustment step size per calibration run. */
+    shiftSize?: number;
+}
+export interface DimensionDiff {
+    dimension: SaDimension;
+    precision: PrecisionPair;
+    previous: PhaseWeights;
+    next: PhaseWeights;
+    changed: boolean;
+}
+export interface AutoCalibrateResult {
+    diffs: DimensionDiff[];
+}
+export declare function autoCalibratePhaseWeights(deps: AutoCalibrateDeps): Promise<AutoCalibrateResult>;
+export declare function renderCalibrationDiff(result: AutoCalibrateResult): string;
+//# sourceMappingURL=auto-calibrate.d.ts.map

package/dist/sa-scoring/auto-calibrate.js

@@ -0,0 +1,107 @@
+/**
+ * Phase 3 weight auto-calibration (RFC-0008 Addendum B §B.8).
+ *
+ * Reads trailing-90-day precision from `SAFeedbackStore`, shifts the
+ * Phase 3 (w_structural, w_llm) pair in the direction of the better-
+ * performing layer, and persists the result to `sa_phase_weights`.
+ *
+ * CR-2: `w_structural ≥ 0.20` floor enforced on the output, as is a
+ * symmetric `w_llm ≥ 0.20` floor — extreme single-layer dominance is
+ * never written.
+ *
+ * Idempotent: if the computed weights round-trip to the currently
+ * persisted pair, the row is not written and the caller's diff is
+ * empty. Rolling 90-day window by default.
+ */
+import { W_STRUCTURAL_FLOOR } from './composite.js';
+// ── Defaults and constants ──────────────────────────────────────────
+export const WEIGHT_FLOOR = W_STRUCTURAL_FLOOR; // 0.20
+export const WEIGHT_CEILING = 1 - WEIGHT_FLOOR; // 0.80
+export const DEFAULT_SHIFT_SIZE = 0.05;
+export const PRECISION_DELTA_THRESHOLD = 0.1;
+/** Default calibration window — 90 days. */
+export const DEFAULT_WINDOW_DAYS = 90;
+/** Phase 2c default weights — used as starting point if none persisted. */
+export const DEFAULT_STARTING_WEIGHTS = Object.freeze({
+    wStructural: 0.35,
+    wLlm: 0.65,
+});
+export function decideCalibrationDirection(precision) {
+    const delta = precision.llm - precision.structural;
+    if (delta > PRECISION_DELTA_THRESHOLD)
+        return { direction: 'toward-llm', delta };
+    if (delta < -PRECISION_DELTA_THRESHOLD)
+        return { direction: 'toward-structural', delta };
+    return { direction: 'hold', delta };
+}
+export function computePhase3Weights(input) {
+    const shift = input.shiftSize ?? DEFAULT_SHIFT_SIZE;
+    const decision = decideCalibrationDirection(input.precision);
+    let wStructural = input.current.wStructural;
+    if (decision.direction === 'toward-llm')
+        wStructural -= shift;
+    else if (decision.direction === 'toward-structural')
+        wStructural += shift;
+    wStructural = Math.max(WEIGHT_FLOOR, Math.min(WEIGHT_CEILING, wStructural));
+    return { wStructural, wLlm: 1 - wStructural };
+}
+export async function autoCalibratePhaseWeights(deps) {
+    const nowMs = (deps.now ?? (() => Date.now()))();
+    const windowDays = deps.windowDays ?? DEFAULT_WINDOW_DAYS;
+    const since = new Date(nowMs - windowDays * 24 * 60 * 60 * 1000).toISOString();
+    const startingWeights = deps.startingWeights ?? DEFAULT_STARTING_WEIGHTS;
+    const diffs = [];
+    for (const dimension of ['SA-1', 'SA-2']) {
+        const existing = deps.stateStore.getSaPhaseWeights(dimension);
+        const current = existing
+            ? { wStructural: existing.wStructural, wLlm: existing.wLlm }
+            : startingWeights;
+        const structural = deps.feedback.structuralPrecision({ dimension, since });
+        const llm = deps.feedback.llmPrecision({ dimension, since });
+        const precision = {
+            structural: structural.precision,
+            llm: llm.precision,
+        };
+        const next = computePhase3Weights({
+            current,
+            precision,
+            shiftSize: deps.shiftSize,
+        });
+        const changed = !weightsEqual(current, next) || !existing; /* first-run write */
+        if (changed) {
+            deps.stateStore.upsertSaPhaseWeights({
+                dimension,
+                wStructural: next.wStructural,
+                wLlm: next.wLlm,
+            });
+        }
+        diffs.push({
+            dimension,
+            precision,
+            previous: current,
+            next,
+            // `changed` is true when we actually wrote: either the weight pair
+            // shifted, OR this was the mandatory first-run initialisation.
+            changed,
+        });
+    }
+    return { diffs };
+}
+function weightsEqual(a, b) {
+    return Math.abs(a.wStructural - b.wStructural) < 1e-9 && Math.abs(a.wLlm - b.wLlm) < 1e-9;
+}
+// ── Diff rendering (for CLI) ─────────────────────────────────────────
+export function renderCalibrationDiff(result) {
+    const lines = [];
+    lines.push('SA phase-weight calibration diff');
+    lines.push('--------------------------------');
+    for (const d of result.diffs) {
+        lines.push(`${d.dimension}:`);
+        lines.push(`  previous : w_structural=${d.previous.wStructural.toFixed(3)}  w_llm=${d.previous.wLlm.toFixed(3)}`);
+        lines.push(`  next     : w_structural=${d.next.wStructural.toFixed(3)}  w_llm=${d.next.wLlm.toFixed(3)}`);
+        lines.push(`  precision: structural=${(d.precision.structural * 100).toFixed(1)}%  llm=${(d.precision.llm * 100).toFixed(1)}%`);
+        lines.push(`  changed  : ${d.changed ? 'yes' : 'no'}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=auto-calibrate.js.map