use Beamreactor\CMDB\CMDB;

CMDB::install();  // Runs cmdb.sql — idempotent (CREATE IF NOT EXISTS)

// Business owner (a client)
$client_id = CMDB::createOwner('client', 'acme-corp', 'ACME Corporation',
    'https://acme.example.com/api',  // remote endpoint
    'admin@acme.com',
    ['contract' => 'PRO-2026', 'sla' => '99.9%'],  // metadata
    3  // trust level (high)
);

// Technical owner (ops team)
$ops_id = CMDB::createOwner('local', 'devops-team', 'DevOps Team');

// Generate and set (store the plain key, only the hash is saved)
$api_key = bin2hex(random_bytes(32));
CMDB::setOwnerApiKey($owner_id, $api_key);

// Verify later
if (CMDB::verifyOwnerApiKey($owner_id, $incoming_key))
{
    // Authenticated
}

CMDB::register(
    'plugin',                          // type
    'xchange',                         // name
    '1.0.0',                           // version
    'Marketplace plugin',              // description
    ['trading', 'rating', 'messaging'],// capabilities
    ['max_photos' => 5],              // config
    $client_id,                        // business owner
    $ops_id                            // technical owner
);

$id = CMDB::componentId('plugin', 'xchange');  // "plugin:xchange"
$parts = CMDB::parseComponentId($id);           // ['type' => 'plugin', 'name' => 'xchange']

CMDB::send(
    'plugin:xchange',       // source
    'plugin:messaging',     // target
    'xchange.first_contact',// channel
    [                        // payload (JSON)
        'buyer_id'   => 42,
        'seller_id'  => 7,
        'product_id' => 123,
        'message'    => 'Interested in your item'
    ],
    'notify',               // action (optional)
    CMDB::PRIORITY_NORMAL,  // priority (optional, default 5)
    3600,                   // TTL in seconds (optional, null = permanent)
    42                      // user_id (optional)
);

// Sender: create a request
$req = CMDB::request('plugin:xchange', 'plugin:messaging', 'xchange.first_contact', [
    'buyer_id' => 42,
    'seller_id' => 7,
]);
// $req = ['message_id' => 15, 'correlation_id' => 'a3f8...']

// Receiver: reply to it
CMDB::reply($req['message_id'], ['status' => 'conversation_opened']);

// Sender: check for responses
$responses = CMDB::getResponses($req['correlation_id'], 'plugin:xchange');

// Get all pending messages
$messages = CMDB::poll('plugin:messaging');

// Filter by channel pattern
$messages = CMDB::poll('plugin:messaging', 'xchange.%');

// Quick checks
if (CMDB::hasPending('plugin:messaging'))
{
    $count = CMDB::countPending('plugin:messaging');
}

// Set a flag
CMDB::setFlag($message_id, CMDB::FLAG_READ);

// Set multiple flags at once
CMDB::setFlag($message_id, CMDB::FLAG_ACK | CMDB::FLAG_PROCESSED);

// Clear a flag
CMDB::clearFlag($message_id, CMDB::FLAG_ERROR);

// Check flags (on a fetched message)
if (CMDB::hasFlag($msg['flags'], CMDB::FLAG_ACK))
{
    // Already acknowledged
}

// Shorthand: acknowledge = ACK + PROCESSED + status update
CMDB::acknowledge($message_id);

// Shorthand: mark as failed with error info
CMDB::fail($message_id, 'Connection timeout to remote API');

// Poll mode (default) — component fetches messages with poll()
CMDB::subscribe('plugin:messaging', 'xchange.*');

// Push mode — handler is called immediately when a matching message arrives
CMDB::subscribe('plugin:messaging', 'xchange.first_contact', 'push',
    'plugins/messaging/handlers/cmdb_push.handler.php'
);

// Both modes
CMDB::subscribe('plugin:monitoring', 'llm.*', 'both',
    'plugins/monitoring/handlers/cmdb_push.handler.php',
    null,  // source filter (null = all sources)
    3      // priority_min: only priority 1-3
);

<?php
// plugins/messaging/handlers/cmdb_push.handler.php
use Beamreactor\CMDB\CMDB;

$msg = CMDB::getMessage($cmdb_push_message_id);

if ($msg && $msg['channel'] === 'xchange.first_contact')
{
    // Create internal conversation between buyer and seller
    $payload = $msg['payload'];
    // ... create_conversation($payload['buyer_id'], $payload['seller_id']);

    CMDB::acknowledge($cmdb_push_message_id);
}
?>

// Run periodically (cron / scheduler)
$expired = CMDB::expireMessages();

// Delete processed/expired/failed messages older than 30 days
$deleted = CMDB::purge(30);

// Components that haven't sent a heartbeat in 30 minutes
$stale = CMDB::getStaleComponents(30);

foreach ($stale as $component)
{
    CMDB::setStatus($component['component_type'], $component['component_name'], 'degraded');
}

use Beamreactor\CMDB\CMDB;

// Register
CMDB::register('plugin', 'xchange', '1.0.0', 'Marketplace', ['trading', 'rating']);

// Subscribe to responses
CMDB::subscribe('plugin:xchange', 'xchange.*', 'push',
    'plugins/xchange/handlers/cmdb_push.handler.php'
);

// Heartbeat (if the plugin runs as a service)
CMDB::heartbeat('plugin', 'xchange');

// xchange triggers a messaging conversation
CMDB::send('plugin:xchange', 'plugin:messaging', 'xchange.first_contact', [
    'buyer_id'   => $buyer_id,
    'seller_id'  => $seller_id,
    'product_id' => $product_id,
    'subject'    => 'Interested in: ' . $product_title,
]);

// In a handler or cron job
$messages = CMDB::poll('plugin:xchange', 'messaging.%');

foreach ($messages as $msg)
{
    // Process
    CMDB::acknowledge($msg['id']);
}

plugins/xchange/sql/migrations/001_initial.sql
plugins/xchange/sql/migrations/002_add_trades_table.sql
plugins/xchange/sql/migrations/003_add_rating_index.sql
lib/cmdb/sql/migrations/001_initial.sql

-- Description: Add trades table and buyer/seller indexes
CREATE TABLE IF NOT EXISTS xchange_trades ( ... );

// Single component
$result = CMDB::migrate(
    'plugin',                                    // component type
    'xchange',                                   // component name
    'plugins/xchange/sql/migrations',            // migrations directory
    '1.2.0',                                     // current version (optional)
    'admin',                                     // who runs this
    'production'                                 // environment tag
);
// $result = ['applied' => 2, 'skipped' => 1, 'failed' => 0, 'errors' => []]

// All components at once (scans lib/*, plugins/*)
$results = CMDB::migrateAll('deploy-server', 'production');
// $results = ['plugin:xchange' => [...], 'lib:cmdb' => [...], ...]

// What migrations have been applied?
$status = CMDB::getMigrationStatus('plugin', 'xchange');
// Returns: migration_id, version, status, description, statements_count,
//          execution_time_ms, applied_by, environment, batch, applied_at

// What's pending?
$pending = CMDB::getPendingMigrations('plugin', 'xchange', 'plugins/xchange/sql/migrations');
// Returns: ['003_add_rating_index.sql']

$tampered = CMDB::verifyMigrationIntegrity();

foreach ($tampered as $t)
{
    echo $t['component'] . ' / ' . $t['file'] . ': ' . $t['issue'];
    // "plugin:xchange / 001_initial.sql: checksum_mismatch"
}

// Auto-run all pending migrations
$results = CMDB::migrateAll('devarea-deploy', 'production');

foreach ($results as $component => $r)
{
    if ($r['failed'] > 0)
    {
        // Alert: migration failed for $component
        error_log("Migration failed: $component — " . implode(', ', $r['errors']));
    }
}

                        ┌─────────────┐
                        │ cmdb_owners │
                        │ (sites,     │
                        │  clients)   │
                        └──────┬──────┘
                   business_owner_id │ technical_owner_id
                               │
┌──────────────┐       ┌──────┴──────┐       ┌───────────────────┐
│   Plugin A   │──send─▶│ cmdb_messages│◀─poll──│    Plugin B       │
│ (xchange)    │       │  (the bus)  │       │ (messaging)       │
└──────────────┘       └──────┬──────┘       └───────────────────┘
       │                      │                        ▲
       │               ┌──────┴──────┐                 │
       └──register────▶│cmdb_registry│    ┌────────────┴──────┐
                       │ (who exists)│    │cmdb_subscriptions │
                       └─────────────┘    │ (who listens)     │
                                          └───────────────────┘

// Owners
CMDB::createOwner($type, $name, $display, $url, $email, $meta, $trust);
CMDB::getOwnedComponents($owner_id, 'business');

// Registry
CMDB::register($type, $name, $version, $desc, $caps, $config, $biz_owner, $tech_owner);
CMDB::getComponent($type, $name);
CMDB::hasCapability($type, $name, 'rating');

// Messages
CMDB::send($source, $target, $channel, $payload, $action, $priority, $ttl);
CMDB::poll($target, $channel_filter);
CMDB::request($source, $target, $channel, $payload);
CMDB::reply($message_id, $payload);
CMDB::acknowledge($message_id);
CMDB::fail($message_id, $error);

// Subscriptions
CMDB::subscribe($subscriber, $pattern, 'push', $handler);
CMDB::unsubscribe($subscriber, $pattern);

// Maintenance
CMDB::expireMessages();
CMDB::purge(30);
CMDB::getStaleComponents(30);

// Migrations
CMDB::migrate($type, $name, $dir, $version, $who, $env);
CMDB::migrateAll($who, $env);
CMDB::getMigrationStatus($type, $name);
CMDB::getPendingMigrations($type, $name, $dir);
CMDB::verifyMigrationIntegrity();