@gestaltrun/dsh-im-runtime 0.1.0 → 0.1.6

package/lib/types/delivery-sqlite.d.ts

@@ -1,22 +1,49 @@
+/** Host-owned sqlite records for IM delivery. Opens one file and reads by key. */
+import { type SqliteConnectionConfig } from './sqlite-connection.ts';
+import type { NasHostLease, SqliteJournalMode } from './nas-host-lease.ts';
+import type { ImUploadControlResult } from './upload-types.ts';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { type ImDeliveryAggregate, type ImExecutionAggregate, type ImProviderCursorAggregate } from './delivery-schema.ts';
-import type { ImAgentTaskId, ImCustomerListPage, ImCustomerListRequest, ImCustomerReadAckRequest, ImDeliveryScope, ImHandlingControl, ImOutboundRequestId, ImOutboundView, ImProviderCursorId, ImScopeId, ImSetHandlingControlRequest } from './delivery-types.ts';
-import type { ImAccountId } from './types.ts';
+import type { ImAgentTaskId, ImCustomerSessionListRequest, ImCustomerSessionPage, ImCustomerListPage, ImCustomerListRequest, ImCustomerReadAckRequest, ImDeliveryScope, ImHandlingControl, ImOutboundRequestId, ImOutboundView, ImProviderCursorId, ImScopeId, ImSetHandlingControlRequest } from './delivery-types.ts';
+import type { ImAccountId, ImPlatform } from './types.ts';
+import type { ImInboundContentQuery } from './transport.ts';
+import type { ImDeliveryAccountSlice } from './placement-slice.ts';
 export declare const IM_DELIVERY_UNIT = "gestaltrun_im_delivery";
 export declare const IM_DELIVERY_UNIT_VERSION = 1;
 /** Monotonic physical layout version stored in `PRAGMA user_version`. */
-export declare const IM_DELIVERY_SCHEMA_VERSION = 2;
+export declare const IM_DELIVERY_SCHEMA_VERSION = 4;
+/** 语句遇锁等待时长；node:sqlite 缺省为 0，任何持锁者都会让语句立即失败。NAS 交接窗口内旧实例的短暂事务通常在 2 秒内提交。 */
+export declare const DEFAULT_DELIVERY_BUSY_TIMEOUT_MS = 2000;
+/** 迁移单步遇锁重试的时间预算；超限抛 `IM_DELIVERY_SQLITE_BUSY`，由 supervisor 重启后再试，而不是无限期卡住启动。 */
+export declare const DEFAULT_DELIVERY_MIGRATION_RETRY_BUDGET_MS = 30000;
+/** Values one consumer derives from scope documents; created by `ImDeliverySqlite.projectScopes`. */
+export interface ImScopeProjection<T> {
+    /**
+     * @param id - complete conversation identity.
+     * @returns the value derived from the stored document, or absence when none is stored; parses the document only when this projection has not derived it yet.
+     */
+    get(id: ImScopeId): T | undefined;
+    /** Stop deriving and release the values. Idempotent; `get` throws afterwards. */
+    dispose(): void;
+}
 /**
  * Durable delivery records with key lookups and small parsed-document caches.
+ * Scope descriptors and correlation identifiers derived from parsed or written documents stay in memory without a
+ * size bound, so account-wide listings and SDK matching do not re-read documents. Like the document caches, they
+ * require this connection to be the only writer.
  * Physical unit tables stay compatible with the sqlite KV layout already on disk.
  */
 export declare class ImDeliverySqlite {
+    private readonly lease?;
+    private readonly releaseReservation?;
     /** Test-only: throw after this many scopes have been committed during 1→2 backfill. */
     static injectBackfillCrashAfter: number | undefined;
     /** Test-only: override the committed backfill batch size. */
     static backfillBatchSize: number | undefined;
     /** Test-only: fail the next customer-index write so putScope can prove rollback. */
     static failNextCustomerIndexWrite: boolean;
+    /** Test-only: fail the next cursor-account index write so putCursor can prove rollback. */
+    static failNextCursorIndexWrite: boolean;
     private readonly db;
     private readonly scopeSelect;
     private readonly scopeUpsert;
@@ -24,16 +51,43 @@ export declare class ImDeliverySqlite {
     private readonly cursorUpsert;
     private readonly executionSelect;
     private readonly executionUpsert;
+    private customerUnreadRevision;
+    private readonly customerUnreads;
     private readonly scopeCache;
+    /**
+     * Descriptor of each stored scope seen since open or the last bulk removal. A scope id hashes its
+     * descriptor (`encodeImScopeId`), so an entry stays exact while that scope is stored.
+     */
+    private readonly scopeDescriptors;
+    /** `correlationIdentifiers` of each parsed or written scope document, grouped by account; every write refreshes its entry. */
+    private readonly correlationByAccount;
+    /** Accounts whose every stored scope has a `correlationByAccount` entry; writes keep them complete until a bulk removal. */
+    private readonly correlationComplete;
+    private readonly projections;
     private readonly executionCache;
     private closed;
+    private readonly releaseFence;
     private constructor();
     /**
      * Open or create the delivery database and ensure unit tables plus lookup indexes.
      * @param path - sqlite file path, or `:memory:`.
+     * @param options - 日志、连接锁和页缓存设置、锁等待与重试预算及可选云端租约；所有访问检查本地期限。
      * @returns the opened record store.
      */
-    static open(path: string): Promise<ImDeliverySqlite>;
+    static open(path: string, options?: SqliteConnectionConfig & {
+        readonly journalMode?: SqliteJournalMode;
+        readonly lease?: NasHostLease;
+        readonly busyTimeoutMs?: number;
+        readonly migrationRetryBudgetMs?: number;
+    }): Promise<ImDeliverySqlite>;
+    /** @param requestId - outbox intent owning private staged bytes and SDK metadata. @returns stored JSON; the media owner validates before use. */
+    mediaPreparation(requestId: ImOutboundRequestId): unknown;
+    /** @param requestId - owning intent. @param value - media-owner validated private JSON, never included in history or Remote snapshots. */
+    saveMediaPreparation(requestId: ImOutboundRequestId, value: object): void;
+    /** @returns file intents whose external preparation started without committed metadata. */
+    unfinishedFilePreparationIds(): readonly ImOutboundRequestId[];
+    /** @param requestId - predecessor intent under retry consideration. @returns whether its external file preparation remains unconfirmed. */
+    hasUnfinishedFilePreparation(requestId: ImOutboundRequestId): boolean;
     /**
      * Read one conversation aggregate by scope id.
      * @param id - complete conversation identity.
@@ -52,6 +106,25 @@ export declare class ImDeliverySqlite {
      * @returns the stored cursor, or absence.
      */
     getCursor(id: ImProviderCursorId): ImProviderCursorAggregate | undefined;
+    /**
+     * Opaque provider cursors for one account.
+     * Stored operations stay in sqlite and are not returned.
+     * Cursor ids come from the derived account index and are ordered by id.
+     * @param accountId - cursor owner.
+     */
+    checkpointCursors(accountId: ImAccountId): readonly {
+        readonly streamId: string;
+        readonly cursor: string;
+    }[];
+    /**
+     * Durable unsubmitted input, unsettled-send and unknown-send counts for one real account.
+     * Message rows are not copied out. Reads the derived per-scope counts maintained with each scope write.
+     * @param accountId - conversation owner.
+     */
+    checkpointCounts(accountId: ImAccountId): {
+        readonly pendingCount: number;
+        readonly unknownSendCount: number;
+    };
     /**
      * Persist one provider cursor.
      * @param id - provider feed identity.
@@ -89,10 +162,47 @@ export declare class ImDeliverySqlite {
     dispatchingScopeIds(): readonly ImScopeId[];
     /**
      * List conversations owned by one configured account.
+     * Membership comes from the account index; descriptors come from memory or the conversation summaries, not documents.
      * @param accountId - durable IM account.
-     * @returns stored scopes for that account.
+     * @returns stored scopes for that account, in scope-id order.
      */
     scopesForAccount(accountId: ImAccountId): ImDeliveryScope[];
+    /**
+     * Read one conversation's descriptor without parsing its document.
+     * @param id - complete conversation identity.
+     * @returns the stored scope, or absence when no document is stored under `id`.
+     */
+    scopeDescriptor(id: ImScopeId): ImDeliveryScope | undefined;
+    /**
+     * Report whether one conversation holds received live inbound above its suppression watermark.
+     * Reads the pending index written with each document, which holds a scope exactly when its `cursor.pendingCount` is positive.
+     * @param id - complete conversation identity.
+     * @returns false for a scope without pending input or without a document.
+     */
+    hasPendingInbound(id: ImScopeId): boolean;
+    /** @param accountId - account owning the conversations. @param platform - admitted platform. @param uid - unqualified buyer UID. @returns matching real direct scopes using summary rows; older empty conversations use their saved direct recipient. The lookup does not populate the aggregate cache. */
+    directScopesForPeer(accountId: ImAccountId, platform: ImPlatform, uid: string): ImDeliveryScope[];
+    /** @param accountId - listener account. @param platform - admitted platform. @param request - platform message identity and optional conversation restriction. @returns matching real scopes from message rows and summaries, without parsing aggregates. */
+    inboundScopes(accountId: ImAccountId, platform: ImPlatform, request: ImInboundContentQuery): ImDeliveryScope[];
+    /**
+     * Conversations of one account whose document holds one of `identifiers` as the external message id of a live
+     * external inbound, or as the request or external message id of a sent outbound.
+     * The first call for an account parses the documents not yet parsed since open or the last bulk removal; later calls read no rows.
+     * @param accountId - durable IM account.
+     * @param identifiers - exact provider message ids or outbound request ids.
+     * @returns matching stored scopes, in scope-id order.
+     */
+    scopesWithCorrelationIdentifier(accountId: ImAccountId, identifiers: ReadonlySet<string>): ImDeliveryScope[];
+    /**
+     * Derive one value from every scope document parsed or written from now on. Each committed write refreshes the
+     * value and bulk removals clear it. A derivation failure during a write leaves that scope underived, and the next
+     * `get` derives it again and throws the failure to its caller; the committed write is unaffected.
+     * @param derive - pure function of one document; it must not keep the document.
+     * @returns accessor of the derived values.
+     */
+    projectScopes<T extends object>(derive: (value: ImDeliveryAggregate) => T): ImScopeProjection<T>;
+    /** @returns scopes with durable observations not yet transferred to the external queue. Reads the derived upload-pending index. */
+    uploadScopeIds(): readonly ImScopeId[];
     /**
      * Resolve the newest execution bound to one Agent Session.
      * @param sessionId - IM Agent Session.
@@ -111,6 +221,68 @@ export declare class ImDeliverySqlite {
      * @returns stored generations for that scope.
      */
     executionsForScope(scopeId: ImScopeId): ImExecutionAggregate[];
+    /**
+     * Newest execution per conversation, resolved with one indexed join per chunk of scope ids.
+     * Ties on generation resolve to the highest task id, the same row the per-scope
+     * `ORDER BY generation DESC LIMIT 1` query returns.
+     * @param scopeIds - complete conversation identities.
+     * @returns the highest-generation task of each scope that has one.
+     */
+    latestExecutionsForScopes(scopeIds: readonly ImScopeId[]): Map<ImScopeId, ImExecutionAggregate>;
+    /**
+     * @param accountId - durable IM account.
+     * @returns ids the account index lists and the scope table stores, in scope-id order.
+     */
+    private accountScopeIds;
+    /**
+     * Fill `scopeDescriptors` for stored ids from the conversation summaries written in the same transaction as each
+     * document, one statement per chunk. Ids whose summary is absent or invalid fall back to their documents.
+     * @param ids - ids whose documents are stored.
+     */
+    private loadScopeDescriptors;
+    /** @param ids - scope ids. @returns known descriptors in the order of `ids`; unknown ids are absent. */
+    private descriptorsOf;
+    /**
+     * Stored scope documents for explicit ids, fetched with one join per chunk.
+     * Ids without a stored document are absent from the result.
+     * @param ids - complete conversation identities.
+     * @returns parsed aggregates keyed by scope id.
+     */
+    private scopeDocuments;
+    /**
+     * Generations of every listed conversation in generation order, resolved with one
+     * indexed join per chunk. Scopes never overlap chunk boundaries, so per-scope order matches `executionsForScope`.
+     * @param scopeIds - complete conversation identities.
+     * @returns per-scope stored generations keyed by scope id.
+     */
+    private executionsForScopes;
+    /**
+     * Export all durable real-conversation facts for one account, excluding simulations and derived indexes.
+     * Documents, generations, read positions and handling controls resolve in a fixed number of
+     * batched queries, not per scope.
+     * @param accountId - source account; the caller drains writers before taking a final snapshot.
+     * @returns independent account slice; it contains buyer data and must not be logged.
+     */
+    exportAccountSlice(accountId: ImAccountId): ImDeliveryAccountSlice;
+    /**
+     * Read positions of one reader batch across scopes, grouped per scope.
+     * Reader order inside each group matches the per-scope point query (reader-id order).
+     * @param scopeIds - complete conversation identities.
+     * @returns acknowledged live-inbound positions keyed by scope id.
+     */
+    private readPositionsForScopes;
+    /**
+     * Handling controls batch across scopes.
+     * @param scopeIds - complete conversation identities.
+     * @returns stored controls keyed by scope id; scopes without a control are absent.
+     */
+    private handlingControlsForScopes;
+    /**
+     * Replace one account's real facts in one transaction, preserving other accounts, simulations and maximum reader positions.
+     * @param slice - wire-validated slice authorized for the target epoch; caller owns stopped listeners, drained queues and exclusive activation. Epoch receipts belong to the handoff journal.
+     * @throws ImPlacementSliceError for identities already owned by another account; transaction failures leave the prior slice intact unless the NAS fence closes the database, in which case the caller must remain stopped and reconcile.
+     */
+    replaceAccountSlice(slice: ImDeliveryAccountSlice): void;
     /**
      * Record a provider actor id that belongs to one configured account.
      * @param accountId - durable IM account.
@@ -154,12 +326,21 @@ export declare class ImDeliverySqlite {
     private insertExecutionIndexes;
     private clearExecutionIndexes;
     private rememberScope;
+    /** Drop parsed scope documents and every projection derived from them after documents were removed or replaced in bulk. */
+    private forgetScopes;
     private rememberExecution;
     /**
      * List customer rows for one account and source, grouped by customer key.
      * @param request - account, real/simulation filter, optional substring, and reader.
      */
     listCustomers(request: ImCustomerListRequest): ImCustomerListPage;
+    /**
+     * Read customer Session references without loading unread or handling state.
+     * @param request - account, source, search and keyset cursor.
+     * @returns Session references in the same order as the full customer list.
+     */
+    listCustomerSessions(request: ImCustomerSessionListRequest): ImCustomerSessionPage;
+    private customerGroups;
     /**
      * Advance one reader's inbound watermark with max semantics.
      * @param request - reader, scope, and observed arrival sequence.
@@ -168,8 +349,10 @@ export declare class ImDeliverySqlite {
     /**
      * Persist one scope's automatic-handling pause fact.
      * @param request - scope and pause fields.
+     * @param upload - successful product operation to journal atomically; absent for safety-only pauses.
+     * @returns committed control revision. Storage failure rolls back both control and observation.
      */
-    setHandlingControl(request: ImSetHandlingControlRequest): ImHandlingControl;
+    setHandlingControl(request: ImSetHandlingControlRequest, upload?: ImUploadControlResult): ImHandlingControl;
     /**
      * Read one scope's automatic-handling pause fact.
      * @param scopeId - complete conversation identity.
@@ -178,6 +361,23 @@ export declare class ImDeliverySqlite {
     private requireHandlingControl;
     private customerMatches;
     private likeMatch;
+    /**
+     * One customer's acknowledged live-inbound watermarks, batched across scopes.
+     * @param readerId - reading customer-service reader.
+     * @param scopeIds - complete conversation identities of one page.
+     * @returns acknowledged sequence per scope; scopes without an ack read as 0.
+     */
+    private readWatermarksForScopes;
+    /** Reuse per-reader counts for this delivery revision; acknowledgements invalidate their reader. */
+    private customerUnreadCounts;
+    /**
+     * Unread live-inbound counts for scopes with their per-scope watermark, one range count per
+     * scope through a values join over the message index. Scopes without unread messages are absent.
+     * @param scopeIds - every scope the counts must cover; scopes missing from `watermarks` read from 0.
+     * @param watermarks - acknowledged sequence per scope id.
+     * @returns unread count per scope id.
+     */
+    private unreadCountsForScopes;
     private customerRow;
     private latestExecutionRow;
     private updateSummaryExecution;

package/lib/types/delivery-types.d.ts

@@ -19,6 +19,10 @@ export type ImSimulationInstanceId = Branded<'ImSimulationInstanceId'>;
 export type ImProviderCursorId = Branded<'ImProviderCursorId'>;
 /** Host-minted identity of one Agent admission batch. */
 export type ImAdmissionId = Branded<'ImAdmissionId'>;
+/** Identity of one product's admission annotation provider. */
+export type ImAdmissionAnnotatorId = Branded<'ImAdmissionAnnotatorId'>;
+/** Stable identity of one analysis of one frozen admission batch. */
+export type ImAdmissionAnnotationId = Branded<'ImAdmissionAnnotationId'>;
 /** Stable identity of one route-bound Agent task generation. */
 export type ImAgentTaskId = Branded<'ImAgentTaskId'>;
 /** Complete identity of a real platform conversation. */
@@ -102,8 +106,43 @@ export interface ImMessageQuote {
     readonly senderDisplayName?: string;
     readonly externalMessageId?: string;
 }
+/** Private bytes supplied by a manual picker or an authorized Host tool; never recorded in Session data. */
+export interface ImMediaInput {
+    readonly kind: 'image' | 'file';
+    readonly name: string;
+    readonly mime: string;
+    readonly base64: string;
+}
+/** Safe durable media description; SHA256 identifies the original selected bytes. */
+export interface ImMediaDescription {
+    readonly kind: 'image' | 'file';
+    readonly name: string;
+    readonly mime: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    /** Original immutable Session file, when an Agent resolved the source. Absent for manual uploads. */
+    readonly sourceFile?: import('@deepseek-ai/dsh-attachment').FileAttachmentRef;
+}
+/** Upload preparation facts, independent from the outbox message submission status. */
+export interface ImMediaPreparationView {
+    readonly state: 'uploading' | 'prepared';
+    readonly imageUrl?: string;
+}
+/** Reusable Host media send; automatic callers supply their frozen task route. */
+export interface ImSendMediaMessageRequest extends Omit<ImRegisterOutboundRequest, 'scope' | 'content'> {
+    readonly scope: ImRealDeliveryScope;
+    readonly file: ImMediaInput;
+    /** Provider-produced immutable file reference; omitted by manual uploads. */
+    readonly sourceFile?: import('@deepseek-ai/dsh-attachment').FileAttachmentRef;
+    readonly routeBinding?: ImOutboundRouteBinding;
+}
 /** Text, image placeholder, or honest unsupported-message presentation. */
 export type ImMessageContent = {
+    readonly text: string;
+    readonly format: 'media';
+    readonly media: ImMediaDescription;
+    readonly quote?: ImMessageQuote;
+} | {
     readonly text: string;
     readonly format: 'text' | 'markdown';
     readonly quote?: ImMessageQuote;
@@ -120,6 +159,8 @@ export type ImMessageContent = {
 };
 /** One normalized inbound provider message before persistence. */
 export interface ImInboundMessageInput {
+    /** Per-message platform facts; absence must not be filled with a later assignment. */
+    readonly uploadIdentity?: import('./upload-types.ts').ImUploadIdentity;
     readonly externalMessageId: string;
     readonly sender: ImSenderAttribution;
     readonly content: ImMessageContent;
@@ -146,8 +187,24 @@ export interface ImAdmissionMessageSource {
     readonly sender: ImSenderAttribution;
     readonly occurredAt: string;
 }
+/** Optional audit metadata; absent legacy data means no annotation was recorded. */
+export interface ImAdmissionAnnotationSource {
+    readonly id: ImAdmissionAnnotationId;
+    readonly annotatorId: ImAdmissionAnnotatorId;
+    readonly version: string;
+    readonly status: 'success' | 'timeout' | 'failed';
+}
+/** Analysis frozen before Session append; only successful results contain model-visible text. */
+export type ImAdmissionAnnotation = ImAdmissionAnnotationSource & ({
+    readonly status: 'success';
+    readonly text: string;
+} | {
+    readonly status: 'timeout' | 'failed';
+});
 /** Frozen route and message evidence recorded with one Session user/message. */
 export interface ImAgentAdmissionSource {
+    /** Analysis identity and disposition; legacy sources omit this field. */
+    readonly annotations?: readonly ImAdmissionAnnotationSource[];
     readonly admissionId: ImAdmissionId;
     /** Customer pause generation at automatic input admission; absent legacy values mean zero. */
     readonly handlingEpoch?: number;
@@ -180,6 +237,8 @@ export interface ImAgentTaskView {
 }
 /** Durable inbound row safe for history UI and model tools. */
 export interface ImInboundMessageView {
+    /** Captured platform facts, absent in legacy stored messages. */
+    readonly uploadIdentity?: import('./upload-types.ts').ImUploadIdentity;
     readonly messageId: ImMessageId;
     readonly scopeId: ImScopeId;
     readonly externalMessageId: string;
@@ -226,6 +285,8 @@ export interface ImIngestInboundPageRequest {
     readonly observedCursor: string | null;
     readonly nextCursor: string | null;
     readonly presentation?: ImConversationPresentation;
+    /** Latest platform-provided direct peer identity; absence retains the stored identity. */
+    readonly directRecipient?: ImDirectRecipient;
     readonly messages: readonly ImInboundMessageInput[];
 }
 /** Receipt stored with the conversation aggregate before a page call resolves. */
@@ -368,6 +429,7 @@ export interface ImOutboundView {
     readonly scopeId: ImScopeId;
     readonly intent: ImOutboundIntent;
     readonly content: ImMessageContent;
+    readonly media?: ImMediaPreparationView;
     readonly status: ImOutboundStatus;
     /** Scope-local admission order, independent of timestamps. */
     readonly sequenceNumber: number;
@@ -479,7 +541,12 @@ export interface ImSendManualMessageRequest {
      */
     readonly accountId?: ImAccountId;
     readonly requestId: ImOutboundRequestId;
+    /** When supplied, dispatch requires the same epoch and a durable customer pause; changes reject before provider submission. */
+    readonly expectedHandlingEpoch?: number;
+    /** Text-only message; empty when media is present. The composer sends accompanying text as another intent. */
     readonly text: string;
+    /** One selected private file, staged only after Send. */
+    readonly media?: ImMediaInput;
 }
 /** Query or confirmation input for a manual message bound through its Session or scope. */
 export interface ImManualMessageQueryRequest {
@@ -490,7 +557,7 @@ export interface ImManualMessageQueryRequest {
     readonly accountId?: ImAccountId;
     readonly requestId: ImOutboundRequestId;
 }
-/** Explicit retry creates a distinct durable intent linked to an uncertain predecessor. */
+/** Explicit retry links a distinct intent to an uncertain text message or a known failed media message; unknown media is not retryable. */
 export interface ImRetryManualMessageRequest {
     readonly sessionId: SessionId;
     /** Wangwang conversation identity; used when {@link sessionId} has no Agent task. */
@@ -559,6 +626,25 @@ export interface ImOutboundPage {
     readonly hasMore: boolean;
     readonly nextBeforeSequenceNumber?: number;
 }
+/** Read-only records of one conversation document, valid only during the projection call that receives them. */
+export interface ImConversationRecords {
+    readonly scope: ImDeliveryScope;
+    readonly cursor: ImConversationCursor;
+    /** @param request - bounded history cursor and origin filter. @returns the page `queryHistory` returns for this document. */
+    queryHistory(request: Omit<ImHistoryQueryRequest, 'scope'>): ImHistoryPage;
+    /** @param request - bounded outbox history cursor. @returns the page `queryOutbound` returns for this document. */
+    queryOutbound(request: Omit<ImOutboundQueryRequest, 'scope'>): ImOutboundPage;
+}
+/** Consumer values derived from conversation documents and refreshed by every committed document write. */
+export interface ImConversationProjection<T> {
+    /**
+     * @param scope - complete conversation identity.
+     * @returns the value for the stored conversation, or for an empty one when none is stored; parses the document only when this projection has not derived it yet.
+     */
+    get(scope: ImDeliveryScope): T;
+    /** Stop deriving and release the values. Idempotent; `get` throws afterwards. */
+    dispose(): void;
+}
 /** Result of comparing one durable Session log with pending IM submissions. */
 export interface ImSessionReconciliationResult {
     readonly sessionId: SessionId;
@@ -593,6 +679,14 @@ export interface ImCustomerListRequest {
         readonly customerKey: string;
     };
 }
+/** Customer Session lookup with the same source, search, sorting and cursor rules as the full customer list. */
+export type ImCustomerSessionListRequest = Omit<ImCustomerListRequest, 'readerId'>;
+/** Customer identity and latest Session without unread or handling projections. */
+export type ImCustomerSessionRow = Pick<ImCustomerRow, 'customerKey' | 'kind' | 'lastActivity' | 'latestSessionId'>;
+/** Keyset page containing only customer Session references. */
+export interface ImCustomerSessionPage extends Omit<ImCustomerListPage, 'items'> {
+    readonly items: readonly ImCustomerSessionRow[];
+}
 /** One customer row projected from the rebuildable conversation index. */
 export interface ImCustomerRow {
     readonly customerKey: string;
@@ -641,6 +735,8 @@ export interface ImHandlingControl {
 }
 /** Persist or clear one scope's automatic-handling pause. */
 export interface ImSetHandlingControlRequest {
+    /** Successful product control result; omitted for automatic safety pauses. */
+    readonly uploadEvent?: Omit<import('./upload-types.ts').ImUploadControlResult, 'target' | 'accountId'>;
     readonly scopeId: ImScopeId;
     readonly automaticHandlingPaused: boolean;
     readonly reason?: string;

package/lib/types/delivery.d.ts

@@ -1,9 +1,14 @@
+import type { ImUploadBinding } from './upload-types.ts';
+import type { ImMessageUploadQueue } from './message-upload.ts';
 import type { ImDeliverySqlite } from './delivery-sqlite.ts';
-import type { ImBeginOutboundAttemptRequest, ImBeginOutboundAttemptResult, ImCancelPendingAiRequest, ImCommitProviderCursorRequest, ImConversationCursor, ImConversationPresentation, ImDeliveryOperationId, ImDeliveryScope, ImGetOutboundRequest, ImHistoryPage, ImHistoryQueryRequest, ImImportJsonlHistoryRequest, ImImportJsonlHistoryResult, ImInboundMessageView, ImInboundOperationQuery, ImInboundPageResult, ImIngestInboundPageRequest, ImMarkSubmittedRequest, ImMarkSubmittedResult, ImMessageId, ImMessageSource, ImOutboundAttemptId, ImOutboundPage, ImOutboundQueryRequest, ImOutboundRequestId, ImOutboundRouteBinding, ImOutboundView, ImPendingInboundRequest, ImProviderCursorCommitResult, ImProviderCursorId, ImProviderCursorOperationQuery, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope, ImRegisterOutboundRequest, ImScopeId, ImSettleOutboundAttemptRequest, ImSettleSimulationOutboundRequest } from './delivery-types.ts';
+import type { ImBeginOutboundAttemptRequest, ImBeginOutboundAttemptResult, ImCancelPendingAiRequest, ImCommitProviderCursorRequest, ImConversationCursor, ImConversationPresentation, ImConversationProjection, ImConversationRecords, ImDeliveryOperationId, ImDeliveryScope, ImGetOutboundRequest, ImHistoryPage, ImHistoryQueryRequest, ImImportJsonlHistoryRequest, ImImportJsonlHistoryResult, ImInboundMessageView, ImInboundOperationQuery, ImInboundPageResult, ImIngestInboundPageRequest, ImMarkSubmittedRequest, ImMarkSubmittedResult, ImMessageId, ImMessageSource, ImOutboundAttemptId, ImOutboundPage, ImOutboundQueryRequest, ImOutboundRequestId, ImOutboundRouteBinding, ImOutboundView, ImPendingInboundRequest, ImProviderCursorCommitResult, ImProviderCursorId, ImProviderCursorOperationQuery, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope, ImRegisterOutboundRequest, ImScopeId, ImSettleOutboundAttemptRequest, ImSettleSimulationOutboundRequest } from './delivery-types.ts';
 import type { ImAccountId, ImPlatform, ImRouteResolution } from './types.ts';
 interface ImDeliveryHost {
+    uploadTarget?: ImUploadBinding['target'];
+    uploadIdentity?: ImUploadBinding['identity'];
+    onUploadReady?(): void;
     automaticHandlingBlocked(scopeId: ImScopeId): boolean;
-    inspectAccount(id: ImAccountId): {
+    inspectAccount(id: ImAccountId, scope?: ImDeliveryScope): {
         readonly platform: ImPlatform;
         readonly paused: boolean;
         readonly revision: import('./types.ts').ImRevision;
@@ -16,6 +21,8 @@ interface ImDeliveryHost {
         readonly messageIds?: readonly ImMessageId[];
         readonly requestId?: ImOutboundRequestId;
     }): void;
+    /** A provider cursor advanced after its sqlite write. */
+    onProviderCursorApplied?(owner: ImProviderCursorOwner): void;
 }
 /**
  * Encode every scope component in an ordered JSON tuple before hashing.
@@ -35,13 +42,20 @@ export declare class ImDeliveryStore {
     private readonly host;
     private readonly tails;
     private readonly cursorTails;
+    private readonly cursors;
     /** @param records - sqlite delivery records. @param host - account policy and post-commit publisher. */
     constructor(records: ImDeliverySqlite, host: ImDeliveryHost);
-    /** Mark interrupted platform calls uncertain before new work can claim them. */
+    /** Recover interrupted sends and unfinished file preparations before publishing the runtime, independently of provider availability. */
     recoverInterruptedAttempts(): Promise<void>;
-    ingestInboundPage(request: ImIngestInboundPageRequest): Promise<ImInboundPageResult>;
+    /** @param request - Validated page and scope. @param receiptTime - Instance script time; absent uses the ingestion clock. @returns The durable page receipt. */
+    ingestInboundPage(request: ImIngestInboundPageRequest, receiptTime?: string): Promise<ImInboundPageResult>;
     queryInboundOperation(scope: ImDeliveryScope, operationId: ImDeliveryOperationId): ImInboundOperationQuery;
     getConversationCursor(scope: ImDeliveryScope): ImConversationCursor;
+    /**
+     * @param project - pure function of one conversation's records.
+     * @returns values derived at each document parse or write; a conversation without a document projects its initial records on every read.
+     */
+    projectConversations<T extends object>(project: (records: ImConversationRecords) => T): ImConversationProjection<T>;
     /** @param scope - durable conversation. @returns last admitted presentation, including the assigned service account when known. */
     getConversationPresentation(scope: ImDeliveryScope): ImConversationPresentation | undefined;
     getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
@@ -65,14 +79,18 @@ export declare class ImDeliveryStore {
     getInbound(scope: ImDeliveryScope, messageId: ImMessageId): ImInboundMessageView;
     markSubmitted(request: ImMarkSubmittedRequest): Promise<ImMarkSubmittedResult>;
     importJsonlHistory(request: ImImportJsonlHistoryRequest): Promise<ImImportJsonlHistoryResult>;
-    registerOutbound(request: ImRegisterOutboundRequest, frozenBinding?: ImOutboundRouteBinding): Promise<ImOutboundView>;
+    /** @param request - Scoped send intent. @param frozenBinding - Route observed by the Agent task. @param clock - Time sampled when the intent is stored. @returns Durable outbox intent. */
+    registerOutbound(request: ImRegisterOutboundRequest, frozenBinding?: ImOutboundRouteBinding, clock?: () => number): Promise<ImOutboundView>;
+    /** @param request - owning real outbox intent. @param media - durable upload display facts. @returns the updated row after its preparation commit. */
+    recordMediaPreparation(request: ImGetOutboundRequest, media: NonNullable<ImOutboundView['media']>): Promise<ImOutboundView>;
     beginOutboundAttempt(request: ImBeginOutboundAttemptRequest): Promise<ImBeginOutboundAttemptResult>;
     /** @param request - Owning attempt. @returns Whether its frozen route and handling epoch still authorize an external submission. */
     authorizeOutboundSubmission(request: ImBeginOutboundAttemptRequest & {
         readonly attemptId: ImOutboundAttemptId;
     }): boolean;
     settleOutboundAttempt(request: ImSettleOutboundAttemptRequest): Promise<ImOutboundView>;
-    settleSimulationOutbound(request: ImSettleSimulationOutboundRequest): Promise<ImOutboundView>;
+    /** @param request - Local simulation intent. @param clock - Time sampled when the send settles. @returns Durable local receipt. */
+    settleSimulationOutbound(request: ImSettleSimulationOutboundRequest, clock?: () => number): Promise<ImOutboundView>;
     getOutbound(request: ImGetOutboundRequest): ImOutboundView | undefined;
     queryOutbound(request: ImOutboundQueryRequest): ImOutboundPage;
     cancelPendingAi(request: ImCancelPendingAiRequest): Promise<readonly ImOutboundView[]>;
@@ -85,6 +103,11 @@ export declare class ImDeliveryStore {
     private lookup;
     private require;
     private mutate;
+    /** Apply one transform to the stored or initial aggregate; the caller already holds the scope's queue. */
+    private applyMutation;
+    /** @param queue - external durable queue. @returns completion after every journal transfer is synced and removed from SQLite. */
+    transferUploads(queue: ImMessageUploadQueue): Promise<void>;
+    private persistMutation;
     private enqueue;
     private enqueueCursor;
 }

package/lib/types/errors.d.ts

@@ -1,5 +1,5 @@
 /** Stable IM runtime configuration failure codes. */
-export type ImRuntimeErrorCode = 'IM_ACCOUNT_NOT_FOUND' | 'IM_ACCOUNT_EXISTS' | 'IM_ACCOUNT_SETUP_CONFIRMED' | 'IM_ACCOUNT_SETUP_NOT_FOUND' | 'IM_IDENTITY_MISMATCH' | 'IM_DELIVERY_OPERATION_REUSED' | 'IM_DELIVERY_SCOPE_INVALID' | 'IM_JSONL_INVALID' | 'IM_LOGIN_ATTEMPT_NOT_FOUND' | 'IM_LOGIN_UNAVAILABLE' | 'IM_MANUAL_ACCOUNT_UNAVAILABLE' | 'IM_MANUAL_MESSAGE_INVALID' | 'IM_MANUAL_RETRY_INVALID' | 'IM_MESSAGE_ALREADY_SUBMITTED' | 'IM_MESSAGE_NOT_FOUND' | 'IM_OPERATION_REUSED' | 'IM_OUTBOUND_ATTEMPT_MISMATCH' | 'IM_OUTBOUND_NOT_FOUND' | 'IM_OUTBOUND_REQUEST_REUSED' | 'IM_OUTBOUND_STATE_INVALID' | 'IM_ROUTE_INVALID' | 'IM_ROUTE_POLICY_DENIED' | 'IM_REAL_SESSION_NOT_FOUND' | 'IM_SESSION_PERSISTENCE_UNAVAILABLE' | 'IM_SIMULATION_INSTANCE_ACTIVE' | 'IM_SIMULATION_INSTANCE_NOT_FOUND' | 'IM_SIMULATION_INSTANCE_NOT_RUNNING' | 'IM_SIMULATION_SESSION_INVALID' | 'IM_SIMULATION_TARGET_INVALID';
+export type ImRuntimeErrorCode = 'IM_ACCOUNT_REPLACED' | 'IM_ACCOUNT_CHANGED' | 'IM_MEDIA_PREPARATION_UNKNOWN' | 'IM_MEDIA_UPLOAD_FAILED' | 'IM_MEDIA_DOWNLOAD_FAILED' | 'IM_MEDIA_CONVERSATION_FAILED' | 'IM_MEDIA_FILE_UPLOAD_NOT_READY' | 'IM_MEDIA_INVALID' | 'IM_MEDIA_UNAVAILABLE' | 'IM_AUTHORIZATION_REQUIRED' | 'IM_EVALUATION_UNAVAILABLE' | 'IM_ACCOUNT_NOT_FOUND' | 'IM_ACCOUNT_EXISTS' | 'IM_ACCOUNT_SETUP_CONFIRMED' | 'IM_ACCOUNT_SETUP_NOT_FOUND' | 'IM_IDENTITY_MISMATCH' | 'IM_DELIVERY_OPERATION_REUSED' | 'IM_DELIVERY_SQLITE_BUSY' | 'IM_DELIVERY_SCOPE_INVALID' | 'IM_JSONL_INVALID' | 'IM_LOGIN_ATTEMPT_NOT_FOUND' | 'IM_LOGIN_UNAVAILABLE' | 'IM_MANUAL_ACCOUNT_UNAVAILABLE' | 'IM_MANUAL_MESSAGE_INVALID' | 'IM_MANUAL_HANDLING_CHANGED' | 'IM_MANUAL_RETRY_INVALID' | 'IM_MESSAGE_ALREADY_SUBMITTED' | 'IM_MESSAGE_NOT_FOUND' | 'IM_OPERATION_REUSED' | 'IM_OUTBOUND_ATTEMPT_MISMATCH' | 'IM_OUTBOUND_NOT_FOUND' | 'IM_OUTBOUND_REQUEST_REUSED' | 'IM_OUTBOUND_STATE_INVALID' | 'IM_ROUTE_INVALID' | 'IM_ROUTE_POLICY_DENIED' | 'IM_REAL_SESSION_NOT_FOUND' | 'IM_SESSION_PERSISTENCE_UNAVAILABLE' | 'IM_SIMULATION_CLOCK_REGISTERED' | 'IM_SIMULATION_INSTANCE_ACTIVE' | 'IM_SIMULATION_INSTANCE_NOT_FOUND' | 'IM_SIMULATION_INSTANCE_NOT_RUNNING' | 'IM_SIMULATION_SESSION_INVALID' | 'IM_SIMULATION_TARGET_INVALID';
 /** Structured IM runtime failure for requests that cannot produce a durable receipt. */
 export declare class ImRuntimeError extends Error {
     readonly code: ImRuntimeErrorCode;