@remnic/core 9.65.6 → 9.65.8

package/src/config.ts

@@ -43,12 +43,10 @@ import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
 import { parseDependencyPropagationConfig } from "./dependency-propagation-config.js";
 import { parseProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
+import { parseActiveContextFields } from "./active-context-config.js";
 import { parseSkillProjectionConfig } from "./procedural/skill-projection.js";
 import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
-import {
-  parseContradictionLocalizationConfig,
-  parseContradictionScanConfig,
-} from "./contradiction-config.js";
+import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { hasLegacyConnectorEntries } from "./connectors/paths.js";
 import {
@@ -699,7 +697,6 @@ function resolveMemoryOsPreset(value: unknown): MemoryOsPresetName | undefined {
   }
   return MEMORY_OS_PRESET_ALIASES[normalized];
 }
-
 export function parseConfig(
   raw: unknown,
   rawOperatorConfig?: Record<string, unknown> | null,
@@ -3306,6 +3303,7 @@ export function parseConfig(
       typeof cfg.maxCompressionTokensPerHour === "number"
         ? Math.max(0, Math.floor(cfg.maxCompressionTokensPerHour))
         : 1500,
+    ...parseActiveContextFields(cfg),
     behaviorLoopAutoTuneEnabled: cfg.behaviorLoopAutoTuneEnabled === true,
     behaviorLoopLearningWindowDays:
       typeof cfg.behaviorLoopLearningWindowDays === "number"

package/src/context-summary.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure context summary seam (issue #2347).
+ *
+ * The only shared summary path: `LcmSummarizer` and active-context
+ * transforms both call `summarizeContextPure`. No DAG writes, no model
+ * client construction — callers inject the model seam (`SummarizeFn`).
+ */
+import { looksLikeMechanicalTelemetryTranscript } from "./telemetry-transcript.js";
+import { estimateTokenCount } from "./token-estimate.js";
+
+/** Model seam injected by the caller (orchestrator LLM path or a test stub). */
+export type SummarizeFn = (
+  text: string,
+  targetTokens: number,
+  aggressive: boolean,
+) => Promise<string | null>;
+
+export type ContextSummaryMethod = "deterministic" | "llm" | "auto";
+
+export interface PureContextSummaryResult {
+  text: string;
+  method: "llm" | "deterministic";
+  /** True when the requested path degraded (auto mode only). */
+  fallback: boolean;
+  modelUsed?: string;
+  /**
+   * Escalation level preserved for LCM callers: 0 normal LLM, 1 aggressive
+   * LLM, 2 deterministic truncation. Undefined when never escalated.
+   */
+  escalation?: number;
+}
+
+export interface SummarizeContextPureOptions {
+  /** LLM seam. Required for `llm`; without it `auto` degrades to deterministic. */
+  llm?: SummarizeFn;
+  /** Hard ceiling for deterministic truncation output. */
+  deterministicMaxTokens?: number;
+  /** Route obvious mechanical telemetry straight to truncation. */
+  telemetryPrefilterEnabled?: boolean;
+  /** Recorded verbatim in the result for telemetry. */
+  modelUsed?: string;
+}
+
+/** Thrown when `llm` mode cannot produce usable text (no silent fallback). */
+export class ContextSummaryUnavailableError extends Error {
+  constructor(reason: string) {
+    super(`context summary unavailable: ${reason}`);
+    this.name = "ContextSummaryUnavailableError";
+  }
+}
+
+const DEFAULT_DETERMINISTIC_MAX_TOKENS = 256;
+/** LLM output tolerance before an attempt is rejected as too long (LCM parity). */
+const OUTPUT_TOKEN_TOLERANCE = 1.5;
+const MIN_DETERMINISTIC_TOKENS = 1;
+
+/**
+ * Summarize text through the shared seam.
+ *
+ * - `deterministic`: safe truncation only, never throws, never calls the LLM.
+ * - `llm`: exactly one non-aggressive LLM call; failure or unusable output
+ *   throws {@link ContextSummaryUnavailableError} (fallback is not allowed).
+ * - `auto`: escalation ladder (LLM → aggressive LLM → deterministic), with
+ *   `fallback: true` and an `escalation` level on degradation.
+ */
+export async function summarizeContextPure(
+  text: string,
+  targetTokens: number,
+  method: ContextSummaryMethod,
+  options: SummarizeContextPureOptions = {},
+): Promise<PureContextSummaryResult> {
+  const deterministicMaxTokens = Math.max(
+    MIN_DETERMINISTIC_TOKENS,
+    options.deterministicMaxTokens ?? DEFAULT_DETERMINISTIC_MAX_TOKENS,
+  );
+
+  if (method === "deterministic") {
+    return {
+      text: deterministicTruncate(text, Math.min(targetTokens, deterministicMaxTokens)),
+      method: "deterministic",
+      fallback: false,
+    };
+  }
+
+  const usableLlm = options.llm ?? null;
+  if (method === "llm") {
+    if (!usableLlm) {
+      throw new ContextSummaryUnavailableError("no llm seam configured");
+    }
+    const result = await attemptLlm(usableLlm, text, targetTokens, false);
+    if (result === null) {
+      throw new ContextSummaryUnavailableError("llm path failed");
+    }
+    return { text: result, method: "llm", fallback: false, modelUsed: options.modelUsed };
+  }
+
+  // auto
+  if (options.telemetryPrefilterEnabled && looksLikeMechanicalTelemetryTranscript(text)) {
+    return {
+      text: deterministicTruncate(text, Math.min(targetTokens, deterministicMaxTokens)),
+      method: "deterministic",
+      fallback: true,
+      escalation: 2,
+    };
+  }
+
+  if (usableLlm) {
+    const normal = await attemptLlm(usableLlm, text, targetTokens, false);
+    if (normal !== null) {
+      return { text: normal, method: "llm", fallback: false, escalation: 0, modelUsed: options.modelUsed };
+    }
+    const aggressiveTarget = Math.max(32, Math.ceil(targetTokens * 0.5));
+    const aggressive = await attemptLlm(usableLlm, text, aggressiveTarget, true);
+    if (aggressive !== null) {
+      return { text: aggressive, method: "llm", fallback: true, escalation: 1, modelUsed: options.modelUsed };
+    }
+  }
+
+  return {
+    text: deterministicTruncate(text, deterministicMaxTokens),
+    method: "deterministic",
+    fallback: true,
+    escalation: 2,
+  };
+}
+
+/** One LLM attempt; null on error, empty, or over-tolerance output. */
+async function attemptLlm(
+  llm: SummarizeFn,
+  text: string,
+  targetTokens: number,
+  aggressive: boolean,
+): Promise<string | null> {
+  try {
+    const result = await llm(text, targetTokens, aggressive);
+    if (!result || result.trim().length === 0) return null;
+    if (estimateTokenCount(result) > targetTokens * OUTPUT_TOKEN_TOLERANCE) return null;
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+/** Deterministic truncation: first and last sentence, plus middle truncation. */
+export function deterministicTruncate(text: string, maxTokens: number): string {
+  if (maxTokens <= 0 || estimateTokenCount(text) <= maxTokens) return text;
+
+  const sentences = text.split(/(?<=[.!?])\s+/).filter((s) => s.length > 0);
+  if (sentences.length <= 2) return clampToTokenBudget(text, maxTokens);
+
+  const first = sentences[0];
+  const last = sentences[sentences.length - 1];
+  const render = (middle: string[], truncated: boolean): string =>
+    `${first} ${middle.join(" ")}${truncated ? " [...] " : " "}${last}`;
+
+  const base = render([], false);
+  if (estimateTokenCount(base) > maxTokens) return clampToTokenBudget(text, maxTokens);
+  if (estimateTokenCount(render([], true)) > maxTokens) return base;
+
+  const middle: string[] = [];
+  for (let i = 1; i < sentences.length - 1; i++) {
+    const candidate = [...middle, sentences[i]];
+    const truncated = i < sentences.length - 2;
+    if (estimateTokenCount(render(candidate, truncated)) > maxTokens) break;
+    middle.push(sentences[i]);
+  }
+
+  const truncated = middle.length < sentences.length - 2;
+  return clampToTokenBudget(render(middle, truncated), maxTokens);
+}
+
+function clampToTokenBudget(text: string, maxTokens: number): string {
+  const codePoints = [...text];
+  let low = 0;
+  let high = codePoints.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (estimateTokenCount(codePoints.slice(0, mid).join("")) <= maxTokens) low = mid;
+    else high = mid - 1;
+  }
+  return codePoints.slice(0, low).join("");
+}

package/src/eval-trajectory-contracts.ts

@@ -0,0 +1,411 @@
+/**
+ * Issue #2345 — internal contracts, config bounds, digests, and validators for
+ * the privacy-safe action-to-outcome trajectory evaluator.
+ *
+ * Internal module: never re-exported from the package root by itself. The
+ * public surface is `eval-trajectory.ts` (builder) and `eval-trajectory-store.ts`
+ * (validation, persistence, promotion gate). Keeping this layer separate holds
+ * every file under the #1995 new-file ratchet cap while preserving one
+ * subsystem.
+ */
+
+import { createHash } from "node:crypto";
+import type { MemoryActionOutcome, MemoryActionPolicyDecision, MemoryActionType } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Constants and bounded config
+// ---------------------------------------------------------------------------
+
+export const EVAL_TRAJECTORY_REPORT_SCHEMA_VERSION = 1;
+
+/** Default delayed-outcome window: 7 days, half-open `actionAt < outcomeAt < actionAt + window`. */
+export const DEFAULT_EVAL_TRAJECTORY_OUTCOME_WINDOW_MS = 604_800_000;
+/** Default allowed clock skew for input timestamps beyond `asOf`. */
+export const DEFAULT_EVAL_TRAJECTORY_MAX_FUTURE_SKEW_MS = 300_000;
+/** Default cap on emitted rows per report. */
+export const DEFAULT_EVAL_TRAJECTORY_MAX_ROWS = 5_000;
+export const MAX_EVAL_TRAJECTORY_ROWS_LIMIT = 50_000;
+/** Default reader expiry: a report older than 30 days fails the checked read. */
+export const DEFAULT_EVAL_TRAJECTORY_REPORT_MAX_AGE_MS = 2_592_000_000;
+
+export interface EvalTrajectoryWeights {
+  task: number;
+  context: number;
+  trust: number;
+  stale: number;
+}
+
+export const DEFAULT_EVAL_TRAJECTORY_WEIGHTS: Readonly<EvalTrajectoryWeights> = Object.freeze({
+  task: 1,
+  context: 0.25,
+  trust: 1,
+  stale: 0.5,
+});
+
+const MEMORY_ACTION_TYPES: Record<string, true> = {
+  store_episode: true,
+  store_note: true,
+  update_note: true,
+  create_artifact: true,
+  summarize_node: true,
+  discard: true,
+  link_graph: true,
+};
+
+/** Action types whose live execution is destructive (irreversible) for promotion gating. */
+export const DESTRUCTIVE_ACTION_TYPES: Record<string, true> = { discard: true };
+
+export const STALE_LIFECYCLE_STATES: Record<string, true> = {
+  active: true,
+  stale: true,
+  archived: true,
+  superseded: true,
+};
+
+export const STALE_OUTCOMES: Record<string, true> = {
+  success: true,
+  partial: true,
+  failure: true,
+  unknown: true,
+};
+
+/**
+ * Fixed promotion thresholds for `deriveUnifiedMemoryPromotionReport`. These
+ * are deliberately conservative named constants — #2348 owns application, and
+ * any loosening must be a reviewed change, not a config knob.
+ */
+export const EVAL_TRAJECTORY_PROMOTION_THRESHOLDS = Object.freeze({
+  minJoinedRows: 30,
+  minReach: 0.5,
+});
+
+export interface EvalTrajectoryRunConfig {
+  outcomeWindowMs: number;
+  maxFutureSkewMs: number;
+  weights: EvalTrajectoryWeights;
+  maxRows: number;
+}
+
+export function resolveEvalTrajectoryRunConfig(partial?: Partial<EvalTrajectoryRunConfig>): EvalTrajectoryRunConfig {
+  const source = partial ?? {};
+  const weightsSource = source.weights ?? DEFAULT_EVAL_TRAJECTORY_WEIGHTS;
+  const weights: EvalTrajectoryWeights = {
+    task: Number(weightsSource.task),
+    context: Number(weightsSource.context),
+    trust: Number(weightsSource.trust),
+    stale: Number(weightsSource.stale),
+  };
+  for (const [name, value] of Object.entries(weights)) {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error(`eval trajectory weight '${name}' must be a finite non-negative number`);
+    }
+  }
+  const totalWeight = weights.task + weights.context + weights.trust + weights.stale;
+  if (!(totalWeight > 0)) {
+    throw new Error("eval trajectory weights must have a positive total weight");
+  }
+
+  const outcomeWindowMs = Number(source.outcomeWindowMs ?? DEFAULT_EVAL_TRAJECTORY_OUTCOME_WINDOW_MS);
+  if (!Number.isSafeInteger(outcomeWindowMs) || outcomeWindowMs <= 0) {
+    throw new Error("outcomeWindowMs must be a positive integer");
+  }
+  const maxFutureSkewMs = Number(source.maxFutureSkewMs ?? DEFAULT_EVAL_TRAJECTORY_MAX_FUTURE_SKEW_MS);
+  if (!Number.isSafeInteger(maxFutureSkewMs) || maxFutureSkewMs < 0) {
+    throw new Error("maxFutureSkewMs must be a non-negative integer");
+  }
+  const maxRows = Number(source.maxRows ?? DEFAULT_EVAL_TRAJECTORY_MAX_ROWS);
+  if (!Number.isSafeInteger(maxRows) || maxRows < 1 || maxRows > MAX_EVAL_TRAJECTORY_ROWS_LIMIT) {
+    throw new Error(`maxRows must be an integer in [1, ${MAX_EVAL_TRAJECTORY_ROWS_LIMIT}]`);
+  }
+  return { outcomeWindowMs, maxFutureSkewMs, weights, maxRows };
+}
+
+// ---------------------------------------------------------------------------
+// Input contracts (sanitized caller rows — raw IDs live here, never in output)
+// ---------------------------------------------------------------------------
+
+export type EvalTrajectoryTaskResult = "success" | "partial" | "failure";
+export type EvalTrajectoryOutcomeSource = "eval_artifact" | "causal_trajectory" | "memory_outcome";
+export type EvalStaleUseLifecycleState = "active" | "stale" | "archived" | "superseded";
+export type EvalStaleUseOutcome = "success" | "partial" | "failure" | "unknown";
+
+export interface EvalActionInput {
+  schemaVersion: 1;
+  /** Stable action identity. Required — rows without it are rejected. */
+  actionId: string;
+  namespace: string;
+  actionAt: string;
+  action: MemoryActionType;
+  /** Immediate operation status. Never a delayed task result. */
+  immediateStatus: MemoryActionOutcome;
+  policyDecision?: MemoryActionPolicyDecision;
+  policyVersion?: string;
+  /** Producing subsystem tag (enum-like; exported through the projection). */
+  subsystem?: string;
+  sessionKey?: string;
+  memoryId?: string;
+  trajectoryId?: string;
+  contextTokensBefore?: number;
+  contextTokensAfter?: number;
+  contextTokenBudget?: number;
+  contextOverflow?: boolean;
+  replayMismatch?: boolean;
+  missingReversibleGuard?: boolean;
+  outsideEligibility?: boolean;
+}
+
+export interface EvalOutcomeInput {
+  schemaVersion: 1;
+  namespace: string;
+  /** Stable local identity used only for digesting/dedup — never exported. */
+  outcomeId: string;
+  outcomeAt: string;
+  source: EvalTrajectoryOutcomeSource;
+  /** success | partial | failure. Memory-outcome results never become task results. */
+  result?: EvalTrajectoryTaskResult;
+  actionId?: string;
+  trajectoryId?: string;
+  memoryId?: string;
+  sessionKey?: string;
+}
+
+export interface EvalStaleUseEvidenceInput {
+  schemaVersion: 1;
+  namespace: string;
+  actionId: string;
+  memoryId: string;
+  lifecycleState: EvalStaleUseLifecycleState;
+  usedAt: string;
+  outcome: EvalStaleUseOutcome;
+}
+
+/**
+ * Normalized digest-only projections. Joins run on these, so raw IDs never
+ * reach the metric or export layers. Equality joins survive digesting because
+ * equal raw keys digest to equal values under the same run salt.
+ */
+export interface EvalActionProjection {
+  schemaVersion: 1;
+  actionDigest: string;
+  namespaceDigest: string;
+  actionAt: string;
+  action: MemoryActionType;
+  immediateStatus: MemoryActionOutcome;
+  policyDecision: MemoryActionPolicyDecision | null;
+  policyVersion: string | null;
+  source: string | null;
+  actionIdDigest: string;
+  sessionKeyDigest: string | null;
+  memoryIdDigest: string | null;
+  trajectoryIdDigest: string | null;
+  contextTokenCost: number | null;
+  trustViolation: 0 | 1;
+}
+
+export interface EvalOutcomeProjection {
+  schemaVersion: 1;
+  outcomeDigest: string;
+  namespaceDigest: string;
+  recordedAt: string;
+  kind: EvalTrajectoryOutcomeSource;
+  /** 1 | 0.5 | 0 for task sources; null when unknown or memory-sourced. */
+  value: number | null;
+  sourceRefDigest: string;
+  actionIdDigest: string | null;
+  trajectoryIdDigest: string | null;
+  memoryIdDigest: string | null;
+  sessionKeyDigest: string | null;
+}
+
+export interface EvalStaleUseEvidence {
+  schemaVersion: 1;
+  actionDigest: string;
+  memoryDigest: string;
+  lifecycleState: EvalStaleUseLifecycleState;
+  usedAt: string;
+  outcome: EvalStaleUseOutcome;
+}
+
+// ---------------------------------------------------------------------------
+// Exported report contracts (digests, enums, numbers only)
+// ---------------------------------------------------------------------------
+
+export type EvalTrajectoryMetricName = "taskOutcome" | "contextTokenCost" | "trustViolation" | "staleMemoryHarm";
+
+export type EvalTrajectoryJoinKind = "action_id" | "trajectory_id" | "memory_scope" | "session_scope";
+
+export type EvalTrajectoryRowStatus =
+  | "joined"
+  | "ambiguous"
+  | "late_outcome"
+  | "future_outcome"
+  | "missing_within_window";
+
+export type EvalTrajectoryRejectionReason =
+  | "missing_action_id"
+  | "namespace_mismatch"
+  | "invalid_timestamp"
+  | "future_beyond_skew"
+  | "malformed_row"
+  | "invalid_context_budget"
+  | "duplicate_row"
+  | "max_rows_exceeded";
+
+export interface EvalActionOutcomeRow {
+  schemaVersion: 1;
+  actionDigest: string;
+  outcomeDigest: string | null;
+  join: EvalTrajectoryJoinKind | null;
+  status: EvalTrajectoryRowStatus;
+  outcomeRecordedAt: string | null;
+  taskOutcome: number | null;
+  contextTokenCost: number | null;
+  trustViolation: 0 | 1;
+  staleMemoryHarm: 0 | 0.5 | 1;
+  actionConditionedUtility: number | null;
+  missingDimensions: EvalTrajectoryMetricName[];
+}
+
+export interface EvalTrajectoryAggregates {
+  rowCount: number;
+  statusCounts: Record<EvalTrajectoryRowStatus, number>;
+  metricMeans: {
+    taskOutcome: number | null;
+    contextTokenCost: number | null;
+    trustViolation: number | null;
+    staleMemoryHarm: number | null;
+    actionConditionedUtility: number | null;
+  };
+  coverage: {
+    reach: number | null;
+    joined: number;
+    missingWithinWindow: number;
+    lateOutcome: number;
+    futureOutcome: number;
+    ambiguous: number;
+    excludedFromMeans: number;
+  };
+  byAction: Array<{ action: MemoryActionType; rowCount: number; meanUtility: number | null }>;
+  byPolicyDecision: Array<{ policyDecision: string; rowCount: number; meanUtility: number | null }>;
+}
+
+export interface EvalTrajectoryReport {
+  schemaVersion: 1;
+  reportId: string;
+  namespaceDigest: string;
+  asOf: string;
+  config: EvalTrajectoryRunConfig;
+  sourceCounts: { actions: number; outcomes: number; staleUseEvidence: number };
+  rejectionCounts: Record<EvalTrajectoryRejectionReason, number>;
+  rows: EvalActionOutcomeRow[];
+  aggregates: EvalTrajectoryAggregates;
+  inputFingerprint: string;
+  contentHash: string;
+}
+
+export type UnifiedMemoryPromotionState =
+  | "insufficient_evidence"
+  | "shadow_eligible"
+  | "active_reversible_eligible"
+  | "active_destructive_review_only"
+  | "demote_to_shadow";
+
+export interface UnifiedMemoryPromotionReport {
+  schemaVersion: 1;
+  sourceReportId: string;
+  namespaceDigest: string;
+  asOf: string;
+  inputFingerprint: string;
+  state: UnifiedMemoryPromotionState;
+  reasons: string[];
+  evidence: {
+    joinedRows: number;
+    reach: number | null;
+    meanUtility: number | null;
+    trustViolations: number;
+    staleHarms: number;
+    destructiveJoinedRows: number;
+  };
+  contentHash: string;
+}
+
+// ---------------------------------------------------------------------------
+// Digests and deterministic serialization
+// ---------------------------------------------------------------------------
+
+export function sha256Hex(input: string): string {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+export function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+export function digestOf(salt: string, payload: unknown): string {
+  return sha256Hex(`${salt}\n${canonicalJson(payload)}`);
+}
+
+/** Byte-identical serialization for given report content, independent of construction order. */
+export function serializeEvalTrajectoryReport(report: EvalTrajectoryReport): string {
+  return `${JSON.stringify(sortKeysDeep(report), null, 2)}\n`;
+}
+
+/** Total-order comparators (equality guarded — never let equal keys claim both orders). */
+export function compareStrings(a: string, b: string): number {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+export function compareRows(a: EvalActionOutcomeRow, b: EvalActionOutcomeRow): number {
+  const byTime = compareStrings(a.outcomeRecordedAt ?? "", b.outcomeRecordedAt ?? "");
+  if (byTime !== 0) return byTime;
+  return compareStrings(a.actionDigest, b.actionDigest);
+}
+
+// ---------------------------------------------------------------------------
+// Small shared validators (local copies — evals.ts is at its ratchet ceiling)
+// ---------------------------------------------------------------------------
+
+const ISO_UTC_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+export function isIsoTimestamp(value: unknown): value is string {
+  return typeof value === "string" && ISO_UTC_TIMESTAMP_RE.test(value) && !Number.isNaN(Date.parse(value));
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function isMemoryActionType(value: unknown): value is MemoryActionType {
+  return typeof value === "string" && MEMORY_ACTION_TYPES[value] === true;
+}
+
+export function isRowStatus(value: unknown): value is EvalTrajectoryRowStatus {
+  return (
+    value === "joined" ||
+    value === "ambiguous" ||
+    value === "late_outcome" ||
+    value === "future_outcome" ||
+    value === "missing_within_window"
+  );
+}
+
+export function isHexSha256(value: unknown): value is string {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}