Kernel Services Checklist

The ObjectStack protocol defines 15 kernel services registered via the CoreServiceName enum (v17 removed the never-implemented graphql entry and retired the never-filled workflow slot, #4451). Each service maps to a set of protocol methods governed by its per-domain contract (DataProtocol, MetadataProtocol, ...) — the transitional ObjectStackProtocol composition alias was dissolved in v17 (ADR-0076 D9); capability availability comes from the runtime discovery services registry.

Key architecture principle: the kernel guarantees only data and metadata, and even those are filled by packages (@objectstack/objectql, @objectstack/metadata) rather than baked in — the kernel's own contribution is an in-memory fallback for the core slots that have one (metadata, cache, queue, job, i18n — not auth). Everything else — including auth and automation — is delivered by plugins. @objectstack/objectql is an example kernel implementation to get the basic API running; production kernels will be rebuilt as separate plugins.

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                     Kernel Layer                         │
│  ┌──────────────────┐  ┌──────────────────────────────┐ │
│  │  metadata (✅)    │  │  data (✅)                   │ │
│  │  MetadataPlugin   │  │  ObjectQL example kernel     │ │
│  │  → sys_metadata   │  │  Will be rebuilt as plugins  │ │
│  │  (in-mem fallback)│  │                              │ │
│  └──────────────────┘  └──────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│                    Plugin Layer                           │
│  All other services: analytics, auth, automation,        │
│  ui, realtime, notification, ai, i18n,                   │
│  search, file-storage, cache, queue, job                 │
│                                                          │
│  Discovery API reports availability per service          │
│  (available / degraded / stub / unavailable) so          │
│  clients adapt their UI accordingly                      │
└─────────────────────────────────────────────────────────┘

Service Overview

1. metadata Service ✅ Implemented

Service Name: metadata · Criticality: core
Implementation: MetadataPlugin (@objectstack/metadata) — persisted to sys_metadata. Fallbacks: the kernel's in-memory createMemoryMetadata (@objectstack/core) when nothing registers the slot, over ObjectQL's in-memory SchemaRegistry of artifact-loaded metadata.
Route Mounts: /api/v1/meta, /api/v1, /api/v1/packages

Protocol Methods

Former Gaps — all now closed

Every gap this section used to list has shipped. Only the kernel's own in-memory fallback is still a "framework": it serves real reads and writes but never reaches disk, which is exactly what it self-declares (degraded).

Discovery: Per-Service Status

The discovery endpoint returns a services map so clients know what is available. The metadata entry is computed from the implementation that fills the slot, not fixed (#4089): a stack running the kernel's in-memory fallback reports degraded with that fallback's own message, while a stack with MetadataPlugin reports available and no message. Below is the former — the fallback case:

{
  "services": {
    "metadata": {
      "enabled": true, "status": "degraded", "handlerReady": true,
      "route": "/api/v1/meta", "provider": "kernel",
      "message": "In-memory metadata registry — real reads and writes, no persistence (lost on restart). Register MetadataPlugin for a persisted registry."
    },
    "data": {
      "enabled": true, "status": "available",
      "route": "/api/v1/data", "provider": "kernel"
    },
    "auth": {
      "enabled": false, "status": "unavailable",
      "message": "Install @objectstack/plugin-auth to enable"
    }
  }
}

stub vs degraded — and what the dispatcher does with each

A service may self-declare that it is not the full thing (ADR-0076 D12), via a __serviceInfo: { status, handlerReady?, message? } property on the registered instance — see Services → presence is not capability for how an in-process caller reads it. The two values mean different things, and for the HTTP surface the difference is load-bearing (#4058):

Only handlerReady is consulted, never status — so an implementation that declares degraded but explicitly sets handlerReady: false is also treated as empty. The rule is enforced by one predicate (isServiceServeable) shared by the service domains, the route-mount gate, and both discovery builders, so what is advertised and what is served cannot disagree. It applies to the dispatcher-owned domains: /analytics, /automation, /notifications, /ai, /i18n. (/storage is no longer a dispatcher domain — the bridge was retired in #4087 and service-storage mounts /api/v1/storage itself — but its route advertisement is still gated on the same predicate.)

The services map still reports a registered stub as { enabled: true, status: "stub", handlerReady: false } rather than collapsing it to unavailable — "something is in this slot, and it is a fake" says more than "install a plugin".

2. data Service ✅ Implemented

Service Name: data · Criticality: required
Implementation: @objectstack/objectql → ObjectQL (IDataEngine)
Route Mount: /api/v1/data

Protocol Methods

Driver Support

3. analytics Service — Plugin Required

Service Name: analytics · Criticality: optional
Implementation: @objectstack/service-analytics (the only implementation)
Route Mount: /api/v1/analytics — only served when the plugin registers the service

Features (via @objectstack/service-analytics)

• Cube semantic queries: measures / dimensions / where filter → SQL or ObjectQL aggregation
• Context-aware read scoping: per-object RLS/tenant predicates resolved from the request's ExecutionContext (fail-closed)
• Cube metadata (/analytics/meta), SQL preview (/analytics/sql), dataset queries (/analytics/dataset/query)

4. auth Service ✅ Implemented

Service Name: auth · Criticality: core
Implementation: AuthPlugin → AuthManager (@objectstack/plugin-auth, built on better-auth)
Route Mount: /api/v1/auth — only exposed when a plugin registers the auth service

Where each capability lives

The auth service covers authentication (identity). Authorization is not a CoreServiceName slot at all — there is no permission service; the evaluators are registered under their own names (security.permissions, security.rls, security.fieldMasker) by @objectstack/plugin-security.

Spec Files: identity/identity.zod.ts, identity/organization.zod.ts, security/permission.zod.ts, system/auth-config.zod.ts, system/tenant.zod.ts (all under packages/spec/src/)

5–6. Business Services

5. ui Service — 1 routed method ✅ (was 5 declared, none routed)

getUiView

Retired in v17: ViewProtocol's five methods

listViews, getView, createView, updateView, deleteView — and their ten Request/Response schemas — were removed in #6239 under ADR-0049 enforce-or-remove. This checklist had recorded them as declared-and-unrouted since it was written; the removal makes that reading permanent instead of re-derivable. Views are read and written through the surfaces that always served them: the metadata API (/api/v1/meta/view/:name, view being a metadata type) for the stored definition, and getUiView above for the resolved render-time view.

The concrete cost of leaving it declared is on the record: #5948's issue body and its 2026-08-07 maintainer ruling both read GetViewResponseSchema — this retired block, zero implementations — as the contract of GET /ui/view/:object/:type, whose declared response is GetUiViewResponseSchema. One word apart, and identical to a grep.

Retired in v17: the workflow slot

The slot, its IWorkflowService contract and the three WorkflowProtocol methods (getWorkflowConfig, getWorkflowState, workflowTransition) were removed in #4451: nothing ever registered or resolved the slot (ADR-0115 Evidence 5), no method ever had an implementation, and no host ever mounted /api/v1/workflow. The three capabilities it named are live elsewhere — state-machine transitions are an object validation rule of type state_machine, approvals are approval flow nodes on the approvals runtime (ADR-0019 — decisions via POST /api/v1/approvals/requests/:id/{approve,reject,recall}, served by @objectstack/plugin-approvals), and record-triggered automation is lifecycle hooks + record_change flows.

6. automation Service — 1 method ✅ @objectstack/service-automation

triggerAutomation
Trigger engine, event triggers from ObjectQL hooks, flow executor, scheduled triggers. The /automation dispatcher domain gates on isServiceServeable, so a slot filled by a self-declared stub answers as an empty one.

7–10. Communication Services

7. realtime — 6 methods · @objectstack/service-realtime

realtimeConnect, realtimeDisconnect, realtimeSubscribe, realtimeUnsubscribe, setPresence, getPresence

8. notification — 7 methods · @objectstack/service-messaging

registerDevice, unregisterDevice, getNotificationPreferences, updateNotificationPreferences, listNotifications, markNotificationsRead, markAllNotificationsRead

The slot name is notification (singular) and the package that fills it shares no word with it — which is why the remedy sentence is looked up in CORE_SERVICE_PROVIDER rather than derived from the slot name. The /notifications domain currently routes the inbox subset: GET /notifications → listInbox, POST /notifications/read → markRead, POST /notifications/read/all → markAllRead. All three are optional on INotificationService — a send-only provider (SMTP, Twilio, a webhook) fills the slot legitimately without an inbox, and each route probes its own method and answers 501 when absent.

9. ai — contract removed ❌

aiNlq, aiSuggest, aiInsights

10. i18n — 3 methods

getLocales, getTranslations, getFieldLabels

Service Name: i18n · Criticality: core
Implementations: @objectstack/service-i18n (production — file-based) · In-memory fallback (createMemoryI18n from @objectstack/core)
Route Mount: /api/v1/i18n
Contract: II18nService in @objectstack/spec/contracts

Service Registration

// Production (real service)
kernel.use(new I18nServicePlugin({ defaultLocale: 'en', localesDir: './i18n' }));

// Development (automatic — DevPlugin wires I18nServicePlugin when translations are declared)
kernel.use(new DevPlugin());

Discovery & Handler Consistency

The Discovery API (/api/v1 or /.well-known/objectstack) and the i18n route handler (/api/v1/i18n/*) both use the same async resolution chain to detect i18n availability:

getServiceAsync() → getService() → context.getService() → services Map

This ensures that discovery.services.i18n.status always matches the actual runtime behavior — a service registered via any mechanism (sync Map, async factory, or context) will be reported correctly in both places.

The locale field in the discovery response is populated from the actual i18n service:

• locale.default — from i18nService.getDefaultLocale() (falls back to 'en')
• locale.supported — from i18nService.getLocales() (falls back to [default])

AppPlugin Auto-Loading

When an app bundle includes an i18n config and translations array, AppPlugin automatically loads the translation data into the i18n service during the start phase:

export default defineStack({
  manifest: { id: 'com.example.crm', namespace: 'crm' },
  i18n: { defaultLocale: 'en', supportedLocales: ['en', 'zh-CN'] },
  translations: [CrmTranslations],   // TranslationBundle[]
});

AppPlugin will:

1. Set the default locale via i18nService.setDefaultLocale()
2. Call i18nService.loadTranslations(locale, data) for each locale in every bundle
3. Skip gracefully if no i18n service is registered (no errors, just a debug log)

REST API Endpoints

11–15. Infrastructure Services

cache, queue, and job are core services: like i18n, the kernel auto-injects an in-memory fallback when no plugin registers them (see CORE_FALLBACK_FACTORIES in packages/core/src/fallbacks/). The optional services (file-storage, search) stay disabled until a plugin provides them.

Roadmap Status

The three-phase build-out this page used to propose has landed, under package names that are service-* more often than plugin-*. Use the real names — a remedy naming a package that cannot be installed is a dead end, which is why CORE_SERVICE_PROVIDER is CI-checked against the workspace.

Shipped

Still open

The workflow slot used to sit in this table ("nothing ships, no consumer"). It was retired outright in v17 (#4451, per ADR-0115 Evidence 5): the capability lives in state_machine validation rules, approval flow nodes (ADR-0019) and record_change flows, so there is nothing left for a slot to promise.

Plugin Implementation Pattern

import type { Plugin } from '@objectstack/core';
import type { IDataEngine } from '@objectstack/spec/contracts';

let authService: AuthServiceImpl;

export const authPlugin: Plugin = {
  // Plugin names are reverse-domain (e.g. 'com.objectstack.auth'),
  // not the npm package name.
  name: 'com.example.auth',

  // ADR-0116 — declare what init() needs and what it unconditionally
  // registers, so a misordering is a named boot error instead of a crash.
  requiresServices: ['data'],
  providesServices: ['auth'],

  async init(ctx) {
    // Register the 'auth' CoreServiceName value
    const engine = ctx.getService<IDataEngine>('data');
    authService = new AuthServiceImpl(engine);
    ctx.registerService('auth', authService);
  },

  async start(ctx) {
    // Late-bind anything that must wait for every plugin to be up.
    // (There is no `onReady()` on IAuthService — that is your own type's API.)
    ctx.hook('kernel:ready', async () => {
      await authService.connect();
    });
  },

  // destroy() takes no arguments — capture what you need in module scope
  async destroy() {
    await authService.shutdown();
  },
};

When a plugin registers a service, the discovery endpoint automatically updates:

• services.auth.enabled → true, status → "available", handlerReady → true, route → "/api/v1/auth" (unless the instance self-declares stub/degraded via __serviceInfo, which is reported verbatim instead)
• routes.auth → "/api/v1/auth" appears in routes
• features flags follow for the slots that have one — search, files, analytics, ai, workflow, notifications, i18n (websockets is hardcoded false; there is no features.auth)

Next Steps