Merge remote-tracking branch 'origin/main' into claude/issue-5928-hook-exclude-objects

Author: claude

.changeset/autonumber-seed-suffix-parse.md

@@ -0,0 +1,41 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/driver-sql": patch
+---
+
+fix(objectql,driver-sql): 自增号播种按声明的 `suffix` 定位计数器,两侧收敛到同一答案 (#6468)
+
+`autonumberFormat` 允许序号槽 `{0..0}` **后面**还有 token —— `renderAutonumber`
+专门返回 `suffix`,其契约就是 `prefix + zero-padded(seq) + suffix`。这类格式渲染
+出的值**序号不在串尾**:`{000}-{YYYY}` 渲染成 `001-2026`,是很常见的单号写法。
+
+两侧的播种解析却都假定「串尾的数字就是计数器」,而且各错各的:
+
+- 引擎兜底播种 `seedAutonumber()` 取整串的**最后一个**数字段 —— 读到的是年份。
+  库里三行 `001-2026`/`002-2026`/`003-2026`(真实计数器 3)把计数器播种成 **2026**,
+  下一个发出的号直接跳到 `2027-2026`;
+- driver-sql 的 `scanMaxNumericTail()` 把 tail 里**所有**数字拼接后 `parseInt` ——
+  同样三行读成 **12026**,下一个号是 `12027-2026`。
+
+于是**同一份元数据、同一批行,换个驱动号段就不一样**;中间跳过的号已经烧掉,事后
+无法回收。只修一侧会把「两个不同的错误答案」变成「一个对一个错」,跨驱动仍不一致,
+所以两侧同 PR 修。
+
+**修法:两侧解析器尊重已声明的 `prefix`/`suffix`。** 两个字符串都由调用方从
+`renderAutonumber` 的返回值取得后传入 —— 两侧都不再自行理解格式,driver-sql 只收
+参数(`getNextSequenceValue` 仅多转发一个位置参数,序列逻辑本身未动):
+
+- **prefix / suffix 任一非空 ⇒ 计数器「有锚」**:取 prefix 之后的**首个**数字段,
+  并在该行确实带有声明的 suffix 时先把它去掉;
+- **两者皆空 ⇒ 「无锚」**:各自的既有读法**逐字保留**(引擎取整串最后一个数字段,
+  driver-sql 拼接全部数字)—— 无 `{0..0}` 槽的格式渲染的就是串尾裸计数器,而早于
+  格式存在的历史值根本没有锚可依。
+
+**suffix 只在匹配时剥离,绝不要求匹配。** `{000}-{YYYY}` 的计数器 scope 是渲染后的
+**prefix**(此处为空),即全局一个计数器、只有显示的年份在变,所以去年的 `007-2025`
+持有计数器 7,必须计入。把 suffix 下推成 `like '%-2026'` 会把这些行整批漏掉、播种
+**低于**真实 max —— 那正是 #6249 修掉的重复单号伤害,自己再造一遍。因此 SQL 谓词
+保持 `like 'prefix%'`,suffix 只在 JS 侧逐行使用。
+
+无后缀格式(`D-{0000}`、`{0000}`)两侧本来就正确,行为不变并已 pin 住;#6467 的
+播种扫描结构未触碰。

.changeset/capability-metadata-kind-registry-entry.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-protocol": patch
+---
+
+fix(spec,metadata-protocol): `capability` 补齐三处注册 —— 授权面不再接受任意 JSON (#5961)
+
+`capability` 是「enforced but undeclared」——#5271 给 `api` 关掉的那个
+`declared ≠ enforced` 的镜像。平台早就把它当成一个 metadata kind 在用:
+`PLURAL_TO_SINGULAR` 从 #5870 起就有 `capabilities` → `capability`,
+`AppPlugin` 用这个名字注册 stack 声明的 capability,
+`bootstrapDeclaredCapabilities` 再读回来 seed `sys_capability`。但三处注册表
+里都没有它:`MetadataTypeSchema`(kind 枚举)、`BUILTIN_METADATA_TYPE_SCHEMAS`
+(schema 解析)、`DEFAULT_METADATA_TYPE_REGISTRY`(谁可以写、怎么加载)。
+
+后果有两条,第二条才是这个 issue 属于授权缺陷而非整洁度问题的原因:
+
+- `getMetadataTypeSchema('capability')` 返回 `undefined`,于是 `saveMetaItem`
+  走了它自己文档化的「未注册类型 → 不校验直接存」分支,
+  `PUT /api/v1/meta/capability/:name` 接受**任意 JSON** 落进 `sys_metadata`。
+  capability 是靠**名字字符串**被解析的——授予侧 `systemPermissions`、
+  要求侧 `requiredPermissions` 都是——所以一行任意 JSON 直接落在活的授权命名
+  空间里。
+- `isRuntimeCreateAllowed` 镜像 `getMetaTypes()` 的合成规则:没有静态注册表条目
+  的类型被当作可运行时创建。所以缺的那一行不只是「没关上门」,它**把门打开了**。
+  `/meta/types` 同步发布了这个虚构:`allowRuntimeCreate: true` + 无 schema,
+  metadata-admin 引擎据此渲染成一个 raw-JSON 文本框。
+
+### 改了什么
+
+- **`BUILTIN_METADATA_TYPE_SCHEMAS['capability'] = CapabilityDeclarationSchema`**。
+  既有的 422 `invalid_metadata` 路径就此覆盖 `capability`,`/meta/types` 发出真
+  JSON Schema。
+- **`DEFAULT_METADATA_TYPE_REGISTRY` 新增 `capability` 条目,
+  `allowRuntimeCreate: false` + `allowOrgOverride: false`**。ADR-0066 D1:包
+  DEFINE capability,权限集 GRANT,资源 REQUIRE。管理员在运行时凭空造一个
+  capability 在这个三分里没有位置——代码里不会有任何地方 require 那个名字,这行
+  只是授权命名空间里一个无人引用的授予目标。这一对标志就是 #5086 的 CODE-ONLY
+  声明,`saveMetaItem` 在**任何** kernel 上都以 403 `not_creatable` 拒绝,并从条
+  目自己的 `filePatterns[0]` 读回「该去哪儿声明」。`supportsOverlay: false`——
+  capability 只是名字/标签/scope,没有 merge 语义,而允许租户 overlay 一个包发布
+  的声明等于允许把 `scope` 从 `org` 抬成 `platform`。`loadOrder: 12` 早于
+  `permission`/`position`(15),使权限集的 `systemPermissions` 解析时 capability
+  已经存在。
+- **`MetadataTypeSchema` 枚举补 `'capability'`**。
+- **`CapabilityDeclarationSchema` 声明 ADR-0010 保护信封并收紧为 `.strict()`**。
+  信封是必须的:loader 对每个已注册类型都调 `applyProtection`,不声明就会 422 掉
+  loader 自己的输出(#4001 在 `permission`/`position` 上补过同一个洞)。收紧则与
+  `api` 不同——`ApiEndpointSchema` 同时是**存储行**的解析器,所以它留在
+  `STILL_STRIP`;而没有任何地方拿这个 schema 重新解析 `sys_capability` 行
+  (`bootstrapDeclaredCapabilities` 通过 `capabilityRowFields` 按名读字段),
+  所以收紧零成本,买到的是一个授权面本就该有的 declared = enforced 姿态。
+  改用 `strictObject` 书写,已知键从 shape 派生,不新增手抄键表。
+
+**包声明通道完全没动。** `AppPlugin` 通过 `registerInMemory` 注册 stack 的
+`capabilities[]`,文件系统 loader 按 `filePatterns` glob——两条都不经过
+`saveMetaItem`,所以 `bootstrapDeclaredCapabilities` 依旧照常 seed。
+`OS_METADATA_WRITABLE=capability` 仍是 ADR-0005 那唯一一道运维逃生门,而在它后面
+写入现在由 `CapabilityDeclarationSchema` 判定(422),不再原样落盘。
+
+⛔ `role` / `profile` / `policy` **不搭车**:它们没有 `PLURAL_TO_SINGULAR` 映射、
+没有声明 schema、没有读回接缝,是另一个问题,另开单。这条以断言形式钉在
+`capability-metadata-kind.test.ts` 里,因为「capability 有了条目,邻居也该有」
+正是下一个显而易见却错误的改动。

.changeset/discovery-environment-single-default.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": patch
+"@objectstack/metadata-protocol": patch
+"@objectstack/runtime": patch
+---
+
+fix(spec,metadata-protocol,runtime): one place decides what an unset `NODE_ENV` advertises (#5936)
+
+A deployment whose operator never exported `NODE_ENV` must not describe itself as
+`development` on `/discovery`: `environment` is a machine-readable field, a client
+reads it to answer "am I talking to production?", and it may skip production warnings
+or loosen a destructive action's confirmation on the answer. #5673 ruled that in and
+fixed it — but only for one of the two producers, because that dispatch put
+`packages/spec` out of scope. The other one, `MetadataProtocol.getDiscovery()` (served
+by `@objectstack/rest`), went on answering `development` for exactly that input.
+
+The default now lives in the shared mapper, `resolveDiscoveryEnvironment`: an absent —
+or blank — value resolves to `production`, and both producers pass the operator's value
+through as they read it, neither carrying a default of its own. That is what makes it
+one decision instead of two copies, and it means the next discovery producer inherits
+the right answer without anyone remembering to copy a line. Patching only
+metadata-protocol would have left a second copy of the default — precisely the drift the
+shared table was created to prevent (#4828).
+
+"Unset" includes a blank value: `NODE_ENV=` exports an empty string, the runtime's
+`getEnv` has always folded that into its default, and had the mapper treated blank as
+"anything else" the two producers would have drifted again on that one input.
+
+**#4828's rule is untouched, and it points the other way on purpose.** A value that IS
+set but is not a spelling this repo recognises (`qa`, `preview`) still degrades to
+`development`, so nothing ever claims `production` on a guess. Absence is not a guess —
+it is the host declining to say.
+
+Behaviour change to expect: a host that exports no `NODE_ENV` and serves `/discovery`
+through `@objectstack/rest` now advertises `environment: "production"` where it
+previously advertised `"development"`. A deployment that genuinely is development should
+say so — `NODE_ENV=development` — which is what the runtime dispatcher has already
+required since #5673.
+
+The mapping table above `NODE_ENV_TO_DISCOVERY_ENVIRONMENT` is corrected in the same
+pass: its `unset / anything else -> development` row had been false for the runtime
+caller since #5673 and is now two rows, one per rule.

.changeset/etl-pipeline-layer-retired.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: retire the L2 ETL layer — `automation/etl.zod.ts` had no executor, and the sync architecture doc was recommending it (#6414)
+
+`ETLPipeline`, `ETLPipelineRun`, `ETLSource`, `ETLDestination`, `ETLTransformation`,
+the `ETLEndpointType` / `ETLTransformationType` / `ETLSyncMode` / `ETLRunStatus`
+enums and the `ETL` factory are REMOVED under ADR-0049 enforce-or-remove. The whole
+file goes, on the same reading #4738 used to retire L1 `DataSyncConfig` one layer up:
+**narrative-only**. No engine ever parsed, scheduled or executed an `ETLPipeline`.
+
+Measured on `origin/main` immediately before the removal: the only non-spec
+references in this repo are two fumadocs-generated documentation sources
+(`apps/docs/.source/*.ts`), not executors; objectui has no reference at all; and
+there is no `packages/spec/liveness/etl.json`, so no ADR-0049 gate ever had a reading
+on the surface — while the same file family's EXECUTED half does have one
+(`liveness/mapping.json`), which is what makes that absence meaningful rather than an
+oversight.
+
+FROM → TO, layer by layer — with one gap stated plainly instead of redirected:
+
+| removed | use instead |
+|---|---|
+| `ETLPipeline.source` + `syncMode` + `schedule` (scheduled extraction from an external system) | `ConnectorSchema.syncConfig` (`integration/connector.zod.ts`) — the live, parsed sync surface: strategy, direction, cron schedule, `conflictResolution`, batching, delete mode |
+| `ETLTransformation` of type `map` / `cast`-like per-field work | `mapping.fieldMapping[].transform` (`data/mapping.zod.ts`) — `none`/`constant`/`map`/`split`/`join`/`lookup`, applied row by row by the REST import path |
+| `ETLPipeline.schedule` alone | `system/job.zod.ts` |
+| `ETLTransformation` of type `join` / `aggregate` / `script` / `merge` / `deduplicate` / … | **nothing.** There is no replacement because there was never an implementation — those ten transformation types named capabilities no runtime had. Do the work where it runs (the destination warehouse's ELT, a `flow`, a scheduled job), and let multi-stage movement return through ADR-0049's ENFORCE route: the engine first, the vocabulary second |
+
+**The fix:** delete the import. Nothing was ever deployed under an `ETLPipeline` —
+that is the finding, not a consolation — so there is no data migration; `tsc` reports
+TS2724/TS2305 at every import of a retired name.
+
+**`packages/spec/docs/SYNC_ARCHITECTURE.md` is rewritten in the same change**, and
+that is not incidental. It named `ETLPipeline` as the recommended destination for
+authors displaced by the L1 retirement and tabulated ten transformation types with
+copyable examples down to `script | Custom JavaScript/Python`. Retiring the schema
+while the doc still recommended it would have been self-contradictory, and
+forwarding L1's authors to a second layer with no executor was the defect compounding
+rather than closing.
+
+**Absorbed:** the #4962 `etl-retry-converged-onto-retry-policy` entry (`retry.maxAttempts`
+→ `maxRetries`, default 3 → 0) — both land in the unreleased protocol 17, so composed,
+a rename on a shape that does not survive the major has no observable effect, and its
+`retiredKey()` tombstone goes with the shape that carried it.
+
+The retirement kit — route 3: no tombstone, no D2 conversion.
+`RETIRED_DEFS_BY_MAJOR[17]` (9 defs) plus the D3 `SemanticMigration`
+`etl-pipeline-layer-retired` are the declaration.
+
+<!-- adr-0087: registered etl-pipeline-layer-retired -->

.changeset/http-server-runtime-vocabulary-retired.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: retire `system/http-server.zod.ts`'s runtime vocabulary — the event, capability and status shapes nothing ever emitted (#5295)
+
+`ServerEventType`, `ServerEventSchema` / `ServerEvent`, `ServerCapabilitiesSchema` /
+`ServerCapabilities` / `ServerCapabilitiesParsed` and `ServerStatusSchema` /
+`ServerStatus` are REMOVED under ADR-0049 enforce-or-remove. This is the second and
+final pass over the file: #4938 removed its CONFIG half (`HttpServerConfigSchema`,
+nine keys, zero readers, zero authoring entry), and this removes the RUNTIME half —
+a 7-member lifecycle event union, an eight-boolean capability report and a
+five-state status record with connection and request counters. Nothing ever emitted,
+consumed or parsed any of them.
+
+FROM → TO:
+
+| removed | what actually decides it |
+|---|---|
+| `ServerEventType` / `ServerEvent(Schema)` | nothing emits a server event feed. Lifecycle is the transport plugin's own start/stop seam; observability is `system/metrics.zod.ts` + `system/logging.zod.ts`, and `OS_SERVER_TIMING` for timings |
+| `ServerCapabilities(Schema/Parsed)` | a transport plugin declares what it provides by implementing the kernel plugin contract — the seams it registers ARE the capability statement |
+| `ServerStatus(Schema)` | `/health` for liveness, the metrics surface for counters |
+
+**The fix:** delete the import. There is no replacement key, because there was
+never a key — none of the four was authorable on any shape. Server-level
+configuration that IS authorable is untouched: `defineStack({ server: { trustProxy,
+security } })` / `StackServerConfigSchema` (#5006) parses exactly as it did in 16.x,
+as does the route-registration half of the same module (`RouteHandlerMetadata`,
+`MiddlewareType`, `MiddlewareConfig`).
+
+**Why now, and what unblocked it.** The card was held rather than queued on a real
+doubt: a response/capability vocabulary can legitimately be a REFERENCE surface for
+host implementers, so "zero consumers in this repo" is weaker evidence for one of
+those than for an authorable key. It was lifted by measuring the reference reader
+itself — `plugin-hono-server`, the one in-tree host implementation, neither
+implements nor reports any of the three: it names no capability record, no status
+shape and no event union, and what it registers is routes and middleware. The
+control passed in the same sweep (`MiddlewareConfig`, twelve lines away, resolves to
+`packages/runtime/src/middleware.ts`).
+
+The retirement kit — route 3 of the retirement playbook, as #4938 was in this same
+file: **no `retiredKey()` tombstone and no D2 conversion**, because a prescription
+nobody can receive is noise and there is no authored document to rewrite.
+`RETIRED_DEFS_BY_MAJOR[17]` (4 defs) plus the D3 `SemanticMigration`
+`http-server-runtime-vocabulary-retired` are the declaration; the generated
+baselines (`json-schema.manifest/system.json`, `authorable-surface/system.json`,
+`api-surface/system.json`) lose their entries in the same change, deliberately.
+
+If host-implementer conformance becomes a real requirement it returns through the
+ENFORCE route: an adapter contract with a checker behind it, vocabulary second.
+
+<!-- adr-0087: registered http-server-runtime-vocabulary-retired -->

.changeset/import-dryrun-asks-for-the-verdict.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/rest": patch
+"@objectstack/objectql": patch
+---
+
+fix(rest,objectql): the import dry run asks the engine for its verdict instead of predicting it (#4633 ruling D)
+
+`POST /api/v1/data/:object/import?dryRun=true` green-lit rows the very same
+endpoint then rejected. Measured on 17.0.0-rc.1: a CSV cell aimed at a
+structured `address` field reported `{ ok: 1, created: 1 }` on the dry run and
+`{ errors: 1, code: 'VALIDATION_FAILED' }` on the real write.
+
+The dry run predicted the write's verdict with a hand-copied mirror of a slice
+of the engine's rules (`import-coerce.ts`'s `firstMissingRequiredField` and
+`firstConstraintViolation`). A copy cannot structurally keep up with the family
+it mirrors: ADR-0104 value shapes (`address` / `location` / references / media),
+`format` checks, object-level `validations` and the state machine had no
+counterpart, and `coerceFieldValue` routes structured shapes through its
+pass-through catch-all, so no verdict was formed at all.
+
+**The mirror is retired.** The dry run now calls `DataProtocol.validateData`
+(#6037), which runs the same `validateRecord` / `evaluateValidationRules` that
+`insert()` runs, under the deployment's own ADR-0104 posture — so a bad value
+shape is an error on a self-certified deployment and an admitted warning on a
+warn-first one, exactly as on the write. Agreement is by construction, not by a
+copy kept in step by hand.
+
+Also in this change:
+
+- **`engine.validate()` now resolves `defaultValue`s and seeds owned roll-up
+  `summary` fields before validating, on `insert` mode**, because `insert()`
+  does. Without it a required-but-defaulted column left unmapped was previewed
+  `failed` and written `created` — a false alarm on the row a preview is meant
+  to reassure you about. `update` mode still does not default (#2706).
+- **A row report failed by validation now names the offending column.** The
+  engine's `ValidationError` carries `fields[]`, so the row's `field` is set and
+  its `code` is the field-level code (`required`, `min_value`, `max_length`,
+  `invalid_type`, …) rather than the wrapper's `VALIDATION_FAILED`. This is the
+  same vocabulary the dry run and the per-cell coercion failures already spoke;
+  before, a `min: 0` violation was `min_value` on the dry run and
+  `VALIDATION_FAILED` on the write.
+- **Dry-run rows may carry `warnings[]`** — findings this deployment admits
+  rather than rejects (ADR-0104 warn-first). The row is `ok`, and the complaint
+  is visible instead of living only in a server log line.
+
+A protocol that does not implement `validateData` (plugin-auth's identity
+import, whose write is better-auth rather than the engine) is not handed a
+substitute: its dry run reports coercion and create/update/skip resolution only.
+An engine-derived preview of a non-engine write would report findings that write
+never produces.