@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

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

@@ -6,7 +6,7 @@ import { NewLineKind } from 'typescript';
 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 { getEnumProperties, getForeignRelationshipProperties, getFormDetailFieldsProperties, 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';
@@ -175,12 +175,12 @@ export class CodeWriter {
             `${bcPascal}Services`,
             `${bcPascal}Repositories`,
         ];
-        ImportDriver.createImportItems(sourceFile, `${APP_CONTAINER}/${bcKebab}`, appImports);
+        ImportDriver.createImportItems(sourceFile, `${APP_CONTAINER}/${bcKebab}/index.js`, appImports);
         const apiImports = [
             `${bcPascal}${modPascal}ApiControllers`,
             `${bcPascal}${modPascal}ApiResolvers`,
         ];
-        ImportDriver.createImportItems(sourceFile, `./${modKebab}`, apiImports);
+        ImportDriver.createImportItems(sourceFile, `./${modKebab}/index.js`, apiImports);
         const providerItems = [
             `...${bcPascal}Handlers`,
             `...${bcPascal}Services`,
@@ -201,7 +201,7 @@ export class CodeWriter {
         const modules = ImportDriver.getImportedDeclarations(sourceFile);
         if (modules.includes(`${bcPascal}Module`))
             return;
-        ImportDriver.createImportItems(sourceFile, `${API_CONTAINER}/${bcKebab}/${bcKebab}.module`, [`${bcPascal}Module`]);
+        ImportDriver.createImportItems(sourceFile, `${API_CONTAINER}/${bcKebab}/${bcKebab}.module.js`, [`${bcPascal}Module`]);
         const importsArray = getInitializer(decoratorArgs.getProperty('imports'));
         ArrayDriver.addArrayItems(sourceFile, [`${bcPascal}Module`], importsArray);
         await this.saveAndTrack(sourceFile, originalText, 'declareBackBoundedContextModuleInApplicationModule', `the "${bcPascal}Module" import into AppModule`);
@@ -399,7 +399,7 @@ export class CodeWriter {
         if (isI18nTable) {
             imports.push(`${bcPascal}Drizzle${modPascal}I18nRepository`);
         }
-        ImportDriver.createImportItems(sourceFile, `./${modKebab}`, imports);
+        ImportDriver.createImportItems(sourceFile, `./${modKebab}/index.js`, imports);
         ArrayDriver.addArrayItem(sourceFile, `...${bcPascal}${modPascal}Handlers`, `${bcPascal}Handlers`);
         ArrayDriver.addArrayItem(sourceFile, `...${bcPascal}${modPascal}Services`, `${bcPascal}Services`);
         ArrayDriver.addArrayItem(sourceFile, `${bcPascal}Drizzle${modPascal}Repository`, `${bcPascal}Repositories`);
@@ -628,10 +628,71 @@ export class CodeWriter {
         const routesArray = getInitializer(routesDecl);
         if (!routesArray)
             return;
-        const resolversModulePath = `./${modKebab}/data-access/${modKebab}.resolvers`;
+        // HR-BARRELS-004: import from the module's data-access SUB-BARREL, never
+        // the deep resolvers file, and NEVER the module barrel (`./${modKebab}`,
+        // which re-exports `./features` and would drag every feature component
+        // into the routes chunk). This is NOT free: the sub-barrel also
+        // re-exports detail-config/list-config/graphql alongside the resolvers,
+        // plus whatever a hand-written `/* #region customizations */` block adds
+        // to it (measured: `production-order-header.derive.ts` pulls in
+        // `ProductionPlanningProductionOrderHeaderStatusEnum` from
+        // `aurora.types` at runtime). Still the right trade-off — those files
+        // are far smaller than a module's `./features` components — just not
+        // literally zero-cost.
+        const resolversModulePath = `./${modKebab}/data-access`;
+        const legacyResolversModulePath = `./${modKebab}/data-access/${modKebab}.resolvers`;
         const listResolverImport = `${modCamel}ListResolver`;
         const newResolverImport = `${modCamel}NewResolver`;
         const detailResolverImport = `${modCamel}DetailResolver`;
+        // Migrate a resolver import still pointing at the deep file (pre-fix
+        // codegen output, or a previously-generated file predating this fix) to
+        // the sub-barrel in place. `ImportDriver` matches declarations by exact
+        // module-specifier text, so without this rewrite an already-generated
+        // file would keep its deep import forever — the create/remove loop below
+        // only ever looks at `resolversModulePath`.
+        const legacyImportDecl = sourceFile.getImportDeclaration(legacyResolversModulePath);
+        if (legacyImportDecl) {
+            const subBarrelImportDecl = sourceFile.getImportDeclaration(resolversModulePath);
+            // `addNamedImports` can only fuse NAMED specifiers into another
+            // declaration — a namespace (`import * as x`) or default import has no
+            // named-import counterpart to merge into, so removing the legacy
+            // declaration below would drop that binding entirely.
+            const legacyHasNamespaceOrDefault = legacyImportDecl.getNamespaceImport() !== undefined ||
+                legacyImportDecl.getDefaultImport() !== undefined;
+            if (subBarrelImportDecl && !legacyHasNamespaceOrDefault) {
+                // Both forms present (unexpected, but handle it): merge the legacy
+                // named specifiers into the sub-barrel import, then drop the legacy
+                // declaration. Dedupe by LOCAL BINDING (`alias ?? name`), never by
+                // exported name: `{ userNewResolver as wizardInit }` and a plain
+                // `{ userNewResolver }` already in the sub-barrel import are TWO
+                // distinct bindings, not a duplicate — deduping by exported name
+                // dropped the aliased specifier and then `.remove()` deleted its
+                // only binding, leaving every reference to `wizardInit` unresolved
+                // (TS2304).
+                const existingLocalNames = new Set(subBarrelImportDecl
+                    .getNamedImports()
+                    .map((ni) => ni.getAliasNode()?.getText() ?? ni.getName()));
+                const toAdd = legacyImportDecl
+                    .getNamedImports()
+                    .filter((ni) => !existingLocalNames.has(ni.getAliasNode()?.getText() ?? ni.getName()))
+                    .map((ni) => ({
+                    alias: ni.getAliasNode()?.getText(),
+                    name: ni.getName(),
+                }));
+                if (toAdd.length > 0)
+                    subBarrelImportDecl.addNamedImports(toAdd);
+                legacyImportDecl.remove();
+            }
+            else {
+                // No sub-barrel import yet, OR the legacy declaration carries a
+                // namespace/default import `addNamedImports` cannot fuse — rewrite
+                // its specifier in place instead of deleting it. When a sub-barrel
+                // import already exists too, this leaves two declarations sharing
+                // the sub-barrel specifier (legal JS/TS — they merge at binding
+                // time), each keeping the import kind it started with.
+                legacyImportDecl.setModuleSpecifier(resolversModulePath);
+            }
+        }
         // ── 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.
@@ -854,6 +915,30 @@ export class CodeWriter {
             const defaultFn = NO_RESULTS_FOUND_DEFAULTS[langCode] ?? NO_RESULTS_FOUND_DEFAULTS.en;
             moduleTranslations[noResultsKey] = defaultFn(pluralLower);
         }
+        // Group section titles (`widget.group`, form-body.eta) share ONE flat key
+        // space with field labels, enum options and the module keys above:
+        // `t('<bc>.<mod>.<PascalCase(...)>')`. Seeding them LAST is what makes a
+        // collision harmless — add-if-missing then always finds the other key
+        // already in place, so a group can never take a name away from the key
+        // that owns it.
+        //
+        // The warning is therefore a diagnostic, not a guard. A group named after a
+        // field renders its `<h4>` with that FIELD's translation, which reads as
+        // correct and hides the mistake — so it has to be said out loud.
+        const groupNames = new Set(getFormDetailFieldsProperties(properties)
+            .map((property) => property.widget?.group)
+            .filter((group) => group !== undefined));
+        for (const group of groupNames) {
+            const pascalGroup = toPascalCase(group);
+            const collidesWithFieldLabel = visibleProperties.some((property) => toPascalCase(property.name) === pascalGroup);
+            if (collidesWithFieldLabel) {
+                console.warn(`[widget.group] module '${this.moduleName}': group '${group}' resolves to i18n key '${pascalGroup}', which is already the label of the field '${group}'. The section title will render that field's translation — rename the group or the field.`);
+                continue;
+            }
+            if (moduleTranslations[pascalGroup] === undefined) {
+                moduleTranslations[pascalGroup] = pascalGroup;
+            }
+        }
         // 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
@@ -947,7 +1032,7 @@ export class CodeWriter {
      * (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';`
+     * Adds the import `import { <bc>Schema, <bc>Relations } from '@app/<bc>/<bc>.relations.js';`
      * (only if absent) and upserts `...<bc>Schema` into `auroraDrizzleSchema`
      * and `...<bc>Relations` into `auroraDrizzleRelations`, both via
      * `ObjectDriver.upsertSpread` with `position: 'spread-region'` — inserted
@@ -976,7 +1061,7 @@ export class CodeWriter {
         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`]);
+        ImportDriver.createImportItems(sourceFile, `@app/${bcKebab}/${bcKebab}.relations.js`, [`${bcCamel}Schema`, `${bcCamel}Relations`]);
         await this.saveAndTrack(sourceFile, originalText, 'registerBcInDrizzleAggregation', `the "${bcCamel}Schema"/"${bcCamel}Relations" spread`);
     }
     // ─── Formatting ─────────────────────────────────────────────────
@@ -1018,13 +1103,17 @@ export class CodeWriter {
      * 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
+     * registry. Same location, same import discipline (the module's public
+     * `domain` sub-barrel, per HR-BARRELS-004 case 2 — this file is loaded
+     * from `app.module.ts` at boot and names EVERY aggregate in the
+     * application, so a root-barrel specifier here would reach every module's
+     * services, handlers and repository before any NestJS module is
+     * constructed), 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>';`
+     * Adds the import `import { <Bc><Mod>FieldSchema } from '@app/<bc>/<mod>/domain/index.js';`
      * (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
@@ -1052,7 +1141,7 @@ export class CodeWriter {
             return;
         if (registryObj.getProperty(aggregateName))
             return;
-        ImportDriver.createImportItems(sourceFile, `@app/${bcKebab}/${modKebab}`, [
+        ImportDriver.createImportItems(sourceFile, `@app/${bcKebab}/${modKebab}/domain/index.js`, [
             symbolName,
         ]);
         registryObj.addPropertyAssignment({

package/dist/generator/handlers/back.handler.d.ts

@@ -42,6 +42,33 @@ export declare function validateMaskedPropertyGetRawExclusion(schema: import('..
  * above: a pure function over the schema, called FIRST in `generateBackModule`.
  */
 export declare function validateMaskedPropertyNotEmbeddedI18n(schema: import('../domain/model.js').ModuleDefinitionSchema): void;
+/**
+ * add-tenant-scope-decorators, design D8: a `hasTenant: true` module whose
+ * schema declares no tenant property (`tenantId` or `tenantIds`, matched by
+ * {@link getTenantProperty}) would otherwise emit `@TenantConstraint()` /
+ * `@TenantPolicy()` with no column to scope by — a filter over a column the
+ * aggregate does not have, which is a runtime failure at best and a silently
+ * unscoped read at worst. Fail-fast, schema-first, same shape as
+ * `validateMaskedPropertyGetRawExclusion` above: a pure function over the
+ * schema, called FIRST in `generateBackModule`, so no file is written for an
+ * offending aggregate.
+ */
+export declare function validateTenantPropertyExists(schema: import('../domain/model.js').ModuleDefinitionSchema): void;
+export declare function validateTenantAwareNoConstraintOperationsExclusion(schema: import('../domain/model.js').ModuleDefinitionSchema): void;
+/**
+ * Judgment-day round 1 (WARNING, both judges agreed): `hasTenant: true` unconditionally emits
+ * `@CurrentAccount() account: IamAccount` on every write/read vertical (see the create resolver
+ * template) with no `@Auth(...)` guard to populate `request.user` when `hasOAuth: false` — there
+ * is no global `APP_GUARD` in `backend/src` to fall back on. Every request to every endpoint of
+ * such a module then hits `resolveTenantScopedAccount`'s "no principal" branch and throws
+ * `TenantScopeMisconfiguredError` (500), unconditionally: the module is generated cleanly but is
+ * unusable end to end.
+ *
+ * Mirrors `validateTenantPropertyExists` exactly (same underlying defect class: `hasTenant: true`
+ * declared without a precondition the mechanism actually needs): a pure function over the schema,
+ * called FIRST in `generateBackModule`, so no file is written for an offending aggregate.
+ */
+export declare function validateTenantRequiresOAuth(schema: import('../domain/model.js').ModuleDefinitionSchema): void;
 export declare function generateBackModule(ctx: GenerationContext, options?: {
     hasTestingFiles?: boolean;
 }): Promise<GenerationResult>;

package/dist/generator/handlers/back.handler.js

@@ -14,7 +14,7 @@ import { API_CONTAINER, APP_CONTAINER, BACK_PACKAGES, } from '../domain/config.j
 import { getCustomFieldValueExcludedFiles } from '../domain/custom-field-value.js';
 import { getI18nTableExcludedFiles } from '../domain/i18n-table.js';
 import { buildPivotSchema } from '../domain/model.js';
-import { getEnumProperties, getManyToManyRelationshipProperties, getValueObjectsProperties, hasI18nProperties, isOperationExcluded, } from '../domain/property-filters.js';
+import { getEnumProperties, getManyToManyRelationshipProperties, getTenantProperty, getValueObjectsProperties, hasI18nProperties, isOperationExcluded, } from '../domain/property-filters.js';
 import { isMaskedReadProperty } from '../domain/property-predicates.js';
 import { getReadonlyPayloadTypesExcludedFiles } from '../domain/readonly-payload-types.js';
 import { saveSchema } from '../domain/schema-loader.js';
@@ -80,6 +80,84 @@ export function validateMaskedPropertyNotEmbeddedI18n(schema) {
         return;
     throw new Error(`[masked-property-i18n ERROR] ${schema.boundedContextName}/${schema.moduleName} declares '${offender.name}' as BOTH isI18n: true and type '${offender.type}'. Under the embedded i18n strategy the field-schema entry is re-typed to 'jsonb' for the per-locale map — the masked type declaration is silently discarded, so @Format's masked-property check no longer matches this field and it is emitted completely UNMASKED, in every locale. Remedy: drop isI18n from the property (a masked secret/password is not a user-facing translatable string), or set the module's i18nStrategy to 'table', where masking is preserved. Then regenerate.`);
 }
+/**
+ * add-tenant-scope-decorators, design D8: a `hasTenant: true` module whose
+ * schema declares no tenant property (`tenantId` or `tenantIds`, matched by
+ * {@link getTenantProperty}) would otherwise emit `@TenantConstraint()` /
+ * `@TenantPolicy()` with no column to scope by — a filter over a column the
+ * aggregate does not have, which is a runtime failure at best and a silently
+ * unscoped read at worst. Fail-fast, schema-first, same shape as
+ * `validateMaskedPropertyGetRawExclusion` above: a pure function over the
+ * schema, called FIRST in `generateBackModule`, so no file is written for an
+ * offending aggregate.
+ */
+export function validateTenantPropertyExists(schema) {
+    if (!schema.hasTenant)
+        return;
+    if (getTenantProperty(schema.aggregateProperties ?? []))
+        return;
+    throw new Error(`[tenant-property-missing ERROR] ${schema.boundedContextName}/${schema.moduleName} declares hasTenant: true but no tenant property was found (looked for 'tenantId' then 'tenantIds'). Add one of those properties to the aggregate, or set hasTenant: false, and regenerate.`);
+}
+/**
+ * add-tenant-scope-decorators, item A (extended by the upsert follow-up):
+ * some operations have NO `constraint` argument in their generated signature,
+ * so `@TenantConstraint()` has nothing to act on. `get-raw`'s signature is
+ * `(account?, sql, timezone)` — phase 6 stripped its tenant plumbing entirely,
+ * leaving a completely unscoped raw-SQL read. `upsert`'s signature carries
+ * `@TenantPolicy()` over the incoming payload but no `constraint` slot for
+ * the row the payload's key resolves to — a payload with a correct tenant
+ * value can still take over an existing row that belongs to another tenant,
+ * because nothing scopes the lookup itself. Both are silently unscoped in a
+ * `hasTenant: true` module that forgets to exclude them.
+ *
+ * {@link TENANT_OPERATIONS_WITHOUT_CONSTRAINT} is the complete list of such
+ * operations — the underlying reason ("no `constraint` argument to attach
+ * `@TenantConstraint()` to") is what puts an operation on it, not the two
+ * names themselves. A future operation with the same shape is one more entry
+ * here, not a new validator.
+ *
+ * Mirrors `validateMaskedPropertyGetRawExclusion` exactly (same underlying
+ * defect class: an operation bypasses a per-request enforcement mechanism
+ * that every other operation carries): a pure function over the schema,
+ * called FIRST in `generateBackModule`, so no file is written for an
+ * offending aggregate. Deliberately does NOT re-validate that the tenant
+ * property exists — {@link validateTenantPropertyExists} already aborts that
+ * case, and duplicating the check here would just produce two errors for one
+ * cause.
+ */
+const TENANT_OPERATIONS_WITHOUT_CONSTRAINT = ['getRaw', 'upsert'];
+export function validateTenantAwareNoConstraintOperationsExclusion(schema) {
+    if (!schema.hasTenant)
+        return;
+    const tenantProperty = getTenantProperty(schema.aggregateProperties ?? []);
+    if (!tenantProperty)
+        return;
+    for (const operation of TENANT_OPERATIONS_WITHOUT_CONSTRAINT) {
+        if (isOperationExcluded(schema, operation))
+            continue;
+        throw new Error(`[tenant-no-constraint-operation ERROR] ${schema.boundedContextName}/${schema.moduleName} declares hasTenant: true (tenant column '${tenantProperty.name}') and does not exclude '${operation}'. '${operation}'s generated signature carries no 'constraint' argument, so @TenantConstraint() has nothing to scope it with — the endpoint would operate completely unscoped by tenant. Add '${operation}' to the aggregate's excludedOperations in *.aurora.yaml, or drop hasTenant, and regenerate.`);
+    }
+}
+/**
+ * Judgment-day round 1 (WARNING, both judges agreed): `hasTenant: true` unconditionally emits
+ * `@CurrentAccount() account: IamAccount` on every write/read vertical (see the create resolver
+ * template) with no `@Auth(...)` guard to populate `request.user` when `hasOAuth: false` — there
+ * is no global `APP_GUARD` in `backend/src` to fall back on. Every request to every endpoint of
+ * such a module then hits `resolveTenantScopedAccount`'s "no principal" branch and throws
+ * `TenantScopeMisconfiguredError` (500), unconditionally: the module is generated cleanly but is
+ * unusable end to end.
+ *
+ * Mirrors `validateTenantPropertyExists` exactly (same underlying defect class: `hasTenant: true`
+ * declared without a precondition the mechanism actually needs): a pure function over the schema,
+ * called FIRST in `generateBackModule`, so no file is written for an offending aggregate.
+ */
+export function validateTenantRequiresOAuth(schema) {
+    if (!schema.hasTenant)
+        return;
+    if (schema.hasOAuth)
+        return;
+    throw new Error(`[tenant-requires-oauth ERROR] ${schema.boundedContextName}/${schema.moduleName} declares hasTenant: true but hasOAuth: false. Every tenant-scoped endpoint emits @CurrentAccount() with no @Auth(...) guard to populate it when hasOAuth is false, and this project wires no global APP_GUARD — every request would throw TenantScopeMisconfiguredError (500). Set hasOAuth: true, or drop hasTenant, and regenerate.`);
+}
 export async function generateBackModule(ctx, options = {}) {
     const { schema } = ctx;
     // 0. Masked-property + getRaw fail-fast (section 7, Defect C): hoisted
@@ -90,6 +168,20 @@ export async function generateBackModule(ctx, options = {}) {
     // isI18n + masked type silently disables masking under the embedded i18n
     // strategy. Same hoisting rationale as 0 above.
     validateMaskedPropertyNotEmbeddedI18n(schema);
+    // 0a-2. add-tenant-scope-decorators, design D8: same hoisting rationale —
+    // a hasTenant: true module with no tenant property aborts before anything
+    // is written.
+    validateTenantPropertyExists(schema);
+    // 0a-3. add-tenant-scope-decorators, item A (extended for upsert): same
+    // hoisting rationale — a hasTenant: true module that does not exclude one
+    // of TENANT_OPERATIONS_WITHOUT_CONSTRAINT (getRaw, upsert) aborts before
+    // anything is written (neither operation's signature has a constraint
+    // argument for @TenantConstraint() to scope).
+    validateTenantAwareNoConstraintOperationsExclusion(schema);
+    // 0a-4. Judgment-day round 1 (WARNING, both judges): a hasTenant: true
+    // module with hasOAuth: false emits @CurrentAccount() with no @Auth(...)
+    // guard to populate it — every request would 500. Same hoisting rationale.
+    validateTenantRequiresOAuth(schema);
     // 0b. Judgment Day round 1 (SECURITY MEDIUM): the guards above only
     // checked `ctx.schema`. `generateAppPivotFiles`/`generateApiPivotFiles`
     // emit a FULL module from `buildPivotSchema(pivot)` — its own
@@ -102,6 +194,9 @@ export async function generateBackModule(ctx, options = {}) {
             const pivotSchema = buildPivotSchema(property.relationship.pivot);
             validateMaskedPropertyGetRawExclusion(pivotSchema);
             validateMaskedPropertyNotEmbeddedI18n(pivotSchema);
+            validateTenantPropertyExists(pivotSchema);
+            validateTenantAwareNoConstraintOperationsExclusion(pivotSchema);
+            validateTenantRequiresOAuth(pivotSchema);
         }
     }
     const result = {
@@ -293,7 +388,7 @@ export async function generateAppFiles(ctx, result) {
         ...getI18nTableExcludedFiles(schema),
         // non-editable-field-codegen (design.md D5, tasks.md 3.7): same gate —
         // the internal service payload-types file is only meaningful for an
-        // aggregate that declares at least one `readonly: true` property.
+        // aggregate that declares at least one `readOnly: true` property.
         ...getReadonlyPayloadTypesExcludedFiles(schema),
     ];
     await generateFromTemplate(logger, 'backend/@app', outputBase, '', options, result);
@@ -331,9 +426,16 @@ async function generateAppPivotFiles(ctx, result) {
         const pivotSchema = buildPivotSchema(pivot);
         const pivotOpts = buildOptions(pivotSchema, ctx);
         // hasCustomFields: pivot (many-to-many join) tables never opt in
-        // (buildPivotSchema never sets the flag — design.md D2 excludes pivots),
-        // so this is always an exclusion for pivot generation. Same reasoning
-        // for readonly (buildPivotSchema never declares the flag either).
+        // (buildPivotSchema never sets the MODULE-level flag — design.md D2
+        // excludes pivots), so this is always an exclusion for pivot generation.
+        // readonly is DIFFERENT: it is a PER-PROPERTY flag, and a pivot's own
+        // properties CAN declare it (add-create-only-property-semantics taught
+        // the loader to validate/normalize readOnly/createOnly inside a pivot's
+        // aggregateProperties too — schema-loader.ts's
+        // validateAndNormalizePropertyFlags recursion). So
+        // getReadonlyPayloadTypesExcludedFiles(pivotSchema) is NOT always an
+        // exclusion here — it reads pivotSchema.aggregateProperties itself and
+        // only excludes the file when none of them declare readOnly.
         pivotOpts.excludedFiles = [
             ...(pivotOpts.excludedFiles ?? []),
             ...getCustomFieldValueExcludedFiles(pivotSchema),

package/dist/generator/packages/installers/auditing.js

@@ -4,15 +4,15 @@ import { addScheduleModule, addToSharedModule, changeSharedModuleAdapter, declar
 export default async function install(ctx) {
     await ctx.install(['@nestjs/axios', '@nestjs/schedule']);
     await ctx.install(['@types/cron'], { dev: true });
-    declareBackPackageModule(ctx, 'AuditingModule', '@app/modules/auditing/auditing.module');
+    declareBackPackageModule(ctx, 'AuditingModule', '@app/modules/auditing/auditing.module.js');
     addScheduleModule(ctx);
     const sharedModule = ctx.sourceFile('app', 'shared.module.ts');
     ImportDriver.createImportItems(sharedModule, '@nestjs/axios', ['HttpModule']);
     addToSharedModule(sharedModule, 'imports', 'HttpModule');
     addToSharedModule(sharedModule, 'exports', 'HttpModule');
-    ImportDriver.createImportItems(sharedModule, '@app/modules/auditing/interceptors/auditing-axios-interceptor.service', ['AuditingAxiosInterceptorService']);
+    ImportDriver.createImportItems(sharedModule, '@app/modules/auditing/interceptors/auditing-axios-interceptor.service.js', ['AuditingAxiosInterceptorService']);
     DecoratorDriver.addModuleDecoratorProperty(sharedModule, 'SharedModule', 'Module', 'providers', 'AuditingAxiosInterceptorService');
-    changeSharedModuleAdapter(sharedModule, 'providers', 'AuditingRunner', 'AuditingAxiosRunner', '@app/modules/auditing/runners/auditing-axios.runner', ['AuditingAxiosRunner']);
+    changeSharedModuleAdapter(sharedModule, 'providers', 'AuditingRunner', 'AuditingAxiosRunner', '@app/modules/auditing/runners/auditing-axios.runner.js', ['AuditingAxiosRunner']);
     sharedModule.saveSync();
     await runGraphqlTypes(ctx);
 }

package/dist/generator/packages/installers/authorization-code.js

@@ -12,7 +12,7 @@ export default async function install(ctx) {
         'passport-jwt',
     ]);
     await ctx.install(['@types/passport-jwt'], { dev: true });
-    declareBackPackageModule(ctx, 'AuthorizationCodeModule', '@api/authorization-code/authorization-code.module');
+    declareBackPackageModule(ctx, 'AuthorizationCodeModule', '@api/authorization-code/authorization-code.module.js');
     const sharedModule = ctx.sourceFile('@aurora', 'shared.module.ts');
     ImportDriver.createImportItems(sharedModule, '@nestjs/axios', ['HttpModule']);
     addToSharedModule(sharedModule, 'imports', 'HttpModule');
@@ -20,10 +20,7 @@ export default async function install(ctx) {
     sharedModule.saveSync();
     // Replace `UseGuards` arg in auth.decorator with the new guards.
     const authDecorator = ctx.sourceFile('@aurora', 'decorators', 'auth.decorator.ts');
-    ImportDriver.createImportItems(authDecorator, '@app/authorization-code', [
-        'AuthenticationJwtGuard',
-        'AuthorizationPermissionsGuard',
-    ]);
+    ImportDriver.createImportItems(authDecorator, '@app/authorization-code/index.js', ['AuthenticationJwtGuard', 'AuthorizationPermissionsGuard']);
     const callExpr = CallExpressionDriver.findCallExpression(authDecorator, 'UseGuards');
     if (callExpr) {
         CallExpressionDriver.removeAllArguments(callExpr);

package/dist/generator/packages/installers/common.js

@@ -2,10 +2,10 @@ import { DecoratorDriver } from '../../engine/code-writer/drivers/decorator.driv
 import { ImportDriver } from '../../engine/code-writer/drivers/import.driver.js';
 import { changeSharedModuleAdapter, declareBackPackageModule, runGraphqlTypes, } from '../package-helpers.js';
 export default async function install(ctx) {
-    declareBackPackageModule(ctx, 'CommonModule', '@app/modules/common/common.module');
+    declareBackPackageModule(ctx, 'CommonModule', '@app/modules/common/common.module.js');
     const sharedModule = ctx.sourceFile('app', 'shared.module.ts');
-    changeSharedModuleAdapter(sharedModule, 'providers', 'CoreGetLangsService', 'CommonGetLangsService', '@app/modules/common/lang/application/get/common-get-langs.service', ['CommonGetLangsService']);
-    ImportDriver.createImportItems(sharedModule, '@app/modules/common/attachment/application/common-attachments.service', ['CommonAttachmentsService']);
+    changeSharedModuleAdapter(sharedModule, 'providers', 'CoreGetLangsService', 'CommonGetLangsService', '@app/modules/common/lang/application/get/common-get-langs.service.js', ['CommonGetLangsService']);
+    ImportDriver.createImportItems(sharedModule, '@app/modules/common/attachment/application/common-attachments.service.js', ['CommonAttachmentsService']);
     DecoratorDriver.addModuleDecoratorProperty(sharedModule, 'SharedModule', 'Module', 'providers', 'CommonAttachmentsService');
     DecoratorDriver.addModuleDecoratorProperty(sharedModule, 'SharedModule', 'Module', 'exports', 'CommonAttachmentsService');
     sharedModule.saveSync();

package/dist/generator/packages/installers/mcp.js

@@ -1,5 +1,5 @@
 import { declareBackPackageModule } from '../package-helpers.js';
 export default async function install(ctx) {
     await ctx.install(['@modelcontextprotocol/sdk', 'zod']);
-    declareBackPackageModule(ctx, 'McpModule', '@app/modules/mcp/mcp.module');
+    declareBackPackageModule(ctx, 'McpModule', '@app/modules/mcp/mcp.module.js');
 }

package/dist/generator/packages/installers/message.js

@@ -1,5 +1,5 @@
 import { declareBackPackageModule, runGraphqlTypes } from '../package-helpers.js';
 export default async function install(ctx) {
-    declareBackPackageModule(ctx, 'MessageModule', '@app/modules/message/message.module');
+    declareBackPackageModule(ctx, 'MessageModule', '@app/modules/message/message.module.js');
     await runGraphqlTypes(ctx);
 }

package/dist/generator/packages/installers/ms-email.js

@@ -5,7 +5,7 @@ export default async function install(ctx) {
     await ctx.install(['@microsoft/microsoft-graph-client']);
     // Swap MailerTransportService adapter to MsGraphMailerTransportService
     const mailerModule = ctx.sourceFile('app', 'mailer-transport.module.ts');
-    ImportDriver.createImportItems(mailerModule, '@app/modules/ms-email/application/ms-graph-mailer-transport.service', ['MsGraphMailerTransportService']);
+    ImportDriver.createImportItems(mailerModule, '@app/modules/ms-email/application/ms-graph-mailer-transport.service.js', ['MsGraphMailerTransportService']);
     DecoratorDriver.changeModuleDecoratorPropertyAdapter(mailerModule, 'MailerTransportModule', 'Module', 'providers', 'MailerTransportService', 'MsGraphMailerTransportService');
     mailerModule.saveSync();
     await runGraphqlTypes(ctx);

package/dist/generator/packages/installers/ms-entra-id.js

@@ -8,11 +8,11 @@ export default async function install(ctx) {
         'passport-azure-ad',
         'passport-http-bearer',
     ]);
-    declareBackPackageModule(ctx, 'MsEntraIdModule', '@app/modules/ms-entra-id/ms-entra-id.module');
+    declareBackPackageModule(ctx, 'MsEntraIdModule', '@app/modules/ms-entra-id/ms-entra-id.module.js');
     // Replace UseGuards arg with the two new guards
     const authDecorator = ctx.sourceFile('app', 'shared', 'decorators', 'auth.decorator.ts');
-    ImportDriver.createImportItems(authDecorator, '@app/modules/ms-entra-id/shared/guards/azure-ad-bearer-auth.guard', ['AzureAdBearerAuthGuard']);
-    ImportDriver.createImportItems(authDecorator, '@app/modules/ms-entra-id/shared/guards/authorization-permissions.guard', ['AuthorizationPermissionsGuard']);
+    ImportDriver.createImportItems(authDecorator, '@app/modules/ms-entra-id/shared/guards/azure-ad-bearer-auth.guard.js', ['AzureAdBearerAuthGuard']);
+    ImportDriver.createImportItems(authDecorator, '@app/modules/ms-entra-id/shared/guards/authorization-permissions.guard.js', ['AuthorizationPermissionsGuard']);
     const callExpr = CallExpressionDriver.findCallExpression(authDecorator, 'UseGuards');
     if (callExpr) {
         CallExpressionDriver.removeAllArguments(callExpr);

package/dist/generator/packages/installers/queue-manager.js

@@ -1,6 +1,6 @@
 import { declareBackPackageModule, runGraphqlTypes, } from '../package-helpers.js';
 export default async function install(ctx) {
     await ctx.install(['@nestjs/bullmq', 'bullmq', 'ioredis']);
-    declareBackPackageModule(ctx, 'QueueManagerModule', '@api/queue-manager/queue-manager.module');
+    declareBackPackageModule(ctx, 'QueueManagerModule', '@api/queue-manager/queue-manager.module.js');
     await runGraphqlTypes(ctx);
 }

package/dist/generator/packages/installers/storage-account-azure.js

@@ -2,8 +2,8 @@ import { changeSharedModuleAdapter, runGraphqlTypes } from '../package-helpers.j
 export default async function install(ctx) {
     await ctx.install(['@azure/storage-blob']);
     const sharedModule = ctx.sourceFile('app', 'shared.module.ts');
-    changeSharedModuleAdapter(sharedModule, 'providers', 'FileManagerService', 'AzureBlobFileManagerService', '@app/modules/storage-account-azure/file-manager/application/azure-blob-file-manager.service', ['AzureBlobFileManagerService']);
-    changeSharedModuleAdapter(sharedModule, 'providers', 'SasService', 'AzureBlobSasService', '@app/modules/storage-account-azure/sas/application/azure-blob-sas.service', ['AzureBlobSasService']);
+    changeSharedModuleAdapter(sharedModule, 'providers', 'FileManagerService', 'AzureBlobFileManagerService', '@app/modules/storage-account-azure/file-manager/application/azure-blob-file-manager.service.js', ['AzureBlobFileManagerService']);
+    changeSharedModuleAdapter(sharedModule, 'providers', 'SasService', 'AzureBlobSasService', '@app/modules/storage-account-azure/sas/application/azure-blob-sas.service.js', ['AzureBlobSasService']);
     sharedModule.saveSync();
     await runGraphqlTypes(ctx);
 }

package/dist/generator/packages/installers/storage-account.js

@@ -4,12 +4,12 @@ import { addProviderToModule, declareBackPackageModule, runGraphqlTypes, } from
 export default async function install(ctx) {
     await ctx.install(['sharp', 'form-data']);
     await ctx.install(['@types/multer'], { dev: true });
-    declareBackPackageModule(ctx, 'StorageAccountModule', '@app/modules/storage-account/storage-account.module');
+    declareBackPackageModule(ctx, 'StorageAccountModule', '@app/modules/storage-account/storage-account.module.js');
     const sharedModule = ctx.sourceFile('app', 'shared.module.ts');
-    addProviderToModule(sharedModule, 'SharedModule', 'Module', 'providers', 'FileManagerService', 'StorageAccountFileManagerService', '@app/modules/storage-account/file-manager/application/storage-account-file-manager.service', ['FileManagerService', 'StorageAccountFileManagerService']);
+    addProviderToModule(sharedModule, 'SharedModule', 'Module', 'providers', 'FileManagerService', 'StorageAccountFileManagerService', '@app/modules/storage-account/file-manager/application/storage-account-file-manager.service.js', ['FileManagerService', 'StorageAccountFileManagerService']);
     DecoratorDriver.addModuleDecoratorProperty(sharedModule, 'SharedModule', 'Module', 'exports', 'FileManagerService');
-    ImportDriver.createImportItems(sharedModule, '@app/modules/storage-account/sas/application/storage-account-sas.service', ['SasService', 'StorageAccountSasService']);
-    addProviderToModule(sharedModule, 'SharedModule', 'Module', 'providers', 'SasService', 'StorageAccountSasService', '@app/modules/storage-account/sas/application/storage-account-sas.service', ['SasService', 'StorageAccountSasService']);
+    ImportDriver.createImportItems(sharedModule, '@app/modules/storage-account/sas/application/storage-account-sas.service.js', ['SasService', 'StorageAccountSasService']);
+    addProviderToModule(sharedModule, 'SharedModule', 'Module', 'providers', 'SasService', 'StorageAccountSasService', '@app/modules/storage-account/sas/application/storage-account-sas.service.js', ['SasService', 'StorageAccountSasService']);
     DecoratorDriver.addModuleDecoratorProperty(sharedModule, 'SharedModule', 'Module', 'exports', 'SasService');
     sharedModule.saveSync();
     await runGraphqlTypes(ctx);

package/dist/generator/packages/installers/support.js

@@ -2,7 +2,7 @@ import { ImportDriver } from '../../engine/code-writer/drivers/import.driver.js'
 import { addToSharedModule, declareBackPackageModule, runGraphqlTypes, } from '../package-helpers.js';
 export default async function install(ctx) {
     await ctx.install(['@nestjs/axios', 'axios']);
-    declareBackPackageModule(ctx, 'SupportModule', '@app/modules/support/support.module');
+    declareBackPackageModule(ctx, 'SupportModule', '@app/modules/support/support.module.js');
     const sharedModule = ctx.sourceFile('app', 'shared.module.ts');
     ImportDriver.createImportItems(sharedModule, '@nestjs/axios', ['HttpModule']);
     addToSharedModule(sharedModule, 'imports', 'HttpModule');

package/dist/generator/packages/installers/tools.js

@@ -1,5 +1,5 @@
 import { declareBackPackageModule, runGraphqlTypes } from '../package-helpers.js';
 export default async function install(ctx) {
-    declareBackPackageModule(ctx, 'ToolsModule', '@app/modules/tools/tools.module');
+    declareBackPackageModule(ctx, 'ToolsModule', '@app/modules/tools/tools.module.js');
     await runGraphqlTypes(ctx);
 }

package/dist/generator/packages/installers/whatsapp.js

@@ -1,5 +1,5 @@
 import { declareBackPackageModule, runGraphqlTypes } from '../package-helpers.js';
 export default async function install(ctx) {
-    declareBackPackageModule(ctx, 'WhatsappModule', '@app/modules/whatsapp/whatsapp.module');
+    declareBackPackageModule(ctx, 'WhatsappModule', '@app/modules/whatsapp/whatsapp.module.js');
     await runGraphqlTypes(ctx);
 }

package/dist/generator/packages/package-helpers.js

@@ -82,19 +82,19 @@ export function addProviderToModule(sourceFile, moduleName, decoratorName, prope
  */
 export function wireBridgesModule(sourceFile) {
     // ── imports ─────────────────────────────────────────────────────────────────
-    ImportDriver.createImportItems(sourceFile, '@api/iam/iam.module', [
+    ImportDriver.createImportItems(sourceFile, '@api/iam/iam.module.js', [
         'IamModule',
     ]);
-    ImportDriver.createImportItems(sourceFile, '@api/o-auth/o-auth.module', [
+    ImportDriver.createImportItems(sourceFile, '@api/o-auth/o-auth.module.js', [
         'OAuthModule',
     ]);
-    ImportDriver.createImportItems(sourceFile, '@aurora/modules/authentication/domain/ports', ['ACCOUNT_LOADER', 'CREDENTIAL_VERIFIER']);
-    ImportDriver.createImportItems(sourceFile, '@bridges/iam', [
+    ImportDriver.createImportItems(sourceFile, '@aurora/modules/authentication/domain/ports/index.js', ['ACCOUNT_LOADER', 'CREDENTIAL_VERIFIER']);
+    ImportDriver.createImportItems(sourceFile, '@bridges/iam/index.js', [
         'IAM_BOUNDED_CONTEXT_SEEDER',
         'IAM_CLIENT_READER',
         'IAM_PERMISSION_SEEDER',
     ]);
-    ImportDriver.createImportItems(sourceFile, '@bridges/providers', [
+    ImportDriver.createImportItems(sourceFile, '@bridges/providers/index.js', [
         'accountLoaderBridge',
         'credentialVerifierBridge',
         'iamBoundedContextSeederBridge',
@@ -130,11 +130,11 @@ export function authBridgesProvidersBarrel(workspaceDir) {
     const providersDir = join(workspaceDir, 'src', '@bridges', 'providers');
     fs.mkdirSync(providersDir, { recursive: true });
     const content = [
-        "export * from './account-loader.bridge';",
-        "export * from './credential-verifier.bridge';",
-        "export * from './iam-bounded-context-seeder.bridge';",
-        "export * from './iam-client-reader.bridge';",
-        "export * from './iam-permission-seeder.bridge';",
+        "export * from './account-loader.bridge.js';",
+        "export * from './credential-verifier.bridge.js';",
+        "export * from './iam-bounded-context-seeder.bridge.js';",
+        "export * from './iam-client-reader.bridge.js';",
+        "export * from './iam-permission-seeder.bridge.js';",
         '',
     ].join('\n');
     fs.writeFileSync(join(providersDir, 'index.ts'), content, 'utf8');

package/dist/generator/utils/code-gen.d.ts

@@ -9,7 +9,11 @@ export interface ImportManagerOptions {
     sortImportedClasses?: boolean;
     sortImports?: boolean;
 }
-/** Group imports by path, deduplicate items, sort, return formatted import/export string. */
+/**
+ * Group imports by path, deduplicate items, sort, return formatted import/export string.
+ * The path is never touched (no suffix added, removed or inferred) — the call site MUST
+ * already declare the full ESM specifier (golden rule 1: the template declares, this never guesses).
+ */
 export declare function importManager({ commandType, imports, sortImportedClasses, sortImports, }: ImportManagerOptions): string;
 export interface ConstructorInjectorManagerOptions {
     injections: ConstructorInjectionStatement[];