|
| 1 | +--- |
| 2 | +"@objectstack/spec": minor |
| 3 | +--- |
| 4 | + |
| 5 | +feat(spec): retire `connector.errorMapping` — eleven authorable keys nothing ever read, one of them spelled like the live `userMessage` channel (#14676, ADR-0049) |
| 6 | + |
| 7 | +<!-- adr-0087: registered connector-error-mapping-removed --> |
| 8 | + |
| 9 | +**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep |
| 10 | +launch-window convention ships it as `minor`; the migration prescription is |
| 11 | +registered under protocol major 18, where `os migrate meta` users will look). |
| 12 | +Triage ruling 2026-09-02 on the census card: ADR-0049 enforce-or-remove decides |
| 13 | +it — declared-but-unenforced authorable surface with zero measured pull for a |
| 14 | +reader comes off. |
| 15 | + |
| 16 | +`ConnectorSchema.errorMapping` carried `ErrorMappingConfig` (`rules`, |
| 17 | +`defaultCategory`, `unmappedBehavior`, `logUnmapped`) and its |
| 18 | +`ErrorMappingRule[]` (`sourceCode`, `sourceMessage`, `targetCode`, |
| 19 | +`targetCategory`, `severity`, `retryable`, `userMessage`) — eleven keys on the |
| 20 | +published authorable surface that **nothing read**: measured on `origin/main`, |
| 21 | +the only reference outside the declaring file and its unit test was a |
| 22 | +type-identity pin. No provider, dispatcher or materializer ever mapped an |
| 23 | +external error through the rules, so `unmappedBehavior` configured nothing and |
| 24 | +a rule's `userMessage` was never shown to anyone. That spelling is what made |
| 25 | +this worse than ordinary dead surface: it is the name of the **live** |
| 26 | +API-error channel (`ApiError.userMessage`, the user-facing refusal text a |
| 27 | +thrown HTTP error declares), so an author who had read that documentation and |
| 28 | +wrote a connector rule reasonably believed they were marking a refusal for an |
| 29 | +end user — and the failure was silent in both directions (it validated, it |
| 30 | +published, no message was ever shown). Removal resolves the collision by |
| 31 | +deletion; the live channel is untouched. |
| 32 | + |
| 33 | +**What is refused:** authoring `errorMapping` on a connector, with any value. |
| 34 | +`ConnectorSchema` is a non-strict `z.object`, so the key is a `retiredKey()` |
| 35 | +tombstone rather than a bare deletion (a deletion would have stripped it in |
| 36 | +silence): authoring it is a `tsc` error (`never`) and a parse error carrying |
| 37 | +the prescription, on the base schema and — through |
| 38 | +`DeclarativeConnectorEntrySchema`, which `superRefine`s the same shape — on |
| 39 | +`stack.connectors[]` and the `PUT /api/v1/meta/connector/:name` door. |
| 40 | + |
| 41 | +**What leaves the public surface:** `ErrorMappingConfigSchema` / |
| 42 | +`ErrorMappingConfig` / `ErrorMappingConfigParsed`, `ErrorMappingRuleSchema` / |
| 43 | +`ErrorMappingRule`, and `ConnectorErrorCategorySchema` / `ConnectorErrorCategory` |
| 44 | +(the enum's only consumers were the two removed shapes; an exported value |
| 45 | +schema with no consumer reads as a capability). `api/ErrorCategory` — the |
| 46 | +HTTP-response vocabulary — is unaffected. |
| 47 | + |
| 48 | +**What stays, byte-identical:** every other connector key (`health`, `retry`, |
| 49 | +`webhooks`, `fieldMappings`, `syncConfig`, `actions`, `triggers`, `provider`, |
| 50 | +`providerConfig`, `auth`, …) with its default and its readers. |
| 51 | + |
| 52 | +## FROM → TO |
| 53 | + |
| 54 | +```ts |
| 55 | +// before — parsed green; nothing ever read the block, no message was ever shown |
| 56 | +defineStack({ |
| 57 | + connectors: [{ |
| 58 | + name: 'payments_api', |
| 59 | + label: 'Payments API', |
| 60 | + type: 'api', |
| 61 | + errorMapping: { |
| 62 | + rules: [{ |
| 63 | + sourceCode: 429, |
| 64 | + targetCode: 'RATE_LIMITED', |
| 65 | + targetCategory: 'rate_limit', |
| 66 | + severity: 'medium', |
| 67 | + retryable: true, |
| 68 | + userMessage: 'The payment provider is busy; try again shortly.', |
| 69 | + }], |
| 70 | + unmappedBehavior: 'generic_error', |
| 71 | + }, |
| 72 | + }], |
| 73 | +}); |
| 74 | + |
| 75 | +// after — delete the key; there is no replacement because no error-mapping |
| 76 | +// engine exists: a connector's failures reach callers as the provider's own |
| 77 | +// errors (ADR-0097). A user-facing refusal text is the API error envelope's |
| 78 | +// `userMessage`, declared by the code that throws — not connector metadata. |
| 79 | +defineStack({ |
| 80 | + connectors: [{ name: 'payments_api', label: 'Payments API', type: 'api' }], |
| 81 | +}); |
| 82 | +``` |
| 83 | + |
| 84 | +One-line fix: delete the `errorMapping` block; `os migrate meta --from 17` |
| 85 | +lists the mechanical edits for existing sources. |
| 86 | + |
| 87 | +The retirement kit: |
| 88 | + |
| 89 | +- `retiredKey()` tombstone on `ConnectorSchema.errorMapping` |
| 90 | + (`packages/spec/src/integration/connector.zod.ts`; the section comment |
| 91 | + records what the shape was), inherited by `DeclarativeConnectorEntrySchema` |
| 92 | +- ADR-0087 registration: `integration/Connector:errorMapping` and |
| 93 | + `integration/DeclarativeConnectorEntry:errorMapping` in |
| 94 | + `RETIRED_KEYS_BY_MAJOR[18]`; `integration/ErrorMappingConfig`, |
| 95 | + `integration/ErrorMappingRule`, `integration/ConnectorErrorCategory` in |
| 96 | + `RETIRED_DEFS_BY_MAJOR[18]`; the D2 conversion |
| 97 | + `connector-error-mapping-removed` (protocol 18) wired into the step-18 chain |
| 98 | + — a pure lossless strip of the block from every `connectors[]` entry, one |
| 99 | + notice per connector (the eleven nested keys leave with the block) |
| 100 | +- no liveness-ledger row: `connector` is not an enrolled ledger type, so |
| 101 | + there is no row to keep or drop |
| 102 | +- pin tests (`connector.test.ts`): refusal pins asserting the issue path, |
| 103 | + code and prescription on the base schema, the declarative entry, and the |
| 104 | + `stack.connectors[]` authoring path; the tsc `never` channel; a |
| 105 | + no-materialize pin; the conversion's strip and notice; zero holders of the |
| 106 | + seven retired names on every public entry; the ADR-0087 registration |
| 107 | +- generated baselines/docs follow the schema (`authorable-surface/`, |
| 108 | + `authorable-defaults/`, `api-surface/`, `json-schema.manifest/`, |
| 109 | + `declaration-map/`, `export-origins/`, spec-changes, upgrade guide, |
| 110 | + reference docs) |
| 111 | +- zero authored occurrences in this repo's examples, skills and docs, and |
| 112 | + zero hits in objectui at `0d8fd7c`, so no in-repo source changes ride along |
0 commit comments