@aperant/framework 0.16.0 → 0.19.0

package/src/cli/host/codex-config.mjs

@@ -0,0 +1,165 @@
+/**
+ * host/codex-config.mjs — live codex model resolution for `apt:spar` (Decision B + C).
+ *
+ * Aperant holds ZERO model names. The only source of truth for the codex
+ * partner's model is the user's live `~/.codex/config.toml`, read at invocation
+ * time with NO fallback default — mirroring the app's "Model selection —
+ * resolver-only, provider-is-output, LIVE" rule.
+ *
+ * Two exports:
+ *   - `parseTopLevelCodexModel(tomlText)` — a deterministic top-level TOML
+ *     `model = "<value>"` line parser (ID-04: top-level only; `[profiles.*]`
+ *     sections are inactive without `--profile`, which spar never passes).
+ *   - `resolveCodexSparModel({ home, existsSync, readFileSync })` — reads
+ *     `<home>/.codex/config.toml` LIVE each call and returns a fail-closed
+ *     `{ available, model, source, reason }` envelope. NEVER a baked constant.
+ *
+ * Parser hardening (plan-gate spar refinement #1). The bias rule is
+ * fail-closed: when a value is ambiguous, return `reason: 'unparseable'` rather
+ * than a wrong or truncated model. A too-strict parse that loses the MCP rung
+ * (falling through to the self-resolving plugin/CLI rungs) is acceptable; a
+ * too-loose parse that passes a wrong model is a bug.
+ */
+
+import { join } from 'node:path'
+
+/** Human-facing source label the SKILL + envelope reference. */
+export const CODEX_CONFIG_SOURCE = '~/.codex/config.toml'
+
+/**
+ * @typedef {Object} ParsedCodexModel
+ * @property {string|null} model — the resolved top-level model, or null.
+ * @property {null|'no_model_key'|'unparseable'} reason — null when a model
+ *   resolved; a machine reason otherwise.
+ */
+
+/**
+ * Parse the FIRST top-level `model = "<value>"` assignment from codex
+ * `config.toml` text. Scans line-by-line, stops at the first `[section]`
+ * header (top-level scope ends there), skips comment lines, and resolves the
+ * first top-level `model` key.
+ *
+ * Handles (refinement #1): a leading UTF-8 BOM, an inline `# comment` after the
+ * value, a no-space `model="x"` assignment, single-quoted TOML literal strings,
+ * and commented-out `#model = "x"` keys (skipped). A malformed / unterminated /
+ * escaped-quote value returns `reason: 'unparseable'` — never a truncated
+ * string. The first top-level `model` line is decisive: if it is malformed the
+ * parser returns `unparseable` rather than scanning for a later valid line
+ * (TOML forbids duplicate keys, and a later-line search would be too loose).
+ *
+ * @param {string} tomlText
+ * @returns {ParsedCodexModel}
+ */
+export function parseTopLevelCodexModel(tomlText) {
+	if (typeof tomlText !== 'string') return { model: null, reason: 'unparseable' }
+
+	// Strip a leading UTF-8 BOM so `model = "x"` still resolves.
+	let text = tomlText
+	if (text.charCodeAt(0) === 0xfeff) text = text.slice(1)
+
+	const lines = text.split(/\r?\n/)
+	for (const rawLine of lines) {
+		const line = rawLine.trimStart()
+		// A `[section]` (or `[[array.of.tables]]`) header ends the top-level
+		// scope — stop scanning; a model below this point is profile-scoped.
+		if (line.startsWith('[')) break
+		// Comment lines (incl. a commented-out `#model = "x"`) are skipped.
+		if (line.startsWith('#')) continue
+		// Top-level `model` assignment? The key must be EXACTLY `model` —
+		// `\s*=` rejects `model_provider`, `models`, `mcp_model`, etc.
+		const assign = line.match(/^model\s*=\s*(.*)$/)
+		if (!assign) continue
+		// First top-level model line is decisive (fail-closed on malformed).
+		return parseQuotedValue(assign[1])
+	}
+	return { model: null, reason: 'no_model_key' }
+}
+
+/**
+ * Parse a quoted TOML string value (the RHS of `model =`). Accepts a
+ * double-quoted basic string or a single-quoted literal string, each optionally
+ * followed by whitespace and/or an inline `# comment`. Any other shape
+ * (unquoted, unterminated, escaped, empty, or trailing non-comment junk) is
+ * fail-closed `unparseable`.
+ *
+ * @param {string} value — the text after `model\s*=\s*`.
+ * @returns {ParsedCodexModel}
+ */
+function parseQuotedValue(value) {
+	const first = value[0]
+	if (first === '"') {
+		const m = value.match(/^"([^"\n]*)"(.*)$/)
+		if (!m) return { model: null, reason: 'unparseable' } // unterminated
+		const inner = m[1]
+		// A backslash means TOML escapes are in play — do NOT attempt to
+		// unescape; fail closed rather than risk a wrong/truncated model.
+		if (inner.includes('\\')) return { model: null, reason: 'unparseable' }
+		if (!isOnlyTrailingComment(m[2])) return { model: null, reason: 'unparseable' }
+		if (inner.length === 0) return { model: null, reason: 'unparseable' }
+		return { model: inner, reason: null }
+	}
+	if (first === "'") {
+		// TOML literal strings carry no escapes.
+		const m = value.match(/^'([^'\n]*)'(.*)$/)
+		if (!m) return { model: null, reason: 'unparseable' }
+		const inner = m[1]
+		if (!isOnlyTrailingComment(m[2])) return { model: null, reason: 'unparseable' }
+		if (inner.length === 0) return { model: null, reason: 'unparseable' }
+		return { model: inner, reason: null }
+	}
+	// Unquoted / bare value — codex `model` is always a quoted string; bias
+	// fail-closed so a malformed line never yields a wrong model.
+	return { model: null, reason: 'unparseable' }
+}
+
+/**
+ * The text after a closing quote must be empty, whitespace, or an inline
+ * `# comment`. Anything else is malformed → fail closed.
+ *
+ * @param {string} rest
+ * @returns {boolean}
+ */
+function isOnlyTrailingComment(rest) {
+	const t = rest.trimStart()
+	return t === '' || t.startsWith('#')
+}
+
+/**
+ * @typedef {Object} CodexSparModelResolution
+ * @property {boolean} available — true iff a live top-level model resolved.
+ * @property {string|null} model — the resolved model, or null when unavailable.
+ * @property {string} source — the config source label (`~/.codex/config.toml`).
+ * @property {null|'config_missing'|'no_model_key'|'unparseable'} reason
+ */
+
+/**
+ * Read `<home>/.codex/config.toml` LIVE and resolve the top-level model.
+ * Fail-closed (Decision C / ID-03): a missing file, a missing top-level `model`
+ * key, or an unparseable value returns `available: false` with a machine reason
+ * and `model: null`. It NEVER substitutes a default. There is no module-level
+ * cached value — the file is re-read on every call.
+ *
+ * `existsSync` / `readFileSync` are injected so tests stay hermetic (no real
+ * `$HOME` read).
+ *
+ * @param {{ home: string, existsSync: (p: string) => boolean, readFileSync: (p: string, enc: string) => string }} deps
+ * @returns {CodexSparModelResolution}
+ */
+export function resolveCodexSparModel({ home, existsSync, readFileSync }) {
+	const source = CODEX_CONFIG_SOURCE
+	const configPath = join(home, '.codex', 'config.toml')
+	if (!existsSync(configPath)) {
+		return { available: false, model: null, source, reason: 'config_missing' }
+	}
+	let text
+	try {
+		text = readFileSync(configPath, 'utf-8')
+	} catch {
+		return { available: false, model: null, source, reason: 'config_missing' }
+	}
+	const { model, reason } = parseTopLevelCodexModel(text)
+	if (model) {
+		return { available: true, model, source, reason: null }
+	}
+	return { available: false, model: null, source, reason: reason ?? 'unparseable' }
+}

package/src/cli/install/legacy-paths.mjs

@@ -108,6 +108,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'agents/apt-personas.md',
 			'agents/apt-plan.md',
 			'agents/apt-pr-review.md',
+			'agents/apt-produce.md',
 			'agents/apt-prototype.md',
 			'agents/apt-quick.md',
 			'agents/apt-release-notes.md',
@@ -153,6 +154,7 @@ export const LEGACY_INSTALL_PATHS = Object.freeze({
 			'commands/apt-personas.md',
 			'commands/apt-plan.md',
 			'commands/apt-pr-review.md',
+			'commands/apt-produce.md',
 			'commands/apt-prototype.md',
 			'commands/apt-quick.md',
 			'commands/apt-release-notes.md',

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

@@ -0,0 +1,245 @@
+/**
+ * @internal
+ * produce/blind-probe.mjs — the held-out cross-family blind-probe set (M2, AC4-6).
+ *
+ * A fixed 10–20 behavioral probe set the implementer/Showrunner NEVER sees
+ * (probe-blindness, US-4 / ID-06), authored + run by a provider family DISJOINT
+ * from the implementer's, re-run on a rotating sample of already-done milestones
+ * against HEAD (US-6).
+ *
+ * The probe SET is a frozen immutable artifact at
+ * `.aperant/produce/<run-id>/probes/<milestone>.json`, written ONCE via
+ * `openSync(path, 'wx')` exclusive-create — a second freeze throws EEXIST and
+ * returns the byte-identical stored set (mirrors setpoint.mjs::freezeSetpoint).
+ * Its CONTENT never enters the event log or the roadmap projection the
+ * Showrunner re-reads each tick (structural probe-blindness, ID-M2-03): the
+ * `produce.probe.frozen` event carries ONLY `{probe_set_hash, author_family}`
+ * and `produce.probe.run` carries ONLY `{result, probe_family, head_sha}`.
+ */
+
+import { createHash } from 'node:crypto'
+import {
+	closeSync,
+	existsSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	writeSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import {
+	appendProduceEvent,
+	readImplementerFamily,
+	readProduceRunEventsMatching,
+} from './events.mjs'
+import { normalizeFamily } from './probe-family.mjs'
+import { projectRoadmap } from './projection.mjs'
+import { resolveRunDir } from './run-id.mjs'
+
+/** sha256 of the canonical JSON of the probe content (the immutable hash stamp). */
+function computeProbeSetHash(content) {
+	return createHash('sha256').update(JSON.stringify(content)).digest('hex')
+}
+
+/** The probes/<milestone>.json path for a run + milestone. */
+export function probeSetPathFor(projectDir, runId, milestoneId) {
+	return join(resolveRunDir(projectDir, runId), 'probes', `${milestoneId}.json`)
+}
+
+/** Read + parse a frozen probe set. Returns null when absent or malformed. */
+export function readProbeSet(projectDir, runId, milestoneId) {
+	const p = probeSetPathFor(projectDir, runId, milestoneId)
+	if (!existsSync(p)) return null
+	try {
+		return JSON.parse(readFileSync(p, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Exclusive-create write of the frozen probe set on the FINAL path (NOT
+ * tmp+rename), so a SECOND write throws EEXIST — the set is immutable.
+ */
+function writeProbeSetExclusive(probePath, probeSet) {
+	mkdirSync(join(probePath, '..'), { recursive: true })
+	const payload = `${JSON.stringify(probeSet, null, 2)}\n`
+	const fd = openSync(probePath, 'wx') // throws EEXIST when already frozen
+	try {
+		writeSync(fd, payload, 0, 'utf-8')
+		fsyncSync(fd)
+	} finally {
+		closeSync(fd)
+	}
+}
+
+/**
+ * Freeze a blind-probe set for a milestone, idempotently. REFUSES fail-closed
+ * when the author family equals the implementer family (a held-out probe an
+ * implementer authored is not held out — ID-06) or when no implementer family
+ * is recorded (ID-M2-02). On a FRESH freeze appends `produce.probe.frozen`
+ * carrying ONLY the hash + author family (never the content). A second freeze
+ * returns the byte-identical stored set (`reused: true`) and never re-logs.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {string} milestoneId
+ * @param {{ content: unknown, authorFamily: string, implementerFamily: string }} args
+ * @param {Date} [now]
+ * @returns {{ ok: true, reused: boolean, probe_set_hash: string, author_family: string }
+ *   | { ok: false, reason: string }}
+ */
+export function freezeProbeSet(
+	projectDir,
+	runId,
+	milestoneId,
+	{ content, authorFamily, implementerFamily },
+	now = new Date(),
+) {
+	if (!authorFamily) return { ok: false, reason: 'no_author_family' }
+	if (!implementerFamily) return { ok: false, reason: 'no_implementer_family' }
+	// Cross-family enforcement (normalized so claude-code === claude).
+	if (normalizeFamily(authorFamily) === normalizeFamily(implementerFamily))
+		return { ok: false, reason: 'same_family_author' }
+
+	const probePath = probeSetPathFor(projectDir, runId, milestoneId)
+	const existing = readProbeSet(projectDir, runId, milestoneId)
+	if (existing)
+		return {
+			ok: true,
+			reused: true,
+			probe_set_hash: existing.probe_set_hash,
+			author_family: existing.author_family,
+		}
+
+	const probeSetHash = computeProbeSetHash(content ?? null)
+	const probeSet = {
+		run_id: runId,
+		milestone_id: milestoneId,
+		author_family: authorFamily,
+		frozen_at: now.toISOString(),
+		probe_set_hash: probeSetHash,
+		// The probe CONTENT lives in the frozen file (blind to the projection) —
+		// it NEVER enters the event log.
+		probes: content ?? null,
+	}
+
+	try {
+		writeProbeSetExclusive(probePath, probeSet)
+	} catch (e) {
+		// Lost a concurrent race — the winner's file is authoritative; re-read it
+		// byte-identically rather than overwriting (mirrors freezeSetpoint).
+		if (e && e.code === 'EEXIST') {
+			const winner = readProbeSet(projectDir, runId, milestoneId)
+			if (winner)
+				return {
+					ok: true,
+					reused: true,
+					probe_set_hash: winner.probe_set_hash,
+					author_family: winner.author_family,
+				}
+		}
+		throw e
+	}
+
+	// Announce by hash + author family ONLY — never the content (ID-M2-03).
+	appendProduceEvent(projectDir, 'produce.probe.frozen', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		probe_set_hash: probeSetHash,
+		author_family: authorFamily,
+	})
+
+	return { ok: true, reused: false, probe_set_hash: probeSetHash, author_family: authorFamily }
+}
+
+/**
+ * Record a blind-probe RUN result. REFUSES fail-closed when the probe family
+ * equals the implementer family (a probe run BY the implementer family is not
+ * cross-family — ID-08) or when no implementer family is recorded. On
+ * acceptance appends `produce.probe.run {run_id, milestone_id, result,
+ * probe_family, head_sha}` — result/family/head_sha only, never content.
+ *
+ * @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 }
+ *   | { ok: false, reason: string }}
+ */
+export function recordProbeRun(projectDir, { runId, milestoneId, result, probeFamily, headSha }) {
+	if (result !== 'pass' && result !== 'fail') return { ok: false, reason: 'invalid_result' }
+	if (!probeFamily) return { ok: false, reason: 'no_probe_family' }
+	if (!headSha) return { ok: false, reason: 'no_head_sha' }
+
+	const implementerFamily = readImplementerFamily(projectDir, runId, milestoneId)
+	if (!implementerFamily) return { ok: false, reason: 'no_recorded_implementer' }
+	if (normalizeFamily(probeFamily) === normalizeFamily(implementerFamily))
+		return { ok: false, reason: 'same_family_probe' }
+
+	appendProduceEvent(projectDir, 'produce.probe.run', {
+		run_id: runId,
+		milestone_id: milestoneId,
+		result,
+		probe_family: probeFamily,
+		head_sha: headSha,
+	})
+
+	return { ok: true, result, probe_family: probeFamily, head_sha: headSha }
+}
+
+/**
+ * Select a DETERMINISTIC rotating sample of already-`done` milestones for blind
+ * re-probing against HEAD (US-6). Rotates by fewest prior probe runs first,
+ * then oldest last-probe-run first (a never-probed done milestone sorts first),
+ * then first-seen roadmap order — so two folds of the same log select the same
+ * sample.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ sample?: number }} [opts]
+ * @returns {{ run_id: string, sample_size: number, selected: Array<{ milestone_id: string, title: string, probe_run_count: number, last_probe_run_at: string | null }> }}
+ */
+export function selectSweepSample(projectDir, runId, { sample = 1 } = {}) {
+	const roadmap = projectRoadmap(projectDir, runId)
+	const done = roadmap.milestones.filter((m) => m.status === 'done')
+
+	const runEvents = readProduceRunEventsMatching(
+		projectDir,
+		runId,
+		(op) => op === 'produce.probe.run',
+	)
+	const stats = new Map()
+	for (const e of runEvents) {
+		const id = e.data && typeof e.data.milestone_id === 'string' ? e.data.milestone_id : null
+		if (!id) continue
+		const s = stats.get(id) || { count: 0, last: null }
+		s.count += 1
+		if (typeof e.t === 'string' && (s.last === null || e.t > s.last)) s.last = e.t
+		stats.set(id, s)
+	}
+
+	const withOrder = done.map((m, idx) => {
+		const s = stats.get(m.id) || { count: 0, last: null }
+		return { milestone: m, order: idx, count: s.count, last: s.last }
+	})
+
+	withOrder.sort((a, b) => {
+		if (a.count !== b.count) return a.count - b.count // fewest probe runs first
+		// oldest last-probe-run first — a never-probed done milestone (null) sorts
+		// ahead of any dated one.
+		const al = a.last ?? ''
+		const bl = b.last ?? ''
+		if (al !== bl) return al < bl ? -1 : 1
+		return a.order - b.order // first-seen roadmap order (stable tiebreak)
+	})
+
+	const n = Number.isFinite(sample) && sample > 0 ? Math.floor(sample) : 1
+	const selected = withOrder.slice(0, n).map((w) => ({
+		milestone_id: w.milestone.id,
+		title: w.milestone.title,
+		probe_run_count: w.count,
+		last_probe_run_at: w.last,
+	}))
+
+	return { run_id: runId, sample_size: selected.length, selected }
+}