@remnic/core 9.66.0 → 9.66.1

package/src/activity/journal.ts

@@ -0,0 +1,113 @@
+/**
+ * User-owned daily journal (issue #1984 PR1).
+ *
+ * Files live at `<memoryDir>/journal/<YYYY-MM-DD>.md` — inside the memory
+ * directory but outside scan roots, same placement as activity digests.
+ * Once written, Remnic never rewrites the file except `seed` with force.
+ * All writes go through writeJournalFile, which stats first.
+ */
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { isValidActivityDate } from "./digest.js";
+
+export const JOURNAL_DIR_NAME = "journal";
+
+/** Minimal card shape the seed renderer needs. TimelineCard is assignable. */
+export interface JournalSeedCard {
+  title: string;
+  startUtc: string;
+  endUtc: string;
+}
+
+export interface SeedJournalInput {
+  memoryDir: string;
+  date: string;
+  cards?: readonly JournalSeedCard[];
+  force?: boolean;
+}
+
+export interface SeedJournalResult {
+  path: string;
+  wrote: boolean;
+}
+
+const JOURNAL_DAY_TOPLEVEL = /^journal[\\/]\d{4}-\d{2}-\d{2}\.md$/i;
+const JOURNAL_DAY_ANYWHERE = /(?:^|[\\/])journal[\\/]\d{4}-\d{2}-\d{2}\.md$/i;
+
+export function journalPath(memoryDir: string, date: string): string {
+  if (!isValidActivityDate(date)) {
+    throw new RangeError(`Invalid journal date "${date}"; expected YYYY-MM-DD.`);
+  }
+  return path.join(memoryDir, JOURNAL_DIR_NAME, `${date}.md`);
+}
+
+/**
+ * Root-aware journal day-file check. With a memory root, only the top-level
+ * `journal/<date>.md` matches so a nested `facts/journal/<date>.md` stays
+ * recallable. Without a root, fall back to the day-file shape anywhere.
+ */
+export function isJournalDayPath(filePath: string, memoryRoot?: string): boolean {
+  if (memoryRoot !== undefined && memoryRoot.length > 0) {
+    const relative = path.relative(memoryRoot, path.resolve(memoryRoot, filePath));
+    return JOURNAL_DAY_TOPLEVEL.test(relative);
+  }
+  return JOURNAL_DAY_ANYWHERE.test(filePath);
+}
+
+export function todayJournalDate(now: Date = new Date()): string {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+function formatCardDuration(card: JournalSeedCard): string {
+  const start = Date.parse(card.startUtc);
+  const end = Date.parse(card.endUtc);
+  const minutes =
+    Number.isFinite(start) && Number.isFinite(end) && end > start
+      ? Math.round((end - start) / 60_000)
+      : 0;
+  return `${minutes}m`;
+}
+
+function renderJournalSeed(date: string, cards: readonly JournalSeedCard[]): string {
+  const ordered = [...cards].sort((left, right) => {
+    const byStart = left.startUtc.localeCompare(right.startUtc);
+    return byStart !== 0 ? byStart : left.title.localeCompare(right.title);
+  });
+  const glance =
+    ordered.length === 0
+      ? ["_No cards._"]
+      : ordered.map((card) => `- ${formatCardDuration(card)} ${card.title}`);
+  return [`# Journal — ${date}`, "", "## Day at a glance", "", ...glance, "", "## Notes", "", ""].join(
+    "\n",
+  );
+}
+
+/** The only journal write. Stats first; existing files are a no-op unless force. */
+function writeJournalFile(filePath: string, content: string, force: boolean): boolean {
+  let exists = false;
+  try {
+    statSync(filePath);
+    exists = true;
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") throw err;
+  }
+  if (exists && !force) return false;
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, content);
+  return true;
+}
+
+export function seedJournal(input: SeedJournalInput): SeedJournalResult {
+  const filePath = journalPath(input.memoryDir, input.date);
+  const wrote = writeJournalFile(
+    filePath,
+    renderJournalSeed(input.date, input.cards ?? []),
+    input.force === true,
+  );
+  return { path: filePath, wrote };
+}

package/src/activity/privacy.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  MS_PER_DAY,
+  observationsForExport,
+  parseActivityPrivacy,
+  shouldRetain,
+} from "./privacy.js";
+
+test("retentionDays 0 keeps forever", () => {
+  const policy = parseActivityPrivacy({ enabled: true, retentionDays: 0 });
+  assert.equal(policy.retentionDays, 0);
+  const now = 1_700_000_000_000;
+  assert.equal(shouldRetain(now - 400 * MS_PER_DAY, now, policy.retentionDays), true);
+  assert.equal(shouldRetain(now, now, 0), true);
+});
+
+test("negative retentionDays throws", () => {
+  assert.throws(() => parseActivityPrivacy({ retentionDays: -1 }), /non-negative integer/);
+  assert.throws(() => parseActivityPrivacy({ retentionDays: -30 }), /non-negative integer/);
+  assert.throws(() => shouldRetain(0, 0, -1), /non-negative integer/);
+});
+
+test("exact expiry boundary is half-open", () => {
+  const now = 1_700_000_000_000;
+  const days = 30;
+  const captured = now - days * MS_PER_DAY;
+  assert.equal(shouldRetain(captured, now, days), false);
+  assert.equal(shouldRetain(captured + 1, now, days), true);
+  assert.equal(shouldRetain(captured - 1, now, days), false);
+});
+
+test("disabled master denies retain and empties export", () => {
+  const policy = parseActivityPrivacy({
+    enabled: false,
+    retentionDays: 0,
+    exportIncludeObservations: true,
+  });
+  assert.equal(policy.enabled, false);
+  assert.equal(shouldRetain(1_700_000_000_000, 1_700_000_000_000, policy.retentionDays, policy.enabled), false);
+  assert.deepEqual(observationsForExport(["obs"], policy), []);
+  assert.equal(parseActivityPrivacy(undefined).enabled, false);
+});
+
+test("exportIncludeObservations defaults false", () => {
+  assert.equal(parseActivityPrivacy(undefined).exportIncludeObservations, false);
+  assert.equal(parseActivityPrivacy({ enabled: true }).exportIncludeObservations, false);
+  const policy = parseActivityPrivacy({ enabled: true });
+  assert.deepEqual(observationsForExport(["obs"], policy), []);
+  const included = parseActivityPrivacy({ enabled: true, exportIncludeObservations: true });
+  assert.deepEqual(observationsForExport(["obs"], included), ["obs"]);
+});

package/src/activity/privacy.ts

@@ -0,0 +1,80 @@
+/**
+ * Activity retention and export policy (issue #2053 first slice).
+ *
+ * Pure helpers. Surfaces and parseConfig wiring wait for a later PR.
+ * Master `activity.enabled` false denies retain and empties export.
+ */
+import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
+
+export const MS_PER_DAY = 86_400_000;
+
+export interface ActivityPrivacyPolicy {
+  enabled: boolean;
+  /** `0` keeps forever. */
+  retentionDays: number;
+  exportIncludeObservations: boolean;
+}
+
+function asRecord(value: unknown, name: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseGate(value: unknown, key: string, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  const parsed = coerceBooleanLike(value, key);
+  if (parsed === undefined) throw new TypeError(`${key} must be a boolean`);
+  return parsed;
+}
+
+/** Parse retention and export knobs. Independent of timeline/journal/weekly blocks. */
+export function parseActivityPrivacy(raw?: unknown): ActivityPrivacyPolicy {
+  if (raw === undefined || raw === null) {
+    return { enabled: false, retentionDays: 0, exportIncludeObservations: false };
+  }
+  const config = asRecord(raw, "activity");
+  const enabled = parseGate(config.enabled, "activity.enabled", false);
+  let retentionDays = 0;
+  if (config.retentionDays !== undefined) {
+    const parsed = coerceNumber(config.retentionDays, "activity.retentionDays");
+    if (parsed === undefined || !Number.isInteger(parsed) || parsed < 0) {
+      throw new RangeError("activity.retentionDays must be a non-negative integer");
+    }
+    retentionDays = parsed;
+  }
+  const exportIncludeObservations = parseGate(
+    config.exportIncludeObservations,
+    "activity.exportIncludeObservations",
+    false,
+  );
+  return { enabled, retentionDays, exportIncludeObservations };
+}
+
+/**
+ * Half-open retain window: keep when age is in `[0, retentionDays)`.
+ * `retentionDays === 0` keeps forever. Master off denies.
+ */
+export function shouldRetain(
+  capturedAtMs: number,
+  nowMs: number,
+  retentionDays: number,
+  enabled = true,
+): boolean {
+  if (!enabled) return false;
+  if (retentionDays < 0 || !Number.isInteger(retentionDays)) {
+    throw new RangeError("activity.retentionDays must be a non-negative integer");
+  }
+  if (retentionDays === 0) return true;
+  return nowMs - capturedAtMs < retentionDays * MS_PER_DAY;
+}
+
+/** Export payload. Master off or the export gate off returns empty. */
+export function observationsForExport<T>(
+  observations: readonly T[],
+  policy: Pick<ActivityPrivacyPolicy, "enabled" | "exportIncludeObservations">,
+): readonly T[] {
+  if (!policy.enabled || !policy.exportIncludeObservations) return [];
+  return observations;
+}

package/src/activity/timeline/index.ts

@@ -4,3 +4,5 @@ export * from "./categories.js";
 export * from "./classify.js";
 export * from "./build.js";
 export * from "./corrections.js";
+export * from "./query.js";
+export * from "./journal-recap.js";

package/src/activity/timeline/journal-recap.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { TimelineCard } from "./types.js";
+import { renderDeterministicJournal } from "./journal-recap.js";
+
+const DATE = "2026-08-17";
+const TZ = "UTC";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Untitled",
+    summary: "none",
+    categoryId: "development",
+    confidence: 1,
+    dayKey: DATE,
+    timezone: TZ,
+    machine: "ws-a",
+    evidenceIds: [],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+const EMPTY_DAY = [
+  `# Journal — ${DATE} (${TZ})`,
+  "",
+  "## Categories",
+  "",
+  "_No categories._",
+  "",
+  "## Cards",
+  "",
+  "_No cards._",
+  "",
+  "## Gaps / idle / pause",
+  "",
+  "- Gaps: 1",
+  "- Idle: 0",
+  "- Pause: 0",
+  "",
+].join("\n");
+
+const ONE_ACTIVITY_PLUS_IDLE = [
+  `# Journal — ${DATE} (${TZ})`,
+  "",
+  "## Categories",
+  "",
+  "- 90m development",
+  "- 15m system.idle",
+  "",
+  "## Cards",
+  "",
+  "- 90m Terminal",
+  "- 15m Idle",
+  "",
+  "## Gaps / idle / pause",
+  "",
+  "- Gaps: 2",
+  "- Idle: 1",
+  "- Pause: 0",
+  "",
+].join("\n");
+
+function activityPlusIdle(): TimelineCard[] {
+  return [
+    card({
+      id: "idle-1",
+      kind: "idle",
+      title: "Idle",
+      categoryId: "system.idle",
+      startUtc: "2026-08-17T15:30:00.000Z",
+      endUtc: "2026-08-17T15:45:00.000Z",
+    }),
+    card({
+      id: "act-1",
+      title: "Terminal",
+      startUtc: "2026-08-17T14:00:00.000Z",
+      endUtc: "2026-08-17T15:30:00.000Z",
+    }),
+  ];
+}
+
+test("empty day still produces a valid journal body", () => {
+  const body = renderDeterministicJournal([], { date: DATE, timezone: TZ });
+  assert.equal(body, EMPTY_DAY);
+  assert.match(body, /^# Journal — /);
+  assert.equal(body.endsWith("\n"), true);
+});
+
+test("one activity plus idle lists durations, titles, and gap counts", () => {
+  const body = renderDeterministicJournal(activityPlusIdle(), { date: DATE, timezone: TZ });
+  assert.equal(body, ONE_ACTIVITY_PLUS_IDLE);
+});
+
+test("same cards render byte-stable on rerun", () => {
+  const cards = activityPlusIdle();
+  const first = renderDeterministicJournal(cards, { date: DATE, timezone: TZ });
+  const second = renderDeterministicJournal(cards, { date: DATE, timezone: TZ });
+  assert.equal(first, second);
+  assert.equal(Buffer.byteLength(first), Buffer.byteLength(second));
+});
+
+test("recap does not invent people or mood claims", () => {
+  const body = renderDeterministicJournal(activityPlusIdle(), { date: DATE, timezone: TZ });
+  assert.equal(/Alice|Bob|Charlie|meeting with/i.test(body), false);
+  assert.equal(/productivity|mood|intent|score/i.test(body), false);
+  assert.match(body, /Terminal/);
+  assert.match(body, /Idle/);
+});

package/src/activity/timeline/journal-recap.ts

@@ -0,0 +1,130 @@
+/**
+ * Deterministic daily journal recap from timeline cards (issue #2051).
+ *
+ * Pure: cards + date + timezone in, Markdown out. No LLM, no I/O.
+ * Same cards always produce the same bytes. Empty days still yield a
+ * valid file body. Does not invent people, mood, or productivity claims.
+ */
+import { activityDayWindow } from "../digest.js";
+import type { TimelineCard } from "./types.js";
+
+export interface DeterministicJournalOptions {
+  date: string;
+  timezone: string;
+}
+
+interface ClippedCard {
+  card: TimelineCard;
+  startMs: number;
+  endMs: number;
+  durationMs: number;
+}
+
+function formatMinutes(ms: number): string {
+  return `${Math.round(ms / 60_000)}m`;
+}
+
+function clipToWindow(
+  cards: readonly TimelineCard[],
+  winStart: number,
+  winEnd: number,
+): ClippedCard[] {
+  const clipped: ClippedCard[] = [];
+  for (const card of cards) {
+    const start = Date.parse(card.startUtc);
+    const end = Date.parse(card.endUtc);
+    if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+    const startMs = Math.max(start, winStart);
+    const endMs = Math.min(end, winEnd);
+    if (endMs <= startMs) continue;
+    clipped.push({ card, startMs, endMs, durationMs: endMs - startMs });
+  }
+  clipped.sort((left, right) => {
+    const byStart = left.startMs - right.startMs;
+    if (byStart !== 0) return byStart;
+    const byTitle = left.card.title.localeCompare(right.card.title);
+    if (byTitle !== 0) return byTitle;
+    return left.card.id.localeCompare(right.card.id);
+  });
+  return clipped;
+}
+
+function categoryLines(clipped: readonly ClippedCard[]): string[] {
+  const totals = new Map<string, number>();
+  for (const row of clipped) {
+    totals.set(row.card.categoryId, (totals.get(row.card.categoryId) ?? 0) + row.durationMs);
+  }
+  const rows = [...totals.entries()].sort((left, right) => {
+    const byDuration = right[1] - left[1];
+    return byDuration !== 0 ? byDuration : left[0].localeCompare(right[0]);
+  });
+  if (rows.length === 0) return ["_No categories._"];
+  return rows.map(([categoryId, durationMs]) => `- ${formatMinutes(durationMs)} ${categoryId}`);
+}
+
+function mergeIntervals(intervals: readonly (readonly [number, number])[]): Array<[number, number]> {
+  const ordered = [...intervals].sort((left, right) => left[0] - right[0] || left[1] - right[1]);
+  const merged: Array<[number, number]> = [];
+  for (const [start, end] of ordered) {
+    const last = merged[merged.length - 1];
+    if (!last || start > last[1]) merged.push([start, end]);
+    else last[1] = Math.max(last[1], end);
+  }
+  return merged;
+}
+
+function countGaps(
+  winStart: number,
+  winEnd: number,
+  intervals: readonly (readonly [number, number])[],
+): number {
+  const merged = mergeIntervals(intervals);
+  let gaps = 0;
+  let cursor = winStart;
+  for (const [start, end] of merged) {
+    if (start > cursor) gaps += 1;
+    cursor = Math.max(cursor, end);
+  }
+  if (cursor < winEnd) gaps += 1;
+  return gaps;
+}
+
+/** Render a byte-stable Markdown journal for one local day. */
+export function renderDeterministicJournal(
+  cards: readonly TimelineCard[],
+  options: DeterministicJournalOptions,
+): string {
+  const window = activityDayWindow(options.date, options.timezone);
+  const winStart = Date.parse(window.startUtc);
+  const winEnd = Date.parse(window.endUtc);
+  const clipped = clipToWindow(cards, winStart, winEnd);
+  const idle = clipped.filter((row) => row.card.kind === "idle").length;
+  const pause = clipped.filter((row) => row.card.kind === "pause").length;
+  const gaps = countGaps(
+    winStart,
+    winEnd,
+    clipped.map((row) => [row.startMs, row.endMs]),
+  );
+  const cardLines =
+    clipped.length === 0
+      ? ["_No cards._"]
+      : clipped.map((row) => `- ${formatMinutes(row.durationMs)} ${row.card.title}`);
+  return [
+    `# Journal — ${options.date} (${options.timezone})`,
+    "",
+    "## Categories",
+    "",
+    ...categoryLines(clipped),
+    "",
+    "## Cards",
+    "",
+    ...cardLines,
+    "",
+    "## Gaps / idle / pause",
+    "",
+    `- Gaps: ${gaps}`,
+    `- Idle: ${idle}`,
+    `- Pause: ${pause}`,
+    "",
+  ].join("\n");
+}

package/src/activity/timeline/query.test.ts

@@ -0,0 +1,198 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseActivityConfig } from "../config.js";
+import {
+  queryTimelineRange,
+  queryTimelineSearch,
+  runTimelineCliCommand,
+  type TimelineQueryCard,
+} from "./query.js";
+import type { TimelineCard } from "./types.js";
+
+function card(overrides: Partial<TimelineQueryCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">): TimelineQueryCard {
+  return {
+    kind: "activity",
+    title: "Untitled",
+    summary: "none",
+    categoryId: "development",
+    confidence: 1,
+    dayKey: overrides.startUtc.slice(0, 10),
+    timezone: "UTC",
+    machine: "ws-a",
+    evidenceIds: [],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+const BOUNDARY_A = card({
+  id: "a",
+  title: "Morning editor",
+  summary: "typed in vscode",
+  startUtc: "2026-07-10T10:00:00.000Z",
+  endUtc: "2026-07-10T11:00:00.000Z",
+});
+const BOUNDARY_B = card({
+  id: "b",
+  title: "Standup call",
+  summary: "zoom standup",
+  categoryId: "communication",
+  startUtc: "2026-07-10T11:00:00.000Z",
+  endUtc: "2026-07-10T12:00:00.000Z",
+});
+const LATER = card({
+  id: "c",
+  title: "Docs writeup",
+  summary: "edited the standup notes",
+  detailedSummary: "longer writeup about the morning editor session",
+  startUtc: "2026-07-11T09:00:00.000Z",
+  endUtc: "2026-07-11T10:00:00.000Z",
+});
+const DISTRACTION = card({
+  id: "d",
+  title: "Video break",
+  summary: "watched a clip",
+  categoryId: "entertainment",
+  distraction: true,
+  startUtc: "2026-07-10T12:00:00.000Z",
+  endUtc: "2026-07-10T12:30:00.000Z",
+});
+
+const CARDS = [BOUNDARY_A, BOUNDARY_B, LATER, DISTRACTION];
+
+test("range at a boundary instant returns only the containing card", () => {
+  const instant = "2026-07-10T11:00:00.000Z";
+  const result = queryTimelineRange(CARDS, { from: instant, to: instant, format: "cards" });
+  assert.ok(Array.isArray(result));
+  assert.deepEqual(
+    result.map((item) => item.id),
+    ["b"],
+  );
+});
+
+test("range rejects a reversed window and names the limit", () => {
+  assert.throws(
+    () =>
+      queryTimelineRange(CARDS, {
+        from: "2026-07-11T00:00:00.000Z",
+        to: "2026-07-10T00:00:00.000Z",
+        format: "cards",
+      }),
+    /reversed range/,
+  );
+});
+
+test("range rejects a 400-day window and names maxRangeDays", () => {
+  assert.throws(
+    () =>
+      queryTimelineRange(CARDS, {
+        from: "2026-01-01T00:00:00.000Z",
+        to: "2027-02-05T00:00:00.000Z",
+        format: "cards",
+      }),
+    /maxRangeDays \(31\)/,
+  );
+});
+
+test("range format cards and compact both round-trip the fixture", () => {
+  const from = "2026-07-10T10:00:00.000Z";
+  const to = "2026-07-10T12:00:00.000Z";
+  const full = queryTimelineRange(CARDS, { from, to, format: "cards", includeDistractions: true });
+  assert.ok(Array.isArray(full));
+  assert.deepEqual(
+    full.map((item) => item.id),
+    ["a", "b"],
+  );
+  const compact = queryTimelineRange(CARDS, { from, to, format: "compact", includeDistractions: true });
+  assert.ok(!Array.isArray(compact));
+  assert.equal(compact.day, "2026-07-10");
+  assert.deepEqual(compact.cards, [
+    { start: BOUNDARY_A.startUtc, end: BOUNDARY_A.endUtc, category: "development", title: "Morning editor", summary: "typed in vscode" },
+    { start: BOUNDARY_B.startUtc, end: BOUNDARY_B.endUtc, category: "communication", title: "Standup call", summary: "zoom standup" },
+  ]);
+});
+
+test("range rejects an unknown format against the allow-list", () => {
+  assert.throws(
+    () =>
+      queryTimelineRange(CARDS, {
+        from: "2026-07-10T10:00:00.000Z",
+        to: "2026-07-10T11:00:00.000Z",
+        format: "markdown" as "cards",
+      }),
+    /format must be one of: cards, compact/,
+  );
+});
+
+test("search empty results stay ok and unreadable store is distinct", () => {
+  assert.deepEqual(queryTimelineSearch(CARDS, { query: "no-such-token" }), { ok: true, results: [] });
+  assert.deepEqual(queryTimelineSearch(null, { query: "editor" }), { ok: false, error: "store_unreadable" });
+  assert.deepEqual(queryTimelineSearch(undefined, { query: "editor" }), { ok: false, error: "store_unreadable" });
+});
+
+test("search rank is match count then recency then id", () => {
+  const shuffled = [LATER, DISTRACTION, BOUNDARY_B, BOUNDARY_A];
+  const found = queryTimelineSearch(shuffled, { query: "standup editor" });
+  assert.equal(found.ok, true);
+  if (!found.ok) return;
+  assert.deepEqual(
+    found.results.map((item) => item.id),
+    ["c", "b", "a"],
+  );
+});
+
+test("search honors detailedSummary and a 1..50 limit", () => {
+  const found = queryTimelineSearch(CARDS, { query: "writeup", limit: 1 });
+  assert.equal(found.ok, true);
+  if (!found.ok) return;
+  assert.deepEqual(
+    found.results.map((item) => item.id),
+    ["c"],
+  );
+  assert.throws(() => queryTimelineSearch(CARDS, { query: "editor", limit: 0 }), /limit must be an integer from 1 to 50/);
+  assert.throws(() => queryTimelineSearch(CARDS, { query: "editor", limit: 51 }), /limit must be an integer from 1 to 50/);
+});
+
+test("timeline.qa defaults off and honors 0-style disable plus maxRangeDays bounds", () => {
+  const defaults = parseActivityConfig(undefined).timeline.qa;
+  assert.deepEqual(defaults, { enabled: false, maxRangeDays: 31 });
+  assert.equal(parseActivityConfig({ timeline: { qa: { enabled: 0 } } }).timeline.qa.enabled, false);
+  assert.equal(parseActivityConfig({ timeline: { qa: { enabled: "off" } } }).timeline.qa.enabled, false);
+  assert.equal(parseActivityConfig({ timeline: { qa: { enabled: true, maxRangeDays: 1 } } }).timeline.qa.maxRangeDays, 1);
+  assert.throws(
+    () => parseActivityConfig({ timeline: { qa: { maxRangeDays: 0 } } }),
+    /maxRangeDays must be an integer from 1 to 366/,
+  );
+  assert.throws(
+    () => parseActivityConfig({ timeline: { qa: { maxRangeDays: 367 } } }),
+    /maxRangeDays must be an integer from 1 to 366/,
+  );
+});
+
+test("CLI runner accepts in-memory cards and does not need a store", async () => {
+  const qa = { enabled: true, maxRangeDays: 31 };
+  let out = "";
+  let err = "";
+  const io = {
+    stdout: { write: (chunk: string) => (out += chunk) },
+    stderr: { write: (chunk: string) => (err += chunk) },
+  };
+  const rangeCode = await runTimelineCliCommand(
+    { cards: CARDS, qa, timelineEnabled: true },
+    ["range", "--from", "2026-07-10T11:00:00.000Z", "--to", "2026-07-10T11:00:00.000Z", "--format", "cards"],
+    io,
+  );
+  assert.equal(rangeCode, 0);
+  assert.deepEqual(JSON.parse(out).map((item: TimelineCard) => item.id), ["b"]);
+
+  out = "";
+  const unread = await runTimelineCliCommand(
+    { cards: null, qa, timelineEnabled: true },
+    ["search", "--query", "editor"],
+    io,
+  );
+  assert.equal(unread, 1);
+  assert.deepEqual(JSON.parse(out), { ok: false, error: "store_unreadable" });
+  assert.equal(err, "");
+});