@vantageos/agent-engine 0.1.0-alpha.7 → 0.3.0-alpha.0

package/dist/component/engine/durableJob.js

@@ -2,52 +2,38 @@ import { v } from "convex/values";
 import { WorkflowManager } from "@convex-dev/workflow";
 import { components, internal } from "../_generated/api.js";
 import { internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
-import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// durableJobs — THE SURVIVAL CONTRACT: pause at the step boundary,
-// deterministic replay, resume, and abandon after N failures. This ENVELOPS
-// `@convex-dev/workflow` -- it does not reimplement
-// durable execution. Every real unit of work (the caller-supplied
-// `stepFunctionHandle`) runs inside its own bounded mutation call; the
-// workflow persists `cursor` (steps [0, cursor) done) between calls, so a
-// job whose TOTAL wall-clock time exceeds a single Convex action's ceiling
-// still completes -- no single call has to survive past the ceiling, only
-// the aggregate progress does.
-//
-// Contract surface (this is what a consumer calls; see
-// examples/vantage-peers-long-task for a worked integration):
-//   1. `start`      -- enqueue a job of N steps, driven by a step function
-//                       the CALLER owns (created via `createFunctionHandle`
-//                       in the caller's own app). We never read the
-//                       caller's tables directly -- component isolation.
-//   2. `getStatus`  -- poll status/cursor/lastError/abandonedAtStep.
-//   3. `cancel`     -- best-effort stop (checked at the next step boundary
-//                       and by the workflow's own cancel()).
-//   4. (internal) the workflow itself is the pause/resume/replay engine:
-//       - PAUSE AT STEP BOUNDARY: each loop iteration is one workflow step;
-//         `@convex-dev/workflow` durably persists after each step returns,
-//         so the process can die between any two steps with zero data loss.
-//       - DETERMINISTIC REPLAY: `runStepInternal` is idempotent -- it
-//         no-ops for any stepIndex < job.cursor, so replaying the workflow
-//         handler after a resume never re-runs completed work.
-//       - RESUME: on restart, the workflow replays its journal up to the
-//         last completed step then continues the same in-memory loop; our
-//         `cursor` on the `durableJobs` row is the second, redundant source
-//         of truth a caller can poll without touching workflow internals.
-//       - ABANDON AFTER N: `runStepInternal` retries the caller's step
-//         function up to `maxAttemptsPerStep` times INSIDE one workflow
-//         step (not via workflow-level retry, which does not apply to
-//         mutations); only once attempts are exhausted does the step throw,
-//         which the workflow handler catches and turns into
-//         `status: "abandoned"` with `abandonedAtStep` + `lastError`.
-//
-// Versioned workflow discipline (workflow#35) -- same as
-// `engine/workflows.ts:sessionWorkflowV1`: never edit `durableJobWorkflowV1`
-// in place once jobs reference it; ship `...V2` and drain v1 first.
-const CURRENT_WORKFLOW_VERSION = "v1";
+import { requireOrgId } from "../lib/auth.js";
+import { appendEventCore, legacyJobOf, loadRun, mirrorToRun, openLegacyRun, } from "./world.js";
+const CURRENT_WORKFLOW_VERSION = "v2";
+async function readJob(ctx, orgId, runId, notFoundMessage = "Job not found") {
+    const run = await loadRun(ctx, orgId, runId, "durableJobs", notFoundMessage);
+    const num = (field) => {
+        const value = run.created[field];
+        if (typeof value !== "number") {
+            throw new Error(`Job run_created payload is missing ${field}`);
+        }
+        return value;
+    };
+    const stepHandle = run.created.stepFunctionHandle;
+    if (typeof stepHandle !== "string") {
+        throw new Error("Job run_created payload is missing stepFunctionHandle");
+    }
+    const steps = await ctx.db
+        .query("worldSteps")
+        .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", runId))
+        .collect();
+    return {
+        run,
+        totalSteps: num("totalSteps"),
+        maxAttemptsPerStep: num("maxAttemptsPerStep"),
+        stepFunctionHandle: stepHandle,
+        cursor: steps.filter((s) => s.status === "completed").length,
+    };
+}
+function publicStatus(status) {
+    return status === "failed" ? "abandoned" : status;
+}
 export const workflow = new WorkflowManager(components.workflow);
-// ---------------------------------------------------------------------
-// PUBLIC CONTRACT
-// ---------------------------------------------------------------------
 export const start = mutation({
     args: {
         orgId: v.string(),
@@ -56,7 +42,7 @@ export const start = mutation({
         totalSteps: v.number(),
         maxAttemptsPerStep: v.number(),
     },
-    returns: v.id("durableJobs"),
+    returns: v.string(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
         if (!Number.isInteger(args.totalSteps) || args.totalSteps <= 0) {
@@ -70,7 +56,7 @@ export const start = mutation({
             throw new Error("Validation: stepFunctionHandle must not be empty");
         }
         const now = Date.now();
-        const jobId = await ctx.db.insert("durableJobs", {
+        const legacyJobId = await ctx.db.insert("durableJobs", {
             orgId,
             kind: args.kind,
             stepFunctionHandle: args.stepFunctionHandle,
@@ -82,13 +68,25 @@ export const start = mutation({
             createdAt: now,
             updatedAt: now,
         });
-        const workflowId = await workflow.start(ctx, internal.engine.durableJob.durableJobWorkflowV1, { jobId });
-        await ctx.db.patch(jobId, { workflowId });
-        return jobId;
+        const runId = await openLegacyRun(ctx, {
+            orgId,
+            table: "durableJobs",
+            legacyId: legacyJobId,
+            data: {
+                kind: args.kind,
+                stepFunctionHandle: args.stepFunctionHandle,
+                totalSteps: args.totalSteps,
+                maxAttemptsPerStep: args.maxAttemptsPerStep,
+                workflowVersion: CURRENT_WORKFLOW_VERSION,
+            },
+        });
+        const workflowId = await workflow.start(ctx, internal.engine.durableJob.durableJobWorkflowV2, { orgId, runId });
+        await ctx.db.patch(legacyJobId, { workflowId });
+        return runId;
     },
 });
 export const getStatus = query({
-    args: { orgId: v.string(), jobId: v.id("durableJobs") },
+    args: { orgId: v.string(), jobId: v.string() },
     returns: v.object({
         status: v.union(v.literal("running"), v.literal("completed"), v.literal("abandoned"), v.literal("cancelled")),
         cursor: v.number(),
@@ -98,42 +96,65 @@ export const getStatus = query({
     }),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const job = await ctx.db.get(args.jobId);
-        assertSameOrg(orgId, job, "Job not found");
+        const job = await readJob(ctx, orgId, args.jobId);
+        const status = publicStatus(job.run.status);
+        let lastError;
+        let abandonedAtStep;
+        if (job.run.status === "failed") {
+            const journal = await ctx.db
+                .query("worldEvents")
+                .withIndex("by_org_run_seq", (q) => q.eq("orgId", orgId).eq("runId", job.run.runId))
+                .collect();
+            const failed = [...journal].reverse().find((e) => e.eventType === "run_failed");
+            if (failed) {
+                try {
+                    const data = JSON.parse(failed.dataJson);
+                    if (typeof data.lastError === "string")
+                        lastError = data.lastError;
+                    if (typeof data.abandonedAtStep === "number") {
+                        abandonedAtStep = data.abandonedAtStep;
+                    }
+                }
+                catch {
+                }
+            }
+        }
         return {
-            status: job.status,
+            status,
             cursor: job.cursor,
             totalSteps: job.totalSteps,
-            lastError: job.lastError,
-            abandonedAtStep: job.abandonedAtStep,
+            lastError,
+            abandonedAtStep,
         };
     },
 });
 export const cancel = mutation({
-    args: { orgId: v.string(), jobId: v.id("durableJobs") },
+    args: { orgId: v.string(), jobId: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
-        const job = await ctx.db.get(args.jobId);
-        assertSameOrg(orgId, job, "Job not found");
-        if (job.status !== "running")
+        const run = await loadRun(ctx, orgId, args.jobId, "durableJobs", "Job not found");
+        if (run.status !== "running")
             return null;
-        await ctx.db.patch(args.jobId, {
-            status: "cancelled",
-            updatedAt: Date.now(),
+        await appendEventCore(ctx, {
+            orgId,
+            runId: run.runId,
+            eventType: "run_cancelled",
+            dataJson: "{}",
         });
-        if (job.workflowId) {
-            await workflow.cancel(ctx, job.workflowId);
+        const legacy = await legacyJobOf(ctx, run, orgId);
+        if (legacy !== null) {
+            await ctx.db.patch(legacy._id, {
+                status: "cancelled",
+                updatedAt: Date.now(),
+            });
+            if (legacy.workflowId) {
+                await workflow.cancel(ctx, legacy.workflowId);
+            }
         }
         return null;
     },
 });
-// ---------------------------------------------------------------------
-// INTERNAL — server-to-server only, invoked by the workflow's own steps.
-// The workflow runs with no end-user identity: every handler below scopes
-// strictly by the orgId already recorded on the `durableJobs` row, never a
-// client-supplied one.
-// ---------------------------------------------------------------------
 export const getJobInternal = internalQuery({
     args: { jobId: v.id("durableJobs") },
     returns: v.union(v.object({
@@ -154,12 +175,6 @@ export const getJobInternal = internalQuery({
         };
     },
 });
-// The one real unit of work per step-boundary. DETERMINISTIC REPLAY GUARD:
-// no-ops for any stepIndex already covered by job.cursor, so a workflow
-// resume (journal replay after a kill mid-run) never re-executes the
-// caller's step function for completed steps. ABANDON AFTER N: retries the
-// caller's step function up to `maxAttemptsPerStep` times before throwing
-// (throwing is what the workflow handler below turns into "abandoned").
 export const runStepInternal = internalMutation({
     args: { jobId: v.id("durableJobs"), stepIndex: v.number() },
     returns: v.null(),
@@ -170,9 +185,23 @@ export const runStepInternal = internalMutation({
         if (job.status === "cancelled")
             return null;
         if (args.stepIndex < job.cursor) {
-            // Already-completed step replayed by a resumed workflow -- no-op.
             return null;
         }
+        const stepId = String(args.stepIndex);
+        await mirrorToRun(ctx, {
+            orgId: job.orgId,
+            table: "durableJobs",
+            legacyId: args.jobId,
+            eventType: "step_created",
+            stepId,
+        });
+        await mirrorToRun(ctx, {
+            orgId: job.orgId,
+            table: "durableJobs",
+            legacyId: args.jobId,
+            eventType: "step_started",
+            stepId,
+        });
         let lastError;
         for (let attempt = 1; attempt <= job.maxAttemptsPerStep; attempt++) {
             try {
@@ -181,6 +210,14 @@ export const runStepInternal = internalMutation({
                     cursor: args.stepIndex + 1,
                     updatedAt: Date.now(),
                 });
+                await mirrorToRun(ctx, {
+                    orgId: job.orgId,
+                    table: "durableJobs",
+                    legacyId: args.jobId,
+                    eventType: "step_completed",
+                    stepId,
+                    dataJson: JSON.stringify({ attempt }),
+                });
                 return null;
             }
             catch (err) {
@@ -205,6 +242,33 @@ export const markAbandonedInternal = internalMutation({
             lastError: args.error,
             updatedAt: Date.now(),
         });
+        const stepId = String(args.stepIndex);
+        await mirrorToRun(ctx, {
+            orgId: job.orgId,
+            table: "durableJobs",
+            legacyId: args.jobId,
+            eventType: "step_created",
+            stepId,
+        });
+        await mirrorToRun(ctx, {
+            orgId: job.orgId,
+            table: "durableJobs",
+            legacyId: args.jobId,
+            eventType: "step_failed",
+            stepId,
+            dataJson: JSON.stringify({ error: args.error }),
+        });
+        await mirrorToRun(ctx, {
+            orgId: job.orgId,
+            table: "durableJobs",
+            legacyId: args.jobId,
+            eventType: "run_failed",
+            dataJson: JSON.stringify({
+                reason: "abandoned",
+                abandonedAtStep: args.stepIndex,
+                lastError: args.error,
+            }),
+        });
         return null;
     },
 });
@@ -219,17 +283,15 @@ export const markCompletedInternal = internalMutation({
             status: "completed",
             updatedAt: Date.now(),
         });
+        await mirrorToRun(ctx, {
+            orgId: job.orgId,
+            table: "durableJobs",
+            legacyId: args.jobId,
+            eventType: "run_completed",
+        });
         return null;
     },
 });
-// durableJobWorkflowV1 -- the pause/resume/replay engine. One loop
-// iteration == one workflow step == one durability boundary: `step.
-// runMutation` returns only after `@convex-dev/workflow` has persisted the
-// journal entry, so a process kill between any two iterations loses zero
-// progress. On resume the workflow replays already-journaled steps from
-// its own history (no caller-visible effect, since runStepInternal is
-// idempotent below job.cursor) and continues the loop from where it left
-// off.
 export const durableJobWorkflowV1 = workflow.define({
     args: { jobId: v.id("durableJobs") },
     returns: v.null(),
@@ -261,3 +323,188 @@ export const durableJobWorkflowV1 = workflow.define({
         return null;
     },
 });
+export const getJobInternalV2 = internalQuery({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.union(v.object({
+        cursor: v.number(),
+        totalSteps: v.number(),
+        maxAttemptsPerStep: v.number(),
+        status: v.union(v.literal("running"), v.literal("completed"), v.literal("abandoned"), v.literal("cancelled")),
+    }), v.null()),
+    handler: async (ctx, args) => {
+        const run = await ctx.db
+            .query("worldRuns")
+            .withIndex("by_org_run", (q) => q.eq("orgId", args.orgId).eq("runId", args.runId))
+            .unique();
+        if (!run)
+            return null;
+        const job = await readJob(ctx, args.orgId, args.runId);
+        return {
+            cursor: job.cursor,
+            totalSteps: job.totalSteps,
+            maxAttemptsPerStep: job.maxAttemptsPerStep,
+            status: publicStatus(job.run.status),
+        };
+    },
+});
+export const runStepInternalV2 = internalMutation({
+    args: { orgId: v.string(), runId: v.string(), stepIndex: v.number() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const job = await readJob(ctx, args.orgId, args.runId);
+        if (job.run.status === "cancelled")
+            return null;
+        const stepId = String(args.stepIndex);
+        const existing = await ctx.db
+            .query("worldSteps")
+            .withIndex("by_org_run_step", (q) => q.eq("orgId", args.orgId).eq("runId", args.runId).eq("stepId", stepId))
+            .unique();
+        if (existing?.status === "completed")
+            return null;
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: args.runId,
+            eventType: "step_created",
+            stepId,
+            dataJson: "{}",
+        });
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: args.runId,
+            eventType: "step_started",
+            stepId,
+            dataJson: "{}",
+        });
+        let lastError;
+        for (let attempt = 1; attempt <= job.maxAttemptsPerStep; attempt++) {
+            try {
+                await ctx.runMutation(job.stepFunctionHandle, { orgId: args.orgId, jobId: args.runId, stepIndex: args.stepIndex });
+                const legacy = await legacyJobOf(ctx, job.run, args.orgId);
+                if (legacy !== null) {
+                    await ctx.db.patch(legacy._id, {
+                        cursor: args.stepIndex + 1,
+                        updatedAt: Date.now(),
+                    });
+                }
+                await appendEventCore(ctx, {
+                    orgId: args.orgId,
+                    runId: args.runId,
+                    eventType: "step_completed",
+                    stepId,
+                    dataJson: JSON.stringify({ attempt }),
+                });
+                return null;
+            }
+            catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new Error(String(lastError));
+    },
+});
+export const markAbandonedInternalV2 = internalMutation({
+    args: {
+        orgId: v.string(),
+        runId: v.string(),
+        stepIndex: v.number(),
+        error: v.string(),
+    },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const job = await readJob(ctx, args.orgId, args.runId);
+        if (job.run.status !== "running")
+            return null;
+        const legacy = await legacyJobOf(ctx, job.run, args.orgId);
+        if (legacy !== null) {
+            await ctx.db.patch(legacy._id, {
+                status: "abandoned",
+                abandonedAtStep: args.stepIndex,
+                lastError: args.error,
+                updatedAt: Date.now(),
+            });
+        }
+        const stepId = String(args.stepIndex);
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: args.runId,
+            eventType: "step_created",
+            stepId,
+            dataJson: "{}",
+        });
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: args.runId,
+            eventType: "step_failed",
+            stepId,
+            dataJson: JSON.stringify({ error: args.error }),
+        });
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: args.runId,
+            eventType: "run_failed",
+            dataJson: JSON.stringify({
+                reason: "abandoned",
+                abandonedAtStep: args.stepIndex,
+                lastError: args.error,
+            }),
+        });
+        return null;
+    },
+});
+export const markCompletedInternalV2 = internalMutation({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.null(),
+    handler: async (ctx, args) => {
+        const job = await readJob(ctx, args.orgId, args.runId);
+        if (job.run.status !== "running")
+            return null;
+        const legacy = await legacyJobOf(ctx, job.run, args.orgId);
+        if (legacy !== null) {
+            await ctx.db.patch(legacy._id, { status: "completed", updatedAt: Date.now() });
+        }
+        await appendEventCore(ctx, {
+            orgId: args.orgId,
+            runId: args.runId,
+            eventType: "run_completed",
+            dataJson: "{}",
+        });
+        return null;
+    },
+});
+export const durableJobWorkflowV2 = workflow.define({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.null(),
+    handler: async (step, args) => {
+        const job = await step.runQuery(internal.engine.durableJob.getJobInternalV2, {
+            orgId: args.orgId,
+            runId: args.runId,
+        });
+        if (!job || job.status !== "running")
+            return null;
+        for (let i = job.cursor; i < job.totalSteps; i++) {
+            try {
+                await step.runMutation(internal.engine.durableJob.runStepInternalV2, {
+                    orgId: args.orgId,
+                    runId: args.runId,
+                    stepIndex: i,
+                });
+            }
+            catch (err) {
+                await step.runMutation(internal.engine.durableJob.markAbandonedInternalV2, {
+                    orgId: args.orgId,
+                    runId: args.runId,
+                    stepIndex: i,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return null;
+            }
+        }
+        await step.runMutation(internal.engine.durableJob.markCompletedInternalV2, {
+            orgId: args.orgId,
+            runId: args.runId,
+        });
+        return null;
+    },
+});

package/dist/component/engine/mandates.js

@@ -4,26 +4,7 @@ import { ShardedCounter } from "@convex-dev/sharded-counter";
 import { internalMutation, mutation, query } from "../_generated/server.js";
 import { components } from "../_generated/api.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/mandates — "intentional divergence from Eve": BOUNDED AUTHORITY.
-// A mandate is a LINE OF DATA scoped
-// orgId+agentId+scope, never a constant read from code (litmus test: a
-// client changes their mind => zero deployment). The rate-limiter has NO
-// static named config in this module -- every call to `spend` builds its
-// `config` inline, dynamically, from the `mandates` row loaded from the
-// database (@convex-dev/rate-limiter README §"Define a rate limit inline /
-// dynamically"). Fails-closed: no mandate row => refusal, never a silent
-// bypass.
-//
-// orgId discipline (component/lib/auth.ts): every PUBLIC function takes
-// `orgId` as an explicit ARGUMENT (auth does not propagate across a
-// component boundary), same as the rest of this component (agents,
-// wakeup, sessions). `spendInternal` also takes `orgId` as an argument, but
-// is an `internalMutation` -- the ONLY caller reachable from any client is
-// `engine/wakeup.enqueue` (an action), which threads its own
-// caller-supplied `orgId` argument through after validating it.
 const rateLimiter = new RateLimiter(components.rateLimiter);
-// Usage rollup, keyed identically to the rate-limiter key (org+agent+scope).
-// internal research notes: counters via sharded-counter, never a canary/alpha dependency.
 const usageCounter = new ShardedCounter(components.shardedCounter);
 const mandateDoc = v.object({
     _id: v.id("mandates"),
@@ -38,9 +19,6 @@ const mandateDoc = v.object({
     createdAt: v.number(),
     updatedAt: v.number(),
 });
-// set — upserts the DATA row that bounds an agent's authority for a given
-// scope. This is the ONLY place a cap value is ever written; there is no
-// constant anywhere in the engine that plays this role.
 export const set = mutation({
     args: {
         orgId: v.string(),
@@ -101,25 +79,6 @@ export const get = query({
             .unique();
     },
 });
-// spend — the single choke point through which every costed action an
-// agent takes must pass. `cost` is a WEIGHTED count (tokens, euros, calls —
-// whatever the mandate's scope means), never a plain call counter.
-//
-// Deny by default, twice over:
-//   1. No mandate row for this org+agent+scope => throw immediately. We do
-//      NOT fall back to "unlimited"; an unconfigured mandate is a refusal,
-//      not an escape hatch. Nothing needs to be persisted for this case, so
-//      throwing (and rolling back the whole transaction) is safe.
-//   2. Mandate exists but is exhausted => an approvalRequests row MUST be
-//      committed. Convex mutations are single transactions: throwing after
-//      `ctx.db.insert` would roll the insert back along with everything
-//      else, silently destroying the very approval request the guard is
-//      supposed to leave behind. So this path returns `{ ok: false }`
-//      instead of throwing -- the approval row survives, and the caller
-//      (engine/wakeup) is REQUIRED to check `.ok` and treat `false` as a
-//      hard refusal. There is no code path that lets the action proceed
-//      past an exhausted mandate; the only way authority is restored is an
-//      explicit human `resolveApproval("approved")`.
 export const spend = mutation({
     args: {
         orgId: v.string(),
@@ -139,14 +98,6 @@ export const spend = mutation({
         return await spendCore(ctx, orgId, args);
     },
 });
-// spendInternal — SAME choke point as `spend`, INTERNAL ONLY (unreachable
-// from any client). This is the ONE function `engine/wakeup.enqueue` (an
-// `action`) calls, in its OWN transaction, before it may ever call
-// `enqueueInternal` to put work in the pool -- see the wiring note in
-// component/engine/wakeup.ts. Trusting an `orgId` argument here is exactly
-// as safe as `engine/wakeup.enqueueInternal` trusting one: the only code
-// that can reach an `internal.*` function is other server code, never a
-// client SDK. The public `spend` above is completely untouched.
 export const spendInternal = internalMutation({
     args: {
         orgId: v.string(),
@@ -174,7 +125,6 @@ async function spendCore(ctx, orgId, args) {
         .withIndex("by_org_agent_scope", (q) => q.eq("orgId", orgId).eq("agentId", args.agentId).eq("scope", args.scope))
         .unique();
     if (!mandate) {
-        // fails-closed: no data => no authority. Never silently unlimited.
         throw new Error(`Mandate refused: no mandate configured for scope "${args.scope}"`);
     }
     const key = `${orgId}:${args.agentId}:${args.scope}`;
@@ -189,10 +139,6 @@ async function spendCore(ctx, orgId, args) {
         },
     });
     if (!status.ok) {
-        // Overrun => a human approval request is created and PERSISTED
-        // (returning instead of throwing so the transaction commits it). This
-        // is the ONLY consequence of an overrun -- there is no code path that
-        // spends past an exhausted mandate.
         const approvalId = await ctx.db.insert("approvalRequests", {
             orgId,
             agentId: args.agentId,
@@ -204,8 +150,6 @@ async function spendCore(ctx, orgId, args) {
         });
         return { ok: false, approvalId };
     }
-    // Rollup via sharded-counter (internal research notes: no canary dependency for a
-    // guardrail). One shard bucket per org+agent+scope key.
     await usageCounter.add(ctx, key, args.cost);
     return { ok: true };
 }
@@ -235,8 +179,6 @@ export const listApprovals = query({
             : rows;
     },
 });
-// resolveApproval — the ONLY way an overrun ever becomes usable authority
-// again: an explicit human decision, recorded, never inferred.
 export const resolveApproval = mutation({
     args: {
         orgId: v.string(),
@@ -257,7 +199,6 @@ export const resolveApproval = mutation({
         return null;
     },
 });
-// usageCount — the rollup readout (sharded-counter), for dashboards/audits.
 export const usageCount = query({
     args: { orgId: v.string(), agentId: v.id("agents"), scope: v.string() },
     returns: v.number(),