@aperant/framework 0.17.0 → 0.19.0

package/src/cli/produce/ledger.mjs

@@ -0,0 +1,284 @@
+/**
+ * @internal
+ * produce/ledger.mjs — the acceptance-criteria ledger + Lyapunov math (M3).
+ *
+ * V (the Lyapunov function) = open acceptance criteria = declared − closed,
+ * folded from the append-only log on every read (ID-M3-01 / ID-M3-02). Each
+ * criterion is a `produce.criteria.declared` event bound to a milestone; it
+ * closes via `produce.criteria.closed`. `produce.scope.changed` is the ONLY
+ * sanctioned way V may rise after the run has begun closing criteria (ID-M3-04).
+ *
+ * This module is a SEPARATE fold parallel to `projection.mjs` — the roadmap
+ * projection still folds `produce.roadmap.*` ONLY, so criteria/scope events
+ * never enter the roadmap the Showrunner re-reads (the M1/M2 blindness invariant
+ * is preserved). It reads ONLY the event log through `events.mjs` (no `node:`
+ * beyond what events.mjs already uses) and holds NO model id (it is pure math).
+ */
+
+import { appendProduceEvent, readProduceRunEventsMatching } from './events.mjs'
+import { slugFromOutcome } from './run-id.mjs'
+
+/** The op-match for the criteria + scope ledger fold (never `produce.roadmap.*`). */
+function isLedgerOp(op) {
+	return op.startsWith('produce.criteria.') || op === 'produce.scope.changed'
+}
+
+/**
+ * Fold the run's acceptance-criteria ledger from the append-only log. A
+ * `produce.criteria.declared` seeds an OPEN criterion (in first-seen order); a
+ * `produce.criteria.closed` advances it to `closed`; `produce.scope.changed` is
+ * recorded on the scope-change trail. Deterministic — two folds of the same log
+ * yield the identical ledger; `updated_at` is the last folded event's timestamp.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   criteria: Array<{ criterion_id: string, milestone_id: string | null, text: string, status: 'open' | 'closed' }>,
+ *   open_count: number,
+ *   closed_count: number,
+ *   scope_changes: Array<{ reason: string, milestone_id: string | null, t: string | null }>,
+ *   updated_at: string | null,
+ * }}
+ */
+export function projectLedger(projectDir, runId) {
+	const events = readProduceRunEventsMatching(projectDir, runId, isLedgerOp)
+	const byId = new Map()
+	const order = []
+	const scopeChanges = []
+	let updatedAt = null
+
+	for (const e of events) {
+		const d = e.data || {}
+		if (e.op === 'produce.criteria.declared') {
+			const cid = typeof d.criterion_id === 'string' ? d.criterion_id : null
+			if (cid && !byId.has(cid)) {
+				byId.set(cid, {
+					criterion_id: cid,
+					milestone_id: typeof d.milestone_id === 'string' ? d.milestone_id : null,
+					text: typeof d.text === 'string' ? d.text : '',
+					status: 'open',
+				})
+				order.push(cid)
+			}
+		} else if (e.op === 'produce.criteria.closed') {
+			const cid = typeof d.criterion_id === 'string' ? d.criterion_id : null
+			if (cid && byId.has(cid)) byId.get(cid).status = 'closed'
+		} else if (e.op === 'produce.scope.changed') {
+			scopeChanges.push({
+				reason: typeof d.reason === 'string' ? d.reason : '',
+				milestone_id: typeof d.milestone_id === 'string' ? d.milestone_id : null,
+				t: typeof e.t === 'string' ? e.t : null,
+			})
+		}
+		if (typeof e.t === 'string') updatedAt = e.t
+	}
+
+	const criteria = order.map((cid) => byId.get(cid))
+	return {
+		run_id: runId,
+		criteria,
+		open_count: criteria.filter((c) => c.status === 'open').length,
+		closed_count: criteria.filter((c) => c.status === 'closed').length,
+		scope_changes: scopeChanges,
+		updated_at: updatedAt,
+	}
+}
+
+/**
+ * V = open acceptance criteria = declared − closed, folded from the log.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {number}
+ */
+export function computeOpenCriteria(projectDir, runId) {
+	return projectLedger(projectDir, runId).open_count
+}
+
+/**
+ * The write-time anti-windup guard (ID-M3-03). `declare-criteria` raises V; it is
+ * REJECTED when the run is IN DESCENT (≥1 `produce.criteria.closed` already
+ * logged) AND no scope-change is supplied. Before descent, declaration is FREE
+ * (the baseline scope-definition window). This is the ONLY hard Lyapunov
+ * enforcement and it is fail-closed.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ hasScopeChange?: boolean }} [opts]
+ * @returns {{ allowed: boolean, reason: string, in_descent: boolean }}
+ */
+export function evaluateDeclareGuard(projectDir, runId, { hasScopeChange = false } = {}) {
+	const closes = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) => op === 'produce.criteria.closed',
+	)
+	const inDescent = closes.length > 0
+	const allowed = !inDescent || !!hasScopeChange
+	let reason
+	if (!allowed) reason = 'in_descent_no_scope_change'
+	else if (!inDescent) reason = 'baseline_window'
+	else reason = 'scope_change'
+	return { allowed, reason, in_descent: inDescent }
+}
+
+/**
+ * Compute the monotone-progress report (ID-M3-02 / AC6). Folds ALL of
+ * `produce.criteria.*` + `produce.scope.changed` +
+ * `produce.roadmap.milestone_status_changed` in append order, maintaining the
+ * running V. Every `milestone_status_changed{status:'done'}` is a checkpoint: it
+ * captures `v_before`, then consumes the contiguous run of `criteria.closed`
+ * events that ship triggered (appended immediately after the done event) to
+ * capture `v_after`. `delta = v_after − v_before` (≤ 0). The series is STRICTLY
+ * DECREASING iff every ship checkpoint had `delta < 0`; a flat ship (delta === 0)
+ * is a soft STALL, not a hard violation.
+ *
+ * Read-time defense (ID-M3-03): a `produce.criteria.declared` that raised V
+ * AFTER descent WITHOUT an accompanying (immediately-preceding)
+ * `produce.scope.changed` is a HARD `lyapunov_violation`. `progress` FLAGS — it
+ * never rejects (the rejection is the write-time guard).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   v_open_now: number,
+ *   v_series: Array<{ milestone_id: string | null, v_before: number, v_after: number, delta: number, decreased: boolean }>,
+ *   strictly_decreasing: boolean,
+ *   lyapunov_ok: boolean,
+ *   lyapunov_violations: Array<{ criterion_id: string | null, milestone_id: string | null, reason: string, t: string | null }>,
+ *   scope_changes: Array<{ reason: string, milestone_id: string | null, t: string | null }>,
+ * }}
+ */
+export function computeProgress(projectDir, runId) {
+	const events = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) =>
+			op.startsWith('produce.criteria.') ||
+			op === 'produce.scope.changed' ||
+			op === 'produce.roadmap.milestone_status_changed',
+	)
+
+	const status = new Map()
+	let v = 0
+	let inDescent = false
+	const vSeries = []
+	const violations = []
+	const scopeChanges = []
+
+	/** Apply a `criteria.closed` payload to V (idempotent; sets inDescent). */
+	const applyClose = (d) => {
+		const cid = typeof d.criterion_id === 'string' ? d.criterion_id : null
+		if (cid && status.get(cid) === 'open') {
+			status.set(cid, 'closed')
+			v -= 1
+		} else if (cid && !status.has(cid)) {
+			// Close of a never-declared criterion — record the state, no V change.
+			status.set(cid, 'closed')
+		}
+		inDescent = true
+	}
+
+	for (let i = 0; i < events.length; i++) {
+		const e = events[i]
+		const d = e.data || {}
+
+		if (e.op === 'produce.criteria.declared') {
+			if (inDescent) {
+				const prev = i > 0 ? events[i - 1] : null
+				const accompanied = !!prev && prev.op === 'produce.scope.changed'
+				if (!accompanied) {
+					violations.push({
+						criterion_id: typeof d.criterion_id === 'string' ? d.criterion_id : null,
+						milestone_id: typeof d.milestone_id === 'string' ? d.milestone_id : null,
+						reason: 'declared_after_descent_without_scope_change',
+						t: typeof e.t === 'string' ? e.t : null,
+					})
+				}
+			}
+			const cid = typeof d.criterion_id === 'string' ? d.criterion_id : null
+			if (cid && !status.has(cid)) {
+				status.set(cid, 'open')
+				v += 1
+			}
+		} else if (e.op === 'produce.criteria.closed') {
+			applyClose(d)
+		} else if (e.op === 'produce.scope.changed') {
+			scopeChanges.push({
+				reason: typeof d.reason === 'string' ? d.reason : '',
+				milestone_id: typeof d.milestone_id === 'string' ? d.milestone_id : null,
+				t: typeof e.t === 'string' ? e.t : null,
+			})
+		} else if (e.op === 'produce.roadmap.milestone_status_changed' && d.status === 'done') {
+			const vBefore = v
+			// Consume the contiguous run of criteria.closed this ship triggered
+			// (the real flow appends them immediately after the done event).
+			let j = i + 1
+			while (j < events.length && events[j].op === 'produce.criteria.closed') {
+				applyClose(events[j].data || {})
+				j++
+			}
+			i = j - 1
+			const vAfter = v
+			const delta = vAfter - vBefore
+			vSeries.push({
+				milestone_id: typeof d.milestone_id === 'string' ? d.milestone_id : null,
+				v_before: vBefore,
+				v_after: vAfter,
+				delta,
+				decreased: delta < 0,
+			})
+		}
+	}
+
+	return {
+		run_id: runId,
+		v_open_now: v,
+		v_series: vSeries,
+		strictly_decreasing: vSeries.every((s) => s.delta < 0),
+		lyapunov_ok: violations.length === 0,
+		lyapunov_violations: violations,
+		scope_changes: scopeChanges,
+	}
+}
+
+/**
+ * Close a shipped milestone's still-open acceptance criteria — the CONSEQUENCE
+ * of a milestone flipping to `done` (ID-M3-05, wired additively in
+ * `cmdSetMilestoneDone`). Folds the ledger, finds the milestone's OPEN criteria,
+ * and appends one `produce.criteria.closed` per criterion so V strictly
+ * decreases. Idempotent — an already-closed (or criteria-less) milestone appends
+ * nothing (`closed_count: 0`), so a criteria-less ship is byte-identical to M2.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {string} milestoneId
+ * @returns {{ closed_count: number, criterion_ids: string[] }}
+ */
+export function closeCriteriaForShippedMilestone(projectDir, runId, milestoneId) {
+	const ledger = projectLedger(projectDir, runId)
+	const open = ledger.criteria.filter((c) => c.milestone_id === milestoneId && c.status === 'open')
+	const criterionIds = []
+	for (const c of open) {
+		appendProduceEvent(projectDir, 'produce.criteria.closed', {
+			run_id: runId,
+			milestone_id: milestoneId,
+			criterion_id: c.criterion_id,
+		})
+		criterionIds.push(c.criterion_id)
+	}
+	return { closed_count: criterionIds.length, criterion_ids: criterionIds }
+}
+
+/**
+ * Mint a criterion id: `<slug-of-text>-<rand>`. Reuses `slugFromOutcome` and a
+ * short random suffix so two criteria minted from the same text never collide.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function mintCriterionId(text) {
+	return `${slugFromOutcome(text)}-${Math.random().toString(36).slice(2, 8)}`
+}

package/src/cli/produce/probe-family.mjs

@@ -0,0 +1,168 @@
+/**
+ * @internal
+ * produce/probe-family.mjs — resolve a probe/oracle provider family DISJOINT
+ * from the implementer's, reusing the apt-spar cross-family mechanism (M2,
+ * ID-M2-01).
+ *
+ * The framework already selects + dispatches a different provider family in
+ * `apt:spar`: `host-detect` returns the current family, a partner-map picks a
+ * different one, and `spar-resolve-partner` resolves the partner's model LIVE
+ * from the user's own CLI config with ZERO baked default. M2 does NOT invent a
+ * second cross-family path — this module consumes the SAME `resolveCodexSparModel`
+ * primitive + the same partner-map shape and adds exactly ONE new rule: the
+ * resolved probe/oracle family must be DISJOINT from the *implementer* family
+ * (not merely "≠ host").
+ *
+ * Provider is an OUTPUT of selection; Aperant NEVER holds a model id (CLAUDE.md
+ * resolver rule / ID-M2-07). For codex the live model comes from
+ * `~/.codex/config.toml`; claude / gemini self-resolve (`model: null`). A
+ * setup where no disjoint family exists (host = implementer = only CLI) returns
+ * `available: false` fail-closed — a single-family setup cannot satisfy the
+ * cross-family rule by design.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolveCodexSparModel } from '../host/codex-config.mjs'
+
+/**
+ * The provider families M2 selects across — the same three apt:spar supports.
+ * Ordered for a deterministic tiebreak when the partner-map default is not in
+ * the available pool.
+ */
+export const KNOWN_FAMILIES = ['claude', 'codex', 'gemini']
+
+/**
+ * The apt-spar §3 partner-map shape: each family's natural cross-family partner.
+ * Consulted as a PREFERENCE only — the disjoint + available + non-host rules
+ * decide the final pick; this just orders ties the way spar does.
+ */
+const PARTNER_MAP = {
+	claude: 'codex',
+	codex: 'claude',
+	gemini: 'codex',
+}
+
+/**
+ * Normalize a provider/CLI family alias to one of KNOWN_FAMILIES. Returns null
+ * for an unrecognized family so it is excluded from selection (fail-closed).
+ *
+ * @param {unknown} family
+ * @returns {string | null}
+ */
+export function normalizeFamily(family) {
+	if (typeof family !== 'string') return null
+	const f = family.trim().toLowerCase()
+	if (f === 'claude' || f === 'claude-code' || f === 'anthropic') return 'claude'
+	if (f === 'codex' || f === 'openai' || f === 'gpt') return 'codex'
+	if (f === 'gemini' || f === 'google') return 'gemini'
+	return null
+}
+
+/**
+ * Pick the probe/oracle family: disjoint from the implementer (the ONE new
+ * rule), preferring a family that is ALSO not the host (a genuine third party),
+ * then honoring the apt-spar partner-map default, then a deterministic order.
+ *
+ * @param {string} implementerFamily — normalized implementer family.
+ * @param {string | null} hostFamily — normalized host family (or null).
+ * @param {string[]} normalizedAvailable — normalized available families.
+ * @returns {{ family: string | null, reason: string | null }}
+ */
+function pickProbeFamily(implementerFamily, hostFamily, normalizedAvailable) {
+	// The ONE new constraint over apt-spar: DISJOINT from the implementer.
+	const disjoint = normalizedAvailable.filter((f) => f !== implementerFamily)
+	if (disjoint.length === 0) return { family: null, reason: 'no_disjoint_family' }
+	// Prefer a disjoint family that is ALSO not the host — a genuine third-party
+	// reviewer. Fall back to a disjoint-but-host family only if that is all
+	// that's available (still satisfies the cross-family rule, which is about the
+	// implementer, not the host).
+	const nonHost = disjoint.filter((f) => f !== hostFamily)
+	const pool = nonHost.length > 0 ? nonHost : disjoint
+	// Honor the partner-map default when it is in the pool (apt-spar §3 shape).
+	const preferred = PARTNER_MAP[implementerFamily]
+	if (preferred && pool.includes(preferred)) return { family: preferred, reason: null }
+	// Deterministic tiebreak: first in KNOWN_FAMILIES order present in the pool.
+	const ordered = KNOWN_FAMILIES.filter((f) => pool.includes(f))
+	return { family: ordered[0] ?? pool[0], reason: null }
+}
+
+/**
+ * Resolve the probe/oracle family + LIVE model for a produce run.
+ *
+ * @param {{
+ *   implementerFamily: string,
+ *   hostFamily?: string | null,
+ *   availableFamilies?: string[],
+ *   codexDeps?: { home: string, existsSync: (p: string) => boolean, readFileSync: (p: string, enc: string) => string },
+ * }} args
+ * @returns {{
+ *   available: boolean,
+ *   probe_family: string | null,
+ *   transport_hint: { prefer_self_resolving: boolean, recommended_walk: string[] } | null,
+ *   model: string | null,
+ *   source: string | null,
+ *   reason: string | null,
+ * }}
+ */
+export function resolveProbeFamily({
+	implementerFamily,
+	hostFamily = null,
+	availableFamilies = KNOWN_FAMILIES,
+	codexDeps,
+} = {}) {
+	const implementer = normalizeFamily(implementerFamily)
+	if (!implementer) {
+		return {
+			available: false,
+			probe_family: null,
+			transport_hint: null,
+			model: null,
+			source: null,
+			reason: 'unknown_implementer_family',
+		}
+	}
+
+	const host = normalizeFamily(hostFamily)
+	const normalizedAvailable = [...new Set(availableFamilies.map(normalizeFamily).filter(Boolean))]
+
+	const { family, reason } = pickProbeFamily(implementer, host, normalizedAvailable)
+	if (!family) {
+		return {
+			available: false,
+			probe_family: null,
+			transport_hint: null,
+			model: null,
+			source: null,
+			reason: reason ?? 'no_disjoint_family',
+		}
+	}
+
+	// Resolve the model LIVE via the reused spar primitive (provider-is-output,
+	// zero baked id). codex reads ~/.codex/config.toml; claude/gemini self-resolve.
+	if (family === 'codex') {
+		const deps = codexDeps ?? { home: homedir(), existsSync, readFileSync }
+		const res = resolveCodexSparModel(deps)
+		return {
+			available: true,
+			probe_family: 'codex',
+			transport_hint: { prefer_self_resolving: true, recommended_walk: ['plugin', 'cli', 'mcp'] },
+			model: res.model,
+			source: res.source,
+			// A codex model that fails to resolve from config does NOT make the
+			// probe family unavailable — the self-resolving plugin/CLI rungs still
+			// run without a named model. Surface the model-resolution reason.
+			reason: res.reason,
+		}
+	}
+
+	// claude / gemini MCP rungs take only {prompt} — no model, no staleness vector.
+	return {
+		available: true,
+		probe_family: family,
+		transport_hint: { prefer_self_resolving: false, recommended_walk: ['mcp', 'plugin', 'cli'] },
+		model: null,
+		source: null,
+		reason: 'self_resolving',
+	}
+}

package/src/cli/produce/projection.mjs

@@ -0,0 +1,105 @@
+/**
+ * @internal
+ * produce/projection.mjs — event-sourced roadmap projection (M1, ID-01).
+ *
+ * The roadmap is DERIVED: `projectRoadmap` folds the run's `produce.roadmap.*`
+ * events into `{ run_id, milestones:[{id,title,status}], updated_at }` on every
+ * call. It is NEVER read as the source of truth — a persisted `roadmap.json`
+ * cache MAY be written for convenience but is always regenerable from the log,
+ * so the shared-mutable-blob lost-update bug is structurally impossible.
+ *
+ * `writeProjectionCache` is a SINGLE-WRITER-PER-RECORD write under withFileLock
+ * (a torn cache is recoverable by re-folding). The event log is the authority;
+ * the cache is disposable.
+ */
+
+import { join } from 'node:path'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { atomicWriteJson } from '../util/io.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
+import { readProduceEventsForRun } from './events.mjs'
+import { resolveRunDir } from './run-id.mjs'
+
+/** M1 milestone lifecycle — `done` is external-oracle-gated (M2, ID-03). */
+const SEED_STATUS = 'planned'
+
+/**
+ * Recompute the roadmap projection for a run by folding its append-only
+ * `produce.roadmap.*` events. `milestone_added` seeds a planned milestone (in
+ * first-seen order); `milestone_status_changed` advances its status. Idempotent
+ * re-adds keep the first seed (never clobber an advanced status). `updated_at`
+ * is derived from the last folded event's timestamp so the projection is
+ * DETERMINISTIC — two folds of the same log yield the identical roadmap.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{ run_id: string, milestones: Array<{ id: string, title: string, status: string }>, updated_at: string | null }}
+ */
+export function projectRoadmap(projectDir, runId) {
+	const events = readProduceEventsForRun(projectDir, runId)
+	const byId = new Map()
+	const order = []
+	let updatedAt = null
+
+	for (const e of events) {
+		const d = e.data || {}
+		const id = typeof d.milestone_id === 'string' ? d.milestone_id : null
+		if (e.op === 'produce.roadmap.milestone_added') {
+			if (id && !byId.has(id)) {
+				byId.set(id, { id, title: typeof d.title === 'string' ? d.title : id, status: SEED_STATUS })
+				order.push(id)
+			}
+		} else if (e.op === 'produce.roadmap.milestone_status_changed') {
+			if (id && byId.has(id) && typeof d.status === 'string') {
+				byId.get(id).status = d.status
+			}
+		}
+		if (typeof e.t === 'string') updatedAt = e.t
+	}
+
+	return {
+		run_id: runId,
+		milestones: order.map((id) => byId.get(id)),
+		updated_at: updatedAt,
+	}
+}
+
+/**
+ * The derived roadmap.json cache path for a run.
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function roadmapCachePath(projectDir, runId) {
+	return join(resolveRunDir(projectDir, runId), 'roadmap.json')
+}
+
+/**
+ * Refresh the derived roadmap.json cache single-writer under withFileLock, and
+ * return the freshly-folded roadmap. Convenience only — the log is the
+ * authority; a corrupt cache is repaired by re-folding (ID-01).
+ *
+ * The fold happens INSIDE the lock (not precomputed then written): the write is
+ * a full idempotent regenerate from the authoritative log, never a
+ * read-modify-write of a shared blob. This guarantees the last writer to
+ * acquire the lock persists the COMPLETE set — a precompute-then-write pattern
+ * could persist a STALE fold if a concurrent O_APPEND landed between the
+ * precompute and the write, silently dropping that milestone from the cache
+ * (parent TD-06 / subtask 4). The event log stays lossless regardless.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{ run_id: string, milestones: Array<{ id: string, title: string, status: string }>, updated_at: string | null }}
+ */
+export function writeProjectionCache(projectDir, runId) {
+	const path = roadmapCachePath(projectDir, runId)
+	return withFileLock(
+		path,
+		() => {
+			const roadmap = projectRoadmap(projectDir, runId)
+			atomicWriteJson(path, roadmap)
+			return roadmap
+		},
+		{ projectRoot: resolveMainRepoRoot(projectDir) },
+	)
+}

package/src/cli/produce/run-id.mjs

@@ -0,0 +1,84 @@
+/**
+ * @internal
+ * produce/run-id.mjs — mint + resolve produce run identifiers and run dirs (M1).
+ *
+ * A produce run is scoped to one frozen acceptance setpoint. Its run-id is a
+ * human-readable slug derived from the outcome plus a short timestamp and a
+ * random suffix (so two `start`s in the same second never collide). The run
+ * dir lives under the SHARED main-repo root at `.aperant/produce/<run-id>/`
+ * (resolveMainRepoRoot) so every worktree agent reads/writes one board
+ * (parent AC8 path / ID-06).
+ */
+
+import { join } from 'node:path'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
+
+/**
+ * Slugify an outcome string into a short kebab identifier. Strips punctuation,
+ * lowercases, keeps the first `maxWords` words. Falls back to 'run' when empty.
+ *
+ * @param {string} outcome
+ * @param {number} [maxWords=6]
+ * @returns {string}
+ */
+export function slugFromOutcome(outcome, maxWords = 6) {
+	const words = String(outcome || '')
+		.toLowerCase()
+		.replace(/[^a-z0-9\s-]/g, ' ')
+		.trim()
+		.split(/\s+/)
+		.filter(Boolean)
+		.slice(0, maxWords)
+	const slug = words.join('-').replace(/-+/g, '-')
+	return slug || 'run'
+}
+
+/**
+ * Mint a fresh run-id: `<slug>-<YYYYMMDD-HHMMSS>-<rand>`. The random suffix
+ * guarantees uniqueness even for identical outcomes minted in the same second.
+ *
+ * @param {string} outcome
+ * @param {Date} [now]
+ * @returns {string}
+ */
+export function mintRunId(outcome, now = new Date()) {
+	const stamp = now
+		.toISOString()
+		.replace(/\.\d+Z$/, '')
+		.replace(/[-:]/g, '')
+		.replace('T', '-')
+	const rand = Math.random().toString(36).slice(2, 6)
+	return `${slugFromOutcome(outcome)}-${stamp}-${rand}`
+}
+
+/**
+ * The `.aperant/produce/` root, resolved to the shared main repo from any cwd.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function resolveProduceRoot(projectDir) {
+	return join(resolveMainRepoRoot(projectDir), '.aperant', 'produce')
+}
+
+/**
+ * The run dir `.aperant/produce/<run-id>/`, resolved to the shared main repo.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {string}
+ */
+export function resolveRunDir(projectDir, runId) {
+	return join(resolveProduceRoot(projectDir), runId)
+}
+
+/**
+ * Repo-relative setpoint path for a run — used as the `setpoint_path` event
+ * field. Forward-slash separated for portability across the event log.
+ *
+ * @param {string} runId
+ * @returns {string}
+ */
+export function relativeSetpointPath(runId) {
+	return ['.aperant', 'produce', runId, 'setpoint.json'].join('/')
+}