@remnic/core 9.64.0 → 9.64.2

package/src/who-knows-cli.ts

@@ -0,0 +1,96 @@
+/**
+ * Input-validation + rendering helpers for the `remnic who-knows` CLI
+ * command (issue #2057). Extracted so validation paths can be unit-tested
+ * without booting an orchestrator (same pattern as `recall-xray-cli.ts`).
+ *
+ * Rules 14 + 51: bare `--limit`, non-integer or out-of-range values, and an
+ * empty topic throw listed-options errors — never silent defaults.
+ */
+
+import {
+  validateWhoKnowsInput,
+  WHO_KNOWS_DEFAULT_LIMIT,
+  WHO_KNOWS_MAX_LIMIT,
+  type WhoKnowsResult,
+} from "./who-knows.js";
+
+export interface ParsedWhoKnowsCliOptions {
+  topic: string;
+  limit: number;
+  namespace?: string;
+  json: boolean;
+}
+
+/** Split raw argv into the positional topic and a flag bag. Value flags error when bare. */
+export function extractWhoKnowsRawArgs(rest: string[]): {
+  topic: string;
+  options: Record<string, unknown>;
+} {
+  const VALUE_FLAGS: Record<string, true> = { "--limit": true, "--namespace": true };
+  const positional: string[] = [];
+  const options: Record<string, unknown> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (token.startsWith("--")) {
+      if (token === "--json") {
+        options.json = true;
+      } else if (VALUE_FLAGS[token]) {
+        const value = rest[i + 1];
+        if (value === undefined || value.startsWith("--")) {
+          throw new Error(`who-knows: ${token} expects a value`);
+        }
+        options[token.slice(2)] = value;
+        i += 1;
+      } else {
+        throw new Error(`who-knows: unknown option ${token} (expected --limit, --namespace, or --json)`);
+      }
+    } else {
+      positional.push(token);
+    }
+  }
+  return { topic: positional.join(" ").trim(), options };
+}
+
+/** Validate the full option bag. Throws listed-options errors for bad input. */
+export function parseWhoKnowsCliOptions(rawTopic: unknown, options: Record<string, unknown>): ParsedWhoKnowsCliOptions {
+  if (typeof rawTopic !== "string" || rawTopic.trim().length === 0) {
+    throw new Error("who-knows: topic is required and must be non-empty");
+  }
+  let limit = WHO_KNOWS_DEFAULT_LIMIT;
+  if (options.limit !== undefined) {
+    const parsed = typeof options.limit === "number" ? options.limit : Number(options.limit);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > WHO_KNOWS_MAX_LIMIT) {
+      throw new Error(`who-knows: --limit expects an integer between 1 and ${WHO_KNOWS_MAX_LIMIT}`);
+    }
+    limit = parsed;
+  }
+  const namespace = typeof options.namespace === "string" && options.namespace.trim().length > 0
+    ? options.namespace.trim()
+    : undefined;
+  validateWhoKnowsInput(rawTopic, limit);
+  return { topic: rawTopic.trim(), limit, namespace, json: options.json === true };
+}
+
+export function renderWhoKnowsJson(result: WhoKnowsResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+export function renderWhoKnowsText(result: WhoKnowsResult): string {
+  if (result.results.length === 0) {
+    return `who knows "${result.topic}": no evidence found`;
+  }
+  const lines = [`who knows "${result.topic}" (top ${result.results.length})`];
+  result.results.forEach((hit, index) => {
+    const name = hit.entityName || hit.entityId;
+    lines.push(`${index + 1}. ${name} [${hit.entityId}] — score ${hit.score.toFixed(4)} — ${hit.rationale}`);
+    for (const ref of hit.evidence) {
+      lines.push(`   - ${ref.id} (${ref.path}) updated ${ref.updated}`);
+    }
+  });
+  return lines.join("\n");
+}
+
+export function renderWhoKnows(result: WhoKnowsResult, json: boolean): string {
+  return json ? renderWhoKnowsJson(result) : renderWhoKnowsText(result);
+}
+

package/src/who-knows.test.ts

@@ -0,0 +1,257 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { EngramAccessInputError } from "./access-errors.js";
+import { EngramAccessService } from "./access-service.js";
+import type { MemoryFile, PluginConfig } from "./types.js";
+import {
+  computeWhoKnows,
+  handleWhoKnowsHttpQuery,
+  validateWhoKnowsInput,
+  type WhoKnowsEntity,
+  type WhoKnowsStorage,
+} from "./who-knows.js";
+import { extractWhoKnowsRawArgs, parseWhoKnowsCliOptions } from "./who-knows-cli.js";
+
+function bodyCode(body: unknown): string | undefined {
+  return body && typeof body === "object" && "code" in body && typeof body.code === "string"
+    ? body.code
+    : undefined;
+}
+
+function mem(overrides: {
+  id: string;
+  content: string;
+  entityRef?: string;
+  updated?: string;
+  importance?: number;
+  confidence?: number;
+  status?: string;
+}): MemoryFile {
+  return {
+    path: `/synthetic/mem/facts/2026-08-17/${overrides.id}.md`,
+    frontmatter: {
+      id: overrides.id,
+      category: "fact",
+      created: overrides.updated ?? "2026-08-01T00:00:00Z",
+      updated: overrides.updated ?? "2026-08-01T00:00:00Z",
+      source: "extraction",
+      confidence: overrides.confidence ?? 0.8,
+      tags: [],
+      ...(overrides.entityRef ? { entityRef: overrides.entityRef } : {}),
+      ...(overrides.importance !== undefined ? { importance: { score: overrides.importance, reason: "test" } } : {}),
+      ...(overrides.status ? { status: overrides.status } : {}),
+      confidenceTier: "inferred",
+    } as MemoryFile["frontmatter"],
+    content: overrides.content,
+  };
+}
+
+function fakeStorage(memories: MemoryFile[], entities: WhoKnowsEntity[] = []): WhoKnowsStorage & { readEntityRaw?: unknown } {
+  return {
+    async readAllMemories() {
+      return memories;
+    },
+    async listEntityNames() {
+      return entities.map((entity) => entity.id);
+    },
+    async readEntity(name) {
+      const entity = entities.find((candidate) => candidate.id === name);
+      return entity
+        ? `---\nname: ${entity.name}\ntype: person\nupdated: 2026-08-01T00:00:00Z\naliases: [${entity.aliases.map((a) => `"${a}"`).join(", ")}]\n---\n`
+        : "";
+    },
+  };
+}
+
+test("scoring ties: recency breaks ties, entity id is the stable final key", () => {
+  const entities: WhoKnowsEntity[] = [
+    { id: "person-alice", name: "Alice", aliases: [] },
+    { id: "person-bob", name: "Bob", aliases: [] },
+  ];
+  // Equal weights: same coverage, importance, confidence — one memory each.
+  const memories = [
+    mem({ id: "m-alice", content: "kafka consumer group tuning notes", entityRef: "person-alice", updated: "2026-08-01T00:00:00Z" }),
+    mem({ id: "m-bob", content: "kafka partition rebalance notes", entityRef: "person-bob", updated: "2026-08-10T00:00:00Z" }),
+  ];
+  const byRecency = computeWhoKnows({ topic: "kafka", limit: 5, memories, entities });
+  assert.equal(byRecency.results[0]?.entityId, "person-bob", "newer evidence wins a score tie");
+  assert.equal(byRecency.results[0]?.score, 1, "top hit normalizes to 1");
+  assert.ok(byRecency.results[0]?.score >= (byRecency.results[1]?.score ?? 0));
+
+  // Full tie (same score, same lastSeen) falls back to entity id ascending.
+  const tied = computeWhoKnows({
+    topic: "kafka",
+    limit: 5,
+    memories: [
+      mem({ id: "m-bob-tie", content: "kafka partition rebalance notes", entityRef: "person-bob", updated: "2026-08-01T00:00:00Z" }),
+      mem({ id: "m-alice-tie", content: "kafka consumer group tuning notes", entityRef: "person-alice", updated: "2026-08-01T00:00:00Z" }),
+    ],
+    entities,
+  });
+  assert.deepEqual(tied.results.map((hit) => hit.entityId), ["person-alice", "person-bob"]);
+  // Deterministic: repeated invocations produce identical output.
+  const again = computeWhoKnows({ topic: "kafka", limit: 5, memories, entities });
+  assert.deepEqual(
+    again.results.map((hit) => hit.entityId),
+    byRecency.results.map((hit) => hit.entityId),
+  );
+});
+
+test("missing entity names: entityRef without an entity file still ranks, name is null", () => {
+  const memories = [mem({ id: "m-ghost", content: "kafka exactly-once semantics deep dive", entityRef: "person-ghost" })];
+  const result = computeWhoKnows({ topic: "kafka", limit: 5, memories, entities: [] });
+  assert.equal(result.results.length, 1);
+  assert.equal(result.results[0]?.entityId, "person-ghost");
+  assert.equal(result.results[0]?.entityName, null);
+  assert.ok(result.results[0]?.evidence[0]?.path.endsWith("m-ghost.md"));
+});
+
+test("zero-evidence topic returns an empty list, not an error", () => {
+  const memories = [mem({ id: "m-unrelated", content: "unrelated quarterly planning notes", entityRef: "person-alice" })];
+  const entities: WhoKnowsEntity[] = [{ id: "person-alice", name: "Alice", aliases: [] }];
+  const result = computeWhoKnows({ topic: "kubernetes", limit: 5, memories, entities });
+  assert.deepEqual(result, { topic: "kubernetes", results: [] });
+});
+
+test("non-active memories are not evidence", () => {
+  const entities: WhoKnowsEntity[] = [{ id: "person-alice", name: "Alice", aliases: [] }];
+  const memories = [
+    mem({ id: "m-sup", content: "kafka notes superseded", entityRef: "person-alice", status: "superseded" }),
+    mem({ id: "m-ok", content: "kafka notes active", entityRef: "person-alice" }),
+  ];
+  const result = computeWhoKnows({ topic: "kafka", limit: 5, memories, entities });
+  assert.equal(result.results.length, 1);
+  assert.equal(result.results[0]?.evidenceCount, 1);
+  assert.equal(result.results[0]?.evidence[0]?.id, "m-ok");
+});
+
+test("authorship bonus is per entity: co-mentioned entity does not get the speaker bonus", () => {
+  const entities: WhoKnowsEntity[] = [
+    { id: "person-alice", name: "Alice", aliases: [] },
+    { id: "person-bob", name: "Bob", aliases: [] },
+  ];
+  const memories = [
+    mem({ id: "m-attr", content: "Alice explained the kafka rebalance with Bob", updated: "2026-08-10T00:00:00Z" }),
+  ];
+  const result = computeWhoKnows({ topic: "kafka", limit: 5, memories, entities });
+  const alice = result.results.find((hit) => hit.entityId === "person-alice");
+  const bob = result.results.find((hit) => hit.entityId === "person-bob");
+  assert.ok(alice && bob, "both co-mentioned entities rank");
+  assert.ok((alice?.score ?? 0) > (bob?.score ?? 0), "attributed speaker outranks the co-mentioned entity");
+  assert.match(alice?.rationale ?? "", /with direct attribution/);
+  assert.doesNotMatch(bob?.rationale ?? "", /with direct attribution/);
+});
+
+test("empty topic and invalid limit are validation errors", () => {
+  assert.throws(() => validateWhoKnowsInput("   ", 5), /whoKnows: topic is required/);
+  assert.throws(() => validateWhoKnowsInput("kafka", 0), /whoKnows: limit/);
+  assert.throws(() => validateWhoKnowsInput("kafka", 51), /whoKnows: limit/);
+});
+
+test("empty topic 400: HTTP helper maps missing/invalid query params to 400 without calling run", async () => {
+  let runCalls = 0;
+  const outcome = await handleWhoKnowsHttpQuery({
+    getParam: (name) => (name === "topic" ? "  " : null),
+    resolveNamespace: (namespace) => namespace,
+    run: async () => {
+      runCalls += 1;
+      throw new Error("must not run");
+    },
+  });
+  assert.equal(outcome.status, 400);
+  assert.equal(bodyCode(outcome.body), "missing_topic");
+  assert.equal(runCalls, 0);
+
+  const badLimit = await handleWhoKnowsHttpQuery({
+    getParam: (name) => (name === "topic" ? "kafka" : name === "limit" ? "abc" : null),
+    resolveNamespace: (namespace) => namespace,
+    run: async () => {
+      runCalls += 1;
+      throw new Error("must not run");
+    },
+  });
+  assert.equal(badLimit.status, 400);
+  assert.equal(bodyCode(badLimit.body), "invalid_limit");
+  assert.equal(runCalls, 0);
+
+  const happy = await handleWhoKnowsHttpQuery({
+    getParam: (name) => (name === "topic" ? "kafka" : name === "limit" ? "3" : name === "namespace" ? "team" : null),
+    resolveNamespace: (namespace) => namespace,
+    run: async (request) => {
+      runCalls += 1;
+      assert.deepEqual(request, { topic: "kafka", limit: 3, namespace: "team" });
+      return { topic: "kafka", results: [] };
+    },
+  });
+  assert.equal(happy.status, 200);
+  assert.equal(runCalls, 1);
+});
+
+test("namespace allow-list gate runs even when the namespace param is omitted", async () => {
+  const resolved: Array<string | undefined> = [];
+  const outcome = await handleWhoKnowsHttpQuery({
+    getParam: (name) => (name === "topic" ? "kafka" : null),
+    resolveNamespace: (namespace) => {
+      resolved.push(namespace);
+      return "default";
+    },
+    run: async (request) => {
+      assert.equal(request.namespace, "default", "resolved default namespace flows into the request");
+      return { topic: "kafka", results: [] };
+    },
+  });
+  assert.equal(outcome.status, 200);
+  assert.deepEqual(resolved, [undefined], "resolver (and its allow-list) ran once with the implicit namespace");
+});
+
+test("namespace restriction: storage is resolved per readable namespace and the ACL matches recall", async () => {
+  const config = {
+    namespacesEnabled: true,
+    defaultNamespace: "default",
+    namespacePolicies: [{ name: "team", readPrincipals: ["reader"], writePrincipals: ["writer"] }],
+    memoryDir: "/synthetic/mem",
+  } as unknown as PluginConfig;
+  const getStorageNames: string[] = [];
+  const teamStorage = fakeStorage(
+    [mem({ id: "m-team", content: "kafka consumer tuning deep dive", entityRef: "person-alice" })],
+    [{ id: "person-alice", name: "Alice", aliases: [] }],
+  );
+  const defaultStorage = fakeStorage([mem({ id: "m-default", content: "kafka other notes", entityRef: "person-carol" })]);
+  const service = Object.create(EngramAccessService.prototype) as EngramAccessService;
+  (service as unknown as { orchestrator: unknown }).orchestrator = {
+    config,
+    getStorage: async (namespace: string) => {
+      getStorageNames.push(namespace);
+      return namespace === "team" ? teamStorage : defaultStorage;
+    },
+  };
+
+  const allowed = await service.whoKnows({ topic: "kafka", namespace: "team", authenticatedPrincipal: "reader" });
+  assert.equal(allowed.results.length, 1);
+  assert.equal(allowed.results[0]?.entityId, "person-alice");
+  assert.deepEqual(getStorageNames, ["team"], "reads only the resolved namespace's storage — no cross-namespace leak");
+
+  await assert.rejects(
+    () => service.whoKnows({ topic: "kafka", namespace: "team" }),
+    (err: unknown) => err instanceof EngramAccessInputError && /authentication required/.test(err.message),
+    "no principal + namespaces enabled must fail closed",
+  );
+
+  await assert.rejects(
+    () => service.whoKnows({ topic: "kafka", namespace: "team", authenticatedPrincipal: "nobody" }),
+    (err: unknown) => err instanceof EngramAccessInputError && /not readable/.test(err.message),
+    "principal outside readPrincipals must be denied",
+  );
+});
+
+test("CLI parsing: empty topic, bare --limit, and unknown flags throw listed-options errors", () => {
+  const { topic, options } = extractWhoKnowsRawArgs(["kafka", "tuning", "--limit", "3", "--json"]);
+  const parsed = parseWhoKnowsCliOptions(topic, options);
+  assert.deepEqual(parsed, { topic: "kafka tuning", limit: 3, namespace: undefined, json: true });
+
+  assert.throws(() => parseWhoKnowsCliOptions("", {}), /topic is required/);
+  assert.throws(() => extractWhoKnowsRawArgs(["kafka", "--limit"]), /--limit expects a value/);
+  assert.throws(() => extractWhoKnowsRawArgs(["kafka", "--bogus"]), /unknown option/);
+  assert.throws(() => parseWhoKnowsCliOptions("kafka", { limit: 0 }), /--limit expects an integer/);
+});