@gestaltrun/dsh-im-runtime 0.0.0-stage → 0.1.0

package/lib/types/delivery.d.ts

@@ -0,0 +1,91 @@
+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 { ImAccountId, ImPlatform, ImRouteResolution } from './types.ts';
+interface ImDeliveryHost {
+    automaticHandlingBlocked(scopeId: ImScopeId): boolean;
+    inspectAccount(id: ImAccountId): {
+        readonly platform: ImPlatform;
+        readonly paused: boolean;
+        readonly revision: import('./types.ts').ImRevision;
+    } | undefined;
+    resolveRoute(scope: ImRealDeliveryScope): ImRouteResolution | undefined;
+    publish(change: {
+        readonly scope: ImDeliveryScope;
+        readonly scopeId: ImScopeId;
+        readonly kind: 'inbound' | 'submitted' | 'outbound';
+        readonly messageIds?: readonly ImMessageId[];
+        readonly requestId?: ImOutboundRequestId;
+    }): void;
+}
+/**
+ * Encode every scope component in an ordered JSON tuple before hashing.
+ * @param scope - complete real or simulation conversation identity.
+ * @returns stable scope identifier shared by history, Session sources, and outbox rows.
+ */
+export declare function encodeImScopeId(scope: ImDeliveryScope): ImScopeId;
+/**
+ * Encode the platform account and provider feed name that jointly own a cursor.
+ * @param owner - provider cursor owner.
+ * @returns stable provider cursor identifier.
+ */
+export declare function encodeImProviderCursorId(owner: ImProviderCursorOwner): ImProviderCursorId;
+/** One-record mutations for complete conversation scopes. */
+export declare class ImDeliveryStore {
+    private readonly records;
+    private readonly host;
+    private readonly tails;
+    private readonly cursorTails;
+    /** @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. */
+    recoverInterruptedAttempts(): Promise<void>;
+    ingestInboundPage(request: ImIngestInboundPageRequest): Promise<ImInboundPageResult>;
+    queryInboundOperation(scope: ImDeliveryScope, operationId: ImDeliveryOperationId): ImInboundOperationQuery;
+    getConversationCursor(scope: ImDeliveryScope): ImConversationCursor;
+    /** @param scope - durable conversation. @returns last admitted presentation, including the assigned service account when known. */
+    getConversationPresentation(scope: ImDeliveryScope): ImConversationPresentation | undefined;
+    getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
+    commitProviderCursor(request: ImCommitProviderCursorRequest): Promise<ImProviderCursorCommitResult>;
+    queryProviderCursorOperation(owner: ImProviderCursorOwner, operationId: ImDeliveryOperationId): ImProviderCursorOperationQuery;
+    queryHistory(request: ImHistoryQueryRequest): ImHistoryPage;
+    pendingInbound(request: ImPendingInboundRequest): readonly ImInboundMessageView[];
+    /**
+     * Consume the current received live batch without an Agent turn.
+     * A later allow only admits newer sequence numbers.
+     * @param scope - conversation whose policy just refused admission.
+     */
+    suppressUnadmitted(scope: ImDeliveryScope): Promise<void>;
+    messageSource(scope: ImDeliveryScope, messageId: ImMessageId): ImMessageSource;
+    /** @param source - durable Session message source. @returns matched scope, or absence for stale or foreign evidence. */
+    matchMessageSource(source: ImMessageSource): {
+        readonly scope: ImDeliveryScope;
+        readonly messageId: ImMessageId;
+    } | undefined;
+    /** @param scope - complete scope. @param messageId - inbound identity. @returns stored row. */
+    getInbound(scope: ImDeliveryScope, messageId: ImMessageId): ImInboundMessageView;
+    markSubmitted(request: ImMarkSubmittedRequest): Promise<ImMarkSubmittedResult>;
+    importJsonlHistory(request: ImImportJsonlHistoryRequest): Promise<ImImportJsonlHistoryResult>;
+    registerOutbound(request: ImRegisterOutboundRequest, frozenBinding?: ImOutboundRouteBinding): 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>;
+    getOutbound(request: ImGetOutboundRequest): ImOutboundView | undefined;
+    queryOutbound(request: ImOutboundQueryRequest): ImOutboundPage;
+    cancelPendingAi(request: ImCancelPendingAiRequest): Promise<readonly ImOutboundView[]>;
+    findSentOutbound(scope: ImRealDeliveryScope, externalMessageId: string): ImOutboundView | undefined;
+    findUnknownOutbound(scope: ImRealDeliveryScope, text: string): ImOutboundView | undefined;
+    private registrationPolicy;
+    private handlingRevoked;
+    private dispatchFailure;
+    private assertRealScope;
+    private lookup;
+    private require;
+    private mutate;
+    private enqueue;
+    private enqueueCursor;
+}
+export {};

package/lib/types/errors.d.ts

@@ -0,0 +1,8 @@
+/** 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';
+/** Structured IM runtime failure for requests that cannot produce a durable receipt. */
+export declare class ImRuntimeError extends Error {
+    readonly code: ImRuntimeErrorCode;
+    /** @param code - stable failure code. @param message - diagnostic detail. */
+    constructor(code: ImRuntimeErrorCode, message: string);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/** Product-owned IM Host runtime and transport registry. */
+import './session-events.ts';
+export type * from './types.ts';
+export type * from './transport.ts';
+export type { ImRuntimeService } from './service-types.ts';
+export { ImRuntimeError } from './errors.ts';
+export type { ImRuntimeErrorCode } from './errors.ts';
+export { imRuntimeDomainSpec } from './schema.ts';
+export { encodeImProviderCursorId, encodeImScopeId } from './delivery.ts';
+export { IM_DELIVERY_SCHEMA_VERSION, ImDeliverySqlite } from './delivery-sqlite.ts';
+export { ImTransportError, ImTransports } from './transports.ts';
+export type { ImTransportErrorCode } from './transports.ts';
+export { ImRoutePolicies } from './policies.ts';
+export type { ImPolicyCheckKind, ImPolicyCheckRequest, ImPolicyDecision, ImRoutePolicy } from './policies.ts';
+export type { ImRouteControllerId } from './types.ts';
+export { resolveRouteAgentPreset } from './route-resolve.ts';
+export { ImRuntime, ImRuntime as default } from './runtime.ts';
+export type { Config as ImRuntimeConfig } from './runtime.ts';
+export type { ImHandlingPausedEvent } from './session-events.ts';

package/lib/types/policies.d.ts

@@ -0,0 +1,53 @@
+/** Registry of product controllers that authorize IM admission and automated sends. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import type { ImDeliveryScope } from './delivery-types.ts';
+import type { ImRouteControllerId, ImRouteId } from './types.ts';
+export type { ImRouteControllerId };
+/** Moments a declared route controller must authorize. */
+export type ImPolicyCheckKind = 'admit' | 'send' | 'manual-send' | 'recover' | 'simulation-end';
+/** One authorization request for a declared controller. */
+export interface ImPolicyCheckRequest {
+    readonly kind: ImPolicyCheckKind;
+    readonly controller: ImRouteControllerId;
+    readonly scope: ImDeliveryScope;
+    readonly routeId: ImRouteId;
+    readonly workspaceId: WorkspaceId;
+}
+/** Allow, or refuse with a stable code. */
+export type ImPolicyDecision = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    readonly code: string;
+    readonly message: string;
+};
+/** Product Provider that owns one controller identity. */
+export interface ImRoutePolicy {
+    check(request: ImPolicyCheckRequest): ImPolicyDecision | Promise<ImPolicyDecision>;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** IM admission and automated-send policies keyed by route controller. */
+        imRoutePolicies: ImRoutePolicies;
+    }
+}
+/** Registry whose entries live and die with their registering Cordis fiber. */
+export declare class ImRoutePolicies extends Service {
+    private readonly policies;
+    /** @param ctx - owning Cordis context. */
+    constructor(ctx: Context);
+    /**
+     * Register the policy for one controller identity.
+     * @param controller - product controller recorded on the route.
+     * @param policy - authorization Provider.
+     * @returns disposer that releases the registration.
+     */
+    register(controller: ImRouteControllerId, policy: ImRoutePolicy): () => void;
+    /**
+     * Authorize one admission or send for a declared controller.
+     * Missing Providers refuse; ordinary routes without a controller skip this registry.
+     * @param request - controller, scope, and check kind.
+     */
+    authorize(request: ImPolicyCheckRequest): Promise<ImPolicyDecision>;
+}

package/lib/types/route-resolve.d.ts

@@ -0,0 +1,10 @@
+/** Explicit Agent-preset resolution for an IM route. */
+import type { ImRouteView } from './types.ts';
+/**
+ * Resolve the Agent preset a route uses.
+ * A recorded preset is used as-is. Absence takes the runtime default.
+ * Callers must fail when a recorded preset cannot mount; they must not fall back.
+ * @param route - stored route fields.
+ * @param defaultId - AgentPresets default when the route omitted a preset.
+ */
+export declare function resolveRouteAgentPreset(route: Pick<ImRouteView, 'agentPreset'>, defaultId: string): string;

package/lib/types/runtime.d.ts

@@ -0,0 +1,360 @@
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import { type SessionId } from '@deepseek-ai/dsh-session';
+import './session-events.ts';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace';
+import { type ZodType } from 'zod';
+import type { ImExecutionAggregate } from './delivery-schema.ts';
+import { ImRoutePolicies } from './policies.ts';
+import type { ImPolicyCheckKind, ImPolicyCheckRequest, ImPolicyDecision } from './policies.ts';
+import { ImTransports } from './transports.ts';
+import type { ImAutomaticSendAuthorization } from './transport.ts';
+import type { ImBeginOutboundAttemptRequest, ImBeginOutboundAttemptResult, ImAgentTaskId, ImAgentTaskView, ImCancelPendingAiRequest, ImCommitProviderCursorRequest, ImConversationCursor, ImCustomerListPage, ImCustomerListRequest, ImCustomerReadAckRequest, ImDeliveryChange, ImDeliveryOperationId, ImDeliveryScope, ImGetOutboundRequest, ImHandlingControl, ImHistoryPage, ImHistoryQueryRequest, ImImportJsonlHistoryRequest, ImImportJsonlHistoryResult, ImInboundMessageView, ImInboundSenderEvidence, ImInboundOperationQuery, ImInboundPageResult, ImIngestInboundPageRequest, ImMarkSubmittedRequest, ImMarkSubmittedResult, ImManualMessageQuery, ImManualMessageQueryRequest, ImManualMessageResult, ImMessageId, ImMessageSource, ImOutboundPage, ImOutboundQueryRequest, ImOutboundAttemptId, ImOutboundRouteBinding, ImOutboundView, ImPendingInboundRequest, ImProviderCursorCommitResult, ImProviderCursorOperationQuery, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope, ImRealSessionBinding, ImRegisterOutboundRequest, ImRetryManualMessageRequest, ImSendManualMessageRequest, ImSessionReconciliationResult, ImSenderAttribution, ImSetHandlingControlRequest, ImSettleOutboundAttemptRequest, ImSettleSimulationOutboundRequest, ImSimulationDeliveryScope, ImSimulationInstanceId, ImScopeId } from './delivery-types.ts';
+import type { ImAccountId, ImAccountCandidate, ImAccountSetupId, ImAccountSetupPreview, ImCancelAccountSetupResult, ImConfirmAccountSetupRequest, ImAccountLifecycleRequest, ImAccountSetupRequest, ImAccountMutationResult, ImAccountOperationQuery, ImAccountView, ImAssignedActorCandidate, ImConversationCandidate, ImConversationCandidatePage, ImConversationKind, ImDirectRecipient, ImCreateRouteRequest, ImDeleteRouteRequest, ImOperationId, ImPlatform, ImPlatformLoginAttemptId, ImPlatformLoginStatus, ImRebindRouteRequest, ImRemoveSimulationTargetRequest, ImRouteMutationResult, ImRouteOperationQuery, ImRouteResolution, ImRouteTarget, ImRouteView, ImRuntimeChange, ImRuntimeSnapshot, ImSaveRouteRequest, ImSaveSimulationTargetRequest, ImSetAccountPausedRequest, ImSimulationTargetMutationResult, ImSimulationTargetOperationQuery, ImCreateSimulationInstanceRequest, ImSimulationInjectionQuery, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImImportSimulationHistoryRequest, ImImportSimulationHistoryResult, ImSimulationInstanceView, ImSimulationSessionScope, ImSimulationTargetView } from './types.ts';
+import type { ImRuntimeService } from './service-types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Synchronous controller veto immediately before an automatic external submission.
+         * @param request - Current route controller and conversation.
+         * @returns A refusal to block submission, or void to delegate.
+         * @mode bail
+         */
+        'imRuntime/authorize-submission'(request: ImPolicyCheckRequest): Extract<ImPolicyDecision, {
+            allow: false;
+        }> | void;
+    }
+}
+/** Stable Wangwang refusal when a direct send has no observed counterpart sender. */
+export declare const WANGWANG_DIRECT_RECIPIENT_UNAVAILABLE = "WANGWANG_DIRECT_RECIPIENT_UNAVAILABLE";
+/** Runtime limits applied to one durable Agent admission. */
+export interface Config {
+    /** Maximum inbound messages copied into one Agent input. */
+    readonly admissionBatchSize?: number;
+    /** Time that unconfirmed provider setup material remains in Host memory. */
+    readonly accountSetupTtlMs?: number;
+    /** Sqlite file for conversation, cursor, and execution records. */
+    readonly deliverySqlitePath?: string | undefined;
+}
+interface ResolvedConfig {
+    readonly admissionBatchSize: number;
+    readonly accountSetupTtlMs: number;
+    readonly deliverySqlitePath?: string | undefined;
+}
+/** Host service implementing the durable configuration half of IM takeover. */
+export declare class ImRuntime extends Service implements ImRuntimeService {
+    static inject: string[];
+    static Config: ZodType<Config>;
+    private accounts?;
+    private simulationTargets?;
+    private simulationInstances?;
+    private deliveryRecords?;
+    private delivery?;
+    private coordinator;
+    private simulationController;
+    private readonly pendingAutomaticPauses;
+    private readonly automaticSendEpochs;
+    private generation;
+    private deliveryGeneration;
+    private simulationTail;
+    private readonly activeListeners;
+    private readonly listenerStates;
+    private readonly listenerTails;
+    private readonly pendingAccountSetups;
+    private readonly observations;
+    readonly transports: ImTransports;
+    readonly policies: ImRoutePolicies;
+    readonly config: ResolvedConfig;
+    /** @param ctx - Cordis context carrying StorageDomain and Credentials. @param config - validated Agent admission limits. */
+    constructor(ctx: Context, config?: Config);
+    /** Open the authoritative configuration domain before publishing the service. */
+    protected [Service.init](): Promise<void>;
+    snapshot(): ImRuntimeSnapshot;
+    subscribe(listener: (change: ImRuntimeChange) => void): () => void;
+    startPlatformLogin(platform: ImPlatform, signal?: AbortSignal): Promise<ImPlatformLoginStatus>;
+    platformLoginStatus(platform: ImPlatform, attemptId: ImPlatformLoginAttemptId): ImPlatformLoginStatus;
+    cancelPlatformLogin(platform: ImPlatform, attemptId: ImPlatformLoginAttemptId): Promise<ImPlatformLoginStatus>;
+    listAccountCandidates(platform: ImPlatform, signal?: AbortSignal): Promise<readonly ImAccountCandidate[]>;
+    discoverConversations(accountId: ImAccountId, signal?: AbortSignal): Promise<ImConversationCandidatePage>;
+    inspectConversation(accountId: ImAccountId, conversationId: string, conversationKind: ImConversationKind, signal?: AbortSignal): Promise<ImConversationCandidate>;
+    /** @param accountId - configured account. @param signal - caller lifetime. @returns assigned service accounts when the platform exposes them. */
+    listAssignedActors(accountId: ImAccountId, signal?: AbortSignal): Promise<readonly ImAssignedActorCandidate[]>;
+    previewAccountSetup(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountSetupPreview>;
+    confirmAccountSetup(request: ImConfirmAccountSetupRequest): Promise<ImAccountMutationResult>;
+    cancelAccountSetup(setupId: ImAccountSetupId): ImCancelAccountSetupResult;
+    addAccount(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountView>;
+    setAccountPaused(request: ImSetAccountPausedRequest): Promise<ImAccountMutationResult>;
+    disconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    reconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /**
+     * Delete one configured account after comparing its observed revision.
+     * @param request - account identity and revision observed before confirmation.
+     * @returns the durable deletion receipt.
+     */
+    deleteAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    refreshAccount(request: ImAccountLifecycleRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
+    queryAccountOperation(accountId: ImAccountId, operationId: ImOperationId): ImAccountOperationQuery;
+    createRoute(request: ImCreateRouteRequest): Promise<ImRouteMutationResult>;
+    saveRoute(request: ImSaveRouteRequest): Promise<ImRouteMutationResult>;
+    rebindRoute(request: ImRebindRouteRequest): Promise<ImRouteMutationResult>;
+    deleteRoute(request: ImDeleteRouteRequest): Promise<ImRouteMutationResult>;
+    queryRouteOperation(account: ImAccountId, operationId: ImOperationId): ImRouteOperationQuery;
+    /**
+     * Keep history flowing for one account without an enabled admit route.
+     * @param accountId - connected account.
+     * @param observation - conversation kind and target to receive.
+     * @returns disposer that drops the lease and reconciles the listener.
+     */
+    registerObservation(accountId: ImAccountId, observation: {
+        readonly conversationKind: ImConversationKind;
+        readonly target: ImRouteTarget;
+    }): () => void;
+    /**
+     * Authorize one admission or automated send when the route declared a controller.
+     * Ordinary routes without a controller are allowed.
+     * @param kind - check moment.
+     * @param route - frozen route.
+     * @param scope - conversation identity.
+     */
+    authorizeRoutePolicy(kind: ImPolicyCheckKind, route: ImRouteView, scope: import('./delivery-types.ts').ImDeliveryScope): Promise<ImPolicyDecision>;
+    resolveRoute(account: ImAccountId, conversationKind: ImConversationKind, conversationId: string, assignedActorId?: string): ImRouteResolution;
+    /** Whether this real conversation currently admits automatic handling. */
+    private conversationAdmits;
+    /** @param scope - durable real conversation. @returns last admitted presentation, including the assigned service account when known. */
+    getConversationPresentation(scope: ImRealDeliveryScope): import('./delivery-types.ts').ImConversationPresentation | undefined;
+    saveSimulationTarget(request: ImSaveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    removeSimulationTarget(request: ImRemoveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    querySimulationTargetOperation(workspaceId: WorkspaceId, operationId: ImOperationId): ImSimulationTargetOperationQuery;
+    listSimulationInstances(): readonly ImSimulationInstanceView[];
+    getSimulationInstance(instanceId: ImSimulationInstanceId): ImSimulationInstanceView | undefined;
+    scopeForSession(sessionId: SessionId): ImSimulationSessionScope | undefined;
+    realScopeForSession(sessionId: SessionId): ImRealSessionBinding | undefined;
+    realBindingForScope(scopeId: ImScopeId): ImRealSessionBinding | undefined;
+    sendManualMessage(request: ImSendManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    queryManualMessage(request: ImManualMessageQueryRequest): ImManualMessageQuery;
+    confirmManualMessage(request: ImManualMessageQueryRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    retryManualMessage(request: ImRetryManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    createSimulationInstance(request: ImCreateSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
+    injectSimulationMember(request: ImInjectSimulationMemberRequest): Promise<ImInboundMessageView>;
+    injectSimulationManagedHuman(request: ImInjectSimulationManagedHumanRequest): Promise<ImInboundMessageView>;
+    querySimulationInjection(request: ImSimulationInjectionQuery): ImInboundOperationQuery;
+    beginStopSimulation(instanceId: ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    beginStopSimulationForSession(sessionId: SessionId): Promise<ImSimulationInstanceView>;
+    waitSimulationStopped(instanceId: ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    subscribeDelivery(listener: (change: ImDeliveryChange) => void): () => void;
+    ingestInboundPage(request: ImIngestInboundPageRequest): Promise<ImInboundPageResult>;
+    queryInboundOperation(scope: ImDeliveryScope, operationId: ImDeliveryOperationId): ImInboundOperationQuery;
+    getConversationCursor(scope: ImDeliveryScope): ImConversationCursor;
+    getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
+    commitProviderCursor(request: ImCommitProviderCursorRequest): Promise<ImProviderCursorCommitResult>;
+    queryProviderCursorOperation(owner: ImProviderCursorOwner, operationId: ImDeliveryOperationId): ImProviderCursorOperationQuery;
+    queryHistory(request: ImHistoryQueryRequest): ImHistoryPage;
+    /**
+     * List customer rows for one account and source from the rebuildable index.
+     * @param request - account, real/simulation filter, optional substring, and reader.
+     */
+    listCustomers(request: ImCustomerListRequest): ImCustomerListPage;
+    /**
+     * Advance one reader's live inbound watermark with max semantics.
+     * @param request - reader, scope, and observed arrival sequence.
+     */
+    ackCustomerRead(request: ImCustomerReadAckRequest): void;
+    /**
+     * Persist one scope's automatic-handling pause fact.
+     * @param request - scope and pause fields.
+     */
+    setHandlingControl(request: ImSetHandlingControlRequest): ImHandlingControl;
+    /**
+     * Read one scope's automatic-handling pause fact.
+     * @param scopeId - complete conversation identity.
+     */
+    getHandlingControl(scopeId: ImScopeId): ImHandlingControl | undefined;
+    /**
+     * Project an unresolved durable forward pause into automatic-processing authorization.
+     * @param scopeId - Customer whose journal pause is unresolved.
+     * @param pending - True before attempting persistence; false only after reconciling the durable pause and journal acknowledgement.
+     * Pending projections survive their caller's disposal until reconciliation or runtime shutdown; they do not change the persisted handling control.
+     */
+    setAutomaticHandlingPausePending(scopeId: ImScopeId, pending: boolean): void;
+    /** @param scopeId - Complete customer scope. @returns Whether a pending journal pause or durable handling control blocks automatic processing. */
+    isAutomaticHandlingBlocked(scopeId: ImScopeId): boolean;
+    private recordHandlingPaused;
+    /**
+     * Open a persisted Agent Session and append `im/handling-paused`.
+     * When no Session log exists, skip the event: handling control remains the
+     * SQLite row from `setHandlingControl`, which is the source of truth for
+     * pause/resume even if a later Agent Session is created.
+     */
+    private appendHandlingPausedToPersisted;
+    /**
+     * Resolve a stored conversation identity from its scope id.
+     * @param scopeId - complete conversation identity.
+     */
+    getDeliveryScope(scopeId: ImScopeId): ImDeliveryScope | undefined;
+    pendingInbound(request: ImPendingInboundRequest): readonly ImInboundMessageView[];
+    getAgentTask(scope: ImDeliveryScope): ImAgentTaskView | undefined;
+    /** @param scope - complete conversation identity. @param messageId - stored inbound identity. @returns stored message. */
+    getInboundMessage(scope: ImDeliveryScope, messageId: ImMessageId): ImInboundMessageView;
+    messageSource(scope: ImDeliveryScope, messageId: ImMessageId): ImMessageSource;
+    markSubmitted(request: ImMarkSubmittedRequest): Promise<ImMarkSubmittedResult>;
+    /** Consume live pending that a route policy just refused, without an Agent turn. */
+    suppressUnadmitted(scope: ImDeliveryScope): Promise<void>;
+    /** Advance watermarks of conversations this newly enabled route would now admit. */
+    private suppressUnadmittedMatchedBy;
+    sessionUserMessage(scope: ImDeliveryScope, messageId: ImMessageId): UserMessage;
+    reconcileSession(sessionId: SessionId): Promise<ImSessionReconciliationResult>;
+    importJsonlHistory(request: ImImportJsonlHistoryRequest): Promise<ImImportJsonlHistoryResult>;
+    importSimulationHistory(request: ImImportSimulationHistoryRequest): Promise<ImImportSimulationHistoryResult>;
+    registerOutbound(request: ImRegisterOutboundRequest): Promise<ImOutboundView>;
+    /** @param request - scope-fixed automated intent. @param binding - task generation recorded before Agent execution. @returns durable intent or a route-changed rejection. */
+    registerAgentOutbound(request: ImRegisterOutboundRequest, binding: ImOutboundRouteBinding): Promise<ImOutboundView>;
+    /**
+     * Bind automatic provider preparation to one scope's handling epoch and durable attempt.
+     * @param request - Owning dispatch attempt.
+     * @param signal - Tool cancellation, retained after external submission.
+     * @returns Provider authorization; dispose after settlement. Submission rechecks controller policy; customer pause revokes only unsubmitted preparation.
+     */
+    automaticSendAuthorization(request: ImBeginOutboundAttemptRequest & {
+        readonly attemptId: ImOutboundAttemptId;
+    }, signal: AbortSignal): ImAutomaticSendAuthorization;
+    beginOutboundAttempt(request: ImBeginOutboundAttemptRequest): Promise<ImBeginOutboundAttemptResult>;
+    settleOutboundAttempt(request: ImSettleOutboundAttemptRequest): Promise<ImOutboundView>;
+    settleSimulationOutbound(request: ImSettleSimulationOutboundRequest): Promise<ImOutboundView>;
+    getOutbound(request: ImGetOutboundRequest): ImOutboundView | undefined;
+    queryOutbound(request: ImOutboundQueryRequest): ImOutboundPage;
+    cancelPendingAi(request: ImCancelPendingAiRequest): Promise<readonly ImOutboundView[]>;
+    findSentOutbound(scope: ImRealDeliveryScope, externalMessageId: string): ImOutboundView | undefined;
+    private confirmUnknownOutbound;
+    private inboundSender;
+    classifyInboundSender(scope: ImRealDeliveryScope, evidence: ImInboundSenderEvidence): ImSenderAttribution;
+    private isNativeActor;
+    /** @param workspaceId - simulated-user Workspace. @returns its current target setting. */
+    simulationTargetForWorkspace(workspaceId: WorkspaceId): ImSimulationTargetView | undefined;
+    /** @param target - current workspace target setting. @returns its exact route when still present. */
+    routeForSimulationTarget(target: ImSimulationTargetView): ImRouteView | undefined;
+    /** @param target - current workspace target setting. @returns its exact safe account when still present. */
+    accountForSimulationTarget(target: ImSimulationTargetView): ImAccountView | undefined;
+    /** @param scope - claimed frozen simulation scope. @returns whether its exact instance accepts delivery. */
+    isSimulationScopeRunning(scope: ImSimulationDeliveryScope): boolean;
+    /** Emit a post-commit instance notification for BFF followers. @param instanceId - changed instance. */
+    publishSimulationInstanceChange(instanceId: ImSimulationInstanceId): void;
+    private requireRealSessionBinding;
+    private requireManualBinding;
+    private assertNamedManualAccount;
+    /**
+     * Hosting controllers shop-match human-manual send the same way they
+     * shop-match `requireOwnedScope`. Ordinary routes without a controller skip.
+     */
+    private authorizeManualSend;
+    private realBindingForScopeSeat;
+    private bindingFromTask;
+    /**
+     * Direct peer that a send may use.
+     * Wangwang accepts a stored id only when this scope has observed that external sender; otherwise it uses the latest observed sender. The conversation id is never a recipient. Other platforms keep a stored peer, then an observed sender.
+     * @param scope - conversation being sent or displayed.
+     * @param stored - recipient frozen on the task, when one exists.
+     * @returns usable peer, or absence when Wangwang has not observed a counterpart.
+     */
+    usableDirectRecipient(scope: ImDeliveryScope, stored?: ImDirectRecipient): ImDirectRecipient | undefined;
+    /**
+     * Store the Wangwang peer a send is allowed to use, including clearing one that no observed sender supports.
+     * @param sessionId - Agent Session that owns the task, when one exists.
+     * @param recipient - usable peer, or absence.
+     */
+    rememberDirectRecipient(sessionId: SessionId | undefined, recipient: ImDirectRecipient | undefined): Promise<void>;
+    private composeRealBinding;
+    private requireManualAccount;
+    private outboundOwner;
+    private assertManualRequestOwner;
+    private manualMessageResult;
+    private dispatchManualMessage;
+    private finishManualMessage;
+    /**
+     * Persist a DSH operator send as live inbound so Agent admission does not wait for a provider echo.
+     * @param scope - conversation that owns the outbound.
+     * @param outbound - settled human-manual intent.
+     */
+    private admitManualOutbound;
+    private settleManualResult;
+    private prepareVerifiedAccount;
+    private persistPreparedAccount;
+    private accountIdForSetup;
+    private expireAccountSetup;
+    private releaseAccountSetup;
+    private clearAccountSetups;
+    private accountTable;
+    private simulationTargetTable;
+    private simulationInstanceTable;
+    private requireSimulationController;
+    private simulationScope;
+    private deliveryStore;
+    private deliveryRecordsStore;
+    /**
+     * Insert one execution when its task id is absent.
+     * @param task - durable Agent task generation.
+     * @returns the stored record, which may already exist.
+     */
+    persistExecution(task: ImExecutionAggregate): Promise<ImExecutionAggregate>;
+    /**
+     * Overwrite one execution record.
+     * @param task - complete stored generation.
+     */
+    putExecution(task: ImExecutionAggregate): Promise<void>;
+    /**
+     * Read one execution by task id.
+     * @param id - durable task identity.
+     * @returns the stored generation, or absence.
+     */
+    getExecution(id: ImAgentTaskId): ImExecutionAggregate | undefined;
+    /**
+     * Apply one serialized transform to a stored execution.
+     * @param id - durable task identity.
+     * @param fn - synchronous transform of the current record.
+     * @returns the stored next record.
+     */
+    updateExecution(id: ImAgentTaskId, fn: (current: ImExecutionAggregate) => ImExecutionAggregate): Promise<ImExecutionAggregate>;
+    /**
+     * List task generations for one conversation in generation order.
+     * @param scopeId - complete conversation identity.
+     * @returns stored generations for that scope.
+     */
+    executionsForScope(scopeId: import('./delivery-types.ts').ImScopeId): readonly ImExecutionAggregate[];
+    /**
+     * Resolve the latest execution bound to one Agent Session.
+     * @param sessionId - IM Agent Session.
+     * @returns that Session's newest task, or absence.
+     */
+    executionForSession(sessionId: SessionId): ImExecutionAggregate | undefined;
+    private assertUnusedIdentity;
+    private requireAccount;
+    private accountError;
+    private updateAccountRoute;
+    private enqueueSimulation;
+    /** Persist a connection intent separately from pause and process listener state. */
+    private setConnectionIntent;
+    /** Store one provider authorization observation under the account revision CAS. */
+    private storeRefreshResult;
+    private publish;
+    private publishDelivery;
+    /** Serialize listener state changes for one configured account. */
+    private scheduleListener;
+    /** Start or stop the provider listener from durable account, route, and observation facts. */
+    private reconcileListener;
+    /** Stop one exact listener before publishing a later start for the same account. */
+    private stopListener;
+    /** Observe an established listener without turning completion into automatic retry. */
+    private observeListener;
+    /** Publish one exact listener generation's terminal state. */
+    private finishListener;
+    /** Stop one ready provider handle and consume its terminal signal without exposing provider errors. */
+    private closeListenerHandle;
+    /** Drain every provider listener owned by this runtime. */
+    private stopAllListeners;
+    /** Bind a provider page sink to one configured account and its platform. */
+    private transportSink;
+    /** Persist every conversation page before committing the provider-owned cursor. */
+    private receiveTransportPage;
+    /** Publish process listener facts without scheduling another reconciliation. */
+    private publishListener;
+}
+export default ImRuntime;

package/lib/types/schema.d.ts

@@ -0,0 +1,50 @@
+import { type ZodType } from 'zod';
+import type { ImAccountId, ImAccountMutationResult, ImAccountView, ImRouteMutationResult, ImRouteView, ImSimulationTargetMutationResult, ImSimulationTargetView, ImSimulationInstanceId, ImSimulationInstanceView } from './types.ts';
+/** Stored account fields; listener status is process state and is derived on read. */
+export type ImAccountRecord = Omit<ImAccountView, 'listener'>;
+export declare const imAccountRecordSchema: ZodType<ImAccountRecord>;
+export declare const imRouteSchema: ZodType<ImRouteView>;
+interface StoredRouteOperation {
+    readonly fingerprint: string;
+    readonly result: ImRouteMutationResult;
+}
+interface StoredAccountMutationResult extends Omit<ImAccountMutationResult, 'account'> {
+    readonly account: ImAccountRecord;
+}
+interface StoredAccountOperation {
+    readonly fingerprint: string;
+    readonly result: StoredAccountMutationResult;
+}
+/** One atomic account aggregate: safe account facts, routes, and queryable operation receipts. */
+export interface ImAccountAggregate {
+    readonly account: ImAccountRecord;
+    readonly routes: Readonly<Record<string, ImRouteView>>;
+    readonly routeOperations: Readonly<Record<string, StoredRouteOperation>>;
+    readonly accountOperations: Readonly<Record<string, StoredAccountOperation>>;
+}
+export declare const imAccountAggregateSchema: ZodType<ImAccountAggregate>;
+export declare const imSimulationTargetSchema: ZodType<ImSimulationTargetView>;
+interface StoredSimulationTargetOperation {
+    readonly fingerprint: string;
+    readonly result: ImSimulationTargetMutationResult;
+}
+/** Workspace simulation-target aggregate retaining receipts after target removal. */
+export interface ImSimulationTargetAggregate {
+    readonly workspaceId: import('@deepseek-ai/dsh-workspace').WorkspaceId;
+    readonly target?: ImSimulationTargetView;
+    readonly operations: Readonly<Record<string, StoredSimulationTargetOperation>>;
+}
+export declare const imSimulationTargetAggregateSchema: ZodType<ImSimulationTargetAggregate>;
+/** Parser for one durable two-Session simulation lifecycle. */
+export declare const imSimulationInstanceSchema: ZodType<ImSimulationInstanceView>;
+/** IM configuration storage schema. Cross-account or cross-table transactions are not implied. */
+export declare const imRuntimeDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        accounts: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<ImAccountId, ImAccountAggregate>;
+        simulation_targets: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<import("@deepseek-ai/dsh-workspace/types").WorkspaceId, ImSimulationTargetAggregate>;
+        simulation_instances: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<ImSimulationInstanceId, ImSimulationInstanceView>;
+    };
+};
+export {};