Merge branch 'main' into claude/issue-10495-objectui-pin-reachability

Author: claude[bot]

.changeset/cli-serve-host-anchored-cluster-import.md

@@ -0,0 +1,16 @@
+---
+"@objectstack/cli": patch
+---
+
+Fix `os serve` failing to boot with `OS_CLUSTER_DRIVER=redis` when the app
+declares `@objectstack/service-cluster` (#10645). The cluster gate and its
+driver were reached through a bare dynamic `import()`, which Node ESM resolves
+against the CLI's own realpath — inside the framework workspace — so packages
+installed under the host app were invisible to it and boot died with
+`Cannot find package '@objectstack/service-cluster'`. Both loads now go through
+the host-anchored importer `serve` already uses for its other optional and
+enterprise packages, so any package the app declares resolves the way the app
+declares it. The host importer is now defined at the top of the boot sequence
+rather than partway down, which is what made these two loads fall back to bare
+resolution in the first place. No change to what `serve` accepts or refuses:
+an undeclared package is still refused by the same declaration gate.

.changeset/datasource-cli-envelope-unwrap.md

@@ -0,0 +1,38 @@
+---
+"@objectstack/cli": patch
+---
+
+**Fix:** `os datasource list-tables`, `os datasource introspect` and
+`os datasource validate` now read the response envelope the server actually
+emits, so all three work against a live server for the first time (#10675).
+
+The three commands read the pre-#3843 **flat** shape — `body.tables`,
+`body.draft`, `body.results`, and `body.error` as a string — while every REST
+body the platform sends is the declared envelope written by `sendOk` /
+`sendError`: `{ success: true, data: { … } }` or
+`{ success: false, error: { code, message } }`. Nothing failed loudly, because
+each payload simply read `undefined` and every command reported that as an
+ordinary empty result:
+
+- `list-tables` printed `No remote tables found.` while the server was
+  returning two tables.
+- `introspect` printed `Failed to generate draft` for drafts the server had
+  generated.
+- `validate` printed `No federated objects to validate.` and exited **0**
+  against drift the server had flagged `missing_column … severity:error` — a
+  schema gate green-lighting a CI-breaking condition it had never read.
+- An unknown datasource crashed with `TypeError: first argument must be a
+  string or instance of Error`, because the error **object** was handed to
+  oclif's `this.error()` instead of `error.message`.
+
+`validate`'s exit code is the behaviour change to note: a datasource whose
+federated objects have drifted now exits **1** where it previously exited 0. If
+you have a pipeline that treats this command as advisory, it starts failing on
+drift that was always there.
+
+A body that is **not** the declared envelope is now a loud failure rather than
+an empty payload. That distinction is the point: "nothing found" is reachable
+only from a server that really said so, never from a response the CLI could not
+read. The legacy flat shape is deliberately *not* also accepted — a
+consumer-side fallback would re-create the divergence as a second de-facto
+contract.

.changeset/doctor-withholds-checks-over-unexamined-tree.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/cli": patch
+---
+
+`os doctor` no longer prints `✓ Test coverage` / `✓ Deprecations` about a tree it
+never examined, and no longer warns `@objectstack/spec  Not built` about a
+workspace that is not part of the tree (#10679).
+
+`findMissingTests()` and `findDeprecatedUsages()` both walk
+`<cwd>/packages/spec/src` — a path that exists in this monorepo and in no
+application built with the framework. Both answered "that directory is not here"
+with the same value they return for "I walked it and found nothing wrong" (an
+empty array), so in a stock `create-objectstack -t blank` scaffold every run
+printed, verbatim:
+
+```
+  ✓ Test coverage         All *.zod.ts files have matching tests
+  ✓ Deprecations          No @deprecated tags found
+```
+
+about files doctor never opened. The command exits 0 either way, so "no problems
+found" and "I never looked" were byte-identical to every downstream reader.
+
+Doctor already refuses to do this one screen down: the ADR-0120 D5e advisory's
+`✓ Unique scope` is withheld unless `ledgerReadingIsComplete()` says the ledger
+half was read in full. These two checks escaped that discipline; this restores
+it, in the same shape #5413 used for the ledger — whether the tree was examined
+is now a fact in the return type rather than an absence, so the print site
+cannot reach the `✓` from the unexamined arm. Where the tree is absent doctor
+prints an informational, named-reason skip instead:
+
+```
+  ℹ Test coverage         Skipped — no packages/spec/src in this directory (monorepo-only check)
+  ℹ Deprecations          Skipped — no packages/spec/src in this directory (monorepo-only check)
+```
+
+`--verbose` adds the resolved directory it looked for. The skip is deliberately
+not a warning: nothing is wrong in an application that has no
+`packages/spec/src`, and withholding a false `✓` must not manufacture a false
+`⚠`.
+
+The adjacent `⚠ @objectstack/spec  Not built` probe read `<cwd>/packages/spec/dist`
+with no check that the workspace it names exists, so in an application it warned
+about an absent package and prescribed `pnpm --filter @objectstack/spec build`, a
+command that cannot succeed there. It is now gated on `packages/spec/package.json`
+being present. Inside the monorepo the row is unchanged; outside it there is no
+row, and an application's spec dependency stays covered by the `Dependencies`
+check and by the spec-version-gap advisory.
+
+Exit codes are untouched — 1 exactly when an error row exists, warnings never
+flip it. One visible consequence: a stock scaffold with no other findings now
+ends on `✅ Environment is healthy and ready for development!` instead of
+`⚠️  Environment is functional but has some warnings`, because the warning it
+used to carry was about a workspace that was never there.

.changeset/objectql-dataset-level-filter.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+Apply a dataset's definition-level `filter` on the ObjectQL analytics path
+(#10413, phase 1). `/api/v1/analytics/query` served by a driver that reports
+`objectqlAggregate` but not `nativeSql` (MongoDB, the memory driver) reached
+`engine.aggregate` with no `filter` key at all: the dataset's own scope — a
+`filter: { is_deleted: false }` on the dataset definition — was dropped, so
+every measure aggregated the whole table while the dashboard door, on the same
+cube and the same measure names, answered the scoped numbers. The scope is now
+ANDed into the strategy's whole-call filter (never merged key-by-key, so a
+caller's own `where` and the time windows cannot be overwritten by it), and the
+representative SQL echo renders it too.
+
+Per-MEASURE `filter`s on this path are still not applied: an
+`engine.aggregate` aggregation is `{ field, method, alias }` and cannot carry a
+predicate of its own. Widening that contract is #10576; lowering the measure
+filters into it is phase 2 of #10413. The native-SQL path already applies both
+(#10298).

apps/docs/next.config.mjs

@@ -6,6 +6,28 @@ const withMDX = createMDX();
 /** @type {import('next').NextConfig} */
 const config = {
   reactStrictMode: true,
+  // `next dev` otherwise writes `apps/docs/AGENTS.md` and `apps/docs/CLAUDE.md`
+  // into the working tree whenever it detects an AI coding agent (Next 16
+  // `ensureAgentRulesForDev`). Neither path is tracked or ignored, so both land
+  // as `??` and any `git add -A` after booting the docs server sweeps them into
+  // an unrelated PR. Those two filenames are load-bearing in this repo: the
+  // root `AGENTS.md` is the binding playbook and agents are told to read the
+  // `AGENTS.md` governing the files they touch, so a Next-authored stub
+  // pointing at `node_modules/next/dist/docs/` can be read as this repo's
+  // discipline -- and the generated text argues for committing itself, which
+  // nudges an agent the wrong way. The generated `CLAUDE.md` is the single
+  // line `@AGENTS.md`, an import directive that pulls the stub in.
+  //
+  // Disabled at the source rather than gitignored on purpose: an ignore rule
+  // for `apps/docs/AGENTS.md` would silently swallow a future repo-authored
+  // `AGENTS.md` for this app, failing invisibly at exactly the moment someone
+  // was trying to add real guidance there. A visible untracked file is a better
+  // failure than an invisibly ignored one for this filename specifically.
+  //
+  // This only stops future generation: a checkout that already ran `next dev`
+  // keeps its copies until they are removed once by hand
+  // (`rm -f apps/docs/AGENTS.md apps/docs/CLAUDE.md`).
+  agentRules: false,
   // No `output: 'standalone'` here on purpose. The standalone packer
   // (`writeStandaloneDirectory` -> `copyTracedFiles`) opens
   // `.next/next-server.js.nft.json`, and that open is the ONLY thing in a

examples/app-showcase/test/approval-resume-relation-expand.test.ts

@@ -68,12 +68,20 @@ const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 const openKernels: Array<{ shutdown?: () => Promise<void> }> = [];
 const openDrivers: Array<{ disconnect?: () => Promise<void> }> = [];
 afterEach(async () => {
-  while (openDrivers.length) {
-    try { await openDrivers.pop()?.disconnect?.(); } catch { /* noop */ }
-  }
+  // Kernels first, drivers second: the kernel's own teardown still wants a
+  // live driver to drain against -- that is the rule, regardless of what it
+  // costs on any given day.
+  //
+  // Measured here (#10373): this file's own DATABASE_ERROR lines are all
+  // "no such table" probes against sys_* tables bootShowcaseApprovals()
+  // never provisions, not post-disconnect reads -- swapping the order left
+  // the count unchanged (36 suite-wide / 31 in this file, before and after).
   while (openKernels.length) {
     try { await openKernels.pop()?.shutdown?.(); } catch { /* noop */ }
   }
+  while (openDrivers.length) {
+    try { await openDrivers.pop()?.disconnect?.(); } catch { /* noop */ }
+  }
 });
 
 interface Booted {

examples/embed-objectql/src/index.ts

@@ -13,6 +13,9 @@
 // shape you would ship in a `*.object.ts` to a full ObjectStack backend. One
 // object model, two hosts; only the installed capability set differs.
 
+import { realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { ObjectQL } from '@objectstack/objectql/core';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { ObjectSchema, Field, type ServiceObject } from '@objectstack/spec/data';
@@ -56,8 +59,41 @@ export async function runEmbeddedEngine(): Promise<AccountRow[]> {
   }) as Promise<AccountRow[]>;
 }
 
-// Allow `node`/`tsx`-style direct execution to print the result.
-if (import.meta.url === `file://${process.argv[1]}`) {
+// ─── entry guard ───────────────────────────────────────────────────────
+// ⛔ NOT ``import.meta.url === `file://${process.argv[1]}` ``. Node symlink-resolves
+// `import.meta.url` but leaves `process.argv[1]` exactly as the caller typed it, and
+// the template also skips the percent-encoding `pathToFileURL` applies — so that
+// spelling goes INERT (exit 0, no output) through a symlink AND on any checkout path
+// containing a character that needs encoding (a `#` in a parent directory name is
+// enough, with no symlink involved). Compare RESOLVED PATHS, never URL strings.
+//
+// Same predicate as `packages/cli/src/utils/invocation.ts` (`isProcessEntry`) and
+// `scripts/invoked-as.mjs` (`invokedAs`). Spelled out rather than imported because
+// neither home is legally reachable from this file — the PR for #10269 carries the
+// boundary measurement. ⚠️ Two predicates answering this question differently IS the
+// defect this closes; change one, change all of them.
+function isProcessEntry(): boolean {
+  const entryArg = process.argv[1];
+  if (!entryArg) return false; // `node --eval` / the REPL
+  const self = resolve(fileURLToPath(import.meta.url));
+  const entry = resolve(entryArg);
+  // `node <dir>` gives the ENTRY ARGUMENT, and only it, directory resolution.
+  const candidates = [entry, join(entry, 'index.js'), join(entry, 'index.mjs'), join(entry, 'index.ts')];
+  if (candidates.includes(self)) return true;
+  const realSelf = realOrSelf(self);
+  return candidates.some((candidate) => realOrSelf(candidate) === realSelf);
+}
+
+/** `realpathSync`, degrading to the input for a path that cannot be read. */
+function realOrSelf(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+if (isProcessEntry()) {
   runEmbeddedEngine()
     .then((rows) => {
       // eslint-disable-next-line no-console