@remnic/core 9.68.0 → 9.69.1

package/src/activity/timeline/week-recurring.test.ts

@@ -0,0 +1,177 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DEFAULT_RECURRENCE_MIN_DAYS,
+  MIN_RECURRENCE_MIN_DAYS,
+  findRecurringPatterns,
+  type WeekDayOccurrence,
+} from "./week-recurring.js";
+
+function rangeErrorMatching(pattern: RegExp): (err: unknown) => boolean {
+  return (err: unknown) => err instanceof RangeError && pattern.test((err as Error).message);
+}
+
+test("default minDays is 3; a key on exactly minDays distinct dates qualifies", () => {
+  assert.equal(DEFAULT_RECURRENCE_MIN_DAYS, 3);
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 100 },
+      { date: "2026-08-11", key: "code", durationMs: 100 },
+      { date: "2026-08-12", key: "code", durationMs: 100 },
+    ],
+  });
+  assert.deepEqual(result, [{ key: "code", dayCount: 3, totalDurationMs: 300 }]);
+});
+
+test("a key on minDays - 1 distinct dates does not qualify", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 999_999 },
+      { date: "2026-08-11", key: "code", durationMs: 999_999 },
+    ],
+  });
+  assert.deepEqual(result, []);
+});
+
+test("same-date occurrences count as one day but all durations sum", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 100 },
+      { date: "2026-08-10", key: "code", durationMs: 40 },
+      { date: "2026-08-11", key: "code", durationMs: 100 },
+      { date: "2026-08-12", key: "code", durationMs: 100 },
+    ],
+  });
+  assert.deepEqual(result, [{ key: "code", dayCount: 3, totalDurationMs: 340 }]);
+});
+
+test("blank keys are ignored", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "", durationMs: 100 },
+      { date: "2026-08-11", key: "   ", durationMs: 100 },
+      { date: "2026-08-12", key: "\t", durationMs: 100 },
+    ],
+  });
+  assert.deepEqual(result, []);
+});
+
+test("keys are compared trimmed and case-sensitively", () => {
+  const result = findRecurringPatterns({
+    occurrences: [
+      { date: "2026-08-10", key: "code", durationMs: 100 },
+      { date: "2026-08-11", key: " code ", durationMs: 100 },
+      { date: "2026-08-12", key: "code", durationMs: 100 },
+      { date: "2026-08-10", key: "Code", durationMs: 100 },
+      { date: "2026-08-11", key: "Code", durationMs: 100 },
+    ],
+  });
+  // " code " folds into "code" (3 distinct days); "Code" stays separate at 2 days.
+  assert.deepEqual(result, [{ key: "code", dayCount: 3, totalDurationMs: 300 }]);
+});
+
+test("minDays must be an integer >= MIN_RECURRENCE_MIN_DAYS", () => {
+  for (const bad of [0, 1, -3, 1.5]) {
+    assert.throws(
+      () => findRecurringPatterns({ occurrences: [], minDays: bad }),
+      rangeErrorMatching(/minDays/),
+    );
+  }
+  assert.doesNotThrow(() =>
+    findRecurringPatterns({
+      occurrences: [{ date: "2026-08-10", key: "code", durationMs: 1 }],
+      minDays: MIN_RECURRENCE_MIN_DAYS,
+    }),
+  );
+});
+
+// minDays 1 would make a single-day key "recurring", which is the invariant
+// this helper exists to enforce — configuration must not be able to disable it.
+test("minDays 1 is refused rather than reporting one-off keys", () => {
+  assert.throws(
+    () =>
+      findRecurringPatterns({
+        occurrences: [{ date: "2026-08-10", key: "code", durationMs: 5 }],
+        minDays: 1,
+      }),
+    rangeErrorMatching(/minDays/),
+  );
+  assert.equal(MIN_RECURRENCE_MIN_DAYS, 2);
+});
+
+test("durationMs must be a finite number >= 0", () => {
+  for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, -1]) {
+    assert.throws(
+      () =>
+        findRecurringPatterns({
+          occurrences: [{ date: "2026-08-10", key: "code", durationMs: bad }],
+        }),
+      rangeErrorMatching(/durationMs/),
+    );
+  }
+});
+
+test("date must be a valid YYYY-MM-DD calendar date", () => {
+  for (const bad of ["", "not-a-date", "2026-8-10", "2026-02-30"]) {
+    assert.throws(
+      () =>
+        findRecurringPatterns({
+          occurrences: [{ date: bad, key: "code", durationMs: 0 }],
+        }),
+      rangeErrorMatching(/date/),
+    );
+  }
+});
+
+test("ordering: dayCount desc, then totalDurationMs desc, then key asc", () => {
+  const result = findRecurringPatterns({
+    minDays: 2,
+    occurrences: [
+      // alpha: 2 days, biggest total — dayCount still ranks it last.
+      { date: "2026-08-10", key: "alpha", durationMs: 999_999 },
+      { date: "2026-08-11", key: "alpha", durationMs: 999_999 },
+      // beta: 3 days, 10 total — wins the dayCount tie on duration.
+      { date: "2026-08-10", key: "beta", durationMs: 4 },
+      { date: "2026-08-11", key: "beta", durationMs: 4 },
+      { date: "2026-08-12", key: "beta", durationMs: 2 },
+      // gamma: 3 days, 8 total — ties delta on both, loses on key ascending.
+      { date: "2026-08-10", key: "gamma", durationMs: 8 },
+      { date: "2026-08-11", key: "gamma", durationMs: 0 },
+      { date: "2026-08-12", key: "gamma", durationMs: 0 },
+      // delta: 3 days, 8 total.
+      { date: "2026-08-10", key: "delta", durationMs: 8 },
+      { date: "2026-08-11", key: "delta", durationMs: 0 },
+      { date: "2026-08-12", key: "delta", durationMs: 0 },
+    ],
+  });
+  assert.deepEqual(result.map((p) => p.key), ["beta", "delta", "gamma", "alpha"]);
+  assert.deepEqual(result[0], { key: "beta", dayCount: 3, totalDurationMs: 10 });
+  assert.deepEqual(result[3], { key: "alpha", dayCount: 2, totalDurationMs: 1_999_998 });
+});
+
+test("empty input and no-qualifier input return []", () => {
+  assert.deepEqual(findRecurringPatterns({ occurrences: [] }), []);
+  assert.deepEqual(
+    findRecurringPatterns({
+      occurrences: [{ date: "2026-08-10", key: "code", durationMs: 5000 }],
+    }),
+    [],
+  );
+});
+
+test("pure: two calls deep-equal and the input is not mutated", () => {
+  const occurrences: WeekDayOccurrence[] = [
+    { date: "2026-08-10", key: "code", durationMs: 100 },
+    { date: "2026-08-10", key: "code", durationMs: 50 },
+    { date: "2026-08-11", key: "mail", durationMs: 10 },
+    { date: "2026-08-11", key: "code", durationMs: 100 },
+    { date: "2026-08-12", key: "code", durationMs: 100 },
+  ];
+  const snapshot = structuredClone(occurrences);
+  const first = findRecurringPatterns({ occurrences });
+  const second = findRecurringPatterns({ occurrences });
+  assert.deepEqual(first, second);
+  assert.deepEqual(first, [{ key: "code", dayCount: 3, totalDurationMs: 350 }]);
+  assert.deepEqual(occurrences, snapshot);
+});

package/src/activity/timeline/week-recurring.ts

@@ -0,0 +1,88 @@
+/**
+ * Recurring weekly pattern gate (issue #2052).
+ *
+ * A category/application key counts as recurring only when it appeared on at
+ * least `minDays` DISTINCT days of the analyzed week, so a one-off blip is
+ * never reported as a pattern. Pure: no I/O, no clock, no input mutation.
+ * Validation happens on the exact occurrence values before any key trimming
+ * (AGENTS.md: validate before normalizing; reject non-finite numbers
+ * explicitly instead of letting NaN fall through a comparison).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+export const DEFAULT_RECURRENCE_MIN_DAYS = 3;
+
+/** Lowest threshold that still means "recurring": two distinct days. */
+export const MIN_RECURRENCE_MIN_DAYS = 2;
+
+export interface WeekDayOccurrence {
+  /** YYYY-MM-DD inside the analyzed week. */
+  date: string;
+  /** Category id or application/domain label. */
+  key: string;
+  durationMs: number;
+}
+
+export interface RecurringPattern {
+  key: string;
+  /** Count of DISTINCT days the key appeared on. */
+  dayCount: number;
+  totalDurationMs: number;
+}
+
+export function findRecurringPatterns(input: {
+  occurrences: readonly WeekDayOccurrence[];
+  minDays?: number;
+}): RecurringPattern[] {
+  const minDays = input.minDays ?? DEFAULT_RECURRENCE_MIN_DAYS;
+  // A floor of 2 is the module's defining invariant, not a preference: at
+  // minDays 1 every key that appeared once is "recurring", which is exactly
+  // the one-off blip this helper exists to exclude. Configuration must not be
+  // able to switch the invariant off.
+  if (!Number.isInteger(minDays) || minDays < MIN_RECURRENCE_MIN_DAYS) {
+    throw new RangeError(
+      `Invalid minDays ${minDays}; expected an integer >= ${MIN_RECURRENCE_MIN_DAYS}.`,
+    );
+  }
+
+  const daysByKey = new Map<string, Set<string>>();
+  const totalsByKey = new Map<string, number>();
+
+  for (const occurrence of input.occurrences) {
+    if (!isValidActivityDate(occurrence.date)) {
+      throw new RangeError(`Invalid date "${occurrence.date}"; expected YYYY-MM-DD.`);
+    }
+    if (
+      typeof occurrence.durationMs !== "number" ||
+      !Number.isFinite(occurrence.durationMs) ||
+      occurrence.durationMs < 0
+    ) {
+      throw new RangeError(`Invalid durationMs ${occurrence.durationMs}; expected a finite number >= 0.`);
+    }
+    const key = occurrence.key.trim();
+    if (key === "") continue;
+    let days = daysByKey.get(key);
+    if (!days) {
+      days = new Set<string>();
+      daysByKey.set(key, days);
+      totalsByKey.set(key, 0);
+    }
+    days.add(occurrence.date);
+    totalsByKey.set(key, totalsByKey.get(key)! + occurrence.durationMs);
+  }
+
+  const patterns: RecurringPattern[] = [];
+  for (const [key, days] of daysByKey) {
+    if (days.size < minDays) continue;
+    patterns.push({ key, dayCount: days.size, totalDurationMs: totalsByKey.get(key)! });
+  }
+
+  patterns.sort((a, b) => {
+    if (a.dayCount !== b.dayCount) return b.dayCount - a.dayCount;
+    if (a.totalDurationMs !== b.totalDurationMs) return b.totalDurationMs - a.totalDurationMs;
+    if (a.key < b.key) return -1;
+    if (a.key > b.key) return 1;
+    return 0;
+  });
+  return patterns;
+}

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

@@ -0,0 +1,138 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { VAULT_PUBLISH_OUTCOMES, summarizeVaultPublish } from "./vault-status.js";
+import type { VaultPublishResult } from "./vault-status.js";
+
+test("summarizeVaultPublish counts a mixed list, sorts by path, and flags the error", () => {
+  const status = summarizeVaultPublish([
+    { path: "notes/e.md", outcome: "updated" },
+    { path: "notes/d.md", outcome: "error", reason: "missing_file" },
+    { path: "notes/a.md", outcome: "updated" },
+    { path: "notes/c.md", outcome: "skipped", reason: "no_marker" },
+    { path: "notes/b.md", outcome: "unchanged" },
+  ]);
+  assert.deepEqual(status.counts, { updated: 2, unchanged: 1, skipped: 1, error: 1 });
+  assert.equal(status.hasError, true);
+  assert.deepEqual(status.results, [
+    { path: "notes/a.md", outcome: "updated" },
+    { path: "notes/b.md", outcome: "unchanged" },
+    { path: "notes/c.md", outcome: "skipped", reason: "no_marker" },
+    { path: "notes/d.md", outcome: "error", reason: "missing_file" },
+    { path: "notes/e.md", outcome: "updated" },
+  ]);
+});
+
+test("empty input returns zeroed counts, no results, and hasError false", () => {
+  const status = summarizeVaultPublish([]);
+  assert.deepEqual(status.counts, { updated: 0, unchanged: 0, skipped: 0, error: 0 });
+  for (const outcome of VAULT_PUBLISH_OUTCOMES) {
+    assert.equal(status.counts[outcome], 0, `count key ${outcome} must exist at zero`);
+  }
+  assert.deepEqual(status.results, []);
+  assert.equal(status.hasError, false);
+});
+
+test("unknown outcome throws TypeError listing the allow-list", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "deleted" }]),
+    (err: unknown) => {
+      assert.ok(err instanceof TypeError);
+      assert.match(err.message, /unknown vault publish outcome/);
+      for (const outcome of VAULT_PUBLISH_OUTCOMES) {
+        assert.ok(err.message.includes(outcome), `message lists ${outcome}`);
+      }
+      return true;
+    },
+  );
+});
+
+test("skipped without a reason throws TypeError", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "skipped" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+});
+
+test("error with a missing or whitespace-only reason throws TypeError", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "error" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "error", reason: "   " }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+});
+
+test("updated and unchanged must not carry a reason", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "updated", reason: "no_marker" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "notes/a.md", outcome: "unchanged", reason: "x" }]),
+    (err: unknown) => err instanceof TypeError && /reason/.test(err.message),
+  );
+});
+
+test("blank path throws RangeError", () => {
+  assert.throws(
+    () => summarizeVaultPublish([{ path: "", outcome: "updated" }]),
+    (err: unknown) => err instanceof RangeError && /path/.test(err.message),
+  );
+  assert.throws(
+    () => summarizeVaultPublish([{ path: " \t ", outcome: "updated" }]),
+    (err: unknown) => err instanceof RangeError && /path/.test(err.message),
+  );
+});
+
+test("duplicate paths are all preserved, not deduplicated", () => {
+  const status = summarizeVaultPublish([
+    { path: "notes/a.md", outcome: "updated" },
+    { path: "notes/a.md", outcome: "skipped", reason: "no_marker" },
+    { path: "notes/a.md", outcome: "updated" },
+  ]);
+  assert.equal(status.results.length, 3);
+  assert.deepEqual(status.counts, { updated: 2, unchanged: 0, skipped: 1, error: 0 });
+  assert.deepEqual(
+    status.results.map((entry) => entry.outcome),
+    ["updated", "updated", "skipped"],
+  );
+  assert.equal(status.hasError, false);
+});
+
+test("order is deterministic across shuffled input", () => {
+  const base: VaultPublishResult[] = [
+    { path: "days/2026-08-18.md", outcome: "error", reason: "missing_file" },
+    { path: "days/2026-08-18.md", outcome: "updated" },
+    { path: "days/2026-08-18.md", outcome: "skipped", reason: "no_marker" },
+    { path: "days/2026-08-18.md", outcome: "skipped", reason: "duplicate_heading" },
+    { path: "days/2026-08-17.md", outcome: "unchanged" },
+    { path: "places/office.md", outcome: "updated" },
+  ];
+  const forward = summarizeVaultPublish(base);
+  const reversed = summarizeVaultPublish([...base].reverse());
+  assert.deepEqual(forward, reversed);
+  assert.deepEqual(
+    forward.results.map((entry) => `${entry.path}:${entry.outcome}:${entry.reason ?? ""}`),
+    [
+      "days/2026-08-17.md:unchanged:",
+      "days/2026-08-18.md:updated:",
+      "days/2026-08-18.md:skipped:duplicate_heading",
+      "days/2026-08-18.md:skipped:no_marker",
+      "days/2026-08-18.md:error:missing_file",
+      "places/office.md:updated:",
+    ],
+  );
+});
+
+test("input is not mutated", () => {
+  const input: VaultPublishResult[] = [
+    { path: "notes/b.md", outcome: "updated" },
+    { path: "notes/a.md", outcome: "skipped", reason: "no_marker" },
+  ];
+  const snapshot = structuredClone(input);
+  summarizeVaultPublish(input);
+  assert.deepEqual(input, snapshot);
+});

package/src/activity/vault-status.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure vault-publish outcome aggregator (issue #1985).
+ *
+ * `summarizeVaultPublish` folds per-file publish results into the status
+ * shape the publish report and the dry-run print: sorted per-file outcomes
+ * plus zero-filled counts. It performs no I/O and never mutates its input.
+ *
+ * Fail-closed contract: an unrecognized outcome is refused, never coerced
+ * into `skipped` or `error`, and `skipped`/`error` must carry a non-blank
+ * reason so every un-actionable row says why.
+ */
+
+export const VAULT_PUBLISH_OUTCOMES = ["updated", "unchanged", "skipped", "error"] as const;
+export type VaultPublishOutcome = (typeof VAULT_PUBLISH_OUTCOMES)[number];
+
+export interface VaultPublishResult {
+  /** Vault-relative note path. */
+  path: string;
+  outcome: string;
+  /** Required for skipped and error, e.g. "no_marker". */
+  reason?: string;
+}
+
+export interface VaultPublishStatus {
+  results: Array<{ path: string; outcome: VaultPublishOutcome; reason?: string }>;
+  counts: Record<VaultPublishOutcome, number>;
+  /** True when at least one entry is an error. */
+  hasError: boolean;
+}
+
+interface ValidatedEntry {
+  path: string;
+  outcome: VaultPublishOutcome;
+  reason?: string;
+}
+
+/** Total order: path asc, then outcome in allow-list order, then reason. */
+function compareEntries(a: ValidatedEntry, b: ValidatedEntry): number {
+  if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+  const rankA = VAULT_PUBLISH_OUTCOMES.indexOf(a.outcome);
+  const rankB = VAULT_PUBLISH_OUTCOMES.indexOf(b.outcome);
+  if (rankA !== rankB) return rankA < rankB ? -1 : 1;
+  const reasonA = a.reason ?? "";
+  const reasonB = b.reason ?? "";
+  if (reasonA !== reasonB) return reasonA < reasonB ? -1 : 1;
+  return 0;
+}
+
+export function summarizeVaultPublish(results: readonly VaultPublishResult[]): VaultPublishStatus {
+  if (!Array.isArray(results)) {
+    throw new TypeError(`summarizeVaultPublish expects an array of results (got ${typeof results})`);
+  }
+
+  const entries: ValidatedEntry[] = [];
+  for (const entry of results) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new TypeError(`vault publish result entries must be objects (got ${typeof entry})`);
+    }
+    if (typeof entry.path !== "string" || entry.path.trim() === "") {
+      throw new RangeError(`vault publish result requires a non-blank path (got ${JSON.stringify(entry.path)})`);
+    }
+    const outcome = VAULT_PUBLISH_OUTCOMES.find((candidate) => candidate === entry.outcome);
+    if (outcome === undefined) {
+      throw new TypeError(
+        `unknown vault publish outcome ${JSON.stringify(entry.outcome)}; expected one of: ${VAULT_PUBLISH_OUTCOMES.join(", ")}`,
+      );
+    }
+    if (outcome === "skipped" || outcome === "error") {
+      if (typeof entry.reason !== "string" || entry.reason.trim() === "") {
+        throw new TypeError(
+          `vault publish outcome "${outcome}" requires a non-blank reason, e.g. "no_marker" (got ${JSON.stringify(entry.reason)})`,
+        );
+      }
+      entries.push({ path: entry.path, outcome, reason: entry.reason });
+    } else {
+      if (entry.reason !== undefined) {
+        throw new TypeError(
+          `vault publish outcome "${outcome}" must not carry a reason (got ${JSON.stringify(entry.reason)})`,
+        );
+      }
+      entries.push({ path: entry.path, outcome });
+    }
+  }
+
+  const sorted = [...entries].sort(compareEntries);
+
+  const counts = {} as Record<VaultPublishOutcome, number>;
+  for (const outcome of VAULT_PUBLISH_OUTCOMES) counts[outcome] = 0;
+  for (const entry of sorted) counts[entry.outcome] += 1;
+
+  return {
+    results: sorted,
+    counts,
+    hasError: counts.error > 0,
+  };
+}

package/src/dedup/index.ts

@@ -474,3 +474,10 @@ export {
   type MergeJudgeVerdictName,
   type ParseMergeVerdictResult,
 } from "./merge-verdict.js";
+
+export {
+  MERGE_DERIVED_VIA,
+  buildMergeFrontmatterUpdate,
+  type MergeFrontmatterUpdate,
+  type MergeProvenanceSource,
+} from "./merge-provenance.js";