@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/dist/internal/endpoint/external-inbound.d.ts

@@ -0,0 +1,36 @@
+import { type EndpointEvent, type EndpointExternalInboundClaimResult, type EndpointExternalInboundOutcome, type EndpointExternalInboundReplyIntent, type EndpointExternalInboundSource } from '../backend-contracts/index.js';
+import type { EndpointIntent } from './engine.js';
+import { type EndpointStore, type EndpointStoreTransaction } from './store.js';
+export interface ExternalInboundClaim {
+    requestId: string;
+    installationGeneration: number;
+    source: EndpointExternalInboundSource;
+    replyIntent?: EndpointExternalInboundReplyIntent;
+    replyOperationId?: string;
+    outcome?: EndpointExternalInboundOutcome;
+}
+/** Uses the existing inbox and its ready index. No expiry makes accepted work
+ * executable again: a lost HTTP response leaves explicit uncertain work. */
+export declare function createExternalInboundClaims(input: {
+    store: EndpointStore;
+    ready(): Promise<unknown>;
+    assertOpen(): void;
+    assertCurrent(tx: EndpointStoreTransaction): Promise<void>;
+    clock(): number;
+    hash(value: string): Promise<string>;
+    ownershipVersion?: number;
+}): {
+    claim(id: string, requestId: string, authorizedEvent: EndpointEvent): Promise<EndpointExternalInboundClaimResult>;
+    reserveReply(id: string, requestId: string, intent: EndpointExternalInboundReplyIntent): Promise<boolean>;
+    /** Seal the selected authority with the ordinary engine preparation identity.
+     * A reply reservation alone is not preparation; a replacement request may
+     * still refresh its authority until this transaction commits. */
+    prepareReply(id: string, requestId: string, operationId: string, prepare: () => Promise<{
+        event: EndpointEvent;
+        intent: EndpointIntent;
+    }>): Promise<{
+        event: EndpointEvent;
+        replayed: boolean;
+    }>;
+    settle(id: string, requestId: string, outcome: EndpointExternalInboundOutcome, replyFingerprint?: string): Promise<boolean>;
+};

package/dist/internal/endpoint/handoff.d.ts

@@ -0,0 +1,50 @@
+import type { EndpointInboundRecord } from './engine.js';
+import type { EndpointStore, EndpointStoreTransaction } from './store.js';
+export type EndpointInboundHandoffPhase = 'queued' | 'claiming' | 'submitted' | 'released' | 'settled';
+/** Process-local capability for one durable input generation. Never serialize it. */
+export interface EndpointInboundHandoff {
+    readonly id: string;
+    readonly conversationId?: string;
+    readonly phase: EndpointInboundHandoffPhase;
+    /** Retain this input in the adapter's existing queue. No retry is scheduled here. */
+    defer(reason?: string): Promise<boolean>;
+    /** Relinquish unsubmitted input to the existing durable inbox. */
+    release(reason?: string): Promise<boolean>;
+    /** Explicitly discard proven unsubmitted input. Submitted effects need reconciliation. */
+    cancel(reason?: string): Promise<boolean>;
+    /** The adapter has positive completion or non-dispatch proof. */
+    settle(reason?: string): Promise<boolean>;
+}
+export type EndpointInboundStartResult<T> = {
+    status: 'submitted';
+    value: T;
+} | {
+    status: 'deferred' | 'unavailable' | 'canceled';
+};
+/** Owns handoff transitions, not provider scheduling, retry policy or output recovery. */
+export declare function createInboundHandoffs(input: {
+    store: EndpointStore;
+    owner: string;
+    ids(): string;
+    clock(): number;
+    leaseMs: number;
+    ready(): Promise<unknown>;
+    assertOpen(): void;
+    assertReady(records: EndpointInboundRecord[]): Promise<void>;
+    /** Required by trusted-host positive non-submission reconciliation. */
+    assertCurrent?(tx: EndpointStoreTransaction): Promise<void>;
+}): {
+    acquire: (id: string) => Promise<EndpointInboundHandoff | null>;
+    start: <T>(handles: EndpointInboundHandoff | readonly EndpointInboundHandoff[], submit: () => T | Promise<T>) => Promise<EndpointInboundStartResult<T>>;
+    reconcileNotSubmitted: (id: string, expected: {
+        expectedHandoffGeneration: string;
+        expectedInstallationId: string;
+    }) => Promise<boolean>;
+    /** Retry only already-requested durable writes, never native submission. */
+    retryPendingDispositions(): Promise<void>;
+    /** Reuse the consumer's existing pump; no separate handoff heartbeat. */
+    refresh(id: string): Promise<boolean>;
+    uncertain(id: string, reason?: string): Promise<boolean> | undefined;
+    settle(id: string, reason?: string): Promise<boolean> | undefined;
+    close(): Promise<void>;
+};

package/dist/internal/endpoint/history.d.ts

@@ -0,0 +1,22 @@
+import type { Endpoint } from './engine.js';
+export interface EndpointHistorySnapshot {
+    messages: Record<string, unknown>[];
+    loading: boolean;
+    loadingMore: boolean;
+    hasMore: boolean;
+}
+export interface EndpointHistorySubscription {
+    loadMore(): void;
+    close(): void;
+}
+export interface EndpointHistoryObserver {
+    observe(parameters: {
+        conversationId: string;
+        startAt?: number;
+        admissionId?: string;
+    }, listener: (value: EndpointHistorySnapshot) => void, onError?: (error: unknown) => void): EndpointHistorySubscription;
+    close(): void;
+}
+/** Explicit older pages plus one bounded live page. Loaded IDs are refreshed in
+ * bounded batches so edits/deletes stay live without re-reading all older pages. */
+export declare function createEndpointHistoryObserver(endpoint: Pick<Endpoint, 'query' | 'observeQuery'>): EndpointHistoryObserver;

package/dist/internal/endpoint/image-generation-errors.d.ts

@@ -0,0 +1,2 @@
+/** Provider and request failures that a retry with the same request cannot fix. */
+export declare function isTerminalImageGenerationError(error: unknown): boolean;

package/dist/internal/endpoint/inbound.d.ts

@@ -0,0 +1,29 @@
+import type { EndpointEvent } from '../backend-contracts/index.js';
+import type { Endpoint } from './engine.js';
+import type { EndpointStore } from './store.js';
+export interface EndpointInboundConsumerOptions {
+    kind: string;
+    conversationId?: string;
+    /** Independent delivery handoffs per room; execution remains runtime-owned. */
+    concurrency?: 'serial' | 'conversation';
+    offer(event: EndpointEvent): Promise<void>;
+    onError?(error: unknown): void;
+    intervalMs?: number;
+}
+export interface EndpointInboundConsumer {
+    receive(event: EndpointEvent): Promise<void>;
+    start(): void;
+    close(): Promise<void>;
+}
+/** The shared inbox owns redelivery. Adapters own the proof that external work completed. */
+export declare function createInboundConsumer(input: {
+    endpoint: Endpoint;
+    store: EndpointStore;
+    owner: string;
+    clock: () => number;
+    leaseMs: number;
+    options: EndpointInboundConsumerOptions;
+    beforeOffer?(event: EndpointEvent): Promise<void>;
+    refreshHandoff?(id: string): Promise<boolean>;
+    retryHandoffDispositions?(): Promise<void>;
+}): EndpointInboundConsumer;

package/dist/internal/endpoint/index.d.ts

@@ -0,0 +1,32 @@
+export * from './engine.js';
+export * from './store.js';
+export * from './transport.js';
+export * from './observe-query.js';
+export type { EndpointInboundConsumer, EndpointInboundConsumerOptions } from './inbound.js';
+export type { EndpointInboundHandoff, EndpointInboundHandoffPhase, EndpointInboundStartResult } from './handoff.js';
+export type { EndpointSyncOptions, EndpointSyncPage } from './sync.js';
+export type { EndpointRecoveryOptions, EndpointRecoveryBaseline } from './recovery.js';
+export type { EndpointEventFamily, EndpointEventObserver, EndpointTransportEvent } from './events.js';
+export * from './media.js';
+export * from './history.js';
+export * from './ephemeral.js';
+export * from './transient-publisher.js';
+export { createArtifactClient, ArtifactRejectedError, type ArtifactClient, type ArtifactClientOptions, type ArtifactCreateOptions, type ArtifactLibrary, type ArtifactWriteResult, } from './artifacts.js';
+export { createArtifactImageClient, type ArtifactImageAddInput, type ArtifactImageClient, type ArtifactImageGenerateInput, type ArtifactImageGenerateResult, type ArtifactImageRegion, } from './artifact-images.js';
+export { isTerminalImageGenerationError } from './image-generation-errors.js';
+export { describeArtifact, summarizeArtifact, type ArtifactChessMoveView, type ArtifactChessView, type ArtifactFormChangeView, type ArtifactFormFieldView, type ArtifactFormView, type ArtifactImageVariantView, type ArtifactImageView, type ArtifactPrincipalView, type ArtifactView, type ArtifactViewOptions, } from './artifact-views.js';
+export { reduceArtifactRecord, replayArtifactPage, artifactCommandConflicts, artifactFormConflicts, type ArtifactConflict } from './artifact-reducer.js';
+export type { ArtifactAsset, ArtifactChessMove, ArtifactChessPlayers, ArtifactChessState, ArtifactCommand, ArtifactCommandBody, ArtifactCommandRecord, ArtifactContext, ArtifactDefinition, ArtifactDomainOutcome, ArtifactFormChange, ArtifactFormColumn, ArtifactFormField, ArtifactFormFieldRemoval, ArtifactFormRow, ArtifactFormState, ArtifactFormTable, ArtifactFormValue, ArtifactImageState, ArtifactImageVariant, ArtifactJson, ArtifactKind, ArtifactOutcomeCode, ArtifactReadResult, ArtifactReference, ArtifactSelection, ArtifactSnapshot, } from '../backend-contracts/index.js';
+export { eraseEndpointPlaintext } from './retention.js';
+export type { EndpointOperationRequest, EndpointOperationReceipt, EndpointOperationError, EndpointPreconditions, EndpointEvent, EndpointQueryRequest, EndpointQueryResponse, } from '../backend-contracts/index.js';
+export { CANON_ENDPOINT_PROTOCOL } from '../backend-contracts/index.js';
+export { endpointContentBoundary, ENDPOINT_CONTENT_ACTIONS, ENDPOINT_CONTENT_QUERIES, ENDPOINT_CONTENT_EPHEMERALS, ENDPOINT_CONTENT_EVENTS } from '../backend-contracts/index.js';
+export type { EndpointContentBoundary, EndpointContentClass, EndpointContentLane } from '../backend-contracts/index.js';
+export type { EndpointRecoveryMigration, EndpointMigrationRoom, EndpointMigrationItem, EndpointMigrationReceipt } from './migration.js';
+export type { EndpointMessageGroupInput, EndpointMessageGroup } from './delivery.js';
+/** Synthetic Dev custody/enrollment coordination; no room activation. */
+export { createMlsDevDeviceCoordinator, type MlsDevDeviceView, type MlsDevProtectedPreparer } from './mls-dev-device.js';
+export type { MlsDevDeviceClient, MlsDevDeviceClientOptions } from './mls-dev-client.js';
+export type { MlsDevDeviceTransport, MlsDevDeviceHttpOptions, MlsDevKeyPackageTransport } from './mls-dev-transport.js';
+export type { MlsDevKeyPackageClient, MlsDevKeyPackageView, MlsDevProtectedKeyPackagePreparer, MlsDevKeyPackagePublicationView, MlsDevKeyPackageClaimView, MlsDevKeyPackageClaimInput } from './mls-dev-key-packages.js';
+export type { MlsDevGroupClient, MlsDevVerifiedMessageBinding, MlsDevCurrentAudience, MlsDevAdmissionHold, MlsDevGroupView, MlsDevGroupRecoveryFailure, MlsDevProtectedGroupPreparer } from './mls-dev-groups.js';

package/dist/internal/endpoint/media.d.ts

@@ -0,0 +1,177 @@
+import { type DeliveryObservation, type DeliveryAttention, type PreparedContent } from '../backend-contracts/index.js';
+import type { Endpoint } from './engine.js';
+import { type EndpointStore } from './store.js';
+export interface EndpointMediaDescriptor {
+    mimeType: string;
+    sizeBytes: number;
+    fileName?: string;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    /** Local-only source cleanup; never sent in a stage manifest. */
+    cleanupAfterSend?: boolean;
+    /** Native-only normalization to apply after durable handoff, before staging. */
+    normalization?: {
+        kind: 'jpeg';
+        maxDimension: 1600;
+        quality: 0.85;
+        fileName: 'photo.jpg';
+    };
+}
+export interface EndpointUploadSession {
+    uploadId: string;
+    uploadUrl: string;
+    sizeBytes: number;
+    mimeType: string;
+    expiresAt?: string;
+}
+export interface EndpointMediaBytes<Source> {
+    /** A bounded-memory digest of the actual bytes, not filename or picker metadata. */
+    digest(source: Source): Promise<string>;
+    discardAll?(): Promise<void>;
+    /** Keep bytes outside caches until the durable message is acknowledged. */
+    retain(key: string, source: Source): Promise<string>;
+    upload(reference: string, session: EndpointUploadSession, options: {
+        signal: AbortSignal;
+        onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+    }): Promise<void>;
+    release(reference: string): Promise<void>;
+    close?(): Promise<void>;
+}
+export interface EndpointMediaFlow {
+    id: string;
+    conversationId: string;
+    messageId: string;
+    message: Record<string, unknown>;
+    fingerprint?: string;
+    createdAt?: string;
+    requiresPublicationApproval?: boolean;
+    files: Array<{
+        descriptor: EndpointMediaDescriptor;
+        reference: string;
+        uploadId?: string;
+        generation?: number;
+        attachment?: Record<string, unknown>;
+        /** How many times a resend asked Canon to process this encrypted room's failed video again. */
+        processingRetries?: number;
+    }>;
+    purpose?: 'prepare';
+    publicationGeneration?: number;
+    /** Frozen at initial staging; an upgrade must never move an uncertain delivery to another publisher. */
+    deliveryMode?: 'legacy' | 'background';
+    observation?: DeliveryObservation;
+    /** Sealed at initial staging; session renewal never changes these bytes. */
+    preparedContent?: PreparedContent;
+    attention?: DeliveryAttention;
+    background?: {
+        phase: EndpointBackgroundMediaSnapshot['status'];
+        uploadedBytes: number;
+        totalBytes: number;
+    };
+    status: 'pending' | 'sending' | 'prepared' | 'succeeded' | 'cancelled' | 'rejected';
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+export interface EndpointMediaProgress {
+    phase: 'preparing' | 'uploading' | 'waiting_for_connection' | 'finalizing' | 'sending' | 'cancelling';
+    uploadedBytes: number;
+    totalBytes: number;
+}
+export interface EndpointMediaSendOptions {
+    signal?: AbortSignal;
+    onProgress?: (progress: EndpointMediaProgress) => void;
+    beforePublish?: () => Promise<boolean>;
+    /** The caller's bounded preflight choice. Existing flows always keep their persisted mode. */
+    handoffMode?: 'background' | 'legacy';
+}
+export interface EndpointMediaInput<Source> {
+    conversationId: string;
+    messageId: string;
+    message: Record<string, unknown>;
+    files: Array<{
+        source: Source;
+        descriptor: EndpointMediaDescriptor;
+    }>;
+}
+export interface EndpointBackgroundMediaSnapshot {
+    identity?: Pick<DeliveryObservation, 'messageId' | 'conversationId' | 'installationId' | 'environmentId'>;
+    schemaVersion?: 2;
+    observation?: DeliveryObservation;
+    attention?: DeliveryAttention;
+    deliveryId: string;
+    status: 'preparing' | 'uploading' | 'waiting_for_connection' | 'sending' | 'cancelling' | 'published' | 'cancelled' | 'expired' | 'rejected';
+    uploadedBytes: number;
+    totalBytes: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/** Native owns remote work once enqueue persists the request. Implementations
+ * must treat enqueue as idempotent for a deliveryId and survive missing JS callbacks. */
+export interface EndpointBackgroundMediaAdapter<Source> {
+    observationVersion?: 2;
+    preparedContentVersion?: 1;
+    available(): Promise<boolean>;
+    sourceIdentity(source: Source): string;
+    enqueue(input: EndpointMediaInput<Source> & {
+        deliveryId: string;
+        installationId: string;
+        preparedContent?: PreparedContent;
+    }): Promise<EndpointBackgroundMediaSnapshot>;
+    inspect(): Promise<EndpointBackgroundMediaSnapshot[]>;
+    /** Query server state only. Must never enqueue/renew/start transfers. */
+    reconcile?(deliveryId: string): Promise<EndpointBackgroundMediaSnapshot>;
+    subscribe(listener: (snapshot: EndpointBackgroundMediaSnapshot) => void): () => void;
+    cancel(deliveryId: string): Promise<void>;
+    cleanup(): Promise<void>;
+    cleanupSource?(source: Source): Promise<void>;
+}
+export interface EndpointMediaPipeline<Source> {
+    /** Prepare durable attachments for a later policy-controlled message publication. */
+    prepare(input: {
+        conversationId: string;
+        attachmentId: string;
+        files: Array<{
+            source: Source;
+            descriptor: EndpointMediaDescriptor;
+        }>;
+    }, options?: Omit<EndpointMediaSendOptions, 'beforePublish'>): Promise<Array<Record<string, unknown>>>;
+    send(input: {
+        conversationId: string;
+        messageId: string;
+        message: Record<string, unknown>;
+        files: Array<{
+            source: Source;
+            descriptor: EndpointMediaDescriptor;
+        }>;
+    }, options?: EndpointMediaSendOptions): Promise<string>;
+    /** With `conversationId`, false for an encrypted room (or one whose mode is unknown): its files are prepared on the
+     * device and sent without the background handoff, so a caller decides before building their descriptors. */
+    canSendInBackground(options?: {
+        maxProbeWaitMs?: number;
+        conversationId?: string;
+    }): Promise<boolean>;
+    resume(id: string, options?: EndpointMediaSendOptions): Promise<string>;
+    resumePending(): Promise<void>;
+    setForeground?(active: boolean): void;
+    list(conversationId: string): Promise<EndpointMediaFlow[]>;
+    subscribe(listener: (flow: EndpointMediaFlow) => void): () => void;
+    cancel(id: string): Promise<void>;
+    /** Release a prepared source after confirmed use or explicit abandonment. */
+    releasePreparedUpload(uploadId: string): Promise<void>;
+    close(options?: {
+        discard?: boolean;
+    }): Promise<void>;
+}
+/** One durable upload→finalize→message dependency graph for every platform. */
+export declare function createEndpointMediaPipeline<Source>(options: {
+    endpoint: Endpoint;
+    store: EndpointStore;
+    bytes: EndpointMediaBytes<Source>;
+    hash?: (value: string) => Promise<string>;
+    ids?: () => string;
+    clock?: () => number;
+    leaseMs?: number;
+    background?: EndpointBackgroundMediaAdapter<Source>;
+}): EndpointMediaPipeline<Source>;

package/dist/internal/endpoint/migration.d.ts

@@ -0,0 +1,50 @@
+import type { EndpointResolvedIdentity } from './engine.js';
+import type { EndpointRecoveryBaseline } from './recovery.js';
+import { type EndpointStore } from './store.js';
+export interface EndpointMigrationItem {
+    id: string;
+    messageId: string;
+    kind: 'message.snapshot' | 'message.deleted';
+    state: 'review' | 'settled' | 'pending' | 'deferred' | 'uncertain';
+    /** Human-reviewed evidence, never a read receipt or last-message marker. */
+    reason?: string;
+    /** Hash of the retained native transcript/journal/export used for reconciliation. */
+    evidenceSha256?: string;
+    providerClaim?: {
+        id: string;
+        status: 'accepted' | 'uncertain' | 'completed';
+    };
+    /** Existing output identifiers stay in their native journal; import never resends them. */
+    legacyOperationIds?: string[];
+}
+export interface EndpointMigrationRoom {
+    conversationId: string;
+    admissionId: string;
+    cursor: string;
+    items: EndpointMigrationItem[];
+}
+export interface EndpointRecoveryMigration {
+    protocol: 'canon.endpoint-migration.v1';
+    identity: EndpointResolvedIdentity;
+    baseline: EndpointRecoveryBaseline;
+    inventorySha256: string;
+    rooms: EndpointMigrationRoom[];
+}
+export interface EndpointMigrationReceipt {
+    reviewedSha256: string;
+    migrationId: string;
+    importedAt: string;
+    rooms: number;
+    items: number;
+}
+/** Operator-only migration. Inventory does not write cursors or acknowledge agent work. */
+export declare function createEndpointMigration(input: {
+    store: EndpointStore;
+    ready(): Promise<EndpointResolvedIdentity>;
+    query<T>(name: string, parameters: Record<string, unknown>): Promise<T>;
+    hash(value: string): Promise<string>;
+    clock(): number;
+}): {
+    plan(baseline: EndpointRecoveryBaseline, conversationIds?: string[]): Promise<EndpointRecoveryMigration>;
+    import(manifest: EndpointRecoveryMigration, reviewedSha256: string): Promise<EndpointMigrationReceipt>;
+};

package/dist/internal/endpoint/mls-crypto.d.ts

@@ -0,0 +1,32 @@
+import { type MlsDevCredentialReceipt, type MlsEnvironmentId } from '../backend-contracts/index.js';
+import type { MlsDevDeviceHttpOptions } from './mls-dev-transport.js';
+export interface MlsDevIssuerKey {
+    readonly keyVersion: string;
+    readonly signaturePublicKey: string;
+}
+export interface MlsDevClientConfiguration {
+    readonly version: 1;
+    /** A declared MLS environment (`MLS_ENVIRONMENT_PROFILES`); every issuer key belongs to it. */
+    readonly environmentId: MlsEnvironmentId;
+    readonly enabled: true;
+    /**
+     * A Dev build's synthetic accounts, the only ones it sets a device up for. A production build lists none: Canon's
+     * eligibility (`/endpoint/capabilities`) decides who uses MLS, so an account made after the build can.
+     */
+    readonly principalIds?: readonly string[];
+    readonly issuerKeys: readonly MlsDevIssuerKey[];
+    /** The feed-receipt keys native checks Canon's signed acceptance times with (mls-signed-acceptance.md). */
+    readonly receiptKeys: readonly MlsDevIssuerKey[];
+}
+/** An environment's reviewed gateway routes on its own API origin, never values learned from a credential response. */
+export declare function mlsDevDeviceHttpConfiguration(environmentId: MlsEnvironmentId): Readonly<MlsDevDeviceHttpOptions>;
+/** Public build configuration. Issuer pins must come from reviewed provisioning;
+ * authenticated service responses are not a trust-root distribution channel. */
+export declare function parseMlsDevClientConfiguration(value: unknown): MlsDevClientConfiguration;
+/** Canonical issuer signature and current validity only. The coordinator binds
+ * the credential to its device/proof; services separately enforce online status.
+ * Kept in an opt-in entry point so ordinary endpoint imports load no crypto. */
+export declare function createMlsDevCredentialVerifier(options: {
+    issuerKeys: readonly MlsDevIssuerKey[];
+    clock?: () => number;
+}): (receipt: MlsDevCredentialReceipt) => Promise<boolean>;

package/dist/internal/endpoint/mls-dev-client.d.ts

@@ -0,0 +1,52 @@
+import { type MlsDevEnrollmentPrincipal, type MlsDevCredentialReceipt } from '../backend-contracts/index.js';
+import type { EndpointResolvedIdentity } from './engine.js';
+import { type MlsDevDeviceView, type MlsDevProtectedPreparer } from './mls-dev-device.js';
+import type { MlsDevDeviceTransport } from './mls-dev-transport.js';
+import { type EndpointStore, type EndpointStoreTransaction } from './store.js';
+import type { MlsDevProtectedGroupPreparer } from './mls-dev-groups.js';
+import type { MlsDevProtectedKeyPackagePreparer } from './mls-dev-key-packages.js';
+export interface MlsDevDeviceClientOptions {
+    principal: MlsDevEnrollmentPrincipal;
+    prepareProtected: MlsDevProtectedPreparer;
+    /** Independently pinned issuer signature, trust and current expiry verification. */
+    verifyCredential(receipt: MlsDevCredentialReceipt): Promise<boolean>;
+    /** Opts in to local device-bound KeyPackage preparation; no publication. */
+    prepareProtectedKeyPackage?: MlsDevProtectedKeyPackagePreparer;
+    prepareProtectedGroup?: MlsDevProtectedGroupPreparer;
+}
+/** Explicit synthetic Dev operations. No timers, eager enrollment or room authority. */
+export interface MlsDevDeviceClient {
+    read(): Promise<MlsDevDeviceView>;
+    /** Ensure local registration; an existing view is not an online status check. */
+    enroll(): Promise<MlsDevDeviceView>;
+    renew(): Promise<MlsDevDeviceView>;
+    /** Requires a committed same-key credential proof, but not an issuer receipt. */
+    reconcile(): Promise<MlsDevDeviceView>;
+    /** Resume deliberate provisioning and keep an enrolled device ready, renewing
+     * once less than half the credential's lifetime remains, so whatever this
+     * device sends stays valid for receivers at least that long. While the
+     * current credential is valid, a failed renewal returns it and is retried
+     * after a minute. Never creates an unrequested enrollment. */
+    ensureReady(): Promise<MlsDevDeviceView>;
+}
+/** Whether readiness would renew this registered device: it has no credential, or less than half its lifetime remains. */
+export declare function isMlsDevCredentialRenewalDue(view: MlsDevDeviceView, now: number): boolean;
+/** Internal factory: the engine owns storage, lifetime, identity and generation. */
+export interface MlsDevDeviceClientContext {
+    store: EndpointStore;
+    ready(): Promise<{
+        identity: EndpointResolvedIdentity;
+        installationGeneration: number;
+    }>;
+    /** The account's MLS principal ID, its alias (mls-dev-groups.md, erasure privacy), as Canon gave and this device checked
+     * it; the account ID itself while it has none. Bindings, credentials and rosters carry it. */
+    mlsPrincipalId(): Promise<string>;
+    signal: AbortSignal;
+    assertOpen(): void;
+    assertCurrent(tx: EndpointStoreTransaction): Promise<void>;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    transport: MlsDevDeviceTransport | undefined;
+    clock: () => number;
+    ids: () => string;
+}
+export declare function createMlsDevDeviceClient(options: MlsDevDeviceClientOptions, context: MlsDevDeviceClientContext): MlsDevDeviceClient;

package/dist/internal/endpoint/mls-dev-device.d.ts

@@ -0,0 +1,69 @@
+import { type MlsDevCredentialChallenge, type MlsDevCredentialCompleteRequest, type MlsDevCredentialReceipt, type MlsDevCredentialRevocationReceipt, type MlsDevCredentialReconciliationChallenge, type MlsDevCredentialReconciliationCompleteRequest, type MlsDevCredentialReconciliationReceipt, type MlsDevDeviceBinding, type MlsDevDeviceCommand, type MlsDevDeviceContext, type MlsDevDevicePreparation, type MlsDevEnrollmentBeginRequest, type MlsDevEnrollmentChallenge, type MlsDevEnrollmentCompleteRequest, type MlsDevEnrollmentResult } from '../backend-contracts/index.js';
+import { type EndpointStore, type EndpointStoreTransaction } from './store.js';
+type ProofCommand = Exclude<MlsDevDeviceCommand, {
+    op: 'create';
+}>;
+type Complete = MlsDevEnrollmentCompleteRequest | MlsDevCredentialCompleteRequest | MlsDevCredentialReconciliationCompleteRequest;
+/** Public observations only. A cached credential is not proof of current online
+ * device/issuer status. Protected state never appears in this view. */
+export interface MlsDevDeviceView {
+    readonly status: 'absent' | 'identity_committed' | 'registered' | 'credential_committed' | 'revoked';
+    readonly binding: MlsDevDeviceBinding;
+    readonly signaturePublicKey?: string;
+    readonly credentialGeneration: number;
+    /** Monotonic local observation used for the next issuance base. Not authority. */
+    readonly observedCredentialGeneration: number;
+    readonly registration?: MlsDevEnrollmentResult;
+    readonly credential?: MlsDevCredentialReceipt;
+    readonly generationObservation?: MlsDevCredentialReconciliationReceipt;
+    readonly revocation?: MlsDevCredentialRevocationReceipt;
+}
+/** This is a security boundary, not a JavaScript key-generation implementation.
+ * The host must authenticate revision-bound protected state and the complete
+ * typed command, enforce its native clock, and return no private material. */
+export type MlsDevProtectedPreparer = (context: MlsDevDeviceContext, command: MlsDevDeviceCommand, wrappedState: string | null) => Promise<MlsDevDevicePreparation>;
+/** Internal same-journal capture for device-bound MLS preparation. It is never
+ * returned through the public device view or treated as publication authority. */
+export interface MlsDevKeyPackagePrerequisite {
+    context: MlsDevDeviceContext;
+    wrappedState: string;
+    credential: MlsDevCredentialReceipt;
+    registration: MlsDevEnrollmentResult;
+    fingerprint: string;
+}
+/** Explicit synthetic Dev coordinator. It owns no transport, timer or retry
+ * loop. The caller supplies an already initialized endpoint store and sends
+ * only the committed public requests returned by these methods. */
+export declare function createMlsDevDeviceCoordinator(input: {
+    store: EndpointStore;
+    binding: MlsDevDeviceBinding;
+    /** The endpoint identity's account, when the binding's principal is its alias. */
+    accountId?: string;
+    installationGeneration: number;
+    prepareProtected: MlsDevProtectedPreparer;
+    /** Required independent issuer signature/trust validation, outside storage.
+     * A structural JWS parser or a caller-selected public key is insufficient. */
+    verifyCredential(receipt: MlsDevCredentialReceipt): Promise<boolean>;
+    /** Authenticates the server response independently. Structural parsing and
+     * the device's own proof cannot authenticate an observation. Missing denies. */
+    verifyGenerationObservation?(receipt: MlsDevCredentialReconciliationReceipt): Promise<boolean>;
+}): {
+    read: () => Promise<MlsDevDeviceView>;
+    captureKeyPackagePrerequisite(tx: EndpointStoreTransaction): Promise<MlsDevKeyPackagePrerequisite>;
+    /** A credential proof pins registration in native custody. Its journal row
+     * commits with that protected state, even if no issuer receipt was received.
+     * Historical proofs remain evidence of the pin after expiry/renewal. */
+    hasCommittedCredentialProof(): Promise<boolean>;
+    /** Look up an exact committed proof without asking custody to sign again.
+     * The driver uses this before refreshing an expired, unprepared challenge. */
+    readCommittedProof(value: ProofCommand): Promise<Complete | undefined>;
+    ensureIdentity(): Promise<MlsDevEnrollmentBeginRequest>;
+    prepareEnrollmentProof(challenge: MlsDevEnrollmentChallenge): Promise<MlsDevEnrollmentCompleteRequest>;
+    prepareCredentialProof(challenge: MlsDevCredentialChallenge, expectedCredentialGeneration: number): Promise<MlsDevCredentialCompleteRequest>;
+    prepareCredentialReconciliationProof(challenge: MlsDevCredentialReconciliationChallenge, expectedCredentialGeneration: number): Promise<MlsDevCredentialReconciliationCompleteRequest>;
+    acceptRegistration(challengeId: string, value: MlsDevEnrollmentResult): Promise<MlsDevDeviceView>;
+    acceptCredential(challengeId: string, value: MlsDevCredentialReceipt): Promise<MlsDevDeviceView>;
+    acceptGenerationObservation(challengeId: string, value: MlsDevCredentialReconciliationReceipt): Promise<MlsDevDeviceView>;
+    acceptRevocation(value: MlsDevCredentialRevocationReceipt): Promise<MlsDevDeviceView>;
+};
+export {};