@ultimat3/manifest 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -13,7 +13,15 @@ by the CLI, not imported.
 | `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 |
+| `diff.ts` | `diffManifest` — the orchestrator: one classifier per section, nothing else |
+| `diff-change.ts` | the shared vocabulary: `ManifestChange`, `index`, `diffNamedSet`, `diffScalar` |
+| `diff-operations.ts` | actions, queries and the permissions they require |
+| `diff-rate-limit.ts` | how a declared rate limit moved |
+| `diff-entities.ts` | tables, columns, keys, invariants |
+| `diff-work.ts` | jobs and tasks — the two things that fail by silently not happening |
+| `diff-routes.ts` | a URL's surface and its delivery facts |
+| `diff-registries.ts` | policies and error codes |
+| `diff-fixtures.ts` | TEST-ONLY: one fully-populated `ManifestSources`. Never in `index.ts` |
 | `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 |
@@ -69,8 +77,25 @@ by the CLI, not imported.
 - 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.
+- **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. Now enforced rather
+  than stated: `diff.test.ts` walks `ARRAY_SECTIONS` (exported by `schema.ts`, the same list
+  `isManifest` checks) and fails on a section emptying without a classified change. `tasks` and
+  `errorCodes` were unread until 2026-08, along with ten fields — a renamed table, a dropped
+  `primaryKey`/`references`, emptied `invariants`, a moved job `queue`, `retry.attempts` 5 → 0, a
+  route's `surface`/`offline`/`hydrate`, and a query's `cacheTags` — and every one of them
+  reported exactly `[{ kind: 'internal', path: 'buildId' }]` with `hasBreaking: false`. A new
+  SECTION needs its own file beside the others; a new FIELD joins the file its section owns.
+- **The axis is what a change refuses, not how it reads.** Something that rejects input that was
+  valid yesterday is breaking (an invariant added, a NOT NULL, a gained permission, a gained
+  enforcement site, a lowered `retry.attempts`); something that accepts more is additive and
+  still reported (an invariant dropped, a permission dropped, more attempts). A removal is
+  breaking on every section, including the two that fail silently: a deleted task never runs
+  again and a job whose `queue` moved piles up where no worker is subscribed.
+- **Absence is evidence only where absence has a meaning.** `primaryKey`/`references` absent IS
+  "no key", so a dropped one is classified. `surface`, `offline`, `hydrate`, `budget` and
+  `revalidateTags` absent means "this file predates the field", so `diffScalar` skips a side that
+  carries nothing rather than reporting every route in an upgraded app as re-surfaced.
 - **`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

package/README.md

@@ -58,9 +58,19 @@ whole mechanism.
 
 | Class | Examples |
 |---|---|
-| **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` |
+| **breaking** | action/query/route/job/**task**/entity/**policy**/**error code** removed; input or output schema changed; policy changed; **an operation gained a required permission**; **a policy gained an enforcement site**; **a rate limit was tightened or introduced**; MCP exposure withdrawn; column removed, retyped, or made NOT NULL; **a column's `primaryKey` or `references` changed in either direction**; **an entity's `table` renamed**; **an invariant added**; **a job's `queue` moved or its `retry.attempts` lowered**; **a route's `surface` changed**; live query became non-live |
+| **additive** | primitive added; nullable column added; a required permission dropped; an enforcement site dropped; **an invariant dropped**; a rate limit loosened or removed; **more retry attempts**; MCP exposure granted; locale added |
+| **internal** | cache tags changed (actions **and queries**); render mode changed; **a route's `offline`/`hydrate`/`budget`/`revalidateTags`**; **a task's `cron`/`tz`/`enqueues`**; **a job's `retry.backoff`**; job steps reordered; **an error code's owning package**; `buildId` |
+
+Every top-level section is classified, and that is checked rather than promised:
+`diff.test.ts` walks `ARRAY_SECTIONS` from `schema.ts` and fails on a section nothing reads. Two
+of them — `tasks` and `errorCodes` — were unread until 2026-08, along with ten fields, so deleting
+every scheduled task reported `internal buildId: content changed` and passed the gate.
+
+One classifier per section, each in its own file: `diff-operations.ts` (actions, queries,
+permissions), `diff-rate-limit.ts`, `diff-entities.ts`, `diff-work.ts` (jobs, tasks),
+`diff-routes.ts`, `diff-registries.ts` (policies, error codes), over the shared vocabulary in
+`diff-change.ts`. `diff.ts` is the orchestrator and nothing else.
 
 `verifyContract()` is the gate: a breaking change fails unless the app's **major** version
 moved. An unparseable version counts as "not bumped" — fail-closed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "3.0.0",
-    "@ultimat3/core": "3.0.0",
-    "@ultimat3/entity": "3.0.0",
-    "@ultimat3/jobs": "3.0.0",
-    "@ultimat3/query": "3.0.0"
+    "@ultimat3/action": "4.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/entity": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/query": "4.0.0"
   }
 }

package/src/diff-change.ts

@@ -0,0 +1,67 @@
+// The vocabulary every classifier in the `diff-*` family speaks: one change, its three kinds, and
+// the two shapes every section needs — an index by name and a flat set difference.
+//
+//   breaking  — an existing consumer stops working (a removal, a tightened input, a changed
+//               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)
+
+export type ChangeKind = 'breaking' | 'additive' | 'internal';
+
+export interface ManifestChange {
+  readonly kind: ChangeKind;
+  /** Dotted path into the manifest, e.g. `actions.publishPost.policy`. */
+  readonly path: string;
+  readonly detail: string;
+}
+
+export function index<T>(items: readonly T[], key: (item: T) => string): Map<string, T> {
+  return new Map(items.map((item) => [key(item), item]));
+}
+
+/**
+ * A flat set of names: what left, what arrived. `removalKind` is the only thing that differs
+ * between sections — a locale disappearing is additive, a permission disappearing is not.
+ */
+export function diffNamedSet(
+  path: string,
+  before: readonly string[],
+  after: readonly string[],
+  removalKind: ChangeKind = 'breaking',
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterSet = new Set(after);
+  const beforeSet = new Set(before);
+  for (const name of before) {
+    if (!afterSet.has(name)) {
+      changes.push({ kind: removalKind, path: `${path}.${name}`, detail: 'removed' });
+    }
+  }
+  for (const name of after) {
+    if (!beforeSet.has(name)) {
+      changes.push({ kind: 'additive', path: `${path}.${name}`, detail: 'added' });
+    }
+  }
+  return changes;
+}
+
+/**
+ * One scalar field, compared only where BOTH sides carry a value.
+ *
+ * `before` is a file parsed off disk, so an optional field a manifest was written before is
+ * absent rather than wrong — and reading absence as a value reports every route in an upgraded
+ * app as newly re-surfaced. Absence is no evidence, the same rule `permissions` already follows.
+ */
+export function diffScalar(
+  kind: ChangeKind,
+  path: string,
+  before: unknown,
+  after: unknown,
+  detail = (from: string, to: string): string => `${from} -> ${to}`,
+): readonly ManifestChange[] {
+  if (before === undefined || after === undefined || before === null || after === null) return [];
+  if (before === after) return [];
+  return [{ kind, path, detail: detail(String(before), String(after)) }];
+}

package/src/diff-entities.ts

@@ -0,0 +1,138 @@
+// The data shape: which table an entity maps to, what its columns promise, and which rules the
+// database itself enforces. The axis is the same one `nullable` already uses — a change that
+// rejects something previously valid is breaking; one that accepts more is additive and reported.
+
+import type { ManifestChange } from './diff-change';
+import { diffScalar, index } from './diff-change';
+import type { ColumnFact, EntityFact } from './schema';
+
+export function diffEntities(
+  before: readonly EntityFact[],
+  after: readonly EntityFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (e) => e.name);
+  const beforeByName = index(before, (e) => e.name);
+
+  for (const entity of before) {
+    const next = afterByName.get(entity.name);
+    const path = `entities.${entity.name}`;
+    if (next === undefined) {
+      changes.push({ kind: 'breaking', path, detail: 'entity removed' });
+      continue;
+    }
+    // The table is the name every hand-written query, view and migration outside the app uses;
+    // a rename leaves the entity intact in the manifest and every one of them broken.
+    changes.push(
+      ...diffScalar(
+        'breaking',
+        `${path}.table`,
+        entity.table,
+        next.table,
+        (from, to) => `table ${from} -> ${to}`,
+      ),
+    );
+    changes.push(...diffColumns(path, entity, next));
+    changes.push(...diffInvariants(`${path}.invariants`, entity.invariants, next.invariants));
+  }
+  for (const entity of after) {
+    if (!beforeByName.has(entity.name)) {
+      changes.push({ kind: 'additive', path: `entities.${entity.name}`, detail: 'entity added' });
+    }
+  }
+  return changes;
+}
+
+/**
+ * An invariant is a CHECK or UNIQUE the database itself enforces, so the direction decides:
+ * adding one rejects rows that were valid a moment ago, dropping one only widens what the table
+ * accepts. Both are reported — a rule that quietly stopped being enforced is what a reviewer of a
+ * data migration most needs to see.
+ */
+function diffInvariants(
+  path: string,
+  before: readonly string[],
+  after: readonly string[],
+): readonly ManifestChange[] {
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+  return [
+    ...after
+      .filter((name) => !beforeSet.has(name))
+      .map((name) => ({
+        kind: 'breaking' as const,
+        path: `${path}.${name}`,
+        detail: 'invariant added; rows that were valid are now rejected',
+      })),
+    ...before
+      .filter((name) => !afterSet.has(name))
+      .map((name) => ({
+        kind: 'additive' as const,
+        path: `${path}.${name}`,
+        detail: 'invariant removed; the rule is no longer enforced',
+      })),
+  ];
+}
+
+function diffColumns(
+  path: string,
+  before: EntityFact,
+  after: EntityFact,
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const nextColumns = index(after.columns, (c) => c.name);
+
+  for (const column of before.columns) {
+    const next = nextColumns.get(column.name);
+    const at = `${path}.columns.${column.name}`;
+    if (next === undefined) {
+      changes.push({ kind: 'breaking', path: at, detail: 'column removed' });
+      continue;
+    }
+    if (column.type !== next.type) {
+      changes.push({
+        kind: 'breaking',
+        path: `${at}.type`,
+        detail: `${column.type} -> ${next.type}`,
+      });
+    }
+    if (column.nullable && !next.nullable) {
+      // Tightening nullability rejects rows that were valid a moment ago.
+      changes.push({ kind: 'breaking', path: `${at}.nullable`, detail: 'became NOT NULL' });
+    }
+    changes.push(...diffKey(at, 'primaryKey', keyOf(column), keyOf(next)));
+    changes.push(...diffKey(at, 'references', column.references, next.references));
+  }
+
+  const beforeColumns = index(before.columns, (c) => c.name);
+  for (const column of after.columns) {
+    if (!beforeColumns.has(column.name)) {
+      changes.push({
+        kind: column.nullable ? 'additive' : 'breaking',
+        path: `${path}.columns.${column.name}`,
+        detail: column.nullable ? 'column added' : 'NOT NULL column added with no default',
+      });
+    }
+  }
+  return changes;
+}
+
+/** `primaryKey` is optional in the file, so absence is the same statement as `false`. */
+const keyOf = (column: ColumnFact): string => (column.primaryKey === true ? 'yes' : 'no');
+
+/**
+ * Identity and relationship, in either direction. Gaining one rejects rows that used to insert;
+ * losing one strands every consumer that navigated the graph the manifest published — a foreign
+ * key is how an agent knows `authorId` reaches `users`, and nothing else in the file says so.
+ */
+function diffKey(
+  at: string,
+  field: 'primaryKey' | 'references',
+  before: string | undefined,
+  after: string | undefined,
+): readonly ManifestChange[] {
+  const from = before ?? 'none';
+  const to = after ?? 'none';
+  if (from === to) return [];
+  return [{ kind: 'breaking', path: `${at}.${field}`, detail: `${field} ${from} -> ${to}` }];
+}

package/src/diff-fixtures.ts

@@ -0,0 +1,95 @@
+// TEST-ONLY. One fully-populated `ManifestSources` for the diff suites, so every section carries a
+// fact and every fact carries every field its type declares — a fixture with an empty `tasks` is
+// how a section nothing classifies stays green. Never exported from `index.ts`.
+
+import type { ManifestSources } from './build';
+import { buildManifest } from './build';
+import type { Manifest } from './schema';
+
+export const fixtureAction = (
+  name: string,
+  policy: string,
+  expose = true,
+  permissions = [policy],
+) => ({
+  name,
+  input: { id: 'uuid' },
+  output: { ok: 'boolean' },
+  policy,
+  permissions,
+  cacheInvalidates: ['post'],
+  mcp: { expose },
+});
+
+export const fixtureQuery = (name: string, policy: string, permissions = [policy]) => ({
+  name,
+  input: {},
+  policy,
+  permissions,
+  live: true,
+  cacheTags: ['post'],
+});
+
+/**
+ * Built through a helper rather than written as `{ code: 'X_…' }`: `x verify`'s `errors` step
+ * reads a `code:` key with an `X_*` literal as a DECLARATION, and this file is not a test file, so
+ * the literal would have published a fixture's code into `framework.manifest.json` as one this
+ * package owns.
+ */
+export const fixtureErrorCode = (code: string, owner: string) => ({ code, package: owner });
+
+/** Every section non-empty, every optional field present. */
+export const FIXTURE: ManifestSources = {
+  app: { name: 'acme', version: '1.4.2' },
+  routes: [
+    {
+      url: '/posts',
+      render: 'isr',
+      offline: 'precache',
+      hydrate: 'idle',
+      revalidateTags: ['post'],
+      budget: { js: '40kb', lcp: 2000 },
+      surface: 'site',
+    },
+  ],
+  entities: [
+    {
+      name: 'post',
+      table: 'posts',
+      columns: [
+        { name: 'id', type: 'uuid', nullable: false, primaryKey: true },
+        { name: 'authorId', type: 'uuid', nullable: false, references: 'users.id' },
+        { name: 'note', type: 'text', nullable: true },
+      ],
+      invariants: ['post_title_present'],
+    },
+  ],
+  actions: [fixtureAction('publishPost', 'post:publish')],
+  queries: [fixtureQuery('feed', 'feed:read')],
+  jobs: [
+    {
+      name: 'sendMail',
+      input: { orgId: 'uuid' },
+      queue: 'critical',
+      retry: { attempts: 5, backoff: 'exponential' },
+      steps: ['a'],
+    },
+  ],
+  tasks: [
+    { name: 'nightlyDigest', cron: '0 3 * * *', tz: 'Europe/Berlin', enqueues: ['sendMail'] },
+  ],
+  policies: [
+    { permission: 'post:publish', description: 'publish a draft', enforcedIn: ['actions.publish'] },
+  ],
+  locales: ['en'],
+  // A code that is genuinely REGISTERED, not an invented one. `error-catalog.test.ts` scans every
+  // non-test file under `packages/*/src` for an `X_*` literal and treats an unregistered one as a
+  // code handed to a reader that no gate can see. A fixture is not shipped source in spirit, but
+  // it is in fact — and widening that scanner to excuse a filename is a worse trade than picking a
+  // real code here, since the diff classifier only ever compares the string.
+  errorCodes: [fixtureErrorCode('X_NOT_FOUND', 'app')],
+};
+
+/** The fixture, built. */
+export const fixtureManifest = (overrides: Partial<ManifestSources> = {}): Manifest =>
+  buildManifest({ ...FIXTURE, ...overrides });

package/src/diff-operations.ts

@@ -0,0 +1,176 @@
+// The two callable surfaces — actions and queries — and the permissions they require.
+
+import { isMcpExposed } from '@ultimat3/core';
+import { canonical } from './build';
+import type { ManifestChange } from './diff-change';
+import { index } from './diff-change';
+import { diffRateLimit } from './diff-rate-limit';
+import type { ActionFact, QueryFact } from './schema';
+
+export function diffActions(
+  before: readonly ActionFact[],
+  after: readonly ActionFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (a) => a.name);
+  const beforeByName = index(before, (a) => a.name);
+
+  for (const action of before) {
+    const next = afterByName.get(action.name);
+    const path = `actions.${action.name}`;
+    if (next === undefined) {
+      // The canonical breaking change: a caller that compiled yesterday no longer does.
+      changes.push({ kind: 'breaking', path, detail: 'action removed' });
+      continue;
+    }
+    if (canonical(action.input) !== canonical(next.input)) {
+      changes.push({ kind: 'breaking', path: `${path}.input`, detail: 'input schema changed' });
+    }
+    if (canonical(action.output) !== canonical(next.output)) {
+      changes.push({ kind: 'breaking', path: `${path}.output`, detail: 'output schema changed' });
+    }
+    if (action.policy !== next.policy) {
+      changes.push({
+        kind: 'breaking',
+        path: `${path}.policy`,
+        detail: `policy ${action.policy ?? 'none'} -> ${next.policy ?? 'none'}`,
+      });
+    }
+    // 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: nextExposed ? 'additive' : 'breaking',
+        path: `${path}.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',
+        path: `${path}.cacheInvalidates`,
+        detail: 'cache tags changed',
+      });
+    }
+  }
+  for (const action of after) {
+    if (!beforeByName.has(action.name)) {
+      changes.push({ kind: 'additive', path: `actions.${action.name}`, detail: 'action added' });
+    }
+  }
+  return changes;
+}
+
+export function diffQueries(
+  before: readonly QueryFact[],
+  after: readonly QueryFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (q) => q.name);
+  const beforeByName = index(before, (q) => q.name);
+
+  for (const query of before) {
+    const next = afterByName.get(query.name);
+    const path = `queries.${query.name}`;
+    if (next === undefined) {
+      changes.push({ kind: 'breaking', path, detail: 'query removed' });
+      continue;
+    }
+    if (canonical(query.input) !== canonical(next.input)) {
+      changes.push({ kind: 'breaking', path: `${path}.input`, detail: 'input schema changed' });
+    }
+    if (query.policy !== next.policy) {
+      changes.push({
+        kind: 'breaking',
+        path: `${path}.policy`,
+        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({
+        kind: next.live ? 'additive' : 'breaking',
+        path: `${path}.live`,
+        detail: `live ${String(query.live)} -> ${String(next.live)}`,
+      });
+    }
+    // The same fact as an action's `cacheInvalidates`, and the same class: which tag flushes a
+    // read is not a caller's contract, but a reviewer has to see it move.
+    if (canonical(query.cacheTags) !== canonical(next.cacheTags)) {
+      changes.push({ kind: 'internal', path: `${path}.cacheTags`, detail: 'cache tags changed' });
+    }
+  }
+  for (const query of after) {
+    if (!beforeByName.has(query.name)) {
+      changes.push({ kind: 'additive', path: `queries.${query.name}`, detail: 'query added' });
+    }
+  }
+  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;
+}

package/src/diff-rate-limit.ts

@@ -0,0 +1,85 @@
+// One rule: how a declared rate limit moved. 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 in the diff can see it.
+
+import type { ManifestChange } from './diff-change';
+import type { ActionFact, RateLimitFact } from './schema';
+
+/** No declaration at all, a declaration, or one this reader cannot make sense of. */
+type RateLimitReading = RateLimitFact | 'none' | 'unreadable';
+
+/**
+ * Introducing a limit where there was none is the same event at its extreme: a client that was
+ * never throttled now can be.
+ */
+export 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;