Merge remote-tracking branch 'origin/main' into claude/issue-4709-homepageid-tombstone-copy

Author: claude

.changeset/lint-searchable-fields-type-validation.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): 视图 `searchableFields` 按运行时同一套判定做构建期校验 —— 一个 lookup 笔误不再等到 400 才暴露 (#4830)
+
+视图(list view)的 `searchableFields` 会被客户端逐字回显为 `$searchFields` 覆盖参数,而
+REST 入口闸(#4254)会用 `resolveSearchFieldResolution`(`@objectstack/spec/data`)判定
+该对象的可搜索集合 —— 声明一个 lookup 等「不可搜索」字段,运行时会把**整条查询** 400
+(`INVALID_FIELD`),列表工具栏搜索对全体角色彻底不可用。此前 `compile`/`validate` 只查
+字段**存在性**,这类笔误全绿放行,只能靠人肉点搜索框发现。
+
+新增规则 `searchable-field-unsearchable`(error 级,新导出常量同名):对每个视图级
+narrowing(对象内建 `listViews`、`defineView` 的 `list`/`listViews`、react 页面的
+`<ListView searchableFields>`)按**运行时同一个函数**(`resolveSearchFieldResolution`,
+非复制的类型清单,杜绝再度漂移)判定 declared = enforced:
+
+- 对象未声明 `searchableFields`(auto 源):视图里出现 lookup/json/hidden/审计列等
+  auto-default 拒绝的字段 → 构建期 error,信息含类型与 400 后果,lookup 给出「镜像到本
+  对象 text/formula 字段」的处方;
+- 对象已声明(declared 源):视图条目超出对象声明集合 → 构建期 error(视图只能收窄、
+  不能放宽,ADR-0061);
+- 对象自身的 `searchableFields`(canonical)维持**只查存在性**:运行时 declared 分支按
+  存在过滤、不按类型过滤,声明即被引擎执行,构建期拒绝会误伤运行时接受的元数据
+  (ADR-0072 D1);
+- 注册表注入的系统列在 narrowing 中跳过判定(其运行时元数据对 linter 不可见,宁可漏报
+  不可误报)。
+
+内部核心 `checkSearchableFieldList` / `indexObjectSearchTargets`(模块级导出,未入包
+barrel)签名有变:索引值从 `Set<string> | null` 变为 `ObjectSearchTarget | null`,并新增
+可选 `role: 'canonical' | 'narrowing'`(默认 `'narrowing'`)参数。

.changeset/retire-activation-events.md

@@ -0,0 +1,65 @@
+---
+"@objectstack/spec": major
+---
+
+refactor(spec)!: remove `activationEvents` (both keys) and the `ActivationEventSchema` vocabulary — lazy activation that no runtime ever implemented (#4657, ADR-0049)
+
+`activationEvents` promised lazy plugin activation ("plugins remain dormant
+until an activation event fires") on two authorable surfaces —
+`DynamicLoadRequest.activationEvents` (`@objectstack/spec/kernel`) and
+`StudioPluginManifest.activationEvents` (`@objectstack/spec/studio`, the
+`defineStudioPlugin` input) — and **no runtime in objectstack / cloud /
+cloud-v1 / objectui ever read either key** (four-repo bare-name scan in #4657,
+re-verified at implementation time). Every plugin has always activated
+immediately on load/registration; cloud-v1's own ROADMAP recorded lazy
+activation as ❌ unimplemented (planned v0.4.0). That is ADR-0049's
+declared ≠ enforced shape in the semantically-lying direction: an author
+writing `activationEvents: [{ type: 'onMetadataType', pattern: 'flow' }]`
+expected deferral and got eager activation with a clean parse.
+
+#4653 had just converged the two `ActivationEventSchema` declarations onto one
+structured `{ type, pattern }` form inside this same unreleased major; with the
+enforce-or-remove ruling landing on **remove**, that converged vocabulary
+retires before ever shipping. Composed across the two changes, a v16 author
+simply deletes the key in whichever form they carried.
+
+Migration (FROM → TO):
+
+- `activationEvents` in a `defineStudioPlugin` input / `StudioPluginManifest`
+  value — v16 string form (`['*']`, `['onMetadataType:flow']`) or v17-rc
+  structured form (`[{ type: 'onStartup', pattern: '*' }]`) alike →
+  **delete the key**. There is no replacement value: eager activation is the
+  only behaviour there has ever been, and `activate()` still runs at
+  registration time. The strict manifest parse rejects the key (and its former
+  VS Code-flavoured aliases `activation` / `events` / `onActivate`) with this
+  prescription.
+- `activationEvents` in a `DynamicLoadRequest` value → **delete the key**.
+  Tombstoned, not silently stripped — `DynamicLoadRequestSchema` is not
+  `.strict()`, so a `retiredKey()` tombstone makes authoring it a `tsc` error
+  and a parse error carrying the prescription.
+- `import { ActivationEventSchema, ActivationEvent } from '@objectstack/spec/kernel'`
+  (or `/studio`) → **no replacement export** (TS2305 after upgrade). Nothing
+  consumed the vocabulary; an exported schema with no consumer is read as a
+  capability by whoever finds it (#3950), so the orphaned def goes with the
+  keys.
+- Lazy activation is a **new capability**: if it is ever built it returns via
+  the enforce route of ADR-0049 through a new ADR — executor first, vocabulary
+  second — not by re-declaring inert keys.
+
+Self-check (#4535 §5): TS2305 — yes, two removed exports on two entries;
+metadata migration — none possible or needed (`StudioPluginManifest` is TS
+configuration parsed by `defineStudioPlugin`, a root schema never stored in
+`sys_metadata`; `DynamicLoadRequest` is a runtime request shape with no
+caller — no stored row exists for a D2 conversion to rewrite, so the change is
+one ADR-0087 D3 semantic record, `plugin-activation-events-retired`); shape
+change — two keys removed, zero behaviour change (eager activation before and
+after, byte-identical).
+
+The retirement kit: `retiredKey()` tombstone on the non-strict kernel schema;
+strict-parse `guidance` prescriptions on the studio manifest (including the
+three former aliases); ADR-0087 D3 semantic migration; baselines
+(`authorable-surface.json` — one `[RETIRED]` line, five lines dropped
+deliberately with the defs; `json-schema.manifest.json` — `kernel/ActivationEvent`
+and `studio/ActivationEvent` def removals; `api-surface.json`) regenerated
+deliberately; compiler-API export pin (`activation-events-retirement.test.ts`,
+zero holders across every public entry) — sabotage-verified.

.changeset/startup-registry-verdict-guard.md

@@ -0,0 +1,10 @@
+---
+---
+
+Tooling-only: `pnpm check:startup-registry-verdict` — startup registry reads may not record a verdict the boot can still contradict (#4777). Adds `scripts/check-startup-registry-verdict.mjs` + the shrink-only `scripts/startup-registry-verdict.baseline.json` (empty on landing), a `Lint & Type Check` step, and an AGENTS.md section. Releases nothing — no package changes.
+
+One showcase cold start on 2026-08-03 produced three instances of one shape in three unrelated subsystems written by three people at three times: ask a registry "is X there?" while the boot is still filling it, treat the "no" as final, and **record** it — cached on the instance (#4772 plugin-auth), asserted in a `warn` (#4771 service-automation), or written to the database (#4769 objectql). The provider registers a moment later and nothing undoes the record. All three are fixed; this is what stops the class from coming back.
+
+The gate matches the three-part shape, and part 3 is what makes it a rule rather than noise — a read-only probe stays completely legal, and the cures are never flagged: a probe deferred into a lazy accessor or a `kernel:ready` hook, a probe whose ordering an ADR-0116 declaration (`dependencies` / `optionalDependencies` / `requiresServices`) has already made final, and a verdict drawn at a declared seal (`sealNodeTypeVocabulary()`) all pass.
+
+Its reach is stated rather than implied: it under-matches on purpose. `getService('cache')` is visible, a `resolveCacheOrFallback()` three layers down another package is not, and #4769 is invisible to it entirely — that "registry" is the `sys_migration` table in a database. This stops the bleeding; it does not cure. Whether the kernel contract should be tightened further is #4776.

.changeset/sys-comment-retire-visibility-reply-count.md

@@ -0,0 +1,68 @@
+---
+"@objectstack/plugin-audit": minor
+---
+
+feat(plugin-audit)!: retire `sys_comment.visibility` and `sys_comment.reply_count` (#4756, ADR-0049)
+
+Both fields were modelled with **zero** runtime consumers — nothing in this repo,
+in `objectui`, or in `cloud` ever read or maintained either one. ADR-0049
+enforce-or-remove; maintainer decision: remove both. Same disposition, and for
+the same stated reason, as `sys_attachment.share_type` / `sys_attachment.visibility`
+in #2755 ("attachment access is derived from the parent record").
+
+**REMOVED — `sys_comment.visibility`** (`'public' | 'internal' | 'private'`,
+defaulted `'public'`).
+
+This one is a **security-looking key with no gate behind it**, which is the
+primary reason it goes rather than stays. No code path consulted it: not
+`enforceFeedsCapability`, not the record-level gates added in #4630, not the
+REST layer, not objectui's discussion panel. A comment an author marked
+`private` was visible to exactly the same people as a `public` one — an app
+author (or an AI authoring metadata) reading the field list would reasonably
+believe otherwise, and get a silent security failure instead of an error. That
+is the Prime Directive #10 trap in its textbook shape.
+
+There is **no replacement key**: after #4630, who can see a comment is decided
+by the record-level permissions of the record its `thread_id` names — one
+coherent rule. A per-row enum layered on top would be a second source of truth
+for the same question. The enum's only genuinely missing meaning ("hidden from
+external/portal principals") depends on external principals existing at all,
+which waits on ADR-0090 D11's `externalSharingModel`; today there is nobody to
+hide a comment from. This does not foreclose that design — when portals land,
+a visibility key can return **enforce-first**, with a real gate and tests.
+
+**FROM → TO:** stop sending `visibility` on `sys_comment` writes; to restrict
+who sees a discussion, restrict who can read the record `thread_id` points at.
+
+**REMOVED — `sys_comment.reply_count`** (`number`, `defaultValue: 0`,
+`readonly: true`).
+
+Never incremented anywhere, and `readonly` meant an author could not set it by
+hand either, so every row read `0` forever — a UI binding an "N replies" badge
+to it rendered `0` for every thread. Deliberately **not** replaced by an
+`afterInsert`/`afterDelete` roll-up: the predicate/bulk write-hook gaps tracked
+by #4770 / #4778 / #4779 (a hook that returns early without a single-record id
+lets the whole bulk operation through) are exactly where a hook-maintained
+counter drifts — a bulk delete of replies would never decrement it. A counter
+that drifts is worse than no counter, because both the UI and an AI reading the
+record trust it. If a badge needs the number, aggregate `parent_id` children at
+read time; a designed roll-up can be revisited once #4775's family has settled
+bulk-hook semantics.
+
+**FROM → TO:** replace reads of `reply_count` with a count of `sys_comment` rows
+whose `parent_id` is the comment's id.
+
+**Stored data.** Existing databases keep both columns as **unmanaged leftovers**
+— no migration, matching #2755. What changes where:
+
+- **Reads are loud everywhere.** The read-axis gates (#4134 / #4226) resolve
+  field names from the object schema, not from the table, so a filter, sort,
+  `select` or `expand` naming `visibility` / `reply_count` now answers
+  `400 INVALID_FIELD` on every deployment, leftover column or not. A "0 replies"
+  badge that silently lied becomes an error that names itself.
+- **Writes are loud on new databases only.** A database provisioned after this
+  change has no such column, so the write fails at the driver and is mapped to
+  the same `400 INVALID_FIELD` envelope. On a pre-existing database the leftover
+  column still accepts a value nothing will ever read — record validation does
+  not reject undeclared keys. Dropping the two columns is an optional manual
+  cleanup, not a requirement.

.github/workflows/lint.yml

@@ -204,6 +204,24 @@ jobs:
       - name: Durability-degradation log-level guard
         run: pnpm check:durability-log-level
 
+      # Startup registry-verdict guard (#4777). One showcase cold start produced
+      # three instances of one shape in three unrelated subsystems: ask a
+      # registry "is X there?" while the boot is still filling it, treat the
+      # "no" as final, and RECORD it — cached on the instance (#4772
+      # plugin-auth), asserted in a warn (#4771 service-automation), or written
+      # to the database (#4769 objectql). The provider registers a moment later
+      # and nothing undoes the record. This gate walks the AST for that
+      # three-part shape: a pre-ready registry read (init()/constructor, or an
+      # ADR-0018 open capability registry before its seal) whose absent verdict
+      # is recorded. Reading is legal and must stay legal — a probe licensed by
+      # an ADR-0116 declaration, or one deferred into a closure/kernel:ready
+      # hook, is exactly the fix and is never flagged. Deliberately narrow: it
+      # cannot see a probe behind an indirection in another package, and it
+      # cannot see #4769 at all (that "registry" is a database table). Runs its
+      # own --self-test first.
+      - name: Startup registry-verdict guard
+        run: pnpm check:startup-registry-verdict
+
       # Release-notes drift guard: the platform is one version-locked train, so
       # every released @objectstack/spec major must have a curated, navigable
       # release page at content/docs/releases/v<major>.mdx. Catches the gap that

AGENTS.md

@@ -601,6 +601,72 @@ shrink-only.
 
 ---
 
+## Startup registry reads — never record a verdict the boot can still contradict
+
+A boot fills its registries incrementally. Asking a registry "is X there?" while
+it is still filling is fine — the answer is simply not final yet. Turning that
+not-yet into a **verdict and recording the verdict** is the defect, because the
+provider registers a moment later and nothing goes back to undo the record.
+
+Decide with **one question**, the counterpart of the degradation-log-level one:
+
+> **At the moment this code concludes "X is not registered", can a provider
+> still register X during this same boot? And is that conclusion RECORDED
+> anywhere that outlives the moment?**
+> **Yes and yes → defect.**
+
+Three parts, all three or it is not a finding:
+
+1. a read of a registry that is still filling — the service registry during
+   `init()`, or a plugin-extensible capability registry before it is sealed;
+2. a terminal conclusion drawn from "absent";
+3. that conclusion **recorded** — cached in an instance field or module binding,
+   asserted in a `warn`, or persisted.
+
+Part 3 is what makes this a rule and not noise. **A read-only probe is
+completely legal**: `AutomationEngine.getUnknownNodeTypeAudit()` reads the
+executor registry on every call, records nothing, and is correct.
+
+**Why this is a rule and not a preference.** One showcase cold start on
+2026-08-03 produced three instances, in three unrelated subsystems, written by
+three people at three times: plugin-auth froze an `undefined` cache handle into
+its config for the life of the process, so rate-limit counters never reached the
+shared store and the printed warning sent operators to provision Redis for a
+problem they did not have (#4772); service-automation asserted that eight
+approval flows "will fail at execution time" 0.8s before the executor that runs
+them was registered, and a deployment that genuinely lacked the plugin emitted
+the identical eight, so the signal could not tell the two apart (#4771); objectql
+wrote an ADR-0104 attestation into `sys_migration` during the same boot that was
+still seeding rows contradicting it, so the next restart rejected its
+predecessor's data (#4769). Whether the kernel contract itself should be
+tightened further is #4776.
+
+**The three cures, in preference order:**
+
+1. **Resolve where it is used, not where you start.** A lazy accessor or a
+   `kernel:ready` hook sees a provider that registered later —
+   `createLazyCacheRateLimitStorage()` in plugin-auth is the reference.
+2. **Declare the ordering (ADR-0116).** `dependencies` / `optionalDependencies`
+   / `requiresServices` make the kernel hoist the provider ahead or assert it
+   registered, which makes "absent" a *fact*. Tolerance belongs in the plugin's
+   own declaration, where the kernel enforces it — not in a checker's ledger.
+3. **Seal the vocabulary, then judge.** For a registry that is open by contract
+   (ADR-0018 flow node types), the host declares the moment it can no longer
+   grow — `AutomationEngine.sealNodeTypeVocabulary()`, called at
+   `kernel:bootstrapped` — and only then is an absence worth reporting.
+
+**It has teeth**: `pnpm check:startup-registry-verdict` walks the AST for that
+three-part shape and fails on it; accepted exceptions live in the shrink-only,
+hand-edited `scripts/startup-registry-verdict.baseline.json`. Like
+`check:durability-log-level` it is deliberately narrow — it cannot *discover* a
+new seam, only stop known ones from regressing, and it under-matches on purpose
+rather than risk a false positive: `getService('cache')` is visible, a
+`resolveCacheOrFallback()` three layers down another package is not, and #4769's
+"registry" is a database table it can never see. Found a new open registry? Add
+it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fixes it.
+
+---
+
 ## Post-Task Checklist
 
 1. `pnpm test` — verify nothing broke. Touched a type-check-covered package? `pnpm typecheck` too.

content/docs/plugins/development.mdx

@@ -384,7 +384,6 @@ export const manifest = defineStudioPlugin({
   name: 'Flow Designer',
   version: '2.0.0',
   description: 'Visual flow builder for automation workflows',
-  activationEvents: [{ type: 'onMetadataType', pattern: 'flow' }],
 
   contributes: {
     metadataViewers: [{
@@ -434,16 +433,13 @@ export const manifest = defineStudioPlugin({
 });
 ```
 
-### Activation Events
+### Activation
 
-Control when your plugin loads with activation events:
-
-| Pattern | Trigger |
-|:---|:---|
-| `*` | Activate immediately (eager, default) |
-| `onMetadataType:object` | When metadata type "object" is loaded |
-| `onCommand:myPlugin.doSomething` | When command is invoked |
-| `onView:myPlugin.myPanel` | When panel is opened |
+Every Studio plugin loads and activates immediately on registration — `activate()`
+runs at registration time, unconditionally. The former `activationEvents` manifest
+key was removed in v17 (#4657, ADR-0049): it declared lazy activation that no
+Studio host ever implemented, so a manifest that still carries it now fails the
+parse with the upgrade prescription. Delete the key.
 
 ### View Modes