@sema-agent/server 1.323.0 → 2.0.0

package/dist/session-sync-kernel.js

@@ -1,39 +1,84 @@
+/** The staging-id format: a real session id with a `#stg-${token}` suffix. The `#` is illegal in a uuidv7, so a
+ *  staging id can never collide with a real session id (the orphan invariant) and is recognizable for the reaper. */
 export function stagingIdFor(realSessionId, token) {
     return `${realSessionId}#stg-${token}`;
 }
+/** The substring marker every staging id carries (the reaper's `LIKE '%#stg-%'` selector). */
 export const STAGING_ID_MARKER = "#stg-";
+/** Recover the real session id from a staging id (everything before the `#stg-` marker), or null if not a staging id. */
 export function realIdOfStaging(stagingId) {
     const i = stagingId.indexOf(STAGING_ID_MARKER);
     return i < 0 ? null : stagingId.slice(0, i);
 }
+/**
+ * §7 — classify how importing `srcEntries` into a destination holding `dstEntries` would relate the two logs. PURE
+ * (no I/O); the §7 fork detector. The comparison is over the ENTRY-ID SETS, not leaf_id:
+ *
+ * Entry ids are copied VERBATIM across backends (fork/import re-seq only `seq`; id/parentId/payload are byte-identical
+ * — see tidb-session-store fork/importEntries), so a set comparison of ids is the SOUND divergence test §7 demands. It
+ * fixes v1's leaf_id-only check, which was unsound BOTH ways:
+ *   - FALSE NEGATIVE (the dangerous one): a cross-end rewind moves `LeafEntry.targetId` back onto a shared OLD entry id,
+ *     so two genuinely-forked logs report the SAME leaf_id → v1 would silently overwrite = data loss (exactly the 2c
+ *     use case). Set comparison sees each side's exclusive ids and reports `fork`.
+ *   - FALSE POSITIVE: a clean fast-forward ends on a NEW leaf id ≠ the dst's leaf → v1 flags a (non-)conflict. Set
+ *     comparison sees dst ⊊ src and reports `fast_forward` (safe).
+ *
+ * `commonAncestor` for a fork = the entry id present in BOTH logs that appears LAST in `srcEntries` oldest-first order
+ * (the deepest shared appended entry = the divergence point), or `null` if the logs share no entry at all.
+ */
 export function classifySyncRelationship(srcEntries, dstEntries) {
+    // Map entries → their ids (the only thing the comparison reads) and delegate to the id-set classifier — ONE source
+    // of the §7 relation logic. (P1d's HTTP plan route, where one peer is REMOTE and sends only an entry-id LIST, calls
+    // classifySyncRelationshipByIds DIRECTLY; this entries-typed entry point is the same logic with a nicer call shape.)
     return classifySyncRelationshipByIds(srcEntries.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
 }
+/**
+ * §7 — the SAME relation classifier as {@link classifySyncRelationship}, over entry-id LISTS (oldest-first) instead of
+ * full entries. This is the canonical implementation the entries-typed wrapper delegates to. It exists in its own right
+ * for the P1d HTTP `/sync/plan` route: the two peers are different PROCESSES (the local shell + the cloud), so the
+ * planning peer holds only the OTHER end's entry-id list (not its `SessionTreeEntry[]`) — the relation is decidable from
+ * the ids alone (ids are copied VERBATIM across backends, so a set comparison of ids is the sound divergence test §7
+ * demands; see the wrapper's doc-comment for why leaf_id was unsound). `srcIds`/`dstIds` are OLDEST-FIRST so the
+ * fork `commonAncestor` (the deepest shared id) and the ordered exclusive/new lists are derived correctly.
+ */
 export function classifySyncRelationshipByIds(srcIds, dstIds) {
+    // dst absent OR empty ⇒ nothing at the destination to relate to / lose → an unconditional fresh import.
     if (dstIds === null || dstIds.length === 0)
         return { relation: "fresh" };
     const srcSet = new Set(srcIds);
     const dstSet = new Set(dstIds);
+    // identical: same cardinality AND every src id is in dst (⟹ the sets are equal) → already present & equal (no-op).
     if (srcSet.size === dstSet.size && [...srcSet].every((id) => dstSet.has(id)))
         return { relation: "identical" };
-    const allDstInSrc = [...dstSet].every((id) => srcSet.has(id));
-    const allSrcInDst = [...srcSet].every((id) => dstSet.has(id));
+    const allDstInSrc = [...dstSet].every((id) => srcSet.has(id)); // dst ⊆ src
+    const allSrcInDst = [...srcSet].every((id) => dstSet.has(id)); // src ⊆ dst
+    // fast_forward: dst ⊊ src (src strictly ahead — a clean append) → safe to apply. newEntryIds = the src ids the dst
+    // lacks, in SRC oldest-first order (the appended tail), so the caller can surface "what would be added".
     if (allDstInSrc && !allSrcInDst) {
         const newEntryIds = srcIds.filter((id) => !dstSet.has(id));
         return { relation: "fast_forward", newEntryIds };
     }
+    // stale: src ⊊ dst (src strictly behind) → applying would DROP the dst entries src never saw = data loss. dstAheadBy
+    // = the dst ids src lacks (dst order). Refused as a conflict unless the caller explicitly resolves overwrite-dst.
     if (allSrcInDst && !allDstInSrc) {
         const dstAheadBy = dstIds.filter((id) => !srcSet.has(id));
         return { relation: "stale", dstAheadBy };
     }
+    // fork: neither set contains the other ⇒ each side has ≥1 exclusive entry (true divergence). The common ancestor is
+    // the deepest shared entry = the LAST id in src oldest-first order that the dst also holds (null if no shared id).
     const srcExclusive = srcIds.filter((id) => !dstSet.has(id));
     const dstExclusive = dstIds.filter((id) => !srcSet.has(id));
     let commonAncestor = null;
     for (const id of srcIds)
         if (dstSet.has(id))
-            commonAncestor = id;
+            commonAncestor = id; // last shared id in src oldest-first order
     return { relation: "fork", commonAncestor, srcExclusive, dstExclusive };
 }
+/**
+ * §7 — a typed conflict the route maps to HTTP 409: an import that WOULD lose destination history (a `fork` or a
+ * `stale` source) and the caller did NOT pass an explicit `{ resolution: "overwrite-dst" }`. Carries the classified
+ * relation so the route/shell can surface the exclusive entry sets to the user for a keep-local / keep-cloud decision.
+ */
 export class SyncConflictError extends Error {
     sessionId;
     relation;

package/dist/session-sync.d.ts

@@ -1,47 +1,164 @@
+/**
+ * 2c session-sync — P1b ORCHESTRATION: export a session's WHOLE portable state from one StoreBackend and import it
+ * verbatim into another (the seamless local↔cloud "save state" move; docs/DESIGN-session-sync.md §5–§10). All the
+ * per-store PRIMITIVES already exist (P1a entries + P1b snapshots/policy/anchor); this module is the COORDINATOR that
+ * (a) reads them into a {@link SessionBundle} and (b) replays them across backends in the §8 fail-closed atomic order.
+ *
+ * This is a SERVICE function — the caller (the future HTTP route, P1d) owns the `sessionOwnerScope` gate (§9: export
+ * 404s a non-owner, import re-stamps owner to the authenticated principal). exportSession/importSession themselves do
+ * NOT authenticate; they assume the caller proved ownership.
+ *
+ * Scope (P1b): a one-shot whole-session move with FAIL-CLOSED validation (§10) + cross-store atomic ordering (§8) +
+ * owner re-stamp (§9). NOT in scope here: sync-watermark / fork detection (§7) and HTTP/streaming blob negotiation
+ * (§5) — those are P1c/P1d. Blobs are NOT held in memory (§5 OOM guard): the bundle carries only the manifest
+ * (relPath→blobHash); bytes flow through a `getBlob(hash)` getter the importer pulls content-addressed (deduped).
+ */
 import type { StoreBackend } from "./plugins/store-backend.js";
 import { type SyncRelation } from "./session-sync-kernel.js";
 import type { SessionTreeEntry, SessionRulesRecord } from "@sema-agent/core";
+/** A blob getter: content-addressed bytes for a sha256 hash, or `undefined` if the source can't supply them.
+ *  Returned by {@link exportSession} (closes over the source store), consumed by {@link importSession}. */
 export type BlobGetter = (hash: string) => Promise<Uint8Array | undefined>;
 export { stagingIdFor, STAGING_ID_MARKER, realIdOfStaging, classifySyncRelationship, classifySyncRelationshipByIds, SyncConflictError } from "./session-sync-kernel.js";
 export type { StagingHandle, ImportStagingStore, SyncRelation } from "./session-sync-kernel.js";
+/**
+ * The portable state of ONE session, ready to replay into another backend. Blobs are deliberately NOT inlined
+ * (§5: a turn's working-tree blobs can be tens of MiB → OOM/413 if buffered); each snapshot carries only its
+ * `manifest` (relPath → blobHash) and the bytes are streamed through the paired {@link BlobGetter}.
+ */
 export interface SessionBundle {
     sessionId: string;
+    /** The FULL durable conversation log (compaction floor bypassed), verbatim ids/parents/payload — `exportEntries`. */
     entries: SessionTreeEntry[];
+    /** One per E19 file snapshot (keyed by `SessionTreeEntry.id` = `key`); manifest = [relPath, blobHash] tuples. */
     snapshots: Array<{
         key: string;
         manifest: Array<[string, string]>;
     }>;
+    /** Every (principal, rules) record for the session, across ALL principals (E6 `listBySession`). */
     policy: SessionRulesRecord[];
+    /** Every E18 resume-at anchor (eventId→entryId + its source owner; owner is RE-KEYED on import, §9). */
     anchors: Array<{
         eventId: string;
         entryId: string;
         owner: string | null;
     }>;
 }
+/**
+ * P1d-α (PULL streaming, §1.5/§5/§15) — a {@link SessionBundle} with the ENTRIES LIFTED OFF THE WIRE: the HTTP PULL
+ * `GET /sync/manifest` returns THIS (small, bounded), and the entries flow separately through the NDJSON
+ * `GET /sync/entries` stream (bounded memory regardless of session size — the §1.5 ruling: entries are small text
+ * rows, so streaming is about ROW COUNT, not blob size). It carries the entries' IDS (`entryIds`, oldest-first — the
+ * local peer feeds these to {@link classifySyncRelationshipByIds} to decide fast-forward / fork BEFORE pulling the
+ * stream) + the count + the current leaf, and the snapshots/policy/anchors EXACTLY as {@link SessionBundle} does.
+ */
 export interface SessionManifest {
     sessionId: string;
+    /** The full durable log's entry IDS, oldest-first (verbatim, cross-backend stable) — NOT the entry payloads. */
     entryIds: string[];
+    /** `entryIds.length` — the number of entries the paired `/sync/entries` stream will yield (the trailer's count). */
     entryCount: number;
+    /** The session's current leaf `SessionTreeEntry.id` (session_meta.leaf_id), or null if it has none. */
     leafId: string | null;
+    /** One per E19 file snapshot (keyed by entry id); manifest = [relPath, blobHash] tuples. EXACTLY as the bundle. */
     snapshots: Array<{
         key: string;
         manifest: Array<[string, string]>;
     }>;
+    /** Every (principal, rules) record across ALL principals (E6 `listBySession`). EXACTLY as the bundle. */
     policy: SessionRulesRecord[];
+    /** Every E18 resume-at anchor (eventId→entryId + source owner; RE-KEYED on import, §9). EXACTLY as the bundle. */
     anchors: Array<{
         eventId: string;
         entryId: string;
         owner: string | null;
     }>;
 }
+/**
+ * EXPORT a session's whole portable state from `srcBackend` into a {@link SessionBundle} + a {@link BlobGetter}.
+ *
+ * - entries: `exportEntries(sessionId)` — `null` ⇒ the session does not exist ⇒ this returns `null` (no partial bundle).
+ * - snapshots: `listKeys(sessionId)` → for each key `exportManifest(scope,key)` → `{key, [...manifest]}`. A key whose
+ *   manifest reads back `null` (a concurrent reap between listKeys and exportManifest) is dropped, not exported empty.
+ * - policy: `listBySession(sessionId)` (empty `[]` if the store lacks the optional seam — honest degrade).
+ * - anchors: `listBySession(sessionId)` (empty `[]` if the store has no resumeAnchor seam).
+ * - getBlob: bound to the source `fileSnapshot().getBlob` so the importer can pull content-addressed bytes lazily.
+ *
+ * The OWNER is NOT exported (import re-stamps it, §9). The owner-scope GATE is the CALLER's (route P1d): this returns
+ * `null` ONLY for "session does not exist", never as an authz signal.
+ *
+ * NB (P1d-α): the HTTP PULL no longer uses this — it uses {@link exportSessionManifest} (entries lifted off the wire)
+ * + the keyset-paged `exportEntriesStream` NDJSON route so memory is bounded by ROW COUNT, not the whole-log array.
+ * exportSession (entries-inline) STAYS for the local same-process import path, P1d-β (PUSH), and the tests.
+ */
 export declare function exportSession(sessionId: string, srcBackend: StoreBackend): Promise<{
     bundle: SessionBundle;
     getBlob: BlobGetter;
 } | null>;
+/**
+ * P1d-α (PULL streaming, §15) — EXPORT a session's portable state as a {@link SessionManifest} (entries LIFTED OFF
+ * the wire) + a {@link BlobGetter}. Like {@link exportSession} but it does NOT load entry payloads: it reads the
+ * IDS-only projection via `listEntryIds` (`null` ⇒ no such session ⇒ this returns `null`), counts them, reads the
+ * current `leafId`, and builds snapshots/policy/anchors EXACTLY as exportSession does. The paired NDJSON
+ * `GET /sync/entries` route streams the entry payloads separately (keyset-paged → bounded memory), so a 1M-entry
+ * session's manifest stays small (ids + counts + the snapshot/policy/anchor metadata).
+ *
+ * The OWNER is NOT exported (import re-stamps it, §9). The owner-scope GATE is the CALLER's (route P1d): this returns
+ * `null` ONLY for "session does not exist". (Named exportSessionManifest, NOT exportManifest, to avoid the collision
+ * with `FileSnapshotStore.exportManifest`.)
+ */
 export declare function exportSessionManifest(sessionId: string, srcBackend: StoreBackend): Promise<{
     manifest: SessionManifest;
     getBlob: BlobGetter;
 } | null>;
+/**
+ * IMPORT a {@link SessionBundle} (+ its {@link BlobGetter}) into `dstBackend` under `bundle.sessionId`, re-stamping
+ * ownership to `importingPrincipal`. Returns the snapshot tally (imported vs honestly-skipped on a destination whose
+ * FileSnapshotStore lacks the importManifest seam — pre-1.141.0; core's InMemory/File NOW carry it, so a local dst
+ * imports snapshots for real).
+ *
+ * §10 FAIL-CLOSED VALIDATION runs FIRST — BEFORE any write:
+ *   1. `validateEntriesForImport(bundle.entries)` (the single core invariant gate: unique ids / parent-before-child /
+ *      one root / leaf-resolvable). Throws on violation; NOTHING is written.
+ *   2. Every blobHash referenced by every snapshot manifest MUST be supplied by `getBlob` — a missing blob would
+ *      restore a PARTIAL tree (files half-written, conversation whole → breaks the entry↔file lockstep). A lightweight
+ *      PRESENCE pre-check (fetch each distinct hash once, no hashing) fails FAST here; the AUTHORITATIVE content-address
+ *      integrity check (`sha256(bytes)===hash`) is done ONCE inside `importManifest` (core 1.141.0), so we don't double-
+ *      hash. (Runs only when the dst supports snapshot import; otherwise there is nothing to half-write.)
+ *
+ * §7 CLASSIFICATION GATE — BEFORE any write, the destination's CURRENT entry log is read and compared to the bundle
+ * via {@link classifySyncRelationship} (a sound entry-id SET comparison, not leaf_id). A `fork` (true divergence) or a
+ * `stale` source (the dst is strictly ahead) WOULD lose destination history → it throws {@link SyncConflictError}
+ * (route → 409) UNLESS the caller passes `{ resolution: "overwrite-dst" }`. An `identical` relation SKIPS the entries
+ * write entirely (the log is already present & equal; the idempotent snapshot/policy/anchor replay below still runs to
+ * heal anything missing). `fresh` / `fast_forward` (and an overwrite-resolved fork/stale) write the entries via the
+ * IDEMPOTENT {@link OwnerAwareSessionStore.replaceEntries} (purge-then-import) — NOT `importEntries`, whose plain
+ * INSERT crashes on a duplicate PK when the session already exists at the destination.
+ *
+ * §8 CROSS-STORE ATOMIC ORDER + IDEMPOTENCY — session_meta (written LAST inside `replaceEntries`) is the sole
+ * commit point, so a crash mid-import leaves orphan blobs/manifests/anchors with NO session_meta = invisible to
+ * wake (never a half-session, only collectable orphans). Order:
+ *   ① snapshots (manifests + content-addressed blobs) — content-addressed + create-once = idempotent retry-to-completion.
+ *      `importManifest` returns a {@link FileSnapshotResult} (NEVER throws — core 1.141.0); a `{ok:false}` (a
+ *      rejecting/missing/hash-mismatched blob the §10 pre-check didn't catch — e.g. a blob corrupted in transit) is
+ *      re-raised as a fail-closed THROW so the import aborts BEFORE the entries commit (no entry↔file split).
+ *   ② entries (`replaceEntries` runs the core gate AGAIN and writes session_meta LAST = the commit point; idempotent
+ *      over an existing session — skipped entirely when the relation is `identical`)
+ *   ③ policy (replay each record via putRules; `opts.operatorOk` defaults FALSE → the E6 tighten-only gate APPLIES, so
+ *      a replay that would LOOSEN an operator-tightened dst policy throws `SessionPolicyError("loosen_forbidden")` —
+ *      `operator:true` is set ONLY when the authenticated importer is itself a verified operator)
+ *   ④ anchors (owner RE-KEYED to `importingPrincipal`, §9)
+ * Steps ③/④ are post-commit; re-running them is idempotent — ③ SKIPS a put whose content already equals the dst row
+ * (a "no-op rev bump" is NOT idempotent: rev is the operator's optimistic-lock token — the A6 fix below), ④ is a
+ * same-value upsert — so a crash between ②–④ is recovered by a retry that converges to the same bytes.
+ *
+ * @param opts.resolution — `"overwrite-dst"` consents to a `fork`/`stale` import that overwrites destination history
+ *   (the user's keep-source decision); omitted ⇒ such an import is refused with {@link SyncConflictError}.
+ * @param opts.operatorOk — when `true`, the policy replay (step ③) is an OPERATOR write (may loosen the dst rules); set
+ *   ONLY when the AUTHENTICATED importer is a verified operator. DEFAULT false → the E6 tighten-only gate applies, so a
+ *   non-operator import is TIGHTEN-ONLY (design §4): a replay that would loosen an operator-tightened dst session policy
+ *   throws `SessionPolicyError("loosen_forbidden")`, which propagates (NOT swallowed) so the route can refuse the loosen.
+ */
 export declare function importSession(bundle: SessionBundle, getBlob: BlobGetter, dstBackend: StoreBackend, importingPrincipal: string | null, opts?: {
     resolution?: "overwrite-dst";
     operatorOk?: boolean;
@@ -50,5 +167,13 @@ export declare function importSession(bundle: SessionBundle, getBlob: BlobGetter
     snapshotsSkipped: number;
     relation: SyncRelation["relation"];
 }>;
+/**
+ * §7 DRY-RUN — classify what importing `sessionId` from `srcBackend` into `dstBackend` WOULD do, WITHOUT writing
+ * anything. The route (P1d) calls this to surface a conflict (fork/stale) to the user BEFORE committing an
+ * {@link importSession} (so the shell can present a keep-local / keep-cloud / fork-new choice up front).
+ *
+ * Returns `null` when the SOURCE session does not exist (no bundle to plan); otherwise the {@link SyncRelation}
+ * between the source's full durable log and the destination's current log (a `null` dst log ⇒ `fresh`). No writes.
+ */
 export declare function planSync(sessionId: string, srcBackend: StoreBackend, dstBackend: StoreBackend): Promise<SyncRelation | null>;
 //# sourceMappingURL=session-sync.d.ts.map

package/dist/session-sync.js

@@ -1,19 +1,50 @@
 import { identicalIdsAlsoIdenticalContent } from "./session-sync-content.js";
 import { classifySyncRelationship, SyncConflictError } from "./session-sync-kernel.js";
 import { validateEntriesForImport, normalizeRules, stripRev } from "@sema-agent/core";
+// ── PURE KERNEL moved to ./session-sync-kernel.ts (design/158 A2) ─────────────────────────────────────────────
+// The §7 relation classifier (classifySyncRelationship[ByIds]), the staging-id scheme (stagingIdFor /
+// STAGING_ID_MARKER / realIdOfStaging), the StagingHandle / ImportStagingStore contracts and SyncConflictError
+// lived here (lines ~26–187) but depend on NOTHING in this repo — while THIS module value-imports StoreBackend and
+// type-imports security's OwnerAwareSessionStore. The three DB session adapters (local/pg/tidb) and security.ts
+// need only those pure symbols, and security.ts importing them from HERE formed the repo's only true type cycle
+// (security ↔ session-sync; lens2 §B/§E). They now live in the leaf module session-sync-kernel.ts (same shape as
+// session-sync-content.ts) and are RE-EXPORTED verbatim below, so existing importers of this module keep working.
 export { stagingIdFor, STAGING_ID_MARKER, realIdOfStaging, classifySyncRelationship, classifySyncRelationshipByIds, SyncConflictError } from "./session-sync-kernel.js";
+/** Narrow `backend.session()` to the optional ownership/export seam (the concrete TiDB/PG/Local stores carry it;
+ *  the bare in-memory dev store doesn't → the methods are optional, exactly like the fork route narrows). */
 function ownerAware(backend) {
     return backend.session();
 }
+/**
+ * EXPORT a session's whole portable state from `srcBackend` into a {@link SessionBundle} + a {@link BlobGetter}.
+ *
+ * - entries: `exportEntries(sessionId)` — `null` ⇒ the session does not exist ⇒ this returns `null` (no partial bundle).
+ * - snapshots: `listKeys(sessionId)` → for each key `exportManifest(scope,key)` → `{key, [...manifest]}`. A key whose
+ *   manifest reads back `null` (a concurrent reap between listKeys and exportManifest) is dropped, not exported empty.
+ * - policy: `listBySession(sessionId)` (empty `[]` if the store lacks the optional seam — honest degrade).
+ * - anchors: `listBySession(sessionId)` (empty `[]` if the store has no resumeAnchor seam).
+ * - getBlob: bound to the source `fileSnapshot().getBlob` so the importer can pull content-addressed bytes lazily.
+ *
+ * The OWNER is NOT exported (import re-stamps it, §9). The owner-scope GATE is the CALLER's (route P1d): this returns
+ * `null` ONLY for "session does not exist", never as an authz signal.
+ *
+ * NB (P1d-α): the HTTP PULL no longer uses this — it uses {@link exportSessionManifest} (entries lifted off the wire)
+ * + the keyset-paged `exportEntriesStream` NDJSON route so memory is bounded by ROW COUNT, not the whole-log array.
+ * exportSession (entries-inline) STAYS for the local same-process import path, P1d-β (PUSH), and the tests.
+ */
 export async function exportSession(sessionId, srcBackend) {
     const session = ownerAware(srcBackend);
+    // entries FIRST — null ⇒ no such session ⇒ no bundle at all (the route maps this to 404).
     const exportEntries = session.exportEntries?.bind(session);
     if (!exportEntries) {
+        // A backend whose session store lacks the export seam can't be a sync SOURCE (older/in-memory dev store). Treat as
+        // "nothing to export" rather than crash — the route already gates on the durable backend being present.
         return null;
     }
     const entries = await exportEntries(sessionId);
     if (entries === null)
-        return null;
+        return null; // session does not exist
+    // snapshots — listKeys → per-key manifest. exportManifest may be absent (no snapshot export seam) → no snapshots.
     const fs = srcBackend.fileSnapshot();
     const snapshots = [];
     if (typeof fs.listKeys === "function" && typeof fs.exportManifest === "function") {
@@ -21,32 +52,53 @@ export async function exportSession(sessionId, srcBackend) {
         for (const key of keys) {
             const manifest = await fs.exportManifest(sessionId, key);
             if (manifest === null)
-                continue;
+                continue; // raced reap between listKeys and exportManifest — skip (never an empty snapshot)
             snapshots.push({ key, manifest: [...manifest] });
         }
     }
+    // policy — every (principal, rules) record across ALL principals (E6 listBySession; optional → []).
     const policyStore = srcBackend.sessionPolicy();
     const policy = typeof policyStore.listBySession === "function"
         ? await policyStore.listBySession(sessionId)
         : [];
+    // anchors — every E18 resume anchor (eventId→entryId + source owner). resumeAnchor is REQUIRED on all backends.
     const anchorStore = srcBackend.resumeAnchor();
     const anchors = typeof anchorStore.listBySession === "function"
         ? await anchorStore.listBySession(sessionId)
         : [];
+    // getBlob — bound to the SOURCE snapshot store so the importer pulls bytes content-addressed (deduped), lazily.
+    // A source without getBlob (no blobs to move) supplies a getter that always returns undefined → snapshots with a
+    // missing blob fail the §10 validation below before any write (never a partial restore).
     const getBlobFn = fs.getBlob?.bind(fs);
     const getBlob = getBlobFn ? (hash) => getBlobFn(hash) : async () => undefined;
     return { bundle: { sessionId, entries, snapshots, policy, anchors }, getBlob };
 }
+/**
+ * P1d-α (PULL streaming, §15) — EXPORT a session's portable state as a {@link SessionManifest} (entries LIFTED OFF
+ * the wire) + a {@link BlobGetter}. Like {@link exportSession} but it does NOT load entry payloads: it reads the
+ * IDS-only projection via `listEntryIds` (`null` ⇒ no such session ⇒ this returns `null`), counts them, reads the
+ * current `leafId`, and builds snapshots/policy/anchors EXACTLY as exportSession does. The paired NDJSON
+ * `GET /sync/entries` route streams the entry payloads separately (keyset-paged → bounded memory), so a 1M-entry
+ * session's manifest stays small (ids + counts + the snapshot/policy/anchor metadata).
+ *
+ * The OWNER is NOT exported (import re-stamps it, §9). The owner-scope GATE is the CALLER's (route P1d): this returns
+ * `null` ONLY for "session does not exist". (Named exportSessionManifest, NOT exportManifest, to avoid the collision
+ * with `FileSnapshotStore.exportManifest`.)
+ */
 export async function exportSessionManifest(sessionId, srcBackend) {
     const session = ownerAware(srcBackend);
+    // entry IDS FIRST — null ⇒ no such session ⇒ no manifest (the route maps this to 404). A backend whose session store
+    // lacks the seam can't be a sync source (older/in-memory dev store) → treat as nothing to export.
     const listEntryIds = session.listEntryIds?.bind(session);
     if (!listEntryIds)
         return null;
     const entryIds = await listEntryIds(sessionId);
     if (entryIds === null)
-        return null;
+        return null; // session does not exist
+    // leafId — the session's current leaf (cache-bypassing single read). Absent seam / no leaf ⇒ null.
     const getLeafId = session.getLeafId?.bind(session);
     const leafId = getLeafId ? await getLeafId(sessionId) : null;
+    // snapshots / policy / anchors — IDENTICAL to exportSession (no entry payloads loaded anywhere here).
     const fs = srcBackend.fileSnapshot();
     const snapshots = [];
     if (typeof fs.listKeys === "function" && typeof fs.exportManifest === "function") {
@@ -54,7 +106,7 @@ export async function exportSessionManifest(sessionId, srcBackend) {
         for (const key of keys) {
             const manifest = await fs.exportManifest(sessionId, key);
             if (manifest === null)
-                continue;
+                continue; // raced reap between listKeys and exportManifest — skip (never an empty snapshot)
             snapshots.push({ key, manifest: [...manifest] });
         }
     }
@@ -66,6 +118,7 @@ export async function exportSessionManifest(sessionId, srcBackend) {
     const anchors = typeof anchorStore.listBySession === "function"
         ? await anchorStore.listBySession(sessionId)
         : [];
+    // getBlob — bound to the SOURCE snapshot store (content-addressed, lazy), exactly like exportSession.
     const getBlobFn = fs.getBlob?.bind(fs);
     const getBlob = getBlobFn ? (hash) => getBlobFn(hash) : async () => undefined;
     return {
@@ -73,16 +126,78 @@ export async function exportSessionManifest(sessionId, srcBackend) {
         getBlob,
     };
 }
+/**
+ * IMPORT a {@link SessionBundle} (+ its {@link BlobGetter}) into `dstBackend` under `bundle.sessionId`, re-stamping
+ * ownership to `importingPrincipal`. Returns the snapshot tally (imported vs honestly-skipped on a destination whose
+ * FileSnapshotStore lacks the importManifest seam — pre-1.141.0; core's InMemory/File NOW carry it, so a local dst
+ * imports snapshots for real).
+ *
+ * §10 FAIL-CLOSED VALIDATION runs FIRST — BEFORE any write:
+ *   1. `validateEntriesForImport(bundle.entries)` (the single core invariant gate: unique ids / parent-before-child /
+ *      one root / leaf-resolvable). Throws on violation; NOTHING is written.
+ *   2. Every blobHash referenced by every snapshot manifest MUST be supplied by `getBlob` — a missing blob would
+ *      restore a PARTIAL tree (files half-written, conversation whole → breaks the entry↔file lockstep). A lightweight
+ *      PRESENCE pre-check (fetch each distinct hash once, no hashing) fails FAST here; the AUTHORITATIVE content-address
+ *      integrity check (`sha256(bytes)===hash`) is done ONCE inside `importManifest` (core 1.141.0), so we don't double-
+ *      hash. (Runs only when the dst supports snapshot import; otherwise there is nothing to half-write.)
+ *
+ * §7 CLASSIFICATION GATE — BEFORE any write, the destination's CURRENT entry log is read and compared to the bundle
+ * via {@link classifySyncRelationship} (a sound entry-id SET comparison, not leaf_id). A `fork` (true divergence) or a
+ * `stale` source (the dst is strictly ahead) WOULD lose destination history → it throws {@link SyncConflictError}
+ * (route → 409) UNLESS the caller passes `{ resolution: "overwrite-dst" }`. An `identical` relation SKIPS the entries
+ * write entirely (the log is already present & equal; the idempotent snapshot/policy/anchor replay below still runs to
+ * heal anything missing). `fresh` / `fast_forward` (and an overwrite-resolved fork/stale) write the entries via the
+ * IDEMPOTENT {@link OwnerAwareSessionStore.replaceEntries} (purge-then-import) — NOT `importEntries`, whose plain
+ * INSERT crashes on a duplicate PK when the session already exists at the destination.
+ *
+ * §8 CROSS-STORE ATOMIC ORDER + IDEMPOTENCY — session_meta (written LAST inside `replaceEntries`) is the sole
+ * commit point, so a crash mid-import leaves orphan blobs/manifests/anchors with NO session_meta = invisible to
+ * wake (never a half-session, only collectable orphans). Order:
+ *   ① snapshots (manifests + content-addressed blobs) — content-addressed + create-once = idempotent retry-to-completion.
+ *      `importManifest` returns a {@link FileSnapshotResult} (NEVER throws — core 1.141.0); a `{ok:false}` (a
+ *      rejecting/missing/hash-mismatched blob the §10 pre-check didn't catch — e.g. a blob corrupted in transit) is
+ *      re-raised as a fail-closed THROW so the import aborts BEFORE the entries commit (no entry↔file split).
+ *   ② entries (`replaceEntries` runs the core gate AGAIN and writes session_meta LAST = the commit point; idempotent
+ *      over an existing session — skipped entirely when the relation is `identical`)
+ *   ③ policy (replay each record via putRules; `opts.operatorOk` defaults FALSE → the E6 tighten-only gate APPLIES, so
+ *      a replay that would LOOSEN an operator-tightened dst policy throws `SessionPolicyError("loosen_forbidden")` —
+ *      `operator:true` is set ONLY when the authenticated importer is itself a verified operator)
+ *   ④ anchors (owner RE-KEYED to `importingPrincipal`, §9)
+ * Steps ③/④ are post-commit; re-running them is idempotent — ③ SKIPS a put whose content already equals the dst row
+ * (a "no-op rev bump" is NOT idempotent: rev is the operator's optimistic-lock token — the A6 fix below), ④ is a
+ * same-value upsert — so a crash between ②–④ is recovered by a retry that converges to the same bytes.
+ *
+ * @param opts.resolution — `"overwrite-dst"` consents to a `fork`/`stale` import that overwrites destination history
+ *   (the user's keep-source decision); omitted ⇒ such an import is refused with {@link SyncConflictError}.
+ * @param opts.operatorOk — when `true`, the policy replay (step ③) is an OPERATOR write (may loosen the dst rules); set
+ *   ONLY when the AUTHENTICATED importer is a verified operator. DEFAULT false → the E6 tighten-only gate applies, so a
+ *   non-operator import is TIGHTEN-ONLY (design §4): a replay that would loosen an operator-tightened dst session policy
+ *   throws `SessionPolicyError("loosen_forbidden")`, which propagates (NOT swallowed) so the route can refuse the loosen.
+ */
 export async function importSession(bundle, getBlob, dstBackend, importingPrincipal, opts) {
     const sessionId = bundle.sessionId;
     const fs = dstBackend.fileSnapshot();
     const canImportSnapshots = typeof fs.importManifest === "function";
+    // ── §7 classification gate, BEFORE any write ───────────────────────────────────────────────────────────────
+    // Read the destination's CURRENT entry log and classify the relationship (sound entry-id set comparison). A fork or
+    // a stale source would lose dst history → refuse with a typed 409 unless the caller explicitly resolved overwrite-dst.
     const dstEntries = (await ownerAware(dstBackend).exportEntries?.(sessionId)) ?? null;
     const rel = classifySyncRelationship(bundle.entries, dstEntries);
     if ((rel.relation === "fork" || rel.relation === "stale") && opts?.resolution !== "overwrite-dst") {
-        throw new SyncConflictError(sessionId, rel);
+        throw new SyncConflictError(sessionId, rel); // 409 — surface the exclusive sets so the user picks keep-local/cloud
     }
+    // ── §10 fail-closed validation, BEFORE any write ────────────────────────────────────────────────────────────
+    // (1) entries invariants (the core gate). validateEntriesForImport throws on any violation; we discard its result
+    //     here (importEntries re-runs it as the authoritative write-time gate) — this is the early fail-closed check so
+    //     we never start writing snapshots for a session whose entries the gate will reject.
     validateEntriesForImport(bundle.entries);
+    // (2) every referenced blob must be fetchable — ONLY when the destination can actually import snapshots (otherwise
+    //     there is nothing to half-write, so a missing blob is moot; the snapshot is honestly skipped below). Fetch each
+    //     DISTINCT hash once (content-addressed) so a large manifest doesn't refetch. This is a lightweight PRESENCE
+    //     pre-check (fail-FAST before we write any entries) — the AUTHORITATIVE sha256 content-address integrity check is
+    //     done ONCE inside importManifest (core 1.141.0); we deliberately don't re-hash here to avoid double-hashing
+    //     a possibly-large blob set. The importManifest {ok:false} below is the backstop for anything the presence check
+    //     can't see (a blob present-but-corrupted-in-transit, a getBlob that rejects only on a later call).
     if (canImportSnapshots) {
         const distinct = new Set();
         for (const snap of bundle.snapshots)
@@ -95,6 +210,19 @@ export async function importSession(bundle, getBlob, dstBackend, importingPrinci
             }
         }
     }
+    // ── ⓪ overwrite-dst subsystem WIPE (fork/stale with explicit consent ONLY) ─────────────────────────────────
+    // "overwrite-dst" means the user chose KEEP-SOURCE — the result must be the SOURCE's state, not "the source's
+    // conversation + the destination's leftover policy/anchors/snapshots" (a MIXED state is worse than lost history:
+    // dangling anchors resolve onto purged entries, an abandoned branch's policy rows keep gating, and a shared-key
+    // snapshot keeps the dst's bytes because importManifest is create-once). So before replaying ①/③/④ we wipe the
+    // dst's per-session subsystem state. Crash-safety: the user consented to discarding the dst's state, and every
+    // wipe+replay leg is idempotent → a crash mid-wipe is recovered by the same retry-to-completion as §8's ②–④.
+    //   · snapshots: prefer the purge seam `deleteBySession` (SQL twins: manifests drop now, blobs go to the async
+    //     orphan GC); fall back to the core-REQUIRED `reap(scope, [])` (in-memory/file stores GC unreferenced blobs
+    //     inline — content-addressed, so blobs still referenced by other scopes survive).
+    //   · anchors / policy: `deleteBySession` where the store carries it — since core 1.423 that is EVERY in-tree
+    //     store (the seam is optional on core's SessionPolicyStore interface and implemented by its File/InMemory
+    //     stores too — [1796]§三 → [1801]; the feature-detect stays for third-party stores that predate the seam).
     const overwriting = (rel.relation === "fork" || rel.relation === "stale") && opts?.resolution === "overwrite-dst";
     if (overwriting) {
         const fsWipe = fs;
@@ -109,6 +237,14 @@ export async function importSession(bundle, getBlob, dstBackend, importingPrinci
         if (typeof policyWipe.deleteBySession === "function")
             await policyWipe.deleteBySession(sessionId);
     }
+    // ── §8 atomic order ─────────────────────────────────────────────────────────────────────────────────────────
+    // ① snapshots — content-addressed blobs + manifest, BEFORE session_meta. Feature-detect importManifest: ALL backends
+    //    now carry it (durable TiDB/PG + core's File/InMemory since 1.141.0) → a local dst imports snapshots for
+    //    real. The only remaining honest-degrade is a backend whose FileSnapshotStore predates the seam (none in-tree).
+    //    importManifest NEVER throws — it returns a FileSnapshotResult; a {ok:false} (rejecting/missing/hash-mismatched
+    //    blob — e.g. corrupted in transit) is re-raised here as a fail-closed THROW so we abort BEFORE the entries commit
+    //    (no entry↔file split). The whole import is the caller's transaction: a throw here means no session_meta is ever
+    //    written (the commit point is inside importEntries, step ②), so the dst stays clean (only collectable orphans).
     let snapshotsImported = 0;
     let snapshotsSkipped = 0;
     if (canImportSnapshots) {
@@ -122,8 +258,16 @@ export async function importSession(bundle, getBlob, dstBackend, importingPrinci
         }
     }
     else {
-        snapshotsSkipped = bundle.snapshots.length;
+        snapshotsSkipped = bundle.snapshots.length; // pre-1.141.0 dst — files pend the import seam; honest degrade (NOT a silent drop)
     }
+    // ② entries — core gate (again, authoritative) + session_meta LAST = the commit point. Owner = importingPrincipal
+    //    (NEVER the bundle's, §9). Written via the IDEMPOTENT replaceEntries (purge-then-import) — NOT importEntries,
+    //    whose plain INSERT crashes on a duplicate PK when the session already exists (fast-forward / overwrite-resolved
+    //    / a §8 retry). When the relation is `identical` the log is already present & equal → SKIP the entries write
+    //    entirely (the snapshot/policy/anchor replay below is idempotent and still runs to heal anything missing). A
+    //    destination without the replace seam can't accept a session at all → throw.
+    // 🔴 同上(`session-sync-content.ts` 顶注):`identical` 只说明 id 集合相等,不说明内容相同。这条路上
+    // `bundle.entries` 与目的端日志都在手上 ⇒ 直接比内容摘要;不符就照常改写(不抛错、不 409)。
     const dstEntriesForContent = await ownerAware(dstBackend).exportEntries?.(sessionId).catch(() => null) ?? null;
     const contentEqual = rel.relation === "identical" && identicalIdsAlsoIdenticalContent(bundle.entries, dstEntriesForContent);
     if (rel.relation !== "identical" || !contentEqual) {
@@ -134,24 +278,53 @@ export async function importSession(bundle, getBlob, dstBackend, importingPrinci
         }
         await replaceEntries(sessionId, importingPrincipal, bundle.entries);
     }
+    // ③ policy — replay each (principal, rules) record VERBATIM. The E6 tighten-only gate is the security boundary here:
+    //    we do NOT pass operator:true unconditionally (a non-operator pushing a client-controlled bundle could otherwise
+    //    LOOSEN an operator-tightened dst session policy — the loosen the E6 route refuses). `opts.operatorOk` defaults
+    //    FALSE → the tighten gate applies, so a TIGHTEN-ONLY import succeeds (design §4 "merge tighten-only") and a
+    //    loosening replay throws SessionPolicyError("loosen_forbidden") — which we do NOT swallow; it propagates to the
+    //    route so the malicious loosen is refused (entries may already have committed: the conversation syncs, only the
+    //    loosen is refused = the correct fail-closed outcome). operator:true ONLY when the AUTHENTICATED importer is a
+    //    verified operator. principal is carried VERBATIM (NOT re-keyed to importingPrincipal): the policy `principal` is
+    //    the per-TASK rule-owner key (`spec.principal`), not the session owner, so re-keying would collapse distinct
+    //    per-principal rows and could clobber. The session-wide row (principal=undefined) stays session-wide and still
+    //    applies to the new owner.
+    //    IDEMPOTENT REPLAY (the A6 fix): a put whose content (rev stripped, normalized) already equals the dst row is
+    //    SKIPPED — putRules bumps `rev` on every write, and `rev` is the optimistic-lock token operators hold for
+    //    read-modify-write. Without the skip, every §8 crash-retry (and every harmless duplicate sync) advances every
+    //    row's rev while changing nothing ⇒ the operator's next putRules({expectedRev}) throws `conflict` on rules whose
+    //    content never moved. With it, retry-after-crash converges to the same BYTES as a single clean run, which is
+    //    what "steps ③/④ are idempotent" (§8 above) actually has to mean. normalizeRules gives both sides the same
+    //    canonical field order/shape, so JSON.stringify is a sound equality here (array ORDER is significant on purpose:
+    //    a reordered list is a different stored byte-state and must be written).
     const policyStore = dstBackend.sessionPolicy();
     const canonRules = (r) => JSON.stringify(normalizeRules(stripRev(r)));
     for (const rec of bundle.policy) {
         const cur = await policyStore.getRules(sessionId, rec.principal);
         if (cur !== null && canonRules(cur) === canonRules(rec.rules))
-            continue;
+            continue; // content already identical — don't touch rev
         await policyStore.putRules(sessionId, rec.principal, rec.rules, { operator: opts?.operatorOk === true });
     }
+    // ④ anchors — owner RE-KEYED to importingPrincipal (§9): the E18 owner-guard resolves under the NEW owner so
+    //    rewind-to-message keeps working post-move (the source owner, e.g. local null, would never resolve in the cloud).
     const anchorStore = dstBackend.resumeAnchor();
     for (const a of bundle.anchors) {
         await anchorStore.put(sessionId, a.eventId, a.entryId, importingPrincipal);
     }
     return { snapshotsImported, snapshotsSkipped, relation: rel.relation };
 }
+/**
+ * §7 DRY-RUN — classify what importing `sessionId` from `srcBackend` into `dstBackend` WOULD do, WITHOUT writing
+ * anything. The route (P1d) calls this to surface a conflict (fork/stale) to the user BEFORE committing an
+ * {@link importSession} (so the shell can present a keep-local / keep-cloud / fork-new choice up front).
+ *
+ * Returns `null` when the SOURCE session does not exist (no bundle to plan); otherwise the {@link SyncRelation}
+ * between the source's full durable log and the destination's current log (a `null` dst log ⇒ `fresh`). No writes.
+ */
 export async function planSync(sessionId, srcBackend, dstBackend) {
     const srcEntries = (await ownerAware(srcBackend).exportEntries?.(sessionId)) ?? null;
     if (srcEntries === null)
-        return null;
+        return null; // no such source session — nothing to plan (the route maps this to 404)
     const dstEntries = (await ownerAware(dstBackend).exportEntries?.(sessionId)) ?? null;
     return classifySyncRelationship(srcEntries, dstEntries);
 }

package/dist/session-titler.d.ts

@@ -1,7 +1,31 @@
+/**
+ * Auto-generated session titles.
+ *
+ * SHAPE: fire-and-forget at FIRST task submit for a session (the objective is known then — no need to wait
+ * for the run to finish, and the web Recents gets the title sooner). Write-once (`setTitleIfNull`, store-side
+ * `WHERE title IS NULL`) — the USER-facing rename lives BFF-side as a label overlay (user label wins
+ * over engine title, two layers never fight). Generation = one cheap-model one-liner via the deployment's
+ * hookLlm face (summarize role → MODEL_CHEAP_ID when configured, else the main model; bounded + timed out).
+ *
+ * FAILURE POSTURE: everything is best-effort — a generation/store failure logs and leaves title null (the
+ * list falls back to objectivePreview). An in-process pending set dedupes concurrent submits on the same
+ * session; the store's IS NULL guard closes the cross-replica race (double generation costs one extra cheap
+ * call at worst, and exactly one title lands).
+ */
 export interface SessionTitlerDeps {
+    /** Secret scrub applied to the RAW llm text before sanitize/persist (workflow audit 2026-07-13: the
+     *  objective may carry a pasted secret and the model can echo it into the title — titles are persisted,
+     *  listed over HTTP, and logged, all outside the trace redact pipeline; wire src/trace/redact.ts here). */
     redact?: (text: string) => string;
+    /** Write-once store leg (SQL twins / local sidecar). Resolves false when a title already existed. */
     setTitleIfNull(sessionId: string, title: string): Promise<boolean>;
+    /** Cheap pre-LLM probe: "titled" = skip (a restart/evicted-seen/another replica
+     *  already paid — don't re-spend an LLM call); "untitled" = generate; "none" = the session_meta row hasn't
+     *  been REGISTERED yet (createRun fires before the Runner's session acquire) — retry after a grace window,
+     *  and if still absent, release the seen slot so the NEXT submit retries (never a permanently-untitled
+     *  session via a swallowed early UPDATE-0). Local lane has no row-existence dimension → never "none". */
     probeTitle(sessionId: string): Promise<"none" | "untitled" | "titled">;
+    /** The deployment's cheap one-shot LLM face (main.ts hookLlm — summarize role default). */
     llm(opts: {
         prompt: string;
         timeoutMs: number;
@@ -22,9 +46,11 @@ export interface SessionTitlerDeps {
     };
 }
 export interface SessionTitler {
+    /** Fire-and-forget: maybe generate + persist a title for this session. Never throws, never blocks the caller. */
     maybeTitle(sessionId: string, objective: string): void;
 }
 export declare const TITLE_MAX_CHARS = 80;
+/** Single line, control chars stripped, hard cap; surrounding quotes (a common LLM tic) trimmed. */
 export declare function sanitizeTitle(raw: string): string;
 export declare function buildTitlePrompt(objective: string): string;
 export declare function createSessionTitler(deps: SessionTitlerDeps): SessionTitler;