@nylorun/runtime 0.9.0-beta → 0.10.0-beta

package/dist/tenant/ephemeral.js

@@ -0,0 +1,156 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync, } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { createRequire } from "node:module";
+import { DatabaseSync } from "node:sqlite";
+import { newTenantId } from "@nylorun/core/compatibility";
+import { hashToken, mintBearerToken } from "../core/executors.js";
+import { createHost } from "../host/create-host.js";
+import { createKekFile } from "../vault/kek.js";
+import { createTenantModule } from "./module.js";
+import { createFsTenantStore } from "./store-fs.js";
+import { bootstrapPrincipal } from "./principals.js";
+import { createTenantLogger } from "./logger.js";
+import { hostPaths, tenantPaths } from "./paths.js";
+import { openTenantRuntime } from "./runtime.js";
+import { migrateTenantDatabase, readTenantConfig } from "./schema.js";
+const nodeRequire = createRequire(import.meta.url);
+function coreVersion() {
+    try {
+        return nodeRequire("@nylorun/core/package.json").version;
+    }
+    catch {
+        return "unknown";
+    }
+}
+function newHostId() {
+    return `host_${newTenantId().slice(3)}`;
+}
+/**
+ * Private Host on port 0 with one Tenant (D9 / A19).
+ * Exported from `@nylorun/runtime/core`.
+ */
+export async function startEphemeralRuntime(options) {
+    const hostRoot = options.hostRoot;
+    const paths = hostPaths(hostRoot);
+    mkdirSync(paths.home, { recursive: true });
+    mkdirSync(paths.tmp, { recursive: true });
+    mkdirSync(paths.tenants, { recursive: true });
+    mkdirSync(paths.trash, { recursive: true });
+    const hostId = newHostId();
+    const adminKey = options.adminKey ?? randomBytes(32).toString("hex");
+    const hostConfig = {
+        hostId,
+        host: "127.0.0.1",
+        port: 0,
+    };
+    const credentials = { adminKey };
+    writeFileSync(paths.config, `${JSON.stringify(hostConfig, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    writeFileSync(paths.credentials, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    const logger = options.logger ??
+        {
+            info() { },
+            warn() { },
+            error() { },
+        };
+    const baseline = options.baseline ?? {};
+    const model = options.model ?? { kind: "scripted", output: "ok" };
+    const configFor = (tenantId) => {
+        const tenant = tenantPaths(hostRoot, tenantId);
+        let sandboxBackend = options.sandboxBackend ?? "virtual";
+        if (existsSync(tenant.database)) {
+            try {
+                const db = new DatabaseSync(tenant.database, { readOnly: true });
+                try {
+                    const seeded = readTenantConfig(db).sandboxBackend;
+                    if (seeded)
+                        sandboxBackend = seeded;
+                }
+                finally {
+                    db.close();
+                }
+            }
+            catch {
+                /* unreadable — keep default */
+            }
+        }
+        return {
+            tenantId,
+            mode: "ephemeral",
+            paths: tenant,
+            sandbox: { backend: sandboxBackend },
+            model,
+            childEnv: Object.freeze({
+                ...baseline,
+                HOME: tenant.home,
+                TMPDIR: tenant.tmp,
+            }),
+            logger: createTenantLogger({
+                tenantId,
+                logPath: tenant.log,
+            }),
+        };
+    };
+    const openRuntime = (config) => openTenantRuntime(config, { createKekIfMissing: true });
+    const store = createFsTenantStore({
+        hostRoot,
+        openRuntime,
+        configFor,
+        logger,
+        writeBootstrap: (db, bootstrap) => {
+            migrateTenantDatabase(db);
+            bootstrapPrincipal(db, bootstrap);
+        },
+    });
+    const module = createTenantModule({
+        hostRoot,
+        store,
+        openRuntime,
+        configFor,
+        logger,
+    });
+    await module.start();
+    const tenantId = options.tenantId ?? newTenantId();
+    const applicationKey = options.applicationKey ?? mintBearerToken();
+    const principalId = options.principalId ?? `principal_${randomBytes(8).toString("hex")}`;
+    const credentialHash = hashToken(applicationKey);
+    await module.create({
+        tenantId,
+        name: options.name ?? "ephemeral",
+        principalId,
+        credentialHash,
+        idempotencyKey: `ephemeral-${tenantId}`,
+    });
+    // KEK for first vault write; openTenantRuntime also creates when hooks allow.
+    const kekPath = tenantPaths(hostRoot, tenantId).kek;
+    if (!existsSync(kekPath))
+        createKekFile(kekPath);
+    const host = createHost({
+        hostRoot,
+        module,
+        config: hostConfig,
+        credentials,
+        logger,
+        coreVersion: coreVersion(),
+    });
+    await host.listen();
+    let closed = false;
+    return {
+        url: host.url,
+        tenantId,
+        applicationKey,
+        adminKey,
+        principalId,
+        hostRoot,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await host.close();
+            await module.close();
+            if (!options.retainRoot)
+                rmSync(hostRoot, { recursive: true, force: true });
+        },
+    };
+}

package/dist/tenant/logger.d.ts

@@ -0,0 +1,9 @@
+import type { Logger } from "./types.js";
+/**
+ * Tenant logger (D12): JSON lines to `logs/tenant.log` with `tenantId` on every record.
+ * Never writes to the process stdout/stderr APIs.
+ */
+export declare function createTenantLogger(options: {
+    tenantId: string;
+    logPath: string;
+}): Logger;

package/dist/tenant/logger.js

@@ -0,0 +1,25 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Tenant logger (D12): JSON lines to `logs/tenant.log` with `tenantId` on every record.
+ * Never writes to the process stdout/stderr APIs.
+ */
+export function createTenantLogger(options) {
+    const { tenantId, logPath } = options;
+    mkdirSync(dirname(logPath), { recursive: true });
+    const write = (level, message, fields) => {
+        const record = {
+            ts: new Date().toISOString(),
+            level,
+            tenantId,
+            message,
+            ...(fields ?? {}),
+        };
+        appendFileSync(logPath, `${JSON.stringify(record)}\n`);
+    };
+    return {
+        info: (message, fields) => write("info", message, fields),
+        warn: (message, fields) => write("warn", message, fields),
+        error: (message, fields) => write("error", message, fields),
+    };
+}

package/dist/tenant/migration.d.ts

@@ -0,0 +1,16 @@
+import { DatabaseSync } from "node:sqlite";
+import type { TenantPaths } from "./types.js";
+import type { TenantEnvelope } from "@nylorun/core/contracts";
+export interface MigrationHooks {
+    schemaVersionOf?: (db: DatabaseSync) => number;
+    migrateTenantDatabase?: (db: DatabaseSync) => {
+        from: number;
+        to: number;
+    };
+    targetVersion?: number;
+}
+/**
+ * Checkpoint WAL, snapshot database + envelope + KEK, migrate, update envelope.
+ * On failure restore the snapshot, keep diagnostics, and throw migration-failed.
+ */
+export declare function migrateTenantWithSnapshot(paths: TenantPaths, envelope: TenantEnvelope, hooks?: MigrationHooks, now?: Date): TenantEnvelope;

package/dist/tenant/migration.js

@@ -0,0 +1,116 @@
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { TENANT_SCHEMA_VERSION, migrateTenantDatabase as defaultMigrate, schemaVersionOf as defaultSchemaVersionOf, } from "./schema.js";
+import { writeEnvelopeFile } from "./envelope.js";
+import { quarantine } from "./quarantine.js";
+function stamp(now) {
+    return now.toISOString().replaceAll(":", "-");
+}
+function copyIfPresent(from, to) {
+    if (existsSync(from))
+        copyFileSync(from, to);
+}
+/**
+ * Checkpoint WAL, snapshot database + envelope + KEK, migrate, update envelope.
+ * On failure restore the snapshot, keep diagnostics, and throw migration-failed.
+ */
+export function migrateTenantWithSnapshot(paths, envelope, hooks = {}, now = new Date()) {
+    const schemaVersionOf = hooks.schemaVersionOf ?? defaultSchemaVersionOf;
+    const migrateTenantDatabase = hooks.migrateTenantDatabase ?? defaultMigrate;
+    const target = hooks.targetVersion ?? TENANT_SCHEMA_VERSION;
+    const db = new DatabaseSync(paths.database);
+    let from;
+    try {
+        from = schemaVersionOf(db);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    if (from > target) {
+        db.close();
+        throw quarantine("schema-too-new", `Tenant schema version ${from} is newer than Host ${target}`, { tenantId: envelope.id });
+    }
+    if (from === target) {
+        db.close();
+        return envelope;
+    }
+    const dirName = `${from}-${target}-${stamp(now)}`;
+    mkdirSync(paths.migration, { recursive: true });
+    const snapshotDir = join(paths.migration, dirName);
+    mkdirSync(snapshotDir, { recursive: true });
+    try {
+        // Checkpoint WAL so the database file is self-contained (invariant 7).
+        db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+        db.close();
+        copyIfPresent(paths.database, join(snapshotDir, "tenant.sqlite"));
+        copyIfPresent(paths.envelope, join(snapshotDir, "tenant.json"));
+        copyIfPresent(paths.kek, join(snapshotDir, "vault-kek"));
+        // Side-car WAL/SHM if present.
+        copyIfPresent(`${paths.database}-wal`, join(snapshotDir, "tenant.sqlite-wal"));
+        copyIfPresent(`${paths.database}-shm`, join(snapshotDir, "tenant.sqlite-shm"));
+        const migrating = new DatabaseSync(paths.database);
+        let result;
+        try {
+            migrating.exec("BEGIN IMMEDIATE");
+            result = migrateTenantDatabase(migrating);
+            migrating.exec("COMMIT");
+        }
+        catch (error) {
+            try {
+                migrating.exec("ROLLBACK");
+            }
+            catch {
+                /* ignore */
+            }
+            migrating.close();
+            throw error;
+        }
+        migrating.close();
+        const updated = {
+            ...envelope,
+            schemaVersion: result.to,
+            updatedAt: now.toISOString(),
+        };
+        writeEnvelopeFile(paths.envelope, updated);
+        return updated;
+    }
+    catch (error) {
+        restoreSnapshot(paths, snapshotDir);
+        writeFileSync(join(snapshotDir, "failure.json"), `${JSON.stringify({
+            at: now.toISOString(),
+            message: error instanceof Error ? error.message : String(error),
+        }, null, 2)}\n`);
+        throw quarantine("migration-failed", error instanceof Error ? error.message : "migration failed", { tenantId: envelope.id, migrationPath: snapshotDir });
+    }
+}
+function restoreSnapshot(paths, snapshotDir) {
+    const dbSnap = join(snapshotDir, "tenant.sqlite");
+    const envSnap = join(snapshotDir, "tenant.json");
+    const kekSnap = join(snapshotDir, "vault-kek");
+    if (existsSync(dbSnap)) {
+        // Replace via temp rename so a partial copy cannot leave a half file.
+        const tmp = `${paths.database}.restore-tmp`;
+        copyFileSync(dbSnap, tmp);
+        renameSync(tmp, paths.database);
+    }
+    if (existsSync(envSnap)) {
+        const tmp = `${paths.envelope}.restore-tmp`;
+        copyFileSync(envSnap, tmp);
+        renameSync(tmp, paths.envelope);
+    }
+    if (existsSync(kekSnap)) {
+        const tmp = `${paths.kek}.restore-tmp`;
+        copyFileSync(kekSnap, tmp);
+        renameSync(tmp, paths.kek);
+    }
+    for (const side of ["-wal", "-shm"]) {
+        const snap = join(snapshotDir, `tenant.sqlite${side}`);
+        const dest = `${paths.database}${side}`;
+        if (existsSync(snap))
+            copyFileSync(snap, dest);
+        else if (existsSync(dest))
+            rmSync(dest, { force: true });
+    }
+}

package/dist/tenant/module.d.ts

@@ -0,0 +1,17 @@
+import { isQuarantineError, quarantine, TenantBusyError, TenantConflictError } from "./quarantine.js";
+import type { Logger, OpenTenantRuntime, TenantConfig, TenantModule, TenantStore } from "./types.js";
+export interface CreateTenantModuleOptions {
+    hostRoot: string;
+    store: TenantStore;
+    openRuntime: OpenTenantRuntime;
+    configFor: (tenantId: string) => TenantConfig;
+    logger: Logger;
+    openConcurrency?: number;
+    openTimeoutMs?: number;
+}
+/**
+ * Deep Tenant module (§8). Discovery, create, resolve, list, delete and
+ * summarize. Storage and Tenant Runtime are injected so WS-B tests without WS-A.
+ */
+export declare function createTenantModule(options: CreateTenantModuleOptions): TenantModule;
+export { TenantBusyError, TenantConflictError, isQuarantineError, quarantine, };

package/dist/tenant/module.js

@@ -0,0 +1,315 @@
+import { existsSync } from "node:fs";
+import { isTenantId } from "@nylorun/core/compatibility";
+import { TENANT_SCHEMA_VERSION } from "./schema.js";
+import { envelopeNow } from "./envelope.js";
+import { tenantPaths } from "./paths.js";
+import { mapPool, TimeoutError, withTimeout } from "./pool.js";
+import { asQuarantine, isQuarantineError, quarantine, TenantBusyError, TenantConflictError, } from "./quarantine.js";
+const OPEN_CONCURRENCY = 4;
+const OPEN_TIMEOUT_MS = 30_000;
+function hasLiveWork(summary) {
+    return (summary.runningSessions > 0 ||
+        summary.connectedExecutors > 0 ||
+        summary.pendingActions > 0);
+}
+function toAdmin(id, entry, envelope) {
+    if (!entry) {
+        return {
+            id,
+            name: envelope?.name ?? null,
+            state: "quarantined",
+            envelope,
+        };
+    }
+    if (entry.kind === "open") {
+        return {
+            id,
+            name: entry.handle.envelope.name,
+            state: "open",
+            envelope: entry.handle.envelope,
+        };
+    }
+    return {
+        id,
+        name: envelope?.name ?? null,
+        state: "quarantined",
+        envelope,
+    };
+}
+/**
+ * Deep Tenant module (§8). Discovery, create, resolve, list, delete and
+ * summarize. Storage and Tenant Runtime are injected so WS-B tests without WS-A.
+ */
+export function createTenantModule(options) {
+    const { hostRoot, store, logger, openConcurrency = OPEN_CONCURRENCY, openTimeoutMs = OPEN_TIMEOUT_MS, } = options;
+    // openRuntime / configFor are consumed by the store; kept on options for B1.
+    void options.openRuntime;
+    void options.configFor;
+    const entries = new Map();
+    let started = false;
+    let closed = false;
+    function rememberOpen(handle) {
+        entries.set(handle.envelope.id, { kind: "open", handle });
+    }
+    function rememberQuarantine(id, q) {
+        entries.set(id, { kind: "quarantined", quarantine: q });
+        logger.warn("tenant quarantined", {
+            tenantId: id,
+            code: q.code,
+            repair: q.repair,
+        });
+    }
+    async function openOne(id) {
+        const existing = entries.get(id);
+        if (existing?.kind === "open")
+            return;
+        try {
+            const handle = await withTimeout(store.open(id), openTimeoutMs, (late) => {
+                void late
+                    .then((h) => h.close())
+                    .catch(() => undefined);
+            });
+            rememberOpen(handle);
+        }
+        catch (error) {
+            if (error instanceof TimeoutError) {
+                rememberQuarantine(id, quarantine("open-timeout", `open timed out after ${openTimeoutMs}ms`, {
+                    tenantId: id,
+                }).toQuarantine());
+                return;
+            }
+            const q = asQuarantine(error);
+            if (q) {
+                rememberQuarantine(id, q);
+                return;
+            }
+            rememberQuarantine(id, quarantine("open-failed", error instanceof Error ? error.message : "open failed", { tenantId: id }).toQuarantine());
+        }
+    }
+    async function discoverId(id) {
+        if (entries.has(id))
+            return entries.get(id);
+        const paths = tenantPaths(hostRoot, id);
+        if (!existsSync(paths.root))
+            return undefined;
+        await openOne(id);
+        return entries.get(id);
+    }
+    const module = {
+        get started() {
+            return started;
+        },
+        async start() {
+            if (closed)
+                throw new Error("Tenant module is closed");
+            const ids = await store.enumerate();
+            await mapPool(ids, openConcurrency, async (id) => {
+                await openOne(id);
+            });
+            started = true;
+            logger.info("tenant module started", {
+                tenants: ids.length,
+                open: [...entries.values()].filter((e) => e.kind === "open").length,
+                quarantined: [...entries.values()].filter((e) => e.kind === "quarantined").length,
+            });
+        },
+        resolve(id) {
+            if (!isTenantId(id))
+                return { kind: "not-found" };
+            const entry = entries.get(id);
+            if (!entry) {
+                // Sync miss: existence check only (disk I/O allowed on miss). Full open
+                // happens on list()/status()/create(); Host sees opaque not-found until then.
+                try {
+                    const paths = tenantPaths(hostRoot, id);
+                    if (!existsSync(paths.root))
+                        return { kind: "not-found" };
+                }
+                catch {
+                    return { kind: "not-found" };
+                }
+                return { kind: "not-found" };
+            }
+            if (entry.kind === "open") {
+                return { kind: "open", handle: entry.handle };
+            }
+            return { kind: "quarantined", quarantine: entry.quarantine };
+        },
+        async create(input) {
+            if (!isTenantId(input.tenantId)) {
+                throw new Error(`Invalid tenant id: ${input.tenantId}`);
+            }
+            const bootstrap = {
+                principalId: input.principalId,
+                credentialHash: input.credentialHash,
+                idempotencyKey: input.idempotencyKey,
+            };
+            const envelope = envelopeNow({
+                id: input.tenantId,
+                name: input.name,
+                schemaVersion: TENANT_SCHEMA_VERSION,
+            });
+            let outcome;
+            try {
+                outcome = await store.create(envelope, bootstrap);
+            }
+            catch (error) {
+                await store.removePartial(input.tenantId).catch(() => undefined);
+                throw error;
+            }
+            if (outcome === "exists") {
+                const matches = await store.bootstrapMatches(input.tenantId, bootstrap);
+                if (!matches)
+                    throw new TenantConflictError();
+                const existing = await store.readEnvelope(input.tenantId);
+                const entry = entries.get(input.tenantId);
+                if (!entry || entry.kind !== "open") {
+                    await openOne(input.tenantId);
+                }
+                return { envelope: existing, created: false };
+            }
+            await openOne(input.tenantId);
+            const opened = entries.get(input.tenantId);
+            if (opened?.kind === "open") {
+                return { envelope: opened.handle.envelope, created: true };
+            }
+            // Created on disk but failed to open — still report the written envelope.
+            return { envelope, created: true };
+        },
+        async list() {
+            const ids = new Set(await store.enumerate());
+            for (const id of entries.keys())
+                ids.add(id);
+            const result = [];
+            for (const id of ids) {
+                if (!isTenantId(id))
+                    continue;
+                let entry = entries.get(id);
+                if (!entry) {
+                    await openOne(id);
+                    entry = entries.get(id);
+                }
+                let envelope = null;
+                try {
+                    envelope = await store.readEnvelope(id);
+                    if (envelope.id !== id) {
+                        rememberQuarantine(id, quarantine("envelope-invalid", `tenant.json id ${envelope.id} does not match directory ${id}`, { tenantId: id }).toQuarantine());
+                        entry = entries.get(id);
+                        envelope = null;
+                    }
+                }
+                catch (error) {
+                    const q = asQuarantine(error);
+                    if (q) {
+                        rememberQuarantine(id, q);
+                        entry = entries.get(id);
+                    }
+                    else {
+                        rememberQuarantine(id, quarantine("envelope-invalid", "tenant.json is unreadable", { tenantId: id }).toQuarantine());
+                        entry = entries.get(id);
+                    }
+                    envelope = null;
+                }
+                result.push(toAdmin(id, entry, envelope));
+            }
+            return result;
+        },
+        async status(id) {
+            if (!isTenantId(id))
+                return undefined;
+            let entry = entries.get(id);
+            if (!entry) {
+                entry = await discoverId(id);
+                if (!entry) {
+                    // Not in memory and not on disk.
+                    const known = (await store.enumerate()).includes(id);
+                    if (!known)
+                        return undefined;
+                    await openOne(id);
+                    entry = entries.get(id);
+                }
+            }
+            if (!entry)
+                return undefined;
+            let envelope = null;
+            try {
+                envelope =
+                    entry.kind === "open"
+                        ? entry.handle.envelope
+                        : await store.readEnvelope(id);
+            }
+            catch {
+                envelope = null;
+            }
+            const base = toAdmin(id, entry, envelope);
+            if (entry.kind === "quarantined") {
+                return { ...base, quarantine: entry.quarantine };
+            }
+            return base;
+        },
+        async delete(id, activeWork) {
+            if (!isTenantId(id))
+                throw new Error(`Invalid tenant id: ${id}`);
+            let entry = entries.get(id);
+            if (!entry) {
+                await discoverId(id);
+                entry = entries.get(id);
+            }
+            if (!entry) {
+                // Still on disk without an entry?
+                const ids = await store.enumerate();
+                if (!ids.includes(id)) {
+                    throw quarantine("open-failed", `Tenant ${id} not found`, {
+                        tenantId: id,
+                    });
+                }
+                await openOne(id);
+                entry = entries.get(id);
+            }
+            if (entry?.kind === "open") {
+                const summary = entry.handle.summary();
+                if (activeWork === "refuse" && hasLiveWork(summary)) {
+                    throw new TenantBusyError();
+                }
+                if (activeWork === "drain" || activeWork === "cancel") {
+                    await entry.handle.drain(activeWork);
+                }
+                // Sandbox prefix cleanup is owned by TenantHandle.close() (WS-A).
+                await entry.handle.close();
+            }
+            await store.trash(id, new Date());
+            entries.delete(id);
+            logger.info("tenant deleted", { tenantId: id, activeWork });
+        },
+        summarize() {
+            let runningSessions = 0;
+            let connectedExecutors = 0;
+            let pendingActions = 0;
+            let uncertainEffects = 0;
+            for (const entry of entries.values()) {
+                if (entry.kind !== "open")
+                    continue;
+                const s = entry.handle.summary();
+                runningSessions += s.runningSessions;
+                connectedExecutors += s.connectedExecutors;
+                pendingActions += s.pendingActions;
+                uncertainEffects += s.uncertainEffects;
+            }
+            return {
+                runningSessions,
+                connectedExecutors,
+                pendingActions,
+                uncertainEffects,
+            };
+        },
+        async close() {
+            closed = true;
+            started = false;
+            const open = [...entries.values()].filter((e) => e.kind === "open");
+            await Promise.all(open.map((e) => e.handle.close().catch(() => undefined)));
+            entries.clear();
+        },
+    };
+    return module;
+}
+export { TenantBusyError, TenantConflictError, isQuarantineError, quarantine, };

package/dist/tenant/paths.d.ts

@@ -0,0 +1,24 @@
+import type { TenantPaths } from "./types.js";
+export interface HostPaths {
+    root: string;
+    config: string;
+    state: string;
+    credentials: string;
+    log: string;
+    home: string;
+    tmp: string;
+    runtime: string;
+    tenants: string;
+    trash: string;
+}
+/** Host layout under NYLORUN_HOME / ~/.nylorun. */
+export declare function hostPaths(hostRoot: string): HostPaths;
+/**
+ * Absolute Tenant paths under `<hostRoot>/tenants/<tenantId>/`.
+ * Validates the id and asserts containment after realpath.
+ *
+ * Basenames frozen here for Wave 0 (design Rev 3 absent):
+ * `tenant.json`, `tenant.sqlite`, `.runtime-lock`, `vault-kek`,
+ * `home/`, `tmp/`, `.migration/`, `sandboxes/`, `plugin-data/`, `logs/tenant.log`.
+ */
+export declare function tenantPaths(hostRoot: string, tenantId: string): TenantPaths;