@remnic/core 9.69.2 → 9.69.4

package/src/activity/journal-vault-prereq.test.ts

@@ -0,0 +1,121 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  VAULT_JOURNAL_PREREQUISITES,
+  checkVaultJournalPrerequisites,
+  type VaultJournalPrereqResult,
+} from "./journal-vault-prereq.js";
+
+const SATISFIED = {
+  vaultEnabled: true,
+  dailyNotePath: "/vault/journal/2026-08-20.md",
+  journalSection: "Journal",
+} as const;
+
+test("all three satisfied returns exactly ok", () => {
+  assert.deepEqual(
+    checkVaultJournalPrerequisites(SATISFIED),
+    { ok: true } satisfies VaultJournalPrereqResult,
+  );
+});
+
+test("vault.enabled unmet alone", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    vaultEnabled: false,
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.enabled"]);
+});
+
+test("vault.dailyNotePath unmet alone", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    dailyNotePath: undefined,
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.dailyNotePath"]);
+});
+
+test("vault.readback.journalSection unmet alone", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    journalSection: "",
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.readback.journalSection"]);
+});
+
+test("all three unmet lists all three in declaration order", () => {
+  const result = checkVaultJournalPrerequisites({
+    vaultEnabled: undefined,
+    dailyNotePath: undefined,
+    journalSection: undefined,
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, [...VAULT_JOURNAL_PREREQUISITES]);
+});
+
+test("string \"true\" does not satisfy vault.enabled", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    vaultEnabled: "true",
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.enabled"]);
+});
+
+test("number 1 does not satisfy vault.enabled", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    vaultEnabled: 1,
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.enabled"]);
+});
+
+test("whitespace-only dailyNotePath is unmet", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    dailyNotePath: "   ",
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.dailyNotePath"]);
+});
+
+test("whitespace-only journalSection is unmet", () => {
+  const result = checkVaultJournalPrerequisites({
+    ...SATISFIED,
+    journalSection: "\t\n",
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.missing, ["vault.readback.journalSection"]);
+});
+
+test("message names every missing key and is a single line", () => {
+  const result = checkVaultJournalPrerequisites({
+    vaultEnabled: "true",
+    dailyNotePath: 42,
+    journalSection: "  ",
+  });
+  assert.equal(result.ok, false);
+  for (const key of result.missing) {
+    assert.ok(result.message.includes(key), `message must name ${key}`);
+  }
+  for (const key of VAULT_JOURNAL_PREREQUISITES) {
+    assert.ok(result.message.includes(key), `message must name ${key}`);
+  }
+  assert.ok(!result.message.includes("\n"), "message must be a single line");
+});
+
+test("input is not mutated", () => {
+  const input = Object.freeze({
+    vaultEnabled: false,
+    dailyNotePath: " ",
+    journalSection: "",
+  });
+  const snapshot = { ...input };
+  checkVaultJournalPrerequisites(input);
+  assert.deepEqual(input, snapshot);
+});

package/src/activity/journal-vault-prereq.ts

@@ -0,0 +1,41 @@
+/**
+ * Vault journal read-back prerequisites (issue #1987).
+ *
+ * Pure. `journal.source: "vault"` requires all three prerequisites; the
+ * caller checks `source` first via the journal-source parser and calls this
+ * only for vault mode. Reports EVERY unmet prerequisite at once so the user
+ * gets one actionable error, not the first hit.
+ */
+
+export const VAULT_JOURNAL_PREREQUISITES = [
+  "vault.enabled",
+  "vault.dailyNotePath",
+  "vault.readback.journalSection",
+] as const;
+export type VaultJournalPrerequisite = (typeof VAULT_JOURNAL_PREREQUISITES)[number];
+
+export type VaultJournalPrereqResult =
+  | { ok: true }
+  | { ok: false; missing: VaultJournalPrerequisite[]; message: string };
+
+export function checkVaultJournalPrerequisites(input: {
+  vaultEnabled?: unknown;
+  dailyNotePath?: unknown;
+  journalSection?: unknown;
+}): VaultJournalPrereqResult {
+  const missing: VaultJournalPrerequisite[] = [];
+  if (input.vaultEnabled !== true) missing.push("vault.enabled");
+  // Exact values are validated: trim() only detects blankness, never rewrites.
+  if (typeof input.dailyNotePath !== "string" || input.dailyNotePath.trim().length === 0) {
+    missing.push("vault.dailyNotePath");
+  }
+  if (typeof input.journalSection !== "string" || input.journalSection.trim().length === 0) {
+    missing.push("vault.readback.journalSection");
+  }
+  if (missing.length === 0) return { ok: true };
+  return {
+    ok: false,
+    missing,
+    message: `vault journal read-back prerequisites unmet: ${missing.join(", ")}`,
+  };
+}

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

@@ -0,0 +1,147 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  ANALYSIS_METADATA_MAX_FIELD_LENGTH,
+  buildAnalysisRunMetadata,
+} from "./analysis-metadata.js";
+
+const VALID = {
+  provider: "openai",
+  model: "gpt-5.2",
+  promptVersion: "timeline-analysis.v2",
+  observationCount: 12,
+};
+
+const STRING_FIELDS = ["provider", "model", "promptVersion"] as const;
+
+test("a valid record round-trips with exactly the documented keys", () => {
+  const result = buildAnalysisRunMetadata(VALID);
+  assert.deepEqual(result, VALID);
+  assert.deepEqual(Object.keys(result).sort(), [
+    "model",
+    "observationCount",
+    "promptVersion",
+    "provider",
+  ]);
+});
+
+test("real provider and model slugs are accepted", () => {
+  for (const model of ["gpt-5.2", "claude-4_1", "anthropic/claude-4", "llama3:8b", "o1"]) {
+    assert.equal(buildAnalysisRunMetadata({ ...VALID, model }).model, model);
+  }
+  for (const promptVersion of ["v3", "2026-08-01", "timeline.v2"]) {
+    assert.equal(
+      buildAnalysisRunMetadata({ ...VALID, promptVersion }).promptVersion,
+      promptVersion,
+    );
+  }
+});
+
+// The guarantee this record makes is that it cannot carry content. A length
+// cap does not deliver that: a short single-line string is happily prose.
+test("prose is rejected even when short and single-line", () => {
+  for (const field of STRING_FIELDS) {
+    for (const prose of [
+      "Summarize this user's activity",
+      "The user said they were tired",
+      "api key lives in the operator profile",
+    ]) {
+      assert.throws(
+        () => buildAnalysisRunMetadata({ ...VALID, [field]: prose }),
+        /must be an identifier/,
+        `${field} must reject ${JSON.stringify(prose)}`,
+      );
+    }
+  }
+});
+
+test("every line-break character is rejected, including U+2028 and U+2029", () => {
+  for (const field of STRING_FIELDS) {
+    for (const sep of ["\n", "\r", "\u2028", "\u2029"]) {
+      assert.throws(
+        () => buildAnalysisRunMetadata({ ...VALID, [field]: `openai${sep}gpt` }),
+        /must not contain a line break/,
+      );
+    }
+  }
+});
+
+test("blank, padded, and non-string values are rejected", () => {
+  for (const field of STRING_FIELDS) {
+    assert.throws(() => buildAnalysisRunMetadata({ ...VALID, [field]: "" }), /must not be empty/);
+    assert.throws(
+      () => buildAnalysisRunMetadata({ ...VALID, [field]: "   " }),
+      /must be an identifier/,
+    );
+    // Validate the exact value: a padded identifier is not trimmed into validity.
+    assert.throws(
+      () => buildAnalysisRunMetadata({ ...VALID, [field]: " openai" }),
+      /must be an identifier/,
+    );
+    assert.throws(
+      () => buildAnalysisRunMetadata({ ...VALID, [field]: 42 as unknown as string }),
+      /must be a string; received number/,
+    );
+  }
+});
+
+test("the field length cap is enforced at the boundary", () => {
+  const max = "a".repeat(ANALYSIS_METADATA_MAX_FIELD_LENGTH);
+  assert.equal(buildAnalysisRunMetadata({ ...VALID, model: max }).model, max);
+  assert.throws(
+    () => buildAnalysisRunMetadata({ ...VALID, model: `${max}a` }),
+    /is too long/,
+  );
+});
+
+test("observationCount accepts 0 and rejects every non-count", () => {
+  assert.equal(buildAnalysisRunMetadata({ ...VALID, observationCount: 0 }).observationCount, 0);
+  for (const bad of [-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+    assert.throws(
+      () => buildAnalysisRunMetadata({ ...VALID, observationCount: bad }),
+      /observationCount must be a non-negative integer/,
+    );
+  }
+});
+
+// An error message is a log line. A caller that mis-passes prompt text or a
+// secret must not have it echoed there through the failure path.
+test("a rejected value is never echoed in the error message", () => {
+  const secret = "my-api-key-value-goes-here-0123456789";
+  assert.throws(
+    () => buildAnalysisRunMetadata({ ...VALID, provider: `${secret} leaked` }),
+    (error: unknown) => {
+      assert.ok(error instanceof RangeError);
+      assert.equal(error.message.includes(secret), false, "message must not echo the value");
+      return true;
+    },
+  );
+  const circular: Record<string, unknown> = {};
+  circular.self = circular;
+  assert.throws(
+    () =>
+      buildAnalysisRunMetadata({
+        ...VALID,
+        observationCount: circular as unknown as number,
+      }),
+    (error: unknown) => {
+      // JSON.stringify would throw a TypeError here instead of the intended
+      // RangeError, and would echo content for a plain object.
+      assert.ok(error instanceof RangeError);
+      assert.equal(error.message.includes("self"), false);
+      return true;
+    },
+  );
+  assert.throws(
+    () =>
+      buildAnalysisRunMetadata({
+        ...VALID,
+        observationCount: 10n as unknown as number,
+      }),
+    (error: unknown) => {
+      assert.ok(error instanceof RangeError, "a bigint must not escape as a TypeError");
+      return true;
+    },
+  );
+});

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

@@ -0,0 +1,97 @@
+/**
+ * Analysis run metadata (issue #2050).
+ *
+ * Pure builder for the provider/model/prompt-version record attached to
+ * stored analysis results and telemetry.
+ *
+ * The no-content guarantee is enforced by SHAPE, not by length: each field
+ * must match an identifier/version syntax, so prose cannot be stored as a
+ * "model name". A 200-character single-line string is happily prose
+ * ("Summarize this user\u0027s activity"), which is why a length cap alone was
+ * not the boundary this record needs. Errors never echo a rejected value,
+ * so a mis-passed prompt cannot reach logs through the failure path either.
+ */
+export interface AnalysisRunMetadata {
+  provider: string;
+  model: string;
+  promptVersion: string;
+  /** Observation ids the run consumed, for evidence tracing. */
+  observationCount: number;
+}
+
+export const ANALYSIS_METADATA_MAX_FIELD_LENGTH = 120;
+
+/**
+ * Identifier syntax for provider and model: letters, digits, and the
+ * separators real provider/model slugs use (`openai`, `gpt-5.2`,
+ * `anthropic/claude-4_1`, `llama3:8b`). No spaces, so a sentence cannot pass.
+ */
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:\-\/]*$/;
+
+/**
+ * Prompt versions are identifiers or dates (`v3`, `2026-08-01`,
+ * `timeline-analysis.v2`), so the same syntax applies.
+ */
+const FIELD_PATTERNS: Readonly<Record<string, RegExp>> = {
+  provider: IDENTIFIER,
+  model: IDENTIFIER,
+  promptVersion: IDENTIFIER,
+};
+
+function validateMetadataField(field: string, value: unknown): string {
+  // Never interpolate the value itself: an error string is a log line, and a
+  // caller that mis-passes prompt text must not have it echoed there.
+  if (typeof value !== "string") {
+    throw new RangeError(
+      `analysis run metadata ${field} must be a string; received ${typeof value}`,
+    );
+  }
+  if (value.length === 0) {
+    throw new RangeError(`analysis run metadata ${field} must not be empty`);
+  }
+  if (value.length > ANALYSIS_METADATA_MAX_FIELD_LENGTH) {
+    throw new RangeError(
+      `analysis run metadata ${field} is too long (max ${ANALYSIS_METADATA_MAX_FIELD_LENGTH} characters)`,
+    );
+  }
+  // Report a line break as a line break even though the pattern would also
+  // reject it. U+2028 and U+2029 are line separators too: they break
+  // line-oriented log consumers exactly like CR and LF.
+  if (/[\n\r\u2028\u2029]/.test(value)) {
+    throw new RangeError(`analysis run metadata ${field} must not contain a line break`);
+  }
+  const pattern = FIELD_PATTERNS[field];
+  if (pattern === undefined) {
+    throw new RangeError(`analysis run metadata has no pattern for field ${field}`);
+  }
+  if (!pattern.test(value)) {
+    throw new RangeError(
+      `analysis run metadata ${field} must be an identifier (letters, digits, and ._:-/ only)`,
+    );
+  }
+  return value;
+}
+
+export function buildAnalysisRunMetadata(input: {
+  provider: string;
+  model: string;
+  promptVersion: string;
+  observationCount: number;
+}): AnalysisRunMetadata {
+  const provider = validateMetadataField("provider", input.provider);
+  const model = validateMetadataField("model", input.model);
+  const promptVersion = validateMetadataField("promptVersion", input.promptVersion);
+  const observationCount = input.observationCount;
+  if (
+    typeof observationCount !== "number" ||
+    !Number.isInteger(observationCount) ||
+    observationCount < 0
+  ) {
+    // Report the type only. JSON.stringify would echo mis-passed content into
+    // the log, and it throws outright on a bigint or a circular object.
+    throw new RangeError(
+      `analysis run metadata observationCount must be a non-negative integer; received ${typeof observationCount}`,
+    );
+  }
+  return { provider, model, promptVersion, observationCount };
+}

package/src/activity/timeline/index.ts

@@ -24,3 +24,4 @@ export * from "./analysis-order.js";
 export * from "./recap-window.js";
 export * from "./analysis-failure.js";
 export * from "./recap-merge-edits.js";
+export * from "./analysis-metadata.js";

package/src/dedup/index.ts

@@ -481,3 +481,9 @@ export {
   type MergeFrontmatterUpdate,
   type MergeProvenanceSource,
 } from "./merge-provenance.js";
+
+export {
+  MERGE_CONTENT_LENGTH_FACTOR,
+  checkMergedContent,
+  type MergeContentCheck,
+} from "./merge-content.js";

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

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  MERGE_CONTENT_LENGTH_FACTOR,
+  checkMergedContent,
+} from "./merge-content.js";
+
+const INCOMING = "alpha";
+const TARGET = "beta";
+
+test("normal merge passes and returns the content unchanged", () => {
+  const merged = "alpha and beta combined";
+  const result = checkMergedContent({
+    mergedContent: merged,
+    incomingContent: INCOMING,
+    targetContent: TARGET,
+  });
+  assert.deepEqual(result, { ok: true, content: merged });
+});
+
+test("merged content at exactly the limit is accepted", () => {
+  const limit = MERGE_CONTENT_LENGTH_FACTOR * (INCOMING.length + TARGET.length);
+  const merged = "x".repeat(limit);
+  const result = checkMergedContent({
+    mergedContent: merged,
+    incomingContent: INCOMING,
+    targetContent: TARGET,
+  });
+  assert.deepEqual(result, { ok: true, content: merged });
+});
+
+test("merged content one character over the limit is oversized with the reported limit", () => {
+  const limit = MERGE_CONTENT_LENGTH_FACTOR * (INCOMING.length + TARGET.length);
+  const result = checkMergedContent({
+    mergedContent: "x".repeat(limit + 1),
+    incomingContent: INCOMING,
+    targetContent: TARGET,
+  });
+  assert.deepEqual(result, { ok: false, reason: "oversized", limit });
+});
+
+test("empty, whitespace-only, null, undefined, object, and bigint merged content are all empty refusals", () => {
+  const cases: unknown[] = ["", "   ", "\t\n", null, undefined, { body: 1 }, 42n];
+  for (const mergedContent of cases) {
+    const result = checkMergedContent({
+      mergedContent,
+      incomingContent: INCOMING,
+      targetContent: TARGET,
+    });
+    assert.deepEqual(result, {
+      ok: false,
+      reason: "empty",
+      limit: MERGE_CONTENT_LENGTH_FACTOR * (INCOMING.length + TARGET.length),
+    });
+  }
+});
+
+test("two empty inputs make the limit zero, so any content is oversized", () => {
+  const result = checkMergedContent({
+    mergedContent: "x",
+    incomingContent: "",
+    targetContent: "",
+  });
+  assert.deepEqual(result, { ok: false, reason: "oversized", limit: 0 });
+});
+
+test("non-string incomingContent throws RangeError naming the field", () => {
+  assert.throws(
+    () =>
+      checkMergedContent({
+        mergedContent: "ok",
+        incomingContent: 7 as unknown as string,
+        targetContent: TARGET,
+      }),
+    (error: unknown) =>
+      error instanceof RangeError && /incomingContent/.test(error.message),
+  );
+});
+
+test("non-string targetContent throws RangeError naming the field", () => {
+  assert.throws(
+    () =>
+      checkMergedContent({
+        mergedContent: "ok",
+        incomingContent: INCOMING,
+        targetContent: null as unknown as string,
+      }),
+    (error: unknown) =>
+      error instanceof RangeError && /targetContent/.test(error.message),
+  );
+});
+
+test("the rejected merged content never appears in an error message or refusal result", () => {
+  const sentinel = "UNIQUE-LEAK-SENTINEL";
+  const leakyObject = { body: sentinel };
+
+  const refusal = checkMergedContent({
+    mergedContent: leakyObject,
+    incomingContent: INCOMING,
+    targetContent: TARGET,
+  });
+  assert.ok(!refusal.ok);
+  assert.ok(!JSON.stringify(refusal).includes(sentinel));
+
+  assert.throws(
+    () =>
+      checkMergedContent({
+        mergedContent: sentinel,
+        incomingContent: undefined as unknown as string,
+        targetContent: TARGET,
+      }),
+    (error: unknown) =>
+      error instanceof RangeError && !error.message.includes(sentinel),
+  );
+});

package/src/dedup/merge-content.ts

@@ -0,0 +1,40 @@
+/**
+ * Merged-content acceptance check (issue #2330).
+ *
+ * A judge-merged body that is blank or a runaway continuation is refused so
+ * the write path can fall back to create. `mergedContent` arrives from a
+ * model and gets a typed refusal; non-string `incomingContent`/
+ * `targetContent` is a caller bug and throws. Internal helper; wiring into
+ * the write path is a later slice.
+ */
+export const MERGE_CONTENT_LENGTH_FACTOR = 4;
+
+export type MergeContentCheck =
+  | { ok: true; content: string }
+  | { ok: false; reason: "empty" | "oversized"; limit: number };
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string") {
+    throw new RangeError(`merge ${field} must be a string`);
+  }
+  return value;
+}
+
+export function checkMergedContent(input: {
+  mergedContent: unknown;
+  incomingContent: string;
+  targetContent: string;
+}): MergeContentCheck {
+  const incoming = requireString(input.incomingContent, "incomingContent");
+  const target = requireString(input.targetContent, "targetContent");
+  const limit = MERGE_CONTENT_LENGTH_FACTOR * (incoming.length + target.length);
+
+  const merged = input.mergedContent;
+  if (typeof merged !== "string" || merged.trim() === "") {
+    return { ok: false, reason: "empty", limit };
+  }
+  if (merged.length > limit) {
+    return { ok: false, reason: "oversized", limit };
+  }
+  return { ok: true, content: merged };
+}

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

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { SPAN_OUTCOMES, tallySpanFallbacks } from "./extraction-span-fallback.js";
+import {
+  SPAN_GATE_MAX_FALLBACK_RATE_PCT,
+  evaluateSpanPhaseGate,
+} from "./extraction-span-gate.js";
+
+test("tallySpanFallbacks: mixed outcomes compute the expected percentage", () => {
+  const tally = tallySpanFallbacks(["span", "fallback", "span", "span", "fallback"]);
+  assert.equal(tally.attempts, 5);
+  assert.equal(tally.fallbacks, 2);
+  assert.equal(tally.fallbackRatePct, 40);
+});
+
+test("tallySpanFallbacks: all-span is exactly 0", () => {
+  const tally = tallySpanFallbacks(["span", "span", "span"]);
+  assert.equal(tally.fallbacks, 0);
+  assert.equal(tally.fallbackRatePct, 0);
+});
+
+test("tallySpanFallbacks: all-fallback is exactly 100", () => {
+  const tally = tallySpanFallbacks(["fallback", "fallback"]);
+  assert.equal(tally.fallbacks, 2);
+  assert.equal(tally.fallbackRatePct, 100);
+});
+
+test("tallySpanFallbacks: zero attempts means no measurement, never NaN", () => {
+  const tally = tallySpanFallbacks([]);
+  assert.equal(tally.attempts, 0);
+  assert.equal(tally.fallbacks, 0);
+  assert.equal(tally.fallbackRatePct, null);
+  assert.equal(Number.isNaN(tally.fallbackRatePct as unknown as number), false);
+});
+
+test("tallySpanFallbacks: unknown outcome throws and lists the allow-list", () => {
+  assert.throws(() => tallySpanFallbacks(["span", "fall back"]), /unknown span outcome/);
+  // No normalization: case variants are unknown outcomes, never successes.
+  assert.throws(() => tallySpanFallbacks(["Span"]), /unknown span outcome/);
+  assert.throws(() => tallySpanFallbacks(["FALLBACK"]), /unknown span outcome/);
+  assert.throws(
+    () => tallySpanFallbacks(["span", "fallback", "recovered"]),
+    /unknown span outcome "recovered"; expected one of \[span, fallback\]/,
+  );
+  assert.deepEqual(SPAN_OUTCOMES, ["span", "fallback"]);
+});
+
+test("tallySpanFallbacks: non-array input throws", () => {
+  assert.throws(() => tallySpanFallbacks("span" as never), /array/);
+  assert.throws(() => tallySpanFallbacks(null as never), /array/);
+  assert.throws(() => tallySpanFallbacks(undefined as never), /array/);
+});
+
+test("tallySpanFallbacks: 1-of-3 rounds deterministically across calls", () => {
+  const first = tallySpanFallbacks(["fallback", "span", "span"]);
+  const second = tallySpanFallbacks(["fallback", "span", "span"]);
+  assert.equal(first.fallbackRatePct, 33.3333);
+  assert.deepEqual(first, second);
+});
+
+test("tallySpanFallbacks: a rate at or above the gate bar is what the gate rejects", () => {
+  const outcomes = [
+    "span",
+    "fallback",
+    "span",
+    "span",
+    "fallback",
+    "span",
+    "span",
+    "span",
+    "span",
+    "span",
+  ];
+  const tally = tallySpanFallbacks(outcomes);
+  assert.equal(tally.fallbackRatePct, 20); // 2 of 10
+  assert.ok(tally.fallbackRatePct >= SPAN_GATE_MAX_FALLBACK_RATE_PCT);
+  const verdict = evaluateSpanPhaseGate({
+    wallClockReductionPct: 30,
+    judgeScoreDropPoints: 0,
+    fallbackRatePct: tally.fallbackRatePct,
+  });
+  assert.equal(verdict.conditions.fallbackRate, false);
+  assert.equal(verdict.pass, false);
+  assert.ok(verdict.failed.includes("fallbackRate"));
+});
+
+test("tallySpanFallbacks: does not mutate the input", () => {
+  const outcomes = ["span", "fallback", "span"];
+  tallySpanFallbacks(outcomes);
+  assert.deepEqual(outcomes, ["span", "fallback", "span"]);
+});
+
+// Review: a 0 rate satisfies the gate's `fallbackRatePct < 15`, so returning 0
+// for an empty sample let an unmeasured run approve Phase B. null cannot be
+// passed to the gate at all, which is the enforcement the comment lacked.
+test("tallySpanFallbacks: an empty sample is null, which the gate cannot accept as a rate", () => {
+  const tally = tallySpanFallbacks([]);
+  assert.equal(tally.fallbackRatePct, null);
+  assert.equal(tally.attempts, 0);
+  assert.equal(Number.isNaN(tally.fallbackRatePct as unknown as number), false);
+  // A measured all-span run is a real 0 and stays distinguishable from null.
+  assert.equal(tallySpanFallbacks(["span"]).fallbackRatePct, 0);
+});