Merge remote-tracking branch 'origin/main' into claude/issue-6881-6762-describe-sweep

Author: claude

.changeset/api-derivation-batch-alias-row-retired.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): drop the producer-less `batch` row from `DATA_ACTION_TO_API_OPERATION` (#6259)
+
+`DATA_ACTION_TO_API_OPERATION` normalizes the action vocabularies its callers
+speak onto canonical `ApiOperation` names. One row, `batch: 'bulk'`, had no
+producer on either side, and the table's own TSDoc still taught readers that it
+did — calling `batch` a "runtime `callData` action".
+
+Both consumers were re-enumerated at `origin/main` before the row was removed:
+
+- `packages/runtime/src/api-exposure.ts` (`checkApiExposure`) is reached only
+  from `callData`, which branches on a closed set — `create`/`get`/`update`/
+  `delete`/`query`/`find`/`aggregate` — and every call site passes one of those
+  as a string literal. Its `batch` arm was retired in #5856, so no caller has
+  been able to send the word since.
+- `packages/rest/src/rest-server.ts` (`apiAccessDenialFromEnable`) is fed only
+  canonical literals by `enforceApiAccess`: `import`, `bulk`, `create`,
+  `update`, `list`, `delete`, `get`, `export`. The cross-object `POST /batch`
+  route is the trap worth naming — it spells `batch` in the **URL** and gates on
+  `'bulk'`, so the route is untouched by this change.
+
+FROM → TO: `batch` → `bulk`. If you read this table directly, spell the bulk
+surface `bulk`; `DATA_ACTION_TO_API_OPERATION['batch']` is now `undefined`.
+
+**Nothing on a live path changes**, because nothing sent `batch`. What changes
+is the answer waiting for anyone who does: the lookup misses, the consumers'
+`?? action` pass-through hands `batch` through unmapped, and an unmapped action
+is *ungated* by `apiMethods` (it still respects `apiEnabled`) — the same
+treatment every custom action gets. That last point is why the row was worth
+removing rather than leaving as harmless: while it existed, one unreachable
+word silently bought a real `bulk ∧ child` permission verdict, and a reader —
+or an AI author — would reasonably conclude `batch` was a supported spelling
+and write consumer-side tolerance for it. Prime Directive #12 forbids exactly
+that: an alias with no producer belongs at the producer or nowhere.
+
+The export itself is unchanged — same name, same `Record<string, ApiOperation>`
+type — so `check:api-surface` records no delta (that snapshot prints type
+references, not expanded shapes; #3883 is the precedent for a key-level change
+being invisible to it). No authorable metadata key is involved, so there is no
+tombstone, no conversion and no liveness-ledger row: nothing parses this table.

.changeset/package-routes-repeated-version-query-param.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/rest": minor
+---
+
+fix(rest): a repeated `?version=` on `/packages/:id` is refused, not silently resolved (#6307)
+
+`IHttpRequest.query` is declared `Record<string, string | string[]>` — a repeated
+query parameter arrives as an **array**. Both `/api/v1/packages/:id` handlers read
+it as a string and passed it straight to `PackageService.get/delete`, whose
+parameter is `version?: string`. Measured on `main` before the fix:
+
+```
+GET    /packages/com.acme.crm?version=1.0.0&version=2.0.0
+       → packageService.get('com.acme.crm', ['1.0.0','2.0.0'])
+DELETE /packages/com.acme.crm?version=1.0.0&version=2.0.0
+       → packageService.delete('com.acme.crm', ['1.0.0','2.0.0'])
+       → 200 { message: 'Deleted com.acme.crm@1.0.0,2.0.0' }
+```
+
+The `DELETE` line is the sharp one. `if (!version && protocol.deletePackage)` is
+what gates the **full uninstall** (#2747: the package's metadata rows, the durable
+`sys_packages` record, and the registered data-plane cleanups — plugin-security
+revoking its permission sets and bindings). Any truthy `version` skips it, so a
+repeated parameter silently narrowed the *scope of the operation* on a destructive
+verb and still reported success.
+
+**Both verbs now refuse the ambiguity** with `400 VALIDATION_ERROR`
+(`The "version" query parameter was supplied 2 times. Supply it at most once — this
+endpoint will not choose between conflicting values.`). `?version=a&version=b` is a
+well-formed request carrying two conflicting intents; picking one silently is a
+wrong answer delivered as a `200`. The rule is identical on both verbs — one
+parameter, one answer — and the code comes from ADR-0112's **standard** catalog
+rather than a newly registered synonym, because "this request contradicts itself"
+is a generic validation condition.
+
+The rule is about **multiplicity, not shape**: the parameter may be supplied at
+most once. A one-element array is one occurrence encoded differently by an adapter
+and is accepted; an empty array is no occurrence. Two identical values are still
+two occurrences and are still refused — "at most one *distinct* value" would be a
+de-duplication rule no client can predict, while "supply it at most once" is
+checkable client-side.
+
+**Not tolerance for off-spec input.** The contract already declared the array; the
+consumer simply never handled a shape it was told to expect.
+
+**Nothing that works today changes.** A single `?version=1.0.0`, no `version` at
+all, and an empty `?version=` all behave exactly as before — including the full
+uninstall still being reached when no version is supplied. No in-repo caller,
+documented example or SDK path repeats the parameter (`client.packages.get` builds
+`?version=` from a single `version?: string`), so the new 400 is unreachable from
+any supported client. It is `minor` rather than `patch` only because a request
+shape that used to answer `200` now answers `400`.
+
+Adapter note, measured over a real socket: the `node:http` adapter
+(`NodeHttpServer`) hands `['1.0.0','2.0.0']` to the handler as the contract
+declares, while the Hono adapter collapses a repeat to the first value before any
+handler sees it. Both are contract-legal (the union permits either), which is
+exactly why the consumer must handle the declared shape rather than depend on
+which server booted.

.changeset/sharing-defer-authored-row-write-widener.md

@@ -0,0 +1,57 @@
+---
+"@objectstack/plugin-sharing": patch
+---
+
+fix(sharing): the by-id write gate defers to an app-authored RLS widener instead of hard-refusing (#5493)
+
+HotCRM's 17.0 GA acceptance sweep declared two RLS update-wideners on one
+profile and measured one of them working. On the junction object
+`crm_campaign_member` a non-owner PATCH returned 200; on `crm_campaign` the
+identical shape returned 403 `FORBIDDEN: insufficient privileges to update
+crm_campaign`. That sentence is the sharing middleware's, not the row gate's
+`(row-level security)` — so the refusal landed **before** RLS was consulted and
+the declared widener was never asked.
+
+The discriminator was never "carries sharing rules". It is whether **record
+sharing enforces on the object at all**: `checkEdit` abstains — and `canEdit`
+therefore answers `true`, letting the write through to RLS — when the effective
+sharing model is `public` (which `controlled_by_parent` maps onto) or when the
+schema has no `owner_id` field. A junction lands in that set; an ordinary owned
+business object does not. Same declaration, opposite outcome, split by a
+property no author writes down.
+
+Row-level write authority is ONE composite determination (maintainer ruling on
+#5492), so the middleware no longer ends the decision by itself. Before it
+hard-refuses a **by-id** update or delete, it asks the security service's
+`ISecurityService.checkAuthoredRowWrite` — the fail-closed verdict landed by
+#5493 step 1 (PR #6841) — whether an **app-authored** (non-floor) row-level
+policy admits this row for this operation. `admit` retracts this authority's
+refusal and hands the row to the security pre-image gate, which composes per
+#6684/#5492 and makes the final row decision. It does not authorize anything on
+its own.
+
+Everything else is unchanged, deliberately:
+
+- **The guarded surface does not shrink.** A member with no authored policy, no
+  share and no bypass is still refused; a read-level share still never widens a
+  write; an `edit`-level share still widens update and not delete (ADR-0111 D3),
+  and an update-only authored widener does not open delete either — the verb is
+  threaded through to the verdict, not collapsed.
+- **Fail-closed on every non-`admit` outcome.** No security service (a
+  deployment without `@objectstack/plugin-security`), a service predating the
+  method, a throwing probe, a principal-less context, an on-behalf-of context
+  (ADR-0090 D10) and any unrecognised verdict all leave today's refusal
+  byte-for-byte intact. The probe is reached through the same structural
+  late-binding this plugin already uses for `hasWriteBypass`; no runtime
+  dependency on `plugin-security` is introduced.
+- **A creator who is no longer the owner gets nothing back.** The platform's own
+  ownership floor (`created_by == current_user.id`, shipped on the additive
+  `member_default` baseline) matches a record transferred away from its creator,
+  so a deferral keyed on "the composed RLS admits this row" would return
+  transferred records to former creators. The verdict is provenance-aware and
+  abstains there; the deferral does not widen it.
+- **The bulk path is untouched** — it composes a filter rather than a verdict,
+  and is tracked separately (#6736).
+- **Objects with no owner field are untouched** (#6698): sharing abstains, the
+  gate never refuses, so the deferral is never reached and the platform
+  `created_by` write floor remains their only row-level write gate.

.changeset/tenant-chokepoint-read-doors.md

@@ -0,0 +1,55 @@
+---
+'@objectstack/driver-sql': patch
+'@objectstack/driver-sqlite-wasm': patch
+'@objectstack/driver-turso': patch
+---
+
+drivers: every SQL read door routes through the tenant chokepoint (#6792)
+
+`SqlDriver.applyTenantScope()` owns read-side tenant isolation for the whole SQL family —
+the `tenantId` early-out, the "object has no tenant field" early-out, the NULL-org
+platform-row rule (#2734) and the ADR-0105 D2 union posture (#3623). Its own docstring
+said "every CRUD method routes through it". Nothing ever checked that, and it was false
+for as long as it had existed. **Three** read doors built their query through
+`getBuilder()` and never arrived:
+
+- **`findWithWindowFunctions()`** — the documented #4286 window door. It returns **rows**,
+  so on a deployment where the scope would have applied (`options.tenantId` set, object
+  has a tenant field) it returned rows belonging to **every** tenant. Measured with two
+  tenants seeded plus one NULL-org platform row: `tenantId: 'org_a'` returned
+  `[a1, a2, b1, b2, p1]` here against `find()`'s `[a1, a2, p1]` — another tenant's rows,
+  handed over at the driver layer.
+- **`analyzeQuery()` / `explain()`** — returns a **plan**, not rows, so this is a smaller
+  fix and it is made on its own merits rather than folded into the one above. It is the
+  same defect #6577 fixed on these two methods one builder line lower: a plan is only
+  worth reading if it explains the statement `find()` would actually run, and a missing
+  tenant predicate changes selectivity and therefore which index the planner picks.
+  Compiled `select * from account` where `find()` sent the `organization_id` clause.
+- **`distinct()`** — returns one column's **values** for every tenant. This one was in no
+  card. #6792 states the opposite, listing `distinct` among the scoped call sites; the
+  13th read site is `aggregate()`. It was found by measuring the invariant rather than
+  re-reading it.
+
+All three now call `applyTenantScope()` beside their `getBuilder()` line, the position
+`findRows()` uses. They route through the chokepoint rather than re-deriving a predicate:
+a local equality would silently drop NULL-org platform rows (#2734) and collapse group
+reads to active-org reach (#3623). Both of the chokepoint's early-outs are inherited
+unchanged, so an unscoped admin/seed read (no `tenantId`) and any object without a tenant
+field behave exactly as before.
+
+**The durable half is a gate, not the three lines.** `pnpm check:tenant-chokepoint`
+(`scripts/check-tenant-chokepoint.mjs`, wired into `.github/workflows/lint.yml`) re-derives
+the invariant from the AST across the `SqlDriver` family on every run: a method that builds
+through `getBuilder(object, options)` must call `applyTenantScope()` on that builder, or
+carry a written exemption. Insert builders are exempt structurally — write-side tenancy is
+`injectTenantOnInsert` — rather than by a name list. It is keyed on the **builder** and not
+on the method signature, because the signature criterion the card sketches ("takes
+`(object, …, options)` and returns rows") misses `distinct` (no `query` parameter) and
+`analyzeQuery` (returns a plan). Verified red against the pre-fix tree, red against a
+newly-added unscoped door, and silent once that door is scoped.
+
+The chokepoint docstring no longer asserts the invariant; it names the gate that proves it.
+
+If you call these doors directly on a multi-tenant deployment, pass `options.tenantId` as
+you would to `find()` — that is what now takes effect. Callers that never passed it are
+unaffected; that remains the documented unscoped/admin path.

.github/workflows/lint.yml

@@ -575,6 +575,44 @@ jobs:
       - name: Spec type-alias convention gate (ADR-0122)
         run: pnpm check:spec-parsed-alias
 
+      # Read-side tenant chokepoint gate (#6792, from #3724 / #6577).
+      # `SqlDriver.applyTenantScope()` owns read-side tenant isolation for the
+      # whole SQL family — the tenantId early-out, the no-tenant-field early-out,
+      # the NULL-org platform-row rule (#2734) and the ADR-0105 D2 union posture
+      # (#3623). Its own docstring claimed "every CRUD method routes through it".
+      # Nothing checked that, and it was FALSE for as long as it had existed:
+      # three doors built through `getBuilder()` and never arrived —
+      # `findWithWindowFunctions` (ROWS: a caller passing `tenantId` got every
+      # tenant's rows, measured `[a1,a2,b1,b2,p1]` against `find()`'s
+      # `[a1,a2,p1]`), `analyzeQuery`/`explain` (a PLAN for a statement `find()`
+      # would not run — the same defect #6577 fixed on these methods one builder
+      # line lower), and `distinct` (every tenant's values for one column).
+      #
+      # The third is the argument for gating rather than fixing. It was in NO
+      # card: #6792 asserts the opposite — that `distinct` is among the 13 scoped
+      # sites — and the triage comment and two rounds of measurement all
+      # inherited that sentence without re-deriving it. The 13th read site is
+      # `aggregate()`. Two of the three doors were found by a human reading the
+      # file for another reason; the third was found only by measuring, which is
+      # the thing a prose invariant can never do for itself.
+      #
+      # Keyed on the BUILDER, not the method signature. #6792 sketches "every
+      # method taking `(object, …, options)` and returning rows"; that criterion
+      # is measurably too narrow — `distinct(object, field, filters, options)`
+      # takes no query and `analyzeQuery` returns a plan, so it misses two of the
+      # three. `getBuilder()` is the single constructor of every statement this
+      # driver sends, so every builder is classified and one that cannot be
+      # classified is an error, never a default (#4690's family). Insert builders
+      # are exempt structurally, not by name: write-side tenancy is
+      # `injectTenantOnInsert`.
+      #
+      # Static AST over three files, no build needed, so it belongs in this job.
+      # Runs its own --self-test first, in both directions — the detector can be
+      # broken while every door is fine, and a scan that stops matching would
+      # report OK while reading nothing.
+      - name: Read-side tenant chokepoint gate
+        run: pnpm check:tenant-chokepoint
+
   typecheck:
     name: TypeScript Type Check
     runs-on: ubuntu-latest

content/docs/data-modeling/queries.mdx

@@ -590,6 +590,17 @@ const ranked = await sqlDriver.findWithWindowFunctions('employee', {
 });
 ```
 
+<Callout type="warn">
+**Pass `options.tenantId` on a multi-tenant deployment.** Like `find()`, this door is
+tenant-scoped only when the caller supplies it — the example above omits it, so it reads
+across every tenant. That is the driver layer's documented contract (seed scripts and
+cross-org tooling depend on the unscoped path), but it is a decision to make deliberately.
+
+Until #6792 the door ignored `options.tenantId` even when you *did* pass it and returned
+every tenant's rows regardless. It now routes through the driver's `applyTenantScope`
+chokepoint like every other read.
+</Callout>
+
 For request-level analytics, use `aggregations` + `groupBy`, or model rankings in
 report/dashboard metadata.
 

content/docs/protocol/objectql/query-syntax.mdx

@@ -826,6 +826,12 @@ from presentation; Postgres and MySQL hand back their own native temporal value)
 then re-deduplicates the presented values, because SQL `DISTINCT` compares the *stored*
 form.
 
+It is tenant-scoped on the same terms as `find()` — the `organization_id` predicate is
+applied when the call carries `options.tenantId` (the fourth argument), and the example
+above omits it, so it returns the column's values across every tenant. Until #6792 the
+predicate was dropped even when `tenantId` *was* supplied, which made a scoped call
+disclose every other tenant's values for that column.
+
 ### Full-Text Search
 
 The `search` parameter does **not** reach a full-text index. The engine expands it into
@@ -959,6 +965,13 @@ projection, and niladic rendering means argument-taking functions (`LAG(field)`)
 emit without their argument. For request-level analytics use `aggregations` +
 `groupBy` (§5).
 
+Tenancy works exactly as it does on `find()`: the driver applies its
+`organization_id` predicate only when the call carries `options.tenantId`. The example
+above omits it and therefore reads across every tenant — the intended unscoped/admin
+path, but a deliberate choice rather than a default to inherit. (Until #6792 this door
+dropped `options.tenantId` even when it was supplied, so a scoped call still returned
+every tenant's rows.)
+
 ---
 
 ## 7. Pagination

package.json

@@ -81,6 +81,7 @@
     "check:engine-double-contract": "node scripts/check-engine-double-contract.mjs --self-test && node scripts/check-engine-double-contract.mjs",
     "check:resume-authority-declared": "node scripts/check-resume-authority-declared.mjs --self-test && node scripts/check-resume-authority-declared.mjs",
     "check:spec-parsed-alias": "node scripts/check-spec-parsed-alias.mjs --self-test && node scripts/check-spec-parsed-alias.mjs",
+    "check:tenant-chokepoint": "node scripts/check-tenant-chokepoint.mjs --self-test && node scripts/check-tenant-chokepoint.mjs",
     "check:stall-guard": "node scripts/run-with-stall-guard.mjs --self-test"
   },
   "keywords": [