@smartmemory/stratum 0.3.4 → 0.4.0

package/dist/guard/transition.js

@@ -4,16 +4,24 @@ import { existsSync, statSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import { canonicalJson } from "./canonical.js";
 import { commandsAllowed, evaluateEvidence, parsePredicateStatement, } from "./evidence.js";
-import { CommandExecutionDisabled, EvidenceParseError, GuardAlreadyRegistered, GuardEngineOwned, GuardNotFound, GuardTampered, IdempotencyConflict, IllegalEdge, InvalidStateName, InvalidWorkspaceRoot, OverrideUnavailable, ParanoidEdgeNeedsTrustedEvidence, StaleFromState, } from "./errors.js";
+import { CommandExecutionDisabled, EvidenceParseError, GuardAlreadyRegistered, GuardEngineOwned, GuardNotFound, GuardTampered, IdempotencyConflict, IllegalEdge, IncompatiblePolicyUpgrade, InvalidStateName, InvalidWorkspaceRoot, OverrideUnavailable, ParanoidEdgeNeedsTrustedEvidence, StaleFromState, UpgradeDescriptorMismatch, } from "./errors.js";
+import { verifyAuthorization } from "./authorization.js";
+import { findDescriptor, loadDescriptorFile } from "./descriptors.js";
 import { guardChecksum } from "./fingerprint.js";
 import { GuardRegistry, LedgerEntry, appendLedger, assertStillHeld, findByIdempotencyKey, isValidStateName, loadRegistry, loadRegistryRaw, persistRegistry, readEngineOwner, readLedger, resourceDir, resourceLock, writeTsOwnerMarker, } from "./store.js";
 import { evaluateJudgedViaCodex } from "../judge/codex_judged.js";
 import { evaluateJudged, } from "../judge/judged.js";
 import { judgeBackend } from "../mcp/server.js";
+import { guardEdgePredicatesFor, sourceFromPredicate, validateBundle } from "../policy/bundle.js";
+import { buildGuardTransitionEvent } from "../policy/events.js";
+import { emitPolicyEvent } from "../policy/smartmemory_client.js";
 const TRUSTED_TYPE = "deterministic";
+const RESERVED_STATE_NAMES = new Set(["__proto__", "constructor", "prototype"]);
 const LLM_TYPES = new Set(["verified", "judged"]);
 let acquireResourceLock = resourceLock;
 let fenceResourceLock = assertStillHeld;
+let warnedGuardRunIdFallback = false;
+const legacyDigestMatchesLogged = new Set();
 /** Replace only the orchestration lock seams in isolated tests. */
 export function setGuardLockingForTests(lock, fence) {
     const previousLock = acquireResourceLock;
@@ -36,16 +44,38 @@ export function _nowMs() {
 export function _edgeKey(fromState, toState) {
     return `${fromState}->${toState}`;
 }
-export function _payloadDigest(fromState, toState, artifacts, modifiedFiles, resolvedBy) {
-    const canonical = canonicalJson({
+export function _payloadDigest(fromState, toState, artifacts, modifiedFiles, resolvedBy, policyChecksum) {
+    return payloadDigestForVersion(fromState, toState, artifacts, modifiedFiles, resolvedBy, policyChecksum, 2);
+}
+/** Recompute persisted digest material according to the entry that owns it. */
+export function payloadDigestForVersion(fromState, toState, artifacts, modifiedFiles, resolvedBy, policyChecksum, digestVersion) {
+    // The registry checksum covers graph, source-stamped edge predicates,
+    // terminal states, and effective stakes. Signing it into every transition
+    // payload makes the enforced policy replay-stable ledger material.
+    const material = {
         from_state: fromState,
         to_state: toState,
         artifacts,
         modified_files: [...modifiedFiles].sort(),
         resolved_by: resolvedBy,
-    });
+    };
+    if (digestVersion === 2)
+        material.policy_checksum = policyChecksum;
+    const canonical = canonicalJson(material);
     return createHash("sha256").update(canonical, "utf8").digest("hex");
 }
+export function noteLegacyDigestMatch(resourceId) {
+    if (legacyDigestMatchesLogged.has(resourceId))
+        return;
+    legacyDigestMatchesLogged.add(resourceId);
+    console.warn(`guard ${resourceId}: matched legacy payload digest version 1`);
+}
+function payloadDigests(fromState, toState, artifacts, modifiedFiles, resolvedBy, policyChecksum) {
+    return {
+        1: payloadDigestForVersion(fromState, toState, artifacts, modifiedFiles, resolvedBy, policyChecksum, 1),
+        2: payloadDigestForVersion(fromState, toState, artifacts, modifiedFiles, resolvedBy, policyChecksum, 2),
+    };
+}
 function assertTsOwnedForMutation(resourceId) {
     if (readEngineOwner(resourceId) === "ts")
         return;
@@ -147,6 +177,36 @@ export function* _allEdgePredicates(edgePredicates) {
     }
 }
 export function _validatePolicy(graph, edgePredicates, initial, terminal, stakes, workspaceRoot) {
+    // Shape before names. The MCP contract types graph/terminal as "object" and
+    // "array", so an adjacency value can arrive as a bare string — and a string
+    // is iterable (its chars pass the name check) while
+    // `String.prototype.includes` matches SUBSTRINGS, so a string adjacency
+    // would make the edge-legality check accept states nobody declared.
+    // Rejecting the shape here covers register, migrate and upgrade at once.
+    if (!Array.isArray(terminal) || terminal.some((name) => typeof name !== "string")) {
+        throw new InvalidStateName("terminal must be an array of state names");
+    }
+    // Duplicates would make `terminal` a multiset, so "frozen exactly" could not
+    // be checked by set equality (`["shipped"]` vs `["shipped","shipped"]` is a
+    // token-free change that set comparison waves through).
+    if (new Set(terminal).size !== terminal.length) {
+        throw new InvalidStateName("terminal must not contain duplicate state names");
+    }
+    for (const [state, targets] of Object.entries(graph)) {
+        if (!Array.isArray(targets) || targets.some((target) => typeof target !== "string")) {
+            throw new InvalidStateName(`graph[${JSON.stringify(state)}] must be an array of state names`);
+        }
+    }
+    for (const [edge, predicates] of Object.entries(edgePredicates)) {
+        if (!Array.isArray(predicates)
+            || predicates.some((predicate) => typeof predicate !== "object" || predicate === null || Array.isArray(predicate))) {
+            throw new EvidenceParseError(`edge_predicates[${JSON.stringify(edge)}] must be an array of predicate objects`);
+        }
+    }
+    for (const [edge, stake] of Object.entries(stakes)) {
+        if (typeof stake !== "string")
+            throw new InvalidStateName(`stakes[${JSON.stringify(edge)}] must be a string`);
+    }
     const names = new Set([...Object.keys(graph), ...terminal, initial]);
     for (const targets of Object.values(graph))
         for (const target of targets)
@@ -155,6 +215,14 @@ export function _validatePolicy(graph, edgePredicates, initial, terminal, stakes
         if (!isValidStateName(name)) {
             throw new InvalidStateName(`invalid state name ${JSON.stringify(name)} (allowed: [A-Za-z0-9_.-])`);
         }
+        // `__proto__` and friends pass the character class but are not ordinary
+        // object keys: a policy carrying one behaves differently depending on
+        // whether it is read as an own property or through the prototype chain, and
+        // a guard policy must mean exactly one thing. Same reservation the IR schema
+        // applies to contract field names.
+        if (RESERVED_STATE_NAMES.has(name)) {
+            throw new InvalidStateName(`reserved state name ${JSON.stringify(name)}`);
+        }
     }
     if (!Object.hasOwn(graph, initial) && !terminal.includes(initial)) {
         throw new InvalidStateName(`initial state ${JSON.stringify(initial)} is not a node in the graph`);
@@ -172,7 +240,7 @@ export function _validatePolicy(graph, edgePredicates, initial, terminal, stakes
         const parsed = parsePredicateStatement(statement);
         if (parsed.name === "command_exit_zero")
             usesCommand = true;
-        if (["server_file_exists", "git_commit_exists", "command_exit_zero"].includes(parsed.name))
+        if (["server_file_exists", "server_file_contains", "git_commit_exists", "command_exit_zero"].includes(parsed.name))
             needsWorkspace = true;
     }
     if (usesCommand && !commandsAllowed()) {
@@ -199,9 +267,20 @@ export function _validatePolicy(graph, edgePredicates, initial, terminal, stakes
         }
     }
 }
-export async function registerGuard(resourceId, graph, edgePredicates, initial, terminal = [], stakes = {}, workspaceRoot = null) {
-    _validatePolicy(graph, edgePredicates, initial, terminal, stakes, workspaceRoot);
-    const checksum = guardChecksum(graph, edgePredicates, terminal, stakes);
+export async function registerGuard(resourceId, graph, edgePredicates, initial, terminal = [], stakes = {}, workspaceRoot = null, policyBundle) {
+    const bundle = policyBundle === undefined ? undefined : validateBundle(policyBundle);
+    let effectivePredicates = edgePredicates;
+    const effectiveStakes = structuredClone(stakes);
+    if (bundle !== undefined) {
+        effectivePredicates = structuredClone(edgePredicates);
+        for (const [fromState, targets] of Object.entries(graph)) {
+            for (const toState of targets)
+                effectivePredicates[`${fromState}->${toState}`] ??= [];
+        }
+        effectivePredicates = guardEdgePredicatesFor(bundle, resourceId, effectivePredicates, effectiveStakes);
+    }
+    _validatePolicy(graph, effectivePredicates, initial, terminal, effectiveStakes, workspaceRoot);
+    const checksum = guardChecksum(graph, effectivePredicates, terminal, effectiveStakes);
     const resourceDirectoryExisted = existsSync(resourceDir(resourceId));
     const status = await acquireResourceLock(resourceId, async ({ token }) => {
         const owner = readEngineOwner(resourceId);
@@ -212,21 +291,30 @@ export async function registerGuard(resourceId, graph, edgePredicates, initial,
         }
         const existing = loadRegistryRaw(resourceId);
         if (existing !== null) {
-            if (existing.checksum === checksum)
+            if (existing.checksum === checksum) {
+                if (bundle !== undefined && existing.bundle_id !== bundle.bundle_id) {
+                    const previousBundleId = existing.bundle_id;
+                    existing.bundle_id = bundle.bundle_id;
+                    await fenceResourceLock(resourceId, token);
+                    persistRegistry(existing);
+                    console.warn(`guard ${resourceId}: refreshed bundle_id from ${previousBundleId ?? "<unset>"} to ${bundle.bundle_id}`);
+                }
                 return "exists";
+            }
             throw new GuardAlreadyRegistered(`guard ${JSON.stringify(resourceId)} already registered with a different policy; use migrate`);
         }
         const registry = new GuardRegistry({
             resource_id: resourceId,
             graph,
-            edge_predicates: edgePredicates,
+            edge_predicates: effectivePredicates,
             initial,
             terminal,
-            stakes,
+            stakes: effectiveStakes,
             checksum,
             graph_version: 1,
             workspace_root: workspaceRoot,
             current_state: initial,
+            ...(bundle !== undefined ? { bundle_id: bundle.bundle_id } : {}),
         });
         await fenceResourceLock(resourceId, token);
         persistRegistry(registry);
@@ -234,17 +322,27 @@ export async function registerGuard(resourceId, graph, edgePredicates, initial,
     });
     return { guard_id: resourceId, checksum, status };
 }
-export function _maybeReplay(registry, idempotencyKey, payloadDigest) {
+export function _maybeReplay(registry, idempotencyKey, digests) {
     if (!idempotencyKey)
         return null;
     const prior = findByIdempotencyKey(registry.resource_id, idempotencyKey);
     if (prior === null)
         return null;
-    if (prior.payload_digest !== payloadDigest) {
+    if (prior.payload_digest !== digests[prior.payload_digest_version]) {
         throw new IdempotencyConflict(`idempotency_key ${JSON.stringify(idempotencyKey)} reused with a different payload`);
     }
+    if (prior.payload_digest_version === 1)
+        noteLegacyDigestMatch(registry.resource_id);
     const verdict = prior.verdict ?? _evidenceToVerdictDict({ met: prior.outcome === "applied", perPredicate: [] }, registry.stakes[_edgeKey(prior.from_state, prior.to_state)] ?? "default", "replayed idempotent transition");
-    return { status: "replayed", verdict, ledger_ref: prior.entry_digest, current_state: registry.current_state };
+    return {
+        status: "replayed",
+        verdict,
+        ledger_ref: prior.entry_digest,
+        current_state: registry.current_state,
+        entry_digest: prior.entry_digest,
+        prev_digest: prior.prev_digest,
+        payload_digest: prior.payload_digest ?? "",
+    };
 }
 function defaultJudge() {
     return judgeBackend() === "openai"
@@ -287,6 +385,7 @@ async function evaluateLlmPredicates(predicates, stakes, judge, context) {
         // estimate remains operational telemetry rather than ledger material.
         dollars: 0,
         turns: results.length,
+        evaluations: results.map(({ predicate, result }) => ({ predicate, met: result.holds })),
     };
 }
 export async function guardTransition(resourceId, fromState, toState, options = {}) {
@@ -294,7 +393,9 @@ export async function guardTransition(resourceId, fromState, toState, options =
     const modifiedFiles = options.modifiedFiles ?? [];
     const idempotencyKey = options.idempotencyKey ?? null;
     const resolvedBy = options.resolvedBy ?? "agent";
-    const payloadDigest = _payloadDigest(fromState, toState, artifacts, modifiedFiles, resolvedBy);
+    if (resolvedBy !== "agent" && resolvedBy !== "human") {
+        throw new EvidenceParseError(`resolved_by must be "agent" or "human", got ${JSON.stringify(resolvedBy)}`);
+    }
     // Phase 1: cheap structural checks while holding the resource lock.
     const snapshot = await acquireResourceLock(resourceId, () => {
         assertTsOwnedForMutation(resourceId);
@@ -304,13 +405,14 @@ export async function guardTransition(resourceId, fromState, toState, options =
         if (guardChecksum(registry.graph, registry.edge_predicates, registry.terminal, registry.stakes) !== registry.checksum) {
             throw new GuardTampered(`guard ${JSON.stringify(resourceId)} policy checksum mismatch`);
         }
-        const replay = _maybeReplay(registry, idempotencyKey, payloadDigest);
+        const digests = payloadDigests(fromState, toState, artifacts, modifiedFiles, resolvedBy, registry.checksum);
+        const replay = _maybeReplay(registry, idempotencyKey, digests);
         if (replay !== null)
             return { replay };
         if (fromState !== registry.current_state) {
             throw new StaleFromState(`from_state ${JSON.stringify(fromState)} != current_state ${JSON.stringify(registry.current_state)}`);
         }
-        if (!(registry.graph[fromState] ?? []).includes(toState)) {
+        if (!_declaresEdge(registry.graph, fromState, toState)) {
             throw new IllegalEdge(`${_edgeKey(fromState, toState)} is not a legal edge`);
         }
         const edge = _edgeKey(fromState, toState);
@@ -321,14 +423,19 @@ export async function guardTransition(resourceId, fromState, toState, options =
             stakes: registry.stakes[edge] ?? "default",
             workspaceRoot: registry.workspace_root,
             ledgerEntries: readLedger(resourceId),
+            payloadDigests: digests,
         };
     });
     if (snapshot.replay !== null)
         return snapshot.replay;
+    const digests = snapshot.payloadDigests;
+    const payloadDigest = digests[2];
     // Phase 2: evidence and judge evaluation deliberately run outside the lock.
     const trusted = snapshot.predicates.filter((predicate) => _ptype(predicate) === TRUSTED_TYPE);
     const llm = snapshot.predicates.filter((predicate) => LLM_TYPES.has(_ptype(predicate)));
     const evidence = await evaluateEvidence(trusted, snapshot.workspaceRoot, snapshot.ledgerEntries);
+    const predicateResults = new Map();
+    trusted.forEach((predicate, index) => predicateResults.set(predicate, evidence.perPredicate[index]?.met ?? false));
     let combinedMet;
     let verdict;
     if (llm.length === 0) {
@@ -337,22 +444,27 @@ export async function guardTransition(resourceId, fromState, toState, options =
     }
     else if (options.judge === null) {
         combinedMet = false;
+        for (const predicate of llm)
+            predicateResults.set(predicate, false);
         verdict = _evidenceToVerdictDict({ met: false, perPredicate: evidence.perPredicate }, snapshot.stakes, "LLM-tier predicates present but no verifier available");
     }
     else {
         const judged = await evaluateLlmPredicates(llm, snapshot.stakes, options.judge ?? defaultJudge(), {
             result: { resource_id: resourceId, edge: snapshot.edge, artifacts, modified_files: modifiedFiles },
         });
+        for (const evaluation of judged.evaluations)
+            predicateResults.set(evaluation.predicate, evaluation.met);
         [combinedMet, verdict] = _mergeVerdict(evidence, judged, snapshot.stakes);
     }
     verdict = normalizeVerdictForLedger(verdict);
+    const ruleVerdicts = ruleVerdictsFor(snapshot.predicates, predicateResults);
     // Phase 3: optimistic commit under a newly-acquired lock.
     return acquireResourceLock(resourceId, async ({ token }) => {
         assertTsOwnedForMutation(resourceId);
         const registry = loadRegistry(resourceId);
         if (registry === null)
             throw new GuardNotFound(`no guard registered for ${JSON.stringify(resourceId)}`);
-        const replay = _maybeReplay(registry, idempotencyKey, payloadDigest);
+        const replay = _maybeReplay(registry, idempotencyKey, digests);
         if (replay !== null)
             return replay;
         if (registry.current_state !== fromState) {
@@ -361,7 +473,7 @@ export async function guardTransition(resourceId, fromState, toState, options =
         if (guardChecksum(registry.graph, registry.edge_predicates, registry.terminal, registry.stakes) !== registry.checksum) {
             throw new GuardTampered(`guard ${JSON.stringify(resourceId)} policy checksum mismatch during commit`);
         }
-        if (!(registry.graph[fromState] ?? []).includes(toState)) {
+        if (!_declaresEdge(registry.graph, fromState, toState)) {
             // Python has the same latent eval-outside-lock race; Slice E should add this re-check there too.
             throw new IllegalEdge(`${_edgeKey(fromState, toState)} is no longer a legal edge after evaluation`);
         }
@@ -383,19 +495,66 @@ export async function guardTransition(resourceId, fromState, toState, options =
             registry.current_state = toState;
             persistRegistry(registry);
         }
-        return { status: outcome, verdict, ledger_ref: ledgerRef, current_state: registry.current_state };
+        if (registry.bundle_id !== undefined) {
+            firePolicyEvent(buildGuardTransitionEvent({
+                runId: guardEventRunId(options.runId, resourceId),
+                bundleId: registry.bundle_id,
+                resourceId,
+                entry,
+                rulesEvaluated: ruleVerdicts,
+            }));
+        }
+        return {
+            status: outcome,
+            verdict,
+            ledger_ref: ledgerRef,
+            current_state: registry.current_state,
+            entry_digest: entry.entry_digest,
+            prev_digest: entry.prev_digest,
+            payload_digest: entry.payload_digest ?? "",
+        };
     });
 }
-export function _checkOverrideToken(token) {
-    const expected = process.env.STRATUM_GUARD_OVERRIDE_TOKEN;
-    if (!expected) {
-        throw new OverrideUnavailable("override unavailable: STRATUM_GUARD_OVERRIDE_TOKEN not set in server env");
+function ruleVerdictsFor(predicates, results) {
+    const verdicts = [];
+    for (const predicate of predicates) {
+        const source = sourceFromPredicate(predicate);
+        if (source === undefined)
+            continue;
+        const type = _ptype(predicate);
+        verdicts.push({
+            rule_id: typeof predicate.id === "string" ? predicate.id : source.record_id,
+            source: structuredClone(source),
+            met: results.get(predicate) ?? false,
+            predicate_type: type === "judged" || type === "verified" ? type : "deterministic",
+        });
     }
-    if (token !== expected)
-        throw new OverrideUnavailable("override token mismatch");
+    return verdicts;
 }
-export async function guardOverride(resourceId, fromState, toState, overrideToken, rationale, resolvedBy = "human") {
-    _checkOverrideToken(overrideToken);
+function firePolicyEvent(event) {
+    void emitPolicyEvent(event).catch((error) => {
+        console.warn(`policy event ${event.event_id} delivery failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+}
+function guardEventRunId(runId, resourceId) {
+    if (runId !== undefined)
+        return runId;
+    if (!warnedGuardRunIdFallback) {
+        warnedGuardRunIdFallback = true;
+        console.warn("WARNING: guard events are using resource_id as run_id; pass run_id to preserve flow correlation");
+    }
+    return resourceId;
+}
+/**
+ * The resource's current ledger head, or `""` for an untouched resource. Signed
+ * into every one-shot authorization so it is valid at exactly one point in this
+ * resource's history and cannot be replayed afterwards.
+ */
+export function _ledgerHead(resourceId) {
+    const ledger = readLedger(resourceId);
+    return ledger.length === 0 ? "" : ledger[ledger.length - 1].entry_digest;
+}
+export async function guardOverride(resourceId, fromState, toState, authorization, rationale, resolvedBy = "human", userId, runId) {
     if (resolvedBy !== "human")
         throw new OverrideUnavailable("override requires resolved_by='human'");
     if (!rationale || !rationale.trim())
@@ -405,10 +564,20 @@ export async function guardOverride(resourceId, fromState, toState, overrideToke
         const registry = loadRegistry(resourceId);
         if (registry === null)
             throw new GuardNotFound(`no guard registered for ${JSON.stringify(resourceId)}`);
+        // Inside the lock: the ledger head must be the one this call will append to,
+        // so a concurrent mutation invalidates the authorization rather than letting
+        // it apply to a history the operator did not sign for.
+        const authorizedBy = verifyAuthorization("override", {
+            resource_id: resourceId,
+            from_state: fromState,
+            to_state: toState,
+            rationale,
+            ledger_head: _ledgerHead(resourceId),
+        }, authorization);
         if (fromState !== registry.current_state) {
             throw new StaleFromState(`from_state ${JSON.stringify(fromState)} != current_state ${JSON.stringify(registry.current_state)}`);
         }
-        if (!(registry.graph[fromState] ?? []).includes(toState)) {
+        if (!_declaresEdge(registry.graph, fromState, toState)) {
             throw new IllegalEdge(`${_edgeKey(fromState, toState)} is not a legal edge (override bypasses predicates, not the graph)`);
         }
         const entry = new LedgerEntry({
@@ -418,17 +587,36 @@ export async function guardOverride(resourceId, fromState, toState, overrideToke
             outcome: "deviation",
             kind: "deviation",
             resolved_by: resolvedBy,
-            rationale,
+            payload_digest: _payloadDigest(fromState, toState, {}, [], resolvedBy, registry.checksum),
+            rationale: `authorized by ${authorizedBy.principal} (${authorizedBy.fingerprint}): ${rationale}`,
         });
         await fenceResourceLock(resourceId, token);
         const ledgerRef = appendLedger(resourceId, entry);
         registry.current_state = toState;
         persistRegistry(registry);
-        return { status: "deviation", ledger_ref: ledgerRef, current_state: registry.current_state, rationale };
+        if (registry.bundle_id !== undefined) {
+            if (userId === undefined) {
+                console.warn("WARNING: guard deviation has no user_id; SmartMemory will reject the enforcement event");
+            }
+            firePolicyEvent(buildGuardTransitionEvent({
+                runId: guardEventRunId(runId, resourceId),
+                bundleId: registry.bundle_id,
+                resourceId,
+                entry,
+                rulesEvaluated: [],
+                ...(userId !== undefined ? { resolvedByUserId: userId } : {}),
+            }));
+        }
+        return {
+            status: "deviation", ledger_ref: ledgerRef, current_state: registry.current_state, rationale,
+            authorized_by: `${authorizedBy.principal} (${authorizedBy.fingerprint})`,
+            entry_digest: entry.entry_digest,
+            prev_digest: entry.prev_digest,
+            payload_digest: entry.payload_digest ?? "",
+        };
     });
 }
-export async function guardMigrate(resourceId, newGraph, newEdgePredicates, overrideToken, rationale, newTerminal = [], newStakes = {}) {
-    _checkOverrideToken(overrideToken);
+export async function guardMigrate(resourceId, newGraph, newEdgePredicates, authorization, rationale, newTerminal = [], newStakes = {}) {
     if (!rationale || !rationale.trim())
         throw new OverrideUnavailable("migrate requires a non-empty rationale");
     return acquireResourceLock(resourceId, async ({ token }) => {
@@ -436,6 +624,14 @@ export async function guardMigrate(resourceId, newGraph, newEdgePredicates, over
         const registry = loadRegistry(resourceId);
         if (registry === null)
             throw new GuardNotFound(`no guard registered for ${JSON.stringify(resourceId)}`);
+        // The authorization names the RESULTING policy, so a signature for one
+        // migration cannot be spent on a different one.
+        const authorizedBy = verifyAuthorization("migrate", {
+            resource_id: resourceId,
+            policy_checksum: guardChecksum(newGraph, newEdgePredicates, newTerminal, newStakes),
+            rationale,
+            ledger_head: _ledgerHead(resourceId),
+        }, authorization);
         _validatePolicy(newGraph, newEdgePredicates, registry.initial, newTerminal, newStakes, registry.workspace_root);
         if (!Object.hasOwn(newGraph, registry.current_state) && !newTerminal.includes(registry.current_state)) {
             throw new InvalidStateName(`current_state ${JSON.stringify(registry.current_state)} is not a node in the new graph`);
@@ -449,6 +645,190 @@ export async function guardMigrate(resourceId, newGraph, newEdgePredicates, over
             outcome: "graph_version",
             kind: "graph_version",
             resolved_by: "human",
+            rationale: `authorized by ${authorizedBy.principal} (${authorizedBy.fingerprint}): ${rationale}`,
+        });
+        await fenceResourceLock(resourceId, token);
+        const ledgerRef = appendLedger(resourceId, entry);
+        registry.graph = newGraph;
+        registry.edge_predicates = newEdgePredicates;
+        registry.terminal = newTerminal;
+        registry.stakes = newStakes;
+        registry.checksum = checksum;
+        registry.graph_version = graphVersion;
+        persistRegistry(registry);
+        return {
+            status: "migrated", checksum, graph_version: graphVersion, ledger_ref: ledgerRef, rationale,
+            authorized_by: `${authorizedBy.principal} (${authorizedBy.fingerprint})`,
+        };
+    });
+}
+/**
+ * Edge legality, robust to a malformed stored adjacency. `_validatePolicy`
+ * rejects a non-array adjacency on the way in, but registries are long-lived
+ * and load through unchecked casts, so one written before that check exists
+ * must still fail closed here: `["b"].includes("x")` is membership, but
+ * `"bxyz".includes("xyz")` is a SUBSTRING match and would legalize an
+ * undeclared, unguarded state.
+ */
+function _declaresEdge(graph, fromState, toState) {
+    const targets = graph[fromState];
+    return Array.isArray(targets) && targets.includes(toState);
+}
+function _graphEdgeKeys(graph) {
+    const keys = new Set();
+    for (const [fromState, targets] of Object.entries(graph)) {
+        for (const toState of targets)
+            keys.add(_edgeKey(fromState, toState));
+    }
+    return keys;
+}
+function _policyNodes(graph, terminal, initial) {
+    const names = new Set([...Object.keys(graph), ...terminal, initial]);
+    for (const targets of Object.values(graph))
+        for (const target of targets)
+            names.add(target);
+    return names;
+}
+/**
+ * Every way the submitted policy is NOT an additive-only extension of the
+ * stored one, as human-readable reasons (empty = compatible).
+ *
+ * Deliberately stricter than strictly necessary, because this classifier is
+ * the only thing standing between a token-free call and a policy change:
+ * existing edges must be byte-identical (even ADDING a predicate to one is
+ * refused — "strengthening" is an ordering this code declines to reason
+ * about), and `terminal` is frozen in both directions — no state may be added
+ * to it or removed from it, and no new edge may enter OR leave a terminal
+ * state. Anything it refuses remains reachable through `guardMigrate` with the
+ * override token.
+ */
+export function _upgradeIncompatibilities(registry, newGraph, newEdgePredicates, newTerminal, newStakes) {
+    const reasons = [];
+    for (const [fromState, targets] of Object.entries(registry.graph)) {
+        if (!Object.hasOwn(newGraph, fromState)) {
+            reasons.push(`node ${JSON.stringify(fromState)} is missing from the new graph`);
+            continue;
+        }
+        const newTargets = new Set(newGraph[fromState] ?? []);
+        for (const toState of targets) {
+            if (!newTargets.has(toState))
+                reasons.push(`edge ${_edgeKey(fromState, toState)} was removed`);
+        }
+    }
+    // Keys of the OLD policy only: predicates/stakes on brand-new edges are the
+    // point of an upgrade, while any pre-existing key must survive untouched —
+    // including "absent stays absent", so a new entry on an old edge is refused.
+    const existingKeys = new Set([
+        ..._graphEdgeKeys(registry.graph),
+        ...Object.keys(registry.edge_predicates),
+        ...Object.keys(registry.stakes),
+    ]);
+    // Own-property reads only: a caller-supplied object still inherits
+    // Object.prototype, so `newEdgePredicates["constructor"]` would otherwise
+    // resolve to an inherited value instead of "absent".
+    const own = (source, key) => (Object.hasOwn(source, key) ? source[key] : null);
+    for (const key of existingKeys) {
+        if (canonicalJson(own(registry.edge_predicates, key)) !== canonicalJson(own(newEdgePredicates, key))) {
+            reasons.push(`predicates changed on existing edge ${key}`);
+        }
+        if (own(registry.stakes, key) !== own(newStakes, key)) {
+            reasons.push(`stakes changed on existing edge ${key}`);
+        }
+    }
+    // Additive-only does NOT mean harmless: an added edge that lands on a state
+    // the old policy already had is a new ROUTE to it, and routes around the
+    // predicates on the old route. `draft -> shipped` guarded by evidence is
+    // worthless if a token-free call can add `draft -> rubber_stamp -> shipped`.
+    // So new edges may only terminate at states that did not exist before —
+    // which keeps the reachability of every pre-existing state exactly as
+    // registered, and still allows grafting a new subgraph (the requesting case).
+    const oldEdges = _graphEdgeKeys(registry.graph);
+    const oldNodes = _policyNodes(registry.graph, registry.terminal, registry.initial);
+    const oldTerminal = new Set(registry.terminal);
+    for (const [fromState, targets] of Object.entries(newGraph)) {
+        for (const toState of targets) {
+            if (oldEdges.has(_edgeKey(fromState, toState)))
+                continue;
+            if (oldNodes.has(toState)) {
+                reasons.push(`new edge ${_edgeKey(fromState, toState)} adds a route into pre-existing state ${JSON.stringify(toState)}`);
+            }
+            // Terminal EGRESS, not just membership. Freezing the terminal set stops a
+            // caller inventing a new way to be done; it does not stop `shipped ->
+            // reopened` with a brand-new `reopened`, which walks a completed resource
+            // back OUT of its terminal state — token-free, over an edge whose
+            // predicates the caller also chose. A terminal state has no outgoing
+            // edges by contract, so growing one is a policy change either way.
+            if (oldTerminal.has(fromState)) {
+                reasons.push(`new edge ${_edgeKey(fromState, toState)} leaves terminal state ${JSON.stringify(fromState)}`);
+            }
+        }
+    }
+    // `terminal` is frozen — not "grows only with new nodes". Stratum never reads
+    // it for edge legality, but consumers read it as COMPLETABILITY, so adding a
+    // terminal state is granting a new way to be done. A token-free caller who
+    // could add one would simply declare its own success state, reach it over a
+    // new edge whose predicates it also chose (an empty predicate list evaluates
+    // as met), and be complete without passing any gate that existed at
+    // registration. Rule 4 does not help there: the bypass never touches an old
+    // state. Granting completability is an authorization decision, so it stays
+    // on the token-gated `guardMigrate`.
+    const newTerminalSet = new Set(newTerminal);
+    for (const name of oldTerminal) {
+        if (!newTerminalSet.has(name))
+            reasons.push(`terminal state ${JSON.stringify(name)} was removed`);
+    }
+    for (const name of newTerminalSet) {
+        if (!oldTerminal.has(name))
+            reasons.push(`terminal state ${JSON.stringify(name)} was added`);
+    }
+    return reasons;
+}
+/**
+ * Routine, token-free policy upgrade: idempotent on an identical policy and
+ * additive-only otherwise. The complement of `guardMigrate`, which keeps the
+ * override token for everything this refuses. See
+ * `docs/features/STRAT-GUARD-UPGRADE/design.md`.
+ */
+export async function guardUpgrade(resourceId, newGraph, newEdgePredicates, rationale, newTerminal = [], newStakes = {}) {
+    if (!rationale || !rationale.trim())
+        throw new OverrideUnavailable("upgrade requires a non-empty rationale");
+    return acquireResourceLock(resourceId, async ({ token }) => {
+        assertTsOwnedForMutation(resourceId);
+        const registry = loadRegistry(resourceId);
+        if (registry === null)
+            throw new GuardNotFound(`no guard registered for ${JSON.stringify(resourceId)}`);
+        // Before ANY comparison: a tampered registry whose stored checksum happened
+        // to match the submitted policy would otherwise return "unchanged" and
+        // silently bless the tampering.
+        if (guardChecksum(registry.graph, registry.edge_predicates, registry.terminal, registry.stakes) !== registry.checksum) {
+            throw new GuardTampered(`guard ${JSON.stringify(resourceId)} policy checksum mismatch`);
+        }
+        _validatePolicy(newGraph, newEdgePredicates, registry.initial, newTerminal, newStakes, registry.workspace_root);
+        const checksum = guardChecksum(newGraph, newEdgePredicates, newTerminal, newStakes);
+        if (checksum === registry.checksum) {
+            // No ledger entry and no version bump: compose re-runs this per resource
+            // on every cold-server touch, and the steady state must write nothing.
+            return { status: "unchanged", checksum, graph_version: registry.graph_version, rationale };
+        }
+        const reasons = _upgradeIncompatibilities(registry, newGraph, newEdgePredicates, newTerminal, newStakes);
+        if (reasons.length > 0) {
+            throw new IncompatiblePolicyUpgrade(`policy upgrade is not additive-only (${reasons.join("; ")}); use a signed upgrade descriptor, or guard migrate with a signed authorization`);
+        }
+        // Unreachable under an additive-only policy (old nodes all survive), kept
+        // as defence in depth against a classifier gap.
+        if (!Object.hasOwn(newGraph, registry.current_state) && !newTerminal.includes(registry.current_state)) {
+            throw new InvalidStateName(`current_state ${JSON.stringify(registry.current_state)} is not a node in the new graph`);
+        }
+        const graphVersion = registry.graph_version + 1;
+        const entry = new LedgerEntry({
+            ts_ms: _nowMs(),
+            from_state: registry.current_state,
+            to_state: registry.current_state,
+            outcome: "graph_version",
+            kind: "graph_version",
+            // The one ledger-visible difference from guardMigrate, which writes
+            // "human": that call means a person held the override token.
+            resolved_by: "agent",
             rationale,
         });
         await fenceResourceLock(resourceId, token);
@@ -463,6 +843,77 @@ export async function guardMigrate(resourceId, newGraph, newEdgePredicates, over
         return { status: "migrated", checksum, graph_version: graphVersion, ledger_ref: ledgerRef, rationale };
     });
 }
+/**
+ * Apply a server-owned, digest-pinned, human-reviewed upgrade descriptor.
+ *
+ * The middle of the three policy-change capabilities. `guardUpgrade` needs no
+ * authorization because it is provably non-weakening; `guardMigrate` needs the
+ * break-glass token because it can do anything. This path can do anything the
+ * descriptor spells out — including granting a terminal state, which
+ * `guardUpgrade` refuses precisely because it is a completability grant — and it
+ * is safe because a human read that exact resulting policy before installing it
+ * and pinned the file's digest into the server environment.
+ *
+ * No additive-only classifier runs here, deliberately. See
+ * `docs/features/STRAT-GUARD-DESCRIPTOR/design.md`.
+ */
+export async function guardApplyUpgrade(resourceId, descriptorId, env = process.env) {
+    // Authorization first, outside the lock: a caller with no descriptor set
+    // configured must not even be able to probe which resources exist.
+    const descriptorFile = loadDescriptorFile(env);
+    const descriptor = findDescriptor(descriptorFile, descriptorId);
+    const { graph, edge_predicates: edgePredicates, terminal, stakes } = descriptor.to_policy;
+    return acquireResourceLock(resourceId, async ({ token }) => {
+        assertTsOwnedForMutation(resourceId);
+        const registry = loadRegistry(resourceId);
+        if (registry === null)
+            throw new GuardNotFound(`no guard registered for ${JSON.stringify(resourceId)}`);
+        if (guardChecksum(registry.graph, registry.edge_predicates, registry.terminal, registry.stakes) !== registry.checksum) {
+            throw new GuardTampered(`guard ${JSON.stringify(resourceId)} policy checksum mismatch`);
+        }
+        const checksum = guardChecksum(graph, edgePredicates, terminal, stakes);
+        // Destination check BEFORE the from_checksum check: a resource already at the
+        // target is a success, not a mismatch. That is what makes a fleet batch
+        // re-runnable after a partial failure.
+        if (checksum === registry.checksum) {
+            return { status: "unchanged", checksum, graph_version: registry.graph_version, descriptor_id: descriptor.id };
+        }
+        if (registry.checksum !== descriptor.from_checksum) {
+            throw new UpgradeDescriptorMismatch(`descriptor ${JSON.stringify(descriptor.id)} is authorized for policy ${descriptor.from_checksum}, `
+                + `but ${JSON.stringify(resourceId)} currently holds ${registry.checksum}`);
+        }
+        // Authorized is not the same as well-formed.
+        _validatePolicy(graph, edgePredicates, registry.initial, terminal, stakes, registry.workspace_root);
+        if (!Object.hasOwn(graph, registry.current_state) && !terminal.includes(registry.current_state)) {
+            throw new InvalidStateName(`current_state ${JSON.stringify(registry.current_state)} is not a node in the new graph`);
+        }
+        const graphVersion = registry.graph_version + 1;
+        const entry = new LedgerEntry({
+            ts_ms: _nowMs(),
+            from_state: registry.current_state,
+            to_state: registry.current_state,
+            outcome: "graph_version",
+            kind: "graph_version",
+            // A human authorized this exact policy, so the ledger says so — and names
+            // which authorization, pinned by the descriptor file's digest.
+            resolved_by: "human",
+            // Names WHO authorized it and WHICH artifact, from the file verified
+            // ABOVE — a re-read could name a digest other than the one authorized.
+            rationale: `descriptor ${descriptor.id} signed by ${descriptorFile.signedBy.principal} `
+                + `(${descriptorFile.signedBy.fingerprint}, file sha256 ${descriptorFile.digest}): ${descriptor.rationale}`,
+        });
+        await fenceResourceLock(resourceId, token);
+        const ledgerRef = appendLedger(resourceId, entry);
+        registry.graph = graph;
+        registry.edge_predicates = edgePredicates;
+        registry.terminal = terminal;
+        registry.stakes = stakes;
+        registry.checksum = checksum;
+        registry.graph_version = graphVersion;
+        persistRegistry(registry);
+        return { status: "applied", checksum, graph_version: graphVersion, ledger_ref: ledgerRef, descriptor_id: descriptor.id };
+    });
+}
 export function guardHistory(resourceId) {
     const registry = loadRegistry(resourceId);
     if (registry === null)