@ultimat3/cli 21.0.0 → 22.1.0

package/src/templates/scaffold-helm-templates.ts

@@ -12,8 +12,18 @@ const helpers = (
 {{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
 {{- end -}}
 
+{{/*
+helm create's rule: a release whose name already contains the chart's is the full name on its own.
+x deploy --method helm names the release after the app, which IS the chart name, so without it
+every object would be ${app.kebab}-${app.kebab}-web.
+*/}}
 {{- define "${app.kebab}.fullname" -}}
-{{- printf "%s-%s" .Release.Name (include "${app.kebab}.name" .) | trunc 63 | trimSuffix "-" -}}
+{{- $name := include "${app.kebab}.name" . -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
 {{- end -}}
 
 {{/*
@@ -92,15 +102,38 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
   HTTP and get both. worker, scheduler and replicator open no HTTP socket at all — the scrape
   listener is their only port — so they take liveness on it and NO readiness: nothing routes to
   them, and a readiness flap would drop the pod out of the Service and so out of the scrape.
+
+  Every one of them takes a startupProbe too, because no listener opens early: the server builds
+  the app's islands before any role binds a port, and a liveness probe counting from container
+  start restarts a pod that is merely booting. 30 x 5s = 150s of boot, then the ordinary checks.
   */}}
   {{- if $cfg.port }}
+  startupProbe:
+    httpGet: { path: /healthz, port: http }
+    periodSeconds: 5
+    failureThreshold: 30
   readinessProbe:
     httpGet: { path: /readyz, port: http }
     periodSeconds: 5
   livenessProbe:
     httpGet: { path: /healthz, port: http }
     periodSeconds: 15
+  {{- /*
+  Holds SIGTERM back while the pod is already out of its Service's endpoints, so a proxy that has
+  not caught up still reaches a listener that answers. lifecycle.preStop.sleep exists from
+  Kubernetes 1.30 and this chart's floor is 1.27, so it renders only where the API server knows it;
+  below that the framework's own readiness grace (/readyz at 503, listener still open) covers it.
+  */}}
+  {{- if semverCompare ">=1.30-0" $root.Capabilities.KubeVersion.Version }}
+  lifecycle:
+    preStop:
+      sleep: { seconds: {{ $root.Values.drain.preStopSleepSeconds | int }} }
+  {{- end }}
   {{- else if $scraped }}
+  startupProbe:
+    httpGet: { path: /metrics, port: metrics }
+    periodSeconds: 5
+    failureThreshold: 30
   livenessProbe:
     httpGet: { path: /metrics, port: metrics }
     periodSeconds: 15
@@ -114,8 +147,9 @@ nobody bound. Derived here rather than stated twice in values.yaml, where the tw
 `;
 
 const deployments = (app: NameSet): string => `{{/*
-One Deployment per enabled role, from one image. terminationGracePeriodSeconds matches the
-framework's SIGTERM drain: in-flight requests, open websockets and running job steps finish.
+One Deployment per enabled role, from one image. terminationGracePeriodSeconds covers the preStop
+sleep, the framework's readiness grace and its SIGTERM drain: in-flight requests, open websockets
+and running job steps finish.
 */}}
 {{- range $role, $cfg := .Values.roles }}
 {{- if $cfg.enabled }}
@@ -151,9 +185,11 @@ spec:
       code that reaches the filesystem, which for a web role is one path traversal. */}}
       automountServiceAccountToken: false
       securityContext: {{- toYaml $.Values.podSecurityContext | nindent 8 }}
-      {{/* At least the framework's drain deadline (25s by default), which is what
-      X_SHUTDOWN_TIMEOUT's fix line tells an operator. Raise this WITH configureLifecycle({
-      deadlineMs }), never instead of it: the drain abandons its hooks at its own deadline. */}}
+      {{/* Spent in order: the preStop sleep (drain.preStopSleepSeconds, 1.30+), the framework's
+      readiness grace (5s outside local environments) and its drain deadline (25s, which is what
+      X_SHUTDOWN_TIMEOUT's fix line names) — 35s, so 45 leaves 10s before SIGKILL. Raise this WITH
+      configureLifecycle({ deadlineMs, readinessGraceMs }), never instead of it: the drain
+      abandons its hooks at its own deadline. */}}
       terminationGracePeriodSeconds: 45
       containers:
         {{- include "${app.kebab}.container" (dict "role" $role "cfg" $cfg "root" $) | nindent 8 }}
@@ -259,12 +295,16 @@ spec:
         paths:
           {{- /* The path the sync node actually serves. Routing /_sync instead sends every
           websocket to the web role, which answers no upgrade. */}}
+          {{- /* Only when the sync role runs: a rule naming a Service the chart did not render is an
+          ingress that 503s every websocket instead of letting it reach nothing at all. */}}
+          {{- if .Values.roles.sync.enabled }}
           - path: /_x/sync
             pathType: Prefix
             backend:
               service:
                 name: {{ include "${app.kebab}.fullname" . }}-sync
                 port: { name: http }
+          {{- end }}
           - path: /
             pathType: Prefix
             backend:
@@ -277,8 +317,13 @@ spec:
 const hpa = (app: NameSet): string => `{{/*
 Per-role autoscalers, off until you turn one on. Each role scales on the signal that predicts ITS
 saturation — CPU is a lagging proxy for all three and scales the wrong thing at the wrong time.
-A Pods metric needs a metrics adapter in the cluster; without one the HPA reads <unknown> and
+Either metric type needs a metrics adapter in the cluster; without one the HPA reads <unknown> and
 holds at minReplicas, which is why these are opt-in rather than a default nobody wired.
+
+autoscaling.type says whose number it is. Pods (the default) is a per-pod series — rps, open
+sockets — averaged across pods. External is ONE series for the whole role, divided by the replica
+count: queue_depth is that shape, because every worker publishes the same global backlog, and read
+as Pods it asked for N times the workers the queue needed. Any other type fails the render.
 */}}
 {{- range $role, $cfg := .Values.roles }}
 {{- if and $cfg.enabled $cfg.autoscaling $cfg.autoscaling.enabled }}
@@ -297,7 +342,20 @@ spec:
     name: {{ include "${app.kebab}.fullname" $ }}-{{ $role }}
   minReplicas: {{ $cfg.autoscaling.minReplicas }}
   maxReplicas: {{ $cfg.autoscaling.maxReplicas }}
+  {{- $type := default "Pods" $cfg.autoscaling.type }}
+  {{- if not (has $type (list "Pods" "External")) }}
+  {{- fail (printf "roles.%s.autoscaling.type is %q — set it to Pods (a per-pod series) or External (one series for the whole role, e.g. queue_depth)" $role $type) }}
+  {{- end }}
   metrics:
+    {{- if eq $type "External" }}
+    - type: External
+      external:
+        metric:
+          name: {{ $cfg.autoscaling.metric }}
+        target:
+          type: AverageValue
+          averageValue: {{ $cfg.autoscaling.targetAverageValue | quote }}
+    {{- else }}
     - type: Pods
       pods:
         metric:
@@ -305,6 +363,7 @@ spec:
         target:
           type: AverageValue
           averageValue: {{ $cfg.autoscaling.targetAverageValue | quote }}
+    {{- end }}
   behavior:
     scaleUp:
       stabilizationWindowSeconds: 30

package/src/templates/scaffold-helm.ts

@@ -34,7 +34,7 @@ image:
 env:
   NODE_ENV: production
 
-existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET
+existingSecret: ${app.kebab}-secrets   # DATABASE_URL, NATS_URL, S3_*, AUTH_SECRET, ULTIMATE_CURSOR_SECRET
 
 # The scrape listener every serving role opens, on its own port and never the app's: the ingress
 # routes / to web, so /metrics beside /healthz on 3000 is /metrics on the internet. This is
@@ -51,6 +51,12 @@ securityContext:
   readOnlyRootFilesystem: true
   capabilities: { drop: [ALL] }
 
+# The stop sequence: out of the Service, then this preStop sleep (Kubernetes 1.30+ only), then
+# SIGTERM, then the framework's readiness grace and drain. terminationGracePeriodSeconds in
+# templates/deployments.yaml is sized to all three, so move them together.
+drain:
+  preStopSleepSeconds: 5
+
 # The release phase. Runs to completion before any serving role starts.
 migrate:
   enabled: true
@@ -63,8 +69,10 @@ migrate:
 # PORT: they differ for sync, which binds PORT + 1, and the chart derives the env from this number
 # so there is only ever one to move.
 #
-# Autoscaling is off until you wire a metrics adapter — each \`metric\` below is a Pods metric the
-# role exports, and an HPA with no adapter behind it reads <unknown> and holds at minReplicas.
+# Autoscaling is off until you wire a metrics adapter — each \`metric\` below is a series the role
+# exports, and an HPA with no adapter behind it reads <unknown> and holds at minReplicas.
+# \`type\` is Pods (the default: a per-pod series averaged across pods) or External (one series for
+# the whole role, divided by the replica count).
 roles:
   web:
     enabled: true
@@ -81,7 +89,14 @@ roles:
       targetAverageValue: "50"
 
   sync:
-    enabled: true
+    # OFF by default. A sync pod on a real database hears committed changes only from a replicator
+    # it can reach, and a fresh deploy has none: booted anyway it is refused (X_REALTIME_TOPOLOGY).
+    # To turn live queries and channels on: declare realtime: { enabled: true, transport: 'nats',
+    # urlEnv: 'NATS_URL' } in app.config.ts (a NATS_URL under transport 'memory' is refused, and
+    # 'nats' without it is too); run NATS and set the SAME NATS_URL for web, sync and the
+    # replicator; enable exactly one replicator (below) against a Postgres started with
+    # wal_level=logical (the replicator creates its publication at boot) and a role with REPLICATION on a cluster dedicated to this app; then set this to true.
+    enabled: false
     replicas: 2
     port: 3001
     resources:
@@ -104,6 +119,10 @@ roles:
       enabled: false
       minReplicas: 1
       maxReplicas: 50
+      # External: every worker publishes the SAME global backlog, so averaged as a Pods metric it
+      # asked for N times the workers the queue needed. Expose it from your adapter deduplicated —
+      # max(queue_depth), never sum, which would multiply it by the pod count again.
+      type: External
       metric: queue_depth       # jobs waiting, exported by the worker role
       targetAverageValue: "100"
 
@@ -112,9 +131,12 @@ roles:
     # Fixed 1, and a second replica is safe but pointless: leadership is an expiring row in
     # x_scheduler_leader, so the extra pod stands by.
     replicas: 1
+    # 512Mi, not 256Mi: a scaffolded app measured ~325 MiB at boot as ROLE=scheduler (2026-09-23),
+    # when every role still built the app's islands first; at 256Mi the pod was OOMKilled on every
+    # boot. Only web builds islands now, so the peak is lower but unmeasured, and the limit stays.
     resources:
       requests: { cpu: 50m, memory: 128Mi }
-      limits: { memory: 256Mi }
+      limits: { memory: 512Mi }
 
   replicator:
     enabled: false              # exactly one per database; enable when the change feed is in use

package/src/templates/scaffold-i18n.ts

@@ -28,27 +28,31 @@ const i18nPackage = (app: NameSet, version: string): string => `{
 `;
 
 /**
- * `en` first, then every other locale alphabetically — a stable order so a diff shows only the
- * locale a run actually added, never a reshuffle. `en` is always included: `default: 'en'` below
- * requires it to be a registered locale, and every real catalog set already has one from `x new`
- * scaffold time.
+ * The default locale first, then every other one alphabetically — a stable order so a diff shows
+ * only the locale a run actually added. The default is `en` when the set holds it (and when the set
+ * is empty, which is `x new`), else the first tag: importing an `en.json` the app does not have is
+ * a file that does not compile.
  */
+export const defaultLocaleOf = (locales: readonly string[]): string =>
+  locales.length === 0 || locales.includes('en') ? 'en' : ([...locales].sort()[0] ?? 'en');
+
 const orderedLocales = (locales: readonly string[]): readonly string[] => {
+  const first = defaultLocaleOf(locales);
   const rest = new Set(locales);
-  rest.delete('en');
-  return ['en', ...[...rest].sort()];
+  rest.delete(first);
+  return [first, ...[...rest].sort()];
 };
 
 /** A locale tag is not always a valid JS binding (`zh-hant`) — `camel()` is the one identifier
  * derivation every generated file already uses for names, so the import agrees with the rest of
  * the app's own naming instead of inventing a second casing rule. */
-const localeImport = (locale: string): string =>
+export const localeImport = (locale: string): string =>
   `import ${camel(locale)} from '../catalogs/${locale}.json';`;
 
 /** The object-literal entry for one locale: shorthand when the binding IS the tag (`en`, `es`, …),
  * `'tag': binding` when `camel()` had to reshape it (`zh-hant` → `zhHant`) — `defineCatalogs` reads
  * the locale from the key, never the identifier, so the quoted form is what keeps it addressable. */
-const localeEntry = (locale: string): string => {
+export const localeEntry = (locale: string): string => {
   const binding = camel(locale);
   return binding === locale ? binding : `'${locale}': ${binding}`;
 };
@@ -61,6 +65,7 @@ const localeEntry = (locale: string): string => {
  */
 export function i18nIndex(locales: readonly string[]): string {
   const ordered = orderedLocales(locales);
+  const fallback = defaultLocaleOf(locales);
   const imports = ordered.map(localeImport).join('\n');
   const entries = ordered.map(localeEntry).join(', ');
   return `// The app's catalog, registered once and typed against English. Every surface resolves strings
@@ -75,13 +80,13 @@ import {
 } from '@ultimat3/i18n';
 ${imports}
 
-export const catalogs = defineCatalogs({ default: 'en', locales: { ${entries} } });
+export const catalogs = defineCatalogs({ default: '${fallback}', locales: { ${entries} } });
 
 /**
  * English is the source of truth for the key space — a second locale must match it exactly, or
  * \`x verify\` fails.
  */
-export type AppCatalog = typeof en;
+export type AppCatalog = typeof ${camel(fallback)};
 
 /** Every key this app's catalog defines — dot-paths, plus the stem of each plural family. */
 export type TranslationKey = KeyOf<AppCatalog>;

package/src/templates/scaffold-repo.ts

@@ -64,9 +64,9 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "dev": "x dev",
     "check": "bin/check",
     "verify": "x verify",
-    "typecheck": "tsc -b --pretty",
+    "typecheck": "tsc -p . --pretty",
     "lint": "biome check .",
-    "test": "bun test",
+    "test": "bun test --isolate",
     "db:migrate": "x db migrate",
     "db:seed": "x db seed"
   },
@@ -89,6 +89,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@ultimat3/i18n": "^${version}",
     "@ultimat3/jobs": "^${version}",
     "@ultimat3/mcp": "^${version}",
+    "@ultimat3/money": "^${version}",
     "@ultimat3/policy": "^${version}",
     "@ultimat3/pwa": "^${version}",
     "@ultimat3/query": "^${version}",
@@ -106,14 +107,16 @@ const rootPackage = (app: NameSet, version: string): string => `{
 
 /**
  * `"incremental": true` is ONE line and it is the difference between a 4.9s typecheck and a 92s
- * one. `x verify`'s first step is `tsc -b`, and `-b` decides "up to date?" by comparing emitted
- * OUTPUTS against inputs — with `noEmit` and no `composite`/`references`, the output it looks for
- * is an `app.config.js` that will never exist (`Project 'tsconfig.json' is out of date because
- * output file 'app.config.js' does not exist`), so every run rebuilt the whole program from
- * scratch, forever. Measured on a 166-file scaffold with no source change between runs: 92s wall
- * / 43s user CPU without it, 4.9s / 8.8s warm with it, and the whole gate at 12s rather than
- * 24-71s. This was the only tree in the framework without incremental typechecking — the repo
- * root has 32 `references` and `examples/dummy/tsconfig.json` sets `composite`.
+ * one. Measured on a 166-file scaffold with no source change between runs: 92s wall / 43s user CPU
+ * without it, 4.9s / 8.8s warm with it.
+ *
+ * The typecheck is `tsc -p .`, never `-b`, `As of 2026-09-23` (#450) — here, in the scaffold's
+ * `typecheck` script, and in `x verify`'s step (`verify-typecheck.ts`, for any root without
+ * `references`). `-b` decides "up to date?" by MTIME, and Bun installs a dependency as hardlinks
+ * carrying its cache's old mtimes: upgrading to a version already in the cache left every input
+ * older than the buildinfo, so `-b` skipped the program and reported green while a cold CI was
+ * red. `-p` with `incremental` compares content hashes. `-b` also wanted an emitted
+ * `app.config.js` that `noEmit` never writes, which is why this line was first needed.
  *
  * The note lives HERE and not in the emitted file, for the reason `biome.json` below gives: an
  * app author has no use for eight lines of framework archaeology in their own tsconfig, and

package/src/templates/scaffold-roles.ts

@@ -4,9 +4,23 @@
 // many answers as the app has folders, and the framework's two tracked apps already disagree.
 
 import type { GeneratedFile } from './naming';
+import { wrapList } from './wrap';
 
-const rolesSource =
-  (): string => `// Who holds which permission, for the whole app. Roles are sugar: every one expands to a flat
+/**
+ * A role's grants as Biome prints them. The example slice's \`post:read\`/\`post:write\` ride along
+ * with it: \`x g resource post\` would have granted them, and the scaffold writes that result.
+ */
+const grants = (base: string, example: string | undefined): string =>
+  wrapList(
+    '    ',
+    'grants: [',
+    [base, ...(example === undefined ? [] : [example])].map((grant) => `'${grant}'`),
+    '],',
+  );
+
+const rolesSource = (
+  example: boolean,
+): string => `// Who holds which permission, for the whole app. Roles are sugar: every one expands to a flat
 // permission set before any policy runs, so a rule never reasons about the hierarchy.
 //
 // ONE file, and it lives in shared/ — the leaf both site/ and app/ already import, and the one the
@@ -16,8 +30,9 @@ const rolesSource =
 // role HERE; calling defineRoles() again from a feature folder works and is the drift this file
 // exists to prevent.
 //
-// \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\`. Granting them is this
-// file's job — a permission no role holds is one no actor can ever exercise.
+// \`x g policy <feature>\` declares \`<feature>:read\` and \`<feature>:write\` and grants them below —
+// read to member, write to admin. A permission no role holds is one no actor can ever exercise,
+// and \`x verify\`'s policy step refuses it (X_PERMISSION_UNGRANTED).
 
 import { definePermissions, defineRoles } from '@ultimat3/policy';
 
@@ -32,11 +47,11 @@ export const appPermissions = definePermissions(['admin:read', 'dashboard:read']
 export const roles = defineRoles({
   member: {
     description: 'Signed in. Reads the app surface.',
-    grants: ['dashboard:read'],
+${grants('dashboard:read', example ? 'post:read' : undefined)}
   },
   admin: {
     description: 'Runs the app: the /admin surface, plus everything a member may do.',
-    grants: ['admin:read'],
+${grants('admin:read', example ? 'post:write' : undefined)}
     inherits: ['member'],
   },
 });
@@ -49,12 +64,25 @@ import { expandRoles, isKnownPermission, rolesGranting } from '@ultimat3/policy'
 import { expect, unitTest } from '@ultimat3/testing';
 import { appPermissions, roles } from './roles';
 
+// Every feature's policy.ts, imported the way the boot scan imports it: \`x g policy\` grants the
+// permissions a policy.ts DECLARES, so the registry below is only whole once they have run.
+const features = new Bun.Glob('{app,site}/*/policy.ts');
+for await (const file of features.scan({ cwd: \`\${import.meta.dir}/..\` })) {
+  await import(\`\${import.meta.dir}/../\${file}\`);
+}
+
 // The map is passed explicitly rather than read off the module-global one: a test that depended on
 // which module imported first would pass alone and fail inside a suite.
 
+// Subsets, never exact lists: every \`x g policy\` adds a grant here, and a pinned list would make
+// the generator's correct edit a red test.
 unitTest('admin inherits every member grant and adds its own', () => {
-  expect(expandRoles(['member'], roles)).toEqual(['dashboard:read']);
-  expect(expandRoles(['admin'], roles)).toEqual(['admin:read', 'dashboard:read']);
+  const member = expandRoles(['member'], roles);
+  const admin = expandRoles(['admin'], roles);
+  expect(member).toContain('dashboard:read');
+  expect(member).not.toContain('admin:read');
+  expect(admin).toContain('admin:read');
+  for (const permission of member) expect(admin).toContain(permission);
 });
 
 unitTest('a role nobody declared grants nothing', () => {
@@ -88,9 +116,9 @@ unitTest('the routes this app ships require permissions this app declares', () =
 `;
 
 /** `apps/web/shared/roles.ts` and its test. Written by `x new`, with or without the example slice. */
-export function rolesFiles(): readonly GeneratedFile[] {
+export function rolesFiles(example = false): readonly GeneratedFile[] {
   return [
-    { path: 'apps/web/shared/roles.ts', contents: rolesSource() },
+    { path: 'apps/web/shared/roles.ts', contents: rolesSource(example) },
     { path: 'apps/web/shared/roles.test.ts', contents: rolesTest() },
   ];
 }

package/src/templates/slice-foundation.ts

@@ -3,7 +3,7 @@
 // `policyFiles`; the five generators that write *into* a slice imported the same files and wrote
 // none of them, so each emitted TS2307 in any slice a resource had not been run in first.
 
-import { stripComments } from '../ts-scan';
+import { stripComments } from '@ultimat3/core';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';

package/src/templates/wrap.ts

@@ -80,7 +80,10 @@ const compareSpecifiers = (left: string, right: string): number => {
  * than spelled in each template, because the correct spelling is not knowable at authoring time.
  */
 export const sortSpecifiers = (names: readonly string[]): readonly string[] =>
-  [...names].sort(compareSpecifiers);
+  [...names].sort((left, right) => compareSpecifiers(bare(left), bare(right)));
+
+/** An inline \`type X\` sorts as \`X\`: Biome orders by the imported name, never by the modifier. */
+const bare = (name: string): string => (name.startsWith('type ') ? name.slice(5) : name);
 
 /**
  * A named import, sorted and wrapped. Its own function because the braces are spaced on one line

package/src/test-passes.ts

@@ -3,8 +3,9 @@
 // this file decides how many, and `test-shards.ts` spends them.
 
 import type { TestFile } from './test-select';
+import { SERIAL_TYPES } from './test-workers';
 import type { TestType } from './verify-tests';
-import { ownerOf, SERIAL_TYPES } from './verify-tests';
+import { ownerOf } from './verify-tests';
 
 /** One `bun test` invocation: which files, how wide, and the type its reproduce line names. */
 export interface TestPass {

package/src/test-workers.ts

@@ -5,6 +5,7 @@
 
 // Bun ships no CPU-count primitive; `cpus()` is the fallback when navigator cannot answer.
 import { cpus } from 'node:os';
+import type { TestType } from '@ultimat3/testing';
 
 /** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
 export function availableCpus(): number {
@@ -48,3 +49,28 @@ export const WORKER_FLOOR = 2;
 
 export const defaultWorkers = (available: number = availableCpus()): number =>
   Math.max(WORKER_FLOOR, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));
+
+/**
+ * Which types run across worker processes, and why the other two cannot.
+ *
+ * Parallel is safe when the only thing a test file shares with another file is the database, and
+ * the database is per worker by construction (`ULTIMATE_TEST_WORKER` → one clone of the migrated
+ * template, `@ultimat3/testing`'s `acquireWorkerDatabase`). Every other process-global in this
+ * framework — the permission set, the roles, the entity/action/query registries, the error-code
+ * titles, the fixture bag — is handled by `--isolate` giving each FILE its own module registry.
+ *
+ * | Type | Why |
+ * |---|---|
+ * | `live` | **serial.** A logical replication slot and a publication are named at the Postgres
+ * CLUSTER level, not inside a database, and this repo's own feed tests hard-code
+ * `x_live_slot` / `x_live_pub` against `TEST_REPLICATION_URL` — the one server, never a per-worker
+ * clone. Two workers would race `pg_create_logical_replication_slot` and the loser's failure would
+ * read as a flake. A per-worker database does not isolate a cluster-wide object |
+ * | `e2e` | **serial.** It runs against the *built output*: one `dist/`, one service-worker
+ * registration, one browser profile. There is nothing per-worker to hand it, and the type is
+ * seconds at most, so a split would buy a race and no time |
+ *
+ * The two are named here rather than tested for, because "can this type be sharded?" is a design
+ * fact about the type, not something a run can discover about itself.
+ */
+export const SERIAL_TYPES: readonly TestType[] = ['live', 'e2e'];

package/src/ts-scan.ts

@@ -30,14 +30,11 @@ export interface CodeScan {
   readonly unresolved: readonly UnresolvedCodeSite[];
 }
 
-// The masking itself — `QUOTES`, `endOfLiteral`, `stripComments`, `maskLiterals` — lives in
-// `@ultimat3/core`'s `source-mask.ts` since 2026-09-05, because `@ultimat3/i18n`'s key extractor
-// (tier 1) needed it and could not reach a tier-5 package. Re-exported here so every scanner in
-// this package, and this package's public API, keep the names they had.
+// The masking itself — `QUOTES`, `endOfLiteral`, `stripComments`, `maskLiterals` — is
+// `@ultimat3/core`'s (`source-mask.ts`), imported from there by every scanner. It was re-exported
+// here and from this package's barrel: two import paths for one function (22.0.0 removed both).
 import { endOfLiteral, maskLiterals, QUOTES, stripComments } from '@ultimat3/core';
 
-export { endOfLiteral, maskLiterals, QUOTES, stripComments };
-
 // `ReadonlySet`, so a consumer cannot mutate what every scan in this package reads.
 export const OPENERS: ReadonlySet<string> = new Set(['(', '[', '{']);
 export const CLOSERS: ReadonlySet<string> = new Set([')', ']', '}']);

package/src/tsconfig-references.ts

@@ -7,9 +7,8 @@
 // root that has no `tsconfig.json` at all, so an `existsSync` ahead of it was a second question
 // with one answer.
 import { join } from 'node:path';
-import { ERROR_DOCS_URL } from '@ultimat3/core';
+import { ERROR_DOCS_URL, maskLiterals, stripComments } from '@ultimat3/core';
 import type { Finding } from './output';
-import { maskLiterals, stripComments } from './ts-scan';
 
 const ROOT_TSCONFIG = 'tsconfig.json';