@ultimat3/manifest 19.1.3 → 19.3.1

package/CLAUDE.md

@@ -113,6 +113,15 @@ by the CLI, not imported.
   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.
+- **`ActionFact.mutator` is classified, and LOSING it is breaking** (`As of 2026-09`). It was
+  written by `sources.ts` and read by no `diff-*.ts` rule — two manifests differing only in an
+  action that stopped being a mutator answered `[{ kind: 'internal', path: 'buildId' }]`, the exact
+  failure the rule above exists for. A mutator is a client-contract CAPABILITY (it decides the HTTP
+  method and the idempotency the typed client and OpenAPI publish), so losing it refuses callers
+  written against it and gaining it refuses nobody. Folded with `=== true` rather than compared
+  through `diffScalar`: `sources.ts` writes the field only when true, so absence IS `false` here,
+  and an older manifest can therefore only under-report a mutator as newly GAINED, which is
+  additive. `mcp.description` joins it as `internal` — visible in the file, in no contract.
 - **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

package/README.md

@@ -74,15 +74,28 @@ permissions), `diff-rate-limit.ts`, `diff-entities.ts`, `diff-work.ts` (jobs, ta
 `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.
+moved. The version is the app's `package.json` `version`, never `app.config.ts` — `AppConfig`
+has no `version` field. 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
+  fix:   bump the major version in package.json - the leading integer, so 1.4.2 becomes
+         2.0.0 - or restore the removed contract
 ```
 
+`from === to` is the shape this fires in first, and it gets its own cause: the drift gate forces
+both sides equal in any green state, so a comparison that "moved" from 0.1.0 to 0.1.0 describes
+nothing. It reads `N breaking change(s) against the committed x.manifest.json, with package.json
+unchanged at 0.1.0` instead.
+
+An app still at **0.x** gets its own fix line too. `majorOf` compares leading integers only, so
+`0.1.0 -> 0.2.0` does not satisfy the gate and only `1.0.0` does — which is a strange demand of an
+app `x new` scaffolded at `0.1.0` with no published clients. That branch names the two honest
+actions: re-commit the baseline with `x manifest`, or `bun pm pkg set version=1.0.0` if the app
+really does have clients to keep a promise to.
+
 ## AGENTS.md: validated, never generated
 
 `checkAgentsMd()` / `assertAgentsMd()` verify that a **hand-written** `AGENTS.md` exists and

package/package.json

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

package/src/diff-operations.ts

@@ -2,7 +2,7 @@
 
 import { canonicalJson, isMcpExposed } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
-import { index } from './diff-change';
+import { diffScalar, index } from './diff-change';
 import { diffRateLimit } from './diff-rate-limit';
 import type { ActionFact, QueryFact } from './schema';
 
@@ -49,6 +49,35 @@ export function diffActions(
         detail: `mcp exposure ${String(exposed)} -> ${String(nextExposed)}`,
       });
     }
+    // `?.`, because `before` is a file parsed off DISK: a hand-trimmed or older manifest can carry
+    // no `mcp` block at all, and a description is not worth a throw out of the differ.
+    changes.push(
+      ...diffScalar(
+        'internal',
+        `${path}.mcp.description`,
+        action.mcp?.description,
+        next.mcp?.description,
+        () => 'description changed',
+      ),
+    );
+    // Written only when TRUE (`sources.ts`), so absence IS `false` here — a fold, the way
+    // `isMcpExposed` folds `expose`, and deliberately not `diffScalar`'s "absence is no evidence":
+    // the value this field is absent FOR is the value it means. A manifest written before the
+    // field existed can therefore only under-report a mutator as newly gained, which is additive
+    // and not a wall of false breakings.
+    //
+    // The direction is the decision: a mutator is a client-contract CAPABILITY, not a label — it
+    // decides the HTTP method and the idempotency the typed client and the OpenAPI document
+    // publish — so an action that stops being one refuses callers written against it.
+    const mutator = action.mutator === true;
+    const nextMutator = next.mutator === true;
+    if (mutator !== nextMutator) {
+      changes.push({
+        kind: nextMutator ? 'additive' : 'breaking',
+        path: `${path}.mutator`,
+        detail: `mutator ${String(mutator)} -> ${String(nextMutator)}`,
+      });
+    }
     changes.push(...diffPermissions(path, action, next));
     changes.push(...diffRateLimit(path, action, next));
     if (canonicalJson(action.cacheInvalidates) !== canonicalJson(next.cacheInvalidates)) {

package/src/errors.ts

@@ -49,15 +49,44 @@ export class ManifestDriftError extends UltimateError {
   }
 }
 
-/** A breaking contract change landed without a version bump. */
+/**
+ * Whether this app has ever published a major. NOT `verify.ts`'s `majorOf`, which DECIDES the gate
+ * and is fail-closed on an unparseable version; this one only picks which sentence the reader gets,
+ * and a version it cannot recognise (`"0"`, `"next"`) falls to the `else` branch — the stricter of
+ * the two instructions, so a guess is never the permissive one.
+ */
+const neverShippedAMajor = (version: string): boolean => version.trim().startsWith('0.');
+
+/**
+ * A breaking contract change landed without a version bump.
+ *
+ * Two causes and two fixes, because the FIRST time this fires it fires in a shape the single
+ * message described wrongly, twice over.
+ *
+ * `from === to` is the guaranteed first-fire shape, not an edge case: the drift gate forces the
+ * committed manifest to match the code in any green state, so both sides carry the same
+ * `package.json` version and `from 0.1.0 to 0.1.0` reads as a comparison that moved when nothing
+ * did. And `x new` scaffolds at `0.1.0`, where the instruction to bump the major is a demand for
+ * `1.0.0` from an app with no published clients — `0.2.0` does not satisfy the gate, because
+ * `majorOf` compares leading integers only.
+ *
+ * The file was wrong too: `AppConfig` has no `version` field and `defineConfig` excess-property-
+ * checks its literal, so "bump the major version in app.config.ts" fails typecheck when followed
+ * literally. The version is read from `package.json` (`app-manifest.ts`).
+ */
 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',
+        input.from === input.to
+          ? `${input.changes.length} breaking change(s) against the committed x.manifest.json, ` +
+            `with package.json unchanged at ${input.from}: ${summarize(input.changes)}`
+          : `${input.changes.length} breaking change(s) from ${input.from} to ${input.to} ` +
+            `with no major version bump: ${summarize(input.changes)}`,
+      fix: neverShippedAMajor(input.from)
+        ? 'a 0.x app has published no compatibility promise, and only 1.0.0 satisfies this gate — 0.2.0 does not: re-commit the baseline with x manifest, or bun pm pkg set version=1.0.0 in package.json'
+        : 'bump the major version in package.json — the leading integer, so 1.4.2 becomes 2.0.0 — or restore the removed contract',
     });
   }
 }

package/src/schema.ts

@@ -140,7 +140,12 @@ export interface ErrorCodeFact {
 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. */
+  /**
+   * App name and semver from the app's `package.json` (`app-manifest.ts`'s `appIdentity`), never
+   * from `app.config.ts` — `AppConfig` has no `version` field and `defineConfig`
+   * excess-property-checks its literal, so an instruction to edit one there fails typecheck.
+   * 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