Merge remote-tracking branch 'origin/main' into claude/issue-5619-sink-engine-dispatch

Author: claude

.changeset/action-session-positions-canonical-roles-alias.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `ActionSession` declares `positions` as canonical and deprecates `roles` (#5779)
+
+The action-body `ctx.session` contract gains `positions`, the ADR-0090 D3 spelling
+of the caller's position names, and demotes `roles` to a deprecated alias of it.
+This is the **spec half** of #5613 phase 2, under the maintainer's contract-first
+ruling ("C skeleton + A semantics"): phase 1 (#5697) declared the shape the runtime
+already built, and this opens the rename on top of that declaration.
+
+**What was wrong.** `buildActionSession()` copies `ExecutionContext.positions` into
+a key spelled `roles` — the one spelling ADR-0090 D3 bans — so an author met two
+different answers to one key name on one platform: `session.roles` is rejected in a
+hook (retired in #5050) and live, populated, and load-bearing in an action body.
+Phase 1 declared that reality without endorsing it and deliberately withheld a
+`positions` key, because minting a second live spelling with no closing date is the
+defect rather than the fix. This change mints it **with** a closing date.
+
+**Migration prescription — do this now.**
+
+- Read `ctx.session.positions`. It is the canonical key and it carries exactly the
+  array `roles` carried; the rename is a rename, not a semantic change.
+- `ctx.session.roles` still resolves for the length of the deprecation window and
+  is removed after it, on the path `session.tenantId` already walked (#3280
+  deprecated, #3290 removed in v11). A body still reading it at that point sees
+  `undefined` with nothing to catch the change — which is why the read moves inside
+  the window, not at its close.
+- Do **not** migrate an access check by renaming it. `roles.includes('admin')`
+  rewritten as `positions.includes('admin')` migrates the defect: neither array is
+  an authorization input. Privilege is judged by the security service, which
+  evaluates capability grants, placements and the derived posture (ADR-0095).
+
+**Sequencing — the contract leads its producer.** This release ships the contract
+only. The producer change (`buildActionSession()` emitting both keys, plus the two
+already-tracked wrong sentences in its docblock) is #5613's runtime half and lands
+separately. Until it does, a built session still carries only `roles`, so
+`positions` is meaning-fixed but not yet presence-guaranteed; both keys are
+optional, which is what lets the declaration lead without breaking anything. A
+reader that must straddle the seam may read `positions` and fall back to `roles`
+for the window's duration only — that fallback expires with the alias.
+
+Additive and non-breaking on its own: adding an optional key rejects nothing that
+parsed before, and the runtime consistency pin
+(`packages/runtime/src/action-session-shape-contract.test.ts`) is unchanged and
+still green.
+
+The reader-facing announcement is the ADR-0087 semantic migration
+`action-session-roles-to-positions`, which carries the prescription above and its
+acceptance criteria into `spec-changes.json`, the generated upgrade guide and the
+`spec_changes` MCP tool.

.changeset/auth-where-operator-coverage.md

@@ -0,0 +1,55 @@
+---
+"@objectstack/plugin-auth": patch
+---
+
+fix(plugin-auth): `convertWhere()` 补齐 `not_in` / `starts_with` / `ends_with`,未识别算子改为响亮拒收 (#5813)
+
+`convertWhere()` 的分支链只覆盖 better-auth 十一个算子里的八个。
+`not_in` / `starts_with` / `ends_with` 落在链尾之外:**`filter` 里不写任何键**,
+不告警,链尾也没有 `else` 兜底。一个只带这类条件的 `where` 因此编成 `{}`。
+
+**丢谓词不是把结果变窄,是变宽 —— 而且发生在身份表上**(#3948 反复论证过的形状,
+driver-memory 的匹配器 `default:` 臂与 objectql 的 `having` 都为此改成了拒收):
+
+- `findMany` / `count` 变成**全表**(仅受 `limit` 截断)。已挂载的
+  `GET /api/v1/auth/admin/list-users`(`auth-route-ledger.ts:161`)把查询参数直接
+  推进 `where`,而 `searchOperator` 的枚举是 `contains | starts_with | ends_with`、
+  `filterOperator` 的枚举**就是整张算子表**。于是
+  `?searchValue=abc&searchOperator=starts_with` 返回的是「全部用户」而不是「以 abc
+  开头的用户」,`?filterField=email&filterOperator=not_in&filterValue=…` 不排除任何人。
+  管理台的用户检索是它的主要消费者。
+- `update` / `delete` / `consumeOne` / `incrementOne` 走的是「先 `findOne(filter)`
+  再按 id 写」,`{}` 让 `findOne` 返回**任意一行**(实测是第一行),于是写到了错误的
+  记录上。实测证据:对四行表执行「删除 `name` 以 `zed` 开头的用户」,修复前删掉的是
+  `u_abc1`(第一行),不是 `u_zed`。
+
+## 改了什么
+
+**一、三个算子按词表直译**(三个 ObjectQL 算子都在 `FILTER_OPERATORS` 里,
+五后端都必须求值):
+
+| better-auth | ObjectQL |
+|:--|:--|
+| `not_in` | `$nin` |
+| `starts_with` | `$startsWith` |
+| `ends_with` | `$endsWith` |
+
+大小写语义两侧同向,直译不开契约缝:better-auth 的 `Where.mode` 默认
+`"sensitive"`,`$startsWith` / `$endsWith` 按 #5701 Q2=A 在契约层也是大小写敏感。
+
+**二、链尾未识别算子响亮抛错**,不再静默丢。错误信息带算子名、字段名与受支持算子
+清单,本身就是操作指引。这是 restore-invariant:否则 better-auth 下次加算子时,
+这个洞会以完全相同的方式重开一次。
+
+## 对使用方的影响
+
+- 用上述三个算子的查询**从「返回全表 / 写错行」变成「按谓词正确过滤」**。这是缺陷
+  修复,不是可依赖行为的移除 —— 但依赖「`starts_with` 检索能列出全部用户」的脚本会
+  看到结果变化。
+- 传入**词表之外**的算子从「静默忽略该条件」变成**抛错**。今天没有活体调用方能命中
+  这一支(`/admin/list-users` 的两个参数都由 better-auth 自己的 zod 枚举把关),它面向
+  的是将来:better-auth 长出第十二个算子时,查询会在第一次执行就失败,而不是悄悄放大。
+  该分支同时是编译期哨兵(`never` 收敛),`pnpm --filter @objectstack/plugin-auth
+  typecheck` 会先一步报错。
+- `Where.mode: 'insensitive'` **不在**本次范围内,也不会被这条拒收波及 —— `mode` 是
+  `operator` 的兄弟字段而非算子,今天仍被忽略(#5814,决策箱中)。

.changeset/authorable-surface-anchor-monotonic.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): `--update-base` re-anchors forward or refuses — never backwards, never mid-merge (#5370)
+
+#5358 made re-anchoring `packages/spec/authorable-surface.base.json` an explicit act
+(`gen:authorable-surface-base`). It settled **when** the anchor may be written, not **where
+from**: the baseline is still `merge-base(HEAD, origin/main)`, and that is not always ahead
+of the anchor already committed.
+
+The reported way in is a stopped merge. Until the merge is committed, `HEAD` is the branch
+tip from *before* it, so the merge base is the branch's **old fork point** rather than the
+main tip being merged in, and re-anchoring there rolls `baseRev` backwards. Measured on the
+#5312 sync relay: `1c3da1f` → `5aae790`, returning the 109 keys #5321 had just retired.
+
+Nothing could catch it. The older rev is a genuine `origin/main` ancestor and the keys
+written are that commit's surface verbatim, so the regressed file is **authentic** —
+`verifyCommittedSurfaceBase`, `check:authorable-surface` and the pre-commit `os-regen` guard
+are green before and after. The only trace is a reverse `baseRev` move in the diff, which
+reads like the #4650 attack shape and was written by the generator itself.
+
+Two refusals, both in `--update-base` only:
+
+- **Mid-merge**: `MERGE_HEAD` present (resolved via `git rev-parse --git-path`, so linked
+  worktrees are handled) refuses before a single schema is generated, the way
+  `--check --update-base` already did, and prescribes the remedy — commit the merge, then
+  re-anchor. `scripts/regen-artifacts.mjs` states the same rule for the merge driver's side
+  ("Re-anchor after the merge is committed, or not at all"); this enforces it for the human
+  who types the command anyway.
+- **Monotonicity**: the write happens only when the committed `baseRev` is an ancestor of
+  the newly resolved rev. Equal keys still take the existing "nothing to re-anchor" path.
+
+Ancestry that cannot be established refuses too, rather than defaulting to either verdict:
+`merge-base --is-ancestor` is read as three answers (`0` / `1` / anything else with a
+`fatal:`), and a `1` from a **shallow** checkout is discarded as unusable — truncation makes
+git report "not an ancestor" about commits that plainly are one. A `0` is trusted
+everywhere, shallow included, because a truncated walk can only lose reachability, never
+invent it.
+
+`gen:schema` and every build are untouched: since #5358 they do not write this file at all,
+so a build during a merge behaves exactly as before.

.changeset/changelog-ships-in-tarball.md

@@ -66,7 +66,6 @@
 "@objectstack/types": patch
 "@objectstack/verify": patch
 "create-objectstack": patch
-"objectstack-vscode": patch
 ---
 
 chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)

.changeset/config.json

@@ -75,7 +75,6 @@
       "@objectstack/embedder-openai",
       "@objectstack/account",
       "create-objectstack",
-      "objectstack-vscode",
       "@objectstack/connector-openapi",
       "@objectstack/verify"
     ]

.changeset/index-type-partial-removed.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/spec": major
+"@objectstack/metadata-core": patch
+---
+
+refactor(spec)!: retire `indexes[].type` and `indexes[].partial` — two authorable index keys no driver ever read (#5248, #4943)
+
+`IndexSchema` declared five keys; only three of them ever reached a `CREATE
+INDEX`. `SqlDriver.syncDeclaredIndexes` builds every declared index through
+knex's `table.index(fields, name)` / `table.unique(fields, { indexName })`, and
+the drift differ's `DeclaredIndexInput` carries `name` / `fields` / `unique` /
+`nullSafeColumns`. So:
+
+- **`partial`** — documented as *"Partial index condition (SQL WHERE clause)"* —
+  produced a **full** index with the predicate silently discarded. This was the
+  damaging half, because it reads as a correctness control: the platform's own
+  `sys_metadata` declared `partial: "state = 'active'"` for overlay uniqueness,
+  and what the declaration alone materialized was an *unrestricted* unique index.
+- **`type`** additionally carried `.default('btree')`, so it appeared in **every**
+  parse output of **every** index — an access-method knob that had never
+  influenced a single statement, rendered as live configuration. (It was pinned
+  as such in a `sys_presence` test, on an object that never declared it.)
+
+Both are the ADR-0078 no-silently-inert / ADR-0049 enforce-or-remove shape.
+Remove was chosen over enforce: enforcing needs per-dialect algorithm mapping
+(`gin`/`gist` Postgres-only, `fulltext` MySQL-family), raw-SQL `CREATE INDEX …
+WHERE` on the dialects that have partial indexes at all (MySQL does not), and a
+redesign of how `isSyncReproducibleIndex` excludes partial indexes from
+incremental sync — design cost for a capability with no demand. If a real need
+appears it returns enforce-first.
+
+## Migration
+
+| FROM | TO |
+| :--- | :--- |
+| `indexes: [{ fields: […], type: 'gin' }]` | `indexes: [{ fields: […] }]` — create the specialised index from a database-layer migration |
+| `indexes: [{ fields: […], partial: "state = 'active'" }]` | `indexes: [{ fields: […] }]` — issue `CREATE [UNIQUE] INDEX … WHERE …` from a runtime migration |
+
+**One-line fix: delete the key.** Neither removal changes any DDL, because no
+DDL ever depended on them — verified byte-for-byte against the `CREATE INDEX`
+statements SQLite actually stores
+(`packages/drivers/driver-sql/src/declared-index-retired-keys.test.ts`).
+
+Both capabilities remain available where they are implementable. The index
+method is the driver/dialect's choice. A partial index is issued as raw SQL from
+a runtime migration — exactly what `metadata-protocol`'s `ensureOverlayIndex`
+already does for `sys_metadata`, and what actually delivers that table's
+active-row-scoped uniqueness today.
+
+⚠️ **Not affected:** driver-sql's own `partial` flag (`parseIndexDdl` /
+`introspectIndexes` / `isSyncReproducibleIndex`). That is a boolean parsed back
+out of the *database's own* DDL for drift detection — the opposite direction —
+so migration-created partial indexes stay recognized and exempt from incremental
+sync, unchanged.
+
+## The retirement kit
+
+- `retiredKey()` tombstones at `IndexSchema` (the shape is deliberately
+  `.strip()`, so a plain delete would swap one silent no-op for another): writing
+  either key is now a `tsc` error and a parse error carrying the prescription.
+  They sit at the bottom of the shape per the #5606 renderer note.
+- **ADR-0087 D2 conversion + D3 chain step** (`object-index-type-partial-removed`,
+  `toMajor: 17`, wired into the existing step-17 chain): strips both keys from
+  `objects[]` and `objectExtensions[]`; `os migrate meta --from 16` rewrites sources
+  mechanically. A pure lossless delete — there was no effect to lose.
+- **Producers flipped:** `sys_metadata` (`idx_sys_metadata_overlay_active`, the
+  case #4943 named) and `sys_view_definition` (`idx_sys_view_def_active`), both
+  with their comments corrected to say what is actually materialized.
+- Published skill (`objectstack-data`), `content/docs/data-modeling/objects.mdx`,
+  liveness ledger note and generated baselines updated.

.changeset/layered-read-outage-is-not-no-overlay.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/metadata-protocol": patch
+---
+
+fix(metadata-protocol): 分层读的 overlay 读失败不再被画成「这一项没有定制」(#5707)
+
+`getMetaItemLayered` 是 Studio「code / overlay / effective」对比视图背后的那次读
+(`GET /api/v1/meta/:type/:name?layers=true`)。它的 `sys_metadata` overlay 读裹着一个
+裸 `catch`,注释写着 "DB unavailable — overlay stays null" 然后照「没有 overlay 行」
+返回。
+
+那不是一个中性的兜底值。这个信封在**同一次响应里同时给出三个正面断言**,而且是 200:
+
+- `overlay: null` —— 「这一项从来没有被定制过」;
+- `overlayScope: null` —— 「org 和 env 两个作用域都没有行」;
+- `effective === code` —— 「现在生效的就是打包件原样」。
+
+对比视图存在的意义正是回答作者「我改过什么」。故障期它回答「什么都没改过」——
+和 #5532 同一个错误(可用性故障被讲成作者的声明事实),只是落在 diff 视图而不是 404 上。
+本次沿用 #5532 / PR #5705 的判定,补上该 PR 按 scope 刻意没有覆盖到的这一处读。
+
+**改了什么**:这一处 `catch` 改为调用同文件的 `rethrowUnlessMetadataStoreUnprovisioned`
+—— `isMissingTableError`(表尚未建 → 确实没有 overlay 行)良性放行,其余上抛
+`status: 503` / `code: SERVICE_UNAVAILABLE`,驱动原始错误挂在 `cause` 上。没有新增
+判定逻辑,也没有新的返回形状:分层信封仍是 code / overlay / effective 三**层**,而不是
+每层三**态** —— 「读不到」不是一层,所以照失败上报,不再冒充某一层的取值。
+
+**wire 可见变化**
+
+| 场景 | 之前 | 之后 |
+|---|---|---|
+| `sys_metadata` 不可达 | `200` + `overlay: null` / `overlayScope: null` / `effective = code` | `503` + `SERVICE_UNAVAILABLE`(`cause` 带驱动报文),可重试 |
+| org 作用域读失败、env 行本可读 | `200`,连那行 env overlay 也一并报告为「没有」 | `503`,同上 |
+| `sys_metadata` 尚未建表 | `200` + 只有 code 层 | 不变 |
+| 存储正常 | 不变 | 不变 |
+
+REST 侧无需改动:`?layers=true` 与普通读共用同一个 `handleRouteError`,#5437 / #5464
+的消毒与日志口原样接住。已测量的消费方处置也都已就位:objectui 的
+`MetadataClient.layered()` 对非 2xx 一律 `throw`(只有 404 映射为空信封),
+ResourceEditPage 的加载 `try/catch` 把它渲染成错误态而不是空白页;
+`plugin-security` 的三个消费点里,两处本就有 `catch` 兜底,唯一没有的
+`projectPermissionMutation` 在 503 化后反而更安全 —— 此前的静默 `null` 会让权限集
+投影悄悄退回打包基线(`customized: false`),没有 declared body 时甚至会把记录
+retire,而协议的 `runMutationProjector` 契约是 never throws,会把 503 收敛成
+`projectionApplied: { success: false }`。