Merge remote-tracking branch 'origin/main' into claude/issue-21320-agent-lifecycle-retired

Author: claude

.changeset/21286-cli-extension-tsdoc-discover.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': patch
+---
+
+The `kernel/cli-extension` module documentation no longer tells plugin authors to run `os plugins install`. Step 2, "Discover", said the plugin is listed in `@objectstack/cli`'s `oclif.plugins` array, or that users install it with `os plugins install`. Neither is true: `@objectstack/cli` declares no `oclif.plugins` and ships no plugin manager, so `os plugins` is not a command. The step now says what loads a plugin: oclif loads a plugin that the CLI's own `package.json` lists in both `oclif.plugins` and `dependencies`. To add a plugin's commands to `os`, build an `os` distribution whose own `package.json` lists the plugin in both places. The generated reference page carries the same text.
+
+Clause-②: no
+
+Documentation only. No schema, export or type changes.

.changeset/21334-view-container-cross-package-default.md

@@ -0,0 +1,31 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): a view container saved for an object another package ships no longer replaces that package's views or its default
+
+Clause-②: no
+
+- **What was wrong.** A runtime view container expands each member to `<object>.<key>`. A `list` that names no key becomes `<object>.default`, a `form` becomes `<object>.form`, and every member that names a key uses that key. Saved under another name, in another package or in none, for an object a code package ships, those expansions replaced that package's views of the same names on `GET /api/v1/meta/view?object=<object>`. The replacements were still stamped with the shipping package's `_packageId` and `_provenance: 'package'`.
+  - On an environment-scoped kernel, the by-name read `GET /api/v1/meta/view/<name>` kept the packaged view, so the two reads disagreed.
+  - On an unscoped kernel, the by-name read served the replacement too, for a container saved into a package or environment-wide.
+  - The container's own default kept `isDefault: true`. It either replaced the object's default view or stood beside it as a second list default.
+- **What it does now.** For an object a code package ships, a container that belongs to another package, or to none, expands every member under its own name:
+  - a `list` that names no key becomes `<object>.<container name>`;
+  - every other member becomes `<object>.<container name>.<key>`. That covers a `list` that names its key, each `listViews` and `formViews` entry, and `form`.
+
+  None of these views carries `isDefault`. Every name the shipping package serves answers its packaged view on both reads, unchanged, and the only `isDefault` views the object lists are the shipping package's.
+- **One exception.** When the shipping package itself serves `<object>.<container name>` (a container named after one of that package's keys), the container's default list becomes `<object>.<container name>.<container name>` instead.
+- **A container with no name of its own** expands nothing on such an object.
+- **What these views carry.** The container's own package as `_packageId` (none for a package-less container), and no other package's `_provenance` or protection envelope.
+- **What stays.** Three kinds of container expand exactly as before, `isDefault` included:
+  - a container bound to the package that ships the object;
+  - a package-less overlay of that package's own container, saved under that container's name;
+  - a container on an object no code package ships.
+
+  A write to `<object>.default` by its own name still overrides it on both reads.
+- **What changes for a caller.** Such a container's views are now served under new names:
+  - its default list as `<object>.<container name>`, instead of `<object>.default`;
+  - each keyed member as `<object>.<container name>.<key>`, instead of `<object>.<key>`.
+
+  A navigation `viewName` or a form-action `target` that used an old name to reach one of these views now reaches the shipping package's view. Use the new name instead.

.changeset/21365-objectql-echo-offset-window.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): the ObjectQL strategy's echoed `sql` renders an offset with no limit in the dialect's own spelling, so SQLite runs the statement it prints
+
+Clause-②: no
+
+**Before**, the ObjectQL strategy wrote its own row window into the statement it echoes: `LIMIT n` when a limit was set, then `OFFSET n` when an offset was. An `offset` with no `limit` therefore echoed a bare `OFFSET`, which SQLite's grammar does not have. Measured through `POST /api/v1/analytics/query` and `POST /api/v1/analytics/sql` on SQLite, for a composition served by the engine aggregate, with `order: { note: 'asc' }` and `offset: 1`: the rows were right (every group after the first), but the echoed `sql` and the `/analytics/sql` body both ended `ORDER BY "note" ASC OFFSET 1`, and SQLite refuses that statement with `near "OFFSET": syntax error`.
+
+**Now** the statement ends with the same window clause the native-SQL strategy runs, for the dialect of the driver that serves the object: `LIMIT -1 OFFSET 1` on SQLite, which runs and answers the same rows. One function renders the window for both strategies.
+
+**Unchanged.** The rows either strategy answers. A window with a `limit` keeps its bytes (`LIMIT 2 OFFSET 1`) on every dialect, and on PostgreSQL an offset with no limit still echoes `OFFSET 1` alone. A host that wires no `sqlDialect` hook gets the native strategy's dialect-neutral spelling, `LIMIT 9223372036854775807 OFFSET 1`. A date-bucketed dimension still echoes as `date_trunc(…)`, which SQLite does not run; this change touches only the window.

.changeset/21391-one-shot-boot-read-only.md

@@ -0,0 +1,24 @@
+---
+'@objectstack/cli': minor
+'@objectstack/runtime': minor
+---
+
+The CLI's one-shot commands no longer write to the database as a side effect of booting. No `os migrate *`, `os meta resync`, `os secret orphans` or `os storage orphans` run loads the app's inline seed data, apply and delete modes included, and every mode that writes nothing now boots read-only.
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) a CLI command's verdict on one edge, not a declaration: a no-write mode of os migrate value-shapes, os migrate recorded-by, os migrate resume, os secret orphans or os storage orphans pointed at a database that lacks a table it reads now exits 1 instead of creating the table and reporting nothing. No authorable key, spelling, export or stored shape moves: every stack parses and loads exactly as before, the write modes write exactly what they wrote before minus the seed loader's rows, and no stored row is read differently or rewritten. What an operator does about the refusal is point --database-url at the deployment's database or boot the deployment once, so there is no rewrite a ledger entry could carry. The other categories are closed on facts: both packages publish (not unpublished); no ADR-0087 id covers a command's verdict, and this diff adds none (not registered / already-registered); and the change is CLI behaviour plus one new optional runtime config key, not a TypeScript declaration change to an existing surface (not runtime-interface-only / type-surface-only). -->
+
+**BREAKING** — a no-write run of `os migrate value-shapes`, `os migrate recorded-by`, `os migrate resume`, `os secret orphans` or `os storage orphans` at a database that lacks a table it reads now exits 1, where it used to exit 0. It ships as `minor` under the launch-window convention for accept-set narrowings.
+
+**What was wrong.** Eight commands booted the full data stack in a mode their documentation says writes nothing: `os migrate value-shapes` (scan), `summary-nulls`, `files-to-references` and `recorded-by` (dry run), `os migrate resume` (list), `os secret orphans` and `os storage orphans` (report), and `os meta resync` without `--yes`. That boot ran schema sync and the app's inline seed loader. The seed loader upserts every seeded row, so each run bumped `updated_at`, stamped `organization_id` on seeded rows that had none, and put an operator's edit to a seeded row back to the seed's value. On `examples/app-crm` that was all 28 seeded rows on every run. On a database behind the app's schema, the boot also added columns and created tables. The apply and delete modes ran the same seed loader alongside the write the operator confirmed.
+
+**What changes for an operator.**
+
+- Every mode that writes nothing boots the way `os migrate plan` does: the schema sync is held back, no seed rows are written, and a SQLite file that does not exist is not created. The database is left byte-identical, and the report is the same as before.
+- No one-shot CLI boot loads the app's inline seed data. `--apply`, `--delete`, `os migrate resume --run` and `os meta resync --yes` write what they report and nothing else. Seeding stays with `os dev` and `os serve`.
+- The deferred schema sync now covers every SQL datasource the boot connects, not only the default one. `os migrate plan` lists a second datasource's pending tables, and `os migrate apply` creates them after you confirm.
+- One edge changes: a no-write run pointed at a database that lacks a table it reads (a SQLite file that does not exist, a database that was never booted, or the wrong `--database-url`) refuses and exits 1 instead of creating the table and reporting nothing. Point `--database-url` at the deployment's database, or boot the deployment once first. `os secret orphans --json` answers that refusal with `"error": "scan_failed"`.
+- `os migrate value-shapes --json` prints one JSON document when the scan fails its gate. It used to print a second one, `{"error":"EEXIT: 1"}`.
+
+**For embedders of `@objectstack/runtime`.** `createStandaloneStack` accepts `armLifecycleSweep` (default `true`). With `false`, the ADR-0057 lifecycle sweep (rotation, retention reaping, archiving and the dangling-reference audit that rides its clock) is never armed on that boot, and an explicit `sweep()` call on it returns an empty report. The CLI passes `false` on every one-shot boot.

.changeset/21409-analytics-row-wildcard-count-only.md

@@ -0,0 +1,121 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec)!: the analytics row wildcard `'*'` is admitted only where a `count` consumes it — a cube or dataset measure over `'*'` under any other aggregate, and a cube dimension over `'*'`, are refused at parse (#21409)
+
+Clause-②: no (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).
+
+`'*'` is the row wildcard: what a `count` aggregates (`COUNT(*)`), reading no
+field value. It is now admitted in exactly one place, a measure that counts:
+
+- `MetricSchema.sql` — a cube measure's `sql` — admits `'*'` under
+  `type: 'count'` only; under any other `type` it is refused at `sql`
+  (code `custom`).
+- `DatasetMeasureSchema.field` — an ADR-0021 dataset measure's `field` — admits
+  `'*'` under `aggregate: 'count'` only; under any other aggregate, or on a
+  measure with no aggregate (a `derived` one), it is refused at `field`
+  (code `custom`). A count may still omit `field`.
+- `DimensionSchema.sql` — a cube dimension's `sql` — never admits `'*'`
+  (code `invalid_format`): it takes the column path without the wildcard arm,
+  the pattern a dataset dimension's `field` already takes.
+
+Each refusal names the slot and the aggregate the author wrote, and prescribes
+the two ways out: a `count`, or a column. A column or a relationship path parses
+byte-identically to before on every slot, and so does a `count` over `'*'`.
+
+Why: no aggregate but `count` has a column to read over `'*'`, and a dimension
+has no aggregate at all, yet the contract admitted the wildcard on any measure
+and on a cube dimension, and the analytics strategies sent it to the database as
+written. Measured at `POST /api/v1/analytics/dataset/query` over a real SQLite
+driver, on the native-SQL and the ObjectQL strategy alike: a dataset measure
+aggregating `'*'` under `sum`, `avg`, `min`, `max` or `count_distinct` answered
+`500 DATABASE_ERROR`. A dataset measure compiles to the cube measure it names
+verbatim, so the same reading covers an authored cube measure. Such a member
+never produced an answer, so no working document changes meaning: the failure
+moves from the query to the authoring parse. The two measure slots ask ONE
+shared predicate; the rule is cross-field (the slot and its aggregate), so it is
+a refinement, which the published JSON Schema cannot carry — both sites are
+declared in `dropped-refinements.baseline.json`. The dimension half is a
+`pattern`, so `json-schema/**` states it.
+
+## FROM → TO
+
+```
+FROM  { name: 'deal_metrics', label: 'Deal Metrics', object: 'deal',
+        dimensions: [{ name: 'stage', field: 'stage' }],
+        measures: [{ name: 'deals', aggregate: 'sum', field: '*' }] }
+      -> DatasetSchema.parse accepted it; a dataset query selecting `deals`
+         answered 500 DATABASE_ERROR
+TO    -> DatasetSchema.parse throws a ZodError at measures.0.field (custom):
+         `measures[].field` is the row wildcard `'*'` under `aggregate: 'sum'`. …
+         defineStack({ datasets }) refuses it at datasets.N.measures.0.field (422
+         STACK_SCHEMA_INVALID), and POST /api/v1/analytics/dataset/query answers
+         400 VALIDATION_FAILED for an inline or a saved copy
+
+      measures: [{ name: 'deals', aggregate: 'count' }]                  // a row count
+      measures: [{ name: 'deal_value', aggregate: 'sum', field: 'amount' }] // an aggregate of a column
+
+FROM  defineCube({ name: 'deals', sql: 'deal',
+        measures: { total: { label: 'Total', type: 'sum', sql: '*' } },
+        dimensions: { everything: { label: 'All', type: 'string', sql: '*' } } })
+TO    -> refused at measures.total.sql (custom) and dimensions.everything.sql (invalid_format)
+
+      measures: { total: { label: 'Total', type: 'sum', sql: 'amount' } },
+      dimensions: { stage: { label: 'Stage', type: 'string', sql: 'stage' } }
+```
+
+**The one-line fix:** parse each cube and dataset; every refusal at `…sql` /
+`…field` naming `'*'` is one member to change — declare a `count` to count rows,
+or name the column the measure aggregates (a dimension names the column it
+groups by). On a `derived` dataset measure, delete `field`: nothing read it.
+There is no mechanical rewrite: `os migrate meta` rewrites nothing for it, and
+lists the entry `analytics-row-wildcard-outside-count-refused` as a manual
+change that requires your judgment.
+
+**What a stored document meets.** A metadata read still serves it as stored,
+with the refusal on its read diagnostics (`_diagnostics`), and a re-save through
+the metadata write door is refused at the slot. `POST
+/api/v1/analytics/dataset/query` parses every dataset it is handed, inline or
+saved, so a stored dataset carrying such a measure answers `400
+VALIDATION_FAILED` at `measures.N.field` on every query — including a query that
+selects only its other measures, which used to answer — until the member is
+fixed: it fails closed. An authored cube reaches the analytics runtime through
+the stack definition, whose parse refuses it.
+
+## The kit
+
+- **Schema.** `data/analytics-column-reference.ts` (not published API) declares
+  the predicate `rowWildcardOutsideCount` and its refusal once; `MetricSchema`
+  and `DatasetMeasureSchema` call both from a refinement, and
+  `DimensionSchema.sql` takes `ANALYTICS_COLUMN_PATH`. No export, key or enum
+  member changes, so the api-surface, authorable-surface and JSON-schema
+  manifest ratchets are unchanged.
+- **ADR-0087.** D3 entry `analytics-row-wildcard-outside-count-refused`. No D2
+  conversion: rewriting to `count` would change the figure the author asked for,
+  and only the author can name the column. No `RETIRED_KEYS_BY_MAJOR` row.
+- **Dropped refinements.** `data/Metric` and `ui/DatasetMeasure` gain their root
+  site, and every published schema embedding them gains the embedded site.
+- **Liveness.** `analytics_cube` `measures.sql` / `dimensions.sql` and `dataset`
+  `measures.field` stay `live`, re-verified, their notes re-pointed here.
+- **Docs.** The `ui/dataset` reference page is regenerated.
+- **Runtime.** Unchanged.
+
+## Reach, measured
+
+- This repository: no example, platform object, doc, skill, script or test
+  fixture authors `'*'` outside a `count` at the three slots (`git grep` of every
+  `field` / `sql` value spelled `'*'`, 173 hits, each read in its enclosing
+  object: 154 under a `count`, the rest QueryAST aggregations, comments and
+  strategy-level literals). One spec pin admitted `'*'` on a cube dimension; it
+  now pins the refusal.
+- objectui at the pinned `.objectui-sha`: zero `field` / `sql` values spelled
+  `'*'` (lit controls: 51 `aggregate: 'sum'`, 438 `field: 'amount'`).
+- Out-of-repo authored metadata: NOT MEASURED.
+
+<!-- adr-0087: registered analytics-row-wildcard-outside-count-refused -->