runlist 0.0.0 → 0.94.1

package/src/app-search.mjs

@@ -0,0 +1,80 @@
+import { libraryKind, matchesLibraryStage, sortLibraryRows } from './app-library.mjs';
+import { readPlanStage, readShipsFrontmatter } from './stages.mjs';
+import {open} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {StringDecoder} from 'node:string_decoder';
+import path from 'node:path';
+import {extractFrontmatter,parseSimpleFrontmatter} from './frontmatter.mjs';
+import {authorizeManagedSource} from './managed-path.mjs';
+
+const detached=value=>JSON.parse(JSON.stringify(value));
+
+// On-demand streaming search. No document bodies or content index are retained.
+export async function searchCheckout(config,library,params) {
+  const words=(params.get('q')??'').slice(0,500).toLowerCase().trim().split(/\s+/).filter(Boolean);
+  const limit=Math.max(1,Math.min(100,Math.floor(Number(params.get('limit'))||50)));
+  const requestedOffset=Math.max(0,Math.floor(Number(params.get('offset'))||0));
+  const all=await library.all(),rows=all.filter(r=>(params.get('archived')==='1'||!r.archived)
+    &&(!params.get('kind')||params.get('kind')==='all'||params.get('kind')==='plans'&&r.kind==='plan'||params.get('kind')==='hubs'&&r.kind==='hub'||params.get('kind')==='documents'&&r.kind==='document')
+    &&matchesLibraryStage(r,params.get('stage'))
+    &&(!params.get('status')||r.status===params.get('status'))&&(!params.get('type')||r.type===params.get('type'))
+    &&(!params.get('folder')||r.folder===params.get('folder')||r.folder.startsWith(params.get('folder')+'/')));
+  sortLibraryRows(rows,params,config);
+  const documents=[],sections=[];let scanned=0,unavailable=0,bytesRead=0,total=0,partial=false,index=0;
+  if(!words.length)return {documents:rows.slice(requestedOffset,requestedOffset+limit),sections:[],total:rows.length,offset:requestedOffset,limit,hasMore:requestedOffset+limit<rows.length,scanned:0,inventoryTotal:rows.length,partial:false,unavailable:0};
+  const budget=128*1024*1024;
+  const worker=async()=>{
+    while(index<rows.length) {
+      if(bytesRead>=budget){partial=true;return;}
+      const row=rows[index++];let fd;
+      try {
+        const file=authorizeManagedSource(path.resolve(config.repoRoot,row.path),config).path;
+        fd=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW??0));const stamp=await fd.stat();
+        if(!stamp.isFile()||stamp.size>8*1024*1024){unavailable++;continue;}
+        const buffer=Buffer.alloc(64*1024),decoder=new StringDecoder('utf8');let offset=0,carry='',lineCarry='',bodyLine=0,fence=null,comment=false,frontmatter=false,first=true,excerpt='';
+        const found=new Set(),headings=[];let rejected=false;
+        const metadata=`${row.title} ${row.path} ${row.status} ${row.type} ${row.modules.join(' ')}`.toLowerCase();
+        words.forEach(w=>{if(metadata.includes(w))found.add(w);});
+        function line(raw){
+          if(bodyLine===0&&raw==='---'&&!frontmatter){frontmatter=true;return;}
+          if(frontmatter){if(raw==='---')frontmatter=false;return;}
+          bodyLine++;
+          if(raw.includes('<!--'))comment=true;
+          const marker=raw.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+          if(marker&&!comment){if(!fence)fence=marker[1];else if(marker[1][0]===fence[0]&&marker[1].length>=fence.length&&!marker[2].trim())fence=null;}
+          const match=!fence&&!comment&&raw.match(/^ {0,3}#{1,6}\s+(.*?)(?:\s+#+\s*)?$/);
+          if(match&&words.every(w=>match[1].toLowerCase().includes(w))&&headings.length<8)headings.push({path:row.path,title:detached(match[1].slice(0,200)),line:bodyLine});
+          if(raw.includes('-->'))comment=false;
+        }
+        while(offset<stamp.size) {
+          if(bytesRead>=budget){partial=true;break;}
+          const {bytesRead:count}=await fd.read(buffer,0,buffer.length,offset);if(!count)break;offset+=count;bytesRead+=count;
+          const chunk=decoder.write(buffer.subarray(0,count));
+          if(first){
+            first=false;const parts=extractFrontmatter(chunk),header=parseSimpleFrontmatter(parts.frontmatter);
+            // Re-check current metadata, even when a cached library row predates a type change.
+            if(header.type==='prompt'||/^---\r?\n/.test(chunk)&&!parts.bodyLineOffset){unavailable++;rejected=true;break;}
+            row.kind=libraryKind(header,row.path);
+            if(row.kind==='plan'){const stage=readPlanStage(readShipsFrontmatter(parts.frontmatter));row.stage=stage.word;row.stageInvalid=stage.invalid;}else{delete row.stage;delete row.stageInvalid;}
+            if(!matchesLibraryStage(row,params.get('stage'))||params.get('kind')==='plans'&&row.kind!=='plan'){rejected=true;break;}
+          }
+          const haystack=(carry+chunk).toLowerCase();
+          for(const word of words){const at=haystack.indexOf(word);if(at>=0){found.add(word);if(!excerpt)excerpt=(carry+chunk).slice(Math.max(0,at-65),at+165).replace(/\s+/g,' ').slice(0,240);}}
+          carry=chunk.slice(-500);
+          const lines=(lineCarry+chunk).split('\n');lineCarry=lines.pop();for(const raw of lines)line(raw.replace(/\r$/,''));
+          // A pathological single-line file must not accumulate the entire body.
+          if(lineCarry.length>4096)lineCarry=lineCarry.slice(-4096);
+        }
+        if(rejected||offset<stamp.size)continue;
+        line(lineCarry+decoder.end());scanned++;
+        if(found.size===words.length){total++;documents.push({...row,excerpt:detached(excerpt)});}
+        for(const heading of headings)if(sections.length<limit)sections.push(heading);
+      }catch{unavailable++;}finally{await fd?.close();}
+    }
+  };
+  await Promise.all(Array.from({length:4},worker));
+  sortLibraryRows(documents,params,config);
+  sections.sort((a,b)=>a.path.localeCompare(b.path)||a.line-b.line);
+  const offset=Math.min(requestedOffset,Math.max(0,Math.floor((documents.length-1)/limit)*limit));
+  return {documents:documents.slice(offset,offset+limit),sections,total,offset,limit,hasMore:offset+limit<total,scanned,inventoryTotal:rows.length,partial,unavailable,bytesRead};
+}

package/src/app-semantic-search.mjs

@@ -0,0 +1,105 @@
+import {createHash,randomUUID} from 'node:crypto';
+import {existsSync,readFileSync,realpathSync,lstatSync,statSync,readdirSync,mkdirSync,writeFileSync,renameSync,unlinkSync,constants} from 'node:fs';
+import {open} from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import {authorizeManagedSource} from './managed-path.mjs';
+import {extractFrontmatter,parseSimpleFrontmatter,normalizeEol} from './frontmatter.mjs';
+import {extractFirstHeading} from './extractors.mjs';
+import {sourceRevision,SourceEditError} from './source-editor.mjs';
+import {readPlanStage,readShipsFrontmatter} from './stages.mjs';
+import {libraryKind,matchesLibraryStage} from './app-library.mjs';
+import {withSemanticClient} from './semantic-search-client.mjs';
+
+const inside=(root,file)=>{const rel=path.relative(root,file);return rel!== '..'&&!rel.startsWith(`..${path.sep}`)&&!path.isAbsolute(rel);};
+const messages={tool_missing:'gmax is optional and is not installed. Exact search is available.',tool_unavailable:'gmax could not be opened. Check its paths in Settings or update it for existing-index-only search.',unsupported_tool:'This gmax installation does not support existing-index-only document search. Update gmax externally, then retry.',unsupported_daemon:'The running gmax daemon needs the existing-index-only contract. Update it externally, then retry.',no_index:'This checkout has no matching gmax index. Add it through gmax externally, then retry.',index_unavailable:'This gmax index is not ready. Exact search is available.',daemon_unavailable:'Start gmax externally, then retry. Runlist does not start its services.',store_unavailable:'This index store is unavailable to the existing-index-only integration.',embedding_unavailable:'gmax has no available warm embedding worker. Finish its startup or current work externally, then retry.',embedding_mismatch:'The index and embedding runtime do not match. Repair through gmax externally.',host_pressure:'gmax declined the request because host resources could not be admitted. Exact search is available.',busy:'gmax is busy. Retry when its current work finishes.',cancelled:'Semantic search cancelled.',timeout:'Semantic search timed out. Narrow the query or retry.',no_coverage:'No indexed Markdown was found in the checked document scope. Check gmax indexing rules externally.',invalid_response:'gmax returned an unsupported response. Exact search is available.',response_too_large:'gmax returned too much data. Narrow the document scope.',tool_changed:'The saved gmax installation changed. Select its paths again in Settings.',search_unavailable:'Semantic search is unavailable. Exact search is available.'};
+const failure=state=>{state=Object.hasOwn(messages,state)?state:'search_unavailable';return {state,message:messages[state],documents:[],sections:[]};};
+function validateInstallation(value){
+ if(!value||typeof value.nodePath!=='string'||typeof value.entryPath!=='string'||!path.isAbsolute(value.nodePath)||!path.isAbsolute(value.entryPath)||value.nodePath.length>4096||value.entryPath.length>4096)throw new SourceEditError('invalid-request','Use absolute paths for the external Node executable and gmax entry file.');
+ const nodePath=realpathSync(value.nodePath),entryPath=realpathSync(value.entryPath),node=statSync(nodePath),entry=statSync(entryPath);
+ if(!node.isFile()||!entry.isFile()||entry.size>1024*1024||!['.js','.mjs','.cjs'].includes(path.extname(entryPath)))throw new Error('invalid installation');
+ const packagePath=path.resolve(path.dirname(entryPath),'../package.json');
+ if(statSync(packagePath).size>65536||!['node','node.exe'].includes(path.basename(nodePath)))throw new Error('invalid runtime');
+ const packageBytes=readFileSync(packagePath),pkg=JSON.parse(packageBytes.toString('utf8'));
+ if(pkg.name!=='grepmax')throw new Error('not gmax');
+ return {nodePath,entryPath,identity:`${node.dev}:${node.ino}:${node.size}:${node.mtimeMs}:${createHash('sha256').update(readFileSync(entryPath)).update(packageBytes).digest('hex')}`,version:pkg.version};
+}
+function discover(){
+ const candidates=[];
+ for(const directory of (process.env.PATH??'').split(path.delimiter).filter(p=>path.isAbsolute(p)))candidates.push({nodePath:path.join(directory,process.platform==='win32'?'node.exe':'node'),entryPath:path.join(directory,'gmax')});
+ const nvm=path.join(os.homedir(),'.nvm/versions/node');try{for(const version of readdirSync(nvm).filter(v=>/^v\d+\.\d+\.\d+$/.test(v)).sort((a,b)=>b.localeCompare(a,undefined,{numeric:true})).slice(0,12))candidates.push({nodePath:path.join(nvm,version,'bin/node'),entryPath:path.join(nvm,version,'lib/node_modules/grepmax/dist/bin.js')});}catch{}
+ if(process.platform==='win32')for(const prefix of [process.env.APPDATA&&path.join(process.env.APPDATA,'npm')].filter(Boolean))for(const candidate of candidates.slice(0,32))candidates.push({nodePath:candidate.nodePath,entryPath:path.join(prefix,'node_modules/grepmax/dist/bin.js')});
+ for(const candidate of candidates.slice(0,80))try{return validateInstallation(candidate);}catch{}
+ return null;
+}
+const defaultSettings=()=>path.join(process.env.XDG_CONFIG_HOME??(process.platform==='win32'?process.env.APPDATA??os.homedir():path.join(os.homedir(),'.config')),'runlist/semantic-search.json');
+export function createAppSemanticSearch({config,library,settingsFile=defaultSettings(),connect=withSemanticClient,timeoutMs=10000}){
+ const jobs=new Map();let active=null;
+ function installation(){try{if(existsSync(settingsFile)){if(lstatSync(settingsFile).isSymbolicLink()||statSync(settingsFile).size>16384)return null;const value=JSON.parse(readFileSync(settingsFile,'utf8'));if(value.nodePath&&value.entryPath){const current=validateInstallation(value);return current.identity===value.identity?current:null;}}}catch{return null;}return discover();}
+ function settings(){const selected=installation();return {available:!!selected,nodePath:selected?.nodePath??'',entryPath:selected?.entryPath??'',version:selected?.version??null,experimental:true,readiness:'not_checked',message:selected?'External gmax was found. Index and embedding readiness are checked only when you search. Semantic search is experimental; text search remains available.':messages.tool_missing};}
+ function saveSettings(body){if(Object.keys(body).some(k=>!['nodePath','entryPath'].includes(k)))throw new SourceEditError('invalid-request','Choose only the external tool paths.');
+   const dir=path.dirname(settingsFile);mkdirSync(dir,{recursive:true,mode:0o700});if(lstatSync(dir).isSymbolicLink()||existsSync(settingsFile)&&lstatSync(settingsFile).isSymbolicLink())throw new SourceEditError('unsafe-local-state','Tool settings must be ordinary local files.');
+   if(body.nodePath===''&&body.entryPath===''){if(existsSync(settingsFile))unlinkSync(settingsFile);return settings();}
+   let value;try{value=validateInstallation(body);}catch{throw new SourceEditError('invalid-request','Choose a valid external Node executable and grepmax dist/bin.js entry file.');}
+   active?.controller.abort();const temp=settingsFile+'.'+randomUUID();writeFileSync(temp,JSON.stringify(value)+'\n',{mode:0o600,flag:'wx'});renameSync(temp,settingsFile);return settings();
+ }
+ function clean(){for(const [id,job] of jobs)if(job.finished&&Date.now()-job.at>60000)jobs.delete(id);while(jobs.size>=16){const first=[...jobs].find(([,job])=>job.finished);if(!first)break;jobs.delete(first[0]);}}
+ const inspect=id=>{const job=jobs.get(id);if(!job)return failure('cancelled');return job.state==='running'?{id,state:'running'}:{id,...job.result};};
+ function cancel(id){const job=jobs.get(id);if(job?.state==='running'){job.controller.abort();job.state='complete';job.result=failure('cancelled');}return inspect(id);}
+ function start(body){
+   if(!body||Object.keys(body).some(k=>!['query','archived','kind','status','type','folder','stage'].includes(k))||typeof body.query!=='string'||body.query.length>500||!body.query.trim()||Object.values(body).some(v=>!['string','boolean'].includes(typeof v)||typeof v==='string'&&v.length>512)||body.archived!==undefined&&typeof body.archived!=='boolean'||body.stage!==undefined&&typeof body.stage!=='string')throw new SourceEditError('invalid-request','Supply a semantic query up to 500 characters and supported document filters.');
+   clean();if(jobs.size>=16)throw new SourceEditError('search-busy','Semantic search is finishing cancelled work. Retry shortly.');const previous=active;if(active?.state==='running')cancel(active.id);const job={id:randomUUID(),controller:new AbortController(),state:'running',at:Date.now(),result:null,finished:false};jobs.set(job.id,job);active=job;
+   const timer=setTimeout(()=>{job.timedOut=true;job.controller.abort();},timeoutMs);timer.unref();
+   job.done=(async()=>{await previous?.done;job.controller.signal.throwIfAborted();return run(body,job.controller.signal);})().then(value=>{if(job.state==='running'){job.result=value;job.state='complete';}},error=>{if(job.state==='running'){job.result=failure(job.timedOut?'timeout':job.controller.signal.aborted?'cancelled':error.code??'search_unavailable');job.state='complete';}}).finally(()=>{clearTimeout(timer);job.at=Date.now();job.finished=true;if(active===job)active=null;});
+   return {id:job.id,state:'running'};
+ }
+ async function run(body,signal){
+   const selected=installation();if(!selected)return failure(existsSync(settingsFile)?'tool_changed':'tool_missing');
+   const checkout=realpathSync(config.repoRoot),all=await library.all();signal.throwIfAborted();
+   let roots=(config.docsRoots??[config.docsRoot]).map(p=>realpathSync(p)).filter(p=>inside(checkout,p));
+   if(body.folder){const folder=realpathSync(path.resolve(config.repoRoot,body.folder));if(!inside(checkout,folder))return failure('no_coverage');roots=roots.flatMap(root=>inside(root,folder)?[folder]:inside(folder,root)?[root]:[]);}
+   if(!roots.length||roots.length>32)return failure('no_coverage');
+   const allowed=new Map(all.flatMap(row=>{try{return [[authorizeManagedSource(path.resolve(config.repoRoot,row.path),config).canonicalPath,row]];}catch{return [];}}));
+   const scopePaths=[...allowed.keys()].filter(p=>roots.some(root=>inside(root,p))),paths=[];let pathBytes=0;for(const p of scopePaths){pathBytes+=Buffer.byteLength(p)+8;if(paths.length>=2000||pathBytes>512*1024)break;paths.push(p);}
+   return connect(selected,checkout,signal,async client=>{
+     const status=await client.tool('document_search_status',{paths});
+     if(status.state!=='ready')return failure(status.state);
+     if(!Number.isSafeInteger(status.generation)||status.generation<1)return failure('embedding_mismatch');
+     if(!status.project||!path.isAbsolute(status.project.root)||!inside(status.project.root,checkout)||!Array.isArray(status.covered)||status.covered.length>paths.length)throw new Error('invalid status');
+     const sample=new Set(paths);if(status.covered.some(entry=>typeof entry.path!=='string'||!sample.has(entry.path)))throw new Error('invalid coverage');
+     if(!status.covered.length&&paths.length===scopePaths.length)return failure('no_coverage');
+     const response=await client.tool('semantic_search',{query:body.query.trim(),prefixes:roots});
+     if(response.state!=='ready')return failure(response.state);
+     if(response.generation!==status.generation)return failure('embedding_mismatch');
+     if(response.root!==status.project.root||response.store!==status.project.store||!Array.isArray(response.matches)||response.matches.length>50)throw new Error('invalid results');
+     const documents=[],sections=[],seen=new Set();let bytes=0,stale=0;
+     for(const match of response.matches){signal.throwIfAborted();let fd;
+       try{
+         if(typeof match.path!=='string'||!path.isAbsolute(match.path)||!Number.isInteger(match.startLine)||!Number.isInteger(match.endLine)||match.startLine<1||match.endLine<match.startLine)continue;
+         const pointer=authorizeManagedSource(match.path,config);if(!inside(checkout,pointer.canonicalPath))continue;
+         const row=allowed.get(pointer.canonicalPath);if(!row||seen.has(row.path)||documents.length>=20)continue;
+         const file=authorizeManagedSource(match.path,config).path;
+         if(path.relative(config.repoRoot,file).split(path.sep).some(p=>p==='prompts'||p==='.git'||config.excludeDirs?.has(p))||file===config.indexPath)continue;
+         fd=await open(file,constants.O_RDONLY|(constants.O_NOFOLLOW??0));const before=await fd.stat();if(!before.isFile()||before.size>8*1024*1024||bytes+before.size>128*1024*1024)continue;
+         bytes+=before.size;const buffer=Buffer.alloc(before.size);let offset=0;while(offset<buffer.length){signal.throwIfAborted();const read=await fd.read(buffer,offset,buffer.length-offset,offset);if(!read.bytesRead)break;offset+=read.bytesRead;}if(offset!==buffer.length)continue;
+         const after=await fd.stat();authorizeManagedSource(file,config);const current=statSync(file);if(before.dev!==current.dev||before.ino!==current.ino||before.size!==after.size||before.mtimeMs!==after.mtimeMs||current.size!==after.size||current.mtimeMs!==after.mtimeMs)continue;
+         const source=buffer.toString('utf8'),parts=extractFrontmatter(source),fm=parseSimpleFrontmatter(parts.frontmatter);
+         if(fm.type!==undefined&&typeof fm.type!=='string'||fm.type==='prompt'||/^---\r?\n/.test(source)&&!parts.bodyLineOffset)continue;
+         const doc={...row,title:String(fm.title||extractFirstHeading(parts.body)||path.basename(file,'.md')).slice(0,300),type:fm.type??'untyped',status:fm.status??'untyped',kind:libraryKind(fm,row.path)};
+         if(doc.kind==='plan'){const stage=readPlanStage(readShipsFrontmatter(parts.frontmatter));doc.stage=stage.word;doc.stageInvalid=stage.invalid;}else{delete doc.stage;delete doc.stageInvalid;}
+         const archived=row.path.split('/').includes(path.basename(config.archiveDir??'archived'))||doc.status==='archived';
+         if(!matchesLibraryStage(doc,body.stage)||!body.archived&&archived||body.kind&&body.kind!=='all'&&({plans:'plan',hubs:'hub',documents:'document'}[body.kind]??body.kind)!==doc.kind||body.status&&body.status!==doc.status||body.type&&body.type!==doc.type||body.folder&&row.folder!==body.folder&&!row.folder.startsWith(body.folder+'/'))continue;
+         const verified=match.hashAlgorithm==='sha256-bytes'&&typeof match.hash==='string'&&/^[a-f0-9]{64}$/.test(match.hash)&&createHash('sha256').update(buffer).digest('hex')===match.hash;
+         const lines=normalizeEol(parts.body).split('\n'),at=verified?match.startLine-parts.bodyLineOffset-1:0;
+         const excerpt=lines.slice(Math.max(0,at),Math.max(0,at)+4).join(' ').replace(/\s+/g,' ').slice(0,240);
+         const revision=sourceRevision(source);documents.push({...doc,excerpt,revision,location:verified?'verified':'changed'});seen.add(row.path);if(!verified){stale++;continue;}
+         // Bound the section lookup to ordinary ATX headings; fences/comments never become jump targets.
+         let fence=null,comment=false,heading=null;for(let i=0;i<=Math.min(at,lines.length-1);i++){const raw=lines[i];if(raw.includes('<!--'))comment=true;const marker=raw.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);if(marker&&!comment){if(!fence)fence=marker[1];else if(marker[1][0]===fence[0]&&marker[1].length>=fence.length&&!marker[2].trim())fence=null;}const h=!fence&&!comment&&raw.match(/^ {0,3}#{1,6}\s+(.*?)(?:\s+#+\s*)?$/);if(h)heading={path:row.path,title:h[1].slice(0,200),line:i+1,revision};if(raw.includes('-->'))comment=false;}
+         if(heading)sections.push(heading);
+       }catch{if(signal.aborted)signal.throwIfAborted();}finally{await fd?.close();}
+     }
+     return {state:'ready',documents,sections,total:documents.length,limited:true,stale,coverage:{partial:paths.length<scopePaths.length||status.covered.length<paths.length||status.coverage?.partial===true||response.indexState?.degraded===true||Number(response.indexState?.failedFiles)>0||response.indexState?.verifying===true},lastIndexed:status.project.lastIndexed??null,indexUpdating:response.indexState?.indexing===true,message:'Top semantic matches from the existing local index.'};
+   });
+ }
+ return {settings,saveSettings,start,inspect,cancel,close(){for(const job of jobs.values())job.controller.abort();return Promise.allSettled([...jobs.values()].map(job=>job.done));}};
+}

package/src/app-service.mjs

@@ -0,0 +1,208 @@
+import { getStageDefinitions } from './stages.mjs';
+import {createAppLifecycle} from './app-lifecycle.mjs';
+import {createAppYardstick} from './app-yardstick.mjs';
+import {createAppFiling} from './app-filing.mjs';
+import {createAppDocuments} from './app-create.mjs';
+import {searchCheckout} from './app-search.mjs';
+import {createAppSemanticSearch} from './app-semantic-search.mjs';
+import {resolveStatusMetadata} from './status-metadata.mjs';
+import {prepareNativeAction} from './native-action.mjs';
+import { createRecordLibrary } from './app-records.mjs';
+import { prepareDecisionAction } from './decision-action.mjs';
+import { createDocumentLibrary, libraryKind } from './app-library.mjs';
+import { createAppGit } from './app-git.mjs';
+import { createAppGitCommits } from './app-git-commits.mjs';
+import { appTemplates } from './new.mjs';
+import { saveTemplate } from './template-store.mjs';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createSourceEditor, SourceEditError, sourceRevision } from './source-editor.mjs';
+import { authorizeManagedSource } from './managed-path.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { deriveFlags, flagsFile, readFlagEvents, triageFlag } from './flags.mjs';
+import { readPlanOwnership, ownershipLiveness } from './pickup.mjs';
+import { normalizeEol } from './frontmatter.mjs';
+import { extractFirstHeading } from './extractors.mjs';
+
+export const localActor = () => ({ kind: 'human', id: `human:local:${createHash('sha256').update(`${os.userInfo().username}:${os.userInfo().uid}`).digest('hex').slice(0, 24)}`, label: os.userInfo().username });
+function problem(code, message) { throw new SourceEditError(code, message); }
+function relative(filePath, config) { return path.relative(config.repoRoot, filePath).split(path.sep).join('/'); }
+function contained(root, filePath) { const rel = path.relative(root, filePath); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); }
+
+function evidenceFor(source, documentPath, config) {
+  const flags = deriveFlags(readFlagEvents(flagsFile(config))).filter(flag => {
+    if (typeof flag.file !== 'string') return false;
+    const id = typeof flag.id === 'string' ? flag.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : '';
+    return flag.file === documentPath || (flag.file && source.includes(flag.file)) || (id && new RegExp(`(?<![A-Za-z0-9])${id}(?![A-Za-z0-9])`).test(source));
+  }).slice(-6).reverse();
+  return flags.map(flag=>flagEvidence(flag,config));
+}
+function flagEvidence(flag,config) {
+    let current = { status: 'unavailable', revision: null, line: null, quote: null };
+    const candidate = path.resolve(config.repoRoot, flag.file), ext = path.extname(candidate).toLowerCase();
+    // Evidence reads are bounded to this checkout and known document/code
+    // types. No arbitrary-file endpoint, prompts, env files, or Git internals.
+    if (contained(config.repoRoot, candidate) && !flag.file.split(/[\\/]/).some(p => ['prompts', '.git', 'node_modules'].includes(p)||config.excludeDirs?.has(p))
+      && /^(?:\.md|\.mjs|\.cjs|\.js|\.ts|\.tsx|\.jsx|\.py|\.swift|\.rs|\.go|\.sql|\.sh|\.css)$/.test(ext)) {
+      try {
+        if (lstatSync(candidate).isSymbolicLink() || !contained(realpathSync(config.repoRoot), realpathSync(candidate)) || statSync(candidate).size > 1024 * 1024) throw new Error('unsafe');
+        const raw = readFileSync(candidate, 'utf8'), lines = normalizeEol(raw).split('\n');
+        const at = Number.isInteger(flag.line) ? flag.line - 1 : null;
+        const quote = at !== null ? lines[at]?.trim().slice(0, 200) ?? null : null;
+        const matches = flag.quote ? lines.flatMap((line, i) => line.trim().slice(0, 200) === flag.quote ? [i + 1] : []) : [];
+        const status = at === null ? 'file' : quote === flag.quote ? 'unchanged' : matches.length === 1 ? 'moved' : matches.length > 1 ? 'ambiguous' : 'changed';
+        const line = status === 'moved' ? matches[0] : flag.line ?? null;
+        current = { status, revision: sourceRevision(raw), line, quote: line ? lines[line - 1]?.trim().slice(0, 200) ?? null : null };
+      } catch { /* Original evidence survives missing or unsafe current files. */ }
+    }
+    return { id: flag.id, text: flag.text, severity: flag.severity, state: flag.state, triage: flag.triage, original: { file: flag.file, line: flag.line, quote: flag.quote, at: flag.at, by: flag.by, revision: null, revisionReason: 'The legacy flag did not record an observed revision.' }, current };
+}
+
+/** Shared checkout operations. Transport adapters supply their own trusted actor. */
+export function createCheckoutService({config,initialPath=null,actor=localActor(),authenticate=()=>actor,semanticOptions={}}) {
+  if (actor.kind !== 'human' || !actor.id) problem('unauthenticated', 'A locally identified human is required.');
+  const library = createDocumentLibrary(config);
+  const semantic=createAppSemanticSearch({config,library,...semanticOptions});
+  const git = createAppGit({config,actor,authenticate,library});
+  const gitCommits = createAppGitCommits({config,actor,authenticate,git});
+  const editor = createSourceEditor({ config, allowStageEdits:true, domainPrepare:prepareNativeAction, legacyTypes:[...(config.validTypes ?? ['plan','doc'])].filter(t=>t!=='prompt'),allowUnconfiguredRead:true, authenticate: req => authenticate(req), authorize: ({ actor: candidate, path: filePath }) => ({ allowed: candidate.kind === 'human' && candidate.id === actor.id && !path.relative(config.repoRoot,filePath).split(path.sep).some(p=>p==='prompts'||p==='.git'||config.excludeDirs?.has(p)) && filePath!==config.indexPath && (config.docsRoots ?? [config.docsRoot]).some(root => contained(path.resolve(root), filePath)) }) });
+  function openDocument(req, documentPath) {
+    const opened = editor.read(req, { path: documentPath });
+    const fm = parseSimpleFrontmatter(extractFrontmatter(opened.source).frontmatter);
+    const repoPath = relative(opened.path, config), ownership = readPlanOwnership(repoPath, config);
+    return { ...opened, path: repoPath, title: (fm.record_schema==='runlist.record/v1'&&(fm.finding||fm.question)) || fm.title || extractFirstHeading(extractFrontmatter(opened.source).body) || path.basename(opened.path, '.md'), status: fm.status, type:fm.type??'untyped',kind:libraryKind(fm,repoPath),stageDefinitions:getStageDefinitions(config),relationships:library.relations(repoPath,fm,extractFrontmatter(opened.source).body),metadata: fm, claim: ownership ? { corrupt: ownership.corrupt, state: ownership.state, sessionId: ownership.sessionId, liveness: ownershipLiveness(ownership) } : null, flags: evidenceFor(opened.source, repoPath, config) };
+  }
+  const records=createRecordLibrary({config,library,readSource:(req,path)=>editor.read(req,{path}),evidence:flag=>flagEvidence(flag,config)});
+  const lifecycle=createAppLifecycle({config,read:openDocument,actor:req=>authenticate(req)});
+  const yardstick=createAppYardstick({config,read:openDocument,actor:req=>authenticate(req),pending:(req,input)=>{
+    const retained=editor.listRecovery(req,{path:input});
+    if(retained.unavailable)problem('recovery-unavailable','Inspect unavailable editor recovery before recording an assessment.');
+    if(retained.items.length)problem('draft-pending','Save or discard this plan’s retained draft, and inspect pending saves, before recording an assessment.');
+    const status=lifecycle.information(req,input);
+    if(!status.enabled)problem('lifecycle-unavailable',status.reason);
+  }});
+  const filing=createAppFiling({config,library,readSource:(input,req)=>{
+    const file=authorizeManagedSource(path.resolve(config.repoRoot,input),config).path,before=lstatSync(file);
+    const opened=editor.read(req,{path:input}),after=lstatSync(file);
+    if(['dev','ino','size','mtimeMs','ctimeMs','mode'].some(key=>before[key]!==after[key]))problem('revision-conflict','This source changed while filing evidence was read. Refresh the report.');
+    return {...opened,stamp:`${after.dev}:${after.ino}:${after.size}:${after.mtimeMs}:${after.ctimeMs}`};
+  }});
+  const assertYardstickIdle=(req,input)=>yardstick.assertIdle(req,relative(path.resolve(config.repoRoot,input),config));
+  const invalidateReports=input=>{library.invalidate(input);records.invalidate();filing.invalidate();};
+  const creation=createAppDocuments({config,actor:req=>authenticate(req),library});
+  async function request(req, route, body) {
+    if (typeof route !== 'string' || !route.startsWith('/api/')) problem('invalid-request','Choose a supported checkout operation.');
+    const url = new URL(route, 'http://checkout.invalid');
+    const authenticated = {actor:authenticate(req)};
+    if(url.pathname==='/api/filing'||url.pathname.startsWith('/api/yardstick')){if(authenticated.actor?.kind!=='human'||authenticated.actor.id!==actor.id)problem('forbidden','This local checkout authority is required.');}
+    if (req.method === 'GET' && url.pathname === '/api/git/status') return git.status(req,url.searchParams);
+    if (req.method === 'GET' && url.pathname === '/api/git/diff') return git.diff(req,url.searchParams);
+    if (req.method === 'GET' && url.pathname === '/api/git/operation') return gitCommits.inspect(req,url.searchParams.get('id'));
+    const send = (_status, value) => { if (_status === 404) problem('not-found',value.message); return value; };
+      if (req.method === 'GET' && url.pathname === '/api/templates') return send(200, appTemplates(config));
+      if(req.method==='GET'&&url.pathname==='/api/create')return creation.options();
+      if(url.pathname.startsWith('/api/semantic/')){
+        if(authenticated.actor?.kind!=='human'||authenticated.actor.id!==actor.id)problem('forbidden','This local checkout authority is required.');
+        if(req.method==='GET'&&url.pathname==='/api/semantic/settings')return semantic.settings();
+        if(req.method==='GET'&&url.pathname==='/api/semantic/result')return semantic.inspect(url.searchParams.get('id'));
+        if(req.method==='POST'){if(!body||typeof body!=='object'||Array.isArray(body))problem('invalid-request','Use a JSON object.');
+          if(url.pathname==='/api/semantic/settings')return semantic.saveSettings(body);
+          if(url.pathname==='/api/semantic/start')return semantic.start(body);
+          if(url.pathname==='/api/semantic/cancel'){if(Object.keys(body).some(k=>k!=='id')||typeof body.id!=='string')problem('invalid-request','Choose a semantic request.');return semantic.cancel(body.id);}
+        }
+      }
+      if(req.method==='GET'&&url.pathname==='/api/search')return searchCheckout(config,library,url.searchParams);
+      if(req.method==='GET'&&url.pathname==='/api/recovery'){
+        const target=url.searchParams.get('path'),groups=[editor.listRecovery(req,{path:target}),...(target?[]:[creation.list(req),lifecycle.list(req),yardstick.list(req),gitCommits.list(req)])];
+        const items=groups.flatMap(group=>group.items).map(item=>({...item,path:path.isAbsolute(item.path)?relative(item.path,config):item.path})).sort((a,b)=>String(b.at).localeCompare(String(a.at)));
+        const offset=Math.max(0,Math.floor(Number(url.searchParams.get('offset'))||0)),limit=Math.max(1,Math.min(200,Math.floor(Number(url.searchParams.get('limit'))||50)));
+        return {items:items.slice(offset,offset+limit),total:items.length,offset,limit,hasMore:offset+limit<items.length,unavailable:groups.reduce((n,g)=>n+g.unavailable,0)};
+      }
+      if (req.method === 'GET' && ['/api/library','/api/plans'].includes(url.pathname)) { const params=new URLSearchParams(url.searchParams); if(url.pathname==='/api/plans'&&!params.has('kind'))params.set('kind','plans'); const metadata=new URLSearchParams(params);if(params.get('content')==='1')metadata.delete('q');let result=await library.query(metadata);if(params.get('content')==='1'&&params.get('q')?.trim())result={...result,...await searchCheckout(config,library,params)}; return send(200,{checkout:path.basename(config.repoRoot),checkoutPath:config.repoRoot,...result,plans:result.documents,initialPath}); }
+      if (req.method === 'GET' && url.pathname === '/api/document') { await library.refresh(); return send(200,openDocument(req,url.searchParams.get('path'))); }
+      if (req.method === 'GET' && url.pathname === '/api/link') { await library.refresh(); return send(200,library.resolve(url.searchParams.get('ref'),url.searchParams.get('from')??'')); }
+      if(req.method==='GET'&&url.pathname==='/api/settings')return send(200,{checkout:path.basename(config.repoRoot),roots:(config.docsRoots??[config.docsRoot]).map(root=>relative(root,config)),exclusions:[...config.excludeDirs],statuses:resolveStatusMetadata(config),configFile:config.configPath?relative(config.configPath,config):null,sharing:{records:'Markdown in this checkout; share through Git',preferences:'This browser',drafts:'Private local editor state',templates:'runlist.templates.json'}});
+      if(req.method==='GET'&&url.pathname==='/api/filing')return filing.request(url.searchParams,req);
+      if(req.method==='GET'&&url.pathname==='/api/yardstick')return yardstick.information(req,url.searchParams.get('path'));
+      if(req.method==='GET'&&url.pathname==='/api/lifecycle')return send(200,lifecycle.information(req,url.searchParams.get('path')));
+      if(req.method==='GET'&&url.pathname==='/api/records'){
+        const kind=url.searchParams.get('kind');if(!['flags','decisions'].includes(kind))problem('invalid-request','Choose flags or decisions.');
+        return send(200,url.searchParams.has('key')?await records.detail(req,kind,url.searchParams.get('key')):await records.query(req,kind,url.searchParams));
+      }
+      if (req.method === 'POST') {
+        if (!body || typeof body !== 'object' || Array.isArray(body)) problem('invalid-request','Use a JSON object.');
+        if(['actor','checkout','repoRoot'].some(key=>key in body))problem('forbidden','Identity and checkout authority belong to the local application.');
+        if(url.pathname==='/api/git/commit/preview')return gitCommits.preview(req,body);
+        if(url.pathname==='/api/git/commit/start')return gitCommits.start(req,body);
+        if(url.pathname==='/api/git/operation/inspect')return gitCommits.inspectJob(req,body);
+        if(url.pathname==='/api/git/operation/recover')return gitCommits.recover(req,body);
+        if(url.pathname==='/api/git/operation/settle')return gitCommits.settle(req,body);
+        if(url.pathname==='/api/git/operation/cancel')return gitCommits.cancel(req,body);
+        if(url.pathname==='/api/create/preview')return creation.preview(req,body);
+        if(url.pathname==='/api/create/inspect')return creation.inspect(req,body);
+        if(url.pathname==='/api/create/discard')return creation.discard(req,body);
+        if(url.pathname==='/api/create/commit'){const result=creation.commit(req,body);invalidateReports();return result;}
+        if(url.pathname==='/api/yardstick/preview')return yardstick.preview(req,body);
+        if(url.pathname==='/api/yardstick/commit'){const result=await yardstick.commit(req,body);invalidateReports();return result;}
+        if(url.pathname==='/api/yardstick/inspect')return yardstick.inspect(req,body);
+        if(url.pathname==='/api/yardstick/settle')return yardstick.settle(req,body);
+        if(url.pathname==='/api/lifecycle/preview'){assertYardstickIdle(req,body.path);return send(200,await lifecycle.preview(req,body));}
+        if(url.pathname==='/api/lifecycle/commit'){const retained=lifecycle.inspect(req,body);if(retained)assertYardstickIdle(req,retained.path);const result=await lifecycle.commit(req,body);invalidateReports();return send(200,result);}
+        if(url.pathname==='/api/lifecycle/inspect')return send(200,lifecycle.inspect(req,body));
+        if(url.pathname==='/api/lifecycle/settle')return send(200,lifecycle.settle(req,body));
+        if(url.pathname==='/api/native/preview'){
+          assertYardstickIdle(req,body.path);
+          const opened=editor.read(req,{path:body.path});
+          const claim=readPlanOwnership(relative(opened.path,config),config);
+          if(claim?.corrupt||claim?.state==='owned')problem('claim-conflict','This record is claimed or its ownership needs repair through the CLI.');
+          if(opened.revision!==body.expectedRevision)problem('revision-conflict','The record changed. Reload and review it again.');
+          const request={path:relative(opened.path,config),operationId:body.operationId,expectedRevision:opened.revision,action:body.action,note:body.note,optionId:body.optionId,at:new Date().toISOString()};
+          request.source=prepareNativeAction(opened.source,request,authenticated.actor);
+          return send(200,{request,before:opened.source});
+        }
+        if(url.pathname==='/api/native/action'){assertYardstickIdle(req,body.path);const result=editor.nativeAction(req,body);invalidateReports(body.path);return send(200,result);}
+        if(url.pathname==='/api/flags/triage'){
+          const selected=await records.detail(req,'flags',body.key);
+          if(selected.native)problem('record-read-only','Use the native record action for this record.');
+          if(!/^sha256:[a-f0-9]{64}$/.test(body.expectedRevision??'')||!body.operationId)problem('invalid-request','Review the current flag and supply its revision and operation ID.');
+          if(typeof body.note!=='string'||!body.note.trim()||body.note.length>4000)problem('invalid-request','Give a reason, up to 4,000 characters.');
+          const human=authenticated.actor;
+          const outcome=triageFlag(config,{id:selected.id,event:body.action,note:body.note,expectedRevision:body.expectedRevision,operationId:body.operationId,by:{kind:'person',name:human.label??human.id,id:human.id}});
+          records.invalidate();return send(200,{...outcome,actor:human});
+        }
+        if(url.pathname==='/api/decisions/preview'){
+          const selected=await records.detail(req,'decisions',body.key);
+          if(!selected.editable||selected.native)problem('record-read-only','Open this record’s source to edit it.');
+          if(selected.revision!==body.expectedRevision)problem('decision-revision-conflict','The source changed. Reload the decision and review it again.');
+          const source=prepareDecisionAction(selected.source,{...body,id:selected.id,line:selected.line,actor:authenticated.actor,at:new Date().toISOString()},config.raw?.decisions);
+          return send(200,{path:selected.path,source,before:selected.source,expectedRevision:selected.revision});
+        }
+        if (url.pathname === '/api/templates/save') { saveTemplate(config,body); return send(200,appTemplates(config)); }
+        if (!['/api/save','/api/undo','/api/draft/read','/api/draft/write','/api/draft/discard','/api/operation/inspect','/api/operation/settle'].includes(url.pathname)) return send(404, { code:'not-found', message:'No such operation.' });
+        if (url.pathname.startsWith('/api/operation/')) {
+          const retained = editor.inspectOperation(req, body);
+          const current = retained ? openDocument(req, retained.path) : null;
+          if (url.pathname.endsWith('settle')) return send(200, editor.settleOperation(req, body));
+          return send(200, retained ? { ...retained, currentSource:current.source, currentRevision:current.revision } : null);
+        }
+        // Save/undo/draft writes validate current source under their own
+        // guards. Draft reads without retained state and discard also need a
+        // stable source read, but none needs a second rendered document and
+        // related evidence before the guarded operation.
+        if(['/api/draft/read','/api/draft/discard'].includes(url.pathname))editor.read(req,{path:body.path});
+        const methods = { '/api/save':'save', '/api/undo':'undo', '/api/draft/read':'readDraft', '/api/draft/write':'putDraft', '/api/draft/discard':'discardDraft' };
+        if(['/api/save','/api/undo','/api/draft/write'].includes(url.pathname))assertYardstickIdle(req,body.path);
+        const result = editor[methods[url.pathname]](req, body);
+        if(['/api/save','/api/undo'].includes(url.pathname)){invalidateReports(body.path);}
+        return send(200, result);
+      }
+      problem('not-found','No such checkout operation.');
+  }
+  return {request,close:()=>semantic.close()};
+}
+export function appError(error) {
+  const code=error.code || 'request-failed';
+  return {code,message:error instanceof SourceEditError || /template|flag-|decision-/.test(code) ? error.message : 'The operation failed. Check the selected checkout.',details:error.details ?? {}};
+}