@hasna-internal/kai-session-persistence 0.1.1-rc.2

package/lib/types/preparations.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Bounded sharing and exclusive reservation of unpublished Sessions.
+ * @module @hasna-internal/kai-session-persistence/preparations
+ */
+import type { Session, SessionId } from '@hasna-internal/kai-session';
+interface PreparedSource {
+    readonly session: Session;
+}
+type PreparationPhase = 'loading' | 'ready' | 'committing' | 'reserved';
+interface PreparationEntry<Source, CommitState> {
+    readonly id: SessionId;
+    readonly result: Promise<Source>;
+    phase: PreparationPhase;
+    source?: Source;
+    reservation?: SessionPreparationReservation<Source, CommitState>;
+    reservationSettled?: Promise<void>;
+    settleReservation?: () => void;
+}
+/** One exclusively held prepared source and its committed persistence state. */
+export interface SessionPreparationReservation<Source, CommitState> {
+    readonly entry: PreparationEntry<Source, CommitState>;
+    readonly source: Source;
+    readonly state: CommitState;
+}
+/** Per-coordinator cold-read sharing, exclusive reservation, and ready-entry LRU. */
+export declare class SessionPreparations<Source extends PreparedSource, CommitState> {
+    private readonly capacity;
+    private readonly entries;
+    constructor(capacity: number);
+    /**
+     * Whether this pool currently knows about an unpublished identity.
+     * @param id - session identity.
+     * @returns whether an entry exists for the identity.
+     */
+    has(id: SessionId): boolean;
+    /**
+     * Observe one prepared source, sharing an in-flight read for the same id.
+     * @param id - session identity.
+     * @param load - cold loader used when no entry exists.
+     * @param signal - optional cancellation signal while waiting.
+     * @returns the shared prepared source.
+     */
+    inspect(id: SessionId, load: () => Promise<Source>, signal?: AbortSignal): Promise<Source>;
+    /**
+     * Reserve one ready source after committing its pending durable repair.
+     * @param id - session identity.
+     * @param load - cold loader used when no entry exists.
+     * @param commit - durable repair and cursor-state commit.
+     * @param signal - optional cancellation signal while waiting.
+     * @returns the exclusive reservation, or undefined if its entry was invalidated.
+     */
+    reserve(id: SessionId, load: () => Promise<Source>, commit: (source: Source) => Promise<{
+        source: Source;
+        state: CommitState;
+    } | undefined>, signal?: AbortSignal): Promise<SessionPreparationReservation<Source, CommitState> | undefined>;
+    /**
+     * Return the exact reservation for Session publication, rejecting aliases.
+     * @param session - exact Session candidate for publication.
+     * @returns its reservation, or undefined when no preparation exists.
+     */
+    reservationFor(session: Session): SessionPreparationReservation<Source, CommitState> | undefined;
+    /**
+     * Consume a reservation after its exact Session has attached.
+     * @param reservation - reservation to consume.
+     */
+    attach(reservation: SessionPreparationReservation<Source, CommitState>): void;
+    /**
+     * Consume a reservation whose caller only needs the committed inspection.
+     * @param reservation - reservation to consume.
+     */
+    discard(reservation: SessionPreparationReservation<Source, CommitState>): void;
+    /**
+     * Return a reusable unpublished reservation to the ready LRU.
+     * @param reservation - reservation to release.
+     * @param reusable - whether the source remains valid for reuse.
+     */
+    release(reservation: SessionPreparationReservation<Source, CommitState>, reusable: boolean): void;
+    /**
+     * Discard a prepared view after the durable log changes.
+     * @param id - changed session identity.
+     */
+    invalidate(id: SessionId): void;
+    /**
+     * Discard an exact stale ready source without disturbing an exclusive owner.
+     * @param id - changed session identity.
+     * @param expected - exact source observed before its revision check.
+     * @returns whether the source was discarded, retained by a reservation, or is absent.
+     */
+    discardReady(id: SessionId, expected: Source): 'discarded' | 'retained' | 'missing';
+    /**
+     * Reject writes while an unpublished Session exclusively reserves the id.
+     * @param id - session identity to check.
+     */
+    assertWritable(id: SessionId): void;
+    /**
+     * Remove a completed entry for an already-serialized append adoption.
+     * @param id - adopted session identity.
+     * @returns the prepared source, or undefined when no ready entry exists.
+     */
+    takeReady(id: SessionId): Source | undefined;
+    private entryFor;
+    private makeReady;
+    private remove;
+    private touch;
+}
+/**
+ * Give a queued observer a prompt cancellation view without cancelling shared work.
+ * @param operation - shared operation whose settlement remains authoritative.
+ * @param signal - observer-local cancellation signal.
+ * @param started - whether the operation has crossed its cancellation cutoff.
+ * @returns the operation result or the observer's prompt cancellation.
+ */
+export declare function observeQueuedAbort<T>(operation: Promise<T>, signal: AbortSignal, started?: () => boolean): Promise<T>;
+export {};
+//# sourceMappingURL=preparations.d.ts.map

package/lib/types/revision.d.ts

@@ -0,0 +1,14 @@
+/** Opaque revision identity for lightweight persistence observations. */
+import type { Branded } from '@hasna-internal/kai-brand';
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+export type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>;
+/**
+ * Brand a backend revision for the provider-neutral persistence contract.
+ * @param value - backend-owned opaque revision representation.
+ * @returns the same runtime string with persistence-revision identity.
+ */
+export declare function SessionPersistenceRevision(value: string): SessionPersistenceRevision;
+//# sourceMappingURL=revision.d.ts.map

package/lib/types/write-behind.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded per-session write batching for the shared persistence coordinator.
+ * @module @hasna-internal/kai-session-persistence/write-behind
+ */
+import type { SessionEvent } from '@hasna-internal/kai-session';
+/** Dependencies and scheduling policy for one live session's write controller. */
+export interface SessionWriteBehindOptions {
+    /** Maximum intentional batching wait after an idle queue receives work. */
+    readonly maxDelayMs: number;
+    /** Persist one stable ordered prefix; resolves only after backend durability. */
+    readonly write: (events: readonly SessionEvent[]) => Promise<void>;
+    /** Observe a detached background write failure without rejecting the producer. */
+    readonly reportBackgroundFailure: (error: unknown) => void;
+}
+/**
+ * Owns one live session's pending events, fixed batching deadline, active write,
+ * failure retention, and explicit quiescence barrier.
+ */
+export declare class SessionWriteBehind {
+    private readonly options;
+    private pending;
+    private timer;
+    private active;
+    private barrier;
+    private deadlineExpired;
+    private automaticPaused;
+    /**
+     * @param options - fixed scheduling policy and durable batch sink.
+     */
+    constructor(options: SessionWriteBehindOptions);
+    /** Whether this controller owns queued events or an active durable write. */
+    get hasWork(): boolean;
+    /**
+     * Copy one event into the persistence-owned queue and start a fixed deadline
+     * when the automatic path is idle.
+     * @param event - frozen live event to retain independently of its producer.
+     */
+    enqueue(event: SessionEvent): void;
+    /**
+     * Cancel the batching wait and durably drain through a quiescent point.
+     * Concurrent callers join the same barrier.
+     * @returns a promise that rejects if the barrier's durable retry fails.
+     */
+    flush(): Promise<void>;
+    /** Cancel the current automatic deadline without draining retained work. */
+    cancelAutomaticWait(): void;
+    /** Start the one fixed window for the current pending prefix. */
+    private armTimer;
+    /** Cancel any pending automatic deadline. */
+    private cancelTimer;
+    /** Start a background write now, or remember that an active write used the budget. */
+    private onDeadline;
+    /** Start one detached write whose failure is reported and retained. */
+    private startBackground;
+    /** Continue immediately after an over-budget active write, otherwise keep its timer. */
+    private continueAutomatic;
+    /** Await overlapping work, drain to quiescence, and settle the shared barrier. */
+    private drainBarrier;
+    /** Start one stable pending prefix, retaining it in order if durability fails. */
+    private startWrite;
+}
+//# sourceMappingURL=write-behind.d.ts.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hasna-internal/kai-session-persistence",
+  "description": "Abstract durable session persistence seam (ctx.sessionPersistence) for the DeepSeek Harness",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-persistence"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@hasna-internal/kai-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-scope": "^0.1.1-rc.2",
+    "@hasna-internal/kai-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}