Validate rerank config in createKnowledgePlane and re-export search result types

Standalone plane construction skipped the maxDocChars check that mount ran,
so a bad override only degraded silently outside HTTP. Move validation into
createKnowledgePlane so both paths share it. Re-export HybridSearchResult,
SearchHit, and VisibilitySpec from the public surface, and list
createKnowledgePlane in AGENTS.md and PRODUCT.md.

Author: TheGreatAxios

AGENTS.md

@@ -18,7 +18,7 @@ CI runs `typecheck` + `test` — both must pass before any push.
 
 ## Layout
 
-- `src/index.ts` — public surface: `mountKnowledgeEngine`, `mountKnowledgeRoutes`
+- `src/index.ts` — public surface: `mountKnowledgeEngine`, `mountKnowledgeRoutes`, `createKnowledgePlane`
 - `src/mount-config.ts` / `src/config.ts` — mount config + engine config
 - `src/routes/` — Hono routes (capture, search, timeline)
 - `src/services/` — capture / search / transform logic

PRODUCT.md

@@ -11,6 +11,8 @@ SDK never creates one; it mounts onto yours. Nothing else ships in this repo.**
 
 1. **Public surface**: `mountKnowledgeEngine(app, opts)` drops the knowledge
    plane + routes onto an Interchange `createApp`;
+   `createKnowledgePlane(config)` builds the same plane without mounting HTTP
+   (CLI seeders, batch ingesters, tests);
    `runKnowledgeMigrations(url)` applies the pgvector schema;
    `loadKnowledgeConfig()` / `KnowledgeConfig` is the mount config.
 2. **The SDK authenticates nothing.** Identity is the request principal, read
@@ -41,6 +43,7 @@ Claude Code / Codex / Workbench (clients)
 │  Host Interchange createApp              │
 │    resolves principal + tenant + grants  │
 │  + mountKnowledgeEngine(app, opts)       │
+│    or createKnowledgePlane(config)       │
 │    reads c.get("principal") from context │
 │    guards via host requireGrant(...)     │
 │         │  in-process                    │
@@ -65,6 +68,8 @@ Access is gated by the host's grant system: pass `grants` (the same
 `{ grantStore, conditionRegistry }` you give `createApp`) to
 `mountKnowledgeEngine`. HTTP routes run `requireGrant("knowledge", <action>)`
 (`capture` for capture, `search` for search/timeline).
+`createKnowledgePlane` builds the same plane without routes — callers acting
+for a user must check the capability themselves (see README).
 
 ### On the wire
 

src/index.ts

@@ -17,8 +17,6 @@ import {
   type GrantConfig,
   type RouteDeps,
 } from "./routes/mount.ts";
-import { toRerankClientConfig } from "./services/search.ts";
-import { validateRerankConfig } from "./core/rerank-client.ts";
 
 // Config
 export type { KnowledgeConfig } from "./mount-config.ts";
@@ -31,13 +29,16 @@ export { RerankConfigError } from "./core/rerank-client.ts";
 // request — a CLI seeder, a batch ingester, or a test — without standing up a
 // Hono app just to get a plane. Callers acting on behalf of a user are
 // responsible for the capability check `requireGrant` would have performed; see
-// the README.
+// the README. Rerank config is validated at construction (same as mount).
 export { createKnowledgePlane } from "./knowledge.ts";
 export type {
+  HybridSearchResult,
   KnowledgeCaptureParams,
   KnowledgeIdentity,
   KnowledgePlane,
   KnowledgeSearchParams,
+  SearchHit,
+  VisibilitySpec,
 } from "./knowledge.ts";
 export { KnowledgeError } from "./knowledge.ts";
 export { CaptureLog, type CaptureEvent } from "./capture-log.ts";
@@ -77,20 +78,8 @@ export function mountKnowledgeEngine(
   app: Hono<TenantEnv>,
   options: MountKnowledgeEngineOptions,
 ): MountedKnowledgeEngine {
-  // Catch a chunk-size / reranker-limit mismatch here, at mount time, rather
-  // than silently on every search once the reranker starts rejecting
-  // batches. This throws instead of warning: a mismatch here means every
-  // rerank call for this host WILL 413 and silently degrade to fused
-  // ranking, with no per-request signal — a boot-time failure surfaces that
-  // once, loudly, instead of leaving reranking quietly broken indefinitely.
-  // This is only safe to throw on because the per-model default budget
-  // (`defaultMaxDocCharsForModel`) is self-consistent by construction —
-  // validation can only fire on an operator's own `maxDocChars` override,
-  // never spuriously on an unmodified config, regardless of which model
-  // that config resolves to.
-  const rerankConfig = toRerankClientConfig(options.config.knowledge.rerank);
-  if (rerankConfig) validateRerankConfig(rerankConfig);
-
+  // Rerank config validation runs inside createKnowledgePlane so standalone
+  // construction and the mount path share one check.
   const knowledge = createKnowledgePlane(options.config);
   const captureLog = new CaptureLog();
   const deps: RouteDeps = {

src/knowledge.ts

@@ -6,14 +6,21 @@ import type { EngineConfig } from "./config.ts";
 import { formatCaughtError, log } from "./log.ts";
 import { createDb, type Db, type RawSql } from "./db/client.ts";
 import type { VisibilitySpec } from "./core/schemas/document.ts";
+import { validateRerankConfig } from "./core/rerank-client.ts";
 import { captureDocument } from "./services/capture.ts";
 import {
   hybridSearch,
   KnowledgeSearchInputError,
+  toRerankClientConfig,
   type HybridSearchResult,
 } from "./services/search.ts";
 import type { KnowledgeConfig } from "./mount-config.ts";
 
+// Re-export so hosts typing plane.search() results don't reach into services/.
+export type { HybridSearchResult } from "./services/search.ts";
+export type { SearchHit } from "./core/schemas/search.ts";
+export type { VisibilitySpec } from "./core/schemas/document.ts";
+
 export type KnowledgeIdentity = {
   principalId: string;
   tenantId: string;
@@ -53,6 +60,20 @@ export type KnowledgePlane = {
 };
 
 export function createKnowledgePlane(config: KnowledgeConfig): KnowledgePlane {
+  // Catch a chunk-size / reranker-limit mismatch at construction time, rather
+  // than silently on every search once the reranker starts rejecting batches.
+  // Throws instead of warning: a mismatch means every rerank call for this
+  // host WILL 413 and silently degrade to fused ranking, with no per-request
+  // signal — a construction-time failure surfaces that once, loudly.
+  // Safe to throw because the per-model default budget
+  // (`defaultMaxDocCharsForModel`) is self-consistent by construction —
+  // validation can only fire on an operator's own `maxDocChars` override,
+  // never spuriously on an unmodified config.
+  // Lives here (not only in mountKnowledgeEngine) so standalone construction
+  // cannot silently degrade on a bad override.
+  const rerankConfig = toRerankClientConfig(config.knowledge.rerank);
+  if (rerankConfig) validateRerankConfig(rerankConfig);
+
   const engineConfig: EngineConfig = config.knowledge;
   const { db, sql }: { db: Db; sql: RawSql } = createDb(engineConfig);
   const deps = { db, sql, config: engineConfig };