Merge remote-tracking branch 'origin/main' into claude/issue-21880-search-companion-scope

Author: claude

content/docs/data-modeling/drivers.mdx

@@ -154,7 +154,10 @@ Two things live **outside** `config`, because they are not driver-specific:
 
 A plugin-contributed driver (`com.vendor.snowflake`) has no contract in this
 repo, so its `config` is left unvalidated rather than judged against a shape the
-platform does not have.
+platform does not have. The platform also does not guess which of its keys hold
+credentials: `config` is stored and served to administrators as written. Keeping
+secrets out of it is the plugin author's responsibility; put the credential in
+the bound secret (`external.credentialsRef`) instead.
 
 <Callout type="info">
 The same schemas are projected to JSON Schema for

content/docs/permissions/sso.mdx

@@ -379,11 +379,16 @@ The Console `/login` and `/register` pages will now show a button for each enabl
 4. Provider redirects to `/api/v1/auth/callback/google`.
 5. better-auth creates a session and redirects to `callbackURL`.
 
-**OIDC/enterprise providers**:
+**OIDC/enterprise providers** (`oidcProviders`): better-auth's generic-OAuth plugin
+registers each one as a social provider and adds no endpoints of its own, so the flow uses
+the same two routes as above.
 1. User clicks **Continue with Okta SSO**.
-2. Client calls `POST /api/v1/auth/sign-in/oauth2` with `{ providerId: "okta", callbackURL }`.
+2. Client calls `POST /api/v1/auth/sign-in/social` with `{ provider: "okta", callbackURL }`,
+   where `provider` is the entry's `providerId`.
 3. Browser redirects to the provider's authorization endpoint.
-4. Provider redirects back; better-auth validates the OIDC token and creates a session.
+4. Provider redirects to `/api/v1/auth/callback/okta`. better-auth exchanges the code, reads
+   the user's profile from the ID token or `userInfoUrl`, creates a session and redirects to
+   `callbackURL`.
 
 ## Linking to an existing account
 

packages/qa/dogfood/test/per-file-cwd.global-setup.ts

@@ -10,22 +10,34 @@
 //      left by a developer's earlier run on a tree without this isolation, or by
 //      a crashed run. The guard judges only what THIS run leaves, so an old
 //      leftover never reds a run that wrote nothing.
-//   2. It creates ONE temporary root for the run and hands it to every worker
-//      through `provide` / `inject`. Each test file makes its own working
-//      directory under that root.
+//   2. It reserves a TAG for the run, `os-dogfood-run-XXXXXX`, as a directory
+//      `mkdtempSync` creates under the system temp directory, and hands the tag
+//      (a name, never a path) to every worker through `provide` / `inject`.
+//      Each test file makes its own working directory directly under the system
+//      temp directory, named `<tag>-file-XXXXXX`.
 //
-// At the END of the run it removes that root, and with it every per-file
-// directory. The removal is run-level, not per-file: on the `shared-showcase`
-// project (`isolate: false`) one memoized boot serves every file on a worker,
-// and its SQLite handles stay open in the directory of the file that booted it.
+// At the END of the run it removes every directory whose name starts with this
+// run's `<tag>-file-`, then the reservation itself. Another run's directories
+// carry another tag, so a concurrent run on the same machine is never touched.
+// The removal is run-level, not per-file: on the `shared-showcase` project
+// (`isolate: false`) one memoized boot serves every file on a worker, and its
+// SQLite handles stay open in the directory of the file that booted it.
+//
+// Why a tag and not a shared parent path (#21924): every `mkdtempSync` base in
+// this tree must be one the tree's scratch-directory scan can read, so that an
+// in-tree fixture root can never hide behind an expression
+// (`scripts/pm/dispatch-gates.mjs`, "no mkdtempSync site in this tree takes a
+// base the scan cannot read"). A path handed over through `inject()` is such an
+// expression. `join(tmpdir(), ...)` is not: it is outside the tree by
+// construction, whatever name follows it.
 //
 // ⛔ This teardown never JUDGES anything. On vitest 4.1.11 an error thrown from
 // a globalSetup teardown is printed as `error during close` and the run still
 // exits 0 (measured), so a guard placed here would be a false green. The guard
 // is a throwing `afterAll` in the per-file module, which fails a test file.
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { TestProject } from 'vitest/node';
 
@@ -34,19 +46,29 @@ const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
 
 declare module 'vitest' {
   export interface ProvidedContext {
-    /** The run's temporary root; each test file makes its working directory under it. */
-    dogfoodCwdRoot: string;
+    /** The run's tag; each test file makes its working directory as `join(tmpdir(), '<tag>-file-')`. */
+    dogfoodRunTag: string;
   }
 }
 
-let runRoot: string | undefined;
+/** The prefix of every per-file directory a run tagged `tag` creates under the system temp directory. */
+export function perFileDirPrefix(tag: string): string {
+  return `${tag}-file-`;
+}
+
+let reservation: string | undefined;
 
 export function setup(project: TestProject): void {
   rmSync(join(PACKAGE_ROOT, '.objectstack'), { recursive: true, force: true });
-  runRoot = mkdtempSync(join(tmpdir(), 'os-dogfood-run-'));
-  project.provide('dogfoodCwdRoot', runRoot);
+  reservation = mkdtempSync(join(tmpdir(), 'os-dogfood-run-'));
+  project.provide('dogfoodRunTag', basename(reservation));
 }
 
 export function teardown(): void {
-  if (runRoot) rmSync(runRoot, { recursive: true, force: true });
+  if (!reservation) return;
+  const prefix = perFileDirPrefix(basename(reservation));
+  for (const name of readdirSync(tmpdir())) {
+    if (name.startsWith(prefix)) rmSync(join(tmpdir(), name), { recursive: true, force: true });
+  }
+  rmSync(reservation, { recursive: true, force: true });
 }

packages/qa/dogfood/test/per-file-cwd.setup.ts

@@ -19,10 +19,18 @@
 // ## What it does
 //
 // At module top level, which runs before the test file's own imports, it makes
-// a directory under the run's temporary root and `chdir`s into it. `afterAll`
-// restores the previous working directory. The directories are removed at the
-// end of the run by the globalSetup, not here: the memoized `shared-showcase`
-// boot keeps its SQLite handles open in the first file's directory.
+// a directory directly under the system temp directory, named with the run's
+// tag (`<tag>-file-XXXXXX`), and `chdir`s into it. `afterAll` restores the
+// previous working directory. The directories are removed at the end of the
+// run by the globalSetup, which sweeps its own tag, not here: the memoized
+// `shared-showcase` boot keeps its SQLite handles open in the first file's
+// directory.
+//
+// The base is spelled `join(tmpdir(), ...)` on purpose (#21924): the tree's
+// scratch-directory scan must be able to read every `mkdtempSync` base, and a
+// path received through `inject()` is one it cannot read. Only the run's TAG
+// comes through `inject()`, as a name component, and it is refused below if
+// it could carry a separator.
 //
 // The invariant for every dogfood author: a file runs in its own temporary
 // cwd, so anything cwd-relative it writes is its own and disappears with the
@@ -38,26 +46,31 @@
 // what this run leaves.
 import { afterAll, inject } from 'vitest';
 import { existsSync, mkdtempSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { perFileDirPrefix } from './per-file-cwd.global-setup.js';
 
 /** `packages/qa/dogfood`, resolved from this module's own location. */
 const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url));
 /** What a file must never leave in the package directory. */
 const LEFTOVER = join(PACKAGE_ROOT, '.objectstack', 'data');
 
-const runRoot = inject('dogfoodCwdRoot');
-if (!runRoot) {
+const runTag = inject('dogfoodRunTag');
+if (!runTag) {
   throw new Error(
-    'per-file-cwd.setup.ts: no run root was provided. The globalSetup ' +
+    'per-file-cwd.setup.ts: no run tag was provided. The globalSetup ' +
       '`test/per-file-cwd.global-setup.ts` must be wired in packages/qa/dogfood/vitest.config.ts; ' +
       'without it this file would run in the package directory.',
   );
 }
+if (/[\\/]|\.\./.test(runTag)) {
+  throw new Error(`per-file-cwd.setup.ts: the run tag ${JSON.stringify(runTag)} is not a plain directory name.`);
+}
 
 const previousCwd = process.cwd();
 const presentAtStart = existsSync(LEFTOVER);
-process.chdir(mkdtempSync(join(runRoot, 'file-')));
+process.chdir(mkdtempSync(join(tmpdir(), perFileDirPrefix(runTag))));
 
 afterAll(() => {
   process.chdir(previousCwd);

packages/qa/dogfood/vitest.config.ts

@@ -143,7 +143,7 @@ runProjectCliOverridePreflight({
 //     `.objectstack/data` exists in the package directory: that throw is the guard.
 //   - The `globalSetup` below is ROOT-level: one run, one call, covering both
 //     projects and each `OS_TEST_SHARD` slice (measured). It clears a stale
-//     `.objectstack` at the start and removes the run's temporary root at the end.
+//     `.objectstack` at the start and removes the run's per-file directories at the end.
 //     Its teardown judges nothing, because a throw there exits 0 on vitest 4.1.11.
 // Both modules' headers carry the rest, including what a dogfood author owes.
 const PER_FILE_CWD = './test/per-file-cwd.setup.ts';

packages/rest/src/meta-state-route-engine-outage.test.ts

@@ -101,6 +101,39 @@
  * same 501 instead of escaping to the route's own `500 EMAIL_SEND_FAILED`.
  */
 
+// [#21920] Pay the state route's `@objectstack/objectql` load at MODULE LOAD,
+// never inside a clocked window.
+//
+// The route reaches `legalNextStates` through a dynamic
+// `await import('@objectstack/objectql')` in `rest-server.ts`, kept dynamic on
+// purpose (a devDependency there: a host without the data engine degrades to
+// 501 rather than failing to load). This package's tests resolve that specifier
+// through `dist/`, so the first request to reach that line pays the vite
+// transform and evaluation of objectql's whole module graph, inside whichever
+// `it()` first gets PAST the gate with a schema: §0's multi-kernel case. Measured
+// on a 4-vCPU container, this file run alone, before this import existed:
+//
+//   * idle: that case cost 3574-3661 ms of the 5000 ms `testTimeout`. Phase-timed,
+//     the handler call is all of it (2.7-2.8 s in a stripped probe); wiring and
+//     boot are under 1 ms each, and the cold KERNEL branch answering a 404 before
+//     the load costs 1.5 ms. So it is the load, not a multi-kernel first-request
+//     cost: under plain Node the same cold import is ~0.6 s on top of the core
+//     and spec this server already loads, and a host whose engine IS objectql
+//     has it loaded before any request.
+//   * confined to one core beside two busy loops: `Test timed out in 5000ms` on
+//     3 of 3 runs, and the load, still in flight, then landed on §3's served
+//     CONTROL (3714-4330 ms), the next case to reach the same line.
+//
+// A module-top import is paid during COLLECTION, which vitest clocks against
+// nothing (AGENTS.md § Build & Test; `scripts/check-test-source-alias.mjs`
+// carries the runner measurement). ⛔ Not a `beforeAll` with a budget, and not a
+// raised timeout: either only moves the window around the cost, and
+// `dev-plugin-security-enforcement-warning.test.ts` (plugin-dev) records such a
+// hook budget being exhausted on a heavier shard. The dynamic call in
+// `rest-server.ts` stays where it is; this only decides where the first load is
+// paid. §0's multi-kernel case pins it with a budget on its own work.
+import '@objectstack/objectql';
+
 import { describe, it, expect, vi } from 'vitest';
 import {
     AUTHZ_STORE_UNAVAILABLE_CODE,
@@ -299,9 +332,25 @@ describe('[#15405] §0 reachability of this consumer, measured', () => {
         // and the route's own engine line is what decides. This is the
         // precondition every case in §1–§4 depends on; without it they would
         // all be measuring the gate.
+        const started = performance.now();
         const seen = await driveStateOnKernelHost(providerHealthy);
+        const ownWorkMs = performance.now() - started;
         expect(seen.outcome).toBe('answered');
         expect(seen.status).toBe(200);
+        // [#21920] PIN — this is the file's FIRST case to reach the route's
+        // `import('@objectstack/objectql')`, so it is the one that pays that load
+        // if it ever lands in a clocked window again (file head). Its own work,
+        // measured on a 4-vCPU container: 3 ms idle, 12-16 ms with this file
+        // confined to a third of one core, 3-23 ms confined to a fifth. The load
+        // it must not carry: 3574-3661 ms with the file run alone, 893 and
+        // 1723 ms in two whole-package runs (an earlier file had already cached
+        // the transform). 500 ms sits about 20x above the first and below every
+        // reading of the second, so the regression reads red on an IDLE box,
+        // well before a loaded shard turns it into the 5000 ms timeout.
+        expect(
+            ownWorkMs,
+            "this case paid a module load inside its clocked window: keep the module-top import of '@objectstack/objectql' at the file head",
+        ).toBeLessThan(500);
     });
 });
 

packages/spec/src/ui/dataset-filter-nested-relation-list.test.ts

@@ -113,7 +113,7 @@ const REFUSED: ReadonlyArray<readonly [
 // §1 Both carriers refuse, at the list's own path
 // ---------------------------------------------------------------------------
 
-describe('#20080 §1 — both analytics carriers refuse a list inside a nested relation', () => {
+describe('§1 — both analytics carriers refuse a list inside a nested relation, at save', () => {
   it.each(REFUSED)('DatasetSchema.filter refuses %s', (_label, filter, issuePath) => {
     const issue = issueAt(DatasetSchema.safeParse(withScope(filter)), `filter.${issuePath}`);
     expect(issue.message).toMatch(/requires a single comparable value, but received an array/);
@@ -145,7 +145,7 @@ describe('#20080 §1 — both analytics carriers refuse a list inside a nested r
 // §2 The carrier prints the analytics door's sentence
 // ---------------------------------------------------------------------------
 
-describe('#20080 §2 — the carrier refusal is the analytics door\'s sentence', () => {
+describe('§2 — the carrier refusal is the analytics door\'s sentence', () => {
   it.each(REFUSED)('%s', (_label, filter, issuePath, field, list, eq, holder) => {
     const door = analyticsDoorRefusal(field, eq ? { $eq: list } : list, holder);
     // The door's refusal is the ADR-0112 class-1 envelope the face throws.
@@ -175,7 +175,7 @@ describe('#20080 §2 — the carrier refusal is the analytics door\'s sentence',
 // §3 A list the shared schema already refuses is refused once, not twice
 // ---------------------------------------------------------------------------
 
-describe('#20080 §3 — outside a nested relation the shared schema answers, once', () => {
+describe('§3 — outside a nested relation the shared schema answers, once', () => {
   it.each([
     ['top level, implicit', { region: ['a'] }, 'region', /^The implicit-equality comparand on field "region"/],
     ['top level, $eq', { region: { $eq: ['a'] } }, 'region.$eq', /^Operator "\$eq" on field "region"/],
@@ -192,7 +192,7 @@ describe('#20080 §3 — outside a nested relation the shared schema answers, on
 // §4 CONTROLS — accepted on both carriers, and kept
 // ---------------------------------------------------------------------------
 
-describe('#20080 §4 — what a nested relation may still carry', () => {
+describe('§4 — what a nested relation may still carry', () => {
   const day = new Date('2026-07-01T00:00:00.000Z');
   it.each([
     ['a scalar', { account: { region: 'a' } }],
@@ -217,7 +217,7 @@ describe('#20080 §4 — what a nested relation may still carry', () => {
     expect(measure.data!.filter).toEqual(filter);
   });
 
-  it('[#20116] $ne carrying a list inside a relation is refused on both carriers, in the door\'s $ne sentence', () => {
+  it('$ne carrying a list inside a relation is refused on both carriers, in the door\'s $ne sentence', () => {
     // This row sat in the table above as "not yet at this save door (#20116)".
     // #20116 routes every slot this walk reaches through the query faces'
     // verdict, so the shape the analytics door refuses on chart is refused here.

packages/spec/src/ui/door-reachability.testkit.test.ts

@@ -58,7 +58,7 @@ const defOf = (s: unknown): unknown => (s as { _zod?: { def?: unknown } })?._zod
 // derivation or a coincidence. A zod upgrade that changes `clone()` semantics
 // changes the bridge's meaning, and that must be LOUD rather than silent.
 // ============================================================================
-describe('#5056 premise — which zod builders share the `_zod.def` object', () => {
+describe('the derived-clone bridge premise — which zod builders share the `_zod.def` object', () => {
   it('`.describe()` shares the def of the instance it was called on', () => {
     // THE mechanism behind #5056. `clone(inst)` without an explicit def reuses
     // `inst._zod.def`, so a described clone is def-IDENTICAL to its receiver.
@@ -104,7 +104,7 @@ describe('#5056 premise — which zod builders share the `_zod.def` object', ()
 // ============================================================================
 // 2. The three controls, on the instrument itself.
 // ============================================================================
-describe('#5056 controls — the walker finds doors, and only real ones', () => {
+describe('controls — the walker finds doors, and only real ones', () => {
   it('positive: live authoring roots resolve, and the graph is really walked', () => {
     const { verdict, nodeCount, rootCount } = measureDoors();
     expect(rootCount, 'every metadata type plus ObjectStackSchema').toBeGreaterThan(20);
@@ -153,7 +153,7 @@ describe('#5056 controls — the walker finds doors, and only real ones', () =>
 // ============================================================================
 // 3. The #5056 regression boundary itself.
 // ============================================================================
-describe('#5056 regression — the any-one-shared-property bridge stays dead', () => {
+describe('regression — the any-one-shared-property bridge stays dead; a share of the shape decides', () => {
   it('a 2-of-19 shared-leaf shape shares leaves with the live graph but is NOT derived from it', () => {
     // The reverse verification, standing rather than one-shot.
     //
@@ -213,6 +213,6 @@ describe('#5056 regression — the any-one-shared-property bridge stays dead', (
       label: I18nLabelSchema.describe('Display label'),
     });
     expect(cloneOverlap(allSharedLeaves), '2 shared of 2 keys').toBe(1);
-    expect(verdict(allSharedLeaves), 'the residual false-reachable case — see #5828').toBe('derived-clone');
+    expect(verdict(allSharedLeaves), 'the residual false-reachable case — no threshold excludes it').toBe('derived-clone');
   });
 });

packages/spec/src/ui/expression-scope-app-root.pin.test.ts

@@ -81,7 +81,7 @@ const sentenceContaining = (source: string, anchor: string): string => {
 /** Root tokens that are still true on these surfaces and must stay in place. */
 const SURVIVING_ROOTS = ['features', 'os.user'] as const;
 
-describe('#17203 — no UI prose face advertises `app` as an expression-scope root', () => {
+describe('no UI prose face advertises `app` as an expression-scope root — the renderer no longer mounts it', () => {
   describe('published faces (read by authoring tools and republished into the reference docs)', () => {
     it('`PageComponentSchema.visibleWhen`.describe() does not name `app` among the mounted roots', () => {
       // ⚠️ NOT `.shape` — ADR-0089 D3a made this schema a `.strict().transform(…)`