fix(ql3): bind evolved reconciliation target

Author: whyour

packages/ql3-local-owner-cli/src/deployment/reconciliation/application/secret-and-config/application/contract.ts

@@ -223,12 +223,25 @@ function normalizeOptions(
       fail('authentication or Secret material must be below deploymentRoot');
     }
   }
+  const targetRelative = path.relative(
+    normalized.deploymentRoot,
+    normalized.targetDatabasePath,
+  );
+  if (
+    !targetRelative ||
+    targetRelative.startsWith('..') ||
+    path.isAbsolute(targetRelative)
+  ) {
+    fail('targetDatabasePath must be below deploymentRoot');
+  }
   if (
-    roots.some(
-      (root) =>
-        overlaps(root, normalized.targetDatabasePath) ||
-        overlaps(normalized.targetDatabasePath, root),
-    )
+    roots
+      .slice(1)
+      .some(
+        (root) =>
+          overlaps(root, normalized.targetDatabasePath) ||
+          overlaps(normalized.targetDatabasePath, root),
+      )
   ) {
     fail('targetDatabasePath overlaps an authority root');
   }

packages/ql3-local-owner-cli/src/deployment/reconciliation/application/secret-and-config/application/coordinator.ts

@@ -338,6 +338,14 @@ export async function applyLocalReconciliationSecretConfig(
   ) {
     fail('apply command is detached from a ready signed decision');
   }
+  const targetSnapshotSha256 = terminal.context.planHeader.targetSnapshotSha256;
+  if (terminal.receipt.applyBindingCount > 0 && targetSnapshotSha256 === null) {
+    fail('active binding plan is missing evolved target authority');
+  }
+  const stoppedProofOptions =
+    targetSnapshotSha256 === null
+      ? {}
+      : { expectedEvolvedTargetSha256: targetSnapshotSha256 };
   const planTerminal = terminal.context.planTerminal;
   const capture = readLocalReconciliationCaptureIntent(
     planTerminal.intent.command.options.captureRoot,
@@ -375,7 +383,11 @@ export async function applyLocalReconciliationSecretConfig(
       fail('apply lost reviewed head compare-and-swap');
     }
     discardUnpreparedLocalReconciliationSecretConfigMaterials(selected);
-    const before = proveLocalReconciliationStoppedState(capture.command, uid);
+    const before = proveLocalReconciliationStoppedState(
+      capture.command,
+      uid,
+      stoppedProofOptions,
+    );
     const materials: Readonly<PreparedReconciliationSecretConfigMaterial>[] =
       [];
     const openRequirements =
@@ -441,7 +453,11 @@ export async function applyLocalReconciliationSecretConfig(
         ? {}
         : { busyTimeoutMs: command.options.busyTimeoutMs }),
     });
-    const after = proveLocalReconciliationStoppedState(capture.command, uid);
+    const after = proveLocalReconciliationStoppedState(
+      capture.command,
+      uid,
+      stoppedProofOptions,
+    );
     if (after.proofDigest !== before.proofDigest) {
       fail('stopped target drifted across preparation');
     }
@@ -522,7 +538,11 @@ export async function applyLocalReconciliationSecretConfig(
     fail('apply lost prepared head compare-and-swap');
   }
   if (!recoveringPreparedIntent) {
-    const stopped = proveLocalReconciliationStoppedState(capture.command, uid);
+    const stopped = proveLocalReconciliationStoppedState(
+      capture.command,
+      uid,
+      stoppedProofOptions,
+    );
     if (stopped.proofDigest !== intent.stoppedProofDigest) {
       fail('stopped proof drifted before write');
     }

packages/ql3-local-owner-cli/src/deployment/reconciliation/application/secret-and-config/coordinator.ts

@@ -614,6 +614,7 @@ function publishPlan(
   authority: Readonly<SecretConfigReviewAuthority>,
   dependencies: LocalReconciliationSecretConfigPlanDependencies,
   uid: number,
+  targetSnapshotSha256: string | null,
   automationTarget?: DatabaseSync,
 ): Readonly<LocalReconciliationSecretConfigPlanReceipt> {
   let descriptor: number | undefined;
@@ -649,6 +650,7 @@ function publishPlan(
       projectId: command.request.projectId,
       tableDisposition: authority.tableDisposition,
       unadaptedLegacyConfigCount: authority.unadaptedLegacyConfigCount,
+      targetSnapshotSha256,
       preparedHeadDigest: head.headDigest,
       preparedAtMs: command.request.preparedAtMs,
     });
@@ -987,6 +989,7 @@ export async function planLocalReconciliationSecretConfig(
       authority,
       dependencies,
       identity.uid,
+      automationTarget?.snapshotSha256 ?? null,
       target,
     );
   const receipt =

packages/ql3-local-owner-cli/src/deployment/reconciliation/application/secret-and-config/planReader.ts

@@ -226,6 +226,7 @@ function header(
       'schemaVersion',
       'secretConfigId',
       'tableDisposition',
+      'targetSnapshotSha256',
       'unadaptedLegacyConfigCount',
     ],
     'header',
@@ -244,6 +245,9 @@ function header(
     record.projectId.length < 1 ||
     (record.tableDisposition !== 'absent' &&
       record.tableDisposition !== 'manual_external') ||
+    (record.targetSnapshotSha256 !== null &&
+      (typeof record.targetSnapshotSha256 !== 'string' ||
+        !DIGEST_PATTERN.test(record.targetSnapshotSha256))) ||
     !Number.isSafeInteger(record.unadaptedLegacyConfigCount) ||
     (record.unadaptedLegacyConfigCount as number) < 0 ||
     ![

packages/ql3-local-owner-cli/src/deployment/reconciliation/application/secret-and-config/rowPlan.ts

@@ -54,6 +54,7 @@ export interface LocalReconciliationSecretConfigPlanHeader {
   readonly projectId: string;
   readonly tableDisposition: 'absent' | 'manual_external';
   readonly unadaptedLegacyConfigCount: number;
+  readonly targetSnapshotSha256: string | null;
   readonly preparedHeadDigest: string;
   readonly preparedAtMs: number;
   readonly headerDigest: string;
@@ -350,11 +351,7 @@ function targetAutomationAdoptionProjection(
           /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
         ),
         planDigest: adoptionText(row, 'planDigest', DIGEST_PATTERN),
-        inventoryDigest: adoptionText(
-          row,
-          'inventoryDigest',
-          DIGEST_PATTERN,
-        ),
+        inventoryDigest: adoptionText(row, 'inventoryDigest', DIGEST_PATTERN),
         decisionDigest: adoptionText(row, 'decisionDigest', DIGEST_PATTERN),
         receiptDigest: adoptionText(row, 'receiptDigest', DIGEST_PATTERN),
         authorizationFileDigest: adoptionText(
@@ -372,11 +369,7 @@ function targetAutomationAdoptionProjection(
         adoptedTriggerCount: selectedAdoptedTriggerCount,
         skippedCount,
         auditEventId: adoptionText(row, 'auditEventId', UUID_V4_PATTERN),
-        createdAtMs: adoptionCount(
-          row,
-          'createdAtMs',
-          Number.MAX_SAFE_INTEGER,
-        ),
+        createdAtMs: adoptionCount(row, 'createdAtMs', Number.MAX_SAFE_INTEGER),
       });
       if (payload.auditEventId !== payload.mutationId) {
         fail('target Automation adoption audit binding drifted');
@@ -1048,8 +1041,7 @@ export function buildLocalReconciliationSecretConfigPlanReceipt(
     adoptedLegacyTriggerCount: footer.adoptedLegacyTriggerCount,
     adoptionProvenanceTaskCount: footer.adoptionProvenanceTaskCount,
     adoptionProvenanceTriggerCount: footer.adoptionProvenanceTriggerCount,
-    automationAdoptionProvenanceState:
-      footer.automationAdoptionProvenanceState,
+    automationAdoptionProvenanceState: footer.automationAdoptionProvenanceState,
     unadaptedLegacyConfigCount: footer.unadaptedLegacyConfigCount,
     outcome: footer.outcome,
     preparedAtMs: header.preparedAtMs,

packages/ql3-local-owner-cli/src/deployment/reconciliation/completion/contract.ts

@@ -342,14 +342,25 @@ function normalizeOptions(
   }
   if (
     secretConfig !== null &&
-    roots.some(
-      (root) =>
-        overlaps(root, secretConfig.targetDatabasePath) ||
-        overlaps(secretConfig.targetDatabasePath, root),
-    )
+    roots
+      .slice(1)
+      .some(
+        (root) =>
+          overlaps(root, secretConfig.targetDatabasePath) ||
+          overlaps(secretConfig.targetDatabasePath, root),
+      )
   ) {
     fail('targetDatabasePath overlaps an authority root');
   }
+  if (secretConfig !== null) {
+    const relative = path.relative(
+      normalized.deploymentRoot,
+      secretConfig.targetDatabasePath,
+    );
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+      fail('Secret/Config targetDatabasePath must be below deploymentRoot');
+    }
+  }
   if (
     automation !== null &&
     secretConfig !== null &&

packages/ql3-local-owner-cli/src/deployment/reconciliation/stoppedProof.ts

@@ -28,9 +28,14 @@ const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
 export interface LocalReconciliationStoppedProof {
   readonly stoppedRecordDigest: string;
   readonly reconciliationEvidenceDigest: string;
+  readonly evolvedTargetSha256?: string;
   readonly proofDigest: string;
 }
 
+export interface LocalReconciliationStoppedProofOptions {
+  readonly expectedEvolvedTargetSha256?: string;
+}
+
 function configurationError(message: string): never {
   throw new LocalDeploymentConfigurationError(message);
 }
@@ -63,6 +68,61 @@ function exact(
   }
 }
 
+function sameFileStat(left: fs.BigIntStats, right: fs.BigIntStats): boolean {
+  return (
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.mode === right.mode &&
+    left.nlink === right.nlink &&
+    left.uid === right.uid &&
+    left.size === right.size &&
+    left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs
+  );
+}
+
+function stableTargetSha256(filePath: string, uid: number): string {
+  let descriptor: number | undefined;
+  const buffer = Buffer.allocUnsafe(64 * 1024);
+  try {
+    const pathStat = fs.lstatSync(filePath, { bigint: true });
+    descriptor = fs.openSync(
+      filePath,
+      fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW,
+    );
+    const before = fs.fstatSync(descriptor, { bigint: true });
+    if (
+      !pathStat.isFile() ||
+      pathStat.isSymbolicLink() ||
+      !sameFileStat(pathStat, before) ||
+      before.uid !== BigInt(uid) ||
+      before.nlink !== 1n ||
+      (before.mode & 0o077n) !== 0n ||
+      fs.realpathSync(filePath) !== filePath ||
+      before.size < 1n
+    ) {
+      configurationError('evolved target database identity is invalid');
+    }
+    const hash = crypto.createHash('sha256');
+    for (;;) {
+      const count = fs.readSync(descriptor, buffer, 0, buffer.byteLength, null);
+      if (count === 0) break;
+      hash.update(buffer.subarray(0, count));
+    }
+    const after = fs.fstatSync(descriptor, { bigint: true });
+    if (!sameFileStat(before, after)) {
+      configurationError('evolved target database changed while hashing');
+    }
+    return hash.digest('hex');
+  } catch (error) {
+    if (error instanceof LocalDeploymentConfigurationError) throw error;
+    return configurationError('evolved target database is unavailable');
+  } finally {
+    buffer.fill(0);
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
 function serviceManagerStoppedPath(
   command: Readonly<LocalReconciliationCapturePrepareCommand>,
 ): string {
@@ -177,7 +237,15 @@ function serviceManagerStoppedRecord(
 export function proveLocalReconciliationStoppedState(
   command: Readonly<LocalReconciliationCapturePrepareCommand>,
   uid: number,
+  options: Readonly<LocalReconciliationStoppedProofOptions> = {},
 ): Readonly<LocalReconciliationStoppedProof> {
+  const expectedEvolvedTargetSha256 = options.expectedEvolvedTargetSha256;
+  if (
+    expectedEvolvedTargetSha256 !== undefined &&
+    !DIGEST_PATTERN.test(expectedEvolvedTargetSha256)
+  ) {
+    configurationError('evolved target snapshot digest is invalid');
+  }
   const persisted =
     command.request.stoppedAuthority === 'docker'
       ? dockerStoppedEvidence(command)
@@ -198,11 +266,42 @@ export function proveLocalReconciliationStoppedState(
     },
     uid,
   );
-  if (
-    current.disposition !== 'reconciliation_required' ||
-    (persisted !== undefined &&
-      persisted.evidenceDigest !== current.evidenceDigest)
-  ) {
+  const exactStoppedData =
+    expectedEvolvedTargetSha256 === undefined &&
+    current.disposition === 'reconciliation_required' &&
+    (persisted === undefined ||
+      persisted.evidenceDigest === current.evidenceDigest);
+  let evolvedStoppedData = false;
+  if (expectedEvolvedTargetSha256 !== undefined) {
+    const currentSha256 = stableTargetSha256(
+      command.request.targetDatabasePath,
+      uid,
+    );
+    const confirmed = readTargetDataReconciliationEvidenceForPaths(
+      {
+        profile: command.request.profile,
+        activationPath: command.request.activationPath,
+        legacySourcePath: command.request.legacySourcePath,
+        targetDatabasePath: command.request.targetDatabasePath,
+        expectedActivationDigest: command.request.expectedActivationDigest,
+        ...(adoptedTargetBaseline === undefined
+          ? {}
+          : { adoptedTargetBaseline }),
+      },
+      uid,
+    );
+    evolvedStoppedData =
+      current.disposition === 'reconciliation_required' &&
+      current.sourceMatchesActivation === true &&
+      current.sourceSidecarsClear === true &&
+      current.targetSidecarsClear === true &&
+      current.targetMatchesActivation === false &&
+      (current.baselineKind !== 'adopted_target' ||
+        current.targetMatchesBaseline === false) &&
+      currentSha256 === expectedEvolvedTargetSha256 &&
+      confirmed.evidenceDigest === current.evidenceDigest;
+  }
+  if (!exactStoppedData && !evolvedStoppedData) {
     configurationError(
       'stopped data does not have exact reconciliation-required evidence',
     );
@@ -211,6 +310,9 @@ export function proveLocalReconciliationStoppedState(
     stoppedAuthority: command.request.stoppedAuthority,
     stoppedRecordDigest: command.request.expectedStoppedRecordDigest,
     reconciliationEvidenceDigest: current.evidenceDigest,
+    ...(expectedEvolvedTargetSha256 === undefined
+      ? {}
+      : { evolvedTargetSha256: expectedEvolvedTargetSha256 }),
   });
   return Object.freeze({ ...payload, proofDigest: cutoverDigest(payload) });
 }