Merge remote-tracking branch 'origin/main' into claude/issue-20193-dispatcher-meta-read-gate

Author: claude

.changeset/19328-install-door-body-parse.md

@@ -0,0 +1,108 @@
+---
+'@objectstack/runtime': minor
+---
+
+fix(runtime): `POST /api/v1/packages` parses the whole body through `PackageInstallBodySchema` instead of reading it key by key (#19328)
+
+Clause-②: no (narrowing)
+
+**BREAKING for callers of the install door.** The door now enforces the
+WHOLE install-body declaration. A body that `PackageInstallBodySchema` refuses
+is refused with `400` / `VALIDATION_ERROR` and installs nothing, whatever the
+reason. Every shape below used to answer `201`, and two of the install options
+used to be honoured. The list names the shapes a caller is most likely to have
+sent, and ends with one bullet for everything else the declaration states. For
+each one, change what you send FROM the refused shape TO the declared one:
+
+- **A manifest with no `type`, in either body form.** FROM
+  `{ "manifest": { "id": …, "name": …, "version": … } }` (or the same manifest
+  sent bare) TO the same manifest with a declared `type`: one of `app`,
+  `plugin`, `ui`, `driver`, `server`, `theme`, `agent`, `objectql`, `module`,
+  `gateway` or `adapter`, e.g. `"type": "app"`. It used to install anyway.
+- **A manifest with no `name`, in either body form.** `name` is the manifest's
+  other required key besides `id`, `version` and `type`. FROM
+  `{ "manifest": { "id": …, "version": …, "type": … } }` (or the same manifest
+  sent bare) TO the same manifest with `"name": "…"`, the human-readable
+  package name. It used to install anyway, because the door parsed only the
+  `id` and `version` legs.
+- **An unknown key inside the manifest, or on a bare body.** Example: a
+  transposed `namesapce`. FROM a manifest carrying the undeclared key TO the
+  manifest with that key removed, or spelled as the declared key it was meant
+  to be (`namespace`). The refusal names the key. The key used to be STORED
+  with the package.
+- **A string-typed `enableOnInstall` or `overwrite`.** FROM
+  `"enableOnInstall": "false"` / `"overwrite": "true"` TO JSON booleans,
+  `"enableOnInstall": false` / `"overwrite": true`. `'false'` used to install a
+  fresh package ENABLED, which is the opposite of what the caller asked for.
+  `'true'` for `overwrite` was read as absent, which answered `409` on an
+  installed id.
+- **Install options spelled on the BARE form (`enableOnInstall`, `overwrite`,
+  `settings`).** FROM `{ "id": …, …, "overwrite": true }` TO the wrapped form,
+  `{ "manifest": { "id": …, … }, "enableOnInstall": …, "overwrite": …,
+  "settings": … }`. `overwrite` may also go on the query string instead
+  (`?overwrite=true`), which a bare body may keep using. Before this change the
+  door handled these key by key: `enableOnInstall` was ignored, but
+  **`overwrite: true` and `settings` were HONOURED** (an installed id was
+  overwritten, and the settings reached the install). All three were also
+  stored as manifest keys. They are refused now. This is the part of the
+  change that removes behaviour a caller could have been relying on.
+- **Any other constraint `ManifestSchema` declares.** Each one is now enforced
+  at this door. Before, only the `id` and `version` legs were, and the manifest
+  was stored as sent. The constraints include:
+  - the `namespace` grammar: 2–20 characters, starting with a lowercase
+    letter, with only lowercase letters, digits and underscores;
+  - the closed value sets of `scope` (`cloud`, `system`, `project`),
+    `runtime` and `packaging`;
+  - the declared type of a key (for example a non-string `description`, or a
+    non-string version in `dependencies`);
+  - the retired manifest keys `configuration`, `capabilities`, `extensions` and
+    `loading`, which the declaration keeps only as named refusals;
+  - unknown keys inside the nested blocks the declaration closes. These are
+    `contributes` (and its `kinds[]`), `data[]` (each entry is a `SeedSchema`
+    seed), `navigationContributions[]` (and their items), `engine`, `engines`,
+    and the structured form of `permissions`.
+
+  FROM the off-declaration value TO the value the declaration states. The
+  refusal names the path.
+
+The accept set only shrinks back to what the published declaration has always
+said. `PackageInstallBodySchema` in `@objectstack/spec` is a union of two
+branches: the wrapped request, or a bare manifest as the whole body.
+`ManifestSchema` declares the manifest's required keys (`id`, `name`,
+`version`, `type`) and the grammar or value set of the rest. It closes the
+manifest, and the nested blocks listed above, against unknown keys.
+The wrapped request types `enableOnInstall` and `overwrite` as booleans. Its
+docblock says a bare manifest carries no install options: «a caller that needs
+an option sends the wrapped form». Until now, the door parsed only two legs of
+the manifest (`id` and `version`) and read every other key positionally off
+the raw body. That is «declared ≠ enforced» on a published API contract. Now
+the door parses the body once through the declared union and reads
+`overwrite`, `settings` and `enableOnInstall` off the parsed request. Nothing
+in `@objectstack/spec` moves, and neither branch of the union is relaxed.
+
+**What is not affected.**
+
+- A well-formed body installs exactly as before, in both forms and on both
+  install limbs (the protocol primitive and the bare-registry fallback).
+- The first-party SDK (`client.packages.install(m, { enableOnInstall,
+  overwrite, settings })`) already sends the wrapped form with JSON booleans.
+  Studio's create-package dialog sends `{ manifest }` with a declared `type`.
+- The manifest is stored as sent, with no parse-time defaults added.
+- The refusals for a missing or malformed `id` and `version` keep their own
+  sentences and still come first.
+- Every request-shape refusal is still answered ahead of the duplicate-id
+  `409`.
+- Boot-time and in-process installs reach `SchemaRegistry.installPackage` /
+  `ObjectQL.registerApp` directly and never pass through this door.
+
+**Still accepted, because the declaration accepts it.** An unknown key at the
+top level of the wrapped form (`{ manifest, bogus }`) is dropped, not refused.
+`PackageInstallRequestSchema` is declared in strip mode, and the door now does
+exactly what the declaration says.
+
+**If you are refused.** The refusal names the path of each failed constraint,
+and the form it read the body as. A misplaced install option also gets the wrapped form (and, for
+`overwrite`, `?overwrite=true`) spelled out. So the prescription arrives with
+the `400` rather than in a changelog.
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable is removed, renamed or reshaped: no spec key, no export, no stored row. `objectstack migrate meta` has nothing to reach, because there is no old spelling that maps to a new one — every refused shape is one the published declaration already refused, and a caller repairs it by sending the declared shape (a declared `type`, a `name`, the declared key or value, a JSON boolean, the wrapped form). The refusal itself carries the remedy. -->

.changeset/19995-judge-filter-read-scope.md

@@ -0,0 +1,19 @@
+---
+'@objectstack/service-analytics': patch
+---
+
+fix(service-analytics): the analytics ObjectQL face asks the engine's own filter admission about a row-level read scope before composing it, and refuses a scope the engine refuses with the policy withheld (#19995)
+
+Clause-②: no
+
+The ObjectQL execute face composes each object's read scope into the `where` it hands `engine.aggregate`. A scope the engine refuses through a door that reads the object's declared fields (a text operator over a field that never holds a string, a temporal comparand the field cannot read, a filter on a formula field, a dotted path through a lookup) came back as the engine's `INVALID_FILTER` or `INVALID_FIELD` / 400. Both analytics HTTP doors relay a 400's message, and that message named the policy's field, and for some classes its operator or comparand. A read-scope refusal is a server fault whose detail belongs in the server log only (the #5367 ruling), so these scopes now answer `READ_SCOPE_COMPILE_FAILED` / 500 with the message withheld, like the other refusals this package's read-scope compiler and guards raise. The `driver-sql` refusals that read the `'policy'` provenance mark are unchanged: they stay a withheld `INVALID_FILTER` / 400.
+
+**How.** The analytics face asks the engine's judge-only admission, `IObjectQLEngine.judgeFilter`, about the scope on its own before composing it. It asks at every engine-bound merge: the direct aggregate, both merges on the cross-object path, and the record-label lookup behind a lookup dimension. The engine runs the same admission it runs when it executes and stops before any driver, so a scope the engine serves is still served. The caller's own `where` is not judged here and keeps the engine's answer, including its 400 and message.
+
+**Also fixed.** The record-label lookup `AnalyticsServicePlugin` supplies for a lookup dimension composed the referenced object's scope with only the vacancy guard. When a dataset sorted by that dimension's labels, a scope the engine refused there came back as its 400, with the policy in the message. When a dataset only displays the labels, a failed lookup is caught and the raw ids render, as before. The lookup now runs the same checks as the other merges and answers the same withheld 500.
+
+**Wiring, and what a host without it keeps.**
+
+- `AnalyticsServicePlugin` wires the judge automatically when it bridges `executeAggregate` to the kernel's `data` engine itself. That is the default composition, so nothing changes in host code.
+- A host that constructs `AnalyticsService` directly can pass the new optional `AnalyticsServiceConfig.judgeFilter`. It must be the judgement of the engine its `executeAggregate` runs on.
+- A host with no judge (a custom `executeAggregate`, or a `data` engine without `judgeFilter`) keeps today's behaviour everywhere except the plugin's record-label lookup. The scope shapes this package judges itself are still refused with the policy withheld, and the rest reach the engine unjudged, as before. That lookup's comparand and placeholder checks are new for every host that uses it, with or without a judge. So on such a host a referenced-object scope that fails one of them now answers the withheld 500 at that lookup, where it used to reach the executor. The host logs one `warn` that no judge is wired, with the remedy.

.changeset/20045-inline-grid-column-currency-scale-refused.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/spec": minor
+---
+
+fix(spec)!: `scale` is refused on a `currency` inline grid column, and the column's `prefix` no longer promises a default symbol (#20045)
+
+Clause-②: no (narrowing)
+
+**BREAKING** — an accept-set narrowing on a published authoring surface, shipped as `minor` under the repo's launch-window convention for accept-set narrowings. An `inlineColumns` entry that declares `type: 'currency'` and `scale` — any value, `scale: 0` included, computed or not — no longer parses. The hand-migration prescription is registered under protocol major 18 as `inline-grid-column-currency-scale-refused`.
+
+A currency's decimal places are the currency's, not a setting. `scale` was already retired from the `currency` field type; the inline grid column, the strict mirror of the console grid's column, still offered per-column decimals on a currency column. It now follows the field.
+
+**`@objectstack/spec`** — `InlineGridColumnSchema` refuses `scale` on a column declaring `type: 'currency'`, with a located issue at the column's `scale`. The refusal opens with the currency field refusal's first sentence and carries its remedy: delete the key; the currency's ISO 4217 minor unit decides how the cell displays the amount and the width a computed amount is rounded to. The remedy names no other key to carry the value. No alias and no grace window. `scale` on a `number` column, and on a column that declares no `type`, is untouched, and the key's describe now names the currency refusal. The column's `prefix` describe no longer promises a `¥` default: it replaces the resolved currency's symbol, and when it is omitted the cell shows the symbol of the currency it resolves. `prefix` is still accepted on a currency column.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `inlineColumns: [{ name: 'amount', type: 'currency', computed: true, expr: 'quantity * unit_price', scale: 2 }]` | `inlineColumns: [{ name: 'amount', type: 'currency', computed: true, expr: 'quantity * unit_price' }]` |
+| `inlineColumns: [{ name: 'unit_price', type: 'currency', prefix: '$', scale: 2 }]` | `inlineColumns: [{ name: 'unit_price', type: 'currency', prefix: '$' }]` |
+
+The one-line fix: delete `scale` from every inline grid column that declares `type: 'currency'`. Nothing replaces it, so ⛔ do not re-declare the value under any other key. A `number` column keeps its `scale`.
+
+## Who is affected, measured
+
+On `origin/main` `1c8b320a89`: one authored `inlineColumns` block in the tree (the showcase invoice, seven identity-only columns, none declaring `type` or `scale`). No platform object, skill, documentation example or JSON fixture declares an inline grid column. One test fixture carried `scale: 2` on a currency column and was re-judged. Deployed metadata was not measured.
+
+<!-- adr-0087: registered inline-grid-column-currency-scale-refused -->