Merge remote-tracking branch 'origin/main' into claude/issue-4456-datasource-key-alias-conversion

# Conflicts:
#	docs/protocol-upgrade-guide.md
#	packages/spec/spec-changes.json
#	packages/spec/src/conversions/registry.ts

Author: claude

.changeset/boot-hydration-scoped-lookup.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): boot hydration grafts each overlay row's protection envelope from ITS OWN package (#4624)
+
+`loadMetaFromDb` (boot hydration) kept a **third** inline copy of the
+overlay→SchemaRegistry registration rule, and its artifact lookup was
+**unscoped** — the exact pre-#1828 shape ADR-0048 removed from `getMetaItems`:
+with two installed packages shipping the same `type`/`name`, a name-colliding
+overlay row grafted the **first-registered** package's
+`_lock`/`_lockReason`/`_packageId`/`_provenance` onto another package's row at
+every kernel boot. A row customized under package B could come up wearing
+package A's identity and lock.
+
+The non-object branch now delegates to the ONE shared
+`hydrateOverlayIntoRegistry` (introduced by #4521 for the read-side hydration
+and the write-through), passing the row's own `package_id` — one rule, one
+implementation, and the ADR-0048 package-scoped lookup applies at boot exactly
+as it does on read and write.
+
+No other boot behaviour changes:
+
+- **Boot order** — when packaged artifacts have not loaded yet at hydration
+  time, the scoped lookup finds nothing, exactly like the unscoped one did,
+  and the row registers unchanged.
+- **Package-less (global) rows** — `package_id IS NULL` keeps the legacy
+  best-effort first-match graft, identical to the read-side hydration.
+- **Row selection** — the helper carries no environment gate; which rows
+  `loadMetaFromDb` loads is decided by its query, unchanged here.

.changeset/datasource-external-inert-keys-retired.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/spec": major
+"@objectstack/example-showcase": patch
+---
+
+feat(spec)!: retire `external.label` and `external.requirePermission` (#4583 batch D)
+
+Two keys on the federation block, both read by nothing.
+
+**`external.label`** — nothing rendered the federation block's own label. Setup →
+Datasources renders the datasource's **top-level** `label`, which every datasource already
+has, so this was a second display name that never displayed. The showcase example declared
+both; it now declares only the one that shows.
+
+**`external.requirePermission`** — no authorization check ever consulted it. A permission
+named here gated nothing: access to a federated datasource's data is governed by the
+ordinary object permission sets and RLS, exactly as for a managed datasource. Naming a
+permission that is never required is the false-compliance shape ADR-0049 exists to remove
+— it reads like an access control and is one only in the author's head.
+
+FROM → TO: delete `external.label` (use the top-level `label`); delete
+`external.requirePermission` and grant or withhold the object permissions instead.
+`os migrate meta --from 16` removes both automatically (conversion
+`datasource-inert-blocks-removed`).
+
+With these, the `datasource` liveness ledger reaches **zero dead properties** — down from
+the 20 it was seeded with in #4487, the highest dead ratio of any governed type.

.changeset/datasource-health-check-retired.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: retire `datasource.healthCheck` — no probe loop ever existed (#4583 batch C)
+
+Three keys — `enabled`, `intervalMs`, `timeoutMs` — declared, strict-guarded, read by
+nothing. No health-check loop was ever scheduled, so `enabled: true` enabled nothing and
+the two timeouts bounded nothing.
+
+Connection liveness is probed **on demand** through the driver handle's `ping()` /
+`checkHealth()`, which the datasource admin service calls for "Test connection". That is
+the mechanism — it needs no configuration here and never read this block.
+
+Note what it is NOT to be confused with: `external.validation.checkIntervalMs` is the one
+recurring datasource timer, and it checks **schema drift** on a federated datasource, not
+connection liveness. It is unaffected.
+
+FROM → TO: delete the block. `os migrate meta --from 16` removes it automatically
+(conversion `datasource-inert-blocks-removed`).

.changeset/datasource-retry-policy-retired.md

@@ -0,0 +1,21 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: retire `datasource.retryPolicy` — nothing ever retried on it (#4583 batch B)
+
+Four keys — `maxRetries`, `baseDelayMs`, `maxDelayMs`, `backoffMultiplier` — declared,
+strict-guarded, and read by no connect or query path. Connection failure is handled by
+the boot policy in the datasource connection service (degraded boot, or `bootCritical`
+fail-fast); nothing retries on a schedule, so setting `maxRetries: 5` changed nothing.
+
+**Do not "fix" this by renaming keys.** `hook.retryPolicy` and `job.retryPolicy` ARE
+enforced — but they are a different key on a different type, and they spell the delay
+`backoffMs`, not `baseDelayMs`. That very inconsistency is the evidence nothing read the
+datasource one: no code in the repo reads both spellings. Moving these values onto a hook
+or a job only makes sense if you actually want that hook or job retried.
+
+FROM → TO: delete the block. `os migrate meta --from 16` removes it automatically
+(conversion `datasource-inert-blocks-removed`). `DatasourceSchema` is `.strict()`, so a
+leftover `retryPolicy` is a loud rejection carrying this prescription — never a silent
+strip.

.changeset/init-service-declared-enforced.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/metadata': patch
+'@objectstack/rest': patch
+'@objectstack/cli': patch
+'@objectstack/service-analytics': patch
+'@objectstack/service-datasource': patch
+'@objectstack/service-job': patch
+'@objectstack/service-knowledge': patch
+'@objectstack/service-queue': patch
+'@objectstack/service-settings': patch
+'@objectstack/service-storage': patch
+---
+
+Init-time service consumption is now declared everywhere, and the declaration is enforced (#4471, ADR-0116). A new CI gate (`check:init-service-contract`) walks every plugin's `init()` call graph — including private helpers, the shape that shipped #4420 — and errors on any init-reachable `getService('X')` of a workspace-provided service that is not covered by `dependencies`, `optionalDependencies`, or `requiresServices`. Eleven previously undeclared init-time consumers (metadata, rest, cli serve plugins, and seven services) now declare `optionalDependencies` on their providers, so the kernel orders them deterministically instead of by registration luck; each still degrades on purpose when the provider is not composed. Plugin authors: a best-effort init-time `getService` must declare its provider in `optionalDependencies` (declared tolerance) — the checker never exempts it.

.changeset/metadata-event-contract.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": patch
+"@objectstack/client": patch
+"@objectstack/spec": minor
+---
+
+fix(metadata,client): `subscribeMetadata` callbacks receive real `MetadataEvent`s — the producer now fulfils the declared contract (#4602)
+
+`@objectstack/spec/api`'s `MetadataEvent` declares top-level `id` (uuid,
+required), `metadataType`, `name`, `definition?`, `userId?` — and after
+#4587's convergence it is the **only** declared contract for realtime
+metadata-change events. But the producer (`MetadataManager`) published a raw
+`RealtimeEventPayload` envelope with everything nested under `payload` and no
+`id`/`userId`, while the client SDK force-cast that envelope into the callback
+(`callback(event as any as MetadataEvent)`). Subscribers who wrote
+`event.name` / `event.metadataType` — exactly what the types promised —
+compiled green and read `undefined` at runtime.
+
+Producer now fulfils the contract:
+
+- `MetadataManager.register()` / `unregister()` build a true `MetadataEvent`
+  (generated uuid `id`, flattened top-level fields, `userId` when the write
+  declares an actor) and validate it with `MetadataEventSchema.parse` before
+  publishing. The transport envelope is unchanged (`RealtimeEventPayload`,
+  with `payload` carrying the complete `MetadataEvent`).
+- A `register()` **overwrite now publishes `metadata.{type}.updated`** instead
+  of a second `.created`, mirroring the existing `added`/`changed` watcher
+  split. Previously `.updated` was declared with no producer at all.
+- `MetadataEventType` is a closed enum: metadata types outside it (e.g.
+  `translation`) have no declared realtime event, so nothing is published for
+  them (debug-logged) instead of emitting an event every schema-compliant
+  consumer must reject.
+
+Consumer validates instead of casting:
+
+- `@objectstack/client`'s `subscribeMetadata` (and therefore
+  `@objectstack/client-react`'s metadata hooks, which delegate to it) unwraps
+  the envelope and runs `MetadataEventSchema.safeParse` at the boundary. An
+  off-contract payload is rejected loudly (handler error, callback never
+  invoked) — never coerced or passed through. The `as any as MetadataEvent`
+  double-cast is gone.
+
+New seam: `MetadataWriteOptions.userId` (`@objectstack/spec/contracts`) lets
+write paths that know the acting user carry it into the published event's
+`userId`. Existing callers are unaffected — the field is optional and absence
+means "no human actor".

.changeset/notification-dual-source-c3.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: the notification vocabulary has one owner per name — `@objectstack/spec/ui` no longer exports `Notification(Schema)` / `NotificationConfig(Schema)`, and `@objectstack/spec/system` no longer exports `NotificationConfig(Schema)` (#4610)
+
+The names `Notification` / `NotificationSchema` (`./api` vs `./ui`) and
+`NotificationConfig` / `NotificationConfigSchema` (`./system` vs `./ui`)
+each resolved to **two different declarations** depending on the import
+path — the #4411 dual-source trap. Resolution (three-repo,
+import-statement-level consumer scan: framework, cloud, objectui):
+
+- **Removed** `NotificationSchema` / `Notification` from
+  `@objectstack/spec/ui`. This was a toast/banner "notification instance"
+  shape (`type`/`severity`/`message`/`duration`/`actions`/`position` + ARIA
+  props) with **zero importers** in all three repos — objectui's toaster
+  never adopted it. The live contract is `./api`'s `Notification(Schema)`:
+  the REST inbox row (`id`/`type`/`title`/`body`/`read`/`data`/`actionUrl`/
+  `createdAt`) embedded in `ListNotificationsResponseSchema`, served by
+  `/api/v1/notifications`, implemented by `@objectstack/client`, and
+  mirrored by `InboxNotification` in `@objectstack/spec/contracts`
+  (ADR-0030: the bell reads this shape).
+  - FROM `import { NotificationSchema, type Notification } from '@objectstack/spec/ui'` →
+    TO `import { NotificationSchema, type Notification } from '@objectstack/spec/api'`.
+    **Shape change**: the api row is an inbox record, not a presentation
+    config — the ui shape's `severity` / `duration` / `dismissible` /
+    `actions` / `position` / ARIA fields do not exist there. For the
+    presentation vocabulary keep using the ui enums, which are unchanged:
+    `NotificationTypeSchema`, `NotificationSeveritySchema`,
+    `NotificationPositionSchema`, `NotificationActionSchema` (+ their
+    types) still live in `@objectstack/spec/ui`.
+- **Removed** `NotificationConfigSchema` / `NotificationConfig` from **both**
+  `@objectstack/spec/system` and `@objectstack/spec/ui` — the bare name left
+  the spec export surface entirely. Both declarations had zero importers in
+  all three repos and were wired into no parent schema. The system side (a
+  channel + template + recipients + schedule + retryPolicy + tracking
+  "unified notification management protocol") predates ADR-0030's accepted
+  delivery architecture and advertised capability the runtime does not
+  deliver (its channel enum's `push`/`slack`/`teams`/`webhook` dead-letter,
+  #3197; nothing reads `schedule`/`retryPolicy`/`tracking`). The ui side (a
+  toaster global config: `defaultPosition`/`defaultDuration`/`maxVisible`/
+  `stackDirection`/`pauseOnHover`) was never adopted by objectui.
+  - FROM `import { NotificationConfigSchema } from '@objectstack/spec/system'` (or `.../ui`) →
+    TO: no direct replacement. The live delivery vocabulary is
+    `NotificationService.emit` (`INotificationService`,
+    `@objectstack/spec/contracts`), the `notify` flow node
+    (`NotifyConfigSchema`, `@objectstack/spec/automation`) and the
+    `sys_notification*` platform objects; per-user delivery preferences are
+    `NotificationPreferences(Schema)` in `@objectstack/spec/api`.
+- `@objectstack/spec/api`'s `Notification(Schema)` and
+  `NotificationPreferences(Schema)` are **unchanged**; `./api` is now the
+  sole owner of the bare `Notification(Schema)` names. Imports from `./api`
+  need no migration. `@objectstack/spec/system`'s `NotificationChannel(Schema)`,
+  `EmailTemplate(Schema)`, `SMSTemplate(Schema)`, `PushNotification(Schema)`
+  and `InAppNotification(Schema)` are **unchanged**.
+
+`dual-source-exports.baseline.json` shrinks by exactly these 4 rows (28 → 24,
+#4535 C3).

.github/workflows/lint.yml

@@ -173,6 +173,21 @@ jobs:
       - name: Wildcard fall-through guard
         run: pnpm check:wildcard-fallthrough
 
+      # Init-service declaration guard (#4471, ADR-0116). The kernel's ordering
+      # contract (dependencies / optionalDependencies / requiresServices /
+      # providesServices) was complete but VOLUNTARY: a plugin that resolves
+      # getService('X') during init() and declares nothing fails only under
+      # unlucky composition orders, usually inside a best-effort try/catch that
+      # downgrades the miss to a warn. That silence shipped #4085 and #4420 (the
+      # latter losing every in-flight approval on restart). This scan walks each
+      # plugin's init() call graph from the AST — the #4420 call sat in a private
+      # helper, not init()'s own body — and errors on any init-reachable
+      # getService of a workspace-provided service that no declaration covers.
+      # Declared tolerance stays in the plugin (optionalDependencies), never in a
+      # checker-side ledger. Runs its own --self-test first.
+      - name: Init-service declaration guard
+        run: pnpm check:init-service-contract
+
       # Release-notes drift guard: the platform is one version-locked train, so
       # every released @objectstack/spec major must have a curated, navigable
       # release page at content/docs/releases/v<major>.mdx. Catches the gap that

content/docs/references/api/meta.json

@@ -32,7 +32,6 @@
     "export",
     "identity",
     "metadata",
-    "notification",
     "package-api",
     "package-registry",
     "plugin-rest-api",