@takboo/dsh-session-bin 0.0.0-stage → 0.1.1

package/dist/host/module.d.ts

@@ -0,0 +1,705 @@
+import type { BinEntry, BinOperation, BinPlan, BinResult, PrepareRequest } from '../operations/schema.js';
+import type { BinStore } from './store.js';
+import type { RetirementOptions } from './retirement.js';
+import type { PreparePurgeRequest, PurgePlan } from '../operations/retirement.js';
+export declare class SessionBinError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/** Internal marker: external failures using the same public Error class remain unknown. */
+export declare function sessionBinRefusal(code: string, message: string): SessionBinError;
+export declare function isSessionBinRefusal(error: unknown): boolean;
+export interface NativeSessionState {
+    archived: boolean;
+    known: boolean;
+    workspaceId: string | null;
+}
+export interface NativeBinPort {
+    inspect(sessionId: string): Promise<NativeSessionState>;
+    activity(sessionId: string): Promise<string[]>;
+    archive(sessionId: string): Promise<void>;
+    unarchive(sessionId: string): Promise<void>;
+}
+export interface ReconcileReport {
+    completed: BinResult[];
+    retryRequired: string[];
+    releasedEntries: string[];
+}
+/** One Host owns this Module; its caller holds the lifetime lease before open. */
+export declare class SessionBinModule {
+    private readonly store;
+    private readonly native;
+    private readonly options;
+    private tail;
+    private closing;
+    private failed;
+    private failure;
+    private closePromise;
+    private readonly invalidated;
+    private readonly observedArchived;
+    private readonly purge;
+    constructor(store: BinStore, native: NativeBinPort, options?: {
+        retirement?: RetirementOptions;
+        legacyReadOnly?: boolean;
+    });
+    preparePurge(request: PreparePurgeRequest): Promise<{
+        schemaVersion: 1 | 2;
+        action: "purge";
+        operationId: string;
+        sessionId: string;
+        expectedEntryId: string | null;
+        binding: {
+            schemaVersion: 1;
+            entryId: string;
+            entryVersion: 1;
+            lifecycle: {
+                storeId: string;
+                sessionId: string;
+                lifecycleId: string;
+            };
+            capabilities: {
+                protocolVersion: 1;
+                ownerId: string;
+                hostVersion: string;
+                providerId: string;
+                storeId: string;
+                participants: {
+                    id: string;
+                    version: string;
+                }[];
+            };
+        } | {
+            schemaVersion: 2;
+            target: "native-archive";
+            entryId: string;
+            entryVersion: 2;
+            lifecycle: {
+                storeId: string;
+                sessionId: string;
+                lifecycleId: string;
+            };
+            capabilities: {
+                protocolVersion: 1;
+                ownerId: string;
+                hostVersion: string;
+                providerId: string;
+                storeId: string;
+                participants: {
+                    id: string;
+                    version: string;
+                }[];
+            };
+        } | null;
+        manifest: {
+            schemaVersion: 1;
+            lifecycle: {
+                storeId: string;
+                sessionId: string;
+                lifecycleId: string;
+            };
+            capabilities: {
+                protocolVersion: 1;
+                ownerId: string;
+                hostVersion: string;
+                providerId: string;
+                storeId: string;
+                participants: {
+                    id: string;
+                    version: string;
+                }[];
+            };
+            resources: {
+                ownerId: string;
+                resourceId: string;
+                revision: string;
+                kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                retention: {
+                    reason: "shared-reference" | "coordination-identity";
+                    retainedBy: {
+                        storeId: string;
+                        sessionId: string;
+                        lifecycleId: string;
+                    }[];
+                } | null;
+            }[];
+        } | null;
+        blockers: {
+            code: string;
+            activity?: string[] | undefined;
+        }[];
+    }>;
+    executePurge(input: PurgePlan): Promise<{
+        action: "purge";
+        operationId: string;
+        sessionId: string;
+        entryId: string | null;
+        status: "success" | "rejected" | "conflict" | "pending-recovery" | "partial-failure";
+        reason: string | null;
+        ownerState: {
+            schemaVersion: 1;
+            request: {
+                operationId: string;
+                expected: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                bin: {
+                    entryId: string;
+                    entryVersion: 1;
+                } | {
+                    kind: "native-archive";
+                    entryId: string;
+                    entryVersion: 2;
+                };
+                manifestDigest: string;
+            };
+            manifest: {
+                schemaVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    revision: string;
+                    kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                    disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                    retention: {
+                        reason: "shared-reference" | "coordination-identity";
+                        retainedBy: {
+                            storeId: string;
+                            sessionId: string;
+                            lifecycleId: string;
+                        }[];
+                    } | null;
+                }[];
+            };
+            authorizationId: string | null;
+            phase: "rejected" | "conflict" | "done" | "fenced" | "quiesced" | "erasing" | "converging";
+            reason: string | null;
+            resources: {
+                ownerId: string;
+                resourceId: string;
+                status: "erased" | "reference-released" | "retained" | "failed";
+                reason: string | null;
+            }[];
+        } | null;
+    }>;
+    getPurgeOperation(operationId: string): Promise<{
+        schemaVersion: 1 | 2;
+        plan: {
+            schemaVersion: 1 | 2;
+            action: "purge";
+            operationId: string;
+            sessionId: string;
+            expectedEntryId: string | null;
+            binding: {
+                schemaVersion: 1;
+                entryId: string;
+                entryVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+            } | {
+                schemaVersion: 2;
+                target: "native-archive";
+                entryId: string;
+                entryVersion: 2;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+            } | null;
+            manifest: {
+                schemaVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    revision: string;
+                    kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                    disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                    retention: {
+                        reason: "shared-reference" | "coordination-identity";
+                        retainedBy: {
+                            storeId: string;
+                            sessionId: string;
+                            lifecycleId: string;
+                        }[];
+                    } | null;
+                }[];
+            } | null;
+            blockers: {
+                code: string;
+                activity?: string[] | undefined;
+            }[];
+        };
+        createdAt: string;
+        phase: "intent" | "done" | "authorizing" | "owner-pending";
+        entry: {
+            schemaVersion: 1;
+            sessionId: string;
+            entryId: string;
+            operationId: string;
+            binnedAt: string;
+            workspaceIdAtBin: string | null;
+            wasArchived: boolean;
+        } | {
+            schemaVersion: 2;
+            sessionId: string;
+            entryId: string;
+        } | null;
+        authorizationId: string | null;
+        ownerState: {
+            schemaVersion: 1;
+            request: {
+                operationId: string;
+                expected: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                bin: {
+                    entryId: string;
+                    entryVersion: 1;
+                } | {
+                    kind: "native-archive";
+                    entryId: string;
+                    entryVersion: 2;
+                };
+                manifestDigest: string;
+            };
+            manifest: {
+                schemaVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    revision: string;
+                    kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                    disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                    retention: {
+                        reason: "shared-reference" | "coordination-identity";
+                        retainedBy: {
+                            storeId: string;
+                            sessionId: string;
+                            lifecycleId: string;
+                        }[];
+                    } | null;
+                }[];
+            };
+            authorizationId: string | null;
+            phase: "rejected" | "conflict" | "done" | "fenced" | "quiesced" | "erasing" | "converging";
+            reason: string | null;
+            resources: {
+                ownerId: string;
+                resourceId: string;
+                status: "erased" | "reference-released" | "retained" | "failed";
+                reason: string | null;
+            }[];
+        } | null;
+        result: {
+            action: "purge";
+            operationId: string;
+            sessionId: string;
+            entryId: string | null;
+            status: "success" | "rejected" | "conflict" | "pending-recovery" | "partial-failure";
+            reason: string | null;
+            ownerState: {
+                schemaVersion: 1;
+                request: {
+                    operationId: string;
+                    expected: {
+                        storeId: string;
+                        sessionId: string;
+                        lifecycleId: string;
+                    };
+                    bin: {
+                        entryId: string;
+                        entryVersion: 1;
+                    } | {
+                        kind: "native-archive";
+                        entryId: string;
+                        entryVersion: 2;
+                    };
+                    manifestDigest: string;
+                };
+                manifest: {
+                    schemaVersion: 1;
+                    lifecycle: {
+                        storeId: string;
+                        sessionId: string;
+                        lifecycleId: string;
+                    };
+                    capabilities: {
+                        protocolVersion: 1;
+                        ownerId: string;
+                        hostVersion: string;
+                        providerId: string;
+                        storeId: string;
+                        participants: {
+                            id: string;
+                            version: string;
+                        }[];
+                    };
+                    resources: {
+                        ownerId: string;
+                        resourceId: string;
+                        revision: string;
+                        kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                        disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                        retention: {
+                            reason: "shared-reference" | "coordination-identity";
+                            retainedBy: {
+                                storeId: string;
+                                sessionId: string;
+                                lifecycleId: string;
+                            }[];
+                        } | null;
+                    }[];
+                };
+                authorizationId: string | null;
+                phase: "rejected" | "conflict" | "done" | "fenced" | "quiesced" | "erasing" | "converging";
+                reason: string | null;
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    status: "erased" | "reference-released" | "retained" | "failed";
+                    reason: string | null;
+                }[];
+            } | null;
+        } | null;
+    } | undefined>;
+    purgeOperations(): Promise<{
+        schemaVersion: 1 | 2;
+        plan: {
+            schemaVersion: 1 | 2;
+            action: "purge";
+            operationId: string;
+            sessionId: string;
+            expectedEntryId: string | null;
+            binding: {
+                schemaVersion: 1;
+                entryId: string;
+                entryVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+            } | {
+                schemaVersion: 2;
+                target: "native-archive";
+                entryId: string;
+                entryVersion: 2;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+            } | null;
+            manifest: {
+                schemaVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    revision: string;
+                    kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                    disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                    retention: {
+                        reason: "shared-reference" | "coordination-identity";
+                        retainedBy: {
+                            storeId: string;
+                            sessionId: string;
+                            lifecycleId: string;
+                        }[];
+                    } | null;
+                }[];
+            } | null;
+            blockers: {
+                code: string;
+                activity?: string[] | undefined;
+            }[];
+        };
+        createdAt: string;
+        phase: "intent" | "done" | "authorizing" | "owner-pending";
+        entry: {
+            schemaVersion: 1;
+            sessionId: string;
+            entryId: string;
+            operationId: string;
+            binnedAt: string;
+            workspaceIdAtBin: string | null;
+            wasArchived: boolean;
+        } | {
+            schemaVersion: 2;
+            sessionId: string;
+            entryId: string;
+        } | null;
+        authorizationId: string | null;
+        ownerState: {
+            schemaVersion: 1;
+            request: {
+                operationId: string;
+                expected: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                bin: {
+                    entryId: string;
+                    entryVersion: 1;
+                } | {
+                    kind: "native-archive";
+                    entryId: string;
+                    entryVersion: 2;
+                };
+                manifestDigest: string;
+            };
+            manifest: {
+                schemaVersion: 1;
+                lifecycle: {
+                    storeId: string;
+                    sessionId: string;
+                    lifecycleId: string;
+                };
+                capabilities: {
+                    protocolVersion: 1;
+                    ownerId: string;
+                    hostVersion: string;
+                    providerId: string;
+                    storeId: string;
+                    participants: {
+                        id: string;
+                        version: string;
+                    }[];
+                };
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    revision: string;
+                    kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                    disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                    retention: {
+                        reason: "shared-reference" | "coordination-identity";
+                        retainedBy: {
+                            storeId: string;
+                            sessionId: string;
+                            lifecycleId: string;
+                        }[];
+                    } | null;
+                }[];
+            };
+            authorizationId: string | null;
+            phase: "rejected" | "conflict" | "done" | "fenced" | "quiesced" | "erasing" | "converging";
+            reason: string | null;
+            resources: {
+                ownerId: string;
+                resourceId: string;
+                status: "erased" | "reference-released" | "retained" | "failed";
+                reason: string | null;
+            }[];
+        } | null;
+        result: {
+            action: "purge";
+            operationId: string;
+            sessionId: string;
+            entryId: string | null;
+            status: "success" | "rejected" | "conflict" | "pending-recovery" | "partial-failure";
+            reason: string | null;
+            ownerState: {
+                schemaVersion: 1;
+                request: {
+                    operationId: string;
+                    expected: {
+                        storeId: string;
+                        sessionId: string;
+                        lifecycleId: string;
+                    };
+                    bin: {
+                        entryId: string;
+                        entryVersion: 1;
+                    } | {
+                        kind: "native-archive";
+                        entryId: string;
+                        entryVersion: 2;
+                    };
+                    manifestDigest: string;
+                };
+                manifest: {
+                    schemaVersion: 1;
+                    lifecycle: {
+                        storeId: string;
+                        sessionId: string;
+                        lifecycleId: string;
+                    };
+                    capabilities: {
+                        protocolVersion: 1;
+                        ownerId: string;
+                        hostVersion: string;
+                        providerId: string;
+                        storeId: string;
+                        participants: {
+                            id: string;
+                            version: string;
+                        }[];
+                    };
+                    resources: {
+                        ownerId: string;
+                        resourceId: string;
+                        revision: string;
+                        kind: "transcript" | "workspace" | "index" | "cache" | "attachment" | "spill" | "coordination";
+                        disposition: "erase" | "release-reference" | "retain-shared" | "retain-coordination";
+                        retention: {
+                            reason: "shared-reference" | "coordination-identity";
+                            retainedBy: {
+                                storeId: string;
+                                sessionId: string;
+                                lifecycleId: string;
+                            }[];
+                        } | null;
+                    }[];
+                };
+                authorizationId: string | null;
+                phase: "rejected" | "conflict" | "done" | "fenced" | "quiesced" | "erasing" | "converging";
+                reason: string | null;
+                resources: {
+                    ownerId: string;
+                    resourceId: string;
+                    status: "erased" | "reference-released" | "retained" | "failed";
+                    reason: string | null;
+                }[];
+            } | null;
+        } | null;
+    }[]>;
+    reconcilePurge(): Promise<import("./retirement.js").PurgeReconcileReport>;
+    private requirePurge;
+    prepare(request: PrepareRequest): Promise<BinPlan>;
+    execute(input: BinPlan): Promise<BinResult>;
+    list(): Promise<BinEntry[]>;
+    operations(): Promise<BinOperation[]>;
+    getOperation(operationId: string): Promise<BinOperation | undefined>;
+    reconcile(): Promise<ReconcileReport>;
+    /** Capture each native archive frame NOW, before queued reconciliation yields.
+     * An observed unarchive/rearchive must not restore an old entry's ownership.
+     * No archive-generation token exists in the SDK for an unobserved restart ABA.
+     */
+    observeArchives(archivedSessionIds: readonly string[]): Promise<ReconcileReport>;
+    close(): Promise<void>;
+    private emptyOperation;
+    private sameRequest;
+    private blockers;
+    private finish;
+    private finalize;
+    private reconcileInner;
+    private unavailable;
+    private enqueue;
+}