@pegma/support-desk-application 0.2.3 → 0.2.4

package/dist/index.js

@@ -16,7 +16,7 @@ import { createEngineeringFollowupSourceServices, planEngineeringFollowupSourceC
 import { createEngineeringFollowupWorkServices } from "./engineering-followup-work.js";
 import { fields as followupFields, integer as followupInteger, text as followupText, } from "./assistant-turn-records.js";
 import { engineeringFollowupCommandKey, engineeringFollowupHeadKey, safeEngineeringFollowupSnapshot as followupSnapshot, checkEngineeringFollowupRecordCapacity, } from "./engineering-followup-records.js";
-import { engineeringFollowupNow, engineeringFollowupVersionsCurrent, } from "./engineering-followup-source.js";
+import { engineeringFollowupNow, engineeringFollowupTrusted, engineeringFollowupVersionsCurrent, } from "./engineering-followup-source.js";
 import { assertResolutionLearningRecord, resolveResolutionLearningOptions, } from "./resolution-learning-records.js";
 import { createResolutionLearningServices, createResolutionLearningSource, planResolutionLearningTicketMutation, } from "./resolution-learning.js";
 export { resolutionLearningDeliveryBinding, resolutionLearningManifestHash, } from "./resolution-learning-worker.js";
@@ -861,6 +861,65 @@ function snapshotCreateCustomerTicketCommand(input) {
         ...(initialHandling === undefined ? {} : { initialHandling }),
     });
 }
+function snapshotCustomerTicketAdmission(input) {
+    const source = boundaryObject(input, "admitted create command");
+    const allowed = [
+        "commandId",
+        "correlationId",
+        "ticketId",
+        "messageId",
+        "subject",
+        "body",
+        "category",
+        "requesterEmail",
+        "preference",
+        "disclosureVersion",
+    ];
+    const keys = Reflect.ownKeys(source);
+    if (Array.isArray(source) ||
+        keys.some((key) => typeof key !== "string" || !allowed.includes(key)))
+        throw new TypeError("Invalid admitted create command fields");
+    const command = Object.freeze(Object.fromEntries(keys.map((key) => [
+        key,
+        ownDataProperty(source, key, "admitted create command field"),
+    ])));
+    const preference = ownDataProperty(command, "preference", "preference");
+    if (preference !== "human" && preference !== "assistant_if_available")
+        throw new TypeError("Invalid admitted create preference");
+    const raw = ownDataProperty(command, "disclosureVersion", "disclosureVersion", true);
+    const disclosureVersion = raw === undefined ? undefined : boundaryString(raw, "disclosureVersion");
+    if (disclosureVersion !== undefined)
+        requireIdentifier(disclosureVersion, "disclosureVersion");
+    return {
+        command,
+        intent: Object.freeze({
+            preference,
+            ...(disclosureVersion === undefined ? {} : { disclosureVersion }),
+        }),
+    };
+}
+function customerCreateMethods(create) {
+    return {
+        async createCustomerTicket(access, input) {
+            return (await create(access, input)).view;
+        },
+        async createAdmittedCustomerTicket(access, input, options) {
+            requirePermission(access, supportPermissions.create);
+            requirePermission(access, supportPermissions.readOwn);
+            const { command, intent } = snapshotCustomerTicketAdmission(input);
+            return create(access, command, {
+                intent,
+                ...(options === undefined ? {} : { options }),
+            });
+        },
+    };
+}
+function admittedCreateMode(record) {
+    if (record?.kind !== "command" ||
+        (record.initialMode !== "human" && record.initialMode !== "assistant"))
+        throw new SupportDeskConflictError("Admitted create receipt mode is invalid");
+    return record.initialMode;
+}
 function snapshotReplyToCustomerTicketCommand(input) {
     const source = boundaryObject(input, "reply command");
     const raw = {
@@ -2408,9 +2467,12 @@ export function createSupportDeskApplication(options) {
     };
     const engineeringFollowupSource = createEngineeringFollowupSourceServices(followupDependencies);
     const engineeringFollowupWork = createEngineeringFollowupWorkServices(followupDependencies, engineeringFollowupSource.internal.load);
-    const approveAndPostEngineeringFollowupWebUpdate = async (access, input, guard) => {
+    const approveAndPostEngineeringFollowupWebUpdate = async (access, input, guard, options = {}) => {
         const actorId = access.principalId;
+        const { signal, verifyBeforeCommit } = options;
         const authorize = () => {
+            if (signal?.aborted)
+                throw new SupportDeskConflictError("Follow-up posting cancelled");
             requireIdentifier(access.principalId, "principalId");
             if (access.principalId !== actorId)
                 throw new SupportDeskAuthorizationError(supportPermissions.engineeringFollowupReview);
@@ -2495,7 +2557,7 @@ export function createSupportDeskApplication(options) {
             requireNonempty(body, "body");
             enforceLimit(body, "body", limits.maxMessageCharacters);
             const bodyHash = await requestFingerprint({ body });
-            await guard();
+            const assertProofCurrent = await guard();
             authorize();
             const occurredAt = clampTicketTime(clock.now(), ticket.updatedAt);
             const updated = applyTicketEvent(ticket, {
@@ -2566,8 +2628,22 @@ export function createSupportDeskApplication(options) {
             if (!(await engineeringFollowupVersionsCurrent(followupDependencies, current.loaded, current.work, current.engineeringWork)))
                 continue;
             authorize();
-            if (now() >=
-                Math.min(Date.parse(work.deadline), checked.deadline, Date.parse(current.proof.attestation.validUntil)))
+            const proofDeadline = Math.min(Date.parse(work.deadline), checked.deadline, Date.parse(current.proof.attestation.validUntil));
+            if (now() >= proofDeadline)
+                throw new SupportDeskConflictError("Follow-up posting proof expired");
+            if (verifyBeforeCommit !== undefined) {
+                const authorityDeadline = Math.min(proofDeadline, now() + engineeringFollowupOptions.trustTimeoutMilliseconds);
+                await engineeringFollowupTrusted(followupDependencies, async () => {
+                    authorize();
+                    await verifyBeforeCommit();
+                }, signal);
+                authorize();
+                if (now() >= authorityDeadline)
+                    throw new SupportDeskConflictError("Follow-up posting authority or proof expired");
+            }
+            if (assertProofCurrent !== undefined &&
+                (typeof assertProofCurrent !== "function" ||
+                    assertProofCurrent() !== true))
                 throw new SupportDeskConflictError("Follow-up posting proof expired");
             const outcome = await records.transact(command.ticketId, [
                 ...derivations.actions,
@@ -2663,7 +2739,7 @@ export function createSupportDeskApplication(options) {
                 : { assistantTurnFingerprint: assistantTurnCommit.fingerprint }),
         });
         const completion = assistantTurnCommit;
-        const parallel = completion?.kind === "complete";
+        const parallel = completion?.kind === "complete" || completion?.kind === "finish";
         for (let attempt = 0; attempt < maxConflictAttempts; attempt += 1) {
             const ticketRead = records.getVersioned(ticketKey(command.ticketId));
             const duplicateRead = parallel
@@ -2692,8 +2768,8 @@ export function createSupportDeskApplication(options) {
                     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
+                // The speculative receipt may predate a concurrent completion or
+                // finish already reflected in this Ticket. Recover its exact 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));
@@ -3106,19 +3182,63 @@ export function createSupportDeskApplication(options) {
                 .sort((a, b) => a.revision - b.revision || a.commandId.localeCompare(b.commandId))
                 .map(({ kind: _kind, partition: _partition, id: _id, ...proof }) => Object.freeze(proof));
         },
-        async createCustomerTicket(access, input) {
+        ...customerCreateMethods(async (access, input, admitted) => {
             requirePermission(access, supportPermissions.create);
             requireIdentifier(access.principalId, "principalId");
+            const actorId = access.principalId;
+            const principal = () => admitted === undefined ? access.principalId : actorId;
+            const signal = admitted?.options?.signal;
+            function authorizeAdmitted(current = access, assistant = false) {
+                if (admitted === undefined)
+                    return;
+                if (signal?.aborted)
+                    throw new SupportDeskConflictError("Admitted create was cancelled");
+                if (current.principalId !== actorId)
+                    throw new SupportDeskAuthorizationError(supportPermissions.create);
+                requirePermission(current, supportPermissions.create);
+                requirePermission(current, supportPermissions.readOwn);
+                if (assistant)
+                    requirePermission(current, supportPermissions.assistantStart);
+            }
+            async function waitForAdmission(check) {
+                authorizeAdmitted();
+                if (signal === undefined)
+                    return check();
+                let onAbort;
+                try {
+                    return await Promise.race([
+                        Promise.resolve().then(() => {
+                            authorizeAdmitted();
+                            return check();
+                        }),
+                        new Promise((_resolve, reject) => {
+                            onAbort = () => reject(new SupportDeskConflictError("Admitted create was cancelled"));
+                            signal.addEventListener("abort", onAbort, { once: true });
+                            if (signal.aborted)
+                                onAbort();
+                        }),
+                    ]);
+                }
+                finally {
+                    if (onAbort !== undefined)
+                        signal.removeEventListener("abort", onAbort);
+                }
+            }
+            authorizeAdmitted();
             const command = snapshotCreateCustomerTicketCommand(input);
-            if (command.initialHandling === "assistant") {
+            let initialHandling = command.initialHandling;
+            if (admitted === undefined && initialHandling === "assistant") {
                 requirePermission(access, supportPermissions.assistantStart);
             }
             requireIdentifier(command.ticketId, "ticketId");
             requireIdentifier(command.messageId, "messageId");
             requireIdentifier(command.commandId, "commandId");
             requireIdentifier(command.correlationId, "correlationId");
-            enforceLimit(command.subject, "subject", limits.maxSubjectCharacters);
-            enforceLimit(command.body, "body", limits.maxMessageCharacters);
+            // Admitted replay keeps fixed ceilings when later instance limits shrink.
+            // Fresh admission applies the configured limits after receipt recovery.
+            const inputLimits = admitted === undefined ? limits : supportDeskLimitMaximums;
+            enforceLimit(command.subject, "subject", inputLimits.maxSubjectCharacters);
+            enforceLimit(command.body, "body", inputLimits.maxMessageCharacters);
             const fingerprintPayload = {
                 type: "create_customer_ticket",
                 ticketId: command.ticketId,
@@ -3135,7 +3255,20 @@ export function createSupportDeskApplication(options) {
                     ? {}
                     : { initialHandling: command.initialHandling }),
             };
-            const fingerprint = await requestFingerprint(fingerprintPayload);
+            const commandType = admitted === undefined
+                ? "create_customer_ticket"
+                : "create_admitted_customer_ticket";
+            const fingerprint = await requestFingerprint(admitted === undefined
+                ? fingerprintPayload
+                : {
+                    ...fingerprintPayload,
+                    type: commandType,
+                    version: 1,
+                    actorId,
+                    commandId: command.commandId,
+                    preference: admitted.intent.preference,
+                    disclosureVersion: admitted.intent.disclosureVersion ?? null,
+                });
             const createThreading = {
                 ticketNumber: true,
                 ...(command.notification === undefined
@@ -3146,8 +3279,10 @@ export function createSupportDeskApplication(options) {
             // later config change cannot break idempotent retries of the same command.
             // Replay never reserves another instance ticket number.
             const existingCreate = await records.get(commandKey(command.ticketId, command.commandId));
-            let createIsReplay = duplicateMatches(existingCreate, "create_customer_ticket", command.messageId, fingerprint);
-            if (!createIsReplay &&
+            authorizeAdmitted();
+            let createIsReplay = duplicateMatches(existingCreate, commandType, command.messageId, fingerprint);
+            if (admitted === undefined &&
+                !createIsReplay &&
                 command.initialHandling === undefined &&
                 existingCreate?.kind === "command" &&
                 existingCreate.commandType === "create_customer_ticket" &&
@@ -3174,19 +3309,28 @@ export function createSupportDeskApplication(options) {
             }
             if (createIsReplay) {
                 const current = await records.get(ticketKey(command.ticketId));
-                if (current?.kind !== "ticket" ||
-                    !owns(current.ticket, access.principalId))
+                authorizeAdmitted();
+                if (current?.kind !== "ticket" || !owns(current.ticket, principal()))
                     throw new SupportDeskNotFoundError();
+                const initialMode = admitted === undefined
+                    ? (initialHandling ?? "human")
+                    : admittedCreateMode(existingCreate);
                 // A crash after ticket commit and before index confirmation must still
                 // converge the principal hint on retry.
                 const fence = await records.get(ticketReservationKey(command.ticketId));
+                authorizeAdmitted();
                 if (fence?.kind === "ticket_reservation" &&
                     fence.state === "committed") {
-                    await confirmCustomerTicket(access.principalId, command.ticketId, fence.token, fence.generation);
+                    await confirmCustomerTicket(principal(), command.ticketId, fence.token, fence.generation);
                 }
-                return customerViewAfterChange(access.principalId, command.ticketId, createThreading);
+                authorizeAdmitted();
+                const view = await customerViewAfterChange(principal(), command.ticketId, createThreading);
+                authorizeAdmitted();
+                return { view, initialMode };
             }
-            if (command.initialHandling === "assistant" && !assistantHandlingEnabled)
+            if (admitted !== undefined && existingCreate !== null)
+                throw new SupportDeskConflictError("Admitted create command changed");
+            if (initialHandling === "assistant" && !assistantHandlingEnabled)
                 throw new SupportDeskConflictError("Assistant handling is disabled");
             if (command.category !== undefined) {
                 if (allowedCategories === undefined ||
@@ -3194,6 +3338,29 @@ export function createSupportDeskApplication(options) {
                     throw new TypeError("create command.category is not configured for this Support Desk instance");
                 }
             }
+            const verifyBeforeCommit = admitted?.options?.verifyBeforeCommit;
+            let assistantAccess;
+            if (admitted !== undefined) {
+                enforceLimit(command.subject, "subject", limits.maxSubjectCharacters);
+                enforceLimit(command.body, "body", limits.maxMessageCharacters);
+                if (typeof verifyBeforeCommit !== "function")
+                    throw new SupportDeskConflictError("Fresh create admission is required");
+                const resolveAssistantStart = admitted.options?.resolveAssistantStart;
+                if (admitted.intent.preference === "assistant_if_available" &&
+                    admitted.intent.disclosureVersion !== undefined &&
+                    assistantHandlingEnabled &&
+                    assistantTurnOptions !== undefined &&
+                    resolveAssistantStart !== undefined) {
+                    const current = await waitForAdmission(resolveAssistantStart);
+                    authorizeAdmitted();
+                    if (current !== null) {
+                        authorizeAdmitted(current, true);
+                        assistantAccess = current;
+                        initialHandling = "assistant";
+                    }
+                }
+            }
+            let initialMode = initialHandling ?? "human";
             // Fail closed before durable number/index reservation so a too-small
             // partition budget cannot exhaust the principal ticket index with
             // reserved-but-never-created tickets.
@@ -3201,18 +3368,17 @@ export function createSupportDeskApplication(options) {
                 (resolutionLearningOptions.enabled ? 1 : 0) +
                 (engineeringOptions.enabled ? 1 : 0) +
                 (command.notification === undefined ? 0 : 1) +
-                (assistantTurnOptions !== undefined &&
-                    command.initialHandling === "assistant"
+                (assistantTurnOptions !== undefined && initialHandling === "assistant"
                     ? 1
                     : 0);
             enforcePartitionRecordLimit(0, limits.maxRecordsPerTicket, estimatedCreateRows +
                 (resolutionLearningOptions.enabled ? 2 : 0) +
                 (engineeringOptions.enabled ? 2 : 0) +
-                (command.initialHandling === "assistant"
+                (initialHandling === "assistant"
                     ? assistantHumanReserveRows +
                         (resolutionLearningOptions.enabled ? 1 : 0)
                     : 0));
-            if (command.initialHandling === "assistant" &&
+            if (initialHandling === "assistant" &&
                 limits.maxMessagesPerTicket < 1 + assistantHumanReserveMessages)
                 throw new SupportDeskLimitError("ticket_messages", limits.maxMessagesPerTicket);
             // Reserve outside the ticket transaction; gaps are accepted if create fails.
@@ -3228,15 +3394,13 @@ export function createSupportDeskApplication(options) {
                 number: ticketNumber,
                 subject: command.subject,
                 channel: "web",
-                ...(command.initialHandling === undefined
-                    ? {}
-                    : { initialHandling: command.initialHandling }),
+                ...(initialHandling === undefined ? {} : { initialHandling }),
                 ...(command.category === undefined
                     ? {}
                     : { category: command.category }),
                 requester: {
                     association: "authenticated",
-                    principalId: access.principalId,
+                    principalId: principal(),
                     ...(command.requesterEmail === undefined
                         ? {}
                         : { email: command.requesterEmail }),
@@ -3247,22 +3411,21 @@ export function createSupportDeskApplication(options) {
                 id: command.messageId,
                 ticketId: command.ticketId,
                 authorKind: "customer",
-                authorPrincipalId: access.principalId,
+                authorPrincipalId: principal(),
                 channel: "web",
                 visibility: "customer",
                 format: "plain_text",
                 body: command.body,
                 createdAt: now,
             };
-            const assistantTurn = assistantTurnOptions !== undefined &&
-                command.initialHandling === "assistant"
+            const assistantTurn = assistantTurnOptions !== undefined && initialHandling === "assistant"
                 ? await createAssistantTurnRecord(ticket, message, command.correlationId, assistantTurnOptions)
                 : undefined;
             const notificationJob = notification === undefined
                 ? undefined
                 : deliveryJobAction(command.ticketId, command.messageId, now, notification);
             const notificationContent = deliveryContent(notification);
-            const reservation = await reserveCustomerTicket(access.principalId, command.ticketId, now);
+            const reservation = await reserveCustomerTicket(principal(), command.ticketId, now);
             const existingReservation = await records.getVersioned(ticketReservationKey(command.ticketId));
             if (existingReservation?.value.kind === "ticket_reservation" &&
                 existingReservation.value.state === "committed" &&
@@ -3332,7 +3495,7 @@ export function createSupportDeskApplication(options) {
                         partition: command.ticketId,
                         id: "quota",
                         messageCount: 1,
-                        ...(command.initialHandling === "assistant"
+                        ...(initialHandling === "assistant"
                             ? { assistantManaged: true }
                             : {}),
                     },
@@ -3356,7 +3519,7 @@ export function createSupportDeskApplication(options) {
                     correlationId: command.correlationId,
                     ticketId: command.ticketId,
                     revision: ticket.revision,
-                    actorId: access.principalId,
+                    actorId: principal(),
                     occurredAt: now,
                     action: supportTicketAuditActions.created,
                 }),
@@ -3367,10 +3530,11 @@ export function createSupportDeskApplication(options) {
                         partition: command.ticketId,
                         id: `command:${command.commandId}`,
                         commandId: command.commandId,
-                        commandType: "create_customer_ticket",
+                        commandType,
                         messageId: command.messageId,
                         requestFingerprint: fingerprint,
                         completedAt: now,
+                        ...(admitted === undefined ? {} : { initialMode }),
                     },
                 },
                 ...(notificationJob === undefined ? [] : [notificationJob]),
@@ -3381,16 +3545,33 @@ export function createSupportDeskApplication(options) {
             // Create starts an empty partition; fail closed if the first write would
             // exceed the configured physical-record budget.
             enforcePartitionRecordLimit(0, limits.maxRecordsPerTicket, actions.length);
+            if (admitted !== undefined && verifyBeforeCommit !== undefined) {
+                authorizeAdmitted();
+                const assertCurrent = await waitForAdmission(() => verifyBeforeCommit(initialMode));
+                authorizeAdmitted();
+                if (assistantAccess !== undefined)
+                    authorizeAdmitted(assistantAccess, true);
+                if (typeof assertCurrent !== "function" || assertCurrent() !== true)
+                    throw new SupportDeskConflictError("Admitted create authority changed");
+            }
             const outcome = await records.transact(command.ticketId, actions);
             if (!outcome.committed) {
                 const existing = await records.get(commandKey(command.ticketId, command.commandId));
-                if (!duplicateMatches(existing, "create_customer_ticket", command.messageId, fingerprint)) {
+                if (!duplicateMatches(existing, commandType, command.messageId, fingerprint)) {
                     throw new SupportDeskConflictError();
                 }
+                // An exact competing commit recovers the winner's historical mode,
+                // using the same create/read-own authority as the early receipt path.
+                if (admitted !== undefined)
+                    initialMode = admittedCreateMode(existing);
             }
-            await confirmCustomerTicket(access.principalId, command.ticketId, reservation.reservationToken, reservation.reservationGeneration);
-            return customerViewAfterChange(access.principalId, command.ticketId, createThreading);
-        },
+            authorizeAdmitted();
+            await confirmCustomerTicket(principal(), command.ticketId, reservation.reservationToken, reservation.reservationGeneration);
+            authorizeAdmitted();
+            const view = await customerViewAfterChange(principal(), command.ticketId, createThreading);
+            authorizeAdmitted();
+            return { view, initialMode };
+        }),
         async replyToCustomerTicket(access, input) {
             requirePermission(access, supportPermissions.replyOwn);
             requireIdentifier(access.principalId, "principalId");