@remnic/core 9.69.2 → 9.69.4

package/src/extraction-span-fallback.ts

@@ -0,0 +1,62 @@
+/**
+ * Span-validation fallback-rate tally (issue #2333 Phase A).
+ *
+ * Counts per-fact extraction outcomes — "span" means the span validated,
+ * "fallback" means validation fell back — and produces the `fallbackRatePct`
+ * input that `evaluateSpanPhaseGate` consumes (finite, [0, 100]; the gate
+ * refuses Phase B at >= SPAN_GATE_MAX_FALLBACK_RATE_PCT).
+ *
+ * An unrecognized outcome throws: bucketing it as a success would understate
+ * the fallback rate and could wave a failing gate through. A zero-attempt
+ * tally reports `fallbackRatePct: null`, which the gate's `number` input
+ * cannot accept, so an unmeasured run cannot be handed to it as 0%.
+ *
+ * Pure. No I/O, no randomness. The input array is not mutated.
+ */
+
+export const SPAN_OUTCOMES = ["span", "fallback"] as const;
+export type SpanOutcome = (typeof SPAN_OUTCOMES)[number];
+
+export interface SpanFallbackTally {
+  attempts: number;
+  fallbacks: number;
+  /**
+   * Percentage in [0, 100] for the gate's `fallbackRatePct` input, or `null`
+   * when there were no attempts.
+   *
+   * `null` rather than 0 is the enforcement: a 0 satisfies the gate's
+   * `fallbackRatePct < 15` comparison, so an unmeasured run could have
+   * approved Phase B. `null` is not assignable to the gate's `number`
+   * parameter, so a caller must handle "no measurement" explicitly instead of
+   * relying on a comment to tell it not to.
+   */
+  fallbackRatePct: number | null;
+}
+
+export function tallySpanFallbacks(outcomes: readonly string[]): SpanFallbackTally {
+  if (!Array.isArray(outcomes)) {
+    throw new TypeError(
+      `tallySpanFallbacks expects an array of span outcomes, got ${typeof outcomes}`,
+    );
+  }
+  let fallbacks = 0;
+  for (const outcome of outcomes) {
+    if (!SPAN_OUTCOMES.includes(outcome as SpanOutcome)) {
+      throw new TypeError(
+        `unknown span outcome ${JSON.stringify(outcome)}; expected one of [${SPAN_OUTCOMES.join(", ")}]`,
+      );
+    }
+    if (outcome === "fallback") {
+      fallbacks += 1;
+    }
+  }
+  const attempts = outcomes.length;
+  if (attempts === 0) {
+    // No measurement. Never 0 and never NaN: 0 would pass the gate's
+    // `< 15` check on no data, and NaN would fail it for the same absence.
+    return { attempts: 0, fallbacks: 0, fallbackRatePct: null };
+  }
+  // Cap at 4 decimal places so repeated tallies are byte-identical.
+  const fallbackRatePct = Math.round((fallbacks / attempts) * 100 * 10_000) / 10_000;
+  return { attempts, fallbacks, fallbackRatePct };
+}

package/src/shared-context/curation-lint.test.ts

@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { lintCuratedClaims } from "./curation-lint.js";
+
+const AVAILABLE = ["item-1", "item-2", "item-3"];
+
+test("a fully-cited claim set returns no findings", () => {
+  const findings = lintCuratedClaims({
+    claims: [
+      { claimId: "c-1", citedItemIds: ["item-1", "item-2"] },
+      { claimId: "c-2", citedItemIds: ["item-3"] },
+    ],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, []);
+});
+
+test("missing citedItemIds gives no_citations", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1" }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [{ claimId: "c-1", reason: "no_citations" }]);
+});
+
+test("an empty citedItemIds array gives no_citations", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1", citedItemIds: [] }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [{ claimId: "c-1", reason: "no_citations" }]);
+});
+
+test("an all-blank citedItemIds array gives no_citations", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1", citedItemIds: ["", "   ", "\t"] }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [{ claimId: "c-1", reason: "no_citations" }]);
+});
+
+test("one valid plus one unknown citation gives unknown_citation listing only the unknown", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1", citedItemIds: ["item-1", "item-404"] }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [
+    { claimId: "c-1", reason: "unknown_citation", unknownIds: ["item-404"] },
+  ]);
+});
+
+test("all-unknown citations give no_citations, not unknown_citation (precedence)", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1", citedItemIds: ["nope-1", "nope-2"] }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [{ claimId: "c-1", reason: "no_citations" }]);
+});
+
+test("unknown ids are sorted ascending and deduplicated", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1", citedItemIds: ["item-1", "zz", "aa", "zz", "mm"] }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [
+    { claimId: "c-1", reason: "unknown_citation", unknownIds: ["aa", "mm", "zz"] },
+  ]);
+});
+
+test("a whitespace-padded citation is unknown (exact comparison, no trim)", () => {
+  const findings = lintCuratedClaims({
+    claims: [{ claimId: "c-1", citedItemIds: ["item-1", " item-2"] }],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [
+    { claimId: "c-1", reason: "unknown_citation", unknownIds: [" item-2"] },
+  ]);
+});
+
+test("a blank claimId throws RangeError naming claimId", () => {
+  assert.throws(
+    () =>
+      lintCuratedClaims({
+        claims: [{ claimId: "   ", citedItemIds: ["item-1"] }],
+        availableItemIds: AVAILABLE,
+      }),
+    (err: unknown) => err instanceof RangeError && /claimId/.test(err.message),
+  );
+});
+
+test("duplicate claim ids are each linted independently", () => {
+  const findings = lintCuratedClaims({
+    claims: [
+      { claimId: "c-1", citedItemIds: ["item-404", "item-1"] },
+      { claimId: "c-1" },
+    ],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(findings, [
+    { claimId: "c-1", reason: "no_citations" },
+    { claimId: "c-1", reason: "unknown_citation", unknownIds: ["item-404"] },
+  ]);
+});
+
+test("findings are deterministic across two calls with shuffled input", () => {
+  const expected: Array<{ claimId: string; reason: string; unknownIds?: string[] }> = [
+    { claimId: "c-1", reason: "no_citations" },
+    { claimId: "c-2", reason: "no_citations" },
+    { claimId: "c-3", reason: "unknown_citation", unknownIds: ["item-404"] },
+  ];
+  const claims = [
+    { claimId: "c-3", citedItemIds: ["item-3", "item-404"] },
+    { claimId: "c-1" },
+    { claimId: "c-2", citedItemIds: [] },
+  ];
+  const first = lintCuratedClaims({ claims, availableItemIds: AVAILABLE });
+  const second = lintCuratedClaims({
+    claims: [claims[2], claims[0], claims[1]],
+    availableItemIds: AVAILABLE,
+  });
+  assert.deepEqual(first, expected);
+  assert.deepEqual(second, expected);
+});
+
+test("inputs are not mutated", () => {
+  const claims = [
+    { claimId: "c-1", citedItemIds: ["zz", "item-1", "zz"] as const },
+  ];
+  const availableItemIds = ["item-1", "item-2"];
+  const claimsSnapshot = structuredClone(claims);
+  const availableSnapshot = [...availableItemIds];
+  lintCuratedClaims({ claims, availableItemIds });
+  assert.deepEqual(claims, claimsSnapshot);
+  assert.deepEqual(availableItemIds, availableSnapshot);
+});
+
+// Review: two claims sharing a claimId AND a reason still differ by their
+// unknownIds, so a comparator returning 0 there let input order decide the
+// output — the contract says the result is deterministic.
+test("duplicate claim ids with different unknown ids sort deterministically", () => {
+  const available = ["item-ok"];
+  const claims = [
+    { claimId: "claim-dup", citedItemIds: ["item-ok", "zeta-missing"] },
+    { claimId: "claim-dup", citedItemIds: ["item-ok", "alpha-missing"] },
+  ];
+  const forward = lintCuratedClaims({ claims, availableItemIds: available });
+  const reversed = lintCuratedClaims({ claims: [...claims].reverse(), availableItemIds: available });
+  assert.deepEqual(forward, reversed, "reversing the input must not reorder findings");
+  assert.deepEqual(
+    forward.map((f) => f.unknownIds),
+    [["alpha-missing"], ["zeta-missing"]],
+    "findings order by unknownIds once claimId and reason tie",
+  );
+});

package/src/shared-context/curation-lint.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared-context curation self-check (issue #1957 requirement 4).
+ *
+ * Pure. A synthesized claim with no traceable source is a lint error:
+ * report claims whose citations are missing, blank, or absent from the
+ * item ids the curation run actually had available.
+ */
+
+export interface CuratedClaim {
+  claimId: string;
+  /** Shared-context item ids this claim was synthesized from. */
+  citedItemIds?: readonly string[];
+}
+
+export interface CurationLintFinding {
+  claimId: string;
+  reason: "no_citations" | "unknown_citation";
+  /** Cited ids that are not in the available set. Only for unknown_citation. */
+  unknownIds?: string[];
+}
+
+export function lintCuratedClaims(input: {
+  claims: readonly CuratedClaim[];
+  availableItemIds: readonly string[];
+}): CurationLintFinding[] {
+  const available = new Set(input.availableItemIds);
+  const findings: CurationLintFinding[] = [];
+
+  for (const claim of input.claims) {
+    const claimId = claim.claimId;
+    if (typeof claimId !== "string" || claimId.trim().length === 0) {
+      throw new RangeError("claimId must be a non-blank string");
+    }
+
+    const unknown = new Set<string>();
+    let validCount = 0;
+    for (const id of claim.citedItemIds ?? []) {
+      if (id.trim().length === 0) continue;
+      if (available.has(id)) {
+        validCount += 1;
+      } else {
+        unknown.add(id);
+      }
+    }
+
+    if (validCount === 0) {
+      findings.push({ claimId, reason: "no_citations" });
+      continue;
+    }
+    if (unknown.size > 0) {
+      findings.push({ claimId, reason: "unknown_citation", unknownIds: [...unknown].sort() });
+    }
+  }
+
+  findings.sort((a, b) => {
+    if (a.claimId !== b.claimId) return a.claimId < b.claimId ? -1 : 1;
+    if (a.reason !== b.reason) return a.reason < b.reason ? -1 : 1;
+    // Duplicate claim ids are linted independently, so two findings can share
+    // both keys above and still differ. Without this tertiary key the result
+    // would depend on upstream iteration order, which the deterministic-output
+    // contract forbids.
+    const left = (a.unknownIds ?? []).join(",");
+    const right = (b.unknownIds ?? []).join(",");
+    if (left !== right) return left < right ? -1 : 1;
+    return 0;
+  });
+  return findings;
+}