@remnic/core 9.69.33 → 9.69.34

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

@@ -0,0 +1,419 @@
+/**
+ * Provider-contract and surface tests for timeline-card analysis (issue #2050).
+ *
+ * Every acceptance path runs against synthetic observations through the
+ * local/remote client seams — no network, no real provider. Prompt and
+ * response content are captured by the fakes and asserted locally.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runTimelineCardAnalysis } from "./analysis-run.js";
+import {
+  classifyAnalysisProviderError,
+  timelineAnalysisCompleteFromClients,
+  TimelineAnalysisProviderError,
+} from "./analysis-provider.js";
+import type { TimelineAnalysisLocalLlm, TimelineAnalysisRemoteLlm } from "./analysis-provider.js";
+import type { ActivityTimelineAnalysisConfig } from "../types.js";
+import type { TimelineCard, TimelineObservation } from "./types.js";
+
+const DATE = "2026-08-17";
+const TZ = "UTC";
+
+function card(
+  overrides: Partial<TimelineCard> & Pick<TimelineCard, "id" | "startUtc" | "endUtc">,
+): TimelineCard {
+  return {
+    kind: "activity",
+    title: "main.ts — editor",
+    summary: "Code editor on ws-a",
+    categoryId: "development",
+    confidence: 0.8,
+    dayKey: DATE,
+    timezone: TZ,
+    machine: "ws-a",
+    evidenceIds: [1],
+    evidenceRange: {
+      firstKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1",
+      lastKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1",
+    },
+    ...overrides,
+  };
+}
+
+function observation(overrides: Partial<TimelineObservation> = {}): TimelineObservation {
+  return {
+    id: 1,
+    machine: "ws-a",
+    capturedAtUtc: "2026-08-17T10:00:00.000Z",
+    app: "editor",
+    windowTitle: "main.ts — editor",
+    contentHash: "hash-1",
+    ...overrides,
+  };
+}
+
+function sampleCards(): TimelineCard[] {
+  return [card({ id: "card-1", startUtc: "2026-08-17T10:00:00.000Z", endUtc: "2026-08-17T10:15:00.000Z" })];
+}
+
+const ENABLED: ActivityTimelineAnalysisConfig = { enabled: true, provider: "openai", model: "gpt-test" };
+
+interface RecordedCall {
+  messages: Array<{ role: string; content: string }>;
+  options: Record<string, unknown>;
+}
+
+function fakeLocal(handler: (call: RecordedCall) => Promise<{ content: string } | null>) {
+  const calls: RecordedCall[] = [];
+  const localLlm: TimelineAnalysisLocalLlm = {
+    chatCompletion: async (messages, options) => {
+      const call = { messages, options: options as unknown as Record<string, unknown> };
+      calls.push(call);
+      return handler(call);
+    },
+  };
+  return { localLlm, calls };
+}
+
+function fakeRemote(handler: (call: RecordedCall) => Promise<{ content: string } | null>) {
+  const calls: RecordedCall[] = [];
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async (messages, options) => {
+      const call = { messages, options: options as unknown as Record<string, unknown> };
+      calls.push(call);
+      return handler(call);
+    },
+  };
+  return { remoteLlm, calls };
+}
+
+test("disabled config makes zero provider calls and produces zero analysis artifacts", async () => {
+  const cards = sampleCards();
+  const local = fakeLocal(async () => ({ content: '{"ops":[]}' }));
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: { enabled: false },
+    deps: { localLlm: local.localLlm, remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "disabled");
+  assert.equal(result.cards, cards);
+  assert.equal(local.calls.length + remote.calls.length, 0);
+  assert.equal(result.failure, undefined);
+  assert.equal(result.metadata, undefined);
+});
+
+test("remote provider is pinned to the single configured model with no chain fallback", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "ok");
+  assert.equal(remote.calls.length, 1);
+  assert.deepEqual(remote.calls[0]?.options.modelChain, { primary: "openai/gpt-test" });
+  assert.equal(remote.calls[0]?.options.includeDefaultModelFallback, false);
+  assert.deepEqual(result.metadata, {
+    provider: "openai",
+    model: "gpt-test",
+    promptVersion: "1",
+    observationCount: 1,
+  });
+});
+
+test("local provider routes to the local client seam", async () => {
+  const local = fakeLocal(async () => ({ content: '{"ops":[]}' }));
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation()],
+    config: { ...ENABLED, provider: "local", model: "qwen3.8-27b" },
+    deps: { localLlm: local.localLlm, remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "ok");
+  assert.equal(local.calls.length, 1);
+  assert.equal(remote.calls.length, 0);
+  assert.equal(local.calls[0]?.options.operation, "timeline-analysis");
+  assert.equal(local.calls[0]?.options.model, "qwen3.8-27b");
+  assert.equal(result.metadata?.provider, "local");
+  assert.equal(result.metadata?.model, "qwen3.8-27b");
+});
+
+test("prompt carries evidence-only chronology and strict-output instructions with only safe fields", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [observation({ browserUrl: "https://example.test/repo" })],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  const prompt = remote.calls[0]?.messages[0]?.content ?? "";
+  for (const phrase of [
+    "Use only supplied evidence",
+    "Preserve chronology",
+    "Do not invent people, places, or tasks",
+    "Avoid productivity or emotional claims",
+    "Return strict JSON",
+  ]) {
+    assert.ok(prompt.includes(phrase), `prompt must instruct: ${phrase}`);
+  }
+  // The prompt is "<instructions>\n<payload JSON>"; the payload is line 2.
+  const payload = JSON.parse(prompt.slice(prompt.indexOf("\n") + 1));
+  assert.deepEqual(Object.keys(payload.observations[0]).sort(), [
+    "app",
+    "browserUrl",
+    "capturedAtUtc",
+    "contentHash",
+    "id",
+    "machine",
+    "windowTitle",
+  ]);
+  // No raw capture channels exist on the observation payload: the type carries
+  // none, and the wire shape proves nothing extra was smuggled in.
+  assert.equal(JSON.stringify(payload).includes("textSource"), false);
+});
+
+test("observations outside the day window are never sent", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: sampleCards(),
+    observations: [
+      observation({ id: 1 }),
+      observation({ id: 2, capturedAtUtc: "2026-08-16T23:59:59.999Z", contentHash: "hash-2" }),
+    ],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  const prompt = remote.calls[0]?.messages[0]?.content ?? "";
+  const payload = JSON.parse(prompt.slice(prompt.indexOf("\n") + 1));
+  assert.equal(payload.observations.length, 1);
+  assert.equal(result.metadata?.observationCount, 1);
+});
+
+test("an impossible date or timezone throws before any provider contact", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  await assert.rejects(
+    () =>
+      runTimelineCardAnalysis({
+        date: "2026-02-30",
+        timezone: TZ,
+        cards: sampleCards(),
+        observations: [observation()],
+        config: ENABLED,
+        deps: { remoteLlm: remote.remoteLlm },
+      }),
+    RangeError,
+  );
+  await assert.rejects(
+    () =>
+      runTimelineCardAnalysis({
+        date: DATE,
+        timezone: "Not/AZone",
+        cards: sampleCards(),
+        observations: [observation()],
+        config: ENABLED,
+        deps: { remoteLlm: remote.remoteLlm },
+      }),
+    RangeError,
+  );
+  assert.equal(remote.calls.length, 0);
+});
+
+test("missing provider seam returns a typed provider_unavailable failure and unchanged cards", async () => {
+  const cards = sampleCards();
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: { ...ENABLED, provider: "local" },
+    deps: { localLlm: null, remoteLlm: null },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.cards, cards);
+  assert.deepEqual(result.failure, { kind: "provider_unavailable", retryable: true, preservesDeterministic: true });
+});
+
+test("unconfigured remote provider returns null and never falls back to another provider", async () => {
+  const remote = fakeRemote(async () => null);
+  const cards = sampleCards();
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [observation()],
+    config: { ...ENABLED, provider: "no-such-provider" },
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "provider_failed");
+  assert.equal(result.cards, cards);
+  assert.equal(result.failure?.kind, "provider_unavailable");
+  assert.equal(remote.calls.length, 1);
+  assert.deepEqual(remote.calls[0]?.options.modelChain, { primary: "no-such-provider/gpt-test" });
+});
+
+for (const [name, error, kind] of [
+  ["timeout", Object.assign(new Error("timeline analysis timed out"), { name: "TimeoutError" }), "timeout"],
+  ["abort", Object.assign(new Error("aborted"), { name: "AbortError" }), "aborted"],
+  ["rate limit status", Object.assign(new Error("HTTP 429"), { status: 429 }), "rate_limited"],
+  ["generic provider crash", new Error("socket hang up"), "provider_unavailable"],
+] as const) {
+  test(`${name} returns the typed failure kind and leaves cards byte-identical`, async () => {
+    const cards = sampleCards();
+    const remote = fakeRemote(async () => {
+      throw error;
+    });
+    const result = await runTimelineCardAnalysis({
+      date: DATE,
+      timezone: TZ,
+      cards,
+      observations: [observation()],
+      config: ENABLED,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(result.status, "provider_failed");
+    assert.equal(result.cards, cards);
+    assert.equal(result.failure?.kind, kind);
+    assert.equal(result.failure?.preservesDeterministic, true);
+  });
+}
+
+for (const [name, body, kind] of [
+  ["empty response body", "", "partial_output"],
+  ["malformed JSON", "the model rambled, no json here", "malformed_json"],
+  ["json without ops", '{"summary":"no ops key"}', "invalid_schema"],
+  ["ops with an invalid entry", '{"ops":[{"cardId":"card-1"}]}', "invalid_schema"],
+] as const) {
+  test(`${name} is typed ${kind} and leaves cards unchanged`, async () => {
+    const cards = sampleCards();
+    const remote = fakeRemote(async () => ({ content: body }));
+    const result = await runTimelineCardAnalysis({
+      date: DATE,
+      timezone: TZ,
+      cards,
+      observations: [observation()],
+      config: ENABLED,
+      deps: { remoteLlm: remote.remoteLlm },
+    });
+    assert.equal(result.status, "invalid_output");
+    assert.equal(result.cards, cards);
+    assert.equal(result.failure?.kind, kind);
+  });
+}
+
+test("a valid op updates only allowed fields and preserves manual edits and evidence", async () => {
+  const locked = card({
+    id: "locked",
+    startUtc: "2026-08-17T11:00:00.000Z",
+    endUtc: "2026-08-17T11:15:00.000Z",
+    manualEdit: { editedAtUtc: "2026-08-17T12:00:00.000Z", title: "kept" },
+  });
+  const open = card({ id: "open", startUtc: "2026-08-17T10:00:00.000Z", endUtc: "2026-08-17T10:15:00.000Z" });
+  const remote = fakeRemote(
+    async () =>
+      ({
+        content: JSON.stringify({
+          ops: [
+            {
+              cardId: "open",
+              title: "Refined title",
+              summary: "Editor work bound to the supplied window",
+              categoryId: "development",
+              confidence: 0.9,
+              uncertainty: "Title inferred from window title only",
+              evidenceRange: { firstKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1", lastKey: "ws-a|2026-08-17T10:00:00.000Z|hash-1" },
+            },
+          ],
+        }),
+      }) as { content: string },
+  );
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards: [locked, open],
+    observations: [observation()],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "ok");
+  const updated = result.cards.find((entry) => entry.id === "open");
+  const untouched = result.cards.find((entry) => entry.id === "locked");
+  assert.equal(updated?.title, "Refined title");
+  assert.equal(updated?.confidence, 0.9);
+  assert.deepEqual(updated?.evidenceRange, open.evidenceRange);
+  assert.deepEqual(updated?.evidenceIds, [1]);
+  assert.equal(untouched?.title, "main.ts — editor");
+  assert.ok(untouched?.manualEdit);
+});
+
+test("empty input returns invalid_output with zero provider calls", async () => {
+  const remote = fakeRemote(async () => ({ content: '{"ops":[]}' }));
+  const cards: TimelineCard[] = [];
+  const result = await runTimelineCardAnalysis({
+    date: DATE,
+    timezone: TZ,
+    cards,
+    observations: [],
+    config: ENABLED,
+    deps: { remoteLlm: remote.remoteLlm },
+  });
+  assert.equal(result.status, "invalid_output");
+  assert.equal(result.cards, cards);
+  assert.equal(remote.calls.length, 0);
+});
+
+test("provider error classification is name/status based and total", () => {
+  assert.equal(classifyAnalysisProviderError(new TimelineAnalysisProviderError("rate_limited", "x")), "rate_limited");
+  assert.equal(
+    classifyAnalysisProviderError(Object.assign(new Error("HTTP 429"), { status: 429 })),
+    "rate_limited",
+  );
+  assert.equal(
+    classifyAnalysisProviderError(new Error("Rate limit exceeded, retry later")),
+    "rate_limited",
+  );
+  assert.equal(
+    classifyAnalysisProviderError(Object.assign(new Error("x"), { name: "AbortError" })),
+    "aborted",
+  );
+  assert.equal(
+    classifyAnalysisProviderError(Object.assign(new Error("x"), { name: "TimeoutError" })),
+    "timeout",
+  );
+  assert.equal(classifyAnalysisProviderError(new Error("socket hang up")), "provider_unavailable");
+  assert.equal(classifyAnalysisProviderError("not an error"), "provider_unavailable");
+});
+
+test("adapter pins the call-time provider verbatim with no chain fallback", async () => {
+  const seen: string[] = [];
+  const remoteLlm: TimelineAnalysisRemoteLlm = {
+    chatCompletion: async (_messages, options) => {
+      seen.push(options.modelChain?.primary ?? "");
+      assert.equal(options.includeDefaultModelFallback, false);
+      return { content: '{"ops":[]}' };
+    },
+  };
+  const complete = timelineAnalysisCompleteFromClients({ localLlm: null, remoteLlm });
+  await complete({
+    prompt: "p",
+    provider: "anthropic",
+    model: "claude-4_1",
+    signal: new AbortController().signal,
+  });
+  assert.deepEqual(seen, ["anthropic/claude-4_1"]);
+});

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

@@ -0,0 +1,106 @@
+/**
+ * Config-driven surface for evidence-bound timeline-card analysis (issue #2050).
+ *
+ * Composes the parsed `activity.timeline.analysis` config with the local/remote
+ * provider seams and `analyzeTimelineCards`. The AI gate is independent of
+ * activity capture, timeline derivation, and memory creation: disabled means
+ * zero provider calls and zero analysis artifacts. Every failure leaves the
+ * deterministic cards byte-identical and returns a typed status.
+ */
+import { activityDayWindow } from "../digest.js";
+import type { ActivityTimelineAnalysisConfig } from "../types.js";
+import { analyzeTimelineCards, type TimelineAnalysisStatus } from "./analysis.js";
+import type { AnalysisFailure } from "./analysis-failure.js";
+import {
+  timelineAnalysisCompleteFromClients,
+  type TimelineAnalysisLocalLlm,
+  type TimelineAnalysisRemoteLlm,
+} from "./analysis-provider.js";
+import { buildAnalysisRunMetadata, type AnalysisRunMetadata } from "./analysis-metadata.js";
+import type { TimelineCard, TimelineCategory, TimelineCorrection, TimelineObservation } from "./types.js";
+
+export interface TimelineAnalysisRunInput {
+  /** Local calendar day being analyzed (YYYY-MM-DD). */
+  date: string;
+  /** IANA timezone the day is bucketed in. */
+  timezone: string;
+  /** Deterministic cards for the day (the bytes that must survive failure). */
+  cards: readonly TimelineCard[];
+  /** Day observations — the only evidence the provider may see. */
+  observations: readonly TimelineObservation[];
+  categories?: readonly TimelineCategory[];
+  /** Prior accepted manual corrections, surfaced to the prompt as edits. */
+  corrections?: readonly TimelineCorrection[];
+  config: ActivityTimelineAnalysisConfig;
+  deps: {
+    localLlm?: TimelineAnalysisLocalLlm | null;
+    remoteLlm?: TimelineAnalysisRemoteLlm | null;
+  };
+  signal?: AbortSignal;
+}
+
+export interface TimelineAnalysisRunResult {
+  status: TimelineAnalysisStatus;
+  /** Same card objects as the input on any non-ok status. */
+  cards: TimelineCard[];
+  failure?: AnalysisFailure;
+  /** Provider/model/prompt-version provenance; identifiers only, never content. */
+  metadata?: AnalysisRunMetadata;
+}
+
+/**
+ * Run the optional analysis for one day. Observations are confined to the
+ * DST-aware day window before anything is sent, so a mis-scoped caller cannot
+ * widen the evidence the provider sees.
+ */
+export async function runTimelineCardAnalysis(
+  input: TimelineAnalysisRunInput,
+): Promise<TimelineAnalysisRunResult> {
+  // Throws RangeError on an impossible date or invalid timezone before any
+  // provider contact — the window bounds the whole run.
+  const { startUtc, endUtc } = activityDayWindow(input.date, input.timezone);
+  if (!input.config.enabled) {
+    return { status: "disabled", cards: input.cards as TimelineCard[] };
+  }
+  const start = Date.parse(startUtc);
+  const end = Date.parse(endUtc);
+  const observations = input.observations.filter((observation) => {
+    const captured = Date.parse(observation.capturedAtUtc);
+    return Number.isFinite(captured) && captured >= start && captured < end;
+  });
+  const result = await analyzeTimelineCards({
+    enabled: true,
+    cards: input.cards,
+    observations,
+    provider: input.config.provider,
+    model: input.config.model,
+    complete: timelineAnalysisCompleteFromClients({
+      localLlm: input.deps.localLlm ?? null,
+      remoteLlm: input.deps.remoteLlm ?? null,
+    }),
+    ...(input.config.timeoutMs === undefined ? {} : { timeoutMs: input.config.timeoutMs }),
+    date: input.date,
+    timezone: input.timezone,
+    ...(input.categories === undefined ? {} : { categories: input.categories }),
+    ...(input.config.preferences === undefined ? {} : { preferences: input.config.preferences }),
+    ...(input.corrections === undefined ? {} : { priorEdits: input.corrections }),
+    ...(input.signal === undefined ? {} : { signal: input.signal }),
+  });
+  if (result.status !== "ok") {
+    return {
+      status: result.status,
+      cards: result.cards,
+      ...(result.failure === undefined ? {} : { failure: result.failure }),
+    };
+  }
+  return {
+    status: "ok",
+    cards: result.cards,
+    metadata: buildAnalysisRunMetadata({
+      provider: result.provider ?? "unknown",
+      model: result.model ?? "unknown",
+      promptVersion: String(result.promptVersion ?? "v0"),
+      observationCount: observations.length,
+    }),
+  };
+}

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 {