@remnic/core 9.65.1 → 9.65.2

package/src/access-service.ts

@@ -201,6 +201,10 @@ import type {
   RecallInvocationOptions,
 } from "./orchestrator.js";
 import { type ProcedureStatsReport, computeProcedureStats } from "./procedural/procedure-stats.js";
+import {
+  runProcedureLibraryMaintenance,
+  type ProcedureLibraryMaintenanceReport,
+} from "./procedural/library-maintenance.js";
 import type { RecallContextComposition } from "./recall-context-composition.js";
 import type { LastRecallSnapshot } from "./recall-state.js";
 import {
@@ -305,6 +309,7 @@ import { toRecallExplainJson } from "./recall-explain-renderer.js";
 import { type TagMatchMode, applyTagFilter, normalizeTags, parseTagMatch } from "./recall-tag-filter.js";
 import { type RecallXraySnapshot, estimateRecallTokens } from "./recall-xray.js";
 import { computeWhoKnows, loadWhoKnowsEntities, validateWhoKnowsInput, WHO_KNOWS_DEFAULT_LIMIT, type WhoKnowsResult } from "./who-knows.js";
+import { computePromotionCandidates, type PromotionCandidatesResult } from "./memory-subject.js";
 import { SupportPassportAccessServiceBase } from "./support-passport/access-service-base.js";
 import {
   type ExportCapsuleOptions,
@@ -2738,6 +2743,41 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     ]);
     return computeWhoKnows({ topic, limit, memories, entities });
   }
+  /**
+   * Read-only promotion-candidate surfacing (issue #2372): agent-subject,
+   * active, reuse-signaled memories in the caller's namespace with no
+   * equivalent in the target layer. No auto-promotion — callers use the
+   * existing promotion commands.
+   */
+  async promotionCandidates(request: {
+    namespace?: string;
+    targetNamespace?: string;
+    limit?: number;
+    authenticatedPrincipal?: string;
+  }): Promise<PromotionCandidatesResult> {
+    const limit = request.limit ?? 20;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+      throw new EngramAccessInputError(
+        `promotion_candidates: limit expects an integer in [1, 100] (got ${String(request.limit)})`,
+      );
+    }
+    const resolvedNamespace = this.resolveReadableNamespace(request.namespace, request.authenticatedPrincipal);
+    const resolvedTarget = this.resolveReadableNamespace(
+      request.targetNamespace ?? this.orchestrator.config.sharedNamespace,
+      request.authenticatedPrincipal,
+    );
+    const minAccessCount = this.orchestrator.config.promotionCandidates.minAccessCount;
+    const [memories, targetMemories] = await Promise.all([
+      (await this.orchestrator.getStorage(resolvedNamespace)).readAllMemories(),
+      (await this.orchestrator.getStorage(resolvedTarget)).readAllMemories(),
+    ]);
+    return {
+      namespace: resolvedNamespace,
+      targetNamespace: resolvedTarget,
+      minAccessCount,
+      candidates: computePromotionCandidates({ memories, targetMemories, minAccessCount, limit }),
+    };
+  }
   async memoryStore(
     request: EngramAccessMemoryStoreRequest,
     hooks?: { enforceWriteQuota?: () => void | Promise<void> }
@@ -3580,6 +3620,51 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     return { namespace: resolvedNamespace, ...report };
   }
 
+  /**
+   * Procedure library health maintenance (issue #2370). Shadow-first: the
+   * gate is checked BEFORE any storage read, so `maintenance.enabled=false`
+   * returns `{ enabled: false }` having touched nothing but config. Apply
+   * mode additionally requires `apply: true`; `dryRun: true` forces shadow.
+   *
+   * The authenticated principal (never a client-supplied actor) drives the
+   * namespace via the same writable resolver `procedureMiningRun` uses, so
+   * cross-tenant writes are impossible.
+   */
+  async procedureLibraryMaintenance(
+    request: {
+      namespace?: string;
+      apply?: boolean;
+      dryRun?: boolean;
+      authenticatedPrincipal?: string;
+    },
+    principal?: string
+  ): Promise<
+    | { enabled: false }
+    | {
+        enabled: true;
+        namespace: string;
+        report: ProcedureLibraryMaintenanceReport;
+      }
+  > {
+    const procedural = this.orchestrator.config.procedural;
+    if (procedural?.enabled !== true || procedural.maintenance?.enabled !== true) {
+      return { enabled: false };
+    }
+    const resolvedNamespace = this.writableNamespaceFor(
+      request.namespace,
+      undefined,
+      request.authenticatedPrincipal ?? principal
+    );
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const report = await runProcedureLibraryMaintenance({
+      memoryDir: storage.dir,
+      storage,
+      config: this.orchestrator.config,
+      apply: request.apply === true && request.dryRun !== true,
+    });
+    return { enabled: true, namespace: resolvedNamespace, report };
+  }
+
   async memorySummarizeHourly(): Promise<{
     ok: true;
     message: string;

package/src/access-surface-catalog.ts

@@ -57,6 +57,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "recall_tier_explain", operation: "recall_tier_explain" },
   { tool: "recall_xray", operation: "recall_xray" },
   { tool: "who_knows", operation: "who_knows" },
+  { tool: "promotion_candidates", operation: "promotion_candidates" },
   { tool: "wearables_status", operation: "wearables_status" },
   { tool: "wearables_sync", operation: "wearables_sync" },
   { tool: "transcript_day", operation: "transcript_day" },
@@ -76,6 +77,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "procedure_mining_run", operation: "procedure_mining_run" },
   { tool: "pattern_reinforcement_run", operation: "pattern_reinforcement_run" },
   { tool: "procedural_stats", operation: "procedural_stats" },
+  { tool: "procedure_library_maintenance", operation: "procedure_library_maintenance" },
   { tool: "memory_get", operation: "memory_get" },
   { tool: "memory_timeline", operation: "memory_timeline" },
   { tool: "memory_store", operation: "memory_store" },

package/src/config.ts

@@ -37,10 +37,12 @@ import { expandTildePath } from "./utils/path.js";
 // lives in connectors/coerce.ts (a tiny, dependency-free module) so neither
 // config.ts → connectors/index.ts nor the reverse circular import arises.
 import { coerceBool, coerceBooleanLike, coerceInstallExtension, coerceNumber } from "./connectors/coerce.js";
+import { parseSubjectRuntimeConfig } from "./subject-config.js";
 import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
 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 {
   parseContradictionLocalizationConfig,
   parseContradictionScanConfig,
@@ -1123,16 +1125,9 @@ export function parseConfig(
     recallMaxCoerced !== undefined && Number.isFinite(recallMaxCoerced)
       ? Math.min(10, Math.max(1, Math.floor(recallMaxCoerced)))
       : 2;
-  // Default-on procedural memory (issue #567 PR 4/5): if the user has NOT
-  // explicitly set `procedural.enabled`, enable it. Explicit `false` (or any
-  // value coerceBool reads as false: `"0"`, `"no"`, `"off"`, `false`) keeps
-  // the feature off. CLAUDE.md rules:
-  //   - #30 — escape hatch remains for operators who want to stay opt-out.
-  //   - #36 — "false"-ish strings coerce to false via coerceBool.
-  //   - #51 — when the key IS present but the value can't be understood
-  //     (typo like `"fales"` or a number like `0`), reject loudly instead
-  //     of silently flipping the default. Silent fallback on bad input is
-  //     how procedural memory would end up "fail-open" for typos.
+  const maintenance = parseProceduralMaintenanceConfig(rawProcedural.maintenance);
+  // Default-on procedural memory (issue #567 PR 4/5). Explicit false-ish
+  // values stay off. Unknown values throw.
   const rawEnabledValue = rawProcedural.enabled;
   let proceduralEnabled: boolean;
   if (rawEnabledValue === undefined) {
@@ -1147,6 +1142,7 @@ export function parseConfig(
     proceduralEnabled = enabledCoerced;
   }
   const procedural: ProceduralConfig = {
+    maintenance,
     enabled: proceduralEnabled,
     /** `0` skips all mining (`minOccurrences_zero`); otherwise clusters need at least this many members. */
     minOccurrences: Math.min(1000, Math.max(0, proceduralMinRaw)),
@@ -2755,11 +2751,11 @@ export function parseConfig(
       }
       return "low";
     })(),
-    // Extraction scope classification. When enabled, the extraction prompt
-    // asks the LLM to classify each fact as "project" or "global". Global
-    // facts are promoted to the shared namespace. Default true (rule 30 gate).
+    // Extraction scope classification (rule 30 gate): "global" facts promote
+    // to the shared namespace. Default true.
     extractionScopeClassificationEnabled:
       coerceBool(cfg.extractionScopeClassificationEnabled) !== false,
+    ...parseSubjectRuntimeConfig(cfg),
     // Extraction judge (issue #376). Opt-in LLM-as-judge fact-worthiness gate.
     extractionJudgeEnabled: cfg.extractionJudgeEnabled === true,
     extractionJudgeModel:
@@ -2778,10 +2774,7 @@ export function parseConfig(
         ? Math.floor(cfg.extractionJudgeMaxDeferrals)
         : 2,
     // Judge telemetry (issue #562 PR 3): opt-in structured emit to the
-    // observation ledger for defer-rate / latency metrics.
-    // Uses `coerceBool` so CLI-style string inputs (`"true"`, `"false"`,
-    // `"1"`, `"0"`) are accepted consistently with the rest of the
-    // codebase (CLAUDE.md gotcha 36).
+    // observation ledger; `coerceBool` accepts CLI-style strings (gotcha 36).
     extractionJudgeTelemetryEnabled:
       coerceBool(cfg.extractionJudgeTelemetryEnabled) === true,
     // Judge training-pair collection (issue #562 PR 4): opt-in shim for a

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,7 @@ 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";
 // ---------------------------------------------------------------------------
 // Direct-answer retrieval tier (issue #518)
 // ---------------------------------------------------------------------------
@@ -493,14 +493,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 {

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 }));
+});