@remnic/core 9.65.1 → 9.65.3

package/src/review/review-deck.ts

@@ -0,0 +1,311 @@
+import { createHash } from "node:crypto";
+
+export type ReviewDeckChoice = "keep" | "prepare_fix" | "not_true";
+export type ReviewDeckRisk = "reversible";
+
+export interface ReviewDeckEvidence {
+  sourceMemoryId?: string;
+  sourceDate?: string;
+  excerpt?: string;
+  relation: "supports" | "conflicts" | "origin";
+}
+
+export interface ReviewDeckItem {
+  schemaVersion: 1;
+  itemId: string;
+  source: "review";
+  sourceId: string;
+  memoryId?: string;
+  content: string;
+  category?: string;
+  lifecycleState?: string;
+  confidence?: number;
+  confidenceTier?: string;
+  reviewReason: string;
+  reviewReasonLabel: string;
+  supportCount: number;
+  provenance: readonly ReviewDeckEvidence[];
+  allowedChoices: readonly ReviewDeckChoice[];
+  choiceRisk: Readonly<Record<ReviewDeckChoice, ReviewDeckRisk | "unavailable">>;
+  namespace: string;
+  revision: string;
+}
+
+export interface ReviewDeckPage {
+  schemaVersion: 1;
+  items: readonly ReviewDeckItem[];
+  nextCursor?: string;
+  total: number;
+}
+
+export type ReviewDeckActionRequest =
+  | { schemaVersion: 1; itemId: string; revision: string; action: "keep" | "not_true"; idempotencyKey: string }
+  | { schemaVersion: 1; itemId: string; revision: string; action: "prepare_fix"; correctionText: string; idempotencyKey: string };
+
+export interface ReviewDeckActionReceipt {
+  schemaVersion: 1;
+  receiptId: string;
+  itemId: string;
+  action: "keep" | "not_true" | "prepare_fix" | "undo";
+  outcome: "planned" | "applied" | "conflict" | "failed";
+  effect: string;
+  undoAvailable: boolean;
+  appliedRevision?: string;
+  correctionPlanId?: string;
+  correctionPreview?: unknown;
+}
+
+export interface ReviewDeckUndoRequest {
+  schemaVersion: 1;
+  receiptId: string;
+  expectedRevision: string;
+  idempotencyKey: string;
+}
+
+export interface ReviewDeckSourceRow {
+  itemId: string;
+  filePath: string;
+  fileContent: string;
+  revision: string;
+  content: string;
+  category?: string;
+  confidence?: number;
+  confidenceTier?: string;
+  reviewReason: string;
+  created: string;
+  source?: string;
+  blockedBy?: string;
+  lifecycleState?: string;
+  context?: string;
+}
+
+export interface ReviewDeckSnapshot {
+  corpusVersion: string;
+  total: number;
+  rows: readonly ReviewDeckSourceRow[];
+}
+
+export interface ReviewDeckCursorScope {
+  principalDigest: string;
+  namespace: string;
+  filterDigest: string;
+  corpusVersion: string;
+}
+
+export class ReviewDeckCursorError extends Error {
+  constructor(message = "Invalid review deck cursor") {
+    super(message);
+    this.name = "ReviewDeckCursorError";
+  }
+}
+
+const ALLOWED_CHOICES = ["keep", "prepare_fix", "not_true"] as const satisfies readonly ReviewDeckChoice[];
+const REVERSIBLE_RISK = {
+  keep: "reversible",
+  prepare_fix: "reversible",
+  not_true: "reversible",
+} as const satisfies Record<ReviewDeckChoice, ReviewDeckRisk>;
+
+const REVIEW_REASON_LABELS: Record<string, string> = {
+  low_confidence: "Low confidence",
+  suggestion: "Suggested memory",
+  tombstone_blocked: "Blocked by a deletion",
+  contradiction: "Conflicts with another memory",
+  duplicate: "Possible duplicate",
+};
+
+const EXCERPT_LIMIT = 240;
+
+export function computeReviewItemRevision(fileContent: string): string {
+  return `rv1:${createHash("sha256").update(fileContent).digest("hex")}`;
+}
+
+export function projectReviewDeckItem(row: ReviewDeckSourceRow, namespace: string): ReviewDeckItem {
+  const provenance = provenanceFromRow(row);
+  return {
+    schemaVersion: 1,
+    itemId: row.itemId,
+    source: "review",
+    sourceId: row.itemId,
+    memoryId: row.itemId,
+    content: row.content,
+    ...(row.category !== undefined ? { category: row.category } : {}),
+    ...(row.lifecycleState !== undefined ? { lifecycleState: row.lifecycleState } : {}),
+    ...(row.confidence !== undefined ? { confidence: row.confidence } : {}),
+    ...(row.confidenceTier !== undefined ? { confidenceTier: row.confidenceTier } : {}),
+    reviewReason: row.reviewReason,
+    reviewReasonLabel: reviewReasonLabel(row.reviewReason),
+    supportCount: provenance.filter((entry) => entry.relation === "supports").length,
+    provenance,
+    allowedChoices: ALLOWED_CHOICES,
+    choiceRisk: REVERSIBLE_RISK,
+    namespace,
+    revision: row.revision,
+  };
+}
+
+export function compareReviewDeckRows(a: ReviewDeckSourceRow, b: ReviewDeckSourceRow): number {
+  const aBlocked = a.blockedBy && a.blockedBy.length > 0 ? 0 : 1;
+  const bBlocked = b.blockedBy && b.blockedBy.length > 0 ? 0 : 1;
+  if (aBlocked !== bBlocked) return aBlocked - bBlocked;
+  const aConfidence = a.confidence ?? 0.5;
+  const bConfidence = b.confidence ?? 0.5;
+  if (aConfidence !== bConfidence) return aConfidence < bConfidence ? -1 : 1;
+  if (a.created !== b.created) return a.created < b.created ? -1 : 1;
+  if (a.itemId !== b.itemId) return a.itemId < b.itemId ? -1 : 1;
+  return 0;
+}
+
+export function encodeReviewDeckCursor(scope: ReviewDeckCursorScope, lastSortKey: string): string {
+  return Buffer.from(
+    JSON.stringify({
+      v: 1,
+      p: scope.principalDigest,
+      n: scope.namespace,
+      f: scope.filterDigest,
+      c: scope.corpusVersion,
+      k: lastSortKey,
+    }),
+    "utf8",
+  ).toString("base64url");
+}
+
+export function decodeReviewDeckCursor(cursor: string, scope: ReviewDeckCursorScope): string {
+  const payload = parseCursorPayload(cursor);
+  if (
+    payload.p !== scope.principalDigest
+    || payload.n !== scope.namespace
+    || payload.f !== scope.filterDigest
+    || payload.c !== scope.corpusVersion
+  ) {
+    throw new ReviewDeckCursorError("Review deck cursor scope mismatch");
+  }
+  return payload.k;
+}
+
+export function buildReviewDeckPage(
+  rows: readonly ReviewDeckSourceRow[],
+  opts: { scope: ReviewDeckCursorScope; cursor?: string; limit: number },
+): ReviewDeckPage {
+  const sorted = [...rows].sort(compareReviewDeckRows);
+  const limit = Math.max(0, opts.limit);
+  let start = 0;
+  if (opts.cursor !== undefined) {
+    const lastSortKey = decodeReviewDeckCursor(opts.cursor, opts.scope);
+    start = sorted.findIndex((row) => reviewDeckSortKey(row) > lastSortKey);
+    if (start < 0) start = sorted.length;
+  }
+  const pageRows = limit === 0 ? [] : sorted.slice(start, start + limit);
+  const items = pageRows.map((row) => projectReviewDeckItem(row, opts.scope.namespace));
+  const consumed = start + pageRows.length;
+  const nextCursor =
+    pageRows.length > 0 && consumed < sorted.length
+      ? encodeReviewDeckCursor(opts.scope, reviewDeckSortKey(pageRows[pageRows.length - 1]))
+      : undefined;
+  return {
+    schemaVersion: 1,
+    items,
+    total: sorted.length,
+    ...(nextCursor !== undefined ? { nextCursor } : {}),
+  };
+}
+
+function reviewDeckSortKey(row: ReviewDeckSourceRow): string {
+  const blocked = row.blockedBy && row.blockedBy.length > 0 ? "0" : "1";
+  return `${blocked}\t${(row.confidence ?? 0.5).toFixed(6)}\t${row.created}\t${row.itemId}`;
+}
+
+function reviewReasonLabel(reason: string): string {
+  const known = REVIEW_REASON_LABELS[reason];
+  if (known) return known;
+  const words = reason.split("_").filter((part) => part.length > 0);
+  if (words.length === 0) return "Review";
+  return words
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function provenanceFromRow(row: ReviewDeckSourceRow): ReviewDeckEvidence[] {
+  const fm = parseFrontmatterFields(row.fileContent);
+  const source = nonempty(row.source) ?? nonempty(fm.source);
+  const context = nonempty(row.context) ?? nonempty(fm.context);
+  const created = nonempty(row.created) ?? nonempty(fm.created);
+  const supportIds = idList(fm.supports);
+  const conflictIds = [...idList(fm.conflicts), ...idList(fm.contradicts)];
+  const relatedIds = idList(fm.relatedMemoryIds);
+  const relatedRelation = row.reviewReason === "contradiction" ? "conflicts" : "supports";
+  const provenance: ReviewDeckEvidence[] = [];
+  if (source !== undefined || context !== undefined) {
+    provenance.push({
+      relation: "origin",
+      ...(created !== undefined ? { sourceDate: created } : {}),
+      excerpt: truncateExcerpt(context ?? source ?? ""),
+    });
+  }
+  for (const sourceMemoryId of supportIds) {
+    provenance.push({ relation: "supports", sourceMemoryId });
+  }
+  for (const sourceMemoryId of conflictIds) {
+    provenance.push({ relation: "conflicts", sourceMemoryId });
+  }
+  for (const sourceMemoryId of relatedIds) {
+    if (supportIds.includes(sourceMemoryId) || conflictIds.includes(sourceMemoryId)) continue;
+    provenance.push({ relation: relatedRelation, sourceMemoryId });
+  }
+  return provenance;
+}
+
+function parseFrontmatterFields(content: string): Record<string, string> {
+  if (!content.startsWith("---\n")) return {};
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) return {};
+  const fields: Record<string, string> = {};
+  for (const line of content.slice(4, end).split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    fields[line.slice(0, colonIdx).trim()] = line.slice(colonIdx + 1).trim();
+  }
+  return fields;
+}
+
+function idList(value: string | undefined): string[] {
+  if (value === undefined || value.length === 0) return [];
+  return value
+    .replace(/^\[|\]$/g, "")
+    .split(",")
+    .map((part) => part.trim().replace(/^["']|["']$/g, ""))
+    .filter((part) => part.length > 0);
+}
+
+function nonempty(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return value.trim().length > 0 ? value : undefined;
+}
+
+function truncateExcerpt(value: string): string {
+  return value.length <= EXCERPT_LIMIT ? value : value.slice(0, EXCERPT_LIMIT);
+}
+
+function parseCursorPayload(cursor: string): { v: 1; p: string; n: string; f: string; c: string; k: string } {
+  if (cursor.length === 0) throw new ReviewDeckCursorError("Malformed review deck cursor");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+  } catch {
+    throw new ReviewDeckCursorError("Malformed review deck cursor");
+  }
+  if (!parsed || typeof parsed !== "object") throw new ReviewDeckCursorError("Malformed review deck cursor");
+  const record = parsed as Record<string, unknown>;
+  if (record.v !== 1) throw new ReviewDeckCursorError("Unsupported review deck cursor schema");
+  if (
+    typeof record.p !== "string"
+    || typeof record.n !== "string"
+    || typeof record.f !== "string"
+    || typeof record.c !== "string"
+    || typeof record.k !== "string"
+    || record.k.length === 0
+  ) {
+    throw new ReviewDeckCursorError("Malformed review deck cursor");
+  }
+  return { v: 1, p: record.p, n: record.n, f: record.f, c: record.c, k: record.k };
+}

package/src/schemas.ts

@@ -103,6 +103,13 @@ export const ExtractedFactSchema = z.object({
     .describe(
       'Scope classification: "global" for cross-project knowledge (framework bugs, library behavior, API patterns, user preferences, general coding patterns); "project" for project-specific knowledge (file paths, env configs, deployment details, project workarounds) and for tool, command, or CLI-flag instructions tied to one agent, since the same tool name can mean different things across agents. When keeping such an agent-tied instruction, begin the fact with a leading "In <agent>," clause naming that agent. Defaults to "project" when a coding context is active.',
     ),
+  subject: z
+    .enum(["user", "agent"])
+    .optional()
+    .nullable()
+    .describe(
+      'Memory subject: "user" when the fact models the person (preferences, relationships, biography, moments, commitments about their life); "agent" when it is reusable operating knowledge (procedures, principles, tool-usage lessons, debugging strategies, environment facts with no personal content). Emit only for fact/decision-like facts; the category defaults cover preference, relationship, moment, commitment, procedure, principle, and skill.',
+    ),
   quote: z
     .string()
     .optional()

package/src/spaces/index.ts

@@ -8,6 +8,8 @@
  * through push/pull and promotion workflows.
  */
 
+import { evaluateSubjectGuard } from "../memory-subject.js";
+import type { SubjectGuardMode } from "../types.js";
 import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -99,6 +101,8 @@ export interface SpacePromoteResult {
   memoriesPromoted: number;
   conflicts: ConflictEntry[];
   durationMs: number;
+  /** Subject-guard warnings (issue #2372): user-subject memories promoted to a shared team space under "warn". */
+  subjectWarnings?: string[];
 }
 
 export interface ConflictEntry {
@@ -748,7 +752,10 @@ export function shareSpace(spaceId: string, members: string[], baseDir?: string)
 export async function promoteSpace(
   sourceSpaceId: string,
   targetSpaceId: string,
-  options?: { memoryIds?: string[]; force?: boolean; forceOverwrite?: boolean; baseDir?: string }
+  options?: {
+    memoryIds?: string[]; force?: boolean; forceOverwrite?: boolean; baseDir?: string;
+    subjectGuard?: SubjectGuardMode; allowUserSubject?: boolean;
+  }
 ): Promise<SpacePromoteResult> {
   const startTime = Date.now();
   const manifest = loadManifest(options?.baseDir);
@@ -766,6 +773,33 @@ export async function promoteSpace(
     }
   }
 
+  // Subject guard (issue #2372): the SAME gate as the scope-profile promotion
+  // path — a user-subject (or unstamped, fail-closed) memory promoted into a
+  // TEAM space warns/rejects with the override named; recorded in the audit trail.
+  const subjectWarnings: string[] = [];
+  const warnedMemoryIds: string[] = [];
+  if (target.kind === "team") {
+    const sourceFiles = fs.existsSync(source.memoryDir) ? walkMd(fs.realpathSync(source.memoryDir)) : [];
+    for (const file of sourceFiles) {
+      const fm = parseSimpleFrontmatter(fs.readFileSync(file, "utf8"));
+      if (!fm?.id) continue;
+      if (options?.memoryIds?.length && !options.memoryIds.includes(fm.id)) continue;
+      const decision = evaluateSubjectGuard({
+        subject: fm.subject === "user" || fm.subject === "agent" ? fm.subject : undefined,
+        sharedTarget: true,
+        mode: options?.subjectGuard ?? "warn",
+        allowUserSubject: options?.allowUserSubject,
+      });
+      if (decision.action === "reject") {
+        throw new Error(`space promote blocked by subject guard: memory ${fm.id} — ${decision.reason}`);
+      }
+      if (decision.action === "warn") {
+        subjectWarnings.push(`memory ${fm.id}: ${decision.reason}`);
+        warnedMemoryIds.push(fm.id);
+      }
+    }
+  }
+
   const result = await copyMemories(source.memoryDir, target.memoryDir, {
     filterIds: options?.memoryIds,
     force: options?.forceOverwrite !== undefined ? options.forceOverwrite : (options?.force ?? false),
@@ -776,7 +810,8 @@ export async function promoteSpace(
       action: "space.promote",
       sourceSpaceId,
       targetSpaceId,
-      details: `Promoted ${result.merged} memories from "${source.name}" to "${target.name}"`,
+      details: `Promoted ${result.merged} memories from "${source.name}" to "${target.name}"${subjectWarnings.length > 0 ? `; subject-guard warned ${subjectWarnings.length} user-subject memories (${warnedMemoryIds.join(", ")})` : ""}${options?.allowUserSubject === true ? "; user-subject override: --allow-user-subject" : ""}`,
+      ...(warnedMemoryIds.length > 0 ? { memoryIds: warnedMemoryIds } : {}),
     },
     options?.baseDir
   );
@@ -787,6 +822,7 @@ export async function promoteSpace(
     memoriesPromoted: result.merged,
     conflicts: result.conflicts,
     durationMs: Date.now() - startTime,
+    ...(subjectWarnings.length > 0 ? { subjectWarnings } : {}),
   };
 }
 

package/src/storage.ts

@@ -13,11 +13,8 @@ import {
 } from "node:fs/promises";
 import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync } from "node:fs";
 import { createHash } from "node:crypto";
-import {
-  computeContentHash,
-  computeLegacyContentHash,
-  normalizeContent,
-} from "./content-hash.js";
+import { computeLegacyContentHash, normalizeContent } from "./content-hash.js";
+import { parseDriftProvenance, serializeDriftProvenance } from "./preferences/drift-types.js";
 import { raceAbort } from "./abort-error.js";
 import { checkCorpusReadAbort, type CorpusReadOptions } from "./corpus-read-cancellation.js";
 import { selectArtifactMatches, type ArtifactSearchOptions } from "./artifact-search.js";
@@ -28,7 +25,6 @@ import { createMemorySnapshot } from "./memory-snapshot.js";
 import { assertMemoryFrontmatterId, warnProjectionFallback } from "./storage-guards.js";
 import { createTombstoneMigrationSourceContents } from "./storage/tombstone-migration-sources.js";
 import { MemoryReadStore, readWindowedMemories, type WindowedMemoryReadOptions, type WindowedMemoryReadResult } from "./storage/memory-read-store.js";
-import { hasSupersessionAudit } from "./storage/supersession-audit.js";
 import { runCommittedInvalidation } from "./storage/committed-invalidation.js";
 import { renderProfileWithLastUpdated, stripOkfProfileFrontmatter, withOkfProfileFrontmatter } from "./storage/profile-header.js";
 import { parseQuestionFile as parseQuestionFileText } from "./storage/questions-file.js";
@@ -166,6 +162,7 @@ import type {
   VerificationState,
   PolicyClass,
   MemoryStatus,
+  MemorySubject,
   MemoryActionEvent,
   MemoryLifecycleEvent,
   MemoryLifecycleEventType,
@@ -326,6 +323,7 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
   if (fm.language) lines.push(`language: ${fm.language}`);
   if (fm.type !== undefined) lines.push(`type: ${fm.type}`);
   if (fm.origin) lines.push(`origin: ${/^[A-Za-z0-9:_.*-]+$/.test(fm.origin) ? fm.origin : JSON.stringify(fm.origin)}`);
+  if (fm.subject) lines.push(`subject: ${fm.subject}`);
   if (fm.entityRef) lines.push(`entityRef: ${fm.entityRef}`);
   if (fm.sourceConnector) {
     // YAML-injection guard (review thread QMPsP): emit unquoted for
@@ -406,6 +404,7 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
     assertMemoryWorthCounter("mw_fail", fm.mw_fail);
     lines.push(`mw_fail: ${fm.mw_fail}`);
   }
+  lines.push(...serializeDriftProvenance(fm));
   // Importance scoring
   if (fm.importance) {
     lines.push(`importanceScore: ${fm.importance.score}`);
@@ -871,6 +870,7 @@ export function parseFrontmatter(raw: string): { frontmatter: MemoryFrontmatter;
       tags,
       entityRef: fm.entityRef || undefined,
       origin: fm.origin !== undefined ? parseOriginClass(decodeYamlScalar(fm.origin)) : undefined,
+      subject: fm.subject === "user" || fm.subject === "agent" ? fm.subject : undefined,
       sourceConnector: fm.sourceConnector ? decodeYamlScalar(fm.sourceConnector) || undefined : undefined,
       toolScoped: fm.toolScoped === "true" ? true : undefined,
       supersedes: fm.supersedes || undefined,
@@ -916,6 +916,7 @@ export function parseFrontmatter(raw: string): { frontmatter: MemoryFrontmatter;
       // Memory Worth counters (issue #560)
       mw_success,
       mw_fail,
+      ...parseDriftProvenance(fm),
       // Importance scoring
       importance,
       // Chunking
@@ -1739,6 +1740,7 @@ export interface WriteMemoryOptions {
   origin?: string;
   sourceConnector?: string;
   toolScoped?: true;
+  subject?: MemorySubject;
 }
 
 /**
@@ -1747,7 +1749,7 @@ export interface WriteMemoryOptions {
  */
 export type SealedWriteExtras = Omit<
   WriteMemoryOptions,
-  "confidence" | "tags" | "entityRef" | "source" | "expiresAt" | "validAt" | "structuredAttributes" | "sourceConnector" | "origin"
+  "confidence" | "tags" | "entityRef" | "source" | "expiresAt" | "validAt" | "structuredAttributes" | "sourceConnector" | "origin" | "subject"
 >;
 
 export class StorageManager extends TombstoneBlockedCaptureIndexHost {
@@ -3791,7 +3793,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       fm.sourceConnector = options.sourceConnector;
     }
     if (options.origin !== undefined) fm.origin = parseOriginClass(options.origin);
-
+    if (options.subject !== undefined) fm.subject = options.subject;
     // Assemble the persisted body (attribute-suffix enrichment + combined
     // sanitize) via the SHARED helper — the sealed-envelope composer uses the
     // same one, so the two write paths cannot diverge (issue #1989 PR2).

package/src/subject-config.ts

@@ -0,0 +1,80 @@
+/**
+ * Config parsing for the memory-subject runtime knobs (issue #2372).
+ *
+ * Extracted from config.ts (its structural-ratchet ceiling forbids growth);
+ * `parseConfig` spreads `parseSubjectRuntimeConfig(cfg)` into the plugin
+ * config literal.
+ *
+ * Validation posture (Review Prevention Checklist §1/§24/§39): invalid
+ * values are REJECTED loudly, never silently reinterpreted — but an omitted
+ * key takes the documented default. The deliberate asymmetry from the issue
+ * stands: classification defaults OFF while the guard defaults "warn", so
+ * enabling classification later immediately yields promotion warnings
+ * without a second flag flip, and with classification off, unstamped
+ * memories still only warn (never silently promote) at shared targets.
+ */
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import {
+  isSubjectGuardMode,
+  PROMOTION_CANDIDATES_DEFAULT_MIN_ACCESS,
+} from "./memory-subject.js";
+import type { SubjectGuardMode } from "./types.js";
+
+export interface SubjectRuntimeConfig {
+  subjectClassification: { enabled: boolean };
+  subjectGuard: SubjectGuardMode;
+  promotionCandidates: { minAccessCount: number };
+}
+
+/**
+ * Reject a non-object block loudly (rule 51 / §1): a shorthand like
+ * `subjectClassification: false` must never normalize silently to `{}`.
+ * Returns void so callers read the block through a DIRECT `cfg.<key>`
+ * member access — the config-contract parser walker derives nested key
+ * paths from those accesses, and a helper return value hides them.
+ */
+function assertObjectBlock(value: unknown, key: string, shape: string): void {
+  if (value === undefined) return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `${key} must be an object (got ${JSON.stringify(value)}). Use ${shape} (issue #2372).`,
+    );
+  }
+}
+
+export function parseSubjectRuntimeConfig(cfg: Record<string, unknown>): SubjectRuntimeConfig {
+  assertObjectBlock(cfg.subjectClassification, "subjectClassification", "subjectClassification: { enabled: true }");
+  const classification = (cfg.subjectClassification ?? {}) as Record<string, unknown>;
+  const rawEnabled = classification.enabled;
+  const enabledCoerced = coerceBool(rawEnabled);
+  if (rawEnabled !== undefined && enabledCoerced === undefined) {
+    throw new Error(
+      `subjectClassification.enabled must be a boolean or one of "true"/"false"/"1"/"0"/` +
+        `"yes"/"no"/"on"/"off" (got ${JSON.stringify(rawEnabled)}) — rejected, not defaulted (issue #2372).`,
+    );
+  }
+  const rawGuard = cfg.subjectGuard;
+  if (rawGuard !== undefined && !isSubjectGuardMode(rawGuard)) {
+    throw new Error(
+      `subjectGuard must be one of: off, warn, enforce (got ${JSON.stringify(rawGuard)}) — ` +
+        `rejected, not defaulted (issue #2372; checklist §1/§39).`,
+    );
+  }
+  assertObjectBlock(cfg.promotionCandidates, "promotionCandidates", "promotionCandidates: { minAccessCount: 3 }");
+  const candidates = (cfg.promotionCandidates ?? {}) as Record<string, unknown>;
+  const minAccessRaw = coerceNumber(candidates.minAccessCount);
+  if (candidates.minAccessCount !== undefined && (minAccessRaw === undefined || !Number.isFinite(minAccessRaw) || minAccessRaw < 0)) {
+    throw new Error(
+      `promotionCandidates.minAccessCount must be a non-negative number (got ${JSON.stringify(candidates.minAccessCount)}) — rejected, not defaulted (issue #2372).`,
+    );
+  }
+  return {
+    subjectClassification: { enabled: rawEnabled === undefined ? false : enabledCoerced === true },
+    subjectGuard: isSubjectGuardMode(rawGuard) ? rawGuard : "warn",
+    promotionCandidates: {
+      minAccessCount:
+        minAccessRaw !== undefined ? Math.floor(minAccessRaw) : PROMOTION_CANDIDATES_DEFAULT_MIN_ACCESS,
+    },
+  };
+}