@supersuit/transcript-md 0.1.0

package/lib/freedom-conversation-citations.mjs

@@ -0,0 +1,88 @@
+// Immutable selection and explicit timing only. No repository discovery, media IO or clock guessing.
+import {createHash} from 'node:crypto';
+import {resolve} from 'node:path';
+import {isDeepStrictEqual} from 'node:util';
+import {parseConversation} from './freedom-conversations.mjs';
+import {parseConversationInstant,conversationCaptureOffsetMs} from './freedom-conversation-time.mjs';
+
+const hash=bytes=>createHash('sha256').update(bytes).digest('hex');
+const sha=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value);
+const nonempty=value=>typeof value==='string'&&!!value.trim();
+const turnIds=ids=>Array.isArray(ids)&&ids.length>0&&ids.every(id=>typeof id==='string'&&/^t-\d{6,}$/.test(id));
+const revisionValid=(r,repository)=>r&&Object.keys(r).sort().join(',')==='kind,value'&&(r.kind==='sha256'&&sha(r.value)||r.kind==='git'&&nonempty(repository)&&/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(r.value));
+const diagnostic=code=>({code,severity:'error',path:null,field:null,message:'Citation or timing could not be resolved from the supplied version and explicit mapping.'});
+const refuse=code=>{throw Object.assign(new Error('Conversation citation could not be created.'),{code});};
+const blocked=record=>!record?.header||record.diagnostics.some(d=>d.severity==='error');
+const selectedTurns=(record,ids)=>ids.map(id=>record.turns.find(t=>t.id===id));
+
+export function citeConversation(record,{turnIds:ids,repository=null,revision={kind:'sha256',value:record.fileSha256}}={}) {
+ if(blocked(record)||record.header.body_format!=='turns-v1')refuse('CITATION_RECORD_INVALID');
+ if(!turnIds(ids))refuse('CITATION_SELECTOR_INVALID');
+ if(repository!==null&&!nonempty(repository)||!revisionValid(revision,repository))refuse('CITATION_REVISION_INVALID');
+ if(revision.kind==='sha256'&&revision.value!==record.fileSha256)refuse('CITATION_REVISION_MISMATCH');
+ const turns=selectedTurns(record,ids);if(turns.some(t=>!t))refuse('NOT_FOUND');
+ return {repository,path:record.file,record_id:record.id,revision:{...revision},selector:{kind:'turn',ids:[...ids],text_sha256:hash(Buffer.concat(turns.map(t=>t.text)))},sources:structuredClone(turns.flatMap(t=>t.sources))};
+}
+
+export function resolveCitation(citation,{readVersion}={}) {
+ const fail=code=>({text:Buffer.alloc(0),diagnostics:[diagnostic(code)]});
+ if(!citation||!nonempty(citation.path)||!nonempty(citation.record_id)||(citation.repository!==null&&!nonempty(citation.repository))||!revisionValid(citation.revision,citation.repository)||!sha(citation.selector?.text_sha256)||!Array.isArray(citation.sources))return fail('CITATION_INVALID');
+ let bytes;
+ try {bytes=readVersion(citation.repository,citation.path,citation.revision);}catch{return fail('CITATION_VERSION_UNAVAILABLE');}
+ if(!Buffer.isBuffer(bytes))return fail('CITATION_VERSION_UNAVAILABLE');
+ // A Git readVersion implementation must read this exact repository/path/commit, never HEAD.
+ if(citation.revision.kind==='sha256'&&hash(bytes)!==citation.revision.value)return fail('CITATION_REVISION_MISMATCH');
+ try {new TextDecoder('utf-8',{fatal:true}).decode(bytes);}catch{return fail('INVALID_UTF8');}
+ const selector=citation.selector;let text;
+ if(selector.kind==='lines') {
+  if(!Number.isSafeInteger(selector.start)||!Number.isSafeInteger(selector.end)||selector.start<1||selector.end<selector.start)return fail('CITATION_SELECTOR_INVALID');
+  const starts=[0];for(let i=0;i<bytes.length;i++)if(bytes[i]===10&&i+1<bytes.length)starts.push(i+1);
+  if(!bytes.length||selector.end>starts.length)return fail('CITATION_SELECTOR_INVALID');
+  text=bytes.subarray(starts[selector.start-1],starts[selector.end]??bytes.length);
+ }else if(selector.kind==='turn') {
+  if(!turnIds(selector.ids))return fail('CITATION_SELECTOR_INVALID');
+  const record=parseConversation(bytes,{file:citation.path});
+  if(blocked(record)||record.header.body_format!=='turns-v1')return fail('CITATION_RECORD_INVALID');
+  if(record.id!==citation.record_id)return fail('CITATION_RECORD_MISMATCH');
+  const turns=selectedTurns(record,selector.ids);if(turns.some(t=>!t))return fail('NOT_FOUND');
+  if(!isDeepStrictEqual(citation.sources,turns.flatMap(t=>t.sources)))return fail('CITATION_SOURCES_MISMATCH');
+  text=Buffer.concat(turns.map(t=>t.text));
+ }else return fail('CITATION_SELECTOR_INVALID');
+ if(hash(text)!==selector.text_sha256)return fail('CITATION_TEXT_MISMATCH');
+ return {text,diagnostics:[]};
+}
+
+// A selected locator supplies a path; an unknown locator never silently picks the first asset.
+function candidatePaths(record,turn,captureId) {
+ const capture=record.header.sources.find(c=>c.id===captureId);
+ const refs=turn.sources.filter(s=>s.capture===captureId);
+ const paths=refs.map(ref=>{
+  const locator=ref.locator===null?null:capture.locators[ref.locator];
+  return locator?.kind==='bundled'?resolve(record.file,'..',locator.path):locator?.path??null;
+ });
+ return [...new Set(paths.length?paths:[null])];
+}
+export function seekConversation(record,{turnId,captureId}={}) {
+ const fail=code=>({candidates:[],gaps:[diagnostic(code)]});
+ if(blocked(record))return fail('CONVERSATION_INVALID');
+ const turn=record.turns.find(t=>t.id===turnId);if(!turn)return fail('NOT_FOUND');
+ const t=turn.timing;if(t===null)return fail('TIMING_UNRESOLVED');
+ let spans=[];
+ if(t.basis==='capture')spans=[{capture:t.capture,offset_ms:t.start_ms,end_ms:t.end_ms}];
+ if(t.basis==='conversation')spans=t.mapping.filter(m=>t.start_ms>=m.conversation_start_ms&&t.start_ms<m.conversation_end_ms).map(m=>({capture:m.capture,offset_ms:m.capture_start_ms+(t.start_ms-m.conversation_start_ms),end_ms:t.end_ms===null?null:m.capture_start_ms+(Math.min(t.end_ms,m.conversation_end_ms)-m.conversation_start_ms),partial:t.end_ms!==null&&t.end_ms>m.conversation_end_ms}));
+ if(t.basis==='wall-clock') {
+  const start=parseConversationInstant(t.start),end=parseConversationInstant(t.end);
+  spans=t.mapping.flatMap(m=>{
+   const anchor=parseConversationInstant(m.wall_start),offset=conversationCaptureOffsetMs(start,anchor,m.capture_start_ms);
+   if(offset.negative)return [];
+   return [{capture:m.capture,offset_ms:offset.value,end_ms:end===null?null:conversationCaptureOffsetMs(end,anchor,m.capture_start_ms).value}];
+  });
+ }
+ if(captureId!==undefined)spans=spans.filter(s=>s.capture===captureId);
+ const candidates=spans.flatMap(span=>candidatePaths(record,turn,span.capture).map(path=>({capture:span.capture,path,offset_ms:span.offset_ms,end_ms:span.end_ms})));
+ const gaps=[];
+ if(!candidates.length)gaps.push(diagnostic('TIMING_GAP'));
+ if(candidates.length>1)gaps.push(diagnostic(captureId===undefined?'CAPTURE_SELECTION_REQUIRED':'TIMING_MAPPING_AMBIGUOUS'));
+ if(spans.some(s=>s.partial))gaps.push(diagnostic('TIMING_PARTIAL_COVERAGE'));
+ return {candidates,gaps};
+}

package/lib/freedom-conversation-legacy.mjs

@@ -0,0 +1,167 @@
+// Read-only compatibility projection. Original bytes, not this projection, are authoritative.
+import {createHash} from 'node:crypto';
+import {basename,resolve} from 'node:path';
+import {parseFlat,stripTrailingComment} from './frontmatter/yaml.mjs';
+import {validateConversation} from './frontmatter/conversation.mjs';
+
+const hash=b=>createHash('sha256').update(b).digest('hex');
+const text=v=>typeof v==='string'&&v.length>0?v:null;
+const list=v=>Array.isArray(v)?v: text(v)?[v]:[];
+const safeKey=k=>/^[a-z][a-z0-9_]*$/.test(k)&&!['__proto__','prototype','constructor'].includes(k);
+const diag=(code,field,severity='error')=>({code,severity,path:null,field,message:'Legacy metadata requires an explicit resolution; original bytes are retained.'});
+// Existing concat producers declare scalar notes. Preserve them as metadata only;
+// sourcesFrom deliberately never uses note as locator, identity or coverage proof.
+const sourceKeys=new Set(['type','path','url','id','role','service','recording_id','note']);
+const roles=new Set(['transcript-body','metadata','generated-notes','supplemental','unknown']);
+const service=s=>typeof s==='string'&&/^[a-z][a-z0-9-]*$/.test(s);
+
+// The flat parser is deliberately string-typed. Screen syntax it otherwise accepts literally
+// (maps, anchors, tags and block scalars) before handing it any value.
+function scalar(raw) {
+ const s=stripTrailingComment(raw);
+ if(!s||/^[\[\]{}|>&*!%@`]/.test(s))throw new Error('unsupported scalar');
+ if(s[0]==='"'||s[0]==="'") {
+  const q=s[0];let end=-1;
+  for(let i=1;i<s.length;i++){if(q==='"'&&s[i]==='\\'){i++;continue;}if(s[i]===q){end=i;break;}}
+  if(end!==s.length-1)throw new Error('unsupported quote');
+ } else if(/:\s|\s[&*!][^\s]/.test(s))throw new Error('unsupported scalar');
+ return parseFlat(`value: ${s}`).value;
+}
+function flatBlock(key,lines) {
+ const raw=stripTrailingComment(lines[0].slice(lines[0].indexOf(':')+1));
+ if(raw.startsWith('[')) {
+  if(!raw.endsWith(']')||lines.slice(1).some(l=>l.trim()&&!l.trim().startsWith('#')))throw new Error('complex list');
+  const inner=raw.slice(1,-1);let q=null,part='',parts=[];
+  for(let i=0;i<inner.length;i++){const c=inner[i];if(q){part+=c;if(c==='\\'&&q==='"'){part+=inner[++i]??'';}else if(c===q)q=null;}else if(c==='"'||c==="'"){q=c;part+=c;}else if(c===','){parts.push(part);part='';}else part+=c;}
+  if(q)throw new Error('unclosed quote');
+  if(inner.trim()){parts.push(part);parts.forEach(scalar);}
+ } else if(raw) {
+  scalar(raw);if(lines.slice(1).some(l=>l.trim()&&!l.trim().startsWith('#')))throw new Error('continuation');
+ } else {
+  const items=lines.slice(1).filter(l=>l.trim()&&!l.trim().startsWith('#'));
+  const indents=new Set();
+  for(const line of items){const m=/^( +)- (.+)$/.exec(line);if(!m)throw new Error('nested');indents.add(m[1].length);scalar(m[2]);}
+  if(indents.size>1)throw new Error('indent');
+ }
+ return parseFlat(lines.join('\n'))[key];
+}
+function sourceBlock(lines) {
+ if(lines[0].slice(lines[0].indexOf(':')+1).trim())throw new Error('inline sources');
+ const items=[];let current=null,base=null,unknown=false;
+ for(const line of lines.slice(1)) {
+  if(!line.trim()||line.trim().startsWith('#'))continue;
+  const head=/^( +)- ([a-z][a-z0-9_]*):\s*(.*)$/.exec(line);
+  let key,raw;
+  if(head){if(base===null)base=head[1].length;if(head[1].length!==base)throw new Error('indent');current={};items.push(current);[, ,key,raw]=head;}
+  else {const m=/^( +)([a-z][a-z0-9_]*):\s*(.*)$/.exec(line);if(!current||!m||m[1].length!==base+2)throw new Error('source shape');[, ,key,raw]=m;}
+  if(!safeKey(key)||Object.hasOwn(current,key))throw new Error('source key');
+  const value=scalar(raw);current[key]=value;if(!sourceKeys.has(key))unknown=true;
+ }
+ return {items,unknown};
+}
+function fieldsFrom(rawHeader) {
+ const fields={},unparsed=new Set(),diagnostics=[];
+ if(rawHeader===null)return {fields,unparsed,diagnostics};
+ const blocks=[];let block=null;
+ for(const line of rawHeader.toString('utf8').split(/\r?\n/)) {
+  if(!line.trim()||line.trim().startsWith('#')){if(block)block.lines.push(line);continue;}
+  if(!/^\s/.test(line)){const m=/^([^:]+):/.exec(line);block={key:m?.[1]??'unknown',lines:[line]};blocks.push(block);}
+  else if(block)block.lines.push(line);else{unparsed.add('unknown');diagnostics.push(diag('LEGACY_FIELD_UNPARSED',null));}
+ }
+ const counts=new Map();for(const b of blocks)counts.set(b.key,(counts.get(b.key)??0)+1);
+ for(const b of blocks) {
+  const {key,lines}=b;
+  try {
+   if(!safeKey(key)||counts.get(key)>1)throw new Error('duplicate or unsafe');
+   if(key==='sources'){const s=sourceBlock(lines);fields[key]=s.items;if(s.unknown)unparsed.add(key);}
+   else fields[key]=flatBlock(key,lines);
+  }catch{unparsed.add(key);}
+ }
+ for(const key of unparsed)diagnostics.push(diag(key==='date'&&counts.get(key)>1?'DATE_CONFLICT':'LEGACY_FIELD_UNPARSED',safeKey(key)?key:null));
+ return {fields,unparsed,diagnostics};
+}
+const locator=patch=>({kind:'service',path:null,url:null,service_id:null,media_type:null,sha256:null,bytes:null,checked_at:null,backup:{status:'unverified',locator:null,sha256:null,verified_at:null},...patch});
+const namespace=c=>c.type==='cloud_recording'?`cloud:${c.service}`:c.type==='zoom_cloud'&&/^GMT\d{8}-\d{6}$/.test(c.vendor_id??'')?'zoom-cloud-gmt':({granola:'granola',meet_cloud:'meet',voice_memo:'voice-memo'}[c.type]??c.type);
+
+function sourcesFrom(fields,evidence=()=>[]) {
+ const captures=[],aliases=[],diagnostics=[];
+ const alias=(namespace,value)=>{if(namespace&&text(value)&&!aliases.some(a=>a.namespace===namespace&&a.value===value))aliases.push({kind:'source-id',namespace,value});};
+ const identity=c=>c.type==='cloud_recording'?c.recording_id:c.vendor_id;
+ function add(s,field,top=false) {
+  let type=text(s.type),vendor=text(s.id),svc=null,recording=null;
+  const url=text(s.url),path=text(s.path);
+  if(type==='cloud_recording') {
+   svc=text(s.service);recording=text(s.recording_id);
+   if(!service(svc)){diagnostics.push(diag('SOURCE_SERVICE_UNRESOLVED',field));return;}
+   if(!recording){diagnostics.push(diag('RECORDING_ID_UNRESOLVED',field));return;}
+   if(vendor&&vendor!==recording)diagnostics.push(diag('SOURCE_ID_CONFLICT',field));vendor=null;
+  }
+  if(type==='meet_cloud'&&url){const id=/\/file\/d\/([^/?#]+)/.exec(url)?.[1];if(id&&vendor&&id!==vendor){diagnostics.push(diag('SOURCE_ID_CONFLICT',field));return;}vendor??=id??null;}
+  let role=text(s.role)??'unknown';if(!roles.has(role)){diagnostics.push(diag('SOURCE_ROLE_UNRESOLVED',field));role='unknown';}
+  const locators=[];
+  if(path)locators.push(locator({kind:'external-local',path}));
+  if(url||recording||vendor)locators.push(locator({url,service_id:recording??vendor}));
+  const c={id:null,type,service:svc,recording_id:recording,vendor_id:vendor,roles:[role],locators,availability:path?'unknown':locators.length?'remote-only':'unknown',evidence:evidence(field)};
+  // Only list/top-level equivalence folds. Multiple distinct list captures stay distinct.
+  const peers=top?captures.filter(x=>x.type===type&&x.service===svc):[];
+  const existing=peers.find(x=>identity(x)&&identity(x)===identity(c))??peers[0];
+  if(existing) {
+   const a=identity(existing),b=identity(c);
+   const overlaps=['path','url','service_id'];
+   const left={path:existing.locators.find(l=>l.path)?.path??null,url:existing.locators.find(l=>l.url)?.url??null,service_id:existing.locators.find(l=>l.service_id)?.service_id??null};
+   const right={path,url,service_id:recording??vendor};
+   if(a&&b&&a!==b||overlaps.some(k=>left[k]&&right[k]&&left[k]!==right[k])){diagnostics.push(diag('SOURCE_ID_CONFLICT',field));return;}
+   if(a&&b&&a===b){existing.roles=[...new Set([...existing.roles,role])];existing.evidence.push(...c.evidence);for(const l of locators)if(!existing.locators.some(x=>JSON.stringify(x)===JSON.stringify(l)))existing.locators.push(l);return;}
+  }
+  c.id=`c-${String(captures.length+1).padStart(3,'0')}`;captures.push(c);
+  alias(namespace(c),identity(c));if(type==='zoom_cloud')alias('zoom-cloud-url',url);
+ }
+ for(const [i,s] of (Array.isArray(fields.sources)?fields.sources:[]).entries())if(s&&typeof s==='object'&&!Array.isArray(s))add(s,`sources[${i}]`);
+ for(const [key,type,urlKey] of [['granola_id','granola','granola_url'],['meet_id','meet_cloud',null],['zoom_gmt','zoom_cloud',null],['voice_memo_id','voice_memo',null]])if(text(fields[key])) {
+  if(key==='zoom_gmt'&&!/^GMT\d{8}-\d{6}$/.test(fields[key]))diagnostics.push(diag('RECORDING_ID_UNRESOLVED',key));
+  else add({type,id:fields[key],url:fields[urlKey]},key,true);
+ }
+ if(text(fields.recording_id)){if(service(fields.source)&&fields.source!=='granola')add({type:'cloud_recording',service:fields.source,recording_id:fields.recording_id,url:fields.url},'recording_id',true);else diagnostics.push(diag('SOURCE_SERVICE_UNRESOLVED','recording_id'));}
+ if(text(fields.zoom_id)){alias('zoom-meeting',fields.zoom_id);diagnostics.push(diag('RECORDING_ID_UNRESOLVED','zoom_id'));}
+ return {captures,aliases,diagnostics};
+}
+/** Exact compatibility refs; no filesystem probes or remote fetches. */
+export function legacySourceRefs(fields) {
+ return sourcesFrom(fields).captures.flatMap(c=>(c.locators.length?c.locators:[null]).flatMap(l=>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}))));
+}
+
+/** Normalize an explicit old file; never infer facts from its name or modify its bytes. */
+export function normalizeLegacy(bytes,{file}) {
+ if(!Buffer.isBuffer(bytes)||typeof file!=='string'||!file)throw new TypeError('legacy input requires bytes and a file');
+ const absolute=resolve(file),relativePath=basename(file),id=relativePath.replace(/\.md$/i,'');
+ const fileSha256=hash(bytes);
+ const base={file:absolute,relativePath,id,layout:'legacy',header:null,legacyFields:{},rawHeader:null,body:bytes,fileSha256,bodySha256:hash(bytes),sections:[],turns:[],gaps:[],diagnostics:[]};
+ const refuse=code=>({...base,diagnostics:[diag(code,null)]});
+ let decoded;try{decoded=new TextDecoder('utf-8',{fatal:true,ignoreBOM:true}).decode(bytes);}catch{return refuse('INVALID_UTF8');}
+ const open=/^(?:\uFEFF)?---(\r?\n)/.exec(decoded);
+ if(!open&&/^(?:\uFEFF)?---/.test(decoded))return refuse('MALFORMED_DELIMITER');
+ if(open){const offset=bytes.subarray(0,3).equals(Buffer.from([239,187,191]))?3:0;const start=offset+3+Buffer.byteLength(open[1]);let cursor=start,close=null;
+  while(cursor<bytes.length){const lf=bytes.indexOf(10,cursor),end=lf<0?bytes.length:lf;const line=bytes.subarray(cursor,end).toString('utf8');if(line==='---'||line==='---\r'){close={start:cursor,end:lf<0?end:end+1};break;}cursor=lf<0?bytes.length:lf+1;}
+  if(!close)return refuse('MALFORMED_DELIMITER');base.rawHeader=bytes.subarray(start,close.start);base.body=bytes.subarray(close.end);base.bodySha256=hash(base.body);
+ }
+ const parsed=fieldsFrom(base.rawHeader),f=parsed.fields;base.legacyFields=f;
+ const evidence=field=>[{kind:'existing-header',locator:`${file}#${field}`,revision:{kind:'sha256',value:fileSha256},note:'Original header declares this metadata; no human confirmation is inferred.'}];
+ const source=sourcesFrom(f,evidence);
+ const h={schema_version:1,kind:'conversation',id,title:text(f.title),description:text(f.description),read_when:list(f.read_when),date:null,start:null,as_of:null,audience:text(f.audience),keep:{scope:'unknown',group:null,decision:null},participants:[],sources:source.captures,connections:[],aliases:[{kind:'legacy-path',value:file,namespace:null},...source.aliases],review:{transcription:'unreviewed',attribution:'unreviewed',processing:'unprocessed',evidence:[]},body_format:'legacy',legacy:{original_path:file,original_revision:{kind:'sha256',value:fileSha256},raw_header_base64:base.rawHeader?.toString('base64')??null,raw_header_sha256:base.rawHeader===null?null:hash(base.rawHeader),fields:f,unparsed_keys:[...parsed.unparsed],body_sha256:base.bodySha256},extensions:{}};
+ const diagnostics=[...parsed.diagnostics,...source.diagnostics];
+ for(const key of ['date','as_of'])if(text(f[key])){const candidate={...h,[key]:f[key]};if(validateConversation(candidate).some(d=>d.field===key&&d.severity==='error'))diagnostics.push(diag('INVALID_DATE',key));else h[key]=f[key];}
+ if(['started_at','happened_at','timezone','time_precision','inferred_from','time_local','start_local','start'].some(k=>Object.hasOwn(f,k)||parsed.unparsed.has(k)))diagnostics.push(diag('TIME_BASIS_UNRESOLVED','start','warning'));
+ for(const key of ['private','sensitivity','keep','scope','sharing']) {
+  if(parsed.unparsed.has(key)){diagnostics.push(diag('RESTRICTION_UNRESOLVED',key));continue;}
+  if(!Object.hasOwn(f,key))continue;
+  if(key==='private'&&f[key]==='true'||key==='sensitivity'&&['private','confidential','restricted'].includes(f[key]))h.keep.scope='home';
+  else if(!(key==='private'&&f[key]==='false'))diagnostics.push(diag('RESTRICTION_UNRESOLVED',key));
+ }
+ for(const key of ['participants','attendees'])for(const label of list(f[key]).filter(text))h.participants.push({id:`p-${String(h.participants.length+1).padStart(3,'0')}`,label,person:null,status:'unknown',role:key==='attendees'?'attendee':'unknown',evidence:evidence(key)});
+ if(text(f.id)&&f.id!==id)h.aliases.push({kind:'record-id',value:f.id,namespace:null});
+ if(text(f.meeting_key))h.extensions.meeting_key=f.meeting_key;
+ diagnostics.push(...validateConversation(h));
+ if(h.sources.length===0)diagnostics.push(diag('SOURCE_UNKNOWN','sources','warning'));
+ base.header=h;base.diagnostics=diagnostics;base.gaps=diagnostics.filter(d=>d.severity==='warning'||d.code.endsWith('_UNRESOLVED'));
+ return base;
+}

package/lib/freedom-conversation-lock.mjs

@@ -0,0 +1,41 @@
+// Mutation-only module. The read door never imports subprocesses or locks.
+import {execFileSync} from 'node:child_process';
+import {realpathSync,lstatSync,mkdirSync} from 'node:fs';
+import {resolve,join} from 'node:path';
+import {paths,stateDir} from './freedom-workspace.mjs';
+import {acquire,release} from './freedom-run-lock.mjs';
+import {withRunLock,MIGRATE_LOCK} from './freedom-migrate-common.mjs';
+
+const refuse=code=>{throw Object.assign(new Error(`${code}: Conversation mutation lock refused.`),{code});};
+/** Git's common-dir output is resolved against the actual command cwd, including subfolders. */
+export function conversationLockContext(root) {
+ if(typeof root!=='string'||!root)refuse('WORKSPACE_REQUIRED');
+ const workspace=realpathSync(resolve(root));
+ let gitCommonDir=null;
+ try {
+  const output=execFileSync('git',['rev-parse','--path-format=absolute','--git-common-dir'],{cwd:workspace,encoding:'utf8',stdio:['ignore','pipe','pipe']}).trim();
+  gitCommonDir=realpathSync(resolve(workspace,output));
+ } catch(e) {
+  if(e.status!==128||!String(e.stderr).includes('not a git repository'))refuse('LOCK_IDENTITY_UNAVAILABLE');
+ }
+ const transcripts=resolve(paths(workspace).transcripts);
+ return {root:workspace,transcripts,gitCommonDir,scope:gitCommonDir?'common-git':'transcript-root-only',
+  lockPath:gitCommonDir?join(gitCommonDir,'freedom-conversation-mutation.lock'):join(transcripts,'.conversation-mutation.lock'),
+  journalDir:gitCommonDir?join(gitCommonDir,'freedom-conversation-revisions'):stateDir('conversation-revisions',workspace)};
+}
+const noLink=file=>{try{if(lstatSync(file).isSymbolicLink())refuse('SYMLINK_REFUSED');}catch(e){if(e.code!=='ENOENT')throw e;}};
+/** Hold common-repository lock first, then the existing capture lock, throughout fn. */
+export function withConversationLock(root,{pid,by},fn) {
+ const context=conversationLockContext(root);
+ noLink(context.transcripts);noLink(context.lockPath);
+ if(!context.gitCommonDir)mkdirSync(context.transcripts,{recursive:true});
+ const lock=acquire(context.lockPath,{pid,by});
+ if(!lock.acquired)refuse('LOCKED');
+ try {
+  noLink(stateDir(MIGRATE_LOCK,context.root));noLink(join(stateDir(MIGRATE_LOCK,context.root),'.lock'));
+  let entered=false;
+  const result=withRunLock(context.root,{pid,by},()=>{entered=true;return fn();});
+  if(!entered)refuse('LOCKED'); // Capture refusal is a result object, never fn success.
+  return result;
+ } finally {if(!lock.reentrant)release(context.lockPath,{pid});}
+}

package/lib/freedom-conversation-time.mjs

@@ -0,0 +1,36 @@
+// Zoned Instants retain their full decimal fraction until relative arithmetic is complete.
+// Date handles only validated whole seconds, which are exact throughout four-digit years.
+export function parseConversationInstant(value) {
+ if(typeof value!=='string')return null;
+ const m=/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z|[+-](\d{2}):(\d{2}))$/.exec(value);
+ if(!m)return null;
+ const year=+m[1],month=+m[2],day=+m[3],leap=year%4===0&&(year%100!==0||year%400===0);
+ if(month<1||month>12||day<1||day>[31,leap?29:28,31,30,31,30,31,31,30,31,30,31][month-1]||+m[4]>=24||+m[5]>=60||+m[6]>=60||m[9]&&(+m[9]>=24||+m[10]>=60))return null;
+ const whole=Date.parse(`${m[1]}-${m[2]}-${m[3]}T${m[4]}:${m[5]}:${m[6]}${m[8]}`);
+ if(!Number.isFinite(whole))return null;
+ return {seconds:BigInt(whole/1000),fraction:(m[7]??'').replace(/0+$/,'')};
+}
+const power=scale=>10n**BigInt(scale);
+function differenceMilliseconds(left,right) {
+ const scale=Math.max(left.fraction.length,right.fraction.length);
+ const fraction=value=>BigInt(value.fraction.padEnd(scale,'0')||'0');
+ return {units:((left.seconds-right.seconds)*power(scale)+fraction(left)-fraction(right))*1000n,scale};
+}
+export function compareConversationInstants(left,right) {
+ const {units}=differenceMilliseconds(left,right);
+ return units<0n?-1:units>0n?1:0;
+}
+// Convert the declared Number offset's decimal representation, including exponent notation.
+// Add it before rounding, so cancellation cannot turn an exact negative offset into zero.
+function decimalMilliseconds(value) {
+ const [mantissa,exponent='0']=String(value).split('e');
+ let units=BigInt(mantissa.replace('.','')),scale=(mantissa.split('.')[1]?.length??0)-Number(exponent);
+ if(scale<0){units*=power(-scale);scale=0;}
+ return {units,scale};
+}
+export function conversationCaptureOffsetMs(at,anchor,captureStartMs) {
+ const delta=differenceMilliseconds(at,anchor),base=decimalMilliseconds(captureStartMs);
+ const scale=Math.max(delta.scale,base.scale);
+ const units=delta.units*power(scale-delta.scale)+base.units*power(scale-base.scale);
+ return {value:Number(`${units}e-${scale}`),negative:units<0n};
+}