wip: #4667 schema edits (in flight)

Author: claude

packages/spec/src/system/book.zod.ts

@@ -3,6 +3,7 @@
 import { z } from 'zod';
 import { lazySchema } from '../shared/lazy-schema';
 import { strictObject } from '../shared/strict-object';
+import { retiredKey } from '../shared/retired-key';
 import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
 
 /**
@@ -51,17 +52,44 @@ export const BookIncludeSchema = lazySchema(() =>
 );
 export type BookInclude = string | { tag: string };
 
+/**
+ * Book-level and group-level inline translation maps, retired in 17.0.0
+ * (#4667, ADR-0049).
+ *
+ * The trap here was PROXIMITY, not plausibility. `doc.translations` — two files
+ * over, the same shape, the same name — is read on every path that renders a
+ * doc. So a book's own map reads as the same feature switched on one level up.
+ * It never was: the tree endpoint and the portal render `label` / `description`
+ * verbatim, and the generic bundle translator covers view / action / object /
+ * app / dashboard / page only (`i18n-resolver.ts`). A localized book was parsed,
+ * stored, round-tripped — and rendered in the authoring locale to every reader.
+ *
+ * Shared by both levels deliberately: an author who localized one almost
+ * certainly localized the other, and splitting the wording would make the second
+ * rejection read like a different problem.
+ */
+const BOOK_TRANSLATIONS_RETIRED =
+  'Inline `translations` on a book (and on a book group) was removed in @objectstack/spec '
+  + '17.0.0 (#4667, ADR-0049) — no resolver ever read it. The book tree endpoint and the '
+  + 'docs portal render `label` / `description` verbatim in every locale, so a localized '
+  + 'book shipped its authoring-locale strings to every reader. Delete the key. NOTE the '
+  + 'near neighbour that DOES work: `doc.translations` is live and read on every doc render '
+  + 'path — localize the docs themselves, and the portal picks the reader\'s locale up from '
+  + 'there. Run `os migrate meta --from 16` to rewrite existing sources automatically.';
+
 export const BookGroupSchema = lazySchema(() =>
   z.object({
     key: z
       .string()
       .regex(/^[a-z][a-z0-9_]*$/, 'group key must be lowercase snake_case')
       .describe('Stable group key (used by overrides, deep links, explicit `doc.group`)'),
     label: z.string().describe('Section title — first-class, i18n-homed'),
-    translations: z
-      .record(z.string(), z.object({ label: z.string() }))
-      .optional()
-      .describe('Per-locale label variants'),
+    // TOMBSTONE, not a deletion: `BookGroupSchema` is a plain `z.object` with
+    // no `.strict()`, so a bare delete would have zod silently STRIP the key —
+    // replacing one silent no-op with another. `retiredKey` types it `never`
+    // (a tsc error at the authoring site) and raises the prescription on parse.
+    // Its liveness row therefore STAYS: the key is still in the walked shape.
+    translations: retiredKey(BOOK_TRANSLATIONS_RETIRED),
     order: z.number().optional().describe('Order of THIS group within the book'),
     include: BookIncludeSchema.optional().describe('Rule that derives membership (glob or tag)'),
     package: z
@@ -77,7 +105,6 @@ export const BookGroupSchema = lazySchema(() =>
 export type BookGroup = {
   key: string;
   label: string;
-  translations?: Record<string, { label: string }>;
   order?: number;
   include?: BookInclude;
   package?: string;
@@ -110,7 +137,12 @@ export const BookSchema = lazySchema(() =>
     aliases: {
       title: 'label', sections: 'groups', chapters: 'groups', toc: 'groups',
       access: 'audience', visibility: 'audience', sort: 'order', position: 'order',
-      url: 'slug', path: 'slug', i18n: 'translations',
+      url: 'slug', path: 'slug',
+      // `i18n: 'translations'` retired with the key it pointed at (#4667).
+    },
+    guidance: {
+      translations: BOOK_TRANSLATIONS_RETIRED,
+      i18n: BOOK_TRANSLATIONS_RETIRED,
     },
   }, {
     name: z
@@ -119,9 +151,7 @@ export const BookSchema = lazySchema(() =>
       .describe('Book name (namespace prefix recommended, like every metadata name)'),
     label: z.string().optional().describe('Display title'),
     description: z.string().optional(),
-    translations: z
-      .record(z.string(), z.object({ label: z.string().optional(), description: z.string().optional() }))
-      .optional(),
+    // `translations` removed in 17.0.0 (#4667) — see BOOK_TRANSLATIONS_RETIRED.
     slug: z.string().optional().describe('Portal URL segment; defaults to name sans prefix'),
     icon: z.string().optional(),
     order: z.number().optional().describe('Orders books within the portal'),
@@ -141,7 +171,6 @@ export type Book = {
   name: string;
   label?: string;
   description?: string;
-  translations?: Record<string, { label?: string; description?: string }>;
   slug?: string;
   icon?: string;
   order?: number;

packages/spec/src/system/job.zod.ts

@@ -87,13 +87,33 @@ export type RetryPolicy = z.infer<typeof RetryPolicySchema>;
  *   }
  * }
  */
+/**
+ * `job.id`, retired in 17.0.0 (#4667, ADR-0049).
+ *
+ * The `describe()` did the damage: "defaults to `name` when omitted" implies an
+ * identity OVERRIDE that never existed. Nothing read the key. `name` is the
+ * job's identity at every layer that has one — the scheduling key, the `sys_job`
+ * row key (the DB adapter upserts by `name` and mints its own row id), and the
+ * `JobExecution.jobId` stamp — so two jobs differing only in `id` were never two
+ * jobs, they were one job declared twice, with the second silently winning.
+ */
+const JOB_ID_RETIRED =
+  '`job.id` was removed in @objectstack/spec 17.0.0 (#4667, ADR-0049) — nothing ever read '
+  + 'it, and its own description ("defaults to `name` when omitted") advertised an identity '
+  + 'override that did not exist. `name` IS the job\'s identity everywhere: the scheduling '
+  + 'key, the `sys_job` row key, and the `JobExecution.jobId` stamp. Two jobs differing only '
+  + 'in `id` were the same job. Delete the key; rename the job via `name` if you need a '
+  + 'different identity. Run `os migrate meta --from 16` to rewrite existing sources '
+  + 'automatically.';
+
 export const JobSchema = lazySchema(() => strictObject({
   surface: 'this job',
   history:
     'Until #4001 closed this shape these were dropped silently — the item still registered, minus whatever the key was meant to configure.',
   aliases: { cron: 'schedule', interval: 'schedule', fn: 'handler', function: 'handler', retry: 'retryPolicy', enabled_: 'enabled', timeoutMs: 'timeout' },
+  guidance: { id: JOB_ID_RETIRED },
 }, {
-  id: z.string().optional().describe('Unique job identifier (defaults to `name` when omitted)'),
+  // `id` removed in 17.0.0 (#4667) — see JOB_ID_RETIRED. `name` is the identity.
   name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Job name (snake_case)'),
   label: z.string().optional().describe('Human-readable label'),
   description: z.string().optional().describe('Job description / purpose'),

packages/spec/src/system/translation.zod.ts

@@ -281,14 +281,35 @@ export type LegacyObjectFirstKey = (typeof LEGACY_OBJECT_FIRST_KEYS)[number];
  * when the two carry different inner shapes and the content has to be rewritten,
  * not renamed.
  */
-const TRANSLATION_KEY_GUIDANCE: Record<LegacyObjectFirstKey, string> = {
+const TRANSLATION_KEY_GUIDANCE: Record<LegacyObjectFirstKey | 'validationMessages', string> = {
+  // Not a legacy object-first key — a group that was live-looking and unread
+  // until 17.0.0 (#4667, ADR-0049). The platform's own signature was on it
+  // twice: the schema example showed a concrete override
+  // ({"discount_limit": "折扣不能超过40%"}), and #3778's migration table steered
+  // retired `errors:` authors straight into it. Both signposts pointed at a
+  // group no resolver read — objectui's spec-translations transform passed it
+  // through to the client tree and nothing downstream consumed it.
+  validationMessages:
+    '`validationMessages` was removed in @objectstack/spec 17.0.0 (#4667, ADR-0049) — no '
+    + 'resolver ever read it, so a translated rule message was stored and never shown. '
+    + 'Validation messages are not translated through a translation group: author the '
+    + 'message on the rule itself (`object.validations[].message`), which the engine '
+    + 'evaluates and returns on every rejected write. Delete the key. Run '
+    + '`os migrate meta --from 16` to rewrite existing sources automatically.',
   o: "`o` is the retired object-first dialect, which no resolver reads — use 'objects.<object_name>'",
   app: "`app` is the retired object-first dialect, which no resolver reads — use 'apps.<app_name>'",
   nav: "`nav` is the retired object-first dialect, which no resolver reads — use 'apps.<app_name>.navigation.<node_id>.label'",
   dashboard: "`dashboard` is the retired object-first dialect, which no resolver reads — use 'dashboards.<dashboard_name>' (plural)",
   reports: '`reports` is the retired object-first dialect — reports have no translation group, omit them',
   notifications: '`notifications` is the retired object-first dialect — notifications have no translation group, omit them',
-  errors: "`errors` is the retired object-first dialect — use 'validationMessages' for rule messages; other errors have no translation group",
+  // Was: "use 'validationMessages' for rule messages". That was a signpost to a
+  // key with no reader — #3778 retired `errors` by pointing authors at
+  // `validationMessages`, which was itself dead, so taking the advice moved the
+  // content from one unread group to another. Both are gone now (#4667).
+  errors:
+    '`errors` is the retired object-first dialect and has no replacement — rule messages are '
+    + 'not translated through a translation group at all. Author the message on the rule '
+    + "itself (`object.validations[].message`); omit `errors`.",
   _globalOptions: "`_globalOptions` is the retired object-first dialect — use 'objects.<object_name>.fields.<field_name>.options'",
   _meta: "`_meta` is the retired object-first dialect — use the top-level 'locale' field (on a bundle, the locale is the map key)",
   namespace: '`namespace` is not part of the translation contract — omit it (ADR-0006 D4 retired namespaces platform-wide)',
@@ -352,8 +373,10 @@ const translationDataShape = () => ({
   /** UI Messages */
   messages: z.record(z.string(), z.string()).optional().describe('UI message translations keyed by message ID'),
 
-  /** Validation Error Messages */
-  validationMessages: z.record(z.string(), z.string()).optional().describe('Translatable validation error messages keyed by rule name (e.g., {"discount_limit": "折扣不能超过40%"})'),
+  // `validationMessages` removed in 17.0.0 (#4667) — see the
+  // TRANSLATION_KEY_GUIDANCE entry. Removing it from this shared shape retires
+  // it at BOTH doors at once (bundle entry + registered item), which is the
+  // asymmetry #3778's item-only guard got wrong.
 
   /**
    * Global (object-less) action translations keyed by action name (snake_case).

packages/spec/src/ui/app.zod.ts

@@ -632,8 +632,8 @@ export const NavigationAreaSchema = lazySchema(() => z.object({
   /** Icon name (Lucide) */
   icon: z.string().optional().describe('Area icon name'),
 
-  /** Sort order among areas (lower = first) */
-  order: z.number().optional().describe('Sort order among areas (lower = first)'),
+  // `order` removed in 17.0.0 (#4667) — see AREA_ORDER_RETIRED. Reorder the
+  // `areas` array instead; declaration order is display order.
 
   /** Area description */
   description: I18nLabelSchema.optional().describe('Area description'),
@@ -652,8 +652,10 @@ export const NavigationAreaSchema = lazySchema(() => z.object({
 }, {
   error: strictUnknownKeyError({
     surface: 'this navigation area',
-    knownKeys: ['id', 'label', 'icon', 'order', 'description', 'visible', 'requiredPermissions', 'navigation'],
-    aliases: { visiblewhen: 'visible', visibleon: 'visible', title: 'label', name: 'id', sort: 'order', permissions: 'requiredPermissions', items: 'navigation', children: 'navigation' },
+    knownKeys: ['id', 'label', 'icon', 'description', 'visible', 'requiredPermissions', 'navigation'],
+    // `sort: 'order'` retired with the key it pointed at (#4667).
+    aliases: { visiblewhen: 'visible', visibleon: 'visible', title: 'label', name: 'id', permissions: 'requiredPermissions', items: 'navigation', children: 'navigation' },
+    guidance: { order: AREA_ORDER_RETIRED, sort: AREA_ORDER_RETIRED },
     history:
       'Until #4001 these were dropped silently — the area still parsed, so its gating or ' +
       'ordering was quietly ignored.',
@@ -888,6 +890,41 @@ const APP_KEYS = [
   'version', 'aria', 'objects', 'apis', 'sharing', 'embed', 'mobileNavigation',
 ] as const;
 
+/**
+ * `app.homePageId`, retired in 17.0.0 (#4667, ADR-0049).
+ *
+ * The schema's own hedge gave it away — "if not set, usually defaults to the
+ * first navigation item" describes the ONLY behaviour that exists. No shell
+ * reads the key: an app's landing page is its first navigation item in `order`,
+ * and the ROOT landing follows `isDefault` routing (objectui's
+ * `RootLandingRedirect`). So an author pinning a home page got the first nav
+ * item anyway, and "usually" was doing the work of "always".
+ */
+const HOME_PAGE_ID_RETIRED =
+  '`app.homePageId` was removed in @objectstack/spec 17.0.0 (#4667, ADR-0049) — no shell '
+  + 'ever read it. An app\'s landing page IS its first navigation item (by `order`), and the '
+  + 'root landing follows `isDefault` routing. Delete the key; to change where an app opens, '
+  + 'reorder `navigation` so the intended entry is first, and set `isDefault` on the app that '
+  + 'should own the root landing. Run `os migrate meta --from 16` to rewrite existing sources '
+  + 'automatically.';
+
+/**
+ * `app.areas[].order`, retired in 17.0.0 (#4667, ADR-0049).
+ *
+ * The sibling that works is what made this one read alive: nav-item `order` IS
+ * sorted (`NavigationRenderer.tsx:1154`). Area-level order is not — `AppSidebar`
+ * and `AppSchemaRenderer` both iterate the `areas` array as authored — so
+ * declaration order has always been display order, and an author who set
+ * `order` to rearrange areas saw nothing move.
+ */
+const AREA_ORDER_RETIRED =
+  '`areas[].order` was removed in @objectstack/spec 17.0.0 (#4667, ADR-0049) — no renderer '
+  + 'ever sorted areas; both the sidebar and the schema renderer iterate the array as '
+  + 'authored, so declaration order already IS display order. Delete the key and reorder the '
+  + '`areas` array itself. NOTE the neighbour that behaves differently: a navigation ITEM\'s '
+  + '`order` is genuinely sorted — this removal does not touch it. Run '
+  + '`os migrate meta --from 16` to rewrite existing sources automatically.';
+
 const appUnknownKeyError = strictUnknownKeyError({
   surface: 'this app',
   knownKeys: APP_KEYS,
@@ -902,9 +939,9 @@ const appUnknownKeyError = strictUnknownKeyError({
     sections: 'areas',
     groups: 'areas',
     permissions: 'requiredPermissions',
-    home: 'homePageId',
-    homepage: 'homePageId',
-    landingpage: 'homePageId',
+    // `home` / `homepage` / `landingpage` aliased `homePageId`, retired in
+    // 17.0.0 (#4667). They fall through to the tombstone's own prescription
+    // rather than renaming onto a key that no longer exists.
     agent: 'defaultAgent',
     logo: 'branding',
     theme: 'branding',
@@ -922,6 +959,11 @@ const appUnknownKeyError = strictUnknownKeyError({
     flows:
       '`flows` is not an App field — flows are top-level stack metadata ' +
       '(`defineStack({ flows })`), not app-scoped.',
+    // The three retired `homePageId` aliases. `retiredKey` already answers the
+    // canonical spelling; these cover the spellings that used to route to it.
+    home: HOME_PAGE_ID_RETIRED,
+    homepage: HOME_PAGE_ID_RETIRED,
+    landingpage: HOME_PAGE_ID_RETIRED,
   },
   history:
     'Until #4001 these were dropped silently — the app still parsed, so navigation or ' +
@@ -1014,12 +1056,13 @@ export const AppSchema = lazySchema(() => z.object({
   contextSelectors: z.array(AppContextSelectorSchema).optional()
     .describe('App-level scope dropdowns whose value is injected into nav items as {<id>} template vars'),
 
-  /** 
-   * App-level Home Page Override
-   * ID of the navigation item to act as the landing page.
-   * If not set, usually defaults to the first navigation item.
+  /**
+   * REMOVED in 17.0.0 (#4667) — see {@link HOME_PAGE_ID_RETIRED}. Tombstoned
+   * rather than deleted, matching the seven #4142 retirements on this schema:
+   * `retiredKey` types it `never`, so an app still authoring it fails to
+   * compile as well as to parse.
    */
-  homePageId: z.string().optional().describe('ID of the navigation item to serve as landing page'),
+  homePageId: retiredKey(HOME_PAGE_ID_RETIRED),
 
   /** 
    * Access Control