Merge remote-tracking branch 'origin/main' into claude/issue-9111-hydrate-overlay-raw-type

Author: claude

.changeset/actions-door-demotes-author-codes.md

@@ -0,0 +1,41 @@
+---
+"@objectstack/spec": minor
+"@objectstack/types": minor
+"@objectstack/runtime": minor
+---
+
+`error.code` is a closed vocabulary at every door (#9106, maintainer ruling
+2026-08-16): the runtime dispatcher's thrown-error exits
+(`HttpDispatcher.errorFromThrown`, `dispatcher-plugin`'s `errorResponseBase`,
+`endpoint-executor`'s `endpointErrorAnswer` — the actions door among them) now
+serve the narrowed `code` the shared resolver (`resolveThrownHttpError`,
+`@objectstack/types`) has always computed, exactly as the REST door has since
+#8016. A thrown code that is not a member of `StandardErrorCode ∪
+ERROR_CODE_LEDGER` no longer reaches `error.code`.
+
+It is not dropped: `ApiErrorSchema` declares a new optional `declaredCode`
+field — the open, author-authored channel — and the demoted spelling rides
+there. Presence means demotion: the field is absent whenever the producer's
+code is a vocabulary member (it is already in `error.code`) or the producer
+declared none. The #7867 sandbox passthrough capability is preserved — a
+metadata app's own thrown `.code` still crosses the QuickJS boundary and still
+reaches the wire.
+
+For a metadata app that throws its own code (e.g.
+`Object.assign(new Error('pick another'), { code: 'DUPLICATE' })` in an action
+body) and reads it back from an actions-door failure:
+
+- FROM: `error.code === 'DUPLICATE'`
+- TO: `error.code` is the closed member the status derives (e.g.
+  `VALIDATION_ERROR` on a 400) and `error.declaredCode === 'DUPLICATE'`.
+  One-line fix: branch on `error.declaredCode` for app-specific spellings;
+  branch on `error.code` for platform conditions.
+
+Platform producers are unaffected: every registered code reaches `error.code`
+verbatim, as before (post-#8846 the dispatcher-vocabulary gate holds that set
+registered). Measured before landing (the ruling's binding precondition): no
+existing consumer of the actions door branches on author-authored strings in
+`error.code`.
+
+`@objectstack/types` adds `demotedDeclaredCode(thrown)` — the one definition of
+"which spelling a boundary surfaces beside the closed `code`".

.changeset/cbp-master-detail-required-forced.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): the builder forces `required: true` on a `master_detail` reference under `controlled_by_parent` (#9138 — #8772 maintainer ruling, Direction 2)
+
+**BREAKING** accept-face narrowing on the authoring builder, landing after the
+v17.0.0 cut (the lockstep launch-window convention ships it as `minor`; the
+prescription is registered under protocol major 18, where `os migrate meta`
+users will look).
+
+A `controlled_by_parent` object derives ALL of its record access from the
+master its `master_detail` reference names (ADR-0055). A master reference that
+is not `required` arms the worst measured failure shape: an insert may omit
+the master FK, the row lands with a null FK that the derived read filter
+(`masterFK IN (accessible master ids)`) can never match — unreadable by
+everyone — and every later by-id write answers `422 MISSING_REQUIRED_FIELD`.
+#8772 measured that only the security gate closed that shape while the
+declaration surface accepted it.
+
+`ObjectSchema.create()` now makes the unsafe shape impossible to newly
+declare:
+
+- an **omitted** `required` on a `master_detail` reference under
+  `sharingModel: 'controlled_by_parent'` is **forced to `true`** in the
+  emitted object;
+- an **explicit `required: false`** there is **refused** with a located error
+  naming the object, the field, the consequence and the fix — an explicitly
+  authored contradiction is not silently rewritten (ADR-0032).
+
+## FROM → TO
+
+```ts
+// before — parsed green; the null-FK trap stayed armed behind the security gate
+export const InvoiceLine = ObjectSchema.create({
+  name: 'invoice_line',
+  sharingModel: 'controlled_by_parent',
+  fields: { invoice: { type: 'master_detail', reference: 'invoice', required: false } },
+});
+
+// after — refused at build with the prescription; omitting `required` is fine
+// (the builder emits `required: true` by construction)
+export const InvoiceLine = ObjectSchema.create({
+  name: 'invoice_line',
+  sharingModel: 'controlled_by_parent',
+  fields: { invoice: { type: 'master_detail', reference: 'invoice', required: true } },
+});
+```
+
+**What stays accepted:** everything outside that one shape. Raw
+`ObjectSchema.parse()` / `.safeParse()` — the path metadata at rest rehydrates
+through — still accept the old shape unrewritten, so existing installs keep
+loading; the security gate's derived enforcement stays; the lint rule
+`relationship/master-detail-required` stays `warning` until its own v18
+promotion (#9139). The 2026-08-15 survey measured the shipped first-party
+surface at exactly 3 `controlled_by_parent` objects, all already
+`required: true` — zero first-party migration.
+
+<!-- adr-0087: registered cbp-master-detail-required-forced -->

.changeset/element-filter-lint-residue.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): drop the `element:filter` entry from `COMPONENT_FIELD_SPECS` (#9220)
+
+The whole `element:filter` element retired at element grain (ADR-0049 — no
+renderer ever shipped for it), so every `ElementFilterProps` key is a
+`retiredKey()` tombstone and no spec-conformant page carries `fields` on it.
+The field-binding rule's job (resolve a field NAME against the object) is not
+the question a retired key raises: an authored key is already reported by name
+with the element-retirement prescription through the #5068 props gate, and the
+binding entry would only add a second finding about a key that no longer
+exists — the #5775/#6629 residue class the package's own
+`component-field-specs-liveness` gate refuses.

.changeset/element-filter-retired.md

@@ -0,0 +1,72 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): retire the `element:filter` element at element grain (#9220, ADR-0049)
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the migration prescription is
+registered under protocol major 18, where `os migrate meta` users will look).
+
+`element:filter` never had a renderer or reader anywhere. Measured at
+retirement (objectstack `2f65b1b42`, objectui `5ffcc14`; cloud per the origin
+card's recorded sweep): objectui registers no renderer for it — its
+`renderers/basic/elements.tsx` header deferred the element to "owning plugins"
+that never materialized — Studio's designer palette carries it as a no-renderer
+`PALETTE_EXCLUSIONS` entry ("list surfaces own filtering (userFilters / filter
+builder)"), and the 2026-06 page-liveness audit recorded it rendering "Unknown
+component type". Every one of its six authorable keys — `object`, `fields`,
+`targetVariable`, `layout`, `showSearch`, `aria` — was a capability claim
+nothing kept: an author (human or AI) who configured a filter element got a
+success receipt for a component that renders nothing (the ADR-0078 shape).
+\#9198 retired `targetVariable` per-key on the two input elements and recorded
+this wider finding; per-key retirement would have been the wrong grain here, so
+the whole element retires at once.
+
+**What is refused:** any authored key on `element:filter` `properties`. All six
+keys are `retiredKey()` tombstones — refused at `tsc` (typed `never`) and at
+the parse, message carrying the element-grain prescription. The
+`ComponentPropsMap` row deliberately STAYS so the #5068 props gate keeps
+dispatching on the type and refusing loudly — deleting the row would demote the
+type to an unregistered custom string the gate deliberately skips.
+
+**What stays accepted:** a bare `element:filter` node with empty `properties`
+(the migrated shape) still parses at the node level — `PageComponentSchema.type`
+is an open union, so a node-level refusal is not expressible; the node was
+always inert and stays inert. `element:filter` is removed from the
+`PageComponentType` enum (de-advertisement — docs, palette derivations, and the
+authorable vocabulary), which changes no parse outcome. Filtering on list
+surfaces is unchanged and was never this element's: use a view's `userFilters`
+quick-filter bar or the list toolbar's filter builder.
+
+The retirement kit:
+
+- tombstones at the schema (`packages/spec/src/ui/component.zod.ts`), enum
+  removal at `packages/spec/src/ui/page.zod.ts`
+- ADR-0087 registration: retired-key entries `ui/ElementFilterProps:object` /
+  `:fields` / `:targetVariable` / `:layout` / `:showSearch` / `:aria` and the
+  D2 conversion `element-filter-removed` (protocol 18), wired into the step-18
+  chain — `os migrate meta --from 17` strips the keys from old sources (pure
+  lossless deletes; none ever had an effect to lose) and leaves the bare node
+- the #9198 conversion's negative-control fixture moves from `element:filter`
+  to an open-union custom type (same assertion — the strip dispatches on the
+  component type, not the key name)
+- pin tests (`component.test.ts` — refusal carries the prescription; the
+  bare migrated node parses clean and materializes nothing)
+- generated baselines/docs follow the schema (`authorable-surface/`,
+  `json-schema.manifest/`, spec-changes, upgrade guide, reference docs)
+
+## FROM → TO
+
+```ts
+// before — parsed green; nothing anywhere rendered it
+{
+  type: 'element:filter',
+  properties: { object: 'order', fields: ['status'], layout: 'sidebar' },
+}
+
+// after — delete the component; filtering belongs to the list surface
+// (view.userFilters / the list toolbar's filter builder)
+```
+
+<!-- adr-0087: registered element-filter-removed -->

.changeset/element-input-target-variable-retired.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): retire the inert `targetVariable` key from `element:text_input` and `element:record_picker` (#9198, ADR-0049)
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the migration prescription is
+registered under protocol major 18, where `os migrate meta` users will look).
+
+`targetVariable` on the two SDUI input elements was a declarative hint with
+zero readers in any repo — its own describe text said the live binding
+"resolves via the variable whose `source` equals this component id"
+(`PageVariableSchema`), and that reverse lookup
+(`usePageVariableBinding(schema?.id)` in the console renderer) is the only
+binding mechanism that exists. Measured (objectstack-ai/objectui#3834,
+re-verified at retirement): no renderer, hook or runtime in objectui,
+framework or cloud reads the key. An author — human or AI — who read the
+manifest, wrote `targetVariable`, and skipped the variable's `source` got an
+input that wrote nothing, with a success receipt and no diagnostic anywhere.
+Same disposition as the sibling inert hint settled by retirement in objectui
+PR #4794.
+
+**What is refused:** an authored `targetVariable` on `element:text_input` or
+`element:record_picker` properties. Both keys are `retiredKey()` tombstones —
+refused at `tsc` (typed `never`) and at the parse, message carrying the
+prescription.
+
+**What stays accepted:** every text input / record picker without the key,
+byte-identically — including the working binding (`variables[].source`), which
+is untouched. `targetVariable` on `element:filter` is a different surface and
+is not part of this disposition. Runtime behaviour is unchanged: nothing ever
+read the key, so removing it removes no behaviour.
+
+The retirement kit:
+
+- tombstones at the schema (`packages/spec/src/ui/component.zod.ts`)
+- ADR-0087 registration: retired-key entries
+  `ui/ElementTextInputProps:targetVariable` +
+  `ui/ElementRecordPickerProps:targetVariable` and the D2 conversion
+  `element-input-target-variable-removed` (protocol 18), wired into the step-18
+  chain — `os migrate meta --from 17` strips the key from old sources (pure
+  lossless delete; it never had an effect to lose)
+- pin tests (`component.test.ts` — refusal carries the prescription; clean
+  parses materialize nothing)
+- generated baselines/docs follow the schema (`authorable-surface/`,
+  `json-schema.manifest/`, spec-changes, upgrade guide, reference docs)
+
+## FROM → TO
+
+```ts
+// before — parsed green; the hint bound nothing
+{
+  id: 'email_input',
+  type: 'element:text_input',
+  properties: { inputType: 'email', targetVariable: 'contact_email' },
+}
+
+// after — delete the key; declare the binding on the page variable instead
+{
+  id: 'email_input',
+  type: 'element:text_input',
+  properties: { inputType: 'email' },
+}
+// page.variables: [{ name: 'contact_email', type: 'string', source: 'email_input' }]
+```
+
+<!-- adr-0087: registered element-input-target-variable-removed -->

.changeset/email-render-only-seam.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/spec": minor
+"@objectstack/plugin-email": minor
+"@objectstack/service-messaging": minor
+---
+
+feat(messaging): `IEmailService` gains a render-only `renderTemplate({ template, locale, data, timezone }) → { subject, html, text }`, and the inbox channel consumes it — localized `sys_email_template` content now reaches `sys_inbox_message` (#9225)
+
+A template-path notify node with `channels: ['inbox', 'email']` delivered a
+localized email and an inbox row whose title was the topic and whose body was
+empty: the locale ladder + `{{var}}` renderer (ADR-0053 format filters
+included) lived inside plugin-email's `sendTemplate`, unreachable without
+sending mail (maintainer-ruled seam, 2026-08-17, on #9225).
+
+- `IEmailService.renderTemplate` (new contract method, `packages/spec`)
+  resolves a `sys_email_template` bundle by `(name, locale)` with the same
+  documented en-US ladder as `sendTemplate`, validates required variables, and
+  returns the rendered `{ subject, html, text }` — strictly render-only: no
+  transport call, no queueing, no `sys_email` row. Implemented ONCE in
+  plugin-email by extracting the resolver `sendTemplate` already used;
+  `sendTemplate` now delivers what the shared resolver renders, byte for byte.
+- The messaging inbox channel consumes it the way the email channel consumes
+  `sendTemplate`: a delivery whose payload carries a notify `template`
+  reference renders `subject` into the row's `title` and `text` into
+  `body_md`, per recipient, at delivery time. A registered email service
+  without the method — or no email service at all — fails the delivery LOUDLY
+  (`TEMPLATE_UNSUPPORTED`, graded permanent) instead of silently degrading to
+  topic-as-title; renderer failure codes (`TEMPLATE_NOT_FOUND` /
+  `TEMPLATE_INACTIVE` / `MISSING_VARIABLES`) land on the delivery row and are
+  graded permanent, mirroring the email channel.
+
+The result shape follows what `sys_email_template` rows carry
+(`subject`/`body_html`/`body_text?`): `html` is the rendered `body_html`,
+`text` is the rendered `body_text` or, when the row declares none, derived
+from the rendered HTML.

.changeset/list-comparand-shape-door.md

@@ -0,0 +1,53 @@
+---
+"@objectstack/spec": patch
+"@objectstack/objectql": patch
+---
+
+fix(spec): enforce the list-comparand rule at the shared compile face, so a scalar `in`/`nin` no longer reaches a driver (#9228)
+
+<!-- adr-0087: not-required (no-migration-prescription) No authorable key is
+added, renamed, retired or tombstoned. The change moves an existing runtime rule
+from `@objectstack/objectql` to `@objectstack/spec` and calls it from
+`parseFilterAST`; the authorable metadata surface is byte-identical. -->
+
+`FieldOperatorsSchema` has always declared `$in` / `$nin` as `z.array(z.any())`
+and `$between` as `z.tuple([min, max])`, and #5869 / PR #6209 built the gate that
+enforces it — but only at `@objectstack/objectql`'s lowering seam. That covers
+every query reaching a driver **through the engine** and nothing else. A caller
+that lowers a filter with `parseFilterAST` and calls a driver directly — an
+embedder, and this repo's own driver conformance suites — met no gate at all:
+`parseFilterAST([['name', 'notin', 'alpha']])` returned `{ name: { $nin:
+'alpha' } }`, a shape the contract forbids, and handed it over.
+
+That path was carried by mingo's own coercion of a non-array `$in`/`$nin`
+operand. mingo 7.2.3 removed the coercion, so from 7.2.4 on the same input
+escapes as an unhandled third-party `TypeError: b.filter is not a function` —
+no `code`, no `status`, no field name — straight to the caller. It is the sole
+failure blocking the `mingo` 7.2.2 -> 7.2.4 bump.
+
+**Fixed at the shared face, with exactly one implementation.** The rule now
+lives in `@objectstack/spec`'s `data/filter-comparand-shape.ts`, the same place
+the comparand-TYPE door (#7872 / PR #8234) was promoted to for the same reason
+("enforced once at the shared compile face for all five drivers"), and
+`parseFilterAST` runs it on everything it returns — shape first, then type, the
+order the engine's own seam already applied. `@objectstack/objectql`'s
+`assertListComparandShapes` is now a delegating wrapper whose only remaining job
+is the engine's `find('deal'): ` caller prefix; no driver was patched (both
+driver families are under the #5499 investment freeze).
+
+**The accept/reject delta is narrow and one-directional.** Newly refused, with
+the ADR-0112 `INVALID_FILTER` / 400 envelope: a non-array `$in` / `$nin`
+comparand and a non-`[min, max]` `$between` comparand, reaching a driver via a
+direct `parseFilterAST` call. Nothing else changes — every filter the engine
+accepted still lowers byte-identically, `$in: []` / `$nin: []` remain legitimate
+declared predicates, list MEMBER types stay unjudged here, and a field spec with
+no `$` key is still not descended into. The same inputs were already refused
+with the same envelope on every engine verb and at the REST ingress, so no
+authored metadata in the repo or in `objectui` produces a shape that newly
+fails: a survey of `examples/**`, `content/docs/**`, fixtures, seeded platform
+objects and objectui's view definitions found every membership rule already
+carrying an array.
+
+`parseFilterAST` gains an optional second argument, `context` — the caller
+prefix both doors in `@objectstack/spec` already take. It is additive and
+defaulted; existing calls are unaffected.