@remnic/core 9.3.654 → 9.3.656

package/src/coding/coding-namespace.ts

@@ -576,8 +576,5 @@ export function lcmReadSessionIdsForNamespaces(
       out.push(key);
     }
   }
-  if (out.length === 0) {
-    out.push(sessionKey);
-  }
   return out;
 }

package/src/config.test.ts

@@ -1331,3 +1331,72 @@ test("parseConfig namespaceCatalogEnabled present-but-unrecognized → throws (r
   assert.throws(() => parseConfig({ namespaceCatalogEnabled: "flase" }), /boolean-like value/);
   assert.throws(() => parseConfig({ namespaceCatalogEnabled: 2 }), /boolean-like value/);
 });
+
+test("parseConfig maintenance namespace fanout defaults match hosted-safe policy", () => {
+  const cfg = parseConfig({});
+  assert.equal(cfg.maintenanceNamespaceFanoutEnabled, true);
+  assert.equal(cfg.maintenanceMaxNamespacesPerCycle, 20);
+  assert.equal(cfg.maintenanceIncludeProjectNamespaces, true);
+  assert.equal(cfg.maintenanceIncludeBranchNamespaces, false);
+  assert.equal(cfg.maintenanceIncludeTeamProjectNamespaces, true);
+  assert.equal(cfg.maintenanceNamespaceLockStaleMs, 10 * 60_000);
+});
+
+test("parseConfig accepts nested maintenance namespace fanout config", () => {
+  const cfg = parseConfig({
+    maintenance: {
+      namespaceFanoutEnabled: "false",
+      maxNamespacesPerCycle: "7",
+      includeProjectNamespaces: "off",
+      includeBranchNamespaces: "on",
+      includeTeamProjectNamespaces: "0",
+      namespaceLockStaleMs: "120000",
+    },
+  });
+  assert.equal(cfg.maintenanceNamespaceFanoutEnabled, false);
+  assert.equal(cfg.maintenanceMaxNamespacesPerCycle, 7);
+  assert.equal(cfg.maintenanceIncludeProjectNamespaces, false);
+  assert.equal(cfg.maintenanceIncludeBranchNamespaces, true);
+  assert.equal(cfg.maintenanceIncludeTeamProjectNamespaces, false);
+  assert.equal(cfg.maintenanceNamespaceLockStaleMs, 120_000);
+});
+
+test("parseConfig flat maintenance namespace fanout fields override nested config", () => {
+  const cfg = parseConfig({
+    maintenance: {
+      namespaceFanoutEnabled: false,
+      maxNamespacesPerCycle: 5,
+    },
+    maintenanceNamespaceFanoutEnabled: true,
+    maintenanceMaxNamespacesPerCycle: 8,
+  });
+  assert.equal(cfg.maintenanceNamespaceFanoutEnabled, true);
+  assert.equal(cfg.maintenanceMaxNamespacesPerCycle, 8);
+});
+
+test("parseConfig rejects invalid maintenance namespace fanout values", () => {
+  assert.throws(
+    () => parseConfig({ maintenance: [] }),
+    /maintenance must be a plain object/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: "off" }),
+    /maintenance must be a plain object/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: [], maintenanceNamespaceFanoutEnabled: false }),
+    /maintenance must be a plain object/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: { namespaceFanoutEnabled: "flase" } }),
+    /maintenance\.namespaceFanoutEnabled must be a boolean-like value/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: { maxNamespacesPerCycle: 0 } }),
+    /maintenance\.maxNamespacesPerCycle must be a positive integer/,
+  );
+  assert.throws(
+    () => parseConfig({ maintenance: { namespaceLockStaleMs: 1.5 } }),
+    /maintenance\.namespaceLockStaleMs must be a positive integer/,
+  );
+});

package/src/config.ts

@@ -19,6 +19,10 @@ import type {
   RecallPipelineConfig,
   RecallSectionConfig,
   ReasoningEffort,
+  ScopeProfileConfig,
+  ScopeProfileLayerId,
+  ScopeProfilePromotionTarget,
+  ScopeTeamConfig,
   SemanticChunkingConfigShape,
   SessionObserverBandConfig,
   SlotBehaviorConfig,
@@ -59,6 +63,263 @@ const LEGACY_ACTIVE_RECALL_CUSTOM_FIELD = [
   "Prompt",
   "Override",
 ].join("") as "activeRecallPromptOverride";
+const SCOPE_PROFILE_LAYER_IDS = [
+  "userProject",
+  "teamProject",
+  "userGlobal",
+  "serverShared",
+] as const satisfies readonly ScopeProfileLayerId[];
+const SCOPE_PROFILE_PROMOTION_TARGETS = [
+  ...SCOPE_PROFILE_LAYER_IDS,
+] as const satisfies readonly ScopeProfilePromotionTarget[];
+const SCOPE_PROFILE_AUTO_PROMOTE_CATEGORIES = [
+  "fact",
+  "correction",
+  "decision",
+  "preference",
+  "rule",
+  "procedure",
+] as const;
+const CONFIDENCE_TIERS = [
+  "explicit",
+  "implied",
+  "inferred",
+  "speculative",
+] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseStringList(value: unknown, keyName: string): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(keyName + " must be an array");
+  }
+  const out: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string" || entry.length === 0) {
+      throw new Error(keyName + " must contain only non-empty strings");
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+function parseScopeProfileLayerList(
+  value: unknown,
+  keyName: string,
+  fallback: ScopeProfileLayerId[],
+): ScopeProfileLayerId[] {
+  if (value === undefined || value === null) return [...fallback];
+  if (!Array.isArray(value)) {
+    throw new Error(`${keyName} must be an array`);
+  }
+  const out: ScopeProfileLayerId[] = [];
+  for (const entry of value) {
+    if (!SCOPE_PROFILE_LAYER_IDS.includes(entry as ScopeProfileLayerId)) {
+      throw new Error(`${keyName} contains unsupported layer: ${String(entry)}`);
+    }
+    if (!out.includes(entry as ScopeProfileLayerId)) {
+      out.push(entry as ScopeProfileLayerId);
+    }
+  }
+  return out;
+}
+
+function parseScopeProfilePromotionTargets(
+  value: unknown,
+  keyName: string,
+): ScopeProfilePromotionTarget[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${keyName} must be an array`);
+  }
+  const out: ScopeProfilePromotionTarget[] = [];
+  for (const entry of value) {
+    if (!SCOPE_PROFILE_PROMOTION_TARGETS.includes(entry as ScopeProfilePromotionTarget)) {
+      throw new Error(`${keyName} contains unsupported target: ${String(entry)}`);
+    }
+    if (!out.includes(entry as ScopeProfilePromotionTarget)) {
+      out.push(entry as ScopeProfilePromotionTarget);
+    }
+  }
+  return out;
+}
+
+function parseScopeProfiles(value: unknown): Record<string, ScopeProfileConfig> {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) {
+    throw new Error("scopeProfiles must be an object");
+  }
+  const profiles: Record<string, ScopeProfileConfig> = {};
+  for (const [profileId, rawProfile] of Object.entries(value)) {
+    if (profileId.trim().length === 0) {
+      throw new Error("scopeProfiles keys must not be empty");
+    }
+    if (!isRecord(rawProfile)) {
+      throw new Error(`scopeProfiles.${profileId} must be an object`);
+    }
+    const readOrder = parseScopeProfileLayerList(
+      rawProfile.readOrder,
+      `scopeProfiles.${profileId}.readOrder`,
+      ["userProject", "userGlobal", "serverShared"],
+    );
+    const writeDefault =
+      rawProfile.writeDefault === undefined || rawProfile.writeDefault === null
+        ? "userProject"
+        : rawProfile.writeDefault;
+    if (!SCOPE_PROFILE_LAYER_IDS.includes(writeDefault as ScopeProfileLayerId)) {
+      throw new Error(`scopeProfiles.${profileId}.writeDefault contains unsupported layer: ${String(writeDefault)}`);
+    }
+    if (
+      rawProfile.teamProject !== undefined &&
+      rawProfile.teamProject !== null &&
+      !isRecord(rawProfile.teamProject)
+    ) {
+      throw new Error("scopeProfiles." + profileId + ".teamProject must be an object");
+    }
+    const teamProject = (() => {
+      if (!isRecord(rawProfile.teamProject)) return undefined;
+      const out: NonNullable<ScopeProfileConfig["teamProject"]> = {};
+      if (rawProfile.teamProject.namespaceTemplate !== undefined) {
+        if (
+          typeof rawProfile.teamProject.namespaceTemplate !== "string" ||
+          rawProfile.teamProject.namespaceTemplate.length === 0
+        ) {
+          throw new Error(
+            `scopeProfiles.${profileId}.teamProject.namespaceTemplate must be a non-empty string`,
+          );
+        }
+        out.namespaceTemplate = rawProfile.teamProject.namespaceTemplate;
+      }
+      if (rawProfile.teamProject.teamId !== undefined) {
+        if (
+          typeof rawProfile.teamProject.teamId !== "string" ||
+          rawProfile.teamProject.teamId.length === 0
+        ) {
+          throw new Error(
+            `scopeProfiles.${profileId}.teamProject.teamId must be a non-empty string`,
+          );
+        }
+        out.teamId = rawProfile.teamProject.teamId;
+      }
+      return out;
+    })();
+    if (
+      rawProfile.autoPromote !== undefined &&
+      rawProfile.autoPromote !== null &&
+      !isRecord(rawProfile.autoPromote)
+    ) {
+      throw new Error(`scopeProfiles.${profileId}.autoPromote must be an object`);
+    }
+    const rawAutoPromote = isRecord(rawProfile.autoPromote) ? rawProfile.autoPromote : {};
+    const hasAutoPromoteEnabled = Object.prototype.hasOwnProperty.call(
+      rawAutoPromote,
+      "enabled",
+    );
+    const autoPromoteEnabled = coerceBool(rawAutoPromote.enabled);
+    if (hasAutoPromoteEnabled && autoPromoteEnabled === undefined) {
+      throw new Error(
+        `scopeProfiles.${profileId}.autoPromote.enabled must be a boolean or boolean-like string`,
+      );
+    }
+    const minConfidenceTier = (() => {
+      const rawTier = rawAutoPromote.minConfidenceTier;
+      if (rawTier === undefined || rawTier === null) return "explicit";
+      if (typeof rawTier !== "string" || !CONFIDENCE_TIERS.includes(rawTier as any)) {
+        throw new Error(
+          `scopeProfiles.${profileId}.autoPromote.minConfidenceTier must be one of: ${CONFIDENCE_TIERS.join(", ")}`,
+        );
+      }
+      return rawTier as typeof CONFIDENCE_TIERS[number];
+    })();
+    const autoPromoteCategories: Array<typeof SCOPE_PROFILE_AUTO_PROMOTE_CATEGORIES[number]> = (() => {
+      if (rawAutoPromote.categories === undefined || rawAutoPromote.categories === null) {
+        return ["fact", "correction", "decision", "preference"];
+      }
+      if (!Array.isArray(rawAutoPromote.categories)) {
+        throw new Error(
+          `scopeProfiles.${profileId}.autoPromote.categories must be an array`,
+        );
+      }
+      const categories: Array<typeof SCOPE_PROFILE_AUTO_PROMOTE_CATEGORIES[number]> = [];
+      for (const entry of rawAutoPromote.categories) {
+        if (typeof entry !== "string" || !SCOPE_PROFILE_AUTO_PROMOTE_CATEGORIES.includes(entry as any)) {
+          throw new Error(
+            "scopeProfiles." + profileId + ".autoPromote.categories must contain only: " +
+              SCOPE_PROFILE_AUTO_PROMOTE_CATEGORIES.join(", "),
+          );
+        }
+        categories.push(entry as typeof SCOPE_PROFILE_AUTO_PROMOTE_CATEGORIES[number]);
+      }
+      return categories;
+    })();
+    profiles[profileId] = {
+      readOrder,
+      writeDefault: writeDefault as ScopeProfileLayerId,
+      promotionTargets: parseScopeProfilePromotionTargets(
+        rawProfile.promotionTargets,
+        `scopeProfiles.${profileId}.promotionTargets`,
+      ),
+      ...(teamProject && Object.keys(teamProject).length > 0 ? { teamProject } : {}),
+      autoPromote: {
+        enabled: autoPromoteEnabled === true,
+        targets: parseScopeProfilePromotionTargets(
+          rawAutoPromote.targets,
+          `scopeProfiles.${profileId}.autoPromote.targets`,
+        ),
+        categories: autoPromoteCategories,
+        minConfidenceTier,
+      },
+    };
+  }
+  return profiles;
+}
+
+function parseScopeTeams(value: unknown): Record<string, ScopeTeamConfig> {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) {
+    throw new Error("teams must be an object");
+  }
+  const teams: Record<string, ScopeTeamConfig> = {};
+  for (const [teamId, rawTeam] of Object.entries(value)) {
+    if (teamId.trim().length === 0) {
+      throw new Error("teams keys must not be empty");
+    }
+    if (!isRecord(rawTeam)) {
+      throw new Error(`teams.${teamId} must be an object`);
+    }
+    const projectNamespaceTemplate = rawTeam.projectNamespaceTemplate;
+    if (projectNamespaceTemplate !== undefined) {
+      if (typeof projectNamespaceTemplate !== "string" || projectNamespaceTemplate.length === 0) {
+        throw new Error(`teams.${teamId}.projectNamespaceTemplate must be a non-empty string`);
+      }
+    }
+    teams[teamId] = {
+      principals: parseStringList(rawTeam.principals, `teams.${teamId}.principals`),
+      ...(projectNamespaceTemplate !== undefined ? { projectNamespaceTemplate } : {}),
+      read: parseStringList(rawTeam.read, `teams.${teamId}.read`),
+      write: parseStringList(rawTeam.write, `teams.${teamId}.write`),
+      promote: parseStringList(rawTeam.promote, `teams.${teamId}.promote`),
+    };
+  }
+  return teams;
+}
+
+function validateScopeProfileTeamReferences(
+  profiles: Record<string, ScopeProfileConfig>,
+  teams: Record<string, ScopeTeamConfig>,
+): void {
+  for (const [profileId, profile] of Object.entries(profiles)) {
+    const teamId = profile.teamProject?.teamId;
+    if (teamId && !Object.prototype.hasOwnProperty.call(teams, teamId)) {
+      throw new Error(
+        `scopeProfiles.${profileId}.teamProject.teamId references unknown team: ${teamId}`,
+      );
+    }
+  }
+}
 
 function parseBoundedIntegerMs(
   value: unknown,
@@ -405,6 +666,74 @@ function resolveNamespaceCatalogEnabled(configValue: unknown): boolean {
   return true;
 }
 
+function readNestedConfig(
+  cfg: Record<string, unknown>,
+  blockName: string,
+  key: string,
+): unknown {
+  const block = validateNestedConfigBlock(cfg, blockName);
+  if (!block) return undefined;
+  return block[key];
+}
+
+function validateNestedConfigBlock(
+  cfg: Record<string, unknown>,
+  blockName: string,
+): Record<string, unknown> | undefined {
+  const block = cfg[blockName];
+  if (block === undefined || block === null) return undefined;
+  if (typeof block !== "object" || Array.isArray(block)) {
+    throw new Error(`${blockName} must be a plain object`);
+  }
+  return block as Record<string, unknown>;
+}
+
+function readFlatOrNestedConfig(
+  cfg: Record<string, unknown>,
+  flatKey: string,
+  blockName: string,
+  nestedKey: string,
+): unknown {
+  return cfg[flatKey] !== undefined
+    ? cfg[flatKey]
+    : readNestedConfig(cfg, blockName, nestedKey);
+}
+
+function resolveBooleanConfig(
+  value: unknown,
+  defaultValue: boolean,
+  keyName: string,
+): boolean {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `${keyName} must be a boolean-like value (true/false/1/0/yes/no/on/off); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function resolvePositiveIntegerConfig(
+  value: unknown,
+  defaultValue: number,
+  keyName: string,
+): number {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceNumber(value);
+  if (
+    coerced === undefined ||
+    !Number.isFinite(coerced) ||
+    !Number.isInteger(coerced) ||
+    coerced < 1
+  ) {
+    throw new Error(
+      `${keyName} must be a positive integer; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
 export function isOpenaiApiKeyDisabled(value: unknown): boolean {
   return value === false || (typeof value === "string" && value.trim().toLowerCase() === "false");
 }
@@ -768,6 +1097,7 @@ export function parseConfig(raw: unknown): PluginConfig {
   } else {
     cfg = baseCfg;
   }
+  validateNestedConfigBlock(cfg, "maintenance");
 
   const modelSource =
     cfg.modelSource === "gateway" ? "gateway" : "plugin";
@@ -1212,6 +1542,24 @@ export function parseConfig(raw: unknown): PluginConfig {
     typeof cfg.memoryDir === "string" && cfg.memoryDir.length > 0
       ? expandTildePath(cfg.memoryDir)
       : DEFAULT_MEMORY_DIR;
+  const scopeProfiles = parseScopeProfiles(cfg.scopeProfiles);
+  const teams = parseScopeTeams(cfg.teams);
+  validateScopeProfileTeamReferences(scopeProfiles, teams);
+  const defaultScopeProfile = (() => {
+    if (cfg.defaultScopeProfile === undefined || cfg.defaultScopeProfile === null) {
+      return undefined;
+    }
+    if (typeof cfg.defaultScopeProfile !== "string" || cfg.defaultScopeProfile.trim().length === 0) {
+      throw new Error("defaultScopeProfile must be a non-empty string");
+    }
+    return cfg.defaultScopeProfile.trim();
+  })();
+  if (
+    defaultScopeProfile !== undefined &&
+    scopeProfiles[defaultScopeProfile] === undefined
+  ) {
+    throw new Error(`defaultScopeProfile references unknown scope profile: ${defaultScopeProfile}`);
+  }
   const rawIdentityInjectionMode = cfg.identityInjectionMode as string | undefined;
   const identityInjectionMode: IdentityInjectionMode =
     rawIdentityInjectionMode
@@ -1482,6 +1830,66 @@ export function parseConfig(raw: unknown): PluginConfig {
         ? Math.max(1, Math.floor(cfg.crossSignalsSemanticTimeoutMs))
         : 4000;
   const recallPipelineConfig = buildRecallPipelineConfig(cfg);
+  const maintenanceNamespaceFanoutEnabled = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceNamespaceFanoutEnabled",
+      "maintenance",
+      "namespaceFanoutEnabled",
+    ),
+    true,
+    "maintenance.namespaceFanoutEnabled",
+  );
+  const maintenanceMaxNamespacesPerCycle = resolvePositiveIntegerConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceMaxNamespacesPerCycle",
+      "maintenance",
+      "maxNamespacesPerCycle",
+    ),
+    20,
+    "maintenance.maxNamespacesPerCycle",
+  );
+  const maintenanceIncludeProjectNamespaces = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceIncludeProjectNamespaces",
+      "maintenance",
+      "includeProjectNamespaces",
+    ),
+    true,
+    "maintenance.includeProjectNamespaces",
+  );
+  const maintenanceIncludeBranchNamespaces = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceIncludeBranchNamespaces",
+      "maintenance",
+      "includeBranchNamespaces",
+    ),
+    false,
+    "maintenance.includeBranchNamespaces",
+  );
+  const maintenanceIncludeTeamProjectNamespaces = resolveBooleanConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceIncludeTeamProjectNamespaces",
+      "maintenance",
+      "includeTeamProjectNamespaces",
+    ),
+    true,
+    "maintenance.includeTeamProjectNamespaces",
+  );
+  const maintenanceNamespaceLockStaleMs = resolvePositiveIntegerConfig(
+    readFlatOrNestedConfig(
+      cfg,
+      "maintenanceNamespaceLockStaleMs",
+      "maintenance",
+      "namespaceLockStaleMs",
+    ),
+    10 * 60_000,
+    "maintenance.namespaceLockStaleMs",
+  );
 
   return {
     openaiApiKey: apiKey,
@@ -2546,6 +2954,12 @@ export function parseConfig(raw: unknown): PluginConfig {
     qmdMaintenanceEnabled: cfg.qmdMaintenanceEnabled !== false,
     qmdMaintenanceDebounceMs:
       typeof cfg.qmdMaintenanceDebounceMs === "number" ? cfg.qmdMaintenanceDebounceMs : 30_000,
+    maintenanceNamespaceFanoutEnabled,
+    maintenanceMaxNamespacesPerCycle,
+    maintenanceIncludeProjectNamespaces,
+    maintenanceIncludeBranchNamespaces,
+    maintenanceIncludeTeamProjectNamespaces,
+    maintenanceNamespaceLockStaleMs,
     qmdAutoEmbedEnabled: cfg.qmdAutoEmbedEnabled === true,
     qmdEmbedMinIntervalMs:
       typeof cfg.qmdEmbedMinIntervalMs === "number" ? cfg.qmdEmbedMinIntervalMs : 60 * 60_000,
@@ -2642,6 +3056,9 @@ export function parseConfig(raw: unknown): PluginConfig {
         })).filter((p) => p.name.length > 0)
       : [],
     defaultRecallNamespaces: Array.isArray(cfg.defaultRecallNamespaces) ? ["self", "shared"].filter((x) => (cfg.defaultRecallNamespaces as any[]).includes(x)) as any : ["self", "shared"],
+    scopeProfiles,
+    defaultScopeProfile,
+    teams,
     cronRecallMode:
       cfg.cronRecallMode === "none"
         ? "none"

package/src/lcm-fallback-read.ts

@@ -57,10 +57,7 @@ const UNDEFINED_SESSION_SENTINEL = " <lcm-sessionless>";
 export function resolveLcmReadSessionIds(
   target: LcmReadSessionTarget,
 ): Array<string | undefined> {
-  const source =
-    target.sessionIds && target.sessionIds.length > 0
-      ? target.sessionIds
-      : [target.sessionId];
+  const source = target.sessionIds !== undefined ? target.sessionIds : [target.sessionId];
   const seen = new Set<string>();
   const out: Array<string | undefined> = [];
   for (const sessionId of source) {
@@ -69,8 +66,7 @@ export function resolveLcmReadSessionIds(
     seen.add(key);
     out.push(sessionId);
   }
-  // Defensive: an all-empty `sessionIds` still collapses to the single-key path.
-  return out.length > 0 ? out : [target.sessionId];
+  return out;
 }
 
 /**