Merge remote-tracking branch 'origin/main' into claude/issue-7496-submitbehavior-url-shape-wt

Author: claude

.changeset/adr-0087-stock-reconciliation-backfill.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": minor
+---
+
+chore(spec): backfill nine ADR-0087 ledger entries the v17 stock was missing (#6350)
+
+The #6148 completeness gate is deliberately **diff-only** — it judges what a PR
+adds, never the inventory, because auditing stock in CI would turn the repo red on
+adoption day and bill main's history to current authors (#6129). The cost of that
+choice is that every breaking changeset already in the v17 train was never compared
+against the ledger. This is the one-time manual reconciliation the maintainer ruled
+for, not a change to the gate: `check-adr-0087-registration.mjs` still judges diffs
+only, and nothing in CI starts auditing inventory.
+
+Measured today over the stock: **274 declared-breaking changesets**, 106 in the
+residue (published break + a real FROM → TO prescription, so only `registered` or
+`already-registered` remain), **61 of them flagged** as never having touched a
+ledger file. Judging those 61 by hand found nine genuinely missing entries, now
+registered as D3 semantic migrations:
+
+| entry | face | issue |
+| --- | --- | --- |
+| `runtime-httpserver-wrapper-retired` | the exported `HttpServer` delegating wrapper | #5122 |
+| `record-details-sections-object-form` | `RecordDetailsProps.sections` shape + `hideFields` | #5611 |
+| `data-driver-query-omit-object` | `IDataDriver`'s query parameter contract | #5181 |
+| `sort-node-direction-rejected` | `orderBy[].direction` → `order` | #4721 |
+| `tool-requires-confirmation-retired` | `tool.requiresConfirmation` | #3715 |
+| `export-axis-opt-in` | `allowExport` unset flips to deny | #3544 |
+| `apimethod-enum-shrink` | `enable.apiMethods` legacy values | #3543 |
+| `sharing-rule-recipient-reconcile` | sharing-rule `group` / `guest` / owner-type rules | #1878 |
+| `client-delete-result-success` | `DeleteDataResult.deleted` → `success` | #5638 |
+
+Two of them had already shipped **half** a retirement: `tool.requiresConfirmation`
+carries a live `retiredKey()` tombstone in `ai/tool.zod.ts` and `SortNodeSchema`
+carries `aliases: { direction: 'order' }`, but neither had the ledger half. A
+tombstone is the proof the removal was declared; the ledger entry is what
+`spec-changes.json`, the upgrade guide and `os migrate meta` project to consumers,
+and a retirement needs both.
+
+Each of the nine stock changesets now carries its `<!-- adr-0087: registered … -->`
+disposition marker, so the judgement is recorded where the next auditor reads
+rather than only in a PR body. `spec-changes.json` and
+`docs/protocol-upgrade-guide.md` are regenerated from the registry.

.changeset/analytics-field-reference-comparand-refusal.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(analytics)!: a `{ $field }` comparand is refused on both SQL-lowering doors instead of being BOUND as the comparison's value (#7598)
+
+<!-- adr-0087: not-required (no-migration-prescription) This change retires NO key and adds none. `FieldReferenceSchema` stays declared in `packages/spec` exactly as it is, stays implemented by `@objectstack/formula`'s in-memory evaluator, and stays COMPILED by `driver-sql` / `driver-sqlite-wasm` under #5222 — `packages/spec` is untouched by this PR, no metadata schema gains or loses a key, and no authored or stored shape becomes unparseable. What moves is one COMPILER's posture at two doors of `@objectstack/service-analytics`: a shape that used to compile into a predicate binding the reference OBJECT as a value now refuses. There is therefore nothing for `objectstack migrate meta` to rewrite — the FROM shape is still valid metadata everywhere it was valid before, and rewriting it would be wrong, since the identical filter continues to execute on the ObjectQL engine path and on both SQL drivers. Nor is there a FROM/TO rule a ledger entry could state: the correct repair depends on which face the author's query routes to, which is a deployment fact rather than a metadata one. The channels that do reach an affected reader are this changeset's CHANGELOG text and the refusal message itself, which names the operator, the field, the referenced column, the faces that DO execute the shape, and why this compiler cannot — all shipped with this change. -->
+
+**⚠️ Behaviour change.** A filter whose comparand is a field reference —
+`{ amount: { $gt: { $field: 'budget' } } }`, the shape
+`FieldReferenceSchema` declares and `compileCelToFilter` emits for a
+field-to-field comparison in a CEL permission / RLS rule — used to COMPILE on
+both of this package's doors. It now refuses: `INVALID_FILTER` / 400 on the
+analytics `where` door, `READ_SCOPE_COMPILE_FAILED` / 500 on the read-scope
+lowering (each door's existing envelope, unchanged).
+
+#7598 was filed reading "these compilers still REFUSE `$field`". Measured on
+`origin/main` (`5823d593d`), nothing refused. For the six scalar comparison
+operators — exactly the ones #5222 taught `driver-sql` to compile into a
+same-table column-to-column comparison — the reference OBJECT went into the
+bind list:
+
+| face | `{ amount: { $gt: { $field: 'budget' } } }` |
+|---|---|
+| `read-scope-sql` | `"person"."amount" > ?` · bound to `{"$field":"budget"}` |
+| `where` → `NativeSQLStrategy` | `WHERE amount > $1` · bound to the JSON TEXT `{"$field":"budget"}` |
+| `where` → `/analytics/sql` echo | `WHERE amount > $1` · bound to the reference OBJECT |
+| `where` → ObjectQL engine | reached `driver-sql`, which compiles it CORRECTLY since #5222 |
+
+So the defect was a silent wrong answer, not a refusal: a syntactically perfect
+predicate comparing a column against a value no row can hold. Three of the four
+faces answered differently, and on the read-scope door the one answering wrongly
+is an administrator's RLS predicate. The gates assumed to be catching this
+(`isBindableComparand` / `isRenderableTextComparand`) had not drifted from
+`driver-sql` — they are simply never ASKED about that position, only about the
+LIKE family and `$in` / `$nin` / `$between` MEMBERS.
+
+**What this does not do:** it does not bring the capability to these compilers.
+The four maintainer rulings that make a referenced column name safe in a SQL
+identifier position (same-table only, declared-only enumeration, tenant-isolation
+column forbidden on both sides, same comparison class) all turn on metadata
+`StrategyContext` does not expose — neither an object's declared field set nor its
+tenant-isolation column — so these compilers cannot enforce them, and shipping a
+port without them would open a comparison surface onto the tenant boundary.
+Implementing it here is a `packages/spec` contract question, left open on #7598.
+
+Field-to-field RLS rules continue to work on the ObjectQL engine path, where the
+driver compiles them with the metadata it owns; they are now loudly refused,
+rather than silently mis-answered, on the raw-SQL analytics path.
+
+Positions already refused before this change keep their exact wording — the LIKE
+family, `$in` / `$nin` members, and a bare `{ field: { $field: … } }` — because
+each of those refusals already CONVERGES with `driver-sql`'s own #5222 refusal
+arm. `minor` rather than `patch` follows #5234, the same class of change on the
+same two doors.

.changeset/apimethod-enum-shrink.md

@@ -79,3 +79,5 @@ passing through Zod; the parse-time strip warning carries no object name).
 primitives = default-open). Read-only and deny-all whitelists are unchanged;
 the seven `[]` declarations are deliberately KEPT as defense-in-depth alongside
 `apiEnabled: false`.
+
+<!-- adr-0087: registered apimethod-enum-shrink -->

.changeset/baseline-additive-on-ui-plane.md

@@ -0,0 +1,43 @@
+---
+'@objectstack/plugin-hono-server': patch
+---
+
+fix(hono-server): apply the baseline ADDITIVELY on `/auth/me/permissions` and `/me/apps` — the ADR-0090 D5 fallback cliff, one plane over (#7608)
+
+Both permission resolutions in `current-user-endpoints.ts` applied the deployment
+baseline permission set(s) only in a **second** `resolvePermissionSets` call gated on
+`resolved.length === 0`. That is the fallback **cliff** D5 abolishes, verbatim:
+
+> The fallback cliff is abolished. Today's semantics ("fallback applies only while the
+> user has *zero* explicit grants") mean the first real grant silently removes the user's
+> baseline. `everyone` is additive like any other position: baseline ∪ explicit, always.
+
+`SecurityPlugin.resolvePermissionSetsForContext` — the **data** plane, one function call
+away — has pushed the baseline into `requested` and resolved once for as long as D5 has
+existed. These two endpoints had not, so the two planes disagreed the moment a member
+held any explicit grant at all.
+
+**What a user saw.** A member who received their **first** position or permission-set
+grant kept the baseline on the data plane and lost it on the **UI** plane.
+`/auth/me/permissions` reported object/field access narrower than a read actually
+returns, and `/me/apps` dropped every app whose `requiredPermissions` or tab visibility
+came from the baseline. Measured on the fixture that ships with this change — a member of
+one org, a baseline granting two capabilities, one explicit grant adding a third —
+receiving that grant took the member from **2 apps to 1**. It now takes them from 2 to
+**3**: the two baseline apps are retained instead of traded away, and the same member
+regains one readable object, one readable field and two capabilities on
+`/auth/me/permissions`. The fail-direction was **closed** (the console hid what the API
+allowed), which is why it read as cosmetic for as long as it did.
+
+The baseline names are now pushed into `requested` before the **single** resolution, in
+one shared `effectivePermissionSetNames` helper both handlers call — which retires the
+second `resolvePermissionSets` call outright rather than merely widening its guard: once
+the baseline is an input to the first call, a second call over a subset of those same
+names can add nothing. Unchanged: a member with zero grants still gets the baseline, a
+deployment declaring an empty baseline still resolves the caller's own names alone, and
+`/me/apps` still filters an app whose `requiredPermissions` nobody holds.
+
+No `principalKind === 'agent'` branch, unlike the plugin's copy, and that is a property
+of this surface rather than an omission — these endpoints are reached only through the
+better-auth **session** resolver, which never marks a principal kind, so an agent has no
+session to present here.

.changeset/client-delete-result-success.md

@@ -96,3 +96,5 @@ server suite never had: a real DELETE over HTTP whose body is read as
 `deleted.success` and whose key set is asserted literally — `z.object` strips
 unknown keys, so a passing parse alone cannot prove no stray `deleted` rode
 along.
+
+<!-- adr-0087: registered client-delete-result-success -->

.changeset/data-driver-query-omit-object.md

@@ -27,3 +27,5 @@ await driver.find('account', { where: { status: 'open' } });
 `QueryAST` 的 zod 形状（`data/query.zod.ts` 的 `BaseQuerySchema`）**没有动**：`object` 在引擎与 hook 那一层是被读的，改的只是驱动契约的参数类型。`expand` 条目里的 `object` 同样保留 —— 那里它命名的是**关联对象**，没有任何实参携带这个事实，不是冗余。
 
 标 major 是因为这是**源码级破坏性**变更（调用点字面量），运行时行为零变化。注意 `check:api-surface` 只看得见新增的 `DriverQuery` 导出、看不见参数类型的收窄（它记录导出存在与否，不记录签名），所以这条迁移说明是该变更唯一的下游载体。
+
+<!-- adr-0087: registered data-driver-query-omit-object -->

.changeset/diagnostics-clean-baseline.md

@@ -0,0 +1,58 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/runtime": patch
+---
+
+fix(objectql,runtime): stop the platform's own stamps from failing spec validation — `/meta/diagnostics` reads clean again (#7561)
+
+`GET /api/v1/meta/diagnostics` reported **94 of 94** registry entries INVALID —
+every entry, `sys_*` and `showcase_*` alike. The endpoint reports entries that
+fail their registered Zod schema, so at a 94/94 baseline it carried **no
+signal**: a genuinely broken object was indistinguishable from a healthy one,
+and any gate or dashboard built on it read permanently red.
+
+Both error shapes behind the 94 were self-inflicted — the platform reporting
+defects about columns it wrote itself, on documents no author wrote or could
+fix.
+
+**`fields.__search: Unrecognized key 'index'`.** `provisionSearchCompanion`
+stamped `index: true` on the hidden `__search` companion column. Field-level
+`index` was removed from `FieldSchema` in the 16.x line (#2377, ADR-0049)
+because a field-level index flag built no index, and `FieldSchema` is a
+`strictObject`, so the key was rejected by name. The companion is provisioned
+before the document is stored and `/meta` re-parses the served body, so the
+stamp badged `_diagnostics: { valid: false }` onto every object the platform
+provisions a companion for. This is the #6810 mechanism one field over
+(`applySystemFields` stamping `indexed` on `organization_id`), and the same
+retired key. The stamp is gone, along with the docblock claim that the column
+"IS `index`ed".
+
+Unlike #6810 the index is **not** re-declared in the object's `indexes[]`, and
+that difference is measured rather than overlooked. #6810's predicate is
+`organization_id = ?` — equality, which a B-tree serves. This column's only
+reader is `buildSearchFilter`, which emits `{ __search: { $contains: term } }`
+— a leading-wildcard `LIKE '%term%'` no B-tree can answer — and `IndexSchema`
+spells nothing else (`name` / `fields` / `unique`; no trigram/GIN method).
+Declaring one would buy write amplification on every row for a read path that
+cannot use it. Search behaviour is unchanged either way: nothing read the flag.
+
+**`config: expected record, received undefined`.** The datasource-visibility
+registration in `DefaultDatasourcePlugin` published the `default` row without
+`config`, which `DatasourceSchema` requires. It is now stamped `{}` —
+deliberately empty, not the host's real config, which carries connection
+credentials that would otherwise land on `GET /api/v1/meta/datasources` for
+every metadata reader. No information is lost versus the omitted key; only the
+spelling changes to the one the contract accepts. Fixed at the producer rather
+than by widening the spec: a real datasource document genuinely needs its
+config, so relaxing the schema would trade one honest verdict for a permanently
+weaker one.
+
+**So it stops recurring.** Two pins land with the fix, because patching one key
+at a time is what turned #6810 into this card. A class pin walks every field
+the platform stamps — `applySystemFields` and `provisionSearchCompanion`,
+across every ownership / tenancy / `systemFields` branch — through
+`FieldSchema`, so the next retired-key stamp turns a suite red instead of
+poisoning diagnostics. A baseline pin asserts a realistically-built registry
+sweeps clean, naming both of this card's error shapes explicitly; the 94/94
+state survived undetected until a human read the endpoint by hand, because
+nothing asserted the baseline.

.changeset/dotted-fields-prose-corrected.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/spec": patch
+---
+
+**docs(spec): `fields` stops prescribing a dotted path no driver resolves (#7601)**
+
+Six in-repo surfaces offered `fields: ['owner.name']` as the supported way to read
+one related column. No driver ever implemented it — measured on a real `SqlDriver`,
+a dotted projection is byte-identical to no projection at all, because Knex renders
+`"account"."name"` against a table that was never joined and the #3821 recovery
+ladder retries `select('*')`. Since #7532 those surfaces are additionally
+contradicted by a `400 INVALID_FIELD` at the ingress gate
+(`assertProjectionFieldsExist`). The migration tooling was the sharpest case: both
+protocol-17 upgrade prescriptions routed authors off `query.joins` and off the
+retired `{ field, fields, alias }` form directly into the refused spelling.
+
+This aligns the declaration to the enforcement. The normative `fields` `.describe()`
+now names `expand` as the sanctioned mechanism for related data — its nested
+`QueryAST` both filters (`where`) and selects (`fields`) the related record's
+columns — and carries the sharp edge that was pinned but never documented: **the
+projection must retain the foreign-key column.** `fields: ['title']` with
+`expand: 'project_id'` resolves nothing, because the relation is carried by that
+key; adding `'project_id'` makes it work. Where the value is wanted on the queried
+object itself, the honest remedy is to denormalise it onto that object (a stored
+field, written when the source changes) — the same remedy the sort axis prescribes
+(#6924). Both retirement prescriptions and the two tombstone rejection messages now
+say the same thing, and the JSON Schema artifacts and reference docs regenerate from
+the source.
+
+**No schema change.** `FieldNodeSchema` stays `z.string()`: the refusal of dotted
+projections is a *semantic* verdict, made at the ingress gate where the field map is
+available to judge against — not a *shape* check. Narrowing the type would duplicate
+that gate and refuse the registry-less internal callers the ingress deliberately
+tolerates. Every input that parsed before this change parses byte-identically after
+it, and the type/runtime pins that assert so are kept and renamed
+(`fieldNodeDottedNotNarrowed`) so they read as the non-narrowing guard they are
+rather than as an endorsement of a feature that does not exist.
+
+Prose, prescriptions and generated artifacts only — no wire, stored-data or
+validation behaviour changes.

.changeset/equality-field-reference-lowering.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+"@objectstack/driver-sql": minor
+---
+
+fix(spec): lower equality triples with a `$field` comparand to `{ $eq: ref }` (#7597)
+
+`parseFilterAST` lowered one authored intent two different ways depending only on
+how the operator was spelled:
+
+| authored | lowered to | what it did |
+| :--- | :--- | :--- |
+| `['amount', '>', { $field: 'budget' }]` | `{ amount: { $gt: { $field: 'budget' } } }` | worked on both evaluation paths |
+| `['amount', '=', { $field: 'budget' }]` | `{ amount: { $field: 'budget' } }` | matched **nothing**, silently |
+
+The four equality spellings (`=`, `==`, `equals`, `eq`) dropped the operator,
+because a LITERAL comparand's implicit-equality form is `{ field: value }` —
+correct for a literal, and for a field reference it produces a field spec whose
+only key is `$field`. Every consumer reads an all-`$` key set as an OPERATOR
+SPEC, and nothing implements an operator named `$field`: the in-memory evaluator
+(`@objectstack/formula`) dispatches it to its operator switch, finds no arm, and
+returns the fail-closed `false` — so the filter matched no record on the very
+path that produced it, with no error anywhere. On SQL push-down the same shape
+arrived as an unknown operator and was refused.
+
+An equality triple whose comparand is a `FieldReferenceSchema` now lowers to the
+explicit `{ field: { $eq: ref } }` — the spelling both evaluation paths already
+implement (the memory evaluator resolves the reference; `driver-sql` compiles it
+to a column-to-column comparison, #5222). `['amount', '=', ref]` and
+`['amount', '>', ref]` are now the same kind of thing.
+
+Unchanged, deliberately:
+
+- **Literal comparands.** `['amount', '=', 5]` still lowers to `{ amount: 5 }`.
+  The fix branches on the comparand being a field reference, never on the
+  operator, and a `$field` carrying a non-string is not a field reference on any
+  path — it keeps the literal lowering too.
+- **The in-memory evaluator's unknown-operator posture.** #6520 examined it and
+  kept it; a hand-authored bare `{ amount: { $field: 'budget' } }`
+  `FilterCondition` keeps exactly its current fate on every backend — fail-closed
+  `false` in memory, and `driver-sql`'s actionable refusal naming `$eq` (#5222).
+  Only what the ARRAY sugar produces has changed.
+
+`@objectstack/driver-sql` gains `CROSS_FIELD_AUTHORED_CASES` — the conformance
+corpus's new AUTHORING arm, entering through the lowering sink instead of at the
+already-lowered object, run by both SQL drivers' cross-field suites. Its only
+other change is documentation.