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

package/src/runtime/storage/registry.js

@@ -0,0 +1,130 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT_BASES = new Set(['project', 'home', 'xdg-config']);
+const ENTRIES = new Set(['file', 'dir', 'record']);
+const RULES                        = new Map([
+  ['count-and-age', ['keepNewest', 'maxAgeDays']],
+  ['work', ['finishedDays']],
+  ['date-partition', ['maxAgeDays']],
+  ['recovery', ['keepNewest']],
+  ['lifecycle-settled', ['defaultHours']],
+  ['report-orphan', ['orphanGraceHours', 'foreignMaxAgeDays']],
+  ['age', ['maxAgeDays']],
+  ['existing', []],
+  ['control', []],
+]);
+const MOMENTS = new Set(['verb', 'session', 'verify', 'install', 'lifecycle-verb', 'uninstall']);
+const STORE_ID = /^[a-z][a-z0-9-]*$/;
+
+function isObject(value     )          { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+function positiveInteger(value     )          { return Number.isInteger(value) && value > 0; }
+function error(errors          , where        , message        )       { errors.push(`${where}: ${message}`); }
+
+/** Validates the closed IC-001 storage declaration document without touching the filesystem. */
+function validateStorageRegistry(registry     )                                    {
+  const errors           = [];
+  if (!isObject(registry)) return { ok: false, errors: ['registry: must be an object'] };
+  if (registry.version !== 1) error(errors, 'version', 'must be 1');
+  if (typeof registry.description !== 'string' || !registry.description.trim()) error(errors, 'description', 'must be a non-empty string');
+  const settings = registry.settings;
+  if (!isObject(settings)) error(errors, 'settings', 'must be an object');
+  else {
+    if (settings.optOutFile !== 'prune') error(errors, 'settings.optOutFile', 'must be prune');
+    for (const field of ['upkeepIntervalHours', 'passBudgetMs', 'maxRemovalsPerPass', 'passLockStaleSeconds', 'orphanGraceHours', 'staleTmpHours']) {
+      if (!positiveInteger(settings[field])) error(errors, `settings.${field}`, 'must be a positive integer');
+    }
+    if (!isObject(settings.ignoreFile) || settings.ignoreFile.name !== '.gitignore'
+      || !Array.isArray(settings.ignoreFile.lines) || settings.ignoreFile.lines.some((line     ) => typeof line !== 'string')) {
+      error(errors, 'settings.ignoreFile', 'must name .gitignore and contain string lines');
+    }
+  }
+  const roots = registry.roots;
+  if (!isObject(roots) || Object.keys(roots).length === 0) error(errors, 'roots', 'must be a non-empty object');
+  else for (const [id, root] of Object.entries(roots)                   ) {
+    if (!isObject(root) || !ROOT_BASES.has(root.base) || !Array.isArray(root.segments)
+      || root.segments.some((segment     ) => typeof segment !== 'string' || !segment || segment === '.' || segment === '..' || segment.includes('/') || segment.includes('\\'))) {
+      error(errors, `roots.${id}`, 'must have a known base and safe path segments');
+    }
+  }
+  if (!Array.isArray(registry.stores)) error(errors, 'stores', 'must be an array');
+  else {
+    const ids = new Set();
+    registry.stores.forEach((store     , index        ) => {
+      const where = `stores[${index}]`;
+      if (!isObject(store)) { error(errors, where, 'must be an object'); return; }
+      if (typeof store.id !== 'string' || !STORE_ID.test(store.id)) error(errors, `${where}.id`, 'must match ^[a-z][a-z0-9-]*$');
+      else if (ids.has(store.id)) error(errors, `${where}.id`, `duplicate id '${store.id}'`); else ids.add(store.id);
+      if (typeof store.root !== 'string' || !roots?.[store.root]) error(errors, `${where}.root`, 'must name a declared root');
+      if (typeof store.path !== 'string' || store.path.startsWith('/') || store.path.split('/').some((part        ) => part === '..' || !part && store.path !== '')) error(errors, `${where}.path`, 'must be relative, slash-separated, and contain no ..');
+      if (!ENTRIES.has(store.entry)) error(errors, `${where}.entry`, 'must be file, dir, or record');
+      if (typeof store.match !== 'string' || !store.match.startsWith('^') || !store.match.endsWith('$')) error(errors, `${where}.match`, 'must be an anchored regular expression');
+      else { try { new RegExp(store.match); } catch { error(errors, `${where}.match`, 'must compile'); } }
+      if (!RULES.has(store.rule)) error(errors, `${where}.rule`, 'must name a known rule kind');
+      if (!isObject(store.bound)) error(errors, `${where}.bound`, 'must be an object');
+      else {
+        for (const field of RULES.get(store.rule) || []) if (!positiveInteger(store.bound[field])) error(errors, `${where}.bound.${field}`, 'must be a positive integer');
+        if (['existing', 'control'].includes(store.rule) && (typeof store.bound.text !== 'string' || !store.bound.text)) error(errors, `${where}.bound.text`, 'must be a non-empty string');
+        if (store.rule === 'existing' && store.bound.value !== undefined && !positiveInteger(store.bound.value)) error(errors, `${where}.bound.value`, 'must be a positive integer when present');
+      }
+      if (store.protect !== null && store.protect !== 'open-work') error(errors, `${where}.protect`, 'must be open-work or null');
+      if (!Array.isArray(store.moments) || store.moments.some((moment     ) => !MOMENTS.has(moment)) || new Set(store.moments).size !== store.moments.length) error(errors, `${where}.moments`, 'must be a unique subset of known moments');
+      if (store.rule === 'existing' && store.moments?.length) error(errors, `${where}.moments`, 'must be empty for existing stores');
+      if (!Array.isArray(store.writers) || store.writers.some((writer     ) => typeof writer !== 'string' || !writer)) error(errors, `${where}.writers`, 'must be an array of repository-relative paths');
+      else if (!store.writers.length && store.rule !== 'control' && !store.id.startsWith('user-settings-')) error(errors, `${where}.writers`, 'may be empty only for control or user-settings stores');
+      if (store.rule === 'existing') {
+        if (!isObject(store.source) || typeof store.source.file !== 'string' || !store.source.file
+          || typeof store.source.pattern !== 'string' || !store.source.pattern) {
+          error(errors, `${where}.source`, 'requires a non-empty file and literal or template pattern');
+        } else if (store.source.pattern.includes('{value}') && !positiveInteger(store.bound?.value)) {
+          error(errors, `${where}.bound.value`, 'must be a positive integer for a {value} source pattern');
+        }
+      }
+    });
+  }
+  if (!Array.isArray(registry.externalWriters)) error(errors, 'externalWriters', 'must be an array');
+  else registry.externalWriters.forEach((writer     , index        ) => {
+    if (!isObject(writer) || typeof writer.file !== 'string' || !writer.file || typeof writer.reason !== 'string' || !writer.reason.trim()) error(errors, `externalWriters[${index}]`, 'requires a file and non-empty reason');
+  });
+  return { ok: errors.length === 0, errors };
+}
+
+/** Loads and fails closed on an IC-001 storage registry. */
+function loadStorageRegistry({ repoRoot, file, fsImpl = fs }      = {})      {
+  const target = file || path.join(path.resolve(repoRoot || process.cwd()), 'core', 'registry', 'storage.json');
+  let registry     ;
+  try { registry = JSON.parse(fsImpl.readFileSync(target, 'utf8')); } catch (cause     ) { throw new Error(`Could not load storage registry '${target}': ${cause.message}`); }
+  const validation = validateStorageRegistry(registry);
+  if (!validation.ok) throw new Error(`Invalid storage registry:\n- ${validation.errors.join('\n- ')}`);
+  return registry;
+}
+
+/** Renders IC-001's canonical human-readable bound for a store. */
+/** Renders an existing-store source pattern for G26's literal source check. */
+function renderSourcePattern(store     )         {
+  const pattern = store?.source?.pattern;
+  if (typeof pattern !== 'string') throw new Error('Existing store has no source pattern');
+  return pattern.includes('{value}') ? pattern.replaceAll('{value}', String(store.bound.value)) : pattern;
+}
+
+function formatBound(store     )         {
+  const bound = store.bound;
+  switch (store.rule) {
+    case 'count-and-age': return `keep newest ${bound.keepNewest}; prune entries older than ${bound.maxAgeDays} days`;
+    case 'work': return `prune finished work after ${bound.finishedDays} days`;
+    case 'date-partition': return `prune partitions older than ${bound.maxAgeDays} days`;
+    case 'recovery': return `keep newest ${bound.keepNewest}, plus the snapshot named by the ledger`;
+    case 'lifecycle-settled': return `retain settled events for ${bound.defaultHours} hours`;
+    case 'report-orphan': return `prune orphan bodies after ${bound.orphanGraceHours} hours; foreign folders after ${bound.foreignMaxAgeDays} days`;
+    case 'age': return `prune inactive directories after ${bound.maxAgeDays} days`;
+    case 'existing':
+    case 'control': return bound.text;
+    default: throw new Error(`Unknown storage rule '${store.rule}'`);
+  }
+}
+
+module.exports = { loadStorageRegistry, validateStorageRegistry, renderSourcePattern, formatBound, RULES };

package/src/runtime/storage/roots.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function absolute(value     )                { return typeof value === 'string' && path.isAbsolute(value) ? value : null; }
+
+/** Resolves IC-001's five physical roots; -g/global deliberately omits project roots. */
+function resolveRoots({ registry, projectRoot, global = false, env = process.env }      = {})                                {
+  const home = absolute(env.HOME) || os.homedir();
+  const xdgBase = env.XDG_CONFIG_HOME === undefined || env.XDG_CONFIG_HOME === ''
+    ? path.join(home, '.config') : absolute(env.XDG_CONFIG_HOME);
+  const project = global ? null : absolute(projectRoot);
+  const bases                                = { project, home, 'xdg-config': xdgBase };
+  return Object.fromEntries(Object.entries(registry.roots).map(([id, root]               ) => {
+    const base = bases[root.base];
+    return [id, base ? path.join(base, ...root.segments) : null];
+  }));
+}
+
+function readSetting(file        , fsImpl     )         {
+  try {
+    const first = fsImpl.readFileSync(file, 'utf8').split(/\r?\n/, 1)[0].trim().toLowerCase();
+    return first === 'on' || first === 'off' ? first : 'off';
+  } catch { return 'off'; }
+}
+
+/** Reads IC-014 and reports exactly which present file made the decision, if any. */
+function readPruneSetting({ registry, roots, rootId, fsImpl = fs }      = {})                                                {
+  const projectFile = roots['project-doflow'] ? path.join(roots['project-doflow'], registry.settings.optOutFile) : null;
+  const userFile = roots['config-home'] ? path.join(roots['config-home'], registry.settings.optOutFile) : null;
+  const usesProject = rootId === 'project-doflow' || rootId === 'project-state';
+  if (usesProject && projectFile && fsImpl.existsSync(projectFile)) return { setting: readSetting(projectFile, fsImpl), decidedBy: projectFile };
+  if (userFile && fsImpl.existsSync(userFile)) return { setting: readSetting(userFile, fsImpl), decidedBy: userFile };
+  return { setting: 'on', decidedBy: null };
+}
+
+function linked(file        , fsImpl     )          {
+  try { return fsImpl.lstatSync(file).isSymbolicLink(); } catch { return false; }
+}
+
+/**
+ * Returns the physical directory for a declared store, or null when a DoFlow-owned component is a
+ * link. The engine treats null as a refuse-to-touch result, never as a path to repair.
+ */
+function resolveStorePath({ store, roots, fsImpl = fs }      = {})                {
+  const root = roots[store.root];
+  if (!root) return null;
+  if (linked(root, fsImpl)) return null;
+  const rootParent = path.dirname(root);
+  if (path.basename(rootParent) === '.doflow' && linked(rootParent, fsImpl)) return null;
+  let current = root;
+  for (const segment of store.path ? store.path.split('/') : []) {
+    current = path.join(current, segment);
+    if (linked(current, fsImpl)) return null;
+  }
+  return current;
+}
+
+module.exports = { resolveRoots, readPruneSetting, resolveStorePath };

package/src/runtime/storage/rules.js

@@ -0,0 +1,282 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { workStatus, createWorkCache, refreshedWorkCache } = require('./work-status.js');
+const { projectKey } = require('../lifecycle/report-store.js');
+const { readEvents } = require('../lifecycle/event-store.js');
+
+const DAY = 86400000;
+const HOUR = 3600000;
+const BODY = /^FU-[0-9a-hjkmnp-tv-z]{6}\.txt$/;
+const LOG = /[0-9]{13}-[A-Za-z0-9._-]+\.log/g;
+const TMP = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json\.[0-9]+\.tmp$/;
+const ruleOrder = ['verification-logs', 'task-evidence', 'task-readiness', 'task-research', 'task-outcome', 'task-retrieval', 'task-attempts', 'task-orchestration', 'runs-project', 'runs-user', 'advice-picks-project', 'advice-picks-user', 'lifecycle-events', 'report-bodies', 'session-dirs', 'project-dirs', 'recovery-user', 'recovery-project'];
+const removableRules = new Set(['count-and-age','work','date-partition','recovery','lifecycle-settled','report-orphan','age']);
+const SAFE_NAMESPACE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// Open-log protection cannot vouch for a record store that holds a link, so the pass fails closed.
+const LINKED = 'link-in-record-store';
+function stopped(context     ) { return Boolean(context.shouldStop?.()); }
+function budgetError() { return Object.assign(new Error('storage pass budget exhausted'), { code: 'EBUDGET', partial: true }); }
+function projectRoot(roots     ) { return roots['project-state'] ? path.dirname(path.dirname(roots['project-state'])) : null; }
+function safeStat(fsImpl     , file     ) { try { return fsImpl.lstatSync(file); } catch { return null; } }
+function names(fsImpl     , dir     ) { return fsImpl.readdirSync(dir); }
+function ageReason(store     , entry     , now     , fsImpl     , storeDir     , shouldStop     ) {
+  const limit = store.bound.maxAgeDays * DAY;
+  if (store.rule === 'date-partition') {
+    const date = entry.name.slice(0, 10);
+    const time = Date.parse(`${date}T00:00:00Z`);
+    if (!Number.isFinite(time) || new Date(time).toISOString().slice(0,10) !== date) return null;
+    const cutoff = new Date(now - limit).toISOString().slice(0,10);
+    return date < cutoff ? 'age' : null;
+  }
+  let newest = entry.stat.mtimeMs;
+  if (store.rule === 'age') {
+    try {
+      for (const child of names(fsImpl, path.join(storeDir, entry.name))) {
+        if (shouldStop?.()) return null;
+        const st = safeStat(fsImpl, path.join(storeDir, entry.name, child));
+        if (!st || st.isSymbolicLink()) return null;
+        newest = Math.max(newest, st.mtimeMs);
+      }
+    } catch { return null; }
+  }
+  return now - newest > limit ? 'age' : null;
+}
+function workCandidates(store     , entries     , context     ) {
+  const { fsImpl, storeDir, now, roots, settings, shouldStop } = context;
+  const project = projectRoot(roots);
+  if (!project) return [];
+  const cache = context.cache || createWorkCache({ projectRoot: project, fsImpl });
+  const recordMatch = new RegExp(store.match), selected        = [];
+  const visit = (dir     , namespace      = null) => {
+    let children;
+    try { children = names(fsImpl, dir); } catch { return true; }
+    for (const name of children) {
+      if (shouldStop?.()) return false;
+      const file = path.join(dir, name), stat = safeStat(fsImpl, file);
+      if (!stat || !stat.isFile()) continue;
+      if (TMP.test(name) && now - stat.mtimeMs > settings.staleTmpHours * HOUR) {
+        selected.push({ name: namespace ? `${namespace}/${name}` : name, reason: 'stale-tmp', bytes: stat.size, mtimeMs: stat.mtimeMs, recordStat: stat });
+      } else if (recordMatch.test(name)) {
+        const result = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: stat.mtimeMs, cache, fsImpl, shouldStop });
+        if (result.incomplete || shouldStop?.()) return false;
+        if (result.state === 'finished' && now - result.since > store.bound.finishedDays * DAY)
+          selected.push({ name: namespace ? `${namespace}/${name}` : name, reason: 'finished-work', bytes: stat.size, mtimeMs: result.since, recordStat: stat });
+      }
+    }
+    return true;
+  };
+  if (!visit(storeDir)) return null;
+  for (const entry of entries) {
+    if (shouldStop?.()) return null;
+    if (entry.stat.isDirectory() && !visit(path.join(storeDir, entry.name), entry.name)) return null;
+  }
+  return selected;
+}
+/** Revalidate the subject under its try-lock against its current run and plan, not the selection snapshot. */
+function recordStillCandidate(store     , candidate     , info     , context     ) {
+  const { fsImpl, roots, now, settings, cache, shouldStop, storeDir } = context;
+  const before = candidate.recordStat;
+  if (!info.isFile() || !before || ['mtimeMs', 'ctimeMs', 'size', 'ino', 'dev'].some(key => info[key] !== before[key])) return false;
+  if (candidate.reason === 'stale-tmp') return now - info.mtimeMs > settings.staleTmpHours * HOUR;
+  const parts = candidate.name.split('/'), name = parts.at(-1), namespace = parts.length === 2 ? parts[0] : null;
+  // workStatus reuses an orchestration record's parsed run. Re-read that subject here and reject
+  // changes rather than mutating the snapshot used by the run's other records.
+  if (store.id === 'task-orchestration' && !namespace && !name.endsWith('_claims.json')) {
+    let current;
+    try { current = JSON.parse(fsImpl.readFileSync(path.join(storeDir, name), 'utf8')); } catch { return false; }
+    const snapshot = cache?.runs.get(name.slice(0, -5));
+    if (!snapshot?.ok || JSON.stringify(current) !== JSON.stringify(snapshot.value)) return false;
+  }
+  const fresh = cache ? refreshedWorkCache(cache) : undefined;
+  const status = workStatus({ projectRoot: projectRoot(roots), store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: info.mtimeMs, cache: fresh, fsImpl, shouldStop });
+  return !status.incomplete && !shouldStop?.() && status.state === 'finished'
+    && status.since === candidate.mtimeMs && now - status.since > store.bound.finishedDays * DAY;
+}
+function workStorePathStatus(store     , roots     , fsImpl     ) {
+  const project = projectRoot(roots), root = roots[store.root];
+  if (!project || !root) return 'missing';
+  const paths = [path.join(project, '.doflow'), root];
+  let current = root;
+  for (const segment of store.path.split('/')) { current = path.join(current, segment); paths.push(current); }
+  for (const candidate of paths) {
+    let info;
+    try { info = fsImpl.lstatSync(candidate); }
+    catch (error     ) { return error.code === 'ENOENT' || error.code === 'ENOTDIR' ? 'missing' : 'inaccessible'; }
+    if (info.isSymbolicLink()) return 'linked';
+  }
+  return 'safe';
+}
+function protectedLogs({ registry, roots, fsImpl, cache, shouldStop }     ) {
+  const project = projectRoot(roots), protectedNames = new Set();
+  if (!project) return { names: protectedNames, incomplete: false };
+  const workCache = cache || createWorkCache({ projectRoot: project, fsImpl });
+  for (const store of registry.stores.filter((s     ) => s.root === 'project-state' && s.entry === 'record' && s.rule === 'work')) {
+    if (shouldStop?.()) return { names: protectedNames, incomplete: true };
+    const pathStatus = workStorePathStatus(store, roots, fsImpl);
+    if (pathStatus === 'missing') continue;
+    if (pathStatus !== 'safe') return { names: protectedNames, incomplete: true, ...(pathStatus === 'linked' ? { reason: LINKED } : {}) };
+    const dir = path.join(roots[store.root], ...store.path.split('/'));
+    const recordMatch = new RegExp(store.match);
+    let linked = false;
+    const visit = (folder     , namespace      = null) => {
+      let list;
+      try { list = names(fsImpl, folder); }
+      catch (error     ) { return error.code === 'ENOENT' || error.code === 'ENOTDIR'; }
+      for (const name of list) {
+        if (shouldStop?.()) return false;
+        const file = path.join(folder, name);
+        let stat;
+        try { stat = fsImpl.lstatSync(file); }
+        catch (error     ) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') continue; return false; }
+        if (stat.isSymbolicLink()) { linked = true; return false; }
+        if (namespace === null && stat.isDirectory() && SAFE_NAMESPACE.test(name) && !name.includes('..')) {
+          if (!visit(file, name)) return false;
+          continue;
+        }
+        if (!stat.isFile() || !recordMatch.test(name)) continue;
+        const status = workStatus({ projectRoot: project, store: store.id, taskId: name.slice(0, -5), namespace, mtimeMs: stat.mtimeMs, cache: workCache, fsImpl, shouldStop });
+        if (status.incomplete || shouldStop?.()) return false;
+        if (status.state === 'finished') continue;
+        try {
+          const text = fsImpl.readFileSync(file, 'utf8');
+          if (shouldStop?.()) return false;
+          const logPattern = new RegExp(LOG.source, 'g');
+          let match;
+          while ((match = logPattern.exec(text)) !== null) {
+            if (shouldStop?.()) return false;
+            protectedNames.add(match[0]);
+          }
+        } catch { return false; }
+      }
+      return true;
+    };
+    if (!visit(dir)) return { names: protectedNames, incomplete: true, ...(linked ? { reason: LINKED } : {}) };
+  }
+  return { names: protectedNames, incomplete: false };
+}
+function lifecyclePathsSafe(project     , fsImpl     ) {
+  for (const rel of [path.join('.doflow'), path.join('.doflow', 'state'), path.join('.doflow', 'state', 'lifecycle'), path.join('.doflow', 'state', 'lifecycle', 'events')]) {
+    try { if (fsImpl.lstatSync(path.join(project, rel)).isSymbolicLink()) return false; }
+    catch (error     ) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') return false; if (rel !== path.join('.doflow', 'state', 'lifecycle', 'events')) return false; }
+  }
+  return true;
+}
+function definitelyMissing(fsImpl     , target     ) {
+  try { fsImpl.lstatSync(target); return false; }
+  catch (error     ) { return error.code === 'ENOENT' || error.code === 'ENOTDIR'; }
+}
+function reportCandidates(store     , entries     , context     ) {
+  const { fsImpl, storeDir, roots, now, settings, shouldStop } = context;
+  const project = projectRoot(roots);
+  const key = project && projectKey(project, fsImpl), selected = [];
+  for (const entry of entries) {
+    if (shouldStop?.()) throw budgetError();
+    const folder = path.join(storeDir, entry.name);
+    let children, bodyNames = [];
+    try {
+      children = names(fsImpl, folder);
+      for (const name of children) {
+        if (shouldStop?.()) throw budgetError();
+        if (BODY.test(name) && safeStat(fsImpl, path.join(folder, name))?.isFile()) bodyNames.push(name);
+      }
+    } catch (error     ) { if (error.partial) throw error; continue; }
+    if (entry.name === key) {
+      const lifecycle = path.join(project, '.doflow/state/lifecycle');
+      if (!safeStat(fsImpl, path.join(lifecycle, 'migrated.json'))?.isFile() || !lifecyclePathsSafe(project, fsImpl)) continue;
+      let snapshot;
+      try { snapshot = readEvents(project, { fsImpl, lockFallback: false, shouldStop }); }
+      catch { continue; }
+      if (snapshot.incomplete) throw budgetError();
+      if (snapshot.unreadable.length) continue;
+      const eventIds = new Set();
+      for (const event of snapshot.events) {
+        if (shouldStop?.()) throw budgetError();
+        const ids = [event.data.id, ...(Array.isArray(event.data.ids) ? event.data.ids : [])];
+        for (const id of ids) {
+          if (shouldStop?.()) throw budgetError();
+          if (typeof id === 'string' && /^FU-[0-9a-hjkmnp-tv-z]{6}$/.test(id)) eventIds.add(id);
+        }
+      }
+      for (const body of bodyNames) {
+        if (shouldStop?.()) throw budgetError();
+        const stat = safeStat(fsImpl, path.join(folder, body));
+        if (stat && !eventIds.has(body.slice(0, -4)) && now - stat.mtimeMs > settings.orphanGraceHours * HOUR)
+          selected.push({ name: `${entry.name}/${body}`, reason: 'orphan-body', bytes: stat.size, mtimeMs: stat.mtimeMs });
+      }
+    } else {
+      const marker = path.join(folder, '.root');
+      if (!safeStat(fsImpl, marker)?.isFile() || !bodyNames.length) continue;
+      let validFolder = true;
+      for (const name of children) {
+        if (shouldStop?.()) throw budgetError();
+        if (name !== '.root' && !bodyNames.includes(name)) { validFolder = false; break; }
+      }
+      if (!validFolder) continue;
+      let root;
+      try { root = fsImpl.readFileSync(marker, 'utf8').trim(); } catch { continue; }
+      if (!path.isAbsolute(root) || !definitelyMissing(fsImpl, root)) continue;
+      let newest = -Infinity;
+      for (const body of bodyNames) {
+        if (shouldStop?.()) throw budgetError();
+        const stat = safeStat(fsImpl, path.join(folder, body));
+        if (!stat) { newest = Infinity; break; }
+        newest = Math.max(newest, stat.mtimeMs);
+      }
+      if (now - newest > store.bound.foreignMaxAgeDays * DAY)
+        selected.push({ name: entry.name, reason: 'foreign-root-gone', bytes: entry.stat.size, mtimeMs: newest });
+    }
+  }
+  return selected;
+}
+function selectCandidates(store     , entries     , context     ) {
+  const { now, fsImpl, storeDir, roots, shouldStop } = context;
+  switch (store.rule) {
+    case 'count-and-age': {
+      const ordered = [...entries].sort((a, b) => Number(b.name.slice(0, 13)) - Number(a.name.slice(0, 13)) || a.name.localeCompare(b.name));
+      if (stopped(context)) return null;
+      const selected = [];
+      for (let index = 0; index < ordered.length; index += 1) {
+        if (shouldStop?.()) return null;
+        const entry = ordered[index], time = Number(entry.name.slice(0, 13));
+        if (index >= store.bound.keepNewest || now - time > store.bound.maxAgeDays * DAY)
+          selected.push({ name: entry.name, reason: index >= store.bound.keepNewest ? 'count' : 'age', bytes: entry.stat.size, mtimeMs: time });
+      }
+      return selected;
+    }
+    case 'date-partition':
+    case 'age': {
+      const selected = [];
+      for (const entry of entries) {
+        if (shouldStop?.()) return null;
+        const reason = ageReason(store, entry, now, fsImpl, storeDir, shouldStop);
+        if (shouldStop?.()) return null;
+        if (reason) selected.push({ name: entry.name, reason, bytes: entry.stat.size, mtimeMs: entry.stat.mtimeMs });
+      }
+      return selected;
+    }
+    case 'work': return workCandidates(store, entries, context);
+    case 'report-orphan': return reportCandidates(store, entries, context);
+    case 'recovery': {
+      const root = roots[store.root]; let ledger;
+      try { ledger = JSON.parse(fsImpl.readFileSync(path.join(root, 'ledger.json'), 'utf8')); if (!ledger || typeof ledger !== 'object' || typeof ledger.lastRecoveryId !== 'string') return []; } catch { return []; }
+      const ordered = [...entries].sort((a, b) => b.name.localeCompare(a.name));
+      if (stopped(context)) return null;
+      const selected = [];
+      for (let index = store.bound.keepNewest; index < ordered.length; index += 1) {
+        if (shouldStop?.()) return null;
+        const entry = ordered[index];
+        if (entry.name.slice(0, -5) !== ledger.lastRecoveryId)
+          selected.push({ name: entry.name, reason: 'count', bytes: entry.stat.size, mtimeMs: entry.stat.mtimeMs });
+      }
+      return selected;
+    }
+    case 'lifecycle-settled': return [];
+    case 'existing': case 'control': return [];
+    default: throw new Error(`Unknown storage rule '${store.rule}'`);
+  }
+}
+module.exports={selectCandidates,recordStillCandidate,protectedLogs,removableRules,ruleOrder,projectRoot,BODY};