Kernel Services Checklist

The ObjectStack protocol defines 17 kernel services registered via the CoreServiceName enum. Each service maps to a set of protocol methods (57 total), governed by the ObjectStackProtocol interface.

Key architecture principle: The kernel itself only provides data and metadata (framework). Everything else — including auth and automation — is delivered by plugins. The current @objectstack/objectql package is an example kernel implementation to get the basic API running; production kernels will be rebuilt as new plugins.

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                     Kernel Layer                         │
│  ┌──────────────────┐  ┌──────────────────────────────┐ │
│  │  metadata (⚠️)   │  │  data + analytics (✅)       │ │
│  │  In-memory only   │  │  ObjectQL example kernel     │ │
│  │  DB persistence   │  │  Will be rebuilt as plugins  │ │
│  │  pending          │  │                              │ │
│  └──────────────────┘  └──────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│                    Plugin Layer                           │
│  All other services: auth, automation, workflow, ui,     │
│  realtime, notification, ai, i18n, graphql, search,     │
│  file-storage, cache, queue, job                         │
│                                                          │
│  Discovery API reports: enabled/unavailable/degraded     │
│  per service so clients adapt their UI accordingly       │
└─────────────────────────────────────────────────────────┘

Service Overview

1. metadata Service ⚠️ Framework

Service Name: metadata · Criticality: required
Implementation: Kernel — SchemaRegistry (in-memory)
Route Mounts: /api/v1/meta, /api/v1, /api/v1/packages

Protocol Methods

Current Limitations

The metadata service is a framework — it works with an in-memory SchemaRegistry loaded from YAML/TS config files at startup.

Discovery: Per-Service Status

The discovery endpoint returns a services map so clients know what is available:

{
  "services": {
    "metadata": {
      "enabled": true, "status": "degraded",
      "route": "/api/v1/meta", "provider": "kernel",
      "message": "In-memory registry; DB persistence pending"
    },
    "data": {
      "enabled": true, "status": "available",
      "route": "/api/v1/data", "provider": "kernel"
    },
    "auth": {
      "enabled": false, "status": "unavailable",
      "message": "Install an auth plugin to enable"
    }
  }
}

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 ✅ Implemented

Service Name: analytics · Criticality: optional
Implementation: @objectstack/objectql (driver-level capability)
Route Mount: /api/v1/analytics

Protocol Methods

Features

• Cube semantic queries: measures / dimensions / filters → ObjectQL aggregation
• Auto-generated metadata from SchemaRegistry (numeric → sum/avg, date → time dimensions)

4. auth Service ❌ Plugin Required

Service Name: auth · Criticality: required
Route Mount: /api/v1/auth — only exposed when a plugin registers the auth service

Plugin Requirements

The auth service covers both authentication (identity) and authorization (permissions). There is no separate permission service in CoreServiceName.

Spec Files: identity.zod.ts, role.zod.ts, organization.zod.ts, auth-config.zod.ts, tenant.zod.ts

5–7. Business Services ❌ Plugin Required

5. ui Service — 5 methods

listViews, getView, createView, updateView, deleteView
View CRUD, layout engine, action registry, permission filtering.

6. workflow Service — 5 methods

getWorkflowConfig, getWorkflowState, workflowTransition, workflowApprove, workflowReject
State machine engine, approval processes, audit trail.

7. automation Service — 1 method

triggerAutomation
Trigger engine, event triggers from ObjectQL hooks, flow executor, scheduled triggers.

8–11. Communication Services ❌ Plugin Required

8. realtime — 6 methods

realtimeConnect, realtimeDisconnect, realtimeSubscribe, realtimeUnsubscribe, setPresence, getPresence

9. notification — 7 methods

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

10. ai — 4 methods

aiNlq, aiChat, aiSuggest, aiInsights

11. i18n — 3 methods

getLocales, getTranslations, getFieldLabels

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

Service Registration

The i18n service is a core built-in service with automatic in-memory fallback. If no plugin registers the service, the kernel automatically injects an in-memory implementation during startup:

// Production (overrides built-in fallback)
kernel.use(new I18nServicePlugin({ defaultLocale: 'en', localesDir: './i18n' }));

// Development (automatic — DevPlugin registers i18n stub for all 17 core services)
kernel.use(new DevPlugin());

// No plugin required — kernel auto-injects in-memory fallback if none registered
const kernel = new ObjectKernel();
await kernel.bootstrap(); // i18n service available via built-in fallback

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

12–17. Infrastructure Services ❌ Plugin Required

Recommended Development Phases

Phase 1: Foundation (P0)

Phase 2: Business Engine (P1)

Phase 3: Advanced Capabilities (P2)

Plugin Implementation Pattern

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

export const authPlugin: Plugin = {
  name: 'plugin-auth',
  provides: ['auth'], // CoreServiceName value
  
  async init(ctx) {
    const engine = ctx.getService<IDataEngine>('data');
    const authService = new AuthServiceImpl(engine);
    ctx.registerService('auth', authService);
  },
  
  async start(ctx) {
    const auth = ctx.getService<IAuthService>('auth');
    await auth.onReady();
  },
  
  async stop(ctx) {
    const auth = ctx.getService<IAuthService>('auth');
    await auth.shutdown();
  },
};

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

• services.auth.enabled → true, status → "available", route → "/api/v1/auth"
• routes.auth → "/api/v1/auth" appears in routes
• features capability flags update accordingly

Next Steps