@remnic/core 9.69.32 → 9.69.34

package/src/activity/timeline/analysis.ts

@@ -1,9 +1,13 @@
 /**
- * Optional AI analysis over deterministic timeline cards (issue #2050 first slice).
- *
- * Injected provider only. parseConfig, registries, and surfaces wait.
- * Failures leave cards unchanged. Disabled makes zero provider calls.
+ * Optional evidence-bound AI analysis over deterministic timeline cards
+ * (issue #2050). Provider calls arrive through the injected `complete`
+ * function; hosts build it from the local/remote seams in analysis-provider.js
+ * and the parsed `activity.timeline.analysis` config. Failures leave the
+ * cards unchanged and carry a typed failure kind. Disabled makes zero
+ * provider calls.
  */
+import { classifyAnalysisFailure, type AnalysisFailure, type AnalysisFailureKind } from "./analysis-failure.js";
+import { classifyAnalysisProviderError } from "./analysis-provider.js";
 import { extractJsonCandidates } from "../../json-extract.js";
 import { log } from "../../logger.js";
 import { DEFAULT_TIMELINE_CATEGORIES } from "./categories.js";
@@ -55,6 +59,8 @@ export interface TimelineAnalysisResult {
   provider?: string;
   model?: string;
   promptVersion?: number;
+  /** Typed failure detail; present only when status is a failure. */
+  failure?: AnalysisFailure;
 }
 
 interface AnalysisOp {
@@ -82,6 +88,7 @@ function fail(
   cards: readonly TimelineCard[],
   provider: string,
   model: string,
+  kind: AnalysisFailureKind,
 ): TimelineAnalysisResult {
   log.info(`timeline analysis status=${status} provider=${provider} model=${model} promptVersion=${TIMELINE_ANALYSIS_PROMPT_VERSION}`);
   return {
@@ -90,6 +97,7 @@ function fail(
     provider,
     model,
     promptVersion: TIMELINE_ANALYSIS_PROMPT_VERSION,
+    failure: classifyAnalysisFailure(kind),
   };
 }
 
@@ -206,32 +214,6 @@ async function callComplete(
   }
 }
 
-function parseOps(raw: string): AnalysisOp[] | null {
-  if (typeof raw !== "string" || raw.trim().length === 0) return null;
-  for (const candidate of extractJsonCandidates(raw)) {
-    try {
-      const parsed: unknown = JSON.parse(candidate);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || !("ops" in parsed)) continue;
-      const ops = parsed.ops;
-      if (!Array.isArray(ops)) continue;
-      const out: AnalysisOp[] = [];
-      let valid = true;
-      for (const item of ops) {
-        const op = asOp(item);
-        if (!op) {
-          valid = false;
-          break;
-        }
-        out.push(op);
-      }
-      if (valid) return out;
-    } catch {
-      continue;
-    }
-  }
-  return null;
-}
-
 function asOp(value: unknown): AnalysisOp | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   if (!("cardId" in value) || typeof value.cardId !== "string" || value.cardId.length === 0) return null;
@@ -262,6 +244,45 @@ function asOp(value: unknown): AnalysisOp | null {
   };
 }
 
+type ParseOpsResult = { ok: true; ops: AnalysisOp[] } | { ok: false; kind: AnalysisFailureKind };
+
+/**
+ * Parse the provider response. An empty/whitespace body is `partial_output`
+ * (nothing came back); a body whose JSON candidates never parse is
+ * `malformed_json`; parseable JSON in the wrong shape — missing `ops`, or an
+ * op that fails validation — is `invalid_schema`.
+ */
+function parseOps(raw: string): ParseOpsResult {
+  if (typeof raw !== "string" || raw.trim().length === 0) return { ok: false, kind: "partial_output" };
+  let sawParsableShape = false;
+  for (const candidate of extractJsonCandidates(raw)) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      if (!("ops" in parsed) || !Array.isArray(parsed.ops)) {
+        sawParsableShape = true;
+        continue;
+      }
+      const out: AnalysisOp[] = [];
+      let valid = true;
+      for (const item of parsed.ops) {
+        const op = asOp(item);
+        if (!op) {
+          valid = false;
+          break;
+        }
+        out.push(op);
+      }
+      if (valid) return { ok: true, ops: out };
+      sawParsableShape = true;
+    } catch {
+      continue;
+    }
+  }
+  if (sawParsableShape) return { ok: false, kind: "invalid_schema" };
+  return { ok: false, kind: "malformed_json" };
+}
+
 function knownEvidenceKeys(cards: readonly TimelineCard[], observations: readonly TimelineObservation[]): Set<string> {
   const keys = new Set<string>();
   for (const observation of observations) keys.add(evidenceKeyOf(observation));
@@ -320,7 +341,15 @@ export async function analyzeTimelineCards(input: TimelineAnalysisInput): Promis
     throw new TimelineAnalysisConfigError("timeoutMs must be a positive integer");
   }
   if (input.cards.length === 0 && input.observations.length === 0) {
-    return fail("invalid_output", cards, provider, model);
+    // Caller-side guard, not a provider failure: nothing to analyze and zero
+    // calls must be made, so no typed response failure is attached.
+    return {
+      status: "invalid_output",
+      cards,
+      provider,
+      model,
+      promptVersion: TIMELINE_ANALYSIS_PROMPT_VERSION,
+    };
   }
 
   const categories = input.categories ?? DEFAULT_TIMELINE_CATEGORIES;
@@ -340,16 +369,16 @@ export async function analyzeTimelineCards(input: TimelineAnalysisInput): Promis
         priorEdits: input.priorEdits,
       });
       const raw = await callComplete(complete, prompt, provider, model, timeoutMs, input.signal);
-      const ops = parseOps(raw);
-      if (!ops) return fail("invalid_output", cards, provider, model);
-      for (const op of ops) merged.set(op.cardId, op);
+      const parsed = parseOps(raw);
+      if (!parsed.ok) return fail("invalid_output", cards, provider, model, parsed.kind);
+      for (const op of parsed.ops) merged.set(op.cardId, op);
     }
-  } catch {
-    return fail("provider_failed", cards, provider, model);
+  } catch (error) {
+    return fail("provider_failed", cards, provider, model, classifyAnalysisProviderError(error));
   }
 
   const applied = applyOps(cards, [...merged.values()], categories, knownEvidenceKeys(cards, ordered));
-  if (!applied) return fail("invalid_output", cards, provider, model);
+  if (!applied) return fail("invalid_output", cards, provider, model, "invalid_schema");
 
   log.info(`timeline analysis status=ok provider=${provider} model=${model} promptVersion=${TIMELINE_ANALYSIS_PROMPT_VERSION}`);
   return {

package/src/activity/timeline/corrections.ts

@@ -108,6 +108,15 @@ export class TimelineCorrectionStore {
   }
 }
 
+/** Corrections whose cardId is in `cards`, in incoming list order. */
+export function correctionsForCards(
+  cards: readonly TimelineCard[],
+  corrections: readonly TimelineCorrection[],
+): TimelineCorrection[] {
+  const ids = new Set(cards.map((card) => card.id));
+  return corrections.filter((correction) => ids.has(correction.cardId));
+}
+
 /**
  * Apply corrections to built cards. Overrides title/category, sets confidence
  * to 1 (a human confirmed it), and stamps manual-edit provenance. Uncorrected

package/src/activity/timeline/index.ts

@@ -10,6 +10,9 @@ export * from "./journal-recap-persist.js";
 export * from "./weekly.js";
 export * from "./weekly-persist.js";
 export * from "./analysis.js";
+export * from "./analysis-provider.js";
+export * from "./analysis-run.js";
+export * from "./regenerate.js";
 export * from "./recap-export.js";
 export * from "./recap-markdown.js";
 export * from "./week-export.js";

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

@@ -196,3 +196,74 @@ test("CLI runner accepts in-memory cards and does not need a store", async () =>
   assert.deepEqual(JSON.parse(out), { ok: false, error: "store_unreadable" });
   assert.equal(err, "");
 });
+
+test("CLI range validates the full request before loading production cards", async () => {
+  const windows: Array<{ from?: string; to?: string }> = [];
+  let err = "";
+  const io = {
+    stdout: { write: () => true },
+    stderr: { write: (chunk: string) => (err += chunk) },
+  };
+  const deps = {
+    cards: null,
+    qa: { enabled: true, maxRangeDays: 1 },
+    timelineEnabled: true,
+    loadCards: async (window: { from?: string; to?: string }) => {
+      windows.push(window);
+      return [];
+    },
+  };
+  const overWide = await runTimelineCliCommand(
+    deps,
+    ["range", "--from", "2026-01-01T00:00:00.000Z", "--to", "2026-06-01T00:00:00.000Z"],
+    io,
+  );
+  assert.equal(overWide, 1);
+  assert.match(err, /maxRangeDays \(1\)/);
+  err = "";
+  const reversed = await runTimelineCliCommand(
+    deps,
+    ["range", "--from", "2026-06-01T00:00:00.000Z", "--to", "2026-01-01T00:00:00.000Z"],
+    io,
+  );
+  assert.equal(reversed, 1);
+  assert.match(err, /reversed range/);
+  err = "";
+  const malformed = await runTimelineCliCommand(
+    deps,
+    ["range", "--from", "not-a-date", "--to", "2026-01-02T00:00:00.000Z"],
+    io,
+  );
+  assert.equal(malformed, 1);
+  assert.match(err, /must be an ISO date or datetime/);
+  assert.deepEqual(windows, [], "an invalid range must never reach the card loader");
+});
+
+test("CLI search validates bounds before loading and passes an unbounded window through", async () => {
+  const windows: Array<{ from?: string; to?: string }> = [];
+  let err = "";
+  const io = {
+    stdout: { write: () => true },
+    stderr: { write: (chunk: string) => (err += chunk) },
+  };
+  const deps = {
+    cards: null,
+    qa: { enabled: true, maxRangeDays: 31 },
+    timelineEnabled: true,
+    loadCards: async (window: { from?: string; to?: string }) => {
+      windows.push(window);
+      return [];
+    },
+  };
+  const reversed = await runTimelineCliCommand(
+    deps,
+    ["search", "--query", "x", "--from", "2027-01-05T00:00:00.000Z", "--to", "2026-01-01T00:00:00.000Z"],
+    io,
+  );
+  assert.equal(reversed, 1);
+  assert.match(err, /reversed range/);
+  assert.deepEqual(windows, [], "invalid search bounds must never reach the card loader");
+  const unbounded = await runTimelineCliCommand(deps, ["search", "--query", "x"], io);
+  assert.equal(unbounded, 0);
+  assert.deepEqual(windows, [{ from: undefined, to: undefined }]);
+});

package/src/activity/timeline/query.ts

@@ -74,6 +74,8 @@ export interface TimelineCliDeps {
   timelineEnabled?: boolean;
   /** Required for `publish`; range/search never read it. */
   config?: PluginConfig;
+  /** Production host loads cards through regenerateTimelineDay. */
+  loadCards?: (window: { from?: string; to?: string }) => Promise<readonly TimelineQueryCard[] | null>;
 }
 
 const USAGE = `Usage: timeline <command> [options]
@@ -119,6 +121,32 @@ function assertRange(fromMs: number, toMs: number, maxRangeDays: number): void {
   }
 }
 
+/**
+ * Validate a range request completely - format, instants, ordering, and
+ * qa.maxRangeDays - with no card access. Production callers must run this
+ * before any side-effecting card loader so an invalid range fails before
+ * day regeneration or analysis spend.
+ */
+export function validateTimelineRangeQuery(query: {
+  from: string;
+  to: string;
+  format: string;
+  maxRangeDays?: number;
+}): void {
+  if (!RANGE_FORMATS.includes(query.format as TimelineRangeFormat)) {
+    throw new TypeError(`format must be one of: ${RANGE_FORMATS.join(", ")}`);
+  }
+  const maxRangeDays = query.maxRangeDays ?? DEFAULT_MAX_RANGE_DAYS;
+  assertRange(parseInstant(query.from, "from"), parseInstant(query.to, "to"), maxRangeDays);
+}
+
+/** Validate optional search bounds the way queryTimelineSearch applies them. */
+export function validateTimelineSearchBounds(bounds: { from?: string; to?: string }): void {
+  const fromMs = parseInstant(bounds.from ?? bounds.to!, "from");
+  const toMs = parseInstant(bounds.to ?? bounds.from!, "to");
+  assertRange(fromMs, toMs, DEFAULT_MAX_RANGE_DAYS);
+}
+
 function cardOverlaps(card: TimelineQueryCard, fromMs: number, toMs: number): boolean {
   const start = Date.parse(card.startUtc);
   const end = Date.parse(card.endUtc);
@@ -304,16 +332,25 @@ export async function runTimelineCliCommand(
       const from = flagString(flags, "--from");
       const to = flagString(flags, "--to");
       if (!from || !to) throw new TypeError("range requires --from and --to");
-      if (!Array.isArray(deps.cards)) {
-        io.stderr.write("store_unreadable\n");
-        return 1;
-      }
       const formatRaw = flagString(flags, "--format") ?? "compact";
       if (formatRaw !== "cards" && formatRaw !== "compact") {
         throw new TypeError("format must be one of: cards, compact");
       }
+      // Validate the complete request before the side-effecting loader: an
+      // over-wide or malformed range must fail before any day regeneration
+      // or analysis spend.
+      validateTimelineRangeQuery({ from, to, format: formatRaw, maxRangeDays: deps.qa.maxRangeDays });
+      const cards = Array.isArray(deps.cards)
+        ? deps.cards
+        : deps.loadCards === undefined
+          ? null
+          : await deps.loadCards({ from, to });
+      if (!Array.isArray(cards)) {
+        io.stderr.write("store_unreadable\n");
+        return 1;
+      }
       const categoriesRaw = flagString(flags, "--categories");
-      const result = queryTimelineRange(deps.cards, {
+      const result = queryTimelineRange(cards, {
         from,
         to,
         format: formatRaw,
@@ -332,10 +369,22 @@ export async function runTimelineCliCommand(
       if (limitRaw !== undefined && !Number.isInteger(limit)) {
         throw new RangeError("limit must be an integer from 1 to 50");
       }
-      const result = queryTimelineSearch(deps.cards, {
+      const from = flagString(flags, "--from");
+      const to = flagString(flags, "--to");
+      // Bounds are validated before the side-effecting loader so a malformed
+      // or over-wide window fails before any day regeneration or analysis.
+      if (from !== undefined || to !== undefined) {
+        validateTimelineSearchBounds({ from, to });
+      }
+      const cards = Array.isArray(deps.cards)
+        ? deps.cards
+        : deps.loadCards === undefined
+          ? null
+          : await deps.loadCards({ from, to });
+      const result = queryTimelineSearch(cards, {
         query: q,
-        from: flagString(flags, "--from"),
-        to: flagString(flags, "--to"),
+        from,
+        to,
         limit,
       });
       io.stdout.write(`${JSON.stringify(result)}\n`);