Merge origin/main into claude/issue-20444-empty-operator-engine-arms

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

Author: claude

.changeset/20233-datasource-filter-action-data-element-migration-guidance-tracker-free.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): `os migrate meta` guidance for the `datasource-*`, `filter-*`, `action-*`, `data-*` and `element-*` migration entries states each lesson in words instead of citing tracker numbers
+
+Clause-②: no
+
+The ADR-0087 semantic entries of the `datasource-*` family (the publish-time credential,
+placeholder and URL refusals, and the bound-secret pairs a mongo datasource cannot use),
+the `filter-*` family (the retired `$regex`, the `$between` endpoint refusals and the
+comparand shapes the save door now refuses), the `action-*` family (the retired
+descriptor key, the `resumeAuthority` default flip, the action-session rename, the bulk
+dispatch contract and the engine facade's query envelope), the `data-*` family (the
+retired driver and engine contract members, the retired field-changed event and two
+duration keys renamed with their unit) and the `element-*` family (the filter rule array
+at the page binding and the element and block doors) are printed by `os migrate meta` as
+the header, `why:` and `verify:` lines of a manual change. Their text sent the reader to
+issue-tracker, decision-batch and ruling-record numbers — some of which no longer
+resolve, and some in other repositories — for what a ruling, measurement or fix had
+decided; it now says what was decided, in the sentence being read. ADR ids are kept.
+
+Text only: no entry id, `surface`, `from` / `to`, conversion or matching logic changes,
+and the chain rewrites exactly what it rewrote before. The generated migration registry,
+`spec-changes.json` and the protocol upgrade guide carry the same text.

.changeset/20289-os-test-names-tags.md

@@ -14,4 +14,4 @@ A Quality Protocol suite's `name`, each scenario's `name` and `description`, and
 - **`--tags TAG[,TAG...]`** runs only the scenarios carrying AT LEAST ONE of the listed tags (any-of, exact, case-sensitive) — the comma-list reading of Odoo's `--test-tags` and the everyday use of Playwright's `--grep @a|@b`. With the flag, an untagged scenario is left out. Left-out scenarios are **deselected**: not run, counted on the summary (`--tags smoke selected 1 of 4 scenarios; 3 deselected (not run, not counted as passed).`), never counted as passed. A requested tag that no loaded scenario carries is named on the summary. An empty entry (`--tags smoke,`) is refused before anything runs. Without the flag nothing changes: every scenario runs.
 - **Exit status.** A selection that matches no scenario takes the posture an empty pattern already has: exit `0` with `No scenario matched --tags …`, and exit `1` under `--fail-on-empty`, whose description now covers both cases. The `Found N test suites.` line and the `SUCCESS: All N scenarios passed.` / `FAILED: …` summary lines keep their spelling.
 - **`@objectstack/core`:** `QA.TestResult` gains `scenarioName` and `description` on every result, and `suiteName` on every result `runSuite` produces (absent only from a lone `runScenario` call, which has no suite).
-- **`@objectstack/spec`:** `TestScenario.requires` (`params`, `plugins`) is still checked by nothing — its describe() now says **NOT CHECKED** instead of reading as a guard, so a scenario that declares a plugin the target lacks still runs, and the unmet requirement surfaces only as whatever failure it causes, if any. The liveness ledger (`liveness/qa.json`) moves the four keys above to `live`, citing their readers.
+- **`@objectstack/spec`:** the liveness ledger (`liveness/qa.json`) moves the four keys above to `live`, citing their readers. `TestScenario.requires`, the family's fifth key, is checked in this same release and has its own note: an unmet `params` or `services` entry skips the scenario with its reason, and `requires.plugins` is retired into `requires.services`.

.changeset/20289-requires-services-skip.md

@@ -0,0 +1,100 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/cli': minor
+---
+
+feat(spec,core,cli)!: a scenario's `requires` is checked before it runs — unmet `params` or `services` SKIP it with a reason; `requires.plugins` is retired into `requires.services` (#20289)
+
+Clause-②: yes (narrowing)
+
+**BREAKING** — shipped as `minor` under the launch-window convention
+(`check-changeset-no-major` refuses `major` until GA; breaking-ness is carried by
+this banner, the `(narrowing)` arm above and the ADR-0087 disposition below,
+never by the level).
+
+A Quality Protocol scenario's `requires` block declared preconditions —
+`params` (environment variables) and `plugins` (plugins that must be loaded) —
+that nothing checked: measured on a stub target, a scenario naming a missing
+plugin and an unset variable reported PASSED exactly like its no-requirements
+control. ADR-0049 enforce-or-remove, verdict ENFORCE (the mainstream has
+declared preconditions: JUnit `@EnabledIfEnvironmentVariable`, pytest `skipif`),
+ruled B for the shape: each key is judged against something `os test` can
+actually observe.
+
+- **`requires.params`** — each variable must be set to a non-empty value in the
+  environment of the process running `os test` (not the target server's, which a
+  suite cannot see). An empty value counts as unset: an unconfigured CI secret
+  arrives as an empty string.
+- **`requires.services`** (new) — each entry is a discovery service key
+  (`CoreServiceName`: `auth`, `automation`, `analytics`, `ai`, `storage`, …; a
+  misspelling is refused when the suite loads) that the target must declare
+  `enabled` with status `available` in its discovery document (ADR-0076 D12).
+  It is read from the discovery request the HTTP adapter already makes once per
+  run; a suite that requires no service issues no extra request.
+- **SKIPPED.** A scenario with an unmet entry runs no step — `setup` included —
+  and `os test` prints it with its reason, naming every unmet entry and, for a
+  service, the services the target does declare available:
+  `Skipped: requires.services 'ai' is not available on the target (enabled: false, status: unavailable). The target declares available: auth, data, metadata.`
+  It is counted on its own — `SUCCESS: 3 scenarios passed. 1 skipped (not run, not counted as passed).` —
+  and never as passed. Skips alone exit `0`; a run in which EVERY selected
+  scenario was skipped prints `No scenario ran: …` instead of `SUCCESS`, exits
+  `0`, and exits `1` under `--fail-on-empty`. With nothing skipped, the summary
+  lines keep their spelling.
+- **`@objectstack/core`:** `QA.TestResult` gains `status` (`'passed' | 'failed' | 'skipped'`)
+  and, on a skipped result, `skipped` (`reason`, `unmet[]`, `availableServices`);
+  `passed` stays and is `false` on a skip. `TestRunner` takes an optional
+  `{ env }` (default: this process's environment), and `TestExecutionAdapter`
+  gains an optional `readTargetServices()` — `HttpTestAdapter` answers it from
+  its one discovery probe. An adapter without it skips a service requirement
+  rather than running it.
+
+```
+FROM  { "id": "ai-summary", "requires": { "plugins": ["@objectstack/service-ai"] }, "steps": [...] }
+      -> ran anyway; the missing plugin surfaced as whatever failure it caused, or passed
+TO    -> os test refuses the suite at load:
+           ✗ scenarios.0.requires.plugins: `scenarios[].requires.plugins` was removed in
+             @objectstack/spec 17.5.0 (ADR-0049 enforce-or-remove) — nothing ever checked it: …
+             Delete the key and name the service the scenario needs in `requires.services`, …
+             Plugin → service: @objectstack/service-analytics → analytics, @objectstack/plugin-auth → auth, …
+
+FROM  { "requires": { "services": ["ai"] }, … }   (new key)
+TO    -> against a target whose discovery does not declare `ai` enabled and available:
+           ⏭️  Scenario: Summarise an account [ai-summary] (skipped)
+              Skipped: requires.services 'ai' is not available on the target (…). The target declares available: …
+```
+
+**Fix.** `requires.plugins: ["<package>"]` → `requires.services: ["<service>"]`,
+using the mapping the refusal prints (derived from `CORE_SERVICE_PROVIDER`, the
+provider table discovery itself reports): `@objectstack/plugin-auth` → `auth`,
+`@objectstack/service-analytics` → `analytics`, `@objectstack/service-automation`
+→ `automation`, `@objectstack/service-storage` → `storage`, and so on; the `ai`
+service is provided by ObjectStack Cloud/Enterprise. A plugin that fills no
+discovery service slot has no service to require — gate that scenario with a
+`params` variable or select it with `--tags`. `tsc` refuses `plugins` at a typed
+authoring site (its input type is `never`). A `TestResult` consumer that counted
+`!passed` as a failure should read `status` — a skipped result is `passed: false`
+and is not a failure.
+
+**What does not change.** A scenario without `requires` runs exactly as before,
+and a suite that requires no service issues no discovery request it did not
+already issue.
+
+### The retirement kit
+
+- **Schema.** `TestScenarioSchema.requires` is a non-strict `z.object()`, so
+  `plugins` is a `retiredKey()` tombstone carrying its prescription (a bare
+  deletion would have stripped it in silence); `services` is new, closed over
+  `CoreServiceName`.
+- **ADR-0087.** `RETIRED_KEYS_BY_MAJOR[18]` gains `qa/TestScenario:requires.plugins`.
+  No D2 conversion: a QA suite is a loose JSON file `os test` loads, never a
+  stack collection member or a stored row. The family's D3 entry,
+  `qa-scenario-requires-plugins-retired`, carries the prescription to
+  `os migrate meta` and the upgrade guide.
+- **Ledger and docs.** `liveness/qa.json` moves `qa.scenarios.requires` from
+  `dead` to `live`, citing the runner's judgement and the adapter as producer;
+  `state-counts.md` moves `qa` to 9 live / 0 dead. The `os test` section of the
+  CLI reference documents the check, the skip line and the exit posture, and the
+  generated `qa/testing` reference page is regenerated.
+
+<!-- adr-0087: registered qa-scenario-requires-plugins-retired -->

.changeset/20450-view-filter-operator-input-typed.md

@@ -0,0 +1,30 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: a view filter rule's `operator` is typed as the canonical `ViewFilterOperator`, not `unknown`
+
+**BREAKING for TypeScript code that writes a view filter rule through a published type**: `ViewFilterRule`, and every carrier of it — `ListView.filter`, a view tab's `filter`, `InterfacePageConfig.filterBy`, and the related-list, record-picker and `object-*` block filter doors. A narrowing of a published TYPE, landing as `minor` (the bump level is not the carrier; this banner and the disposition below are). The runtime accept set does not move at all: no schema's parse, no value and no export changes.
+
+`operator` is a `z.preprocess` over the alias fold, and zod types a preprocess's input from its function's parameter. That parameter was `unknown`, so `ViewFilterRule['operator']` was `unknown`: `{ field: 'status', operator: 42 }` compiled as a rule on every carrier, and was refused only when the schema parsed it. The input type is now `ViewFilterOperator`, the vocabulary the alias table's own contract says new producers emit, so an alias spelling or a non-string is refused by the compiler.
+
+What does not change:
+
+- **The runtime.** `ViewFilterRuleSchema` still folds every legacy spelling it folded before (`eq`, `gt`, `notIn`, `isNull`, …) to its canonical id, and still refuses a non-string at `operator` with the enum's own issue. Stored `sys_metadata` rows, YAML and JSON bodies and plain-JS producers that carry an alias parse exactly as before, and `os validate` answers as before.
+- **`normalizeFilterOperator`.** Its parameter stays `unknown`: it exists to fold untyped stored metadata, and its callers pass raw strings by design.
+- **The parsed type.** `ViewFilterRuleParsed['operator']` was already the canonical enum.
+
+## FROM → TO
+
+| Wrote (TypeScript) | Write instead |
+| --- | --- |
+| `{ field: 'status', operator: 'eq', value: 'open' }` | `{ field: 'status', operator: 'equals', value: 'open' }` |
+| `{ field: 'amount', operator: 'gte', value: 100 }` | `{ field: 'amount', operator: 'greater_than_or_equal', value: 100 }` |
+| `{ field: 'stage', operator: 'notIn', value: ['lost'] }` | `{ field: 'stage', operator: 'not_in', value: ['lost'] }` |
+| `operator: someString` (a value typed `string`) | type the unvalidated rule `unknown` and `ViewFilterRuleSchema.safeParse` it, or fold it with `normalizeFilterOperator` and check it against `VIEW_FILTER_OPERATORS` first |
+
+The one-line fix: write the canonical id. Every alias maps to exactly one, and `VIEW_FILTER_OPERATOR_ALIASES` is that map; the rewritten rule selects the same rows, because the schema already folded the alias to that id.
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered view-filter-rule-operator-input-canonical -->

.changeset/20478-dispatcher-meta-layers.md

@@ -0,0 +1,37 @@
+---
+'@objectstack/rest': minor
+'@objectstack/runtime': patch
+---
+
+fix(rest, runtime): the runtime dispatcher serves the layered view, `GET /meta/:type/:name/layers` and the deprecated `?layers=` flag, as `RestServer` serves it (#20478)
+
+Clause-②: yes (widening) — `@objectstack/rest`'s root entry gains three value exports (`createMetaLayeredAnswer`, `wantsMetaItemLayers`, `metaItemLayersDeprecationHeaders`) and two type exports (`MetaLayeredAnswer`, `MetaLayeredRequest`). Nothing any published version exported is removed, renamed or narrowed. `@objectstack/runtime` publishes no new surface and stays a `patch`.
+
+A host that mounts only the `${prefix}/*` catch-all (`createHonoApp`, and any
+adapter written on the public `HttpDispatcher` API) serves `/meta` through the
+runtime dispatcher. Until now, on such a host:
+
+- **`GET /meta/:type/:name?layers=true` answered the plain read.** The body was
+  `{ type, name, item }` with a `200`, so a client reading `code`, `overlay` or
+  `effective` read `undefined`. There was no `Deprecation` header and no `Link`
+  to the successor. An author (a caller the item's save door admits) was served
+  the app pruned, where the layered view serves them every layer whole.
+- **`GET /meta/:type/:name/layers` was no route.** It answered a located
+  `404 ROUTE_NOT_FOUND`.
+
+Both spellings now answer what `RestServer` answers: the three layers, each
+judged by the per-caller read gate under the stored-version doors' policy
+(whole for a caller who may save the item, pruned as the plain read prunes it
+for everyone else), each projected through the object-schema field mask, and
+`private, no-store` when the caller's field visibility could not be determined.
+The read is scoped to the caller's vetted organization and to `?package=`. The
+flag's answers, refusals included, carry `Deprecation: true`, and a `Link` to
+`/layers` built from the request's own URL (every `createHonoApp` request
+carries one; a host that hands `dispatch()` no URL gets `Deprecation` alone). The route answers `501 NOT_IMPLEMENTED` where the protocol has no
+layered read, and the flag is then the plain read, on both transports.
+
+**What changed.** Everything `RestServer`'s layered helper does after the store
+read moved, unchanged, into `createMetaLayeredAnswer`, and the flag's parse and
+headers into `wantsMetaItemLayers` and `metaItemLayersDeprecationHeaders`. The
+dispatcher's `/meta` domain calls all three. `RestServer`'s own answers are
+unchanged: every existing REST test passes unedited.

content/docs/deployment/cli.mdx

@@ -1715,9 +1715,38 @@ out are **deselected**: not run, counted on the summary
 and never counted as passed. A listed tag that no loaded scenario carries is named
 on the summary, since a typo narrows the run without failing it, and an empty entry
 (`--tags smoke,`) is refused before anything runs. Without the flag every scenario
-runs. A scenario's `requires` block is **not checked**: a scenario that names a
-plugin the target does not load still runs, and the unmet requirement surfaces
-only as whatever failure it causes, if any — the scenario can still pass.
+runs.
+
+**A scenario's `requires` is checked before its first step.** Two keys, each
+judged against something `os test` can observe:
+
+- `requires.params` — environment variables that must be set to a non-empty
+  value **in the process running `os test`** (not on the target server, which a
+  suite cannot see): `"params": ["BILLING_SANDBOX_KEY"]`.
+- `requires.services` — service keys the target must declare in its discovery
+  document as `enabled` with status `available`, read from the same discovery
+  request the runner already makes once per run: `"services": ["ai", "analytics"]`.
+  The keys are the discovery service names (`auth`, `automation`, `storage`, …),
+  and a misspelled one is refused when the suite loads.
+
+A scenario with an unmet entry is **skipped**: none of its steps runs — `setup`
+included — and its line says why, naming every unmet entry and, for a service,
+the services the target does declare available:
+
+```text
+  ⏭️  Scenario: Summarise an account with the AI service [ai-summary] (skipped)
+     Skipped: requires.services 'ai' is not available on the target (enabled: false, status: unavailable). The target declares available: auth, data, metadata.
+```
+
+A skipped scenario is counted on its own —
+`SUCCESS: 3 scenarios passed. 1 skipped (not run, not counted as passed).` — and
+is never counted as passed. Skips alone do not fail a run, but a run in which
+**every** selected scenario was skipped proved nothing: it prints
+`No scenario ran: all 2 selected scenarios were skipped on unmet requirements.`
+instead of `SUCCESS`, exits **0**, and exits **1** under `--fail-on-empty`. The
+retired `requires.plugins` is refused when the suite loads, with the plugin →
+service mapping in its message: no served surface lists loaded plugins, so it
+was never checkable, and `requires.services` asks the question it stood for.
 
 **A pattern that matches no suite is not a failure by default.** The run prints
 `Found 0 test suites.` — the same machine-readable line a full run prints, so a