@panaversity/ksor 0.0.7 → 0.0.9

package/templates/scaffold/README.md

@@ -31,32 +31,53 @@ part of `pnpm dev`. The ordered path is:
 
 ```sh
 cp .env.example .env    # fill in KSOR_DB_URL, GEMINI_API_KEY, KSOR_AUTH_DISABLED=1
-pnpm serve             # schema → grant → ingest → serve
+pnpm provision         # once: apply the schema, authorize ingest
+pnpm refresh           # ingest the record, collect retired generations
+pnpm serve             # the MCP server
 ```
 
 `ksor` reads `.env` automatically — nothing to export. `KSOR_AUTH_DISABLED=1`
 is required for a local run: serve refuses to boot unauthenticated on purpose,
 so a server is never open by accident.
 
-Add one block to `instance.md` first — `database: { dsn_env: KSOR_DB_URL }`,
-the NAME of the variable, never the DSN. That is the whole required config:
+Uncomment the `database:` block already in `instance.md` — it names the
+VARIABLE holding your DSN, never the DSN itself. That is the whole required
+config:
 `embedding:` already defaults to Gemini at 1536 dimensions, and leaving
 `retrieval:` out starts you with the abstention gate off and honest about it
 (turn it on afterwards with `ksor calibrate`, once the record is serving).
 
-`pnpm serve` is the only command this rung needs — first run, after editing
-`knowledge/`, or just to bring the server back. A rerun on an unchanged record
+`pnpm provision` runs once — it applies the schema (or migrates it forward) and
+authorizes ingest, the two privileged acts that should not happen on every
+boot. After that: `pnpm refresh` publishes what you have edited, and `pnpm serve`
+runs the server. They are separate because publishing is an act, not a side
+effect of starting a process. A rerun on an unchanged record
 costs nothing: no new generation, no embedding, no rows. Edit a document and
 the next run picks up exactly that change. `AGENTS.md` → "Serving to agents" is the
-full runbook; your coding agent reads it first. `pnpm serve` binds loopback
-with auth off for local use; a public bind fails closed unless auth is
-configured. Any other operation is `pnpm exec ksor <verb>`.
+full runbook; your coding agent reads it first. `pnpm serve` refuses to boot
+unauthenticated: a local run declares `KSOR_AUTH_DISABLED=1` (already in
+`.env.example`) and binds loopback, so a server is never left open by accident;
+a public bind needs a configured SSO door instead. Any other operation is
+`pnpm exec ksor <verb>`.
 
 Then talk to your coding agent — `AGENTS.md` carries the working rules, and
 the agent kit in `.agents/skills/` knows how to interview you
 (`intake-interview`), convert your source material (`add-sources`), and keep
 the record well-formed (`format-checker`, also `pnpm check`).
 
+### A note on the lockfile
+
+The committed `pnpm-lock.yaml` covers the site. It cannot cover
+`@panaversity/ksor` itself, because the version pinned in `package.json` is
+stamped by the CLI that scaffolded this project and could not be resolved before
+that happened. So your FIRST `pnpm install` writes it — run it before you push,
+and commit the result.
+
+The deploy config already accounts for this (`vercel.json` installs with
+`--no-frozen-lockfile`), and the shipped `validate.yml` runs no install. If you
+add CI of your own, note that pnpm turns on `--frozen-lockfile` automatically
+whenever `CI` is set.
+
 ## The files, explained
 
 Nothing here is decoration, and the dotfiles are not ceremony — each one is a
@@ -100,6 +121,22 @@ and anything that can serve files can serve it.
   outside it), build with `pnpm build`, serve `system/site/out/`. If the
   build image's pnpm predates the `packageManager` pin, set the
   `ENABLE_EXPERIMENTAL_COREPACK=1` build environment variable.
+**Once `instance.md` declares a `database:`, the BUILD needs the DSN too.**
+`pnpm build` first runs `pnpm export-denylist`, which asks the record's
+database what has been withdrawn (`ksor takedown --export`) and writes
+`.ksor-denylist.json` for the site to read. Without it the build stops:
+
+```
+KSOR_DB_URL is unset, and instance.md declares a database
+  why: a takedown lives in that database. Without it this build cannot tell
+  'nothing is denied' from 'nobody asked'
+```
+
+That is deliberate — a site built without asking would publish a document you
+withdrew. Give the build environment the same `KSOR_DB_URL` your server uses
+(read access is enough), or keep the record database-free, where the export
+writes "nothing denied" and exits 0.
+
 - **GitHub Pages, nginx, S3, anything static** — run `pnpm build` and
   upload `system/site/out/`. Hosted under a sub-path (like
   `user.github.io/repo`)? Build with `KSOR_BASE_PATH=/repo pnpm build`.

package/templates/scaffold/env.example

@@ -2,8 +2,11 @@
 # A real environment variable always wins over this file, so CI and production
 # keep their own values.
 
-# The Postgres store, named by instance.md's database.dsn_env.
-# Needs the pgvector extension: CREATE EXTENSION vector;
+# The Postgres store, named by instance.md's database.dsn_env — uncomment the
+# `database:` block there first. Needs the pgvector extension:
+# CREATE EXTENSION vector;
+# On a remote host prefer sslmode=verify-full, which states the TLS posture
+# explicitly instead of relying on a driver default that is due to change.
 KSOR_DB_URL=postgresql://user:password@host:5432/dbname
 
 # The embedding provider key. instance.md defaults to gemini-embedding-001.
@@ -17,7 +20,84 @@ GEMINI_API_KEY=
 #   KSOR_SSO_URL=https://your-sso.example.com
 #   KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
 #   KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
+# The JWKS endpoint defaults to <KSOR_SSO_URL>/api/auth/jwks, which is Better
+# Auth's layout. EVERY other provider — Auth0, Okta, Entra, Keycloak, Cognito —
+# publishes its keys elsewhere, and a wrong JWKS URL fails as a TRANSIENT fetch
+# error, so every request 503s with nothing naming the cause. Say where the keys
+# are:
+#   KSOR_JWKS_URL=https://your-sso.example.com/.well-known/jwks.json
 # Serving a public bind with auth off additionally requires
 # KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1, which serves your whole record to anyone
 # who can reach the port.
 KSOR_AUTH_DISABLED=1
+
+# ── Production knobs ────────────────────────────────────────────────────────
+# Unset is fine for a local run; each one matters once this serves for real.
+
+# Snapshot-token signing keys, "kid=secret[,kid2=secret2]" (first is active).
+# WITHOUT this the key is generated per PROCESS. Two deployments need it, not
+# just one: any MULTI-REPLICA deploy (a token minted by one replica is refused
+# by another), and any SCALE-TO-ZERO host, where a single replica mints a new
+# key on every cold start — so a snapshot issued before a scale-down stops
+# validating after it, even with one instance.
+# KSOR_SNAPSHOT_KEYS=v1=<32+ random bytes>
+
+# Which audience tier this server serves, when instance.md declares
+# `audiences:`. Unset = the least-privileged tier. Same variable the site's
+# per-audience build reads, so both surfaces mean the same thing.
+# KSOR_AUDIENCE=public
+
+# Bind. PORT is honoured too, for hosts that inject it.
+# KSOR_MCP_HOST=127.0.0.1
+# KSOR_MCP_PORT=8080
+
+# Request caps and pool sizing.
+# KSOR_MAX_INFLIGHT=64
+# KSOR_MAX_BODY_BYTES=1000000
+# KSOR_CONTENT_POOL_MAX=20       # ceiling under load
+# By DEFAULT ksor holds NO open database connection when idle: the pool's
+# minimum is 0 and an unused connection is closed after KSOR_CONTENT_POOL_IDLE_MS.
+# Raising the minimum above 0 makes the server open that many connections at
+# boot and KEEP them — a warm first request, paid for with sockets held open
+# against your database. Opt in only if cold-start latency matters more.
+# KSOR_CONTENT_POOL_MIN=0
+# KSOR_CONTENT_POOL_IDLE_MS=10000
+# KSOR_DRAIN_TIMEOUT_MS=8000     # hard deadline on shutdown; stay under the ~10s
+#                                 a scale-to-zero runtime allows before SIGKILL
+
+# Public-door hardening. Both default to the safe posture; set them when a
+# proxy or a browser client sits in front and you know the exact names.
+#   KSOR_ALLOWED_HOSTS=records.example.com     Host header allow-list (DNS-rebind defence)
+#   KSOR_ALLOWED_ORIGINS=https://app.example.com   browser Origin allow-list
+# Naming the issuer adds one more check to every token, for one variable:
+#   KSOR_SSO_ISSUER=https://your-sso.example.com
+
+# Connection behaviour. Unset is right for almost everyone; these exist for a
+# deployment that has measured something.
+#   KSOR_DB_CONNECT_PER_REQUEST=1  close the connection when each call finishes,
+#                                  instead of returning it to the pool. OFF by
+#                                  default because the default measures better:
+#                                  a quiet server already holds ZERO connections
+#                                  (min 0 + a 10s idle window), and inside a
+#                                  burst the handshake is paid once. Measured on
+#                                  loopback: 2.58ms/call per-request against
+#                                  0.13ms pooled, and a remote TLS endpoint
+#                                  widens that. Turn it on where per-request
+#                                  connection is genuinely cheaper — a local
+#                                  pooler sidecar, or a runtime that reuses no
+#                                  process between invocations.
+#   KSOR_DB_POOLED_ENDPOINT=1     force "this DSN is a transaction pooler" when
+#                                 the host name does not say so
+#   KSOR_READ_RETRY_ATTEMPTS=5    retries for a read that fails at the CONNECTION
+#                                 level — a waking serverless compute
+#   KSOR_READ_RETRY_BACKOFF_S=1.0 linear backoff between those attempts
+
+# Ingest safety. A corpus that shrinks by more than this FRACTION (0.15 = 15%)
+# refuses to flip; KSOR_ALLOW_SHRINK=1 is how you say a big deletion is meant.
+# KSOR_MAX_SHRINK=0.15
+# KSOR_ALLOW_SHRINK=1
+
+# Embedding timeouts and cache (tuning only; unset is sensible).
+# KSOR_EMBED_TIMEOUT_S=30
+# KSOR_QUERY_EMBED_TIMEOUT_S=10
+# KSOR_EMBED_CACHE_MAX=1000

package/templates/scaffold/gitignore

@@ -15,3 +15,7 @@ system/site/.staged-knowledge/
 !.env.example
 
 .DS_Store
+
+# The takedown manifest the site build reads — exported from the database,
+# never hand-edited, and re-exported on every build.
+.ksor-denylist.json

package/templates/scaffold/instance.md

@@ -4,6 +4,20 @@ name: KSOR-STAMP-NAME
 ksor:
   requires: ">=KSOR-STAMP-VERSION"
   scaffolded: "KSOR-STAMP-VERSION"
+# The served MCP rung needs ONE required block: the NAME of the environment
+# variable holding your Postgres DSN — never the DSN itself. Uncomment it, copy
+# .env.example to .env, then run `pnpm serve`. Nothing else here is required:
+# `embedding:` already defaults to Gemini at 1536 dimensions, and leaving
+# `retrieval:` out starts you with the abstention gate off and honest about it
+# (turn it on afterwards with `ksor calibrate`, once the record is serving).
+# database:
+#   dsn_env: KSOR_DB_URL
+# Where agents reach this record's MCP surface, and the semver it publishes as.
+# Both go into /.well-known/mcp/server.json, the document an agent reads to
+# DISCOVER this record instead of being told the URL. Leave mcp_url out until
+# the server is actually published: an invented URL is worse than none.
+# mcp_url: https://records.example.com/mcp
+# version: 0.1.0
 ---
 
 # Knowledge System of Record

package/templates/scaffold/package.json

@@ -5,12 +5,16 @@
   "type": "module",
   "scripts": {
     "dev": "pnpm -C system/site dev",
-    "build": "pnpm -C system/site build",
+    "build": "pnpm export-denylist && pnpm -C system/site build",
+    "export-denylist": "ksor takedown --instance instance.md --export .ksor-denylist.json",
     "check": "node .agents/skills/format-checker/check.mjs",
-    "serve": "pnpm schema && pnpm grant && pnpm ingest && ksor serve",
+    "provision": "pnpm schema && pnpm grant",
+    "serve": "ksor serve",
+    "refresh": "pnpm ingest && pnpm gc",
     "schema": "ksor schema --instance instance.md --apply",
     "grant": "ksor grant --instance instance.md",
-    "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip"
+    "ingest": "ksor ingest --instance instance.md --knowledge knowledge --flip",
+    "gc": "ksor gc --instance instance.md"
   },
   "dependencies": {
     "@panaversity/ksor": "KSOR-STAMP-VERSION"

package/templates/scaffold/system/site/app/.well-known/mcp/server.json/route.ts

@@ -0,0 +1,45 @@
+import { appName, mcpEndpoint, mcpNamespace, recordVersion } from "@/lib/shared";
+
+/**
+ * `/.well-known/mcp/server.json` — how an agent DISCOVERS this record's MCP
+ * surface without being told the URL.
+ *
+ * AGENTS.md's critical rule 3 names this as one of the surfaces that must not
+ * break, because agents finding a KSoR is how a KSoR gets used. A document a
+ * validating client rejects is a broken surface, so this follows the published
+ * schema rather than an approximation of it:
+ *
+ *   $schema      recommended, and it is what tells a reader which revision
+ *                this document claims to satisfy.
+ *   name         REQUIRED, and must match ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$ —
+ *                a namespace, one slash, an identifier. `instance.md`'s bare
+ *                `name:` has no slash, so it was rejected outright.
+ *   version      REQUIRED. Absent, the document failed validation on its own.
+ *   capabilities NOT a field in the schema; it was invented here.
+ *
+ * (Checked against the 2025-12-11 schema, round-6 review of #43, which built
+ * the scaffold and validated the emitted file.)
+ *
+ * Static-exported alongside the site, so it is served by whatever host serves
+ * the record's pages and needs no runtime.
+ */
+export const dynamic = "force-static";
+
+const SCHEMA = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
+
+export function GET(): Response {
+  const endpoint = mcpEndpoint();
+  return Response.json(
+    {
+      $schema: SCHEMA,
+      name: `${mcpNamespace()}/${appName}`,
+      description: `The ${appName} Knowledge System of Record: governed markdown served with citations and honest abstention.`,
+      version: recordVersion(),
+      // Absent until the owner declares where the server runs — an invented
+      // URL is worse than none, because an agent would try it and conclude the
+      // record is down rather than unpublished.
+      ...(endpoint === null ? {} : { remotes: [{ type: "streamable-http", url: endpoint }] }),
+    },
+    { headers: { "cache-control": "public, max-age=300" } },
+  );
+}

package/templates/scaffold/system/site/lib/audience-rule.ts

@@ -0,0 +1,44 @@
+/**
+ * The audience rule, alone, with no imports and no side effects.
+ *
+ * CANONICAL COPY: `packages/content/src/lib/audience-rule.ts`. The scaffold's
+ * site carries a byte-identical copy at
+ * `system/site/lib/audience-rule.ts`, and `audience-rule-drift.test.ts`
+ * fails if the two ever differ. The site cannot simply import the kernel: its
+ * lib is deliberately dependency-light and runs inside Next's build, while the
+ * kernel package carries pg and the embedding providers.
+ *
+ * Why the rule gets its own file at all: the site and the kernel enforce the
+ * same visibility rule in two languages — TypeScript here, SQL in
+ * `audience.ts` — and it drifted four separate times while each side's own
+ * tests stayed green, because each side was internally consistent with itself.
+ * `AUDIENCE_CASES` is the shared decision table both are asserted against, and
+ * this file is the shared implementation of the TypeScript half.
+ */
+
+export interface AudienceModel {
+  /** Least- to most-restricted, `public` first. */
+  readonly audiences: readonly string[];
+  /** The tier of a document that declares no `visibility:`. */
+  readonly defaultVisibility: string;
+}
+
+/**
+ * May a build FOR `audience` publish a document of this `visibility`?
+ *
+ * `model === null` is a record that declares no audience model: nothing to
+ * filter, everything publishes — the level-0 shape.
+ */
+export function decideVisible(
+  model: AudienceModel | null,
+  audience: string,
+  visibility: string | null,
+): boolean {
+  if (model === null) return true;
+  const value = visibility === null || visibility === "" ? model.defaultVisibility : visibility;
+  const rank = model.audiences.indexOf(value);
+  // An undeclared visibility is refused, never published: a value no build
+  // understands is a typo, and a typo reads as a restriction.
+  if (rank === -1) return false;
+  return rank <= model.audiences.indexOf(audience);
+}

package/templates/scaffold/system/site/lib/audience.ts

@@ -1,3 +1,4 @@
+import { decideVisible, type AudienceModel } from "./audience-rule";
 import { instanceFrontmatter } from "./shared";
 
 /**
@@ -15,12 +16,8 @@ import { instanceFrontmatter } from "./shared";
  * that declares no audiences has no model and publishes every document —
  * the behaviour of every instance written before this key existed.
  */
-export interface AudienceModel {
-  /** Least- to most-restricted, `public` first. */
-  readonly audiences: readonly string[];
-  /** The tier of a document that declares no `visibility:`. */
-  readonly defaultVisibility: string;
-}
+export type { AudienceModel };
+export { decideVisible };
 
 function unquote(raw: string): string {
   const trimmed = raw.trim();
@@ -157,14 +154,7 @@ export const buildAudience: string = resolveBuildAudience(audienceModel);
 
 /** Whether a document of this visibility belongs in THIS build. */
 export function visibleInBuild(visibility: string | null): boolean {
-  if (audienceModel === null) return true;
-  const value =
-    visibility === null || visibility === "" ? audienceModel.defaultVisibility : visibility;
-  const rank = audienceModel.audiences.indexOf(value);
-  // An undeclared visibility is refused, never published: a value no build
-  // understands is a typo, and a typo reads as a restriction.
-  if (rank === -1) return false;
-  return rank <= audienceModel.audiences.indexOf(buildAudience);
+  return decideVisible(audienceModel, buildAudience, visibility);
 }
 
 /**

package/templates/scaffold/system/site/lib/denial-rule.ts

@@ -0,0 +1,212 @@
+/**
+ * The denial rule, alone, with no imports and no side effects.
+ *
+ * CANONICAL COPY: `packages/content/src/lib/denial-rule.ts`. The scaffold's
+ * site carries a byte-identical copy at `system/site/lib/denial-rule.ts`, and
+ * `denial-rule-drift.test.ts` fails if the two ever differ — the same
+ * arrangement decision 18 made for the audience rule, and for the same reason:
+ * the site cannot import the kernel, whose package carries pg and the embedding
+ * providers.
+ *
+ * Why it is a leaf: these functions decide whether a withdrawn document gets
+ * published, and they lived inside a module that reads `instance.md` at import
+ * time — so none of them could be tested as rules. A round-8 mutation made
+ * `isDenied` return false unconditionally, which publishes every withdrawn
+ * document to `/docs` and `llms.txt`, and the entire suite stayed green.
+ */
+
+/** The shape `ksor takedown --export` writes. */
+export interface DenylistManifest {
+  format?: number;
+  corpus_id?: string;
+  source?: string;
+  denied?: { stable_id?: string; scope?: string }[];
+  denied_subtrees?: string[];
+}
+
+/**
+ * Is this document denied? Exact ids, plus the directories a `--subtree`
+ * takedown governs.
+ *
+ * `ksor takedown --export` expands a `--subtree` denial to its actual
+ * descendants by walking parent_id, where the tree lives. Interpreting SCOPE
+ * here meant prefix-matching stable_ids, and a section's stable_id ends in
+ * `/index` (or `#section`), so the prefix never matched its children and every
+ * descendant kept publishing — the failure decision 14 records as the reason
+ * its own walk uses parent_id rather than a prefix.
+ *
+ * But an expanded list can only name what the ACTIVE GENERATION contains, and
+ * the site reads DISK. A document added under a withdrawn section after the
+ * last ingest is on disk and not in the database, so subtree denials also
+ * arrive as DIRECTORIES. That is not the rejected prefix match: those paths
+ * come from `sources.origin_path`, so they are real locations on disk, and a
+ * document's location cannot be decoupled from itself by a frontmatter
+ * `sor_id:` the way its id can.
+ *
+ * `recordPath` is in the record's own frame (it starts with the record
+ * directory's name), because that is the frame `origin_path` uses.
+ */
+export function isDenied(
+  manifest: DenylistManifest,
+  stableId: string,
+  recordPath: string,
+): boolean {
+  if ((manifest.denied ?? []).some((d) => String(d.stable_id) === stableId)) return true;
+  return (manifest.denied_subtrees ?? []).some((dir) => {
+    const prefix = String(dir).replace(/\\/g, "/");
+    if (prefix === "/") return true;
+    return recordPath.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`);
+  });
+}
+
+/**
+ * A plain scalar, read the way the kernel's frontmatter reader reads one.
+ *
+ * The two diverged on a TRAILING COMMENT: the kernel strips `# …` from an
+ * unquoted scalar and the site kept it, so `sor_id: hr/policy # renamed 2026`
+ * gave the kernel `hr/policy` and the site `hr/policy # renamed 2026`. A
+ * takedown on the id the MCP door reports as `provenance.stable_id` was then
+ * denied by the door and silently ignored by the site build, which kept
+ * publishing the document.
+ *
+ * A comment cannot appear inside a QUOTED scalar's value, so quoting is
+ * resolved first — exactly the kernel's order.
+ *
+ * `ok: false` marks a value the kernel's reader REFUSES rather than reads: a
+ * flow collection, an anchor, a block scalar, or anything with a `: ` in it.
+ * That matters because refusing one line poisons the whole map — see
+ * `frontmatterMap`.
+ */
+export function scalarLike(raw: string | undefined): string | undefined {
+  if (raw === undefined) return undefined;
+  const parsed = readScalar(raw.trim());
+  return parsed.kind === "string" ? parsed.value : undefined;
+}
+
+/**
+ * Plain scalars the kernel's reader converts to a bool, null, int or float —
+ * never a string, so they can never be an id.
+ */
+const YAML_TYPED =
+  /^(?:true|True|TRUE|false|False|FALSE|yes|Yes|YES|no|No|NO|on|On|ON|off|Off|OFF|~|null|Null|NULL|[-+]?[0-9][0-9_]*|[-+]?(?:\.[0-9]+|[0-9][0-9_]*\.[0-9_]*)(?:[eE][-+]?[0-9]+)?)$/;
+
+/**
+ * Three outcomes, because the kernel's reader has three:
+ *
+ *   string    a plain or quoted string — usable as an id.
+ *   typed     a bool, null, int or float. The kernel KEEPS the key with a
+ *             non-string value, and `stableIdOf` requires a string, so the
+ *             override is dropped. The key exists; it just is not an id.
+ *   refused   a shape the reader will not read at all. The kernel POISONS the
+ *             whole map on one of these.
+ *
+ * Collapsing `typed` into `refused` would empty the map for a document whose
+ * `order: 3` is perfectly ordinary — which the kernel does not do.
+ */
+interface ScalarRead {
+  readonly kind: "string" | "typed" | "refused";
+  readonly value: string;
+}
+
+function readScalar(raw: string): ScalarRead {
+  // An EMPTY value is `null` to the kernel — the key exists and is not a
+  // string, exactly like a bool or a number.
+  if (raw === "") return { kind: "typed", value: "" };
+  const dq = /^"(.*)"$/.exec(raw);
+  if (dq !== null)
+    return { kind: "string", value: (dq[1] ?? "").replace(/\\"/g, '"').replace(/\\\\/g, "\\") };
+  const sq = /^'(.*)'$/.exec(raw);
+  if (sq !== null) return { kind: "string", value: (sq[1] ?? "").replace(/''/g, "'") };
+  const plain = raw.replace(/[ \t]+#.*$/, "").trim();
+  // The shapes the kernel's reader does not hand back as a STRING. Two groups,
+  // and both matter for the same reason:
+  //
+  //   refused    a flow collection, an anchor, a block scalar, a plain value
+  //              containing ": " — the kernel returns ok:false and poisons the
+  //              whole map.
+  //   typed      a YAML bool, null, int or float — the kernel returns them as
+  //              non-strings, and `stableIdOf` requires a string, so it DROPS
+  //              the override. `sor_id: 4711` therefore resolved to the path on
+  //              the kernel and to "4711" here: a takedown honoured by the door
+  //              and ignored by the site build, the same divergence round 9
+  //              closed for comments and flow lists, in the same function
+  //              (round-10 review of PR 43).
+  //
+  // Both are `ok: false` here because both end with the site NOT taking an
+  // override — which is what the kernel does. Kept in step with `scalarValue`
+  // in ingest/adapters/plain-tree.ts and bound to it by
+  // `stable-id-conformance.test.ts`.
+  if (/:[ \t]/.test(plain) || plain.endsWith(":")) return { kind: "refused", value: "" };
+  if (/^[|>&*!{[]/.test(plain)) return { kind: "refused", value: "" };
+  if (YAML_TYPED.test(plain)) return { kind: "typed", value: "" };
+  return { kind: "string", value: plain };
+}
+
+/**
+ * The frontmatter block as a map, read the way the KERNEL reads it — including
+ * the part that looks like a bug and is load-bearing: if ANY top-level line is
+ * a shape the reader refuses, the WHOLE map comes back empty.
+ *
+ * That behaviour is inherited from the oracle's PyYAML path, and mirroring it
+ * is not optional. The site read `sor_id:` with a bare regex, so a document
+ * carrying an ordinary flow list —
+ *
+ *     title: Policy
+ *     tags: [hr, payroll]
+ *     sor_id: hr/policy
+ *
+ * — got `hr/policy` here and `knowledge/policies/policy` from the kernel, which
+ * drops the override with the poisoned map. A takedown then matched on exactly
+ * one surface: denied by the MCP door, ignored by the site build, published to
+ * /docs and llms.txt. That is the failure decisions 14 and 18 exist to stop,
+ * re-entered through the denial rule (round-9 review of PR 43).
+ */
+export function frontmatterMap(block: string): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const line of block.split(/\r?\n/)) {
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    if (/^[ \t]/.test(line)) continue; // nested structure — no top-level scalar
+    const kv = /^([^\s:]+):(?:[ \t]+(.*))?$/.exec(line);
+    const key = kv?.[1];
+    if (key === undefined) return {};
+    const parsed = readScalar((kv?.[2] ?? "").trim());
+    if (parsed.kind === "refused") return {};
+    // A typed value is present in the kernel's map and is not a string; this
+    // map holds strings, so the key is simply absent — which is what every
+    // consumer here needs to know about it.
+    if (parsed.kind === "string") map[key] = parsed.value;
+  }
+  return map;
+}
+
+/**
+ * The file's path in the frame the RECORD uses — `sources.origin_path`, which
+ * is project-root relative and therefore starts with the record directory's
+ * own name. `relPath` is the file's path relative to the record directory,
+ * with forward slashes.
+ */
+export function recordPathFrom(recordName: string, relPath: string): string {
+  return `${recordName}/${relPath}`;
+}
+
+/**
+ * The record's stable_id for a file, mirroring the kernel's adapter —
+ * INCLUDING the `sor_id:` frontmatter override.
+ *
+ * Deriving it from the path alone meant a takedown of any document carrying an
+ * `sor_id:` never matched here and it stayed published, while the MCP door
+ * denied it: the same decoupling decision 14 records as the reason the subtree
+ * walk uses parent_id rather than a prefix.
+ */
+export function stableIdFrom(
+  recordName: string,
+  relPath: string,
+  frontmatterBlock: string,
+): string {
+  // Through the MAP, not a bare regex on the block: the kernel drops the whole
+  // map when any line is a shape it refuses, and an id the two surfaces read
+  // differently is a takedown that lands on one of them.
+  const override = frontmatterMap(frontmatterBlock)["sor_id"];
+  if (override !== undefined && override !== "") return override;
+  return `${recordName}/${relPath.replace(/\.md$/i, "")}`;
+}

package/templates/scaffold/system/site/lib/shared.ts

@@ -58,3 +58,51 @@ function readInstanceTitle(): string {
 }
 
 export const appTitle: string = readInstanceTitle();
+
+/**
+ * Where this record's MCP surface is published, if the owner has said.
+ *
+ * `null` when they have not: an invented URL is worse than none, because an
+ * agent would try it and conclude the record is down rather than unpublished.
+ */
+export function mcpEndpoint(): string | null {
+  const declared = /^mcp_url:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[1] ?? "";
+  const value = declared.trim().replace(/^["']|["']$/g, "");
+  return value === "" ? null : value;
+}
+
+/**
+ * The namespace half of the MCP `name`, which the schema requires to look like
+ * `<namespace>/<identifier>` — a bare record name has no slash and is rejected
+ * by a validating client (round-6 review of #43).
+ *
+ * Derived from the published MCP URL's host in reverse-DNS order, which is the
+ * convention and is something the owner has already declared rather than a
+ * second thing to configure. With no URL declared there is nothing published to
+ * namespace, so the local-only namespace says exactly that.
+ */
+export function mcpNamespace(): string {
+  const endpoint = mcpEndpoint();
+  if (endpoint === null) return "local";
+  try {
+    const host = new URL(endpoint).hostname;
+    const labels = host.split(".").filter((l) => l !== "");
+    // A bare host or an IP literal cannot be reversed into a namespace
+    // meaningfully; "local" is honest about that.
+    if (labels.length < 2 || /^\d+$/.test(labels[labels.length - 1] ?? "")) return "local";
+    return labels.reverse().join(".");
+  } catch {
+    return "local";
+  }
+}
+
+/**
+ * The version this record publishes as. The record's own generation is not a
+ * semver, and the schema wants one, so this reads an explicit `version:` from
+ * instance.md and falls back to a first-release default.
+ */
+export function recordVersion(): string {
+  const declared = /^version:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[1] ?? "";
+  const value = declared.trim().replace(/^["']|["']$/g, "");
+  return /^\d+\.\d+\.\d+/.test(value) ? value : "0.1.0";
+}