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

package/src/runtime/scaffold/languages.ts

@@ -0,0 +1,245 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Language selection and emitters — everything `scaffold.js`'s generator needs to know about a
+ * target language: which extension maps to which language, which extensions are content rather
+ * than code, which source languages have no emitter yet, the per-language identifier-casing rules,
+ * the emitters themselves, and `repoLanguage()`, which asks `command-detect.ts` what toolchain the
+ * repository itself uses (for test stubs, which have no file extension of their own to read).
+ */
+
+const { detectCommands } = require('../command-detect.ts');
+
+/**
+ * Per-file language comes from the file's own extension, because `plan.md` already states it:
+ * `files: src/runtime/scaffold/generate.js` is not ambiguous about being JavaScript, and asking a
+ * repository-wide detector would be a worse answer than the one the plan wrote down.
+ *
+ * Repository-wide detection is still needed for the test stubs, which derive from acceptance
+ * criteria and therefore have no path to read an extension from. That question — "what toolchain
+ * is this repository" — is `command-detect.ts`'s, so it is asked there rather than answered a
+ * second time here. See `repoLanguage()` for the one place its output is interpreted.
+ */
+const EXTENSION_LANGUAGE: Readonly<Record<string, string>> = Object.freeze({
+  '.js': 'javascript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.jsx': 'javascript',
+  '.ts': 'typescript',
+  '.mts': 'typescript',
+  '.cts': 'typescript',
+  '.tsx': 'typescript',
+  '.py': 'python',
+  '.go': 'go',
+  '.rs': 'rust',
+});
+
+/**
+ * Extensions that are content, not code. A plan task naming one of these is not a gap in this
+ * generator — there is no signature to emit for a markdown file — so these skip benignly and never
+ * push the run to a non-zero exit.
+ */
+const PROSE_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.md', '.markdown', '.txt', '.rst',
+  '.yaml', '.yml', '.json', '.jsonc', '.toml', '.ini', '.cfg', '.conf', '.env', '.lock',
+  '.html', '.css', '.scss', '.svg', '.png', '.jpg', '.gif', '.csv',
+]);
+
+/**
+ * Source languages the *prose* algorithm in `references/scaffold.md` covers through its
+ * Default-Implementation Grammar table, but this module has no emitter for. Named explicitly so a
+ * plan that touches one produces "no emitter for Java", not silence — the gap is real and belongs
+ * in the manifest, not in a reader's assumptions.
+ */
+const UNEMITTED_SOURCE_EXTENSIONS: Readonly<Record<string, { name: string; inProseGrammar: boolean }>> = Object.freeze({
+  '.java': { name: 'Java', inProseGrammar: true },
+  '.kt': { name: 'Kotlin', inProseGrammar: true },
+  '.kts': { name: 'Kotlin', inProseGrammar: true },
+  '.cs': { name: 'C#', inProseGrammar: true },
+  '.swift': { name: 'Swift', inProseGrammar: true },
+  '.m': { name: 'Objective-C', inProseGrammar: true },
+  '.h': { name: 'Objective-C or C header', inProseGrammar: false },
+  '.sh': { name: 'Shell', inProseGrammar: false },
+  '.bash': { name: 'Shell', inProseGrammar: false },
+  '.rb': { name: 'Ruby', inProseGrammar: false },
+  '.php': { name: 'PHP', inProseGrammar: false },
+  '.c': { name: 'C', inProseGrammar: false },
+  '.cc': { name: 'C++', inProseGrammar: false },
+  '.cpp': { name: 'C++', inProseGrammar: false },
+  '.hpp': { name: 'C++', inProseGrammar: false },
+});
+
+/** Splits an identifier-ish path segment into lowercase words, so every language can re-case it
+ * to its own convention from one parse. */
+function words(name: string): string[] {
+  return name
+    .replace(/\.[^.]+$/, '')
+    .split(/[^A-Za-z0-9]+/)
+    .flatMap((part) => part.split(/(?<=[a-z0-9])(?=[A-Z])/))
+    .filter(Boolean)
+    .map((part) => part.toLowerCase());
+}
+
+const camel = (parts: string[]): string => parts.map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join('') || 'scaffold';
+const pascal = (parts: string[]): string => parts.map((w) => w[0].toUpperCase() + w.slice(1)).join('') || 'Scaffold';
+const snake = (parts: string[]): string => parts.join('_') || 'scaffold';
+
+/**
+ * One entry per language this module can emit. Each `module` and `test` body is a signature plus a
+ * single "not implemented" signal drawn from the Default-Implementation Grammar pinned in
+ * `references/scaffold.md` — the same table the external-dependency case uses, so the two halves of
+ * that document agree on what an unimplemented body looks like.
+ */
+const EMITTERS: Readonly<Record<string, any>> = Object.freeze({
+  javascript: {
+    line: (t: string) => (t ? `// ${t}` : '//'),
+    module: ({ symbol, message }: any) => [
+      '/**',
+      ' * Placeholder signature — replace with the real surface before implementing.',
+      ' * @returns {never}',
+      ' */',
+      `function ${symbol}() {`,
+      `  throw new Error(${JSON.stringify(message)});`,
+      '}',
+      '',
+      `module.exports = { ${symbol} };`,
+    ].join('\n'),
+    testName: (id: string) => `${id}.test.js`,
+    test: ({ id, cases, message }: any) => [
+      "const { test } = require('node:test');",
+      '',
+      ...cases.map(({ statement }: any) => [
+        `test(${JSON.stringify(`${id} — ${statement}`)}, () => {`,
+        `  throw new Error(${JSON.stringify(message)});`,
+        '});',
+        '',
+      ].join('\n')),
+    ].join('\n').trimEnd(),
+  },
+
+  typescript: {
+    line: (t: string) => (t ? `// ${t}` : '//'),
+    module: ({ symbol, message }: any) => [
+      '/** Placeholder signature — replace with the real surface before implementing. */',
+      `export function ${symbol}(): never {`,
+      `  throw new Error(${JSON.stringify(message)});`,
+      '}',
+    ].join('\n'),
+    testName: (id: string) => `${id}.test.ts`,
+    test: ({ id, cases, message }: any) => [
+      "import { test } from 'node:test';",
+      '',
+      ...cases.map(({ statement }: any) => [
+        `test(${JSON.stringify(`${id} — ${statement}`)}, (): void => {`,
+        `  throw new Error(${JSON.stringify(message)});`,
+        '});',
+        '',
+      ].join('\n')),
+    ].join('\n').trimEnd(),
+  },
+
+  python: {
+    line: (t: string) => (t ? `# ${t}` : '#'),
+    module: ({ symbol, message }: any) => [
+      `def ${symbol}() -> None:`,
+      '    """Placeholder signature — replace with the real surface before implementing."""',
+      `    raise NotImplementedError(${JSON.stringify(message)})`,
+    ].join('\n'),
+    testName: (id: string) => `test_${id.toLowerCase().replace(/-/g, '_')}.py`,
+    test: ({ cases, message }: any) => cases.map(({ statement }: any, i: number) => [
+      `def test_case_${i + 1}() -> None:`,
+      `    """${statement.replace(/"/g, "'")}"""`,
+      `    raise NotImplementedError(${JSON.stringify(message)})`,
+      '',
+    ].join('\n')).join('\n').trimEnd(),
+  },
+
+  go: {
+    line: (t: string) => (t ? `// ${t}` : '//'),
+    module: ({ symbol, message, pkg }: any) => [
+      `package ${pkg}`,
+      '',
+      'import "errors"',
+      '',
+      '// Placeholder signature — replace with the real surface before implementing.',
+      `func ${symbol}() error {`,
+      `\treturn errors.New(${JSON.stringify(message)})`,
+      '}',
+    ].join('\n'),
+    testName: (id: string) => `${id.toLowerCase().replace(/-/g, '_')}_test.go`,
+    test: ({ id, cases, message, pkg }: any) => [
+      `package ${pkg}`,
+      '',
+      'import "testing"',
+      '',
+      ...cases.map(({ statement }: any, i: number) => [
+        `// ${statement}`,
+        `func Test${pascal(words(id))}Case${i + 1}(t *testing.T) {`,
+        `\tt.Fatal(${JSON.stringify(message)})`,
+        '}',
+        '',
+      ].join('\n')),
+    ].join('\n').trimEnd(),
+  },
+
+  rust: {
+    line: (t: string) => (t ? `// ${t}` : '//'),
+    module: ({ symbol, message }: any) => [
+      '/// Placeholder signature — replace with the real surface before implementing.',
+      `pub fn ${symbol}() {`,
+      `    unimplemented!(${JSON.stringify(message)});`,
+      '}',
+    ].join('\n'),
+    testName: (id: string) => `${id.toLowerCase().replace(/-/g, '_')}.rs`,
+    test: ({ id, cases, message }: any) => cases.map(({ statement }: any, i: number) => [
+      `// ${statement}`,
+      '#[test]',
+      `fn ${snake(words(id))}_case_${i + 1}() {`,
+      `    unimplemented!(${JSON.stringify(message)});`,
+      '}',
+      '',
+    ].join('\n')).join('\n').trimEnd(),
+  },
+});
+
+/**
+ * The repository's own toolchain, asked of `command-detect.ts` rather than re-derived here.
+ *
+ * Partial fit, stated rather than papered over: that module answers "which manifests are present",
+ * which pins the toolchain but not the dialect inside it — `package.json` alone does not say
+ * TypeScript. The one extra bit is read from its own output (a `typecheck` role exists only when a
+ * tsc script or a `tsconfig.json` was found), so no second detector is introduced.
+ */
+function repoLanguage(repoRoot: string, fsImpl: any): any {
+  const detected = detectCommands({ projectRoot: repoRoot, fsImpl });
+  if (!detected.manifestFound) {
+    return { id: null, signal: 'none', why: 'no build manifest found by command-detect.ts' };
+  }
+  const has = (name: string) => detected.manifests.includes(name);
+  if (has('package.json')) {
+    const typescript = Boolean(detected.commands.typecheck);
+    return { id: typescript ? 'typescript' : 'javascript', signal: 'package.json', why: null };
+  }
+  if (has('Cargo.toml')) return { id: 'rust', signal: 'Cargo.toml', why: null };
+  if (has('go.mod')) return { id: 'go', signal: 'go.mod', why: null };
+  if (has('pyproject.toml')) return { id: 'python', signal: 'pyproject.toml', why: null };
+  return {
+    id: null,
+    signal: detected.manifests.join(', ') || 'none',
+    why: `command-detect.ts resolved only ${detected.manifests.join(', ') || 'nothing'}, which names no source language`,
+  };
+}
+
+module.exports = {
+  EXTENSION_LANGUAGE,
+  PROSE_EXTENSIONS,
+  UNEMITTED_SOURCE_EXTENSIONS,
+  words,
+  camel,
+  pascal,
+  snake,
+  EMITTERS,
+  repoLanguage,
+};

package/src/runtime/storage/cli.ts

@@ -0,0 +1,64 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { loadStorageRegistry } = require('./registry.ts');
+const { resolveRoots, readPruneSetting } = require('./roots.ts');
+const { runPass } = require('./engine.ts');
+const { upkeepAfterVerb } = require('./upkeep.ts');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+
+function handleStorageCommand({ action = 'report', json = false, global = false, projectRoot = '.', env = process.env, fsImpl = fs }: any = {}) {
+  if (!['report', 'prune', 'upkeep'].includes(action)) {
+    console.error(`doflow storage: unknown action '${action}' (expected report, prune, or upkeep)`);
+    process.exitCode = 2;
+    return;
+  }
+  if (action === 'upkeep') {
+    // IC-018: prints nothing and exits 0 even when the registry is unavailable; upkeep fails closed.
+    upkeepAfterVerb({ projectRoot: global ? null : path.resolve(projectRoot), env, fsImpl });
+    return;
+  }
+  let registry;
+  try { registry = loadStorageRegistry({ repoRoot: REPO_ROOT, fsImpl }); }
+  catch (error: any) {
+    console.error(`doflow storage: storage registry unavailable${error.message ? `: ${error.message}` : ''}`);
+    process.exitCode = 2;
+    return;
+  }
+  const roots = resolveRoots({ registry, projectRoot: global ? null : path.resolve(projectRoot), global, env });
+  const projectSetting = readPruneSetting({ registry, roots, rootId: 'project-state', fsImpl });
+  const userSetting = readPruneSetting({ registry, roots, rootId: 'user-state', fsImpl });
+  const setting = Object.fromEntries(Object.keys(roots).map(rootId => [rootId,
+    readPruneSetting({ registry, roots, rootId, fsImpl })]));
+  const mode = action === 'prune' ? 'prune' : 'report';
+  const result = runPass({ registry, roots, mode, setting, now: Date.now(), env, fsImpl });
+  const removed = result.stores.reduce((sum: any, row: any) => sum + row.removed, 0);
+  const entries = `entr${removed === 1 ? 'y' : 'ies'}`;
+  if (action === 'prune' && Object.values(setting).every(value => value.setting === 'off')) {
+    const decision = projectSetting.decidedBy || userSetting.decidedBy || path.join(roots['config-home'], registry.settings.optOutFile);
+    // IC-013: an explicitly set DOFLOW_RETENTION_HOURS still removes settled lifecycle events.
+    console.log(removed === 0 ? `storage: pruning is off (${decision}); nothing removed`
+      : `storage: pruning is off (${decision}); DOFLOW_RETENTION_HOURS still applied to lifecycle events: removed ${removed} ${entries}`);
+    return;
+  }
+  if (json) {
+    console.log(JSON.stringify({
+      setting: { project: projectSetting.setting, user: userSetting.setting,
+        decidedBy: { project: projectSetting.decidedBy, user: userSetting.decidedBy } },
+      ...result,
+    }, null, 2));
+    return;
+  }
+  console.log(`Settings: project ${projectSetting.setting}${projectSetting.decidedBy ? ` (${projectSetting.decidedBy})` : ' (default)'}; user ${userSetting.setting}${userSetting.decidedBy ? ` (${userSetting.decidedBy})` : ' (default)'}`);
+  for (const row of result.stores) {
+    const names = row.selected.slice(0, 20).map((entry: any) => entry.name);
+    const more = row.selected.length > 20 ? `\n    ... and ${row.selected.length - 20} more` : '';
+    console.log(`${row.id}\n  Location: ${row.location || '(not configured)'}\n  Entries: ${row.entries}; size: ${row.bytes} bytes\n  Bound: ${row.bound}\n  Would remove: ${row.selected.length}${names.length ? `\n    ${names.join('\n    ')}` : ''}${more}`);
+  }
+  if (action === 'prune') console.log(`storage: removed ${removed} ${entries}`);
+}
+
+module.exports = { handleStorageCommand };

package/src/runtime/storage/engine.ts

@@ -0,0 +1,249 @@
+'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 { randomBytes } = require('node:crypto');
+const { formatBound } = require('./registry.ts');
+const { resolveStorePath } = require('./roots.ts');
+const { selectCandidates, recordStillCandidate, protectedLogs, removableRules, ruleOrder, projectRoot } = require('./rules.ts');
+const { retainLocked } = require('../lifecycle/store-upkeep.ts');
+const { parseWindow, selectExpired } = require('../lifecycle/retention.ts');
+const { readEvents } = require('../lifecycle/event-store.ts');
+const { createWorkCache } = require('./work-status.ts');
+const { projectKey } = require('../lifecycle/report-store.ts');
+const SAFE_NAMESPACE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const TOMBSTONE = /^\.[A-Za-z0-9][A-Za-z0-9._-]*\.pruning-[0-9]+-[0-9a-f]{8}$/;
+
+function stat(fsImpl: any,file: any) { try { return fsImpl.lstatSync(file); } catch { return null; } }
+function ownedPathLinked(store: any,roots: any,fsImpl: any) {
+  const root=roots[store.root]; if (!root) return false;
+  const owned=path.basename(root)==='doflow' || path.basename(root)==='.doflow' ? root : path.dirname(root);
+  for (const dir of [owned,...(store.path ? [root,...store.path.split('/').reduce((a: any,part: any)=>{a.push(path.join(a.at(-1)||root,part));return a;},[])] : [root])])
+    if (stat(fsImpl,dir)?.isSymbolicLink()) return true;
+  return false;
+}
+function inventory(store: any,storeDir: any,fsImpl: any,shouldStop: any) {
+  const match=new RegExp(store.match), entries=[];
+  for (const name of fsImpl.readdirSync(storeDir)) {
+    if (shouldStop?.()) return null;
+    const matches=match.test(name), namespace=store.entry==='record' && SAFE_NAMESPACE.test(name) && !name.includes('..');
+    if (!matches && !namespace) continue;
+    const info=stat(fsImpl,path.join(storeDir,name));
+    if (shouldStop?.()) return null;
+    if (!info || info.isSymbolicLink()) continue;
+    if (store.entry==='dir' && !info.isDirectory() || store.entry==='file' && !info.isFile()
+      || store.entry==='record' && !(matches && info.isFile() || namespace && info.isDirectory())) continue;
+    entries.push({name,stat:info});
+  }
+  return entries;
+}
+function sweepTombstones(fsImpl: any,storeDir: any,row: any) {
+  for (const name of fsImpl.readdirSync(storeDir)) {
+    if (!TOMBSTONE.test(name)) continue;
+    const target=path.join(storeDir,name);
+    try {
+      const info=fsImpl.lstatSync(target);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      // Node's recursive rm removes nested links themselves, never their referents.
+      fsImpl.rmSync(target,{recursive:true});
+      row.removed++;
+    } catch (error: any) {
+      if (error.code==='ENOENT') row.removed++;
+      else row.failed.push({name,code:error.code || 'EIO'});
+    }
+  }
+}
+function removalOrder(candidates: any) {
+  const oldest=[...candidates].sort((a,b)=>a.mtimeMs-b.mtimeMs || a.name.localeCompare(b.name));
+  const byName=new Map(oldest.map(candidate=>[candidate.name,candidate])), emitted=new Set(), ordered=[];
+  for (const candidate of oldest) {
+    // Preserve oldest-first order except that a task's claims must disappear before its record.
+    const claims=byName.get(candidate.name.replace(/\.json$/, '_claims.json'));
+    for (const entry of [claims,candidate]) {
+      if (entry && !emitted.has(entry.name)) { ordered.push(entry); emitted.add(entry.name); }
+    }
+  }
+  return ordered;
+}
+function removeOne(fsImpl: any,storeDir: any,candidate: any,store: any,context: any) {
+  const parts=candidate.name.split('/');
+  if (parts.length>2 || parts.some((part: any)=>!part || part==='.' || part==='..')) throw Object.assign(new Error('unsafe name'),{code:'EINVAL'});
+  const target=path.join(storeDir,...parts), lock=`${target}.lock`;
+  let locked=false;
+  try {
+    if (parts.length===2) {
+      const parent=fsImpl.lstatSync(path.join(storeDir,parts[0]));
+      if (parent.isSymbolicLink() || !parent.isDirectory()) return false;
+    }
+    if (store.entry==='record') {
+      try { fsImpl.mkdirSync(lock); locked=true; }
+      catch(error: any) { if (error.code==='EEXIST') return false; throw error; }
+    }
+    const info=fsImpl.lstatSync(target);
+    if (info.isSymbolicLink()) return false;
+    if (locked) {
+      if (!recordStillCandidate(store,candidate,info,context)) return false;
+      // Some record writers do not honor this lock. Catch a write during the work-status read
+      // too; a changed subject must wait for another pass even if it still looks finished.
+      const current=fsImpl.lstatSync(target);
+      if (current.isSymbolicLink() || !current.isFile()
+        || ['mtimeMs','ctimeMs','size','ino','dev'].some(key=>current[key]!==info[key])) return false;
+    }
+    if (context.shouldStop()) return false;
+    if (info.isDirectory()) {
+      // An appending hook may have refreshed a child since selection. Revalidate before hiding.
+      if (store.rule==='age' && !selectCandidates(store,[{name:candidate.name,stat:info}],context)?.length) return false;
+      if (context.shouldStop()) return false;
+      const tombstone=path.join(path.dirname(target),`.${path.basename(target)}.pruning-${process.pid}-${randomBytes(4).toString('hex')}`);
+      try { fsImpl.renameSync(target,tombstone); } catch { return false; }
+      const renamed=fsImpl.lstatSync(tombstone);
+      if (!renamed.isDirectory() || renamed.isSymbolicLink()) return false;
+      fsImpl.rmSync(tombstone,{recursive:true});
+    } else if (info.isFile()) fsImpl.unlinkSync(target);
+    else return false;
+    return true;
+  } catch(error: any) { if (error.code==='ENOENT') return true; throw error; }
+  finally {
+    if (locked) {
+      try { fsImpl.rmdirSync(lock); } catch(error: any) { if (error.code!=='ENOENT') throw error; }
+    }
+  }
+}
+function cleanEmptyNamespace(fsImpl: any,storeDir: any,name: any,report = false) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) return;
+  const dir=path.join(storeDir,name);
+  try {
+    if (report && fsImpl.readdirSync(dir).join() === '.root') fsImpl.unlinkSync(path.join(dir,'.root'));
+    fsImpl.rmdirSync(dir);
+  } catch { /* another record, or an active writer */ }
+}
+function projectKeyMarker(fsImpl: any,storeDir: any,roots: any) {
+  const project=projectRoot(roots);
+  if (!project) return;
+  let key;
+  try { key=projectKey(project,fsImpl); } catch { return; }
+  const dir=path.join(storeDir,key);
+  if (!stat(fsImpl,dir)?.isDirectory() || stat(fsImpl,path.join(dir,'.root'))) return;
+  try { fsImpl.writeFileSync(path.join(dir,'.root'),`${fsImpl.realpathSync(project)}\n`,{flag:'wx'}); } catch { /* best effort */ }
+}
+/** A bounded pass over registry-declared stores; report mode never writes. */
+function runPass({registry,roots,stores,mode,setting={},now=Date.now(),budgetMs,maxRemovals,env=process.env,fsImpl=fs}: any) {
+  if (mode!=='report' && mode!=='prune') throw new Error('Storage pass mode must be report or prune');
+  const started=performance.now(), budget=budgetMs===undefined?(mode==='report'?Infinity:registry.settings.passBudgetMs):budgetMs;
+  const cap=maxRemovals===undefined?registry.settings.maxRemovalsPerPass:maxRemovals;
+  const requested=new Set(stores || registry.stores.filter((s: any)=>removableRules.has(s.rule)).map((s: any)=>s.id));
+  const ordered=[...registry.stores].filter(s=>requested.has(s.id) && removableRules.has(s.rule))
+    .sort((a,b)=>ruleOrder.indexOf(a.id)-ruleOrder.indexOf(b.id));
+  const result: any={mode,partial:false,durationMs:0,stores:[]};
+  let removals=0, protectedSet: any=null;
+  const shouldStop=()=>mode==='prune' && (removals>=cap || performance.now()-started>=budget);
+  const project=projectRoot(roots);
+  const workCache=project && ordered.some(s=>s.rule==='work' || s.protect==='open-work')
+    ? createWorkCache({projectRoot:project,fsImpl}) : null;
+  // P0/P1 run for every requested store before any budgeted inventory or selection. A stopped
+  // pass must still finish removing folders that an earlier interrupted pass already hid.
+  const ready=[];
+  for (const store of ordered) {
+    const root=roots[store.root], storeSetting=typeof setting[store.root]==='string'?setting[store.root]:setting[store.root]?.setting || 'on';
+    const location=root?path.join(root,...(store.path?store.path.split('/'):[])):'';
+    const row: any={id:store.id,root:root || '',location,bound:formatBound(store),setting:storeSetting,entries:0,bytes:0,selected:[],removed:0,protected:0,failed:[]};
+    result.stores.push(row);
+    if (!root) { row.skipped='absent'; continue; }
+    if (ownedPathLinked(store,roots,fsImpl) || resolveStorePath({store,roots,fsImpl})===null) { row.skipped='link'; continue; }
+    if (!stat(fsImpl,root) || !stat(fsImpl,location)?.isDirectory()) { row.skipped='absent'; continue; }
+    // IC-013: an explicit DOFLOW_RETENTION_HOURS governs lifecycle events even while pruning is off.
+    const explicitWindow=store.rule==='lifecycle-settled' ? parseWindow(env) : {state:'off'};
+    if (mode==='prune' && storeSetting==='off' && explicitWindow.state!=='on') { row.skipped='setting-off'; continue; }
+    if (mode==='prune') {
+      try { sweepTombstones(fsImpl,location,row); }
+      catch(error: any) { row.failed.push({name:store.id,code:error.code || 'EIO'}); continue; }
+    }
+    ready.push({store,row,location,explicitWindow,storeSetting});
+  }
+  for (const {store,row,location,explicitWindow,storeSetting} of ready) {
+    if (shouldStop()) { result.partial=true; break; }
+    let entries;
+    try { entries=inventory(store,location,fsImpl,shouldStop); }
+    catch(error: any) { row.failed.push({name:store.id,code:error.code || 'EIO'}); continue; }
+    if (entries===null) { result.partial=true; break; }
+    row.entries=entries.length;
+    for (const entry of entries) {
+      if (shouldStop()) { result.partial=true; break; }
+      row.bytes+=entry.stat.size;
+    }
+    if (result.partial) break;
+    if (store.rule==='lifecycle-settled') {
+      // Report and prune share one window: the env window, else the default only while the setting is on.
+      const window=explicitWindow.state==='on' ? {...explicitWindow,source:'env'}
+        : explicitWindow.state==='invalid' ? explicitWindow
+          : storeSetting==='off' ? {state:'off'}
+            : {state:'on',hours:store.bound.defaultHours,ms:store.bound.defaultHours*3600000,source:'default'};
+      if (window.state==='on') {
+        if (mode==='report') {
+          let snapshot;
+          try { snapshot=readEvents(project,{fsImpl,lockFallback:false,shouldStop}); }
+          catch(error: any) { row.failed.push({name:store.id,code:error.code || 'EIO'}); continue; }
+          if (snapshot.incomplete) { result.partial=true; break; }
+          if (snapshot.unreadable.length) { row.failed.push({name:store.id,code:'EIO'}); continue; }
+          const selection=selectExpired(snapshot.events,{now:new Date(now),windowMs:window.ms,shouldStop});
+          if (selection.incomplete) { result.partial=true; break; }
+          row.selected=selection.files.map((name: any)=>({name,reason:'settled',bytes:stat(fsImpl,path.join(location,name))?.size || 0}));
+        } else {
+          let output;
+          try { output=retainLocked(project,{fsImpl,now:new Date(now),window,maxFiles:Math.max(0,cap-removals),shouldStop}); }
+          catch(error: any) { row.failed.push({name:store.id,code:error.code || 'EIO'}); continue; }
+          row.selected=output.selected.map(({name,bytes}: any)=>({name,reason:'settled',bytes}));
+          row.removed=output.removed; removals+=row.removed;
+          if (output.warning.length) row.failed.push({name:store.id,code:output.code || 'EIO'});
+          if (output.partial) { result.partial=true; break; }
+        }
+      }
+      if (shouldStop()) { result.partial=true; break; }
+      continue;
+    }
+    let candidates;
+    try { candidates=selectCandidates(store,entries,{registry,roots,fsImpl,storeDir:location,now,settings:registry.settings,shouldStop,cache:workCache}); }
+    catch(error: any) {
+      if (error.partial) { result.partial=true; break; }
+      row.failed.push({name:store.id,code:error.code || 'EIO'}); continue;
+    }
+    if (candidates===null) { result.partial=true; break; }
+    if (store.protect==='open-work' && candidates.length) {
+      if (!protectedSet) {
+        const protection=protectedLogs({registry,roots,fsImpl,cache:workCache,shouldStop});
+        if (protection.incomplete) {
+          if (shouldStop()) { result.partial=true; break; }
+          row.failed.push({name:store.id,code:protection.reason || 'EIO'}); continue;
+        }
+        protectedSet=protection.names;
+      }
+      row.protected=candidates.filter((c: any)=>protectedSet.has(c.name)).length;
+      candidates=candidates.filter((c: any)=>!protectedSet.has(c.name));
+    }
+    const orderedCandidates=store.entry==='record' ? removalOrder(candidates)
+      : [...candidates].sort((a,b)=>a.mtimeMs-b.mtimeMs || a.name.localeCompare(b.name));
+    if (shouldStop()) { result.partial=true; break; }
+    row.selected=orderedCandidates.map(({name,reason,bytes})=>({name,reason,bytes}));
+    if (mode==='report') continue;
+    if (shouldStop()) { result.partial=true; break; }
+    const removalContext={registry,roots,fsImpl,storeDir:location,now,settings:registry.settings,shouldStop,cache:workCache};
+    for (const candidate of orderedCandidates) {
+      if (shouldStop()) { result.partial=true; break; }
+      try {
+        if (ownedPathLinked(store,roots,fsImpl) || resolveStorePath({store,roots,fsImpl})===null) continue;
+        if (removeOne(fsImpl,location,candidate,store,removalContext)) {
+          row.removed++; removals++;
+          if (store.entry==='record' && candidate.name.includes('/')) cleanEmptyNamespace(fsImpl,location,candidate.name.split('/')[0]);
+          if (store.rule==='report-orphan' && candidate.name.includes('/')) cleanEmptyNamespace(fsImpl,location,candidate.name.split('/')[0],true);
+        }
+      } catch(error: any) { row.failed.push({name:candidate.name,code:error.code || 'EIO'}); }
+    }
+    if (store.rule==='report-orphan' && !result.partial) projectKeyMarker(fsImpl,location,roots);
+    if (result.partial) break;
+  }
+  result.durationMs=performance.now()-started;
+  return result;
+}
+module.exports={runPass};