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

package/dist/component/engine/world.js

@@ -0,0 +1,665 @@
+import { v } from "convex/values";
+import { mutation, query, } from "../_generated/server.js";
+import { assertSameOrg, requireOrgId } from "../lib/auth.js";
+function pad26(n) {
+    return String(n).padStart(26, "0");
+}
+function slotToEventId(seq) {
+    return `evnt_${pad26(seq)}`;
+}
+function newRunId() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 14)}`;
+}
+const eventResult = v.object({
+    eventId: v.string(),
+    seq: v.number(),
+    runId: v.string(),
+    eventType: v.string(),
+    stepId: v.optional(v.string()),
+    hookId: v.optional(v.string()),
+    correlationId: v.optional(v.string()),
+    dataJson: v.string(),
+    createdAt: v.number(),
+});
+const runResult = v.object({
+    runId: v.string(),
+    status: v.union(v.literal("running"), v.literal("completed"), v.literal("failed"), v.literal("cancelled")),
+    eventCount: v.number(),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+const stepResult = v.object({
+    runId: v.string(),
+    stepId: v.string(),
+    status: v.union(v.literal("running"), v.literal("completed"), v.literal("failed")),
+    dataJson: v.optional(v.string()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+const hookResult = v.object({
+    runId: v.string(),
+    hookId: v.string(),
+    token: v.string(),
+    status: v.union(v.literal("pending"), v.literal("disposed")),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+});
+export async function appendEventCore(ctx, args) {
+    const orgId = requireOrgId(args.orgId);
+    const now = Date.now();
+    let runId = args.runId;
+    let runDoc;
+    if (runId === null) {
+        if (args.eventType !== "run_created") {
+            throw new Error("Validation: a null runId is only valid for a run_created event");
+        }
+        if (args.correlationId !== undefined) {
+            const correlationId = args.correlationId;
+            const prior = await ctx.db
+                .query("worldEvents")
+                .withIndex("by_org_correlation", (q) => q.eq("orgId", orgId).eq("correlationId", correlationId))
+                .collect();
+            const priorCreated = prior.find((e) => e.eventType === "run_created");
+            if (priorCreated) {
+                const existingRun = await ctx.db
+                    .query("worldRuns")
+                    .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", priorCreated.runId))
+                    .unique();
+                assertSameOrg(orgId, existingRun, "Run not found");
+                return {
+                    event: {
+                        eventId: slotToEventId(priorCreated.seq),
+                        seq: priorCreated.seq,
+                        runId: priorCreated.runId,
+                        eventType: priorCreated.eventType,
+                        stepId: priorCreated.stepId,
+                        hookId: priorCreated.hookId,
+                        correlationId: priorCreated.correlationId,
+                        dataJson: priorCreated.dataJson,
+                        createdAt: priorCreated.createdAt,
+                    },
+                    run: {
+                        runId: existingRun.runId,
+                        status: existingRun.status,
+                        eventCount: existingRun.eventCount,
+                        createdAt: existingRun.createdAt,
+                        updatedAt: existingRun.updatedAt,
+                    },
+                    step: null,
+                    hook: null,
+                };
+            }
+        }
+        runId = newRunId();
+        const runDocId = await ctx.db.insert("worldRuns", {
+            orgId,
+            runId,
+            status: "running",
+            eventCount: 0,
+            createdAt: now,
+            updatedAt: now,
+        });
+        runDoc = await ctx.db.get(runDocId);
+    }
+    else {
+        runDoc = await ctx.db
+            .query("worldRuns")
+            .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", runId))
+            .unique();
+        assertSameOrg(orgId, runDoc, "Run not found");
+    }
+    if (!runDoc) {
+        throw new Error("Run not found");
+    }
+    let stepAlreadyExists = false;
+    if (args.eventType === "step_created") {
+        if (!args.stepId) {
+            throw new Error("Validation: step_created/step_started requires stepId");
+        }
+        const existingStep = await ctx.db
+            .query("worldSteps")
+            .withIndex("by_org_run_step", (q) => q.eq("orgId", orgId).eq("runId", runId).eq("stepId", args.stepId))
+            .unique();
+        if (existingStep) {
+            assertSameOrg(orgId, existingStep, "Step not found");
+            stepAlreadyExists = true;
+            const journal = await ctx.db
+                .query("worldEvents")
+                .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", runId))
+                .collect();
+            const prior = journal.find((e) => e.eventType === "step_created" && e.stepId === args.stepId);
+            if (prior) {
+                return {
+                    event: {
+                        eventId: slotToEventId(prior.seq),
+                        seq: prior.seq,
+                        runId: prior.runId,
+                        eventType: prior.eventType,
+                        stepId: prior.stepId,
+                        hookId: prior.hookId,
+                        correlationId: prior.correlationId,
+                        dataJson: prior.dataJson,
+                        createdAt: prior.createdAt,
+                    },
+                    run: {
+                        runId: runDoc.runId,
+                        status: runDoc.status,
+                        eventCount: runDoc.eventCount,
+                        createdAt: runDoc.createdAt,
+                        updatedAt: runDoc.updatedAt,
+                    },
+                    step: {
+                        runId: existingStep.runId,
+                        stepId: existingStep.stepId,
+                        status: existingStep.status,
+                        dataJson: existingStep.dataJson,
+                        createdAt: existingStep.createdAt,
+                        updatedAt: existingStep.updatedAt,
+                    },
+                    hook: null,
+                };
+            }
+        }
+    }
+    const seq = runDoc.eventCount + 1;
+    const eventId = slotToEventId(seq);
+    await ctx.db.insert("worldEvents", {
+        orgId,
+        runId,
+        seq,
+        eventType: args.eventType,
+        stepId: args.stepId,
+        hookId: args.hookId,
+        correlationId: args.correlationId,
+        dataJson: args.dataJson,
+        createdAt: now,
+    });
+    await ctx.db.patch(runDoc._id, { eventCount: seq, updatedAt: now });
+    let stepDoc = null;
+    let hookDoc = null;
+    let finalRunDoc = { ...runDoc, eventCount: seq, updatedAt: now };
+    switch (args.eventType) {
+        case "step_created":
+        case "step_started": {
+            if (!args.stepId) {
+                throw new Error("Validation: step_created/step_started requires stepId");
+            }
+            const existingStep = await ctx.db
+                .query("worldSteps")
+                .withIndex("by_org_run_step", (q) => q.eq("orgId", orgId).eq("runId", runId).eq("stepId", args.stepId))
+                .unique();
+            if (existingStep && args.eventType === "step_started") {
+                assertSameOrg(orgId, existingStep, "Step not found");
+                await ctx.db.patch(existingStep._id, {
+                    status: "running",
+                    dataJson: args.dataJson,
+                    updatedAt: now,
+                });
+                stepDoc = await ctx.db.get(existingStep._id);
+                break;
+            }
+            if (stepAlreadyExists) {
+                stepDoc = await ctx.db
+                    .query("worldSteps")
+                    .withIndex("by_org_run_step", (q) => q.eq("orgId", orgId).eq("runId", runId).eq("stepId", args.stepId))
+                    .unique();
+                break;
+            }
+            const stepId = await ctx.db.insert("worldSteps", {
+                orgId,
+                runId,
+                stepId: args.stepId,
+                status: "running",
+                dataJson: args.dataJson,
+                createdAt: now,
+                updatedAt: now,
+            });
+            stepDoc = await ctx.db.get(stepId);
+            break;
+        }
+        case "step_completed":
+        case "step_failed": {
+            if (!args.stepId) {
+                throw new Error("Validation: step_completed/step_failed requires stepId");
+            }
+            const existing = await ctx.db
+                .query("worldSteps")
+                .withIndex("by_org_run_step", (q) => q.eq("orgId", orgId).eq("runId", runId).eq("stepId", args.stepId))
+                .unique();
+            assertSameOrg(orgId, existing, "Step not found");
+            await ctx.db.patch(existing._id, {
+                status: args.eventType === "step_completed" ? "completed" : "failed",
+                dataJson: args.dataJson,
+                updatedAt: now,
+            });
+            stepDoc = await ctx.db.get(existing._id);
+            break;
+        }
+        case "hook_created": {
+            if (!args.hookId) {
+                throw new Error("Validation: hook_created requires hookId");
+            }
+            const parsed = JSON.parse(args.dataJson);
+            if (!parsed.token) {
+                throw new Error("Validation: hook_created payload requires token");
+            }
+            const hookDocId = await ctx.db.insert("worldHooks", {
+                orgId,
+                runId,
+                hookId: args.hookId,
+                token: parsed.token,
+                status: "pending",
+                createdAt: now,
+                updatedAt: now,
+            });
+            hookDoc = await ctx.db.get(hookDocId);
+            break;
+        }
+        case "hook_disposed": {
+            if (!args.hookId) {
+                throw new Error("Validation: hook_disposed requires hookId");
+            }
+            const existing = await ctx.db
+                .query("worldHooks")
+                .withIndex("by_org_hook", (q) => q.eq("orgId", orgId).eq("hookId", args.hookId))
+                .unique();
+            assertSameOrg(orgId, existing, "Hook not found");
+            await ctx.db.delete(existing._id);
+            hookDoc = null;
+            break;
+        }
+        case "run_cancelled": {
+            await ctx.db.patch(runDoc._id, { status: "cancelled", updatedAt: now });
+            finalRunDoc = { ...finalRunDoc, status: "cancelled" };
+            break;
+        }
+        case "run_completed": {
+            await ctx.db.patch(runDoc._id, { status: "completed", updatedAt: now });
+            finalRunDoc = { ...finalRunDoc, status: "completed" };
+            break;
+        }
+        case "run_failed": {
+            await ctx.db.patch(runDoc._id, { status: "failed", updatedAt: now });
+            finalRunDoc = { ...finalRunDoc, status: "failed" };
+            break;
+        }
+        case "run_created":
+            break;
+        default:
+            break;
+    }
+    return {
+        event: {
+            eventId,
+            seq,
+            runId,
+            eventType: args.eventType,
+            stepId: args.stepId,
+            hookId: args.hookId,
+            correlationId: args.correlationId,
+            dataJson: args.dataJson,
+            createdAt: now,
+        },
+        run: {
+            runId: finalRunDoc.runId,
+            status: finalRunDoc.status,
+            eventCount: finalRunDoc.eventCount,
+            createdAt: finalRunDoc.createdAt,
+            updatedAt: finalRunDoc.updatedAt,
+        },
+        step: stepDoc
+            ? {
+                runId: stepDoc.runId,
+                stepId: stepDoc.stepId,
+                status: stepDoc.status,
+                dataJson: stepDoc.dataJson,
+                createdAt: stepDoc.createdAt,
+                updatedAt: stepDoc.updatedAt,
+            }
+            : null,
+        hook: hookDoc
+            ? {
+                runId: hookDoc.runId,
+                hookId: hookDoc.hookId,
+                token: hookDoc.token,
+                status: hookDoc.status,
+                createdAt: hookDoc.createdAt,
+                updatedAt: hookDoc.updatedAt,
+            }
+            : null,
+    };
+}
+export const appendEvent = mutation({
+    args: {
+        orgId: v.string(),
+        runId: v.union(v.string(), v.null()),
+        eventType: v.string(),
+        stepId: v.optional(v.string()),
+        hookId: v.optional(v.string()),
+        correlationId: v.optional(v.string()),
+        dataJson: v.string(),
+    },
+    returns: v.object({
+        event: eventResult,
+        run: v.union(runResult, v.null()),
+        step: v.union(stepResult, v.null()),
+        hook: v.union(hookResult, v.null()),
+    }),
+    handler: async (ctx, args) => {
+        if (args.correlationId?.startsWith("legacy:")) {
+            throw new Error("Validation: invalid correlationId");
+        }
+        return appendEventCore(ctx, args);
+    },
+});
+export function legacyCorrelationId(table, legacyId) {
+    return `legacy:${table}:${legacyId}`;
+}
+export async function findRunIdByCorrelation(ctx, orgId, correlationId) {
+    const events = await ctx.db
+        .query("worldEvents")
+        .withIndex("by_org_correlation", (q) => q.eq("orgId", orgId).eq("correlationId", correlationId))
+        .collect();
+    return events.find((e) => e.eventType === "run_created")?.runId ?? null;
+}
+export async function openLegacyRun(ctx, args) {
+    const result = await appendEventCore(ctx, {
+        orgId: args.orgId,
+        runId: null,
+        eventType: "run_created",
+        correlationId: legacyCorrelationId(args.table, args.legacyId),
+        dataJson: JSON.stringify(args.data),
+    });
+    return result.event.runId;
+}
+export async function mirrorToRun(ctx, args) {
+    const runId = await findRunIdByCorrelation(ctx, args.orgId, legacyCorrelationId(args.table, args.legacyId));
+    if (runId === null)
+        return false;
+    await appendEventCore(ctx, {
+        orgId: args.orgId,
+        runId,
+        eventType: args.eventType,
+        stepId: args.stepId,
+        dataJson: args.dataJson ?? "{}",
+    });
+    return true;
+}
+export async function loadRun(ctx, orgId, runId, kind, notFoundMessage) {
+    const run = await ctx.db
+        .query("worldRuns")
+        .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", runId))
+        .unique();
+    assertSameOrg(orgId, run, notFoundMessage);
+    const first = await ctx.db
+        .query("worldEvents")
+        .withIndex("by_org_run_seq", (q) => q.eq("orgId", orgId).eq("runId", runId).eq("seq", 1))
+        .unique();
+    const prefix = `legacy:${kind}:`;
+    if (!first ||
+        first.eventType !== "run_created" ||
+        first.correlationId === undefined ||
+        !first.correlationId.startsWith(prefix)) {
+        throw new Error(notFoundMessage);
+    }
+    let created = {};
+    try {
+        const parsed = JSON.parse(first.dataJson);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            created = parsed;
+        }
+    }
+    catch {
+        created = {};
+    }
+    const legacyId = first.correlationId.slice(prefix.length);
+    return {
+        runId: run.runId,
+        status: run.status,
+        eventCount: run.eventCount,
+        legacyId: legacyId.length > 0 ? legacyId : null,
+        created,
+    };
+}
+export async function legacySessionOf(ctx, run, orgId) {
+    if (run.legacyId === null)
+        return null;
+    const id = ctx.db.normalizeId("sessions", run.legacyId);
+    if (id === null)
+        return null;
+    const doc = await ctx.db.get(id);
+    return doc !== null && doc.orgId === orgId ? doc : null;
+}
+export async function legacyJobOf(ctx, run, orgId) {
+    if (run.legacyId === null)
+        return null;
+    const id = ctx.db.normalizeId("durableJobs", run.legacyId);
+    if (id === null)
+        return null;
+    const doc = await ctx.db.get(id);
+    return doc !== null && doc.orgId === orgId ? doc : null;
+}
+export function agentIdOfRun(ctx, run) {
+    const raw = run.created.agentId;
+    const id = typeof raw === "string" ? ctx.db.normalizeId("agents", raw) : null;
+    if (id === null)
+        throw new Error("Agent not found");
+    return id;
+}
+export function payloadOrUndefined(dataJson) {
+    return dataJson === "{}" ? undefined : dataJson;
+}
+export { slotToEventId };
+export const getRun = query({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.union(runResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldRuns")
+            .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", args.runId))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            return null;
+        }
+        return {
+            runId: doc.runId,
+            status: doc.status,
+            eventCount: doc.eventCount,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        };
+    },
+});
+export const listRuns = query({
+    args: { orgId: v.string() },
+    returns: v.array(runResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldRuns")
+            .withIndex("by_org", (q) => q.eq("orgId", orgId))
+            .collect();
+        return docs.map((doc) => ({
+            runId: doc.runId,
+            status: doc.status,
+            eventCount: doc.eventCount,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        }));
+    },
+});
+export const getStep = query({
+    args: { orgId: v.string(), runId: v.string(), stepId: v.string() },
+    returns: v.union(stepResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldSteps")
+            .withIndex("by_org_run_step", (q) => q.eq("orgId", orgId).eq("runId", args.runId).eq("stepId", args.stepId))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            return null;
+        }
+        return {
+            runId: doc.runId,
+            stepId: doc.stepId,
+            status: doc.status,
+            dataJson: doc.dataJson,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        };
+    },
+});
+export const listSteps = query({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.array(stepResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldSteps")
+            .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", args.runId))
+            .collect();
+        return docs.map((doc) => ({
+            runId: doc.runId,
+            stepId: doc.stepId,
+            status: doc.status,
+            dataJson: doc.dataJson,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        }));
+    },
+});
+export const getEvent = query({
+    args: { orgId: v.string(), runId: v.string(), eventId: v.string() },
+    returns: v.union(eventResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldEvents")
+            .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", args.runId))
+            .collect();
+        const doc = docs.find((d) => slotToEventId(d.seq) === args.eventId);
+        if (!doc || doc.orgId !== orgId) {
+            return null;
+        }
+        return {
+            eventId: slotToEventId(doc.seq),
+            seq: doc.seq,
+            runId: doc.runId,
+            eventType: doc.eventType,
+            stepId: doc.stepId,
+            hookId: doc.hookId,
+            correlationId: doc.correlationId,
+            dataJson: doc.dataJson,
+            createdAt: doc.createdAt,
+        };
+    },
+});
+export const listEvents = query({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.array(eventResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldEvents")
+            .withIndex("by_org_run_seq", (q) => q.eq("orgId", orgId).eq("runId", args.runId))
+            .collect();
+        return docs.map((doc) => ({
+            eventId: slotToEventId(doc.seq),
+            seq: doc.seq,
+            runId: doc.runId,
+            eventType: doc.eventType,
+            stepId: doc.stepId,
+            hookId: doc.hookId,
+            correlationId: doc.correlationId,
+            dataJson: doc.dataJson,
+            createdAt: doc.createdAt,
+        }));
+    },
+});
+export const listEventsByCorrelationId = query({
+    args: { orgId: v.string(), correlationId: v.string() },
+    returns: v.array(eventResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldEvents")
+            .withIndex("by_org_correlation", (q) => q.eq("orgId", orgId).eq("correlationId", args.correlationId))
+            .collect();
+        return docs.map((doc) => ({
+            eventId: slotToEventId(doc.seq),
+            seq: doc.seq,
+            runId: doc.runId,
+            eventType: doc.eventType,
+            stepId: doc.stepId,
+            hookId: doc.hookId,
+            correlationId: doc.correlationId,
+            dataJson: doc.dataJson,
+            createdAt: doc.createdAt,
+        }));
+    },
+});
+export const getHook = query({
+    args: { orgId: v.string(), hookId: v.string() },
+    returns: v.union(hookResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldHooks")
+            .withIndex("by_org_hook", (q) => q.eq("orgId", orgId).eq("hookId", args.hookId))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            return null;
+        }
+        return {
+            runId: doc.runId,
+            hookId: doc.hookId,
+            token: doc.token,
+            status: doc.status,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        };
+    },
+});
+export const getHookByToken = query({
+    args: { orgId: v.string(), token: v.string() },
+    returns: v.union(hookResult, v.null()),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const doc = await ctx.db
+            .query("worldHooks")
+            .withIndex("by_org_token", (q) => q.eq("orgId", orgId).eq("token", args.token))
+            .unique();
+        if (!doc || doc.orgId !== orgId) {
+            return null;
+        }
+        return {
+            runId: doc.runId,
+            hookId: doc.hookId,
+            token: doc.token,
+            status: doc.status,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        };
+    },
+});
+export const listHooks = query({
+    args: { orgId: v.string(), runId: v.string() },
+    returns: v.array(hookResult),
+    handler: async (ctx, args) => {
+        const orgId = requireOrgId(args.orgId);
+        const docs = await ctx.db
+            .query("worldHooks")
+            .withIndex("by_org_run", (q) => q.eq("orgId", orgId).eq("runId", args.runId))
+            .collect();
+        return docs.map((doc) => ({
+            runId: doc.runId,
+            hookId: doc.hookId,
+            token: doc.token,
+            status: doc.status,
+            createdAt: doc.createdAt,
+            updatedAt: doc.updatedAt,
+        }));
+    },
+});

package/dist/component/lib/auth.js

@@ -1,37 +1,11 @@
-// Trust model (CORRECTIF BLOQUANT, VP k1741evjzm72rj91tkcbdhpskx8ah35a):
-// Convex does NOT propagate the calling app's `ctx.auth` identity across a
-// component boundary -- this is a platform isolation guarantee, not a
-// choice this component makes (convex-test: "Auth doesn't propagate across
-// component boundaries"). A handler inside this component can therefore
-// NEVER read `ctx.auth.getUserIdentity()` and expect it to reflect the
-// consumer app's end user -- there is no such identity to read here.
-//
-// The consumer app has ALREADY authenticated its user and resolved their
-// orgId on ITS OWN side (e.g. Clerk org claim, read in the consumer's own
-// `ctx.auth`) before ever calling into this component. `orgId` is passed
-// as an explicit argument on every public function in this component.
-//
-// What does NOT change: this component still derives NOTHING from the
-// client beyond what the consumer's public API surface exposes, still
-// denies by default, and `orgId` is still the first field of every index
-// and is still enforced on every document read via `assertSameOrg` below
-// -- a caller-supplied `orgId` can never see another org's rows. The
-// isolation boundary moved from "component reads ctx.auth" (impossible
-// across a component boundary) to "component enforces the orgId the
-// consumer already vouches for"; the boundary itself -- deny by default,
-// orgId first, no cross-org reads -- is unchanged.
 export function requireOrgId(orgId) {
     if (!orgId || typeof orgId !== "string" || orgId.trim().length === 0) {
         throw new Error("Unauthenticated: caller did not supply a non-empty orgId");
     }
     return orgId;
 }
-// Throws unless the document's orgId matches the caller-supplied orgId.
-// Use on every read/write of a document fetched by _id, since db.get()
-// does not filter by index.
 export function assertSameOrg(callerOrgId, doc, notFoundMessage) {
     if (!doc || doc.orgId !== callerOrgId) {
-        // Same error for "not found" and "cross-org" -- do not leak existence.
         throw new Error(notFoundMessage);
     }
 }