Merge remote-tracking branch 'origin/main' into claude/issue-20361-shard-liveness-counts

# Conflicts:
#	packages/spec/liveness/state-counts.md

Author: claude

.changeset/20233-field-export-api-dataset-hook-metadata-migration-guidance-tracker-free.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): `os migrate meta` guidance for the `field-*`, `export-*`, `api-*`, `dataset-*`, `hook-*` and `metadata-*` migration entries states each lesson in words instead of citing tracker numbers
+
+Clause-②: no
+
+The ADR-0087 semantic entries of the `field-*` family (the runtime `field` write door, the
+`maxLength` / `minLength` / `scale` / `precision` refusals, `scale` on a currency field,
+`multiple` on a type that holds one value, and predicates that read through a reference),
+the `export-*` family (the export permission axis, the eight constraint keys retired from
+`ExportFieldMeta` and the retired export-job API family), the `api-*` family (the runtime `api` write door,
+the split API entry and two duration keys renamed with their unit), the `dataset-*` family
+(the aggregate × field-type refusals and the nested-relation list refused at save), the
+`hook-*` family (the retired hook-session `roles` and the two `registerHook` refusals) and
+the `metadata-*` family (the retired customization protocol, the re-partitioned endpoint
+switches, the metadata-manager cache keys and the retired `additionalTypes`) are printed by
+`os migrate meta` as the header, `why:` and `verify:` lines of a manual change. Their text
+sent the reader to issue-tracker, decision-batch and ruling-record numbers — some of which
+no longer resolve, and some in another repository — for what a ruling, measurement or fix
+had decided; it now says what was decided, in the sentence being read. ADR ids are kept.
+
+Text only: no entry id, `from` / `to`, conversion or matching logic changes, and the chain
+rewrites exactly what it rewrote before. One entry's `surface` (the header line of
+`dataset-measure-aggregate-field-type-refused`) drops the two tracker numbers it carried and
+names nothing else differently. The generated migration registry, `spec-changes.json` and
+the protocol upgrade guide carry the same text.

.changeset/20294-openapi-info-publisher-overlay.md

@@ -0,0 +1,91 @@
+---
+'@objectstack/spec': minor
+'@objectstack/rest': minor
+---
+
+feat(spec,rest)!: the served OpenAPI `info` carries the publisher's `api.documentation` identity; `api.documentation.version` retired (#20294)
+
+Clause-②: yes (narrowing)
+
+**BREAKING** — shipped as `minor` under the launch-window convention
+(`check-changeset-no-major` refuses `major` until GA; breaking-ness is carried by
+this banner, the `(narrowing)` arm above and the ADR-0087 disposition below,
+never by the level). The breaking half is one key: `api.documentation.version`.
+
+`RestServerConfig.api.documentation` (`RestApiConfigSchema`) declared nine
+members, and `RestServer` parsed them, copied them into its config — and never
+read them back. Measured before this change, with every member authored: both
+doors that serve the OpenAPI document (`{apiPath}/openapi.json` and its
+environment-scoped twin) answered the bundled artifact's `info` unchanged, 0 of 9
+honoured. ADR-0049 enforce-or-remove, split by who owns each field:
+
+- **Enforced — the publisher's identity.** `title`, `description`,
+  `termsOfService`, `contact` (`name` / `url` / `email`) and `license` (`name` /
+  `url`) now overlay the served `info` on both doors. A member you leave unset
+  keeps the bundled value, and a config with nothing authored — no block,
+  `documentation: {}` — serves `info` byte-identical to
+  `@objectstack/spec/openapi.json`, exactly as before. `contact` and `license`
+  replace the bundled object **whole**: `license: { name: 'MIT' }` serves
+  `{ name: 'MIT' }` with no URL, never MIT at the bundled Apache-2.0 URL, and a
+  partial `contact` never keeps ObjectStack's name or URL.
+- **Retired — `documentation.version`.** The served `info.version` is the
+  protocol version, the version of the `@objectstack/spec` package that generated
+  the document, with no configured override: an earlier ruling made it equal the
+  published artifact's so an integrator can read which protocol version they are
+  talking to. A publisher-set version would give the field a third meaning, so
+  the key is now refused.
+
+```
+FROM  new RestServer(server, protocol, { api: { documentation: { title: 'Acme Orders API', version: '2.3.0' } } })
+      -> constructed; GET /api/v1/openapi.json served info.title 'ObjectStack REST API'
+         and info.version = the spec version — both authored values ignored
+TO    -> throws: REST API configuration is invalid: `api` does not satisfy
+         `RestApiConfigSchema` …
+           - api.documentation.version: `api.documentation.version` was removed in
+             @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — … Delete the key. To publish
+             your app's own release number, write it into `api.documentation.description`, …
+
+FROM  new RestServer(server, protocol, { api: { documentation: { title: 'Acme Orders API' } } })
+      -> GET /api/v1/openapi.json: info.title 'ObjectStack REST API'
+TO    -> GET /api/v1/openapi.json: info.title 'Acme Orders API' (and on the environment-scoped door)
+
+FROM  RestApiConfigSchema.parse({ documentation: { description: 'd' } }).documentation
+      -> { title: 'ObjectStack API', description: 'd' }   // a default no document ever served
+TO    -> { description: 'd' }
+```
+
+**Fix.** `api.documentation.version` → delete the key. The served
+`info.version` is always the protocol version; to publish your app's own release
+number, write it into `api.documentation.description`. `tsc` refuses the key at
+the authoring site (its input type is `never`), and `RestServer` construction and
+the REST plugin's `start` refuse it with that prescription.
+
+**What else changes.** `documentation.title` is `.optional()` instead of
+`.default('ObjectStack API')`: that default was materialized into every present
+block and never served, so the parsed block now carries exactly what was
+authored (the parsed `title` is typed `string | undefined` now). `api.version` (the route identifier) and the runtime version still
+never reach `info.version`. A host that authors none of these keys — every
+CLI-started deployment, since `os serve` forwards only `enableProjectScoping`
+and `projectResolution` — serves the same document as before.
+
+### The kit
+
+- **Schema.** The eight identity members carry describes naming the served
+  `info` field; `version` is a `retiredKey()` tombstone inside the live
+  `documentation` block (a non-strict `z.object()`, so a bare deletion would have
+  stripped it in silence), next to the `enabled` tombstone.
+- **REST server.** `registerOpenApiEndpoints` builds `info` through a pure
+  helper that returns a NEW object — the cached artifact's own `info` is never
+  written — and the same handler serves both doors.
+- **ADR-0087.** `RETIRED_KEYS_BY_MAJOR[18]` gains
+  `api/RestApiConfig:documentation.version`; the D3 entry
+  `rest-api-documentation-version-retired` carries the prescription to
+  `os migrate meta` and the upgrade guide. No D2 conversion: a `RestServerConfig`
+  is plugin TS configuration, never a stack collection member or a stored row.
+- **Ledger and docs.** `liveness/rest_api.json`: the eight identity leaves and
+  the `contact` / `license` containers flip to `live` with the overlay as
+  evidence; the `version` row stays `dead` with a REMOVED note. The generated
+  `state-counts.md` moves `rest_api` from 12 live / 12 dead to 20 / 4; the
+  `rest-server` reference page is regenerated.
+
+<!-- adr-0087: registered rest-api-documentation-version-retired -->

.changeset/20397-diff-default-range-labels.md

@@ -6,6 +6,6 @@ fix(metadata-protocol): `diffMetaItem`'s default range labels its to side with t
 
 With no `toVersion`, the to side is the current active `sys_metadata` row. Its body was compared, but `toVersion` came from the newest `sys_metadata_history` row, which is a draft save whenever a draft is pending: every draft save appends a history row. The labels and the bodies then named different rows. Measured on the real REST stack, an app with one active save and two draft saves answered `fromVersion 2 → toVersion 3` over its version-1 body, and a view with one active save and one draft save answered "no changes" labelled `1 → 2` while version 2 differs.
 
-- **Now:** `toVersion` is the active row's own `version`, read in the same read as its body. The default `fromVersion` is still the history version immediately before that label. An item whose active row is version 2 with a draft pending answers `1 → 2`, the same answer as `?from=1&to=2`.
+- **Now:** `toVersion` is the active row's own `version`, read in the same read as its body. The default `fromVersion` rule is not changed by this entry (#20451, in the same release, then moves it to the nearest earlier version whose body differs from the to side's). An item whose active row is version 2 with a draft pending answers `1 → 2`, the same answer as `?from=1&to=2`.
 - **No active row** (a draft-only item, or a deleted one): the to side is absent, and both labels are `null` with empty buckets, as the response schema declares for an absent side. Before, a draft-only item was labelled with its newest draft save, and its from side could be an earlier draft save's body. A deleted item was labelled `N-1 → N` up to its tombstone. That deletion is still read by naming its versions (`?from=N-1&to=N`).
 - Unchanged: the response shape, explicit `from` / `to` ranges, and the default range of an item with no draft pending.

.changeset/20444-empty-operator-engine-arms.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/driver-sql': minor
+'@objectstack/driver-turso': minor
+'@objectstack/driver-memory': minor
+'@objectstack/driver-mongodb': minor
+'@objectstack/formula': minor
+'@objectstack/objectql': minor
+'@objectstack/spec': minor
+---
+
+feat(drivers,formula,objectql): the engine's filter faces answer the staged `$empty` operator (#20444)
+
+Clause-②: yes (widening)
+
+`$empty: true | false` is declared by `@objectstack/spec` (`FieldOperatorsSchema`) with a per-type meaning: a text-like field is empty when it is null or `''`, a multi-value field (multiselect, checkboxes, tags, or a select / radio / lookup / user / file / image with `multiple: true`) when it is null or `[]`, and every other type only when it is null. `$empty: false` is the exact complement. Until now every face in this list refused it (`INVALID_FILTER` / 400), except `matchesFilterCondition`, which answered `false` for every record. **A driver or evaluator called directly now answers it:**
+
+- **By the field's declared type**, through the spec's one expansion (`expandEmptyOperator`): `driver-sql`'s filter compiler (and so `driver-sqlite-wasm` and `driver-turso`'s local transport, which inherit it), `driver-turso`'s remote transport, `driver-memory`'s query path (`find` / `count` / `update` / `delete`) and `driver-mongodb`'s `translateFilter` (its `find`, its aggregate `$match`). The declaration is the one each driver already receives — `initObjects` / `registerObjectMetadata` / `registerExternalObject` on the SQL family, `syncSchema` on the others. On SQL a multi-value field's empty list is tested as stored JSON per dialect (SQLite `json_array_length` behind a `json_valid` guard, PostgreSQL a `jsonb` comparison, MySQL `JSON_LENGTH`), never as an equality comparand.
+- **By value** — null, a missing value, `''` and `[]` are empty (`isEmptyFilterValue`) — on the faces that read no field declaration: `@objectstack/formula`'s `matchesFilterCondition` (the RLS write-side `check`), `driver-memory`'s reference matcher, and `@objectstack/objectql`'s `having` and per-aggregation `filter`. In `having`, a `count` or `sum` holding `0` is not empty.
+
+**Refused, never guessed** (`INVALID_FILTER` / 400): `$empty` on a field whose declaration the driver does not hold (a table built outside its registration, a builtin column such as `id`, a field with no `type`, or `translateFilter` / `RemoteTransport` used standalone without a declaration), a multi-value field on a SQL dialect the driver does not model, and a flag that is not a boolean. `driver-memory`'s analytics (cube) face refuses `$empty` as an operator it cannot compile, as it does `$null`.
+
+New optional API: `translateFilter(where, temporalKind?, valueShape?)` in `@objectstack/driver-mongodb` takes a declared-value-shape resolver (type `ValueShapeResolver`), and `buildAggregationPipeline` a `valueShape` option; `RemoteTransport.setDeclaredValueShapeResolver` in `@objectstack/driver-turso`, which `TursoDriver` wires. `@objectstack/spec`'s shared `FILTER_LOGIC_CASES` table gains seven `$empty` cases: a backend that runs it answers `$empty` or goes red, and its harness must declare the fixture's columns.
+
+`$empty` stays staged: it is not in `FILTER_OPERATORS`, so the engine's front door still refuses it until the flip card adds it, and the view operators `is_empty` / `is_not_empty` still lower to `$null`.

.changeset/20451-diff-default-from-differs.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/metadata-protocol': patch
+'@objectstack/rest': patch
+---
+
+fix(metadata-protocol): `GET /meta/:type/:name/diff` with no `from` compares against the nearest earlier version whose body differs, so the default diff right after a publish shows what the publish changed (#20451)
+
+Clause-②: no — no key, export, route, parameter or response field moves; only which version the default `from` side names.
+
+Every draft save appends a `sys_metadata_history` row, and publishing the draft appends the same body again as the next row. The default `from` side was the history row immediately before the `to` side, so right after a publish it was the draft save the publish came from, and the default diff answered "no changes". The change the publish carried was reachable only by naming `?from=`.
+
+- **Now:** with no `from`, `diffMetaItem` walks back from the `to` side over the history rows it already reads and takes the nearest earlier row whose body differs, by the diff's own equality (all three buckets empty means equal). A body-less row, a delete's, compares as an empty body, so the walk stops on it and the answer names the deletion. With no earlier row that differs, the `from` side is absent: `fromVersion: null`, everything added.
+- **Measured on the real REST stack**, before → after:
+
+| history | default range before | default range now |
+|:--|:--|:--|
+| v1 active, v2 draft save, v3 publish | `2 → 3`, no changes | `1 → 3`, the change the publish carried |
+| the same with a v4 draft pending | `2 → 3`, no changes | `1 → 3` |
+| create, delete, draft save, publish | `3 → 4`, no changes | `2 → 4`, everything added |
+| create, delete, active recreate | `2 → 3`, everything added | unchanged |
+| a new item draft-saved, then published | `1 → 2`, no changes | `null → 2`, everything added |
+| a single version | `null → 1`, everything added | unchanged |
+
+- **Unchanged:** an explicit `?from=` / `?to=` names exactly its versions (`?from=2&to=3` over the first row still answers "no changes"); the default `to` side is the active version; the response shape; the one history read, with no cap. The walk compares the stored bodies before redaction, as the diff itself does, so a credential-only change still stops it and its values are still not served.
+- `@objectstack/rest`: the route's OpenAPI summary states the new default.

.changeset/20492-uninstall-refuse-before-mutate.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/runtime': patch
+'@objectstack/spec': patch
+---
+
+fix(runtime): `DELETE /packages/:id` refuses an uninstall that names no organization before it touches the running registry (#20492)
+
+Clause-②: no
+
+A caller holding `manage_metadata` with no active organization — a member removed from an organization whose session still names it, or a caller who never selected one — sent `DELETE /api/v1/packages/:id` and was answered `400 TENANT_SCOPE_REQUIRED`. The dispatcher had already run the registry uninstall by then, so the package and every object it registers had left the running process for everyone it serves, while its stored rows still said it was installed. The state lasted until a restart re-seeded the registry.
+
+The door now asks the persisted delete's organization-scope question first, from the same organization value it hands `deletePackage`, and only when a persisted delete will run. The same refusal (`400 TENANT_SCOPE_REQUIRED`) now arrives before anything changes: the package stays served, listed and registered, and its stored rows are untouched. The refusal's message names what an HTTP caller can do, which is to select an organization they are a member of and retry.
+
+- **Unchanged:** a caller acting in an organization uninstalls exactly as before. A read-only package is still refused `422 WRITABLE_PACKAGE_REQUIRED` first. A host with no persisted delete (no `deletePackage` on its `protocol` service) still uninstalls from the registry alone, because there is no refusal to mirror there. The protocol keeps its own refusal as a second line.
+
+- **`@objectstack/spec`:** `PROVENANCE_WAIVERS` (the error-code ledger) gains one entry: `@objectstack/runtime` stamps `TENANT_SCOPE_REQUIRED`, which stays registered under `@objectstack/metadata-protocol`. The door mirrors `deletePackage`'s refusal and does not emit a second vocabulary. The registered code union and `ErrorCode` are unchanged.

.changeset/20494-milestone-type-default-describe.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/spec': patch
+---
+
+`activityMilestones[].type`'s `.describe()` now states the real default: an unset `type` keeps the update row's kind, `updated` (#20494)
+
+Clause-②: no
+
+No behaviour changes and no schema shape change. `object.zod.ts`'s `activityMilestones[].type` field described its default as `"completed"`; the runtime never wrote that. `audit-writers.ts` starts `activityType` from `activityTypeFor(action)`, and a milestone can only fire on the UPDATE branch (`create` / `delete` return their own summary before the milestone match ever runs), so an unset `type` has always emitted `updated`. `milestone.type` overrides it only when the author actually sets it — that half of the describe was correct and is unchanged.
+
+The corrected string is the published half: it ships in `packages/spec/dist/*.d.ts`, in the JSON Schema under `packages/spec/json-schema/`, and in the generated `content/docs/references/data/object.mdx` (regenerated with `gen:docs`, never hand-edited). A repo-wide search for the old wording found no other hand-written copy; `object.form.ts`'s `activityMilestones.type` help text ("Unset: updated.", shipped with PR #20485) already stated the real default and is unchanged.
+
+`packages/plugins/plugin-audit/src/activity-type-vocabulary-enforcement.test.ts` already measured the runtime's real answer — its title and docblock are corrected in the same PR to stop describing a divergence and stop saying the finding was "filed separately" (this card, #20494, is where it was filed). Its assertions are byte-for-byte unchanged.