@dbsp/core 3.3.0 → 3.4.0

package/dist/index.js

@@ -3022,9 +3022,6 @@ function generateJoinReasoning(relation, joinType, _hasFilter) {
   return `Relation ${relation.source}.${relation.name} is optional without filter - using LEFT JOIN to preserve parent rows without matches`;
 }
 
-// src/transition/applier.ts
-import { createHash as createHash3, randomUUID } from "crypto";
-
 // src/transition/context-match.ts
 import { createHash } from "crypto";
 
@@ -3101,7 +3098,7 @@ function stableJsonInner(value, seen) {
       return `array:[${entries2.join(",")}]`;
     }
     const tag = objectTag(value);
-    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(
+    const entries = Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(
       ([key, item]) => `${JSON.stringify(key)}:${stableJsonInner(item, seen)}`
     );
     return `${tag}:{${entries.join(",")}}`;
@@ -3308,6 +3305,10 @@ function plainDataError(kind, path) {
     `a minted plan must be plain data; found ${kind} at ${path}`
   );
 }
+function isVisibleArrayIndex(value, key) {
+  const index = Number(key);
+  return String(index) === key && Number.isInteger(index) && index >= 0 && index < value.length;
+}
 function assertPlainDataAndFreeze(value, path, seen) {
   if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "undefined") {
     return;
@@ -3363,6 +3364,12 @@ function assertPlainDataAndFreeze(value, path, seen) {
     if ("get" in descriptor || "set" in descriptor) {
       throw plainDataError("accessor", childPath(path, key));
     }
+    if (isPlainObject && !descriptor.enumerable) {
+      throw plainDataError("non-enumerable property", childPath(path, key));
+    }
+    if (isPlainArray && key !== "length" && !isVisibleArrayIndex(value, key)) {
+      throw plainDataError("named array property", childPath(path, key));
+    }
     assertPlainDataAndFreeze(descriptor.value, childPath(path, key), seen);
   }
   try {
@@ -3902,8 +3909,11 @@ function assumptionAccepted(assumption, policy) {
   });
 }
 
-// src/transition/resume.ts
+// src/transition/plan-digest.ts
 import { createHash as createHash2 } from "crypto";
+function transitionPlanDigest(plan2) {
+  return createHash2("sha256").update(stableJson(plan2)).digest("hex");
+}
 
 // src/transition/transition-lessor.ts
 var TRANSITION_LESSOR_BRAND = /* @__PURE__ */ Symbol.for("dbsp.transition.lessor");
@@ -4696,8 +4706,24 @@ var RESUMER_ARTIFACT = {
   id: semanticArtifactId("dbsp.core.transition.resume"),
   version: "0.1.0"
 };
-function digest(value) {
-  return createHash2("sha256").update(stableJson(value)).digest("hex");
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object") {
+    for (const child of Object.values(value)) {
+      deepFreeze(child);
+    }
+    Object.freeze(value);
+  }
+  return value;
+}
+function snapshotLoadedRun(value) {
+  const serialized = JSON.stringify(value);
+  if (serialized === void 0) {
+    throw new Error("loaded transition journal is not JSON serializable");
+  }
+  return deepFreeze(JSON.parse(serialized));
+}
+function errorDetail(error) {
+  return error instanceof Error ? error.message : "unknown error";
 }
 function planEvidenceContext(plan2) {
   return plan2.observations.find(
@@ -4728,7 +4754,7 @@ function completedAssessment() {
     ]
   };
 }
-function contextMismatch(detail) {
+function contextMismatch(detail, journals = [], observations = []) {
   return {
     assessment: assessment(
       {
@@ -4738,11 +4764,11 @@ function contextMismatch(detail) {
         scope: [],
         detail
       },
-      "planned",
+      "outcome-unknown",
       "replan-required"
     ),
-    journals: [],
-    observations: []
+    journals,
+    observations
   };
 }
 function unacceptedStepAssumption(plan2, step, assumption) {
@@ -5116,7 +5142,7 @@ async function withObservedStep(registry, step, target, baseContext, phase, use)
       failure = error;
       observation = {
         ok: false,
-        detail: error instanceof Error ? error.message : "observation failed"
+        detail: errorDetail(error)
       };
     }
     try {
@@ -5144,27 +5170,49 @@ function validatePolicyForStep(plan2, step, policy) {
   }
   return void 0;
 }
-async function resumeTransitionRun(registry, input) {
-  const loaded = await input.loadCurrent(input.runId);
-  if (loaded.run.runId !== input.runId) {
+async function resumeTransitionRunInternal(registry, input, runId, completed, observations) {
+  let supplied;
+  try {
+    supplied = await input.loadCurrent(runId);
+  } catch (error) {
+    return contextMismatch(
+      `transition run ${runId} could not be loaded: ${errorDetail(error)}`
+    );
+  }
+  let loaded;
+  try {
+    loaded = snapshotLoadedRun(supplied);
+  } catch (error) {
+    return contextMismatch(
+      `loaded journal could not be snapshotted safely: ${errorDetail(error)}`
+    );
+  }
+  if (loaded.run.runId !== runId) {
     return contextMismatch(
       "loaded journal run id does not match requested run id"
     );
   }
-  if (loaded.run.planDigest !== digest(loaded.plan)) {
-    return contextMismatch("loaded plan digest does not match run metadata");
+  let diagnostic;
+  try {
+    if (loaded.run.planDigest !== transitionPlanDigest(loaded.plan)) {
+      return contextMismatch("loaded plan digest does not match run metadata");
+    }
+    diagnostic = validateTransitionRelationalInvariants({
+      kind: "plan",
+      plan: loaded.plan
+    });
+  } catch (error) {
+    return contextMismatch(
+      `loaded plan could not be validated: ${errorDetail(error)}`
+    );
   }
-  const diagnostic = validateTransitionRelationalInvariants({
-    kind: "plan",
-    plan: loaded.plan
-  });
   if (!diagnostic.ok) {
     return contextMismatch(
       `loaded plan failed invariant validation: ${diagnostic.detail}`
     );
   }
-  const evidenceContext = planEvidenceContext(loaded.plan);
-  if (!evidenceContext) {
+  const evidenceContext2 = planEvidenceContext(loaded.plan);
+  if (!evidenceContext2) {
     return contextMismatch("loaded plan contains no durable evidence context");
   }
   const referencedAssumptions = /* @__PURE__ */ new Set();
@@ -5204,7 +5252,14 @@ async function resumeTransitionRun(registry, input) {
       observations: []
     };
   }
-  const baseContext = await input.readContext(input.target, loaded.run);
+  let baseContext;
+  try {
+    baseContext = await input.readContext(input.target, loaded.run);
+  } catch (error) {
+    return contextMismatch(
+      `transition run ${runId} target context could not be read: ${errorDetail(error)}`
+    );
+  }
   const runContextMatch = matchRunObservationContext({
     run: loaded.run,
     actual: baseContext
@@ -5214,7 +5269,7 @@ async function resumeTransitionRun(registry, input) {
   }
   const evidenceIdentityMatch = matchObservationContextIdentity({
     expected: baseContext,
-    actual: evidenceContext,
+    actual: evidenceContext2,
     label: "loaded plan evidence context"
   });
   if (!evidenceIdentityMatch.ok) {
@@ -5228,24 +5283,35 @@ async function resumeTransitionRun(registry, input) {
     if (!effectsResolution.ok) {
       return contextMismatch(effectsResolution.detail);
     }
-    operationEffectsByRef.set(
-      step.operation.ref,
-      effectsResolution.semantics.effectsOf(step.operation, baseContext)
+    try {
+      operationEffectsByRef.set(
+        step.operation.ref,
+        effectsResolution.semantics.effectsOf(step.operation, baseContext)
+      );
+    } catch (error) {
+      return contextMismatch(
+        `operation ${step.operation.ref} effects could not be resolved: ${errorDetail(error)}`
+      );
+    }
+  }
+  let semanticDiagnostic;
+  try {
+    semanticDiagnostic = validateTransitionRelationalInvariants({
+      kind: "plan",
+      plan: loaded.plan,
+      operationEffectsByRef
+    });
+  } catch (error) {
+    return contextMismatch(
+      `loaded plan could not be semantically validated: ${errorDetail(error)}`
     );
   }
-  const semanticDiagnostic = validateTransitionRelationalInvariants({
-    kind: "plan",
-    plan: loaded.plan,
-    operationEffectsByRef
-  });
   if (!semanticDiagnostic.ok) {
     return contextMismatch(
       `loaded plan failed semantic invariant validation: ${semanticDiagnostic.detail}`
     );
   }
   const orderedSteps = orderedPlanSteps(loaded.plan, stepById);
-  const completed = [];
-  const observations = [];
   for (const step of orderedSteps) {
     const events = grouped.get(step.stepId);
     if (!events?.intent && !events?.observed) {
@@ -5429,6 +5495,64 @@ async function resumeTransitionRun(registry, input) {
     observations
   };
 }
+async function resumeTransitionRun(registry, input) {
+  const completed = [];
+  const observations = [];
+  const runId = input.runId;
+  try {
+    return await resumeTransitionRunInternal(
+      registry,
+      input,
+      runId,
+      completed,
+      observations
+    );
+  } catch (error) {
+    return contextMismatch(
+      `transition run ${runId} could not be resumed: ${errorDetail(error)}`,
+      completed,
+      observations
+    );
+  }
+}
+
+// src/transition/run-metadata.ts
+import { randomUUID } from "crypto";
+var TRANSITION_PLANNER_ARTIFACT = {
+  id: semanticArtifactId("dbsp.core.transition.planner"),
+  version: "0.1.0"
+};
+function evidenceContext(observations) {
+  const evidence = observations.filter(
+    (observation) => observation.role === "evidence"
+  );
+  const first = evidence[0]?.context;
+  if (!first) {
+    throw new Error(
+      "internal error: minted proven plan has no evidence observation context"
+    );
+  }
+  const expected = stableJson(first);
+  for (const observation of evidence.slice(1)) {
+    if (stableJson(observation.context) !== expected) {
+      throw new Error(
+        "internal error: minted proven plan evidence observations do not share one context"
+      );
+    }
+  }
+  return first;
+}
+function createTransitionRunMetadata(plan2) {
+  const context = evidenceContext(plan2.observations);
+  return {
+    runId: `dbsp-${randomUUID()}`,
+    planDigest: transitionPlanDigest(plan2),
+    targetContextDigest: observationContextDigest(context),
+    databaseId: context.databaseId,
+    coreVersion: TRANSITION_PLANNER_ARTIFACT.version,
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
 
 // src/transition/applier.ts
 var APPLIER_ARTIFACT = {
@@ -5452,6 +5576,13 @@ function completedAssessment2(proven) {
     continuation: "none"
   };
 }
+function transitionLessorRejectionResult() {
+  return {
+    assessment: transitionLessorRejectionAssessment(APPLIER_ARTIFACT),
+    journals: [],
+    observations: []
+  };
+}
 function primaryClaimFromPlan(plan2) {
   return plan2.claims[0]?.id ?? plan2.steps.flatMap((step) => [...step.requiredClaims])[0] ?? claimId("dbsp.transition.claim.plan");
 }
@@ -5479,9 +5610,6 @@ function evidenceIds2(observations) {
 function recordedAt2() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
-function digest2(value) {
-  return createHash3("sha256").update(stableJson(value)).digest("hex");
-}
 function lockTimeoutMs(runtime, step, context) {
   const effects = runtime.effectsOf(step.operation, context);
   const waits = effects.effects.locks.flatMap(
@@ -5489,35 +5617,9 @@ function lockTimeoutMs(runtime, step, context) {
   );
   return waits.length > 0 ? Math.max(...waits) : 5e3;
 }
-function contextFromPlanObservations(observations) {
-  const evidence = observations.filter(
-    (observation) => observation.role === "evidence"
-  );
-  const first = evidence[0]?.context;
-  if (!first) {
-    return void 0;
-  }
-  const expected = stableJson(first);
-  for (const observation of evidence.slice(1)) {
-    if (stableJson(observation.context) !== expected) {
-      return void 0;
-    }
-  }
-  return first;
-}
 function fingerprintMatches2(expected, actual) {
   return expected.digest === actual.digest;
 }
-function transitionRunMetadata(plan2, context) {
-  return {
-    runId: `dbsp-${randomUUID()}`,
-    planDigest: digest2(plan2),
-    targetContextDigest: digest2(context),
-    databaseId: context.databaseId,
-    coreVersion: APPLIER_ARTIFACT.version,
-    startedAt: recordedAt2()
-  };
-}
 function intentRecord(step, run) {
   return {
     runId: run.runId,
@@ -5635,6 +5737,22 @@ function invalidPlanResult(detail) {
     observations: []
   };
 }
+function persistenceFailureResult(run, error) {
+  return {
+    assessment: assessment2({
+      code: "persistence-failed",
+      artifact: APPLIER_ARTIFACT,
+      fact: {
+        key: "transition-run-id",
+        value: run.runId
+      },
+      detail: `transition-run persistence is indeterminate; load run ${run.runId} before retrying: ${errorDetail2(error)}`,
+      scope: []
+    }),
+    journals: [],
+    observations: []
+  };
+}
 function unknownJournal(intent) {
   return {
     intent,
@@ -5689,11 +5807,11 @@ var CommitOutcomeUncertainError = class extends Error {
     this.originalError = error;
   }
 };
-function errorDetail(error) {
+function errorDetail2(error) {
   return error instanceof Error ? error.message : "unknown error";
 }
 function withJournalWriteWarning(assessmentValue, error) {
-  const detail = `observed journal write failed after outcome was decided: ${errorDetail(error)}`;
+  const detail = `observed journal write failed after outcome was decided: ${errorDetail2(error)}`;
   return {
     ...assessmentValue,
     reasons: assessmentValue.reasons.map(
@@ -5734,7 +5852,7 @@ function durableEvidence(observations) {
     (observation) => observation.role === "evidence"
   );
 }
-function createApplier(registry) {
+function createApplier(registry, persister) {
   return {
     artifact: APPLIER_ARTIFACT,
     async apply(proven, policy, target) {
@@ -5742,7 +5860,16 @@ function createApplier(registry) {
       if (!isMintedInProcessPlan(plan2)) {
         return invalidPlanResult(UNMINTED_PLAN_DETAIL);
       }
-      if (plan2.steps.length === 0 || plan2.segments.length === 0) {
+      if (plan2.segments.length === 0) {
+        if (!isTransitionLessor(target)) {
+          return transitionLessorRejectionResult();
+        }
+        return uncomposablePlanResult(
+          plan2,
+          "plan contains no executable steps"
+        );
+      }
+      if (plan2.steps.length === 0) {
         return uncomposablePlanResult(
           plan2,
           "plan contains no executable steps"
@@ -5758,10 +5885,12 @@ function createApplier(registry) {
         );
       }
       const reportedAssessment = derivedApplicableAssessment(plan2);
-      const proofContext = contextFromPlanObservations(plan2.observations);
+      const proofContext = plan2.observations.find(
+        (observation) => observation.role === "evidence"
+      )?.context;
       if (!proofContext) {
         throw new Error(
-          "internal error: minted proven plan evidence observations do not share one context"
+          "internal error: minted proven plan has no evidence observation context"
         );
       }
       const assumptionById = new Map(
@@ -5782,7 +5911,7 @@ function createApplier(registry) {
           return unacceptedAssumptionResult(plan2, assumption);
         }
       }
-      const run = transitionRunMetadata(plan2, proofContext);
+      const run = createTransitionRunMetadata(plan2);
       const operationEffectsByRef = /* @__PURE__ */ new Map();
       for (const step of plan2.steps) {
         const operationResolution = registry.resolveOperation(step.operation);
@@ -5852,8 +5981,8 @@ function createApplier(registry) {
           journalWriteFailure ?? params.result
         );
       };
-      let runtimeContext = proofContext;
       const stepById = new Map(plan2.steps.map((step) => [step.stepId, step]));
+      const preflightSegments = [];
       for (const segment of plan2.segments) {
         const segmentSteps = segment.stepIds.map(
           (stepId2) => stepById.get(stepId2)
@@ -5979,6 +6108,29 @@ function createApplier(registry) {
             )
           );
         }
+        preflightSegments.push({
+          segment,
+          resolvedSteps,
+          first,
+          transactional,
+          segmentCoordinator
+        });
+      }
+      if (!isTransitionLessor(target)) {
+        return resultWithCommittedJournals(transitionLessorRejectionResult());
+      }
+      try {
+        await persister.persist(run, plan2);
+      } catch (error) {
+        return persistenceFailureResult(run, error);
+      }
+      let runtimeContext = proofContext;
+      for (const {
+        resolvedSteps,
+        first,
+        transactional,
+        segmentCoordinator
+      } of preflightSegments) {
         let client;
         let lease;
         let committed = false;
@@ -5989,13 +6141,6 @@ function createApplier(registry) {
         let activeOperationAttempted = false;
         let activeNonRollbackableOperationExecuted = false;
         const completedInSegment = [];
-        if (!isTransitionLessor(target)) {
-          return resultWithCommittedJournals({
-            assessment: transitionLessorRejectionAssessment(APPLIER_ARTIFACT),
-            journals: [],
-            observations: []
-          });
-        }
         try {
           lease = await acquireTransitionLease(target);
           client = { opaqueClient: lease.session };
@@ -6478,7 +6623,7 @@ function createApplier(registry) {
                       operationKind: entry.step.operation.operationKind,
                       operationRef: entry.step.operation.ref,
                       scope: [],
-                      detail: `after-commit expectedAfter observation failed after commit: ${errorDetail(error)}`
+                      detail: `after-commit expectedAfter observation failed after commit: ${errorDetail2(error)}`
                     },
                     "outcome-unknown",
                     "human-intervention-required"
@@ -6563,7 +6708,7 @@ function createApplier(registry) {
                   operationKind: active.step.operation.operationKind,
                   operationRef: active.step.operation.ref,
                   scope: [],
-                  detail: `commit outcome uncertain after commit failure: ${errorDetail(error.originalError)}`
+                  detail: `commit outcome uncertain after commit failure: ${errorDetail2(error.originalError)}`
                 },
                 "outcome-unknown",
                 "human-intervention-required"
@@ -9125,6 +9270,106 @@ function createEvidenceView(params) {
   return new CoreEvidenceView(params.evidence, params.context, params.requests);
 }
 
+// src/transition/execution-contract.ts
+import { EXECUTION_CONTRACT_VERSION } from "@dbsp/types";
+function canonicalRequirements(requirements) {
+  const ordered = [...requirements].sort((left, right) => {
+    const leftJson = stableJson(left);
+    const rightJson = stableJson(right);
+    return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+  });
+  return ordered.filter(
+    (requirement, index) => index === 0 || stableJson(requirement) !== stableJson(ordered[index - 1])
+  );
+}
+function compareNamespaceIdentity(left, right) {
+  return left.name < right.name ? -1 : left.name > right.name ? 1 : left.oid < right.oid ? -1 : left.oid > right.oid ? 1 : 0;
+}
+function canonicalNamespaces(namespaces) {
+  const ordered = [...namespaces].sort(compareNamespaceIdentity);
+  return ordered.filter(
+    (namespace, index) => index === 0 || compareNamespaceIdentity(namespace, ordered[index - 1] ?? namespace) !== 0
+  );
+}
+function createExecutionContract(requirements) {
+  return {
+    version: EXECUTION_CONTRACT_VERSION,
+    requirements: canonicalRequirements(requirements)
+  };
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function validRequirement(requirement) {
+  if (requirement === null || typeof requirement !== "object" || Array.isArray(requirement))
+    return false;
+  const value = requirement;
+  if (!nonEmpty(value.kind) || !["must-match", "set-and-verify", "must-satisfy", "provenance"].includes(
+    value.mode
+  ))
+    return false;
+  switch (value.kind) {
+    case "postgresql.physical-target": {
+      if (!(value.mode === "must-match" && nonEmpty(value.systemIdentifier) && nonEmpty(value.databaseOid) && Array.isArray(value.namespaces) && value.namespaces.length > 0 && value.namespaces.every(
+        (item) => item !== null && typeof item === "object" && nonEmpty(item.name) && nonEmpty(item.oid)
+      )))
+        return false;
+      const namespaces = value.namespaces;
+      return stableJson(namespaces) === stableJson(canonicalNamespaces(namespaces)) && new Set(namespaces.map((namespace) => namespace.name)).size === namespaces.length;
+    }
+    case "postgresql.engine-version":
+      return value.mode === "must-satisfy" && nonEmpty(value.stepId) && (value.minServerVersionNum === void 0 || Number.isInteger(value.minServerVersionNum)) && (value.maxServerVersionNum === void 0 || Number.isInteger(value.maxServerVersionNum));
+    case "postgresql.authority":
+      return value.mode === "must-satisfy" && ["schema-usage", "table-alter", "type-alter"].includes(
+        value.action
+      ) && nonEmpty(value.schema) && (value.action === "schema-usage" || nonEmpty(value.object));
+    case "postgresql.session-setting":
+      return (value.mode === "set-and-verify" || value.mode === "provenance") && [
+        "standard_conforming_strings",
+        "search_path",
+        "client_encoding",
+        "TimeZone"
+      ].includes(value.setting) && nonEmpty(value.value) && (value.mode !== "set-and-verify" || value.setting === "standard_conforming_strings" && value.value === "on" || value.setting === "client_encoding" && value.value === "UTF8");
+    default:
+      return false;
+  }
+}
+function validateExecutionContract(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value))
+    return {
+      ok: false,
+      detail: "plan is missing an execution contract; re-plan before execution"
+    };
+  const contract = value;
+  if (contract.version !== EXECUTION_CONTRACT_VERSION)
+    return {
+      ok: false,
+      detail: `execution contract version ${String(contract.version)} is unsupported`
+    };
+  if (!Array.isArray(contract.requirements) || contract.requirements.length === 0)
+    return { ok: false, detail: "execution contract has no requirements" };
+  if (!contract.requirements.every(validRequirement))
+    return {
+      ok: false,
+      detail: "execution contract contains an unknown requirement kind or mode"
+    };
+  const canonical = canonicalRequirements(contract.requirements);
+  if (stableJson(canonical) !== stableJson(contract.requirements))
+    return {
+      ok: false,
+      detail: "execution contract requirements are not canonically ordered"
+    };
+  return { ok: true, contract };
+}
+function bindExecutionContract(plan2, contract) {
+  const validation = validateExecutionContract(contract);
+  if (!validation.ok) throw new Error(validation.detail);
+  return mintInProcessPlan({
+    ...plan2,
+    executionContract: validation.contract
+  });
+}
+
 // src/transition/composer.ts
 function sameResource4(left, right) {
   return stableJson(left) === stableJson(right);
@@ -9821,6 +10066,14 @@ var ObservationContextMismatchError = class extends Error {
     this.name = "ObservationContextMismatchError";
   }
 };
+function verifyCapturedTargetIdentity(expected, actual) {
+  if (expected.postgresqlTargetIdentity === void 0) return;
+  if (stableJson(expected.postgresqlTargetIdentity) !== stableJson(actual.postgresqlTargetIdentity)) {
+    throw new ObservationContextMismatchError(
+      "proof observation target identity does not match the target captured before evidence collection"
+    );
+  }
+}
 function validateIssuedObservation(observation, context) {
   const contextMatch = matchLiveObservationContext({
     expected: context,
@@ -10552,6 +10805,7 @@ async function proveTransitions(registry, compare, target, context, initialState
             requiredObservations
           ) : context
         );
+        verifyCapturedTargetIdentity(context, candidateContext);
         if (!sharedProofContext) {
           sharedProofContext = candidateContext;
         } else {
@@ -10686,6 +10940,7 @@ async function proveTransitions(registry, compare, target, context, initialState
             lease = await checkoutProofClient(target);
             client = lease.session;
             proofContext = issuer.readContext ? await issuer.readContext(client, context, requiredObservations) : context;
+            verifyCapturedTargetIdentity(context, proofContext);
             proofContext = registry.contextWithDerivedCapabilities(proofContext);
             const supportMismatch = ruleSupportMismatch(rule, proofContext);
             if (supportMismatch) {
@@ -11224,6 +11479,7 @@ async function retryUnknownRecognition(registry, compare, target, context) {
       lease = await checkoutProofClient(target);
       client = lease.session;
       let proofContext2 = issuer.readContext ? await issuer.readContext(client, context, recognitionRequests) : context;
+      verifyCapturedTargetIdentity(context, proofContext2);
       proofContext2 = registry.contextWithDerivedCapabilities(proofContext2);
       const supportMismatch2 = ruleSupportMismatch(rule, proofContext2);
       if (supportMismatch2) {
@@ -11856,10 +12112,10 @@ function candidateProgressKey(entry) {
 function completedJournalRefs(journals) {
   return journals.filter((journal) => journal.outcome === "completed").map((journal) => journal.intent.operation.ref);
 }
-function createStagedTransitionOrchestrator(registry) {
+function createStagedTransitionOrchestrator(registry, persister) {
   const comparator = createComparator(registry);
   const prover = createProver(registry);
-  const applier = createApplier(registry);
+  const applier = createApplier(registry, persister);
   return {
     async applyStagedTransition(input) {
       const journals = [];
@@ -12003,8 +12259,41 @@ function createStagedTransitionOrchestrator(registry) {
 
 // src/adapter.ts
 function supportsExecution(adapter) {
+  const connectionProvider = adapter;
+  if (typeof connectionProvider.getPoolInstance === "function") {
+    try {
+      connectionProvider.getPoolInstance();
+    } catch {
+      return false;
+    }
+  }
   return typeof adapter.execute === "function" && typeof adapter.executeOne === "function" && typeof adapter.executeOneOrThrow === "function";
 }
+function assertConnectionAvailable(adapter, operation) {
+  const availability = adapter.connectionAvailability;
+  if (availability?.status === "unavailable") {
+    throw new ExecutionError({
+      operation,
+      reason: availability.reason,
+      fix: availability.fix
+    });
+  }
+}
+function executeCompiledQuery(adapter, query, operation) {
+  assertConnectionAvailable(adapter, operation);
+  return adapter.execute(query);
+}
+function executeCompiledQueryWithMeta(adapter, query, operation) {
+  assertConnectionAvailable(adapter, operation);
+  if (typeof adapter.executeWithMeta !== "function") {
+    throw new ExecutionError({
+      operation,
+      reason: "this adapter does not implement executeWithMeta",
+      fix: "Use an adapter that implements executeWithMeta."
+    });
+  }
+  return adapter.executeWithMeta(query);
+}
 function supportsStreaming(adapter) {
   return adapter.capabilities?.supportsStreaming === true && "stream" in adapter && typeof adapter.stream === "function";
 }
@@ -12913,7 +13202,7 @@ var CteQueryBuilder = class {
     const intent = this.buildIntent();
     const compileOptions = this.compileOptions();
     const compiled = adapter.compileCteQuery(intent, compileOptions);
-    return adapter.execute(compiled);
+    return executeCompiledQuery(adapter, compiled, "withCte().all()");
   }
   /**
    * Alias for all().
@@ -14729,9 +15018,10 @@ var MutationBuilderBase = class {
   async affectedRows() {
     const adapter = this.requireAdapter(this.operationName);
     const intent = this.buildIntent();
+    const operation = `${this.operationName}.affectedRows()`;
     if (typeof adapter.executeWithMeta !== "function") {
       throw new ExecutionError({
-        operation: `${this.operationName}.affectedRows`,
+        operation,
         reason: "this adapter does not support affectedRows(); it does not implement executeWithMeta",
         fix: "Use an adapter that implements executeWithMeta, or call execute() when row count metadata is not required."
       });
@@ -14743,18 +15033,18 @@ var MutationBuilderBase = class {
       onHookError: this.onHookError,
       schemaName: this.schemaName,
       inTransaction: this.inTransaction,
-      prepare: (preparedIntent) => this.prepareMutationExecution(adapter, preparedIntent)
+      prepare: (preparedIntent) => this.prepareMutationExecution(adapter, preparedIntent, operation)
     });
     if (execution.affectedRows === void 0) {
       throw new ExecutionError({
-        operation: `${this.operationName}.affectedRows`,
+        operation,
         reason: "this adapter does not support affectedRows(); it did not return executeWithMeta metadata",
         fix: "Use an adapter that implements executeWithMeta and returns rowCount metadata."
       });
     }
     return execution.affectedRows;
   }
-  prepareMutationExecution(adapter, intent) {
+  prepareMutationExecution(adapter, intent, operation = `${this.operationName}()`) {
     const compileOptions = {
       model: this.model,
       ...this.schemaName ? { schemaName: this.schemaName } : {}
@@ -14766,13 +15056,21 @@ var MutationBuilderBase = class {
         parameters: compiled.parameters,
         execute: async () => {
           if (typeof adapter.executeWithMeta === "function") {
-            const result2 = await adapter.executeWithMeta(compiled);
+            const result2 = await executeCompiledQueryWithMeta(
+              adapter,
+              compiled,
+              operation
+            );
             return {
               result: result2.rows,
               affectedRows: result2.rowCount
             };
           }
-          const result = await adapter.execute(compiled);
+          const result = await executeCompiledQuery(
+            adapter,
+            compiled,
+            operation
+          );
           return {
             result
           };
@@ -14786,13 +15084,17 @@ var MutationBuilderBase = class {
       parameters: compiled.parameters,
       execute: async () => {
         if (typeof adapter.executeWithMeta === "function") {
-          const result = await adapter.executeWithMeta(compiled);
+          const result = await executeCompiledQueryWithMeta(
+            adapter,
+            compiled,
+            operation
+          );
           return {
             result: void 0,
             affectedRows: result.rowCount
           };
         }
-        await adapter.execute(compiled);
+        await executeCompiledQuery(adapter, compiled, operation);
         return {
           result: void 0
         };
@@ -16629,7 +16931,11 @@ var NqlBuilderImpl = class {
           parameters: compiled.parameters,
           execute: async () => {
             if (typeof adapter.executeWithMeta === "function") {
-              const metadata = await adapter.executeWithMeta(compiled);
+              const metadata = await executeCompiledQueryWithMeta(
+                adapter,
+                compiled,
+                "nql().all()"
+              );
               const hookRows2 = metadata.rows;
               const rawRows2 = snapshotMutationRows(hookRows2);
               return {
@@ -16641,7 +16947,11 @@ var NqlBuilderImpl = class {
                 affectedRows: metadata.rowCount
               };
             }
-            const hookRows = await adapter.execute(compiled);
+            const hookRows = await executeCompiledQuery(
+              adapter,
+              compiled,
+              "nql().all()"
+            );
             const rawRows = snapshotMutationRows(hookRows);
             return {
               result: {
@@ -16663,6 +16973,7 @@ var NqlBuilderImpl = class {
     });
   }
   async executeNqlProgramSequence(compiledIntent, adapter) {
+    assertConnectionAvailable(adapter, "nql().all()");
     if (!supportsTransactions(adapter)) {
       throw new ExecutionError({
         operation: "nql",
@@ -16926,6 +17237,7 @@ var NqlBuilderImpl = class {
     if (hasExecutableNqlProgramSequence(compiledIntent.bundle)) {
       return this.executeNqlProgramSequence(compiledIntent, adapter);
     }
+    assertConnectionAvailable(adapter, "nql().all()");
     if (compiledIntent.kind === "mutation") {
       return (await this.runMutationStatement(
         adapter,
@@ -16948,7 +17260,7 @@ var NqlBuilderImpl = class {
         ),
         this.nqlBundleCompileOptions()
       );
-      const rows = await adapter.execute(compiled2);
+      const rows = await executeCompiledQuery(adapter, compiled2, "nql().all()");
       if (bindingFinalPlanHasJsonAggIncludes(planReport2)) {
         hydrateJsonAggIncludes(
           rows,
@@ -16961,7 +17273,7 @@ var NqlBuilderImpl = class {
     const planReport = this.planInternal();
     const finalBundle = this.createFinalNqlStatementBundle(compiledIntent);
     const compiled = hasNqlBindings(finalBundle) ? adapter.compile(finalBundle, this.nqlBundleCompileOptions()) : adapter.compile(planReport);
-    return adapter.execute(compiled);
+    return executeCompiledQuery(adapter, compiled, "nql().all()");
   }
   async run() {
     await this.all();
@@ -17461,7 +17773,11 @@ var ResultHydrator = class {
         parentIds,
         compileOptions
       );
-      const childResults = await adapter.execute(includeQuery);
+      const childResults = await executeCompiledQuery(
+        adapter,
+        includeQuery,
+        "all()"
+      );
       const childrenByParentId = /* @__PURE__ */ new Map();
       for (const child of childResults) {
         const parentId = this.extractKeyValue(
@@ -17617,7 +17933,11 @@ var ResultHydrator = class {
       this.model,
       compileOptions
     );
-    const recursiveRows = await adapter.execute(compiledRecursive);
+    const recursiveRows = await executeCompiledQuery(
+      adapter,
+      compiledRecursive,
+      "all()"
+    );
     this.mergeRecursiveResults(
       results,
       recursiveRows,
@@ -17857,8 +18177,11 @@ var SetOperationBuilderImpl = class _SetOperationBuilderImpl {
   }
   async all() {
     const adapter = this.requireAdapter();
-    const compiled = adapter.compileSetOperation(this.intent, this.model);
-    return adapter.execute(compiled);
+    const compiled = adapter.compileSetOperation(
+      this.intent,
+      this.model
+    );
+    return executeCompiledQuery(adapter, compiled, "set operation all()");
   }
   async first() {
     const rows = await this.all();
@@ -17938,6 +18261,7 @@ function stream(builder, options) {
       return this;
     },
     async next() {
+      assertConnectionAvailable(adapter, "stream()");
       if (!supportsStreaming(adapter)) {
         throw createUnsupportedStreamingError();
       }
@@ -18535,8 +18859,10 @@ var QueryBuilderImpl = class _QueryBuilderImpl {
       planReport,
       compileOptions
     );
-    const mainResults = await adapter.execute(
-      compiledWithIncludes.main
+    const mainResults = await executeCompiledQuery(
+      adapter,
+      compiledWithIncludes.main,
+      "all()"
     );
     const hydrator = new ResultHydrator(
       this.ctx.model,
@@ -18709,7 +19035,7 @@ var QueryBuilderImpl = class _QueryBuilderImpl {
       compileOptions.schemaName = this.ctx.schemaName;
     }
     const compiled = adapter.compile(planReport, compileOptions);
-    const rows = await adapter.execute(compiled);
+    const rows = await executeCompiledQuery(adapter, compiled, "exists()");
     return rows.length > 0 && rows[0].exists === true;
   }
   async existsWithHooks(adapter, store) {
@@ -18765,7 +19091,7 @@ var QueryBuilderImpl = class _QueryBuilderImpl {
       compileOptions.schemaName = this.ctx.schemaName;
     }
     const compiled = adapter.compile(planReport, compileOptions);
-    const rows = await adapter.execute(compiled);
+    const rows = await executeCompiledQuery(adapter, compiled, "exists()");
     const result = rows.length > 0 && rows[0].exists === true;
     const afterCtx = {
       table: this.from,
@@ -19049,8 +19375,10 @@ var QueryBuilderImpl = class _QueryBuilderImpl {
     );
     let mainResults;
     try {
-      mainResults = await adapter.execute(
-        compiledWithIncludes.main
+      mainResults = await executeCompiledQuery(
+        adapter,
+        compiledWithIncludes.main,
+        "all()"
       );
     } catch (error) {
       if (store.onError.length > 0) {
@@ -19468,7 +19796,7 @@ var RawCteQueryBuilder = class {
       ...this.model !== void 0 && { model: this.model }
     } : void 0;
     const compiled = adapter.compileCteQuery(intent, compileOptions);
-    return adapter.execute(compiled);
+    return executeCompiledQuery(adapter, compiled, "recursive().all()");
   }
   /**
    * Alias for `all()`.
@@ -20055,6 +20383,11 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
           )
         );
       }
+      try {
+        assertConnectionAvailable(adapter, "transaction()");
+      } catch (error) {
+        return Promise.reject(error);
+      }
       if (!supportsTransactions(adapter)) {
         return Promise.reject(createUnsupportedTransactionError());
       }
@@ -20097,6 +20430,11 @@ function createOrmInstance(model, strictMode, relationHints, adapter, schemaName
           )
         );
       }
+      try {
+        assertConnectionAvailable(adapter, "withPinnedConnection()");
+      } catch (error) {
+        return Promise.reject(error);
+      }
       if (!supportsPinnedConnections(adapter)) {
         return Promise.reject(createUnsupportedPinnedConnectionError());
       }
@@ -21793,6 +22131,7 @@ export {
   array,
   arrayAgg,
   assertCapability,
+  assertConnectionAvailable,
   assertContains,
   assertDbColumnExists,
   assertDbOutput,
@@ -21818,8 +22157,10 @@ export {
   assertSQLTable,
   assertSuccess,
   assertTypeSupported,
+  assumptionAccepted,
   assumptionId,
   batchValues,
+  bindExecutionContract,
   capitalize,
   caseWhen,
   cast,
@@ -21833,11 +22174,13 @@ export {
   composeBeforeMutationHooks,
   composeBeforeQueryHooks,
   composeOnErrorHooks,
+  concludeEvidenceForObligation,
   countDistinctRelationPathsByName,
   createApplier,
   createComparator,
   createDialectCapabilities,
   createEvidenceView,
+  createExecutionContract,
   createHookManager,
   createNqlTag,
   createOrm,
@@ -21848,6 +22191,7 @@ export {
   createRecursiveMetadata,
   createStagedTransitionOrchestrator,
   createTransitionLessor,
+  createTransitionRunMetadata,
   decapitalize,
   defaultIndexName,
   defaultLogger,
@@ -21956,6 +22300,7 @@ export {
   notExists,
   nqlRaw,
   objectToWhereIntent,
+  observationContextDigest,
   op,
   or,
   outerRef,
@@ -22012,8 +22357,10 @@ export {
   supportsStreaming,
   supportsTransactions,
   textScore,
+  transitionPlanDigest,
   unary,
   validateAssertionBlocks,
+  validateExecutionContract,
   validateRecursiveInclude,
   validateRecursiveShape,
   validateSchemaIndexOptions,