@ultimat3/manifest 7.0.0 → 8.0.0

package/CLAUDE.md

@@ -33,7 +33,16 @@ 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`.
-- `buildId` = sha256 of the canonical body. Verifiable from the file alone.
+- `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`
+  (**removed, breaking**): that form spells `-0` as `0` and `NaN`/`±Infinity` as `null`, so a
+  default a client is told to expect could move and the diff answered "no change". Ordinary JSON
+  is byte-identical between the two — both tracked apps' committed manifests hash to the same id
+  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.
 - 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

package/README.md

@@ -45,7 +45,7 @@ bytes. Enforced, not hoped for:
   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 —
+- `buildId` is a sha256 of `canonicalJson` (`@ultimat3/core`) over the 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.
 

package/package.json

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

package/src/build.ts

@@ -16,6 +16,7 @@
 // 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 type {
   ActionFact,
   EntityFact,
@@ -90,30 +91,19 @@ export function buildManifest(sources: ManifestSources): Manifest {
 }
 
 /**
- * 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.
+ * 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.
+ *
+ * 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(canonical(body));
+  hasher.update(canonicalJson(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);

package/src/diff-operations.ts

@@ -1,7 +1,6 @@
 // The two callable surfaces — actions and queries — and the permissions they require.
 
-import { isMcpExposed } from '@ultimat3/core';
-import { canonical } from './build';
+import { canonicalJson, isMcpExposed } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
 import { index } from './diff-change';
 import { diffRateLimit } from './diff-rate-limit';
@@ -23,10 +22,10 @@ export function diffActions(
       changes.push({ kind: 'breaking', path, detail: 'action removed' });
       continue;
     }
-    if (canonical(action.input) !== canonical(next.input)) {
+    if (canonicalJson(action.input) !== canonicalJson(next.input)) {
       changes.push({ kind: 'breaking', path: `${path}.input`, detail: 'input schema changed' });
     }
-    if (canonical(action.output) !== canonical(next.output)) {
+    if (canonicalJson(action.output) !== canonicalJson(next.output)) {
       changes.push({ kind: 'breaking', path: `${path}.output`, detail: 'output schema changed' });
     }
     if (action.policy !== next.policy) {
@@ -52,7 +51,7 @@ export function diffActions(
     }
     changes.push(...diffPermissions(path, action, next));
     changes.push(...diffRateLimit(path, action, next));
-    if (canonical(action.cacheInvalidates) !== canonical(next.cacheInvalidates)) {
+    if (canonicalJson(action.cacheInvalidates) !== canonicalJson(next.cacheInvalidates)) {
       changes.push({
         kind: 'internal',
         path: `${path}.cacheInvalidates`,
@@ -83,7 +82,7 @@ export function diffQueries(
       changes.push({ kind: 'breaking', path, detail: 'query removed' });
       continue;
     }
-    if (canonical(query.input) !== canonical(next.input)) {
+    if (canonicalJson(query.input) !== canonicalJson(next.input)) {
       changes.push({ kind: 'breaking', path: `${path}.input`, detail: 'input schema changed' });
     }
     if (query.policy !== next.policy) {
@@ -104,7 +103,7 @@ export function diffQueries(
     }
     // 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)) {
+    if (canonicalJson(query.cacheTags) !== canonicalJson(next.cacheTags)) {
       changes.push({ kind: 'internal', path: `${path}.cacheTags`, detail: 'cache tags changed' });
     }
   }

package/src/diff-routes.ts

@@ -2,7 +2,7 @@
 // now answers JSON breaks every link to it — while the delivery facts (`render`, `offline`,
 // `hydrate`, `budget`, `revalidateTags`) are internal and reported.
 
-import { canonical } from './build';
+import { canonicalJson } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
 import { diffScalar, index } from './diff-change';
 import type { RouteFact } from './schema';
@@ -88,6 +88,6 @@ function diffJson(
   detail: string,
 ): readonly ManifestChange[] {
   if (before === undefined || after === undefined) return [];
-  if (canonical(before) === canonical(after)) return [];
+  if (canonicalJson(before) === canonicalJson(after)) return [];
   return [{ kind, path, detail }];
 }

package/src/diff-work.ts

@@ -2,7 +2,7 @@
 // nothing throws, the work simply stops happening — which is why a removal on either side is
 // breaking rather than a note in the diff.
 
-import { canonical } from './build';
+import { canonicalJson } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
 import { diffScalar, index } from './diff-change';
 import type { JobFact, TaskFact } from './schema';
@@ -23,7 +23,7 @@ export function diffJobs(
       changes.push({ kind: 'breaking', path, detail: 'job removed' });
       continue;
     }
-    if (canonical(job.input) !== canonical(next.input)) {
+    if (canonicalJson(job.input) !== canonicalJson(next.input)) {
       changes.push({
         kind: 'breaking',
         path: `${path}.input`,
@@ -42,7 +42,7 @@ export function diffJobs(
       ),
     );
     changes.push(...diffRetry(path, job, next));
-    if (canonical(job.steps) !== canonical(next.steps)) {
+    if (canonicalJson(job.steps) !== canonicalJson(next.steps)) {
       changes.push({
         kind: 'internal',
         path: `${path}.steps`,
@@ -118,7 +118,7 @@ export function diffTasks(
     changes.push(
       ...diffScalar('internal', `${path}.tz`, task.tz, next.tz, (a, b) => `${a} -> ${b}`),
     );
-    if (canonical(task.enqueues) !== canonical(next.enqueues)) {
+    if (canonicalJson(task.enqueues) !== canonicalJson(next.enqueues)) {
       changes.push({ kind: 'internal', path: `${path}.enqueues`, detail: 'enqueued jobs changed' });
     }
   }

package/src/emit.ts

@@ -4,7 +4,8 @@
 // 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 { canonicalJson } from '@ultimat3/core';
+import { contentHash } from './build';
 import { ManifestDriftError } from './errors';
 import type { Manifest } from './schema';
 import { isManifest } from './schema';
@@ -127,7 +128,8 @@ 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`);
+    if (canonicalJson(onDisk[key]) !== canonicalJson(fresh[key]))
+      differences.push(`${key} differs`);
   }
   return differences.length > 0 ? differences : ['buildId differs'];
 }

package/src/index.ts

@@ -10,7 +10,7 @@ export {
   checkAgentsMd,
 } from './agents-md';
 export type { ManifestSources } from './build';
-export { buildManifest, canonical, contentHash } from './build';
+export { buildManifest, contentHash } from './build';
 export type { ChangeKind, ManifestChange, ManifestDiff } from './diff';
 export { diffManifest, formatDiff } from './diff';
 export type { DocEntry, DocEntryKind } from './docs-scan';