@agentplat/inference-control 0.3.0-beta.1 → 0.3.0-beta.2

package/dist/tools.js

@@ -1,4 +1,4 @@
-import { canonicalizeControlJsonV1, digestControlJsonV1, utf8ByteLength, } from './canonical.js';
+import { canonicalizeControlJsonV1, digestControlJsonV1, utf8ByteLength, } from "./canonical.js";
 export const MAX_ACTION_INPUT_BYTES_V1 = 65_536;
 export const MAX_CONTROL_JSON_DEPTH_V1 = 64;
 export const MAX_CONTROL_JSON_NODES_V1 = 65_536;
@@ -6,18 +6,18 @@ export function canonicalControlJson(value) {
     return canonicalizeControlJsonV1(value);
 }
 export function controlDigest(domain, value) {
-    if (domain === 'grant')
-        return digestControlJsonV1('state', value);
+    if (domain === "grant")
+        return digestControlJsonV1("state", value);
     return digestControlJsonV1(domain, value);
 }
 export function actionInputDigest(input) {
-    return controlDigest('action-input', input);
+    return controlDigest("action-input", input);
 }
 export function scopeDigest(scope) {
-    return controlDigest('scope', scope);
+    return controlDigest("scope", scope);
 }
 export function actionDigest(grant, binding) {
-    return controlDigest('action', {
+    return controlDigest("action", {
         scopeDigest: grant.scopeDigest,
         namespace: binding.namespace,
         toolId: binding.toolId,
@@ -42,10 +42,8 @@ function idempotencyKey(scope, key) {
 }
 function assertTime(time) {
     if (!Number.isSafeInteger(time) || time < 0)
-        throw new TypeError('logicalTimeMs must be a non-negative safe integer');
+        throw new TypeError("logicalTimeMs must be a non-negative safe integer");
 }
-const grantReserveCapability = Symbol('grant-ledger-reserve-capability');
-const grantOutcomeCapability = Symbol('grant-ledger-outcome-capability');
 /** In-memory, single-process ledger. Reservation is synchronous and linearized. */
 export class LocalGrantLedger {
     gatewayId;
@@ -61,25 +59,25 @@ export class LocalGrantLedger {
             grant.expiresAtLogicalMs <= grant.issuedAtLogicalMs ||
             grant.expiresAtLogicalMs - grant.issuedAtLogicalMs > 120_000 ||
             !grant.singleUse ||
-            grant.status !== 'issued' ||
+            grant.status !== "issued" ||
             grant.reservation !== null ||
             !isActionScopeV1(grant.scope) ||
             scopeDigest(grant.scope) !== grant.scopeDigest ||
             !/^sha256:[0-9a-f]{64}$/.test(grant.inputDigest) ||
             !/^sha256:[0-9a-f]{64}$/.test(grant.actionDigest))
-            throw new TypeError('Invalid Action Grant');
+            throw new TypeError("Invalid Action Grant");
         const prior = this.grants.get(grant.grantId);
         if (prior) {
-            if (controlDigest('grant', prior) !==
-                controlDigest('grant', grant))
-                throw new Error('state_conflict');
+            if (controlDigest("grant", prior) !==
+                controlDigest("grant", grant))
+                throw new Error("state_conflict");
             return prior;
         }
         const key = idempotencyKey(grant.scopeDigest, grant.idempotencyKey);
         const previous = this.idempotency.get(key);
         if (previous) {
             if (previous.actionDigest !== grant.actionDigest)
-                throw new Error('grant_idempotency_conflict');
+                throw new Error("grant_idempotency_conflict");
             return this.grants.get(previous.grantId);
         }
         const retained = freezeGrant(grant);
@@ -94,43 +92,6 @@ export class LocalGrantLedger {
         }));
         return retained;
     }
-    [grantReserveCapability](grantId, gatewayId, time, authority) {
-        this.time(time);
-        const grant = this.require(grantId);
-        if (grant.status !== 'issued')
-            throw new Error('grant_consumed');
-        if (time >= grant.expiresAtLogicalMs)
-            return this.expire(grant);
-        assertCurrentAuthority(grant.scope, grant.scopeDigest, authority);
-        const reservation = Object.freeze({
-            schemaVersion: 1,
-            reservationId: `${grantId}:reservation:${grant.stateGeneration + 1}`,
-            dispatchAttemptId: `${grantId}:dispatch:${grant.stateGeneration + 1}`,
-            reservedByGatewayId: gatewayId,
-            reservedStateGeneration: grant.stateGeneration + 1,
-            authorityGeneration: authorityGenerationFor(grant.scope, authority),
-            fencingToken: fencingTokenFor(grant.scope, authority),
-            reservedAtLogicalMs: time,
-        });
-        return this.replace({
-            ...grant,
-            stateGeneration: grant.stateGeneration + 1,
-            status: 'reserved',
-            reservation,
-        });
-    }
-    [grantOutcomeCapability](grantId, reservationId, dispatchAttemptId, status) {
-        const grant = this.require(grantId);
-        if (grant.status !== 'reserved' ||
-            grant.reservation?.reservationId !== reservationId ||
-            grant.reservation.dispatchAttemptId !== dispatchAttemptId)
-            throw new Error('state_conflict');
-        return this.replace({
-            ...grant,
-            stateGeneration: grant.stateGeneration + 1,
-            status,
-        });
-    }
     snapshot() {
         return Object.freeze({
             schemaVersion: 1,
@@ -146,27 +107,27 @@ export class LocalGrantLedger {
             !Number.isSafeInteger(snapshot.highWaterLogicalMs) ||
             snapshot.highWaterLogicalMs < 0 ||
             snapshot.highWaterLogicalMs < this.highWater)
-            throw new TypeError('Invalid Action Grant snapshot');
+            throw new TypeError("Invalid Action Grant snapshot");
         const grants = new Map();
         const idempotency = new Map();
         for (const source of snapshot.grants) {
             assertGrantSnapshot(source, snapshot.highWaterLogicalMs);
-            const grant = source.status === 'reserved'
+            const grant = source.status === "reserved"
                 ? {
                     ...source,
-                    status: 'indeterminate',
+                    status: "indeterminate",
                     stateGeneration: source.stateGeneration + 1,
                 }
                 : source;
             const frozen = freezeGrant(grant);
             if (grants.has(frozen.grantId))
-                throw new Error('state_conflict');
+                throw new Error("state_conflict");
             const key = idempotencyKey(frozen.scopeDigest, frozen.idempotencyKey);
             const previous = idempotency.get(key);
             if (previous && previous.actionDigest !== frozen.actionDigest)
-                throw new Error('grant_idempotency_conflict');
+                throw new Error("grant_idempotency_conflict");
             if (previous)
-                throw new Error('state_conflict');
+                throw new Error("state_conflict");
             grants.set(frozen.grantId, frozen);
             idempotency.set(key, Object.freeze({
                 schemaVersion: 1,
@@ -188,48 +149,227 @@ export class LocalGrantLedger {
     get(grantId) {
         return this.grants.get(grantId);
     }
-    replace(grant) {
-        const frozen = freezeGrant(grant);
-        this.grants.set(frozen.grantId, frozen);
-        this.idempotency.set(idempotencyKey(frozen.scopeDigest, frozen.idempotencyKey), Object.freeze({
-            schemaVersion: 1,
-            scopeDigest: frozen.scopeDigest,
-            idempotencyKey: frozen.idempotencyKey,
-            actionDigest: frozen.actionDigest,
-            grantId: frozen.grantId,
-            retainedOutcome: frozen.status,
-        }));
-        return frozen;
+    observeLogicalTime(logicalTimeMs) {
+        this.time(logicalTimeMs);
     }
-    expire(grant) {
-        return this.replace({
-            ...grant,
-            stateGeneration: grant.stateGeneration + 1,
-            status: 'expired',
+    loadGrant(grantId) {
+        return this.grants.get(grantId);
+    }
+    loadIdempotency(scope, key) {
+        return this.idempotency.get(idempotencyKey(scope, key));
+    }
+    createGrant(input) {
+        assertRepositoryPair(input.grant, input.idempotency);
+        const prior = this.grants.get(input.grant.grantId);
+        if (prior) {
+            const same = grantStateDigest(prior) === grantStateDigest(input.grant);
+            return Object.freeze({
+                status: same ? "existing" : "conflict",
+                conflictKind: same ? null : "grant",
+                grant: prior,
+            });
+        }
+        const key = idempotencyKey(input.idempotency.scopeDigest, input.idempotency.idempotencyKey);
+        const previous = this.idempotency.get(key);
+        if (previous) {
+            const found = this.grants.get(previous.grantId) ?? null;
+            const same = previous.actionDigest === input.idempotency.actionDigest &&
+                found !== null;
+            return Object.freeze({
+                status: same ? "existing" : "conflict",
+                conflictKind: same ? null : "idempotency",
+                grant: found,
+            });
+        }
+        const grant = freezeGrant(input.grant);
+        const record = freezeIdempotency(input.idempotency);
+        this.grants.set(grant.grantId, grant);
+        this.idempotency.set(key, record);
+        return Object.freeze({
+            status: "created",
+            conflictKind: null,
+            grant,
         });
     }
-    require(id) {
-        const grant = this.grants.get(id);
-        if (!grant)
-            throw new Error('grant_missing');
-        return grant;
+    compareAndSwapGrant(input) {
+        const current = this.grants.get(input.grantId);
+        if (!current ||
+            current.stateGeneration !== input.expectedStateGeneration ||
+            grantStateDigest(current) !== input.expectedGrantDigest)
+            return Object.freeze({ status: "conflict", grant: current ?? null });
+        if (input.nextGrant.grantId !== input.grantId ||
+            input.nextGrant.scopeDigest !== current.scopeDigest ||
+            input.nextGrant.idempotencyKey !== current.idempotencyKey)
+            throw new Error("state_conflict");
+        assertRepositoryPair(input.nextGrant, input.nextIdempotency);
+        const grant = freezeGrant(input.nextGrant);
+        this.grants.set(grant.grantId, grant);
+        this.idempotency.set(idempotencyKey(grant.scopeDigest, grant.idempotencyKey), freezeIdempotency(input.nextIdempotency));
+        return Object.freeze({ status: "updated", grant });
     }
     time(value) {
         assertTime(value);
         if (value < this.highWater)
-            throw new Error('logical_time_rollback');
+            throw new Error("logical_time_rollback");
         this.highWater = value;
     }
 }
-/** Gateway-only mutation helpers; intentionally not exported from this module. */
-function reserveGrantForGateway(ledger, grantId, gatewayId, time, authority) {
-    return ledger[grantReserveCapability](grantId, gatewayId, time, authority);
-}
-function settleGrantForGateway(ledger, grantId, reservationId, dispatchAttemptId, status) {
-    return ledger[grantOutcomeCapability](grantId, reservationId, dispatchAttemptId, status);
+/** Issues through the same exact-create port used by durable repositories. */
+export async function issueActionGrantV1(repository, source) {
+    assertIssuableGrant(source);
+    await repository.observeLogicalTime(source.issuedAtLogicalMs);
+    const grant = freezeGrant(source);
+    const idempotency = idempotencyForGrant(grant);
+    const result = await repository.createGrant({ grant, idempotency });
+    if (result.status === "conflict")
+        throw new Error(result.conflictKind === "idempotency"
+            ? "grant_idempotency_conflict"
+            : "state_conflict");
+    if (!result.grant)
+        throw new Error("repository_unavailable");
+    assertGrantSnapshot(result.grant, Number.MAX_SAFE_INTEGER);
+    if (result.status === "created") {
+        if (grantStateDigest(result.grant) !== grantStateDigest(grant))
+            throw new Error("state_conflict");
+    }
+    else if (result.grant.scopeDigest !== grant.scopeDigest ||
+        result.grant.idempotencyKey !== grant.idempotencyKey ||
+        result.grant.actionDigest !== grant.actionDigest) {
+        throw new Error("state_conflict");
+    }
+    return result.grant;
+}
+/** Resolves an indeterminate grant only from an explicit authoritative proof. */
+export async function reconcileActionGrantV1(repository, input) {
+    const grant = await repository.loadGrant(input.grantId);
+    if (!grant)
+        throw new Error("grant_missing");
+    assertGrantSnapshot(grant, Number.MAX_SAFE_INTEGER);
+    if ((grant.status === "dispatched" || grant.status === "failed") &&
+        grant.status === input.outcome &&
+        grant.reservation?.reservationId === input.reservationId &&
+        grant.reservation.dispatchAttemptId === input.dispatchAttemptId)
+        return grant;
+    if (grant.status !== "indeterminate" ||
+        grant.reservation?.reservationId !== input.reservationId ||
+        grant.reservation.dispatchAttemptId !== input.dispatchAttemptId)
+        throw new Error("state_conflict");
+    const next = freezeGrant({
+        ...grant,
+        stateGeneration: grant.stateGeneration + 1,
+        status: input.outcome,
+    });
+    if (!(await compareAndSwapGrantState(repository, grant, next)))
+        throw new Error("state_conflict");
+    return next;
+}
+/** Gateway-only semantic mutation helpers; intentionally not exported. */
+async function reserveGrantForGateway(repository, grantId, gatewayId, time, authority) {
+    await repository.observeLogicalTime(time);
+    const grant = await repository.loadGrant(grantId);
+    if (!grant)
+        throw new Error("grant_missing");
+    assertGrantSnapshot(grant, Number.MAX_SAFE_INTEGER);
+    if (grant.status !== "issued")
+        throw new Error("grant_consumed");
+    if (time >= grant.expiresAtLogicalMs) {
+        const expired = freezeGrant({
+            ...grant,
+            stateGeneration: grant.stateGeneration + 1,
+            status: "expired",
+        });
+        const written = await compareAndSwapGrantState(repository, grant, expired);
+        if (!written)
+            throw new Error("state_conflict");
+        throw new Error("grant_expired");
+    }
+    assertCurrentAuthority(grant.scope, grant.scopeDigest, authority);
+    const reservation = Object.freeze({
+        schemaVersion: 1,
+        reservationId: `${grantId}:reservation:${grant.stateGeneration + 1}`,
+        dispatchAttemptId: `${grantId}:dispatch:${grant.stateGeneration + 1}`,
+        reservedByGatewayId: gatewayId,
+        reservedStateGeneration: grant.stateGeneration + 1,
+        authorityGeneration: authorityGenerationFor(grant.scope, authority),
+        fencingToken: fencingTokenFor(grant.scope, authority),
+        reservedAtLogicalMs: time,
+    });
+    const next = freezeGrant({
+        ...grant,
+        stateGeneration: grant.stateGeneration + 1,
+        status: "reserved",
+        reservation,
+    });
+    if (!(await compareAndSwapGrantState(repository, grant, next)))
+        throw new Error("grant_consumed");
+    return next;
+}
+async function settleGrantForGateway(repository, grantId, reservationId, dispatchAttemptId, status) {
+    const grant = await repository.loadGrant(grantId);
+    if (!grant)
+        throw new Error("grant_missing");
+    assertGrantSnapshot(grant, Number.MAX_SAFE_INTEGER);
+    if (grant.status === status &&
+        grant.reservation?.reservationId === reservationId &&
+        grant.reservation.dispatchAttemptId === dispatchAttemptId)
+        return grant;
+    if (grant.status !== "reserved" ||
+        grant.reservation?.reservationId !== reservationId ||
+        grant.reservation.dispatchAttemptId !== dispatchAttemptId)
+        throw new Error("state_conflict");
+    const next = freezeGrant({
+        ...grant,
+        stateGeneration: grant.stateGeneration + 1,
+        status,
+    });
+    if (!(await compareAndSwapGrantState(repository, grant, next))) {
+        const current = await repository.loadGrant(grantId);
+        if (current?.status === status &&
+            current.reservation?.reservationId === reservationId &&
+            current.reservation.dispatchAttemptId === dispatchAttemptId)
+            return current;
+        throw new Error("state_conflict");
+    }
+    return next;
+}
+async function compareAndSwapGrantState(repository, current, next) {
+    const result = await repository.compareAndSwapGrant({
+        grantId: current.grantId,
+        expectedStateGeneration: current.stateGeneration,
+        expectedGrantDigest: grantStateDigest(current),
+        nextGrant: next,
+        nextIdempotency: idempotencyForGrant(next),
+    });
+    return (result.status === "updated" &&
+        result.grant !== null &&
+        grantStateDigest(result.grant) === grantStateDigest(next));
 }
 function assertGrantSnapshot(grant, highWater) {
     if (!isPlainRecord(grant) ||
+        !hasExactKeys(grant, [
+            "schemaVersion",
+            "grantId",
+            "stateGeneration",
+            "scope",
+            "scopeDigest",
+            "namespace",
+            "toolId",
+            "operation",
+            "actionBindingId",
+            "actionBindingVersion",
+            "handlerDigest",
+            "inputDigest",
+            "actionDigest",
+            "assessmentRequestId",
+            "assessmentId",
+            "assessmentTargetDigest",
+            "idempotencyKey",
+            "issuedAtLogicalMs",
+            "expiresAtLogicalMs",
+            "singleUse",
+            "status",
+            "reservation",
+        ]) ||
         grant.schemaVersion !== 1 ||
         !nonEmptyString(grant.grantId) ||
         !positiveInteger(grant.stateGeneration) ||
@@ -248,18 +388,28 @@ function assertGrantSnapshot(grant, highWater) {
         !isGrantStatus(grant.status) ||
         !nonEmptyString(grant.idempotencyKey) ||
         !nonEmptyString(grant.scopeDigest))
-        throw new TypeError('Invalid Action Grant snapshot');
-    if (grant.status === 'issued' || grant.status === 'expired') {
+        throw new TypeError("Invalid Action Grant snapshot");
+    if (grant.status === "issued" || grant.status === "expired") {
         if (grant.reservation !== null)
-            throw new TypeError('Invalid Action Grant snapshot');
+            throw new TypeError("Invalid Action Grant snapshot");
     }
     else if (!isActionReservation(grant.reservation, highWater, grant)) {
-        throw new TypeError('Invalid Action Grant snapshot');
+        throw new TypeError("Invalid Action Grant snapshot");
     }
 }
 function isActionReservation(value, highWater, grant) {
     return Boolean(value &&
         isPlainRecord(value) &&
+        hasExactKeys(value, [
+            "schemaVersion",
+            "reservationId",
+            "dispatchAttemptId",
+            "reservedByGatewayId",
+            "reservedStateGeneration",
+            "authorityGeneration",
+            "fencingToken",
+            "reservedAtLogicalMs",
+        ]) &&
         value.schemaVersion === 1 &&
         nonEmptyString(value.reservationId) &&
         nonEmptyString(value.dispatchAttemptId) &&
@@ -274,16 +424,56 @@ function isActionReservation(value, highWater, grant) {
                 value.authorityGeneration >= 0)) &&
         (value.fencingToken === null || nonEmptyString(value.fencingToken)));
 }
+function assertIssuableGrant(grant) {
+    assertGrantSnapshot(grant, grant.issuedAtLogicalMs);
+    if (grant.status !== "issued" || grant.reservation !== null)
+        throw new TypeError("Invalid Action Grant");
+}
+function grantStateDigest(grant) {
+    return controlDigest("grant", grant);
+}
+function idempotencyForGrant(grant) {
+    return Object.freeze({
+        schemaVersion: 1,
+        scopeDigest: grant.scopeDigest,
+        idempotencyKey: grant.idempotencyKey,
+        actionDigest: grant.actionDigest,
+        grantId: grant.grantId,
+        retainedOutcome: grant.status,
+    });
+}
+function freezeIdempotency(value) {
+    return Object.freeze({ ...value });
+}
+function assertRepositoryPair(grant, record) {
+    assertGrantSnapshot(grant, Number.MAX_SAFE_INTEGER);
+    if (!isPlainRecord(record) ||
+        !hasExactKeys(record, [
+            "schemaVersion",
+            "scopeDigest",
+            "idempotencyKey",
+            "actionDigest",
+            "grantId",
+            "retainedOutcome",
+        ]) ||
+        record.schemaVersion !== 1 ||
+        record.scopeDigest !== grant.scopeDigest ||
+        record.idempotencyKey !== grant.idempotencyKey ||
+        record.actionDigest !== grant.actionDigest ||
+        record.grantId !== grant.grantId ||
+        record.retainedOutcome !== grant.status)
+        throw new TypeError("Invalid Action Grant repository record");
+}
 function assertCurrentAuthority(scope, expectedScopeDigest, authority) {
-    if (authority.status !== 'current' ||
+    if (authority.status !== "current" ||
         !isActionScopeV1(authority.scope) ||
         scopeDigest(authority.scope) !== expectedScopeDigest)
-        throw new Error('grant_scope_mismatch');
-    if (scope.kind === 'coordinated' &&
+        throw new Error("grant_scope_mismatch");
+    if (scope.kind === "coordinated" &&
         (authority.authorityGeneration !== scope.authorityGeneration ||
             authority.fencingToken !== scope.fencingToken))
-        throw new Error('grant_fence_stale');
-    if (scope.kind === 'standalone' &&
+        throw new Error("grant_fence_stale");
+    if (scope.kind === "standalone" &&
         ((authority.authorityGeneration != null) !==
             (authority.fencingToken != null) ||
             (authority.authorityGeneration != null &&
@@ -291,11 +481,11 @@ function assertCurrentAuthority(scope, expectedScopeDigest, authority) {
                     authority.authorityGeneration < 0)) ||
             (authority.fencingToken != null &&
                 !nonEmptyString(authority.fencingToken))))
-        throw new Error('grant_fence_stale');
+        throw new Error("grant_fence_stale");
 }
 export function normalizeAuthorityResultV1(resolver, scope, actionDigestValue, value) {
     if (!isPlainRecord(value) || value.schemaVersion !== 1)
-        throw new Error('authority_result_invalid');
+        throw new Error("authority_result_invalid");
     const expectedScopeDigest = scopeDigest(scope);
     const common = value.resolverId === resolver.resolverId &&
         value.resolverVersion === resolver.resolverVersion &&
@@ -304,55 +494,55 @@ export function normalizeAuthorityResultV1(resolver, scope, actionDigestValue, v
         isDigest(value.scopeDigest) &&
         isDigest(value.actionDigest);
     if (!common)
-        throw new Error('authority_result_invalid');
-    if (value.status === 'stale' || value.status === 'unavailable') {
+        throw new Error("authority_result_invalid");
+    if (value.status === "stale" || value.status === "unavailable") {
         if (!hasExactKeys(value, [
-            'schemaVersion',
-            'status',
-            'resolverId',
-            'resolverVersion',
-            'scopeDigest',
-            'actionDigest',
+            "schemaVersion",
+            "status",
+            "resolverId",
+            "resolverVersion",
+            "scopeDigest",
+            "actionDigest",
         ]))
-            throw new Error('authority_result_invalid');
+            throw new Error("authority_result_invalid");
         return Object.freeze({ ...value });
     }
-    if (value.status !== 'current' ||
+    if (value.status !== "current" ||
         !hasExactKeys(value, [
-            'schemaVersion',
-            'status',
-            'resolverId',
-            'resolverVersion',
-            'scopeDigest',
-            'actionDigest',
-            'scope',
-            'authorityGeneration',
-            'fencingToken',
+            "schemaVersion",
+            "status",
+            "resolverId",
+            "resolverVersion",
+            "scopeDigest",
+            "actionDigest",
+            "scope",
+            "authorityGeneration",
+            "fencingToken",
         ]) ||
         !isActionScopeV1(value.scope) ||
         scopeDigest(value.scope) !== expectedScopeDigest ||
         (value.authorityGeneration !== null &&
-            (typeof value.authorityGeneration !== 'number' ||
+            (typeof value.authorityGeneration !== "number" ||
                 !Number.isSafeInteger(value.authorityGeneration) ||
                 value.authorityGeneration < 0)) ||
         (value.fencingToken !== null && !nonEmptyString(value.fencingToken)))
-        throw new Error('authority_result_invalid');
+        throw new Error("authority_result_invalid");
     return Object.freeze({
         ...value,
         scope: freezeScope(value.scope),
     });
 }
 function authorityGenerationFor(scope, authority) {
-    if (authority.status !== 'current')
+    if (authority.status !== "current")
         return null;
-    return scope.kind === 'coordinated'
+    return scope.kind === "coordinated"
         ? scope.authorityGeneration
         : (authority.authorityGeneration ?? null);
 }
 function fencingTokenFor(scope, authority) {
-    if (authority.status !== 'current')
+    if (authority.status !== "current")
         return null;
-    return scope.kind === 'coordinated'
+    return scope.kind === "coordinated"
         ? scope.fencingToken
         : (authority.fencingToken ?? null);
 }
@@ -368,7 +558,7 @@ function authorityMatchesReservation(scope, expectedScopeDigest, authority, rese
     }
 }
 function freezeScope(scope) {
-    if (scope.kind === 'standalone')
+    if (scope.kind === "standalone")
         return Object.freeze({
             schemaVersion: scope.schemaVersion,
             kind: scope.kind,
@@ -390,72 +580,72 @@ export function boundedCanonicalControlJsonV1(value, maximumBytes, reasonCode) {
         if (!Number.isSafeInteger(maximumBytes) ||
             maximumBytes < 1 ||
             maximumBytes > MAX_ACTION_INPUT_BYTES_V1)
-            throw new TypeError('Invalid canonical JSON byte limit');
+            throw new TypeError("Invalid canonical JSON byte limit");
         let nodes = 0;
         let canonicalBytes = 0;
         const addCanonicalBytes = (bytes) => {
             canonicalBytes += bytes;
             if (canonicalBytes > maximumBytes)
-                throw new TypeError('Canonical JSON exceeds its byte limit');
+                throw new TypeError("Canonical JSON exceeds its byte limit");
         };
         const active = new Set();
-        const stack = [{ kind: 'enter', value, depth: 0 }];
+        const stack = [{ kind: "enter", value, depth: 0 }];
         while (stack.length) {
             const item = stack.pop();
-            if (item.kind === 'exit') {
+            if (item.kind === "exit") {
                 active.delete(item.value);
                 continue;
             }
             nodes += 1;
             if (nodes > MAX_CONTROL_JSON_NODES_V1)
-                throw new TypeError('Canonical JSON contains too many nodes');
+                throw new TypeError("Canonical JSON contains too many nodes");
             if (item.depth > MAX_CONTROL_JSON_DEPTH_V1)
-                throw new TypeError('Canonical JSON is too deeply nested');
+                throw new TypeError("Canonical JSON is too deeply nested");
             if (item.value === null) {
                 addCanonicalBytes(4);
                 continue;
             }
             const valueType = typeof item.value;
-            if (valueType === 'string') {
+            if (valueType === "string") {
                 if (item.value.length > maximumBytes)
-                    throw new TypeError('Canonical JSON exceeds its byte limit');
+                    throw new TypeError("Canonical JSON exceeds its byte limit");
                 addCanonicalBytes(utf8ByteLength(JSON.stringify(item.value)));
                 continue;
             }
-            if (valueType === 'boolean') {
+            if (valueType === "boolean") {
                 addCanonicalBytes(item.value ? 4 : 5);
                 continue;
             }
-            if (valueType === 'number') {
+            if (valueType === "number") {
                 if (!Number.isFinite(item.value))
-                    throw new TypeError('Canonical JSON requires finite numbers');
+                    throw new TypeError("Canonical JSON requires finite numbers");
                 addCanonicalBytes(Object.is(item.value, -0)
                     ? 1
                     : utf8ByteLength(JSON.stringify(item.value)));
                 continue;
             }
-            if (valueType !== 'object')
-                throw new TypeError('Canonical JSON contains a non-JSON value');
+            if (valueType !== "object")
+                throw new TypeError("Canonical JSON contains a non-JSON value");
             const objectValue = item.value;
             if (active.has(objectValue))
-                throw new TypeError('Canonical JSON cannot contain cycles');
+                throw new TypeError("Canonical JSON cannot contain cycles");
             active.add(objectValue);
-            stack.push({ kind: 'exit', value: objectValue });
+            stack.push({ kind: "exit", value: objectValue });
             const keys = Reflect.ownKeys(objectValue);
-            if (keys.some((key) => typeof key === 'symbol'))
-                throw new TypeError('Canonical JSON cannot contain symbol keys');
+            if (keys.some((key) => typeof key === "symbol"))
+                throw new TypeError("Canonical JSON cannot contain symbol keys");
             if (Array.isArray(objectValue)) {
                 if (Object.getPrototypeOf(objectValue) !== Array.prototype)
-                    throw new TypeError('Canonical JSON requires plain arrays');
-                if (keys.length !== objectValue.length + 1 || !keys.includes('length'))
-                    throw new TypeError('Canonical JSON arrays cannot have extra keys');
+                    throw new TypeError("Canonical JSON requires plain arrays");
+                if (keys.length !== objectValue.length + 1 || !keys.includes("length"))
+                    throw new TypeError("Canonical JSON arrays cannot have extra keys");
                 addCanonicalBytes(2 + Math.max(0, objectValue.length - 1));
                 for (let index = objectValue.length - 1; index >= 0; index -= 1) {
                     const descriptor = Object.getOwnPropertyDescriptor(objectValue, String(index));
-                    if (!descriptor || !('value' in descriptor) || !descriptor.enumerable)
-                        throw new TypeError('Canonical JSON cannot contain sparse arrays or accessors');
+                    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+                        throw new TypeError("Canonical JSON cannot contain sparse arrays or accessors");
                     stack.push({
-                        kind: 'enter',
+                        kind: "enter",
                         value: descriptor.value,
                         depth: item.depth + 1,
                     });
@@ -464,18 +654,18 @@ export function boundedCanonicalControlJsonV1(value, maximumBytes, reasonCode) {
             }
             const prototype = Object.getPrototypeOf(objectValue);
             if (prototype !== Object.prototype && prototype !== null)
-                throw new TypeError('Canonical JSON requires plain objects');
+                throw new TypeError("Canonical JSON requires plain objects");
             addCanonicalBytes(2 + Math.max(0, keys.length - 1));
             for (let index = keys.length - 1; index >= 0; index -= 1) {
                 const key = keys[index];
                 if (key.length > maximumBytes)
-                    throw new TypeError('Canonical JSON exceeds its byte limit');
+                    throw new TypeError("Canonical JSON exceeds its byte limit");
                 addCanonicalBytes(utf8ByteLength(JSON.stringify(key)) + 1);
                 const descriptor = Object.getOwnPropertyDescriptor(objectValue, key);
-                if (!descriptor || !('value' in descriptor) || !descriptor.enumerable)
-                    throw new TypeError('Canonical JSON cannot contain accessors or hidden properties');
+                if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+                    throw new TypeError("Canonical JSON cannot contain accessors or hidden properties");
                 stack.push({
-                    kind: 'enter',
+                    kind: "enter",
                     value: descriptor.value,
                     depth: item.depth + 1,
                 });
@@ -483,7 +673,7 @@ export function boundedCanonicalControlJsonV1(value, maximumBytes, reasonCode) {
         }
         const canonical = canonicalizeControlJsonV1(value);
         if (utf8ByteLength(canonical) > maximumBytes)
-            throw new TypeError('Canonical JSON exceeds its byte limit');
+            throw new TypeError("Canonical JSON exceeds its byte limit");
         return canonical;
     }
     catch {
@@ -491,13 +681,13 @@ export function boundedCanonicalControlJsonV1(value, maximumBytes, reasonCode) {
     }
 }
 function freezeControlJsonObject(value, maximumBytes) {
-    return deepFreeze(JSON.parse(boundedCanonicalControlJsonV1(value, maximumBytes, 'action_not_permitted')));
+    return deepFreeze(JSON.parse(boundedCanonicalControlJsonV1(value, maximumBytes, "action_not_permitted")));
 }
 function freezeToolContext(value) {
     return deepFreeze(JSON.parse(JSON.stringify(value)));
 }
 function deepFreeze(value) {
-    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
         Object.freeze(value);
         for (const child of Object.values(value))
             deepFreeze(child);
@@ -505,33 +695,33 @@ function deepFreeze(value) {
     return value;
 }
 function isPlainRecord(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
+    if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
     const prototype = Object.getPrototypeOf(value);
     return ((prototype === Object.prototype || prototype === null) &&
-        Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => 'value' in descriptor));
+        Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => "value" in descriptor));
 }
 function isPlainArray(value) {
     return (Array.isArray(value) &&
         Object.getPrototypeOf(value) === Array.prototype &&
-        Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => 'value' in descriptor));
+        Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => "value" in descriptor));
 }
 function nonEmptyString(value) {
-    return typeof value === 'string' && value.length > 0;
+    return typeof value === "string" && value.length > 0;
 }
 function positiveInteger(value) {
     return Number.isSafeInteger(value) && value > 0;
 }
 function isDigest(value) {
-    return typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value);
+    return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
 }
 function isGrantStatus(value) {
-    return (value === 'issued' ||
-        value === 'reserved' ||
-        value === 'dispatched' ||
-        value === 'failed' ||
-        value === 'indeterminate' ||
-        value === 'expired');
+    return (value === "issued" ||
+        value === "reserved" ||
+        value === "dispatched" ||
+        value === "failed" ||
+        value === "indeterminate" ||
+        value === "expired");
 }
 export function isActionScopeV1(value) {
     if (!isPlainRecord(value) || value.schemaVersion !== 1)
@@ -543,44 +733,44 @@ export function isActionScopeV1(value) {
         positiveInteger(value.policyVersion);
     if (!common)
         return false;
-    if (value.kind === 'standalone')
+    if (value.kind === "standalone")
         return (hasExactKeys(value, [
-            'schemaVersion',
-            'kind',
-            'tenantId',
-            'runId',
-            'agentId',
-            'organizationId',
-            'workspaceId',
-            'policyId',
-            'policyVersion',
+            "schemaVersion",
+            "kind",
+            "tenantId",
+            "runId",
+            "agentId",
+            "organizationId",
+            "workspaceId",
+            "policyId",
+            "policyVersion",
         ]) &&
-            (typeof value.organizationId === 'string' ||
+            (typeof value.organizationId === "string" ||
                 value.organizationId === null) &&
-            (typeof value.workspaceId === 'string' || value.workspaceId === null));
-    return (value.kind === 'coordinated' &&
+            (typeof value.workspaceId === "string" || value.workspaceId === null));
+    return (value.kind === "coordinated" &&
         hasExactKeys(value, [
-            'schemaVersion',
-            'kind',
-            'tenantId',
-            'runId',
-            'agentId',
-            'policyId',
-            'policyVersion',
-            'meshId',
-            'objectiveId',
-            'objectiveRevision',
-            'workItemId',
-            'workItemRevision',
-            'peerId',
-            'instanceId',
-            'assignmentAuthorityId',
-            'assignmentEpoch',
-            'fencingToken',
-            'leaseExpiresAtLogicalMs',
-            'authorityGeneration',
-            'objectiveTerminal',
-            'workTerminal',
+            "schemaVersion",
+            "kind",
+            "tenantId",
+            "runId",
+            "agentId",
+            "policyId",
+            "policyVersion",
+            "meshId",
+            "objectiveId",
+            "objectiveRevision",
+            "workItemId",
+            "workItemRevision",
+            "peerId",
+            "instanceId",
+            "assignmentAuthorityId",
+            "assignmentEpoch",
+            "fencingToken",
+            "leaseExpiresAtLogicalMs",
+            "authorityGeneration",
+            "objectiveTerminal",
+            "workTerminal",
         ]) &&
         [
             value.meshId,
@@ -597,9 +787,9 @@ export function isActionScopeV1(value) {
             value.assignmentEpoch,
             value.leaseExpiresAtLogicalMs,
             value.authorityGeneration,
-        ].every((item) => typeof item === 'number' && Number.isSafeInteger(item) && item >= 0) &&
-        typeof value.objectiveTerminal === 'boolean' &&
-        typeof value.workTerminal === 'boolean');
+        ].every((item) => typeof item === "number" && Number.isSafeInteger(item) && item >= 0) &&
+        typeof value.objectiveTerminal === "boolean" &&
+        typeof value.workTerminal === "boolean");
 }
 function hasExactKeys(value, expected) {
     const actual = Object.getOwnPropertyNames(value).sort();
@@ -620,12 +810,12 @@ export class ActionGateway {
         this.ledger = ledger;
         if (!nonEmptyString(authorityResolver.resolverId) ||
             !positiveInteger(authorityResolver.resolverVersion))
-            throw new Error('dependency_rebind_failed');
+            throw new Error("dependency_rebind_failed");
         const maxActionInputBytes = limits.maxActionInputBytes ?? MAX_ACTION_INPUT_BYTES_V1;
         if (!Number.isSafeInteger(maxActionInputBytes) ||
             maxActionInputBytes < 1 ||
             maxActionInputBytes > MAX_ACTION_INPUT_BYTES_V1)
-            throw new Error('dependency_rebind_failed');
+            throw new Error("dependency_rebind_failed");
         this.maxActionInputBytes = maxActionInputBytes;
         this.binding = freezeBinding(binding);
         this.dispatcher = Object.freeze({
@@ -652,17 +842,18 @@ export class ActionGateway {
     }
     async invoke(input) {
         if (!isPlainRecord(input) ||
-            !hasExactKeys(input, Object.hasOwn(input, 'input')
-                ? ['schemaVersion', 'grantId', 'input', 'logicalTimeMs']
-                : ['schemaVersion', 'grantId', 'logicalTimeMs']) ||
+            !hasExactKeys(input, Object.hasOwn(input, "input")
+                ? ["schemaVersion", "grantId", "input", "logicalTimeMs"]
+                : ["schemaVersion", "grantId", "logicalTimeMs"]) ||
             input.schemaVersion !== 1 ||
             !nonEmptyString(input.grantId))
-            throw new Error('action_not_permitted');
+            throw new Error("action_not_permitted");
         const value = freezeControlJsonObject(input.input ?? {}, this.maxActionInputBytes);
         const digest = actionInputDigest(value);
-        const grant = this.ledger.get(input.grantId);
+        const grant = await this.ledger.loadGrant(input.grantId);
         if (!grant)
-            throw new Error('grant_missing');
+            throw new Error("grant_missing");
+        assertGrantSnapshot(grant, Number.MAX_SAFE_INTEGER);
         if (grant.actionBindingId !== this.binding.actionBindingId ||
             grant.actionBindingVersion !== this.binding.actionBindingVersion ||
             grant.namespace !== this.binding.namespace ||
@@ -678,26 +869,26 @@ export class ActionGateway {
             this.binding.fencingMode !== this.dispatcher.fencingMode ||
             grant.inputDigest !== digest ||
             grant.actionDigest !== actionDigest(grant, this.binding))
-            throw new Error('grant_action_mismatch');
-        if (grant.scope.kind === 'coordinated' &&
-            (this.binding.fencingMode !== 'downstream_atomic' ||
-                this.dispatcher.fencingMode !== 'downstream_atomic'))
-            throw new Error('dependency_rebind_failed');
+            throw new Error("grant_action_mismatch");
+        if (grant.scope.kind === "coordinated" &&
+            (this.binding.fencingMode !== "downstream_atomic" ||
+                this.dispatcher.fencingMode !== "downstream_atomic"))
+            throw new Error("dependency_rebind_failed");
         if (!(await this.assessmentResolver.consumeCurrent(grant, input.logicalTimeMs)))
-            throw new Error('grant_assessment_mismatch');
+            throw new Error("grant_assessment_mismatch");
         const first = normalizeAuthorityResultV1(this.authorityResolver, grant.scope, grant.actionDigest, await this.authorityResolver.resolve(grant.scope, grant.actionDigest, input.logicalTimeMs));
-        const reserved = reserveGrantForGateway(this.ledger, grant.grantId, this.ledger.gatewayId, input.logicalTimeMs, first);
+        const reserved = await reserveGrantForGateway(this.ledger, grant.grantId, this.ledger.gatewayId, input.logicalTimeMs, first);
         const reservation = reserved.reservation;
         try {
             const context = freezeToolContext(await this.contextResolver.resolve(reserved.scope, this.binding));
             if (context.tenant.tenantId !== reserved.scope.tenantId ||
                 context.toolId !== this.binding.toolId ||
                 context.runId !== reserved.scope.runId)
-                throw new Error('invocation_context_mismatch');
+                throw new Error("invocation_context_mismatch");
             const latest = normalizeAuthorityResultV1(this.authorityResolver, reserved.scope, reserved.actionDigest, await this.authorityResolver.resolve(reserved.scope, reserved.actionDigest, input.logicalTimeMs));
             if (!authorityMatchesReservation(reserved.scope, reserved.scopeDigest, latest, reservation)) {
-                settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, 'failed');
-                throw new Error('grant_fence_stale');
+                await settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, "failed");
+                throw new Error("grant_fence_stale");
             }
             let assessmentStillCurrent = false;
             try {
@@ -707,8 +898,8 @@ export class ActionGateway {
                 assessmentStillCurrent = false;
             }
             if (!assessmentStillCurrent) {
-                settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, 'failed');
-                throw new Error('grant_assessment_mismatch');
+                await settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, "failed");
+                throw new Error("grant_assessment_mismatch");
             }
             const permit = Object.freeze({
                 schemaVersion: 1,
@@ -728,13 +919,13 @@ export class ActionGateway {
                 context,
                 permit,
             });
-            settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, result.ok ? 'dispatched' : 'failed');
+            await settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, result.ok ? "dispatched" : "failed");
             return result;
         }
         catch (error) {
-            const current = this.ledger.get(reserved.grantId);
-            if (current?.status === 'reserved')
-                settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, 'indeterminate');
+            const current = await this.ledger.loadGrant(reserved.grantId);
+            if (current?.status === "reserved")
+                await settleGrantForGateway(this.ledger, reserved.grantId, reservation.reservationId, reservation.dispatchAttemptId, "indeterminate");
             throw error;
         }
     }
@@ -742,8 +933,8 @@ export class ActionGateway {
 export async function freezeToolRegistryBinding(registry, toolId, binding) {
     const found = await registry.get(toolId);
     if (!found)
-        throw new Error('action_not_permitted');
-    const handlerDigest = controlDigest('handler-binding', {
+        throw new Error("action_not_permitted");
+    const handlerDigest = controlDigest("handler-binding", {
         definition: found.definition,
         binding: { ...binding, toolId },
     });