@nylorun/runtime 0.9.0-beta → 0.11.0-beta

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/model-setting.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Tenant-level fixture model: Tenant setting `model.fixture`, seeded with
+ * `fixtureModel: true` (`PUT /v1/tenant/config/seed`, Host feature `tenant-fixture-model`).
+ * A Tenant with it answers every model call with the Runtime's deterministic fixture model
+ * (`core/provider.ts` `toolFixtureModel`) instead of its configured model, whatever the Host
+ * uses for other Tenants. Temporary test Tenants seed it (scripts/lib/temporary-tenant.mjs).
+ *
+ * The setting is read once per advance, in a transaction the advance makes anyway, so a Tenant
+ * seeded on another node takes it at its next advance.
+ */
+import type { Tx } from "../store/types.js";
+export declare const FIXTURE_MODEL_SETTING = "model.fixture";
+/** Whether the Tenant uses the fixture model. */
+export declare function usesFixtureModel(t: Tx): Promise<boolean>;
+/** Seeds the setting if absent. Returns whether it was inserted. */
+export declare function seedFixtureModel(t: Tx): Promise<boolean>;

package/dist/tenant/model-setting.js

@@ -0,0 +1,12 @@
+export const FIXTURE_MODEL_SETTING = "model.fixture";
+/** Whether the Tenant uses the fixture model. */
+export async function usesFixtureModel(t) {
+    return (await t.getSetting(FIXTURE_MODEL_SETTING)) === "true";
+}
+/** Seeds the setting if absent. Returns whether it was inserted. */
+export async function seedFixtureModel(t) {
+    if ((await t.getSetting(FIXTURE_MODEL_SETTING)) !== undefined)
+        return false;
+    await t.putSetting(FIXTURE_MODEL_SETTING, "true");
+    return true;
+}

package/dist/tenant/module.d.ts

@@ -0,0 +1,38 @@
+import { isQuarantineError, quarantine, TenantBusyError, TenantConflictError } from "./quarantine.js";
+import { TenantNotFoundError, TenantUnavailableError, type Logger, type OpenTenantRuntime, type TenantConfig, type TenantModule, type TenantStore } from "./types.js";
+export interface CreateTenantModuleOptions {
+    store: TenantStore;
+    /** Unused: the store derives paths. Accepted so callers can pass the store's options. */
+    hostRoot?: string;
+    /** Unused: the store opens Tenants. Accepted so callers can pass the store's options. */
+    openRuntime?: OpenTenantRuntime;
+    /** Unused; see `openRuntime`. */
+    configFor?: (tenantId: string) => TenantConfig;
+    logger: Logger;
+    /** Bound on one Tenant open; a slower open quarantines it with `open-timeout`. */
+    openTimeoutMs?: number;
+    /**
+     * Runs after a Tenant is created in the store, before it opens: creates what lives outside
+     * it (its Durable Streams basin). A failure is logged; opening the Tenant repairs it.
+     */
+    onCreated?: (tenantId: string) => Promise<void>;
+    /**
+     * Runs after a Tenant is removed from the store: removes what lives outside it (its
+     * Durable Streams basin, its armed sweep). A failure is logged; the Tenant stays deleted.
+     */
+    onDeleted?: (tenantId: string) => Promise<void>;
+}
+/**
+ * Deep Tenant module (§8): discovery, create, resolve, list, delete and summarize over an
+ * injected `TenantStore`.
+ *
+ * Handles open on demand and are cached (architecture §8.2). The first call that needs a
+ * Tenant (`resolve`, `status`, `worker`, `delete`) opens it once, even when several ask at
+ * the same time; a failed open is cached as a quarantine, and a missing Tenant is not
+ * cached. A failure outside the Tenant (`TenantUnavailableError`: the database is down, its
+ * sweep could not be armed) is thrown to the caller and not cached either, so the next use
+ * tries again. A Tenant being deleted resolves as not found, so a late request or Worker
+ * call cannot reopen it while its storage is removed.
+ */
+export declare function createTenantModule(options: CreateTenantModuleOptions): TenantModule;
+export { TenantBusyError, TenantConflictError, TenantNotFoundError, TenantUnavailableError, isQuarantineError, quarantine, };

package/dist/tenant/module.js

@@ -0,0 +1,319 @@
+import { isTenantId } from "@nylorun/core/compatibility";
+import { POSTGRES_SCHEMA_VERSION } from "../store/postgres/migrations/index.js";
+import { envelopeNow } from "./envelope.js";
+import { TimeoutError, withTimeout } from "./pool.js";
+import { asQuarantine, isQuarantineError, quarantine, TenantBusyError, TenantConflictError, } from "./quarantine.js";
+import { TenantNotFoundError, TenantUnavailableError, } from "./types.js";
+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?.kind === "open") {
+        return {
+            id,
+            name: entry.handle.envelope.name,
+            state: "open",
+            envelope: entry.handle.envelope,
+        };
+    }
+    return {
+        id,
+        name: envelope?.name ?? null,
+        state: entry ? "quarantined" : "open",
+        envelope,
+    };
+}
+/** The quarantine an open failure carries, from either quarantine error type. */
+function quarantineOf(error) {
+    const carried = error?.quarantine;
+    if (carried && typeof carried === "object" && "code" in carried)
+        return carried;
+    return asQuarantine(error);
+}
+/**
+ * Deep Tenant module (§8): discovery, create, resolve, list, delete and summarize over an
+ * injected `TenantStore`.
+ *
+ * Handles open on demand and are cached (architecture §8.2). The first call that needs a
+ * Tenant (`resolve`, `status`, `worker`, `delete`) opens it once, even when several ask at
+ * the same time; a failed open is cached as a quarantine, and a missing Tenant is not
+ * cached. A failure outside the Tenant (`TenantUnavailableError`: the database is down, its
+ * sweep could not be armed) is thrown to the caller and not cached either, so the next use
+ * tries again. A Tenant being deleted resolves as not found, so a late request or Worker
+ * call cannot reopen it while its storage is removed.
+ */
+export function createTenantModule(options) {
+    const { store, logger, openTimeoutMs = OPEN_TIMEOUT_MS } = options;
+    const entries = new Map();
+    const opening = new Map();
+    const deleting = new Set();
+    let started = false;
+    let closed = false;
+    function rememberQuarantine(id, q) {
+        const entry = { kind: "quarantined", quarantine: q };
+        entries.set(id, entry);
+        logger.warn("tenant quarantined", {
+            tenantId: id,
+            code: q.code,
+            repair: q.repair,
+        });
+        return entry;
+    }
+    async function openEntry(id) {
+        let handle;
+        try {
+            handle = await withTimeout(store.open(id), openTimeoutMs, (late) => {
+                void late.then((h) => h.close()).catch(() => undefined);
+            });
+        }
+        catch (error) {
+            if (error instanceof TenantNotFoundError)
+                return undefined;
+            if (closed || deleting.has(id))
+                return undefined;
+            if (error instanceof TenantUnavailableError) {
+                // Not the Tenant's fault: not cached, so the next use opens it again.
+                logger.warn("tenant unavailable", {
+                    tenantId: id,
+                    message: error.cause instanceof Error ? error.cause.message : String(error.cause),
+                });
+                throw error;
+            }
+            if (error instanceof TimeoutError)
+                return rememberQuarantine(id, quarantine("open-timeout", `open timed out after ${openTimeoutMs}ms`, {
+                    tenantId: id,
+                }).toQuarantine());
+            return rememberQuarantine(id, quarantineOf(error) ??
+                quarantine("open-failed", error instanceof Error ? error.message : "open failed", { tenantId: id }).toQuarantine());
+        }
+        if (closed || deleting.has(id)) {
+            await handle.close().catch(() => undefined);
+            return undefined;
+        }
+        const entry = { kind: "open", handle };
+        entries.set(id, entry);
+        return entry;
+    }
+    /** The cached entry, or the result of opening the Tenant once. */
+    async function load(id) {
+        if (deleting.has(id))
+            return undefined;
+        const cached = entries.get(id);
+        if (cached)
+            return cached;
+        if (closed)
+            return undefined;
+        let pending = opening.get(id);
+        if (!pending) {
+            pending = openEntry(id).finally(() => opening.delete(id));
+            opening.set(id, pending);
+        }
+        return pending;
+    }
+    const openEntries = () => [...entries.values()].filter((e) => e.kind === "open");
+    const module = {
+        get started() {
+            return started;
+        },
+        async start() {
+            if (closed)
+                throw new Error("Tenant module is closed");
+            const ids = await store.enumerate();
+            started = true;
+            logger.info("tenant module started", { tenants: ids.length });
+        },
+        async resolve(id) {
+            if (!isTenantId(id))
+                return { kind: "not-found" };
+            const entry = await load(id);
+            if (!entry)
+                return { kind: "not-found" };
+            if (entry.kind === "open")
+                return { kind: "open", handle: entry.handle };
+            return { kind: "quarantined", quarantine: entry.quarantine };
+        },
+        async worker(id) {
+            if (!isTenantId(id))
+                return undefined;
+            const entry = await load(id);
+            return entry?.kind === "open" ? entry.handle.worker : undefined;
+        },
+        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,
+                ...(input.studioCredentialHash
+                    ? { studioCredentialHash: input.studioCredentialHash }
+                    : {}),
+            };
+            // The store records its own schema version.
+            const envelope = envelopeNow({
+                id: input.tenantId,
+                name: input.name,
+                schemaVersion: POSTGRES_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);
+                await load(input.tenantId).catch(() => undefined);
+                return { envelope: existing, created: false };
+            }
+            await options.onCreated?.(input.tenantId).catch((error) => logger.warn("tenant create step failed; open repairs it", {
+                tenantId: input.tenantId,
+                message: error instanceof Error ? error.message : String(error),
+            }));
+            const opened = await load(input.tenantId).catch(() => undefined);
+            if (opened?.kind === "open") {
+                return { envelope: opened.handle.envelope, created: true };
+            }
+            // Created but failed to open: report the stored envelope.
+            return {
+                envelope: await store
+                    .readEnvelope(input.tenantId)
+                    .catch(() => 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].sort()) {
+                if (!isTenantId(id) || deleting.has(id))
+                    continue;
+                let entry = entries.get(id);
+                if (entry?.kind === "open") {
+                    result.push(toAdmin(id, entry, null));
+                    continue;
+                }
+                let envelope = null;
+                try {
+                    envelope = await store.readEnvelope(id);
+                    if (envelope.id !== id) {
+                        entry = {
+                            kind: "quarantined",
+                            quarantine: quarantine("envelope-invalid", `Tenant envelope id ${envelope.id} does not match ${id}`, { tenantId: id }).toQuarantine(),
+                        };
+                        envelope = null;
+                    }
+                }
+                catch (error) {
+                    // Deleted since it was enumerated.
+                    if (error instanceof TenantNotFoundError)
+                        continue;
+                    if (error instanceof TenantUnavailableError)
+                        throw error;
+                    // Listed as quarantined; only opening it caches a quarantine.
+                    entry ??= {
+                        kind: "quarantined",
+                        quarantine: quarantineOf(error) ??
+                            quarantine("envelope-invalid", "Tenant envelope is unreadable", {
+                                tenantId: id,
+                            }).toQuarantine(),
+                    };
+                }
+                result.push(toAdmin(id, entry, envelope));
+            }
+            return result;
+        },
+        async status(id) {
+            if (!isTenantId(id))
+                return undefined;
+            const entry = await load(id);
+            if (!entry)
+                return undefined;
+            if (entry.kind === "open")
+                return toAdmin(id, entry, null);
+            const envelope = await store.readEnvelope(id).catch(() => null);
+            return { ...toAdmin(id, entry, envelope), quarantine: entry.quarantine };
+        },
+        async delete(id, activeWork) {
+            if (!isTenantId(id))
+                throw new Error(`Invalid tenant id: ${id}`);
+            if (deleting.has(id))
+                throw new TenantBusyError("Tenant is being deleted");
+            const entry = await load(id);
+            if (!entry)
+                throw new TenantNotFoundError(id);
+            if (entry.kind === "open") {
+                const summary = await entry.handle.summary();
+                if (activeWork === "refuse" && hasLiveWork(summary)) {
+                    throw new TenantBusyError();
+                }
+                if (activeWork === "drain" || activeWork === "cancel") {
+                    await entry.handle.drain(activeWork);
+                }
+            }
+            deleting.add(id);
+            try {
+                entries.delete(id);
+                // Sandbox prefix cleanup is owned by TenantHandle.close().
+                if (entry.kind === "open")
+                    await entry.handle.close();
+                await store.trash(id, new Date());
+            }
+            finally {
+                deleting.delete(id);
+            }
+            logger.info("tenant deleted", { tenantId: id, activeWork });
+            await options.onDeleted?.(id).catch((error) => logger.warn("tenant delete cleanup failed", {
+                tenantId: id,
+                message: error instanceof Error ? error.message : String(error),
+            }));
+        },
+        async summarize() {
+            let runningSessions = 0;
+            let connectedExecutors = 0;
+            let pendingActions = 0;
+            let uncertainEffects = 0;
+            let outboxDepth;
+            let relayLagMs;
+            for (const s of await Promise.all(openEntries().map((e) => e.handle.summary()))) {
+                runningSessions += s.runningSessions;
+                connectedExecutors += s.connectedExecutors;
+                pendingActions += s.pendingActions;
+                uncertainEffects += s.uncertainEffects;
+                if (s.outboxDepth !== undefined)
+                    outboxDepth = (outboxDepth ?? 0) + s.outboxDepth;
+                if (s.relayLagMs !== undefined)
+                    relayLagMs = Math.max(relayLagMs ?? 0, s.relayLagMs);
+            }
+            return {
+                runningSessions,
+                connectedExecutors,
+                pendingActions,
+                uncertainEffects,
+                ...(outboxDepth !== undefined ? { outboxDepth } : {}),
+                ...(relayLagMs !== undefined ? { relayLagMs } : {}),
+            };
+        },
+        async close() {
+            closed = true;
+            started = false;
+            await Promise.allSettled([...opening.values()]);
+            const open = openEntries();
+            entries.clear();
+            await Promise.all(open.map((e) => e.handle.close().catch(() => undefined)));
+        },
+    };
+    return module;
+}
+export { TenantBusyError, TenantConflictError, TenantNotFoundError, TenantUnavailableError, isQuarantineError, quarantine, };

package/dist/tenant/paths.d.ts

@@ -0,0 +1,28 @@
+import type { Logger, TenantPaths } from "./types.js";
+export interface HostPaths {
+    root: string;
+    config: string;
+    credentials: string;
+    home: string;
+    tmp: string;
+    tenants: string;
+    trash: string;
+}
+/** Host layout under NYLORUN_HOME / ~/.nylorun. */
+export declare function hostPaths(hostRoot: string): HostPaths;
+/**
+ * Absolute Tenant directory paths under `<hostRoot>/tenants/<tenantId>/`.
+ * Validates the id and asserts containment after realpath.
+ *
+ * The directory holds what stays on the Host (the Tenant's data is its Postgres schema):
+ * `vault-kek`, `home/`, `tmp/`, `sandboxes/`, `plugin-data/`, `logs/tenant.log`.
+ */
+export declare function tenantPaths(hostRoot: string, tenantId: string): TenantPaths;
+/**
+ * Moves every Tenant directory that holds a `tenant.sqlite` to `trash/`, logging each.
+ *
+ * Those are beta Tenants from the SQLite Runtime. They are not migrated (recreate them); a
+ * Postgres Tenant's directory never holds that file. Moving them at Host start keeps a new
+ * Postgres Tenant with the same id from sharing the old directory. Returns the moved ids.
+ */
+export declare function trashSqliteTenants(hostRoot: string, logger: Logger): string[];

package/dist/tenant/paths.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readdirSync, realpathSync, renameSync, } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { isTenantId } from "@nylorun/core/compatibility";
+function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+    return realpathSync(path);
+}
+function assertContained(parent, child) {
+    const root = parent.endsWith(sep) ? parent : parent + sep;
+    if (child !== parent && !child.startsWith(root)) {
+        throw new Error(`Path ${child} escapes host tenants root ${parent}`);
+    }
+}
+/** Host layout under NYLORUN_HOME / ~/.nylorun. */
+export function hostPaths(hostRoot) {
+    const root = resolve(hostRoot);
+    return {
+        root,
+        config: join(root, "host.json"),
+        credentials: join(root, "host-credentials.json"),
+        home: join(root, "home"),
+        tmp: join(root, "tmp"),
+        tenants: join(root, "tenants"),
+        trash: join(root, "trash"),
+    };
+}
+/**
+ * Absolute Tenant directory paths under `<hostRoot>/tenants/<tenantId>/`.
+ * Validates the id and asserts containment after realpath.
+ *
+ * The directory holds what stays on the Host (the Tenant's data is its Postgres schema):
+ * `vault-kek`, `home/`, `tmp/`, `sandboxes/`, `plugin-data/`, `logs/tenant.log`.
+ */
+export function tenantPaths(hostRoot, tenantId) {
+    if (!isTenantId(tenantId)) {
+        throw new Error(`Invalid tenant id: ${String(tenantId)}`);
+    }
+    const host = hostPaths(hostRoot);
+    const tenantsRoot = ensureDir(host.tenants);
+    const root = join(tenantsRoot, tenantId);
+    // Containment before the Tenant directory exists: resolve under real tenants root.
+    const resolvedRoot = resolve(tenantsRoot, tenantId);
+    assertContained(tenantsRoot, resolvedRoot);
+    if (existsSync(root)) {
+        assertContained(tenantsRoot, realpathSync(root));
+    }
+    return {
+        root: resolvedRoot,
+        kek: join(resolvedRoot, "vault-kek"),
+        home: join(resolvedRoot, "home"),
+        tmp: join(resolvedRoot, "tmp"),
+        sandboxes: join(resolvedRoot, "sandboxes"),
+        pluginData: join(resolvedRoot, "plugin-data"),
+        logs: join(resolvedRoot, "logs"),
+        log: join(resolvedRoot, "logs", "tenant.log"),
+    };
+}
+/** The database file of a Tenant from before the Postgres Session Store. */
+const SQLITE_DATABASE = "tenant.sqlite";
+/**
+ * Moves every Tenant directory that holds a `tenant.sqlite` to `trash/`, logging each.
+ *
+ * Those are beta Tenants from the SQLite Runtime. They are not migrated (recreate them); a
+ * Postgres Tenant's directory never holds that file. Moving them at Host start keeps a new
+ * Postgres Tenant with the same id from sharing the old directory. Returns the moved ids.
+ */
+export function trashSqliteTenants(hostRoot, logger) {
+    const host = hostPaths(hostRoot);
+    if (!existsSync(host.tenants))
+        return [];
+    const moved = [];
+    const stamp = new Date().toISOString().replaceAll(":", "-");
+    for (const entry of readdirSync(host.tenants, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const directory = join(host.tenants, entry.name);
+        if (!existsSync(join(directory, SQLITE_DATABASE)))
+            continue;
+        mkdirSync(host.trash, { recursive: true });
+        const destination = join(host.trash, `${entry.name}-sqlite-${stamp}`);
+        renameSync(directory, destination);
+        moved.push(entry.name);
+        logger.warn("sqlite_tenant_moved_to_trash", {
+            tenant: entry.name,
+            from: directory,
+            to: destination,
+            reason: "SQLite Tenants are not migrated to the Postgres Session Store; recreate the Tenant",
+        });
+    }
+    return moved;
+}

package/dist/tenant/pool.d.ts

@@ -0,0 +1,10 @@
+/** Run async work over items with a fixed concurrency limit. */
+export declare function mapPool<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Race a promise against a timeout. On timeout the late result is handed to
+ * `onLate` (Risk R6: mark quarantined and close a late handle).
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, onLate?: (late: Promise<T>) => void): Promise<T>;

package/dist/tenant/pool.js

@@ -0,0 +1,54 @@
+/** Run async work over items with a fixed concurrency limit. */
+export async function mapPool(items, concurrency, worker) {
+    if (items.length === 0)
+        return [];
+    const limit = Math.max(1, Math.min(concurrency, items.length));
+    const results = new Array(items.length);
+    let next = 0;
+    async function run() {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: limit }, () => run()));
+    return results;
+}
+export class TimeoutError extends Error {
+    constructor(message = "operation timed out") {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+/**
+ * Race a promise against a timeout. On timeout the late result is handed to
+ * `onLate` (Risk R6: mark quarantined and close a late handle).
+ */
+export async function withTimeout(promise, timeoutMs, onLate) {
+    let timer;
+    let timedOut = false;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            timedOut = true;
+            reject(new TimeoutError(`timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        const result = await Promise.race([promise, timeout]);
+        return result;
+    }
+    catch (error) {
+        if (timedOut && onLate) {
+            onLate(promise.then((value) => value, (lateError) => {
+                throw lateError;
+            }));
+        }
+        throw error;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/tenant/principals.d.ts

@@ -0,0 +1,13 @@
+import type { Tx } from "../store/types.js";
+import type { BootstrapPrincipal } from "./types.js";
+export type { PrincipalRow } from "../store/types.js";
+/** Principal id of the Studio key derived from the admin key. */
+export declare const STUDIO_PRINCIPAL_ID = "studio";
+/**
+ * Writes the application principal and idempotency key in the caller's transaction, plus
+ * principal `studio` when the bootstrap carries a Studio credential hash.
+ * Exported for WS-B's `TenantStore.create` (A3).
+ */
+export declare function bootstrapPrincipal(t: Tx, bootstrap: BootstrapPrincipal, now?: Date): Promise<void>;
+/** Whether the stored bootstrap (and Studio) principals equal `bootstrap`. */
+export declare function bootstrapPrincipalMatches(t: Tx, bootstrap: BootstrapPrincipal): Promise<boolean>;

package/dist/tenant/principals.js

@@ -0,0 +1,37 @@
+/** Principal id of the Studio key derived from the admin key. */
+export const STUDIO_PRINCIPAL_ID = "studio";
+/**
+ * Writes the application principal and idempotency key in the caller's transaction, plus
+ * principal `studio` when the bootstrap carries a Studio credential hash.
+ * Exported for WS-B's `TenantStore.create` (A3).
+ */
+export async function bootstrapPrincipal(t, bootstrap, now = new Date()) {
+    const createdAt = now.toISOString();
+    await t.insertPrincipal({
+        id: bootstrap.principalId,
+        role: "application",
+        tokenHash: bootstrap.credentialHash,
+        idempotencyKey: bootstrap.idempotencyKey,
+        createdAt,
+    });
+    if (bootstrap.studioCredentialHash)
+        await t.insertPrincipal({
+            id: STUDIO_PRINCIPAL_ID,
+            role: "application",
+            tokenHash: bootstrap.studioCredentialHash,
+            idempotencyKey: null,
+            createdAt,
+        });
+}
+/** Whether the stored bootstrap (and Studio) principals equal `bootstrap`. */
+export async function bootstrapPrincipalMatches(t, bootstrap) {
+    const row = await t.principalById(bootstrap.principalId);
+    if (!row ||
+        row.role !== "application" ||
+        row.tokenHash !== bootstrap.credentialHash ||
+        row.idempotencyKey !== bootstrap.idempotencyKey)
+        return false;
+    const studio = await t.principalById(STUDIO_PRINCIPAL_ID);
+    return ((studio?.role === "application" ? studio.tokenHash : undefined) ===
+        bootstrap.studioCredentialHash);
+}

package/dist/tenant/quarantine-error.d.ts

@@ -0,0 +1,6 @@
+import type { Quarantine } from "./types.js";
+/** Typed quarantine raised while opening a Tenant Runtime (A7). */
+export declare class QuarantineError extends Error {
+    readonly quarantine: Quarantine;
+    constructor(code: Quarantine["code"], message: string, repair?: string);
+}