@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': minor
+'@objectstack/driver-sql': patch
+'@objectstack/metadata-core': patch
+---
+
+feat(spec): a field declares the key or keys it was renamed from — `renamedFrom` on `FieldSchema`
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+Skills-docs: follow-up #30885 — `skills/**` does not teach the key yet: it is declared ahead of the upgrade step that carries the data (rename execution, #30885), and that step owns the skills line; this diff documents it in `content/docs/data-modeling/fields.mdx` and the generated references
+
+A package author can now say that a field was renamed, so that an upgrade knows a rename from a drop-and-add. On the new field, write the old key: `account_name: Field.text({ label: 'Account Name', renamedFrom: ['company'] })`. A field renamed twice lists both earlier keys. This is the manifest half of the rename mapping ruled on epic objectstack-ai/cloud#3652 (Q3 「默认拒绝，需显式映射（推荐）」, and on where the mapping lives, 「写进清单 renamedFrom」), and it supersedes item 5 of objectstack#24443's ruling A ("No rename spelling is added to the spec").
+
+- **`@objectstack/spec`: `FieldSchema.renamedFrom: string[]`, optional.** Each entry is an earlier key of this same field, in the field-key grammar (lowercase snake_case). The parse refuses, in one located issue naming the object, the field and the old key: an entry that is not a field key (judged by `FieldSchema`), and, in `ObjectSchema`'s refinement beside the stage-field check, an entry that is the field's own key, an entry repeated within one list, an entry that another field of the same object still declares (the old name is still in use), and an old key that two fields of the same object both claim. Type compatibility between the old column and the new field is not judged at parse: it depends on the installed version, so the upgrade plan judges it. An object that does not write the key parses exactly as before; nothing materializes.
+- **Declared ahead of its readers.** Nothing in this release reads the key at upgrade or anywhere else. The upgrade plan (#30884) and the rename execution (#30885) read it; until the execution ships, no upgrade carries a column on this declaration. The liveness ledger records the row as `planned`, naming #30885 as the reader that flips it to `live`.
+- **Publish-time consequence.** `FieldSchema` is strict, so an artifact that carries `renamedFrom` is refused, as an unrecognized key, by every runtime older than this release. A package that adds the key needs an installing runtime at this release or later; a package that does not write it is unaffected.
+- **`@objectstack/driver-sql` and `@objectstack/metadata-core`: the key is classified in the two maps pinned exhaustive over `FieldSchema`.** The SQL driver's builtin-column classification files it as `storage` (on `id`, `created_at` or `updated_at` the platform's own column takes no data from an old one, so the builtin-column diagnostic reports it as discarded there). The field-level security scrub keeps it: the parse refuses any entry that names a live field, so no entry can name a field a caller is denied.
@@ -458,6 +458,12 @@ These properties are available on all field types:
 
 Database indexes are declared at the object level in the object's `indexes[]` array — there is no per-field `index` flag. See [Indexing](/docs/data-modeling/indexing).
 
+### Package upgrades
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `renamedFrom` | `string[]` | — | Earlier keys of this field (snake_case), e.g. `renamedFrom: ['company']` on a field now keyed `account_name`: on a package upgrade from a version that has the old key and not this one, the platform carries the old column's data to this field instead of adding an empty column. Each entry once; never the field's own key, a key another field of the object still declares, or an old key another field also claims — each refused at parse. Read only at package upgrade, and declared ahead of the upgrade step that carries the data: until that step ships, no upgrade carries a column on this declaration |
+
 ### Security
 
 | Property | Type | Default | Description |
 
@@ -125,6 +125,7 @@ const result = CurrencyConfigSchema.parse(data);
 | **placeholder** | `string` | optional | Placeholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from `inlineHelpText` (always-visible help rendered beside/under the input) and `description` (tooltip/developer documentation). |
 | **autonumberFormat** | `string` | optional (default: `"{0000}"`) | Auto-number format: literal text + `{0000}` counter, `{YYYY}`/`{MM}`/`{DD}`/`{YYYYMMDD}` date tokens (business tz), and `{field_name}` interpolation. Counter resets per rendered prefix (e.g. AD`{YYYYMMDD}``{0000}` resets daily). Omitted on an `autonumber` field ⇒ the contract default `{0000}`, which every driver and the engine fallback read, so one field numbers alike on every backend. |
 | **externalId** | `boolean` | optional (default: `false`) | Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own `externalId`; an import names it in the mapping's `upsertKey`. |
+| **renamedFrom** | `string[]` | optional | Earlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. `renamedFrom: ['company']` on a field now keyed `account_name`. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only at package upgrade: no record read, write or query reads it, and the type of the old column is judged by the upgrade plan, not here. Declared ahead of the upgrade step that carries the data: until that step ships, no upgrade carries a column on this declaration. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
 
@@ -294,6 +294,7 @@ const result = ApiMethod.parse(data);
 | **placeholder** | `string` | optional | Placeholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from `inlineHelpText` (always-visible help rendered beside/under the input) and `description` (tooltip/developer documentation). |
 | **autonumberFormat** | `string` | optional (default: `"{0000}"`) | Auto-number format: literal text + `{0000}` counter, `{YYYY}`/`{MM}`/`{DD}`/`{YYYYMMDD}` date tokens (business tz), and `{field_name}` interpolation. Counter resets per rendered prefix (e.g. AD`{YYYYMMDD}``{0000}` resets daily). Omitted on an `autonumber` field ⇒ the contract default `{0000}`, which every driver and the engine fallback read, so one field numbers alike on every backend. |
 | **externalId** | `boolean` | optional (default: `false`) | Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own `externalId`; an import names it in the mapping's `upsertKey`. |
+| **renamedFrom** | `string[]` | optional | Earlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. `renamedFrom: ['company']` on a field now keyed `account_name`. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only at package upgrade: no record read, write or query reads it, and the type of the old column is judged by the upgrade plan, not here. Declared ahead of the upgrade step that carries the data: until that step ships, no upgrade carries a column on this declaration. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -666,6 +667,7 @@ const result = ApiMethod.parse(data);
 | **placeholder** | `string` | optional | Placeholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from `inlineHelpText` (always-visible help rendered beside/under the input) and `description` (tooltip/developer documentation). |
 | **autonumberFormat** | `string` | optional (default: `"{0000}"`) | Auto-number format: literal text + `{0000}` counter, `{YYYY}`/`{MM}`/`{DD}`/`{YYYYMMDD}` date tokens (business tz), and `{field_name}` interpolation. Counter resets per rendered prefix (e.g. AD`{YYYYMMDD}``{0000}` resets daily). Omitted on an `autonumber` field ⇒ the contract default `{0000}`, which every driver and the engine fallback read, so one field numbers alike on every backend. |
 | **externalId** | `boolean` | optional (default: `false`) | Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own `externalId`; an import names it in the mapping's `upsertKey`. |
+| **renamedFrom** | `string[]` | optional | Earlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. `renamedFrom: ['company']` on a field now keyed `account_name`. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only at package upgrade: no record read, write or query reads it, and the type of the old column is judged by the upgrade plan, not here. Declared ahead of the upgrade step that carries the data: until that step ships, no upgrade carries a column on this declaration. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
 
@@ -128,6 +128,7 @@ Add a new field to an existing object
 | **placeholder** | `string` | optional | Placeholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from `inlineHelpText` (always-visible help rendered beside/under the input) and `description` (tooltip/developer documentation). |
 | **autonumberFormat** | `string` | optional (default: `"{0000}"`) | Auto-number format: literal text + `{0000}` counter, `{YYYY}`/`{MM}`/`{DD}`/`{YYYYMMDD}` date tokens (business tz), and `{field_name}` interpolation. Counter resets per rendered prefix (e.g. AD`{YYYYMMDD}``{0000}` resets daily). Omitted on an `autonumber` field ⇒ the contract default `{0000}`, which every driver and the engine fallback read, so one field numbers alike on every backend. |
 | **externalId** | `boolean` | optional (default: `false`) | Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own `externalId`; an import names it in the mapping's `upsertKey`. |
+| **renamedFrom** | `string[]` | optional | Earlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. `renamedFrom: ['company']` on a field now keyed `account_name`. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only at package upgrade: no record read, write or query reads it, and the type of the old column is judged by the upgrade plan, not here. Declared ahead of the upgrade step that carries the data: until that step ships, no upgrade carries a column on this declaration. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -562,6 +563,7 @@ Add a new field to an existing object
 | **placeholder** | `string` | optional | Placeholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from `inlineHelpText` (always-visible help rendered beside/under the input) and `description` (tooltip/developer documentation). |
 | **autonumberFormat** | `string` | optional (default: `"{0000}"`) | Auto-number format: literal text + `{0000}` counter, `{YYYY}`/`{MM}`/`{DD}`/`{YYYYMMDD}` date tokens (business tz), and `{field_name}` interpolation. Counter resets per rendered prefix (e.g. AD`{YYYYMMDD}``{0000}` resets daily). Omitted on an `autonumber` field ⇒ the contract default `{0000}`, which every driver and the engine fallback read, so one field numbers alike on every backend. |
 | **externalId** | `boolean` | optional (default: `false`) | Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own `externalId`; an import names it in the mapping's `upsertKey`. |
+| **renamedFrom** | `string[]` | optional | Earlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. `renamedFrom: ['company']` on a field now keyed `account_name`. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only at package upgrade: no record read, write or query reads it, and the type of the old column is judged by the upgrade plan, not here. Declared ahead of the upgrade step that carries the data: until that step ships, no upgrade carries a column on this declaration. |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
 
@@ -87,6 +87,7 @@ export const FIELD_KEY_STORAGE_CLASS: Readonly<Record<string, FieldKeyClass>> =
   returnType: 'storage',      // the formula's stored/returned type
   summaryOperations: 'storage', // rollup storage
   currencyConfig: 'storage',  // currency mode can change what is physically stored
+  renamedFrom: 'storage',     // the earlier column(s) a package upgrade carries into this one (cloud#3652 ruling D3) — this driver's DDL does not read it yet, and on a builtin column name the platform's own column takes no data from an old one
 
   // ---- presentation: honoured by layers other than the DDL -----------------
   name: 'presentation',       // identity; the physical column is the field KEY (`columnName` was retired, #2377)
 
@@ -636,6 +636,11 @@ export const FIELD_REFERENCE_POSITIONS: Readonly<Record<string, Scrub>> = {
     // A boolean facet of this lookup: it declares the target's name readable
     // by every reader of this record (#29171) and names no field.
     referenceNameVisible: keep,
+    // The earlier keys of THIS field (cloud#3652 ruling D3): names of columns
+    // the field had in earlier package versions. The parse refuses any entry
+    // that is a key another field of the object still declares, so no entry
+    // can name a field a caller is denied — kept, like a boolean facet.
+    renamedFrom: keep,
     // Names of ANOTHER object's fields — that object's projection governs them.
     // `displayField` / `descriptionField` / `lookupColumns` / `lookupFilters`
     // name fields of the `reference` target (the lookup picker reads them);
 
@@ -364,6 +364,8 @@ describe('#17501 — /meta/types serves a real schema for `action`, and moves no
     // lookup fills.
     // [#29171] `field` 81 → 82: `referenceNameVisible`, a lookup's declared
     // name exposure.
+    // [#30880] `field` 82 → 83: `renamedFrom`, the earlier key(s) a package
+    // upgrade carries a field's column from (cloud#3652 ruling D3).
     // [#28022] `app` 22 → 23: `landing`, the per-audience landing list.
     // [#28404] `app` 23 → 24, `dashboard` 20 → 21, `dataset` 16 → 17, `flow`
     // 22 → 23, `page` 26 → 27, `report` 23 → 24: `overrides`, the ADR-0146 D2
@@ -372,7 +374,7 @@ describe('#17501 — /meta/types serves a real schema for `action`, and moves no
     // gain it, and their counts stay.
     // [#28979] `page` 27 → 28: `apps`, the app scope of a record page.
     const CARD_PROPERTY_COUNTS: Record<string, number> = {
-        agent: 24, app: 24, dashboard: 21, dataset: 17, field: 82, flow: 23,
+        agent: 24, app: 24, dashboard: 21, dataset: 17, field: 83, flow: 23,
         hook: 23, object: 49, page: 28, position: 13, report: 24, skill: 16, tool: 14,
     };
 
 
@@ -344,6 +344,7 @@
     "data/Field:relatedListColumns",
     "data/Field:relatedListFilter",
     "data/Field:relatedListTitle",
+    "data/Field:renamedFrom",
     "data/Field:required",
     "data/Field:requiredPermissions",
     "data/Field:requiredWhen",