Merge origin/main into claude/issue-5503-autonumber-readonly-strip

Conflict: packages/objectql/src/engine.ts — the `insert()` doc comment only,
where #5610 (strictReadonlyWrites, #5126) and #5503 each rewrote the same block.
Resolved by SUPERPOSITION, not by taking a side.

Both incoming notes carried the same standing condition, and #5503 is what
discharges it:

  - #3407: "if insert ever gains a silent strip, wire the listener at that
    strip site";
  - #5126: "`strictReadonlyWrites` is inert here ... because insert strips
    nothing. If insert ever gains a strip, both members wire up together at
    that site."

#5503 gives insert a strip (caller-supplied runtime-owned `autonumber`), so
both members of `WriteObservabilityOptions` now discharge at that site:

  - default    → strip, commit, report via `onFieldsDropped` (unchanged);
  - strict ON  → `ReadonlyFieldRejectedError` before any driver call, and the
    listener deliberately does NOT fire (a refused write did not complete —
    #5126's own design point, mirrored).

UPDATE needed no new code: the autonumber limb rides `stripReadonlyFields` →
`reportDroppedFields` → `assertNoStrictDrops`, the seam #5126 already built, so
a caller-supplied record number is refused at equal rank with a declared
`readonly` field for free. Pinned by test rather than assumed.

`ReadonlyFieldRejectedError` gained an optional `operation` (default `'update'`,
so #5126's UPDATE message stays byte-identical) because the verb and the
remedies genuinely differ: an INSERT refusal is always about a runtime-owned
value, whose exempt writers are `isSystem` and the `preserveAudit` historical
import, while `readonlyWhen` cannot lock anything on a create.

No new policy was invented at the seam. #5126 states that strict "adds no
second policy — it reports the existing one", and that a field the strip does
not take is not rejected either; applying that verbatim is what keeps the
`isSystem` / `preserveAudit` exemptions accepted under strict. Pinned in tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V7WetGmnfoXNn8cLieKKmx

Author: claude

.changeset/alias-integrity-direct-call-sites.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": patch
+---
+
+Put the 44 pre-helper alias tables under the alias-integrity gate — including the
+collision claim they were never measured on.
+
+`alias-integrity.test.ts` (#5013) judges alias tables built by `strictObject`,
+which registers each one alongside the `.shape` it makes claims about. The 44
+call sites that predate that helper call `strictUnknownKeyError` directly and
+hand it a transcribed `knownKeys` array; with no shape to register, they sat
+outside every claim the gate makes.
+
+`strictUnknownKeyError` now records its own `{ surface, knownKeys, aliases,
+guidance }` in an internal registry, and the gate judges that batch too. The
+registration lives in the factory, so no schema module changed.
+
+What each claim is worth on this batch differs, and the gate says so rather than
+implying uniform coverage:
+
+- **alias key is not a known key** and **alias target is a known key** are
+  answered against the transcribed array. If that array has drifted from its
+  schema, both answers inherit the drift — the gap `strictObject` exists to
+  abolish, and only migrating a call site closes it (#5593).
+- **no two alias keys share an `aliasProbe`** (#5481) loses nothing: a collision
+  is a property of the table alone. These tables were **unmeasured** on it, not
+  clean — #5481 postdates the measurement recorded in #5483 — and the sweep they
+  had never had comes back clean at 52 tables.
+
+The target claim found a real one on its first run: `ui/app.zod.ts` shares four
+"start expanded" aliases across all nine navigation-item variants, but `expanded`
+is declared on the `group` variant alone, so on the other eight the suggestion
+names a key that variant also rejects — the second rejection this campaign
+exists to end. Filed as #5555 (the fix rewrites author-facing message text) and
+pinned here shrink-only, structurally, so nothing else can enter the tolerance.
+
+Two supporting pieces, both deliberately visible rather than implicit: the walk
+now forces error maps that build themselves on first use (`data/object.zod.ts`
+defers its map around a temporal dead zone, and would otherwise never register),
+and the six prose alias targets on `ui/app.zod.ts`'s navigation items —
+`type: 'url' (with url)` and friends, which name a variant rather than a key —
+are an enumerated allowlist scoped to that surface, with a staleness check that
+fails if an entry stops being used.
+
+The shrink-only ratchet at 44 is unchanged. What it discourages — a new call
+site minting a fresh second copy of a key list — is exactly as undesirable as it
+was before these tables gained a guard.

.changeset/delete-fallback-success-shape.md

@@ -0,0 +1,39 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): `callData('delete', …)` 的 ObjectQL 兜底返回 spec 声明的 `{ object, id, success }`,与 protocol 路径同形 (#5581)
+
+`callData` 是 protocol 优先 + ObjectQL 兜底,两条路径此前对「删除成功」给的是两种形状:
+
+| 路径 | 此前 | 现在 |
+|---|---|---|
+| protocol(`deleteData`) | `{ object, id, success: true }` | 不变 |
+| ObjectQL 兜底 | `{ object, id, deleted: true }` | `{ object, id, success: true }` |
+
+规范只有一个:`DeleteDataResponseSchema`(`packages/spec/src/api/protocol.zod.ts`)声明的是
+`{ object, id, success }`,`deleted` 从未被任何 schema 声明;公开的 HTTP 文档
+(`content/docs/protocol/kernel/http-protocol.mdx`)也一直写的是 `success`。所以兜底是唯一
+的偏离方,protocol 路径与 spec、与文档都无需改动。
+
+这是 #5138 同一族缺陷的成功侧:#5138 收敛的是「记录不存在」的答案,本次收敛的是「删除成功」
+的答案 —— 后者是每一次正常请求都会走到的面,而非只在 id 写错时才碰到。此前按
+`DeleteDataResponseSchema` 写的客户端,在**未注册 `protocol` 槽**的精简装配上会从一个 HTTP 200
+里读到 `success === undefined`,即「删除到底成没成功」读不出来,而调用方无从分辨自己走的是哪条
+路径。消费端各自兼容 `success ?? deleted` 两种拼写正是 contract-first 禁止的形状,所以修在
+生产方,不在消费方。
+
+## ⚠️ 升级须知(行为变化)
+
+**仅影响没有安装 `MetadataPlugin`(`@objectstack/metadata-protocol`,即注册 `protocol` 槽)的
+精简装配。** 装了该插件的部署走 protocol 优先路径,本来就返回 `success`,不受影响。
+
+在这类精简装配上,以下三个面的 `DELETE` 成功体键名由 `deleted` 改为 `success`:
+
+- `DELETE /api/v1/data/:object/:id`
+- MCP 的 `delete_record` 工具(`domains/mcp.ts` 的 `remove` 桥)
+- 声明式端点(`objectParams.operation: 'delete'`,#5092)
+
+若你的代码读的是 `response.data.deleted`,请改读 `response.data.success` —— 这也是 spec 与
+公开文档自始至终声明的键。删除行为本身(含 #5138 落的「记录不存在则 404 `RECORD_NOT_FOUND`
+且不发出写」)完全未变,变的只有成功体拼写这一个键。

.changeset/doctor-optional-package-load-boundary.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `os doctor` no longer treats a broken `@objectstack/cloud-connection` install as "not installed" (#5644)
+
+`readInstalledPackageEntries()` reached the installed-package ledger through a
+dynamic `import('@objectstack/cloud-connection')` whose `catch` meant "the
+optional package is not installed". That is right for one of the two things it
+caught:
+
+- **The specifier does not resolve** — the optional package really is not
+  there. Silence is correct and unchanged: `os doctor` must run to completion in
+  a checkout that never had it.
+- **The package is installed and will not load** — a pruned or unbuilt `dist/`,
+  an interrupted install, an artefact that throws while it evaluates, a
+  transitive dependency missing under it. It threw too, so it was answered with
+  the same silence.
+
+The ADR-0120 D5e unique-scope advisory then saw "no installed packages", found
+nothing to report, and the run printed:
+
+```
+  ✓ Unique scope          No unconfirmed installation-wide uniques for this 'isolated' environment
+```
+
+Measured: with the package present-but-unloadable and a ledger declaring an
+installation-wide `unique`, that line was printed and the finding appeared
+nowhere, `--verbose` included. It is the same false PASS #5412 removed at the
+`readdir` boundary and #5413 at the entry boundary, one boundary further up —
+and `os serve`, loading the same package in the same directory, has always named
+the failure out loud.
+
+The two states are now separated by **resolution**, not by the `import()` having
+thrown (`isModuleNotFoundError()` first — an error that is not a module-not-found
+error came from the package itself, so it is present by definition; then
+`import.meta.resolve()`, which answers "is the package there" without stating its
+entry file, unlike `createRequire().resolve()`). Only the genuinely-absent half
+is silent. The other prints an ordinary `HealthCheckResult` through the same
+renderer every other check uses:
+
+```
+  ⚠ Unique scope          Could not load the installed-package ledger reader (installed packages
+                          NOT checked for installation-wide uniques) — Cannot find module …
+```
+
+**Warning, not error**, and the exit code is unchanged, matching its two
+siblings: the environment still runs; what broke is doctor's ability to see part
+of it. The cause is quoted from the thrower, and `--verbose` expands it together
+with the remedy — reinstall, or build the package in a monorepo checkout.
+
+The row is **not** conditional on `.objectstack/installed-packages/` existing.
+Doctor cannot honestly say a ledger is absent when the constant naming the
+ledger's location is an export of the package that would not load.
+
+One consequence worth stating: in a monorepo checkout where
+`packages/cloud-connection` has not been built, `os doctor` under the `isolated`
+posture now prints this warning instead of a clean bill. That state is exactly
+what sent #5612 chasing a report face that had never regressed.

.changeset/flow-time-relative-descriptor-lint.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): report a `config.timeRelative` descriptor the sweep will refuse, at authoring time (#5496)
+
+A flow start node declaring `config.timeRelative` got **zero** authoring-time
+diagnostics when its descriptor could not parse. The two rules that look at the
+slot each looked at something else: `lint-flow-patterns` decides "this is a
+time-relative flow" from `timeRelative != null` alone (never the shape), and
+`validate-flow-trigger-readiness`'s existing check reads only
+`timeRelative.object`, to compare it against the stack's objects. So
+
+```ts
+config: { timeRelative: { object: 'task', field: 'due_at', offsetDays: -1 } }
+```
+
+— three separate schema violations: `dateField` missing, `offsetDays` declared
+as an int **array** and written as a scalar, and `field` an unrecognized key —
+passed `os validate` silently. `TimeRelativeTriggerSchema` does reject it, but
+the only place that schema ran was **bind time**, inside
+`TimeRelativeTriggerPlugin.start()`, which warns and returns: the sweep is never
+installed, the flow reports itself armed, and the author's sole feedback is one
+line in a server log. For an AI author that line is outside the feedback loop
+entirely; `os validate` is what it reads.
+
+**New rule — `flow-time-relative-descriptor-invalid` (warning).** A start node
+whose `config.timeRelative` is present runs that same schema at authoring time,
+and a failure is reported naming `config.timeRelative` with the schema's own
+issue list forwarded — so the diagnostic carries the missing key, the wrong type,
+and, for an unrecognized key, the "did you mean" the schema already computes
+(`field` → `dateField`) plus its wrong-layer guidance (a `schedule` written
+*inside* the descriptor is told it belongs beside it). The list is rendered
+exactly as the bind-time warning renders it, so the two channels tell one story.
+
+Nothing is shifted except **when** the schema runs. No shape knowledge is
+re-implemented in the rule and no consumer-side tolerance is added: the verdict
+and every word of its wording remain `TimeRelativeTriggerSchema`'s, so the rule
+tracks the descriptor's contract as it evolves instead of drifting from a second
+copy of it.
+
+The rule and the existing object-name check decide different facts and cannot
+report the same one twice — only the stack knows whether an object name exists,
+and only the schema knows the descriptor's shape. A descriptor wrong in both ways
+gets both findings, at their own paths. Canonical descriptors are unaffected:
+every one shipped in the repo (the showcase `Task Due Reminder`, the
+`content/docs` examples) parses, so this adds no diagnostic to existing apps.

.changeset/hook-context-session-roles-retired.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: retire `HookContext.session.roles` — declared, read by two dead branches, never produced (#5050)
+
+`session.roles` on the runtime hook context was ADR-0049's enforce-or-remove
+case with **neither end**: it was declared in `data/hook.zod.ts`, read by
+exactly two consumers, and produced by nobody. The two readers were
+plugin-approvals' admin exemptions — the approval record lock and the delegation
+write guard, each opening with `session.roles?.includes('admin')` — and both
+were deleted in #4839 (PR #5049) on the maintainer's ruling. The producer side
+was empty the whole time: ObjectQL's `buildSession()` builds the session field
+by field (`userId`, `organizationId`, `accessToken`, `isSystem`, `actor`, the
+skip flags) and has never written `roles`, and nothing else feeds a
+HookContext. So every read resolved `undefined`,
+and a guard keyed on it was dead code that merely LOOKED like an authorization
+decision — plus a second admin dialect competing with the one ADR-0090 D3 /
+ADR-0095 D3 sanction.
+
+Cross-repo consumer check ran in both directions before removing anything
+(#4895's discipline, after #4865's tombstone was disproven by objectui):
+`cloud` has zero `session.roles` while its hook consumers really do read
+`hookContext?.session?.userId` (`service-cloud/src/marketplace-visibility-plugin.ts`,
+`control-plane-org-scope-plugin.ts`) — a positive control in the same run;
+`objectui` has zero, and its `roles` are the `/auth/me` **user** payload, a
+different surface that is untouched.
+
+One neighbour is called out rather than folded in, because mistaking it for a
+producer would read as refuting the whole finding (#4865's lesson): an **action**
+body's `ctx.session` is a different, untyped object built by `runtime`'s
+`buildActionSession()`, and it does populate a `roles` key from `ec.positions`.
+It never becomes a HookContext and no schema types it, so it is neither evidence
+against this retirement nor fixed by it — it is filed and tracked apart.
+
+**Nothing observable changes.** A key nobody wrote and nothing read cannot alter
+a single decision — this is the declaration catching up with the runtime, not a
+behaviour change.
+
+FROM → TO:
+
+- `HookContext.session.roles` (`@objectstack/spec/data`) → removed. Delete the
+  key. To gate a hook on the caller, read `ctx.session.userId` /
+  `ctx.session.isSystem`; to judge PRIVILEGE, ask the security service, which
+  evaluates capability grants (`permissions`), placements (`positions`) and the
+  derived posture off the execution context (ADR-0095 D3) — never a role-name
+  string comparison.
+
+The retirement kit: the key is **tombstoned**, not deleted, because
+`HookContextSchema` is deliberately not `.strict()` (strictness there would turn
+an engine-internal enrichment into a breaking change for anyone parsing a
+context they were handed, as `provenance` was in #3712) — a plain delete would
+have stripped it in silence, the #3733 / ADR-0104 failure. `retiredKey()` gives
+both channels instead: `tsc` types the key `never` at any producer, and a parse
+raises the prescription itself. There is **no** ADR-0087 D2 conversion and
+nothing for `os migrate meta` to rewrite: a HookContext is built per operation
+by the engine and never stored, so no `sys_metadata` row, example or template
+can carry the key — the `openApi31` (#4579) / `activationEvents` (#4657) shape,
+registered as the `hook-context-session-roles-retired` **semantic** migration at
+major 17 so the prescription still reaches `spec-changes.json`, the generated
+upgrade guide and the `spec_changes` MCP tool. The four export/def ratchets are
+unchanged by design: this narrows a nested key inside a surviving def, which
+`api-surface.json`, `authorable-surface.json` (whose walk records top-level keys
+per def), `api-surface-signatures.json` and `json-schema.manifest.json` are all
+blind to — the enum-narrowing reading of the two, not the whole-def one.

.changeset/metadata-loader-delete-contract.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/metadata": patch
+---
+
+fix(metadata): `capabilities.write` now means BOTH directions — a writable datasource loader must implement `delete()` (#5276)
+
+`MetadataLoader` declared `save?` and no `delete`, so `capabilities.write` meant
+two different things at the two ends of an item's life: to `register()` it meant
+"persist into me", and to `unregister()` it guaranteed nothing at all.
+`unregister()` duck-typed `delete` at the call site and, when a loader had none,
+**silently skipped it** — then dropped the registry entry, invalidated the list
+cache and announced a `deleted` event anyway. The caller (Studio/Setup, REST
+DELETE, the CLI, a package teardown) was told the delete succeeded while the row
+stayed in the loader's store, was read straight back out by the next
+`list()`/`get()`, and survived every restart with nothing to retry it.
+
+Two changes, both making the declaration binding instead of decorative:
+
+- **`MetadataLoader` now declares `delete?(type: string, name: string): Promise<void>`.**
+  The capability is stated on the contract, next to `save?`, instead of being
+  guessed at by each caller. A loader implemented against the interface can now
+  see that the method exists.
+- **`MetadataManager.registerLoader()` rejects the combination that cannot
+  honour it.** A loader declaring `protocol: 'datasource:'` **and**
+  `capabilities.write: true` **without** a `delete()` method is refused at
+  registration with an error naming the loader, the consequence, and both
+  repairs. `registerLoader()` is the sole writer of the loader map — the
+  constructor's `config.loaders` funnel through it — so the combination can no
+  longer reach the runtime and lose a deletion there.
+
+**Does this affect you?** Only if you register a custom metadata loader that
+declares `protocol: 'datasource:'` with `capabilities.write: true`. If it does
+and has no `delete()`, registration now throws where it previously succeeded and
+quietly discarded your deletions. Two ways to fix it, both stated in the error:
+
+1. implement `async delete(type: string, name: string): Promise<void>` on the
+   loader, removing the item from its store (`DatabaseLoader` in this package is
+   the reference implementation); or
+2. if the loader is genuinely read-only, declare `capabilities.write: false` — a
+   read-only `datasource:` loader registers without complaint and is never
+   written to in the first place.
+
+Loaders on the other protocols (`file:`, `memory:`, `http:`, `s3:`) are
+unaffected in either direction: `MetadataManager` never persists to them at
+runtime, so it has no deletion of its own to take back, and they may declare
+`capabilities.write` without a `delete()` exactly as before. The one
+`datasource:` loader shipped in this package, `DatabaseLoader`, has always
+implemented `delete()` and is unchanged.

.changeset/record-highlights-field-readonly.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `RecordHighlightsField` declares `readonly` (#5176)
+
+The object form of a `record:highlights` entry now declares an optional
+`readonly: boolean`. It marks a highlight chip as non-editable — use it for
+columns a hook or automation maintains, which must not be hand-edited from the
+record header.
+
+```ts
+{
+  type: 'record:highlights',
+  properties: {
+    fields: [
+      'name',
+      { name: 'supply_share', type: 'number', readonly: true },
+    ],
+  },
+}
+```
+
+**Why this is a spec change and not a renderer detail.** The renderer's
+`HeaderHighlight` gate already refuses inline editing on a chip carrying
+`readonly`, but the key was not declared here — and the object member is not
+`.strict()`, so `RecordHighlightsField` **silently stripped** it:
+
+```
+input   { fields: [ { name: 'supply_share', readonly: true, type: 'number' } ] }
+parsed  { fields: [ { name: 'supply_share', type: 'number' } ] }
+```
+
+That worked end to end only because per-component props are not parsed on the
+live load path today (`PageComponentSchema.properties` is
+`z.record(z.string(), z.unknown())`, so the bag rides through untouched). The
+moment that gate is wired up, an authored `readonly` becomes either a silent
+strip — a machine-owned column quietly editable again, with no diagnostic
+anywhere — or a hard parse error. Declaring the key makes the authored
+declaration and the enforced behaviour the same fact, which is what ADR-0049
+asks for: it is enforced on arrival, not declared-and-inert.
+
+For authors — including AI authors — the key now appears in the generated
+component reference, and a misspelling (`readOnly`, `read_only`) is a wrong key
+rather than a second de-facto contract the renderer happens to honour.
+
+Purely additive: `readonly` is optional and no default is materialized, so an
+entry that does not author it parses exactly as before, and the bare-string form
+of a highlight field is unchanged.