@druumen/sessions-db 0.1.0

package/lib/operations.mjs

@@ -0,0 +1,490 @@
+/**
+ * Library-API operations for sessions-db.
+ *
+ * These wrap the storage primitives (`tryUpdateProjection` + `loadProjection`)
+ * with input validation, business invariants, and a uniform `{ ok, event_id?,
+ * error? }` result shape so callers (the CLI handlers AND library consumers
+ * such as cockpit) do not have to re-implement the same checks.
+ *
+ * Three contracts every operation here MUST honor:
+ *
+ *   1. **Validate before write.** Each operation rejects invalid input and
+ *      missing target sessions BEFORE appending to events.jsonl. We do not
+ *      want the SSoT to grow `alias_set` events for non-existent sessions.
+ *
+ *   2. **Result shape.** Success → `{ ok: true, event_id: '<evt_...>' }`.
+ *      Failure → `{ ok: false, error: '<message>' }`. Operations DO NOT
+ *      throw for business-class failures (lock timeout, not-found, cycle).
+ *      System-class failures (disk full, permission denied) are caught by
+ *      `tryUpdateProjection` and returned as `{ ok: false }` too — operations
+ *      preserve that shape rather than re-raising.
+ *
+ *   3. **Lock-safe.** Every operation that mutates the projection routes
+ *      through `tryUpdateProjection`, which holds the projection lock across
+ *      the load → apply → save cycle. Operations never themselves perform
+ *      raw `appendEvent` / `saveProjection` outside that primitive.
+ *
+ * Adding a new operation: write a thin function that builds the canonical
+ * event payload, calls `tryUpdateProjection`, and returns `commitResult()`.
+ * Resist the urge to extend signatures with `--dry-run` or `--json` —
+ * those are CLI-display concerns; the library returns structured results
+ * and lets the caller render them.
+ */
+
+import { computeSweepTransitions } from './sweep.mjs';
+import {
+  loadProjection,
+  newEvent,
+  tryUpdateProjection,
+} from './storage.mjs';
+
+const VALID_OUTCOMES = new Set([
+  'open',
+  'done',
+  'blocked',
+  'abandoned',
+  'merged',
+  'superseded',
+]);
+
+const MAX_PARENT_CHAIN_DEPTH = 50;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve `{ rootPath, root, paths }` opts into a single object suitable
+ * for storage primitives. All fields are optional; when omitted we let
+ * storage fall back to its full Day 4 resolution chain (env → ascend →
+ * cwd/.dru-code).
+ *
+ * Storage's `resolvePaths` honors all three shapes (`paths` > `rootPath`
+ * > `root` > default), so we just pass them through. Callers picking
+ * `rootPath` (Day 4 form) get the canonical-filename layout; callers on
+ * the legacy `root` form keep the `tickets/_logs/` anchored layout.
+ */
+function storageOpts({ rootPath, root, paths } = {}) {
+  const out = {};
+  if (rootPath !== undefined) out.rootPath = rootPath;
+  if (root !== undefined) out.root = root;
+  if (paths !== undefined) out.paths = paths;
+  return out;
+}
+
+/**
+ * Verify a stable_id exists in the projection. Returns the matched session
+ * record on success or `{ ok: false, error }` on miss. Library consumers
+ * differentiate the miss via the `error` string; CLI wraps it in stderr +
+ * exit 1.
+ */
+async function ensureSessionExists(stableId, opts) {
+  const projection = await loadProjection(storageOpts(opts));
+  const session = projection.sessions && projection.sessions[stableId];
+  if (!session) {
+    return { ok: false, error: `stable_id not found: ${stableId}`, projection: null };
+  }
+  return { ok: true, projection, session };
+}
+
+/**
+ * Build event + commit through tryUpdateProjection. Returns the canonical
+ * library-API result shape.
+ */
+async function commitOp({ op, stableId, payload, opts }) {
+  const event = newEvent({ op, stable_id: stableId, payload });
+  const result = await tryUpdateProjection(event, storageOpts(opts));
+  if (!result.ok) {
+    return { ok: false, error: result.error };
+  }
+  return { ok: true, event_id: event.event_id };
+}
+
+// ---------------------------------------------------------------------------
+// Public operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Set or clear the human-readable alias on a session.
+ *
+ * Either `alias` (non-empty string) or `clear: true` must be provided —
+ * mutually exclusive. Validation matches the CLI's argparse behavior so the
+ * library consumer surface is symmetric with the CLI surface.
+ *
+ * @param {{
+ *   stableId: string,
+ *   alias?: string,
+ *   clear?: boolean,
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export async function setAlias(opts) {
+  if (!opts || typeof opts !== 'object') {
+    return { ok: false, error: 'setAlias: opts required' };
+  }
+  const { stableId, alias, clear } = opts;
+  if (typeof stableId !== 'string' || stableId.length === 0) {
+    return { ok: false, error: 'setAlias: stableId required' };
+  }
+  const wantsClear = clear === true;
+  const hasAlias = alias !== undefined && alias !== null;
+  if (wantsClear && hasAlias) {
+    return { ok: false, error: 'setAlias: alias and clear are mutually exclusive' };
+  }
+  if (!wantsClear && !hasAlias) {
+    return { ok: false, error: 'setAlias: provide alias or clear=true' };
+  }
+  if (hasAlias && (typeof alias !== 'string' || alias.length === 0)) {
+    return { ok: false, error: 'setAlias: alias must be a non-empty string' };
+  }
+  const exists = await ensureSessionExists(stableId, opts);
+  if (!exists.ok) return { ok: false, error: exists.error };
+  const payload = wantsClear ? { alias: null } : { alias };
+  return commitOp({ op: 'alias_set', stableId, payload, opts });
+}
+
+/**
+ * Link a session to one or more tasks / projects (additive, idempotent).
+ *
+ * At least one of `tasks` / `projects` must be a non-empty array. The
+ * reducer already de-dupes against existing entries so re-running with the
+ * same payload is a no-op on projection state (but still writes an audit
+ * event).
+ *
+ * @param {{
+ *   stableId: string,
+ *   tasks?: string[],
+ *   projects?: string[],
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export async function linkTask(opts) {
+  if (!opts || typeof opts !== 'object') {
+    return { ok: false, error: 'linkTask: opts required' };
+  }
+  const { stableId } = opts;
+  if (typeof stableId !== 'string' || stableId.length === 0) {
+    return { ok: false, error: 'linkTask: stableId required' };
+  }
+  const tasks = normalizeIdList(opts.tasks);
+  const projects = normalizeIdList(opts.projects);
+  if (tasks.length === 0 && projects.length === 0) {
+    return { ok: false, error: 'linkTask: provide at least one task or project' };
+  }
+  const exists = await ensureSessionExists(stableId, opts);
+  if (!exists.ok) return { ok: false, error: exists.error };
+  const payload = {};
+  if (tasks.length > 0) payload.tasks = tasks;
+  if (projects.length > 0) payload.projects = projects;
+  return commitOp({ op: 'session_link', stableId, payload, opts });
+}
+
+/**
+ * Unlink one or more tasks / projects from a session (set-based filter,
+ * idempotent). Removing an id that isn't present is a no-op on projection
+ * state but still produces an audit event — operator intent is recorded
+ * regardless of resulting state change.
+ *
+ * @param {{
+ *   stableId: string,
+ *   tasks?: string[],
+ *   projects?: string[],
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export async function unlinkTask(opts) {
+  if (!opts || typeof opts !== 'object') {
+    return { ok: false, error: 'unlinkTask: opts required' };
+  }
+  const { stableId } = opts;
+  if (typeof stableId !== 'string' || stableId.length === 0) {
+    return { ok: false, error: 'unlinkTask: stableId required' };
+  }
+  const tasks = normalizeIdList(opts.tasks);
+  const projects = normalizeIdList(opts.projects);
+  if (tasks.length === 0 && projects.length === 0) {
+    return { ok: false, error: 'unlinkTask: provide at least one task or project' };
+  }
+  const exists = await ensureSessionExists(stableId, opts);
+  if (!exists.ok) return { ok: false, error: exists.error };
+  const payload = {};
+  if (tasks.length > 0) payload.tasks = tasks;
+  if (projects.length > 0) payload.projects = projects;
+  return commitOp({ op: 'session_unlink', stableId, payload, opts });
+}
+
+/**
+ * Set or clear the hub-spoke parent relationship for a session.
+ *
+ * Either `parentId` (non-empty string, distinct from `childId`) or `clear:
+ * true` must be provided. When setting a parent we:
+ *   - reject self-cycle (parentId === childId, exit-1 in CLI)
+ *   - verify parent exists
+ *   - walk parent's ancestor chain up to MAX_PARENT_CHAIN_DEPTH and reject
+ *     if `childId` appears anywhere — that would close a cycle of length
+ *     ≥ 2 (e.g. existing A→B + proposed `setParent({childId: B, parentId: A})`
+ *     would form A→B→A).
+ *
+ * The MAX_PARENT_CHAIN_DEPTH bound is a defense against a stale projection
+ * cycle (rare; would require an earlier guard bypass). 50 is generous —
+ * real hub-spoke chains are 1-3 hops.
+ *
+ * @param {{
+ *   childId: string,
+ *   parentId?: string,
+ *   clear?: boolean,
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export async function setParent(opts) {
+  if (!opts || typeof opts !== 'object') {
+    return { ok: false, error: 'setParent: opts required' };
+  }
+  const { childId, parentId, clear } = opts;
+  if (typeof childId !== 'string' || childId.length === 0) {
+    return { ok: false, error: 'setParent: childId required' };
+  }
+  const wantsClear = clear === true;
+  const hasParent = parentId !== undefined && parentId !== null;
+  if (wantsClear && hasParent) {
+    return { ok: false, error: 'setParent: parentId and clear are mutually exclusive' };
+  }
+  if (!wantsClear && !hasParent) {
+    return { ok: false, error: 'setParent: provide parentId or clear=true' };
+  }
+  if (hasParent && (typeof parentId !== 'string' || parentId.length === 0)) {
+    return { ok: false, error: 'setParent: parentId must be a non-empty string' };
+  }
+  if (hasParent && parentId === childId) {
+    return {
+      ok: false,
+      error: 'setParent: parent and child cannot be the same stable_id',
+    };
+  }
+
+  // Verify child exists. Cycle detection must use the same projection load
+  // so the walk reflects what storage will see when the event commits.
+  const childCheck = await ensureSessionExists(childId, opts);
+  if (!childCheck.ok) return { ok: false, error: childCheck.error };
+
+  if (hasParent) {
+    const projection = childCheck.projection;
+    const parentSession = projection.sessions && projection.sessions[parentId];
+    if (!parentSession) {
+      return { ok: false, error: `stable_id not found: ${parentId}` };
+    }
+
+    // Multi-hop cycle detection — walk parent's ancestor chain via
+    // parent_session_id pointers; refuse if we encounter `childId` along
+    // the way. The 1-cycle (parentId === childId) was already rejected.
+    let cursor = parentId;
+    for (let depth = 0; depth < MAX_PARENT_CHAIN_DEPTH && cursor; depth++) {
+      if (cursor === childId) {
+        return {
+          ok: false,
+          error:
+            `setParent: would create a cycle: proposed parent ${parentId} ` +
+            `reaches child ${childId} after ${depth} hop(s)`,
+        };
+      }
+      const ancestor = projection.sessions && projection.sessions[cursor];
+      cursor = ancestor && ancestor.parent_session_id
+        ? ancestor.parent_session_id
+        : null;
+    }
+  }
+
+  const payload = wantsClear
+    ? { parent_session_id: null }
+    : { parent_session_id: parentId };
+  return commitOp({ op: 'parent_set', stableId: childId, payload, opts });
+}
+
+/**
+ * Close (or reopen) a session with a terminal outcome.
+ *
+ * Outcome enum is enforced (matches projection schema): open | done |
+ * blocked | abandoned | merged | superseded. `open` is allowed — operators
+ * may reopen a previously-closed session by passing `outcome: 'open'`; the
+ * reducer's closed_at always tracks the latest close event so the reopen is
+ * visible in the audit trail.
+ *
+ * @param {{
+ *   stableId: string,
+ *   outcome: string,
+ *   reason?: string,
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ * }} opts
+ * @returns {Promise<{ ok: boolean, event_id?: string, error?: string }>}
+ */
+export async function closeSession(opts) {
+  if (!opts || typeof opts !== 'object') {
+    return { ok: false, error: 'closeSession: opts required' };
+  }
+  const { stableId, outcome, reason } = opts;
+  if (typeof stableId !== 'string' || stableId.length === 0) {
+    return { ok: false, error: 'closeSession: stableId required' };
+  }
+  if (typeof outcome !== 'string' || outcome.length === 0) {
+    return { ok: false, error: 'closeSession: outcome required' };
+  }
+  if (!VALID_OUTCOMES.has(outcome)) {
+    return {
+      ok: false,
+      error:
+        `closeSession: outcome must be one of: ` +
+        `${[...VALID_OUTCOMES].join(', ')}`,
+    };
+  }
+  if (reason !== undefined && reason !== null && typeof reason !== 'string') {
+    return { ok: false, error: 'closeSession: reason must be a string' };
+  }
+  const exists = await ensureSessionExists(stableId, opts);
+  if (!exists.ok) return { ok: false, error: exists.error };
+
+  const payload = { outcome };
+  if (reason !== undefined) payload.closed_reason = reason;
+  return commitOp({ op: 'close', stableId, payload, opts });
+}
+
+/**
+ * Compute and (optionally) apply activity_state transitions across all
+ * sessions in the projection.
+ *
+ * Returns:
+ *   - dryRun: true → `{ ok: true, dryRun: true, transitions }` with the
+ *     planned transitions list (no events written).
+ *   - dryRun: false → `{ ok: boolean, applied, failed, summary }` after
+ *     attempting each transition through `tryUpdateProjection`. `ok` is
+ *     true when zero failures.
+ *
+ * Lock model: each transition acquires the projection lock independently
+ * via `tryUpdateProjection`. For typical sweep volumes (single digits per
+ * run) this is fine; if the workspace grows huge a future `--batch` mode
+ * can fold all transitions into a single under-lock pass.
+ *
+ * @param {{
+ *   rootPath?: string,
+ *   root?: string,
+ *   paths?: object,
+ *   idleThresholdDays?: number,
+ *   archiveThresholdDays?: number,
+ *   dryRun?: boolean,
+ *   now?: number,
+ * }} [opts]
+ * @returns {Promise<
+ *   | { ok: true, dryRun: true, transitions: Array<object> }
+ *   | { ok: boolean, applied: Array<object>, failed: Array<object>, summary: object }
+ * >}
+ */
+export async function runSweep(opts = {}) {
+  const idleThresholdDays = opts.idleThresholdDays;
+  const archiveThresholdDays = opts.archiveThresholdDays;
+
+  if (idleThresholdDays !== undefined
+      && (!Number.isFinite(idleThresholdDays) || idleThresholdDays <= 0)) {
+    return {
+      ok: false,
+      error: `runSweep: idleThresholdDays must be a positive number (got: ${idleThresholdDays})`,
+    };
+  }
+  if (archiveThresholdDays !== undefined
+      && (!Number.isFinite(archiveThresholdDays) || archiveThresholdDays <= 0)) {
+    return {
+      ok: false,
+      error: `runSweep: archiveThresholdDays must be a positive number (got: ${archiveThresholdDays})`,
+    };
+  }
+  if (idleThresholdDays !== undefined
+      && archiveThresholdDays !== undefined
+      && archiveThresholdDays < idleThresholdDays) {
+    return {
+      ok: false,
+      error:
+        `runSweep: archiveThresholdDays (${archiveThresholdDays}) must be >= ` +
+        `idleThresholdDays (${idleThresholdDays})`,
+    };
+  }
+
+  const projection = await loadProjection(storageOpts(opts));
+  const transitions = computeSweepTransitions(projection, {
+    idleThresholdDays,
+    archiveThresholdDays,
+    now: opts.now,
+  });
+
+  if (opts.dryRun === true) {
+    return { ok: true, dryRun: true, transitions };
+  }
+
+  const applied = [];
+  const failed = [];
+  for (const t of transitions) {
+    const event = newEvent({
+      op: 'sweep',
+      stable_id: t.stable_id,
+      payload: {
+        activity_state: t.to_state,
+        effective_last_progress: t.effective_last_progress,
+      },
+    });
+    const result = await tryUpdateProjection(event, storageOpts(opts));
+    if (result.ok) {
+      applied.push({ ...t, event_id: event.event_id });
+    } else {
+      failed.push({ ...t, error: result.error });
+    }
+  }
+
+  const toIdle = applied.filter((a) => a.to_state === 'idle').length;
+  const toArchived = applied.filter((a) => a.to_state === 'archived').length;
+  return {
+    ok: failed.length === 0,
+    applied,
+    failed,
+    summary: {
+      total: transitions.length,
+      applied: applied.length,
+      failed: failed.length,
+      to_idle: toIdle,
+      to_archived: toArchived,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Local utilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce an id-list input into a deduped array of non-empty strings.
+ * Accepts undefined / null / single-string / array. Used by linkTask /
+ * unlinkTask so a caller passing `'foo'` instead of `['foo']` still works.
+ */
+function normalizeIdList(input) {
+  if (input === undefined || input === null) return [];
+  const arr = Array.isArray(input) ? input : [input];
+  const seen = new Set();
+  const out = [];
+  for (const v of arr) {
+    if (typeof v !== 'string' || v.length === 0) continue;
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+  }
+  return out;
+}

package/lib/paths.mjs

@@ -0,0 +1,199 @@
+/**
+ * Centralized storage-path resolution for sessions-db.
+ *
+ * Prior to Day 4, every storage primitive (`appendEvent`, `loadProjection`,
+ * `tryUpdateProjection`, `recordSessionSeen`, `initProjection`,
+ * `watchProjection`) hand-rolled its own "anchor opts.paths against opts.root
+ * or fall back to PATHS + cwd" path-joining logic. That worked while there
+ * was a single canonical layout (`tickets/_logs/`) and a single consumer
+ * (this monorepo), but it doesn't survive cockpit-marketplace users who:
+ *   - don't have `tickets/_logs/` (no monorepo)
+ *   - want a product-neutral default (`.dru-code/`)
+ *   - need an env-var override for VS Code workspace overrides
+ *   - might call from inside a child workspace dir and expect "find existing
+ *     storage upward" instead of accidentally creating a parallel one
+ *
+ * `resolveStoragePaths(opts)` collapses all five priorities into one entry
+ * point. First hit wins:
+ *
+ *   1. opts.rootPath — explicit caller arg (highest priority; tests + library
+ *      consumers that already know exactly where storage lives)
+ *   2. process.env.DRUUMEN_SESSIONS_DB_ROOT — env var override (cockpit
+ *      Setup Wizard writes this, CI overrides it, ops can pin during incidents)
+ *   3. cwd-ascend (bounded) for an existing `tickets/_logs/sessions-db.json`
+ *      — preserves the druumen monorepo experience: running any sessions-db
+ *      command from anywhere inside the worktree finds the canonical
+ *      tickets/_logs/ root just like the previous hand-rolled cwd-anchor did.
+ *   4. cwd-ascend (bounded) for an existing `.dru-code/sessions-db.json` —
+ *      the new convention for fresh installs that have already been
+ *      initialized once.
+ *   5. Default new: `<cwd>/.dru-code/` — what fresh `initProjection({})`
+ *      lands when no existing storage is found. Cockpit marketplace's first
+ *      install creates this dir.
+ *
+ * Layout invariant inside `<root>/`:
+ *   - sessions-db-events.jsonl  — append-only SSoT
+ *   - sessions-db.json          — projection cache
+ *   - sessions-db.json.lock     — exclusive-create lockfile
+ *
+ * The same three filenames are used for both druumen-monorepo
+ * (`tickets/_logs/`) and `.dru-code/` layouts so callers never need a
+ * layout-conditional path computation.
+ *
+ * Why an ascend bound (MAX_ASCEND_DEPTH=12)? Walking to filesystem `/` is
+ * slow on networked mounts and pointless — anyone keeping their workspace
+ * 12 directories deep is doing something unusual and should set
+ * `DRUUMEN_SESSIONS_DB_ROOT` explicitly. The bound caps the worst-case stat
+ * count at 12 × 2 (two candidate file checks per level) = 24 stats per call.
+ *
+ * Zero new runtime deps: `node:fs`, `node:path`. Same as the rest of lib/.
+ */
+
+import { existsSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+/**
+ * Hard cap on cwd-ascend depth. Twelve levels is generous — a typical
+ * worktree depth is 1-3, monorepos may go to 5-6. Pinning at 12 means the
+ * worst-case stat budget is 24 (two candidate paths × 12 levels) before
+ * we fall through to the default. Set deliberately conservative so the
+ * resolver never accidentally walks to `/` on a slow networked mount.
+ */
+export const MAX_ASCEND_DEPTH = 12;
+
+/**
+ * The three on-disk filenames (relative to whichever root the resolver
+ * picks). Frozen so callers can't accidentally mutate. Exported for tests
+ * + the rare library consumer that wants to know the canonical names.
+ */
+export const STORAGE_FILENAMES = Object.freeze({
+  eventsJsonl: 'sessions-db-events.jsonl',
+  projectionJson: 'sessions-db.json',
+  lockFile: 'sessions-db.json.lock',
+});
+
+/**
+ * Resolve storage paths from caller opts + env + autodiscover.
+ *
+ * @param {{ rootPath?: string, cwd?: string }} [opts]
+ * @returns {{
+ *   root: string,
+ *   eventsJsonl: string,
+ *   projectionJson: string,
+ *   lockFile: string,
+ *   source: 'arg' | 'env' | 'tickets-logs' | 'dru-code' | 'default',
+ * }}
+ */
+export function resolveStoragePaths(opts = {}) {
+  // ----- Priority 1: explicit opts.rootPath -----
+  // Tests + library consumers that already pinned the location pass this.
+  // Resolved against process.cwd() so a relative override (`./tmp/db`) still
+  // produces an absolute path the rest of the library can use.
+  if (typeof opts.rootPath === 'string' && opts.rootPath.length > 0) {
+    const root = resolve(opts.rootPath);
+    return { root, ...buildFilePaths(root), source: 'arg' };
+  }
+
+  // ----- Priority 2: env var -----
+  // DRUUMEN_SESSIONS_DB_ROOT is the documented escape hatch for ops /
+  // cockpit Setup Wizard / CI matrix runs. Empty string is treated as
+  // "not set" so `DRUUMEN_SESSIONS_DB_ROOT=` in a half-configured env file
+  // doesn't silently send writes to `/sessions-db-events.jsonl`.
+  const envRoot = process.env.DRUUMEN_SESSIONS_DB_ROOT;
+  if (typeof envRoot === 'string' && envRoot.length > 0) {
+    const root = resolve(envRoot);
+    return { root, ...buildFilePaths(root), source: 'env' };
+  }
+
+  // ----- Priorities 3 + 4: cwd-ascend for existing storage -----
+  // We walk upward from opts.cwd (or process.cwd) checking for either a
+  // legacy druumen-monorepo `tickets/_logs/sessions-db.json` (priority 3)
+  // OR a new-convention `.dru-code/sessions-db.json` (priority 4). At each
+  // level the legacy check runs first — when both exist somehow, the
+  // existing-data location wins so we never silently bifurcate writes.
+  const startCwd = resolve(
+    typeof opts.cwd === 'string' && opts.cwd.length > 0 ? opts.cwd : process.cwd(),
+  );
+  const found = ascendForExistingDb(startCwd);
+  if (found) {
+    return { root: found.root, ...buildFilePaths(found.root), source: found.source };
+  }
+
+  // ----- Priority 5: new default `<cwd>/.dru-code/` -----
+  // Fresh-install case. `initProjection` will mkdir this; until it does,
+  // the path is virtual (just where future writes will land).
+  const defaultRoot = join(startCwd, '.dru-code');
+  return { root: defaultRoot, ...buildFilePaths(defaultRoot), source: 'default' };
+}
+
+/**
+ * Build absolute file paths from a root directory. Assumes `root` is already
+ * absolute (callers in this module always resolve before calling).
+ *
+ * @param {string} root
+ * @returns {{ eventsJsonl: string, projectionJson: string, lockFile: string }}
+ */
+function buildFilePaths(root) {
+  return {
+    eventsJsonl: join(root, STORAGE_FILENAMES.eventsJsonl),
+    projectionJson: join(root, STORAGE_FILENAMES.projectionJson),
+    lockFile: join(root, STORAGE_FILENAMES.lockFile),
+  };
+}
+
+/**
+ * Walk upward from `startCwd` looking for an existing sessions-db storage
+ * dir. Returns `{ root, source }` on first hit, null after MAX_ASCEND_DEPTH
+ * levels or when reaching the filesystem root.
+ *
+ * Order at each level:
+ *   - tickets/_logs/sessions-db.json (druumen-monorepo legacy)
+ *   - .dru-code/sessions-db.json (new convention)
+ *
+ * Why projection-file existence (not directory existence)? An empty
+ * `tickets/_logs/` or `.dru-code/` directory could legitimately predate
+ * sessions-db (e.g. another tool created it). Using the projection file as
+ * the existence signal guarantees we only adopt locations that already have
+ * sessions-db state — never sibling tools' storage dirs.
+ *
+ * @param {string} startCwd absolute path
+ * @returns {{ root: string, source: 'tickets-logs' | 'dru-code' } | null}
+ */
+function ascendForExistingDb(startCwd) {
+  let cwd = startCwd;
+  for (let depth = 0; depth < MAX_ASCEND_DEPTH; depth++) {
+    // Priority 3: druumen monorepo convention
+    const ticketsLogsRoot = join(cwd, 'tickets', '_logs');
+    if (existsSync(join(ticketsLogsRoot, STORAGE_FILENAMES.projectionJson))) {
+      return { root: ticketsLogsRoot, source: 'tickets-logs' };
+    }
+    // Priority 4: .dru-code/ convention
+    const druCodeRoot = join(cwd, '.dru-code');
+    if (existsSync(join(druCodeRoot, STORAGE_FILENAMES.projectionJson))) {
+      return { root: druCodeRoot, source: 'dru-code' };
+    }
+    // Stop at filesystem root — `path.dirname('/') === '/'` on POSIX,
+    // and on Windows `path.dirname('C:\\') === 'C:\\'`. Either way the
+    // parent === self loop guard catches it.
+    const parent = dirname(cwd);
+    if (parent === cwd) break;
+    cwd = parent;
+  }
+  return null;
+}
+
+/**
+ * Helper for callers that already have a fully-resolved root and want to
+ * compute file paths (tests, custom integrations). Public so consumers can
+ * mirror the layout invariant without importing internal helpers.
+ *
+ * @param {string} root absolute or relative; resolved against cwd if relative
+ * @returns {{ root: string, eventsJsonl: string, projectionJson: string, lockFile: string }}
+ */
+export function pathsFromRoot(root) {
+  if (typeof root !== 'string' || root.length === 0) {
+    throw new TypeError('pathsFromRoot: root must be a non-empty string');
+  }
+  const abs = isAbsolute(root) ? root : resolve(root);
+  return { root: abs, ...buildFilePaths(abs) };
+}