@ultimat3/manifest 16.0.0 → 18.0.0

package/CLAUDE.md

@@ -30,6 +30,13 @@ by the CLI, not imported.
 
 ## Invariants
 
+- **`checkAgentsMd`'s `maxBytes` is a whole number of 0 or more** (`As of 2026-08-26`),
+  `finiteCount('checkAgentsMd', 'maxBytes', …)`, and it is screened in `checkAgentsMd` rather than
+  in `assertAgentsMd` because that is the function that READS the option — "inspect without
+  throwing" is a promise about the repository's state, not about a caller passing a budget that is
+  not a number. `bytes > maxBytes` is false when `maxBytes` is `NaN`, so `assertAgentsMd` passed an
+  `AGENTS.md` of any size while the `AgentsMdCheck` it returned reported `ok: false`: the gate's
+  throw and the gate's report disagreeing about one file, with nothing raising.
 - **No nondeterminism.** No timestamp, git sha, hostname, counter, or unsorted iteration.
   `buildManifest` is pure — it must never read a registry, a clock, or the filesystem.
 - Top-level key order in the file is fixed by `KEY_ORDER` in `emit.ts` — `as const satisfies
@@ -125,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": "16.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": "16.0.0",
-    "@ultimat3/core": "16.0.0",
-    "@ultimat3/entity": "16.0.0",
-    "@ultimat3/jobs": "16.0.0",
-    "@ultimat3/query": "16.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/agents-md.ts

@@ -15,6 +15,7 @@
 // This module therefore checks exactly two things: that the file exists, and that it has not
 // grown into a document nobody reads. It never writes.
 
+import { finiteCount } from '@ultimat3/core';
 import { AgentsMdMissingError, AgentsMdTooLargeError } from './errors';
 
 export const AGENTS_MD_FILENAME = 'AGENTS.md';
@@ -43,7 +44,12 @@ export interface CheckAgentsMdInput {
 /** Inspect without throwing — `x verify --json` reports, `assertAgentsMd` enforces. */
 export async function checkAgentsMd(input: CheckAgentsMdInput = {}): Promise<AgentsMdCheck> {
   const path = input.path ?? `./${AGENTS_MD_FILENAME}`;
-  const maxBytes = input.maxBytes ?? AGENTS_MD_MAX_BYTES;
+  // `bytes > maxBytes` is false when `maxBytes` is `NaN`, so `assertAgentsMd` passed a file of any
+  // size while the check it returned reported `ok: false` — the gate's throw and the gate's report
+  // disagreeing about one file, with nothing raising. Screened here rather than in `assertAgentsMd`
+  // because this is the function that reads the option; "inspect without throwing" is about the
+  // file's state, and a budget that is not a number is the caller's bug, not the repository's.
+  const maxBytes = finiteCount('checkAgentsMd', 'maxBytes', input.maxBytes ?? AGENTS_MD_MAX_BYTES);
   const file = Bun.file(path);
 
   if (!(await file.exists())) {

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) => ({