@ultimat3/admin 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -7,9 +7,14 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 ## Rules
 
 - **One authz.** `AdminAuthz` (`authz.ts`) is the only decision path. `action-gate.ts`, `crud.ts` and `page-guard.tsx` call `decideAll`; views render what the gate returned. Never add a second check in a view or an MCP handler.
+- **The subject carries the tenant and the loaded row.** `AdminActor.orgId` reaches `policyActor` and `AdminSubject.row` reaches `evaluate`, so an org-scoped or ownership rule can fire at all. It could not: every admin decision was evaluated with `actor.orgId === undefined` and `row === null`, so a role-only rule allowed and the coarse `admin:read` + `<entity>:read` pair was the only gate on a row — while `adminList`/`adminSearch` add no tenant predicate of their own. `adminDetail`, `adminUpdate` and `adminDestroy` load the row BEFORE the guard, the shape `packages/action/src/invoke.ts` uses; `undefined` means "not loaded" and is left off the subject, `null` means "looked and found none" and fails a row rule closed. Pinned in `policy-subject.test.ts`, which asserts the SUBJECT a policy receives — `staticAuthz` is a grant-list stub and no suite driving it can see any of this.
+- **The MCP caller is the ambient actor for the whole call.** `mcp.ts` wraps `callAdminTool` in a child context (or a fresh root one over stdio, where there is no surrounding request), the same rule `@ultimat3/mcp`'s `app-tool.ts` states. `AdminApp.ctx()` builds a plain `CrudCtx` and touches nothing async-local, so everything deriving from `tryUseContext()` — entity's tenant guard, the query cache authority, the jit-preload store — read the TRANSPORT's actor: an agent token authorized as agent X while the repo reads ran as the cookie user's tenant, and over stdio `actorTenant` was `undefined` and `assertRowTenant` a no-op. Pinned in `mcp-context.test.ts`.
 - **A custom page's guard is composed, never written.** `pages.ts` turns a `pages:` entry into an `AdminRoute` carrying `[admin:read, …declared]`; `routes.ts` is the only thing that may hand a page component to a router and it hands the `guardedPage()` wrapper, with `permissions[0]` already in `defineRoute({ policy })`. `AdminPageProps.ctx` is required by the type so the wrapper cannot be bypassed by calling the component directly. An empty permission list is `X_ADMIN_PAGE_UNGUARDED` at `defineAdmin` time — the one place an unauthenticated admin screen could have been born.
+- **One `AdminAction.name`, one handler.** The name is the MCP tool name (`admin.action.<name>`), the default label key, AND the key `callAdminTool` resolves a handler by — three addresses, one string. Two actions sharing it is `X_ADMIN_ACTION_DUPLICATE` at `defineAdmin` time (`admin.ts`, `mcp.test.ts`), not at the first agent call: `.find()` on a name dispatches to whichever resource came first, which is a call that SUCCEEDS against the wrong action and reports nothing. Refused at declaration rather than in `adminMcp()` because an app that renders the dashboard and never wires MCP has the same two broken label keys and the same ambiguous dispatch. The framework's own examples already qualify the name with the entity (`post.publish`) — the `fix:` line is that convention, made into the instruction. The same object attached through both `actions:` and `resources[e].actions` is one action, not two: identity, not name, is what "already seen" means.
 - **A host that serves an admin URL itself reads its gate, never restates it.** `adminRouteFor(app, path)` (`routes.ts`) is that read, and `AdminRouteConfig.policy` is what it hands over — the same object `config.policy` carries, non-optional so a caller need not prove it exists. Typing `policy: { permission: 'admin:read' }` into a page file beside a route table that already declares one for that URL is two declarations of one URL's authz; they agree until somebody edits one. The deployed demo shipped exactly that on five pages until 1.2.0, and its `apps/admin/app/admin/route-policy.test.ts` is the rule made executable: a quoted permission anywhere under `app/admin/**/page.tsx` fails the suite. An undeclared path is `X_ADMIN_PAGE_PATH_INVALID`, listing the paths that would have worked.
-- **One bridge per foreign package.** `policy-bridge.ts` is the only file calling `evaluate`/`definePermissions`; `routes.ts` the only one calling `defineRoute`; `mcp.ts` the only one calling `defineAppMcp`; `dev/data.ts` the only one importing introspection (dynamically — `/_x` must stay out of the production graph).
+- **A `/_x` source reads a registry through its DESCRIPTOR TYPE, never as an untyped bag.** `import type { RouteDescriptor }` beside the dynamic `import()` — the type is erased, so /_x still costs the production graph nothing, and a renamed descriptor field becomes a typecheck failure in `dev/data.ts` naming the field. The bag was defended here as tolerance and bought three panels that were wrong for every row and could not go red: `route['render']`, `route['budget']`, `route['revalidate']`, `job['idempotencyKey']` and `entity['drift']` are names no descriptor has ever published, so a read answered `undefined`, took the fallback, and shipped the fallback as a fact — every route `stream` with no budget and no tag, every job non-idempotent, every schema drift-free. `dev/published-keys.test.ts` is the runtime half a type cannot answer: it walks what the real registries EMIT, so a field the type declares and the projection never writes is a red test.
+- **A fact `/_x` cannot know is absent or `null` — never a value that happens to be constant.** `hasMeta` was dropped because `defineRoute()` refuses a route with no `meta`, so `missingMeta` was a defect list with no member it could hold; `JobDescriptor.idempotent` is published *because* `job()` refuses a definition without a key — a guarantee shown where the question is asked. `DbPanelData.drift` is `null` when nothing wired the check, because drift is the entities against the DATABASE and `[]` claims a match nobody verified.
+- **One bridge per foreign package.** `policy-bridge.ts` is the only file calling `evaluate`/`definePermissions`; `routes.ts` the only one calling `defineRoute`; `mcp.ts` the only one calling `defineAppMcp`; `dev/data.ts` the only one importing introspection (dynamically — `/_x` must stay out of the production graph). Source only: a **test** declares the permissions its own `can()` fixtures use, because `definePermissions` writes a process-global registry and `bun test` seats several files in one process — `dev/data.test.ts` relied on the empty-registry-means-permissive fallback and went red the first time it shared a process with anything that imports this package.
 - **One entity surface** (`registry.ts`) — the admin reads what `entity()` actually exposes: `$name`, `$primaryKey`, `$columns[c].$meta`, `$schema`, `$describe()`. It is a structural subset so a new column kind still derives, and `RegisteredEntity` is the `tsc`-checked proof that a real `entity()` result satisfies it — never a comment claiming it does.
 - **One flattener.** `entity-columns.ts` is the only file that reads `$meta` or calls `$describe()`; everything downstream takes `AdminColumnFacts`. Money stays one property (the admin renders rows, not tables), a FK target comes back resolved from `$describe()`, and only a **generated** default (`uuid`, `now`) is read-only — `.default('free')` is a starting value.
 - **A deliberate query loop declares itself.** `search.ts` runs one indexed lookup per text field on purpose — the query IR is a conjunction, so three small indexed reads beat one unindexed `OR` — and says so through `expectedQueryLoop()` from `@ultimat3/db` (tier 1, downward, and the only thing this package imports from it). That is the one suppression mechanism: never a comment pragma and never a list of exempt call sites. A new loop here either argues for itself in a `reason` or it is an N+1.
@@ -24,7 +29,7 @@ Two products, one package, **two entry points**: `@ultimat3/admin/dev` (`src/dev
 - **A dev panel catches only the error that means "not wired".** `DevSourceUnavailableError` and nothing wider: a bare `catch` in `dev/panel-live.ts` reported an authz refusal and a dropped NATS connection from a *running* sync node as `dev.live.no-sync-node`, telling the reader to install a tier they already had. Everything else reaches `panelPayload`, which renders its code and its fix.
 - **What an entity does not declare, the admin does not invent.** `sensitive`, a fixed `currency` and `labelField` come from `AdminResourceOptions` or they are absent. Same rule for a URL: the reference widget links through `WidgetContext.hrefFor` or renders plain text — it used to build `/${entity}s/${id}`, which is English pluralisation by concatenation and drops `basePath`. The route table is `AdminApp`'s; a widget three layers down does not get to guess it.
 - **One read-only SQL guard, and it is `@ultimat3/mcp`'s — the whole verdict, with nothing held back.** `dev/panel-db.ts` calls `assertReadOnlyQuery` (tier 5 → tier 4, already a dependency) rather than keeping a second keyword scan: that guard also refuses a batch, a call into the `pg_read_*`/`pg_advisory_*`/`pg_sleep`/`set_config` families, `FOR UPDATE`, and a delimiter that never closes in all five forms (`'`, `E'`, `"`, `$tag$`, slash-star). A local unterminated-delimiter refusal lived here for one revision and was **deleted**: it tested for a surviving `'`/`"`, so it covered three of the five and called a dollar-quoted body "a quote" — one failure mode, two explanations, and a second detector for a property the guard below already tests. What stays local is the emptiness test and the **way out**: `@ultimat3/mcp` tells its caller to expose an action, which a developer at `/_x` cannot act on. The panel says "Fix the statement, or — if it is meant to write — run it with `x db psql --write`", conditional on purpose: `--write` grants writes, it does not close a delimiter, and it used to be printed as *the* fix for a syntax error.
-- **Every admin operation is audited, reads included.** `adminList` was the one call that logged nothing in either direction; `ListResult` now carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`), because the subject of a listing is not a row.
+- **Every admin operation is audited, reads included.** `adminList` was the one call that logged nothing in either direction; `ListResult` now carries its `AuditEntry` on both branches, keyed on the table (`entityId: null`), because the subject of a listing is not a row. `adminSearch` was the second, and it read rows out of EVERY readable entity: `AdminSearchResult.audit` now carries one entry per resource it decided about — `allowed` per searched resource, a `deniedDraft` per refused one. A resource skipped for having no text field or no repo is not an authz event and writes none.
 - Money through `assertMoney`, timestamps through `assertZone`, pagination through `pagination.ts`. No `offset`, ever.
 - **One cursor codec.** `pagination.ts` is the only file calling core's `encodeCursor`/`decodeCursor`; it wraps them as `encodeAdminCursor`/`decodeAdminCursor`, scoped `admin:<resource>`. An invalid cursor is page one here, not an error page — but the signature is checked first, so a forged one cannot seek.
 - Labels are i18n keys derived in `resource.ts` (`admin.<entity>.field.<name>`); only `.tsx` calls `t()`. MCP tool descriptions are literal English (protocol payload, not UI copy).

package/README.md

@@ -17,11 +17,11 @@ One panel per file. Each kills one question, and each is available as `--json`
 
 | Panel | Kills |
 |---|---|
-| `routes` | which handler serves this? — render mode, offline strategy, budget, meta |
+| `routes` | which handler serves this? — render mode, offline strategy, revalidate tags, budget |
 | `timeline` | where did the time go? — flamegraph of SQL, cache, action, policy spans + the N+1 count |
 | `live` | what does each subscriber receive, and **why** — the matcher's decision trace |
 | `jobs` | queue depth, step traces, retry-from-step target, dead letter |
-| `db` | psql in a tab (read-only; `assertReadOnly` refuses DML), schema diff vs migrations |
+| `db` | psql in a tab (read-only; `assertReadOnly` refuses DML), schema + drift (`null` unless a host wires the check) |
 | `mail` | caught mail, rendered, per locale, with the locale gaps listed |
 | `cache` | the tag graph — what invalidated what, and which tags are orphans |
 | `policy` | the permission matrix per actor, every cell carrying its trace |
@@ -201,7 +201,10 @@ shape already is, written down once so two apps do not invent two layouts. `x g
 | Every mutation and every denial is on the audit log, with a before/after diff | `audit.ts` |
 | Branding aliases tokens only — `accent: '#7c3aed'` is a compile error | `theme.ts` |
 
-Single-row reads are audited; list pages are not (volume).
+Reads are audited too, and on both branches: `adminDetail` keys its entry on the row,
+`adminList` and `adminSearch` key theirs on the table (`entityId: null`), and a refusal is an
+entry of its own. `AdminSearchResult.audit` carries one entry per resource the call decided
+about — searched or refused — so a jump box that walked every readable entity leaves a trace.
 
 ## AI-first
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/admin",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Two dashboards: the /_x framework dev panels and the generated, AI-first app admin",
   "license": "MIT",
   "type": "module",
@@ -32,20 +32,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "2.0.0",
-    "@ultimat3/ai": "2.0.0",
-    "@ultimat3/cache": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/db": "2.0.0",
-    "@ultimat3/entity": "2.0.0",
-    "@ultimat3/i18n": "2.0.0",
-    "@ultimat3/jobs": "2.0.0",
-    "@ultimat3/mcp": "2.0.0",
-    "@ultimat3/money": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/query": "2.0.0",
-    "@ultimat3/render": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/ui": "2.0.0"
+    "@ultimat3/action": "4.0.0",
+    "@ultimat3/ai": "4.0.0",
+    "@ultimat3/cache": "4.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/db": "4.0.0",
+    "@ultimat3/entity": "4.0.0",
+    "@ultimat3/i18n": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/mcp": "4.0.0",
+    "@ultimat3/money": "4.0.0",
+    "@ultimat3/policy": "4.0.0",
+    "@ultimat3/query": "4.0.0",
+    "@ultimat3/render": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/ui": "4.0.0"
   }
 }

package/src/admin.ts

@@ -6,6 +6,7 @@ import { type AuditLog, memoryAuditLog } from './audit';
 import type { AdminActor, AdminAuthz } from './authz';
 import type { CrudCtx } from './crud';
 import { permissionsForOperation } from './crud';
+import { AdminActionDuplicateError } from './errors';
 import { adminNav, type NavGroup, type NavItem, type NavOptions, visibleNav } from './nav';
 import { type AdminCustomPage, type AdminPageComponent, pageNavItems, pageRoutes } from './pages';
 import type { AdminOperation } from './permissions';
@@ -124,6 +125,37 @@ function resourceRoutes(basePath: string, resource: AdminResource): readonly Adm
   return routes;
 }
 
+/**
+ * One `AdminAction.name`, one handler. The name is the MCP tool name (`admin.action.<name>`), the
+ * default label key (`admin.action.<name>`) AND the key `callAdminTool` resolves a handler by, so
+ * two actions sharing it dispatch to whichever `.find()` reached first — a call that succeeds
+ * against the wrong action and reports nothing. Refused here rather than in `adminMcp()`, because
+ * an app that renders the dashboard and never wires MCP has the same two broken label keys and
+ * the same ambiguous dispatch.
+ *
+ * Identity, not name, is what "already seen" means: `defineAdmin` attaches `input.actions` to the
+ * entity each one names AND appends `resources[<entity>].actions`, so an author who spelled the
+ * same object in both meant one action, not two.
+ */
+function assertUniqueActionNames(
+  resources: readonly AdminResource[],
+  declared: readonly AdminAction[],
+): void {
+  const seen = new Map<string, { readonly action: AdminAction; readonly entities: string[] }>();
+  // `declared` is every action the caller passed, not just the global ones: an action naming an
+  // entity that is not in `entities` reaches neither list, and its name still has to be unique.
+  for (const action of [...resources.flatMap((resource) => resource.actions), ...declared]) {
+    const found = seen.get(action.name);
+    if (found === undefined) {
+      seen.set(action.name, { action, entities: [action.entity ?? 'the global toolbar'] });
+      continue;
+    }
+    if (found.action === action) continue;
+    found.entities.push(action.entity ?? 'the global toolbar');
+    throw new AdminActionDuplicateError({ name: action.name, entities: found.entities });
+  }
+}
+
 /** Derive the whole admin from the registries. */
 export function defineAdmin(input: DefineAdminInput): AdminApp {
   const basePath = input.basePath ?? '/admin';
@@ -141,6 +173,8 @@ export function defineAdmin(input: DefineAdminInput): AdminApp {
     });
   });
 
+  assertUniqueActionNames(resources, actions);
+
   const pages = input.pages ?? [];
   const navOptions = input.nav ?? {};
   const extra: readonly (NavItem & { readonly group: string })[] = [

package/src/authz.ts

@@ -11,6 +11,14 @@ import { ADMIN_PERMISSION_SPEC, type AdminPermission } from './permissions';
 
 export interface AdminActor {
   readonly id: string;
+  /**
+   * The tenant this operator acts under. NOT optional in practice on a multi-tenant app: the
+   * admin's subject reached `policyAuthz` with `orgId: undefined`, so an org-scoped rule could
+   * not fire and a role-only rule allowed — while `adminList`/`adminSearch` add no tenant
+   * predicate of their own. Absent still means "single-tenant app", which is why the type keeps
+   * it optional; a rule that reads it must fail closed on `undefined` like any other policy.
+   */
+  readonly orgId?: string;
   readonly roles?: readonly string[];
   /** BCP-47. Drives every `t()` call and every `Intl` format in the admin. */
   readonly locale?: string;
@@ -23,6 +31,16 @@ export interface AdminSubject {
   readonly entity?: string;
   readonly id?: string;
   readonly input?: unknown;
+  /**
+   * The already-loaded row, for a row-level rule. `null` means "no row was loaded", which the
+   * policy layer treats as no evidence of permission — same contract as an `action`'s `row:`
+   * loader. Absent entirely means the surface has no row to load (a list page, a create form).
+   *
+   * Without it every admin decision evaluated with `row: null` and `input = { entity, id }`, so
+   * an ownership rule could not fire at all and the coarse `admin:read` + `<entity>:read` pair
+   * was the only gate on a single row.
+   */
+  readonly row?: unknown;
 }
 
 export interface AdminDecision {

package/src/crud.ts

@@ -59,10 +59,20 @@ export function decideOperation(
   op: AdminOperation,
   ctx: CrudCtx,
   id?: string,
+  /**
+   * The row the surface ALREADY loaded, or `null` for "looked and found none". `undefined` means
+   * not loaded at all — a list page, a create form, a nav button — and is left off the subject
+   * entirely, because "there is no row here" and "there is a row and nobody loaded it" are
+   * different facts and only the second is a bug. Every admin decision used to be evaluated
+   * without one, so an ownership rule could not fire and the coarse `admin:read` + `<entity>:read`
+   * pair was the only gate on a single row.
+   */
+  row?: AdminRow | null,
 ): AdminDecision {
   return decideAll(ctx.authz, permissionsForOperation(resource.name, op), ctx.actor, {
     entity: resource.name,
     ...(id === undefined ? {} : { id }),
+    ...(row === undefined ? {} : { row }),
   });
 }
 
@@ -140,9 +150,12 @@ export async function adminDetail<Row extends AdminRow>(
   ctx: CrudCtx,
   id: string,
 ): Promise<CrudResult<Row>> {
-  const decision = decideOperation(resource, 'detail', ctx, id);
-  if (!decision.allowed) return refuse(resource, 'detail', ctx, decision, id);
+  // The row is loaded BEFORE the guard, the shape `packages/action/src/invoke.ts` uses for a
+  // row-level `policy`: a rule that decides about a row cannot decide without one, and the
+  // predicate has to stay synchronous. A denial still returns no row.
   const row = await repoOf(resource).find(id);
+  const decision = decideOperation(resource, 'detail', ctx, id, row);
+  if (!decision.allowed) return refuse(resource, 'detail', ctx, decision, id);
   return {
     ok: true,
     row,
@@ -196,11 +209,13 @@ export async function adminUpdate<Row extends AdminRow>(
   id: string,
   patch: Readonly<Record<string, unknown>>,
 ): Promise<CrudResult<Row>> {
-  const decision = decideOperation(resource, 'update', ctx, id);
-  if (!decision.allowed) return refuse(resource, 'update', ctx, decision, id);
-
+  // `before` was already loaded here, just after the guard rather than before it — so the rule
+  // that decides whether this actor may touch THIS row never saw the row.
   const repo = repoOf(resource);
   const before = await repo.find(id);
+  const decision = decideOperation(resource, 'update', ctx, id, before);
+  if (!decision.allowed) return refuse(resource, 'update', ctx, decision, id);
+
   const parsed = await validateInput(resource.entity.$schema, { ...(before ?? {}), ...patch });
   if (!parsed.ok) return invalid(resource, 'update', ctx, id, parsed.issues, decision);
 
@@ -208,9 +223,16 @@ export async function adminUpdate<Row extends AdminRow>(
   // strip (undeclared, or normalized to a different value) must never reach the repo. Scoped
   // to the keys actually submitted, so a partial update stays partial rather than rewriting
   // every field of `before` too.
+  // `Object.hasOwn`, not `key in`: `in` walks the prototype chain, so a patch naming `toString`,
+  // `constructor` or `__proto__` put an inherited member into the object handed to `repo.update`
+  // — the exact thing the paragraph above says cannot happen. Over MCP the transport refuses
+  // those keys (`additionalProperties: false`), but `callAdminTool` and `adminUpdate` are both
+  // public API and `mcp.ts` keeps its own gate for a direct call and a future transport.
   const submittedKeys = Object.keys(patch);
   const validatedPatch: Readonly<Record<string, unknown>> = Object.fromEntries(
-    submittedKeys.filter((key) => key in parsed.value).map((key) => [key, parsed.value[key]]),
+    submittedKeys
+      .filter((key) => Object.hasOwn(parsed.value, key))
+      .map((key) => [key, parsed.value[key]]),
   );
   const after = await repo.update(id, validatedPatch);
   return {
@@ -238,7 +260,9 @@ export async function adminDestroy<Row extends AdminRow>(
   id: string,
   confirmation: string | undefined,
 ): Promise<CrudResult<Row>> {
-  const decision = decideOperation(resource, 'delete', ctx, id);
+  const repo = repoOf(resource);
+  const before = await repo.find(id);
+  const decision = decideOperation(resource, 'delete', ctx, id, before);
   if (!decision.allowed) return refuse(resource, 'delete', ctx, decision, id);
 
   const expected = confirmationToken(resource.name, id);
@@ -258,8 +282,6 @@ export async function adminDestroy<Row extends AdminRow>(
     );
   }
 
-  const repo = repoOf(resource);
-  const before = await repo.find(id);
   await repo.destroy(id);
   return {
     ok: true,

package/src/detail.tsx

@@ -33,6 +33,18 @@ export interface AdminDetailProps<Row extends AdminRow> {
   readonly onCancel?: () => void;
 }
 
+/**
+ * The audit row's verb. `operation` holds a CRUD verb for `kind: 'operation'` and the ACTION NAME
+ * for `kind: 'action'`, and the catalog declares only `admin.operation.{list,detail,search,create,
+ * update,delete,page}` — so an entry for `post.publish` rendered the literal key
+ * `admin.operation.post.publish` into the page. `admin.action.<name>` is the same key
+ * `action-gate.ts` gives the button that ran it, so the two read identically.
+ */
+export const operationLabel = (entry: AuditEntry): string =>
+  entry.kind === 'action'
+    ? t(`admin.action.${entry.operation}`)
+    : t(`admin.operation.${entry.operation}`);
+
 export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>): JSX.Element {
   if (props.error !== null) {
     return <ErrorState error={adminErrorFrom(props.error)} />;
@@ -102,7 +114,7 @@ export function AdminDetail<Row extends AdminRow>(props: AdminDetailProps<Row>):
             {props.audit.map((entry) => (
               <li>
                 <code>{entry.at}</code> <span>{entry.actor.id}</span>{' '}
-                <span>{t(`admin.operation.${entry.operation}`)}</span>{' '}
+                <span>{operationLabel(entry)}</span>{' '}
                 <span data-outcome={entry.outcome}>
                   {t(`admin.audit.outcome.${entry.outcome}`)}
                 </span>

package/src/dev/data.ts

@@ -63,17 +63,6 @@ export function staticDevSources(facts: Partial<DevSources> = {}): DevSources {
   };
 }
 
-type Bag = Readonly<Record<string, unknown>>;
-
-const bagOf = (value: unknown): Bag =>
-  typeof value === 'object' && value !== null ? (value as Bag) : {};
-const str = (value: unknown, fallback = ''): string =>
-  typeof value === 'string' ? value : fallback;
-const numOf = (value: unknown, fallback = 0): number =>
-  typeof value === 'number' ? value : fallback;
-const listOf = (value: unknown): readonly unknown[] => (Array.isArray(value) ? value : []);
-const strings = (value: unknown): readonly string[] => listOf(value).map((item) => String(item));
-
 export interface DevSourceOptions {
   /** The app's authz. The policy matrix is computed through it, never re-derived. */
   readonly authz?: AdminAuthz;
@@ -136,9 +125,19 @@ const STEP_STATUS: Readonly<Record<StepStatus, JobStepFact['status']>> = {
 };
 
 /**
- * Registry output is read field by field: a registry that grows a field must not break the
- * dev dashboard, and a registry that renames one should show a blank cell in /_x rather than
- * crash the process an engineer is debugging with.
+ * Every registry is read through its OWN descriptor type, not as an untyped bag. The bag was
+ * defended here as tolerance — "a renamed field should show a blank cell rather than crash the
+ * process an engineer is debugging with" — and what it actually bought was three panels that
+ * were wrong for every row and could not go red: `route['render']`, `route['budget']`,
+ * `route['revalidate']` and `job['idempotencyKey']` are names no descriptor has ever published,
+ * so /_x reported every route as `stream` with no budget and every job as non-idempotent.
+ *
+ * The packages ship in lockstep at one version, so a renamed descriptor field is a rename this
+ * file can be edited with — as a TYPECHECK failure naming the field, which is the tolerance
+ * worth having. It costs the production graph nothing: `await import('@ultimat3/render')` is
+ * typed by the module it resolves to, so /_x is still reached only through the dynamic import
+ * and no descriptor type has to be named here at all. `published-keys.test.ts` is the other
+ * half — it walks what the real registries EMIT, which a stale `dist/*.d.ts` would hide.
  */
 export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
   const hooks = opts.hooks ?? {};
@@ -146,23 +145,26 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
   const sources: DevSources = {
     async routes(): Promise<readonly RouteFact[]> {
       const { describeRoutes } = await import('@ultimat3/render');
-      return listOf(describeRoutes()).map((raw) => {
-        const route = bagOf(raw);
-        const budget = bagOf(route['budget']);
-        return {
-          path: str(route['path']),
-          render: str(route['render'], 'stream'),
-          offline: str(route['offline'], 'network-only'),
-          hydrate: str(route['hydrate'], 'idle'),
-          handler: str(route['handler'], str(route['file'])),
-          budget: {
-            ...(typeof budget['js'] === 'string' ? { js: budget['js'] } : {}),
-            ...(typeof budget['lcp'] === 'number' ? { lcp: budget['lcp'] } : {}),
-          },
-          revalidateTags: strings(bagOf(route['revalidate'])['tags']),
-          hasMeta: route['meta'] !== undefined,
-        };
-      });
+      return describeRoutes().map((route) => ({
+        path: route.path,
+        // `RouteDescriptor` calls the render mode `mode`; the panel's own word is `render`, and
+        // the two are bridged here, once. Reading `route['render']` answered `undefined` for
+        // every route, so the fallback shipped — `stream` for the whole table, forever.
+        render: route.mode,
+        offline: route.offline,
+        hydrate: route.hydrate,
+        // A descriptor has no `handler`: the FILE is what names the row.
+        handler: route.file,
+        // Two flat fields on the descriptor, one nested bag on the fact — the panel's budget
+        // check reads `budget.js`. Spread, never `js: undefined`: `exactOptionalPropertyTypes`.
+        budget: {
+          ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
+          ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
+        },
+        // `revalidateTags`, already flattened to keys — never `revalidate.tags`, a shape the
+        // descriptor does not have and which answered `[]` for every ISR route in the app.
+        revalidateTags: route.revalidateTags,
+      }));
     },
 
     traces: unwired<readonly RequestTrace[]>('traces', 'timeline'),
@@ -186,38 +188,30 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
           entry.sql,
         ]),
       );
-      return listOf(queries).map((raw) => {
-        const query = bagOf(raw);
-        const name = str(query['name']);
-        return {
-          name,
-          live: query['live'] === true,
-          // `QueryDescriptor`'s permission field is named `capability`, not `policy` — this
-          // fact keeps its own field named `policy` (that is the /_x rendering, not the registry).
-          policy: str(query['capability']),
-          sql: sqlByName.get(name) ?? null,
-        };
-      });
+      return queries.map((query) => ({
+        name: query.name,
+        live: query.live,
+        // `QueryDescriptor`'s permission field is named `capability`, not `policy` — this
+        // fact keeps its own field named `policy` (that is the /_x rendering, not the registry).
+        policy: query.capability,
+        sql: sqlByName.get(query.name) ?? null,
+      }));
     },
 
     subscribers: unwired<readonly LiveSubscriberFact[]>('subscribers', 'live'),
 
     async jobDefs(): Promise<readonly JobDefFact[]> {
       const { describeJobs } = await import('@ultimat3/jobs');
-      return listOf(describeJobs()).map((raw) => {
-        const job = bagOf(raw);
-        const retry = bagOf(job['retry']);
-        return {
-          name: str(job['name']),
-          queue: str(job['queue'], 'default'),
-          steps: strings(job['steps']),
-          retry: {
-            attempts: numOf(retry['attempts'], 1),
-            backoff: str(retry['backoff'], 'exponential'),
-          },
-          idempotent: job['idempotencyKey'] !== undefined,
-        };
-      });
+      return describeJobs().map((job) => ({
+        name: job.name,
+        queue: job.queue,
+        steps: job.steps,
+        retry: { attempts: job.retry.attempts, backoff: job.retry.backoff },
+        // The descriptor's own boolean. `job['idempotencyKey']` was a read of the DEFINITION's
+        // field on a descriptor that never carried it, so every job on the panel reported
+        // non-idempotent — the opposite of what `job()` refuses to register without.
+        idempotent: job.idempotent,
+      }));
     },
 
     async queues(): Promise<readonly QueueFact[]> {
@@ -301,38 +295,28 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
 
     async tables(): Promise<readonly TableFact[]> {
       const { describeEntities } = await import('@ultimat3/entity');
-      return listOf(describeEntities()).map((raw) => {
-        const entity = bagOf(raw);
-        return {
-          name: str(entity['table'], str(entity['name'])),
-          // `EntityDescription.columns` is a LIST of physical columns — money is already two
-          // of them here. Reading it as a record produced a table whose columns were "0", "1".
-          columns: listOf(entity['columns']).map((rawColumn) => {
-            const column = bagOf(rawColumn);
-            return {
-              name: str(column['column'], str(column['property'], 'unknown')),
-              type: str(column['kind'], 'unknown'),
-              nullable: column['notNull'] !== true,
-            };
-          }),
-        };
-      });
+      return describeEntities().map((entity) => ({
+        name: entity.table,
+        // `EntityDescription.columns` is a LIST of physical columns — money is already two
+        // of them here. Reading it as a record produced a table whose columns were "0", "1".
+        columns: entity.columns.map((column) => ({
+          // The PHYSICAL name, which is the vocabulary a psql tab speaks.
+          name: column.column,
+          type: column.kind,
+          nullable: !column.notNull,
+        })),
+      }));
     },
 
-    async drift(): Promise<readonly DriftFact[]> {
-      const { describeEntities } = await import('@ultimat3/entity');
-      return listOf(describeEntities()).flatMap((raw) => {
-        const entity = bagOf(raw);
-        return listOf(entity['drift']).map((rawIssue) => {
-          const issue = bagOf(rawIssue);
-          return {
-            table: str(entity['table'], str(entity['name'])),
-            column: typeof issue['column'] === 'string' ? issue['column'] : null,
-            issue: str(issue['issue'], 'unknown'),
-          };
-        });
-      });
-    },
+    /**
+     * Unwired, and it has to be: drift is a COMPARISON — the entities this process declares
+     * against the columns a database actually has — and `describeEntities()` is only one half of
+     * it. This source used to read a `drift` key off `EntityDescription`, which has never had one,
+     * so the panel answered `[]` for every app and every schema: "no drift" printed over a
+     * database nobody looked at. Only a host holding the connection can answer (`x db migrate`'s
+     * `checkDrift`), so it wires the hook or the panel says the check did not run.
+     */
+    drift: unwired<readonly DriftFact[]>('drift', 'db'),
 
     runSql: unwired<SqlResult>('runSql', 'db'),
     mail: unwired<readonly MailFact[]>('mail', 'mail'),
@@ -347,16 +331,13 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         import('@ultimat3/cache'),
         import('@ultimat3/entity'),
       ]);
-      return listOf(describeEntities()).map((raw) => {
-        const name = str(bagOf(raw)['name']);
-        return {
-          tag: name,
-          dependents: listOf(dependentsOf([{ entity: name }])).map((rawDep) => {
-            const dep = bagOf(rawDep);
-            return { kind: str(dep['kind']), id: str(dep['id']) };
-          }),
-        };
-      });
+      return describeEntities().map((entity) => ({
+        tag: entity.name,
+        dependents: dependentsOf([{ entity: entity.name }]).map((dependent) => ({
+          kind: dependent.kind,
+          id: dependent.id,
+        })),
+      }));
     },
 
     invalidations: unwired<readonly InvalidationFact[]>('invalidations', 'cache'),
@@ -379,11 +360,15 @@ export function defaultDevSources(opts: DevSourceOptions = {}): DevSources {
         });
       }
       const { describeActions } = await import('@ultimat3/action');
-      // `ActionDescriptor`'s permission field is named `capability`, not `policy` — reading the
-      // latter answered '' for every action, so the matrix came back empty even when both
-      // `authz` and `actors` were wired correctly.
+      // `permissions`, NOT `capability`. `capability` is the policy's DISPLAY label and
+      // `action.ts` says so: a composite renders as `and(post:read, org:member)`, which is not a
+      // permission and can never be granted — so every composite-guarded action was a
+      // permanently-denied row, and an operator read a real grant as missing. `permissions` is
+      // the flattened list a grant is actually matched against. This is the SECOND time the two
+      // were confused: `x policy list` reported the same actions as unenforced for the same
+      // reason, and `ActionDescriptor.permissions` carries that history in its own doc comment.
       const permissions = [
-        ...new Set(listOf(describeActions()).map((raw) => str(bagOf(raw)['capability']))),
+        ...new Set(describeActions().flatMap((action) => action.permissions)),
       ].filter((permission) => permission !== '');
 
       return actors.flatMap((actor) =>

package/src/dev/facts.ts

@@ -1,15 +1,27 @@
 // The facts a /_x panel may read: one shape per introspection call. Kept apart from the
 // sources that produce them so a panel imports the shape it renders and nothing else.
 
+/**
+ * One row of the route table, in the panel's own words: `render` is the descriptor's `mode` and
+ * `handler` is its `file`. Both renames are made in `data.ts`, once.
+ *
+ * There is no `hasMeta`, deliberately. `defineRoute()` REFUSES a route with no `meta` function
+ * (`packages/render/src/route.ts`), so every registered route has one and the field could only
+ * ever be `true` — it was published as `false` for every route instead, off a `meta` key no
+ * descriptor carries, and fed a `missingMeta` list that can never have a member. Whether the meta
+ * a route returns is any GOOD is a render-time question: `meta` takes the loaded data, so nothing
+ * static can answer it, and a list that always reads "0 routes missing meta" is worse than absent.
+ */
 export interface RouteFact {
   readonly path: string;
+  /** `RouteDescriptor.mode` — `ssr`, `isr`, `static`, `stream`, `spa`. */
   readonly render: string;
   readonly offline: string;
   readonly hydrate: string;
+  /** The route's source file: what names the row. A descriptor publishes no handler. */
   readonly handler: string;
   readonly budget: { readonly js?: string; readonly lcp?: number };
   readonly revalidateTags: readonly string[];
-  readonly hasMeta: boolean;
 }
 
 /**
@@ -85,6 +97,12 @@ export interface JobDefFact {
   readonly queue: string;
   readonly steps: readonly string[];
   readonly retry: { readonly attempts: number; readonly backoff: string };
+  /**
+   * `JobDescriptor.idempotent` — `true` for every registered job, because `job()` refuses a
+   * definition with no `idempotencyKey`. Published rather than assumed: it read the DEFINITION's
+   * `idempotencyKey` off a descriptor that never carried it, so the panel called every job in
+   * the app unsafe to retry.
+   */
   readonly idempotent: boolean;
 }
 
@@ -153,6 +171,11 @@ export interface TableFact {
   readonly columns: readonly ColumnFact[];
 }
 
+/**
+ * One column the database and the entities disagree about. A COMPARISON, so no registry can
+ * produce it alone — `DevSources.drift` is a hook a host holding the connection wires, and the
+ * db panel reports `drift: null` ("nobody checked") rather than `[]` ("nothing wrong") without it.
+ */
 export interface DriftFact {
   readonly table: string;
   readonly column: string | null;