@remnic/core 9.65.8 → 9.66.1

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

@@ -0,0 +1,215 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { TimelineCard, TimelineCategory } from "./types.js";
+import { buildWeeklyActivitySummary } from "./weekly.js";
+
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+const WEEK_START = "2026-07-13T00:00:00.000Z";
+const WEEK_END = "2026-07-20T00:00:00.000Z";
+const WEEK_MS = 7 * DAY;
+
+const CATEGORIES: TimelineCategory[] = [
+  { id: "alpha", name: "Alpha", color: "#111111", description: "a", order: 1 },
+  { id: "beta", name: "Beta", color: "#222222", description: "b", order: 2 },
+  { id: "development", name: "Development", color: "#333333", description: "d", order: 3 },
+];
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">,
+): TimelineCard {
+  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,
+  };
+}
+
+function options(overrides: Partial<Parameters<typeof buildWeeklyActivitySummary>[1]> = {}) {
+  return {
+    timezone: "UTC",
+    weekStartUtc: WEEK_START,
+    weekEndUtc: WEEK_END,
+    categories: CATEGORIES,
+    ...overrides,
+  };
+}
+
+test("empty week reports zeros, full gap, and previous period unavailable", () => {
+  const summary = buildWeeklyActivitySummary([], options());
+  assert.equal(summary.formatVersion, 1);
+  assert.equal(summary.activeMs, 0);
+  assert.equal(summary.idleMs, 0);
+  assert.equal(summary.pauseMs, 0);
+  assert.equal(summary.unclassifiedMs, 0);
+  assert.equal(summary.gapMs, WEEK_MS);
+  assert.deepEqual(
+    summary.categories.map((row) => row.durationMs),
+    [0, 0, 0],
+  );
+  assert.equal(summary.days.length, 7);
+  assert.ok(summary.days.every((day) => day.gapMs === DAY && day.activeMs === 0));
+  assert.deepEqual(summary.previousPeriod, { available: false });
+  assert.equal("durationMs" in summary.previousPeriod, false);
+  const blob = JSON.stringify(summary);
+  assert.equal(/productivity|mood|intent|score/i.test(blob), false);
+});
+
+test("exact midnight boundary is not double-counted", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "ends-at-midnight",
+        categoryId: "alpha",
+        startUtc: "2026-07-13T23:00:00.000Z",
+        endUtc: "2026-07-14T00:00:00.000Z",
+      }),
+      card({
+        id: "starts-at-midnight",
+        categoryId: "beta",
+        startUtc: "2026-07-14T00:00:00.000Z",
+        endUtc: "2026-07-14T01:00:00.000Z",
+      }),
+      card({
+        id: "before-week",
+        categoryId: "development",
+        startUtc: "2026-07-12T23:00:00.000Z",
+        endUtc: WEEK_START,
+      }),
+      card({
+        id: "after-week",
+        categoryId: "development",
+        startUtc: WEEK_END,
+        endUtc: "2026-07-20T01:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.equal(summary.categories.find((row) => row.categoryId === "alpha")?.durationMs, HOUR);
+  assert.equal(summary.categories.find((row) => row.categoryId === "beta")?.durationMs, HOUR);
+  assert.equal(summary.categories.find((row) => row.categoryId === "development")?.durationMs, 0);
+  assert.equal(summary.activeMs, 2 * HOUR);
+
+  const day13 = summary.days.find((day) => day.date === "2026-07-13");
+  const day14 = summary.days.find((day) => day.date === "2026-07-14");
+  assert.equal(day13?.categories.find((row) => row.categoryId === "alpha")?.durationMs, HOUR);
+  assert.equal(day13?.categories.find((row) => row.categoryId === "beta")?.durationMs, 0);
+  assert.equal(day14?.categories.find((row) => row.categoryId === "beta")?.durationMs, HOUR);
+  assert.equal(day14?.categories.find((row) => row.categoryId === "alpha")?.durationMs, 0);
+});
+
+test("idle and pause kinds are distinct from active", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "work",
+        startUtc: "2026-07-13T10:00:00.000Z",
+        endUtc: "2026-07-13T11:00:00.000Z",
+      }),
+      card({
+        id: "idle",
+        kind: "idle",
+        categoryId: "alpha",
+        startUtc: "2026-07-13T11:00:00.000Z",
+        endUtc: "2026-07-13T11:30:00.000Z",
+      }),
+      card({
+        id: "pause",
+        kind: "pause",
+        categoryId: "beta",
+        startUtc: "2026-07-13T11:30:00.000Z",
+        endUtc: "2026-07-13T11:45:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.equal(summary.activeMs, HOUR);
+  assert.equal(summary.idleMs, 30 * 60_000);
+  assert.equal(summary.pauseMs, 15 * 60_000);
+  assert.equal(summary.gapMs, WEEK_MS - HOUR - 30 * 60_000 - 15 * 60_000);
+});
+
+test("unknown category is unclassified, not a silent zero row", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "mystery",
+        categoryId: "not-configured",
+        startUtc: "2026-07-15T08:00:00.000Z",
+        endUtc: "2026-07-15T09:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.equal(summary.unclassifiedMs, HOUR);
+  assert.equal(summary.activeMs, HOUR);
+  assert.equal(summary.categories.some((row) => row.categoryId === "not-configured"), false);
+  assert.ok(summary.categories.every((row) => row.durationMs === 0));
+});
+
+test("configured category with no cards stays at zero", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "only-dev",
+        categoryId: "development",
+        startUtc: "2026-07-16T12:00:00.000Z",
+        endUtc: "2026-07-16T13:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  const byId = Object.fromEntries(summary.categories.map((row) => [row.categoryId, row.durationMs]));
+  assert.equal(byId.development, HOUR);
+  assert.equal(byId.alpha, 0);
+  assert.equal(byId.beta, 0);
+  assert.equal(summary.categories.length, 3);
+});
+
+test("equal durations sort by categoryId ascending", () => {
+  const summary = buildWeeklyActivitySummary(
+    [
+      card({
+        id: "a",
+        categoryId: "alpha",
+        startUtc: "2026-07-13T09:00:00.000Z",
+        endUtc: "2026-07-13T10:00:00.000Z",
+      }),
+      card({
+        id: "b",
+        categoryId: "beta",
+        startUtc: "2026-07-13T10:00:00.000Z",
+        endUtc: "2026-07-13T12:00:00.000Z",
+      }),
+      card({
+        id: "d",
+        categoryId: "development",
+        startUtc: "2026-07-13T12:00:00.000Z",
+        endUtc: "2026-07-13T14:00:00.000Z",
+      }),
+    ],
+    options(),
+  );
+  assert.deepEqual(
+    summary.categories.map((row) => row.categoryId),
+    ["beta", "development", "alpha"],
+  );
+  assert.deepEqual(
+    summary.categories.map((row) => row.durationMs),
+    [2 * HOUR, 2 * HOUR, HOUR],
+  );
+  const day13 = summary.days.find((day) => day.date === "2026-07-13");
+  assert.deepEqual(
+    day13?.categories.map((row) => row.categoryId),
+    ["beta", "development", "alpha"],
+  );
+});

package/src/activity/timeline/weekly.ts

@@ -0,0 +1,234 @@
+/**
+ * Deterministic weekly time/activity summary over timeline cards (issue #2052).
+ *
+ * Pure: cards + week bounds + category registry in, snapshot out. Half-open
+ * UTC [weekStart, weekEnd). Previous-period comparison is omitted in this
+ * slice and marked unavailable, never a silent zero. Later surfaces
+ * (CLI/MCP/HTTP/UI) consume this shape; they are not built here.
+ */
+import { parseFlexibleIsoTimestamp } from "../../utils/iso-timestamp.js";
+import { activityDayWindow, assertValidTimezone } from "../digest.js";
+import type { TimelineCard, TimelineCardKind, TimelineCategory } from "./types.js";
+
+export const WEEKLY_ACTIVITY_FORMAT_VERSION = 1;
+
+export interface WeeklyActivityOptions {
+  timezone: string;
+  weekStartUtc: string;
+  weekEndUtc: string;
+  categories: readonly TimelineCategory[];
+}
+
+export interface WeeklyCategoryTotal {
+  categoryId: string;
+  durationMs: number;
+}
+
+export interface WeeklyKindTotals {
+  activeMs: number;
+  idleMs: number;
+  pauseMs: number;
+  gapMs: number;
+  unclassifiedMs: number;
+}
+
+export interface WeeklyDayTotal extends WeeklyKindTotals {
+  date: string;
+  startUtc: string;
+  endUtc: string;
+  categories: WeeklyCategoryTotal[];
+}
+
+/** First slice never computes a prior week; the field is present so callers cannot treat absence as zero. */
+export interface WeeklyPreviousPeriodUnavailable {
+  available: false;
+}
+
+export interface WeeklyActivitySummary extends WeeklyKindTotals {
+  formatVersion: number;
+  timezone: string;
+  weekStartUtc: string;
+  weekEndUtc: string;
+  categories: WeeklyCategoryTotal[];
+  days: WeeklyDayTotal[];
+  previousPeriod: WeeklyPreviousPeriodUnavailable;
+}
+
+interface Acc extends WeeklyKindTotals {
+  byCategory: Map<string, number>;
+  intervals: Array<[number, number]>;
+}
+
+function parseBound(value: string, label: string): number {
+  const ms = parseFlexibleIsoTimestamp(value);
+  if (ms === null) {
+    throw new RangeError(`${label} is not a valid ISO timestamp`);
+  }
+  return ms;
+}
+
+function clip(start: number, end: number, winStart: number, winEnd: number): [number, number] | null {
+  const clippedStart = Math.max(start, winStart);
+  const clippedEnd = Math.min(end, winEnd);
+  return clippedEnd > clippedStart ? [clippedStart, clippedEnd] : null;
+}
+
+function unionDuration(intervals: readonly (readonly [number, number])[]): number {
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  let total = 0;
+  let curStart = Number.NaN;
+  let curEnd = Number.NaN;
+  for (const [start, end] of sorted) {
+    if (!Number.isFinite(curStart)) {
+      curStart = start;
+      curEnd = end;
+      continue;
+    }
+    if (start <= curEnd) {
+      curEnd = Math.max(curEnd, end);
+      continue;
+    }
+    total += curEnd - curStart;
+    curStart = start;
+    curEnd = end;
+  }
+  if (Number.isFinite(curStart)) total += curEnd - curStart;
+  return total;
+}
+
+function localDateOf(ms: number, timezone: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(ms));
+  const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? "";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+function shiftIsoDate(date: string, days: number): string {
+  const parsed = new Date(`${date}T00:00:00Z`);
+  parsed.setUTCDate(parsed.getUTCDate() + days);
+  return parsed.toISOString().slice(0, 10);
+}
+
+function daysOverlappingWeek(
+  weekStartMs: number,
+  weekEndMs: number,
+  timezone: string,
+): Array<{ date: string; startMs: number; endMs: number }> {
+  if (weekEndMs <= weekStartMs) return [];
+  let date = localDateOf(weekStartMs, timezone);
+  let window = activityDayWindow(date, timezone);
+  if (Date.parse(window.startUtc) > weekStartMs) {
+    date = shiftIsoDate(date, -1);
+    window = activityDayWindow(date, timezone);
+  }
+  const days: Array<{ date: string; startMs: number; endMs: number }> = [];
+  while (Date.parse(window.startUtc) < weekEndMs) {
+    const startMs = Math.max(Date.parse(window.startUtc), weekStartMs);
+    const endMs = Math.min(Date.parse(window.endUtc), weekEndMs);
+    if (endMs > startMs) days.push({ date, startMs, endMs });
+    date = shiftIsoDate(date, 1);
+    window = activityDayWindow(date, timezone);
+  }
+  return days;
+}
+
+function emptyAcc(categoryIds: readonly string[]): Acc {
+  return {
+    activeMs: 0,
+    idleMs: 0,
+    pauseMs: 0,
+    gapMs: 0,
+    unclassifiedMs: 0,
+    byCategory: new Map(categoryIds.map((id) => [id, 0])),
+    intervals: [],
+  };
+}
+
+function addClipped(acc: Acc, kind: TimelineCardKind, categoryId: string, known: ReadonlySet<string>, start: number, end: number): void {
+  const duration = end - start;
+  acc.intervals.push([start, end]);
+  if (kind === "idle") acc.idleMs += duration;
+  else if (kind === "pause") acc.pauseMs += duration;
+  else acc.activeMs += duration;
+  if (known.has(categoryId)) {
+    acc.byCategory.set(categoryId, (acc.byCategory.get(categoryId) ?? 0) + duration);
+  } else {
+    acc.unclassifiedMs += duration;
+  }
+}
+
+function sortCategoryTotals(byCategory: Map<string, number>): WeeklyCategoryTotal[] {
+  return [...byCategory.entries()]
+    .map(([categoryId, durationMs]) => ({ categoryId, durationMs }))
+    .sort((a, b) => b.durationMs - a.durationMs || (a.categoryId < b.categoryId ? -1 : a.categoryId > b.categoryId ? 1 : 0));
+}
+
+function finish(acc: Acc, windowMs: number): WeeklyKindTotals & { categories: WeeklyCategoryTotal[] } {
+  const covered = unionDuration(acc.intervals);
+  return {
+    activeMs: acc.activeMs,
+    idleMs: acc.idleMs,
+    pauseMs: acc.pauseMs,
+    gapMs: Math.max(0, windowMs - covered),
+    unclassifiedMs: acc.unclassifiedMs,
+    categories: sortCategoryTotals(acc.byCategory),
+  };
+}
+
+/** Build a time/activity summary for one half-open week. Pure. */
+export function buildWeeklyActivitySummary(
+  cards: readonly TimelineCard[],
+  options: WeeklyActivityOptions,
+): WeeklyActivitySummary {
+  assertValidTimezone(options.timezone);
+  const weekStartMs = parseBound(options.weekStartUtc, "weekStartUtc");
+  const weekEndMs = parseBound(options.weekEndUtc, "weekEndUtc");
+  if (weekStartMs > weekEndMs) {
+    throw new RangeError("reversed range: weekStartUtc must be <= weekEndUtc");
+  }
+
+  const categoryIds = options.categories.map((category) => category.id);
+  const known = new Set(categoryIds);
+  const week = emptyAcc(categoryIds);
+  const dayWindows = daysOverlappingWeek(weekStartMs, weekEndMs, options.timezone);
+  const dayAccs = dayWindows.map(() => emptyAcc(categoryIds));
+
+  for (const card of cards) {
+    const start = Date.parse(card.startUtc);
+    const end = Date.parse(card.endUtc);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) continue;
+    const weekClip = clip(start, end, weekStartMs, weekEndMs);
+    if (!weekClip) continue;
+    addClipped(week, card.kind, card.categoryId, known, weekClip[0], weekClip[1]);
+    for (let i = 0; i < dayWindows.length; i++) {
+      const day = dayWindows[i];
+      const dayClip = clip(start, end, day.startMs, day.endMs);
+      if (dayClip) addClipped(dayAccs[i], card.kind, card.categoryId, known, dayClip[0], dayClip[1]);
+    }
+  }
+
+  const weekTotals = finish(week, weekEndMs - weekStartMs);
+  const days: WeeklyDayTotal[] = dayWindows.map((day, i) => {
+    const totals = finish(dayAccs[i], day.endMs - day.startMs);
+    return {
+      date: day.date,
+      startUtc: new Date(day.startMs).toISOString(),
+      endUtc: new Date(day.endMs).toISOString(),
+      ...totals,
+    };
+  });
+
+  return {
+    formatVersion: WEEKLY_ACTIVITY_FORMAT_VERSION,
+    timezone: options.timezone,
+    weekStartUtc: new Date(weekStartMs).toISOString(),
+    weekEndUtc: new Date(weekEndMs).toISOString(),
+    ...weekTotals,
+    days,
+    previousPeriod: { available: false },
+  };
+}

package/src/activity/types.ts

@@ -96,6 +96,25 @@ export interface ActivitySourceConfig {
   token?: string;
 }
 
+/** Opt-in daily journal settings (issue #1984). Default off. */
+export interface ActivityTimelineJournalConfig {
+  enabled: boolean;
+}
+
+/** Opt-in timeline Q&A range/search settings (issue #1983 PR1). Default off. */
+export interface ActivityTimelineQaConfig {
+  enabled: boolean;
+  /** Inclusive max half-open range length in 24h days. Integer 1..366. */
+  maxRangeDays: number;
+}
+
+/** Opt-in timeline-card derivation settings (issue #2049). Default off. */
+export interface ActivityTimelineConfig {
+  enabled: boolean;
+  journal: ActivityTimelineJournalConfig;
+  qa: ActivityTimelineQaConfig;
+}
+
 /** Opt-in activity synchronization + trust-gated extraction settings. */
 export interface ActivityConfig {
   enabled: boolean;
@@ -114,4 +133,5 @@ export interface ActivityConfig {
   minImportance: ImportanceLevel;
   /** `0` means no count cap. */
   maxMemoriesPerDay: number;
+  timeline: ActivityTimelineConfig;
 }

package/src/activity/vault-publish.test.ts

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { applyManagedRegion, publishVaultRegion } from "./vault-publish.js";
+
+const START = "<!-- remnic:timeline:start -->";
+const END = "<!-- remnic:timeline:end -->";
+
+function withVault(fn: (vaultPath: string) => void): void {
+  const vaultPath = mkdtempSync(path.join(tmpdir(), "remnic-vault-"));
+  try {
+    fn(vaultPath);
+  } finally {
+    rmSync(vaultPath, { recursive: true, force: true });
+  }
+}
+
+test("applyManagedRegion replaces only the marked region", () => {
+  const fileText = [
+    "---",
+    "title: daily",
+    "---",
+    "",
+    "human notes",
+    START,
+    "old cards",
+    END,
+    "more human",
+    "",
+  ].join("\n");
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "new cards",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(
+    result.text,
+    [
+      "---",
+      "title: daily",
+      "---",
+      "",
+      "human notes",
+      START,
+      "new cards",
+      END,
+      "more human",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("applyManagedRegion is a no-op when markers are missing", () => {
+  const fileText = "no managed region here\n";
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "new cards",
+  });
+  assert.deepEqual(result, { ok: false, reason: "no_marker", text: fileText });
+});
+
+test("applyManagedRegion preserves CRLF outside and inside the owned region", () => {
+  const fileText = [
+    "---",
+    "title: daily",
+    "---",
+    "",
+    "human notes",
+    START,
+    "old cards",
+    END,
+    "more human",
+    "",
+  ].join("\r\n");
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "new cards\nline two",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  assert.equal(
+    result.text,
+    [
+      "---",
+      "title: daily",
+      "---",
+      "",
+      "human notes",
+      START,
+      "new cards",
+      "line two",
+      END,
+      "more human",
+      "",
+    ].join("\r\n"),
+  );
+  assert.equal(result.text.includes("\n") && !result.text.includes("\r\n"), false);
+});
+
+test("applyManagedRegion keeps every outside byte identical", () => {
+  const prefix = "---\nkeep: me\n---\n\n- [ ] task\n```dataview\nLIST\n```\n";
+  const suffix = "\n<!-- other-agent:start -->\nleave this\n<!-- other-agent:end -->\n  trailing  \n";
+  const fileText = `${prefix}${START}\nold\n${END}${suffix}`;
+  const startAt = fileText.indexOf(START);
+  const endAt = fileText.indexOf(END);
+  const before = Buffer.from(fileText.slice(0, startAt + START.length), "utf8");
+  const after = Buffer.from(fileText.slice(endAt), "utf8");
+  const result = applyManagedRegion(fileText, {
+    strategy: "markers",
+    name: "timeline",
+    content: "replacement",
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+  const nextStart = result.text.indexOf(START);
+  const nextEnd = result.text.indexOf(END);
+  assert.deepEqual(Buffer.from(result.text.slice(0, nextStart + START.length), "utf8"), before);
+  assert.deepEqual(Buffer.from(result.text.slice(nextEnd), "utf8"), after);
+});
+
+test("publishVaultRegion updates an existing note and skips an unchanged rewrite", () => {
+  withVault((vaultPath) => {
+    const relativeFile = "Daily Notes/2026-08-17.md";
+    const dest = path.join(vaultPath, relativeFile);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    writeFileSync(dest, `intro\n${START}\nold\n${END}\noutro\n`);
+    const first = publishVaultRegion({
+      vaultPath,
+      relativeFile,
+      name: "timeline",
+      content: "new cards",
+    });
+    assert.deepEqual(first, { ok: true, status: "updated" });
+    assert.equal(readFileSync(dest, "utf8"), `intro\n${START}\nnew cards\n${END}\noutro\n`);
+    const mtime = statSync(dest).mtimeMs;
+    const second = publishVaultRegion({
+      vaultPath,
+      relativeFile,
+      name: "timeline",
+      content: "new cards",
+    });
+    assert.deepEqual(second, { ok: true, status: "unchanged" });
+    assert.equal(statSync(dest).mtimeMs, mtime);
+  });
+});
+
+test("publishVaultRegion never creates a missing file", () => {
+  withVault((vaultPath) => {
+    const relativeFile = "missing.md";
+    const result = publishVaultRegion({
+      vaultPath,
+      relativeFile,
+      name: "timeline",
+      content: "new cards",
+    });
+    assert.deepEqual(result, { ok: false, reason: "missing_file" });
+    assert.equal(existsSync(path.join(vaultPath, relativeFile)), false);
+  });
+});