@remnic/core 9.3.717 → 9.3.719

package/src/correction/passive-capture.ts

@@ -0,0 +1,335 @@
+/**
+ * correction/passive-capture.ts — routes detected passive corrections to the
+ * Correction Contract (#1580) by mode: queue, auto, or off (issue #1581).
+ *
+ * This module is the thin handoff between the extraction post-processing step
+ * (which calls `detectPassiveCorrections`) and the CorrectionService's
+ * `plan()` / `apply()` pipeline. It adds NO parallel correction logic (rule 22)
+ * — the planner does all the locating/classifying; this module only decides
+ * whether to queue the resulting plan for review or auto-apply it.
+ *
+ * Guards (auto mode):
+ *   - plan confidence ≥ confidenceFloor
+ *   - classification ∈ {outdated, wrong}
+ *   - affected.length ≤ autoApplyMaxAffected
+ *   - every action ∈ {supersede, edit, retract} (never auto-apply
+ *     rescope/redaction_rule/never_store — those are policy changes)
+ * If ANY guard fails, the plan falls back to queue.
+ *
+ * Session scoping (rule 42): a correction detected in session S plans only
+ * against S's readable namespaces. The CorrectionService already enforces this
+ * through its namespace policy; this module passes the session-scoped context.
+ *
+ * Dedup: fingerprint detected corrections by `bufferKey + normalizedCorrectionText`
+ * so parallel sessions / re-flushes don't double-plan.
+ */
+
+import { log } from "../logger.js";
+import type { PassiveCorrection } from "./passive-correction-detector.js";
+import type {
+  CorrectionClassification,
+  CorrectionOutcome,
+  CorrectionPlan,
+  CorrectionRequest,
+  CorrectionAction,
+} from "./correction-contract.js";
+import {
+  enqueuePassiveCorrectionNotification,
+} from "./passive-correction-notifications.js";
+
+// ---------------------------------------------------------------------------
+// Config + context
+// ---------------------------------------------------------------------------
+
+export type CorrectionCaptureMode = "off" | "queue" | "auto";
+
+export interface PassiveCaptureConfig {
+  mode: CorrectionCaptureMode;
+  confidenceFloor: number;
+  autoApplyMaxAffected: number;
+}
+
+export interface PassiveCaptureContext {
+  /** The correction feature must be enabled for capture to run. */
+  correctionEnabled: boolean;
+  /** Whether this is a live session (not replay/import). Auto-apply is
+   *  live-session only — replayed history may contain corrections the user
+   *  later re-reverted; queue those. */
+  isLiveSession: boolean;
+  /** Buffer key for dedup fingerprinting. */
+  bufferKey: string;
+  /** Session key for namespace/principal resolution. */
+  sessionKey?: string;
+  /** Authenticated principal. */
+  principal?: string;
+  /** Authorized namespace the extraction wrote to. */
+  namespace: string;
+}
+
+// ---------------------------------------------------------------------------
+// Deps (injected — the orchestrator wires these)
+// ---------------------------------------------------------------------------
+
+export interface PassiveCaptureDeps {
+  /** Plan a correction through the Correction Contract. */
+  planCorrection(request: CorrectionRequest): Promise<CorrectionPlan>;
+  /** Apply a planned correction (auto mode only). */
+  applyCorrection(
+    planId: string,
+    opts: { confirm: true; namespace?: string; sessionKey?: string; principal?: string },
+  ): Promise<CorrectionOutcome>;
+  /** Resolve the storage dir for notification enqueue (per namespace). */
+  storageDir(namespace: string): Promise<string>;
+  /**
+   * Resolve a memory handle (`[m:xxxx]`) to a concrete memory id, returning
+   * null when the handle is unresolvable in the session (graceful — the
+   * planner then falls back to text search). Wired to the orchestrator single
+   * shared `resolveMemoryIdOrHandle` helper (#1582) so handle resolution has
+   * one path (rule 22). Review: "memory handles not resolved".
+   */
+  resolveHandle?(ref: string, sessionKey?: string): string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Telemetry
+// ---------------------------------------------------------------------------
+
+export interface PassiveCaptureTelemetry {
+  detected: number;
+  queued: number;
+  autoApplied: number;
+  /** Reason → count for auto-apply suppressions. */
+  suppressedReasons: Record<string, number>;
+}
+
+export function emptyTelemetry(): PassiveCaptureTelemetry {
+  return { detected: 0, queued: 0, autoApplied: 0, suppressedReasons: {} };
+}
+
+// ---------------------------------------------------------------------------
+// Dedup fingerprint
+// ---------------------------------------------------------------------------
+
+/** Normalize correction text for fingerprinting (case + whitespace + punctuation). */
+function normalizeForFingerprint(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
+function correctionFingerprint(bufferKey: string, correction: PassiveCorrection): string {
+  return `${bufferKey}::${correction.polarity}::${normalizeForFingerprint(correction.targetHint)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-apply guards
+// ---------------------------------------------------------------------------
+
+/** Action kinds that are safe to auto-apply (state-preserving, not policy changes). */
+const AUTO_APPLICABLE_ACTION_KINDS = new Set(["supersede", "edit", "retract"]);
+
+/** Classifications safe for auto-apply. */
+const AUTO_APPLICABLE_CLASSIFICATIONS = new Set<CorrectionClassification>(["outdated", "wrong"]);
+
+export type AutoApplySuppressionReason =
+  | "non_live_session"
+  | "confidence_below_floor"
+  | "classification_not_allowed"
+  | "affected_too_large"
+  | "disallowed_action_kind"
+  | "empty_plan";
+
+/**
+ * Evaluate all auto-apply guards. Returns the suppression reason (if any), or
+ * null if auto-apply may proceed.
+ */
+export function evaluateAutoApplyGuards(
+  plan: CorrectionPlan,
+  config: PassiveCaptureConfig,
+  isLiveSession: boolean,
+): AutoApplySuppressionReason | null {
+  if (!isLiveSession) return "non_live_session";
+  if (plan.confidence < config.confidenceFloor) return "confidence_below_floor";
+  if (!AUTO_APPLICABLE_CLASSIFICATIONS.has(plan.classification)) {
+    return "classification_not_allowed";
+  }
+  if (plan.affected.length > config.autoApplyMaxAffected) {
+    return "affected_too_large";
+  }
+  // An empty action list is a no-op plan (review: "queue plans that contain no
+  // actions"). Auto-applying it would mark a correction as applied, write an
+  // audit record + notification, and record the dedup fingerprint — yet nothing
+  // changed. Suppress so it queues for human review instead.
+  if (plan.actions.length === 0) {
+    return "empty_plan";
+  }
+  for (const action of plan.actions) {
+    if (!AUTO_APPLICABLE_ACTION_KINDS.has(action.kind)) {
+      return "disallowed_action_kind";
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry: capture passive corrections
+// ---------------------------------------------------------------------------
+
+export interface PassiveCaptureResult {
+  telemetry: PassiveCaptureTelemetry;
+  /** Plans created (both queued and auto-applied). */
+  plans: CorrectionPlan[];
+}
+
+/**
+ * Process a batch of detected passive corrections. For each correction:
+ *   1. Check dedup fingerprint — skip if already processed for this bufferKey.
+ *   2. Build a CorrectionRequest and call the planner.
+ *   3. Dispatch by mode: queue → plan is left pending; auto → apply if all
+ *      guards pass, else fall back to queue.
+ *   4. Record telemetry.
+ *
+ * Fail-open: a planning or apply error for ONE correction never blocks the
+ * others. The error is logged and the correction is counted as suppressed.
+ */
+export async function capturePassiveCorrections(
+  corrections: readonly PassiveCorrection[],
+  ctx: PassiveCaptureContext,
+  config: PassiveCaptureConfig,
+  deps: PassiveCaptureDeps,
+  dedupState: Set<string>,
+): Promise<PassiveCaptureResult> {
+  const telemetry = emptyTelemetry();
+  const plans: CorrectionPlan[] = [];
+  telemetry.detected = corrections.length;
+
+  for (const correction of corrections) {
+    // 1. Dedup — checked before planning, but the fingerprint is only
+    //    recorded AFTER a successful plan so a transient planning failure
+    //    can be retried on a later flush (review: "dedup blocks retry
+    //    after failure").
+    const fp = correctionFingerprint(ctx.bufferKey, correction);
+    if (dedupState.has(fp)) {
+      continue;
+    }
+
+    // 2. Resolve `[m:xxxx]` handles to concrete memory ids (review:
+    //    "memory handles not resolved"). The planner resolveTargetMemories
+    //    expects memory ids, not raw handle tokens — passing a handle
+    //    string would throw "target memory not found". Unresolvable handles
+    //    are dropped so the planner falls back to text search (graceful
+    //    degradation; a correction without a resolved target is still valid).
+    let targetIds: string[] | undefined;
+    if (correction.handles.length > 0 && deps.resolveHandle && ctx.sessionKey) {
+      const resolved: string[] = [];
+      for (const handle of correction.handles) {
+        const id = deps.resolveHandle(handle, ctx.sessionKey);
+        if (id) resolved.push(id);
+      }
+      if (resolved.length > 0) targetIds = resolved;
+    }
+
+    // 3. Build + plan
+    const request: CorrectionRequest = {
+      text: correction.correctedAssertion || correction.sourceExcerpt,
+      ...(targetIds ? { targetIds } : {}),
+      ...(ctx.sessionKey ? { sessionKey: ctx.sessionKey } : {}),
+      ...(ctx.principal ? { principal: ctx.principal } : {}),
+      namespace: ctx.namespace,
+    };
+
+    let plan: CorrectionPlan;
+    try {
+      plan = await deps.planCorrection(request);
+    } catch (err) {
+      log.warn(
+        `passive-correction: planning failed for "${correction.targetHint.slice(0, 60)}": ${err instanceof Error ? err.message : String(err)}`,
+      );
+      continue;
+    }
+    plans.push(plan);
+    // Record the fingerprint only after a successful plan.
+    dedupState.add(fp);
+
+    // 3. Dispatch by mode
+    if (config.mode === "queue") {
+      telemetry.queued += 1;
+      continue;
+    }
+
+    // mode === "auto"
+    const suppression = evaluateAutoApplyGuards(plan, config, ctx.isLiveSession);
+    if (suppression) {
+      telemetry.suppressedReasons[suppression] =
+        (telemetry.suppressedReasons[suppression] ?? 0) + 1;
+      telemetry.queued += 1;
+      continue;
+    }
+
+    // Guards passed — auto-apply
+    try {
+      const outcome = await deps.applyCorrection(plan.planId, {
+        confirm: true,
+        namespace: ctx.namespace,
+        ...(ctx.sessionKey ? { sessionKey: ctx.sessionKey } : {}),
+        ...(ctx.principal ? { principal: ctx.principal } : {}),
+      });
+      // A partial outcome means some actions failed (per-action races or
+      // storage failures). Don't count it as auto-applied or notify — queue
+      // for human review instead (review: "partial outcomes as failures").
+      if (outcome.status !== "applied") {
+        // Partial outcome: some actions applied, some failed. The plan is
+        // consumed (status 'partial', not 'pending'), so it won't appear in
+        // listPending — do NOT increment queued (review: "partial not
+        // re-queued"). The audit record captures which actions failed.
+        log.warn(
+          `passive-correction: plan ${plan.planId} applied partially — some actions failed (see audit record)`,
+        );
+        continue;
+      }
+      telemetry.autoApplied += 1;
+
+      // Enqueue notification for the next briefing
+      try {
+        const dir = await deps.storageDir(ctx.namespace);
+        await enqueuePassiveCorrectionNotification(dir, {
+          planId: plan.planId,
+          summary: buildNotificationSummary(plan),
+          undoCommand: `auto-applied (plan ${plan.planId})`,
+          createdAt: new Date().toISOString(),
+        });
+      } catch (err) {
+        // Notification is best-effort — never block on it.
+        log.debug(`passive-correction: notification enqueue failed (non-fatal): ${err}`);
+      }
+    } catch (err) {
+      log.warn(
+        `passive-correction: auto-apply failed for plan ${plan.planId}: ${err instanceof Error ? err.message : String(err)} — plan left in queue`,
+      );
+      telemetry.queued += 1;
+    }
+  }
+
+  return { telemetry, plans };
+}
+
+// ---------------------------------------------------------------------------
+// Notification summary builder
+// ---------------------------------------------------------------------------
+
+function buildNotificationSummary(plan: CorrectionPlan): string {
+  const action = plan.actions[0];
+  if (!action) {
+    return plan.request.text.slice(0, 80);
+  }
+  const target =
+    action.kind === "supersede"
+      ? action.loserId
+      : action.kind === "edit" || action.kind === "retract" || action.kind === "rescope"
+        ? action.memoryId
+        : "pattern";
+  return `${plan.classification}: ${plan.request.text.slice(0, 60)}${plan.request.text.length > 60 ? "..." : ""} (${target})`;
+}

package/src/correction/passive-correction-detector.test.ts

@@ -0,0 +1,263 @@
+/**
+ * passive-correction-detector.test.ts — fixture matrix for passive correction
+ * detection (issue #1581 PR 1).
+ *
+ * Positive fixtures (≥12): direct update, retraction, stop-storing, tense/
+ * morphology variants, correction embedded mid-paragraph, handle-referenced.
+ * Anti-fixtures (≥8): quoting someone else's correction; correcting a third
+ * party; hypothetical; self-correction within the same turn that resolves
+ * itself; the agent being corrected about a tool output, not stored memory.
+ */
+
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import {
+  detectPassiveCorrections,
+  extractHandles,
+  type DetectorTurn,
+} from "./passive-correction-detector.js";
+
+function user(content: string): DetectorTurn[] {
+  return [{ role: "user", content }];
+}
+
+test("positive: direct update — actually we use PostgreSQL now", () => {
+  const results = detectPassiveCorrections(user("actually we use PostgreSQL now, not MySQL"));
+  assert.ok(results.length >= 1, `expected >=1 correction, got ${results.length}`);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: direct update — no, we renamed that service", () => {
+  const results = detectPassiveCorrections(user("no, we renamed that service to auth-svc"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: retraction — we don't use Redis anymore", () => {
+  const results = detectPassiveCorrections(user("we don't use Redis anymore"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "retract"));
+});
+
+test("positive: retraction — that's wrong", () => {
+  const results = detectPassiveCorrections(user("that's wrong, I never said that"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "retract"));
+});
+
+test("positive: stop-storing — stop suggesting Vim", () => {
+  const results = detectPassiveCorrections(user("stop suggesting Vim, I switched to Helix months ago"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "stop_storing"));
+});
+
+test("positive: stop-storing — don't bring up that project", () => {
+  const results = detectPassiveCorrections(user("don't bring up that project anymore"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "stop_storing"));
+});
+
+test("positive: tense variant — we switched to (past)", () => {
+  const results = detectPassiveCorrections(user("we switched to GitHub Actions for CI"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: tense variant — we're switching to (progressive)", () => {
+  const results = detectPassiveCorrections(user("we're switching to pnpm from npm"));
+  assert.ok(results.length >= 1, `expected >=1, got ${results.length}`);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: tense variant — we've migrated to (present perfect)", () => {
+  const results = detectPassiveCorrections(user("we've migrated to PostgreSQL"));
+  assert.ok(results.length >= 1, `expected >=1, got ${results.length}`);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: no longer phrasing", () => {
+  const results = detectPassiveCorrections(user("I no longer work on that project"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: that's outdated phrasing", () => {
+  const results = detectPassiveCorrections(user("that's outdated, the API changed last week"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: correction embedded mid-paragraph", () => {
+  const results = detectPassiveCorrections(
+    user("I was reviewing the architecture and noticed the docs say we use AWS. Actually, we moved to GCP last quarter, so those docs need updating."),
+  );
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: deadline moved to Friday", () => {
+  const results = detectPassiveCorrections(user("the deadline moved to Friday"));
+  assert.ok(results.length >= 1);
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("positive: handle-referenced [m:4f2a] is wrong", () => {
+  const results = detectPassiveCorrections(user("that's wrong, [m:4f2a] is incorrect — the real value is 42"));
+  assert.ok(results.length >= 1);
+  assert.ok(results[0].handles.includes("[m:4f2a]"));
+});
+
+test("positive: multiple handles extracted", () => {
+  const results = detectPassiveCorrections(
+    user("actually, [m:4f2a] and [m:8b1c] are both outdated"),
+  );
+  assert.ok(results.length >= 1, `expected >=1, got ${results.length}`);
+  assert.ok(results[0].handles.includes("[m:4f2a]"));
+  assert.ok(results[0].handles.includes("[m:8b1c]"));
+});
+
+// ── Anti-fixtures ──────────────────────────────────────────────────────────
+
+test("anti-fixture: quoting someone else's correction", () => {
+  const results = detectPassiveCorrections(
+    user('Bob told me "that\'s wrong" about the deployment process'),
+  );
+  const retracts = results.filter((r) => r.polarity === "retract");
+  assert.strictEqual(retracts.length, 0, `expected 0 retract corrections, got ${retracts.length}`);
+});
+
+test("anti-fixture: correcting a third party", () => {
+  const results = detectPassiveCorrections(
+    user("tell Bob he's wrong about the API design"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: hypothetical — if we ever moved to MySQL", () => {
+  const results = detectPassiveCorrections(
+    user("if we ever moved to MySQL, we'd need to rewrite the migrations"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: hypothetical — what if we switch", () => {
+  const results = detectPassiveCorrections(
+    user("what if we switch to a different framework?"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: self-resolving — actually wait, the original was right", () => {
+  const results = detectPassiveCorrections(
+    user("actually, wait, never mind, the original was right"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: self-resolving — scratch that", () => {
+  const results = detectPassiveCorrections(
+    user("actually we moved to... no, scratch that, we're still on the old system"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: tool output correction", () => {
+  const results = detectPassiveCorrections(
+    user("the output is wrong, the test results don't match"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: agent corrected about code, not stored memory", () => {
+  const results = detectPassiveCorrections(
+    user("your code has a bug in the error handler"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("anti-fixture: suppose / hypothetical scenario", () => {
+  const results = detectPassiveCorrections(
+    user("suppose we changed the database — what would break?"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+// ── Characterization ───────────────────────────────────────────────────────
+
+test("characterization: assistant turns are not scanned", () => {
+  const results = detectPassiveCorrections([
+    { role: "assistant", content: "actually, we moved to PostgreSQL" },
+  ]);
+  assert.strictEqual(results.length, 0);
+});
+
+test("characterization: empty content produces no corrections", () => {
+  const results = detectPassiveCorrections([{ role: "user", content: "" }]);
+  assert.strictEqual(results.length, 0);
+});
+
+test("characterization: non-corrective user text produces no corrections", () => {
+  const results = detectPassiveCorrections(
+    user("Can you help me write a function to parse JSON?"),
+  );
+  assert.strictEqual(results.length, 0);
+});
+
+test("characterization: confidence is in [0, 1]", () => {
+  const results = detectPassiveCorrections(user("we switched to Go"));
+  for (const r of results) {
+    assert.ok(r.confidence >= 0 && r.confidence <= 1);
+  }
+});
+
+test("characterization: sourceExcerpt is populated", () => {
+  const results = detectPassiveCorrections(user("we switched to Go"));
+  for (const r of results) {
+    assert.ok(r.sourceExcerpt.length > 0);
+  }
+});
+
+// ── extractHandles ─────────────────────────────────────────────────────────
+
+test("extractHandles: extracts [m:xxxx] handles", () => {
+  assert.deepStrictEqual(extractHandles("see [m:4f2a] and [m:8b1c]"), ["[m:4f2a]", "[m:8b1c]"]);
+});
+
+test("extractHandles: returns empty for no handles", () => {
+  assert.deepStrictEqual(extractHandles("no handles here"), []);
+});
+
+test("contraction does not suppress a correction phrase (review: apostrophe quote detection)", () => {
+  // OLD isWithinQuotes treated the ASCII apostrophe as a quote opener. A single
+  // contraction with no closing apostrophe ("We've switched to Postgres") left
+  // the scanner in quoted mode and suppressed the correction — a false negative.
+  // Only double quotes delimit quoted speech; apostrophes are contractions.
+  const results = detectPassiveCorrections(user("We've switched to Postgres"));
+  assert.ok(results.length > 0, "contraction-led correction must be detected");
+  assert.ok(results.some((r) => r.polarity === "update"));
+});
+
+test("double-quoted correction is still suppressed (isWithinQuotes uses double quotes only)", () => {
+  // After dropping single-quote handling, real double-quoted speech must STILL
+  // be suppressed — only the delimiter set changed, not the suppression itself.
+  const results = detectPassiveCorrections(
+    user('Bob told me "that\'s wrong" about the deployment process'),
+  );
+  const retracts = results.filter((r) => r.polarity === "retract");
+  assert.strictEqual(retracts.length, 0, "double-quoted speech must still be suppressed");
+});
+
+test("overlapping cues dedup: 'actually, we don't use Redis anymore' emits one correction (review)", () => {
+  // Both the "actually" (update) and "don't use X anymore" (retract) patterns
+  // match the same targetHint. Polarity-agnostic dedup keeps one correction.
+  const results = detectPassiveCorrections(
+    user("actually, we don't use Redis anymore for caching"),
+  );
+  const redisCorrections = results.filter((r) =>
+    r.targetHint.toLowerCase().includes("redis"),
+  );
+  assert.ok(
+    redisCorrections.length <= 1,
+    `overlapping cues for same target must emit at most one correction, got ${redisCorrections.length}`,
+  );
+});