Merge remote-tracking branch 'origin/main' into claude/issue-16354-dataset-measure-aggregate-field-type-lint

Author: claude

.changeset/18550-reference-carrier-residue.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/rest": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/lint": minor
+"@objectstack/verify": minor
+---
+
+The remaining raw `FieldSchema.reference` readers now **REFUSE** a carrier they cannot read, instead of answering "no target" (#18550). The previous release routed the arbiter (`referenceCarrierOf`) and the lint target readers; these were the measured residue of the same ruling — every reader, not just the arbiter.
+
+`FieldSchema.reference` is `z.string().optional()`, so `ObjectSchema.safeParse` refuses an object- or array-valued carrier at the contract door. These reads are the other door: the one a value reaches only when it never went through parse — a hand-built fixture, a raw `registerObject`, a stored row rehydrated past its schema.
+
+**`@objectstack/objectql`** — both of the delete cascade's carrier reads (`planCascadeAtomicity` and `cascadeDeleteRelations`). This is the one with a measurable runtime consequence, and it is why the level is not `patch`:
+
+```
+before   acct=1 task=1
+delete   RESOLVED true       <- success reported to the caller
+after    acct=0 task=1       <- an ORPHANED master_detail row
+```
+
+An unreadable carrier made the relation invisible to the cascade, so the parent was deleted, the detail row stayed, and the caller was told the delete succeeded — no `restrict` refusal, no `set_null`, nothing logged. It now refuses before any row is touched.
+
+**`@objectstack/rest`** — the public-form lookup picker's field-def fallback. The field def is also hoisted out of the metadata fetch's `catch {}`, so an unreadable carrier is no longer reported as `LOOKUP_TARGET_MISSING`: "no target is declared" and "the declared target cannot be read" want different fixes from whoever owns the metadata.
+
+**`@objectstack/metadata-protocol`** — the seed dependency graph, which also retires an `as string` cast that asserted exactly what its truthiness guard had not checked.
+
+**`@objectstack/lint`** — the four remaining target readers: `masterDetailCount` (`validate-expressions`), the `displayField` consumer edge (`validate-field-consumers`), the field and action-param targets (`validate-object-references`), and `masterOf` (`validate-sharing-rule-enforceability`).
+
+**`@objectstack/verify`** — `relationTarget`, which no longer degrades an unreadable carrier to the generic "has no `reference` target" an object with no relationship metadata at all receives.
+
+`null`, `undefined` and `''` are ABSENCE, not a wrong shape, and still answer `undefined` at every one of these sites — a field is allowed to name no target, and `StrictField` declares `reference` nullable. Each site's absence answer is pinned alongside its refusal.
+
+Upgrading: nothing conformant changes. A non-string `reference` could not be authored, stored or parsed before this release either; what changes is that one now fails loudly at the read instead of being read as an absent target. If a test asserted the old silence, assert the refusal instead.

.changeset/18762-cloud-adr-citation-sweep.md

@@ -0,0 +1,51 @@
+---
+'@objectstack/cloud-connection': patch
+---
+
+docs(cloud-connection): cite the cloud control-plane decisions as `cloud ADR-NNNN` instead of bare numbers that resolve to this repo's own records (#18762)
+
+AGENTS.md Prime Directive 13 is explicit — an ADR "lives in the repository whose
+code it governs", and a cloud decision is cited as `cloud ADR-NNNN`, "never as a
+bare number, which `scripts/check-adr-anchors.mjs` resolves against *this*
+registry (the two number independently)". The rule landed; the stock this
+package already carried was never swept.
+
+Read against this repository's registry, the bare numbers pointed at real but
+unrelated records:
+
+- `ADR-0008` → `docs/adr/0008-metadata-repository-and-change-log.md`, *Metadata
+  Repository, Change Log & Subscription (M0 → M4)* — zero occurrences of
+  "control plane", "cloud-connection" or "Phase 1"/"Phase 2".
+- `ADR-0007` → `docs/adr/0007-settings-manifest-and-kv-store.md`, *Settings —
+  Manifest + K/V Store + Resolver*. The cloud ADR-0007 these lines mean is the
+  one this repo's own ADR-0003 status line already names: the decision that
+  redefined `sys_package_installation` as management-plane desired state and put
+  runtime truth in the `LocalManifestSource` ledger.
+- `ADR-0009` → `docs/adr/0009-execution-pinned-metadata.md`, *Execution-Pinned
+  Metadata* — not the marketplace Setup-navigation ownership decision the lines
+  describe.
+
+That is worse than citing a number nobody has. A dangling id stops a reader; an
+id that resolves lets them believe they read the right page and walk away with
+the wrong decision.
+
+18 citations now carry the `cloud` qualifier, in the spelling this package
+already used elsewhere for the very same numbers — `cloud ADR-0008` in
+`connection-credential-store.ts`, `cloud ADR-0007 step ⑤` in
+`local-manifest-source.ts`, `cloud ADR-0009 P2a` in `marketplace-ui.ts`'s own
+header. All three numbers already carried both spellings inside this one
+package, and `marketplace-ui.ts` carried both inside a single file — qualified in
+its header on line 4, bare on lines 16 and 43.
+
+What actually reaches a consumer of this package:
+
+- The npm `description` field, which is the sentence shown on the package page.
+- `README.md`, including the closing pointer that already said "in the cloud
+  repository" while writing the number bare.
+- The published `.d.ts`, which carries the module and plugin docblocks.
+
+No behaviour moves. No type, export, route, schema or runtime path is touched —
+this is citation spelling and prose only, which is why it ships as a patch rather
+than silently. No ADR record is written or edited. `packages/cloud-connection/CHANGELOG.md`
+is deliberately untouched: it is published history, and a released entry is
+amended in a dedicated docs-only PR, never as a rider on code changes.

.changeset/18978-aggregate-surface-scope.md

@@ -0,0 +1,50 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec): `spec-changes.json`'s aggregate export diff declares the release pair it really spans (#18978)
+
+Clause-②: yes (widening) — one new OPTIONAL key on a published artifact (`aggregate.surfaceScope`)
+and one new optional field on `SpecChangesSchema`. Nothing is renamed, retired or reshaped: the
+schema still ACCEPTS a record without it, every existing key keeps its spelling and meaning, and
+`perMajor` and the `release` section are byte-identical. Contract-review tier.
+
+`aggregate.added` / `aggregate.removed` are not registry-derived. A release-time api-surface diff
+fills them by comparing the artifact being published against the previously **published** one, so
+they span **one release** — while the record they sit in is keyed by protocol major (`from: 10,
+to: 17`) and every entry carries only `since: 17` / `removedIn: 17`, with
+`perMajor[16 → 17].added` at `0` beside it. Nothing in the file distinguished one minor's slice
+from the whole major-boundary delta.
+
+Measured on the published `@objectstack/spec@17.4.0` Release asset: `aggregate.added` = **225**,
+`aggregate.removed` = **51**, every entry `since`/`removedIn` = 17 — and set-identical to a
+recomputed `17.3.0 → 17.4.0` diff of the two tarballs' own `api-surface/` snapshots. It was the
+minor's delta wearing a major's label.
+
+**What ships now.** A record whose export arrays are non-empty carries the version pair they were
+diffed between:
+
+```bash
+jq '.aggregate | {from, to, surfaceScope, added: (.added | length), removed: (.removed | length)}' \
+  node_modules/@objectstack/spec/spec-changes.json
+```
+
+- `surfaceScope: { fromVersion, toVersion }` present ⇒ `added`/`removed` span exactly that
+  published-version pair. ⛔ They are **not** the `from` → `to` major delta, and never were.
+- `surfaceScope` absent ⇒ the record carries no export diff at all and `added`/`removed` are
+  empty. ⛔ Read that as "this record does not say", never as "nothing was added between `from`
+  and `to`" — the same rule the `release` section already states for itself.
+- `from` / `to` still answer the major-boundary question for `converted` / `migrated`, which are
+  registry-derived and unaffected.
+
+**Refused at the producer and at the publish gate, in both directions.** The generator reads the
+previous version off the previous artifact's own `package.json`, omits the arrays loudly when it
+cannot read one, and refuses outright to write a non-empty unlabelled array.
+`scripts/check-release-spec-changes.mjs` — which until now checked the `release` section and not
+the aggregate — recomputes the aggregate's claim from the two tarballs and refuses an absent,
+mislabelled or untrue scope. Its self-test roster grows from 15 batteries to 23.
+
+**Nothing previously honest moved.** The committed registry-only projection and every `perMajor`
+record carry no new key at all; the committed `spec-changes.json` changes on its `$comment` line
+and nowhere else. The published schema is deliberately not narrowed — every manifest published so
+far carries an unscoped diff and must keep parsing.

.changeset/19046-object-grid-page-size-accept-set.md

@@ -0,0 +1,33 @@
+---
+'@objectstack/spec': minor
+---
+
+**BREAKING for authored metadata** — the `object-grid` page-component door now refuses a page size of `0`, a negative page size and a non-integer page size, at all three of its spellings: `pagination.pageSize`, every `pagination.pageSizeOptions[]` entry, and the flat `pageSize` shorthand (#19046).
+
+Clause-②: yes (narrowing)
+
+The accept set shrinks to the one the VIEW arm has ruled all along. `PaginationConfigSchema` (`view.zod.ts`) declares `pageSize: z.number().int().positive()` and pins its refusals by name; `MetadataQuery` and the two marketplace request schemas say `z.number().int().min(1)`, each with its own throwing pin. The `object-grid` door said `pagination: z.unknown()` and `pageSize: z.number()` — the only page-size declaration in the package that accepted `0`, and the one renderers read.
+
+**It was not theoretical.** Measured at objectui#9853: an authored `pagination.pageSize: 0` reached `ObjectGrid`, went out on the wire as `$top: 0` and rendered ZERO ROWS, with no grouping needed to trigger it — through this arm, with a `success: true` receipt from this schema. The view arm would have refused the same value. objectui#9896 repaired the consumer half (a resolver at every read point, fail-soft, one loud diagnostic); this is the declaration half and is not a prerequisite for it.
+
+```
+✗ pagination.pageSize: Too small: expected number to be greater than 0
+✗ pageSize: Invalid input: expected int, received number
+```
+
+### Migration — FROM → TO
+
+| You wrote | Write instead |
+| --- | --- |
+| `pagination: { pageSize: 0 }` | `showPagination: false` and no `pagination` bag — the bag's PRESENCE is what enables paging, so `pageSize: 0` never meant "no paging" |
+| `pagination: { pageSize: 0 }` (meaning "all rows on one page") | the page size you actually want (`{ pageSize: 100 }`); `0` reached the wire as `$top: 0` and returned nothing |
+| `pagination: { pageSizeOptions: [0, 25, 50] }` | `{ pageSizeOptions: [25, 50] }` — drop the `0` entry; selecting it set the fetch window to zero rows |
+| `pageSize: 25.5` | `pageSize: 25` — a fractional page size was truncated or forwarded verbatim, depending on the read point |
+
+The one-line fix is always the same: **write a positive integer, or delete the key and take the renderer's default.**
+
+<!-- adr-0087: registered ui-object-grid-page-size-positive-integer-refused -->
+
+**⛔ What this deliberately does NOT narrow: the `pagination` bag stays OPEN.** The card's defect is that the two arms disagreed about a page SIZE — not that the bag should become a closed shape. `pagination` is now a `z.looseObject` that validates the two members whose value is a page size and passes every other key through unvalidated, so a sibling key that parsed before still parses and still survives the parse byte-identically (pinned in `component-object-grid-pagination-accept-set.pin.test.ts` §3). Reusing the view arm's `PaginationConfigSchema` here would have refused every sibling key this door has accepted since it was written — the `…` in its own describe says authors write them — which is a wider narrowing than the measured defect and a different decision. `PaginationConfigSchema` itself is unchanged and stays closed; §4 of that pin states both the agreement and the deliberate asymmetry.
+
+**One second axis, named rather than left to be discovered.** `pagination` moves from `z.unknown()` to an object type, so a non-object value (`pagination: true`) is refused where it used to parse. Measured before narrowing: zero non-object `pagination` values exist on an `object-grid` node in either repository's corpus, the objectui registry has published this input as `type: 'object'` all along (`plugin-grid/src/index.tsx`), so the html tier already answered `type-mismatch` on one, and the renderer reads the key for PRESENCE (`schema.pagination !== undefined`) — which means an authored `pagination: false` used to turn paging ON. That value now gets a located refusal instead of the opposite of what it says.

content/docs/references/ui/component.mdx

@@ -514,8 +514,8 @@ Sort field and direction pair
 | **defaultFilters** | `any` | optional | Legacy base-filter fallback, read only when `filter` is absent. Prefer `filter` |
 | **sort** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Initial row order — the SortItem array form `[{ field, order }, ...]`, the one sort orthography every declared `sort` door on this platform shares; lowered to the wire `$orderby`. The legacy string clause (`name desc`) is refused — see migration `object-block-sort-item-array` |
 | **defaultSort** | `never` | optional | [REMOVED] `object-grid` property `defaultSort` was removed in @objectstack/spec 17 (ADR-0049) — it was the legacy second spelling of `sort`: a single `{ field, order }` pair read only when `sort` was absent, so one intent had two spellings and a grid authoring both silently ignored this one. Rename the key to `sort` and wrap the value in an array (`defaultSort: { field, order }` becomes `sort: [{ field, order }]`); the pair itself is unchanged. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; apply them by hand. |
-| **pagination** | `any` | optional | Pagination config (`{ pageSize, pageSizeOptions, … }`); its presence enables paging |
-| **pageSize** | `number` | optional | Flat page-size shorthand; `pagination.pageSize` wins when both are set |
+| **pagination** | `{ pageSize?: integer; pageSizeOptions?: integer[] } & Record<string, any>` | optional | Pagination config (`{ pageSize, pageSizeOptions, … }`); its presence enables paging. `pageSize` and every `pageSizeOptions` entry is a positive integer — the accept set the view arm's `PaginationConfigSchema` already rules; the bag stays open, so other keys pass through unvalidated |
+| **pageSize** | `integer` | optional | Flat page-size shorthand, a positive integer; `pagination.pageSize` wins when both are set |
 | **showPagination** | `boolean` | optional | Show the pager (read only when `pagination` is absent) |
 | **searchableFields** | `string[]` | optional | Fields the toolbar search queries; a non-empty list enables search |
 | **showSearch** | `boolean` | optional | Show the search box (read only when `searchableFields` is absent) |

content/docs/ui/forms.mdx

@@ -257,7 +257,7 @@ sections: [{
 | `displayFields` | Fields projected into each result row (plus `id`); the visitor's `q` is `contains`-matched against the **first** entry. At most 5; omitted → `['name']`. |
 | `maxResults` | Rows per request, integer 1–50 (default 20). 50 is a hard server ceiling; there is **no pagination** on this surface (`offset` is pinned to 0), so a leaked endpoint cannot enumerate the table. |
 | `filter` | Static pre-filter rows (same `{ field, operator, value }` dialect as list-view filters), ANDed ahead of the visitor's search. |
-| `object` | The object to search. Optional — omit it and the server resolves the target from the field's own definition on the parent object: its `reference` key, and only that key. A stored row spelling the target `referenceTo` / `target` / `options.objectName` is **not** resolved — the route answers `500 LOOKUP_TARGET_MISSING` — because `FieldSchema` accepts no spelling but `reference`. Declare it only to search something other than what the field points at. |
+| `object` | The object to search. Optional — omit it and the server resolves the target from the field's own definition on the parent object: its `reference` key, and only that key. A stored row spelling the target `referenceTo` / `target` / `options.objectName` is **not** resolved — the route answers `500 LOOKUP_TARGET_MISSING` — because `FieldSchema` accepts no spelling but `reference`. That key is also **read through the one carrier accessor**, so a stored row whose `reference` holds something other than a string (an object, an array) is refused rather than searched — see the error table below. Declare it only to search something other than what the field points at. |
 
 Those four keys are the whole block. It admits exactly what the route enforces
 — an unknown subkey, a 6th display field, or `maxResults: 51` is a **parse
@@ -285,6 +285,7 @@ Errors:
 | `403 LOOKUP_NOT_PUBLIC` | the field has no `publicPicker` block — the deliberate loud default (#3022); also any server-managed anchor (`owner_id`, `organization_id`, …), which never gets a picker even if one is declared |
 | `404 FORM_NOT_FOUND` | slug not registered on any `sharing.allowAnonymous: true` view |
 | `500 LOOKUP_TARGET_MISSING` | the referenced object could not be resolved from either `publicPicker.object` or the field definition — the field names no target object at all (or its object metadata is unreachable). Until #7486 this also fired for a perfectly well-formed field, because the fallback read only the legacy spellings and not the canonical `reference`; declaring `object` was the workaround and is no longer needed. |
+| `500 INTERNAL_ERROR` | the field def **declares** a target this route cannot READ — a stored `reference` holding an object or an array rather than the object name `FieldSchema` declares. ⚠️ Deliberately **not** `LOOKUP_TARGET_MISSING`: "nothing names the target" and "the named target is unreadable" want different fixes from whoever owns the metadata, so they get different answers. The unreadable carrier is named in full in the server log (it is withheld from the response body, as every fault's text is); the picker's search never runs. |
 
 ### Auth model
 

content/docs/upgrading.mdx

@@ -335,8 +335,27 @@ jq '.release | {fromVersion, toVersion,
 named — `"./ai: AgentSchema (const)"`, the entry point followed by the export
 and its kind. `converted` and `migrated` are the ADR-0087 conversions and
 semantic migrations first registered in that release. The same file's
-`aggregate` and `perMajor` records are unchanged and still answer the
-major-boundary question.
+`perMajor` records are unchanged and still answer the major-boundary question,
+and so does `aggregate` — for its `converted` and `migrated`, which are derived
+from the ADR-0087 registries across the whole `from` → `to` range.
+
+⛔ **But not for `aggregate.added` / `aggregate.removed`.** Those come from the
+same one-release export diff as the section above, not from the major range the
+record is keyed by, so when they are filled the `aggregate` record carries a
+`surfaceScope` naming the exact pair they span:
+
+```bash
+jq '.aggregate | {from, to, surfaceScope,
+                  added: (.added | length), removed: (.removed | length)}' \
+  node_modules/@objectstack/spec/spec-changes.json
+```
+
+`surfaceScope` absent means that record claims no export diff at all and its
+`added` / `removed` are empty — the registry-only shape. ⛔ Read that as "this
+record does not say", never as "nothing was added between `from` and `to`",
+which is the same rule the `release` section states for itself below. A release
+whose `aggregate` arrays disagree with the two published tarballs, or carry no
+`surfaceScope`, does not publish.
 
 The `os` CLI reads the same section, so a CI job does not have to know the file
 exists: