runlist 0.0.0 → 0.94.2

package/src/agent-context.mjs

@@ -0,0 +1,201 @@
+import { die, isArchivedPath, truncate } from './util.mjs';
+import { isCoordinationHub } from './runlist.mjs';
+import { readPlanOwnership, ownershipLiveness } from './pickup.mjs';
+import {
+  actionablePromptStatuses,
+  comparePromptDocs,
+  compareStrings,
+  resolveStatusMetadata,
+  statusMetadataFor,
+} from './status-metadata.mjs';
+
+export const AGENT_CONTEXT_SCHEMA = Object.freeze({ name: 'dotmd.agent-context', version: 1 });
+export const DEFAULT_AGENT_CONTEXT_BYTES = 16 * 1024;
+export const AGENT_CONTEXT_SECTIONS = Object.freeze(['statusVocabulary', 'counts', 'prompts', 'plans', 'issues']);
+
+export function parseAgentContextOptions(args) {
+  const value = name => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+  const rawBudget = value('--max-bytes');
+  const maxBytes = rawBudget === undefined ? DEFAULT_AGENT_CONTEXT_BYTES : Number(rawBudget);
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 2048) die('--max-bytes takes a whole number of bytes, at least 2048.');
+  const rawSections = value('--sections');
+  const sections = rawSections === undefined ? null : [...new Set(rawSections.split(',').map(s => s.trim()).filter(Boolean))];
+  if (sections && (!sections.length || sections.some(s => !AGENT_CONTEXT_SECTIONS.includes(s)))) {
+    die(`--sections is a comma-separated selection of ${AGENT_CONTEXT_SECTIONS.join(', ')}.`);
+  }
+  return { maxBytes, sections };
+}
+
+const LIMITS = Object.freeze({ vocabulary: 32, prompts: 8, plans: 12, hubs: 8, issues: 10 });
+
+export function boundedCollection(items, limit) {
+  const selected = items.slice(0, limit);
+  return {
+    total: items.length,
+    shown: selected.length,
+    truncated: selected.length < items.length,
+    items: selected,
+  };
+}
+
+function compactDoc(doc, config) {
+  const blockers = (doc.blockers ?? []).map(item => truncate(String(item), 160));
+  const ownership = doc.type === 'plan' ? readPlanOwnership(doc.path, config) : null;
+  return {
+    path: doc.path,
+    title: truncate(doc.title ?? '', 160),
+    status: doc.status,
+    type: doc.type,
+    nextStep: doc.nextStep ? truncate(doc.nextStep, 300) : null,
+    blockers: boundedCollection(blockers, 3),
+    daysSinceUpdate: doc.daysSinceUpdate ?? null,
+    ...(doc.owner ? { owner: doc.owner } : {}),
+    ...(ownership ? { claim: ownership.corrupt ? { state: 'unverifiable', reason: ownership.reason } : {
+      state: ownership.state, sessionId: ownership.sessionId,
+      claimedAt: ownership.claimedAt, liveness: ownershipLiveness(ownership),
+    } } : {}),
+  };
+}
+
+function docCollection(docs, limit, config) {
+  return { total: docs.length, shown: Math.min(docs.length, limit), truncated: docs.length > limit, items: docs.slice(0, limit).map(doc => compactDoc(doc, config)) };
+}
+
+function enforceByteBudget(context, maxBytes) {
+  context.budget = { maxBytes, bytes: 0, truncated: false };
+  const measure = () => {
+    for (let i = 0; i < 4; i++) context.budget.bytes = Buffer.byteLength(JSON.stringify(context, null, 2) + '\n');
+    return context.budget.bytes;
+  };
+  const collections = [
+    context.plans?.stale, context.plans?.listed, context.plans?.hubs,
+    context.issues?.warnings,
+    ...Object.values(context.statusVocabulary ?? {}).reverse(),
+    context.issues?.errors, context.prompts?.actionable, context.plans?.focus,
+  ].filter(Boolean);
+  const protectedItem = (collection, item, i) => {
+    if (collection === context.plans?.focus || collection === context.plans?.listed) {
+      if (item.claim?.state === 'owned' || item.claim?.state === 'unverifiable' || item.owner) return true;
+      if (collection === context.plans?.focus && i === 0) return true;
+    }
+    return i === 0 && (collection === context.prompts?.actionable || collection === context.issues?.errors);
+  };
+  while (measure() > maxBytes) {
+    let removed = false;
+    for (const collection of collections) {
+      const i = collection.items.findLastIndex((item, i) => !protectedItem(collection, item, i));
+      if (i < 0) continue;
+      collection.items.splice(i, 1);
+      collection.shown = collection.items.length;
+      collection.truncated = collection.shown < collection.total;
+      context.budget.truncated = true;
+      removed = true;
+      break;
+    }
+    if (!removed) die(`Agent context needs ${context.budget.bytes} bytes to retain its counts, claims, next prompt and first action; increase --max-bytes or select fewer --sections.`);
+  }
+  return context;
+}
+
+function rankMap(metadata, type) {
+  return new Map((metadata.byType[type] ?? []).map(item => [item.name, item.rank]));
+}
+
+function compareByStatusAndPath(ranks) {
+  return (a, b) => (ranks.get(a.status) ?? Number.MAX_SAFE_INTEGER) - (ranks.get(b.status) ?? Number.MAX_SAFE_INTEGER)
+    || compareStrings(a.path, b.path);
+}
+
+function issueItem(issue) {
+  return { path: issue.path ?? null, message: truncate(issue.message ?? String(issue), 300) };
+}
+
+export function buildAgentContext(index, config, options = {}) {
+  const maxBytes = options.maxBytes ?? DEFAULT_AGENT_CONTEXT_BYTES;
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 2048) die('--max-bytes takes a whole number of bytes, at least 2048.');
+  const sections = options.sections ?? AGENT_CONTEXT_SECTIONS;
+  if (!Array.isArray(sections) || !sections.length || sections.some(s => !AGENT_CONTEXT_SECTIONS.includes(s))) die('Unknown agent-context section.');
+  const metadata = resolveStatusMetadata(config);
+  const planRanks = rankMap(metadata, 'plan');
+  const closed = (doc) => isArchivedPath(doc.path, config)
+    || config.lifecycle.archiveStatuses.has(doc.status)
+    || config.lifecycle.terminalStatuses.has(doc.status);
+  const livePlans = index.docs.filter(doc => doc.type === 'plan' && !closed(doc));
+  const hubs = livePlans.filter(isCoordinationHub).sort((a, b) => compareStrings(a.path, b.path));
+  const leaves = livePlans.filter(doc => !isCoordinationHub(doc));
+  const focus = leaves
+    .filter(doc => statusMetadataFor(config, 'plan', doc.status)?.context === 'expanded')
+    .sort(compareByStatusAndPath(planRanks));
+  const listed = leaves
+    .filter(doc => statusMetadataFor(config, 'plan', doc.status)?.context === 'listed')
+    .sort(compareByStatusAndPath(planRanks));
+  const stale = leaves
+    .filter(doc => doc.isStale && !statusMetadataFor(config, 'plan', doc.status)?.skipStale)
+    .sort((a, b) => (b.daysSinceUpdate ?? -1) - (a.daysSinceUpdate ?? -1)
+      || compareByStatusAndPath(planRanks)(a, b));
+
+  const promptStatuses = actionablePromptStatuses(config);
+  const prompts = index.docs
+    .filter(doc => doc.type === 'prompt' && promptStatuses.has(doc.status) && !closed(doc))
+    .sort(comparePromptDocs);
+
+  const vocabulary = {};
+  const vocabularyTypes = options.types?.length
+    ? metadata.typeOrder.filter(type => options.types.includes(type))
+    : metadata.typeOrder;
+  for (const type of vocabularyTypes) {
+    vocabulary[type] = boundedCollection(
+      (metadata.byType[type] ?? []).map(item => ({
+        name: item.name,
+        context: item.context,
+        staleDays: item.staleDays,
+        startable: item.startable,
+        terminal: item.terminal,
+        archive: item.archive,
+      })),
+      LIMITS.vocabulary,
+    );
+  }
+
+  const issueSort = (a, b) => compareStrings(a.path ?? '', b.path ?? '')
+    || compareStrings(a.message ?? '', b.message ?? '');
+  const errors = [...index.errors].sort(issueSort).map(issueItem);
+  const warnings = [...index.warnings].sort(issueSort).map(issueItem);
+
+  const context = {
+    schema: AGENT_CONTEXT_SCHEMA,
+    generatedAt: options.generatedAt ?? new Date().toISOString(),
+    scope: {
+      roots: options.roots?.length ? [...options.roots] : null,
+      types: options.types?.length ? [...options.types] : null,
+      ...(options.sections ? { sections: [...sections] } : {}),
+    },
+    statusVocabulary: vocabulary,
+    counts: {
+      documents: index.docs.length,
+      byStatus: { ...index.countsByStatus },
+      byType: Object.fromEntries(Object.entries(index.countsByType).map(([type, counts]) => [type, { ...counts }])),
+      errors: index.errors.length,
+      warnings: index.warnings.length,
+    },
+    prompts: {
+      actionable: docCollection(prompts, LIMITS.prompts, config),
+      next: prompts[0] ? compactDoc(prompts[0], config) : null,
+    },
+    plans: {
+      focus: docCollection(focus, LIMITS.plans, config),
+      listed: docCollection(listed, LIMITS.plans, config),
+      stale: docCollection(stale, LIMITS.plans, config),
+      hubs: docCollection(hubs, LIMITS.hubs, config),
+    },
+    issues: {
+      errors: boundedCollection(errors, LIMITS.issues),
+      warnings: boundedCollection(warnings, LIMITS.issues),
+    },
+    ...(options.skippedHooks?.length ? {
+      validationPreview: { status: 'built-in-only', skippedHooks: [...options.skippedHooks] },
+    } : {}),
+  };
+  for (const section of AGENT_CONTEXT_SECTIONS) if (!sections.includes(section)) delete context[section];
+  return enforceByteBudget(context, maxBytes);
+}

package/src/ai.mjs

@@ -0,0 +1,30 @@
+import { generate } from './model.mjs';
+
+// Model-backed text for summaries and lint. The server applies each model's
+// own chat template, so prompts are plain system and user messages.
+// `runlist model` shows which model runs and where.
+
+export function runModel(prompt, opts = {}) {
+  const { system, ...rest } = opts;
+  const messages = system ? [{ role: 'system', content: system }, { role: 'user', content: prompt }] : [{ role: 'user', content: prompt }];
+  const text = generate(messages, rest);
+  return text ? text.replace(/\*\*/g, '').replace(/^#+\s*/gm, '').trim() : null;
+}
+
+export function summarizeDocBody(bodyText, meta, opts = {}) {
+  if (!bodyText?.trim()) return null;
+  const prompt = `Write a 2-3 sentence plain text summary of this document. State what it covers, its current state (${meta.status}), and what remains to be done. No markdown formatting. No bold, headers, or bullets. Do not start with "This document" or "Here is".
+
+Title: ${meta.title}
+${bodyText.slice(0, 6000)}`;
+  return runModel(prompt, {
+    system: 'You write brief, direct summaries. No preamble. No filler. Start with the subject immediately.',
+    maxTokens: 200,
+    ...opts,
+  });
+}
+
+export function summarizeDiffText(diffText, filePath, model) {
+  const prompt = `Summarize this git diff in 1-2 sentences. Focus on what changed semantically, not line counts.\n\nFile: ${filePath}\n\n${diffText.slice(0, 4000)}`;
+  return runModel(prompt, { model, maxTokens: 150 });
+}

package/src/app-create.mjs

@@ -0,0 +1,169 @@
+import {createHash} from 'node:crypto';
+import {existsSync, lstatSync, mkdirSync, readFileSync, readdirSync} from 'node:fs';
+import path from 'node:path';
+import {appDocumentTemplates, catchAllRoot, renderAppDocument} from './new.mjs';
+import {readTemplateStore} from './template-store.mjs';
+import {parseDocFile} from './index.mjs';
+import {extractFrontmatter, parseSimpleFrontmatter} from './frontmatter.mjs';
+import {authorizeManagedDestination, authorizeRepoGeneratedPath} from './managed-path.mjs';
+import {createFileExclusive, replaceSnapshot, snapshotFile, withPathLocks} from './atomic-mutation.mjs';
+import {SourceEditError, assertPrivateEditorStorage, sourceRevision} from './source-editor.mjs';
+import {stateDir} from './naming.mjs';
+import {parseNativeRecord} from './native-record.mjs';
+import {recordSettings,recordSettingsPath,recordSettingsText,renderNewRecord,assertRecordTrackable} from './record-create.mjs';
+
+const uuid=/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/;
+const fail=(code,message)=>{throw new SourceEditError(code,message);};
+const hash=value=>createHash('sha256').update(value).digest('hex');
+const json=value=>JSON.stringify(value,null,2)+'\n';
+
+/** Reviewed, exclusive creation. The renderer never supplies the committed source. */
+export function createAppDocuments({config,actor,library}) {
+  const directory=path.join(stateDir(config.repoRoot),'editor','creations');
+  const initialConfig=config.configPath?hash(readFileSync(config.configPath)):null;
+  function safe(file) {
+    const checked=authorizeRepoGeneratedPath(file,config).path;
+    let current=config.repoRoot;
+    for(const part of path.relative(config.repoRoot,checked).split(path.sep)) {
+      current=path.join(current,part);
+      try{if(lstatSync(current).isSymbolicLink())fail('unsafe-local-state','Creation reviews may not traverse symlinks.');}
+      catch(error){if(error.code!=='ENOENT')throw error;}
+    }
+    return checked;
+  }
+  function location(id){if(!uuid.test(id??''))fail('invalid-id','A UUID v4 creation operation is required.');return safe(path.join(directory,id+'.json'));}
+  function read(id) {
+    const file=location(id);if(!existsSync(file))return null;
+    try {
+      if(!lstatSync(file).isFile()||lstatSync(file).size>2*1024*1024)throw new Error('size');
+      const value=JSON.parse(readFileSync(file,'utf8'));
+      if(value.schema!==1||value.id!==id||!['reviewed','prepared','committed','discarded'].includes(value.state)||!value.actor||typeof value.path!=='string'||sourceRevision(value.source)!==value.revision)throw new Error('schema');
+      if(value.native!==undefined){
+        const parsed=parseNativeRecord(value.source),record=parsed.record;
+        if(value.native!==true||!parsed.ok||!['flag','decision'].includes(record.type)||record.status!=='open'||record.record_data.created_by.id!==value.actor.id||record.record_data.created_by.kind!==value.actor.kind||typeof value.recordShared!=='boolean'||value.recordGuard!==null&&!/^sha256:[a-f0-9]{64}$/.test(value.recordGuard))throw new Error('native schema');
+        if(value.setup){
+          if(value.setup.path!=='runlist.records.json'||typeof value.setup.source!=='string'||Buffer.byteLength(value.setup.source)>16384)throw new Error('setup');
+          const settings=JSON.parse(value.setup.source),folder=record.type==='flag'?'flags':'decisions';
+          if(settings.schema!==1||settings.repositoryId!==record.record_data.repository_id||settings.shared!==false||value.path.slice(0,value.path.lastIndexOf('/'))!==`${settings.root}/${folder}`)throw new Error('setup identity');
+        }
+      }
+      return value;
+    }catch{fail('state-corrupt','The creation review needs inspection; it will not be overwritten.');}
+  }
+  function own(context,value){const who=actor(context);if(who.kind!=='human'||who.id!==value.actor.id||who.kind!==value.actor.kind)fail('forbidden','This creation review belongs to another user.');}
+  function write(value) {
+    safe(directory);assertPrivateEditorStorage(config.repoRoot,directory);mkdirSync(directory,{recursive:true,mode:0o700});safe(directory);
+    const file=location(value.id);
+    if(existsSync(file))replaceSnapshot(snapshotFile(file),json(value),{repoRoot:config.repoRoot,locked:true});
+    else createFileExclusive(file,json(value),{repoRoot:config.repoRoot,mode:0o600,locked:true});
+  }
+  function destination(relative) {
+    if(typeof relative!=='string'||path.isAbsolute(relative)||relative.includes('\\')||relative.split('/').some(p=>!p||p==='.'||p==='..'||p==='prompts'||p==='.git'||config.excludeDirs?.has(p)))fail('invalid-path','Choose a Markdown destination within the configured document roots.');
+    const file=path.resolve(config.repoRoot,relative);
+    if(file===config.indexPath)fail('invalid-path','The generated index is not a document destination.');
+    return authorizeManagedDestination(file,config).path;
+  }
+  const guards=()=>{const current=config.configPath?hash(readFileSync(config.configPath)):null;if(current!==initialConfig)fail('creation-review-stale','Configuration changed. Reopen the checkout before creating a document.');return {templates:readTemplateStore(config).revision,config:current};};
+  async function options(){
+    const catalog=appDocumentTemplates(config),roots=(config.docsRoots??[config.docsRoot]).map(root=>path.relative(config.repoRoot,root).split(path.sep).join('/'));
+    const templates=catalog.templates.filter(t=>config.validTypes.has(t.type)).map(t=>{
+      const target=t.type==='plan'?(config.docsRoots??[config.docsRoot]).find(r=>path.basename(r)==='plans'):null;
+      const folder=target??(t.type==='plan'?path.join(catchAllRoot(config),'plans'):catchAllRoot(config));
+      const statuses=[...(config.typeStatuses?.get(t.type)??config.validStatuses)].filter(s=>s!=='in-session'&&!config.lifecycle.archiveStatuses.has(s));
+      return {...t,folder:path.relative(config.repoRoot,folder).split(path.sep).join('/'),statuses,defaultStatus:statuses.includes(t.defaultStatus)?t.defaultStatus:statuses[0]};
+    });
+    let records=null,recordError=null;
+    try{
+      records=recordSettings(config,safe,destination);
+      if(records.needsSetup){const existing=(await library?.all()??[]).flatMap(row=>row.recordRepositoryId?[row.recordRepositoryId]:[]);records=recordSettings(config,safe,destination,existing);}
+      for(const type of ['flag','decision'])templates.push({name:type,type,native:true,origin:'Native Markdown',description:type==='flag'?'A finding to triage, with its original context.':'An open question with described alternatives and consequences.',folder:`${records.root}/${type==='flag'?'flags':'decisions'}`,statuses:['open'],defaultStatus:'open'});
+    }catch(error){recordError=error.message;}
+    return {...catalog,roots,templates,records,recordError};
+  }
+  function publicReview(value){const parsed=value.native?parseNativeRecord(value.source):null;return {operationId:value.id,state:value.state,path:value.path,source:value.source,revision:value.revision,diagnostics:value.diagnostics,...(parsed?{record:parsed.record,setup:value.setup??null}:{})};}
+  async function preview(context,request) {
+    const who=actor(context);if(who.kind!=='human'||!who.id)fail('forbidden','Document creation requires a local human.');
+    const catalog=await options(),template=catalog.templates.find(t=>t.name===request.template);
+    if(!template)fail('invalid-template',catalog.recordError??'Choose an available document or record template.');
+    if(typeof request.title!=='string'||!request.title.trim()||request.title.length>200||/[\r\n\0]/.test(request.title))fail('invalid-request','Give the document a single-line title, up to 200 characters.');
+    if(typeof request.filename!=='string'||!/^[a-z0-9][a-z0-9_-]{0,119}\.md$/.test(request.filename))fail('invalid-path','Use a Markdown filename with letters, numbers, hyphens or underscores.');
+    if(!template.statuses.includes(request.status))fail('invalid-status','Choose a configured initial status.');
+    if(typeof request.body!=='string'||Buffer.byteLength(request.body)>256*1024||request.body.includes('\0'))fail('invalid-source','Initial content must be text smaller than 256 KiB.');
+    const fields=[request.template,request.title,request.filename,request.folder,request.status,request.body];
+    if(template.native)fields.push(request.severity,request.options);
+    const requestHash=hash(JSON.stringify(fields));
+    const prior=read(request.operationId);if(prior){own(context,prior);if(prior.requestHash!==requestHash)fail('operation-reused','This creation ID already belongs to another review.');return publicReview(prior);}
+    const relative=`${request.folder}/${request.filename}`,file=destination(relative);
+    if(existsSync(file))fail('creation-conflict','A file already exists at this destination. Choose another filename.');
+    const today=new Date().toISOString();
+    let source,setup=null,native=false,recordGuard=null,recordShared=false,diagnostics=[];
+    if(template.native){
+      if(request.folder!==template.folder)fail('invalid-path','Create records in their configured flag or decision folder.');
+      const settings=catalog.records;assertRecordTrackable(config,file,settings.shared);
+      ({source,setup}=renderNewRecord(request,who,settings,today));native=true;recordGuard=settings.revision;recordShared=settings.shared;
+      if(setup)assertRecordTrackable(config,safe(recordSettingsPath(config)),settings.shared);
+    }else{
+    source=renderAppDocument(request.template,{title:request.title.trim(),status:request.status,today,bodyInput:request.body},config);
+    const warnings=[],fm=parseSimpleFrontmatter(extractFrontmatter(source).frontmatter,warnings);
+    if(warnings.length||fm.type!==template.type||fm.status!==request.status||fm.record_schema!==undefined)fail('invalid-template','Repair the template metadata before creating a document.');
+    const parsed=parseDocFile(file,config,{source});diagnostics=[...parsed.errors,...parsed.warnings].map(d=>({level:d.level,message:d.message}));
+    if(parsed.errors.length)throw new SourceEditError('invalid-record','The new document fails checkout validation.',{diagnostics});
+    }
+    const value={schema:1,id:request.operationId,state:'reviewed',actor:who,path:relative,source,revision:sourceRevision(source),requestHash,guards:guards(),diagnostics,at:today,...(native?{native,setup,recordGuard,recordShared}:{})};
+    return withPathLocks([location(value.id)],{repoRoot:config.repoRoot},()=>{
+      const prior=read(value.id);if(prior){own(context,prior);if(prior.requestHash!==requestHash)fail('operation-reused','This creation ID already belongs to another review.');return publicReview(prior);}
+      write(value);return publicReview(value);
+    });
+  }
+  function inspect(context,{operationId}) {
+    const value=read(operationId);if(!value)return null;own(context,value);const file=destination(value.path);
+    let currentRevision=null;
+    if(existsSync(file)) {if(lstatSync(file).isSymbolicLink()||!lstatSync(file).isFile()||lstatSync(file).size>8*1024*1024)fail('creation-conflict','The destination is unavailable for inspection.');currentRevision=sourceRevision(readFileSync(file,'utf8'));}
+    return {...publicReview(value),currentRevision};
+  }
+  function commit(context,{operationId}) {
+    const prior=read(operationId);if(!prior)fail('operation-missing','Review the document before creating it.');own(context,prior);
+    return withPathLocks([location(operationId),destination(prior.path),...(prior.native?[safe(recordSettingsPath(config))]:[])],{repoRoot:config.repoRoot},()=>{
+      const value=read(operationId);own(context,value);const file=destination(value.path);
+      if(value.state==='discarded')fail('creation-discarded','This review was discarded. Prepare a new document.');
+      if(value.state==='committed')return {...publicReview(value),replayed:true};
+      if(value.native){
+        if(JSON.stringify(value.guards)!==JSON.stringify(guards()))fail('creation-review-stale','Configuration changed. Review a new record.');
+        const metadataSource=recordSettingsText(config,safe),current=metadataSource===null?null:sourceRevision(metadataSource);
+        const recovered=value.state==='prepared'&&value.setup&&current===sourceRevision(value.setup.source);
+        if(current!==value.recordGuard&&!recovered)fail('creation-review-stale','Record settings changed. Review the record again.');
+        assertRecordTrackable(config,file,value.recordShared);
+      }
+      if(value.state==='prepared'&&existsSync(file)) {
+        const current=inspect(context,{operationId});
+        if(current.currentRevision!==value.revision)fail('creation-uncertain','The destination differs from the reviewed source. Inspect it; it will not be overwritten.');
+      } else {
+        if(existsSync(file))fail('creation-conflict','Another file appeared at this destination. It will not be overwritten.');
+        if(JSON.stringify(value.guards)!==JSON.stringify(guards()))fail('creation-review-stale','Configuration or templates changed. Review a new document before creating it.');
+        value.state='prepared';write(value);
+        if(value.setup){const metadata=safe(recordSettingsPath(config)),source=recordSettingsText(config,safe);if(source===null)createFileExclusive(metadata,value.setup.source,{repoRoot:config.repoRoot,locked:true});else if(sourceRevision(source)!==sourceRevision(value.setup.source))fail('creation-uncertain','Record setup differs from this review. Inspect it before continuing.');}
+        mkdirSync(path.dirname(file),{recursive:true});destination(value.path);
+        createFileExclusive(file,value.source,{repoRoot:config.repoRoot,locked:true});
+      }
+      if(value.setup){const metadata=safe(recordSettingsPath(config)),source=recordSettingsText(config,safe);if(source===null)createFileExclusive(metadata,value.setup.source,{repoRoot:config.repoRoot,locked:true});else if(sourceRevision(source)!==sourceRevision(value.setup.source))fail('creation-uncertain','Record setup differs from this review. Inspect it before continuing.');}
+      value.state='committed';write(value);return publicReview(value);
+    });
+  }
+  function discard(context,{operationId}) {
+    return withPathLocks([location(operationId)],{repoRoot:config.repoRoot},()=>{
+      const value=read(operationId);if(!value)return {discarded:true};own(context,value);
+      if(!['reviewed','discarded'].includes(value.state))fail('creation-uncertain','Inspect this creation outcome before dismissing it.');
+      value.state='discarded';write(value);return {discarded:true};
+    });
+  }
+  function list(context) {
+    safe(directory);if(!existsSync(directory))return {items:[],unavailable:0};
+    const items=[];let unavailable=0;
+    for(const name of readdirSync(directory).filter(n=>n.endsWith('.json')&&uuid.test(n.slice(0,-5)))) {
+      try{const value=read(name.slice(0,-5));if(value.actor.id!==actor(context).id||!['reviewed','prepared'].includes(value.state))continue;own(context,value);destination(value.path);items.push({kind:'creation',path:value.path,operationId:value.id,state:value.state,at:value.at,available:true});}
+      catch{unavailable++;}
+    }
+    return {items,unavailable};
+  }
+  return {options,preview,commit,inspect,discard,list};
+}

package/src/app-filing.mjs

@@ -0,0 +1,139 @@
+import { randomUUID } from 'node:crypto';
+import { setImmediate as yieldThread } from 'node:timers/promises';
+import { assembleFilingCoverage, filingLiveHub, filingOptions, filingParentTarget, prepareFilingHub } from './filing.mjs';
+import { SourceEditError } from './source-editor.mjs';
+
+const detached = value => JSON.parse(JSON.stringify(value));
+const number = (params, key, fallback, max) => {
+  const value = Number(params.get(key) ?? fallback);
+  return Number.isInteger(value) && value >= 0 ? Math.min(value, max) : fallback;
+};
+const multiple = plan => plan.rows.length > 1 || new Set(plan.rows.flatMap(row => row.categories)).size > 1;
+const noCategory = plan => plan.rows.some(row => !row.categories.length);
+
+/** One private, read-only report per checkout. No scan happens during creation. */
+export function createAppFiling({ config, library, readSource }) {
+  let scan = null, epoch = 0, advancing = null;
+  function invalidate() { epoch++; scan = null; }
+  function summary(current = scan) {
+    if (!filingOptions(config.filing)) return { enabled: false, state: 'disabled', complete: false, reason: 'Filing reports are not enabled in this repository configuration.' };
+    if (!current) return { enabled: true, state: 'idle', complete: false };
+    return { enabled: true, scanId: current.id, generation: current.generation, state: current.report ? current.report.complete ? 'complete' : 'incomplete' : 'scanning',
+      complete: current.report?.complete ?? false, progress: { done: current.index, total: current.documents.length },
+      totals: current.report?.complete ? current.report.totals : null,
+      failures: current.failures.slice(0, 50), failureCount: current.failures.length };
+  }
+  async function inventory(force = false) { return library.filingInventory({ refresh: force }); }
+  function requireScan(params) {
+    if (!scan || params.get('scanId') !== scan.id) throw new SourceEditError('filing-scan-stale', 'The filing report changed. Refresh it before continuing.');
+    return scan;
+  }
+  function finish(current) {
+    current.report = assembleFilingCoverage(current.documents, config, current.rows, current.parents,
+      { complete: current.inventoryComplete, failures: current.failures });
+    current.rows = null;
+    current.parents = null;
+  }
+  async function start(params) {
+    const ticket = epoch;
+    const observed = await inventory(params.get('refresh') === '1');
+    if (ticket !== epoch) throw new SourceEditError('filing-scan-stale', 'Saved files changed. Refresh the filing report.');
+    if (scan?.generation === observed.generation && params.get('refresh') !== '1') return summary();
+    const documents = observed.documents.map(doc => detached({ ...doc, path: doc.repoPath ?? doc.path }));
+    scan = { id: randomUUID(), epoch, generation: observed.generation, documents, byPath: new Map(documents.map(doc => [doc.path, doc])), index: 0, rows: [], parents: new Map(), revisions: new Map(),
+      inventoryComplete: observed.complete, failures: detached(observed.failures ?? []), report: null };
+    if (!documents.length) finish(scan);
+    return summary();
+  }
+  async function currentScan(params) {
+    const current = requireScan(params), observed = await inventory();
+    if (current !== scan || observed.generation !== current.generation || current.epoch !== epoch) {
+      if (current === scan) invalidate();
+      throw new SourceEditError('filing-scan-stale', 'Saved files changed. Refresh the filing report.');
+    }
+    return current;
+  }
+  async function advance(params, context) {
+    if (advancing) { await advancing; return summary(await currentScan(params)); }
+    const current = await currentScan(params);
+    if (current.report) return summary(current);
+    advancing = (async () => {
+      const end = Math.min(current.documents.length, current.index + 8);
+      while (current.index < end) {
+        const doc = current.documents[current.index++];
+        current.parents.set(doc.path, filingParentTarget(doc, config));
+        if (filingLiveHub(doc, config)) {
+          try {
+            const opened = await readSource(doc.path, context);
+            if (doc.stamp && opened.stamp !== doc.stamp) throw new Error('changed since inventory');
+            if (Buffer.byteLength(opened.source) > 8 * 1024 * 1024) throw new Error('oversized');
+            const rows = prepareFilingHub(doc, opened.source, config);
+            if (current.rows.length + rows.length > 100_000) throw new Error('too many rows');
+            current.rows.push(...detached(rows));
+            current.revisions.set(doc.path, opened.revision);
+          } catch {
+            current.failures.push({ path: doc.path, message: 'Hub source is unavailable, changed, unsafe or exceeds report limits.' });
+          }
+        }
+        await yieldThread();
+        if (current !== scan || current.epoch !== epoch) throw new SourceEditError('filing-scan-stale', 'Saved files changed. Refresh the filing report.');
+      }
+      await currentScan(params);
+      if (current.index === current.documents.length) finish(current);
+      return summary(current);
+    })();
+    try { return await advancing; } finally { advancing = null; }
+  }
+  function planSummary(plan, current) {
+    const doc = current.byPath.get(plan.path);
+    return { path: plan.path, title: String(doc?.title ?? plan.path).slice(0, 300), status: plan.status,
+      filing: current.report.complete ? plan.filing : plan.rows.length ? 'observed' : 'unknown',
+      filedThrough: plan.filedThrough, homeCount: plan.rows.length,
+      multiplyFiled: current.report.complete ? multiple(plan) : null, noCategory: current.report.complete ? noCategory(plan) : null };
+  }
+  async function page(params) {
+    const current = await currentScan(params);
+    if (!current.report) return { ...summary(current), plans: [], total: 0, offset: 0, limit: 50, hasMore: false };
+    const group = params.get('group') ?? 'all';
+    if (!['all', 'unfiled', 'multiple', 'no-category', 'parent', 'direct'].includes(group)) throw new SourceEditError('invalid-request', 'Choose a supported filing filter.');
+    const words = (params.get('q') ?? '').slice(0, 500).toLowerCase().trim().split(/\s+/).filter(Boolean);
+    const documents = new Map(current.documents.map(doc => [doc.path, doc]));
+    const matches = current.report.plans.filter(plan =>
+      (group === 'all' || current.report.complete && (group === 'unfiled' ? plan.filing === 'unfiled' : group === 'multiple' ? multiple(plan) : group === 'no-category' ? noCategory(plan) : plan.filing === group)) &&
+      words.every(word => `${plan.path} ${documents.get(plan.path)?.title ?? ''} ${plan.status}`.toLowerCase().includes(word))).sort((a, b) => a.path.localeCompare(b.path));
+    const limit = Math.max(1, number(params, 'limit', 50, 50));
+    const offset = Math.min(number(params, 'offset', 0, 10_000_000), Math.max(0, Math.floor((matches.length - 1) / limit) * limit));
+    return { ...summary(current), plans: matches.slice(offset, offset + limit).map(plan => planSummary(plan, current)), total: matches.length, offset, limit, hasMore: offset + limit < matches.length,
+      reason: !current.report.complete && group !== 'all' ? 'Filing findings are unavailable until a complete scan can be made. Select All plans to inspect observed evidence.' : null };
+  }
+  async function detail(params, context) {
+    const current = await currentScan(params);
+    const plan = current.report?.plans.find(plan => plan.path === params.get('path'));
+    if (!plan) throw new SourceEditError('filing-plan-unavailable', 'This plan is unavailable in the filing report. Refresh the report.');
+    const limit = Math.max(1, number(params, 'homeLimit', 20, 20));
+    const offset = Math.min(number(params, 'homeOffset', 0, 100_000), Math.max(0, Math.floor((plan.rows.length - 1) / limit) * limit));
+    const sources = new Map(), homes = [];
+    for (const row of plan.rows.slice(offset, offset + limit)) {
+      if (!sources.has(row.hub)) {
+        try { sources.set(row.hub, (await readSource(row.hub, context)).revision === current.revisions.get(row.hub) ? 'unchanged' : 'changed'); }
+        catch { sources.set(row.hub, 'unavailable'); }
+      }
+      homes.push({ ...row, categories: row.categories.slice(0, 100).map(category => category.slice(0, 300)),
+        categoriesShortened: row.categories.length > 100 || row.categories.some(category => category.length > 300),
+        category: row.category?.slice(0, 300) ?? null, revision: current.revisions.get(row.hub), current: sources.get(row.hub) });
+    }
+    await currentScan(params);
+    return { ...summary(current), ...planSummary(plan, current), homes, totalHomes: plan.rows.length, homeOffset: offset, homeLimit: limit, hasMoreHomes: offset + limit < plan.rows.length };
+  }
+  async function request(params = new URLSearchParams(), context) {
+    if (!filingOptions(config.filing)) return summary();
+    const op = params.get('op') ?? 'status';
+    if (op === 'start') return start(params);
+    if (op === 'advance') return advance(params, context);
+    if (op === 'status') return params.has('scanId') ? summary(await currentScan(params)) : summary();
+    if (op === 'page') return page(params);
+    if (op === 'detail') return detail(params, context);
+    throw new SourceEditError('invalid-request', 'Choose a supported filing report operation.');
+  }
+  return { request, invalidate };
+}

package/src/app-git-commits.mjs

@@ -0,0 +1,48 @@
+import {commitPlatformQualified} from './git-commit-support.mjs';
+import {fork} from 'node:child_process';
+import {realpathSync} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import path from 'node:path';
+import {gitEnvironment} from './app-git.mjs';
+import {commitStore,uuid,fail,hash} from './git-commit-store.mjs';
+import {run} from './git-commit-protocol.mjs';
+import {currentProcessOwner,processStartIdentity,processOwnerLiveness} from './atomic-mutation.mjs';
+// Jobs survive renderer/helper disconnect; no operation ID is ever replayed.
+const children=new Map();
+function stopped(r){if(!r.workerOwner)return r.state==='reviewed'||r.state==='failed';if(processOwnerLiveness(r.workerOwner)!=='dead')return false;try{process.kill(-r.workerOwner.pid,0);return false;}catch(e){return e.code==='ESRCH';}}
+const publicOperation=(r,live)=>({operationId:r.id,state:r.state,running:live,path:r.rows[0]?.path??r.paths[0],paths:r.paths,message:r.message,branch:r.selectedBranch,head:r.head,tree:r.tree??null,commitId:r.commit??null,indexReady:r.indexReady??false,failure:r.failure??null,recovery:r.recovery??null,resolved:!!r.resolved,at:r.at,review:r.state==='reviewed'?r.review:[],execution:{hooks:Object.entries(r.material?.hooks?.files??{}).filter(([,entry])=>entry?.mode&0o111).map(([kind])=>kind),signing:r.material?.signing?.format??'none',filters:(r.material?.filters??[]).map(profile=>profile.name)},canCommit:r.state==='reviewed'&&!live,canRecover:!live&&r.action!=='preview'&&!r.resolved&&['not-committed','committed-index-recovery','committed'].includes(r.state),observedRef:r.observedRef??null,observedIndex:r.observedIndex??null,canSettle:!live&&!r.resolved&&['uncertain-ref-publication','uncertain-external-ref','committed-external-ref'].includes(r.state)&&typeof r.observedRef==='string'&&typeof r.observedIndex==='string',expiresAt:r.expiresAt??null});
+export function createAppGitCommits({config,actor,authenticate,git}){
+ const root=realpathSync(config.repoRoot),store=commitStore(root,actor);
+ const identity=req=>{const candidate=authenticate(req);if(candidate?.kind!=='human'||candidate.id!==actor.id)fail('forbidden','Git commits belong to the authenticated checkout owner.');};
+ const platform=()=>{if(!commitPlatformQualified())fail('git-platform-unqualified','Local commits are not yet qualified on this platform and architecture. Use Git; editing and Changes remain available.');};
+ function storage(){const r={root};const relative=path.relative(root,store.directory).split(path.sep).join('/');if(run(r,['check-ignore','-q','--',relative+'/'],{allow:[0,1]}).code!==0||run(r,['ls-files','-z','--',relative]).bytes.length)fail('unsafe-local-state','Private Git operations must be ignored and untracked.');store.ensure();}
+ function live(r){return children.has(root+':'+r.id)||!stopped(r);}
+ function blocker(except){return store.all().find(r=>r.id!==except&&(live(r)||r.action!=='preview'&&!r.resolved&&!(r.state==='committed'&&r.indexReady)));}
+ function launch(id,action){
+  const token=randomUUID();let child;
+  store.update(id,r=>{r.action=action;r.launchToken=token;r.state=action==='preview'?'reviewing':action==='execute'?'starting':r.state;r.parentOwner=currentProcessOwner();delete r.finishedAt;});
+  try{
+   child=fork(new URL('./git-commit-worker.mjs',import.meta.url),[],{env:gitEnvironment(),detached:true,stdio:['ignore','ignore','ignore','ipc'],execArgv:['--max-old-space-size=192','--max-semi-space-size=4']});
+   const key=root+':'+id;children.set(key,child);
+   store.update(id,r=>{r.workerOwner={...currentProcessOwner(),pid:child.pid,processStartIdentity:processStartIdentity(child.pid)};});
+   const timer=setTimeout(()=>{try{if(processOwnerLiveness(store.read(id)?.workerOwner)==='live')process.kill(-child.pid,'SIGKILL');}catch{}},70000);timer.unref();
+   child.once('exit',()=>{clearTimeout(timer);children.delete(key);try{store.update(id,r=>{if(r.action==='preview'&&r.state==='reviewing'){r.state='failed';r.failure={code:r.cancelRequestedAt?'git-cancelled':'git-review-interrupted',message:r.cancelRequestedAt?'The review was stopped. Start a new review when ready.':'The review stopped before completion. Start a new review; no commit was executed.'};}});}catch{}});child.once('error',()=>{clearTimeout(timer);children.delete(key);try{store.update(id,r=>{r.failure={code:'git-job-start',message:'The Git job could not start. Inspect its retained receipt.'};});}catch{}});
+   child.send({root,actor,id,action,token});child.unref();child.channel?.unref();
+  }catch(error){if(child)try{process.kill(-child.pid,'SIGKILL');}catch{}store.update(id,r=>{r.failure={code:'git-job-start',message:'The Git job could not start. Inspect its retained receipt.'};if(action==='preview')r.state='failed';});throw error;}
+  return publicOperation(store.read(id),true);
+ }
+ async function preview(req,request){
+  identity(req);platform();if(!uuid.test(request.operationId??''))fail('invalid-id','Use a UUID v4 local commit review ID.');
+  if(typeof request.message!=='string'||!request.message.trim()||Buffer.byteLength(request.message)>8192||request.message.includes('\0')||Buffer.from(request.message).toString('utf8')!==request.message)fail('invalid-request','Write a UTF-8 commit message of at most 8 KiB.');
+  const message=request.message.replace(/\n?$/,'\n');if(Buffer.byteLength(message)>8192)fail('invalid-request','The complete commit message must fit in 8 KiB, including its final newline.');const requestHash=hash(JSON.stringify([request.paths,message]));
+  const previous=store.read(request.operationId);if(previous){if(previous.requestHash!==requestHash)fail('operation-reused','This operation ID already belongs to another review.');return publicOperation(previous,live(previous));}
+  const selection=await git.selection(req,request.paths);identity(req);storage();
+  return store.exclusive(()=>{const prior=store.read(request.operationId);if(prior){if(prior.requestHash!==requestHash)fail('operation-reused','This ID already belongs to another review.');return publicOperation(prior,live(prior));}if(blocker())fail('git-operation-active','Inspect the retained Git operation before starting another review.');store.create({schema:1,id:request.operationId,root,actor,requestHash,state:'reviewing',action:'preview',paths:selection.paths,authorizedSources:selection.authorizedSources,rows:selection.rows.map(row=>({path:row.path,original:row.original??null,kind:row.kind})),head:selection.head,selectedBranch:selection.branch,message,configPath:config.configPath??null,at:new Date().toISOString()});return launch(request.operationId,'preview');});
+ }
+ function inspect(req,id){identity(req);const r=store.read(id);if(!r)return null;return publicOperation(r,live(r));}
+ function start(req,{operationId}){identity(req);platform();storage();return store.exclusive(()=>{const r=store.read(operationId);if(!r)fail('git-operation-missing','Review a local commit first.');if(r.state!=='reviewed'||live(r))return publicOperation(r,live(r));if(Date.now()>r.expiresAt)fail('git-review-expired','This review expired. Review current files again.');if(blocker(operationId))fail('git-operation-active','Another retained Git operation needs inspection first.');return launch(operationId,'execute');});}
+ function job(req,{operationId,...request},action){identity(req);platform();storage();return store.exclusive(()=>{const r=store.read(operationId);if(!r)fail('git-operation-missing','The retained Git operation is missing.');if(live(r))fail('git-operation-running','The Git process group is still active or cannot be verified as stopped.');if(r.action==='preview')return publicOperation(r,false);if(action==='settle'){if(typeof request.note!=='string'||!request.note.trim()||request.note.length>4000||!/^[a-f0-9]{64}$/.test(request.expectedIndexRevision??'')||request.expectedRef!==r.observedRef||request.expectedIndexRevision!==r.observedIndex)fail('invalid-request','Acknowledge the current inspected ref/index with a note up to 4,000 characters.');store.update(operationId,d=>{d.settlementRequest={note:request.note.trim(),expectedRef:request.expectedRef,expectedIndexRevision:request.expectedIndexRevision};});}if(r.resolved&&action==='recover')return publicOperation(r,false);return launch(operationId,action);});}
+ function cancel(req,{operationId}){identity(req);platform();const r=store.read(operationId);if(!r)fail('git-operation-missing','The retained Git operation is missing.');if(live(r)){if(processOwnerLiveness(r.workerOwner)!=='live')fail('git-owner-unverified','The worker identity cannot be verified. Keep its receipt and inspect with Git.');store.update(operationId,d=>{d.cancelRequestedAt=new Date().toISOString();});try{process.kill(-r.workerOwner.pid,'SIGKILL');}catch(error){if(error.code!=='ESRCH')throw error;}}return publicOperation(store.read(operationId),live(store.read(operationId)));}
+ function list(req){identity(req);const items=[];let unavailable=0;try{for(const r of store.all())if(!r.resolved&&(r.state!=='committed'||!r.indexReady))items.push({kind:'git-commit',path:r.rows[0]?.path??r.paths[0],operationId:r.id,state:r.state,at:r.at,available:true});}catch(error){if(error.code==='forbidden')throw error;unavailable++;}return {items,unavailable};}
+ return {preview,start,inspect,inspectJob:(req,body)=>job(req,body,'inspect'),recover:(req,body)=>job(req,body,'recover'),cancel,settle:(req,body)=>job(req,body,'settle'),list};
+}