@arcfold/dsh 0.0.0-stage → 0.4.0

package/src/importer.mjs

@@ -0,0 +1,298 @@
+import { DomainError, canonicalJson, identity } from './store.mjs';
+import { IMPORT_LIMITS, readLegacyImport, importDigest, textDigest, importMethodField } from './legacy-import-source.mjs';
+import { invalidateDependents } from './learning-goals.mjs';
+import { projectUnderstanding } from './learning-contracts.mjs';
+import { usageForVersion } from './methods.mjs';
+import { browseScope } from './browse-scope.mjs';
+
+const fail = (code,message) => { throw new DomainError(code,message); };
+const nonnegative = value => Number.isSafeInteger(value) && value >= 0;
+const positive = value => Number.isSafeInteger(value) && value > 0;
+const usable = row => ['enabled','trial','paused'].includes(row.eligibility);
+const safeErrors = new Set(['import_token_limit','import_depth_limit','import_key_limit','import_duplicate_key','import_number_limit',
+  'invalid_import_file','import_chunk_limit','import_byte_limit','import_digest_mismatch','import_incomplete','invalid_import_json',
+  'invalid_import_format','import_projection_limit','import_string_limit','import_record_limit','invalid_import_identity',
+  'import_scope_limit','empty_import','invalid_import_export','invalid_import_source','import_scope_unknown']);
+function page(rows,offset,limit) { return {items:rows.slice(offset,offset+limit),total:rows.length,nextOffset:offset+limit<rows.length?offset+limit:null}; }
+function pagination(offset,limit,max) { if(!nonnegative(offset)||!positive(limit)||limit>max) fail('invalid_import_page','分页范围无效。'); }
+function mapping(sessionId,scopeMap=[]) {
+  if(!Array.isArray(scopeMap)||scopeMap.length>1) fail('invalid_import_scope','仅可选择一个旧交流。');
+  return scopeMap.map(row=>{
+    if(!row||Object.keys(row).sort().join(',')!=='sourceConversationId,targetSessionId'||row.targetSessionId!==sessionId)
+      fail('invalid_import_scope','旧交流只能映射到当前主交流。');
+    identity(row.sourceConversationId,'Old conversation');return {...row};
+  });
+}
+const commandId = (op,sessionId,requestId) => 'import-command:'+importDigest([op,sessionId,requestId]);
+const batchId = (sessionId,requestId) => 'import:'+importDigest([sessionId,requestId]);
+const publicBatch = row => Object.fromEntries(['id','revision','sessionId','status','file','format','previewHash','scopeMap','sourceScopes','counts','createdAt','updatedAt','error'].map(key=>[key,row[key]]));
+const emptyCounts = () => ({sources:0,records:0,enabled:0,trial:0,paused:0,history:0,needsReview:0});
+const methodBody=row=>({title:row.title??'',guidance:row.guidance??'',appliesTo:row.appliesTo??'',doesNotApplyTo:row.doesNotApplyTo??''});
+const targetScope=row=>({...(row.scope.topics?.length?{topics:row.scope.topics}:{}),...(row.scope.kind==='mapped'?{conversationId:row.scope.targetSessionId}:{})});
+function normalizedExistingScope(row){
+  const scope=row.scope??{};
+  if(!scope||typeof scope!=='object'||Array.isArray(scope)||Object.keys(scope).some(key=>!['conversationId','topics'].includes(key))||
+    scope.topics!==undefined&&!Array.isArray(scope.topics))return null;
+  return {...(scope.topics?.length?{topics:scope.topics}:{}),...(scope.conversationId?{conversationId:scope.conversationId}:{})};
+}
+
+/** Business import only: the caller proves owner/live-main/native receipt. */
+export class ImportService {
+  constructor({business}) {
+    if(!business?.storage) fail('invalid_import_config','需要业务存储。');
+    this.store=business.storage;this.inflight=new Map();this.closed=false;this.abort=new AbortController();
+    this.store.transaction(()=>{
+      for(const row of this.store.listAll('import_batches',{where:{status:'preparing'}}))
+        this.store.save('import_batches',{...row,status:'failed',error:{code:'import_interrupted',message:'上次准备未完成；没有自动重试或确认。'}},{expectedRevision:row.revision});
+    });
+  }
+  async close() { this.closed=true;this.abort.abort();await Promise.allSettled([...this.inflight.values()]); }
+  compareMethod(row,existing){
+    const bodyHash=importDigest(methodBody(row.original));
+    const sameIdentity=existing.filter(old=>old.importProvenance?.originalId===row.originalId&&old.importProvenance.originalVersion===row.version&&
+      (!old.importProvenance.originalFormat||old.importProvenance.originalFormat===row.originalFormat));
+    const matches=sameIdentity.length?sameIdentity:existing.filter(old=>importDigest(methodBody(old))===bodyHash);
+    const evidence=matches.map(old=>{let usage;try{usage=usageForVersion(this.store,old);}catch{usage=null;}
+      return {id:old.id,revision:old.revision,recordHash:importDigest(old),usage};});
+    if(!matches.length)return {match:'new',evidence};
+    const same=matches.length===1&&importDigest(methodBody(matches[0]))===bodyHash&&normalizedExistingScope(matches[0])!==null&&
+      canonicalJson(normalizedExistingScope(matches[0]))===canonicalJson(targetScope(row))&&evidence[0].usage!==null;
+    return {match:same?'duplicate':'conflict',existingRecordId:matches[0].id,evidence};
+  }
+  preparationRequest({sessionId,receiptId,requestId,scopeMap=[]}) {
+    identity(sessionId,'Session');identity(receiptId,'Receipt');identity(requestId,'Request');
+    return {sessionId,receiptId,requestId,scopeMap:mapping(sessionId,scopeMap)};
+  }
+  replayPreparation(input) {
+    const request=this.preparationRequest(input),old=this.store.get('import_batches',batchId(request.sessionId,request.requestId));
+    if(!old)return null;
+    if(old.requestHash!==importDigest(request))fail('import_identity_conflict','这个提交编号已绑定另一份内容。');
+    return this.inflight.get(old.id) || publicBatch(old);
+  }
+  async prepare(input) {
+    const request=this.preparationRequest(input),prior=this.replayPreparation(request);
+    if(prior)return await prior;
+    if(this.closed)fail('import_unavailable','导入服务已停止。');
+    const {file,read,signal,userIdentity}=input;
+    if(!file||typeof file.name!=='string'||file.name.length>512||!nonnegative(file.bytes)||file.bytes>IMPORT_LIMITS.maxFileBytes||
+      !/^[a-f0-9]{64}$/.test(file.sha256)||typeof read!=='function')fail('invalid_import_file','原生附件元数据无效。');
+    identity(userIdentity,'Owner');
+    const row=this.store.save('import_batches',{id:batchId(request.sessionId,request.requestId),...request,
+      requestHash:importDigest(request),status:'preparing',file:{name:file.name,bytes:file.bytes,sha256:file.sha256},
+      format:null,previewHash:null,scopeMap:request.scopeMap,sourceScopes:[],counts:emptyCounts(),error:null,owner:userIdentity});
+    const pending=Promise.resolve().then(async()=>{
+      try {
+        const abort=signal?AbortSignal.any([signal,this.abort.signal]):this.abort.signal;
+        abort.throwIfAborted();
+        const parsed=await readLegacyImport({stream:read(abort),expectedBytes:file.bytes,expectedSha256:file.sha256,signal:abort});
+        abort.throwIfAborted();
+        if(request.scopeMap.some(m=>!parsed.sourceScopes.some(s=>s.sourceConversationId===m.sourceConversationId)))
+          fail('import_scope_unknown','映射的旧交流不在这份完整导出中。');
+        const mapped=new Map(request.scopeMap.map(m=>[m.sourceConversationId,m.targetSessionId]));
+        const records=parsed.records.map(item=>{
+          const target=item.scope.global?null:mapped.get(item.scope.sourceConversationId)||null;
+          const scope={kind:item.scope.global?'global':target?'mapped':'historical',
+            sourceConversationId:item.scope.sourceConversationId,targetSessionId:target,...(item.scope.topics?{topics:item.scope.topics}:{})};
+          return {...item,originalFormat:parsed.format,scope,...(!item.scope.global&&!target&&usable(item)?{eligibility:'history',reasonCodes:[...item.reasonCodes,'scope_not_mapped']}:{})};
+        });
+        for(const item of records)if(item.kind==='understandings'){
+          const direct=parsed.sources.map(source=>({id:source.id,role:source.role,content:source.content,revision:source.originalVersion,withdrawn:!source.available}));
+          const dependencies=(item.original.dependencies||[]).map(ref=>{
+            const kind=ref.kind||['events','understandings','methods'].find(kind=>kind==='events'?parsed.sources.some(source=>source.originalId===ref.id):records.some(record=>record.kind===kind&&record.originalId===ref.id));
+            return {...ref,kind:kind??'unknown',id:kind+':'+ref.id};
+          });
+          item.claimType=parsed.format==='arcfold2-database-snapshot'?'inference':projectUnderstanding({content:item.content,
+            claimType:item.original.claimType||'inference',proposedClaimType:item.original.proposedClaimType??item.original.claimType??'inference',
+            sourceIds:item.sourceIds,dependencies},direct).claimType;
+        }
+        const methodGroups=new Map();
+        for(const item of records)if(item.kind==='methods'&&usable(item)){
+          const key=importDigest(methodBody(item.original));
+          methodGroups.set(key,[...(methodGroups.get(key)||[]),item]);
+        }
+        for(const group of methodGroups.values())if(group.length>1)for(const item of group){
+          item.eligibility='needs_review';item.reasonCodes.push('method_batch_conflict');
+        }
+        const existingMethods=this.store.listAll('methods');
+        for(const item of records){
+          if(item.kind!=='methods'||!usable(item))continue;
+          item.methodCheck=this.compareMethod(item,existingMethods);
+          if(item.methodCheck.match!=='new'){
+            item.existingRecordId=item.methodCheck.existingRecordId;
+            item.eligibility=item.methodCheck.match==='duplicate'?'history':'needs_review';
+            item.reasonCodes.push(item.methodCheck.match==='duplicate'?'method_already_present':'method_existing_conflict');
+          }
+        }
+        // A qualified dependency cannot be silently widened through a global parent.
+        const byId=new Map(records.map(item=>[item.id,item]));let changed;
+        do {changed=false;for(const item of records){
+          if(!usable(item))continue;
+          for(const ref of item.original.dependencies || []){
+            const kind=ref.kind||['events','understandings','methods'].find(k=>k==='events'?parsed.sources.some(s=>s.originalId===ref.id):byId.has(k+':'+ref.id));
+            if(kind==='events')continue;
+            const dep=byId.get(kind+':'+ref.id);
+            if(!dep||!usable(dep)||dep.eligibility==='paused'){
+              item.eligibility='needs_review';item.reasonCodes.push('dependency_not_eligible');changed=true;break;
+            }
+            if(dep.scope.kind!=='global'&&(item.scope.kind!=='mapped'||dep.scope.kind!=='mapped'||item.scope.targetSessionId!==dep.scope.targetSessionId)){
+              item.eligibility='needs_review';item.reasonCodes.push('dependency_scope_mismatch');changed=true;break;
+            }
+          }
+        }}while(changed);
+        const counts=emptyCounts();counts.sources=parsed.sources.length;counts.records=records.length;
+        for(const item of records)counts[item.eligibility==='needs_review'?'needsReview':item.eligibility]++;
+        const previewHash=importDigest({file:row.file,format:parsed.format,scopeMap:request.scopeMap,
+          provenance:parsed.provenance,sources:parsed.sources,records,history:parsed.history});
+        return this.store.transaction(()=>{
+          abort.throwIfAborted();
+          for(const source of parsed.sources)this.store.save('import_sources',{...source,id:row.id+':source:'+importDigest(source.id),
+            batchId:row.id,sourceKey:source.id,textKey:'source:'+importDigest(source.id),sha256:textDigest(source.content)});
+          for(const record of records)this.store.save('import_records',{...record,id:row.id+':record:'+importDigest(record.id),
+            batchId:row.id,recordKey:record.id,textKey:'record:'+importDigest(record.id),originalTextKey:'original:'+importDigest(record.id)});
+          for(const [index,entry] of parsed.history.entries())this.store.save('import_history',{id:row.id+':history:'+index,batchId:row.id,...entry});
+          const projectionHash=importDigest(['import_sources','import_records','import_history'].map(kind=>this.store.listAll(kind,{where:{batchId:row.id}})));
+          const saved=this.store.save('import_batches',{...row,status:'ready',format:parsed.format,previewHash,projectionHash,
+            sourceScopes:parsed.sourceScopes,counts,provenance:parsed.provenance},{expectedRevision:row.revision});
+          return publicBatch(saved);
+        });
+      }catch(error){
+        const current=this.store.get('import_batches',row.id);
+        const code=safeErrors.has(error?.code)?error.code:'import_prepare_failed';
+        return publicBatch(this.store.save('import_batches',{...current,status:'failed',previewHash:null,
+          error:{code,message:safeErrors.has(code)?error.message.slice(0,240):'附件准备未完成；原文未启用，没有自动重试。'}},{expectedRevision:current.revision}));
+      }
+    });
+    this.inflight.set(row.id,pending);
+    try{return await pending;}finally{this.inflight.delete(row.id);}
+  }
+  list({sessionId,viewScope,offset=0,limit=20}) {
+    identity(sessionId,'Session');pagination(offset,limit,100);
+    if(browseScope(viewScope,'all')==='current') {
+      const rows=this.store.listAll('import_batches',{where:{sessionId}}).reverse();
+      return page(rows.map(publicBatch),offset,limit);
+    }
+    const total=this.store.db.prepare("SELECT COUNT(*) AS n FROM records WHERE kind='import_batches'").get().n;
+    const items=this.store.list('import_batches',{offset,limit,order:'desc'}).map(publicBatch);
+    return {items,total,nextOffset:offset+limit<total?offset+limit:null};
+  }
+  batch(id) {identity(id,'Batch');const row=this.store.get('import_batches',id);if(!row)fail('import_not_found','导入批次不存在。');return row;}
+  details({sessionId,batchId:id,view='records',offset=0,limit,textKey}) {
+    identity(sessionId,'Session');const batch=this.batch(id),header=publicBatch(batch);
+    if(!['records','sources','text'].includes(view))fail('invalid_import_page','预览类型无效。');
+    limit??=view==='text'?16000:20;pagination(offset,limit,view==='text'?32000:50);
+    if(view==='text'){
+      identity(textKey,'Text');
+      const ordinary=['import_sources','import_records'].flatMap(kind=>this.store.list(kind,{where:{batchId:id,textKey},limit:1}))[0];
+      const original=this.store.list('import_records',{where:{batchId:id,originalTextKey:textKey},limit:1})[0];
+      const row=ordinary||original;
+      if(!row)fail('import_text_denied','该原文不属于此批预览。');
+      const text=original?canonicalJson(row.original):row.content;
+      return {batch:header,view,textKey,text:text.slice(offset,offset+limit),offset,total:text.length,nextOffset:offset+limit<text.length?offset+limit:null};
+    }
+    if(textKey!==undefined)fail('invalid_import_page','记录列表不接受原文编号。');
+    const rows=this.store.listAll(view==='records'?'import_records':'import_sources',{where:{batchId:id}});
+    const projected=rows.map(row=>view==='sources'?{id:row.sourceKey,originalId:row.originalId,role:row.role,
+      sourceConversationId:row.sourceConversationId,occurredAt:row.occurredAt,textPreview:row.content.slice(0,240),textKey:row.textKey,
+      sha256:row.sha256,available:row.available}:{id:row.recordKey,kind:row.kind,originalId:row.originalId,
+      title:row.kind==='methods'?importMethodField(row.original,'title'):String(row.original.title || '').slice(0,120),
+      textPreview:row.content.slice(0,240),textKey:row.textKey,...(row.originalTextKey?{originalTextKey:row.originalTextKey}:{}),
+      eligibility:row.eligibility,reasonCodes:row.reasonCodes,sourceIds:row.sourceIds,scope:row.scope,
+      ...(row.kind==='methods'?{appliesTo:importMethodField(row.original,'appliesTo'),doesNotApplyTo:importMethodField(row.original,'doesNotApplyTo')}:{}),
+      ...(row.kind==='understandings'?{claimType:row.claimType}:{}),
+      ...(row.methodUsage?{methodUsage:row.methodUsage}:{}),...(row.existingRecordId?{existingRecordId:row.existingRecordId}:{})});
+    return {batch:header,view,...page(projected,offset,limit)};
+  }
+  mutation(op,input,apply) {
+    const {sessionId,batchId:id,expectedRevision,previewHash,requestId,userIdentity}=input;
+    for(const value of [sessionId,id,requestId,userIdentity])identity(value,'Request identity');
+    if(!positive(expectedRevision)||!/^[a-f0-9]{64}$/.test(previewHash))fail('invalid_import_request','确认必须绑定完整预览和版本。');
+    const request={sessionId,batchId:id,expectedRevision,previewHash,requestId},key=commandId(op,sessionId,requestId),requestHash=importDigest(request);
+    return this.store.transaction(()=>{
+      const prior=this.store.get('import_commands',key);
+      if(prior){if(prior.requestHash!==requestHash)fail('import_identity_conflict','这个提交编号已绑定另一项决定。');return prior.result;}
+      const batch=this.batch(id);
+      if(batch.revision!==expectedRevision||batch.previewHash!==previewHash)fail('revision_conflict','预览版本已变化，请重新查看。');
+      const result=publicBatch(apply(batch));
+      this.store.save('import_commands',{id:key,operation:op,request,requestHash,actor:'user',userIdentity,result,
+        authority:'listed-knowledge-guidance-only; no-tools-execution-spending-or-goal-control'});
+      return result;
+    });
+  }
+  confirm(input) {return this.mutation('confirm',input,batch=>{
+    if(batch.sessionId!==input.sessionId||batch.status!=='ready')fail('import_not_confirmable','仅能在准备预览的当前主交流中确认完整预览。');
+    const fingerprint=importDigest([batch.file.sha256,batch.scopeMap]);
+    const prior=this.store.get('import_applications',fingerprint);
+    if(prior){const existing=this.batch(prior.batchId);if(existing.status==='withdrawn')fail('import_already_withdrawn','相同来源批次已撤销，不会借重复准备重新启用。');return existing;}
+    const sources=this.store.listAll('import_sources',{where:{batchId:batch.id}}),records=this.store.listAll('import_records',{where:{batchId:batch.id}});
+    if(importDigest([sources,records,this.store.listAll('import_history',{where:{batchId:batch.id}})])!==batch.projectionHash)
+      fail('import_dependency_changed','保存的预览正文已变化，未导入。');
+    const existingMethods=this.store.listAll('methods');
+    for(const row of records)if(row.methodCheck&&canonicalJson(row.methodCheck)!==canonicalJson(this.compareMethod(row,existingMethods)))
+      fail('import_dependency_changed','已有方法或试用记录已变化，请重新准备预览。');
+    const saved=new Map(),byKey=new Map(records.map(row=>[row.recordKey,row]));
+    const targetId=key=>'legacy:'+importDigest([fingerprint,key]);
+    const mapped=new Map(batch.scopeMap.map(row=>[row.sourceConversationId,row.targetSessionId]));
+    for(const source of sources){
+      const conversationId=mapped.get(source.sourceConversationId)||'legacy-conversation:'+importDigest([fingerprint,source.sourceConversationId]);
+      const event=this.store.save('events',{id:targetId(source.sourceKey),conversationId,sessionId:conversationId,role:source.role,author:source.role,
+        content:source.content,occurredAt:source.occurredAt,importBatchId:batch.id,
+        provenance:{...source.provenance,importBatchId:batch.id,originalId:source.originalId,originalRevision:source.originalVersion,
+          originalConversationId:source.sourceConversationId,fileSha256:batch.file.sha256,bodySha256:source.sha256}});
+      saved.set(source.sourceKey,event);
+      if(!source.available)this.store.save('source_controls',{id:event.id,withdrawn:true,useProhibited:true,reason:'legacy_source_unavailable',importBatchId:batch.id});
+    }
+    function currentDependency(ref){
+      const kind=ref.kind||['events','understandings','methods'].find(kind=>saved.has(kind+':'+ref.id)||byKey.has(kind+':'+ref.id));
+      const key=kind+':'+ref.id;
+      if(!saved.has(key))write(byKey.get(key));
+      const row=saved.get(key);if(!row)fail('import_dependency_changed','预览的依赖不能完整写入。');
+      return {kind,id:row.id,revision:row.revision};
+    }
+    const store=this.store;
+    function write(row){
+      if(!row||!usable(row)||saved.has(row.recordKey))return;
+      const original=row.original,scope=targetScope(row);
+      const sourceIds=row.sourceIds.map(key=>saved.get(key)?.id);
+      if(sourceIds.some(id=>!id))fail('import_dependency_changed','预览的原话缺失。');
+      const dependencies=(original.dependencies||[]).map(currentDependency);
+      for(const key of row.sourceIds){const source=saved.get(key);if(!dependencies.some(ref=>ref.id===source.id))dependencies.push({kind:'events',id:source.id,revision:source.revision});}
+      const provenance={importBatchId:batch.id,originalFormat:row.originalFormat,originalId:row.originalId,originalRevision:original.revision ?? null,
+        originalVersion:row.version,fileSha256:batch.file.sha256};
+      const common={id:targetId(row.recordKey),conversationId:row.scope.targetSessionId||'legacy-conversation:'+importDigest([fingerprint,row.scope.sourceConversationId]),
+        scope,sourceIds,dependencies,version:row.version,importBatchId:batch.id,importProvenance:provenance};
+      let value;
+      if(row.kind==='understandings'){
+        const old2=row.originalFormat==='arcfold2-database-snapshot';
+        value=projectUnderstanding({...common,content:row.content,status:'active',claimType:old2?'inference':original.claimType||'inference',
+          proposedClaimType:old2?'inference':original.proposedClaimType??original.claimType??'inference'},row.sourceIds.map(key=>saved.get(key)));
+        if(value.claimType!==row.claimType)fail('import_dependency_changed','理解性质与已确认预览不符，未导入。');
+      }
+      else if(row.kind==='methods')value={...common,title:original.title,guidance:original.guidance,appliesTo:original.appliesTo,
+        doesNotApplyTo:original.doesNotApplyTo,status:original.status,trialUses:row.methodUsage.trialUses,maxTrialUses:row.methodUsage.maxTrialUses,
+        validated:false,origin:'imported_guidance',signature:importDigest({title:original.title,guidance:original.guidance,appliesTo:original.appliesTo,doesNotApplyTo:original.doesNotApplyTo}),
+        pauseReason:original.pauseReason ?? null,authority:'work-guidance-only; no-new-tool-or-permission',
+        activationSourceId:original.activationSourceId?saved.get('events:'+original.activationSourceId)?.id ?? null:null,
+        importedTrialBasis:{trialUses:row.methodUsage.trialUses,version:row.version,source:'complete-legacy-export'}};
+      else return;
+      saved.set(row.recordKey,store.save(row.kind,value));
+    }
+    for(const row of records)write(row);
+    const appliedIds=[...saved.values()].map(row=>row.id);
+    this.store.save('import_applications',{id:fingerprint,batchId:batch.id,fileSha256:batch.file.sha256,scopeMap:batch.scopeMap,appliedIds});
+    return this.store.save('import_batches',{...batch,status:'confirmed',fingerprint,appliedIds},{expectedRevision:batch.revision});
+  });}
+  withdraw(input) {return this.mutation('withdraw',input,batch=>{
+    if(batch.status!=='confirmed')fail('import_not_withdrawable','只有已确认批次可以撤销。');
+    const ids=[];
+    for(const source of this.store.listAll('events',{where:{importBatchId:batch.id}})){
+      const old=this.store.get('source_controls',source.id);
+      if(!old?.withdrawn)this.store.save('source_controls',{...old,id:source.id,withdrawn:true,useProhibited:true,
+        reason:'import_batch_withdrawn',importBatchId:batch.id},{expectedRevision:old?.revision ?? null});
+      ids.push(source.id);
+    }
+    const changes=invalidateDependents(this.store,{ids,pendingId:batch.id,reason:'import_batch_withdrawn'});
+    this.store.save('audit',{id:'import-withdraw:'+batch.id,actor:'user',action:'import_batch_withdrawn',batchId:batch.id,
+      sourceIds:ids,changes,meaning:'future knowledge eligibility only; original sources, independent later experience and goal control retained'});
+    return this.store.save('import_batches',{...batch,status:'withdrawn'},{expectedRevision:batch.revision});
+  });}
+}

package/src/index.mjs

@@ -0,0 +1,53 @@
+import { OpportunityService } from './opportunities.mjs';
+import { ImportService } from './importer.mjs';
+import { BusinessStore } from './business.mjs';
+import { SessionBridge } from './session-bridge.mjs';
+import { MethodService } from './methods.mjs';
+import { GoalService } from './goals.mjs';
+import { UnderstandingService } from './understandings.mjs';
+import { GoalExecution } from './goal-execution.mjs';
+
+export const name = 'arcfold-business';
+export const inject = ['sessions', 'sessionPersistence', 'llm'];
+export async function apply(ctx, config = {}) {
+  if (config.goalTreeV3?.enabled !== undefined && typeof config.goalTreeV3.enabled !== 'boolean') throw new Error('goalTreeV3.enabled must be an explicit boolean');
+  ctx.provide('arcfoldTreeMode', Object.freeze({ enabled: config.goalTreeV3?.enabled === true }));
+  if (config.goalTreeV3?.enabled === true) {
+    const { installTreeRuntime } = await import('./tree/runtime.mjs');
+    await installTreeRuntime(ctx, config.goalTreeV3, { legacyFilename: config.filename });
+    return;
+  }
+  const desktopState = ctx.get('arcfoldDesktopSetup')?.status().state;
+  if (!config.filename && ['needs_setup', 'configured', 'activation_failed', 'interrupted', 'unavailable'].includes(desktopState)) {
+    ctx.provide('arcfoldLegacyMode', Object.freeze({ enabled: true }));
+    return;
+  }
+  // The native Loader adds this dependency to the original execution entries.
+  // Dependency activation is reactive; disabled expressions are not.
+  ctx.provide('arcfoldLegacyMode', Object.freeze({ enabled: true }));
+  if (config.goalTreeV3?.enabled !== undefined && config.goalTreeV3.enabled !== false) throw new Error('goalTreeV3.enabled must be an explicit boolean');
+  if (typeof config.filename !== 'string' || !config.filename) throw new Error('An explicit Arcfold business database path is required');
+  const business = new BusinessStore({ filename: config.filename });
+  const opportunities = new OpportunityService({ business });
+  const imports = new ImportService({ business });
+  const methods = new MethodService({ business });
+  const goals = new GoalService({ business });
+  const understandings = new UnderstandingService({ business, goals });
+  const bridge = new SessionBridge({ business, methods, goals, understandings, sessions: ctx.sessions, persistence: ctx.sessionPersistence,
+    logger: ctx.logger, maxContextCharacters: config.maxContextCharacters ?? 24000 });
+  const work = new GoalExecution({ business });
+  bridge.work = work;
+  goals.execution = work;
+  ctx.effect(() => async () => { await imports.close(); await bridge.close(); }, 'close Arcfold business storage after reconciliation');
+  ctx.on('session/event', (session, event) => bridge.observe(session, event));
+  ctx.on('llm/stream', (options, next) => bridge.guardStream(options, next));
+  await bridge.recover();
+  ctx.provide('arcfoldBusiness', business);
+  ctx.provide('arcfoldOpportunities', opportunities);
+  ctx.provide('arcfoldImports', imports);
+  ctx.provide('arcfoldBridge', bridge);
+  ctx.provide('arcfoldMethods', methods);
+  ctx.provide('arcfoldGoals', goals);
+  ctx.provide('arcfoldWork', work);
+  ctx.provide('arcfoldUnderstandings', understandings);
+}

package/src/learning-contracts.mjs

@@ -0,0 +1,220 @@
+// Extracted from Arcfold 3.0 src/contracts.mjs (four Learn schemas and parsers),
+// src/evidence.mjs (literal-user projection), src/prompts.mjs (learning policy).
+// No Service, Work, model client or execution state is imported.
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './store.mjs';
+export class ContractError extends Error {
+  constructor(code, message, details = null) { super(message); this.name = 'ContractError'; this.code = code; this.details = details; }
+}
+export const digest = value => createHash('sha256').update(canonicalJson(value)).digest('hex');
+export const clone = value => structuredClone(value);
+const str = (maxLength = 4000, minLength = 0) => ({ type: 'string', minLength, maxLength });
+const list = (items, maxItems = 12) => ({ type: 'array', items, maxItems });
+const obj = properties => ({ type: 'object', properties, required: Object.keys(properties), additionalProperties: false });
+const enumeration = values => ({ type: 'string', enum: values });
+const ids = max => list(str(200, 1), max);
+
+// One finite action definition supplies both model instructions and executable
+// schema branches. Membership/current-version checks still belong to commit.
+const newTarget = { schema: { ...str(200), enum: [''] }, example: '',
+  instruction: '必须严格为 ""；新记录编号由程序生成，不能填空白、拟造编号或临时别名' };
+const existingTarget = collection => ({ schema: { ...str(200, 1), pattern: '\\S' },
+  example: `${collection}-visible-id`,
+  instruction: `必须逐字选用 ${collection} 中显示的现有编号；不能为空或自行编造，提交时仍核当前记录与版本` });
+const goalAlias = { schema: { ...str(200), pattern: '^(?:|new-goal:[\\s\\S]*)(?![\\s\\S])' }, example: 'new-goal:example',
+  instruction: '可为 ""，或以 new-goal: 开头的本区新建目标临时别名；非空别名须在本区唯一，只用于关系引用，不是持久编号' };
+const noAlias = { schema: { ...str(200), enum: [''] }, example: '', instruction: '必须严格为 ""；更新已有目标不能声明新建别名' };
+const actionRules = {
+  understandings: { create: { targetId: newTarget }, supersede: { targetId: existingTarget('existingUnderstandings') }, withdraw: { targetId: existingTarget('existingUnderstandings') } },
+  methods: { create: { targetId: newTarget }, revise: { targetId: existingTarget('existingMethods') }, pause: { targetId: existingTarget('existingMethods') } },
+  opportunities: { create: { targetId: newTarget }, reuse: { targetId: existingTarget('existingOpportunities') } },
+  goals: { create: { targetId: newTarget, clientRef: goalAlias }, update: { targetId: existingTarget('existingGoals'), clientRef: noAlias } },
+};
+const operations = section => enumeration(Object.keys(actionRules[section]));
+function actionObject(section, properties) {
+  // Keep shared properties/limits available to the legacy import projection.
+  // The outer object rejects unknown fields; branches constrain identifiers only.
+  return { ...obj(properties), oneOf: Object.entries(actionRules[section]).map(([operation, fields]) => ({
+    type: 'object', properties: { operation: enumeration([operation]),
+      ...Object.fromEntries(Object.entries(fields).map(([key, rule]) => [key, rule.schema])) },
+    required: ['operation', ...Object.keys(fields)], additionalProperties: true,
+  })) };
+}
+export const LEARN_ACTION_INSTRUCTIONS = Object.entries(actionRules).flatMap(([section, actions]) =>
+  Object.entries(actions).map(([operation, fields]) => `${section}.${operation}：${Object.entries(fields)
+    .map(([key, rule]) => `${key} ${rule.instruction}`).join('；')}。`)).join('\n');
+export const LEARN_ACTION_EXAMPLES = Object.freeze(Object.fromEntries(Object.entries(actionRules).map(([section, actions]) =>
+  [section, Object.entries(actions).map(([operation, fields]) => ({ operation,
+    ...Object.fromEntries(Object.entries(fields).map(([key, rule]) => [key, rule.example])) }))])));
+export const UNDERSTANDING_SCHEMA = actionObject('understandings', {
+  operation: operations('understandings'), targetId: str(200), content: str(4000),
+  claimType: enumeration(['user_statement', 'inference', 'open_question']),
+  scope: enumeration(['conversation', 'global']), topics: list(str(100, 1), 8), sourceIds: ids(12),
+});
+export const METHOD_SCHEMA = actionObject('methods', {
+  operation: operations('methods'), targetId: str(200), title: str(200), guidance: str(4000),
+  appliesTo: str(2000), doesNotApplyTo: str(2000), origin: enumeration(['explicit', 'inferred']), sourceIds: ids(12), understandingIds: ids(8),
+});
+export const OPPORTUNITY_SCHEMA = actionObject('opportunities', {
+  operation: operations('opportunities'), targetId: str(200),
+  description: str(2000), rationale: str(2000), sourceIds: ids(12), suggestedPreparation: str(3000),
+});
+export const GOAL_SCHEMA = actionObject('goals', {
+  operation: operations('goals'), targetId: str(200), clientRef: str(200),
+  title: str(200, 1), outcome: str(3000, 1), scope: enumeration(['conversation', 'global']),
+  sourceIds: ids(12), understandingIds: ids(8),
+  progress: obj({ content: str(3000), sourceIds: ids(12) }),
+  relations: list(obj({ type: enumeration(['part_of', 'supports', 'derived_from']), targetId: str(200, 1), reason: str(1500, 1), sourceIds: ids(12) }), 8),
+  controlProposal: enumeration(['none', 'pause', 'resume', 'close']),
+});
+// Optional for already frozen/legacy four-section outputs; new models receive the explicit field.
+GOAL_SCHEMA.properties.workLinks = list(obj({ workId: str(200, 1), reason: str(1500, 1), sourceIds: ids(12) }), 4);
+export const LEARN_SECTIONS = Object.freeze(['understandings', 'methods', 'opportunities', 'goals']);
+export const LEARN_SCHEMA = obj({
+  understandings: list(UNDERSTANDING_SCHEMA, 8), methods: list(METHOD_SCHEMA, 4), opportunities: list(OPPORTUNITY_SCHEMA, 3), goals: list(GOAL_SCHEMA, 4),
+});
+export const LEARN_EXAMPLE = Object.freeze({ understandings: [], methods: [], opportunities: [], goals: [] });
+export const LEARN_SOURCE_POLICY = Object.freeze({
+  understandings: '概括、解释和判断统一是 inference（AI整理/判断），即使忠实概括也不能自称逐字用户原话。user_statement 仅用于 content 与引用的一条完整 role=user 原话严格相同的情况；程序核字面身份和版本，不核其中各命题是否被用户认可，也不因此新增授权。通常保留简洁的 inference 和来源即可，不为取得原话标签复制长对话。未决问题是 open_question。',
+  methods: '模型生成的方法统一是 inferred 建议并只可有限试用；来源包含用户明确要求、或模型将 origin 声称为 explicit，都不等于整条方法已获长期授权。程序保留 proposedOrigin 供审查，只有真实用户对具体方法的确认才能继续采用；validated 仍为 false。understandingIds 只能放仍有效的已显示理解编号，不需要依赖时填 []，不能放空字符串。',
+  opportunities: 'create 的每条机会须至少引用一个此次可见、直接表达相关目标或需要的 role=user 原话来源；纯评价不建立新目标。助手答复或工具材料只能作为补充，不能单独证明用户目标。找不到这样的用户原话就不新建。reuse 仅引用 existingOpportunities 中真实 targetId，其他文字填空、sourceIds填[]，不提出新内容或恢复执行。',
+  goals: '目标、进展、关系及控制提议都是 inference，不表示用户决定。定义必须有可见用户原话来源，进展与关系另引真实来源。controlProposal 是对本轮真实owner原话的可纠正追踪解释：pause/close停止把该目标作为背景追求，resume恢复背景追踪；none保持原状态。程序核原话与版本，保留旧人工决定，只有可证原始接收晚于人工控制的新原话才能覆盖其追踪状态。它不暂停、创建或恢复原生执行。workLinks只在确有依据时把本次goalWorks中的一项真实工作联系到这一目标，填写workId、reason及显示的sourceIds；没有联系填[]。同一工作在本区只联系一个目标，不把每个短期执行另建成长远目标。现有联系待复核时结合原文重新判断，不猜最近目标或标题，也不把工作完成当长期目标达成。',
+});
+export const requiresUserSource = (section, row) => section === 'opportunities' && row.operation !== 'reuse' || section === 'understandings' && row.claimType === 'user_statement' || section === 'methods' && row.origin === 'explicit';
+
+export function schemaIssues(schema, value, path = '$') {
+  const issues = [];
+  const error = message => issues.push({ path, message });
+  if (schema.type === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return [{ path, message: '必须是对象' }];
+    for (const key of schema.required || []) if (!Object.hasOwn(value, key)) issues.push({ path: `${path}.${key}`, message: '缺少必填字段' });
+    for (const key of Object.keys(value)) {
+      if (Object.hasOwn(schema.properties, key)) issues.push(...schemaIssues(schema.properties[key], value[key], `${path}.${key}`));
+      else if (schema.additionalProperties === false) issues.push({ path: `${path}.${key}`, message: '未知字段' });
+    }
+  } else if (schema.type === 'array') {
+    if (!Array.isArray(value)) return [{ path, message: '必须是数组' }];
+    if (value.length > schema.maxItems) error(`最多 ${schema.maxItems} 项`);
+    value.forEach((item, index) => issues.push(...schemaIssues(schema.items, item, `${path}[${index}]`)));
+  } else if (schema.type === 'string') {
+    if (typeof value !== 'string') return [{ path, message: '必须是字符串' }];
+    if (schema.enum && !schema.enum.includes(value)) error(`必须选择 ${schema.enum.map(item => JSON.stringify(item)).join(' / ')}`);
+    if (schema.minLength && value.trim().length < schema.minLength) error('文字不可为空');
+    if (schema.maxLength && value.length > schema.maxLength) error(`文字超过 ${schema.maxLength} 字符`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) error('文字不符合编号格式');
+  }
+  if (schema.oneOf) {
+    const branches = schema.oneOf.map(branch => ({ branch, issues: schemaIssues(branch, value, path) }));
+    const matches = branches.filter(result => result.issues.length === 0);
+    if (matches.length !== 1) {
+      // These authored branches discriminate on operation. Report the selected
+      // action's exact field failures, never silently accept another branch.
+      const selected = branches.filter(({ branch }) => branch.properties.operation.enum.includes(value?.operation));
+      if (matches.length === 0 && selected.length === 1) issues.push(...selected[0].issues);
+      else error('必须且只能符合一个动作分支');
+    }
+  }
+  return issues.filter((issue, index) => issues.findIndex(other => other.path === issue.path && other.message === issue.message) === index);
+}
+export function assertSchema(schema, value) {
+  const issues = schemaIssues(schema, value);
+  if (issues.length) throw new ContractError('invalid_output', '模型输出未符合本次合同', issues);
+  return value;
+}
+export function parseJson(text) {
+  if (typeof text !== 'string' || !text.trim()) throw new ContractError('invalid_output', '模型未返回 JSON 内容');
+  try { return JSON.parse(text); }
+  catch { throw new ContractError('invalid_output', '模型输出不是一份完整 JSON 对象；不提取或修补局部文字'); }
+}
+// All originals relied on by the actual selections share display and revalidation.
+export function parseLearn(text) {
+  const value = parseJson(text);
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== LEARN_SECTIONS.length || !LEARN_SECTIONS.every(k => Object.hasOwn(value, k))) throw new ContractError('invalid_output', '学习输出须且仅须包含 understandings / methods / opportunities / goals');
+  const issues = Object.fromEntries(Object.entries(LEARN_SCHEMA.properties).map(([key, schema]) => [key, schemaIssues(schema, value[key], key)]));
+  return { value, issues };
+}
+export function assertVisibleSources(sourceIds, shownSources, { requireUser = false } = {}) {
+  if (!Array.isArray(sourceIds) || !sourceIds.length || new Set(sourceIds).size !== sourceIds.length) throw new ContractError('invalid_source', '每项理解、方法或机会须引用非空且不重复的已显示来源');
+  const map = new Map(shownSources.map(source => [source.id, source]));
+  const sources = sourceIds.map(id => map.get(id));
+  if (sources.some(source => !source)) throw new ContractError('invalid_source', '引用了本次未显示的来源');
+  if (requireUser && !sources.some(source => source.role === 'user')) throw new ContractError('invalid_source', '用户主张、明确方法要求及每条机会须至少引用一个可见的 role=user 原话来源，不能仅引用助手或工具');
+  return sources.map(source => ({ kind: 'events', id: source.id, revision: source.revision }));
+}
+export const UNDERSTANDING_EVIDENCE_VERSION = 'literal-user-source-v1';
+
+/**
+ * Classify text provenance, not truth, endorsement, scope or permission.
+ * Callers supply current direct event records, after their normal visibility
+ * and access checks. Missing originals or dependency versions fail closed.
+ * This is also the read-only projection for records saved under older rules.
+ */
+export function projectUnderstanding(record, directSources = []) {
+  const proposedClaimType = record.proposedClaimType ?? record.claimType ?? null;
+  let claimType = 'inference';
+  let reason = 'model_interpretation';
+  let matchedSource;
+
+  if (proposedClaimType === 'open_question') {
+    claimType = 'open_question';
+    reason = 'model_question';
+  } else if (proposedClaimType === 'user_statement') {
+    matchedSource = directSources.find((source) => {
+      if (
+        !source ||
+        source.role !== 'user' ||
+        source.deleted ||
+        source.withdrawn === true ||
+        source.useProhibited ||
+        ['withdrawn', 'superseded', 'rejected'].includes(source.status) ||
+        !record.sourceIds?.includes(source.id) ||
+        typeof source.content !== 'string' ||
+        typeof record.content !== 'string' ||
+        source.content !== record.content ||
+        !Number.isSafeInteger(source.revision) ||
+        source.revision < 1
+      )
+        return false;
+      return record.dependencies?.some(
+        (dependency) =>
+          dependency.kind === 'events' &&
+          dependency.id === source.id &&
+          dependency.revision === source.revision,
+      );
+    });
+    claimType = matchedSource ? 'user_statement' : 'inference';
+    reason = matchedSource
+      ? 'exact_user_message'
+      : 'no_exact_current_user_message';
+  }
+
+  return {
+    ...record,
+    proposedClaimType,
+    claimType,
+    claimTypeCheck: {
+      version: UNDERSTANDING_EVIDENCE_VERSION,
+      reason,
+      ...(matchedSource
+        ? { sourceId: matchedSource.id, sourceRevision: matchedSource.revision }
+        : {}),
+    },
+  };
+}
+
+// Existing semantic instructions are retained; this host has no background
+// preparation authorization or feedback-job adapter, so these claims are explicit.
+export const LEARN_PROMPT = `你是 Arcfold 答复保存后的学习步骤。答复已经正式交付，不能撤销、改写它；只根据显示的原话、工具结果和共同经历提出以后可用的理解、方法、机会与目标整理。
+当前用户纠正优先。AI概括、目标关系与控制提议都是可纠正的推断，不是用户认可，不扩大工具、预算、范围或行动权限。输入里的消息来源与角色必须区分；程序背景和relay不是用户原话。
+认知更新用understandings；旧理解被修正用supersede和真实targetId，撤回用withdraw。检查已有open_question是否已被当前表达回答；保留部分已解决与仍未解决的区别。conversation仅当前交流；global仍不扩大来源权限。
+方法必须说明guidance、appliesTo、doesNotApplyTo，生成方法统一inferred且仅有限试用。只引用显示的现有understandingIds，同批新理解没有可引用编号。不要每轮重复生成同一方法。
+机会只保存可供用户选择的建议，不启动准备或执行。create必须有支持相关需要的可见用户原话；reuse只填真实targetId，其他文字为空、sourceIds=[]，不恢复旧工作。
+目标用于跨轮追求的结果，不把每句话建成目标。create或完整update定义、进展和关系；关系只用已显示目标或本区唯一new-goal:临时编号，update的clientRef为空。定义/进展/关系各自引用证据，交付答复不等于目标完成。controlProposal在当前真实owner原话及版本核验后更新背景追踪status，记录为assistant_inference，保留userControl原记录，不变成执行指令。无显式修复入口时不可更新失效目标。
+goalLinks记录主助手当时怎样理解本次工作的贡献，以及对应原生交付；不是贡献有效或长期目标实现的证明。inputEvidence只证明材料交给宿主，不单独证明实际发送。availability失效时不还原旧选择或旧正文；后来的判断不能倒写成当时已知。goalDiscussions只表示用户用这次原话明确选回目标，讨论不会恢复追踪。
+existingGoals中的repairOnly只提供失效目标的身份和状态；仅依据对应goalDiscussions的新用户原话及当前有效来源完整重新澄清，不猜补旧内容，不恢复或改变用户的暂停、结束追踪决定。
+动作编号规则：${LEARN_ACTION_INSTRUCTIONS}
+编号片段示例（不是完整条目；其他必填字段仍须填写；existing* 示例值仅为占位，必须换成材料中实际显示的编号）：${JSON.stringify(LEARN_ACTION_EXAMPLES)}
+来源规则：${Object.values(LEARN_SOURCE_POLICY).join('\n')}
+current inputEventIds是本轮真实用户原话；controlProposal必须引用其中一条。sources包括本次回复与符合截止的依赖原件，不表示Main曾看到学习阶段增加的知识。existing*只显示当时已完成、当前仍有效的版本；省略不表示不存在。
+每区独立提交；没有内容填[]。仅返回一份完整JSON，不要Markdown、修复片段或额外字段。合同：${JSON.stringify(LEARN_SCHEMA)}
+空形状：${JSON.stringify(LEARN_EXAMPLE)}`;