@capybara-hq/kernel 0.1.0-rc.22 → 0.1.0-rc.24

package/dist/infra/outbox/registry.d.ts

@@ -0,0 +1,120 @@
+import type { JobsOptions } from "bullmq";
+import type { KernelQueueName } from "../queue/queue-names.js";
+/** What the registry says about one job name added through the outbox (spec §3.5, §5). */
+export interface OutboxJobSpec {
+    /** The kernel queue the job is added to, or the queues when one job name serves several. */
+    queue: KernelQueueName | readonly KernelQueueName[];
+    /** One sentence: why a duplicate delivery of this job is harmless (state check, key, id). */
+    idempotent: string;
+    /** Repo-relative path of the file whose `@Processor` handles the job. */
+    processedIn: string;
+    /**
+     * BullMQ options the dispatcher adds the job with over the queue defaults
+     * (`QUEUE_JOB_DEFAULTS`); the job id and the delay always come from the row.
+     */
+    opts?: Pick<JobsOptions, "attempts" | "backoff" | "priority" | "removeOnComplete" | "removeOnFail">;
+}
+/**
+ * Every job name added through the outbox. The task that introduces a job name adds its entry; a
+ * name without one does not type-check as an `OutboxJobName` (`add` does not check it at runtime).
+ */
+export declare const OUTBOX_JOBS: {
+    readonly run: {
+        readonly queue: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs"];
+        readonly idempotent: "the run worker starts only a run in `queued` state for this job's runId; a finished run's job only repeats the idempotent post-run ensureRun, a waiting run's does nothing";
+        readonly processedIn: "packages/kernel/src/runtime/run-processors.ts";
+        readonly opts: {
+            readonly attempts: 1;
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "ensure-run": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "ensureRun decides from the conversation's state; with nothing unconsumed it is a no-op";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "wait-timeout": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "a timeout acts only on a still-pending wait (a row lock and status check) and a resume starts only a waiting run with nothing else pending";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "stop-tree": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "stopping a stopped run is a no-op";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "deliver-to-parent": {
+        readonly queue: "cap-kernel-maintenance";
+        readonly idempotent: "the delivery's idempotency key is the child run id";
+        readonly processedIn: "packages/kernel/src/runtime/maintenance.ts";
+        readonly opts: {
+            readonly attempts: 5;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 5000;
+            };
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+    readonly "usage-report": {
+        readonly queue: "cap-kernel-usage-report";
+        readonly idempotent: "handlers are idempotent by eventId (the event's `<conversationId>/<seq>` or the model_usage row id), and the job's `pending` list keeps a retry from reaching plugins already served";
+        readonly processedIn: "packages/kernel/src/runtime/run-processors.ts";
+        readonly opts: {
+            readonly attempts: 6;
+            readonly backoff: {
+                readonly type: "exponential";
+                readonly delay: 2000;
+            };
+            readonly removeOnComplete: {
+                readonly age: number;
+                readonly count: 100000;
+            };
+            readonly removeOnFail: {
+                readonly age: number;
+                readonly count: 100000;
+            };
+        };
+    };
+    readonly deliver: {
+        readonly queue: "cap-kernel-channels";
+        readonly idempotent: "a delivery resumes from the conversation's delivered seq under a per-conversation lock and sends with idempotency keys, so a second job sends nothing twice";
+        readonly processedIn: "packages/kernel/src/channels/channels.module.ts";
+        readonly opts: {
+            readonly attempts: 8;
+            readonly backoff: {
+                readonly type: "deliver";
+            };
+            readonly priority: 10;
+            readonly removeOnComplete: true;
+            readonly removeOnFail: true;
+        };
+    };
+};
+export type OutboxJobName = keyof typeof OUTBOX_JOBS;
+/** The registry's BullMQ options of a job name (none for a name it does not list). */
+export declare function outboxJobOptions(name: string): OutboxJobSpec["opts"];

package/dist/infra/outbox/registry.js

@@ -0,0 +1,108 @@
+/**
+ * Every job name added through the outbox. The task that introduces a job name adds its entry; a
+ * name without one does not type-check as an `OutboxJobName` (`add` does not check it at runtime).
+ */
+export const OUTBOX_JOBS = {
+    // `runtime/run-jobs.ts` RUN_JOB: one name on both run queues (a sub-agent's runs go to the
+    // sub-agent queue), under the job ids `runJobId` builds and, for a waiting run's resume
+    // (`RunResume.resumeIn`), `resumeJobId`
+    run: {
+        queue: ["cap-kernel-runs", "cap-kernel-subagent-runs"],
+        idempotent: "the run worker starts only a run in `queued` state for this job's runId; a finished run's job only repeats the idempotent post-run ensureRun, a waiting run's does nothing",
+        processedIn: "packages/kernel/src/runtime/run-processors.ts",
+        // one attempt (the run's own paths handle failures); removed once done, so the next run of the
+        // same trigger can take the id again (the post-run ensureRun, R34)
+        opts: { attempts: 1, removeOnComplete: true, removeOnFail: true },
+    },
+    // `runtime/run-jobs.ts` ENSURE_RUN_JOB: the ensure-run backstop owed with every message, queue
+    // change, background task finish, sub-agent delivery and run end (spec §6), under the job ids
+    // `ensureRunJobId` builds
+    "ensure-run": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "ensureRun decides from the conversation's state; with nothing unconsumed it is a no-op",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // removed once done (the queue defaults keep finished jobs), so a later write under the same
+        // seq (a queue change writes no event of its own) owes a job that is not deduped away
+        opts: { removeOnComplete: true, removeOnFail: true },
+    },
+    // `runtime/waits.ts` WAIT_TIMEOUT_JOB: owed with the suspend that sets a run `waiting`, under
+    // `waitTimeoutJobId`, with `runAt` = the wait's deadline (spec §6 "Resumes and timeouts")
+    "wait-timeout": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "a timeout acts only on a still-pending wait (a row lock and status check) and a resume starts only a waiting run with nothing else pending",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // retried while PG is briefly unavailable; removed once done
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `runtime/subagents/tree-jobs.ts` STOP_TREE_JOB: owed by a run's terminal transaction that
+    // leaves an active fork child (or a person-stopped sub-agent's descendants), under
+    // `stopChildrenJobId`, and by a root's delete, under `stopDeletedTreeJobId` (spec §6)
+    "stop-tree": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "stopping a stopped run is a no-op",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        // retried while PG is briefly unavailable; removed once done
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `runtime/subagents/tree-jobs.ts` DELIVER_TO_PARENT_JOB: owed by a sub-agent run's terminal
+    // transaction, under `deliverToParentJobId` (spec §6)
+    "deliver-to-parent": {
+        queue: "cap-kernel-maintenance",
+        idempotent: "the delivery's idempotency key is the child run id",
+        processedIn: "packages/kernel/src/runtime/maintenance.ts",
+        opts: {
+            attempts: 5,
+            backoff: { type: "exponential", delay: 5_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+    // `runtime/usage-report-jobs.ts` USAGE_REPORT_JOB: owed with the usage it reports (a `usage`
+    // event or a `model_usage` row) while some plugin subscribes, under `usageReportJobId` /
+    // `modelUsageJobId` (spec §8.1)
+    "usage-report": {
+        queue: "cap-kernel-usage-report",
+        idempotent: "handlers are idempotent by eventId (the event's `<conversationId>/<seq>` or the model_usage row id), and the job's `pending` list keeps a retry from reaching plugins already served",
+        processedIn: "packages/kernel/src/runtime/run-processors.ts",
+        // first attempt plus 5 retries, 2 s doubling (F11); finished jobs kept a day so a re-add of the
+        // same id (a crash between the add and the row's delete) dedupes; failed ones a week; both
+        // capped by count (I-2: a long outage of a billing endpoint cannot grow Redis)
+        opts: {
+            attempts: 6,
+            backoff: { type: "exponential", delay: 2_000 },
+            removeOnComplete: { age: 24 * 3600, count: 100_000 },
+            removeOnFail: { age: 7 * 86_400, count: 100_000 },
+        },
+    },
+    // `channels/deliver-job.ts` DELIVER_JOB: owed by every event append of a conversation with a
+    // channel target (a reply, an approval decision, a question answer, a wait stop) and by binding
+    // a conversation to its target, under `deliverJobId` (spec §8.1)
+    deliver: {
+        queue: "cap-kernel-channels",
+        idempotent: "a delivery resumes from the conversation's delivered seq under a per-conversation lock and sends with idempotency keys, so a second job sends nothing twice",
+        processedIn: "packages/kernel/src/channels/channels.module.ts",
+        // the platform's retry-after, else exponential (the processor's `deliver` backoff strategy);
+        // behind inbound jobs; removed once done, so a later append's id is never deduped away
+        opts: {
+            attempts: 8,
+            backoff: { type: "deliver" },
+            priority: 10,
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    },
+};
+/** The registry's BullMQ options of a job name (none for a name it does not list). */
+export function outboxJobOptions(name) {
+    return OUTBOX_JOBS[name]?.opts;
+}

package/dist/infra/queue/queue-names.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The kernel's own BullMQ queues, spelled as literals so infra code (the outbox registry and
+ * dispatcher) names a queue without importing feature modules. `KERNEL_QUEUE_NAMES`
+ * (admin/health.service.ts) lists the same names from the feature constants;
+ * test/infra/queue-names.test.ts keeps the two equal.
+ */
+export declare const KERNEL_QUEUES: readonly ["cap-kernel-runs", "cap-kernel-subagent-runs", "cap-kernel-channels", "cap-kernel-maintenance", "cap-kernel-plugin-scope", "cap-kernel-titles", "cap-kernel-usage-report", "cap-kernel-evals"];
+export type KernelQueueName = (typeof KERNEL_QUEUES)[number];

package/dist/infra/queue/queue-names.js

@@ -0,0 +1,16 @@
+/**
+ * The kernel's own BullMQ queues, spelled as literals so infra code (the outbox registry and
+ * dispatcher) names a queue without importing feature modules. `KERNEL_QUEUE_NAMES`
+ * (admin/health.service.ts) lists the same names from the feature constants;
+ * test/infra/queue-names.test.ts keeps the two equal.
+ */
+export const KERNEL_QUEUES = [
+    "cap-kernel-runs",
+    "cap-kernel-subagent-runs",
+    "cap-kernel-channels",
+    "cap-kernel-maintenance",
+    "cap-kernel-plugin-scope",
+    "cap-kernel-titles",
+    "cap-kernel-usage-report",
+    "cap-kernel-evals",
+];

package/dist/kernel.module.js

@@ -25,6 +25,7 @@ import { databaseCheck, HEALTH_CHECKS, redisCheck } from "./infra/health/health.
 import { GracefulShutdownModule } from "./infra/lifecycle/graceful-shutdown.module.js";
 import { LockModule } from "./infra/lock/lock.module.js";
 import { LoggingModule } from "./infra/logging/logging.module.js";
+import { OutboxModule } from "./infra/outbox/outbox.module.js";
 import { PresenceModule } from "./infra/presence/presence.module.js";
 import { QueueModule } from "./infra/queue/queue.module.js";
 import { RedisModule } from "./infra/redis/redis.module.js";
@@ -95,6 +96,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 ConfigModule.forRoot(config, options.env !== undefined ? { env: options.env } : {}),
                 GracefulShutdownModule,
                 DatabaseModule.forRoot(),
+                // owed jobs written in the caller's transaction (transactional outbox spec §3.2)
+                OutboxModule,
                 RedisModule,
                 LockModule,
                 CacheModule,

package/dist/local-devices/device-policy.service.d.ts

@@ -53,6 +53,10 @@ export declare class DevicePolicyService {
         features: DeviceFeature[];
         policy: DeviceLocalPolicySummary | null;
     } | null>;
+    /** Adds `op` to the machine's pending ops, dropping the expired ones. */
+    private notePending;
+    /** Removes the pending op `opId` from the machine's row. */
+    private dropPending;
     /**
      * 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`

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

@@ -7,8 +7,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { randomUUID } from "node:crypto";
 import { ToolError, validateAllowHost, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -21,6 +23,11 @@ import { isolationOf } from "./policy-summary.js";
 import { 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;
 /** The prefix the relay puts before a machine's `policy`-kind refusal. */
 const REFUSED_PREFIX = "Refused by the machine's local policy: ";
 const OFFLINE_MESSAGE = "The device's machine is offline, so its policy was not changed. Start capybara-device on it.";
@@ -89,6 +96,17 @@ let DevicePolicyService = class DevicePolicyService {
             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
+        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;
         try {
             ({ policy } = await this.relay.call(input.deviceId, "policy", args, {
@@ -101,11 +119,15 @@ let DevicePolicyService = class DevicePolicyService {
             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, policy: null });
+                await this.record({ ...input, machineId: machine.id, opId, policy: null });
+            }
+            else {
+                // refused or failed: nothing changed, so it explains no later change
+                await this.dropPending(machine.id, opId);
             }
             return this.notApplied(input.deviceId, e);
         }
-        await this.record({ ...input, machineId: machine.id, policy });
+        await this.record({ ...input, machineId: machine.id, opId, policy });
         return { applied: true, policy };
     }
     /** The active machine's features and policy summary (null when no machine is connected). */
@@ -113,6 +135,27 @@ let DevicePolicyService = class DevicePolicyService {
         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) {
+        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()}
+        ) || jsonb_build_array(${JSON.stringify(op)}::jsonb)`,
+        })
+            .where("id", "=", 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`
@@ -136,7 +179,11 @@ let DevicePolicyService = class DevicePolicyService {
                 isolationNow = input.policy.isolation;
             await this.db
                 .updateTable("device_machines")
-                .set({ local_policy: JSON.stringify(input.policy) })
+                // 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();
@@ -186,6 +233,12 @@ let DevicePolicyService = class DevicePolicyService {
         };
     }
 };
+__decorate([
+    Transactional()
+], DevicePolicyService.prototype, "notePending", null);
+__decorate([
+    Transactional()
+], DevicePolicyService.prototype, "dropPending", null);
 __decorate([
     Transactional()
 ], DevicePolicyService.prototype, "record", null);
@@ -198,6 +251,11 @@ DevicePolicyService = __decorate([
     __param(4, Inject(KERNEL_LOGGER))
 ], DevicePolicyService);
 export { DevicePolicyService };
+/** The machine's pending ops without `opId` (an expired one left for the next note to drop). */
+const withoutOp = (opId) => sql `(
+    SELECT coalesce(jsonb_agg(e), '[]'::jsonb) FROM jsonb_array_elements(pending_policy_ops) e
+    WHERE e->>'id' <> ${opId}
+  )`;
 /**
  * Hosts the platform may send: an approval's `add` takes exact hosts only (a card never grants a
  * wildcard); the owner's own change on the device page (no approval) may add a wildcard (spec §7);

package/dist/local-devices/local-device-gateway.d.ts

@@ -55,6 +55,8 @@ declare class DeviceConnection {
     private chain;
     /** Resolves once the lease is handed back (or was never held). */
     private released;
+    /** The hello's record, then each policy frame's, one after another (never rejects). */
+    private recorded;
     constructor(gw: LocalDeviceGateway, socket: WebSocket, identity: MachineIdentity, credential: string);
     get deviceId(): string;
     start(): void;
@@ -101,7 +103,7 @@ declare class DeviceConnection {
  * sockets are this process's own; everything other replicas need is in Redis.
  */
 export declare class LocalDeviceGateway {
-    readonly machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">;
+    readonly machines: Pick<MachinesService, "authenticate" | "recordHello" | "recordPolicy" | "touch">;
     readonly locks: Pick<LockService, "hold">;
     readonly bus: ExtensionContext["bus"];
     readonly redis: Redis;
@@ -112,7 +114,7 @@ export declare class LocalDeviceGateway {
     private stopping;
     /** How often connections are pinged ({@link PING_INTERVAL_MS}; a test seam). */
     pingIntervalMs: number;
-    constructor(machines: Pick<MachinesService, "authenticate" | "recordHello" | "touch">, locks: Pick<LockService, "hold">, bus: ExtensionContext["bus"], redis: Redis, config: KernelConfigService, log: Pick<KernelLogger, "info" | "warn">);
+    constructor(machines: Pick<MachinesService, "authenticate" | "recordHello" | "recordPolicy" | "touch">, locks: Pick<LockService, "hold">, bus: ExtensionContext["bus"], redis: Redis, config: KernelConfigService, log: Pick<KernelLogger, "info" | "warn">);
     graceMs(): number;
     leaseTtlMs(): number;
     maxFrameBytes(): number;

package/dist/local-devices/local-device-gateway.js

@@ -114,6 +114,8 @@ class DeviceConnection {
     chain = Promise.resolve();
     /** Resolves once the lease is handed back (or was never held). */
     released;
+    /** The hello's record, then each policy frame's, one after another (never rejects). */
+    recorded = Promise.resolve();
     constructor(gw, socket, identity, credential) {
         this.gw = gw;
         this.socket = socket;
@@ -174,20 +176,43 @@ class DeviceConnection {
             }
             clearTimeout(this.helloTimer);
             this.state = "claiming";
-            if (!(await this.claim()))
-                return;
-            try {
-                // the raw summary too: the frame parser drops one it cannot read whole, and its
-                // isolation must still reach the kernel
-                const rawPolicy = JSON.parse(text).policy;
-                await this.gw.machines.recordHello(this.identity.machineId, frame, rawPolicy);
-            }
-            catch (e) {
-                this.gw.log.warn("could not record a device hello", {
-                    deviceId: this.deviceId,
-                    error: errMsg(e),
-                });
-            }
+            // the raw summary too: the frame parser drops one it cannot read whole, and its
+            // isolation must still reach the kernel
+            const rawPolicy = JSON.parse(text).policy;
+            // set before the first await: a policy frame that follows is recorded after the hello
+            this.recorded = (async () => {
+                if (!(await this.claim()))
+                    return;
+                try {
+                    await this.gw.machines.recordHello(this.identity.machineId, frame, rawPolicy);
+                }
+                catch (e) {
+                    this.gw.log.warn("could not record a device hello", {
+                        deviceId: this.deviceId,
+                        error: errMsg(e),
+                    });
+                }
+            })();
+            await this.recorded;
+            return;
+        }
+        if (frame.type === "policy" && this.state !== "hello") {
+            // after the hello's record and the earlier policy frames, in the order they came
+            const rawPolicy = JSON.parse(text).policy;
+            this.recorded = this.recorded.then(async () => {
+                if (this.state === "closed")
+                    return;
+                try {
+                    await this.gw.machines.recordPolicy(this.identity.machineId, frame.policy, rawPolicy);
+                }
+                catch (e) {
+                    this.gw.log.warn("could not record a device policy change", {
+                        deviceId: this.deviceId,
+                        error: errMsg(e),
+                    });
+                }
+            });
+            await this.recorded;
             return;
         }
         if (frame.type !== "res" || this.state === "hello") {

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

@@ -94,9 +94,33 @@ export declare class MachinesService {
      * alone, read from `rawPolicy` (the frame's raw `policy`; {@link isolationOf}: anything but
      * `sandbox` is `none`), so it never hides that commands run without a sandbox. A reported
      * 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.
+     * `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}).
      */
     recordHello(machineId: string, hello: DeviceHello, rawPolicy?: unknown): Promise<void>;
+    /**
+     * 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
+     * ceiling), read and audited as the hello's ({@link recordHello}): an unreadable summary keeps
+     * its isolation alone (`rawPolicy`); a change the owner made on the machine is audited
+     * `device.policy_changed` (`via: "device"`), else a changed isolation `device.isolation_reported`.
+     * The next sandbox call then records a new `device_paths` event when the facts the model is told
+     * changed. A revoked machine is left alone.
+     */
+    recordPolicy(machineId: string, summary: DeviceLocalPolicySummary | undefined, rawPolicy?: unknown): Promise<void>;
+    /**
+     * The summary to store for one a program reported (hello or `policy` frame): the parsed one,
+     * else its raw isolation alone, else null. When both the stored and the reported summary are
+     * readable and what the owner sets changed ({@link localPolicyDiff}) by no `policy` op the
+     * platform sent ({@link opExplains}: its answer may come after the machine's own report), the
+     * owner changed it on the machine (`capybara-device policy ...`): audited
+     * `device.policy_changed` with `via: "device"`, the isolation with it, so the device page lists
+     * it beside the platform's changes; one an op explains is not audited here (the op's answer
+     * is). Otherwise a reported isolation that differs from the stored one (none stored counts as
+     * `sandbox`) is audited `device.isolation_reported`. A summary reported again is no change. Runs in the caller's transaction, with the machine's row locked.
+     */
+    private reportedPolicy;
     /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
     touch(machineId: string): Promise<void>;
     /**