@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/generator/domain/property-validators.js

@@ -23,10 +23,14 @@ export function getValidators(property) {
     if (property.type === 'id' && !property.widget)
         return [];
     // Defense in depth (non-editable-field-codegen, design.md D2): the form
-    // filters already drop a `readonly: true` property before it reaches a
+    // filters already drop a `readOnly: true` property before it reaches a
     // control, so this never fires in the generated form today — but any other
     // caller of this helper must not emit a validator no control can satisfy.
-    if (property.readonly)
+    // NOTE: createOnly is deliberately NOT checked here — it gets full
+    // validators in BOTH modes (add-create-only-property-semantics); only the
+    // generated form's edit-mode `disabled()` restricts it, never a dropped
+    // validator.
+    if (property.readOnly)
         return [];
     // Many-to-many relationship — FormControl holds `string[]` of FK ids.
     // Non-nullable means "at least one selection"; Angular's built-in
@@ -69,8 +73,9 @@ export function getSignalFormValidators(property, pathVar = 'path') {
     if (property.type === 'id' && !property.widget)
         return [];
     // Defense in depth (non-editable-field-codegen, design.md D2) — see the
-    // matching guard in `getValidators` above.
-    if (property.readonly)
+    // matching guard in `getValidators` above. createOnly is deliberately NOT
+    // checked here — see the note there.
+    if (property.readOnly)
         return [];
     if (property.relationship?.type === 'many-to-many') {
         return property.nullable ? [] : [`required(${pathVar})`, `minLength(${pathVar}, 1)`];

package/dist/generator/domain/readonly-payload-types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Internal service payload types for aggregates that declare at least one
- * `readonly: true` property (non-editable-field-codegen, design.md D5/D6/D7).
+ * `readOnly: true` property (non-editable-field-codegen, design.md D5/D6/D7).
  *
  * Two layers protect a readonly field (design.md D13): the public write
  * contract (DTOs, GraphQL inputs) excludes it, and the generated
@@ -19,7 +19,7 @@
 import type { ModuleDefinitionSchema, Property } from './model.js';
 export type ReadonlyPayloadSchema = Pick<ModuleDefinitionSchema, 'aggregateProperties' | 'boundedContextName' | 'moduleName' | 'moduleNames'>;
 /**
- * The `readonly: true` properties of an aggregate, in declaration order —
+ * The `readOnly: true` properties of an aggregate, in declaration order —
  * EXCLUDING `relationship`-typed properties (the canonical many-to-many
  * shape, `PROPERTY_TYPE.RELATIONSHIP`). `DTO_TYPES` has no `relationship`
  * key, so `getDtoType` throws for one; more fundamentally, there is no
@@ -30,7 +30,7 @@ export type ReadonlyPayloadSchema = Pick<ModuleDefinitionSchema, 'aggregatePrope
  */
 export declare function getReadonlyProperties(properties?: Property[]): Property[];
 /**
- * Whether the aggregate declares at least one `readonly: true` property
+ * Whether the aggregate declares at least one `readOnly: true` property
  * eligible for the internal payload intersection — mirrors
  * `getReadonlyProperties`'s relationship exclusion, so a readonly
  * many-to-many alone does not trigger emission of the payload-types file.

package/dist/generator/domain/readonly-payload-types.js

@@ -1,6 +1,6 @@
 /**
  * Internal service payload types for aggregates that declare at least one
- * `readonly: true` property (non-editable-field-codegen, design.md D5/D6/D7).
+ * `readOnly: true` property (non-editable-field-codegen, design.md D5/D6/D7).
  *
  * Two layers protect a readonly field (design.md D13): the public write
  * contract (DTOs, GraphQL inputs) excludes it, and the generated
@@ -18,9 +18,9 @@
  */
 import { toKebabCase, toPascalCase } from '../utils/string-utils.js';
 import { getDtoType, getPropertyName } from './property-mappers.js';
-import { isReadonly, isRelationship } from './property-predicates.js';
+import { isReadOnly, isRelationship } from './property-predicates.js';
 /**
- * The `readonly: true` properties of an aggregate, in declaration order —
+ * The `readOnly: true` properties of an aggregate, in declaration order —
  * EXCLUDING `relationship`-typed properties (the canonical many-to-many
  * shape, `PROPERTY_TYPE.RELATIONSHIP`). `DTO_TYPES` has no `relationship`
  * key, so `getDtoType` throws for one; more fundamentally, there is no
@@ -30,10 +30,10 @@ import { isReadonly, isRelationship } from './property-predicates.js';
  * here rather than mapped.
  */
 export function getReadonlyProperties(properties = []) {
-    return properties.filter((property) => isReadonly(property) && !isRelationship(property));
+    return properties.filter((property) => isReadOnly(property) && !isRelationship(property));
 }
 /**
- * Whether the aggregate declares at least one `readonly: true` property
+ * Whether the aggregate declares at least one `readOnly: true` property
  * eligible for the internal payload intersection — mirrors
  * `getReadonlyProperties`'s relationship exclusion, so a readonly
  * many-to-many alone does not trigger emission of the payload-types file.

package/dist/generator/domain/relations-builder.d.ts

@@ -40,6 +40,16 @@
  */
 import type { BcRelationEntry, BcRelationsModuleEntry } from '../utils/relations-file.js';
 import type { ModuleDefinitionSchema } from './model.js';
+/**
+ * `<module>` half of a `relationship.modulePath`, in the SAME shape the
+ * generator's own relation-building resolves it to a file/schema-map key:
+ * every segment after the bounded context is joined with '-' (e.g.
+ * `iam/user/profile` -> `user-profile`), not just the second segment. The
+ * authoring-time gate (`schema-loader.ts::assertRelationshipModulePathsExist`)
+ * imports this instead of re-deriving its own 2-segment split, so a
+ * multi-segment modulePath resolves to the SAME file both places check.
+ */
+export declare function moduleNameFromModulePath(modulePath: string): string;
 /**
  * One declared cross-BC relation, paired with the OWNER and TARGET identity
  * a resolution/upsert step (tasks.md groups 4-5) needs — never re-derives

package/dist/generator/domain/relations-builder.js

@@ -59,7 +59,16 @@ function schemaMapKey(boundedContextName, moduleName) {
 function isSameBoundedContext(schema, property) {
     return property.relationship.modulePath.split('/')[0] === toKebabCase(schema.boundedContextName);
 }
-function moduleNameFromModulePath(modulePath) {
+/**
+ * `<module>` half of a `relationship.modulePath`, in the SAME shape the
+ * generator's own relation-building resolves it to a file/schema-map key:
+ * every segment after the bounded context is joined with '-' (e.g.
+ * `iam/user/profile` -> `user-profile`), not just the second segment. The
+ * authoring-time gate (`schema-loader.ts::assertRelationshipModulePathsExist`)
+ * imports this instead of re-deriving its own 2-segment split, so a
+ * multi-segment modulePath resolves to the SAME file both places check.
+ */
+export function moduleNameFromModulePath(modulePath) {
     return modulePath.split('/').slice(1).join('-');
 }
 /** `<bc>/<module>` path of a schema, in the same kebab-case shape `relationship.modulePath` uses. */
@@ -352,7 +361,7 @@ export function buildBcRelationsModuleEntry(schema) {
         // SAME `@app/<bc>/` tree, the module barrel is still the public surface
         // a sibling file imports from (HR-BARRELS-002) — not a reach-in relative
         // path to the module's internal `infrastructure/drizzle/` subdirectory.
-        importPath: `@app/${bcKebab}/${modKebab}`,
+        importPath: `@app/${bcKebab}/${modKebab}/index.js`,
         key: schemaMapKey(schema.boundedContextName, schema.moduleName),
         relations,
         tableSymbol: tableSymbol(schema.boundedContextName, schema.moduleName),
@@ -378,7 +387,7 @@ export function buildCustomFieldValueRelationsModuleEntry(schema) {
         // Satellite of the parent module (design.md D2: "no separate .aurora.yaml
         // aggregate") — the value table's pgTable symbol is exported from the
         // SAME module barrel as the parent, not a barrel of its own.
-        importPath: `@app/${bcKebab}/${modKebab}`,
+        importPath: `@app/${bcKebab}/${modKebab}/index.js`,
         key: customFieldValueSchemaMapKey(schema),
         relations: [{ expression: `r.one.${ownKey}()`, label: toCamelCase(schema.moduleName) }],
         tableSymbol: getCustomFieldValueTableSymbol(schema),
@@ -405,7 +414,7 @@ export function buildI18nTableRelationsModuleEntry(schema) {
         // Satellite of the parent module (same convention as the custom-field-value
         // companion) — the i18n table's pgTable symbol is exported from the SAME
         // module barrel as the parent, not a barrel of its own.
-        importPath: `@app/${bcKebab}/${modKebab}`,
+        importPath: `@app/${bcKebab}/${modKebab}/index.js`,
         key: i18nTableSchemaMapKey(schema),
         relations: [{ expression: `r.one.${ownKey}()`, label: toCamelCase(schema.moduleName) }],
         tableSymbol: getI18nTableTableSymbol(schema),

package/dist/generator/domain/schema-loader.d.ts

@@ -11,3 +11,44 @@ export declare function parseBoundedContextModule(input: string): {
     boundedContextName: string;
     moduleName: string;
 };
+/**
+ * Pure-validation entry point onto the seven `createOnly`/`readOnly` rules
+ * above, for a consumer that must CHECK a schema without normalizing it
+ * in-place (`packages/cli/src/sheets/sync/sheet-to-yaml.ts`'s pull path,
+ * add-create-only-property-semantics).
+ *
+ * This function IS `validateAndNormalizePropertyFlags` — run against a deep
+ * clone of `properties`, so it can never mutate the caller's schema in place
+ * and can never re-emit the deprecated-`readonly` `console.warn` for a key
+ * the caller already normalized through its own dedicated step
+ * (`normalizeDeprecatedReadonlyKey`, called before the pull ever reaches this
+ * point). Every one of the seven rules therefore has exactly ONE
+ * implementation shared with the loader.
+ *
+ * Clone-over-split was chosen over splitting `validateAndNormalizePropertyFlags`
+ * into a separate "pure validation" function and a separate "normalize the
+ * deprecated key" function: the seven rules read `raw.readOnly` after the
+ * function's OWN normalization step has already run in the same pass, so
+ * splitting them apart would require either duplicating the normalization
+ * step in both halves or threading an already-normalized flag through every
+ * call site — more surface for the two halves to drift apart than a single
+ * clone call costs at pull time (a handful of properties, once per module).
+ */
+export declare function validatePropertyFlags(properties: Record<string, unknown>[] | undefined, aggregateName: string, boundedContextName: string, moduleName: string, excludedOperations: unknown, yamlPath: string, i18nStrategy?: 'embedded' | 'table'): void;
+/**
+ * Authoring-time gate for the module a caller is actively generating: every
+ * `relationship.modulePath` declared on `schema` (including one nested inside
+ * a many-to-many pivot's own `aggregateProperties`) MUST name a schema that
+ * exists on disk — crossing a bounded context is legitimate (decided in
+ * T-4.2), the target YAML simply has to be there. Deliberately kept OUT of
+ * `loadSchema`/`validateSchema`, which stays a permissive read primitive:
+ * `discoverDeclaredCrossBcRelations` scans every `cliter/` YAML to find
+ * candidates before `isModuleGenerated` decides which ones resolve, and
+ * `cross-schema-resolver`/`property-mappers` load a related schema for one
+ * specific check without requiring every other relationship on it to
+ * resolve — all three would break if `loadSchema` itself refused a schema
+ * over an unrelated dangling `modulePath`. Call this explicitly at the one
+ * point where "the author is generating THIS module right now" is true (the
+ * `generate` command, right after its own `loadSchema` call).
+ */
+export declare function assertRelationshipModulePathsExist(schema: ModuleDefinitionSchema, cwd?: string): void;

package/dist/generator/domain/schema-loader.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
 import { DETAIL_MODE, DIALOG_WIDTH, GENDER, SCHEMA_DEFINITION_EXTENSION, VALID_PROPERTY_TYPES, } from './config.js';
+import { moduleNameFromModulePath } from './relations-builder.js';
 /**
  * Load a module definition schema from a YAML file.
  *
@@ -15,7 +16,7 @@ export function loadSchema(boundedContextName, moduleName, cwd = process.cwd())
     }
     const raw = fs.readFileSync(yamlPath, 'utf8');
     const parsed = YAML.parse(raw);
-    validateSchema(parsed);
+    validateSchema(parsed, yamlPath);
     return addDefaults(parsed);
 }
 export function saveSchema(schema, cwd = process.cwd()) {
@@ -35,7 +36,30 @@ export function parseBoundedContextModule(input) {
     }
     return { boundedContextName, moduleName };
 }
-function validateSchema(obj) {
+/**
+ * Field paths for which the deprecated `readonly` -> `readOnly` migration
+ * warning has already been printed once (add-create-only-property-semantics).
+ * `loadSchema` runs repeatedly for the same module during one
+ * `catalyst generate` invocation (cross-schema resolution re-reads related
+ * modules), so without this dedup a single run prints the identical
+ * migration line once per re-read — the same shape of fix already applied on
+ * the runtime side (`sanitize-record.function.ts`'s `deprecatedAliasWarned`).
+ * Keyed by `${yamlPath}:${propertyPath}`, so two different files declaring a
+ * property with the same name still warn independently.
+ *
+ * KNOWN LIMITATION, same shape as `deprecatedAliasWarned`'s own doc comment:
+ * this `Set` is MODULE-level, so it persists for the lifetime of the process
+ * (or, in tests, for the whole Mocha run — the module is loaded once). A spec
+ * that loads a FIXED fixture `yamlPath` twice (across two `it()`s, or across
+ * two spec files) shares ONE dedup key: only the FIRST load ever warns, so a
+ * second spec asserting "warns exactly once" against that same fixed path
+ * would see the warning already consumed and get a vacuous pass (or a
+ * confusing zero-warnings failure) depending on run order. Today's specs
+ * dodge this by luck — each one writes its fixture YAML into a fresh, unique
+ * `tmpdir()` path per test — not by a guarantee this `Set` provides.
+ */
+const deprecatedReadonlyWarned = new Set();
+function validateSchema(obj, yamlPath) {
     const required = [
         ['boundedContextName', 'string'],
         ['moduleName', 'string'],
@@ -52,6 +76,282 @@ function validateSchema(obj) {
     }
     validateFrontBlock(obj);
     validatePropertyTypes(obj.aggregateProperties, obj.boundedContextName, obj.moduleName);
+    validateAndNormalizePropertyFlags(obj.aggregateProperties, obj.aggregateName, obj.boundedContextName, obj.moduleName, obj.excludedOperations, obj.i18nStrategy, yamlPath);
+}
+/**
+ * Validates and NORMALIZES the `readOnly` / `createOnly` property flags
+ * in-place on the raw parsed YAML object, before it is cast to
+ * `ModuleDefinitionSchema` (add-create-only-property-semantics):
+ *
+ * - a property declaring `createOnly`, `readOnly`, or the deprecated
+ *   `readonly` with a value that is not a literal boolean fails the load
+ *   naming the aggregate, the property and the value found. This
+ *   runs BEFORE every other check below, which all test truthiness and
+ *   would otherwise silently accept a YAML-1.1 string like `"yes"` — the
+ *   `yaml` package's default 1.2 core schema does not coerce it to `true`;
+ * - a property declaring the deprecated `readonly` spelling and not the
+ *   canonical `readOnly` is normalized to `readOnly` in-memory, and emits
+ *   exactly ONE deprecation warning naming the file, the property and the
+ *   remedy — downstream of this function nothing reads `readonly`;
+ * - a property declaring BOTH spellings, or both `readOnly` and `createOnly`,
+ *   fails the load naming the file and the property (guessing a winner would
+ *   silently change the author's declared contract — design D5);
+ * - a property declaring `createOnly` on a `type: 'relationship'` property
+ *   (many-to-many, or a one-to-many/one-to-one navigation property — NOT a
+ *   many-to-one FK, which is `type: 'id'` with a `relationship` block and is
+ *   therefore untouched by this gate) fails the load naming the aggregate
+ *   and the property. `createOnly` has no reliable enforcement point there:
+ *   a many-to-many property's write-side "<singular>Ids" sibling entry is
+ *   built independently of this property's own field-schema entry
+ *   (`property-mappers.ts` builds it inline and never reaches
+ *   `makeScalarEntry`, the only place that copies the flag), and a
+ *   navigation-only property carries no scalar field-schema entry at all.
+ *   A many-to-one FK's scalar entry DOES carry the flag (`makeScalarEntry`
+ *   copies it), and the runtime guard fires on it — this shape is the
+ *   canonical use of `createOnly` on a relationship ("the client picks the
+ *   parent at creation, frozen afterwards"). Its one real
+ *   gap — the embed-form dialog injects the parent FK into the update
+ *   payload too — is closed at the template that does the injecting
+ *   (`__module_name__-form-embed.component.ts.eta`), not here;
+ * - a property declaring `createOnly` on the PRIMARY KEY fails the load
+ *   naming the aggregate and the property. The generated update-by-id
+ *   handler still reads `payload.<primaryKey>` to identify the record after
+ *   the field is stripped from the update-by-id input/DTO, which does not
+ *   compile;
+ * - a property declaring `createOnly` on an aggregate that does not exclude
+ *   `upsert` fails the load naming the aggregate, the property and the
+ *   remedy (design D6): the generated upsert handler types its payload with
+ *   the update-by-id input, which no longer carries the field;
+ * - a property declaring `createOnly` on an `autoIncrement` property fails
+ *   the load naming the aggregate and the property: the same class
+ *   of "silently does nothing" this whole rule set exists to catch —
+ *   `buildFieldSchemaEntries` (`property-mappers.ts`) skips every
+ *   `autoIncrement` property before it reaches `makeScalarEntry`, the only
+ *   place that copies the flag onto a field-schema entry, so no runtime
+ *   guard is ever emitted;
+ * - a property declaring BOTH `isI18n: true` and `createOnly: true` fails
+ *   the load naming the aggregate and the property, UNCONDITIONALLY —
+ *   whatever the owning module's `i18nStrategy`. Measured cause:
+ *   `isAllowProperty` (`property-mappers.ts`) returns early on the
+ *   `property.isI18n && i18nStrategy !== 'table'` branch, BEFORE it ever
+ *   reaches the `createOnly` gate — so under the embedded strategy the key
+ *   stays in every update input/DTO while `makeScalarEntry` still emits
+ *   `createOnly: true` on the generated field-schema entry, and the runtime
+ *   rejects a key the public contract still advertises as writable: every
+ *   edit of the aggregate returns a 400. Under `'table'` the property IS
+ *   correctly dropped from the update-by-id input/DTO, but the update-by-id
+ *   service template still destructures every `getI18nProperties()` field
+ *   name (with no `createOnly` filter) out of that same payload type, so the
+ *   emitted TypeScript fails to compile (`TS2339`). The remedy is unchanged:
+ *   drop one of the two flags.
+ * - a property declaring BOTH `isI18n: true` and `readOnly: true` fails the
+ *   load naming the aggregate and the property, but ONLY when the owning
+ *   module's `i18nStrategy` is the default/explicit `'embedded'` — UNLIKE
+ *   the `createOnly` rule above, this one is conditional. Under `'embedded'`
+ *   the failure mode is the same silent-400 shape as `isI18n`+`createOnly`:
+ *   `isAllowProperty`'s `isI18n` branch returns before it ever reaches the
+ *   `readOnly` gate, so the key stays in the update contract while
+ *   `makeScalarEntry` still emits `readOnly: true` on the field-schema entry
+ *   — every edit that includes it is rejected at runtime. Under `'table'`
+ *   this combination is SAFE and loads fine: `readOnly` (unlike `createOnly`)
+ *   has a widening mechanism — `readonly-payload-types.ts`'s
+ *   `getReadonlyProperties` filters only on `isReadOnly`, with no `isI18n`
+ *   exclusion — so under `'table'` the field is correctly dropped from the
+ *   public update-by-id input (`isAllowProperty` falls through to the
+ *   generic `readOnly && !allowReadonly` gate once `i18nStrategy` is
+ *   `'table'`) but is re-added as an OPTIONAL member on the internal
+ *   `<Bc>Update<Mod>ByIdPayload` type the update-by-id SERVICE actually
+ *   destructures against — it compiles clean. MEASURED, not deduced:
+ *   `test/codegen/backend/i18n-readonly-table-typecheck.test.ts` renders the
+ *   real update-by-id-service and payload-types templates for a
+ *   `table`-strategy fixture with this exact combination and typechecks the
+ *   result with `tsc --strict` (zero diagnostics), plus a sensitivity
+ *   control that strips the widened member back out and confirms the same
+ *   render then fails to compile — proving the clean result isn't vacuous.
+ *
+ * Recurses into a many-to-many property's pivot `aggregateProperties`,
+ * carrying the PIVOT's own identity (aggregateName/boundedContextName/
+ * moduleName/excludedOperations) — a pivot is its own generated module, so
+ * its `createOnly` + `upsert` check is against its own exclusions, not the
+ * owning aggregate's. The `isI18n` + `createOnly` rejection above applies to
+ * a pivot's own properties the same way, through this same recursion,
+ * unconditionally. The `isI18n` + `readOnly` rejection ALSO applies
+ * unconditionally to a pivot's own properties — not because the rule itself
+ * is unconditional (it isn't), but because a pivot never carries its own
+ * `i18nStrategy` (`RelationshipPivot` has no such field, and
+ * `buildPivotSchema` never copies one in), so every downstream `?? 'embedded'`
+ * default applies to a pivot's generated module regardless of the OWNING
+ * aggregate's `i18nStrategy`. The recursive call below therefore never
+ * forwards the owning module's `i18nStrategy` into the pivot's own check —
+ * it always validates the pivot as `'embedded'`, matching what the pivot's
+ * own codegen actually does.
+ */
+function validateAndNormalizePropertyFlags(properties, aggregateName, boundedContextName, moduleName, excludedOperations, i18nStrategy, yamlPath) {
+    if (!Array.isArray(properties))
+        return;
+    const excluded = Array.isArray(excludedOperations) ? excludedOperations : [];
+    for (const raw of properties) {
+        const propertyPath = `${boundedContextName}/${moduleName}.${String(raw.name)}`;
+        // Type gate, BEFORE every combination gate below: the `yaml`
+        // package's default 1.2 core schema parses `createOnly: yes` as the
+        // STRING 'yes', not the boolean `true` — a natural YAML-1.1 typo. Every
+        // downstream consumer (this function's own combination gates included)
+        // tests truthiness, so a non-boolean value slips past every rejection
+        // below while still taking effect at codegen (`isAllowProperty` drops
+        // the key from update contracts, `makeScalarEntry` emits the flag on
+        // the field-schema entry) — refuse it here, by TYPE, so every gate past
+        // this point can trust it received an actual boolean.
+        for (const flagName of ['createOnly', 'readOnly', 'readonly']) {
+            const value = raw[flagName];
+            if (value !== undefined && typeof value !== 'boolean') {
+                throw new TypeError(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                    `declares "${flagName}" with a non-boolean value (${JSON.stringify(value)}). "${flagName}" ` +
+                    `must be a literal boolean — a quoted or YAML-1.1 string (e.g. "yes"/"no") is silently truthy ` +
+                    `to every downstream consumer and bypasses every "${flagName}" rejection. Remedy: use ` +
+                    `${flagName}: true or ${flagName}: false.`);
+            }
+        }
+        const hasCanonicalReadOnly = raw.readOnly !== undefined;
+        const hasDeprecatedReadonly = raw.readonly !== undefined;
+        if (hasCanonicalReadOnly && hasDeprecatedReadonly) {
+            throw new Error(`YAML schema error in "${yamlPath}": property "${propertyPath}" declares BOTH "readOnly" and the deprecated "readonly". Declare only "readOnly".`);
+        }
+        if (hasDeprecatedReadonly && !hasCanonicalReadOnly) {
+            raw.readOnly = raw.readonly;
+            delete raw.readonly;
+            const dedupKey = `${yamlPath}:${propertyPath}`;
+            if (!deprecatedReadonlyWarned.has(dedupKey)) {
+                deprecatedReadonlyWarned.add(dedupKey);
+                console.warn(`${yamlPath}: property "${propertyPath}" uses the deprecated "readonly" key — rename it to ` +
+                    `"readOnly" in the YAML. "readonly" is removed in the next major of @aurorajs.dev/catalyst.`);
+            }
+        }
+        if (raw.readOnly === true && raw.createOnly === true) {
+            throw new Error(`YAML schema error in "${yamlPath}": property "${propertyPath}" declares BOTH "readOnly" and ` +
+                `"createOnly". They are mutually exclusive — declare only one.`);
+        }
+        if (raw.createOnly === true && raw.type === 'relationship') {
+            throw new Error(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                `declares "createOnly" on a "relationship"-typed property (many-to-many, or a one-to-many/ ` +
+                `one-to-one navigation property). "createOnly" has no enforcement point there: a many-to-many ` +
+                `property's write-side "<singular>Ids" sibling entry is built independently of this property's ` +
+                `own field-schema entry, and a navigation-only property carries no scalar field-schema entry at ` +
+                `all for the flag to attach to. Remedy: drop "createOnly" from this property — a many-to-one FK ` +
+                `(type: "id" with a "relationship" block) is unaffected by this rejection, since it DOES carry ` +
+                `a scalar field-schema entry the flag attaches to.`);
+        }
+        // `primaryKey` has no load-time type gate of its own (unlike createOnly/
+        // readOnly/readonly above) — it is a pre-existing key that may already
+        // carry a non-boolean value in a schema in the wild, so adding a strict
+        // gate here would refuse YAML that loads and works today. Truthiness
+        // matches every downstream consumer instead, so a YAML-1.1 "yes" habit
+        // still triggers this rejection.
+        if (raw.createOnly === true && raw.primaryKey) {
+            throw new Error(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                `declares "createOnly" on the primary key. The generated update-by-id handler still reads ` +
+                `"payload.${String(raw.name)}" to identify the record after the field is stripped from the ` +
+                `update-by-id input/DTO, which does not compile. Remedy: drop "createOnly" from the primary key.`);
+        }
+        // `autoIncrement` gets the same treatment as `primaryKey` above: no
+        // strict type gate (pre-existing key, possible non-boolean values in the
+        // wild), so this rejection matches on truthiness instead of `=== true`.
+        if (raw.createOnly === true && raw.autoIncrement) {
+            throw new Error(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                `declares "createOnly" on an "autoIncrement" property. "buildFieldSchemaEntries" ` +
+                `(property-mappers.ts) skips every autoIncrement property before it ever reaches ` +
+                `"makeScalarEntry" — the only place that copies the "createOnly" flag onto a field-schema ` +
+                `entry — so no runtime guard is ever emitted for it. The flag would silently do nothing. ` +
+                `Remedy: drop "createOnly" from the autoIncrement property.`);
+        }
+        // `excludedOperations` is the ONLY mechanism this gate honors. A module
+        // can also suppress individual generated files via `excludedFiles`, but
+        // that is per-file surgery, not a coherent "this operation does not
+        // exist" declaration: it never removes the upsert RESOLVER (only its own
+        // exact path or a matching glob is suppressed, and the resolver still
+        // imports and injects the upsert handler regardless), and excluding the
+        // whole `src/@app/**` tree to reach the handler also removes every
+        // `*.field-schema.ts` file — the runtime `createOnly` guard along with
+        // it. Either shape leaves the module broken independent of `createOnly`,
+        // so this gate does not try to detect it.
+        if (raw.createOnly === true && !excluded.includes('upsert')) {
+            throw new Error(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                `declares "createOnly" but does not exclude "upsert" in "excludedOperations". The generated ` +
+                `upsert handler cannot populate this field once it is removed from the update-by-id input. ` +
+                `Remedy: add "upsert" to excludedOperations, or drop the createOnly flag.`);
+        }
+        // `isI18n` gets the same treatment as `primaryKey` above: no strict type
+        // gate (pre-existing key, possible non-boolean values in the wild), so
+        // this rejection matches on truthiness instead of `=== true`.
+        if (raw.isI18n && raw.createOnly === true) {
+            throw new Error(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                `declares BOTH "isI18n" and "createOnly". Under "i18nStrategy: 'table'" the update-by-id ` +
+                `service still destructures this field out of a payload type that no longer carries it, so ` +
+                `the emitted TypeScript does not compile; under the default "i18nStrategy: 'embedded'" the ` +
+                `field stays in the update contract ("isAllowProperty" never reaches the "createOnly" check ` +
+                `for an isI18n property) while the field-schema entry still marks it "createOnly", so every ` +
+                `edit that includes it is rejected at runtime with a 400. Remedy: drop one of the two flags.`);
+        }
+        // `isI18n` + `readOnly` is conditional on `i18nStrategy` (unlike
+        // `createOnly` above) — safe under `'table'` (readOnly-payload widening
+        // re-adds the field), unsafe under the default/explicit `'embedded'`
+        // (isAllowProperty's isI18n branch never reaches the readOnly gate). See
+        // the function's own JSDoc for the measured evidence.
+        if (raw.isI18n && raw.readOnly === true && i18nStrategy !== 'table') {
+            throw new Error(`YAML schema error in "${yamlPath}": aggregate "${aggregateName}" property "${propertyPath}" ` +
+                `declares BOTH "isI18n" and "readOnly" under "i18nStrategy: '${i18nStrategy ?? 'embedded'}'". ` +
+                `"isAllowProperty" (property-mappers.ts) returns early on the "isI18n" branch before it ever ` +
+                `reaches the "readOnly" gate, so the field stays in the update contract while the generated ` +
+                `field-schema entry still marks it "readOnly" — every edit that includes it is rejected at ` +
+                `runtime with a 400. Remedy: drop one of the two flags, or declare "i18nStrategy: 'table'" on ` +
+                `the module — under "table" the readonly-payload widening covers this combination and it loads fine.`);
+        }
+        const relationship = raw.relationship;
+        const pivot = relationship?.pivot;
+        if (Array.isArray(pivot?.aggregateProperties)) {
+            validateAndNormalizePropertyFlags(pivot.aggregateProperties, String(pivot.aggregateName ?? aggregateName), String(pivot.boundedContextName ?? boundedContextName), String(pivot.moduleName ?? moduleName), pivot.excludedOperations, 
+            // A pivot never carries its own `i18nStrategy` (`RelationshipPivot`
+            // has no such field, and `buildPivotSchema` never copies one in), so
+            // its own generated module always renders under the embedded
+            // default downstream — NOT the owning aggregate's `i18nStrategy`.
+            // Deliberately not forwarding `i18nStrategy` here, unconditionally.
+            undefined, yamlPath);
+        }
+    }
+}
+/**
+ * Pure-validation entry point onto the seven `createOnly`/`readOnly` rules
+ * above, for a consumer that must CHECK a schema without normalizing it
+ * in-place (`packages/cli/src/sheets/sync/sheet-to-yaml.ts`'s pull path,
+ * add-create-only-property-semantics).
+ *
+ * This function IS `validateAndNormalizePropertyFlags` — run against a deep
+ * clone of `properties`, so it can never mutate the caller's schema in place
+ * and can never re-emit the deprecated-`readonly` `console.warn` for a key
+ * the caller already normalized through its own dedicated step
+ * (`normalizeDeprecatedReadonlyKey`, called before the pull ever reaches this
+ * point). Every one of the seven rules therefore has exactly ONE
+ * implementation shared with the loader.
+ *
+ * Clone-over-split was chosen over splitting `validateAndNormalizePropertyFlags`
+ * into a separate "pure validation" function and a separate "normalize the
+ * deprecated key" function: the seven rules read `raw.readOnly` after the
+ * function's OWN normalization step has already run in the same pass, so
+ * splitting them apart would require either duplicating the normalization
+ * step in both halves or threading an already-normalized flag through every
+ * call site — more surface for the two halves to drift apart than a single
+ * clone call costs at pull time (a handful of properties, once per module).
+ */
+export function validatePropertyFlags(properties, aggregateName, boundedContextName, moduleName, excludedOperations, yamlPath, 
+// Optional, default-absent (treated as `'embedded'` by the isI18n+readOnly
+// rule): the sheets sync's `AuroraSchema` (`src/sheets/domain/types.ts`)
+// has no `i18nStrategy` field of its own, so its one caller
+// (`sheet-to-yaml.ts`) has nothing to pass here today — embedded is also
+// the conservative choice, since it is the strategy every sheets-pulled
+// module renders under regardless.
+i18nStrategy) {
+    if (!Array.isArray(properties))
+        return;
+    validateAndNormalizePropertyFlags(structuredClone(properties), aggregateName, boundedContextName, moduleName, excludedOperations, i18nStrategy, yamlPath);
 }
 /** Actionable, load-time rejection of an unrecognized `type` value — see `VALID_PROPERTY_TYPES`. */
 function throwUnknownPropertyType(propertyPath, type) {
@@ -100,6 +400,53 @@ function validatePropertyTypes(properties, boundedContextName, moduleName) {
         }
     }
 }
+/**
+ * Authoring-time gate for the module a caller is actively generating: every
+ * `relationship.modulePath` declared on `schema` (including one nested inside
+ * a many-to-many pivot's own `aggregateProperties`) MUST name a schema that
+ * exists on disk — crossing a bounded context is legitimate (decided in
+ * T-4.2), the target YAML simply has to be there. Deliberately kept OUT of
+ * `loadSchema`/`validateSchema`, which stays a permissive read primitive:
+ * `discoverDeclaredCrossBcRelations` scans every `cliter/` YAML to find
+ * candidates before `isModuleGenerated` decides which ones resolve, and
+ * `cross-schema-resolver`/`property-mappers` load a related schema for one
+ * specific check without requiring every other relationship on it to
+ * resolve — all three would break if `loadSchema` itself refused a schema
+ * over an unrelated dangling `modulePath`. Call this explicitly at the one
+ * point where "the author is generating THIS module right now" is true (the
+ * `generate` command, right after its own `loadSchema` call).
+ */
+export function assertRelationshipModulePathsExist(schema, cwd = process.cwd()) {
+    walkRelationshipModulePaths(schema.aggregateProperties, schema.boundedContextName, schema.moduleName, cwd);
+}
+function walkRelationshipModulePaths(properties, boundedContextName, moduleName, cwd) {
+    if (!Array.isArray(properties))
+        return;
+    for (const property of properties) {
+        const modulePath = property.relationship?.modulePath;
+        if (modulePath) {
+            const propertyPath = `${boundedContextName}/${moduleName}.${property.name}`;
+            // Same resolver the generator itself uses to turn a modulePath into a
+            // bc/module pair (relations-builder.ts's moduleNameFromModulePath) —
+            // NOT a 2-segment destructure, which silently drops every segment past
+            // the second and checks the wrong file for a 3+-segment modulePath
+            // (e.g. `iam/user/profile` -> `user-profile`, not bare `user`).
+            const targetBc = modulePath.split('/')[0];
+            const targetModule = moduleNameFromModulePath(modulePath);
+            if (!targetBc || !targetModule) {
+                throw new Error(`YAML schema error in "${propertyPath}": relationship.modulePath "${modulePath}" is malformed (expected "bounded-context/module").`);
+            }
+            const targetYamlPath = path.join(cwd, 'cliter', targetBc, targetModule + SCHEMA_DEFINITION_EXTENSION);
+            if (!fs.existsSync(targetYamlPath)) {
+                throw new Error(`YAML schema error in "${propertyPath}": relationship.modulePath "${modulePath}" does not name an existing schema. Expected file: ${targetYamlPath}`);
+            }
+        }
+        const pivot = property.relationship?.pivot;
+        if (pivot) {
+            walkRelationshipModulePaths(pivot.aggregateProperties, pivot.boundedContextName ?? boundedContextName, pivot.moduleName ?? moduleName, cwd);
+        }
+    }
+}
 function validateFrontBlock(obj) {
     const { front } = obj;
     if (front === undefined || front === null)

package/dist/generator/engine/code-writer/code-writer.d.ts

@@ -204,7 +204,7 @@ export declare 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
@@ -224,13 +224,17 @@ export declare 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