@druumen/sessions-db 0.1.0

package/lib/types.mjs

@@ -0,0 +1,276 @@
+/**
+ * Shared `@typedef` declarations for `@druumen/sessions-db`.
+ *
+ * This file is the single source of truth for the public type vocabulary —
+ * other `.mjs` files reference these typedefs by name in their JSDoc rather
+ * than re-declaring the same shape locally. `tsc --emitDeclarationOnly`
+ * lifts the typedefs from this module into `types/types.d.ts`, and the
+ * curated `types/index.d.ts` re-exports the public subset.
+ *
+ * Conventions:
+ *  - Branded scalar types (SessionStableId, ClaudeSessionId, EventId, Iso8601)
+ *    are kept as plain `string` aliases so JS callers do not need cast helpers.
+ *    Cockpit / TS consumers get nominal-ish naming via the alias name in
+ *    function signatures (`(stableId: SessionStableId)` reads better than
+ *    `(stableId: string)`); the runtime check stays a string check.
+ *  - Enums (ActivityState, Outcome, IdentitySource, IdentityConfidence,
+ *    EventOp) are union-of-string-literals so misspellings are caught at
+ *    type-check time.
+ *  - The projection schema mirrors `lib/projection.mjs` `emptySession()` 1:1.
+ *    When that function gains a field, this typedef MUST be updated in the
+ *    same commit.
+ *
+ * This module exports nothing at runtime — it is types-only. The `export {}`
+ * keeps it a valid ES module so tsc/Node both treat it as a module rather
+ * than a script.
+ */
+
+/**
+ * @typedef {string} SessionStableId
+ *   Sessions-db stable identifier — `sess_<uuidv7-with-dashes>`.
+ *   See `uuid.mjs` `generateSessionId()` / `isSessionId()`.
+ */
+
+/**
+ * @typedef {string} ClaudeSessionId
+ *   Claude Code's per-process session UUID (canonical 8-4-4-4-12, v4).
+ *   Read from the SessionStart hook payload's `session_id` field.
+ */
+
+/**
+ * @typedef {string} EventId
+ *   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).
+ */
+
+/**
+ * @typedef {string} Iso8601
+ *   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`.
+ */
+
+/**
+ * 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)
+ *
+ * @typedef {'active' | 'idle' | 'archived'} ActivityState
+ */
+
+/**
+ * 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
+ *
+ * @typedef {'open' | 'done' | 'blocked' | 'abandoned' | 'merged' | 'superseded'} Outcome
+ */
+
+/**
+ * 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
+ *
+ * @typedef {'claude_session_id_index' | 'transcript_lineage' | 'fingerprint_corroborator' | 'minted'} IdentitySource
+ */
+
+/**
+ * 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)
+ *
+ * @typedef {'exact' | 'high' | 'low' | 'minted'} IdentityConfidence
+ */
+
+/**
+ * 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
+ *
+ * @typedef {'session_seen' | 'session_link' | 'session_unlink' | 'alias_set' | 'parent_set' | 'close' | 'sweep' | 'manual_link'} EventOp
+ */
+
+/**
+ * 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`).
+ *
+ * @typedef {Object} TranscriptFile
+ * @property {string} path                    Absolute path on disk
+ * @property {(string|null)} first_uuid       First record uuid (lineage start)
+ * @property {(string|null)} last_uuid        Last record uuid (lineage tail)
+ * @property {number} size                    File size in bytes
+ * @property {Iso8601} mtime                  fs mtime (ISO string)
+ * @property {('ok' | 'corrupted' | 'too_large')} status
+ *           Parser outcome — `corrupted` => unrecoverable, `too_large` =>
+ *           skipped (`> maxSizeMb`)
+ */
+
+/**
+ * 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 }`
+ *
+ * @typedef {Object} IdentityResolution
+ * @property {IdentitySource} source
+ * @property {IdentityConfidence} confidence
+ * @property {Record<string, unknown>} matched
+ */
+
+/**
+ * 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.
+ *
+ * @typedef {Object} ParentCandidate
+ * @property {SessionStableId} candidate
+ *           Stable id of the candidate parent session
+ * @property {(number|string)} confidence
+ *           0..1 numeric score OR category label (`'low'`); current writers
+ *           emit the categorical form
+ * @property {Object} reason
+ * @property {string[]} reason.fingerprints_matched
+ *           Fingerprint version names that matched (e.g.
+ *           `['first_human_prompt_v1']`)
+ * @property {number} reason.corroborator_count
+ *           Total corroborators (strong + weak)
+ * @property {number} reason.strong_corroborator_count
+ *           Location-anchored corroborators (cwd / worktree_realpath)
+ * @property {number} reason.weak_corroborator_count
+ *           Signal-anchored corroborators (branch / time-window)
+ */
+
+/**
+ * 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`.
+ *
+ * @typedef {Object} KnownSession
+ * @property {SessionStableId} stable_id
+ * @property {(string|null)} alias
+ * @property {ClaudeSessionId[]} claude_session_ids
+ * @property {TranscriptFile[]} transcript_files
+ * @property {Object} fingerprints
+ * @property {(string|null)} fingerprints.first_human_prompt_v1
+ * @property {(string|null)} fingerprints.lineage_prefix_v1
+ * @property {(SessionStableId|null)} parent_session_id
+ * @property {ParentCandidate[]} parent_candidate_ids
+ * @property {number} parent_candidates_omitted_count
+ *           Number of parent candidates dropped by the
+ *           `MAX_PARENT_CANDIDATES` cap on the most recent session_seen
+ * @property {(IdentityResolution|null)} identity_resolution
+ * @property {(string|null)} worktree_path_observed
+ * @property {(string|null)} worktree_realpath
+ * @property {(string|null)} worktree_registry_name
+ * @property {(string|null)} git_common_dir
+ * @property {(string|null)} branch_at_start
+ * @property {(string|null)} branch_current
+ * @property {(string|null)} head_at_start
+ * @property {(string|null)} head_last_seen
+ * @property {string[]} tasks
+ * @property {string[]} projects
+ * @property {ActivityState} activity_state
+ * @property {Outcome} outcome
+ * @property {(Iso8601|null)} closed_at
+ * @property {(string|null)} closed_reason
+ * @property {Iso8601} created_at
+ * @property {Iso8601} last_progress_at
+ * @property {(string|null)} first_prompt_preview
+ */
+
+/**
+ * Cache file `_meta` block.
+ *
+ * @typedef {Object} ProjectionMeta
+ * @property {2} schema_version
+ *           Pinned to `2` — bump when reducer semantics change
+ * @property {string[]} fingerprint_versions
+ *           Names of the fingerprint algorithms the writer emits
+ *           (e.g. `['first_human_prompt_v1', 'lineage_prefix_v1']`)
+ * @property {(Iso8601|null)} updated
+ *           Last write timestamp (saveProjection bumps to now)
+ * @property {number} event_count
+ *           Total events folded into this projection
+ * @property {(EventId|null)} last_event_id
+ */
+
+/**
+ * On-disk projection cache shape (`tickets/_logs/sessions-db.json`).
+ * Result of folding `events.jsonl` from the empty projection.
+ *
+ * @typedef {Object} Projection
+ * @property {ProjectionMeta} _meta
+ * @property {Record<SessionStableId, KnownSession>} sessions
+ */
+
+/**
+ * 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.
+ *
+ * @typedef {Object} SessionEvent
+ * @property {Iso8601} ts
+ * @property {EventId} event_id
+ * @property {EventOp} op
+ * @property {SessionStableId} stable_id
+ * @property {Record<string, unknown>} payload
+ */
+
+export {};

package/lib/uuid.mjs

@@ -0,0 +1,116 @@
+/**
+ * UUIDv7 generator for sessions-db stable IDs.
+ *
+ * Spec: RFC 9562 §5.7 — UUIDv7 (Unix Epoch time-ordered).
+ * Layout (128 bits, big-endian):
+ *   - bits 0..47   : 48-bit unix timestamp in milliseconds
+ *   - bits 48..51  : 4-bit version (= 0b0111 = 7)
+ *   - bits 52..63  : 12 bits of random "rand_a"
+ *   - bits 64..65  : 2-bit IETF variant (= 0b10)
+ *   - bits 66..127 : 62 bits of random "rand_b"
+ *
+ * Output format: `sess_<uuidv7-with-dashes>`
+ *
+ * Notes:
+ * - Node 22's `crypto.randomUUID` always emits v4; the `{version:7}` option
+ *   is silently ignored. We implement the bit layout ourselves with
+ *   `crypto.randomFillSync` (16 bytes, then patch the version + variant
+ *   nibbles, then write the timestamp big-endian into the first 6 bytes).
+ * - To preserve monotonic ordering when multiple IDs are generated within
+ *   the same millisecond we keep the previous timestamp around and bump
+ *   the 12-bit `rand_a` counter when a collision is detected. Across
+ *   millisecond boundaries `rand_a` is fully random.
+ */
+
+import { randomFillSync } from 'node:crypto';
+
+const PREFIX = 'sess_';
+// Matches the canonical 8-4-4-4-12 hex shape with version nibble forced to 7
+// and variant nibble in {8,9,a,b}.
+const UUIDV7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SESSION_ID_RE = new RegExp(`^${PREFIX}${UUIDV7_RE.source.slice(1, -1)}$`);
+
+let lastTimestampMs = -1;
+let lastRandA = 0;
+
+/**
+ * Generate a fresh `sess_<uuidv7>` string.
+ * @returns {string}
+ */
+export function generateSessionId() {
+  const bytes = Buffer.alloc(16);
+  randomFillSync(bytes);
+
+  const nowMs = Date.now();
+  let timestampMs = nowMs;
+  let randA;
+
+  if (nowMs <= lastTimestampMs) {
+    // Same-or-earlier millisecond: reuse the previous timestamp and bump
+    // rand_a so successive IDs remain strictly monotonic.
+    timestampMs = lastTimestampMs;
+    randA = (lastRandA + 1) & 0xfff;
+    if (randA === 0) {
+      // Overflowed the 12-bit counter — advance the timestamp by 1ms so we
+      // do not collide with the prior ID.
+      timestampMs += 1;
+      // randA stays 0 after overflow; rand_b is still random so we keep
+      // collision probability negligible.
+    }
+  } else {
+    // Use 12 random bits from the buffer for rand_a.
+    randA = ((bytes[6] & 0x0f) << 8) | bytes[7];
+  }
+
+  // Write the 48-bit timestamp big-endian into bytes[0..5].
+  // (Buffer.writeUIntBE supports up to 6 bytes, exactly 48 bits.)
+  bytes.writeUIntBE(timestampMs, 0, 6);
+
+  // bytes[6]: top nibble = version (0x70), bottom nibble = high 4 bits of randA.
+  bytes[6] = 0x70 | ((randA >>> 8) & 0x0f);
+  // bytes[7]: low 8 bits of randA.
+  bytes[7] = randA & 0xff;
+  // bytes[8]: top 2 bits = variant 0b10, remaining 6 bits stay random.
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+  lastTimestampMs = timestampMs;
+  lastRandA = randA;
+
+  const hex = bytes.toString('hex');
+  const uuid =
+    hex.slice(0, 8) +
+    '-' +
+    hex.slice(8, 12) +
+    '-' +
+    hex.slice(12, 16) +
+    '-' +
+    hex.slice(16, 20) +
+    '-' +
+    hex.slice(20, 32);
+
+  return PREFIX + uuid;
+}
+
+/**
+ * Validate a sessions-db session id.
+ * @param {unknown} s
+ * @returns {boolean}
+ */
+export function isSessionId(s) {
+  return typeof s === 'string' && SESSION_ID_RE.test(s);
+}
+
+/**
+ * Extract the embedded unix-ms timestamp from a UUIDv7 session id.
+ * @param {string} sessionId
+ * @returns {number} unix ms
+ */
+export function extractTimestamp(sessionId) {
+  if (!isSessionId(sessionId)) {
+    throw new TypeError(`extractTimestamp: not a sessions-db id: ${sessionId}`);
+  }
+  // Strip prefix, then strip dashes from the first three groups (12 hex chars
+  // = 48 bits) and parseInt as base-16. Number is safe since 48 bits < 53.
+  const hex = sessionId.slice(PREFIX.length).replace(/-/g, '').slice(0, 12);
+  return Number.parseInt(hex, 16);
+}

package/lib/watch.mjs

@@ -0,0 +1,217 @@
+/**
+ * Projection-file watcher for sessions-db.
+ *
+ * `watchProjection(rootPath, listener)` invokes `listener` whenever the
+ * projection cache (`tickets/_logs/sessions-db.json` by default) changes.
+ * Returns a Disposable (`{ dispose }`) so callers can unsubscribe — used
+ * by cockpit to feed the live UI without re-polling the on-disk JSON.
+ *
+ * Two redundant signals are wired up:
+ *
+ *   1. **fs.watch** — the OS-level inotify / FSEvents subscription. Fast
+ *      (sub-100ms latency on typical hardware) but unreliable under some
+ *      conditions:
+ *        - editors that "atomic save" (write to tmp + rename) deliver a
+ *          `rename` event but the watcher dies on the inode swap on Linux
+ *        - networked filesystems may drop events
+ *        - macOS FSEvents coalesces aggressively under load
+ *
+ *   2. **1s polling fallback** — `setInterval` reads `mtimeMs` and fires
+ *      the listener if it changed since the last poll. Bounded latency
+ *      regardless of watcher health. Cheap (a single stat per second).
+ *
+ * Both paths funnel through a single **80ms debounce** window so a flurry
+ * of events (sweep applying multiple transitions, or fs.watch + poll both
+ * detecting the same write) collapses into one listener call. The window
+ * is internal — callers do not need to debounce themselves.
+ *
+ * Why 80ms? Long enough to coalesce a write-then-rename (atomic save) and
+ * a fs.watch+poll race (typically < 50ms apart), short enough that the UI
+ * still feels live. Tunable via `opts.debounceMs` for tests.
+ *
+ * Listener contract:
+ *   - Called as `listener({ type, path })` where `type` is one of
+ *     `'change' | 'rename' | 'poll'` (whichever signal fired) and `path`
+ *     is the absolute path to projection.json.
+ *   - Synchronous; if your handler is async, swallow promise rejections
+ *     yourself — the watcher does NOT await.
+ *   - Errors thrown by the listener are caught and silently ignored so a
+ *     buggy consumer doesn't crash the watcher loop.
+ */
+
+import { existsSync, statSync, watch } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+
+import { resolveStoragePaths } from './paths.mjs';
+import { PATHS } from './storage.mjs';
+
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const DEFAULT_DEBOUNCE_MS = 80;
+
+/**
+ * Watch the projection file at `rootPath` and invoke `listener` on change.
+ *
+ * Path resolution (Day 4 — symmetric with storage.mjs):
+ *
+ *   - If `opts.paths.projectionJson` is provided, that's the file watched
+ *     (anchored on `rootPath` if relative). Backward-compat with Day 1-3.
+ *
+ *   - Otherwise `rootPath` is treated as a Day 4 storage root and we
+ *     delegate to `resolveStoragePaths({ rootPath })` so the canonical
+ *     filename + cross-platform path normalization apply uniformly.
+ *
+ * @param {string} rootPath
+ * @param {(event: { type: 'change' | 'rename' | 'poll', path: string }) => void} listener
+ * @param {{
+ *   paths?: { projectionJson?: string },
+ *   pollIntervalMs?: number,
+ *   debounceMs?: number,
+ * }} [opts]
+ * @returns {{ dispose: () => void }}
+ */
+export function watchProjection(rootPath, listener, opts = {}) {
+  if (typeof rootPath !== 'string' || rootPath.length === 0) {
+    throw new TypeError('watchProjection: rootPath required');
+  }
+  if (typeof listener !== 'function') {
+    throw new TypeError('watchProjection: listener function required');
+  }
+
+  let projectionPath;
+  if (opts.paths && opts.paths.projectionJson) {
+    // Legacy form: explicit override anchored at rootPath. Preserves the
+    // pre-Day-4 layout (rootPath = monorepo root, paths embed
+    // `tickets/_logs/`).
+    const projectionRel = opts.paths.projectionJson;
+    projectionPath = isAbsolute(projectionRel)
+      ? projectionRel
+      : resolve(rootPath, projectionRel);
+  } else {
+    // Day 4 form: rootPath IS the storage dir. Delegate so canonical
+    // filenames + path-normalization stay in lib/paths.mjs.
+    const r = resolveStoragePaths({ rootPath });
+    projectionPath = r.projectionJson;
+  }
+
+  const pollIntervalMs = typeof opts.pollIntervalMs === 'number' && opts.pollIntervalMs > 0
+    ? opts.pollIntervalMs
+    : DEFAULT_POLL_INTERVAL_MS;
+  const debounceMs = typeof opts.debounceMs === 'number' && opts.debounceMs >= 0
+    ? opts.debounceMs
+    : DEFAULT_DEBOUNCE_MS;
+
+  // Debounce coalesces multiple events within `debounceMs` into one listener
+  // call. We capture the LAST fired event's `type` so the consumer sees the
+  // most recent signal source ("rename" wins over earlier "change" within the
+  // same window — useful for atomic-save detection).
+  let pendingTimer = null;
+  let pendingType = null;
+  const fireSoon = (type) => {
+    pendingType = type;
+    if (pendingTimer !== null) return;
+    pendingTimer = setTimeout(() => {
+      const t = pendingType;
+      pendingTimer = null;
+      pendingType = null;
+      try {
+        listener({ type: t, path: projectionPath });
+      } catch {
+        // Swallow listener errors — a buggy consumer must not kill the
+        // watcher. If they need observability, they should add their own
+        // try/catch.
+      }
+    }, debounceMs);
+  };
+
+  // -------------------------------------------------------------------------
+  // fs.watch — primary signal. May fail to attach (file doesn't exist yet)
+  // or die mid-way (atomic-save inode swap). Both are tolerated; the poll
+  // fallback covers gaps.
+  // -------------------------------------------------------------------------
+  let fsWatcher = null;
+  const tryAttachWatcher = () => {
+    if (!existsSync(projectionPath)) return;
+    if (fsWatcher) return;
+    try {
+      fsWatcher = watch(projectionPath, { persistent: false }, (eventType) => {
+        // eventType is 'change' | 'rename'. Atomic save fires 'rename'
+        // and may then invalidate this watcher; the next poll will
+        // detect it and re-attach.
+        if (eventType === 'rename') {
+          // Tear down the watcher — the underlying inode is gone.
+          try { fsWatcher && fsWatcher.close(); } catch { /* noop */ }
+          fsWatcher = null;
+        }
+        fireSoon(eventType === 'rename' ? 'rename' : 'change');
+      });
+      fsWatcher.on('error', () => {
+        // Swallow watcher errors and rely on poll fallback. The watcher
+        // will be re-attached on the next poll once the file is back.
+        try { fsWatcher && fsWatcher.close(); } catch { /* noop */ }
+        fsWatcher = null;
+      });
+    } catch {
+      fsWatcher = null;
+    }
+  };
+  tryAttachWatcher();
+
+  // -------------------------------------------------------------------------
+  // Polling — runs every `pollIntervalMs` regardless of watcher health.
+  // Tracks the last seen `mtimeMs` and fires the listener on change. Also
+  // re-attaches fs.watch if it died (atomic save dropped the inode).
+  // -------------------------------------------------------------------------
+  let lastMtimeMs = readMtimeSafe(projectionPath);
+  let pollTimer = setInterval(() => {
+    // Re-attach watcher first so any subsequent fs.watch deliveries can
+    // pre-empt this poll's debounce window cleanly.
+    if (!fsWatcher) tryAttachWatcher();
+
+    const current = readMtimeSafe(projectionPath);
+    if (current === null) {
+      // File doesn't exist (yet). Reset baseline so the first appearance
+      // counts as a change.
+      if (lastMtimeMs !== null) lastMtimeMs = null;
+      return;
+    }
+    if (lastMtimeMs === null || current !== lastMtimeMs) {
+      lastMtimeMs = current;
+      fireSoon('poll');
+    }
+  }, pollIntervalMs);
+  // Don't keep the event loop alive on the watcher's behalf — the consumer
+  // owns liveness via the Disposable.
+  if (typeof pollTimer.unref === 'function') pollTimer.unref();
+
+  return {
+    dispose() {
+      if (pendingTimer !== null) {
+        clearTimeout(pendingTimer);
+        pendingTimer = null;
+        pendingType = null;
+      }
+      if (pollTimer !== null) {
+        clearInterval(pollTimer);
+        pollTimer = null;
+      }
+      if (fsWatcher) {
+        try { fsWatcher.close(); } catch { /* noop */ }
+        fsWatcher = null;
+      }
+    },
+  };
+}
+
+/**
+ * Read the file's `mtimeMs` and return it, or null if the file is missing
+ * or unreadable. Never throws — this is the polling-loop hot path and any
+ * error must degrade to "no change" rather than crashing the timer.
+ */
+function readMtimeSafe(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@druumen/sessions-db",
+  "version": "0.1.0",
+  "description": "Cross-session traceability for Claude Code — events.jsonl SSoT + JSON projection cache + 3-priority identity reconciliation",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./types/index.d.ts",
+  "bin": {
+    "sessions-db": "./cli/sessions-db.mjs",
+    "sessions-db-session-start": "./cli/sessions-db-session-start.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./cli": "./cli/sessions-db.mjs",
+    "./hook": "./cli/sessions-db-session-start.mjs"
+  },
+  "files": [
+    "lib/",
+    "cli/",
+    "types/",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@gitlab.tinfant.org:8922/druumen/sessions-db.git"
+  },
+  "bugs": {
+    "email": "security@druumen.com"
+  },
+  "homepage": "https://github.com/druumen/sessions-db#readme",
+  "keywords": [
+    "claude-code",
+    "session-tracking",
+    "cli",
+    "developer-tools"
+  ],
+  "scripts": {
+    "test": "find __tests__ -name '*.test.mjs' -type f -print0 | xargs -0 node --test",
+    "build:types": "tsc -p tsconfig.json",
+    "check:types-smoke": "tsc --noEmit -p __tests__/types-smoke/tsconfig.json",
+    "prepublishOnly": "npm run build:types"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}