@theaiinc/yggdrasil 0.2.1 → 0.3.0

package/dist/src/services/realm-lifecycle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * RealmLifecycleService — handles Realm registration, heartbeat, and stale detection.
+ *
+ * Yggdrasil manages the lifecycle of Realm instances. Ratatoskr is the transport
+ * that relays messages from Realm to Yggdrasil — it never stores or decides on realm state.
+ *
+ * Lifecycle:
+ *   creating ──→ running ──→ unhealthy ──→ destroyed
+ *                    ↑            │
+ *                    └──── recover ┘
+ *
+ * Stale detection: if a realm has not heartbeated within the stale TTL,
+ * Yggdrasil marks it unhealthy automatically.
+ */
+import type { Realm, RealmRegistration, RealmHeartbeat, RealmDeregistration, RealmTemplateType } from '../types/index.js';
+import { RealmRegistry } from './realm-registry.js';
+export declare class RealmLifecycleService {
+    private readonly registry;
+    private readonly staleTtlMs;
+    private staleTimer;
+    private registered;
+    constructor(registry: RealmRegistry, staleTtlMs?: number);
+    /**
+     * Register a realm that has just come online.
+     * Transitions the realm from 'creating' → 'running' and sets its endpoints.
+     * If the realm is not yet in the registry (spawned by an external process),
+     * it is added directly.
+     */
+    registerRealm(registration: RealmRegistration, templateType: RealmTemplateType): Realm;
+    /**
+     * Process a realm heartbeat.
+     * Updates lastHeartbeat timestamp and recovers from unhealthy state.
+     */
+    heartbeatRealm(heartbeat: RealmHeartbeat): Realm | undefined;
+    /**
+     * Process a realm deregistration (intentional shutdown).
+     */
+    deregisterRealm(deregistration: RealmDeregistration): void;
+    /**
+     * Start stale detection timer.
+     * Checks all running realms periodically and marks stale ones as unhealthy.
+     */
+    startStaleDetection(): void;
+    /**
+     * Stop stale detection timer.
+     */
+    stopStaleDetection(): void;
+}
+//# sourceMappingURL=realm-lifecycle.d.ts.map

package/dist/src/services/realm-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/services/realm-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC1H,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOpD,qBAAa,qBAAqB;IAK9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,UAAU,CAAkB;gBAGjB,QAAQ,EAAE,aAAa,EACvB,UAAU,GAAE,MAA6B;IAG5D;;;;;OAKG;IACH,aAAa,CAAC,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,iBAAiB,GAAG,KAAK;IA+CtF;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,cAAc,GAAG,KAAK,GAAG,SAAS;IAmB5D;;OAEG;IACH,eAAe,CAAC,cAAc,EAAE,mBAAmB,GAAG,IAAI;IAiB1D;;;OAGG;IACH,mBAAmB,IAAI,IAAI;IA8B3B;;OAEG;IACH,kBAAkB,IAAI,IAAI;CAO3B"}

package/dist/src/services/realm-lifecycle.js

@@ -0,0 +1,154 @@
+/**
+ * RealmLifecycleService — handles Realm registration, heartbeat, and stale detection.
+ *
+ * Yggdrasil manages the lifecycle of Realm instances. Ratatoskr is the transport
+ * that relays messages from Realm to Yggdrasil — it never stores or decides on realm state.
+ *
+ * Lifecycle:
+ *   creating ──→ running ──→ unhealthy ──→ destroyed
+ *                    ↑            │
+ *                    └──── recover ┘
+ *
+ * Stale detection: if a realm has not heartbeated within the stale TTL,
+ * Yggdrasil marks it unhealthy automatically.
+ */
+import { getLogger } from './logger.js';
+const DEFAULT_STALE_TTL_MS = 60_000; // 60s without heartbeat → unhealthy
+const STALE_CHECK_INTERVAL_MS = 10_000; // check every 10s
+const logger = getLogger();
+export class RealmLifecycleService {
+    registry;
+    staleTtlMs;
+    staleTimer;
+    registered = false;
+    constructor(registry, staleTtlMs = DEFAULT_STALE_TTL_MS) {
+        this.registry = registry;
+        this.staleTtlMs = staleTtlMs;
+    }
+    /**
+     * Register a realm that has just come online.
+     * Transitions the realm from 'creating' → 'running' and sets its endpoints.
+     * If the realm is not yet in the registry (spawned by an external process),
+     * it is added directly.
+     */
+    registerRealm(registration, templateType) {
+        const now = new Date().toISOString();
+        const existing = this.registry.getRealm(registration.realmId);
+        if (existing) {
+            // Realm was pre-registered by RealmProvisioner — update it
+            existing.state = 'running';
+            existing.endpoints = registration.endpoints;
+            existing.lastHeartbeat = now;
+            existing.updatedAt = now;
+            logger.info('Realm registered (updated existing)', {
+                realmId: registration.realmId,
+                runnerId: registration.runnerId,
+                template: templateType,
+            });
+            return existing;
+        }
+        // Realm was spawned externally (e.g. manually) — add to registry
+        const realm = {
+            id: registration.realmId,
+            templateId: templateType,
+            runnerId: registration.runnerId,
+            state: 'running',
+            endpoints: { ...registration.endpoints },
+            createdAt: now,
+            updatedAt: now,
+            lastHeartbeat: now,
+        };
+        // Create a minimal template from registration data
+        const template = {
+            id: `${registration.realmId}-template`,
+            type: templateType,
+            capabilities: registration.capabilities,
+        };
+        this.registry.addRealm(realm, template);
+        logger.info('Realm registered (new)', {
+            realmId: registration.realmId,
+            runnerId: registration.runnerId,
+            template: templateType,
+        });
+        return realm;
+    }
+    /**
+     * Process a realm heartbeat.
+     * Updates lastHeartbeat timestamp and recovers from unhealthy state.
+     */
+    heartbeatRealm(heartbeat) {
+        const realm = this.registry.getRealm(heartbeat.realmId);
+        if (!realm) {
+            logger.warn('Heartbeat for unknown realm', { realmId: heartbeat.realmId });
+            return undefined;
+        }
+        realm.lastHeartbeat = new Date().toISOString();
+        realm.updatedAt = realm.lastHeartbeat;
+        // Recover from unhealthy state
+        if (realm.state === 'unhealthy' && heartbeat.healthy) {
+            realm.state = 'running';
+            logger.info('Realm recovered from unhealthy', { realmId: heartbeat.realmId });
+        }
+        return realm;
+    }
+    /**
+     * Process a realm deregistration (intentional shutdown).
+     */
+    deregisterRealm(deregistration) {
+        const realm = this.registry.getRealm(deregistration.realmId);
+        if (!realm) {
+            logger.warn('Deregistration for unknown realm', { realmId: deregistration.realmId });
+            return;
+        }
+        realm.state = 'destroyed';
+        realm.updatedAt = new Date().toISOString();
+        this.registry.removeRealm(deregistration.realmId);
+        logger.info('Realm deregistered', {
+            realmId: deregistration.realmId,
+            reason: deregistration.reason,
+        });
+    }
+    /**
+     * Start stale detection timer.
+     * Checks all running realms periodically and marks stale ones as unhealthy.
+     */
+    startStaleDetection() {
+        if (this.staleTimer)
+            return;
+        this.registered = true;
+        this.staleTimer = setInterval(() => {
+            const now = Date.now();
+            const stale = [];
+            for (const realm of this.registry.listRealms()) {
+                if (realm.state !== 'running')
+                    continue;
+                if (!realm.lastHeartbeat) {
+                    // No heartbeat yet — give it time
+                    continue;
+                }
+                const elapsed = now - new Date(realm.lastHeartbeat).getTime();
+                if (elapsed > this.staleTtlMs) {
+                    stale.push(realm.id);
+                }
+            }
+            for (const realmId of stale) {
+                this.registry.updateRealmState(realmId, 'unhealthy');
+                logger.warn('Realm marked unhealthy due to heartbeat timeout', {
+                    realmId,
+                    missedBy: `${Math.round((now - new Date(this.registry.getRealm(realmId)?.lastHeartbeat ?? now).getTime()) / 1000)}s`,
+                });
+            }
+        }, STALE_CHECK_INTERVAL_MS);
+    }
+    /**
+     * Stop stale detection timer.
+     */
+    stopStaleDetection() {
+        if (this.staleTimer) {
+            clearInterval(this.staleTimer);
+            this.staleTimer = undefined;
+        }
+        this.registered = false;
+    }
+}
+//# sourceMappingURL=realm-lifecycle.js.map

package/dist/src/services/realm-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-lifecycle.js","sourceRoot":"","sources":["../../../src/services/realm-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/src/services/realm-provisioner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * RealmProvisioner — ensures a realm exists for a given allocation decision.
+ *
+ * Yggdrasil decides. RealmProvisioner executes.
+ *
+ * If the allocation says "spawn", it sends a command to the runner (via
+ * Ratatoskr's task mechanism) to create the Realm container/VM and waits
+ * for the endpoints to be ready.
+ *
+ * If the allocation says "attach", it returns the existing realm.
+ *
+ * Future:
+ *   - Synchronous spawn via Ratatoskr task endpoint
+ *   - Pool management (pre-warm idle realms)
+ *   - Retry with backoff on failed spawns
+ *   - Veto check: if a runner rejects a spawn, fall through to next candidate
+ */
+import type { Realm, RealmAllocation } from '../types/index.js';
+import { RealmRegistry } from './realm-registry.js';
+export declare class RealmProvisioner {
+    private readonly registry;
+    constructor(registry: RealmRegistry);
+    /**
+     * Ensure a realm matching the allocation exists.
+     * Returns the realm (either existing or newly created).
+     */
+    ensureRealm(allocation: RealmAllocation, ownerId?: string): Promise<Realm>;
+    /**
+     * Create (or mark as creating) a new realm instance.
+     *
+     * In v1 this registers the realm in-memory with a 'creating' state.
+     * The async spawn happens when the runner acknowledges and reports back
+     * with the actual endpoints.
+     */
+    private spawnRealm;
+    /**
+     * Update realm endpoints and state (called when a runner reports back).
+     */
+    updateRealmEndpoints(realmId: string, state: Realm['state'], endpoints: Realm['endpoints']): void;
+    /**
+     * Destroy a realm instance.
+     */
+    destroyRealm(realmId: string): Promise<void>;
+}
+//# sourceMappingURL=realm-provisioner.d.ts.map

package/dist/src/services/realm-provisioner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-provisioner.d.ts","sourceRoot":"","sources":["../../../src/services/realm-provisioner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,aAAa;IAEpD;;;OAGG;IACG,WAAW,CAAC,UAAU,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;IAWhF;;;;;;OAMG;YACW,UAAU;IA4CxB;;OAEG;IACH,oBAAoB,CAClB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EACrB,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,GAC5B,IAAI;IASP;;OAEG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAKnD"}

package/dist/src/services/realm-provisioner.js

@@ -0,0 +1,102 @@
+/**
+ * RealmProvisioner — ensures a realm exists for a given allocation decision.
+ *
+ * Yggdrasil decides. RealmProvisioner executes.
+ *
+ * If the allocation says "spawn", it sends a command to the runner (via
+ * Ratatoskr's task mechanism) to create the Realm container/VM and waits
+ * for the endpoints to be ready.
+ *
+ * If the allocation says "attach", it returns the existing realm.
+ *
+ * Future:
+ *   - Synchronous spawn via Ratatoskr task endpoint
+ *   - Pool management (pre-warm idle realms)
+ *   - Retry with backoff on failed spawns
+ *   - Veto check: if a runner rejects a spawn, fall through to next candidate
+ */
+import { nanoid } from 'nanoid';
+export class RealmProvisioner {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    /**
+     * Ensure a realm matching the allocation exists.
+     * Returns the realm (either existing or newly created).
+     */
+    async ensureRealm(allocation, ownerId) {
+        if (allocation.action === 'attach' && allocation.realmId) {
+            const existing = this.registry.getRealm(allocation.realmId);
+            if (existing) {
+                return existing;
+            }
+        }
+        return this.spawnRealm(allocation, ownerId);
+    }
+    /**
+     * Create (or mark as creating) a new realm instance.
+     *
+     * In v1 this registers the realm in-memory with a 'creating' state.
+     * The async spawn happens when the runner acknowledges and reports back
+     * with the actual endpoints.
+     */
+    async spawnRealm(allocation, ownerId) {
+        const now = new Date().toISOString();
+        const realmId = `realm-${nanoid(12)}`;
+        const realm = {
+            id: realmId,
+            templateId: allocation.template.id,
+            runnerId: allocation.runnerId,
+            ...(ownerId !== undefined ? { ownerId } : {}),
+            state: 'creating',
+            endpoints: {
+                observation: '',
+                input: '',
+            },
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.registry.addRealm(realm, allocation.template);
+        // In a full implementation, this would send a command to the runner:
+        //   POST /runners/:runnerId/tasks
+        //   { type: "spawn_realm", template: template.type, realmId }
+        //
+        // The runner would Docker exec the realm container, wait for it,
+        // then POST back to Yggdrasil:
+        //   PATCH /api/v1/realms/:realmId
+        //   { state: "running", endpoints: { observation, input } }
+        //
+        // The runner may also veto by returning a failed task.
+        //
+        // For now, simulate a short spawn delay and set placeholder endpoints.
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        realm.state = 'running';
+        realm.endpoints = {
+            observation: `http://realm-placeholder:8542/api/v1/realms/${realmId}/capture`,
+            input: `http://realm-placeholder:8542/api/v1/realms/${realmId}`,
+        };
+        realm.updatedAt = new Date().toISOString();
+        return realm;
+    }
+    /**
+     * Update realm endpoints and state (called when a runner reports back).
+     */
+    updateRealmEndpoints(realmId, state, endpoints) {
+        this.registry.updateRealmState(realmId, state);
+        const entry = this.registry.getEntry(realmId);
+        if (entry) {
+            entry.realm.endpoints = endpoints;
+            entry.realm.updatedAt = new Date().toISOString();
+        }
+    }
+    /**
+     * Destroy a realm instance.
+     */
+    async destroyRealm(realmId) {
+        this.registry.updateRealmState(realmId, 'destroyed');
+        // In a full implementation, would send a destroy command to the runner.
+        this.registry.removeRealm(realmId);
+    }
+}
+//# sourceMappingURL=realm-provisioner.js.map

package/dist/src/services/realm-provisioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-provisioner.js","sourceRoot":"","sources":["../../../src/services/realm-provisioner.ts"],"names":[],"mappings":"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"}

package/dist/src/services/realm-registry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * RealmRegistry — stores Realm templates advertised by runners and Realm instances.
+ *
+ * Responsibilities:
+ *   - Tracks RealmTemplate[] per runner (what CAN be spawned)
+ *   - Tracks Realm[] (what IS running)
+ *   - Provides lookup by runner, template type, owner, and pool tag
+ *
+ * Yggdrasil is stateless-in-memory in v1. A future version may add
+ * FileSessionStore or database-backed persistence.
+ */
+import type { Realm, RealmTemplate } from '../types/index.js';
+export interface RealmRegistryEntry {
+    realm: Realm;
+    template: RealmTemplate;
+}
+export declare class RealmRegistry {
+    /** Runner ID → realm templates they advertise. */
+    private readonly templatesByRunner;
+    /** Realm ID → realm instance + its template. */
+    private readonly realms;
+    /**
+     * Register or update realm templates for a runner.
+     */
+    setTemplates(runnerId: string, templates: RealmTemplate[]): void;
+    /**
+     * Get templates for a specific runner.
+     */
+    getTemplates(runnerId: string): RealmTemplate[];
+    /**
+     * Get all templates across all runners that match a given template type.
+     */
+    getTemplatesByType(type: string): Array<{
+        runnerId: string;
+        template: RealmTemplate;
+    }>;
+    /**
+     * Remove templates for a runner (e.g. on deregistration).
+     */
+    removeTemplates(runnerId: string): void;
+    /**
+     * Register a new realm instance.
+     */
+    addRealm(realm: Realm, template: RealmTemplate): void;
+    /**
+     * Get a realm instance by ID.
+     */
+    getRealm(realmId: string): Realm | undefined;
+    /**
+     * Get realm + template by ID.
+     */
+    getEntry(realmId: string): RealmRegistryEntry | undefined;
+    /**
+     * Find a running realm by owner ID and template type (persistent realm affinity).
+     * This is how ownerId becomes a scheduling primitive.
+     */
+    findRealmByOwner(ownerId: string, templateType: string): Realm | undefined;
+    /**
+     * Find an idle realm in a pool (by template type, no owner).
+     */
+    findPooledRealm(templateType: string, poolTag?: string): Realm | undefined;
+    /**
+     * List all realm instances.
+     */
+    listRealms(): Realm[];
+    /**
+     * List realms for a specific runner.
+     */
+    listRealmsByRunner(runnerId: string): Realm[];
+    /**
+     * Update realm state.
+     */
+    updateRealmState(realmId: string, state: Realm['state']): void;
+    /**
+     * Remove a realm.
+     */
+    removeRealm(realmId: string): void;
+    /**
+     * Clear all state (useful for testing).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=realm-registry.d.ts.map

package/dist/src/services/realm-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-registry.d.ts","sourceRoot":"","sources":["../../../src/services/realm-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,aAAa,EAAmB,MAAM,mBAAmB,CAAC;AAE/E,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,qBAAa,aAAa;IACxB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAsC;IAExE,gDAAgD;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAIhE;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,IAAI;IAIhE;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,EAAE;IAI/C;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,CAAC;IAYtF;;OAEG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMvC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAIrD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAI5C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIzD;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAa1E;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAe1E;;OAEG;IACH,UAAU,IAAI,KAAK,EAAE;IAIrB;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,KAAK,EAAE;IAM7C;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI;IAQ9D;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIlC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId"}

package/dist/src/services/realm-registry.js

@@ -0,0 +1,136 @@
+/**
+ * RealmRegistry — stores Realm templates advertised by runners and Realm instances.
+ *
+ * Responsibilities:
+ *   - Tracks RealmTemplate[] per runner (what CAN be spawned)
+ *   - Tracks Realm[] (what IS running)
+ *   - Provides lookup by runner, template type, owner, and pool tag
+ *
+ * Yggdrasil is stateless-in-memory in v1. A future version may add
+ * FileSessionStore or database-backed persistence.
+ */
+export class RealmRegistry {
+    /** Runner ID → realm templates they advertise. */
+    templatesByRunner = new Map();
+    /** Realm ID → realm instance + its template. */
+    realms = new Map();
+    // ── Template management ──────────────────────────────────────────────
+    /**
+     * Register or update realm templates for a runner.
+     */
+    setTemplates(runnerId, templates) {
+        this.templatesByRunner.set(runnerId, templates);
+    }
+    /**
+     * Get templates for a specific runner.
+     */
+    getTemplates(runnerId) {
+        return this.templatesByRunner.get(runnerId) ?? [];
+    }
+    /**
+     * Get all templates across all runners that match a given template type.
+     */
+    getTemplatesByType(type) {
+        const results = [];
+        for (const [runnerId, templates] of this.templatesByRunner.entries()) {
+            for (const template of templates) {
+                if (template.type === type) {
+                    results.push({ runnerId, template });
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Remove templates for a runner (e.g. on deregistration).
+     */
+    removeTemplates(runnerId) {
+        this.templatesByRunner.delete(runnerId);
+    }
+    // ── Realm instance management ────────────────────────────────────────
+    /**
+     * Register a new realm instance.
+     */
+    addRealm(realm, template) {
+        this.realms.set(realm.id, { realm, template });
+    }
+    /**
+     * Get a realm instance by ID.
+     */
+    getRealm(realmId) {
+        return this.realms.get(realmId)?.realm;
+    }
+    /**
+     * Get realm + template by ID.
+     */
+    getEntry(realmId) {
+        return this.realms.get(realmId);
+    }
+    /**
+     * Find a running realm by owner ID and template type (persistent realm affinity).
+     * This is how ownerId becomes a scheduling primitive.
+     */
+    findRealmByOwner(ownerId, templateType) {
+        for (const [, entry] of this.realms.entries()) {
+            if (entry.realm.ownerId === ownerId &&
+                entry.template.type === templateType &&
+                (entry.realm.state === 'running' || entry.realm.state === 'paused')) {
+                return entry.realm;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Find an idle realm in a pool (by template type, no owner).
+     */
+    findPooledRealm(templateType, poolTag) {
+        for (const [, entry] of this.realms.entries()) {
+            if (entry.realm.state === 'running' &&
+                entry.template.type === templateType &&
+                entry.realm.ownerId === undefined) {
+                if (poolTag === undefined || entry.realm.poolTag === poolTag) {
+                    return entry.realm;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * List all realm instances.
+     */
+    listRealms() {
+        return Array.from(this.realms.values()).map((e) => e.realm);
+    }
+    /**
+     * List realms for a specific runner.
+     */
+    listRealmsByRunner(runnerId) {
+        return Array.from(this.realms.values())
+            .filter((e) => e.realm.runnerId === runnerId)
+            .map((e) => e.realm);
+    }
+    /**
+     * Update realm state.
+     */
+    updateRealmState(realmId, state) {
+        const entry = this.realms.get(realmId);
+        if (entry) {
+            entry.realm.state = state;
+            entry.realm.updatedAt = new Date().toISOString();
+        }
+    }
+    /**
+     * Remove a realm.
+     */
+    removeRealm(realmId) {
+        this.realms.delete(realmId);
+    }
+    /**
+     * Clear all state (useful for testing).
+     */
+    clear() {
+        this.templatesByRunner.clear();
+        this.realms.clear();
+    }
+}
+//# sourceMappingURL=realm-registry.js.map

package/dist/src/services/realm-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-registry.js","sourceRoot":"","sources":["../../../src/services/realm-registry.ts"],"names":[],"mappings":"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"}

package/dist/src/services/realm-scheduler.d.ts

@@ -0,0 +1,47 @@
+/**
+ * RealmScheduler — makes allocation decisions for session requests.
+ *
+ * Yggdrasil owns all scheduling policy:
+ *   - Which realm type?
+ *   - Which owner?
+ *   - Reuse allowed?
+ *   - Spawn allowed?
+ *   - Priority?
+ *
+ * Ratatoskr reports facts (CPU, memory, realms, templates).
+ * Yggdrasil decides. Ratatoskr may veto ("I cannot do that") but
+ * must never suggest alternatives — that is orchestration.
+ *
+ * Current implementation:
+ *   Simple first-fit by template match + online status.
+ *
+ * Future:
+ *   Resource-aware, owner-aware, cost-aware, affinity-aware,
+ *   informed by Ratatoskr's /state endpoint.
+ */
+import type { CreateSessionRequest, RealmAllocation, SessionCapability, RunnerInfo } from '../types/index.js';
+import { RealmRegistry } from './realm-registry.js';
+export declare class RealmScheduler {
+    private readonly registry;
+    private readonly getRunner;
+    constructor(registry: RealmRegistry, getRunner: (runnerId: string) => RunnerInfo | undefined);
+    /**
+     * Decide how to allocate a realm for a session request.
+     *
+     * Yggdrasil decides:
+     *   - Which runner
+     *   - Which template
+     *   - Whether to spawn new or attach to existing
+     *
+     * Priority order:
+     *   1. Attach to existing realm owned by this owner (persistent realm)
+     *   2. Attach to a pooled idle realm (pre-warmed)
+     *   3. Spawn a new realm on a healthy runner
+     */
+    schedule(request: CreateSessionRequest): Promise<RealmAllocation>;
+    /**
+     * Resolve default capabilities for a template type when not explicitly provided.
+     */
+    static defaultCapabilitiesFor(type: string): SessionCapability[];
+}
+//# sourceMappingURL=realm-scheduler.d.ts.map

package/dist/src/services/realm-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-scheduler.d.ts","sourceRoot":"","sources":["../../../src/services/realm-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAoBpD,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS;IAG1E;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAqDvE;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE;CAGjE"}