Merge branch 'main' into claude/issue-10268-release-section-coverage

Author: claude[bot]

.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

packages/cli/src/commands/doctor-env-provenance.test.ts

@@ -447,7 +447,18 @@ describe('os doctor, end to end, against a posture that only exists in .env', ()
     const healthy = await runDoctor();
 
     expect(healthy.exitCode).toBeUndefined();
-    expect(healthy.out).toContain('Environment is functional');
+    // #10679 — this used to read `toContain('Environment is functional')`, and
+    // it passed for a reason that had nothing to do with #5387: the temp cwd
+    // has no `packages/spec`, and doctor warned `@objectstack/spec Not built`
+    // about that absent workspace on every run. Removing that phantom warning
+    // leaves this cwd with no findings at all, so the summary is now the
+    // healthy one. What the control actually claims — doctor reached its
+    // summary and did NOT refuse to call this environment usable — is what the
+    // matcher says instead, and it still cannot pass for the broken leg below
+    // (that one prints `Some critical issues found`).
+    expect(healthy.out).toMatch(
+      /Environment is (healthy and ready for development|functional but has some warnings)/,
+    );
     expect(healthy.out).not.toContain('Tenancy posture');
     // The report says what it read even when everything is fine — that is the
     // "not a silent merge" half, and it is only observable on a healthy run.

packages/cli/src/commands/doctor-tenancy-posture-report.test.ts

@@ -295,8 +295,19 @@ describe('os doctor reports an unrecognized posture and exits non-zero', () => {
 
     // Doctor completes normally. This is the sentence #5382 quoted, and here it
     // is CORRECT: this environment really can start.
+    //
+    // #10679 — the matcher accepts either non-error summary. The control used
+    // to pin `Environment is functional but has some warnings` literally, and
+    // it held only because the temp cwd has no `packages/spec` and doctor
+    // warned `@objectstack/spec Not built` about that absent workspace every
+    // time. With that phantom warning gone this cwd has no findings, so the
+    // summary is the healthy one. Either sentence proves the control's actual
+    // claim; neither can be produced by the broken leg below, which prints
+    // `Some critical issues found` and exits 1.
     expect(healthy.exitCode).toBeUndefined();
-    expect(healthy.out).toContain('Environment is functional');
+    expect(healthy.out).toMatch(
+      /Environment is (healthy and ready for development|functional but has some warnings)/,
+    );
     expect(healthy.out).not.toContain('Tenancy posture');
 
     // ── The case: one character changed ──────────────────────────────────