@ultimat3/manifest 1.1.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,88 @@
+# @ultimat3/manifest — boundary
+
+Tier 4. May import tier 0–3: `core schema i18n money time cache seo entity policy http action
+query jobs realtime`. **Never** `render mcp ai pwa ui admin testing cli`.
+
+Route, policy, task and locale facts come from tier 4 / per-app code, so they are **injected**
+by the CLI, not imported.
+
+## Owns
+
+| File | Job |
+|---|---|
+| `schema.ts` | the manifest's typed shape + `MANIFEST_VERSION` |
+| `build.ts` | `buildManifest` — pure, deterministic, stably sorted |
+| `sources.ts` | wires `describe*` from entity/action/query/jobs into `ManifestSources` |
+| `diff.ts` | `diffManifest` — breaking / additive / internal |
+| `verify.ts` | `verifyContract` — the major-bump gate |
+| `emit.ts` | canonical serialisation, write, `--json`, drift check |
+| `agents-md.ts` | read-only AGENTS.md existence + size check |
+| `docs-scan.ts` | read-only: an installed package tree → `DocEntry[]`. Never writes |
+| `docs-search.ts` | pure ranking of `DocEntry[]` against a question. No I/O, no clock |
+
+## Invariants
+
+- **No nondeterminism.** No timestamp, git sha, hostname, counter, or unsorted iteration.
+  `buildManifest` is pure — it must never read a registry, a clock, or the filesystem.
+- Top-level key order in the file is fixed by `KEY_ORDER` in `emit.ts`.
+- `buildId` = sha256 of the canonical body. Verifiable from the file alone.
+- Job `steps` keep declared order. Everything else sorts.
+- `permissions` is derived, never a second declared list — and derived from each operation's own
+  `permissions`, **never from `policy`**. `policy` is a DISPLAY label: a composite renders as
+  `and(post:publish, org:administer)`, which is not a permission and matches no grant, so deriving
+  from it published one fictional entry per composite rule and dropped every real one.
+- **An operation's own `permissions` and `rateLimit` are contract, and `diff.ts` classifies both.**
+  A permission gained is breaking (every caller holding the old grant set starts collecting 403s
+  and no schema in the file moved); one dropped is additive but reported, because a widening of
+  access is what a reviewer most needs to see. A rate limit tightened — in burst OR in refill rate,
+  compared cross-multiplied so no rounding can invent a change — is breaking, and so is
+  introducing one where there was none; loosening or removing is additive.
+- **An absent `permissions` is NOT an empty one.** Unlike `mcp.expose` there is no value to fold
+  absence into: `[]` asserts "this operation requires nothing", so reading an absent field that
+  way would call every permission of every operation newly required the first time an app diffs
+  against a manifest written before the field existed. Absence is no evidence — the comparison is
+  skipped. Same for a `rateLimit` neither half of which `toBucket` would accept.
+- **`isManifest` checks every top-level key, never five and a cast.** `diffManifest` reads
+  `before.queries`, `before.jobs`, `before.permissions` and `before.locales` with no guard, so a
+  section a truncated or hand-trimmed file happens not to carry was a bare `TypeError` two calls
+  from the gate that exists to explain. The FACTS inside a section stay unwalked — a manifest
+  written before a field existed is still readable, which is `MANIFEST_VERSION`'s rule.
+- **`--json` is awaited.** `emitManifest({ stdout: true })` writes through `await Bun.write(
+  Bun.stdout, …)`: a write to a pipe is asynchronous and `process.exit()` discards the queue, and
+  this is the largest payload the CLI prints. Same bug `scripts/stdout-truncation.test.ts` pins.
+- **One package's tree costs that package.** `scanInstalledDocs` guards each `scanPackageDocs`,
+  and a `package.json` that will not parse is "not a package", not a `SyntaxError` thrown through
+  the `Promise.all` for every other package to inherit. `node_modules` is not curated and is not
+  stable while an install is running.
+- `agents-md.ts` **never writes**. Generated prose lowers agent task success; facts go in
+  `x.manifest.json` and conventions stay human-authored.
+- `docs-scan.ts` emits **no artifact**. The published tarball is the source, so the docs are
+  already installed; a generated `docs.json` would be a second copy of them, and the second copy
+  is what drifts. There is no drift check for local docs because there is nothing that can drift.
+- `docs-scan.ts` indexes the **file header comment**, not JSDoc: `As of 2026-08`, 99.8% of source
+  files carry a header, 42.3% of public exports carry JSDoc, and `job()` is in the missing 57.7%.
+- A guide topic is unique within its package — repeated headings take a document-order suffix.
+- Neither docs module may import a registry or a clock. `docs-search.ts` is pure; `docs-scan.ts`
+  reads files and nothing else.
+- **A new manifest field ⇒ a `diff.ts` rule for it.** Always — a field nothing classifies is a
+  fact the gate cannot see, which is the whole reason the field was added.
+- **`MANIFEST_VERSION` bumps only when a reader built for the old version would be WRONG** — a
+  field removed, retyped, or given a new meaning — never for one that is merely added. Two costs
+  make the reflex expensive: `isCompatible` is an equality check, so a bump rejects every
+  `x.manifest.json` in existence at once; and `diff.ts` classifies a `manifestVersion` change as
+  **breaking**, so it also demands a major release of every APP that regenerates. Charging every
+  app a major for a field their readers never had to look at is a fix line that is not true.
+  `build.test.ts`'s `shape compatibility` case is the assertion — if it fails, the bump is earned.
+- `diff.ts` reads `mcp.expose` through `isMcpExposed` from `@ultimat3/core`, on **both** sides.
+  `before` is a file parsed off disk, so an older or hand-trimmed manifest can carry an absent or
+  non-boolean value that `!==` would classify from; and the fact `sources.ts` publishes has to be
+  the answer `toMcpTools` gives, or the gate demands a major bump for a tool that never existed.
+
+## Commands
+
+```
+bun test packages/manifest
+bun run --filter @ultimat3/manifest typecheck
+x manifest        # build + emit
+x verify          # drift + contract gate, and the AGENTS.md check under the `manifest` step
+```

package/README.md

@@ -18,17 +18,22 @@ verifyContract({ before: committed, after: manifest });
 |---|---|
 | `routes` | url, render mode, offline strategy, hydrate, revalidate tags, budget |
 | `entities` | table, columns (type, nullability, PK, FK), named invariants |
-| `actions` | input + output schema, policy, cache invalidations, MCP exposure, `mutator` when it is one |
-| `queries` | input schema, policy, live, cache tags |
+| `actions` | input + output schema, policy label, **required permissions**, cache invalidations, declared rate limit, MCP exposure, `mutator` when it is one |
+| `queries` | input schema, policy label, **required permissions**, live, cache tags |
 | `jobs` | input schema, queue, retry policy, step names |
 | `tasks` | cron, tz, jobs enqueued |
 | `policies` | permission, where enforced |
-| `permissions` | **derived** from policies + primitives, never declared twice |
+| `permissions` | **derived** from policies + each operation's own list, never declared twice |
 | `locales`, `errorCodes` | catalogs a tool can enumerate |
 
 Plus `manifestVersion` (shape version, so a reader can check compatibility), `app`, and
 `buildId`.
 
+An operation's `policy` is its **display label** — a composite renders as
+`and(post:publish, org:administer)`, which is not a permission and matches no grant. Match a grant
+against `permissions`; matching on `policy` reports every non-trivially-guarded operation as
+enforcing nothing.
+
 ## Determinism
 
 The file is committed and reviewed, so two builds of the same tree must produce identical
@@ -53,8 +58,8 @@ whole mechanism.
 
 | Class | Examples |
 |---|---|
-| **breaking** | action/query/route/job/entity removed; input or output schema changed; policy changed; MCP exposure withdrawn; column removed, retyped, or made NOT NULL; live query became non-live |
-| **additive** | primitive added; nullable column added; MCP exposure granted; locale added |
+| **breaking** | action/query/route/job/entity removed; input or output schema changed; policy changed; **an operation gained a required permission**; **a rate limit was tightened or introduced**; MCP exposure withdrawn; column removed, retyped, or made NOT NULL; live query became non-live |
+| **additive** | primitive added; nullable column added; a required permission dropped; a rate limit loosened or removed; MCP exposure granted; locale added |
 | **internal** | cache tags changed; render mode changed; job steps reordered; `buildId` |
 
 `verifyContract()` is the gate: a breaking change fails unless the app's **major** version
@@ -87,6 +92,32 @@ past 200 lines, or claims to be generated. Those warnings ride in the step's `ou
 generated half — and unlike the drift check it applies everywhere, including a repo that has
 never run `x manifest`. Enforced, not documented: both codes below can actually fail a build.
 
+## Local docs: read, never emitted
+
+`scanPackageDocs()` / `scanInstalledDocs()` read an installed package tree and return `DocEntry`
+values; `searchDocs()` ranks them against a question. This is what `x docs "how does job() retry"`
+answers from — offline, from `node_modules`, with no filename known in advance.
+
+There is **no generated `docs.json`**, on purpose. The published artifact *is* the source
+(`PUBLISHING.md`): `files` ships `src/**`, `README.md` and `CLAUDE.md`, and Bun runs the
+TypeScript directly. Every doc is therefore already inside the tarball — what was missing was
+retrieval, not payload. A per-package `docs.json` would be a **second copy** of bytes the install
+already has, and the second copy is the one that goes stale. Reading the installed source cannot
+disagree with the installed version, because it *is* the installed version.
+
+| Entry | Source | Topic |
+|---|---|---|
+| `module` | the file header comment on a module `src/index.ts` re-exports, plus its public symbols | `jobs.retry` |
+| `guide` | a `##` section of `README.md` or `CLAUDE.md`, quoted verbatim | `money.README#why-no-floats` |
+
+The **file header** is the doc unit, not JSDoc. Measured across this repo, `As of 2026-08`: 99.8%
+of source files carry a 1–4 line header (2,510 of 2,514), while only 42.3% of public exports have
+JSDoc directly above the declaration (1,868 of 4,414) — `job()` itself has none. Ranking a question
+against 42% coverage would have missed the framework's most-used export.
+
+Same split as `AGENTS.md` above: this module **derives** facts and **quotes** human prose. It
+never writes, and it never synthesises a sentence.
+
 ## Errors
 
 | Code | Meaning | Fix |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "1.1.0",
-    "@ultimat3/core": "1.1.0",
-    "@ultimat3/entity": "1.1.0",
-    "@ultimat3/jobs": "1.1.0",
-    "@ultimat3/query": "1.1.0"
+    "@ultimat3/action": "2.0.0",
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/entity": "2.0.0",
+    "@ultimat3/jobs": "2.0.0",
+    "@ultimat3/query": "2.0.0"
   }
 }

package/src/build.ts

@@ -60,10 +60,15 @@ export function buildManifest(sources: ManifestSources): Manifest {
 
   // Derived, never declared twice: the permission list IS the set of policy permissions
   // plus anything an action asserts. Two lists that must agree eventually disagree.
+  //
+  // Read from `permissions`, never from `policy`. `policy` is a policy's LABEL — for a composite
+  // it renders `and(post:publish, org:administer)`, which is not a permission and matches no
+  // grant, so deriving from it published one fictional entry per composite rule and dropped the
+  // real ones. Every non-trivial rule in a real app is a composite.
   const permissions = unique([
     ...policies.map((p) => p.permission),
-    ...actions.map((a) => a.policy).filter((p): p is string => p !== null),
-    ...queries.map((q) => q.policy).filter((p): p is string => p !== null),
+    ...actions.flatMap((a) => a.permissions),
+    ...queries.flatMap((q) => q.permissions),
   ]);
 
   const body = {
@@ -128,13 +133,17 @@ const normalizeEntity = (entity: EntityFact): EntityFact => ({
   invariants: [...entity.invariants].sort(),
 });
 
+// `permissions` is sorted here as well as by its producer: `ManifestSources` is a public input,
+// so a caller assembling facts by hand must not be able to make two builds of one program differ.
 const normalizeAction = (action: ActionFact): ActionFact => ({
   ...action,
+  permissions: [...action.permissions].sort(),
   cacheInvalidates: [...action.cacheInvalidates].sort(),
 });
 
 const normalizeQuery = (query: QueryFact): QueryFact => ({
   ...query,
+  permissions: [...query.permissions].sort(),
   cacheTags: [...query.cacheTags].sort(),
 });
 

package/src/diff.ts

@@ -2,15 +2,17 @@
 //
 // Three classes, and the classification is the whole value:
 //   breaking  — an existing consumer stops working (a removal, a tightened input, a changed
-//               output, a new or changed policy on something that already shipped)
+//               output, a new or changed policy, a newly REQUIRED permission, a tightened rate
+//               limit — anything that already shipped and now refuses a caller it served)
 //   additive  — a new capability; nothing that worked stops working
 //   internal  — visible in the file but not in the contract (a description, a cache tag, the
 //               buildId itself)
 // `x verify` fails on a breaking change without a major version bump. Additive and internal
 // changes never fail, which is what makes the gate credible enough to leave on.
 
+import { isMcpExposed } from '@ultimat3/core';
 import { canonical } from './build';
-import type { ActionFact, JobFact, Manifest, QueryFact, RouteFact } from './schema';
+import type { ActionFact, JobFact, Manifest, QueryFact, RateLimitFact, RouteFact } from './schema';
 
 export type ChangeKind = 'breaking' | 'additive' | 'internal';
 
@@ -91,14 +93,22 @@ function diffActions(
         detail: `policy ${action.policy ?? 'none'} -> ${next.policy ?? 'none'}`,
       });
     }
-    if (action.mcp.expose !== next.mcp.expose) {
+    // Through `isMcpExposed`, not the raw field: `before` is a file parsed from disk, so an
+    // older or hand-trimmed manifest can carry an absent, `null` or non-boolean `expose` that
+    // `!==` would read as a change and classify from. One predicate, the same one the tool
+    // projection asks, is what makes this verdict match what the surface actually serves.
+    const exposed = isMcpExposed(action.mcp);
+    const nextExposed = isMcpExposed(next.mcp);
+    if (exposed !== nextExposed) {
       // Widening the surface is additive; withdrawing a tool an agent depends on is not.
       changes.push({
-        kind: next.mcp.expose ? 'additive' : 'breaking',
+        kind: nextExposed ? 'additive' : 'breaking',
         path: `${path}.mcp.expose`,
-        detail: `mcp exposure ${String(action.mcp.expose)} -> ${String(next.mcp.expose)}`,
+        detail: `mcp exposure ${String(exposed)} -> ${String(nextExposed)}`,
       });
     }
+    changes.push(...diffPermissions(path, action, next));
+    changes.push(...diffRateLimit(path, action, next));
     if (canonical(action.cacheInvalidates) !== canonical(next.cacheInvalidates)) {
       changes.push({
         kind: 'internal',
@@ -140,6 +150,7 @@ function diffQueries(
         detail: `policy ${query.policy ?? 'none'} -> ${next.policy ?? 'none'}`,
       });
     }
+    changes.push(...diffPermissions(path, query, next));
     if (query.live !== next.live) {
       // Losing live-ness breaks subscribers; gaining it breaks nobody.
       changes.push({
@@ -157,6 +168,146 @@ function diffQueries(
   return changes;
 }
 
+/**
+ * The permissions an operation REQUIRES, and the direction each move points.
+ *
+ * Gaining one is breaking: every caller holding yesterday's grant set is refused by an operation
+ * that served them, and the failure arrives at runtime as a 403 with nothing in the build that
+ * said so. Losing one is additive — nothing that worked stops working — but it is still reported,
+ * because a grant quietly dropped from an operation is a widening of access a reviewer has to see.
+ *
+ * Matched on `permissions`, never `policy`: `policy` is a display label, and a composite's label
+ * (`and(post:publish, org:administer)`) equals no permission, so a rule reading it would call
+ * every non-trivially-guarded operation unchanged while both of its real grants moved.
+ */
+function diffPermissions(
+  path: string,
+  before: ActionFact | QueryFact,
+  after: ActionFact | QueryFact,
+): readonly ManifestChange[] {
+  const declared = readPermissions(before);
+  const next = readPermissions(after);
+  // Absence is no evidence, on either side. Unlike `mcp.expose` there is no value to fold it
+  // into: `[]` asserts "this operation requires nothing", so reading an absent field as `[]`
+  // would report every permission of every operation as newly required the first time an app
+  // diffs against a manifest written before the field existed — a wall of false breakings for
+  // an upgrade that changed no authorization at all.
+  if (declared === undefined || next === undefined) return [];
+
+  const changes: ManifestChange[] = [];
+  const declaredSet = new Set(declared);
+  const nextSet = new Set(next);
+  for (const permission of next) {
+    if (!declaredSet.has(permission)) {
+      changes.push({
+        kind: 'breaking',
+        path: `${path}.permissions.${permission}`,
+        detail: 'now required; callers granted the old set are refused',
+      });
+    }
+  }
+  for (const permission of declared) {
+    if (!nextSet.has(permission)) {
+      changes.push({
+        kind: 'additive',
+        path: `${path}.permissions.${permission}`,
+        detail: 'no longer required; access widened',
+      });
+    }
+  }
+  return changes;
+}
+
+/** The list as the FILE carries it, or `undefined` when it carries nothing this can compare. */
+function readPermissions(fact: ActionFact | QueryFact): readonly string[] | undefined {
+  const value: unknown = fact.permissions;
+  if (!Array.isArray(value)) return undefined;
+  return value.every((entry) => typeof entry === 'string')
+    ? (value as readonly string[])
+    : undefined;
+}
+
+/** No declaration at all, a declaration, or one this reader cannot make sense of. */
+type RateLimitReading = RateLimitFact | 'none' | 'unreadable';
+
+/**
+ * A tightened limit refuses a caller the old pair served, which is the definition of breaking —
+ * and it is the one contract change that leaves every schema in the manifest untouched, so
+ * nothing else here can see it. Introducing a limit where there was none is the same event at
+ * its extreme: a client that was never throttled now can be.
+ */
+function diffRateLimit(
+  path: string,
+  before: ActionFact,
+  after: ActionFact,
+): readonly ManifestChange[] {
+  const declared = readRateLimit(before);
+  const next = readRateLimit(after);
+  if (declared === 'unreadable' || next === 'unreadable') return [];
+  const at = `${path}.rateLimit`;
+
+  if (declared === 'none') {
+    if (next === 'none') return [];
+    return [
+      {
+        kind: 'breaking',
+        path: at,
+        detail: `rate limit introduced (${render(next)}); an unthrottled caller can now be refused`,
+      },
+    ];
+  }
+  if (next === 'none') {
+    return [{ kind: 'additive', path: at, detail: `rate limit removed (was ${render(declared)})` }];
+  }
+  if (tighter(declared, next)) {
+    return [
+      {
+        kind: 'breaking',
+        path: at,
+        detail: `rate limit tightened ${render(declared)} -> ${render(next)}; callers at the old rate are refused`,
+      },
+    ];
+  }
+  if (tighter(next, declared)) {
+    return [
+      {
+        kind: 'additive',
+        path: at,
+        detail: `rate limit loosened ${render(declared)} -> ${render(next)}`,
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Both halves, because either one alone refuses somebody: `limit` is the burst a caller may
+ * spend at once and `limit / windowMs` is the rate it refills at, so a larger burst on a slower
+ * refill still turns away a client the old pair served. Cross-multiplied rather than divided —
+ * both windows are positive, and an exact integer comparison cannot invent a change out of a
+ * rounding difference in a file that is diffed on every build.
+ */
+const tighter = (from: RateLimitFact, to: RateLimitFact): boolean =>
+  to.limit < from.limit || to.limit * from.windowMs < from.limit * to.windowMs;
+
+const render = (limit: RateLimitFact): string => `${limit.limit}/${limit.windowMs}ms`;
+
+function readRateLimit(fact: ActionFact): RateLimitReading {
+  const value: unknown = fact.rateLimit;
+  if (value === undefined || value === null) return 'none';
+  if (typeof value !== 'object') return 'unreadable';
+  const record = value as Record<string, unknown>;
+  const limit = record['limit'];
+  const windowMs = record['windowMs'];
+  // The same two conditions `toBucket` enforces at mount: a non-positive window is an infinite
+  // refill and a sub-token limit closes the endpoint, so neither describes a limit to compare.
+  if (!positive(limit) || !positive(windowMs)) return 'unreadable';
+  return { limit, windowMs };
+}
+
+const positive = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0;
+
 function diffRoutes(
   before: readonly RouteFact[],
   after: readonly RouteFact[],

package/src/docs-scan.ts

@@ -0,0 +1,285 @@
+// Doc entries read out of an installed package tree, at query time.
+//
+// WHY NOTHING IS GENERATED HERE
+// -----------------------------
+// The published artifact IS the source (PUBLISHING.md): `files` ships `src/**` and `README.md`,
+// and Bun runs the TypeScript directly. So every doc an agent needs is already inside
+// `node_modules` — what was missing is retrieval, not payload. A generated `docs.json` per package
+// would be a SECOND copy of bytes the tarball already carries, and a second copy is the thing that
+// drifts. Reading the installed source cannot disagree with the installed version, because it is
+// the installed version. Same split `agents-md.ts` states: facts are derived, prose is
+// human-authored — this module derives, and quotes human prose verbatim. It never writes.
+
+// `node:` by necessity, not habit. Bun exposes no native directory listing: `Bun.Glob` walks a
+// pattern and yields matches, while this needs the immediate children of the scope directory —
+// including the ones that turn out not to be packages. And Bun ships no path module at all, so
+// `basename`/`join` are the only way to build a path without hand-rolling separator handling.
+import { readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+export type DocEntryKind = 'module' | 'guide';
+
+export interface DocEntry {
+  /** `jobs.retry`, `jobs.README#queues` — stable, derived, and unique within a package. */
+  readonly topic: string;
+  readonly package: string;
+  /**
+   * The installed version this entry was read out of. Carried on every entry because a doc an
+   * agent cannot date is a doc it cannot distrust — and this is the only staleness signal that
+   * matters once the text itself is the installed source.
+   */
+  readonly version: string;
+  readonly kind: DocEntryKind;
+  /** First line of the module header, or the heading text. Empty when the module has none. */
+  readonly title: string;
+  /** The header comment or the section body, verbatim, capped. */
+  readonly text: string;
+  /** Public export names this module contributes to the package's API. */
+  readonly symbols: readonly string[];
+  /** Package-relative, so a match names a file an agent can open. */
+  readonly source: string;
+}
+
+/** Long enough for a 1–4 line header and a short section, short enough to print several. */
+const MAX_TEXT = 1_200;
+
+/** Only `README.md` and `CLAUDE.md`: the two files every package is already gated on carrying. */
+const GUIDE_FILES = ['README.md', 'CLAUDE.md'] as const;
+
+const clamp = (text: string): string =>
+  text.length <= MAX_TEXT ? text : `${text.slice(0, MAX_TEXT).trimEnd()}…`;
+
+const read = async (path: string): Promise<string | undefined> => {
+  const file = Bun.file(path);
+  return (await file.exists()) ? file.text() : undefined;
+};
+
+/**
+ * Local re-exports only. `export { t } from '@ultimat3/schema'` is another package's symbol: an
+ * entry for it would point at a file this package does not ship, and two packages would claim one
+ * topic. The public name is the one after `as` — that is what an importer can actually write.
+ */
+const RE_EXPORT = /export\s+(?:type\s+)?\{([^}]*)\}\s+from\s+'(\.[^']+)'/g;
+
+export function parseReExports(indexSource: string): ReadonlyMap<string, readonly string[]> {
+  const byModule = new Map<string, string[]>();
+  for (const match of indexSource.matchAll(RE_EXPORT)) {
+    const module = (match[2] ?? '').replace(/^\.\//, '');
+    const names = (match[1] ?? '')
+      .split(',')
+      .map(
+        (raw) =>
+          raw
+            .trim()
+            .split(/\s+as\s+/)
+            .at(-1)
+            ?.trim() ?? '',
+      )
+      .filter((name) => name !== '');
+    if (names.length === 0) continue;
+    const existing = byModule.get(module);
+    if (existing === undefined) byModule.set(module, names);
+    else existing.push(...names);
+  }
+  return byModule;
+}
+
+/**
+ * The 1–4 line header every source file carries (99.8% of them, measured) is the most reliable
+ * doc unit in this codebase — far more so than JSDoc, which sits on 42% of public exports and not
+ * on `job()` itself. Both comment styles, because both are in use.
+ */
+export function headerComment(source: string): string {
+  const lines = source.split('\n');
+  const first = lines[0]?.trimStart() ?? '';
+  const out: string[] = [];
+  if (first.startsWith('//')) {
+    for (const line of lines) {
+      const trimmed = line.trimStart();
+      if (!trimmed.startsWith('//')) break;
+      out.push(trimmed.replace(/^\/\/\s?/, ''));
+    }
+  } else if (first.startsWith('/*')) {
+    for (const line of lines) {
+      const trimmed = line.trim();
+      out.push(
+        trimmed
+          .replace(/^\/\*+\s?/, '')
+          .replace(/\s?\*+\/$/, '')
+          .replace(/^\*\s?/, ''),
+      );
+      if (trimmed.endsWith('*/')) break;
+    }
+  }
+  // A rule of dashes under a heading is a separator in prose, never a sentence.
+  return clamp(
+    out
+      .join('\n')
+      .replace(/^-{3,}$/gm, '')
+      .trim(),
+  );
+}
+
+const slug = (heading: string): string =>
+  heading
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+
+/**
+ * `##`-and-deeper sections of a human-authored guide, quoted verbatim. This is where a conceptual
+ * question ("why is money never a float") finds an answer that no symbol name carries.
+ */
+export function parseGuideSections(
+  markdown: string,
+): readonly { readonly heading: string; readonly body: string }[] {
+  const sections: { heading: string; body: string[] }[] = [];
+  for (const line of markdown.split('\n')) {
+    const heading = /^#{2,}\s+(.+?)\s*$/.exec(line);
+    if (heading !== null) sections.push({ heading: heading[1] ?? '', body: [] });
+    else sections.at(-1)?.body.push(line);
+  }
+  return sections.map((section) => ({
+    heading: section.heading,
+    body: clamp(section.body.join('\n').trim()),
+  }));
+}
+
+/** `@ultimat3/jobs` → `jobs`. An unscoped package (`create-ultimate`) keeps its whole name. */
+export const shortName = (packageName: string): string => packageName.split('/').at(-1) ?? '';
+
+async function guideEntries(
+  dir: string,
+  name: string,
+  version: string,
+): Promise<readonly DocEntry[]> {
+  const entries: DocEntry[] = [];
+  // Two `##` sections can carry the same text, and their slugs would then collide into one topic
+  // id — silently, which is the failure mode the search's own coverage floor exists to prevent,
+  // and a direct contradiction of `DocEntry.topic`'s promise to be unique within a package. No
+  // shipped guide collides today; an app's own package is one heading away from it. The suffix
+  // follows document order, so the id is still derived and still reproducible.
+  const used = new Map<string, number>();
+  for (const file of GUIDE_FILES) {
+    const markdown = await read(join(dir, file));
+    if (markdown === undefined) continue;
+    const stem = basename(file, '.md');
+    for (const section of parseGuideSections(markdown)) {
+      const base = `${shortName(name)}.${stem}#${slug(section.heading)}`;
+      const seen = (used.get(base) ?? 0) + 1;
+      used.set(base, seen);
+      entries.push({
+        topic: seen === 1 ? base : `${base}-${seen}`,
+        package: name,
+        version,
+        kind: 'guide',
+        title: section.heading,
+        text: section.body,
+        symbols: [],
+        source: file,
+      });
+    }
+  }
+  return entries;
+}
+
+/**
+ * One package tree → its doc entries. A tree with no `package.json` is not a package (npm leaves
+ * `.bin` and cache directories inside a scope), and a module `index.ts` names but the tarball does
+ * not ship is skipped rather than reported: `files` excludes test helpers on purpose, and an entry
+ * pointing at a file the install does not have is exactly the lie this module must not tell.
+ */
+export async function scanPackageDocs(dir: string): Promise<readonly DocEntry[]> {
+  const manifest = await read(join(dir, 'package.json'));
+  if (manifest === undefined) return [];
+  // A truncated `package.json` is what an interrupted install leaves behind, and it is not a
+  // package either — same answer as a directory with none, rather than a `SyntaxError` thrown
+  // through `scanInstalledDocs`'s `Promise.all` for every other package to inherit.
+  const parsed: unknown = parseJson(manifest);
+  if (parsed === undefined) return [];
+  // `unknown` + a field-by-field read, never a cast: this JSON is whatever is on disk.
+  const field = (key: string): string | undefined => {
+    if (typeof parsed !== 'object' || parsed === null) return undefined;
+    const value: unknown = Reflect.get(parsed, key);
+    return typeof value === 'string' ? value : undefined;
+  };
+  const name = field('name');
+  if (name === undefined) return [];
+  const version = field('version') ?? '';
+
+  const index = await read(join(dir, 'src/index.ts'));
+  const modules: ReadonlyMap<string, readonly string[]> =
+    index === undefined ? new Map<string, readonly string[]>() : parseReExports(index);
+  const scanned = await Promise.all(
+    [...modules].map(async ([module, symbols]) => {
+      // `.tsx` before giving up: @ultimat3/ui ships ~40 components as .tsx, and resolving only
+      // `.ts` indexed none of them — a shipped command silently blind to a whole package.
+      const candidates = [`src/${module}.ts`, `src/${module}.tsx`] as const;
+      let source: string | undefined;
+      let text: string | undefined;
+      for (const candidate of candidates) {
+        text = await read(join(dir, candidate));
+        if (text !== undefined) {
+          source = candidate;
+          break;
+        }
+      }
+      if (text === undefined || source === undefined) return undefined;
+      const header = headerComment(text);
+      return {
+        topic: `${shortName(name)}.${module}`,
+        package: name,
+        version,
+        kind: 'module',
+        title: header.split('\n')[0] ?? '',
+        text: header,
+        symbols: [...new Set(symbols)].sort(),
+        source,
+      } satisfies DocEntry;
+    }),
+  );
+  // Modules sort by topic; guides keep the order they were written in. Sorting a guide's sections
+  // alphabetically would reorder an argument its author sequenced on purpose, and prose read out
+  // of order is prose an agent has to reassemble. Both halves are deterministic, which is what
+  // "two scans of one tree agree" actually requires.
+  const moduleEntries = scanned
+    .filter((entry) => entry !== undefined)
+    .sort((a, b) => a.topic.localeCompare(b.topic));
+  return [...moduleEntries, ...(await guideEntries(dir, name, version))];
+}
+
+/**
+ * Every package under a resolved `@ultimat3` scope directory. Deliberately a directory listing
+ * rather than a hardcoded package list: an app installs the subset it uses, this repo has all 29,
+ * and a list would answer for packages that are not there.
+ */
+export async function scanInstalledDocs(scopeDir: string): Promise<readonly DocEntry[]> {
+  let names: readonly string[];
+  try {
+    names = await readdir(scopeDir);
+  } catch {
+    return [];
+  }
+  const perPackage = await Promise.all(
+    [...names].sort().map(async (name) => {
+      try {
+        return await scanPackageDocs(join(scopeDir, name));
+      } catch {
+        // `node_modules` is not a curated tree and it is not stable while an install is running:
+        // a file can vanish between `exists()` and `text()`, and a directory can be half-written.
+        // One package's tree is worth exactly that package's entries — never the whole answer.
+        return [];
+      }
+    }),
+  );
+  return perPackage.flat();
+}
+
+/** `undefined` rather than a throw. The bytes are whatever is on disk, not something we wrote. */
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}

package/src/docs-search.ts

@@ -0,0 +1,225 @@
+// Ranking doc entries against a natural-language question. Pure — no I/O, no clock — so the
+// order it produces is a function of its input alone, and a scan plus a search is reproducible.
+
+import type { DocEntry } from './docs-scan';
+
+/**
+ * Words that carry no signal in a question about an API. Deliberately tiny: every word removed
+ * here is a word an agent cannot search for, and `get`, `set`, `run` and `new` are all real
+ * symbol names in this framework.
+ */
+const STOPWORDS: ReadonlySet<string> = new Set([
+  'a',
+  'an',
+  'and',
+  'are',
+  'as',
+  'at',
+  'be',
+  'but',
+  'by',
+  'can',
+  'do',
+  'does',
+  'for',
+  'from',
+  'how',
+  'i',
+  'if',
+  'in',
+  'is',
+  'it',
+  'its',
+  'me',
+  'my',
+  'no',
+  'not',
+  'of',
+  'on',
+  'or',
+  'the',
+  'to',
+  'use',
+  'using',
+  'was',
+  'what',
+  'when',
+  'where',
+  'which',
+  'why',
+  'with',
+  'you',
+  'your',
+]);
+
+/**
+ * Split on non-alphanumerics, then split camelCase — so `nextRetry` answers a query for `retry`
+ * and `retry` answers one for `nextRetry`. The joined original is kept alongside its parts so an
+ * exact symbol name can still score as an exact hit.
+ */
+export function tokenize(query: string): readonly string[] {
+  const out: string[] = [];
+  const push = (token: string): void => {
+    if (token.length < 2 || STOPWORDS.has(token) || out.includes(token)) return;
+    out.push(token);
+  };
+  // Case is load-bearing until after the split: lowercasing first erases the boundary in
+  // `nextRetry`, which is the one this exists to find.
+  for (const word of query.split(/[^a-zA-Z0-9]+/)) {
+    if (word === '') continue;
+    const parts = word.split(/(?<=[a-z0-9])(?=[A-Z])/);
+    for (const part of parts) push(part.toLowerCase());
+    if (parts.length > 1) push(word.toLowerCase());
+  }
+  return out;
+}
+
+/**
+ * A question about rationale wants the prose a human wrote, not the declaration site: "why is
+ * money never a float" is answered by the README section that argues it, while the module that
+ * exports `Money` merely contains the word. `how` is deliberately absent — "how do I call job()"
+ * is a question about an API, and the symbol is the better answer.
+ */
+const RATIONALE = /^\s*(why|should|when should)\b/i;
+
+export interface DocHit {
+  readonly entry: DocEntry;
+  readonly score: number;
+  /** The symbols and words that earned the hit — why this answer, not just which. */
+  readonly matched: readonly string[];
+  /** How many of the query's tokens this entry accounted for. See `COVERAGE`. */
+  readonly covered: number;
+}
+
+/**
+ * The share of a question's words an entry must account for to be offered as an answer.
+ *
+ * Without this, "kubernetes ingress annotation rewrite-target" returned `cli.cmd-build` — one
+ * token of five, matched on `--target` — presented in the same shape as a real answer. An agent
+ * cannot see that difference, and a confident irrelevant answer is worse than no answer, because
+ * it stops the search. Half the words is the line between "about this" and "mentions this".
+ */
+const COVERAGE = 0.5;
+
+/**
+ * Weights, highest first: an exact public symbol name is the strongest possible signal that this
+ * is the file the question is about; prose is the weakest, because every package's README says
+ * "cache" somewhere. Prose is capped so a long document cannot out-score the declaration itself.
+ */
+const EXACT_SYMBOL = 12;
+const PARTIAL_SYMBOL = 4;
+const TOPIC = 7;
+const PACKAGE = 3;
+const TITLE = 3;
+const TEXT = 1;
+const MAX_TEXT_SCORE = 6;
+/** Applied once, to a guide entry, when the question asks for rationale rather than an API. */
+const RATIONALE_BONUS = 5;
+
+function scoreEntry(
+  entry: DocEntry,
+  tokens: readonly string[],
+  rationale: boolean,
+): DocHit | undefined {
+  const symbolsLower = entry.symbols.map((symbol) => symbol.toLowerCase());
+  const topicTokens = tokenize(entry.topic);
+  const packageToken = entry.package.split('/').at(-1)?.toLowerCase() ?? '';
+  const titleLower = entry.title.toLowerCase();
+  const textLower = entry.text.toLowerCase();
+  const matched: string[] = [];
+  let score = 0;
+  let textScore = 0;
+
+  let covered = 0;
+  for (const token of tokens) {
+    const before = score + textScore;
+    // Symbol, topic and package name are three views of ONE fact — "this thing is called that".
+    // Summing them let a token that is a package name, its module name and its exported type
+    // (`money`) out-score three genuinely independent hits, so the strongest view wins alone.
+    const exact = symbolsLower.indexOf(token);
+    const partial = exact >= 0 ? -1 : symbolsLower.findIndex((symbol) => symbol.includes(token));
+    const symbolScore = exact >= 0 ? EXACT_SYMBOL : partial >= 0 ? PARTIAL_SYMBOL : 0;
+    const nameScore = Math.max(
+      symbolScore,
+      topicTokens.includes(token) ? TOPIC : 0,
+      packageToken === token ? PACKAGE : 0,
+    );
+    score += nameScore;
+    const named = entry.symbols[exact >= 0 ? exact : partial];
+    if (symbolScore > 0 && named !== undefined) matched.push(named);
+    else if (nameScore > 0 && !matched.includes(token)) matched.push(token);
+
+    // Prose is independent evidence of the same token, and is counted on top — capped, so a long
+    // document cannot out-argue the declaration it describes.
+    if (titleLower.includes(token)) {
+      score += TITLE;
+      if (!matched.includes(token)) matched.push(token);
+    } else if (textLower.includes(token)) {
+      textScore += TEXT;
+      if (!matched.includes(token)) matched.push(token);
+    }
+    // Counted per query token, not per hit: a token that matched a symbol AND the prose is still
+    // one of the question's words accounted for.
+    if (score + textScore > before) covered += 1;
+  }
+  score += Math.min(textScore, MAX_TEXT_SCORE);
+  if (score === 0) return undefined;
+  return {
+    entry,
+    score: score + (rationale && entry.kind === 'guide' ? RATIONALE_BONUS : 0),
+    matched,
+    covered,
+  };
+}
+
+/**
+ * Ranked answers to a question, best first. A query that earns no points anywhere returns an
+ * empty list rather than the corpus: a search that always answers teaches an agent to trust an
+ * answer that was never about its question.
+ *
+ * Ties break on topic, never on scan order, so the corpus can be assembled in any order and the
+ * ranking still reproduces.
+ */
+export function searchDocs(
+  entries: readonly DocEntry[],
+  query: string,
+  limit = 8,
+): readonly DocHit[] {
+  const tokens = tokenize(query);
+  if (tokens.length === 0) return [];
+  const rationale = RATIONALE.test(query);
+  const required = Math.ceil(tokens.length * COVERAGE);
+  const hits: DocHit[] = [];
+  for (const entry of entries) {
+    const hit = scoreEntry(entry, tokens, rationale);
+    if (hit !== undefined && hit.covered >= required) hits.push(hit);
+  }
+  hits.sort((a, b) => b.score - a.score || a.entry.topic.localeCompare(b.entry.topic));
+  return hits.slice(0, limit);
+}
+
+/**
+ * Nearest topics for a question that matched nothing — the same "here is what does exist" move
+ * `x errors explain` makes for an unregistered code, so a miss still ends in something runnable.
+ */
+export function nearestTopics(
+  entries: readonly DocEntry[],
+  query: string,
+  limit = 5,
+): readonly string[] {
+  const tokens = tokenize(query);
+  const scored: { topic: string; score: number }[] = [];
+  for (const entry of entries) {
+    const topic = entry.topic.toLowerCase();
+    let score = 0;
+    for (const token of tokens) {
+      if (topic.includes(token)) score += 2;
+      // A prefix, so `retries` still reaches `retry` and `caching` reaches `cache`. Four
+      // characters, because three matches almost everything.
+      else if (token.length >= 4 && topic.includes(token.slice(0, 4))) score += 1;
+    }
+    if (score > 0) scored.push({ topic: entry.topic, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.topic.localeCompare(b.topic));
+  return [...new Set(scored.map((item) => item.topic))].slice(0, limit);
+}

package/src/emit.ts

@@ -56,8 +56,11 @@ export async function emitManifest(input: EmitInput): Promise<EmitResult> {
   const text = manifestJson(input.manifest);
 
   if (input.stdout === true) {
-    // stdout is the wire in `--json` mode; nothing else may be written to it.
-    Bun.stdout.write(text);
+    // stdout is the wire in `--json` mode; nothing else may be written to it — and the write is
+    // AWAITED, because a write to a pipe is asynchronous and `process.exit()` throws away whatever
+    // is still queued. Unawaited, the largest payload the CLI prints was the one that lost bytes,
+    // exactly as `scripts/stdout-truncation.test.ts` documents for the same bug elsewhere.
+    await Bun.write(Bun.stdout, text);
     return { path, bytes: text.length, buildId: input.manifest.buildId, changed: false };
   }
 

package/src/index.ts

@@ -12,6 +12,17 @@ export type { ManifestSources } from './build';
 export { buildManifest, canonical, contentHash } from './build';
 export type { ChangeKind, ManifestChange, ManifestDiff } from './diff';
 export { diffManifest, formatDiff } from './diff';
+export type { DocEntry, DocEntryKind } from './docs-scan';
+export {
+  headerComment,
+  parseGuideSections,
+  parseReExports,
+  scanInstalledDocs,
+  scanPackageDocs,
+  shortName,
+} from './docs-scan';
+export type { DocHit } from './docs-search';
+export { nearestTopics, searchDocs, tokenize } from './docs-search';
 export type { EmitInput, EmitResult } from './emit';
 export {
   assertNoDrift,
@@ -42,6 +53,7 @@ export type {
   OfflineStrategy,
   PolicyFact,
   QueryFact,
+  RateLimitFact,
   RenderMode,
   RouteFact,
   TaskFact,

package/src/schema.ts

@@ -5,7 +5,16 @@
 // Every collection is `readonly` and every field is a plain JSON value: the manifest must
 // round-trip through `JSON.stringify` without loss, because that is how it is stored.
 
-/** Bumped when the manifest SHAPE changes, not when an app's contents change. */
+/**
+ * Bumped when a reader built for the previous version would be WRONG, not merely incomplete:
+ * a field removed, retyped, or given a new meaning.
+ *
+ * Deliberately NOT bumped for a field that is only added. `isCompatible` is an equality check,
+ * so a bump rejects every `x.manifest.json` in existence at once — and `diffManifest` classifies
+ * a `manifestVersion` change as **breaking**, so a bump also demands a major version bump of
+ * every APP that regenerates its manifest against the new framework. Charging every app a major
+ * release for a field their readers never had to look at is a fix line that is not true.
+ */
 export const MANIFEST_VERSION = 1;
 
 export type JsonValue =
@@ -47,13 +56,32 @@ export interface EntityFact {
   readonly invariants: readonly string[];
 }
 
+/** A declared bucket as the author wrote it — `toBucket`'s input, never its converted output. */
+export interface RateLimitFact {
+  readonly limit: number;
+  readonly windowMs: number;
+}
+
 export interface ActionFact {
   readonly name: string;
   readonly input: JsonValue;
   readonly output: JsonValue;
-  /** Permission string the policy asserts, e.g. `post:publish`. */
+  /**
+   * The policy's DISPLAY label — `post:publish` for a bare `can()`, but
+   * `and(post:publish, org:administer)` for a composite. Read `permissions` to ask which grants a
+   * policy actually asserts; matching on this string reports every composite as enforcing nothing.
+   */
   readonly policy: string | null;
+  /** Every permission the policy asserts, flattened through the combinators, deduped and sorted. */
+  readonly permissions: readonly string[];
   readonly cacheInvalidates: readonly string[];
+  /**
+   * The declared rate limit; absent when the action declares none. A contract, not a tuning
+   * knob: a client written against 1000/minute is broken by 5/minute as surely as by a narrowed
+   * input, and the OpenAPI document already publishes the same pair as `x-ultimate.rateLimit` —
+   * the manifest is the copy the gate reads, so without it the tightening passes clean.
+   */
+  readonly rateLimit?: RateLimitFact;
   readonly mcp: { readonly expose: boolean; readonly description?: string };
   readonly mutator?: boolean;
 }
@@ -62,7 +90,10 @@ export interface QueryFact {
   readonly name: string;
   /** Optional: `QueryDescriptor` is schema-erased, so a live query may not expose one. */
   readonly input?: JsonValue;
+  /** The policy's DISPLAY label — see `ActionFact.policy`, and read `permissions` to match on. */
   readonly policy: string | null;
+  /** Every permission the policy asserts, flattened through the combinators, deduped and sorted. */
+  readonly permissions: readonly string[];
   readonly live: boolean;
   readonly cacheTags: readonly string[];
 }
@@ -116,20 +147,55 @@ export interface Manifest {
   readonly errorCodes: readonly ErrorCodeFact[];
 }
 
-/** Whether a reader built for `MANIFEST_VERSION` can consume `manifest`. */
+/**
+ * Whether a reader built for `MANIFEST_VERSION` can consume `manifest`.
+ *
+ * READABILITY, not completeness. An older file may simply lack a field this build publishes;
+ * that is a reader's `?? []`, not an incompatibility. See `MANIFEST_VERSION` for when the answer
+ * is allowed to become `false`.
+ */
 export function isCompatible(manifest: { manifestVersion: number }): boolean {
   return manifest.manifestVersion === MANIFEST_VERSION;
 }
 
-/** Structural check for a value read off disk, before it is trusted as a `Manifest`. */
+/** Every top-level section the type declares as an array. Checked, never assumed. */
+const ARRAY_SECTIONS: readonly (keyof Manifest)[] = [
+  'routes',
+  'entities',
+  'actions',
+  'queries',
+  'jobs',
+  'tasks',
+  'policies',
+  'permissions',
+  'locales',
+  'errorCodes',
+];
+
+/**
+ * Structural check for a value read off disk, before it is trusted as a `Manifest`.
+ *
+ * EVERY top-level key, because the cast covers all of them: this checked five and cast the rest,
+ * and `diffManifest` then read `before.queries`, `before.jobs`, `before.permissions` and
+ * `before.locales` with no guard — so a section a hand-trimmed or truncated file happened not to
+ * carry surfaced as a bare `TypeError` out of the contract gate, two calls from the file that
+ * caused it. Rejecting here makes it `X_MANIFEST_DRIFT`, which names the file and the command.
+ *
+ * The individual FACTS inside a section are deliberately not walked: a manifest written before a
+ * field existed is still readable, which is the compatibility rule `MANIFEST_VERSION` owns and
+ * `build.test.ts`'s `shape compatibility` case pins.
+ */
 export function isManifest(value: unknown): value is Manifest {
   if (typeof value !== 'object' || value === null) return false;
   const m = value as Record<string, unknown>;
-  return (
-    typeof m['manifestVersion'] === 'number' &&
-    typeof m['buildId'] === 'string' &&
-    Array.isArray(m['actions']) &&
-    Array.isArray(m['routes']) &&
-    Array.isArray(m['entities'])
-  );
+  if (typeof m['manifestVersion'] !== 'number' || typeof m['buildId'] !== 'string') return false;
+  for (const section of ARRAY_SECTIONS) if (!Array.isArray(m[section])) return false;
+  return isAppIdentity(m['app']);
+}
+
+/** `app` drives the semver gate, so a missing or non-string version is not a manifest. */
+function isAppIdentity(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null) return false;
+  const app = value as Record<string, unknown>;
+  return typeof app['name'] === 'string' && typeof app['version'] === 'string';
 }

package/src/sources.ts

@@ -62,7 +62,11 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
       input: asJson(action.input),
       output: asJson(action.output),
       policy: action.capability,
+      permissions: action.permissions,
       cacheInvalidates: action.invalidates,
+      // Written only when declared, exactly like `mcp.description`: absence already reads as
+      // "no limit", and the descriptor's `null` is not a JSON fact worth a line per action.
+      ...(action.rateLimit === null ? {} : { rateLimit: action.rateLimit }),
       mcp: {
         expose: action.mcp.expose,
         ...(action.mcp.description === null ? {} : { description: action.mcp.description }),
@@ -75,6 +79,7 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
     queries: describeQueries().map((query) => ({
       name: query.name,
       policy: query.capability,
+      permissions: query.permissions,
       live: query.live,
       cacheTags: query.tags,
     })),