Merge remote-tracking branch 'origin/main' into claude/issue-20390-forward-conversion-window

# Conflicts:
#	packages/metadata-core/src/artifact-forward-conversion.test.ts

Author: claude

.changeset/15429-decision-edge-branching-first-match.md

@@ -0,0 +1,100 @@
+---
+"@objectstack/spec": minor
+"@objectstack/service-automation": minor
+"@objectstack/lint": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/metadata-core": patch
+---
+
+feat(automation)!: an edge-branched `decision` is exclusive — the first out-edge whose condition holds, in declaration order, wins; `mode: 'inclusive'` takes every one (#15429)
+
+<!-- adr-0087: registered flow-decision-mode-inclusive-explicit -->
+
+Clause-②: yes
+
+**BREAKING** — the run-time semantics of a shipped node type change. A `decision` node that
+declares no `config.conditions` and branches on its out-edges used to take EVERY out-edge whose
+condition held, one after another, while its schema, the docs and the engine's own comment all
+called it an exclusive gateway; hotcrm#1555 rendered a refusal screen AND ran the conversion in
+one execution. Maintainer ruling on #15429 (2026-09-23, 「跟主流对齐」): the gateway follows
+BPMN's exclusive gateway, Salesforce Flow's Decision and n8n's Switch default, and taking every
+true branch is a declaration the author writes down.
+
+| | before | after |
+|:--|:--|:--|
+| two conditioned out-edges, both hold | both successors run, sequentially, nothing reported | the FIRST declared one runs; the second records a `skipped` step |
+| `config: { mode: 'inclusive' }` | accepted, never read | every out-edge whose condition holds runs, sequentially |
+| none holds | the `isDefault` edge runs | unchanged |
+| `mode` beside a non-empty `conditions` list, or outside `'exclusive' \| 'inclusive'` | refused by a direct parse only | refused at `registerFlow` and by `os validate`, with the schema's own sentence |
+
+## Migration: FROM → TO
+
+`os migrate meta --from 17` lists the mechanical edits for existing sources and applies them
+to the migrated stack: the ADR-0087 D2 conversion `flow-decision-mode-inclusive-explicit`
+writes `mode: 'inclusive'` onto every decision that has no `conditions` list and two or more
+conditioned out-edges, inside ADR-0031 regions included, so a migrated flow runs exactly as it
+did.
+
+```ts
+// FROM — every true out-edge ran
+{ id: 'verdict', type: 'decision', label: 'Verdict?' }
+// TO — what the conversion writes; delete the key where the conditions partition
+{ id: 'verdict', type: 'decision', label: 'Verdict?', config: { mode: 'inclusive' } }
+```
+
+Then review each written key (the paired D3 entry `flow-decision-edge-branching-first-match`
+carries the acceptance criteria): delete it where the conditions partition (`== 'a'` beside
+`!= 'a'`, `>` beside `<=`, a guard beside `isDefault: true`), keep it where the flow relies on
+more than one branch running for one record, and where the overlap was accidental narrow the
+conditions into a partition and delete the key. `os validate` reports
+`flow-decision-inclusive-overlap` on every decision that keeps the key with two or more
+conditioned out-edges, so the review list is the lint output.
+
+## BREAKING for flows stored in `sys_metadata` — maintainer ruling letter C on #15429
+
+A `decision` node stored in `sys_metadata` (a flow built or edited in the Studio designer) with
+**no `config.conditions`, no `mode`, and two or more out-edges carrying a `condition`** evaluates
+**first-match** after this upgrade: where it took every out-edge whose condition held, it now takes
+only the first one that holds, in the order the flow declares its edges. Nothing rewrites that row
+— no stored-row migration, no cutoff, no read-path completion — because nothing about a stored row
+says it was saved before the flip. The one-line fix, for a node that meant every branch:
+
+```ts
+{ id: 'route', type: 'decision', label: 'Route', config: { mode: 'inclusive' } }
+```
+
+`os migrate meta --stored` (and `POST /api/v1/meta/_migrate-stored`) lists every such node under
+`decisionModeReview` — flow row, node id, label and path — on a preview and an `--apply` run
+alike, and writes nothing for it: the list moves no row outcome, no count and no exit code, so an
+operator can review the candidates before and after the upgrade. A node leaves the list once it
+declares `mode`, either member. Every such node in the measured corpus below is a partition, where
+the new meaning runs exactly what the old one did.
+
+Authored sources and built artifacts keep the old behaviour instead, where the source's age is a
+fact: `os migrate meta --from 17` writes `mode: 'inclusive'` (above), while the authoring funnel,
+the automation engine's flow rehydration seam and the artifact-ingestion door all refuse the
+conversion by id — a default flip replayed there would turn a decision written today against this
+contract, where an omitted `mode` means exclusive, into an inclusive gateway.
+
+## Reach, measured at landing
+
+- Release state: the npm registry's `latest` `@objectstack/spec` is `17.4.0` (`npm view`,
+  2026-09-27), whose `json-schema/automation/DecisionConfig.json` declares `conditions` only —
+  `mode` has not shipped; `.changeset/19867-decision-config-mode.md` and
+  `.changeset/20168-decision-mode-beside-conditions-refused.md` are still unconsumed in this
+  tree. So `mode` reaches its first release together with the traversal that reads it and the
+  conversion that writes it; no published accept set narrows, and the registration and
+  `os validate` refusals narrow nothing that shipped.
+- Corpus census (this repository at the branch base and `objectstack-ai/hotcrm` at `2f7b2326`,
+  read-only): 30 decision nodes across 48 flows; 17 have two or more conditioned out-edges and
+  no `mode` (the conversion's positives — every one a hand-written partition, including
+  hotcrm's `lead_conversion.decision_duplicate`, the #1555 node), 13 have one conditioned
+  out-edge (left alone), and no node of any other type carries a conditioned out-edge, so the
+  exclusive traversal is scoped to `decision` with nothing else to migrate.
+- What the published surface gains: the D2 conversion and its D3 entry in the protocol-18
+  chain (`spec-changes.json`, the upgrade guide), `DecisionConfigSchema.mode`'s describe and
+  docblock now state the run-time semantics, and `@objectstack/lint` gains
+  `flow-decision-mode-invalid` (gating) and `flow-decision-inclusive-overlap` (advisory).
+
+The traversal change is scoped to `decision` nodes: conditioned out-edges of any other node
+type keep the every-true-edge traversal they had (none was measured to exist).

.changeset/20282-analytics-cube-public-enforced.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-analytics': minor
+---
+
+An analytics cube's `public` now takes effect, and it defaults to visible: `CubeSchema.public` defaults to `true` (it was `false`), and the analytics service hides a cube that declares `public: false` from discovery and refuses every query against it (#20282).
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered analytics-cube-public-default-visible-enforced -->
+
+**BREAKING**: this narrows what the analytics API answers. A query or SQL dry run against a cube declared `public: false` (`POST /api/v1/analytics/query`, `POST /api/v1/analytics/sql`) was answered before this change and is now refused with `404 CUBE_NOT_FOUND`, and `GET /api/v1/analytics/meta` no longer lists that cube. The same happens to every cube in an artifact built by `os compile` before this release, which carries a materialized `public: false` from the old default. The remedy: delete `public: false` from any cube that is meant to be queried (cubes are visible by default), and recompile pre-release artifacts. It ships as `minor` under the launch-window convention; the widening half is the default moving to visible.
+
+Until this change nothing read `public`. `GET /api/v1/analytics/meta` listed a `public: false` cube and every query door answered it, so the flag withheld nothing. Its declared default, `false`, could not simply be switched on: enforcing it as declared would have hidden every cube that omits the key. The default is now the Cube.dev default (visible), and an explicit `false` is enforced:
+
+- `GET /api/v1/analytics/meta` omits a cube declared `public: false`, and `?cube=` naming one answers `[]`, the same as a name no cube has.
+- `POST /api/v1/analytics/query` and `POST /api/v1/analytics/sql` refuse it with `404 CUBE_NOT_FOUND` — the same refusal, byte for byte, that an unknown cube name gets, so a caller cannot use it to learn that a hidden cube exists. The one shared message names both possibilities, so it still tells an author how to expose a hidden cube. The refusal comes before any SQL is built, and it is never an empty result.
+
+`public` is visibility on the analytics API, not row security. An object's records stay governed by its permissions and row-level security on every door, whether or not a cube over it is hidden. What `public: false` does is exactly the two points above: the cube is left out of `/analytics/meta`, and queries and SQL generation against it are refused. The cube's definition stays readable on the metadata door, like any other authored schema.
+
+What to expect after upgrading:
+
+- **A cube that omits `public`** stays visible and queryable. It was visible before too, because nothing read the key. A client that parses cube metadata through the published JSON Schema now materializes `public: true` where it materialized `false`.
+- **A cube that writes `public: false`** is now hidden and refused. If you wrote it only because it was the old default, delete the line (cubes are visible by default). A dashboard or report that queries such a cube starts answering `404 CUBE_NOT_FOUND` until you do.
+- **A compiled artifact built before this release** carries a materialized `public: false` on every cube, because `os compile` writes the parsed stack with its defaults applied. Recompile it with this release before serving cubes from it.
+- **Cubes the platform mints itself** stay visible: the cube inferred for an ad-hoc query on an object (the KPI path), a compiled dataset's cube (`POST /api/v1/analytics/dataset/query`), and `CubeRegistry.inferFromObject`. Each wrote a literal `false`, the old default, and now writes `true`.
+
+The showcase example's `showcase_delivery` cube, which is the app's demonstration of `/api/v1/analytics/*`, drops its `public: false`.

.changeset/20316-flow-node-config-required-keys-refused.md

@@ -0,0 +1,82 @@
+---
+'@objectstack/spec': minor
+'@objectstack/lint': minor
+---
+
+fix(spec)!: a flow node config its executor cannot run — a key its contract requires, left out, or a decision branch list it cannot read — is refused at authoring (#20316)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered flow-node-config-required-keys-refused -->
+
+**BREAKING** — an accept-set narrowing on authored flow-node `config`, 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).
+
+**What changed.** A flow node's `config` is an open record, so what its executor
+requires was checked by no build door. `FlowSchema.parse`, `AutomationEngine.registerFlow`
+and `objectstack validate` all admitted a node that left out a key its executor
+contract requires — and the executor's own contract parse then refused the node on
+every run that reached it. A `decision` branch with no `label` was worse: it never
+failed, the matched branch reported no label, and traversal took EVERY out-edge, so
+the flow ran green down the wrong paths. All three doors now refuse these shapes
+through one judge, `flowNodeConfigRefusals` (new in `@objectstack/spec/automation`):
+
+- **A key a builtin's executor contract requires, left out.** Each builtin node's
+  config is parsed against the very contract its executor parses against
+  (`getBuiltinNodeConfigContracts()`, new, reconciled against the executors' own parse
+  calls), and only the keys left out are kept — a present value of the wrong type, and
+  an undeclared key, are judged where they were before. The keys: `objectName` on
+  `get_record` / `create_record` / `update_record` / `delete_record`; `recipients` on
+  `notify` (and `title` when there is no `template`); `url` on `http`; `function` on
+  `script`; `flowName` on `subflow`; `collection` and `flowName` on `map`;
+  `collection` on a `loop` that has a `body`; `branches` on `parallel`; `try` on
+  `try_catch`; and on `screen`, each field's `name`, each option's `value` and
+  `label`, and a `lookup` field's `reference`. A key a rule of the contract requires
+  (the `notify` title, the `lookup` reference) is refused in the contract's own words.
+- **A `decision` branch list its executor cannot read.** `conditions` present and not
+  `null` must be an array; every branch must be an object; every branch's `label` must
+  be a non-blank string (absent, `null`, blank or non-text all name no out-edge).
+
+Each refusal is a `custom` issue anchored at the key (`nodes.1.config.objectName`,
+`nodes.1.config.fields.0.name`, `nodes.1.config.conditions.0.label`, or the region
+path `nodes.1.config.body.nodes.0.config…`), met at `registerFlow` and
+`objectstack validate` through that same parse, and reported by
+`validateStackExpressions` for a stack handed to it directly. The refusal codes join
+`FLOW_SLOT_REFUSAL_CODES`: `node-config-key-missing`, `node-config-key-required-by-rule`,
+`decision-conditions-not-array`, `decision-branch-not-object`,
+`decision-branch-label-missing`.
+
+The Studio flow designer writes refused shapes when a node is added and saved before
+it is configured, when a decision branch row's label cell is left empty, and when a
+screen field row's name cell is left empty. Where such a node already sits, the whole
+flow is refused: registered from the metadata registry or `sys_metadata` at boot, it
+is skipped with a `failed to register flow` warn naming it while the flows beside it
+register; a `defineStack({ flows })` source throws `StackSchemaInvalidError` for the
+whole stack; an artifact file is refused whole at load.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `{ type: 'get_record', config: { outputVariable: 'rows' } }` | the object it reads — `config: { objectName: 'account', outputVariable: 'rows' }` (the same for `create_record` / `update_record` / `delete_record`) |
+| `{ type: 'loop', config: { body: { … } } }` | the array it iterates — `config: { collection: '{rows}', body: { … } }` |
+| `{ type: 'map', config: { flowName: 'per_row' } }` | `config: { collection: '{rows}', flowName: 'per_row' }` |
+| `{ type: 'http', config: { method: 'GET' } }` | `config: { url: 'https://api.example.com/v1/items', method: 'GET' }` |
+| `{ type: 'script' }` | the registered function it calls — `config: { function: 'recalc_totals' }` |
+| `{ type: 'notify', config: { recipients: ['{record.owner}'] } }` | a content source — `title: 'Deal won'`, or a `template` |
+| `conditions: [{ expression: 'record.amount > 1000' }]` on a `decision` | the out-edge it routes to — `[{ label: 'large', expression: 'record.amount > 1000' }]`, beside an out-edge labelled `large` |
+| `conditions: ['record.amount > 1000']` | `[{ label: 'large', expression: 'record.amount > 1000' }]` |
+
+**One-line fix:** write the key the node was meant to carry. To branch on the
+out-edges instead of on `conditions`, delete `conditions` and put each predicate on its
+edge's `condition`.
+
+**Unchanged.** A node carrying every key its contract requires parses, registers and
+validates as before; a legacy flat-graph `loop` (no `body`) still needs no
+`collection`; a `decision` with no `conditions`, `conditions: null` or an empty list
+still routes by its out-edges; `assignment`, `wait`, `connector_action` and plugin node
+types are not judged by this rule; and a key spelled by a D2 alias (`object`, `flow`,
+`functionName`, …) is still canonicalized before `registerFlow` and `objectstack
+validate` judge it.

.claude/skills/pm-dispatch/references/lanes/ui.md

@@ -5,8 +5,8 @@
 ## 形态
 
 - 本席为姊妹仓执行座位:在 objectui 仓认领、派发、复核、落地。
-- ⛔ 不产 `domain:*`、type 与定级,中央分诊唯一生产,见 SKILL.md 多仓协调规则 1 与 4。
-- 误标 ⛔ 不自改:挂 `pm:retriage` 加异议评论同笔,见同节规则 4。
+- ⛔ 不产 `domain:*`、type 与定级,中央分诊唯一生产;误标 ⛔ 不自改,挂 `pm:retriage`+异议同笔。
+- 维护者裁决例外于上条与 SKILL.md 无标签禁认领:main/队列 `Spec Main Shape Gate` 红即止血认领。
 
 ## 范围
 

content/docs/api/client-sdk.mdx

@@ -318,7 +318,7 @@ const result = await client.analytics.query({
 });
 console.log(result.rows.length, result.fields[0].name); // AnalyticsResult, unwrapped
 
-// Get cube metadata — all cubes, or one with meta('account')
+// Get cube metadata — all cubes (those declared public: false are omitted), or one with meta('account')
 const meta = await client.analytics.meta('account');
 console.log(meta[0].name, meta[0].measures.length);     // the bare cube list
 

content/docs/api/data-api.mdx

@@ -479,10 +479,12 @@ so its column shows the tenant default. The cube query on this page carries no c
 
 ### `GET /analytics/meta`
 
-Get metadata for all registered cubes. Cubes are explicitly defined (via `defineCube`
-or the analytics service's `cubes` config) — a cube referenced by a query that isn't
-yet registered is lazily auto-inferred from that query's shape, but metadata isn't
-proactively generated for every object.
+Get metadata for all registered cubes, except those declared `public: false`, which are
+omitted (and refused by `POST /analytics/query` and `POST /analytics/sql` with the same
+`404 CUBE_NOT_FOUND` an unknown cube name gets). Cubes are explicitly defined (via
+`defineCube` or the analytics service's `cubes` config) — a cube referenced by a query
+that isn't yet registered is lazily auto-inferred from that query's shape, but metadata
+isn't proactively generated for every object.
 
 Pass `?cube=<name>` to filter the listing to a single cube (this is what
 `client.analytics.meta(cube)` sends).