From c28ed069167b7cbae393080fc1522f9641f548a8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 19:54:13 +0000 Subject: [PATCH 1/3] docs(spec): state the decision in words in four conversion summaries that cited deleted tracker numbers (stage 9) Ruling C+D form D: a conversion `summary` is author-shown (`os migrate meta`, spec-changes.json, the protocol upgrade guide), so it carries the lesson, not a number to look up. The four numbers removed answer 404 on the board; the lit reference in the submitLabel summary stays. No id, surface, verdict or code token moves. The comment clause at the withdrawn field-required-notnull-explicit entry said every docblock around retiredFromLoadPath misstates it; the flag's own docblock has stated the authoring-only reach since commit 29dd1a6dd, so the clause now says that. Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude --- packages/spec/src/conversions/registry.ts | 27 ++++++++++++++--------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/packages/spec/src/conversions/registry.ts b/packages/spec/src/conversions/registry.ts index 61f7a794dd6..0ef18fdf23f 100644 --- a/packages/spec/src/conversions/registry.ts +++ b/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, path: string): Record => { 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) { From f01ca644bc0cea18361240de43f2a0d90f4d617c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 19:55:13 +0000 Subject: [PATCH 2/3] chore(spec): regenerate spec-changes.json and the protocol upgrade guide for the reworded mongo conversion summary Generated by gen:spec-changes and gen:upgrade-guide; only the one summary's copy moves (two JSON lines, one guide table row). Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude --- docs/protocol-upgrade-guide.md | 2 +- packages/spec/spec-changes.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/protocol-upgrade-guide.md b/docs/protocol-upgrade-guide.md index a05b4d89000..6ff61392cf7 100644 --- a/docs/protocol-upgrade-guide.md +++ b/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.._validations..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 | diff --git a/packages/spec/spec-changes.json b/packages/spec/spec-changes.json index efb9b39c90e..de0f260d18a 100644 --- a/packages/spec/spec-changes.json +++ b/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 }, From 31a296909f3b69407d21c9daf3c6bd73a534b80e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 29 Sep 2026 19:55:14 +0000 Subject: [PATCH 3/3] chore(changeset): patch for the four reworded conversion summaries Claude-Session: https://claude.ai/code/session_014EJ1ED8X4MMrT18BhVx4tx Co-authored-by: Claude --- ...ec-conversion-summaries-decision-in-words.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .changeset/spec-conversion-summaries-decision-in-words.md diff --git a/.changeset/spec-conversion-summaries-decision-in-words.md b/.changeset/spec-conversion-summaries-decision-in-words.md new file mode 100644 index 00000000000..d0c7ce3e86b --- /dev/null +++ b/.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.