feat(spec,cli): publish the foundational capability slate so every runtime reads one list (#3786, cloud#925) (#4170)

`Serve.ALWAYS_ON_CAPABILITIES` was declared in the CLI under a comment saying
cloud / multi-environment hosts "mirror this list on their per-project kernels".
Nothing made that true, and they had already diverged: cloud's per-tenant slate
was missing `sms`, `messaging` and `analytics`, so an app that worked under
`objectstack serve` could lose `notify` deliveries and dataset previews once
hosted — silently.

The slate and its per-entry rationale move to PLATFORM_ALWAYS_ON_CAPABILITIES in
@objectstack/spec, beside PLATFORM_CAPABILITY_PROVIDERS — published a release
earlier for exactly this reason. Serve.ALWAYS_ON_CAPABILITIES becomes a
re-export, kept as a stable handle for existing callers.

Four assertions make the single declaration trustworthy for both readers: frozen,
deduped, non-empty; the foundational prefix pinned (mount order matters when
services bind during kernel:ready); every member a real PLATFORM_CAPABILITY_TOKENS
entry with a declared provider; and every member edition:'open', since a floor the
open distribution cannot mount is not a floor. Verified by mutation.

No behaviour change — the published slate is byte-identical to the CLI's list and
serve-defaults / serve-capability-vocabulary pass unchanged. What changes is that
cloud now has something to derive from, closing the half cloud#925 left open.

Author: os-zhuang

.changeset/platform-always-on-capabilities.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": patch
+---
+
+feat(spec,cli): publish the foundational capability slate so every runtime reads one list (#3786, cloud#925)
+
+`Serve.ALWAYS_ON_CAPABILITIES` — the capabilities auto-added to every app's
+`requires` outside `--preset minimal` — was declared in the CLI, under a comment
+noting that "cloud / multi-environment hosts (which live in a separate
+distribution) mirror this list on their per-project kernels."
+
+Nothing made that true, and they had already diverged. Cloud's per-tenant slate
+was missing **`sms`, `messaging` and `analytics`**, so an app that worked under
+`objectstack serve` could lose `notify` deliveries and dataset previews once
+hosted — silently, with no error anywhere. The framework's own comment on
+`analytics` spells out the failure mode it was made always-on to prevent:
+"Without it the dataset preview + dashboard/report analytics widgets silently
+no-op."
+
+**New export: `PLATFORM_ALWAYS_ON_CAPABILITIES`** (`@objectstack/spec`, and
+`@objectstack/spec/kernel`). The slate and its per-entry rationale now live
+beside `PLATFORM_CAPABILITY_PROVIDERS` — the map published for exactly this
+reason one release earlier, "so cloud's objectos-runtime and the framework CLI
+classify a `requires` token identically". `Serve.ALWAYS_ON_CAPABILITIES` is now
+a re-export of it, kept as a stable handle for existing callers rather than
+deleted: one declaration, two readers.
+
+Four assertions make the single declaration trustworthy for both of them — the
+slate is frozen, deduped and non-empty; its foundational prefix
+(`queue, job, cache, settings, email, storage`) is pinned, because mount order
+matters when services bind to each other during `kernel:ready`; every member is
+a real `PLATFORM_CAPABILITY_TOKENS` entry; every member has a declared provider;
+and every member is `edition: 'open'`, since a floor the open distribution
+cannot mount is not a floor. Verified by mutation: an unknown token, an
+enterprise-edition token, and a reordered prefix each turn the gate red.
+
+**No behaviour change.** The published slate is byte-identical to the list the
+CLI already had, and `serve-defaults.test.ts` / `serve-capability-vocabulary.test.ts`
+pass unchanged. What changes is that there is now something to derive from:
+cloud's hosted runtime can drop its copy and read this instead, which is the
+follow-up cloud#925 left open — it lands there once the `.objectstack-sha` pin
+moves past this release.

packages/cli/src/commands/serve.ts

@@ -11,7 +11,7 @@ import { mergeBootConfig } from '../utils/merge-boot-config.js';
 import { isHostConfig, shouldBootWithLibrary } from '../utils/plugin-detection.js';
 import { resolveDriverType, resolveStorageDefinition, UnsupportedDriverError } from '../utils/storage-driver.js';
 import { readEnvWithDeprecation, resolveMultiOrgEnabled, resolveTenancyPosture, resolveAllowDegradedTenancy, isMcpServerEnabled, stampSearchPinyinEnabled, isModuleNotFoundError } from '@objectstack/types';
-import { PLATFORM_CAPABILITY_TOKENS } from '@objectstack/spec/kernel';
+import { PLATFORM_CAPABILITY_TOKENS, PLATFORM_ALWAYS_ON_CAPABILITIES } 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';
@@ -200,20 +200,19 @@ export default class Serve extends Command {
    *
    * Opt out: `objectstack serve --preset minimal`.
    *
-   * Cloud / multi-environment hosts (which live in a separate distribution)
-   * mirror this list on their per-project kernels.
+   * DERIVED from `@objectstack/spec`'s `PLATFORM_ALWAYS_ON_CAPABILITIES`, where
+   * the slate and its per-entry rationale now live. This used to BE the
+   * declaration, under a comment noting that cloud / multi-environment hosts
+   * "mirror this list on their per-project kernels" — with nothing making that
+   * true. They had diverged: the hosted slate was missing `sms`, `messaging` and
+   * `analytics`, so an app that worked under `objectstack serve` silently lost
+   * dataset previews and `notify` deliveries once hosted (cloud#925, #3786).
+   *
+   * Kept as a re-export rather than deleted so `Serve.ALWAYS_ON_CAPABILITIES`
+   * stays a stable handle for existing callers and tests — one declaration, two
+   * readers.
    */
-  static readonly ALWAYS_ON_CAPABILITIES: readonly string[] = Object.freeze([
-    // The first six form the pinned foundational prefix (see
-    // serve-defaults.test.ts) — grow the slate AFTER them.
-    'queue', 'job', 'cache', 'settings', 'email', 'storage', 'sms', 'sharing', 'messaging',
-    // `analytics` is foundational post-ADR-0021: the AnalyticsService backs the
-    // dataset/cube query endpoints (`/api/v1/analytics/*`). It must exist even
-    // when an app declares no `analyticsCubes`, because a `dataset` can be
-    // authored/previewed inline (Studio) and compiled on the fly. Without it the
-    // dataset preview + dashboard/report analytics widgets silently no-op.
-    'analytics',
-  ]);
+  static readonly ALWAYS_ON_CAPABILITIES: readonly string[] = PLATFORM_ALWAYS_ON_CAPABILITIES;
 
   /**
    * Auto-registered plugin tiers. Plugins explicitly listed in

packages/spec/api-surface.json

@@ -81,6 +81,7 @@
     "ObjectStackDefinitionSchema (const)",
     "ObjectStackSchema (const)",
     "P (const)",
+    "PLATFORM_ALWAYS_ON_CAPABILITIES (const)",
     "PLATFORM_CAPABILITY_PROVIDERS (const)",
     "PLATFORM_CAPABILITY_TOKENS (const)",
     "PlatformCapabilityProvider (interface)",
@@ -1612,6 +1613,7 @@
     "OpsFilePathSchema (const)",
     "OpsPluginStructure (type)",
     "OpsPluginStructureSchema (const)",
+    "PLATFORM_ALWAYS_ON_CAPABILITIES (const)",
     "PLATFORM_CAPABILITY_PROVIDERS (const)",
     "PLATFORM_CAPABILITY_TOKENS (const)",
     "PROTOCOL_MAJOR (const)",

packages/spec/src/index.ts

@@ -135,6 +135,9 @@ export {
   PLATFORM_CAPABILITY_TOKENS,
   isKnownPlatformCapability,
   PLATFORM_CAPABILITY_PROVIDERS,
+  // The foundational slate every server-side runtime mounts (cloud#925, #3786) —
+  // one declaration for `objectstack serve` and cloud's per-tenant runtime alike.
+  PLATFORM_ALWAYS_ON_CAPABILITIES,
   classifyRequiredCapability,
   type CapabilityEdition,
   type PlatformCapabilityProvider,

packages/spec/src/kernel/platform-capabilities.test.ts

@@ -3,6 +3,7 @@ import {
   PLATFORM_CAPABILITY_TOKENS,
   isKnownPlatformCapability,
   PLATFORM_CAPABILITY_PROVIDERS,
+  PLATFORM_ALWAYS_ON_CAPABILITIES,
   classifyRequiredCapability,
 } from './platform-capabilities';
 
@@ -114,3 +115,57 @@ describe('classifyRequiredCapability (#3366)', () => {
     expect(seen).toEqual(['@objectstack/service-automation']);
   });
 });
+
+/**
+ * The foundational slate (cloud#925, #3786).
+ *
+ * It moved here from `Serve.ALWAYS_ON_CAPABILITIES` because two runtimes mount
+ * it — `objectstack serve` and cloud's per-tenant objectos-runtime — and the
+ * second kept a copy under a comment that only said hosts "mirror this list".
+ * They had already diverged by three entries. These assertions are what makes
+ * the single declaration trustworthy for both readers.
+ */
+describe('PLATFORM_ALWAYS_ON_CAPABILITIES', () => {
+  it('is frozen, non-empty and free of duplicates', () => {
+    expect(Object.isFrozen(PLATFORM_ALWAYS_ON_CAPABILITIES)).toBe(true);
+    expect(PLATFORM_ALWAYS_ON_CAPABILITIES.length).toBeGreaterThan(0);
+    expect(PLATFORM_ALWAYS_ON_CAPABILITIES).toHaveLength(
+      new Set(PLATFORM_ALWAYS_ON_CAPABILITIES).size,
+    );
+  });
+
+  it('pins the foundational prefix — grow the slate AFTER these six', () => {
+    // Order matters at mount time: settings/queue/job must precede the services
+    // that bind to them during their own `kernel:ready` phase.
+    expect(PLATFORM_ALWAYS_ON_CAPABILITIES.slice(0, 6)).toEqual([
+      'queue', 'job', 'cache', 'settings', 'email', 'storage',
+    ]);
+  });
+
+  it('every member is a real platform capability token', () => {
+    // A slate entry outside the vocabulary could never be classified, and every
+    // runtime mounting the slate would force-add a token nothing provides.
+    const unknown = PLATFORM_ALWAYS_ON_CAPABILITIES.filter(
+      (c) => !(PLATFORM_CAPABILITY_TOKENS as readonly string[]).includes(c),
+    );
+    expect(unknown).toEqual([]);
+  });
+
+  it('every member has a declared provider', () => {
+    // The slate is force-mounted, so a member with no provider entry would be
+    // added to every app's `requires` and then fail to resolve for all of them.
+    const providerless = PLATFORM_ALWAYS_ON_CAPABILITIES.filter(
+      (c) => !PLATFORM_CAPABILITY_PROVIDERS[c],
+    );
+    expect(providerless).toEqual([]);
+  });
+
+  it('is open-edition only — the floor must be mountable without a licence', () => {
+    // A cloud/enterprise-edition entry in the FLOOR would make the open
+    // distribution unable to satisfy its own defaults.
+    const gated = PLATFORM_ALWAYS_ON_CAPABILITIES.filter(
+      (c) => PLATFORM_CAPABILITY_PROVIDERS[c]?.edition !== 'open',
+    );
+    expect(gated).toEqual([]);
+  });
+});

packages/spec/src/kernel/platform-capabilities.ts

@@ -168,6 +168,48 @@ export const PLATFORM_CAPABILITY_PROVIDERS: Readonly<Record<string, PlatformCapa
     governance: { package: null, edition: 'cloud', note: 'cloud governance tier' },
   });
 
+/**
+ * The foundational capability slate: what every server-side runtime is expected
+ * to mount whether or not an app names it in `requires`.
+ *
+ * These are the services the platform assumes exist — background work, settings
+ * persistence, transactional mail, file uploads, notifications, analytics — so
+ * an app that never declares them still behaves the way its authors (and the
+ * Studio surfaces) expect.
+ *
+ * Published here rather than left on `Serve.ALWAYS_ON_CAPABILITIES` for the same
+ * reason {@link PLATFORM_CAPABILITY_PROVIDERS} was: **more than one runtime
+ * mounts this slate.** The CLI's `serve` builds one kernel per process; cloud's
+ * objectos-runtime builds one per tenant environment and carried its own copy,
+ * under a CLI comment that merely said such hosts "mirror this list". They had
+ * already diverged — the hosted slate was missing `sms`, `messaging` and
+ * `analytics` — so an app that worked under `objectstack serve` could lose
+ * dataset previews and `notify` deliveries once hosted, silently, with no error
+ * anywhere (cloud#925, framework#3786). A second list nobody checks is how that
+ * happens; one exported list is how it stops.
+ *
+ * This is the FLOOR, not the ceiling: a host may mount more (cloud adds
+ * `observability`), and `objectstack serve --preset minimal` opts out entirely.
+ */
+export const PLATFORM_ALWAYS_ON_CAPABILITIES: readonly string[] = Object.freeze([
+  // The first six are the pinned foundational prefix — grow the slate AFTER them.
+  'queue', 'job', 'cache', 'settings', 'email', 'storage',
+  'sms',
+  'sharing',
+  // `messaging` is foundational post-ADR-0030: notifications flow through a
+  // single ingress (`NotificationService.emit`) — collaboration `@mention` /
+  // assignment (plugin-audit) and the `notify` flow node both deliver through
+  // the messaging pipeline, and the Console bell reads its materialization
+  // (`sys_inbox_message`). Without it those notifications silently no-op.
+  'messaging',
+  // `analytics` is foundational post-ADR-0021: the AnalyticsService backs the
+  // dataset/cube query endpoints (`/api/v1/analytics/*`). It must exist even
+  // when an app declares no `analyticsCubes`, because a `dataset` can be
+  // authored/previewed inline (Studio) and compiled on the fly. Without it the
+  // dataset preview + dashboard/report analytics widgets silently no-op.
+  'analytics',
+]);
+
 /**
  * Outcome of classifying one `requires` token against the installed providers:
  *   - `ok`          — provider resolvable (installed); nothing to do.