@druumen/sessions-db 0.1.0

package/types/storage.d.mts

@@ -0,0 +1,276 @@
+/**
+ * Build a canonical event. Auto-fills `ts` (ISO ms) and `event_id`
+ * (UUIDv7 with `evt_` prefix — same generator as session IDs but with a
+ * different prefix so naive lookups can distinguish them).
+ *
+ * @param {{ op: string, stable_id: string, payload?: object,
+ *   ts?: string, event_id?: string }} input
+ */
+export function newEvent({ op, stable_id, payload, ts, event_id }: {
+    op: string;
+    stable_id: string;
+    payload?: object;
+    ts?: string;
+    event_id?: string;
+}): {
+    ts: string;
+    event_id: string;
+    op: string;
+    stable_id: string;
+    payload: any;
+};
+/**
+ * Append an event to events.jsonl. **No lock** — relies on POSIX O_APPEND
+ * atomicity for concurrent multi-process append safety, which is only
+ * guaranteed for writes ≤ PIPE_BUF (4 KiB). We enforce that bound via
+ * MAX_EVENT_BYTES and reject oversized events instead of silently risking
+ * interleave.
+ *
+ * @param {object} event
+ * @param {{ paths?: typeof PATHS, root?: string }} [opts]
+ * @throws {Error} when the serialized line exceeds MAX_EVENT_BYTES — caller
+ *   must reduce payload size or split into multiple smaller events.
+ */
+export function appendEvent(event: object, opts?: {
+    paths?: typeof PATHS;
+    root?: string;
+}): Promise<void>;
+/**
+ * Read events.jsonl into structured `{ events, corruptions }` output.
+ *
+ * Distinguishes two corruption modes:
+ *  - tail_partial: malformed line is the last non-empty line of the file —
+ *    almost always a write-in-progress (writer crashed or we read mid-write).
+ *    Tolerated; surfaced in `corruptions` for diagnostics but does not block
+ *    rebuild.
+ *  - middle_corruption: malformed line has at least one valid line after it
+ *    in the file. This implies real data damage (filesystem error, partial
+ *    overwrite, manual edit). Surfaced as a fatal corruption that callers
+ *    (rebuildProjection) escalate to an exception.
+ *
+ * @param {{ paths?: typeof PATHS, root?: string }} [opts]
+ * @returns {{ events: Array<object>, corruptions: Array<{
+ *   lineNumber: number, kind: 'tail_partial'|'middle_corruption',
+ *   tolerated: boolean, excerpt: string, error: string }> }}
+ */
+export function readAllEvents(opts?: {
+    paths?: typeof PATHS;
+    root?: string;
+}): {
+    events: Array<object>;
+    corruptions: Array<{
+        lineNumber: number;
+        kind: "tail_partial" | "middle_corruption";
+        tolerated: boolean;
+        excerpt: string;
+        error: string;
+    }>;
+};
+/**
+ * Load the projection cache from disk. On missing/corrupt file, falls back
+ * to a full rebuild from events.jsonl.
+ *
+ * @param {{ paths?: typeof PATHS, root?: string }} [opts]
+ * @returns {Promise<object>}
+ */
+export function loadProjection(opts?: {
+    paths?: typeof PATHS;
+    root?: string;
+}): Promise<object>;
+/**
+ * Atomically write the projection cache.
+ *
+ * Default behavior acquires the file lock around the entire write. Callers
+ * that already hold the lock (e.g. `tryUpdateProjection`'s read-modify-write
+ * cycle) pass `withLock: false` to avoid double-acquire deadlock.
+ *
+ * Steps (with lock):
+ *  1. Acquire the file lock
+ *  2. Write to `<projection>.tmp.<pid>`
+ *  3. fsync the tmp file
+ *  4. rename tmp → real (atomic on POSIX)
+ *  5. Release the lock
+ *
+ * On any error, attempts to clean up the tmp file before propagating.
+ *
+ * @param {object} projection
+ * @param {{ paths?: typeof PATHS, root?: string,
+ *   lockTimeoutMs?: number, lockRetryMs?: number,
+ *   withLock?: boolean }} [opts]
+ */
+export function saveProjection(projection: object, opts?: {
+    paths?: typeof PATHS;
+    root?: string;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+    withLock?: boolean;
+}): Promise<void>;
+/**
+ * Full rebuild: scan events.jsonl, fold into a fresh projection, persist.
+ *
+ * Returns `toleratedCorruptions` so callers can surface diagnostics
+ * (tail-partial lines from interrupted writes are common during heavy
+ * concurrent load and worth observing). Middle-line corruption escalates
+ * to a thrown error from `readAllEventsOrThrow` and never reaches here.
+ *
+ * @param {{ paths?: typeof PATHS, root?: string,
+ *   lockTimeoutMs?: number, lockRetryMs?: number }} [opts]
+ * @returns {Promise<{ sessionCount: number, eventCount: number,
+ *   toleratedCorruptions: number }>}
+ */
+export function rebuildProjection(opts?: {
+    paths?: typeof PATHS;
+    root?: string;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+}): Promise<{
+    sessionCount: number;
+    eventCount: number;
+    toleratedCorruptions: number;
+}>;
+/**
+ * Best-effort incremental update for hook callers.
+ *
+ * Pattern (from Phase 1 ticket §"Hook caller pattern"):
+ *   1. Build event with newEvent()
+ *   2. Append it to events.jsonl FIRST via O_APPEND (race-safe SSoT)
+ *   3. Acquire the projection lock and run the full read-modify-write under
+ *      the lock so concurrent hooks cannot read the same baseline projection
+ *      and clobber each other's derived state.
+ *   4. If anything fails, return `{ ok: false, error }` — the SSoT is
+ *      already consistent, so the next rebuild reconciles the projection.
+ *
+ * @param {object} event
+ * @param {{ paths?: typeof PATHS, root?: string,
+ *   lockTimeoutMs?: number, lockRetryMs?: number }} [opts]
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export function tryUpdateProjection(event: object, opts?: {
+    paths?: typeof PATHS;
+    root?: string;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+}): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * Atomic transaction for `session_seen` events.
+ *
+ * Why a dedicated entry point instead of "lookup → mint → tryUpdateProjection"?
+ *
+ * The hook's old flow ran `loadProjection` outside the lock to look up an
+ * existing stable_id by claude_session_id, minted a fresh one on miss, built
+ * the event with that stable_id, then handed the event to
+ * `tryUpdateProjection`. With two concurrent hooks for the SAME
+ * claude_session_id, both would observe an empty projection during the
+ * unlocked lookup, both mint different stable_ids, both append events under
+ * different stable_ids, and the projection would split into two records
+ * for the same logical session.
+ *
+ * P3 (this phase) extends the resolution from "claude_session_id only" to
+ * the full 3-priority chain implemented in `identity.mjs`:
+ *
+ *   1. claude_session_id_index (exact)         — baseline P2 behavior
+ *   2. transcript_lineage (high)               — covers fork/resume
+ *   3. fingerprint_corroborator (low)          — soft cross-session match
+ *
+ * On any miss → mint via uuidv7. Fingerprint matches without enough
+ * corroborators are surfaced as `parent_candidate_ids[]` (hub-spoke hints —
+ * NOT auto-promoted to parent_session_id).
+ *
+ * Critical-section flow (held under projection lock end-to-end):
+ *
+ *   1. Acquire projection lock
+ *   2. Load projection inside lock
+ *   3. Run resolveIdentity() against the baseline projection (P1→P2→P3→mint)
+ *   4. Call `payloadBuilder(stableId, identityResolution)` for the payload
+ *   5. Auto-inject `identity_resolution` + merged `parent_candidate_ids`
+ *      into the payload so the audit trail is always present
+ *   6. Build canonical event via `newEvent`
+ *   7. Append event to events.jsonl
+ *   8. Apply event to in-memory projection
+ *   9. Save projection (under same lock — pass `withLock: false`)
+ *  10. Release lock
+ *
+ * The `payloadBuilder` callback receives both `stableId` and the full
+ * `identityResolution` object; callers may inspect/override the audit
+ * fields, but if they leave `payload.identity_resolution` undefined we
+ * inject it ourselves. `parent_candidate_ids` is merged additively so a
+ * caller-supplied list (rare; mostly the projection's own derivation) is
+ * preserved.
+ *
+ * Privacy: pass `opts.storeFirstPrompt: false` to clear the
+ * `first_prompt_preview` field on the persisted payload (whatever the
+ * payloadBuilder returned is overwritten with `null`). Default `true`
+ * preserves the pre-0.1.0 behavior. Sanitization, fingerprints, and
+ * transcript_files meta are NOT affected — only the human-readable preview
+ * is stripped, so identity reconciliation still works for opt-out users.
+ *
+ * @param {{
+ *   claudeSessionId: string,
+ *   payloadBuilder: (stableId: string, identityResolution?: object) => object,
+ *   transcriptMeta?: object|null,
+ *   gitContext?: object|null,
+ *   cwd?: string|null,
+ *   fingerprints?: { first_human_prompt_v1?: string|null, lineage_prefix_v1?: string|null }|null,
+ *   now?: number,
+ *   timeWindowHours?: number,
+ *   minCorroborators?: number,
+ *   storeFirstPrompt?: boolean,
+ *   paths?: typeof PATHS,
+ *   root?: string,
+ *   lockTimeoutMs?: number,
+ *   lockRetryMs?: number,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, stableId?: string, eventId?: string,
+ *   minted?: boolean, identityResolution?: object, error?: string }>}
+ */
+export function recordSessionSeen(opts: {
+    claudeSessionId: string;
+    payloadBuilder: (stableId: string, identityResolution?: object) => object;
+    transcriptMeta?: object | null;
+    gitContext?: object | null;
+    cwd?: string | null;
+    fingerprints?: {
+        first_human_prompt_v1?: string | null;
+        lineage_prefix_v1?: string | null;
+    } | null;
+    now?: number;
+    timeWindowHours?: number;
+    minCorroborators?: number;
+    storeFirstPrompt?: boolean;
+    paths?: typeof PATHS;
+    root?: string;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+}): Promise<{
+    ok: boolean;
+    stableId?: string;
+    eventId?: string;
+    minted?: boolean;
+    identityResolution?: object;
+    error?: string;
+}>;
+/**
+ * Hard cap on a single event's serialized size (line bytes including the
+ * trailing newline). Set to 4 KiB — the conservative POSIX `PIPE_BUF` lower
+ * bound that guarantees `O_APPEND + write(2)` is atomic on regular files
+ * across concurrent writers. Larger payloads risk write interleave on some
+ * filesystems even with O_APPEND, so we reject them up front and force the
+ * caller to chunk or trim instead of corrupting events.jsonl.
+ *
+ * Exported so callers (sanitize layer, transcript reader, hook composers)
+ * can pre-check before constructing events.
+ */
+export const MAX_EVENT_BYTES: 4096;
+/**
+ * Default on-disk paths. Resolved against `process.cwd()` so callers that
+ * run from the workspace root see the canonical layout. Tests pass an
+ * `opts.paths` override to write to a tmpdir.
+ */
+export const PATHS: Readonly<{
+    eventsJsonl: "tickets/_logs/sessions-db-events.jsonl";
+    projectionJson: "tickets/_logs/sessions-db.json";
+    lockFile: "tickets/_logs/sessions-db.lock";
+}>;

package/types/sweep.d.mts

@@ -0,0 +1,58 @@
+/**
+ * Compute desired activity_state transitions for all sessions in a projection.
+ *
+ * @param {object} projection
+ * @param {{
+ *   now?: number,
+ *   idleThresholdDays?: number,
+ *   archiveThresholdDays?: number,
+ * }} [opts]
+ * @returns {Array<{
+ *   stable_id: string,
+ *   from_state: string,
+ *   to_state: string,
+ *   effective_last_progress: string,
+ *   age_days: number,
+ * }>}
+ */
+export function computeSweepTransitions(projection: object, opts?: {
+    now?: number;
+    idleThresholdDays?: number;
+    archiveThresholdDays?: number;
+}): Array<{
+    stable_id: string;
+    from_state: string;
+    to_state: string;
+    effective_last_progress: string;
+    age_days: number;
+}>;
+/**
+ * Compute the effective "last progress" timestamp for a session — the max
+ * (latest) ISO 8601 timestamp across:
+ *   - session.last_progress_at
+ *   - session.transcript_files[*].mtime
+ *   - session.hive_watcher_last_seen   (future hive-watcher integration)
+ *
+ * Returns the epoch ISO string when no candidate is parseable.
+ *
+ * Implementation note (codex P5 round-1 fix): we MUST parse each candidate
+ * to epoch ms and compare numerically, then re-emit a normalized ISO 8601
+ * (Z) string. A naive lexicographic `candidates.sort().pop()` only works
+ * when every candidate is uniformly Z-suffixed with identical fractional
+ * precision — and that invariant is fragile in practice:
+ *   - transcript_files[*].mtime is sourced from the local fs `Stats.mtime`
+ *     and gets ISO-stringified at write time; on a host with non-UTC
+ *     TZ env the stringifier may emit `+02:00` offsets.
+ *   - hive_watcher_last_seen comes from a different writer with its own
+ *     formatter (sub-millisecond precision possible).
+ *   - operator-supplied --json fixtures may carry mixed precisions.
+ * Lex-sorting `2026-05-09T05:00:00+02:00` against `2026-05-09T04:00:00.000Z`
+ * picks the wrong winner; lex-sorting `...100Z` against `...100.500Z`
+ * picks the SHORTER string as larger because `0` < `5` at position 23 once
+ * the lengths diverge. Both are silent miscategorization → wrong sweep
+ * verdict. Date.parse() canonicalizes everything to a single epoch axis.
+ *
+ * @param {object} session
+ * @returns {string} ISO 8601 timestamp (always Z, normalized)
+ */
+export function computeEffectiveLastProgress(session: object): string;

package/types/transcript.d.mts

@@ -0,0 +1,59 @@
+/**
+ * @typedef {{
+ *   sessionId: string|null,
+ *   firstUuid: string|null,
+ *   lastUuid: string|null,
+ *   firstParentUuid: string|null,
+ *   recordCount: number,
+ *   firstHumanPromptRaw: string|null,
+ *   cwd: string|null,
+ *   gitBranch: string|null,
+ *   size: number,
+ *   mtime: Date,
+ *   status: 'ok' | 'corrupted' | 'too_large',
+ * }} TranscriptMeta
+ */
+/**
+ * Convert an absolute filesystem path to the dash-encoded workspace hash that
+ * Claude Code uses for the `~/.claude/projects/<hash>/` directory name. The
+ * encoding replaces every path separator and dot with a dash and keeps the
+ * leading dash that Claude Code itself prepends.
+ *
+ * @param {string} cwd absolute path
+ * @returns {string} e.g. `-Users-zm-leng-Documents-...-drummen-com-cn`
+ */
+export function workspaceHashFromCwd(cwd: string): string;
+/**
+ * List every `.jsonl` transcript in a workspace's Claude Code directory,
+ * sorted by mtime descending (newest first). Returns absolute paths.
+ *
+ * @param {string} workspaceHash dash-encoded hash, OR an absolute path that
+ *   we will hash for you.
+ * @returns {string[]}
+ */
+export function listTranscriptFiles(workspaceHash: string): string[];
+/**
+ * Parse a single Claude Code transcript jsonl file and return its identity +
+ * lineage metadata. Streams the file line-by-line; never loads the whole
+ * thing into memory.
+ *
+ * @param {string} path absolute path to the jsonl file
+ * @param {{ maxSizeMb?: number }} [opts]
+ * @returns {Promise<TranscriptMeta>}
+ */
+export function parseTranscriptFile(path: string, opts?: {
+    maxSizeMb?: number;
+}): Promise<TranscriptMeta>;
+export type TranscriptMeta = {
+    sessionId: string | null;
+    firstUuid: string | null;
+    lastUuid: string | null;
+    firstParentUuid: string | null;
+    recordCount: number;
+    firstHumanPromptRaw: string | null;
+    cwd: string | null;
+    gitBranch: string | null;
+    size: number;
+    mtime: Date;
+    status: "ok" | "corrupted" | "too_large";
+};

package/types/types.d.mts

@@ -0,0 +1,255 @@
+/**
+ * Sessions-db stable identifier — `sess_<uuidv7-with-dashes>`.
+ * See `uuid.mjs` `generateSessionId()` / `isSessionId()`.
+ */
+export type SessionStableId = string;
+/**
+ * Claude Code's per-process session UUID (canonical 8-4-4-4-12, v4).
+ * Read from the SessionStart hook payload's `session_id` field.
+ */
+export type ClaudeSessionId = string;
+/**
+ * events.jsonl per-row identifier — `evt_<uuidv7-with-dashes>`.
+ * Same generator as SessionStableId, different prefix (so visual scans of
+ * the jsonl tail can tell event ids from session ids).
+ */
+export type EventId = string;
+/**
+ * ISO 8601 timestamp string (UTC `Z` suffix preferred, but offset forms
+ * are accepted on input — sweep + projection consumers parse via
+ * `Date.parse` not lex compare). All sessions-db writers emit `Z`.
+ */
+export type Iso8601 = string;
+/**
+ * Activity state machine (sweep-driven).
+ *
+ *   active   — fresh session OR within idle threshold (default 14d)
+ *   idle     — past idle threshold but within archive threshold (default 30d)
+ *   archived — past archive threshold (terminal — sweep never re-promotes)
+ */
+export type ActivityState = "active" | "idle" | "archived";
+/**
+ * Operator-driven outcome (set by `close` op).
+ *
+ *   open       — default; session has not been explicitly closed
+ *   done       — work completed successfully
+ *   blocked    — paused on external dependency
+ *   abandoned  — won't continue
+ *   merged     — folded into another session (manual_link target)
+ *   superseded — replaced by a newer session
+ */
+export type Outcome = "open" | "done" | "blocked" | "abandoned" | "merged" | "superseded";
+/**
+ * Identity resolution source. Reflects which priority chain step assigned
+ * the session's stable_id during the most recent `session_seen`.
+ *
+ *   claude_session_id_index — P1: exact csid hit in projection
+ *   transcript_lineage      — P2: incoming firstParentUuid matches an existing
+ *                              transcript_files[*].last_uuid (resume / fork)
+ *   fingerprint_corroborator — P3: fingerprint match + sufficient corroborators
+ *   minted                  — none of the above; fresh stable_id
+ */
+export type IdentitySource = "claude_session_id_index" | "transcript_lineage" | "fingerprint_corroborator" | "minted";
+/**
+ * Confidence label co-emitted with `IdentitySource`.
+ *
+ *   exact   — P1 hit (csid is unique per session)
+ *   high    — P2 hit (lineage chain is structurally derived)
+ *   low     — P3 hit (fingerprint + corroborators is heuristic)
+ *   minted  — no resolution path matched (fresh id)
+ */
+export type IdentityConfidence = "exact" | "high" | "low" | "minted";
+/**
+ * events.jsonl op label. Each op has its own reducer in
+ * `lib/projection.mjs` (`reduceSessionSeen`, `reduceSessionLink`, …).
+ *
+ *   session_seen   — primary observation (created + every SessionStart)
+ *   session_link   — additive: attach tasks/projects to a session
+ *   session_unlink — set-based filter: detach tasks/projects (P5)
+ *   alias_set      — set or clear human-readable alias
+ *   parent_set     — set or clear parent_session_id
+ *   close          — set outcome + closed_at + closed_reason
+ *   sweep          — synthetic: activity_state transition (active → idle / archived)
+ *   manual_link    — operator-supplied parent_candidate_ids merge
+ */
+export type EventOp = "session_seen" | "session_link" | "session_unlink" | "alias_set" | "parent_set" | "close" | "sweep" | "manual_link";
+/**
+ * One transcript file (`~/.claude/projects/<workspace-hash>/<uuid>.jsonl`)
+ * as captured in a session's `transcript_files[]`.
+ *
+ * `first_uuid` and `last_uuid` are the lineage anchors used by the P2
+ * `transcript_lineage` resolution; `status` reflects the parser outcome
+ * (`'ok' | 'corrupted' | 'too_large'`, see `lib/transcript.mjs`).
+ */
+export type TranscriptFile = {
+    /**
+     * Absolute path on disk
+     */
+    path: string;
+    /**
+     * First record uuid (lineage start)
+     */
+    first_uuid: (string | null);
+    /**
+     * Last record uuid (lineage tail)
+     */
+    last_uuid: (string | null);
+    /**
+     * File size in bytes
+     */
+    size: number;
+    /**
+     * fs mtime (ISO string)
+     */
+    mtime: Iso8601;
+    /**
+     *           Parser outcome — `corrupted` => unrecoverable, `too_large` =>
+     *           skipped (`> maxSizeMb`)
+     */
+    status: ("ok" | "corrupted" | "too_large");
+};
+/**
+ * Audit trail attached to each `session_seen` event payload (and mirrored
+ * to `KnownSession.identity_resolution` — last-write-wins).
+ *
+ * `matched` is op-specific and kept loose (`Record<string, unknown>`)
+ * because each `IdentitySource` populates a different shape:
+ *   - claude_session_id_index → `{ claude_session_id }`
+ *   - transcript_lineage      → `{ first_parent_uuid, matched_transcript_path, matched_last_uuid }`
+ *   - fingerprint_corroborator → `{ fingerprints_matched, corroborators, corroborator_count, strong_corroborator_count }`
+ *   - minted                  → `{}` or `{ ambiguous: true, ambiguous_count }`
+ */
+export type IdentityResolution = {
+    source: IdentitySource;
+    confidence: IdentityConfidence;
+    matched: Record<string, unknown>;
+};
+/**
+ * Hub-spoke parent hint surfaced when fingerprint evidence exists but does
+ * not meet the corroborator threshold (or when multiple candidates tie).
+ *
+ * The `reason.confidence` carried inside the candidate object is a
+ * categorical label (currently always `'low'` from `collectParentCandidates`).
+ * The numeric `confidence` field at the top of the typedef is reserved for
+ * future scoring (0..1) — current writers leave it as a category-derived
+ * string in tests, so we type it loosely.
+ */
+export type ParentCandidate = {
+    /**
+     *           Stable id of the candidate parent session
+     */
+    candidate: SessionStableId;
+    /**
+     *           0..1 numeric score OR category label (`'low'`); current writers
+     *           emit the categorical form
+     */
+    confidence: (number | string);
+    reason: {
+        fingerprints_matched: string[];
+        corroborator_count: number;
+        strong_corroborator_count: number;
+        weak_corroborator_count: number;
+    };
+};
+/**
+ * Per-session record in `Projection.sessions[stable_id]`.
+ *
+ * Every field is populated lazily by the per-op reducers in
+ * `lib/projection.mjs`. Rules of thumb:
+ *  - `claude_session_ids[]` and `transcript_files[]` are append+dedup
+ *    (later observations augment, never overwrite, the lineage history).
+ *  - `worktree_*`, `branch_current`, `head_last_seen`, `identity_resolution`,
+ *    `parent_candidates_omitted_count` are last-write-wins (recency
+ *    matters more than first observation).
+ *  - `branch_at_start`, `head_at_start`, `first_prompt_preview` are
+ *    first-write-wins (initial observation captures these and we refuse
+ *    to overwrite to preserve history).
+ *  - `tasks[]` and `projects[]` are set-mutated by `session_link` (add) /
+ *    `session_unlink` (remove).
+ *  - `activity_state` is sweep-driven; `outcome` / `closed_at` /
+ *    `closed_reason` are operator-driven via `close`.
+ */
+export type KnownSession = {
+    stable_id: SessionStableId;
+    alias: (string | null);
+    claude_session_ids: ClaudeSessionId[];
+    transcript_files: TranscriptFile[];
+    fingerprints: {
+        first_human_prompt_v1: (string | null);
+        lineage_prefix_v1: (string | null);
+    };
+    parent_session_id: (SessionStableId | null);
+    parent_candidate_ids: ParentCandidate[];
+    /**
+     *           Number of parent candidates dropped by the
+     *           `MAX_PARENT_CANDIDATES` cap on the most recent session_seen
+     */
+    parent_candidates_omitted_count: number;
+    identity_resolution: (IdentityResolution | null);
+    worktree_path_observed: (string | null);
+    worktree_realpath: (string | null);
+    worktree_registry_name: (string | null);
+    git_common_dir: (string | null);
+    branch_at_start: (string | null);
+    branch_current: (string | null);
+    head_at_start: (string | null);
+    head_last_seen: (string | null);
+    tasks: string[];
+    projects: string[];
+    activity_state: ActivityState;
+    outcome: Outcome;
+    closed_at: (Iso8601 | null);
+    closed_reason: (string | null);
+    created_at: Iso8601;
+    last_progress_at: Iso8601;
+    first_prompt_preview: (string | null);
+};
+/**
+ * Cache file `_meta` block.
+ */
+export type ProjectionMeta = {
+    /**
+     *           Pinned to `2` — bump when reducer semantics change
+     */
+    schema_version: 2;
+    /**
+     *           Names of the fingerprint algorithms the writer emits
+     *           (e.g. `['first_human_prompt_v1', 'lineage_prefix_v1']`)
+     */
+    fingerprint_versions: string[];
+    /**
+     *           Last write timestamp (saveProjection bumps to now)
+     */
+    updated: (Iso8601 | null);
+    /**
+     *           Total events folded into this projection
+     */
+    event_count: number;
+    last_event_id: (EventId | null);
+};
+/**
+ * On-disk projection cache shape (`tickets/_logs/sessions-db.json`).
+ * Result of folding `events.jsonl` from the empty projection.
+ */
+export type Projection = {
+    _meta: ProjectionMeta;
+    sessions: Record<SessionStableId, KnownSession>;
+};
+/**
+ * One row in `events.jsonl` (the SSoT). `payload` is op-specific — each
+ * op's reducer reads only the fields it understands; unknown fields are
+ * preserved by the storage layer but ignored by the reducer.
+ *
+ * Tightening `payload` to a per-op union of payload shapes is intentionally
+ * deferred — current writers (CLI + hook) treat payloads as
+ * `Record<string, unknown>` and rely on runtime defensive reads. A future
+ * type-tightening pass can add `SessionSeenPayload`, `SessionLinkPayload`,
+ * etc. without breaking consumers.
+ */
+export type SessionEvent = {
+    ts: Iso8601;
+    event_id: EventId;
+    op: EventOp;
+    stable_id: SessionStableId;
+    payload: Record<string, unknown>;
+};

package/types/uuid.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Generate a fresh `sess_<uuidv7>` string.
+ * @returns {string}
+ */
+export function generateSessionId(): string;
+/**
+ * Validate a sessions-db session id.
+ * @param {unknown} s
+ * @returns {boolean}
+ */
+export function isSessionId(s: unknown): boolean;
+/**
+ * Extract the embedded unix-ms timestamp from a UUIDv7 session id.
+ * @param {string} sessionId
+ * @returns {number} unix ms
+ */
+export function extractTimestamp(sessionId: string): number;