Merge remote-tracking branch 'origin/main' into claude/issue-5322-empty-combinator-identity

# Conflicts:
#	packages/services/service-analytics/src/strategies/filter-normalizer.ts

Author: claude

.changeset/adr-0076-status-line-calibration.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs(adr-0076): 把状态行从 `Proposed` 校准为 `Accepted`，并逐条记录 D1–D12 的真实落地状态（#5063）。参照 #4919 对 ADR-0078 的做法：不整体翻牌，每条决定给出在 `origin/main` 上核对到的证据 —— D3 完全未建、D10/D11 只落一半、D9 已越过 step-1 把联合类型彻底解散、D7 已有 CI 触发指标。同时给 D9 的 back-compat 条目补一条状态注记（组合别名已不存在）。纯文档改动，不发布任何包。

.changeset/adr0120-isolated-install-gate-and-truth-sweep.md

@@ -0,0 +1,81 @@
+---
+"@objectstack/types": minor
+"@objectstack/cloud-connection": minor
+"@objectstack/lint": minor
+"@objectstack/cli": minor
+"@objectstack/spec": patch
+"@objectstack/driver-sql": patch
+---
+
+feat(types,cloud-connection,lint,cli): ADR-0120 17.x 收尾 —— `isolated` 安装期姿态硬门(D5e)、D5c 重拼写 advisory、成文契约扫荡与三姿态 conformance (#5081)
+
+ADR-0120 17.x 波的第三块,也是最后一块。前两块已在 main 上:#5212(driver 侧
+D3+D4 —— `COALESCE(organization_id, '__global__')` 物化、drift 两侧同步、重复预检)
+与 #5208(spec 词汇 `'organization'` + D5a/D5b lint)。本次补齐三件事:安装期的
+姿态决策点、剩余的成文契约、以及把「一个 app 包跑遍三种姿态」从假设变成测试。
+
+**D5e —— 装进 `isolated` 环境时的硬门。** 词汇本身是姿态无关的:作者说的是业务
+边界(`'organization'` 一个组织一份 / `'global'` 整个安装一份),没有任何索引形状
+读姿态。唯一的残留在一个方向上:`isolated` 下组织就是**不同客户**,此时 app 业务
+对象上的 `'global'` 唯一既跨客户过度约束,又变成跨客户的存在性预言机(S10/S14)。
+维护者裁定这是**硬门而非 advisory**:把带 `'global'` 唯一(非 `sys` 对象)的 app
+装进 `isolated` 环境会**停下来并逐索引列出**,安装者(通常是 AI agent)要么确认它
+确实是平台级的,要么改写为 `'organization'`;确认按 ADR-0104 attestation 风格
+留痕在安装清单里(`InstalledManifestEntry.globalUniqueAttestation` —— 确认了什么、
+谁确认的、何时、在哪个姿态下问的),**之后不复问**。
+
+- 停下的安装**什么都不留**:先于 hot-register 和任何 ledger 写入,所以作者改完
+  元数据可以直接重试,不需要先卸载。
+- 逐索引确认是有牙齿的:`confirmGlobalUniques` 收 `true` 或明确的 id 数组,只确认
+  其中一条仍会在剩下的那条上停住。
+- 升级引入的**新**约束会被问,老的答案继续算数。
+- 另一个姿态下给出的确认**不算同意** —— `isolated` 那个问题在 `single` 下从未被
+  问过,所以按「未确认」处理(唯一不会静默放行跨客户约束的方向)。
+- ⛔ **永不做成启动期告警**(#4884 纪律)。boot 时的 rehydrate 不评估此门;门够不到
+  的两类存量 —— 门禁上线前的安装、装后姿态变更的环境 —— 由 `os doctor` 与
+  `os migrate plan` 的 advisory 形态覆盖。
+
+判定里有三条是承重的,别「简化」掉:声明索引上的裸 `unique: true` **算**(D1 说它
+就是 `'global'` 的位置式拼写,排除它等于让整个 17.x 可以靠拼写绕过);字段级
+`true` **不算**(它是 `'organization'`,永久合法);`sys_`/`base_` 对象**不算**
+(S5 那批引擎幂等键天然就是平台级的,每次安装都问一遍就是 #4884 的误报类)。
+
+CLI: `os package install` 新增 `--confirm-global-uniques`,并把 409 渲染成可读的
+逐条清单而不是一句 "Install failed (409)"。
+
+**D5c —— 遗留手写组织复合索引的 advisory。** 新规则
+`unique/legacy-organization-composite`:声明的唯一索引自己列出了组织列
+(`{ fields: ['name','organization_id'], unique: true }`)—— 这是词汇出现之前手写
+per-organization 的写法。它读起来像「每组织唯一」,物化出来却是普通复合索引,而
+SQL UNIQUE 是 NULL-distinct 的:组织列为 NULL 的行上它**什么都不约束**(#5030),
+在单组织部署上那就是每一行。改写成 `unique: 'organization'`(`fields` 原样保留,
+driver 会把已列出的组织列**就地**变成 NULL-safe 形式)正是补上这个洞的动作。
+**永远只是 advisory,永远不自动修**:老拼写永久合法、零强制 drift,而 opt-in 是
+真实的物理收紧,要走 D4 的 `recreate_index` + 重复预检。
+
+**D6 —— 成文契约扫荡。** `content/docs/data-modeling/indexing.mdx` 的
+§Two ways to say "unique" 全节按新词汇重写(含 `os:check` 代码块);
+`content/docs/protocol/objectql/schema.mdx` 的 §Uniqueness and tenancy 重写为
+§Uniqueness and scope —— 其中那句「单租户部署不受影响,租户列是常量,复合索引
+退化为单列索引」是 #5030 **证伪过的原话**,现已替换为 D3 的 NULL-safe 事实;
+`content/docs/deployment/cli.mdx` 的 `replace_unique_index` / `recreate_index`
+条目补上 NULL-safe 形状与重复预检;`content/docs/references/**` 经
+`gen:schema && gen:docs` 再生成,未手改。
+
+按 ADR-0120 Resolved #2 的非规范性引导(官方示例/脚手架/生成器在新代码中输出
+显式拼写),`skills/objectstack-data/**` 的索引与校验规则整体扫过:声明索引一律
+说清 scope,并新增一节完整讲 `'organization'` 的 NULL-safe 语义与「永远不写姿态」。
+顺带修掉那里长期使用的 `tenant_id` —— 平台的列叫 `organization_id`。
+`examples/**`、`create-objectstack` 模板与 `os generate` 经核查**根本没有声明任何
+唯一约束**,故无可扫;这是核查结论,不是遗漏。
+
+**三姿态 conformance(ADR §Acceptance tests)。** 同一个 fixture app 在
+`single | group | isolated` 三姿态下启动,逐 S 行用**真实的违规插入**断言 enforcement
+(S1/S2/S3/S4/S5/S6/S7/S8/S9/S11/S12),并逐姿态捕获物化出的索引键,断言三者
+**逐字节相同** —— 「没有任何索引形状读姿态」这句话一旦有两者不同就是假的。相同性
+断言配了一条正向断言(对着期望的键形状),这样「三次都什么都没建」不会读成「一致」。
+外加 ADR 只要的那一条 transition smoke:在 `single` 下建库、`isolated` 下重新打开,
+drift op 为零。
+
+对既有部署的影响:除新增的安装期确认外,本次不改变任何已有物化行为。字段级
+`unique: true` 一如既往合法。

.changeset/analytics-filter-refusal-envelope.md

@@ -0,0 +1,61 @@
+---
+"@objectstack/service-analytics": patch
+"@objectstack/rest": patch
+---
+
+fix(analytics,rest): an analytics filter refusal reaches the caller as `400 INVALID_FILTER`, not `500 ANALYTICS_QUERY_FAILED` (#5352)
+
+Misspell an operator in a dashboard widget's filter and analytics refuses it —
+correctly, and loudly, which is the posture #3948 / #5240 / #5325 / #5334 each
+argued for one refusal at a time: dropping a predicate the compiler cannot
+express does not narrow the query, it **widens** it to rows the author excluded,
+and a chart drawn over the whole dataset looks like a working chart.
+
+The refusal never reached the author. It landed as `500 ANALYTICS_QUERY_FAILED`
+— read as "the platform is broken" rather than "your filter has a typo", and
+counted by ops alerting as a 5xx. The identical mistake on `find()` has answered
+`400 INVALID_FILTER` since #3948, so one authoring error had two wire shapes,
+chosen by which face happened to catch it.
+
+**One defect, two halves — either alone leaves it unfixed.**
+
+- **Producer** (`filter-normalizer.ts`): seven of its nine refusals were bare
+  `throw new Error(…)` carrying no `code`/`status`. All nine now go through the
+  `invalidFilterError` helper #5334 introduced (`INVALID_FILTER` / 400), which
+  becomes the module's only way to refuse.
+- **Consumer** (`rest-server.ts`, `POST /analytics/dataset/query`): the catch
+  discarded `error.code` / `error.status` and re-derived the classification from
+  a hardcoded list of message substrings — so a producer that took ADR-0112
+  seriously was punished for it. It now reads the envelope **first**; the
+  substring list is demoted to a fallback for the families that still carry no
+  envelope.
+
+**Observable behaviour change — read this if you alert or retry on status.**
+The same request that returned `500 ANALYTICS_QUERY_FAILED` now returns
+`400 INVALID_FILTER` (and, for two neighbouring conditions whose producers
+already declared an envelope this route was discarding, `400 INVALID_FIELD` for
+a measure over a field the object does not have, `404 CUBE_NOT_FOUND` for an
+unregistered cube). Monitoring that counted these as server faults will see the
+5xx rate drop and a 4xx rate appear; a client that retries on 5xx will stop
+retrying a request that could only ever fail the same way. Both are the intended
+correction — the condition was always the caller's mistake — but they are
+visible, so they are stated rather than buried.
+
+**Which inputs are refused did not change.** This changes the SHAPE of the
+error and nothing about the judgement that produced it: no refusal condition
+was touched, no input that used to compile now refuses, and no input that used
+to refuse now compiles. That claim is pinned input-by-input (refusals *and*
+accepted inputs with their compiled trees) in
+`filter-refusal-envelope.test.ts`, which is green both before and after the
+change — only the envelope assertions move.
+
+The message-substring list survives on purpose. All six of its entries were
+re-verified as bare `Error`s (`dataset-compiler.ts`, `native-sql-strategy.ts`,
+`dataset-executor.ts`, `read-scope-sql.ts`), so deleting it would regress those
+families from `400 DATASET_INVALID` to 500. It is a placeholder for their
+enveloping, not a second classification mechanism, and it is now documented as
+such: a new refusal should carry a `code`/`status` and be served by the
+envelope branch for free. The passthrough is deliberately **4xx-only** and
+requires **both** `code` and `status`, so an internal fault can never be
+re-labelled as the caller's fault, and this route never invents a code a
+producer failed to supply.

.changeset/analytics-where-filter-array-lowered.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): a `where` written as a `FilterArray` is lowered instead of silently dropped (#5334)
+
+**Observable behaviour change.** An analytics query whose `where` arrived as an
+ARRAY had its filter **deleted**: `normalizeAnalyticsFilterTree` answered every
+array with `return null`, so no predicate was compiled, no error was raised, and
+the widget charted the **entire dataset**. The compiled SQL stayed perfectly
+valid — just broader than the author asked for — which is why it was invisible
+to every test that asserts a SQL string. The issue's own measurement:
+`generateSql({cube:'deals', measures:['total'], dimensions:['id'], where:
+[['stage','=','won']]})` emitted `SELECT id AS "id", COUNT(*) AS "total" FROM
+"deal" GROUP BY id` with an empty `params`. It now emits the bound `WHERE` and
+returns the two won deals.
+
+`FilterArray` (`['stage','=','won']`, `['and', […], […]]`, `[[…], […]]`) is
+INPUT-ONLY authoring sugar (#5285), and #5158's ruling C says every door into
+the runtime lowers it through the single `parseFilterAST` sink before anything
+downstream sees a filter. #5329 closed ObjectQL's six entry points that way and
+deleted the four drivers' private array dialects. Analytics is the **fifth
+door**: it compiles `where` itself — to SQL (`NativeSQLStrategy`) or to a
+`FilterCondition` for the engine (`ObjectQLStrategy`) — so nothing upstream
+lowers for it. It now gives the same three answers the engine door gives:
+
+- `[]` — "no filter", not a failed filter: no predicate, no error (unchanged).
+- A well-formed `FilterArray` — **lowered** through `parseFilterAST`, so both
+  spellings of one filter select the same rows on both strategies.
+- Any other non-empty array — **refused** with `INVALID_FILTER` / 400
+  (ADR-0112), the envelope the drivers' `filterArrayReachedDriverError` uses.
+  This is where the undeclared INFIX form (`[condA, 'or', condB]`) lands, and
+  where a list of `FilterCondition` objects (`[{stage:'won'}]`) lands — neither
+  is a `FilterArray`, `parseFilterAST` has no lowering for either, and dropping
+  them is what returned the unfiltered dataset.
+
+Lowering rather than refusing keeps one dashboard's metadata meaning one thing:
+the same `where` on a plain `find()` already lowers at the engine door, so
+refusing it here would have forked the product by which face read the metadata.

.changeset/api-metadata-type-registry.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `api` is a declared metadata kind — `DEFAULT_METADATA_TYPE_REGISTRY` + `BUILTIN_METADATA_TYPE_SCHEMAS` (#5271, part of #5206)
+
+`api` items were produced, indexed and executed while the spec declared the kind
+nowhere. Artifact ingest maps `defineStack({ apis })` to `api` metadata
+(`ARTIFACT_FIELD_TO_TYPE`), the endpoint matcher indexes them
+(`buildEndpointIndex`), and #5040's executor serves them — but
+`DEFAULT_METADATA_TYPE_REGISTRY` had no `{ type: 'api', … }` entry and
+`BUILTIN_METADATA_TYPE_SCHEMAS` had no `api` binding. So
+`getMetadataTypeSchema('api')` returned `undefined` and `saveMetaItem` took its
+documented "unregistered type is stored without validation" branch:
+`PUT /api/v1/meta/api/:name` accepted **any JSON** and answered 200. That is
+`declared ≠ enforced` read backwards — enforced but **undeclared**.
+
+Both halves are now declared, which is one fix with two faces:
+
+- **A body is validated.** The existing 422 `invalid_metadata` path applies to
+  `api` like every other kind, with structured Zod issues naming the offending
+  key. An endpoint with no `target`, or no `type`, is refused instead of stored.
+- **The type is describable.** `/meta/types` emits a real JSON Schema and a
+  create seed for `api`, so the metadata-admin engine renders a form rather than
+  a raw-JSON textarea, and the entry carries a real label, domain and file
+  patterns instead of the synthesised `label: 'api'`, `filePatterns: []`
+  placeholder a type with no registry row gets.
+
+**The write door is unchanged.** `allowRuntimeCreate: true` records what the
+runtime already did: with no static registry entry, both write gates
+(`isRuntimeCreateAllowed`, `assertAllowed`) fall through to "runtime-creatable",
+and both name `api` in that comment. `allowOrgOverride` stays `false`, also its
+effective value today — an endpoint is the publishing package's outward URL
+contract, and a per-org fork could move `path`, flip `authRequired` or drop
+`rateLimit` on a URL third parties integrate against. Marking the type code-only
+instead (`allowRuntimeCreate: false` + `allowOrgOverride: false`) was considered
+and rejected: it would turn today's 200 into a 403 rather than validate it, and
+#5086's refusal runs before persistence for drafts too, which would leave
+#5206 step 2's `publishPackageDrafts` endpoint gate with no draft to gate.
+
+**`ApiEndpointSchema` gains the ADR-0010 protection envelope, and stays open to
+unknown keys.** Every registered kind must declare the envelope its loader
+stamps (`_packageId` / `_provenance`), or it is dropped on every parse; that
+spread is added. Closing the shape against unknown keys was attempted and
+**measured to be unsafe**: the same schema parses stored rows as well as
+authored declarations (`buildEndpointIndex`, `gateApiItemsForPublish`), and a
+stored row carries the metadata layer's own bookkeeping (`packageId`, `state`),
+so `strictObject` turned 10 tests in `packages/metadata` red — the load-time
+backstop excluded endpoints and the publish gate reported a schema error in
+place of its ADR-0121 D6 verdict. `api` therefore joins `view` on the #4001
+campaign's `STILL_STRIP` list, with that measurement written into the list's own
+note, and the real fix (separating the stored envelope from the body at the
+metadata layer) is filed as #5309 rather than bought by teaching the authoring
+vocabulary two storage keys.
+
+**This is a shape check, not a second servability judge.** ADR-0121's rules —
+the `apps/<namespace>` carve-out (D1/D2), anonymous-requires-an-armed-`rateLimit`
+(D6), the supported target subset, mapping and policy — stay with
+`validateApiEndpointDeclarations` / `identityFreeEndpointGateFailure`, which run
+at publish and again at load. A pin test asserts an anonymous unmetered endpoint
+parses green here and is still refused by the gate, so the two never grow
+competing opinions.
+
+**Upgrade note (not purely additive).** A stored `api` row that does not satisfy
+`ApiEndpointSchema` is refused with 422 on its **next write**; reads and the
+existing load-time behaviour are unchanged (the matcher already excluded
+unparseable rows loudly, #5189). Every `api` declaration reachable in this repo
+— the two E8-migrated showcase endpoints and the two dogfood policy-fixture
+endpoints — was parsed against `ApiEndpointSchema` before landing this: all four
+clean. A live deployment's `sys_metadata` cannot be scanned from CI; an operator
+holding hand-written `api` rows should run `GET /api/v1/meta/diagnostics?type=api`
+(which now covers the type) before upgrading.
+
+ADR-0088's admission test is satisfied on all three clauses: independent
+lifecycle (the matcher indexes and invalidates one item at a time), declarative
+governability (`allowRuntimeCreate` plus file patterns), and a real consumer
+(#5040's executor, boot-proven by #5040 E8). This does not reverse the `router`
+kind's retirement — `router`'s delivered forms are code contributions, whereas a
+single `ApiEndpoint` is a declarative artifact, exactly the "third, real
+delivered form" ADR-0088's own `router` row anticipated.