@remnic/core 9.65.8 → 9.66.1

package/src/activity/config.ts

@@ -1,7 +1,14 @@
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
 import type { ImportanceLevel } from "../types.js";
-import type { ActivityConfig, ActivityExtractionMode, ActivitySourceConfig } from "./types.js";
+import type {
+  ActivityConfig,
+  ActivityExtractionMode,
+  ActivitySourceConfig,
+  ActivityTimelineConfig,
+  ActivityTimelineJournalConfig,
+  ActivityTimelineQaConfig,
+} from "./types.js";
 
 const EXTRACTION_MODES: readonly ActivityExtractionMode[] = ["off", "smart"];
 const IMPORTANCE_LEVELS: readonly ImportanceLevel[] = ["critical", "high", "normal", "low", "trivial"];
@@ -22,6 +29,7 @@ export function defaultActivityConfig(): ActivityConfig {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
+    timeline: { enabled: false, journal: { enabled: false }, qa: { enabled: false, maxRangeDays: 31 } },
   };
 }
 
@@ -182,5 +190,62 @@ export function parseActivityConfig(raw: unknown): ActivityConfig {
     minConfidence: parseUnitInterval(config.minConfidence, "minConfidence", defaults.minConfidence),
     minImportance: minImportance as ImportanceLevel,
     maxMemoriesPerDay,
+    timeline: parseTimelineConfig(config.timeline),
   };
 }
+
+/**
+ * Parse the `activity.timeline.*` block. `enabled` is the master gate for
+ * timeline-card derivation (issue #2049); default false. A non-object block
+ * is malformed and must fail rather than silently disabling the layer.
+ */
+function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
+  if (raw === undefined) return { enabled: false, journal: { enabled: false }, qa: parseTimelineQaConfig(undefined) };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline must be an object");
+  }
+  const timeline = raw as Record<string, unknown>;
+  const enabledValue = coerceBooleanLike(timeline.enabled, "activity.timeline.enabled");
+  if (timeline.enabled !== undefined && enabledValue === undefined) {
+    throw new TypeError("activity.timeline.enabled must be a boolean");
+  }
+  return {
+    enabled: enabledValue ?? false,
+    journal: parseTimelineJournalConfig(timeline.journal),
+    qa: parseTimelineQaConfig(timeline.qa),
+  };
+}
+
+function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig {
+  if (raw === undefined) return { enabled: false };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.journal must be an object");
+  }
+  const journal = raw as Record<string, unknown>;
+  const enabledValue = coerceBooleanLike(journal.enabled, "activity.timeline.journal.enabled");
+  if (journal.enabled !== undefined && enabledValue === undefined) {
+    throw new TypeError("activity.timeline.journal.enabled must be a boolean");
+  }
+  return { enabled: enabledValue ?? false };
+}
+
+function parseTimelineQaConfig(raw: unknown): ActivityTimelineQaConfig {
+  if (raw === undefined) return { enabled: false, maxRangeDays: 31 };
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.qa must be an object");
+  }
+  const qa = raw as Record<string, unknown>;
+  const enabledValue = coerceBooleanLike(qa.enabled, "activity.timeline.qa.enabled");
+  if (qa.enabled !== undefined && enabledValue === undefined) {
+    throw new TypeError("activity.timeline.qa.enabled must be a boolean");
+  }
+  const maxRangeDaysValue = coerceNumber(qa.maxRangeDays, "activity.timeline.qa.maxRangeDays");
+  if (qa.maxRangeDays !== undefined && maxRangeDaysValue === undefined) {
+    throw new TypeError("activity.timeline.qa.maxRangeDays must be an integer from 1 to 366");
+  }
+  const maxRangeDays = maxRangeDaysValue ?? 31;
+  if (!Number.isInteger(maxRangeDays) || maxRangeDays < 1 || maxRangeDays > 366) {
+    throw new RangeError("activity.timeline.qa.maxRangeDays must be an integer from 1 to 366");
+  }
+  return { enabled: enabledValue ?? false, maxRangeDays };
+}

package/src/activity/index.ts

@@ -14,4 +14,7 @@ export * from "./runner.js";
 export * from "./scheduler.js";
 export * from "./config.js";
 export * from "./reindex.js";
+export * from "./timeline/index.js";
+export * from "./journal.js";
 export * from "./memory-gen.js";
+export * from "./privacy.js";

package/src/activity/journal.test.ts

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { isSearchExcludedPath } from "../orchestration/generic-recall-paths.js";
+import { ALL_CATEGORY_DIRS, RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
+import { parseActivityConfig } from "./config.js";
+import { isJournalDayPath, journalPath, seedJournal } from "./journal.js";
+
+const DATE = "2026-08-17";
+
+function withMemoryDir(fn: (memoryDir: string) => void): void {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-journal-"));
+  try {
+    fn(memoryDir);
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+}
+
+test("activity.timeline.journal.enabled defaults off", () => {
+  assert.equal(parseActivityConfig(undefined).timeline.journal.enabled, false);
+  assert.equal(
+    parseActivityConfig({ timeline: { journal: { enabled: true } } }).timeline.journal.enabled,
+    true,
+  );
+  assert.throws(
+    () => parseActivityConfig({ timeline: { journal: "on" } }),
+    /activity\.timeline\.journal must be an object/,
+  );
+});
+
+test("seed is a hard no-op without force", () => {
+  withMemoryDir((memoryDir) => {
+    const first = seedJournal({
+      memoryDir,
+      date: DATE,
+      cards: [{ title: "Write seed", startUtc: "2026-08-17T14:00:00.000Z", endUtc: "2026-08-17T14:45:00.000Z" }],
+    });
+    assert.equal(first.wrote, true);
+    assert.equal(first.path, journalPath(memoryDir, DATE));
+    const original = readFileSync(first.path);
+    const second = seedJournal({
+      memoryDir,
+      date: DATE,
+      cards: [{ title: "Different card", startUtc: "2026-08-17T15:00:00.000Z", endUtc: "2026-08-17T16:00:00.000Z" }],
+    });
+    assert.equal(second.wrote, false);
+    assert.deepEqual(readFileSync(second.path), original);
+  });
+});
+
+test("seed with force overwrites the existing file", () => {
+  withMemoryDir((memoryDir) => {
+    seedJournal({ memoryDir, date: DATE });
+    const original = readFileSync(journalPath(memoryDir, DATE), "utf8");
+    const forced = seedJournal({
+      memoryDir,
+      date: DATE,
+      force: true,
+      cards: [{ title: "Forced rewrite", startUtc: "2026-08-17T10:00:00.000Z", endUtc: "2026-08-17T11:30:00.000Z" }],
+    });
+    assert.equal(forced.wrote, true);
+    const next = readFileSync(forced.path, "utf8");
+    assert.notEqual(next, original);
+    assert.match(next, /# Journal — 2026-08-17/);
+    assert.match(next, /## Day at a glance/);
+    assert.match(next, /- 90m Forced rewrite/);
+    assert.match(next, /## Notes/);
+  });
+});
+
+test("journal day files sit outside scan roots and generic search", () => {
+  assert.equal(ALL_CATEGORY_DIRS.includes("journal"), false);
+  assert.equal(RECALL_FALLBACK_DIRS.includes("journal"), false);
+  assert.equal(isJournalDayPath("journal/2026-08-17.md"), true);
+  assert.equal(
+    isJournalDayPath("facts/journal/2026-08-17.md", "/tmp/remnic-fixture-memory"),
+    false,
+    "nested stays recallable",
+  );
+  assert.equal(isSearchExcludedPath("journal/2026-08-17.md"), true);
+  assert.equal(
+    isSearchExcludedPath("facts/journal/2026-08-17.md", { memoryDir: "/tmp/remnic-fixture-memory" }),
+    false,
+  );
+
+  withMemoryDir((memoryDir) => {
+    const result = seedJournal({ memoryDir, date: DATE });
+    const relative = path.relative(memoryDir, result.path).replace(/\\/g, "/");
+    assert.equal(relative, "journal/2026-08-17.md");
+    assert.equal(isSearchExcludedPath(relative), true);
+    assert.equal(isSearchExcludedPath(result.path, { memoryDir }), true);
+  });
+});

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;
+}