@pegma/support-desk-application 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -3,7 +3,29 @@ import { type AccessContext } from "@pegma/authorization-core";
 import { type MailJob } from "@pegma/mail";
 import type { Clock, IsoTimestamp, Logger, PrincipalId } from "@pegma/spine";
 import { type Store } from "@pegma/storage-core";
-import type { MessageId, RequesterAssociation, Ticket, TicketChannel, TicketId, TicketMessage, TicketPriority, TicketStatus } from "@pegma/support-desk-contracts";
+import type { InboundSenderAuthentication, MessageFormat, MessageId, RequesterAssociation, Ticket, TicketChannel, TicketId, TicketMessage, TicketPriority, TicketStatus, TicketHandling, TicketHandlingState } from "@pegma/support-desk-contracts";
+import type { AssistantTurnApplication, AssistantTurnOptions } from "./assistant-turn-types.js";
+import { type AssistantTurnRecord } from "./assistant-turn-records.js";
+import type { ResolutionLearningApplication, ResolutionLearningOptions, ResolutionLearningSourceResult } from "./resolution-learning-types.js";
+import type { EngineeringApplication, EngineeringOptions, EngineeringPolicyApplication } from "./engineering-types.js";
+import { type EngineeringSourceRecord, type EngineeringWorkRecord, type EngineeringReceiptRecord } from "./engineering-records.js";
+import type { EngineeringFollowupApplication, EngineeringFollowupOptions } from "./engineering-followup-types.js";
+import { type EngineeringFollowupRecord } from "./engineering-followup-records.js";
+import { type ResolutionLearningReviewRecord, type ResolutionLearningSourceRecord, type ResolutionLearningWorkRecord } from "./resolution-learning-records.js";
+export type * from "./resolution-learning-types.js";
+export type { ResolutionLearningReviewRecord, ResolutionLearningSourceRecord, ResolutionLearningWorkRecord, } from "./resolution-learning-records.js";
+export { resolutionLearningDeliveryBinding, resolutionLearningManifestHash, } from "./resolution-learning-worker.js";
+export type * from "./assistant-turn-types.js";
+export type { AssistantTurnRecord } from "./assistant-turn-records.js";
+export type { InboundSenderAuthentication };
+export type * from "./engineering-types.js";
+export type * from "./engineering-followup-types.js";
+export type { EngineeringFollowupHeadRecord, EngineeringFollowupWorkRecord, EngineeringFollowupReceiptRecord, EngineeringFollowupRecord, EngineeringFollowupPreparedBundle, EngineeringFollowupRetestSummary, } from "./engineering-followup-records.js";
+export { engineeringFollowupModelManifestHash, engineeringFollowupContextHash, engineeringFollowupPublicFactsHash, engineeringFollowupChecksBinding, engineeringFollowupRetestRequestId, engineeringFollowupRetestProductBinding, engineeringFollowupRetestRequestHash, engineeringFollowupRetestSummary, engineeringFollowupModelAttemptCount, } from "./engineering-followup-records.js";
+export type { EngineeringSourceRecord, EngineeringWorkRecord, EngineeringReceiptRecord, EngineeringPreparedProposal, } from "./engineering-records.js";
+export { engineeringPolicyRecords, engineeringPolicyAudit, engineeringPolicyAuditActions, createEngineeringPolicyServices, } from "./engineering-policy.js";
+export type { EngineeringPolicyOptions, EngineeringPolicyRecord, } from "./engineering-policy.js";
+export { engineeringModelManifestHash, engineeringRoutingBinding, engineeringExportChecksBinding, engineeringRoutingBindingHash, engineeringStaffSelectionHash, } from "./engineering-work.js";
 export declare const supportPermissions: Readonly<{
     readonly create: "support.ticket.create";
     readonly readOwn: "support.ticket.read.own";
@@ -14,6 +36,32 @@ export declare const supportPermissions: Readonly<{
     readonly assign: "support.ticket.assign";
     readonly manage: "support.ticket.manage";
     readonly auditRead: "support.audit.read";
+    readonly assistantStart: "support.ticket.assistant.start";
+    readonly assistantRead: "support.ticket.assistant.read";
+    readonly assistantReply: "support.ticket.assistant.reply";
+    readonly assistantEscalate: "support.ticket.assistant.escalate";
+    readonly requestPerson: "support.ticket.request_person.own";
+    readonly takeOver: "support.ticket.take_over";
+    readonly confirmSuccess: "support.ticket.confirm_success.own";
+    readonly learningRead: "support.learning.read";
+    readonly learningEvidenceSubmit: "support.learning.evidence.submit";
+    readonly learningProcess: "support.learning.process";
+    readonly learningReview: "support.learning.review";
+    readonly learningWithdraw: "support.learning.withdraw";
+    readonly engineeringRead: "support.engineering.read";
+    readonly engineeringEvidenceSubmit: "support.engineering.evidence.submit";
+    readonly engineeringProcess: "support.engineering.process";
+    readonly engineeringReview: "support.engineering.review";
+    readonly engineeringWithdraw: "support.engineering.withdraw";
+    readonly engineeringRestrictedRead: "support.engineering.restricted.read";
+    readonly engineeringSecurityReview: "support.engineering.security.review";
+    readonly engineeringReconcile: "support.engineering.reconcile";
+    readonly engineeringPolicyRead: "support.engineering.policy.read";
+    readonly engineeringPolicyManage: "support.engineering.policy.manage";
+    readonly engineeringFollowupRead: "support.engineering.followup.read";
+    readonly engineeringFollowupProcess: "support.engineering.followup.process";
+    readonly engineeringFollowupReview: "support.engineering.followup.review";
+    readonly engineeringFollowupEvidenceSubmit: "support.engineering.followup.evidence.submit";
 }>;
 export interface SupportDeskLimits {
     readonly maxSubjectCharacters: number;
@@ -38,10 +86,37 @@ export declare class SupportDeskNotFoundError extends Error {
 export declare class SupportDeskConflictError extends Error {
     constructor(message?: string);
 }
+/** Content-safe collision hint, available only after staff authorization. */
+export declare class SupportDeskStaleRevisionError extends SupportDeskConflictError {
+    readonly currentRevision: number;
+    readonly updatedAt: IsoTimestamp;
+    constructor(currentRevision: number, updatedAt: IsoTimestamp);
+}
+export interface ResponseTargets {
+    readonly firstResponseDueAt?: IsoTimestamp;
+    readonly resolutionDueAt?: IsoTimestamp;
+}
+/** Content-free facts; hosts own calendars, presence, and target calculation. */
+export interface ResponseTargetContext extends ResponseTargets {
+    readonly reason: "created" | "customer_replied" | "priority_changed";
+    readonly ticketId: TicketId;
+    readonly revision: number;
+    readonly priority: TicketPriority;
+    readonly category?: string;
+    readonly channel: TicketChannel;
+    readonly createdAt: IsoTimestamp;
+    readonly occurredAt: IsoTimestamp;
+    readonly firstStaffRespondedAt?: IsoTimestamp;
+    readonly resolvedAt?: IsoTimestamp;
+}
+export interface ResponseTargetPolicy {
+    /** Complete replacement of due timestamps. Must be safe to retry on conflicts. */
+    computeTargets(context: ResponseTargetContext): ResponseTargets | Promise<ResponseTargets>;
+}
 export declare class SupportDeskLimitError extends Error {
-    readonly field: "subject" | "body" | "customer_tickets" | "ticket_messages" | "ticket_partition";
+    readonly field: "subject" | "body" | "handoff_summary" | "serialized_record" | "customer_tickets" | "engineering_policy_records" | "engineering_policy_repositories" | "ticket_messages" | "ticket_partition";
     readonly maximum: number;
-    constructor(field: "subject" | "body" | "customer_tickets" | "ticket_messages" | "ticket_partition", maximum: number);
+    constructor(field: "subject" | "body" | "handoff_summary" | "serialized_record" | "customer_tickets" | "engineering_policy_records" | "engineering_policy_repositories" | "ticket_messages" | "ticket_partition", maximum: number);
 }
 /**
  * Staff queue online scan hit a configured materialization budget before the
@@ -67,6 +142,12 @@ export interface DeliveryContent {
     readonly variables: Readonly<Record<string, string>>;
     readonly subject: string;
     readonly outboundMessageId: string;
+    /**
+     * Optional host-minted opaque reply-routing token rendered into the reply
+     * address. Indexed by SHA-256 in `support-desk.thread-index.v1`; never a
+     * read capability and never logged.
+     */
+    readonly replyRoutingToken?: string;
 }
 interface TicketRecord {
     readonly kind: "ticket";
@@ -93,7 +174,7 @@ interface AuditMemberRecord {
     readonly id: string;
     readonly event: AuditEvent;
 }
-type SupportCommandType = "create_customer_ticket" | "reply_customer_ticket" | "staff_reply" | "add_note" | "assign_ticket" | "change_priority" | "resolve_ticket" | "close_ticket" | "reopen_ticket";
+type SupportCommandType = "create_customer_ticket" | "reply_customer_ticket" | "staff_reply" | "add_note" | "assign_ticket" | "change_priority" | "set_tags" | "resolve_ticket" | "close_ticket" | "reopen_ticket" | "inbound_email_create" | "inbound_email_reply" | "assistant_reply" | "assistant_escalate" | "request_person" | "take_over" | "confirm_customer_success";
 interface CommandRecord {
     readonly kind: "command";
     readonly partition: TicketId;
@@ -107,12 +188,78 @@ interface CommandRecord {
     readonly messageId?: MessageId;
     readonly requestFingerprint: string;
     readonly completedAt: IsoTimestamp;
+    /** New staff commands retain their result; messages are selected by revision. */
+    readonly resultTicket?: Ticket;
+}
+interface InboundReplyRerouteFenceRecord {
+    readonly kind: "inbound_reply_reroute_fence";
+    readonly partition: TicketId;
+    readonly id: string;
+    readonly commandId: string;
+    readonly messageId: MessageId;
+    readonly requestFingerprint: string;
+    readonly recordedAt: IsoTimestamp;
+}
+interface InboundCreateRerouteFenceRecord {
+    readonly kind: "inbound_create_reroute_fence";
+    readonly partition: TicketId;
+    readonly id: string;
+    readonly commandId: string;
+    readonly messageId: MessageId;
+    readonly requestFingerprint: string;
+    readonly recordedAt: IsoTimestamp;
 }
 interface TicketQuotaRecord {
     readonly kind: "ticket_quota";
     readonly partition: TicketId;
     readonly id: "quota";
     readonly messageCount: number;
+    /** Only explicitly opted-in web conversations reserve human completion capacity. */
+    readonly assistantManaged?: true;
+}
+export type AssistantEscalationReason = "no_guidance" | "unsuccessful" | "capacity" | "provider_failure" | "other";
+export interface HandoffWorkRecord {
+    readonly kind: "handoff_work";
+    readonly partition: TicketId;
+    readonly id: string;
+    readonly status: "pending";
+    readonly reason: AssistantEscalationReason | "customer_requested" | "email_reply";
+    readonly summary?: string;
+    readonly attemptedGuideIds: readonly string[];
+    readonly transcript: {
+        readonly ticketId: TicketId;
+        readonly throughRevision: number;
+        readonly lastVisibleMessageId: MessageId;
+    };
+    readonly handlingGeneration: number;
+    readonly createdAt: IsoTimestamp;
+}
+/** Staff-only handoff context, separate from message/replay and assistant DTOs. */
+export interface HandoffWorkDto {
+    readonly ticketId: TicketId;
+    readonly workId: string;
+    readonly status: HandoffWorkRecord["status"];
+    readonly reason: HandoffWorkRecord["reason"];
+    readonly summary?: string;
+    readonly attemptedGuideIds: readonly string[];
+    readonly transcript: HandoffWorkRecord["transcript"];
+    readonly handlingGeneration: number;
+    readonly createdAt: IsoTimestamp;
+}
+export interface CustomerSuccessConfirmation {
+    readonly commandId: string;
+    readonly ticketId: TicketId;
+    readonly confirmedBy: PrincipalId;
+    readonly confirmedAt: IsoTimestamp;
+    readonly lastSeenVisibleMessageId: MessageId;
+    readonly revision: number;
+    readonly handlingGeneration: number;
+    readonly resolutionCycle?: number;
+}
+interface CustomerSuccessRecord extends CustomerSuccessConfirmation {
+    readonly kind: "customer_success";
+    readonly partition: TicketId;
+    readonly id: string;
 }
 interface TicketReservationRecord {
     readonly kind: "ticket_reservation";
@@ -122,7 +269,13 @@ interface TicketReservationRecord {
     readonly generation: number;
     readonly state: "committed" | "cancelled";
 }
-export type SupportRecord = TicketRecord | TicketQuotaRecord | TicketReservationRecord | MessageRecord | AuditMemberRecord | CommandRecord | DeliveryJob;
+export type SupportRecord = EngineeringFollowupRecord | EngineeringSourceRecord | EngineeringWorkRecord | EngineeringReceiptRecord | ResolutionLearningSourceRecord | ResolutionLearningWorkRecord | ResolutionLearningReviewRecord | {
+    readonly kind: "resolution_learning_receipt";
+    readonly partition: string;
+    readonly id: string;
+    readonly fingerprint: string;
+    readonly result: ResolutionLearningSourceResult;
+} | AssistantTurnRecord | TicketRecord | TicketQuotaRecord | TicketReservationRecord | MessageRecord | AuditMemberRecord | CommandRecord | InboundReplyRerouteFenceRecord | InboundCreateRerouteFenceRecord | HandoffWorkRecord | CustomerSuccessRecord | DeliveryJob;
 /** Closed MVP registry of durable accepted-change audit action names. */
 export declare const supportTicketAuditActions: Readonly<{
     readonly created: "support.ticket.created";
@@ -132,9 +285,38 @@ export declare const supportTicketAuditActions: Readonly<{
     readonly assigned: "support.ticket.assigned";
     readonly unassigned: "support.ticket.unassigned";
     readonly priorityChanged: "support.ticket.priority_changed";
+    readonly tagsChanged: "support.ticket.tags_changed";
     readonly resolved: "support.ticket.resolved";
     readonly closed: "support.ticket.closed";
     readonly reopened: "support.ticket.reopened";
+    readonly assistantReplied: "support.ticket.assistant_replied";
+    readonly humanRequested: "support.ticket.human_requested";
+    readonly humanEscalated: "support.ticket.human_escalated";
+    readonly humanTakenOver: "support.ticket.human_taken_over";
+    readonly customerSuccessConfirmed: "support.ticket.customer_success_confirmed";
+    readonly learningEnrolled: "support.learning.enrolled";
+    readonly learningEvidenceRecorded: "support.learning.evidence_recorded";
+    readonly learningEvidenceInvalidated: "support.learning.evidence_invalidated";
+    readonly learningWithdrawn: "support.learning.withdrawn";
+    readonly learningReviewed: "support.learning.reviewed";
+    readonly engineeringEnrolled: "support.engineering.enrolled";
+    readonly engineeringEvidenceRecorded: "support.engineering.evidence_recorded";
+    readonly engineeringEvidenceInvalidated: "support.engineering.evidence_invalidated";
+    readonly engineeringWithdrawn: "support.engineering.withdrawn";
+    readonly engineeringRepositorySelected: "support.engineering.repository_selected";
+    readonly engineeringProposalPrepared: "support.engineering.proposal_prepared";
+    readonly engineeringReviewed: "support.engineering.reviewed";
+    readonly engineeringDispatchStarted: "support.engineering.dispatch_started";
+    readonly engineeringExportRecorded: "support.engineering.export_recorded";
+    readonly engineeringReconciled: "support.engineering.reconciled";
+    readonly engineeringFollowupObserved: "support.engineering.followup.observed";
+    readonly engineeringFollowupBundlePrepared: "support.engineering.followup.bundle_prepared";
+    readonly engineeringFollowupReassessed: "support.engineering.followup.reassessed";
+    readonly engineeringFollowupRetried: "support.engineering.followup.retried";
+    readonly engineeringFollowupAbandoned: "support.engineering.followup.abandoned";
+    readonly engineeringFollowupRejected: "support.engineering.followup.rejected";
+    readonly engineeringFollowupNoticePosted: "support.engineering.followup.notice_posted";
+    readonly engineeringFollowupRetestRecorded: "support.engineering.followup.retest_recorded";
 }>;
 export interface CustomerTicketIndexEntry {
     readonly ticketId: TicketId;
@@ -155,15 +337,61 @@ export interface InboundReceipt {
     readonly providerEventId: string;
     readonly externalMessageId?: string;
     readonly payloadFingerprint: string;
-    readonly status: "processing" | "processed" | "rejected";
+    /** Canonical replay hash; absent on receipts written by earlier versions. */
+    readonly replayFingerprint?: string;
+    /** `rerouting` is a resumable claim used only to normalize an older route. */
+    readonly status: "processing" | "rerouting" | "processed" | "rejected";
     /** Trusted host time at which processing first reserved this receipt. */
     readonly receivedAt: IsoTimestamp;
     /** Trusted host time at which processing reached a terminal status. */
     readonly processedAt?: IsoTimestamp;
+    /** Resulting ticket; present only on a terminal receipt that names one. */
     readonly ticketId?: TicketId;
+    /** Resulting message; present only on a terminal receipt that names one. */
     readonly messageId?: MessageId;
     readonly diagnostic?: string;
+    /**
+     * Host-minted ticket ID reserved by the first delivery. Every retry of the
+     * same provider event reuses it instead of the retry's own identifiers.
+     */
+    readonly reservedTicketId?: TicketId;
+    /** Host-minted message ID reserved by the first delivery. */
+    readonly reservedMessageId?: MessageId;
+    readonly correlationId?: string;
+    /**
+     * First routing decision. Ordinary replays retain it; processing receipts
+     * written by older versions may be normalized before ticket work resumes.
+     */
+    readonly route?: InboundReceiptRoute;
+    readonly outcome?: InboundEmailOutcome;
 }
+/** How inbound mail was associated with an existing ticket, if at all. */
+export type InboundMatchMethod = "routing_token" | "message_id" | "subject_marker" | "none";
+/** Coarse, content-free reason an inbound message created no message. */
+export type InboundSuppressionReason = "auto_submitted" | "precedence" | "auto_reply_header" | "bounce" | "delivery_report" | "support_address_loop";
+export type InboundEmailOutcome = "created" | "replied" | "duplicate_message" | "suppressed" | "rejected";
+/** Routing decision persisted on the receipt before any ticket work. */
+export type InboundReceiptRoute = {
+    readonly kind: "suppressed";
+    readonly reason: InboundSuppressionReason;
+} | {
+    readonly kind: "duplicate_message";
+    readonly ticketId: TicketId;
+    readonly messageId: MessageId;
+} | {
+    readonly kind: "reply";
+    readonly ticketId: TicketId;
+    readonly matchMethod: Exclude<InboundMatchMethod, "none">;
+} | {
+    readonly kind: "new_conversation";
+    readonly ticketId: TicketId;
+    readonly matchMethod: InboundMatchMethod;
+    readonly association: "matched_email" | "unverified";
+    readonly principalId?: PrincipalId;
+    readonly priority: InboundRoutingPriority;
+    readonly category?: string;
+    readonly relatedTicketId?: TicketId;
+};
 export interface DeliveryCallbackInput {
     readonly provider: string;
     readonly providerEventId: string;
@@ -221,10 +449,16 @@ export interface QueueIndexRecord {
     readonly status: TicketStatus;
     readonly priority: TicketPriority;
     readonly category?: string;
+    readonly tags?: readonly string[];
+    readonly firstResponseDueAt?: IsoTimestamp;
+    readonly resolutionDueAt?: IsoTimestamp;
+    readonly firstStaffRespondedAt?: IsoTimestamp;
+    readonly resolvedAt?: IsoTimestamp;
     readonly requesterAssociation: RequesterAssociation;
     readonly channel: TicketChannel;
     readonly assignedTo?: PrincipalId;
     readonly updatedAt: IsoTimestamp;
+    readonly handling?: TicketHandling;
 }
 export declare const queueIndex: import("@pegma/storage-core").CollectionDefinition<QueueIndexRecord>;
 /** Default terminal-retention cutoff shared by projection, repair, and sweep. */
@@ -255,6 +489,13 @@ export interface NotificationInput {
     readonly subject: string;
     readonly outboundMessageId: string;
     readonly maxAttempts?: number;
+    /**
+     * Optional opaque reply-routing token the host renders into this
+     * notification's reply address: 22 to 128 URL-safe base64 characters from
+     * a cryptographically random source (at least 128 bits). Support Desk
+     * indexes it so an inbound reply can be matched by key lookup.
+     */
+    readonly replyRoutingToken?: string;
 }
 export interface CreateCustomerTicketCommand {
     readonly commandId: string;
@@ -267,6 +508,7 @@ export interface CreateCustomerTicketCommand {
     readonly category?: string;
     readonly requesterEmail?: string;
     readonly notification?: NotificationInput;
+    readonly initialHandling?: "assistant";
 }
 /**
  * Instance-scoped positive ticket-number counter.
@@ -298,6 +540,7 @@ export interface CustomerTicketSummary {
     readonly channel: Ticket["channel"];
     readonly createdAt: Ticket["createdAt"];
     readonly customerUpdatedAt: Ticket["customerUpdatedAt"];
+    readonly handling?: TicketHandlingState;
 }
 /**
  * Customer-safe conversation fields. Omits principal IDs and provider
@@ -326,7 +569,58 @@ export interface StaffTicketView {
     readonly ticket: Ticket;
     readonly messages: readonly TicketMessage[];
 }
-export interface StaffReplyCommand {
+/** Service-only safe conversation; never includes staff notes or requester identity. */
+export interface AssistantConversationView extends CustomerTicketView {
+    readonly revision: number;
+    readonly handling: TicketHandling;
+    readonly triggerMessageId?: MessageId;
+}
+export interface AssistantTurnFence {
+    readonly commandId: string;
+    readonly correlationId: string;
+    readonly ticketId: TicketId;
+    readonly expectedRevision: number;
+    readonly expectedHandlingGeneration: number;
+    readonly triggerMessageId: MessageId;
+}
+export interface AssistantReplyCommand extends AssistantTurnFence {
+    readonly messageId: MessageId;
+    readonly body: string;
+}
+export interface AssistantEscalationCommand extends AssistantTurnFence {
+    readonly reason?: AssistantEscalationReason;
+    readonly summary?: string;
+    readonly attemptedGuideIds?: readonly string[];
+}
+export interface HandlingCommandResult {
+    readonly ticketId: TicketId;
+    readonly revision: number;
+    readonly handlingGeneration: number;
+    readonly messageId?: MessageId;
+}
+export interface RequestPersonCommand {
+    readonly commandId: string;
+    readonly correlationId: string;
+    readonly ticketId: TicketId;
+}
+export interface TakeOverTicketCommand extends RequestPersonCommand {
+    readonly expectedRevision: number;
+    readonly expectedHandlingGeneration: number;
+}
+export interface ConfirmCustomerSuccessCommand extends RequestPersonCommand {
+    readonly lastSeenVisibleMessageId: MessageId;
+}
+export interface StaffRevisionHint {
+    /** Omit to retain automatic conflict retries; supplied values must match. */
+    readonly expectedRevision?: number;
+}
+export interface SetTagsCommand extends StaffRevisionHint {
+    readonly commandId: string;
+    readonly correlationId: string;
+    readonly ticketId: TicketId;
+    readonly tags: readonly string[];
+}
+export interface StaffReplyCommand extends StaffRevisionHint {
     readonly commandId: string;
     readonly correlationId: string;
     readonly ticketId: TicketId;
@@ -334,14 +628,14 @@ export interface StaffReplyCommand {
     readonly body: string;
     readonly notification?: NotificationInput;
 }
-export interface AddNoteCommand {
+export interface AddNoteCommand extends StaffRevisionHint {
     readonly commandId: string;
     readonly correlationId: string;
     readonly ticketId: TicketId;
     readonly messageId: MessageId;
     readonly body: string;
 }
-export interface AssignTicketCommand {
+export interface AssignTicketCommand extends StaffRevisionHint {
     readonly commandId: string;
     readonly correlationId: string;
     readonly ticketId: TicketId;
@@ -356,13 +650,13 @@ export interface AssignTicketCommand {
     readonly body?: string;
     readonly notification?: NotificationInput;
 }
-export interface ChangePriorityCommand {
+export interface ChangePriorityCommand extends StaffRevisionHint {
     readonly commandId: string;
     readonly correlationId: string;
     readonly ticketId: TicketId;
     readonly priority: TicketPriority;
 }
-export interface LifecycleTicketCommand {
+export interface LifecycleTicketCommand extends StaffRevisionHint {
     readonly commandId: string;
     readonly correlationId: string;
     readonly ticketId: TicketId;
@@ -381,6 +675,14 @@ export interface LifecycleTicketCommand {
  * confirmation. Storage never filters or sorts projection rows.
  */
 export interface StaffQueueQuery {
+    /** Human work is the default; assistant/all are explicit supervision views. */
+    readonly handling?: "human" | "assistant" | "all";
+    readonly tag?: string;
+    /** Target filters and due sorting default to resolution. */
+    readonly target?: "first_response" | "resolution";
+    readonly targetState?: "overdue" | "due_soon";
+    /** Required for due_soon; inclusive horizon, at most 30 days. */
+    readonly dueSoonMilliseconds?: number;
     readonly status?: TicketStatus | readonly TicketStatus[];
     readonly priority?: TicketPriority | readonly TicketPriority[];
     readonly association?: RequesterAssociation | readonly RequesterAssociation[];
@@ -389,15 +691,21 @@ export interface StaffQueueQuery {
     readonly assignedTo?: PrincipalId;
     readonly unassignedOnly?: boolean;
     /** Newest updates first is the default staff presentation. */
-    readonly sort?: "updated_newest" | "updated_oldest";
+    readonly sort?: "updated_newest" | "updated_oldest" | "due_soonest" | "due_latest";
 }
 /** Confirmed active ticket summary for the staff queue surface. */
 export interface StaffQueueItem {
+    readonly handling: TicketHandlingState;
     readonly ticketId: TicketId;
     readonly revision: number;
     readonly status: TicketStatus;
     readonly priority: TicketPriority;
     readonly category?: string;
+    readonly tags?: readonly string[];
+    readonly firstResponseDueAt?: IsoTimestamp;
+    readonly resolutionDueAt?: IsoTimestamp;
+    readonly firstStaffRespondedAt?: IsoTimestamp;
+    readonly resolvedAt?: IsoTimestamp;
     readonly requesterAssociation: RequesterAssociation;
     readonly channel: TicketChannel;
     readonly assignedTo?: PrincipalId;
@@ -427,7 +735,15 @@ export interface QueueInactiveSweepResult {
     readonly physicalRows: number;
     readonly deleted: number;
 }
-export interface SupportDeskApplication {
+export interface SupportDeskApplication extends AssistantTurnApplication, ResolutionLearningApplication, EngineeringApplication, EngineeringFollowupApplication, EngineeringPolicyApplication {
+    readHandoffWork(access: AccessContext, ticketId: TicketId): Promise<readonly HandoffWorkDto[]>;
+    readAssistantConversation(access: AccessContext, ticketId: TicketId): Promise<AssistantConversationView>;
+    replyAsAssistant(access: AccessContext, command: AssistantReplyCommand): Promise<HandlingCommandResult>;
+    escalateToHuman(access: AccessContext, command: AssistantEscalationCommand): Promise<HandlingCommandResult>;
+    requestPerson(access: AccessContext, command: RequestPersonCommand): Promise<CustomerTicketView>;
+    takeOverTicket(access: AccessContext, command: TakeOverTicketCommand): Promise<StaffTicketView>;
+    confirmCustomerSuccess(access: AccessContext, command: ConfirmCustomerSuccessCommand): Promise<CustomerTicketView>;
+    readCustomerSuccessConfirmations(access: AccessContext, ticketId: TicketId): Promise<readonly CustomerSuccessConfirmation[]>;
     createCustomerTicket(access: AccessContext, command: CreateCustomerTicketCommand): Promise<CustomerTicketView>;
     replyToCustomerTicket(access: AccessContext, command: ReplyToCustomerTicketCommand): Promise<CustomerTicketView>;
     listCustomerTickets(access: AccessContext): Promise<readonly CustomerTicketSummary[]>;
@@ -447,12 +763,15 @@ export interface SupportDeskApplication {
     addNote(access: AccessContext, command: AddNoteCommand): Promise<StaffTicketView>;
     assignTicket(access: AccessContext, command: AssignTicketCommand): Promise<StaffTicketView>;
     changePriority(access: AccessContext, command: ChangePriorityCommand): Promise<StaffTicketView>;
+    setTags(access: AccessContext, command: SetTagsCommand): Promise<StaffTicketView>;
     resolveTicket(access: AccessContext, command: LifecycleTicketCommand): Promise<StaffTicketView>;
     closeTicket(access: AccessContext, command: LifecycleTicketCommand): Promise<StaffTicketView>;
     reopenTicket(access: AccessContext, command: LifecycleTicketCommand): Promise<StaffTicketView>;
     readTicketAuditHistory(access: AccessContext, ticketId: TicketId): Promise<readonly AuditEvent[]>;
 }
 export declare function validateOutboundMessageId(value: string, field?: string): string;
+export declare const assistantHumanReserveRows = 12;
+export declare const assistantHumanReserveMessages = 1;
 export interface ProjectTicketToQueueOptions {
     readonly store: Store;
     readonly clock: Clock;
@@ -503,6 +822,22 @@ export declare function createSupportDeskApplication(options: {
      * At most 32 values matching `^[a-z][a-z0-9_]{0,31}$`.
      */
     readonly allowedCategories?: readonly string[];
+    /** At most 32 normalized, deduplicated staff labels; absent disables adding tags. */
+    readonly allowedTags?: readonly string[];
+    /** Default 8, hard maximum 32. Empty tags always clear the ticket. */
+    readonly maxTagsPerTicket?: number;
+    readonly responseTargetPolicy?: ResponseTargetPolicy;
+    readonly assistantHandlingEnabled?: boolean;
+    /** Optional durable scheduling; absent retains the SD-01 manual assistant seam. */
+    readonly assistantTurns?: AssistantTurnOptions;
+    readonly resolutionLearning?: ResolutionLearningOptions;
+    readonly engineering?: EngineeringOptions;
+    readonly engineeringFollowup?: EngineeringFollowupOptions;
+    readonly engineeringPolicy?: {
+        readonly maxRepositories?: number;
+        readonly maxRecords?: number;
+        readonly historyRetentionMilliseconds?: number;
+    };
 }): SupportDeskApplication;
 export declare function inboundReceiptLocation(channelId: string, providerEventId: string): Promise<{
     readonly bucket: string;
@@ -531,5 +866,265 @@ export declare function sweepDeliveryCallbackReceipts(store: Store, clock: Clock
 export declare function pruneCustomerTicketIndex(store: Store, principalId: PrincipalId, input: {
     readonly reservedBefore: IsoTimestamp;
 }): Promise<readonly TicketId[]>;
-export {};
+/** Which looked-up identifier a thread-index row resolves. */
+export type ThreadIndexKind = "message_id" | "reply_token" | "ticket_number";
+/**
+ * One key-lookup hint from an external identifier to a ticket.
+ *
+ * Partitions are `mid:<sha256>` for a `Message-ID`, `rt:<sha256>` for an
+ * opaque reply-routing token, and `number:<n>` for an instance ticket number,
+ * so every partition holds exactly one row and nothing grows without bound.
+ * A row is never authorization evidence: every lookup reloads the causal
+ * authoritative ticket or message and re-derives the row before trusting it.
+ * The reply token itself is never stored here, only its hash.
+ */
+export interface ThreadIndexRecord {
+    /** Physical partition (see above). */
+    readonly key: string;
+    readonly id: "thread";
+    readonly kind: ThreadIndexKind;
+    readonly ticketId: TicketId;
+    /** Causal message for `message_id` and `reply_token` rows. */
+    readonly messageId?: MessageId;
+    /** Who generated an indexed `Message-ID`. */
+    readonly source?: "outbound" | "inbound";
+    /** Authoritative creation time of the causal message or ticket. */
+    readonly issuedAt: IsoTimestamp;
+}
+export declare const threadIndex: import("@pegma/storage-core").CollectionDefinition<ThreadIndexRecord>;
+/**
+ * Default lifetime of `Message-ID` and reply-token threading rows. Lookups,
+ * repair, and sweeping all treat older rows as absent; ticket-number rows
+ * live as long as their ticket.
+ */
+export declare const defaultThreadIndexRetentionMilliseconds: number;
+/** Actor recorded on Audit events accepted from verified inbound mail. */
+export declare const inboundEmailSystemActorId = "support-desk.inbound-email";
+export interface ThreadIndexWorkerOptions {
+    readonly store: Store;
+    readonly clock: Clock;
+    /**
+     * Shared lifetime for `Message-ID` and reply-token rows. Hosts pass the
+     * value configured on the inbound processor to every repair and sweep
+     * invocation (no silent per-worker default).
+     */
+    readonly threadIndexRetentionMilliseconds: number;
+    /** Opaque adapter-issued continuation; omit to begin a new cycle. */
+    readonly cursor?: string;
+    /** Physical records per page; at most {@link MAX_SCAN_PAGE_SIZE}. */
+    readonly limit?: number;
+}
+export interface ThreadIndexRepairPageResult {
+    /** Host-persisted only after this whole page succeeds. */
+    readonly nextCursor: string | null;
+    readonly physicalRows: number;
+    readonly indexed: number;
+    readonly collisions: number;
+}
+export interface ThreadIndexSweepPageResult {
+    readonly nextCursor: string | null;
+    readonly physicalRows: number;
+    readonly deleted: number;
+}
+/**
+ * Scan one page of authoritative `support-desk.records.v1` rows and insert
+ * every thread-index row they imply (ticket numbers, outbound `Message-ID`s,
+ * reply tokens, and inbound `Message-ID`s). Rows past retention are not
+ * recreated. Hosts persist `nextCursor` only after the whole page succeeds
+ * and repeat complete cycles.
+ */
+export declare function repairThreadIndexPage(options: ThreadIndexWorkerOptions): Promise<ThreadIndexRepairPageResult>;
+/**
+ * Scan one page of thread-index rows and conditionally delete every row whose
+ * authoritative target is gone, no longer derives it, or is past retention.
+ * Uses `deleteIfUnchanged` with the scanned version.
+ */
+export declare function sweepThreadIndexPage(options: ThreadIndexWorkerOptions): Promise<ThreadIndexSweepPageResult>;
+/**
+ * Loop and bounce signals the host adapter copies from verified headers or
+ * the SMTP envelope. Support Desk only inspects them; it never stores them.
+ */
+export interface InboundLoopSignals {
+    /** RFC 3834 `Auto-Submitted`; any value other than `no` suppresses. */
+    readonly autoSubmitted?: string;
+    /** `Precedence`; `bulk`, `junk`, `list`, or `auto_reply` suppresses. */
+    readonly precedence?: string;
+    /**
+     * `X-Auto-Response-Suppress`; `All`, `OOF`, or `AutoReply` keeps the message
+     * but forbids an automatic acknowledgement to the sender.
+     */
+    readonly autoResponseSuppress?: string;
+    /** True when `X-Autoreply`, `X-Autorespond`, or a similar header exists. */
+    readonly autoReplyHeaderPresent?: boolean;
+    /** `List-Id`; keeps the message but forbids an acknowledgement. */
+    readonly listId?: string;
+    /** Top-level `Content-Type`; `multipart/report` and delivery-status suppress. */
+    readonly contentType?: string;
+    /** SMTP envelope sender (`Return-Path`); empty or `<>` is a bounce. */
+    readonly envelopeSender?: string;
+}
+/**
+ * Provider-neutral inbound message, produced by a host adapter only after it
+ * verified the provider webhook or delivery mechanism, bounded MIME parsing,
+ * and reduced the content to safe plain text or constrained Markdown.
+ *
+ * Sender and content fields are hostile sender-controlled data. Identifiers
+ * are host-minted, and `senderAuthentication` is a host-evaluated result from
+ * trusted post-verification evidence. Raw MIME and HTML never belong here.
+ * There is deliberately no principal, role, plan, priority, or session field:
+ * sender authentication permits an email reply join but never establishes web
+ * identity or access.
+ */
+export interface InboundEmailInput {
+    /** Host mailbox or channel identifier (an opaque name, not an address). */
+    readonly channelId: string;
+    /** Provider's stable event or delivery identifier for deduplication. */
+    readonly providerEventId: string;
+    /** Server-minted ID used only if this event creates a new ticket. */
+    readonly ticketId: TicketId;
+    /** Server-minted ID for the message this event may create. */
+    readonly messageId: MessageId;
+    readonly correlationId: string;
+    /** Sender address chosen by the host adapter; routing input only. */
+    readonly from: string;
+    /** Host-evaluated sender result bound to the normalized `from` address. */
+    readonly senderAuthentication?: InboundSenderAuthentication;
+    /** Untrusted display name; stored for staff context only. */
+    readonly fromName?: string;
+    /** Decoded subject; controls collapse and it is cut to the subject limit. */
+    readonly subject: string;
+    /** Normalized safe text with quoted history already bounded by the host. */
+    readonly body: string;
+    readonly format?: MessageFormat;
+    /** The inbound message's own `Message-ID`. */
+    readonly externalMessageId?: string;
+    readonly inReplyTo?: string;
+    /** `References`, oldest first; only the newest entries are consulted. */
+    readonly references?: readonly string[];
+    /** Candidate opaque token the host extracted from the reply address. */
+    readonly replyRoutingToken?: string;
+    readonly loopSignals?: InboundLoopSignals;
+}
+/** Host account-email lookup result. Only `one` yields `matched_email`. */
+export type InboundSenderMatch = {
+    readonly matches: "none";
+} | {
+    readonly matches: "one";
+    readonly principalId: PrincipalId;
+} | {
+    readonly matches: "many";
+};
+/**
+ * Host port that compares a sender address with known accounts. The answer
+ * routes a ticket; it never authenticates the sender, never grants web
+ * access, and is never used to choose an `AccessContext`.
+ */
+export interface InboundAccountMatcher {
+    matchSenderEmail(input: {
+        readonly channelId: string;
+        readonly email: string;
+    }): Promise<InboundSenderMatch>;
+}
+/** Inbound mail may never be automatically assigned `urgent`. */
+export type InboundRoutingPriority = Exclude<TicketPriority, "urgent">;
+/** Content-free routing facts. Subject and body are deliberately absent. */
+export interface InboundRoutingInput {
+    readonly channelId: string;
+    readonly association: "matched_email" | "unverified";
+    /** Present only for `matched_email`; routing context, not identity. */
+    readonly principalId?: PrincipalId;
+    readonly relatedTicketId?: TicketId;
+}
+export interface InboundRoutingDecision {
+    readonly priority: InboundRoutingPriority;
+    /** Optional category from the processor's configured allowlist. */
+    readonly category?: string;
+}
+/** Host policy for a new inbound conversation (paid/unpaid tables live here). */
+export interface InboundRoutingPolicy {
+    routeNewConversation(input: InboundRoutingInput): InboundRoutingDecision | Promise<InboundRoutingDecision>;
+}
+export interface InboundNotificationContext {
+    readonly outcome: "created" | "replied";
+    readonly channelId: string;
+    readonly ticketId: TicketId;
+    readonly ticketNumber: number;
+    readonly messageId: MessageId;
+    readonly association: RequesterAssociation;
+    readonly matchMethod: InboundMatchMethod;
+    readonly assignedTo?: PrincipalId;
+    /**
+     * False when the sender asked for no automatic responses or the message
+     * came through a list. Hosts must then not acknowledge the sender; a staff
+     * notification is still allowed.
+     */
+    readonly senderAcknowledgementAllowed: boolean;
+}
+/**
+ * Optional host port returning one notification to commit in the same ticket
+ * transaction as the inbound message (for example a staff alert). Never
+ * called for suppressed, duplicate, or rejected mail.
+ */
+export interface InboundNotificationPolicy {
+    notificationFor(context: InboundNotificationContext): NotificationInput | undefined | Promise<NotificationInput | undefined>;
+}
+export interface InboundEmailResult {
+    /** True when this provider event already had a receipt. */
+    readonly duplicateDelivery: boolean;
+    readonly outcome: InboundEmailOutcome;
+    readonly ticketId?: TicketId;
+    readonly messageId?: MessageId;
+    readonly matchMethod?: InboundMatchMethod;
+    /** Requester association of a newly created ticket. */
+    readonly association?: RequesterAssociation;
+    readonly relatedTicketId?: TicketId;
+    /** Coarse content-free reason for `suppressed` or `rejected`. */
+    readonly reason?: string;
+}
+export interface InboundMailProcessorOptions {
+    readonly store: Store;
+    readonly clock: Clock;
+    readonly logger?: Logger;
+    readonly accountMatcher: InboundAccountMatcher;
+    readonly routingPolicy: InboundRoutingPolicy;
+    readonly notificationPolicy?: InboundNotificationPolicy;
+    /** Same limits as the application; subject and body bounds apply here. */
+    readonly limits?: Partial<SupportDeskLimits>;
+    readonly maxConflictAttempts?: number;
+    /** Must equal the application's queue terminal-retention cutoff. */
+    readonly queueTerminalRetentionMilliseconds?: number;
+    /** Lifetime of `Message-ID` and reply-token rows; defaults to 365 days. */
+    readonly threadIndexRetentionMilliseconds?: number;
+    /** Frozen category allowlist for host routing decisions. */
+    readonly allowedCategories?: readonly string[];
+    readonly responseTargetPolicy?: ResponseTargetPolicy;
+    /**
+     * Instance subject-marker prefix, for example `SD` for `[SD-1042]`. Without
+     * one, subject-marker fallback is disabled.
+     */
+    readonly subjectMarkerPrefix?: string;
+    /** This instance's own support addresses; mail from them is a loop. */
+    readonly supportAddresses?: readonly string[];
+}
+export interface InboundMailProcessor {
+    /**
+     * Deduplicate, route, and record one verified inbound message. Safe to
+     * retry with the same provider event: a retry resumes the first delivery's
+     * reserved identifiers and routing decision and returns its result.
+     */
+    processInboundEmail(input: InboundEmailInput): Promise<InboundEmailResult>;
+}
+/**
+ * Create the inbound mail processor a host's mail worker calls after it has
+ * verified provider authenticity and normalized bounded MIME content.
+ *
+ * Processing order: reserve the provider-event receipt with `insertIfAbsent`
+ * before any ticket work; suppress bounce and auto-reply loops; persist one
+ * routing decision on the receipt (routing token, then `In-Reply-To` /
+ * `References`, then subject marker, each confirmed against authoritative
+ * records); then create or reply in one ticket-partition transaction with
+ * its Audit event, command receipt, and optional notification; finally mark
+ * the receipt terminal and refresh the queue and threading projections.
+ */
+export declare function createInboundMailProcessor(options: InboundMailProcessorOptions): InboundMailProcessor;
 //# sourceMappingURL=index.d.ts.map