@entrorove/skill 0.1.23 → 0.1.25

package/local-ledger.mjs

@@ -1,3 +1,4 @@
+import { operationSchemasFor } from './local-contracts.mjs';
 import { createHash, randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -18,9 +19,20 @@ async function repository(value) { if (typeof value !== 'string' || !path.isAbso
 function repoDigest(root) { return sha(root).slice(0, 32); }
 async function privateDir(directory) { await fs.mkdir(directory, { recursive: true, mode: 0o700 }); const stat = await fs.lstat(directory); if (!stat.isDirectory() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'state directory must be a real directory'); if (process.platform !== 'win32') await fs.chmod(directory, 0o700); }
 async function atomic(file, value) { await privateDir(path.dirname(file)); const tmp = `${file}.${randomUUID()}.tmp`; await fs.writeFile(tmp, `${canonical(value)}\n`, { flag: 'wx', mode: 0o600 }); await fs.rename(tmp, file); if (process.platform !== 'win32') await fs.chmod(file, 0o600); }
-async function read(file) { await privateDir(path.dirname(file)); const stat = await fs.lstat(file); if (!stat.isFile() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'ledger state must be a regular file'); return JSON.parse(await fs.readFile(file, 'utf8')); }
+async function read(file, ensureDirectory = true) { if (ensureDirectory) await privateDir(path.dirname(file)); const stat = await fs.lstat(file); if (!stat.isFile() || stat.isSymbolicLink()) fail('ENTROROVE_STATE_INVALID', 'ledger state must be a regular file'); return JSON.parse(await fs.readFile(file, 'utf8')); }
 function ledgerPath(home, root) { return path.join(rootFor(home), 'ledgers', repoDigest(root), 'state.json'); }
 async function loadLedger(input, create = false) { const root = await repository(input.repositoryRoot); const file = ledgerPath(input.home, root); try { const state = await read(file); if (state.schemaVersion !== LEDGER_SCHEMA || state.repositoryDigest !== repoDigest(root)) fail('ENTROROVE_LEDGER_INVALID', 'ledger identity mismatch'); return { root, file, state }; } catch (error) { if (!create || error.code !== 'ENOENT') throw error; const state = { schemaVersion: LEDGER_SCHEMA, repositoryDigest: repoDigest(root), sequence: 0, head: null, activeBranch: null, branches: [], records: [] }; await atomic(file, state); return { root, file, state }; } }
+async function readLedgerForQuery(input) {
+  const root = await repository(input.repositoryRoot); const file = ledgerPath(input.home, root);
+  try {
+    const state = await read(file, false);
+    if (state.schemaVersion !== LEDGER_SCHEMA || state.repositoryDigest !== repoDigest(root)) fail('ENTROROVE_LEDGER_INVALID', 'ledger identity mismatch');
+    return { root, file, state };
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return { root, file, state: { schemaVersion: LEDGER_SCHEMA, repositoryDigest: repoDigest(root), sequence: 0, head: null, activeBranch: null, branches: [], records: [] } };
+  }
+}
 async function append(input, event, data = {}) { const root = await repository(input.repositoryRoot); const file = ledgerPath(input.home, root); const previous = ledgerLocks.get(file) ?? Promise.resolve(); let release; const current = new Promise(resolve => { release = resolve; }); const queued = previous.then(() => current); ledgerLocks.set(file, queued); await previous; try { return await withStateLock(file, async () => { const authority = await loadLedger(input, true); const at = new Date().toISOString(); const unsigned = { sequence: authority.state.sequence + 1, event, at, ...data }; const record = { ...unsigned, previousDigest: authority.state.head, digest: sha(canonical(unsigned) + (authority.state.head ?? '')) }; const state = { ...authority.state, sequence: record.sequence, head: record.digest, records: [...authority.state.records, record] }; await atomic(authority.file, state); return { authority, state, record }; }); } finally { release(); if (ledgerLocks.get(file) === queued) ledgerLocks.delete(file); } }
 export async function appendLedgerRecord(input, event, data = {}) { if (typeof event !== 'string' || !event.trim()) fail('ENTROROVE_LEDGER_EVENT', 'ledger event is required'); return (await append(input, event, data)).record; }
 export async function branchCreate(input) { const name = id(input.name ?? input.branchName, 'branchName'); const fromRef = typeof input.fromRef === 'string' && input.fromRef ? input.fromRef : 'working-tree'; const authority = await loadLedger(input, true); if (authority.state.branches.some(item => item.name === name)) fail('ENTROROVE_BRANCH_EXISTS', `virtual branch already exists: ${name}`); const branch = { branchId: `branch-${randomUUID()}`, name, fromRef, description: input.description ?? '', virtual: true, createdAt: new Date().toISOString(), snapshotId: input.snapshotId ?? null }; const state = { ...authority.state, branches: [...authority.state.branches, branch], activeBranch: authority.state.activeBranch ?? name }; await atomic(authority.file, state); await append(input, 'branch-create', { name, fromRef, virtual: true }); return { schemaVersion: LEDGER_SCHEMA, status: 'verified', branch, forbidGitBranch: true, forbidWorktree: true }; }
@@ -35,7 +47,7 @@ export async function preflight(input) {
   const reasons = []; if (!archguard.verified) reasons.push(archguard.reason); if (!evidence) reasons.push('trusted signed evidence bound to this flow, snapshot, and contract with exitCode 0 is required');
   return { schemaVersion: LEDGER_SCHEMA, status: archguard.verified && evidence ? 'verified' : 'blocked', source: 'entrorove-ledger', checks: { archguard: archguard.verified, evidence }, reasons, virtualOnly: true, keyId: archguard.keyId ?? null };
 }
-export async function ledgerQuery(input) { const authority = await loadLedger(input, true); const limit = Number.isSafeInteger(input.limit) ? Math.min(500, Math.max(1, input.limit)) : 100; return { schemaVersion: LEDGER_SCHEMA, status: 'verified', repositoryDigest: repoDigest(authority.root), records: authority.state.records.slice(-limit), head: authority.state.head, sequence: authority.state.sequence }; }
+export async function ledgerQuery(input) { const authority = await readLedgerForQuery(input); const limit = Number.isSafeInteger(input.limit) ? Math.min(500, Math.max(1, input.limit)) : 100; return { schemaVersion: LEDGER_SCHEMA, status: 'verified', repositoryDigest: repoDigest(authority.root), records: authority.state.records.slice(-limit), head: authority.state.head, sequence: authority.state.sequence }; }
 
 function validatePlan(plan) { if (!plan || typeof plan !== 'object' || Array.isArray(plan) || plan.schemaVersion !== 'entrorove.execution-plan/1.0' || !ID.test(plan.chainId) || !Array.isArray(plan.steps) || !plan.steps.length) fail('ENTROROVE_CHAIN_PLAN_INVALID', 'chain plan must declare a schema, chainId, and steps'); const seen = new Set(); for (const [index, step] of plan.steps.entries()) { if (!step || typeof step !== 'object' || !ID.test(step.stepId) || seen.has(step.stepId) || !['command', 'skill', 'coordinator', 'decision'].includes(step.kind)) fail('ENTROROVE_CHAIN_STEP_INVALID', `step ${index} is invalid`); seen.add(step.stepId); } return plan; }
 async function chainAuthority(input, create = false) { const root = await repository(input.repositoryRoot); const chainId = id(input.chainId ?? input.plan?.chainId, 'chainId'); const file = path.join(rootFor(input.home), 'chains', repoDigest(root), chainId, 'state.json'); try { const state = await read(file); if (state.schemaVersion !== CHAIN_SCHEMA || state.chainId !== chainId || state.repositoryDigest !== repoDigest(root)) fail('ENTROROVE_CHAIN_INVALID', 'chain state identity mismatch'); return { root, chainId, file, state }; } catch (error) { if (!create || error.code !== 'ENOENT') throw error; return { root, chainId, file, state: null }; } }
@@ -49,10 +61,4 @@ export const LOCAL_LEDGER_OPERATIONS = Object.freeze({
   'chain-init': chainInit, 'chain-resume': chainResume, 'chain-status': chainStatus, 'chain-answer': chainAnswer,
   'branch-create-virtual': branchCreate, 'chain-ledger-init': chainInit, 'chain-ledger-status': chainStatus, 'chain-ledger-query': ledgerQuery,
 });
-const LEDGER_REQUIRED = {
-  'branch-create': ['repositoryRoot', 'name', 'fromRef'], 'branch-list': ['repositoryRoot'], 'branch-switch': ['repositoryRoot', 'branchName'],
-  'diff-report': ['repositoryRoot'], preflight: ['repositoryRoot'], 'ledger-query': ['repositoryRoot'], 'chain-init': ['repositoryRoot', 'plan'],
-  'chain-resume': ['repositoryRoot', 'chainId'], 'chain-status': ['repositoryRoot', 'chainId'], 'chain-answer': ['repositoryRoot', 'chainId', 'answer'],
-  'branch-create-virtual': ['repositoryRoot', 'name', 'fromRef'], 'chain-ledger-init': ['repositoryRoot', 'plan'], 'chain-ledger-status': ['repositoryRoot', 'chainId'], 'chain-ledger-query': ['repositoryRoot'],
-};
-export const LOCAL_LEDGER_SCHEMAS = Object.freeze(Object.fromEntries(Object.keys(LOCAL_LEDGER_OPERATIONS).map(operation => [operation, { type: 'object', additionalProperties: false, required: LEDGER_REQUIRED[operation] ?? [] }])));
+export const LOCAL_LEDGER_SCHEMAS = operationSchemasFor(LOCAL_LEDGER_OPERATIONS);

package/local-merge-archguard-verification.d.mts

@@ -0,0 +1,44 @@
+import type { KeyObject } from 'node:crypto';
+
+export interface MergeInspectionOptions {
+  publicKey?: string;
+  now?: number;
+  consumedNonces?: ReadonlySet<string>;
+}
+export interface MergePreflightInspectionOptions extends MergeInspectionOptions {
+  preparation?: unknown;
+  mergeLease?: unknown;
+  preparationPublicKey?: string;
+  authorityPublicKey?: string;
+  consumedPreparationNonces?: ReadonlySet<string>;
+  consumedLeaseNonces?: ReadonlySet<string>;
+}
+export interface MergeReceiptDetails {
+  authentic?: boolean;
+  status?: 'passed' | 'blocked';
+  reason?: string;
+  preparation?: Record<string, unknown>;
+  preflight?: Record<string, unknown>;
+  attestation?: Record<string, unknown>;
+}
+export type MergeReceiptInspection = MergeReceiptDetails & (
+  { verified: true; keyId: string; nonce: string; receiptDigest: string }
+  | { verified: false; keyId?: string; nonce?: string; receiptDigest?: string }
+);
+export const MERGE_ARCHGUARD_SCHEMA: 'entrorove.archguard-merge-preflight/1.0';
+export const MERGE_PREPARATION_SCHEMA: 'entrorove.merge-preparation-receipt/1.0';
+export const MERGE_PIN_ENV: 'ENTROROVE_ARCHGUARD_RUNNER_PUBLIC_KEY';
+export const MERGE_ARCHGUARD_RUNTIME_SHA256: string;
+export const SHA256: RegExp;
+export const ID: RegExp;
+export function mergeSha256(bytes: string | Uint8Array): string;
+export function mergeCanonical(value: unknown): string;
+export function configuredMergePin(publicKey: string | undefined): { key: KeyObject; der: Buffer; keyId: string; publicKey: string };
+export function verifyMergeSignature(value: unknown, signature: unknown, keyId: unknown, publicKey: string | undefined): string;
+export function verifyMergeLifetime(value: Record<string, unknown>, now?: number, consumedNonces?: ReadonlySet<string>): void;
+export function inspectMergeSignedEnvelope(value: unknown, options: MergeInspectionOptions & { schemaVersion: string }): MergeReceiptInspection;
+export function inspectLegacyArchguardPreflight(value: unknown, binding?: Record<string, unknown>, options?: MergeInspectionOptions): MergeReceiptInspection;
+export function mergeArtifactSha256(files: ReadonlyArray<{ path: string; sha256: string }>): string;
+export function mergePreflightBinding(preparation: Record<string, unknown>): Record<string, unknown>;
+export function inspectMergePreparation(preparation: unknown, binding?: Record<string, unknown>, options?: MergeInspectionOptions): MergeReceiptInspection;
+export function inspectMergeArchguardPreflight(preflight: unknown, binding?: Record<string, unknown>, options?: MergePreflightInspectionOptions): MergeReceiptInspection;

package/local-merge-archguard-verification.mjs

@@ -0,0 +1,240 @@
+import { createHash, createPublicKey, verify } from 'node:crypto';
+
+export const MERGE_ARCHGUARD_SCHEMA = 'entrorove.archguard-merge-preflight/1.0';
+export const MERGE_PREPARATION_SCHEMA = 'entrorove.merge-preparation-receipt/1.0';
+export const MERGE_PIN_ENV = 'ENTROROVE_ARCHGUARD_RUNNER_PUBLIC_KEY';
+export const SHA256 = /^[0-9a-f]{64}$/;
+export const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const idValid = value => typeof value === 'string' && ID.test(value);
+export const mergeSha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+export const MERGE_ARCHGUARD_RUNTIME_SHA256 = '836f20b270139371bef43e3934fa7232371e42d46371c513db2a5e3c5622b215';
+const MISSING_SHA256 = mergeSha256('entrorove.missing-file/1.0');
+const CONTEXT_FIELDS = ['repositoryDigest', 'flowId', 'stepId', 'baselineRef', 'sourceRef', 'targetRef', 'paths',
+  'sourceFiles', 'targetFiles', 'afterManifest', 'beforeFullManifest', 'mergedArtifactSha256', 'snapshotDigest',
+  'snapshotReceiptDigest', 'architectureContractDigest', 'mappings', 'mappingProof', 'mappingDigest', 'mergeLeaseDigest', 'architectureLedgerDigest'];
+const LEASE_CONTEXT = ['mergeId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'leaseId', 'generation', 'epoch', 'scopePaths'];
+const OPTIONAL_CONTEXT = ['handoffEpoch'];
+
+export function mergeCanonical(value, ancestors = new Set()) {
+  if (value === null || ['string', 'boolean'].includes(typeof value)) return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (!value || typeof value !== 'object' || ancestors.has(value)
+    || (!Array.isArray(value) && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))) {
+    throw new Error('Merge evidence must be finite plain JSON');
+  }
+  const next = new Set(ancestors).add(value);
+  return Array.isArray(value) ? `[${value.map(item => mergeCanonical(item, next)).join(',')}]`
+    : `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${mergeCanonical(value[key], next)}`).join(',')}}`;
+}
+
+export function configuredMergePin(publicKey) {
+  if (typeof publicKey !== 'string' || !publicKey) throw new Error('An independently configured Archguard runner pin is required');
+  const der = Buffer.from(publicKey, 'base64');
+  if (der.toString('base64') !== publicKey) throw new Error('Archguard runner pin must be canonical base64');
+  const key = createPublicKey({ key: der, type: 'spki', format: 'der' });
+  if (key.asymmetricKeyType !== 'ed25519' || !key.export({ type: 'spki', format: 'der' }).equals(der)) {
+    throw new Error('Archguard runner pin must be canonical Ed25519 SPKI');
+  }
+  return { key, der, keyId: mergeSha256(der), publicKey };
+}
+
+export function verifyMergeSignature(value, signature, keyId, publicKey) {
+  const pin = configuredMergePin(publicKey);
+  if (typeof signature !== 'string' || !/^[A-Za-z0-9_-]{86}$/.test(signature)) throw new Error('Archguard signature must be canonical base64url');
+  const bytes = Buffer.from(signature, 'base64url');
+  if (bytes.length !== 64 || bytes.toString('base64url') !== signature || keyId !== pin.keyId) throw new Error('Archguard signature or key identity is invalid');
+  const source = mergeCanonical(value);
+  if (Buffer.byteLength(source) > 4 * 1024 * 1024 || !verify(null, Buffer.from(source), pin.key, bytes)) throw new Error('Archguard signature is invalid');
+  return pin.keyId;
+}
+
+export function verifyMergeLifetime(value, now = Date.now(), consumedNonces) {
+  const issued = Date.parse(value.issuedAt), expires = Date.parse(value.expiresAt);
+  if (!Number.isFinite(now) || typeof value.issuedAt !== 'string' || typeof value.expiresAt !== 'string'
+    || !Number.isFinite(issued) || !Number.isFinite(expires) || issued > now || expires <= now || expires <= issued
+    || expires - issued > 300_000 || !idValid(value.nonce) || consumedNonces?.has(value.nonce)) {
+    throw new Error('Archguard receipt lifetime, nonce, or replay state is invalid');
+  }
+}
+
+export function inspectMergeSignedEnvelope(value, options = {}) {
+  try {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || value.schemaVersion !== options.schemaVersion) throw new Error('Merge receipt schema is invalid');
+    const { signature, ...unsigned } = value;
+    verifyMergeLifetime(value, options.now, options.consumedNonces);
+    const keyId = verifyMergeSignature(unsigned, signature, value.keyId,
+      Object.hasOwn(options, 'publicKey') ? options.publicKey : process.env[MERGE_PIN_ENV]?.trim());
+    return { verified: true, keyId, nonce: value.nonce, receiptDigest: mergeSha256(mergeCanonical(value)) };
+  } catch (error) { return { verified: false, reason: error instanceof Error ? error.message : String(error) }; }
+}
+
+export function inspectLegacyArchguardPreflight(attestation, binding = {}, options = {}) {
+  try {
+    if (!attestation || attestation.schemaVersion !== 'entrorove.archguard-preflight/1.0' || attestation.status !== 'passed'
+      || !idValid(attestation.flowId) || !idValid(attestation.stepId)
+      || !SHA256.test(String(attestation.snapshotDigest)) || !SHA256.test(String(attestation.contractDigest))) {
+      throw new Error('Archguard preflight is missing or not passed');
+    }
+    const keys = ['flowId', 'stepId', 'snapshotDigest', 'contractDigest'];
+    for (const key of ['mergeDigest', 'preparationDigest', 'sourceRef', 'targetRef']) if (Object.hasOwn(binding, key)) keys.push(key);
+    if (keys.some(key => !Object.hasOwn(binding, key) || mergeCanonical(attestation[key]) !== mergeCanonical(binding[key]))) throw new Error('Archguard preflight frozen binding does not match');
+    const { receipt, ...unsigned } = attestation;
+    if (!receipt || receipt.schemaVersion !== 'entrorove.runner-receipt/1.0') throw new Error('Archguard signed receipt is missing');
+    verifyMergeLifetime(attestation, options.now, options.consumedNonces);
+    const keyId = verifyMergeSignature(unsigned, receipt.signature, receipt.keyId,
+      Object.hasOwn(options, 'publicKey') ? options.publicKey : process.env[MERGE_PIN_ENV]?.trim());
+    return { verified: true, attestation, keyId, nonce: attestation.nonce, receiptDigest: mergeSha256(mergeCanonical(attestation)) };
+  } catch (error) { return { verified: false, reason: error instanceof Error ? error.message : String(error) }; }
+}
+
+function requireValue(condition, message) { if (!condition) throw new Error(message); }
+function canonicalEqual(left, right) { return mergeCanonical(left) === mergeCanonical(right); }
+function pathValid(value) {
+  return typeof value === 'string' && value.length <= 500 && value === value.trim() && value === value.normalize('NFC')
+    && !/^[~\/]|[\\:\u0000-\u001f\u007f]/.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
+}
+function validateManifest(files, source = false) {
+  requireValue(Array.isArray(files) && files.length > 0 && files.length <= 512, 'Merge file manifest is missing or unbounded');
+  const names = files.map(file => file?.path);
+  requireValue(names.every(pathValid) && canonicalEqual(names, [...new Set(names)].sort()), 'Merge manifest paths must be canonical, sorted and unique');
+  requireValue(!names.some((name, index) => names.slice(index + 1).some(other => other.startsWith(`${name}/`))), 'Merge manifest paths overlap');
+  for (const file of files) {
+    const fields = source ? 'exists|mode|path|sha256|sourcePath' : 'exists|mode|path|sha256';
+    requireValue(Object.keys(file).sort().join('|') === fields && (!source || pathValid(file.sourcePath)), 'Merge file origin or metadata shape is invalid');
+    requireValue(file && typeof file.exists === 'boolean' && SHA256.test(String(file.sha256))
+      && (file.exists ? Number.isSafeInteger(file.mode) && file.mode >= 0 && file.mode <= 0o777 : file.mode === null && file.sha256 === MISSING_SHA256), 'Merge manifest file metadata is invalid');
+    requireValue(!source || file.exists, 'Merge source deletion is explicitly unsupported');
+  }
+}
+function validateMapping(value, source) {
+  const proof = value.mappingProof;
+  requireValue(proof?.schemaVersion === 'entrorove.merge-artifact-mapping/1.0' && SHA256.test(String(value.mappingDigest))
+    && mergeSha256(mergeCanonical(proof)) === value.mappingDigest, 'Merge mapping must retain its complete original frozen proof');
+  requireBinding(proof, value, ['flowId', 'ownerId', 'taskDigest', 'chainDigest']);
+  requireValue(idValid(proof.planId) && SHA256.test(String(proof.planDigest)) && SHA256.test(String(proof.scopeArtifactDigest))
+    && proof.blueprintBinding && typeof proof.blueprintBinding === 'object' && !Array.isArray(proof.blueprintBinding)
+    && Object.keys(proof.blueprintBinding).length > 0, 'Merge mapping original plan or Blueprint ancestry is missing');
+  requireValue(Array.isArray(proof.entries) && proof.entries.length > 0 && proof.entries.length <= 512
+    && proof.entries.every(entry => entry && pathValid(entry.sourcePath) && pathValid(entry.targetPath)
+      && SHA256.test(String(entry.sha256)) && idValid(entry.producerNodeRef) && idValid(entry.producerStepId) && idValid(entry.stepId)), 'Merge mapping producer entries are invalid');
+  const targets = proof.entries.map(entry => entry.targetPath), origins = proof.entries.map(entry => entry.sourcePath);
+  requireValue(canonicalEqual(targets, [...new Set(targets)].sort()) && new Set(origins).size === origins.length, 'Merge mapping origins or targets are duplicated');
+  const expected = source.map(file => ({ sourcePath: file.sourcePath, targetPath: file.path }));
+  requireValue(canonicalEqual(value.mappings, expected), 'Merge source origins do not match their exact immutable mapping');
+  for (const file of source) requireValue(proof.entries.some(entry => entry.sourcePath === file.sourcePath
+    && entry.targetPath === file.path && entry.sha256 === file.sha256), 'Merge mapping source is not the original declared producer artifact');
+}
+export function mergeArtifactSha256(files) {
+  return mergeSha256(`validator.file-manifest/1.0\n${files.map(file => `${file.path}\0${file.sha256}`).join('\n')}`);
+}
+function validateRef(ref, role, preparation, files) {
+  requireValue(ref?.kind === 'snapshot' && idValid(ref.artifactId) && SHA256.test(String(ref.manifestDigest)), 'Merge ref must identify a frozen snapshot');
+  const manifest = { schemaVersion: 'entrorove.merge-artifact/1.0', artifactId: ref.artifactId, role,
+    repositoryDigest: preparation.repositoryDigest, flowId: preparation.flowId, stepId: preparation.stepId, files };
+  requireValue(ref.manifestDigest === mergeSha256(mergeCanonical(manifest)), 'Merge reference does not bind the exact frozen manifest');
+}
+export function mergePreflightBinding(preparation) {
+  const fields = [...CONTEXT_FIELDS, ...LEASE_CONTEXT, ...OPTIONAL_CONTEXT.filter(key => Object.hasOwn(preparation, key))];
+  return { ...Object.fromEntries(fields.map(key => [key, preparation[key]])),
+    preparationDigest: mergeSha256(mergeCanonical(preparation)), mergeDigest: preparation.mergedArtifactSha256 };
+}
+function validatePreparation(value) {
+  requireValue(/^[0-9a-f]{32}$/.test(String(value.repositoryDigest)) && idValid(value.flowId) && idValid(value.stepId), 'Merge preparation repository, flow or step is invalid');
+  requireValue(typeof value.baselineRef === 'string' && value.baselineRef.trim() === value.baselineRef && value.baselineRef.length > 0 && value.baselineRef.length <= 2_000, 'Merge baseline reference is required');
+  for (const key of ['mergedArtifactSha256', 'snapshotDigest', 'snapshotReceiptDigest', 'architectureContractDigest', 'mergeLeaseDigest', 'architectureLedgerDigest']) requireValue(SHA256.test(String(value[key])), `Merge preparation ${key} is invalid`);
+  validateManifest(value.beforeFullManifest);
+  const source = value.sourceFiles?.map(file => ({ ...file, exists: true })); validateManifest(source, true);
+  validateManifest(value.targetFiles); validateMapping(value, source);
+  const mappedPaths = source.map(file => file.path);
+  const mappedBefore = value.beforeFullManifest.filter(file => mappedPaths.includes(file.path));
+  requireValue(canonicalEqual(value.targetFiles, mappedBefore), 'Merge target batch differs from its wide frozen target');
+  const nativeFiles = source.map(({ path, sha256 }) => ({ path, sha256 }));
+  requireValue(canonicalEqual(value.afterManifest, nativeFiles) && value.mergedArtifactSha256 === mergeArtifactSha256(nativeFiles), 'Merge actual artifact hash or manifest is inconsistent');
+  requireValue(canonicalEqual(mappedPaths, value.targetFiles.map(file => file.path)), 'Merge source and target batch path sets differ');
+  const changed = source.filter(({ sourcePath, ...file }, index) => !canonicalEqual(file, value.targetFiles[index])).map(file => file.path);
+  requireValue(changed.length > 0 && canonicalEqual(value.paths, changed), 'Merge requires exact nonempty actual changes');
+  requireValue(source.some((file, index) => !value.targetFiles[index].exists || file.sha256 !== value.targetFiles[index].sha256), 'Merge requires actual nonempty byte changes; modes alone cannot authorize it');
+  validateRef(value.sourceRef, 'source', value, source); validateRef(value.targetRef, 'target', value, value.beforeFullManifest);
+  requireValue(value.sourceRef.artifactId !== value.targetRef.artifactId, 'Merge source and target refs must be distinct');
+  for (const key of ['mergeId', 'taskId', 'ownerId', 'leaseId']) requireValue(idValid(value[key]), `Merge ${key} is invalid`);
+  for (const key of ['taskDigest', 'chainDigest']) requireValue(SHA256.test(String(value[key])), `Merge ${key} is invalid`);
+  requireValue(Number.isSafeInteger(value.generation) && value.generation > 0 && Number.isSafeInteger(value.epoch) && value.epoch >= 0, 'Merge lease generation or epoch is invalid');
+  requireValue(canonicalEqual(value.scopePaths, value.beforeFullManifest.map(file => file.path)), 'Merge preparation must cover its entire wide original snapshot');
+  if (Object.hasOwn(value, 'handoffEpoch')) requireValue(Number.isSafeInteger(value.handoffEpoch) && value.handoffEpoch >= 0, 'Merge handoff epoch is invalid');
+}
+function requireBinding(value, binding, fields) {
+  for (const key of fields) if (Object.hasOwn(binding, key)) requireValue(canonicalEqual(value[key], binding[key]), `Merge frozen ${key} binding does not match`);
+}
+export function inspectMergePreparation(preparation, binding = {}, options = {}) {
+  const signed = inspectMergeSignedEnvelope(preparation, { ...options, schemaVersion: MERGE_PREPARATION_SCHEMA,
+    publicKey: options.publicKey ?? process.env.ENTROROVE_TASK_HANDOFF_RUNNER_PUBLIC_KEY?.trim() });
+  if (!signed.verified) return signed;
+  try {
+    validatePreparation(preparation); requireBinding(preparation, binding, [...CONTEXT_FIELDS, ...LEASE_CONTEXT, ...OPTIONAL_CONTEXT]);
+    return { ...signed, preparation };
+  } catch (error) { return { verified: false, reason: error instanceof Error ? error.message : String(error) }; }
+}
+function validateNativeCheckpoint(result, source, target, preflight) {
+  const { checkpoint, ledgerEntry } = result;
+  requireValue(result.path === source.path && result.sourcePath === source.sourcePath && result.sha256 === source.sha256 && result.beforeSha256 === target.sha256
+    && result.contentSha256 === source.sha256 && result.exists === true, 'Archguard checkpoint input is not the actual frozen artifact');
+  requireValue(checkpoint && ['passed', 'blocked'].includes(checkpoint.status) && typeof checkpoint.writeAllowed === 'boolean'
+    && typeof checkpoint.rollbackRequired === 'boolean' && checkpoint.writeAllowed === !checkpoint.rollbackRequired
+    && (checkpoint.status === 'passed') === checkpoint.writeAllowed, 'Archguard checkpoint verdict is inconsistent');
+  requireValue(ledgerEntry?.schemaVersion === 'archguard.checkpoint-ledger/1.0' && SHA256.test(String(ledgerEntry.checkpointId))
+    && idValid(ledgerEntry.blockId) && ledgerEntry.path === source.path && ledgerEntry.beforeSha256 === target.sha256
+    && ledgerEntry.afterSha256 === source.sha256 && ledgerEntry.contractRevision === preflight.contractRevision
+    && ledgerEntry.status === checkpoint.status && ledgerEntry.rollbackRequired === checkpoint.rollbackRequired, 'Archguard native ledger does not bind the exact checkpoint');
+  const metrics = checkpoint.metrics;
+  requireValue(metrics?.path === source.path && typeof metrics.complexityChecked === 'boolean'
+    && ['first-party', 'third-party', 'generated', 'dependency-lockfile'].includes(metrics.inspectionScope)
+    && ['fileLines', 'maxNestingDepth', 'maxFunctionLines', 'animations', 'transitions'].every(key => Number.isSafeInteger(metrics[key]) && metrics[key] >= 0), 'Archguard native metrics are missing or invalid');
+  requireValue(Array.isArray(checkpoint.findings) && checkpoint.findings.every(finding => finding && typeof finding.blocking === 'boolean'
+    && typeof finding.ruleId === 'string' && finding.ruleId && finding.entityRef === source.path && ['P0', 'P1', 'P2'].includes(finding.severity)), 'Archguard native findings are malformed');
+  const rules = [...new Set(checkpoint.findings.map(finding => finding.ruleId))].sort();
+  const blocking = [...new Set(checkpoint.findings.filter(finding => finding.blocking).map(finding => finding.ruleId))].sort();
+  requireValue(canonicalEqual(ledgerEntry.ruleIds, rules) && canonicalEqual(ledgerEntry.blockingRuleIds, blocking)
+    && (!blocking.length || checkpoint.status === 'blocked'), 'Archguard native rule verdicts disagree');
+  requireValue(checkpoint.drift && ['green', 'yellow', 'red'].includes(checkpoint.drift.trend)
+    && (checkpoint.drift.trend !== 'red' || checkpoint.status === 'blocked'), 'Archguard native drift verdict is invalid');
+}
+export function inspectMergeArchguardPreflight(preflight, binding = {}, options = {}) {
+  const signed = inspectMergeSignedEnvelope(preflight, { ...options, schemaVersion: MERGE_ARCHGUARD_SCHEMA });
+  if (!signed.verified) return signed;
+  try {
+    const preparation = options.preparation;
+    const prepared = inspectMergePreparation(preparation, binding, { publicKey: options.preparationPublicKey, now: options.now,
+      consumedNonces: options.consumedPreparationNonces ?? options.consumedNonces });
+    requireValue(prepared.verified, prepared.reason ?? 'Original merge preparation is required');
+    const lease = options.mergeLease;
+    const leased = inspectMergeSignedEnvelope(lease, { schemaVersion: 'entrorove.merge-lease/1.0', now: options.now,
+      publicKey: options.authorityPublicKey ?? process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY?.trim(),
+      consumedNonces: options.consumedLeaseNonces ?? options.consumedNonces });
+    requireValue(leased.verified, leased.reason ?? 'Original signed merge lease is required');
+    const leaseFields = [...LEASE_CONTEXT, 'repositoryDigest', 'flowId', 'stepId', 'baselineRef', 'architectureContractDigest', 'mappings', 'mappingProof', 'mappingDigest'];
+    requireValue(leaseFields.every(key => Object.hasOwn(lease, key)), 'Original merge lease fields are missing');
+    requireBinding(preparation, lease, leaseFields);
+    requireValue(canonicalEqual(preparation.sourceFiles.map(file => file.path), lease.paths) && SHA256.test(String(lease.architectureLedgerDigest))
+      && preparation.mergeLeaseDigest === leased.receiptDigest && preparation.architectureLedgerDigest === lease.architectureLedgerDigest
+      && preflight.mergeLeaseDigest === leased.receiptDigest && preflight.architectureLedgerDigest === lease.architectureLedgerDigest
+      && lease.mappingProof.planId === lease.planId && lease.mappingProof.planDigest === lease.planDigest
+      && SHA256.test(String(lease.scopeContractArtifactDigest)) && lease.mappingProof.scopeArtifactDigest === lease.scopeContractArtifactDigest
+      && preflight.scopeContractArtifactDigest === lease.scopeContractArtifactDigest,
+    'Archguard original authority lease or frozen architecture ledger binding is invalid');
+    const expected = mergePreflightBinding(preparation);
+    requireBinding(preflight, expected, Object.keys(expected)); requireBinding(preflight, binding, [...Object.keys(expected), 'contractRawDigest', 'contractRevision', 'contractId', 'nativeLedgerHeadDigest']);
+    requireValue(preflight.nativeRuntimeSha256 === MERGE_ARCHGUARD_RUNTIME_SHA256 && preflight.architectureContract?.schemaVersion === 'archguard.contract/1.0'
+      && mergeSha256(mergeCanonical(preflight.architectureContract)) === preflight.architectureContractDigest
+      && preflight.contractId === preflight.architectureContract.contractId && preflight.contractRevision === preflight.architectureContract.revision
+      && Number.isSafeInteger(preflight.contractRevision) && preflight.contractRevision > 0 && SHA256.test(String(preflight.contractRawDigest))
+      && SHA256.test(String(preflight.nativeLedgerHeadDigest)), 'Archguard locked native contract or actual native ledger head is missing or inconsistent');
+    requireValue(Date.parse(preflight.expiresAt) <= Math.min(Date.parse(preparation.expiresAt), Date.parse(lease.expiresAt))
+      && Date.parse(preflight.issuedAt) >= Math.max(Date.parse(preparation.issuedAt), Date.parse(lease.issuedAt)), 'Archguard preflight outlives its original frozen preparation or lease');
+    requireValue(Array.isArray(preflight.results) && preflight.results.length === preparation.sourceFiles.length, 'Every actual output file requires its own native checkpoint');
+    preflight.results.forEach((result, index) => validateNativeCheckpoint(result, preparation.sourceFiles[index], preparation.targetFiles[index], preflight));
+    const passed = preflight.results.every(result => result.checkpoint.status === 'passed');
+    requireValue(preflight.status === (passed ? 'passed' : 'blocked'), 'Archguard preflight summary disagrees with native checkpoints');
+    return { ...signed, verified: passed, authentic: true, status: preflight.status, preflight,
+      ...(passed ? {} : { reason: 'Actual native Archguard checkpoint blocked the merge' }) };
+  } catch (error) { return { verified: false, reason: error instanceof Error ? error.message : String(error) }; }
+}

package/local-merge-archguard.mjs

@@ -0,0 +1,138 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { context, authority, readBytes, readLedger, withExclusiveLock, fail } from './local-archguard-state.mjs';
+import { contractFile, loadContractLock } from './local-archguard-contract.mjs';
+import { history, drift } from './local-archguard-snapshot.mjs';
+import { evaluateArchguardCheckpoint } from './local-archguard-evaluate.mjs';
+import { signRunnerReceipt } from './local-archguard-signing.mjs';
+import { readFrozenMergeArtifact } from './local-merge-artifacts.mjs';
+import { context as mergeContext, withMergeFence } from './local-merge-storage.mjs';
+import { inspectMergeLease } from './local-merge-authority.mjs';
+import { configuredMergePin, inspectMergePreparation, inspectMergeArchguardPreflight, mergePreflightBinding,
+  mergeCanonical, mergeSha256, SHA256, MERGE_ARCHGUARD_SCHEMA, MERGE_ARCHGUARD_RUNTIME_SHA256 } from './local-merge-archguard-verification.mjs';
+
+const equal = (left, right) => mergeCanonical(left) === mergeCanonical(right);
+function requireValue(condition, code, message) { if (!condition) fail(code, message); }
+
+async function lockedContract(ctx, expected) {
+  const current = await contractFile(ctx), locked = await loadContractLock(ctx);
+  requireValue(locked.usedConfirmations?.length > 0 && locked.repositoryDigest === ctx.repositoryDigest
+    && current.contractDigest === locked.contractDigest && current.rawDigest === locked.rawDigest
+    && current.contract.revision === locked.revision && current.contractDigest === expected,
+  'MERGE_ARCH_CONTRACT', 'Merge preflight requires the unchanged explicitly confirmed original architecture contract');
+  return current;
+}
+async function artifacts(input, preparation) {
+  const source = await readFrozenMergeArtifact(input, preparation.sourceRef);
+  const target = await readFrozenMergeArtifact(input, preparation.targetRef);
+  const after = source.manifest.files.map(({ exists, ...file }) => file);
+  requireValue(source.manifest.role === 'source' && target.manifest.role === 'target'
+    && source.manifest.files.every(file => file.exists) && equal(after, preparation.sourceFiles)
+    && equal(target.manifest.files, preparation.beforeFullManifest),
+  'MERGE_ARCH_ARTIFACT', 'Archguard reads only the exact frozen source and target manifests');
+  return { source, target };
+}
+async function assertTarget(ctx, expected) {
+  for (const file of expected) {
+    const actual = await readBytes(path.join(ctx.root, file.path), !file.exists, ctx);
+    requireValue(actual.exists === file.exists && (!file.exists || mergeSha256(actual.content) === file.sha256 && actual.mode === file.mode),
+      'MERGE_ARCH_TARGET_CHANGED', 'Actual target differs from its frozen original merge snapshot');
+  }
+}
+async function scanCandidate(current, source, target, previous) {
+  const results = [], entries = [...previous], decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+  const before = new Map(target.files.map(file => [file.path, file]));
+  for (const [index, file] of source.files.entries()) {
+    const content = decoder.decode(file.bytes);
+    requireValue(mergeSha256(Buffer.from(content)) === file.sha256, 'MERGE_ARCH_ENCODING', 'Archguard requires unchanged valid UTF-8 source bytes');
+    const result = await evaluateArchguardCheckpoint(current.contract, { blockId: `merge-${index + 1}`, path: file.path,
+      content, beforeSha256: before.get(file.path).sha256 }, entries);
+    entries.push(result.ledgerEntry);
+    results.push({ path: file.path, exists: true, sha256: file.sha256, contentSha256: file.sha256,
+      sourcePath: file.sourcePath, beforeSha256: before.get(file.path).sha256, ...result });
+  }
+  return results;
+}
+async function produceLocked(ctx, input, lease) {
+  const preparation = input.preparation, pin = configuredMergePin(process.env.ENTROROVE_ARCHGUARD_RUNNER_PUBLIC_KEY?.trim()), config = await authority(ctx);
+  requireValue(config.runnerPublicKey === pin.publicKey, 'MERGE_ARCH_RUNNER_PIN', 'Original Archguard runner signer must match the independently configured preflight pin');
+  const binding = { repositoryDigest: ctx.repositoryDigest, flowId: ctx.flowId, stepId: input.stepId,
+    ...Object.fromEntries(['mergeId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'leaseId', 'generation', 'epoch', 'architectureContractDigest', 'baselineRef'].map(key => [key, lease[key]])),
+    mappings: lease.mappings, mappingProof: lease.mappingProof, mappingDigest: lease.mappingDigest, scopePaths: lease.scopePaths };
+  const prepared = inspectMergePreparation(preparation, binding);
+  requireValue(prepared.verified, 'MERGE_ARCH_PREPARATION', prepared.reason ?? 'Original signed merge preparation is required');
+  const current = await lockedContract(ctx, preparation.architectureContractDigest), ledger = await readLedger(ctx);
+  requireValue(SHA256.test(String(ledger.headDigest)), 'MERGE_ARCH_LEDGER_UNMANAGED', 'Merge preflight requires an actual managed native ledger head');
+  requireValue(!drift(ledger).interrupted, 'MERGE_ARCH_RED_INTERRUPT', 'Archguard red interrupt requires trusted human direction before preflight');
+  const frozen = await artifacts(input, preparation); await assertTarget(ctx, frozen.target.files);
+  const results = await scanCandidate(current, frozen.source, frozen.target, history(ledger));
+  const fresh = await artifacts(input, preparation); await assertTarget(ctx, fresh.target.files);
+  const unchanged = await lockedContract(ctx, preparation.architectureContractDigest), latest = await readLedger(ctx);
+  requireValue(fresh.source.files.every((file, index) => file.bytes.equals(frozen.source.files[index].bytes))
+    && unchanged.rawDigest === current.rawDigest && latest.headDigest === ledger.headDigest,
+  'MERGE_ARCH_SCAN_RACE', 'Frozen artifacts, architecture contract or checkpoint history changed during actual scan');
+  requireValue(inspectMergePreparation(preparation, binding).verified, 'MERGE_ARCH_PREPARATION_EXPIRED', 'Original preparation expired during actual Archguard scan');
+  const now = Date.now(), expires = Math.min(Date.parse(preparation.expiresAt), Date.parse(lease.expiresAt), now + 60_000);
+  const payload = { schemaVersion: MERGE_ARCHGUARD_SCHEMA, ...mergePreflightBinding(preparation),
+    status: results.every(result => result.checkpoint.status === 'passed') ? 'passed' : 'blocked',
+    architectureContract: current.contract, contractId: current.contract.contractId, contractRevision: current.contract.revision,
+    contractRawDigest: current.rawDigest, nativeLedgerHeadDigest: ledger.headDigest, nativeRuntimeSha256: MERGE_ARCHGUARD_RUNTIME_SHA256, results,
+    mergeLeaseDigest: mergeSha256(mergeCanonical(lease)), architectureLedgerDigest: lease.architectureLedgerDigest,
+    scopeContractArtifactDigest: lease.scopeContractArtifactDigest,
+    issuedAt: new Date(now).toISOString(), expiresAt: new Date(expires).toISOString(), nonce: randomUUID() };
+  const signed = await signRunnerReceipt(ctx, payload, true);
+  const checked = inspectMergeArchguardPreflight(signed, binding, { preparation, mergeLease: lease });
+  requireValue(checked.authentic, 'MERGE_ARCH_OUTPUT_INVALID', checked.reason ?? 'Produced native Archguard receipt failed its own independent inspection');
+  return signed;
+}
+
+export async function produceMergeArchguardPreflight(input) {
+  const merge = await mergeContext(input);
+  return withMergeFence(merge, async (state, registration) => {
+    const lease = inspectMergeLease(input.mergeLease, merge, state, registration), ctx = await context(input);
+    return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), () =>
+      withExclusiveLock(path.join(ctx.directory, 'mutation.lock'), () => produceLocked(ctx, input, lease)));
+  });
+}
+
+async function nativeCurrent(ctx, binding) {
+  requireValue(binding && typeof binding === 'object' && !Array.isArray(binding), 'MERGE_ARCH_CONTRACT', 'Original architecture binding is required');
+  requireValue(SHA256.test(String(binding.architectureContractDigest)), 'MERGE_ARCH_CONTRACT', 'Original canonical architecture binding is required');
+  const current = await lockedContract(ctx, binding.architectureContractDigest), ledger = await readLedger(ctx);
+  requireValue(!drift(ledger).interrupted, 'MERGE_ARCH_RED_INTERRUPT', 'Native Archguard red interrupt prohibits a merge or rollback commit');
+  requireValue(SHA256.test(String(ledger.headDigest)), 'MERGE_ARCH_LEDGER_UNMANAGED', 'Actual managed native ledger head is required');
+  if (Object.hasOwn(binding, 'contractRawDigest')) requireValue(current.rawDigest === binding.contractRawDigest,
+    'MERGE_ARCH_CONTRACT', 'Actual architecture raw bytes changed after their original preflight');
+  if (Object.hasOwn(binding, 'nativeLedgerHeadDigest')) requireValue(ledger.headDigest === binding.nativeLedgerHeadDigest,
+    'MERGE_ARCH_LEDGER_CHANGED', 'Actual native checkpoint history changed after its original frozen head');
+  return { architectureContractDigest: current.contractDigest, contractRawDigest: current.rawDigest, nativeLedgerHeadDigest: ledger.headDigest };
+}
+
+// Caller already holds the physical handoff and merge repository fences. Invoke
+// assertCurrent inside the atomic finish/recovery boundary before publishing.
+export async function withMergeArchguardStateFence(input, binding, action) {
+  requireValue(typeof action === 'function', 'MERGE_ARCH_ACTION', 'Native architecture fence requires its original action');
+  const ctx = await context(input);
+  return withExclusiveLock(path.join(ctx.repositoryState, 'mutation.lock'), () =>
+    withExclusiveLock(path.join(ctx.directory, 'mutation.lock'), async () => {
+      const facts = Object.freeze(await nativeCurrent(ctx, binding));
+      const assertCurrent = async () => { await nativeCurrent(ctx, facts); };
+      return action(assertCurrent, facts);
+    }));
+}
+
+export async function withMergeArchguardFence(input, preflight, action) {
+  requireValue(typeof action === 'function', 'MERGE_ARCH_ACTION', 'Native architecture fence requires its original action');
+  const ctx = await context(input), binding = { repositoryDigest: ctx.repositoryDigest, flowId: ctx.flowId, stepId: input.stepId };
+  const assertReceipt = () => {
+    const checked = inspectMergeArchguardPreflight(preflight, binding, { preparation: input.preparation, mergeLease: input.mergeLease });
+    requireValue(checked.verified && checked.authentic, 'MERGE_ARCH_PREFLIGHT', checked.reason ?? 'Original independent passing native preflight is required');
+  };
+  assertReceipt();
+  return withMergeArchguardStateFence(input, preflight, async assertNativeCurrent => {
+    const pin = configuredMergePin(process.env.ENTROROVE_ARCHGUARD_RUNNER_PUBLIC_KEY?.trim()), config = await authority(ctx);
+    requireValue(config.runnerPublicKey === pin.publicKey, 'MERGE_ARCH_RUNNER_PIN', 'Original native runner authority differs from its independent pin');
+    const assertCurrent = async () => { assertReceipt(); await assertNativeCurrent(); };
+    await assertCurrent(); return action(assertCurrent);
+  });
+}

package/local-merge-artifacts.mjs

@@ -0,0 +1,86 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { snapshotAuthority14 } from './local-mutation-snapshot.mjs';
+import { canonical, sha256, fail, identifier, paths, noLinks, MISSING_SHA256, context, withMergeFence, directory, read, json, writeJson } from './local-merge-storage.mjs';
+import { inspectMergeLease, signMergeReceipt } from './local-merge-authority.mjs';
+import { assertDistinctMergeTargets } from './local-merge-targets.mjs';
+
+export const mergeArtifactDigest = files => sha256(`validator.file-manifest/1.0\n${files.map(file => `${file.path}\0${file.sha256}`).join('\n')}`);
+const entry = (name, value) => ({ path: name, exists: value.exists, sha256: value.sha256, mode: value.mode });
+export async function readMergeSnapshot(ctx, receipt) {
+  const value = await snapshotAuthority14(ctx.input, ctx.root, receipt);
+  return { manifest: value.manifest, directory: value.snapshotRoot };
+}
+async function freeze(ctx, role, root, names, mappings = []) {
+  const artifactId = `${role}-${randomUUID()}`, directoryPath = path.join(ctx.state, 'artifacts', artifactId);
+  await directory(path.join(directoryPath, 'blobs')); const files = []; let total = 0;
+  for (const name of names) {
+    const sourcePath = role === 'source' ? mappings.find(item => item.targetPath === name).sourcePath : name;
+    const value = await read(path.join(root, sourcePath), ctx.input, sourcePath, role === 'target');
+    total += value.bytes?.length ?? 0; if (total > 64 * 1024 * 1024) fail('MERGE_ARTIFACT_LIMIT', 'Merge artifact exceeds its bounded byte quota');
+    if (value.exists) {
+      const blob = path.join(directoryPath, 'blobs', value.sha256);
+      try { await fs.writeFile(blob, value.bytes, { flag: 'wx', mode: 0o600 }); }
+      catch (error) { if (error.code !== 'EEXIST') throw error;
+        if (!(await read(blob, ctx.input, sourcePath)).bytes.equals(value.bytes)) fail('MERGE_BLOB_CHANGED', 'Duplicate artifact blob differs from its actual bytes'); }
+    }
+    files.push({ ...entry(name, value), ...(role === 'source' ? { sourcePath } : {}) });
+  }
+  const manifest = { schemaVersion: 'entrorove.merge-artifact/1.0', artifactId, role, repositoryDigest: ctx.repo, flowId: ctx.flowId, stepId: ctx.stepId, files };
+  await writeJson(path.join(directoryPath, 'manifest.json'), manifest);
+  return { ref: { kind: 'snapshot', artifactId, manifestDigest: sha256(canonical(manifest)) }, manifest };
+}
+export async function readFrozenMergeArtifact(input, ref) {
+  const ctx = await context(input);
+  if (!ref || ref.kind !== 'snapshot' || !/^[0-9a-f]{64}$/.test(ref.manifestDigest ?? '')) fail('MERGE_REF_INVALID', 'Merge refs must identify frozen private snapshot manifests');
+  const directoryPath = path.join(ctx.state, 'artifacts', identifier(ref.artifactId)), manifest = await json(path.join(directoryPath, 'manifest.json'));
+  if (Object.keys(ref).sort().join('|') !== 'artifactId|kind|manifestDigest'
+    || Object.keys(manifest).sort().join('|') !== 'artifactId|files|flowId|repositoryDigest|role|schemaVersion|stepId'
+    || !['source', 'target'].includes(manifest.role) || manifest.schemaVersion !== 'entrorove.merge-artifact/1.0' || manifest.artifactId !== ref.artifactId || manifest.repositoryDigest !== ctx.repo
+    || manifest.flowId !== ctx.flowId || manifest.stepId !== ctx.stepId || sha256(canonical(manifest)) !== ref.manifestDigest
+    || canonical(paths(manifest.files.map(file => file.path))) !== canonical(manifest.files.map(file => file.path))) fail('MERGE_REF_CHANGED', 'Frozen merge manifest or reference changed');
+  const files = [];
+  for (const file of manifest.files) {
+    if (manifest.role === 'source') paths([file.sourcePath]);
+    if (Object.keys(file).sort().join('|') !== (manifest.role === 'source' ? 'exists|mode|path|sha256|sourcePath' : 'exists|mode|path|sha256')
+      || typeof file.exists !== 'boolean' || !/^[0-9a-f]{64}$/.test(file.sha256 ?? '')
+      || file.exists && (!Number.isInteger(file.mode) || file.mode < 0 || file.mode > 0o777)
+      || !file.exists && (file.sha256 !== MISSING_SHA256 || file.mode !== null)
+      || manifest.role === 'source' && !file.exists) fail('MERGE_REF_CHANGED', 'Frozen merge file metadata is invalid');
+    const value = file.exists ? await read(path.join(directoryPath, 'blobs', file.sha256), ctx.input, file.sourcePath ?? file.path) : { bytes: null };
+    if (file.exists && value.sha256 !== file.sha256) fail('MERGE_BLOB_CHANGED', 'Frozen merge blob differs from its signed actual digest');
+    files.push({ ...file, bytes: value.bytes });
+  }
+  return { manifest, files };
+}
+export async function prepareMergeArtifacts(input) {
+  const ctx = await context(input);
+  return withMergeFence(ctx, async (state, registration) => {
+    const lease = inspectMergeLease(input.mergeLease, ctx, state, registration);
+    const snapshot = await readMergeSnapshot(ctx, input.snapshotReceipt), scopePaths = paths(snapshot.manifest.paths), names = paths(lease.mappings.map(item => item.targetPath));
+    if (canonical(scopePaths) !== canonical(lease.scopePaths)
+      || snapshot.manifest.contractDigest !== lease.architectureContractDigest) fail('MERGE_SCOPE_CHANGED', 'Frozen merge scope and architecture must exactly match its original signed lease and snapshot');
+    const suppliedSourceRoot = input.sourceRoot ?? ctx.root; await noLinks(suppliedSourceRoot); const sourceRoot = await fs.realpath(suppliedSourceRoot);
+    if (sourceRoot !== ctx.root) fail('MERGE_SOURCE_ORIGIN', 'Merge candidate origins must retain the original registered repository');
+    await assertDistinctMergeTargets(ctx.input, scopePaths.map(path => ({ path })));
+    const target = await freeze(ctx, 'target', ctx.root, scopePaths), source = await freeze(ctx, 'source', sourceRoot, names, lease.mappings);
+    if (canonical(target.manifest.files) !== canonical(snapshot.manifest.files)) fail('MERGE_TARGET_CHANGED', 'Merge target changed from its frozen original snapshot');
+    const targetFiles = target.manifest.files.filter(file => names.includes(file.path));
+    const changed = names.filter((name, index) => { const { sourcePath, ...file } = source.manifest.files[index]; return canonical(file) !== canonical(targetFiles[index]); });
+    if (!changed.length) fail('MERGE_CHANGES_REQUIRED', 'Merge requires nonempty actual file changes');
+    const sourceFiles = source.manifest.files.map(({ exists, ...file }) => file);
+    if (sourceFiles.some(file => !lease.mappingProof.entries.some(entry => entry.sourcePath === file.sourcePath && entry.targetPath === file.path && entry.sha256 === file.sha256))) {
+      fail('MERGE_SOURCE_ANCESTRY', 'Actual candidate source differs from its frozen native producer mapping proof');
+    }
+    return signMergeReceipt(ctx.input, { schemaVersion: 'entrorove.merge-preparation-receipt/1.0', repositoryDigest: ctx.repo,
+      flowId: ctx.flowId, stepId: ctx.stepId, baselineRef: lease.baselineRef, sourceRef: source.ref, targetRef: target.ref, paths: changed,
+      ...Object.fromEntries(['mergeId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest', 'leaseId', 'generation', 'epoch'].map(field => [field, lease[field]])),
+      mergeLeaseDigest: sha256(canonical(lease)), architectureLedgerDigest: lease.architectureLedgerDigest,
+      scopePaths,
+      mappings: lease.mappings, mappingDigest: lease.mappingDigest, mappingProof: lease.mappingProof,
+      sourceFiles, targetFiles, mergedArtifactSha256: mergeArtifactDigest(sourceFiles), snapshotDigest: input.snapshotReceipt.snapshotDigest,
+      afterManifest: sourceFiles.map(({ path, sha256 }) => ({ path, sha256 })), beforeFullManifest: target.manifest.files,
+      snapshotReceiptDigest: input.snapshotReceipt.receiptDigest, architectureContractDigest: input.snapshotReceipt.contractDigest });
+  });
+}