Merge remote-tracking branch 'origin/main' into claude/issue-20141-masked-field-types-declared

Author: claude

.changeset/17707-concurrent-limit-exceeded-retired.md

@@ -0,0 +1,27 @@
+---
+'@objectstack/spec': minor
+---
+
+**BREAKING** — `CONCURRENT_LIMIT_EXCEEDED` is removed from the closed `StandardErrorCode` catalogue (#17707).
+
+A `major`-class change, recorded as `minor` under the launch-window convention. ADR-0049 enforce-or-remove applied to the ADR-0112 error catalogue: ruling A on #17707, narrowed on 2026-09-24 to this code alone.
+
+**Why.** A catalogue member is the list callers branch on exhaustively, and a member with no producer teaches a branch that cannot fire. `CONCURRENT_LIMIT_EXCEEDED` had no producer behind it when the ruling was recorded, so it leaves the catalogue. Its neighbour `QUOTA_EXCEEDED` stays, unchanged, as the narrowing ruled.
+
+### FROM → TO
+
+| removed | what to write instead |
+| --- | --- |
+| `CONCURRENT_LIMIT_EXCEEDED` (`StandardErrorCode`, 429) | nothing — delete the branch. For request pacing branch on `RATE_LIMIT_EXCEEDED` (HTTP 429; wait `retryAfterSeconds` before retrying). A service that enforces its own concurrency limit registers a code for it in its own error-code ledger. |
+
+**The one-line fix: delete every branch on `CONCURRENT_LIMIT_EXCEEDED`.** A comparison against a value typed `StandardErrorCode` or `ErrorCode` no longer compiles (`TS2367`). At runtime the spelling now fails `StandardErrorCode`, `ErrorCode` / `ApiErrorSchema.code` and `makeApiErrorSchema(...)` parse, and the failure message is the removal prescription itself.
+
+**What stays.** The other `StandardErrorCode` members, `QUOTA_EXCEEDED` included, are unchanged.
+
+⚠️ **The out-of-repo consumer population is NOT MEASURED.** Inside this repository the code occurred only in the enum declaration, the hand-written error catalogue page, the generated reference pages and the unpinned-status baseline, and the pinned objectui checkout does not name it; `@objectstack/spec` is published, so readers elsewhere were not measured.
+
+The ADR-0087 D3 semantic entry `standard-error-code-concurrent-limit-exceeded-retired` carries the judgement: an error code is wire vocabulary, not a metadata key, so there is no authored source for a D2 conversion to rewrite.
+
+Clause-②: no
+
+<!-- adr-0087: registered standard-error-code-concurrent-limit-exceeded-retired -->

.changeset/18697-version-grammar-canon-semver.md

@@ -0,0 +1,120 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/runtime': minor
+---
+
+feat(spec)!: the canon for "the version of a package or plugin" is SemVer 2.0.0 — nine carriers, one grammar
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered manifest-version-semver-2-0-0, plugin-version-semver-2-0-0, package-version-row-semver-2-0-0, package-manifest-version-grammar-enforced -->
+
+**BREAKING** — four published accept sets converge on one, and the fringe each
+of them carried outside SemVer 2.0.0 is refused. The widening half needs no
+action from anyone; the narrowing half is listed per carrier below, with its
+FROM → TO.
+
+One concept was judged by four different grammars across ten carriers in two
+repositories, and the strictest refused `2.0.0-beta.1` — the exact string a
+sibling declaration documented as an example of itself. The disagreement was
+observable between doors on the same resource, not merely between schema files:
+`os plugin build` refused a prerelease the publish door accepted, the Studio
+form refused it twice over, the `PATCH` door answered `400`, and the install
+door parsed nothing at all. An earlier change collapsed the eight regex literals
+onto three exported constants, which removed the drift but not the disagreement.
+
+`@objectstack/spec/kernel` now exports ONE grammar —
+`SEMVER_2_0_0_VERSION_PATTERN`, semver.org's own published expression — and
+every carrier references it.
+
+## What every author gains, with no edit
+
+Prerelease and build suffixes are accepted on the five carriers that demanded a
+bare three-segment core, so `2.0.0-beta.1`, `17.0.0-rc.5`, `1.0.0+20230101` and
+`1.0.0-rc.1+exp.sha.5114f85` now pass a key that refused all of them. Identifiers
+are case-preserving everywhere, as the standard requires. This repository cuts
+prereleases of its own packages while the key describing a package could not
+express one; that ends here.
+
+```
+FROM  ManifestSchema.parse({ id: 'com.acme.crm', version: '2.0.0-beta.1', … })
+      -> throws                              // and `os plugin build` exits 1
+
+TO    ManifestSchema.parse({ id: 'com.acme.crm', version: '2.0.0-beta.1', … })
+      -> parses
+```
+
+## What stops being accepted, per carrier
+
+Eight strings, all of them forms SemVer 2.0.0 forbids and none of them a valid
+prerelease. What they have in common is that no precedence order exists for any
+of them — `dependency-resolver.ts` can place none in an order — so a package
+versioned this way could be published and never compared against its own
+successor.
+
+```
+FROM  version: '01.1.1'        TO  version: '1.1.1'     // §2 no leading zero in
+FROM  version: '1.01.1'        TO  version: '1.1.1'     //    a numeric identifier
+FROM  version: '1.1.01'        TO  version: '1.1.1'
+FROM  version: '1.0.0-0123'    TO  version: '1.0.0-123' // §9 no leading zero in a
+                                                        //    numeric prerelease id
+FROM  version: '1.0.0-alpha..1' TO version: '1.0.0-alpha.1'  // §9 no empty
+FROM  version: '1.0.0-alpha..'  TO version: '1.0.0-alpha'    //    identifier
+FROM  version: '1.0.0-.'        TO version: '1.0.0'
+FROM  version: '1.0.0+.'        TO version: '1.0.0'     // §10 no empty build id
+```
+
+⛔ Each repair above is one defensible reading and not the only one, which is
+why they ship as ADR-0087 D3 semantic TODOs rather than as mechanical D2
+conversions: a version is how a release is addressed, so rewriting one
+re-points whatever already resolved the old string. Run
+`objectstack migrate meta --from <N>` for the per-site list.
+
+Per carrier:
+
+- `ManifestSchema.version` and its three sibling declarations
+  (`MetadataPluginManifestSchema`, `PluginRegistryEntrySchema`,
+  `PluginMetadataSchema`), plus the `PATCH /api/v1/packages/:id` door: gain the
+  whole prerelease and build space; lose a leading zero in the numeric core.
+- `PluginSchema.version` and the plugin boot path in `@objectstack/core`: lose
+  those eight and **nothing else**. ⭐ Every valid prerelease and build form the
+  loader accepts today it still accepts, which is what keeps the widen-never-
+  narrow ruling on that path honoured rather than reversed; both halves of that
+  bound are pinned in `plugin.test.ts` and `plugin-loader.test.ts`.
+- `PackageVersionSchema.version`: gains case-preserving identifiers
+  (`1.0.0-Beta.1`, `1.0.0+Build.5`), which the boot path has always accepted and
+  this key alone refused; loses the same eight.
+- `PackageManifestSchema.version`: was a bare `z.string()` constraining nothing,
+  so it is the one carrier where the grammar is entirely new. `latest`,
+  `v1.0.0`, `1.0`, the empty string and `2.0.0-beta.1extra!` were accepted and
+  frozen into a published manifest snapshot; each is refused now. A dist-tag
+  becomes the version it pointed at, a `v`-prefix drops, a two-segment string
+  gains its patch.
+
+## The prose moved with the grammar
+
+Every `.describe()` names SemVer 2.0.0 and the nine generated reference-doc rows
+follow; the `PATCH` door's refusal says so; `manifest.test.ts`'s
+「should enforce semantic versioning」 case stops listing `1.0.0-beta` among the
+invalid versions. `PluginLoader.isSemverShapedVersion` becomes `isSemverVersion`
+— a predicate named for a standard it does not implement gets misused by the
+next caller whatever its docblock says, and the name is true now.
+
+Three exported constants are retired, each replaced by the one canon:
+
+```
+FROM  import { MAJOR_MINOR_PATCH_VERSION_PATTERN } from '@objectstack/spec/kernel'
+FROM  import { SEMVER_SHAPED_VERSION_PATTERN } from '@objectstack/spec/kernel'
+FROM  import { SEMVER_SHAPED_LOWERCASE_VERSION_PATTERN } from '@objectstack/spec/kernel'
+TO    import { SEMVER_2_0_0_VERSION_PATTERN } from '@objectstack/spec/kernel'
+```
+
+⛔ They are not interchangeable with what they replaced — each named an accept
+set that no longer exists, which is why they are retired rather than aliased. A
+consumer that referenced one to REPRODUCE a verdict gets the canon's verdict
+now; one that referenced it to match a foreign grammar owns that grammar itself.
+
+The accept set is pinned witness by witness in `version-grammar.test.ts`: move a
+cell there and you have moved a published accept set on nine carriers at once,
+in one visible edit.

.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/20143-like-underscore-code-point.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/spec": minor
+"@objectstack/formula": minor
+"@objectstack/driver-memory": minor
+---
+
+`$like` / `$ilike`: `_` matches exactly one Unicode code point on every face, so an emoji or any other character outside the Basic Multilingual Plane is one `_`, as SQL `LIKE` and SQLite `GLOB` count it (#20143).
+
+The SQLite faces (`driver-sql` on better-sqlite3, `driver-sqlite-wasm`, `driver-turso` local and remote) already answered by code points. The JavaScript faces did not: they compiled the spec's `likePatternToRegexSource` with no regular-expression flags, so `_` read one UTF-16 code unit, which is half of an emoji. The same REST filter returned a different row set depending on which driver backed the object. Measured at `e7f69dbb` over values holding `😀` (U+1F600) and `𝒜` (U+1D49C), 48 answer cells on the JS faces differed from the SQLite faces; after this change, none do.
+
+- **`@objectstack/spec`**: a new export, `likePatternToRegExp(pattern, foldAscii?)`, compiles the translation with the `u` flag, the one compilation in which `_` is one code point. `matchesLikePattern` evaluates it. `likePatternToRegexSource` is unchanged and still exported; its source means one code point per `_` only under `u`. The `$like` description now says that a character is one Unicode code point.
+- **`@objectstack/formula`**: `matchesFilterCondition` answers `$like` / `$ilike` by code points, through the spec's `matchesLikePattern`. Its own CEL `size()` already counted code points.
+- **`@objectstack/driver-memory`**: all three `$like` doors (the `$like` filter and the AST `like` / `ilike` node through mingo, and the reference matcher) answer by code points.
+
+The answer set moves in both directions on those three faces, only for values holding a character outside the BMP:
+
+| pattern | a stored `😀` | `a😀b` | `a😀😀b` |
+|---|---|---|---|
+| `_` | now matches | — | — |
+| `__` | no longer matches | — | — |
+| `a_b` | — | now matches | — |
+| `a__b` | — | no longer matches | now matches |
+
+`$ilike` moves the same way. No pattern is newly refused and no refusal is lifted. Values made only of characters inside the BMP answer exactly as before.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing an author writes is removed or renamed: no spec key, no export and no config field moves, and no stored metadata representation changes, so `objectstack migrate meta` has nothing to rewrite. What moves is the row set a `$like` / `$ilike` query returns on the JavaScript faces, and only for stored values holding a character outside the BMP, where it now equals what every SQLite face already returned. -->

.changeset/20176-aggregation-temporal-storage-rule.md

@@ -28,7 +28,7 @@ What the rule does, now in one place:
 - A value the rule cannot read is compared as written, and so is every non-temporal column, presence tests (`$exists`, `$null`), the text operators and a `{ $field }` reference.
 - An object whose declared fields the engine cannot see keeps the previous comparison.
 
-`@objectstack/core` exports the rule as `temporalStorageForm(value, kind)`, `kind` being `'datetime' | 'date' | 'time'`. `driver-sql` (`canonicalUtcDatetime`, `toDateOnly`, `canonicalTimeOfDay`) and `driver-memory` (`coerceTemporalValue`) each carried a copy of it; both now call it. The copies agreed on every shape measured when they were lifted, so no `where`, write or read answer of either driver changes. MySQL still binds a `datetime` in its own literal spelling.
+`@objectstack/core` exports the rule as `temporalStorageForm(value, kind)`, `kind` being `'datetime' | 'date' | 'time'`. `driver-sql` (`canonicalUtcDatetime`, `toDateOnly`, `canonicalTimeOfDay`) and `driver-memory` (`coerceTemporalValue`) each carried a copy of it; both now call it. The copies agreed on every shape measured when they were lifted, so the lift itself changes no `where`, write or read answer of either driver (#20203, in the same release, then reads an epoch-millisecond number on a `date` field as its UTC calendar day). MySQL still binds a `datetime` in its own literal spelling.
 
 `@objectstack/objectql`'s `applyInMemoryAggregation(rows, ast, timezone?, fields?)` takes the object's declared field map as an optional fourth argument, and a per-aggregation `filter` reads a temporal comparand by the rule only when it is given. Called without it, the function answers as before.