@ultimat3/manifest 19.1.3 → 19.2.0

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.2.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": "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.2.0",
+    "@ultimat3/core": "19.2.0",
+    "@ultimat3/entity": "19.2.0",
+    "@ultimat3/jobs": "19.2.0",
+    "@ultimat3/query": "19.2.0"
   }
 }

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