@ultimat3/manifest 17.0.0 → 18.0.0

package/CLAUDE.md

@@ -132,6 +132,14 @@ by the CLI, not imported.
   **breaking**, so it also demands a major release of every APP that regenerates. Charging every
   app a major for a field their readers never had to look at is a fix line that is not true.
   `build.test.ts`'s `shape compatibility` case is the assertion — if it fails, the bump is earned.
+- **`QueryFact.subscribes` is the one fact a tier-1 generator cannot reach any other way** (`As of
+  2026-08-26`). `@ultimat3/db` needs the tables a live query subscribes to so `x db gen` can grant
+  them `REPLICA IDENTITY FULL`, and `@ultimat3/cli` (tier 5) cannot import `@ultimat3/query`'s
+  runtime to ask — the manifest is the crossing. Written only when the read declared some:
+  `QueryDescriptor.subscribes` is `null` for a read that named none and an empty list is refused at
+  `query()`, so absence carries the whole meaning and no plain read pays a key for it. Classified
+  in `diff-operations.ts` as **internal** — no caller's contract moved — but reported, because the
+  list is what a migration is keyed on.
 - `diff.ts` reads `mcp.expose` through `isMcpExposed` from `@ultimat3/core`, on **both** sides.
   `before` is a file parsed off disk, so an older or hand-trimmed manifest can carry an absent or
   non-boolean value that `!==` would classify from; and the fact `sources.ts` publishes has to be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "17.0.0",
+  "version": "18.0.0",
   "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
   "license": "MIT",
   "type": "module",
@@ -24,17 +24,17 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "17.0.0",
-    "@ultimat3/core": "17.0.0",
-    "@ultimat3/entity": "17.0.0",
-    "@ultimat3/jobs": "17.0.0",
-    "@ultimat3/query": "17.0.0"
+    "@ultimat3/action": "18.0.0",
+    "@ultimat3/core": "18.0.0",
+    "@ultimat3/entity": "18.0.0",
+    "@ultimat3/jobs": "18.0.0",
+    "@ultimat3/query": "18.0.0"
   }
 }

package/src/build.ts

@@ -147,6 +147,9 @@ const normalizeQuery = (query: QueryFact): QueryFact => ({
   ...query,
   permissions: [...query.permissions].sort(),
   cacheTags: [...query.cacheTags].sort(),
+  // Conditional, not `?? []`: the fact is absent when the read declared nothing, and writing an
+  // empty array would make every plain read carry a key that means the same as no key.
+  ...(query.subscribes === undefined ? {} : { subscribes: [...query.subscribes].sort() }),
 });
 
 // Job steps keep their DECLARED order — a job's steps are a sequence, not a set, and

package/src/diff-fixtures.ts

@@ -27,6 +27,7 @@ export const fixtureQuery = (name: string, policy: string, permissions = [policy
   policy,
   permissions,
   live: true,
+  subscribes: ['posts'],
   cacheTags: ['post'],
 });
 

package/src/diff-operations.ts

@@ -106,6 +106,15 @@ export function diffQueries(
     if (canonicalJson(query.cacheTags) !== canonicalJson(next.cacheTags)) {
       changes.push({ kind: 'internal', path: `${path}.cacheTags`, detail: 'cache tags changed' });
     }
+    // Internal for the same reason, and reported for a sharper one: this list is what `x db gen`
+    // grants REPLICA IDENTITY FULL to, so a move here is a migration the release owes.
+    if (canonicalJson(query.subscribes ?? null) !== canonicalJson(next.subscribes ?? null)) {
+      changes.push({
+        kind: 'internal',
+        path: `${path}.subscribes`,
+        detail: 'subscribed relations changed',
+      });
+    }
   }
   for (const query of after) {
     if (!beforeByName.has(query.name)) {

package/src/schema.ts

@@ -96,6 +96,17 @@ export interface QueryFact {
   /** Every permission the policy asserts, flattened through the combinators, deduped and sorted. */
   readonly permissions: readonly string[];
   readonly live: boolean;
+  /**
+   * The relations a live read is patched from, as the query DECLARED them — absent when it
+   * declared none, exactly like `ActionFact.rateLimit`, because an empty array on every plain
+   * read is bytes in a hand-reviewed file for no fact gained.
+   *
+   * The reason this fact exists: `x db gen` has to grant `REPLICA IDENTITY FULL` to those tables
+   * or `@ultimat3/realtime` refuses the subscription, and `@ultimat3/cli` cannot derive them —
+   * the relation name lives inside the query's `sql:` callback, which no generator can invoke
+   * without valid input. So the manifest is the one place a tier-1 generator can read it.
+   */
+  readonly subscribes?: readonly string[];
   readonly cacheTags: readonly string[];
 }
 

package/src/sources.ts

@@ -81,6 +81,9 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
       policy: query.capability,
       permissions: query.permissions,
       live: query.live,
+      // Written only when declared — `null` is the descriptor's "the read named none", and an
+      // empty list is refused at `query()`, so absence carries the whole meaning.
+      ...(query.subscribes === null ? {} : { subscribes: query.subscribes }),
       cacheTags: query.tags,
     })),
     jobs: describeJobs().map((job) => ({