@remnic/core 9.66.1 → 9.66.3

package/src/activity/privacy-window.test.ts

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MS_PER_DAY } from "./privacy.js";
+import { filterPrivacyWindow } from "./privacy-window.js";
+
+function item(capturedAtMs: number, id = capturedAtMs) {
+  return { id, capturedAtMs };
+}
+
+test("window is half-open [fromMs, toMs)", () => {
+  const fromMs = 1_000;
+  const toMs = 2_000;
+  const kept = filterPrivacyWindow(
+    [item(fromMs - 1), item(fromMs), item(toMs - 1), item(toMs)],
+    { fromMs, toMs, retainDays: 0 },
+  );
+  assert.deepEqual(
+    kept.map((entry) => entry.capturedAtMs),
+    [fromMs, toMs - 1],
+  );
+});
+
+test("retainDays 0 keeps all ages inside the window", () => {
+  const toMs = 400 * MS_PER_DAY;
+  const old = item(toMs - 390 * MS_PER_DAY, 1);
+  const kept = filterPrivacyWindow([old], { fromMs: 0, toMs, retainDays: 0 });
+  assert.deepEqual(kept, [old]);
+});
+
+test("retainDays N drops older than N days before toMs", () => {
+  const toMs = 10 * MS_PER_DAY;
+  const fromMs = 0;
+  const cutoff = toMs - 3 * MS_PER_DAY;
+  const kept = filterPrivacyWindow(
+    [item(cutoff - 1, 1), item(cutoff, 2), item(cutoff + 1, 3), item(toMs - 1, 4)],
+    { fromMs, toMs, retainDays: 3 },
+  );
+  assert.deepEqual(
+    kept.map((entry) => entry.id),
+    [3, 4],
+  );
+});
+
+test("empty items or inverted window return []", () => {
+  assert.deepEqual(filterPrivacyWindow([], { fromMs: 0, toMs: 10, retainDays: 0 }), []);
+  assert.deepEqual(filterPrivacyWindow([item(5)], { fromMs: 10, toMs: 10, retainDays: 0 }), []);
+  assert.deepEqual(filterPrivacyWindow([item(5)], { fromMs: 10, toMs: 0, retainDays: 0 }), []);
+});

package/src/activity/privacy-window.ts

@@ -0,0 +1,32 @@
+/**
+ * Half-open activity privacy window (issue #2053).
+ */
+import { shouldRetain } from "./privacy.js";
+
+export interface PrivacyWindowItem {
+  capturedAtMs: number;
+}
+
+export interface PrivacyWindowOptions {
+  fromMs: number;
+  toMs: number;
+  retainDays: number;
+}
+
+/**
+ * Keep items in `[fromMs, toMs)`.
+ * `retainDays` 0 keeps all ages. `retainDays` N drops older than N days before `toMs`.
+ * `toMs <= fromMs` returns `[]`.
+ */
+export function filterPrivacyWindow<T extends PrivacyWindowItem>(
+  items: readonly T[],
+  options: PrivacyWindowOptions,
+): T[] {
+  const { fromMs, toMs, retainDays } = options;
+  if (toMs <= fromMs) return [];
+  return items.filter((item) => {
+    const capturedAtMs = item.capturedAtMs;
+    if (capturedAtMs < fromMs || capturedAtMs >= toMs) return false;
+    return shouldRetain(capturedAtMs, toMs, retainDays);
+  });
+}

package/src/activity/retain-days.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseRetainDays } from "./retain-days.js";
+
+test("retainDays 0 keeps forever", () => {
+  assert.equal(parseRetainDays(0), 0);
+});
+
+test("retainDays 7 is accepted", () => {
+  assert.equal(parseRetainDays(7), 7);
+});
+
+test("negative retainDays throws", () => {
+  assert.throws(() => parseRetainDays(-1), /non-negative integer/);
+});
+
+test("float retainDays throws", () => {
+  assert.throws(() => parseRetainDays(1.5), /non-negative integer/);
+});

package/src/activity/retain-days.ts

@@ -0,0 +1,14 @@
+/**
+ * Parse activity retain-days (issue #2053 leftover).
+ *
+ * `0` keeps forever. Finite integer ≥ 0 is returned.
+ * Negative and non-integer values throw.
+ */
+export function parseRetainDays(value: number): number {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new RangeError(
+      `activity.retainDays must be a non-negative integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}

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

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

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseClaimObservationId } from "./analysis-claim.js";
+
+test("ok claim returns trimmed observationId", () => {
+  assert.deepEqual(parseClaimObservationId({ observationId: "obs-1" }), {
+    ok: true,
+    observationId: "obs-1",
+  });
+});
+
+test("missing observationId is missing_observation", () => {
+  assert.deepEqual(parseClaimObservationId({}), { ok: false, error: "missing_observation" });
+});
+
+test("empty observationId is missing_observation", () => {
+  assert.deepEqual(parseClaimObservationId({ observationId: "" }), {
+    ok: false,
+    error: "missing_observation",
+  });
+});
+
+test("trims observationId and treats whitespace as missing", () => {
+  assert.deepEqual(parseClaimObservationId({ observationId: "  obs-1  " }), {
+    ok: true,
+    observationId: "obs-1",
+  });
+  assert.deepEqual(parseClaimObservationId({ observationId: "   " }), {
+    ok: false,
+    error: "missing_observation",
+  });
+});

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

@@ -0,0 +1,16 @@
+/**
+ * Parse a timeline analysis claim's observationId (issue #2050).
+ */
+export type ParseClaimObservationIdResult =
+  | { ok: true; observationId: string }
+  | { ok: false; error: "missing_observation" };
+
+export function parseClaimObservationId(claim: {
+  observationId?: string | null;
+}): ParseClaimObservationIdResult {
+  const raw = claim.observationId;
+  if (raw == null) return { ok: false, error: "missing_observation" };
+  const observationId = raw.trim();
+  if (observationId.length === 0) return { ok: false, error: "missing_observation" };
+  return { ok: true, observationId };
+}

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

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { dedupeObservationIds } from "./analysis-dup.js";
+
+test("empty input returns an empty array", () => {
+  assert.deepEqual(dedupeObservationIds([]), []);
+});
+
+test("keeps first-seen order and drops later duplicates", () => {
+  assert.deepEqual(dedupeObservationIds(["obs-b", "obs-a", "obs-b", "obs-c", "obs-a"]), [
+    "obs-b",
+    "obs-a",
+    "obs-c",
+  ]);
+});
+
+test("does not mutate the input array", () => {
+  const input = ["obs-b", "obs-a", "obs-b"];
+  const snapshot = input.slice();
+  const deduped = dedupeObservationIds(input);
+  assert.deepEqual(input, snapshot);
+  assert.notEqual(deduped, input);
+});
+
+test("drops empty strings", () => {
+  assert.deepEqual(dedupeObservationIds(["b", "", "a", "", "b"]), ["b", "a"]);
+});

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

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

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

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

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

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

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