Merge origin/main into claude/issue-5271-api-metadata-type-registry

Author: claude

.changeset/auth-invalid-membership-policy-outcome.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/plugin-auth": minor
+---
+
+fix(auth): an unrecognised membership policy is refused by both reconcilers, not auto-bound by one of them (#5205)
+
+**The sign-up path used to bind anyway.** `reconcileMembership` and
+`backfillMemberships` — both public exports of `@objectstack/plugin-auth` — read
+the same `policy` field and judged it with opposite predicates. Sign-up tested
+`policy === 'invite-only'`, so any *other* value fell through to the `auto`
+branch and auto-bound the new user; the backfill tested `policy !== 'auto'` and
+refused. One input, two opposite postures, and the fail-open half was the one
+that runs per sign-up. A caller who wrote `'inviteOnly'` — or any host passing
+the policy from JavaScript, past the `MembershipPolicy` type — got auto-binding
+while believing they had switched it off, with nothing in the logs to say so.
+
+Both entry points now check `isMembershipPolicy()` before any policy semantics
+and refuse: nothing is bound, and the refusal names the offending value at
+`error` level (and on the returned result, so it survives a caller that passed
+no logger). This is the posture #5152 took one layer up at the settings
+boundary — an unrecognised value is rejected loudly, never coerced to `auto`.
+
+**Contract change — `ReconcileOutcome` gains `'invalid-policy'`, and
+`BackfillMembershipsResult.reason` gains the same member.** Both are exported
+types, so a consumer that switches exhaustively over them (a `never`-checked
+`default`, or a `Record< ReconcileOutcome, … >`) must handle the new member.
+The new verdict is deliberately *not* a reuse of the existing `policy-skip` /
+`'policy'`: those mean "a valid policy said no", and reporting them for "this
+is not a policy" sends whoever is debugging a missing bind to inspect a
+deployment setting that is fine. `BackfillMembershipsResult` also gains an
+optional `error?: string`, and the `logger` shape on `ReconcileMembershipDeps`
+gains an optional `error?` method (it falls back to `warn`).
+
+**No behaviour change for the two real policies.** `auto` binds and
+`invite-only` skips exactly as before, on both paths — the framework's own
+callers resolve the policy through `AuthManager.getMembershipPolicy()`, whose
+return type is `MembershipPolicy`, so nothing on a supported path can reach the
+new branch. This closes the dormant divergence on the export surface.

.changeset/dataset-cross-datasource-compile-gate.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/service-analytics": minor
+---
+
+fix(service-analytics): reject a dataset's cross-datasource JOIN when it is compiled, not when it is queried (#5115)
+
+#5033 routed a dataset's raw SQL to its base object's own datasource, which
+turned a JOIN whose target lives in another database into a **loud query-time
+failure** — correct, but late: the dataset can still be saved, published and
+put on a dashboard, and the failure lands in front of whoever opens that
+dashboard, usually in another environment on another day. It is a pure metadata
+error, decidable the moment the dataset is compiled: the whole dataset is
+lowered into ONE statement on the base object's datasource, so a join target
+bound elsewhere is simply not there.
+
+`compileDataset` now decides it. `AnalyticsService.registerDataset` — the single
+door every dataset passes through, whether pre-registered at boot, saved, or
+previewed as a Studio draft — hands the compiler the datasource and federation
+probes that already existed on `AnalyticsServiceConfig`, and a proven conflict
+is rejected before any SQL is built. The message names both objects, both
+datasources, the offending `include` path, and the two ways out (bind both
+objects to the same datasource, or drop the relationship), in the same wording
+family as the #5033 query-time diagnostic so the two never read as two bugs.
+
+**Who is affected.** This is a tightening: a dataset that used to compile and
+then fail (or, before #5033, silently read the wrong database) now fails at
+registration. It fires only where the metadata *proves* the conflict — the base
+object and a join target each declare an explicit `object.datasource` and the
+two names differ. A dataset registered at boot is skipped with a WARN naming the
+conflict, as before; the rest of the host's datasets still register.
+
+**What is deliberately not rejected** ("cannot answer, do not block", the same
+tiering as `isRegisteredObject` / `getObjectFieldNames`):
+
+- a host that wires no datasource probe at all (no data engine) — compiles
+  exactly as it did before;
+- either side leaving `datasource` at its default. `'default'` is the schema's
+  default *value*, not a routing decision: `ObjectQL.getDriver` short-circuits
+  only on an explicit non-`'default'` name, then falls through to
+  `datasourceMapping` rules, the ADR-0057 §3.6 lifecycle split
+  (audit/telemetry/event) and the owning package's `defaultDatasource` — none of
+  which are visible to the compiler. Treating `'default'` as "the primary DB"
+  would reject datasets whose objects a mapping rule in fact lands on the *same*
+  database;
+- a federated (external) participant on either side. `NativeSQLStrategy` already
+  declines such a cube (ADR-0062 D6), so the query is served by the ObjectQL
+  FK-expand path, which crosses datasources by construction.
+
+Everything not proven here keeps failing loudly at query time via #5033.
+Making cross-datasource dashboards actually *work* (declining in
+`NativeSQLStrategy` and serving the join with two reads) is separate and not
+part of this change.

.changeset/kernel-shutdown-isolate-and-honest-timeout.md

@@ -0,0 +1,44 @@
+---
+"@objectstack/core": patch
+---
+
+fix(core): one throwing `kernel:shutdown` handler no longer skips every plugin `destroy()` and kills the process under a false "Shutdown timed out" (#5274)
+
+**On `ObjectKernel`, a single bad shutdown subscriber used to end the entire teardown
+and `process.exit(1)` the host — reporting a timeout that never happened.**
+
+`performShutdown()` dispatched `kernel:shutdown` through `context.trigger` (a bare
+awaited loop that never catches), so the first handler that threw propagated out to
+`shutdown()`'s `Promise.race` catch. That catch was written for the timeout race alone
+and treated every exception as one, producing three consequences at once:
+
+1. the remaining `kernel:shutdown` handlers never ran;
+2. **every** plugin's `destroy()` was skipped — the reverse-order destroy pass sits
+   after the trigger in `performShutdown()`, so it was never reached;
+3. the process was killed by `process.exit(1)` under the log line
+   `Shutdown timed out — forcing exit`, while nothing had timed out — sending whoever
+   read it to the `shutdownTimeout` config for a handler bug.
+
+Two changes, matching the reasoning #5257 recorded at `LiteKernel`'s shutdown dispatch
+site:
+
+- **`kernel:shutdown` now dispatches ISOLATING on `ObjectKernel` too.** A handler that
+  throws is logged as `Hook handler failed: kernel:shutdown` and the remaining handlers
+  still run, followed by the reverse-order `destroy()` pass and the `onShutdown()`
+  handlers — both of which already isolated per plugin and per handler. What is queued
+  behind a failing shutdown handler is the cleanup that flushes buffers, closes
+  connections and releases locks, so one bad handler must not amplify into leaks and
+  unflushed writes. The BOOT-path hooks are untouched: `kernel:ready`,
+  `kernel:bootstrapped` and `kernel:listening` still propagate and still fail the boot
+  (#5170, #5257).
+- **The timeout catch now handles only a genuine timeout**, discriminated by identity on
+  the timer's own rejection — not by message, not by type, so nothing a plugin throws
+  can impersonate it. A genuine `shutdownTimeout` overrun is **unchanged**: it still
+  logs `Shutdown timed out — forcing exit` and still calls `process.exit(1)`, because
+  teardown really is hung and the process would otherwise hold what it failed to
+  release. Any other exception is logged at `error` and follows the normal path —
+  `state = 'stopped'`, return — with no `process.exit`, leaving an embedding host
+  (cloud auth-proxy, CLI, a test runner) its own chance to finish cleanly.
+
+`shutdown()` still never rejects, so no existing caller changes. Telling the two paths
+apart is the point of the fix, and both are pinned by named tests.

.changeset/org-create-effective-posture-gate.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/plugin-auth": major
+"@objectstack/verify": minor
+---
+
+BREAKING(auth): `organization/create` 改判**实际生效的** tenancy posture —— 没有组织墙的部署不再能创建组织 (#5261)
+
+`POST /api/v1/auth/organization/create` 的闸门此前判的是操作者**请求的** posture
+(`postureEnforcesWall(resolveTenancyPosture())`,一次纯 env 读)。现在判 `tenancy` 服务给出的
+**生效** posture —— `tenancy?.posture ?? resolveTenancyPosture()`,与 `/auth/config` 的
+`features.multiOrgEnabled` 是**同一次求值**。
+
+## 为什么
+
+两个站点此前只在一种形状下分叉,而那种形状恰恰是最不该放行的一种 —— ADR-0093 D5 **降级态**:
+请求了 `isolated`/`group`,但企业包 `@objectstack/organizations` 缺席,于是 `tenancy.posture`
+解析为 `single` 且 `degraded=true`。此时:
+
+- 闸门读「请求」→ **放行**;
+- `/auth/config` 读「生效」→ `multiOrgEnabled=false`,console 把「创建组织」入口**藏起来**。
+
+结果是 UI 没有按钮而 API 打得通,并且建出来的每一个组织都是**没有任何引擎强制的租户边界** ——
+声明了但没强制,ADR-0049 最讨厌的那一类,只不过发生在部署层。改判生效 posture 之后两者同解、
+永不分叉:**没有墙,就没有组织**,无论这个部署是从未要过墙,还是要了没拿到。
+
+## 破坏性影响(有意为之)
+
+**没有安装企业包 `@objectstack/organizations` 的部署将完全无法创建组织**,任何 env 组合都不行 ——
+`OS_TENANCY_POSTURE=isolated`、`OS_MULTI_ORG_ENABLED=true`、两个一起设,都不再能把闸门说通。
+这是一次实打实的能力收缩,不是 knob 纠正,所以搭 v17 主版本车。
+
+| 部署形状 | 改前 | 改后 |
+|---|---|---|
+| 有企业包,posture `isolated` / `group`(墙真的立着) | 200 | **200**(不变) |
+| **请求了墙但企业包缺席(D5 降级态)** | 200 | **403** ⚠️ |
+| `single` / 两个 knob 都不设 | 403 | 403(不变) |
+| 未注册 `tenancy` 服务的精简嵌入(回落 env 解析) | 按 env | 按 env(不变) |
+
+`serve.ts` 本来就在降级态**默认拒绝启动**(要 `OS_ALLOW_DEGRADED_TENANCY=1` 才走),所以这条收缩
+命中的是一个已经需要显式选择才能到达的形状:从此那里的 org-create 路由也一并拒绝,而不是半通不通。
+cloud 控制面与任何装了企业包的部署不受影响。
+
+**迁移**:需要多组织能力的部署安装并声明 `@objectstack/organizations`(ADR-0081 D2)。仅靠 env
+声明一个墙、而没有实现它的运行时,不再被当作多组织部署对待。
+
+## `@objectstack/verify`(minor,新增)
+
+`BootOptions.multiTenant` 增加 `'posture-only'` 取值:注册一个内置的 `org-scoping` 服务替身,
+让 `tenancy` 服务解析出真实、**非降级**的 `isolated` posture,从而打开受 posture 把守的路由 ——
+供那些「组织墙是**前置条件**而非被测对象」的 fixture 使用(#3624 的 `org-create-default-team`
+dogfood 就是为它而建:那条回归此前靠「boot 后翻 env、闸门 live 读」开路,本次收缩把这个绕法关死了)。
+
+⛔ 它**不做任何租户隔离**:不 stamp `organization_id`,不 scope 任何查询 —— 它让部署的
+**posture** 为真,不是让**墙**为真。跨租户隔离的唯一诚实证明仍然是 `multiTenant: true` +
+真实的企业包,这也是那些 gate 在本仓继续 skip 而不是假装通过的原因。

.changeset/posture-misreads-sweep.md

@@ -0,0 +1,61 @@
+---
+'@objectstack/objectql': patch
+'@objectstack/runtime': patch
+'@objectstack/plugin-dev': patch
+'@objectstack/driver-sql': patch
+'@objectstack/cli': patch
+'@objectstack/cloud-connection': patch
+---
+
+fix(tenancy): eight sites answered "is this deployment multi-org?" with the demoted `OS_MULTI_ORG_ENABLED` (#5262)
+
+ADR-0105 D1 made `OS_TENANCY_POSTURE` the authoritative knob and demoted
+`OS_MULTI_ORG_ENABLED` to a back-compat *input* of `resolveTenancyPosture()`.
+A deployment configured the documented way — `OS_TENANCY_POSTURE=isolated` (or
+`group`), legacy boolean unset — therefore reads `false` from
+`resolveMultiOrgEnabled()` while running a fully mounted organization wall.
+#5233 corrected two sites in `plugin-auth`; a census found eight more, all
+written before that function's doc comment was corrected. Third recurrence of
+the shape (cloud#1020, #5233).
+
+Each site was judged separately for **which** posture answers its question —
+what the operator REQUESTED, or what the `tenancy` service reports is actually
+IN FORCE — rather than converted mechanically:
+
+- `objectql` `SchemaRegistry` — the env-derived multi-tenant default. Reads the
+  REQUESTED posture (it is constructed below the kernel, with no service
+  registry to ask). The `organization_id` column was always provisioned; what
+  diverged is its INDEX, so a posture-only deployment ran the Layer 0 wall's
+  hottest predicate unindexed while SecurityPlugin compiled that same wall.
+- `plugin-dev` — whether to load the enterprise `@objectstack/organizations`.
+  REQUESTED posture, mirroring `serve.ts`: this branch is what mounts the wall,
+  so asking whether the wall is up would be circular. A posture-only dev stack
+  previously never loaded the package at all and served traffic unwalled. Its
+  diagnostic now names the posture that was requested instead of asserting
+  `OS_MULTI_ORG_ENABLED=true` at an operator who never set it.
+- `runtime` `AppPlugin` (inline seed + hot-reload seeder) — EFFECTIVE posture,
+  via the `tenancy` service. These ask "will the per-org replay run instead of
+  me?", and on an ADR-0093 D5 degraded boot that replay does not exist, so
+  keying on the request would defer to a replay that can never happen. Walled
+  deployments previously inline-seeded exactly the NULL-organization rows the
+  code's own comment exists to avoid.
+- `cloud-connection` marketplace local install (install-time seed + rehydrate
+  heal) — EFFECTIVE posture, same reasoning. The install path is a write path:
+  a walled deployment wrote every sample row with no `organization_id`, landing
+  the app's data outside the wall its own reads apply.
+- `driver-sql` `isMultiTenantMode()` — REQUESTED posture (a driver has no
+  kernel to ask, and a suppressed warning is the costlier error for a
+  diagnostic). It also no longer memoises into `_multiTenantMode`: that froze a
+  process-level fact into a per-instance verdict on whichever write landed
+  first. The gate now resolves live, which is affordable because
+  `auditMissingTenant` consults it only after the `tenantId` early-out.
+- `cli` `os verify` — REQUESTED posture. This one produced a green verification
+  run over an unverified property: a posture-only deployment silently skipped
+  every multi-tenant proof and exited 0.
+
+**No configuration change is needed anywhere.** Deployments setting only
+`OS_MULTI_ORG_ENABLED=true` keep working unchanged — `resolveTenancyPosture()`
+falls back to it — and the `OS_TENANCY_POSTURE=isolated` + `OS_MULTI_ORG_ENABLED=true`
+belt-and-braces configuration stays valid. Deployments that set only
+`OS_TENANCY_POSTURE` can now drop the redundant boolean. Single-org behaviour is
+unchanged at every site; only the knob each one reads is corrected.

.changeset/publish-drafts-endpoint-gate.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): `publishPackageDrafts` 现在对 `api` draft 跑 ADR-0121 端点发布门 (#5206 step 2)
+
+`protocol.publishPackageDrafts` 是 Studio「全部发布」的真实入径(ADR-0033 /
+ADR-0067 D2)。在此之前,它唯一的按类型前置检查是对象命名空间前缀
+(`validateObjectNamespacePrefix`,仅 `d.type === 'object'`),于是一条 `api`
+draft **不经任何一道门**就被提升为 `active` —— 与 #5189 在
+`MetadataManager.publishPackage` 上修掉的是同一形状、另一条路。
+
+安全后果早已被 PR #5203 的装载期兜底挡住:端点匹配器在建索引时用同一个
+`firstFailure` 重判每一条存量条目,没过门的被排除出索引并 `error` 点名。所以
+这次修的是**拒绝得太晚**:ADR-0121 的原文是「publish 拒绝」,作者应当在
+publish 当场拿到点名 key 的处方,而不是到装载期日志里才发现自己的端点在答
+404。
+
+**判据只有一份。** 本改动调用 `@objectstack/spec/api` 导出的
+`validateApiEndpointDeclarations`(#5203 公开)—— 就是 stack schema 跑的那个
+函数、`publishPackage` 跑的那个函数、装载期兜底跑的那个 `firstFailure`。拒绝
+文案直接用门函数自己的消息(已包含端点名、越界的 key 和改法),本包不复述任何
+一条「什么算可服务」的规则。
+
+与 `publishPackage` 不同,这条路**有身份**:包的 `manifest.namespace` 本来就
+为对象前缀规则读过了,所以这里跑的是**全量门**,命名空间门(ADR-0121 D1/D2)
+包含在内。命名空间门**不**以「包声明了 namespace」为条件 —— 门函数自己的前置
+判据(声明了 `apis:` 的 stack 必须显式声明 `manifest.namespace`)本身就是一条
+判据,对「压根没有 namespace」的包跳过它,等于给最不可能过编译期的那批包留一
+个洞。对象前缀规则对无 namespace 的包网开一面,是因为一个裸对象名只是命名气味;
+一个无命名空间的端点是一个**无主 URL**。
+
+**行为变化(用户可见)**:
+
+- 一条 `api` draft 若违反端点门(最典型:ADR-0121 D6 —— `authRequired: false`
+  却没有 `rateLimit.enabled: true` 的预算),`publishPackageDrafts` 现在返回
+  `success: false` / `publishedCount: 0`,该条目进入 `failed[]`,`code`
+  为 `ENDPOINT_GATE`;body 连 `ApiEndpointSchema` 都不满足的,`code` 为
+  `ENDPOINT_SCHEMA`(解析是判定的前置,不是第六道门 —— 判不了的形状也服务不
+  了)。
+- **失败粒度沿用既有语义,未发明新的批次语义**:与命名空间前缀违规完全一致,
+  这是一次**提升任何东西之前**的前置拒绝,整批不落地(`published: []`),同批
+  的健康 draft 保持 draft 态。这既是 ADR-0067 D2 的「一次 commit 不能落一半」,
+  也是 #5189 在另一条路上的同一姿势(`itemsPublished: 0`)。两类违规现在合并
+  在**同一份报告**里返回,作者一次往返就能看全。
+- 判定范围是**本批被提升的 draft**,与紧邻它的对象前缀规则一致。与同包已
+  `active` 的端点撞车不在此拦截 —— 匹配器对全库重复声明有确定性裁决并 `error`
+  点名(`buildEndpointIndex`);把范围扩到整包 active 集合意味着「因为你没在发
+  布的东西而拒绝这次发布」,那是另一份契约,不是一个 bug 修复。
+
+装载期兜底(#5203)原样保留,未移除也未削弱:publish 是**更早**的那道门,不是
+最后那道门的替代品。
+
+`api` 进 `DEFAULT_METADATA_TYPE_REGISTRY` / `BUILTIN_METADATA_TYPE_SCHEMAS`
+(即 Studio 直写路径的 422)是 #5206 的第 1 步,拆在子单 #5271(spec 车道);
+本改动**不依赖**它落地。