System lifecycle — from boot to ready state

┌─────────────────────────────────────────────────────────────────┐
│ Phase 1: INITIALIZE                                             │
│  └─ Load environment variables                                  │
│  └─ Validate runtime requirements (Node.js version, memory)     │
│  └─ Initialize logging infrastructure                           │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 2: CONFIGURE                                              │
│  └─ Load configuration files (objectstack.config.yml)           │
│  └─ Merge config sources (env → file → defaults)                │
│  └─ Validate configuration schema                               │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 3: CONNECT                                                │
│  └─ Establish database connections (PostgreSQL, Redis)          │
│  └─ Run health checks                                           │
│  └─ Initialize connection pools                                 │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 4: LOAD PLUGINS                                           │
│  └─ Discover installed plugins                                  │
│  └─ Resolve dependency graph                                    │
│  └─ Load plugins in topological order                           │
│  └─ Execute onBoot() hooks                                      │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 5: REGISTER METADATA                                      │
│  └─ Register ObjectQL schemas (objects, fields)                 │
│  └─ Register ObjectUI layouts (views, dashboards)               │
│  └─ Register permissions and validation rules                   │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 6: START SERVICES                                         │
│  └─ Start event bus                                             │
│  └─ Start job scheduler                                         │
│  └─ Start audit logger                                          │
│  └─ Start HTTP server                                           │
└─────────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────────┐
│ Phase 7: READY                                                  │
│  └─ Mark instance as healthy                                    │
│  └─ Begin accepting requests                                    │
│  └─ Log boot time metrics                                       │
└─────────────────────────────────────────────────────────────────┘

import { ObjectKernel } from '@objectstack/core';
import { AppPlugin } from '@objectstack/runtime';
import { SqlDriver } from '@objectstack/driver-sql';
import stack from './objectstack.config';

const kernel = new ObjectKernel({
  defaultStartupTimeout: 60_000,
  gracefulShutdown: true,
  shutdownTimeout: 30_000,
});

kernel.use(new SqlDriver({ /* ... */ }));
kernel.use(new AppPlugin(stack));
await kernel.bootstrap();

// AppPlugin: degrades on engine-less kernels, but when the engine is
// composed it must never init first — and a non-empty bundle cannot
// register at all without the manifest service.
class AppPlugin implements Plugin {
  optionalDependencies = ['com.objectstack.engine.objectql'];
  requiresServices = ['manifest'];
  // ...
}

[2024-01-15T10:23:01.234Z] INFO  ObjectStack starting...
[2024-01-15T10:23:01.250Z] INFO  Phase 1: Initialize
[2024-01-15T10:23:01.251Z] INFO    ✓ Node.js v20.10.0
[2024-01-15T10:23:01.252Z] INFO    ✓ Memory: 2048 MB available
[2024-01-15T10:23:01.300Z] INFO  Phase 2: Configure
[2024-01-15T10:23:01.301Z] INFO    ✓ Loaded objectstack.config.yml
[2024-01-15T10:23:01.302Z] INFO    ✓ Merged 3 config sources
[2024-01-15T10:23:01.400Z] INFO  Phase 3: Connect
[2024-01-15T10:23:01.450Z] INFO    ✓ PostgreSQL connected (10 pool size)
[2024-01-15T10:23:01.460Z] INFO    ✓ Redis connected
[2024-01-15T10:23:01.500Z] INFO  Phase 4: Load Plugins
[2024-01-15T10:23:01.501Z] INFO    → @objectstack/core@2.0.0
[2024-01-15T10:23:01.550Z] INFO    → @mycompany/crm@1.5.0
[2024-01-15T10:23:01.600Z] INFO    → @vendor/salesforce@3.2.1
[2024-01-15T10:23:01.650Z] INFO    ✓ 3 plugins loaded
[2024-01-15T10:23:01.700Z] INFO  Phase 5: Register Metadata
[2024-01-15T10:23:01.701Z] INFO    ✓ 15 objects registered
[2024-01-15T10:23:01.702Z] INFO    ✓ 42 views registered
[2024-01-15T10:23:01.800Z] INFO  Phase 6: Start Services
[2024-01-15T10:23:01.850Z] INFO    ✓ Event bus started
[2024-01-15T10:23:01.900Z] INFO    ✓ Job scheduler started (5 jobs loaded)
[2024-01-15T10:23:01.950Z] INFO    ✓ HTTP server listening on :3000
[2024-01-15T10:23:02.000Z] INFO  Phase 7: Ready
[2024-01-15T10:23:02.001Z] INFO  ObjectStack ready in 766ms

[2024-01-15T10:23:01.500Z] ERROR Phase 4: Load Plugins
[2024-01-15T10:23:01.501Z] ERROR   ✗ @vendor/broken-plugin@1.0.0
[2024-01-15T10:23:01.502Z] ERROR   Dependency @objectstack/core@^3.0.0 not satisfied
[2024-01-15T10:23:01.503Z] ERROR   (Installed version: 2.0.0)
[2024-01-15T10:23:01.504Z] FATAL Boot failed. Exiting.

// Design sketch (ADR-0025). No `os` command runs this flow today.

async function installPlugin(packageName: string, version: string) {
  const transaction = await db.beginTransaction();
  
  try {
    // Step 1: Download and validate
    const manifest = await registry.download(packageName, version);
    await validateManifest(manifest);
    
    // Step 2: Dependency resolution
    await resolveDependencies(manifest.dependencies);
    
    // Step 3: Backup current state
    const backup = await createBackup();
    
    // Step 4: Run pre-install hook
    await manifest.lifecycle.preInstall?.({ context, transaction });
    
    // Step 5: Apply schema changes (ObjectQL)
    for (const object of manifest.objects) {
      await ObjectQL.createOrUpdateObject(object, { transaction });
    }
    
    // Step 6: Register UI metadata (ObjectUI)
    for (const view of manifest.views) {
      await ObjectUI.registerView(view, { transaction });
    }
    
    // Step 7: Apply configuration defaults
    await ConfigStore.merge(manifest.defaultConfig, { transaction });
    
    // Step 8: Run post-install hook
    await manifest.lifecycle.postInstall?.({ context, transaction });
    
    // Step 9: Mark plugin as installed
    await PluginRegistry.markInstalled(packageName, version, { transaction });
    
    // Step 10: Commit transaction
    await transaction.commit();
    
    logger.info(`✓ Installed ${packageName}@${version}`);
    
  } catch (error) {
    // Rollback on any error
    await transaction.rollback();
    logger.error(`✗ Installation failed: ${error.message}`);
    throw error;
  }
}

# @mycompany/sales-cloud depends on:
dependencies:
  '@objectstack/core': '^2.0.0'
  '@mycompany/crm-base': '^1.0.0'
  '@vendor/email': '>=2.5.0 <3.0.0'

async function resolveDependencies(
  deps: Record<string, string>
): Promise<void> {
  for (const [pkg, versionRange] of Object.entries(deps)) {
    const installed = await PluginRegistry.getInstalled(pkg);
    
    if (!installed) {
      throw new Error(
        `Dependency ${pkg} is not installed. ` +
        `Install it first.`
      );
    }
    
    if (!semver.satisfies(installed.version, versionRange)) {
      throw new Error(
        `Dependency ${pkg}@${installed.version} does not satisfy ` +
        `required version ${versionRange}`
      );
    }
  }
}

// plugin.ts — a runtime plugin implements Plugin: `name` plus
// init / start / destroy. `init` is required; the other two are optional.
export class SalesforceSyncPlugin implements Plugin {
  name = 'plugin.salesforce-sync';
  version = '3.2.1';

  // Phase 1 — runs for every plugin, sequentially, in registration order.
  // Register services, schemas and routes here; other plugins' services
  // may not exist yet.
  async init(ctx: PluginContext) {
    if (!process.env.SALESFORCE_API_KEY) {
      throw new Error('Salesforce API key not configured');
    }
  }

  // Phase 2 — runs after EVERY plugin's init has completed, so every
  // registered service is resolvable. Begin actual work here.
  async start(ctx: PluginContext) {
    ctx.logger.info('Salesforce sync started');
  }

  // Shutdown — invoked in reverse registration order, and as rollback for
  // plugins already started when a later plugin's start() fails.
  async destroy() {
    /* stop timers, close connections */
  }
}

objectstack upgrade @vendor/salesforce --to 3.3.0

objectstack upgrade @vendor/salesforce --to 3.3.0 --strategy blue-green

objectstack upgrade @vendor/salesforce --to 3.3.0 --strategy rolling

// src/objects/salesforce_account.object.ts
import { ObjectSchema, Field } from '@objectstack/spec/data';

export default ObjectSchema.create({
  name: 'salesforce_account',
  sharingModel: 'private',
  label: 'Salesforce Account',
  fields: {
    salesforce_id: Field.text({ required: true, unique: 'global' }),
    account_name: Field.text(),
    last_sync: Field.datetime(),
  },
});

os generate migration               # → migrations/<timestamp>_migration.ts
os generate migration --format sql  # → migrations/<timestamp>_migration.sql
os generate migration --dry-run     # Preview without writing

// migrations/20260101000000_migration.ts — auto-generated
export async function up(db: any): Promise<void> {
  await db.schema.createTable('salesforce_account', (t: any) => {
    t.string('id').primary();
    t.string('salesforce_id').notNullable().unique();
    t.string('account_name');
    t.datetime('last_sync');
  });
}

export async function down(db: any): Promise<void> {
  await db.schema.dropTable('salesforce_account');
}

[2024-01-15T10:30:00.000Z] INFO  Starting upgrade: 3.2.1 → 3.3.0
[2024-01-15T10:30:01.000Z] INFO  [1/3] Running migration 005_add_column...
[2024-01-15T10:30:01.500Z] ERROR Migration failed: column "account_name" already exists
[2024-01-15T10:30:01.501Z] WARN  Rolling back migration 005...
[2024-01-15T10:30:02.000Z] INFO  ✓ Rollback complete
[2024-01-15T10:30:02.001Z] INFO  Restoring previous version from backup...
[2024-01-15T10:30:03.000Z] INFO  ✓ Restored to version 3.2.1

[2024-01-15T10:30:00.000Z] INFO  Upgrade complete, validating...
[2024-01-15T10:30:01.000Z] INFO  Running health checks...
[2024-01-15T10:30:02.000Z] ERROR Health check failed: /api/health returned 500
[2024-01-15T10:30:02.001Z] WARN  Automatic rollback initiated
[2024-01-15T10:30:05.000Z] INFO  ✓ Rolled back to version 3.2.1

GET /health
  → 200 { success: true, data: { status: "ok", timestamp, version, uptime } }
        if the process is alive (liveness)
  → never fails on a dependency — see below

GET /ready
  → 200 { success: true, data: { status: "ready", state } } when the kernel is
        running AND every data driver answers (readiness)
  → 503 while still booting or shutting down
  → 503 carrying { state, drivers: [...] } in error.details when a data driver
        stops answering

{
  "success": true,
  "data": {
    "status": "ok",
    "timestamp": "2024-01-15T11:00:00.000Z",
    "version": "<the serving artifact's version>",
    "uptime": 3600
  }
}

import { PluginHealthMonitor } from '@objectstack/core';
import { PluginHealthCheckSchema } from '@objectstack/spec/kernel';

// 1. The plugin side — a plain method, invoked with NO arguments.
export const salesforcePlugin = {
  name: '@vendor/salesforce',

  // The name is free; `checkMethod` below is what points at it.
  async healthCheck() {
    try {
      await salesforce.query('SELECT Id FROM Account LIMIT 1');
      return true;
    } catch (error) {
      return { status: 'unhealthy', message: error.message };
    }
  },
};

// 2. The host side — the embedding application owns the monitor.
const monitor = new PluginHealthMonitor(kernel.logger);

// `registerPlugin` takes the PARSED config, so parse it: the schema fills in
// intervalMs 30000, timeoutMs 5000, failureThreshold 3 and successThreshold 1.
monitor.registerPlugin(
  salesforcePlugin.name,
  PluginHealthCheckSchema.parse({ checkMethod: 'healthCheck' }),
);

monitor.startMonitoring(salesforcePlugin.name, salesforcePlugin);

{
  "status": "healthy",
  "timestamp": "2024-01-15T11:00:00.000Z",
  "metrics": {
    "uptimeMs": 3600000
  },
  "checks": [
    { "name": "healthCheck", "status": "passed" }
  ]
}

SIGTERM received
  ↓
[1] Stop accepting new requests
  ↓
[2] Finish in-flight requests (timeout: 30s)
  ↓
[3] Stop background jobs
  ↓
[4] Close database connections
  ↓
[5] Flush audit logs
  ↓
[6] Exit process

import { ObjectKernel } from '@objectstack/core';

const kernel = new ObjectKernel({
  // Enable graceful shutdown on SIGTERM / SIGINT
  gracefulShutdown: true,
  // Wait this long for in-flight work to drain before force-stopping
  shutdownTimeout: 30_000,
});

// ✓ GOOD: Use transaction
const tx = await db.beginTransaction();
try {
  await step1(tx);
  await step2(tx);
  await tx.commit();
} catch (error) {
  await tx.rollback();
}

// ✗ BAD: No transaction
await step1();
await step2(); // If this fails, step1 is not reverted!

// ✗ BAD: Modifying an existing migration file
// migrations/20260101000000_migration.ts (ALREADY APPLIED)
// Editing it here changes history that databases have already seen.

// ✓ GOOD: Generate a new migration after updating the object metadata
//   1. Edit src/objects/account.object.ts — add the new field
//   2. Run:  os generate migration
//   3. Commit  migrations/20260201000000_migration.ts

# Staging
# Design intent: `os` has no `upgrade` command
objectstack upgrade --dry-run  # Preview changes
objectstack upgrade            # Apply upgrade

# `os test` is real: it runs qa/*.test.json scenarios against a running server
os test --url https://staging.example.com

# If tests pass → Production (design intent)
objectstack upgrade --production

# Automated monitoring
objectstack upgrade @vendor/salesforce --monitor --duration 300
# Watches /health for 5 minutes, auto-rollback if unhealthy

## v4.0.0 (Breaking Changes)

### Removed
- `salesforce.sync()` method (use `salesforce.syncAccounts()` instead)

### Changed
- `salesforce_account.name` field renamed to `account_name`

### Migration Guide
1. Update code: `sync()` → `syncAccounts()`
2. Edit the relevant object metadata files
3. Run `os generate migration` and review the generated DDL
4. Apply via your usual Knex / driver pipeline