@runuai/host 0.9.148 → 0.9.149

package/lib/project-env-replica.ts

@@ -0,0 +1,2094 @@
+/**
+ * Durable Uai Cloud task-machine project-env replica (ADR-153).
+ *
+ * The cloud owns the records. A sidecar keeps a whole-task, value-free
+ * replica plus encrypted materialised values. Snapshot pages are written to
+ * staging and are never served; only the exact commit marker promotes them.
+ * A newer head is first made durable with no plaintext, then its immutable
+ * SSM reference is fetched and conditionally installed. Thus a crash can
+ * withhold a value, but can never pair an old value with a new policy/head.
+ */
+
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+import { and, asc, eq } from "drizzle-orm";
+
+import {
+  MAX_PROJECT_ENV_ACK_PAGE_BYTES,
+  isHostOpId,
+  isProjectEnvPolicyEpochs,
+  isProjectEnvReplicaApplyFrame,
+  isProjectEnvReplicaBeginFrame,
+  isProjectEnvReplicaBindingState,
+  isProjectEnvReplicaCommitFrame,
+  isProjectEnvReplicaPageFrame,
+  isProjectEnvReplicaResult,
+  sameProjectEnvHead,
+  type ProjectEnvBinding,
+  type ProjectEnvDeliveryCursor,
+  type ProjectEnvReplicaApplyFrame,
+  type ProjectEnvReplicaBeginFrame,
+  type ProjectEnvReplicaBindingState,
+  type ProjectEnvReplicaCommitFrame,
+  type ProjectEnvReplicaMaterialization,
+  type ProjectEnvReplicaPageFrame,
+  type ProjectEnvReplicaResult,
+  type ProjectEnvValueRef,
+  type ProjectEnvWithholdReason,
+} from "../src/protocol";
+import {
+  configuredCredentialStore,
+  credentialStorePrefix,
+  isParameterPathSegment,
+  parameterName,
+  type CredentialStore,
+} from "./credential-store";
+import { getDb, schema, type Db } from "./db";
+import {
+  noteProjectEnvAuthorityChange,
+  noteProjectEnvValueMutation,
+  onProjectEnvChange,
+  openProjectEnvValueFromStorage,
+  projectEnvParameterName,
+  sealProjectEnvValueForStorage,
+} from "./host-env";
+import { masterKey } from "./secrets";
+import { parseStoredProjectEnv } from "./user-credentials-store";
+
+type ReplicaAuthorityRow =
+  typeof schema.hostProjectEnvReplicaAuthority.$inferSelect;
+type ReplicaRecordRow =
+  typeof schema.hostProjectEnvReplicaRecords.$inferSelect;
+type ReplicaStageRecordRow =
+  typeof schema.hostProjectEnvReplicaStageRecords.$inferSelect;
+type ReplicaReceiptRow =
+  typeof schema.hostProjectEnvReplicaReceipts.$inferSelect;
+type ReplicaTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
+type ReplicaExecutor = Db | ReplicaTransaction;
+
+const RECEIPT_HMAC_DOMAIN = Buffer.from(
+  "uai.project_env.replica_receipt.v1\0",
+  "utf8",
+);
+const MAX_REASON = "x".repeat(64);
+
+export class ProjectEnvReplicaCorruptError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectEnvReplicaCorruptError";
+  }
+}
+
+export interface ProjectEnvReplicaStatus {
+  activated: boolean;
+  gateOpen: boolean;
+  attemptId: string | null;
+  orgId: string | null;
+  appliedThrough: ProjectEnvDeliveryCursor | null;
+  policyEpochs: number[];
+  projectIds: string[];
+}
+
+export interface ProjectEnvReplicaSnapshotEntry {
+  state: ProjectEnvReplicaBindingState;
+  materialization: ProjectEnvReplicaMaterialization;
+  value: string | null;
+}
+
+export interface ProjectEnvReplicaSnapshotProject {
+  projectId: string;
+  recordVersion: number;
+  entries: ProjectEnvReplicaSnapshotEntry[];
+}
+
+export interface ProjectEnvReplicaSnapshot {
+  projects: ProjectEnvReplicaSnapshotProject[];
+}
+
+export interface ProjectEnvReplicaValueReader {
+  readStaged(name: string): Promise<string | null>;
+  readLegacy(
+    name: string,
+    version: number,
+  ): Promise<{ value: string; version: number } | null>;
+}
+
+export type ProjectEnvReplicaBeginResult = {
+  appliedThrough: ProjectEnvDeliveryCursor;
+  policyEpochs: number[];
+};
+
+export type ProjectEnvReplicaPageResult =
+  | {
+      ok: true;
+      attemptId: string;
+      projectId: string;
+      after: string | null;
+      recordVersion: number;
+      results: ProjectEnvReplicaResult[];
+      complete: boolean;
+      policyEpochs: number[];
+      appliedThrough: ProjectEnvDeliveryCursor;
+    }
+  | {
+      ok: false;
+      attemptId: string;
+      code: ProjectEnvWithholdReason;
+      policyEpochs: number[];
+      appliedThrough: ProjectEnvDeliveryCursor;
+    };
+
+export type ProjectEnvReplicaApplyResult =
+  | {
+      ok: true;
+      replayed: boolean;
+      attemptId: string | null;
+      projectId: string;
+      recordVersion: number;
+      result: ProjectEnvReplicaResult;
+      policyEpochs: number[];
+      appliedThrough: ProjectEnvDeliveryCursor;
+    }
+  | {
+      ok: false;
+      replayed: boolean;
+      consumed: boolean;
+      attemptId: string | null;
+      code: ProjectEnvWithholdReason;
+      policyEpochs: number[];
+      appliedThrough: ProjectEnvDeliveryCursor;
+    };
+
+export type ProjectEnvReplicaCommitResult =
+  | {
+      ok: true;
+      attemptId: string;
+      policyEpochs: number[];
+      appliedThrough: ProjectEnvDeliveryCursor;
+    }
+  | {
+      ok: false;
+      attemptId: string;
+      code: ProjectEnvWithholdReason;
+      policyEpochs: number[];
+      appliedThrough: ProjectEnvDeliveryCursor;
+    };
+
+function authorityRow(executor: ReplicaExecutor): ReplicaAuthorityRow {
+  const row = executor
+    .select()
+    .from(schema.hostProjectEnvReplicaAuthority)
+    .where(eq(schema.hostProjectEnvReplicaAuthority.id, "replica"))
+    .get();
+  if (!row) {
+    throw new ProjectEnvReplicaCorruptError(
+      "project environment replica authority row is missing",
+    );
+  }
+  return row;
+}
+
+function policyEpochs(row: ReplicaAuthorityRow): number[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(row.policyEpochsJson);
+  } catch {
+    throw new ProjectEnvReplicaCorruptError(
+      "stored replica policy epochs are malformed",
+    );
+  }
+  if (!isProjectEnvPolicyEpochs(parsed)) {
+    throw new ProjectEnvReplicaCorruptError(
+      "stored replica policy epochs are invalid",
+    );
+  }
+  return parsed;
+}
+
+function cursor(row: ReplicaAuthorityRow): ProjectEnvDeliveryCursor | null {
+  if (!row.activated) return null;
+  if (
+    !isHostOpId(row.streamId) ||
+    !Number.isSafeInteger(row.appliedSequence) ||
+    row.appliedSequence < 0
+  ) {
+    throw new ProjectEnvReplicaCorruptError(
+      "stored replica delivery cursor is invalid",
+    );
+  }
+  return { streamId: row.streamId, sequence: row.appliedSequence };
+}
+
+function requiredCursor(row: ReplicaAuthorityRow): ProjectEnvDeliveryCursor {
+  const value = cursor(row);
+  if (value === null) {
+    throw new ProjectEnvReplicaCorruptError(
+      "project environment replica has not been activated",
+    );
+  }
+  return value;
+}
+
+function authorityOrgId(row: ReplicaAuthorityRow): string {
+  if (!row.activated || row.orgId === null || !isParameterPathSegment(row.orgId)) {
+    throw new ProjectEnvReplicaCorruptError(
+      "stored replica organization is invalid",
+    );
+  }
+  return row.orgId;
+}
+
+function parseJson(value: string | null, what: string): unknown {
+  if (value === null) return null;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    throw new ProjectEnvReplicaCorruptError(`stored ${what} is malformed`);
+  }
+}
+
+function rowState(
+  row: ReplicaRecordRow | ReplicaStageRecordRow,
+): ProjectEnvReplicaBindingState {
+  const binding = parseJson(row.bindingJson, "replica binding") as
+    | ProjectEnvBinding
+    | null;
+  const valueRef = parseJson(row.valueRefJson, "replica value reference") as
+    | ProjectEnvValueRef
+    | null;
+  const state: unknown = {
+    key: row.key,
+    head: row.tombstone
+      ? {
+          revision: row.revision,
+          generation: row.generation,
+          tombstone: true,
+          valueRef: null,
+        }
+      : {
+          revision: row.revision,
+          generation: row.generation,
+          tombstone: false,
+          valueRef,
+        },
+    binding,
+    policyEpoch: row.policyEpoch,
+    listingGeneration: row.listingGeneration,
+  };
+  if (!isProjectEnvReplicaBindingState(state)) {
+    throw new ProjectEnvReplicaCorruptError(
+      `stored replica record is invalid (${row.projectId}/${row.key})`,
+    );
+  }
+  return state;
+}
+
+function rowMaterialization(
+  row: ReplicaRecordRow | ReplicaStageRecordRow,
+): ProjectEnvReplicaMaterialization {
+  const value: unknown =
+    row.materialization === "installed"
+      ? { kind: "installed" }
+      : row.materialization === "withheld"
+        ? { kind: "withheld", reason: row.materializationReason }
+        : row.materialization === "unavailable"
+          ? { kind: "unavailable", reason: row.materializationReason }
+          : null;
+  const result: unknown = { state: rowState(row), materialization: value };
+  if (!isProjectEnvReplicaResult(result)) {
+    throw new ProjectEnvReplicaCorruptError(
+      `stored replica materialization is invalid (${row.projectId}/${row.key})`,
+    );
+  }
+  return (result as ProjectEnvReplicaResult).materialization;
+}
+
+function rowResult(
+  row: ReplicaRecordRow | ReplicaStageRecordRow,
+): ProjectEnvReplicaResult {
+  const result: unknown = {
+    state: rowState(row),
+    materialization: rowMaterialization(row),
+  };
+  if (!isProjectEnvReplicaResult(result)) {
+    throw new ProjectEnvReplicaCorruptError(
+      `stored replica outcome is invalid (${row.projectId}/${row.key})`,
+    );
+  }
+  return result;
+}
+
+function materializationColumns(
+  materialization: ProjectEnvReplicaMaterialization,
+): { materialization: string; materializationReason: string | null } {
+  return {
+    materialization: materialization.kind,
+    materializationReason:
+      materialization.kind === "installed" ? null : materialization.reason,
+  };
+}
+
+function stateColumns(state: ProjectEnvReplicaBindingState) {
+  return {
+    revision: state.head.revision,
+    generation: state.head.generation,
+    tombstone: state.head.tombstone,
+    valueRefJson:
+      state.head.valueRef === null
+        ? null
+        : JSON.stringify(state.head.valueRef),
+    bindingJson:
+      state.binding === null ? null : JSON.stringify(state.binding),
+    policyEpoch: state.policyEpoch,
+    listingGeneration: state.listingGeneration,
+  };
+}
+
+function sortedProjectIds(executor: ReplicaExecutor): string[] {
+  return executor
+    .select({ projectId: schema.hostProjectEnvReplicaProjects.projectId })
+    .from(schema.hostProjectEnvReplicaProjects)
+    .orderBy(asc(schema.hostProjectEnvReplicaProjects.projectId))
+    .all()
+    .map((row) => row.projectId);
+}
+
+function sameStrings(left: readonly string[], right: readonly string[]): boolean {
+  return (
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  );
+}
+
+function notifyProjects(projectIds: Iterable<string>): void {
+  const uniqueProjectIds = new Set(projectIds);
+  for (const projectId of uniqueProjectIds) {
+    noteProjectEnvValueMutation(projectId);
+  }
+  // An empty task still needs to wake admission when begin/commit changes its
+  // authority gate. There is no project revision to bump in that case.
+  if (uniqueProjectIds.size === 0) noteProjectEnvAuthorityChange();
+}
+
+function exactJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(exactJson).join(",")}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${exactJson(object[key])}`)
+    .join(",")}}`;
+}
+
+function requestMac(frame: ProjectEnvReplicaApplyFrame): string {
+  const semanticRequest = {
+    kind: frame.kind,
+    projectId: frame.projectId,
+    recordVersion: frame.recordVersion,
+    state: frame.state,
+    delivery: frame.delivery,
+  };
+  return createHmac("sha256", masterKey())
+    .update(RECEIPT_HMAC_DOMAIN)
+    .update(exactJson(semanticRequest))
+    .digest("hex");
+}
+
+function sameMac(left: string, right: string): boolean {
+  if (!/^[0-9a-f]{64}$/.test(left) || !/^[0-9a-f]{64}$/.test(right)) {
+    return false;
+  }
+  return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+
+function sameState(
+  left: ProjectEnvReplicaBindingState,
+  right: ProjectEnvReplicaBindingState,
+): boolean {
+  return exactJson(left) === exactJson(right);
+}
+
+type StateOrder = "same" | "newer" | "older" | "conflict";
+
+function stateOrder(
+  incoming: ProjectEnvReplicaBindingState,
+  current: ProjectEnvReplicaBindingState,
+): StateOrder {
+  const revisionDelta = incoming.head.revision - current.head.revision;
+  const generationDelta = incoming.head.generation - current.head.generation;
+  if (revisionDelta < 0 && generationDelta <= 0) return "older";
+  if (generationDelta < 0 && revisionDelta <= 0) return "older";
+  if (revisionDelta < 0 || generationDelta < 0) return "conflict";
+  if (revisionDelta === 0 && generationDelta === 0) {
+    if (!sameProjectEnvHead(incoming.head, current.head)) return "conflict";
+    if (
+      exactJson(incoming.binding) !== exactJson(current.binding) ||
+      incoming.policyEpoch !== current.policyEpoch
+    ) {
+      return "conflict";
+    }
+    if (incoming.listingGeneration < current.listingGeneration) return "older";
+    if (incoming.listingGeneration === current.listingGeneration) {
+      return sameState(incoming, current) ? "same" : "conflict";
+    }
+    return "newer";
+  }
+  if (incoming.listingGeneration < current.listingGeneration) return "conflict";
+  // One counter staying put constrains the fields that counter protects.
+  if (
+    revisionDelta === 0 &&
+    (incoming.head.tombstone !== current.head.tombstone ||
+      exactJson(incoming.binding) !== exactJson(current.binding) ||
+      incoming.policyEpoch !== current.policyEpoch)
+  ) {
+    return "conflict";
+  }
+  if (
+    generationDelta === 0 &&
+    (incoming.head.tombstone !== current.head.tombstone ||
+      exactJson(incoming.head.valueRef) !== exactJson(current.head.valueRef))
+  ) {
+    return "conflict";
+  }
+  return "newer";
+}
+
+/** One cloud record-version step can perform exactly one head-table move. */
+function isReachableRecordAdvance(
+  incoming: ProjectEnvReplicaBindingState,
+  current: ProjectEnvReplicaBindingState | null,
+): boolean {
+  if (current === null) {
+    return (
+      (incoming.head.revision === 1 &&
+        incoming.head.generation === 1 &&
+        !incoming.head.tombstone) ||
+      (incoming.head.revision === 1 &&
+        incoming.head.generation === 0 &&
+        incoming.head.tombstone)
+    );
+  }
+  const revision = incoming.head.revision - current.head.revision;
+  const generation = incoming.head.generation - current.head.generation;
+  if (incoming.listingGeneration < current.listingGeneration) return false;
+  if (revision === 0 && generation === 0) {
+    return (
+      sameProjectEnvHead(incoming.head, current.head) &&
+      exactJson(incoming.binding) === exactJson(current.binding) &&
+      incoming.policyEpoch === current.policyEpoch &&
+      incoming.listingGeneration > current.listingGeneration
+    );
+  }
+  // A live rotation moves only generation. Policy and binding are retained.
+  if (revision === 0 && generation === 1) {
+    return (
+      !current.head.tombstone &&
+      !incoming.head.tombstone &&
+      exactJson(incoming.binding) === exactJson(current.binding) &&
+      incoming.policyEpoch === current.policyEpoch
+    );
+  }
+  // Approve / epoch upgrade moves only revision and retains the value ref.
+  if (revision === 1 && generation === 0) {
+    return (
+      !current.head.tombstone &&
+      !incoming.head.tombstone &&
+      exactJson(incoming.head.valueRef) === exactJson(current.head.valueRef)
+    );
+  }
+  // Delete/removal, save-after-delete and first-save-on-fence move both.
+  if (revision === 1 && generation === 1) {
+    if (current.head.generation === 0) {
+      return current.head.tombstone && !incoming.head.tombstone;
+    }
+    return (
+      current.head.tombstone !== incoming.head.tombstone &&
+      exactJson(incoming.binding) === exactJson(current.binding) &&
+      incoming.policyEpoch === current.policyEpoch
+    );
+  }
+  return false;
+}
+
+function retainedExisting(
+  row: ReplicaRecordRow | ReplicaStageRecordRow,
+  epochs: readonly number[],
+): { result: ProjectEnvReplicaResult; fetch: boolean; changed: false } {
+  const state = rowState(row);
+  return {
+    result: rowResult(row),
+    fetch:
+      !state.head.tombstone &&
+      row.materialization !== "installed" &&
+      desiredMaterialization(state, epochs).kind === "unavailable",
+    changed: false,
+  };
+}
+
+function desiredMaterialization(
+  state: ProjectEnvReplicaBindingState,
+  epochs: readonly number[],
+): ProjectEnvReplicaMaterialization {
+  if (state.head.tombstone) {
+    return { kind: "withheld", reason: "tombstone" };
+  }
+  if (state.policyEpoch === null || !epochs.includes(state.policyEpoch)) {
+    return { kind: "withheld", reason: "policy_epoch_unknown" };
+  }
+  if (state.binding?.kind === "omit") {
+    return { kind: "withheld", reason: "binding_omits" };
+  }
+  if (state.binding?.kind === "withhold") {
+    return { kind: "withheld", reason: state.binding.reason };
+  }
+  return { kind: "unavailable", reason: "materialization_pending" };
+}
+
+function putStageRecord(
+  tx: ReplicaTransaction,
+  attemptId: string,
+  projectId: string,
+  state: ProjectEnvReplicaBindingState,
+  materialization: ProjectEnvReplicaMaterialization,
+  present: boolean,
+): void {
+  tx.insert(schema.hostProjectEnvReplicaStageRecords)
+    .values({
+      attemptId,
+      projectId,
+      key: state.key,
+      ...stateColumns(state),
+      ...materializationColumns(materialization),
+      present,
+      updatedAt: Date.now(),
+    })
+    .onConflictDoUpdate({
+      target: [
+        schema.hostProjectEnvReplicaStageRecords.attemptId,
+        schema.hostProjectEnvReplicaStageRecords.projectId,
+        schema.hostProjectEnvReplicaStageRecords.key,
+      ],
+      set: {
+        ...stateColumns(state),
+        ...materializationColumns(materialization),
+        present,
+        updatedAt: Date.now(),
+      },
+    })
+    .run();
+}
+
+function putLiveRecord(
+  tx: ReplicaTransaction,
+  projectId: string,
+  state: ProjectEnvReplicaBindingState,
+  materialization: ProjectEnvReplicaMaterialization,
+): void {
+  tx.insert(schema.hostProjectEnvReplicaRecords)
+    .values({
+      projectId,
+      key: state.key,
+      ...stateColumns(state),
+      ...materializationColumns(materialization),
+      updatedAt: Date.now(),
+    })
+    .onConflictDoUpdate({
+      target: [
+        schema.hostProjectEnvReplicaRecords.projectId,
+        schema.hostProjectEnvReplicaRecords.key,
+      ],
+      set: {
+        ...stateColumns(state),
+        ...materializationColumns(materialization),
+        updatedAt: Date.now(),
+      },
+    })
+    .run();
+}
+
+function stageRecord(
+  tx: ReplicaTransaction,
+  attemptId: string,
+  projectId: string,
+  key: string,
+): ReplicaStageRecordRow | null {
+  return (
+    tx
+      .select()
+      .from(schema.hostProjectEnvReplicaStageRecords)
+      .where(
+        and(
+          eq(schema.hostProjectEnvReplicaStageRecords.attemptId, attemptId),
+          eq(schema.hostProjectEnvReplicaStageRecords.projectId, projectId),
+          eq(schema.hostProjectEnvReplicaStageRecords.key, key),
+        ),
+      )
+      .get() ?? null
+  );
+}
+
+function liveRecord(
+  tx: ReplicaTransaction,
+  projectId: string,
+  key: string,
+): ReplicaRecordRow | null {
+  return (
+    tx
+      .select()
+      .from(schema.hostProjectEnvReplicaRecords)
+      .where(
+        and(
+          eq(schema.hostProjectEnvReplicaRecords.projectId, projectId),
+          eq(schema.hostProjectEnvReplicaRecords.key, key),
+        ),
+      )
+      .get() ?? null
+  );
+}
+
+function resetStagedProject(
+  tx: ReplicaTransaction,
+  attemptId: string,
+  projectId: string,
+): void {
+  tx.delete(schema.hostProjectEnvReplicaStageValues)
+    .where(
+      and(
+        eq(schema.hostProjectEnvReplicaStageValues.attemptId, attemptId),
+        eq(schema.hostProjectEnvReplicaStageValues.projectId, projectId),
+      ),
+    )
+    .run();
+  tx.delete(schema.hostProjectEnvReplicaStageRecords)
+    .where(
+      and(
+        eq(schema.hostProjectEnvReplicaStageRecords.attemptId, attemptId),
+        eq(schema.hostProjectEnvReplicaStageRecords.projectId, projectId),
+      ),
+    )
+    .run();
+  const records = tx
+    .select()
+    .from(schema.hostProjectEnvReplicaRecords)
+    .where(eq(schema.hostProjectEnvReplicaRecords.projectId, projectId))
+    .all();
+  for (const row of records) {
+    putStageRecord(
+      tx,
+      attemptId,
+      projectId,
+      rowState(row),
+      rowMaterialization(row),
+      false,
+    );
+  }
+  const values = tx
+    .select()
+    .from(schema.hostProjectEnvReplicaValues)
+    .where(eq(schema.hostProjectEnvReplicaValues.projectId, projectId))
+    .all();
+  for (const row of values) {
+    tx.insert(schema.hostProjectEnvReplicaStageValues)
+      .values({ attemptId, ...row })
+      .run();
+  }
+}
+
+function retainStageState(
+  tx: ReplicaTransaction,
+  attemptId: string,
+  projectId: string,
+  incoming: ProjectEnvReplicaBindingState,
+  epochs: readonly number[],
+): { result: ProjectEnvReplicaResult; fetch: boolean } {
+  const stored = stageRecord(tx, attemptId, projectId, incoming.key);
+  if (stored !== null) {
+    const current = rowState(stored);
+    const order = stateOrder(incoming, current);
+    if (order === "older" || order === "conflict") {
+      putStageRecord(
+        tx,
+        attemptId,
+        projectId,
+        current,
+        rowMaterialization(stored),
+        true,
+      );
+      const retained = stageRecord(tx, attemptId, projectId, incoming.key)!;
+      return {
+        result: rowResult(retained),
+        fetch:
+          !current.head.tombstone &&
+          retained.materialization !== "installed" &&
+          desiredMaterialization(current, epochs).kind === "unavailable",
+      };
+    }
+    if (order === "same") {
+      const desired = desiredMaterialization(current, epochs);
+      const keep =
+        stored.materialization === "installed" || desired.kind === "withheld"
+          ? desired.kind === "withheld"
+            ? desired
+            : rowMaterialization(stored)
+          : desired;
+      if (keep.kind !== "installed") {
+        tx.delete(schema.hostProjectEnvReplicaStageValues)
+          .where(
+            and(
+              eq(schema.hostProjectEnvReplicaStageValues.attemptId, attemptId),
+              eq(schema.hostProjectEnvReplicaStageValues.projectId, projectId),
+              eq(schema.hostProjectEnvReplicaStageValues.key, incoming.key),
+            ),
+          )
+          .run();
+      }
+      putStageRecord(tx, attemptId, projectId, current, keep, true);
+      return {
+        result: rowResult(stageRecord(tx, attemptId, projectId, incoming.key)!),
+        fetch: keep.kind === "unavailable",
+      };
+    }
+  }
+  const desired = desiredMaterialization(incoming, epochs);
+  tx.delete(schema.hostProjectEnvReplicaStageValues)
+    .where(
+      and(
+        eq(schema.hostProjectEnvReplicaStageValues.attemptId, attemptId),
+        eq(schema.hostProjectEnvReplicaStageValues.projectId, projectId),
+        eq(schema.hostProjectEnvReplicaStageValues.key, incoming.key),
+      ),
+    )
+    .run();
+  putStageRecord(tx, attemptId, projectId, incoming, desired, true);
+  return {
+    result: rowResult(stageRecord(tx, attemptId, projectId, incoming.key)!),
+    fetch: desired.kind === "unavailable",
+  };
+}
+
+function retainLiveState(
+  tx: ReplicaTransaction,
+  projectId: string,
+  incoming: ProjectEnvReplicaBindingState,
+  epochs: readonly number[],
+): { result: ProjectEnvReplicaResult; fetch: boolean; changed: boolean } {
+  const stored = liveRecord(tx, projectId, incoming.key);
+  if (stored !== null) {
+    const current = rowState(stored);
+    const order = stateOrder(incoming, current);
+    if (order === "older" || order === "conflict") {
+      return {
+        result: rowResult(stored),
+        fetch:
+          !current.head.tombstone &&
+          stored.materialization !== "installed" &&
+          desiredMaterialization(current, epochs).kind === "unavailable",
+        changed: false,
+      };
+    }
+    if (order === "same") {
+      const desired = desiredMaterialization(current, epochs);
+      if (stored.materialization === "installed" && desired.kind !== "withheld") {
+        return { result: rowResult(stored), fetch: false, changed: false };
+      }
+      tx.delete(schema.hostProjectEnvReplicaValues)
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaValues.projectId, projectId),
+            eq(schema.hostProjectEnvReplicaValues.key, incoming.key),
+          ),
+        )
+        .run();
+      putLiveRecord(tx, projectId, current, desired);
+      return {
+        result: rowResult(liveRecord(tx, projectId, incoming.key)!),
+        fetch: desired.kind === "unavailable",
+        changed: true,
+      };
+    }
+  }
+  const desired = desiredMaterialization(incoming, epochs);
+  tx.delete(schema.hostProjectEnvReplicaValues)
+    .where(
+      and(
+        eq(schema.hostProjectEnvReplicaValues.projectId, projectId),
+        eq(schema.hostProjectEnvReplicaValues.key, incoming.key),
+      ),
+    )
+    .run();
+  putLiveRecord(tx, projectId, incoming, desired);
+  return {
+    result: rowResult(liveRecord(tx, projectId, incoming.key)!),
+    fetch: desired.kind === "unavailable",
+    changed: true,
+  };
+}
+
+function defaultValueReader(): ProjectEnvReplicaValueReader | null {
+  const store = configuredCredentialStore();
+  if (store === null) return null;
+  return {
+    readStaged: (name) => store.get(name),
+    readLegacy: async (name, version) => {
+      if (store.getVersion === undefined) return null;
+      const found = await store.getVersion(name, version);
+      return found === null
+        ? null
+        : { value: found.value, version: found.version };
+    },
+  };
+}
+
+export function projectEnvReplicaStagedParameterName(
+  projectId: string,
+  key: string,
+  stagingId: string,
+): string {
+  const digest = createHash("sha256").update(key, "utf8").digest("hex");
+  if (
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(
+      stagingId,
+    )
+  ) {
+    throw new Error("invalid staged project environment identity");
+  }
+  return parameterName(
+    credentialStorePrefix(),
+    "projects",
+    projectId,
+    "env-values",
+    digest,
+    stagingId,
+  );
+}
+
+function exactObject(
+  value: unknown,
+  keys: readonly string[],
+): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === keys.length &&
+    keys.every((key) => Object.hasOwn(value, key))
+  );
+}
+
+async function readMaterializedValue(
+  orgId: string,
+  projectId: string,
+  state: ProjectEnvReplicaBindingState,
+  reader: ProjectEnvReplicaValueReader | null,
+): Promise<{ value: string } | { reason: string }> {
+  if (state.head.tombstone || state.head.valueRef === null) {
+    return { reason: "tombstone" };
+  }
+  if (reader === null) return { reason: "credential_store_unavailable" };
+  const ref = state.head.valueRef;
+  try {
+    if (ref.kind === "staged") {
+      const name = projectEnvReplicaStagedParameterName(
+        projectId,
+        state.key,
+        ref.stagingId,
+      );
+      const raw = await reader.readStaged(name);
+      if (raw === null) return { reason: "value_missing" };
+      const parsed: unknown = JSON.parse(raw);
+      if (
+        !exactObject(parsed, [
+          "v",
+          "kind",
+          "orgId",
+          "projectId",
+          "key",
+          "stagingId",
+          "value",
+        ]) ||
+        parsed.v !== 2 ||
+        parsed.kind !== "project-env" ||
+        parsed.orgId !== orgId ||
+        parsed.projectId !== projectId ||
+        parsed.key !== state.key ||
+        parsed.stagingId !== ref.stagingId ||
+        typeof parsed.value !== "string"
+      ) {
+        return { reason: "value_envelope_mismatch" };
+      }
+      return { value: parsed.value };
+    }
+    const name = projectEnvParameterName(projectId, state.key);
+    if (name === null) return { reason: "value_reference_invalid" };
+    const found = await reader.readLegacy(name, ref.ssmVersion);
+    if (found === null) return { reason: "value_missing" };
+    if (found.version !== ref.ssmVersion) {
+      return { reason: "value_version_mismatch" };
+    }
+    const envelope = parseStoredProjectEnv(found.value);
+    if (envelope.projectId !== projectId || envelope.key !== state.key) {
+      return { reason: "value_envelope_mismatch" };
+    }
+    return { value: envelope.value };
+  } catch {
+    return { reason: "value_unavailable" };
+  }
+}
+
+async function materializeStage(
+  attemptId: string,
+  projectId: string,
+  key: string,
+  reader: ProjectEnvReplicaValueReader | null,
+): Promise<void> {
+  const before = getDb().transaction((tx) => {
+    const authority = authorityRow(tx);
+    if (authority.attemptId !== attemptId) return null;
+    const row = stageRecord(tx, attemptId, projectId, key);
+    if (row === null) return null;
+    const state = rowState(row);
+    return row.materialization === "unavailable"
+      ? { state, orgId: authorityOrgId(authority) }
+      : null;
+  });
+  if (before === null) return;
+  const fetched = await readMaterializedValue(
+    before.orgId,
+    projectId,
+    before.state,
+    reader,
+  );
+  getDb().transaction((tx) => {
+    const authority = authorityRow(tx);
+    if (authority.attemptId !== attemptId) return;
+    const current = stageRecord(tx, attemptId, projectId, key);
+    if (current === null || !sameState(rowState(current), before.state)) return;
+    if ("value" in fetched) {
+      tx.insert(schema.hostProjectEnvReplicaStageValues)
+        .values({
+          attemptId,
+          projectId,
+          key,
+          revision: before.state.head.revision,
+          generation: before.state.head.generation,
+          valueRefJson: JSON.stringify(before.state.head.valueRef),
+          valueEnc: sealProjectEnvValueForStorage(fetched.value),
+          updatedAt: Date.now(),
+        })
+        .onConflictDoUpdate({
+          target: [
+            schema.hostProjectEnvReplicaStageValues.attemptId,
+            schema.hostProjectEnvReplicaStageValues.projectId,
+            schema.hostProjectEnvReplicaStageValues.key,
+          ],
+          set: {
+            revision: before.state.head.revision,
+            generation: before.state.head.generation,
+            valueRefJson: JSON.stringify(before.state.head.valueRef),
+            valueEnc: sealProjectEnvValueForStorage(fetched.value),
+            updatedAt: Date.now(),
+          },
+        })
+        .run();
+      putStageRecord(
+        tx,
+        attemptId,
+        projectId,
+        before.state,
+        { kind: "installed" },
+        current.present,
+      );
+    } else {
+      tx.delete(schema.hostProjectEnvReplicaStageValues)
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaStageValues.attemptId, attemptId),
+            eq(schema.hostProjectEnvReplicaStageValues.projectId, projectId),
+            eq(schema.hostProjectEnvReplicaStageValues.key, key),
+          ),
+        )
+        .run();
+      putStageRecord(
+        tx,
+        attemptId,
+        projectId,
+        before.state,
+        { kind: "unavailable", reason: fetched.reason },
+        current.present,
+      );
+    }
+  });
+}
+
+async function materializeLive(
+  projectId: string,
+  key: string,
+  reader: ProjectEnvReplicaValueReader | null,
+): Promise<boolean> {
+  const before = getDb().transaction((tx) => {
+    const authority = authorityRow(tx);
+    const row = liveRecord(tx, projectId, key);
+    if (row === null || row.materialization !== "unavailable") return null;
+    return { state: rowState(row), orgId: authorityOrgId(authority) };
+  });
+  if (before === null) return false;
+  const fetched = await readMaterializedValue(
+    before.orgId,
+    projectId,
+    before.state,
+    reader,
+  );
+  const changed = getDb().transaction((tx) => {
+    const current = liveRecord(tx, projectId, key);
+    if (current === null || !sameState(rowState(current), before.state)) return false;
+    if ("value" in fetched) {
+      tx.insert(schema.hostProjectEnvReplicaValues)
+        .values({
+          projectId,
+          key,
+          revision: before.state.head.revision,
+          generation: before.state.head.generation,
+          valueRefJson: JSON.stringify(before.state.head.valueRef),
+          valueEnc: sealProjectEnvValueForStorage(fetched.value),
+          updatedAt: Date.now(),
+        })
+        .onConflictDoUpdate({
+          target: [
+            schema.hostProjectEnvReplicaValues.projectId,
+            schema.hostProjectEnvReplicaValues.key,
+          ],
+          set: {
+            revision: before.state.head.revision,
+            generation: before.state.head.generation,
+            valueRefJson: JSON.stringify(before.state.head.valueRef),
+            valueEnc: sealProjectEnvValueForStorage(fetched.value),
+            updatedAt: Date.now(),
+          },
+        })
+        .run();
+      putLiveRecord(tx, projectId, before.state, { kind: "installed" });
+    } else {
+      tx.delete(schema.hostProjectEnvReplicaValues)
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaValues.projectId, projectId),
+            eq(schema.hostProjectEnvReplicaValues.key, key),
+          ),
+        )
+        .run();
+      putLiveRecord(tx, projectId, before.state, {
+        kind: "unavailable",
+        reason: fetched.reason,
+      });
+    }
+    return true;
+  });
+  if (changed) noteProjectEnvValueMutation(projectId);
+  return changed;
+}
+
+function pageFits(
+  frame: ProjectEnvReplicaPageFrame,
+  states: readonly ProjectEnvReplicaBindingState[],
+  policy: readonly number[],
+  appliedThrough: ProjectEnvDeliveryCursor,
+): boolean {
+  const results: ProjectEnvReplicaResult[] = states.map((state) => {
+    const candidate: unknown = {
+      state,
+      materialization: state.head.tombstone
+        ? { kind: "withheld", reason: MAX_REASON }
+        : { kind: "unavailable", reason: MAX_REASON },
+    };
+    if (!isProjectEnvReplicaResult(candidate)) {
+      throw new ProjectEnvReplicaCorruptError(
+        "valid replica state could not form a page result",
+      );
+    }
+    return candidate;
+  });
+  const ack = {
+    kind: "env.replica.ack",
+    opId: frame.opId,
+    ok: true,
+    phase: "page",
+    attemptId: frame.attemptId,
+    projectId: frame.projectId,
+    after: frame.after,
+    recordVersion: frame.recordVersion,
+    results,
+    complete: frame.complete,
+    policyEpochs: policy,
+    appliedThrough,
+  };
+  return Buffer.byteLength(JSON.stringify(ack), "utf8") <= MAX_PROJECT_ENV_ACK_PAGE_BYTES;
+}
+
+/** Close the gate and create an exact whole-task staging view. */
+export function beginProjectEnvReplica(
+  frame: ProjectEnvReplicaBeginFrame,
+  keptPolicyEpochs: readonly number[],
+  orgId: string,
+): ProjectEnvReplicaBeginResult {
+  if (
+    !isProjectEnvReplicaBeginFrame(frame) ||
+    !isProjectEnvPolicyEpochs(keptPolicyEpochs) ||
+    !isParameterPathSegment(orgId)
+  ) {
+    throw new Error("invalid project environment replica begin");
+  }
+  const beforeProjects = sortedProjectIds(getDb());
+  const result = getDb().transaction((tx) => {
+    const before = authorityRow(tx);
+    if (before.activated && before.orgId !== orgId) {
+      throw new ProjectEnvReplicaCorruptError(
+        "replica organization cannot change after activation",
+      );
+    }
+    const changedStream = before.streamId !== frame.attempt.streamId;
+    if (changedStream) {
+      // Receipts only deduplicate one stream. A whole-task replica starts a
+      // fresh stream for each incarnation/reconnect, so retaining older rows
+      // cannot answer a future delivery and would grow without bound.
+      tx.delete(schema.hostProjectEnvReplicaReceipts).run();
+    }
+    tx.delete(schema.hostProjectEnvReplicaStageValues).run();
+    tx.delete(schema.hostProjectEnvReplicaStageRecords).run();
+    tx.delete(schema.hostProjectEnvReplicaStageProjects).run();
+    for (const projectId of frame.projectIds) {
+      tx.insert(schema.hostProjectEnvReplicaStageProjects)
+        .values({
+          attemptId: frame.attempt.attemptId,
+          projectId,
+          recordVersion: null,
+          lastKey: null,
+          complete: false,
+        })
+        .run();
+      resetStagedProject(tx, frame.attempt.attemptId, projectId);
+    }
+    tx.update(schema.hostProjectEnvReplicaAuthority)
+      .set({
+        activated: true,
+        gateOpen: false,
+        streamId: frame.attempt.streamId,
+        appliedSequence: changedStream ? 0 : before.appliedSequence,
+        attemptId: frame.attempt.attemptId,
+        orgId,
+        policyEpochsJson: JSON.stringify(keptPolicyEpochs),
+        updatedAt: Date.now(),
+      })
+      .where(eq(schema.hostProjectEnvReplicaAuthority.id, "replica"))
+      .run();
+    return {
+      appliedThrough: {
+        streamId: frame.attempt.streamId,
+        sequence: changedStream ? 0 : before.appliedSequence,
+      },
+      policyEpochs: [...keptPolicyEpochs],
+    };
+  });
+  notifyProjects([...beforeProjects, ...frame.projectIds]);
+  return result;
+}
+
+/** Install one stable, canonical page into the closed staging view. */
+export async function applyProjectEnvReplicaPage(
+  frame: ProjectEnvReplicaPageFrame,
+  reader: ProjectEnvReplicaValueReader | null = defaultValueReader(),
+): Promise<ProjectEnvReplicaPageResult> {
+  if (!isProjectEnvReplicaPageFrame(frame)) {
+    throw new Error("invalid project environment replica page");
+  }
+  type Prepared =
+    | { done: ProjectEnvReplicaPageResult }
+    | {
+        done?: never;
+        fetchKeys: string[];
+        epochs: number[];
+        appliedThrough: ProjectEnvDeliveryCursor;
+      };
+  const prepared: Prepared = getDb().transaction((tx): Prepared => {
+    const authority = authorityRow(tx);
+    const appliedThrough = requiredCursor(authority);
+    const epochs = policyEpochs(authority);
+    const refuse = (code: string): ProjectEnvReplicaPageResult => ({
+      ok: false,
+      attemptId: frame.attemptId,
+      code,
+      policyEpochs: epochs,
+      appliedThrough,
+    });
+    if (authority.attemptId !== frame.attemptId || authority.gateOpen) {
+      return { done: refuse("reconciliation_attempt_mismatch") } as const;
+    }
+    if (!pageFits(frame, frame.records, epochs, appliedThrough)) {
+      return { done: refuse("ack_page_too_large") } as const;
+    }
+    const staged = tx
+      .select()
+      .from(schema.hostProjectEnvReplicaStageProjects)
+      .where(
+        and(
+          eq(schema.hostProjectEnvReplicaStageProjects.attemptId, frame.attemptId),
+          eq(schema.hostProjectEnvReplicaStageProjects.projectId, frame.projectId),
+        ),
+      )
+      .get();
+    if (!staged) return { done: refuse("project_not_in_attempt") } as const;
+    const liveVersion =
+      tx
+        .select({ recordVersion: schema.hostProjectEnvReplicaProjects.recordVersion })
+        .from(schema.hostProjectEnvReplicaProjects)
+        .where(eq(schema.hostProjectEnvReplicaProjects.projectId, frame.projectId))
+        .get()?.recordVersion ?? 0;
+    if (frame.recordVersion < liveVersion) {
+      return { done: refuse("record_version_stale") } as const;
+    }
+    if (frame.after === null) {
+      resetStagedProject(tx, frame.attemptId, frame.projectId);
+      tx.update(schema.hostProjectEnvReplicaStageProjects)
+        .set({
+          recordVersion: frame.recordVersion,
+          lastKey: null,
+          complete: false,
+        })
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaStageProjects.attemptId, frame.attemptId),
+            eq(schema.hostProjectEnvReplicaStageProjects.projectId, frame.projectId),
+          ),
+        )
+        .run();
+    } else if (
+      staged.complete ||
+      staged.recordVersion !== frame.recordVersion ||
+      staged.lastKey !== frame.after
+    ) {
+      return { done: refuse("snapshot_page_mismatch") } as const;
+    }
+    const fetchKeys: string[] = [];
+    const retainedStates: ProjectEnvReplicaBindingState[] = [];
+    let sameVersionConflict = false;
+    for (const state of frame.records) {
+      if (frame.recordVersion === liveVersion) {
+        const before = stageRecord(
+          tx,
+          frame.attemptId,
+          frame.projectId,
+          state.key,
+        );
+        if (
+          before === null ||
+          stateOrder(state, rowState(before)) !== "same"
+        ) {
+          sameVersionConflict = true;
+        }
+      }
+      const retained = retainStageState(
+        tx,
+        frame.attemptId,
+        frame.projectId,
+        state,
+        epochs,
+      );
+      retainedStates.push(retained.result.state);
+      if (retained.fetch) fetchKeys.push(retained.result.state.key);
+    }
+    // A machine ahead of/conflicting with the page echoes what it retained.
+    // That state can be wider than the incoming one, so only sizing the
+    // request would permit an oversized acknowledgement.
+    if (!pageFits(frame, retainedStates, epochs, appliedThrough)) {
+      return { done: refuse("ack_page_too_large") };
+    }
+    if (sameVersionConflict) {
+      return { done: refuse("snapshot_version_conflict") };
+    }
+    if (frame.complete && frame.recordVersion === liveVersion) {
+      const liveRows = tx
+        .select()
+        .from(schema.hostProjectEnvReplicaRecords)
+        .where(eq(schema.hostProjectEnvReplicaRecords.projectId, frame.projectId))
+        .orderBy(asc(schema.hostProjectEnvReplicaRecords.key))
+        .all();
+      const stagedRows = tx
+        .select()
+        .from(schema.hostProjectEnvReplicaStageRecords)
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaStageRecords.attemptId, frame.attemptId),
+            eq(schema.hostProjectEnvReplicaStageRecords.projectId, frame.projectId),
+          ),
+        )
+        .orderBy(asc(schema.hostProjectEnvReplicaStageRecords.key))
+        .all()
+        .filter((row) => row.present);
+      if (
+        liveRows.length !== stagedRows.length ||
+        liveRows.some(
+          (row, index) =>
+            stagedRows[index] === undefined ||
+            !sameState(rowState(row), rowState(stagedRows[index]!)),
+        )
+      ) {
+        return { done: refuse("snapshot_version_conflict") };
+      }
+    }
+    tx.update(schema.hostProjectEnvReplicaStageProjects)
+      .set({
+        recordVersion: frame.recordVersion,
+        lastKey: frame.records.at(-1)?.key ?? null,
+        complete: frame.complete,
+      })
+      .where(
+        and(
+          eq(schema.hostProjectEnvReplicaStageProjects.attemptId, frame.attemptId),
+          eq(schema.hostProjectEnvReplicaStageProjects.projectId, frame.projectId),
+        ),
+      )
+      .run();
+    return { fetchKeys, epochs, appliedThrough } as const;
+  });
+  if (prepared.done !== undefined) return prepared.done;
+  for (const key of prepared.fetchKeys) {
+    await materializeStage(frame.attemptId, frame.projectId, key, reader);
+  }
+  return getDb().transaction((tx) => {
+    const authority = authorityRow(tx);
+    const appliedThrough = requiredCursor(authority);
+    const epochs = policyEpochs(authority);
+    if (authority.attemptId !== frame.attemptId || authority.gateOpen) {
+      return {
+        ok: false,
+        attemptId: frame.attemptId,
+        code: "reconciliation_attempt_mismatch",
+        policyEpochs: epochs,
+        appliedThrough,
+      };
+    }
+    const results = frame.records.map((state) => {
+      const row = stageRecord(tx, frame.attemptId, frame.projectId, state.key);
+      if (row === null) {
+        throw new ProjectEnvReplicaCorruptError(
+          "staged replica page record disappeared",
+        );
+      }
+      return rowResult(row);
+    });
+    return {
+      ok: true,
+      attemptId: frame.attemptId,
+      projectId: frame.projectId,
+      after: frame.after,
+      recordVersion: frame.recordVersion,
+      results,
+      complete: frame.complete,
+      policyEpochs: epochs,
+      appliedThrough,
+    };
+  });
+}
+
+function receiptResult(
+  row: ReplicaReceiptRow,
+  authority: ReplicaAuthorityRow,
+  projectId: string,
+): ProjectEnvReplicaApplyResult {
+  const appliedThrough = requiredCursor(authority);
+  const epochs = policyEpochs(authority);
+  if (!row.ok) {
+    if (row.code === null) {
+      throw new ProjectEnvReplicaCorruptError("replica refusal has no code");
+    }
+    return {
+      ok: false,
+      replayed: true,
+      consumed: true,
+      attemptId: authority.attemptId,
+      code: row.code,
+      policyEpochs: epochs,
+      appliedThrough,
+    };
+  }
+  const parsed = parseJson(row.resultJson, "replica delivery result");
+  if (!isProjectEnvReplicaResult(parsed) || row.recordVersion === null) {
+    throw new ProjectEnvReplicaCorruptError(
+      "stored replica delivery result is invalid",
+    );
+  }
+  return {
+    ok: true,
+    replayed: true,
+    attemptId: authority.attemptId,
+    projectId,
+    recordVersion: row.recordVersion,
+    result: parsed,
+    policyEpochs: epochs,
+    appliedThrough,
+  };
+}
+
+function saveReceipt(
+  tx: ReplicaTransaction,
+  frame: ProjectEnvReplicaApplyFrame,
+  outcome:
+    | { ok: true; result: ProjectEnvReplicaResult; recordVersion: number }
+    | { ok: false; code: string },
+): void {
+  tx.insert(schema.hostProjectEnvReplicaReceipts)
+    .values({
+      streamId: frame.delivery.streamId,
+      sequence: frame.delivery.sequence,
+      requestMac: requestMac(frame),
+      resultJson: outcome.ok ? JSON.stringify(outcome.result) : null,
+      recordVersion: outcome.ok ? outcome.recordVersion : null,
+      ok: outcome.ok,
+      code: outcome.ok ? null : outcome.code,
+      createdAt: Date.now(),
+    })
+    .run();
+  tx.update(schema.hostProjectEnvReplicaAuthority)
+    .set({ appliedSequence: frame.delivery.sequence, updatedAt: Date.now() })
+    .where(eq(schema.hostProjectEnvReplicaAuthority.id, "replica"))
+    .run();
+}
+
+function transientApply(
+  authority: ReplicaAuthorityRow,
+  code: string,
+): ProjectEnvReplicaApplyResult {
+  return {
+    ok: false,
+    replayed: false,
+    consumed: false,
+    attemptId: authority.attemptId,
+    code,
+    policyEpochs: policyEpochs(authority),
+    appliedThrough: requiredCursor(authority),
+  };
+}
+
+/** Apply/replay exactly one ordered cloud-authoritative delta. */
+export async function applyProjectEnvReplicaDelivery(
+  frame: ProjectEnvReplicaApplyFrame,
+  reader: ProjectEnvReplicaValueReader | null = defaultValueReader(),
+): Promise<ProjectEnvReplicaApplyResult> {
+  if (!isProjectEnvReplicaApplyFrame(frame)) {
+    throw new Error("invalid project environment replica delivery");
+  }
+  type Prepared =
+    | { done: ProjectEnvReplicaApplyResult }
+    | {
+        done?: never;
+        retained: {
+          result: ProjectEnvReplicaResult;
+          fetch: boolean;
+          changed: boolean;
+        };
+        actualVersion: number;
+        attemptId: string | null;
+        changedLive: boolean;
+      };
+  const prepared: Prepared = getDb().transaction((tx): Prepared => {
+    const authority = authorityRow(tx);
+    if (!authority.activated) {
+      throw new ProjectEnvReplicaCorruptError(
+        "replica delivery arrived before activation",
+      );
+    }
+    const current = requiredCursor(authority);
+    if (frame.delivery.streamId !== current.streamId) {
+      return { done: transientApply(authority, "stream_mismatch") } as const;
+    }
+    if (frame.delivery.sequence <= current.sequence) {
+      const receipt = tx
+        .select()
+        .from(schema.hostProjectEnvReplicaReceipts)
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaReceipts.streamId, frame.delivery.streamId),
+            eq(schema.hostProjectEnvReplicaReceipts.sequence, frame.delivery.sequence),
+          ),
+        )
+        .get();
+      if (!receipt) return { done: transientApply(authority, "receipt_missing") } as const;
+      if (!sameMac(receipt.requestMac, requestMac(frame))) {
+        return {
+          done: {
+            ok: false,
+            replayed: true,
+            consumed: true,
+            attemptId: authority.attemptId,
+            code: "delivery_conflict",
+            policyEpochs: policyEpochs(authority),
+            appliedThrough: current,
+          },
+        } as const;
+      }
+      const replay = receiptResult(receipt, authority, frame.projectId);
+      return { done: replay } as const;
+    }
+    if (frame.delivery.sequence !== current.sequence + 1) {
+      return { done: transientApply(authority, "delivery_gap") } as const;
+    }
+    if (
+      authority.gateOpen
+        ? frame.reconciliationAttemptId !== undefined
+        : authority.attemptId === null ||
+          frame.reconciliationAttemptId !== authority.attemptId
+    ) {
+      return {
+        done: transientApply(authority, "reconciliation_attempt_mismatch"),
+      } as const;
+    }
+    const epochs = policyEpochs(authority);
+    const consumed = (code: string): Prepared => {
+      saveReceipt(tx, frame, { ok: false, code });
+      const after = authorityRow(tx);
+      return {
+        done: {
+          ok: false,
+          replayed: false,
+          consumed: true,
+          attemptId: after.attemptId,
+          code,
+          policyEpochs: epochs,
+          appliedThrough: requiredCursor(after),
+        },
+      };
+    };
+    let retained:
+      | { result: ProjectEnvReplicaResult; fetch: boolean; changed: boolean }
+      | null = null;
+    let actualVersion: number;
+    if (authority.attemptId !== null) {
+      const staged = tx
+        .select()
+        .from(schema.hostProjectEnvReplicaStageProjects)
+        .where(
+          and(
+            eq(schema.hostProjectEnvReplicaStageProjects.attemptId, authority.attemptId),
+            eq(schema.hostProjectEnvReplicaStageProjects.projectId, frame.projectId),
+          ),
+        )
+        .get();
+      if (!staged || !staged.complete || staged.recordVersion === null) {
+        return { done: transientApply(authority, "snapshot_incomplete") } as const;
+      }
+      if (frame.recordVersion > staged.recordVersion + 1) {
+        return { done: transientApply(authority, "record_version_gap") } as const;
+      }
+      const stored = stageRecord(
+        tx,
+        authority.attemptId,
+        frame.projectId,
+        frame.state.key,
+      );
+      const order =
+        stored === null ? "newer" : stateOrder(frame.state, rowState(stored));
+      const advances =
+        frame.recordVersion === staged.recordVersion + 1 &&
+        order === "newer" &&
+        isReachableRecordAdvance(
+          frame.state,
+          stored === null ? null : rowState(stored),
+        );
+      if (advances) {
+        const stagedResult = retainStageState(
+          tx,
+          authority.attemptId,
+          frame.projectId,
+          frame.state,
+          epochs,
+        );
+        retained = { ...stagedResult, changed: false };
+        actualVersion = frame.recordVersion;
+        tx.update(schema.hostProjectEnvReplicaStageProjects)
+          .set({ recordVersion: actualVersion })
+          .where(
+            and(
+              eq(schema.hostProjectEnvReplicaStageProjects.attemptId, authority.attemptId),
+              eq(schema.hostProjectEnvReplicaStageProjects.projectId, frame.projectId),
+            ),
+          )
+          .run();
+      } else if (stored !== null) {
+        // A lower/equal version, an older state, or an invalid transition is
+        // answered with what this replica actually retained. The cloud can
+        // then quarantine/reconcile without the stream getting stuck.
+        retained = retainedExisting(stored, epochs);
+        actualVersion = staged.recordVersion;
+      } else {
+        return consumed("record_version_conflict");
+      }
+    } else {
+      const project = tx
+        .select()
+        .from(schema.hostProjectEnvReplicaProjects)
+        .where(eq(schema.hostProjectEnvReplicaProjects.projectId, frame.projectId))
+        .get();
+      if (!project) {
+        return consumed("project_not_in_replica");
+      }
+      if (frame.recordVersion > project.recordVersion + 1) {
+        return { done: transientApply(authority, "record_version_gap") } as const;
+      }
+      const stored = liveRecord(tx, frame.projectId, frame.state.key);
+      const order =
+        stored === null ? "newer" : stateOrder(frame.state, rowState(stored));
+      const advances =
+        frame.recordVersion === project.recordVersion + 1 &&
+        order === "newer" &&
+        isReachableRecordAdvance(
+          frame.state,
+          stored === null ? null : rowState(stored),
+        );
+      if (advances) {
+        retained = retainLiveState(tx, frame.projectId, frame.state, epochs);
+        actualVersion = frame.recordVersion;
+        tx.update(schema.hostProjectEnvReplicaProjects)
+          .set({ recordVersion: actualVersion })
+          .where(eq(schema.hostProjectEnvReplicaProjects.projectId, frame.projectId))
+          .run();
+      } else if (stored !== null) {
+        retained = retainedExisting(stored, epochs);
+        actualVersion = project.recordVersion;
+      } else {
+        return consumed("record_version_conflict");
+      }
+    }
+    return {
+      retained,
+      actualVersion,
+      attemptId: authority.attemptId,
+      changedLive: authority.attemptId === null && retained.changed,
+    } as const;
+  });
+  if (prepared.done !== undefined) return prepared.done;
+  if (prepared.changedLive) noteProjectEnvValueMutation(frame.projectId);
+  if (prepared.retained.fetch) {
+    if (prepared.attemptId === null) {
+      await materializeLive(frame.projectId, frame.state.key, reader);
+    } else {
+      await materializeStage(
+        prepared.attemptId,
+        frame.projectId,
+        frame.state.key,
+        reader,
+      );
+    }
+  }
+  return getDb().transaction((tx) => {
+    const authority = authorityRow(tx);
+    const current = requiredCursor(authority);
+    if (
+      frame.delivery.streamId !== current.streamId ||
+      frame.delivery.sequence !== current.sequence + 1 ||
+      authority.attemptId !== prepared.attemptId
+    ) {
+      return transientApply(authority, "replica_state_changed");
+    }
+    const row =
+      prepared.attemptId === null
+        ? liveRecord(tx, frame.projectId, frame.state.key)
+        : stageRecord(
+            tx,
+            prepared.attemptId,
+            frame.projectId,
+            frame.state.key,
+          );
+    if (row === null) {
+      return transientApply(authority, "replica_state_missing");
+    }
+    const result = rowResult(row);
+    saveReceipt(tx, frame, {
+      ok: true,
+      result,
+      recordVersion: prepared.actualVersion,
+    });
+    const after = authorityRow(tx);
+    return {
+      ok: true,
+      replayed: false,
+      attemptId: after.attemptId,
+      projectId: frame.projectId,
+      recordVersion: prepared.actualVersion,
+      result,
+      policyEpochs: policyEpochs(after),
+      appliedThrough: requiredCursor(after),
+    };
+  });
+}
+
+/** Promote the exact staged task view and open the serving gate atomically. */
+export function completeProjectEnvReplica(
+  frame: ProjectEnvReplicaCommitFrame,
+): ProjectEnvReplicaCommitResult {
+  if (!isProjectEnvReplicaCommitFrame(frame)) {
+    throw new Error("invalid project environment replica commit");
+  }
+  const beforeProjects = sortedProjectIds(getDb());
+  const result: ProjectEnvReplicaCommitResult = getDb().transaction(
+    (tx): ProjectEnvReplicaCommitResult => {
+    const authority = authorityRow(tx);
+    const appliedThrough = requiredCursor(authority);
+    const epochs = policyEpochs(authority);
+    const refuse = (code: string): ProjectEnvReplicaCommitResult => ({
+      ok: false,
+      attemptId: frame.attemptId,
+      code,
+      policyEpochs: epochs,
+      appliedThrough,
+    });
+    if (authority.attemptId !== frame.attemptId || authority.gateOpen) {
+      return refuse("reconciliation_attempt_mismatch");
+    }
+    if (
+      frame.highWater.streamId !== appliedThrough.streamId ||
+      frame.highWater.sequence !== appliedThrough.sequence
+    ) {
+      return refuse("delivery_incomplete");
+    }
+    const stagedProjects = tx
+      .select()
+      .from(schema.hostProjectEnvReplicaStageProjects)
+      .where(eq(schema.hostProjectEnvReplicaStageProjects.attemptId, frame.attemptId))
+      .orderBy(asc(schema.hostProjectEnvReplicaStageProjects.projectId))
+      .all();
+    if (
+      stagedProjects.length !== frame.versions.length ||
+      stagedProjects.some(
+        (project, index) =>
+          !project.complete ||
+          project.recordVersion === null ||
+          project.projectId !== frame.versions[index]?.projectId ||
+          project.recordVersion !== frame.versions[index]?.recordVersion,
+      )
+    ) {
+      return refuse("record_version_changed");
+    }
+
+    const records = tx
+      .select()
+      .from(schema.hostProjectEnvReplicaStageRecords)
+      .where(eq(schema.hostProjectEnvReplicaStageRecords.attemptId, frame.attemptId))
+      .orderBy(
+        asc(schema.hostProjectEnvReplicaStageRecords.projectId),
+        asc(schema.hostProjectEnvReplicaStageRecords.key),
+      )
+      .all()
+      .filter((row) => row.present);
+    const liveKeys = new Set(records.map((row) => `${row.projectId}\0${row.key}`));
+    const values = tx
+      .select()
+      .from(schema.hostProjectEnvReplicaStageValues)
+      .where(eq(schema.hostProjectEnvReplicaStageValues.attemptId, frame.attemptId))
+      .all();
+    const valuesByKey = new Map(
+      values.map((row) => [`${row.projectId}\0${row.key}`, row]),
+    );
+    for (const row of records) {
+      const state = rowState(row);
+      const materialization = rowMaterialization(row);
+      const value = valuesByKey.get(`${row.projectId}\0${row.key}`);
+      if (materialization.kind === "installed") {
+        if (
+          value === undefined ||
+          value.revision !== state.head.revision ||
+          value.generation !== state.head.generation ||
+          value.valueRefJson !== JSON.stringify(state.head.valueRef)
+        ) {
+          throw new ProjectEnvReplicaCorruptError(
+            "staged installed value does not match its replica head",
+          );
+        }
+      } else if (value !== undefined) {
+        throw new ProjectEnvReplicaCorruptError(
+          "staged withheld replica record still has a value",
+        );
+      }
+    }
+
+    tx.delete(schema.hostProjectEnvReplicaValues).run();
+    tx.delete(schema.hostProjectEnvReplicaRecords).run();
+    tx.delete(schema.hostProjectEnvReplicaProjects).run();
+    for (const project of stagedProjects) {
+      tx.insert(schema.hostProjectEnvReplicaProjects)
+        .values({
+          projectId: project.projectId,
+          recordVersion: project.recordVersion!,
+        })
+        .run();
+    }
+    for (const row of records) {
+      putLiveRecord(tx, row.projectId, rowState(row), rowMaterialization(row));
+    }
+    for (const row of values) {
+      if (!liveKeys.has(`${row.projectId}\0${row.key}`)) continue;
+      tx.insert(schema.hostProjectEnvReplicaValues)
+        .values({
+          projectId: row.projectId,
+          key: row.key,
+          revision: row.revision,
+          generation: row.generation,
+          valueRefJson: row.valueRefJson,
+          valueEnc: row.valueEnc,
+          updatedAt: Date.now(),
+        })
+        .run();
+    }
+    tx.delete(schema.hostProjectEnvReplicaStageValues).run();
+    tx.delete(schema.hostProjectEnvReplicaStageRecords).run();
+    tx.delete(schema.hostProjectEnvReplicaStageProjects).run();
+    tx.update(schema.hostProjectEnvReplicaAuthority)
+      .set({ gateOpen: true, attemptId: null, updatedAt: Date.now() })
+      .where(eq(schema.hostProjectEnvReplicaAuthority.id, "replica"))
+      .run();
+    return {
+      ok: true,
+      attemptId: frame.attemptId,
+      policyEpochs: epochs,
+      appliedThrough,
+    };
+    },
+  );
+  if (result.ok) {
+    notifyProjects([...beforeProjects, ...frame.versions.map((version) => version.projectId)]);
+  }
+  return result;
+}
+
+/** Each sidecar connection/restart closes the replica before any task read. */
+export function closeProjectEnvReplicaGate(): void {
+  const projects = sortedProjectIds(getDb());
+  getDb().transaction((tx) => {
+    // A snapshot attempt belongs to one authenticated sidecar connection.
+    // Purge it when that connection closes so a replacement cannot resume or
+    // commit work prepared under the old connection.
+    tx.delete(schema.hostProjectEnvReplicaStageValues).run();
+    tx.delete(schema.hostProjectEnvReplicaStageRecords).run();
+    tx.delete(schema.hostProjectEnvReplicaStageProjects).run();
+    tx.update(schema.hostProjectEnvReplicaAuthority)
+      .set({ gateOpen: false, attemptId: null, updatedAt: Date.now() })
+      .where(eq(schema.hostProjectEnvReplicaAuthority.id, "replica"))
+      .run();
+  });
+  notifyProjects(projects);
+}
+
+export function readProjectEnvReplicaStatus(): ProjectEnvReplicaStatus {
+  return getDb().transaction((tx) => {
+    const row = authorityRow(tx);
+    return {
+      activated: row.activated,
+      gateOpen: row.gateOpen,
+      attemptId: row.attemptId,
+      orgId: row.orgId,
+      appliedThrough: cursor(row),
+      policyEpochs: policyEpochs(row),
+      projectIds: sortedProjectIds(tx),
+    };
+  });
+}
+
+/** How long a bindings-capable sidecar TaskUp waits for its first complete
+ * replica reconciliation before returning a retryable admission failure. */
+export const PROJECT_ENV_REPLICA_READY_TIMEOUT_MS = 3 * 60_000;
+
+/**
+ * Wait until the local replica is an activated, committed serving view.
+ *
+ * Subscribe before the second read so a begin/commit between the first read
+ * and listener installation cannot be lost. Gate changes share the task-env
+ * invalidation signal, avoiding a polling window and keeping an empty task
+ * correct too.
+ */
+export function awaitProjectEnvReplicaReady(
+  timeoutMs = PROJECT_ENV_REPLICA_READY_TIMEOUT_MS,
+): Promise<void> {
+  const ready = (): boolean => {
+    const status = readProjectEnvReplicaStatus();
+    return status.activated && status.gateOpen && status.attemptId === null;
+  };
+  if (ready()) return Promise.resolve();
+
+  return new Promise<void>((resolve, reject) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | null = null;
+    let unsubscribe = (): void => {};
+    const finish = (error?: unknown): void => {
+      if (settled) return;
+      settled = true;
+      if (timer !== null) clearTimeout(timer);
+      unsubscribe();
+      if (error === undefined) resolve();
+      else reject(error);
+    };
+    const check = (): void => {
+      try {
+        if (ready()) finish();
+      } catch (error) {
+        finish(error);
+      }
+    };
+
+    unsubscribe = onProjectEnvChange(check);
+    timer = setTimeout(
+      () =>
+        finish(
+          new Error(
+            "task environment replica did not become ready before the admission deadline",
+          ),
+        ),
+      timeoutMs,
+    );
+    timer.unref?.();
+    check();
+  });
+}
+
+/**
+ * Fail-closed live read for the task loader and proxy. The caller must name
+ * the task's exact project set. Withheld/unavailable records remain visible
+ * as metadata but carry no value; any mismatch or corrupt row rejects the
+ * whole snapshot.
+ */
+export function readProjectEnvReplicaSnapshot(
+  projectIds: readonly string[],
+): ProjectEnvReplicaSnapshot | null {
+  try {
+    return getDb().transaction((tx) => {
+      const authority = authorityRow(tx);
+      if (!authority.activated || !authority.gateOpen || authority.attemptId !== null) {
+        return null;
+      }
+      const requested = [...projectIds];
+      const expected = [...new Set(requested)].sort();
+      if (
+        expected.length !== requested.length ||
+        !sameStrings(expected, sortedProjectIds(tx))
+      ) {
+        return null;
+      }
+      const projects: ProjectEnvReplicaSnapshotProject[] = [];
+      // Preserve task order: the loader resolves duplicate key names with the
+      // lead project first. Only set comparison is canonicalised above.
+      for (const projectId of requested) {
+        const project = tx
+          .select()
+          .from(schema.hostProjectEnvReplicaProjects)
+          .where(eq(schema.hostProjectEnvReplicaProjects.projectId, projectId))
+          .get();
+        if (!project) throw new ProjectEnvReplicaCorruptError("replica project is missing");
+        const rows = tx
+          .select()
+          .from(schema.hostProjectEnvReplicaRecords)
+          .where(eq(schema.hostProjectEnvReplicaRecords.projectId, projectId))
+          .orderBy(asc(schema.hostProjectEnvReplicaRecords.key))
+          .all();
+        const values = new Map(
+          tx
+            .select()
+            .from(schema.hostProjectEnvReplicaValues)
+            .where(eq(schema.hostProjectEnvReplicaValues.projectId, projectId))
+            .all()
+            .map((row) => [row.key, row]),
+        );
+        const entries: ProjectEnvReplicaSnapshotEntry[] = [];
+        for (const row of rows) {
+          const state = rowState(row);
+          const materialization = rowMaterialization(row);
+          const valueRow = values.get(row.key);
+          let value: string | null = null;
+          if (materialization.kind === "installed") {
+            if (
+              state.head.tombstone ||
+              valueRow === undefined ||
+              valueRow.revision !== state.head.revision ||
+              valueRow.generation !== state.head.generation ||
+              valueRow.valueRefJson !== JSON.stringify(state.head.valueRef)
+            ) {
+              throw new ProjectEnvReplicaCorruptError(
+                "installed replica value does not match its head",
+              );
+            }
+            value = openProjectEnvValueFromStorage(valueRow.valueEnc);
+            values.delete(row.key);
+          } else if (valueRow !== undefined) {
+            throw new ProjectEnvReplicaCorruptError(
+              "withheld replica record still has a value",
+            );
+          }
+          entries.push({ state, materialization, value });
+        }
+        if (values.size > 0) {
+          throw new ProjectEnvReplicaCorruptError(
+            "replica value has no authority record",
+          );
+        }
+        projects.push({
+          projectId,
+          recordVersion: project.recordVersion,
+          entries,
+        });
+      }
+      return { projects };
+    });
+  } catch {
+    return null;
+  }
+}
+
+/** Diagnostics for tests and recovery; contains no values. */
+export function listProjectEnvReplicaReceipts(): Array<{
+  streamId: string;
+  sequence: number;
+  requestMac: string;
+  ok: boolean;
+  code: string | null;
+  result: ProjectEnvReplicaResult | null;
+  recordVersion: number | null;
+}> {
+  return getDb()
+    .select()
+    .from(schema.hostProjectEnvReplicaReceipts)
+    .orderBy(
+      asc(schema.hostProjectEnvReplicaReceipts.streamId),
+      asc(schema.hostProjectEnvReplicaReceipts.sequence),
+    )
+    .all()
+    .map((row) => {
+      const result = parseJson(row.resultJson, "replica delivery result");
+      if (result !== null && !isProjectEnvReplicaResult(result)) {
+        throw new ProjectEnvReplicaCorruptError(
+          "stored replica receipt result is invalid",
+        );
+      }
+      return {
+        streamId: row.streamId,
+        sequence: row.sequence,
+        requestMac: row.requestMac,
+        ok: row.ok,
+        code: row.code,
+        result,
+        recordVersion: row.recordVersion,
+      };
+    });
+}
+
+/** Production adapter for callers that inject only the configured store. */
+export function projectEnvReplicaValueReader(
+  store: CredentialStore | null = configuredCredentialStore(),
+): ProjectEnvReplicaValueReader | null {
+  if (store === null) return null;
+  return {
+    readStaged: (name) => store.get(name),
+    readLegacy: async (name, version) => {
+      if (store.getVersion === undefined) return null;
+      const found = await store.getVersion(name, version);
+      return found === null
+        ? null
+        : { value: found.value, version: found.version };
+    },
+  };
+}