Merge remote-tracking branch 'origin/main' into claude/issue-21062-picker-queryable-key

Author: claude

.changeset/20513-metadata-core-case-labels-state-the-case.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/metadata-core': patch
+---
+
+The shared engine case tables and the published contract suites in metadata-core no longer cite tracker numbers in their case labels; each label states its case in words
+
+Clause-②: no
+
+Several labels these tables and suites ship ended with an issue-tracker number where the case belonged. A
+test driven from them printed that number as part of its name, and a failing assertion quoted it as the
+reason. The number goes; where the label did not already say what the case is, it now does.
+
+- `ENGINE_DELETE_DISPATCH_CASES`, `ENGINE_UPDATE_DISPATCH_CASES` and `ENGINE_FINDONE_PREDICATE_CASES`:
+  the `what` labels of 22 rows. Among them, the compare-and-set rows now say the by-id path would drop the
+  CAS guard; the payload-id rows say which declared `where.id` would be silently dropped; and the falsy
+  `where.id` boundary says it is a scalar, so neither the different-row refusal nor the non-scalar refusal
+  applies.
+- `@objectstack/metadata-core/testing`: the repository contract suite's `serialized-form identity` group
+  title, and two `why` texts of `OBJECT_SCHEMA_MASK_CASES` (the empty-readable-set refusal, and the
+  write-capable exemption, which now names the schema write gate, `manage_metadata`).
+
+Text only: no case is added, removed or re-ordered, and no `options`, `data`, `expect`, `expectId`, `id`,
+`readable` or `context` value moves. A suite that selects or skips these cases by their label text (a
+`-t` filter, a skip list) needs the new spelling.

.changeset/20573-knowledge-record-branch.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/service-knowledge': patch
+---
+
+fix(service-knowledge): the realtime event bridge no longer keeps a `record.created` / `record.updated` / `record.deleted` branch, and its docs name the events ObjectQL really publishes (#20573)
+
+No producer emits a bare `record.*` event: the ObjectQL engine publishes `data.record.created` / `data.record.updated` / `data.record.deleted` for a single-record write and `data.records.updated` / `data.records.deleted` for a predicate write (`multi: true`), and `@objectstack/spec` already dropped the bare names from `RealtimeEventType`. The `KnowledgeServicePlugin` subscription handler still carried a branch for them, with a `payload.record ?? payload` fallback for a shape nothing sends. That branch is removed. The `data.record.*` sync (record body from `after`, id from `recordId`) and the `data.records.*` stale-index warning are unchanged.
+
+The `enableEventSync` option's TSDoc and the `handleRecordUpsert` / `handleRecordDelete` docs now name `data.record.created|updated|deleted` instead of `record.*`.
+
+If a plugin of yours publishes a bare `record.created`, `record.updated` or `record.deleted` event through `IRealtimeService` and relied on the knowledge index following it, publish `data.record.created|updated|deleted` with the `DataEvent` payload instead (the record in `after`, its id in `recordId`).

.changeset/20987-analytics-contains-membership.md

@@ -0,0 +1,21 @@
+---
+'@objectstack/core': minor
+'@objectstack/service-analytics': minor
+'@objectstack/driver-sql': patch
+---
+
+fix(service-analytics)!: the analytics read scope and the native `where` answer `$contains` / `$notContains` on a multi-valued or JSON-stored field by membership, with the one construct `driver-sql` emits, now exported from `@objectstack/core` (#20987)
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a correction of which rows two analytics SQL faces answer for one operator on one declared field class: the read scope `compileScopedFilterToSql` compiles from a row policy, and the native strategy's rendering of a query's `where`. No authorable key, spelling, export or stored shape of metadata moves; `packages/spec` is untouched, and the contract sentence the faces now meet (`FILTER_OPERATORS.$contains`) is the one already declared. A policy or filter that was written stays written as it was, and what it now selects is what the data door already selected for it, so there is nothing a ledger entry could rewrite. The new refusal on a datasource whose SQL dialect the host cannot name is a refusal of a query, not of stored metadata. The other categories are closed on facts: the packages publish (not `unpublished`); no ADR-0087 id covers a filter operator's reading (not `registered` / `already-registered`); and the change is runtime behaviour plus one additive export, not a declaration change (not `runtime-interface-only` / `type-surface-only`). -->
+
+**BREAKING**: this narrows what the analytics doors answer for one class of read. A row policy (the read scope the analytics plugin compiles from the security service, or a host's own `getReadScope`) whose `$contains` or `$notContains` names a field declared multi-valued (`multiple: true` on a multi-capable type, or a multi-option type) or JSON-stored now selects the rows holding the comparand as an ELEMENT of the stored list. It used to select every row whose stored JSON text contained the comparand as a substring, so on SQLite a policy could admit rows outside it, and on PostgreSQL every query under such a policy answered `500` (MySQL was not measured). An analytics count under such a policy now equals what the same caller reads through the data door. On a datasource whose SQL dialect the analytics host cannot name, such a policy now refuses the query (`READ_SCOPE_COMPILE_FAILED` / `500`) instead of falling back to the substring reading. It ships as `minor` under the launch-window convention.
+
+**The `where`.** `POST /api/v1/analytics/query`, the dataset door and `/analytics/sql` on the native strategy render the same membership test for a `$contains` / `$notContains` in a query's `where` (or a dataset's `runtimeFilter`) on such a field: on PostgreSQL the query answers rows where it answered `500`, and on SQLite the count stops over-counting (`$contains`) and under-counting (`$notContains`). On a datasource whose dialect the host cannot name, the operator on such a field is refused `INVALID_FILTER` / `400`. The ObjectQL strategy already answered membership and is unchanged.
+
+**Unchanged.** On a scalar text field `$contains` stays the substring test, on every face. `$notContains` keeps its NULL rule: a row with no value satisfies it. A host that wires no field metadata keeps the substring reading, because it cannot tell a JSON column from a text one; the analytics plugin wires it from the data engine.
+
+**New export.** `@objectstack/core` exports `jsonMembershipPredicate(dialect, emitters, value)` and `jsonMembershipCandidates(value)`, with the `JsonMembershipDialect` and `JsonMembershipEmitters` types: the per-dialect membership construct (#17590) moved from `@objectstack/driver-sql`, where it was module-private, and made placeholder-agnostic. `@objectstack/driver-sql` imports it and emits byte-identical statements and bindings.
+
+**What to do after upgrading.** Nothing, unless a policy or a dashboard filter relied on the substring reading of a multi-valued or JSON-stored field: such a filter now selects members only, as the data door always did. A host whose analytics `sqlDialect` hook answers nothing for a SQL datasource should answer `'sqlite'`, `'postgres'` or `'mysql'`, or the operator on such a field is refused.

.changeset/21005-action-row-endpoint-refused.md

@@ -0,0 +1,31 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: `action:button` / `action:icon` refuse `endpoint` with the rename `ActionSchema` already prescribes — `endpoint` → `target` (#21005)
+
+**BREAKING** — `endpoint` on an `action:button` or `action:icon` component (`ActionButtonProps`, `ActionIconProps`) is no longer a declared key. `ActionSchema` has always refused `endpoint` with "Did you mean `endpoint` → `target`?", while these two rows accepted it. objectui's console registers its own `api` handler, which reads `target` and never `endpoint`, so an `api` button written with `endpoint` passed the props gate and called nothing. The rows now refuse it with the same rename, read from the one alias table the action and both rows share. Write the endpoint as `target`.
+
+Clause-②: yes (narrowing)
+
+## FROM → TO
+
+| you wrote (17.5 and earlier) | write instead |
+| --- | --- |
+| `{ type: 'action:button', properties: { actionType: 'api', endpoint: '/api/v1/x' } }` | `{ type: 'action:button', properties: { actionType: 'api', target: '/api/v1/x' } }` |
+| `{ type: 'action:icon', properties: { actionType: 'api', endpoint: '/api/v1/x' } }` | `{ type: 'action:icon', properties: { actionType: 'api', target: '/api/v1/x' } }` |
+| `endpoint` on a block with no `actionType` | add `actionType: 'api'` and rename `endpoint` to `target` |
+
+**The one-line fix:** rename `endpoint` to `target` in the block's `properties`; the value (the URL the `api` action calls) is unchanged.
+
+**What an author who still writes it sees.** A page is never refused for it: a page component's `properties` is an open bag, so `definePage()`, `defineStack({ pages })` and the page write door accept the page as before. `os validate` / `os build` / `os lint` report `component-props-unknown-key` as a warning at `properties.endpoint`, with the rename "Did you mean `endpoint` → `target`?" — the same clause `ActionSchema` prints. The two rows also stop answering `path` with the edit-distance guess `patch` (the declarative write's field values): `url`, `endpoint`, `path` and `href` all rename to `target`, on the action and on both blocks alike. A typed `ActionButtonProps` / `ActionIconProps` input fails `tsc` at `endpoint`.
+
+## The migration kit
+
+- **The D2 conversion `action-block-endpoint-to-target`** (protocol 18, retired from the load path) renames `endpoint` to `target` on an `action:button` / `action:icon` whose `actionType` is `api`, the one meaning the key declared, with one notice per block. It reaches blocks in regions, nested in a container's `children`, and in a slotted page's named slots, so a stored `page` row or a built artifact that carries the key loads with `target` through the rehydration seams, which replay it. An already-present `target` wins: a twin with the same value is dropped. A block with no `actionType`, another `actionType`, a non-string `endpoint`, or a `target` that names a different endpoint is left as stored and reported as a TODO. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand.
+- **The D3 entry `action-block-endpoint-spelling-retired`** names what the rename cannot decide: the TODO sites above, and code — a custom action handler that read `endpoint` off the action reads nothing once the block carries `target`.
+- **No deprecation window**, per the project's startup-stage posture.
+
+Census at landing: no producer in this repository (examples, templates, platform pages, fixtures) or in objectui's examples authors `endpoint` on either block. ⚠️ **The out-of-repo consumer population is NOT MEASURED.** `@objectstack/spec` is published, so this is breaking for consumers no telemetry was consulted for.
+
+<!-- adr-0087: registered action-block-endpoint-to-target, action-block-endpoint-spelling-retired -->

.changeset/21017-quickadd-remedy.md

@@ -0,0 +1,11 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the `object-kanban` `quickAdd` retirement no longer sends authors to the `kanban-ui` block, which objectui does not register
+
+Clause-②: no
+
+- The refusal of `quickAdd` on `object-kanban` now ends "Delete the key; `object-kanban` offers no quick-add control." It used to say the control "is unchanged on the `kanban-ui` block". objectui retired that block (objectui#8257), so a node of that type saves clean and renders nothing. The refusal itself is unchanged: the same key is still refused, with the same code and path.
+- The same sentence replaces the old one in the `os migrate meta --from 17` output (the `object-kanban-quick-add-retired` entry) and in the summary of the `object-kanban-quick-add-removed` conversion. That entry no longer offers "move the board to a host that renders the `kanban-ui` block" as a second way out.
+- No author action beyond the existing one. `quickAdd: true` on an `object-kanban` is still a parse error. Delete the key.

.changeset/21054-plan-runs-no-app-hooks.md

@@ -0,0 +1,37 @@
+---
+'@objectstack/cli': patch
+'@objectstack/runtime': minor
+---
+
+fix(cli): `os migrate plan` / `apply` no longer run the app's `onEnable` or a host plugin's post-declaration hooks during their boot
+
+Clause-②: yes (widening)
+
+The two schema commands boot the host's stack to read what it declares. That boot ran the
+config's `onEnable`, and every `kernel:bootstrapped` / `kernel:listening` hook a host plugin
+registered from `init()`. A hook that reads a table the plan does not declare then failed on
+every plan. On `examples/app-crm`, whose `onEnable` binds positions to permission sets, each
+plan printed six `[sql-driver] DATABASE_ERROR` lines and six `position binding lookup failed`
+warnings, on a database `apply` had just migrated as well as on an absent one.
+
+The boot now composes host code for its declarations only:
+
+- `AppPlugin` takes a new `skipOnEnable` option. When it is set, `start()` does not run the
+  bundle's `onEnable`, logs that it withheld it, and reports it through `onEnableWithheld`. The
+  migrate commands set it on the app they compose from `objectstack.config.ts`.
+- A host plugin's `init()` gets a context that does not register `kernel:bootstrapped` or
+  `kernel:listening` hooks. The kernel contract defines those phases as work after registration
+  ends: reconcile/backfill, and opening listeners. `kernel:ready` hooks still run, and the
+  write guard still refuses their row writes. `kernel:shutdown` hooks and data hooks register
+  as before.
+- The plan's notes, and the `--json` payload's `composition.notes`, carry one line naming what
+  was not run.
+
+The plan itself is unchanged: the same tables, the same pending DDL, the same drift. `apply`
+still flushes the DDL the operator confirms and still runs the coverage pass. The platform's own
+plugins are untouched, so the value-shape gate announcement still prints.
+
+`@objectstack/runtime` widens its public surface, additively: `AppPlugin`, exported from the
+package root, gains the optional constructor option `skipOnEnable` (default `false`) and the
+read-only getter `onEnableWithheld`. A composition that does not pass the option gets exactly
+the behaviour it had, `onEnable` included.

.changeset/21063-security-contract-zero-set-fields.md

@@ -0,0 +1,33 @@
+---
+'@objectstack/spec': minor
+---
+
+docs(spec)!: the security service contract's field answers for a caller who resolves no permission set exclude the fields that declare `requiredPermissions` (#21063)
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) Only the prose of the ISecurityService interface moves: no method, parameter, return type, schema key or stored shape changes, so objectstack migrate meta has nothing to rewrite. The answers it now states are the ones every field-level requiredPermissions declaration already implied. -->
+
+**BREAKING for implementers and consumers of `ISecurityService` field answers.**
+
+**What changed.** The contract in `@objectstack/spec/contracts` now states the
+field answers for a non-system caller who resolves no permission set. Such a
+caller holds no permission-set field grant and no capability. No grant narrows
+its answers, and a field's own declarations still apply: a field that declares
+`requiredPermissions` is not in its `getReadableFields` answer (unless a
+`maskingRule` on the field serves it masked, which keeps it as a served
+column), and it is not in its `getWritableFields` answer.
+`getMetadataReadableFields` answers the same for that caller when the
+deployment's fallback set resolves to nothing. The contract used to say the
+data-plane answer for that caller was the full field set, because the engine
+middleware skipped its whole field gate for it. The middleware skips only its
+permission-set grant gates.
+
+**Who this reaches.** An implementation of `ISecurityService` must answer this
+way for that caller. A consumer that relied on the full field set for that
+caller now receives the narrower answer from the reference implementation
+(`@objectstack/plugin-security`).
+
+**What to do.** An implementation folds each field's `requiredPermissions`
+into its answer for this caller exactly as it does for a caller whose
+permission sets lack the capability. A consumer needs no change.

.changeset/21063-zero-set-capability-fold.md

@@ -0,0 +1,40 @@
+---
+'@objectstack/plugin-security': minor
+---
+
+fix(plugin-security)!: a field that declares `requiredPermissions` is not served to a caller who resolves no permission set, and that caller may not query on it or write it (#21063)
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing an author wrote is rewritten or changes meaning: every field-level requiredPermissions already declared mask on read and deny on write for a caller who does not hold all of it, and this change makes the runtime honour that declaration for the one caller class it skipped. No stored metadata, schema key or published type moves. -->
+
+**BREAKING for callers who resolve no permission set.**
+
+**What changed.** A field that declares `requiredPermissions` is masked on read
+and denied on write unless the caller holds all of them (ADR-0066 D3). A caller
+who carries a principal but resolves no permission set holds no capability, so
+the gate applies to it, but the runtime served that caller the stored value,
+let it filter, sort, group and aggregate on the field, and accepted a write
+that named it. The explain engine already reported the field hidden for that
+caller. Now the field is not served to it (a field that also declares a
+`maskingRule` is served masked, as before). A filter, sort key, group key or
+aggregate that names the field is refused with `403 PERMISSION_DENIED`, and so
+is a write payload that names it, as for any other caller who lacks the
+capability.
+
+The published field answers agree with what is served and refused.
+`ISecurityService.getReadableFields`, `getQueryableFields` and
+`getWritableFields` no longer list such a field for this caller, and neither
+does `getMetadataReadableFields` when the deployment's fallback set resolves to
+nothing. The write preview answers such a payload as the write path does.
+
+**Who this reaches.** A caller who resolves no permission set but carries a
+position, a named permission set or a user id. A caller with none of the three
+is handed through untouched, as before, and the field projections say so. A
+caller who resolves at least one permission set is unaffected, and so is a
+system context. Whether this caller may read or write the object at all is
+unchanged.
+
+**What to do.** Nothing, unless such a caller needs the field. A field's
+`requiredPermissions` name the capabilities that open it, so give the caller a
+permission set that holds all of them, or drop the requirement from the field.