Merge remote-tracking branch 'origin/main' into claude/issue-5309-endpoint-envelope-body-split

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/i18n-label-union-and-tab-translations.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": minor
+---
+
+i18n label contract: inline locale maps are authorized, and filter-preset tabs get a translation slot
+
+**`I18nLabelSchema` accepts two forms, not one (#5728).** It declared a plain
+`z.string()` while three published platform pages authored 31 inline
+`{ en, 'zh-CN', 'ja-JP', 'es-ES' }` maps that objectui resolves through
+`pickLocalized` — so the authoritative document was the wrong one, and the
+#5068 component-props gate reported 42 findings against the platform's own
+pages. The schema is now a union of the default-language string and an inline
+locale map. `ElementTextPropsSchema.content` was declared a bare `z.string()`
+and therefore out of that union's reach; it moves onto `I18nLabelSchema` in the
+same change, which is the other 8 of the 42. The gate now reports **0**.
+
+This does not reverse #4667 / #5055. What those retired was the *key-reference*
+dialect (`{ key, defaultValue }`) — a shape with **no resolver**, whose label
+reached the screen as a raw key or not at all. What is authorized here is the
+inline locale map, which has a live resolver and which the CLI's `i18n-extract`
+already understands. Same "declared = enforced" principle, applied in both
+directions: the map's keys are constrained to BCP-47 tags (plus `default`), so
+`{ key, defaultValue }` stays a parse error rather than becoming "a locale map
+whose locales are named `key` and `defaultValue`".
+
+Zero breaking: every previously-valid label is still valid. The
+translation-bundle channel remains the direction that scales and is unchanged.
+
+**Filter-preset tab labels are translatable (#5377).** `ObjectTranslationData`
+gains `_tabs`, addressed by `ViewTabSchema.name`, and `resolveTabLabel` reads
+it — explicit `_tabs` translation, then the referenced view's `_views.*.label`
+for a tab that carries `view` (the path that already worked, preserved), then
+the authored literal. A tab carrying only a `filter` referenced nothing to
+inherit from and had no key of its own, so its label rendered in the source
+language above a fully localized grid with no authoring workaround. `os i18n
+extract` scaffolds the new keys, so the slot, the resolver and the extractor
+land together.
+
+`I18nLabelSchema`'s description no longer claims "i18n keys are auto-generated
+by the framework" — none are. `AriaPropsSchema.ariaLabel` now states that no
+translation-bundle slot addresses it.