@aperant/framework 0.17.0 → 0.20.0

package/src/cli/produce/scheduler.mjs

@@ -0,0 +1,423 @@
+/**
+ * @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
+	})
+}

package/src/cli/produce/setpoint.mjs

@@ -0,0 +1,122 @@
+/**
+ * @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 }
+}