@remnic/core 9.66.2 → 9.66.4

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

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { boundEvidence } from "./analysis-evidence.js";
+
+function claim(observationId: number, title: string) {
+  return { observationId, title };
+}
+
+function observation(id: number) {
+  return { id };
+}
+
+test("drops claims whose observationId is missing", () => {
+  const kept = boundEvidence(
+    [claim(1, "first"), claim(99, "ghost"), claim(2, "second")],
+    [observation(1), observation(2)],
+  );
+  assert.deepEqual(kept, [claim(1, "first"), claim(2, "second")]);
+});
+
+test("keeps claim order", () => {
+  const kept = boundEvidence(
+    [claim(3, "third"), claim(1, "first"), claim(2, "second")],
+    [observation(1), observation(2), observation(3)],
+  );
+  assert.deepEqual(kept, [claim(3, "third"), claim(1, "first"), claim(2, "second")]);
+});
+
+test("empty observations return no claims", () => {
+  assert.deepEqual(boundEvidence([claim(1, "first")], []), []);
+});

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

@@ -0,0 +1,20 @@
+/**
+ * Drop analysis claims that do not cite a supplied observation (issue #2050).
+ */
+export interface TimelineEvidenceClaim {
+  observationId: number;
+}
+
+export interface TimelineEvidenceObservation {
+  id: number;
+}
+
+/** Keep claims whose observationId is present. Preserve claim order. */
+export function boundEvidence<T extends TimelineEvidenceClaim>(
+  claims: readonly T[],
+  observations: readonly TimelineEvidenceObservation[],
+): T[] {
+  if (observations.length === 0) return [];
+  const ids = new Set(observations.map((observation) => observation.id));
+  return claims.filter((claim) => ids.has(claim.observationId));
+}

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

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseMaxBatch } from "./analysis-max.js";
+
+test("maxBatch 0 is allowed", () => {
+  assert.equal(parseMaxBatch(0), 0);
+});
+
+test("maxBatch 8 is returned", () => {
+  assert.equal(parseMaxBatch(8), 8);
+});
+
+test("negative maxBatch throws", () => {
+  assert.throws(() => parseMaxBatch(-1), /non-negative integer/);
+});
+
+test("float maxBatch throws", () => {
+  assert.throws(() => parseMaxBatch(1.5), /non-negative integer/);
+});
+
+test("non-number maxBatch throws RangeError", () => {
+  for (const bad of ["8", undefined, Number.NaN, null]) {
+    assert.throws(() => parseMaxBatch(bad), RangeError);
+  }
+});

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

@@ -0,0 +1,14 @@
+/**
+ * Timeline analysis max-batch parse (issue #2050 leftover).
+ *
+ * Pure. 0 is allowed (empty batches). Negative or non-integer throws.
+ * Finite integer ≥ 0 is returned.
+ */
+export function parseMaxBatch(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new RangeError(
+      `analysis maxBatch must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}

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

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { sortObservationIds } from "./analysis-order.js";
+
+test("empty input returns an empty array", () => {
+  assert.deepEqual(sortObservationIds([]), []);
+});
+
+test("sorts ids with localeCompare", () => {
+  assert.deepEqual(sortObservationIds(["obs-c", "obs-a", "obs-b"]), [
+    "obs-a",
+    "obs-b",
+    "obs-c",
+  ]);
+});
+
+test("does not mutate the input array", () => {
+  const input = ["obs-c", "obs-a"];
+  const snapshot = input.slice();
+  const sorted = sortObservationIds(input);
+  assert.deepEqual(input, snapshot);
+  assert.notEqual(sorted, input);
+});
+
+test("drops empty strings", () => {
+  assert.deepEqual(sortObservationIds(["b", "", "a", ""]), ["a", "b"]);
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Stable observation-id order for timeline analysis (issue #2050 leftover).
+ *
+ * localeCompare sort. Empty input → []. Does not mutate input. Drops empty strings.
+ */
+
+/** Return a new localeCompare-sorted id list. Empty strings are dropped. */
+export function sortObservationIds(ids: readonly string[]): string[] {
+  return ids.filter((id) => id !== "").sort((a, b) => a.localeCompare(b));
+}

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

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseOverlap } from "./analysis-overlap.js";
+
+test("overlap 0 is allowed", () => {
+  assert.equal(parseOverlap(0, 8), 0);
+  assert.equal(parseOverlap(0, 0), 0);
+});
+
+test("overlap 3 with maxBatch 8 is returned", () => {
+  assert.equal(parseOverlap(3, 8), 3);
+});
+
+test("overlap >= maxBatch throws when maxBatch > 0", () => {
+  assert.throws(() => parseOverlap(8, 8), /less than maxBatch/);
+  assert.throws(() => parseOverlap(5, 4), /less than maxBatch/);
+});
+
+test("negative overlap throws", () => {
+  assert.throws(() => parseOverlap(-1, 8), /non-negative integer/);
+});
+
+test("float overlap throws", () => {
+  assert.throws(() => parseOverlap(1.5, 8), /non-negative integer/);
+});

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

@@ -0,0 +1,17 @@
+/**
+ * Timeline analysis overlap parse (issue #2050 leftover).
+ *
+ * Pure. 0 is allowed. Negative or non-integer throws.
+ * When maxBatch > 0, overlap must be less than maxBatch.
+ */
+export function parseOverlap(value: unknown, maxBatch: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new RangeError(
+      `analysis overlap must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  if (maxBatch > 0 && value >= maxBatch) {
+    throw new RangeError(`analysis overlap must be less than maxBatch; got ${value} >= ${maxBatch}`);
+  }
+  return value;
+}

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

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildAnalysisPrompt } from "./analysis-prompt.js";
+
+test("empty observations render (empty)", () => {
+  const first = buildAnalysisPrompt({ observations: [] });
+  const second = buildAnalysisPrompt({ observations: [] });
+  assert.match(first, /\(empty\)/);
+  assert.equal(first, second);
+  assert.doesNotMatch(first, /\[\s*\{/);
+});
+
+test("observations sort by id, not input order", () => {
+  const prompt = buildAnalysisPrompt({
+    observations: [
+      { id: 3, capturedAtUtc: "2026-08-17T12:00:00.000Z" },
+      { id: 1, capturedAtUtc: "2026-08-17T10:00:00.000Z" },
+      { id: 2, capturedAtUtc: "2026-08-17T11:00:00.000Z" },
+    ],
+  });
+  const first = prompt.indexOf('"id":1');
+  const second = prompt.indexOf('"id":2');
+  const third = prompt.indexOf('"id":3');
+  assert.ok(first >= 0 && second > first && third > second);
+  assert.match(prompt, /2026-08-17T10:00:00.000Z/);
+  assert.match(prompt, /2026-08-17T11:00:00.000Z/);
+  assert.match(prompt, /2026-08-17T12:00:00.000Z/);
+});
+
+test("free-text body and extra fields do not leak", () => {
+  const prompt = buildAnalysisPrompt({
+    observations: [
+      {
+        id: 9,
+        capturedAtUtc: "2026-08-17T09:00:00.000Z",
+        body: "SECRET-BODY",
+        text: "SECRET-TEXT",
+        windowTitle: "SECRET-TITLE",
+        app: "SECRET-APP",
+      } as { id: number; capturedAtUtc: string },
+    ],
+  });
+  assert.equal(prompt.includes("SECRET-BODY"), false);
+  assert.equal(prompt.includes("SECRET-TEXT"), false);
+  assert.equal(prompt.includes("SECRET-TITLE"), false);
+  assert.equal(prompt.includes("SECRET-APP"), false);
+  assert.match(prompt, /"id":9/);
+  assert.match(prompt, /2026-08-17T09:00:00.000Z/);
+});

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

@@ -0,0 +1,24 @@
+/**
+ * Deterministic evidence-only analysis prompt (issue #2050).
+ * No LLM call. Prompt lists observation id and capturedAtUtc only.
+ */
+export type AnalysisPromptObservation = {
+  id: number;
+  capturedAtUtc: string;
+};
+
+const INSTRUCTIONS =
+  "Use only supplied evidence. Preserve chronology. Do not invent people, places, or tasks. Return strict JSON.";
+
+function listedObservation(observation: AnalysisPromptObservation): AnalysisPromptObservation {
+  return { id: observation.id, capturedAtUtc: observation.capturedAtUtc };
+}
+
+/** Build a deterministic prompt. Observations sort by id. Empty lists render as (empty). */
+export function buildAnalysisPrompt(input: {
+  observations: readonly AnalysisPromptObservation[];
+}): string {
+  const listed = [...input.observations].sort((a, b) => a.id - b.id).map(listedObservation);
+  const body = listed.length === 0 ? "(empty)" : JSON.stringify(listed);
+  return `${INSTRUCTIONS}\nObservations: ${body}`;
+}

package/src/activity/timeline/index.ts

@@ -10,4 +10,12 @@ export * from "./journal-recap-persist.js";
 export * from "./weekly.js";
 export * from "./weekly-persist.js";
 export * from "./analysis.js";
+export * from "./recap-export.js";
+export * from "./recap-markdown.js";
+export * from "./week-export.js";
+export * from "./week-snapshot.js";
 export * from "./analysis-batch.js";
+export * from "./analysis-evidence.js";
+export * from "./analysis-prompt.js";
+export * from "./analysis-claim.js";
+export * from "./analysis-order.js";

package/src/activity/timeline/recap-card-count.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { countRecapCards } from "./recap-card-count.js";
+
+test("empty list is 0", () => {
+  assert.equal(countRecapCards([]), 0);
+});
+
+test("counts unique ids", () => {
+  assert.equal(countRecapCards(["card-a", "card-b", "card-a"]), 2);
+  assert.equal(countRecapCards(["card-a", "card-b", "card-c"]), 3);
+});
+
+test("drops empty strings and does not mutate", () => {
+  const cards = ["card-a", "", "card-b", "", "card-a"];
+  assert.equal(countRecapCards(cards), 2);
+  assert.deepEqual(cards, ["card-a", "", "card-b", "", "card-a"]);
+});

package/src/activity/timeline/recap-card-count.ts

@@ -0,0 +1,13 @@
+/**
+ * Recap card counter (issue #2051 leftover).
+ *
+ * Unique ids after dropping empty strings. Does not mutate input.
+ */
+
+export function countRecapCards(cards: readonly string[]): number {
+  const unique = new Set<string>();
+  for (const id of cards) {
+    if (id !== "") unique.add(id);
+  }
+  return unique.size;
+}

package/src/activity/timeline/recap-card-id.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseRecapCardId } from "./recap-card-id.js";
+
+test("ok card id returns trimmed id", () => {
+  assert.deepEqual(parseRecapCardId("card-1"), { ok: true, id: "card-1" });
+});
+
+test("empty card id is missing_id", () => {
+  assert.deepEqual(parseRecapCardId(""), { ok: false, error: "missing_id" });
+  assert.deepEqual(parseRecapCardId("   "), { ok: false, error: "missing_id" });
+});
+
+test("newline in card id is invalid_id", () => {
+  assert.deepEqual(parseRecapCardId("card-1\ncard-2"), { ok: false, error: "invalid_id" });
+});
+
+test("trims surrounding whitespace", () => {
+  assert.deepEqual(parseRecapCardId("  card-1  "), { ok: true, id: "card-1" });
+});

package/src/activity/timeline/recap-card-id.ts

@@ -0,0 +1,16 @@
+/**
+ * Parse a recap card id (issue #2051 leftover).
+ *
+ * Pure. Empty is missing_id. Newline is invalid_id.
+ */
+
+export type ParseRecapCardIdResult =
+  | { ok: true; id: string }
+  | { ok: false; error: "missing_id" | "invalid_id" };
+
+export function parseRecapCardId(value: string): ParseRecapCardIdResult {
+  const id = value.trim();
+  if (id.length === 0) return { ok: false, error: "missing_id" };
+  if (id.includes("\n")) return { ok: false, error: "invalid_id" };
+  return { ok: true, id };
+}

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseRecapDate } from "./recap-date.js";
+
+test("accepts a trimmed YYYY-MM-DD date", () => {
+  assert.deepEqual(parseRecapDate("2026-08-19"), { ok: true, date: "2026-08-19" });
+  assert.deepEqual(parseRecapDate("  2026-08-19  "), { ok: true, date: "2026-08-19" });
+});
+
+test("empty and whitespace-only values are missing_date", () => {
+  assert.deepEqual(parseRecapDate(""), { ok: false, error: "missing_date" });
+  assert.deepEqual(parseRecapDate("   "), { ok: false, error: "missing_date" });
+});
+
+test("rejects strings that are not YYYY-MM-DD", () => {
+  assert.deepEqual(parseRecapDate("20260819"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseRecapDate("2026-8-19"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseRecapDate("2026-08-19T00:00:00Z"), { ok: false, error: "invalid_date" });
+  assert.deepEqual(parseRecapDate("not-a-date"), { ok: false, error: "invalid_date" });
+});

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

@@ -0,0 +1,19 @@
+/**
+ * Parse a recap local-day string (issue #2051 leftover).
+ *
+ * Trim first. Empty → missing_date. Bounded YYYY-MM-DD only (no ReDoS).
+ */
+
+export type RecapDateResult =
+  | { ok: true; date: string }
+  | { ok: false; error: "missing_date" | "invalid_date" };
+
+const RECAP_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Trim and accept YYYY-MM-DD, or return a typed error. */
+export function parseRecapDate(value: string): RecapDateResult {
+  const date = value.trim();
+  if (date.length === 0) return { ok: false, error: "missing_date" };
+  if (!RECAP_DATE.test(date)) return { ok: false, error: "invalid_date" };
+  return { ok: true, date };
+}

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

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isEmptyRecapCards } from "./recap-empty.js";
+
+test("null, undefined, and empty array are empty", () => {
+  assert.equal(isEmptyRecapCards(null), true);
+  assert.equal(isEmptyRecapCards(undefined), true);
+  assert.equal(isEmptyRecapCards([]), true);
+});
+
+test("a non-empty array is not empty", () => {
+  assert.equal(isEmptyRecapCards([{ id: 1 }]), false);
+  assert.equal(isEmptyRecapCards([0]), false);
+});
+
+test("a non-array throws", () => {
+  assert.throws(() => isEmptyRecapCards({}), TypeError);
+  assert.throws(() => isEmptyRecapCards("cards"), TypeError);
+  assert.throws(() => isEmptyRecapCards(1), TypeError);
+});

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

@@ -0,0 +1,14 @@
+/**
+ * Empty-set guard for timeline recap cards (issue #2051 leftover).
+ *
+ * null, undefined, and [] are empty. A non-array throws. Any other array is not empty.
+ */
+
+/** True when the recap card list is absent or has no items. */
+export function isEmptyRecapCards(cards: unknown): boolean {
+  if (cards == null) return true;
+  if (!Array.isArray(cards)) {
+    throw new TypeError("cards must be an array");
+  }
+  return cards.length === 0;
+}

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

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { TimelineCard } from "./types.js";
+import { exportDeterministicRecap } from "./recap-export.js";
+
+const DATE = "2026-08-17";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Title",
+    summary: "Summary",
+    categoryId: "work",
+    confidence: 0.9,
+    startUtc: "2026-08-17T09:00:00.000Z",
+    endUtc: "2026-08-17T10:00:00.000Z",
+    dayKey: DATE,
+    timezone: "UTC",
+    machine: "machine-a",
+    evidenceIds: [1],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+test("empty cards export date and timezone with an empty card list", () => {
+  const recap = exportDeterministicRecap({
+    date: DATE,
+    timezone: "UTC",
+    cards: [],
+  });
+  assert.deepEqual(recap, { date: DATE, timezone: "UTC", cards: [] });
+  assert.equal(JSON.stringify(recap), `{"date":"${DATE}","timezone":"UTC","cards":[]}`);
+});
+
+test("cards are sorted by id regardless of input order", () => {
+  const recap = exportDeterministicRecap({
+    date: DATE,
+    timezone: "UTC",
+    cards: [
+      card({ id: "card-c" }),
+      card({ id: "card-a" }),
+      card({ id: "card-b" }),
+    ],
+  });
+  assert.deepEqual(
+    recap.cards.map((c) => c.id),
+    ["card-a", "card-b", "card-c"],
+  );
+});
+
+test("timezone is echoed verbatim, not normalized", () => {
+  const recap = exportDeterministicRecap({
+    date: DATE,
+    timezone: "America/Chicago",
+    cards: [],
+  });
+  assert.equal(recap.timezone, "America/Chicago");
+});
+
+test("input cards are not mutated and reruns are stable", () => {
+  const input = [card({ id: "card-b" }), card({ id: "card-a" })];
+  const first = exportDeterministicRecap({
+    date: DATE,
+    timezone: "UTC",
+    cards: input,
+  });
+  const second = exportDeterministicRecap({
+    date: DATE,
+    timezone: "UTC",
+    cards: input,
+  });
+  assert.deepEqual(input.map((c) => c.id), ["card-b", "card-a"]);
+  assert.equal(JSON.stringify(first), JSON.stringify(second));
+});

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

@@ -0,0 +1,41 @@
+/**
+ * Deterministic machine-readable recap export from timeline cards (issue #2051).
+ *
+ * Pure: cards + date + timezone in, stable JSON out. No LLM, no I/O, no
+ * persistence. Same cards always serialize to the same bytes, regardless of
+ * input array order: cards are sorted by id before serialization.
+ */
+import type { TimelineCard } from "./types.js";
+
+export interface DeterministicRecapOptions {
+  date: string;
+  timezone: string;
+  cards: readonly TimelineCard[];
+}
+
+export interface DeterministicRecap {
+  date: string;
+  timezone: string;
+  cards: TimelineCard[];
+}
+
+function compareCardIds(a: TimelineCard, b: TimelineCard): number {
+  if (a.id < b.id) return -1;
+  if (a.id > b.id) return 1;
+  return 0;
+}
+
+/**
+ * Build the byte-stable JSON recap document for one local day.
+ * Callers may `JSON.stringify` the returned object; construction order
+ * (date, timezone, cards) is fixed, so serialization is deterministic.
+ */
+export function exportDeterministicRecap(
+  options: DeterministicRecapOptions,
+): DeterministicRecap {
+  return {
+    date: options.date,
+    timezone: options.timezone,
+    cards: [...options.cards].sort(compareCardIds),
+  };
+}

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

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { sortRecapCardIds } from "./recap-id.js";
+
+test("empty input returns an empty array", () => {
+  assert.deepEqual(sortRecapCardIds([]), []);
+});
+
+test("sorts ids with localeCompare", () => {
+  assert.deepEqual(sortRecapCardIds(["card-c", "card-a", "card-b"]), [
+    "card-a",
+    "card-b",
+    "card-c",
+  ]);
+});
+
+test("does not mutate the input array", () => {
+  const input = ["card-c", "card-a"];
+  const snapshot = input.slice();
+  const sorted = sortRecapCardIds(input);
+  assert.deepEqual(input, snapshot);
+  assert.notEqual(sorted, input);
+});
+
+test("drops empty strings", () => {
+  assert.deepEqual(sortRecapCardIds(["b", "", "a", ""]), ["a", "b"]);
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Stable recap card-id order (issue #2051 leftover).
+ *
+ * localeCompare sort. Empty input → []. Does not mutate input. Drops empty strings.
+ */
+
+/** Return a new localeCompare-sorted id list. Empty strings are dropped. */
+export function sortRecapCardIds(ids: readonly string[]): string[] {
+  return ids.filter((id) => id !== "").sort((a, b) => a.localeCompare(b));
+}

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

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderRecapMarkdown } from "./recap-markdown.js";
+import type { TimelineCard } from "./types.js";
+
+const DATE = "2026-08-17";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "Title",
+    summary: "Summary",
+    categoryId: "work",
+    confidence: 0.9,
+    startUtc: "2026-08-17T09:00:00.000Z",
+    endUtc: "2026-08-17T10:00:00.000Z",
+    dayKey: DATE,
+    timezone: "UTC",
+    machine: "machine-a",
+    evidenceIds: [1],
+    evidenceRange: null,
+    ...overrides,
+  };
+}
+
+test("empty cards print heading plus (empty)", () => {
+  assert.equal(
+    renderRecapMarkdown({ date: DATE, timezone: "UTC", cards: [] }),
+    [`# Recap — ${DATE} (UTC)`, "", "(empty)", ""].join("\n"),
+  );
+});
+
+test("cards are sorted by id regardless of input order", () => {
+  const input = [card({ id: "card-c" }), card({ id: "card-a" }), card({ id: "card-b" })];
+  const first = renderRecapMarkdown({ date: DATE, timezone: "UTC", cards: input });
+  const second = renderRecapMarkdown({ date: DATE, timezone: "UTC", cards: input });
+  assert.equal(
+    first,
+    [`# Recap — ${DATE} (UTC)`, "", "- card-a", "- card-b", "- card-c", ""].join("\n"),
+  );
+  assert.deepEqual(
+    input.map((row) => row.id),
+    ["card-c", "card-a", "card-b"],
+  );
+  assert.equal(first, second);
+});
+
+test("timezone is echoed verbatim, not normalized", () => {
+  assert.equal(
+    renderRecapMarkdown({ date: DATE, timezone: "America/Chicago", cards: [] }),
+    [`# Recap — ${DATE} (America/Chicago)`, "", "(empty)", ""].join("\n"),
+  );
+});