Kernel: The System Protocol

┌──────────────────────────────────────────────────────────────────┐
│                     Application Layer                            │
│  ObjectQL (Data) + ObjectUI (Interface) + Business Logic         │
└─────────────────────────┬────────────────────────────────────────┘
                          │
┌─────────────────────────▼────────────────────────────────────────┐
│                        Kernel                                    │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐   │
│  │ Lifecycle Mgmt │  │ Plugin Registry │  │ Config Resolver  │   │
│  │  Boot/Install  │  │  Dependencies   │  │  Merge Strategy  │   │
│  │    Upgrade     │  │   Versioning    │  │  Multi-tenant    │   │
│  └────────────────┘  └────────────────┘  └──────────────────┘   │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐   │
│  │  i18n Engine   │  │  Event Bus     │  │  Job Scheduler   │   │
│  │  Translations  │  │  Pub/Sub       │  │  Cron/Interval   │   │
│  └────────────────┘  └────────────────┘  └──────────────────┘   │
│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐   │
│  │  Audit Logger  │  │  Secret Store  │  │  Tenant Isolator │   │
│  │  Change Track  │  │  Encryption    │  │  Multi-org       │   │
│  └────────────────┘  └────────────────┘  └──────────────────┘   │
└───────────────────────────────────────────────────────────────────┘
                          │
                ┌─────────┴─────────┐
                ▼                   ▼
        ┌──────────────┐    ┌──────────────┐
        │  PostgreSQL  │    │    Redis     │
        │   (Primary)  │    │   (Cache)    │
        └──────────────┘    └──────────────┘

# 47-step deployment runbook
1. Pull latest code
2. Run database migrations (hope they don't fail)
3. Update config.yaml (which version?)
4. Restart service 1, wait 30s
5. Restart service 2, wait 30s
...
47. Pray to the demo gods

# Publish a compiled artifact as a versioned package to ObjectOS Cloud
os package publish dist/objectstack.json --env <environment-id> --install
# ✓ Validated dependencies
# ✓ Applied schema changes
# ✓ Updated configuration
# ✓ Zero-downtime restart
# Done in 12 seconds.

// package.json
"dependencies": {
  "stripe": "^10.0.0",      // Need 10.x
  "accounting-plugin": "*",  // This needs stripe@9.x
  // 💥 Conflict! Manual resolution required.
}

# manifest block in objectstack.config.ts (via defineStack)
id: com.mycompany.billing
version: 2.0.0
dependencies:
  '@objectstack/core': '^2.0.0'
  'com.stripe.plugin': '>=10.0.0 <11.0.0'

// Where is the source of truth?
const apiKey = 
  process.env.API_KEY ||              // Environment variable
  config.get('stripe.apiKey') ||      // Config file
  tenant.settings.apiKey ||           // Database
  'fallback-key';                     // 💀 Hardcoded default

// One resolver, one precedence order — the `settings` service
// (SettingsService, registered by SettingsServicePlugin)
const settings = ctx.getService<any>('settings');
const { value, source, locked } = await settings.get('stripe', 'apiKey', {
  tenantId,
  userId,
});
// Cascade: OS_STRIPE_APIKEY (env) > global > tenant > user > registered default.
// `source` names the winning scope; `locked: true` means a higher scope pinned it
// (a write to a locked key throws SettingsLockedError).

// Manual boot — the pattern the Runtime wrapper in @objectstack/runtime automates
import { ObjectKernel } from '@objectstack/core';
import { AppPlugin, DriverPlugin } from '@objectstack/runtime';
import { ObjectQLPlugin } from '@objectstack/objectql';
import { SqlDriver } from '@objectstack/driver-sql';
import stack from './objectstack.config';

const kernel = new ObjectKernel();

// Phase 1 — driver (storage backend)
await kernel.use(new DriverPlugin(new SqlDriver({ /* ... */ }), 'default'));

// Phase 2 — ObjectQL data layer
await kernel.use(new ObjectQLPlugin());

// Phase 3 — application metadata (objects, views, apps, flows, agents…)
await kernel.use(new AppPlugin(stack));

// Phase 4 — host (HTTP via HonoServerPlugin, MCP via MCPServerPlugin; optional)
// await kernel.use(new HonoServerPlugin({ port: 3000 }));

// Phase 5 — start everything
await kernel.bootstrap();

// Incoming API request: GET /api/v1/data/account/123
//
// The transport plugin (HonoServerPlugin) hands the raw request to the REST
// layer, which resolves ONE identity envelope and threads it into the engine:

// 1. Identity — resolveExecutionContext() reads the better-auth session (or
//    API key), aggregates positions/permission sets/RLS membership, and layers
//    locale + timezone on top. It always resolves; anonymous yields
//    `{ isSystem: false, positions: [], permissions: [] }`.
const context = await resolveExecutionContext({ getService, getQl, request });
// → ExecutionContext { userId, tenantId, locale, timezone, positions,
//                      permissions, isSystem, ... }

// 2. Data — the context rides along as `context`, on the query itself or on
//    the engine's trailing options argument (the engine merges both). It is
//    what permissions and RLS are enforced against.
const ql = ctx.getService<any>('objectql');
const account = await ql.findOne('account', { where: { id: '123' }, context });

// Install a package: os package install com.vendor.salesforce-sync
// (the argument is a reverse-domain manifest id, or a path to a compiled
//  artifact JSON for an air-gapped install)
//
// A package is METADATA — no package code executes at install time.
// What actually happens:
//
// 1. Validate — manifest shape, engines.protocol compatibility (ADR-0025 §3.2),
//    artifact signature.
// 2. Register — registry.installPackage() gates the namespace and records
//    the InstalledPackage; the durable copy lands in `sys_packages` and is
//    rehydrated on every boot.
// 3. Materialize — metadata is hot-registered, `syncSchemas` applies the
//    schema, and declared side effects (translations, seed data) run.
//
// Executable members of an app bundle (`onEnable`, `functions`) run at BOOT,
// invoked by AppPlugin — installation only stores them.

// Manual steps
db.createTable('accounts');
db.addColumn('accounts', 'name', 'string');
permissions.grant('admin', 'accounts', 'read');
// Miss a step? System broken.

# objectstack.config.ts — declared via defineStack({ ... })
# `objects` is a list; each object's `fields` is a MAP keyed by snake_case name
objects:
  - name: account
    fields:
      name:
        type: text
# PermissionSet grants use allow* flags (not role/object/access)
permissions:
  - name: account_read
    objects:
      account:
        allowRead: true
# Kernel ensures runtime matches the declared metadata

# Scaffold new plugin (created under packages/plugins/plugin-<name>/)
os create plugin slack-integration

# Generated structure:
packages/plugins/plugin-slack-integration/
  package.json     # name, version, dependencies (@objectstack/spec, zod)
  tsconfig.json
  src/
    index.ts       # default-export Plugin object (name, version, initialize, destroy)
  README.md

// A plugin object may carry a Zod `configSchema` describing its settings.
// NOTE: the kernel RECORDS the schema but does not enforce it yet — `use()`
// takes no config argument, so the loader has nothing to parse and logs
// "config validation postponed" instead of running the schema. Treat
// `configSchema` as a declaration of shape, and validate values you actually
// depend on yourself.
export const slackPlugin: Plugin = {
  name: 'slack-integration',
  version: '0.1.0',
  configSchema: z.object({
    apiKey: z.string().describe('Slack API Key'),
    channel: z.string().default('#general'),
    enabled: z.boolean().default(true),
  }),
  async init(ctx) {
    // Runtime-resolved values come from the `settings` service, not from a
    // `config` object on the context — there is no `ctx.config`.
    const settings = ctx.getService<any>('settings');
    const { value: channel } = await settings.get('slack', 'channel', {});
  },
};

// Define translations
// i18n/en.json
{
  "slack.button.send": "Send to Slack",
  "slack.error.invalid_channel": "Channel {{channel}} not found"
}

// i18n/de.json
{
  "slack.button.send": "An Slack senden",
  "slack.error.invalid_channel": "Kanal {{channel}} nicht gefunden"
}

// Use in code — the i18n service is resolved from the registry, and the
// locale is an explicit argument (take it from the ExecutionContext).
const i18n = ctx.getService<II18nService>('i18n');
const message = i18n.t('slack.button.send', context.locale);
// t(key, locale, params?) interpolates {{params}} and falls back to the
// configured fallback locale, returning the key itself when nothing matches.