@supersuit/transcript-md 0.1.0

package/lib/freedom-conversations-cli.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Keep informational commands ahead of imports: even schema/config IO is unnecessary there.
+const commands=['list','read','validate','sources','resolve','cite','seek','create','annotate','revise','recover'];
+const args=process.argv.slice(2);
+if(args.length===1&&args[0]==='--help') {
+ console.log('Conversation records\n\nlist [--workspace DIR | --transcripts-dir DIR] [--include-sections] [--json]\nread FILE [--workspace DIR] [--include-body] [--json]\nvalidate FILE [--workspace DIR] [--json]\nsources FILE [--workspace DIR] [--json]\nresolve ID [--workspace DIR] [--json]\ncite FILE --turn ID [--turn ID] [--workspace DIR] [--json]\nseek FILE --turn ID [--capture ID] [--workspace DIR] [--json]\ncreate --workspace DIR --spec FILE [--json]\nannotate FILE --spec FILE --expected-sha SHA [--workspace DIR] [--json]\nrevise FILE --spec FILE --expected-sha SHA [--workspace DIR] [--json]\nrecover FILE --revision-id ID --action resume|reverse [--workspace DIR] [--json]\n--capabilities --json');
+} else if(args.length===2&&args.includes('--capabilities')&&args.includes('--json')) {
+ console.log(JSON.stringify({api_version:1,schema_versions:[1],commands,revision:null}));
+} else {
+ const json=args.includes('--json');
+ const diagnostic=code=>({code,severity:'error',path:null,field:null,message:'Conversation command could not complete; check arguments and record diagnostics.'});
+ const conflict=code=>['LOCKED','STALE_PIN','STALE_TURN_PIN','STALE_REVISION_RETRY','RECOVERY_THIRD_STATE','REVISION_INCOMPLETE','REVISION_ID_COLLISION'].includes(code)||code.endsWith('_COLLISION');
+ const exitFor=diagnostics=>diagnostics.some(d=>d.code==='PRIVACY_REFUSED')?4:diagnostics.some(d=>conflict(d.code))?3:diagnostics.some(d=>['ID_COLLISION','AMBIGUOUS_ALIAS'].includes(d.code))?3:diagnostics.some(d=>d.severity==='error'&&d.code!=='NOT_FOUND')?2:diagnostics.some(d=>d.code==='NOT_FOUND')?1:0;
+ try {
+  const command=args[0],options={},positionals=[];
+  if(!commands.includes(command))throw new Error('INVALID_ARGUMENTS');
+  for(let i=1;i<args.length;i++) {
+   const arg=args[i];
+   if(arg==='--turn') {
+    if(!args[i+1]||args[i+1].startsWith('--'))throw new Error('INVALID_ARGUMENTS');(options[arg]??=[]).push(args[++i]);
+   } else if(['--workspace','--transcripts-dir','--capture','--spec','--expected-sha','--revision-id','--action'].includes(arg)) {
+    if(Object.hasOwn(options,arg)||!args[i+1]||args[i+1].startsWith('--'))throw new Error('INVALID_ARGUMENTS');options[arg]=args[++i];
+   } else if(['--json','--include-body','--include-sections'].includes(arg)) {
+    if(Object.hasOwn(options,arg))throw new Error('INVALID_ARGUMENTS');options[arg]=true;
+   } else if(arg.startsWith('--'))throw new Error('INVALID_ARGUMENTS');
+   else positionals.push(arg);
+  }
+  if(options['--workspace']&&options['--transcripts-dir']||options['--transcripts-dir']&&command!=='list'||options['--include-body']&&command!=='read'||options['--include-sections']&&command!=='list'||positionals.length!==(['list','create'].includes(command)?0:1))throw new Error('INVALID_ARGUMENTS');
+  if(options['--turn']&&!['cite','seek'].includes(command)||options['--capture']&&command!=='seek'||['cite','seek'].includes(command)&&!options['--turn']?.length||command==='seek'&&options['--turn'].length!==1)throw new Error('INVALID_ARGUMENTS');
+  const mutations=['create','annotate','revise','recover'];
+  if(options['--spec']&&!['create','annotate','revise'].includes(command)||options['--expected-sha']&&!['annotate','revise'].includes(command)||options['--revision-id']&&command!=='recover'||options['--action']&&command!=='recover')throw new Error('INVALID_ARGUMENTS');
+  if(mutations.includes(command)) {
+   if(['create','annotate','revise'].includes(command)&&!options['--spec']||['annotate','revise'].includes(command)&&!options['--expected-sha']||command==='recover'&&(!options['--revision-id']||!['resume','reverse'].includes(options['--action'])))throw new Error('INVALID_ARGUMENTS');
+   const writer=await import('./freedom-conversation-write.mjs');
+   const {readFileSync}=await import('node:fs');
+   const {resolveTrackedRoot}=await import('./freedom-workspace.mjs');
+   const root=options['--workspace']?resolveTrackedRoot(options['--workspace']):command==='create'?resolveTrackedRoot(process.cwd()):undefined;
+   let spec;if(options['--spec'])try{spec=JSON.parse(readFileSync(options['--spec'],'utf8'));}catch{throw new Error('INVALID_ARGUMENTS');}
+   const common={pid:process.pid,by:'conversation-cli',root};
+   const result=command==='create'?writer.createConversation({...common,spec}):command==='annotate'?writer.annotateConversation({...common,file:positionals[0],spec,expectedSha:options['--expected-sha']}):command==='revise'?writer.reviseConversation({...common,file:positionals[0],spec,expectedSha:options['--expected-sha']}):writer.recoverConversationRevision({...common,file:positionals[0],revisionId:options['--revision-id'],action:options['--action']});
+   console.log(JSON.stringify({api_version:1,...result}));
+  }else {
+  const door=await import('./freedom-conversations.mjs');
+  const {resolveTrackedRoot}=await import('./freedom-workspace.mjs');
+  let root;const workspace=()=>root??=(resolveTrackedRoot(options['--workspace']??process.cwd()));
+  let records=[],diagnostics=[];
+  if(command==='list')({records,diagnostics}=options['--transcripts-dir']?door.listConversationDirectory(options['--transcripts-dir']):door.listConversations(workspace()));
+  else if(command==='resolve') {
+   const listed=door.listConversations(workspace()),result=door.resolveConversation(listed.records,positionals[0],{root});
+   records=result.record?[result.record]:[];diagnostics=[...listed.diagnostics,...result.diagnostics];
+  }else {
+   let record=door.readConversation(positionals[0],options['--workspace']?{root:workspace()}:{});
+   if(record.diagnostics.some(d=>d.code==='REDIRECT_WORKSPACE_REQUIRED'))record=door.readConversation(positionals[0],{root:workspace()});
+   records=[record];diagnostics=record.diagnostics;
+  }
+  diagnostics=[...new Map(diagnostics.map(d=>[JSON.stringify(d),d])).values()];
+  const metadata=record=>{
+   const h=record.header?.schema_version===1?record.header:{};
+   const data={id:h.id??null,path:record.file,file:record.file,relativePath:record.relativePath,layout:record.layout,date:h.date??null,title:h.title??null,participants:h.participants??[],sources:h.sources??[],review:h.review??null,body_format:h.body_format??null,aliases:h.aliases??[],fileSha256:record.fileSha256,bodySha256:record.bodySha256,gaps:record.gaps,diagnostics:record.diagnostics};
+   if(command==='sources')data.sources=door.conversationSourceRefs(record);
+   if(options['--include-body']&&!record.diagnostics.some(d=>d.code==='INVALID_UTF8'))Object.assign(data,{header:h,legacyFields:record.legacyFields,body:record.body.toString('utf8'),rawHeader:record.rawHeader?.toString('utf8')??null,turns:record.turns.map(t=>({...t,text:t.text.toString('utf8')}))});
+   if(options['--include-body']||options['--include-sections'])data.sections=record.sections.map(s=>({...s,bytes:s.bytes.toString('utf8')}));
+   return data;
+  };
+  let output={api_version:1,records:records.map(metadata),diagnostics};
+  if(['cite','seek'].includes(command)&&!diagnostics.some(d=>d.severity==='error')) {
+   const citations=await import('./freedom-conversation-citations.mjs');
+   if(command==='cite')output=citations.citeConversation(records[0],{turnIds:options['--turn']});
+   else {
+    output=citations.seekConversation(records[0],{turnId:options['--turn'][0],captureId:options['--capture']});
+    diagnostics=output.gaps;
+   }
+  }
+  if(json)console.log(JSON.stringify(output));
+  else {
+   if(command==='cite'&&output.selector||command==='seek'&&output.candidates)console.log(JSON.stringify(output));
+   for(const r of output.records??[])console.log(`${r.id??'(invalid)'}\t${r.path}`);
+   for(const d of diagnostics)console.error(`${d.severity}: ${d.code}`);
+  }
+  process.exitCode=command==='seek'&&output.candidates?.length===0?1:exitFor(diagnostics);
+  }
+ }catch(e) {
+  const d=diagnostic(e.code&&/^[A-Z][A-Z0-9_]+$/.test(e.code)?e.code:e.message==='INVALID_ARGUMENTS'?'INVALID_ARGUMENTS':'READ_INCOMPLETE');
+  if(json)console.log(JSON.stringify({api_version:1,records:[],diagnostics:[d]}));else console.error(`${d.severity}: ${d.code}`);
+  process.exitCode=exitFor([d]);
+ }
+}

package/lib/freedom-conversations.mjs

@@ -0,0 +1,358 @@
+// Synchronous read door. Explicit roots only; no binding discovery, writes or media probes.
+import {readFileSync,readdirSync,lstatSync,realpathSync} from 'node:fs';
+import {resolve,relative,basename,dirname,join,isAbsolute,sep} from 'node:path';
+import {createHash} from 'node:crypto';
+import {paths} from './freedom-workspace.mjs';
+import {parseConversationHeader,validateConversation} from './frontmatter/conversation.mjs';
+import {parseConversationInstant,compareConversationInstants} from './freedom-conversation-time.mjs';
+import {normalizeLegacy} from './freedom-conversation-legacy.mjs';
+import {conversationIdCollisionKey as foldId} from './freedom-conversation-casefold.mjs';
+
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+const diagnostic=(code,path=null,field=null,severity='error')=>({code,severity,path,field,message:'Conversation record requires explicit resolution; no source content is included in this diagnostic.'});
+const excludedPart=p=>/^[._]/.test(p)||['sources','derived','staging'].includes(p);
+export function classifyConversationPath(p) {
+ if(typeof p!=='string'||p.includes('\\')||p.includes('\0'))return 'excluded';
+ const parts=p.split('/');
+ if(parts.some(p=>!p||excludedPart(p))||parts.at(-1)==='README.md'||parts.at(-1)==='annotations.md')return 'excluded';
+ if(parts.length===2&&parts[1]==='transcript.md')return 'canonical';
+ if(parts.length===1&&/\.md$/.test(p))return 'legacy';
+ return 'excluded';
+}
+const emptyRecord=(file,bytes=Buffer.alloc(0),layout='canonical')=>({file:resolve(file),relativePath:basename(file),id:null,layout,header:null,legacyFields:null,rawHeader:null,body:bytes,fileSha256:hash(bytes),bodySha256:hash(bytes),sections:[],turns:[],gaps:[],diagnostics:[]});
+const attachGaps=r=>{r.diagnostics=r.diagnostics.map(d=>({...d,path:d.path??r.file}));r.gaps=r.diagnostics.filter(d=>d.severity==='warning'||d.code.endsWith('_UNRESOLVED'));return r;};
+
+// Byte offsets, including original CRLF separators, remain independent of JS string lengths.
+function physicalLines(bytes,startLine=1) {
+ const lines=[];let start=0,line=startLine;
+ while(start<bytes.length){const lf=bytes.indexOf(10,start),end=lf<0?bytes.length:lf+1;lines.push({start,end,line:line++,text:bytes.subarray(start,lf<0?end:lf).toString('utf8').replace(/\r$/,'')});start=end;}
+ return lines;
+}
+const interpretation=/^(?:granola notes|summary|key quotes|action items|notes|generated notes|generated interpretation)$/i;
+const warning=/^(?:attribution warning|speaker attribution(?: warning)?|transcription warning|warning|warnings)$/i;
+function sectionsFor(record,bodyStartLine) {
+ const lines=physicalLines(record.body,bodyStartLine),headings=[],warningStarts=[];let fence=null;
+ for(let i=0;i<lines.length;i++) {
+  const text=lines[i].text;
+  if(fence){if(new RegExp(`^ {0,3}${fence.char}{${fence.length},}\\s*$`).test(text))fence=null;continue;}
+  const opening=/^ {0,3}(`{3,}|~{3,})(.*)$/.exec(text);
+  if(opening&&!(opening[1][0]==='`'&&opening[2].includes('`'))){fence={char:opening[1][0],length:opening[1].length};continue;}
+  const m=/^ {0,3}(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/.exec(text);
+  if(m)headings.push({index:i,level:m[1].length,name:m[2]});
+  if(/^\s*>\s*\[!WARNING\]/i.test(text)||/^\s*(?:>\s*)?\*\*(?:speaker )?attribution warning\b/i.test(text))warningStarts.push(i);
+ }
+ const canonical=record.header.body_format==='turns-v1';
+ const kind=h=>canonical?(h.level===2&&h.name==='Transcript'?'transcript':'other'):/^(?:Transcript|Full transcript)$/i.test(h.name)?'transcript':warning.test(h.name)?'warning':interpretation.test(h.name)?'interpretation':'other';
+ // Canonical section ownership is H2-only; nested names never create another speech span.
+ const sectionHeadings=canonical?headings.filter(h=>h.level<=2):headings;
+ const sections=[];
+ const add=(name,kind,start,end)=>{if(start>=end)return;sections.push({name,kind,startLine:lines[start].line,endLine:lines[end-1].line,bytes:record.body.subarray(lines[start].start,lines[end-1].end)});};
+ // Select outer sections; nested headings remain part of the parent exact byte span.
+ let consumed=0;
+ for(let i=0;i<sectionHeadings.length;i++) {
+  const h=sectionHeadings[i];if(h.index<consumed)continue;
+  if(h.index>consumed)add('', 'other',consumed,h.index);
+  let end=lines.length;
+  for(let j=i+1;j<sectionHeadings.length;j++) {
+   const next=sectionHeadings[j];
+   const boundary=kind(next)!=='other'||canonical&&['Now','Log','Open questions'].includes(next.name);
+   if(next.level<=h.level&&(kind(h)!=='transcript'||boundary)){end=next.index;break;}
+  }
+  // A display title or notes container must not swallow a nested Transcript heading.
+  if(kind(h)!=='transcript')end=sectionHeadings[i+1]?.index??lines.length;
+  add(h.name,kind(h),h.index,end);consumed=end;
+ }
+ if(consumed<lines.length)add('', 'other',consumed,lines.length);
+ // Warnings are independent views even where they overlap a larger transcript section.
+ for(const h of headings.filter(h=>warning.test(h.name)))if(!sections.some(s=>s.startLine===lines[h.index].line&&s.kind==='warning')) {
+  const next=headings.find(x=>x.index>h.index&&x.level<=h.level);add(h.name,'warning',h.index,next?.index??lines.length);
+ }
+ for(const start of warningStarts){let end=start+1;while(end<lines.length&&lines[end].text.trim()&&(!lines[start].text.trimStart().startsWith('>')||lines[end].text.trimStart().startsWith('>')))end++;add('Attribution warning','warning',start,end);}
+ if(canonical) {
+  const required=['Now','Transcript','Log','Open questions'],actual=headings.filter(h=>h.level===2).map(h=>h.name);
+  if(JSON.stringify(actual)!==JSON.stringify(required)||headings.some(h=>h.level===2&&lines[h.index].text!==`## ${h.name}`))record.diagnostics.push(diagnostic('CANONICAL_SECTIONS_INVALID',record.file,'body'));
+  const titles=headings.filter(h=>h.level===1);
+  if(titles.length>1||titles.some(h=>h.name!==record.header.title))record.diagnostics.push(diagnostic('TITLE_MISMATCH',record.file,'title'));
+ }
+ const transcripts=sections.filter(s=>s.kind==='transcript');
+ if(!transcripts.length)record.diagnostics.push(diagnostic('TRANSCRIPT_SECTION_UNKNOWN',record.file,'body','warning'));
+ else if(!canonical&&transcripts.every(s=>!s.bytes.toString('utf8').replace(/^[^\n]*(?:\n|$)/,'').trim()))record.diagnostics.push(diagnostic('TRANSCRIPT_EMPTY',record.file,'body','warning'));
+ return sections.sort((a,b)=>a.startLine-b.startLine);
+}
+
+const exactKeys=(value,keys)=>value!==null&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).sort().join(',')===[...keys].sort().join(',');
+const milliseconds=n=>typeof n==='number'&&Number.isFinite(n)&&n>=0;
+const interval=(start,end)=>milliseconds(start)&&(end===null||milliseconds(end)&&end>=start);
+function validTiming(t,captures) {
+ if(t===null)return true;
+ if(!t||typeof t!=='object')return false;
+ if(t.basis==='capture')return exactKeys(t,['basis','capture','start_ms','end_ms'])&&captures.has(t.capture)&&interval(t.start_ms,t.end_ms);
+ if(t.basis==='conversation')return exactKeys(t,['basis','start_ms','end_ms','mapping'])&&interval(t.start_ms,t.end_ms)&&Array.isArray(t.mapping)&&t.mapping.every(m=>
+  exactKeys(m,['capture','conversation_start_ms','conversation_end_ms','capture_start_ms','capture_end_ms'])&&captures.has(m.capture)&&
+  [m.conversation_start_ms,m.conversation_end_ms,m.capture_start_ms,m.capture_end_ms].every(milliseconds)&&m.conversation_end_ms>=m.conversation_start_ms&&
+  m.capture_end_ms-m.capture_start_ms===m.conversation_end_ms-m.conversation_start_ms);
+ if(t.basis==='wall-clock') {
+  const start=parseConversationInstant(t.start),end=parseConversationInstant(t.end);
+  return exactKeys(t,['basis','start','end','mapping'])&&!!start&&(t.end===null||!!end&&compareConversationInstants(end,start)>=0)&&Array.isArray(t.mapping)&&t.mapping.every(m=>
+   exactKeys(m,['capture','wall_start','capture_start_ms'])&&captures.has(m.capture)&&!!parseConversationInstant(m.wall_start)&&milliseconds(m.capture_start_ms));
+ }
+ return false;
+}
+function turnsFor(record) {
+ if(record.header.body_format!=='turns-v1'||record.diagnostics.some(d=>d.severity==='error'))return [];
+ const section=record.sections.find(s=>s.kind==='transcript');if(!section)return [];
+ const lines=physicalLines(section.bytes,section.startLine),starts=[],turns=[],ids=new Set();let fence=null;
+ const fail=(code,field='body')=>record.diagnostics.push(diagnostic(code,record.file,field));
+ for(let i=1;i<lines.length;i++) {
+  const text=lines[i].text;
+  if(fence){if(new RegExp(`^ {0,3}${fence.char}{${fence.length},}\\s*$`).test(text))fence=null;continue;}
+  const opening=/^ {0,3}(`{3,}|~{3,})(.*)$/.exec(text);
+  if(opening&&!(opening[1][0]==='`'&&opening[2].includes('`'))){fence={char:opening[1][0],length:opening[1].length};continue;}
+  const heading=/^### (t-\d{6,})$/.exec(text);
+  if(heading)starts.push({index:i,id:heading[1]});
+  else if(/^\s*#{1,6}\s+t-/.test(text))fail('TURN_HEADING_INVALID');
+ }
+ const preludeEnd=starts[0]?.index??lines.length;
+ if(lines.slice(1,preludeEnd).some(l=>l.text.trim()))fail('TURN_GRAMMAR_INVALID');
+ const captures=new Map(record.header.sources.map(c=>[c.id,c]));
+ for(let i=0;i<starts.length;i++) {
+  const {index,id}=starts[i],end=starts[i+1]?.index??lines.length;
+  if(ids.has(id))fail('TURN_ID_DUPLICATE');ids.add(id);
+  const comment=/^<!-- turn (\{.*\}) -->$/.exec(lines[index+1]?.text??'');
+  if(!comment){fail('TURN_METADATA_INVALID');continue;}
+  // Reuse the scoped codec's JSON syntax/duplicate/prototype checks; no second JSON parser.
+  const parsed=parseConversationHeader(Buffer.from(`---\nextensions: ${comment[1]}\n---\n`));
+  const meta=parsed.header?.extensions;
+  if(!exactKeys(meta,['speaker','sources','timing','source_gap'])){fail('TURN_METADATA_INVALID');continue;}
+  if(meta.speaker!==null&&!record.header.participants.some(p=>p.id===meta.speaker))fail('TURN_SPEAKER_UNKNOWN','speaker');
+  const gap=meta.source_gap===null||typeof meta.source_gap==='string'&&!!meta.source_gap.trim();
+  if(!gap||!Array.isArray(meta.sources)||!meta.sources.length&&meta.source_gap===null)fail('TURN_SOURCE_INVALID','sources');
+  const warnUnknown=field=>record.diagnostics.push(diagnostic('UNKNOWN_FACT',record.file,`turns[${i}].${field}`,'warning'));
+  if(Array.isArray(meta.sources))for(const [sourceIndex,ref] of meta.sources.entries()) {
+   if(!exactKeys(ref,['capture','locator','start_ms','end_ms'])){fail('TURN_SOURCE_INVALID','sources');continue;}
+   for(const key of ['locator','start_ms','end_ms'])if(ref[key]===null)warnUnknown(`sources[${sourceIndex}].${key}`);
+   const capture=captures.get(ref.capture);
+   if(!capture||!(ref.locator===null||Number.isInteger(ref.locator)&&ref.locator>=0&&ref.locator<capture.locators.length)||!(ref.start_ms===null&&ref.end_ms===null||interval(ref.start_ms,ref.end_ms)))fail('TURN_SOURCE_INVALID','sources');
+  }
+  if(!validTiming(meta.timing,captures))fail('TURN_TIMING_INVALID','timing');
+  else if(meta.timing!==null){const endField=meta.timing.basis==='wall-clock'?'end':'end_ms';if(meta.timing[endField]===null)warnUnknown(`timing.${endField}`);}
+  for(const [missing,code,field] of [[meta.speaker===null,'SPEAKER_UNRESOLVED','speaker'],[meta.timing===null,'TIMING_UNRESOLVED','timing'],[!!meta.source_gap,'TURN_SOURCE_UNRESOLVED','sources']])if(missing)record.diagnostics.push(diagnostic(code,record.file,field,'warning'));
+  const textStart=lines[index+1].end,textEnd=end<lines.length?lines[end].start:section.bytes.length;
+  turns.push({id,...meta,text:section.bytes.subarray(textStart,textEnd),startLine:lines[index].line,endLine:lines[end-1].line});
+ }
+ if(record.diagnostics.some(d=>d.severity==='error'))return [];
+ const empty=turns.map(turn=>!turn.text.toString('utf8').trim());
+ for(let i=0;i<turns.length;i++)if(empty[i])record.diagnostics.push(diagnostic('TURN_EMPTY',record.file,`turns[${i}].text`,'warning'));
+ if(empty.every(Boolean))record.diagnostics.push(diagnostic('TRANSCRIPT_EMPTY',record.file,'body','warning'));
+ return turns;
+}
+
+function canonicalIntent(bytes,file,layout) {
+ if(layout==='canonical'||layout!=='legacy'&&basename(file)==='transcript.md')return true;
+ // Inspect only the delimited header, never a quoted header inside transcript speech.
+ const text=bytes.toString('utf8'),match=/^(?:\uFEFF)?---\r?\n([\s\S]*?)(?:\r?\n---(?:\r?\n|$)|$)/.exec(text);
+ return !!match&&/^(?:schema_version\s*:|kind\s*:\s*["']?conversation(?:-redirect)?["']?\s*$)/m.test(match[1]);
+}
+export function parseConversation(bytes,{file,layout}) {
+ if(!Buffer.isBuffer(bytes)||typeof file!=='string'||!file)throw new TypeError('conversation requires bytes and a file');
+ if(layout!==undefined&&!['legacy','canonical'].includes(layout))throw new TypeError('layout must be legacy or canonical');
+ let record;
+ if(canonicalIntent(bytes,file,layout)) {
+  const parsed=parseConversationHeader(bytes);
+  record={...emptyRecord(file,bytes,layout??'canonical'),...parsed,bodySha256:hash(parsed.body)};
+  if(!parsed.header){if(!parsed.diagnostics.length)record.diagnostics.push(diagnostic('CANONICAL_HEADER_REQUIRED',record.file));return attachGaps(record);}
+  if(parsed.header.kind==='conversation-redirect') {
+   // Header codec owns syntax. Redirects have their own deliberately minimal schema.
+   record.diagnostics=[];
+   const h=parsed.header;
+   if(h.schema_version!==1||Object.keys(h).sort().join(',')!=='kind,schema_version,to'||typeof h.to!=='string'||!h.to||parsed.body.length!==0)record.diagnostics.push(diagnostic('INVALID_REDIRECT',record.file));
+   return attachGaps(record);
+  }
+  record.id=typeof parsed.header.id==='string'?parsed.header.id:null;
+  record.diagnostics=validateConversation(parsed.header,(layout==='canonical'||layout===undefined&&basename(file)==='transcript.md')?{folderId:basename(dirname(file))}:{});
+  if(record.diagnostics.some(d=>d.severity==='error'))return attachGaps(record);
+ } else record=normalizeLegacy(bytes,{file});
+ if(record.header) {
+  const prefix=bytes.subarray(0,bytes.length-record.body.length);
+  const startLine=1+prefix.reduce((n,b)=>n+(b===10?1:0),0);
+  record.sections=sectionsFor(record,startLine);
+  record.turns=turnsFor(record);
+  if(record.header.sources.length===0&&!record.diagnostics.some(d=>d.code==='SOURCE_UNKNOWN'))record.diagnostics.push(diagnostic('SOURCE_UNKNOWN',record.file,'sources','warning'));
+  if(record.header.participants.length===0)record.diagnostics.push(diagnostic('PARTICIPANTS_UNKNOWN',record.file,'participants','warning'));
+ }
+ return attachGaps(record);
+}
+const inside=(root,file)=>{const rel=relative(resolve(root),resolve(file));return rel===''||(!isAbsolute(rel)&&rel!=='..'&&!rel.startsWith('..'+sep));};
+function safeRedirectTarget(root,to) {
+ if(isAbsolute(to)||to.includes('\\')||to.includes('\0')||to.split('/').some(p=>!p||p==='.'||p==='..'))return null;
+ const target=resolve(root,to);if(!inside(root,target))return null;
+ // Check existing ancestors too, so a missing leaf below an escaping symlink still refuses.
+ let ancestor=target;
+ while(true){try{if(!inside(realpathSync(root),realpathSync(ancestor)))return null;break;}catch(e){if(e.code!=='ENOENT'&&e.code!=='ENOTDIR')throw e;const parent=dirname(ancestor);if(parent===ancestor)throw e;ancestor=parent;}}
+ return target;
+}
+export function readConversation(file,{read=readFileSync,root,layout}={}) {
+ let current=resolve(file),hops=0;const seen=new Set();
+ while(true) {
+  if(seen.has(current)){const r=emptyRecord(current);r.diagnostics=[diagnostic('REDIRECT_LOOP',current)];return r;}seen.add(current);
+  let record;
+  try {
+   // Layout is evidence from the caller or the explicit mapped root, never a guessed binding.
+   let currentLayout=hops===0?layout:undefined;
+   if(currentLayout===undefined&&root) {
+    const classified=classifyConversationPath(relative(paths(root).transcripts,current).split(sep).join('/'));
+    if(classified!=='excluded')currentLayout=classified;
+   }
+   record=parseConversation(read(current),{file:current,layout:currentLayout});
+  }catch(e){record=emptyRecord(current);record.diagnostics=[diagnostic(e.code==='ENOENT'?'NOT_FOUND':'READ_INCOMPLETE',current)];return record;}
+  if(record.header?.kind!=='conversation-redirect') {
+   if(hops>0&&(record.layout!=='canonical'||basename(current)!=='transcript.md'))record.diagnostics.push(diagnostic('REDIRECT_TARGET_INVALID',current));
+   return record;
+  }
+  if(record.diagnostics.length)return record;
+  if(!root){record.diagnostics.push(diagnostic('REDIRECT_WORKSPACE_REQUIRED',current));return record;}
+  if(hops++>=8){record.diagnostics.push(diagnostic('REDIRECT_HOP_LIMIT',current));return record;}
+  let target;try{target=safeRedirectTarget(root,record.header.to);}catch{record.diagnostics.push(diagnostic('READ_INCOMPLETE',current));return record;}
+  if(!inside(root,current)||!target){record.diagnostics.push(diagnostic('REDIRECT_OUTSIDE_WORKSPACE',current));return record;}
+  current=target;
+ }
+}
+export function listConversationDirectory(transcriptsDir) {
+ if(typeof transcriptsDir!=='string'||!transcriptsDir)throw new TypeError('explicit transcript directory required');
+ const root=resolve(transcriptsDir),records=[],diagnostics=[];
+ function visit(dir,rel='') {
+  let entries;try{const stat=lstatSync(dir);if(stat.isSymbolicLink()){diagnostics.push(diagnostic('SYMLINK_EXCLUDED',dir));return;}entries=readdirSync(dir).sort();}catch{diagnostics.push(diagnostic('READ_INCOMPLETE',dir));return;}
+  for(const name of entries) {
+   const file=join(dir,name),p=rel?`${rel}/${name}`:name;let stat;
+   try{stat=lstatSync(file);}catch{diagnostics.push(diagnostic('READ_INCOMPLETE',file));continue;}
+   if(stat.isSymbolicLink()){diagnostics.push(diagnostic('SYMLINK_EXCLUDED',file));continue;}
+   if(p.split('/').some(excludedPart)||name==='annotations.md'||name==='README.md')continue;
+   if(stat.isDirectory()){visit(file,p);continue;}
+   const layout=classifyConversationPath(p);
+   if(stat.isFile()&&layout!=='excluded') {
+    let record;try{record=parseConversation(readFileSync(file),{file,layout});}catch{diagnostics.push(diagnostic('READ_INCOMPLETE',file));continue;}
+    if(record.header?.kind==='conversation-redirect'){diagnostics.push(...record.diagnostics);continue;}
+    record.relativePath=p;records.push(record);diagnostics.push(...record.diagnostics);
+   }else if(/\.md$/.test(name))diagnostics.push(diagnostic('UNCLASSIFIED_MARKDOWN',file));
+  }
+ }
+ visit(root);diagnostics.push(...indexConversations(records).diagnostics);return {records,diagnostics};
+}
+export function listConversations(root) {
+ if(typeof root!=='string'||!root)throw new TypeError('explicit workspace root required');
+ try{return listConversationDirectory(paths(root).transcripts);}catch{return {records:[],diagnostics:[diagnostic('READ_INCOMPLETE',resolve(root))]};}
+}
+const aliasesOf=record=>Array.isArray(record.header?.aliases)?record.header.aliases.filter(a=>a&&typeof a.value==='string'):[];
+const addIndex=(map,key,record)=>{const values=map.get(key)??[];if(!values.includes(record))values.push(record);map.set(key,values);};
+function conversationIndex(records) {
+ const byId=new Map(),byAlias=new Map(),folded=new Map(),diagnostics=[],collisions=new Map();
+ const collision=(values,code,field)=>{
+  if(values.length<2)return;
+  for(const record of values) {
+   diagnostics.push(diagnostic(code,record.file,field));
+   const peers=collisions.get(record)??new Set();
+   for(const peer of values)peers.add(peer);
+   collisions.set(record,peers);
+  }
+ };
+ for(const record of records) {
+  if(typeof record.id==='string'){addIndex(byId,record.id,record);addIndex(folded,foldId(record.id),record);}
+  for(const a of aliasesOf(record))if(typeof a.value==='string')addIndex(byAlias,a.kind==='source-id'?`${a.namespace}:${a.value}`:a.value,record);
+ }
+ for(const values of folded.values())collision(values,'ID_COLLISION','id');
+ for(const [key,values] of byAlias){const candidates=[...new Set([...values,...(byId.get(key)??[])])];collision(candidates,'AMBIGUOUS_ALIAS','aliases');}
+ const portable=new Map([...folded].map(([key,values])=>[key,[...values]]));
+ for(const record of records)for(const a of aliasesOf(record))if(a.kind==='record-id'&&typeof a.value==='string')addIndex(portable,foldId(a.value),record);
+ for(const values of portable.values())if(values.some(r=>aliasesOf(r).some(a=>a.kind==='record-id')))collision(values,'AMBIGUOUS_ALIAS','aliases');
+ return {byId,byAlias,diagnostics,collisions};
+}
+export function indexConversations(records) {
+ const {byId,byAlias,diagnostics}=conversationIndex(records);return {byId,byAlias,diagnostics};
+}
+export function resolveConversation(records,idOrAlias,{root}={}) {
+ const {byId,byAlias,diagnostics,collisions}=conversationIndex(records),candidates=new Set([...(byId.get(idOrAlias)??[]),...(byAlias.get(idOrAlias)??[])]);
+ // Bare vendor-id queries are compatibility lookups, never a preference between namespaces.
+ for(const r of records)if(aliasesOf(r).some(a=>a.kind==='source-id'&&a.value===idOrAlias))candidates.add(r);
+ const select=candidates=>{
+  // Follow the selected records' collision memberships, not the spelling of this query.
+  // Set iteration includes newly reached peers, retaining transitive conflicts too.
+  for(const candidate of candidates)for(const peer of collisions.get(candidate)??[])candidates.add(peer);
+  if(candidates.size>1) {
+   const files=new Set([...candidates].map(r=>r.file));
+   const blocking=diagnostics.filter(d=>files.has(d.path));
+   return {record:null,diagnostics:[...blocking,...[...candidates].map(r=>diagnostic('AMBIGUOUS_ALIAS',r.file,'aliases'))]};
+  }
+  const record=[...candidates][0];return {record,diagnostics:record.diagnostics};
+ };
+ if(candidates.size)return select(candidates);
+ if(root&&idOrAlias.endsWith('.md')) {
+  let target;try{target=safeRedirectTarget(root,idOrAlias);}catch{return {record:null,diagnostics:[diagnostic('READ_INCOMPLETE')]};}
+  if(!target)return {record:null,diagnostics:[diagnostic('REDIRECT_OUTSIDE_WORKSPACE')]};
+  const record=readConversation(target,{root});
+  const indexed=records.filter(r=>r.file===record.file);
+  if(indexed.length){const selected=select(new Set(indexed));if(!selected.record)return selected;}
+  return {record:record.header?.kind==='conversation'?record:null,diagnostics:record.diagnostics};
+ }
+ return {record:null,diagnostics:[diagnostic('NOT_FOUND')]};
+}
+export function conversationSourceRefs(record) {
+ if(record.header?.schema_version!==1||record.header.kind!=='conversation'||!Array.isArray(record.header.sources)||validateConversation(record.header).some(d=>d.severity==='error'))return [];
+ return record.header.sources.flatMap(c=>(Array.isArray(c.locators)&&c.locators.length?c.locators:[null]).flatMap(l=>(Array.isArray(c.roles)?c.roles:[]).map(role=>({capture:c.id,type:c.type,service:c.service,recordingId:c.recording_id,vendorId:c.vendor_id,role,path:l?.path??null,url:l?.url??null,serviceId:l?.service_id??null,availability:c.availability}))));
+}
+export const conversationSections=record=>record.sections;
+export const conversationTurns=record=>record.turns;
+
+const sharingDecision=(effectiveScope,reason,allowed=false)=>({allowed,effectiveScope,reason});
+// Retained restrictions are authoritative after relocation too. Do not reinterpret old
+// permissive-looking values, or let a new scope choice erase an unresolved old restriction.
+function retainedSharingRestriction(record) {
+ const keys=['private','sensitivity','keep','scope','sharing'];
+ if(record.diagnostics?.some(d=>d.code==='RESTRICTION_UNRESOLVED')||record.header?.legacy?.unparsed_keys?.some(k=>keys.includes(k)))return 'RESTRICTION_UNRESOLVED';
+ let home=false;
+ for(const fields of [record.legacyFields,record.header?.legacy?.fields])if(fields)for(const key of keys) {
+  if(!Object.hasOwn(fields,key))continue;
+  const value=fields[key];
+  if(key==='private'&&(value===true||value==='true')||key==='sensitivity'&&['private','confidential','restricted'].includes(value))home=true;
+  else if(!(key==='private'&&(value===false||value==='false')))return 'RESTRICTION_UNRESOLVED';
+ }
+ return home?'SHARING_HOME':null;
+}
+
+/** Report the stored boundary only; neither audience nor this result authorizes delivery. */
+export function effectiveSharing(record) {
+ if(!record||typeof record!=='object')return sharingDecision('home','INVALID_SCHEMA');
+ const restriction=retainedSharingRestriction(record);
+ if(restriction==='RESTRICTION_UNRESOLVED')return sharingDecision('home',restriction);
+ if(validateConversation(record.header).some(d=>d.severity==='error')||record.diagnostics?.some(d=>d.severity==='error'))return sharingDecision('home','INVALID_SCHEMA');
+ if(restriction)return sharingDecision('home',restriction);
+ const scope=record.header.keep.scope;
+ if(scope==='unknown')return sharingDecision('home','SHARING_UNKNOWN');
+ if(scope==='home')return sharingDecision('home','SHARING_HOME');
+ return sharingDecision(scope,'DELIVERY_TARGET_REQUIRED');
+}
+
+/** Pure boundary gate. Inject fresh group facts; outbound session authorization is separate. */
+export function canProjectConversation(record,target,context={}) {
+ const boundary=effectiveSharing(record);
+ if(boundary.effectiveScope==='home')return boundary;
+ const h=record.header,scope=boundary.effectiveScope;
+ // Reuse the scoped schema for Evidence and group-path shape, without another parser.
+ const checkKeep=keep=>validateConversation({...h,keep}).some(d=>d.severity==='error');
+ if(context?.decision!==undefined&&(context.decision===null||checkKeep({scope:'home',group:null,decision:context.decision})))return sharingDecision('home','INVALID_CONTEXT_DECISION');
+ if(!target||!['public','group'].includes(target.kind))return sharingDecision(scope,'INVALID_PROJECTION_TARGET');
+ if(target.kind==='group'&&(typeof target.group!=='string'||checkKeep({scope:'home',group:target.group,decision:null})))return sharingDecision(scope,'INVALID_PROJECTION_TARGET');
+ if(scope==='family'&&(target.kind!=='group'||target.group!==h.keep.group))return sharingDecision(scope,'GROUP_MISMATCH');
+ if(target.kind==='group') {
+  let group;
+  try {group=typeof context?.resolveGroup==='function'?context.resolveGroup(target.group):null;}catch{return sharingDecision('home','GROUP_UNRESOLVED');}
+  if(!group||group.exists!==true||group.authorized!==true)return sharingDecision('home','GROUP_UNRESOLVED');
+ }
+ return sharingDecision(scope,'SHARING_ALLOWED',true);
+}
+
+export function conversationCount(root) {
+ const {records,diagnostics}=listConversations(root);
+ const blocking=diagnostics.filter(d=>d.severity==='error');
+ if(blocking.length)throw Object.assign(new Error('Conversation count is unavailable because discovery is incomplete or conflicting.'),{code:blocking[0].code,diagnostics:blocking});
+ return records.length;
+}

package/lib/freedom-is-main.mjs

@@ -0,0 +1,65 @@
+/**
+ * "Was I run, or was I imported?" — answered once, correctly, so nobody hand-rolls it again.
+ *
+ * Node resolves symlinks when it loads a module, so `import.meta.url` is always the file's REAL
+ * path. `process.argv[1]` is whatever the caller typed. A script reached through a symlink sees
+ * two different strings for one file, and every hand-rolled comparison of them returns false.
+ *
+ * The consequence is the worst shape a failure can take: `main()` does not run, nothing is
+ * written, and the process exits 0. There is no error to read and no output to miss. It reads
+ * exactly like a successful run, and the only way anyone finds out is by noticing that the thing
+ * they asked for is not there.
+ *
+ * This is not an exotic path. A symlink is how Freedom reaches its own scripts: `.agents/skills`
+ * points at the operator's skills folder, `~/.agents/skills` and `~/.claude/skills` point back
+ * into the workspace, and a skill that lives in the repo it belongs to is symlinked into the
+ * global index. Roughly a third of skill paths on a mature machine cross one.
+ *
+ * Every near-miss below shipped in this repo at some point, and each one looks careful:
+ *
+ *   import.meta.url === `file://${process.argv[1]}`
+ *       Raw strings. Also wrong for a relative argv, and wrong for any path needing URL escaping.
+ *
+ *   resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))
+ *       `resolve` makes a path absolute and flattens `..`. It does not follow a symlink. This is
+ *       the one that reads as the fixed version.
+ *
+ *   import.meta.url === pathToFileURL(process.argv[1]).href
+ *       Correct URL encoding, no symlink resolution. Same failure, better punctuation.
+ *
+ *   import.meta.url.endsWith(process.argv[1].split("/").pop())
+ *       Compares BASENAMES, so it is loose in the other direction: any file of the same name
+ *       anywhere satisfies it.
+ *
+ * Earned 2026-09-09. Two concat calls against a private copy of a script reported nothing and
+ * produced nothing; the same commands at the real path worked first time. A sweep then found 36
+ * of these in the shipped template, including `freedom-session-name.mjs`, which the session
+ * opener reads to decide whether to offer a session name — and whose silence reads as "no".
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * True when this module is the script node was asked to run.
+ *
+ * @param {string} moduleUrl Always pass `import.meta.url` from the calling module.
+ * @returns {boolean}
+ *
+ * @example
+ *   import { isMain } from "../../lib/freedom-is-main.mjs";
+ *   if (isMain(import.meta.url)) process.exit(main(process.argv.slice(2)));
+ */
+export function isMain(moduleUrl) {
+  const entry = process.argv[1];
+  if (!entry || !moduleUrl) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(entry);
+  } catch {
+    // A path that cannot be resolved (deleted mid-run, or an argv[1] that is not a real file, as
+    // under `node --eval`) is not this module. Never throw from a guard: a crash here takes down
+    // an import that had nothing to do with running as a CLI.
+    return false;
+  }
+}
+
+export default isMain;

package/lib/freedom-migrate-common.mjs

@@ -0,0 +1,15 @@
+// Shared capture-lock implementation only; archive migration remains outside this package.
+import {join} from 'node:path';
+import {stateDir} from './freedom-workspace.mjs';
+import {acquire as acquireLock,release as releaseLock} from './freedom-run-lock.mjs';
+export const MIGRATE_LOCK='catch-up-freeda';
+export function withRunLock(root, { pid, by }, fn) {
+  const lockPath = join(stateDir(MIGRATE_LOCK, root), ".lock");
+  const lock = acquireLock(lockPath, { pid, by });
+  if (!lock.acquired) {
+    const h = lock.status.record;
+    return { code: 1, error: `refused: the ${MIGRATE_LOCK} run lock is held${h ? ` by pid ${h.pid} (${h.by ?? "unknown"}, since ${h.since ?? "unknown"})` : ` (${lock.status.why ?? lock.status.state})`}. Wait for that run to finish.` };
+  }
+  try { return fn(); }
+  finally { if (!lock.reentrant) releaseLock(lockPath, { pid }); }
+}

package/lib/freedom-people.mjs

@@ -0,0 +1,8 @@
+// Only existing caller-owned person references; no person discovery or operational processing.
+import {statSync} from 'node:fs';
+import {join,resolve as resolvePath,sep} from 'node:path';
+import {paths} from './freedom-workspace.mjs';
+export function peopleDir(root){return paths(root).people;}
+const isFile=p=>{try{return statSync(p).isFile();}catch{return false;}};
+export function safeSlug(dir,slug){if(typeof slug!=='string'||!slug||slug.startsWith('/')||/[\\\0]/.test(slug))return false;if(slug.split('/').some(seg=>seg===''||seg.startsWith('.')))return false;const root=resolvePath(dir);return resolvePath(root,slug).startsWith(root+sep);}
+export function recordPath(dir,slug){if(!safeSlug(dir,slug))return null;for(const c of [join(dir,slug,'friend.md'),join(dir,`${slug}.md`),join(dir,'archive',slug,'friend.md'),join(dir,'archive',`${slug}.md`)])if(isFile(c))return c;return null;}