@ultimat3/manifest 27.6.1 → 27.8.0

package/package.json

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

package/src/diff-routes.ts

@@ -70,6 +70,7 @@ export function diffRoutes(
         'revalidate tags changed',
       ),
     );
+    changes.push(...diffRevalidate(path, route, next));
   }
   for (const route of after) {
     if (!beforeByUrl.has(route.url)) {
@@ -79,6 +80,43 @@ export function diffRoutes(
   return changes;
 }
 
+/**
+ * What an invalidation does to the route's stored pages and what they are keyed on. `onInvalidate`
+ * is written for every `isr` route, so two manifests that both carry it both know `maxStale` and
+ * `query` — and only then is an ABSENT one of those a value ("undeclared") rather than no evidence.
+ */
+function diffRevalidate(
+  path: string,
+  route: RouteFact,
+  next: RouteFact,
+): readonly ManifestChange[] {
+  if (route.onInvalidate === undefined || next.onInvalidate === undefined) return [];
+  const declared = (value: unknown): unknown => (value === undefined ? null : value);
+  return [
+    ...diffScalar(
+      'internal',
+      `${path}.onInvalidate`,
+      route.onInvalidate,
+      next.onInvalidate,
+      (from, to) => `onInvalidate ${from} -> ${to}`,
+    ),
+    ...diffJson(
+      'internal',
+      `${path}.maxStale`,
+      declared(route.maxStale),
+      declared(next.maxStale),
+      'revalidate maxStale changed',
+    ),
+    ...diffJson(
+      'internal',
+      `${path}.query`,
+      declared(route.query),
+      declared(next.query),
+      'revalidate query changed',
+    ),
+  ];
+}
+
 /** The structural sibling of `diffScalar`: absent on either side is still no evidence. */
 function diffJson(
   kind: ManifestChange['kind'],

package/src/schema.ts

@@ -36,6 +36,16 @@ export interface RouteFact {
   readonly offline?: OfflineStrategy;
   readonly hydrate?: HydrateStrategy;
   readonly revalidateTags?: readonly string[];
+  /**
+   * An `isr` route's `revalidate.onInvalidate`, written for EVERY `isr` route — `'stale'` too — so
+   * a route flipping `'purge'` back to `'stale'` is a change `x manifest diff` can see. Its
+   * presence is also what says this manifest knows the two keys below.
+   */
+  readonly onInvalidate?: 'stale' | 'purge';
+  /** `revalidate.maxStale`, as declared; absent when the route declared none. */
+  readonly maxStale?: string | number;
+  /** `revalidate.query`, sorted; absent when the route declared none (it keys on the whole query). */
+  readonly query?: readonly string[];
   readonly budget?: { readonly js?: string };
   /** Which surface the route lives in — `site` may never import from `app`. */
   readonly surface?: 'site' | 'app' | 'api';