@runuai/host 0.9.148 → 0.9.150

package/lib/project-env-authority.ts

@@ -0,0 +1,1319 @@
+/**
+ * Durable owned-runner project-env authority (ADR-153).
+ *
+ * This module deliberately has no websocket knowledge. It owns the one SQLite
+ * transaction that couples a value/head CAS, project record version, ordered
+ * cursor and replay receipt. Receipts contain a keyed MAC of a request and a
+ * value-free outcome; a plaintext set value is never durable outside its
+ * encrypted host_project_env row.
+ */
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { and, asc, eq, sql } from "drizzle-orm";
+
+import {
+  INITIAL_PROJECT_ENV_POLICY_EPOCH,
+  isHostOpId,
+  isProjectEnvBindingState,
+  isProjectEnvBindingSetFrame,
+  isProjectEnvDeleteFrame,
+  isProjectEnvDeliverySkipFrame,
+  isProjectEnvPolicyEpochs,
+  isProjectEnvReconciledFrame,
+  isProjectEnvReconciliationAttempt,
+  isProjectEnvRemoveFrame,
+  isProjectEnvSetFrame,
+  sameProjectEnvHead,
+  type ProjectEnvBinding,
+  type ProjectEnvBindingSetFrame,
+  type ProjectEnvBindingState,
+  type ProjectEnvDeleteFrame,
+  type ProjectEnvDeliveryCursor,
+  type ProjectEnvDeliverySkipFrame,
+  type ProjectEnvHead,
+  type ProjectEnvReconcileBeginFrame,
+  type ProjectEnvReconciledFrame,
+  type ProjectEnvRemoveFrame,
+  type ProjectEnvSetFrame,
+  type ProjectEnvWithholdReason,
+} from "../src/protocol";
+import { getDb, schema, type Db } from "./db";
+import { PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY } from "./project-env-feature";
+import {
+  mirrorProjectEnvDeletionToStore,
+  mirrorProjectEnvToStore,
+  noteProjectEnvAuthorityChange,
+  noteProjectEnvValueMutation,
+  openProjectEnvValueFromStorage,
+  sealProjectEnvValueForStorage,
+} from "./host-env";
+import { masterKey } from "./secrets";
+
+/** Managed runtimes must claim this floor before the first begin transaction. */
+export const PROJECT_ENV_AUTHORITY_RUNTIME_CAPABILITY =
+  PROJECT_ENV_BINDINGS_RUNTIME_CAPABILITY;
+
+type ModernProjectEnvSetFrame = Extract<
+  ProjectEnvSetFrame,
+  { delivery: ProjectEnvDeliveryCursor }
+>;
+type ModernProjectEnvDeleteFrame = Extract<
+  ProjectEnvDeleteFrame,
+  { delivery: ProjectEnvDeliveryCursor }
+>;
+
+export type ProjectEnvOwnedDeliveryFrame =
+  | ModernProjectEnvSetFrame
+  | ModernProjectEnvDeleteFrame
+  | ProjectEnvRemoveFrame
+  | ProjectEnvBindingSetFrame
+  | ProjectEnvDeliverySkipFrame;
+
+type ProjectEnvRecordRow = typeof schema.hostProjectEnvRecords.$inferSelect;
+type ProjectEnvAuthorityRow = typeof schema.hostProjectEnvAuthority.$inferSelect;
+type ProjectEnvReceiptRow =
+  typeof schema.hostProjectEnvDeliveryReceipts.$inferSelect;
+type ProjectEnvTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
+
+export class ProjectEnvAuthorityCorruptError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectEnvAuthorityCorruptError";
+  }
+}
+
+export interface ProjectEnvAuthorityStatus {
+  activated: boolean;
+  gateOpen: boolean;
+  appliedThrough: ProjectEnvDeliveryCursor | null;
+  attemptId: string | null;
+  policyEpochs: number[];
+  legacyVersion: number;
+}
+
+export interface ProjectEnvRecordInventory {
+  projectId: string;
+  recordVersion: number;
+  states: ProjectEnvBindingState[];
+}
+
+export interface ProjectEnvAuthorityEntry {
+  key: string;
+  state: ProjectEnvBindingState | null;
+  value: string;
+}
+
+export interface ProjectEnvAuthorityProjectSnapshot {
+  projectId: string;
+  recordVersion: number;
+  entries: ProjectEnvAuthorityEntry[];
+}
+
+export interface ProjectEnvAuthoritySnapshot {
+  mode: "legacy" | "authority";
+  projects: ProjectEnvAuthorityProjectSnapshot[];
+}
+
+export type ProjectEnvDeliveryApplyResult =
+  | {
+      ok: true;
+      replayed: boolean;
+      appliedThrough: ProjectEnvDeliveryCursor;
+      state: ProjectEnvBindingState | null;
+      recordVersion: number | null;
+    }
+  | {
+      ok: false;
+      replayed: boolean;
+      consumed: boolean;
+      code: ProjectEnvWithholdReason;
+      appliedThrough: ProjectEnvDeliveryCursor;
+    };
+
+export type ProjectEnvReconciliationBeginResult = {
+  appliedThrough: ProjectEnvDeliveryCursor;
+  activatedNow: boolean;
+  foldedLegacyKeys: Array<{ projectId: string; key: string }>;
+};
+
+export type ProjectEnvReconciliationCompleteResult =
+  | { ok: true; appliedThrough: ProjectEnvDeliveryCursor }
+  | {
+      ok: false;
+      code: ProjectEnvWithholdReason;
+      appliedThrough: ProjectEnvDeliveryCursor;
+    };
+
+const RECEIPT_HMAC_DOMAIN = Buffer.from(
+  "uai.project_env.delivery_receipt.v1\0",
+  "utf8",
+);
+
+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 canonicalDeliveryRequest(frame: ProjectEnvOwnedDeliveryFrame): unknown {
+  switch (frame.kind) {
+    case "env.var.set":
+      return {
+        kind: frame.kind,
+        projectId: frame.projectId,
+        key: frame.key,
+        value: frame.value,
+        orgId: frame.orgId ?? null,
+        expectedHead: frame.expectedHead,
+        ...(Object.hasOwn(frame, "initialBinding")
+          ? { initialBinding: frame.initialBinding }
+          : {}),
+        policyEpoch: frame.policyEpoch,
+        listingGeneration: frame.listingGeneration,
+        delivery: frame.delivery,
+      };
+    case "env.var.delete":
+      return {
+        kind: frame.kind,
+        projectId: frame.projectId,
+        key: frame.key,
+        expectedHead: frame.expectedHead,
+        policyEpoch: frame.policyEpoch,
+        listingGeneration: frame.listingGeneration,
+        delivery: frame.delivery,
+      };
+    case "env.var.remove":
+      return {
+        kind: frame.kind,
+        projectId: frame.projectId,
+        key: frame.key,
+        listingGeneration: frame.listingGeneration,
+        delivery: frame.delivery,
+      };
+    case "env.binding.set":
+      return {
+        kind: frame.kind,
+        projectId: frame.projectId,
+        key: frame.key,
+        binding: frame.binding,
+        expectedHead: frame.expectedHead,
+        policyEpoch: frame.policyEpoch,
+        listingGeneration: frame.listingGeneration,
+        orgId: frame.orgId ?? null,
+        delivery: frame.delivery,
+      };
+    case "env.delivery.skip":
+      return { kind: frame.kind, delivery: frame.delivery };
+  }
+}
+
+function requestMac(frame: ProjectEnvOwnedDeliveryFrame): string {
+  return createHmac("sha256", masterKey())
+    .update(RECEIPT_HMAC_DOMAIN)
+    .update(exactJson(canonicalDeliveryRequest(frame)))
+    .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 parseBinding(bindingJson: string | null): ProjectEnvBinding | null {
+  if (bindingJson === null) return null;
+  try {
+    return JSON.parse(bindingJson) as unknown as ProjectEnvBinding;
+  } catch {
+    throw new ProjectEnvAuthorityCorruptError(
+      "stored project environment binding is malformed",
+    );
+  }
+}
+
+function rowState(row: ProjectEnvRecordRow): ProjectEnvBindingState {
+  const state: ProjectEnvBindingState = {
+    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: { kind: "row" },
+        },
+    binding: parseBinding(row.bindingJson),
+    policyEpoch: row.policyEpoch,
+    listingGeneration: row.listingGeneration,
+  };
+  if (!isProjectEnvBindingState(state)) {
+    throw new ProjectEnvAuthorityCorruptError(
+      `stored project environment record is invalid (${row.projectId}/${row.key})`,
+    );
+  }
+  return state;
+}
+
+function storedRecord(
+  tx: ProjectEnvTransaction,
+  projectId: string,
+  key: string,
+): ProjectEnvRecordRow | null {
+  return (
+    tx
+      .select()
+      .from(schema.hostProjectEnvRecords)
+      .where(
+        and(
+          eq(schema.hostProjectEnvRecords.projectId, projectId),
+          eq(schema.hostProjectEnvRecords.key, key),
+        ),
+      )
+      .get() ?? null
+  );
+}
+
+function authorityRow(tx: ProjectEnvTransaction | Db): ProjectEnvAuthorityRow {
+  const row = tx
+    .select()
+    .from(schema.hostProjectEnvAuthority)
+    .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+    .get();
+  if (!row) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "project environment authority row is missing",
+    );
+  }
+  return row;
+}
+
+function parsePolicyEpochs(row: ProjectEnvAuthorityRow): number[] {
+  let value: unknown;
+  try {
+    value = JSON.parse(row.policyEpochsJson);
+  } catch {
+    throw new ProjectEnvAuthorityCorruptError(
+      "stored project environment policy epochs are malformed",
+    );
+  }
+  if (!isProjectEnvPolicyEpochs(value)) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "stored project environment policy epochs are invalid",
+    );
+  }
+  return value;
+}
+
+function cursorFor(row: ProjectEnvAuthorityRow): ProjectEnvDeliveryCursor | null {
+  if (!row.activated) return null;
+  const cursor = { streamId: row.streamId, sequence: row.appliedSequence };
+  if (
+    !isHostOpId(row.streamId) ||
+    !Number.isSafeInteger(row.appliedSequence) ||
+    row.appliedSequence < 0
+  ) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "stored project environment delivery cursor is invalid",
+    );
+  }
+  return cursor as ProjectEnvDeliveryCursor;
+}
+
+function validateAuthorityRow(row: ProjectEnvAuthorityRow): void {
+  parsePolicyEpochs(row);
+  cursorFor(row);
+  if (
+    !Number.isSafeInteger(row.legacyVersion) ||
+    row.legacyVersion < 0 ||
+    row.modernWrite ||
+    (row.attemptId !== null && !isHostOpId(row.attemptId)) ||
+    (row.attemptId === null) !== (row.attemptLegacyVersion === null) ||
+    (row.gateOpen && row.attemptId !== null)
+  ) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "stored project environment authority state is invalid",
+    );
+  }
+}
+
+export function readProjectEnvAuthorityStatus(): ProjectEnvAuthorityStatus {
+  const row = authorityRow(getDb());
+  validateAuthorityRow(row);
+  return {
+    activated: row.activated,
+    gateOpen: row.gateOpen,
+    appliedThrough: cursorFor(row),
+    attemptId: row.attemptId,
+    policyEpochs: parsePolicyEpochs(row),
+    legacyVersion: row.legacyVersion,
+  };
+}
+
+/** A corrupted or closed activated authority never permits a value read. */
+export function projectEnvAuthorityGateAllowsReads(): boolean {
+  try {
+    const status = readProjectEnvAuthorityStatus();
+    return !status.activated || status.gateOpen;
+  } catch {
+    return false;
+  }
+}
+
+function projectRecordVersion(
+  tx: ProjectEnvTransaction | Db,
+  projectId: string,
+): number {
+  const row = tx
+    .select({ recordVersion: schema.hostProjectEnvProjects.recordVersion })
+    .from(schema.hostProjectEnvProjects)
+    .where(eq(schema.hostProjectEnvProjects.projectId, projectId))
+    .get();
+  const version = row?.recordVersion ?? 0;
+  if (!Number.isSafeInteger(version) || version < 0) {
+    throw new ProjectEnvAuthorityCorruptError(
+      `stored project environment record version is invalid (${projectId})`,
+    );
+  }
+  return version;
+}
+
+function bumpProjectRecordVersion(
+  tx: ProjectEnvTransaction,
+  projectId: string,
+): number {
+  tx.insert(schema.hostProjectEnvProjects)
+    .values({ projectId, recordVersion: 1 })
+    .onConflictDoUpdate({
+      target: schema.hostProjectEnvProjects.projectId,
+      set: {
+        recordVersion: sql`${schema.hostProjectEnvProjects.recordVersion} + 1`,
+      },
+    })
+    .run();
+  return projectRecordVersion(tx, projectId);
+}
+
+function putState(
+  tx: ProjectEnvTransaction,
+  projectId: string,
+  state: ProjectEnvBindingState,
+): void {
+  if (!isProjectEnvBindingState(state)) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "refusing to persist an invalid project environment record",
+    );
+  }
+  tx.insert(schema.hostProjectEnvRecords)
+    .values({
+      projectId,
+      key: state.key,
+      revision: state.head.revision,
+      generation: state.head.generation,
+      tombstone: state.head.tombstone,
+      bindingJson: state.binding === null ? null : JSON.stringify(state.binding),
+      policyEpoch: state.policyEpoch,
+      listingGeneration: state.listingGeneration,
+      updatedAt: Date.now(),
+    })
+    .onConflictDoUpdate({
+      target: [
+        schema.hostProjectEnvRecords.projectId,
+        schema.hostProjectEnvRecords.key,
+      ],
+      set: {
+        revision: state.head.revision,
+        generation: state.head.generation,
+        tombstone: state.head.tombstone,
+        bindingJson:
+          state.binding === null ? null : JSON.stringify(state.binding),
+        policyEpoch: state.policyEpoch,
+        listingGeneration: state.listingGeneration,
+        updatedAt: Date.now(),
+      },
+    })
+    .run();
+}
+
+function inventoryWith(
+  tx: ProjectEnvTransaction | Db,
+  projectId: string,
+): ProjectEnvRecordInventory {
+  const rows = tx
+    .select()
+    .from(schema.hostProjectEnvRecords)
+    .where(eq(schema.hostProjectEnvRecords.projectId, projectId))
+    .orderBy(asc(schema.hostProjectEnvRecords.key))
+    .all();
+  const version = projectRecordVersion(tx, projectId);
+  if (rows.length > 0 && version === 0) {
+    throw new ProjectEnvAuthorityCorruptError(
+      `project environment records have no version (${projectId})`,
+    );
+  }
+  return {
+    projectId,
+    recordVersion: version,
+    states: rows.map(rowState),
+  };
+}
+
+export function readProjectEnvRecordInventory(
+  projectId: string,
+): ProjectEnvRecordInventory {
+  return getDb().transaction((tx) => inventoryWith(tx, projectId));
+}
+
+/**
+ * One consistent, fail-closed value/head snapshot for the loader/proxy. Before
+ * activation it preserves the legacy value-only behavior. Once activated it
+ * returns null unless the gate is open and every live record has exactly one
+ * decryptable value row (and no unrecorded row exists).
+ */
+export function readProjectEnvAuthoritySnapshot(
+  projectIds: readonly string[],
+): ProjectEnvAuthoritySnapshot | null {
+  try {
+    return getDb().transaction((tx) => {
+      const authority = authorityRow(tx);
+      validateAuthorityRow(authority);
+      if (authority.activated && !authority.gateOpen) return null;
+
+      const projects: ProjectEnvAuthorityProjectSnapshot[] = [];
+      for (const projectId of projectIds) {
+        const valueRows = tx
+          .select()
+          .from(schema.hostProjectEnv)
+          .where(eq(schema.hostProjectEnv.projectId, projectId))
+          .orderBy(asc(schema.hostProjectEnv.key))
+          .all();
+        if (!authority.activated) {
+          projects.push({
+            projectId,
+            recordVersion: 0,
+            entries: valueRows.map((row) => ({
+              key: row.key,
+              state: null,
+              value: openProjectEnvValueFromStorage(row.valueEnc),
+            })),
+          });
+          continue;
+        }
+
+        const inventory = inventoryWith(tx, projectId);
+        const values = new Map(valueRows.map((row) => [row.key, row.valueEnc]));
+        const entries: ProjectEnvAuthorityEntry[] = [];
+        for (const state of inventory.states) {
+          if (state.head.tombstone) {
+            if (values.has(state.key)) {
+              throw new ProjectEnvAuthorityCorruptError(
+                `tombstoned project environment record has a value (${projectId}/${state.key})`,
+              );
+            }
+            continue;
+          }
+          const valueEnc = values.get(state.key);
+          if (valueEnc === undefined) {
+            throw new ProjectEnvAuthorityCorruptError(
+              `live project environment record has no value (${projectId}/${state.key})`,
+            );
+          }
+          entries.push({
+            key: state.key,
+            state,
+            value: openProjectEnvValueFromStorage(valueEnc),
+          });
+          values.delete(state.key);
+        }
+        if (values.size > 0) {
+          throw new ProjectEnvAuthorityCorruptError(
+            `project environment value has no authority record (${projectId})`,
+          );
+        }
+        projects.push({
+          projectId,
+          recordVersion: inventory.recordVersion,
+          entries,
+        });
+      }
+      return { mode: authority.activated ? "authority" : "legacy", projects };
+    });
+  } catch {
+    return null;
+  }
+}
+
+function setModernWrite(tx: ProjectEnvTransaction, value: boolean): void {
+  const changed = tx
+    .update(schema.hostProjectEnvAuthority)
+    .set({ modernWrite: value, updatedAt: Date.now() })
+    .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+    .run().changes;
+  if (changed !== 1) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "project environment authority row could not be fenced",
+    );
+  }
+}
+
+function backfillLegacyValues(tx: ProjectEnvTransaction): void {
+  const record = tx
+    .select({ key: schema.hostProjectEnvRecords.key })
+    .from(schema.hostProjectEnvRecords)
+    .limit(1)
+    .get();
+  const project = tx
+    .select({ projectId: schema.hostProjectEnvProjects.projectId })
+    .from(schema.hostProjectEnvProjects)
+    .limit(1)
+    .get();
+  if (record || project) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "unactivated project environment authority already has records",
+    );
+  }
+  const rows = tx
+    .select({
+      projectId: schema.hostProjectEnv.projectId,
+      key: schema.hostProjectEnv.key,
+    })
+    .from(schema.hostProjectEnv)
+    .orderBy(
+      asc(schema.hostProjectEnv.projectId),
+      asc(schema.hostProjectEnv.key),
+    )
+    .all();
+  const projects = new Set<string>();
+  for (const row of rows) {
+    putState(tx, row.projectId, {
+      key: row.key,
+      head: {
+        revision: 1,
+        generation: 1,
+        tombstone: false,
+        valueRef: { kind: "row" },
+      },
+      binding: null,
+      policyEpoch: INITIAL_PROJECT_ENV_POLICY_EPOCH,
+      listingGeneration: 0,
+    });
+    projects.add(row.projectId);
+  }
+  for (const projectId of projects) {
+    tx.insert(schema.hostProjectEnvProjects)
+      .values({ projectId, recordVersion: 1 })
+      .run();
+  }
+}
+
+function foldLegacyJournal(
+  tx: ProjectEnvTransaction,
+): Array<{ projectId: string; key: string }> {
+  const rows = tx
+    .select({
+      projectId: schema.hostProjectEnvLegacyJournal.projectId,
+      key: schema.hostProjectEnvLegacyJournal.key,
+    })
+    .from(schema.hostProjectEnvLegacyJournal)
+    .groupBy(
+      schema.hostProjectEnvLegacyJournal.projectId,
+      schema.hostProjectEnvLegacyJournal.key,
+    )
+    .orderBy(
+      asc(schema.hostProjectEnvLegacyJournal.projectId),
+      asc(schema.hostProjectEnvLegacyJournal.key),
+    )
+    .all();
+  for (const dirty of rows) {
+    const old = storedRecord(tx, dirty.projectId, dirty.key);
+    let state: ProjectEnvBindingState;
+    if (!old) {
+      // A post-activation legacy insert/delete has no authorized value. The
+      // migration tombstone shape makes every delayed legacy save stale.
+      state = {
+        key: dirty.key,
+        head: {
+          revision: 2,
+          generation: 2,
+          tombstone: true,
+          valueRef: null,
+        },
+        binding: null,
+        policyEpoch: INITIAL_PROJECT_ENV_POLICY_EPOCH,
+        listingGeneration: 0,
+      };
+      putState(tx, dirty.projectId, state);
+      bumpProjectRecordVersion(tx, dirty.projectId);
+    } else {
+      const current = rowState(old);
+      if (!current.head.tombstone) {
+        state = {
+          ...current,
+          head: {
+            revision: current.head.revision + 1,
+            generation: current.head.generation + 1,
+            tombstone: true,
+            valueRef: null,
+          },
+        };
+        putState(tx, dirty.projectId, state);
+        bumpProjectRecordVersion(tx, dirty.projectId);
+      }
+    }
+    tx.delete(schema.hostProjectEnv)
+      .where(
+        and(
+          eq(schema.hostProjectEnv.projectId, dirty.projectId),
+          eq(schema.hostProjectEnv.key, dirty.key),
+        ),
+      )
+      .run();
+  }
+  tx.delete(schema.hostProjectEnvLegacyJournal).run();
+  return rows;
+}
+
+/**
+ * Activate (if needed), fold every legacy write, close the gate, and persist a
+ * fresh attempt. The caller must claim capability floor 4 before calling this
+ * on an unactivated managed runtime.
+ */
+export function beginProjectEnvReconciliation(
+  frame: ProjectEnvReconcileBeginFrame,
+  policyEpochs: readonly number[],
+): ProjectEnvReconciliationBeginResult {
+  if (
+    frame.kind !== "env.reconcile.begin" ||
+    !isHostOpId(frame.opId) ||
+    !isProjectEnvReconciliationAttempt(frame.attempt) ||
+    !isProjectEnvPolicyEpochs(policyEpochs)
+  ) {
+    throw new Error("invalid project environment reconciliation begin");
+  }
+  const result = getDb().transaction((tx) => {
+    const before = authorityRow(tx);
+    validateAuthorityRow(before);
+    setModernWrite(tx, true);
+    if (!before.activated) backfillLegacyValues(tx);
+    const foldedLegacyKeys = before.activated ? foldLegacyJournal(tx) : [];
+    const streamChanged = before.streamId !== frame.attempt.streamId;
+    tx.update(schema.hostProjectEnvAuthority)
+      .set({
+        activated: true,
+        gateOpen: false,
+        streamId: frame.attempt.streamId,
+        appliedSequence: streamChanged ? 0 : before.appliedSequence,
+        attemptId: frame.attempt.attemptId,
+        attemptLegacyVersion: before.legacyVersion,
+        policyEpochsJson: JSON.stringify(policyEpochs),
+        modernWrite: false,
+        updatedAt: Date.now(),
+      })
+      .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+      .run();
+    return {
+      appliedThrough: {
+        streamId: frame.attempt.streamId,
+        sequence: streamChanged ? 0 : before.appliedSequence,
+      },
+      activatedNow: !before.activated,
+      foldedLegacyKeys,
+    };
+  });
+  for (const dirty of result.foldedLegacyKeys) {
+    noteProjectEnvValueMutation(dirty.projectId);
+    mirrorProjectEnvDeletionToStore(dirty.projectId, dirty.key);
+  }
+  noteProjectEnvAuthorityChange();
+  return result;
+}
+
+function headEqual(
+  current: ProjectEnvBindingState | null,
+  expected: ProjectEnvHead | null,
+): boolean {
+  if (current === null || expected === null) return current === null && expected === null;
+  return sameProjectEnvHead(current.head, expected);
+}
+
+function stateFor(
+  tx: ProjectEnvTransaction,
+  projectId: string,
+  key: string,
+): ProjectEnvBindingState | null {
+  const row = storedRecord(tx, projectId, key);
+  return row ? rowState(row) : null;
+}
+
+function receiptResult(
+  receipt: ProjectEnvReceiptRow,
+  cursor: ProjectEnvDeliveryCursor,
+): ProjectEnvDeliveryApplyResult {
+  if (receipt.ok) {
+    let state: ProjectEnvBindingState | null = null;
+    if (receipt.stateJson !== null) {
+      try {
+        const parsed: unknown = JSON.parse(receipt.stateJson);
+        if (!isProjectEnvBindingState(parsed)) throw new Error("invalid");
+        state = parsed;
+      } catch {
+        throw new ProjectEnvAuthorityCorruptError(
+          "stored project environment delivery outcome is invalid",
+        );
+      }
+    }
+    return {
+      ok: true,
+      replayed: true,
+      appliedThrough: cursor,
+      state,
+      recordVersion: receipt.recordVersion,
+    };
+  }
+  if (receipt.code === null) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "stored project environment refusal has no code",
+    );
+  }
+  return {
+    ok: false,
+    replayed: true,
+    consumed: true,
+    code: receipt.code,
+    appliedThrough: cursor,
+  };
+}
+
+function transientResult(
+  row: ProjectEnvAuthorityRow,
+  code: ProjectEnvWithholdReason,
+): ProjectEnvDeliveryApplyResult {
+  const cursor = cursorFor(row);
+  if (!cursor) {
+    throw new ProjectEnvAuthorityCorruptError(
+      "project environment delivery arrived before activation",
+    );
+  }
+  return {
+    ok: false,
+    replayed: false,
+    consumed: false,
+    code,
+    appliedThrough: cursor,
+  };
+}
+
+function saveReceipt(
+  tx: ProjectEnvTransaction,
+  frame: ProjectEnvOwnedDeliveryFrame,
+  outcome:
+    | {
+        ok: true;
+        state: ProjectEnvBindingState | null;
+        recordVersion: number | null;
+      }
+    | { ok: false; code: ProjectEnvWithholdReason },
+): void {
+  tx.insert(schema.hostProjectEnvDeliveryReceipts)
+    .values({
+      streamId: frame.delivery.streamId,
+      sequence: frame.delivery.sequence,
+      requestKind: frame.kind,
+      requestMac: requestMac(frame),
+      ok: outcome.ok,
+      stateJson:
+        outcome.ok && outcome.state !== null
+          ? JSON.stringify(outcome.state)
+          : null,
+      recordVersion: outcome.ok ? outcome.recordVersion : null,
+      code: outcome.ok ? null : outcome.code,
+      createdAt: Date.now(),
+    })
+    .run();
+  tx.update(schema.hostProjectEnvAuthority)
+    .set({ appliedSequence: frame.delivery.sequence, updatedAt: Date.now() })
+    .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+    .run();
+}
+
+function terminalRefusal(
+  tx: ProjectEnvTransaction,
+  frame: ProjectEnvOwnedDeliveryFrame,
+  code: ProjectEnvWithholdReason,
+): ProjectEnvDeliveryApplyResult {
+  saveReceipt(tx, frame, { ok: false, code });
+  return {
+    ok: false,
+    replayed: false,
+    consumed: true,
+    code,
+    appliedThrough: frame.delivery,
+  };
+}
+
+function applySet(
+  tx: ProjectEnvTransaction,
+  frame: ModernProjectEnvSetFrame,
+  policyEpochs: readonly number[],
+): { state: ProjectEnvBindingState; recordVersion: number } | string {
+  const current = stateFor(tx, frame.projectId, frame.key);
+  if (!headEqual(current, frame.expectedHead)) return "head_mismatch";
+  if (!policyEpochs.includes(frame.policyEpoch)) return "policy_epoch_unknown";
+  if (current && frame.listingGeneration < current.listingGeneration) {
+    return "listing_generation_stale";
+  }
+
+  let state: ProjectEnvBindingState;
+  if (current === null) {
+    state = {
+      key: frame.key,
+      head: {
+        revision: 1,
+        generation: 1,
+        tombstone: false,
+        valueRef: { kind: "row" },
+      },
+      binding: frame.initialBinding ?? null,
+      policyEpoch: frame.policyEpoch,
+      listingGeneration: frame.listingGeneration,
+    };
+  } else if (current.head.generation === 0) {
+    state = {
+      key: frame.key,
+      head: {
+        revision: 2,
+        generation: 1,
+        tombstone: false,
+        valueRef: { kind: "row" },
+      },
+      binding: frame.initialBinding ?? null,
+      policyEpoch: frame.policyEpoch,
+      listingGeneration: frame.listingGeneration,
+    };
+  } else {
+    if (frame.policyEpoch !== current.policyEpoch) return "policy_epoch_mismatch";
+    state = {
+      ...current,
+      head: current.head.tombstone
+        ? {
+            revision: current.head.revision + 1,
+            generation: current.head.generation + 1,
+            tombstone: false,
+            valueRef: { kind: "row" },
+          }
+        : {
+            revision: current.head.revision,
+            generation: current.head.generation + 1,
+            tombstone: false,
+            valueRef: { kind: "row" },
+          },
+      listingGeneration: frame.listingGeneration,
+    };
+  }
+  putState(tx, frame.projectId, state);
+  tx.insert(schema.hostProjectEnv)
+    .values({
+      projectId: frame.projectId,
+      key: frame.key,
+      valueEnc: sealProjectEnvValueForStorage(frame.value),
+      updatedAt: Date.now(),
+      ...(frame.orgId ? { orgId: frame.orgId } : {}),
+    })
+    .onConflictDoUpdate({
+      target: [schema.hostProjectEnv.projectId, schema.hostProjectEnv.key],
+      set: {
+        valueEnc: sealProjectEnvValueForStorage(frame.value),
+        updatedAt: Date.now(),
+        ...(frame.orgId ? { orgId: frame.orgId } : {}),
+      },
+    })
+    .run();
+  return { state, recordVersion: bumpProjectRecordVersion(tx, frame.projectId) };
+}
+
+function applyDelete(
+  tx: ProjectEnvTransaction,
+  frame: ModernProjectEnvDeleteFrame,
+  policyEpochs: readonly number[],
+): { state: ProjectEnvBindingState; recordVersion: number } | string {
+  const current = stateFor(tx, frame.projectId, frame.key);
+  if (!headEqual(current, frame.expectedHead) || current?.head.tombstone !== false) {
+    return "head_mismatch";
+  }
+  if (
+    !policyEpochs.includes(frame.policyEpoch) ||
+    frame.policyEpoch !== current.policyEpoch
+  ) {
+    return "policy_epoch_unknown";
+  }
+  if (frame.listingGeneration < current.listingGeneration) {
+    return "listing_generation_stale";
+  }
+  const state: ProjectEnvBindingState = {
+    ...current,
+    head: {
+      revision: current.head.revision + 1,
+      generation: current.head.generation + 1,
+      tombstone: true,
+      valueRef: null,
+    },
+    listingGeneration: frame.listingGeneration,
+  };
+  putState(tx, frame.projectId, state);
+  tx.delete(schema.hostProjectEnv)
+    .where(
+      and(
+        eq(schema.hostProjectEnv.projectId, frame.projectId),
+        eq(schema.hostProjectEnv.key, frame.key),
+      ),
+    )
+    .run();
+  return { state, recordVersion: bumpProjectRecordVersion(tx, frame.projectId) };
+}
+
+function applyRemove(
+  tx: ProjectEnvTransaction,
+  frame: ProjectEnvRemoveFrame,
+): { state: ProjectEnvBindingState; recordVersion: number } | string {
+  const current = stateFor(tx, frame.projectId, frame.key);
+  if (current && frame.listingGeneration < current.listingGeneration) {
+    return "listing_generation_stale";
+  }
+  let state: ProjectEnvBindingState;
+  if (current === null) {
+    state = {
+      key: frame.key,
+      head: {
+        revision: 1,
+        generation: 0,
+        tombstone: true,
+        valueRef: null,
+      },
+      binding: null,
+      policyEpoch: null,
+      listingGeneration: frame.listingGeneration,
+    };
+  } else if (!current.head.tombstone) {
+    state = {
+      ...current,
+      head: {
+        revision: current.head.revision + 1,
+        generation: current.head.generation + 1,
+        tombstone: true,
+        valueRef: null,
+      },
+      listingGeneration: frame.listingGeneration,
+    };
+  } else {
+    state = { ...current, listingGeneration: frame.listingGeneration };
+  }
+  const changed = exactJson(state) !== exactJson(current);
+  if (changed) putState(tx, frame.projectId, state);
+  tx.delete(schema.hostProjectEnv)
+    .where(
+      and(
+        eq(schema.hostProjectEnv.projectId, frame.projectId),
+        eq(schema.hostProjectEnv.key, frame.key),
+      ),
+    )
+    .run();
+  return {
+    state,
+    recordVersion: changed
+      ? bumpProjectRecordVersion(tx, frame.projectId)
+      : projectRecordVersion(tx, frame.projectId),
+  };
+}
+
+function applyBinding(
+  tx: ProjectEnvTransaction,
+  frame: ProjectEnvBindingSetFrame,
+  policyEpochs: readonly number[],
+): { state: ProjectEnvBindingState; recordVersion: number } | string {
+  const current = stateFor(tx, frame.projectId, frame.key);
+  if (!headEqual(current, frame.expectedHead) || current?.head.tombstone !== false) {
+    return "head_mismatch";
+  }
+  if (!policyEpochs.includes(frame.policyEpoch)) return "policy_epoch_unknown";
+  if (frame.listingGeneration < current.listingGeneration) {
+    return "listing_generation_stale";
+  }
+  const state: ProjectEnvBindingState = {
+    ...current,
+    head: { ...current.head, revision: current.head.revision + 1 },
+    binding: frame.binding,
+    policyEpoch: frame.policyEpoch,
+    listingGeneration: frame.listingGeneration,
+  };
+  putState(tx, frame.projectId, state);
+  return { state, recordVersion: bumpProjectRecordVersion(tx, frame.projectId) };
+}
+
+function validOwnedDeliveryFrame(
+  value: unknown,
+): value is ProjectEnvOwnedDeliveryFrame {
+  if (isProjectEnvSetFrame(value)) {
+    return "delivery" in value && value.delivery !== undefined;
+  }
+  if (isProjectEnvDeleteFrame(value)) {
+    return "delivery" in value && value.delivery !== undefined;
+  }
+  return (
+    isProjectEnvRemoveFrame(value) ||
+    isProjectEnvBindingSetFrame(value) ||
+    isProjectEnvDeliverySkipFrame(value)
+  );
+}
+
+/**
+ * Apply exactly the next delivery, or replay its value-free receipt. Terminal
+ * CAS/policy refusals consume their sequence. Gaps, stale attempts and stream
+ * mismatches do not. Different content at an already-consumed sequence is
+ * refused; the special late skip keeps the original operation's outcome.
+ */
+export function applyProjectEnvDelivery(
+  frame: ProjectEnvOwnedDeliveryFrame,
+): ProjectEnvDeliveryApplyResult {
+  if (!validOwnedDeliveryFrame(frame)) {
+    throw new Error("invalid modern project environment delivery");
+  }
+  const result = getDb().transaction((tx) => {
+    const authority = authorityRow(tx);
+    validateAuthorityRow(authority);
+    if (!authority.activated) return transientResult(authority, "not_activated");
+    const current = cursorFor(authority)!;
+    if (frame.delivery.streamId !== current.streamId) {
+      return transientResult(authority, "stream_mismatch");
+    }
+    if (frame.delivery.sequence <= current.sequence) {
+      const receipt = tx
+        .select()
+        .from(schema.hostProjectEnvDeliveryReceipts)
+        .where(
+          and(
+            eq(
+              schema.hostProjectEnvDeliveryReceipts.streamId,
+              frame.delivery.streamId,
+            ),
+            eq(
+              schema.hostProjectEnvDeliveryReceipts.sequence,
+              frame.delivery.sequence,
+            ),
+          ),
+        )
+        .get();
+      if (!receipt) return transientResult(authority, "receipt_missing");
+      if (frame.kind === "env.delivery.skip") {
+        return receiptResult(receipt, current);
+      }
+      if (receipt.requestKind === "env.delivery.skip") {
+        return {
+          ok: false,
+          replayed: true,
+          consumed: true,
+          code: "delivery_skipped",
+          appliedThrough: current,
+        } as const;
+      }
+      if (
+        receipt.requestKind !== frame.kind ||
+        !sameMac(receipt.requestMac, requestMac(frame))
+      ) {
+        return {
+          ok: false,
+          replayed: true,
+          consumed: true,
+          code: "delivery_conflict",
+          appliedThrough: current,
+        } as const;
+      }
+      return receiptResult(receipt, current);
+    }
+    if (frame.delivery.sequence !== current.sequence + 1) {
+      return transientResult(authority, "delivery_gap");
+    }
+    if (
+      authority.gateOpen
+        ? frame.reconciliationAttemptId !== undefined
+        : authority.attemptId === null ||
+          frame.reconciliationAttemptId !== authority.attemptId
+    ) {
+      return transientResult(authority, "reconciliation_attempt_mismatch");
+    }
+
+    setModernWrite(tx, true);
+    const policyEpochs = parsePolicyEpochs(authority);
+    let applied:
+      | { state: ProjectEnvBindingState; recordVersion: number }
+      | string
+      | null;
+    switch (frame.kind) {
+      case "env.var.set":
+        applied = applySet(tx, frame, policyEpochs);
+        break;
+      case "env.var.delete":
+        applied = applyDelete(tx, frame, policyEpochs);
+        break;
+      case "env.var.remove":
+        applied = applyRemove(tx, frame);
+        break;
+      case "env.binding.set":
+        applied = applyBinding(tx, frame, policyEpochs);
+        break;
+      case "env.delivery.skip":
+        applied = null;
+        break;
+    }
+    if (typeof applied === "string") {
+      setModernWrite(tx, false);
+      return terminalRefusal(tx, frame, applied);
+    }
+    setModernWrite(tx, false);
+    saveReceipt(tx, frame, {
+      ok: true,
+      state: applied?.state ?? null,
+      recordVersion: applied?.recordVersion ?? null,
+    });
+    return {
+      ok: true,
+      replayed: false,
+      appliedThrough: frame.delivery,
+      state: applied?.state ?? null,
+      recordVersion: applied?.recordVersion ?? null,
+    } as const;
+  });
+  if (result.ok && !result.replayed) noteProjectEnvAuthorityChange();
+  if (result.ok && !result.replayed && frame.kind === "env.var.set") {
+    noteProjectEnvValueMutation(frame.projectId);
+    mirrorProjectEnvToStore(frame.projectId, frame.key);
+  } else if (
+    result.ok &&
+    !result.replayed &&
+    (frame.kind === "env.var.delete" || frame.kind === "env.var.remove")
+  ) {
+    noteProjectEnvValueMutation(frame.projectId);
+    mirrorProjectEnvDeletionToStore(frame.projectId, frame.key);
+  }
+  return result;
+}
+
+export const applyProjectEnvSet = (frame: ModernProjectEnvSetFrame) =>
+  applyProjectEnvDelivery(frame);
+export const applyProjectEnvDelete = (frame: ModernProjectEnvDeleteFrame) =>
+  applyProjectEnvDelivery(frame);
+export const applyProjectEnvRemove = (frame: ProjectEnvRemoveFrame) =>
+  applyProjectEnvDelivery(frame);
+export const applyProjectEnvBinding = (frame: ProjectEnvBindingSetFrame) =>
+  applyProjectEnvDelivery(frame);
+export const applyProjectEnvSkip = (frame: ProjectEnvDeliverySkipFrame) =>
+  applyProjectEnvDelivery(frame);
+
+/** Open the gate only for the exact current attempt, stream, cursor and record versions. */
+export function completeProjectEnvReconciliation(
+  frame: ProjectEnvReconciledFrame,
+): ProjectEnvReconciliationCompleteResult {
+  if (!isProjectEnvReconciledFrame(frame)) {
+    throw new Error("invalid project environment reconciliation marker");
+  }
+  const result = getDb().transaction((tx): ProjectEnvReconciliationCompleteResult => {
+    const authority = authorityRow(tx);
+    validateAuthorityRow(authority);
+    const cursor = cursorFor(authority);
+    if (!cursor) {
+      throw new ProjectEnvAuthorityCorruptError(
+        "project environment reconciliation completed before activation",
+      );
+    }
+    const refuse = (code: string): ProjectEnvReconciliationCompleteResult => ({
+      ok: false,
+      code,
+      appliedThrough: cursor,
+    });
+    if (authority.attemptId !== frame.attemptId) {
+      return refuse("reconciliation_attempt_mismatch");
+    }
+    if (
+      frame.highWater.streamId !== cursor.streamId ||
+      frame.highWater.sequence > cursor.sequence
+    ) {
+      return refuse("delivery_incomplete");
+    }
+    if (authority.attemptLegacyVersion !== authority.legacyVersion) {
+      return refuse("legacy_write_detected");
+    }
+    for (const version of frame.versions) {
+      if (projectRecordVersion(tx, version.projectId) !== version.recordVersion) {
+        return refuse("record_version_changed");
+      }
+    }
+    tx.update(schema.hostProjectEnvAuthority)
+      .set({
+        gateOpen: true,
+        attemptId: null,
+        attemptLegacyVersion: null,
+        updatedAt: Date.now(),
+      })
+      .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+      .run();
+    return { ok: true, appliedThrough: cursor };
+  });
+  if (result.ok) noteProjectEnvAuthorityChange();
+  return result;
+}
+
+/** Explicit fail-closed transition for transport loss or storage diagnostics. */
+export function closeProjectEnvAuthorityGate(): void {
+  getDb()
+    .update(schema.hostProjectEnvAuthority)
+    .set({ gateOpen: false, updatedAt: Date.now() })
+    .where(eq(schema.hostProjectEnvAuthority.id, "host"))
+    .run();
+  noteProjectEnvAuthorityChange();
+}
+
+/** Value-free inspection used by tests and crash recovery diagnostics. */
+export function listProjectEnvDeliveryReceipts(): Array<{
+  streamId: string;
+  sequence: number;
+  requestKind: string;
+  requestMac: string;
+  ok: boolean;
+  state: ProjectEnvBindingState | null;
+  recordVersion: number | null;
+  code: string | null;
+}> {
+  return getDb()
+    .select()
+    .from(schema.hostProjectEnvDeliveryReceipts)
+    .orderBy(
+      asc(schema.hostProjectEnvDeliveryReceipts.streamId),
+      asc(schema.hostProjectEnvDeliveryReceipts.sequence),
+    )
+    .all()
+    .map((row) => {
+      const result = receiptResult(row, {
+        streamId: row.streamId,
+        sequence: row.sequence,
+      });
+      return {
+        streamId: row.streamId,
+        sequence: row.sequence,
+        requestKind: row.requestKind,
+        requestMac: row.requestMac,
+        ok: result.ok,
+        state: result.ok ? result.state : null,
+        recordVersion: result.ok ? result.recordVersion : null,
+        code: result.ok ? null : result.code,
+      };
+    });
+}