@nylorun/runtime 0.8.0-beta → 0.10.0-beta

package/dist/tenant/envelope.js

@@ -0,0 +1,54 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { TenantEnvelopeSchema, } from "@nylorun/core/contracts";
+import { quarantine } from "./quarantine.js";
+export function parseEnvelope(raw, expectedId) {
+    const parsed = TenantEnvelopeSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw quarantine("envelope-invalid", "tenant.json is missing or not a valid Tenant envelope", expectedId ? { tenantId: expectedId } : {});
+    }
+    if (expectedId !== undefined && parsed.data.id !== expectedId) {
+        throw quarantine("envelope-invalid", `tenant.json id ${parsed.data.id} does not match directory ${expectedId}`, { tenantId: expectedId });
+    }
+    return parsed.data;
+}
+export function readEnvelopeFile(path, expectedId) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            throw quarantine("envelope-invalid", "tenant.json is missing", expectedId ? { tenantId: expectedId } : {});
+        }
+        throw quarantine("corrupt", "tenant.json could not be read", expectedId ? { tenantId: expectedId } : {});
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        throw quarantine("envelope-invalid", "tenant.json is not valid JSON", expectedId ? { tenantId: expectedId } : {});
+    }
+    return parseEnvelope(json, expectedId);
+}
+/** Write envelope via temp sibling then rename (atomic on the same filesystem). */
+export function writeEnvelopeFile(envelopePath, envelope) {
+    const validated = parseEnvelope(envelope, envelope.id);
+    const tmp = join(envelopePath + `.tmp-${process.pid}-${Date.now()}`);
+    writeFileSync(tmp, `${JSON.stringify(validated, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    renameSync(tmp, envelopePath);
+}
+export function envelopeNow(input, now = new Date()) {
+    const iso = now.toISOString();
+    return {
+        id: input.id,
+        name: input.name,
+        createdAt: iso,
+        updatedAt: iso,
+        schemaVersion: input.schemaVersion,
+    };
+}

package/dist/tenant/ephemeral.d.ts

@@ -0,0 +1,31 @@
+import type { Logger, TenantModelConfig } from "./types.js";
+export interface StartEphemeralRuntimeOptions {
+    /** Absolute Host root. Caller creates any temporary directory. */
+    hostRoot: string;
+    tenantId?: string;
+    name?: string;
+    applicationKey?: string;
+    adminKey?: string;
+    principalId?: string;
+    /** Allowlisted baseline for childEnv (e.g. PATH). Never read from ambient here. */
+    baseline?: Readonly<Record<string, string>>;
+    model?: TenantModelConfig;
+    sandboxBackend?: "auto" | "microsandbox" | "virtual";
+    /** When true, close() leaves hostRoot on disk. */
+    retainRoot?: boolean;
+    logger?: Logger;
+}
+export interface EphemeralRuntime {
+    url: string;
+    tenantId: string;
+    applicationKey: string;
+    adminKey: string;
+    principalId: string;
+    hostRoot: string;
+    close(): Promise<void>;
+}
+/**
+ * Private Host on port 0 with one Tenant (D9 / A19).
+ * Exported from `@nylorun/runtime/core`.
+ */
+export declare function startEphemeralRuntime(options: StartEphemeralRuntimeOptions): Promise<EphemeralRuntime>;

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, };