@starci/hfs 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 5.4.0 - 2026-11-03
+
+- Fixed: `starci app sync --execute` never leaves an app uncompilable. Before it writes a managed TypeScript file or deletes a retired one, it compiles each front-end and back-end project with the change applied (the app's own TypeScript; the changed files and every file importing them, against what is on disk). A managed group whose render adds a type error, in its own files or in an app file that imports one, is held whole: `HFS_SYNC_GROUP_HELD`, exit 1, naming the group, its files and the first errors (what the app must add or still imports); the rest is written, and a side without TypeScript installed is named in a notice (`sync/compile-guard.mts`).
+- Fixed: `starci app codemod module-definition` drops every imported name the rewrite made unused (`ConfigurableModuleCls`, `ConfigurableModuleHost`, `ConfigurableModuleBuilder`), keeps the names the file still uses and `import type`, keeps the builder's JSDoc, and writes each file as the app's Prettier prints it, so no TS6133 and no prettier-hook refusal follow it (`codemod/app-prettier.mts`).
+- Changed: `starci app codemod account-doors --contract` says why it writes nothing: the contract migration is already in the chain, or no migration grants the app role on schema `auth`.
+- Changed: the lite sign-in renders `@starci/auth` 0.2.1: `identity_refresh_tokens.raced_count` in the baseline (the package's `identity-sessions.sql`), the refresh-token entity's `racedCount` and the session store's `markTokenRaced`. An app whose baseline holds the 0.2.0 tables adds `@starci/auth/migrations/identity-refresh-raced-successors.sql` as a migration.
+- Changed: the canon pins name `@starci/auth` 0.2.1, `@starci/auth-oidc` 0.1.1 and the Grammar family 0.21.16.
+- Upgrade, for an app on the CLI 1.1.0-alpha.49 / hfs 5.0.8 render moving to this version: (1) `npx starci app codemod module-definition --execute`, then `npm install`; (2) `npx starci app sync --execute`, which writes everything that compiles and holds the auth-lite sign-in glue while the app's own identity code differs, naming each missing or still-imported symbol; (3) adopt `@starci/mail` and make the identity domain provide what the held errors name; (4) `npx starci app sync --execute` again, which writes the glue once it compiles; (5) `npx starci app codemod account-doors --execute`, and `--contract` when the app still grants on schema `auth`; (6) add the `raced_count` migration above.
+
 ## 5.3.0 - 2026-11-03
 
 - Fixed: the secrets family of the committed check cache stores codes, paths, positions and digests only (`cache/secret-records.mts`, `runtime/scripts/lib/secret-records.mts`), and the one secret judgement of R06 judges a file of `.starcistacks/cache/check/secrets/` by that contract, so `starci app check` can no longer write a cache the staged guard refuses (`HFS_PLAINTEXT_SECRET` for the `secrets/` folder name). A cache written before reads back as digests. Codemod: `starci app codemod secrets-cache`.

package/README.md

@@ -207,6 +207,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `starci app sync --execute` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
+`starci app sync --execute` never leaves the app uncompilable (`sync/compile-guard.mjs`): before it writes a managed TypeScript source or deletes a retired one, the side's own TypeScript compiles the app with those writes over the disk, and a managed group (`managedBy`) whose writes add a type error, in its own files or in an app file that imports one, is held whole: `HFS_SYNC_GROUP_HELD` (exit 1) names the group, its files and the errors (the names the render reads that the app does not provide yet, or the names it drops that the app still imports), and the rest of the render is written. The held files stay `HFS_SYNC_DRIFT` until the app provides what the render reads and sync runs again; a side whose TypeScript is not installed is written and named in a notice.
 Each finding is reported once: the managed ESLint and stylelint factory configs under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
 The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:world`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is `starci app check --gate lint`: ESLint over each side with its canon and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
 (slot `app.task-graph`): it carries the task graph, which no preset can render.

package/codemod/account-doors.mjs

@@ -97,8 +97,14 @@ export function migrateAccountDoors({ root, write = false, contract = false, now
     }
     if (report.findings.length)
         return report;
-    if (names.some((name) => name.includes(`_${CONTRACT_NAME}`)) || !names.some((name) => AUTH_GRANT.test(statementsOf(root, name))))
+    if (names.some((name) => name.includes(`_${CONTRACT_NAME}`))) {
+        report.next.push('the contract migration is already in the chain: nothing is left to revoke');
         return report;
+    }
+    if (!names.some((name) => AUTH_GRANT.test(statementsOf(root, name)))) {
+        report.next.push('no migration grants the application role on schema auth (the app reached accounts through the doors from the start): nothing to revoke');
+        return report;
+    }
     const file = `${MIGRATIONS_DIR}/${stamp}_${CONTRACT_NAME}.sql`;
     report.changes.push({ file, phase, why: 'revokes the direct grants on schema auth, auth.users and auth.identities from the application role' });
     report.next.push('the deploy applies it right after the accept; the release before the doors cannot sign in after a rollback unless the grants are given back');

package/codemod/app-prettier.d.mts

@@ -0,0 +1,5 @@
+import { type Prettier } from '../sync/format.mjs';
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+export declare function prettierOf(root: string, folders: readonly string[]): Prettier | undefined;
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+export declare function formatted(prettier: Prettier, root: string, file: string, text: string): Promise<string>;

package/codemod/app-prettier.mjs

@@ -0,0 +1,27 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadPrettier } from '../sync/format.mjs';
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+export function prettierOf(root, folders) {
+    for (const folder of [...folders, root]) {
+        try {
+            return loadPrettier(folder);
+        }
+        catch { /* the next folder */ }
+    }
+    return undefined;
+}
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+export async function formatted(prettier, root, file, text) {
+    const ignorePath = path.join(root, '.prettierignore');
+    try {
+        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
+        if (info.ignored || !info.inferredParser)
+            return text;
+        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
+        return await prettier.format(text, { ...options, filepath: file });
+    }
+    catch {
+        return text;
+    }
+}

package/codemod/explicit-surface.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { declarationSurface, isEmittableSource } from '../runtime/scripts/lib/declaration-surface.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
-import { loadPrettier } from '../sync/format.mjs';
+import { formatted, prettierOf } from './app-prettier.mjs';
 import { applyEdits, importEdits } from './explicit-surface-edit.mjs';
 import { conventionType, MAX_TYPE_LENGTH, renderType } from './explicit-surface-render.mjs';
 import { GENERATED, relativePosix, sideFolders } from './source-tree.mjs';
@@ -212,30 +212,6 @@ async function sideSources(root, side, folder) {
     visit(folder);
     return { files: files.sort(), scope: selects === undefined ? 'walk' : 'canon' };
 }
-/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
-function prettierOf(root, folders) {
-    for (const folder of [...folders, root]) {
-        try {
-            return loadPrettier(folder);
-        }
-        catch { /* the next folder */ }
-    }
-    return undefined;
-}
-/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
-async function formatted(prettier, root, file, text) {
-    const ignorePath = path.join(root, '.prettierignore');
-    try {
-        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
-        if (info.ignored || !info.inferredParser)
-            return text;
-        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
-        return await prettier.format(text, { ...options, filepath: file });
-    }
-    catch {
-        return text;
-    }
-}
 /** The side-relative name a report gives `absolute`. */
 const nameOf = (root, absolute) => relativePosix(root, absolute);
 /** Plans every open file of one program, checks that the rewritten files read no worse than the originals, and returns what each file becomes. */

package/codemod/main.mjs

@@ -59,10 +59,6 @@ function runCodemod(name, root, write) {
         const report = migrateSopsRules({ root, write });
         return { report, markdown: sopsRulesMarkdown(report) };
     }
-    if (name === 'module-definition') {
-        const report = migrateModuleDefinition({ root, write });
-        return { report, markdown: moduleDefinitionMarkdown(report) };
-    }
     if (name === 'secrets-cache') {
         const report = migrateSecretsCache({ root, write });
         return { report, markdown: secretsCacheMarkdown(report) };
@@ -126,6 +122,12 @@ async function explicitSurfaceMain(argv, io) {
     const report = await migrateExplicitSurface({ root: path.resolve(io.cwd), write: options.write });
     return emit(options, { report, markdown: explicitSurfaceMarkdown(report) }, io);
 }
+/** `starci app codemod module-definition`: it formats each rewritten definition with the app's Prettier, which is asynchronous. */
+async function moduleDefinitionMain(argv, io) {
+    const options = reportArguments(argv);
+    const report = await migrateModuleDefinition({ root: path.resolve(io.cwd), write: options.write });
+    return emit(options, { report, markdown: moduleDefinitionMarkdown(report) }, io);
+}
 /** `starci app codemod account-doors [--contract]`: the expand migration of the account doors, or (a release later) the contract migration that revokes the old grants. */
 function accountDoorsMain(argv, io) {
     const contract = argv.includes('--contract');
@@ -145,6 +147,8 @@ export function codemodMain(argv, io) {
         return explicitSurfaceMain(rest, io);
     if (name === 'account-doors')
         return accountDoorsMain(rest, io);
+    if (name === 'module-definition')
+        return moduleDefinitionMain(rest, io);
     if (name === undefined || !CODEMODS.includes(name))
         throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
     const options = reportArguments(rest);

package/codemod/module-definition.d.mts

@@ -1,3 +1,4 @@
+import type { Prettier } from '../sync/format.mjs';
 /** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
 type Ts = typeof import('typescript');
 /** One definition the migration rewrites: which form it was written in, the helper it became and the names it exports. */
@@ -41,12 +42,18 @@ export declare function transformModuleDefinition({ ts, text, file }: {
     changes: ModuleDefinitionChange[];
     findings: ModuleDefinitionFinding[];
 };
-/** Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, then the dependency in the root package.json. */
-export declare function migrateModuleDefinition({ root, write, ts }: {
+/** What `migrateModuleDefinition` takes: the app root, whether to write, and the compiler and formatter of the app (found in it when left out; `prettier: null` writes the codemod's own layout). */
+export interface ModuleDefinitionOptions {
     root: string;
     write?: boolean;
     ts?: Ts | null;
-}): ModuleDefinitionReport;
+    prettier?: Prettier | null;
+}
+/**
+ * Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, each rewritten file formatted by the app's Prettier
+ * (so `app check --format` and the app's hook accept it as written), then the dependency in the root package.json.
+ */
+export declare function migrateModuleDefinition({ root, write, ts, prettier }: ModuleDefinitionOptions): Promise<ModuleDefinitionReport>;
 /** Render the rewrite and what is left for a person as Markdown; JSON consumers read the same report object. */
 export declare function moduleDefinitionMarkdown(report: ModuleDefinitionReport): string;
 export {};

package/codemod/module-definition.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { formatted, prettierOf } from './app-prettier.mjs';
 import { filesUnder, relativePosix, sideFolders } from './source-tree.mjs';
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const KIT = '@starci/nest-kit';
@@ -118,7 +119,7 @@ function readDefinition(ts, source) {
         drop.add(statement);
         if (at === null) {
             at = statement;
-            doc = docOf(ts, source, statement);
+            doc = docOf(ts, source, statement) || docOf(ts, source, builtStatement);
         }
     }
     if (at === null || names.length === 0)
@@ -130,25 +131,34 @@ function readDefinition(ts, source) {
         return unfit(source, builtStatement, 'MODULE_DEFINITION_NAMES', 'another statement of the file reads the builder result or `Host`');
     return { ...read, names: [...names].sort((a, b) => [...EXPORTED].indexOf(a) - [...EXPORTED].indexOf(b)), doc, drop, at, from: 'typed builder' };
 }
-/** The one export of the new definition, laid out the way Prettier prints it at the width of the canon (break the arguments of a call that takes a token, else after the `=`). */
+/** The one export of the new definition, laid out the way Prettier prints it at the width of the canon (one line; else the options object opens on the line of the `=` when that fits; else the call breaks after the `=`). */
 function exportLine(reading, helper) {
     const head = `export const { ${reading.names.join(', ')} } =`;
     const call = `${helper}<${reading.options}>(${reading.token === null ? '' : `{ optionsInjectionToken: ${reading.token} }`})`;
     if (`${head} ${call}`.length <= PRINT_WIDTH)
         return `${head} ${call}`;
-    return reading.token === null ? `${head}\n    ${call}` : `${head} ${helper}<${reading.options}>({\n    optionsInjectionToken: ${reading.token},\n})`;
+    const hug = `${head} ${helper}<${reading.options}>({`;
+    return reading.token !== null && hug.length <= PRINT_WIDTH ? `${hug}\n    optionsInjectionToken: ${reading.token},\n})` : `${head}\n    ${call}`;
 }
-/** The import declaration of `@nestjs/common` without the builder names, or null when nothing else is imported from it. */
-function nestImport(ts, source, statement) {
-    const bindings = statement.importClause?.namedBindings;
-    if (bindings === undefined || !ts.isNamedImports(bindings))
+/** The words of `text` (identifier characters), so a binding is known to be read by its name. */
+const wordsOf = (text) => new Set(text.match(/[\w$]+/g));
+/**
+ * An import declaration without the named bindings the rewrite made unused (read by the dropped statements, by none of the kept ones), or null
+ * when nothing is left of it; `import type` and inline `type` stay as written.
+ */
+function prunedImport(ts, source, statement, before, after) {
+    const clause = statement.importClause;
+    const bindings = clause?.namedBindings;
+    if (clause === undefined || bindings === undefined || !ts.isNamedImports(bindings))
         return statement.getText(source);
-    const kept = bindings.elements.filter((element) => !['ConfigurableModuleBuilder', 'ConfigurableModuleHost'].includes((element.propertyName ?? element.name).text));
+    const kept = bindings.elements.filter((element) => after.has(element.name.text) || !before.has(element.name.text));
     if (kept.length === bindings.elements.length)
         return statement.getText(source);
-    if (kept.length === 0 && statement.importClause?.name === undefined)
+    if (kept.length === 0 && clause.name === undefined)
         return null;
-    return `import { ${kept.map((element) => element.getText(source)).join(', ')} } from "@nestjs/common"`;
+    const named = kept.length === 0 ? '' : `{ ${kept.map((element) => element.getText(source)).join(', ')} }`;
+    const head = [clause.name?.text, named].filter((part) => part !== undefined && part !== '').join(', ');
+    return `import ${clause.isTypeOnly ? 'type ' : ''}${head} from ${statement.moduleSpecifier.getText(source)}`;
 }
 /** Rewrite one definition file's text to the helper form; `text` unchanged when the file holds no definition the codemod can rewrite. */
 export function transformModuleDefinition({ ts, text, file = 'x.module-definition.ts' }) {
@@ -162,13 +172,11 @@ export function transformModuleDefinition({ ts, text, file = 'x.module-definitio
     if ('reason' in read)
         return { ...none, findings: [{ file, line: read.line, code: read.code, reason: read.reason }] };
     const helper = read.representative ? 'defineCapabilityModule' : 'defineConfigurableModule';
-    const imports = [`import { ${helper} } from "${KIT}"`];
     const body = [];
+    const declarations = [];
     for (const statement of source.statements) {
         if (ts.isImportDeclaration(statement)) {
-            const nest = ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === '@nestjs/common' ? nestImport(ts, source, statement) : statement.getText(source);
-            if (nest !== null)
-                imports.push(nest);
+            declarations.push(statement);
             continue;
         }
         if (read.drop.has(statement))
@@ -179,6 +187,9 @@ export function transformModuleDefinition({ ts, text, file = 'x.module-definitio
         }
         body.push(text.slice(statement.pos, statement.end).replace(/^\s*\n/, '').trimEnd());
     }
+    const before = wordsOf(source.statements.filter((statement) => !ts.isImportDeclaration(statement)).map((statement) => statement.getText(source)).join('\n'));
+    const after = wordsOf(body.join('\n'));
+    const imports = [`import { ${helper} } from "${KIT}"`, ...declarations.flatMap((statement) => prunedImport(ts, source, statement, before, after) ?? [])];
     const output = `${imports.join('\n')}\n\n${body.join('\n\n')}\n`;
     return { text: output, changes: [{ file, from: read.from, helper, names: read.names }], findings: [] };
 }
@@ -186,13 +197,17 @@ export function transformModuleDefinition({ ts, text, file = 'x.module-definitio
 function kitVersion() {
     return bundledPins()[KIT]?.version ?? '0.1.0';
 }
-/** Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, then the dependency in the root package.json. */
-export function migrateModuleDefinition({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+/**
+ * Preview or apply the rewrite in one app: every `*.module-definition.ts` under its sides, each rewritten file formatted by the app's Prettier
+ * (so `app check --format` and the app's hook accept it as written), then the dependency in the root package.json.
+ */
+export async function migrateModuleDefinition({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT), prettier }) {
     if (!ts)
         throw new Error('module-definition needs TypeScript installed in the app or @starci/hfs development checkout');
     const folders = sideFolders(root);
     if (!folders.length)
         throw new Error('module-definition runs at an app root with a be/ directory');
+    const formatter = prettier === undefined ? prettierOf(root, folders) : prettier ?? undefined;
     const packageFile = path.join(root, 'package.json');
     const manifest = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, 'utf8')) : null; // reason: package.json parsed from disk, only dependencies is read
     const declared = manifest?.dependencies?.[KIT] !== undefined;
@@ -207,7 +222,7 @@ export function migrateModuleDefinition({ root, write = false, ts = loadTypescri
         if (result.text !== original) {
             report.filesChanged.push(file);
             if (write)
-                fs.writeFileSync(target, result.text);
+                fs.writeFileSync(target, formatter === undefined ? result.text : await formatted(formatter, root, target, result.text));
         }
     }
     if (report.filesChanged.length > 0 && !declared && manifest !== null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -38,7 +38,7 @@ pins:
     source: packages/next-data/package.json
     why: 'the SWR data helpers of every front end (fe-stack data, owner:next-data-package): pollingRestart, the viewer and tenant key helpers, viewerSwrConfig and the viewer cache; each operation hook stays in the app and the package holds no component.'
   '@starci/grammar':
-    version: 0.21.15
+    version: 0.21.16
     group: starci
     install: registry
     side: fe
@@ -52,28 +52,28 @@ pins:
     source: packages/next-i18n/package.json
     why: 'the next-intl stack of every front end (fe-stack i18n, owner:next-i18n-package): defineI18n over the locales of the app, the locale-negotiating proxy, the locale-aware navigation, the request config that loads the catalogs of the app and the locale read of the [locale] layout; the app keeps its message catalogs and writes none of the stack.'
   '@starci/eslint-canon-be':
-    version: 3.14.0
+    version: 3.14.1
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.12.0
+    version: 9.12.1
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.15
+    version: 0.21.16
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.15
+    version: 0.21.16
     group: starci
     install: registry
     side: fe
@@ -127,14 +127,14 @@ pins:
     source: packages/nest-kit/package.json
     why: 'the module definition of every back-end module: defineConfigurableModule and defineCapabilityModule return the module base class, the options token and the options types with their types stated, so a <x>.module-definition.ts is one call that the lint on stated export types (R368) and the duplicate-code check (R21) both accept; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth':
-    version: 0.2.0
+    version: 0.2.1
     group: starci
     install: registry
     side: both
     source: packages/auth/package.json
     why: 'the lite sign-in: the NestJS module (EdDSA access tokens with a multi-key JWKS, passwords, Google OAuth with state and PKCE, rotating refresh sessions, the sign-in budget, the refresh cookie), the front-end client and its React bindings, the door contracts and test doubles; the one importer of the identity libraries, reached by a back end only through integrations/passport; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/auth-oidc':
-    version: 0.1.0
+    version: 0.1.1
     group: starci
     install: registry
     side: both
@@ -155,7 +155,7 @@ pins:
     source: packages/mail/package.json
     why: 'outgoing mail of a back end: a NestJS module and the Mailer port over SMTP (connect, greeting, socket and total timeouts, STARTTLS required by default, recipient, message and attachment checks, a shared SMTP target policy, coded errors, typed escaping render helpers returning { subject, text, html }), with @starci/mail/testing for its specs; the only importer of nodemailer (R90).'
   '@starci/hfs':
-    version: 5.3.0
+    version: 5.4.0
     group: starci
     install: registry
     side: both

package/sync/compile-guard.d.mts

@@ -0,0 +1,36 @@
+/** The TypeScript compiler API of the app's own install, typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** The refusal code of a held group. */
+export declare const GROUP_HELD = "HFS_SYNC_GROUP_HELD";
+/** The pseudo-group of the retired files a sync deletes. */
+export declare const RETIRED_GROUP = "retired";
+/** One write the guard judges: an app-relative path, its managed group, and its new text (null: the file is deleted). */
+export interface GuardedWrite {
+    path: string;
+    group: string;
+    text: string | null;
+}
+/** A group sync does not write, with its files and the errors its writes would add. */
+export interface HeldGroup {
+    group: string;
+    files: string[];
+    errors: string[];
+}
+/** What the guard answers: the held groups, and the sides it could not compile. */
+export interface GuardVerdict {
+    held: HeldGroup[];
+    unchecked: string[];
+}
+/** Whether `file` (app-relative) is TypeScript source a side compiles. */
+export declare const isGuardedSource: (file: string) => boolean;
+/** The tsconfig that compiles an app-relative source: `be/tsconfig.json`, or the front-end app's or package's own; null when there is none. */
+export declare function projectOf(root: string, file: string): string | null;
+/**
+ * The groups `starci app sync --execute` holds back at `root`: every write of a TypeScript source is compiled, per side, with the side's own
+ * TypeScript (`loadTs`, the app's install by default); a side with no tsconfig compiles nothing, a side whose TypeScript is not installed is
+ * named in `unchecked`.
+ */
+export declare function guardWrites(root: string, writes: readonly GuardedWrite[], loadTs?: (dir: string) => Ts | null): GuardVerdict;
+/** The lines sync prints for a held group: what is held and why, the first errors, and what to do. */
+export declare function heldLines(group: HeldGroup): string[];
+export {};

package/sync/compile-guard.mjs

@@ -0,0 +1,189 @@
+// compile-guard.mjs - HFS_SYNC_GROUP_HELD: `starci app sync --execute` never writes a render that leaves the app uncompilable. Before it writes
+// a managed TypeScript source (or deletes a retired one), the side's own TypeScript compiles the app with the writes laid over the disk and
+// compares the diagnostics of every file they touch, and of every file that imports one, with the same files on disk. A managed group whose
+// writes add an error (a template that reads a name the app does not provide yet, or drops one the app still imports) is held whole: none
+// of its files is written, the rest of the render is, and the sync names the group, its files and the errors, so the app provides what the
+// render reads and runs sync again. A side whose TypeScript is not installed cannot be compiled; its writes go through and say so.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+/** The refusal code of a held group. */
+export const GROUP_HELD = 'HFS_SYNC_GROUP_HELD';
+/** The pseudo-group of the retired files a sync deletes. */
+export const RETIRED_GROUP = 'retired';
+/** How many errors a held group prints. */
+const SHOWN_ERRORS = 20;
+const SOURCE = /\.tsx?$/;
+/** Whether `file` (app-relative) is TypeScript source a side compiles. */
+export const isGuardedSource = (file) => SOURCE.test(file) && !file.endsWith('.d.ts') && (file.startsWith('be/') || file.startsWith('fe/'));
+/** The tsconfig that compiles an app-relative source: `be/tsconfig.json`, or the front-end app's or package's own; null when there is none. */
+export function projectOf(root, file) {
+    const parts = file.split('/');
+    const project = parts[0] === 'be' ? 'be/tsconfig.json' : parts.length > 3 ? `fe/${parts[1]}/${parts[2]}/tsconfig.json` : null;
+    return project !== null && fs.existsSync(path.join(root, project)) ? project : null;
+}
+/** One side's compilation: its compiler, options and root files, the overlay of writes keyed the way the host compares file names. */
+class Side {
+    #ts;
+    #root;
+    #options;
+    #rootNames;
+    #baseline = new Map();
+    #program;
+    constructor(ts, root, project) {
+        this.#ts = ts;
+        this.#root = root;
+        const file = path.join(root, project);
+        const read = ts.readConfigFile(file, ts.sys.readFile);
+        const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(file), { noEmit: true }, file);
+        this.#options = { ...parsed.options, noEmit: true };
+        this.#rootNames = parsed.fileNames;
+    }
+    /** The name the host compares: absolute, forward slashes, lower case where the file system ignores case. */
+    key(file) {
+        const absolute = path.resolve(this.#root, file).replaceAll('\\', '/');
+        return this.#ts.sys.useCaseSensitiveFileNames ? absolute : absolute.toLowerCase();
+    }
+    #host(overlay) {
+        const host = this.#ts.createCompilerHost(this.#options, true);
+        const { readFile, fileExists, getSourceFile } = host;
+        host.readFile = (name) => (overlay.has(this.key(name)) ? overlay.get(this.key(name)) ?? undefined : readFile.call(host, name));
+        host.fileExists = (name) => (overlay.has(this.key(name)) ? overlay.get(this.key(name)) !== null : fileExists.call(host, name));
+        host.getSourceFile = (name, language, onError, create) => {
+            if (!overlay.has(this.key(name)))
+                return getSourceFile.call(host, name, language, onError, create);
+            const text = overlay.get(this.key(name));
+            return text === null || text === undefined ? undefined : this.#ts.createSourceFile(name, text, language, true);
+        };
+        return host;
+    }
+    #programOf(overlay, added) {
+        const rootNames = [...this.#rootNames.filter((name) => overlay.get(this.key(name)) !== null), ...added];
+        return this.#ts.createProgram({ rootNames, options: this.#options, host: this.#host(overlay), ...(this.#program === undefined ? {} : { oldProgram: this.#program }) });
+    }
+    /** The files of the program that import one of `targets` (keys), each with the targets it imports. */
+    importers(targets, overlay) {
+        const host = this.#host(overlay);
+        const cache = this.#ts.createModuleResolutionCache(this.#root, (name) => this.key(name), this.#options);
+        const found = new Map();
+        for (const name of this.#rootNames) {
+            const text = host.readFile(name);
+            if (text === undefined)
+                continue;
+            for (const imported of this.#ts.preProcessFile(text, true, true).importedFiles) {
+                const resolved = this.#ts.resolveModuleName(imported.fileName, name, this.#options, host, cache).resolvedModule?.resolvedFileName;
+                if (resolved === undefined || !targets.has(this.key(resolved)))
+                    continue;
+                const into = found.get(this.key(name)) ?? new Set();
+                into.add(this.key(resolved));
+                found.set(this.key(name), into);
+            }
+        }
+        return found;
+    }
+    /** The errors of `files` (keys) as `path TScode message`, each file once, in the program with `overlay` laid over the disk. */
+    errors(files, overlay, added) {
+        const program = this.#programOf(overlay, added);
+        if (overlay.size === 0)
+            this.#program = program;
+        const byKey = new Map(program.getSourceFiles().map((source) => [this.key(source.fileName), source]));
+        const answer = new Map();
+        for (const file of files) {
+            const source = byKey.get(file);
+            const relative = path.relative(this.#root, source?.fileName ?? file).replaceAll('\\', '/');
+            const found = source === undefined ? [] : [...program.getSyntacticDiagnostics(source), ...program.getSemanticDiagnostics(source)];
+            answer.set(file, found.map((diagnostic) => `${relative}${source === undefined || diagnostic.start === undefined ? '' : `:${String(source.getLineAndCharacterOfPosition(diagnostic.start).line + 1)}`} TS${String(diagnostic.code)} ${this.#ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}`));
+        }
+        return answer;
+    }
+    /** The errors of `files` on disk, computed once per file. */
+    baseline(files) {
+        const missing = files.filter((file) => !this.#baseline.has(file));
+        if (missing.length > 0)
+            for (const [file, found] of this.errors(missing, new Map(), []))
+                this.#baseline.set(file, found);
+        return new Map(files.map((file) => [file, this.#baseline.get(file) ?? []]));
+    }
+}
+/** An error without its line, so a line moved by the write is the same error. */
+const unplaced = (error) => error.replace(/^([^ ]*?):\d+ /, '$1 ');
+/** The errors of `after` that `before` does not hold, counted as a multiset of unplaced errors. */
+function added(before, after) {
+    const left = new Map();
+    for (const error of before)
+        left.set(unplaced(error), (left.get(unplaced(error)) ?? 0) + 1);
+    return after.filter((error) => {
+        const count = left.get(unplaced(error)) ?? 0;
+        left.set(unplaced(error), count - 1);
+        return count <= 0;
+    });
+}
+/** The held groups of one side: compile with every write of the groups still in play, hold the groups that add an error, again until none does. */
+function judgeSide(side, writes) {
+    const held = [];
+    let open = [...writes];
+    while (open.length > 0) {
+        const overlay = new Map(open.map((write) => [side.key(write.path), write.text]));
+        const groupOf = new Map(open.map((write) => [side.key(write.path), write.group]));
+        // An importer is found on the disk with the new files added, so the importer of a file the writes delete is found too.
+        const importers = side.importers(new Set(overlay.keys()), new Map([...overlay].filter(([, text]) => text !== null)));
+        const files = [...new Set([...[...overlay.keys()].filter((file) => overlay.get(file) !== null), ...importers.keys()])];
+        const before = side.baseline(files);
+        const after = side.errors(files, overlay, open.filter((write) => write.text !== null).map((write) => path.resolve(write.path)));
+        const errors = new Map();
+        for (const file of files) {
+            const fresh = added(before.get(file) ?? [], after.get(file) ?? []);
+            if (fresh.length === 0)
+                continue;
+            const groups = groupOf.has(file) ? [groupOf.get(file)] : [...(importers.get(file) ?? [])].map((target) => groupOf.get(target));
+            for (const group of groups)
+                errors.set(group, [...(errors.get(group) ?? []), ...fresh]);
+        }
+        if (errors.size === 0)
+            break;
+        for (const [group, found] of errors)
+            held.push({ group, files: open.filter((write) => write.group === group).map((write) => write.path), errors: [...new Set(found)] });
+        open = open.filter((write) => !errors.has(write.group));
+    }
+    return held;
+}
+/**
+ * The groups `starci app sync --execute` holds back at `root`: every write of a TypeScript source is compiled, per side, with the side's own
+ * TypeScript (`loadTs`, the app's install by default); a side with no tsconfig compiles nothing, a side whose TypeScript is not installed is
+ * named in `unchecked`.
+ */
+export function guardWrites(root, writes, loadTs = (dir) => loadTypescript(dir, root)) {
+    const verdict = { held: [], unchecked: [] };
+    const bySide = new Map();
+    for (const write of writes.filter((candidate) => isGuardedSource(candidate.path))) {
+        const project = projectOf(root, write.path);
+        if (project !== null)
+            bySide.set(project, [...(bySide.get(project) ?? []), { ...write, path: path.join(root, write.path) }]);
+    }
+    for (const [project, sideWrites] of bySide) {
+        const ts = loadTs(path.join(root, path.dirname(project)));
+        if (ts === null) {
+            verdict.unchecked.push(project);
+            continue;
+        }
+        for (const group of judgeSide(new Side(ts, root, project), sideWrites)) {
+            const relative = group.files.map((file) => path.relative(root, file).replaceAll('\\', '/'));
+            const known = verdict.held.find((entry) => entry.group === group.group);
+            if (known === undefined)
+                verdict.held.push({ ...group, files: relative });
+            else
+                verdict.held.splice(verdict.held.indexOf(known), 1, { group: group.group, files: [...known.files, ...relative], errors: [...known.errors, ...group.errors] });
+        }
+    }
+    return verdict;
+}
+/** The lines sync prints for a held group: what is held and why, the first errors, and what to do. */
+export function heldLines(group) {
+    const more = group.errors.length > SHOWN_ERRORS ? [`  ... ${String(group.errors.length - SHOWN_ERRORS)} more`] : [];
+    return [
+        `${GROUP_HELD} ${group.group}: ${String(group.files.length)} files not written, the render adds ${String(group.errors.length)} type errors to the app (${group.files.join(', ')})`,
+        ...group.errors.slice(0, SHOWN_ERRORS).map((error) => `  ${error}`),
+        ...more,
+        `  make the app provide what the render reads (each error names it), then run "npx --no-install starci app sync --execute" again`,
+    ];
+}

package/sync/index.d.mts

@@ -1,6 +1,7 @@
 import { type RepoView } from '../runtime/scripts/hfs/slots.mjs';
 import type { AppRepo } from '../runtime/scripts/hfs/slot-app-view.mjs';
 import type { Slot, SlotManifest } from '../runtime/scripts/hfs/manifest-shape.mjs';
+import { guardWrites, type GuardedWrite } from './compile-guard.mjs';
 import type { ImageApp } from './stack-images.mjs';
 export declare const TEMPLATES_DIR: string;
 /** The scopes a target is rendered for: the app root, then each side. */
@@ -22,6 +23,7 @@ export interface Target {
     template: string;
     mode: string;
     slot?: string;
+    group?: string;
     markdown?: boolean;
 }
 /** The markers around a managed block. */
@@ -39,6 +41,8 @@ export interface RenderedTarget {
     scripts?: Record<string, unknown>;
     markdown?: boolean | undefined;
     markers?: Markers;
+    /** The managed group of a slot's file (`managedBy`), which sync writes or holds whole (compile-guard.mjs). */
+    group?: string;
 }
 /** What comparing a rendered target with the disk answers. */
 export interface TargetCheck {
@@ -229,9 +233,13 @@ export declare function renderRepo(root: string, { presets, parseYaml, notices,
 export declare function retiredFiles(root: string, hfs: {
     edition?: string;
 } | null | undefined): string[];
-export declare function runSync(argv: string[], { cwd, out, presets, parseYaml }?: {
+/** The writes of `targets` and the deletions of `retired` the compile guard judges: every file sync would change, with its managed group. */
+export declare function guardedWrites(root: string, targets: readonly RenderedTarget[], retired: readonly string[]): GuardedWrite[];
+export declare function runSync(argv: string[], { cwd, out, presets, parseYaml, loadTs }?: {
     cwd?: string;
     out?: (line: string) => unknown;
     presets?: Presets | undefined;
     parseYaml?: ParseYaml | undefined;
+    /** The TypeScript of a side folder the compile guard compiles with; the app's own install by default. */
+    loadTs?: Parameters<typeof guardWrites>[2];
 }): Promise<number>;

package/sync/index.mjs

@@ -29,6 +29,7 @@ import { feAppPackageName } from '../runtime/scripts/hfs/rules/monorepo.mjs';
 import { DEFAULT_PORT, NODE_IMAGE, dockerfilePath } from '../runtime/scripts/hfs/rules/docker.mjs';
 import { isFile } from '../runtime/scripts/lib/fs-kind.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
+import { RETIRED_GROUP, guardWrites, heldLines, isGuardedSource } from './compile-guard.mjs';
 import { readDeclaredStack, stackWorkflowVariables } from './stack-images.mjs';
 import { DB_DOCKERFILE, DB_IMAGE_APP, RETIRED_DB_DOCKERFILE } from '../db/image.mjs';
 import { byCodeUnit } from '../report/order.mjs';
@@ -99,7 +100,7 @@ function slotTargets(slot, scope, edition, manifest, hasTemplate, enabled) {
         const template = managedTemplate(scope, group, file, hasTemplate);
         if (!template)
             throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${scope}, but templates/{${scope},common}/${group} has no template for it`);
-        return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id };
+        return { path: file, template, mode: MODE_OF_GROUP[group] ?? 'file', slot: slot.id, group };
     });
 }
 function unlistedTargets(scope, edition) {
@@ -548,7 +549,7 @@ function renderOnce(hfs, presets, { sonarKey, readTemplate = readBundled, manife
                 const markers = target.markdown ? { begin: '<!-- >>> starci app sync (managed block; do not edit) >>> -->', end: '<!-- <<< starci app sync <<< -->' } : { begin: BLOCK_BEGIN, end: BLOCK_END };
                 const spacing = target.markdown ? '\n' : '';
                 const managed = target.mode === 'block' ? `${markers.begin}\n${spacing}${trailingNewline(body)}${spacing}${markers.end}\n` : body;
-                return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed) };
+                return { path: where, scope, mode: target.mode, markdown: target.markdown, markers, content: managed, hash: hashOf(managed), ...(target.group === undefined ? {} : { group: target.group }) };
             })];
     });
 }
@@ -714,6 +715,16 @@ export function retiredFiles(root, hfs) {
         walk(file);
     return found;
 }
+/** The writes of `targets` and the deletions of `retired` the compile guard judges: every file sync would change, with its managed group. */
+export function guardedWrites(root, targets, retired) {
+    const changed = checkTargets(root, targets).filter(result => result.status !== 'ok' && isGuardedSource(result.path));
+    const writes = changed.map((result) => {
+        const target = targets.find(candidate => candidate.path === result.path);
+        const file = path.join(root, target.path);
+        return { path: target.path, group: target.group ?? target.path, text: writtenContent(target, fs.existsSync(file) ? lf(fs.readFileSync(file, 'utf8')) : '') };
+    });
+    return [...writes, ...retired.map((file) => ({ path: file, group: RETIRED_GROUP, text: null }))];
+}
 /** `starci app sync [--execute] [--cwd <dir>]` at the app root: the dry run reports drift, --execute writes; returns 0 clean, 1 drift, 2 usage. */
 function syncOptions(argv) {
     const write = argv.includes('--execute');
@@ -738,7 +749,7 @@ function reportSyncCheck(root, targets, out, retired = []) {
     out(`starci app sync: ${results.length - bad.length} of ${results.length} in sync${bad.length ? '; run "npx --no-install starci app sync --execute"' : ''}`);
     return bad.length || retired.length ? 1 : 0;
 }
-export async function runSync(argv, { cwd = process.cwd(), out = (line) => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
+export async function runSync(argv, { cwd = process.cwd(), out = (line) => process.stdout.write(`${line}\n`), presets, parseYaml, loadTs } = {}) {
     const options = syncOptions(argv);
     if (!options) {
         out('usage: starci app sync [--execute] [--cwd <dir>]');
@@ -754,18 +765,27 @@ export async function runSync(argv, { cwd = process.cwd(), out = (line) => proce
             for (const notice of new Set(notices))
                 out(notice);
         if (write) {
-            const written = writeTargets(root, targets);
+            const { held, unchecked } = guardWrites(root, guardedWrites(root, targets, retired), loadTs);
+            const holds = new Set(held.flatMap(group => group.files));
+            const free = targets.filter(target => !holds.has(target.path));
+            const written = writeTargets(root, free);
+            const removed = retired.filter(file => !holds.has(file));
             for (const file of written)
                 out(`wrote ${file}`);
-            for (const file of retired) {
+            for (const file of removed) {
                 fs.rmSync(path.join(root, file));
                 out(`removed ${file} (retired)`);
             }
             for (const dir of LITE_RETIRED_DIRS)
-                if (retired.length && fs.existsSync(path.join(root, dir)) && !fs.readdirSync(path.join(root, dir)).length)
+                if (removed.length && fs.existsSync(path.join(root, dir)) && !fs.readdirSync(path.join(root, dir)).length)
                     fs.rmdirSync(path.join(root, dir));
-            out(`starci app sync: ${written.length} written, ${targets.length - written.length} already in sync`);
-            return 0;
+            for (const project of unchecked)
+                out(`notice: the writes compiled by ${project} were not type-checked: its TypeScript is not installed (run npm install, then "npx --no-install starci app check")`);
+            for (const group of held)
+                for (const line of heldLines(group))
+                    out(line);
+            out(`starci app sync: ${written.length} written, ${free.length - written.length} already in sync${holds.size ? `, ${holds.size} held` : ''}`);
+            return held.length ? 1 : 0;
         }
         return reportSyncCheck(root, targets, out, retired);
     }

package/templates/app/skeleton-lite/db/migrations/__timestamp___baseline.sql

@@ -25,7 +25,8 @@ end;
 $$;
 
 -- The device sessions and rotating refresh tokens of @starci/auth. A token is stored by its sha256 only; a rotated token stays,
--- marked used, so a replay is detected (a replay inside the grace window is a racing tab, an older one ends the session).
+-- marked used, so a replay is detected: a replay inside the grace window gets a successor of its own (raced_count bounds how many),
+-- an older one ends the session and every token of it.
 -- identity_attempts counts the sign-in attempts of one address in a window every replica shares (the budget of failures).
 -- The app owns auth.users (db/bootstrap.sql) and the role app_be.
 
@@ -48,6 +49,7 @@ create table public.identity_refresh_tokens (
     created_at timestamptz not null default now(),
     expires_at timestamptz not null,
     used_at timestamptz,
+    raced_count integer not null default 0,
     constraint identity_refresh_tokens_hash_key unique (token_hash)
 );
 

package/templates/be/auth-lite/src/modules/domain/identity/persistence/entities/identity-refresh-token.entity.ts

@@ -31,4 +31,8 @@ export class IdentityRefreshTokenEntity {
     /** When the token was rotated away, or null while it is the live one. */
     @Column({ name: "used_at", type: "timestamptz", nullable: true })
     usedAt!: Date | null
+
+    /** How many successors replays of this token obtained within the grace window after its rotation (bounded). */
+    @Column({ name: "raced_count", type: "integer", default: 0 })
+    racedCount!: number
 }

package/templates/be/auth-lite/src/modules/domain/identity/session-store.service.spec.ts

@@ -19,6 +19,7 @@ const row = (usedAt: Date | null): IdentityRefreshTokenEntity => ({
     createdAt: NOW,
     expiresAt: LATER,
     usedAt,
+    racedCount: 0,
 })
 
 const build = async (entityManager: MockEntityManager = mockEntityManager()) => {
@@ -39,11 +40,11 @@ describe("IdentitySessionStoreService.transaction", () => {
         })
 
         expect(entityManager.insert).toHaveBeenCalledWith(IdentitySessionEntity, { id: "s-1", userId: "u-1", createdAt: NOW, refreshedAt: NOW, userAgent: "agent", ip: "203.0.113.9" })
-        expect(entityManager.insert).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: null })
+        expect(entityManager.insert).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: null, racedCount: 0 })
         expect(transaction.commits).toBe(1)
     })
 
-    it("reads the token for update, marks it used and drops the expired ones", async () => {
+    it("reads the token for update, marks it used or raced and drops the expired ones", async () => {
         const { subject, entityManager } = await build(
             mockEntityManager({
                 findOne: [[IdentityRefreshTokenEntity, row(NOW)], [IdentityRefreshTokenEntity, null]],
@@ -56,13 +57,15 @@ describe("IdentitySessionStoreService.transaction", () => {
         const missing = await subject.transaction((tx) => tx.findTokenForUpdate("h-2"))
         await subject.transaction(async (tx) => {
             await tx.markTokenUsed("t-1", NOW)
+            await tx.markTokenRaced("t-1", 2)
             await tx.deleteExpiredTokens("u-1", NOW)
         })
 
-        expect(found).toEqual({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: NOW })
+        expect(found).toEqual({ id: "t-1", sessionId: "s-1", userId: "u-1", tokenHash: "h-1", expiresAt: LATER, usedAt: NOW, racedCount: 0 })
         expect(missing).toBeNull()
         expect(entityManager.findOne).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { where: { tokenHash: "h-1" }, lock: { mode: "pessimistic_write" } })
         expect(entityManager.update).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1" }, { usedAt: NOW })
+        expect(entityManager.update).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { id: "t-1" }, { racedCount: 2 })
         expect(entityManager.delete).toHaveBeenCalledWith(IdentityRefreshTokenEntity, { userId: "u-1", expiresAt: LessThan(NOW) })
     })
 

package/templates/be/auth-lite/src/modules/domain/identity/session-store.service.ts

@@ -13,6 +13,7 @@ const recordOf = (row: IdentityRefreshTokenEntity): RefreshTokenRecord => ({
     tokenHash: row.tokenHash,
     expiresAt: row.expiresAt,
     usedAt: row.usedAt,
+    racedCount: row.racedCount,
 })
 
 const transactionOf = (scoped: EntityManager): SessionTransaction => ({
@@ -34,6 +35,7 @@ const transactionOf = (scoped: EntityManager): SessionTransaction => ({
             tokenHash: token.tokenHash,
             expiresAt: token.expiresAt,
             usedAt: null,
+            racedCount: 0,
         })
     },
     findTokenForUpdate: async (tokenHash) => {
@@ -43,6 +45,9 @@ const transactionOf = (scoped: EntityManager): SessionTransaction => ({
     markTokenUsed: async (tokenId, at) => {
         await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { usedAt: at })
     },
+    markTokenRaced: async (tokenId, racedCount) => {
+        await scoped.update(IdentityRefreshTokenEntity, { id: tokenId }, { racedCount })
+    },
     deleteExpiredTokens: async (userId, before) => {
         await scoped.delete(IdentityRefreshTokenEntity, { userId, expiresAt: LessThan(before) })
     },
@@ -69,7 +74,7 @@ export class IdentitySessionStoreService implements SessionStore {
         await this.entityManager.update(IdentitySessionEntity, { id: sessionId }, { refreshedAt: now })
     }
 
-    /** Ends one session; its tokens go with it (the foreign key cascades). */
+    /** Ends one session and revokes every token of it (the foreign key cascades). */
     async closeSession(sessionId: string): Promise<void> {
         await this.entityManager.delete(IdentitySessionEntity, { id: sessionId })
     }