@capybara-hq/kernel 0.1.0-rc.25 → 0.1.0-rc.27

package/dist/local-devices/device-policy.service.js

@@ -9,66 +9,111 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { randomUUID } from "node:crypto";
 import { ToolError, validateAllowHost, } from "@capybara-hq/plugin-sdk";
-import { Inject, Injectable } from "@nestjs/common";
+import { Inject, Injectable, Optional } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { currentStore, TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { deviceNotFound } from "../sandbox/sandbox.service.js";
 import { MachinesService } from "./machines.js";
-import { isolationOf } from "./policy-summary.js";
-import { LocalDeviceRelay, ON_MACHINE_PREFIX } from "./relay.js";
+import { DEVICE_OP_RESOLVE_JOB, deviceOpResolveJobId } from "./policy-op-jobs.js";
+import { isolationOf, pendingPolicyOpsOf } from "./policy-summary.js";
+import { LIST_TTL_MARGIN_MS, LocalDeviceRelay, ON_MACHINE_PREFIX } from "./relay.js";
 /** How long the machine may take to apply a policy change. */
 export const POLICY_DEADLINE_MS = 30_000;
-/**
- * How long a sent op may still explain a summary the machine reports by itself: its deadline and
- * the reconnect grace, with room for an answer that comes only with the next hello.
- */
-const PENDING_OP_MS = POLICY_DEADLINE_MS + 5 * 60_000;
+/** How long the machine may take to answer a `policyStatus` (it only reads its op log). */
+const STATUS_DEADLINE_MS = 10_000;
+/** How long an op left `unknown` waits for the machine's hello to report it (from its intent). */
+export const UNKNOWN_OP_MS = 24 * 3_600_000;
 /** The prefix the relay puts before a machine's `policy`-kind refusal. */
 const REFUSED_PREFIX = "Refused by the machine's local policy: ";
+/**
+ * Test seam (`KernelOverride`): called by {@link DevicePolicyService.send} right after the `policy`
+ * op's call returned, before its outcome is recorded (by `apply` or a network ask's decision);
+ * throwing stands for a crash between the call and the resolve transaction.
+ * The kernel never provides it.
+ */
+export const DEVICE_POLICY_AFTER_CALL = Symbol("DEVICE_POLICY_AFTER_CALL");
 const OFFLINE_MESSAGE = "The device's machine is offline, so its policy was not changed. Start capybara-device on it.";
 const UNSUPPORTED_MESSAGE = "The device's capybara-device program cannot change its policy from the platform. Update capybara-device on the machine.";
+const UNCONFIRMED_MESSAGE = "The device's machine did not confirm the policy change; the platform checks it again shortly.";
+const INTERRUPTED_MESSAGE = "capybara-device stopped while applying the policy change, and the change is not in the device's policy now.";
+/** The longest text of the machine's own error the caller is told (as its op log keeps it). */
+const MAX_MACHINE_MESSAGE = 500;
+const NOT_RECEIVED_MESSAGE = "The device's machine never received the policy change.";
 const errMsg = (e) => (e instanceof Error ? e.message : String(e));
 /**
  * Changes a local device's policy on its machine (network ask-to-allow spec §5.2; sandbox dev
  * tiers spec §7.3: its hosts, its `tier`, and `isolation` back to `sandbox`): the kernel→device
- * `policy` op over the {@link LocalDeviceRelay}. The machine is the authority: it
- * refuses widening unless its owner allows remote grants, validates every host and answers with
- * the policy as written, which the kernel then keeps on the active machine's row (§5.4) and
- * audits as `device.policy_changed`.
+ * `policy` op over the {@link LocalDeviceRelay}. The machine is the authority: it refuses
+ * widening unless its owner allows remote grants, validates every host and answers with the
+ * policy as written, which the kernel then keeps on the active machine's row (§5.4).
  *
- * The op is sent outside any transaction (a decision records its outcome afterwards, in its own
- * transaction); only the summary write and the audit row are transactional. Callers decide who
- * may change a device's policy (the device owner, in a signed-in session); this service checks
- * only that the device is a live device of the org.
+ * Intent first (transactional outbox spec §7): {@link begin} writes the intent in a transaction
+ * before anything is sent (the entry on the machine row's `pending_policy_ops`, the audit
+ * `device.policy_requested` and the `device-op-resolve` job owed for when the op can no longer
+ * reach the machine); the call sends the op with its id (no transaction open); {@link settleIn}
+ * records the outcome: `device.policy_changed` (applied), `device.policy_failed` (refused, never
+ * received) or `device.policy_unknown` (no answer: the entry stays, `unknown`, for the machine's
+ * next hello or the resolver). A crash between the call and the resolve transaction leaves the
+ * intent and its owed job, whose resolver asks the machine what became of the op (never sends it
+ * again). Callers decide who may change a device's policy (the device owner, in a signed-in
+ * session); this service checks only that the device is a live device of the org.
  */
 let DevicePolicyService = class DevicePolicyService {
     db;
     txHost;
     relay;
     machines;
+    outbox;
+    config;
     log;
-    constructor(db, txHost, relay, machines, log) {
+    afterCall;
+    constructor(db, txHost, relay, machines, outbox, config, log, afterCall = () => { }) {
         this.db = db;
         this.txHost = txHost;
         this.relay = relay;
         this.machines = machines;
+        this.outbox = outbox;
+        this.config = config;
         this.log = log;
+        this.afterCall = afterCall;
     }
     /**
-     * Sends the `policy` op (no transaction may be open), stores the returned summary and audits
-     * `device.policy_changed`. Never throws for an offline machine, a refusal or a program without
-     * the `policyOp` feature (nothing is sent to it); a device that is not a live device of `orgId`
-     * is `device.not_found`.
+     * Changes the policy: {@link begin}, the call, then the outcome recorded in its own transaction
+     * (no transaction may be open). Never throws for an offline machine, a refusal or a program
+     * without the `policyOpId` feature (nothing is sent to it); a device that is not a live device
+     * of `orgId` is `device.not_found`.
      */
     async apply(input) {
+        const begun = await this.begin(input);
+        if ("outcome" in begun)
+            return begun.outcome;
+        const { intent } = begun;
+        const sent = await this.send(intent);
+        const out = await this.settle(intent, sent.result);
+        if (sent.notFound)
+            throw deviceNotFound();
+        // unknown: the caller is told what the call saw (offline, or an answer the machine did not
+        // confirm), not the recorded state's generic text
+        return sent.result.outcome === "unknown" ? sent.outcome : (out ?? sent.outcome);
+    }
+    /**
+     * Checks the device and its machine, then records the intent in its own transaction: the entry
+     * (`sent`) on the machine's row, the audit `device.policy_requested` and the `device-op-resolve`
+     * job owed for when the op can no longer reach the machine. No transaction may be open (the
+     * call follows). Returns the intent, or why nothing will be sent (offline, unsupported).
+     */
+    async begin(input) {
         if (currentStore()) {
-            throw new Error("DevicePolicyService.apply() must not run inside a transaction: send the policy op " +
-                "first, then record the decision in a transaction.");
+            throw new Error("DevicePolicyService.begin() must not run inside a transaction: the intent is recorded " +
+                "first, the policy op sent, then the outcome recorded in a transaction.");
         }
         assertHosts(input.change, input.source.approvalId !== undefined);
         const device = await this.db
@@ -82,176 +127,327 @@ let DevicePolicyService = class DevicePolicyService {
             .executeTakeFirst();
         if (!device)
             throw deviceNotFound();
-        if (device.source !== "local") {
-            return { applied: false, reason: "unsupported", message: UNSUPPORTED_MESSAGE };
-        }
+        if (device.source !== "local")
+            return { outcome: unsupported() };
         const machine = await this.machines.activeFor(input.deviceId);
         if (machine === null)
-            return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
-        if (!machine.features.includes("policyOp")) {
-            return { applied: false, reason: "unsupported", message: UNSUPPORTED_MESSAGE };
-        }
+            return { outcome: offline() };
+        // only a program that logs op outcomes under their ids can tell what became of a lost answer
+        if (!machine.features.includes("policyOpId"))
+            return { outcome: unsupported() };
         // not connected: nothing is sent (a queued op would wait for a reconnect nobody watches)
-        if (!(await this.relay.holderLive(input.deviceId))) {
-            return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
-        }
-        const args = { ...input.change, source: input.source };
-        // noted before it is sent: the machine may report the change by itself (a `policy` frame)
-        // before its answer is recorded, and the device page lists it once, as the platform's
+        if (!(await this.relay.holderLive(input.deviceId)))
+            return { outcome: offline() };
         const opId = randomUUID();
-        await this.notePending(machine.id, {
-            id: opId,
-            add: input.change.add ?? [],
-            remove: input.change.remove ?? [],
-            ...(input.change.tier !== undefined && { tier: input.change.tier }),
-            ...(input.change.isolation !== undefined && { isolation: input.change.isolation }),
-            until: Date.now() + PENDING_OP_MS,
-        });
-        let policy;
+        const args = { ...input.change, opId, source: input.source };
+        const recorded = await this.recordIntent({ ...input, machineId: machine.id, opId });
+        if (!recorded)
+            return { outcome: offline() };
+        return {
+            intent: { orgId: input.orgId, deviceId: input.deviceId, machineId: machine.id, opId, args },
+        };
+    }
+    /**
+     * Sends the intent's `policy` op (no transaction may be open) and classifies the answer:
+     * applied; refused (the machine's local policy refused it: its message); anything else is
+     * `unknown`, left to the resolver's `policyStatus`: no answer, and an answer the kernel cannot
+     * trust to mean "not applied" (a result it cannot read, the machine's own error). `notFound`:
+     * the device was deleted meanwhile (recorded as unknown; the caller throws `device.not_found`).
+     */
+    async send(intent) {
+        if (currentStore()) {
+            throw new Error("DevicePolicyService.send() must not run inside a transaction: the outcome is recorded " +
+                "afterwards, in its own transaction.");
+        }
+        const sent = await this.call(intent);
+        this.afterCall(intent.opId);
+        return sent;
+    }
+    /** The `policy` op's call and its classification ({@link send}). */
+    async call(intent) {
         try {
-            ({ policy } = await this.relay.call(input.deviceId, "policy", args, {
+            const { policy } = await this.relay.call(intent.deviceId, "policy", intent.args, {
                 deadlineMs: POLICY_DEADLINE_MS,
                 // the relay gives up by itself (deadline plus the reconnect grace)
                 signal: new AbortController().signal,
-            }));
+            });
+            return { result: { outcome: "applied", policy }, outcome: { applied: true, policy } };
         }
         catch (e) {
-            if (e instanceof ApiError && e.code === "device.offline") {
-                // the op was sent and the wait ran out: the machine may still apply it, so the attempt is
-                // audited unconfirmed; its next hello reports the policy as it is
-                await this.record({ ...input, machineId: machine.id, opId, policy: null });
+            if (e instanceof ApiError) {
+                // device.offline (the wait ran out: the machine may still apply it), device.forbidden
+                // (the machine was disconnected meanwhile), device.not_found (the device was deleted)
+                return {
+                    result: { outcome: "unknown" },
+                    outcome: offline(),
+                    ...(e.code === "device.not_found" && { notFound: true }),
+                };
             }
-            else {
-                // refused or failed: nothing changed, so it explains no later change
-                await this.dropPending(machine.id, opId);
+            if (e instanceof ToolError && e.message.startsWith(REFUSED_PREFIX)) {
+                const message = e.message.slice(REFUSED_PREFIX.length);
+                return {
+                    result: { outcome: "refused", message },
+                    outcome: { applied: false, reason: "refused", message },
+                };
             }
-            return this.notApplied(input.deviceId, e);
+            // an unreadable result (the machine may have applied it) or the machine's own error (it may
+            // have failed after the write): what the machine logged under the op id tells
+            this.log.warn("a device policy change was not confirmed by the machine", {
+                deviceId: intent.deviceId,
+                opId: intent.opId,
+                error: errMsg(e),
+            });
+            const raw = errMsg(e);
+            const message = (raw.startsWith(ON_MACHINE_PREFIX) ? raw.slice(ON_MACHINE_PREFIX.length) : raw).slice(0, MAX_MACHINE_MESSAGE);
+            return {
+                result: { outcome: "unknown" },
+                outcome: {
+                    applied: false,
+                    reason: "offline",
+                    message: `${UNCONFIRMED_MESSAGE} ${message}`,
+                },
+            };
         }
-        await this.record({ ...input, machineId: machine.id, opId, policy });
-        return { applied: true, policy };
+    }
+    /**
+     * What the machine says became of the op `opId` (a read-only `policyStatus`), or `offline` when
+     * no replica holds its connection or it does not answer. Never sends the change.
+     */
+    async outcomeOf(deviceId, opId) {
+        if (!(await this.relay.holderLive(deviceId)))
+            return { outcome: "offline" };
+        try {
+            return await this.relay.call(deviceId, "policyStatus", { opId }, { deadlineMs: STATUS_DEADLINE_MS, signal: new AbortController().signal });
+        }
+        catch (e) {
+            this.log.warn("could not ask a machine what became of a policy op", {
+                deviceId,
+                opId,
+                error: errMsg(e),
+            });
+            return { outcome: "offline" };
+        }
+    }
+    /**
+     * Records what became of the op `opId` of machine `machineId`, in the caller's transaction (the
+     * machine's row locked): `applied` → the policy the machine wrote (when given) kept on the row,
+     * the entry removed, `device.policy_changed` (`late` when the op was left `unknown`); `refused`,
+     * `not_received` or `interrupted` → the entry removed, `device.policy_failed` (`reason` the
+     * outcome); `unknown` → the entry kept, `unknown` until a day after its intent,
+     * `device.policy_unknown` (once; ignored once a hello reported the op). Returns the outcome for
+     * the caller, or null when the op has no live entry (resolved already, or expired: a no-op).
+     */
+    async settleIn(ref, result) {
+        const row = await this.db
+            .selectFrom("device_machines")
+            .select(["org_id", "device_id", "local_policy", "pending_policy_ops", "revoked_at"])
+            .where("id", "=", ref.machineId)
+            .forUpdate()
+            .executeTakeFirst();
+        const op = pendingPolicyOpsOf(row?.pending_policy_ops).find((o) => o.id === ref.opId);
+        // an expired entry no longer explains the machine's own reports (they are audited as the
+        // owner's): recording the op too would list the change twice
+        if (row === undefined || op === undefined || op.until <= Date.now())
+            return null;
+        const auditOp = (action, extra) => audit(this.db.db, {
+            actorAccountId: op.source.accountId,
+            ...(op.actorTokenId !== undefined && { actorTokenId: op.actorTokenId }),
+            orgId: row.org_id,
+            action,
+            target: row.device_id,
+            detail: { ...changeDetail(op), ...extra },
+        });
+        if (result.outcome === "unknown") {
+            // a hello reported the op meanwhile (its job records it), or it is unknown already
+            if (op.reported !== undefined || op.status === "unknown")
+                return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
+            await this.db
+                .updateTable("device_machines")
+                .set({
+                pending_policy_ops: withOp(op.id, {
+                    status: "unknown",
+                    until: op.sentAt + UNKNOWN_OP_MS,
+                }),
+            })
+                .where("id", "=", ref.machineId)
+                .execute();
+            await auditOp("device.policy_unknown", {});
+            return offline();
+        }
+        const live = row.revoked_at === null;
+        let isolationNow;
+        const policy = result.outcome === "applied" ? result.policy : undefined;
+        if (policy !== undefined && live) {
+            // the isolation the machine reports now, when it differs from the stored one: a tier change
+            // turns an unsandboxed device's sandbox back on without asking for it (spec §5.4, §10.4)
+            const before = isolationOf(row.local_policy) ?? "sandbox";
+            if (policy.isolation !== before)
+                isolationNow = policy.isolation;
+        }
+        await this.db
+            .updateTable("device_machines")
+            .set({
+            // resolved: the op no longer explains a summary the machine reports
+            pending_policy_ops: withoutOp(op.id),
+            ...(policy !== undefined && live && { local_policy: JSON.stringify(policy) }),
+        })
+            .where("id", "=", ref.machineId)
+            .execute();
+        if (result.outcome === "applied") {
+            await auditOp("device.policy_changed", {
+                ...(isolationNow !== undefined && { isolation: isolationNow }),
+                ...(op.status === "unknown" && { late: true }),
+            });
+            const stored = policy ?? (await this.machines.activeFor(row.device_id))?.localPolicy;
+            return stored
+                ? { applied: true, policy: stored }
+                : { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
+        }
+        const message = result.outcome === "refused"
+            ? result.message
+            : result.outcome === "interrupted"
+                ? INTERRUPTED_MESSAGE
+                : NOT_RECEIVED_MESSAGE;
+        await auditOp("device.policy_failed", { reason: result.outcome, message });
+        return result.outcome === "refused"
+            ? { applied: false, reason: "refused", message }
+            : offline();
     }
     /** The active machine's features and policy summary (null when no machine is connected). */
     async summary(deviceId) {
         const m = await this.machines.activeFor(deviceId);
         return m === null ? null : { features: m.features, policy: m.localPolicy };
     }
-    /** Adds `op` to the machine's pending ops, dropping the expired ones. */
-    async notePending(machineId, op) {
+    /**
+     * How long after its intent an op can no longer reach the machine: the call's deadline, the
+     * reconnect grace and the request list's margin (the relay's list TTL), plus 5 s. A machine
+     * that does not know the op id by then never will.
+     */
+    resolveDelayMs() {
+        const graceMs = this.config.get().devices.local.reconnectGraceSeconds * 1000;
+        return POLICY_DEADLINE_MS + graceMs + LIST_TTL_MARGIN_MS + 5_000;
+    }
+    /** {@link settleIn} in its own transaction (the {@link apply} path). */
+    settle(intent, result) {
+        return this.settleIn(intent, result);
+    }
+    /**
+     * The intent transaction: locks the machine's row (still the device's active machine), appends
+     * the entry (dropping the expired ones), audits `device.policy_requested` and owes the
+     * `device-op-resolve` job. False when the machine was revoked meanwhile (nothing written).
+     */
+    async recordIntent(input) {
+        const locked = await this.db
+            .selectFrom("device_machines")
+            .select("id")
+            .where("id", "=", input.machineId)
+            .where("revoked_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (locked === undefined)
+            return false;
+        const now = Date.now();
+        const resolveAt = now + this.resolveDelayMs();
+        const { change, source } = input;
+        const op = {
+            id: input.opId,
+            add: change.add ?? [],
+            remove: change.remove ?? [],
+            ...(change.tier !== undefined && { tier: change.tier }),
+            ...(change.isolation !== undefined && { isolation: change.isolation }),
+            source: {
+                accountId: source.accountId,
+                via: source.via,
+                approvalId: source.approvalId ?? null,
+            },
+            ...(input.actorTokenId !== undefined && { actorTokenId: input.actorTokenId }),
+            status: "sent",
+            sentAt: now,
+            resolveAt,
+            // a summary the machine reports by itself may be this op's until it is resolved
+            until: now + UNKNOWN_OP_MS,
+        };
         await this.db
             .updateTable("device_machines")
             .set({
             pending_policy_ops: sql `(
           SELECT coalesce(jsonb_agg(e), '[]'::jsonb) FROM jsonb_array_elements(pending_policy_ops) e
-          WHERE (e->>'until')::bigint > ${Date.now()}
+          WHERE (e->>'until')::bigint > ${now}
         ) || jsonb_build_array(${JSON.stringify(op)}::jsonb)`,
         })
-            .where("id", "=", machineId)
+            .where("id", "=", input.machineId)
             .execute();
-    }
-    /** Removes the pending op `opId` from the machine's row. */
-    async dropPending(machineId, opId) {
-        await this.db
-            .updateTable("device_machines")
-            .set({ pending_policy_ops: withoutOp(opId) })
-            .where("id", "=", machineId)
-            .execute();
-    }
-    /**
-     * Keeps the policy the machine wrote on its row and audits the change (`confirmed`); with no
-     * policy (the answer never came) only audits the attempt, unconfirmed. The detail's `isolation`
-     * is the one asked for, or the one the machine now reports when it changed (a tier change turns
-     * the sandbox back on).
-     */
-    async record(input) {
-        // the isolation the machine reports now, when it differs from the stored one: a tier change
-        // turns an unsandboxed device's sandbox back on without asking for it (spec §5.4, §10.4)
-        let isolationNow;
-        if (input.policy !== null) {
-            const prev = await this.db
-                .selectFrom("device_machines")
-                .select("local_policy")
-                .where("id", "=", input.machineId)
-                .where("revoked_at", "is", null)
-                .forUpdate()
-                .executeTakeFirst();
-            const before = isolationOf(prev?.local_policy) ?? "sandbox";
-            if (input.policy.isolation !== before)
-                isolationNow = input.policy.isolation;
-            await this.db
-                .updateTable("device_machines")
-                // answered: the op no longer explains a summary the machine reports
-                .set({
-                local_policy: JSON.stringify(input.policy),
-                pending_policy_ops: withoutOp(input.opId),
-            })
-                .where("id", "=", input.machineId)
-                .where("revoked_at", "is", null)
-                .execute();
-        }
-        const { change, source } = input;
         await audit(this.db.db, {
             actorAccountId: source.accountId,
             ...(input.actorTokenId !== undefined && { actorTokenId: input.actorTokenId }),
             orgId: input.orgId,
-            action: "device.policy_changed",
+            action: "device.policy_requested",
             target: input.deviceId,
-            detail: {
-                add: change.add ?? [],
-                remove: change.remove ?? [],
-                // only when set (null: follow the org's default); the device page lists the change
-                ...(change.tier !== undefined && { tier: change.tier }),
-                ...((isolationNow ?? change.isolation) !== undefined && {
-                    isolation: isolationNow ?? change.isolation,
-                }),
-                by: source.accountId,
-                via: source.via,
-                approvalId: source.approvalId ?? null,
-                confirmed: input.policy !== null,
-            },
+            detail: changeDetail(op),
         });
-    }
-    /** The outcome of a failed op: offline, or the machine's refusal; a deleted device is thrown. */
-    notApplied(deviceId, e) {
-        if (e instanceof ApiError) {
-            if (e.code === "device.not_found")
-                throw e;
-            // device.offline, or device.forbidden (the machine was disconnected meanwhile)
-            return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
-        }
-        if (e instanceof ToolError && e.message.startsWith(REFUSED_PREFIX)) {
-            return { applied: false, reason: "refused", message: e.message.slice(REFUSED_PREFIX.length) };
-        }
-        // anything else the machine answered (its own error, an invalid result): not applied
-        this.log.warn("a device policy change failed on the machine", { deviceId, error: errMsg(e) });
-        const message = errMsg(e);
-        return {
-            applied: false,
-            reason: "refused",
-            message: message.startsWith(ON_MACHINE_PREFIX)
-                ? message.slice(ON_MACHINE_PREFIX.length)
-                : message,
-        };
+        await this.outbox.add({
+            queue: MAINTENANCE_QUEUE_NAME,
+            name: DEVICE_OP_RESOLVE_JOB,
+            jobId: deviceOpResolveJobId(input.opId),
+            data: { machineId: input.machineId, opId: input.opId },
+            runAt: new Date(resolveAt),
+            orgId: input.orgId,
+        });
+        return true;
     }
 };
 __decorate([
-    Transactional()
-], DevicePolicyService.prototype, "notePending", null);
+    Transactional({ propagation: "mandatory" })
+], DevicePolicyService.prototype, "settleIn", null);
 __decorate([
     Transactional()
-], DevicePolicyService.prototype, "dropPending", null);
+], DevicePolicyService.prototype, "settle", null);
 __decorate([
     Transactional()
-], DevicePolicyService.prototype, "record", null);
+], DevicePolicyService.prototype, "recordIntent", null);
 DevicePolicyService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
     __param(2, Inject(LocalDeviceRelay)),
     __param(3, Inject(MachinesService)),
-    __param(4, Inject(KERNEL_LOGGER))
+    __param(4, Inject(OutboxService)),
+    __param(5, Inject(KernelConfigService)),
+    __param(6, Inject(KERNEL_LOGGER)),
+    __param(7, Optional()),
+    __param(7, Inject(DEVICE_POLICY_AFTER_CALL))
 ], DevicePolicyService);
 export { DevicePolicyService };
-/** The machine's pending ops without `opId` (an expired one left for the next note to drop). */
+const offline = () => ({
+    applied: false,
+    reason: "offline",
+    message: OFFLINE_MESSAGE,
+});
+const unsupported = () => ({
+    applied: false,
+    reason: "unsupported",
+    message: UNSUPPORTED_MESSAGE,
+});
+/** The audit detail of an op's change and source (every `device.policy_*` row of an op). */
+function changeDetail(op) {
+    return {
+        opId: op.id,
+        add: op.add,
+        remove: op.remove,
+        // only when set (null: follow the org's default); the device page lists the change
+        ...(op.tier !== undefined && { tier: op.tier }),
+        ...(op.isolation !== undefined && { isolation: op.isolation }),
+        by: op.source.accountId,
+        via: op.source.via,
+        approvalId: op.source.approvalId,
+    };
+}
+/** The machine's pending ops with the fields `patch` merged into the op `opId`. */
+const withOp = (opId, patch) => sql `(
+    SELECT coalesce(jsonb_agg(CASE WHEN e->>'id' = ${opId} THEN e || ${JSON.stringify(patch)}::jsonb ELSE e END), '[]'::jsonb)
+    FROM jsonb_array_elements(pending_policy_ops) e
+  )`;
+/** The machine's pending ops without `opId` (an expired one left for the next intent to drop). */
 const withoutOp = (opId) => sql `(
     SELECT coalesce(jsonb_agg(e), '[]'::jsonb) FROM jsonb_array_elements(pending_policy_ops) e
     WHERE e->>'id' <> ${opId}

package/dist/local-devices/machines.d.ts

@@ -1,6 +1,7 @@
 import type { DeviceFeature, DeviceHello, DeviceLocalPolicySummary, DeviceStopArgs, ExtensionContext } from "@capybara-hq/plugin-sdk";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { LocalDeviceRelay } from "./relay.js";
 /** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
@@ -43,8 +44,9 @@ export declare class MachinesService {
     readonly txHost: TransactionHost;
     private readonly relay;
     private readonly bus;
+    private readonly outbox;
     private readonly log;
-    constructor(db: KernelDb, txHost: TransactionHost, relay: Pick<LocalDeviceRelay, "holderLive" | "send">, bus: ExtensionContext["bus"], log: Pick<KernelLogger, "warn">);
+    constructor(db: KernelDb, txHost: TransactionHost, relay: Pick<LocalDeviceRelay, "holderLive" | "send">, bus: ExtensionContext["bus"], outbox: Pick<OutboxService, "add">, log: Pick<KernelLogger, "warn">);
     /**
      * A new machine for the device and its credential (returned once). Revokes the
      * device's active machine first. Joins the caller's transaction (the device confirmation),
@@ -96,9 +98,22 @@ export declare class MachinesService {
      * isolation that differs from the stored one (none stored counts as `sandbox`) is audited
      * `device.isolation_reported` (sandbox dev tiers spec §10.4), once per change; a change of what
      * the owner sets, made on the machine while it was away, is audited `device.policy_changed`
-     * ({@link reportedPolicy}).
+     * ({@link reportedPolicy}). The outcomes of its recent policy ops (`recentOps`) backfill the
+     * platform's ops still pending on the row ({@link backfillOps}).
      */
     recordHello(machineId: string, hello: DeviceHello, rawPolicy?: unknown): Promise<void>;
+    /**
+     * Hello backfill (transactional outbox spec §7): a pending op of the platform's whose outcome
+     * the hello reports (`applied`, `refused`), or that it does not list although the op can no
+     * longer reach the machine (`absent`: past its `resolveAt`), is marked `reported` and owes a
+     * `device-op-resolve` job (`device-op-reported-<opId>`) that records the outcome. An op the
+     * machine logged only as `started` (it stopped between the log and the answer) is judged once
+     * past its `resolveAt` by the policy the hello reports: its change there → `applied`, else
+     * `interrupted` (within the window, or with no readable policy, it is left). An expired entry
+     * (past `until`) is skipped: the machine's reports are no longer the op's. Runs in the caller's
+     * transaction, with the machine's row locked; an op already reported is not owed again.
+     */
+    private backfillOps;
     /**
      * Stores the local policy summary a connected program pushed after its hello (a `policy` frame:
      * its policy file changed on the machine, its localhost proxy guard flipped, a new tier