@sema-ai/core 1.275.1

package/dist/core/session-store.js

@@ -0,0 +1,298 @@
+import { InMemorySessionRepo, uuidv7, } from "../internal/harness.js";
+import { isSessionConflict } from "./session.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * TTL-cached {@link SessionStore} over a pluggable {@link SessionRepo}.
+ *
+ * Sessions are cached in process memory and evicted after `defaultTtlDays` of inactivity. With the
+ * default in-memory repo they live only in this process (lost on restart). Supply a **durable** repo
+ * and the same caching/concurrency logic becomes a "session center": on `acquire`, a session not in
+ * the live cache is **resumed from the repo** (`repo.open`) rather than recreated — so a stateless
+ * runner resumes a conversation after a restart or across replicas. The optimistic-lock seam
+ * (`SessionWriteOptions.expectedLeafId` → `SessionError("conflict")`) keeps two replicas writing the
+ * same session safe; the Runner reconciles a lost CAS and retries.
+ *
+ * See `design/10-会话持久化与会话中心.md` for the durable-backend (TiDB) contract.
+ */
+export class TtlSessionStore {
+    repo;
+    entries = new Map();
+    /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) share one session. */
+    pending = new Map();
+    /** Sessions pinned by a design/45 checkpoint — skipped by idle sweep until unpinned (B6/§5). */
+    pinned = new Set();
+    defaultTtlMs;
+    evictPolicy;
+    sweepTimer;
+    constructor(opts = {}) {
+        this.repo = opts.repo ?? new InMemorySessionRepo();
+        this.defaultTtlMs = (opts.defaultTtlDays ?? 7) * DAY_MS;
+        this.evictPolicy = opts.evict ?? (opts.repo ? "forget" : "delete");
+        if (opts.sweepIntervalMs !== undefined && opts.sweepIntervalMs > 0) {
+            this.sweepTimer = setInterval(() => this.sweep(), opts.sweepIntervalMs);
+            // Do not keep the process alive just for sweeping.
+            this.sweepTimer.unref?.();
+        }
+    }
+    /** Get an existing session by id (resuming from the repo if needed), or create one. */
+    async acquire(sessionId, opts) {
+        this.sweep();
+        if (sessionId) {
+            const existing = this.entries.get(sessionId);
+            if (existing) {
+                existing.lastActiveAt = Date.now();
+                return { session: existing.session, sessionId };
+            }
+            // design/114 Phase3 (F1): a `requireExisting` acquire NEVER creates and can REJECT (not_found). It must
+            // bypass the shared create-dedup `pending` — otherwise a concurrent create-capable waiter awaiting that
+            // same promise would inherit the not_found rejection instead of creating-on-miss. It never double-creates
+            // (it only opens), so skipping the dedup is safe; two concurrent `requireExisting` opens each just
+            // repo.open independently (both find-and-cache, or both fail loud) — harmless.
+            if (opts?.requireExisting) {
+                return { session: await this.openOrCreate(sessionId, true), sessionId };
+            }
+            // Dedup concurrent create-capable acquisitions of the same id (the open/create below has an await gap).
+            const inflight = this.pending.get(sessionId);
+            if (inflight) {
+                return { session: await inflight, sessionId };
+            }
+            const p = this.openOrCreate(sessionId, false);
+            this.pending.set(sessionId, p);
+            try {
+                return { session: await p, sessionId };
+            }
+            finally {
+                this.pending.delete(sessionId);
+            }
+        }
+        const session = await this.createAndStore(undefined);
+        const meta = await session.getMetadata();
+        return { session, sessionId: meta.id };
+    }
+    /** Resume an existing session from the repo, or create it if the backend has no such id (unless
+     *  `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). */
+    async openOrCreate(id, requireExisting = false) {
+        try {
+            const session = await this.repo.open({ id, createdAt: "" });
+            const meta = await session.getMetadata();
+            // Carry the persisted lineage into the cache entry — a reopened fork (post-eviction acquire) must keep
+            // its `forkedFrom` in `list()` projections (codex 1.265.0 review F4).
+            this.entries.set(id, { session, lastActiveAt: Date.now(), createdAt: meta.createdAt, ...(meta.forkedFrom !== undefined ? { forkedFrom: meta.forkedFrom } : {}) });
+            return session;
+        }
+        catch (err) {
+            // `not_found` (or a conflict racing a creator) → create fresh. A real backend error rethrows.
+            if (!isNotFound(err) && !isSessionConflict(err)) {
+                throw err;
+            }
+            // design/114 Phase3: `requireExisting` ⇒ FAIL-LOUD on a genuinely missing session — never the silent
+            // create-on-miss that turns a reuse-style warm-resume into a fresh empty run ("looks warm, actually fresh").
+            // Only `not_found`: a conflict is a racing creator, so the session WILL exist — fall through to resolve it.
+            if (requireExisting && isNotFound(err)) {
+                throw err;
+            }
+            return this.createAndStore(id);
+        }
+    }
+    async createAndStore(id) {
+        const session = await this.repo.create(id ? { id } : {});
+        const meta = await session.getMetadata();
+        // Same lineage carry as openOrCreate: `create({id})` on a file-backed repo REOPENS an existing session
+        // (idempotent create), which may be a fork whose metadata carries `forkedFrom`.
+        this.entries.set(meta.id, { session, lastActiveAt: Date.now(), createdAt: meta.createdAt, ...(meta.forkedFrom !== undefined ? { forkedFrom: meta.forkedFrom } : {}) });
+        return session;
+    }
+    /** Refresh the idle timer for a session. */
+    touch(sessionId) {
+        const e = this.entries.get(sessionId);
+        if (e) {
+            e.lastActiveAt = Date.now();
+        }
+    }
+    /** Record the most recent task run on a cached session (the `/resume` `lastRunId`); also bumps the idle
+     *  timer. Best-effort — a no-op if the session isn't cached here (the run will still be re-attachable via
+     *  its checkpoint). */
+    noteTaskRun(sessionId, taskId) {
+        const e = this.entries.get(sessionId);
+        if (e) {
+            e.lastTaskId = taskId;
+            e.lastActiveAt = Date.now();
+        }
+    }
+    /** List the live cache as {@link SessionSummary} projections, newest-first by `lastActiveAt` (so a shell's
+     *  `/resume` shows recent sessions + their last run first). The in-memory store lists only its live cache,
+     *  not evicted/durable history — a durable backend overrides this to list persisted sessions. */
+    async list() {
+        return [...this.entries.entries()]
+            .map(([sessionId, e]) => ({
+            sessionId,
+            lastActiveAt: e.lastActiveAt,
+            ...(e.createdAt !== undefined && e.createdAt !== "" ? { createdAt: e.createdAt } : {}),
+            ...(e.lastTaskId !== undefined ? { lastTaskId: e.lastTaskId } : {}),
+            ...(e.forkedFrom !== undefined ? { forkedFrom: e.forkedFrom } : {}),
+        }))
+            .sort((a, b) => b.lastActiveAt - a.lastActiveAt);
+    }
+    /**
+     * design/110 (F3) — FORK a session: copy `sourceId`'s committed history into a NEW session and return its id
+     * (or `null` when the source doesn't exist). Delegates to the backing repo's `fork`, so a durable repo persists the
+     * branch; the in-memory repo holds it in-process. Registering the result in this cache makes `acquire(forkedId)`
+     * hit immediately — the synchronous child run that `Agent(subagent_type:"fork")` launches resumes the fork without a repo round-trip.
+     *
+     * Adding this method is what makes {@link hasSessionFork} true for a `TtlSessionStore` wrapping ANY repo, so the
+     * fork capability mounts (it was INERT before — the durable repo had `fork` but the store never exposed it).
+     */
+    async fork(sourceId, owner) {
+        // Resume the source from its committed history. A missing id → null: forking a non-existent session must NEVER
+        // create-empty (unlike `acquire`/`openOrCreate`, which create-on-miss) — else a fork of a bad id would hand back
+        // an empty session masquerading as the parent's context. A real backend error (not `not_found`) is not "source
+        // missing" — rethrow it so the fork tool reports a fork FAILURE, not a (wrong) "source not found".
+        let source;
+        try {
+            source = await this.repo.open({ id: sourceId, createdAt: "" });
+        }
+        catch (err) {
+            if (isNotFound(err)) {
+                return null;
+            }
+            throw err;
+        }
+        // F4: when the source's leaf is an IN-FLIGHT assistant turn (tool calls emitted, results not yet committed —
+        // exactly the state while THIS Fork tool's own call executes), fork to its PARENT so the child does not inherit
+        // an orphan tool-call that wake/resume reconciliation would taint with an [INTERRUPTED] result. A settled leaf
+        // forks whole (`{}`). `/branch` and explicit-entryId callers do not reach this path (they call `repo.fork` directly).
+        const forkOptions = await settledForkOptions(source);
+        // `owner` scopes the new session for a multi-tenant durable repo. The default-typed `SessionRepo.fork` options
+        // (`{entryId?, position?, id?}`) carry no `owner` field — the bundled in-memory/file/pg repos ignore the extra key;
+        // a multi-tenant repo reads it. Built as a loose object + cast so the optional `owner` doesn't fight the static type.
+        const forkParams = { ...forkOptions, id: uuidv7() };
+        if (owner != null) {
+            forkParams.owner = owner;
+        }
+        const forked = await this.repo.fork(await source.getMetadata(), forkParams);
+        const meta = await forked.getMetadata();
+        // Register the fork in the cache (mirrors createAndStore) so the immediate child `acquire(forkedId)` hits it;
+        // a durable repo also persisted it, so a later cross-replica resume re-opens the same history.
+        this.entries.set(meta.id, {
+            session: forked,
+            lastActiveAt: Date.now(),
+            createdAt: meta.createdAt,
+            // F7 fork-GC seam: prefer the repo-stamped lineage; fall back to the known source for a repo
+            // that predates the forkedFrom stamp.
+            forkedFrom: meta.forkedFrom ?? sourceId,
+        });
+        return meta.id;
+    }
+    /** Drop a session from the live set. With a durable repo (`evict: "forget"`) the history is kept. */
+    async release(sessionId) {
+        // A pinned session backs a COMMITTED durable checkpoint awaiting resume — never release/delete it (else the
+        // checkpoint is orphaned), mirroring sweep()'s pin guard. Reachable when a committed suspend is MASKED by a
+        // higher-priority failure status (budget/threw/output.invalid), so a caller's isDurablePause() check on the
+        // result status misses it and releases unconditionally (R6 bug-hunt). unpin() (on resume/expiry) re-enables it.
+        if (this.pinned.has(sessionId)) {
+            return;
+        }
+        const e = this.entries.get(sessionId);
+        if (!e) {
+            return;
+        }
+        this.entries.delete(sessionId);
+        if (this.evictPolicy === "delete") {
+            await this.repo.delete(await e.session.getMetadata());
+        }
+    }
+    /** Drop only the cached view — the repo keeps the session regardless of `evictPolicy`, so a re-acquire
+     *  re-opens the SAME history (B-17: the reconcile retry / prepare-throw paths must never delete). Cost
+     *  on the default in-memory repo: ONE retained session object **per forgotten id** until process end
+     *  (invisible to `size`/`sweep`, which track the cache) — accumulation across many distinct forgotten
+     *  ids is the accepted trade-off vs silent history loss; deployments with churn use a durable repo,
+     *  where retention is the backend's normal job. A pinned id stays pinned (a forget must never expose a
+     *  suspended task's session to sweep eviction). */
+    forget(sessionId) {
+        this.entries.delete(sessionId);
+    }
+    /** Pin a session so idle sweep can't evict it while a design/45 checkpoint awaits resume (§5). */
+    pin(sessionId) {
+        this.pinned.add(sessionId);
+    }
+    /** Release a design/45 pin (on resume or checkpoint expiry); the session resumes normal idle eviction. */
+    unpin(sessionId) {
+        this.pinned.delete(sessionId);
+    }
+    /** Evict idle-expired sessions from the cache. Deletes durable history only when `evict: "delete"`. */
+    sweep(now = Date.now()) {
+        for (const [id, e] of this.entries) {
+            // A pinned session backs a suspended task awaiting resume — never evict it on the idle timer (§5).
+            if (this.pinned.has(id)) {
+                continue;
+            }
+            if (now - e.lastActiveAt > this.defaultTtlMs) {
+                this.entries.delete(id);
+                if (this.evictPolicy === "delete") {
+                    void this.repo.delete({ id, createdAt: "" });
+                }
+            }
+        }
+    }
+    get size() {
+        return this.entries.size;
+    }
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+        }
+    }
+}
+/**
+ * design/110 (F4) — pick the fork point so a child does NOT inherit an in-flight (uncommitted) tool call.
+ *
+ * The agent loop commits the assistant turn (`message_end` → `appendMessage`) BEFORE it executes that turn's tool
+ * calls. So while the Fork tool's own `execute` runs, the source session's LEAF is the assistant message that carries
+ * the Fork tool-call (and any sibling parallel calls) with NO tool results behind it yet. Forking the whole log would
+ * copy that orphan call into the child, and the child's wake-time `reconcileInterruptedSession` would inject an
+ * `[INTERRUPTED]` result for it — polluting the inherited context ("I called Fork → it was interrupted").
+ *
+ * Detection: leaf is an assistant `message` whose `content` includes a `toolCall` block (the message shape — there is
+ * NO `toolCalls` field; tool calls are content blocks, mirroring `agent-loop.ts`'s `content.filter(c => c.type ===
+ * "toolCall")`). When so, fork at the leaf's PARENT (`position:"at"` includes the parent, excludes the assistant turn)
+ * — the correct fork semantics: "inherit my context up to, but not including, the spawn call". A settled leaf, or an
+ * unsettled assistant that is somehow a root (no `parentId`, fail-safe), forks the whole log (`{}`).
+ */
+async function settledForkOptions(source) {
+    const storage = source.getStorage();
+    // Walk from the leaf to the nearest assistant message. At fork time (mid-Fork-execute) the most-recent assistant
+    // turn is the IN-FLIGHT one whose tool calls are still running. A leaf-ONLY check covers the PARALLEL default (all
+    // `toolResult`s commit only after Promise.all → leaf IS the assistant) and a Fork-first sequential turn, but MISSES
+    // the case where Fork is NOT the turn's first call under SEQUENTIAL execution: an earlier sibling call's `toolResult`
+    // has already committed and is the leaf (review-flagged edge). Skip those trailing `toolResult` messages to reach the
+    // turn's assistant, then fork at ITS parent — so the child never inherits the orphan Fork call.
+    let id = await storage.getLeafId();
+    while (id) {
+        const entry = await storage.getEntry(id);
+        if (!entry || entry.type !== "message") {
+            return {};
+        }
+        if (entry.message.role === "assistant") {
+            // The in-flight turn — fork BEFORE it iff it carries a tool call (the Fork call + any siblings). A settled
+            // text-only assistant, or one with no parent (fail-safe), forks the whole log (`{}`). `position:"at"` includes
+            // the parent + excludes the assistant turn = "inherit my context up to, but not including, the spawn call".
+            const hasToolCall = Array.isArray(entry.message.content) &&
+                entry.message.content.some((c) => c.type === "toolCall");
+            return hasToolCall && entry.parentId ? { entryId: entry.parentId, position: "at" } : {};
+        }
+        if (entry.message.role !== "toolResult") {
+            // A user/other message reached before any assistant ⟹ the leaf is a settled boundary; no in-flight turn.
+            return {};
+        }
+        id = entry.parentId;
+    }
+    return {};
+}
+/** A repo `open` miss for a missing id. */
+function isNotFound(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === "not_found");
+}
+//# sourceMappingURL=session-store.js.map

package/dist/core/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/core/session-store.ts"],"names":[],"mappings":"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"}

package/dist/core/session.d.ts

@@ -0,0 +1,144 @@
+export { Session } from "../internal/harness.js";
+export type { SessionApi } from "../internal/harness.js";
+export { InMemorySessionRepo, InMemorySessionStorage, uuidv7, validateEntriesForImport, StreamingImportValidator, } from "../internal/harness.js";
+export { BaseSessionStorage, leafIdAfterEntry, } from "../internal/harness.js";
+export type { SessionStorage, SessionRepo, SessionMetadata, SessionTreeEntry, } from "../internal/harness.js";
+export { SessionError } from "../internal/harness.js";
+export type { SessionWriteOptions } from "../internal/harness.js";
+import type { SessionApi } from "../internal/harness.js";
+import type { SessionTreeEntry } from "../internal/harness.js";
+/** True when `err` is a session optimistic-lock conflict (a concurrent writer won the branch leaf). */
+export declare function isSessionConflict(err: unknown): boolean;
+/** A session handed back by a {@link SessionStore}: the harness `Session` plus its resolved id. */
+export interface AcquiredSession {
+    session: SessionApi;
+    sessionId: string;
+}
+/**
+ * A lightweight, read-only projection of one session for a `/resume` list (shell K-5 — re-attach without an
+ * N+1 walk). Returned in bulk by {@link SessionStore.list}, newest-first by `lastActiveAt` by convention.
+ * `lastTaskId` is the engine's term for what the service/wire surfaces as the session's **`lastRunId`** — the
+ * most recent task run on this session, so a shell re-attaches in ONE hop.
+ */
+export interface SessionSummary {
+    /** The session id. */
+    sessionId: string;
+    /** When the session was created ({@link SessionMetadata.createdAt}, ISO string); absent when the backend's
+     *  cache view doesn't carry it. */
+    createdAt?: string;
+    /** Epoch ms the session was last acquired / touched / ran — the newest-first sort key for "recent sessions". */
+    lastActiveAt: number;
+    /** The most recent task run on this session (core's `taskId`; the service projects it as `lastRunId`).
+     *  Absent until a task has run on the session (recorded via {@link SessionStore.noteTaskRun}). */
+    lastTaskId?: string;
+    /** F7 fork-GC seam: the parent session this one was forked from ({@link SessionMetadata.forkedFrom}).
+     *  Lets a consumer render/reap fork lineage; absent on non-forked sessions and on cache views that
+     *  predate the fork. The durable source of truth is the repo's persisted metadata. */
+    forkedFrom?: string;
+}
+/**
+ * The session lifecycle/caching layer the {@link Runner} depends on.
+ *
+ * `TtlSessionStore` is the default (in-memory, 7-day idle TTL). Provide a custom implementation
+ * to back sessions with durable, external storage (the "Session center"): `acquire` reconstructs
+ * a session from the persisted event log so any stateless runner instance can resume it.
+ *
+ * Implementations must be safe under concurrent `acquire` of the same id (return one session).
+ */
+export interface SessionStore {
+    /** Get an existing session by id, or create one (optionally with a caller-supplied id). design/114 Phase3:
+     *  `opts.requireExisting` ⇒ a store MUST fail loud (throw a `not_found` {@link SessionError}) on a genuinely
+     *  missing id rather than create-on-miss — so a reuse-style warm-resume of a gone session errors instead of
+     *  silently starting a fresh empty run. A store that cannot honor it MUST still not silently create (either
+     *  implement the check or reject the option). */
+    acquire(sessionId?: string, opts?: {
+        requireExisting?: boolean;
+    }): Promise<AcquiredSession>;
+    /** Mark a session recently active (resets idle TTL where applicable). May be async for durable stores. */
+    touch(sessionId: string): void | Promise<void>;
+    /** Drop a session from the live set (e.g. a throwaway task). Durable history may be retained by the backend. */
+    release(sessionId: string): Promise<void>;
+    /**
+     * Drop only the CACHED view of a session — **never** deletes history (unlike `release`, which with the
+     * in-memory `TtlSessionStore`'s default `evict: "delete"` policy removes the session from the repo too).
+     * The Runner uses this where the intent is "discard a stale view and re-wake", and on a prepare-phase
+     * throw after acquire (audit B-17 + the 1.93.0 throw-cleanup contract gap: calling `release` there
+     * silently DELETED an existing session's whole history on the default store — the re-acquire then
+     * continued on an empty same-id session). **Optional, but custom stores SHOULD implement it**: when
+     * absent the Runner performs NO fallback (it never substitutes `release`, whose contract permits
+     * deletion — B-17 council) — the cached view is simply not dropped, so a persistent reconcile conflict
+     * exhausts its retry budget and propagates instead of risking history. A store whose `release` is
+     * already history-safe can implement `forget = release`.
+     */
+    forget?(sessionId: string): void | Promise<void>;
+    /**
+     * Protect a session from idle eviction while a design/45 checkpoint references it (a suspended task
+     * must still be resumable). `pin` before suspend, `unpin` on resume/expiry. **Optional**: a durable
+     * backend that never idle-GCs sessions (service's `tidb-session-store`) implements both as no-ops and
+     * is still safe; only the in-memory `TtlSessionStore` needs a real pin (its `sweep` skips pinned ids).
+     * See design/45 §5 / M3.
+     */
+    pin?(sessionId: string): void | Promise<void>;
+    unpin?(sessionId: string): void | Promise<void>;
+    /**
+     * Record that a task run STARTED on a session (the Runner calls this at task start, when both ids are
+     * known) so the store can surface it as {@link SessionSummary.lastTaskId} — letting a `/resume` list
+     * re-attach to the most recent run, even one still in-flight or suspended. **Optional + best-effort**: a
+     * store that surfaces no session list may ignore it; it MUST NOT throw. The engine's `taskId` is the
+     * service's `lastRunId`.
+     */
+    noteTaskRun?(sessionId: string, taskId: string): void | Promise<void>;
+    /**
+     * Enumerate known sessions as lightweight {@link SessionSummary} projections (newest-first by
+     * `lastActiveAt`) so a shell's `/resume` lists sessions + their last run in ONE call. **Optional**: the
+     * in-memory `TtlSessionStore` lists its live cache; a durable backend lists persisted sessions. A store
+     * that cannot enumerate omits this (the shell then has no session-list affordance — honest degrade).
+     */
+    list?(): Promise<SessionSummary[]>;
+    /**
+     * design/110 — FORK a session: copy `sourceId`'s durable history (root→leaf) into a NEW session and return its
+     * id (or `null` if the source doesn't exist). The forked session is independent (writes to it don't touch the
+     * source). Backs CC `/fork` (continue with the parent's full context) AND the inheriting-context subagent fork
+     * (run a child on the fork so it inherits the parent context + shares the prompt-cache prefix). **Optional**:
+     * a store implements it only if it can replay history. `TtlSessionStore` DOES — it delegates to its
+     * {@link SessionRepo} (so {@link hasSessionFork} is true) — BUT the fork is only as durable as that repo:
+     * an in-memory repo forks IN-PROCESS yet loses the copy on restart, while a durable repo (file/pg) makes the
+     * fork survive restart/replica. **Capability presence ≠ durability** — a cross-replica consumer (design/114
+     * warm-resume) MUST wire a durable repo; core cannot verify durability, only fail-loud on a missing source at
+     * fork time (returns `null`). `owner` (if given) scopes the new session for multi-tenant stores. MUST copy the COMMITTED leaf (an in-flight
+     * uncommitted turn of an active source is not included — a fork is a snapshot at the fork point).
+     */
+    fork?(sourceId: string, owner?: string | null): Promise<string | null>;
+    /** Number of live/cached sessions (best-effort). */
+    readonly size: number;
+    /** Release resources (timers, connections). Best-effort; must not throw. */
+    dispose(): void | Promise<void>;
+}
+/** Structural detection: does this store expose the optional {@link SessionStore.fork}? Mounts the fork
+ *  capability only when true (INERT otherwise — mirrors `hasScheduler`/`hasBackgroundShell`). */
+export declare function hasSessionFork(store: SessionStore): store is SessionStore & {
+    fork: NonNullable<SessionStore["fork"]>;
+};
+/**
+ * F3 bounded-wake recipe, packaged. Given the **path-ordered** entries of a branch
+ * (root→leaf, e.g. `await session.getBranch(leafId)` or a durable store's leaf-walk),
+ * returns the smallest self-contained tail a stateless runner needs to resume:
+ *
+ *  - `floorEntryId` = the **latest** compaction's `firstKeptEntryId` (null if never compacted),
+ *  - `tail` = entries from that floor to the leaf — i.e. the surviving compaction summary
+ *    plus every message kept after it. Everything before the floor is already folded into
+ *    that summary, so it can stay cold in durable storage.
+ *
+ * Hand the result straight to a floored storage:
+ * `new InMemorySessionStorage({ entries: tail, floorEntryId })` (or your durable equivalent).
+ * `buildContext()` on that is identical to waking from the full tree — see `session-floor.test.ts`.
+ *
+ * Pure and allocation-light: it scans for the last compaction and slices. If the tree was never
+ * compacted (or the floor isn't on this path — shouldn't happen for a real branch) it returns the
+ * full input unchanged with `floorEntryId: null`, so callers can always use the result verbatim.
+ */
+export declare function boundedTail(pathEntries: readonly SessionTreeEntry[]): {
+    tail: SessionTreeEntry[];
+    floorEntryId: string | null;
+};
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"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"}

package/dist/core/session.js

@@ -0,0 +1,56 @@
+// Pluggable session building blocks. A durable backend (e.g. a TiDB session event-log center)
+// is built from these: implement/extend `SessionStorage` (usually `extends BaseSessionStorage`,
+// overriding appendEntry/setLeafId to persist), wrap it in `Session`, and expose it via a
+// `SessionStore` whose `acquire` reconstructs a session from the persisted log (= wake/resume).
+export { Session } from "../internal/harness.js";
+export { InMemorySessionRepo, InMemorySessionStorage, uuidv7, validateEntriesForImport, StreamingImportValidator, } from "../internal/harness.js";
+export { BaseSessionStorage, leafIdAfterEntry, } from "../internal/harness.js";
+// Optimistic-lock seam (F2): durable backends use SessionWriteOptions.expectedLeafId for CAS;
+// a losing concurrent writer gets SessionError("conflict") — detect it with isSessionConflict().
+export { SessionError } from "../internal/harness.js";
+import { SessionError } from "../internal/harness.js";
+/** True when `err` is a session optimistic-lock conflict (a concurrent writer won the branch leaf). */
+export function isSessionConflict(err) {
+    return err instanceof SessionError && err.code === "conflict";
+}
+/** Structural detection: does this store expose the optional {@link SessionStore.fork}? Mounts the fork
+ *  capability only when true (INERT otherwise — mirrors `hasScheduler`/`hasBackgroundShell`). */
+export function hasSessionFork(store) {
+    return typeof store.fork === "function";
+}
+/**
+ * F3 bounded-wake recipe, packaged. Given the **path-ordered** entries of a branch
+ * (root→leaf, e.g. `await session.getBranch(leafId)` or a durable store's leaf-walk),
+ * returns the smallest self-contained tail a stateless runner needs to resume:
+ *
+ *  - `floorEntryId` = the **latest** compaction's `firstKeptEntryId` (null if never compacted),
+ *  - `tail` = entries from that floor to the leaf — i.e. the surviving compaction summary
+ *    plus every message kept after it. Everything before the floor is already folded into
+ *    that summary, so it can stay cold in durable storage.
+ *
+ * Hand the result straight to a floored storage:
+ * `new InMemorySessionStorage({ entries: tail, floorEntryId })` (or your durable equivalent).
+ * `buildContext()` on that is identical to waking from the full tree — see `session-floor.test.ts`.
+ *
+ * Pure and allocation-light: it scans for the last compaction and slices. If the tree was never
+ * compacted (or the floor isn't on this path — shouldn't happen for a real branch) it returns the
+ * full input unchanged with `floorEntryId: null`, so callers can always use the result verbatim.
+ */
+export function boundedTail(pathEntries) {
+    // Latest compaction wins: a re-compaction's summary already folds in the prior one.
+    let lastCompaction;
+    for (const e of pathEntries) {
+        if (e.type === "compaction")
+            lastCompaction = e;
+    }
+    if (!lastCompaction)
+        return { tail: [...pathEntries], floorEntryId: null };
+    const floorEntryId = lastCompaction.firstKeptEntryId;
+    const floorIdx = pathEntries.findIndex((e) => e.id === floorEntryId);
+    if (floorIdx < 0) {
+        // Defensive: floor not on this path — don't drop history we can't account for.
+        return { tail: [...pathEntries], floorEntryId: null };
+    }
+    return { tail: pathEntries.slice(floorIdx), floorEntryId };
+}
+//# sourceMappingURL=session.js.map

package/dist/core/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,gGAAgG;AAChG,0FAA0F;AAC1F,gGAAgG;AAChG,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAIjD,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,MAAM,EACN,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAOhC,8FAA8F;AAC9F,iGAAiG;AACjG,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAItD,uGAAuG;AACvG,MAAM,UAAU,iBAAiB,CAAC,GAAY;IAC5C,OAAO,GAAG,YAAY,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;AAChE,CAAC;AA4GD;iGACiG;AACjG,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,OAAO,OAAQ,KAA4B,CAAC,IAAI,KAAK,UAAU,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAAC,WAAwC;IAIlE,oFAAoF;IACpF,IAAI,cAA2C,CAAC;IAChD,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY;YAAE,cAAc,GAAG,CAAoB,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,cAAc;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAE3E,MAAM,YAAY,GAAG,cAAc,CAAC,gBAAgB,CAAC;IACrD,MAAM,QAAQ,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,YAAY,CAAC,CAAC;IACrE,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,+EAA+E;QAC/E,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;AAC7D,CAAC"}