Merge origin/main into claude/issue-20887-analytics-nested-relation

main's #20931 (the field-read admission gate), #20955 (the queryable-field
gate), #20954 (plugin-security's comparand guard) and #20962 (relationship
path objects in the admitted and scoped set) touched
packages/services/service-analytics. The merge is clean at the text level;
both sides' additions to analytics-service.ts and native-sql-strategy.ts are
kept whole.

Claude-Session: https://claude.ai/code/session_01XY5uCwTjZj7884yYtyur4H
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/20313-use-grouping-live.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': patch
+---
+
+The `field` liveness ledger grades `useGrouping` `live`, and the key's docblock stops describing a grouping heuristic the renderer does not use
+
+Clause-②: no
+
+A number field's authored `useGrouping` is honoured by the console this release builds against:
+an authored `true` or `false` decides whether the value renders with thousands separators, and an
+absent key keeps the renderer's interim rule. The `liveness/field.json` row therefore moves from
+`planned` to `live`, citing the objectui reader and the sites that carry the key to the number
+cell, and `liveness/state-counts/field.md` is regenerated to match. The `FieldSchema.useGrouping`
+docblock in `src/data/field.zod.ts` said the interim rule looked at a field's `min` / `max`
+bounds, and that the renderer half had not landed; both are corrected: the rule reads only a
+declared `scale: 0` (ungrouped) against any other `scale` or none (grouped), and the renderer half
+reads an authored value first. Text and ledger only: the schema, its `.describe()` string, every
+export and all runtime behaviour are unchanged.

.changeset/20513-seven-packages-runtime-strings-state-the-decision.md

@@ -0,0 +1,38 @@
+---
+'@objectstack/core': patch
+'@objectstack/driver-memory': patch
+'@objectstack/driver-mongodb': patch
+'@objectstack/formula': patch
+'@objectstack/metadata': patch
+'@objectstack/metadata-core': patch
+'@objectstack/objectql': patch
+'@objectstack/platform-objects': patch
+---
+
+Refusals, log lines and field help in core, the in-memory and MongoDB drivers, formula, metadata, metadata-core, objectql and platform-objects no longer cite tracker numbers; each states the reason in words
+
+Clause-②: no
+
+Many messages these packages show to authors, administrators and operators ended with an issue-tracker
+number where the reason belonged. The number goes, and where the sentence did not already say what was
+decided, it now does. Where an ADR stood beside the number, the ADR stays.
+
+- Refusals and prescriptions: the retired health-check keys, the `IMetadataService.register` refusals
+  (the contract refuses loudly and names the mismatch, never coerces a value into storability), the
+  kernel's plugin-ordering errors (registration order is not a contract), the in-memory and MongoDB
+  filter and aggregation refusals, formula's empty field constraint, the retired `artifact-api`
+  source, and the by-id update and delete refusals. The MongoDB retired-aggregate refusal now says the
+  function left `AggregationFunction` because no SQL backend compiled it; its undeclared-aggregate
+  refusal says the builder used to sum an unrecognised name before this refusal existed.
+- The `findOne` no-predicate refusal loses its citation in `objectql` and in `metadata-core`'s
+  `engineFindOnePredicateRefusalMessage` together, so the two still read byte for byte the same.
+- The in-memory and MongoDB drivers' multi-tenancy refusals (`MEMORY_MULTI_TENANT_UNSUPPORTED`,
+  `MONGODB_MULTI_TENANT_UNSUPPORTED`) no longer end with a `Tracking:` line linking a tracker card;
+  the sentence above it already says the driver refuses rather than run or answer unisolated.
+- Field help and protection text: the `sys_account` token help (and its es-ES, ja-JP and zh-CN
+  translations), the `sys_email` headers help and the SCIM credential store's protection reason.
+- Log lines: the superseded-registration warning, the authz cache posture line, the endpoint matcher's
+  excluded-item error, the metadata history and loader-read failure errors, and the fresh-datastore
+  attestation info lines.
+
+Text only: no error code, field name, status or behaviour changes.

.changeset/20583-refusal-conversions-json.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/cli": patch
+---
+
+**When a `defineStack` or `composeStacks` call converts a deprecated spelling and then refuses the config, `objectstack validate --json`, `objectstack build --json` and `objectstack lint --json` now report both the refusal and the ADR-0087 conversions it applied.**
+
+`defineStack` rewrites a deprecated metadata spelling to its canonical shape when the config loads, such as `description` on a `page:header` component (canonical `subtitle`). When the same call then refused the config, for example on an unknown `requires` token (`STACK_CAPABILITY_UNKNOWN`), each of the three commands exited 1 with the refusal's `error` and `code` and with `conversions: []`. The conversion reached stderr only, as a warn-once line.
+
+The refusal now carries the conversions the producer applied before it refused (`stackConversionsOf(error)` in `@objectstack/spec`), and each command adds them to the `conversions` list of its failure payload, beside the refusal. Each conversion is listed once. A refusal whose source needed no conversion, and any other failure at load, still answers `conversions: []`.
+
+Nothing is accepted or refused differently: the exit code, `error`, `code` and every other key of each payload are unchanged, and no key is added. The text face is unchanged.
+
+Clause-②: no

.changeset/20594-cli-bin-provenance-anchors.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/cli': patch
+---
+
+Provenance comments in `@objectstack/cli`'s `bin/run.js` were re-anchored
+
+Three docblock lines above `bin/run.js`'s `process.stderr` `error` listener
+cited a tracker number that no longer resolves on GitHub. They now cite the
+commit in this repository's history that made a failed stderr write non-fatal
+on the dev shim. The file ships because npm packs a `bin` target regardless of
+`files`, which is why this is a release note at all. Comment only: no command,
+flag, exit code, error code, export or runtime behaviour changes.

.changeset/20602-export-year-four-digits.md

@@ -0,0 +1,26 @@
+---
+'@objectstack/rest': patch
+---
+
+fix(rest): `GET /api/v1/data/:object/export` writes a `date` or `datetime` cell with a four-digit year, so an export of a year from 0001 to 0999 re-imports (#20602)
+
+Clause-②: no
+
+A `date` of `0500-01-01` exported as `500-01-01`, in CSV, xlsx and JSON alike,
+and so did the day of a `datetime` cell whose business-timezone day fell before
+year 1000: the instant `1000-01-01T02:00:00.000Z` exported in America/New_York
+as `999-12-31 21:03:58`. `POST /api/v1/data/:object/import` reads a four-digit
+year only, so re-importing the platform's own file refused that row as
+`invalid_date`. The export now spells every `date` and `datetime` cell's day
+with the storage rule the write doors use (`temporalStorageForm` from
+`@objectstack/core`): `0500-01-01` and `0999-12-31 21:03:58`, which the import
+reads back as the same day and the same instant.
+
+**What is not affected.** Every cell whose day falls in the years 1000 to 9999
+exports byte for byte as before, in every business timezone and with none. The
+clock of a `datetime` cell is unchanged. A `datetime` stored before year 1000,
+which the write doors now refuse, exports with a padded year as well, and the
+import refuses it as `invalid_date`, as the write doors do. A year outside 0001
+to 9999 stays unpadded, and a `datetime` whose business-timezone day falls in
+such a year now spells that year as the storage rule does (`0-12-31`, not the
+era year `1-12-31`); the import refuses both spellings, as before.

.changeset/20701-import-row-not-null-and-unique-door-answer.md

@@ -0,0 +1,27 @@
+---
+'@objectstack/rest': patch
+---
+
+fix(rest): an import row for a NOT NULL refusal or a unique conflict answers what the create door answers (#20701)
+
+**`POST /api/v1/data/:object/import` and the async import job — a NOT NULL
+refusal.** When the database refuses a row because a NOT NULL column has no
+value (for example a field declared `storage: { notNull: true }` and not
+`required`, which the engine's own check lets through), the committed row
+now fails with `code: 'required'`, `field` set to the field, and the sentence
+`POST /api/v1/data/:object` gives for it ("f is required"). It used to fail with
+the database's own code (`SQLITE_CONSTRAINT_NOTNULL` on SQLite) and no `field`.
+The create door answers `400 VALIDATION_FAILED` with a `required` finding for
+the field; the row reports that finding the way it reports a `required` field
+the engine refuses itself, so no database dialect's code reaches the row.
+
+**A unique conflict.** A committed row that repeats a unique value keeps
+`code: 'UNIQUE_VIOLATION'` and its `field`, and now carries the create door's
+sentence, "A record with this f already exists", in place of the engine's longer
+sentence (which the create door returns as `developerMessage`).
+
+The async job's rows, read from `GET /api/v1/data/import/jobs/:jobId/results`,
+change the same way. The row takes these answers from the same mapper as the
+create door, as it already does for a missing database column. No key is added
+to the row. The dry run still previews such rows as `ok`, because it checks the
+metadata and does not judge `storage.notNull` or uniqueness.

.changeset/20701-import-row-schema-drift-door-answer.md

@@ -0,0 +1,21 @@
+---
+'@objectstack/rest': patch
+---
+
+fix(rest): an import row for a missing database column answers what the create door answers (#20701)
+
+**`POST /api/v1/data/:object/import` and the async import job.** When an object
+declares a field whose database column is missing (the schema has drifted from
+the metadata), a committed row that writes that field now fails with
+`code: 'INVALID_FIELD'`, `field` set to the field, and the sentence
+`POST /api/v1/data/:object` gives for the same key: "The database table of
+object 'X' has no column for field 'f'. If the object declares 'f', its database
+schema has drifted from the metadata: run 'os migrate' to reconcile." It used to
+fail with the database's own code and text (for example `SQLITE_ERROR` and
+`table X has no column named f`) and no `field`. The async job's rows, read from
+`GET /api/v1/data/import/jobs/:jobId/results`, change the same way.
+
+The row now classifies a write error through the same mapper as the create door,
+and takes that answer when it is `INVALID_FIELD`. The dry run still cannot see a missing column,
+because it checks the metadata and not the table, so it previews such a row as
+`ok`.

.changeset/20819-regime-c-refusal-path.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): the refusal of an in-place edit or removal of a packaged flow names the clone and the on/off switch, not a redeploy or `OS_METADATA_WRITABLE` (#20819)
+
+Clause-②: no
+
+A write or removal that targets a flow shipped by a code package, and does not name that package, is refused with `403 NOT_OVERRIDABLE`. That covers `PUT /api/v1/meta/flow/:name` without `?package=`, `DELETE /api/v1/meta/flow/:name`, `PUT` and `DELETE /api/v1/automation/:name`, and `POST /api/v1/automation` onto a packaged flow's name. The refusal used to say "Edit the source artifact and redeploy, or set OS_METADATA_WRITABLE to grant a runtime escape hatch", and cited ADR-0005. The administrator of an installed package can do neither.
+
+The refusal now names the two paths ADR-0126 sanctions for a packaged flow, and cites ADR-0126:
+
+- clone it under a new name to customize it: `POST /api/v1/automation/:name/clone` with `{ name, label }`;
+- or switch it off: `POST /api/v1/automation/:name/toggle` with `{ enabled: false }`. Where one install serves several organizations, only the platform operator can use the switch.
+
+The status, the code and which writes are refused are unchanged. `OS_METADATA_WRITABLE=flow` still opens the lock as before; the refusal just no longer suggests it. Every other metadata type's refusal reads exactly as before. A write that names the shipping package with `?package=` is refused with `403 ITEM_LOCKED` by a separate limb, which this change leaves as it was.

.changeset/20822-f3-route-then-delete.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/metadata': patch
+'@objectstack/objectql': patch
+'@objectstack/driver-memory': patch
+---
+
+fix: the whole-day bound on a bare `YYYY-MM-DD` upper bound is applied at the seams only — `DatabaseLoader.queryHistory` in driver mode becomes one, the engine seam lowers type-blind for an object with no field map, and `InMemoryDriver` drops its own copy (ADR-0053 D-D1 items 5 and 7, #20822)
+
+Clause-②: no
+
+- **`@objectstack/metadata` — `DatabaseLoader.queryHistory` in driver mode lowers its own filter.** With a raw `IDataDriver` (`MetadataManager.setDatabaseDriver`) the history filter reaches the driver without passing any seam. The loader now runs the shared `lowerFilterCondition` (`@objectstack/spec/data`) on it, typed by the history object it syncs: `until: 'YYYY-MM-DD'` reads `recorded_at < next day`, so every version recorded on that day is kept on every driver, and an instant `until` is kept as written. Engine mode is unchanged (the engine's own `where` seam lowers it). Before this, the whole day was kept only by each driver's own copy of the rule; with `@objectstack/driver-memory`'s copy deleted below, `until` = today would have gone from every version of the day to none.
+- **`@objectstack/objectql` — an object with no field map is lowered type-blind.** The engine's `where` seam (on `find`, `findOne`, `count`, `update`, `delete` and `aggregate`'s `where` / `aggregations[i].filter`) reads the object's declared field map and rewrites a declared `datetime` column only. For an object the registry does not hold there is no declaration to read, and the seam now applies the whole-day rules to every column (a bare-day `$lte` becomes `$lt` the next day, a `$between` splits), as ADR-0053 D-D1 item 7 rules for a seam that cannot read the declared type. It used to leave such an object to each driver's own copy. Visible on `SqlDriver`: a bare-day `$lte` on a non-`datetime` column of an unregistered object that holds ISO instant text now keeps the whole day; a `datetime` or `date` column answers as before. An object with a field map is unchanged.
+- **`@objectstack/driver-memory` — `InMemoryDriver` compiles the comparison it is handed.** Its four copies of the whole-day rule are deleted (the `$lte` and `$between` arms of the filter translator, the `<=` and `between` arms of the AST-node translator). A read through the engine hands it a `where` the engine's seam has already lowered, so on that path a declared `datetime` column keeps the whole named day, and a declared `date` column answers as before. A row-level security `using` filter is not lowered by the engine's seam: the security middleware ANDs it into the query's `where` after that seam has run, and only the RLS compile seam lowers it, rewriting just the columns its field guard declares `datetime`. Two answers converge on what `SqlDriver` already returns (ADR-0053 D-D1 item 7's scope): on a registered object, a bare-day `$lte` / `$between` on a declared `text` column holding ISO instant text, or on a column the object does not declare, is now compared as written, where this driver used to widen it to the whole day. One path narrows outside those two: an RLS `using` policy with a bare-day upper bound, on an object whose declared fields the security plugin cannot resolve, is compiled with no field guard, so the RLS compile seam reads no column as `datetime` and the bound reaches this driver as written, where this driver used to widen it to the whole day; that holds until #20822 group 2 makes the RLS compile seam type-blind when it has no guard. A direct `find()` that passed no seam gets the comparison it wrote (item 5); lower the filter with `lowerFilterCondition` first to keep the whole-day reading.

.changeset/20846-temporal-range-message.md

@@ -0,0 +1,38 @@
+---
+'@objectstack/core': minor
+'@objectstack/spec': patch
+'@objectstack/objectql': patch
+'@objectstack/rest': patch
+---
+
+fix(objectql,rest): a `date` or `datetime` value refused for its year says so — "must be a date in the years 0001 to 9999" / "must be a datetime whose UTC year falls in the years 1000 to 9999" — instead of "must be a valid date (ISO-8601)", which was false for a value such as `0500-07-15T10:00:00Z` (#20846)
+
+Clause-②: yes (widening) — one new export on `@objectstack/core`'s root, `SUPPORTED_TEMPORAL_YEARS`. No value's verdict moves and no wire key moves: the field code stays `invalid_date` and its `constraint` stays `{ type }`.
+
+`POST` / `PATCH /api/v1/data/:object` and each row of `POST /api/v1/data/:object/import`
+refuse a `date` outside the years 0001 to 9999 and a `datetime` whose UTC year falls
+outside 1000 to 9999. When the value itself is readable — an ISO 8601 string such as
+`0500-07-15T10:00:00Z` or `+010000-01-01`, or a `Date` — the refusal's message now
+names the kind's years. An author who read "not valid ISO" rewrote the spelling, and no
+spelling of that year is admitted.
+
+- `@objectstack/spec`: the validation message catalog gains `invalid_date_range` and
+  `invalid_datetime_range` in `en`, `zh-CN`, `ja-JP` and `es-ES`. They are two more
+  sentences of the `invalid_date` code, never a wire value. The years are the template
+  parameters `{{firstYear}}` / `{{lastYear}}`. A deployment that overrides a message
+  under `validation.field.invalid_date` or `validation.field.invalid_datetime` does not
+  cover these values. To override their text, define
+  `validation.field.invalid_date_range` / `validation.field.invalid_datetime_range`.
+- `@objectstack/core`: `SUPPORTED_TEMPORAL_YEARS` (`{ date: { first: 1, last: 9999 },
+  datetime: { first: 1000, last: 9999 } }`, frozen) is the range
+  `isOutsideTemporalYearRange` judges by. It is exported so a refusal names the range
+  from the source the doors use, never a copy of its numbers.
+- `@objectstack/objectql` and `@objectstack/rest`: the record validator and the import's
+  cell reader choose the range sentence for such a value. An import cell with more than
+  four year digits (`+010000-01-01`) is refused by the import's reader. It used to read
+  "is not a valid date" and now gets the same range sentence as the write door.
+
+**What is not affected.** Which values are refused is unchanged, and so is the refusal's
+code (`invalid_date`) and `constraint`. A value that is not readable keeps its sentence:
+"must be a valid date (ISO-8601)" at the write door, `"…" is not a valid date` at the import.
+So does a number, which is never a written `date` or `datetime`.