phronesis 1.0.0

package/vendor/core/src/contract.js

@@ -0,0 +1,245 @@
+// Ontology frontmatter contract — specs/ontology.md, locked by change 0009
+// (primitive vocabulary + the relationships field per change 0012 / ADR 0006).
+//
+// The single source for what `phronesis validate` enforces. Pure data + pure checks,
+// no filesystem — link *existence* is resolved by the caller (validate.js), which has
+// fs access. Extracted to packages/core (core-0007) so the T2.2 action types validate
+// inputs against this same contract (the "two consumers → package" rule).
+
+export const OBJECT_TYPES = [
+  'person', 'project', 'decision', 'commitment', 'insight', 'organization',
+  'codex-principle-seed', 'codex-principle-personal',
+];
+export const DOMAIN_TYPES = ['person', 'project', 'decision', 'commitment', 'insight', 'organization'];
+export const CODEX_PRINCIPLE_TYPES = ['codex-principle-seed', 'codex-principle-personal'];
+// Entity types name what something IS (a person, an organization) — never the door's
+// relationship to it (ADR 0006 / change 0012). The door's relationship semantics live
+// in the `relationships` field, valid only here.
+export const ENTITY_TYPES = ['person', 'organization'];
+
+// Domain object type -> its compiled/ subdirectory (the type-dir).
+export const TYPE_DIR = {
+  person: 'people',
+  project: 'projects',
+  decision: 'decisions',
+  commitment: 'commitments',
+  insight: 'insights',
+  organization: 'organizations',
+};
+// Frozen: the CLI scaffold consumes this list directly (one source) — a consumer
+// push() must throw, not silently widen the contract process-wide.
+export const COMPILED_DIRS = Object.freeze(Object.values(TYPE_DIR));
+
+export const ENUMS = {
+  status: ['active', 'archived', 'superseded'],
+  exposure: ['private', 'context-ok', 'shareable'],
+  authored_by: ['agent', 'human', 'hybrid', 'seed'],
+  confidence: ['low', 'medium', 'high'],
+  outcome_status: ['pending', 'met', 'partial', 'reversed'],
+  stance: ['gravity', 'adopted', 'documented', 'skeptical-of'],
+};
+
+export const LINK_RELS = [
+  'enriched-by', 'decided-by', 'decided-in', 'supersedes', 'superseded-by',
+  'enables', 'blocks', 'cites',
+];
+
+export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const SLUG = '[a-z0-9]+(?:-[a-z0-9]+)*';
+const DIRS = COMPILED_DIRS.join('|');
+
+// Exported for the action spine's payload schemas (actions.js) — one slug grammar,
+// not a re-typed copy that drifts. SLUG_SOURCE is the raw fragment for composing
+// larger grammars (e.g. {collection}/{slug}); never slice it out of RE_SLUG.source.
+export const SLUG_SOURCE = SLUG;
+export const RE_SLUG = new RegExp(`^${SLUG}$`);
+const RE_DOMAIN_BARE = new RegExp(`^(?:${DIRS})/${SLUG}$`);
+const RE_DOMAIN_FULL = new RegExp(`^domains/${SLUG}/compiled/(?:${DIRS})/${SLUG}\\.md$`);
+const RE_CODEX = new RegExp(`^codex/(?:personal/${SLUG}|seed/${SLUG}/${SLUG})$`);
+const RE_RAW = new RegExp(`^domains/${SLUG}/raw/.+\\.[A-Za-z0-9]+$`);
+
+// Classify a link target per the 0009 grammar. Returns the form, whether `forward:true`
+// may waive its existence (domain-object targets only), and a resolver to the
+// install-relative path of the target file (needs the source object's domain for the
+// bare form; returns null when a bare slug has no domain to resolve against).
+export function classifyTarget(target) {
+  if (typeof target !== 'string' || target.length === 0) {
+    return { form: 'invalid', domainObject: false, relPath: () => null };
+  }
+  if (RE_DOMAIN_BARE.test(target)) {
+    return {
+      form: 'domain-object',
+      domainObject: true,
+      relPath: (srcDomain) => (srcDomain ? `domains/${srcDomain}/compiled/${target}.md` : null),
+    };
+  }
+  if (RE_DOMAIN_FULL.test(target)) {
+    return { form: 'domain-object', domainObject: true, relPath: () => target };
+  }
+  if (RE_CODEX.test(target)) {
+    return { form: 'codex-object', domainObject: false, relPath: () => `${target}.md` };
+  }
+  if (RE_RAW.test(target)) {
+    return { form: 'raw-source', domainObject: false, relPath: () => target };
+  }
+  return { form: 'invalid', domainObject: false, relPath: () => null };
+}
+
+function enumError(fm, field, errors) {
+  if (fm[field] !== undefined && !ENUMS[field].includes(fm[field])) {
+    errors.push(`${field}: "${fm[field]}" is not one of ${ENUMS[field].join(' | ')}`);
+  }
+}
+
+// Type-scoped fields (change 0012): valid only on a subset of object types, refused
+// everywhere else. `required` ⇒ absence on an in-scope type is an error; `check` owns
+// the value's shape. An open vocabulary (relationships) gets a shape check and
+// deliberately NO enum — closed where the machine routes, open where only humans read
+// (ADR 0006); `lint` owns value consistency, not `validate`.
+const TYPE_SCOPED_FIELDS = [
+  {
+    field: 'stance',
+    types: CODEX_PRINCIPLE_TYPES,
+    required: true,
+    requiredError: 'missing required field: stance (required on codex principles)',
+    forbiddenError: 'stance: only allowed on codex-principle objects',
+    check: (fm, errors) => enumError(fm, 'stance', errors),
+  },
+  {
+    field: 'relationships',
+    types: ENTITY_TYPES,
+    required: false,
+    forbiddenError: `relationships: only allowed on entity types (${ENTITY_TYPES.join(', ')})`,
+    check: (fm, errors) => {
+      if (!Array.isArray(fm.relationships)) {
+        errors.push('relationships: must be a list of non-empty strings');
+        return;
+      }
+      fm.relationships.forEach((v, i) => {
+        if (typeof v !== 'string' || v.trim() === '') {
+          errors.push(`relationships[${i}]: must be a non-empty string`);
+        }
+      });
+    },
+  },
+];
+
+// Validate one object's parsed frontmatter against the contract. `ctx`:
+//   { layer: 'domain'|'codex', domain: slug|null, typeDir: string|null,
+//     codexKind: 'seed'|'personal'|null, name: <basename without .md> }
+// Returns { errors: string[], links: [{ rel, target, forward, cls }] } — the caller
+// existence-checks `links` (it needs the filesystem).
+export function validateFrontmatter(fm, ctx) {
+  const errors = [];
+  const links = [];
+  if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) {
+    return { errors: ['frontmatter is not a YAML mapping'], links };
+  }
+
+  // type
+  if (!fm.type) errors.push('missing required field: type');
+  else if (!OBJECT_TYPES.includes(fm.type)) errors.push(`type: "${fm.type}" is not a known object type`);
+
+  // universal required
+  for (const f of ['name', 'title', 'created', 'exposure']) {
+    if (fm[f] === undefined || fm[f] === null || fm[f] === '') errors.push(`missing required field: ${f}`);
+  }
+  for (const f of ['created', 'updated', 'review_date']) {
+    if (fm[f] !== undefined && fm[f] !== null && !DATE_RE.test(String(fm[f]))) {
+      errors.push(`${f}: "${fm[f]}" is not YYYY-MM-DD`);
+    }
+  }
+  enumError(fm, 'exposure', errors);
+  enumError(fm, 'status', errors);
+  enumError(fm, 'confidence', errors);
+  enumError(fm, 'outcome_status', errors);
+
+  // provenance.authored_by
+  const prov = fm.provenance;
+  if (prov === undefined || prov === null || typeof prov !== 'object') {
+    errors.push('missing required field: provenance.authored_by');
+  } else if (!prov.authored_by) {
+    errors.push('missing required field: provenance.authored_by');
+  } else if (!ENUMS.authored_by.includes(prov.authored_by)) {
+    errors.push(`provenance.authored_by: "${prov.authored_by}" is not one of ${ENUMS.authored_by.join(' | ')}`);
+  }
+
+  // name: kebab-case-slug (specs/ontology.md), and == its filename — the action-type
+  // contract computes the path deterministically from name, so they must agree.
+  if (fm.name !== undefined && fm.name !== null && fm.name !== '') {
+    const nm = String(fm.name);
+    if (!RE_SLUG.test(nm)) errors.push(`name: "${nm}" is not a kebab-case slug`);
+    if (ctx.name && nm !== ctx.name) errors.push(`name: "${nm}" does not match filename "${ctx.name}"`);
+  }
+
+  // domain field: required on domain objects (== the folder), forbidden on codex
+  if (ctx.layer === 'domain') {
+    if (!fm.domain) errors.push('missing required field: domain (required on domain objects)');
+    else if (fm.domain !== ctx.domain) errors.push(`domain: "${fm.domain}" does not match its workspace "${ctx.domain}"`);
+  } else if (fm.domain !== undefined) {
+    errors.push('domain: must be omitted on codex objects (the codex is unaffiliated)');
+  }
+
+  // type-scoped fields: stance (required on codex principles), relationships
+  // (optional on entity types) — each forbidden everywhere outside its types.
+  const isPrinciple = CODEX_PRINCIPLE_TYPES.includes(fm.type);
+  for (const sf of TYPE_SCOPED_FIELDS) {
+    if (sf.types.includes(fm.type)) {
+      if (sf.required) {
+        if (!fm[sf.field]) errors.push(sf.requiredError);
+        else sf.check(fm, errors);
+      } else if (fm[sf.field] !== undefined) {
+        sf.check(fm, errors);
+      }
+    } else if (fm[sf.field] !== undefined) {
+      errors.push(sf.forbiddenError);
+    }
+  }
+
+  // type <-> layer <-> path
+  if (DOMAIN_TYPES.includes(fm.type)) {
+    if (ctx.layer !== 'domain') errors.push(`type "${fm.type}" is a domain object but lives in the codex layer`);
+    else if (ctx.typeDir !== TYPE_DIR[fm.type]) {
+      errors.push(`type "${fm.type}" must live in compiled/${TYPE_DIR[fm.type]}/, not compiled/${ctx.typeDir || '.'}/`);
+    }
+  } else if (isPrinciple) {
+    if (ctx.layer !== 'codex') errors.push(`type "${fm.type}" is a codex principle but lives in a domain workspace`);
+    else if (fm.type === 'codex-principle-seed' && ctx.codexKind !== 'seed') {
+      errors.push('codex-principle-seed must live under codex/seed/');
+    } else if (fm.type === 'codex-principle-personal' && ctx.codexKind !== 'personal') {
+      errors.push('codex-principle-personal must live under codex/personal/');
+    }
+  }
+
+  // links
+  if (fm.links !== undefined) {
+    if (!Array.isArray(fm.links)) {
+      errors.push('links: must be a list');
+    } else {
+      fm.links.forEach((link, i) => {
+        if (link === null || typeof link !== 'object') {
+          errors.push(`links[${i}]: must be a mapping with rel + target`);
+          return;
+        }
+        if (!link.rel) errors.push(`links[${i}]: missing rel`);
+        else if (!LINK_RELS.includes(link.rel)) errors.push(`links[${i}]: rel "${link.rel}" is not in the link vocabulary`);
+        if (link.target === undefined || link.target === null || link.target === '') {
+          errors.push(`links[${i}]: missing target`);
+          return;
+        }
+        const cls = classifyTarget(link.target);
+        if (cls.form === 'invalid') {
+          errors.push(`links[${i}]: target "${link.target}" matches no link-target form`);
+          return;
+        }
+        const forward = link.forward === true;
+        if (forward && !cls.domainObject) {
+          errors.push(`links[${i}]: forward:true is only allowed on domain-object targets (not "${link.target}")`);
+        }
+        links.push({ rel: link.rel, target: link.target, forward, cls });
+      });
+    }
+  }
+
+  return { errors, links };
+}

package/vendor/core/src/event-log.js

@@ -0,0 +1,338 @@
+// Event-log core — the canonical typed-event stream (specs/event-log.md; core-0006 / T4.0).
+// The substrate every hook subscribes to and every action type emits into: atomic append
+// to .phronesis/events/{YYYY-MM-DD}.jsonl (daily rotation by the LOCAL-tz boundary), a typed
+// record, a capture gate that keeps message/prompt bodies out of the log by default, and the
+// retention/purge mechanics. Pure core: no CLI, no daemon, no filesystem watching — the
+// daemon (T4.1) drives appendEvent for file.* events; the CLI (event.js) wraps emit/tail.
+//
+// Lives in packages/core (core-0007): this module owns the format + validation + I/O; the
+// only Phronesis-specific coupling is the .phronesis/ path layout, kept in named helpers.
+
+import { join } from 'node:path';
+import { appendFile, readFile, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import fse from 'fs-extra';
+
+// The V1 vocabulary (specs/event-log.md §"V1 event types"). A typed stream rejects bare
+// garbage, so emission is NOT open to anything — but it is NOT a closed set either: the
+// spec allows connector-specific events, so the valid set is this vocabulary UNION the
+// connector.<name>.<event> extension pattern (isValidType).
+export const EVENT_TYPES = new Set([
+  'session.start',
+  'session.end',
+  'message.user',
+  'message.agent',
+  'skill.invoked',
+  'skill.completed',
+  'action_type.requested',
+  'action_type.committed',
+  'compile.candidate',
+  'compile.accepted',
+  'compile.rejected',
+  'recall.candidate',
+  'recall.injected',
+  'decision.candidate',
+  'person.candidate',
+  'commitment.candidate',
+  'outcome.due',
+  'schedule.due',
+  'file.created',
+  'file.modified',
+  'file.deleted',
+]);
+
+// Connector-authored extension namespace, e.g. connector.granola.transcript_arrived
+// (event-log.md:83). The only open namespace — everything else must be a known type.
+const CONNECTOR_TYPE_RE = /^connector\.[a-z0-9_-]+\.[a-z0-9][a-z0-9._-]*$/;
+
+export function isKnownType(type) {
+  return EVENT_TYPES.has(type);
+}
+
+// Valid = known vocabulary ∪ the connector extension pattern. The core writes any valid
+// type (the daemon uses it for file.*); the CLI additionally refuses the reserved
+// set below so a caller cannot forge events that belong to an authoritative emitter.
+export function isValidType(type) {
+  return typeof type === 'string' && (EVENT_TYPES.has(type) || CONNECTOR_TYPE_RE.test(type));
+}
+
+// Reserved-emitter types: each has a SOLE authoritative path, and the public CLI
+// refuses freehand emission (event-log.md:164 integrity anti-pattern — events must
+// come from authoritative sources). `file.*` is the V1.5 daemon's filesystem watch
+// (reserved AND unemitted until it ships); `outcome.due` is the V1 session-start
+// due-check (session-hooks.js runDueCheck, per the ratified change 0010 delta — the
+// daemon's date-watch takes over at V1.5); `schedule.due` is the V1 session-start
+// due-check's schedule half (schedule.js runScheduleDueCheck, per the ratified change
+// 0042 delta — the daemon time-watch takes over at V1.5); `skill.invoked` / `skill.completed`
+// are emitted by compliant surface adapters such as the Claude Code lifecycle
+// producer. The `compile.*` lifecycle events (`compile.candidate` from the compile
+// action; `compile.accepted` / `compile.rejected` from the operator review path) are
+// the authoritative provenance `compile review` trusts to classify drafts — its L4
+// quarantine reads the latest candidate's `suspicious_payload` flag AND `content_digest`
+// (change 0027). If a caller could freehand-emit a clean `compile.candidate` with a
+// matching digest, it could make a tampered draft batch-eligible (and could already
+// clear a flagged one) — so the digest is "handler-computed, never caller-supplied"
+// ONLY if the candidate EVENT is itself unforgeable. All authorities write through core
+// appendEvent (the handler + the accept/reject moves); the refusal is a CLI-layer policy,
+// not a format rule.
+const RESERVED_EXACT = new Set([
+  'outcome.due',
+  'schedule.due',
+  'skill.invoked',
+  'skill.completed',
+  'compile.candidate',
+  'compile.accepted',
+  'compile.rejected',
+]);
+export function isReservedType(type) {
+  return typeof type === 'string' && (type.startsWith('file.') || RESERVED_EXACT.has(type));
+}
+
+// Capture-gated fields per event-type prefix (security.md + change 0005). Stored only when
+// config event_log.capture_message_text is true; otherwise dropped, with a non-revealing
+// stand-in retained: message bodies collapse to `length`, recall queries to `prompt_hash`.
+const CAPTURE_GATED = [
+  { prefix: 'message.', field: 'text', keep: 'length', derive: (s) => s.length },
+  { prefix: 'recall.', field: 'query', keep: 'prompt_hash', derive: (s) => sha256(s) },
+];
+
+function sha256(s) {
+  return createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+// --- Paths -------------------------------------------------------------------------------
+
+export function eventsDir(installRoot) {
+  return join(installRoot, '.phronesis', 'events');
+}
+
+function archiveDir(installRoot) {
+  return join(eventsDir(installRoot), 'archive');
+}
+
+// Daily file name from a moment, by the LOCAL-tz calendar day (event-log.md:19). The record
+// `ts` is UTC; the FILE is named by local day — a deliberate split so an operator's stream
+// rotates on their midnight, not UTC's.
+export function localDateStamp(date = new Date()) {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, '0');
+  const d = String(date.getDate()).padStart(2, '0');
+  return `${y}-${m}-${d}`;
+}
+
+const DAY_FILE_RE = /^(\d{4}-\d{2}-\d{2})\.jsonl$/;
+
+// --- Ids ---------------------------------------------------------------------------------
+
+// Zero-dep, time-sortable id: evt_<base36(epoch-ms)><base36(rand)> — ULID-shaped without the
+// ulid dep. Same-ms ties fall back to append order within the day file (Decision H). The
+// Date.now/Math.random ban is a Workflow-tool constraint; this is product code.
+export function makeEventId(now = new Date()) {
+  const t = Math.floor(now.getTime()).toString(36);
+  const r = Math.random().toString(36).slice(2, 12).padEnd(10, '0');
+  return `evt_${t}${r}`;
+}
+
+// --- Config ------------------------------------------------------------------------------
+
+// Read the installation's event_log config with privacy-safe defaults. A missing/garbled
+// config fails CLOSED to capture-off (no bodies stored) — the safe default for a privacy
+// gate is "do not capture."
+export async function readEventLogConfig(installRoot) {
+  const defaults = { captureMessageText: false, retentionDays: 90 };
+  try {
+    const cfg = await fse.readJson(join(installRoot, '.phronesis', 'config.json'));
+    const el = (cfg && cfg.event_log) || {};
+    return {
+      captureMessageText: el.capture_message_text === true,
+      retentionDays:
+        Number.isInteger(el.retention_days) && el.retention_days > 0 ? el.retention_days : 90,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+// --- Validation + capture gate -----------------------------------------------------------
+
+// Fail-closed validation: throw a SPECIFIC reason on the first violation (rules.md: assert
+// the specific reason, not just that it failed). All fields but `payload` are mandatory and
+// non-empty (event-log.md:36).
+export function validateEventInput({ type, session_id, actor, surface, payload }) {
+  if (!isValidType(type)) {
+    throw new Error(
+      `event type "${type}" is not in the V1 vocabulary or a connector.<name>.<event> extension`,
+    );
+  }
+  if (typeof session_id !== 'string' || session_id === '') {
+    throw new Error('session_id is required and must be a non-empty string');
+  }
+  if (typeof actor !== 'string' || actor === '') {
+    throw new Error('actor is required and must be a non-empty string');
+  }
+  if (typeof surface !== 'string' || surface === '') {
+    throw new Error('surface is required and must be a non-empty string');
+  }
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('payload must be a JSON object');
+  }
+}
+
+// Apply the privacy capture gate to a payload. With capture on, the payload is returned
+// untouched. With capture off, each gated field is dropped whenever it is PRESENT (any type —
+// a non-string body must never reach disk either; presence-based, not string-typed, so a
+// structured `{ text: {...} }` or `{ query: [...] }` cannot slip the gate). The non-revealing
+// stand-in is derived only from a string body (text → length, query → prompt_hash); a
+// non-string body is dropped with whatever metadata the caller already supplied. Pure:
+// returns a new object, never mutates the caller's payload.
+export function applyCaptureGate(type, payload, { captureMessageText }) {
+  const out = { ...payload };
+  if (captureMessageText) return out;
+  for (const { prefix, field, keep, derive } of CAPTURE_GATED) {
+    if (type.startsWith(prefix) && field in out) {
+      if (out[keep] === undefined && typeof out[field] === 'string') out[keep] = derive(out[field]);
+      delete out[field];
+    }
+  }
+  return out;
+}
+
+// --- Append + read -----------------------------------------------------------------------
+
+// The universal write path. Validates, applies the capture gate (reading config unless
+// captureMessageText is passed explicitly), stamps id + ts, and atomically appends one JSON
+// line to the local-day file. Returns the stored record (the gated payload, the assigned id).
+// `now` is injectable for deterministic tests.
+export async function appendEvent({
+  installRoot,
+  type,
+  session_id,
+  actor,
+  surface,
+  payload = {},
+  captureMessageText,
+  now = new Date(),
+} = {}) {
+  validateEventInput({ type, session_id, actor, surface, payload });
+  const capture =
+    captureMessageText === undefined
+      ? (await readEventLogConfig(installRoot)).captureMessageText
+      : captureMessageText;
+  const record = {
+    id: makeEventId(now),
+    ts: now.toISOString(),
+    session_id,
+    type,
+    actor,
+    surface,
+    payload: applyCaptureGate(type, payload, { captureMessageText: capture }),
+  };
+  const dir = eventsDir(installRoot);
+  await fse.ensureDir(dir);
+  // Single O_APPEND write of one line — atomic for line-sized records (matches the run
+  // ledger's appendFileSync idiom; the spec asks for atomic appends).
+  await appendFile(join(dir, `${localDateStamp(now)}.jsonl`), `${JSON.stringify(record)}\n`);
+  return record;
+}
+
+// Live day files (newest last), excluding the archive/ subdir. The archive holds rotated
+// .jsonl files too, so a name-regex on the events/ dir (non-recursive) is what keeps cold
+// storage out of the live stream.
+export async function listDayFiles(installRoot) {
+  let entries;
+  try {
+    entries = await readdir(eventsDir(installRoot), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && DAY_FILE_RE.test(e.name))
+    .map((e) => e.name)
+    .sort();
+}
+
+// Read the live stream in chronological order (by day file, then append order within each),
+// optionally filtered by exact `type` and an inclusive ISO `since` (ISO-8601 sorts as text).
+export async function readEvents({ installRoot, since, type } = {}) {
+  const out = [];
+  for (const name of await listDayFiles(installRoot)) {
+    let content;
+    try {
+      content = await readFile(join(eventsDir(installRoot), name), 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let ev;
+      try {
+        ev = JSON.parse(trimmed);
+      } catch {
+        continue; // a torn/partial line never poisons a read
+      }
+      if (type && ev.type !== type) continue;
+      if (since && !(ev.ts >= since)) continue;
+      out.push(ev);
+    }
+  }
+  return out;
+}
+
+// --- Retention + purge (distinct verbs) --------------------------------------------------
+
+function isDateStamp(s) {
+  return typeof s === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(s);
+}
+
+async function archiveFile(installRoot, name) {
+  await fse.ensureDir(archiveDir(installRoot));
+  await fse.move(join(eventsDir(installRoot), name), join(archiveDir(installRoot), name), {
+    overwrite: true,
+  });
+}
+
+// The local day exactly `days` before `now`. A file is "older than retention" when its date
+// is strictly before this cutoff (a file dated exactly `days` ago is kept).
+function cutoffDateStamp(now, days) {
+  const d = new Date(now.getTime());
+  d.setDate(d.getDate() - days);
+  return localDateStamp(d);
+}
+
+// ARCHIVE files past the retention window to events/archive/ (event-log.md:19). The mechanism
+// only — AUTOMATIC scheduling is the daemon's job (T4.1); T4.0 ships an explicitly-invokable
+// verb so emit pays no rotation tax.
+export async function enforceRetention({ installRoot, retentionDays, now = new Date() } = {}) {
+  const days =
+    Number.isInteger(retentionDays) && retentionDays > 0
+      ? retentionDays
+      : (await readEventLogConfig(installRoot)).retentionDays;
+  const cutoff = cutoffDateStamp(now, days);
+  const archived = [];
+  for (const name of await listDayFiles(installRoot)) {
+    if (name.slice(0, 10) < cutoff) {
+      await archiveFile(installRoot, name);
+      archived.push(name);
+    }
+  }
+  return { archived, cutoff, retentionDays: days };
+}
+
+// DELETE day files before `before` (operator wipe / privacy, event-log.md:145). With
+// `archive` the files are moved to events/archive/ instead of removed. Distinct from
+// enforceRetention: purge is operator intent on an arbitrary boundary; rotate is the policy.
+export async function purgeEvents({ installRoot, before, archive = false } = {}) {
+  if (!isDateStamp(before)) {
+    throw new Error('purge requires --before YYYY-MM-DD');
+  }
+  const acted = [];
+  for (const name of await listDayFiles(installRoot)) {
+    if (name.slice(0, 10) < before) {
+      if (archive) await archiveFile(installRoot, name);
+      else await fse.remove(join(eventsDir(installRoot), name));
+      acted.push(name);
+    }
+  }
+  return { files: acted, archived: archive, before };
+}