@substrat-run/adapter-cloudflare 0.161.0 → 0.163.0

package/dist/control-plane-do.js

@@ -4,7 +4,7 @@ import { replyOf } from './do-reply.js';
 import { switchSqlOver } from './scope-do.js';
 import { blankSqlComments, boundShapesColumn, executableSqlStatements, installsReconciledOf, PROVISIONED_VERSIONS_SQL, provisionedVersionsParams, } from '@substrat-run/kernel';
 import { COPY_BACKFILL_SCOPE_SQL, COPY_BACKFILL_SQL, COPY_BACKFILL_SUPERSEDE_SQL, COPY_CLAIM_SQL, COPY_EXPIRED_SQL, COPY_MOVE_RENEW_SQL, copyMoveRenewParams, PENDING_COPY_KEEP_ALIVE_SQL, pendingCopyKeepAliveParams, copyBackfillParams, copyBackfillRefusal, SUBJECT_ERASURE_CLAIM_SQL, subjectErasureClaimParams, COPY_MOVE_CONFIRM_SQL, COPY_MOVE_LIVE_PREDICATE, SCOPE_COPY_LEASE_MS, SERVES_NOW_CONDITION, SERVES_NOW_PREDICATE, servesNowParams, SCOPE_SCRIPT_COPY_COLUMNS, copyMoveConfirmParams, copyMoveLiveParams, } from '@substrat-run/kernel';
-import { opsFailureReferenceWhere } from '@substrat-run/kernel';
+import { autoAdmittedProdRefusal, listedPromoteRefusal, opsFailureReferenceWhere } from '@substrat-run/kernel';
 import { doBuiltColumnsOf, doRedactionSql } from './sql.js';
 import { assertReplayableDump, AUTO_ADMISSION_NOTE, instant, opsFailureFingerprint, ROUTE_SCOPE_HOSTNAMES_MAX, SCOPE_GATE_REASONS, substratError } from '@substrat-run/contracts';
 /**
@@ -818,6 +818,30 @@ export const REPLIED_METHODS = [
     'admitVersion',
     'rejectVersion',
     'setVerticalServing',
+    // #2565: refuses a listed vertical's prod with forbidden (`unlistedOnly`) or conflict (an
+    // auto-admitted version). A DO from before lists it not, so the current coordinator fails closed.
+    'promoteChannel',
+    // #2526: the role, grant and org writes at a tenant node, each with its admin row in its unit. A
+    // DO from before lists none of them, so the current coordinator fails closed against it. That is
+    // why the org write is `insertOrg` and not `createOrg` with a trailing row: an older DO lists
+    // `createOrg` and would drop the row and create the org.
+    'defineRoleOrRefusal',
+    'assignTenantRole',
+    'writeTenantTuple',
+    'writeOrgTenantTuple',
+    'writeTenantSystemGrant',
+    'grantConnectionInDirectory',
+    'insertOrg',
+    // #2526: the hostname and entitlement writes, each reading its row and judging its no-op in the
+    // unit that writes it and its admin row. A DO from before lists none of them, so the current
+    // coordinator fails closed against it; a coordinator from before calls them directly, without
+    // the trailing row, and gets the bare write it always did.
+    'bindHostnameInDirectory',
+    'setHostnameStatus',
+    'setHostnameIssuance',
+    'deleteHostname',
+    'grantEntitlement',
+    'revokeEntitlement',
 ];
 export class ControlPlaneDO extends DurableObject {
     sql;
@@ -1371,6 +1395,8 @@ export class ControlPlaneDO extends DurableObject {
         if (status === 'reaped') {
             throw substratError('validation_failed', `tenant ${tenantId} cannot be set to 'reaped' via setTenantStatus — reap goes through reapTenant (control-plane.md §4.8)`);
         }
+        if (before.status === 'reaped')
+            throw substratError('conflict', `tenant ${tenantId} is reaped and cannot change status`);
         // Stamp/clear deleting_at so the grace-window sweep can age tenants (§4.8):
         // entering `deleting` stamps, leaving it (an un-delete) clears — the same shape
         // transitionScope uses for archived_at.
@@ -1864,9 +1890,19 @@ export class ControlPlaneDO extends DurableObject {
      * system-held definition of a key with no system-held definition stored (none at all included): its tenant-level seats are read here, in the unit, and
      * `seatedInScopes` carries what the coordinator read off the tenant's scopes. A refusal is answered
      * as data, so its text survives the hop, and writes nothing. The current coordinator calls this one
-     * (the same split as `transitionScope` and `transitionScopeOrRefusal`).
+     * (the same split as `transitionScope` and `transitionScopeOrRefusal`), through `reply` (#2526),
+     * with `audit`: the row, its `before` the role read here, commits with the definition. A
+     * coordinator from before #2526 passes none and records its own.
      */
-    defineRoleOrRefusal(tenantId, role, reservation = { reserved: [], declared: [] }, seatedInScopes = false) {
+    defineRoleOrRefusal(tenantId, role, reservation = { reserved: [], declared: [] }, seatedInScopes = false, audit) {
+        return this.ctx.storage.transactionSync(() => {
+            const outcome = this.defineRoleIn(tenantId, role, reservation, seatedInScopes);
+            if (audit && 'before' in outcome)
+                this.recordAdmin({ ...audit, before: outcome.before });
+            return outcome;
+        });
+    }
+    defineRoleIn(tenantId, role, reservation, seatedInScopes) {
         const tenantRoles = this.listRoles({ tenantId }).map((r) => ({
             key: r.role_key,
             permissions: JSON.parse(r.permissions),
@@ -1930,21 +1966,67 @@ export class ControlPlaneDO extends DurableObject {
         };
     }
     // -- tenant-level tuples (checker rules 1, 2, 4) ----------------------------
-    writeTenantTuple(tenantId, subject, relation, object, expiresAt) {
-        this.sql.exec(`INSERT OR REPLACE INTO _substrat_tenant_tuples
-         (tenant_id, subject, relation, object, expires_at)
-       VALUES (?, ?, ?, ?, ?)`, tenantId, subject, relation, object, expiresAt);
+    /**
+     * A tenant tuple, upserted. With `audit` (#2526, `grant` at the tenant node, called through
+     * `reply`), its admin row commits in the same transaction; without, as a coordinator from before
+     * #2526 calls it, and as this object's own units do, it is the bare write.
+     */
+    writeTenantTuple(tenantId, subject, relation, object, expiresAt, audit) {
+        const write = () => {
+            this.sql.exec(`INSERT OR REPLACE INTO _substrat_tenant_tuples
+           (tenant_id, subject, relation, object, expires_at)
+         VALUES (?, ?, ?, ?, ?)`, tenantId, subject, relation, object, expiresAt);
+            return true;
+        };
+        if (audit)
+            this.writeAndAudit(write, audit);
+        else
+            write();
+    }
+    /**
+     * #2526: `assignRole` at the tenant node — the role's reservation judged (`reserved`, what the
+     * coordinator's modules reserve to a system principal: a role mixing them with other keys is
+     * refused, #2430), the tuple and its admin row, in one unit. A refusal is answered as data and
+     * writes nothing. A role not defined here is not judged, as before.
+     */
+    assignTenantRole(tenantId, principal, roleKey, reserved, audit) {
+        return this.ctx.storage.transactionSync(() => {
+            const role = reserved.length > 0 ? this.getRole(tenantId, roleKey) : undefined;
+            const refused = role ? reservedRoleRefusal(role, new Set(reserved), 'platform') : null;
+            if (refused)
+                return { refused };
+            this.writeTenantTuple(tenantId, `principal:${principal}`, `role:${roleKey}`, `tenant:${tenantId}`, null);
+            this.recordAdmin(audit);
+            return {};
+        });
+    }
+    /**
+     * #2526: a tenant tuple that names an org — `grantToOrg` at the tenant node, and `addMember` —
+     * with its admin row, in one unit, refused `not_found` when the org is not in the tenant.
+     */
+    writeOrgTenantTuple(tenantId, orgId, subject, relation, object, expiresAt, audit) {
+        this.writeAndAudit(() => {
+            if (!this.readOrg(tenantId, orgId))
+                throw substratError('not_found', `unknown org ${orgId} in tenant ${tenantId}`);
+            this.writeTenantTuple(tenantId, subject, relation, object, expiresAt);
+            return true;
+        }, audit);
     }
     /**
      * #1743: a tenant-level `system:<module>` grant, refused while the record holds the module
      * off on any scope (`scopesSwitchedOffFor`). Synchronous, so the read and the write are one
-     * DO unit. Answers the switched-off scopes; non-empty means nothing was written.
+     * DO unit. Answers the switched-off scopes; non-empty means nothing was written. With `audit`
+     * (#2526, through `reply`), the row commits with the tuple, and a refusal records none.
      */
-    writeTenantSystemGrant(tenantId, moduleId, relation, expiresAt) {
-        const off = scopesSwitchedOffFor(this.kernelSql, tenantId, moduleId);
-        if (off.length === 0) {
+    writeTenantSystemGrant(tenantId, moduleId, relation, expiresAt, audit) {
+        let off = [];
+        this.writeAndAudit(() => {
+            off = scopesSwitchedOffFor(this.kernelSql, tenantId, moduleId);
+            if (off.length > 0)
+                return false;
             this.writeTenantTuple(tenantId, `system:${moduleId}`, relation, `tenant:${tenantId}`, expiresAt);
-        }
+            return true;
+        }, audit);
         return off;
     }
     // -- the hostname map (K-26) ------------------------------------------------
@@ -2138,7 +2220,11 @@ export class ControlPlaneDO extends DurableObject {
             scope_hostnames: JSON.parse(scope_hostnames_json),
         };
     }
-    /** Demote any current canonical for this surface — exactly one may hold it. */
+    /**
+     * Demote any current canonical for this surface — exactly one may hold it. This and
+     * `upsertHostname` are `bindHostnameInDirectory`'s steps; a coordinator from before #2526 still
+     * calls them directly.
+     */
     demoteCanonical(scopeId, surface) {
         this.sql.exec('UPDATE hostnames SET canonical = 0 WHERE scope_id = ? AND surface = ?', scopeId, surface);
     }
@@ -2151,8 +2237,62 @@ export class ControlPlaneDO extends DurableObject {
           status, status_note, canonical, created_at, custom_hostname_id, validation_records)
        VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, ?, ?, NULL, NULL)`, h.hostname, h.tenantId, h.scopeId, h.verticalSlug, h.surface, h.region, h.canonical ? 1 : 0, h.createdAt);
     }
-    setHostnameStatus(hostname, status, note) {
-        this.sql.exec('UPDATE hostnames SET status = ?, status_note = ? WHERE hostname = ?', status, note, hostname);
+    /**
+     * #2526: `bindHostname` as one unit — the scope (in the tenant), the name's current holder and
+     * whether it released the name (archived or reaped), the demotion of the surface's canonical,
+     * the bind and its admin row, whose vertical is the scope's as read here. A name another live
+     * scope holds is refused `conflict`, writing nothing; so is the demotion when the bind fails.
+     */
+    bindHostnameInDirectory(h, audit) {
+        this.ctx.storage.transactionSync(() => {
+            const scope = this.getScopeRecord(h.tenantId, h.scopeId);
+            if (!scope)
+                throw substratError('not_found', `unknown scope ${h.scopeId} in tenant ${h.tenantId}`);
+            const existing = this.readHostname(h.hostname);
+            if (existing && existing.scope_id !== h.scopeId) {
+                // A hostname routes to exactly one place; silently rebinding would move another
+                // tenant's traffic. Exception: the holder is ARCHIVED or REAPED (a deleted app, storage
+                // since wiped) — it has released the name, so the rebind reclaims it.
+                const holder = this.getScopeRecord(existing.tenant_id, existing.scope_id);
+                if (holder?.status !== 'archived' && holder?.status !== 'reaped') {
+                    throw substratError('conflict', `hostname '${h.hostname}' is already bound to another scope`);
+                }
+            }
+            if (h.canonical)
+                this.demoteCanonical(h.scopeId, h.surface);
+            this.upsertHostname({ ...h, verticalSlug: scope.vertical });
+            this.recordAdmin({ ...audit, vertical: scope.vertical });
+        });
+    }
+    /**
+     * With `audit` (#2526, through `reply`): the row is read here — refused `not_found` when the
+     * name is not bound — and a status it already holds writes nothing and records nothing;
+     * otherwise the update and its admin row, its target and `before` from that read, commit as
+     * one unit. Answers whether it wrote. Without, as a coordinator from before #2526 calls it, the
+     * bare update.
+     */
+    setHostnameStatus(hostname, status, note, audit) {
+        return this.auditedHostnameUpdate(hostname, (row) => row.status === status, () => this.sql.exec('UPDATE hostnames SET status = ?, status_note = ? WHERE hostname = ?', status, note, hostname).rowsWritten > 0, audit);
+    }
+    /**
+     * #2526: a hostname update with its admin row. Without `audit`, the bare `write`. With it, one
+     * unit: the row read (refused `not_found` when the name is not bound), nothing written and
+     * nothing recorded when `unchanged` judges it so, else the write and the row, whose target and
+     * `before` status are the row as read.
+     */
+    auditedHostnameUpdate(hostname, unchanged, write, audit) {
+        if (!audit)
+            return write();
+        return this.ctx.storage.transactionSync(() => {
+            const row = this.readHostname(hostname);
+            if (!row)
+                throw substratError('not_found', `unknown hostname '${hostname}'`);
+            if (unchanged(row))
+                return false; // idempotent, and a no-op is not audited
+            write();
+            this.recordAdmin({ ...audit, tenantId: row.tenant_id, scopeId: row.scope_id, before: { status: row.status } });
+            return true;
+        });
     }
     /**
      * Record the result of a Cloudflare-for-SaaS issuance step (§4.7) — the status the
@@ -2161,25 +2301,42 @@ export class ControlPlaneDO extends DurableObject {
      * `undefined`); the DNS records and status are refreshed each pass. This is the only
      * writer that moves a hostname off `pending` into `verifying`/`active`/`failed` for a
      * custom domain.
+     *
+     * With `audit` (#2526, through `reply`): the row is read here — refused `not_found` when the
+     * name is not bound — and a poll that finds nothing changed (the same status, the same records,
+     * the id already set) writes nothing and records nothing; otherwise the update and its admin
+     * row, its target and `before` from that read, commit as one unit. Answers whether it wrote.
+     * Without, as a coordinator from before #2526 calls it, the bare update.
      */
-    setHostnameIssuance(hostname, fields) {
-        if (fields.customHostnameId !== undefined) {
-            this.sql.exec(`UPDATE hostnames
+    setHostnameIssuance(hostname, fields, audit) {
+        // A poll that changes nothing is not an event, so the reconcile sweep does not flood the
+        // admin log with no-op rows every interval. No records are stored as NULL.
+        const unchanged = (row) => row.status === fields.status &&
+            (row.validation_records ?? null) === fields.validationRecords &&
+            (fields.customHostnameId === undefined || fields.customHostnameId === row.custom_hostname_id);
+        return this.auditedHostnameUpdate(hostname, unchanged, () => (fields.customHostnameId !== undefined
+            ? this.sql.exec(`UPDATE hostnames
             SET status = ?, status_note = ?, custom_hostname_id = ?, validation_records = ?
-          WHERE hostname = ?`, fields.status, fields.note, fields.customHostnameId, fields.validationRecords, hostname);
-        }
-        else {
-            this.sql.exec(`UPDATE hostnames SET status = ?, status_note = ?, validation_records = ? WHERE hostname = ?`, fields.status, fields.note, fields.validationRecords, hostname);
-        }
+          WHERE hostname = ?`, fields.status, fields.note, fields.customHostnameId, fields.validationRecords, hostname)
+            : this.sql.exec(`UPDATE hostnames SET status = ?, status_note = ?, validation_records = ? WHERE hostname = ?`, fields.status, fields.note, fields.validationRecords, hostname)).rowsWritten > 0, audit);
     }
     /**
      * Delete a binding and answer the row it removed, or null. With `owner`, only while the row
      * still names that tenant and scope (#2285): the delete decides it, not an earlier read.
+     * With `audit` (#2526, through `reply`), the admin row, its target and `before` from the row
+     * removed, commits with the delete; a delete that removed nothing records nothing.
      */
-    deleteHostname(hostname, owner) {
-        const rows = this.sql.exec(`DELETE FROM hostnames WHERE hostname = ?${owner ? ' AND tenant_id = ? AND scope_id = ?' : ''}
-       RETURNING tenant_id, scope_id, status`, hostname, ...(owner ? [owner.tenantId, owner.scopeId] : [])).toArray();
-        return rows[0] ?? null;
+    deleteHostname(hostname, owner, audit) {
+        let removed = null;
+        this.writeAndAudit(() => {
+            const rows = this.sql.exec(`DELETE FROM hostnames WHERE hostname = ?${owner ? ' AND tenant_id = ? AND scope_id = ?' : ''}
+         RETURNING tenant_id, scope_id, status`, hostname, ...(owner ? [owner.tenantId, owner.scopeId] : [])).toArray();
+            removed = rows[0] ?? null;
+            return removed !== null;
+        }, audit && (() => ({
+            ...audit, tenantId: removed.tenant_id, scopeId: removed.scope_id, before: { hostname, status: removed.status },
+        })));
+        return removed;
     }
     listHostnames(filter) {
         const where = [];
@@ -2243,10 +2400,8 @@ export class ControlPlaneDO extends DurableObject {
                     .exec(`SELECT v.id, v.admission_note FROM vertical_channels c JOIN vertical_versions v ON v.id = c.version_id
               WHERE c.vertical_slug = ? AND c.channel = 'prod'`, slug)
                     .toArray()[0];
-                if (prod?.admission_note === AUTO_ADMISSION_NOTE) {
-                    throw substratError('conflict', `vertical '${slug}' prod version ${prod.id} is auto-admitted (private self-serve) — ` +
-                        `a staff admit must vouch for it before listing`);
-                }
+                if (prod?.admission_note === AUTO_ADMISSION_NOTE)
+                    throw autoAdmittedProdRefusal(slug, prod.id);
             }
             return { listed: !!r.listed };
         }, audit);
@@ -2714,15 +2869,23 @@ export class ControlPlaneDO extends DurableObject {
      * Remove a reaped fork's directory presence: hostname bindings + the scope row
      * (preview-and-snapshots.md §9). The coordinator's deleteSnapshot calls this AFTER
      * wiping the scope DO's storage — the fork-only refusal lives there, not here.
+     * #2555: with `onlyWhile`, only a scope still in that status is removed, judged in the same unit,
+     * so a scope another call activated in between keeps its row; answers whether it was removed.
      */
-    deleteScopeDirectory(scopeId) {
-        this.ctx.storage.transactionSync(() => {
+    deleteScopeDirectory(scopeId, onlyWhile) {
+        return this.ctx.storage.transactionSync(() => {
+            if (onlyWhile) {
+                const row = this.sql.exec('SELECT status FROM scopes WHERE scope_id = ?', scopeId).toArray()[0];
+                if (row?.status !== onlyWhile)
+                    return false;
+            }
             this.sql.exec('UPDATE peer_bindings SET invalidated = 1 WHERE target_scope_id = ?', scopeId);
             this.sql.exec('DELETE FROM hostnames WHERE scope_id = ?', scopeId);
             forgetSwitchesOf(this.kernelSql, scopeId);
             this.forgetLifecycleDeliveries('scope_id = ?', scopeId);
             forgetScopeStorage(doRedactionSql(this.sql), scopeId);
             this.sql.exec('DELETE FROM scopes WHERE scope_id = ?', scopeId);
+            return true;
         });
     }
     /**
@@ -2747,12 +2910,28 @@ export class ControlPlaneDO extends DurableObject {
      * channel has none yet). A compare-and-set in one synchronous transaction, so no other promote
      * runs between the read and the write: a promote judged its gates against `from` across awaits,
      * and the one that lost the race is told so (`false`) and writes nothing, `audit` included.
+     *
+     * #2565: the vertical's `listed` is read in the same unit — refusing a listed vertical when
+     * `unlistedOnly`, and an auto-admitted version as a listed vertical's new prod. It replaces
+     * `moveChannel`, which judged neither: a new name, so a DO from before refuses the call and a
+     * coordinator from before finds no `moveChannel` to call. Both fail closed.
      */
-    moveChannel(from, history, audit) {
+    promoteChannel(from, history, unlistedOnly, audit) {
         return this.writeAndAudit(() => {
             const now = this.readChannel(history.vertical_slug, history.channel);
             if ((now?.version_id ?? null) !== from)
                 return false;
+            const vertical = this.readVertical(history.vertical_slug);
+            const listed = vertical?.listed;
+            if (listed && unlistedOnly)
+                throw listedPromoteRefusal();
+            // A re-promote of what prod already names, and what serves (if anything does), moves
+            // nothing, so it is not judged again. One whose serve would change what runs is.
+            const serving = vertical?.serving_ref && vertical.serving_version_id ? vertical.serving_version_id : history.version_id;
+            if (listed && history.channel === 'prod' && (from !== history.version_id || serving !== history.version_id) &&
+                this.versionAdmission(history.version_id).admission_note === AUTO_ADMISSION_NOTE) {
+                throw autoAdmittedProdRefusal(history.vertical_slug, history.version_id);
+            }
             this.sql.exec(`INSERT INTO vertical_channels (vertical_slug, channel, version_id, updated_at)
          VALUES (?, ?, ?, ?)
          ON CONFLICT (vertical_slug, channel) DO UPDATE SET version_id = ?, updated_at = ?`, history.vertical_slug, history.channel, history.version_id, history.at, history.version_id, history.at);
@@ -2805,6 +2984,15 @@ export class ControlPlaneDO extends DurableObject {
         this.sql.exec('INSERT INTO orgs (org_id, tenant_id, slug, name, created_at) VALUES (?, ?, ?, ?, ?)', orgId, tenantId, slug, name, createdAt);
         return true;
     }
+    /**
+     * #2526: `createOrg` with its admin row, in one unit; an org that already exists writes nothing,
+     * the row included. A new name rather than a trailing argument on `createOrg`, which an older
+     * ControlPlaneDO already lists in `REPLIED_METHODS`: there the argument would be dropped and the
+     * org created with no row, where an unknown method fails closed.
+     */
+    insertOrg(orgId, tenantId, slug, name, createdAt, audit) {
+        return this.writeAndAudit(() => this.createOrg(orgId, tenantId, slug, name, createdAt), audit);
+    }
     listOrgs(tenantId) {
         return this.sql
             .exec('SELECT * FROM orgs WHERE tenant_id = ? ORDER BY slug', tenantId)
@@ -2955,8 +3143,24 @@ export class ControlPlaneDO extends DurableObject {
     /**
      * Upsert; returns before/after for the host's audit row, `changed: false` when
      * the merged result equals what the row already carried (not audited upstream).
+     * With `audit` (#2526, through `reply`), an effective change commits with its admin row,
+     * `before` and `after` the grant as read and written here; an unchanged grant records none.
      */
-    grantEntitlement(tenantId, key, input, actor) {
+    grantEntitlement(tenantId, key, input, actor, audit) {
+        let result;
+        this.writeAndAudit(() => {
+            result = this.grantEntitlementIn(tenantId, key, input, actor);
+            return result.changed;
+        }, audit && (() => ({
+            ...audit,
+            before: result.before
+                ? { entitlementKey: key, expiresAt: result.before.expires_at, quota: result.before.quota, plan: result.before.plan }
+                : null,
+            after: { entitlementKey: key, expiresAt: result.after.expires_at, quota: result.after.quota, plan: result.after.plan },
+        })));
+        return result;
+    }
+    grantEntitlementIn(tenantId, key, input, actor) {
         const existing = this.readEntitlement(tenantId, key);
         const next = {
             expiresAt: input.expiresAt !== undefined ? input.expiresAt : (existing?.expires_at ?? null),
@@ -2994,12 +3198,23 @@ export class ControlPlaneDO extends DurableObject {
             },
         };
     }
-    /** DELETE; returns the removed row (the host's audit `before`), null if none. */
-    revokeEntitlement(tenantId, key) {
-        const existing = this.readEntitlement(tenantId, key);
-        if (!existing)
-            return null;
-        this.sql.exec('DELETE FROM _substrat_entitlements WHERE tenant_id = ? AND entitlement_key = ?', tenantId, key);
+    /**
+     * DELETE; returns the removed row (the host's audit `before`), null if none. With `audit`
+     * (#2526, through `reply`), the admin row, `before` the row removed, commits with the delete;
+     * a revoke of nothing held records nothing.
+     */
+    revokeEntitlement(tenantId, key, audit) {
+        let existing = null;
+        this.writeAndAudit(() => {
+            existing = this.readEntitlement(tenantId, key);
+            if (!existing)
+                return false;
+            this.sql.exec('DELETE FROM _substrat_entitlements WHERE tenant_id = ? AND entitlement_key = ?', tenantId, key);
+            return true;
+        }, audit && (() => ({
+            ...audit,
+            before: { entitlementKey: key, expiresAt: existing.expires_at, quota: existing.quota, plan: existing.plan },
+        })));
         return existing;
     }
     tenantHoldsEntitlement(tenantId, key) {
@@ -3338,6 +3553,42 @@ export class ControlPlaneDO extends DurableObject {
           granted_by, granted_at, revoked_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)`, row.connectionId, row.tenantId, row.vertical, row.permission, row.scopeId, row.expiresAt, row.grantedBy, row.grantedAt);
     }
+    /**
+     * #2526: `grantToConnection`'s directory half as one unit — the connection (live, in the grant's
+     * tenant) and, at a scope node, the scope (in that tenant, running the connection's vertical)
+     * judged as they stand now, the record (`recordConnectionGrant`), the tenant tuple at the tenant
+     * node, and the admin row, whose vertical and provider are the connection's as read here. A
+     * scope node's tuple is delivered by the coordinator after this commits; the record is what a
+     * reconcile re-seats it from when that delivery fails. Answers the connection's vertical.
+     */
+    grantConnectionInDirectory(row, audit) {
+        return this.ctx.storage.transactionSync(() => {
+            const conn = this.readConnection(row.connectionId);
+            if (!conn)
+                throw new Error(`connection not found: ${row.connectionId}`);
+            if (conn.revoked_at)
+                throw new Error(`connection ${row.connectionId} is revoked — grant nothing to it`);
+            if (conn.tenant_id !== row.tenantId) {
+                throw new Error(`connection ${row.connectionId} belongs to tenant ${conn.tenant_id} and cannot be granted anything in ${row.tenantId}`);
+            }
+            if (row.scopeId) {
+                const scope = this.getScopeRecord(row.tenantId, row.scopeId);
+                if (!scope)
+                    throw substratError('not_found', `unknown scope ${row.scopeId} in tenant ${row.tenantId}`);
+                if (scope.vertical !== conn.vertical) {
+                    throw new Error(`connection ${row.connectionId} is for vertical '${conn.vertical}' and scope ` +
+                        `${row.scopeId} runs '${scope.vertical ?? 'none'}'`);
+                }
+            }
+            this.recordConnectionGrant({ ...row, vertical: conn.vertical });
+            if (!row.scopeId) {
+                this.writeTenantTuple(row.tenantId, `connection:${row.connectionId}`, `granted:${row.permission}`, `tenant:${row.tenantId}`, row.expiresAt);
+            }
+            const after = (audit.after ?? {});
+            this.recordAdmin({ ...audit, vertical: conn.vertical, after: { ...after, provider: conn.provider } });
+            return { vertical: conn.vertical };
+        });
+    }
     // -- the kill switches' record (#1674, #2029) — `system-switch-record.ts` is the whole rule ---
     /** OFF's write, before the scope's switch moves (#1823). Answers the row as it was. */
     recordSwitchedOff(row) {