@ultimat3/cli 1.2.0 → 3.0.0

package/src/metrics-endpoint.ts

@@ -8,15 +8,20 @@ import {
   METRICS_PATH,
   markListening,
   metricsText,
+  stringField,
+  UltimateError,
 } from '@ultimat3/core';
+import { docsFor } from './error-codes';
+import { neighbouringPort } from './flag-number';
 
 /**
  * A port of its own, and NOT the role's HTTP port, for one reason the chart makes concrete:
  * `docker/helm/templates/ingress.yaml` routes `path: /` `Prefix` to the web Service, so a
  * `/metrics` mounted beside `/healthz` on port 3000 is `/metrics` on the internet — route
- * patterns, request volumes and error rates, published. Nothing in the chart fronts this port:
- * `service.yaml` only publishes `http`, so the endpoint is cluster-internal by construction
- * rather than by an ingress exclusion somebody has to remember to write.
+ * patterns, request volumes and error rates, published. `service.yaml` does publish this port
+ * so a `ServiceMonitor` has a named target, but `ingress.yaml` selects its backend port BY NAME
+ * (`http`), so the endpoint stays cluster-internal by construction rather than by an ingress
+ * exclusion somebody has to remember to write.
  *
  * It is also the only thing `worker`, `scheduler` and `replicator` could ever be scraped on —
  * they open no HTTP socket at all, and `queue_depth` is exactly the signal one of them owns.
@@ -24,6 +29,37 @@ import {
  */
 export const DEFAULT_METRICS_PORT = 9090;
 
+/**
+ * `X_PORT_IN_USE` is the code the CLI already registers for "this dev port is taken", and the
+ * scrape port is one — a synonym here would be a second code for one condition. The fix moves the
+ * port rather than naming a process to kill, because `METRICS_PORT` is the one knob both `x dev`
+ * and the container read (`serve.ts`'s `metricsPortFromEnv`).
+ *
+ * The port it names comes from `neighbouringPort`, never `port + 1`: at the top of the range
+ * that is 65536, and an instruction that cannot run is the failure this code exists to end.
+ */
+export class MetricsPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
+      fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
+      docs: docsFor('X_PORT_IN_USE'),
+    });
+  }
+}
+
+/**
+ * Bun surfaces the bind failure as an `Error` carrying the libc code; nothing else is ours. Read
+ * through `stringField`, never `error instanceof Error` plus a property access: both run on a value
+ * this process did not build, and either can throw one line before the guard that was meant to make
+ * the path safe. Exported because whether the kernel refuses a second bind is the OS's business,
+ * not this package's — the contract worth pinning is that an EADDRINUSE-shaped throw becomes a
+ * coded refusal, and that is testable without racing a socket.
+ */
+export const isAddressInUse = (error: unknown): boolean =>
+  stringField(error, 'code') === 'EADDRINUSE';
+
 export interface MetricsEndpointOptions {
   /** 0 asks the kernel for an ephemeral port, which is what a test wants. */
   readonly port?: number;
@@ -44,20 +80,32 @@ export interface MetricsEndpoint {
  * signal at the moment of load is worse than no autoscaler.
  */
 export function startMetricsEndpoint(options: MetricsEndpointOptions = {}): MetricsEndpoint {
-  const server = Bun.serve({
-    port: options.port ?? DEFAULT_METRICS_PORT,
-    hostname: options.hostname ?? 'localhost',
-    fetch(request: Request): Response {
-      if (new URL(request.url).pathname !== METRICS_PATH) {
-        return new Response('not found', { status: 404 });
-      }
-      // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot steal
-      // each other's samples — but a cache would hand the second one a stale window.
-      return new Response(metricsText(), {
-        headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+  const port = options.port ?? DEFAULT_METRICS_PORT;
+  // `startRoles` opens this FIRST, before any role, so `Bun.serve`'s own bare `Error` was what a
+  // second `x dev` on one machine reported: no code, no fix, at the boot path this package owns.
+  // The return type is inferred, keeping `Bun.serve`'s own shape stated once.
+  function listen() {
+    try {
+      return Bun.serve({
+        port,
+        hostname: options.hostname ?? 'localhost',
+        fetch(request: Request): Response {
+          if (new URL(request.url).pathname !== METRICS_PATH) {
+            return new Response('not found', { status: 404 });
+          }
+          // `collectMetrics()` is cumulative and never reset by a read, so two scrapers cannot
+          // steal each other's samples — but a cache would hand the second one a stale window.
+          return new Response(metricsText(), {
+            headers: { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' },
+          });
+        },
       });
-    },
-  });
+    } catch (error) {
+      if (!isAddressInUse(error)) throw error;
+      throw new MetricsPortInUseError({ port });
+    }
+  }
+  const server = listen();
   // Same rule as every other socket the framework opens: announce it, so a request back to it is
   // recognisably this process calling itself rather than egress the test seal must refuse.
   const stopListening = markListening(server.url.origin);

package/src/migrations.ts

@@ -4,11 +4,18 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Migration } from '@ultimat3/db';
+import type { Migration, SchemaDescription } from '@ultimat3/db';
+import { parseSnapshot } from '@ultimat3/db';
 
-/** Where `x new` writes them and where `x db gen` adds to. App-root-relative, POSIX. */
+/** Where `x db gen` — the only writer — puts them. App-root-relative, POSIX. */
 export const MIGRATIONS_DIR = 'packages/db/migrations';
 
+/** The schema `<id>` leaves behind, written by `x db gen` so the next one can diff against it. */
+export const snapshotFileName = (id: string): string => `${id}.snapshot.json`;
+
+/** The hash of the entity source `<id>` was generated from. `drift.ts` writes and reads it. */
+export const hashFileName = (id: string): string => `${id}.hash`;
+
 /**
  * `-- down` alone on a line splits a migration file. Anchored to the whole line so a comment that
  * merely mentions the word — `-- down migrations are required` — is not mistaken for the marker.
@@ -25,21 +32,47 @@ export function parseMigrationSql(id: string, sql: string): Migration {
   return { id, name: migrationName(id), up, down };
 }
 
+/**
+ * A snapshot that will not parse is *absent*, never a half-read one: the `up` beside it is still
+ * the migration this app applies, so the file list stays whole. What that absence then means is
+ * the caller's — `x db gen` refuses with `X_MIGRATION_SNAPSHOT_MISSING` when it is the newest
+ * migration's, because there is nothing left to diff the entities against.
+ */
+async function readSnapshot(dir: string, id: string): Promise<SchemaDescription | undefined> {
+  const file = Bun.file(join(dir, snapshotFileName(id)));
+  if (!(await file.exists())) return undefined;
+  // Parsed to the last nested field by `@ultimat3/db`, never asserted: `{"tables":[null]}` is
+  // valid JSON and a cast made it a `SchemaDescription` the diff then threw on.
+  return parseSnapshot(await file.json().catch(() => undefined));
+}
+
 /**
  * Sorted by id, because that is the apply order and `pendingMigrations` re-sorts on the same key.
  * A missing directory is an empty list rather than a throw: an app can legitimately declare no
  * entity yet, and the count is reported so "nothing was applied" is never silent.
+ *
+ * `<id>.down.sql` is skipped and never read as a migration of its own. Migrations before 1.2.0
+ * were hand-written as a `<id>.sql` / `<id>.down.sql` pair — a layout no generator ever produced
+ * and this reader would have applied as a migration named `<id>.down`, dropping every table the
+ * pair exists to reverse. One migration is one file, split by the `-- down` marker.
  */
 export async function readMigrations(root: string): Promise<readonly Migration[]> {
   const dir = join(root, MIGRATIONS_DIR);
   if (!existsSync(dir)) return [];
   const files: string[] = [];
-  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir })) files.push(file);
+  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir })) {
+    if (!file.endsWith('.down.sql')) files.push(file);
+  }
   files.sort();
   const migrations: Migration[] = [];
   for (const file of files) {
+    const id = file.replace(/\.sql$/, '');
     const text = await Bun.file(join(dir, file)).text();
-    migrations.push(parseMigrationSql(file.replace(/\.sql$/, ''), text));
+    const snapshot = await readSnapshot(dir, id);
+    migrations.push({
+      ...parseMigrationSql(id, text),
+      ...(snapshot === undefined ? {} : { snapshot }),
+    });
   }
   return migrations;
 }

package/src/otlp-export.ts

@@ -0,0 +1,64 @@
+// OTLP export, switched on by the variable the shipped Helm chart already sets. Until this file
+// `OTEL_EXPORTER_OTLP_ENDPOINT` was in `docker/helm/values.yaml` and **no code read it**: a
+// deployment configured a collector, the collector received nothing, and the only signal that
+// anything was wrong was an empty dashboard.
+
+import {
+  configureMetrics,
+  configureTelemetry,
+  logger,
+  onShutdown,
+  otlpMetricExporter,
+  otlpSpanExporter,
+  startMetricExport,
+  tryOtlpEndpoint,
+} from '@ultimat3/core';
+import type { Env } from './dev-services';
+
+/** How often counters are pushed. Core's own default; named here because the boot chose it. */
+export const METRIC_EXPORT_INTERVAL_MS = 60_000;
+
+/**
+ * Install whichever exporters an endpoint was configured for, and return the release.
+ *
+ * `tryOtlpEndpoint` is asked FIRST, per signal, because both constructors throw
+ * `X_OTLP_ENDPOINT_INVALID` when nothing configured one — deliberately, so that a telemetry
+ * exporter can never silently send nowhere. Asking is what makes the exporter optional without
+ * making it silent.
+ *
+ * Both are registered with `onShutdown(..., { phase: 'close' })`: the last spans of a drain are
+ * the ones that explain the drain, and a process that exits with a full queue loses exactly the
+ * window an operator went looking for.
+ */
+export function startOtlpExport(env: Env = process.env): () => void {
+  const releases: (() => void)[] = [];
+
+  // The boot's OWN env, not `process.env`, and the resolved endpoint is then passed to the
+  // exporter explicitly: `runRole({ env })` is a real seam — a test and an in-process host both
+  // pass an env that is not the process's — and an exporter that re-read `process.env` would
+  // answer a different question from the one this function just asked.
+  const traces = tryOtlpEndpoint('traces', env);
+  if (traces !== undefined) {
+    const exporter = otlpSpanExporter({ endpoint: traces });
+    configureTelemetry({ exporter });
+    releases.push(onShutdown('otlp-traces', () => exporter.shutdown(), { phase: 'close' }));
+    logger.info('ultimate otlp traces', { endpoint: traces });
+  }
+
+  const metrics = tryOtlpEndpoint('metrics', env);
+  if (metrics !== undefined) {
+    const exporter = otlpMetricExporter({ endpoint: metrics });
+    configureMetrics({ exporter });
+    // The push loop, and not only the exporter: `configureMetrics` names where a snapshot goes
+    // and nothing decides when one is taken, so without this the collector receives one export —
+    // the drain's — for the whole life of the process.
+    const stopTimer = startMetricExport(METRIC_EXPORT_INTERVAL_MS);
+    releases.push(stopTimer);
+    releases.push(onShutdown('otlp-metrics', () => exporter.flush(), { phase: 'close' }));
+    logger.info('ultimate otlp metrics', { endpoint: metrics });
+  }
+
+  return () => {
+    for (const release of releases.reverse()) release();
+  };
+}

package/src/output.ts

@@ -2,6 +2,9 @@
 // and the JSON renderer are projections of it, so `--json` can never drift from the terminal
 // output (axiom 4). The human renderer owns the canonical 3-line error format.
 
+import { renderThrowable, stringField } from '@ultimat3/core';
+import { msg } from './messages';
+
 export interface Finding {
   readonly code: string;
   readonly cause: string;
@@ -19,6 +22,8 @@ export interface StepResult {
   readonly findings: readonly Finding[];
   /** Captured stdout/stderr, shown on failure or with --verbose. */
   readonly output?: string;
+  /** Worker processes the step used; `1` means it ran serially. Absent for a non-test step. */
+  readonly workers?: number;
 }
 
 export type JsonValue =
@@ -57,34 +62,39 @@ export interface UltimateErrorShape {
   readonly message: string;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
 /**
  * Structural check, deliberately not `instanceof`: an error may cross a subprocess or worker
  * boundary and arrive as a plain object, and the renderer must still produce the fix line.
+ *
+ * Every field goes through core's `stringField`, because the value is a caught throwable and the
+ * probe itself is a property read: a getter that throws, or a `Proxy` trapping `get`, raised HERE
+ * — one line before the total renderer below, in the function whose whole job is deciding what the
+ * terminal shows.
  */
 export function isUltimateErrorShape(value: unknown): value is UltimateErrorShape {
-  if (!isRecord(value)) return false;
   return (
-    typeof value['code'] === 'string' &&
-    value['code'].startsWith('X_') &&
-    typeof value['cause'] === 'string' &&
-    typeof value['fix'] === 'string'
+    stringField(value, 'code')?.startsWith('X_') === true &&
+    stringField(value, 'cause') !== undefined &&
+    stringField(value, 'fix') !== undefined
   );
 }
 
 export function findingFrom(value: unknown): Finding {
-  if (isUltimateErrorShape(value)) {
-    const docs = value.docs;
-    return docs === undefined
-      ? { code: value.code, cause: value.cause, fix: value.fix }
-      : { code: value.code, cause: value.cause, fix: value.fix, docs };
+  // Read once and carry the values, rather than narrowing and reading the same properties again:
+  // a getter is a function, and nothing promises it answers the same way twice.
+  const code = stringField(value, 'code');
+  const cause = stringField(value, 'cause');
+  const fix = stringField(value, 'fix');
+  if (code?.startsWith('X_') === true && cause !== undefined && fix !== undefined) {
+    const docs = stringField(value, 'docs');
+    return docs === undefined ? { code, cause, fix } : { code, cause, fix, docs };
   }
-  const cause = value instanceof Error ? value.message : String(value);
+  // This is the LAST renderer between a thrown value and the terminal: a hostile `toString`, a
+  // throwing `message` getter or a trapped `instanceof` here loses the whole report, not one line
+  // of it. `renderThrowable` is total on all three.
   return {
     code: 'X_CLI_UNEXPECTED',
-    cause,
+    cause: renderThrowable(value),
     fix: 'x doctor --json',
     docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
   };
@@ -130,10 +140,20 @@ const mark = (step: StepResult): string => {
   return step.ok ? '✓' : '✗';
 };
 
+/**
+ * How the step was run, when that is a fact about the step rather than about the machine. A gate
+ * that silently went parallel is a gate whose failures a reader would blame on flakiness, so a
+ * serial step says so and a parallel one names its width.
+ */
+const width = (step: StepResult): string => {
+  if (step.workers === undefined || step.skipped === true) return '';
+  return `  ${step.workers === 1 ? msg('cli.verify.serial') : msg('cli.verify.workers', { workers: step.workers })}`;
+};
+
 export function renderHuman(result: CommandResult, verbose = false): string {
   const out: string[] = [];
   for (const step of result.steps ?? []) {
-    out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms`);
+    out.push(`  ${mark(step)} ${step.name.padEnd(18)} ${step.durationMs}ms${width(step)}`);
     for (const finding of step.findings) out.push(renderFinding(finding, '      '));
     if (step.output !== undefined && step.output.length > 0 && (verbose || !step.ok)) {
       for (const line of step.output.trimEnd().split('\n')) out.push(`      | ${line}`);
@@ -152,6 +172,16 @@ export function renderJson(result: CommandResult): string {
     durationMs: step.durationMs,
     skipped: step.skipped === true,
     findings: step.findings,
+    ...(step.workers === undefined ? {} : { workers: step.workers }),
+    // A FAILED step carries its captured stdout, exactly as the human renderer prints it. CI runs
+    // `--json`, and without this the log said only "one or more unit tests failed" with a generic
+    // fix line — the failing test's name and its assertion diff existed and were thrown away, so
+    // the only way to learn what broke was to re-run it somewhere else. CI output is a prompt:
+    // whoever reads it next, agent or human, must be able to act without reproducing first.
+    // Success stays quiet (`--verbose` is the human's opt-in) so a green run is not a wall of text.
+    ...(step.ok || step.output === undefined || step.output.length === 0
+      ? {}
+      : { output: step.output }),
   }));
   const payload = {
     ok: result.ok,

package/src/parse.ts

@@ -2,7 +2,7 @@
 // same way and `--json` / `--help` behave identically everywhere. Pure: no I/O, no process
 // access, so the parser is unit-testable and the dispatcher owns all side effects.
 
-import { BadFlagError, UnknownCommandError } from './errors';
+import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './errors';
 
 export type FlagValue = string | boolean;
 
@@ -20,6 +20,32 @@ export interface CommandSpec {
   readonly usage: string;
   readonly aliases?: readonly string[];
   readonly subcommands?: readonly string[];
+  /**
+   * What a bare `x <command>` means, when it means anything. Declared, never inferred: the parser
+   * used to answer `subcommands[0]`, so `x db` ran `gen` — the migration GENERATOR — because it
+   * sorted first. A command with no defensible default omits this and the parser refuses instead.
+   */
+  readonly defaultSubcommand?: string;
+  /**
+   * A closed set the FIRST positional must come from, where the command has one. Declarative only:
+   * the parser leaves positionals to the command, because `x test`'s own `readOnlyType` already
+   * refuses an unknown type with the list. What this adds is a set `fix-command.ts` can resolve a
+   * citation against. `packages/ai/src/eval-errors.ts` avoids `x test <eval-name>` by hand, with a
+   * three-line comment explaining that it is `X_CLI_BAD_FLAG` — a convention held by memory,
+   * because nothing outside `cmd-test.ts` knew what `x test` accepts. Declare it from the SAME
+   * constant the command validates against, never a second literal.
+   */
+  readonly positionalChoices?: readonly string[];
+  /**
+   * The same closed set, one level down: the set a named SUBCOMMAND's first positional must come
+   * from. `positionalChoices` cannot express it, because `fix-command.ts` only consults that field
+   * where a command declares NO subcommands — so `x db branch ls` resolved as command +
+   * subcommand and nothing ever looked at `ls`. That is how a shipped `fix:` told an agent to run
+   * a listing while `x db branch` read `ls` as a branch name and created a database from it.
+   * Declarative only, exactly like `positionalChoices`: the command still refuses an unknown word
+   * itself, and this is declared from the SAME constant it validates against.
+   */
+  readonly subcommandPositionals?: Readonly<Record<string, readonly string[]>>;
   readonly flags?: readonly FlagSpec[];
   /** Command needs an app root (`app.config.ts`) — the dispatcher enforces it. */
   readonly requiresApp?: boolean;
@@ -44,6 +70,15 @@ export const GLOBAL_FLAGS: readonly FlagSpec[] = [
   { name: 'verbose', type: 'boolean', summary: 'include step output on success' },
 ];
 
+/**
+ * Whether raw argv asked for JSON, readable BEFORE the parse succeeds. The parse-failure path in
+ * `dispatch.ts` has no `ParsedArgs` to read `--json` off — and it used to test `argv.includes`
+ * for the long form only, so `x doctor -j --bogusflag` rendered its `X_CLI_BAD_FLAG` as prose to
+ * an agent that had asked for JSON and then called `JSON.parse` on it. One detection, two callers.
+ */
+export const wantsJson = (argv: readonly string[]): boolean =>
+  argv.some((token) => token === '--json' || token === '-j');
+
 const HELP_ALIASES = new Set(['--help', '-h', 'help']);
 const VERSION_ALIASES = new Set(['--version', '-v', '-V']);
 
@@ -118,7 +153,7 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   // `help` and `version` short-circuit the flag loop below, so `--json` has to be read here or the
   // two commands silently print prose to an agent that asked for JSON — and every `fix:` naming
   // `x help --json` would be a command that does not do what it says.
-  const json = tokens.some((token) => token === '--json' || token === '-j');
+  const json = wantsJson(tokens);
   if (VERSION_ALIASES.has(first)) return blank('version', specs, json);
   if (HELP_ALIASES.has(first)) {
     const rest = tokens.slice(1).filter((token) => !token.startsWith('-'));
@@ -198,7 +233,10 @@ function readSubcommand(spec: CommandSpec, positionals: readonly string[]): stri
   const allowed = spec.subcommands;
   if (allowed === undefined || allowed.length === 0) return undefined;
   const token = positionals[0];
-  if (token === undefined) return allowed[0];
+  if (token === undefined) {
+    if (spec.defaultSubcommand !== undefined) return spec.defaultSubcommand;
+    throw new MissingSubcommandError({ command: spec.name, known: allowed });
+  }
   if (allowed.includes(token)) return token;
   const suggestion = nearest(token, allowed);
   throw new UnknownCommandError(

package/src/policy-facts.ts

@@ -12,12 +12,30 @@ import { devActors } from './dev-policy';
 
 const isDefined = <T>(value: T | undefined): value is T => value !== undefined;
 
-/** Descriptor names whose `capability` is exactly this permission — shared by list and explain. */
-const namesEnforcing = <D extends { readonly name: string; readonly capability: string }>(
+/**
+ * Descriptor names whose policy references this permission — shared by list and explain.
+ *
+ * Matched on `permissions` and never on `capability`. `capability` is the DISPLAY label, and a
+ * composite policy renders as `and(post:publish, org:administer)` — never a bare permission — so
+ * an equality test against it reported every action guarded by a composite as enforcing nothing.
+ * That is `unenforced`: "this grant does nothing", printed about every non-trivial rule in a real
+ * app, to the compliance engineer reading it before an access review.
+ */
+const namesEnforcing = <
+  D extends { readonly name: string; readonly permissions: readonly string[] },
+>(
   descriptors: readonly D[],
   permission: string,
 ): readonly string[] =>
-  descriptors.filter((descriptor) => descriptor.capability === permission).map((d) => d.name);
+  descriptors
+    .filter((descriptor) => descriptor.permissions.includes(permission))
+    .map((d) => d.name);
+
+/** The same rule as `namesEnforcing`, for the two `explain` filters that keep the descriptor. */
+const enforces = (
+  descriptor: { readonly permissions: readonly string[] },
+  permission: string,
+): boolean => descriptor.permissions.includes(permission);
 
 // ── list ──────────────────────────────────────────────────────────────────
 
@@ -66,7 +84,14 @@ export type SubjectKind = 'permission' | DeclarationKind;
 export interface DeclarationExplanation {
   readonly name: string;
   readonly kind: DeclarationKind;
+  /** The policy's DISPLAY label — `and(post:publish, org:administer)` for a composite. */
   readonly capability: string;
+  /**
+   * Every permission the policy tree references, flattened. What a grant is MATCHED against; the
+   * label above is what a person reads. Published because `grantingRoles` is derived from it —
+   * `rolesGranting('and(a:b, c:d)')` is a lookup that can only ever answer nothing.
+   */
+  readonly permissions: readonly string[];
   readonly label: string;
   /**
    * Whether this policy can be decided at all outside a request. `false` when evaluating it
@@ -117,6 +142,7 @@ const explainAction = (action: AnyAction): DeclarationExplanation => {
     name: descriptor.name,
     kind: 'action',
     capability: descriptor.capability,
+    permissions: descriptor.permissions,
     label: action.policy.label,
     ...matrixFor(action.policy),
   };
@@ -128,6 +154,7 @@ const explainQuery = (query: AnyQuery): DeclarationExplanation => {
     name: descriptor.name,
     kind: 'query',
     capability: descriptor.capability,
+    permissions: descriptor.permissions,
     label: query.policy.label,
     ...matrixFor(query.policy),
   };
@@ -168,12 +195,12 @@ export function explainPolicy(name: string): SubjectExplanation | undefined {
     const { permission } = resolved;
     const declarations = [
       ...describeActions()
-        .filter((descriptor) => descriptor.capability === permission)
+        .filter((descriptor) => enforces(descriptor, permission))
         .map((descriptor) => getAction(descriptor.name))
         .filter(isDefined)
         .map(explainAction),
       ...describeQueries()
-        .filter((descriptor) => descriptor.capability === permission)
+        .filter((descriptor) => enforces(descriptor, permission))
         .map((descriptor) => getQuery(descriptor.name))
         .filter(isDefined)
         .map(explainQuery),
@@ -190,7 +217,12 @@ export function explainPolicy(name: string): SubjectExplanation | undefined {
   return {
     subject: name,
     kind: resolved.kind,
-    grantingRoles: rolesGranting(declaration.capability),
+    // The union over every permission the policy references, not a lookup on the label: a
+    // composite-guarded action reported NO granting roles at all, which reads as "nobody can do
+    // this" about a declaration half the roles in the app can reach.
+    grantingRoles: [
+      ...new Set(declaration.permissions.flatMap((permission) => rolesGranting(permission))),
+    ].sort(),
     declarations: [declaration],
   };
 }

package/src/policy-fixture.ts

@@ -15,19 +15,26 @@ interface PostRow {
 }
 
 /**
- * Three permissions, three roles, two actions and two queries — each fact earning its place.
+ * Four permissions, three roles, two actions and two queries — each fact earning its place.
  *
- * `post:read` is declared but enforced by nothing: `archivePost`'s policy grants that permission
- * to its second clause, but the compound policy's own capability is `and(post:publish, post:read)`
- * — a different string — so `post:read` alone stays unenforced. `post:publish` is enforced by an
- * action AND a query at once, so the aggregation across declarations has something to aggregate.
+ * `archivePost` is guarded by a COMPOSITE, and that is the point of it: its display capability is
+ * the label `and(post:publish, post:read)`, which is not any permission, so a report that matched
+ * on the label counted this action as enforcing nothing and printed both of its permissions as
+ * dead grants. It enforces two, and the facts say so.
+ *
+ * `post:delete` is the control: declared, granted to `admin`, enforced by nothing at all. It is
+ * what a genuinely dead grant looks like, and it is what keeps `unenforced` a claim worth making
+ * now that a composite no longer lands in it by accident.
+ *
+ * `post:publish` is enforced by two actions AND a query, so the aggregation across declarations
+ * has something to aggregate.
  *
  * Registers only; the registries are process-global, so the caller clears them first.
  */
 export function registerPolicyFixture(): void {
-  definePermissions(['post:publish', 'post:read', 'feed:read'] as const);
+  definePermissions(['post:publish', 'post:read', 'post:delete', 'feed:read'] as const);
   defineRoles({
-    admin: { grants: ['post:publish', 'post:read', 'feed:read'] },
+    admin: { grants: ['post:publish', 'post:read', 'post:delete', 'feed:read'] },
     editor: { grants: ['post:publish', 'post:read'] },
     reader: { grants: ['post:read', 'feed:read'] },
   });