@remnic/core 9.66.11 → 9.66.12

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

@@ -0,0 +1,104 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  ANALYSIS_FAILURE_KINDS,
+  classifyAnalysisFailure,
+  isAnalysisFailureKind,
+  type AnalysisFailureKind,
+} from "./analysis-failure.js";
+
+test("every known kind classifies with the explicit retryable split", () => {
+  const retryableKinds: readonly AnalysisFailureKind[] = [
+    "provider_unavailable",
+    "timeout",
+    "rate_limited",
+  ];
+  const nonRetryableKinds: readonly AnalysisFailureKind[] = [
+    "aborted",
+    "malformed_json",
+    "invalid_schema",
+    "partial_output",
+    "invalid_config",
+  ];
+  for (const kind of ANALYSIS_FAILURE_KINDS) {
+    const failure = classifyAnalysisFailure(kind);
+    assert.equal(failure.kind, kind);
+    assert.equal(failure.preservesDeterministic, true);
+    const expectedRetryable = retryableKinds.includes(kind);
+    assert.ok(
+      expectedRetryable || nonRetryableKinds.includes(kind),
+      `${kind} missing from the explicit retryable split`,
+    );
+    assert.equal(
+      failure.retryable,
+      expectedRetryable,
+      `${kind} retryable must be ${expectedRetryable}`,
+    );
+  }
+});
+
+test("the explicit retryable split covers all kinds exactly once", () => {
+  const split: readonly string[] = [
+    "provider_unavailable",
+    "timeout",
+    "rate_limited",
+    "aborted",
+    "malformed_json",
+    "invalid_schema",
+    "partial_output",
+    "invalid_config",
+  ];
+  assert.equal(new Set(split).size, split.length);
+  assert.deepEqual(
+    [...ANALYSIS_FAILURE_KINDS].sort(),
+    [...split].sort(),
+  );
+});
+
+test("unknown string kind throws TypeError naming the allowed kinds", () => {
+  assert.throws(
+    () => classifyAnalysisFailure("provider_on_fire"),
+    (err: unknown) => {
+      assert.ok(err instanceof TypeError);
+      assert.match((err as Error).message, /unknown analysis failure/);
+      for (const kind of ANALYSIS_FAILURE_KINDS) {
+        assert.ok((err as Error).message.includes(kind));
+      }
+      return true;
+    },
+  );
+});
+
+test("empty, null, undefined, and non-string kinds throw", () => {
+  for (const bad of ["", undefined, null, 42]) {
+    assert.throws(
+      () => classifyAnalysisFailure(bad as string),
+      TypeError,
+      `expected throw for ${String(bad)}`,
+    );
+  }
+});
+
+test("isAnalysisFailureKind is false for non-strings, empty, and unknown", () => {
+  assert.equal(isAnalysisFailureKind(undefined), false);
+  assert.equal(isAnalysisFailureKind(null), false);
+  assert.equal(isAnalysisFailureKind(42), false);
+  assert.equal(isAnalysisFailureKind({ kind: "timeout" }), false);
+  assert.equal(isAnalysisFailureKind(""), false);
+  assert.equal(isAnalysisFailureKind("timeout "), false);
+  assert.equal(isAnalysisFailureKind("TIMEOUT"), false);
+  assert.equal(isAnalysisFailureKind("provider_on_fire"), false);
+  for (const kind of ANALYSIS_FAILURE_KINDS) {
+    assert.equal(isAnalysisFailureKind(kind), true);
+  }
+});
+
+test("preservesDeterministic is true for every kind", () => {
+  for (const kind of ANALYSIS_FAILURE_KINDS) {
+    assert.deepEqual(
+      classifyAnalysisFailure(kind).preservesDeterministic,
+      true,
+    );
+  }
+});

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

@@ -0,0 +1,60 @@
+/**
+ * Typed failure classification for timeline analysis (issue #2050).
+ *
+ * Unknown kinds fail closed with a TypeError. Pure: no I/O, no clock, no randomness.
+ */
+
+export const ANALYSIS_FAILURE_KINDS = [
+  "provider_unavailable",
+  "timeout",
+  "aborted",
+  "rate_limited",
+  "malformed_json",
+  "invalid_schema",
+  "partial_output",
+  "invalid_config",
+] as const;
+export type AnalysisFailureKind = (typeof ANALYSIS_FAILURE_KINDS)[number];
+
+export interface AnalysisFailure {
+  kind: AnalysisFailureKind;
+  /** True only when retrying the same request could plausibly succeed. */
+  retryable: boolean;
+  /** True when the deterministic cards must be preserved unchanged. */
+  preservesDeterministic: true;
+}
+
+const RETRYABLE_BY_KIND: Readonly<Record<AnalysisFailureKind, boolean>> = {
+  provider_unavailable: true,
+  timeout: true,
+  rate_limited: true,
+  aborted: false,
+  malformed_json: false,
+  invalid_schema: false,
+  partial_output: false,
+  invalid_config: false,
+};
+
+/** True when the value is one of the known failure kinds. */
+export function isAnalysisFailureKind(
+  value: unknown,
+): value is AnalysisFailureKind {
+  return (
+    typeof value === "string" &&
+    (ANALYSIS_FAILURE_KINDS as readonly string[]).includes(value)
+  );
+}
+
+/** Classify a failure kind. Unknown kinds throw; there is no permissive default. */
+export function classifyAnalysisFailure(kind: string): AnalysisFailure {
+  if (!isAnalysisFailureKind(kind)) {
+    throw new TypeError(
+      `unknown analysis failure kind: ${String(kind)}; allowed kinds: ${ANALYSIS_FAILURE_KINDS.join(", ")}`,
+    );
+  }
+  return {
+    kind,
+    retryable: RETRYABLE_BY_KIND[kind],
+    preservesDeterministic: true,
+  };
+}

package/src/activity/timeline/index.ts

@@ -21,3 +21,4 @@ export * from "./analysis-prompt.js";
 export * from "./analysis-claim.js";
 export * from "./analysis-order.js";
 export * from "./recap-window.js";
+export * from "./analysis-failure.js";

package/src/dedup/index.ts

@@ -467,3 +467,10 @@ export {
   type MergeDecision,
   type MergeDecisionOptions,
 } from "./merge-decision.js";
+
+export {
+  MERGE_JUDGE_VERDICTS,
+  parseMergeJudgeVerdict,
+  type MergeJudgeVerdictName,
+  type ParseMergeVerdictResult,
+} from "./merge-verdict.js";

package/src/dedup/merge-verdict.test.ts

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MERGE_JUDGE_VERDICTS, parseMergeJudgeVerdict } from "./merge-verdict.js";
+
+test("every allow-list name parses (loops the constant)", () => {
+  for (const name of MERGE_JUDGE_VERDICTS) {
+    const result = parseMergeJudgeVerdict(name);
+    assert.equal(result.ok, true);
+    assert.ok(result.ok);
+    assert.equal(result.verdict, name);
+    assert.equal(result.decision, name === "merge" ? "merge" : "create");
+  }
+});
+
+test("accepts mixed case and surrounding whitespace", () => {
+  for (const raw of ["MERGE", " merge ", "Create", "\tcreate\n", "UnCertain", "  uncertain  "]) {
+    const result = parseMergeJudgeVerdict(raw);
+    assert.ok(result.ok, `expected "${raw}" to parse`);
+    assert.equal(result.verdict, raw.trim().toLowerCase());
+  }
+});
+
+test("only merge yields decision merge", () => {
+  const merged = parseMergeJudgeVerdict("merge");
+  assert.ok(merged.ok);
+  assert.equal(merged.decision, "merge");
+});
+
+test("uncertain yields decision create", () => {
+  const result = parseMergeJudgeVerdict("uncertain");
+  assert.ok(result.ok);
+  assert.equal(result.verdict, "uncertain");
+  assert.equal(result.decision, "create");
+});
+
+test("empty and non-string inputs give empty_verdict with decision create", () => {
+  const empties: unknown[] = ["", "   ", null, undefined, 42, { verdict: "merge" }, ["merge"]];
+  for (const raw of empties) {
+    const result = parseMergeJudgeVerdict(raw);
+    assert.ok(!result.ok, `expected ${JSON.stringify(raw)} to fail`);
+    assert.equal(result.error, "empty_verdict");
+    assert.equal(result.decision, "create");
+  }
+});
+
+test("unrecognized strings give unknown_verdict with decision create", () => {
+  for (const raw of ["I think merge", "maybe", "merge them", "merg", "MERGE!"]) {
+    const result = parseMergeJudgeVerdict(raw);
+    assert.ok(!result.ok, `expected "${raw}" to fail`);
+    assert.equal(result.error, "unknown_verdict");
+    assert.equal(result.decision, "create");
+  }
+});
+
+test("no input throws", () => {
+  const hostile: unknown[] = [
+    "",
+    "   ",
+    null,
+    undefined,
+    0,
+    NaN,
+    {},
+    [],
+    () => "merge",
+    Symbol("merge"),
+    "I think merge",
+    "merge",
+  ];
+  for (const raw of hostile) {
+    assert.doesNotThrow(() => parseMergeJudgeVerdict(raw));
+  }
+});

package/src/dedup/merge-verdict.ts

@@ -0,0 +1,31 @@
+/**
+ * Strict parser for free-form merge-judge verdicts (issue #2330 slice).
+ *
+ * Keeps "unparseable answer" distinguishable from a deliberate "create"
+ * while still failing closed: every failure carries decision "create".
+ */
+
+export const MERGE_JUDGE_VERDICTS = ["merge", "create", "uncertain"] as const;
+export type MergeJudgeVerdictName = (typeof MERGE_JUDGE_VERDICTS)[number];
+
+export type ParseMergeVerdictResult =
+  | { ok: true; verdict: MergeJudgeVerdictName; decision: "merge" | "create" }
+  | { ok: false; error: "empty_verdict" | "unknown_verdict"; decision: "create" };
+
+export function parseMergeJudgeVerdict(raw: unknown): ParseMergeVerdictResult {
+  if (typeof raw !== "string") {
+    return { ok: false, error: "empty_verdict", decision: "create" };
+  }
+  const normalized = raw.trim().toLowerCase();
+  if (normalized === "") {
+    return { ok: false, error: "empty_verdict", decision: "create" };
+  }
+  if (!(MERGE_JUDGE_VERDICTS as readonly string[]).includes(normalized)) {
+    return { ok: false, error: "unknown_verdict", decision: "create" };
+  }
+  return {
+    ok: true,
+    verdict: normalized as MergeJudgeVerdictName,
+    decision: normalized === "merge" ? "merge" : "create",
+  };
+}

package/src/extraction-span-provenance.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spanToProvenance } from "./extraction-span-provenance.js";
+
+const TEXT = "The quick brown fox jumps over the lazy dog";
+
+test("spanToProvenance: mid-text span yields exact slice with echoed offsets", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 19 });
+  assert.deepEqual(result, {
+    ok: true,
+    provenance: { quote: "quick brown fox", charStart: 4, charEnd: 19 },
+  });
+  if (result.ok) {
+    assert.ok(result.provenance.charEnd >= result.provenance.charStart);
+  }
+});
+
+test("spanToProvenance: full-text span succeeds", () => {
+  const result = spanToProvenance({ text: TEXT, start: 0, end: TEXT.length });
+  assert.deepEqual(result, {
+    ok: true,
+    provenance: { quote: TEXT, charStart: 0, charEnd: TEXT.length },
+  });
+});
+
+test("spanToProvenance: matching supplied quote succeeds", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 9, quote: "quick" });
+  assert.deepEqual(result, {
+    ok: true,
+    provenance: { quote: "quick", charStart: 4, charEnd: 9 },
+  });
+});
+
+test("spanToProvenance: whitespace-differing quote is quote_mismatch", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 15, quote: "quick  brown" });
+  assert.deepEqual(result, { ok: false, error: "quote_mismatch" });
+});
+
+test("spanToProvenance: paraphrase is quote_mismatch", () => {
+  const result = spanToProvenance({ text: TEXT, start: 4, end: 19, quote: "a fast fox" });
+  assert.deepEqual(result, { ok: false, error: "quote_mismatch" });
+});
+
+test("spanToProvenance: empty span", () => {
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: 3, end: 3 }), {
+    ok: false,
+    error: "empty_span",
+  });
+  assert.deepEqual(spanToProvenance({ text: "", start: 0, end: 0 }), {
+    ok: false,
+    error: "empty_span",
+  });
+});
+
+test("spanToProvenance: out of range", () => {
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: -1, end: 4 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: 0, end: TEXT.length + 1 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+  assert.deepEqual(spanToProvenance({ text: TEXT, start: 10, end: 4 }), {
+    ok: false,
+    error: "out_of_range",
+  });
+});
+
+test("spanToProvenance: non-integers and non-finite offsets throw", () => {
+  assert.throws(() => spanToProvenance({ text: TEXT, start: 1.5, end: 4 }), /integers/);
+  assert.throws(() => spanToProvenance({ text: TEXT, start: 0, end: 3.2 }), /integers/);
+  assert.throws(() => spanToProvenance({ text: TEXT, start: Number.NaN, end: 4 }), /integers/);
+  assert.throws(
+    () => spanToProvenance({ text: TEXT, start: 0, end: Number.POSITIVE_INFINITY }),
+    /integers/,
+  );
+});
+
+test("spanToProvenance: does not mutate the input object", () => {
+  const input = { text: TEXT, start: 4, end: 19, quote: "quick brown fox" };
+  const snapshot = { ...input };
+  spanToProvenance(input);
+  assert.deepEqual(input, snapshot);
+});

package/src/extraction-span-provenance.ts

@@ -0,0 +1,41 @@
+/**
+ * Isolated span-provenance builder (issue #2333).
+ *
+ * Pure. Builds the ProvenanceSource quote/charStart/charEnd triple from
+ * offsets and verifies a model-supplied quote equals the sliced text, so a
+ * bad offset pair can never persist a quote absent from the source.
+ */
+
+export interface SpanProvenance {
+  quote: string;
+  charStart: number;
+  charEnd: number;
+}
+
+export type SpanProvenanceResult =
+  | { ok: true; provenance: SpanProvenance }
+  | { ok: false; error: "empty_span" | "out_of_range" | "quote_mismatch" };
+
+export function spanToProvenance(input: {
+  text: string;
+  start: number;
+  end: number;
+  /** Optional model-supplied quote to verify against the slice. */
+  quote?: string;
+}): SpanProvenanceResult {
+  const { text, start, end, quote } = input;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) {
+    throw new TypeError("span offsets must be integers");
+  }
+  if (start < 0 || end > text.length || end < start) {
+    return { ok: false, error: "out_of_range" };
+  }
+  if (start === end) {
+    return { ok: false, error: "empty_span" };
+  }
+  const sliced = text.slice(start, end);
+  if (quote !== undefined && quote !== sliced) {
+    return { ok: false, error: "quote_mismatch" };
+  }
+  return { ok: true, provenance: { quote: sliced, charStart: start, charEnd: end } };
+}

package/src/recall-deep-rewrite.test.ts

@@ -0,0 +1,199 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  MAX_REFINES_PER_INVOCATION,
+  validateRefineRewrite,
+} from "./recall-deep-rewrite.js";
+
+const base = {
+  currentQuery: "who met at the cafe",
+  refinesUsed: 0,
+};
+
+test("genuine rewrite succeeds and is trimmed", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      ...base,
+      refinedQuery: "  which people met at the cafe on friday  ",
+    }),
+    { ok: true, refinedQuery: "which people met at the cafe on friday" },
+  );
+});
+
+test("success keeps internal whitespace as written", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      ...base,
+      refinedQuery: "which  people  met at the cafe",
+    }),
+    { ok: true, refinedQuery: "which  people  met at the cafe" },
+  );
+});
+
+test("refinesUsed 0 is allowed", () => {
+  assert.equal(
+    validateRefineRewrite({
+      ...base,
+      refinesUsed: 0,
+      refinedQuery: "which people met at the cafe",
+    }).ok,
+    true,
+  );
+});
+
+test("refinesUsed 1 is allowed", () => {
+  assert.equal(
+    validateRefineRewrite({
+      ...base,
+      refinesUsed: 1,
+      refinedQuery: "which people met at the cafe",
+    }).ok,
+    true,
+  );
+});
+
+test("refinesUsed 2 gives refine_budget_spent", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      ...base,
+      refinesUsed: 2,
+      refinedQuery: "which people met at the cafe",
+    }),
+    { ok: false, stop: true, reason: "refine_budget_spent" },
+  );
+});
+
+test("refinesUsed 3 gives refine_budget_spent", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      ...base,
+      refinesUsed: 3,
+      refinedQuery: "which people met at the cafe",
+    }),
+    { ok: false, stop: true, reason: "refine_budget_spent" },
+  );
+});
+
+test("budget check wins over a valid rewrite", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      currentQuery: "who met at the cafe",
+      refinedQuery: "completely different and clearly better query",
+      refinesUsed: MAX_REFINES_PER_INVOCATION,
+    }),
+    { ok: false, stop: true, reason: "refine_budget_spent" },
+  );
+});
+
+test("negative refinesUsed throws", () => {
+  assert.throws(
+    () => validateRefineRewrite({ ...base, refinedQuery: "new query", refinesUsed: -1 }),
+    RangeError,
+  );
+  assert.throws(
+    () => validateRefineRewrite({ ...base, refinedQuery: "new query", refinesUsed: -1 }),
+    /refinesUsed/,
+  );
+});
+
+test("float refinesUsed throws", () => {
+  assert.throws(
+    () => validateRefineRewrite({ ...base, refinedQuery: "new query", refinesUsed: 1.5 }),
+    /refinesUsed/,
+  );
+});
+
+test("NaN refinesUsed throws", () => {
+  assert.throws(
+    () => validateRefineRewrite({ ...base, refinedQuery: "new query", refinesUsed: Number.NaN }),
+    /refinesUsed/,
+  );
+});
+
+test("empty string rewrite gives empty_rewrite", () => {
+  assert.deepEqual(validateRefineRewrite({ ...base, refinedQuery: "" }), {
+    ok: false,
+    stop: true,
+    reason: "empty_rewrite",
+  });
+});
+
+test("whitespace-only rewrite gives empty_rewrite", () => {
+  assert.deepEqual(validateRefineRewrite({ ...base, refinedQuery: "   " }), {
+    ok: false,
+    stop: true,
+    reason: "empty_rewrite",
+  });
+});
+
+test("null rewrite gives empty_rewrite", () => {
+  assert.deepEqual(validateRefineRewrite({ ...base, refinedQuery: null }), {
+    ok: false,
+    stop: true,
+    reason: "empty_rewrite",
+  });
+});
+
+test("undefined rewrite gives empty_rewrite", () => {
+  assert.deepEqual(validateRefineRewrite({ ...base, refinedQuery: undefined }), {
+    ok: false,
+    stop: true,
+    reason: "empty_rewrite",
+  });
+});
+
+test("number rewrite gives empty_rewrite", () => {
+  assert.deepEqual(validateRefineRewrite({ ...base, refinedQuery: 42 }), {
+    ok: false,
+    stop: true,
+    reason: "empty_rewrite",
+  });
+});
+
+test("exact duplicate gives identical_rewrite", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      ...base,
+      refinedQuery: "who met at the cafe",
+    }),
+    { ok: false, stop: true, reason: "identical_rewrite" },
+  );
+});
+
+test("case-different duplicate gives identical_rewrite", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      ...base,
+      refinedQuery: "  Who Met At The Cafe  ",
+    }),
+    { ok: false, stop: true, reason: "identical_rewrite" },
+  );
+});
+
+test("extra internal whitespace duplicate gives identical_rewrite", () => {
+  assert.deepEqual(
+    validateRefineRewrite({
+      currentQuery: "who met",
+      refinedQuery: "who  met",
+      refinesUsed: 0,
+    }),
+    { ok: false, stop: true, reason: "identical_rewrite" },
+  );
+});
+
+test("every failure carries stop true", () => {
+  const failures = [
+    validateRefineRewrite({
+      ...base,
+      refinedQuery: "fine",
+      refinesUsed: 2,
+    }),
+    validateRefineRewrite({ ...base, refinedQuery: "   " }),
+    validateRefineRewrite({ ...base, refinedQuery: "who met at the cafe" }),
+  ];
+  for (const failure of failures) {
+    assert.equal(failure.ok, false);
+    assert.equal(failure.stop, true);
+  }
+});

package/src/recall-deep-rewrite.ts

@@ -0,0 +1,50 @@
+/**
+ * Validate a deep-recall REFINE rewrite (issue #2332).
+ *
+ * Pure. The budget check runs before the rewrite is inspected, so an
+ * exhausted budget cannot be bypassed by a valid-looking query. An empty
+ * or no-progress rewrite is rejected and treated as STOP.
+ */
+export const MAX_REFINES_PER_INVOCATION = 2;
+
+export type RefineRewriteResult =
+  | { ok: true; refinedQuery: string }
+  | {
+      ok: false;
+      stop: true;
+      reason: "empty_rewrite" | "identical_rewrite" | "refine_budget_spent";
+    };
+
+export function validateRefineRewrite(input: {
+  currentQuery: string;
+  refinedQuery: unknown;
+  refinesUsed: number;
+}): RefineRewriteResult {
+  if (!Number.isInteger(input.refinesUsed) || input.refinesUsed < 0) {
+    throw new RangeError(
+      `refinesUsed must be a non-negative integer; got ${JSON.stringify(input.refinesUsed)}`,
+    );
+  }
+  if (input.refinesUsed >= MAX_REFINES_PER_INVOCATION) {
+    return { ok: false, stop: true, reason: "refine_budget_spent" };
+  }
+  if (
+    typeof input.refinedQuery !== "string" ||
+    input.refinedQuery.trim() === ""
+  ) {
+    return { ok: false, stop: true, reason: "empty_rewrite" };
+  }
+  const trimmed = input.refinedQuery.trim();
+  // Comparison key: case-folded with internal whitespace runs collapsed, so
+  // pure case/spacing drift is not progress. The returned rewrite keeps
+  // internal whitespace as the model wrote it.
+  const currentKey = input.currentQuery
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+  const refinedKey = trimmed.toLowerCase().replace(/\s+/g, " ");
+  if (refinedKey === currentKey) {
+    return { ok: false, stop: true, reason: "identical_rewrite" };
+  }
+  return { ok: true, refinedQuery: trimmed };
+}