@ultimat3/manifest 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @ultimat3/manifest 📋
+
+Generated facts. `x.manifest.json` is emitted from code, committed, and diffed in review —
+it is how an agent learns what the app *is* without reading every file.
+
+```ts
+import { buildManifest, emitManifest, assertNoDrift, verifyContract } from '@ultimat3/manifest';
+
+const manifest = buildManifest(frameworkSources({ app, routes, policies }));
+await emitManifest({ manifest });                  // x manifest
+await assertNoDrift({ manifest });                 // x verify
+verifyContract({ before: committed, after: manifest });
+```
+
+## What it contains
+
+| Section | Facts |
+|---|---|
+| `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 |
+| `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 |
+| `locales`, `errorCodes` | catalogs a tool can enumerate |
+
+Plus `manifestVersion` (shape version, so a reader can check compatibility), `app`, and
+`buildId`.
+
+## Determinism
+
+The file is committed and reviewed, so two builds of the same tree must produce identical
+bytes. Enforced, not hoped for:
+
+- **No timestamps, no git sha, no hostname, no build counter.**
+- Every collection is sorted by a stable key before writing — `Map`/`Set` iteration order is
+  insertion order, and insertion order depends on module load order, which depends on the
+  filesystem.
+- Object keys are written in a fixed order, not `JSON.stringify` order, so reordering a
+  struct literal produces no diff.
+- `buildId` is a sha256 of the canonical body, so it changes if and only if a fact changed —
+  and `verifyBuildId()` re-derives it from the file, catching a hand edit.
+- Job `steps` keep declared order. A job's steps are a sequence, not a set.
+
+A manifest that churns on every build trains reviewers to ignore its diff, which defeats the
+whole mechanism.
+
+## The contract diff
+
+`diffManifest(before, after)` classifies every change:
+
+| 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 |
+| **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
+moved. An unparseable version counts as "not bumped" — fail-closed.
+
+```
+X_MANIFEST_BREAKING: contract broke without a version bump
+  cause: 1 breaking change(s) from 1.4.2 to 1.5.0 with no major version bump:
+         actions.publishPost: action removed
+  fix:   bump the major version in app.config.ts, or restore the removed contract
+```
+
+## AGENTS.md: validated, never generated
+
+`checkAgentsMd()` / `assertAgentsMd()` verify that a **hand-written** `AGENTS.md` exists and
+is under 12kB. They do not generate prose, and there is deliberately no generator to point at.
+
+Research shows LLM-generated context files *reduce* task success and add steps: the prose
+reads plausibly, drifts from reality the moment anything changes, and an agent trusts it over
+the code. So the split is fixed:
+
+- **facts are generated** → `x.manifest.json`, regenerated every build;
+- **conventions are human-authored** → `AGENTS.md`, short enough to be read every time.
+
+The checker warns (never fails) when `AGENTS.md` starts tabulating schema or route facts, runs
+past 200 lines, or claims to be generated. Those warnings ride in the step's `output`, so
+`x verify --json` carries them for a human to judge.
+
+`x verify` runs `assertAgentsMd()` inside its `manifest` step — the same step that checks the
+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.
+
+## Errors
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `X_MANIFEST_DRIFT` | committed file no longer matches the code, or was hand-edited so its `buildId` no longer hashes its own body | `x manifest` |
+| `X_MANIFEST_BREAKING` | contract broke with no major bump | bump the version, or restore |
+| `X_AGENTS_MD_MISSING` | no `AGENTS.md` | write one by hand |
+| `X_AGENTS_MD_TOO_LARGE` | over the byte budget | move facts to `x.manifest.json` |

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ultimat3/manifest",
+  "version": "1.0.0",
+  "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/manifest"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/action": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/entity": "1.0.0",
+    "@ultimat3/jobs": "1.0.0",
+    "@ultimat3/query": "1.0.0"
+  }
+}

package/src/agents-md.ts

@@ -0,0 +1,94 @@
+// AGENTS.md validation. Read-only, deliberately narrow.
+//
+// WHY THIS DOES NOT GENERATE PROSE
+// --------------------------------
+// The obvious feature request is "generate AGENTS.md from the code". We refuse, on evidence:
+// LLM-generated context files measurably REDUCE task success and increase the number of
+// steps an agent takes. The generated prose reads plausibly, drifts from reality the moment
+// anything changes, and — worst of all — an agent trusts it over the code.
+//
+// So the split is: FACTS ARE GENERATED, CONVENTIONS ARE HUMAN-AUTHORED. `x.manifest.json`
+// carries everything derivable from code and is regenerated on every build. `AGENTS.md`
+// carries what a human knows and code cannot express — why this queue is separate, which
+// service is load-bearing, what not to touch — and stays short enough to be read every time.
+//
+// This module therefore checks exactly two things: that the file exists, and that it has not
+// grown into a document nobody reads. It never writes.
+
+import { AgentsMdMissingError, AgentsMdTooLargeError } from './errors';
+
+export const AGENTS_MD_FILENAME = 'AGENTS.md';
+
+/**
+ * Default budget, in bytes. Roughly 3k tokens — long enough for stack, commands, conventions,
+ * and hard-won gotchas; short enough that an agent reads all of it rather than skimming.
+ */
+export const AGENTS_MD_MAX_BYTES = 12_000;
+
+export interface AgentsMdCheck {
+  readonly path: string;
+  readonly exists: boolean;
+  readonly bytes: number;
+  readonly maxBytes: number;
+  readonly ok: boolean;
+  /** Non-fatal observations, surfaced by `x verify --json` for a human to judge. */
+  readonly warnings: readonly string[];
+}
+
+export interface CheckAgentsMdInput {
+  readonly path?: string;
+  readonly maxBytes?: number;
+}
+
+/** Inspect without throwing — `x verify --json` reports, `assertAgentsMd` enforces. */
+export async function checkAgentsMd(input: CheckAgentsMdInput = {}): Promise<AgentsMdCheck> {
+  const path = input.path ?? `./${AGENTS_MD_FILENAME}`;
+  const maxBytes = input.maxBytes ?? AGENTS_MD_MAX_BYTES;
+  const file = Bun.file(path);
+
+  if (!(await file.exists())) {
+    return { path, exists: false, bytes: 0, maxBytes, ok: false, warnings: [] };
+  }
+  const text = await file.text();
+  const bytes = Buffer.byteLength(text, 'utf8');
+  return {
+    path,
+    exists: true,
+    bytes,
+    maxBytes,
+    ok: bytes <= maxBytes,
+    warnings: warningsFor(text),
+  };
+}
+
+/** The `x verify` gate. Throws `X_AGENTS_MD_*`; never repairs the file. */
+export async function assertAgentsMd(input: CheckAgentsMdInput = {}): Promise<AgentsMdCheck> {
+  const check = await checkAgentsMd(input);
+  if (!check.exists) throw new AgentsMdMissingError({ path: check.path });
+  if (check.bytes > check.maxBytes) {
+    throw new AgentsMdTooLargeError({
+      path: check.path,
+      bytes: check.bytes,
+      maxBytes: check.maxBytes,
+    });
+  }
+  return check;
+}
+
+/**
+ * Warn when the file has started duplicating generated facts. Duplication is how a context
+ * file goes stale: the copy and the source drift, and the agent believes the copy.
+ */
+function warningsFor(text: string): readonly string[] {
+  const warnings: string[] = [];
+  if (/^\s*\|.*\|\s*$/m.test(text) && /\b(column|entity|route|endpoint)\b/i.test(text)) {
+    warnings.push('looks like it tabulates schema or route facts; those live in x.manifest.json');
+  }
+  if (text.split('\n').length > 200) {
+    warnings.push('over 200 lines; a context file that long is skimmed, not read');
+  }
+  if (/generated by|do not edit/i.test(text)) {
+    warnings.push('claims to be generated; AGENTS.md is human-authored by design');
+  }
+  return warnings;
+}

package/src/build.ts

@@ -0,0 +1,143 @@
+// `buildManifest` — the generated facts, emitted from code.
+//
+// DETERMINISM IS THE WHOLE POINT. `x.manifest.json` is committed and diffed in review, so
+// two builds of the same tree must produce identical bytes. That means:
+//   - no timestamps, no git sha, no build counter, no hostname;
+//   - every collection is sorted by a stable key before it is written, because `Map` and
+//     `Set` iteration order is insertion order and insertion order depends on module load
+//     order, which depends on the filesystem;
+//   - object keys are written in a fixed order (see `emit.ts`), not `JSON.stringify` order;
+//   - `buildId` is a content hash of the sorted body, so it changes if and only if a fact
+//     changed.
+// A manifest that churns on every build trains reviewers to ignore its diff, which defeats
+// the entire mechanism.
+//
+// Sources are injected. Route facts come from `@ultimat3/render` and policy facts are
+// assembled per app — both outside what this tier may import — so the CLI supplies them and
+// this function stays pure and unit-testable.
+
+import type {
+  ActionFact,
+  EntityFact,
+  ErrorCodeFact,
+  JobFact,
+  Manifest,
+  PolicyFact,
+  QueryFact,
+  RouteFact,
+  TaskFact,
+} from './schema';
+import { MANIFEST_VERSION } from './schema';
+
+export interface ManifestSources {
+  readonly app: { readonly name: string; readonly version: string };
+  readonly routes?: readonly RouteFact[];
+  readonly entities?: readonly EntityFact[];
+  readonly actions?: readonly ActionFact[];
+  readonly queries?: readonly QueryFact[];
+  readonly jobs?: readonly JobFact[];
+  readonly tasks?: readonly TaskFact[];
+  readonly policies?: readonly PolicyFact[];
+  readonly locales?: readonly string[];
+  readonly errorCodes?: readonly ErrorCodeFact[];
+}
+
+export function buildManifest(sources: ManifestSources): Manifest {
+  const routes = sortBy(sources.routes ?? [], (r) => r.url);
+  const entities = sortBy(sources.entities ?? [], (e) => e.name).map(normalizeEntity);
+  const actions = sortBy(sources.actions ?? [], (a) => a.name).map(normalizeAction);
+  const queries = sortBy(sources.queries ?? [], (q) => q.name).map(normalizeQuery);
+  const jobs = sortBy(sources.jobs ?? [], (j) => j.name).map(normalizeJob);
+  const tasks = sortBy(sources.tasks ?? [], (t) => t.name).map((t) => ({
+    ...t,
+    enqueues: [...t.enqueues].sort(),
+  }));
+  const policies = sortBy(sources.policies ?? [], (p) => p.permission).map((p) => ({
+    ...p,
+    enforcedIn: [...p.enforcedIn].sort(),
+  }));
+  const errorCodes = sortBy(sources.errorCodes ?? [], (e) => `${e.package}:${e.code}`);
+
+  // 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.
+  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),
+  ]);
+
+  const body = {
+    manifestVersion: MANIFEST_VERSION,
+    app: sources.app,
+    routes,
+    entities,
+    actions,
+    queries,
+    jobs,
+    tasks,
+    policies,
+    permissions,
+    locales: [...(sources.locales ?? [])].sort(),
+    errorCodes,
+  };
+
+  return { ...body, buildId: contentHash(body) };
+}
+
+/**
+ * Content hash of the manifest body. Deliberately excludes `buildId` itself, and is computed
+ * over the same canonical serialisation `emit.ts` writes — so `buildId` is verifiable from
+ * the file alone.
+ */
+export function contentHash(body: Omit<Manifest, 'buildId'>): string {
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(canonical(body));
+  return hasher.digest('hex').slice(0, 16);
+}
+
+/** Sorted-key JSON. Never `JSON.stringify(value)` directly — key order is not a contract. */
+export function canonical(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (typeof value !== 'object' || value === null) return value;
+  const record = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(record).sort()) out[key] = sortKeys(record[key]);
+  return out;
+}
+
+function sortBy<T>(items: readonly T[], key: (item: T) => string): readonly T[] {
+  return [...items].sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+}
+
+function unique(values: readonly string[]): readonly string[] {
+  return [...new Set(values)].sort();
+}
+
+// Inner collections are sorted too: a reordered column list is a spurious diff.
+const normalizeEntity = (entity: EntityFact): EntityFact => ({
+  ...entity,
+  columns: sortBy(entity.columns, (c) => c.name),
+  invariants: [...entity.invariants].sort(),
+});
+
+const normalizeAction = (action: ActionFact): ActionFact => ({
+  ...action,
+  cacheInvalidates: [...action.cacheInvalidates].sort(),
+});
+
+const normalizeQuery = (query: QueryFact): QueryFact => ({
+  ...query,
+  cacheTags: [...query.cacheTags].sort(),
+});
+
+// Job steps keep their DECLARED order — a job's steps are a sequence, not a set, and
+// sorting them would misrepresent the program.
+const normalizeJob = (job: JobFact): JobFact => ({ ...job, steps: [...job.steps] });

package/src/diff.ts

@@ -0,0 +1,308 @@
+// `diffManifest` — the contract diff `x verify` gates on.
+//
+// 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)
+//   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 { canonical } from './build';
+import type { ActionFact, JobFact, Manifest, QueryFact, RouteFact } from './schema';
+
+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 interface ManifestDiff {
+  readonly changes: readonly ManifestChange[];
+  readonly breaking: readonly ManifestChange[];
+  readonly additive: readonly ManifestChange[];
+  readonly internal: readonly ManifestChange[];
+  readonly hasBreaking: boolean;
+}
+
+export function diffManifest(before: Manifest, after: Manifest): ManifestDiff {
+  const changes: ManifestChange[] = [];
+
+  if (before.manifestVersion !== after.manifestVersion) {
+    changes.push({
+      kind: 'breaking',
+      path: 'manifestVersion',
+      detail: `manifest shape ${before.manifestVersion} -> ${after.manifestVersion}`,
+    });
+  }
+  if (before.buildId !== after.buildId) {
+    changes.push({ kind: 'internal', path: 'buildId', detail: 'content changed' });
+  }
+
+  changes.push(...diffActions(before.actions, after.actions));
+  changes.push(...diffQueries(before.queries, after.queries));
+  changes.push(...diffRoutes(before.routes, after.routes));
+  changes.push(...diffJobs(before.jobs, after.jobs));
+  changes.push(...diffEntities(before, after));
+  changes.push(...diffNamedSet('permissions', before.permissions, after.permissions));
+  changes.push(...diffNamedSet('locales', before.locales, after.locales, 'additive'));
+
+  const sorted = [...changes].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const breaking = sorted.filter((c) => c.kind === 'breaking');
+  return {
+    changes: sorted,
+    breaking,
+    additive: sorted.filter((c) => c.kind === 'additive'),
+    internal: sorted.filter((c) => c.kind === 'internal'),
+    hasBreaking: breaking.length > 0,
+  };
+}
+
+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'}`,
+      });
+    }
+    if (action.mcp.expose !== next.mcp.expose) {
+      // Widening the surface is additive; withdrawing a tool an agent depends on is not.
+      changes.push({
+        kind: next.mcp.expose ? 'additive' : 'breaking',
+        path: `${path}.mcp.expose`,
+        detail: `mcp exposure ${String(action.mcp.expose)} -> ${String(next.mcp.expose)}`,
+      });
+    }
+    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;
+}
+
+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'}`,
+      });
+    }
+    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)}`,
+      });
+    }
+  }
+  for (const query of after) {
+    if (!beforeByName.has(query.name)) {
+      changes.push({ kind: 'additive', path: `queries.${query.name}`, detail: 'query added' });
+    }
+  }
+  return changes;
+}
+
+function diffRoutes(
+  before: readonly RouteFact[],
+  after: readonly RouteFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByUrl = index(after, (r) => r.url);
+  const beforeByUrl = index(before, (r) => r.url);
+
+  for (const route of before) {
+    const next = afterByUrl.get(route.url);
+    if (next === undefined) {
+      // A removed URL is a 404 for anyone holding a link to it.
+      changes.push({ kind: 'breaking', path: `routes.${route.url}`, detail: 'route removed' });
+      continue;
+    }
+    if (route.render !== next.render) {
+      changes.push({
+        kind: 'internal',
+        path: `routes.${route.url}.render`,
+        detail: `render ${route.render} -> ${next.render}`,
+      });
+    }
+  }
+  for (const route of after) {
+    if (!beforeByUrl.has(route.url)) {
+      changes.push({ kind: 'additive', path: `routes.${route.url}`, detail: 'route added' });
+    }
+  }
+  return changes;
+}
+
+function diffJobs(
+  before: readonly JobFact[],
+  after: readonly JobFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after, (j) => j.name);
+  const beforeByName = index(before, (j) => j.name);
+
+  for (const job of before) {
+    const next = afterByName.get(job.name);
+    if (next === undefined) {
+      // Enqueued-but-undeliverable work is silent data loss, so a removal is breaking.
+      changes.push({ kind: 'breaking', path: `jobs.${job.name}`, detail: 'job removed' });
+      continue;
+    }
+    if (canonical(job.input) !== canonical(next.input)) {
+      changes.push({
+        kind: 'breaking',
+        path: `jobs.${job.name}.input`,
+        detail: 'input schema changed; in-flight payloads will not parse',
+      });
+    }
+    if (canonical(job.steps) !== canonical(next.steps)) {
+      changes.push({
+        kind: 'internal',
+        path: `jobs.${job.name}.steps`,
+        detail: 'steps changed; resumed runs may replay differently',
+      });
+    }
+  }
+  for (const job of after) {
+    if (!beforeByName.has(job.name)) {
+      changes.push({ kind: 'additive', path: `jobs.${job.name}`, detail: 'job added' });
+    }
+  }
+  return changes;
+}
+
+function diffEntities(before: Manifest, after: Manifest): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const afterByName = index(after.entities, (e) => e.name);
+  const beforeByName = index(before.entities, (e) => e.name);
+
+  for (const entity of before.entities) {
+    const next = afterByName.get(entity.name);
+    if (next === undefined) {
+      changes.push({ kind: 'breaking', path: `entities.${entity.name}`, detail: 'entity removed' });
+      continue;
+    }
+    const nextColumns = index(next.columns, (c) => c.name);
+    for (const column of entity.columns) {
+      const nextColumn = nextColumns.get(column.name);
+      const path = `entities.${entity.name}.columns.${column.name}`;
+      if (nextColumn === undefined) {
+        changes.push({ kind: 'breaking', path, detail: 'column removed' });
+        continue;
+      }
+      if (column.type !== nextColumn.type) {
+        changes.push({
+          kind: 'breaking',
+          path: `${path}.type`,
+          detail: `${column.type} -> ${nextColumn.type}`,
+        });
+      }
+      if (column.nullable && !nextColumn.nullable) {
+        // Tightening nullability rejects rows that were valid a moment ago.
+        changes.push({ kind: 'breaking', path: `${path}.nullable`, detail: 'became NOT NULL' });
+      }
+    }
+    const beforeColumns = index(entity.columns, (c) => c.name);
+    for (const column of next.columns) {
+      if (!beforeColumns.has(column.name)) {
+        changes.push({
+          kind: column.nullable ? 'additive' : 'breaking',
+          path: `entities.${entity.name}.columns.${column.name}`,
+          detail: column.nullable ? 'column added' : 'NOT NULL column added with no default',
+        });
+      }
+    }
+  }
+  for (const entity of after.entities) {
+    if (!beforeByName.has(entity.name)) {
+      changes.push({ kind: 'additive', path: `entities.${entity.name}`, detail: 'entity added' });
+    }
+  }
+  return changes;
+}
+
+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;
+}
+
+function index<T>(items: readonly T[], key: (item: T) => string): Map<string, T> {
+  return new Map(items.map((item) => [key(item), item]));
+}
+
+/** One line per change, `--json`-free, for a terminal summary. */
+export function formatDiff(diff: ManifestDiff): readonly string[] {
+  return diff.changes.map((c) => `${c.kind.padEnd(8)} ${c.path}: ${c.detail}`);
+}

package/src/emit.ts

@@ -0,0 +1,137 @@
+// Serialisation and I/O for `x.manifest.json`, plus the drift check `x verify` runs.
+//
+// The serialiser writes keys in a FIXED order rather than whatever `JSON.stringify` produces,
+// so a refactor that reorders a struct literal does not produce a diff. Two-space indent and
+// a trailing newline: the file is reviewed by humans and diffed by git.
+
+import { canonical, contentHash } from './build';
+import { ManifestDriftError } from './errors';
+import type { Manifest } from './schema';
+import { isManifest } from './schema';
+
+export const MANIFEST_FILENAME = 'x.manifest.json';
+
+/** Top-level key order. Explicit so the file reads in a sensible order every time. */
+const KEY_ORDER: readonly (keyof Manifest)[] = [
+  'manifestVersion',
+  'buildId',
+  'app',
+  'routes',
+  'entities',
+  'actions',
+  'queries',
+  'jobs',
+  'tasks',
+  'policies',
+  'permissions',
+  'locales',
+  'errorCodes',
+];
+
+/** The exact bytes written to disk. Deterministic for a given manifest. */
+export function manifestJson(manifest: Manifest): string {
+  const ordered: Record<string, unknown> = {};
+  for (const key of KEY_ORDER) ordered[key] = manifest[key];
+  return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+
+export interface EmitInput {
+  readonly manifest: Manifest;
+  /** Defaults to `./x.manifest.json`. */
+  readonly path?: string;
+  /** `--json`: print to stdout instead of writing. Machine-readable output on everything. */
+  readonly stdout?: boolean;
+}
+
+export interface EmitResult {
+  readonly path: string;
+  readonly bytes: number;
+  readonly buildId: string;
+  /** False when the file already contained these exact bytes. */
+  readonly changed: boolean;
+}
+
+export async function emitManifest(input: EmitInput): Promise<EmitResult> {
+  const path = input.path ?? `./${MANIFEST_FILENAME}`;
+  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);
+    return { path, bytes: text.length, buildId: input.manifest.buildId, changed: false };
+  }
+
+  const existing = await readIfExists(path);
+  // Skip the write when nothing moved: an unchanged mtime keeps file watchers quiet.
+  if (existing === text) {
+    return { path, bytes: text.length, buildId: input.manifest.buildId, changed: false };
+  }
+  await Bun.write(path, text);
+  return { path, bytes: text.length, buildId: input.manifest.buildId, changed: true };
+}
+
+/** Read and structurally validate a manifest. `undefined` when absent or unparseable. */
+export async function readManifest(path?: string): Promise<Manifest | undefined> {
+  const text = await readIfExists(path ?? `./${MANIFEST_FILENAME}`);
+  if (text === undefined) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  return isManifest(parsed) ? parsed : undefined;
+}
+
+/**
+ * A file that does not describe itself. Kept apart from `describeDrift`'s section list because
+ * it is a different repair story: the code did not move, someone typed into the generated file.
+ */
+const HAND_EDITED = 'hand-edited — its buildId does not hash its own contents';
+
+/**
+ * Fail if the committed file does not match a freshly built manifest. Drift means an agent
+ * reading `x.manifest.json` is reading a description of a program that no longer exists —
+ * strictly worse than no manifest at all.
+ */
+export async function assertNoDrift(input: {
+  readonly manifest: Manifest;
+  readonly path?: string;
+}): Promise<void> {
+  const path = input.path ?? `./${MANIFEST_FILENAME}`;
+  const onDisk = await readManifest(path);
+  if (onDisk === undefined) {
+    throw new ManifestDriftError({ path, differences: ['file is missing or unreadable'] });
+  }
+  // Before the ids are compared, not after: a body edited by hand with its `buildId` left alone
+  // still carries the id a fresh build produces, so an id-only gate waves through the one
+  // manifest that lies about the code. `buildId` hashes the body, so the file convicts itself.
+  if (!verifyBuildId(onDisk)) {
+    throw new ManifestDriftError({ path, differences: [HAND_EDITED] });
+  }
+  if (onDisk.buildId === input.manifest.buildId) return;
+
+  throw new ManifestDriftError({ path, differences: describeDrift(onDisk, input.manifest) });
+}
+
+/** Which top-level sections moved. Enough to point at the change without dumping the file. */
+function describeDrift(onDisk: Manifest, fresh: Manifest): readonly string[] {
+  const differences: string[] = [];
+  for (const key of KEY_ORDER) {
+    if (key === 'buildId') continue;
+    if (canonical(onDisk[key]) !== canonical(fresh[key])) differences.push(`${key} differs`);
+  }
+  return differences.length > 0 ? differences : ['buildId differs'];
+}
+
+/** Verify a file's `buildId` against its own contents — catches a hand-edited manifest. */
+export function verifyBuildId(manifest: Manifest): boolean {
+  const { buildId, ...body } = manifest;
+  return contentHash(body) === buildId;
+}
+
+async function readIfExists(path: string): Promise<string | undefined> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return undefined;
+  return file.text();
+}

package/src/errors.ts

@@ -0,0 +1,93 @@
+// The X_* codes owned by @ultimat3/manifest. `x verify` raises these, so each fix line is a
+// command the developer (or the agent) can run verbatim.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const MANIFEST_ERROR_CODES = [
+  'X_MANIFEST_DRIFT',
+  'X_MANIFEST_BREAKING',
+  'X_AGENTS_MD_MISSING',
+  'X_AGENTS_MD_TOO_LARGE',
+] as const;
+
+export type ManifestErrorCode = (typeof MANIFEST_ERROR_CODES)[number];
+
+export const MANIFEST_ERROR_TITLES: Readonly<Record<ManifestErrorCode, string>> = {
+  X_MANIFEST_DRIFT: 'x.manifest.json differs from the code',
+  X_MANIFEST_BREAKING: 'a published contract was removed or narrowed',
+  X_AGENTS_MD_MISSING: 'no AGENTS.md',
+  X_AGENTS_MD_TOO_LARGE: 'AGENTS.md grew past its cap',
+};
+
+// Titles must be registered for format() to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(MANIFEST_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);
+
+const docsFor = (code: ManifestErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/**
+ * The committed `x.manifest.json` no longer matches the code. Drift means an agent reading
+ * the manifest is reading a description of a program that no longer exists.
+ */
+export class ManifestDriftError extends UltimateError {
+  constructor(input: { path: string; differences: readonly string[] }) {
+    super({
+      code: 'X_MANIFEST_DRIFT',
+      cause: `${input.path} is stale: ${summarize(input.differences)}`,
+      fix: 'x manifest',
+      docs: docsFor('X_MANIFEST_DRIFT'),
+    });
+  }
+}
+
+/** A breaking contract change landed without a version bump. */
+export class ManifestBreakingError extends UltimateError {
+  constructor(input: { changes: readonly string[]; from: string; to: string }) {
+    super({
+      code: 'X_MANIFEST_BREAKING',
+      cause:
+        `${input.changes.length} breaking change(s) from ${input.from} to ${input.to} ` +
+        `with no major version bump: ${summarize(input.changes)}`,
+      fix: 'bump the major version in app.config.ts, or restore the removed contract',
+      docs: docsFor('X_MANIFEST_BREAKING'),
+    });
+  }
+}
+
+/**
+ * `AGENTS.md` is absent. It is hand-written on purpose and is not generated, so the fix is
+ * to write one — see the note in `agents-md.ts`.
+ */
+export class AgentsMdMissingError extends UltimateError {
+  constructor(input: { path: string }) {
+    super({
+      code: 'X_AGENTS_MD_MISSING',
+      cause: `${input.path} does not exist`,
+      fix: `create ${input.path} by hand: stack, commands, conventions. Keep it short; facts live in x.manifest.json`,
+      docs: docsFor('X_AGENTS_MD_MISSING'),
+    });
+  }
+}
+
+/** `AGENTS.md` grew past its budget. A long context file measurably lowers task success. */
+export class AgentsMdTooLargeError extends UltimateError {
+  constructor(input: { path: string; bytes: number; maxBytes: number }) {
+    super({
+      code: 'X_AGENTS_MD_TOO_LARGE',
+      cause: `${input.path} is ${input.bytes}B, over the ${input.maxBytes}B budget`,
+      fix: 'move generated facts out of AGENTS.md and let x.manifest.json carry them',
+      docs: docsFor('X_AGENTS_MD_TOO_LARGE'),
+    });
+  }
+}
+
+/** First three items plus a count — a message with 400 entries is a message nobody reads. */
+function summarize(items: readonly string[]): string {
+  if (items.length <= 3) return items.join('; ');
+  return `${items.slice(0, 3).join('; ')} (+${items.length - 3} more)`;
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// Public API of @ultimat3/manifest. Explicit — `x verify`, `x manifest`, and the MCP
+// `manifest.read` resource are all built from exactly these exports.
+
+export type { AgentsMdCheck, CheckAgentsMdInput } from './agents-md';
+export {
+  AGENTS_MD_FILENAME,
+  AGENTS_MD_MAX_BYTES,
+  assertAgentsMd,
+  checkAgentsMd,
+} from './agents-md';
+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 { EmitInput, EmitResult } from './emit';
+export {
+  assertNoDrift,
+  emitManifest,
+  MANIFEST_FILENAME,
+  manifestJson,
+  readManifest,
+  verifyBuildId,
+} from './emit';
+export type { ManifestErrorCode } from './errors';
+export {
+  AgentsMdMissingError,
+  AgentsMdTooLargeError,
+  MANIFEST_ERROR_CODES,
+  MANIFEST_ERROR_TITLES,
+  ManifestBreakingError,
+  ManifestDriftError,
+} from './errors';
+export type {
+  ActionFact,
+  ColumnFact,
+  EntityFact,
+  ErrorCodeFact,
+  HydrateStrategy,
+  JobFact,
+  JsonValue,
+  Manifest,
+  OfflineStrategy,
+  PolicyFact,
+  QueryFact,
+  RenderMode,
+  RouteFact,
+  TaskFact,
+} from './schema';
+export { isCompatible, isManifest, MANIFEST_VERSION } from './schema';
+export type { FrameworkSourcesInput } from './sources';
+export { frameworkSources } from './sources';
+export type { VerifyContractInput, VerifyContractResult } from './verify';
+export { verifyContract } from './verify';

package/src/schema.ts

@@ -0,0 +1,135 @@
+// The manifest's own typed schema, plus the version field that lets a tool decide whether it
+// can read a given file. `x.manifest.json` is a public contract consumed by agents, editors,
+// and CI — a shape change without a version bump silently breaks all three.
+//
+// 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. */
+export const MANIFEST_VERSION = 1;
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
+export type OfflineStrategy = 'precache' | 'runtime' | 'network-only';
+export type HydrateStrategy = 'idle' | 'visible' | 'interaction' | 'never';
+
+export interface RouteFact {
+  readonly url: string;
+  readonly render: RenderMode;
+  readonly offline?: OfflineStrategy;
+  readonly hydrate?: HydrateStrategy;
+  readonly revalidateTags?: readonly string[];
+  readonly budget?: { readonly js?: string; readonly lcp?: number };
+  /** Which surface the route lives in — `site` may never import from `app`. */
+  readonly surface?: 'site' | 'app' | 'api';
+}
+
+export interface ColumnFact {
+  readonly name: string;
+  readonly type: string;
+  readonly nullable: boolean;
+  readonly primaryKey?: boolean;
+  readonly references?: string;
+}
+
+export interface EntityFact {
+  readonly name: string;
+  readonly table: string;
+  readonly columns: readonly ColumnFact[];
+  /** Named invariants, so an agent can see the rules without reading the migration. */
+  readonly invariants: readonly string[];
+}
+
+export interface ActionFact {
+  readonly name: string;
+  readonly input: JsonValue;
+  readonly output: JsonValue;
+  /** Permission string the policy asserts, e.g. `post:publish`. */
+  readonly policy: string | null;
+  readonly cacheInvalidates: readonly string[];
+  readonly mcp: { readonly expose: boolean; readonly description?: string };
+  readonly mutator?: boolean;
+}
+
+export interface QueryFact {
+  readonly name: string;
+  /** Optional: `QueryDescriptor` is schema-erased, so a live query may not expose one. */
+  readonly input?: JsonValue;
+  readonly policy: string | null;
+  readonly live: boolean;
+  readonly cacheTags: readonly string[];
+}
+
+export interface JobFact {
+  readonly name: string;
+  readonly input: JsonValue;
+  readonly queue: string;
+  readonly retry: { readonly attempts: number; readonly backoff: string };
+  readonly steps: readonly string[];
+}
+
+export interface TaskFact {
+  readonly name: string;
+  readonly cron: string;
+  readonly tz: string;
+  readonly enqueues: readonly string[];
+}
+
+export interface PolicyFact {
+  readonly permission: string;
+  readonly description?: string;
+  /** Where this policy is enforced. One policy, N surfaces — this lists them. */
+  readonly enforcedIn: readonly string[];
+}
+
+export interface ErrorCodeFact {
+  readonly code: string;
+  readonly package: string;
+}
+
+export interface Manifest {
+  /** Shape version. A reader checks this before anything else. */
+  readonly manifestVersion: number;
+  /** App name and semver from `app.config.ts`. Drives the breaking-change gate. */
+  readonly app: { readonly name: string; readonly version: string };
+  /**
+   * Content hash of everything below. Deterministic — NOT a timestamp and not a git sha, so
+   * two builds of the same tree produce the same manifest byte-for-byte.
+   */
+  readonly buildId: string;
+  readonly routes: readonly RouteFact[];
+  readonly entities: readonly EntityFact[];
+  readonly actions: readonly ActionFact[];
+  readonly queries: readonly QueryFact[];
+  readonly jobs: readonly JobFact[];
+  readonly tasks: readonly TaskFact[];
+  readonly policies: readonly PolicyFact[];
+  readonly permissions: readonly string[];
+  readonly locales: readonly string[];
+  readonly errorCodes: readonly ErrorCodeFact[];
+}
+
+/** Whether a reader built for `MANIFEST_VERSION` can consume `manifest`. */
+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`. */
+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'])
+  );
+}

package/src/sources.ts

@@ -0,0 +1,92 @@
+// Wires the framework's description functions into `ManifestSources`.
+//
+// Split from `build.ts` so `buildManifest` stays a pure function of its input — the
+// determinism guarantee is much easier to trust (and to test) when the builder cannot reach
+// a global registry. Routes and policies are supplied by the caller: the route table lives
+// in `@ultimat3/render`, which is this same tier.
+
+import { describeActions } from '@ultimat3/action';
+import { describeEntities } from '@ultimat3/entity';
+import { describeJobs } from '@ultimat3/jobs';
+import { describeQueries } from '@ultimat3/query';
+import type { ManifestSources } from './build';
+import type { ErrorCodeFact, JsonValue, PolicyFact, RouteFact, TaskFact } from './schema';
+
+export interface FrameworkSourcesInput {
+  readonly app: { readonly name: string; readonly version: string };
+  /** From `@ultimat3/render`'s `describeRoutes()`. */
+  readonly routes?: readonly RouteFact[];
+  /** Assembled per app from its policy modules. */
+  readonly policies?: readonly PolicyFact[];
+  readonly tasks?: readonly TaskFact[];
+  readonly locales?: readonly string[];
+  /** Each package's `*_ERROR_CODES`, flattened by the CLI. */
+  readonly errorCodes?: readonly ErrorCodeFact[];
+}
+
+/**
+ * Read every primitive registry and combine with the caller-supplied facts. The `describe*`
+ * functions return the framework's own descriptors; they are narrowed to the manifest's
+ * fact shapes here, which is the one place that mapping lives.
+ */
+/**
+ * A `JsonSchemaObject` is JSON by construction, but TypeScript will not assign an interface
+ * to an index-signature type. Converted in exactly one place rather than widening every fact.
+ */
+const asJson = (value: object): JsonValue => value as JsonValue;
+
+export function frameworkSources(input: FrameworkSourcesInput): ManifestSources {
+  return {
+    app: input.app,
+    routes: input.routes ?? [],
+    policies: input.policies ?? [],
+    tasks: input.tasks ?? [],
+    locales: input.locales ?? [],
+    errorCodes: input.errorCodes ?? [],
+    // Projected field by field, never cast: the primitive registries own richer shapes
+    // than the manifest publishes, and a cast would silently rot when either side moves.
+    entities: describeEntities().map((entity) => ({
+      name: entity.name,
+      table: entity.table,
+      columns: entity.columns.map((column) => ({
+        name: column.column,
+        type: column.kind,
+        nullable: !column.notNull,
+        primaryKey: column.primaryKey,
+        ...(column.references === null ? {} : { references: column.references }),
+      })),
+      invariants: entity.invariants.map((invariant) => invariant.name),
+    })),
+    actions: describeActions().map((action) => ({
+      name: action.name,
+      input: asJson(action.input),
+      output: asJson(action.output),
+      policy: action.capability,
+      cacheInvalidates: action.invalidates,
+      mcp: {
+        expose: action.mcp.expose,
+        ...(action.mcp.description === null ? {} : { description: action.mcp.description }),
+      },
+      // Written only when true, exactly like `mcp.description`: `ActionFact.mutator` is optional,
+      // so absence already reads as "a plain action", and a `false` on every other action would
+      // be bytes added to a file that is reviewed by hand for no fact gained.
+      ...(action.mutator ? { mutator: true } : {}),
+    })),
+    queries: describeQueries().map((query) => ({
+      name: query.name,
+      policy: query.capability,
+      live: query.live,
+      cacheTags: query.tags,
+    })),
+    jobs: describeJobs().map((job) => ({
+      name: job.name,
+      input: asJson(job.input),
+      queue: job.queue,
+      retry: { attempts: job.retry.attempts, backoff: job.retry.backoff },
+      // Empty by construction, not dropped by the projection: a step name is chosen inside
+      // `run()` at execution time, so no static reader can know it. `x jobs show` reports the
+      // steps an actual run recorded.
+      steps: job.steps,
+    })),
+  };
+}

package/src/verify.ts

@@ -0,0 +1,52 @@
+// The contract gate `x verify` runs: a breaking change is allowed, but only with a major
+// version bump. This is the enforcement half of `diff.ts` — the diff classifies, this decides.
+//
+// Enforced, not documented: a convention that isn't a build error doesn't exist.
+
+import type { ManifestDiff } from './diff';
+import { diffManifest } from './diff';
+import { ManifestBreakingError } from './errors';
+import type { Manifest } from './schema';
+
+export interface VerifyContractInput {
+  /** The manifest currently committed — the published contract. */
+  readonly before: Manifest;
+  /** The manifest just built from code. */
+  readonly after: Manifest;
+}
+
+export interface VerifyContractResult {
+  readonly diff: ManifestDiff;
+  readonly majorBumped: boolean;
+  readonly ok: boolean;
+}
+
+/**
+ * Classify, then gate. Throws `X_MANIFEST_BREAKING` when the contract broke and the major
+ * version did not move; returns the diff otherwise so the caller can print it.
+ */
+export function verifyContract(input: VerifyContractInput): VerifyContractResult {
+  const diff = diffManifest(input.before, input.after);
+  const from = majorOf(input.before.app.version);
+  const to = majorOf(input.after.app.version);
+  // Fail-closed: an unparseable version on EITHER side counts as "not bumped", so a
+  // malformed version string can never wave a breaking change through.
+  const majorBumped = from >= 0 && to >= 0 && to > from;
+  const ok = !diff.hasBreaking || majorBumped;
+
+  if (!ok) {
+    throw new ManifestBreakingError({
+      changes: diff.breaking.map((c) => `${c.path}: ${c.detail}`),
+      from: input.before.app.version,
+      to: input.after.app.version,
+    });
+  }
+  return { diff, majorBumped, ok };
+}
+
+/** Major component of a semver string, or -1 when it cannot be parsed. */
+function majorOf(version: string): number {
+  const match = /^(\d+)\./.exec(version.trim());
+  if (match === null) return -1;
+  return Number.parseInt(match[1] ?? '', 10);
+}