Merge remote-tracking branch 'origin/main' into claude/discussion-13564-a38847

Author: hotlong

.changeset/action-description-and-params-translation.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): an action's `description` and its parameter dialog now honour the translation bundle
+
+`translateAction` overlaid only `label`, `confirmText`, `successMessage` and
+`resultDialog`. The keys for the rest were already there — the translation
+schema declares `_actions.ACTION.description` and
+`_actions.ACTION.params.PARAM.{label, helpText, placeholder, options}`, and the
+translation linter validates both, reporting a parameter key the action does not
+declare with a did-you-mean naming the ones it does. So the keys parsed, they
+linted, and they resolved to nothing: a translated deployment rendered a
+translated action button that opened an untranslated form, because an action's
+`description` is the explanatory line under the dialog title and its
+parameters' `label` / `helpText` / `placeholder` / option labels are the rest of
+that dialog.
+
+They are applied now, wherever the action is served — the REST metadata read,
+OpenAPI, MCP — and through `globalActions` for an action that belongs to no
+object, the same object-scoped-first order every other action key already used.
+
+Parameters are matched by `name`, falling back to `field` for a field-backed
+parameter that names no key of its own: the same rule the linter collects
+parameters by, so a key the linter accepts is a key the resolver finds. Option
+labels are matched on the stored option `value`, since the authored side is an
+array of options while the translation side is a `value` to label map.
+
+Nothing changes for a bundle that carries none of these keys: the authored text
+is kept, the parameter array keeps its identity, and a bundle key naming a
+parameter the action does not declare is ignored rather than invented into the
+dialog. No schema, no validator and no accepted shape moves — every key applied
+here was already declared and already validated.

.changeset/action-engine-facade-find-filter.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionEngineFacade.find` declares its second parameter as a FILTER, not an ObjectQL envelope (#14175)
+
+`find(object, query: Record<string, unknown>)` documented nothing, and its
+parameter carried the name of the envelope every other read on the platform
+takes. The runtime (`buildActionEngineFacade`,
+`packages/runtime/src/action-execution.ts`) treats the argument as the bare
+`where` half — wrapping a non-empty one as `{ where: filter }` and passing
+`{}` through unwrapped — so a handler that passed the envelope got
+`{ where: { where: … } }`, matched nothing and returned `[]` with no error,
+while its one unfiltered read kept working. A hand-written test double built
+on the same belief passed every assertion; an application's headline action
+was a silent no-op for its whole life under a green suite.
+
+The member is now `find(object, filter: FilterCondition)` — the published
+`QueryAST.where` type — with a doc comment stating the contract, the runtime's
+wrap, and both limbs (envelope wrapped; empty passed through); the facade
+docblock points at it. The parameter's TYPE now says what the runtime does
+at the one place a handler author reads.
+
+Compile-layer signal only, shipped as `patch` (the #12615 precedent — a
+compile-time narrowing with no change in what parses or runs): no runtime
+behaviour changes, nothing changes in what the facade accepts or returns, and
+the narrowing bites only a primitive or a mistyped `$and` / `$or` / `$not`.
+⚠️ It does NOT refuse `{ where: … }` at compile time — `FilterCondition`'s
+string index signature admits `where` as a field name — so the compile-time
+bar is partial and the doc comment is the contract of record. An
+implementation typed with the old `Record<string, unknown>` still satisfies
+the interface (method parameters are bivariant), so nothing constructing the
+facade changes.

.changeset/action-method-example-data-door-path.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `ActionSchema.method`'s worked example now names the shipped data door
+
+The `method` docblock's only worked example of a `type: 'api'` PATCH pointed at
+`/api/v1/sys_api_key/{id}` — a path the router never mounts. The shipped data
+door composes as `getApiBasePath()` + `crud.dataPrefix` + `/:object/:id`, so the
+update endpoint is `PATCH /api/v1/data/:object/:id` on a default host. The `/data`
+segment was missing, and nothing catches the difference at authoring time:
+`objectstack validate` does not check `target`, `type: 'api'` has no author-time
+route validation, and the action parses green, renders, is clickable, and 404s at
+the click — the same silent shape as an unregistered handler, arriving through a
+doc example. This mattered more than an ordinary stale comment because it is the
+one worked example of that route on the published contract.
+
+The example now reads `/api/v1/data/sys_api_key/${ctx.recordId}`. The object name
+is unchanged on purpose — the error was the path STRUCTURE, not which object the
+example picks — and the id is spelled with the `${ctx.X}` interpolation that
+`target`'s own docblock documents, so the two placeholder conventions in this one
+schema stop reading as interchangeable (a bare `{recordId}` is `newTabUrl`'s
+convention alone).
+
+Two things the corrected example now says that the old one did not:
+
+- **The full path is host-dependent.** Under `enableProjectScoping` with
+  `projectResolution: 'required'` only
+  `/api/v1/environments/:environmentId/data/:object/:id` is registered, so even a
+  correctly spelled unscoped path still 404s on such a host. An author copying a
+  full path needs to know which base their host mounts.
+- **A single-record field write has a declarative form now.** `operation: 'update'`
+  with `patch` writes the current record on the data plane as the caller, with no
+  endpoint, method or id placeholder to spell. The `type: 'api'` + `PATCH` form
+  remains the way to call an explicit endpoint.
+
+Documentation only: no schema member, no `.describe()` and no runtime behaviour
+changes. It is a `patch` rather than a `skip-changeset` because the corrected text
+publishes — `@objectstack/spec` ships `dist/**` and `src/**/*.zod.ts`, and both
+carry this docblock.

.changeset/action-row-update-declarative.md

@@ -0,0 +1,19 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): a row action gets the declarative single-record field write — `operation: 'update'` + `patch` (#14092)
+
+The most common action in any app — set a field on the current record — had no declarative form for a ROW action while the BULK form was fully declarative: a list view's `bulkActionDefs` `{ operation: 'update', patch, visible }` runs on the data plane under the caller's own permissions with hooks and validations firing, and the identical intent on one row had to be a hand-written, system-elevated handler that re-established that authorization by hand. Maintainer ruling 2026-09-01: the row action gets the bulk def's declarative counterpart.
+
+`ActionSchema` now accepts, mirroring the bulk vocabulary word for word and inventing no second spelling:
+
+- `operation: 'update'` — the declarative single-record field write. One member by ruling; `'delete'` and `'custom'` are refused with the reason (a row delete is the object's own affordance; `'custom'` means "dispatch the action this def names", and on a row the action is already the action).
+- `patch: Record<string, unknown>` — static field values written to the current record, merged UNDER the values `params` collects (a param of the same name wins). Passed through verbatim.
+- The action's existing `params`, `visible`, `confirmText` and `undoable` keys are reused, nothing duplicated; `undoable` now has its anchor — the patch names exactly the fields whose prior values are captured.
+
+Key shape, pinned for contract review: `operation` is a parallel key beside `type`, not a new `ActionType` member. `type` stays at its default `'script'` — the platform action route, which is where the write is performed — and answers WHERE the action dispatches; `operation` answers WHAT the platform does there. Every contradiction is refused at its own path with a prescription: any other explicit `type`, `target`, `body`, `method`, `bodyExtra`, `bodyShape`, `recordIdParam`/`recordIdField`, `onSuccess`, `opensInNewTab`/`newTabUrl` beside `operation: 'update'`; `patch` without it; `operation: 'update'` with neither `patch` nor `params`; a `list_toolbar` location (no current record). `defineStack` refuses a standalone `operation: 'update'` action that names no `objectName` (an object-embedded one is bound by the object it is written on). An inline page-element action cannot carry the keys at all.
+
+Executor contract for the downstream halves (runtime action dispatcher, objectui row-action executor — separate cards; both keys are `planned` in the liveness ledger until they land): a single-record data-plane update of the CURRENT record executed AS THE CALLER and never system-elevated, so the caller's object/row/field permissions, the object's hooks and its validations fire exactly as for a user edit; a caller who cannot read or write the row is refused; `undoable` captures the prior values of exactly the fields written.
+
+Pure widening: nothing that parsed before stops parsing — `operation` and `patch` were unknown keys on this strict shape, and every new refusal is keyed on one of them.

.changeset/adr0130-metadata-door-reads-packages.md

@@ -0,0 +1,75 @@
+---
+"@objectstack/metadata": patch
+"@objectstack/core": minor
+"@objectstack/objectql": patch
+"@objectstack/runtime": patch
+---
+
+fix(metadata): register a `packages[]` artifact per package at the metadata door so every object has one owner across every door (#14599)
+
+A release artifact carrying `packages[]` (ADR-0130 D4) was read at the metadata
+door as if it carried one package: `MetadataPlugin._parseAndRegisterArtifact`
+iterated the **flattened top level** and stamped every item with the artifact's
+own `manifest.id`. For an artifact composed with `composeStacks(…, { manifest:
+'preserve' })` that id is one arbitrary member's — `selectManifest`'s `'last'`
+pick — so a two-package artifact registered the **module's** object under the
+**App** package's identity, while the ObjectQL load path, reading the same
+artifact's `packages[]`, owned it under the module's.
+
+The platform then held two answers to "who owns this object", and which one a
+consumer saw depended on the door it went through. Measured on a real boot of
+`examples/app-multi-package`:
+
+- `GET /api/v1/meta/object` served `crm_order` **twice** — the list merge keys
+  slots by `${packageId}${name}`, so the two differently-attributed copies
+  landed in two slots;
+- `GET /api/v1/meta/object?package=<the App package>` returned the **module's**
+  object, because the App-stamped copy was re-ingested into the registry as that
+  package's contribution;
+- the layers door named the App package while the item door and
+  `GET /api/v1/packages` named the module;
+- Studio's Data pillar for the App package listed the module's object — ADR-0130
+  Consequences §1.3a ("Studio's scope is the package") did not hold.
+
+**The door now reads both shapes, and attributes every item to the body it was
+found in.** `packages` present → each assembled package body's collections are
+registered stamped with **that body's** id; `packages` absent → the single
+`manifest` branch runs exactly as before (D7). The owner is read off the body an
+item was found in — never reverse-derived by matching a top-level item's name
+against a name-to-package index, which would be the second metadata-identity
+resolution path #14512's triage rejected by name.
+
+**Ordering and the entry gate are reused, not re-derived (D5).** The door calls
+the same `resolveArtifactPackageOrder` the ObjectQL load path calls, so the two
+readers of one `packages[]` cannot disagree about the registration order **or**
+about which artifacts are loadable at all.
+
+⚠️ **`resolveArtifactPackageOrder` / `artifactPackageId` moved to
+`@objectstack/core`** — hence the `minor` there. They were in
+`@objectstack/objectql`, which **depends on** `@objectstack/metadata`, so the
+metadata door could not import them from where they lived; `@objectstack/core`
+already owns `resolvePluginOrder` and is already a dependency of both readers,
+so hosting them there adds **no edge** to the package graph. `@objectstack/objectql`
+re-exports both under their existing names — its published surface is unchanged,
+which is why it is graded `patch`. `@objectstack/runtime` is `patch` for the
+dispatcher error vocabulary's `file:` anchors, repointed at the new path.
+
+**Single-package artifacts are byte-for-byte unaffected (D7)**, measured rather
+than asserted: the whole `manager.register` sequence for a single-`manifest`
+artifact — every call, in order, with the id and version each item was stamped
+with — is pinned as a literal in
+`packages/metadata/src/plugin-artifact-packages-attribution.test.ts` and was
+recorded identically on both legs of the ablation. A real boot of
+`examples/app-todo` answers every door identically before and after.
+
+**Nothing a booted instance can see today disappears.** Every live
+`ARTIFACT_FIELD_TO_TYPE` key is a member of `AssembledPackageBodySchema`
+(measured, not assumed), so iterating bodies loses no collection; and because
+`packages` composes by `concat`, an artifact whose top level carries a
+definition no package body repeats keeps it — registered once, attributed to the
+artifact's own identity, and logged, because it means the artifact's two halves
+disagree about what it ships.
+
+⛔ The **producer** half is untouched: `composeStacks` and `os build` keep
+emitting the flattened top level alongside `packages[]`. Whether they should is
+#14512's decision, not this door's.

.changeset/aliased-install-host-importer.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/types": patch
+---
+
+fix(types): an aliased install (`"foo": "npm:bar@1"`) is now found by the host importer's ESM-only fallback
+
+`createHostImporter`'s #14041 fallback finder verifies the one directory it
+consults — `<hostRoot>/node_modules/<key>` — by matching that directory's
+`package.json` `name` against the declared package name. An aliased install
+fails that check by construction: `{ "dependencies": { "foo": "npm:bar@1" } }`
+puts a manifest named `bar` at `node_modules/foo`. The finder answered
+`absent`, and an ESM-only aliased package therefore kept the pre-#14041 INSTALL
+wording — a confidently-wrong remedy sending an operator to run `pnpm install`
+against an install that is already correct, on a declaration shape
+`packageNameFromSpecifier`'s own documentation blesses.
+
+The declaration is now parsed for the name it promises: `npm:bar@1`,
+`npm:@acme/x@^2` and the aliased `workspace:bar@*` name the package installed
+under the key, so that is the manifest name the finder expects there. An
+aliased ESM-only package is rescued exactly as a plain one is, and an aliased
+install publishing nothing loadable gets the message about the PACKAGE's own
+shape instead of the INSTALL message.
+
+⚠️ The manifest-name check itself is NOT loosened — that check is what keeps
+the fallback strictly tighter than the CJS resolution it backs up (#4719's
+declaration gate, from the fallback side). What moved is the EXPECTATION, still
+authored by the host and still read out of the host's own `package.json`: an
+alias naming one package refuses a directory holding another, a non-aliased
+declaration is unchanged, and a value that is not a bare package name — a
+`workspace:` range, an alias carrying a subpath — yields no expectation to move
+to, so the key stays and today's refusal is kept. `link:` and `file:` name a
+LOCATION rather than a package, so no name is derivable from them at all; they
+keep the key expectation, and with it the conservative direction the finder had
+before.

.changeset/analytics-result-builtin-aggregate.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-analytics": minor
+---
+
+feat(spec,analytics): `AnalyticsResult.fields[].builtinAggregate` — a closed discriminator for a measure column whose display name is the server's built-in default (#14492)
+
+**What a consumer sees.** `queryDataset()` (and `POST /api/v1/analytics/dataset/query`,
+which relays the result verbatim) now carries an optional
+`fields[].builtinAggregate?: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count_distinct'`
+on a measure column. It is present exactly when the dataset measure behind the
+column declares an `aggregate` and **no** `label` — the producer then has nothing
+but the aggregate to name the column by, so it says which aggregate that is. It is
+absent whenever the author declared a label (a plain string or an inline locale
+map, even one with no entry for the request locale: an author's text is never
+re-labelled by a consumer), and absent on dimension columns and derived measures.
+The vocabulary is `AggregationFunction` (`data/query.zod.ts`), the one closed
+aggregate enum — no second spelling. `AnalyticsResultResponseSchema`
+(`api/analytics.zod.ts`) mirrors the member, refusing a spelling outside the enum.
+
+**Why.** An AI-built dashboard's "count of customers by status" chart showed the
+English axis title "Count" on a Chinese UI. The renderer (objectui
+`buildChartSeries()` / `labelOf()`) treats `fields[].label` as resolved author
+content and passes it through verbatim — correctly, since a real custom label
+("Tasks") must survive. What it could not tell apart was an author's text from
+the server's built-in default for a bare `count`. Guessing from the label text
+was refused (it would catch an author who really named a field `Count`, and break
+the moment the default is spelled in another language); translating on the
+server was not taken (it copies the front end's language decision into the
+producer and leaves nothing for a per-widget override). The ruling (2026-09-02,
+option B) is a structured discriminator on the contract: the consumer prefers a
+locale lookup keyed by `builtinAggregate` — mirroring its existing
+`report.aggregate.*` keys — and falls back to `label`, then `name`.
+
+**Producer-side changes.**
+
+- `@objectstack/service-analytics` — `queryDataset`'s measure enrichment sets
+  `builtinAggregate` from the dataset measure's own `aggregate` when the measure
+  has no authored `label`. Judged on the authored key, never on the resolved
+  string.
+- `@objectstack/spec` — the `dataset` create seed (`metadata-create-seeds.ts`)
+  drops its hardcoded `label: 'Count'` from the seeded `count` measure, so a
+  dataset created from Studio is a built-in default (wire: `builtinAggregate:
+  'count'`) instead of an authored English literal. `getMeta()` for such a
+  dataset now titles the metric by its name (`count`) rather than `Count`;
+  `CubeMeta.measures[].type` already carried the aggregate there.
+
+Purely additive: no key is removed or renamed, no authorable schema changes shape,
+and a consumer that ignores the member sees exactly the response it saw before.