@aurorajs.dev/catalyst-cli 1.0.1 → 1.1.3

package/dist/generator/engine/code-writer/code-writer.js

@@ -1,34 +1,89 @@
+import chalk from 'chalk';
 import * as fs from 'node:fs';
 import { join } from 'node:path';
-import { IndentationText, Node, Project, QuoteKind } from 'ts-morph';
+import { IndentationText, Node, Project, QuoteKind, SyntaxKind, } from 'ts-morph';
 import { NewLineKind } from 'typescript';
-import { ADMIN_CONTAINER, API_CONTAINER, APP_CONTAINER, DASHBOARD_CONTAINER, DASHBOARD_TRANSLATIONS, SCHEMA_DEFINITION_EXTENSION, } from '../../domain/config.js';
-import { getForeignRelationshipProperties, getWithoutTimestampsProperties, hasI18nProperties, uuid, } from '../../domain/property-filters.js';
-import { toCamelCase, toKebabCase, toPascalCase, } from '../../utils/string-utils.js';
+import { ADMIN_CONTAINER, API_CONTAINER, APP_CONTAINER, DASHBOARD_CONTAINER, DASHBOARD_TRANSLATIONS, DETAIL_MODE, SCHEMA_DEFINITION_EXTENSION, } from '../../domain/config.js';
+import { selectRelevantCrossBcCandidates } from '../../domain/cross-bc-relations-discovery.js';
+import { isModuleGenerated } from '../../domain/module-resolution.js';
+import { getEnumProperties, getForeignRelationshipProperties, getWithoutTimestampsProperties, isOperationExcluded, uuid, } from '../../domain/property-filters.js';
+import { getPropertyEnumOptions } from '../../domain/property-mappers.js';
+import { buildBcRelationsModuleEntry, buildCustomFieldValueRelationsModuleEntry, buildI18nTableRelationsModuleEntry, } from '../../domain/relations-builder.js';
+import { emptyBcRelationsSkeleton, upsertBcRelationsFile, upsertCrossBcRelationEntry, } from '../../utils/relations-file.js';
+import { humanizeEnumOption, toCamelCase, toKebabCase, toPascalCase, } from '../../utils/string-utils.js';
+import { isFileContentIgnored } from '../ignored-file.js';
 import { formatCode } from '../prettier-engine.js';
 import { ArrayDriver } from './drivers/array.driver.js';
 import { ImportDriver } from './drivers/import.driver.js';
+import { ObjectDriver } from './drivers/object.driver.js';
 import { getInitializer } from './helpers.js';
+/**
+ * `CodeWriter` — the second write engine. It patches SHARED files (accumulated
+ * by several modules — bounded-context routes, navigation, icon providers,
+ * NestJS modules, `relations.ts`, translations, permission seeds) in place via
+ * ts-morph or direct JSON rewrite, as opposed to `file-writer.ts`, which
+ * renders one `.eta` template per file.
+ *
+ * harden-generator-emission-contract (section 4, follow-up #5): every patcher
+ * honours the SAME `ignored file` sentinel `file-writer.ts` already checked,
+ * and every EFFECTIVE mutation (content actually changed) is recorded in
+ * `patchedFilePaths` and optionally logged under `--verbose`. A run that
+ * changes nothing makes zero writes and logs zero mutations.
+ *
+ * The sentinel means TWO different things, decided by the target file — see
+ * `assertNotIgnoredForRequiredAppend` for the seven REQUIRED-APPEND targets
+ * and `checkIgnored` for the FULL-REWRITE ones:
+ *
+ * | Shape           | Patchers                                                   | `ignored file` means |
+ * | --------------- | ---------------------------------------------------------- | -------------------- |
+ * | FULL-REWRITE    | routes, navigation, icons aggregator, translations, nav-main | skip the file, silently — an honest whole-file opt-out |
+ * | REQUIRED-APPEND | BC seed, BC relations, the two `@config/drizzle` registries, `@api/<bc>/<bc>.module.ts`, `app.module.ts`, `@app/<bc>/index.ts` | HARD STOP, but only when an append is genuinely due |
+ *
+ * Two-entry remedy matrix (design D2) — READ THIS before adding a third:
+ *
+ * | Symptom                                          | Remedy                                                            |
+ * | ------------------------------------------------- | ------------------------------------------------------------------ |
+ * | "this operation/route must not exist"              | `excludedOperations` in the aggregate's YAML (schema-first; already honoured by `generateFrontRoutes`). |
+ * | "this shared file is fully hand-maintained now"    | `catalyst origin ignore <path>` — the sentinel this class checks. **Only valid on a FULL-REWRITE target.** On a REQUIRED-APPEND target the marker does not opt the file out: it aborts `catalyst generate` for every module of that bounded context that still needs an entry. There the honest remedies are narrower — take over the whole registration by hand and keep it current yourself, or leave the file to the generator (its patch is additive and idempotent; it never rewrites the file wholesale, so hand edits elsewhere in it survive untouched). |
+ *
+ * There is NO third remedy. Do not add heuristics that guess a deliberately
+ * deleted line was intentional (design D2) — that failure mode is silent,
+ * which is strictly worse than the current visible `.origin`/patch-log
+ * behaviour.
+ */
 export class CodeWriter {
     aggregateName;
     apiDirectory;
     appDirectory;
     boundedContextName;
+    detailMode;
+    excludedOperations;
     hasI18n;
+    i18nStrategy;
     moduleName;
     moduleNames;
     srcDirectory;
+    formatCode;
+    ignoredFilePaths = new Set();
+    logger;
+    patchedFilePaths = new Set();
     project;
-    savedFiles = new Set();
+    verbose;
     constructor(opts) {
         this.aggregateName = opts.aggregateName;
         this.apiDirectory = opts.apiDirectory;
         this.appDirectory = opts.appDirectory;
         this.boundedContextName = opts.boundedContextName;
+        this.detailMode = opts.detailMode;
+        this.excludedOperations = opts.excludedOperations ?? [];
+        this.formatCode = opts.formatCode ?? formatCode;
         this.hasI18n = opts.hasI18n;
+        this.i18nStrategy = opts.i18nStrategy;
+        this.logger = opts.logger ?? console;
         this.moduleName = opts.moduleName;
         this.moduleNames = opts.moduleNames;
         this.srcDirectory = opts.srcDirectory;
+        this.verbose = opts.verbose ?? false;
         this.project = new Project({
             manipulationSettings: {
                 indentationText: IndentationText.TwoSpaces,
@@ -40,7 +95,7 @@ export class CodeWriter {
             tsConfigFilePath: join(process.cwd(), opts.srcDirectory, '..', 'tsconfig.json'),
         });
     }
-    addSeedPermissions() {
+    async addSeedPermissions() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const bcCamel = toCamelCase(this.boundedContextName);
         const modCamel = toCamelCase(this.moduleName);
@@ -48,8 +103,17 @@ export class CodeWriter {
         if (!fs.existsSync(seedFilePath))
             return;
         const sourceFile = this.project.addSourceFileAtPath(seedFilePath);
+        const originalText = sourceFile.getFullText();
         const regionTag = `${bcCamel}.${modCamel}`;
-        if (sourceFile.getFullText().includes(`'${regionTag}.access'`)) {
+        // Idempotence by module natural key: ANY permission of this module counts,
+        // not one specific action. A hand-kept block may deliberately omit
+        // `.access`/`.upsert` (nobody consumes them), and probing for `.access`
+        // alone appended a full duplicate block — duplicate names break the boot
+        // (Postgres 21000, single INSERT with ON CONFLICT on name). The leading
+        // quote anchors the string literal; the trailing dot avoids prefix
+        // collisions between camelCase siblings (`productionOrder` vs
+        // `productionOrderHeader`).
+        if (sourceFile.getFullText().includes(`'${regionTag}.`)) {
             return;
         }
         const permissionsDecl = sourceFile.getVariableDeclaration('permissions');
@@ -89,19 +153,24 @@ export class CodeWriter {
         ].join('\n');
         const arrayEnd = permissionsArray.getEnd() - 1;
         sourceFile.insertText(arrayEnd, block + '\n');
-        this.saveAndTrack(sourceFile);
+        await this.saveAndTrack(sourceFile, originalText, 'addSeedPermissions', `the "${this.boundedContextName}.${this.moduleName}.*" permission block`);
     }
-    declareBackApplicationItemsInModule() {
+    async declareBackApplicationItemsInModule() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const bcPascal = toPascalCase(this.boundedContextName);
         const modKebab = toKebabCase(this.moduleName);
         const modPascal = toPascalCase(this.moduleName);
-        const sourceFile = this.project.addSourceFileAtPath(join(process.cwd(), this.srcDirectory, this.apiDirectory, bcKebab, `${bcKebab}.module.ts`));
+        const modulePath = join(process.cwd(), this.srcDirectory, this.apiDirectory, bcKebab, `${bcKebab}.module.ts`);
+        const sourceFile = this.project.addSourceFileAtPath(modulePath);
+        const originalText = sourceFile.getFullText();
         const decoratorArgs = this.getModuleDecoratorArguments(sourceFile, `${bcPascal}Module`, 'Module');
         const providersArray = getInitializer(decoratorArgs.getProperty('providers'));
         const controllersArray = getInitializer(decoratorArgs.getProperty('controllers'));
+        // No model registration in the Drizzle world: the module's pgTable is
+        // registered in the per-BC relations file (`<bc>.relations.ts`, see
+        // declareBackSchemaInBcRelations), NOT in the NestJS module's `imports:`
+        // array — the `SequelizeModule.forFeature` anchor (and its throw) is gone.
         const appImports = [
-            `${bcPascal}Models`,
             `${bcPascal}Handlers`,
             `${bcPascal}Services`,
             `${bcPascal}Repositories`,
@@ -112,8 +181,6 @@ export class CodeWriter {
             `${bcPascal}${modPascal}ApiResolvers`,
         ];
         ImportDriver.createImportItems(sourceFile, `./${modKebab}`, apiImports);
-        const modelArrayArgument = this.getModelArrayArgument(decoratorArgs);
-        ArrayDriver.addArrayItem(sourceFile, `...${bcPascal}Models`, modelArrayArgument);
         const providerItems = [
             `...${bcPascal}Handlers`,
             `...${bcPascal}Services`,
@@ -122,12 +189,14 @@ export class CodeWriter {
         providerItems.push(`...${bcPascal}${modPascal}ApiResolvers`);
         ArrayDriver.addArrayItems(sourceFile, providerItems, providersArray);
         ArrayDriver.addArrayItem(sourceFile, `...${bcPascal}${modPascal}ApiControllers`, controllersArray);
-        this.saveAndTrack(sourceFile);
+        await this.saveAndTrack(sourceFile, originalText, 'declareBackApplicationItemsInModule', `the "${bcPascal}${modPascal}ApiResolvers"/"${bcPascal}${modPascal}ApiControllers" resolver and controller registration`);
     }
-    declareBackBoundedContextModuleInApplicationModule() {
+    async declareBackBoundedContextModuleInApplicationModule() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const bcPascal = toPascalCase(this.boundedContextName);
-        const sourceFile = this.project.addSourceFileAtPath(join(process.cwd(), this.srcDirectory, 'app.module.ts'));
+        const appModulePath = join(process.cwd(), this.srcDirectory, 'app.module.ts');
+        const sourceFile = this.project.addSourceFileAtPath(appModulePath);
+        const originalText = sourceFile.getFullText();
         const decoratorArgs = this.getModuleDecoratorArguments(sourceFile, 'AppModule', 'Module');
         const modules = ImportDriver.getImportedDeclarations(sourceFile);
         if (modules.includes(`${bcPascal}Module`))
@@ -135,14 +204,123 @@ export class CodeWriter {
         ImportDriver.createImportItems(sourceFile, `${API_CONTAINER}/${bcKebab}/${bcKebab}.module`, [`${bcPascal}Module`]);
         const importsArray = getInitializer(decoratorArgs.getProperty('imports'));
         ArrayDriver.addArrayItems(sourceFile, [`${bcPascal}Module`], importsArray);
-        this.saveAndTrack(sourceFile);
+        await this.saveAndTrack(sourceFile, originalText, 'declareBackBoundedContextModuleInApplicationModule', `the "${bcPascal}Module" import into AppModule`);
     }
-    declareFrontBoundedContext() {
+    /**
+     * Upserts a module's `pgTable` entry into the per-BC Drizzle relations
+     * assembly file (`@app/<bc>/<bc>.relations.ts`) — the successor of the
+     * `SequelizeModule.forFeature` model registration (design D3). The anchors
+     * are structural (ts-morph AST, design D12, group 13 amendment — no
+     * `AURORA:*` marker comments): the barrel import, the `<bcCamel>Schema`
+     * object literal property, and the `defineRelations(...)` callback's
+     * returned object literal property. Regenerating one module touches only
+     * that module's property; regenerating twice produces byte-identical
+     * output.
+     *
+     * LOCATION (F5 group 12.1, decisión del usuario 2026-07-04): moved from
+     * `@api/<bc>/` to `@app/<bc>/` (BC root) — the file is pure persistence
+     * infrastructure (its only consumers are the central Drizzle assembly +
+     * its spec; no `<bc>.module.ts` imports it), and it imports every table
+     * FROM `@app/<bc>/*` already. It landed in `@api` by inertia (successor of
+     * `SequelizeModule.forFeature`, which WAS module-consumed); `@app` is the
+     * correct home now, mirroring how `<bc>.module.ts` sits at the `@api` BC
+     * root for the opposite (consumed-by-DI) reason.
+     *
+     * When the file does not exist yet (FIRST module of the BC), it is created
+     * from the empty skeleton instead of throwing — the throw in the old
+     * `getModelArrayArgument` was a fossil of the anchor being a library import.
+     * A file that exists but does not export the `<bcCamel>Schema` object
+     * literal, or does not call `defineRelations(...)` with an object-literal
+     * callback body, is treated as corrupted and reported, never silently
+     * rewritten.
+     */
+    async declareBackSchemaInBcRelations(schema) {
+        const bcKebab = toKebabCase(this.boundedContextName);
+        const bcCamel = toCamelCase(this.boundedContextName);
+        const relationsPath = join(process.cwd(), this.srcDirectory, this.appDirectory, bcKebab, `${bcKebab}.relations.ts`);
+        if (!fs.existsSync(relationsPath)) {
+            fs.mkdirSync(join(relationsPath, '..'), { recursive: true });
+            fs.writeFileSync(relationsPath, emptyBcRelationsSkeleton(bcKebab), 'utf8');
+        }
+        const sourceFile = this.project.addSourceFileAtPath(relationsPath);
+        const originalText = sourceFile.getFullText();
+        const entry = buildBcRelationsModuleEntry(schema);
+        // Cross-BC entries (design.md D1/D3, `generate-cross-bc-drizzle-relations`,
+        // tasks.md group 2) belong at the merged assembly point
+        // (`@config/drizzle/aurora-drizzle-schema.ts`), never here: THIS file's
+        // `defineRelations(<bcCamel>Schema, ...)` is scoped to the bounded
+        // context's OWN schema map and cannot address a foreign table — writing
+        // one in would produce an unresolvable `r.<foreignKey>` reference.
+        // `buildBcRelationsModuleEntry` builds cross-BC entries too (group 2
+        // opened that gate), tagged `isCrossBc`, precisely so the bidirectional
+        // trigger at the end of THIS method (group 5,
+        // `resolveAndUpsertCrossBcRelations`) can route them to the cross-BC
+        // upsert (group 3). Filtering them out here is what keeps this file's
+        // contract unchanged while that other path carries them.
+        const sameBcRelations = entry.relations.filter((relation) => !relation.isCrossBc);
+        upsertBcRelationsFile(sourceFile, bcCamel, { ...entry, relations: sameBcRelations });
+        // hasCustomFields (design.md D2, add-custom-fields change): the satellite
+        // value table is not driven by aggregateProperties, so it needs a SECOND,
+        // independent upsert for its own schema-map key — otherwise `r.<key>` in
+        // the parent's `customFieldValues` expression above would not resolve.
+        // Returns null (no-op) for every module that has not opted in.
+        const customFieldValueEntry = buildCustomFieldValueRelationsModuleEntry(schema);
+        if (customFieldValueEntry) {
+            upsertBcRelationsFile(sourceFile, bcCamel, customFieldValueEntry);
+        }
+        // i18nStrategy: 'table' (design.md D5, add-i18n-table-codegen group 5):
+        // same rationale as the customFieldValue entry above — the companion's
+        // own schema-map key needs a separate upsert so `r.<key>` resolves inside
+        // the parent's `<module>I18n` relation expression.
+        const i18nTableEntry = buildI18nTableRelationsModuleEntry(schema);
+        if (i18nTableEntry) {
+            upsertBcRelationsFile(sourceFile, bcCamel, i18nTableEntry);
+        }
+        // Judgment Day round 1, finding 1a: the sentinel gate used to sit here as
+        // an early `return`, which ALSO skipped the two registrations below — two
+        // calls that target DIFFERENT files with their OWN independent ignore
+        // state. Round 2, finding 1 moved it once more, into `saveAndTrack`: it
+        // now gates ONLY the write to `relations.ts`, and only when that write is
+        // genuinely needed, so an already-registered module regenerates against
+        // an adopted relations file without aborting. Each registration below
+        // asserts against its OWN target file, on the same terms.
+        await this.saveAndTrack(sourceFile, originalText, 'declareBackSchemaInBcRelations', `the Drizzle relations entry for "${schema.boundedContextName}/${schema.moduleName}"`);
+        // auto-register-bc-drizzle-schema (design.md D1): this method already
+        // fires once per module (back.handler.ts addReferences) and once per
+        // pivot with the PIVOT's own bounded context (back.handler.ts
+        // addPivotReferences constructs the CodeWriter with
+        // `boundedContextName: pivot.boundedContextName`), so piggybacking here
+        // gives correct BC attribution for both cases for free. The aggregation
+        // registration is idempotent by BC name (D2), so the repeated per-module/
+        // per-pivot firing converges to a single spread pair per BC.
+        await this.registerBcInDrizzleAggregation(this.boundedContextName);
+        // Cross-BC bidirectional trigger (design.md D3, tasks.md group 5):
+        // piggybacks on the SAME call site for the SAME reason as the
+        // aggregation registration above — this method already fires once per
+        // module/pivot with correct BC/module attribution (`schema`, not
+        // `this.boundedContextName`, since a pivot's own identity lives on the
+        // pseudo-schema `buildPivotSchema` built). Resolves and upserts every
+        // declared cross-BC relation whose OWNER or TARGET is THIS module: its
+        // own (filtered out of `sameBcRelations` above, tagged `isCrossBc`) and
+        // every OTHER already-declared relation elsewhere in the project that
+        // targets this module, now that it exists — the mechanism that lets
+        // "generate A, then generate B" complete the pair with no manual step.
+        await this.resolveAndUpsertCrossBcRelations(selectRelevantCrossBcCandidates(schema, process.cwd()));
+        // harden-generator-emission-contract (Defect D): piggybacks on the SAME
+        // call site as the Drizzle registration above, per-module (not per-BC —
+        // `schema`, not `this.boundedContextName`), so a pivot's own aggregate
+        // registers under its own name too.
+        await this.registerModuleInFieldSchemaRegistry(schema);
+    }
+    async declareFrontBoundedContext() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const routesPath = join(process.cwd(), this.srcDirectory, ADMIN_CONTAINER, 'routes.ts');
         if (!fs.existsSync(routesPath))
             return;
+        if (this.checkIgnored(routesPath))
+            return;
         const sourceFile = this.project.addSourceFileAtPath(routesPath);
+        const originalText = sourceFile.getFullText();
         // Find the children array inside the default-exported route object.
         // Structure: export default [{ path: '', children: [ ... ] }]
         const defaultExport = sourceFile.getExportAssignment((d) => !d.isExportEquals());
@@ -150,7 +328,9 @@ export class CodeWriter {
             return;
         // Handle both `export default [...]` and `export default [...] satisfies Routes`
         let expr = defaultExport.getExpression();
-        if (expr && 'getExpression' in expr && expr.getKindName() === 'SatisfiesExpression') {
+        if (expr &&
+            'getExpression' in expr &&
+            expr.getKindName() === 'SatisfiesExpression') {
             expr = expr.getExpression();
         }
         const routesArray = expr;
@@ -172,63 +352,63 @@ export class CodeWriter {
             if (pathValue.getText() === `'${bcKebab}'`)
                 return;
         }
-        childrenArray.addElement(`{\n  path: '${bcKebab}',\n  loadChildren: () => import('./bounded-contexts/${bcKebab}/${bcKebab}.routes').then((m) => m.${toCamelCase(this.boundedContextName)}Routes),\n}`, { useNewLines: true });
-        this.saveAndTrack(sourceFile);
+        childrenArray.addElement(`{\n  path: '${bcKebab}',\n  loadChildren: () => import('./apps/${bcKebab}/${bcKebab}.routes').then((m) => m.${toCamelCase(this.boundedContextName)}Routes),\n}`, { useNewLines: true });
+        await this.saveAndTrack(sourceFile, originalText, 'declareFrontBoundedContext');
     }
-    declareFrontComponents() {
+    async declareFrontComponents() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const bcPascal = toPascalCase(this.boundedContextName);
         const modKebab = toKebabCase(this.moduleName);
         const modPascal = toPascalCase(this.moduleName);
-        const sourceFile = this.project.addSourceFileAtPath(join(process.cwd(), this.srcDirectory, DASHBOARD_CONTAINER, bcKebab, `${bcKebab}.module.ts`));
+        const bcModulePath = join(process.cwd(), this.srcDirectory, DASHBOARD_CONTAINER, bcKebab, `${bcKebab}.module.ts`);
+        if (this.checkIgnored(bcModulePath))
+            return;
+        const sourceFile = this.project.addSourceFileAtPath(bcModulePath);
+        const originalText = sourceFile.getFullText();
         const decoratorArgs = this.getModuleDecoratorArguments(sourceFile, `${bcPascal}Module`, 'NgModule');
         const declarationsArray = getInitializer(decoratorArgs.getProperty('declarations'));
         ImportDriver.createImportItems(sourceFile, `./${modKebab}/${modKebab}-list.component`, [`${modPascal}ListComponent`]);
         ImportDriver.createImportItems(sourceFile, `./${modKebab}/${modKebab}-detail.component`, [`${modPascal}DetailComponent`]);
         ArrayDriver.addArrayItems(sourceFile, [`${modPascal}DetailComponent`, `${modPascal}ListComponent`], declarationsArray);
-        this.saveAndTrack(sourceFile);
-    }
-    async formatSavedFiles() {
-        for (const filePath of this.savedFiles) {
-            const code = fs.readFileSync(filePath, 'utf8');
-            // eslint-disable-next-line no-await-in-loop
-            const formatted = await formatCode(code, filePath);
-            if (formatted !== code) {
-                fs.writeFileSync(filePath, formatted, 'utf8');
-            }
-        }
+        await this.saveAndTrack(sourceFile, originalText, 'declareFrontComponents');
     }
-    generateBackAppBoundedContextReferences(properties, excluded = []) {
+    async generateBackAppBoundedContextReferences(_properties, excluded = []) {
         if (excluded.includes('src/@app/**'))
             return;
         const bcKebab = toKebabCase(this.boundedContextName);
         const bcPascal = toPascalCase(this.boundedContextName);
         const modKebab = toKebabCase(this.moduleName);
         const modPascal = toPascalCase(this.moduleName);
-        const sourceFile = this.project.addSourceFileAtPath(join(process.cwd(), this.srcDirectory, this.appDirectory, bcKebab, 'index.ts'));
+        const bcIndexPath = join(process.cwd(), this.srcDirectory, this.appDirectory, bcKebab, 'index.ts');
+        const sourceFile = this.project.addSourceFileAtPath(bcIndexPath);
+        const originalText = sourceFile.getFullText();
+        // No Model entry (Drizzle has no model classes — the pgTable symbol is
+        // exported by the module barrel and consumed by the per-BC relations
+        // file). Under `i18nStrategy: 'table'` the module barrel ALSO exports a
+        // companion `<Bc>Drizzle<Mod>I18nRepository` (one row per (parent, lang)
+        // pair) that the create/update/delete services inject — it must be
+        // registered in `<Bc>Repositories` alongside the base repo, or the NestJS
+        // boot fails to resolve `<Bc>Create<Mod>Service`'s companion dependency
+        // (a runtime DI error tsc/compile-check cannot catch).
+        const isI18nTable = this.hasI18n && this.i18nStrategy === 'table';
         const imports = [
             `${bcPascal}${modPascal}Handlers`,
             `${bcPascal}${modPascal}Services`,
-            `${bcPascal}${modPascal}Model`,
-            `${bcPascal}Sequelize${modPascal}Repository`,
+            `${bcPascal}Drizzle${modPascal}Repository`,
         ];
+        if (isI18nTable) {
+            imports.push(`${bcPascal}Drizzle${modPascal}I18nRepository`);
+        }
         ImportDriver.createImportItems(sourceFile, `./${modKebab}`, imports);
         ArrayDriver.addArrayItem(sourceFile, `...${bcPascal}${modPascal}Handlers`, `${bcPascal}Handlers`);
         ArrayDriver.addArrayItem(sourceFile, `...${bcPascal}${modPascal}Services`, `${bcPascal}Services`);
-        ArrayDriver.addArrayItem(sourceFile, `${bcPascal}${modPascal}Model`, `${bcPascal}Models`);
-        ArrayDriver.addArrayItem(sourceFile, `${bcPascal}Sequelize${modPascal}Repository`, `${bcPascal}Repositories`);
-        if (hasI18nProperties(properties)) {
-            const i18nImports = [
-                `${bcPascal}${modPascal}I18nModel`,
-                `${bcPascal}Sequelize${modPascal}I18nRepository`,
-            ];
-            ImportDriver.createImportItems(sourceFile, `./${modKebab}`, i18nImports);
-            ArrayDriver.addArrayItem(sourceFile, `${bcPascal}${modPascal}I18nModel`, `${bcPascal}Models`);
-            ArrayDriver.addArrayItem(sourceFile, `${bcPascal}Sequelize${modPascal}I18nRepository`, `${bcPascal}Repositories`);
-        }
-        this.saveAndTrack(sourceFile);
-    }
-    generateBackTestingForeignReferences(properties) {
+        ArrayDriver.addArrayItem(sourceFile, `${bcPascal}Drizzle${modPascal}Repository`, `${bcPascal}Repositories`);
+        if (isI18nTable) {
+            ArrayDriver.addArrayItem(sourceFile, `${bcPascal}Drizzle${modPascal}I18nRepository`, `${bcPascal}Repositories`);
+        }
+        await this.saveAndTrack(sourceFile, originalText, 'generateBackAppBoundedContextReferences', `the "${bcPascal}${modPascal}Handlers"/"${bcPascal}${modPascal}Services"/"${bcPascal}Drizzle${modPascal}Repository" handler, service and repository registration`);
+    }
+    async generateBackTestingForeignReferences(properties) {
         const bcKebab = toKebabCase(this.boundedContextName);
         const foreignRelationships = getForeignRelationshipProperties(properties, this.boundedContextName);
         const cliterDir = join(process.cwd(), 'cliter', bcKebab);
@@ -241,11 +421,13 @@ export class CodeWriter {
             for (const yamlFile of yamlFiles) {
                 const e2eTestFile = yamlFile.replace(SCHEMA_DEFINITION_EXTENSION, '.e2e-spec.ts');
                 const e2eTestPath = join(process.cwd(), 'test', 'acceptance', bcKebab, e2eTestFile);
-                if (fs.existsSync(e2eTestPath)) {
+                if (fs.existsSync(e2eTestPath) && !this.checkIgnored(e2eTestPath)) {
                     const sourceFile = this.project.addSourceFileAtPath(e2eTestPath);
+                    const originalText = sourceFile.getFullText();
                     // NOTE: Foreign module imports/registrations are disabled upstream
                     // (can be micro-services). Keeping the save in case future logic is added.
-                    this.saveAndTrack(sourceFile);
+                    // eslint-disable-next-line no-await-in-loop
+                    await this.saveAndTrack(sourceFile, originalText, 'generateBackTestingForeignReferences');
                 }
             }
         }
@@ -258,7 +440,7 @@ export class CodeWriter {
      * fully overwritten on each regen — no preservation regions, no incremental prune.
      * No-op when `{bc}.navigation.ts` is missing or has no `{bcCamel}Navigation` declaration.
      */
-    generateFrontIconsProviders(srcDirectory, boundedContextName) {
+    async generateFrontIconsProviders(srcDirectory, boundedContextName) {
         const bcKebab = toKebabCase(boundedContextName);
         const bcCamel = toCamelCase(boundedContextName);
         const navFilePath = join(process.cwd(), srcDirectory, DASHBOARD_CONTAINER, bcKebab, `${bcKebab}.navigation.ts`);
@@ -295,26 +477,46 @@ export class CodeWriter {
         }
         const sortedIcons = [...icons].sort();
         const aggregatorPath = join(process.cwd(), srcDirectory, DASHBOARD_CONTAINER, bcKebab, `${bcKebab}-icons.providers.ts`);
+        // Checked on the WRITE target (the aggregator), not `navFilePath` above,
+        // which this method only ever reads. Checked with plain `fs` (not via
+        // ts-morph) because `createSourceFile({ overwrite: true })` below builds
+        // its in-memory content from scratch — it never reads the aggregator's
+        // current disk content, so it cannot see the sentinel itself.
+        if (this.checkIgnored(aggregatorPath))
+            return;
+        const originalText = fs.existsSync(aggregatorPath)
+            ? fs.readFileSync(aggregatorPath, 'utf8')
+            : '';
         const content = buildIconsAggregatorContent(bcKebab, bcCamel, sortedIcons);
         const aggregatorSourceFile = this.project.createSourceFile(aggregatorPath, content, { overwrite: true });
-        this.saveAndTrack(aggregatorSourceFile);
+        await this.saveAndTrack(aggregatorSourceFile, originalText, 'generateFrontIconsProviders');
     }
     /**
      * Append a NavItem for the current module inside `{bc}.navigation.ts` of the admin dashboard.
-     * Idempotent — silently skips if the entry url already exists. No-op when the BC does not
-     * use the dashboard (file/variable/items array missing). When `outlineIcon` is provided
-     * it becomes the NavItem `icon`.
+     * Idempotent — silently skips if the entry url already exists AND all permission fields are
+     * already correct. No-op when the BC does not use the dashboard (file/variable/items array
+     * missing). When `outlineIcon` is provided it becomes the NavItem `icon`.
+     *
+     * Permission backfill rules (add-if-missing, NEVER overwrite):
+     *  - Group object → `permission: '<bc>.access'` (module-section visibility)
+     *  - Child item   → `permission: '<bc>.<mod>.access'` (the module's view/visibility permission)
      */
     // eslint-disable-next-line max-params
-    generateFrontNavigation(srcDirectory, boundedContextName, moduleName, moduleNames, outlineIcon) {
+    async generateFrontNavigation(srcDirectory, boundedContextName, moduleName, moduleNames, outlineIcon) {
         const bcKebab = toKebabCase(boundedContextName);
         const bcCamel = toCamelCase(boundedContextName);
         const modKebab = toKebabCase(moduleName);
+        const modCamel = toCamelCase(moduleName);
         const modNamesPascal = toPascalCase(moduleNames);
+        const groupPermission = `${bcCamel}.access`;
+        const childPermission = `${bcCamel}.${modCamel}.access`;
         const navFilePath = join(process.cwd(), srcDirectory, DASHBOARD_CONTAINER, bcKebab, `${bcKebab}.navigation.ts`);
         if (!fs.existsSync(navFilePath))
             return;
+        if (this.checkIgnored(navFilePath))
+            return;
         const sourceFile = this.project.addSourceFileAtPath(navFilePath);
+        const originalText = sourceFile.getFullText();
         // Locate `export const {bcCamel}Navigation: NavItem[] = [{ ..., items: [] }]`
         const navigation = sourceFile.getVariableDeclaration(`${bcCamel}Navigation`);
         if (!navigation)
@@ -329,44 +531,95 @@ export class CodeWriter {
         if (!itemsProp)
             return;
         const itemsArray = getInitializer(itemsProp);
-        // Idempotent: skip when a NavItem with this url already exists
+        let mutated = false;
+        // ── Group permission backfill (add-if-missing, never overwrite) ──────────
+        mutated =
+            ensureStringProperty(bcNavItem, 'permission', groupPermission, itemsProp) || mutated;
+        // ── Check whether a child with this url already exists, at ANY depth ─────
+        // `NavSubItem.items` nests to arbitrary depth, so the lookup must descend.
         const targetUrl = `'/${bcKebab}/${modKebab}'`;
-        for (const element of itemsArray.getElements()) {
-            const urlProp = element.getProperty('url');
-            if (!urlProp)
-                continue;
-            const urlValue = getInitializer(urlProp);
-            if (urlValue.getText() === targetUrl)
-                return;
+        const findChildByUrl = (items) => {
+            if (!items?.getElements)
+                return undefined;
+            for (const element of items.getElements()) {
+                // A hand-curated array may hold spreads (`...commonItems`), which carry no properties.
+                if (!Node.isObjectLiteralExpression(element))
+                    continue;
+                const urlProp = element.getProperty('url');
+                if (urlProp) {
+                    const urlValue = getInitializer(urlProp);
+                    if (urlValue.getText() === targetUrl)
+                        return element;
+                }
+                const childItemsProp = element.getProperty('items');
+                if (!childItemsProp)
+                    continue;
+                const childItemsArr = getInitializer(childItemsProp);
+                const foundInChild = findChildByUrl(childItemsArr);
+                if (foundInChild)
+                    return foundInChild;
+            }
+            return undefined;
+        };
+        const existingChild = findChildByUrl(itemsArray);
+        if (existingChild) {
+            // ── Child backfill: add permission only if absent (never overwrite) ────
+            mutated =
+                ensureStringProperty(existingChild, 'permission', childPermission) ||
+                    mutated;
+        }
+        else {
+            // ── Append new child with permission ────────────────────────────────────
+            const iconPart = outlineIcon ? `, icon: '${outlineIcon}'` : '';
+            itemsArray.addElement(`{ title: '${modNamesPascal}', translation: 'navigation.${modNamesPascal}', url: '/${bcKebab}/${modKebab}'${iconPart}, permission: '${childPermission}' }`);
+            mutated = true;
+        }
+        if (mutated) {
+            await this.saveAndTrack(sourceFile, originalText, 'generateFrontNavigation');
         }
-        const iconPart = outlineIcon ? `, icon: '${outlineIcon}'` : '';
-        itemsArray.addElement(`{ title: '${modNamesPascal}', translation: 'navigation.${modNamesPascal}', url: '/${bcKebab}/${modKebab}'${iconPart} }`);
-        this.saveAndTrack(sourceFile);
     }
     /**
      * Ensure `{DASHBOARD_TRANSLATIONS}/navigation/{langCode}.json` contains a key for this module.
      * Key is `toPascalCase(moduleNames)` — must match the `translation: 'navigation.{key}'`
      * used by `generateFrontNavigation`. Missing keys get the PascalCase default placeholder.
-     * Writes JSON directly (not TS AST), so it does not flow through Prettier.
+     * Writes JSON directly (not TS AST); `writeJsonIfChanged` runs the candidate through the
+     * same Prettier path as disk before comparing.
+     *
+     * Judgment Day round 1, finding 2: this used to unconditionally re-sort every key via
+     * `sortObjectByKeys` before every write. A file whose keys were NOT already alphabetical
+     * (the common case — keys are appended as modules are added, not maintained sorted by
+     * hand) therefore differed from disk on EVERY run even when the module's own key was
+     * already present, logging a spurious mutation forever. Now the object is mutated
+     * in place (add-if-missing preserves existing insertion order) and NOT re-sorted — a
+     * genuinely new key is appended at the end, exactly where a hand edit would put it.
      */
-    generateFrontNavigationTranslation(langCode) {
+    async generateFrontNavigationTranslation(langCode) {
         const translationPath = join(process.cwd(), this.srcDirectory, '..', DASHBOARD_TRANSLATIONS, 'navigation', `${langCode}.json`);
-        const translationObject = JSON.parse(fs.readFileSync(translationPath, 'utf8'));
+        if (this.checkIgnored(translationPath))
+            return;
+        const originalContent = fs.readFileSync(translationPath, 'utf8');
+        const translationObject = JSON.parse(originalContent);
         const modsPascal = toPascalCase(this.moduleNames);
         if (translationObject[modsPascal] === undefined) {
             translationObject[modsPascal] = modsPascal;
         }
-        const sorted = sortObjectByKeys(translationObject);
-        fs.writeFileSync(translationPath, JSON.stringify(sorted, null, 2));
+        await this.writeJsonIfChanged(translationPath, originalContent, JSON.stringify(translationObject, null, 2), 'generateFrontNavigationTranslation');
     }
-    generateFrontRoutes() {
+    async generateFrontRoutes() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const modKebab = toKebabCase(this.moduleName);
         const modCamel = toCamelCase(this.moduleName);
         const routesFilePath = join(process.cwd(), this.srcDirectory, DASHBOARD_CONTAINER, bcKebab, `${bcKebab}.routes.ts`);
         if (!fs.existsSync(routesFilePath))
             return;
+        if (this.checkIgnored(routesFilePath))
+            return;
         const sourceFile = this.project.addSourceFileAtPath(routesFilePath);
+        // Captured BEFORE any manipulation — compared at the end so a run that
+        // changes nothing (already-reconciled file) makes ZERO disk writes,
+        // instead of unconditionally re-writing a hand-maintained file on every
+        // regen.
+        const originalText = sourceFile.getFullText();
         const bcCamel = toCamelCase(this.boundedContextName);
         const routesVarName = `${bcCamel}Routes`;
         const routesDecl = sourceFile.getVariableDeclaration(routesVarName);
@@ -375,27 +628,142 @@ export class CodeWriter {
         const routesArray = getInitializer(routesDecl);
         if (!routesArray)
             return;
-        for (const element of routesArray.getElements()) {
-            const pathProp = element.getProperty('path');
-            if (!pathProp)
+        const resolversModulePath = `./${modKebab}/data-access/${modKebab}.resolvers`;
+        const listResolverImport = `${modCamel}ListResolver`;
+        const newResolverImport = `${modCamel}NewResolver`;
+        const detailResolverImport = `${modCamel}DetailResolver`;
+        // ── path/element helpers ────────────────────────────────────────────
+        // Non-object elements (e.g. a `...sharedRoutes` spread) are skipped, never
+        // force-cast — an unchecked cast used to crash `.getProperty()` on them.
+        const getObjectElements = () => routesArray
+            .getElements()
+            .filter((element) => Node.isObjectLiteralExpression(element));
+        const findRouteElementsByPath = (path) => getObjectElements().filter((element) => getRoutePathValue(element) === path);
+        const findRouteElementByPath = (path) => findRouteElementsByPath(path)[0];
+        // Codegen ownership: a detail route is OURS only if its `loadComponent`
+        // points at THIS module's detail component. A hand-written custom route
+        // sharing the same `path` (e.g. a bespoke onboarding wizard mounted at
+        // `<module>/new`) must never be deleted during reconciliation.
+        const isOwnedDetailRoute = (element) => {
+            const loadComponentProp = element.getProperty('loadComponent');
+            const text = loadComponentProp?.getInitializer()?.getText();
+            return (text?.includes(`./${modKebab}/features/${modKebab}-detail.component`) ?? false);
+        };
+        // Insert new elements before a trailing wildcard (`path: '**'`) catch-all
+        // route when present — appending after it would put this module's routes
+        // behind the catch-all, where Angular's router never reaches them.
+        const addRouteElement = (text) => {
+            const elements = routesArray.getElements();
+            const last = elements.at(-1);
+            const lastIsWildcard = last !== undefined &&
+                Node.isObjectLiteralExpression(last) &&
+                getRoutePathValue(last) === '**';
+            if (lastIsWildcard) {
+                routesArray.insertElement(elements.length - 1, text, {
+                    useNewLines: true,
+                });
+            }
+            else {
+                routesArray.addElement(text, { useNewLines: true });
+            }
+        };
+        // ── List route: insert-if-missing, NEVER rewritten if present — it may
+        // carry user customizations (guards, extra data). Shared by both modes.
+        if (!findRouteElementByPath(modKebab)) {
+            addRouteElement(`{\n  path: '${modKebab}',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-list.component'),\n  resolve: { pagination: ${modCamel}ListResolver },\n}`);
+        }
+        // ── Detail routes: full set-reconciliation, in BOTH modes ───────────────
+        // `allDetailPaths` enumerates every path the generator can ever own for
+        // this module; `expectedDetailPaths` is the subset that must exist for
+        // the CURRENT detailMode/hasI18n. Anything owned-but-not-expected is
+        // removed (ALL matches — stale duplicates included, not just the first);
+        // anything expected-but-missing (and not already claimed by a hand-written
+        // route at that exact path) is inserted.
+        const allDetailPaths = [
+            `${modKebab}/new`,
+            `${modKebab}/new/:id/:langId`,
+            `${modKebab}/edit/:id`,
+            `${modKebab}/edit/:id/:langId`,
+        ];
+        // static-graphql-documents R1 follow-up: a `/new` (or `/edit/:id`) route
+        // pointing at a resolver whose mutation the backend doesn't implement
+        // (excludedOperations: create / updateById) is a dead click, not a
+        // harmless no-op — omit the whole path family, base AND i18n variant.
+        const createExcluded = isOperationExcluded({ excludedOperations: this.excludedOperations }, 'create');
+        const updateByIdExcluded = isOperationExcluded({ excludedOperations: this.excludedOperations }, 'updateById');
+        const expectedDetailPaths = (this.detailMode === DETAIL_MODE.DIALOG
+            ? []
+            : this.hasI18n
+                ? allDetailPaths
+                : [`${modKebab}/new`, `${modKebab}/edit/:id`]).filter((path) => {
+            if (createExcluded && (path === `${modKebab}/new` || path === `${modKebab}/new/:id/:langId`)) {
+                return false;
+            }
+            if (updateByIdExcluded &&
+                (path === `${modKebab}/edit/:id` || path === `${modKebab}/edit/:id/:langId`)) {
+                return false;
+            }
+            return true;
+        });
+        for (const path of allDetailPaths) {
+            if (expectedDetailPaths.includes(path))
                 continue;
-            const pathValue = getInitializer(pathProp);
-            if (pathValue.getText() === `'${modKebab}'`)
-                return;
+            for (const element of findRouteElementsByPath(path)) {
+                if (isOwnedDetailRoute(element))
+                    routesArray.removeElement(element);
+            }
         }
-        ImportDriver.createImportItems(sourceFile, `./${modKebab}/data-access/${modKebab}.resolvers`, [
-            `${modCamel}DetailResolver`,
-            `${modCamel}ListResolver`,
-            `${modCamel}NewResolver`,
-        ]);
-        // list, new, edit
-        routesArray.addElement(`{\n  path: '${modKebab}',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-list.component'),\n  resolve: { pagination: ${modCamel}ListResolver },\n}`, { useNewLines: true });
-        routesArray.addElement(`{\n  path: '${modKebab}/new',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-detail.component'),\n  data: { mode: 'new' },\n  resolve: { init: ${modCamel}NewResolver },\n}`, { useNewLines: true });
-        const editPath = this.hasI18n
-            ? `${modKebab}/edit/:id/:langId`
-            : `${modKebab}/edit/:id`;
-        routesArray.addElement(`{\n  path: '${editPath}',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-detail.component'),\n  data: { mode: 'edit' },\n  resolve: { item: ${modCamel}DetailResolver },\n}`, { useNewLines: true });
-        this.saveAndTrack(sourceFile);
+        const detailRouteText = {
+            // Translation edit — same component/data/resolver; the :langId segment
+            // drives the Content-Language header and the not-translatable-fields
+            // lock. Angular matches by exact segment count, so both routes coexist
+            // without ambiguity.
+            [`${modKebab}/edit/:id/:langId`]: `{\n  path: '${modKebab}/edit/:id/:langId',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-detail.component'),\n  data: { mode: 'edit' },\n  resolve: { item: ${modCamel}DetailResolver },\n}`,
+            // Base-language edit — ALWAYS emitted: the actions-column Edit navigates
+            // to ['/<bc>/<mod>/edit', id] (2 segments), so this route must exist
+            // even for i18n modules (replacing it with the :langId variant leaves
+            // that click dead). With no :langId the DetailResolver pins no
+            // Content-Language header and the server resolves APP_FALLBACK_LANG
+            // (design.md D11).
+            [`${modKebab}/edit/:id`]: `{\n  path: '${modKebab}/edit/:id',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-detail.component'),\n  data: { mode: 'edit' },\n  resolve: { item: ${modCamel}DetailResolver },\n}`,
+            // New TRANSLATION for an EXISTING row (id known, langId missing a
+            // translation): reuses the same detail component, 'new' mode and
+            // NewResolver as the plain /new route — increment 1 scope only wires
+            // column + cell + route; the form/resolver read the extra :id/:langId
+            // params in increment 2.
+            [`${modKebab}/new/:id/:langId`]: `{\n  path: '${modKebab}/new/:id/:langId',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-detail.component'),\n  data: { mode: 'new' },\n  resolve: { init: ${modCamel}NewResolver },\n}`,
+            [`${modKebab}/new`]: `{\n  path: '${modKebab}/new',\n  loadComponent: () => import('./${modKebab}/features/${modKebab}-detail.component'),\n  data: { mode: 'new' },\n  resolve: { init: ${modCamel}NewResolver },\n}`,
+        };
+        for (const path of expectedDetailPaths) {
+            const ownedMatch = findRouteElementsByPath(path).some((element) => isOwnedDetailRoute(element));
+            if (ownedMatch)
+                continue;
+            // Never insert a duplicate/conflicting path — a hand-written custom
+            // route already claiming it wins (see Finding 3: ownership check).
+            if (findRouteElementByPath(path))
+                continue;
+            addRouteElement(detailRouteText[path]);
+        }
+        // ── Resolver imports: reconciled AFTER routes, driven purely by whether
+        // each resolver's LOCAL name is still referenced somewhere in the file.
+        // Inserting a route above naturally makes its resolver "referenced"; a
+        // user who deliberately deleted an import and rewired the route to a
+        // custom resolver must not have it silently resurrected.
+        for (const resolverName of [
+            listResolverImport,
+            newResolverImport,
+            detailResolverImport,
+        ]) {
+            if (ImportDriver.isIdentifierUsedOutsideImports(sourceFile, resolverName)) {
+                ImportDriver.createImportItems(sourceFile, resolversModulePath, [
+                    resolverName,
+                ]);
+            }
+            else {
+                ImportDriver.removeUnusedNamedImport(sourceFile, resolversModulePath, resolverName);
+            }
+        }
+        await this.saveAndTrack(sourceFile, originalText, 'generateFrontRoutes');
     }
     /**
      * Ensure the bounded-context i18n JSON for `langCode` has keys for every non-timestamp,
@@ -405,26 +773,59 @@ export class CodeWriter {
      * in kebab-case; inner object is `Record<string, string>` (PascalCase keys).
      * Missing entries get a PascalCase default placeholder; the English helper-text template
      * is written for every language and translated manually afterwards.
-     * Writes JSON directly (not TS AST), so it does not flow through Prettier.
+     * Writes JSON directly (not TS AST); `writeJsonIfChanged` runs the candidate
+     * through the same formatter as the on-disk content before comparing, so it
+     * DOES flow through Prettier (its sibling
+     * `generateFrontNavigationTranslation` says the same).
      */
-    generateFrontTranslations(properties, langCode) {
+    async generateFrontTranslations(properties, langCode) {
         const bcKebab = toKebabCase(this.boundedContextName);
         const modKebab = toKebabCase(this.moduleName);
         const translationPath = join(process.cwd(), this.srcDirectory, '..', DASHBOARD_TRANSLATIONS, bcKebab, `${langCode}.json`);
-        const translationObject = JSON.parse(fs.readFileSync(translationPath, 'utf8'));
-        if (!translationObject[modKebab] || typeof translationObject[modKebab] !== 'object') {
+        if (this.checkIgnored(translationPath))
+            return;
+        const originalContent = fs.readFileSync(translationPath, 'utf8');
+        const translationObject = JSON.parse(originalContent);
+        if (!translationObject[modKebab] ||
+            typeof translationObject[modKebab] !== 'object') {
             translationObject[modKebab] = {};
         }
         const moduleTranslations = translationObject[modKebab];
-        const names = getWithoutTimestampsProperties(properties)
-            .filter((p) => p.name !== 'id')
-            .map((p) => p.name);
-        for (const name of names) {
-            const pascalName = toPascalCase(name);
+        const visibleProperties = getWithoutTimestampsProperties(properties).filter((p) => p.name !== 'id');
+        for (const property of visibleProperties) {
+            const pascalName = toPascalCase(property.name);
             if (moduleTranslations[pascalName] === undefined) {
                 moduleTranslations[pascalName] = pascalName;
             }
         }
+        // Per-option i18n keys for enum properties (scalar OR array-of-enum): the
+        // enum form widget (partials/fields/enum-field.eta) and the ENUM table
+        // cell (EnumCell) both resolve `t('<bc>.<mod>.<Pascal>.<OPTION>')` at
+        // runtime. Flat key with a literal dot — NOT a nested object.
+        // Add-if-missing: a translator may have already localized the option.
+        /*
+         * Uppercase invariant: `getPropertyEnumOptions` normalizes every option
+         * with `.trim().toUpperCase()`, so keys are always seeded as
+         * `<Pascal>.<UPPER_SNAKE_OPTION>`. `enum-field.eta` (the form widget)
+         * builds its runtime lookup key from the RAW yaml option instead — the
+         * two paths agree today only because every `enumOptions` entry in
+         * `cliter/**` is already UPPER_SNAKE_CASE (the catalyst-schema skill's
+         * documented examples, e.g. `patterns-workflow.md`'s
+         * `[PENDING, APPROVED, REJECTED, CANCELLED]`, and the backend union type
+         * derived from the same list, follow the same convention). If a schema
+         * ever declares a lowercase/mixed-case option, this seeding would drift
+         * from the value the form actually submits. Not a live bug — flag it if
+         * that assumption ever needs to be lifted.
+         */
+        for (const property of getEnumProperties(visibleProperties)) {
+            const pascalName = toPascalCase(property.name);
+            for (const option of getPropertyEnumOptions(property) ?? []) {
+                const optionKey = `${pascalName}.${option}`;
+                if (moduleTranslations[optionKey] === undefined) {
+                    moduleTranslations[optionKey] = humanizeEnumOption(option);
+                }
+            }
+        }
         const pluralPascal = toPascalCase(this.moduleNames);
         if (moduleTranslations.Title === undefined) {
             moduleTranslations.Title = pluralPascal;
@@ -453,9 +854,23 @@ export class CodeWriter {
             const defaultFn = NO_RESULTS_FOUND_DEFAULTS[langCode] ?? NO_RESULTS_FOUND_DEFAULTS.en;
             moduleTranslations[noResultsKey] = defaultFn(pluralLower);
         }
-        translationObject[modKebab] = sortObjectByKeys(moduleTranslations);
-        const sorted = sortObjectByKeys(translationObject);
-        fs.writeFileSync(translationPath, JSON.stringify(sorted, null, 2));
+        // Judgment Day round 1, finding 2: no longer re-sorted — see
+        // `generateFrontNavigationTranslation`'s note. `moduleTranslations` is
+        // already the same object read off `translationObject[modKebab]` (or a
+        // freshly-created `{}` on the very first module of this file); the
+        // assignment below is a no-op in the common case and only matters when
+        // the key didn't exist yet.
+        translationObject[modKebab] = moduleTranslations;
+        this.seedRequiredManyToManyErrors(translationObject, properties, langCode, singularLower);
+        await this.writeJsonIfChanged(translationPath, originalContent, JSON.stringify(translationObject, null, 2), 'generateFrontTranslations');
+    }
+    /** Every file path that opted out via the `ignored file` sentinel this run. */
+    getIgnoredFilePaths() {
+        return [...this.ignoredFilePaths];
+    }
+    /** Every file path that received an EFFECTIVE in-place mutation this run. */
+    getPatchedFilePaths() {
+        return [...this.patchedFilePaths];
     }
     /**
      * Idempotent bootstrap: ensure `nav-main.ts` imports `{bcCamel}Icons` from the aggregator
@@ -464,13 +879,16 @@ export class CodeWriter {
      * existing entries. Skips with a warning when `provideIcons` is invoked with anything other
      * than an inline `ObjectLiteralExpression` (developer-customized shape).
      */
-    registerBcAggregatorInNavMain(srcDirectory, boundedContextName) {
+    async registerBcAggregatorInNavMain(srcDirectory, boundedContextName) {
         const bcKebab = toKebabCase(boundedContextName);
         const bcCamel = toCamelCase(boundedContextName);
         const navMainPath = join(process.cwd(), srcDirectory, 'app/domains/admin/layout/sidebar/nav-main.ts');
         if (!fs.existsSync(navMainPath))
             return;
+        if (this.checkIgnored(navMainPath))
+            return;
         const sourceFile = this.project.addSourceFileAtPath(navMainPath);
+        const originalText = sourceFile.getFullText();
         const componentClass = sourceFile
             .getClasses()
             .find((c) => c.getDecorator('Component'));
@@ -489,7 +907,8 @@ export class CodeWriter {
             return;
         let provideIconsCall;
         for (const elem of providersArr.getElements()) {
-            if (Node.isCallExpression(elem) && elem.getExpression().getText() === 'provideIcons') {
+            if (Node.isCallExpression(elem) &&
+                elem.getExpression().getText() === 'provideIcons') {
                 provideIconsCall = elem;
                 break;
             }
@@ -498,18 +917,19 @@ export class CodeWriter {
             return;
         const argv = provideIconsCall.getArguments();
         if (argv.length !== 1 || !Node.isObjectLiteralExpression(argv[0])) {
-            console.warn(`[NAV-MAIN BOOTSTRAP SKIPPED] provideIcons argument is not an inline object literal in ${navMainPath}`);
+            this.logger.log(`[NAV-MAIN BOOTSTRAP SKIPPED] provideIcons argument is not an inline object literal in ${navMainPath}`);
             return;
         }
         const iconsObj = argv[0];
         const spreadName = `${bcCamel}Icons`;
-        for (const prop of iconsObj.getProperties()) {
-            if (Node.isSpreadAssignment(prop) &&
-                prop.getExpression().getText() === spreadName) {
-                return;
-            }
-        }
-        const importPath = `../../bounded-contexts/${bcKebab}/${bcKebab}-icons.providers`;
+        // Append-position upsert (the icons object is a flat spread set; a plain
+        // append preserves the pre-refactor placement). A no-op result means the
+        // spread was already present → return early WITHOUT touching the import,
+        // exactly as the previous inline loop did.
+        const mutated = ObjectDriver.upsertSpread(iconsObj, spreadName);
+        if (!mutated)
+            return;
+        const importPath = `../../apps/${bcKebab}/${bcKebab}-icons.providers`;
         const hasImport = sourceFile
             .getImportDeclarations()
             .some((decl) => decl.getModuleSpecifierValue() === importPath);
@@ -519,28 +939,71 @@ export class CodeWriter {
                 namedImports: [spreadName],
             });
         }
-        iconsObj.addSpreadAssignment({ expression: spreadName });
-        this.saveAndTrack(sourceFile);
+        await this.saveAndTrack(sourceFile, originalText, 'registerBcAggregatorInNavMain');
+    }
+    /**
+     * Auto-registers a bounded context into the backend Drizzle schema/relations
+     * aggregation file `src/@config/drizzle/aurora-drizzle-schema.ts`
+     * (auto-register-bc-drizzle-schema, design.md D1–D5) — the manual-extension
+     * step the scaffold's JSDoc used to require of every new BC.
+     *
+     * Adds the import `import { <bc>Schema, <bc>Relations } from '@app/<bc>/<bc>.relations';`
+     * (only if absent) and upserts `...<bc>Schema` into `auroraDrizzleSchema`
+     * and `...<bc>Relations` into `auroraDrizzleRelations`, both via
+     * `ObjectDriver.upsertSpread` with `position: 'spread-region'` — inserted
+     * after the last existing spread and BEFORE any hand-written named override
+     * property (D3: a trailing spread would shadow deep-merged overrides like
+     * `hubApp`/`iamAccount`, since object spread is last-wins). Idempotent by
+     * BC name (D2): a no-op when both spreads already exist. Shape-guarded
+     * (D3): if either target's initializer is not an inline object literal the
+     * helper can anchor, it warns and skips WITHOUT mutating anything. A
+     * missing aggregation file is a silent no-op (no throw), like
+     * `registerBcAggregatorInNavMain`.
+     */
+    async registerBcInDrizzleAggregation(boundedContextName) {
+        const bcKebab = toKebabCase(boundedContextName);
+        const bcCamel = toCamelCase(boundedContextName);
+        const aggregationPath = join(process.cwd(), this.srcDirectory, '@config', 'drizzle', 'aurora-drizzle-schema.ts');
+        if (!fs.existsSync(aggregationPath))
+            return;
+        const sourceFile = this.project.addSourceFileAtPath(aggregationPath);
+        const originalText = sourceFile.getFullText();
+        const schemaObj = this.getDrizzleAggregationObjectLiteral(sourceFile, 'auroraDrizzleSchema', aggregationPath);
+        const relationsObj = this.getDrizzleAggregationObjectLiteral(sourceFile, 'auroraDrizzleRelations', aggregationPath);
+        if (!schemaObj || !relationsObj)
+            return;
+        const schemaMutated = ObjectDriver.upsertSpread(schemaObj, `${bcCamel}Schema`, { position: 'spread-region' });
+        const relationsMutated = ObjectDriver.upsertSpread(relationsObj, `${bcCamel}Relations`, { position: 'spread-region' });
+        if (!schemaMutated && !relationsMutated)
+            return;
+        ImportDriver.createImportItems(sourceFile, `@app/${bcKebab}/${bcKebab}.relations`, [`${bcCamel}Schema`, `${bcCamel}Relations`]);
+        await this.saveAndTrack(sourceFile, originalText, 'registerBcInDrizzleAggregation', `the "${bcCamel}Schema"/"${bcCamel}Relations" spread`);
     }
     // ─── Formatting ─────────────────────────────────────────────────
-    registerFrontNavigation() {
+    async registerFrontNavigation() {
         const bcKebab = toKebabCase(this.boundedContextName);
         const bcCamel = toCamelCase(this.boundedContextName);
         const navDataPath = join(process.cwd(), this.srcDirectory, ADMIN_CONTAINER, 'navigation-data.ts');
         if (!fs.existsSync(navDataPath))
             return;
+        if (this.checkIgnored(navDataPath))
+            return;
         const sourceFile = this.project.addSourceFileAtPath(navDataPath);
-        const existingImport = sourceFile.getImportDeclaration((d) => d.getModuleSpecifierValue().includes(`bounded-contexts/${bcKebab}`));
+        const originalText = sourceFile.getFullText();
+        const existingImport = sourceFile.getImportDeclaration((d) => d.getModuleSpecifierValue().includes(`apps/${bcKebab}`));
         if (existingImport)
             return;
-        ImportDriver.createImportItems(sourceFile, `./bounded-contexts/${bcKebab}`, [`${bcCamel}Navigation`]);
+        ImportDriver.createImportItems(sourceFile, `./apps/${bcKebab}`, [
+            `${bcCamel}Navigation`,
+        ]);
         // Insert `...{bcCamel}Navigation` before the closing `]` of `navMain`
         const navMainText = sourceFile.getText();
         if (navMainText.includes(`...${bcCamel}Navigation`))
             return;
         const navMainMatch = navMainText.match(/navMain:\s*\[([^]*?)\]\s*satisfies/);
         if (navMainMatch) {
-            const insertPos = navMainText.indexOf(navMainMatch[0]) + navMainMatch[0].indexOf('] satisfies');
+            const insertPos = navMainText.indexOf(navMainMatch[0]) +
+                navMainMatch[0].indexOf('] satisfies');
             // Ensure the last array element before the spread has a trailing comma so
             // the inserted spread does not produce invalid syntax.
             const textBeforeInsert = navMainText.slice(0, insertPos).trimEnd();
@@ -548,37 +1011,373 @@ export class CodeWriter {
             const prefix = needsComma ? ',\n' : '';
             sourceFile.replaceText([insertPos, insertPos], `${prefix}    ...${bcCamel}Navigation,\n  `);
         }
-        this.saveAndTrack(sourceFile);
+        await this.saveAndTrack(sourceFile, originalText, 'registerFrontNavigation');
     }
-    getModelArrayArgument(decoratorArgs) {
-        const importsArray = getInitializer(decoratorArgs.getProperty('imports'));
-        const sequelizeElement = importsArray
-            .getElements()
-            .find((el) => el.getText().startsWith('SequelizeModule.forFeature'));
-        if (!sequelizeElement) {
-            throw new Error('SequelizeModule.forFeature is not defined in the module.');
+    /**
+     * Auto-registers the generated module's aggregate into the masked-property
+     * field-schema registry `src/@config/drizzle/aurora-field-schemas.ts`
+     * (harden-generator-emission-contract, Defect D) — the sibling mechanism of
+     * `registerBcInDrizzleAggregation` for `masked-property-query-guard`'s own
+     * registry. Same location, same import discipline (module barrel, per
+     * HR-BARRELS-002/003), same placement rationale — but a DIFFERENT shape:
+     * this registry is keyed PER AGGREGATE (`registerBcInDrizzleAggregation`'s
+     * sibling is keyed per bounded context), one NAMED property per module
+     * (`<AggregateName>: <Bc><Mod>FieldSchema`), never a spread.
+     *
+     * Adds the import `import { <Bc><Mod>FieldSchema } from '@app/<bc>/<mod>';`
+     * (only if absent) and appends the property (only if absent) — idempotent
+     * by aggregate name. A missing registry file is a silent no-op (no throw),
+     * like `registerBcInDrizzleAggregation`. Called from the same place the
+     * Drizzle sibling is called: `declareBackSchemaInBcRelations`, so a pivot's
+     * own aggregate registers too (pivots ARE in the existing 60-entry
+     * registry, e.g. `IamRoleAccount`).
+     *
+     * ADDITIVE ONLY (design D10): does not prune, reorder or repair entries it
+     * did not write, and does NOT fix the scaffold's inherited registry
+     * (declined item I — a `scripts/packager/` concern). Widening this method
+     * to "fix" either would silently break a hand-curated registry.
+     */
+    async registerModuleInFieldSchemaRegistry(schema) {
+        const bcKebab = toKebabCase(schema.boundedContextName);
+        const modKebab = toKebabCase(schema.moduleName);
+        const { aggregateName } = schema;
+        const symbolName = `${aggregateName}FieldSchema`;
+        const registryPath = join(process.cwd(), this.srcDirectory, '@config', 'drizzle', 'aurora-field-schemas.ts');
+        if (!fs.existsSync(registryPath))
+            return;
+        const sourceFile = this.project.addSourceFileAtPath(registryPath);
+        const originalText = sourceFile.getFullText();
+        const registryObj = this.getDrizzleAggregationObjectLiteral(sourceFile, 'auroraFieldSchemas', registryPath, 'FIELD SCHEMA REGISTRY');
+        if (!registryObj)
+            return;
+        if (registryObj.getProperty(aggregateName))
+            return;
+        ImportDriver.createImportItems(sourceFile, `@app/${bcKebab}/${modKebab}`, [
+            symbolName,
+        ]);
+        registryObj.addPropertyAssignment({
+            initializer: symbolName,
+            name: aggregateName,
+        });
+        await this.saveAndTrack(sourceFile, originalText, 'registerModuleInFieldSchemaRegistry', `the "${aggregateName}: ${symbolName}" registry entry`);
+    }
+    /**
+     * Resolution gate and skip reporting (design.md D3 "Resolution test",
+     * tasks.md group 4) for cross-BC relation candidates — the entries
+     * `code-writer.ts::declareBackSchemaInBcRelations` filters OUT of the
+     * per-BC relations file (`isCrossBc`, group 2/3). The caller decides WHICH
+     * candidates are relevant to the module currently being generated (tasks.md
+     * group 5's bidirectional trigger, `selectRelevantCrossBcCandidates` — which
+     * is the filter; `discoverDeclaredCrossBcRelations` is the unfiltered
+     * project-wide scan it wraps);
+     * this method only decides, per candidate, whether BOTH endpoints resolve —
+     * owner gate first, then target — and upserts or reports accordingly.
+     *
+     * Resolution is decided against BOTH endpoints' GENERATED backend modules
+     * (`isModuleGenerated`) — a YAML under `cliter/` is NOT evidence (12 of the
+     * 30 declared cross-BC references measured in T-4.1 have one with no
+     * generated module). Gating only the target was a measured defect: a
+     * reverse candidate whose OWNER is ungenerated produced an entry naming an
+     * undefined `<owner>Relations` identifier and a table key absent from
+     * `auroraDrizzleSchema`, leaving an assembly file that neither compiles nor
+     * boots. An unresolved candidate is never silently dropped: it
+     * is REPORTED (`[CROSS-BC RELATION SKIPPED]`, naming both sides of the
+     * pair) — silence in a new place would reproduce the exact defect this
+     * change removes. A run with unresolvable candidates still completes and
+     * still writes every resolvable one (tasks.md 4.3) — a partially-generated
+     * project is a normal intermediate state, not a failure.
+     *
+     * Mirrors `registerBcInDrizzleAggregation`'s silent no-op when the
+     * aggregation file itself does not exist yet — that is a DIFFERENT,
+     * infrastructure-missing condition (the scaffold itself), not a "target
+     * not generated" resolution outcome, so it is not reported the same way.
+     */
+    async resolveAndUpsertCrossBcRelations(candidates) {
+        const skipped = [];
+        let written = 0;
+        if (candidates.length === 0)
+            return { skipped, written };
+        const aggregationPath = join(process.cwd(), this.srcDirectory, '@config', 'drizzle', 'aurora-drizzle-schema.ts');
+        if (!fs.existsSync(aggregationPath))
+            return { skipped, written };
+        const sourceFile = this.project.addSourceFileAtPath(aggregationPath);
+        const originalText = sourceFile.getFullText();
+        const srcDirAbsolute = join(process.cwd(), this.srcDirectory);
+        for (const candidate of candidates) {
+            // BOTH sides need a generated module, and for the SAME reason. The entry names the owner's
+            // per-BC relations map (`...<owner>Relations.<ownerKey>`) and the owner's table key on
+            // `auroraDrizzleSchema`; neither exists until the owner's bounded context is generated. A
+            // reverse candidate reaches this loop from any target's generation, so an owner that was
+            // never generated is a normal state, not an anomaly: `iam/account` alone has three such
+            // candidates today (`support/comment`, `support/issue`, `whatsapp/message`).
+            if (!isModuleGenerated(srcDirAbsolute, candidate.ownerBoundedContextKebab, candidate.ownerModuleKebab)) {
+                skipped.push(candidate);
+                this.logCrossBcSkip(candidate, 'owner module not generated yet');
+                continue;
+            }
+            if (!isModuleGenerated(srcDirAbsolute, candidate.targetBoundedContextKebab, candidate.targetModuleKebab)) {
+                skipped.push(candidate);
+                this.logCrossBcSkip(candidate, 'target module not generated yet');
+                continue;
+            }
+            const result = upsertCrossBcRelationEntry(sourceFile, {
+                ownerBoundedContextCamelCase: candidate.ownerBoundedContextCamelCase,
+                ownerKey: candidate.ownerKey,
+                relation: candidate.relation,
+            });
+            if (result.warning) {
+                skipped.push(candidate);
+                this.logCrossBcSkip(candidate, result.warning);
+                continue;
+            }
+            if (result.mutated)
+                written += 1;
+        }
+        if (written > 0) {
+            await this.saveAndTrack(sourceFile, originalText, 'resolveAndUpsertCrossBcRelations', `${written} cross-BC relation entry(ies)`);
+        }
+        return { skipped, written };
+    }
+    /**
+     * REQUIRED-APPEND gate. For a file this generator MUST append to for the
+     * module to FUNCTION, the `ignored file` sentinel is a HARD STOP, never a
+     * silent skip. Seven targets, each named by the patcher that owns it:
+     *
+     * | Target                                    | Patcher                                            | Missing entry means |
+     * | ----------------------------------------- | -------------------------------------------------- | ------------------- |
+     * | `@app/<bc>/<bc>.seed.ts`                  | `addSeedPermissions`                               | every `@Auth`-guarded endpoint of the module is unreachable |
+     * | `@app/<bc>/<bc>.relations.ts`             | `declareBackSchemaInBcRelations`                   | the module's table is outside the BC relations graph |
+     * | `@config/drizzle/aurora-drizzle-schema.ts`| `registerBcInDrizzleAggregation`                   | the BC never joins the ORM schema |
+     * | `@config/drizzle/aurora-field-schemas.ts` | `registerModuleInFieldSchemaRegistry`              | `masked-property-query-guard` fails OPEN for the aggregate |
+     * | `@api/<bc>/<bc>.module.ts`                | `declareBackApplicationItemsInModule`              | the module's resolvers/controllers are never registered — boots fine, every endpoint absent |
+     * | `app.module.ts`                           | `declareBackBoundedContextModuleInApplicationModule` | `<Bc>Module` is never imported by AppModule |
+     * | `@app/<bc>/index.ts`                      | `generateBackAppBoundedContextReferences`          | handlers/services/repository never enter the BC arrays — NestJS DI fails at boot |
+     *
+     * Measured for the first row: `iam.seed.ts`, `o-auth.seed.ts` and
+     * `hub.seed.ts` all carried the marker; once `addSeedPermissions` started
+     * honouring it (section 4), every module generated in those three bounded
+     * contexts silently received ZERO seeded permissions, with nothing but one
+     * skipped log line to notice by. The three `@api`/`app.module`/`@app` rows
+     * were promoted in Judgment Day round 2 (finding 2): three of the seven are
+     * already in `AVOID_OVERWRITING_FILES`, i.e. the generator's own taxonomy
+     * already says the additive patch is their ONLY write path.
+     *
+     * The sentinel keeps its honest whole-file meaning ONLY for FULL-REWRITE
+     * patchers (routes, navigation, icons, translations, …), where "this file
+     * is fully hand-maintained now" is a coherent, safe opt-out — this method
+     * is deliberately NOT used there; `checkIgnored` below is unchanged for
+     * those call sites.
+     *
+     * WHERE this runs matters as much as what it checks: it is called from
+     * `saveAndTrack`, AFTER the formatted candidate is known to differ from
+     * disk (Judgment Day round 2, finding 1). "The file is an append target" is
+     * not the trigger — "the generator actually has something to append" is. A
+     * module whose entry is already present and byte-correct regenerates
+     * against an adopted file silently, exactly as before the gate existed.
+     *
+     * Never returns `true`/`false` like `checkIgnored` — either the file is
+     * clear (silently returns) or the run ABORTS with an actionable error
+     * naming the file, what it needed to append, and the remedy. A file that
+     * does not exist yet is not "ignored" (nothing has opted out of a file
+     * that was never created) and is left to the caller's own creation logic.
+     */
+    assertNotIgnoredForRequiredAppend(filePath, whatItNeedsToAppend) {
+        if (!fs.existsSync(filePath))
+            return;
+        if (!isFileContentIgnored(fs.readFileSync(filePath, 'utf8')))
+            return;
+        throw new Error(`${filePath} is marked "// ignored file" but ${this.boundedContextName}/${this.moduleName} needs to append ${whatItNeedsToAppend} to it. ` +
+            'This file is a REQUIRED-APPEND target: the module cannot function without this entry, so the generator refuses to silently skip it. ' +
+            // Judgment Day round 2, finding 7: the previous wording promised
+            // ".origin and the module lock" as the safety net for hand edits.
+            // That is FALSE for every one of the seven targets. Three of them
+            // (the BC seed, `@api/<bc>/<bc>.module.ts`, `@app/<bc>/index.ts`)
+            // are in `AVOID_OVERWRITING_FILES`, so `file-manager.ts` `continue`s
+            // before `writeFile` under `--force` and `writeFile` only logs
+            // "[INFO] exist" without it — `handleExistingFile` is never reached,
+            // so no `.origin` can ever be produced for them (which also makes
+            // `catalyst origin ignore` a silent no-op there: it needs an existing
+            // `.origin`). The other four are not rendered by any template at
+            // all. Corrected again in the SPEC CONFORMITY gate: the LOCK half of
+            // that replacement was also false. `file-writer.ts` pushes the lock
+            // entry outside the if/else chain, so a run without `--force` records
+            // one for these paths — 27 of this repo's 53 back locks carry the seed
+            // entry. A lock entry here buys detection, not protection: with no
+            // template rendering over the file there is nothing for the integrity
+            // check to gate. What actually protects hand edits is narrower and
+            // stronger: nothing ever rewrites these files wholesale.
+            'Nothing else in the generator writes these files: no template renders over them, so they never produce a .origin — the additive patch of the generator\'s own managed entry is the ONLY write, and hand edits anywhere else in the file are untouched by construction. ' +
+            'Remedy: delete the "// ignored file" marker line, or add the entry by hand yourself and re-run.');
+    }
+    /**
+     * The `ignored file` sentinel gate (design D1). MUST be called at the point
+     * each patcher OPENS its target file — before `addSourceFileAtPath` /
+     * `createSourceFile` / `fs.readFileSync` — so an ignored file is skipped
+     * before any ts-morph manipulation. Returns `false` (never ignored) for a
+     * file that does not exist yet: there is nothing to have opted out.
+     */
+    checkIgnored(filePath) {
+        if (!fs.existsSync(filePath))
+            return false;
+        if (!isFileContentIgnored(fs.readFileSync(filePath, 'utf8')))
+            return false;
+        this.ignoredFilePaths.add(filePath);
+        // Unconditional (not gated by --verbose), mirroring file-writer.ts's own
+        // `[IGNORED FILE]` log — an opt-out taking effect is significant enough
+        // to always report, the same way file-writer already does.
+        this.logger.log('%s %s', chalk.cyanBright.bold('[IGNORED FILE]'), filePath);
+        return true;
+    }
+    /**
+     * Resolves the top-level exported `auroraDrizzleSchema`/`auroraDrizzleRelations`
+     * object literal by structural anchor (variable declaration name + inline
+     * object-literal initializer) — never by comment/marker. Warns and returns
+     * `undefined` when the initializer has been reshaped into something the
+     * helper cannot safely anchor (a developer customization), so the caller
+     * can skip the mutation entirely rather than clobber it.
+     */
+    getDrizzleAggregationObjectLiteral(sourceFile, variableName, filePath, warningLabel = 'DRIZZLE AGGREGATION') {
+        const declaration = sourceFile.getVariableDeclaration(variableName);
+        const objectLiteral = declaration?.getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+        if (!objectLiteral) {
+            this.logger.log(`[${warningLabel} SKIPPED] '${variableName}' is not an anchorable inline object literal in ${filePath}`);
         }
-        return sequelizeElement.getArguments()[0];
+        return objectLiteral;
     }
     getModuleDecoratorArguments(sourceFile, className, decoratorName) {
         const cls = sourceFile.getClass(className);
         const decorator = cls?.getDecorator(decoratorName);
         return decorator.getArguments()[0];
     }
-    saveAndTrack(sourceFile) {
+    /** `[CROSS-BC RELATION SKIPPED]` — names both sides of the pair, never silent (tasks.md group 4). */
+    logCrossBcSkip(candidate, reason) {
+        this.logger.log('%s %s/%s.%s -> %s/%s (%s)', chalk.yellow.bold('[CROSS-BC RELATION SKIPPED]'), candidate.ownerBoundedContextKebab, candidate.ownerModuleKebab, candidate.relation.label, candidate.targetBoundedContextKebab, candidate.targetModuleKebab, reason);
+    }
+    /**
+     * Records an EFFECTIVE in-place mutation (design D3): the count feeds the
+     * run's closing summary (always visible); the per-file detail is gated by
+     * `--verbose`, matching `file-writer.ts`'s `[FILE OVERWRITE]` convention.
+     */
+    recordPatch(filePath, patcherName) {
+        this.patchedFilePaths.add(filePath);
+        if (this.verbose) {
+            this.logger.log('%s %s %s', chalk.magenta.bold('[FILE PATCHED]'), patcherName, filePath);
+        }
+    }
+    /**
+     * Generalizes the before/after comparison `generateFrontRoutes` pioneered
+     * (design D3): `originalText` MUST be captured right after the file is
+     * opened, before any manipulation. A run that changes nothing makes ZERO
+     * disk writes and records ZERO mutation.
+     *
+     * This is ALSO the single seam where the REQUIRED-APPEND sentinel gate runs
+     * (Judgment Day round 2, finding 1): `requiredAppend` is asserted only once
+     * the formatted candidate is known to DIFFER from disk, i.e. only once the
+     * generator genuinely has something to append. Asserting earlier (at the
+     * point the file is opened) aborted the run for a module whose entry was
+     * already present and byte-correct, with a message that claimed an append
+     * was needed when none was.
+     */
+    async saveAndTrack(sourceFile, originalText, patcherName, requiredAppend) {
+        // Judgment Day round 1, finding 2: comparing ts-morph's raw re-print
+        // against Prettier-formatted disk content made this a false positive on
+        // EVERY run (ts-morph's own printer never matches Prettier's style byte
+        // for byte — import wrapping, trailing commas, quote choice). Formatting
+        // the CANDIDATE through the same Prettier path before comparing is the
+        // only way "did this actually change" agrees with what is on disk.
+        const filePath = sourceFile.getFilePath();
+        const formattedCandidate = await this.formatCode(sourceFile.getFullText(), filePath);
+        if (formattedCandidate === originalText)
+            return;
+        if (requiredAppend) {
+            this.assertNotIgnoredForRequiredAppend(filePath, requiredAppend);
+        }
+        sourceFile.replaceWithText(formattedCandidate);
         sourceFile.saveSync();
-        this.savedFiles.add(sourceFile.getFilePath());
+        this.recordPatch(filePath, patcherName);
+    }
+    /**
+     * Required many-to-many error keys (enforce-required-many-to-many-relationships,
+     * design.md D4): top-level `error` object, sibling of the module keys — NOT nested
+     * under `translationObject[modKebab]`. The key MUST match, literally, the
+     * `rules.translationKey` derived by `buildFieldSchemaEntries` for the SAME property
+     * (property-mappers.ts) — `<bc-kebab>.error.<moduleCamel><PascalCase(prop.name)>Required` —
+     * so the runtime ArrayTypeHandler's translation and this seeded default resolve to the
+     * same i18n entry. Same if-undefined idempotent pattern as `No<Plural>Found`: a
+     * manually-edited message survives regeneration.
+     *
+     * `<moduleCamel>` (NOT `aggregateName`) — revised post-Judgment-Day round 1 (F3,
+     * user-approved): matches the hand-written production precedent and avoids
+     * duplicating the bounded context, already present via `<bc-kebab>`.
+     */
+    seedRequiredManyToManyErrors(translationObject, properties, langCode, entitySingular) {
+        const requiredManyToManyProperties = properties.filter((p) => p.type === 'relationship' && p.relationship?.type === 'many-to-many' && p.nullable === false);
+        if (requiredManyToManyProperties.length === 0)
+            return;
+        const errorTranslations = (typeof translationObject.error === 'object' && translationObject.error !== null
+            ? translationObject.error
+            : {});
+        for (const property of requiredManyToManyProperties) {
+            const errorKey = `${toCamelCase(this.moduleName)}${toPascalCase(property.name)}Required`;
+            if (errorTranslations[errorKey] !== undefined)
+                continue;
+            const defaultFn = REQUIRED_MANY_TO_MANY_ERROR_DEFAULTS[langCode] ?? REQUIRED_MANY_TO_MANY_ERROR_DEFAULTS.en;
+            errorTranslations[errorKey] = defaultFn(entitySingular, property.relationship?.singularName ?? '');
+        }
+        // Judgment Day round 1, finding 2: no longer re-sorted — same reasoning
+        // as `generateFrontNavigationTranslation`'s note.
+        translationObject.error = errorTranslations;
+    }
+    /**
+     * The JSON-write sibling of `saveAndTrack`, for the two patchers
+     * (`generateFrontNavigationTranslation`, `generateFrontTranslations`) that
+     * rewrite a JSON file directly via `fs`, never through ts-morph. Same
+     * no-op-if-unchanged and mutation-recording contract.
+     */
+    async writeJsonIfChanged(filePath, originalContent, newContent, patcherName) {
+        // Same fix as `saveAndTrack`: `JSON.stringify(obj, null, 2)` never
+        // carries a trailing newline and does not match whatever style Prettier
+        // (or a hand editor) left on disk — format the CANDIDATE the same way
+        // before comparing, so an unchanged semantic object round-trips to
+        // byte-identical content instead of a spurious mutation every run.
+        const formattedCandidate = await this.formatCode(newContent, filePath);
+        if (formattedCandidate === originalContent)
+            return;
+        fs.writeFileSync(filePath, formattedCandidate);
+        this.recordPatch(filePath, patcherName);
     }
 }
 const NO_RESULTS_FOUND_DEFAULTS = {
     en: (plural) => `No ${plural} found.`,
     es: (plural) => `No se encontraron ${plural}.`,
 };
+const REQUIRED_MANY_TO_MANY_ERROR_DEFAULTS = {
+    en: (entitySingular, relationSingular) => `The ${entitySingular} must have at least one ${relationSingular} assigned.`,
+    es: (entitySingular, relationSingular) => `El/La ${entitySingular} debe tener al menos un ${relationSingular} asignado.`,
+};
+/**
+ * Read a route object literal's `path` VALUE, not its raw source text — so a
+ * consumer whose Prettier config uses double quotes (or a template literal
+ * with no substitutions) is still recognized as the same route by
+ * `generateFrontRoutes`'s reconciliation. Returns `undefined` for a missing
+ * `path` property or a non-literal initializer (e.g. a computed expression).
+ */
+function getRoutePathValue(element) {
+    const pathProp = element.getProperty('path');
+    const initializer = pathProp?.getInitializer();
+    if (!initializer)
+        return undefined;
+    if (Node.isStringLiteral(initializer) ||
+        Node.isNoSubstitutionTemplateLiteral(initializer)) {
+        return initializer.getLiteralValue();
+    }
+    return undefined;
+}
 function buildIconsAggregatorContent(bcKebab, bcCamel, icons) {
     const header = [
         '/**',
         ' * @aurora-catalyst-generated',
-        ` * @source frontend/src/app/domains/admin/bounded-contexts/${bcKebab}/${bcKebab}.navigation.ts`,
+        ` * @source frontend/src/app/domains/admin/apps/${bcKebab}/${bcKebab}.navigation.ts`,
         ' */',
     ].join('\n');
     if (icons.length === 0) {
@@ -588,10 +1387,29 @@ function buildIconsAggregatorContent(bcKebab, bcCamel, icons) {
     const objectBody = icons.map((icon) => `  ${icon},`).join('\n');
     return `${header}\n${importLine}\n\nexport const ${bcCamel}Icons = {\n${objectBody}\n};\n`;
 }
-function sortObjectByKeys(obj) {
-    const sorted = {};
-    for (const key of Object.keys(obj).sort()) {
-        sorted[key] = obj[key];
+/**
+ * Ensure `obj` has a string property `name` equal to `value`.
+ * Add-if-missing semantics: NEVER overwrites an existing value, even if different.
+ * Returns `true` when the property was added (the AST was mutated), `false` otherwise.
+ *
+ * @param obj - the object literal to mutate.
+ * @param name - property name.
+ * @param value - string value to set (without surrounding quotes).
+ * @param insertBefore - when provided, the new property is inserted BEFORE this node
+ *   (used to place `permission` before `items` for readability).
+ */
+function ensureStringProperty(obj, name, value, insertBefore) {
+    if (obj.getProperty(name))
+        return false;
+    if (insertBefore) {
+        // Find the index of the insertBefore property inside obj
+        const props = obj.getProperties();
+        const idx = props.indexOf(insertBefore);
+        if (idx !== -1) {
+            obj.insertPropertyAssignment(idx, { initializer: `'${value}'`, name });
+            return true;
+        }
     }
-    return sorted;
+    obj.addPropertyAssignment({ initializer: `'${value}'`, name });
+    return true;
 }