@smartmemory/compose 0.4.1 → 0.5.1

package/lib/consumer-fanout.js

@@ -21,6 +21,8 @@ import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
+import { normalizeOwnedPath, profilesDigest as digestJson } from './pipeline-profiles.js';
+import { worktreeBaseFor, readCheckpointRef, prepareCheckpoint, publishCheckpoint, reconcileCheckpoint, WaveCheckpointError } from './wave-checkpoint.js';
 
 const JOURNAL_VERSION = 1;
 let tempIndexSequence = 0;
@@ -96,7 +98,7 @@ function canonicalPath(path) {
   return resolve(existing, ...missing);
 }
 
-function withTemporaryIndex(cwd, fn) {
+export function withTemporaryIndex(cwd, fn) {
   const indexPath = join(
     tmpdir(),
     `compose-consumer-index-${process.pid}-${tempIndexSequence++}-${randomUUID()}`,
@@ -143,6 +145,56 @@ function cumulativeDiff(cwd, baseCommit) {
   });
 }
 
+/** Enumerate the exact retained patch, never the worker's reported files_changed. */
+function retainedPatchEvidence(cwd, baseCommit, diff) {
+  return withTemporaryIndex(cwd, env => {
+    git(cwd, ['read-tree', baseCommit], { env });
+    if (diff) git(cwd, ['apply', '--cached', '--binary', '-'], { env, input: diff });
+    const capturedTree = git(cwd, ['write-tree'], { env });
+    // --no-renames gives delete/add endpoints; -z preserves whitespace and newlines.
+    const changedPaths = git(cwd, ['diff', '--cached', '--name-only', '-z', '--no-renames', baseCommit, '--'],
+      { env, trim: false }).split('\0').filter(Boolean);
+    return { baseCommit, capturedTree, changedPaths };
+  });
+}
+function checkOwnership(cwd, entry, { capture = false } = {}) {
+  if (!entry.ownership && !Object.hasOwn(entry.itemBinding?.item ?? {}, 'files_owned')) return null;
+  let allowedFiles = [];
+  let evidence;
+  let code = 'FILES_OWNED_VIOLATION';
+  let files = [];
+  try {
+    if (!entry.itemBinding || entry.itemBinding.itemDigest !== digestJson(entry.itemBinding.item)) {
+      code = 'OWNERSHIP_EVIDENCE_MISMATCH'; throw new Error('Item binding missing or digest differs');
+    }
+    const owned = entry.itemBinding?.item?.files_owned;
+    if (!Array.isArray(owned)) throw new Error('files_owned must be an array');
+    allowedFiles = owned.map(normalizeOwnedPath);
+    if (typeof entry.diff !== 'string' || entry.diffDigest !== sha256(entry.diff) || !entry.ownership?.baseCommit) {
+      code = 'OWNERSHIP_EVIDENCE_MISMATCH';
+      throw new Error('Retained patch/base/digest missing or changed');
+    }
+    evidence = retainedPatchEvidence(cwd, entry.ownership.baseCommit, entry.diff);
+    if (!capture && (evidence.capturedTree !== entry.ownership.capturedTree
+      || digestJson(evidence.changedPaths) !== digestJson(entry.ownership.changedPaths))) {
+      code = 'OWNERSHIP_EVIDENCE_MISMATCH';
+      throw new Error('Retained patch tree/paths differ from capture');
+    }
+    files = evidence.changedPaths.filter(file => !allowedFiles.includes(file));
+    if (!files.length) { if (capture) entry.ownership = evidence; return null; }
+  } catch (error) {
+    if (code !== 'FILES_OWNED_VIOLATION' || evidence === undefined && allowedFiles.length) code = 'OWNERSHIP_EVIDENCE_MISMATCH';
+    files = evidence?.changedPaths ?? [];
+    return { code, taskId: entry.itemBinding?.item?.id, stepId: entry.scopedId, itemIndex: entry.itemIndex,
+      generation: entry.generation, dispatchToken: entry.dispatchToken, severity: 'error', files, allowedFiles,
+      diffDigest: entry.diffDigest, message: error.message };
+  }
+  if (capture) entry.ownership = evidence;
+  return { code, taskId: entry.itemBinding?.item?.id, stepId: entry.scopedId, itemIndex: entry.itemIndex,
+    generation: entry.generation, dispatchToken: entry.dispatchToken, severity: 'error', files, allowedFiles,
+    diffDigest: entry.diffDigest, message: `Task ${entry.itemBinding?.item?.id ?? entry.scopedId} changed unowned paths: ${files.join(', ')}` };
+}
+
 /**
  * Apply one lane's cumulative diff to a temporary index.
  *
@@ -286,8 +338,16 @@ export class ConsumerMergeDecisionError extends ConsumerArtifactError {
   }
 }
 
+/** Cancellation must never enter the merge-repair/revise decision channel. */
+export class MergeAfterCancelError extends ConsumerArtifactError {
+  constructor(message) {
+    super('MERGE_AFTER_CANCEL', message);
+    this.name = 'MergeAfterCancelError';
+  }
+}
+
 export class ConsumerFanoutArtifacts {
-  constructor({ runId, targetCwd, artifactRoot, hooks = {}, revisionDigest, specDigest }) {
+  constructor({ runId, targetCwd, artifactRoot, hooks = {}, revisionDigest, specDigest, profilesDigest }) {
     this.runId = runId;
     this.targetCwd = canonicalPath(targetCwd);
     this.artifactRoot = canonicalPath(artifactRoot ?? defaultArtifactRoot(this.targetCwd));
@@ -303,6 +363,7 @@ export class ConsumerFanoutArtifacts {
     // a crash between journal creation and the first bind cannot leave an
     // unpinned journal that a drifted spec could later re-pin as the truth.
     this._initialRevisionDigest = typeof revisionDigest === 'string' && revisionDigest.length > 0 ? revisionDigest : null;
+    this._initialProfilesDigest = profilesDigest;
     this._initialSpecDigest = typeof specDigest === 'string' && specDigest.length > 0 ? specDigest : null;
     this.runRoot = join(this.artifactRoot, runDirectoryName(runId));
     this.journalPath = join(this.runRoot, 'journal.json');
@@ -411,6 +472,15 @@ export class ConsumerFanoutArtifacts {
         );
       }
     }
+    if (this._initialProfilesDigest !== undefined) {
+      if (journal.profilesDigest !== undefined && journal.profilesDigest !== this._initialProfilesDigest) {
+        throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Consumer profiles changed');
+      }
+      if (journal.profilesDigest === undefined && (journal.issuances.length || journal.wave)) {
+        throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Cannot add profiles to an active legacy run');
+      }
+      journal.profilesDigest = this._initialProfilesDigest;
+    }
     return journal;
   }
 
@@ -418,6 +488,7 @@ export class ConsumerFanoutArtifacts {
     if (!existsSync(this.journalPath)) {
       const journal = {
         version: JOURNAL_VERSION,
+        ...(this._initialProfilesDigest !== undefined ? { profilesDigest: this._initialProfilesDigest } : {}),
         runId: this.runId,
         targetCwd: this.targetCwd,
         createdAt: now(),
@@ -444,7 +515,8 @@ export class ConsumerFanoutArtifacts {
     const before = readFileSync(this.journalPath, 'utf8');
     const journal = this.#reload();
     if ((this._initialRevisionDigest && journal.revisionDigest !== JSON.parse(before).revisionDigest)
-      || (this._initialSpecDigest && journal.specDigest !== JSON.parse(before).specDigest)) {
+      || (this._initialSpecDigest && journal.specDigest !== JSON.parse(before).specDigest)
+      || (this._initialProfilesDigest !== undefined && journal.profilesDigest !== JSON.parse(before).profilesDigest)) {
       this.#writeGuarded(journal);
     }
     return journal;
@@ -531,7 +603,10 @@ export class ConsumerFanoutArtifacts {
       itemIndex: descriptor.itemIndex,
       generation: descriptor.generation,
       path,
-      baseCommit: git(this.targetCwd, ['rev-parse', 'HEAD']),
+      baseCommit: this.journal.wave
+        ? (this.journal.waveAdmissions?.find(a => a.fanoutStepId === descriptor.step && a.epoch === (this.journal.dispatchBindings?.[descriptor.dispatchToken]?.itemBinding.epoch ?? descriptor.epoch))?.baseCommit
+          ?? worktreeBaseFor({ journal: this.journal, ref: readCheckpointRef({ cwd: this.targetCwd, ref: this.journal.wave.ref }) }))
+        : git(this.targetCwd, ['rev-parse', 'HEAD']),
       status: 'creating',
       superseded: false,
       createdAt: now(),
@@ -562,8 +637,15 @@ export class ConsumerFanoutArtifacts {
    * First-write-wins; a later issuance carrying a DIFFERENT engine revision digest
    * is a mid-run revision the journal must reject rather than silently absorb.
    */
-  bindRunRevision({ revisionDigest, specDigest }) {
+  bindRunRevision({ revisionDigest, specDigest, profilesDigest }) {
     return this.#mutate(() => {
+      if (profilesDigest !== undefined) {
+        if (this.journal.profilesDigest !== undefined && this.journal.profilesDigest !== profilesDigest
+          || this.journal.profilesDigest === undefined && (this.journal.issuances.length || this.journal.wave)) {
+          throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Consumer profiles changed');
+        }
+        this.journal.profilesDigest = profilesDigest;
+      }
       if (typeof revisionDigest === 'string' && revisionDigest.length > 0) {
         if (this.journal.revisionDigest === null) {
           this.journal.revisionDigest = revisionDigest;
@@ -582,6 +664,236 @@ export class ConsumerFanoutArtifacts {
     });
   }
 
+  /** Additive v1 seam records: absent until explicitly enabled. */
+  recordWaveAdmission(admission) {
+    return this.#mutate(() => {
+      if (!Array.isArray(admission.items) || !admission.inputDigest || !admission.baseCommit) {
+        throw new ConsumerArtifactError('WAVE_INPUT_INVALID', 'Admission needs full items, digest and pinned base');
+      }
+      if (this.journal.wave && !this.journal.waveAdmissions?.some(a => a.fanoutStepId === admission.fanoutStepId && a.epoch === admission.epoch)) {
+        const base = worktreeBaseFor({ journal: this.journal, ref: readCheckpointRef({ cwd: this.targetCwd, ref: this.journal.wave.ref }) });
+        if (base !== admission.baseCommit) throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Admission base differs from published tip');
+      }
+      this.journal.waveAdmissions ??= [];
+      const previous = this.journal.waveAdmissions.find(a => a.fanoutStepId === admission.fanoutStepId && a.epoch === admission.epoch);
+      if (previous) {
+        if (digestJson({ ...previous, validatedAt: null }) !== digestJson({ ...admission, validatedAt: null })) {
+          throw new ConsumerArtifactError('WAVE_INPUT_INVALID', 'Recorded wave admission changed');
+        }
+        return previous;
+      }
+      const record = { ...structuredClone(admission), validatedAt: admission.validatedAt ?? now() };
+      this.journal.waveAdmissions.push(record);
+      return record;
+    });
+  }
+
+  recordDispatchBinding({ dispatchToken, itemBinding, resolvedProfile }) {
+    return this.#mutate(() => {
+      if (this.journal.profilesDigest !== undefined && resolvedProfile?.profilesDigest !== this.journal.profilesDigest) {
+        throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Dispatch profile is not pinned to this run');
+      }
+      if (itemBinding.itemDigest !== digestJson(itemBinding.item)) {
+        throw new ConsumerArtifactError('WAVE_INPUT_INVALID', 'Dispatch item digest differs');
+      }
+      this.journal.dispatchBindings ??= {};
+      const binding = { itemBinding: structuredClone(itemBinding), resolvedProfile: structuredClone(resolvedProfile) };
+      const previous = this.journal.dispatchBindings[dispatchToken];
+      if (previous && digestJson(previous) !== digestJson(binding)) {
+        throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Dispatch binding changed');
+      }
+      this.journal.dispatchBindings[dispatchToken] = binding;
+      return binding;
+    });
+  }
+
+  recordPendingUsageReceipt({ dispatchId, receipt }) {
+    return this.#mutate(() => {
+      this.journal.pendingUsageReceipts ??= [];
+      const existing = this.journal.pendingUsageReceipts.find(r => r.dispatchId === dispatchId);
+      if (existing) {
+        if (digestJson(existing.receipt) !== digestJson(receipt)) {
+          throw new ConsumerArtifactError('CONSUMER_EVIDENCE_MISMATCH', 'Receipt payload changed on replay');
+        }
+        return existing;
+      }
+      const record = { dispatchId, receipt: structuredClone(receipt), state: 'pending' };
+      this.journal.pendingUsageReceipts.push(record);
+      return record;
+    });
+  }
+
+  acknowledgeUsageReceipt({ dispatchId, seq }) {
+    return this.#mutate(() => {
+      const receipt = this.journal.pendingUsageReceipts?.find(r => r.dispatchId === dispatchId);
+      if (!receipt) throw new ConsumerArtifactError('CONSUMER_EVIDENCE_MISMATCH', 'Receipt intent is missing');
+      receipt.state = 'acknowledged';
+      if (seq !== undefined) receipt.seq = seq;
+      return receipt;
+    });
+  }
+
+  initializeWave({ ref, profilesDigest }) {
+    return this.#mutate(() => {
+      if (this.journal.wave) {
+        if (this.journal.wave.ref !== ref || this.journal.wave.profilesDigest !== profilesDigest) {
+          throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Wave configuration changed');
+        }
+        return this.journal.wave;
+      }
+      if (readCheckpointRef({ cwd: this.targetCwd, ref }) !== null) {
+        throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Pre-existing unowned wave ref');
+      }
+      if (existsSync(resolve(this.targetCwd, git(this.targetCwd, ['rev-parse', '--git-path', 'MERGE_HEAD'])))
+        || git(this.targetCwd, ['ls-files', '-u'])) throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Unresolved index merge');
+      const baseCommit = git(this.targetCwd, ['rev-parse', 'HEAD']);
+      this.journal.wave = { ref, baseCommit, baseTree: git(this.targetCwd, ['rev-parse', 'HEAD^{tree}']),
+        initialWorkingTree: snapshotWorkingTree(this.targetCwd), profilesDigest, checkpoints: [] };
+      return this.journal.wave;
+    });
+  }
+
+  recordPreparedCheckpoint(checkpoint) {
+    return this.#mutate(() => {
+      const wave = this.journal.wave;
+      if (!wave) throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Wave not initialized');
+      const existing = wave.checkpoints.find(c => c.gateToken === checkpoint.gateToken);
+      if (existing) {
+        if (existing.commit !== checkpoint.commit || existing.tree !== checkpoint.tree) {
+          throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Checkpoint token changed');
+        }
+        return existing;
+      }
+      const parent = wave.checkpoints.at(-1)?.commit ?? wave.baseCommit;
+      if (checkpoint.parentCommit !== parent || checkpoint.waveNumber !== wave.checkpoints.length + 1
+        || !checkpoint.gateToken || !Number.isInteger(checkpoint.gateOrdinal)) {
+        throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Checkpoint order or identity differs');
+      }
+      const record = { ...structuredClone(checkpoint), state: 'prepared', preparedAt: now() };
+      wave.checkpoints.push(record);
+      return record;
+    });
+  }
+
+  markCheckpointPublished({ gateToken, commit, evidenceReceiptId }) {
+    return this.#mutate(() => {
+      const checkpoint = this.journal.wave?.checkpoints.find(c => c.gateToken === gateToken);
+      if (!checkpoint || checkpoint.commit !== commit
+        || readCheckpointRef({ cwd: this.targetCwd, ref: this.journal.wave.ref }) !== commit) {
+        throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Publication does not match prepared checkpoint');
+      }
+      this.#verifyCheckpointObject(checkpoint);
+      checkpoint.state = 'published';
+      checkpoint.publishedAt ??= now();
+      checkpoint.materializedTree ??= checkpoint.tree;
+      if (evidenceReceiptId) checkpoint.evidenceReceiptId = evidenceReceiptId;
+      return checkpoint;
+    });
+  }
+
+  /** Recover approved obligations only; never replay their patches into the live parent. */
+  recoverCheckpoint(transaction) {
+    const wave = this.journal.wave;
+    if (!wave) return;
+    let checkpoint = wave.checkpoints.find(c => c.gateToken === transaction.gateToken);
+    const tip = readCheckpointRef({ cwd: this.targetCwd, ref: wave.ref });
+    // A verified newer recorded tip must never be rewound to a historical checkpoint.
+    const index = checkpoint ? wave.checkpoints.indexOf(checkpoint) : -1;
+    if (checkpoint && (checkpoint.gateOrdinal !== transaction.gateOrdinal
+      || checkpoint.gateStepId !== transaction.gateStepId || checkpoint.tree !== transaction.witnessChain.at(-1)
+      || checkpoint.parentCommit !== transaction.checkpointParent)) {
+      throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Checkpoint differs from its approved merge obligation');
+    }
+    for (const [i, recorded] of wave.checkpoints.entries()) {
+      if (recorded.parentCommit !== (wave.checkpoints[i - 1]?.commit ?? wave.baseCommit)) {
+        throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Recorded checkpoint chain is broken');
+      }
+    }
+    if (index >= 0 && wave.checkpoints.slice(index + 1).some(c => c.state === 'published' && c.commit === tip)) {
+      for (const recorded of wave.checkpoints.slice(index)) this.#verifyCheckpointObject(recorded);
+      return;
+    }
+    if (!checkpoint) {
+      const previous = wave.checkpoints.at(-1)?.commit ?? null;
+      if (reconcileCheckpoint({ journalEntry: { gateOutcome: 'approve', previousCommit: previous }, refValue: tip }) !== 'PREPARE_AND_PUBLISH') {
+        throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Unexpected ref before preparation');
+      }
+      if (!Number.isInteger(transaction.gateOrdinal)) throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Missing gate ordinal');
+      const tree = transaction.witnessChain.at(-1);
+      this.#verifyCheckpointReplay(transaction, tree);
+      this.#materializeCheckpoint(transaction, tree);
+      const prepared = prepareCheckpoint({ cwd: this.targetCwd, ref: wave.ref,
+        parentCommit: transaction.checkpointParent ?? previous ?? wave.baseCommit, tree,
+        message: `Compose wave ${wave.checkpoints.length + 1} run ${this.runId} gate ${transaction.gateToken}` });
+      checkpoint = this.recordPreparedCheckpoint({ ...prepared, waveNumber: wave.checkpoints.length + 1,
+        fanoutStepId: transaction.fanoutStepId, epoch: transaction.epoch, gateStepId: transaction.gateStepId,
+        gateToken: transaction.gateToken, gateOrdinal: transaction.gateOrdinal, baselineTree: transaction.baselineTree,
+        orderedDispatchTokens: transaction.acceptedDispatchTokens ?? transaction.orderedDiffs.map(d => d.dispatchToken) });
+    }
+    this.#verifyCheckpointObject(checkpoint);
+    const action = reconcileCheckpoint({ journalEntry: checkpoint, refValue: tip });
+    if (action === 'REPLAY_AND_PUBLISH') {
+      if (checkpoint.payloadsDroppedAt) throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', 'Checkpoint payloads were already cleaned');
+      this.#materializeCheckpoint(transaction, checkpoint.tree);
+      this.#verifyCheckpointReplay(transaction, checkpoint.tree);
+      publishCheckpoint({ cwd: this.targetCwd, ref: wave.ref, expected: tip, commit: checkpoint.commit });
+    } else if (!['MARK_PUBLISHED', 'ALREADY_PUBLISHED'].includes(action)) {
+      throw new WaveCheckpointError(action, 'Cannot reconcile checkpoint ref');
+    } else if (transaction.witnessChain.slice(0, -1).includes(snapshotWorkingTree(this.targetCwd))) {
+      this.#materializeCheckpoint(transaction, checkpoint.tree);
+    }
+    this.markCheckpointPublished({ gateToken: checkpoint.gateToken, commit: checkpoint.commit });
+  }
+
+  #materializeCheckpoint(transaction, tree) {
+    const live = snapshotWorkingTree(this.targetCwd);
+    if (live === tree) return;
+    if (transaction.witnessChain.includes(live)) {
+      checkoutTreeDelta(this.targetCwd, live, tree);
+      return;
+    }
+    const changed = git(this.targetCwd, ['diff', '--name-only', '-z', '--no-renames', tree, live, '--'], { trim: false }).split('\0').filter(Boolean);
+    const wavePaths = new Set(git(this.targetCwd, ['diff', '--name-only', '-z', '--no-renames', transaction.baselineTree, tree, '--'],
+      { trim: false }).split('\0').filter(Boolean));
+    if (changed.some(path => wavePaths.has(path))) {
+      throw new WaveCheckpointError('WAVE_CHECKPOINT_DIVERGED', 'Parent differs ambiguously from the integrated checkpoint');
+    }
+    // Independent post-wave edits are preserved; publication captures only the witness.
+  }
+
+  #verifyCheckpointReplay(transaction, expectedTree) {
+    try {
+      const tree = withTemporaryIndex(this.targetCwd, env => {
+        git(this.targetCwd, ['read-tree', transaction.baselineTree], { env });
+        for (const ordered of transaction.orderedDiffs) {
+          if (typeof ordered.diff !== 'string' || sha256(ordered.diff) !== ordered.digest) throw new Error('Missing or changed retained patch');
+          if (ordered.diff) applyDiffToIndex(this.targetCwd, ordered.diff, env);
+        }
+        return git(this.targetCwd, ['write-tree'], { env });
+      });
+      if (tree !== expectedTree) throw new Error('Replayed tree differs');
+    } catch (error) { throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', error.message); }
+  }
+
+  #verifyCheckpointObject(checkpoint) {
+    try {
+      const object = git(this.targetCwd, ['cat-file', 'commit', checkpoint.commit], { trim: false });
+      const boundary = object.indexOf('\n\n');
+      const headers = object.slice(0, boundary).split('\n');
+      const metadata = checkpoint.commitMetadata;
+      const epoch = Math.floor(Date.parse(metadata.date) / 1000);
+      const identity = `${metadata.authorName} <${metadata.authorEmail}> ${epoch} +0000`;
+      const expectedHeaders = [`tree ${checkpoint.tree}`, `parent ${checkpoint.parentCommit}`,
+        `author ${identity}`, `committer ${identity}`];
+      if (digestJson(headers) !== digestJson(expectedHeaders)
+        || object.slice(boundary + 2).replace(/\n$/, '') !== checkpoint.message.replace(/\n$/, '')) {
+        throw new Error('Checkpoint identity/tree/parent/message differs');
+      }
+      git(this.targetCwd, ['cat-file', '-e', `${checkpoint.parentCommit}^{commit}`]);
+      git(this.targetCwd, ['cat-file', '-e', `${checkpoint.tree}^{tree}`]);
+    } catch (error) { throw new WaveCheckpointError('WAVE_CHECKPOINT_EVIDENCE_MISSING', error.message); }
+  }
+
   /** Record which fanout step a merge gate settles, so resume never re-derives it
    *  from a mutable local spec that may have drifted. First-write-wins per gate. */
   recordGateBinding({ gateStepId, fanoutStepId }) {
@@ -618,7 +930,7 @@ export class ConsumerFanoutArtifacts {
       || (scope.fanoutStepId === fanoutStepId && scope.itemIndex === itemIndex);
     let changed = false;
     for (const issuance of this.journal.issuances) {
-      if (issuance.state === 'merged' || issuance.state === 'superseded') continue;
+      if (issuance.state === 'merged' || issuance.state === 'superseded' || issuance.state === 'failed') continue;
       if (!inScope(issuance.fanoutStepId, issuance.itemIndex)) continue;
       const fanoutItems = audit?.steps?.[issuance.fanoutStepId]?.fanout?.items;
       const item = Array.isArray(fanoutItems) ? fanoutItems[issuance.itemIndex] : undefined;
@@ -670,13 +982,17 @@ export class ConsumerFanoutArtifacts {
    */
   reconcileDescriptor(descriptor, audit) {
     return this.#mutate(() => {
+      const binding = this.journal.dispatchBindings?.[descriptor.dispatchToken]?.itemBinding;
+      if (isNoneIsolation(descriptor) && Object.hasOwn(binding?.item ?? {}, 'files_owned')) {
+        throw new ConsumerArtifactError('WAVE_OWNERSHIP_INVALID', 'Ownership requires worktree isolation');
+      }
       // Per-item settlement: the descriptor's audit is a concurrent snapshot that
       // may be stale for OTHER items, so reconcile only this item's own records.
       this.#reconcileAuditInto(audit, { fanoutStepId: descriptor.step, itemIndex: descriptor.itemIndex });
       const prepared = this.journal.issuances.find(
         (entry) => entry.dispatchToken === descriptor.dispatchToken,
       );
-      if (prepared?.state === 'prepared') {
+      if (prepared?.state === 'prepared' || prepared?.state === 'failed') {
         return { action: 'report', envelope: structuredClone(prepared.envelope), issuance: prepared };
       }
       if (prepared?.state === 'accepted') {
@@ -739,14 +1055,26 @@ export class ConsumerFanoutArtifacts {
     });
   }
 
-  prepareIssuance(descriptor, envelope, { finalStage }) {
+  prepareIssuance(descriptor, envelope, { finalStage, itemBinding, resolvedProfile, ownership } = {}) {
     return this.#mutate(() => {
       const existing = this.journal.issuances.find(
         (entry) => entry.dispatchToken === descriptor.dispatchToken,
       );
       if (existing) return existing;
 
+      const binding = itemBinding ?? this.journal.dispatchBindings?.[descriptor.dispatchToken]?.itemBinding
+        ?? (ownership ? {
+          item: structuredClone(descriptor.item ?? {}), itemDigest: digestJson(descriptor.item ?? {}),
+          epoch: descriptor.epoch, sourceProvenance: 'descriptor.item',
+        } : undefined);
+      const ownershipEnabled = ownership || Object.hasOwn(binding?.item ?? {}, 'files_owned');
+      const profile = resolvedProfile ?? this.journal.dispatchBindings?.[descriptor.dispatchToken]?.resolvedProfile;
+      const fields = { ...(binding ? { itemBinding: structuredClone(binding) } : {}),
+        ...(profile ? { resolvedProfile: structuredClone(profile) } : {}) };
       if (isNoneIsolation(descriptor)) {
+        if (ownership || Object.hasOwn(binding?.item ?? {}, 'files_owned')) {
+          throw new ConsumerArtifactError('WAVE_OWNERSHIP_INVALID', 'Ownership requires worktree isolation');
+        }
         // Envelope-only journal entry: no worktree, no witness, no diff. It never
         // participates in the merge (prepareMerge filters isolation:none out), so
         // its files persist directly in the target cwd.
@@ -760,6 +1088,7 @@ export class ConsumerFanoutArtifacts {
           attempt: descriptor.attempt,
           revisionDigest: descriptor.revisionDigest,
           contractDigest: descriptor.contractDigest,
+          ...fields,
           isolation: 'none',
           worktreeKey: null,
           witnessTree: null,
@@ -796,6 +1125,8 @@ export class ConsumerFanoutArtifacts {
         attempt: descriptor.attempt,
         revisionDigest: descriptor.revisionDigest,
         contractDigest: descriptor.contractDigest,
+        ...fields,
+        ...(ownershipEnabled && finalStage ? { ownership: { baseCommit: worktree.baseCommit } } : {}),
         isolation: 'worktree',
         worktreeKey: worktree.key,
         witnessTree: witness.witnessTree,
@@ -806,11 +1137,39 @@ export class ConsumerFanoutArtifacts {
         diffDigest: diff === null ? null : sha256(diff),
         preparedAt: now(),
       };
+      if (finalStage && ownershipEnabled) {
+        const finding = checkOwnership(this.targetCwd, entry, { capture: true });
+        if (finding) this.#failOwnership(entry, finding);
+      }
       this.journal.issuances.push(entry);
       return entry;
     });
   }
 
+  #failOwnership(entry, finding) {
+    entry.state = 'failed';
+    entry.findings ??= [];
+    if (!entry.findings.some(f => f.code === finding.code && f.message === finding.message)) entry.findings.push(finding);
+    entry.ownership ??= {};
+    entry.ownership.finding = finding;
+    entry.envelope = { ...entry.envelope, failure: `${finding.code}: ${finding.message}` };
+    delete entry.envelope.output;
+  }
+
+  #verifyOwnership(entry, ordered) {
+    let finding = checkOwnership(this.targetCwd, entry);
+    if (entry.itemBinding && ordered && (ordered.diff !== entry.diff || ordered.digest !== entry.diffDigest
+      || ordered.bindingDigest !== digestJson(entry.itemBinding))) {
+      finding = { code: 'OWNERSHIP_EVIDENCE_MISMATCH', message: 'Ordered patch/binding differs from captured issuance',
+        dispatchToken: entry.dispatchToken, severity: 'error', files: [], allowedFiles: entry.itemBinding.item?.files_owned ?? [] };
+    }
+    if (finding) {
+      this.#failOwnership(entry, finding);
+      this.#save();
+      throw new ConsumerMergeDecisionError(finding.code, finding.message, { finding });
+    }
+  }
+
   prepareArtifactFailure(descriptor, envelope, error) {
     return this.#mutate(() => {
       const existing = this.journal.issuances.find(
@@ -861,13 +1220,20 @@ export class ConsumerFanoutArtifacts {
         { gateToken },
       );
     }
-    if (existing) return existing;
+    if (existing) {
+      for (const ordered of existing.orderedDiffs ?? []) {
+        const issuance = this.journal.issuances.find(e => e.dispatchToken === ordered.dispatchToken);
+        if (issuance) this.#verifyOwnership(issuance, ordered);
+      }
+      return existing;
+    }
 
     const accepted = this.acceptedEntriesFor(fanoutStepId);
     // Only isolation:worktree items own a diff and participate in the merge.
     // isolation:none items already wrote in the target cwd; they are accepted
     // evidence but owe no diff (a pure-none fanout yields zero ordered diffs).
     const worktreeAccepted = accepted.filter((entry) => entry.isolation !== 'none');
+    for (const entry of worktreeAccepted) this.#verifyOwnership(entry);
     const baselineTree = snapshotWorkingTree(this.targetCwd);
     // A worker that changed NOTHING owes an empty diff, not a missing one, and it
     // must not join the merge: applying nothing leaves the tree identical, so its
@@ -888,6 +1254,7 @@ export class ConsumerFanoutArtifacts {
       itemIndex: entry.itemIndex,
       generation: entry.generation,
       digest: entry.diffDigest,
+      ...(entry.itemBinding ? { bindingDigest: digestJson(entry.itemBinding) } : {}),
       diff: entry.diff,
     }));
     const recordBlocked = (code, message, witnessChain = [baselineTree]) => {
@@ -965,6 +1332,12 @@ export class ConsumerFanoutArtifacts {
       gateToken,
       fanoutStepId,
       state: 'prepared',
+      ...(this.journal.wave ? {
+        epoch: audit?.steps?.[fanoutStepId]?.epoch,
+        checkpointParent: this.journal.wave.checkpoints.at(-1)?.commit ?? this.journal.wave.baseCommit,
+        acceptedDispatchTokens: worktreeAccepted.map(e => e.dispatchToken),
+        gateOrdinal: (audit?.events ?? []).filter(e => e.type === 'gate_resolved' && e.stepId === gateStepId).length,
+      } : {}),
       baselineTree,
       witnessChain,
       orderedDiffs,
@@ -1079,6 +1452,10 @@ export class ConsumerFanoutArtifacts {
         // not a lockfile in this slice.
         const live = this.#currentTransaction(gateToken);
         if (live) this.#assertMergeNotDecided(live, gateToken);
+        this.#mutate(() => {
+          const issuance = this.journal.issuances.find(e => e.dispatchToken === ordered.dispatchToken);
+          if (issuance) this.#verifyOwnership(issuance, ordered);
+        });
         // Same merge algorithm as the witness precompute (temporary index,
         // three-way), then the merged tree is checked out. Applying straight to
         // the working tree cannot use --3way (it requires the real index to match).
@@ -1165,7 +1542,7 @@ export class ConsumerFanoutArtifacts {
     });
   }
 
-  restoreMergeBaseline(transaction, audit) {
+  restoreMergeBaseline(transaction, audit, opts = {}) {
     if (!transaction) return undefined;
     return this.#mutate(() => {
       // Re-find against the fresh journal — the passed reference may predate a
@@ -1176,6 +1553,7 @@ export class ConsumerFanoutArtifacts {
       restoreWorkingTree(this.targetCwd, tx.baselineTree);
       tx.state = wasBlocked ? 'blocked' : 'rolled_back';
       tx.rolledBackAt = now();
+      tx.rollbackReason = opts.reason ?? null;
       tx.recovery ??= { baselineRestores: 0 };
       tx.recovery.baselineRestores = (tx.recovery.baselineRestores ?? 0) + 1;
       tx.recovery.baselineVerifiedTree = tx.baselineTree;
@@ -1214,6 +1592,20 @@ export class ConsumerFanoutArtifacts {
     });
   }
 
+  /** C40: a failed restore callback writes nothing. Persist its finding through
+   * a separate guarded mutation, reloading the durable transaction first. */
+  markRollbackFailed(transaction, error) {
+    if (!transaction) return undefined;
+    return this.#mutate(() => {
+      const tx = this.journal.mergeTransactions.find((entry) => entry.gateToken === transaction.gateToken);
+      if (!tx) return undefined;
+      tx.state = 'rollback_failed';
+      tx.failureCode = 'merge_revert_failed';
+      tx.failure = error?.message ?? String(error);
+      return tx;
+    });
+  }
+
   markGateResolved(transaction, outcome) {
     if (!transaction) return undefined;
     return this.#mutate(() => {
@@ -1238,10 +1630,18 @@ export class ConsumerFanoutArtifacts {
     });
   }
 
-  cleanupWorktrees(reason) {
+  cleanupWorktrees(reason, { dispatchTokens } = {}) {
     this.#mutate(() => {
+      const selected = dispatchTokens ? new Set(dispatchTokens) : null;
+      const eligible = token => {
+        if (selected && !selected.has(token)) return false;
+        if (!this.journal.wave) return true;
+        return this.journal.wave.checkpoints.some(c => c.state === 'published' && c.evidenceReceiptId
+          && c.orderedDispatchTokens.includes(token));
+      };
+      const worktreeKeys = new Set(this.journal.issuances.filter(e => eligible(e.dispatchToken)).map(e => e.worktreeKey));
       for (const record of this.journal.worktrees) {
-        if (record.cleanedAt) continue;
+        if (record.cleanedAt || (selected || this.journal.wave) && !worktreeKeys.has(record.key)) continue;
         if (existsSync(record.path)) {
           try {
             git(this.targetCwd, ['worktree', 'remove', '--force', record.path], { timeout: 60_000 });
@@ -1254,16 +1654,20 @@ export class ConsumerFanoutArtifacts {
         record.cleanupReason = reason;
       }
       for (const issuance of this.journal.issuances) {
-        if (typeof issuance.diff === 'string') {
+        if (eligible(issuance.dispatchToken) && typeof issuance.diff === 'string') {
           issuance.diff = null;
           issuance.diffDroppedAt = now();
         }
       }
+      for (const checkpoint of this.journal.wave?.checkpoints ?? []) {
+        if (checkpoint.state === 'published' && checkpoint.evidenceReceiptId
+          && checkpoint.orderedDispatchTokens.every(eligible)) checkpoint.payloadsDroppedAt ??= now();
+      }
       for (const transaction of this.journal.mergeTransactions) {
         for (const ordered of transaction.orderedDiffs ?? []) {
-          if (typeof ordered.diff === 'string') ordered.diff = null;
+          if (eligible(ordered.dispatchToken) && typeof ordered.diff === 'string') ordered.diff = null;
         }
-        if (transaction.orderedDiffs?.length > 0 && !transaction.diffPayloadsDroppedAt) {
+        if (transaction.orderedDiffs?.length > 0 && transaction.orderedDiffs.every(d => d.diff === null) && !transaction.diffPayloadsDroppedAt) {
           transaction.diffPayloadsDroppedAt = now();
         }
       }
@@ -1297,10 +1701,15 @@ export function verifyConsumerRunRevision({
   artifactRoot,
   specDigest,
   resumeRevisionDigest,
+  profilesDigest,
 }) {
   if (!runId || !existsSync(journalLocation({ runId, targetCwd, artifactRoot }))) return null;
   const { journal } = new ConsumerFanoutArtifacts({ runId, targetCwd, artifactRoot });
 
+  if ((journal.profilesDigest !== undefined || profilesDigest !== undefined) && journal.profilesDigest !== profilesDigest) {
+    throw new ConsumerArtifactError('CONSUMER_PROFILE_REVISION_MISMATCH', 'Consumer profiles differ from the pinned run',
+      { recorded: journal.profilesDigest, current: profilesDigest });
+  }
   const fullyPinned = Boolean(journal.revisionDigest) && Boolean(journal.specDigest);
   if (!fullyPinned) {
     const hasWork = journal.issuances.length > 0
@@ -1382,13 +1791,14 @@ export function recoverAdvancedConsumerArtifacts({
     const matchingGateEvents = gateEvents.filter(
       (event) => event.stepId === transaction.gateStepId,
     );
-    const eventOffset = gateEventOffsets.get(transaction.gateStepId) ?? 0;
+    const eventOffset = transaction.gateOrdinal ?? gateEventOffsets.get(transaction.gateStepId) ?? 0;
     const resolvedEvent = matchingGateEvents[eventOffset];
     gateEventOffsets.set(transaction.gateStepId, eventOffset + 1);
     const resolvedOutcome = transaction.gateOutcome ?? resolvedEvent?.detail?.decision;
     const approvedComplete = transaction.state === 'complete' && resolvedOutcome === 'approve';
 
-    if (approvedComplete && gateState?.status !== 'waiting_gate') {
+    if (approvedComplete && (artifacts.journal.wave || gateState?.status !== 'waiting_gate')) {
+      if (artifacts.journal.wave) artifacts.recoverCheckpoint(transaction);
       artifacts.markGateAdvanced({ gateToken: transaction.gateToken, outcome: resolvedOutcome, at: resolvedEvent?.at });
       recoveredDecision = true;
       approvedAdvanced = true;