Merge remote-tracking branch 'origin/main' into claude/fix-conflict-twdtn7

# Conflicts:
#	packages/lint/src/validate-expressions.test.ts

Author: claude

.changeset/collapse-hook-event-taxonomy.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+"@objectstack/objectql": patch
+---
+
+Collapse the hook event taxonomy from 18 declared events to the 8 the engine actually dispatches (#3195). The removed 10 (`beforeFindOne`/`afterFindOne`, `beforeCount`/`afterCount`, `beforeAggregate`/`afterAggregate`, `beforeUpdateMany`/`afterUpdateMany`, `beforeDeleteMany`/`afterDeleteMany`) were declared in `HookEvent` but never fired — the enum mirrored the engine method table instead of domain events, so a hook subscribing to them registered fine and then silently no-op'd.
+
+- `findOne` now fires the same `beforeFind`/`afterFind` hooks as `find` — the read event attaches to record materialization, not the engine method, so one subscription covers every read shape (no separate `beforeFindOne`/`afterFindOne`).
+- Bulk (`multi: true`) updates/deletes already fire the singular `beforeUpdate`/`beforeDelete`/`afterUpdate`/`afterDelete` events with the row-scoping predicate in `ctx.input.ast`; this is now documented, and there is no `*Many` event.
+- Read authorization / row filtering is the RLS/permission-rule layer's job and field masking is field-level metadata — neither is a hook every author must re-attach.
+- `engine.registerHook` now warns when a hook subscribes to an event the engine never dispatches, so enum-vs-dispatch drift can't recur silently.
+
+No shipped hook or authored metadata used any of the removed events; authoring one now fails loudly at parse/validate time instead of registering a dead hook. Skills and docs updated to teach the 8 events and the declarative alternatives.

.changeset/mcp-validate-expression-tool.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/mcp": minor
+---
+
+feat(mcp): `validate_expression` tool — validate a CEL expression against a schema before authoring (#1928)
+
+Adds an agent-callable MCP tool that runs the same build-time expression checks
+as `objectstack build`, so an AI can validate a formula / predicate / flow
+condition **while authoring** instead of shipping one that silently evaluates to
+`null`. Given `{ objectName, expression, site? }` it resolves the object's real
+schema (field names + types, via the principal-bound `describeObject` bridge)
+and returns:
+
+- **errors** — bare field refs (`amount` → `record.amount`), unknown fields
+  (with a did-you-mean), unknown functions;
+- **warnings** — text/boolean fields misused in arithmetic, date-equality
+  pitfalls;
+- **inScope** — the fields, stdlib functions, and namespace roots available, so
+  the model can self-correct;
+- **inferredType** for a `formula` site.
+
+`site` (`formula` | `validation` | `flow_condition` | `template`, default
+`formula`) maps to the validator's role + scope — `flow_condition` binds fields
+bare, the rest bind `record.<field>`. Read-only, gated by the `data:read` OAuth
+scope, and fail-closed on `sys_*` objects like the other schema tools. This is
+the authoring-time surface the guardrail series (#1928) always pointed at;
+`@objectstack/mcp` gains a `@objectstack/formula` dependency (acyclic; formula is
+a leaf).

.changeset/perf-timing-admin-detail.md

@@ -0,0 +1,29 @@
+---
+"@objectstack/observability": minor
+"@objectstack/plugin-hono-server": minor
+"@objectstack/driver-sql": minor
+---
+
+feat(observability): admin-only richer per-request timing detail via `X-OS-Debug-Timing: json` (#2408)
+
+Completes the optional "richer JSON" diagnostic from #2408. In addition to the
+basic `Server-Timing` header, an admin/service caller can now request a
+per-query breakdown — the slowest SQL statements and a query count — by sending
+`X-OS-Debug-Timing: json`. The detail is returned in a separate
+`X-OS-Debug-Timing-Detail` response header (compact JSON) and is **admin-only,
+even under global mode**: an ordinary caller never sees SQL shapes.
+
+- **observability**: `PerfTiming` gains opt-in per-event detail capture
+  (`enableDetail` / `recordDetail` / `details`) plus the ambient
+  `recordServerTimingDetail`. The disclosure gate gains a `privileged` level
+  (set by `allowPerfDisclosure`, read via `isPerfDisclosurePrivileged`) so the
+  richer detail can be gated independently of the basic header.
+- **driver-sql**: when detail capture is on, the query listener additionally
+  records each query's **parametrized** statement (knex's `q.sql`, `?`
+  placeholders) — never the bindings, so no literal row value ever enters the
+  collector. Zero overhead when detail is off.
+- **plugin-hono-server**: `X-OS-Debug-Timing: json` enables detail capture; the
+  middleware emits `X-OS-Debug-Timing-Detail` (slowest queries, capped and
+  sanitized to header-safe ASCII) only when the principal is a proven admin.
+
+Basic and global behavior are unchanged; `json` is purely additive.

.changeset/remove-form-surfaced-dead-props-2377.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec)!: remove form-surfaced dead metadata props + correct 3 misclassified-live entries (#2377, ADR-0049)
+
+The next enforce-or-remove slice of #2377. Versioned `minor` per the launch-window
+policy (the fixed group makes a `major` promote the whole monorepo).
+
+## Removed (dead, no runtime reader — verified in both framework and objectui)
+
+- **field**: `columnName`, `index`, `referenceFilters`. This empties the field
+  dead-prop set. `columnName` also removed its now-moot **ADR-0062 D7** lint
+  (`validate-expressions.ts`), the dead `StorageNameMapping.resolveColumnName` /
+  `buildColumnMap` / `buildReverseColumnMap` helpers, and closes ADR-0062 R10 —
+  external physical-column mapping is `external.columnMap` only.
+- **object**: `tags`, `active`, `abstract` — now rejecting tombstones in
+  `UNKNOWN_KEY_GUIDANCE`.
+- **agent**: `tenantId`.
+
+The removed props are dropped from the authoring forms (`field/object/agent.form.ts`)
+and the regenerated metadata-forms i18n bundles.
+
+## Corrected to `live` (the ledger was wrong — readers existed)
+
+- **object `isSystem`** — `plugin-sharing` `effectiveSharingModel` defaults a
+  no-`sharingModel` `isSystem` object to public; also read by the security-posture
+  lint. KEPT.
+- **object `enable.searchable`** — `metadata-protocol` global search (`searchAll`)
+  uses `enable.searchable === false` as an opt-out. KEPT.
+- **action `type:'form'`** — objectui `ActionRunner.executeForm` routes it to the
+  FormView at `/forms/:target`; a build-time lint validates the target. KEPT.
+
+## Deliberately deferred
+
+`object.enable.trash` / `enable.mru` — dead, but inert `default(true)` flags set by
+~35 `sys-*.object.ts` files; removing them is high-churn / low-value. Left `dead`
+(authorWarn-skipped).
+
+## Migration
+
+- field/agent props: authoring them was already a no-op; they now strip silently.
+  `columnName` → the physical column is always the field key (rename the field, or
+  use `external.columnMap` for external objects); `index` → declare it in object
+  `indexes[]`; `referenceFilters` → `lookupFilters`.
+- object `tags`/`active`/`abstract`: `ObjectSchema.create()` now throws a located
+  error naming the removal. None gated anything at runtime — remove them.

.changeset/retire-feed-discovery-surface.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/spec": minor
+"@objectstack/metadata-protocol": patch
+"@objectstack/client": patch
+---
+
+**Breaking (discovery response shape): retire the residual feed capability surface (#3180, follow-up to #1959 / ADR-0052 §5).**
+
+The feed backend was retired long ago; #1959 removed the feed contracts + SDK. This
+removes the last discovery/dispatcher references to it, and fixes a real bug where the
+`comments` capability was permanently `false`.
+
+- `@objectstack/spec` — `WellKnownCapabilitiesSchema.feed` and `ApiRoutesSchema.feed`
+  (`routes.feed`) are **removed**, and the `/api/v1/feed` entry is dropped from
+  `DEFAULT_DISPATCHER_ROUTES`. FROM → TO: clients reading `discovery.capabilities.feed`
+  or `discovery.routes.feed` → use `discovery.capabilities.comments`; comments/activity
+  are served by the generic data API on `sys_comment` / `sys_activity`
+  (`/api/v1/data/sys_comment/…`).
+- `@objectstack/metadata-protocol` — `getDiscovery()` no longer emits the always-`false`
+  `feed` service/capability. **Bug fix:** the `comments` capability previously keyed off
+  the deleted `'feed'` service (so it was permanently `false` after #1955); it now tracks
+  the presence of the `sys_comment` object (provided by the always-on audit slate), so
+  `declared === enforced`.
+- `@objectstack/client` — the internal `feed: '/api/v1/feed'` route constant is removed
+  (it only existed to satisfy the now-removed `ApiRoutes.feed` type; no client code used it).

CONTRIBUTING.md

@@ -181,7 +181,6 @@ Use `camelCase`:
 ```typescript
 {
   maxLength: 100,
-  referenceFilters: ['active'],
   defaultValue: 'none',
 }
 ```

content/docs/api/data-flow.mdx

@@ -96,7 +96,7 @@ sequenceDiagram
 
     QE-->>K: DataRecord
 
-    K->>H: afterFindOne hooks
+    K->>H: afterFind hooks (fire for findOne too)
     H-->>K: Transformed record
 
     K->>Sec: applyFieldSecurity(record, user)
@@ -310,7 +310,7 @@ flowchart TD
     end
 ```
 
-The lifecycle events are defined by the `HookEvent` enum. Reads also have hooks: `beforeFind/afterFind`, `beforeFindOne/afterFindOne`, `beforeCount/afterCount`, and `beforeAggregate/afterAggregate`. Bulk writes add `beforeUpdateMany/afterUpdateMany` and `beforeDeleteMany/afterDeleteMany`.
+The lifecycle events are defined by the `HookEvent` enum (8 events). Reads fire `beforeFind`/`afterFind` — for **both** `find` and `findOne`, so one subscription covers every read shape. Bulk writes (`multi: true`) fire the **same** `beforeUpdate`/`beforeDelete`/`afterUpdate`/`afterDelete` events as single-id writes, with the row-scoping predicate in `ctx.input.ast`. There are deliberately no per-method (`findOne`/`count`/`aggregate`) or `*Many` events: read authorization and row filtering are RLS/permission-rule concerns, and field masking is field-level metadata.
 
 | Hook | Phase | Can Modify? | Can Abort? |
 |:---|:---|:---|:---|

content/docs/kernel/events.mdx

@@ -58,10 +58,10 @@ The Data Engine runs hooks around record reads and mutations. Write operations f
 | Event | When |
 | :--- | :--- |
 | `beforeInsert` / `afterInsert` | Around record creation. |
-| `beforeUpdate` / `afterUpdate` | Around record update. |
-| `beforeDelete` / `afterDelete` | Around record deletion. |
+| `beforeUpdate` / `afterUpdate` | Around record update — single-id **and** bulk (`multi: true`). |
+| `beforeDelete` / `afterDelete` | Around record deletion — single-id **and** bulk (`multi: true`). |
 
-Read and bulk variants (`beforeFind`/`afterFind`, `beforeCount`, `beforeAggregate`, `beforeUpdateMany`, `beforeDeleteMany`, …) also exist.
+Reads fire `beforeFind` / `afterFind`, for **both** `find` and `findOne` (one read event covers every read shape). There are no per-method (`findOne`/`count`/`aggregate`) or `*Many` events: read authorization and row filtering are handled by RLS/permission rules, field masking by field-level metadata, and bulk writes by the same `before*`/`after*` write events (with the row-scoping predicate in `ctx.input.ast`).
 
 ### The HookContext
 

content/docs/protocol/objectql/schema.mdx

@@ -594,12 +594,15 @@ const customerHook: Hook = {
 export default customerHook;
 ```
 
-**Event Types** (camelCase):
+**Event Types** (camelCase) — 8 events:
 - `beforeInsert` / `afterInsert`
-- `beforeUpdate` / `afterUpdate`
-- `beforeDelete` / `afterDelete`
-- Query-side: `beforeFind` / `afterFind`, `beforeCount` / `afterCount`, and the
-  bulk variants `beforeUpdateMany` / `beforeDeleteMany`, etc.
+- `beforeUpdate` / `afterUpdate` — fire for single-id **and** bulk (`multi: true`) updates
+- `beforeDelete` / `afterDelete` — fire for single-id **and** bulk (`multi: true`) deletes
+- `beforeFind` / `afterFind` — fire for **both** `find` and `findOne`
+
+There are no per-method (`findOne` / `count` / `aggregate`) or `*Many` events: read
+authorization and row filtering are RLS/permission-rule concerns, field masking is
+field-level metadata, and bulk writes reuse the singular write events.
 
 ## Advanced Features
 

content/docs/references/ai/agent.mdx

@@ -83,7 +83,6 @@ const result = AIKnowledge.parse(data);
 | **active** | `boolean` | ✅ |  |
 | **access** | `string[]` | optional | Who can chat with this agent |
 | **permissions** | `string[]` | optional | Required permission-set capabilities |
-| **tenantId** | `string` | optional | Tenant/Organization ID |
 | **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ | [EXPERIMENTAL — NOT ENFORCED, #1901] Intended listing scope. No runtime consumer yet; use access/permissions for real gating. |
 | **planning** | `{ maxIterations: integer }` | optional | Autonomous reasoning and planning configuration |
 | **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | Agent memory management |