Merge origin/main into issue-3355 managedBy retirement

Two conflicts, both in the protocol 17 narrative where concurrent
retirement PRs each appended a paragraph:

- packages/spec/src/migrations/registry.ts — #4509 (unwarnable mapping /
  contextSelector keys) landed on main with a "Finally, ..." paragraph
  while this branch had one of its own. Both retirements are real and
  both belong in the v17 story, so both paragraphs are kept: the
  managedBy rename reworded to "Separately, ..." and placed first, with
  #4509 keeping the closing position. No content dropped from either
  side. conversionIds merged cleanly and carries both sets.

- docs/protocol-upgrade-guide.md — generated from the registry above, so
  it was regenerated rather than hand-reconciled.

Verified after the merge: 69/69 turbo test+typecheck tasks across the 8
affected packages, and all 17 spec check gates.

Author: claude

.changeset/doc-tags-connects-book-tag-include.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): declare `doc.tags`, so a book group's `include: { tag }` can finally match something (#4509)
+
+`BookGroup.include` has always accepted two shapes — a glob over doc names, or
+`{ tag: '<t>' }`. The tag variant could never match a single doc in any stack,
+and not because the matcher was missing. Everything downstream already existed:
+
+- `matchesInclude` compares `doc.tags` against the rule (`book.zod.ts`)
+- the book route already forwards `tags: d.tags` into the resolver (`rest-server.ts`)
+- `ResolverDoc` already declares `tags?: string[]` — annotated `(P3d; absent today)`
+
+The gap was one line at the *authoring* end: `DocSchema` is `.strict()` and had
+no `tags` key, so writing `tags:` on a doc was a parse error. Every doc therefore
+reached the resolver with `tags === undefined`, and the variant matched nothing,
+forever.
+
+This is the enforce half of ADR-0049 enforce-or-remove. Removal was the
+alternative and was rejected on two grounds: a union member has no clean
+tombstone (`retiredKey` covers object keys), so authors would have received a
+bare union error carrying no prescription — and it would have discarded a
+working matcher to fix a declaration.
+
+```ts
+defineDoc({ name: 'crm_guide_lead', content: '# Leads', tags: ['tutorial'] })
+defineBook({ name: 'crm', groups: [{ key: 'tut', label: 'Tutorials', include: { tag: 'tutorial' } }] })
+```
+
+Prefer a name convention (`include: 'crm_guide_*'`) where one exists — tags earn
+their place when membership cuts *across* naming, e.g. a `tutorial` tag spanning
+several feature prefixes, which no glob can collect.
+
+Additive: `DocSchema` previously rejected `tags`, so nothing that parsed before
+parses differently now.

.changeset/mapping-context-selector-unwarnable-keys-retired.md

@@ -0,0 +1,63 @@
+---
+'@objectstack/spec': major
+'@objectstack/platform-objects': patch
+---
+
+feat(spec)!: retire the five keys the advisory lint could never have warned about — mapping `extractQuery`/`errorPolicy`/`batchSize`, contextSelector `includeAll`/`placement` (#4509)
+
+Five authorable keys parsed, stored, and controlled nothing. What groups them is
+not the type they sit on but **why they had to go out in a major rather than
+after a deprecation cycle**: four of the five carry schema DEFAULTS, and a
+default materialises at parse time — so the liveness advisory lint cannot tell a
+value the author wrote from one the schema supplied. Marking them would have
+warned on every mapping and every selector in existence, which is why the ledger
+recorded them as `_authorWarnSkipped` instead. For a key in that state, removal
+is not the escalation after a warning. It is the only channel that ever reaches
+the author.
+
+**The retirement kit:**
+
+| FROM | TO | Fix |
+|---|---|---|
+| `mapping.extractQuery` | *(removed)* | Delete the key. Exports run through the ordinary query API (`POST /api/v1/data/:object/query`) — no exporter has ever read a mapping artifact. |
+| `mapping.errorPolicy` | *(removed)* | Delete the key. Error handling on the import path belongs to the import REQUEST's own options, not the stored mapping. |
+| `mapping.batchSize` | *(removed)* | Delete the key. The write path sizes its own batches. **Do not relocate the value** — see below. |
+| `app.contextSelectors[].includeAll` | *(removed)* | Delete the key. Selectors are mandatory-scope; widen `optionsSource.filter` to widen the choices. |
+| `app.contextSelectors[].placement` | *(removed)* | Delete the key. Selectors always render in the sidebar header; `'topbar'` placed nothing. |
+
+Run `os migrate meta --from 16` to rewrite existing sources automatically.
+
+**`includeAll` is the one worth reading twice.** It was not unread — it was
+deliberately *disobeyed*, and for a security reason. A context selector is a
+mandatory scope, so an "All" row would clear the scope on a surface that exists
+to be scoped; on Studio's package selector that means listing the platform's own
+system/cloud kernel packages to a developer who scoped to their own package. The
+renderer never offered an All row regardless of the flag, so `includeAll: false`
+hardened nothing and `includeAll: true` unlocked nothing. `STUDIO_APP` shipped
+authoring `includeAll: true` against a renderer that ignored it — that authoring
+site goes with the key in this change.
+
+**`batchSize` deliberately offers no rename.** `bulkActionDef.batchSize`,
+`connector.batchSize`, `sync.batchSize`, `offline.batchSize`, the seed loader's
+and the NoSQL driver cursor's are all LIVE and enforced — but each is a
+different key on a different type sizing its own path, and none of them sizes a
+mapping import. The rejection says so explicitly, because "removed" plus a
+familiar name one line away is exactly how a dead setting gets laundered into a
+live-looking one. Same trap `datasource.retryPolicy` had to defuse against
+`hook`/`job` `retryPolicy` (which spell the delay `backoffMs`) one issue
+earlier.
+
+Both schemas are `.strict()`, so the keys are deleted from the shape and
+rejected with a `guidance` prescription rather than tombstoned; their liveness
+rows are deleted rather than kept. The retired ALIAS spellings (`query`,
+`onError`, `errorHandling`, `errorMode`, `batch`, `chunkSize`, `skipErrors`,
+`showall`, `location`) route to the same prescriptions instead of suggesting a
+rename onto a key that is also gone.
+
+Registered as the ADR-0087 D2 conversion `mapping-inert-keys-removed` and an
+extension of `app-dead-authoring-keys-removed`, both wired into the protocol-17
+D3 chain step. The mapping conversion is scoped to the `mappings` collection
+deliberately — a stack-wide strip would delete an enforced `batchSize` from
+connector, sync, bulk-action and offline shapes.
+
+`datasource` reached zero dead keys in #4583; `mapping` reaches zero here.

content/docs/references/data/mapping.mdx

@@ -60,9 +60,6 @@ const result = FieldMappingSchema.parse(data);
 | **fieldMapping** | `{ source: string \| string[]; target: string \| string[]; transform: Enum<'none' \| 'constant' \| 'lookup' \| 'split' \| 'join' \| 'javascript' \| 'map'>; params?: object }[]` | ✅ |  |
 | **mode** | `Enum<'insert' \| 'update' \| 'upsert'>` | ✅ |  |
 | **upsertKey** | `string[]` | optional | Fields to match for upsert (e.g. email) |
-| **extractQuery** | `{ object: string; fields?: string[]; where?: any; search?: string \| { query: string; fields?: string[]; fuzzy: boolean; operator: Enum<'and' \| 'or'>; … }; … }` | optional | Query to run for export only |
-| **errorPolicy** | `Enum<'skip' \| 'abort' \| 'retry'>` | ✅ |  |
-| **batchSize** | `number` | ✅ |  |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |

content/docs/references/system/doc.mdx

@@ -67,6 +67,7 @@ const result = DocSchema.parse(data);
 | **content** | `string` | ✅ | Raw Markdown content (CommonMark + GFM) |
 | **order** | `number` | optional | Sort key within a book group (ADR-0046 §6) |
 | **group** | `string` | optional | Explicit book-group key (ADR-0046 §6); rules usually suffice |
+| **tags** | `string[]` | optional | Membership tags matched by a book group's `include: { tag }` rule (ADR-0046 §5) |
 | **translations** | `Record<string, { label?: string; description?: string; content: string }>` | optional | Per-locale `{label?,description?,content}` variants; the base doc is the fallback |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |

content/docs/references/ui/app.mdx

@@ -128,10 +128,8 @@ const result = ActionNavItemSchema.parse(data);
 | **label** | `string` | ✅ | Dropdown label |
 | **icon** | `string` | optional | Icon name |
 | **optionsSource** | `{ endpoint: string; valueKey: string; labelKey: string; filter?: { key: string; op: Enum<'eq' \| 'ne' \| 'in' \| 'nin'>; value: string \| string[] }[] }` | ✅ | Option data source |
-| **includeAll** | `boolean` | ✅ | Prepend an "All" option that clears the scope |
-| **allValue** | `string` | ✅ | Template value when "All" is selected (empty = no filter) |
+| **allValue** | `string` | ✅ | Sentinel value meaning "no concrete selection yet" (empty string is almost always right) |
 | **persist** | `Enum<'query' \| 'session' \| 'none'>` | ✅ | Persist selection via URL query, sessionStorage, or not at all |
-| **placement** | `Enum<'sidebar_header' \| 'topbar'>` | ✅ | Render location in the app chrome |
 
 
 ---