@ultimat3/manifest 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -13,6 +13,7 @@ by the CLI, not imported.
 | `schema.ts` | the manifest's typed shape + `MANIFEST_VERSION` |
 | `build.ts` | `buildManifest` — pure, deterministic, stably sorted |
 | `sources.ts` | wires `describe*` from entity/action/query/jobs into `ManifestSources` |
+| `sources-admin.ts` | the declared admins, read off `Symbol.for('ultimate.admin.mounts')` through each one's own `describe()` — never an import of `@ultimat3/admin`. `unknown` in, field by field: a description this build does not understand is skipped whole |
 | `diff.ts` | `diffManifest` — the orchestrator: one classifier per section, nothing else |
 | `diff-change.ts` | the shared vocabulary: `ManifestChange`, `index`, `diffNamedSet`, `diffScalar` |
 | `diff-operations.ts` | actions, queries and the permissions they require |
@@ -20,6 +21,7 @@ by the CLI, not imported.
 | `diff-entities.ts` | tables, columns, keys, invariants |
 | `diff-work.ts` | jobs and tasks — the two things that fail by silently not happening |
 | `diff-routes.ts` | a URL's surface and its delivery facts |
+| `diff-admin.ts` | the `admin` section: a filter, sort, scope, resource or mounted route removed is breaking; a default scope moving or a row scope appearing is breaking; a route's permissions are judged like an operation's |
 | `diff-registries.ts` | policies and error codes |
 | `diff-fixtures.ts` | TEST-ONLY: one fully-populated `ManifestSources`. Never in `index.ts` |
 | `verify.ts` | `verifyContract` — the major-bump gate |

package/README.md

@@ -20,7 +20,8 @@ verifyContract({ before: committed, after: manifest });
 | `entities` | table, columns (type, nullability, PK, FK), named invariants |
 | `actions` | input + output schema, policy label, **required permissions**, cache invalidations, declared rate limit, MCP exposure, `mutator` when it is one |
 | `queries` | input schema, policy label, **required permissions**, live, cache tags |
-| `jobs` | input schema, queue, retry policy, step names |
+| `admin` | one entry per `defineAdmin()`: `basePath`; each resource's `filters`, `sorts`, `scopes` (`name`, `default`, `count`) and `rowScoped`; each mounted route's `url`, `view`, `entity` and `permissions`. `[]` for an app with no admin. Read off the process's own declarations — the one section the CLI does not inject |
+| `jobs` | input schema, queue, retry policy, step names, and — only when the job declares a cap — `concurrency: { limit, keyed, whenBusy }` |
 | `tasks` | cron, tz, jobs enqueued |
 | `policies` | permission, where enforced |
 | `permissions` | **derived** from policies + each operation's own list, never declared twice |
@@ -59,9 +60,9 @@ whole mechanism.
 
 | Class | Examples |
 |---|---|
-| **breaking** | action/query/route/job/**task**/entity/**policy**/**error code** removed; input or output schema changed; policy changed; **an operation gained a required permission**; **a policy gained an enforcement site**; **a rate limit was tightened or introduced**; MCP exposure withdrawn; column removed, retyped, or made NOT NULL; **a column's `primaryKey` or `references` changed in either direction**; **an entity's `table` renamed**; **an invariant added**; **a job's `queue` moved or its `retry.attempts` lowered**; **a route's `surface` changed**; live query became non-live |
-| **additive** | primitive added; nullable column added; **a column that lost NOT NULL**; a required permission dropped; an enforcement site dropped; **an invariant dropped**; a rate limit loosened or removed; **more retry attempts**; MCP exposure granted; locale added |
-| **internal** | cache tags changed (actions **and queries**); render mode changed; **a route's `offline`/`hydrate`/`budget`/`revalidateTags`**; **a task's `cron`/`tz`/`enqueues`**; **a job's `retry.backoff`**; job steps reordered; **an error code's owning package**; `buildId` |
+| **breaking** | action/query/route/job/**task**/entity/**policy**/**error code** removed; input or output schema changed; policy changed; **an operation gained a required permission**; **a policy gained an enforcement site**; **a rate limit was tightened or introduced**; MCP exposure withdrawn; column removed, retyped, or made NOT NULL; **a column sealed, unsealed, or moved from `lookup` to opaque** (sealing removes the field from every output; unsealing leaves stored values ciphertext); **a column's `primaryKey` or `references` changed in either direction**; **an entity's `table` renamed**; **an invariant added**; **a job's `queue` moved or its `retry.attempts` lowered**; **a route's `surface` changed**; live query became non-live; **an admin, an admin resource or an admin route removed; an admin list's filter, sort or scope removed; its default scope moved; a row scope introduced** |
+| **additive** | primitive added; nullable column added; **a column that lost NOT NULL**; **a sealed column moved from opaque to `lookup`** (reported: equal values now store equal strings); a required permission dropped; an enforcement site dropped; **an invariant dropped**; a rate limit loosened or removed; **more retry attempts**; MCP exposure granted; locale added; an admin, resource, route, filter, sort or scope added; a row scope removed |
+| **internal** | cache tags changed (actions **and queries**); render mode changed; **a route's `offline`/`hydrate`/`budget`/`revalidateTags`**; **a task's `cron`/`tz`/`enqueues`**; **a job's `retry.backoff`**; **a job's `concurrency`, declared, edited or removed**; job steps reordered; **an error code's owning package**; `buildId` |
 
 Every top-level section is classified, and that is checked rather than promised:
 `diff.test.ts` walks `ARRAY_SECTIONS` from `schema.ts` and fails on a section nothing reads. Two
@@ -70,7 +71,7 @@ every scheduled task reported `internal buildId: content changed` and passed the
 
 One classifier per section, each in its own file: `diff-operations.ts` (actions, queries,
 permissions), `diff-rate-limit.ts`, `diff-entities.ts`, `diff-work.ts` (jobs, tasks),
-`diff-routes.ts`, `diff-registries.ts` (policies, error codes), over the shared vocabulary in
+`diff-routes.ts`, `diff-admin.ts`, `diff-registries.ts` (policies, error codes), over the shared vocabulary in
 `diff-change.ts`. `diff.ts` is the orchestrator and nothing else.
 
 `verifyContract()` is the gate: a breaking change fails unless the app's **major** version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/manifest",
-  "version": "22.14.0",
+  "version": "23.0.0",
   "description": "x.manifest.json: deterministic generated facts, contract diff, AGENTS.md budget",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,11 +32,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.14.0",
-    "@ultimat3/core": "22.14.0",
-    "@ultimat3/entity": "22.14.0",
-    "@ultimat3/jobs": "22.14.0",
-    "@ultimat3/query": "22.14.0",
-    "@ultimat3/realtime": "22.14.0"
+    "@ultimat3/action": "23.0.0",
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/entity": "23.0.0",
+    "@ultimat3/jobs": "23.0.0",
+    "@ultimat3/query": "23.0.0",
+    "@ultimat3/realtime": "23.0.0"
   }
 }

package/src/build.ts

@@ -19,6 +19,7 @@
 import { canonicalJson } from '@ultimat3/core';
 import type {
   ActionFact,
+  AdminFact,
   ChannelFact,
   EntityFact,
   ErrorCodeFact,
@@ -38,6 +39,7 @@ export interface ManifestSources {
   readonly actions?: readonly ActionFact[];
   readonly queries?: readonly QueryFact[];
   readonly channels?: readonly ChannelFact[];
+  readonly admin?: readonly AdminFact[];
   readonly jobs?: readonly JobFact[];
   readonly tasks?: readonly TaskFact[];
   readonly policies?: readonly PolicyFact[];
@@ -51,6 +53,7 @@ export function buildManifest(sources: ManifestSources): Manifest {
   const actions = sortBy(sources.actions ?? [], (a) => a.name).map(normalizeAction);
   const queries = sortBy(sources.queries ?? [], (q) => q.name).map(normalizeQuery);
   const channels = sortBy(sources.channels ?? [], (c) => c.name).map(normalizeChannel);
+  const admin = sortBy(sources.admin ?? [], (a) => a.basePath).map(normalizeAdmin);
   const jobs = sortBy(sources.jobs ?? [], (j) => j.name).map(normalizeJob);
   const tasks = sortBy(sources.tasks ?? [], (t) => t.name).map((t) => ({
     ...t,
@@ -84,6 +87,7 @@ export function buildManifest(sources: ManifestSources): Manifest {
     actions,
     queries,
     channels,
+    admin,
     jobs,
     tasks,
     policies,
@@ -134,6 +138,15 @@ const normalizeRoute = (route: RouteFact): RouteFact =>
       // different answer from an absent key, and `emit.ts` writes what it is given.
       { ...route, revalidateTags: [...route.revalidateTags].sort() };
 
+// Resources and routes are sets, keyed by entity and by URL. What is INSIDE them is not: filters
+// and scopes are drawn in declaration order, and a route's permissions are a pair with the coarse
+// gate first — sorting either would publish an order the admin does not have.
+const normalizeAdmin = (admin: AdminFact): AdminFact => ({
+  ...admin,
+  resources: sortBy(admin.resources, (r) => r.entity),
+  routes: sortBy(admin.routes, (r) => r.url),
+});
+
 const normalizeEntity = (entity: EntityFact): EntityFact => ({
   ...entity,
   columns: sortBy(entity.columns, (c) => c.name),

package/src/diff-admin.ts

@@ -0,0 +1,199 @@
+// The admin in a contract diff. An admin's list URLs are bookmarked and its MCP tools are called
+// by agents, so what a list ANSWERS is contract: a filter, a sort or a scope that goes away
+// refuses a caller it served, a default scope that moves changes what a bare URL lists, and a row
+// scope that appears hides rows from actors who saw them. An action is an MCP tool: one that goes
+// away, stops taking `ids`, or starts excluding rows (`when`) refuses a call it answered. A
+// route's permissions are judged like any operation's; layout and related lists are internal.
+
+import type { ManifestChange } from './diff-change';
+import { diffNamedSet, index } from './diff-change';
+import { diffPermissions } from './diff-operations';
+import type { AdminActionFact, AdminFact, AdminResourceFact } from './schema';
+
+/** A change of one boolean fact, breaking in one direction and additive in the other. */
+const flag = (
+  path: string,
+  before: boolean,
+  after: boolean,
+  breaksWhen: boolean,
+  detail: string,
+): readonly ManifestChange[] =>
+  before === after
+    ? []
+    : [
+        {
+          kind: after === breaksWhen ? 'breaking' : 'additive',
+          path,
+          detail: `${detail} ${String(before)} -> ${String(after)}`,
+        },
+      ];
+
+function diffActions(
+  path: string,
+  before: readonly AdminActionFact[],
+  after: readonly AdminActionFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [
+    ...diffNamedSet(
+      path,
+      before.map((action) => action.name),
+      after.map((action) => action.name),
+    ),
+  ];
+  const next = index(after, (action) => action.name);
+  for (const action of before) {
+    const now = next.get(action.name);
+    if (now === undefined) continue;
+    const at = `${path}.${action.name}`;
+    changes.push(
+      ...diffPermissions(
+        at,
+        { permissions: [action.permission] },
+        { permissions: [now.permission] },
+      ),
+      // `when` appearing refuses rows the tool ran on; the batch path going away refuses `ids`;
+      // a schema appearing refuses a call that sent nothing; destructive starts asking for a token.
+      ...flag(`${at}.when`, action.when, now.when, true, 'when'),
+      ...flag(`${at}.batch`, action.batch, now.batch, false, 'batch'),
+      ...flag(`${at}.input`, action.input, now.input, true, 'input schema'),
+      ...flag(`${at}.destructive`, action.destructive, now.destructive, true, 'destructive'),
+    );
+    if (action.threshold !== now.threshold) {
+      changes.push({
+        kind: 'internal',
+        path: `${at}.threshold`,
+        detail: `threshold ${String(action.threshold)} -> ${String(now.threshold)}`,
+      });
+    }
+  }
+  return changes;
+}
+
+const layout = (sections: AdminResourceFact['sections']): string =>
+  JSON.stringify(sections.map((section) => [section.title, section.fields]));
+
+function diffResource(
+  path: string,
+  before: AdminResourceFact,
+  after: AdminResourceFact,
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [
+    ...diffNamedSet(`${path}.filters`, before.filters, after.filters),
+    ...diffNamedSet(`${path}.sorts`, before.sorts, after.sorts),
+    ...diffNamedSet(
+      `${path}.scopes`,
+      before.scopes.map((scope) => scope.name),
+      after.scopes.map((scope) => scope.name),
+    ),
+  ];
+  const next = index(after.scopes, (scope) => scope.name);
+  for (const scope of before.scopes) {
+    const now = next.get(scope.name);
+    if (now === undefined) continue;
+    if (scope.default !== now.default) {
+      changes.push({
+        kind: 'breaking',
+        path: `${path}.scopes.${scope.name}.default`,
+        detail: `default ${String(scope.default)} -> ${String(now.default)}; a bare list URL reads other rows`,
+      });
+    }
+    if (scope.count !== now.count) {
+      changes.push({
+        kind: 'internal',
+        path: `${path}.scopes.${scope.name}.count`,
+        detail: `count ${String(scope.count)} -> ${String(now.count)}`,
+      });
+    }
+  }
+  changes.push(...diffActions(`${path}.actions`, before.actions, after.actions));
+  // A related card is the related resource's own list, reachable on its own: neither direction
+  // refuses a caller.
+  changes.push(...diffNamedSet(`${path}.related`, before.related, after.related, 'internal'));
+  for (const key of ['sections', 'formGroups'] as const) {
+    if (layout(before[key]) !== layout(after[key])) {
+      changes.push({ kind: 'internal', path: `${path}.${key}`, detail: `${key} rearranged` });
+    }
+  }
+  if (before.rowScoped !== after.rowScoped) {
+    changes.push({
+      // Appearing narrows what every actor sees; going away widens it — which breaks nobody, and
+      // is still a change a reviewer has to see.
+      kind: after.rowScoped ? 'breaking' : 'additive',
+      path: `${path}.rowScoped`,
+      detail: after.rowScoped ? 'rows are now scoped per actor' : 'rows are no longer scoped',
+    });
+  }
+  return changes;
+}
+
+function diffAdmin(before: AdminFact, after: AdminFact): readonly ManifestChange[] {
+  const root = `admin.${before.basePath}`;
+  const changes: ManifestChange[] = [];
+  if (before.audit !== after.audit) {
+    changes.push({
+      kind: 'internal',
+      path: `${root}.audit`,
+      detail: `audit log ${before.audit} -> ${after.audit}`,
+    });
+  }
+
+  const resources = index(after.resources, (resource) => resource.entity);
+  for (const resource of before.resources) {
+    const path = `${root}.resources.${resource.entity}`;
+    const next = resources.get(resource.entity);
+    if (next === undefined) changes.push({ kind: 'breaking', path, detail: 'resource removed' });
+    else changes.push(...diffResource(path, resource, next));
+  }
+  const had = index(before.resources, (resource) => resource.entity);
+  for (const resource of after.resources) {
+    if (!had.has(resource.entity)) {
+      changes.push({
+        kind: 'additive',
+        path: `${root}.resources.${resource.entity}`,
+        detail: 'resource added',
+      });
+    }
+  }
+
+  const routes = index(after.routes, (route) => route.url);
+  for (const route of before.routes) {
+    const path = `${root}.routes.${route.url}`;
+    const next = routes.get(route.url);
+    if (next === undefined) changes.push({ kind: 'breaking', path, detail: 'route removed' });
+    else changes.push(...diffPermissions(path, route, next));
+  }
+  const served = index(before.routes, (route) => route.url);
+  for (const route of after.routes) {
+    if (!served.has(route.url)) {
+      changes.push({
+        kind: 'additive',
+        path: `${root}.routes.${route.url}`,
+        detail: 'route added',
+      });
+    }
+  }
+  return changes;
+}
+
+export function diffAdmins(
+  before: readonly AdminFact[],
+  after: readonly AdminFact[],
+): readonly ManifestChange[] {
+  const changes: ManifestChange[] = [];
+  const next = index(after, (admin) => admin.basePath);
+  const had = index(before, (admin) => admin.basePath);
+  for (const admin of before) {
+    const now = next.get(admin.basePath);
+    if (now === undefined) {
+      changes.push({ kind: 'breaking', path: `admin.${admin.basePath}`, detail: 'admin removed' });
+    } else {
+      changes.push(...diffAdmin(admin, now));
+    }
+  }
+  for (const admin of after) {
+    if (!had.has(admin.basePath)) {
+      changes.push({ kind: 'additive', path: `admin.${admin.basePath}`, detail: 'admin added' });
+    }
+  }
+  return changes;
+}

package/src/diff-entities.ts

@@ -110,6 +110,7 @@ function diffColumns(
     }
     changes.push(...diffKey(at, 'primaryKey', keyOf(column), keyOf(next)));
     changes.push(...diffKey(at, 'references', column.references, next.references));
+    changes.push(...diffSealed(`${at}.sealed`, column.sealed, next.sealed));
   }
 
   const beforeColumns = index(before.columns, (c) => c.name);
@@ -132,6 +133,63 @@ function diffColumns(
   return changes;
 }
 
+/**
+ * How a column is sealed is a WIRE fact as much as a storage one: `.sealed()` emits no DDL and
+ * leaves the column's type alone, so nothing else in the file moves — while the field leaves every
+ * action output, query row, record and live frame the app sends. Absence is a statement here, not
+ * missing evidence: the field is written only for a sealed column, and a manifest older than the
+ * feature had none.
+ *
+ * Three of the four moves break a consumer. Sealing removes a field every client read. Unsealing
+ * puts it back AND leaves every stored value a ciphertext no read opens any more. `lookup` to
+ * opaque refuses the equality filters and the unique rule that were legal. Opaque to `lookup` is
+ * the one that only widens — reported all the same, because equal values now store equal strings,
+ * and rows written before are found only once they are re-sealed.
+ */
+function diffSealed(
+  path: string,
+  before: ColumnFact['sealed'],
+  after: ColumnFact['sealed'],
+): readonly ManifestChange[] {
+  if (before === after) return [];
+  if (before === undefined) {
+    return [
+      {
+        kind: 'breaking',
+        path,
+        detail: `became sealed (${after}); the field is removed from every output`,
+      },
+    ];
+  }
+  if (after === undefined) {
+    return [
+      {
+        kind: 'breaking',
+        path,
+        detail:
+          'no longer sealed; stored values stay ciphertext until rewritten, and the field joins every output',
+      },
+    ];
+  }
+  return after === 'lookup'
+    ? [
+        {
+          kind: 'additive',
+          path,
+          detail:
+            'sealed opaque -> lookup; equal values now store equal strings, and existing rows match only after a re-seal',
+        },
+      ]
+    : [
+        {
+          kind: 'breaking',
+          path,
+          detail:
+            'sealed lookup -> opaque; an equality filter or a unique rule on it is now refused',
+        },
+      ];
+}
+
 /** `primaryKey` is optional in the file, so absence is the same statement as `false`. */
 const keyOf = (column: ColumnFact): string => (column.primaryKey === true ? 'yes' : 'no');
 

package/src/diff-work.ts

@@ -42,6 +42,22 @@ export function diffJobs(
       ),
     );
     changes.push(...diffRetry(path, job, next));
+    // A cap decides how much runs at once and what a claim over it does; neither is the shape an
+    // enqueuer or a queued payload depends on. Declared, removed and edited alike.
+    if (canonicalJson(job.concurrency ?? null) !== canonicalJson(next.concurrency ?? null)) {
+      changes.push({
+        kind: 'internal',
+        path: `${path}.concurrency`,
+        detail: 'concurrency changed; runs already in flight keep the slots they hold',
+      });
+    }
+    if ((job.onSettled ?? false) !== (next.onSettled ?? false)) {
+      changes.push({
+        kind: 'internal',
+        path: `${path}.onSettled`,
+        detail: next.onSettled === true ? 'onSettled hook declared' : 'onSettled hook removed',
+      });
+    }
     if (canonicalJson(job.steps) !== canonicalJson(next.steps)) {
       changes.push({
         kind: 'internal',

package/src/diff.ts

@@ -11,6 +11,7 @@
 // `[{ kind: 'internal', path: 'buildId' }]` and passed. `diff.test.ts` walks `ARRAY_SECTIONS` and
 // fails on a section nothing here classifies.
 
+import { diffAdmins } from './diff-admin';
 import type { ManifestChange } from './diff-change';
 import { diffNamedSet } from './diff-change';
 import { diffChannels } from './diff-channels';
@@ -49,6 +50,8 @@ export function diffManifest(before: Manifest, after: Manifest): ManifestDiff {
   changes.push(...diffQueries(before.queries, after.queries));
   // `?? []`: a file written before channels were projected carries none, which is not a removal.
   changes.push(...diffChannels(before.channels ?? [], after.channels ?? []));
+  // The same `?? []`, for the same reason: no `admin` key is a file older than the section.
+  changes.push(...diffAdmins(before.admin ?? [], after.admin ?? []));
   changes.push(...diffRoutes(before.routes, after.routes));
   changes.push(...diffJobs(before.jobs, after.jobs));
   changes.push(...diffTasks(before.tasks, after.tasks));

package/src/emit.ts

@@ -33,6 +33,7 @@ export const KEY_ORDER = [
   'actions',
   'queries',
   'channels',
+  'admin',
   'jobs',
   'tasks',
   'policies',

package/src/index.ts

@@ -42,6 +42,10 @@ export {
 } from './errors';
 export type {
   ActionFact,
+  AdminFact,
+  AdminResourceFact,
+  AdminRouteFact,
+  AdminScopeFact,
   ChannelFact,
   ColumnFact,
   EntityFact,

package/src/schema.ts

@@ -41,6 +41,77 @@ export interface RouteFact {
   readonly surface?: 'site' | 'app' | 'api';
 }
 
+/** One scope of an admin list: a tab, by name. */
+export interface AdminScopeFact {
+  readonly name: string;
+  /** What a bare list URL reads. At most one per resource. */
+  readonly default: boolean;
+  /** The tab shows a row count — one extra query per list page. */
+  readonly count: boolean;
+}
+
+/** One titled group of an admin detail page or form. `title` is an i18n key; `null` untitled. */
+export interface AdminSectionFact {
+  readonly title: string | null;
+  readonly fields: readonly string[];
+}
+
+/**
+ * One admin action: its button, its batch bar entry and its ONE MCP tool. `when` narrows which rows
+ * it applies to; `batch` puts it in the bar and gives the tool `ids`; past `threshold` rows a batch
+ * is queued as `admin.batch` jobs instead of run in the request.
+ */
+export interface AdminActionFact {
+  readonly name: string;
+  readonly permission: string;
+  readonly destructive: boolean;
+  readonly input: boolean;
+  readonly when: boolean;
+  readonly batch: boolean;
+  readonly threshold: number | null;
+}
+
+/** One resource of a generated admin: what its list answers, and whether a row scope narrows it. */
+export interface AdminResourceFact {
+  readonly entity: string;
+  /** Mount-relative: `/posts`. */
+  readonly path: string;
+  /** The fields a list URL's `f.<field>` and the MCP list tool's `where` may name, in bar order. */
+  readonly filters: readonly string[];
+  /** The fields `?sort=` may name. */
+  readonly sorts: readonly string[];
+  /** Tab order. */
+  readonly scopes: readonly AdminScopeFact[];
+  /** `rows` is declared: every read of the resource is narrowed per actor. */
+  readonly rowScoped: boolean;
+  /** The detail page's groups, drawing order; undeclared fields are the last, default one. */
+  readonly sections: readonly AdminSectionFact[];
+  /** The create and edit form's groups, the same way. */
+  readonly formGroups: readonly AdminSectionFact[];
+  /** `hasMany` relations drawn on the detail page as the related resource's own list. */
+  readonly related: readonly string[];
+  /** Declaration order — the order the buttons are drawn in. */
+  readonly actions: readonly AdminActionFact[];
+}
+
+/** One route `defineAdmin()` mounts — no page file declares it. */
+export interface AdminRouteFact {
+  readonly url: string;
+  readonly view: string;
+  readonly entity: string | null;
+  /** Every permission the screen decides on, coarse gate first. A pair, not a set. */
+  readonly permissions: readonly string[];
+}
+
+/** One generated admin, as `defineAdmin()` derived it. */
+export interface AdminFact {
+  readonly basePath: string;
+  /** The audit log the admin writes: `memory` forgets at every restart; `postgres` is the record. */
+  readonly audit: string;
+  readonly resources: readonly AdminResourceFact[];
+  readonly routes: readonly AdminRouteFact[];
+}
+
 export interface ColumnFact {
   readonly name: string;
   readonly type: string;
@@ -53,6 +124,13 @@ export interface ColumnFact {
    * is additive — every existing row takes the default — and was classed breaking without this.
    */
   readonly hasDefault?: boolean;
+  /**
+   * The column is `.sealed()`: stored as ciphertext, absent from every output. `'lookup'` is the
+   * deterministic form, matchable by equality. Written only when sealed, so a column that is not
+   * reads as it always did — and an agent reading the manifest can tell a field it will never be
+   * sent from one that is merely missing.
+   */
+  readonly sealed?: 'opaque' | 'lookup';
 }
 
 export interface EntityFact {
@@ -140,6 +218,19 @@ export interface JobFact {
   readonly queue: string;
   readonly retry: { readonly attempts: number; readonly backoff: string };
   readonly steps: readonly string[];
+  /**
+   * The job's fleet-wide cap, present only when it declares one. `keyed: true` says `limit` holds
+   * per `concurrency.key(input)` — "one run per account" — rather than for the whole job, and
+   * `whenBusy` is what a claim over it does (`null` for a plain number, which always waits).
+   * Optional for `channels`' reason: a manifest written before this existed is "no cap known".
+   */
+  readonly concurrency?: {
+    readonly limit: number;
+    readonly keyed: boolean;
+    readonly whenBusy: string | null;
+  };
+  /** Present, and `true`, only when the job declares an `onSettled` hook. */
+  readonly onSettled?: true;
 }
 
 export interface TaskFact {
@@ -185,6 +276,12 @@ export interface Manifest {
    * is "no channels", never an unreadable manifest. `buildManifest` always writes it.
    */
   readonly channels?: readonly ChannelFact[];
+  /**
+   * The generated admins the app declares, each with its resources and mounted routes. Optional to
+   * a READER only, exactly as `channels` is: a file written before admins were projected has none.
+   * `buildManifest` always writes it — `[]` for an app with no admin.
+   */
+  readonly admin?: readonly AdminFact[];
   readonly jobs: readonly JobFact[];
   readonly tasks: readonly TaskFact[];
   readonly policies: readonly PolicyFact[];
@@ -243,6 +340,7 @@ export function isManifest(value: unknown): value is Manifest {
   for (const section of ARRAY_SECTIONS) if (!Array.isArray(m[section])) return false;
   // Absent is a pre-channel file and readable; present and not an array is a damaged one.
   if (m['channels'] !== undefined && !Array.isArray(m['channels'])) return false;
+  if (m['admin'] !== undefined && !Array.isArray(m['admin'])) return false;
   return isAppIdentity(m['app']);
 }
 

package/src/sources-admin.ts

@@ -0,0 +1,158 @@
+// The admins this process declared, as manifest facts. `@ultimat3/admin` is a tier above this
+// package and may not be imported, so its mount registry is read off the global symbol registry —
+// the same seam `@ultimat3/cli` mounts the screens through — and each admin is asked to describe
+// ITSELF. What comes back is `unknown` and is read field by field: a description this build does
+// not understand is skipped whole, never half-published.
+
+import type {
+  AdminActionFact,
+  AdminFact,
+  AdminResourceFact,
+  AdminRouteFact,
+  AdminScopeFact,
+  AdminSectionFact,
+} from './schema';
+
+/** `@ultimat3/admin`'s `ADMIN_MOUNTS`. Restated — the package cannot be imported from here. */
+export const ADMIN_MOUNTS_KEY: symbol = Symbol.for('ultimate.admin.mounts');
+
+type Bag = Readonly<Record<string, unknown>>;
+
+const bagOf = (value: unknown): Bag | undefined =>
+  typeof value === 'object' && value !== null ? (value as Bag) : undefined;
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' ? value : undefined;
+
+const texts = (value: unknown): readonly string[] | undefined =>
+  Array.isArray(value) && value.every((one) => typeof one === 'string')
+    ? (value as readonly string[])
+    : undefined;
+
+/** Every element read, or the whole list refused: a half-read list is a manifest that lies. */
+const each = <T>(
+  value: unknown,
+  read: (one: unknown) => T | undefined,
+): readonly T[] | undefined => {
+  if (!Array.isArray(value)) return undefined;
+  const out: T[] = [];
+  for (const one of value) {
+    const fact = read(one);
+    if (fact === undefined) return undefined;
+    out.push(fact);
+  }
+  return out;
+};
+
+const scopeOf = (value: unknown): AdminScopeFact | undefined => {
+  const bag = bagOf(value);
+  const name = text(bag?.['name']);
+  if (bag === undefined || name === undefined) return undefined;
+  return { name, default: bag['default'] === true, count: bag['count'] === true };
+};
+
+const sectionOf = (value: unknown): AdminSectionFact | undefined => {
+  const bag = bagOf(value);
+  const fields = texts(bag?.['fields']);
+  const title = bag?.['title'];
+  if (bag === undefined || fields === undefined) return undefined;
+  if (title !== null && typeof title !== 'string') return undefined;
+  return { title, fields };
+};
+
+const actionOf = (value: unknown): AdminActionFact | undefined => {
+  const bag = bagOf(value);
+  const name = text(bag?.['name']);
+  const permission = text(bag?.['permission']);
+  const threshold = bag?.['threshold'];
+  if (bag === undefined || name === undefined || permission === undefined) return undefined;
+  if (threshold !== null && typeof threshold !== 'number') return undefined;
+  return {
+    name,
+    permission,
+    destructive: bag['destructive'] === true,
+    input: bag['input'] === true,
+    when: bag['when'] === true,
+    batch: bag['batch'] === true,
+    threshold,
+  };
+};
+
+const resourceOf = (value: unknown): AdminResourceFact | undefined => {
+  const bag = bagOf(value);
+  const entity = text(bag?.['entity']);
+  const path = text(bag?.['path']);
+  const filters = texts(bag?.['filters']);
+  const sorts = texts(bag?.['sorts']);
+  const scopes = each(bag?.['scopes'], scopeOf);
+  const sections = each(bag?.['sections'], sectionOf);
+  const formGroups = each(bag?.['formGroups'], sectionOf);
+  const related = texts(bag?.['related']);
+  const actions = each(bag?.['actions'], actionOf);
+  if (
+    bag === undefined ||
+    entity === undefined ||
+    path === undefined ||
+    filters === undefined ||
+    sorts === undefined ||
+    scopes === undefined ||
+    sections === undefined ||
+    formGroups === undefined ||
+    related === undefined ||
+    actions === undefined
+  ) {
+    return undefined;
+  }
+  return {
+    entity,
+    path,
+    filters,
+    sorts,
+    scopes,
+    rowScoped: bag['rowScoped'] === true,
+    sections,
+    formGroups,
+    related,
+    actions,
+  };
+};
+
+const routeOf = (value: unknown): AdminRouteFact | undefined => {
+  const bag = bagOf(value);
+  const url = text(bag?.['url']);
+  const view = text(bag?.['view']);
+  const permissions = texts(bag?.['permissions']);
+  if (bag === undefined || url === undefined || view === undefined || permissions === undefined) {
+    return undefined;
+  }
+  return { url, view, entity: text(bag['entity']) ?? null, permissions };
+};
+
+const adminOf = (mount: unknown): AdminFact | undefined => {
+  const describe = bagOf(mount)?.['describe'];
+  if (typeof describe !== 'function') return undefined;
+  const described = bagOf((describe as () => unknown).call(mount));
+  const basePath = text(described?.['basePath']);
+  const audit = text(described?.['audit']);
+  const resources = each(described?.['resources'], resourceOf);
+  const routes = each(described?.['routes'], routeOf);
+  if (
+    basePath === undefined ||
+    audit === undefined ||
+    resources === undefined ||
+    routes === undefined
+  ) {
+    return undefined;
+  }
+  return { basePath, audit, resources, routes };
+};
+
+/** Every admin `defineAdmin()` declared in this process. Empty for an app that declares none. */
+export function declaredAdmins(): readonly AdminFact[] {
+  const held = (globalThis as { [key: symbol]: unknown })[ADMIN_MOUNTS_KEY];
+  if (!(held instanceof Map)) return [];
+  return [...held.values()].flatMap((mount) => {
+    const fact = adminOf(mount);
+    return fact === undefined ? [] : [fact];
+  });
+}

package/src/sources.ts

@@ -6,12 +6,20 @@
 // in `@ultimat3/render`, which is this same tier.
 
 import { describeActions } from '@ultimat3/action';
-import { describeEntities } from '@ultimat3/entity';
+import { describeEntities, registeredEntities, sealedFields } from '@ultimat3/entity';
 import { describeJobs } from '@ultimat3/jobs';
 import { describeQueries } from '@ultimat3/query';
 import { describeChannels } from '@ultimat3/realtime/server';
 import type { ManifestSources } from './build';
-import type { ErrorCodeFact, JsonValue, PolicyFact, RouteFact, TaskFact } from './schema';
+import type {
+  AdminFact,
+  ErrorCodeFact,
+  JsonValue,
+  PolicyFact,
+  RouteFact,
+  TaskFact,
+} from './schema';
+import { declaredAdmins } from './sources-admin';
 
 export interface FrameworkSourcesInput {
   readonly app: { readonly name: string; readonly version: string };
@@ -23,6 +31,11 @@ export interface FrameworkSourcesInput {
   readonly locales?: readonly string[];
   /** Each package's `*_ERROR_CODES`, flattened by the CLI. */
   readonly errorCodes?: readonly ErrorCodeFact[];
+  /**
+   * The app's generated admins. Omitted, they are read off the process's own declarations
+   * (`sources-admin.ts`) — the one section a caller does not have to inject.
+   */
+  readonly admin?: readonly AdminFact[];
 }
 
 /**
@@ -36,7 +49,33 @@ export interface FrameworkSourcesInput {
  */
 const asJson = (value: object): JsonValue => value as JsonValue;
 
+/** Absent stays absent: only a sealed column carries the field. */
+const sealedFact = (
+  how: 'opaque' | 'lookup' | undefined,
+): { readonly sealed?: 'opaque' | 'lookup' } => (how === undefined ? {} : { sealed: how });
+
+/**
+ * `<entity name>` -> `<physical column>` -> how it is sealed. Read off the declarations rather than
+ * `$describe()`, which is the DDL's projection: sealing changes no DDL, so it is not on it, and a
+ * column becoming sealed must not move the schema hash a migration is checked against.
+ */
+function sealedColumns(): ReadonlyMap<string, ReadonlyMap<string, 'opaque' | 'lookup'>> {
+  return new Map(
+    registeredEntities().map((entry) => [
+      entry.name,
+      new Map(
+        // `core` is absent on a hand-registered entry, which declares no columns to seal.
+        (entry.core === undefined ? [] : sealedFields(entry.core)).map((field) => [
+          field.column,
+          field.lookup ? ('lookup' as const) : ('opaque' as const),
+        ]),
+      ),
+    ]),
+  );
+}
+
 export function frameworkSources(input: FrameworkSourcesInput): ManifestSources {
+  const sealed = sealedColumns();
   return {
     app: input.app,
     routes: input.routes ?? [],
@@ -44,6 +83,7 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
     tasks: input.tasks ?? [],
     locales: input.locales ?? [],
     errorCodes: input.errorCodes ?? [],
+    admin: input.admin ?? declaredAdmins(),
     // Projected field by field, never cast: the primitive registries own richer shapes
     // than the manifest publishes, and a cast would silently rot when either side moves.
     entities: describeEntities().map((entity) => ({
@@ -56,6 +96,7 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
         primaryKey: column.primaryKey,
         ...(column.hasDefault ? { hasDefault: true } : {}),
         ...(column.references === null ? {} : { references: column.references }),
+        ...sealedFact(sealed.get(entity.name)?.get(column.column)),
       })),
       invariants: entity.invariants.map((invariant) => invariant.name),
     })),
@@ -108,6 +149,19 @@ export function frameworkSources(input: FrameworkSourcesInput): ManifestSources
       // `run()` at execution time, so no static reader can know it. `x jobs show` reports the
       // steps an actual run recorded.
       steps: job.steps,
+      // Absent, never `null`, for a job with no cap: a row gains the key the day its job declares
+      // one, so adding this fact moved no committed manifest but the ones it is a fact about.
+      ...(job.concurrency === null
+        ? {}
+        : {
+            concurrency: {
+              limit: job.concurrency.limit,
+              keyed: job.concurrency.keyed,
+              whenBusy: job.concurrency.whenBusy,
+            },
+          }),
+      // The same rule: only a job that declares the hook carries the key.
+      ...(job.onSettled ? { onSettled: true as const } : {}),
     })),
   };
 }