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

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/machines.d.ts

@@ -94,23 +94,31 @@ 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 changed isolation is audited `device.isolation_reported`.
+     * 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. Audits `device.isolation_reported` when the isolation
-     * differs from the stored one (none stored counts as `sandbox`). Runs in the caller's
-     * transaction, with the machine's row locked.
+     * 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. */

package/dist/local-devices/machines.js

@@ -20,7 +20,7 @@ import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { LOCAL_PROVIDER } from "../sandbox/providers.js";
 import { deviceNotFound } from "../sandbox/sandbox.service.js";
 import { deviceRevokedTopic } from "./keys.js";
-import { deviceFeaturesOf, isolationOf, localPolicyOf } from "./policy-summary.js";
+import { deviceFeaturesOf, isolationOf, localPolicyDiff, localPolicyOf, opExplains, pendingPolicyOpsOf, } from "./policy-summary.js";
 import { LocalDeviceRelay } from "./relay.js";
 /** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
 export const MACHINE_CREDENTIAL_PREFIX = "cap_dev_";
@@ -162,7 +162,9 @@ let MachinesService = 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}).
      */
     async recordHello(machineId, hello, rawPolicy = hello.policy) {
         const self = await this.db
@@ -177,6 +179,7 @@ let MachinesService = class MachinesService {
             "roots",
             "created_at",
             "local_policy",
+            "pending_policy_ops",
         ])
             .where("id", "=", machineId)
             .where("revoked_at", "is", null)
@@ -229,14 +232,15 @@ let MachinesService = class MachinesService {
      * 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 changed isolation is audited `device.isolation_reported`.
+     * 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.
      */
     async recordPolicy(machineId, summary, rawPolicy = summary) {
         const self = await this.db
             .selectFrom("device_machines")
-            .select(["device_id", "org_id", "account_id", "local_policy"])
+            .select(["device_id", "org_id", "account_id", "local_policy", "pending_policy_ops"])
             .where("id", "=", machineId)
             .where("revoked_at", "is", null)
             .forUpdate()
@@ -253,12 +257,46 @@ let MachinesService = class MachinesService {
     }
     /**
      * The summary to store for one a program reported (hello or `policy` frame): the parsed one,
-     * else its raw isolation alone, else null. Audits `device.isolation_reported` when the isolation
-     * differs from the stored one (none stored counts as `sandbox`). Runs in the caller's
-     * transaction, with the machine's row locked.
+     * 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.
      */
     async reportedPolicy(machineId, self, reported, rawPolicy) {
         const summary = localPolicyOf(reported);
+        const prev = localPolicyOf(self.local_policy);
+        const diff = summary !== null && prev !== null ? localPolicyDiff(prev, summary) : null;
+        if (diff !== null) {
+            const now = Date.now();
+            const byOp = pendingPolicyOpsOf(self.pending_policy_ops).some((op) => op.until > now && opExplains(op, diff));
+            // the platform's op: its answer lists it (the isolation with it)
+            if (byOp)
+                return summary;
+            await audit(this.db.db, {
+                actorAccountId: self.account_id,
+                orgId: self.org_id,
+                action: "device.policy_changed",
+                target: self.device_id,
+                detail: {
+                    add: diff.add,
+                    remove: diff.remove,
+                    ...(diff.tier !== undefined && { tier: diff.tier.to, tierFrom: diff.tier.from }),
+                    ...(diff.localhost !== undefined && { localhost: diff.localhost }),
+                    ...(diff.isolation !== undefined && { isolation: diff.isolation }),
+                    ...(diff.remoteGrants !== undefined && { remoteGrants: diff.remoteGrants }),
+                    by: self.account_id,
+                    via: "device",
+                    machineId,
+                    approvalId: null,
+                    confirmed: true,
+                },
+            });
+            return summary;
+        }
         const isolation = summary?.isolation ?? isolationOf(rawPolicy);
         const before = isolationOf(self.local_policy) ?? "sandbox";
         if (isolation !== null && isolation !== before) {

package/dist/local-devices/policy-summary.d.ts

@@ -1,4 +1,4 @@
-import { type DeviceFeature, type DeviceLocalPolicySummary } from "@capybara-hq/plugin-sdk";
+import { type DeviceFeature, type DeviceLocalPolicySummary, type SandboxTier } from "@capybara-hq/plugin-sdk";
 /**
  * The known features in `v` (a hello's `features` or the stored column), in a fixed order and
  * deduped; anything else (unknown names, a non-array) is dropped.
@@ -18,3 +18,46 @@ export declare function localPolicyOf(v: unknown): DeviceLocalPolicySummary | nu
  * there is none.
  */
 export declare function isolationOf(v: unknown): "sandbox" | "none" | null;
+/**
+ * What changed between two local policy summaries, in the owner's terms (the device page's change
+ * list, sandbox dev tiers spec §10.4): hosts added to and removed from the allowlist, the chosen
+ * tier (`null`: follows the org's default), the localhost access, the isolation and whether the
+ * machine accepts the platform's changes. Facts the owner does not set (the effective tier, unix
+ * sockets) are left out. Each field is present only when it changed.
+ */
+export interface LocalPolicyDiff {
+    add: string[];
+    remove: string[];
+    tier?: {
+        from: SandboxTier | null;
+        to: SandboxTier | null;
+    };
+    localhost?: DeviceLocalPolicySummary["localhost"];
+    isolation?: DeviceLocalPolicySummary["isolation"];
+    remoteGrants?: DeviceLocalPolicySummary["remoteGrants"];
+}
+/** The {@link LocalPolicyDiff} from `prev` to `next`; null when nothing the owner sets changed. */
+export declare function localPolicyDiff(prev: DeviceLocalPolicySummary, next: DeviceLocalPolicySummary): LocalPolicyDiff | null;
+/**
+ * A `policy` op the platform sent to a machine whose answer may not be recorded yet (kept on the
+ * machine's row, `pending_policy_ops`): the change asked for, and until when (epoch ms) a summary
+ * the machine reports by itself may still be that op's.
+ */
+export interface PendingPolicyOp {
+    id: string;
+    add: string[];
+    remove: string[];
+    /** Present when the op set the tier (null: follow the org's default). */
+    tier?: SandboxTier | null;
+    isolation?: "sandbox";
+    until: number;
+}
+/** The pending ops stored on a machine row (malformed entries dropped). */
+export declare function pendingPolicyOpsOf(v: unknown): PendingPolicyOp[];
+/**
+ * Whether `diff` is what the platform's `op` did (its answer, or the machine's own report of it
+ * before the answer was recorded): hosts within the op's, the tier the op set, and only what a
+ * tier change moves with it (the isolation back to `sandbox`, the localhost access). The device
+ * page then lists the change once, as the platform's.
+ */
+export declare function opExplains(op: PendingPolicyOp, diff: LocalPolicyDiff): boolean;

package/dist/local-devices/policy-summary.js

@@ -61,3 +61,72 @@ export function isolationOf(v) {
     }
     return "none";
 }
+/** The {@link LocalPolicyDiff} from `prev` to `next`; null when nothing the owner sets changed. */
+export function localPolicyDiff(prev, next) {
+    const before = new Set(prev.allowedDomains);
+    const after = new Set(next.allowedDomains);
+    const d = {
+        add: [...after].filter((h) => !before.has(h)).sort(),
+        remove: [...before].filter((h) => !after.has(h)).sort(),
+    };
+    const fromTier = prev.tier ?? null;
+    const toTier = next.tier ?? null;
+    if (fromTier !== toTier)
+        d.tier = { from: fromTier, to: toTier };
+    if (prev.localhost !== next.localhost)
+        d.localhost = next.localhost;
+    if (prev.isolation !== next.isolation)
+        d.isolation = next.isolation;
+    if (prev.remoteGrants !== next.remoteGrants)
+        d.remoteGrants = next.remoteGrants;
+    const changed = d.add.length > 0 ||
+        d.remove.length > 0 ||
+        d.tier !== undefined ||
+        d.localhost !== undefined ||
+        d.isolation !== undefined ||
+        d.remoteGrants !== undefined;
+    return changed ? d : null;
+}
+/** The pending ops stored on a machine row (malformed entries dropped). */
+export function pendingPolicyOpsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    const hosts = (x) => Array.isArray(x) ? x.filter((h) => typeof h === "string") : [];
+    const out = [];
+    for (const e of v) {
+        if (typeof e !== "object" || e === null)
+            continue;
+        const o = e;
+        if (typeof o.id !== "string" || typeof o.until !== "number")
+            continue;
+        out.push({
+            id: o.id,
+            add: hosts(o.add),
+            remove: hosts(o.remove),
+            ...("tier" in o && { tier: isSandboxTier(o.tier) ? o.tier : null }),
+            ...(o.isolation === "sandbox" && { isolation: "sandbox" }),
+            until: o.until,
+        });
+    }
+    return out;
+}
+/**
+ * Whether `diff` is what the platform's `op` did (its answer, or the machine's own report of it
+ * before the answer was recorded): hosts within the op's, the tier the op set, and only what a
+ * tier change moves with it (the isolation back to `sandbox`, the localhost access). The device
+ * page then lists the change once, as the platform's.
+ */
+export function opExplains(op, diff) {
+    if (!diff.add.every((h) => op.add.includes(h)))
+        return false;
+    if (!diff.remove.every((h) => op.remove.includes(h)))
+        return false;
+    if (diff.tier !== undefined && (op.tier === undefined || diff.tier.to !== op.tier))
+        return false;
+    if (diff.isolation !== undefined && op.isolation === undefined && op.tier === undefined) {
+        return false;
+    }
+    if (diff.localhost !== undefined && op.tier === undefined)
+        return false;
+    return diff.remoteGrants === undefined;
+}

package/dist/models/embeddings.d.ts

@@ -2,9 +2,9 @@ import { type ExtensionEmbedRequest, type ExtensionEmbedResult, type ExtensionMo
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
-import { KernelEvents } from "../infra/events/kernel-events.js";
 import { type HookRunner } from "../runtime/hook-calls.js";
 import { ProviderRegistry } from "../runtime/providers.js";
+import { UsageReportJobs } from "../runtime/usage-report-jobs.js";
 import { ModelPurposesService } from "./purposes.js";
 /** An extension's `permissions.models` (what it declared, as approved in its manifest). */
 export type DeclaredModelPurposes = readonly NonNullable<ExtensionPermissions["models"]>[number][];
@@ -29,9 +29,9 @@ export declare const EMBED_MAX_INPUTS = 2048;
  *   limited by `models.embedTimeoutMs` (`ModelError("timeout")`), checks each result ({@link validateEmbedResult}: a
  *   wrong count, dimension or a non-finite number is a `ModelError` of kind `server`), and
  *   concatenates the vectors; no retries (an extension retries itself if it wants to);
- * - writes one `model_usage` row (the sum of the batches' input tokens) and announces it after the
- *   commit (`model_usage.recorded`: the usage reporter's `ModelUsageJobs` enqueues its
- *   `usage.report` delivery; the usage sweep catches up a lost one). A call that fails after the
+ * - writes one `model_usage` row (the sum of the batches' input tokens) and, in the same
+ *   transaction, owes its `usage.report` delivery while some plugin subscribes (`UsageReportJobs`,
+ *   transactional outbox spec §8.1). A call that fails after the
  *   provider answered some batches (an invalid result, a later batch failing) still records their
  *   input tokens before the error reaches the extension; one that fails before any answer records
  *   nothing.
@@ -42,14 +42,14 @@ export declare class ModelEmbeddings {
     readonly txHost: TransactionHost;
     private readonly purposes;
     private readonly providers;
-    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
-    private readonly events;
+    /** The row's `usage.report` delivery, owed with it. */
+    private readonly usage;
     private readonly log;
     /** `models.embedTimeoutMs` (hot). */
     private readonly config;
     constructor(kdb: KernelDb, txHost: TransactionHost, purposes: Pick<ModelPurposesService, "resolve">, providers: Pick<ProviderRegistry, "resolve">, 
-    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
-    events: Pick<KernelEvents, "emit">, log: Pick<Logger, "warn">, 
+    /** The row's `usage.report` delivery, owed with it. */
+    usage: Pick<UsageReportJobs, "oweModelUsage">, log: Pick<Logger, "warn">, 
     /** `models.embedTimeoutMs` (hot). */
     config: Pick<KernelConfigService, "get">);
     /** Refuses a purpose `plugin` did not declare with kind `embedding`, or an org it is off in. */
@@ -77,6 +77,6 @@ export declare class ModelEmbeddings {
         orgId: string;
         purpose: string;
     }): Promise<ExtensionModelTarget | null>;
-    /** One `model_usage` row; its `usage.report` delivery is enqueued after the commit. */
+    /** One `model_usage` row with its owed `usage.report` delivery. */
     private record;
 }

package/dist/models/embeddings.js

@@ -13,15 +13,14 @@ import { ApiError } from "../errors.js";
 import { isExtensionEnabled } from "../extensions/enabled.js";
 import { audit } from "../identity/audit.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
-import { afterCommit } from "../infra/database/after-commit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
-import { KernelEvents } from "../infra/events/kernel-events.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { embeddingDeniedAudit } from "../runtime/hook-calls.js";
 import { modelDeniedText } from "../runtime/model-call.js";
 import { ProviderRegistry } from "../runtime/providers.js";
+import { UsageReportJobs } from "../runtime/usage-report-jobs.js";
 import { ModelPurposesService } from "./purposes.js";
 /** Most texts one `ctx.models.embed` call may carry (the kernel splits them by `maxBatch`). */
 export const EMBED_MAX_INPUTS = 2048;
@@ -44,9 +43,9 @@ export const EMBED_MAX_INPUTS = 2048;
  *   limited by `models.embedTimeoutMs` (`ModelError("timeout")`), checks each result ({@link validateEmbedResult}: a
  *   wrong count, dimension or a non-finite number is a `ModelError` of kind `server`), and
  *   concatenates the vectors; no retries (an extension retries itself if it wants to);
- * - writes one `model_usage` row (the sum of the batches' input tokens) and announces it after the
- *   commit (`model_usage.recorded`: the usage reporter's `ModelUsageJobs` enqueues its
- *   `usage.report` delivery; the usage sweep catches up a lost one). A call that fails after the
+ * - writes one `model_usage` row (the sum of the batches' input tokens) and, in the same
+ *   transaction, owes its `usage.report` delivery while some plugin subscribes (`UsageReportJobs`,
+ *   transactional outbox spec §8.1). A call that fails after the
  *   provider answered some batches (an invalid result, a later batch failing) still records their
  *   input tokens before the error reaches the extension; one that fails before any answer records
  *   nothing.
@@ -57,19 +56,19 @@ let ModelEmbeddings = class ModelEmbeddings {
     txHost;
     purposes;
     providers;
-    events;
+    usage;
     log;
     config;
     constructor(kdb, txHost, purposes, providers, 
-    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
-    events, log, 
+    /** The row's `usage.report` delivery, owed with it. */
+    usage, log, 
     /** `models.embedTimeoutMs` (hot). */
     config) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.purposes = purposes;
         this.providers = providers;
-        this.events = events;
+        this.usage = usage;
         this.log = log;
         this.config = config;
     }
@@ -243,7 +242,7 @@ let ModelEmbeddings = class ModelEmbeddings {
             throw e;
         }
     }
-    /** One `model_usage` row; its `usage.report` delivery is enqueued after the commit. */
+    /** One `model_usage` row with its owed `usage.report` delivery. */
     async record(plugin, orgId, purpose, model, inputTokens) {
         const row = await this.kdb.db
             .insertInto("model_usage")
@@ -257,13 +256,7 @@ let ModelEmbeddings = class ModelEmbeddings {
         })
             .returning("id")
             .executeTakeFirstOrThrow();
-        // fire and forget: the extension's call never waits on the enqueue (PG, Redis); a lost one is
-        // caught up by the usage sweep
-        afterCommit(() => {
-            void this.events
-                .emit("model_usage.recorded", { id: row.id })
-                .catch((err) => this.log.warn("model usage event failed", { usageId: row.id, err }));
-        });
+        await this.usage.oweModelUsage(row.id, orgId);
     }
 };
 __decorate([
@@ -275,7 +268,7 @@ ModelEmbeddings = __decorate([
     __param(1, Inject(TransactionHost)),
     __param(2, Inject(ModelPurposesService)),
     __param(3, Inject(ProviderRegistry)),
-    __param(4, Inject(KernelEvents)),
+    __param(4, Inject(UsageReportJobs)),
     __param(5, Inject(KERNEL_LOGGER)),
     __param(6, Inject(KernelConfigService))
 ], ModelEmbeddings);

package/dist/models/models.module.js

@@ -9,6 +9,7 @@ import { ExtensionRegistryModule } from "../extensions/registry.js";
 import { IdentityModule } from "../identity/identity.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { ProvidersModule } from "../runtime/providers.js";
+import { UsageReportJobsModule } from "../runtime/usage-report-jobs.js";
 import { ModelEmbeddings } from "./embeddings.js";
 import { ModelEnablementModule } from "./enablement.js";
 import { PricesService } from "./prices.js";
@@ -28,6 +29,8 @@ ModelsModule = __decorate([
             OrgLockModule,
             ProvidersModule,
             ModelEnablementModule,
+            // an embed call's `usage.report` delivery, owed with its `model_usage` row (no queue)
+            UsageReportJobsModule,
         ],
         providers: [PricesService, ModelPurposesService, ModelEmbeddings],
         exports: [PricesService, ModelPurposesService, ModelEnablementModule, ModelEmbeddings],

package/dist/orgs/directory-sync.js

@@ -611,7 +611,7 @@ let DirectorySync = class DirectorySync {
         if (row?.source !== source)
             return undefined;
         const result = await this.offboarding.offboard(orgId, accountId, "directory");
-        // the markers, events and run stops follow the root commit (none after a rollback)
+        // the revocation markers and events follow the root commit (hints; none after a rollback)
         afterCommit(() => this.offboarding.afterOffboard(result));
         return result;
     }

package/dist/orgs/members.service.js

@@ -151,7 +151,7 @@ let MembersService = class MembersService {
         }
         const actor = { actorAccountId, ...(actorTokenId !== undefined && { actorTokenId }) };
         const res = await this.offboarding.offboard(orgId, targetId, "removed", actor);
-        // the markers, events and run stops follow the root commit (none after a rollback)
+        // the revocation markers and events follow the root commit (hints; none after a rollback)
         afterCommit(() => this.offboarding.afterOffboard(res));
         await audit(this.db.db, {
             ...actor,