@vantageos/agent-engine 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/component/convex.config.js

@@ -35,15 +35,14 @@ import crons from "@convex-dev/crons/convex.config";
 // awaitEventTimeouts, wakeableWork) is deliberately NOT yet re-hosted
 // here — porting those without a working component-level test harness
 // behind each of them would violate Day 128 (never ship unverified).
-// C3 (this pass): mandates ("notre ligne", autorité bornée) are now hosted
-// under this component boundary, following the exact same trio the
-// repo-root prototype used (I0 §3, `convex/convex.config.ts`) -- official
-// `@convex-dev/*` libraries only, NO canary/alpha dependency for a
-// guardrail: `rate-limiter` for the fails-closed spend gate itself,
-// `sharded-counter` for the usage rollup. See component/engine/mandates.ts.
-// C4 (this pass): habits ("notre ligne", un cron DYNAMIQUE par agent/org)
-// are now hosted under this component boundary, ported byte-identical from
-// the repo-root prototype (convex/habits.ts). `crons` is a sub-component of
+// Mandates (bounded, weighted spending authority per agent/org/scope) are
+// hosted under this component boundary, using official `@convex-dev/*`
+// libraries only -- no canary/alpha dependency for a guardrail:
+// `rate-limiter` for the fails-closed spend gate itself, `sharded-counter`
+// for the usage rollup. See component/engine/mandates.ts.
+// Habits (a dynamic, per-agent/org cron schedule editable at runtime) are
+// also hosted under this component boundary, ported byte-identical from the
+// repo-root prototype (convex/habits.ts). `crons` is a sub-component of
 // THIS component -- create/updateSchedule/enable/disable register or tear
 // down a runtime cron job via `@convex-dev/crons` inside the SAME Convex
 // mutation transaction that writes the `habits` row, so no habit schedule

package/dist/component/engine/awaitEventTimeout.js

@@ -4,15 +4,14 @@ import { internalMutation, mutation } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // engine/awaitEventTimeout — self-built timeout for step.awaitEvent
 // (workflow#177: "Convex does not provide a native timeout for
-// awaitEvent"). PORTED from convex/engine/awaitEventTimeout.ts (repo-root
-// prototype) into the component boundary (C2). We schedule a mutation that
+// awaitEvent"). We schedule a mutation that
 // fires a "blank" `sandbox.timeout` sessionEvent at the deadline; the
 // workflow's `awaitEvent` call is written to also accept this event name so
 // it wakes up even if the awaited event never arrives. Pattern:
 // maintainer's posted code in workflow#177, adapted to our sessionEvents
 // table.
 //
-// C2 MIGRATION NOTE ("notre ligne"): orgId is an EXPLICIT ARGUMENT on
+// NOTE ("intentional divergence from Eve"): orgId is an EXPLICIT ARGUMENT on
 // every public function, never derived from `ctx.auth` -- auth does NOT
 // propagate across a component boundary (component/lib/auth.ts). Also:
 // `sessionEvents.name`'s union in component/schema.ts did not previously

package/dist/component/engine/delegation.js

@@ -2,25 +2,23 @@ import { v } from "convex/values";
 import { api, internal } from "../_generated/api.js";
 import { action, internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/delegation — C6 (SYNTHESE.md §4.d): "un agent qui délègue à un
-// autre agent = LE MÊME système pause/réveil (awaitEvent/sendEvent) que le
-// pont sandbox -- un seul système à écrire, pas deux". Ported from
-// convex/engine/delegation.ts (repo-root prototype, I6) into the component
-// boundary (C6). Every delegation path below (declared subagent AND the
-// built-in `agent` clone tool) terminates in exactly ONE call to
-// `engine.wakeup.enqueue` -- the SAME public action C2/C3 already ships,
-// imported here and never reimplemented.
+// engine/delegation — an agent delegating to another agent uses THE SAME
+// pause/wake system (awaitEvent/sendEvent) as the sandbox bridge: one
+// system to maintain, not two. Every delegation path below (declared
+// subagent AND the built-in `agent` clone tool) terminates in exactly ONE
+// call to `engine.wakeup.enqueue` -- the same public action this component
+// already ships, imported here and never reimplemented.
 // grep proof: this file makes zero calls to `wakeupPool.*` / `workflow.*`
 // directly; the only wake-capable call in this module is
 // `api.engine.wakeup.enqueue` at the bottom of `delegateToSubagent` and
 // `invokeAgentClone`.
 //
-// C6 orgId discipline (component/lib/auth.ts): every PUBLIC function takes
+// 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 engine/mandates.ts (C3) / engine/wakeup.ts
-// (C2). `delegateToSubagent`/`invokeAgentClone` are `action`s because they
-// each call `api.engine.wakeup.enqueue` (itself an action, C3's two-
-// transaction funding protocol) -- `orgId` is threaded explicitly through
+// component boundary), same as engine/mandates.ts / engine/wakeup.ts.
+// `delegateToSubagent`/`invokeAgentClone` are `action`s because they each
+// call `api.engine.wakeup.enqueue` (itself an action: the two-transaction
+// funding protocol) -- `orgId` is threaded explicitly through
 // every hop, never relying on any identity propagation across the boundary.
 // Reserved tool name for the built-in, root-only, non-recursive clone tool
 // (eve.dev/docs/subagents). A declared subagent may never claim this name --
@@ -125,10 +123,10 @@ export const listSubagents = query({
 // (a.2) DELEGATION -- reuses `engine.wakeup.enqueue` end to end
 // ---------------------------------------------------------------------
 // delegateToSubagent — A delegates to a declared subagent B by the SAME
-// pause/réveil mechanism the sandbox bridge (C5) uses: it enqueues the
+// pause/wake mechanism the sandbox bridge uses: it enqueues the
 // caller-supplied `workFunctionHandle` (an action that performs B's turn)
 // through `api.engine.wakeup.enqueue`. That enqueue funds through
-// `mandates.spendInternal` (C3's own choke point, untouched), puts the work
+// `mandates.spendInternal` (the funding choke point, untouched), puts the work
 // into `wakeupPool`, and when it resolves, `engine.wakeup.onWorkComplete`
 // calls `workflow.sendEvent` (workflowId, awaitedEventName, ...) -- waking
 // whatever workflow step A's own session parked on `step.awaitEvent`. There
@@ -167,7 +165,7 @@ export const delegateToSubagent = action({
             awaitedEventName: args.awaitedEventName,
         });
         // THE reuse point: no bespoke pause/wake code below this line -- this
-        // is a direct call into C2/C3's own PUBLIC `engine.wakeup.enqueue`
+        // is a direct call into this component's own PUBLIC `engine.wakeup.enqueue`
         // action. `orgId` is threaded explicitly (no identity propagation
         // across the component boundary).
         await ctx.runAction(api.engine.wakeup.enqueue, {

package/dist/component/engine/directory.js

@@ -2,7 +2,7 @@ import { v } from "convex/values";
 import { query } from "../_generated/server.js";
 import { requireOrgId } from "../lib/auth.js";
 // engine/directory — component-boundary port of the app-level
-// `convex/directory.ts:listByOrg` (M-COMPLETION C1, VP k1717xyrn25n99h6j10m48f1jx8akg6v).
+// `convex/directory.ts:listByOrg`.
 //
 // Trust-boundary divergence from the app-level prototype (see
 // component/lib/auth.ts): auth does NOT propagate across a component

package/dist/component/engine/durableJob.js

@@ -3,9 +3,9 @@ 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 (I1, SYNTHESE.md §5/§7): "mise en
-// pause à la frontière d'étape, rejeu déterministe, reprise, abandon après
-// N échecs." This ENVELOPS `@convex-dev/workflow` -- it does not reimplement
+// 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
@@ -13,8 +13,8 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // still completes -- no single call has to survive past the ceiling, only
 // the aggregate progress does.
 //
-// Contract surface (this is what a consumer -- VantagePeers/Sigma first --
-// calls; see examples/vantage-peers-long-task for a worked integration):
+// 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
@@ -40,7 +40,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 //         which the workflow handler catches and turns into
 //         `status: "abandoned"` with `abandonedAtStep` + `lastError`.
 //
-// Versioned workflow discipline (workflow#35, I0 §7.1) -- same as
+// 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";

package/dist/component/engine/habits.js

@@ -3,17 +3,16 @@ import { Crons } from "@convex-dev/crons";
 import { internal, components } from "../_generated/api.js";
 import { internalMutation, mutation, query } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/habits — NOTRE LIGNE (SYNTHESE §2/§4.e-ter: "ce qui transforme un
-// chat en employé"). Une habitude = un cron DYNAMIQUE par agent/org,
-// enregistré à l'exécution via @convex-dev/crons — jamais un
-// `convex/crons.ts` statique. Créer / exécuter / modifier / désactiver ne
-// redéploient jamais rien : le `cronExpression` est une DONNÉE portée par
-// la ligne `habits`, le cron runtime en est un simple reflet. Ported from
-// convex/habits.ts (repo-root prototype) into the component boundary (C4).
+// engine/habits — "intentional divergence from Eve": a habit is what turns
+// a chat into an employee. A habit is a DYNAMIC cron per agent/org,
+// registered at runtime via @convex-dev/crons — never a static
+// `convex/crons.ts`. Creating, running, editing or disabling one deploys
+// nothing: the `cronExpression` is DATA carried by the `habits` row, and
+// the runtime cron is merely a reflection of it.
 //
-// C4 orgId discipline (component/lib/auth.ts): every PUBLIC function takes
+// 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 engine/mandates.ts (C3). The cron runtime
+// component boundary), same as engine/mandates.ts. The cron runtime
 // target is `internal.engine.habits.run` -- the component-boundary path
 // for this module, mirroring `internal.habits.run` at the app level.
 const crons = new Crons(components.crons);

package/dist/component/engine/mandates.js

@@ -4,9 +4,8 @@ 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 — NOTRE LIGNE (SYNTHESE §2 / §4.e-ter) : « autorité
-// bornée ». Ported from convex/mandates.ts (repo-root prototype) into the
-// component boundary (C3). A mandate is a LINE OF DATA scoped
+// 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
@@ -15,7 +14,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // dynamically"). Fails-closed: no mandate row => refusal, never a silent
 // bypass.
 //
-// C3 orgId discipline (component/lib/auth.ts): every PUBLIC function takes
+// 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
@@ -24,7 +23,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // 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).
-// I0 §7.4: counters via sharded-counter, never a canary/alpha dependency.
+// 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"),
@@ -143,7 +142,7 @@ export const spend = mutation({
 // 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 C3 wiring note in
+// `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
@@ -205,7 +204,7 @@ async function spendCore(ctx, orgId, args) {
         });
         return { ok: false, approvalId };
     }
-    // Rollup via sharded-counter (I0 §7.4: no canary dependency for a
+    // 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 };

package/dist/component/engine/sandboxCallback.js

@@ -3,12 +3,10 @@ import { v } from "convex/values";
 import { components, internal } from "../_generated/api.js";
 import { internalMutation, mutation, query } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/sandboxCallback — C5: THE SIGNED CALLBACK GATE'S DB-SIDE LOGIC,
-// PORTED from convex/engine/sandboxCallback.ts (repo-root prototype, I5,
-// SYNTHESE.md §4.c-d, i0-research §8/§5) into the component boundary.
+// engine/sandboxCallback — THE SIGNED CALLBACK GATE'S DB-SIDE LOGIC.
 //
-// NOTRE LIGNE (C5 recherche-d'abord, see component/schema.ts's C5 header
-// comment for the measured verdict + citations):
+// BOUNDARY (see the sandbox-bridge header in component/schema.ts for the
+// measured verdict behind each of these):
 //   - The public HTTP route (`/sandbox/callback`) that verifies the
 //     `SANDBOX_CALLBACK_SECRET` HMAC signature over the raw body CANNOT
 //     live in this component (no official `@convex-dev/*` component ships
@@ -20,12 +18,11 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 //     (`Sandbox.create()` / `sandbox.runCommand()`) CANNOT live in this
 //     component either (Convex's own bundler hard-crashes on any "use
 //     node" file inside a child component). It stays app-level
-//     (convex/engine/sandboxBridgeActions.ts) and calls INTO `startRun` /
-//     `attachSandboxId` below (both PUBLIC `mutation`s, not
-//     `internalMutation`s, precisely so a cross-component caller can reach
-//     them — a component's `internal*` functions are unreachable from
-//     outside the component, see component/engine/mandates.ts's
-//     `spendInternal` for the same convention already established in C3).
+//     and calls INTO `startRun` / `attachSandboxId` below (both PUBLIC
+//     `mutation`s, not `internalMutation`s, precisely so a cross-component
+//     caller can reach them — a component's `internal*` functions are
+//     unreachable from outside the component; engine/mandates.ts's
+//     `spendInternal` follows the same convention).
 //
 // Everything below assumes the signature already checked out (verified by
 // the caller, upstream of this module) — this module's job is dedup-by-

package/dist/component/engine/sessions.js

@@ -29,12 +29,11 @@ const CURRENT_SESSION_WORKFLOW_VERSION = "v1";
 // manifest immediately so a caller can act on it before the first turn,
 // then STARTS the durable, versioned session workflow
 // (engine/workflows.ts:sessionWorkflowV1) that pilots this session from
-// here on (C1.5 -- retires the T2-QUINQUIES "sessions are just an event
-// table" divergence).
+// here on.
 //
-// RETURN CONTRACT ("notre ligne", C1.5): `start` now returns
+// RETURN CONTRACT ("intentional divergence from Eve"): `start` returns
 // `{ sessionId, workflowId }` instead of a bare `sessionId`. A bare ID
-// return was the pre-C1.5 shape when no workflow existed to reference;
+// would be the shape for a session with no workflow to reference;
 // once a session IS piloted by a real, durable workflow run, silently
 // dropping that run's id would make it unobservable/uncancellable to
 // every caller except one that re-reads the session row. Returning both
@@ -45,7 +44,7 @@ const CURRENT_SESSION_WORKFLOW_VERSION = "v1";
 export const start = mutation({
     args: { orgId: v.string(), agentId: v.id("agents"), createdBy: v.string() },
     returns: v.object({ sessionId: v.id("sessions"), workflowId: v.string() }),
-    // EXPLICIT return-type annotation ("notre ligne" -- Convex pattern for
+    // EXPLICIT return-type annotation ("intentional divergence from Eve" -- Convex pattern for
     // any handler that references `components`/a WorkflowManager built on
     // `components.workflow`): `workflow.start` closes over `components`,
     // which closes back over this component's own generated `api` --
@@ -55,7 +54,7 @@ export const start = mutation({
     // `.d.ts` EMISSION (declaration:true, tsconfig.build.json) fails --
     // TS2502/TS2615/TS7022 -- even though `tsc --noEmit` at the repo root
     // stays green (noEmit skips the exact codepath that breaks). Measured
-    // on PR #13 (Eta gate): `npm run build` is the build that SHIPS; a
+    // on PR #13 (build gate review): `npm run build` is the build that SHIPS; a
     // green `tsc --noEmit` is not sufficient proof by itself.
     handler: async (ctx, args) => {
         const orgId = requireOrgId(args.orgId);
@@ -188,8 +187,8 @@ export const requestToolCall = mutation({
         // approval === "once": gate unless this tool's approval was already
         // resolved with `decision: "approved"` in this session. A prior
         // `decision: "denied"` resolution must NOT be treated as
-        // authorization (that was the pre-alpha.5 bug -- "outil sauté, tour
-        // complété quand même") -- it is reported back as a terminal refusal
+        // authorization (the tool would be skipped while the turn still
+        // completed) -- it is reported back as a terminal refusal
         // instead, and the caller re-requests (a fresh human decision) rather
         // than silently proceeding.
         const events = await ctx.db
@@ -272,7 +271,7 @@ export const listEvents = query({
         _id: v.id("sessionEvents"),
         _creationTime: v.number(),
         name: v.union(v.literal("session.started"), v.literal("turn.started"), v.literal("turn.reasoning"), v.literal("turn.toolCall.requested"), v.literal("turn.toolCall.completed"), v.literal("turn.toolCall.denied"), v.literal("turn.completed"), v.literal("tool.approval.requested"), v.literal("tool.approval.resolved"), 
-        // C2 — blank event auto-inserted by
+        // Blank event auto-inserted by
         // `engine/awaitEventTimeout.fire` (workflow#177).
         v.literal("sandbox.timeout")),
         payload: v.optional(v.string()),

package/dist/component/engine/toolApprovals.js

@@ -10,7 +10,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 //   1. `decision` -- the RESPONSE to THIS ONE pending approval request,
 //      for THIS turn only. Vocabulary aligned with Eve's `ApprovalStatus`
 //      (packages/eve/src/public/definitions/approval.ts: "approved" |
-//      "denied" | ...) -- eve parity, cited verbatim, not "notre ligne".
+//      "denied" | ...) -- eve parity, cited verbatim, not "intentional divergence from Eve".
 //      `"denied"` means: this turn's tool call is refused, full stop. It
 //      does NOT change the agent's standing policy for the tool, and it
 //      must NOT be interpreted as "tool skipped, turn completed anyway" --

package/dist/component/engine/vpConnection.js

@@ -2,22 +2,19 @@ import { v } from "convex/values";
 import { action, internalMutation, internalQuery, mutation, query, } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 import { internal } from "../_generated/api.js";
-// engine/vpConnection — C6 (I6.b), mvp-evevantage.md §2.2 "Travail
-// d'équipe". Ported from convex/engine/vpConnection.ts (repo-root
-// prototype) into the component boundary (C6). The four VantagePeers tools
+// engine/vpConnection — teamwork. The four VantagePeers tools
 // (memory, tasks, messages, notes) are wired as a CONNECTION of the agent
-// aggregate -- notre ligne, same slot family as `connections` (MCP/OpenAPI).
+// aggregate -- intentional divergence from Eve, same slot family as `connections` (MCP/OpenAPI).
 // Four toggles, ON by default.
 //
 // DIRECT ACCESS, NO NETWORK IN THE HOT PATH: `invokeVpTool` dispatches via a
 // caller-supplied Convex function handle (`createFunctionHandle`), the same
 // discipline `engine/wakeup.ts` and `engine/durableJob.ts` already use for
 // `workFunctionHandle` / `stepFunctionHandle` -- an in-process function
-// reference resolved by `ctx.runMutation`, never an HTTP request. grep proof
-// (cited in the PR/README): this file contains zero occurrences of the
-// literal fetch call.
+// reference resolved by `ctx.runMutation`, never an HTTP request: this file
+// contains zero occurrences of the literal fetch call.
 //
-// C6 orgId discipline (component/lib/auth.ts): every PUBLIC function takes
+// orgId discipline (component/lib/auth.ts): every PUBLIC function takes
 // `orgId` as an explicit ARGUMENT (auth does not propagate across a
 // component boundary). `orgId` is passed EXPLICITLY to the target function
 // handle (never trusting the target's own `ctx.auth`) -- this is the
@@ -25,7 +22,7 @@ import { internal } from "../_generated/api.js";
 // is expected to write scoped to the `orgId` it was HANDED, not to derive
 // one itself.
 const vpTool = v.union(v.literal("memory"), v.literal("tasks"), v.literal("messages"), v.literal("notes"));
-// defaultToggles — mvp §2.2: "quatre interrupteurs cochés par défaut". A
+// defaultToggles — four switches, all ticked by default. A
 // missing `vpConnections` row means "use these defaults", so every agent
 // starts with all four VP tools available with zero extra setup.
 export const defaultToggles = {

package/dist/component/engine/wakeup.js

@@ -4,17 +4,16 @@ import { WorkflowManager } from "@convex-dev/workflow";
 import { components, internal } from "../_generated/api.js";
 import { action, internalMutation, mutation, query } from "../_generated/server.js";
 import { assertSameOrg, requireOrgId } from "../lib/auth.js";
-// engine/wakeup — THE GENERIC WAKE-UP PRIMITIVE (I2, SYNTHESE.md §5: "Adam
-// ne demande pas toutes les minutes s'il y a du travail -- il est réveillé
-// quand du travail arrive"). PORTED from convex/engine/wakeup.ts (repo-root
-// prototype) into the component boundary (C2). Mechanism: `enqueue` puts
-// caller-supplied work (an action, referenced by an opaque handle string
+// engine/wakeup — THE GENERIC WAKE-UP PRIMITIVE. An agent does not ask every
+// minute whether work has arrived: it is woken the instant the work resolves.
+// Mechanism: `enqueue` puts caller-supplied work (an action, referenced by
+// an opaque handle string
 // from `createFunctionHandle` in the CALLER's own app, same
 // component-isolation discipline as `durableJob.stepFunctionHandle`) into a
 // dedicated `@convex-dev/workpool` (`components.wakeupPool`, declared in
 // component/convex.config.ts). That pool's `onComplete` callback -- which
-// fires in its OWN transaction once the work resolves (I0 §2: "onComplete
-// en transaction séparée, pas de pause native", workpool issue #133) --
+// fires in its OWN transaction once the work resolves (workpool issue #133:
+// onComplete runs in a separate transaction; there is no native pause) --
 // calls `workflow.sendEvent(...)` against the CALLER-supplied
 // `workflowId`. Any workflow step parked on
 // `step.awaitEvent({ name: awaitedEventName })` resumes the INSTANT that
@@ -28,7 +27,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // of those tables.
 //
 // ---------------------------------------------------------------------
-// C2 MIGRATION NOTES ("notre ligne")
+// "intentional divergence from Eve"
 // ---------------------------------------------------------------------
 //
 // (A) orgId is an EXPLICIT ARGUMENT on every public function, never derived
@@ -36,7 +35,7 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 // (see component/lib/auth.ts). The consumer app has already authenticated
 // its caller and resolved orgId on its OWN side before calling in.
 //
-// (B) C3: MANDATE FUNDING CHOKE-POINT IS NOW WIRED. `enqueue` is an
+// (B) MANDATE FUNDING CHOKE-POINT. `enqueue` is an
 // `action` because funding-then-starting is a TWO-TRANSACTION protocol a
 // single mutation cannot express: `mandates.spendInternal` must be able to
 // COMMIT an `approvalRequests` row on an overrun WITHOUT that commit being
@@ -54,13 +53,12 @@ import { assertSameOrg, requireOrgId } from "../lib/auth.js";
 //   4. only on `result.ok === true` does it call `enqueueInternal` in a
 //      SECOND transaction to actually put the work in the pool.
 // There is no code path from "client wants work started" to "work enters
-// the pool" that does not pass through step 2 -- this is the "argument you
-// cannot fabricate" form (Pi/Sigma, T4 lesson): the only way to make
+// the pool" that does not pass through step 2 -- this is an "argument you
+// cannot fabricate" pattern: the only way to make
 // `enqueueInternal` run at all is to be `enqueue` itself, and `enqueue`
-// always calls `mandates.spendInternal` first. Mirrors the app-level
-// pre-C2 prototype (`convex/engine/wakeup.ts`) exactly, adapted to the
-// orgId-argument discipline of this component boundary (`spendInternal`
-// takes `orgId` as an argument rather than deriving it from `ctx.auth`).
+// always calls `mandates.spendInternal` first. `spendInternal` takes
+// `orgId` as an argument rather than deriving it from `ctx.auth`, per the
+// boundary discipline in note A.
 export const wakeupPool = new Workpool(components.wakeupPool, {
     maxParallelism: 10,
 });
@@ -72,8 +70,8 @@ const workflow = new WorkflowManager(components.workflow);
 // ---------------------------------------------------------------------
 // PUBLIC CONTRACT
 // ---------------------------------------------------------------------
-// enqueue — the ONLY client-facing entry point (C3: now an `action`, see
-// note B above). Funds the work through `mandates.spendInternal` in its
+// enqueue — the ONLY client-facing entry point (an `action`, see note B
+// above). Funds the work through `mandates.spendInternal` in its
 // own transaction FIRST; only calls `enqueueInternal` (a second,
 // independent transaction) once that funding succeeded.
 export const enqueue = action({
@@ -119,9 +117,9 @@ export const enqueue = action({
         });
     },
 });
-// enqueueInternal -- INTERNAL ONLY variant, kept for the C3 two-transaction
-// protocol (a future funding `action` calls this in its SECOND transaction
-// once `mandates.spend` returned `{ ok: true }`, same split as the
+// enqueueInternal -- INTERNAL ONLY variant, kept for the two-transaction
+// funding protocol (`enqueue` calls this in its SECOND transaction
+// once `mandates.spendInternal` returned `{ ok: true }`, same split as the
 // app-level prototype). Unreachable from any client: Convex excludes
 // `internal.*` functions from the API surface shipped to clients.
 export const enqueueInternal = internalMutation({

package/dist/component/engine/workflows.js

@@ -2,12 +2,9 @@ import { WorkflowManager } from "@convex-dev/workflow";
 import { v } from "convex/values";
 import { components, internal } from "../_generated/api.js";
 import { internalMutation, internalQuery } from "../_generated/server.js";
-// C1.5 — porting the durable, VERSIONED session workflow into the
-// component boundary (ported from the repo-root prototype,
-// convex/engine/workflows.ts). This is what makes `sessions.start` open a
-// session PILOTED by `@convex-dev/workflow` instead of the T2-QUINQUIES
-// "sessions are just an event table" divergence (component/schema.ts,
-// sessions table comment retired alongside this file).
+// The durable, VERSIONED session workflow. This is what makes
+// `sessions.start` open a session PILOTED by `@convex-dev/workflow` rather
+// than a bare event table.
 //
 // Trust model at this boundary: the workflow engine runs with NO end-user
 // identity and NO client-supplied orgId (component isolation, same
@@ -53,7 +50,7 @@ export const recordTurnStartedInternal = internalMutation({
         return null;
     },
 });
-// Versioned workflow discipline (workflow#35, I0 §7.1): "if you change much
+// Versioned workflow discipline (workflow#35): "if you change much
 // of anything in a workflow while there are ongoing workflows, they'll
 // fail." We never edit a workflow function in place once sessions
 // reference it -- a breaking change ships as `sessionWorkflowV2`, and the