@remnic/core 9.66.1 → 9.66.2

package/src/activity/journal-vault-read.test.ts

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { readVaultJournal, stripRemnicOwnedRegions } from "./journal-vault-read.js";
+
+const START = "<!-- remnic:timeline:start -->";
+const END = "<!-- remnic:timeline:end -->";
+
+test("missing file is exists false, not an error", () => {
+  assert.deepEqual(readVaultJournal({ fileText: null, journalSection: "Journal" }), {
+    ok: true,
+    exists: false,
+    reason: "missing_file",
+  });
+  assert.deepEqual(readVaultJournal({ fileText: undefined, journalSection: "Journal" }), {
+    ok: true,
+    exists: false,
+    reason: "missing_file",
+  });
+});
+
+test("missing heading is exists false, not an error", () => {
+  const fileText = ["---", "date: 2026-08-17", "---", "", "## Timeline", "cards", ""].join("\n");
+  assert.deepEqual(readVaultJournal({ fileText, journalSection: "Journal" }), {
+    ok: true,
+    exists: false,
+    reason: "missing_heading",
+  });
+});
+
+test("empty day returns exists true with empty text", () => {
+  const fileText = ["## Journal", "## Next", ""].join("\n");
+  const result = readVaultJournal({ fileText, journalSection: "Journal" });
+  assert.deepEqual(result, {
+    ok: true,
+    exists: true,
+    text: "",
+    heading: "Journal",
+    warnings: [],
+  });
+});
+
+test("duplicate heading refuses with line numbers", () => {
+  const fileText = ["# Day", "## Journal", "first", "## Notes", "## Journal", "second", ""].join("\n");
+  const result = readVaultJournal({ fileText, journalSection: "Journal" });
+  assert.deepEqual(result, { ok: false, reason: "duplicate_heading", lines: [2, 5] });
+});
+
+test("strips remnic marker regions and publish section headings", () => {
+  const fileText = [
+    "---",
+    "date: 2026-08-17",
+    "---",
+    "",
+    "## Journal",
+    "I walked the dog.",
+    START,
+    "- 09:00 standup",
+    END,
+    "Still thinking about the meeting.",
+    "### Timeline",
+    "nested publish",
+    "### Notes",
+    "more user text",
+    "",
+    "## Timeline",
+    START,
+    "sibling publish",
+    END,
+    "",
+  ].join("\n");
+
+  const result = readVaultJournal({
+    fileText,
+    journalSection: "Journal",
+    publishSectionNames: ["Timeline"],
+  });
+  assert.equal(result.ok, true);
+  if (!result.ok || !result.exists) {
+    assert.fail("expected journal text");
+    return;
+  }
+  assert.equal(result.heading, "Journal");
+  assert.equal(result.warnings.length, 0);
+  assert.match(result.text, /I walked the dog\./);
+  assert.match(result.text, /Still thinking about the meeting\./);
+  assert.match(result.text, /more user text/);
+  assert.doesNotMatch(result.text, /standup/);
+  assert.doesNotMatch(result.text, /nested publish/);
+  assert.doesNotMatch(result.text, /sibling publish/);
+  assert.doesNotMatch(result.text, /remnic:/);
+  assert.doesNotMatch(result.text, /### Timeline/);
+});
+
+test("non-ASCII journal heading matches exactly", () => {
+  const fileText = ["## Tagebuch 📝", "Heute ruhig.", "## Andere", ""].join("\n");
+  const result = readVaultJournal({ fileText, journalSection: "Tagebuch 📝" });
+  assert.deepEqual(result, {
+    ok: true,
+    exists: true,
+    text: "Heute ruhig.",
+    heading: "Tagebuch 📝",
+    warnings: [],
+  });
+});
+
+test("unclosed start marker strips to end of section and warns", () => {
+  const fileText = ["## Journal", "keep me", START, "leaked publish", "## Next", "outside", ""].join(
+    "\n",
+  );
+  const result = readVaultJournal({ fileText, journalSection: "Journal" });
+  assert.equal(result.ok, true);
+  if (!result.ok || !result.exists) {
+    assert.fail("expected journal text");
+    return;
+  }
+  assert.equal(result.text, "keep me");
+  assert.equal(result.warnings.length, 1);
+  assert.match(result.warnings[0]!, /timeline/);
+});
+
+test("marker pair split across the section boundary does not leak", () => {
+  const fileText = [
+    START,
+    "before journal",
+    "## Journal",
+    "leaked into journal",
+    END,
+    "user after",
+    "## Next",
+    "",
+  ].join("\n");
+  const result = readVaultJournal({ fileText, journalSection: "Journal" });
+  assert.equal(result.ok, true);
+  if (!result.ok || !result.exists) {
+    assert.fail("expected journal text");
+    return;
+  }
+  assert.equal(result.text, "user after");
+  assert.doesNotMatch(result.text, /leaked/);
+});
+
+test("stripRemnicOwnedRegions returns only user text after injected regions", () => {
+  const user = "Day was quiet.\nSecond line.\n";
+  const names = ["timeline", "weekly", "digest"] as const;
+  for (const name of names) {
+    const region = `<!-- remnic:${name}:start -->\nOWNED ${name}\n<!-- remnic:${name}:end -->\n`;
+    const mixed = `${region}${user}${region}${user}`;
+    const stripped = stripRemnicOwnedRegions(mixed);
+    assert.equal(stripped.text, `${user}${user}`);
+    assert.deepEqual(stripped.warnings, []);
+  }
+});

package/src/activity/journal-vault-read.ts

@@ -0,0 +1,214 @@
+/**
+ * Read-only vault daily-note journal section (issue #1987 first slice).
+ *
+ * Pure: file text in, journal body out. Never writes. Strips Remnic-owned
+ * marker regions and publisher-owned headings so published timeline text
+ * cannot re-enter the journal. Path templates stay in vault-publish.
+ */
+
+export interface ReadVaultJournalInput {
+  fileText: string | null | undefined;
+  journalSection: string;
+  publishSectionNames?: readonly string[];
+}
+
+export type ReadVaultJournalResult =
+  | { ok: true; exists: false; reason: "missing_file" | "missing_heading" }
+  | { ok: true; exists: true; text: string; heading: string; warnings: readonly string[] }
+  | { ok: false; reason: "duplicate_heading"; lines: readonly number[] };
+
+const REMNIC_OPEN = "<!-- remnic:";
+
+export function readVaultJournal(input: ReadVaultJournalInput): ReadVaultJournalResult {
+  if (input.fileText === null || input.fileText === undefined) {
+    return { ok: true, exists: false, reason: "missing_file" };
+  }
+  if (input.journalSection.length === 0) {
+    return { ok: true, exists: false, reason: "missing_heading" };
+  }
+
+  const lines = splitFileLines(input.fileText);
+  const hits: number[] = [];
+  const levels: number[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const heading = parseAtxHeading(lines[i]!);
+    if (heading && heading.text === input.journalSection) {
+      hits.push(i + 1);
+      levels.push(heading.level);
+    }
+  }
+  if (hits.length === 0) return { ok: true, exists: false, reason: "missing_heading" };
+  if (hits.length > 1) return { ok: false, reason: "duplicate_heading", lines: hits };
+
+  const headingIndex = hits[0]! - 1;
+  const level = levels[0]!;
+  let endIndex = lines.length;
+  for (let i = headingIndex + 1; i < lines.length; i++) {
+    const heading = parseAtxHeading(lines[i]!);
+    if (heading && heading.level <= level) {
+      endIndex = i;
+      break;
+    }
+  }
+
+  const body = lines.slice(headingIndex + 1, endIndex).join("\n");
+  const stripped = stripRemnicOwnedRegions(body, input.publishSectionNames ?? []);
+  return {
+    ok: true,
+    exists: true,
+    text: trimNewlines(stripped.text),
+    heading: input.journalSection,
+    warnings: stripped.warnings,
+  };
+}
+
+/** Remove Remnic marker pairs and publisher-owned heading sections. */
+export function stripRemnicOwnedRegions(
+  text: string,
+  publishSectionNames: readonly string[] = [],
+): { text: string; warnings: readonly string[] } {
+  const marked = cutIntervals(text, remnicIntervals(text));
+  return {
+    text: stripPublishHeadings(marked.text, publishSectionNames),
+    warnings: marked.warnings,
+  };
+}
+
+function splitFileLines(fileText: string): string[] {
+  const lines = fileText.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (line.endsWith("\r")) lines[i] = line.slice(0, -1);
+  }
+  return lines;
+}
+
+function parseAtxHeading(line: string): { level: number; text: string } | null {
+  let level = 0;
+  while (level < line.length && level < 6 && line[level] === "#") level++;
+  if (level === 0) return null;
+  const after = line[level];
+  if (after !== " " && after !== "\t") return null;
+
+  let start = level + 1;
+  let end = line.length;
+  while (start < end && (line[start] === " " || line[start] === "\t")) start++;
+  while (end > start && (line[end - 1] === " " || line[end - 1] === "\t")) end--;
+
+  let hashEnd = end;
+  while (hashEnd > start && line[hashEnd - 1] === "#") hashEnd--;
+  if (hashEnd < end && hashEnd > start && (line[hashEnd - 1] === " " || line[hashEnd - 1] === "\t")) {
+    end = hashEnd;
+    while (end > start && (line[end - 1] === " " || line[end - 1] === "\t")) end--;
+  }
+  return { level, text: line.slice(start, end) };
+}
+
+function remnicIntervals(text: string): {
+  intervals: Array<{ start: number; end: number }>;
+  warnings: string[];
+} {
+  const starts: Array<{ name: string; start: number; after: number }> = [];
+  const ends: Array<{ name: string; start: number; end: number }> = [];
+
+  let from = 0;
+  while (from < text.length) {
+    const open = text.indexOf(REMNIC_OPEN, from);
+    if (open === -1) break;
+    const afterOpen = open + REMNIC_OPEN.length;
+    const commentEnd = text.indexOf("-->", afterOpen);
+    if (commentEnd === -1) break;
+    const inner = text.slice(afterOpen, commentEnd).trim();
+    if (inner.endsWith(":start")) {
+      const name = inner.slice(0, -":start".length);
+      if (name.length > 0) starts.push({ name, start: open, after: commentEnd + 3 });
+    } else if (inner.endsWith(":end")) {
+      const name = inner.slice(0, -":end".length);
+      if (name.length > 0) ends.push({ name, start: open, end: commentEnd + 3 });
+    }
+    from = commentEnd + 3;
+  }
+
+  const usedEnds = new Set<number>();
+  const intervals: Array<{ start: number; end: number }> = [];
+  const warnings: string[] = [];
+
+  for (const start of starts) {
+    const match = ends.find((end) => end.name === start.name && end.start >= start.after && !usedEnds.has(end.start));
+    if (match) {
+      usedEnds.add(match.start);
+      intervals.push({ start: start.start, end: eatTrailingNewline(text, match.end) });
+    } else {
+      intervals.push({ start: start.start, end: text.length });
+      warnings.push(`unclosed remnic region "${start.name}"`);
+    }
+  }
+
+  for (const end of ends) {
+    if (usedEnds.has(end.start)) continue;
+    const startBefore = starts.some((start) => start.start < end.start);
+    if (!startBefore) intervals.push({ start: 0, end: eatTrailingNewline(text, end.end) });
+  }
+
+  return { intervals: mergeIntervals(intervals), warnings };
+}
+
+function eatTrailingNewline(text: string, index: number): number {
+  if (text[index] === "\n") return index + 1;
+  if (text[index] === "\r" && text[index + 1] === "\n") return index + 2;
+  if (text[index] === "\r") return index + 1;
+  return index;
+}
+
+function mergeIntervals(items: Array<{ start: number; end: number }>): Array<{ start: number; end: number }> {
+  if (items.length === 0) return [];
+  const sorted = items.slice().sort((a, b) => a.start - b.start || a.end - b.end);
+  const out = [{ start: sorted[0]!.start, end: sorted[0]!.end }];
+  for (let i = 1; i < sorted.length; i++) {
+    const cur = sorted[i]!;
+    const last = out[out.length - 1]!;
+    if (cur.start <= last.end) last.end = Math.max(last.end, cur.end);
+    else out.push({ start: cur.start, end: cur.end });
+  }
+  return out;
+}
+
+function cutIntervals(
+  text: string,
+  found: { intervals: Array<{ start: number; end: number }>; warnings: string[] },
+): { text: string; warnings: string[] } {
+  let out = "";
+  let pos = 0;
+  for (const interval of found.intervals) {
+    if (interval.start > pos) out += text.slice(pos, interval.start);
+    pos = Math.max(pos, interval.end);
+  }
+  if (pos < text.length) out += text.slice(pos);
+  return { text: out, warnings: found.warnings };
+}
+
+function stripPublishHeadings(text: string, names: readonly string[]): string {
+  if (names.length === 0 || text.length === 0) return text;
+  const lines = text.split("\n");
+  const keep = lines.map(() => true);
+  for (let i = 0; i < lines.length; i++) {
+    if (!keep[i]) continue;
+    const heading = parseAtxHeading(lines[i]!);
+    if (!heading || !names.includes(heading.text)) continue;
+    keep[i] = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const next = parseAtxHeading(lines[j]!);
+      if (next && next.level <= heading.level) break;
+      keep[j] = false;
+    }
+  }
+  return lines.filter((_, i) => keep[i]).join("\n");
+}
+
+function trimNewlines(text: string): string {
+  let start = 0;
+  let end = text.length;
+  while (start < end && (text[start] === "\n" || text[start] === "\r")) start++;
+  while (end > start && (text[end - 1] === "\n" || text[end - 1] === "\r")) end--;
+  return text.slice(start, end);
+}

package/src/activity/journal.ts

@@ -87,7 +87,7 @@ function renderJournalSeed(date: string, cards: readonly JournalSeedCard[]): str
 }
 
 /** The only journal write. Stats first; existing files are a no-op unless force. */
-function writeJournalFile(filePath: string, content: string, force: boolean): boolean {
+export function writeJournalFile(filePath: string, content: string, force: boolean): boolean {
   let exists = false;
   try {
     statSync(filePath);

package/src/activity/timeline/analysis-batch.test.ts

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { batchObservations } from "./analysis-batch.js";
+import type { TimelineBatchObservation } from "./analysis-batch.js";
+
+function obs(id: number, capturedAtUtc: string): TimelineBatchObservation {
+  return { id, capturedAtUtc };
+}
+
+test("empty observations return no batches", () => {
+  assert.deepEqual(batchObservations([], { maxBatch: 3, overlap: 1 }), []);
+});
+
+test("maxBatch 0 returns no batches", () => {
+  assert.deepEqual(
+    batchObservations([obs(1, "2026-08-17T10:00:00.000Z")], { maxBatch: 0, overlap: 0 }),
+    [],
+  );
+});
+
+test("overlap shares the trailing window with the next batch", () => {
+  const items = [1, 2, 3, 4, 5].map((id) => obs(id, `2026-08-17T10:0${id}:00.000Z`));
+  const batches = batchObservations(items, { maxBatch: 3, overlap: 1 });
+  assert.deepEqual(
+    batches.map((batch) => batch.map((item) => item.id)),
+    [
+      [1, 2, 3],
+      [3, 4, 5],
+    ],
+  );
+});
+
+test("order is capturedAtUtc then id, not input order", () => {
+  const items = [
+    obs(3, "2026-08-17T12:00:00.000Z"),
+    obs(2, "2026-08-17T10:00:00.000Z"),
+    obs(1, "2026-08-17T10:00:00.000Z"),
+  ];
+  const batches = batchObservations(items, { maxBatch: 3, overlap: 0 });
+  assert.deepEqual(
+    batches.map((batch) => batch.map((item) => item.id)),
+    [[1, 2, 3]],
+  );
+});
+
+test("maxBatch below 1 is rejected except 0", () => {
+  assert.throws(() => batchObservations([], { maxBatch: -1, overlap: 0 }), RangeError);
+  assert.throws(() => batchObservations([], { maxBatch: 0.5, overlap: 0 }), RangeError);
+});
+
+test("negative overlap and overlap covering the batch are rejected", () => {
+  assert.throws(() => batchObservations([], { maxBatch: 3, overlap: -1 }), RangeError);
+  assert.throws(() => batchObservations([], { maxBatch: 3, overlap: 3 }), RangeError);
+  assert.throws(() => batchObservations([], { maxBatch: 3, overlap: 4 }), RangeError);
+});

package/src/activity/timeline/analysis-batch.ts

@@ -0,0 +1,45 @@
+/**
+ * Bounded overlapping observation batches for timeline analysis (issue #2050).
+ */
+import type { TimelineObservation } from "./types.js";
+
+export type TimelineBatchObservation = Pick<TimelineObservation, "id" | "capturedAtUtc">;
+
+export interface BatchObservationsOptions {
+  maxBatch: number;
+  overlap: number;
+}
+
+function compareObservations(a: TimelineBatchObservation, b: TimelineBatchObservation): number {
+  const time = Date.parse(a.capturedAtUtc) - Date.parse(b.capturedAtUtc);
+  if (time !== 0) return time;
+  return a.id - b.id;
+}
+
+/** Split observations into overlapping windows. Order is capturedAtUtc, then id. */
+export function batchObservations<T extends TimelineBatchObservation>(
+  observations: readonly T[],
+  options: BatchObservationsOptions,
+): T[][] {
+  const { maxBatch, overlap } = options;
+  if (!Number.isInteger(overlap) || overlap < 0) {
+    throw new RangeError("overlap must be a non-negative integer");
+  }
+  if (maxBatch === 0) return [];
+  if (!Number.isInteger(maxBatch) || maxBatch < 1) {
+    throw new RangeError("maxBatch must be 0 or a positive integer");
+  }
+  if (overlap >= maxBatch) {
+    throw new RangeError("overlap must be less than maxBatch");
+  }
+  if (observations.length === 0) return [];
+
+  const ordered = [...observations].sort(compareObservations);
+  const step = maxBatch - overlap;
+  const batches: T[][] = [];
+  for (let start = 0; start < ordered.length; start += step) {
+    batches.push(ordered.slice(start, start + maxBatch));
+    if (start + maxBatch >= ordered.length) break;
+  }
+  return batches;
+}