@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/heart/steward-policy.js

@@ -0,0 +1,618 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readStewardPolicy = readStewardPolicy;
+exports.updateStewardPolicy = updateStewardPolicy;
+exports.readRoutineActionReceipts = readRoutineActionReceipts;
+exports.inspectRoutineActionGrant = inspectRoutineActionGrant;
+exports.consumeRoutineActionGrant = consumeRoutineActionGrant;
+exports.withStewardPolicyLease = withStewardPolicyLease;
+exports.withRoutineActionAttempt = withRoutineActionAttempt;
+exports.transitionRoutineActionReceipt = transitionRoutineActionReceipt;
+exports.recoverRoutineActionReceipts = recoverRoutineActionReceipts;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_util_1 = require("node:util");
+const runtime_1 = require("../nerves/runtime");
+const session_transaction_1 = require("../mind/session-transaction");
+const EMPTY_POLICY = { schemaVersion: 1, version: 0, desiredStates: {}, routineActionGrants: {}, updatedAt: null };
+const MAX_POLICY_BYTES = 1024 * 1024;
+const MAX_AUDIT_ROW_BYTES = 16 * MAX_POLICY_BYTES;
+function sha256(bytes) {
+    return (0, node_crypto_1.createHash)("sha256").update(bytes, "utf8").digest("hex");
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactKeys(value, required, optional = []) {
+    return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+function canonicalTime(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
+}
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function textArray(value) {
+    return Array.isArray(value) && value.every(text) && new Set(value).size === value.length;
+}
+function ownerAuthorization(value) {
+    return record(value) && exactKeys(value, ["profileId", "profileVersion", "requestId", "sessionKey", "receiptId"])
+        && value.profileId === "sanctuary-owner" && positiveInteger(value.profileVersion)
+        && text(value.requestId) && text(value.sessionKey) && text(value.receiptId);
+}
+function desiredEntry(value, version) {
+    return record(value) && exactKeys(value, ["value", "provenance", "version", "source"], ["expiresAt"])
+        && text(value.value) && text(value.source) && positiveInteger(value.version) && value.version <= version
+        && (value.provenance === "stated" || value.provenance === "observed" || value.provenance === "default")
+        && (value.expiresAt === undefined || canonicalTime(value.expiresAt));
+}
+function grantEntry(value, version) {
+    return record(value) && exactKeys(value, ["action", "targets", "maxCount", "windowMs", "verificationRequired", "exclusions", "provenance", "issuer", "authorizedAt", "authorizingSessionEvent", "version"], ["expiresAt"])
+        && text(value.action) && textArray(value.targets) && value.targets.length > 0 && textArray(value.exclusions)
+        && positiveInteger(value.maxCount) && positiveInteger(value.windowMs) && value.verificationRequired === true
+        && (value.provenance === "stated" || value.provenance === "installed_explicit_policy")
+        && text(value.issuer) && text(value.authorizingSessionEvent) && canonicalTime(value.authorizedAt)
+        && positiveInteger(value.version) && value.version <= version && (value.expiresAt === undefined || canonicalTime(value.expiresAt));
+}
+function policyRecord(value) {
+    if (!record(value) || !exactKeys(value, ["schemaVersion", "version", "desiredStates", "routineActionGrants", "updatedAt"])
+        || value.schemaVersion !== 1 || typeof value.version !== "number" || !Number.isSafeInteger(value.version) || value.version < 0
+        || !record(value.desiredStates) || !record(value.routineActionGrants)
+        || !(value.updatedAt === null ? value.version === 0 : canonicalTime(value.updatedAt)))
+        return false;
+    const version = value.version;
+    return Object.entries(value.desiredStates).every(([key, entry]) => text(key) && desiredEntry(entry, version))
+        && Object.entries(value.routineActionGrants).every(([key, entry]) => text(key) && grantEntry(entry, version));
+}
+function policyImage(bytes) {
+    if (Buffer.byteLength(bytes) > MAX_POLICY_BYTES)
+        throw new Error("steward policy audit image exceeds its bound");
+    if (bytes === "")
+        return structuredClone(EMPTY_POLICY);
+    let value;
+    try {
+        value = JSON.parse(bytes);
+    }
+    catch (cause) {
+        throw new Error("steward policy audit image is invalid", { cause });
+    }
+    if (!policyRecord(value))
+        throw new Error("steward policy audit image is invalid");
+    return value;
+}
+function mutationFingerprint(kind, key, result) {
+    const generated = ["version", "issuer", "authorizedAt", "authorizingSessionEvent"];
+    const input = Object.fromEntries(Object.entries(result).filter(([field]) => !generated.includes(field)).sort(([left], [right]) => left.localeCompare(right)));
+    return sha256(JSON.stringify([kind, key, input]));
+}
+function operationIdentity(issuer, event, requestId, kind, key) {
+    return JSON.stringify([issuer, event, requestId, kind, key]);
+}
+function auditRow(value) {
+    if (!record(value) || !exactKeys(value, ["schemaVersion", "transactionId", "precedingBytesSha256", "mutationKind", "key", "mutationFingerprint", "affectedKeyResult", "affectedKeyResultSha256", "issuer", "authorizingSessionEvent", "authorization", "preimage", "preimageVersion", "preimageSha256", "postimage", "postimageVersion", "postimageSha256", "at"])
+        || value.schemaVersion !== 2 || (value.mutationKind !== "set_desired_state" && value.mutationKind !== "grant_routine_action")
+        || !text(value.key) || !text(value.issuer) || !text(value.authorizingSessionEvent) || !ownerAuthorization(value.authorization)
+        || typeof value.preimage !== "string" || typeof value.postimage !== "string" || !canonicalTime(value.at))
+        return false;
+    const before = policyImage(value.preimage);
+    const after = policyImage(value.postimage);
+    const result = value.mutationKind === "set_desired_state" ? after.desiredStates[value.key] : after.routineActionGrants[value.key];
+    if (!result || value.preimageVersion !== before.version || value.postimageVersion !== after.version
+        || after.version !== before.version + 1 || result.version !== after.version || after.updatedAt !== value.at
+        || value.preimageSha256 !== sha256(value.preimage) || value.postimageSha256 !== sha256(value.postimage)
+        || value.postimage !== JSON.stringify(after, null, 2) || !(0, node_util_1.isDeepStrictEqual)(value.affectedKeyResult, result)
+        || value.affectedKeyResultSha256 !== sha256(JSON.stringify(result))
+        || value.mutationFingerprint !== mutationFingerprint(value.mutationKind, value.key, result)
+        || value.transactionId !== sha256(JSON.stringify([operationIdentity(value.issuer, value.authorizingSessionEvent, value.authorization.requestId, value.mutationKind, value.key), value.mutationFingerprint])))
+        return false;
+    if ("action" in result && (result.issuer !== value.issuer || result.authorizingSessionEvent !== value.authorizingSessionEvent || result.authorizedAt !== value.at))
+        return false;
+    const expected = {
+        ...before, version: after.version, updatedAt: value.at,
+        desiredStates: value.mutationKind === "set_desired_state" ? { ...before.desiredStates, [value.key]: result } : before.desiredStates,
+        routineActionGrants: value.mutationKind === "grant_routine_action" ? { ...before.routineActionGrants, [value.key]: result } : before.routineActionGrants,
+    };
+    return (0, node_util_1.isDeepStrictEqual)(after, expected);
+}
+function policyDir(agentRoot) {
+    return path.join(agentRoot, "state", "policy");
+}
+function policyPath(agentRoot) {
+    return path.join(policyDir(agentRoot), "steward.json");
+}
+function receiptsPath(agentRoot) {
+    return path.join(policyDir(agentRoot), "action-receipts.ndjson");
+}
+function auditPath(agentRoot) {
+    return path.join(policyDir(agentRoot), "policy-audit.ndjson");
+}
+function ensureDirectory(agentRoot) {
+    fs.mkdirSync(policyDir(agentRoot), { recursive: true, mode: 0o700 });
+    fs.chmodSync(policyDir(agentRoot), 0o700);
+}
+function syncParentDirectory(filePath) {
+    const directory = fs.openSync(path.dirname(filePath), fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+}
+function appendReceipt(filePath, value) {
+    const creating = !fs.existsSync(filePath);
+    const fd = fs.openSync(filePath, "a", 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.chmodSync(filePath, 0o600);
+    if (creating)
+        syncParentDirectory(filePath);
+}
+function requireText(value, label) {
+    const result = typeof value === "string" ? value.trim() : "";
+    if (!result)
+        throw new Error(`${label} must be nonempty`);
+    return result;
+}
+function optionalExpiry(value, now) {
+    if (!value)
+        return undefined;
+    const epoch = Date.parse(value);
+    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== value || (now !== undefined && epoch <= Date.parse(now)))
+        throw new Error("policy expiry must be a future canonical timestamp");
+    return value;
+}
+function validateStewardPolicy(value) {
+    if (!policyRecord(value))
+        throw new Error("steward policy is invalid");
+    return value;
+}
+function readAuditBytes(agentRoot) {
+    try {
+        const bytes = fs.readFileSync(auditPath(agentRoot));
+        const decoded = bytes.toString("utf8");
+        if (!Buffer.from(decoded, "utf8").equals(bytes))
+            throw new Error("steward policy audit encoding is invalid");
+        return decoded;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+}
+function readPolicyTransaction(filePath, lease) {
+    const exists = fs.existsSync(filePath);
+    if (exists && fs.statSync(filePath).size > MAX_POLICY_BYTES)
+        throw new Error("steward policy exceeds its bound");
+    const snapshot = (0, session_transaction_1.readSessionTransaction)(filePath, lease);
+    const raw = exists ? fs.readFileSync(filePath) : Buffer.alloc(0);
+    if (!Buffer.from(snapshot.bytes, "utf8").equals(raw))
+        throw new Error("steward policy encoding or bytes changed");
+    return { ...snapshot, exists };
+}
+function readAuditedPolicy(agentRoot, lease) {
+    const filePath = policyPath(agentRoot);
+    let snapshot = readPolicyTransaction(filePath, lease);
+    let policy = !snapshot.exists && snapshot.bytes === "" ? structuredClone(EMPTY_POLICY) : validateStewardPolicy(snapshot.value);
+    const auditBytes = readAuditBytes(agentRoot);
+    const rows = [];
+    const seen = new Set();
+    const preceding = (0, node_crypto_1.createHash)("sha256");
+    let legacyVersion = 0;
+    if (auditBytes && !auditBytes.endsWith("\n"))
+        throw new Error("steward policy audit has a partial final row");
+    for (const line of auditBytes ? auditBytes.slice(0, -1).split("\n") : []) {
+        if (Buffer.byteLength(line) > MAX_AUDIT_ROW_BYTES)
+            throw new Error("steward policy audit row exceeds its bound");
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch (cause) {
+            throw new Error("steward policy audit row is invalid", { cause });
+        }
+        if (record(row) && row.schemaVersion === 1) {
+            if (rows.length || !positiveInteger(row.policyVersion) || row.policyVersion <= legacyVersion)
+                throw new Error("steward policy audit legacy prefix is invalid");
+            legacyVersion = row.policyVersion;
+        }
+        else {
+            if (!auditRow(row) || row.precedingBytesSha256 !== preceding.copy().digest("hex"))
+                throw new Error("steward policy audit row is invalid");
+            const prior = rows.at(-1);
+            if (prior ? row.preimage !== prior.postimage || row.preimageVersion !== prior.postimageVersion : row.preimageVersion !== legacyVersion)
+                throw new Error("steward policy audit chain is invalid");
+            const identity = operationIdentity(row.issuer, row.authorizingSessionEvent, row.authorization.requestId, row.mutationKind, row.key);
+            if (seen.has(identity))
+                throw new Error("steward policy audit contains a duplicate transaction");
+            seen.add(identity);
+            rows.push(row);
+        }
+        preceding.update(`${line}\n`, "utf8");
+    }
+    const last = rows.at(-1);
+    if (!last) {
+        if (policy.version !== legacyVersion)
+            throw new Error("steward policy audit does not match the policy head");
+    }
+    else if (snapshot.bytes !== last.postimage) {
+        if (snapshot.bytes !== last.preimage)
+            throw new Error("steward policy audit does not match the policy head");
+        const fd = fs.openSync(auditPath(agentRoot), "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        syncParentDirectory(auditPath(agentRoot));
+        (0, session_transaction_1.writeSessionTransaction)(filePath, policyImage(last.postimage), { lease, expectedRevision: snapshot.revision });
+        snapshot = readPolicyTransaction(filePath, lease);
+        if (snapshot.bytes !== last.postimage)
+            throw new Error("steward policy audit recovery readback differs");
+        policy = validateStewardPolicy(snapshot.value);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.steward_policy_recovered", message: "recovered an authorized steward policy write", meta: { version: policy.version } });
+    }
+    return { ...snapshot, policy, rows, auditBytes };
+}
+function readPolicyState(agentRoot) {
+    if (!fs.existsSync(policyPath(agentRoot)) && !fs.existsSync(auditPath(agentRoot))) {
+        return { policy: structuredClone(EMPTY_POLICY), rows: [] };
+    }
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), (lease) => readAuditedPolicy(agentRoot, lease));
+}
+function readStewardPolicy(agentRoot) {
+    return readPolicyState(agentRoot).policy;
+}
+function updateStewardPolicy(agentRoot, input) {
+    if (input.actor.trustLevel !== "family")
+        throw new Error("steward policy mutation requires family authority");
+    const authorizingSessionEvent = requireText(input.actor.sessionEventId, "authorizing session event");
+    const issuer = requireText(input.actor.friendId, "issuer");
+    const authorization = input.actor.authorization;
+    if (!ownerAuthorization(authorization))
+        throw new Error("steward policy mutation requires current owner authorization");
+    if (input.mutation.kind !== "set_desired_state" && input.mutation.kind !== "grant_routine_action")
+        throw new Error("steward policy mutation kind is invalid");
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), (lease) => {
+        const snapshot = readAuditedPolicy(agentRoot, lease);
+        const current = snapshot.policy;
+        const now = input.now ?? new Date().toISOString();
+        if (!canonicalTime(now))
+            throw new Error("policy update time must be canonical");
+        const expiresAt = optionalExpiry(input.mutation.expiresAt);
+        const version = current.version + 1;
+        if (!positiveInteger(version))
+            throw new Error("steward policy version is exhausted");
+        const next = { ...current, version, desiredStates: { ...current.desiredStates }, routineActionGrants: { ...current.routineActionGrants }, updatedAt: now };
+        const key = requireText(input.mutation.key, input.mutation.kind === "set_desired_state" ? "desired state key" : "routine action key");
+        let affectedKeyResult;
+        if (input.mutation.kind === "set_desired_state") {
+            if (input.mutation.provenance !== "stated" && input.mutation.provenance !== "observed" && input.mutation.provenance !== "default")
+                throw new Error("desired state provenance is invalid");
+            affectedKeyResult = {
+                value: requireText(input.mutation.value, "desired state value"),
+                provenance: input.mutation.provenance,
+                version,
+                source: requireText(input.mutation.source, "desired state source"),
+                ...(expiresAt ? { expiresAt } : {}),
+            };
+            next.desiredStates = { ...current.desiredStates, [key]: affectedKeyResult };
+        }
+        else {
+            if (input.mutation.provenance !== "stated" && input.mutation.provenance !== "installed_explicit_policy")
+                throw new Error("routine action grants require explicit authority");
+            if (!positiveInteger(input.mutation.maxCount) || !positiveInteger(input.mutation.windowMs))
+                throw new Error("routine action grant bounds are invalid");
+            if (input.mutation.verificationRequired !== true)
+                throw new Error("routine action grants require post-action verification");
+            if (!Array.isArray(input.mutation.targets) || !Array.isArray(input.mutation.exclusions))
+                throw new Error("routine action targets and exclusions must be arrays");
+            const targets = [...new Set(input.mutation.targets.map((value) => requireText(value, "routine action target")))].sort();
+            if (targets.length === 0)
+                throw new Error("routine action grant requires a target");
+            affectedKeyResult = {
+                action: requireText(input.mutation.action, "routine action"), targets, maxCount: input.mutation.maxCount, windowMs: input.mutation.windowMs,
+                verificationRequired: input.mutation.verificationRequired, exclusions: [...new Set(input.mutation.exclusions.map((value) => requireText(value, "routine action exclusion")))].sort(), provenance: input.mutation.provenance,
+                issuer, authorizedAt: now, authorizingSessionEvent, version, ...(expiresAt ? { expiresAt } : {}),
+            };
+            next.routineActionGrants = { ...current.routineActionGrants, [key]: affectedKeyResult };
+        }
+        const fingerprint = mutationFingerprint(input.mutation.kind, key, affectedKeyResult);
+        const identity = operationIdentity(issuer, authorizingSessionEvent, authorization.requestId, input.mutation.kind, key);
+        const previousIndex = snapshot.rows.findIndex((row) => operationIdentity(row.issuer, row.authorizingSessionEvent, row.authorization.requestId, row.mutationKind, row.key) === identity);
+        if (previousIndex >= 0) {
+            const previous = snapshot.rows[previousIndex];
+            const currentResult = previous.mutationKind === "set_desired_state" ? current.desiredStates[key] : current.routineActionGrants[key];
+            if (previous.mutationFingerprint !== fingerprint || snapshot.rows.slice(previousIndex + 1).some((row) => row.mutationKind === previous.mutationKind && row.key === key)
+                || !(0, node_util_1.isDeepStrictEqual)(currentResult, previous.affectedKeyResult))
+                throw new Error("steward policy transaction replay changed");
+            return current;
+        }
+        if (current.version !== input.expectedVersion)
+            throw new Error(`steward policy version changed: expected ${input.expectedVersion}, got ${current.version}`);
+        optionalExpiry(expiresAt, now);
+        const postimage = JSON.stringify(next, null, 2);
+        if (Buffer.byteLength(postimage) > MAX_POLICY_BYTES)
+            throw new Error("steward policy exceeds its bound");
+        const row = {
+            schemaVersion: 2, transactionId: sha256(JSON.stringify([identity, fingerprint])), precedingBytesSha256: sha256(snapshot.auditBytes),
+            mutationKind: input.mutation.kind, key, mutationFingerprint: fingerprint, affectedKeyResult, affectedKeyResultSha256: sha256(JSON.stringify(affectedKeyResult)),
+            issuer, authorizingSessionEvent, authorization: { ...authorization },
+            preimage: snapshot.bytes, preimageVersion: current.version, preimageSha256: snapshot.revision,
+            postimage, postimageVersion: version, postimageSha256: sha256(postimage), at: now,
+        };
+        if (Buffer.byteLength(JSON.stringify(row)) > MAX_AUDIT_ROW_BYTES)
+            throw new Error("steward policy audit row exceeds its bound");
+        ensureDirectory(agentRoot);
+        appendReceipt(auditPath(agentRoot), row);
+        (0, session_transaction_1.writeSessionTransaction)(policyPath(agentRoot), next, { lease, expectedRevision: snapshot.revision });
+        if (readPolicyTransaction(policyPath(agentRoot), lease).bytes !== postimage)
+            throw new Error("steward policy publication readback differs");
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.steward_policy_updated", message: "updated steward policy", meta: { version, mutationKind: input.mutation.kind, issuer } });
+        return next;
+    });
+}
+function readActionReceiptHistory(agentRoot) {
+    const filePath = receiptsPath(agentRoot);
+    if (!fs.existsSync(filePath))
+        return [];
+    return fs.readFileSync(filePath, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+function readRoutineActionReceipts(agentRoot) {
+    const latest = new Map();
+    for (const receipt of readActionReceiptHistory(agentRoot))
+        latest.set(receipt.id, receipt);
+    return [...latest.values()];
+}
+function currentRequester(value, target) {
+    if (!record(value) || !text(value.friendId))
+        return false;
+    if (value.kind === "owner" || value.kind === "household_request") {
+        return exactKeys(value, ["kind", "friendId", "profileId", "requestId", "sessionEventId", "origin"])
+            && value.profileId === (value.kind === "owner" ? "sanctuary-owner" : "sanctuary-household")
+            && text(value.requestId) && text(value.sessionEventId) && record(value.origin)
+            && exactKeys(value.origin, ["friendId", "channel", "key"])
+            && value.origin.friendId === value.friendId && value.origin.channel === "telegram" && text(value.origin.key);
+    }
+    return value.kind === "owner_event" && exactKeys(value, ["kind", "friendId", "profileId", "event", "target"])
+        && value.profileId === "sanctuary-event" && record(value.target) && exactKeys(value.target, ["id", "name"])
+        && text(value.target.id) && value.target.name === target && record(value.event)
+        && exactKeys(value.event, ["schemaVersion", "recordPath", "agent", "source", "eventId", "generation", "observationRevision", "claimOwner"])
+        && value.event.schemaVersion === 1 && value.event.source === "sanctuary-health"
+        && value.event.eventId === `container:${value.target.id}:availability`
+        && text(value.event.recordPath) && text(value.event.agent) && positiveInteger(value.event.generation)
+        && text(value.event.observationRevision) && text(value.event.claimOwner);
+}
+function appliedEntry(rows, kind, key, entry) {
+    return rows.some((row) => row.mutationKind === kind && row.key === key && row.postimageVersion === entry.version && (0, node_util_1.isDeepStrictEqual)(row.affectedKeyResult, entry));
+}
+const UNRESOLVED_ACTION_STATES = new Set(["reserved", "attempting", "effect_acknowledged", "recovery_pending", "indeterminate"]);
+function inspectRoutineActionGrantSnapshot(policy, rows, receipts, input) {
+    const now = input.now === undefined ? new Date().toISOString() : input.now;
+    if (!canonicalTime(now))
+        return { allowed: false, reason: "routine action time must be canonical" };
+    if (!text(input.key) || !text(input.action) || !text(input.target))
+        return { allowed: false, reason: "routine action requires an exact key, action, and target" };
+    if (input.expectedPolicyVersion !== undefined && policy.version !== input.expectedPolicyVersion)
+        return { allowed: false, reason: "routine action policy version changed" };
+    if (!currentRequester(input.requester, input.target) || !positiveInteger(input.authorizationVersion))
+        return { allowed: false, reason: "routine action requires a current versioned requester" };
+    const desiredKey = `container:${input.target}`;
+    const desired = policy.desiredStates[desiredKey];
+    if (input.expectedDesiredStateVersion !== undefined && desired?.version !== input.expectedDesiredStateVersion)
+        return { allowed: false, reason: "routine action desired state version changed" };
+    const activeDesired = desired && (desired.expiresAt === undefined || Date.parse(desired.expiresAt) > Date.parse(now));
+    const desiredValue = desired?.value.toLowerCase();
+    if (activeDesired && /^(?:off|disabled|paused|intentionally_off|intentionally_paused)$/u.test(desiredValue))
+        return { allowed: false, reason: "container is expected off" };
+    const grant = policy.routineActionGrants[input.key];
+    if (input.expectedGrantVersion !== undefined && grant?.version !== input.expectedGrantVersion)
+        return { allowed: false, reason: "routine action grant version changed" };
+    const fallback = input.requester.kind === "owner" ? { approvalFallback: true } : {};
+    if (!grant)
+        return { allowed: false, reason: "routine action grant is missing", ...fallback };
+    if (grant.provenance !== "stated")
+        return { allowed: false, reason: "routine action grant must be owner-stated" };
+    if (!appliedEntry(rows, "grant_routine_action", input.key, grant))
+        return { allowed: false, reason: "routine action grant has no applied owner authorization" };
+    if (grant.action !== input.action)
+        return { allowed: false, reason: "routine action does not match the grant" };
+    if (!grant.targets.includes(input.target) || grant.exclusions.includes(input.target))
+        return { allowed: false, reason: "routine action target is not authorized" };
+    if (grant.expiresAt && Date.parse(grant.expiresAt) <= Date.parse(now))
+        return { allowed: false, reason: "routine action grant expired", ...fallback };
+    if (!activeDesired || desired.provenance !== "stated" || !appliedEntry(rows, "set_desired_state", desiredKey, desired))
+        return { allowed: false, reason: "container has no active applied owner-stated desired state" };
+    if (!["on", "always_on", "expected_on"].includes(desiredValue) && !(desiredValue === "on_demand" && input.requester.kind !== "owner_event"))
+        return { allowed: false, reason: "container desired state does not authorize this request" };
+    if (receipts.some((receipt) => receipt.action === input.action && receipt.target === input.target && UNRESOLVED_ACTION_STATES.has(receipt.state))) {
+        return { allowed: false, reason: "routine action has an unresolved receipt for this target" };
+    }
+    const windowStart = Date.parse(now) - grant.windowMs;
+    if (receipts.filter((receipt) => receipt.key === input.key && Date.parse(receipt.reservedAt) > windowStart).length >= grant.maxCount)
+        return { allowed: false, reason: "routine action rate limit reached" };
+    return { allowed: true, policyVersion: policy.version, desiredStateVersion: desired.version, grantVersion: grant.version, key: input.key, action: grant.action, target: input.target, requester: input.requester, authorizationVersion: input.authorizationVersion };
+}
+function inspectRoutineActionGrant(agentRoot, input) {
+    try {
+        const { policy, rows } = readPolicyState(agentRoot);
+        return inspectRoutineActionGrantSnapshot(policy, rows, readRoutineActionReceipts(agentRoot), input);
+    }
+    catch (error) {
+        return { allowed: false, reason: error instanceof Error ? error.message : "routine action policy is unavailable" };
+    }
+}
+function consumeRoutineActionGrant(agentRoot, input) {
+    if (!text(input.authorizationReceiptId))
+        throw new Error("routine action requires a current authorization receipt");
+    const authorizationReceiptId = input.authorizationReceiptId;
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), (lease) => {
+        const snapshot = readAuditedPolicy(agentRoot, lease);
+        const policy = snapshot.policy;
+        const grant = policy.routineActionGrants[input.key];
+        const now = input.now === undefined ? new Date().toISOString() : input.now;
+        const action = input.action === undefined ? grant?.action ?? "" : input.action;
+        const receipts = readRoutineActionReceipts(agentRoot);
+        const decision = inspectRoutineActionGrantSnapshot(policy, snapshot.rows, receipts, { ...input, action, now });
+        if (!decision.allowed)
+            throw new Error(decision.reason);
+        const resolvedTarget = input.resolvedTarget === undefined
+            ? decision.requester.kind === "owner_event" ? decision.requester.target : { id: "unresolved", name: input.target }
+            : input.resolvedTarget;
+        if (!record(resolvedTarget) || !text(resolvedTarget.id) || resolvedTarget.name !== input.target)
+            throw new Error("routine action resolved target is invalid");
+        if (decision.requester.kind === "owner_event" && resolvedTarget.id !== decision.requester.target.id)
+            throw new Error("routine action event target binding changed");
+        ensureDirectory(agentRoot);
+        const id = `action-${(0, node_crypto_1.randomUUID)()}`;
+        const receipt = {
+            schemaVersion: 2,
+            id,
+            state: "reserved",
+            key: input.key,
+            action,
+            target: input.target,
+            policyVersion: policy.version,
+            grantVersion: grant.version,
+            desiredStateVersion: decision.desiredStateVersion,
+            requester: structuredClone(decision.requester),
+            reservedAt: now,
+            updatedAt: now,
+            authorizationReceiptId,
+            authorizationVersion: decision.authorizationVersion,
+            attemptId: input.attemptId ?? `attempt-${(0, node_crypto_1.randomUUID)()}`,
+            attempt: 1,
+            expectedBeforeState: input.expectedBeforeState ?? null,
+            resolvedTarget: { id: resolvedTarget.id, name: resolvedTarget.name },
+            effect: input.effect ?? { operation: action, targetId: resolvedTarget.id },
+            effectReceipt: null,
+            verifiedAfterState: null,
+            recoveryState: { state: "not_needed", compensation: "none" },
+        };
+        appendReceipt(receiptsPath(agentRoot), receipt);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.routine_action_reserved", message: "reserved routine action grant", meta: { key: input.key, target: input.target, policyVersion: policy.version } });
+        return receipt;
+    });
+}
+function withStewardPolicyLease(agentRoot, operation) {
+    return (0, session_transaction_1.withSessionTurnLease)(policyPath(agentRoot), operation);
+}
+async function withRoutineActionAttempt(agentRoot, reservation, validate, attempt) {
+    await withStewardPolicyLease(agentRoot, async (lease) => {
+        await validate();
+        const snapshot = readAuditedPolicy(agentRoot, lease);
+        const receipts = readRoutineActionReceipts(agentRoot);
+        const current = receipts.find((receipt) => receipt.id === reservation.id);
+        if (!current || current.state !== "reserved" || !(0, node_util_1.isDeepStrictEqual)(current, reservation))
+            throw new Error("routine action reservation changed");
+        if (!reservation.requester || reservation.desiredStateVersion === undefined)
+            throw new Error("routine action reservation has no current requester binding");
+        const now = new Date().toISOString();
+        const decision = inspectRoutineActionGrantSnapshot(snapshot.policy, snapshot.rows, receipts.filter((receipt) => receipt.id !== reservation.id), {
+            key: reservation.key, action: reservation.action, target: reservation.target, requester: reservation.requester,
+            authorizationVersion: reservation.authorizationVersion, expectedPolicyVersion: reservation.policyVersion,
+            expectedDesiredStateVersion: reservation.desiredStateVersion, expectedGrantVersion: reservation.grantVersion, now,
+        });
+        if (!decision.allowed)
+            throw new Error(decision.reason);
+        const reservedAt = Date.parse(reservation.reservedAt);
+        const windowStart = Date.parse(now) - snapshot.policy.routineActionGrants[reservation.key].windowMs;
+        if (!(reservedAt > windowStart && reservedAt <= Date.parse(now)))
+            throw new Error("routine action reservation is outside its rate window");
+        await attempt();
+    });
+}
+function transitionRoutineActionReceipt(agentRoot, input) {
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), () => {
+        const current = readRoutineActionReceipts(agentRoot).find((receipt) => receipt.id === input.id);
+        if (!current)
+            throw new Error("routine action receipt is missing");
+        if (current.state !== input.expectedState)
+            throw new Error(`routine action receipt state changed: expected ${input.expectedState}, got ${current.state}`);
+        const now = input.at ?? new Date().toISOString();
+        const recoveryState = input.recoveryState ?? current.recoveryState;
+        const next = {
+            ...current,
+            state: input.state,
+            updatedAt: now,
+            ...(input.effectReceipt !== undefined ? { effectReceipt: input.effectReceipt } : {}),
+            ...(input.verifiedAfterState !== undefined ? { verifiedAfterState: input.verifiedAfterState } : {}),
+            recoveryState,
+        };
+        appendReceipt(receiptsPath(agentRoot), next);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.routine_action_transitioned", message: "transitioned routine action receipt", meta: { id: next.id, state: next.state, target: next.target } });
+        return next;
+    });
+}
+async function recoverRoutineActionReceipts(agentRoot, options) {
+    const recovered = [];
+    for (const receipt of readRoutineActionReceipts(agentRoot)) {
+        if (receipt.state === "reserved") {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: receipt.id, expectedState: "reserved", state: "recovered_no_effect", recoveryState: { state: "completed", compensation: "none" } }));
+            continue;
+        }
+        if (receipt.state === "attempting") {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: receipt.id, expectedState: "attempting", state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } }));
+            continue;
+        }
+        if (receipt.state !== "effect_acknowledged" && receipt.state !== "recovery_pending")
+            continue;
+        const pending = receipt.state === "effect_acknowledged"
+            ? transitionRoutineActionReceipt(agentRoot, { id: receipt.id, expectedState: "effect_acknowledged", state: "recovery_pending", recoveryState: { state: "pending", compensation: "none" } })
+            : receipt;
+        options.afterRecoveryClaim?.(pending);
+        const observed = await options.observeTarget(pending.resolvedTarget);
+        if (observed.id === pending.resolvedTarget.id && observed.name === pending.resolvedTarget.name && observed.state === "running") {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: pending.id, expectedState: "recovery_pending", state: "verified", verifiedAfterState: observed.state, recoveryState: { state: "completed", compensation: "none" } }));
+        }
+        else {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: pending.id, expectedState: "recovery_pending", state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } }));
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.routine_action_recovery", message: "reconciled interrupted routine action receipts", meta: { recoveredCount: recovered.length } });
+    return recovered;
+}