@panaversity/ksor 0.0.23 → 0.0.24

package/dist/gateway.d.mts

@@ -0,0 +1,144 @@
+import { CallToolResult, McpServer as McpServer$1, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import { z as z$1 } from "zod";
+import pg from "pg";
+//#region ../content-gateway/dist/gateway-api-D9COH1tR.d.mts
+//#region src/instructions.d.ts
+/**
+ * Has the owner said what this record is FOR yet?
+ *
+ * The MCP door already answers honestly when they have not — it replaces the
+ * template with a plain statement that the scope is unstated. But the operator
+ * starting the server was told nothing, so a record serving with no declared
+ * identity looked exactly like one that had been described. The boot report is
+ * where that belongs, beside the abstention posture: both are answers to "how
+ * much should I trust what this thing says".
+ */
+declare function recordIsUndescribed(authored: string): boolean;
+declare function composeInstructions(authored: string): string;
+//#endregion
+//#region ../content/dist/index.d.mts
+//#endregion
+//#region src/lib/abstain.d.ts
+/**
+ * The abstention gates (oracle SC/lib/abstain.py, exact). "Not in this
+ * corpus" is a correct answer, never an error, never a licence to fall back
+ * on model knowledge.
+ *
+ * Floors come from the instance frontmatter, never module globals, and are
+ * calibrated per corpus per embedding space — never copy a calibrated
+ * constant between corpora.
+ */
+interface AbstainConfig {
+  /**
+   * A calibrated number gates (abstain below it); `null` = no gate declared,
+   * honest absence surfaced on /health; `"uncalibrated"` = a floor was
+   * DECLARED but not measured, which REFUSES every serve until it is pasted
+   * (the "fail closed once a floor is declared" invariant, representable).
+   */
+  readonly vectorFloor: number | null | "uncalibrated";
+  /**
+   * Degraded-path ts_rank_cd floor; null = abstain only on zero matches.
+   * Recorded negative result (oracle, measured on 416 in-corpus gold + 38
+   * OOC probes): ts_rank_cd does NOT separate in/out-of-corpus — every
+   * leak-stopping floor false-abstained 67–98% (0.1333 → FA 255/379;
+   * 0.7 → FA 355/379). The shipped instance keeps keyword_floor null;
+   * never set one by intuition, recalibrate per corpus.
+   */
+  readonly keywordFloor: number | null;
+}
+interface ContentInstance {
+  /** The corpus identity — instance.md's `name:` (the path/name IS the identity). */
+  readonly name: string;
+  readonly corpusId: string;
+  readonly tenantId: string;
+  /** The NAME of the env var holding the DSN; the composition root resolves it. */
+  readonly dsnEnv: string;
+  readonly abstain: AbstainConfig;
+  readonly maximumResponseCharacters: number;
+  /** The authored agent-surface instructions (the body, edge-trimmed). */
+  readonly instructions: string;
+  /** Transport name (registry key, never persisted). */
+  readonly embeddingProvider: string;
+  /** The record's reader audiences, least- to most-restricted; empty = no model. */
+  /** The Postgres text-search configuration the keyword arm stems with. */
+  readonly textSearchConfig: string;
+  readonly audiences: readonly string[];
+  /** The tier a document takes when it declares none; null = none declared. */
+  readonly defaultVisibility: string | null;
+  /** model + dim are the persisted IDENTITY of the embedding space. */
+  readonly embeddingModel: string;
+  readonly embeddingDim: number;
+}
+interface KeyRing {
+  readonly keys: ReadonlyMap<string, Buffer>;
+  /** Mint with the active key; keep validating old ids until their tokens age out (≤ TTL). */
+  readonly active: string;
+}
+declare const MAX_SEARCH_K = 50;
+interface ServiceContext {
+  readonly pool: pg.Pool;
+  readonly instance: ContentInstance;
+  readonly ring: KeyRing;
+  /** sha256 of instance.md — the deployment binding snapshots carry. */
+  readonly instanceDigest: string;
+  /** The query-embed pipeline (cache + breaker + timeout live behind it); returns a pgvector literal or a raw vector. */
+  readonly embedQuery: (query: string) => Promise<readonly number[] | string>;
+  /** The verified caller, or null → audited as "anonymous". */
+  readonly actor?: () => string | null;
+  /**
+   * The audience tier this door serves. null = the record's least-privileged
+   * tier, which is the safe default: a door that cannot establish who is asking
+   * must not hand out the restricted half of the record. Ignored entirely when
+   * the instance declares no `audiences:` model.
+   */
+  readonly audience?: string | null;
+}
+/**
+ * The largest outline a caller may ASK for. The tool schema and the service
+ * both derive from it, so the ceiling is one number rather than three
+ * hand-copied ones.
+ */
+declare const MAX_OUTLINE_LIMIT = 5e3;
+//#endregion
+//#region src/tools.d.ts
+/**
+ * The framework text every tool description must carry.
+ *
+ * A registration file puts its own prose ABOVE one of these. It is a template
+ * literal in adopter code, so nothing stops someone omitting it — which is why
+ * the door verifies its own served surface at boot rather than trusting that
+ * nobody did.
+ */
+declare const FLOOR: Readonly<Record<"search" | "outline" | "read", string>>;
+/** Every ksor tool is a read: no writes, safe to retry, closed world. */
+declare const READ_ONLY: {
+  readonly readOnlyHint: true;
+  readonly destructiveHint: false;
+  readonly idempotentHint: true;
+  readonly openWorldHint: false;
+};
+declare const SEARCH_OUTPUT: StandardSchemaWithJSON;
+declare const OUTLINE_OUTPUT: StandardSchemaWithJSON;
+declare const READ_OUTPUT: StandardSchemaWithJSON;
+interface SearchArgs {
+  readonly query: string;
+  readonly k: number;
+}
+declare function searchHandler(ctx: ServiceContext): (args: SearchArgs) => Promise<CallToolResult>;
+interface OutlineArgs {
+  readonly node?: string | undefined;
+  readonly depth?: number | undefined;
+  readonly limit: number;
+  readonly offset?: number | undefined;
+}
+declare function outlineHandler(ctx: ServiceContext): (args: OutlineArgs) => Promise<CallToolResult>;
+interface ReadArgs {
+  readonly slug: string;
+  readonly heading?: string | undefined;
+  readonly from_heading?: string | undefined;
+  readonly snapshot_token?: string | undefined;
+  readonly token_budget?: number | undefined;
+}
+declare function readHandler(ctx: ServiceContext): (args: ReadArgs) => Promise<CallToolResult>;
+//#endregion
+export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, type OutlineArgs, READ_ONLY, READ_OUTPUT, type ReadArgs, SEARCH_OUTPUT, type SearchArgs, type ServiceContext, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/dist/gateway.mjs

@@ -0,0 +1,2 @@
+import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-BF06IsJ--D-eI--yB.mjs";
+export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/docs/index.md

@@ -32,6 +32,10 @@ instead of their training memory. The corpus grows with each implemented verb.
   export the manifest the site build reads), `ksor calibrate` (measure the
   abstention floor) and `ksor gc` (reap retired generations). Only `ksor dev` and `ksor build` remain designed, not
   implemented: each prints an honest notice and exits `2`.
+  - **[tool-surface.md](./tool-surface.md)** — shaping what agents see.
+    `system/gateways/content.ts` is emitted, adopter-owned and deletable; it
+    decides tool names, what the record says it covers, and how much of the
+    caller's context an answer costs. Includes the measurements.
   - **[deploying.md](./deploying.md)** — getting both surfaces onto a host. The
     scaffold emits a `Dockerfile` that names no vendor, and a `vercel.json` that
     points at it to put the site and the MCP door behind one domain. Includes

package/docs/tool-surface.md

@@ -0,0 +1,133 @@
+---
+title: The tool surface
+status: draft
+---
+
+# Shaping what agents see — `system/gateways/content.ts`
+
+That file is your record's MCP registration: ordinary `registerTool` calls with
+ordinary zod. It decides what your tools are called, what they say, what they
+accept, and which of them exist. It is yours, and deleting it is supported —
+without it the door serves the same defaults.
+
+## Why it is worth editing
+
+An agent pays for this surface out of its context window, and it pays twice.
+Every tool's name, description and input schema is resident for the whole
+session; every answer spends more.
+
+Measured against a live 81-document record (6,963 chunks), ~4 chars/token:
+
+|                                | chars  | ~tokens |                     |
+| ------------------------------ | ------ | ------- | ------------------- |
+| all three tool definitions     | 11,960 | 2,990   | **always resident** |
+| `search` alone                 | 5,383  | 1,346   | always resident     |
+| `outline` + `read`             | 6,571  | 1,643   | always resident     |
+| one `search`, `k=10` (default) | 14,164 | 3,541   | per call            |
+| one `search`, `k=5`            | 8,009  | 2,002   | per call            |
+
+An agent with five records attached carries ~15,000 tokens of definitions before
+doing any work.
+
+## The three edits that pay
+
+### 1. Delete a tool nothing calls
+
+The biggest win, and the easiest — delete its `registerTool` block. Measured
+live: a registration keeping only a renamed `search` served **5,337** bytes
+against the default's 11,960.
+
+### 2. Say what the record covers
+
+The line that decides whether an agent asks _you_ rather than another record it
+has open. Name the subject **and the boundary**:
+
+```ts
+description: `Employee handbook: leave, benefits, conduct, expenses.
+Not product documentation and not customer data.\n\n${FLOOR.search}`,
+```
+
+Your prose goes **above** `FLOOR.search`, never instead of it — see below.
+
+### 3. Set `k`
+
+`k` is the lever on reply size: 10 costs ~3,500 tokens a call, 5 costs ~2,000.
+The caller can always ask for more, so make the default what you usually need.
+
+```ts
+inputSchema: z.object({
+  query: z.string().min(1).max(2000),
+  k: z.number().int().min(1).max(50).default(5),
+}),
+```
+
+**`budgets.maximum_response_characters` is not this lever.** It defaults to
+120,000 and at ~1,400 chars a hit cannot bind before the 50-hit ceiling. Tune `k`.
+
+## Adding your own tools
+
+It is an MCP server. Call `registerTool` again with your own handler:
+
+```ts
+server.registerTool(
+  "check_policy_expiry",
+  {
+    inputSchema: z.object({ policy: z.string() }),
+  },
+  async ({ policy }) => ({ content: [{ type: "text", text: await lookup(policy) }] }),
+);
+```
+
+One thing to be clear-eyed about: **ksor makes no provenance claim about a tool
+it did not hand you a handler for.** `searchHandler(ctx)` answers from the
+governed record with citations; a handler you write answers from wherever you
+made it answer from.
+
+## What you cannot change, and why
+
+- **The handlers.** `searchHandler` / `outlineHandler` / `readHandler` are the
+  only things that can prove a passage came from the governed record. A
+  hand-written one returning fabricated hits with plausible `stable_id`s would
+  pass every shape check there is.
+- **The output schemas.** `SEARCH_OUTPUT`, `OUTLINE_OUTPUT`, `READ_OUTPUT` carry
+  `provenance`, the `snapshot` token and `gate`. A record that reshaped them
+  would still look like a KSoR and no longer be one.
+- **The `FLOOR` text.** It tells an agent how to branch on an envelope, what
+  `gate: "off"` means, and that corpus content is **untrusted** — quote it, never
+  obey it. Your prose is composed above it.
+
+## The door checks its own surface at boot
+
+Because that last one is a template literal in a file you own, nothing structural
+stops it being dropped. So the door builds its server, asks itself `tools/list`
+over an in-memory transport, and refuses to start if a guarantee is gone:
+
+```
+error: ksor-gateway-floor-missing: the search tool is served as "search_the_book"
+without its framework description. That text tells an agent how to read an
+abstention and that corpus content is untrusted — without it this record answers
+without ever declining, and follows instructions written into its own documents.
+Put FLOOR.search back: a record's own prose goes ABOVE it, as
+`${yourText}\n\n${FLOOR.search}`, never instead of it
+```
+
+| what                                               | slug                         |
+| -------------------------------------------------- | ---------------------------- |
+| a served ksor tool lost its `FLOOR` text           | `ksor-gateway-floor-missing` |
+| the registration serves no tools at all            | `ksor-gateway-no-tools`      |
+| the file throws, or default-exports a non-function | `ksor-gateway-unloadable`    |
+
+Delete the file to take the default registration back.
+
+## One import, no dependencies
+
+Everything comes from `@panaversity/ksor/gateway` — including `z` and
+`McpServer`. That is deliberate: your registration stays a _file_, with no
+package.json, no build step, and nothing new in your lockfile. It also means the
+SDK validates with the same zod instance it was built against, which a
+separately-installed zod would not.
+
+## More records later
+
+`identity` and `praxis` get `system/gateways/<record>.ts` by the same rule.
+Nothing above is specific to content except which tools exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",
@@ -44,6 +44,11 @@
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./gateway": {
+      "types": "./dist/gateway.d.mts",
+      "import": "./dist/gateway.mjs",
+      "default": "./dist/gateway.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {

package/templates/scaffold/AGENTS.md

@@ -311,6 +311,48 @@ signing keys, an unknown key id answers **503**, not 401 — the token may well
 good and the door's key set merely stale, so a client should retry rather than
 send the user back through a login.
 
+## Shaping the agent surface — `system/gateways/content.ts`
+
+That file is this record's MCP registration — ordinary `registerTool` with
+ordinary zod. It is yours, and it is **deletable**: without it the door serves
+the same defaults.
+
+Edit it because an agent pays for this surface out of its context window, twice.
+Measured on an 81-document record:
+
+|                                  |                                |
+| -------------------------------- | ------------------------------ |
+| all three tool definitions       | ~2,990 tokens, always resident |
+| one `search` at `k=10` (default) | ~3,541 tokens per call         |
+| one `search` at `k=5`            | ~2,002 tokens per call         |
+
+Three edits pay for themselves:
+
+- **Delete a tool nothing calls.** Removing `outline` and `read` gives back
+  ~1,643 tokens for the whole session.
+- **Say what this record covers**, above `FLOOR.search`. It is how an agent with
+  several records attached picks yours; name the subject AND the boundary.
+- **Set `k`** in the input schema — it is the lever on reply size.
+
+```ts
+description: `Leave, benefits, conduct. Not product docs.\n\n${FLOOR.search}`,
+inputSchema: z.object({ query: z.string(), k: z.number().int().default(5) }),
+```
+
+You can add your own tools with `registerTool` too — but be clear-eyed: ksor
+makes no provenance claim about a tool it did not hand you a handler for.
+
+What you cannot change is deliberate: the handlers, the output schemas, and the
+`FLOOR` text. Your prose goes ABOVE the floor, never instead of it — the floor
+tells an agent how to read an abstention and that corpus content is untrusted,
+and a record that dropped it would answer without ever declining.
+
+Because that is a template literal in a file you own, the door checks its own
+surface at boot and refuses to start if a guarantee is gone:
+`ksor-gateway-floor-missing`, `ksor-gateway-no-tools`,
+`ksor-gateway-unloadable`. Full detail:
+`node_modules/@panaversity/ksor/docs/tool-surface.md`.
+
 ## Withdrawing a document — `ksor takedown`
 
 A takedown is the one governance act that must reach EVERY surface at once.

package/templates/scaffold/system/gateways/content.ts

@@ -0,0 +1,162 @@
+/**
+ * The default registration — and the ORIGINAL of the file `ksor init` emits.
+ *
+ * This is the canonical half of decision 18's mechanism, applied to the agent
+ * surface: one rule, two places, asserted rather than trusted. The scaffold's
+ * `system/gateways/content.ts` is this file byte-for-byte below the import
+ * block, and `default-gateway-drift.test.ts` fails on the line that diverges.
+ *
+ * Two places rather than one is forced, not chosen. Node refuses to type-strip
+ * any `.ts` under `node_modules` — `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`,
+ * with no flag to lift it — so the published package cannot import its own
+ * emitted template as a fallback. The compiled twin is how a deleted file still
+ * serves, and the drift test is what stops the twins disagreeing.
+ *
+ * Everything below the import block is what an adopter owns: tool names, titles,
+ * what the record says it covers, input schemas, annotations, and which tools
+ * exist at all. What it composes — handlers, output schemas, and the FLOOR text
+ * — stays in the package, because those are the citation and abstention
+ * guarantees and a hand-written handler is the one thing no shape check catches.
+ */
+
+import {
+  composeInstructions,
+  FLOOR,
+  MAX_OUTLINE_LIMIT,
+  MAX_SEARCH_K,
+  McpServer,
+  outlineHandler,
+  OUTLINE_OUTPUT,
+  READ_ONLY,
+  READ_OUTPUT,
+  readHandler,
+  SEARCH_OUTPUT,
+  searchHandler,
+  z,
+  type ServiceContext,
+} from "@panaversity/ksor/gateway";
+
+export default function buildGateway(ctx: ServiceContext, version: string): McpServer {
+  const server = new McpServer(
+    // The MCP server name agents see. Change it to your record's name.
+    { name: "ksor", version },
+    // instance.md's body is this record's system prompt, preserved beneath the
+    // framework floor. Leave this alone unless you mean to replace the prompt.
+    { instructions: composeInstructions(ctx.instance.instructions) },
+  );
+
+  server.registerTool(
+    "search",
+    {
+      title: "Search the record",
+      // WHAT THIS RECORD COVERS goes first — it is how an agent with several
+      // records attached decides to ask yours. Say the subject AND the
+      // boundary; the second half prevents more wrong calls than the first:
+      //
+      //   description: `Employee handbook: leave, benefits, conduct, expenses.
+      //   Not product documentation and not customer data.\n\n${FLOOR.search}`,
+      //
+      // FLOOR.search must stay. It tells an agent how to read an abstention and
+      // that corpus text is untrusted; the door checks it is still there at boot.
+      description: FLOOR.search,
+      inputSchema: z.object({
+        query: z
+          .string()
+          .min(1)
+          .max(2000)
+          .describe("A focused question or phrase to search the record for"),
+        // `k` is the lever on reply size: 10 costs an agent ~3,500 tokens a
+        // call, 5 costs ~2,000. Lower it to what your record actually needs —
+        // a caller can always ask for more.
+        k: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_SEARCH_K)
+          .default(10)
+          .describe(`Maximum passages to return (1–${MAX_SEARCH_K})`),
+      }),
+      outputSchema: SEARCH_OUTPUT,
+      annotations: READ_ONLY,
+    },
+    searchHandler(ctx),
+  );
+
+  // Delete a tool by deleting its block. Measured: outline and read together
+  // cost ~1,643 tokens of context that is resident for an agent's whole
+  // session, whether or not it ever calls them.
+  server.registerTool(
+    "outline",
+    {
+      title: "Outline the record",
+      description: FLOOR.outline,
+      inputSchema: z.object({
+        node: z
+          .string()
+          .optional()
+          .describe("Slug or '/'-path to drill into; omit to browse the top level"),
+        depth: z.number().int().min(0).max(5).optional().describe("Extra levels below the anchor"),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_OUTLINE_LIMIT)
+          .default(200)
+          .describe("Maximum rows in ONE page"),
+        offset: z
+          .number()
+          .int()
+          .min(0)
+          .optional()
+          .describe("Rows to skip — pass the previous response's next_offset to continue"),
+      }),
+      outputSchema: OUTLINE_OUTPUT,
+      annotations: READ_ONLY,
+    },
+    outlineHandler(ctx),
+  );
+
+  server.registerTool(
+    "read",
+    {
+      title: "Read a document",
+      description: FLOOR.read,
+      inputSchema: z.object({
+        slug: z.string().min(1).describe("The document's slug or '/'-qualified path (see outline)"),
+        heading: z
+          .string()
+          .optional()
+          .describe(
+            "Restrict to one section subtree: a full heading path, any prefix of one, or a " +
+              "section's last segment when it is unique in the document",
+          ),
+        from_heading: z
+          .string()
+          .optional()
+          .describe("Window cursor from a previous response's next"),
+        snapshot_token: z
+          .string()
+          .optional()
+          .describe(
+            'The "token" string from a search response\'s "snapshot" object — not the object.',
+          ),
+        token_budget: z
+          .number()
+          .int()
+          .min(100)
+          .max(70000)
+          .optional()
+          .describe("Response size budget in tokens (default 70000)"),
+      }),
+      outputSchema: READ_OUTPUT,
+      annotations: READ_ONLY,
+    },
+    readHandler(ctx),
+  );
+
+  // Add your own tools here with ordinary registerTool + zod. They are yours;
+  // ksor makes no provenance claim about a tool it did not hand you a handler
+  // for, and the boot check only inspects the ones it did.
+
+  return server;
+}