@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/runtime/lifecycle/cli.ts

@@ -0,0 +1,276 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The `followup`, `lifecycle` and `goal` verb handlers (IC-006 to IC-009, IC-022). All work on the
+ * project store at the IC-001 root, so `-g` is refused with exit 2. `--json` prints the result
+ * object unmodified; exit 0 = answered or written, 1 = a refusal, 2 = usage. A refusal is returned
+ * by the service and printed here, never thrown, so it cannot reach failure capture (NFR-005).
+ */
+
+const { finishRuntime, usageError } = require('../cli-result.ts');
+const { projectRoot } = require('./root.ts');
+const followup = require('./followup.ts');
+const { StoreUnsafeError, StoreLockedError } = require('./event-store.ts');
+const { prepareStore } = require('./store-upkeep.ts');
+const { printSafe } = require('../mask.ts');
+const { buildOverview, initFeature, featureStatus } = require('./overview.ts');
+const { releaseFeatures, recordMerged } = require('./release.ts');
+const goal = require('./goal.ts');
+
+const FOLLOWUP_ACTIONS = ['add', 'list', 'take', 'settle', 'promote', 'report'];
+const LIFECYCLE_ACTIONS = ['overview', 'init', 'release', 'status', 'merged'];
+const GOAL_ACTIONS = ['add', 'item', 'check', 'link', 'list', 'done'];
+/** The flags each goal action takes, besides --goal, --channel and --json; any other one given is a usage error. */
+const GOAL_FLAGS: Record<string, any> = {
+  add: ['statement', 'item'], item: ['text'], check: ['item', 'evidence', 'unmet'],
+  link: ['slug', 'replace'], list: [], done: ['reason'],
+};
+
+function sourceText(source: any) {
+  return [source.kind, source.feature, source.taskClass, source.taskId, source.release, source.stage, source.ref].filter(Boolean).join(' ');
+}
+
+function followupLines(result: any) {
+  const lines = [];
+  switch (result.action) {
+    case 'add': for (const c of result.created) lines.push(`added ${c.id} (${sourceText(c.source)}): ${c.statement}`); break;
+    case 'list':
+      if (result.items.length === 0) lines.push(`No ${result.state === 'all' ? '' : `${result.state} `}follow-ups.`);
+      for (const i of result.items) lines.push(`${i.id}  ${i.state}${i.takenBy ? ` by ${i.takenBy}` : ''}${i.intent ? ` -> ${i.intent}` : ''}  (${sourceText(i.source)}, ${i.added})  ${i.statement}`);
+      break;
+    case 'take': lines.push(`${result.feature} took ${result.ids.join(', ')}`); break;
+    case 'settle': lines.push(`settled ${result.ids.join(', ')} as ${result.as}`); break;
+    case 'promote': lines.push(`created ${result.intent} from ${result.ids.join(', ')}`); break;
+    case 'report':
+      for (const c of result.created) lines.push(`reported ${c.id} (${sourceText(c.source)}): ${c.statement}`, `  body ${c.body} (${c.bodyBytes} bytes), excerpt ${c.excerptBytes} bytes, ${c.masked} value${c.masked === 1 ? '' : 's'} masked`);
+      for (const line of result.next) lines.push(`next: ${line}`);
+      break;
+    default: break;
+  }
+  return lines;
+}
+
+function overviewLines(r: any) {
+  const lines = [`${r.mode} overview: ${r.followups.open} open follow-up${r.followups.open === 1 ? '' : 's'}, ${r.followups.shown} shown (release mode ${r.releaseMode}${r.integrationRef ? `, integration ref ${r.integrationRef}` : ''})`];
+  for (const i of r.followups.items) lines.push(`  ${i.id}  (${sourceText(i.source)}, ${i.added})${i.promoted ? ` promoted to ${i.intent}` : ''}${i.pending === false ? ' settled this run' : ''}  ${i.statement}`);
+  if (Array.isArray(r.failures)) {
+    lines.push(`failures: ${r.failures.length} new or regressed`);
+    for (const f of r.failures) lines.push(`  ${f.fp}  ${f.status}  x${f.count}  ${f.command} ${f.kind}${f.message ? `: ${f.message}` : ''}  (last seen ${f.lastSeen}, ${f.lastVersion})`);
+  }
+  for (const g of r.goals) lines.push(`goal ${g.goal}: ${g.items.met}/${g.items.total} items met${g.proposeDone ? ' (propose done)' : ''}`, ...g.nudges.map((n: any) => `  ${n}`), ...(g.conflicts || []).map((c: any) => `  conflict: ${c.reason}${c.text ? ` (dropped text: ${JSON.stringify(c.text)})` : ''}`));
+  const f = r.features;
+  // The finished and awaiting-release lists only grow, so the text shows their bounded form.
+  const bounded = (key: any) => (r.featuresShown && r.featuresShown[key]) || { count: f[key].length, shown: f[key], more: 0 };
+  const names = [['finished', bounded('finished')], ['awaiting release', bounded('awaitingRelease')],
+    ['in progress', { count: f.inProgress.length, shown: f.inProgress, more: 0 }], ['unknown', { count: f.unknown.length, shown: f.unknown, more: 0 }]].filter(([, b]) => b.count);
+  for (const [label, b] of names) {
+    lines.push(`${label}: ${b.shown.join(', ')}${b.more ? ` (+${b.more} more; --json lists them all, lifecycle --action status --slug <slug> shows one)` : ''}`);
+  }
+  if (r.gitError) lines.push(`git unavailable (${r.gitError}): feature statuses are unknown`);
+  if (r.mode === 'maintain') lines.push(`pending: ${r.pending}`);
+  if (r.note) lines.push(`note: ${r.note}`);
+  if (r.conflicts.length) lines.push(`${r.conflicts.length} event conflict${r.conflicts.length === 1 ? '' : 's'} (see --json)`);
+  if (r.unreadable.length) lines.push(`unreadable event files: ${r.unreadable.map((n: any) => (r.unreadableReasons && r.unreadableReasons[n] ? `${n} (${r.unreadableReasons[n]})` : n)).join(', ')}`);
+  for (const line of r.next) lines.push(`next: ${line}`);
+  return lines;
+}
+
+function releaseLines(r: any) {
+  const lines = [`${r.recorded ? 'recorded' : 'preview of'} release ${r.tag} (previous ${r.previousTag || 'none'}, bound ${r.bound})`];
+  for (const c of r.candidates) if (!r.excluded.includes(c.slug)) lines.push(`  ships ${c.slug}  (${c.evidence}${c.ref ? ` ${c.ref}` : ''})`);
+  if (r.added.length) lines.push(`added: ${r.added.join(', ')}`);
+  if (r.excluded.length) lines.push(`excluded: ${r.excluded.join(', ')}`);
+  if (r.notDetected.length) lines.push(`not detected: ${r.notDetected.join(', ')}`);
+  if (r.followupsDone.length) lines.push(`follow-ups done: ${r.followupsDone.join(', ')}`);
+  if (r.note) lines.push(`note: ${r.note}`);
+  for (const line of r.next) lines.push(`next: ${line}`);
+  return lines;
+}
+
+function lifecycleLines(result: any) {
+  switch (result.action) {
+    case 'init': return [`${result.slug}: tracked ${result.tracked}${result.taken.length ? `, took ${result.taken.join(', ')}` : ''}${result.goal ? `, serves ${result.goal}` : ''}`, ...result.next];
+    case 'status': return [`${result.slug}: ${result.status}${result.evidence ? ` (${result.evidence.kind}${result.evidence.ref ? ` ${result.evidence.ref}` : ''})` : ''}${result.release ? `, release ${result.release}` : ''}`, ...(result.note ? [`note: ${result.note}`] : [])];
+    case 'release': return releaseLines(result);
+    case 'merged': return [`${result.slug}: merge confirmed, now ${result.status}`];
+    default: return result.mode ? overviewLines(result) : [];
+  }
+}
+
+function goalLines(r: any) {
+  const met = (g: any) => `${g.progress.met}/${g.progress.total} items met`;
+  switch (r.action) {
+    case 'add': return [`added goal ${r.goal}: ${r.outcome}`, ...r.items.map((i: any) => `  ${i.id}  ${i.text}`), ...r.next.map((n: any) => `next: ${n}`)];
+    case 'item': return [`added ${r.item.id} to ${r.goal}: ${r.item.text}`, ...r.next.map((n: any) => `next: ${n}`)];
+    case 'check': return [`${r.goal} ${r.item}: ${r.met ? 'met' : 'unmet'} (${r.evidence}); ${r.progress.met}/${r.progress.total} items met${r.proposeDone ? ' (propose done)' : ''}`, ...r.next.map((n: any) => `next: ${n}`)];
+    case 'link': return [r.linked === 'already' ? `${r.slug} already serves ${r.goal}` : `${r.slug} now serves ${r.goal}${r.replaced ? ` (was ${r.replaced})` : ''}`];
+    case 'done': return [`${r.goal} is done${r.unmet.length ? ` with ${r.unmet.join(', ')} unmet: ${r.reason}` : ''}`];
+    default: {
+      const lines = r.goals.length === 0 ? ['No goals.'] : [];
+      for (const g of r.goals) {
+        lines.push(`${g.goal}  ${g.status}  ${met(g)}${g.proposeDone ? ' (propose done)' : ''}  ${g.outcome}`);
+        for (const i of g.items) lines.push(`  ${i.id}  ${i.met ? 'met' : 'open'}  ${i.text}${i.evidence ? `  (${i.evidence})` : ''}`);
+        for (const [label, list] of [['finished', g.features.finished], ['awaiting release', g.features.awaitingRelease], ['in progress', g.features.inProgress], ['unknown', g.features.unknown]]) {
+          if (list.length) lines.push(`  ${label}: ${list.join(', ')}`);
+        }
+        for (const n of g.nudges) lines.push(`  ${n}`);
+        for (const c of g.conflicts || []) lines.push(`  conflict: ${c.reason}${c.text ? ` (dropped text: ${JSON.stringify(c.text)})` : ''}`);
+      }
+      if (r.reason) lines.push(`note: ${r.reason}`);
+      return [...lines, ...r.next.map((n: any) => `next: ${n}`)];
+    }
+  }
+}
+
+/** Prints a result and sets the exit status; shared by the verbs. */
+function emit(result: any, json: any, lines: any) {
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else if (result.ok === false) console.log(printSafe(`${result.finding}: ${result.message}`));
+  else for (const line of lines(result)) console.log(printSafe(line));
+  return finishRuntime(result.ok === false ? 1 : 0);
+}
+
+/** Runs `fn`, turning a caller mistake into the exit-2 usage result and a lock that never came into the `store-locked` refusal. */
+function guarded(verb: any, action: any, json: any, fn: any) {
+  try {
+    return fn();
+  } catch (error: any) {
+    if (error instanceof followup.FollowupUsageError || error instanceof StoreUnsafeError) return usageError(verb, error.message, json);
+    if (error instanceof StoreLockedError) return emit({ ok: false, action, finding: 'store-locked', message: error.message }, json, () => []);
+    throw error;
+  }
+}
+
+/** Runs the store upkeep for one invocation and prints its lines to stderr; returns its refusal, or null. */
+function upkeep(verb: any, action: any, root: any) {
+  const prepared = prepareStore(root);
+  for (const line of prepared.lines) console.error(printSafe(`doflow ${verb}: ${line}`));
+  return prepared.ok ? null : { ok: false, action, finding: prepared.finding, message: prepared.message };
+}
+
+function refuseGlobal(verb: any, global: any, json: any) {
+  return global ? usageError(verb, `${verb} works on the project store at the repository root and refuses -g`, json) : null;
+}
+
+/**
+ * `followup` verb. Actions: add, list, take, settle, promote, report.
+ * @param {Object} options
+ * @param {string} [options.action] absent when --action was not given
+ * @param {string} options.cwd directory the verb runs from (the project, or a subfolder of it)
+ * @param {Object} options.flags parsed flag values: statement, stage, source, taskClass, taskId, release,
+ *   batch, channel, state, ids, as, reason, evidence, title; for report also file, stdin, text, feature
+ */
+function handleFollowupCommand({ action, cwd, global = false, slug = null, json = false, flags = {} }: any = {}) {
+  const refused = refuseGlobal('followup', global, json);
+  if (refused !== null) return refused;
+  return guarded('followup', action, json, () => {
+    if (!FOLLOWUP_ACTIONS.includes(action)) throw new followup.FollowupUsageError(`--action is required: one of ${FOLLOWUP_ACTIONS.join(', ')} (got '${action}')`);
+    if (action !== 'report') {
+      for (const name of ['file', 'stdin', 'text', 'feature']) {
+        if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to --action report only`);
+      }
+    }
+    for (const name of ['tag', 'confirm', 'exclude']) {
+      if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to the lifecycle verb's --action release only, not to followup`);
+    }
+    const root = projectRoot(cwd || process.cwd());
+    const refusedStore = upkeep('followup', action, root);
+    if (refusedStore) return emit(refusedStore, json, followupLines);
+    let result;
+    if (action === 'report') {
+      if (flags.statement === undefined) throw new followup.FollowupUsageError('--statement is required for --action report');
+      result = followup.reportFollowup({
+        root, statement: flags.statement, input: { file: flags.file, stdin: Boolean(flags.stdin), text: flags.text },
+        release: flags.release, feature: flags.feature, channel: flags.channel,
+      });
+    } else if (action === 'add') {
+      const batch = flags.batch !== undefined;
+      if (batch && flags.statement !== undefined) throw new followup.FollowupUsageError('--batch cannot be combined with --statement');
+      if (!batch && flags.statement === undefined) throw new followup.FollowupUsageError('--statement is required for --action add (or pass --batch <file.json>)');
+      result = followup.addFollowups({
+        root, cwd: cwd || process.cwd(), channel: flags.channel,
+        items: batch ? followup.readBatchFile(flags.batch) : [{ statement: flags.statement }],
+        defaults: { stage: flags.stage, slug, source: flags.source, taskClass: flags.taskClass, taskId: flags.taskId, release: flags.release, batch },
+      });
+    } else if (action === 'list') {
+      result = followup.listFollowups({ root, state: flags.state });
+    } else if (action === 'take') {
+      result = followup.takeFollowups({ root, ids: flags.ids, slug, channel: flags.channel });
+    } else if (action === 'settle') {
+      result = followup.settleFollowups({ root, ids: flags.ids, as: flags.as, reason: flags.reason, evidence: flags.evidence, channel: flags.channel });
+    } else {
+      if (flags.title === undefined) throw new followup.FollowupUsageError('--title is required for --action promote');
+      result = followup.promoteFollowups({ root, ids: flags.ids, title: flags.title, channel: flags.channel });
+    }
+    return emit(result, json, followupLines);
+  });
+}
+
+/**
+ * `lifecycle` verb. Actions: overview, init, release, status, merged.
+ * @param {Object} options.flags parsed flag values: take, intent, goal, maintain, since, tag, confirm,
+ *   feature, exclude, reason, channel
+ */
+function handleLifecycleCommand({ action, cwd, global = false, slug = null, json = false, flags = {} }: any = {}) {
+  const refused = refuseGlobal('lifecycle', global, json);
+  if (refused !== null) return refused;
+  return guarded('lifecycle', action === undefined ? 'overview' : action, json, () => {
+    // The bare verb is the overview; the router passes no action unless --action was given.
+    const act = action === undefined ? 'overview' : action;
+    if (!LIFECYCLE_ACTIONS.includes(act)) throw new followup.FollowupUsageError(`--action is required: one of ${LIFECYCLE_ACTIONS.join(', ')} (got '${action}')`);
+    if (flags.maintain && act !== 'overview') throw new followup.FollowupUsageError('--maintain applies to --action overview only');
+    if (flags.since !== undefined && !flags.maintain) throw new followup.FollowupUsageError('--since applies to --action overview --maintain only');
+    if (act !== 'release') {
+      for (const name of ['tag', 'confirm', 'feature', 'exclude']) {
+        if (flags[name] !== undefined && flags[name] !== false) throw new followup.FollowupUsageError(`--${name} applies to --action release only`);
+      }
+    }
+    if (flags.reason !== undefined && act !== 'merged') throw new followup.FollowupUsageError('--reason applies to --action merged only');
+    const root = projectRoot(cwd || process.cwd());
+    const refusedStore = upkeep('lifecycle', act, root);
+    if (refusedStore) return emit(refusedStore, json, lifecycleLines);
+    let result;
+    if (act === 'overview') result = buildOverview({ root, maintain: Boolean(flags.maintain), since: flags.since });
+    else if (act === 'init') result = initFeature({ root, slug, take: flags.take, intent: flags.intent, goal: flags.goal });
+    else if (act === 'release') result = releaseFeatures({ root, tag: flags.tag, confirm: Boolean(flags.confirm), features: flags.feature, exclude: flags.exclude, channel: flags.channel });
+    else if (act === 'merged') result = recordMerged({ root, slug, reason: flags.reason, channel: flags.channel });
+    else result = featureStatus({ root, slug });
+    return emit(result, json, lifecycleLines);
+  });
+}
+
+/**
+ * `goal` verb. Actions: add, item, check, link, list, done.
+ * @param {Object} options.flags parsed flag values: goal, statement, item (a list), text, evidence, unmet,
+ *   replace, reason, channel; `--slug` arrives as `slug`
+ */
+function handleGoalCommand({ action, cwd, global = false, slug = null, json = false, flags = {} }: any = {}) {
+  const refused = refuseGlobal('goal', global, json);
+  if (refused !== null) return refused;
+  return guarded('goal', action, json, () => {
+    if (!GOAL_ACTIONS.includes(action)) throw new followup.FollowupUsageError(`--action is required: one of ${GOAL_ACTIONS.join(', ')} (got '${action}')`);
+    const given = { ...flags, slug: slug === null ? undefined : slug };
+    for (const name of ['statement', 'item', 'text', 'evidence', 'unmet', 'replace', 'reason', 'slug']) {
+      if (!GOAL_FLAGS[action].includes(name) && given[name] !== undefined && given[name] !== false) {
+        throw new followup.FollowupUsageError(`--${name} does not apply to --action ${action}`);
+      }
+    }
+    if (action !== 'list' && flags.goal === undefined) throw new followup.FollowupUsageError(`--goal is required for --action ${action}`);
+    const root = projectRoot(cwd || process.cwd());
+    const refusedStore = upkeep('goal', action, root);
+    if (refusedStore) return emit(refusedStore, json, goalLines);
+    const base = { root, goal: flags.goal };
+    let result;
+    if (action === 'add') result = goal.addGoal({ ...base, statement: flags.statement, items: flags.item, channel: flags.channel });
+    else if (action === 'item') result = goal.addItem({ ...base, text: flags.text, channel: flags.channel });
+    else if (action === 'check') result = goal.checkItem({ ...base, item: flags.item, evidence: flags.evidence, unmet: Boolean(flags.unmet), channel: flags.channel });
+    else if (action === 'link') result = goal.linkFeature({ ...base, slug, replace: Boolean(flags.replace), channel: flags.channel });
+    else if (action === 'done') result = goal.doneGoal({ ...base, reason: flags.reason, channel: flags.channel });
+    else result = goal.listGoals({ root, goal: flags.goal });
+    return emit(result, json, goalLines);
+  });
+}
+
+module.exports = { handleFollowupCommand, handleLifecycleCommand, handleGoalCommand, FOLLOWUP_ACTIONS, LIFECYCLE_ACTIONS, GOAL_ACTIONS };

package/src/runtime/lifecycle/event-store.ts

@@ -0,0 +1,340 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The project lifecycle event store (IC-001, IC-002, IC-003). One JSON file per event under
+ * `<root>/.doflow/state/lifecycle/events/`, created with an exclusive create, never edited or
+ * renamed, and deleted only by the retention pass. The store is local to a checkout, not shared through git. DoFlow never runs `git add`,
+ * `git commit` or `git push` on these paths and never writes an ignore rule for them (DEC-012).
+ *
+ * A write holds the store lock, folds what is there, refuses an event that would be illegal at the
+ * end of that fold (`illegal-transition`, nothing written) and stamps `at` as the later of the
+ * clock and one millisecond past the newest `at` it has seen, so a later event on one clone never
+ * sorts before one it has read.
+ */
+
+const nodeFs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { acquireLock } = require('../task-state.ts');
+const { printSafe } = require('../mask.ts');
+const { foldInto, finalize, applyEvent } = require('./fold.ts');
+
+const LIFECYCLE_REL = path.join('.doflow', 'state', 'lifecycle');
+const EVENTS_REL = path.join(LIFECYCLE_REL, 'events');
+/** The retention journal, beside the events folder and never inside it. */
+const JOURNAL_REL = path.join(LIFECYCLE_REL, 'retention.json');
+/** Lock-free reads tried while the journal's generation keeps moving, before one read under the lock. */
+const STABLE_READS = 3;
+/** The pause between those reads: the store lock's own wait. */
+const READ_WAIT_MS = 20;
+const ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz';
+/** `<UTC YYYYMMDDTHHMMSSmmmZ>-<6 lowercase Crockford base32 characters>`. */
+const EVENT_ID = /^[0-9]{8}T[0-9]{9}Z-[0-9a-hjkmnp-tv-z]{6}$/;
+const COLLISION_RETRIES = 5;
+/** The largest legitimate event is a goal with 100 items of 280 characters (about 30 KiB); a file over this is not one. */
+const MAX_EVENT_BYTES = 256 * 1024;
+/** The retention journal lists at most a pass's worth of names (store-upkeep.js bounds a pass well below this). */
+const MAX_JOURNAL_BYTES = 16 * 1024 * 1024;
+const READ_CHUNK = 64 * 1024;
+/** The decision register's channel vocabulary: who the caller says is acting. */
+const CHANNEL_BY: Record<string, string> = { question: 'user', gate: 'user', prompt: 'user', default: 'agent' };
+
+function eventsDir(root: string): string { return path.join(root, EVENTS_REL); }
+function lockTarget(root: string): string { return path.join(root, EVENTS_REL); }
+
+/** @param {string} [channel] defaults to `default` @returns {'user'|'agent'|null} null for an unknown channel */
+function byFromChannel(channel: string = 'default'): string | null { return CHANNEL_BY[channel] ?? null; }
+
+/** `length` random characters of the lowercase Crockford base32 alphabet. */
+function randomChars(length: number): string {
+  const bytes = crypto.randomBytes(length);
+  let out = '';
+  for (const b of bytes) out += ALPHABET[b % 32];
+  return out;
+}
+
+function idFor(at: string, random: (n: number) => string): string { return `${at.replace(/[-:.]/g, '')}-${random(6)}`; }
+
+/** Synchronous sleep without spinning, as the store lock waits. */
+function sleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** DEC-045: `at` is a strict UTC timestamp that is a real instant, so year 10000 and "+275760-..." never parse. */
+const STRICT_AT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function isStrictAt(at: any): boolean {
+  if (typeof at !== 'string' || !STRICT_AT.test(at)) return false;
+  const ms = Date.parse(at);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === at;
+}
+
+/** An IC-002 envelope whose `at` is strict and equals the time prefix of its file id. */
+function isEnvelope(event: any, idFromName: string): boolean {
+  return event && typeof event === 'object' && event.v === 1 && event.id === idFromName
+    && typeof event.type === 'string' && typeof event.by === 'string'
+    && isStrictAt(event.at) && idFromName.startsWith(`${event.at.replace(/[-:.]/g, '')}-`)
+    && event.data && typeof event.data === 'object' && !Array.isArray(event.data);
+}
+
+/** The store folders are the project's own: a symlink at either one could send a read or a write outside the repository. */
+class StoreUnsafeError extends Error {}
+
+/** The store lock could not be taken in time; the verb refuses with `store-locked` and writes nothing. */
+class StoreLockedError extends Error {}
+
+function assertStoreFolders(root: string, fsImpl: any): void {
+  for (const rel of [path.join('.doflow'), path.join('.doflow', 'state'), LIFECYCLE_REL, EVENTS_REL]) {
+    const folder = path.join(root, rel);
+    let link = false;
+    try { link = fsImpl.lstatSync(folder).isSymbolicLink(); } catch { /* absent: nothing to follow */ }
+    if (link) throw new StoreUnsafeError(`${folder} is a symbolic link; the lifecycle store is never read or written through one`);
+  }
+}
+
+/**
+ * One store file's text, or `{reason}` when it must not be read: not a regular file (a symlink, a
+ * FIFO, a device, a folder), larger than `maxBytes`, or gone. A symlink is refused by `lstat`
+ * and again by `O_NOFOLLOW` where the platform has it; `O_NONBLOCK` keeps a FIFO swapped in after
+ * the `lstat` from blocking the open, and the descriptor is checked again before any read.
+ */
+function readEventFile(fsImpl: any, file: string, maxBytes: number = MAX_EVENT_BYTES): { reason?: string; text?: string } {
+  const flags = nodeFs.constants;
+  let fd: number | undefined;
+  try {
+    if (!fsImpl.lstatSync(file).isFile()) return { reason: 'not a regular file' };
+    fd = fsImpl.openSync(file, flags.O_RDONLY | (flags.O_NOFOLLOW || 0) | (flags.O_NONBLOCK || 0));
+    const st = fsImpl.fstatSync(fd);
+    if (!st.isFile()) return { reason: 'not a regular file' };
+    const tooLarge = { reason: `larger than ${maxBytes / 1024} KiB` };
+    if (st.size > maxBytes) return tooLarge;
+    // Read in chunks up to one byte past the cap, so a file that grew after the fstat is still caught.
+    const chunks: Buffer[] = [];
+    let length = 0;
+    while (length <= maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(READ_CHUNK, maxBytes + 1 - length));
+      const n = fsImpl.readSync(fd, chunk, 0, chunk.length, null);
+      if (n === 0) break;
+      chunks.push(chunk.subarray(0, n));
+      length += n;
+    }
+    return length > maxBytes ? tooLarge : { text: Buffer.concat(chunks, length).toString('utf8') };
+  } catch (error: any) {
+    return { reason: error.code || 'unreadable' };
+  } finally {
+    if (fd !== undefined) { try { fsImpl.closeSync(fd); } catch { /* read already done */ } }
+  }
+}
+
+/** The event with every string print-safe; a report excerpt is multi-line by design, so it keeps its line breaks (cli.js removes them when printing). */
+function cleanEvent(event: any): any {
+  const clean = printSafe(event);
+  if (typeof event.data.excerpt === 'string') clean.data.excerpt = printSafe(event.data.excerpt, { keepLineBreaks: true });
+  return clean;
+}
+
+/** Whether `name` is `<EVENT_ID>.json`. */
+function isEventName(name: string): boolean {
+  const match = /^(.+)\.json$/.exec(name);
+  return Boolean(match) && EVENT_ID.test((match as RegExpExecArray)[1]);
+}
+
+/**
+ * The retention journal: the files a retention pass is deleting, and a token that changes on every
+ * write. Absent, unreadable, unparseable or of another version reads as no generation and nothing
+ * pending; a pending name that is not an event file name is ignored.
+ * @returns {{generation: string|null, pending: string[]}}
+ */
+function readJournal(root: string, fsImpl: any = nodeFs): { generation: string | null; pending: string[] } {
+  const read = readEventFile(fsImpl, path.join(root, JOURNAL_REL), MAX_JOURNAL_BYTES);
+  let journal: any;
+  try { journal = read.reason ? null : JSON.parse(read.text as string); } catch { journal = null; }
+  if (!journal || typeof journal !== 'object' || journal.v !== 1) return { generation: null, pending: [] };
+  return {
+    generation: typeof journal.generation === 'string' ? journal.generation : null,
+    pending: Array.isArray(journal.pending) ? journal.pending.filter((name: any) => typeof name === 'string' && isEventName(name)) : [],
+  };
+}
+
+/** One pass over the event files, leaving out the names in `hidden`. */
+function readEventFiles(root: string, fsImpl: any, hidden: Set<string>, shouldStop?: () => boolean): any {
+  const dir = eventsDir(root);
+  let names: string[];
+  try {
+    names = fsImpl.readdirSync(dir);
+  } catch (error: any) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return { events: [], unreadable: [], reasons: {} };
+    throw error;
+  }
+  const orderedNames = names.sort();
+  if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+  const events: any[] = [];
+  const unreadable: string[] = [];
+  const reasons: Record<string, string> = {};
+  for (const name of orderedNames) {
+    if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+    if (!isEventName(name) || hidden.has(name)) continue;
+    const read = readEventFile(fsImpl, path.join(dir, name));
+    if (read.reason) { unreadable.push(name); reasons[name] = read.reason; continue; }
+    try {
+      const event = JSON.parse(read.text as string);
+      // Someone else's file is shown as it is read, so its text is made print-safe here (stored bytes are not changed).
+      if (isEnvelope(event, name.slice(0, -'.json'.length))) events.push(cleanEvent(event)); else unreadable.push(name);
+    } catch {
+      unreadable.push(name);
+    }
+  }
+  if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+  return { events, unreadable, reasons };
+}
+
+/**
+ * Reads every event file. A missing folder is an empty store; a file whose name is not an event id
+ * is ignored; a matching entry that is not a regular file of at most MAX_EVENT_BYTES, or is not an
+ * IC-002 envelope (including one still being written), is skipped and named in `unreadable`, with
+ * the reason in `reasons[name]` when it is not simply a corrupt file. A symlinked store folder
+ * throws StoreUnsafeError.
+ *
+ * Files the retention journal lists as pending are neither events nor unreadable, so an item a
+ * retention pass is removing is seen whole or not at all. When the journal's generation moves
+ * during a read, the read is repeated, at most STABLE_READS times, and then done once under the
+ * store lock, which every journal writer holds. A caller already holding the lock never sees the
+ * generation move, so it returns after the first read. A lock that cannot be taken throws
+ * StoreLockedError.
+ * @returns {{events: Object[], unreadable: string[], reasons: Object<string,string>, incomplete?: true}}
+ */
+function readEvents(root: string, { fsImpl = nodeFs, lockFallback = true, shouldStop }: any = {}): any {
+  assertStoreFolders(root, fsImpl);
+  if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+  for (let attempt = 1; attempt <= STABLE_READS; attempt += 1) {
+    if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+    const before = readJournal(root, fsImpl);
+    if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+    const result = readEventFiles(root, fsImpl, new Set(before.pending), shouldStop);
+    if (result.incomplete || shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+    const after = readJournal(root, fsImpl);
+    if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+    if (after.generation === before.generation) return result;
+    if (attempt < STABLE_READS && !shouldStop?.()) sleep(READ_WAIT_MS);
+  }
+  if (shouldStop?.()) return { events: [], unreadable: [], reasons: {}, incomplete: true };
+  if (!lockFallback) throw new StoreLockedError('Lifecycle event store changed during a read; a stable snapshot was unavailable.');
+  let release: () => void;
+  try {
+    release = acquireLock(fsImpl, lockTarget(root));
+  } catch (error: any) {
+    if (/^Could not lock/.test(error.message || '')) throw new StoreLockedError(`${error.message} Nothing was written.`);
+    throw error;
+  }
+  try {
+    return readEventFiles(root, fsImpl, new Set(readJournal(root, fsImpl).pending), shouldStop);
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Reads and folds the store.
+ * @param {string} root the IC-001 root
+ * @param {{hasBody?: Function, fsImpl?: Object}} [options]
+ * @returns {Object} the fold result (see fold.js) plus `unreadable`
+ */
+function readFold(root: string, { fsImpl = nodeFs, hasBody, now = new Date() }: any = {}): any {
+  const { events, unreadable, reasons } = readEvents(root, { fsImpl });
+  return { ...finalize(foldInto(events, { now }), { hasBody }), unreadable, unreadableReasons: reasons };
+}
+
+/** Picks a free, valid id for each draft before any file is created, so a batch is all or nothing. */
+function allocateIds(fsImpl: any, dir: string, stamped: any[], random: (n: number) => string): string[] | null {
+  const chosen = new Set<string>();
+  const ids: string[] = [];
+  for (const { at, id } of stamped) {
+    let candidate: string | null = id;
+    for (let attempt = 0; attempt <= COLLISION_RETRIES; attempt += 1) {
+      if (attempt > 0) candidate = idFor(at, random);
+      if (EVENT_ID.test(candidate as string) && !chosen.has(candidate as string) && !fsImpl.existsSync(path.join(dir, `${candidate}.json`))) break;
+      candidate = null;
+    }
+    if (!candidate) return null;
+    chosen.add(candidate);
+    ids.push(candidate);
+  }
+  return ids;
+}
+
+/**
+ * Appends events. All are checked against the local fold first; one illegal event refuses the whole
+ * call and nothing is written.
+ *
+ * @param {string} root the IC-001 root
+ * @param {Array<{type:string, by:'user'|'agent', data:Object}>} drafts
+ * @param {{now?: Date, fsImpl?: Object, random?: (n:number)=>string}} [options]
+ * @returns {{ok:true, written: Array<{id:string, file:string, event:Object}>}
+ *   | {ok:false, finding:string, message:string, conflict?:Object, written?: Array}}
+ *   `file` is root-relative with `/` separators. The findings are `illegal-transition` (any fold
+ *   conflict, with its own `code` in `conflict.code`), `id-collision`, `invalid-id` (the clock or
+ *   the random source cannot produce an id of the IC-001 shape) and `store-locked`.
+ */
+function appendEvents(root: string, drafts: any[], { now = new Date(), fsImpl = nodeFs, random = randomChars }: any = {}): any {
+  const dir = eventsDir(root);
+  // A write that would be refused leaves nothing behind, not even the store folder (IC-001: created
+  // on the first write), so the check runs once before the folder and the lock and again under the lock.
+  const early = planEvents(root, drafts, { now, fsImpl, random });
+  if (early.refused) return early.refused;
+  fsImpl.mkdirSync(dir, { recursive: true });
+  let release: () => void;
+  try {
+    release = acquireLock(fsImpl, lockTarget(root));
+  } catch (error: any) {
+    if (/^Could not lock/.test(error.message || '')) return { ok: false, finding: 'store-locked', message: `${error.message} Nothing was written.` };
+    throw error;
+  }
+  try {
+    const { stamped, refused } = planEvents(root, drafts, { now, fsImpl, random });
+    if (refused) return refused;
+    const ids = allocateIds(fsImpl, dir, stamped, random);
+    if (!ids) return { ok: false, finding: 'id-collision', written: [], message: `could not find a free event id after ${COLLISION_RETRIES} tries. Nothing was written.` };
+    const written: any[] = [];
+    stamped.forEach(({ draft, at }: any, index: number) => {
+      const event = { v: 1, id: ids[index], type: draft.type, at, by: draft.by, data: draft.data };
+      const file = path.join(dir, `${event.id}.json`);
+      // The ids are free under the lock; the exclusive create only guards against a writer outside it.
+      fsImpl.writeFileSync(file, `${JSON.stringify(event, null, 2)}\n`, { encoding: 'utf8', flag: 'wx' });
+      written.push({ id: event.id, file: path.relative(root, file).split(path.sep).join('/'), event });
+    });
+    return { ok: true, written };
+  } finally {
+    release();
+  }
+}
+
+/** Folds the store, stamps each draft and applies it; `refused` is the whole call's refusal when any is illegal. */
+function planEvents(root: string, drafts: any[], { now, fsImpl, random }: any): any {
+  const state = foldInto(readEvents(root, { fsImpl }).events, { now });
+  // An event dated far ahead is not in the fold (DEC-045), so it cannot push this stamp forward.
+  let floor = state.newestAt === null ? -Infinity : state.newestAt + 1;
+  const stamped: any[] = [];
+  for (const draft of drafts) {
+    const atMs = Math.max(now.getTime(), floor);
+    floor = atMs + 1;
+    let at: string | null;
+    try { at = new Date(atMs).toISOString(); } catch { at = null; }
+    // The dry run draws the id the write will try first, so a conflict names the event it refuses.
+    const id = at && isStrictAt(at) ? idFor(at, random) : null;
+    if (!id || !EVENT_ID.test(id)) {
+      return { refused: { ok: false, finding: 'invalid-id', message: 'cannot build an event id of the form <UTC time>-<6 base32 characters> from the clock and the random source. Nothing was written.' } };
+    }
+    const raised = applyEvent(state, { v: 1, id, type: draft.type, at, by: draft.by, data: draft.data }, { checkFuture: false });
+    if (raised.length) {
+      return { refused: { ok: false, finding: 'illegal-transition', conflict: raised[0], message: `${raised[0].reason}. Nothing was written.` } };
+    }
+    stamped.push({ draft, at, id });
+  }
+  return { stamped };
+}
+
+module.exports = {
+  appendEvents, readEvents, readFold, byFromChannel, randomChars, StoreUnsafeError, StoreLockedError, MAX_EVENT_BYTES,
+  EVENT_ID, EVENTS_REL, LIFECYCLE_REL, JOURNAL_REL, ALPHABET, COLLISION_RETRIES, lockTarget, readJournal, isEventName,
+};