Merge remote-tracking branch 'origin/main' into claude/dead-dashboard-header-refs-7zo1ut

# Conflicts:
#	content/docs/getting-started/validating-metadata.mdx
#	packages/cli/src/commands/validate.ts

Author: claude

.changeset/capability-provider-preflight-3366.md

@@ -0,0 +1,28 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": minor
+---
+
+feat(cli): preflight that every `requires` capability has an installable provider
+in the current edition (#3366)
+
+A capability listed in `requires: [...]` was only checked at `serve`/`start` time,
+and a missing provider produced a generic "not installed — add it to your
+dependencies" error even when the provider has **no installable version in the
+current edition**. `os validate` (token-vocabulary only) and `os build` (never
+resolved providers) both passed, so a `validate && build && test` CI script never
+caught it — it surfaced only as an opaque boot crash. Seen upgrading an
+open-edition app from `14.7` to `16` after `@objectstack/service-ai` went
+cloud-only (ADR-0025).
+
+- `@objectstack/spec/kernel` now exports `PLATFORM_CAPABILITY_PROVIDERS`
+  (token → provider package + edition) and a pure `classifyRequiredCapability()` —
+  one machine-readable source of truth for the provider/edition knowledge the
+  serve resolver previously encoded informally.
+- `os build` and `os validate` gained a provider preflight. A `requires` entry
+  whose provider has **no installable version in the active edition** (e.g. `ai` →
+  `@objectstack/service-ai`, cloud-only) now fails fast with an edition-aware
+  message; an absent-but-installable provider is an advisory `pnpm add` hint, not
+  a hard error; a satisfied `requires` list passes unchanged.
+- The `os serve` boot error now renders the same classification, so preflight and
+  boot read identically.

.changeset/dashboard-filter-field-validation.md

@@ -0,0 +1,23 @@
+---
+"@objectstack/lint": minor
+---
+
+Validate dashboard filter field-existence at build time (extend ADR-0021, #3365).
+
+`validateWidgetBindings` now checks that every dashboard-level filter (`dateRange`
++ each `globalFilters[]`) resolves to a real field on each bound widget's dataset
+object. Since #2501 wired these filters into every widget's analytics query, a
+filter field absent on a widget's object — e.g. a `dateRange` bound to
+`close_date` inherited by an account/contact widget over a different object —
+emitted invalid SQL (`no such column: close_date`) and crashed the widget at
+render time. That build-decidable invariant previously escaped `os validate` /
+`os build` and failed only when a user opened the dashboard.
+
+It now fails the build (new rule `dashboard-filter-field-unknown`) with a message
+naming the dashboard, widget, filter, field, and object, unless the widget opts
+out via `filterBindings: { <name>: false }` or re-targets to an existing field —
+mirroring the field-existence invariant ADR-0032 enforces for CEL references.
+Effective-field resolution matches the runtime (`filterBindings` re-target /
+opt-out, legacy `targetWidgets` allow-list, filter default). Registry-injected
+system fields (e.g. `created_at`, the `dateRange` default) and objects outside
+the validated stack never false-positive.

.changeset/notifications-hono-e2e-regression-test.md

@@ -0,0 +1,4 @@
+---
+---
+
+Add an end-to-end regression test that boots a real hono server (ObjectQL + messaging + dispatcher) and drives the in-app notifications mark-read flow over HTTP, asserting `sys_notification_receipt` rows flip to `read` and the unread count drops (#3362). Test-only (plus a test-scoped devDependency); no runtime code changes, so this releases nothing.

.changeset/server-timing-admin-gated-hono.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/observability": patch
+"@objectstack/rest": patch
+"@objectstack/plugin-hono-server": patch
+"@objectstack/runtime": patch
+---
+
+fix(server-timing): emit the per-request, admin-gated `Server-Timing` header on the standard server (`os serve`/`dev`) (#3361)
+
+The per-request `Server-Timing` path (#2408) — where an admin sends
+`X-OS-Debug-Timing: 1` (or `json`) and gets phase timings while an ordinary user
+gets nothing — never emitted on the shipped Hono server. The disclosure gate the
+Hono middleware opens is only ever flipped by the runtime dispatcher's
+`timedResolveExecutionContext`, but the data (`/api/v1/data/*`) and metadata
+(`/api/v1/meta/*`) routes on `os serve`/`dev` are served by `@objectstack/rest`'s
+`RestServer` (which shadows the Hono plugin's own CRUD), and its identity
+resolver never opened the gate. Only global mode (`OS_SERVER_TIMING=true`) — which
+discloses to *every* caller, not just admins — worked.
+
+- **observability**: the disclosure predicate `isPerfDisclosurePrincipal(ec)` now
+  lives here (the home of the gate), the single definition of "who may pull
+  per-request timings" shared by every HTTP entry point. `@objectstack/runtime`
+  re-exports it for back-compat.
+- **rest**: `RestServer.resolveExecCtx` opens the gate for an admin/service
+  principal (via the carried `posture` rung), the REST-server analog of the
+  dispatcher — this is the fix that makes `os serve`/`dev` emit.
+- **plugin-hono-server**: the standalone CRUD surface's self-contained
+  `resolveCtx` opens the gate too (deriving the rung for the gate decision only,
+  never writing it onto the enforcement context). Adds an e2e test that boots the
+  Hono app and asserts an admin gets `Server-Timing` while a member/anon does not.

content/docs/getting-started/validating-metadata.mdx

@@ -48,6 +48,16 @@ If a name doesn't resolve, the chart renders **empty** — no error (ADR-0021).
 `os validate` resolves every binding against the declared datasets and fails on a
 dangling one.
 
+The same gate also checks **dashboard-level filter fields**. A dashboard's
+`dateRange` and each `globalFilters[]` entry are broadcast into every widget's
+analytics query, so a filter field that doesn't exist on a bound widget's object
+emits invalid SQL (`no such column: …`) and crashes that widget at render time.
+`os validate` fails when a filter's effective field — after any per-widget
+`filterBindings` re-target — is absent on the widget's dataset object, naming the
+dashboard, widget, filter, field, and object. Opt a widget out with
+`filterBindings: { <name>: false }`, or re-target the filter to one of that
+object's own fields.
+
 ### 3. Dead action/route references
 
 A dashboard `header.actions[]` button (and a widget's `actionUrl`) names a target:

packages/cli/src/commands/compile.ts

@@ -18,6 +18,7 @@ import { lintFlowPatterns } from '../utils/lint-flow-patterns.js';
 import { lintAutonumberFormats } from '../utils/lint-autonumber-formats.js';
 import { lintLivenessProperties } from '../utils/lint-liveness-properties.js';
 import { lintViewRefs } from '../utils/lint-view-refs.js';
+import { preflightRequiredCapabilities, renderCapabilityMessage } from '../utils/capability-preflight.js';
 import { collectAndLintDocs } from '../utils/collect-docs.js';
 import { buildRuntimeBundle, cleanupOldRuntimeBundles } from '../utils/build-runtime.js';
 import {
@@ -171,6 +172,45 @@ export default class Compile extends Command {
         }
       }
 
+      // 3b-ter. [#3366] Installable-provider preflight. Every capability the app
+      //     DECLARES in `requires: [...]` must have a provider resolvable in the
+      //     active edition. `os validate` only checks the token vocabulary and
+      //     `os build` never resolved providers, so a `requires` entry whose
+      //     provider has NO installable version in this edition (e.g. `ai` →
+      //     @objectstack/service-ai, cloud-only since ADR-0025) slipped through
+      //     to a generic `os start` crash. Fail the build with the edition-aware
+      //     message instead; an absent-but-installable provider is a `pnpm add`
+      //     hint (advisory), and a satisfied list passes silently.
+      if (!flags.json) printStep('Checking capability providers (#3366)...');
+      const capPreflight = preflightRequiredCapabilities({
+        requires: Array.isArray((config as { requires?: unknown[] }).requires)
+          ? ((config as { requires?: unknown[] }).requires as unknown[])
+          : [],
+        projectDir: path.dirname(absolutePath),
+      });
+      if (capPreflight.errors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({
+            success: false,
+            error: 'capability provider preflight failed',
+            issues: capPreflight.errors.map((c) => ({ token: c.token, message: renderCapabilityMessage(c) })),
+          }));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`Capability provider check failed (${capPreflight.errors.length} issue${capPreflight.errors.length > 1 ? 's' : ''})`);
+        for (const c of capPreflight.errors) {
+          console.log(`  • ${renderCapabilityMessage(c)}`);
+        }
+        this.exit(1);
+      }
+      if (capPreflight.warnings.length > 0 && !flags.json) {
+        console.log('');
+        for (const c of capPreflight.warnings) {
+          printWarning(renderCapabilityMessage(c));
+        }
+      }
+
       // 3b-bis. ADR-0089 D3b — deprecated visibility aliases + mis-layered
       //     binding root. Checked on `normalized` (PRE-parse): the schema folds
       //     `visibleOn`/`visibility` into `visibleWhen` at parse, so `result.data`

packages/cli/src/commands/serve.ts

@@ -11,6 +11,7 @@ import { isHostConfig, shouldBootWithLibrary } from '../utils/plugin-detection.j
 import { resolveDriverType, createStorageDriver, UnsupportedDriverError } from '../utils/storage-driver.js';
 import { readEnvWithDeprecation, resolveMultiOrgEnabled, resolveAllowDegradedTenancy, isMcpServerEnabled, resolveSearchPinyinEnabled, isModuleNotFoundError } from '@objectstack/types';
 import { PLATFORM_CAPABILITY_TOKENS } from '@objectstack/spec/kernel';
+import { missingProviderMessage } from '../utils/capability-preflight.js';
 import { resolveObjectStackHome } from '@objectstack/runtime';
 import { LOG_LEVELS, resolveLogLevel, readLogLevelEnv } from '../utils/log-level.js';
 import {
@@ -1840,7 +1841,7 @@ export default class Serve extends Command {
       const loadOptionalServicePlugin = async (
         pkg: string,
         exportName: string,
-        opts: { required: boolean; label: string; track: string },
+        opts: { required: boolean; label: string; track: string; capability: string },
       ): Promise<boolean> => {
         try {
           const mod: any = await importFromHost(pkg);
@@ -1860,9 +1861,12 @@ export default class Serve extends Command {
           if (opts.required) {
             const msg = err instanceof Error ? err.message : String(err);
             throw new Error(
+              // #3366 — an absent provider is classified by edition: a cloud-only
+              // capability (e.g. `ai` → @objectstack/service-ai) says so instead of
+              // the un-followable "add it to your dependencies". Same wording the
+              // `os build` preflight prints, so boot and preflight read identically.
               Serve.isModuleNotFoundError(err)
-                ? `[${opts.label}] required but ${pkg} is not installed. `
-                    + `Add it to the app's dependencies, or drop the capability from \`requires\`.`
+                ? missingProviderMessage(opts.capability)
                 : `[${opts.label}] failed to start: ${msg}`,
             );
           }
@@ -1900,7 +1904,7 @@ export default class Serve extends Command {
         const aiLoaded = await loadOptionalServicePlugin(
           '@objectstack/service-ai',
           'AIServicePlugin',
-          { required: aiDecision === 'required', label: 'AI', track: 'AIService' },
+          { required: aiDecision === 'required', label: 'AI', track: 'AIService', capability: 'ai' },
         );
 
         // AI Studio (AI-driven metadata authoring / "online development") builds on
@@ -1927,7 +1931,7 @@ export default class Serve extends Command {
               await loadOptionalServicePlugin(
                 '@objectstack/service-ai-studio',
                 'AIStudioPlugin',
-                { required: studioDecision === 'required', label: 'AI Studio', track: 'AIStudio' },
+                { required: studioDecision === 'required', label: 'AI Studio', track: 'AIStudio', capability: 'ai-studio' },
               );
             }
           }
@@ -2100,9 +2104,12 @@ export default class Serve extends Command {
           // best-effort: absent ⇒ warn, crash ⇒ error, boot continues.
           if (declaredRequires.has(cap)) {
             throw new Error(
+              // #3366 — edition-aware message via the shared classifier (same
+              // wording the `os build` preflight prints). For these CAPABILITY_
+              // PROVIDERS tokens (all open-edition) that's the `pnpm add` hint;
+              // the cloud-only tokens surface their edition boundary instead.
               missing
-                ? `Capability "${cap}" is required but ${spec.pkg} is not installed. `
-                    + `Add it to the app's dependencies, or remove "${cap}" from \`requires\`.`
+                ? missingProviderMessage(cap)
                 : `Capability "${cap}" (${spec.pkg}) failed to start: ${msg}`,
             );
           }

packages/cli/src/commands/validate.ts

@@ -3,7 +3,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { existsSync, readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import chalk from 'chalk';
 import { ZodError } from 'zod';
 import { ObjectStackDefinitionSchema, normalizeStackInput, type ConversionNotice } from '@objectstack/spec';
@@ -19,6 +19,7 @@ import { validateCapabilityReferences } from '@objectstack/lint';
 import { validateVisibilityPredicates } from '@objectstack/lint';
 import { validateSecurityPosture } from '@objectstack/lint';
 import { validateFlowTriggerReadiness } from '@objectstack/lint';
+import { preflightRequiredCapabilities, renderCapabilityMessage } from '../utils/capability-preflight.js';
 import {
   printHeader,
   printKV,
@@ -460,6 +461,42 @@ export default class Validate extends Command {
         }
       }
 
+      // 3h. [#3366] Installable-provider preflight — the shift-left of the
+      //     `serve`-time capability check. `os validate` previously only checked
+      //     the `requires` tokens against the vocabulary (ADR-0066), never
+      //     whether each token's provider is resolvable in the active edition. A
+      //     token whose provider has NO installable version here (e.g. `ai` →
+      //     @objectstack/service-ai, cloud-only) fails; absent-but-installable is
+      //     an advisory `pnpm add` hint. Mirrors the `os build` gate exactly.
+      if (!flags.json) printStep('Checking capability providers (#3366)...');
+      const capProviderPreflight = preflightRequiredCapabilities({
+        requires: Array.isArray((config as { requires?: unknown[] }).requires)
+          ? ((config as { requires?: unknown[] }).requires as unknown[])
+          : [],
+        projectDir: dirname(absolutePath),
+      });
+      const capProviderErrors = capProviderPreflight.errors;
+      const capProviderWarnings = capProviderPreflight.warnings.map((c) => ({
+        token: c.token,
+        message: renderCapabilityMessage(c),
+      }));
+      if (capProviderErrors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({
+            valid: false,
+            errors: capProviderErrors.map((c) => ({ token: c.token, message: renderCapabilityMessage(c) })),
+            duration: timer.elapsed(),
+          }, null, 2));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`Capability provider check failed (${capProviderErrors.length} issue${capProviderErrors.length > 1 ? 's' : ''})`);
+        for (const c of capProviderErrors) {
+          console.log(`  • ${renderCapabilityMessage(c)}`);
+        }
+        this.exit(1);
+      }
+
       // 4. Collect and display stats
       const stats = collectMetadataStats(config);
 
@@ -472,7 +509,7 @@ export default class Validate extends Command {
           valid: true,
           manifest: config.manifest,
           stats,
-          warnings: [...exprWarnings, ...widgetWarnings, ...actionRefWarnings, ...styleWarnings, ...jsxWarnings, ...capWarnings, ...flowReadinessWarnings, ...securityAdvisories],
+          warnings: [...exprWarnings, ...widgetWarnings, ...actionRefWarnings, ...styleWarnings, ...jsxWarnings, ...capWarnings, ...flowReadinessWarnings, ...securityAdvisories, ...capProviderWarnings],
           conversions: conversionNotices,
           specVersionGap: specGap,
           duration: timer.elapsed(),
@@ -483,6 +520,12 @@ export default class Validate extends Command {
       // 5. Warnings (non-blocking)
       const warnings: string[] = [];
 
+      // [#3366] Installable-provider hints — a declared capability whose provider
+      // is absent but addable (`pnpm add`), or an unknown token (typo).
+      for (const w of capProviderWarnings) {
+        warnings.push(w.message);
+      }
+
       // ADR-0089 D3b — deprecated visibility aliases + mis-layered binding root.
       // Checked on `normalized` (PRE-parse): the schema folds `visibleOn`/
       // `visibility` into `visibleWhen` during parse, so `result.data` no longer