@remnic/core 9.3.725 → 9.3.727

package/src/admin/admin-surfaces.test.ts

@@ -13,6 +13,7 @@ import path from "node:path";
 import test from "node:test";
 
 import { NamespaceCatalog } from "../namespaces/catalog.js";
+import { resolveScopeProfilePlan } from "../namespaces/scope-profiles.js";
 import { parseConfig } from "../config.js";
 import {
   AdminPromotionError,
@@ -456,3 +457,291 @@ test("promoteMemory throws source_not_found when the source memory is absent", a
     (err: unknown) => err instanceof AdminPromotionError && err.code === "source_not_found",
   );
 });
+
+// ---------------------------------------------------------------------------
+// gatherMaintenanceHealth — honest QMD state classification (issue #1658 thread 1)
+// ---------------------------------------------------------------------------
+
+/** Build a QMD health snapshot fixture for the provider. */
+function qmdFixture(namespace: string, overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    namespace,
+    collection: `col-${namespace}`,
+    available: true,
+    collectionState: "present",
+    debugStatus: "ok",
+    installedVersion: "1.0.0",
+    supportedVersion: "1.0.0",
+    supported: true,
+    upgradeAvailable: false,
+    daemonMode: false,
+    ...overrides,
+  };
+}
+
+test("gatherMaintenanceHealth classifies a present QMD collection as healthy (issue #1658 thread 1)", async () => {
+  const memoryDir = await makeTempDir();
+  try {
+    const config = makeConfig({ memoryDir });
+    const catalog = new NamespaceCatalog(config);
+    await catalog.registerConfiguredNamespaces();
+    const report = await gatherMaintenanceHealth({
+      catalog,
+      qmdHealthProvider: async (ns) => qmdFixture(ns, { collectionState: "present" }),
+    });
+    assert.equal(report.degradedMode, false);
+    const entry = report.perNamespace.find((e) => e.namespace === "default");
+    assert.ok(entry, "default namespace entry must exist");
+    assert.equal(entry!.qmdState, "healthy");
+    assert.equal(entry!.qmdDegraded, false);
+    assert.match(entry!.qmdStateReason, /ready/i);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gatherMaintenanceHealth classifies an unknown collection state distinctly from missing (issue #1658 thread 1)", async () => {
+  const memoryDir = await makeTempDir();
+  try {
+    const config = makeConfig({ memoryDir });
+    const catalog = new NamespaceCatalog(config);
+    await catalog.registerConfiguredNamespaces();
+    const report = await gatherMaintenanceHealth({
+      catalog,
+      qmdHealthProvider: async (ns) => qmdFixture(ns, { collectionState: "unknown" }),
+    });
+    // "unknown" is still counted degraded (matches the router health path) so
+    // aggregate alerting is unchanged, but it is now RENDERED honestly as a
+    // distinct state rather than collapsed into "missing".
+    assert.equal(report.degradedMode, true);
+    const entry = report.perNamespace.find((e) => e.namespace === "default");
+    assert.ok(entry);
+    assert.equal(entry!.qmdState, "unknown");
+    assert.equal(entry!.qmdDegraded, true);
+    assert.match(entry!.qmdStateReason, /transient/i);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gatherMaintenanceHealth classifies a missing collection as an actionable state (issue #1658 thread 1)", async () => {
+  const memoryDir = await makeTempDir();
+  try {
+    const config = makeConfig({ memoryDir });
+    const catalog = new NamespaceCatalog(config);
+    await catalog.registerConfiguredNamespaces();
+    const report = await gatherMaintenanceHealth({
+      catalog,
+      qmdHealthProvider: async (ns) => qmdFixture(ns, { collectionState: "missing" }),
+    });
+    const entry = report.perNamespace.find((e) => e.namespace === "default");
+    assert.ok(entry);
+    assert.equal(entry!.qmdState, "missing");
+    assert.equal(entry!.qmdDegraded, true);
+    assert.match(entry!.qmdStateReason, /not built|index/i);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gatherMaintenanceHealth classifies an unavailable backend distinctly (issue #1658 thread 1)", async () => {
+  const memoryDir = await makeTempDir();
+  try {
+    const config = makeConfig({ memoryDir });
+    const catalog = new NamespaceCatalog(config);
+    await catalog.registerConfiguredNamespaces();
+    const report = await gatherMaintenanceHealth({
+      catalog,
+      qmdHealthProvider: async (ns) => qmdFixture(ns, { available: false, collectionState: "unknown" }),
+    });
+    const entry = report.perNamespace.find((e) => e.namespace === "default");
+    assert.ok(entry);
+    assert.equal(entry!.qmdState, "unavailable");
+    assert.equal(entry!.qmdDegraded, true);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("gatherMaintenanceHealth reports not_probed when no provider is supplied (issue #1658 thread 1)", async () => {
+  const memoryDir = await makeTempDir();
+  try {
+    const config = makeConfig({ memoryDir });
+    const catalog = new NamespaceCatalog(config);
+    await catalog.registerConfiguredNamespaces();
+    const report = await gatherMaintenanceHealth({ catalog });
+    const entry = report.perNamespace.find((e) => e.namespace === "default");
+    assert.ok(entry);
+    assert.equal(entry!.qmdState, "not_probed");
+    assert.equal(entry!.qmdDegraded, false);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// promoteMemory — honest project-context promotion reasons (issue #1658 thread 2)
+// ---------------------------------------------------------------------------
+
+test("promoteMemory reports an honest 'no active scope profile' reason for a project target without a profile (issue #1658 thread 2)", async () => {
+  const config = makeConfig();
+  const storage = makeMemoryStorageProvider();
+  const result = await promoteMemory({
+    config,
+    sourceMemoryId: "mem-1",
+    sourceNamespace: "default",
+    principal: "alice",
+    targets: [{ kind: "userProject" }],
+    reason: "promote project fact",
+    actor: "alice",
+    storage,
+    // scopeProfilePlan omitted → no active profile.
+  });
+  assert.equal(result.ok, false);
+  const target = result.targets[0]!;
+  assert.equal(target.authorized, false);
+  assert.equal(target.namespace, "");
+  assert.match(target.reason, /no active scope profile/);
+  assert.match(target.reason, /coding context/i);
+  assert.equal(storage.written.length, 0);
+});
+
+test("promoteMemory reports an honest 'no active scope profile' reason for a non-project target without a profile (issue #1658 thread 2)", async () => {
+  const config = makeConfig();
+  const storage = makeMemoryStorageProvider();
+  const result = await promoteMemory({
+    config,
+    sourceMemoryId: "mem-1",
+    sourceNamespace: "default",
+    principal: "alice",
+    targets: [{ kind: "serverShared" }],
+    reason: "promote shared fact",
+    actor: "alice",
+    storage,
+  });
+  assert.equal(result.ok, false);
+  const target = result.targets[0]!;
+  assert.match(target.reason, /no active scope profile/);
+  // Non-project targets must NOT mention coding context.
+  assert.doesNotMatch(target.reason, /coding context/i);
+});
+
+test("promoteMemory surfaces the profile layer's 'missing project context' reason when a project target is configured but unresolvable (issue #1658 thread 2)", async () => {
+  const config = makeConfig({
+    defaultScopeProfile: "team",
+    scopeProfiles: {
+      team: {
+        readOrder: ["userGlobal"],
+        writeDefault: "userGlobal",
+        promotionTargets: ["userProject"],
+        autoPromote: { enabled: false, targets: [], categories: ["fact"], minConfidenceTier: "speculative" },
+      },
+    },
+    principalFromSessionKeyMode: "prefix",
+    principalFromSessionKeyRules: [{ match: "alice:", principal: "alice" }],
+    namespacePolicies: [{ name: "alice", readPrincipals: ["alice"], writePrincipals: ["alice"] }],
+  });
+  // No coding context → the userProject layer resolves "missing project context".
+  const scopeProfilePlan = resolveScopeProfilePlan({
+    config,
+    principal: "alice",
+    codingContext: null,
+    codingOverlay: null,
+  });
+  assert.ok(scopeProfilePlan, "scope profile must be active for this config");
+  const storage = makeMemoryStorageProvider();
+  const result = await promoteMemory({
+    config,
+    sourceMemoryId: "mem-1",
+    sourceNamespace: "alice",
+    principal: "alice",
+    targets: [{ kind: "userProject" }],
+    reason: "promote project fact",
+    actor: "alice",
+    storage,
+    scopeProfilePlan,
+  });
+  assert.equal(result.ok, false);
+  const target = result.targets[0]!;
+  assert.equal(target.authorized, false);
+  assert.match(target.reason, /missing project context/i);
+});
+
+// ---------------------------------------------------------------------------
+// inspectScope — read-only override honest warning (issue #1658 thread 6)
+// ---------------------------------------------------------------------------
+
+test("inspectScope warns when an explicit override is readable but not writable (issue #1658 thread 6)", () => {
+  const config = makeConfig({
+    principalFromSessionKeyMode: "prefix",
+    principalFromSessionKeyRules: [{ match: "alice:", principal: "alice" }],
+    namespacePolicies: [
+      // alice can READ "audit-log" but cannot WRITE it.
+      { name: "audit-log", readPrincipals: ["alice", "bob"], writePrincipals: ["bob"] },
+      { name: "alice", readPrincipals: ["alice"], writePrincipals: ["alice"] },
+    ],
+  });
+  const inspection = inspectScope({
+    config,
+    sessionKey: "alice:bot:x:1",
+    namespace: "audit-log",
+  });
+  // The override is readable → it becomes the effective write namespace...
+  assert.equal(inspection.namespaceOverride, "audit-log");
+  assert.equal(inspection.writeNamespace, "audit-log");
+  // ...but alice cannot write it → an honest warning must surface the mismatch.
+  assert.ok(
+    inspection.warnings.some(
+      (w) => w.includes("audit-log") && w.includes("not writable") && w.includes("writes will be rejected"),
+    ),
+    "expected a read-only-override warning; got: " + JSON.stringify(inspection.warnings),
+  );
+});
+
+test("inspectScope does not warn when an explicit override is writable (issue #1658 thread 6)", () => {
+  const config = makeConfig({
+    principalFromSessionKeyMode: "prefix",
+    principalFromSessionKeyRules: [{ match: "alice:", principal: "alice" }],
+    namespacePolicies: [
+      { name: "shared", readPrincipals: ["alice"], writePrincipals: ["alice"] },
+      { name: "alice", readPrincipals: ["alice"], writePrincipals: ["alice"] },
+    ],
+  });
+  const inspection = inspectScope({
+    config,
+    sessionKey: "alice:bot:x:1",
+    namespace: "shared",
+  });
+  assert.equal(inspection.namespaceOverride, "shared");
+  assert.ok(
+    !inspection.warnings.some((w) => w.includes("not writable")),
+    "no read-only-override warning expected for a writable override",
+  );
+});
+
+test("gatherMaintenanceHealth preserves the original qmdDegraded invariant for an unrecognized collectionState (issue #1658 thread 1)", async () => {
+  // The original degraded formula was: !available || "missing" || "unknown".
+  // An available backend with any OTHER collectionState (present/skipped/and any
+  // unrecognized value) was NOT degraded. The classified qmdState surfaces the
+  // unrecognized value honestly, but the degraded bit must stay false so the
+  // aggregate alerting invariant is byte-for-byte unchanged.
+  const memoryDir = await makeTempDir();
+  try {
+    const config = makeConfig({ memoryDir });
+    const catalog = new NamespaceCatalog(config);
+    await catalog.registerConfiguredNamespaces();
+    const report = await gatherMaintenanceHealth({
+      catalog,
+      qmdHealthProvider: async (ns) =>
+        qmdFixture(ns, { collectionState: "future-state" }),
+    });
+    const entry = report.perNamespace.find((e) => e.namespace === "default");
+    assert.ok(entry);
+    assert.equal(entry!.qmdDegraded, false, "unrecognized collectionState must not flip degraded (unchanged semantics)");
+    assert.equal(entry!.qmdState, "unknown");
+    assert.match(entry!.qmdStateReason, /unrecognized collection state 'future-state'/);
+    assert.equal(report.degradedMode, false);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/admin/admin-surfaces.ts

@@ -213,6 +213,17 @@ export function inspectScope(options: InspectScopeOptions): ScopeInspection {
       `requested namespace override '${options.namespace}' is not readable by this principal and was ignored`
     );
   }
+  // Issue #1658 thread 6: when an explicit namespace override is readable but
+  // NOT writable, it still becomes the effective write namespace (baseNamespace
+  // in the scope plan). Surface the mismatch honestly so the operator knows
+  // writes will be rejected rather than reading writeNamespace as a usable
+  // target. (The per-layer writable flag already records this, but the
+  // top-level writeNamespace field does not.)
+  if (plan.namespaceOverride && !canWriteNamespace(plan.principal, plan.namespaceOverride, config)) {
+    warnings.push(
+      `explicit namespace override '${plan.namespaceOverride}' is readable but not writable by this principal; it is the effective write namespace but writes will be rejected`
+    );
+  }
 
   const layers: ScopeInspectionLayer[] = [];
   const scopeProfilePlan = plan.scopeProfilePlan;
@@ -417,6 +428,27 @@ function toAdminEntry(record: NamespaceRecord, staleBefore: Date): AdminNamespac
 // Maintenance and QMD health
 // ---------------------------------------------------------------------------
 
+/**
+ * Honest, distinguishable classification of a namespace's QMD/search health
+ * (issue #1658 thread 1). A single `qmdDegraded` bit collapses the legitimate
+ * transient "unknown" (QMD reachable but collection status not yet populated,
+ * normal during startup/reindex) together with the actionable "missing"
+ * (collection not built — operator must act) and "unavailable" (backend down).
+ * Surfacing a classified state lets the dashboard render each case honestly
+ * instead of a flat degraded flag or a silent blank.
+ */
+export type AdminNamespaceQmdState =
+  /** Backend reachable and collection present (or intentionally skipped). */
+  | "healthy"
+  /** Backend reachable but collection status not yet determined (transient). */
+  | "unknown"
+  /** Backend reachable but the collection is not built for this namespace. */
+  | "missing"
+  /** Backend unreachable / probe threw. */
+  | "unavailable"
+  /** No QMD probe was run for this report (provider omitted or returned null). */
+  | "not_probed";
+
 /** QMD/search health snapshot for one namespace (delegated to NamespaceSearchRouter). */
 export interface AdminNamespaceQmdHealth {
   namespace: string;
@@ -438,8 +470,20 @@ export interface AdminNamespaceHealth {
   lastMaintenanceAt?: Record<string, string>;
   /** True when no maintenance has ever been recorded. */
   maintenanceMissing: boolean;
-  /** True when QMD is unavailable OR its collection is missing for this namespace. */
+  /**
+   * True when QMD is unavailable OR its collection is missing/unknown for this
+   * namespace. Matches the NamespaceSearchRouter health path so the aggregate
+   * `degradedMode` flag stays consistent with runtime alerting.
+   */
   qmdDegraded: boolean;
+  /**
+   * Honest, distinguishable QMD state (issue #1658 thread 1). Complements
+   * `qmdDegraded` so the dashboard can render "unknown" (transient) separately
+   * from "missing"/"unavailable" (action needed) instead of a flat bit.
+   */
+  qmdState: AdminNamespaceQmdState;
+  /** Human-readable explanation of {@link qmdState}, safe to show operators. */
+  qmdStateReason: string;
   qmd?: AdminNamespaceQmdHealth;
   /** Reason the QMD probe failed, when it did. */
   qmdError?: string;
@@ -473,6 +517,66 @@ export interface MaintenanceHealthOptions {
  * timestamps from the catalog and (optionally) QMD diagnostics from the
  * injected provider.
  */
+/**
+ * Classify a QMD health snapshot into an honest, distinguishable state bucket
+ * (issue #1658 thread 1). The `degraded` bit mirrors the NamespaceSearchRouter
+ * health path (unavailable / missing / unknown) so the aggregate `degradedMode`
+ * flag and any downstream alerting stay consistent; the classified `state` +
+ * `reason` let the dashboard render each case distinctly instead of a flat bit.
+ */
+function classifyQmdState(qmd: AdminNamespaceQmdHealth): {
+  state: AdminNamespaceQmdState;
+  reason: string;
+  degraded: boolean;
+} {
+  if (!qmd.available) {
+    return {
+      state: "unavailable",
+      reason: "QMD backend is unavailable for this namespace",
+      degraded: true,
+    };
+  }
+  // collectionState is the router's string ("present" | "missing" | "unknown"
+  // | "skipped"); classify defensively — an unrecognized value is reported as
+  // "unknown" rather than silently treated as healthy.
+  switch (qmd.collectionState) {
+    case "present":
+      return { state: "healthy", reason: "QMD collection is ready", degraded: false };
+    case "skipped":
+      // "skipped" means QMD is intentionally disabled for this namespace; it is
+      // neither degraded nor a blank — surface it honestly as healthy/idle.
+      return {
+        state: "healthy",
+        reason: "QMD is skipped for this namespace (intentionally disabled)",
+        degraded: false,
+      };
+    case "missing":
+      return {
+        state: "missing",
+        reason: "QMD collection is not built for this namespace — add the collection to the QMD index",
+        degraded: true,
+      };
+    case "unknown":
+      return {
+        state: "unknown",
+        reason: "QMD collection status could not be determined (transient during startup/reindex)",
+        degraded: true,
+      };
+    default:
+      // Preserve the ORIGINAL qmdDegraded invariant exactly: an available
+      // backend with an unrecognized collectionState was NOT degraded before
+      // this PR (the pre-image only flagged missing/unknown/unavailable). We
+      // still surface the unrecognized value HONESTLY via state/reason so the
+      // dashboard can render it, but we do not flip the degraded bit — that
+      // would change alerting and contradict the "unchanged semantics" claim.
+      return {
+        state: "unknown",
+        reason: `QMD reported an unrecognized collection state '${qmd.collectionState}'`,
+        degraded: false,
+      };
+  }
+}
+
 export async function gatherMaintenanceHealth(options: MaintenanceHealthOptions): Promise<MaintenanceHealthReport> {
   const { catalog, qmdHealthProvider } = options;
   if (!catalog.enabled) {
@@ -488,22 +592,32 @@ export async function gatherMaintenanceHealth(options: MaintenanceHealthOptions)
         lastMaintenanceAt: record.lastMaintenanceAt,
         maintenanceMissing: !record.lastMaintenanceAt || Object.keys(record.lastMaintenanceAt).length === 0,
         qmdDegraded: false,
+        qmdState: "not_probed",
+        qmdStateReason: "QMD health probe not run for this report",
       };
       if (qmdHealthProvider) {
         try {
           const qmd = await qmdHealthProvider(record.namespace);
           if (qmd) {
             entry.qmd = qmd;
-            entry.qmdDegraded =
-    !qmd.available ||
-    qmd.collectionState === "missing" ||
-    qmd.collectionState === "unknown";
+            // Classify the collection state into an honest, distinguishable
+            // bucket (issue #1658 thread 1) and derive the degraded bit from
+            // the same inputs the NamespaceSearchRouter health path uses.
+            const classified = classifyQmdState(qmd);
+            entry.qmdState = classified.state;
+            entry.qmdStateReason = classified.reason;
+            entry.qmdDegraded = classified.degraded;
+          } else {
+            entry.qmdState = "not_probed";
+            entry.qmdStateReason = "QMD health not available for this namespace";
           }
         } catch (err) {
-          entry.qmdDegraded = true;
           // Sanitize: never echo raw error messages to the dashboard. The
           // generic diagnostic is sufficient for operators; the full error
           // is logged by the qmdHealthProvider's caller (access-service).
+          entry.qmdDegraded = true;
+          entry.qmdState = "unavailable";
+          entry.qmdStateReason = "QMD health probe failed";
           entry.qmdError = "QMD health probe failed";
         }
       }
@@ -735,7 +849,24 @@ export async function promoteMemory(options: PromoteMemoryOptions): Promise<Memo
           : "explicit namespace is not writable by this principal",
       };
     }
-    const layer = scopeProfilePlan?.promotionTargets.find((t) => t.target === requested.kind);
+    if (!scopeProfilePlan) {
+      // Issue #1658 thread 2: distinguish "no active scope profile" from
+      // "profile does not configure this target". A project-scoped target
+      // (userProject/teamProject) cannot resolve without an active profile +
+      // coding context; report that honestly instead of a generic "not
+      // configured" message that implies a profile is active.
+      return {
+        target: requested.kind,
+        namespace: "",
+        authorized: false,
+        promoted: false,
+        reason:
+          requested.kind === "userProject" || requested.kind === "teamProject"
+            ? `no active scope profile; '${requested.kind}' promotion requires an active scope profile with a coding context (pass a sessionKey)`
+            : `no active scope profile; '${requested.kind}' promotion requires an active scope profile`,
+      };
+    }
+    const layer = scopeProfilePlan.promotionTargets.find((t) => t.target === requested.kind);
     if (!layer) {
       return {
         target: requested.kind,