docs(spec): four conversion summaries state their decision in words instead of a deleted tracker number (stage 9)

.changeset/spec-conversion-summaries-decision-in-words.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': patch
+---
+
+Four conversion summaries now state their decision in words instead of citing a tracker number
+
+Clause-②: no
+
+The `summary` of four ADR-0087 conversions (`datasource-driver-mongo-to-mongodb`,
+`translation-component-submit-label-removed`, `mapping-lookup-params-removed` and
+`connector-error-mapping-removed`) cited a GitHub issue that no longer exists. That
+text is what `os migrate meta`, `spec-changes.json` and the protocol upgrade guide show
+an author, so each now says what was decided and why: one driver id for driver and
+config contract, retire rather than re-anchor `submitLabel`, remove rather than
+implement the import lookup params, and delete `errorMapping` to end its `userMessage`
+collision without a rename. Wording only: no conversion id, surface, retirement state,
+transform, schema, export or runtime behaviour changes.

docs/protocol-upgrade-guide.md

@@ -185,7 +185,7 @@ Finally it removes the 'pdf' member of `view.exportOptions` formats (#8010, main
 | `job-id-removed` | `job.id` | job key 'id' removed (#4667 — nothing read it; `name` is the job's identity everywhere, so two jobs differing only in `id` were the same job, and the key's own description advertised an override that did not exist) | retired — `migrate meta` only |
 | `translation-validation-messages-removed` | `translation.validationMessages` | translation key 'validationMessages' removed (#4667 — no resolver read it, so a translated rule message was stored and never shown; #3778's migration table had been steering retired `errors:` authors into it). Author the message on the rule itself (`object.validations[].message`), and translate it under the object-scoped group `objects.<object_name>._validations.<rule_name>.message`, which the write path resolves (17.3.0, #14381) | retired — `migrate meta` only |
 | `datasource-config-driver-key-aliases` | `datasource.config` | datasource config keys → canonical per driver: sqlite 'file'/'database' → 'filename', postgres/mysql 'connectionString' → 'url' and 'user' → 'username', mongo 'uri' → 'url' and 'user' → 'username' (#4456 — driver-factory `??` fallback graduation) | retired — `migrate meta` only |
-| `datasource-driver-mongo-to-mongodb` | `datasource.driver` | datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver package and the published DRIVER_CATALOG already used (#6345) | live — protocol 17 loader accepts the old shape |
+| `datasource-driver-mongo-to-mongodb` | `datasource.driver` | datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver package and the published DRIVER_CATALOG already used, so the id that selects a driver and the id that selects its config contract are one string with no mapping between them | live — protocol 17 loader accepts the old shape |
 | `flow-node-script-branch-keys-removed` | `flow.node.script.config.actionType / flow.node.script.config.template / flow.node.script.config.recipients / flow.node.script.config.variables / flow.node.script.config.script` | script flow-node config keys 'actionType' (→ 'function' when it was shorthand for one; otherwise removed — 'email'/'slack' were logger-backed stubs that delivered nothing), plus 'template' / 'recipients' / 'variables' (fed those stubs) and 'script' (inline JS the runtime never executed) (#4343) | retired — `migrate meta` only |
 | `retry-policy-converged` | `flow.errorHandling.retryDelayMs / flow.node.config.retry.retryDelayMs / job.retryPolicy.maxRetries / job.retryPolicy.backoffMultiplier` | retry policy unified across job.retryPolicy, try_catch retry and flow.errorHandling: base delay 'retryDelayMs' → 'backoffMs', and the pre-17 job defaults (maxRetries 3, backoffMultiplier 2) written out explicitly now that the merged default is 0 / 1 (#4661, #4964) | live — protocol 17 loader accepts the old shape |
 | `object-managed-by-system-to-system-data` | `object.managedBy` | object managedBy 'system' → 'system-data' (#3355 — ADR-0103's residual bucket named the engine-owned half v16 had already moved out to `engine-owned`; the rename leaves the name describing what the bucket actually holds: admin/user-writable platform data) | retired — `migrate meta` only |

packages/spec/spec-changes.json

@@ -226,7 +226,7 @@
       },
       {
         "surface": "datasource.driver",
-        "to": "datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver package and the published DRIVER_CATALOG already used (#6345)",
+        "to": "datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver package and the published DRIVER_CATALOG already used, so the id that selects a driver and the id that selects its config contract are one string with no mapping between them",
         "conversionId": "datasource-driver-mongo-to-mongodb",
         "toMajor": 17
       },
@@ -1118,7 +1118,7 @@
         },
         {
           "surface": "datasource.driver",
-          "to": "datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver package and the published DRIVER_CATALOG already used (#6345)",
+          "to": "datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver package and the published DRIVER_CATALOG already used, so the id that selects a driver and the id that selects its config contract are one string with no mapping between them",
           "conversionId": "datasource-driver-mongo-to-mongodb",
           "toMajor": 17
         },

packages/spec/src/conversions/registry.ts

@@ -2097,7 +2097,8 @@ const toolInertAuthoringKeysRemoved: MetadataConversion = {
  * entry: `retiredFromLoadPath` still holds nothing back at three runtime seams
  * (ADR-0087's 2026-09-13 addendum names all three). Before setting that flag on a DEFAULT FLIP — as opposed to a
  * lossless delete or a rename — read that addendum, because the flag does not mean
- * what its name and every docblock around it say it means.
+ * what its name says: its own docblock (`RetiredConversionState` in `types.ts`) has
+ * stated the authoring-only reach since commit 29dd1a6dd.
  */
 
 /**
@@ -3525,7 +3526,8 @@ const datasourceDriverMongoToMongodb: MetadataConversion = {
   surface: 'datasource.driver',
   summary:
     "datasource driver id 'mongo' → 'mongodb' — the canonical id both boot hosts, the driver "
-    + 'package and the published DRIVER_CATALOG already used (#6345)',
+    + 'package and the published DRIVER_CATALOG already used, so the id that selects a driver '
+    + 'and the id that selects its config contract are one string with no mapping between them',
   apply(stack, emit) {
     return mapDatasources(stack, (ds, path) => {
       // Only the exact legacy canon, trimmed and lower-cased the same way
@@ -7367,10 +7369,11 @@ const translationComponentSubmitLabelRemoved: MetadataConversion = {
   retiredAfter: '17.2.0',
   surface: 'translation.pages.components.submitLabel',
   summary:
-    "translation component-copy key 'submitLabel' removed (#10926 — its only declared carrier, "
-    + "'element:form', retired whole in #9249, so the resolver no longer overlays it and a stored "
-    + "string was read by nothing; the live form surface's submit copy is 'object-form''s "
-    + "'submitText', localized at its own authoring site)",
+    "translation component-copy key 'submitLabel' removed (retired rather than re-anchored — its "
+    + "only declared carrier, 'element:form', retired whole in #9249, so the resolver no longer "
+    + "overlays it and a stored string was read by nothing; the live form surface's submit copy "
+    + "is 'object-form''s 'submitText', localized at its own authoring site, and re-anchoring the "
+    + 'key there would only have added a second place to translate one word)',
   apply(stack, emit) {
     const stripFromData = (data: Record<string, unknown>, path: string): Record<string, unknown> => {
       const pages = data.pages;
@@ -8278,10 +8281,11 @@ const mappingLookupParamsRemoved: MetadataConversion = {
   retiredAfter: '17.2.0',
   surface: 'mapping.fieldMapping[].params.object / .fromField / .toField / .autoCreate',
   summary:
-    "mapping lookup params 'object'/'fromField'/'toField'/'autoCreate' removed (#10329, "
-    + 'ADR-0049 — the import path never read them: `lookup` copies the cell through and '
+    "mapping lookup params 'object'/'fromField'/'toField'/'autoCreate' removed (ADR-0049 — "
+    + 'the import path never read them: `lookup` copies the cell through and '
     + "reference resolution runs off the target field's own metadata. `autoCreate` never "
-    + 'created anything — an unresolved reference fails the row either way)',
+    + 'created anything — an unresolved reference fails the row either way. Implementing them '
+    + 'instead would have added a second reference-resolution dialect to the import path)',
   apply(stack, emit) {
     const RETIRED = ['object', 'fromField', 'toField', 'autoCreate'];
     return mapCollection(stack, 'mappings', (m, path) => {
@@ -9287,9 +9291,10 @@ const connectorErrorMappingRemoved: MetadataConversion = {
   retiredAfter: '17.3.0',
   surface: 'connector.errorMapping',
   summary:
-    "connector key 'errorMapping' removed (#14676, ADR-0049 — no engine ever mapped an external "
+    "connector key 'errorMapping' removed (ADR-0049 — no engine ever mapped an external "
     + 'error through the rules, so the eleven nested keys configured nothing, and the rule-level '
-    + '`userMessage` shared its spelling with the live API-error channel while never being shown. '
+    + '`userMessage` shared its spelling with the live API-error channel while never being shown; '
+    + 'deleting the block resolves that collision without a rename. '
     + 'The whole ErrorMappingConfig / ErrorMappingRule shape and the ConnectorErrorCategory enum '
     + 'went with it)',
   apply(stack, emit) {