@remnic/core 9.3.708 → 9.3.709

package/src/correction/correction-contract.ts

@@ -0,0 +1,416 @@
+/**
+ * correction/correction-contract.ts — Types for the Correction Contract
+ * (issue #1580).
+ *
+ * The Correction Contract is the SINGLE plan/apply pipeline every memory
+ * correction flows through: supersession, invalidation, tombstone, edit,
+ * rescope, redaction. A correction arrives as a plain-language statement
+ * ("we migrated to MySQL in March"); the planner turns it into a structured
+ * {@link CorrectionPlan}; the executor applies the plan in non-destructive
+ * order through the existing storage/orchestrator chokepoints.
+ *
+ * This module is PURE types + validation helpers — no I/O, no side effects.
+ * The planner and executor live in sibling modules and inject their own
+ * collaborators so the contract is testable in isolation (rule 33).
+ *
+ * Design rules honored (issue #1580 design section):
+ *   - Plans are per-request state on disk, never module-level (rules 11/47).
+ *   - Caller-supplied namespaces are NEVER trusted raw — the service
+ *     resolves them through the normal namespace policy (rule 42).
+ *   - Bulk operations refuse past maxAffected (no silent truncation, §39).
+ *   - `never_store` redaction patterns must be bounded and safe (§34).
+ */
+
+import type { MemoryCategory, MemoryFrontmatter } from "../types.js";
+
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+
+/**
+ * The user-facing input: a plain-language correction plus optional explicit
+ * targets. This is what every surface (MCP / HTTP / CLI) collects before
+ * handing off to the planner.
+ */
+export interface CorrectionRequest {
+  /** Natural-language correction statement. Required, non-empty. */
+  text: string;
+  /**
+   * Explicit target memory ids (or handles via #1582). When present the
+   * planner resolves these directly; an unknown id is an explicit error
+   * (rule 34), never a silent empty plan. When absent the planner searches.
+   */
+  targetIds?: string[];
+  /** Session key for namespace/principal resolution. */
+  sessionKey?: string;
+  /** Authenticated principal (resolved by the service, never trusted raw). */
+  principal?: string;
+  /**
+   * Caller-suggested namespace. ALWAYS re-resolved through the namespace
+   * policy by the service before reaching the planner (rule 42). The
+   * planner only sees the ALREADY-AUTHORIZED namespace.
+   */
+  namespace?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Classification + actions
+// ---------------------------------------------------------------------------
+
+export type CorrectionClassification =
+  | "wrong"
+  | "outdated"
+  | "incomplete"
+  | "wrong_scope"
+  | "never_store";
+
+export const CORRECTION_CLASSIFICATIONS: readonly CorrectionClassification[] = [
+  "wrong",
+  "outdated",
+  "incomplete",
+  "wrong_scope",
+  "never_store",
+];
+
+/**
+ * A draft for a replacement memory (supersede action). Mirrors the subset of
+ * {@link MemoryFrontmatter} a correction caller may legitimately set; the
+ * executor fills in id/created/updated/source.
+ */
+export interface MemoryDraft {
+  content: string;
+  category?: MemoryCategory;
+  confidence?: number;
+  tags?: string[];
+  entityRef?: string;
+  /** Optional event-time anchor for bi-temporal supersession (#1578). */
+  validAt?: string;
+  /** Optional observed-at anchor for bi-temporal supersession (#1578). */
+  observedAt?: string;
+  structuredAttributes?: Record<string, string>;
+}
+
+/**
+ * The known {@link MemoryCategory} values. A replacement/rescope category must
+ * be one of these — rejecting path-like or unexpected strings before they reach
+ * `StorageManager.writeMemory`, which incorporates the category into the
+ * generated memory id/path (review thread Of-XJ).
+ */
+export const MEMORY_CATEGORIES: readonly MemoryCategory[] = [
+  "fact", "preference", "correction", "entity", "decision",
+  "relationship", "principle", "commitment", "moment",
+  "skill", "rule", "procedure", "reasoning_trace",
+];
+
+export type CorrectionAction =
+  /** Outdated: a new fact replaces the loser. */
+  | { kind: "supersede"; loserId: string; replacement?: MemoryDraft }
+  /** Incomplete / minor-wrong: a versioned edit to an existing memory. */
+  | { kind: "edit"; memoryId: string; patch: string }
+  /** Wrong: retire + tombstone. */
+  | { kind: "retract"; memoryId: string }
+  /** Wrong scope: move to a different namespace. */
+  | { kind: "rescope"; memoryId: string; toNamespace: string }
+  /** Never-store: a future-extraction redaction rule. */
+  | { kind: "redaction_rule"; pattern: string };
+
+export const CORRECTION_ACTION_KINDS: readonly CorrectionAction["kind"][] = [
+  "supersede",
+  "edit",
+  "retract",
+  "rescope",
+  "redaction_rule",
+];
+
+// ---------------------------------------------------------------------------
+// Plan + outcome
+// ---------------------------------------------------------------------------
+
+/**
+ * One affected memory in a plan: where it lives, an excerpt, why it is
+ * affected, and (when available) the source quote that supports the
+ * correction (#1575 provenance).
+ */
+export interface CorrectionAffectedEntry {
+  memoryId: string;
+  /** File path relative to the storage dir, for diff rendering. */
+  path: string;
+  excerpt: string;
+  why: string;
+  sourceQuote?: string;
+}
+
+/**
+ * A persisted, expiring correction plan. Read-only artifact produced by the
+ * planner; consumed (once) by the executor.
+ */
+export interface CorrectionPlan {
+  planId: string;
+  request: CorrectionRequest;
+  /** Authorized namespace the plan is scoped to (resolved by the service). */
+  namespace: string;
+  affected: CorrectionAffectedEntry[];
+  classification: CorrectionClassification;
+  actions: CorrectionAction[];
+  /** Human-readable diff preview rendered via page-versioning. */
+  diff: string;
+  /** Planner confidence in [0, 1]. `0` means manual selection required. */
+  confidence: number;
+  warnings: string[];
+  createdAt: string;
+  /** ISO timestamp after which apply rejects the plan as expired. */
+  expiresAt: string;
+  /**
+   * Lifecycle: `pending` → `applying` → `applied`|`partial` (or `discarded`).
+   * The executor flips a plan to `applying` BEFORE running any mutation
+   * (review thread OgIqt): if the process dies mid-apply, the plan stays
+   * `applying` and is NOT silently retryable — a partially-applied plan must
+   * never be re-applied wholesale (it would duplicate succeeded actions).
+   */
+  status?: "pending" | "applying" | "applied" | "discarded" | "partial";
+}
+
+/**
+ * Per-action outcome recorded by the executor. An action whose new-state
+ * write failed is `failed`; the executor never destroys old state for a
+ * failed action (rule 25 / checklist §14).
+ */
+export interface CorrectionActionResult {
+  action: CorrectionAction;
+  status: "applied" | "failed" | "skipped";
+  /** For supersede: the new memory id. For edit: the memory id. */
+  memoryId?: string;
+  /** For supersede/retract: the emitted tombstone id (if any). */
+  tombstoneId?: string;
+  error?: string;
+}
+
+export interface CorrectionOutcome {
+  planId: string;
+  status: "applied" | "partial";
+  results: CorrectionActionResult[];
+  /** Audit-record memory id (corrections are themselves memories). */
+  auditMemoryId: string;
+  /** ISO timestamp of the apply. */
+  appliedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helpers (pure) — shared by planner, executor, and surface tests
+// ---------------------------------------------------------------------------
+
+/** Maximum supported `text` length. Surfaces bound this earlier; the planner
+ *  re-validates so a direct-service caller cannot bypass. */
+export const CORRECTION_TEXT_MAX = 10_000;
+
+/** Maximum supported redaction pattern length (§34 — bounded patterns). */
+export const REDACTION_PATTERN_MAX = 256;
+
+/**
+ * Validate a {@link CorrectionRequest}'s invariants. Returns the cleaned
+ * request or throws with a field-specific message (rule 51 — list valid
+ * options, never silently default).
+ */
+export function validateCorrectionRequest(request: CorrectionRequest): CorrectionRequest {
+  if (!request || typeof request !== "object") {
+    throw new CorrectionContractError("CorrectionRequest must be an object.");
+  }
+  const text = typeof request.text === "string" ? request.text.trim() : "";
+  if (text.length === 0) {
+    throw new CorrectionContractError("CorrectionRequest.text is required and must be non-empty.");
+  }
+  if (text.length > CORRECTION_TEXT_MAX) {
+    throw new CorrectionContractError(
+      `CorrectionRequest.text exceeds the ${CORRECTION_TEXT_MAX}-character limit (${text.length}).`,
+    );
+  }
+  const targetIds = Array.isArray(request.targetIds)
+    ? request.targetIds.filter((id): id is string => typeof id === "string" && id.length > 0)
+    : undefined;
+  if (targetIds !== undefined && targetIds.length === 0) {
+    // An empty array is treated as "not provided" so callers can forward
+    // optional fields without a separate presence flag.
+    return {
+      text,
+      ...(request.sessionKey ? { sessionKey: request.sessionKey } : {}),
+      ...(request.principal ? { principal: request.principal } : {}),
+      ...(request.namespace ? { namespace: request.namespace } : {}),
+    };
+  }
+  return {
+    text,
+    ...(targetIds ? { targetIds } : {}),
+    ...(request.sessionKey ? { sessionKey: request.sessionKey } : {}),
+    ...(request.principal ? { principal: request.principal } : {}),
+    ...(request.namespace ? { namespace: request.namespace } : {}),
+  };
+}
+
+/**
+ * Validate a redaction pattern (§34 — bounded, literal-or-safe-regex; reject
+ * catastrophic patterns). Returns the cleaned pattern or throws.
+ */
+export function validateRedactionPattern(pattern: string): string {
+  if (typeof pattern !== "string") {
+    throw new CorrectionContractError("redaction_rule.pattern must be a string.");
+  }
+  const trimmed = pattern.trim();
+  if (trimmed.length === 0) {
+    throw new CorrectionContractError("redaction_rule.pattern is required.");
+  }
+  if (trimmed.length > REDACTION_PATTERN_MAX) {
+    throw new CorrectionContractError(
+      `redaction_rule.pattern exceeds the ${REDACTION_PATTERN_MAX}-character bound.`,
+    );
+  }
+  // Reject patterns that could match an unbounded string (catastrophic /
+  // overly-broad). A literal or a bounded regex is fine; a bare `.*` / `.`
+  // regex is not. We do NOT execute the regex (ReDoS); we only inspect shape.
+  if (isRegexLike(trimmed) && isOverlyBroadRegex(trimmed)) {
+    throw new CorrectionContractError(
+      "redaction_rule.pattern is too broad — use a bounded literal or a more specific pattern.",
+    );
+  }
+  return trimmed;
+}
+
+/** Heuristic: treat `/.../` or presence of regex metacharacters as regex. */
+function isRegexLike(pattern: string): boolean {
+  if (pattern.startsWith("/") && pattern.endsWith("/") && pattern.length >= 2) return true;
+  return /[\\^$.|?*+()[\]{}]/.test(pattern);
+}
+
+/** Reject a regex that would match an arbitrary-length run of any character. */
+function isOverlyBroadRegex(pattern: string): boolean {
+  const body = pattern.startsWith("/") && pattern.endsWith("/")
+    ? pattern.slice(1, -1)
+    : pattern;
+  // `.*`, `.+`, `.`, or `(.*)` etc. anywhere → overly broad.
+  if (/(?:^|[^\\])\(\.\*\)|(?:^|[^\\])\.\*|(?:^|[^\\])\.\+|^\.([^*+]?)$/.test(body)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Validate the shape of a {@link CorrectionAction}. Used by the executor
+ * before applying and by the surface layer to reject malformed client input
+ * (rule 51 — list valid kinds).
+ */
+export function validateCorrectionAction(action: unknown): asserts action is CorrectionAction {
+  if (!action || typeof action !== "object") {
+    throw new CorrectionContractError("CorrectionAction must be an object.");
+  }
+  const a = action as Record<string, unknown>;
+  if (typeof a.kind !== "string" || !CORRECTION_ACTION_KINDS.includes(a.kind as CorrectionAction["kind"])) {
+    throw new CorrectionContractError(
+      `CorrectionAction.kind must be one of: ${CORRECTION_ACTION_KINDS.join(", ")}.`,
+    );
+  }
+  switch (a.kind) {
+    case "supersede":
+      if (typeof a.loserId !== "string" || a.loserId.length === 0) {
+        throw new CorrectionContractError("supersede.loserId is required.");
+      }
+      if (a.replacement !== undefined && a.replacement !== null) {
+        validateMemoryDraft(a.replacement);
+      }
+      break;
+    case "edit":
+      if (typeof a.memoryId !== "string" || a.memoryId.length === 0) {
+        throw new CorrectionContractError("edit.memoryId is required.");
+      }
+      if (typeof a.patch !== "string" || a.patch.length === 0) {
+        throw new CorrectionContractError("edit.patch is required and must be non-empty.");
+      }
+      break;
+    case "retract":
+      if (typeof a.memoryId !== "string" || a.memoryId.length === 0) {
+        throw new CorrectionContractError("retract.memoryId is required.");
+      }
+      break;
+    case "rescope":
+      if (typeof a.memoryId !== "string" || a.memoryId.length === 0) {
+        throw new CorrectionContractError("rescope.memoryId is required.");
+      }
+      if (typeof a.toNamespace !== "string" || a.toNamespace.trim().length === 0) {
+        throw new CorrectionContractError("rescope.toNamespace is required.");
+      }
+      break;
+    case "redaction_rule":
+      if (typeof a.pattern !== "string") {
+        throw new CorrectionContractError("redaction_rule.pattern is required.");
+      }
+      validateRedactionPattern(a.pattern);
+      break;
+  }
+}
+
+/** Validate a {@link MemoryDraft}. Throws on invalid shape. */
+export function validateMemoryDraft(draft: unknown): asserts draft is MemoryDraft {
+  if (!draft || typeof draft !== "object") {
+    throw new CorrectionContractError("MemoryDraft must be an object.");
+  }
+  const d = draft as Record<string, unknown>;
+  if (typeof d.content !== "string" || d.content.trim().length === 0) {
+    throw new CorrectionContractError("MemoryDraft.content is required and must be non-empty.");
+  }
+  if (d.category !== undefined) {
+    if (typeof d.category !== "string" || !(MEMORY_CATEGORIES as readonly string[]).includes(d.category)) {
+      throw new CorrectionContractError(
+        `MemoryDraft.category must be one of: ${MEMORY_CATEGORIES.join(", ")}.`,
+      );
+    }
+  }
+  if (d.confidence !== undefined && (typeof d.confidence !== "number" || d.confidence < 0 || d.confidence > 1)) {
+    throw new CorrectionContractError("MemoryDraft.confidence must be a number in [0, 1].");
+  }
+  if (d.tags !== undefined && !Array.isArray(d.tags)) {
+    throw new CorrectionContractError("MemoryDraft.tags must be an array.");
+  }
+  if (d.structuredAttributes !== undefined && (typeof d.structuredAttributes !== "object" || d.structuredAttributes === null)) {
+    throw new CorrectionContractError("MemoryDraft.structuredAttributes must be an object.");
+  }
+}
+
+/**
+ * Deterministic fallback plan (rule 13): when the planner's LLM is
+ * unavailable, the plan degrades to a search result, never an error page.
+ * Classification `outdated`, confidence `0`, actions empty.
+ */
+export function deterministicFallbackPlan(args: {
+  request: CorrectionRequest;
+  namespace: string;
+  affected: CorrectionAffectedEntry[];
+  warnings: string[];
+  createdAt: string;
+  expiresAt: string;
+}): CorrectionPlan {
+  return {
+    planId: newPlanId(),
+    request: args.request,
+    namespace: args.namespace,
+    affected: args.affected,
+    classification: "outdated",
+    actions: [],
+    diff: "",
+    confidence: 0,
+    warnings: [...args.warnings, "planner LLM unavailable — manual action selection required"],
+    createdAt: args.createdAt,
+    expiresAt: args.expiresAt,
+    status: "pending",
+  };
+}
+
+/** Generate a stable plan id. Exposed for tests + deterministic fallback. */
+export function newPlanId(): string {
+  return `corr-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** Error class for contract violations. Surfaces map it to a 400 / input error. */
+export class CorrectionContractError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CorrectionContractError";
+  }
+}