@remnic/core 9.65.0 → 9.65.2

package/src/memory-subject.ts

@@ -0,0 +1,314 @@
+/**
+ * Memory subject: user-centric vs agent-centric classification (issue #2372).
+ *
+ * Scope says WHERE a memory lives; subject says WHOM it is about — and that
+ * is what determines where it may safely go. `user` memories model one
+ * person (preferences, relationships, biography, moments, commitments);
+ * `agent` memories model how to operate (procedures, principles,
+ * tool-usage lessons, debugging strategies, environment facts with no
+ * personal content).
+ *
+ * This module owns, in one place:
+ *  - the deterministic write-time classification (category defaults with an
+ *    optional extractor override),
+ *  - the promotion guard shared by EVERY promotion surface (spaces promote
+ *    AND scope-profile promotion targets — AGENTS.md §27 uniform gating),
+ *  - read-only promotion-candidate surfacing (reuse-signaled agent-subject
+ *    memories with no equivalent in the target layer), and
+ *  - the deterministic backfill pass (shadow/apply, no LLM).
+ */
+
+import { ContentHashIndex } from "./storage/content-hash-index.js";
+import { sanitizeMemoryContent } from "./sanitize.js";
+import type { McpTool } from "./access-mcp.js";
+import type { MemoryCategory, MemoryFile, MemorySubject, SubjectGuardMode } from "./types.js";
+
+export const SUBJECT_VALUES = ["user", "agent"] as const;
+export const SUBJECT_GUARD_MODES = ["off", "warn", "enforce"] as const;
+
+/** The CLI / per-call override that permits a user-subject promotion. */
+export const SUBJECT_GUARD_OVERRIDE_FLAG = "--allow-user-subject";
+
+export function isMemorySubject(value: unknown): value is MemorySubject {
+  return value === "user" || value === "agent";
+}
+
+export function isSubjectGuardMode(value: unknown): value is SubjectGuardMode {
+  return value === "off" || value === "warn" || value === "enforce";
+}
+
+// ---------------------------------------------------------------------------
+// Write-time classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic category defaults (issue #2372 §1):
+ *   user — preference, relationship, moment, commitment
+ *   agent — procedure, principle, skill
+ * Every other category has no default; the resolver falls back to `"user"`,
+ * the most-restrictive value (Review Prevention Checklist §36 — an unsafe
+ * enum default is never the convenient one).
+ */
+const SUBJECT_CATEGORY_DEFAULTS: Partial<Record<MemoryCategory, MemorySubject>> = {
+  preference: "user",
+  relationship: "user",
+  moment: "user",
+  commitment: "user",
+  procedure: "agent",
+  principle: "agent",
+  skill: "agent",
+};
+
+export function subjectDefaultForCategory(category: MemoryCategory): MemorySubject {
+  return SUBJECT_CATEGORY_DEFAULTS[category] ?? "user";
+}
+
+/**
+ * Resolve the write-time subject: the extractor's single-token value when it
+ * emitted a valid one, else the category default. Never reclassifies on read.
+ */
+export function resolveWriteSubject(
+  category: MemoryCategory,
+  extractorValue: unknown,
+): MemorySubject {
+  return isMemorySubject(extractorValue) ? extractorValue : subjectDefaultForCategory(category);
+}
+
+// ---------------------------------------------------------------------------
+// Promotion guard (uniform across every promotion surface — §27)
+// ---------------------------------------------------------------------------
+
+/** Scope-profile promotion targets that are shared layers. */
+export function isSharedPromotionTarget(target: string): boolean {
+  return target === "teamProject" || target === "serverShared";
+}
+
+export interface SubjectGuardDecision {
+  action: "allow" | "warn" | "reject";
+  /** Effective subject — an absent subject resolves to "user" (fail closed, §36). */
+  effectiveSubject: MemorySubject;
+  /** Structured reason; empty string when action === "allow". */
+  reason: string;
+  /** The override that permits this promotion when action is reject/warn. */
+  override: typeof SUBJECT_GUARD_OVERRIDE_FLAG;
+}
+
+/**
+ * Evaluate one promotion against the subject guard. Shared by the spaces
+ * promotion workflow and the scope-profile promotion targets so the two
+ * surfaces cannot drift (issue #2372 acceptance 2, AGENTS.md §27).
+ *
+ *  - mode "off", non-shared targets, agent-subject memories, and explicit
+ *    `allowUserSubject` overrides all allow.
+ *  - a `user`-subject memory (or a memory with NO subject — fail closed)
+ *    promoted to a shared layer warns under "warn" and rejects under
+ *    "enforce", with the override named in the reason (§39: never a silent
+ *    accept).
+ */
+export function evaluateSubjectGuard(params: {
+  subject: MemorySubject | undefined;
+  sharedTarget: boolean;
+  mode: SubjectGuardMode;
+  allowUserSubject?: boolean;
+}): SubjectGuardDecision {
+  const effectiveSubject = params.subject ?? "user";
+  const base = { effectiveSubject, override: SUBJECT_GUARD_OVERRIDE_FLAG } as const;
+  if (params.mode === "off" || !params.sharedTarget || effectiveSubject === "agent") {
+    return { action: "allow", reason: "", ...base };
+  }
+  if (params.allowUserSubject === true) {
+    return { action: "allow", reason: "user-subject promotion override accepted", ...base };
+  }
+  return {
+    action: params.mode === "enforce" ? "reject" : "warn",
+    reason:
+      `subject=${effectiveSubject} memory targets a shared layer (team/server); ` +
+      `user-subject memories model one person and must not be shared; ` +
+      `override with ${SUBJECT_GUARD_OVERRIDE_FLAG} (allowUserSubject: true) if intended`,
+    ...base,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Promotion candidates (read-only surfacing — no auto-promotion)
+// ---------------------------------------------------------------------------
+
+export type PromotionReuseSignal = "reinforcement" | "memory_worth" | "access_count";
+
+export interface PromotionCandidate {
+  id: string;
+  path: string;
+  category: MemoryCategory;
+  content: string;
+  accessCount: number;
+  reinforcementCount: number;
+  mwSuccess: number;
+  mwFail: number;
+  reuseSignal: PromotionReuseSignal;
+}
+
+/** Default reuse-signal threshold for `accessCount` (config `promotionCandidates.minAccessCount`). */
+export const PROMOTION_CANDIDATES_DEFAULT_MIN_ACCESS = 3;
+
+/** Canonical content form for target-equivalence checks (same normalize pipeline as dedup). */
+export function promotionCandidateKey(content: string): string {
+  return ContentHashIndex.normalizeContent(sanitizeMemoryContent(content).text);
+}
+
+/**
+ * List `subject: "agent"` memories that (a) are active, (b) show a reuse
+ * signal (`reinforcement_count > 0` OR `mw_success > mw_fail` OR
+ * `accessCount >= minAccessCount`), and (c) have no equivalent already in
+ * the promotion target layer (content-hash check via the dedup normalizer).
+ * Pure over the two memory lists; callers resolve namespaces.
+ */
+export function computePromotionCandidates(options: {
+  memories: MemoryFile[];
+  targetMemories: MemoryFile[];
+  minAccessCount: number;
+  limit?: number;
+}): PromotionCandidate[] {
+  if (!Number.isFinite(options.minAccessCount) || options.minAccessCount < 0) {
+    throw new Error(
+      `computePromotionCandidates: minAccessCount must be a non-negative number (got ${String(options.minAccessCount)})`,
+    );
+  }
+  const targetKeys = new Set(
+    options.targetMemories.map((m) => promotionCandidateKey(m.content ?? "")),
+  );
+  const out: PromotionCandidate[] = [];
+  for (const memory of options.memories) {
+    const fm = memory.frontmatter;
+    if (fm.subject !== "agent") continue;
+    if ((fm.status ?? "active") !== "active") continue;
+    const reinforcementCount = fm.reinforcement_count ?? 0;
+    const mwSuccess = fm.mw_success ?? 0;
+    const mwFail = fm.mw_fail ?? 0;
+    const accessCount = fm.accessCount ?? 0;
+    let reuseSignal: PromotionReuseSignal | undefined;
+    if (reinforcementCount > 0) reuseSignal = "reinforcement";
+    else if (mwSuccess > mwFail) reuseSignal = "memory_worth";
+    else if (accessCount >= options.minAccessCount) reuseSignal = "access_count";
+    if (reuseSignal === undefined) continue;
+    if (targetKeys.has(promotionCandidateKey(memory.content ?? ""))) continue;
+    out.push({
+      id: fm.id,
+      path: memory.path,
+      category: fm.category,
+      content: memory.content ?? "",
+
+      accessCount,
+      reinforcementCount,
+      mwSuccess,
+      mwFail,
+      reuseSignal,
+    });
+    if (options.limit !== undefined && out.length >= options.limit) break;
+  }
+  return out;
+}
+
+export interface PromotionCandidatesResult {
+  namespace: string;
+  targetNamespace: string;
+  minAccessCount: number;
+  candidates: PromotionCandidate[];
+}
+
+export const PROMOTION_CANDIDATES_MCP_TOOLS: McpTool[] = [
+  {
+    // Registered as `engram.promotion_candidates`; `withToolAliases` emits
+    // the canonical `remnic.promotion_candidates` alias (dual-naming).
+    name: "engram.promotion_candidates",
+    description:
+      "List agent-subject memories in the caller's namespace that are active, show a reuse signal (reinforcement_count > 0, mw_success > mw_fail, or accessCount >= threshold), and have no equivalent in the promotion target layer (default: the shared namespace). Read-only report; promotion itself uses the existing promotion commands (issue #2372).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: {
+          type: "string",
+          description:
+            "Optional source namespace. Enforced against the caller's principal the same way recall is.",
+        },
+        targetNamespace: {
+          type: "string",
+          description: "Promotion target layer checked for existing equivalents. Default: the shared namespace.",
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 100,
+          description: "Maximum candidates to return (default 20, max 100).",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Backfill (governance shadow/apply — deterministic rules only, no LLM)
+// ---------------------------------------------------------------------------
+
+/**
+ * Storage surface the backfill needs (mirrors pattern-reinforcement's
+ * structural interface so tests can pass an in-memory stub).
+ * `writeMemoryFrontmatter` invalidates caches and syncs the fact-hash index
+ * (§25/§31), so a stamped memory is immediately discoverable.
+ */
+export interface SubjectBackfillStorage {
+  readAllMemories(): Promise<MemoryFile[]>;
+  writeMemoryFrontmatter(memory: MemoryFile, patch: Partial<MemoryFile["frontmatter"]>): Promise<boolean>;
+}
+
+export interface SubjectBackfillReport {
+  mode: "shadow" | "apply";
+  scanned: number;
+  stamped: number;
+  alreadyStamped: number;
+  stamps: Array<{
+    id: string;
+    category: MemoryCategory;
+    subject: MemorySubject;
+    path: string;
+  }>;
+}
+
+/**
+ * Stamp `subject` on memories that have none, using ONLY the deterministic
+ * category defaults (never an LLM, never reclassifying an existing subject —
+ * issue #2372 §1.3). `shadow` reports the intended stamps without writing;
+ * `apply` writes through `writeMemoryFrontmatter`, which invalidates the
+ * memory caches and re-syncs the fact-hash index.
+ */
+export async function backfillMemorySubjects(options: {
+  storage: SubjectBackfillStorage;
+  mode: "shadow" | "apply";
+}): Promise<SubjectBackfillReport> {
+  const memories = await options.storage.readAllMemories();
+  const report: SubjectBackfillReport = {
+    mode: options.mode,
+    scanned: memories.length,
+    stamped: 0,
+    alreadyStamped: 0,
+    stamps: [],
+  };
+  for (const memory of memories) {
+    if (memory.frontmatter.subject !== undefined) {
+      report.alreadyStamped++;
+      continue;
+    }
+    const subject = subjectDefaultForCategory(memory.frontmatter.category);
+    report.stamps.push({
+      id: memory.frontmatter.id,
+      category: memory.frontmatter.category,
+      subject,
+      path: memory.path,
+    });
+    if (options.mode === "apply") {
+      await options.storage.writeMemoryFrontmatter(memory, { subject });
+    }
+    report.stamped++;
+  }
+  return report;
+}

package/src/memory-worth-outcomes.test.ts

@@ -306,11 +306,15 @@ test("concurrent outcomes for the same memory do NOT lose updates", async () =>
   }
 });
 
-test("eligible-category set is exactly {fact}", () => {
+test("eligible-category set is exactly {fact, procedure}", () => {
   // Pinning this keeps PR 3 in lockstep with the PR 1 doctor allowlist in
   // operator-toolkit.ts (MEMORY_WORTH_ELIGIBLE_CATEGORIES). If either side
   // expands, this test and the doctor test must both be updated.
+  // `procedure` joined in issue #2370: the procedure library-health loop
+  // retires on failure-dominant mw_* counters, so injected procedures must
+  // accrue outcomes.
   const eligible = memoryWorthOutcomeEligibleCategories();
-  assert.equal(eligible.size, 1);
+  assert.equal(eligible.size, 2);
   assert.ok(eligible.has("fact"));
+  assert.ok(eligible.has("procedure"));
 });

package/src/memory-worth-outcomes.ts

@@ -20,8 +20,9 @@
  *     preserved. The PR 1 serializer rejects negative / non-integer counters,
  *     so we rely on that for defensive validation rather than duplicating it.
  *   - Only instruments categories in `MEMORY_WORTH_OUTCOME_ELIGIBLE_CATEGORIES`
- *     (currently `fact`, matching `MEMORY_WORTH_ELIGIBLE_CATEGORIES` in
- *     operator-toolkit.ts for the doctor audit). Non-eligible memories return
+ *     (currently `fact` and `procedure` — procedures joined in issue #2370 —
+ *     matching `MEMORY_WORTH_ELIGIBLE_CATEGORIES` in operator-toolkit.ts for
+ *     the doctor audit). Non-eligible memories return
  *     `{ ok: false, reason: "ineligible_category" }` rather than throwing so
  *     the caller — typically a ledger consumer draining heterogeneous events
  *     — doesn't need to pre-filter by category.
@@ -94,14 +95,17 @@ function runSerialized<T>(key: string, task: () => Promise<T>): Promise<T> {
 }
 
 /**
- * Categories currently instrumented for Memory Worth counters. Must be kept
- * in sync with `MEMORY_WORTH_ELIGIBLE_CATEGORIES` in `operator-toolkit.ts`.
- * Declared here (not imported) to avoid a circular dep with operator-toolkit,
- * which imports from this file's peers. The two constants are validated by a
+ * Categories currently instrumented for Memory Worth counters. `procedure`
+ * joined in issue #2370 — the procedure library-health maintenance loop
+ * retires on failure-dominant `mw_*` counters, so injected procedures must
+ * be able to accrue outcomes. Must be kept in sync with
+ * `MEMORY_WORTH_ELIGIBLE_CATEGORIES` in `operator-toolkit.ts`. Declared
+ * here (not imported) to avoid a circular dep with operator-toolkit, which
+ * imports from this file's peers. The two constants are validated by a
  * test to stay in lockstep.
  */
 const MEMORY_WORTH_OUTCOME_ELIGIBLE_CATEGORIES: ReadonlySet<MemoryFrontmatter["category"]> =
-  new Set(["fact"]);
+  new Set(["fact", "procedure"]);
 
 /**
  * Exported so downstream tests / operators can query the allowlist without

package/src/operator-toolkit.ts

@@ -1580,7 +1580,7 @@ export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise
  * alongside the scoring/increment logic so the doctor audit stays in sync.
  */
 const MEMORY_WORTH_ELIGIBLE_CATEGORIES: ReadonlySet<MemoryFile["frontmatter"]["category"]> =
-  new Set(["fact"]);
+  new Set(["fact", "procedure"]);
 
 /**
  * Count memories that pre-date the Memory Worth counters introduced in issue

package/src/orchestration/extraction-persist.ts

@@ -74,6 +74,7 @@ import {
 } from "../behavior-signals.js";
 import { buildProcedurePersistBody } from "../procedural/procedure-types.js";
 import { stripAttributesSuffix } from "../structured-attributes.js";
+import { evaluateSubjectGuard, isSharedPromotionTarget, resolveWriteSubject } from "../memory-subject.js";
 import { LocalLlmClient } from "../local-llm.js";
 import type { ExtractionEngine } from "../extraction.js";
 import {
@@ -94,6 +95,7 @@ import type {
   MemoryFile,
   MemoryFrontmatter,
   MemoryLink,
+  MemorySubject,
   PluginConfig,
   ProvenanceSource,
   MemoryCategory,
@@ -338,6 +340,19 @@ export class ExtractionPersistCoordinator {
     // introduced (ratchet scatteredConfigFlagReads; see #1523).
     const namespacesEnabled = resolveNamespaceCapabilities(this.deps.config).namespaces;
     const sourceConnector = sourceContext?.sourceConnector; const origin = classifyExtractionOrigin(sourceContext);
+    // Subject guard (issue #2372): the ONE gate shared by every extraction-side
+    // promotion path so behavior matches the spaces surface (§27).
+    const subjectGuardAllows = (subject: MemorySubject | undefined, target: string, label: string): boolean => {
+      const decision = evaluateSubjectGuard({
+        subject,
+        sharedTarget: isSharedPromotionTarget(target),
+        mode: this.deps.config.subjectGuard,
+      });
+      if (decision.action !== "allow") {
+        log.warn(`subject-guard(${decision.action}) ${label}: ${decision.reason}`);
+      }
+      return decision.action !== "reject";
+    };
     const promoteMemoryToProfileTargets = async (options: {
       sourceStorage: StorageManager;
       category: string;
@@ -353,8 +368,7 @@ export class ExtractionPersistCoordinator {
       intentEntityTypes?: string[];
       memoryKind?: MemoryFrontmatter["memoryKind"];
       validAt?: string;
-      // #1578 — bi-temporal bounds + ingestion provenance forwarded to profile-
-      // target copies (same defect class as shared promotion; cursor bugbot).
+      // #1578 — bi-temporal bounds + provenance forwarded to profile-target copies.
       invalidAt?: string;
       observedAt?: string;
       eventTimeSource?: "extracted" | "assumed";
@@ -362,6 +376,7 @@ export class ExtractionPersistCoordinator {
       sources?: ProvenanceSource[];
       provenance?: "verified" | "unverified" | "none";
       toolScoped?: true;
+      subject?: MemorySubject;
       harmonicFact?: Omit<
         HarmonicConstructionInput["persistedFacts"][number],
         "memoryId"
@@ -392,6 +407,7 @@ export class ExtractionPersistCoordinator {
         try {
           const targetStorage = await this.deps.getStorageRouter().storageFor(target.namespace);
           if (targetStorage.dir === options.sourceStorage.dir) continue;
+          if (!subjectGuardAllows(options.subject, target.target, `profile promotion to ${target.target}`)) continue;
           // Compose BEFORE the dedup gate (#2014 round 2): salvage mode may
           // drop or clamp attributes, and the dedup hash, contentHashSource,
           // and supersession keys below must all describe the SURVIVING
@@ -406,6 +422,7 @@ export class ExtractionPersistCoordinator {
               structuredAttributes: options.structuredAttributes,
               validAt: options.validAt,
               ...(sourceContext?.sourceConnector ? { sourceConnector: sourceContext.sourceConnector } : {}),
+              ...(options.subject !== undefined ? { subject: options.subject } : {}),
             },
             { source: `${options.source}-${target.target}-promotion` },
           );
@@ -557,8 +574,7 @@ export class ExtractionPersistCoordinator {
       memoryKind?: MemoryFrontmatter["memoryKind"];
       validAt?: string;
       // #1578 — bi-temporal bounds + ingestion provenance forwarded to the
-      // shared-namespace copy so shared recall honours the same invalid_at
-      // window as the source fact (cursor bugbot).
+      // shared-namespace copy (cursor bugbot).
       invalidAt?: string;
       observedAt?: string;
       eventTimeSource?: "extracted" | "assumed";
@@ -568,6 +584,7 @@ export class ExtractionPersistCoordinator {
       /** Claim-level provenance spans (issue #1575 PR 2). */
       sources?: ProvenanceSource[];
       provenance?: "verified" | "unverified" | "none";
+      subject?: MemorySubject;
       harmonicFact?: Omit<
         HarmonicConstructionInput["persistedFacts"][number],
         "memoryId"
@@ -591,43 +608,19 @@ export class ExtractionPersistCoordinator {
         )
       )
         return;
+      if (!subjectGuardAllows(options.subject, "serverShared", "shared promotion")) return;
       try {
         const sharedStorage = await this.deps.getStorageRouter().storageFor(
           this.deps.config.sharedNamespace,
         );
-        // Dedup gate: canonicalize content before hashing.
-        // Issue #369 (PR #401): When inline attribution is enabled,
-        // `applyInlineCitation` appends a timestamp-bearing marker (e.g.
-        // `[Source: ..., ts=2026-04-11T...]`).  Because the timestamp changes
-        // on every call, hashing cited content produces a unique hash each
-        // time — defeating dedup entirely and allowing the same logical fact to
-        // be promoted repeatedly.  Also, both promotion call sites pass
-        // `fact.content`, which can already carry an inline citation (e.g. a
-        // relayed or reprocessed fact).  Strip any pre-existing citation so the
-        // dedup key matches the hash stored from the original un-cited write.
-        // PR #402 round-6 (Fix #2 / chatgpt-codex P1 PRRT_kwDORJXyws56U74n):
-        // Compute the enriched content before the hash-dedup check so the
-        // lookup uses the same content that writeMemory will actually store.
-        // When structuredAttributes are present, writeMemory appends an
-        // "[Attributes: ...]" suffix before hashing; hasFactContentHash must
-        // receive the same enriched body or the check is against a different
-        // hash and dedup fails to fire (letting duplicates through) or fires
-        // when it shouldn't (collapsing memories with different enrichments).
-        // Fix #1 (P2 PRRT_kwDORJXyws56VHZc): use normalizeAttributePairs so
-        // key order and casing are canonical — identical to the enrichment
-        // applied by storage.writeMemory — preventing spurious hash misses
-        // when attribute maps arrive with different insertion orders or casing.
-        // Fix #4 (Low PRRT_kwDORJXyws56VHth): sanitize the base content before
-        // building dedupContent.  writeMemory runs sanitizeMemoryContent on the
-        // enriched body before hashing; if sanitization redacts the content to
-        // REDACTED_PLACEHOLDER the stored hash is for the redacted form, not
-        // the raw form.  Computing dedupContent from sanitized.text here ensures
-        // the hash lookup and the normalizedIncoming comparison both use the
-        // same content that writeMemory will actually store.
-        // Combined fix: strip any pre-existing citation FIRST to obtain
-        // rawContent (the canonical body), then sanitize rawContent (not
-        // options.content) when building dedupContent, so that citation
-        // stripping and sanitization are applied in a consistent order.
+        // Dedup gate: canonicalize content before hashing. Strip any
+        // pre-existing citation FIRST (applyInlineCitation appends a
+        // timestamped marker, so hashing cited content defeats dedup and
+        // call sites may pass already-cited content), then sanitize the base
+        // and build the attribute-enriched body with normalizeAttributePairs
+        // — the same canonicalization writeMemory applies — so the hash
+        // lookup uses the exact body writeMemory stores (#369/#401, #402
+        // round-6 fixes; PRRT_kwDORJXyws56VHZc / VHth).
         const rawContent =
           citationEnabled &&
           hasCitationForTemplate(options.content, citationTemplate)
@@ -649,6 +642,7 @@ export class ExtractionPersistCoordinator {
             structuredAttributes: options.structuredAttributes,
             validAt: options.validAt,
             ...(sourceContext?.sourceConnector ? { sourceConnector: sourceContext.sourceConnector } : {}),
+            ...(options.subject !== undefined ? { subject: options.subject } : {}),
           },
           { source: `${options.source}-shared-promotion` },
         );
@@ -1330,7 +1324,8 @@ export class ExtractionPersistCoordinator {
             profileAllowsSharedWrites &&
             this.deps.storageDirNamespace(storage.dir) !== this.deps.config.sharedNamespace &&
             shouldPromoteGlobalFactToShared({ scope: f.scope, content: f.content,
-              sourceConnector, procedureSteps: f.procedureSteps })
+              sourceConnector, procedureSteps: f.procedureSteps }) &&
+            subjectGuardAllows(f.subject, "serverShared", "pre-judge shared routing")
           ) {
             factNs = this.deps.config.sharedNamespace;
           }
@@ -1577,10 +1572,13 @@ export class ExtractionPersistCoordinator {
           );
         }
       }
-
-      // Scope-based namespace routing: a `global` fact (scope classification
-      // on, no explicit routing-rule namespace) is promoted to the shared
-      // namespace unless the tool-scope guard withholds it (#2183).
+      // Write-time subject stamp (issue #2372): extractor token over the
+      // category default; absent when classification is disabled (byte-identical).
+      const factSubject = this.deps.config.subjectClassification?.enabled === true
+        ? resolveWriteSubject(writeCategory, fact.subject)
+        : undefined;
+      // Scope-based namespace routing: a `global` fact (no explicit routing
+      // rule) promotes to the shared namespace unless a guard withholds it.
       if (
         lifecycleCaps.extractionScopeClassification &&
         namespacesEnabled &&
@@ -1590,7 +1588,7 @@ export class ExtractionPersistCoordinator {
         const currentNs = this.deps.storageDirNamespace(targetStorage.dir);
         if (currentNs !== this.deps.config.sharedNamespace && profileAllowsSharedWrites) {
           if (shouldPromoteGlobalFactToShared({ scope: fact.scope, content: fact.content,
-            sourceConnector, procedureSteps: fact.procedureSteps })) {
+            sourceConnector, procedureSteps: fact.procedureSteps }) && subjectGuardAllows(fact.subject, "serverShared", "scope-routing")) {
             try {
               targetStorage = await this.deps.getStorageRouter().storageFor(
                 this.deps.config.sharedNamespace,
@@ -2383,6 +2381,7 @@ export class ExtractionPersistCoordinator {
             sourceStorage: targetStorage,
             category: writeCategory,
             content: fact.content,
+            subject: factSubject,
             confidence: fact.confidence,
             tags: fact.tags,
             entityRef: fact.entityRef,
@@ -2579,6 +2578,7 @@ export class ExtractionPersistCoordinator {
           structuredAttributes: fact.structuredAttributes,
           validAt: biTemporal ? biTemporal.validFrom : sourceContext?.validAt,
           ...(extractionSourceConnector ? { sourceConnector: extractionSourceConnector } : {}),
+          ...(factSubject !== undefined ? { subject: factSubject } : {}),
         },
         { source: extractionWriteSource },
 );
@@ -2697,6 +2697,7 @@ export class ExtractionPersistCoordinator {
           category: writeCategory,
           content: fact.content,
           confidence: fact.confidence,
+          subject: factSubject,
           tags: fact.tags,
           entityRef:
             typeof (fact as any).entityRef === "string"
@@ -2822,11 +2823,10 @@ export class ExtractionPersistCoordinator {
       }
     }
 
-    // Tracks whether THIS extraction persisted any durable, non-fact output to the
-    // BASE namespace's storage (entity / relationship / profile / question). The
-    // per-fact catalog touch (storage chokepoint #1522) only fires inside the fact write loop, so a
-    // fact-less extraction that still persists durable data must record exactly one
-    // base-namespace catalog touch after all writes complete (NHZEZ, codex P2).
+    // Tracks whether THIS extraction persisted any durable, non-fact output
+    // (entity / relationship / profile / question) to the BASE namespace.
+    // A fact-less extraction still records exactly one base-namespace catalog
+    // touch after all writes complete (NHZEZ, codex P2).
     let durableNonFactWritten = false;
     let durableNonFactTouchRecorded = false;
     const touchBaseNonFactNamespace = () => {

package/src/orchestration/recall-internal-deps.ts

@@ -219,6 +219,8 @@ export interface RecallInternalDeps {
       searchOptions?: SearchQueryOptions;
       onDebugSnapshot?: (snapshot: QmdRecallSnapshot) => Promise<void>;
       /** Backend degradation observer, threaded into every QMD call (#1536). */
+      /** Cross-lingual plan flag (#2197): supplement the lexical page with vector-tier hits. */
+      crossScript?: boolean;
       onDegradation?: (degradation: SearchDegradation) => void;
       abortSignal?: AbortSignal;
     },