@artenx/dshb 0.1.31 → 0.1.33

package/lib/{session-sync-Zfo1Q-qT.d.ts → session-sync-BuOJvFxK.d.ts}

@@ -1056,6 +1056,7 @@ type SyncSessionObject = {
   bytes: number;
   digest: string;
   data: string;
+  deferred?: boolean;
 } | {
   id: string;
   kind: 'file';
@@ -1063,6 +1064,7 @@ type SyncSessionObject = {
   bytes: number;
   digest: string;
   data: string;
+  deferred?: boolean;
 } | {
   id: string;
   kind: 'spill';
@@ -1071,6 +1073,7 @@ type SyncSessionObject = {
   digest: string;
   data: string;
   unavailable?: boolean;
+  deferred?: boolean;
 };
 interface SyncSessionEntry {
   metadata: SyncRecordMetadata;
@@ -1138,6 +1141,35 @@ interface SyncSessionApplyOptions {
 interface ExportObjectCacheEntry {
   object: SyncSessionObject;
 }
+/**
+ * 带外对象收件箱：对端推送/拉取的大对象（附件/spill）先落盘到
+ * `<home>/dshb/sync-objects/<sha256hex>`，apply 阶段按 digest 流式水合进
+ * 本地存储并删除。落盘全程流式（内存 O(单帧)），对象总体积不受堆约束。
+ * apply 失败时收件箱保留（journal 回放仍可水合），孤儿文件由 TTL 清扫回收。
+ */
+interface SyncObjectInboxWriter {
+  write(chunk: Uint8Array): Promise<void>;
+  commit(): Promise<void>;
+  abort(): Promise<void>;
+}
+declare class SyncSessionObjectInbox {
+  private readonly root;
+  constructor(home?: string);
+  get path(): string;
+  private fileFor;
+  /**
+   * 打开一个收件箱写入器：逐帧流式写盘 + 增量摘要校验，内存 O(帧)。
+   * commit() 校验字节数与 digest 后原子重命名；abort() 清理临时文件。
+   */
+  writerFor(digest: string, expectedBytes: number): Promise<SyncObjectInboxWriter>;
+  /** 便捷写入：把对象流整段写进收件箱（测试与小对象用）。 */
+  write(digest: string, bytes: number, stream: AsyncIterable<Uint8Array>): Promise<void>;
+  /** 打开收件箱文件的只读流（apply 水合用）；调用方负责消费完毕。 */
+  read(digest: string): Promise<AsyncIterable<Uint8Array>>;
+  delete(digest: string): Promise<void>;
+  /** TTL 清扫：删除超过 maxAgeMs 未修改的孤儿文件。 */
+  sweep(maxAgeMs?: number): Promise<number>;
+}
 declare class ExportObjectCache {
   private readonly entries;
   private bytes;
@@ -1240,6 +1272,7 @@ interface SpillStoreLike {
 declare function sessionEventListDigest(events: readonly SessionEvent[]): string;
 declare function estimateJsonBytes(value: unknown, limit: number): number | undefined;
 declare function planSessionTransfers(direction: 'pull' | 'bidirectional', localEntries: readonly SyncSessionEntry[], remoteEntries: readonly SyncSessionEntry[]): SyncSessionTransferPlan;
+declare function validateObjectPayload(object: unknown): SyncSessionObject;
 declare function validateSyncSessionBundle(value: unknown): SyncSessionBundle;
 declare function makeSyncSessionBundle(instanceId: string, entries: SyncSessionEntry[], skipped?: Array<{
   sessionId: string;
@@ -1268,11 +1301,14 @@ declare class SyncSessionService {
   private readonly exportCacheStore;
   private readonly manifestPayloadCache;
   private manifestPayloadCacheBytes;
+  /** 带外对象收件箱：对象流 RPC 的落盘暂存区，apply 水合后删除。 */
+  readonly objectInbox: SyncSessionObjectInbox;
   constructor(state: SyncStateStore, nodes: SyncNodeService, registry: NodeRegistry, bindings: WorkspaceBindingsStore, getWorkspaces: () => WorkspaceRegistryLike | undefined, getPersistence: () => SessionPersistenceLike | undefined, getAttachments: () => AttachmentStoreLike | undefined, getSpills: () => SpillStoreLike | undefined, instructions: SessionInstructionSnapshotStore, journal?: SyncSessionJournalStore, now?: () => number, home?: string);
   exportBundle(): Promise<SyncSessionBundle>;
   exportManifest(): Promise<SyncSessionManifest>;
   exportEntries(keys: readonly string[], manifestDigest?: string, prefixes?: readonly SyncSessionEventPrefix[], options?: {
     sharedObjects?: boolean;
+    deferredObjects?: boolean;
   }): Promise<SyncSessionBundle>;
   private rememberManifestPayloads;
   applyBundle(value: unknown, sourceName: string, peerId?: string, options?: SyncSessionApplyOptions): Promise<SyncSessionApplyResult>;
@@ -1307,8 +1343,24 @@ declare class SyncSessionService {
   private readStableSession;
   private exportObjects;
   private requirePersistence;
+  /**
+   * 把 deferred 对象编码为带外帧流：每对象一行 JSON 头 + 原始字节。
+   * 内容从本地存储流式读取（spill/文件流式；图片体积有限走缓冲），
+   * 逐块校验字节数与摘要，内存 O(单块)。
+   */
+  streamObjects(objects: readonly SyncSessionObject[]): AsyncGenerator<Uint8Array>;
+  private openObjectContent;
+  /** 单帧写入上限：超过即认为流失控。 */
+  private static readonly OBJECT_STREAM_HEADER_MAX_BYTES;
+  /**
+   * 解析并落盘对端推送的对象帧流：逐帧写收件箱，边写边校验摘要，
+   * 内存 O(单帧)。返回接收的对象数。
+   */
+  ingestObjectStream(source: AsyncIterable<Uint8Array>): Promise<number>;
+  /** apply 成功后删除已水合对象的收件箱文件；失败保留供 journal 回放。 */
+  deleteInboxedObjects(digests: Iterable<string>): Promise<void>;
   private serializeMutation;
 }
 //#endregion
-export { validateSyncSessionBundle as C, syncSessionEntryKey as S, estimateJsonBytes as _, SyncSessionEntry as a, planSessionTransfers as b, SyncSessionEventPrefix as c, SyncSessionManifestEntry as d, SyncSessionObject as f, WorkspaceRegistryLike as g, SyncSessionWorkspace as h, SyncSessionBundle as i, SyncSessionInstructionSnapshot as l, SyncSessionTransferPlan as m, SyncSessionApplyOptions as n, SyncSessionError as o, SyncSessionService as p, SyncSessionApplyResult as r, SyncSessionEventDelta as s, ExportObjectCache as t, SyncSessionManifest as u, makeSyncSessionBundle as v, validateSyncSessionManifest as w, sessionEventListDigest as x, makeSyncSessionManifest as y };
-//# sourceMappingURL=session-sync-Zfo1Q-qT.d.ts.map
+export { sessionEventListDigest as C, validateSyncSessionManifest as D, validateSyncSessionBundle as E, planSessionTransfers as S, validateObjectPayload as T, SyncSessionWorkspace as _, SyncSessionBundle as a, makeSyncSessionBundle as b, SyncSessionEventDelta as c, SyncSessionManifest as d, SyncSessionManifestEntry as f, SyncSessionTransferPlan as g, SyncSessionService as h, SyncSessionApplyResult as i, SyncSessionEventPrefix as l, SyncSessionObjectInbox as m, SyncObjectInboxWriter as n, SyncSessionEntry as o, SyncSessionObject as p, SyncSessionApplyOptions as r, SyncSessionError as s, ExportObjectCache as t, SyncSessionInstructionSnapshot as u, WorkspaceRegistryLike as v, syncSessionEntryKey as w, makeSyncSessionManifest as x, estimateJsonBytes as y };
+//# sourceMappingURL=session-sync-BuOJvFxK.d.ts.map