Gate JSDoc completeness on every package export

New doc-sync gate verify-export-jsdoc walks every module-level exported
name under packages/*/*/src and requires description prose everywhere,
plus @param per parameter and @returns on non-void annotated returns for
function-like exports, public class methods, properties, and accessors.
The parsing + check helpers move out of gen-cordis-catalog.ts into a
shared scripts/jsdoc.ts so 'documented' means one thing on both gated
surfaces.

Deliberate exemptions (documented in the RFC): heritage-declared class
members (the seam declaration is the doc's one home — the one checker
query in an otherwise pure-AST walk), cordis plugin-protocol slots
(name/inject/reusable/Config/apply, top-level and static), constructors,
overload implementations, declare-module augmentation bodies, and
re-export statements (checked at the defining module).

The 203 under-documented exports the gate found at adoption are filled
in this change, so the gate lands green; generated catalogs/graphs are
regenerated for the shifted line pointers.

RFC: docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md

packages/session-persistence/session-persistence-jsonl/src/format.ts

@@ -27,7 +27,11 @@ export interface HeaderLine {
   seedLength?: number
 }
 
-/** Build the header line object from a {@link SessionHeader}. */
+/**
+ * Build the header line object from a {@link SessionHeader}.
+ * @param header - the immutable session metadata to serialize.
+ * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
+ */
 export function toHeaderLine(header: SessionHeader): HeaderLine {
   return {
     type: 'session',
@@ -40,7 +44,11 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
   }
 }
 
-/** Parse a header line back into a {@link SessionHeader}. */
+/**
+ * Parse a header line back into a {@link SessionHeader}.
+ * @param line - the shape-checked first line of a log (see the `isHeaderLine` guard).
+ * @returns the header, absent optional fields omitted.
+ */
 export function fromHeaderLine(line: HeaderLine): SessionHeader {
   return {
     version: line.version,
@@ -77,6 +85,8 @@ function isHeaderLine(value: unknown): value is HeaderLine {
  * `Buffer.from(…, 'utf8')` would do, breaking injectivity). `.` is in the safe
  * set for readability but the whole-segment tokens `.`/`..` are escaped so they
  * can never traverse.
+ * @param raw - the string to encode; must be non-empty (throws on `''`).
+ * @returns the escaped single path segment, decodable back to `raw`.
  */
 export function encodeSegment(raw: string): string {
   if (raw.length === 0) throw new Error('cannot encode an empty path segment')
@@ -97,9 +107,12 @@ export function encodeSegment(raw: string): string {
 
 /**
  * The directory a session's files live in: the configured root, then a per-cwd
- * subdirectory so sessions group by project. The cwd subdir is a stable hash
- * (short, collision-resistant, filesystem-safe) plus an encoded suffix for
- * readability; sessions without a cwd go in a shared `_no-cwd` bucket.
+ * subdirectory so sessions group by project. The cwd subdir is a stable hash of
+ * the cwd (short, collision-resistant, filesystem-safe); sessions without a
+ * cwd go in a shared `_no-cwd` bucket.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory; `undefined` selects the shared `_no-cwd` bucket.
+ * @returns the per-cwd bucket directory path under `root`.
  */
 export function sessionDir(root: string, cwd: string | undefined): string {
   if (cwd === undefined) return join(root, '_no-cwd')
@@ -107,12 +120,22 @@ export function sessionDir(root: string, cwd: string | undefined): string {
   return join(root, `cwd-${hash}`)
 }
 
-/** The append-only event-log file path for a session. */
+/**
+ * The append-only event-log file path for a session.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory (picks the per-cwd bucket; `undefined` → `_no-cwd`).
+ * @param id - the session id, path-encoded via {@link encodeSegment} before filesystem use.
+ * @returns the session's `.jsonl` log file path.
+ */
 export function logPath(root: string, cwd: string | undefined, id: SessionId): string {
   return join(sessionDir(root, cwd), `${encodeSegment(id)}.jsonl`)
 }
 
-/** Serialize one event as a JSONL line (no trailing newline). */
+/**
+ * Serialize one event as a JSONL line (no trailing newline).
+ * @param event - the event to serialize verbatim.
+ * @returns the event's single-line JSON text; the writer adds the newline.
+ */
 export function eventLine(event: SessionEvent): string {
   return JSON.stringify(event)
 }
@@ -135,6 +158,9 @@ export function eventLine(event: SessionEvent): string {
  * This relies on the session-log invariant that every event lives inside a turn
  * (`Session.append` enforces it): only the final turn can be open, so the
  * preserved tail is at most one unclosed turn.
+ * @param buffer - the raw bytes of the log file (header line first).
+ * @returns the header, the preserved event prefix, and `committedBytes` — the
+ *   byte offset the next append truncates any torn tail to.
  */
 export function scanLog(buffer: Buffer): { meta: SessionHeader; events: SessionEvent[]; committedBytes: number } {
   const text = buffer.toString('utf8')
@@ -239,6 +265,8 @@ export function scanLog(buffer: Buffer): { meta: SessionHeader; events: SessionE
  * `undefined` if it is missing/not a header. Used by `list()` to read session
  * metadata WITHOUT parsing the whole log: a session picker scales with the
  * number of sessions, not the total size of every conversation.
+ * @param firstLine - the first line of a log file (without its trailing newline).
+ * @returns the parsed header, or `undefined` when the line is not a well-formed session header.
  */
 export function parseHeaderMeta(firstLine: string): SessionHeader | undefined {
   let parsed: unknown

packages/session-persistence/session-persistence-jsonl/src/index.ts

@@ -31,6 +31,7 @@ import {
   encodeSegment, eventLine, logPath, parseHeaderMeta, scanLog, sessionDir, toHeaderLine,
 } from './format.ts'
 
+/** Plugin config: where the JSONL backend keeps its session logs (`root` is required — no default). */
 export interface Config {
   /**
    * Root directory for all session files. Required (no default): a default of

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -76,6 +76,9 @@ export type JournalMode = 'wal' | 'delete' | 'truncate' | 'persist'
  * is the merged layout carrying every column; bumping past the collided v3
  * makes the version check reject both sibling v3 databases instead of opening
  * one against columns it does not have.
+ * @param path - the SQLite database file to open (created when absent).
+ * @param journalMode - the journal pragma to apply — a closed in-code union, validated by the plugin Config.
+ * @returns the open handle with pragmas applied and both tables ensured.
  */
 export function openDatabase(path: string, journalMode: JournalMode): DatabaseSync {
   const db = new DatabaseSync(path)
@@ -120,7 +123,11 @@ export function openDatabase(path: string, journalMode: JournalMode): DatabaseSy
   return db
 }
 
-/** Reconstruct the {@link SessionHeader} from a `sessions` row. */
+/**
+ * Reconstruct the {@link SessionHeader} from a `sessions` row.
+ * @param row - the `sessions` table row.
+ * @returns the header, `NULL` columns mapped to omitted optional fields.
+ */
 export function rowToMeta(row: SessionRow): SessionHeader {
   return {
     version: row.version,
@@ -132,7 +139,12 @@ export function rowToMeta(row: SessionRow): SessionHeader {
   }
 }
 
-/** Reconstruct a {@link SessionEvent} from an `events` row (parses `data`). */
+/**
+ * Reconstruct a {@link SessionEvent} from an `events` row (parses `data`).
+ * @param row - the `events` table row; `data` and the surface columns hold JSON text.
+ * @returns the reconstructed event; throws when a JSON column fails to parse
+ *   ({@link scanRows} treats that as a hole, not corruption, in the tail).
+ */
 export function rowToEvent(row: EventRow): SessionEvent {
   // Surface-metadata fields are conditional on the event type in the type
   // system; spread them so each variant gets only the fields it declares.
@@ -172,6 +184,9 @@ export function rowToEvent(row: EventRow): SessionEvent {
  * This relies on the session-log invariant that every event lives inside a turn
  * (`Session.append` enforces it): only the final turn can be open, so the
  * preserved tail is at most one unclosed turn.
+ * @param rows - one session's event rows, ordered by seq ascending.
+ * @returns the preserved event prefix, plus `tornFrom` — the seq the physical
+ *   delete starts at — when a torn tail exists.
  */
 export function scanRows(rows: readonly EventRow[]): { preserved: SessionEvent[]; tornFrom?: number } {
   // Pass 1: parse each row's data; a row whose data is not valid JSON is a hole.

packages/session-persistence/session-persistence/src/coordinator.ts

@@ -186,6 +186,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Register a new session's metadata (lazy: no physical write until the first
    * {@link append}). Rejects if the id is already tracked or already persisted.
+   * @param meta - the immutable header (id, version, cwd, lineage) to record; snapshotted at call time.
    */
   create(meta: SessionHeader): Promise<void> {
     // Snapshot the metadata at call time: the op runs later (behind the
@@ -216,6 +217,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
   /**
    * Durably persist a batch of events. Honors the append-only and contiguous-seq
    * contracts; rejects non-JSON-serializable `event.data`.
+   * @param id - the session the batch belongs to.
+   * @param events - the contiguous batch to persist, in seq order; deep-cloned at call time.
    */
   async append(id: SessionId, events: readonly SessionEvent[]): Promise<void> {
     // Validate serializability BEFORE cloning so a bad event surfaces the typed
@@ -252,6 +255,8 @@ export class PersistenceCoordinator<TornMarker = unknown> {
    * Reload a session: its {@link SessionHeader} plus the event log up to the last
    * durable checkpoint, with any interrupted final turn durably closed (synthetic
    * boundary events) during load.
+   * @param id - the persisted session to reload.
+   * @returns the header plus the event log, ending on a balanced `turn/end`.
    */
   load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
     return this.serialize(id, () => this.loadCore(id))

packages/session-persistence/session-persistence/src/index.ts

@@ -45,6 +45,9 @@ declare module 'cordis' {
  *
  * The comparison includes the full event payload, not just seq/type/time, so a
  * mutated seed cannot be grafted onto a durable log with the same envelope.
+ * @param seed - the live session's creation-time event snapshot.
+ * @param prefix - the persisted prefix the seed must reproduce.
+ * @returns `true` when the prefix fits within the seed and every event matches by JSON text.
  */
 export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly SessionEvent[]): boolean {
   return prefix.length <= seed.length
@@ -58,6 +61,7 @@ export function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly
  * Reject non-JSON-serializable event data before a backend serializes a batch.
  * Live session appends already enforce this; persistence append paths also
  * accept replay/fork batches that may bypass a live session instance.
+ * @param events - the batch to validate; throws naming the offending event's type and seq.
  */
 export function assertSerializable(events: readonly SessionEvent[]): void {
   for (const event of events) {