@x12i/memorix-service 3.13.0 → 3.14.0

package/dist/writes/queued-write.js

@@ -0,0 +1,288 @@
+/**
+ * Queued content write (docs/async-content-write-FR.md).
+ *
+ * `queue: true` validates a row, stores one receipt in the operational database, and answers 202.
+ * The document is written later by the drain worker, in accept order for each storage key.
+ *
+ * The idempotency identity is storage key + run id + step id. Memorix derives it, keeps it in the
+ * receipt's `writeId`, and the existing unique `(orgId, caller, writeId)` index enforces it.
+ * "The same row" is the canonical content hash a synchronous write computes over the whole body:
+ * `data`, `_metadata`, `_audit` and the rest. The same tuple with any difference is `409 QUEUE_KEY_REUSED`.
+ */
+import { createHash } from "node:crypto";
+import { adoptRecordMetadata, canonicalJson, resolveContentInstanceFromDraft, resolveContentInstanceSelector, WriterError, } from "@x12i/memorix-data";
+import { ServiceError } from "../errors.js";
+import { normalizeWritePrecondition } from "../write-precondition.js";
+import { asServiceError, batchError, CONTENT_BATCH_LIMIT, prepareWrite, queuedBody, storageKey, } from "./content-write.js";
+import { newReceiptId, } from "./receipt-store.js";
+/**
+ * A new row is not applied for this long. A second accept for the same key may hold a lower accept
+ * number and still be on its way to the database. The wait lets it land first.
+ */
+export const QUEUE_SETTLE_MS = 500;
+const MAX_ID_LENGTH = 200;
+/** `queue` is absent, or a boolean. */
+export function readQueueFlag(value) {
+    if (value === undefined || value === null || value === false)
+        return false;
+    if (value === true)
+        return true;
+    throw new ServiceError("VALIDATION", "queue must be a boolean", 400, { field: "queue", retryable: false });
+}
+function validation(field, message) {
+    return new ServiceError("VALIDATION", message, 400, { field, retryable: false });
+}
+/** ACCEPT-03: what a queued write may not carry. */
+function assertQueueShape(body) {
+    if (body.writeId !== undefined && body.writeId !== null && body.writeId !== "") {
+        throw validation("writeId", "writeId is not used with queue: true. Memorix derives the idempotency key from the storage key, run id and step id.");
+    }
+    if (body.op !== undefined && body.op !== "upsert") {
+        throw validation("op", "a queued write is an upsert. patch, replace, add and remove use the synchronous write.");
+    }
+    if (body.precondition !== undefined && body.precondition !== null) {
+        const form = normalizeWritePrecondition(body.precondition, body.expectedRevision).form;
+        if (form !== "none") {
+            throw validation("precondition", `a queued write uses precondition none, not ${form}`);
+        }
+    }
+    if (body.expectedRevision !== undefined && body.expectedRevision !== null) {
+        throw validation("expectedRevision", "a queued write has no caller revision. Memorix assigns it.");
+    }
+    if (!body.record || typeof body.record !== "object" || Array.isArray(body.record)) {
+        throw validation("record", "record required");
+    }
+}
+function readExecutionId(execution, name) {
+    const field = `_metadata.execution.${name}`;
+    const value = execution[name];
+    if (typeof value !== "string" || !value.trim()) {
+        throw validation(field, `${field} is required with queue: true`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length > MAX_ID_LENGTH) {
+        throw validation(field, `${field} must be at most ${MAX_ID_LENGTH} characters`);
+    }
+    return trimmed;
+}
+/** Run id and step id, read after the fold a synchronous write applies to `properties` / `metadata` / `_metadata`. */
+function executionIds(record) {
+    const data = record.data && typeof record.data === "object" && !Array.isArray(record.data)
+        ? record.data
+        : {};
+    const folded = adoptRecordMetadata({ ...record, data });
+    const execution = folded._metadata?.execution;
+    if (!execution || typeof execution !== "object" || Array.isArray(execution)) {
+        throw validation("_metadata.execution", "_metadata.execution.runId and _metadata.execution.stepId are required with queue: true");
+    }
+    const bag = execution;
+    return { runId: readExecutionId(bag, "runId"), stepId: readExecutionId(bag, "stepId") };
+}
+function keyIdOf(objectType, contentType, address) {
+    return `${objectType}\u0000${contentType}\u0000${address}`;
+}
+/**
+ * The queue key of one stored-document address, or null when the address cannot be resolved
+ * (for example a discriminated content type read without its discriminator).
+ */
+export function queueKeyIdFor(catalog, args) {
+    try {
+        const address = resolveContentInstanceSelector({
+            recordId: args.recordId,
+            contentType: args.contentType,
+            discriminatorValue: args.discriminatorValue,
+            catalog,
+        });
+        return keyIdOf(args.objectType, args.contentType, address.storageKey);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The record a queued row will write, shaped like a stored read, minus the `revision` it does not have yet.
+ */
+export function pendingRecord(row) {
+    const record = structuredClone(row.request.record ?? {});
+    delete record.revision;
+    return record;
+}
+function addMs(iso, ms) {
+    return new Date(Date.parse(iso) + ms).toISOString();
+}
+function nowOf(deps) {
+    return (deps.now ?? (() => new Date().toISOString()))();
+}
+/** Validate the row and derive its identity. Nothing is stored. */
+function prepareQueued(deps, body, now) {
+    assertQueueShape(body);
+    const { queue: _queue, ...rest } = body;
+    void _queue;
+    const prepared = prepareWrite(deps, { ...rest, op: "upsert", precondition: "none" }, now);
+    const request = prepared.request;
+    const catalog = deps.ports.catalog;
+    const objectType = catalog.getObjectType(request.objectType);
+    if (!objectType) {
+        throw new WriterError("ROUTE_UNKNOWN_OBJECT_TYPE", `Unknown objectType ${request.objectType}`);
+    }
+    if (!objectType.contentTypes.includes(request.contentType)) {
+        throw new WriterError("ROUTE_UNKNOWN_CONTENT_TYPE", `contentType ${request.contentType} not allowed for ${request.objectType}`, { objectType: request.objectType, contentType: request.contentType, allowed: objectType.contentTypes });
+    }
+    if (catalog.getContentProfile && !catalog.getContentProfile(request.contentType)) {
+        throw new WriterError("METADATA_DESCRIPTOR_MISSING", `content type ${request.contentType} on ${request.objectType} has no descriptor; ensure the pack at startup before writing`, { objectType: request.objectType, contentType: request.contentType });
+    }
+    const resolved = resolveContentInstanceFromDraft(request.record, catalog);
+    const { runId, stepId } = executionIds(body.record);
+    const recordId = resolved.address.recordId;
+    const key = storageKey(resolved.address.kind === "discriminated"
+        ? { ...request, discriminatorValue: resolved.address.discriminatorValue }
+        : request, recordId);
+    const keyId = keyIdOf(request.objectType, request.contentType, resolved.address.storageKey);
+    const writeId = `queue:${createHash("sha256").update(canonicalJson({ keyId, runId, stepId })).digest("hex")}`;
+    return { prepared, identity: { keyId, runId, stepId, storageKey: key, writeId } };
+}
+/**
+ * Accept one row. 202 `queued`, or the answer for a repeat, or a rejection that stored nothing.
+ */
+export async function runQueuedWrite(deps, body) {
+    const now = nowOf(deps);
+    let prepared;
+    let identity;
+    try {
+        ({ prepared, identity } = prepareQueued(deps, body, now));
+        await deps.checkWrite?.(prepared.request);
+    }
+    catch (err) {
+        return { kind: "rejected", error: asServiceError(err) };
+    }
+    const seq = await deps.receipts.reserveSeq(deps.scope.orgId, 1);
+    const row = {
+        receiptId: newReceiptId(),
+        orgId: deps.scope.orgId,
+        caller: deps.caller,
+        writeId: identity.writeId,
+        contentHash: prepared.contentHash,
+        status: "queued",
+        request: prepared.request,
+        queue: {
+            seq,
+            keyId: identity.keyId,
+            runId: identity.runId,
+            stepId: identity.stepId,
+            storageKey: identity.storageKey,
+        },
+        attempts: 0,
+        nextAttemptAt: addMs(now, QUEUE_SETTLE_MS),
+        createdAt: now,
+        updatedAt: now,
+    };
+    const inserted = await deps.receipts.insert(row);
+    if (inserted === "inserted")
+        return { kind: "queued", httpStatus: 202, body: queuedBody(row) };
+    const existing = await deps.receipts.findByWriteId(deps.scope.orgId, deps.caller, identity.writeId);
+    if (existing)
+        return answerRepeat(existing, prepared.contentHash);
+    return {
+        kind: "rejected",
+        error: new ServiceError("WRITE_UNAVAILABLE", "the write queue could not record this row; send it again", 503, {
+            retryable: true,
+            retryAfterMs: 1_000,
+        }),
+    };
+}
+/** The same tuple again: the original receipt, or 409 when the row differs. */
+function answerRepeat(existing, contentHash) {
+    if (existing.contentHash !== contentHash) {
+        return {
+            kind: "rejected",
+            error: new ServiceError("QUEUE_KEY_REUSED", "this storage key, run id and step id was already accepted with different content. Send a correction under a new step id.", 409, { field: "stepId", retryable: false, receiptId: existing.receiptId }),
+        };
+    }
+    if (existing.status === "stored") {
+        return { kind: "stored", httpStatus: 200, body: publicQueuedReceipt(existing) };
+    }
+    if (existing.status === "queued" || existing.status === "pending") {
+        return { kind: "queued", httpStatus: 202, body: queuedBody(existing) };
+    }
+    const error = existing.error;
+    return {
+        kind: "rejected",
+        error: new ServiceError(error?.code ?? "VALIDATION", error?.message ?? "write was rejected", error?.status ?? 400, {
+            field: error?.field,
+            retryable: false,
+            receiptId: existing.receiptId,
+        }),
+    };
+}
+/**
+ * Accept up to 500 rows in array order. Each row is stored and acknowledged before its result is recorded.
+ * One bad row does not reject the batch or drop rows already stored.
+ */
+export async function runQueuedBatch(deps, body, datasourceFor) {
+    if (!body || typeof body !== "object" || Array.isArray(body) || !Array.isArray(body.writes)) {
+        throw new ServiceError("VALIDATION", "writes must be an array", 400, { field: "writes", retryable: false });
+    }
+    const writes = body.writes;
+    if (writes.length > CONTENT_BATCH_LIMIT) {
+        throw new ServiceError("VALIDATION", `writes accepts at most ${CONTENT_BATCH_LIMIT} rows`, 400, {
+            field: "writes",
+            retryable: false,
+        });
+    }
+    const results = [];
+    for (const item of writes) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            results.push({
+                error: { code: "VALIDATION", field: "writes", message: "each write must be an object", retryable: false },
+            });
+            continue;
+        }
+        const row = item;
+        if (row.queue !== undefined) {
+            results.push({
+                error: {
+                    code: "VALIDATION",
+                    field: "queue",
+                    message: "queue is set on the batch body, not on a row",
+                    retryable: false,
+                },
+            });
+            continue;
+        }
+        try {
+            const datasource = datasourceFor(row);
+            const outcome = await runQueuedWrite({ ...deps, datasource }, row);
+            if (outcome.kind === "rejected")
+                results.push(batchError(outcome.error));
+            else
+                results.push(outcome.body);
+        }
+        catch (err) {
+            results.push(batchError(err));
+        }
+    }
+    return { results };
+}
+/** What `GET /api/data/receipts/:id`, the run list, and a repeat of a stored row return for a queued write. */
+export function publicQueuedReceipt(row) {
+    const queue = row.queue;
+    return {
+        receiptId: row.receiptId,
+        status: row.status,
+        ...(queue ? { storageKey: queue.storageKey, runId: queue.runId, stepId: queue.stepId } : {}),
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        ...(row.status === "stored" && row.receipt ? { receipt: row.receipt } : {}),
+        ...(row.status === "rejected" && row.error
+            ? {
+                error: {
+                    code: row.error.code,
+                    field: row.error.field,
+                    message: row.error.message,
+                    retryable: row.error.retryable,
+                },
+            }
+            : {}),
+    };
+}
+//# sourceMappingURL=queued-write.js.map

package/dist/writes/queued-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queued-write.js","sourceRoot":"","sources":["../../src/writes/queued-write.ts"],"names":[],"mappings":"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"}

package/dist/writes/receipt-store.d.ts

@@ -1,5 +1,6 @@
 import type { Db } from "mongodb";
 export declare const WRITE_RECEIPTS_COLLECTION = "write-receipts";
+export declare const RECEIPT_SEQ_COLLECTION = "write-receipt-seq";
 export declare const REJECTED_RECEIPT_TTL_MS: number;
 export declare const WRITE_ATTEMPT_LEASE_MS = 30000;
 export type WriteOperation = "created" | "updated" | "removed" | "unchanged";
@@ -44,16 +45,39 @@ export type ReceiptError = {
     retryAfterMs?: number;
     status: number;
 };
+/**
+ * What a queued row adds to its receipt. A synchronous receipt has none of this.
+ */
+export type QueuedWriteInfo = {
+    /** Accept number, monotonic per org. Rows for one key apply in this order. */
+    seq: number;
+    /** The storage key the row lands on. Rows with the same `keyId` apply one at a time. */
+    keyId: string;
+    runId: string;
+    stepId: string;
+    storageKey: WriteReceipt["storageKey"];
+};
+export type RunReceiptStatus = "queued" | "stored" | "rejected";
+export type RunSummary = {
+    queued: number;
+    stored: number;
+    rejected: number;
+};
 export type WriteReceiptRow = {
     receiptId: string;
     orgId: string;
     caller: string;
     writeId?: string;
     contentHash: string;
-    status: "pending" | "stored" | "rejected";
+    /**
+     * `pending` is a synchronous write that failed in a way a retry can fix.
+     * `queued` is a row that was accepted with `queue: true` and is not applied yet.
+     */
+    status: "pending" | "queued" | "stored" | "rejected";
     receipt?: WriteReceipt;
     error?: ReceiptError;
     request: StoredContentWrite;
+    queue?: QueuedWriteInfo;
     attempts: number;
     nextAttemptAt: string;
     createdAt: string;
@@ -69,10 +93,36 @@ export type WriteReceiptStore = {
     list(args: {
         orgId: string;
         caller: string;
-        status?: "pending" | "stored" | "rejected";
+        status?: "pending" | "queued" | "stored" | "rejected";
         limit: number;
     }): Promise<WriteReceiptRow[]>;
     claimDue(orgId: string, now: string, limit: number, leaseMs: number): Promise<WriteReceiptRow[]>;
+    /** The first of `count` consecutive accept numbers for this org. */
+    reserveSeq(orgId: string, count: number): Promise<number>;
+    /**
+     * Queued rows that are due and have no earlier open row on the same key.
+     * Each returned row is leased: no other claim returns it until the lease ends.
+     */
+    claimQueued(orgId: string, now: string, limit: number, leaseMs: number): Promise<WriteReceiptRow[]>;
+    /** Queued-write receipts of one run for one caller, in accept order, after the cursor. */
+    listByRun(args: {
+        orgId: string;
+        caller: string;
+        runId: string;
+        stepId?: string;
+        status?: RunReceiptStatus;
+        /** Return rows whose accept number is greater than this. */
+        after?: number;
+        limit: number;
+    }): Promise<WriteReceiptRow[]>;
+    summarizeRun(args: {
+        orgId: string;
+        caller: string;
+        runId: string;
+        stepId?: string;
+    }): Promise<RunSummary>;
+    /** The newest accepted row for a key that has not been applied. */
+    latestQueuedForKey(orgId: string, keyId: string): Promise<WriteReceiptRow | null>;
 };
 export declare function newReceiptId(): string;
 export declare function rejectedExpiry(nowIso: string): string;

package/dist/writes/receipt-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"receipt-store.d.ts","sourceRoot":"","sources":["../../src/writes/receipt-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"receipt-store.d.ts","sourceRoot":"","sources":["../../src/writes/receipt-store.ts"],"names":[],"mappings":"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"}

package/dist/writes/receipt-store.js

@@ -3,6 +3,7 @@
  */
 import { randomBytes } from "node:crypto";
 export const WRITE_RECEIPTS_COLLECTION = "write-receipts";
+export const RECEIPT_SEQ_COLLECTION = "write-receipt-seq";
 export const REJECTED_RECEIPT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 export const WRITE_ATTEMPT_LEASE_MS = 30_000;
 export function newReceiptId() {
@@ -11,12 +12,17 @@ export function newReceiptId() {
 export function rejectedExpiry(nowIso) {
     return new Date(Date.parse(nowIso) + REJECTED_RECEIPT_TTL_MS).toISOString();
 }
+function matchesRun(row, args) {
+    return (row.caller === args.caller &&
+        row.queue?.runId === args.runId &&
+        (args.stepId === undefined || row.queue.stepId === args.stepId));
+}
 export function createMemoryWriteReceiptStore() {
     const buckets = new Map();
     function bucket(orgId) {
         let found = buckets.get(orgId);
         if (!found) {
-            found = { byId: new Map(), byWriteId: new Map() };
+            found = { byId: new Map(), byWriteId: new Map(), seq: 0 };
             buckets.set(orgId, found);
         }
         return found;
@@ -78,6 +84,67 @@ export function createMemoryWriteReceiptStore() {
             }
             return claimed;
         },
+        async reserveSeq(orgId, count) {
+            const box = bucket(orgId);
+            const first = box.seq + 1;
+            box.seq += count;
+            return first;
+        },
+        async claimQueued(orgId, now, limit, leaseMs) {
+            const until = new Date(Date.parse(now) + leaseMs).toISOString();
+            const open = [...bucket(orgId).byId.values()].filter((row) => row.status === "queued" && row.queue);
+            const earliestOpen = new Map();
+            for (const row of open) {
+                const seen = earliestOpen.get(row.queue.keyId);
+                if (seen === undefined || row.queue.seq < seen)
+                    earliestOpen.set(row.queue.keyId, row.queue.seq);
+            }
+            const claimed = [];
+            const due = open
+                .filter((row) => row.nextAttemptAt <= now)
+                .sort((a, b) => a.queue.seq - b.queue.seq);
+            for (const row of due) {
+                if (claimed.length >= limit)
+                    break;
+                if (earliestOpen.get(row.queue.keyId) !== row.queue.seq)
+                    continue;
+                row.nextAttemptAt = until;
+                row.attempts += 1;
+                row.updatedAt = now;
+                claimed.push(structuredClone(row));
+            }
+            return claimed;
+        },
+        async listByRun(args) {
+            return [...bucket(args.orgId).byId.values()]
+                .filter((row) => matchesRun(row, args))
+                .filter((row) => (args.status ? row.status === args.status : true))
+                .filter((row) => (args.after === undefined ? true : row.queue.seq > args.after))
+                .sort((a, b) => a.queue.seq - b.queue.seq)
+                .slice(0, args.limit)
+                .map((row) => structuredClone(row));
+        },
+        async summarizeRun(args) {
+            const summary = { queued: 0, stored: 0, rejected: 0 };
+            for (const row of bucket(args.orgId).byId.values()) {
+                if (!matchesRun(row, args))
+                    continue;
+                if (row.status === "queued" || row.status === "stored" || row.status === "rejected") {
+                    summary[row.status] += 1;
+                }
+            }
+            return summary;
+        },
+        async latestQueuedForKey(orgId, keyId) {
+            let latest = null;
+            for (const row of bucket(orgId).byId.values()) {
+                if (row.status !== "queued" || row.queue?.keyId !== keyId)
+                    continue;
+                if (!latest || row.queue.seq > latest.queue.seq)
+                    latest = row;
+            }
+            return latest ? structuredClone(latest) : null;
+        },
     };
 }
 export function createMongoWriteReceiptStore(db) {
@@ -96,6 +163,29 @@ export function createMongoWriteReceiptStore(db) {
         ]).then(() => undefined);
         return ready;
     }
+    /**
+     * Indexes for queued writes only. They are separate from `ensure()` so a synchronous write never
+     * waits for them: on a large `write-receipts` collection the first build scans every row once.
+     * Partial filters keep synchronous receipts out of these indexes, and each query on one of them
+     * states the field its filter names, so the planner can use it.
+     * A failed build is tried again on the next queue call.
+     */
+    let queueReady = null;
+    function ensureQueue() {
+        queueReady ??= Promise.all([
+            ensure(),
+            coll.createIndex({ orgId: 1, status: 1, "queue.seq": 1 }, { name: "queue_seq", partialFilterExpression: { "queue.seq": { $exists: true } } }),
+            coll.createIndex({ orgId: 1, "queue.keyId": 1, status: 1, "queue.seq": 1 }, { name: "queue_key", partialFilterExpression: { "queue.keyId": { $exists: true } } }),
+            coll.createIndex({ orgId: 1, caller: 1, "queue.runId": 1, status: 1, "queue.seq": 1 }, { name: "queue_run_status", partialFilterExpression: { "queue.runId": { $exists: true } } }),
+            coll.createIndex({ orgId: 1, caller: 1, "queue.runId": 1, "queue.seq": 1 }, { name: "queue_run", partialFilterExpression: { "queue.runId": { $exists: true } } }),
+        ]).then(() => undefined, (err) => {
+            queueReady = null;
+            throw err;
+        });
+        return queueReady;
+    }
+    /** One counter document per org. `$inc` is atomic, so two processes never share a number. */
+    const counters = db.collection(RECEIPT_SEQ_COLLECTION);
     return {
         async findByWriteId(orgId, caller, writeId) {
             await ensure();
@@ -108,7 +198,8 @@ export function createMongoWriteReceiptStore(db) {
             return doc ? fromDoc(doc) : null;
         },
         async insert(row) {
-            await ensure();
+            // A synchronous receipt never waits for the queue indexes.
+            await (row.queue ? ensureQueue() : ensure());
             try {
                 await coll.insertOne(toDoc(row));
                 return "inserted";
@@ -154,6 +245,104 @@ export function createMongoWriteReceiptStore(db) {
             }
             return claimed;
         },
+        async reserveSeq(orgId, count) {
+            const after = await counters.findOneAndUpdate({ _id: orgId }, { $inc: { seq: count } }, { upsert: true, returnDocument: "after" });
+            if (!after)
+                throw new Error("receipt sequence counter did not return a document");
+            return after.seq - count + 1;
+        },
+        async claimQueued(orgId, now, limit, leaseMs) {
+            await ensureQueue();
+            const until = new Date(Date.parse(now) + leaseMs).toISOString();
+            const claimed = [];
+            const taken = new Set();
+            const pageSize = Math.max(limit * 4, 16);
+            // Rows waiting behind an earlier row on the same key fill the front of the order.
+            // Keep paging past them, up to a cap, so other keys are not starved.
+            const SCAN_CAP = 4_000;
+            let scanned = 0;
+            let after = 0;
+            while (claimed.length < limit && scanned < SCAN_CAP) {
+                // Only what the claim needs. The full row, with its request body, is read once it is claimed.
+                const page = await coll
+                    .find({ orgId, status: "queued", "queue.seq": { $gt: after }, nextAttemptAt: { $lte: now } }, { projection: { _id: 1, "queue.seq": 1, "queue.keyId": 1, nextAttemptAt: 1 } })
+                    .sort({ "queue.seq": 1 })
+                    .limit(pageSize)
+                    .toArray();
+                if (page.length === 0)
+                    break;
+                for (const doc of page) {
+                    scanned += 1;
+                    after = doc.queue.seq;
+                    if (claimed.length >= limit)
+                        break;
+                    const keyId = doc.queue.keyId;
+                    if (taken.has(keyId))
+                        continue;
+                    const ahead = await coll.findOne({
+                        orgId,
+                        status: "queued",
+                        "queue.keyId": keyId,
+                        "queue.seq": { $lt: doc.queue.seq },
+                    }, { projection: { _id: 1 } });
+                    if (ahead)
+                        continue;
+                    const updated = await coll.updateOne({ _id: doc._id, status: "queued", nextAttemptAt: doc.nextAttemptAt }, { $set: { nextAttemptAt: until, updatedAt: now }, $inc: { attempts: 1 } });
+                    if (updated.modifiedCount !== 1)
+                        continue;
+                    taken.add(keyId);
+                    const fresh = await coll.findOne({ _id: doc._id });
+                    if (fresh)
+                        claimed.push(fromDoc(fresh));
+                }
+                if (page.length < pageSize)
+                    break;
+            }
+            return claimed;
+        },
+        async listByRun(args) {
+            await ensureQueue();
+            const filter = {
+                orgId: args.orgId,
+                caller: args.caller,
+                "queue.runId": args.runId,
+                "queue.seq": { $gt: args.after ?? 0 },
+            };
+            if (args.stepId !== undefined)
+                filter["queue.stepId"] = args.stepId;
+            if (args.status)
+                filter.status = args.status;
+            const docs = await coll.find(filter).sort({ "queue.seq": 1 }).limit(args.limit).toArray();
+            return docs.map(fromDoc);
+        },
+        async summarizeRun(args) {
+            await ensureQueue();
+            const match = {
+                orgId: args.orgId,
+                caller: args.caller,
+                "queue.runId": args.runId,
+            };
+            if (args.stepId !== undefined)
+                match["queue.stepId"] = args.stepId;
+            const groups = await coll
+                .aggregate([
+                { $match: match },
+                { $group: { _id: "$status", n: { $sum: 1 } } },
+            ])
+                .toArray();
+            const summary = { queued: 0, stored: 0, rejected: 0 };
+            for (const group of groups) {
+                if (group._id === "queued" || group._id === "stored" || group._id === "rejected") {
+                    summary[group._id] = group.n;
+                }
+            }
+            return summary;
+        },
+        async latestQueuedForKey(orgId, keyId) {
+            await ensureQueue();
+            const doc = await coll.findOne({ orgId, status: "queued", "queue.keyId": keyId, "queue.seq": { $gt: 0 } }, { sort: { "queue.seq": -1 } });
+            return doc ? fromDoc(doc) : null;
+        },
     };
 }
 function toDoc(row) {