@ai-dossier/sched 0.2.0 → 0.3.0

package/dist/teardown.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Script-based teardown for merged units (#468 AC2) — the tail work that the
+ * fleet pattern used to re-dispatch a whole full-cycle run for.
+ *
+ * Two scripts, chosen by the run's `setup` milestone:
+ * - pool-claimed worktree → `worktree-pool return --path <wt> --json` — the
+ *   pool's own self-check (#453: `verification.entry_status`) is the
+ *   verification; a non-`warm` entry or a failed exit is a failed step.
+ * - cold worktree → `git worktree remove --force <wt>` + a path-gone check
+ *   (verify-first, so a re-run after a crash between subprocess and state
+ *   write is idempotent).
+ *
+ * `--force` on the remove is deliberate: the WIP-sync rule pushes everything
+ * durable to origin, so untracked leftovers (logs, warmup status) are trash.
+ *
+ * A failed teardown is DEGRADATION, never unit failure — the PR is already
+ * merged. The outcome is recorded as `cleanup=failed-<step>` on the entry and
+ * journaled, and the report agent is dispatched regardless so the failure is
+ * surfaced in the report.
+ *
+ * Everything runs through an injectable `ExecFn` (the project.ts pattern) —
+ * tests script the subprocesses, no real pool or git is touched.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEARDOWN_TIMEOUT_MS = void 0;
+exports.isSafeWorktree = isSafeWorktree;
+exports.runTeardown = runTeardown;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Timeout for teardown subprocesses — pool return shells out through npx and recycles a worktree (git ops), which is slow. */
+exports.TEARDOWN_TIMEOUT_MS = 120_000;
+/**
+ * Pool CLI invocation. Requires ≥0.6.0 — `status --json`, `return --json`,
+ * and the `verification.entry_status` self-check (#453) all landed there, so
+ * `^0.5.1` (which resolves to ≤0.5.3) cannot ever satisfy the JSON contract
+ * and every pool teardown would record `failed-pool-return`. Versions ≤0.5.0
+ * additionally carry the data-loss `gc` bug — never pin lower.
+ */
+const POOL_BIN = 'npx';
+const POOL_ARGS_PREFIX = ['-y', '@ai-dossier/worktree-pool@^0.6.0'];
+/**
+ * Containment check for a worktree path recovered from an issue comment
+ * (#468): the path must be absolute and fully resolved (no `..`/`.`/symlink
+ * variance), and — for COLD worktrees — live under one of the two worktree
+ * roots this project uses: `<repo>/worktrees/` (setup-issue-workflow's
+ * inside-repo convention) or `<repo>/../worktrees/` (the AGENTS.md sibling
+ * convention). A crafted milestone can otherwise make the scheduler
+ * `git worktree remove --force` ANY registered worktree — including a
+ * parallel agent's (CWE-22). Pool-claimed worktrees are validated by the
+ * pool itself (return only accepts paths in pool state), so containment
+ * applies to the cold path only.
+ */
+function isSafeWorktree(repoRoot, worktree) {
+    if (worktree.includes('\0'))
+        return false;
+    if (!path.isAbsolute(worktree))
+        return false;
+    if (path.resolve(worktree) !== worktree)
+        return false;
+    const roots = [path.resolve(repoRoot, 'worktrees'), path.resolve(repoRoot, '..', 'worktrees')];
+    return roots.some((root) => worktree.startsWith(root + path.sep));
+}
+/** The repo's toplevel directory (containment root), or null when git cannot say. */
+function repoToplevel(exec, repoDir) {
+    const out = exec('git', ['rev-parse', '--show-toplevel'], repoDir);
+    return out !== null && path.isAbsolute(out) ? path.resolve(out) : null;
+}
+/** Path-listing of `git worktree list --porcelain` (null when the call fails). */
+function worktreeList(exec, repoDir) {
+    return exec('git', ['worktree', 'list', '--porcelain'], repoDir);
+}
+/** Whether `worktree` still appears in git's worktree listing. */
+function listedAsWorktree(exec, repoDir, worktree) {
+    const list = worktreeList(exec, repoDir);
+    if (list === null)
+        return true; // unknown — assume still present (conservative)
+    return list
+        .split('\n')
+        .some((line) => line.startsWith('worktree ') && line.slice('worktree '.length) === worktree);
+}
+/**
+ * Run the teardown script for one merged unit. `info` comes from the unit's
+ * setup milestone (groundtruth.setupInfo); a missing `info` is the caller's
+ * `failed-missing-setup-info` case — this function always has one.
+ */
+function runTeardown(exec, repoDir, info, fsExists = (p) => {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}) {
+    // The worktree path originates from an issue comment written by the spawned
+    // agent — validate it before any destructive subprocess (CWE-22).
+    if (info.worktree.includes('\0') || !path.isAbsolute(info.worktree)) {
+        return {
+            cleanup: 'failed-invalid-worktree',
+            detail: `worktree path rejected (must be absolute): ${info.worktree}`,
+        };
+    }
+    if (info.poolClaimed) {
+        // Pool membership is validated by the pool's own `return` (it only
+        // accepts paths in pool state) — no local containment root applies.
+        return poolReturn(exec, repoDir, info.worktree);
+    }
+    const root = repoToplevel(exec, repoDir) ?? path.resolve(repoDir);
+    if (!isSafeWorktree(root, info.worktree)) {
+        return {
+            cleanup: 'failed-invalid-worktree',
+            detail: `worktree path rejected (must be a resolved path under the repo's worktrees root ${path.join(root, 'worktrees')}): ${info.worktree}`,
+        };
+    }
+    return worktreeRemove(exec, repoDir, info.worktree, fsExists);
+}
+function poolReturn(exec, repoDir, worktree) {
+    // Verify-first idempotency: if the pool already lists this path as a warm
+    // (unassigned) spare, a previous return landed and the state write was
+    // lost — claim done rather than erroring a second return.
+    const statusJson = exec(POOL_BIN, [...POOL_ARGS_PREFIX, 'status', '--json'], repoDir);
+    if (statusJson !== null && poolEntryFor(statusJson, worktree) === 'warm') {
+        return { cleanup: 'done', detail: 'already returned to pool (idempotent re-run)' };
+    }
+    const out = exec(POOL_BIN, [...POOL_ARGS_PREFIX, 'return', '--path', worktree, '--json'], repoDir);
+    if (out === null) {
+        return {
+            cleanup: 'failed-pool-return',
+            detail: 'worktree-pool return failed (non-zero exit, timeout, or npx unavailable) — entry left unverified; inspect `worktree-pool status`',
+        };
+    }
+    // Verified before claimed: the pool's own self-check must report the
+    // recycled entry as `warm` — anything else is a failed step.
+    const entryStatus = parseReturnVerification(out);
+    if (entryStatus === null) {
+        return {
+            cleanup: 'failed-pool-return',
+            detail: 'worktree-pool return produced unparseable output',
+        };
+    }
+    if (entryStatus !== 'warm') {
+        return {
+            cleanup: 'failed-pool-return',
+            detail: `pool self-check reports entry_status=${entryStatus}`,
+        };
+    }
+    return { cleanup: 'done', detail: 'returned to pool as a warm spare' };
+}
+function worktreeRemove(exec, repoDir, worktree, fsExists) {
+    // Verify-first idempotency: already gone → a previous remove landed.
+    if (!fsExists(worktree) && !listedAsWorktree(exec, repoDir, worktree)) {
+        return { cleanup: 'done', detail: 'worktree already removed (idempotent re-run)' };
+    }
+    const out = exec('git', ['worktree', 'remove', '--force', '--', worktree], repoDir);
+    if (out === null) {
+        return {
+            cleanup: 'failed-worktree-remove',
+            detail: 'git worktree remove failed (non-zero exit or timeout)',
+        };
+    }
+    // Verified before claimed: the path must be gone AND git must no longer
+    // list it — a lingering entry means the removal did not fully land.
+    if (fsExists(worktree) || listedAsWorktree(exec, repoDir, worktree)) {
+        return {
+            cleanup: 'failed-worktree-remove',
+            detail: 'worktree still present after git worktree remove',
+        };
+    }
+    return { cleanup: 'done', detail: 'worktree removed' };
+}
+/** The pool entry status (`warm`/`assigned`/…) for `worktree`, or null when absent/unparseable. */
+function poolEntryFor(statusJson, worktree) {
+    try {
+        const parsed = JSON.parse(statusJson);
+        if (parsed === null || typeof parsed !== 'object')
+            return null;
+        const worktrees = parsed.worktrees;
+        if (!Array.isArray(worktrees))
+            return null;
+        for (const raw of worktrees) {
+            if (raw === null || typeof raw !== 'object')
+                continue;
+            const entry = raw;
+            if (entry.path === worktree && typeof entry.status === 'string')
+                return entry.status;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `verification.entry_status` of a successful `return --json`, or null when unparseable. */
+function parseReturnVerification(returnJson) {
+    try {
+        const parsed = JSON.parse(returnJson);
+        if (parsed === null || typeof parsed !== 'object')
+            return null;
+        const verification = parsed.verification;
+        if (verification === null || typeof verification !== 'object')
+            return null;
+        const status = verification.entry_status;
+        return typeof status === 'string' ? status : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=teardown.js.map

package/dist/teardown.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Types for the deterministic scheduler core (RFC-0001 §B/C.1/D, issue #460).
+ *
+ * The state unions below are the RFC-0001 §D state machines frozen into types.
+ * `state.ts` owns the transition tables; nothing here does I/O. The package
+ * itself never invokes an LLM: it spawns the agent process the operator
+ * configured (dispatch.ts) and reads ground truth via injectable subprocess
+ * exec (project.ts, groundtruth.ts) — never an LLM call of its own (AC7).
+ */
+/** Execution mode of a queue entry. `full` runs the unchanged full-cycle; `slot` runs as a batch member. */
+export type CycleMode = 'full' | 'slot';
+/** Model tier the entry is dispatched at (RFC-0001 role-based routing: mechanical / generation / judgment). */
+export type ModelTier = 'mechanical' | 'mid' | 'strong';
+/**
+ * Issue lifecycle per RFC-0001 §D.1:
+ *
+ * ```
+ * queued → classified{full|slot}
+ *   full:  → dispatched → (full-cycle's own phase trail) → shipped → done
+ *           #468 detached ship: dispatched → parked{pr} (PR on auto-merge;
+ *           the watcher owns the merge wait) → shipped → done
+ *   slot:  → batched(b) → waiting → in-work → committed(range) → validated
+ *              → shipped-in-batch → done
+ * failure edges (any state):
+ *   in-work/committed → evicted(reason) → requeued{full}
+ *   any → blocked(dep-failed) | decision-pending | failed(escalation-cap)
+ * ```
+ */
+export type IssueStatus = 'queued' | 'classified' | 'dispatched' | 'parked' | 'shipped' | 'done' | 'batched' | 'waiting' | 'in-work' | 'committed' | 'validated' | 'shipped-in-batch' | 'evicted' | 'requeued' | 'blocked' | 'decision-pending' | 'failed';
+/** Issue statuses that cannot transition further. */
+export declare const TERMINAL_ISSUE_STATUSES: ReadonlySet<IssueStatus>;
+/**
+ * Statuses that mean the issue's work has merged. Dependency edges gate on
+ * these: "an issue with an unmerged dependency is never runnable" (AC5).
+ */
+export declare const SATISFIED_ISSUE_STATUSES: ReadonlySet<IssueStatus>;
+/** Teardown outcome values (#468): verified cleanup or a failed step. */
+export type CleanupStatus = 'done' | `failed-${string}`;
+/**
+ * Batch lifecycle per RFC-0001 §D.2:
+ *
+ * ```
+ * forming → ready → executing(member i/N) ⟲ → validating → reviewing → shipping
+ *   → awaiting-merge → merged → deployed → reported → done
+ * failure edges:
+ *   validating → attributing → fixing(1 bounded attempt) → validating
+ *              → evicting(revert range) → validating
+ *   evictions > ⅓ OR revert-conflict → dissolving → members requeued
+ *   awaiting-merge: CONFLICTING | auto-merge-blocked → rebasing → re-validating → shipping
+ *                   (2nd failure → dissolved)
+ * ```
+ */
+export type BatchStatus = 'forming' | 'ready' | 'executing' | 'validating' | 'attributing' | 'fixing' | 'evicting' | 'reviewing' | 'shipping' | 'awaiting-merge' | 'rebasing' | 're-validating' | 'merged' | 'deployed' | 'reported' | 'done' | 'dissolving' | 'dissolved';
+/** Batch statuses that cannot transition further. */
+export declare const TERMINAL_BATCH_STATUSES: ReadonlySet<BatchStatus>;
+/**
+ * Batch statuses that mean the batch's PR has merged. Cross-batch dependency
+ * edges gate on these (a batch is never dispatched while a batch it depends
+ * on is unmerged — RFC-0001 §E.4 "scheduler gates on merge").
+ */
+export declare const MERGED_BATCH_STATUSES: ReadonlySet<BatchStatus>;
+/**
+ * Worker slot lifecycle per RFC-0001 §D.3:
+ *
+ * ```
+ * idle → assigned(unit) → running(pid, phase, last_progress_at)
+ *   → exited → verifying(reconcile vs GitHub/runstate) → complete → idle
+ * stall: running[30 min no progress] → recovering(redispatch tier+1, ≤2) → running | failed → idle
+ * ```
+ */
+export type SlotStatus = 'idle' | 'assigned' | 'running' | 'exited' | 'verifying' | 'complete' | 'recovering' | 'failed';
+/** Slot statuses that hold a live unit against `max_slots`. */
+export declare const LIVE_SLOT_STATUSES: ReadonlySet<SlotStatus>;
+/** One queued unit of work (RFC-0001 §C.1 "queue entries"). */
+export interface QueueEntry {
+    /** GitHub issue number. Unique among active entries. */
+    issue: number;
+    /** Execution mode for this issue. */
+    mode: CycleMode;
+    /** Batch id when `mode === 'slot'`; always null for `full`. */
+    batch: string | null;
+    /** Issue numbers this entry depends on (edges gate readiness). */
+    deps: number[];
+    /** Model tier the entry is dispatched at. */
+    tier: ModelTier;
+    /** Current D.1 state. */
+    status: IssueStatus;
+    /** Free-form reason attached to failure-edge transitions (evicted/blocked/failed). */
+    reason: string | null;
+    /**
+     * PR number the unit parked on `auto-merge` (#468), from the ship phase's
+     * `awaiting-merge` milestone (`pr=` key). Set when the agent exits parked;
+     * drives the PR watcher until the merge is accepted.
+     */
+    pr: number | null;
+    /**
+     * Teardown outcome for a merged unit (#468): `done` or `failed-<step>`, or
+     * null while teardown is still pending. Recorded only after the cleanup
+     * was verified (pool return self-check / worktree path gone).
+     */
+    cleanup: CleanupStatus | null;
+    enqueued_at: string;
+    updated_at: string;
+}
+/** A batch of slot-mode issues sharing one lifecycle (RFC-0001 §C.4/E.4). */
+export interface BatchEntry {
+    id: string;
+    status: BatchStatus;
+    /** Member issue numbers, in dispatch order. */
+    members: number[];
+    base_branch: string;
+    /** Index of the member currently in work, when status is `executing` (1-based member pointer). */
+    executing_member: number;
+    created_at: string;
+    updated_at: string;
+}
+/** A worker slot (RFC-0001 §D.3). */
+export interface SlotEntry {
+    id: number;
+    status: SlotStatus;
+    /** Unit identifier currently held: `issue:<n>` or `batch:<id>`; null when idle. */
+    unit: string | null;
+    /** OS pid of the spawned agent process, when known (#464 dispatch). */
+    pid: number | null;
+    /**
+     * `/proc/<pid>/stat` start-time (field 22) recorded at spawn, when
+     * available (Linux). Persisted so a restarted sched can verify a state.json
+     * pid still belongs to our agent — a mismatched start time means the pid
+     * was reused by an unrelated process and must never be signalled (decision
+     * 1, option C). Null on platforms without /proc: best-effort.
+     */
+    pid_start: number | null;
+    /** Scheduler phase the unit is in, when running. */
+    phase: string | null;
+    /** Last progress signal (new milestone or pushed commit) — stall-timer anchor. */
+    last_progress_at: string | null;
+    /** Working branch of the unit, captured from the setup milestone's `branch=` key. */
+    branch: string | null;
+    /** Last seen head sha of `branch` on origin — the "new pushed commit" stall signal. */
+    last_head: string | null;
+    /** Recovery attempts for the current unit (stall ladder, cap 2 — RFC-0001 §C.1). */
+    recoveries: number;
+    updated_at: string;
+}
+/** Hot operational truth, persisted transactionally to `state.json` (RFC-0001 §D.4). */
+export interface SchedState {
+    schema_version: typeof SCHEMA_VERSION;
+    /** When true, `computeAssignments` returns no assignments (sched pause). */
+    paused: boolean;
+    entries: QueueEntry[];
+    batches: BatchEntry[];
+    slots: SlotEntry[];
+    /** Monotonic counter for stable slot ids. */
+    next_slot_id: number;
+    /**
+     * When the PR watcher last polled (#468) — parked PRs are polled every
+     * `pr_poll_interval_ms` (default 150 s). Polled on each reconcile tick
+     * when due (a `reconcile_interval_ms` longer than the interval slows the
+     * effective cadence); persisted so the cadence survives a sched restart.
+     */
+    last_pr_poll_at: string | null;
+}
+/** Durable intent, persisted separately in `config.json` (state.json is rebuildable hot truth). */
+export interface SchedConfig {
+    max_slots: number;
+    /** Stall timeout in ms — no new milestone AND no new pushed commit for this long → redispatch stronger (default 30 min). */
+    stall_timeout_ms?: number;
+    /** Reconciliation tick interval in ms (default 60 000). */
+    reconcile_interval_ms?: number;
+    /**
+     * Parked-PR poll interval in ms (#468, default 150 000 — "every 2–3 min").
+     * Checked on each reconcile tick when due; see `SchedState.last_pr_poll_at`.
+     */
+    pr_poll_interval_ms?: number;
+    /** Agent dispatch settings (#464); every field optional with engine defaults. */
+    dispatch?: DispatchConfig;
+}
+/**
+ * Agent dispatch configuration (#464). The command is a template: `{model}`
+ * and `{issue}` placeholders are substituted per dispatch; a `{model}` item
+ * whose tier has no model configured drops together with its flag.
+ */
+export interface DispatchConfig {
+    /** Command template, e.g. `['claude','-p','--output-format','json','--model','{model}']`. */
+    command?: string[];
+    /** Prompt template sent on the child's stdin; `{issue}` substituted. */
+    prompt?: string;
+    /** Tier → model id/alias mapping (defaults: haiku / sonnet / opus). */
+    tier_models?: Partial<Record<ModelTier, string>>;
+    /**
+     * Prompt template for the report agent dispatched after a merged PR
+     * (#468); `{issue}`, `{pr}` and `{cleanup}` substituted. Defaults to
+     * `DEFAULT_REPORT_PROMPT_TEMPLATE`.
+     */
+    report_prompt?: string;
+}
+/** The escalation ladder: one tier stronger, or null at the top (RFC-0001 §C.1). */
+export declare const TIER_LADDER: Readonly<Record<ModelTier, ModelTier | null>>;
+/** The ladder as an ordered array (weakest first) — the single ordering source. */
+export declare const TIER_ORDER: readonly ModelTier[];
+/** Cap on recovery attempts before a unit fails (RFC-0001 §C.1 "cap 2"). */
+export declare const ESCALATION_CAP = 2;
+/** Default stall timeout: 30 minutes without a milestone or pushed commit (RFC-0001 §C.1). */
+export declare const DEFAULT_STALL_TIMEOUT_MS: number;
+/** Default reconciliation tick: ~60s (RFC-0001 §C.1). */
+export declare const DEFAULT_RECONCILE_INTERVAL_MS: number;
+/** Default parked-PR poll interval: 2.5 min (#468 AC1 "every 2–3 min"). */
+export declare const DEFAULT_PR_POLL_INTERVAL_MS: number;
+export declare const SCHEMA_VERSION: "1.2.0";
+/** Schema versions `validateState` accepts on load (migrated to SCHEMA_VERSION on save). */
+export declare const LEGACY_SCHEMA_VERSIONS: readonly string[];
+export declare const CONFIG_SCHEMA_VERSION: "1.2.0";
+/** Config schema versions `loadConfig` accepts (older configs carry only max_slots). */
+export declare const LEGACY_CONFIG_SCHEMA_VERSIONS: readonly string[];
+/** Config file shape (schema_version + the config itself). */
+export interface SchedConfigFile {
+    schema_version: string;
+    max_slots: number;
+    stall_timeout_ms?: number;
+    reconcile_interval_ms?: number;
+    pr_poll_interval_ms?: number;
+    dispatch?: DispatchConfig;
+}
+export declare const DEFAULT_MAX_SLOTS = 3;
+/** Bounds for `max_slots` when reading `config.json` (named — not magic numbers in persist.ts). */
+export declare const MIN_MAX_SLOTS = 1;
+export declare const MAX_MAX_SLOTS = 64;
+/** Thrown by every non-declared state-machine edge. */
+export declare class IllegalTransitionError extends Error {
+    readonly kind: 'issue' | 'batch' | 'slot';
+    readonly from: string;
+    readonly to: string;
+    constructor(kind: 'issue' | 'batch' | 'slot', from: string, to: string);
+}
+/** Thrown when an issue, batch, or slot id does not exist in the state. */
+export declare class SchedNotFoundError extends Error {
+    constructor(message: string);
+}
+/** Every event the engine journals to `events.jsonl` (append-only). */
+export type JournalEventName = 'assigned' | 'spawned' | 'exit-detected' | 'orphan-pid' | 'external-advance' | 'progress' | 'phase-updated' | 'verify-complete' | 'verify-incomplete' | 'stalled' | 'redispatched' | 'unit-failed' | 'dependents-blocked' | 'requeued' | 'ground-truth-unreachable' | 'tick-failed' | 'pr-parked' | 'merge-accepted' | 'pr-watch-failed' | 'pr-watch-waiting' | 'teardown-done' | 'teardown-failed' | 'report-dispatched' | 'report-failed';
+/** One journaled event. `ts` is stamped by the journal, never by callers. */
+export interface JournalEvent {
+    ts: string;
+    event: JournalEventName;
+    /** Unit the event concerns (`issue:<n>` / `batch:<id>`), when applicable. */
+    unit?: string;
+    slot?: number;
+    issue?: number;
+    pid?: number;
+    tier?: ModelTier;
+    detail?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Types for the deterministic scheduler core (RFC-0001 §B/C.1/D, issue #460).
+ *
+ * The state unions below are the RFC-0001 §D state machines frozen into types.
+ * `state.ts` owns the transition tables; nothing here does I/O. The package
+ * itself never invokes an LLM: it spawns the agent process the operator
+ * configured (dispatch.ts) and reads ground truth via injectable subprocess
+ * exec (project.ts, groundtruth.ts) — never an LLM call of its own (AC7).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedNotFoundError = exports.IllegalTransitionError = exports.MAX_MAX_SLOTS = exports.MIN_MAX_SLOTS = exports.DEFAULT_MAX_SLOTS = exports.LEGACY_CONFIG_SCHEMA_VERSIONS = exports.CONFIG_SCHEMA_VERSION = exports.LEGACY_SCHEMA_VERSIONS = exports.SCHEMA_VERSION = exports.DEFAULT_PR_POLL_INTERVAL_MS = exports.DEFAULT_RECONCILE_INTERVAL_MS = exports.DEFAULT_STALL_TIMEOUT_MS = exports.ESCALATION_CAP = exports.TIER_ORDER = exports.TIER_LADDER = exports.LIVE_SLOT_STATUSES = exports.MERGED_BATCH_STATUSES = exports.TERMINAL_BATCH_STATUSES = exports.SATISFIED_ISSUE_STATUSES = exports.TERMINAL_ISSUE_STATUSES = void 0;
+/** Issue statuses that cannot transition further. */
+exports.TERMINAL_ISSUE_STATUSES = new Set(['done', 'failed']);
+/**
+ * Statuses that mean the issue's work has merged. Dependency edges gate on
+ * these: "an issue with an unmerged dependency is never runnable" (AC5).
+ */
+exports.SATISFIED_ISSUE_STATUSES = new Set([
+    'shipped',
+    'shipped-in-batch',
+    'done',
+]);
+/** Batch statuses that cannot transition further. */
+exports.TERMINAL_BATCH_STATUSES = new Set(['done', 'dissolved']);
+/**
+ * Batch statuses that mean the batch's PR has merged. Cross-batch dependency
+ * edges gate on these (a batch is never dispatched while a batch it depends
+ * on is unmerged — RFC-0001 §E.4 "scheduler gates on merge").
+ */
+exports.MERGED_BATCH_STATUSES = new Set([
+    'merged',
+    'deployed',
+    'reported',
+    'done',
+]);
+/** Slot statuses that hold a live unit against `max_slots`. */
+exports.LIVE_SLOT_STATUSES = new Set([
+    'assigned',
+    'running',
+    'recovering',
+]);
+/** The escalation ladder: one tier stronger, or null at the top (RFC-0001 §C.1). */
+exports.TIER_LADDER = {
+    mechanical: 'mid',
+    mid: 'strong',
+    strong: null,
+};
+/** The ladder as an ordered array (weakest first) — the single ordering source. */
+exports.TIER_ORDER = ['mechanical', 'mid', 'strong'];
+/** Cap on recovery attempts before a unit fails (RFC-0001 §C.1 "cap 2"). */
+exports.ESCALATION_CAP = 2;
+/** Default stall timeout: 30 minutes without a milestone or pushed commit (RFC-0001 §C.1). */
+exports.DEFAULT_STALL_TIMEOUT_MS = 30 * 60 * 1000;
+/** Default reconciliation tick: ~60s (RFC-0001 §C.1). */
+exports.DEFAULT_RECONCILE_INTERVAL_MS = 60 * 1000;
+/** Default parked-PR poll interval: 2.5 min (#468 AC1 "every 2–3 min"). */
+exports.DEFAULT_PR_POLL_INTERVAL_MS = 150 * 1000;
+exports.SCHEMA_VERSION = '1.2.0';
+/** Schema versions `validateState` accepts on load (migrated to SCHEMA_VERSION on save). */
+exports.LEGACY_SCHEMA_VERSIONS = ['1.0.0', '1.1.0'];
+exports.CONFIG_SCHEMA_VERSION = '1.2.0';
+/** Config schema versions `loadConfig` accepts (older configs carry only max_slots). */
+exports.LEGACY_CONFIG_SCHEMA_VERSIONS = ['1.0.0', '1.1.0'];
+exports.DEFAULT_MAX_SLOTS = 3;
+/** Bounds for `max_slots` when reading `config.json` (named — not magic numbers in persist.ts). */
+exports.MIN_MAX_SLOTS = 1;
+exports.MAX_MAX_SLOTS = 64;
+/** Thrown by every non-declared state-machine edge. */
+class IllegalTransitionError extends Error {
+    kind;
+    from;
+    to;
+    constructor(kind, from, to) {
+        super(`Illegal ${kind} transition: ${from} → ${to}`);
+        this.name = 'IllegalTransitionError';
+        this.kind = kind;
+        this.from = from;
+        this.to = to;
+    }
+}
+exports.IllegalTransitionError = IllegalTransitionError;
+/** Thrown when an issue, batch, or slot id does not exist in the state. */
+class SchedNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SchedNotFoundError';
+    }
+}
+exports.SchedNotFoundError = SchedNotFoundError;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AA8CH,qDAAqD;AACxC,QAAA,uBAAuB,GAA6B,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7F;;;GAGG;AACU,QAAA,wBAAwB,GAA6B,IAAI,GAAG,CAAC;IACxE,SAAS;IACT,kBAAkB;IAClB,MAAM;CACP,CAAC,CAAC;AAyCH,qDAAqD;AACxC,QAAA,uBAAuB,GAA6B,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAEhG;;;;GAIG;AACU,QAAA,qBAAqB,GAA6B,IAAI,GAAG,CAAC;IACrE,QAAQ;IACR,UAAU;IACV,UAAU;IACV,MAAM;CACP,CAAC,CAAC;AAuBH,+DAA+D;AAClD,QAAA,kBAAkB,GAA4B,IAAI,GAAG,CAAC;IACjE,UAAU;IACV,SAAS;IACT,YAAY;CACb,CAAC,CAAC;AAqIH,oFAAoF;AACvE,QAAA,WAAW,GAAkD;IACxE,UAAU,EAAE,KAAK;IACjB,GAAG,EAAE,QAAQ;IACb,MAAM,EAAE,IAAI;CACb,CAAC;AAEF,mFAAmF;AACtE,QAAA,UAAU,GAAyB,CAAC,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAEhF,4EAA4E;AAC/D,QAAA,cAAc,GAAG,CAAC,CAAC;AAEhC,8FAA8F;AACjF,QAAA,wBAAwB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvD,yDAAyD;AAC5C,QAAA,6BAA6B,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvD,2EAA2E;AAC9D,QAAA,2BAA2B,GAAG,GAAG,GAAG,IAAI,CAAC;AAEzC,QAAA,cAAc,GAAG,OAAgB,CAAC;AAE/C,4FAA4F;AAC/E,QAAA,sBAAsB,GAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAE/D,QAAA,qBAAqB,GAAG,OAAgB,CAAC;AAEtD,wFAAwF;AAC3E,QAAA,6BAA6B,GAAsB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAYtE,QAAA,iBAAiB,GAAG,CAAC,CAAC;AAEnC,mGAAmG;AACtF,QAAA,aAAa,GAAG,CAAC,CAAC;AAClB,QAAA,aAAa,GAAG,EAAE,CAAC;AAEhC,uDAAuD;AACvD,MAAa,sBAAuB,SAAQ,KAAK;IACtC,IAAI,CAA6B;IACjC,IAAI,CAAS;IACb,EAAE,CAAS;IAEpB,YAAY,IAAgC,EAAE,IAAY,EAAE,EAAU;QACpE,KAAK,CAAC,WAAW,IAAI,gBAAgB,IAAI,MAAM,EAAE,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;CACF;AAZD,wDAYC;AAED,2EAA2E;AAC3E,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-dossier/sched",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deterministic scheduler core for dossier batch cycles \u2014 queue, slots, persistent state machine, dispatch engine with completion verification and stall/escalation ladder. The scheduler never invokes an LLM.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",