@ultimat3/manifest 24.0.0 → 25.1.0

package/CLAUDE.md

@@ -44,7 +44,7 @@ by the CLI, not imported.
 - Top-level key order in the file is fixed by `KEY_ORDER` in `emit.ts` — `as const satisfies
   readonly (keyof Manifest)[]` AND walked by `emit.test.ts`, the treatment `ARRAY_SECTIONS` has,
   because the annotation catches a key that is not on `Manifest` and only the walk catches one that
-  is MISSING. `manifestJson` writes those keys and no others while `contentHash` hashes the whole
+  is MISSING. `manifestJson` writes those keys and no others while `fingerprint` hashes the whole
   body, so a 14th field would go into the hash and be dropped from the file — after which
   `assertNoDrift` convicts the committed manifest as HAND_EDITED, a correct refusal with the wrong
   diagnosis, about a file nobody touched.
@@ -162,7 +162,7 @@ by the CLI, not imported.
 - `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
-  the answer `toMcpTools` gives, or the gate demands a major bump for a tool that never existed.
+  the answer `@ultimat3/mcp`'s catalog gives, or the gate demands a major bump for a tool that never existed.
 
 ## Commands
 

package/package.json

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

package/src/build.ts

@@ -99,20 +99,12 @@ export function buildManifest(sources: ManifestSources): Manifest {
 
   // Before the hash: a fact the written file cannot hold must never get a buildId at all.
   assertFiniteFacts(body, '');
-  return { ...body, buildId: contentHash(body) };
-}
-
-/**
- * Content hash of the manifest body: `@ultimat3/core`'s `fingerprint`, SHA-256/16 over the same
- * INJECTIVE `canonicalJson` the diff compares on, so a fact that changed cannot hash the same as
- * the fact it replaced. It was a hand-written copy of that function, byte for byte — the value is
- * unchanged, the second implementation is gone. Deliberately excludes `buildId` itself.
- *
- * This is a HASH, never the published document: `manifestJson` in `emit.ts` is what reaches disk,
- * and it is `JSON.stringify` with a fixed key order for exactly that reason.
- */
-export function contentHash(body: Omit<Manifest, 'buildId'>): string {
-  return fingerprint(body);
+  // The build id is `@ultimat3/core`'s `fingerprint` of the body — SHA-256/16 over the same
+  // INJECTIVE `canonicalJson` the diff compares on, so a fact that changed cannot hash the same as
+  // the fact it replaced — and deliberately excludes `buildId` itself. A HASH, never the published
+  // document: `manifestJson` in `emit.ts` is what reaches disk, with a fixed key order. The
+  // `contentHash` alias this package exported for it left in 25.0.0 (plan 101, M3).
+  return { ...body, buildId: fingerprint(body) };
 }
 
 function sortBy<T>(items: readonly T[], key: (item: T) => string): readonly T[] {

package/src/diff-admin.ts

@@ -28,6 +28,35 @@ const flag = (
         },
       ];
 
+/**
+ * The admin-level gate, as `adminPermissionForAction` (`@ultimat3/admin`) decides it: `destructive`
+ * and `matching` hold the write gate, and only then does `readonly` lower it. Restated, not
+ * imported: the admin is a tier above this package. `destructive` reports its own change (and its
+ * own `admin:destroy` gate), so this only says read or write.
+ */
+const gateOf = (action: AdminActionFact): 'admin:read' | 'admin:write' =>
+  action.readonly && !action.destructive && !action.matching ? 'admin:read' : 'admin:write';
+
+/** `readonly` / `matching` flipping: a caller sees it only when the gate moves. */
+function diffGate(at: string, before: AdminActionFact, after: AdminActionFact): ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const [was, is] = [gateOf(before), gateOf(after)];
+  if (was !== is) {
+    // Write → read lets an `admin:read` caller in; read → write refuses one it served.
+    const kind = is === 'admin:write' ? 'breaking' : 'additive';
+    changes.push({ kind, path: `${at}.gate`, detail: `admin gate ${was} -> ${is}` });
+  }
+  for (const key of ['readonly', 'matching'] as const) {
+    // An absent flag reads as `false` (`schema.ts`): a baseline written before the field existed
+    // is not a change against a build that states `false`.
+    const [had, has] = [before[key] === true, after[key] === true];
+    if (had === has) continue;
+    const detail = `${key} ${String(had)} -> ${String(has)}`;
+    changes.push({ kind: 'internal', path: `${at}.${key}`, detail });
+  }
+  return changes;
+}
+
 function diffActions(
   path: string,
   before: readonly AdminActionFact[],
@@ -58,6 +87,7 @@ function diffActions(
       ...flag(`${at}.input`, action.input, now.input, true, 'input schema'),
       ...flag(`${at}.destructive`, action.destructive, now.destructive, true, 'destructive'),
     );
+    changes.push(...diffGate(at, action, now));
     if (action.threshold !== now.threshold) {
       changes.push({
         kind: 'internal',

package/src/docs-scan.ts

@@ -158,18 +158,21 @@ async function guideEntries(
   // id — silently, which is the failure mode the search's own coverage floor exists to prevent,
   // and a direct contradiction of `DocEntry.topic`'s promise to be unique within a package. No
   // shipped guide collides today; an app's own package is one heading away from it. The suffix
-  // follows document order, so the id is still derived and still reproducible.
-  const used = new Map<string, number>();
+  // follows document order, so the id is still derived and still reproducible. EVERY emitted id is
+  // recorded and a suffix climbs past a taken one: `## Retry`, `## Retry`, `## Retry 2` otherwise
+  // gave the second `Retry` and the real `Retry 2` the same `retry-2`.
+  const emitted = new Set<string>();
   for (const file of GUIDE_FILES) {
     const markdown = await read(join(dir, file));
     if (markdown === undefined) continue;
     const stem = basename(file, '.md');
     for (const section of parseGuideSections(markdown)) {
       const base = `${shortName(name)}.${stem}#${slug(section.heading)}`;
-      const seen = (used.get(base) ?? 0) + 1;
-      used.set(base, seen);
+      let topic = base;
+      for (let suffix = 2; emitted.has(topic); suffix += 1) topic = `${base}-${suffix}`;
+      emitted.add(topic);
       entries.push({
-        topic: seen === 1 ? base : `${base}-${seen}`,
+        topic,
         package: name,
         version,
         kind: 'guide',

package/src/emit.ts

@@ -4,8 +4,7 @@
 // so a refactor that reorders a struct literal does not produce a diff. Two-space indent and
 // a trailing newline: the file is reviewed by humans and diffed by git.
 
-import { canonicalJson } from '@ultimat3/core';
-import { contentHash } from './build';
+import { canonicalJson, fingerprint } from '@ultimat3/core';
 import { ManifestDriftError } from './errors';
 import type { Manifest } from './schema';
 import { isManifest } from './schema';
@@ -18,7 +17,7 @@ export const MANIFEST_FILENAME = 'x.manifest.json';
  * `as const satisfies` and a test that WALKS it, the treatment `ARRAY_SECTIONS` already has
  * (`schema.ts`) — the annotation catches a key that is not on `Manifest`, only a walk catches one
  * that is missing. It was a bare annotation, and `manifestJson` writes these keys and no others
- * while `contentHash` hashes the whole body: a 14th field added to `Manifest` would have gone into
+ * while `fingerprint` hashes the whole body: a 14th field added to `Manifest` would have gone into
  * the hash and been dropped from the file, after which `assertNoDrift` convicts the committed
  * manifest as HAND_EDITED — a correct refusal carrying the wrong diagnosis, about a file nobody
  * touched. Exported for that test alone; deliberately NOT re-exported by `src/index.ts`, because
@@ -150,7 +149,7 @@ function describeDrift(onDisk: Manifest, fresh: Manifest): readonly string[] {
 /** Verify a file's `buildId` against its own contents — catches a hand-edited manifest. */
 export function verifyBuildId(manifest: Manifest): boolean {
   const { buildId, ...body } = manifest;
-  return contentHash(body) === buildId;
+  return fingerprint(body) === buildId;
 }
 
 async function readIfExists(path: string): Promise<string | undefined> {

package/src/index.ts

@@ -10,7 +10,7 @@ export {
   checkAgentsMd,
 } from './agents-md';
 export type { ManifestSources } from './build';
-export { buildManifest, contentHash } from './build';
+export { buildManifest } from './build';
 export type { ChangeKind, ManifestChange, ManifestDiff } from './diff';
 export { diffManifest, formatDiff } from './diff';
 export type { DocEntry, DocEntryKind } from './docs-scan';

package/src/schema.ts

@@ -69,6 +69,13 @@ export interface AdminActionFact {
   readonly when: boolean;
   readonly batch: boolean;
   readonly threshold: number | null;
+  /**
+   * The two inputs of the admin-level gate besides `destructive`: `readonly` lowers it to
+   * `admin:read`, `matching` (a set-based write) holds it at `admin:write`. Absent from a file
+   * written before they were recorded, and read there as `false`.
+   */
+  readonly readonly: boolean;
+  readonly matching: boolean;
 }
 
 /** One resource of a generated admin: what its list answers, and whether a row scope narrows it. */

package/src/sources-admin.ts

@@ -75,6 +75,8 @@ const actionOf = (value: unknown): AdminActionFact | undefined => {
     when: bag['when'] === true,
     batch: bag['batch'] === true,
     threshold,
+    readonly: bag['readonly'] === true,
+    matching: bag['matching'] === true,
   };
 };
 

package/src/sources.ts

@@ -23,7 +23,7 @@ import { declaredAdmins } from './sources-admin';
 
 export interface FrameworkSourcesInput {
   readonly app: { readonly name: string; readonly version: string };
-  /** From `@ultimat3/render`'s `describeRoutes()`. */
+  /** From `@ultimat3/render`'s `describePages()`. */
   readonly routes?: readonly RouteFact[];
   /** Assembled per app from its policy modules. */
   readonly policies?: readonly PolicyFact[];

package/src/diff-fixtures.ts

@@ -1,96 +0,0 @@
-// TEST-ONLY. One fully-populated `ManifestSources` for the diff suites, so every section carries a
-// fact and every fact carries every field its type declares — a fixture with an empty `tasks` is
-// how a section nothing classifies stays green. Never exported from `index.ts`.
-
-import type { ManifestSources } from './build';
-import { buildManifest } from './build';
-import type { Manifest } from './schema';
-
-export const fixtureAction = (
-  name: string,
-  policy: string,
-  expose = true,
-  permissions = [policy],
-) => ({
-  name,
-  input: { id: 'uuid' },
-  output: { ok: 'boolean' },
-  policy,
-  permissions,
-  cacheInvalidates: ['post'],
-  mcp: { expose },
-});
-
-export const fixtureQuery = (name: string, policy: string, permissions = [policy]) => ({
-  name,
-  input: {},
-  policy,
-  permissions,
-  live: true,
-  subscribes: ['posts'],
-  cacheTags: ['post'],
-});
-
-/**
- * Built through a helper rather than written as `{ code: 'X_…' }`: `x verify`'s `errors` step
- * reads a `code:` key with an `X_*` literal as a DECLARATION, and this file is not a test file, so
- * the literal would have published a fixture's code into `framework.manifest.json` as one this
- * package owns.
- */
-export const fixtureErrorCode = (code: string, owner: string) => ({ code, package: owner });
-
-/** Every section non-empty, every optional field present. */
-export const FIXTURE: ManifestSources = {
-  app: { name: 'acme', version: '1.4.2' },
-  routes: [
-    {
-      url: '/posts',
-      render: 'isr',
-      offline: 'precache',
-      hydrate: 'idle',
-      revalidateTags: ['post'],
-      budget: { js: '40kb' },
-      surface: 'site',
-    },
-  ],
-  entities: [
-    {
-      name: 'post',
-      table: 'posts',
-      columns: [
-        { name: 'id', type: 'uuid', nullable: false, primaryKey: true },
-        { name: 'authorId', type: 'uuid', nullable: false, references: 'users.id' },
-        { name: 'note', type: 'text', nullable: true },
-      ],
-      invariants: ['post_title_present'],
-    },
-  ],
-  actions: [fixtureAction('publishPost', 'post:publish')],
-  queries: [fixtureQuery('feed', 'feed:read')],
-  jobs: [
-    {
-      name: 'sendMail',
-      input: { orgId: 'uuid' },
-      queue: 'critical',
-      retry: { attempts: 5, backoff: 'exponential' },
-      steps: ['a'],
-    },
-  ],
-  tasks: [
-    { name: 'nightlyDigest', cron: '0 3 * * *', tz: 'Europe/Berlin', enqueues: ['sendMail'] },
-  ],
-  policies: [
-    { permission: 'post:publish', description: 'publish a draft', enforcedIn: ['actions.publish'] },
-  ],
-  locales: ['en'],
-  // A code that is genuinely REGISTERED, not an invented one. `error-catalog.test.ts` scans every
-  // non-test file under `packages/*/src` for an `X_*` literal and treats an unregistered one as a
-  // code handed to a reader that no gate can see. A fixture is not shipped source in spirit, but
-  // it is in fact — and widening that scanner to excuse a filename is a worse trade than picking a
-  // real code here, since the diff classifier only ever compares the string.
-  errorCodes: [fixtureErrorCode('X_NOT_FOUND', 'app')],
-};
-
-/** The fixture, built. */
-export const fixtureManifest = (overrides: Partial<ManifestSources> = {}): Manifest =>
-  buildManifest({ ...FIXTURE, ...overrides });