|
| 1 | +--- |
| 2 | +'@objectstack/spec': major |
| 3 | +'@objectstack/example-todo': patch |
| 4 | +--- |
| 5 | + |
| 6 | +feat(spec)!: retire the six remaining `authorWarn` dead keys — book/group `translations`, `job.id`, `translation.validationMessages`, `app.homePageId`, `app.areas[].order` (#4667) |
| 7 | + |
| 8 | +The #4488 liveness audit marked as `authorWarn` the keys whose *declaration* |
| 9 | +actively misleads — not merely unread, but shaped so an author reasonably |
| 10 | +concludes they configure something. #4509 and #4583 cleared the rest; these six |
| 11 | +are what remained, and each shipped with its own reason for reading alive. |
| 12 | + |
| 13 | +**The retirement kit:** |
| 14 | + |
| 15 | +| FROM | TO | Fix | |
| 16 | +|---|---|---| |
| 17 | +| `book.translations` | *(removed)* | Delete the key. Localize the **docs** — `doc.translations` is live on every doc render path. | |
| 18 | +| `book.groups[].translations` | *(removed)* | Same. Tombstoned, since `BookGroupSchema` is not `.strict()`. | |
| 19 | +| `job.id` | *(removed)* | Delete the key. `name` is the job's identity everywhere. | |
| 20 | +| `translation.validationMessages` | *(removed)* | Delete the key. Author the message on the rule: `object.validations[].message`. | |
| 21 | +| `app.homePageId` | *(removed)* | Delete the key. Reorder `navigation`; set `isDefault` for the root landing. | |
| 22 | +| `app.areas[].order` | *(removed)* | Delete the key. Reorder the `areas` array itself. | |
| 23 | + |
| 24 | +Run `os migrate meta --from 16` to rewrite existing sources automatically. |
| 25 | + |
| 26 | +**Each read alive for a different reason, and the prescriptions say which:** |
| 27 | + |
| 28 | +- **book `translations`** — *proximity*. `doc.translations`, two files over, same |
| 29 | + name and shape, works on every read path. The book-level map was parsed, |
| 30 | + stored and round-tripped, and rendered in the authoring locale to every |
| 31 | + reader: the tree endpoint and the portal emit `label` / `description` |
| 32 | + verbatim. |
| 33 | +- **`job.id`** — *its own description*. "Defaults to `name` when omitted" |
| 34 | + advertises an identity override that does not exist. `name` is the scheduling |
| 35 | + key, the `sys_job` row key, and the `JobExecution.jobId` stamp — so two jobs |
| 36 | + differing only in `id` were one job declared twice. |
| 37 | +- **`translation.validationMessages`** — *the platform's own signposts, twice*. |
| 38 | + The schema example showed a concrete override, and #3778's legacy-key |
| 39 | + migration table steered retired `errors:` authors straight into it. **That |
| 40 | + guidance entry is rewritten here**: retiring one dead key by pointing at |
| 41 | + another is the defect, not the fix. |
| 42 | +- **`app.homePageId`** — *its own hedge*. "If not set, usually defaults to the |
| 43 | + first navigation item" described the only behaviour there was. |
| 44 | +- **`app.areas[].order`** — *the sibling that works*. Nav-item `order` really is |
| 45 | + sorted; area-level order never was, and both renderers iterate the array as |
| 46 | + authored. |
| 47 | + |
| 48 | +**Routes differ, deliberately.** `book.groups[].translations` and |
| 49 | +`app.homePageId` are **tombstoned** (`retiredKey`: `never` at compile time, a |
| 50 | +prescription at parse time) — the group schema is a plain `z.object`, where a |
| 51 | +bare delete would have zod silently strip the key, trading one silent no-op for |
| 52 | +another. The other four are strict deletions carrying `guidance`. Retired alias |
| 53 | +spellings (`i18n`, `home`, `homepage`, `landingpage`, `sort`) route to the same |
| 54 | +prescriptions rather than renaming onto keys that are gone. |
| 55 | + |
| 56 | +Registered as three ADR-0087 D2 conversions (`book-translations-removed`, |
| 57 | +`job-id-removed`, `translation-validation-messages-removed`) plus an extension |
| 58 | +of `app-dead-authoring-keys-removed`, all wired into the protocol-17 D3 chain. |
| 59 | + |
| 60 | +**Also corrected, both found by the gates rather than by grep:** the published |
| 61 | +`objectstack-i18n` skill taught `validationMessages` in a copy-paste example |
| 62 | +(an AI reproduces that verbatim), and `examples/app-todo` authored the group in |
| 63 | +three locales — where the `en` entries merely duplicated the rule's own text and |
| 64 | +the zh-CN / ja-JP translations had never once been rendered. |
| 65 | + |
| 66 | +After this, the only `authorWarn` keys left in the ledger are the two fail-open |
| 67 | +area gates tracked in #4651, which need a decision rather than a patch. |
0 commit comments