@aperant/framework 0.17.0 → 0.19.0

package/src/cli/produce/claim.mjs

@@ -0,0 +1,543 @@
+/**
+ * @internal
+ * produce/claim.mjs — the Claim Envelope: a provider-neutral interop SHAPE +
+ * a data-driven profile registry + an event-sourced claim ledger (M6).
+ *
+ * A Claim Envelope captures a durable, bounded, expiring claim (the `lesson`
+ * profile is the only one M6 ships). It is NOT a 4th persistence store (parent
+ * D-02/D-03, ID-M6-01): the ledger reuses the EXACT substrate M1/M2 already use —
+ * a per-record immutable content file at `.aperant/produce/<run-id>/claims/<id>.json`
+ * written ONCE via `openSync(path, 'wx')` (mirrors setpoint.mjs / blind-probe.mjs),
+ * referenced by `content_hash` from an append-only `produce.claim.declared` event,
+ * and PROJECTED by a `projectClaims` fold parallel to `ledger.mjs::projectLedger`.
+ * The roadmap projection still folds `produce.roadmap.*` ONLY, so claim ops never
+ * enter the roadmap the Showrunner re-reads (blindness preserved).
+ *
+ * Generalization is REGISTRY DATA, never a code fork (ID-M6-02): `CLAIM_PROFILES`
+ * maps a profile id → `{ requiredFields, validate }`, and `validateClaimEnvelope`
+ * dispatches on `envelope.profile` via the registry — there is NO hardcoded
+ * `if (profile === 'lesson')` branch, so a 2nd profile is one map entry and an
+ * unknown profile fails closed.
+ *
+ * Deterministic, node-only, ZERO model id — it is pure fold/validation math over
+ * the log + per-record files, like ledger.mjs / scheduler.mjs (ID-M6-08).
+ */
+
+import { createHash } from 'node:crypto'
+import {
+	closeSync,
+	existsSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	writeSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
+import { appendProduceEvent, readProduceRunEventsMatching } from './events.mjs'
+import { resolveRunDir, slugFromOutcome } from './run-id.mjs'
+
+/** Plain (non-array, non-null) object guard. */
+function isPlainObject(v) {
+	return v != null && typeof v === 'object' && !Array.isArray(v)
+}
+
+/** Plain object carrying at least one own key. */
+function isNonEmptyObject(v) {
+	return isPlainObject(v) && Object.keys(v).length > 0
+}
+
+/** A bound is a non-empty string / non-empty array / non-empty object. */
+function isNonEmptyBound(v) {
+	if (typeof v === 'string') return v.trim().length > 0
+	if (Array.isArray(v)) return v.length > 0
+	if (isPlainObject(v)) return Object.keys(v).length > 0
+	return false
+}
+
+/**
+ * A scope is BOUNDED iff it is a plain object, `global !== true`, and carries at
+ * least one non-`global` key with a non-empty bound (anti-windup, ID-M6-05). A
+ * `{ global: true }` scope or a scope with no actual bound is REJECTED.
+ */
+function isBoundedScope(scope) {
+	if (!isPlainObject(scope)) return false
+	if (scope.global === true) return false
+	return Object.keys(scope).some((k) => k !== 'global' && isNonEmptyBound(scope[k]))
+}
+
+/**
+ * An expiry object carries a decay path: `expires_at` (non-empty string) OR
+ * `revalidate_against_head` (any truthy value). A lesson with no expiry/decay
+ * path is REJECTED (anti-corrosion, ID-M6-04).
+ */
+function hasExpiry(expiry) {
+	if (!isPlainObject(expiry)) return false
+	const hasExpiresAt = typeof expiry.expires_at === 'string' && expiry.expires_at.trim().length > 0
+	const hasRevalidate =
+		expiry.revalidate_against_head != null && expiry.revalidate_against_head !== false
+	return hasExpiresAt || hasRevalidate
+}
+
+/** The verifiable plan requirement — a non-empty string / array / object. */
+function isNonEmptyVerifier(rv) {
+	if (typeof rv === 'string') return rv.trim().length > 0
+	if (Array.isArray(rv)) return rv.length > 0
+	if (isPlainObject(rv)) return Object.keys(rv).length > 0
+	return false
+}
+
+/**
+ * The `lesson` profile validator (ID-M6-03). REQUIRES all 6 AC15 fields and
+ * REJECTS fail-closed (never throws): missing provenance; empty preconditions
+ * (unconditional rule — bounded-critic clamp); global/unbounded scope
+ * (anti-windup); missing expiry (anti-corrosion); missing negative_evidence
+ * field; empty resolution_verifier. Returns `{ ok:false, reason }`.
+ *
+ * @param {Record<string, unknown>} env
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+function validateLessonEnvelope(env) {
+	if (!isNonEmptyObject(env.provenance)) return { ok: false, reason: 'missing_provenance' }
+	if (!Array.isArray(env.preconditions) || env.preconditions.length === 0)
+		return { ok: false, reason: 'empty_preconditions' }
+	if (!isBoundedScope(env.scope)) return { ok: false, reason: 'unbounded_scope' }
+	if (!hasExpiry(env.expiry)) return { ok: false, reason: 'missing_expiry' }
+	if (!Array.isArray(env.negative_evidence))
+		return { ok: false, reason: 'missing_negative_evidence' }
+	if (!isNonEmptyVerifier(env.resolution_verifier))
+		return { ok: false, reason: 'empty_resolution_verifier' }
+	return { ok: true }
+}
+
+/**
+ * The data-driven profile registry (ID-M6-02). A profile is one map entry
+ * (`{ requiredFields, validate }`) — adding a 2nd is data, not a code fork. M6
+ * SHIPS only `lesson`; the generalization is PROVEN by a test that injects a
+ * trivial second profile via `validateClaimEnvelope`'s `profiles` arg.
+ */
+export const CLAIM_PROFILES = {
+	lesson: {
+		requiredFields: [
+			'provenance',
+			'preconditions',
+			'scope',
+			'expiry',
+			'negative_evidence',
+			'resolution_verifier',
+		],
+		validate: validateLessonEnvelope,
+	},
+}
+
+/**
+ * Validate a Claim Envelope by dispatching on `envelope.profile` through the
+ * REGISTRY (never a hardcoded profile branch — ID-M6-02). An unknown/absent
+ * profile fails closed (`{ ok:false, reason:'unknown_profile' }`). Never throws.
+ *
+ * @param {Record<string, unknown>} envelope
+ * @param {{ profiles?: Record<string, { validate: (env: Record<string, unknown>) => { ok: boolean, reason?: string } }> }} [opts]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function validateClaimEnvelope(envelope, { profiles = CLAIM_PROFILES } = {}) {
+	const env = isPlainObject(envelope) ? envelope : {}
+	const profileId = typeof env.profile === 'string' ? env.profile : ''
+	const spec = profiles[profileId]
+	if (!spec || typeof spec.validate !== 'function') return { ok: false, reason: 'unknown_profile' }
+	return spec.validate(env)
+}
+
+/**
+ * Mint a claim id: `<slug-of-text>-<rand>`. Reuses `slugFromOutcome` + a short
+ * random suffix (mirrors ledger.mjs::mintCriterionId) so two claims minted from
+ * the same text never collide. Falls back to the profile when text is empty.
+ *
+ * @param {string} profile
+ * @param {string} text
+ * @returns {string}
+ */
+export function mintClaimId(profile, text) {
+	const slug = slugFromOutcome(text || profile || 'claim')
+	return `${slug}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+/** sha256 of the canonical JSON of the claim content (the immutable hash stamp). */
+function computeClaimContentHash(content) {
+	return createHash('sha256')
+		.update(JSON.stringify(content ?? null))
+		.digest('hex')
+}
+
+/** The claims/<claim-id>.json path for a run + claim. */
+export function claimPathFor(projectDir, runId, claimId) {
+	return join(resolveRunDir(projectDir, runId), 'claims', `${claimId}.json`)
+}
+
+/** Read + parse a frozen claim record. Returns null when absent or malformed. */
+export function readClaim(projectDir, runId, claimId) {
+	const p = claimPathFor(projectDir, runId, claimId)
+	if (!existsSync(p)) return null
+	try {
+		return JSON.parse(readFileSync(p, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Exclusive-create write of the frozen claim record on the FINAL path (NOT
+ * tmp+rename), so a SECOND write throws EEXIST — the claim content is immutable
+ * (mirrors setpoint.mjs::writeSetpointExclusive / blind-probe.mjs).
+ */
+function writeClaimExclusive(claimPath, record) {
+	mkdirSync(dirname(claimPath), { recursive: true })
+	const payload = `${JSON.stringify(record, null, 2)}\n`
+	const fd = openSync(claimPath, 'wx') // throws EEXIST when already frozen
+	try {
+		writeSync(fd, payload, 0, 'utf-8')
+		fsyncSync(fd)
+	} finally {
+		closeSync(fd)
+	}
+}
+
+/**
+ * Freeze a Claim Envelope, idempotently. VALIDATES first (refuses to freeze an
+ * invalid envelope — fail-closed), computes `content_hash = sha256(envelope)`,
+ * writes `claims/<claim-id>.json` exclusive-create, and on a FRESH freeze appends
+ * `produce.claim.declared {run_id, profile, claim_id, content_hash}` (content_hash
+ * only — the full envelope lives in the frozen file, ID-M6-07). A second freeze
+ * of the same claim id returns the byte-identical stored record (`reused: true`)
+ * and never re-logs. The resolved `profile` (explicit arg or `envelope.profile`)
+ * is authoritative for validation dispatch + the stored/logged profile.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {{ profile?: string, envelope: Record<string, unknown>, claimId?: string }} args
+ * @param {{ profiles?: object, now?: Date }} [opts]
+ * @returns {{ ok: true, reused: boolean, claim_id: string, profile: string | null, content_hash: string }
+ *   | { ok: false, reason: string }}
+ */
+export function freezeClaim(
+	projectDir,
+	runId,
+	{ profile, envelope, claimId } = {},
+	{ profiles = CLAIM_PROFILES, now = new Date() } = {},
+) {
+	const env = isPlainObject(envelope) ? envelope : {}
+	const resolvedProfile =
+		typeof profile === 'string' && profile
+			? profile
+			: typeof env.profile === 'string'
+				? env.profile
+				: null
+	// The resolved profile is authoritative — validate + store + log agree.
+	const envelopeForValidation = resolvedProfile ? { ...env, profile: resolvedProfile } : env
+
+	const verdict = validateClaimEnvelope(envelopeForValidation, { profiles })
+	if (!verdict.ok) return { ok: false, reason: verdict.reason }
+
+	const resolvedClaimId =
+		typeof claimId === 'string' && claimId
+			? claimId
+			: typeof env.id === 'string' && env.id
+				? env.id
+				: mintClaimId(
+						resolvedProfile ?? 'claim',
+						typeof env.resolution_verifier === 'string' ? env.resolution_verifier : resolvedProfile,
+					)
+
+	const existing = readClaim(projectDir, runId, resolvedClaimId)
+	if (existing)
+		return {
+			ok: true,
+			reused: true,
+			claim_id: resolvedClaimId,
+			profile: existing.profile ?? resolvedProfile,
+			content_hash: existing.content_hash,
+		}
+
+	const contentHash = computeClaimContentHash(envelopeForValidation)
+	const record = {
+		run_id: runId,
+		claim_id: resolvedClaimId,
+		profile: resolvedProfile,
+		frozen_at: now.toISOString(),
+		content_hash: contentHash,
+		// The full claim content lives HERE — blind to the event log (ID-M6-07).
+		envelope: envelopeForValidation,
+	}
+
+	try {
+		writeClaimExclusive(claimPathFor(projectDir, runId, resolvedClaimId), record)
+	} 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 = readClaim(projectDir, runId, resolvedClaimId)
+			if (winner)
+				return {
+					ok: true,
+					reused: true,
+					claim_id: resolvedClaimId,
+					profile: winner.profile ?? resolvedProfile,
+					content_hash: winner.content_hash,
+				}
+		}
+		throw e
+	}
+
+	// Announce by hash + profile ONLY — never the content (ID-M6-07).
+	appendProduceEvent(projectDir, 'produce.claim.declared', {
+		run_id: runId,
+		profile: resolvedProfile,
+		claim_id: resolvedClaimId,
+		content_hash: contentHash,
+	})
+
+	return {
+		ok: true,
+		reused: false,
+		claim_id: resolvedClaimId,
+		profile: resolvedProfile,
+		content_hash: contentHash,
+	}
+}
+
+/** The closed set of consumption-delta target kinds (mirrors ALLOWED_CLAIM_TARGET_KINDS). */
+export const CLAIM_TARGET_KINDS = ['acceptance_criterion', 'subtask', 'proof_obligation']
+
+/**
+ * Fold the run's claim ledger from the append-only log — a SEPARATE fold parallel
+ * to `ledger.mjs::projectLedger` / `saga.mjs::projectSaga` (the roadmap projection
+ * still folds `produce.roadmap.*` ONLY, so claim ops never enter the roadmap the
+ * Showrunner re-reads). A `produce.claim.declared` seeds an ACTIVE claim (in
+ * first-seen order); a `produce.claim.expired` advances it to `expired`;
+ * `produce.claim.consumed` is a forensic-only event that does NOT change status.
+ * Deterministic — two folds of the same log yield the identical ledger.
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @returns {{
+ *   run_id: string,
+ *   claims: Array<{ claim_id: string, profile: string | null, content_hash: string | null, status: 'active' | 'expired' }>,
+ *   active_count: number,
+ *   expired_count: number,
+ *   updated_at: string | null,
+ * }}
+ */
+export function projectClaims(projectDir, runId) {
+	const events = readProduceRunEventsMatching(projectDir, runId, (op) =>
+		op.startsWith('produce.claim.'),
+	)
+	const byId = new Map()
+	const order = []
+	let updatedAt = null
+
+	for (const e of events) {
+		const d = e.data || {}
+		const cid = typeof d.claim_id === 'string' ? d.claim_id : null
+		if (e.op === 'produce.claim.declared') {
+			if (cid && !byId.has(cid)) {
+				byId.set(cid, {
+					claim_id: cid,
+					profile: typeof d.profile === 'string' ? d.profile : null,
+					content_hash: typeof d.content_hash === 'string' ? d.content_hash : null,
+					status: 'active',
+				})
+				order.push(cid)
+			}
+		} else if (e.op === 'produce.claim.expired') {
+			if (cid && byId.has(cid)) byId.get(cid).status = 'expired'
+		}
+		if (typeof e.t === 'string') updatedAt = e.t
+	}
+
+	const claims = order.map((cid) => byId.get(cid))
+	return {
+		run_id: runId,
+		claims,
+		active_count: claims.filter((c) => c.status === 'active').length,
+		expired_count: claims.filter((c) => c.status === 'expired').length,
+		updated_at: updatedAt,
+	}
+}
+
+/**
+ * The DEFAULT HEAD re-validation predicate (ID-M6-04) — a deterministic
+ * path-exists / grep against the working tree, NEVER an LLM judgment (mirrors the
+ * injected `codexDeps` in probe-family.mjs / the injected existence predicate in
+ * resolveResumeCwd). `check` is `{ path?, pattern? }` (or a bare path string).
+ * Returns false when the referenced file/pattern no longer matches HEAD.
+ *
+ * @param {unknown} check
+ * @returns {boolean}
+ */
+function defaultHeadCheck(check) {
+	const spec = typeof check === 'string' ? { path: check } : isPlainObject(check) ? check : {}
+	if (typeof spec.path === 'string' && spec.path) {
+		if (!existsSync(spec.path)) return false
+		if (typeof spec.pattern === 'string' && spec.pattern) {
+			try {
+				return readFileSync(spec.path, 'utf-8').includes(spec.pattern)
+			} catch {
+				return false
+			}
+		}
+		return true
+	}
+	// No actionable check descriptor → nothing to invalidate (still valid).
+	return true
+}
+
+/** One precondition matches ctx iff every key equals (or set-includes) the ctx value. */
+function matchOne(cond, ctx) {
+	if (!isPlainObject(cond)) return false
+	return Object.keys(cond).every((k) => {
+		const expected = cond[k]
+		const actual = ctx[k]
+		if (Array.isArray(expected)) return expected.includes(actual)
+		if (Array.isArray(actual)) return actual.includes(expected)
+		return actual === expected
+	})
+}
+
+/**
+ * The claim FIRES (its trigger matches) iff EVERY precondition matches ctx
+ * (conjunction — a narrow gate, bounded-critic ID-M6-05). An absent/empty
+ * preconditions list is vacuously matched (a validated lesson always has ≥1).
+ */
+function preconditionsMatch(preconditions, ctx) {
+	if (!Array.isArray(preconditions) || preconditions.length === 0) return true
+	const c = isPlainObject(ctx) ? ctx : {}
+	return preconditions.every((cond) => matchOne(cond, c))
+}
+
+/**
+ * Decide whether a claim may be consumed against a ctx (ID-M6-04, anti-corrosion).
+ * DETERMINISTIC (no LLM). SKIPS with a reason when: the claim is time-expired
+ * (`now() > expiry.expires_at` → `expired`); the claim's `revalidate_against_head`
+ * check no longer matches HEAD (`headCheck(check) === false` → `head_invalidated`);
+ * or the preconditions don't match ctx (`precondition_unmatched`). Otherwise
+ * `{ consume: true }`. `now` + `headCheck` are INJECTED (default now = new Date,
+ * default headCheck = the working-tree path-exists/grep).
+ *
+ * @param {Record<string, unknown>} claim — the claim ENVELOPE (carries expiry + preconditions).
+ * @param {Record<string, unknown>} [ctx]
+ * @param {{ now?: () => Date, headCheck?: (check: unknown) => boolean }} [deps]
+ * @returns {{ consume: true } | { consume: false, reason: string }}
+ */
+export function evaluateClaimForConsumption(claim, ctx = {}, deps = {}) {
+	const now = typeof deps.now === 'function' ? deps.now : () => new Date()
+	const headCheck = typeof deps.headCheck === 'function' ? deps.headCheck : defaultHeadCheck
+	const env = isPlainObject(claim) ? claim : {}
+	const expiry = isPlainObject(env.expiry) ? env.expiry : {}
+
+	// (1) Time expiry.
+	if (typeof expiry.expires_at === 'string' && expiry.expires_at) {
+		const expiresAt = new Date(expiry.expires_at).getTime()
+		if (Number.isFinite(expiresAt) && now().getTime() > expiresAt) {
+			return { consume: false, reason: 'expired' }
+		}
+	}
+	// (2) HEAD re-validation (anti-corrosion) — deterministic, never an LLM.
+	if (expiry.revalidate_against_head != null && expiry.revalidate_against_head !== false) {
+		if (!headCheck(expiry.revalidate_against_head)) {
+			return { consume: false, reason: 'head_invalidated' }
+		}
+	}
+	// (3) Precondition match against ctx (the trigger).
+	if (!preconditionsMatch(env.preconditions, ctx)) {
+		return { consume: false, reason: 'precondition_unmatched' }
+	}
+	return { consume: true }
+}
+
+/** Read the frozen claim ENVELOPE (the `.envelope` payload), null when absent/malformed. */
+function readClaimEnvelope(projectDir, runId, claimId) {
+	const record = readClaim(projectDir, runId, claimId)
+	if (!record) return null
+	return isPlainObject(record.envelope) ? record.envelope : null
+}
+
+/**
+ * Derive the bounded consumption DELTA from a claim envelope's
+ * `resolution_verifier` ONLY (ID-M6-06 — the down-projection). Returns
+ * `[{ kind, requirement, ref? }]` where `kind` is clamped to the closed
+ * CLAIM_TARGET_KINDS set (fail-closed default `acceptance_criterion`) and
+ * `requirement` is a bounded string taken FROM `resolution_verifier`. This
+ * function reads NOTHING ELSE off the envelope — never `provenance`,
+ * `negative_evidence`, `preconditions`, or a raw body — so a sentinel placed in
+ * those fields can never reach the consume output (the sentinel-non-leak
+ * invariant). NO raw-lesson-text → prompt concatenation sink lives here.
+ *
+ * @param {Record<string, unknown>} envelope
+ * @returns {Array<{ kind: string, requirement: string, ref?: string }>}
+ */
+function deriveTargets(envelope) {
+	const rv = isPlainObject(envelope) ? envelope.resolution_verifier : undefined
+	const raw = Array.isArray(rv) ? rv : [rv]
+	const targets = []
+	for (const item of raw) {
+		if (typeof item === 'string' && item.length > 0) {
+			targets.push({ kind: 'acceptance_criterion', requirement: item })
+		} else if (isPlainObject(item)) {
+			const kind = CLAIM_TARGET_KINDS.includes(item.kind) ? item.kind : 'acceptance_criterion'
+			const requirement =
+				typeof item.requirement === 'string' && item.requirement
+					? item.requirement
+					: typeof item.text === 'string'
+						? item.text
+						: ''
+			const target = { kind, requirement }
+			if (typeof item.ref === 'string' && item.ref) target.ref = item.ref
+			targets.push(target)
+		}
+	}
+	return targets
+}
+
+/**
+ * Consume the run's ACTIVE claims against a ctx (ID-M6-06 — THE M6 invariant).
+ * For each active claim, evaluate it; a consumable claim emits ONE bounded delta
+ * `{ claim_id, profile, targets: [{ kind, requirement, ref? }] }` where every
+ * `targets[].kind ∈ CLAIM_TARGET_KINDS` and `requirement` is derived FROM
+ * `resolution_verifier` — a projection DOWN. The output MUST NOT carry the claim's
+ * `provenance` / `negative_evidence` / `preconditions` / body (never a context
+ * paste). Skipped claims (expired / head_invalidated / precondition_unmatched /
+ * unreadable) surface under `skipped[]` with a reason. PURE — appends no event
+ * (the CLI records `produce.claim.consumed` per target for the forensic trail).
+ *
+ * @param {string} projectDir
+ * @param {string} runId
+ * @param {Record<string, unknown>} [ctx]
+ * @param {{ now?: () => Date, headCheck?: (check: unknown) => boolean }} [deps]
+ * @returns {{
+ *   consumed: Array<{ claim_id: string, profile: string | null, targets: Array<{ kind: string, requirement: string, ref?: string }> }>,
+ *   skipped: Array<{ claim_id: string, reason: string }>,
+ * }}
+ */
+export function consumeClaims(projectDir, runId, ctx = {}, deps = {}) {
+	const ledger = projectClaims(projectDir, runId)
+	const consumed = []
+	const skipped = []
+	for (const summary of ledger.claims) {
+		if (summary.status !== 'active') continue // expired claims never consume
+		const envelope = readClaimEnvelope(projectDir, runId, summary.claim_id)
+		if (!envelope) {
+			skipped.push({ claim_id: summary.claim_id, reason: 'unreadable_claim' })
+			continue
+		}
+		const verdict = evaluateClaimForConsumption(envelope, ctx, deps)
+		if (!verdict.consume) {
+			skipped.push({ claim_id: summary.claim_id, reason: verdict.reason })
+			continue
+		}
+		consumed.push({
+			claim_id: summary.claim_id,
+			profile: summary.profile ?? (typeof envelope.profile === 'string' ? envelope.profile : null),
+			targets: deriveTargets(envelope),
+		})
+	}
+	return { consumed, skipped }
+}