@ultimat3/manifest 29.3.0 → 29.3.2

package/package.json

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

package/src/diff-input.ts

@@ -0,0 +1,54 @@
+// An input schema's change, classified (`diffActions`, `diffQueries`, `diffJobs`): byte-identical
+// is no change; only ADDING optional top-level properties to an object schema is `additive`, since
+// every payload the old (closed) schema accepted the new one accepts; anything else is `breaking`.
+//
+// Deliberately shallow: only the top level is compared, so an optional property added INSIDE a
+// nested object still reads as breaking — over-reporting is the safe side of a contract check.
+
+import { canonicalJson } from '@ultimat3/core';
+import type { ManifestChange } from './diff-change';
+
+type JsonObject = Readonly<Record<string, unknown>>;
+
+const isObject = (value: unknown): value is JsonObject =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const names = (value: unknown): readonly string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+/** True when `after` accepts every payload `before` does, by only adding optional properties. */
+export function onlyAddsOptionalProperties(before: unknown, after: unknown): boolean {
+  if (!isObject(before) || !isObject(after)) return false;
+  // Only a CLOSED schema: an open one (`additionalProperties` true or absent) already accepted any
+  // extra key, so a new typed property can refuse a payload it used to take (`{ trigger: 123 }`).
+  if (before['additionalProperties'] !== false) return false;
+  const beforeProps = before['properties'];
+  const afterProps = after['properties'];
+  if (!isObject(beforeProps) || !isObject(afterProps)) return false;
+  // Everything but `properties` and `required` must be the same (type, additionalProperties, …).
+  const { properties: _bp, required: beforeRequired, ...beforeRest } = before;
+  const { properties: _ap, required: afterRequired, ...afterRest } = after;
+  if (canonicalJson(beforeRest) !== canonicalJson(afterRest)) return false;
+  // No property removed or changed.
+  for (const [name, schema] of Object.entries(beforeProps)) {
+    if (!(name in afterProps)) return false;
+    if (canonicalJson(schema) !== canonicalJson(afterProps[name])) return false;
+  }
+  // Nothing newly required — an old property or a new one.
+  const wasRequired = new Set(names(beforeRequired));
+  return names(afterRequired).every((name) => wasRequired.has(name));
+}
+
+/** The change between two input schemas at `path`, or none. */
+export function diffInput(
+  path: string,
+  before: unknown,
+  after: unknown,
+  breakingDetail: string,
+): readonly ManifestChange[] {
+  if (canonicalJson(before) === canonicalJson(after)) return [];
+  if (onlyAddsOptionalProperties(before, after)) {
+    return [{ kind: 'additive', path, detail: 'input gained optional properties' }];
+  }
+  return [{ kind: 'breaking', path, detail: breakingDetail }];
+}

package/src/diff-operations.ts

@@ -4,6 +4,7 @@
 import { canonicalJson, isMcpExposed } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
 import { diffScalar, index } from './diff-change';
+import { diffInput } from './diff-input';
 import { diffRateLimit } from './diff-rate-limit';
 import type { ActionFact, QueryFact } from './schema';
 
@@ -28,9 +29,7 @@ export function diffActions(
       changes.push({ kind: 'breaking', path, detail: 'action removed' });
       continue;
     }
-    if (canonicalJson(action.input) !== canonicalJson(next.input)) {
-      changes.push({ kind: 'breaking', path: `${path}.input`, detail: 'input schema changed' });
-    }
+    changes.push(...diffInput(`${path}.input`, action.input, next.input, 'input schema changed'));
     if (canonicalJson(action.output) !== canonicalJson(next.output)) {
       changes.push({ kind: 'breaking', path: `${path}.output`, detail: 'output schema changed' });
     }
@@ -119,12 +118,8 @@ export function diffQueries(
     }
     // 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.input !== undefined && next.input !== undefined) {
+      changes.push(...diffInput(`${path}.input`, query.input, next.input, 'input schema changed'));
     }
     if (query.policy !== next.policy) {
       changes.push({

package/src/diff-work.ts

@@ -5,6 +5,7 @@
 import { canonicalJson } from '@ultimat3/core';
 import type { ManifestChange } from './diff-change';
 import { diffScalar, index } from './diff-change';
+import { diffInput } from './diff-input';
 import type { JobFact, TaskFact } from './schema';
 
 export function diffJobs(
@@ -23,13 +24,15 @@ export function diffJobs(
       changes.push({ kind: 'breaking', path, detail: 'job removed' });
       continue;
     }
-    if (canonicalJson(job.input) !== canonicalJson(next.input)) {
-      changes.push({
-        kind: 'breaking',
-        path: `${path}.input`,
-        detail: 'input schema changed; in-flight payloads will not parse',
-      });
-    }
+    // An optional property added is additive: every in-flight payload still parses.
+    changes.push(
+      ...diffInput(
+        `${path}.input`,
+        job.input,
+        next.input,
+        'input schema changed; in-flight payloads will not parse',
+      ),
+    );
     // The same failure as a removal, from the worker's side: a fleet subscribed to the old queue
     // keeps running and stops receiving this job, and the rows pile up where nobody drains them.
     changes.push(