Merge remote-tracking branch 'origin/main' into claude/auth-gate-disconnect-issues-6wz8ew

# Conflicts:
#	docs/protocol-upgrade-guide.md
#	packages/spec/src/migrations/registry.ts

Author: claude

.changeset/action-body-type-gate.md

@@ -0,0 +1,80 @@
+---
+"@objectstack/runtime": minor
+"@objectstack/lint": minor
+"@objectstack/spec": patch
+---
+
+fix(runtime,lint): `action.body` binds a handler only for `type: 'script'` (#4352)
+
+`ActionSchema.body` has always described itself as "Only used when type is
+`script`", and its JSDoc went further — "Only meaningful when
+`type === 'script'`. When set, the runtime invokes the body inside the sandbox
+… and ignores `target`." The runtime read none of it:
+`actionBodyRunnerFactory` bound a handler the moment `body` parsed, and
+`collectBundleActions` collected any named action. A `type: 'url'` action
+carrying a leftover `body` was therefore registered in the action registry and
+executed in the sandbox — reachable through
+`POST /api/v1/actions/:object/:action` and through
+`ql.object(o).execute(name)`, and counted by the governance inventory as a live
+handler.
+
+Declared ≠ enforced, in the shape that is hardest to debug: an author flips
+`type` from `script` to `url`, reasonably concludes the body is now dead code,
+and it keeps running with nothing anywhere saying so.
+
+**Behaviour change.** `body` now runs only under `type: 'script'`:
+
+| Action | Before | After |
+|:--|:--|:--|
+| `type: 'script'` + `body` | body runs | unchanged — body runs |
+| `type` omitted + `body` | body runs | unchanged — body runs (`ActionType.default('script')`) |
+| `type: 'url' \| 'modal' \| 'flow' \| 'api' \| 'form'` + `body` | body ran | **no handler is bound**; the refusal is logged |
+
+Only an action that **explicitly** declares a non-`script` type *and* carries a
+`body` changes behaviour. An omitted `type` still means `script`, because the
+collectors walk raw bundle objects — a `strict: false` `defineStack` or a legacy
+`manifest.actions[]` never passes through `ActionSchema`, so the schema's own
+default has to be applied at the gate rather than assumed to have been applied
+already.
+
+**FROM → TO.** If you have an action whose body you want to keep running, set
+`type: 'script'` and move the navigation/dispatch target elsewhere; if you want
+the target behaviour, delete the now-inert `body`:
+
+```diff
+  {
+    name: 'open_portal',
+-   type: 'url',
++   type: 'script',
+    target: '/portal',
+    body: { language: 'js', source: "await ctx.api.object('lead').update(…)", capabilities: ['api.write'] },
+  }
+```
+
+The refusal is **not** silent — silence would only relocate the invisibility the
+issue is about. `actionBodyRunnerFactory` logs a warning naming the action, its
+declared `type`, and both fixes.
+
+Authoring-time rejection of the same contradiction already shipped in #4438
+(`ActionSchema` rejects `body` alongside a non-`script` `type`), so what remains
+reachable here is data at rest published before that gate existed, plus bundles
+that never parsed. This release closes that half. New tests also pin that the
+**publish gate resolves to the rejecting schema** — through
+`getMetadataTypeSchema('action')` and `ObjectSchema.actions` — so a re-point of
+either registration cannot silently reopen the hole while the schema's own unit
+tests stay green.
+
+`@objectstack/lint`'s `validate-action-body-writes` filters by `type` again.
+#4344 deliberately made that rule type-blind on the grounds that "the runtime
+binds a handler from `action.body` alone … checking what executes beats checking
+what the schema says should" — true then, and the comment predicted its own
+revision. Execution and declaration are the same set again, so a non-`script`
+body no longer produces write-set advice about writes that provably never
+happen; the publish gate names that metadata's real defect (`type`) with its own
+prescription.
+
+`collectBundleActions` stays deliberately type-blind: it feeds governance
+surfaces that must enumerate every declared action, bound or not, and the other
+bind path (`engine.setDefaultActionRunner`, for Studio-authored actions) never
+walks it. The gate lives at the single point where a `body` becomes an
+executable handler, so there is no second copy of the rule to drift.

.changeset/actor-attribution-seam.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": minor
+"@objectstack/plugin-auth": minor
+"@objectstack/plugin-audit": minor
+"@objectstack/plugin-security": minor
+---
+
+feat(auth,objectql,audit,security,spec): identity-table writes carry the real actor, so `sys_member` history stops saying "system" (#4586)
+
+better-auth owns every write to the identity tables (`sys_member`, `sys_user`,
+`sys_invitation`, …) and its ObjectQL adapter runs them `isSystem: true` **on
+purpose** — the route already authorized the action under better-auth's own ACL,
+and ADR-0092 D2 refuses user-context writes to those tables outright. The
+consequence was that the human who clicked *make admin* was known exactly once,
+in the hook layer where the session exists, and then discarded: every
+`trackHistory` transition on `sys_member` recorded `user_id: null` / "system",
+and `sys_user_permission_set.granted_by` was written null by the auto-grant.
+"Who made this person an org admin?" had no answer in the platform's own audit
+log.
+
+**What changed**
+
+A request-scoped attribution seam, general rather than a `sys_member` special
+case:
+
+| Layer | Before | After |
+|:--|:--|:--|
+| `ExecutionContext` | `userId` / `actor` only | new optional `attributedUserId` — the human CREDITED for a write the system AUTHORIZED |
+| `HookContext` | `session`, `user` | new `provenance.attributedUserId`, split off the context beside `session` |
+| better-auth ObjectQL adapter | `{ isSystem: true }` | `{ isSystem: true, attributedUserId }` when a request scope is open |
+| audit writer | `user_id = session.userId ?? null` | falls back to `provenance.attributedUserId` when the session names nobody |
+| `auto-org-admin-grant` | `granted_by: null`, no `reason` | the attributed human in `granted_by`, plus a machine-provenance `reason` naming the writer and the triggering `sys_member` row |
+
+Outside a request scope nothing changes: writes stay bare `{ isSystem: true }`
+and audit rows keep recording `null`. Absence is still never upgraded into a
+caller, and never written as a sentinel string (ADR-0118 D1/D2).
+
+**Hard constraint — attribution is not authority**
+
+`attributedUserId` is read by exactly one consumer, the audit writer, and by no
+security middleware. It never becomes `ExecutionContext.userId`, so it is never
+the subject the engine authorizes as: not RLS `current_user`, not the ownership
+stamp, not permission resolution. A context carrying only `attributedUserId`
+authorizes exactly like an empty context (ANONYMOUS), and a context carrying it
+beside `isSystem: true` authorizes exactly like `isSystem` alone. Re-authorizing
+identity writes as the human would re-adjudicate a decision better-auth already
+made — the second adjudication track ADR-0095 D3 closed. The constraint is
+pinned by tests at three layers: the engine seam
+(`packages/objectql/src/engine.test.ts`), the better-auth adapter
+(`packages/plugins/plugin-auth/src/auth-actor-attribution.test.ts`), and the
+live HTTP route (a plain member still cannot promote themselves).
+
+**For authors and plugin developers**
+
+`attributedUserId` is authorable on `ExecutionContext` and readable as
+`ctx.provenance?.attributedUserId` in hooks. Use it to answer *who is
+responsible*; keep using `ctx.session` / `ctx.user` to decide *what is
+permitted*. The two are separate fields precisely so the distinction cannot be
+blurred by accident.

.changeset/data-driver-find-stream-retired.md

@@ -0,0 +1,100 @@
+---
+"@objectstack/spec": major
+"@objectstack/driver-sql": major
+"@objectstack/driver-memory": major
+"@objectstack/driver-mongodb": major
+---
+
+refactor(spec,drivers)!: retire `IDataDriver.findStream` — a required method with no caller, whose two main implementations did the opposite of what it promised (#4484, ADR-0049 enforce-or-remove)
+
+`findStream` was a **required** method on the driver contract — every driver and
+every test double had to implement it — documented as the read
+
+> Optimized for large datasets to avoid memory overflow.
+
+Three things were true about it at once, and each is worse in the light of the
+others.
+
+**Nothing called it.** Not the query engine (there is no `stream` entry on it),
+not REST export, not import, not any bulk-read path. Repo-wide, outside the
+contract declaration and the three driver implementations, every single hit was
+a test double — and roughly twenty of those satisfied the required method like
+this:
+
+```ts
+findStream() { throw new Error('not implemented'); }
+```
+
+Twenty stubs that throw, across four packages, for years, and no test ever went
+red. That is not an anecdote about test hygiene; it is the proof of absence. A
+method whose every double throws is a method nothing reaches.
+
+**Two of the three implementations inverted its one guarantee.** `SqlDriver` and
+`InMemoryDriver` both did this:
+
+```ts
+const results = await this.find(object, query, options);  // ← the entire result set
+for (const row of results) yield row;
+```
+
+The whole table is resident in memory before the first `yield`. A caller who
+believed the doc comment and reached for `findStream` precisely because a result
+set was too large would have hit the overflow it existed to prevent, at exactly
+the scale where it mattered. `SqlDriver` carried a `TODO: Use Knex .stream()`
+admitting it.
+
+**The one real implementation dropped a parameter.** `MongoDBDriver._findStream`
+did walk a cursor — but it was the only read in that driver never routed through
+`buildFindOptions`, so it hardcoded `projection: { _id: 0 }` and silently
+discarded `query.fields`. (#4459 unified `find`/`findOne` onto `buildFindOptions`
+and recorded in its TSDoc that `_findStream` was left out. This removal subsumes
+that divergence rather than fixing it — there is nothing left to fix it for.)
+
+Rather than manufacture a caller to justify three implementations, the method is
+retired. If a cursor-based read is wanted, it should arrive **with** the caller
+that needs it, so the contract can be shaped by a real requirement instead of
+being reverse-engineered from a doc comment nobody could test.
+
+**Migration.**
+
+| Wrote | Write instead |
+| --- | --- |
+| `for await (const row of driver.findStream(obj, q)) { … }` | page `driver.find(obj, { ...q, limit, offset })` in a loop |
+| `findStream(…) { … }` on your own driver | delete the method (see below) |
+| `findStream() { throw new Error('ni'); }` in a test double | delete the line |
+
+Paging `find()` is not a downgrade from what `findStream` actually did: on SQL
+and memory it is strictly better (bounded pages instead of one full
+materialisation), and the paged read is the one with an **enforced** guarantee —
+`IDataDriver.find` requires a total order across the whole walk, checked by the
+shared `PAGINATION_CASES` / `PAGINATION_UNORDERED_CASES` fixtures in
+`data/pagination-conformance.ts`. `findStream` never had a conformance case at
+all.
+
+**Driver authors: nothing breaks on you.** An implementation left in place still
+compiles — an extra method is not an error on a class or a widened object — it is
+simply never reached, so deleting it is cleanup you can do whenever. The break is
+on the **caller** side: `driver.findStream(...)` no longer type-checks, and there
+were no callers.
+
+**No tombstone, deliberately.** The other v17 retirements tombstone their key so
+authoring it fails loudly with a prescription. That would be noise here.
+`DriverInterfaceSchema` describes a contract that code *implements*; nothing in
+either repository ever ran a driver object through `.parse()`, so a
+`retiredKey()` there would carry its prescription to no one. The channel that can
+carry it is `tsc`, and `tsc` reports it where it is actionable — at a call site.
+The key is removed from the schema and from `IDataDriver`, and the retirement is
+registered as the `data-driver-find-stream-retired` semantic entry in the
+protocol-17 chain step (ADR-0087 D3), so `spec-changes.json`, the generated
+upgrade guide and the `spec_changes` MCP tool all carry it. There is no
+`os migrate meta` step: a driver is code, never stack metadata, so the chain has
+no source to rewrite.
+
+**Left standing on purpose:** `DriverCapabilities.streaming`, the capability flag
+whose only referent was this method. It has no readers either (and the values
+written into it were already wrong — `SqlDriver` declared `streaming: false`
+while implementing `findStream`, `InMemoryDriver` declared `true` for the
+copy-everything version), but removing a key from the capabilities literal breaks
+every driver that writes it, third-party included, and the same audit should
+cover the other ~30 flags in one pass rather than one at a time. Tracked as
+#4634.

.changeset/data-event-contract.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/client": patch
+"@objectstack/plugin-webhooks": patch
+"@objectstack/service-knowledge": patch
+---
+
+fix(objectql,client): `subscribeData` callbacks receive real `DataEvent`s — the producer now fulfils the declared contract (#4626)
+
+`@objectstack/spec/api`'s `DataEvent` declares top-level `id` (uuid,
+required), `type`, `object`, `recordId` (required), `changes?`, `before?`,
+`after?`, `userId?`, `timestamp`. But the producer (the ObjectQL engine)
+published a raw `RealtimeEventPayload` envelope with `{ recordId, after,
+changes }` nested under `payload` and never generated `id`/`userId`, while the
+client SDK force-cast that envelope into the callback (`callback(event as any
+as DataEvent)`). Subscribers who wrote `event.recordId` / `event.changes` —
+exactly what the types promised — compiled green and read `undefined` at
+runtime. The data-side twin of #4602.
+
+Producer now fulfils the contract:
+
+- `ObjectQL.insert()` / `update()` / `delete()` build a true `DataEvent`
+  (generated uuid `id`, flattened top-level fields, `userId` from the
+  execution context when the write names an actor) and validate it with
+  `DataEventSchema.parse` before publishing. The transport envelope is
+  unchanged (`RealtimeEventPayload`, with `payload` carrying the complete
+  `DataEvent`), so subscribers keep receiving `{ type, object, payload,
+  timestamp }` on the wire.
+- A batch insert publishes one event **per record** (as before), each with its
+  own event id.
+- **A multi-row write (`multi: true` → `updateMany` / `deleteMany`) now
+  publishes nothing.** Those driver methods return only an affected count, so
+  there is no record for a required `recordId` to name; the engine logs a
+  warning naming the gap instead of publishing the previous fabrication
+  (`recordId: ''`, `after: <affected count>`), which every schema-compliant
+  consumer had to reject. **Consequence: webhooks and knowledge sync no longer
+  fire for bulk writes** — they previously fired once with an unusable body. A
+  real bulk event contract is tracked in #4639.
+
+Consumers validate or read the fulfilled shape instead of guessing:
+
+- `@objectstack/client`'s `subscribeData` (and therefore
+  `@objectstack/client-react`'s `useDataSubscription` /
+  `useDataSubscriptionCallback` / `useAutoRefresh`, which delegate to it)
+  unwraps the envelope and runs `DataEventSchema.safeParse` at the boundary.
+  An off-contract payload is rejected loudly (handler error, callback never
+  invoked) — never coerced or passed through. The `as any as DataEvent`
+  double-cast is gone, and the `recordId` option now filters on the fulfilled
+  event.
+- `@objectstack/plugin-webhooks`' auto-enqueuer reads the required
+  `recordId` directly; its `recordId ?? id ?? after?.id ?? before?.id ??
+  'unknown'` fallback chain is gone, and an off-contract event is dropped with
+  a warning rather than delivered under the literal id `'unknown'`. Delivered
+  webhook bodies now also carry the event's `id`/`type`/`userId`; the record
+  itself stays nested under `after` and the envelope keys (`object`,
+  `recordId`, `action`, `timestamp`) still win.
+- `@objectstack/service-knowledge`'s event sync reads the record from `after`
+  (create/update) and the id from `recordId` (delete) for `data.record.*`.
+  It previously indexed the envelope itself as if it were the row, and never
+  resolved an id for deletes.

.changeset/driver-conformance-zero-discovery.md

@@ -0,0 +1,33 @@
+---
+---
+
+test(drivers): a conformance run that discovers zero drivers is a failure, not an OK (#4646)
+
+`scripts/check-driver-conformance.mjs` discovers driver packages from disk under a
+hardcoded `DRIVERS_DIR`. `listDir` swallows ENOENT and returns `[]`, and all three
+invariants iterate the discovered set — CONSUMED over `drivers`, RECONCILED over
+`LEDGER` (empty since #4405, the intended steady state), CLASSIFIED not over drivers
+at all. So a stale `DRIVERS_DIR` produced `OK — 0 covered cell(s)` and exit 0.
+
+CI never had this exposure: `lint.yml` runs `pnpm check:driver-conformance`, which is
+`--self-test && audit`, and the self-test carried a driver-discovery assertion. The
+false green was on the bare `node scripts/check-driver-conformance.mjs` the script's
+own header documents as a usage.
+
+Two things were wrong with leaving the guard there. It read
+`drivers.length >= 3 && drivers.includes('driver-sql')` — a hardcoded name and count
+inside the one script whose stated rule is that drivers come from disk and are never
+listed, so both needed hand-editing on the next driver added or package moved, which
+is precisely when the guard earns its keep. And its failure text ("discovers driver
+packages from disk") named neither `DRIVERS_DIR` nor the stale path, leaving whoever
+tripped it to find that themselves.
+
+DISCOVERED is now a fourth invariant in `audit()`, and the message names the directory
+it searched. The self-test drives the invariant in both directions instead of standing
+in for it, and asserts nothing about which drivers exist.
+
+The case-set axis cannot rot this way and is left alone: `CASE_SETS` is a declared
+expectation, so a vanished `spec/src/data` fails CLASSIFIED's reverse direction with
+one error per case-set. The driver axis is disk-discovery with nothing declared to
+reconcile against — that asymmetry is why zero was reachable on one axis and not the
+other, and it is what DISCOVERED supplies.