@pegma/support-desk-application 0.1.1 → 0.2.0

package/README.md

@@ -3,6 +3,84 @@
 Authorized customer ticket services and provider-neutral durable outbox
 records for Support Desk. The host supplies an `@pegma/storage-core` `Store`
 and a trusted Authorization Core access context.
+The host server supplies `correlationId` on commands; the application validates
+and propagates it and never generates it.
+
+The synchronized source candidate is `0.2.0` and includes changes beyond the
+published `0.1.1` artifacts. SD-01 adds handling/handoff foundations
+without model generation or a KB dependency; source review/tests determine
+completion. Host adoption requires the later synchronized SD-06 release and
+activation gates, not a source checkout or overwritten registry version.
+
+SD-02's merged source adds opt-in `assistantTurns` and the
+`AssistantTurnApplication` methods `scanAssistantTurnCandidates`,
+`claimAssistantTurn`, `prepareAssistantTurnAttempt`, `completeAssistantTurn`,
+and `finishAssistantTurnAttempt`. These keep bounded causal turn work beside
+the ticket and expose fixed answer/escalation completion with a read-only
+validation guard. They add no KB or provider dependency to this package;
+the optional `@pegma/support-desk-ai` coordinator owns those integrations.
+Lease/preparation/retry metadata do not bump Ticket revision, exact receipts recover
+ambiguous commits, and request-person/takeover remain provider-independent.
+See the [layout checkpoint](../../docs/COLLECTIONS.md#sd-02-assistant-turn-layout-checkpoint)
+and [coordination guide](../../docs/ASSISTANT_COORDINATION.md). Current-head
+tests/review and future verified SD-06 publication remain required.
+
+SD-03's merged source adds opt-in `resolutionLearning` and fixed evidence,
+work, exact staff review, withdrawal, and reconciliation operations. The
+[resolution learning guide](../../docs/RESOLUTION_LEARNING.md) documents the
+`support.learning.*` permissions, trusted evidence ports, 13-row human reserve
+plus two withdrawal rows, and source retention requirements. The public AI
+learning coordinator and KB delivery integration live in the optional AI
+package. This application
+package still has no KB or model-provider dependency.
+
+SD-04's merged source adds optional `engineering` evidence/work services and
+bounded `engineeringPolicy` configuration. Repository policy has its own
+declared collection and atomic Audit/receipts. Engineering source/work records
+share the ticket partition, with independent withdrawal and terminal-result
+capacity reserved before external dispatch. The optional AI package supplies
+model and GitHub coordination through host ports. See the
+[engineering guide](../../docs/ENGINEERING_EXPORT.md). Host adoption still
+requires the synchronized SD-06 release and its activation gates.
+
+SD-05's merged source adds optional `engineeringFollowup` services
+through `EngineeringFollowupApplication`. Signed allowlisted input and current
+confirmed fix-to-product/build/deployment mapping establish bounded private
+follow-up work; issue closure or a release tag alone does not. Independent
+issue/deployment generations and captured source/destination revocation epochs
+fence stale associations. Default four, hard maximum eight semantic work sets
+share the existing ticket partition; delivered work never rearms.
+
+`prepareEngineeringFollowupBundle` requires mode `prepare` or
+`staff_reassessment`. `rejectEngineeringFollowupBundle` is a local staff review
+with a reason, independent of provider/export availability. The combined
+`approveAndPostEngineeringFollowupWebUpdate` commits one authenticated web
+notice, quota, Audit/receipt, and delivered marker while preserving status,
+handling, and first-staff-response facts. No worker or email sends a notice.
+Five prepaid rows and one message slot cover bundle preparation and posting;
+parent engineering withdrawal scrubs children using its existing privacy reserve.
+Admission checks each actual stage: exact model manifests and their completion
+states before paid work, then actual bundle/request counts and later retest/post
+states at bundle preparation. Retest Audit/receipts use ordinary capacity.
+`recoverEngineeringFollowupPreparation` returns only an opaque accepted result
+bound to the current staff actor and exact recovery intent before live work or
+proof reads, preventing duplicate preparation after a lost acknowledgement.
+`retryEngineeringFollowupWork` explicitly readmits held/superseded or expired
+draftless model work under fresh same-semantic proof, retaining its ID and
+lifetime attempt cap and reserving five rows plus a slot. Its two Audit/receipt
+rows use ordinary capacity. `abandonEngineeringFollowupWork` locally holds
+undelivered work without provider/proof ports, spends its own two funded rows or
+ordinary capacity, and releases the remaining tail/slot while preserving history.
+Both use current review and queue authority; parent withdrawal remains the
+privacy-erasure operation.
+The optional coordinator additionally needs follow-up read and queue grants for
+new private processing/review; direct base operations retain their purpose
+permissions. Metadata-only receipt replay remains available under each base
+operation's current grants. Zero-row stale/unchanged/unavailable observations
+are live reevaluated reads, with no persisted command receipt.
+See the [release follow-up guide](../../docs/ENGINEERING_FOLLOWUP.md) for trusted
+ports, explicit retry/reassessment, private KB/retest handoffs, and capacity rules.
+Current-head validation/review, publication, and host acceptance remain separate.
 
 Customer create uses `support.ticket.create`; list and read both use the
 documented `support.ticket.read.own` permission and then confirm authoritative
@@ -22,8 +100,101 @@ Staff services use the same application factory and ticket partition:
 | `resolveTicket`          | `support.queue.read` + `support.ticket.manage`    | → `resolved` (closed tickets must reopen first)                     |
 | `closeTicket`            | `support.queue.read` + `support.ticket.manage`    | → `closed` (resolved only)                                          |
 | `reopenTicket`           | `support.queue.read` + `support.ticket.manage`    | resolved/closed → `waiting_on_support`                              |
+| `setTags`                | `support.queue.read` + `support.ticket.manage`    | Replace staff tags; status, customer time, and mail unchanged       |
 | `readTicketAuditHistory` | `support.audit.read`                              | Ordered Audit history for one ticket                                |
 
+### Optional handling and human controls (SD-01)
+
+The factory's `assistantHandlingEnabled` defaults to false. Explicit trusted
+web create with `initialHandling: "assistant"` requires both create and
+`support.ticket.assistant.start`. Legacy omission remains human handling with
+no rewrite. No model or KB is configured by enabling these source commands.
+Turning the flag off refuses new assistant creation/replies. Exact committed
+replays remain available after current command permissions and customer
+ownership checks, without new rows or reservations; receipts do not restore
+revoked access.
+
+| Method                             | Permission and boundary                                                                                          |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `readAssistantConversation`        | `support.ticket.assistant.read`; service-only safe messages plus revision/handling/customer-trigger fences       |
+| `replyAsAssistant`                 | `support.ticket.assistant.reply`; exact revision/handling/trigger, attributed plain-text reply, no mail          |
+| `escalateToHuman`                  | `support.ticket.assistant.escalate`; exact fences plus bounded handoff work                                      |
+| `requestPerson`                    | `support.ticket.request_person.own` and ownership; deterministic human request with current customer-safe result |
+| `takeOverTicket`                   | Queue read plus `support.ticket.take_over`; exact revision/handling fences and historical staff result           |
+| `confirmCustomerSuccess`           | `support.ticket.confirm_success.own` and ownership/current visible-message proof; always resolves                |
+| `readCustomerSuccessConfirmations` | Queue read plus audit read; private text-free confirmation evidence                                              |
+
+`readHandoffWork(access, ticketId)` requires queue read and returns bounded
+staff-only work DTOs with summary/guide IDs/transcript references, separate
+from historical staff replay and customer/assistant results.
+
+Assistant reads omit internal notes and requester identity. Their extra
+revision/generation metadata is service-only. Assistant commits require the
+latest visible message to remain the triggering customer message; new input
+or human handling defeats stale work. Only a public staff reply establishes
+`firstStaffRespondedAt`. Staff reopen enters human-pending for explicit
+handling; fresh inbound mail and verified email into assistant chat use humans.
+
+Customer confirmation supplies `lastSeenVisibleMessageId`, never internal
+revision/generation or free-form evidence. It always resolves (no optional
+flag), requires reopening closed work, and stores proof privately. Already
+human active requests and repeated accepted resolved proof add no rows.
+Assistant reply/escalation return only bounded `HandlingCommandResult` fields.
+Ticket change, work/evidence, Audit, and replay receipt commit together;
+handoff stores bounded summary/guide IDs and transcript references, not copied
+transcripts, notes, or mail jobs.
+
+Default `listStaffQueue` uses `handling: "human"`; `"assistant"`/`"all"`
+are explicit supervision views. Quota `assistantManaged` reserves 12 ordinary
+rows and one human message slot until the first staff response; controls keep
+a four-row/one-message tail. Legacy quotas retain their limits. Repeated
+no-ops avoid churn, but finite control cycles remain subject to named capacity.
+See [host composition](../../docs/HOST_COMPOSITION.md#optional-handling-and-deterministic-controls-sd-01)
+and [collections](../../docs/COLLECTIONS.md#sd-01-handling-and-handoff-layout-checkpoint)
+for exact admission, replay, and source/release boundaries.
+
+Handoff summaries are limited to 2,000 UTF-16 code units with
+`SupportDeskLimitError` field `handoff_summary`. Complete serialized assistant
+message/handoff records, including wrappers, are limited to 60,000 UTF-16
+bytes with field `serialized_record`; refusal occurs before commit.
+
+### Optional lifecycle extras
+
+`setTags` requires queue read plus `support.ticket.manage`. Configure
+`allowedTags` (at most 32 raw entries, normalized, deduplicated, sorted) and
+`maxTagsPerTicket` (default 8, maximum 32). Tags follow the category identifier
+discipline after trimming and lowercasing; each raw label is at most 64
+characters with no controls. `[]` clears tags. This command updates staff time
+and revision only, with an atomic `support.ticket.tags_changed` audit action
+and receipt, and no messages or mail. Queue query `tag` matches one label.
+
+Pass optional `responseTargetPolicy: { computeTargets(context) }` to both
+`createSupportDeskApplication` and `createInboundMailProcessor`. The host
+returns canonical ISO `firstResponseDueAt` / `resolutionDueAt` fields as a
+complete replacement on create, customer follow-up (web/email), and priority
+changes. Omitted result fields clear targets; absent policy preserves them.
+The frozen context is content-free and hooks must tolerate retries. First
+public staff reply sets `firstStaffRespondedAt` once. `resolvedAt` describes
+the current resolution cycle; reopen/reply clears it and re-resolution sets
+it again. Calendars, business hours, and presence remain host responsibilities.
+
+Queue queries select `target: "first_response" | "resolution"` (resolution
+by default), `targetState: "overdue" | "due_soon"`, and the latter's required
+`dueSoonMilliseconds` (0 to 30 days, rejected otherwise). Sort by `due_soonest` or `due_latest`,
+with completed/missing targets last and ticket ID tie-breaking. All values
+come from authoritative confirmation within existing scan budgets. Tags,
+targets, and milestones stay out of customer DTOs and automatic customer mail.
+
+Every staff mutation accepts optional `expectedRevision`. A mismatch fails
+before ticket changes with `SupportDeskStaleRevisionError`, exposing only
+`currentRevision` and `updatedAt` for HTTP 409. Omission retains existing
+conflict retries. Replay detection precedes revision checking; new receipts
+return the original result using a ticket snapshot and message revision cutoff.
+Legacy receipts retain current-detail replay. Run queue repair after upgrade
+to enrich old rows; no automatic target or historical milestone backfill runs.
+See [host composition](../../docs/HOST_COMPOSITION.md#optional-lifecycle-extras-task-13)
+for complete retry, lifecycle, and HTTP semantics.
+
 ### Staff queue projection
 
 `support-desk.queue-index.v1` holds one projection row per ticket (partition =
@@ -46,6 +217,12 @@ still terminal beyond the shared cutoff). Both workers require an explicit
 the application so projection, repair, and sweep share one cutoff. The
 projection is never ownership or permission evidence.
 
+A valid positive older active hint can discover a newer active canonical
+ticket, including a human handoff, without waiting for projection repair.
+Malformed, nonpositive, future-revision, and inactive hints are refused;
+canonical fields alone govern handling/filter/sort. Missing or inactive hints
+can still cause a temporary repair gap.
+
 Staff reads return `StaffTicketView` (full `Ticket` and all `TicketMessage`
 rows). Mutations that return that view also require `support.queue.read` so a
 narrow write permission cannot bypass the staff-detail boundary. They do not
@@ -87,12 +264,12 @@ When a create includes a notification, Support Desk sets the
 lifecycle changes. Internal notes, assignment, and priority changes advance
 only staff-facing `updatedAt` (in core workflow events).
 
-Accepted-change history is exact `@pegma/audit@0.1.0` projected into the
+Accepted-change history is exact `@pegma/audit@0.2.0` projected into the
 ticket partition with `defineAudit`. Customer create/reply and every staff
 mutation drop Audit transaction actions beside the state change; history is
 read through `readTicketAuditHistory` / Audit, not a private sorter. Domain
 `TicketEvent` remains pure workflow input and is not stored as a second audit
-shape. Authorization Core is exact `0.1.2`.
+shape. Authorization Core is exact `0.4.0`.
 
 Customer and staff commands are snapshotted from own data properties exactly
 once before validation, idempotency fingerprinting, or persistence. Accessors
@@ -109,7 +286,7 @@ Outbound `Message-ID` values must be at most 254 ASCII characters with a
 dot-atom local part, a valid DNS domain, and no controls or malformed dots.
 
 Outbound state is the application projection of published exact
-`@pegma/mail@0.1.0`. Support Desk keeps its `delivery:*` physical record and
+`@pegma/mail@0.1.1`. Support Desk keeps its `delivery:*` physical record and
 stores immutable template, subject, and `Message-ID` content on the causal
 message in the same transaction. The generic package owns claims, provider
 idempotency, submission generations, retry/reconciliation transitions,
@@ -129,10 +306,54 @@ Reply timestamps are sampled and validated on every transaction attempt, then
 clamped to the stored ticket's `updatedAt` so clock skew cannot move a
 conversation backward.
 
-Inbound processing remains a future phase, but its declared receipt collection
-is already hard-bounded to 256 hash slots per partition. Terminal receipt
-retention uses trusted processing time, a 30-day deduplication horizon, and
-version-conditional deletion; in-flight receipts are never swept.
+### Inbound mail
+
+`createInboundMailProcessor({ store, clock, accountMatcher, routingPolicy,
+notificationPolicy?, subjectMarkerPrefix?, supportAddresses?, ... })` returns
+`processInboundEmail(input)`. The host calls it only after verifying the
+provider event and normalizing bounded MIME into `InboundEmailInput` (safe
+text, sender address, host-evaluated `senderAuthentication`, threading headers,
+candidate reply token, and loop signals). There is no permission check: the
+caller is a trusted worker, and the input has no principal, role, plan,
+priority, or session field.
+
+For a ticket with `requester.email`, every reply locator requires the
+case-insensitive normalized `from` address to equal that email and a passing
+sender result bound to the same `from`. DMARC requires aligned DKIM or aligned
+SPF; `host_identity` represents an equivalent host-authenticated identity.
+Missing, failed, unaligned, or differently bound results create a new
+unverified related ticket and leave the named ticket unchanged. A ticket
+without a requester email retains the opaque routing-token flow; headers and
+subject markers alone remain insufficient. Sender authentication never selects
+a principal or grants web access.
+
+Processing reserves the `support-desk.inbound-receipts.v1` receipt with
+`insertIfAbsent` before ticket work (256 hash slots per partition), suppresses
+bounce and auto-reply loops, persists one routing decision on the receipt,
+and then creates or replies in one ticket-partition transaction with an Audit
+event (`system` actor `support-desk.inbound-email`), a command receipt, and an
+optional notification. Retries and concurrent duplicates return the first
+delivery's result and identifiers. Earlier receipts without a canonical replay
+fingerprint recognize only their exact prior payload shapes, bind the current
+fingerprint before continuing, and retain their original ticket-command
+fingerprint. Matching order is reply token,
+`In-Reply-To`/`References`, then subject marker, all through
+`support-desk.thread-index.v1` key lookups confirmed against authoritative
+records. A repeated inbound message's own `Message-ID` is checked for duplicate
+delivery first; when it does not qualify, its ticket precedes the subject
+marker as the related-ticket fallback. Unsafe or ambiguous matches create a new
+unverified ticket with the staff-only `Ticket.relatedTicketId`. A unique account
+match creates a `matched_email` ticket that stays invisible to customer web
+services.
+
+Notifications may carry an optional `replyRoutingToken` (22 to 128 URL-safe
+characters) for the host to render into the reply address. The application
+indexes it by SHA-256, with each notification `Message-ID` and every ticket
+number, after commit. Schedule `repairThreadIndexPage` and
+`sweepThreadIndexPage` with the same `threadIndexRetentionMilliseconds` as the
+processor. Terminal receipt retention uses trusted processing time, a 30-day
+deduplication horizon, and version-conditional deletion; in-flight receipts
+are never swept.
 
 ## Host composition
 

package/dist/assistant-turn-capacity.d.ts

@@ -0,0 +1,13 @@
+import { type AssistantTurnRecord } from "./assistant-turn-records.js";
+/**
+ * Reserve a constructive upper bound before a paid request can be prepared.
+ * Earlier bindings and metadata remain verbatim. Only the current attempt's
+ * accounting/metadata can change; a later preparation must reserve again.
+ *
+ * The old 8KB gap alone was insufficient: maximum legal processing metadata
+ * is 10,898 encoded bytes and finish stores it twice. Count complete reply,
+ * escalation, retry/supersession receipts and the largest replacement claim,
+ * using the same processing builder and encoder as actual writes.
+ */
+export declare function maximumPostPreparationRecordBytes(job: AssistantTurnRecord): number;
+//# sourceMappingURL=assistant-turn-capacity.d.ts.map

package/dist/assistant-turn-capacity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-turn-capacity.d.ts","sourceRoot":"","sources":["../src/assistant-turn-capacity.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAmBrC;;;;;;;;;GASG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,mBAAmB,GACvB,MAAM,CAoFR"}

package/dist/assistant-turn-capacity.js

@@ -0,0 +1,111 @@
+import { assistantTurnProcessingState, encodedBytes, withoutAssistantTurnLease, } from "./assistant-turn-records.js";
+// Each accepted UTF-16 code unit can occupy at most six JSON characters.
+// Lone surrogates reach that bound and are allowed by the text validator.
+const maximumText = "\ud800".repeat(200);
+const maximumProcessing = Object.freeze({
+    provider: maximumText,
+    model: maximumText,
+    requestId: maximumText,
+    currency: maximumText,
+    failureCategory: "\ud800".repeat(80),
+    inputTokens: Number.MAX_SAFE_INTEGER,
+    outputTokens: Number.MAX_SAFE_INTEGER,
+    costMicros: Number.MAX_SAFE_INTEGER,
+});
+// Extended ISO years have the longest canonical Date.toISOString() shape.
+const maximumTimestamp = "+100000-01-01T00:00:00.000Z";
+const maximumFingerprint = "f".repeat(64);
+/**
+ * Reserve a constructive upper bound before a paid request can be prepared.
+ * Earlier bindings and metadata remain verbatim. Only the current attempt's
+ * accounting/metadata can change; a later preparation must reserve again.
+ *
+ * The old 8KB gap alone was insufficient: maximum legal processing metadata
+ * is 10,898 encoded bytes and finish stores it twice. Count complete reply,
+ * escalation, retry/supersession receipts and the largest replacement claim,
+ * using the same processing builder and encoder as actual writes.
+ */
+export function maximumPostPreparationRecordBytes(job) {
+    const base = withoutAssistantTurnLease(job);
+    const processed = assistantTurnProcessingState(base, maximumProcessing, {
+        attemptId: `${job.turnId}:${job.attempt}`,
+        accounting: "not_called", // Longest supported accounting value.
+    });
+    const key = { ticketId: job.ticketId, turnId: job.turnId };
+    const result = {
+        ticketId: job.ticketId,
+        revision: Number.MAX_SAFE_INTEGER,
+        handlingGeneration: Number.MAX_SAFE_INTEGER,
+    };
+    const finishReceipt = (finishResult) => ({
+        fingerprint: maximumFingerprint,
+        result: finishResult,
+    });
+    const retry = {
+        ...processed,
+        status: "retry",
+        nextAttemptAt: maximumTimestamp,
+        lastFinish: finishReceipt({
+            ...key,
+            outcome: "retry_scheduled",
+            nextAttemptAt: maximumTimestamp,
+        }),
+    };
+    const superseded = {
+        ...processed,
+        status: "superseded",
+        lastFinish: finishReceipt({ ...key, outcome: "superseded" }),
+    };
+    const escalated = {
+        ...processed,
+        status: "escalated",
+        terminalResult: result,
+        lastFinish: finishReceipt({ ...key, outcome: "escalated", result }),
+    };
+    const completed = {
+        ...assistantTurnProcessingState(base, maximumProcessing),
+        status: "completed",
+        terminalResult: { ...result, messageId: maximumText },
+    };
+    const directEscalation = {
+        ...assistantTurnProcessingState(base, maximumProcessing),
+        status: "escalated",
+        terminalResult: result,
+    };
+    // Retry/expired-lease recovery must still admit the next owner before that
+    // owner's preparation can perform its own size reservation. In particular,
+    // don't assume its workerId/claimId will be as short as the current owner's.
+    const nextAttempt = Math.min(job.maxAttempts, job.attempt + 1);
+    const attemptId = `${job.turnId}:${nextAttempt}`;
+    const claim = {
+        ...key,
+        workerId: maximumText,
+        claimId: maximumText,
+        claimGeneration: nextAttempt,
+        attempt: nextAttempt,
+        attemptId,
+        commandId: `assistant-complete:${attemptId}`,
+        correlationId: job.correlationId,
+        expectedRevision: Number.MAX_SAFE_INTEGER,
+        expectedHandlingGeneration: job.triggerHandlingGeneration,
+        triggerMessageId: job.triggerMessageId,
+    };
+    const { nextAttemptAt: _retryAt, ...afterRetry } = retry;
+    const replacement = {
+        ...afterRetry,
+        status: "claimed",
+        attempt: nextAttempt,
+        claimGeneration: nextAttempt,
+        claim,
+        leaseUntil: maximumTimestamp,
+    };
+    return Math.max(...[
+        retry,
+        superseded,
+        escalated,
+        completed,
+        directEscalation,
+        replacement,
+    ].map(encodedBytes));
+}
+//# sourceMappingURL=assistant-turn-capacity.js.map

package/dist/assistant-turn-capacity.js.map

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

package/dist/assistant-turn-records.d.ts

@@ -0,0 +1,68 @@
+import type { IsoTimestamp } from "@pegma/spine";
+import type { EntityKey } from "@pegma/storage-core";
+import type { Ticket, TicketMessage } from "@pegma/support-desk-contracts";
+import type { HandlingCommandResult } from "./index.js";
+import type { AssistantAttemptBinding, AssistantPreparedAttempt, AssistantTurnClaimFence, AssistantTurnAccounting, AssistantTurnFinishResult, AssistantTurnOptions, AssistantTurnProcessingMetadata } from "./assistant-turn-types.js";
+export interface ResolvedAssistantTurnOptions {
+    readonly maxAttempts: number;
+    readonly maxTurnMilliseconds: number;
+    readonly maxLeaseMilliseconds: number;
+}
+/** One bounded row per causal message; attempts never append physical rows. */
+export interface AssistantTurnRecord {
+    readonly kind: "assistant_turn";
+    readonly partition: string;
+    readonly id: string;
+    readonly ticketId: string;
+    readonly turnId: string;
+    readonly triggerMessageId: string;
+    readonly triggerRevision: number;
+    readonly triggerHandlingGeneration: number;
+    readonly correlationId: string;
+    readonly createdAt: IsoTimestamp;
+    readonly turnDeadline: IsoTimestamp;
+    readonly maxAttempts: number;
+    readonly status: "pending" | "claimed" | "retry" | "completed" | "escalated" | "superseded";
+    readonly attempt: number;
+    readonly claimGeneration: number;
+    readonly claim?: AssistantTurnClaimFence;
+    readonly leaseUntil?: IsoTimestamp;
+    readonly nextAttemptAt?: IsoTimestamp;
+    readonly preparedAttempts: readonly AssistantPreparedAttempt[];
+    readonly processing?: AssistantTurnProcessingMetadata;
+    readonly terminalResult?: HandlingCommandResult;
+    readonly lastFinish?: {
+        readonly fingerprint: string;
+        readonly result: AssistantTurnFinishResult;
+    };
+}
+export declare const maximumRecordBytes = 60000;
+/** Initial ceiling; preparation also reserves the largest reachable later state. */
+export declare const preparedRecordBytes = 52000;
+export declare const maximumBindingBytes = 12000;
+export declare function dataObject(value: unknown, name: string): Record<string, unknown>;
+export declare function fields(value: unknown, name: string, required: readonly string[], optional?: readonly string[]): Record<string, unknown>;
+export declare function dataArray(value: unknown, name: string, maximum: number): readonly unknown[];
+export declare function text(value: unknown, name: string, maximum?: number): string;
+export declare function integer(value: unknown, name: string, minimum?: number, maximum?: number): number;
+export declare function timestamp(value: unknown, name: string): number;
+export declare function encodedBytes(value: unknown): number;
+export declare function canonical(value: unknown): string;
+export declare function fingerprint(value: unknown): Promise<string>;
+export declare function snapshot<T>(value: T): T;
+export declare function resolveAssistantTurnOptions(input: AssistantTurnOptions | undefined): ResolvedAssistantTurnOptions | undefined;
+export declare function assistantTurnKey(ticketId: string, turnId: string): EntityKey;
+export declare function terminalTurn(record: AssistantTurnRecord): boolean;
+export declare function withoutAssistantTurnLease(job: AssistantTurnRecord): AssistantTurnRecord;
+/** Shared by real state changes and the constructive preparation size bound. */
+export declare function assistantTurnProcessingState(job: AssistantTurnRecord, processing: AssistantTurnProcessingMetadata | undefined, accounting?: {
+    readonly attemptId: string;
+    readonly accounting: AssistantTurnAccounting;
+}): AssistantTurnRecord;
+export declare function createAssistantTurnRecord(ticket: Ticket, message: TicketMessage, correlationId: string, options: ResolvedAssistantTurnOptions): Promise<AssistantTurnRecord>;
+export declare const assistantTurnFenceFields: readonly string[];
+export declare function validateFence(input: unknown, extraRequired?: readonly string[], extraOptional?: readonly string[]): AssistantTurnClaimFence & Record<string, unknown>;
+export declare function validateProcessing(input: unknown): AssistantTurnProcessingMetadata | undefined;
+export declare function validateBinding(input: unknown): AssistantAttemptBinding;
+export declare function assertAssistantTurnRecord(value: AssistantTurnRecord, physical?: EntityKey): void;
+//# sourceMappingURL=assistant-turn-records.d.ts.map

package/dist/assistant-turn-records.d.ts.map

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