@ultimat3/cli 1.2.0 → 3.0.0

package/src/serve.ts

@@ -4,11 +4,25 @@
 // `dev: true`. The only production-shaped decisions live here: which role, which port, and the
 // fact that a container must bind every interface.
 
-import { listActions, toRoute } from '@ultimat3/action';
 import type { Role } from '@ultimat3/core';
-import { isRole, logger, ROLES } from '@ultimat3/core';
-import { type MigrationReport, migrate } from '@ultimat3/db';
+import {
+  configureErrorReporting,
+  isRole,
+  logger,
+  ROLES,
+  sentryErrorReporter,
+} from '@ultimat3/core';
+import {
+  assertNoDrift,
+  checkDrift,
+  type DriftReport,
+  type MigrationReport,
+  migrate,
+} from '@ultimat3/db';
 import type { Route } from '@ultimat3/http';
+import { createIsrController } from '@ultimat3/render';
+import { apiRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import { assetRoutes } from './dev-assets';
@@ -20,10 +34,15 @@ import type { RunningServices } from './dev-runtime';
 import { startServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { resolveServices } from './dev-services';
+import { storageRoutes } from './dev-storage';
 import { PortInvalidError, RoleUnknownError } from './errors';
 import { holdUntilShutdown } from './hold';
+import { buildIslands } from './island-bundle';
+import { islandRoutes } from './island-routes';
 import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import { readMigrations } from './migrations';
+import { startOtlpExport } from './otlp-export';
+import type { RuntimeOverrides } from './runtime-overrides';
 
 export const DEFAULT_PORT = 3000;
 
@@ -67,6 +86,45 @@ export function metricsPortFromEnv(env: Env): number {
   return portValue(env, 'METRICS_PORT', DEFAULT_METRICS_PORT);
 }
 
+/**
+ * The scrape port a boot uses, given the app port it already resolved. One expression, and it is
+ * exported because `x dev` is the second caller: `cmd-dev.ts` passed no `metricsPort` at all, so
+ * `METRICS_PORT` was honoured in the container and ignored on a laptop — the dev/prod parity break
+ * `dev-roles.ts`'s own header forbids, and a second copy of this rule would be the same break
+ * one edit later.
+ *
+ * An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
+ * fixed 9090 would fail the next suite to boot beside it. An environment that names the port still
+ * wins — that is the deploy talking.
+ */
+export const metricsPortFor = (env: Env, port: number, override?: number): number =>
+  override ?? (port === 0 && env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(env));
+
+/**
+ * The one env var that turns error monitoring on, and the only vendor-shaped name in the boot
+ * path. Not a platform primitive (axiom 7): the value is a URL to whatever the operator runs, the
+ * wire format behind it is documented and self-hostable, and `SENTRY_DSN` is what every monitor
+ * that speaks it already documents — inventing a second spelling would mean an operator's existing
+ * tooling sets a variable this framework ignores. Exactly the precedent
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` already sets in `docker/helm/values.yaml`.
+ */
+export const ERROR_DSN_KEY = 'SENTRY_DSN';
+
+/**
+ * Switch reporting on for this process. Unset DSN leaves core's no-op reporter in place, so a
+ * laptop and a CI run pay nothing and page nobody — and the release every event carries is the
+ * build id this boot already computed, never a second identity for the same deploy.
+ */
+export function configureReporting(env: Env, buildId: string): void {
+  const dsn = env[ERROR_DSN_KEY]?.trim();
+  configureErrorReporting({
+    release: buildId,
+    // A malformed DSN throws here, at boot, rather than at the first outage: a monitor that was
+    // never connected looks exactly like an app that never failed.
+    ...(dsn === undefined || dsn.length === 0 ? {} : { reporter: sentryErrorReporter({ dsn }) }),
+  });
+}
+
 export interface ServeOptions {
   readonly root: string;
   readonly env: Env;
@@ -76,6 +134,16 @@ export interface ServeOptions {
   readonly port?: number;
   /** Overrides `METRICS_PORT`, on the same terms. */
   readonly metricsPort?: number;
+  /**
+   * The drivers this deployment supplies instead of the ones the environment would select.
+   *
+   * This field is why `apps/web/server.ts` can stay three lines and still run a custom queue, a
+   * shared ISR store or an app's own middleware. Before it there was nowhere to hand the framework
+   * a driver, so the only way was an ambient setter from an app module — which `loadApp` imports
+   * AFTER `startServices` has captured its own, giving a process that enqueues to one queue and
+   * claims from another. `startRoles` now refuses that split outright.
+   */
+  readonly runtime?: RuntimeOverrides;
 }
 
 export interface ServedApp {
@@ -93,6 +161,8 @@ export interface MigratedApp {
   readonly kind: 'migrated';
   readonly role: 'migrate';
   readonly report: MigrationReport;
+  /** The post-condition: the live schema against the ledger this run just wrote. */
+  readonly drift: DriftReport;
 }
 
 export type StartedApp = ServedApp | MigratedApp;
@@ -106,9 +176,16 @@ export type StartedApp = ServedApp | MigratedApp;
  *
  * It boots the queue, not the whole runtime: this role touches the database and nothing else, and
  * `startQueue` is what installs `db()` for `migrate()` to find.
+ *
+ * The drift check is the post-condition, and it lives here rather than in `cmd-db.ts` for the same
+ * reason the migrator does: it needs the connection this function opened, and a developer and a
+ * release phase must not verify different things. It is **returned, never thrown** — the role's
+ * contract is "apply every migration, then exit", and a schema difference after a clean apply is a
+ * diagnostic, not a failed migration. `x db migrate` is where it is actionable, so `x db migrate`
+ * is what fails on it.
  */
 export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
-  const queue = await startQueue(resolveServices(options.root, options.env));
+  const queue = await startQueue(resolveServices(options.root, options.env), options.runtime);
   try {
     const migrations = await readMigrations(options.root);
     const report = await migrate({
@@ -122,12 +199,43 @@ export async function runMigrations(options: ServeOptions): Promise<MigratedApp>
       available: migrations.length,
       appVersion: report.appVersion,
     });
-    return { kind: 'migrated', role: 'migrate', report };
+    const drift = await checkDrift({ migrations });
+    // Logged with the first difference, not just a count: a release phase's log is the only place
+    // an operator sees this, and "3 differences" names nothing to act on.
+    if (!drift.ok) {
+      logger.warn('ultimate migrate drift', {
+        differences: drift.differences.length,
+        cause: drift.differences[0]?.cause,
+        fix: drift.differences[0]?.fix,
+      });
+    }
+    return { kind: 'migrated', role: 'migrate', report, drift };
   } finally {
     await queue.stop();
   }
 }
 
+/**
+ * Release what a boot acquired before it failed, newest first.
+ *
+ * Every failure here is swallowed, because the step that refused to start is the one worth
+ * reporting — the same rule `startRoles`' own rollback runs by. Without it a throw between
+ * `startServices` and `startRoles` left the Postgres pool, the queue and the OTLP exporter running
+ * in a process whose caller has already given up: `x dev` and the container both retry the boot,
+ * and the second attempt met a `.x/pgdata` the first one still held.
+ */
+export async function releaseBoot(
+  acquired: readonly (() => void | Promise<void>)[],
+): Promise<void> {
+  for (const release of [...acquired].reverse()) {
+    try {
+      await release();
+    } catch {
+      // Deliberately empty: see above.
+    }
+  }
+}
+
 /**
  * Boot order is `x dev`'s, for the reason `x dev` gives: services, then the app's own modules
  * (importing them IS the registration), then the role that serves what they registered. The route
@@ -136,7 +244,29 @@ export async function runMigrations(options: ServeOptions): Promise<MigratedApp>
  */
 export async function serveApp(options: ServeOptions): Promise<ServedApp> {
   const role = options.role ?? roleFromEnv(options.env);
-  const runtime = await startServices(resolveServices(options.root, options.env), options.env);
+  const runtime = await startServices(
+    resolveServices(options.root, options.env),
+    options.env,
+    options.runtime,
+  );
+  // Everything acquired from here down, in order, so a throw anywhere below gives it all back.
+  const acquired: (() => void | Promise<void>)[] = [() => runtime.stop()];
+  try {
+    return await bootRoles({ options, role, runtime, acquired });
+  } catch (error) {
+    await releaseBoot(acquired);
+    throw error;
+  }
+}
+
+/** The half of `serveApp` whose every acquisition is registered for rollback. */
+async function bootRoles(boot: {
+  readonly options: ServeOptions;
+  readonly role: Role;
+  readonly runtime: RunningServices;
+  readonly acquired: (() => void | Promise<void>)[];
+}): Promise<ServedApp> {
+  const { options, role, runtime, acquired } = boot;
   // Importing the app's modules IS the registration: every route, action and job below is
   // whatever this call put in the registries.
   await loadApp(options.root);
@@ -149,18 +279,44 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
     stamped !== undefined && stamped.length > 0
       ? stamped
       : (await appManifest(options.root)).manifest.buildId;
+  // Before the first socket opens: everything above this line fails loudly into the container's
+  // own logs, everything below it is a served request, a claimed job or a routed frame.
+  configureReporting(options.env, buildId);
+  // Beside error reporting, and for the same reason it is here: `OTEL_EXPORTER_OTLP_ENDPOINT` is
+  // in the shipped chart and nothing read it, so every deployment that configured a collector got
+  // an empty dashboard. `x dev` keeps its own recorder — the `/_x` timeline is a different sink
+  // with a different lifetime — so this is the production boot's alone (axiom 6).
+  const stopOtlp = startOtlpExport(options.env);
+  acquired.push(stopOtlp);
+  // Built at boot rather than shipped prebuilt, so the container serves the same chunks `x dev`
+  // does from the same source — the alternative is a second bundler invocation in the image build
+  // whose output nothing compares against the one the dev loop proved.
+  const islands = await buildIslands(options.root);
   const routes: readonly Route[] = [
-    ...listActions().map(toRoute),
-    ...assetRoutes({ root: options.root, storage: runtime.storage }),
-    ...appRoutes({ buildId }),
+    ...apiRoutes(),
+    ...assetRoutes({
+      root: options.root,
+      storage: runtime.storage,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+    }),
+    ...storageRoutes({ storage: runtime.storage }),
+    ...islandRoutes(() => islands),
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => islands.resolverFor(file),
+      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
+      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
+      // the fleet while the other eleven keep serving the page it just invalidated.
+      ...(options.runtime?.isrStore === undefined
+        ? {}
+        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+    }),
   ];
   const port = options.port ?? portFromEnv(options.env);
   // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
   // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
   // still wins — that is the deploy talking.
-  const metricsPort =
-    options.metricsPort ??
-    (port === 0 && options.env['METRICS_PORT'] === undefined ? 0 : metricsPortFromEnv(options.env));
+  const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const running = await startRoles({
     roles: [role],
     port,
@@ -169,8 +325,13 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
     runtime,
     routes,
     env: options.env,
+    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
+    // guarded page with the problem document, rendered as raw JSON in the viewport.
+    signInPath: await loadSignInPath(options.root),
     http: CONTAINER_BINDING,
+    ...(options.runtime === undefined ? {} : { overrides: options.runtime }),
   });
+  acquired.push(() => running.stop());
   return {
     kind: 'served',
     role,
@@ -181,6 +342,9 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
     async stop() {
       await running.stop();
       await runtime.stop();
+      // Last: the exporters outlive the roles they were recording, so the drain's own spans and
+      // the final counter snapshot still have somewhere to go.
+      stopOtlp();
     },
   };
 }
@@ -192,7 +356,15 @@ export async function serveApp(options: ServeOptions): Promise<ServedApp> {
  */
 export async function runRole(options: ServeOptions): Promise<StartedApp> {
   const role = options.role ?? roleFromEnv(options.env);
-  if (role === 'migrate') return runMigrations({ ...options, role });
+  if (role === 'migrate') {
+    const migrated = await runMigrations({ ...options, role });
+    // The release phase has one channel — the exit code — so drift is thrown here rather than
+    // returned. `x db migrate` calls the same `runMigrations` and renders every difference as a
+    // finding before exiting non-zero; a container that logged one and exited 0 would let the
+    // deploy roll on over a schema nobody can reconstruct, which is the failure drift exists for.
+    assertNoDrift(migrated.drift);
+    return migrated;
+  }
   const app = await serveApp({ ...options, role });
   logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
   await holdUntilShutdown('serve', () => app.stop())();

package/src/shell-quote.ts

@@ -0,0 +1,15 @@
+// POSIX single-quoting for a value the CLI pastes into a line a reader runs — a `fix:`, a
+// reproduce command. Its own module, and not `test-shards.ts` where it started, because the
+// subprocess boundary needs it too and `test-shards.ts` imports `exec.ts`: one leaf both can
+// reach is the alternative to an import cycle or a second quoter.
+
+const SHELL_SAFE = /^[\w@%+=:,./-]+$/;
+
+/**
+ * A program name, a `--filter` or a path holding a space, a `$` or a `;` pastes back as two
+ * arguments or as a second command, so an unquoted line runs something other than what it claims.
+ * `'\''` is the only escape a single-quoted string has. A shell-safe value is left alone, so the
+ * common case stays readable.
+ */
+export const quoteArg = (value: string): string =>
+  SHELL_SAFE.test(value) ? value : `'${value.split("'").join("'\\''")}'`;

package/src/source-files.ts

@@ -4,6 +4,10 @@
 
 export const SOURCE_GLOBS = [
   'packages/*/src/**/*.{ts,tsx}',
+  // Three packages carry an `e2e` directory beside `src`. It is shipped source by every rule that
+  // matters here — a 900-line file or an unrunnable `fix:` in one was invisible to `filesize` and
+  // `errors` alike, and `scripts/boundaries.ts` walked past it for the same reason.
+  'packages/*/e2e/**/*.{ts,tsx}',
   'scripts/**/*.{ts,tsx}',
   'site/**/*.{ts,tsx}',
   'app/**/*.{ts,tsx}',

package/src/statement-loop.ts

@@ -0,0 +1,74 @@
+// One repeated statement shape, as every surface renders it. The ledger next door decides that a
+// shape repeated; `@ultimat3/entity` decides which fix it has earned; this file is the one
+// projection all four surfaces read — so `x dev`'s findings, the `/_x` timeline, the browser
+// overlay and the log line can never disagree about a loop's code, its cause or the line that ends it.
+
+import type { StatementLoopFact } from '@ultimat3/admin/dev';
+import { logger } from '@ultimat3/core';
+import { nPlusOne } from '@ultimat3/entity';
+import type { OverlayNotice } from '@ultimat3/http';
+import type { RepeatedStatement } from './dev-n-plus-one';
+import type { Finding } from './output';
+
+/**
+ * The verdict, as an error — built here rather than in the ledger because the count keeps rising
+ * after a shape is promoted: a loop of fifty reads `ran 50 times` when a surface asks, not
+ * `ran 5 times` because that is where the threshold sat. `nPlusOne` is `@ultimat3/entity`'s, and
+ * deliberately: the `fix:` names `preload`, `insertAll` and `updateWhere`, which are that package's
+ * vocabulary and derived from the relations the schema already declared — a line composed here
+ * would be a second answer to "what ends this loop", one the schema never agreed to.
+ */
+export function loopFacts(repeat: RepeatedStatement): StatementLoopFact {
+  const attribution = repeat.attribution;
+  const error = nPlusOne({
+    kind: repeat.kind,
+    subject: repeat.fingerprint,
+    count: repeat.count,
+    entity: attribution?.entity,
+    op: attribution?.op,
+  });
+  return {
+    requestId: repeat.requestId,
+    code: error.code,
+    cause: error.cause,
+    fix: error.fix,
+    docs: error.docs ?? null,
+    subject: repeat.fingerprint,
+    count: repeat.count,
+    sample: repeat.sample,
+  };
+}
+
+/**
+ * The `x dev` half. `at` is the request id and not a file: a loop has no line to open — it is a
+ * page's worth of statements — and the id is what joins this finding to the timeline's own row and
+ * to the log line the same request emitted.
+ */
+export const loopFinding = (facts: StatementLoopFact): Finding => ({
+  code: facts.code,
+  cause: facts.cause,
+  fix: facts.fix,
+  at: facts.requestId,
+  ...(facts.docs === null ? {} : { docs: facts.docs }),
+});
+
+/** The browser half. `exactOptionalPropertyTypes`: an absent doc link is omitted, never `undefined`. */
+export const loopNotice = (facts: StatementLoopFact): OverlayNotice => ({
+  code: facts.code,
+  cause: facts.cause,
+  fix: facts.fix,
+  ...(facts.docs === null ? {} : { docs: facts.docs }),
+});
+
+/**
+ * The log half, emitted once per request per code by the ledger that counts.
+ *
+ * The root logger and not `ctx.logger`, because this runs inside the request's own ALS scope and
+ * core's `setLoggerContextFields` puts `requestId` and `traceId` on every line emitted there — so
+ * the ids ride along without this file reaching for a context it would then have to prove it had.
+ * One line, in the 3-line contract's own order, because a warning an agent has to reassemble from
+ * three log records is a warning it acts on in three passes.
+ */
+export const warnLoop = (facts: StatementLoopFact): void => {
+  logger.warn(`${facts.code}: ${facts.cause} — fix: ${facts.fix}`);
+};

package/src/style-csp.ts

@@ -0,0 +1,18 @@
+// Every inline `<style>` body a served process can put in a document, as the `style-src` sources
+// that admit it. Read from the stylesheet registry at boot rather than checked in as a constant:
+// importing the app's modules IS what fills that registry, so a committed hash would describe a
+// stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
+
+import { cspHashSource } from '@ultimat3/http';
+import { SURFACES, stylesFor } from '@ultimat3/render';
+
+/**
+ * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in
+ * the tag, per surface, so hashing the same call is the only way the two cannot drift. `extra`
+ * carries the documents this package does not render — `/_x`'s shell — because the caller is what
+ * knows which of them it mounted.
+ */
+export function inlineStyleSources(extra: readonly string[] = []): readonly string[] {
+  const bodies = [...SURFACES.map((surface) => stylesFor(surface)), ...extra];
+  return [...new Set(bodies.filter((body) => body.length > 0).map(cspHashSource))].sort();
+}

package/src/sync-authenticator.ts

@@ -0,0 +1,59 @@
+// The app's HTTP authenticator, seen as the `sync` node's. Until this file `sync-node.ts` was
+// handed no `authenticate` by any host, so every socket the framework ever opened carried
+// `actorId: null` — and the channel guard, the live-query gate, the presence entry and the
+// per-tenant subscription cap all decided against an anonymous actor. Realtime was single-tenant
+// by wiring, not by design.
+
+import type { Actor } from '@ultimat3/core';
+import type { HttpConfig } from '@ultimat3/http';
+import {
+  configuredAuthenticator,
+  createRequestContext,
+  defineHttpConfig,
+  UltimateRequest,
+} from '@ultimat3/http';
+import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime';
+
+/**
+ * The upgrade request, dressed as the request an `Authenticator` reads.
+ *
+ * A websocket upgrade IS an HTTP request — same cookies, same `Authorization` header — so the
+ * app's one resolver answers it, and an app does not write a second identity for its sockets.
+ * The limiter is off because nothing in this config path serves a request: it exists so
+ * `ctx.config` is a real `HttpConfig`, and a rate limit resolved here would be a second, unread
+ * declaration of the app's own numbers.
+ */
+function upgradeConfig(buildId: string): HttpConfig {
+  return defineHttpConfig({ buildId, rateLimit: { enabled: false, scope: 'process' } });
+}
+
+/**
+ * What the sync node is given when the app configured an authenticator, and `undefined` when it
+ * did not — which keeps `x dev` anonymous and makes the node log that it is, exactly as
+ * `createSyncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
+ *
+ * The grant carries **no `expiresAt` and no `refresh`**, and that is the honest limit of this
+ * adapter rather than an omission: `configureAuthenticator()` resolves an `Actor` and says nothing
+ * about how long it stays true, so inventing a window here would either close live sockets that
+ * are still authorized or claim a lifetime the app never promised. A deployment whose credential
+ * has a real expiry passes `runtime.syncAuthenticate` and gets re-authorization; the timer for it
+ * already lives in `createSyncNode.start()`.
+ */
+export function syncAuthenticator(buildId: string): SyncAuthenticator | undefined {
+  const authenticate = configuredAuthenticator();
+  if (authenticate === undefined) return undefined;
+  // Once per node, not once per upgrade: resolving a config is pure and a 50k-socket node pays
+  // this per connection otherwise.
+  const config = upgradeConfig(buildId);
+  return async (request: Request): Promise<SyncGrant | null> => {
+    const ctx = createRequestContext({
+      url: new URL(request.url),
+      method: request.method,
+      role: 'sync',
+      config,
+      requestHeaders: request.headers,
+    });
+    const actor: Actor | null = await authenticate(new UltimateRequest(request, ctx), ctx);
+    return actor === null ? null : { actor };
+  };
+}

package/src/templates/action.ts

@@ -5,6 +5,8 @@
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { sliceFoundation } from './slice-foundation';
+import { wrapImport } from './wrap';
 
 const actionSource = (
   name: NameSet,
@@ -18,7 +20,7 @@ import { action, t } from '@ultimat3/action';
 // slice's own files and are shared by every action in it.
 
 import { ${feature.pascal}NotFoundError } from '../errors';
-import { can${feature.pascal}Write, ${feature.camel}Tag } from '../policy';
+${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
 import * as repo from '../repo';
 
 export const ${name.camel} = action({
@@ -28,7 +30,7 @@ export const ${name.camel} = action({
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
   cache: { invalidates: [${feature.camel}Tag] },
-  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  mcp: { expose: true, description: '${name.raw} — edit this description' },
   async handle({ input }) {
     const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
@@ -58,7 +60,7 @@ export const ${name.camel} = mutator({
   input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
-  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  mcp: { expose: true, description: '${name.raw} — edit this description' },
   // tx.table(name) rather than tx.${feature.plural}: the typed accessor exists only once the app
   // augments LocalTables, and generated code cannot assume that has happened yet. The name is the
   // entity's snake_case table, so the local twin and the server row live under one key.
@@ -77,25 +79,6 @@ export const ${name.camel} = mutator({
 });
 `;
 
-const errorsSource = (
-  feature: NameSet,
-): string => `// The ${feature.kebab} feature's X_* codes. Never throw a bare Error: an agent reading the failure
-// needs the code, the cause and the exact command that fixes it.
-
-import { UltimateError } from '@ultimat3/core';
-
-export class ${feature.pascal}NotFoundError extends UltimateError {
-  constructor(input: { id: string }) {
-    super({
-      code: 'X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND',
-      cause: \`no ${feature.kebab} with id \${input.id}\`,
-      fix: 'x db studio to confirm the row exists, or pass an id from the list query',
-      docs: 'https://ultimate.dev/errors/X_NOT_FOUND',
-    });
-  }
-}
-`;
-
 const ID = '00000000-0000-4000-8000-000000000001';
 const ORG = '00000000-0000-4000-8000-000000000002';
 const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
@@ -121,7 +104,9 @@ const actionTest = (
   name: NameSet,
   feature: NameSet,
   isMutator: boolean,
-): string => `import { testActor } from '@ultimat3/policy';
+): string => `// ${name.camel}: its declared shape, the input it refuses, the contract every action owes, and the
+// foreign-org actor it denies before the handler runs. One declaration, every surface.
+import { testActor } from '@ultimat3/policy';
 import { contractTest, expect, unitTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
@@ -148,21 +133,21 @@ unitTest('${name.camel} rejects input that is not a uuid', async () => {
   await expect(target.input).toAcceptInput(input);
 });
 
-contractTest('${name.camel} passes the contract every action owes', async () => {
+contractTest('${name.camel} passes the action contract', async () => {
   // Three assertions the framework makes for any action, without knowing what this one does:
   // garbage input is rejected, an anonymous actor is denied, and the operation reaches the
   // OpenAPI document. \`.contract()\` is the projection; this loop just runs it.
   for (const contract of target.contract()) await contract.run();
 });
 
-contractTest('${name.camel} denies a foreign org before the handler runs', async () => {
+contractTest('${name.camel} denies a foreign org', async () => {
   // \`.as()\` is the one execution path with the actor swapped, so this denial is the same one
   // HTTP, MCP and the job surface would produce — and no repo call happened to produce it.
   const denied = await target.as(outsider, input).catch((error: unknown) => error);
   expect(denied).toBeUltimateError('X_FORBIDDEN');
 });
 
-contractTest('${name.camel} projects one MCP tool and one OpenAPI operation', () => {
+contractTest('${name.camel} projects one tool and one operation', () => {
   // Same policy object on both surfaces — an MCP call cannot reach a different authz path.
   expect(target.tool().policy).toBe(target.policy);
   expect(target.tool().description).not.toBe('');
@@ -180,14 +165,14 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
   return [
+    // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
+    // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
+    // into a slice no `x g resource` had created emitted all three imports and wrote none of them.
+    ...sliceFoundation(target, ['entity', 'policy', 'errors']),
     {
       path: `${dir}/${name.kebab}.ts`,
       contents: isMutator ? mutatorSource(name, feature) : actionSource(name, feature),
     },
     { path: `${dir}/${name.kebab}.test.ts`, contents: actionTest(name, feature, isMutator) },
-    {
-      path: `${target.surfaceDir}/${target.feature}/errors.ts`,
-      contents: errorsSource(feature),
-    },
   ];
 }