@ultimat3/manifest 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -32,7 +32,18 @@ by the CLI, not imported.
 
 - **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`.
+- Top-level key order in the file is fixed by `KEY_ORDER` in `emit.ts` — `as const satisfies
+  readonly (keyof Manifest)[]` AND walked by `emit.test.ts`, the treatment `ARRAY_SECTIONS` has,
+  because the annotation catches a key that is not on `Manifest` and only the walk catches one that
+  is MISSING. `manifestJson` writes those keys and no others while `contentHash` hashes the whole
+  body, so a 14th field would go into the hash and be dropped from the file — after which
+  `assertNoDrift` convicts the committed manifest as HAND_EDITED, a correct refusal with the wrong
+  diagnosis, about a file nobody touched.
+- **Every author-declared inner list is sorted**, `routes[].revalidateTags` included (`As of
+  2026-08-23`). It was the one collection `buildManifest` left in declaration order, so reordering
+  `revalidate: [tag.b, tag.a]` in a route file churned `buildId` and emitted a
+  `routes.<url>.revalidateTags` change nothing had changed. `jobs[].steps` is the one exception and
+  says so at its own declaration: steps are a sequence, not a set.
 - `buildId` = sha256 of `@ultimat3/core`'s `canonicalJson` over the body — the framework's one
   INJECTIVE form, and the same one every `diff-*.ts` equality is taken over. It was a local
   `JSON.stringify(sortKeys(v))` until 2026-08-22, exported from `index.ts` as `canonical`
@@ -98,7 +109,9 @@ by the CLI, not imported.
 - **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
+  still reported (an invariant dropped, a permission dropped, more attempts, **a column that lost
+  NOT NULL** — `diffColumns` implemented only the tightening half until 2026-08-23, so a loosened
+  column was reported as nothing at all). 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

package/README.md

@@ -40,7 +40,8 @@ The file is committed and reviewed, so two builds of the same tree must produce
 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
+- Every collection is sorted by a stable key before writing, inner lists included (a route's
+  `revalidateTags`, an action's `cacheInvalidates`, a task's `enqueues`) — `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
@@ -59,7 +60,7 @@ whole mechanism.
 | Class | Examples |
 |---|---|
 | **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 |
+| **additive** | primitive added; nullable column added; **a column that lost NOT NULL**; 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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "9.0.0",
+  "version": "10.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": "9.0.0",
-    "@ultimat3/core": "9.0.0",
-    "@ultimat3/entity": "9.0.0",
-    "@ultimat3/jobs": "9.0.0",
-    "@ultimat3/query": "9.0.0"
+    "@ultimat3/action": "10.0.0",
+    "@ultimat3/core": "10.0.0",
+    "@ultimat3/entity": "10.0.0",
+    "@ultimat3/jobs": "10.0.0",
+    "@ultimat3/query": "10.0.0"
   }
 }

package/src/build.ts

@@ -44,7 +44,7 @@ export interface ManifestSources {
 }
 
 export function buildManifest(sources: ManifestSources): Manifest {
-  const routes = sortBy(sources.routes ?? [], (r) => r.url);
+  const routes = sortBy(sources.routes ?? [], (r) => r.url).map(normalizeRoute);
   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);
@@ -117,6 +117,18 @@ function unique(values: readonly string[]): readonly string[] {
 }
 
 // Inner collections are sorted too: a reordered column list is a spurious diff.
+// `revalidateTags` is an author-declared SET — the same kind of list as an action's
+// `cacheInvalidates`, which has always been sorted here. Left in declaration order it was the one
+// inner collection `buildManifest` did not normalise, so reordering `revalidate: [tag.b, tag.a]`
+// in a route file churned `buildId` and emitted a spurious `routes.<url>.revalidateTags` change.
+// `jobs[].steps` is the one deliberate exception, and says why above itself.
+const normalizeRoute = (route: RouteFact): RouteFact =>
+  route.revalidateTags === undefined
+    ? route
+    : // Spread, never assigned: `exactOptionalPropertyTypes` makes an explicit `undefined` a
+      // different answer from an absent key, and `emit.ts` writes what it is given.
+      { ...route, revalidateTags: [...route.revalidateTags].sort() };
+
 const normalizeEntity = (entity: EntityFact): EntityFact => ({
   ...entity,
   columns: sortBy(entity.columns, (c) => c.name),

package/src/diff-entities.ts

@@ -96,9 +96,17 @@ function diffColumns(
         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' });
+    if (column.nullable !== next.nullable) {
+      // Both directions, the axis this file's header declares and `diffInvariants` already
+      // implements: tightening rejects rows that were valid a moment ago, loosening only widens
+      // what the table accepts — and a constraint that quietly stopped being enforced is what a
+      // reviewer of a data migration most needs to see. Only the tightening half was here, so
+      // dropping NOT NULL reported nothing at all.
+      changes.push(
+        next.nullable
+          ? { kind: 'additive', path: `${at}.nullable`, detail: 'became nullable' }
+          : { 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));

package/src/emit.ts

@@ -12,8 +12,19 @@ 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)[] = [
+/**
+ * Top-level key order. Explicit so the file reads in a sensible order every time.
+ *
+ * `as const satisfies` and a test that WALKS it, the treatment `ARRAY_SECTIONS` already has
+ * (`schema.ts`) — the annotation catches a key that is not on `Manifest`, only a walk catches one
+ * that is missing. It was a bare annotation, and `manifestJson` writes these keys and no others
+ * while `contentHash` hashes the whole body: a 14th field added to `Manifest` would have gone into
+ * the hash and been dropped from the file, after which `assertNoDrift` convicts the committed
+ * manifest as HAND_EDITED — a correct refusal carrying the wrong diagnosis, about a file nobody
+ * touched. Exported for that test alone; deliberately NOT re-exported by `src/index.ts`, because
+ * the ORDER is this module's business and a public one would be semver-locked.
+ */
+export const KEY_ORDER = [
   'manifestVersion',
   'buildId',
   'app',
@@ -27,7 +38,7 @@ const KEY_ORDER: readonly (keyof Manifest)[] = [
   'permissions',
   'locales',
   'errorCodes',
-];
+] as const satisfies readonly (keyof Manifest)[];
 
 /** The exact bytes written to disk. Deterministic for a given manifest. */
 export function manifestJson(manifest: Manifest): string {

package/src/errors.ts

@@ -28,7 +28,12 @@ registerErrorCodes(
   ),
 );
 
-const docsFor = (code: ManifestErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
+// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
+// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
+// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
+// answered 404, host included, on every error it has ever thrown; restating the replacement here
+// would be the same constant in eight places waiting to drift again.
 
 /**
  * The committed `x.manifest.json` no longer matches the code. Drift means an agent reading
@@ -40,7 +45,6 @@ export class ManifestDriftError extends UltimateError {
       code: 'X_MANIFEST_DRIFT',
       cause: `${input.path} is stale: ${summarize(input.differences)}`,
       fix: 'x manifest',
-      docs: docsFor('X_MANIFEST_DRIFT'),
     });
   }
 }
@@ -54,7 +58,6 @@ export class ManifestBreakingError extends UltimateError {
         `${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'),
     });
   }
 }
@@ -69,7 +72,6 @@ export class AgentsMdMissingError extends UltimateError {
       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'),
     });
   }
 }
@@ -81,7 +83,6 @@ export class AgentsMdTooLargeError extends UltimateError {
       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'),
     });
   }
 }