@pegma/support-desk-application 0.2.0 → 0.2.2

package/dist/index.js

@@ -2,7 +2,7 @@ import { auditRecordId, defineAudit } from "@pegma/audit";
 import { hasPermission } from "@pegma/authorization-core";
 import { defineMail, maxMailAttempts } from "@pegma/mail";
 import { noopLogger } from "@pegma/spine";
-import { defineCollection, MAX_SCAN_PAGE_SIZE, } from "@pegma/storage-core";
+import { ConcurrencyError, defineCollection, MAX_SCAN_PAGE_SIZE, } from "@pegma/storage-core";
 import { applyTicketEvent, createTicket, effectiveTicketHandling, } from "@pegma/support-desk-core";
 import { assertAssistantTurnRecord, createAssistantTurnRecord, resolveAssistantTurnOptions, } from "./assistant-turn-records.js";
 import { createAssistantTurnServices, } from "./assistant-turns.js";
@@ -149,6 +149,7 @@ export const supportTicketAuditActions = Object.freeze({
     learningEvidenceInvalidated: "support.learning.evidence_invalidated",
     learningWithdrawn: "support.learning.withdrawn",
     learningReviewed: "support.learning.reviewed",
+    learningReviewCancelled: "support.learning.review_cancelled",
     engineeringEnrolled: "support.engineering.enrolled",
     engineeringEvidenceRecorded: "support.engineering.evidence_recorded",
     engineeringEvidenceInvalidated: "support.engineering.evidence_invalidated",
@@ -1068,12 +1069,34 @@ function enforcePartitionRecordLimit(recordCount, maximum, additional = 0) {
 export const assistantHumanReserveRows = 12;
 export const assistantHumanReserveMessages = 1;
 const firstHumanReplyReserveRows = 4;
-async function planTicketDerivationMutation(records, before, after, rows, visibleChange = false, notice) {
-    const learning = await planResolutionLearningTicketMutation(records, before, after, notice !== undefined && visibleChange);
-    const engineering = notice === undefined
-        ? await planEngineeringTicketMutation(records, before, after, {
+/** Settle unused speculative failures without changing their consumer order. */
+async function prepareRead(read) {
+    try {
+        return { outcome: "read", value: await read() };
+    }
+    catch (error) {
+        return { outcome: "failed", error };
+    }
+}
+function readValue(observation) {
+    if (observation.outcome === "failed")
+        throw observation.error;
+    return observation.value;
+}
+async function planTicketDerivationMutation(records, before, after, rows, visibleChange = false, notice, parallel = false) {
+    const learningRead = planResolutionLearningTicketMutation(records, before, after, notice !== undefined && visibleChange);
+    const engineeringRead = parallel && notice === undefined
+        ? prepareRead(() => planEngineeringTicketMutation(records, before, after, {
             visibleChange,
-        })
+        }))
+        : undefined;
+    const learning = await learningRead;
+    const engineering = notice === undefined
+        ? engineeringRead === undefined
+            ? await planEngineeringTicketMutation(records, before, after, {
+                visibleChange,
+            })
+            : readValue(await engineeringRead)
         : { actions: [], additionalRows: 0 };
     const reopened = ["resolved", "closed"].includes(before.value.ticket.status) &&
         !["resolved", "closed"].includes(after.status);
@@ -1499,41 +1522,8 @@ export async function projectTicketToQueue(ticketId, options) {
     }
     const records = store.collection(supportRecords);
     const projections = store.collection(queueIndex);
-    const ticketRecord = await records.get(ticketKey(ticketId));
-    if (ticketRecord?.kind !== "ticket") {
-        const existing = await projections.getVersioned(queueProjectionKey(ticketId));
-        if (existing === null) {
-            return "absent";
-        }
-        const removed = await projections.deleteIfUnchanged(queueProjectionKey(ticketId), existing.version);
-        return removed ? "deleted" : "kept";
-    }
-    const ticket = ticketRecord.ticket;
-    if (ticket.id !== ticketId) {
-        throw new TypeError("stored ticket id does not match its partition");
-    }
-    // Sample the host clock only for terminal retention. Active tickets never
-    // consult wall time, so post-commit projection does not consume sequence
-    // clocks used by ticket mutations.
-    if (isTerminalTicketStatus(ticket.status)) {
-        const now = clock.now();
-        if (ticketBeyondTerminalCutoff(ticket, now, terminalRetentionMilliseconds)) {
-            const existing = await projections.getVersioned(queueProjectionKey(ticketId));
-            if (existing === null) {
-                return "absent";
-            }
-            // Only prune a projection that still matches this terminal revision.
-            // A concurrent reopen can land a newer active row between the ticket
-            // read and this delete; that row must be preserved for repair to see.
-            if (existing.value.projectedRevision !== ticket.revision) {
-                return "kept";
-            }
-            const removed = await projections.deleteIfUnchanged(queueProjectionKey(ticketId), existing.version);
-            return removed ? "deleted" : "kept";
-        }
-    }
-    const derived = deriveQueueIndexRecord(ticket);
-    const result = await projections.update(queueProjectionKey(ticketId), (current) => {
+    const key = queueProjectionKey(ticketId);
+    function decide(current, derived) {
         if (current === null) {
             return { action: "write", value: derived };
         }
@@ -1560,8 +1550,55 @@ export async function projectTicketToQueue(ticketId, options) {
         if (queueIndexContentEqual(current, legacy))
             return { action: "write", value: derived };
         throw new SupportDeskConflictError("Queue projection revision collision with divergent content");
-    }, { maxAttempts: maxConflictAttempts });
-    return result.written ? "written" : "kept";
+    }
+    for (let attempt = 0; attempt < maxConflictAttempts; attempt += 1) {
+        const ticketRead = records.get(ticketKey(ticketId));
+        const projectionRead = prepareRead(() => projections.getVersioned(key));
+        const ticketRecord = await ticketRead;
+        if (ticketRecord?.kind !== "ticket") {
+            const existing = readValue(await projectionRead);
+            if (existing === null)
+                return "absent";
+            if (await projections.deleteIfUnchanged(key, existing.version))
+                return "deleted";
+            if (attempt + 1 === maxConflictAttempts)
+                return "kept";
+            continue;
+        }
+        const ticket = ticketRecord.ticket;
+        if (ticket.id !== ticketId)
+            throw new TypeError("stored ticket id does not match its partition");
+        // Active tickets never consult wall time. Retry terminal retention only
+        // with the new authoritative Ticket and projection observations together.
+        if (isTerminalTicketStatus(ticket.status)) {
+            const now = clock.now();
+            if (ticketBeyondTerminalCutoff(ticket, now, terminalRetentionMilliseconds)) {
+                const existing = readValue(await projectionRead);
+                if (existing === null)
+                    return "absent";
+                // A newer active projection from a concurrent reopen must survive.
+                if (existing.value.projectedRevision !== ticket.revision)
+                    return "kept";
+                if (await projections.deleteIfUnchanged(key, existing.version))
+                    return "deleted";
+                if (attempt + 1 === maxConflictAttempts)
+                    return "kept";
+                continue;
+            }
+        }
+        const derived = deriveQueueIndexRecord(ticket);
+        const existing = readValue(await projectionRead);
+        const decision = decide(existing?.value ?? null, derived);
+        if (decision.action !== "write")
+            return "kept";
+        const written = existing === null
+            ? (await projections.insertIfAbsent(decision.value)).inserted
+            : await projections.putIfUnchanged(decision.value, existing.version);
+        if (written)
+            return "written";
+        // Rebuild both observations; never keep a stale Ticket across a CAS retry.
+    }
+    throw new ConcurrencyError(queueIndex.name, key, maxConflictAttempts);
 }
 function toStaffQueueItem(ticket) {
     return Object.freeze({
@@ -2625,13 +2662,21 @@ export function createSupportDeskApplication(options) {
                 ? {}
                 : { assistantTurnFingerprint: assistantTurnCommit.fingerprint }),
         });
+        const completion = assistantTurnCommit;
+        const parallel = completion?.kind === "complete";
         for (let attempt = 0; attempt < maxConflictAttempts; attempt += 1) {
-            const versioned = await records.getVersioned(ticketKey(command.ticketId));
+            const ticketRead = records.getVersioned(ticketKey(command.ticketId));
+            const duplicateRead = parallel
+                ? prepareRead(() => records.get(commandKey(command.ticketId, command.commandId)))
+                : undefined;
+            const versioned = await ticketRead;
             if (versioned?.value.kind !== "ticket" ||
                 (customer && !owns(versioned.value.ticket, access.principalId)))
                 throw new SupportDeskNotFoundError();
             const ticket = versioned.value.ticket;
-            const duplicate = await records.get(commandKey(command.ticketId, command.commandId));
+            const duplicate = duplicateRead === undefined
+                ? await records.get(commandKey(command.ticketId, command.commandId))
+                : readValue(await duplicateRead);
             if (duplicateMatches(duplicate, operation, command.messageId, fingerprint)) {
                 if (duplicate?.kind !== "command" ||
                     duplicate.resultTicket === undefined)
@@ -2640,6 +2685,27 @@ export function createSupportDeskApplication(options) {
             }
             if (duplicate !== null)
                 throw new SupportDeskConflictError("Command ID reused with different input");
+            if (parallel &&
+                (ticket.channel !== "web" ||
+                    isTerminalTicketStatus(ticket.status) ||
+                    effectiveTicketHandling(ticket).state !== "assistant" ||
+                    ticket.revision !== command.expectedRevision ||
+                    effectiveTicketHandling(ticket).generation !==
+                        command.expectedHandlingGeneration)) {
+                // The speculative receipt may predate a concurrent exact completion
+                // that this Ticket observation already contains. Recover its receipt
+                // before rejecting the now-stale live fence; ordinary paired reads
+                // retain their existing cost and original whole-attempt CAS versions.
+                const accepted = await records.get(commandKey(command.ticketId, command.commandId));
+                if (duplicateMatches(accepted, operation, command.messageId, fingerprint)) {
+                    if (accepted?.kind !== "command" ||
+                        accepted.resultTicket === undefined)
+                        throw new SupportDeskConflictError("Handling receipt is incomplete");
+                    return accepted.resultTicket;
+                }
+                if (accepted !== null)
+                    throw new SupportDeskConflictError("Command ID reused with different input");
+            }
             if (operation === "assistant_reply" && !assistantHandlingEnabled)
                 throw new SupportDeskConflictError("Assistant handling is disabled");
             const rows = await records.list(command.ticketId);
@@ -2698,7 +2764,21 @@ export function createSupportDeskApplication(options) {
                             });
             if (updated.revision === ticket.revision)
                 return ticket;
-            const learningMutation = await planTicketDerivationMutation(records, { value: versioned.value, version: versioned.version }, updated, rows, operation === "assistant_reply");
+            const originalTicket = {
+                value: versioned.value,
+                version: versioned.version,
+            };
+            const planMutation = () => planTicketDerivationMutation(records, originalTicket, updated, rows, operation === "assistant_reply", undefined, parallel);
+            const mutationRead = parallel ? prepareRead(planMutation) : undefined;
+            const quotaRead = parallel && operation === "assistant_reply"
+                ? prepareRead(() => records.getVersioned(ticketQuotaKey(command.ticketId)))
+                : undefined;
+            const assistantRead = parallel && completion !== undefined
+                ? prepareRead(() => assistantTurns.completionAction(ticket, rows, updated, completion))
+                : undefined;
+            const learningMutation = mutationRead === undefined
+                ? await planMutation()
+                : readValue(await mutationRead);
             const learningConfirmation = operation === "confirm_customer_success"
                 ? await resolutionLearning.customerConfirmation(learningMutation.source, updated, access.principalId, command.lastSeenVisibleMessageId, command.commandId, rows)
                 : { actions: [], additionalRows: 0 };
@@ -2714,7 +2794,9 @@ export function createSupportDeskApplication(options) {
                 ...learningConfirmation.actions,
             ];
             if (operation === "assistant_reply") {
-                const quota = await records.getVersioned(ticketQuotaKey(command.ticketId));
+                const quota = quotaRead === undefined
+                    ? await records.getVersioned(ticketQuotaKey(command.ticketId))
+                    : readValue(await quotaRead);
                 if (quota?.value.kind !== "ticket_quota")
                     throw new SupportDeskConflictError("Ticket partition quota metadata is missing");
                 if (quota.value.messageCount >= limits.maxMessagesPerTicket)
@@ -2827,7 +2909,9 @@ export function createSupportDeskApplication(options) {
             });
             const assistantCommit = assistantTurnCommit === undefined
                 ? undefined
-                : await assistantTurns.completionAction(ticket, rows, updated, assistantTurnCommit);
+                : assistantRead === undefined
+                    ? await assistantTurns.completionAction(ticket, rows, updated, assistantTurnCommit)
+                    : readValue(await assistantRead);
             if (assistantCommit !== undefined) {
                 actions.push(assistantCommit.action);
                 await assistantCommit.verifyBeforeCommit();