@ultimat3/manifest 23.0.0 → 24.0.0

package/CLAUDE.md

@@ -62,7 +62,10 @@ by the CLI, not imported.
   they already carried — so the swap is observable only where the old form folded. **The published
   document is `manifestJson` and is still `JSON.stringify` with a fixed key order**: an injective
   form emits tokens JSON cannot parse, which is why `@ultimat3/action`'s `stableStringify` exists
-  as a separate function and why this one may not be written to disk.
+  as a separate function and why this one may not be written to disk. **So a fact the document
+  cannot hold is refused at build** (`As of 2026-10-02`, `finite-facts.ts`, `X_MANIFEST_FACT_INVALID`
+  with `meta.path`): `NaN`, `±Infinity` and `-0` hashed apart from what the file wrote, so a manifest
+  carrying one failed its own `verifyBuildId` and read as drift on every build.
 - 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
@@ -136,6 +139,11 @@ by the CLI, not imported.
   "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.
+  `QueryFact.input` follows the same rule (`As of 2026-10-02`): `sources.ts` now projects the
+  handle's schema through `jsonSchemaOf` — it wrote none before, so the README's promise was false
+  and the input compare never fired — and a committed manifest from before carries none.
+  `hasDefault` is different: absent IS "no default", so a NOT NULL column losing one is breaking,
+  a nullable one `internal`, gaining one additive.
 - **`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/package.json

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

package/src/build.ts

@@ -16,7 +16,8 @@
 // assembled per app — both outside what this tier may import — so the CLI supplies them and
 // this function stays pure and unit-testable.
 
-import { canonicalJson } from '@ultimat3/core';
+import { fingerprint } from '@ultimat3/core';
+import { assertFiniteFacts } from './finite-facts';
 import type {
   ActionFact,
   AdminFact,
@@ -96,21 +97,22 @@ export function buildManifest(sources: ManifestSources): Manifest {
     errorCodes,
   };
 
+  // Before the hash: a fact the written file cannot hold must never get a buildId at all.
+  assertFiniteFacts(body, '');
   return { ...body, buildId: contentHash(body) };
 }
 
 /**
- * Content hash of the manifest body. Deliberately excludes `buildId` itself, and is taken over
- * `@ultimat3/core`'s `canonicalJson` — the same INJECTIVE form the diff compares on, so a fact
- * that changed cannot hash the same as the fact it replaced.
+ * Content hash of the manifest body: `@ultimat3/core`'s `fingerprint`, SHA-256/16 over the same
+ * INJECTIVE `canonicalJson` the diff compares on, so a fact that changed cannot hash the same as
+ * the fact it replaced. It was a hand-written copy of that function, byte for byte — the value is
+ * unchanged, the second implementation is gone. Deliberately excludes `buildId` itself.
  *
  * This is a HASH, never the published document: `manifestJson` in `emit.ts` is what reaches disk,
  * and it is `JSON.stringify` with a fixed key order for exactly that reason.
  */
 export function contentHash(body: Omit<Manifest, 'buildId'>): string {
-  const hasher = new Bun.CryptoHasher('sha256');
-  hasher.update(canonicalJson(body));
-  return hasher.digest('hex').slice(0, 16);
+  return fingerprint(body);
 }
 
 function sortBy<T>(items: readonly T[], key: (item: T) => string): readonly T[] {

package/src/diff-entities.ts

@@ -108,6 +108,7 @@ function diffColumns(
           : { kind: 'breaking', path: `${at}.nullable`, detail: 'became NOT NULL' },
       );
     }
+    changes.push(...diffDefault(`${at}.hasDefault`, column.hasDefault === true, next));
     changes.push(...diffKey(at, 'primaryKey', keyOf(column), keyOf(next)));
     changes.push(...diffKey(at, 'references', column.references, next.references));
     changes.push(...diffSealed(`${at}.sealed`, column.sealed, next.sealed));
@@ -133,6 +134,27 @@ function diffColumns(
   return changes;
 }
 
+/**
+ * A declared default on a column that was already there. It was read for an ADDED column only, so
+ * a NOT NULL column losing its default reported nothing but `buildId` — while every writer that
+ * omits the column is refused from then on. Dropped from a nullable column, an omitted value
+ * becomes NULL instead: nobody is refused, but the stored meaning moved. Gaining one only widens.
+ */
+function diffDefault(
+  path: string,
+  had: boolean,
+  next: EntityFact['columns'][number],
+): readonly ManifestChange[] {
+  const has = next.hasDefault === true;
+  if (had === has) return [];
+  if (has) return [{ kind: 'additive', path, detail: 'default added' }];
+  return [
+    next.nullable
+      ? { kind: 'internal', path, detail: 'default dropped; an omitted value is now NULL' }
+      : { kind: 'breaking', path, detail: 'default dropped; a writer that omits it is refused' },
+  ];
+}
+
 /**
  * How a column is sealed is a WIRE fact as much as a storage one: `.sealed()` emits no DDL and
  * leaves the column's type alone, so nothing else in the file moves — while the field leaves every

package/src/diff-fixtures.ts

@@ -49,7 +49,7 @@ export const FIXTURE: ManifestSources = {
       offline: 'precache',
       hydrate: 'idle',
       revalidateTags: ['post'],
-      budget: { js: '40kb', lcp: 2000 },
+      budget: { js: '40kb' },
       surface: 'site',
     },
   ],

package/src/diff-operations.ts

@@ -117,7 +117,13 @@ export function diffQueries(
       changes.push({ kind: 'breaking', path, detail: 'query removed' });
       continue;
     }
-    if (canonicalJson(query.input) !== canonicalJson(next.input)) {
+    // Both sides or neither: a manifest committed before queries published their input carries
+    // none, and a side with nothing on it is no evidence of a change (`diff-routes.ts`'s rule).
+    if (
+      query.input !== undefined &&
+      next.input !== undefined &&
+      canonicalJson(query.input) !== canonicalJson(next.input)
+    ) {
       changes.push({ kind: 'breaking', path: `${path}.input`, detail: 'input schema changed' });
     }
     if (query.policy !== next.policy) {

package/src/errors.ts

@@ -8,6 +8,7 @@ export const MANIFEST_ERROR_CODES = [
   'X_MANIFEST_BREAKING',
   'X_AGENTS_MD_MISSING',
   'X_AGENTS_MD_TOO_LARGE',
+  'X_MANIFEST_FACT_INVALID',
 ] as const;
 
 export type ManifestErrorCode = (typeof MANIFEST_ERROR_CODES)[number];
@@ -17,6 +18,7 @@ export const MANIFEST_ERROR_TITLES: Readonly<Record<ManifestErrorCode, string>>
   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',
+  X_MANIFEST_FACT_INVALID: 'a manifest fact is a number JSON cannot write back',
 };
 
 // Titles must be registered for format() to render the contract's first line. Every code above is
@@ -116,6 +118,26 @@ export class AgentsMdTooLargeError extends UltimateError {
   }
 }
 
+/**
+ * A number in the manifest body that JSON cannot write back as itself. `canonicalJson` hashes `NaN`,
+ * `Infinity` and `-0` as those tokens and `JSON.stringify` writes them as `null` and `0`, so a
+ * manifest built from one fails its own `verifyBuildId` the moment it is read back, and the
+ * committed file reads as drift on every build. `path` is where in the body it sits.
+ */
+export class ManifestFactInvalidError extends UltimateError {
+  constructor(input: { path: string; value: string }) {
+    super({
+      code: 'X_MANIFEST_FACT_INVALID',
+      cause: `the manifest fact at ${input.path} is ${input.value}, which x.manifest.json would write as ${input.value === '-0' ? '0' : 'null'} — the file could never match its own buildId`,
+      fix:
+        input.value === '-0'
+          ? `set the declaration that publishes ${input.path} to 0, then run x manifest`
+          : `set the declaration that publishes ${input.path} to a finite number, then run x manifest`,
+      meta: { path: input.path, value: input.value },
+    });
+  }
+}
+
 /** 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('; ');

package/src/finite-facts.ts

@@ -0,0 +1,28 @@
+// Single responsibility: refuse a manifest number JSON cannot write back as itself. The body is
+// hashed by `canonicalJson`, which keeps `NaN`, `Infinity` and `-0` distinct, and written by
+// `JSON.stringify`, which does not — so one such fact made a manifest that failed its own buildId.
+
+import { ManifestFactInvalidError } from './errors';
+
+/** Depth-first, in key order, so the refusal names the FIRST offending fact the file would hold. */
+export function assertFiniteFacts(value: unknown, path: string): void {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value) || Object.is(value, -0)) {
+      throw new ManifestFactInvalidError({
+        path,
+        value: Object.is(value, -0) ? '-0' : String(value),
+      });
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item: unknown, index) => {
+      assertFiniteFacts(item, `${path}[${String(index)}]`);
+    });
+    return;
+  }
+  if (value === null || typeof value !== 'object') return;
+  for (const [key, item] of Object.entries(value)) {
+    assertFiniteFacts(item, path === '' ? key : `${path}.${key}`);
+  }
+}

package/src/index.ts

@@ -39,6 +39,7 @@ export {
   MANIFEST_ERROR_TITLES,
   ManifestBreakingError,
   ManifestDriftError,
+  ManifestFactInvalidError,
 } from './errors';
 export type {
   ActionFact,

package/src/schema.ts

@@ -36,7 +36,7 @@ export interface RouteFact {
   readonly offline?: OfflineStrategy;
   readonly hydrate?: HydrateStrategy;
   readonly revalidateTags?: readonly string[];
-  readonly budget?: { readonly js?: string; readonly lcp?: number };
+  readonly budget?: { readonly js?: string };
   /** Which surface the route lives in — `site` may never import from `app`. */
   readonly surface?: 'site' | 'app' | 'api';
 }
@@ -173,7 +173,11 @@ export interface ActionFact {
 
 export interface QueryFact {
   readonly name: string;
-  /** Optional: `QueryDescriptor` is schema-erased, so a live query may not expose one. */
+  /**
+   * The input's JSON Schema, projected from the query handle as an action's is. Optional only for
+   * a manifest committed before queries published it; `diffQueries` reads an absent side as no
+   * evidence rather than as a changed schema.
+   */
   readonly input?: JsonValue;
   /** The policy's DISPLAY label — see `ActionFact.policy`, and read `permissions` to match on. */
   readonly policy: string | null;

package/src/sources.ts

@@ -5,10 +5,10 @@
 // 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 { describeActions, jsonSchemaOf } from '@ultimat3/action';
 import { describeEntities, registeredEntities, sealedFields } from '@ultimat3/entity';
 import { describeJobs } from '@ultimat3/jobs';
-import { describeQueries } from '@ultimat3/query';
+import { describeQueries, getQuery } from '@ultimat3/query';
 import { describeChannels } from '@ultimat3/realtime/server';
 import type { ManifestSources } from './build';
 import type {
@@ -49,6 +49,12 @@ export interface FrameworkSourcesInput {
  */
 const asJson = (value: object): JsonValue => value as JsonValue;
 
+/** `describeQueries` and `getQuery` read one registry, so the handle is always there. */
+const queryInput = (name: string): { readonly input?: JsonValue } => {
+  const handle = getQuery(name);
+  return handle === undefined ? {} : { input: asJson(jsonSchemaOf(handle.input)) };
+};
+
 /** Absent stays absent: only a sealed column carries the field. */
 const sealedFact = (
   how: 'opaque' | 'lookup' | undefined,
@@ -121,6 +127,9 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
     })),
     queries: describeQueries().map((query) => ({
       name: query.name,
+      // The handle's own schema, projected exactly as an action's is: the descriptor is
+      // schema-erased, and without this `diffQueries`' input compare never fired on a real app.
+      ...queryInput(query.name),
       policy: query.capability,
       permissions: query.permissions,
       live: query.live,