@aurorajs.dev/catalyst-cli 1.1.3 → 2.0.0

package/dist/generator/utils/code-gen.js

@@ -3,7 +3,11 @@
  * importManager, constructorInjectorManager, returnTypeManager, indexesManager, variablesInjectorManager.
  */
 import { toCamelCase, toSnakeCase } from './string-utils.js';
-/** 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 function importManager({ commandType = 'import', imports = [], sortImportedClasses = true, sortImports = true, }) {
     const grouped = new Map();
     for (const imp of imports) {

package/dist/generator/utils/relations-file.js

@@ -97,6 +97,67 @@ function getBcRelationsObjectLiteralOrThrow(sourceFile, boundedContextCamelCase)
     }
     return relationsObj;
 }
+/**
+ * True when the `(r) => ({ ... })` callback's BODY actually reads the identifier `r` —
+ * decided by reading the fact (golden rule 1: the YAML/generator declares, it never
+ * infers), not by guessing from the SHAPE of the object literal it returns. A generated
+ * entry is always a `key: {}` or `key: { label: r.many.foo(...) }` object literal, but a
+ * hand-written customization next to it can read `r` through a form that shape alone
+ * cannot see: a spread (`...customRelations(r)`), a non-literal initializer
+ * (`legacyManual: buildLegacyManualRelations(r)`), or any other expression — the file is
+ * editable by convention (`@aurora-catalyst-generated` files ARE editable), so the next
+ * `catalyst generate` must not delete a parameter a hand-written line still needs.
+ *
+ * Walks every descendant `Identifier` of the arrow function's body whose text is `r`,
+ * excluding the parameter declaration itself (its own name is an Identifier too) and an
+ * identifier sitting in PROPERTY-NAME position (`r: something` would otherwise false-
+ * positive on an object key that merely happens to be named `r`, not a reference to the
+ * parameter).
+ */
+const RELATIONS_CALLBACK_PARAMETER_NAME = 'r';
+function relationsCallbackBodyReadsParameter(arrowFn) {
+    const parameter = arrowFn.getParameters()[0];
+    const parameterNameNode = parameter?.getName() === RELATIONS_CALLBACK_PARAMETER_NAME ? parameter.getNameNode() : undefined;
+    const body = arrowFn.getBody();
+    return body.getDescendantsOfKind(SyntaxKind.Identifier).some((identifier) => {
+        if (identifier.getText() !== RELATIONS_CALLBACK_PARAMETER_NAME)
+            return false;
+        if (identifier === parameterNameNode)
+            return false;
+        const parent = identifier.getParent();
+        // A shorthand property (`{ r }`) both NAMES and REFERENCES `r` — a real read, kept.
+        // A non-shorthand key (`r: value`) merely happens to be named `r` — not a read.
+        const isNonShorthandPropertyName = parent?.asKind(SyntaxKind.PropertyAssignment)?.getNameNode() === identifier;
+        return !isNonShorthandPropertyName;
+    });
+}
+/**
+ * Keeps the `defineRelations(<bc>Schema, (r) => ({ ... }))` callback's
+ * parameter list in sync with whether its BODY actually reads `r` —
+ * declared-but-unused triggers oxlint's `no-unused-vars` the moment a
+ * bounded context's every module has empty relations (measured: `lacrem`,
+ * `partner`, `sap-integration`). Re-evaluated on every upsert, so clearing
+ * the last relation-carrying module drops the parameter again and adding
+ * one back — generated OR hand-written — restores it.
+ */
+function syncRelationsCallbackParameter(sourceFile) {
+    const defineRelationsCall = CallExpressionDriver.findCallExpression(sourceFile, 'defineRelations');
+    const arrowFn = defineRelationsCall?.getArguments()[1]?.asKind(SyntaxKind.ArrowFunction);
+    if (!arrowFn)
+        return;
+    const needsParameter = relationsCallbackBodyReadsParameter(arrowFn);
+    const hasParameter = arrowFn.getParameters().length > 0;
+    if (needsParameter && !hasParameter) {
+        arrowFn.addParameter({ name: 'r' });
+    }
+    else if (!needsParameter && hasParameter) {
+        // Removing in place shifts remaining indices, so walk back-to-front.
+        const parameters = arrowFn.getParameters();
+        for (let i = parameters.length - 1; i >= 0; i--) {
+            parameters[i].remove();
+        }
+    }
+}
 /**
  * Upserts one module's entry across the per-BC relations assembly file's
  * three AST anchors (import, schema-map property, relations-map property).
@@ -108,6 +169,7 @@ export function upsertBcRelationsFile(sourceFile, boundedContextCamelCase, entry
     ObjectDriver.upsertProperty(schemaObj, entry.key, entry.tableSymbol);
     const relationsObj = getBcRelationsObjectLiteralOrThrow(sourceFile, boundedContextCamelCase);
     ObjectDriver.upsertProperty(relationsObj, entry.key, buildRelationsObjectLiteralText(entry.relations));
+    syncRelationsCallbackParameter(sourceFile);
 }
 /**
  * Resolves the `crossBcRelations = defineRelationsPart(auroraDrizzleSchema,

package/dist/sheets/domain/types.d.ts

@@ -39,6 +39,8 @@ export interface AuroraWidget {
 export interface AuroraProperty {
     arrayOptions?: AuroraArrayOptions;
     autoIncrement?: boolean;
+    /** Client instantiates once, at creation — never after (add-create-only-property-semantics). */
+    createOnly?: boolean;
     decimals?: [number, number];
     defaultValue?: unknown;
     description?: string;
@@ -55,7 +57,8 @@ export interface AuroraProperty {
     name: string;
     nullable?: boolean;
     primaryKey?: boolean;
-    readonly?: boolean;
+    /** Canonical spelling (add-create-only-property-semantics). The sheet column keeps its existing header, `readonly`. */
+    readOnly?: boolean;
     relationship?: AuroraRelationship;
     type: string;
     /** Integer-only: unsigned column when true. */
@@ -103,6 +106,7 @@ export interface SheetPropertyRow {
     'arrayOptions.maxLength': string;
     'arrayOptions.type': string;
     autoIncrement: string;
+    createOnly: string;
     decimals: string;
     defaultValue: string;
     description: string;

package/dist/sheets/domain/types.js

@@ -10,6 +10,7 @@ export const PROPERTY_HEADERS = [
     'unsigned',
     'autoIncrement',
     'readonly',
+    'createOnly',
     'index',
     'indexUsing',
     'indexName',
@@ -169,6 +170,7 @@ export function retiredHeaderIndexes(headers) {
  */
 export const REQUIRED_PROPERTY_COLUMNS = [
     'readonly',
+    'createOnly',
     'unsigned',
     'indexName',
     'indexFields',
@@ -225,6 +227,7 @@ export function sheetControlledHeaders(headers, rows) {
  */
 const COLUMN_WIDTHS = {
     autoIncrement: 110,
+    createOnly: 95,
     defaultValue: 130,
     description: 520,
     example: 130,

package/dist/sheets/sync/sheet-to-yaml.d.ts

@@ -1,5 +1,5 @@
 import { sheets_v4 } from 'googleapis';
-import type { AuroraPivot, AuroraProperty } from '../domain/types.js';
+import type { AuroraPivot, AuroraProperty, AuroraSchema } from '../domain/types.js';
 export interface PullOptions {
     backup?: boolean;
     dryRun?: boolean;
@@ -21,6 +21,7 @@ export interface PullContext {
 }
 /** Pull schemas from one BC's Google Sheet into local YAML files. */
 export declare function pullBoundedContext(context: PullContext, options?: PullOptions): Promise<PullResult>;
+export declare function readModuleSheet(api: sheets_v4.Sheets, spreadsheetId: string, sheetName: string, existingSchema?: AuroraSchema, boundedContextName?: string): Promise<AuroraSchema | null>;
 /**
  * Split a sheet's grid into the module's own property rows and its pivot blocks.
  *

package/dist/sheets/sync/sheet-to-yaml.js

@@ -1,9 +1,10 @@
 import jsYaml from 'js-yaml';
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { validatePropertyFlags } from '../../generator/domain/schema-loader.js';
 import { sheetControlledHeaders } from '../domain/types.js';
 import { extractPivotNameFromSeparator, isPivotSeparator, parsePivotMetadataRows, } from '../transformers/pivot-transformer.js';
-import { sheetRowToProperty } from '../transformers/property-transformer.js';
+import { normalizeDeprecatedReadonlyKey, sheetRowToProperty, } from '../transformers/property-transformer.js';
 // Sheets to exclude from module processing (system sheets)
 const EXCLUDED_SHEETS = new Set(['DATA', 'MODULES', 'TEMPLATE']);
 /** Pull schemas from one BC's Google Sheet into local YAML files. */
@@ -46,8 +47,16 @@ export async function pullBoundedContext(context, options = {}) {
                 if (existsSync(existingFilePath)) {
                     existingYamlContent = readFileSync(existingFilePath, 'utf8');
                     existingSchema = jsYaml.load(existingYamlContent);
+                    // The sheets sync reads YAML directly and never calls `loadSchema`
+                    // — the one place that normalizes the deprecated `readonly`
+                    // spelling. Without this, a property still declared
+                    // `readonly: true` survives the `{ ...existing }` spread inside
+                    // `mergeProperties` alongside a freshly written `readOnly`, so the
+                    // pulled YAML ends up declaring BOTH spellings — which the next
+                    // `catalyst generate` rejects at load time.
+                    normalizeDeprecatedReadonlyKey(existingSchema.aggregateProperties);
                 }
-                const schema = await readModuleSheet(sheetsApi, spreadsheetId, sheetName, existingSchema);
+                const schema = await readModuleSheet(sheetsApi, spreadsheetId, sheetName, existingSchema, context.boundedContextName);
                 if (!schema) {
                     result.messages.push(`Skipped: ${sheetName} (empty or invalid)`);
                     continue;
@@ -98,7 +107,13 @@ export async function pullBoundedContext(context, options = {}) {
     }
     return result;
 }
-async function readModuleSheet(api, spreadsheetId, sheetName, existingSchema) {
+export async function readModuleSheet(api, spreadsheetId, sheetName, existingSchema, 
+// Only meaningful when `existingSchema` is absent (a brand-new module):
+// there is no YAML on disk yet to read the real `boundedContextName`
+// from, so the caller (`pullBoundedContext`) threads its own
+// `context.boundedContextName` through here instead of leaving the
+// constructed schema with an empty one (see the `propertyPath` fix below).
+boundedContextName = '') {
     const response = await api.spreadsheets.values.get({
         // The sheet name alone means "every populated cell". An `A:Z` cap silently
         // hid every column past the 26th, so a key whose column sits beyond Z was
@@ -148,7 +163,7 @@ async function readModuleSheet(api, spreadsheetId, sheetName, existingSchema) {
         : {
             aggregateName: toPascalCase(sheetName),
             aggregateProperties: properties,
-            boundedContextName: '',
+            boundedContextName,
             moduleName: sheetName,
             moduleNames: sheetName + 's',
             version: '0.0.1',
@@ -160,7 +175,69 @@ async function readModuleSheet(api, spreadsheetId, sheetName, existingSchema) {
             schema.description = existingSchema.description;
         }
     }
-    mergePivotsIntoProperties(schema.aggregateProperties, pivots);
+    const newlyAttachedPivotIndices = mergePivotsIntoProperties(schema.aggregateProperties, pivots);
+    // Fail loudly here rather than writing a YAML `catalyst generate` refuses
+    // forever, by reusing the LOADER'S OWN validation
+    // (`generator/domain/schema-loader.ts`'s `validatePropertyFlags`) instead
+    // of a hand-maintained copy of its rules (add-create-only-property-semantics).
+    // Runs on a VALIDATION-ONLY clone of `schema.aggregateProperties` (built
+    // below), AFTER `mergePivotsIntoProperties` above, so it validates exactly
+    // what gets written to disk: a pivot row whose edits are discarded because
+    // the many-to-many already has a pivot (see `mergePivotsIntoProperties`)
+    // is never checked, and a pivot row that DOES get written is checked with
+    // its real `relationship.pivot` shape — the loader recurses into it the
+    // same way `catalyst generate` will.
+    //
+    // Of the seven rules `validatePropertyFlags` enforces, exactly ONE reads
+    // `excludedOperations` — `createOnly` requires its own scope's
+    // `excludedOperations` to include `'upsert'`. The other six never look at
+    // it, so they still run unconditionally below, on every pull, same as the
+    // loader. That one rule is the only one this pull ever defers, and only
+    // for a scope with NO real source of `excludedOperations` to check
+    // against yet:
+    //
+    // - the whole MODULE, when there is no `existingSchema` — a brand-new
+    //   module the sheet is creating for the first time. No sheet column
+    //   carries `excludedOperations`, and there is no YAML on disk either, so
+    //   the author has had no way to declare it;
+    // - a many-to-many's PIVOT, exactly when `mergePivotsIntoProperties` just
+    //   attached it FROM the sheet's own pivot block (`newlyAttachedPivotIndices`
+    //   above) — the pivot never existed in the YAML before this pull, so its
+    //   `excludedOperations` is equally undeclared. An ALREADY-existing pivot
+    //   keeps its real `excludedOperations` untouched (preserved by
+    //   `mergeProperties`'s spread) and is still enforced as-is.
+    //
+    // Deferring the check for those two cases is NOT a silent bypass: this
+    // pull still writes the YAML exactly as the sheet declared it (with
+    // `createOnly: true`, never a fabricated `excludedOperations`), and the
+    // NEXT `catalyst generate` runs the SAME rule against a real, on-disk YAML
+    // the author can now edit — something a sheet-only scope never offered.
+    const propertiesForValidation = structuredClone(schema.aggregateProperties);
+    for (const index of newlyAttachedPivotIndices) {
+        const pivot = propertiesForValidation[index]?.relationship?.pivot;
+        if (pivot && pivot.excludedOperations === undefined) {
+            pivot.excludedOperations = ['upsert'];
+        }
+    }
+    const excludedOperationsForValidation = existingSchema
+        ? existingSchema.excludedOperations
+        : ['upsert'];
+    try {
+        // The cast below widens, it does not lie: `validatePropertyFlags`
+        // deliberately types its `properties` parameter as `Record<string,
+        // unknown>[]` (it validates raw parsed-YAML bags too, from
+        // `catalyst generate`'s own load path), and TypeScript's structural
+        // typing refuses that widening implicitly for a NAMED interface without
+        // its own index signature — `AuroraProperty` carries every field the
+        // function reads (`readOnly`, `createOnly`, `type`, `primaryKey`,
+        // `autoIncrement`, `isI18n`, `relationship.pivot.aggregateProperties`),
+        // so nothing is hidden, only the interface's name.
+        validatePropertyFlags(propertiesForValidation, schema.aggregateName, schema.boundedContextName, schema.moduleName, excludedOperationsForValidation, `${sheetName}.aurora.yaml`);
+    }
+    catch (error) {
+        const err = error;
+        throw new Error(`Sheet "${sheetName}" cannot be pulled — it would write a YAML that "catalyst generate" refuses to load: ${err.message}`);
+    }
     return schema;
 }
 /**
@@ -392,9 +469,10 @@ function toPascalCase(str) {
  * a blank cell silently drop a description or a default value.
  */
 const CLEARABLE_PROPERTY_FIELDS = new Set([
+    'createOnly',
     'indexFields',
     'indexName',
-    'readonly',
+    'readOnly',
     'unsigned',
 ]);
 /**
@@ -416,6 +494,7 @@ const HEADER_TO_PROPERTY_FIELDS = {
     'arrayOptions.maxLength': ['arrayOptions'],
     'arrayOptions.type': ['arrayOptions'],
     autoIncrement: ['autoIncrement'],
+    createOnly: ['createOnly'],
     decimals: ['decimals'],
     defaultValue: ['defaultValue'],
     description: ['description'],
@@ -433,7 +512,8 @@ const HEADER_TO_PROPERTY_FIELDS = {
     name: ['name'],
     nullable: ['nullable'],
     primaryKey: ['primaryKey'],
-    readonly: ['readonly'],
+    // Column header stays `readonly`; the property field is the canonical `readOnly`.
+    readonly: ['readOnly'],
     'rel.aggregateName': ['relationship'],
     'rel.avoidConstraint': ['relationship'],
     'rel.field': ['relationship'],
@@ -625,9 +705,18 @@ function parsePivotSection(rows, startIdx) {
     };
     return { endIdx: i, pivot };
 }
-/** Merge parsed pivot rows back into the matching many-to-many `relationship.pivot`. */
+/**
+ * Merge parsed pivot rows back into the matching many-to-many `relationship.pivot`.
+ *
+ * Returns the SET OF INDICES (into `properties`) whose `relationship.pivot` was
+ * assigned by THIS call — i.e. a pivot newly attached from the sheet, never one
+ * an existing YAML already carried (the outer `!prop.relationship.pivot` guard
+ * skips those entirely). The caller (`readModuleSheet`) uses this set to know
+ * which pivots have no real on-disk `excludedOperations` to validate against yet.
+ */
 function mergePivotsIntoProperties(properties, pivots) {
-    for (const prop of properties) {
+    const newlyAttachedIndices = new Set();
+    for (const [index, prop] of properties.entries()) {
         if (prop.relationship?.type === 'many-to-many' &&
             !prop.relationship.pivot) {
             const possiblePivotNames = [
@@ -638,17 +727,20 @@ function mergePivotsIntoProperties(properties, pivots) {
                 const pivot = pivots.get(pivotName);
                 if (pivot) {
                     prop.relationship.pivot = pivot;
+                    newlyAttachedIndices.add(index);
                     break;
                 }
             }
             for (const [, pivot] of pivots) {
                 if (pivot.aggregateProperties?.some((p) => p.relationship?.modulePath === prop.relationship?.modulePath)) {
                     prop.relationship.pivot = pivot;
+                    newlyAttachedIndices.add(index);
                     break;
                 }
             }
         }
     }
+    return newlyAttachedIndices;
 }
 function createBackup(backupsPath, cliterPath, boundedContextName) {
     const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');

package/dist/sheets/sync/yaml-to-sheet.js

@@ -2,7 +2,7 @@ import jsYaml from 'js-yaml';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { applyMoves, CHECKMARK, columnMoves, columnWidth, getSchemaPath, mergeRequiredHeaders, PROPERTY_HEADERS, renamedHeaders, retiredHeaderIndexes, toA1Column, } from '../domain/types.js';
-import { propertyToSheetRow } from '../transformers/property-transformer.js';
+import { normalizeDeprecatedReadonlyKey, propertyToSheetRow, } from '../transformers/property-transformer.js';
 import { createPropertyWithoutPivot } from '../transformers/relationship-transformer.js';
 import { formatValidationResult, validateSchema, } from '../validators/schema-validator.js';
 const TEMPLATE_SHEET_NAME = 'TEMPLATE';
@@ -28,6 +28,11 @@ export async function pushBoundedContext(context, options = {}) {
             const filePath = join(bcPath, file);
             const content = readFileSync(filePath, 'utf8');
             const schema = jsYaml.load(content);
+            // The sheets sync reads YAML directly and never calls `loadSchema` — the
+            // one place that normalizes the deprecated `readonly` spelling. Without
+            // this, a property still declared `readonly: true` renders an empty
+            // (unchecked) cell in the pushed sheet.
+            normalizeDeprecatedReadonlyKey(schema.aggregateProperties);
             const validation = validateSchema(schema);
             if (!validation.isValid) {
                 result.messages.push(`Validation failed for ${file}:`, formatValidationResult(validation));

package/dist/sheets/transformers/property-transformer.d.ts

@@ -1,4 +1,43 @@
 import type { AuroraProperty, SheetPropertyRow } from '../domain/types.js';
+/**
+ * Normalizes the deprecated `readonly` YAML key to the canonical `readOnly`,
+ * in place, on every property — the sheets-sync equivalent of what
+ * `schema-loader.ts`'s `validateAndNormalizePropertyFlags` does for
+ * `catalyst generate` (add-create-only-property-semantics, design D8). The
+ * sheets sync parses YAML directly with `jsYaml.load` and never calls
+ * `loadSchema`, so without this normalization it is the one consumer surface
+ * where the deprecated spelling silently stops working:
+ *
+ * - **push** — `propertyToSheetRow` only reads `property.readOnly`, so a
+ *   property still declared `readonly: true` renders an EMPTY cell, reporting
+ *   a read-only field as writable with no warning;
+ * - **pull** — a property spread from a YAML that still carries `readonly`
+ *   survives `mergeProperties`'s `{ ...existing }` spread alongside a freshly
+ *   written `readOnly`, so the property ends up declaring BOTH spellings —
+ *   which the next `catalyst generate` rejects at load time.
+ *
+ * Fails CLOSED where both spellings are present and disagree (mirroring the
+ * runtime's own `sanitizeRecord`, `sanitize-record.function.ts`
+ * "Effective readOnly value"): the STRICTER value wins — `true` if EITHER
+ * spelling says `true` — never the canonical spelling unconditionally, which
+ * would let the canonical key win even when it is the more permissive
+ * `false`, silently dropping the write guard the author declared under the
+ * deprecated spelling. Relying instead on "the load-time contract gate
+ * rejects the combination the next time `catalyst generate` loads the YAML"
+ * does not hold on the PULL path: `sheet-to-yaml.ts` writes the normalized
+ * schema back to the YAML file, so after a pull the deprecated key is
+ * already gone from disk and that gate has nothing left to catch.
+ *
+ * Recurses into a many-to-many property's pivot `aggregateProperties` — a
+ * pivot is its own generated module and carries the deprecated spelling the
+ * same way a top-level property does (the CLI loader's own
+ * `validateAndNormalizePropertyFlags` recurses into pivots for the same
+ * reason). Without this recursion, a pivot property still spelled
+ * `readonly: true` renders an EMPTY sheet cell on push (a frozen column
+ * reported as writable) — the same defect `propertyToSheetRow` has for a
+ * top-level property, just one level deeper.
+ */
+export declare function normalizeDeprecatedReadonlyKey(properties?: AuroraProperty[]): void;
 export declare function propertyToSheetRow(property: AuroraProperty): SheetPropertyRow;
 export declare function sheetRowToProperty(row: SheetPropertyRow): AuroraProperty;
 export declare function propertiesToSheetValues(properties: AuroraProperty[]): string[][];

package/dist/sheets/transformers/property-transformer.js

@@ -54,12 +54,69 @@ function getLengthValue(property) {
     }
     return '';
 }
+/**
+ * Normalizes the deprecated `readonly` YAML key to the canonical `readOnly`,
+ * in place, on every property — the sheets-sync equivalent of what
+ * `schema-loader.ts`'s `validateAndNormalizePropertyFlags` does for
+ * `catalyst generate` (add-create-only-property-semantics, design D8). The
+ * sheets sync parses YAML directly with `jsYaml.load` and never calls
+ * `loadSchema`, so without this normalization it is the one consumer surface
+ * where the deprecated spelling silently stops working:
+ *
+ * - **push** — `propertyToSheetRow` only reads `property.readOnly`, so a
+ *   property still declared `readonly: true` renders an EMPTY cell, reporting
+ *   a read-only field as writable with no warning;
+ * - **pull** — a property spread from a YAML that still carries `readonly`
+ *   survives `mergeProperties`'s `{ ...existing }` spread alongside a freshly
+ *   written `readOnly`, so the property ends up declaring BOTH spellings —
+ *   which the next `catalyst generate` rejects at load time.
+ *
+ * Fails CLOSED where both spellings are present and disagree (mirroring the
+ * runtime's own `sanitizeRecord`, `sanitize-record.function.ts`
+ * "Effective readOnly value"): the STRICTER value wins — `true` if EITHER
+ * spelling says `true` — never the canonical spelling unconditionally, which
+ * would let the canonical key win even when it is the more permissive
+ * `false`, silently dropping the write guard the author declared under the
+ * deprecated spelling. Relying instead on "the load-time contract gate
+ * rejects the combination the next time `catalyst generate` loads the YAML"
+ * does not hold on the PULL path: `sheet-to-yaml.ts` writes the normalized
+ * schema back to the YAML file, so after a pull the deprecated key is
+ * already gone from disk and that gate has nothing left to catch.
+ *
+ * Recurses into a many-to-many property's pivot `aggregateProperties` — a
+ * pivot is its own generated module and carries the deprecated spelling the
+ * same way a top-level property does (the CLI loader's own
+ * `validateAndNormalizePropertyFlags` recurses into pivots for the same
+ * reason). Without this recursion, a pivot property still spelled
+ * `readonly: true` renders an EMPTY sheet cell on push (a frozen column
+ * reported as writable) — the same defect `propertyToSheetRow` has for a
+ * top-level property, just one level deeper.
+ */
+export function normalizeDeprecatedReadonlyKey(properties) {
+    if (!Array.isArray(properties))
+        return;
+    for (const property of properties) {
+        const raw = property;
+        if (raw.readonly !== undefined) {
+            // Both present and disagreeing: the STRICTER value wins (true if
+            // EITHER says true) — see the fail-closed rationale in the function
+            // doc above. Only "readonly" present: adopt it as-is.
+            property.readOnly =
+                raw.readOnly === undefined
+                    ? raw.readonly
+                    : raw.readOnly === true || raw.readonly === true;
+            delete raw.readonly;
+        }
+        normalizeDeprecatedReadonlyKey(property.relationship?.pivot?.aggregateProperties);
+    }
+}
 export function propertyToSheetRow(property) {
     return {
         'arrayOptions.enumOptions': formatEnumOptions(property.arrayOptions?.enumOptions),
         'arrayOptions.maxLength': property.arrayOptions?.maxLength?.toString() || '',
         'arrayOptions.type': property.arrayOptions?.type || '',
         autoIncrement: boolToString(property.autoIncrement),
+        createOnly: boolToString(property.createOnly),
         decimals: formatDecimals(property.decimals),
         defaultValue: formatDefaultValue(property.defaultValue),
         description: cleanDescription(property.description),
@@ -76,7 +133,9 @@ export function propertyToSheetRow(property) {
         name: property.name || '',
         nullable: boolToString(property.nullable),
         primaryKey: boolToString(property.primaryKey),
-        readonly: boolToString(property.readonly),
+        // Column header stays `readonly` (the existing sheet contract); the
+        // property field is the canonical `readOnly` (add-create-only-property-semantics).
+        readonly: boolToString(property.readOnly),
         'rel.aggregateName': property.relationship?.aggregateName || '',
         'rel.avoidConstraint': boolToString(property.relationship?.avoidConstraint),
         'rel.field': property.relationship?.field || '',
@@ -110,7 +169,9 @@ export function sheetRowToProperty(row) {
     if (row.indexFields)
         property.indexFields = parseEnumOptions(row.indexFields);
     if (parseBooleanValue(row.readonly))
-        property.readonly = true;
+        property.readOnly = true;
+    if (parseBooleanValue(row.createOnly))
+        property.createOnly = true;
     if (parseBooleanValue(row.unsigned))
         property.unsigned = true;
     // `length` is the column; `maxLength/length` is its old name, still read from a