knowledge-engine: add a grant-checked ask() that answers from retrieved context

Rebased and slimmed onto current main (post #10 rerank-budget validator,
post #11 log-detail interpolation + degrade metrics). Dropped 13 files of
pure Prettier reformatting that had accumulated on the old branch and were
never part of this feature; nothing else changed.

ask() performs its own knowledge:search grant check internally, since an
in-process caller never passes through the HTTP requireGrant route guard.
It then searches as the asking principal (same per-document ACL/block-list
path as search()), assembles a bounded grounded-context block, and calls a
host-supplied generate() function. The engine intentionally owns no
generation client, matching its existing posture on embedding.

Claude-Session: https://claude.ai/code/session_017GTgGzn5xAwvkU2GAPAHpF

Author: TheGreatAxios

README.md

@@ -58,6 +58,71 @@ import { runKnowledgeMigrations } from "@corbits/knowledge-engine/migrations";
 await runKnowledgeMigrations(process.env.KNOWLEDGE_DATABASE_URL);
 ```
 
+## ask()
+
+`knowledge.ask()` answers a question from retrieved context, in-process — no
+HTTP hop, no separate host-side answer synthesis. It is grant-checked
+internally, so it is safe to call from anywhere a host has resolved a
+principal, even code paths that never go through the mounted HTTP routes:
+
+```ts
+const { text, citations, evidence } = await knowledge.ask({
+  tenantId,
+  principalId,
+  query,
+  k: 6, // optional, defaults to hybridSearch's default
+});
+```
+
+1. Checks the capability grant (`authorize(grantStore, principalId, tenantId,
+"knowledge", "search", conditionRegistry)`) and throws
+   `KnowledgeNotPermittedError` unless the effect is an explicit `"allow"` — no
+   matching grant (`effect: null`) denies too. This runs whether or not the
+   call came through the HTTP route guard, so it can never be forgotten.
+2. Searches as that principal (`hybridSearch`), so per-document visibility and
+   block lists apply exactly as they do for `search()`.
+3. Assembles a grounded context block from the hits' `snippet` text, truncated
+   to a character budget.
+4. Calls the **host-supplied** `generate` function with a system prompt that
+   instructs answering only from context and refusing explicitly when the
+   context doesn't contain the answer.
+5. Returns the answer text, the citations actually used (matched to the `[N]`
+   markers in the prompt), and the search's evidence level.
+
+### The engine owns no generation client
+
+`ask()` takes generation as an injected function, not as config:
+
+```ts
+type Generate = (messages: readonly ChatMessage[]) => Promise<string>;
+
+mountKnowledgeEngine(app, {
+  config,
+  grants,
+  generate: async (messages) => runInferenceSomehow(messages),
+});
+```
+
+This is deliberate. Interchange already has an inference layer
+(`@intx/inference`) with provider adapters, tenant-scoped credentials, a retry
+policy, audit collection and authz gates. A `fetch` client here would bypass all
+of it and take an API key from a raw env var — so hosts wire `generate` to that
+layer instead, and credentials stay in the credential store where they belong.
+
+It also keeps the engine transport-free, which is the posture it already takes
+on embedding: never in-process, always an endpoint the owner plugs in.
+
+Omit `generate` if the host only captures and searches; `ask()` then fails with
+a 501 naming what is missing rather than at some later point.
+
+Two things that belong in the host's `generate`, learned the hard way:
+
+- **Timeouts must be generous for local models.** A cold 10GB model can take
+  over a minute to page into memory before emitting a token.
+- **Use a non-reasoning model.** A reasoning model that exhausts its budget
+  returns chain-of-thought with empty content, and the host will see an empty
+  answer. Detect it there and say so.
+
 ## Local development
 
 The SDK is not a server — it mounts onto your app. This repo ships a

src/index.ts

@@ -11,7 +11,11 @@ import { createRequireGrant, type TenantEnv } from "@intx/hub-api";
 
 import type { KnowledgeConfig } from "./mount-config.ts";
 import { CaptureLog } from "./capture-log.ts";
-import { createKnowledgePlane, type KnowledgePlane } from "./knowledge.ts";
+import {
+  createKnowledgePlane,
+  type Generate,
+  type KnowledgePlane,
+} from "./knowledge.ts";
 import {
   mountKnowledgeRoutes,
   type GrantConfig,
@@ -26,7 +30,16 @@ export { loadKnowledgeConfig } from "./mount-config.ts";
 export type { EngineConfig } from "./config.ts";
 export { RerankConfigError } from "./core/rerank-client.ts";
 // Knowledge plane + capture log
-export type { KnowledgePlane } from "./knowledge.ts";
+export type {
+  KnowledgePlane,
+  KnowledgePlaneOptions,
+  KnowledgeAskParams,
+  AskResult,
+  AskCitation,
+  ChatMessage,
+  Generate,
+} from "./knowledge.ts";
+export { KnowledgeNotPermittedError, KnowledgeError } from "./knowledge.ts";
 export { CaptureLog, type CaptureEvent } from "./capture-log.ts";
 // Migrations
 export { runKnowledgeMigrations } from "./migrations.ts";
@@ -52,6 +65,15 @@ export type MountKnowledgeEngineOptions = {
    * unguarded.
    */
   grants: GrantConfig;
+  /**
+   * How `ask()` reaches a model. Omit if this host only captures and searches;
+   * `ask()` then fails with a 501 naming what is missing.
+   *
+   * The engine owns no generation client on purpose — Interchange's
+   * `@intx/inference` already has provider adapters, tenant-scoped credentials,
+   * retry, audit and authz gates. Wire this to that rather than to a bare fetch.
+   */
+  generate?: Generate;
 };
 
 export type MountedKnowledgeEngine = {
@@ -78,7 +100,9 @@ export function mountKnowledgeEngine(
   const rerankConfig = toRerankClientConfig(options.config.knowledge.rerank);
   if (rerankConfig) validateRerankConfig(rerankConfig);
 
-  const knowledge = createKnowledgePlane(options.config);
+  const knowledge = createKnowledgePlane(options.config, options.grants, {
+    ...(options.generate ? { generate: options.generate } : {}),
+  });
   const captureLog = new CaptureLog();
   const deps: RouteDeps = {
     knowledge,

src/knowledge.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createInMemoryGrantStore } from "@intx/authz";
+import type { GrantRule } from "@intx/authz";
+
+import {
+  createKnowledgePlane,
+  KnowledgeNotPermittedError,
+  synthesizeAnswer,
+} from "./knowledge.ts";
+import type { KnowledgeConfig } from "./mount-config.ts";
+import type { ChatMessage } from "./knowledge.ts";
+import type { SearchHit } from "./core/schemas/search.ts";
+
+const PRINCIPAL = "p1";
+const TENANT = "t1";
+
+function grant(action: string): GrantRule {
+  return {
+    id: `g-${action}`,
+    resource: "knowledge",
+    action,
+    effect: "allow",
+    origin: "role",
+    conditions: null,
+    expiresAt: null,
+    roleId: null,
+    principalId: PRINCIPAL,
+  };
+}
+
+function hit(overrides: Partial<SearchHit> = {}): SearchHit {
+  return {
+    chunk_id: "chunk-1",
+    document_id: "doc-1",
+    version: 1,
+    version_id: "v1",
+    status: "current",
+    score: 0.9,
+    title: "Doc One",
+    snippet: "the relevant snippet",
+    kind: "note",
+    created_by_kind: "human",
+    citation: {
+      adapter: "mcp",
+      external_ref: "ref-1",
+      open: { type: "doc", id: "doc-1" },
+    },
+    entity_ids: [],
+    channels_matched: ["lexical"],
+    ...overrides,
+  } as SearchHit;
+}
+
+const config: KnowledgeConfig = {
+  knowledge: {
+    databaseUrl: "postgres://localhost:5432/nonexistent-test-db",
+    dbPoolMax: 1,
+    embed: {
+      baseUrl: "http://embed",
+      model: "m",
+      apiStyle: "openai",
+      apiKey: undefined,
+    },
+    rerank: {
+      baseUrl: undefined,
+      model: undefined,
+      apiKey: undefined,
+      maxDocChars: undefined,
+    },
+  },
+};
+
+describe("ask() — grant check", () => {
+  it("denies with KnowledgeNotPermittedError when no grant matches (effect: null)", async () => {
+    const grants = {
+      grantStore: createInMemoryGrantStore([]),
+      conditionRegistry: {},
+    };
+    const plane = createKnowledgePlane(config, grants);
+    await expect(
+      plane.ask({ tenantId: TENANT, principalId: PRINCIPAL, query: "q" }),
+    ).rejects.toBeInstanceOf(KnowledgeNotPermittedError);
+  });
+
+  it("denies when the only matching grant is an explicit deny", async () => {
+    const denyGrant: GrantRule = { ...grant("search"), effect: "deny" };
+    const grants = {
+      grantStore: createInMemoryGrantStore([denyGrant]),
+      conditionRegistry: {},
+    };
+    const plane = createKnowledgePlane(config, grants);
+    await expect(
+      plane.ask({ tenantId: TENANT, principalId: PRINCIPAL, query: "q" }),
+    ).rejects.toBeInstanceOf(KnowledgeNotPermittedError);
+  });
+});
+
+describe("synthesizeAnswer", () => {
+  const neverCalled = mock(() =>
+    Promise.reject(new Error("generate must not be called")),
+  );
+
+  it("refuses with no citations when there are no hits", async () => {
+    const result = await synthesizeAnswer(
+      "q",
+      { hits: [], evidence: "none" },
+      neverCalled,
+    );
+    expect(result.citations).toEqual([]);
+    expect(result.evidence).toBe("none");
+    expect(neverCalled).not.toHaveBeenCalled();
+  });
+
+  it("refuses with no citations when hits have no readable snippet text", async () => {
+    const result = await synthesizeAnswer(
+      "q",
+      { hits: [hit({ snippet: "   " })], evidence: "weak" },
+      neverCalled,
+    );
+    expect(result.text).toContain("couldn't read any text");
+    expect(result.citations).toEqual([]);
+    expect(neverCalled).not.toHaveBeenCalled();
+  });
+
+  it("grounds the prompt in the retrieved snippets and returns their citations", async () => {
+    const generate = mock((messages: readonly ChatMessage[]) => {
+      // The grounding contract: the model sees the numbered context, and only
+      // the numbered context, for the hits that fit the budget.
+      expect(messages[1]?.content).toContain("[1] Doc One");
+      expect(messages[1]?.content).toContain("the relevant snippet");
+      return Promise.resolve("Grounded answer [1].");
+    });
+
+    const result = await synthesizeAnswer(
+      "what is the answer?",
+      { hits: [hit()], evidence: "strong" },
+      generate,
+    );
+
+    expect(result.text).toBe("Grounded answer [1].");
+    expect(result.evidence).toBe("strong");
+    expect(result.citations).toEqual([
+      {
+        index: 1,
+        documentId: "doc-1",
+        title: "Doc One",
+        citation: hit().citation,
+      },
+    ]);
+  });
+
+  it("propagates a generate failure rather than inventing an answer", async () => {
+    const generate = mock(() => Promise.reject(new Error("model unreachable")));
+    await expect(
+      synthesizeAnswer("q", { hits: [hit()], evidence: "weak" }, generate),
+    ).rejects.toThrow("model unreachable");
+  });
+});