@remnic/core 9.65.1 → 9.65.3

package/src/contradiction/contradiction-review.ts

@@ -17,9 +17,31 @@ import type { ContradictionVerdict } from "./contradiction-judge.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
-export type ResolutionVerb = "keep-a" | "keep-b" | "merge" | "both-valid" | "needs-more-context";
-
-const VALID_RESOLUTION_VERBS: readonly ResolutionVerb[] = [
+/**
+ * Resolution verbs. The first five are contradiction-pair verbs; the last
+ * three resolve a `kind: "preference-drift"` item (issue #2371). Verb validity
+ * is per-kind — `executeResolution` rejects a cross-kind verb — but the stored
+ * union is shared so one review queue, one `review_resolve` surface, and one
+ * resolution record serve both item kinds.
+ */
+export type ResolutionVerb =
+  | "keep-a"
+  | "keep-b"
+  | "merge"
+  | "both-valid"
+  | "needs-more-context"
+  | "keep"
+  | "supersede"
+  | "archive";
+
+/** Review-item kind. Absent on every pair written before issue #2371. */
+export type ReviewItemKind = "contradiction" | "preference-drift";
+
+/** Verbs valid for a `kind: "preference-drift"` item. */
+export const PREFERENCE_DRIFT_VERBS: readonly ResolutionVerb[] = ["keep", "supersede", "archive"];
+
+/** Verbs valid for a contradiction pair. */
+export const CONTRADICTION_VERBS: readonly ResolutionVerb[] = [
   "keep-a",
   "keep-b",
   "merge",
@@ -27,11 +49,23 @@ const VALID_RESOLUTION_VERBS: readonly ResolutionVerb[] = [
   "needs-more-context",
 ];
 
+const VALID_RESOLUTION_VERBS: readonly ResolutionVerb[] = [
+  ...CONTRADICTION_VERBS,
+  ...PREFERENCE_DRIFT_VERBS,
+];
+
 export interface ContradictionPair {
   /** Deterministic pair ID: sha256(sorted(memoryIdA, memoryIdB) plus namespace when scoped). */
   pairId: string;
   /** Memory IDs (sorted). */
   memoryIds: [string, string];
+  /**
+   * Item kind (issue #2371). Absent on every pair written before drift
+   * detection existed, which reads as `"contradiction"`. A
+   * `"preference-drift"` item pairs the aging preference (first id) with the
+   * recent evidence that pointed away from it (second id).
+   */
+  kind?: ReviewItemKind;
   /** Judge verdict. */
   verdict: ContradictionVerdict;
   /** Judge rationale. */
@@ -85,8 +119,20 @@ export function isDefaultReviewNamespace(
   return !requested || requested === defaultNamespace || resolvedNamespace === defaultNamespace;
 }
 
+const TERMINAL_RESOLUTIONS: Partial<Record<ResolutionVerb, true>> = {
+  "keep-a": true,
+  "keep-b": true,
+  merge: true,
+  // Every preference-drift verb is terminal: the user has answered the "is
+  // this preference still true?" question, so the item must leave the
+  // unresolved queue and never be re-proposed by a later scan (issue #2371).
+  keep: true,
+  supersede: true,
+  archive: true,
+};
+
 function isTerminalResolution(resolution: ResolutionVerb | undefined): boolean {
-  return resolution === "keep-a" || resolution === "keep-b" || resolution === "merge";
+  return resolution !== undefined && TERMINAL_RESOLUTIONS[resolution] === true;
 }
 
 function preservesDirectResolution(resolution: ResolutionVerb | undefined): boolean {

package/src/contradiction/contradiction-scan.ts

@@ -380,8 +380,16 @@ function normalizeScanNamespace(namespace: string | undefined): string | undefin
   return trimmed ? trimmed : undefined;
 }
 
-async function resolveScanStorage(
-  deps: ScanDependencies,
+/**
+ * Resolve the namespace-scoped storage a scan must read and write through.
+ *
+ * Exported and narrowed to the fields it actually reads so sibling scans
+ * (preference drift, issue #2371) share ONE namespace resolver rather than
+ * re-deriving the read/write namespace independently — the divergence the
+ * namespace/ACL scenario matrix in AGENTS.md exists to prevent.
+ */
+export async function resolveScanStorage(
+  deps: Pick<ScanDependencies, "config" | "storage" | "storageForNamespace">,
   namespace: string | undefined,
 ): Promise<ScanStorageResolution> {
   if (!resolveNamespaceCapabilities(deps.config).namespaces) {
@@ -427,7 +435,10 @@ function isStorageManagerLike(value: unknown): value is StorageManager {
   return typeof candidate.readAllMemories === "function";
 }
 
-function fallbackResolvedNamespace(deps: ScanDependencies, namespace: string | undefined): string | undefined {
+function fallbackResolvedNamespace(
+  deps: Pick<ScanDependencies, "config">,
+  namespace: string | undefined,
+): string | undefined {
   if (namespace) return namespace;
   return resolveNamespaceCapabilities(deps.config).namespaces ? deps.config.defaultNamespace : undefined;
 }

package/src/contradiction/resolution.ts

@@ -10,7 +10,13 @@ import { composeMemoryEnvelope } from "../write-envelope.js";
 import type { StorageManager } from "../storage.js";
 import type { MemoryCategory, MemoryFile } from "../types.js";
 import type { ResolutionVerb } from "./contradiction-review.js";
-import { readPair, resolvePair } from "./contradiction-review.js";
+import {
+  CONTRADICTION_VERBS,
+  PREFERENCE_DRIFT_VERBS,
+  readPair,
+  resolvePair,
+} from "./contradiction-review.js";
+import { resolvePreferenceDrift } from "../preferences/preference-drift.js";
 
 export interface ResolutionResult {
   pairId: string;
@@ -50,7 +56,14 @@ export interface ExecuteResolutionOptions {
   onMergedMemoryWritten?: (namespace: string | undefined, storageDir: string) => void;
 }
 
-const VALID_VERBS: ResolutionVerb[] = ["keep-a", "keep-b", "merge", "both-valid", "needs-more-context"];
+/**
+ * Every verb the `review_resolve` surface accepts, across both review-item
+ * kinds (issue #2371). This is a *surface-level* gate only: per-kind validity
+ * is enforced inside {@link executeResolution}, which is the first place the
+ * item's `kind` is known. Callers therefore reject an unknown verb early and
+ * a cross-kind verb precisely.
+ */
+const VALID_VERBS: readonly ResolutionVerb[] = [...CONTRADICTION_VERBS, ...PREFERENCE_DRIFT_VERBS];
 
 export function isValidResolutionVerb(value: string): value is ResolutionVerb {
   return VALID_VERBS.includes(value as ResolutionVerb);
@@ -94,6 +107,41 @@ export async function executeResolution(
   if (pair.resolution && pair.resolution !== "needs-more-context") {
     return { pairId, verb, affectedIds: [], message: `Pair already resolved with verb "${pair.resolution}"` };
   }
+  // Verb validity is per review-item kind (issue #2371). A preference-drift
+  // item never accepts keep-a/keep-b/merge (there is no "B" to keep — the
+  // second id is witness evidence, not a competing claim), and a contradiction
+  // pair never accepts keep/supersede/archive. Rejecting the cross-kind verb
+  // here, after the record is loaded, is the only place both kinds are known.
+  const isDriftItem = pair.kind === "preference-drift";
+  const verbMatchesKind = isDriftItem
+    ? PREFERENCE_DRIFT_VERBS.includes(verb)
+    : CONTRADICTION_VERBS.includes(verb);
+  if (!verbMatchesKind) {
+    const allowed = (isDriftItem ? PREFERENCE_DRIFT_VERBS : CONTRADICTION_VERBS).join(", ");
+    return {
+      pairId,
+      verb,
+      affectedIds: [],
+      message: `Verb "${verb}" is not valid for a ${isDriftItem ? "preference-drift" : "contradiction"} item. Valid: ${allowed}`,
+    };
+  }
+
+  if (isDriftItem) {
+    const outcome = await resolvePreferenceDrift(
+      resolutionStorage,
+      pair,
+      verb as "keep" | "supersede" | "archive",
+      {
+        mergedContent: options.mergedContent,
+        onMemoryWritten: options.onMergedMemoryWritten,
+      },
+    );
+    // Only record the terminal resolution when memories actually changed;
+    // a refused resolution must stay actionable in the queue.
+    if (outcome.affectedIds.length > 0) resolvePair(memoryDir, pairId, verb);
+    return { pairId, verb, affectedIds: outcome.affectedIds, message: outcome.message };
+  }
+
 
   const [idA, idB] = pair.memoryIds;
   const affectedIds: string[] = [];

package/src/extraction-prompt.ts

@@ -22,6 +22,7 @@ export const EXTRACTION_RESPONSE_SHAPE = `{
     "promptedByQuestion": "<optional source-grounded question>",
     "quote": "<optional exact contiguous source span>",
     "scope": "<optional project-or-global>",
+    "subject": "<optional user-or-agent>",
     "structuredAttributes": {"<key>": "<value>"},
     "procedureSteps": [{"order": 1, "intent": "<step>"}, {"order": 2, "intent": "<step>"}],
     "reasoningTrace": {

package/src/extraction.ts

@@ -312,6 +312,8 @@ export class ExtractionEngine {
               promptedByQuestion: extractionText(f.promptedByQuestion),
               scope:
                 f.scope === "global" || f.scope === "project" ? f.scope : undefined,
+              subject:
+                f.subject === "user" || f.subject === "agent" ? f.subject : undefined,
               structuredAttributes: extractionAttributes(f.structuredAttributes),
               procedureSteps,
               reasoningTrace,
@@ -1425,7 +1427,8 @@ Rules:
 - ${OUTPUT_LANGUAGE_POLICY}
 ${CUE_ANCHOR_PROMPT_INSTRUCTION}\n- Include at most five durable relationships.${this.config.provenance?.enabled ? `
 - Each fact must include a quote copied verbatim from one contiguous conversation span.` : ""}${lifecycleCaps.extractionScopeClassification ? `
-- Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}
+- Set each fact scope to "global" for cross-project knowledge or "project" for codebase-specific knowledge. Tool, command, or CLI-flag instructions tied to one agent are "project" (the same tool name can mean different things across agents); when keeping one, begin the fact with a leading "In <agent>," clause naming that agent.` : ""}${this.config.subjectClassification?.enabled === true ? `
+- Set each fact subject to "user" when it models the person (preferences, relationships, biography, moments, commitments about their life) or "agent" when it is reusable operating knowledge (procedures, principles, tool-usage lessons, debugging strategies, environment facts with no personal content).` : ""}${ambientCapture ? AMBIENT_CAPTURE_PROMPT_SECTION_COMPACT : ""}
 ${eventTimePromptInstruction(this.config)}
 Return only valid JSON matching this shape. Placeholder text describes field shape only and is never source evidence:
 ${EXTRACTION_RESPONSE_SHAPE}

package/src/index.ts

@@ -229,7 +229,8 @@ export type {
   ProcedureStatsConfigSnapshot,
   ProcedureStatsRecent,
 } from "./procedural/procedure-stats.js";
-
+export { runProcedureLibraryMaintenance, type ProcedureLibraryMaintenanceReport, type ProcedureMaintenanceAction, type ProcedureMaintenanceActionKind, type ProcedureMaintenanceReasonCode, type ProcedureMaintenanceEvidence, type ProcedureMaintenanceMarker } from "./procedural/library-maintenance.js";
+export * from "./preferences/index.js";
 // ---------------------------------------------------------------------------
 // Direct-answer retrieval tier (issue #518)
 // ---------------------------------------------------------------------------
@@ -493,14 +494,13 @@ export {
   type RecallXrayFormat,
 } from "./recall-xray-renderer.js";
 export type {
-  RecallXraySnapshot,
-  RecallXrayResult,
-  RecallXrayScoreDecomposition,
-  RecallXrayServedBy,
-  RecallFilterTrace,
+  RecallXraySnapshot, RecallXrayResult, RecallXrayScoreDecomposition, RecallXrayServedBy, RecallFilterTrace,
 } from "./recall-xray.js";
 export * from "./who-knows.js";
 export * from "./who-knows-cli.js";
+export * from "./memory-subject.js";
+export * from "./memory-subject-cli.js";
+export * from "./subject-config.js";
 
 // ChatGPT Apps-compatible memory inspector demo.
 export {
@@ -516,6 +516,7 @@ export {
   type RemnicChatGptMemoryInspectorResult,
 } from "./mcp-memory-inspector-app.js";
 export * from "./coding/pre-action-gate.js";
+export * from "./coding/action-gate.js";
 export * from "./causal-trajectory.js";
 // Coding-agent subsystem (issue #569)
 export {
@@ -806,10 +807,7 @@ export {
   type SemanticDedupDecision,
 } from "./dedup/semantic.js";
 
-// ---------------------------------------------------------------------------
 // Review Inbox
-// ---------------------------------------------------------------------------
-
 export {
   listReviewItems,
   performReview,
@@ -819,6 +817,8 @@ export {
   type ReviewListResult,
   type ReviewOptions,
 } from "./review/index.js";
+export * from "./review/review-deck.js";
+export * from "./review/review-deck-snapshot.js";
 
 // ---------------------------------------------------------------------------
 // Diff-Aware Sync

package/src/mcp-read-only-tools.ts

@@ -17,6 +17,7 @@ export const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
   recall_tier_explain: true,
   recall_xray: true,
   who_knows: true,
+  promotion_candidates: true,
   briefing: true,
   wearables_status: true,
   transcript_day: true,

package/src/memory-subject-cli.ts

@@ -0,0 +1,135 @@
+/**
+ * CLI surface for memory-subject operations (issue #2372).
+ *
+ * `remnic promotion-candidates` — read-only surfacing of agent-subject,
+ * reuse-signaled promotion candidates. `remnic subjects backfill` — the
+ * deterministic shadow/apply stamp for unstamped memories. Runners take an
+ * io seam (service/storage callbacks + stdout) so tests drive them without
+ * booting an orchestrator; the remnic-cli entry supplies the real ones.
+ */
+
+import type {
+  PromotionCandidatesResult,
+  SubjectBackfillReport,
+} from "./memory-subject.js";
+
+export interface PromotionCandidatesCliOptions {
+  namespace?: string;
+  targetNamespace?: string;
+  limit: number;
+  json: boolean;
+}
+
+export function parsePromotionCandidatesCliOptions(args: {
+  namespace?: string;
+  targetNamespace?: string;
+  limit?: string;
+  json?: boolean;
+}): PromotionCandidatesCliOptions {
+  let limit = 20;
+  if (args.limit !== undefined) {
+    const parsed = Number(args.limit);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 100) {
+      throw new Error(
+        `promotion-candidates: --limit expects an integer in [1, 100] (got ${JSON.stringify(args.limit)})`,
+      );
+    }
+    limit = parsed;
+  }
+  return {
+    ...(args.namespace !== undefined && args.namespace !== "" ? { namespace: args.namespace } : {}),
+    ...(args.targetNamespace !== undefined && args.targetNamespace !== ""
+      ? { targetNamespace: args.targetNamespace }
+      : {}),
+    limit,
+    json: args.json === true,
+  };
+}
+
+export function renderPromotionCandidates(result: PromotionCandidatesResult, json: boolean): string {
+  if (json) return JSON.stringify(result, null, 2);
+  const lines = [
+    `Namespace: ${result.namespace}  Target layer: ${result.targetNamespace}  (minAccessCount ${result.minAccessCount})`,
+  ];
+  if (result.candidates.length === 0) {
+    lines.push("No promotion candidates.");
+    return lines.join("\n");
+  }
+  for (const c of result.candidates) {
+    lines.push(
+      `- ${c.id} [${c.category}] signal=${c.reuseSignal} access=${c.accessCount} reinforced=${c.reinforcementCount} mw=${c.mwSuccess}/${c.mwFail}`,
+    );
+    lines.push(`  ${c.content.replace(/\s+/g, " ").slice(0, 100)}`);
+  }
+  lines.push("Promote explicitly with the existing promotion commands; nothing is auto-promoted.");
+  return lines.join("\n");
+}
+
+export async function runPromotionCandidatesCommand(
+  rest: string[],
+  io: {
+    promotionCandidates: (request: {
+      namespace?: string;
+      targetNamespace?: string;
+      limit?: number;
+    }) => Promise<PromotionCandidatesResult>;
+    stdout: (line: string) => void;
+  },
+): Promise<void> {
+  const flag = (name: string): string | undefined => {
+    const hit = rest.find((a) => a.startsWith(`--${name}=`));
+    return hit === undefined ? undefined : hit.slice(name.length + 3);
+  };
+  const options = parsePromotionCandidatesCliOptions({
+    namespace: flag("namespace"),
+    targetNamespace: flag("target-namespace"),
+    limit: flag("limit"),
+    json: rest.includes("--json"),
+  });
+  const result = await io.promotionCandidates({
+    ...(options.namespace !== undefined ? { namespace: options.namespace } : {}),
+    ...(options.targetNamespace !== undefined ? { targetNamespace: options.targetNamespace } : {}),
+    limit: options.limit,
+  });
+  io.stdout(renderPromotionCandidates(result, options.json));
+}
+
+export interface SubjectsBackfillCliOptions {
+  mode: "shadow" | "apply";
+  namespace?: string;
+}
+
+export function parseSubjectsBackfillCliOptions(args: {
+  apply?: boolean;
+  namespace?: string;
+}): SubjectsBackfillCliOptions {
+  return {
+    mode: args.apply === true ? "apply" : "shadow",
+    ...(args.namespace !== undefined && args.namespace !== "" ? { namespace: args.namespace } : {}),
+  };
+}
+
+export async function runSubjectsBackfillCommand(
+  rest: string[],
+  io: {
+    backfill: (options: { mode: "shadow" | "apply"; namespace?: string }) => Promise<SubjectBackfillReport>;
+    stdout: (line: string) => void;
+  },
+): Promise<void> {
+  const namespaceFlag = rest.find((a) => a.startsWith("--namespace="))?.slice("--namespace=".length);
+  const options = parseSubjectsBackfillCliOptions({
+    apply: rest.includes("--apply"),
+    namespace: namespaceFlag,
+  });
+  const report = await io.backfill(options);
+  const lines = [
+    `Mode: ${report.mode}  Scanned: ${report.scanned}  Already stamped: ${report.alreadyStamped}  To stamp: ${report.stamped}`,
+  ];
+  for (const stamp of report.stamps) {
+    lines.push(`- ${stamp.id} [${stamp.category}] → subject: ${stamp.subject}`);
+  }
+  if (report.mode === "shadow") {
+    lines.push("Shadow run — nothing written. Re-run with --apply to stamp.");
+  }
+  io.stdout(lines.join("\n"));
+}

package/src/memory-subject.test.ts

@@ -0,0 +1,48 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  evaluateSubjectGuard,
+  resolveWriteSubject,
+  SUBJECT_GUARD_OVERRIDE_FLAG,
+} from "./memory-subject.js";
+import { parseSubjectRuntimeConfig } from "./subject-config.js";
+
+test("category defaults: procedure is agent, preference is user, unknown is user", () => {
+  assert.equal(resolveWriteSubject("procedure", undefined), "agent");
+  assert.equal(resolveWriteSubject("preference", undefined), "user");
+  assert.equal(resolveWriteSubject("fact", undefined), "user");
+  assert.equal(resolveWriteSubject("procedure", "user"), "user");
+});
+
+test("shared-layer guard: missing subject fails closed as user", () => {
+  const warn = evaluateSubjectGuard({
+    subject: undefined,
+    sharedTarget: true,
+    mode: "warn",
+  });
+  assert.equal(warn.action, "warn");
+  assert.equal(warn.effectiveSubject, "user");
+  assert.ok(warn.reason.includes(SUBJECT_GUARD_OVERRIDE_FLAG));
+
+  const reject = evaluateSubjectGuard({
+    subject: "user",
+    sharedTarget: true,
+    mode: "enforce",
+  });
+  assert.equal(reject.action, "reject");
+
+  const allowed = evaluateSubjectGuard({
+    subject: "agent",
+    sharedTarget: true,
+    mode: "enforce",
+  });
+  assert.equal(allowed.action, "allow");
+});
+
+test("subjectClassification omitted is off; invalid values throw", () => {
+  assert.equal(parseSubjectRuntimeConfig({}).subjectClassification.enabled, false);
+  assert.equal(parseSubjectRuntimeConfig({}).subjectGuard, "warn");
+  assert.throws(() => parseSubjectRuntimeConfig({ subjectGuard: "loud" }));
+  assert.throws(() => parseSubjectRuntimeConfig({ subjectClassification: false }));
+});