Merge remote-tracking branch 'origin/main' into claude/rest-read-path-field-degradation-4240d5

Author: os-zhuang

.changeset/adapter-hono-auth-wildcard-yields.md

@@ -1,5 +1,5 @@
 ---
-"@objectstack/adapter-hono": patch
+"@objectstack/hono": patch
 ---
 
 fix(adapters/hono): the auth wildcard yields paths the auth service does not own (#4117)

.changeset/adr-0104-meta-advertisement-as-implemented.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(adr-0104): amend the upgrade-path advertisement clause to record how it landed (#4253/#4284) — `os migrate meta` names the migrations without gate status, because gate status is per deployment (2026-07-27 addendum) while `meta` acts on source, which deploys to zero-or-N of them; status is reported where a datastore is actually open. Releases nothing.

.changeset/ai-slot-remedy-tells-the-truth.md

@@ -0,0 +1,18 @@
+---
+'@objectstack/spec': patch
+'@objectstack/runtime': patch
+---
+
+Discovery stops telling Cloud/Enterprise deployments that nothing implements `ai` (#4093 follow-up).
+
+`CORE_SERVICE_PROVIDER` recorded `null` for `ai` because no **workspace** package provides it, and `serviceUnavailableMessage('ai')` therefore produced *"No implementation ships for the 'ai' slot"*. That is false: `@objectstack/service-ai` registers the slot in `objectstack-ai/cloud`. The table conflated "not in this repository" with "does not exist" — the same class of wrong answer the table was introduced to end, one step further out.
+
+Verified against the cloud repository rather than inferred: `packages/service-ai/src/plugin.ts` calls `ctx.registerService('ai', …)`, and the package is `private: true`, so there is genuinely nothing to install — which is why `null` stays right and an `Install X` sentence would still be wrong. `search`, `workflow` and `graphql` were checked the same way and nothing registers them in either repository, so their `null` and their "nothing ships" sentence are accurate.
+
+`ai` now carries a `REMEDY_DETAIL` sentence — *"Provided by @objectstack/service-ai in ObjectStack Cloud/Enterprise — no implementation ships in the open framework"* — the mechanism `ui` already used. Both discovery (`services.ai.message`) and the `/ai` 501 body report it.
+
+This **removes** code: `/ai`'s domain had a local message override, added because the shared sentence was wrong there. Correcting the table fixed the domain *and* discovery, which the override could never reach, so the override and `capabilityUnavailable`'s `message?` parameter are both gone. A slot whose sentence is wrong needs the table corrected, not a local exception.
+
+Also corrected: three places still describing `/ai`'s absent-service answer as a 404 (`docs/api/client-sdk.mdx`, `docs/releases/v17.mdx`, and a comment in `packages/client`'s URL-conformance test) — stale since that answer became 501.
+
+FROM → TO: `services.ai.message` and the `/ai/*` 501 body change text. Nothing branches on either — `status` and `enabled` are the contract, the message is prose for humans and agents.

.changeset/approval-vocabularies-derived.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/spec": minor
+"@objectstack/plugin-approvals": patch
+---
+
+fix(spec,plugin-approvals): the two approval vocabularies are derived, not hand-matched (#3786)
+
+`sys_approval_request.status` and `sys_approval_action.action` spelled their
+option lists out — five values and twelve — each under a "Keep in sync with
+`ApprovalStatus` / `ApprovalActionKind` (spec/contracts)" comment, while the
+contract held the same sets as bare type unions. Seventeen strings matched by
+hand across a package boundary, with nothing checking them. They did all still
+agree; the sweep that found them (#3786) verified that verbatim before changing
+anything.
+
+Agreeing is not the same as being held, and both directions of drift are quiet:
+
+- a value the **column** accepts and the contract omits is invisible to every
+  consumer typed against the contract — the row exists and nothing can narrow it;
+- a value the **contract** declares and the column rejects surfaces only at write
+  time, on whichever tenant first reaches that transition.
+
+An audit vocabulary is a bad place for either. So the contract now publishes the
+lists as values — `APPROVAL_STATUSES` and `APPROVAL_ACTION_KINDS` — with
+`ApprovalStatus` / `ApprovalActionKind` derived from them via
+`(typeof X)[number]`, and the two columns spread the constants. The per-entry
+rationale (which action kinds move the flow, which are thread-only, why
+`returned` differs from `recalled`) moved onto the constants, where the values
+live.
+
+**New exports, no behaviour change.** The emitted option lists are byte-identical
+— verified against the built artifact before and after. Existing imports of the
+two types are unaffected; the types resolve to the same unions.
+
+`approval-vocabularies.test.ts` pins the qualifier that derivation alone cannot:
+the columns agree with the contract *while the spread is there*, and the test
+fails if either is re-inlined as a literal that has drifted. It also guards the
+guard (an unresolvable import would compare two empty lists and pass) and asserts
+the two vocabularies stay distinct, since a copy-paste pointing one column at the
+other constant would satisfy "derived from the contract" while being the wrong
+vocabulary entirely.
+
+Verified by mutation in both directions: adding a value to `APPROVAL_STATUSES`
+propagates into the built `sys_approval_request.status` options (the derivation
+is live, not a stale build), and re-inlining a drifted literal fails
+`sys_approval_request.status offers exactly the contract statuses, in order`.

.changeset/changelog-ships-in-tarball.md

@@ -0,0 +1,100 @@
+---
+"@objectstack/account": patch
+"@objectstack/cli": patch
+"@objectstack/client": patch
+"@objectstack/client-react": patch
+"@objectstack/cloud-connection": patch
+"@objectstack/connector-mcp": patch
+"@objectstack/connector-openapi": patch
+"@objectstack/connector-rest": patch
+"@objectstack/connector-slack": patch
+"@objectstack/console": patch
+"@objectstack/core": patch
+"@objectstack/driver-memory": patch
+"@objectstack/driver-mongodb": patch
+"@objectstack/driver-sql": patch
+"@objectstack/driver-sqlite-wasm": patch
+"@objectstack/embedder-openai": patch
+"@objectstack/formula": patch
+"@objectstack/hono": patch
+"@objectstack/knowledge-memory": patch
+"@objectstack/knowledge-ragflow": patch
+"@objectstack/lint": patch
+"@objectstack/mcp": patch
+"@objectstack/metadata": patch
+"@objectstack/metadata-core": patch
+"@objectstack/metadata-fs": patch
+"@objectstack/metadata-protocol": patch
+"@objectstack/objectql": patch
+"@objectstack/observability": patch
+"@objectstack/platform-objects": patch
+"@objectstack/plugin-approvals": patch
+"@objectstack/plugin-audit": patch
+"@objectstack/plugin-auth": patch
+"@objectstack/plugin-dev": patch
+"@objectstack/plugin-email": patch
+"@objectstack/plugin-hono-server": patch
+"@objectstack/plugin-pinyin-search": patch
+"@objectstack/plugin-reports": patch
+"@objectstack/plugin-security": patch
+"@objectstack/plugin-sharing": patch
+"@objectstack/plugin-webhooks": patch
+"@objectstack/rest": patch
+"@objectstack/runtime": patch
+"@objectstack/sdui-parser": patch
+"@objectstack/service-analytics": patch
+"@objectstack/service-automation": patch
+"@objectstack/service-cache": patch
+"@objectstack/service-cluster": patch
+"@objectstack/service-cluster-redis": patch
+"@objectstack/service-datasource": patch
+"@objectstack/service-i18n": patch
+"@objectstack/service-job": patch
+"@objectstack/service-knowledge": patch
+"@objectstack/service-messaging": patch
+"@objectstack/service-package": patch
+"@objectstack/service-queue": patch
+"@objectstack/service-realtime": patch
+"@objectstack/service-settings": patch
+"@objectstack/service-sms": patch
+"@objectstack/service-storage": patch
+"@objectstack/setup": patch
+"@objectstack/studio": patch
+"@objectstack/trigger-api": patch
+"@objectstack/trigger-record-change": patch
+"@objectstack/trigger-schedule": patch
+"@objectstack/types": patch
+"@objectstack/verify": patch
+"create-objectstack": patch
+"objectstack-vscode": patch
+---
+
+chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)
+
+The AGENTS.md post-task checklist requires breaking changesets to carry their
+FROM → TO migration because "this text ships to consumers as `CHANGELOG.md`
+inside the npm package and is what an upgrading agent greps after the tombstone
+error." That delivery path was severed for 68 of the 69 publishable packages:
+npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike
+older npm versions — not `CHANGELOG.md`, and the canonical
+`"files": ["dist", "README.md"]` whitelist never named it. Measured on npm
+10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its
+70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it
+explicitly.
+
+The tombstone-error scenario is precisely the one where the repo is out of
+reach — the upgrading agent has `node_modules` and nothing else — so the
+migration text has to ride in the tarball. Every publishable package now
+declares `CHANGELOG.md` in `files`, and the canonical whitelist is
+`["dist", "README.md", "CHANGELOG.md"]`.
+
+The other half is the gate: `check:published-files` gains a fifth invariant,
+COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the
+always-required lint job, so the next package cannot silently sever the path
+again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves
+into the canonical set.
+
+Consumer-visible change: one more file per install (the package's changelog,
+e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key"
+node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was
+promised.

.changeset/docs-plugin-spec-onupgrade-example.md

@@ -0,0 +1,5 @@
+---
+---
+
+docs: fix the plugin-spec CHANGELOG example that still taught the retired
+`onUpgrade` hook as running automatically (#4212 family). Releases nothing.

.changeset/fix-stale-hono-changeset-ref.md

@@ -0,0 +1,4 @@
+---
+---
+
+Repo-plumbing only: the pending changeset `adapter-hono-auth-wildcard-yields` referenced the Hono adapter by its old `@objectstack/adapter-hono` name, which `changeset version` rejects because the workspace package is named `@objectstack/hono`. Renamed the entry; a full sweep of every other pending changeset (and `pre.json`) against the workspace found nothing else stale. Releases nothing by itself.

.changeset/query-ast-inert-request-surface.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/spec": major
+"@objectstack/plugin-security": patch
+---
+
+refactor(data)!: the QueryAST request surface stops declaring what no executor runs — `joins` and `windowFunctions` removed, six search flags and `aggregations[].filter` marked experimental, and the liveness ledger now governs the query surface (#4286)
+
+#4196 removed one declared-but-inert member from `FieldNode`. Applying the same
+method to the rest of the request surface (#4286) found 12 more members of
+`QueryAST` that no executor runs — `packages/objectql`'s `engine.ts` contains
+zero reads of any of them on the query path. This change dispositions the
+mechanical tiers and closes the gate that let the class stay invisible.
+
+**Removed (tombstoned): `query.joins` and `query.windowFunctions`.**
+
+- `joins` — no engine or driver ever read it; a query carrying it silently ran
+  as a single-table query. Related-record retrieval already has a live
+  spelling: `expand`. The orphaned `JoinNode` / `JoinNodeInput` /
+  `JoinNodeSchema` / `JoinType` / `JoinStrategy` exports are deleted with the
+  key (`data/JoinNode`, `data/JoinType`, `data/JoinStrategy` leave the
+  published JSON schemas).
+- `windowFunctions` — `find()` never applied it, so every OVER clause it
+  declared was silently dropped. The one live door is the SQL driver's own
+  `findWithWindowFunctions(object, query)` (driver-level, not on the
+  `IDataDriver` contract), and its input is a flat driver shape the spec
+  vocabulary never matched — `WindowFunctionNodeSchema` declared `field` /
+  `over` / `frame` members that door never read. The `WindowFunction` /
+  `WindowSpec` / `WindowFunctionNode` exports are deleted with the key.
+
+**FROM → TO**
+
+| Was | Now |
+| :--- | :--- |
+| `joins: [{ type: 'inner', object: 'customer', on: … }]` | `expand: { customer_id: { object: 'customer', fields: ['name'] } }` |
+| `joins` for one related column | `fields: ['customer_id.name']` (dotted path) |
+| `windowFunctions: [{ function: 'rank', … }]` in a query | `aggregations` + `groupBy`, or rankings in report/dashboard metadata |
+| OVER-clause SQL from an embedder | `sqlDriver.findWithWindowFunctions(object, { windowFunctions: [{ function, alias, partitionBy?, orderBy? }] })` |
+
+The one-line fix: **delete the key**. Both are `retiredKey()` tombstones on the
+non-strict `BaseQuerySchema`, so authoring either fails `tsc` (input type
+`never`) and a query still carrying one — even as an empty array — fails to
+parse with the prescription itself. `QueryAST` is a request shape, never stored
+in stack metadata, so there is no `os migrate meta` step: the removals are
+registered as protocol-18 **semantic** migrations (`query-joins-retired`,
+`query-window-functions-retired`), the #4196 precedent.
+
+Compat note for the REST boundary: both names remain **reserved** list-query
+parameters while the tombstones live (`retiredKey()` keeps a key in
+`keyof QueryAST`, which feeds `RESERVED_LIST_QUERY_PARAMS`), so nothing changes
+for objects with fields named `joins`/`windowFunctions` — the un-reservation
+happens when the tombstones age out, and is called out in
+`metadata-protocol`'s `QUERY_AST_KEYS` comment for whoever does it.
+
+**Marked `[EXPERIMENTAL — not enforced]` (no wire or compat impact):**
+`search.fuzzy` / `operator` / `boost` / `minScore` / `language` / `highlight`
+(the ADR-0061 expansion reads only `query` + `fields`) and
+`AggregationNode.filter` (a SQL `FILTER (WHERE …)` affordance neither the SQL
+builders nor the in-memory fallback applies). Authoring one is now a
+declaration, not a silent no-op.
+
+**Deliberately NOT dispositioned here** (they want a maintainer call, #4286
+steps 3–4): `having` (the strongest enforce candidate — `engine.aggregate()`
+currently rebuilds the driver AST without it), and `cursor` / `distinct`
+(shipped SDK producers `QueryBuilder.cursor()` / `.distinct()`; `distinct` is
+mis-wired — its only observable effect is suppressing the REST list count).
+All three are recorded `dead` with evidence in the new ledger.
+
+**The gate:** `QuerySchema` joins the liveness ledger through the gate's
+`SPEC_ONLY_SCHEMAS` override (the `webhook` precedent) as governed type
+`query` — the first governance of what *callers* write into a query rather
+than what authors write into metadata files. `packages/spec/liveness/query.json`
+classifies all 27 walked members (15 live with evidence, 7 experimental via
+describe markers, 5 dead), so the next declared-but-inert request member fails
+CI instead of needing a person to notice it.
+
+`@objectstack/plugin-security` (patch): the FLS predicate guard's
+`windowFunctions` walk is pruned — the clause no longer exists to leak through.
+The `having` and `aggregations[].filter` walks stay, deliberately: those
+members remain declared, and the guard being ready is what makes enforcing
+them later safe.

.changeset/register-field-file-collection-proof.md

@@ -0,0 +1,4 @@
+---
+---
+
+chore(spec): register the `adr0104-field-file-collection` dogfood proof tag in the ADR-0054 registry, honestly unbound — the collection contract it guards is `lifecycle` on the system `sys_file` object, already bound to `data-lifecycle`. Gate-only (`packages/spec/scripts/`, not published), so this releases nothing.

.changeset/wait-timeout-keys-retired.md

@@ -0,0 +1,42 @@
+---
+'@objectstack/spec': major
+'@objectstack/service-automation': patch
+---
+
+feat(spec)!: retire `waitEventConfig.timeoutMs` / `.onTimeout` — `wait` never had a timeout (#4158)
+
+Both keys described a timeout and neither delivered one, so protocol 18 removes the pair
+rather than leaving a promise the runtime does not keep (PD #10).
+
+- **`onTimeout`** had **zero** readers. No path ever inspected it, so neither `'fail'` nor
+  `'continue'` ever happened — and its `.default('fail')` stamped a decision nothing made
+  onto every wait node. The showcase set `onTimeout: 'continue'`, which did nothing.
+- **`timeoutMs`** said *"maximum wait time before timeout"* while its only reader used it
+  as the timer **duration** when `timerDuration` was absent. It did something, just not
+  what it claimed.
+
+Together they declared a timeout `wait` does not have: a run resumes when its timer
+elapses or its signal arrives, never on a deadline. Real timeout semantics are left
+unimplemented deliberately — they should be built to a requirement, not retrofitted to
+fit two keys that happened to be declared.
+
+`timeoutMs` **converts to `timerDuration`** rather than being dropped, because that is
+what it did. It is stringified on the way: the target is `z.string()` while `timeoutMs`
+was `z.number()`, and `parseIsoDuration` reads a bare numeric string as milliseconds — so
+`timeoutMs: 60000` and `timerDuration: '60000'` are the same wait. Moving the number
+unstringified would have produced a block that no longer parses, which a test pins. With
+`timerDuration` already set it is dropped instead: the executor's `??` never looked past
+the duration, so it was already dead metadata.
+
+Both leave the **load path** (`retiredFromLoadPath`), which is the registry's existing
+split: a key retired for being *renamed* keeps a load window, because punishing an author
+for a spelling nobody warned them about is pointless; a key that **misdescribed itself**
+does not, because silently absorbing it lets the author keep believing they configured a
+timeout. That is why `api.requireAuth`, the tool/app/flow inert keys and RLS `priority`
+all left it too. The migration chain converts stored sources mechanically; the schema
+tombstones name the replacement.
+
+One fixture interaction worth recording: the #4045 lift fixture used
+`waitEventConfig.timeoutMs` to demonstrate its fourth ledger entry, and the fixture
+harness replays the whole table — so its `after` described an end state protocol 18 makes
+unreachable. It now lifts `eventType` instead. The harness caught this itself.