Merge remote-tracking branch 'origin/main' into claude/issue-20637-cube-refreshkey-retired

Author: claude

.changeset/20596-service-datasource-provenance-anchors.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/service-datasource': patch
+---
+
+Provenance comments in `service-datasource` were re-anchored
+
+Comment and docblock lines under `src/` that cited tracker numbers which no
+longer resolve on GitHub now cite the commit in this repository's history that
+decided the matter, and say in their own words what was decided. Comments
+only: no type, schema, export, log or refusal text, or runtime behaviour changes.

.changeset/20611-gate-reads-redaction-context.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/lint': minor
+'@objectstack/metadata-protocol': minor
+---
+
+The runtime metadata publish gate refuses an `api` flow with no per-flow secret, and reads a secret the flow read path withheld as present (#20611).
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) Nothing authorable changes spelling or type: `packages/spec` is untouched, and the start node `config` stays the open record it was. What changes is that the runtime metadata write door now refuses one authored shape at publish: an `api`-bound flow whose start node carries no usable `config.secret`. `objectstack migrate meta` could not rewrite that shape even in principle, because the missing value is a shared secret only the author and the sending system can supply. Rows at rest are not judged or rewritten; the automation engine has refused to register such a flow since 17.5.0, and that load path's disposition is recorded in its own published changelog entry. -->
+
+**BREAKING** — an accept-set narrowing on the runtime metadata write door,
+shipped as `minor` under the launch-window convention (`check-changeset-no-major`
+refuses `major` until GA; breaking-ness is carried by this banner and the ADR-0087
+disposition above, not by the level). An `active` save through `/meta` of an
+`api`-bound flow whose start node carries no usable `config.secret` (a
+`PUT /api/v1/meta/flow/:name`, or the publish of such a draft) used to be stored;
+the automation engine then refused to register it (`400` on the `/automation`
+doors, a skip with a warning at boot). It is now refused at the save with
+`422 INVALID_METADATA`, the issue naming `flow-api-trigger-secret-missing` at the
+start node's `config.secret`, and nothing is stored. A draft save is still
+accepted; its publish is refused the same way.
+**One-line fix:** set a non-blank `config.secret` on the flow's start node — or,
+for a flow that is only ever started explicitly, declare `type: 'autolaunched'`
+with no `triggerType: 'api'`.
+
+**What does not change: a signed flow's round trip.** Every served flow definition withholds the start node's `config.secret`, so a body saved back after a read arrives without it, and the save restores the stored secret only after every gate has run, so that no gate handles a restored credential. The gate is now told WHERE the save will restore a credential from the stored row: those positions only, never the values. `flow-api-trigger-secret-missing` reads a secret that was withheld and is stored as present, and one that is absent and not stored as missing. So a GET → edit → PUT of a signed flow, and the first save of a code-authored flow whose secret is in the app's source, keep passing and keep their secret. An explicit empty `config.secret` is the author's own value and is refused as blank.
+
+`@objectstack/lint`:
+
+- `validateFlowApiTriggerSecret` now runs on the runtime publish gate too (`surfaces` `['cli', 'runtime-publish']`, `runtimeTypes: ['flow']`). Its `surfaceReason` is gone.
+- `AuthoringRuleContext` gains an optional `restoredCredentialPaths`: a `ReadonlySet<string>` of stack-relative positions in the rules' own finding-path spelling (`flows[0].nodes[1].config.secret`). Only the runtime publish gate sets it; `runAuthoringRules` never forwards it, so `os validate`, `os build` and `os lint` judge the author's own values as before.
+- `runRuntimeAuthoringRules` accepts an optional `restoredCredentialPaths`: item-relative dotted positions in the `@objectstack/spec/kernel` redactor registry's `redactedKeys` spelling (`nodes.1.config.secret`). The gate re-spells them against the written item's place in its snapshot.
+- `validateFlowApiTriggerSecret(stack, options?)` accepts an optional `{ restoredCredentialPaths }`, and treats a listed start-node secret position as present.
+
+`@objectstack/metadata-protocol`: `saveMetaItem` hands the runtime authoring gate the positions its own credential carry-forward will fill, computed from the same stored body. This costs one indexed `sys_metadata` read on an `active` save of a type with a registered redactor (`datasource`, and `flow` where the automation plugin registers one), and nothing for any other type or for a draft save. The carry-forward itself is unchanged and still runs after every gate. The draft→active promotion judges the stored draft row, which already holds what that draft's save carried forward, so it needs no such positions.

.changeset/20620-migrate-meta-verdict-first.md

@@ -0,0 +1,33 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): `os migrate meta --from N` prints the schema verdict and the refusals first, then the applied mechanical edits, then the manual changes
+
+Clause-②: no
+
+`os migrate meta --from N` prints every semantic entry of every protocol major the
+chain crosses, whatever the stack uses: a `--from 17` run prints 242 manual changes.
+Those used to come before the schema verdict, which was the last line of the report
+and said "resolve the manual changes above". The refusals that keep the migrated
+stack from parsing were not listed at all. The only refusal list was the one printed
+while the config loaded, and that list names the stack as authored, including the
+keys the chain goes on to convert.
+
+The human-readable report now prints three groups, each opened by one header line
+that counts it:
+
+1. the verdict: `Migrated stack is schema-valid`, or
+   `Migrated stack does not yet pass schema validation — N refusals left after the chain`
+   followed by one `✗ path: message` line per refusal of the migrated stack;
+2. `Applied N mechanical change(s):`;
+3. `N manual change(s) require your judgment:`.
+
+No manual change is dropped, merged or reworded. Every applied edit and every
+manual change prints byte for byte as before, in the same order within its group.
+The data-migration advice is still the last thing printed. A range that holds no
+migration step also leads with the verdict, which now lists the source's refusals,
+and the note naming the range to use follows it.
+
+`--json` is unchanged: same keys, same values, same array order. The exit code is
+unchanged too: a run whose migrated stack does not parse still exits 0.

.changeset/20647-analytics-result-object.md

@@ -0,0 +1,23 @@
+---
+'@objectstack/spec': minor
+---
+
+feat(spec): a dataset answer declares its base object as `object` (#20647)
+
+Clause-②: yes (widening)
+
+`AnalyticsResult` (`@objectstack/spec/contracts`) gains one optional member,
+`object?: string`, and `AnalyticsResultResponseSchema` (`@objectstack/spec/api`)
+mirrors it on `data`. It is the base object of the dataset the answer was
+computed from, by machine name. Nothing is removed or renamed, and no existing
+member changes meaning.
+
+**For a consumer.** Code typed against `AnalyticsResult` can read `object` from a
+`queryDataset` answer without a cast, and a parse with
+`AnalyticsResultResponseSchema` keeps `data.object` where it used to strip it. The
+contract asks every dataset answer to carry it, whatever dimensions are selected
+and whether or not rows came back. A cube query answer has no dataset behind it
+and carries none.
+
+**Producers.** This release declares the member. `@objectstack/service-analytics`
+sets it on every dataset answer once #20644 lands.

.changeset/spec-conversions-connector-provenance-anchors.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+---
+
+Provenance comments in `conversions/registry.ts` and `integration/connector.zod.ts` were re-anchored
+
+Clause-②: no
+
+Thirteen comment and docblock sites in `src/conversions/registry.ts` and
+`src/integration/connector.zod.ts` cited tracker numbers that no longer resolve on
+GitHub. They now cite the record that decided the matter: ADR-0087's 2026-09-13
+addendum for the data-at-rest seams `retiredFromLoadPath` does not hold back, and
+otherwise the commit in this repository's history. Comments only: no type, schema,
+export, `describe()` text, conversion `summary` or runtime behaviour changes.

content/docs/references/api/analytics.mdx

@@ -122,7 +122,7 @@ const result = AnalyticsEndpoint.parse(data);
 | **success** | `boolean` | ✅ | Operation success status |
 | **error** | `{ code: Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| …>; declaredCode?: string; message: string; userMessage?: string; … }` | optional | Error details if success is false |
 | **meta** | `{ timestamp: string; duration?: integer; requestId?: string; traceId?: string }` | optional | Response metadata |
-| **data** | `{ rows: Record<string, any>[]; fields: object[]; sql?: string; totals?: object[] }` | ✅ |  |
+| **data** | `{ rows: Record<string, any>[]; fields: object[]; sql?: string; totals?: object[]; … }` | ✅ |  |
 
 ### Nested Shape: `AnalyticsResultResponse.error`
 
@@ -155,6 +155,7 @@ const result = AnalyticsEndpoint.parse(data);
 | **fields** | `{ name: string; type: string; label?: string; format?: string; … }[]` | ✅ | Column metadata |
 | **sql** | `string` | optional | Executed SQL (if debug enabled) |
 | **totals** | `{ dimensions: string[]; rows: Record<string, any>[] }[]` | optional | Marginal aggregates - one entry per requested totals grouping, in request order, each computed with the measure's true aggregate over the underlying data (never re-derived from bucketed values). The grand-total grouping yields a single dimensionless row. |
+| **object** | `string` | optional | The base object of the dataset the answer was computed from: the dataset's `object`, by machine name. Every dataset answer (`POST /analytics/dataset/query`) must carry it, whatever dimensions are selected and whether or not rows came back, so a consumer can refresh on that object's record changes and drill into its records. Absent on a cube query answer, which has no dataset behind it. |
 
 
 ---