@xemahq/xema 0.1.4 → 0.2.0

package/dist/runtime/runner/helm-runner.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HelmRunner = void 0;
+const node_child_process_1 = require("node:child_process");
+const service_runner_1 = require("./service-runner");
+const DEFAULT_CHART_REPO = 'oci://registry.local/xema/charts';
+const DEFAULT_NAMESPACE = 'xema';
+const DEFAULT_WAIT_TIMEOUT = '5m';
+class HelmRunner {
+    opts;
+    kind = service_runner_1.ServiceRunnerKind.Helm;
+    bin;
+    namespace;
+    chartRepo;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.bin = opts.bin ?? 'helm';
+        this.namespace = opts.namespace ?? process.env.XEMA_NAMESPACE ?? DEFAULT_NAMESPACE;
+        this.chartRepo = opts.chartRepo ?? process.env.XEMA_CHART_REPO ?? DEFAULT_CHART_REPO;
+    }
+    async start(input) {
+        const { entry } = input;
+        const release = entry.name;
+        const args = [
+            'upgrade',
+            '--install',
+            release,
+            `${this.chartRepo}/${entry.name}`,
+            '--namespace',
+            this.namespace,
+            '--create-namespace',
+            '--wait',
+            '--timeout',
+            this.opts.waitTimeout ?? DEFAULT_WAIT_TIMEOUT,
+        ];
+        if (entry.imageTag) {
+            args.push('--set', `image.tag=${entry.imageTag}`);
+        }
+        if (entry.imageRef) {
+            args.push('--set', `image.repository=${entry.imageRef}`);
+        }
+        await this.helm(args);
+        const url = `http://${entry.name}.${this.namespace}.svc.cluster.local`;
+        return {
+            name: entry.name,
+            url,
+            handle: `helm:${release}`,
+            close: async () => {
+                await this.helm(['uninstall', release, '--namespace', this.namespace]).catch(() => undefined);
+            },
+        };
+    }
+    helm(args) {
+        const env = { ...process.env };
+        if (this.opts.kubeconfig) {
+            env.KUBECONFIG = this.opts.kubeconfig;
+        }
+        return new Promise((resolve, reject) => {
+            (0, node_child_process_1.execFile)(this.bin, [...args], { env, maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+                if (err) {
+                    reject(new Error(`${this.bin} ${args.join(' ')} failed: ${stderr || err.message}`));
+                    return;
+                }
+                resolve(stdout);
+            });
+        });
+    }
+}
+exports.HelmRunner = HelmRunner;
+//# sourceMappingURL=helm-runner.js.map

package/dist/runtime/runner/helm-runner.js.map

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

package/dist/runtime/runner/native-runner.d.ts

@@ -0,0 +1,9 @@
+import { ServiceRunnerKind, type RunningService, type ServiceRunner, type StartServiceInput } from './service-runner';
+export declare class NativeRunner implements ServiceRunner {
+    readonly kind = ServiceRunnerKind.Native;
+    private readonly monorepoRoot;
+    constructor(monorepoRoot?: string);
+    start(input: StartServiceInput): Promise<RunningService>;
+    private bootInProcess;
+}
+//# sourceMappingURL=native-runner.d.ts.map

package/dist/runtime/runner/native-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-runner.d.ts","sourceRoot":"","sources":["../../../src/runtime/runner/native-runner.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAqB1B,qBAAa,YAAa,YAAW,aAAa;IAChD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,YAAY,CAAC,EAAE,MAAM;IAW3B,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC;YAwChD,aAAa;CA6B5B"}

package/dist/runtime/runner/native-runner.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeRunner = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const forked_worker_1 = require("../../dev/forked-worker");
+const paths_1 = require("../paths");
+const health_probe_1 = require("./health-probe");
+const service_runner_1 = require("./service-runner");
+class NativeRunner {
+    kind = service_runner_1.ServiceRunnerKind.Native;
+    monorepoRoot;
+    constructor(monorepoRoot) {
+        const root = monorepoRoot ?? (0, paths_1.findMonorepoRoot)();
+        if (!root) {
+            throw new Error('NativeRunner requires a monorepo checkout (built service dist/ trees). ' +
+                'Run inside the monorepo, or use the container substrate.');
+        }
+        this.monorepoRoot = root;
+    }
+    async start(input) {
+        const { entry, env, port, readinessTimeoutMs } = input;
+        if (!entry.servicePath) {
+            throw new Error(`${entry.name}: no servicePath (platform-substrate service) — not bootable natively. ` +
+                `Use the container substrate for this service.`);
+        }
+        const serviceRoot = (0, node_path_1.join)(this.monorepoRoot, entry.servicePath);
+        const distMain = (0, node_path_1.join)(serviceRoot, 'dist', 'main.js');
+        if (!(0, node_fs_1.existsSync)(distMain)) {
+            throw new Error(`${entry.name} dist not found at ${distMain}. Run \`pnpm --filter ${entry.name} build\` first.`);
+        }
+        const needsFork = (0, node_fs_1.existsSync)((0, node_path_1.join)(serviceRoot, 'prisma', 'schema.prisma'));
+        applyEnv(env);
+        if (needsFork) {
+            const child = await (0, forked_worker_1.spawnForkedWorker)({
+                name: entry.name,
+                port,
+                siblingAppDir: serviceRoot,
+                readinessTimeoutMs,
+            }, '/');
+            return {
+                name: entry.name,
+                url: child.url,
+                handle: `pid:${String(child.pid)}`,
+                close: () => child.close(),
+            };
+        }
+        return this.bootInProcess(entry.name, serviceRoot, port, readinessTimeoutMs);
+    }
+    async bootInProcess(name, serviceRoot, port, readinessTimeoutMs) {
+        const appModulePath = (0, node_path_1.join)(serviceRoot, 'dist', 'app.module.js');
+        if (!(0, node_fs_1.existsSync)(appModulePath)) {
+            throw new Error(`${name} dist did not produce app.module.js at ${appModulePath}.`);
+        }
+        const bundle = requireCommonJs(appModulePath);
+        const nestCore = requireCommonJs(require.resolve('@nestjs/core'));
+        const app = await nestCore.NestFactory.create(bundle.AppModule, {
+            logger: ['error', 'warn', 'log'],
+            abortOnError: false,
+        });
+        await app.listen(port);
+        const url = await app.getUrl();
+        await (0, health_probe_1.waitForReady)(url, readinessTimeoutMs).catch(async (err) => {
+            await app.close();
+            throw err;
+        });
+        return {
+            name,
+            url,
+            handle: 'in-process',
+            close: () => app.close(),
+        };
+    }
+}
+exports.NativeRunner = NativeRunner;
+function applyEnv(env) {
+    for (const [k, v] of Object.entries(env)) {
+        process.env[k] = v;
+    }
+}
+function requireCommonJs(modulePath) {
+    const loaded = require(modulePath);
+    return loaded;
+}
+//# sourceMappingURL=native-runner.js.map

package/dist/runtime/runner/native-runner.js.map

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

package/dist/runtime/runner/service-runner.d.ts

@@ -0,0 +1,23 @@
+import type { RosterEntry } from '../roster';
+export interface RunningService {
+    readonly name: string;
+    readonly url: string;
+    readonly handle: string;
+    close(graceMs: number): Promise<void>;
+}
+export interface StartServiceInput {
+    readonly entry: RosterEntry;
+    readonly env: Readonly<Record<string, string>>;
+    readonly port: number;
+    readonly readinessTimeoutMs: number;
+}
+export declare enum ServiceRunnerKind {
+    Native = "native",
+    Container = "container",
+    Helm = "helm"
+}
+export interface ServiceRunner {
+    readonly kind: ServiceRunnerKind;
+    start(input: StartServiceInput): Promise<RunningService>;
+}
+//# sourceMappingURL=service-runner.d.ts.map

package/dist/runtime/runner/service-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-runner.d.ts","sourceRoot":"","sources":["../../../src/runtime/runner/service-runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAS7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,oBAAY,iBAAiB;IAC3B,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,IAAI,SAAS;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAOjC,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC1D"}

package/dist/runtime/runner/service-runner.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceRunnerKind = void 0;
+var ServiceRunnerKind;
+(function (ServiceRunnerKind) {
+    ServiceRunnerKind["Native"] = "native";
+    ServiceRunnerKind["Container"] = "container";
+    ServiceRunnerKind["Helm"] = "helm";
+})(ServiceRunnerKind || (exports.ServiceRunnerKind = ServiceRunnerKind = {}));
+//# sourceMappingURL=service-runner.js.map

package/dist/runtime/runner/service-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-runner.js","sourceRoot":"","sources":["../../../src/runtime/runner/service-runner.ts"],"names":[],"mappings":";;;AA6BA,IAAY,iBAIX;AAJD,WAAY,iBAAiB;IAC3B,sCAAiB,CAAA;IACjB,4CAAuB,CAAA;IACvB,kCAAa,CAAA;AACf,CAAC,EAJW,iBAAiB,iCAAjB,iBAAiB,QAI5B"}

package/dist/runtime/supervisor.d.ts

@@ -0,0 +1,46 @@
+import type { XemaConfig, Substrate } from './config/schema';
+import type { InfraPlan } from './infra/infra-plan';
+import type { RosterEntry } from './roster';
+import type { RunningService, ServiceRunner } from './runner/service-runner';
+import type { Wave } from './waves';
+export interface SupervisorOptions {
+    readonly roster: readonly RosterEntry[];
+    readonly waves: readonly Wave[];
+    readonly runner: ServiceRunner;
+    readonly config: XemaConfig;
+    readonly infra: InfraPlan;
+    readonly substrate: Substrate;
+    readonly ports: ReadonlyMap<string, number>;
+    readonly containerPort?: number;
+    readonly readinessTimeoutMs?: number;
+    readonly graceMs?: number;
+    readonly onEvent?: (event: LifecycleEvent) => void;
+}
+export interface LifecycleEvent {
+    readonly kind: 'wave-start' | 'service-starting' | 'service-ready' | 'service-skipped' | 'wave-complete';
+    readonly service?: string;
+    readonly wave?: number;
+    readonly tier?: string;
+    readonly detail?: string;
+}
+export interface SkippedService {
+    readonly name: string;
+    readonly reason: string;
+}
+export interface BringUpResult {
+    readonly running: readonly RunningService[];
+    readonly skipped: readonly SkippedService[];
+}
+export declare class Supervisor {
+    private readonly opts;
+    private readonly running;
+    private readonly skipped;
+    private readonly seeded;
+    constructor(opts: SupervisorOptions);
+    bringUp(): Promise<BringUpResult>;
+    private startMember;
+    shutdown(): Promise<void>;
+    get current(): readonly RunningService[];
+    private emit;
+}
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/runtime/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/runtime/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAG,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAUpC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EACT,YAAY,GACZ,kBAAkB,GAClB,eAAe,GACf,iBAAiB,GACjB,eAAe,CAAC;IACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC7C;AAMD,qBAAa,UAAU;IAKT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAEK,IAAI,EAAE,iBAAiB;IAW9C,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;YA+BzB,WAAW;IAWnB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B,IAAI,OAAO,IAAI,SAAS,cAAc,EAAE,CAEvC;IAED,OAAO,CAAC,IAAI;CAGb"}

package/dist/runtime/supervisor.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Supervisor = void 0;
+const env_seeder_1 = require("./env-seeder");
+const DEFAULT_READINESS_MS = 45_000;
+const DEFAULT_GRACE_MS = 5_000;
+const MANDATORY_TIER = 'kernel';
+class Supervisor {
+    opts;
+    running = [];
+    skipped = [];
+    seeded;
+    constructor(opts) {
+        this.opts = opts;
+        this.seeded = (0, env_seeder_1.seedEnv)({
+            config: opts.config,
+            infra: opts.infra,
+            roster: opts.roster,
+            substrate: opts.substrate,
+            ports: opts.ports,
+            ...(opts.containerPort !== undefined ? { containerPort: opts.containerPort } : {}),
+        });
+    }
+    async bringUp() {
+        const readinessTimeoutMs = this.opts.readinessTimeoutMs ?? DEFAULT_READINESS_MS;
+        for (const wave of this.opts.waves) {
+            this.emit({ kind: 'wave-start', wave: wave.index, tier: wave.tier });
+            const results = await Promise.allSettled(wave.members.map((entry) => this.startMember(entry, readinessTimeoutMs)));
+            for (let i = 0; i < results.length; i += 1) {
+                const member = wave.members[i];
+                const result = results[i];
+                if (!member || !result) {
+                    continue;
+                }
+                if (result.status === 'fulfilled') {
+                    this.running.push(result.value);
+                    this.emit({ kind: 'service-ready', service: member.name, detail: result.value.url });
+                }
+                else {
+                    const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+                    if (member.tier === MANDATORY_TIER) {
+                        await this.shutdown();
+                        throw new Error(`Mandatory service ${member.name} failed to start: ${reason}`);
+                    }
+                    this.skipped.push({ name: member.name, reason });
+                    this.emit({ kind: 'service-skipped', service: member.name, detail: reason });
+                }
+            }
+            this.emit({ kind: 'wave-complete', wave: wave.index, tier: wave.tier });
+        }
+        return { running: [...this.running], skipped: [...this.skipped] };
+    }
+    async startMember(entry, readinessTimeoutMs) {
+        this.emit({ kind: 'service-starting', service: entry.name, tier: entry.tier });
+        const port = this.opts.ports.get(entry.name);
+        if (port === undefined) {
+            throw new Error(`no port assigned for ${entry.name}`);
+        }
+        const env = { ...this.seeded.base, ...this.seeded.perService(entry) };
+        return this.opts.runner.start({ entry, env, port, readinessTimeoutMs });
+    }
+    async shutdown() {
+        const graceMs = this.opts.graceMs ?? DEFAULT_GRACE_MS;
+        for (const svc of [...this.running].reverse()) {
+            await svc.close(graceMs).catch(() => undefined);
+        }
+        this.running.length = 0;
+    }
+    get current() {
+        return [...this.running];
+    }
+    emit(event) {
+        this.opts.onEvent?.(event);
+    }
+}
+exports.Supervisor = Supervisor;
+//# sourceMappingURL=supervisor.js.map

package/dist/runtime/supervisor.js.map

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

package/dist/runtime/unit-type.d.ts

@@ -0,0 +1,9 @@
+export declare enum RuntimeUnitType {
+    Infra = "infra",
+    BootstrapJob = "bootstrap-job",
+    Service = "service",
+    Web = "web"
+}
+export declare const WEB_SERVICE_NAME = "xema-host-web";
+export declare function classifyService(name: string, tier: string): RuntimeUnitType;
+//# sourceMappingURL=unit-type.d.ts.map

package/dist/runtime/unit-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-type.d.ts","sourceRoot":"","sources":["../../src/runtime/unit-type.ts"],"names":[],"mappings":"AAiBA,oBAAY,eAAe;IACzB,KAAK,UAAU;IACf,YAAY,kBAAkB;IAC9B,OAAO,YAAY;IACnB,GAAG,QAAQ;CACZ;AAGD,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAOhD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAK3E"}

package/dist/runtime/unit-type.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEB_SERVICE_NAME = exports.RuntimeUnitType = void 0;
+exports.classifyService = classifyService;
+var RuntimeUnitType;
+(function (RuntimeUnitType) {
+    RuntimeUnitType["Infra"] = "infra";
+    RuntimeUnitType["BootstrapJob"] = "bootstrap-job";
+    RuntimeUnitType["Service"] = "service";
+    RuntimeUnitType["Web"] = "web";
+})(RuntimeUnitType || (exports.RuntimeUnitType = RuntimeUnitType = {}));
+exports.WEB_SERVICE_NAME = 'xema-host-web';
+function classifyService(name, tier) {
+    if (name === exports.WEB_SERVICE_NAME || tier === 'edge') {
+        return RuntimeUnitType.Web;
+    }
+    return RuntimeUnitType.Service;
+}
+//# sourceMappingURL=unit-type.js.map

package/dist/runtime/unit-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit-type.js","sourceRoot":"","sources":["../../src/runtime/unit-type.ts"],"names":[],"mappings":";;;AAgCA,0CAKC;AApBD,IAAY,eAKX;AALD,WAAY,eAAe;IACzB,kCAAe,CAAA;IACf,iDAA8B,CAAA;IAC9B,sCAAmB,CAAA;IACnB,8BAAW,CAAA;AACb,CAAC,EALW,eAAe,+BAAf,eAAe,QAK1B;AAGY,QAAA,gBAAgB,GAAG,eAAe,CAAC;AAOhD,SAAgB,eAAe,CAAC,IAAY,EAAE,IAAY;IACxD,IAAI,IAAI,KAAK,wBAAgB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACjD,OAAO,eAAe,CAAC,GAAG,CAAC;IAC7B,CAAC;IACD,OAAO,eAAe,CAAC,OAAO,CAAC;AACjC,CAAC"}

package/dist/runtime/waves.d.ts

@@ -0,0 +1,15 @@
+import type { BootGraph } from './boot-graph-loader';
+import type { RosterEntry } from './roster';
+export interface Wave {
+    readonly index: number;
+    readonly tier: string;
+    readonly members: readonly RosterEntry[];
+}
+export declare function deriveWaves(roster: readonly RosterEntry[], bootGraph?: BootGraph): Wave[];
+export declare function findWaveOrderViolations(waves: readonly Wave[], bootGraph: BootGraph): Array<{
+    service: string;
+    requires: string;
+    serviceTier: string;
+    requiresTier: string;
+}>;
+//# sourceMappingURL=waves.d.ts.map

package/dist/runtime/waves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waves.d.ts","sourceRoot":"","sources":["../../src/runtime/waves.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAY5C,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAYD,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,EAAE,CA8BzF;AAQD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,SAAS,EAAE,SAAS,GACnB,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CA2CzF"}

package/dist/runtime/waves.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveWaves = deriveWaves;
+exports.findWaveOrderViolations = findWaveOrderViolations;
+const DEFAULT_TIER_RANK = {
+    kernel: 0,
+    system: 1,
+    base: 2,
+    platform: 3,
+    edge: 4,
+};
+function deriveWaves(roster, bootGraph) {
+    const rank = (tier) => {
+        const fromGraph = bootGraph?.tiers[tier];
+        if (typeof fromGraph === 'number') {
+            return fromGraph;
+        }
+        const fromDefault = DEFAULT_TIER_RANK[tier];
+        if (typeof fromDefault === 'number') {
+            return fromDefault;
+        }
+        return Number.MAX_SAFE_INTEGER;
+    };
+    const byTier = new Map();
+    for (const entry of roster) {
+        const bucket = byTier.get(entry.tier);
+        if (bucket) {
+            bucket.push(entry);
+        }
+        else {
+            byTier.set(entry.tier, [entry]);
+        }
+    }
+    const orderedTiers = [...byTier.keys()].sort((a, b) => rank(a) - rank(b));
+    return orderedTiers.map((tier, index) => ({
+        index,
+        tier,
+        members: (byTier.get(tier) ?? []).slice().sort((a, b) => a.name.localeCompare(b.name)),
+    }));
+}
+function findWaveOrderViolations(waves, bootGraph) {
+    const tierOfService = new Map();
+    for (const wave of waves) {
+        for (const m of wave.members) {
+            tierOfService.set(m.name, wave.tier);
+        }
+    }
+    const rank = (tier) => typeof bootGraph.tiers[tier] === 'number' ? bootGraph.tiers[tier] : Number.MAX_SAFE_INTEGER;
+    const violations = [];
+    for (const wave of waves) {
+        for (const m of wave.members) {
+            const node = bootGraph.services.get(m.name);
+            if (!node) {
+                continue;
+            }
+            for (const req of node.startupRequires) {
+                if (bootGraph.infraServices.has(req)) {
+                    continue;
+                }
+                const reqTier = tierOfService.get(req);
+                if (reqTier === undefined) {
+                    continue;
+                }
+                if (rank(reqTier) >= rank(wave.tier)) {
+                    violations.push({
+                        service: m.name,
+                        requires: req,
+                        serviceTier: wave.tier,
+                        requiresTier: reqTier,
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}
+//# sourceMappingURL=waves.js.map

package/dist/runtime/waves.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/xema",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Xema OS global CLI (plan v4.3 §6 Phase J). Single binary day-0 onboarding: `npm i -g @xemahq/xema && xema dev` boots the whole stack; `xema biome scaffold` / `install` / `publish` / `lint` author and ship biomes; `xema run <capability>` invokes through the local capability-router. Multi-platform: works without pnpm or any monorepo clone.",
   "type": "commonjs",
   "main": "dist/cli.js",
@@ -8,7 +8,8 @@
     "xema": "./dist/cli.js"
   },
   "files": [
-    "dist/**/*"
+    "dist/**/*",
+    "xema.config.example.yaml"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -18,12 +19,14 @@
     "@nestjs/common": "11.1.13",
     "@nestjs/core": "11.1.13",
     "@nestjs/platform-express": "11.1.13",
-    "@xemahq/kernel-state-runtime": "^0.1.4",
-    "@xemahq/service-registry-nest": "^0.1.7",
+    "@xemahq/kernel-contracts": "^0.22.0",
+    "@xemahq/kernel-state-runtime": "^0.1.5",
+    "@xemahq/service-registry-nest": "^0.1.9",
     "commander": "^12.1.0",
     "reflect-metadata": "0.2.2",
     "rxjs": "7.8.2",
-    "yaml": "^2.6.1"
+    "yaml": "^2.6.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
@@ -39,8 +42,7 @@
     "ts-jest": "^29.4.9",
     "ts-node": "^10.9.2",
     "typescript": "5.9.3",
-    "typescript-eslint": "^8.56.1",
-    "@xemahq/kernel-contracts": "^0.13.0"
+    "typescript-eslint": "^8.56.1"
   },
   "pkg": {
     "scripts": [
@@ -58,9 +60,6 @@
     ],
     "outputPath": "dist/bin"
   },
-  "peerDependencies": {
-    "@xemahq/kernel-contracts": ">=0.13.0"
-  },
   "scripts": {
     "clean": "rm -rf dist",
     "build": "tsc -p tsconfig.json && node ./scripts/post-build.cjs",

package/xema.config.example.yaml

@@ -0,0 +1,45 @@
+# Xema launcher topology — copy to `xema.config.yaml` and edit.
+# Docs: https://xema.dev  |  CLI: `xema up`, `xema down`, `xema status`, `xema logs`.
+#
+# Every value shown is the default; delete what you don't override.
+
+edition: oss                     # which distribution edition to launch
+
+# ── backing infrastructure (BYO model) ───────────────────────────────────────
+# mode ∈ managed | external | disabled
+#   managed  — the launcher starts + owns it (and its data volume)
+#   external — you already run it; give the URL (launcher health-probes it)
+#   disabled — not run (only allowed for optional components)
+infra:
+  postgres:    { mode: managed }                 # mandatory
+  redis:       { mode: managed }                 # mandatory
+  etcd:        { mode: managed }                 # mandatory (service discovery)
+  keycloak:    { mode: managed }                 # mandatory (identity)
+  objectStore: { mode: managed }                 # mandatory (blobs/artifacts)
+  search:      { mode: managed }                 # optional (full-text / vectors)
+  fga:         { mode: managed }                 # optional (authorization ReBAC)
+  git:         { mode: disabled }                # optional (SCM integration)
+  temporal:    { mode: managed }                 # optional (durable workflows)
+  # Example BYO:
+  # keycloak: { mode: external, url: https://sso.example.com/realms/xema, realm: xema }
+  # objectStore: { mode: external, url: https://s3.example.com, secretRef: my-s3 }
+
+# ── application services ─────────────────────────────────────────────────────
+app:
+  substrate: container           # container | native | helm
+  include: [ all ]               # all | tier names (kernel/system/base/platform) | service names
+  exclude: []                    # service names to drop
+  features: []                   # curated capability bundles (union with include)
+  web:
+    enabled: false               # start the host-shell frontend (or use `xema up --web`)
+
+# ── persistence ──────────────────────────────────────────────────────────────
+state:
+  workspaces:
+    driver: docker_local         # docker_local (container) | host_path (native)
+
+# ── secrets the launcher must obtain (never dev-defaulted in production) ──────
+secrets:
+  OPENCODE_SERVER_PASSWORD: { from: prompt }
+  # DELEGATED_SESSION_JWT_PRIVATE_KEY: { from: file, path: ./keys/session.pem }
+  # LLM_PROVIDER_ANTHROPIC_API_KEY: { from: env }