@nextcommerce/campaigns-os 1.34.1 → 1.37.2

package/src/progress-node.mjs

@@ -0,0 +1,177 @@
+// Best-effort producer adapter. Sanitized immutable bytes are durable before delivery.
+import {randomBytes,createHash} from 'node:crypto';
+import {mkdirSync,readFileSync,writeFileSync,renameSync,rmSync,readdirSync,lstatSync} from 'node:fs';
+import {join,resolve,dirname} from 'node:path';
+import {PROGRESS_SCHEMA_VERSION,PROGRESS_STAGES,PROGRESS_STAGE_STATUSES,PROGRESS_CONTINUATIONS,PROGRESS_ACTION_IDS,PROGRESS_GATE_IDS,canonicalProgressJson,progressSnapshotId,verifyProgressSnapshot} from './progress.mjs';
+import {specMaterialHash} from './spec-identity.mjs';
+import {sameFile} from './fs-identity.mjs';
+import {resolveConsent,CANONICAL_REMIT_SCOPE,normalizeConsentScope,announceDefaultOnTelemetry} from './consent.mjs';
+import {boundedResponseText,isLoopbackHostname} from './remit.mjs';
+export const PROGRESS_OBSERVATION = Symbol('canonical progress observation');
+export const PROGRESS_ENDPOINT = '/api/progress';
+const accepted = (value,values,fallback='unknown')=>values.includes(value)?value:fallback;
+const hash = value=>typeof value==='string'&&/^(?:sha256:)?[0-9a-f]{64}$/i.test(value)?`sha256:${value.replace(/^sha256:/i,'').toLowerCase()}`:null;
+const id = value=>typeof value==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(value)?value:null;
+const digest = value=>`sha256:${createHash('sha256').update(value).digest('hex')}`;
+const read = path=>{try{return JSON.parse(readFileSync(path,'utf8'));}catch{return null;}};
+function atomic(path,value) {const tmp=`${path}.${randomBytes(8).toString('hex')}.tmp`;writeFileSync(tmp,`${canonicalProgressJson(value)}\n`,{mode:0o600});renameSync(tmp,path);}
+export function resolveProgressEndpoint(args,workspace,context) {
+  // A foreign context cannot donate a source endpoint or quietly fall back.
+  const named=context?.packet_path;
+  const bound=typeof named==='string'&&named.trim()&&sameFile(resolve(workspace.targetRepo,named),workspace.packetPath,{requireExisting:true});
+  const explicit=args['proxy-base'];
+  const source=context?.intake?.proxy_base;
+  if (!explicit && !bound && source) return {ok:false,reason:'source_binding_invalid'};
+  if (explicit===undefined && (source===null||source===undefined) && workspace.packet?.spec?.spec_url) {
+    try { if (new URL(workspace.packet.spec.spec_url).origin!==CANONICAL_REMIT_SCOPE) return {ok:false,reason:'source_binding_missing'}; } catch { return {ok:false,reason:'source_binding_invalid'}; }
+  }
+  const raw=explicit!==undefined?explicit:source!==null&&source!==undefined?source:CANONICAL_REMIT_SCOPE;
+  if (typeof raw!=='string'||!raw.trim()) return {ok:false,reason:'endpoint_invalid'};
+  try {
+    const url=new URL(raw);
+    if (url.username||url.password||url.search||url.hash||!['https:','http:'].includes(url.protocol)||(url.protocol==='http:'&&!isLoopbackHostname(url.hostname))) return {ok:false,reason:'endpoint_invalid'};
+    const base=url.href.replace(/\/+$/,'');
+    return {ok:true,base,scope:normalizeConsentScope(base)};
+  } catch {return {ok:false,reason:'endpoint_invalid'};}
+}
+export function projectProgressObservation({workspace,context,report,doctor,continuation,qaResult=null,packageVersion}) {
+  const packet=workspace.packet;
+  let spec=null;
+  try {spec=JSON.parse(readFileSync(resolve(dirname(workspace.packetPath),packet.spec.local_path),'utf8'));}catch{}
+  const mapId=id(packet?.spec?.map_id);
+  const localHash=spec?hash(specMaterialHash(spec)):null;
+  const localMapId=id(spec?.spec_identity?.map_id||spec?.map_id);
+  const baseline=context?.intake?.saved_map_revision;
+  const contextBound=typeof context?.packet_path==='string'&&context.packet_path.trim()&&sameFile(resolve(workspace.targetRepo,context.packet_path),workspace.packetPath,{requireExisting:true});
+  const aligned=contextBound&&mapId&&localMapId===mapId&&baseline?.map_id===mapId&&baseline?.algorithm==='map-store-v1'&&hash(baseline.hash)&&localHash&&localHash===hash(baseline.local_spec_material_hash);
+  const build=hash(doctor?.derived?.build_output_fingerprint?.value);
+  const recordedBuild=hash(report?.stages?.assembly?.build_fingerprint);
+  const reportBound=doctor?.derived?.prepare_build_gate?.binding_failure!==true&&contextBound&&mapId&&localMapId===mapId&&report?.identity?.map_id===mapId&&localHash&&localHash===hash(report?.identity?.spec_material_hash);
+  const qaSource=hash(report?.stages?.qa?.evidence?.source_build_fingerprint);
+  const verdict=qaResult?.verdict;
+  const qa=verdict?{
+    verdict_id:id(verdict.run_id),disposition:accepted(verdict.disposition,['ready','ready_with_exceptions','blocked']),
+    binding:reportBound&&id(verdict.run_id)&&id(verdict.run_id)===id(report?.stages?.qa?.verdict_run_id)&&build&&qaSource===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'&&hash(verdict.spec_hash)===localHash?'matching':'unconfirmed',
+    publish_state:accepted(qaResult?.qa_verdict_publish?.state,['skipped','ok','failed']),
+  }:null;
+  const gates=(Array.isArray(continuation?.gates)?continuation.gates:[]).slice(0,16).map(gate=>({id:accepted(gate?.id,PROGRESS_GATE_IDS),state:PROGRESS_GATE_IDS.includes(gate?.id)?accepted(gate?.status,['pass','blocked','waived','not_applicable']):'unknown'}));
+  const actions=[...new Set((Array.isArray(continuation?.next_actions)?continuation.next_actions:[]).slice(0,64).map(action=>accepted(action?.id,PROGRESS_ACTION_IDS)))];
+  const stage=accepted(continuation?.stage,PROGRESS_CONTINUATIONS);
+  const preview=typeof packet?.deploy?.preview_url==='string'&&packet.deploy.preview_url?packet.deploy.preview_url:null;
+  return {
+    schema_version:PROGRESS_SCHEMA_VERSION,package_version:packageVersion,producer:qaResult?'qa':'next',
+    identity:{map_id:mapId,map_revision_hash:contextBound&&baseline?.map_id===mapId?hash(baseline?.hash):(localMapId===mapId?hash(spec?.spec_identity?.spec_hash||spec?.spec_hash):null),map_revision_algorithm:'map-store-v1',saved_revision_alignment:aligned?'aligned':'unconfirmed',local_spec_material_hash:localHash,local_spec_material_algorithm:'campaign-spec-material-v1',build_fingerprint:build,build_fingerprint_algorithm:'sha256-manifest/v1'},
+    stages:PROGRESS_STAGES.map(stage=>{
+      const status=reportBound?accepted(report?.stages?.[stage]?.status,PROGRESS_STAGE_STATUSES):'unknown';
+      const source=stage==='assembly'?recordedBuild:stage==='qa'?qaSource:null;
+      return {stage,status,source_build_fingerprint:source,build_binding:reportBound&&build&&source===build&&doctor?.derived?.build_output_fingerprint?.status==='pass'?'matching':'unconfirmed'};
+    }),
+    preview:{present:Boolean(preview),url_hash:preview?digest(preview):null},
+    continuation:{stage,blocked:continuation?.ok!==true||(Array.isArray(continuation?.divergences)&&continuation.divergences.length>0)||stage==='unknown'||gates.some(gate=>['blocked','unknown'].includes(gate.state))||actions.includes('unknown'),divergent:Array.isArray(continuation?.divergences)&&continuation.divergences.length>0,action_ids:actions,gates},qa,
+  };
+}
+async function lock(dir,fn,{budgetMs=1500}={}) {
+  const path=join(dir,'.allocation-lock'); const start=Date.now();const token=randomBytes(16).toString('hex');
+  const abandoned=(unownedMtime=null)=>{
+    try {
+      const stat=lstatSync(path);if(!stat.isDirectory()||stat.isSymbolicLink())return false;
+      const owner=read(join(path,'owner.json'));
+      if(Number.isInteger(owner?.pid)&&owner.pid>0&&typeof owner.token==='string') {
+        try {process.kill(owner.pid,0);return false;}catch(error){return error.code==='ESRCH';}
+      }
+      // A killed process can leave the directory before writing its owner.
+      // Give a live allocator ample time to finish that tiny synchronous gap.
+      return Date.now()-(unownedMtime??stat.mtimeMs)>10000;
+    }catch{return false;}
+  };
+  const recover=()=>{
+    if(!abandoned())return;
+    let originalMtime;try{originalMtime=lstatSync(path).mtimeMs;}catch{return;}
+    const claim=join(path,'.recovery');
+    // Only this exclusive claimant can rename the old lock. An interrupted
+    // recovery claim fails closed for explicit offline recovery; recursively
+    // stealing recovery claims would reintroduce a check/rename race.
+    try {mkdirSync(claim);atomic(join(claim,'owner.json'),{pid:process.pid,token});}catch{return;}
+    let moved=false;
+    try {
+      if(!abandoned(originalMtime))return;
+      const tomb=`${path}.abandoned-${token}`;
+      renameSync(path,tomb);moved=true;rmSync(tomb,{recursive:true,force:true});
+    }catch{}finally{if(!moved&&read(join(claim,'owner.json'))?.token===token){try{rmSync(claim,{recursive:true,force:true});}catch{}}}
+  };
+  while (true) {
+    try {mkdirSync(path);atomic(join(path,'owner.json'),{pid:process.pid,token});break;}catch(error){if(error.code!=='EEXIST'||Date.now()-start>=budgetMs)throw new Error('progress.lock_unavailable');recover();await new Promise(resolve=>setTimeout(resolve,20));}
+  }
+  try{return await fn();}finally{if(read(join(path,'owner.json'))?.token===token)rmSync(path,{recursive:true,force:true});}
+}
+export async function persistProgressObservation(observation,{dir,now=()=>new Date(),historyLimit=32}={}) {
+  mkdirSync(dir,{recursive:true,mode:0o700});
+  return lock(dir,async()=>{
+    const latest=read(join(dir,'latest.json'));
+    const latestValid=latest&&(await verifyProgressSnapshot(latest)).ok;
+    const observationHash=digest(canonicalProgressJson(observation));
+    if (latestValid) {
+      const {snapshot_id,stream_id,sequence,previous_snapshot_id,observed_at,...old}=latest;
+      if (digest(canonicalProgressJson(old))===observationHash) return {snapshot:latest,reused:true};
+    }
+    // A new spec/build identity starts an independent history; stage completion
+    // from the old output cannot become completion for the new output.
+    const sameIdentity=latestValid&&canonicalProgressJson(latest.identity)===canonicalProgressJson(observation.identity);
+    const snapshot={...observation,stream_id:sameIdentity?latest.stream_id:`progress_${randomBytes(16).toString('hex')}`,sequence:sameIdentity?latest.sequence+1:1,previous_snapshot_id:sameIdentity?latest.snapshot_id:null,observed_at:now().toISOString()};
+    snapshot.snapshot_id=await progressSnapshotId(snapshot);
+    if (!(await verifyProgressSnapshot(snapshot)).ok) throw new Error('progress.invalid_projection');
+    atomic(join(dir,`${snapshot.snapshot_id.slice(7)}.snapshot.json`),snapshot);
+    atomic(join(dir,'latest.json'),snapshot);
+    const history=readdirSync(dir).filter(name=>/^[0-9a-f]{64}\.snapshot\.json$/.test(name)).map(name=>({name,at:read(join(dir,name))?.observed_at||''})).sort((a,b)=>a.name===`${snapshot.snapshot_id.slice(7)}.snapshot.json`?-1:b.name===`${snapshot.snapshot_id.slice(7)}.snapshot.json`?1:b.at.localeCompare(a.at)||b.name.localeCompare(a.name));
+    const limit=Math.min(32,Math.max(1,historyLimit));
+    for (const old of history.slice(limit)) if(old.name!==`${snapshot.snapshot_id.slice(7)}.snapshot.json`) {rmSync(join(dir,old.name),{force:true});rmSync(join(dir,old.name.replace('.snapshot.json','.remit.json')),{force:true});}
+    return {snapshot,reused:false};
+  });
+}
+export async function remitProgressSnapshot(snapshot,{base,campaignKey,fetchImpl=globalThis.fetch,budgetMs=2000}={}) {
+  const bytes=canonicalProgressJson(snapshot);const deadline=Date.now()+Math.min(2000,Math.max(1,budgetMs));
+  let reason='transport_failed';let attempts=0;let httpStatus=null;
+  for (let attempt=0;attempt<2&&Date.now()<deadline;attempt++) {
+    attempts++;
+    try {
+      const response=await fetchImpl(`${base}${PROGRESS_ENDPOINT}`,{method:'POST',redirect:'error',headers:{'Content-Type':'application/json','Accept':'application/json','X-Campaign-Key':campaignKey},body:bytes,signal:AbortSignal.timeout(Math.max(1,deadline-Date.now()))});
+      httpStatus=response.status;
+      let ack=null;try{ack=JSON.parse(await boundedResponseText(response,{maxBodyBytes:4096,timeoutMs:Math.max(1,deadline-Date.now())}));}catch{}
+      if ((response.ok||response.status===409)&&ack?.ok===true&&ack.snapshot_id===snapshot.snapshot_id&&ack.digest===snapshot.snapshot_id) return {state:'ok',reason:'acknowledged',attempts,http_status:httpStatus};
+      reason=response.status===409?'conflict':response.ok?'ack_invalid':'http_refused';
+      if (!(response.status===429||response.status>=500)) break;
+    } catch {reason='transport_failed';}
+  }
+  return {state:'failed',reason,attempts,http_status:httpStatus};
+}
+export async function observeProgress(args,continuation,{qaResult=null,packageVersion,resolveKey,env=process.env,configPath,fetchImpl,warn=message=>process.stderr.write(`${message}\n`)}={}) {
+  if (args['no-write']===true) return {state:'disabled',reason:'no_write'};
+  try {
+    const source=continuation?.[PROGRESS_OBSERVATION];
+    if (!source) return {state:'skipped',reason:'observation_unavailable'};
+    const {workspace,context}=source;
+    const endpoint=resolveProgressEndpoint(args,workspace,context);
+    const observation=projectProgressObservation({...source,continuation,qaResult,packageVersion});
+    const storageScope=digest(canonicalProgressJson({packet:workspace.packetPath,context:workspace.contextPath,report:workspace.reportPath,endpoint:endpoint.ok?endpoint.scope:null})).slice(7);
+    const dir=join(workspace.targetRepo,'.campaign-runtime','progress',storageScope);
+    const {snapshot,reused}=await persistProgressObservation(observation,{dir});
+    const metaPath=join(dir,`${snapshot.snapshot_id.slice(7)}.remit.json`);
+    const prior=read(metaPath);
+    if (prior?.state==='ok') return {state:'ok',reason:'already_acknowledged',snapshot_id:snapshot.snapshot_id,reused};
+    let reason=!snapshot.identity.map_id?'map_id_missing':!endpoint.ok?endpoint.reason:args['no-remit']===true?'no_remit':null;
+    const consent=reason?null:resolveConsent({env,...(configPath?{configPath}:{}),proxyBase:endpoint.base,warn:()=>{}});
+    if (!reason&&consent.state!=='on') reason='consent_off';
+    if (!reason&&consent.scope_bypassed) reason='scoped_consent_required';
+    const key=reason?null:resolveKey?.(workspace.packet,workspace.packetPath,env)?.key;
+    if (!reason&&!key) reason='campaign_key_missing';
+    if (!reason) announceDefaultOnTelemetry(`${endpoint.base}${PROGRESS_ENDPOINT}`);
+    const remit=reason?{state:'skipped',reason,attempts:0,http_status:null}:await remitProgressSnapshot(snapshot,{base:endpoint.base,campaignKey:key,fetchImpl});
+    atomic(metaPath,{...remit,snapshot_id:snapshot.snapshot_id});
+    if(remit.state==='failed')warn('[campaigns-os] Progress delivery pending; the local observation is retained. Lifecycle result is unchanged.');
+    return {...remit,snapshot_id:snapshot.snapshot_id,reused};
+  } catch(error) {
+    if(error?.message==='progress.lock_unavailable')warn('[campaigns-os] Progress allocation lock occupied; wait for the current writer. For abandoned or interrupted recovery, stop target writers and follow the offline lock recovery in docs/progress-snapshots.md. Lifecycle result is unchanged.');
+    else warn('[campaigns-os] Progress observation unavailable; lifecycle result is unchanged.');
+    return {state:'failed',reason:'capture_unavailable'};
+  }
+}

package/src/progress.mjs

@@ -0,0 +1,133 @@
+// Portable wire contract. No filesystem, network, Node globals or lifecycle picker.
+export const PROGRESS_SCHEMA_VERSION = 'campaigns-os-progress-snapshot/v0';
+export const PROGRESS_STAGES = ['prepare_build', 'setup', 'assembly', 'polish', 'deploy', 'qa'];
+export const PROGRESS_CONTINUATIONS = ['prepare-build', 'doctor-blocked', 'setup', 'build', 'polish', 'deploy', 'qa', 'done', 'unknown'];
+export const PROGRESS_STAGE_STATUSES = ['pending', 'required', 'blocked', 'completed', 'completed_with_warnings', 'skipped', 'unknown'];
+export const PROGRESS_GATE_IDS = ['doctor', 'prepare_build', 'theme_gate', 'polish_gate', 'page_kit.sdk_version', 'page_kit.store_profile', 'built_output.upsell_selector_scope', 'polish.hidden_eager_media', 'unknown'];
+export const PROGRESS_ACTION_IDS = [
+  'doctor_recheck', 'restore_prepare_build_binding', 'recheck', 'rerun_prepare_build',
+  'divergence_inspect', 'setup_skill', 'build_skill', 'build_local_proof', 'build_production_parity',
+  'polish_skill', 'deploy', 'advance', 'install_browser', 'qa_run', 'run_end', 'run_record_present',
+  'run_record_remit_recovery', 'run_record_closeout', 'purchase_proof_unknown',
+  'theme_gate.starter_palette_blocks_qa', 'theme_gate.brand_contract_unreadable',
+  'theme_gate.theme_generate', 'theme_gate.apply_brand_layer', 'theme_gate.waive_theme', 'theme_gate.fix_load_order',
+  'polish_gate.rerun_build', 'polish_gate.run_polish', 'polish_gate.repair_waiver',
+  'checkpoint.page_kit.sdk_version.repair_spec', 'checkpoint.page_kit.sdk_version.refresh_spec',
+  'checkpoint.page_kit.store_profile.repair_spec', 'checkpoint.built_output.upsell_selector_scope.repair_selectors',
+  ...['page_kit.sdk_version', 'page_kit.store_profile', 'built_output.upsell_selector_scope'].flatMap(id => ['repair_target', 'align_store_profile', 'align_sdk_version', 'repair_waiver', 'waive'].map(action => `checkpoint.${id}.${action}`)),
+  ...['capture', 'install_browser', 'repair', 'repair_authority', 'local_proof_rebuild', 'waive'].map(action => `checkpoint.polish.hidden_eager_media.${action}`),
+  'unknown',
+];
+const str = pattern => ({type:'string', pattern});
+const hash = {type:['string','null'], pattern:'^sha256:[0-9a-f]{64}$'};
+const opaque = {type:['string','null'], pattern:'^[A-Za-z0-9_-]{1,64}$'};
+const enumeration = values => ({enum:values});
+const object = properties => ({type:'object', additionalProperties:false, required:Object.keys(properties), properties});
+export const PROGRESS_SNAPSHOT_SCHEMA = {
+  $schema:'https://json-schema.org/draft/2020-12/schema',
+  $id:'https://nextcommerce.com/schemas/campaigns-os-progress-snapshot.v0.schema.json',
+  title:'Campaigns OS minimal progress observation v0',
+  ...object({
+    schema_version:{const:PROGRESS_SCHEMA_VERSION}, snapshot_id:str('^sha256:[0-9a-f]{64}$'),
+    stream_id:str('^progress_[0-9a-f]{32}$'), sequence:{type:'integer',minimum:1,maximum:2147483647},
+    previous_snapshot_id:hash, observed_at:str('^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$'),
+    package_version:str('^\\d{1,6}\\.\\d{1,6}\\.\\d{1,6}$'), producer:enumeration(['next','qa']),
+    identity:object({map_id:opaque,map_revision_hash:hash,map_revision_algorithm:{const:'map-store-v1'},
+      saved_revision_alignment:enumeration(['aligned','unconfirmed']),local_spec_material_hash:hash,
+      local_spec_material_algorithm:{const:'campaign-spec-material-v1'},build_fingerprint:hash,
+      build_fingerprint_algorithm:{const:'sha256-manifest/v1'}}),
+    stages:{type:'array',minItems:6,maxItems:6,items:object({stage:enumeration(PROGRESS_STAGES),status:enumeration(PROGRESS_STAGE_STATUSES),
+      build_binding:enumeration(['matching','unconfirmed']),source_build_fingerprint:hash})},
+    preview:object({present:{type:'boolean'},url_hash:hash}),
+    continuation:object({stage:enumeration(PROGRESS_CONTINUATIONS),blocked:{type:'boolean'},divergent:{type:'boolean'},
+      action_ids:{type:'array',maxItems:64,uniqueItems:true,items:enumeration(PROGRESS_ACTION_IDS)},
+      gates:{type:'array',maxItems:16,items:object({id:enumeration(PROGRESS_GATE_IDS),state:enumeration(['pass','blocked','waived','not_applicable','unknown'])})}}),
+    qa:{anyOf:[{type:'null'},object({verdict_id:opaque,disposition:enumeration(['ready','ready_with_exceptions','blocked','unknown']),
+      binding:enumeration(['matching','unconfirmed']),publish_state:enumeration(['skipped','ok','failed','unknown'])})]},
+  }),
+};
+export function canonicalProgressJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalProgressJson).join(',')}]`;
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonicalProgressJson(value[key])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+export async function progressDigest(value, cryptoImpl = globalThis.crypto) {
+  const bytes = new TextEncoder().encode(canonicalProgressJson(value));
+  const digest = await cryptoImpl.subtle.digest('SHA-256',bytes);
+  return `sha256:${Array.from(new Uint8Array(digest),byte=>byte.toString(16).padStart(2,'0')).join('')}`;
+}
+export async function progressSnapshotId(snapshot, cryptoImpl) {
+  const {snapshot_id:ignored,...content} = snapshot;
+  return progressDigest(content,cryptoImpl);
+}
+// Small bounded validator for exactly the schema vocabulary above. Fixed error codes,
+// never values or property names from an untrusted payload.
+export function validateProgressSnapshot(value) {
+  const errors = [];
+  let count = 0;
+  function check(data,schema,depth=0) {
+    if (++count>2048 || depth>12) return false;
+    if (schema.anyOf) return schema.anyOf.some(branch=>check(data,branch,depth+1));
+    if (Object.hasOwn(schema,'const') && data!==schema.const) return false;
+    if (schema.enum && !schema.enum.includes(data)) return false;
+    if (schema.type) {
+      const type = data===null?'null':Array.isArray(data)?'array':typeof data==='number'&&Number.isInteger(data)?'integer':typeof data;
+      const allowed = Array.isArray(schema.type)?schema.type:[schema.type];
+      if (!allowed.includes(type)) return false;
+    }
+    if (typeof data==='string' && schema.pattern && !new RegExp(schema.pattern).test(data)) return false;
+    if (typeof data==='number' && (data<schema.minimum||data>schema.maximum)) return false;
+    if (Array.isArray(data)) {
+      if (data.length<(schema.minItems||0)||data.length>(schema.maxItems||0)) return false;
+      if (Object.keys(data).length!==data.length) return false;
+      if (schema.uniqueItems && new Set(data).size!==data.length) return false;
+      return data.every(item=>check(item,schema.items,depth+1));
+    }
+    if (data && typeof data==='object') {
+      if (!schema.properties || Object.keys(data).some(key=>!Object.hasOwn(schema.properties,key))) return false;
+      if (schema.required.some(key=>!Object.hasOwn(data,key))) return false;
+      return Object.entries(data).every(([key,item])=>check(item,schema.properties[key],depth+1));
+    }
+    return true;
+  }
+  if (!check(value,PROGRESS_SNAPSHOT_SCHEMA)) errors.push('progress.invalid_shape');
+  if (!errors.length && (new Set(value.stages.map(stage=>stage.stage)).size!==6 || value.stages.some((stage,index)=>stage.stage!==PROGRESS_STAGES[index]))) errors.push('progress.invalid_stages');
+  if (!errors.length && value.identity.saved_revision_alignment==='aligned' && (!value.identity.map_id||!value.identity.map_revision_hash||!value.identity.local_spec_material_hash)) errors.push('progress.invalid_alignment');
+  if (!errors.length && value.continuation.gates.some(gate=>gate.id==='unknown'&&gate.state!=='unknown')) errors.push('progress.unsupported_authority');
+  if (!errors.length && value.sequence===1 && value.previous_snapshot_id!==null) errors.push('progress.invalid_chain');
+  if (!errors.length && value.sequence>1 && value.previous_snapshot_id===null) errors.push('progress.invalid_chain');
+  if (!errors.length && value.stages.some(stage=>stage.build_binding==='matching'&&(!value.identity.build_fingerprint||stage.source_build_fingerprint!==value.identity.build_fingerprint))) errors.push('progress.invalid_build_binding');
+  if (!errors.length && value.qa?.binding==='matching'&&(!value.qa.verdict_id||!value.identity.build_fingerprint||value.stages.find(stage=>stage.stage==='qa').build_binding!=='matching')) errors.push('progress.invalid_qa_binding');
+  if (!errors.length && (value.continuation.stage==='unknown'||value.continuation.action_ids.includes('unknown')||value.continuation.gates.some(gate=>gate.id==='unknown'||gate.state==='unknown'))&&!value.continuation.blocked) errors.push('progress.unsupported_authority');
+  if (!errors.length && value.preview.present!==(value.preview.url_hash!==null)) errors.push('progress.invalid_preview');
+  if (!errors.length && value.continuation.divergent&&!value.continuation.blocked) errors.push('progress.invalid_divergence');
+  if (!errors.length && !Number.isFinite(Date.parse(value.observed_at))) errors.push('progress.invalid_time');
+  return {ok:errors.length===0,errors};
+}
+export async function verifyProgressSnapshot(snapshot,cryptoImpl) {
+  const checked=validateProgressSnapshot(snapshot);
+  if (!checked.ok) return checked;
+  return (await progressSnapshotId(snapshot,cryptoImpl))===snapshot.snapshot_id?checked:{ok:false,errors:['progress.digest_mismatch']};
+}
+// Identity groups include build, local spec and saved revision; never merge stages
+// across builds. Histories contain whole observations, not a readiness decision.
+export async function groupProgressHistories(snapshots,{cryptoImpl,maxSnapshots=256}={}) {
+  if (!Array.isArray(snapshots)||snapshots.length>Math.min(maxSnapshots,256)) return {ok:false,groups:[],errors:['progress.history_bound']};
+  const groups=new Map(); let rejected=0;
+  for (const snapshot of snapshots) {
+    if (!(await verifyProgressSnapshot(snapshot,cryptoImpl)).ok) {rejected++;continue;}
+    const key=canonicalProgressJson({identity:snapshot.identity,stream_id:snapshot.stream_id});
+    if (!groups.has(key)) groups.set(key,[]);
+    groups.get(key).push(snapshot);
+  }
+  return {ok:rejected===0,errors:rejected?['progress.invalid_history_member']:[],groups:[...groups.values()].map(items=>{
+    const unique=[...new Map(items.map(item=>[item.snapshot_id,item])).values()].sort((a,b)=>a.sequence-b.sequence);
+    const conflicted=new Set(unique.map(item=>item.sequence)).size!==unique.length;
+    const incomplete=unique[0].sequence!==1 || unique.some((item,index)=>index>0&&(item.sequence!==unique[index-1].sequence+1||item.previous_snapshot_id!==unique[index-1].snapshot_id));
+    return {identity:unique[0].identity,stream_id:unique[0].stream_id,state:conflicted?'conflicted':incomplete?'incomplete':unique[0].identity.saved_revision_alignment!=='aligned'||!unique[0].identity.build_fingerprint?'unconfirmed':'observed',snapshots:unique};
+  })};
+}
+export function progressStorageKey(snapshot,scopeHash) {
+  if (!validateProgressSnapshot(snapshot).ok||!/^sha256:[0-9a-f]{64}$/.test(scopeHash)||!snapshot.identity.map_id||!snapshot.identity.map_revision_hash) return null;
+  return `progress:v0:${scopeHash.slice(7)}:${snapshot.identity.map_id}:${snapshot.identity.map_revision_hash.slice(7)}:${snapshot.stream_id}:${snapshot.sequence}:${snapshot.snapshot_id.slice(7)}`;
+}