@aperant/framework 0.17.0 → 0.19.0

package/dist/cli/produce/scheduler.mjs

@@ -0,0 +1,399 @@
+/**
+ * @internal
+ * produce/scheduler.mjs — the deterministic WSJF/WIP "what-next-under-budget"
+ * brain (M5, ID-M5-01/ID-M5-02).
+ *
+ * A NEW CONSUMER that FOLDS the existing M1/M3/M4 projections into a WSJF
+ * (Weighted Shortest Job First) ranking of the READY milestones + a WIP-limited
+ * pick. It reads `projectRoadmap` (M1 status/order/title), `projectLedger` (M3
+ * open acceptance criteria per milestone), `listRegressions` + the run's latest
+ * `produce.ttl.reverified` result (M4 unresolved regression), and its OWN small
+ * meta-fold over `produce.roadmap.milestone_added` (the additive depends_on /
+ * priority / size fields). It NEVER writes to those modules — projection.mjs /
+ * ledger.mjs / saga.mjs / verification-ttl.mjs stay BYTE-UNTOUCHED (ID-M5-02).
+ *
+ * The math is pure integer arithmetic over recorded folds — NO LLM, NO model id
+ * (scheduler.mjs is in the produce-no-hardcoded-models.guard scan list, AC11),
+ * NO daemon, NO loop. `computeSchedule` emits NO event (a pure read); the wake
+ * `tick` is the ONLY writer of `produce.schedule.computed` (ID-M5-06).
+ *
+ * WSJF(m) = CostOfDelay(m) / JobSize(m)
+ *   CostOfDelay(m) = W_REGRESS·regression_flag(m)   // 5·{0|1}
+ *                  + W_BLOCK  ·blocking_count(m)     // 3·(# milestones depending on m)
+ *                  + W_VALUE  ·open_criteria(m)      // 2·(M3 open criteria bound to m)
+ *                  + priority(m)                      // + optional declared priority (default 0)
+ *   JobSize(m)     = declared_size(m) > 0 ? declared_size(m) : max(open_criteria(m), 1)
+ *
+ * open_criteria deliberately appears in BOTH the CoD value term AND (as the
+ * fallback) in JobSize — standard WSJF (prefer small, high-value jobs); a
+ * declared --size decouples them (ID-M5-01). ready_queue is sorted WSJF
+ * descending → roadmap first-seen order → milestone_id, a total stable order so
+ * two folds of the same log are byte-identical.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readProduceRunEventsMatching } from './events.mjs';
+import { projectLedger } from './ledger.mjs';
+import { projectRoadmap } from './projection.mjs';
+import { listRegressions } from './verification-ttl.mjs';
+/**
+ * WSJF cost-of-delay weights (ID-M5-01). Fixed integer constants — the ordering
+ * is intentional: a shipped-but-regressed milestone is user-facing breakage
+ * (most urgent) > a milestone blocking many downstream ones > a milestone with
+ * more open value locked behind it > a human-declared priority nudge.
+ */
+export const W_REGRESS = 5;
+export const W_BLOCK = 3;
+export const W_VALUE = 2;
+/** The default WIP cap when neither a flag nor config supplies one (ID-M5-05). */
+export const DEFAULT_WIP_LIMIT = 1;
+/**
+ * Load `.aperant/config.json` defensively (mirrors roadmap/backend-adapter.mjs).
+ * Returns `{}` on any read/parse failure so the WIP resolver never throws.
+ *
+ * @param {string} projectDir
+ * @returns {Record<string, unknown>}
+ */
+function loadConfig(projectDir) {
+    const p = join(projectDir, '.aperant', 'config.json');
+    if (!existsSync(p))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Resolve the WIP cap deterministically (ID-M5-05):
+ * `--wip <n>` flag → `.aperant/config.json :: produce.wip` → default 1. A
+ * non-numeric / negative / bare `--wip` value is ignored (falls through). The
+ * cap is the max number of CONCURRENT in_progress milestones the loop will run.
+ *
+ * @param {string} projectDir
+ * @param {Map<string, string | true>} flags
+ * @returns {number}
+ */
+export function resolveWipLimit(projectDir, flags) {
+    const flagVal = flags && typeof flags.get === 'function' ? flags.get('wip') : undefined;
+    if (typeof flagVal === 'string') {
+        const n = Number.parseInt(flagVal, 10);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    const cfg = loadConfig(projectDir);
+    const produceCfg = cfg && typeof cfg.produce === 'object' && cfg.produce !== null ? cfg.produce : null;
+    if (produceCfg && Number.isFinite(produceCfg.wip) && Number(produceCfg.wip) >= 0) {
+        return Math.trunc(Number(produceCfg.wip));
+    }
+    return DEFAULT_WIP_LIMIT;
+}
+/**
+ * Fold the run's `produce.roadmap.milestone_added` events into the per-milestone
+ * scheduling metadata carried as ADDITIVE optional fields on that event
+ * (ID-M5-03): `depends_on` (string[]), `priority` (int, default 0), `size`
+ * (positive int | null). An M1-style milestone (added with no new flags) folds
+ * to `{ depends_on: [], priority: 0, size: null }` — byte-identical behavior.
+ * First-seen wins (idempotent re-adds never clobber).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Map<string, { depends_on: string[], priority: number, size: number | null }>}
+ */
+export function readMilestoneMeta(projectDir, runId) {
+    const events = readProduceRunEventsMatching(projectDir, runId, (op) => op === 'produce.roadmap.milestone_added');
+    const meta = new Map();
+    for (const e of events) {
+        const d = e.data || {};
+        const id = typeof d.milestone_id === 'string' ? d.milestone_id : null;
+        if (!id || meta.has(id))
+            continue;
+        const dependsOn = Array.isArray(d.depends_on)
+            ? d.depends_on.filter((x) => typeof x === 'string' && x.length > 0)
+            : [];
+        const priority = Number.isFinite(d.priority) ? Math.trunc(Number(d.priority)) : 0;
+        const size = Number.isFinite(d.size) && Number(d.size) > 0 ? Math.trunc(Number(d.size)) : null;
+        meta.set(id, { depends_on: dependsOn, priority, size });
+    }
+    return meta;
+}
+/**
+ * CostOfDelay = 5·regression + 3·blocking + 2·open_criteria + priority (all
+ * integer). Absent fields default to 0.
+ *
+ * @param {{ regressionFlag?: number, blockingCount?: number, openCriteria?: number, priority?: number }} args
+ * @returns {number}
+ */
+export function computeCostOfDelay({ regressionFlag = 0, blockingCount = 0, openCriteria = 0, priority = 0, } = {}) {
+    return (W_REGRESS * (regressionFlag ? 1 : 0) +
+        W_BLOCK * blockingCount +
+        W_VALUE * openCriteria +
+        priority);
+}
+/**
+ * JobSize = declared_size when positive, else the open-criteria count floored at
+ * 1 (never 0 — a criteria-less, size-less milestone is the smallest job = 1, so
+ * WSJF never divides by zero). ID-M5-01.
+ *
+ * @param {{ declaredSize?: number | null, openCriteria?: number }} args
+ * @returns {number}
+ */
+export function computeJobSize({ declaredSize = null, openCriteria = 0 } = {}) {
+    if (Number.isFinite(declaredSize) && Number(declaredSize) > 0)
+        return Math.trunc(Number(declaredSize));
+    return Math.max(openCriteria, 1);
+}
+/**
+ * WSJF = CostOfDelay / JobSize. JobSize is guaranteed ≥ 1 (computeJobSize) so
+ * this never divides by zero.
+ *
+ * @param {number} costOfDelay
+ * @param {number} jobSize
+ * @returns {number}
+ */
+export function computeWsjf(costOfDelay, jobSize) {
+    return costOfDelay / (jobSize > 0 ? jobSize : 1);
+}
+/**
+ * True iff milestone `milestoneId` has an UNRESOLVED M4 verification-TTL
+ * regression — it appears in `listRegressions` AND its latest recorded
+ * `produce.ttl.reverified` result is not `pass` (ID-M5-07). A subsequent
+ * `--result pass` re-verify resolves it (latest result becomes `pass`).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {string} milestoneId
+ * @returns {boolean}
+ */
+export function hasUnresolvedRegression(projectDir, runId, milestoneId) {
+    const regressed = listRegressions(projectDir, runId).some((r) => r.milestone_id === milestoneId);
+    if (!regressed)
+        return false;
+    const reverifies = readProduceRunEventsMatching(projectDir, runId, (op) => op === 'produce.ttl.reverified');
+    let latestResult = null;
+    for (const e of reverifies) {
+        const d = e.data || {};
+        if (d.milestone_id === milestoneId && typeof d.result === 'string')
+            latestResult = d.result;
+    }
+    return latestResult !== 'pass';
+}
+/**
+ * A ranked ready-queue entry with its WSJF terms exposed.
+ *
+ * @typedef {Object} ScheduleEntry
+ * @property {string} milestone_id
+ * @property {string} title
+ * @property {string} status
+ * @property {number} wsjf
+ * @property {number} cost_of_delay
+ * @property {number} job_size
+ * @property {number} open_criteria
+ * @property {number} blocking_count
+ * @property {number} priority
+ * @property {boolean} regressed
+ */
+/**
+ * The pure schedule combiner (ID-M5-02). Folds the existing projections + the
+ * meta-fold + regressions into a WSJF-ranked `ready_queue`, a `blocked` list
+ * (with `blocked_by` = the not-done deps), the `in_progress` accounting, and a
+ * WIP-limited `pick` of the top `wip_available` ready milestones. Emits NO
+ * event and mutates no module (a pure read).
+ *
+ * Ready-set membership: a `planned` milestone is READY iff every `depends_on`
+ * id resolves to a roadmap milestone with status `done` (an unknown dep fails
+ * closed = unmet); otherwise it goes to `blocked`. A `done` milestone with an
+ * unresolved M4 regression re-enters the ready set tagged regressed:true.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ wipLimit?: number }} [opts]
+ * @returns {{
+ *   run_id: string,
+ *   wip_limit: number,
+ *   wip_in_use: number,
+ *   wip_available: number,
+ *   ready_queue: ScheduleEntry[],
+ *   blocked: Array<{ milestone_id: string, title: string, blocked_by: string[] }>,
+ *   in_progress: Array<{ milestone_id: string, title: string }>,
+ *   pick: ScheduleEntry[],
+ *   reason: string,
+ *   cycle: string[] | null,
+ * }}
+ */
+export function computeSchedule(projectDir, runId, { wipLimit = 1 } = {}) {
+    const roadmap = projectRoadmap(projectDir, runId);
+    const ledger = projectLedger(projectDir, runId);
+    const meta = readMilestoneMeta(projectDir, runId);
+    // M3 open acceptance criteria per milestone.
+    const openByMilestone = new Map();
+    for (const c of ledger.criteria) {
+        if (c.status === 'open' && typeof c.milestone_id === 'string') {
+            openByMilestone.set(c.milestone_id, (openByMilestone.get(c.milestone_id) || 0) + 1);
+        }
+    }
+    // blocking_count(m) = # of milestones whose depends_on includes m.
+    const blockingCount = new Map();
+    for (const m of roadmap.milestones) {
+        const dm = meta.get(m.id);
+        for (const dep of dm ? dm.depends_on : []) {
+            blockingCount.set(dep, (blockingCount.get(dep) || 0) + 1);
+        }
+    }
+    const statusById = new Map(roadmap.milestones.map((m) => [m.id, m.status]));
+    const firstSeenOrder = new Map(roadmap.milestones.map((m, i) => [m.id, i]));
+    const inProgress = roadmap.milestones
+        .filter((m) => m.status === 'in_progress')
+        .map((m) => ({ milestone_id: m.id, title: m.title }));
+    const wipInUse = inProgress.length;
+    const wipAvailable = Math.max(0, wipLimit - wipInUse);
+    /** Build a ranked ready-queue entry with its WSJF terms exposed. */
+    const buildEntry = (m, regressed) => {
+        const dm = meta.get(m.id) || { depends_on: [], priority: 0, size: null };
+        const openCriteria = openByMilestone.get(m.id) || 0;
+        const blocking = blockingCount.get(m.id) || 0;
+        const costOfDelay = computeCostOfDelay({
+            regressionFlag: regressed ? 1 : 0,
+            blockingCount: blocking,
+            openCriteria,
+            priority: dm.priority,
+        });
+        const jobSize = computeJobSize({ declaredSize: dm.size, openCriteria });
+        return {
+            milestone_id: m.id,
+            title: m.title,
+            status: m.status,
+            wsjf: computeWsjf(costOfDelay, jobSize),
+            cost_of_delay: costOfDelay,
+            job_size: jobSize,
+            open_criteria: openCriteria,
+            blocking_count: blocking,
+            priority: dm.priority,
+            regressed,
+        };
+    };
+    // Ready set = { planned with all deps done } ∪ { done with an unresolved M4
+    // regression } (ID-M5-07). A regressed `done` milestone re-enters ready_queue
+    // tagged regressed:true; its regression_flag gives it the W_REGRESS=5 CoD
+    // weight, so it ranks toward the top and competes for a WIP slot — the loop
+    // defends what it shipped. WIP still counts roadmap `in_progress` ONLY (a
+    // regressed done milestone is a candidate, not counted as in_progress).
+    const readyQueue = [];
+    const blocked = [];
+    for (const m of roadmap.milestones) {
+        if (m.status === 'planned') {
+            const dm = meta.get(m.id) || { depends_on: [], priority: 0, size: null };
+            // An unknown dep fails closed = unmet (ID-M5-04).
+            const notDone = dm.depends_on.filter((dep) => statusById.get(dep) !== 'done');
+            if (notDone.length === 0) {
+                readyQueue.push(buildEntry(m, false));
+            }
+            else {
+                blocked.push({ milestone_id: m.id, title: m.title, blocked_by: notDone });
+            }
+        }
+        else if (m.status === 'done' && hasUnresolvedRegression(projectDir, runId, m.id)) {
+            readyQueue.push(buildEntry(m, true));
+        }
+    }
+    sortReadyQueue(readyQueue, firstSeenOrder);
+    const pick = readyQueue.slice(0, wipAvailable);
+    // A dependency cycle among not-done milestones means none can EVER become
+    // ready — surface it as a diagnostic rather than a misleading silent idle
+    // (ID-M5-04). The cyclic milestones simply never enter ready_queue.
+    const cycle = detectDependencyCycle(roadmap, meta);
+    let reason;
+    if (wipAvailable === 0)
+        reason = 'wip_saturated';
+    else if (readyQueue.length === 0)
+        reason = cycle ? 'dependency_cycle_detected' : 'no_ready_milestones';
+    else
+        reason = 'scheduled';
+    return {
+        run_id: runId,
+        wip_limit: wipLimit,
+        wip_in_use: wipInUse,
+        wip_available: wipAvailable,
+        ready_queue: readyQueue,
+        blocked,
+        in_progress: inProgress,
+        pick,
+        reason,
+        cycle,
+    };
+}
+/**
+ * Minimal inline DFS over the NOT-DONE dependency sub-graph (ID-M5-04). An edge
+ * m → dep exists when m depends on dep AND dep is itself a not-done roadmap
+ * milestone (a `done` dep is satisfied; an UNKNOWN dep is a leaf — it can't form
+ * a cycle). Returns the offending cycle's milestone ids (the recursion-stack
+ * slice from the re-entered gray node), or `null` when the sub-graph is acyclic.
+ * Deterministic — iterates in roadmap first-seen order.
+ *
+ * @param {{ milestones: Array<{ id: string, status: string }> }} roadmap
+ * @param {Map<string, { depends_on: string[] }>} meta
+ * @returns {string[] | null}
+ */
+function detectDependencyCycle(roadmap, meta) {
+    const nodes = roadmap.milestones.filter((m) => m.status !== 'done').map((m) => m.id);
+    const nodeSet = new Set(nodes);
+    const depsOf = (id) => (meta.get(id)?.depends_on ?? []).filter((dep) => nodeSet.has(dep));
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map(nodes.map((n) => [n, WHITE]));
+    const stack = [];
+    let found = null;
+    const visit = (n) => {
+        if (found)
+            return;
+        color.set(n, GRAY);
+        stack.push(n);
+        for (const dep of depsOf(n)) {
+            if (found)
+                return;
+            const c = color.get(dep);
+            if (c === GRAY) {
+                found = stack.slice(stack.indexOf(dep));
+                return;
+            }
+            if (c === WHITE)
+                visit(dep);
+        }
+        stack.pop();
+        color.set(n, BLACK);
+    };
+    for (const n of nodes) {
+        if (found)
+            break;
+        if (color.get(n) === WHITE)
+            visit(n);
+    }
+    return found;
+}
+/**
+ * Sort a ready-queue in place: WSJF descending → roadmap first-seen order →
+ * milestone_id lexicographic. A total, stable order so two folds of the same
+ * log are byte-identical (ID-M5-01 tie-break).
+ *
+ * @param {Array<{ wsjf: number, milestone_id: string }>} queue
+ * @param {Map<string, number>} firstSeenOrder
+ */
+function sortReadyQueue(queue, firstSeenOrder) {
+    queue.sort((a, b) => {
+        if (b.wsjf !== a.wsjf)
+            return b.wsjf - a.wsjf;
+        const ao = firstSeenOrder.get(a.milestone_id) ?? 0;
+        const bo = firstSeenOrder.get(b.milestone_id) ?? 0;
+        if (ao !== bo)
+            return ao - bo;
+        if (a.milestone_id < b.milestone_id)
+            return -1;
+        if (a.milestone_id > b.milestone_id)
+            return 1;
+        return 0;
+    });
+}
+//# sourceMappingURL=scheduler.mjs.map

package/dist/cli/produce/scheduler.mjs.map

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

package/dist/cli/produce/setpoint.d.mts

@@ -0,0 +1,52 @@
+/**
+ * sha256 of the canonical JSON of the setpoint's immutable core.
+ *
+ * @param {{ run_id: string, outcome: string, frozen_at: string }} core
+ * @returns {string}
+ */
+export function computeSetpointHash(core: {
+    run_id: string;
+    outcome: string;
+    frozen_at: string;
+}): string;
+/**
+ * The setpoint.json path for a given run dir.
+ * @param {string} runDir
+ * @returns {string}
+ */
+export function setpointPathFor(runDir: string): string;
+/**
+ * Exclusive-create write of the setpoint. Uses `openSync(path, 'wx')` on the
+ * FINAL path (NOT a tmp+rename) so a SECOND write throws EEXIST — the setpoint
+ * is immutable. Any attempt to overwrite an existing setpoint throws.
+ *
+ * @param {string} setpointPath
+ * @param {object} setpoint
+ */
+export function writeSetpointExclusive(setpointPath: string, setpoint: object): void;
+/**
+ * Read + parse the frozen setpoint for a run dir. Returns null when absent or
+ * malformed (never throws).
+ *
+ * @param {string} runDir
+ * @returns {object | null}
+ */
+export function readSetpoint(runDir: string): object | null;
+/**
+ * Freeze the setpoint for a run, idempotently. If already frozen, returns the
+ * byte-identical stored setpoint with `reused: true`. Otherwise writes it once
+ * via exclusive create and returns `reused: false`.
+ *
+ * @param {string} runDir
+ * @param {{ run_id: string, outcome: string }} args
+ * @param {Date} [now]
+ * @returns {{ reused: boolean, setpoint: object }}
+ */
+export function freezeSetpoint(runDir: string, { run_id, outcome }: {
+    run_id: string;
+    outcome: string;
+}, now?: Date): {
+    reused: boolean;
+    setpoint: object;
+};
+//# sourceMappingURL=setpoint.d.mts.map

package/dist/cli/produce/setpoint.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setpoint.d.mts","sourceRoot":"","sources":["../../../src/cli/produce/setpoint.mjs"],"names":[],"mappings":"AAoCA;;;;;GAKG;AACH,0CAHW;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACpD,MAAM,CAIlB;AAED;;;;GAIG;AACH,wCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;GAOG;AACH,qDAHW,MAAM,YACN,MAAM,QAYhB;AAED;;;;;;GAMG;AACH,qCAHW,MAAM,GACJ,MAAM,GAAG,IAAI,CAUzB;AAED;;;;;;;;;GASG;AACH,uCALW,MAAM,uBACN;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,QACnC,IAAI,GACF;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAqBjD"}

package/dist/cli/produce/setpoint.mjs

@@ -0,0 +1,113 @@
+/**
+ * @internal
+ * produce/setpoint.mjs — the FROZEN acceptance setpoint (M1, ID-02).
+ *
+ * The setpoint is the fixed external reference the parent spar requires
+ * instead of the Showrunner's moving opinion. It is written ONCE via
+ * `openSync(path, 'wx')` (exclusive create) — a second write throws EEXIST, so
+ * the reference cannot drift. `produce start` on a run whose setpoint already
+ * exists is idempotent-reuse: it returns the byte-identical stored setpoint,
+ * NEVER an overwrite.
+ *
+ * File shape: `{ run_id, outcome, frozen_at, setpoint_hash }` where
+ * `setpoint_hash = sha256(canonical JSON of { run_id, outcome, frozen_at })`.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Stable-key-order JSON of the hashable setpoint core. */
+function canonicalSetpointJson(core) {
+    return JSON.stringify({
+        run_id: core.run_id,
+        outcome: core.outcome,
+        frozen_at: core.frozen_at,
+    });
+}
+/**
+ * sha256 of the canonical JSON of the setpoint's immutable core.
+ *
+ * @param {{ run_id: string, outcome: string, frozen_at: string }} core
+ * @returns {string}
+ */
+export function computeSetpointHash(core) {
+    return createHash('sha256').update(canonicalSetpointJson(core)).digest('hex');
+}
+/**
+ * The setpoint.json path for a given run dir.
+ * @param {string} runDir
+ * @returns {string}
+ */
+export function setpointPathFor(runDir) {
+    return join(runDir, 'setpoint.json');
+}
+/**
+ * Exclusive-create write of the setpoint. Uses `openSync(path, 'wx')` on the
+ * FINAL path (NOT a tmp+rename) so a SECOND write throws EEXIST — the setpoint
+ * is immutable. Any attempt to overwrite an existing setpoint throws.
+ *
+ * @param {string} setpointPath
+ * @param {object} setpoint
+ */
+export function writeSetpointExclusive(setpointPath, setpoint) {
+    mkdirSync(dirname(setpointPath), { recursive: true });
+    const payload = `${JSON.stringify(setpoint, null, 2)}\n`;
+    const fd = openSync(setpointPath, 'wx'); // throws EEXIST when already frozen
+    try {
+        writeSync(fd, payload, 0, 'utf-8');
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Read + parse the frozen setpoint for a run dir. Returns null when absent or
+ * malformed (never throws).
+ *
+ * @param {string} runDir
+ * @returns {object | null}
+ */
+export function readSetpoint(runDir) {
+    const p = setpointPathFor(runDir);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Freeze the setpoint for a run, idempotently. If already frozen, returns the
+ * byte-identical stored setpoint with `reused: true`. Otherwise writes it once
+ * via exclusive create and returns `reused: false`.
+ *
+ * @param {string} runDir
+ * @param {{ run_id: string, outcome: string }} args
+ * @param {Date} [now]
+ * @returns {{ reused: boolean, setpoint: object }}
+ */
+export function freezeSetpoint(runDir, { run_id, outcome }, now = new Date()) {
+    const existing = readSetpoint(runDir);
+    if (existing)
+        return { reused: true, setpoint: existing };
+    const frozen_at = now.toISOString();
+    const core = { run_id, outcome, frozen_at };
+    const setpoint = { ...core, setpoint_hash: computeSetpointHash(core) };
+    try {
+        writeSetpointExclusive(setpointPathFor(runDir), setpoint);
+    }
+    catch (e) {
+        // Lost a concurrent race — the winner's file is authoritative; re-read
+        // it byte-identically rather than overwriting (ID-02).
+        if (e && e.code === 'EEXIST') {
+            const winner = readSetpoint(runDir);
+            if (winner)
+                return { reused: true, setpoint: winner };
+        }
+        throw e;
+    }
+    return { reused: false, setpoint };
+}
+//# sourceMappingURL=setpoint.mjs.map

package/dist/cli/produce/setpoint.mjs.map

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

package/dist/cli/produce/verification-ttl.d.mts

@@ -0,0 +1,75 @@
+/**
+ * Select a DETERMINISTIC rotating sample of already-`done` milestones STALE
+ * against HEAD (ID-M4-03 / AC7). REUSES `selectSweepSample` for the rotation
+ * order (fewest/oldest last-probe-run first), then annotates each candidate with
+ * staleness against `headSha` and FILTERS OUT the FRESH ones (last re-verified
+ * against the current HEAD). Returns the first `sample` STALE candidates. An
+ * absent HEAD sha fails closed (nothing selected).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ headSha: string, sample?: number }} args
+ * @returns {{ run_id: string, head_sha: string | null, sample_size: number,
+ *   selected: Array<{ milestone_id: string, title: string, last_reverify_head_sha: string | null, last_reverify_at: string | null, stale: boolean }> }}
+ */
+export function selectTtlReverifySample(projectDir: string, runId: string, { headSha, sample }?: {
+    headSha: string;
+    sample?: number;
+}): {
+    run_id: string;
+    head_sha: string | null;
+    sample_size: number;
+    selected: Array<{
+        milestone_id: string;
+        title: string;
+        last_reverify_head_sha: string | null;
+        last_reverify_at: string | null;
+        stale: boolean;
+    }>;
+};
+/**
+ * Record a scheduled TTL re-verify RUN against HEAD (ID-M4-03). REUSES the M2
+ * cross-family guard (refuses a same-family re-verify, or when no implementer
+ * family is recorded). Appends `produce.ttl.reverified {run_id, milestone_id,
+ * head_sha, result}`; on `result === 'fail'` ALSO appends
+ * `produce.ttl.regression_detected` AND fires the FORWARD compensator via
+ * saga.mjs::compensatePhase({phase:'verify', reason:'ttl_regression@<sha>'}) — a
+ * revert-branch + reopen + re-plan, NEVER a merged-PR rollback. A `pass`
+ * refreshes verification against the new HEAD and logs no regression.
+ *
+ * @param {string} projectDir
+ * @param {{ runId: string, milestoneId: string, result: string, probeFamily: string, headSha: string }} args
+ * @returns {{ ok: true, result: string, probe_family: string, head_sha: string, regression: boolean, compensator: object | null }
+ *   | { ok: false, reason: string }}
+ */
+export function recordTtlReverify(projectDir: string, { runId, milestoneId, result, probeFamily, headSha }: {
+    runId: string;
+    milestoneId: string;
+    result: string;
+    probeFamily: string;
+    headSha: string;
+}): {
+    ok: true;
+    result: string;
+    probe_family: string;
+    head_sha: string;
+    regression: boolean;
+    compensator: object | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read-only fold of the run's `produce.ttl.regression_detected` events (for saga
+ * status / canary context). Chronological order.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {Array<{ milestone_id: string | null, head_sha: string | null, t: string | null }>}
+ */
+export function listRegressions(projectDir: string, runId: string): Array<{
+    milestone_id: string | null;
+    head_sha: string | null;
+    t: string | null;
+}>;
+//# sourceMappingURL=verification-ttl.d.mts.map

package/dist/cli/produce/verification-ttl.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-ttl.d.mts","sourceRoot":"","sources":["../../../src/cli/produce/verification-ttl.mjs"],"names":[],"mappings":"AAiEA;;;;;;;;;;;;;GAaG;AACH,oDANW,MAAM,SACN,MAAM,wBACN;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IACvE,QAAQ,EAAE,KAAK,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,CAiCtJ;AAED;;;;;;;;;;;;;;GAcG;AACH,8CALW,MAAM,wDACN;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1F;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC3H;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4CnC;AAED;;;;;;;GAOG;AACH,4CAJW,MAAM,SACN,MAAM,GACJ,KAAK,CAAC;IAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAa7F"}