@ultimat3/cli 29.3.2 → 30.0.0

package/src/static-images.ts

@@ -0,0 +1,115 @@
+// Single responsibility: the image variants a static export's documents promise, as FILES. While
+// the export renders, `responsiveImage` asks this module for each variant's URL — `/_img/<source
+// hash>-<width>.<ext>` — and after it, every URL an exported document names is decoded, resized
+// and written through core's pipeline. A dumb file server then answers `image/webp` for a webp.
+
+// why: Bun exposes no path-join primitive, and every variant path is relative to the export root.
+import { join } from 'node:path';
+import { canEncode, imageUnsupported, sniffImageFormat, transformImageBytes } from '@ultimat3/core';
+import { contentHash } from '@ultimat3/render/server';
+import type { StaticImageRequest } from '@ultimat3/seo';
+import { ImageSourceUnreadableError } from './static-capture-errors';
+
+/** Where every variant lands, and the prefix a document names it by. */
+export const STATIC_IMAGE_DIR = '_img';
+
+/** The source encodings an export can read and resize — core's decoders, minus SVG markup. */
+const SOURCE_GLOB = new Bun.Glob('**/*.{png,jpg,jpeg,webp,gif}');
+
+interface Source {
+  readonly file: string;
+  readonly hash: string;
+  /** What the variant is written as when the document named no format. */
+  readonly ownFormat: 'png' | 'jpeg' | 'webp';
+}
+
+interface Variant {
+  readonly src: string;
+  readonly width: number;
+  /** `undefined` for a source the export does not hold: the URL is recorded, never written. */
+  readonly source: Source | undefined;
+  readonly format: string;
+}
+
+export interface StaticImages {
+  /** The URL builder `@ultimat3/seo`'s static seam calls. Never throws: refusals wait for `write`. */
+  imageUrl(request: StaticImageRequest): string;
+  /**
+   * Writes every recorded variant an exported document names, and answers their site paths. A
+   * named variant of a `src` the export does not hold is `X_IMAGE_SOURCE_UNREADABLE`; one in a
+   * format the pipeline cannot encode (`avif`) is core's `X_IMAGE_UNSUPPORTED` — a build error,
+   * never a dead `<source>`. URLs only weighed documents named are never written.
+   */
+  write(documents: readonly string[]): Promise<readonly string[]>;
+}
+
+const EXTENSION: ReadonlyMap<string, string> = new Map([
+  ['png', 'png'],
+  ['jpeg', 'jpg'],
+  ['webp', 'webp'],
+  ['avif', 'avif'],
+]);
+
+/** The site path a `src` names, without a query or fragment — the file it is in the export. */
+const pathOf = (src: string): string => src.replace(/[?#].*$/, '');
+
+/** Index the images the export already holds (`asset()` copies, icons), by their site path. */
+async function indexSources(out: string): Promise<ReadonlyMap<string, Source>> {
+  const sources = new Map<string, Source>();
+  for await (const relative of SOURCE_GLOB.scan({ cwd: out, onlyFiles: true })) {
+    const site = `/${relative.split('\\').join('/')}`;
+    if (site.startsWith(`/${STATIC_IMAGE_DIR}/`)) continue;
+    const file = join(out, relative);
+    const bytes = await Bun.file(file).bytes();
+    const format = sniffImageFormat(bytes);
+    if (format === null) continue;
+    sources.set(site, {
+      file,
+      hash: contentHash(bytes),
+      ownFormat: format === 'jpeg' || format === 'webp' ? format : 'png',
+    });
+  }
+  return sources;
+}
+
+export async function staticImages(out: string): Promise<StaticImages> {
+  const sources = await indexSources(out);
+  const variants = new Map<string, Variant>();
+  return {
+    imageUrl({ src, width, format }) {
+      const source = sources.get(pathOf(src));
+      const resolved = format ?? source?.ownFormat ?? 'png';
+      // A src the export lacks still gets a stable URL, so `write` can tell which document named it.
+      const stem = source === undefined ? `missing-${contentHash(src)}` : source.hash;
+      const url = `/${STATIC_IMAGE_DIR}/${stem}-${String(width)}.${EXTENSION.get(resolved) ?? resolved}`;
+      variants.set(url, { src, width, source, format: resolved });
+      return url;
+    },
+    async write(documents) {
+      const named = [...variants].filter(([url]) => documents.some((html) => html.includes(url)));
+      const missing = [
+        ...new Set(named.filter(([, one]) => one.source === undefined).map(([, one]) => one.src)),
+      ];
+      if (missing.length > 0) throw new ImageSourceUnreadableError(missing);
+      const refused = named.find(([, one]) => !canEncode(one.format));
+      if (refused !== undefined) {
+        throw imageUnsupported(
+          `a static page asked responsiveImage() for ${refused[1].format}, which the build pipeline cannot encode, so its <source> would name a file no build writes`,
+          "responsiveImage(input, { formats: ['webp'] })   # drop avif from a static route; a CDN driver serves it at runtime",
+          { format: refused[1].format, src: refused[1].src },
+        );
+      }
+      const written: string[] = [];
+      for (const [url, one] of named) {
+        if (one.source === undefined || !canEncode(one.format)) continue;
+        const bytes = await transformImageBytes(await Bun.file(one.source.file).bytes(), {
+          width: one.width,
+          format: one.format,
+        });
+        await Bun.write(join(out, url.slice(1)), bytes);
+        written.push(url);
+      }
+      return written;
+    },
+  };
+}

package/src/stream-hole-scope.ts

@@ -0,0 +1,55 @@
+// What is ambient inside a `<Hole>` of a `stream` page: the request's context, with the hole's own
+// signal (its deadline, the client's disconnect, the document's close) in place of the request's,
+// and the response headers sealed — they left with the first flush, so a write there was a cookie
+// or a `Location` nobody would ever receive.
+
+import { runWithContext, tryUseContext, UltimateError } from '@ultimat3/core';
+import type { HoleEnter } from '@ultimat3/render/server';
+
+const FIX =
+  'load: async () => { setCookie(name, value); return data; },   // in defineRoute, never inside a Hole';
+
+/** A response header or redirect written under a hole, after the status and headers were sent. */
+export class StreamAlreadyFlushedError extends UltimateError {
+  constructor(what: string) {
+    super({
+      code: 'X_STREAM_ALREADY_FLUSHED',
+      cause: `${what} ran inside a <Hole> on a render: 'stream' page, after the status and headers were sent with the first flush, so the browser would never receive it`,
+      fix: FIX,
+    });
+  }
+}
+
+/** Every write to the response headers refuses; every read answers what was sent. */
+const sealedHeaders = (headers: Headers): Headers =>
+  new Proxy(headers, {
+    get(target, key) {
+      if (key === 'append' || key === 'set' || key === 'delete') {
+        return (name: string) => {
+          throw new StreamAlreadyFlushedError(`writing the ${name} response header (setCookie)`);
+        };
+      }
+      const value: unknown = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+
+/**
+ * The scope a hole's children run in. Forwarded rather than rebuilt, as `runToCompletion` forwards a
+ * request's context: a rebuilt `ctxOf` drops the http fields, and `useRequestHeader()` inside a hole
+ * would then refuse. Services the request built keep the request's signal; the ambient one is the hole's.
+ */
+export const enterHole: HoleEnter = (signal, run) => {
+  const parent = tryUseContext();
+  if (parent === undefined) return run();
+  const sealed = sealedHeaders((parent as { readonly headers?: Headers }).headers ?? new Headers());
+  const scope = new Proxy(parent, {
+    get: (target, key) =>
+      key === 'signal' ? signal : key === 'headers' ? sealed : Reflect.get(target, key),
+    set: (target, key, value) => {
+      if (key === 'redirect') throw new StreamAlreadyFlushedError('setRedirect()');
+      return Reflect.set(target, key, value);
+    },
+  });
+  return runWithContext(scope, run);
+};

package/src/style-bundle.ts

@@ -3,7 +3,7 @@
 // asset over (`island-bundle.ts`), because the two answer the same question — "what does this
 // document make the browser fetch, and can it keep it?" — and one mechanism is the whole point.
 //
-// Why it stopped being an inline `<style>`: measured against ai-maxxing on 2026-09-06, every
+// Why it stopped being an inline `<style>`: measured against one adopter's app on 2026-09-06, every
 // `app/` document carried one 156,738-byte block — 1,336 rules from 406 module sources, byte
 // identical across `/`, `/fleet`, `/fleet/[host]` and the session page — inside a response the
 // pipeline sends `Cache-Control: private, no-store`. 92% of the dashboard document and 89% of the

package/src/style-routes.ts

@@ -4,7 +4,7 @@
 // image.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE, textResponse } from '@ultimat3/http';
 import type { StyleBundle } from './style-bundle';
 import { STYLE_BASE_PATH } from './style-bundle';
 
@@ -49,7 +49,8 @@ export function styleRoutes(source: StyleSource): readonly Route[] {
           return applyCacheHeaders(missing, NO_STORE);
         }
         return applyCacheHeaders(
-          new Response(chunk.css, { headers: { 'content-type': 'text/css; charset=utf-8' } }),
+          // `textResponse` for the length it declares: `compress` reads nothing undeclared.
+          textResponse(chunk.css, { headers: { 'content-type': 'text/css; charset=utf-8' } }),
           { mode: 'immutable' },
         );
       },

package/src/sw-precache-plan.ts

@@ -49,7 +49,7 @@ const spell = (path: string, locale: string, locales: RoutedLocales): string =>
  * The route table, as the service worker sees it — once per routed locale. The server strips a
  * `/en/` prefix before it matches (`@ultimat3/http`'s `locale-prefix.ts`), and the worker matches
  * pathnames: with one spelling per route, no `/en/…` URL had a rule, so the English site was never
- * cached and never offline (notificado.co, 22.3.2). Only the fields a browser can act on cross,
+ * cached and never offline (one adopter, 22.3.2). Only the fields a browser can act on cross,
  * plus — for a spelling this build rendered — the content hash and byte count of its document.
  */
 export function pwaRoutes(
@@ -106,7 +106,7 @@ export interface PrecacheAssetInput {
 /**
  * The island chunks a PRECACHED page boots, every surface stylesheet and every framework script.
  * Every island in the app was precached, so a first anonymous visit to a marketing page downloaded
- * the admin, KYC and payment islands too — 43 chunks, ~1 MB on notificado.co (22.3.2). The rest are
+ * the admin, KYC and payment islands too — 43 chunks, ~1 MB on one adopter (22.3.2). The rest are
  * cached the first time a page asks for one (`ISLAND_BASE_PATH` is a runtime asset prefix).
  *
  * Two readers of "which islands", because only one of them exists per build: the static export

package/src/sw-routes.ts

@@ -3,7 +3,7 @@
 // both artifacts as files and mounts nothing, and it must not have to import a route table to do it.
 
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders } from '@ultimat3/http';
+import { applyCacheHeaders, textResponse } from '@ultimat3/http';
 import { revalidatedResponse } from './revalidated-response';
 import type { ServiceWorkerArtifacts } from './sw-artifacts';
 import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts';
@@ -24,7 +24,7 @@ export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly
     meta: { name: 'pwa.serviceWorker', auth: 'public' },
     handler: () =>
       applyCacheHeaders(
-        new Response(artifacts.source, {
+        textResponse(artifacts.source, {
           headers: {
             'content-type': 'text/javascript; charset=utf-8',
             // Without it the browser refuses to let a worker served from `/` control `/`, which

package/src/templates/action-tests.ts

@@ -0,0 +1,306 @@
+// The tests `x g action` and `x g mutator` write beside the declaration: a `unit` file for its shape
+// and handler, a `contract` file for its projections. Split from `action.ts` because the gate types
+// a test by its filename, and the two together passed that file's ceiling.
+
+import { sortedImports } from './imports';
+import type { NameSet } from './naming';
+
+/** The code the slice's `errors.ts` declares for a missing row. */
+const notFoundCode = (feature: NameSet): string =>
+  `X_${feature.kebab.toUpperCase().split('-').join('_')}_NOT_FOUND`;
+
+const ID = '00000000-0000-4000-8000-000000000001';
+const ORG = '00000000-0000-4000-8000-000000000002';
+const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
+
+/** The declaration-shape assertions that differ between the two primitives. */
+const shapeTest = (name: NameSet, feature: NameSet, isMutator: boolean): string =>
+  isMutator
+    ? `unitTest('${name.camel} projects both halves and a conflict strategy', () => {
+  // The projected names mirror the declaration: local() optimistic, server() authoritative.
+  // server() routes through the same invoke() core as every other surface, so it cannot skip
+  // the input parse, the policy or the output parse.
+  expect(target.describeMutator().kind).toBe('mutator');
+  expect(target.conflict).toBe('server-wins');
+  expect(typeof target.local).toBe('function');
+  expect(typeof target.server).toBe('function');
+});`
+    : `unitTest('${name.camel} is a declared action that invalidates its slice', () => {
+  expect(target.kind).toBe('action');
+  expect(target.describe().name).toBe('${name.camel}');
+  // Without \`cache: { invalidates }\` every cached read of this slice serves the row as it was.
+  expect(target.describe().invalidates).toContain(${feature.camel}Tag.entity);
+});`;
+
+/**
+ * The contract test's preamble. Everything but the target rides only where it is USED: the
+ * scaffolded app lints with `noUnusedVariables: error`, so an actor or an input the file never
+ * reads would be a lint failure in code nobody typed — which is what a hand-written policy, whose
+ * tenancy this generator asserts nothing about, was handed.
+ */
+const preamble = (
+  name: NameSet,
+  feature: NameSet,
+  isMutator: boolean,
+  wrappers: string,
+  outsider: boolean,
+  /** `testActor` is imported for the outsider, or for a contract suite's exercise actor. */
+  importsActor = outsider,
+): string => `${importsActor ? "import { testActor } from '@ultimat3/policy';\n" : ''}import { ${wrappers} } from '@ultimat3/testing';
+import { ${name.camel} } from './${name.kebab}';
+${
+  outsider
+    ? `
+const id = '${ID}';
+const orgId = '${ORG}';
+const input = { id, orgId${isMutator ? ", title: 'a title'" : ''} };
+`
+    : ''
+}
+// Named here because every projection needs a stable name and this file does not boot the app.
+// At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
+// object, so each projection of it works there with nothing to remember.
+const target = ${name.camel}.named('${name.camel}');
+${
+  outsider
+    ? `
+// Holds the grant, wrong org. That is the interesting actor: a denial here is the predicate
+// deciding, not the permission check, so this test fails if the tenancy rule is ever dropped.
+const outsider = testActor('outsider', {
+  orgId: '${OTHER_ORG}',
+  permissions: ['${feature.kebab}:write'],
+}).actor;
+`
+    : ''
+}`;
+
+/** What the unit test may do with the slice the declaration lives in. */
+export interface HandlerShape {
+  readonly isMutator: boolean;
+  /** The handler reads a row by id and throws `<Feature>NotFoundError` when there is none. */
+  readonly lookup: boolean;
+  /** The slice still takes the row `x g entity` scaffolds, so the test may store one. */
+  readonly storesRow: boolean;
+  readonly dbModule: string;
+  /**
+   * The permission the writer is granted — `<feature>:write` for the policy this generator wrote,
+   * the one literal `can('<perm>')` of a handwritten one, or `undefined` when that policy's grant
+   * cannot be read, and then no assertion depends on it.
+   */
+  readonly grant: string | undefined;
+  /** The input and the writer name an org: the slice is tenant-scoped, or its policy reads one. */
+  readonly org: boolean;
+}
+
+/**
+ * The optimistic half, run against the client store `@ultimat3/testing` ships. A twin is replayed
+ * on every rebase, so the two facts worth failing on are the row one application leaves and that a
+ * second leaves the same one — and that a row the store never held is not invented.
+ */
+const localTwinTests = (): string => `
+unitTest('the local twin marks the row pending, and a replay lands in the same place', () => {
+  const store = memoryLocalTx({ [TABLE]: { [id]: { id, title: 'before', pending: false } } });
+  target.local(store.tx, input);
+  const once = store.rows(TABLE);
+  expect(once).toEqual({ [id]: { id, title: 'a title', pending: true } });
+  // A rebase replays the queued write: twice through must equal once through.
+  target.local(store.tx, input);
+  expect(store.rows(TABLE)).toEqual(once);
+});
+
+unitTest('the local twin invents no row the store never held', () => {
+  const store = memoryLocalTx();
+  target.local(store.tx, input);
+  expect(store.rows(TABLE)).toEqual({});
+});
+`;
+
+/** The authoritative half's cases, refusal first, in the shape the slice earns. */
+const handlerTests = (feature: NameSet, shape: HandlerShape): string => {
+  if (shape.grant === undefined) {
+    return `
+// No handler assertion: ../policy.ts is hand-written and its grant is not one literal can('…'),
+// so which actor reaches the handler is the author's to state — add that test here.
+`;
+  }
+  const answer = shape.isMutator ? "{ id, title: 'a title' }" : '{ id }';
+  if (!shape.lookup) {
+    return `
+unitTest('an actor without the grant is refused before the handler runs', async () => {
+  const stranger = testActor('stranger'${shape.org ? ', { orgId }' : ''}).actor;
+  const refused = await target.as(stranger, input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('X_FORBIDDEN');
+});
+
+unitTest('the handler answers a writer${shape.org ? ' in the org' : ''}', async () => {
+  expect(await target.as(writer, input)).toEqual(${answer});
+});
+`;
+  }
+  const found = shape.isMutator
+    ? "{ id: row.id, title: 'a title' }"
+    : "{ id: row.id, title: 'kept' }";
+  const call = shape.isMutator
+    ? "{ id: row.id, orgId, title: 'a title' }"
+    : '{ id: row.id, orgId }';
+  return `
+unitTest('the handler refuses an id nothing holds', async () => {
+  const refused = await target.as(writer, input).catch((error: unknown) => error);
+  expect(refused).toBeUltimateError('${notFoundCode(feature)}');
+});
+${
+  shape.storesRow
+    ? `
+unitTest('the handler answers the row it found', async () => {
+  const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
+  const row = await runWithContext(ctxOf({ actor: writer }), () => repo.insert(draft));
+  const answer = await target.as(writer, ${call});
+  expect(answer).toEqual(${found});
+});
+
+unitTest('the handler reads its row in one statement', async ({ statements }) => {
+  const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
+  const row = await runWithContext(ctxOf({ actor: writer }), () => repo.insert(draft));
+  const before = statements.count();
+  await target.as(writer, ${call});
+  // Its own lookup and nothing else, on this driver as on Postgres: a read added per row is red.
+  expect(statements.count() - before).toBe(1);
+});
+`
+    : ''
+}`;
+};
+
+/**
+ * The unit test: the declaration's shape, the input it refuses, and the HANDLER — run through
+ * `.as()`, the one execution path, against the in-memory driver. A mutator's local twin runs
+ * against `memoryLocalTx`. The contract projections are next door, in their own suite.
+ *
+ * A row is stored only in a slice whose row this generator can spell (`sliceTakesScaffoldRow`): a
+ * slice an author reshaped has its own columns, and a test that inserted `{ title, price }` into
+ * it would be a guess about someone else's table.
+ */
+export const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): string => {
+  const known = shape.grant !== undefined;
+  const stores = known && shape.lookup && shape.storesRow;
+  const testing = [
+    ...(stores ? ['afterEach'] : []),
+    'expect',
+    ...(shape.isMutator ? ['memoryLocalTx'] : []),
+    'unitTest',
+  ].join(', ');
+  return `// ${name.camel}: its declared shape, the input it refuses, and what its handler answers — in
+// process, so all three belong to the \`unit\` step. The contract projections are next door.
+${sortedImports([
+  ...(stores ? ["import { ctxOf, runWithContext } from '@ultimat3/core';"] : []),
+  ...(known ? ["import { testActor } from '@ultimat3/policy';"] : []),
+  `import { ${testing} } from '@ultimat3/testing';`,
+  ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
+])}${shape.isMutator ? '' : `\nimport { ${feature.camel}Tag } from '../policy';`}${stores ? "\nimport * as repo from '../repo';" : ''}
+import { ${name.camel} } from './${name.kebab}';
+
+const id = '${ID}';
+${shape.org ? `const orgId = '${ORG}';\n` : ''}const input = { id${shape.org ? ', orgId' : ''}${shape.isMutator ? ", title: 'a title'" : ''} };
+${shape.isMutator ? `\n// The client store's table: the entity's own, so the twin and the server row share one key.\nconst TABLE = '${feature.table}';\n` : ''}
+// Named here because every projection needs a stable name and this file does not boot the app.
+// At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
+// object, so each projection of it works there with nothing to remember.
+const target = ${name.camel}.named('${name.camel}');
+${
+  known
+    ? `
+// Holds the grant${shape.org ? ' in the org the input names' : ''}: past the policy, so what answers is the handler.
+const grant = ['${shape.grant}'];
+const writer = testActor('writer', { ${shape.org ? 'orgId, ' : ''}permissions: grant }).actor;
+`
+    : ''
+}${
+  stores
+    ? `
+// One store per process: without this, one test's rows are the next test's fixtures.
+afterEach(() => {
+  driver.reset?.();
+});
+`
+    : ''
+}
+${shapeTest(name, feature, shape.isMutator)}
+
+unitTest('${name.camel} rejects input that is not a uuid', async () => {
+  await expect(target.input).toRejectInput({ ...input, id: 'not-a-uuid' });
+  await expect(target.input).toAcceptInput(input);
+});
+${shape.isMutator ? localTwinTests() : ''}${handlerTests(feature, shape)}`;
+};
+
+/**
+ * Who the generated-input runs act as: an actor holding the slice's grant — `<feature>:write` for
+ * the policy this generator wrote, the one literal `can('<perm>')` of a handwritten one — in the
+ * input's org when the rule compares orgs. A grant that cannot be read is the author's to name,
+ * so those runs are skipped out loud instead.
+ */
+const exerciseActor = (grant: string | undefined, orgRule: boolean): string =>
+  grant === undefined
+    ? ''
+    : `
+// Holds the grant${orgRule ? ', in the org every generated input is bound to' : ''}: the actor the handler runs as when \`.contract()\`
+// calls it with generated legal input.
+const member = testActor('member', {${orgRule ? '\n  orgId,' : ''}
+  permissions: ['${grant}'],
+}).actor;
+`;
+
+/** The `.contract()` argument: the actor and, under an org rule, the org every draw is bound to. */
+const exerciseOption = (grant: string | undefined, orgRule: boolean): string => {
+  if (grant === undefined) {
+    return "{\n    exercise: { off: '../policy.ts names no one grant: pass { actor } holding what it checks' },\n  }";
+  }
+  return orgRule
+    ? '{\n    exercise: { actor: member, input: (drawn) => ({ ...(drawn as object), orgId }) },\n  }'
+    : '{ exercise: { actor: member } }';
+};
+
+export const actionContractTest = (
+  name: NameSet,
+  feature: NameSet,
+  isMutator: boolean,
+  /** The slice's policy is the one this generator wrote, so its tenancy rule is known. */
+  scaffoldPolicy = true,
+  /** That policy holds an org rule: false for a slice whose entity names no tenant. */
+  orgRule = scaffoldPolicy,
+  /** The permission the exercise actor holds; `undefined` when the policy's grant cannot be read. */
+  grant: string | undefined = scaffoldPolicy ? `${feature.kebab}:write` : undefined,
+): string => `// ${name.camel}: the contract every action owes, and the foreign-org actor it denies before the
+// handler runs. One declaration, every surface.
+${preamble(name, feature, isMutator, 'contractTest, expect', orgRule, orgRule || grant !== undefined)}${exerciseActor(grant, orgRule)}
+contractTest('${name.camel} passes the action contract', async () => {
+  // Four assertions the framework makes for any action, without knowing what this one does:
+  // garbage input is rejected, an anonymous actor is denied, the operation reaches the OpenAPI
+  // document, and the handler survives 16 generated legal inputs, each rolled back.
+  for (const contract of target.contract(${exerciseOption(grant, orgRule)})) {
+    await contract.run();
+  }
+});
+
+${
+  orgRule
+    ? `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');
+});
+`
+    : scaffoldPolicy
+      ? `// No foreign-org assertion: this slice's entity names no tenant, so there is no other org to deny.
+`
+      : `// No foreign-org assertion: ../policy.ts is hand-written, and whether it checks the org is the
+// author's rule to state — add that test here.
+`
+}
+// No MCP tool until it is described: a placeholder description misleads the agent reading it.
+contractTest('${name.camel} projects one operation and no tool', () => {
+  expect(target.openapi().operationId).toBe('${name.camel}');
+  expect(target.mcp?.expose ?? false).toBe(false);
+});
+`;