@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/environments/environments.service.js

@@ -0,0 +1,791 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { deviceLeaseKey } from "../devices/keys.js";
+import { MachinesService } from "../devices/machines.js";
+import { ApiError } from "../errors.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
+import { audit } from "../identity/audit.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { SandboxJobs } from "../sandbox/jobs.js";
+import { DEVICE_PROVIDER, isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
+import { environmentNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { demotedProvider, EnvironmentAccess, environmentProvider, environmentUnavailable, inUseForDefault, } from "./access.js";
+const isUniqueViolation = (e, constraint) => typeof e === "object" &&
+    e !== null &&
+    e.code === "23505" &&
+    e.constraint === constraint;
+const nameTaken = () => new ApiError("environment.name_taken", "You already have an environment with this name");
+/**
+ * Personal environments (spec 2026-11-07-environments-design §4.2 items 7, 12, 13; §6; §9):
+ * cloud ones on the deployment's sandbox provider and `device` ones on a connected machine; a
+ * person's environments in an org, visible and usable only by their owner (anyone else gets
+ * `environment.not_found`). Deleting one soft-deletes it and destroys its instance and files in a
+ * `sandbox-destroy-for` job after the commit.
+ */
+let EnvironmentsService = class EnvironmentsService {
+    db;
+    txHost;
+    config;
+    providers;
+    sandbox;
+    sandboxJobs;
+    access;
+    displayNames;
+    log;
+    locks;
+    machines;
+    constructor(db, txHost, config, providers, sandbox, sandboxJobs, access, displayNames, log, 
+    /** Reads the device relay's lease (`online`). */
+    locks, machines) {
+        this.db = db;
+        this.txHost = txHost;
+        this.config = config;
+        this.providers = providers;
+        this.sandbox = sandbox;
+        this.sandboxJobs = sandboxJobs;
+        this.access = access;
+        this.displayNames = displayNames;
+        this.log = log;
+        this.locks = locks;
+        this.machines = machines;
+    }
+    /**
+     * The person's live environments in the org, the default first, then by creation. With a
+     * current sandbox provider the default environment is created first if missing (its first need,
+     * spec §4.2 item 7; an existing one is only read).
+     */
+    async list(orgId, accountId) {
+        const cloudAvailable = this.providers.cloud() !== undefined;
+        const defaultId = cloudAvailable ? await this.ensureDefault(orgId, accountId) : null;
+        const items = await this.views(orgId, accountId);
+        const last = await this.db
+            .selectFrom("conversations as c")
+            .innerJoin("environments as e", "e.id", "c.environment_id")
+            .select("c.environment_id")
+            .where("c.org_id", "=", orgId)
+            .where("c.account_id", "=", accountId)
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .orderBy("c.updated_at", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return {
+            items,
+            defaultId: defaultId ?? items.find((v) => v.isDefault)?.id ?? null,
+            lastUsedId: last?.environment_id ?? null,
+            cloudAvailable,
+        };
+    }
+    /** One of the person's live environments; anyone else's (or a missing one) → `not_found`. */
+    async get(orgId, accountId, id) {
+        const [view] = await this.views(orgId, accountId, id);
+        if (!view)
+            throw environmentNotFound();
+        return view;
+    }
+    /**
+     * A new personal cloud environment, ready at once (its instance and files are made on first
+     * use). Needs a current sandbox provider (`environment.unavailable`); a live name of the person's
+     * (case-insensitive) → `environment.name_taken`; `environments.maxPersonal` live ones (the
+     * default counts) → `environment.limit_reached`. Serialized per person by their membership row.
+     */
+    async create(orgId, accountId, input, actorTokenId, auditDetail) {
+        const id = await this.insert(orgId, accountId, input.name, actorTokenId, auditDetail);
+        return this.get(orgId, accountId, id);
+    }
+    async insert(orgId, accountId, name, actorTokenId, auditDetail) {
+        const current = this.providers.cloud();
+        if (!current)
+            throw environmentUnavailable(null);
+        return this.insertNamed(orgId, accountId, name, "cloud", current.plugin, actorTokenId, auditDetail ?? {});
+    }
+    /**
+     * A new personal `device` environment for a machine being connected (provider `@device`; the
+     * machine row is the caller's). Joins the caller's transaction (the device authorization's).
+     * Counted against `environments.maxPersonal` (`environment.limit_reached`); a live name of the
+     * person's → `environment.name_taken`. Needs no cloud provider.
+     */
+    async createDevice(orgId, accountId, name) {
+        const id = await this.insertNamed(orgId, accountId, name, "device", DEVICE_PROVIDER, undefined, {
+            source: "device",
+        });
+        return { id };
+    }
+    /**
+     * Inserts a named personal environment under the person's membership lock, after the limit
+     * and name checks, and audits `environment.created`. Runs in the caller's transaction.
+     */
+    async insertNamed(orgId, accountId, name, source, provider, actorTokenId, auditDetail) {
+        await this.lockMember(orgId, accountId);
+        const { n } = await this.db
+            .selectFrom("environments")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirstOrThrow();
+        const max = this.config.get().environments.maxPersonal;
+        if (Number(n) >= max) {
+            throw new ApiError("environment.limit_reached", `You already have ${max} environments in this organization; delete one to create another`);
+        }
+        await this.assertNameFree(orgId, accountId, name);
+        const id = randomUUID();
+        try {
+            await this.db
+                .insertInto("environments")
+                .values({
+                id,
+                org_id: orgId,
+                owner_kind: "personal",
+                owner_account_id: accountId,
+                name,
+                source,
+                provider,
+            })
+                .execute();
+        }
+        catch (e) {
+            if (isUniqueViolation(e, "environments_name_uq"))
+                throw nameTaken();
+            throw e;
+        }
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.created",
+            target: id,
+            detail: { name, ...auditDetail },
+        });
+        return id;
+    }
+    /**
+     * The refusals {@link create} would raise, read without locks or writes (a precheck before a
+     * confirmation card): no sandbox provider, the person's limit, a name already taken. Throws the
+     * same {@link ApiError}s; a race still ends in `create`'s own refusal.
+     */
+    async checkCreate(orgId, accountId, name) {
+        if (!this.providers.cloud())
+            throw environmentUnavailable(null);
+        const { n } = await this.db
+            .selectFrom("environments")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirstOrThrow();
+        const max = this.config.get().environments.maxPersonal;
+        if (Number(n) >= max) {
+            throw new ApiError("environment.limit_reached", `You already have ${max} environments in this organization; delete one to create another`);
+        }
+        await this.assertNameFree(orgId, accountId, name);
+    }
+    /** How many of the person's conversations work in the environment (read only). */
+    async boundConversations(orgId, accountId, id) {
+        const { n } = await this.db
+            .selectFrom("conversations")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .where("environment_id", "=", id)
+            .executeTakeFirstOrThrow();
+        return Number(n);
+    }
+    /**
+     * The refusals {@link resetFiles} would raise (not found, its provider not current, a connected
+     * environment), read only.
+     */
+    async checkReset(orgId, accountId, id) {
+        refuseDeviceReset(await this.access.usable(orgId, accountId, id));
+    }
+    /** The refusals {@link rename} would raise, read without locks (see {@link checkCreate}). */
+    async checkRename(orgId, accountId, id, name) {
+        const before = await this.get(orgId, accountId, id);
+        if (before.name?.toLowerCase() !== name.toLowerCase()) {
+            await this.assertNameFree(orgId, accountId, name);
+        }
+    }
+    /**
+     * Renames one of the person's live environments (the default too); see {@link create}. A
+     * renamed former default is the person's own from then on: it loses its demotion mark, so a
+     * switch back to its provider no longer restores it.
+     */
+    async rename(orgId, accountId, id, name, actorTokenId, auditDetail) {
+        await this.renameIn(orgId, accountId, id, name, actorTokenId, auditDetail);
+        return this.get(orgId, accountId, id);
+    }
+    async renameIn(orgId, accountId, id, name, actorTokenId, auditDetail) {
+        const before = await this.lockOwn(orgId, accountId, id);
+        if (before.name === name)
+            return;
+        // the same name in another case is this environment's own: the index allows it
+        if (before.name?.toLowerCase() !== name.toLowerCase()) {
+            await this.assertNameFree(orgId, accountId, name);
+        }
+        try {
+            await this.db
+                .updateTable("environments")
+                .set({ name, demoted_from_provider: null, updated_at: sql `now()` })
+                .where("id", "=", id)
+                .execute();
+        }
+        catch (e) {
+            if (isUniqueViolation(e, "environments_name_uq"))
+                throw nameTaken();
+            throw e;
+        }
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.renamed",
+            target: id,
+            detail: { from: before.name, to: name, ...auditDetail },
+        });
+    }
+    /**
+     * Deletes one of the person's live environments: soft delete, its IM default row cleared, and
+     * after the commit a `sandbox-destroy-for` job (the worker waits for running commands, then
+     * destroys the instance and the files). Conversations bound to it keep pointing at it; their
+     * sandbox tools then fail with `environment.not_found`. A device environment's machine is
+     * revoked in the same transaction; after the commit it is told `stop { reason: "deleted" }`
+     * (while connected) and its connection is closed.
+     */
+    async remove(orgId, accountId, id, actorTokenId, auditDetail) {
+        const before = await this.lockOwn(orgId, accountId, id);
+        await this.db
+            .updateTable("environments")
+            .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
+            .where("id", "=", id)
+            .execute();
+        await this.db
+            .deleteFrom("environment_defaults")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .where("environment_id", "=", id)
+            .execute();
+        await this.machines.revokeActive(id, "deleted");
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.deleted",
+            target: id,
+            detail: { name: before.name, isDefault: before.is_default, ...auditDetail },
+        });
+        afterCommit(async () => {
+            try {
+                await this.sandboxJobs.destroy([id]);
+            }
+            catch (err) {
+                // the hourly destruction sweep destroys deleted environments too
+                this.log.warn("cannot schedule environment destruction", { environmentId: id, err });
+            }
+        });
+    }
+    /**
+     * Disconnects the machine of one of the person's own device environments (it must sign in
+     * again); see {@link MachinesService.revoke}.
+     */
+    async revokeMachine(orgId, accountId, id, actorTokenId) {
+        await this.machines.revoke(orgId, accountId, id, actorTokenId);
+    }
+    /**
+     * Starts one of the person's environments over with empty files (after
+     * `environment.files_lost`): records the request (audit), then, after the commit, enqueues the
+     * `sandbox-reset-files` job (deterministic id per environment), whose worker waits for running
+     * commands and destroys any instance and the file system; the next use creates new ones. Its
+     * provider must be the current one (`environment.unavailable`); a connected environment's files
+     * are its machine owner's (`environment.files_on_device`). An enqueue failure is thrown
+     * (the request can be repeated: the reset is idempotent).
+     */
+    async resetFiles(orgId, accountId, id, actorTokenId, auditDetail) {
+        await this.recordReset(orgId, accountId, id, actorTokenId, auditDetail);
+        await this.sandboxJobs.resetFiles(id);
+    }
+    /** The check and audit row of {@link resetFiles}, committed before the job is enqueued. */
+    async recordReset(orgId, accountId, id, actorTokenId, auditDetail) {
+        refuseDeviceReset(await this.access.usable(orgId, accountId, id));
+        await audit(this.db.db, {
+            actorAccountId: accountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "environment.files_reset",
+            target: id,
+            ...(auditDetail !== undefined && { detail: auditDetail }),
+        });
+    }
+    /**
+     * The person's default environment in the org, created when missing (named by the UI, `name`
+     * NULL). An existing usable one is read without locking. A live default whose files or
+     * instance are kept by a provider that is not the current one (a provider switch, spec §4.2
+     * item 13) is stranded: it is demoted (marked with the provider it was demoted from; the UI
+     * names it 「个人环境（<provider display name>）」) and stays listed as unavailable and deletable.
+     * Its replacement is the person's former default demoted from the current provider when there
+     * is one (switching back restores it, with its files), else a fresh default. A live default
+     * not in use yet (no healthy files, no instance, none being created: {@link inUseForDefault})
+     * is likewise swapped for a former default holding healthy files at the current provider; it is
+     * demoted (from the provider it was made under) so it can come back in turn. A former default
+     * belongs to the provider holding its resources once it holds any, else to the one it was
+     * demoted from ({@link demotedProvider}), so one swapped out empty and used afterwards is
+     * labelled and restored by where its files are.
+     * All of it in one transaction: switching back and forth never adds environments.
+     *
+     * Replacing one first takes the person's membership row (`FOR SHARE`, after the org row), so an
+     * offboarding that removes them cannot leave a live default behind; not a member (any more) →
+     * `org.not_found`. Idempotent under concurrency: the live default row and the person's former
+     * defaults of the current provider are locked (`FOR NO KEY UPDATE`) and the live default re-read
+     * after them, the partial unique index on the live default makes a racing insert do nothing, and
+     * the select that follows reads the winner. Needs a current sandbox provider
+     * (`environment.unavailable`). It is the person's baseline, so it is created even at
+     * `environments.maxPersonal`.
+     */
+    async ensureDefault(orgId, accountId) {
+        const live = await this.defaultOf(orgId, accountId);
+        if (live && !this.stranded(live)) {
+            const current = this.providers.cloud()?.plugin;
+            if (inUseForDefault(live) || current === undefined)
+                return live.id;
+            const former = await this.formerDefaults(orgId, accountId, current);
+            if (!former.some((f) => f.holdsFiles))
+                return live.id;
+        }
+        return this.insertDefault(orgId, accountId);
+    }
+    async insertDefault(orgId, accountId) {
+        const current = this.providers.cloud();
+        if (!current)
+            throw environmentUnavailable(null);
+        await this.lockMember(orgId, accountId, "share");
+        const locked = await this.defaultOf(orgId, accountId, true);
+        const former = await this.formerDefaults(orgId, accountId, current.plugin, true);
+        // a racing replacement committed while this waited: its default is the answer
+        const live = locked ?? (await this.defaultOf(orgId, accountId));
+        if (live && live !== locked)
+            return live.id;
+        const stranded = live !== undefined && this.stranded(live);
+        const withFiles = former.find((f) => f.holdsFiles);
+        if (live && !stranded && (inUseForDefault(live) || withFiles === undefined))
+            return live.id;
+        // a default is needed (none, or a stranded one): any former default will do, files first
+        const restore = withFiles ?? (live === undefined || stranded ? former[0] : undefined);
+        if (live) {
+            const from = stranded
+                ? (environmentProvider(live, current.plugin) ?? "unknown")
+                : (live.provider ?? current.plugin);
+            await this.demote(live.id, from);
+        }
+        if (restore) {
+            await this.db
+                .updateTable("environments")
+                .set({ is_default: true, demoted_from_provider: null, updated_at: sql `now()` })
+                .where("id", "=", restore.id)
+                .execute();
+            return restore.id;
+        }
+        await this.db
+            .insertInto("environments")
+            .values({
+            id: randomUUID(),
+            org_id: orgId,
+            owner_kind: "personal",
+            owner_account_id: accountId,
+            name: null,
+            is_default: true,
+            source: "cloud",
+            provider: current.plugin,
+        })
+            .onConflict((oc) => oc
+            .columns(["org_id", "owner_account_id"])
+            .where(sql `is_default AND deleted_at IS NULL`)
+            .doNothing())
+            .execute();
+        const row = await this.defaultOf(orgId, accountId);
+        if (row === undefined)
+            throw new Error("the default environment was not created");
+        return row.id;
+    }
+    /**
+     * Turns the live default into an ordinary environment marked as demoted from `provider`; a name
+     * the person gave it stays. Runs under the person's membership lock and the default row's lock,
+     * before any other row becomes the default (the partial unique index).
+     */
+    async demote(id, provider) {
+        await this.db
+            .updateTable("environments")
+            .set({ is_default: false, demoted_from_provider: provider, updated_at: sql `now()` })
+            .where("id", "=", id)
+            .execute();
+    }
+    /**
+     * The person's live former defaults of `provider` ({@link demotedProvider}: files or an instance
+     * kept by `provider`, or none and demoted from it), the ones holding healthy files first (lost
+     * files count as none), then the most recently used, then the most recently demoted. `lock`
+     * takes their rows (`FOR NO KEY UPDATE`, in id order, so racing replacements queue on the same
+     * rows).
+     */
+    async formerDefaults(orgId, accountId, provider, lock = false) {
+        const rows = await this.db
+            .selectFrom("environments as e")
+            .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .select([
+            "e.id",
+            "e.provider",
+            "e.updated_at",
+            "i.provider as instance_provider",
+            "i.fs_status",
+            "e.demoted_from_provider",
+            "i.handle",
+            "i.status",
+            "i.last_used_at",
+        ])
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.is_default", "=", false)
+            .where("e.demoted_from_provider", "is not", null)
+            .where((eb) => eb.or([eb("e.demoted_from_provider", "=", provider), eb("i.provider", "=", provider)]))
+            .where("e.deleted_at", "is", null)
+            .orderBy("e.id")
+            .$if(lock, (q) => q.forNoKeyUpdate("e"))
+            .execute();
+        const time = (d) => d?.getTime() ?? 0;
+        return rows
+            .map((r) => {
+            const facts = {
+                provider: r.provider,
+                instanceProvider: r.instance_provider,
+                fsStatus: r.fs_status,
+                hasInstance: r.handle !== null,
+            };
+            return {
+                r,
+                holdsFiles: inUseForDefault({ ...facts, status: r.status }),
+                belongs: demotedProvider(r.demoted_from_provider, facts) === provider,
+            };
+        })
+            .filter(({ belongs }) => belongs)
+            .sort((a, b) => Number(b.holdsFiles) - Number(a.holdsFiles) ||
+            time(b.r.last_used_at) - time(a.r.last_used_at) ||
+            time(b.r.updated_at) - time(a.r.updated_at))
+            .map(({ r, holdsFiles }) => ({ id: r.id, holdsFiles }));
+    }
+    /**
+     * The person's IM default (what `/env` set): the environment their next new IM conversation
+     * uses. Null when none was set, or the chosen one is deleted (the row is cleared with it).
+     */
+    async imDefault(orgId, accountId) {
+        const row = await this.db
+            .selectFrom("environment_defaults as d")
+            .innerJoin("environments as e", "e.id", "d.environment_id")
+            .select("e.id")
+            .where("d.org_id", "=", orgId)
+            .where("d.account_id", "=", accountId)
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .executeTakeFirst();
+        return row?.id ?? null;
+    }
+    /**
+     * Sets the person's IM default. Only one of their own live environments in the org, usable now
+     * (`environment.not_found` / `environment.unavailable` otherwise); the row is written by one
+     * statement that re-checks the environment is live. There is no row lock, so a delete racing
+     * past that check can leave a stale row; reads ignore it ({@link imDefault} joins on
+     * `deleted_at IS NULL`).
+     */
+    async setImDefault(orgId, accountId, environmentId) {
+        await this.access.usable(orgId, accountId, environmentId);
+        const written = await this.db
+            .insertInto("environment_defaults")
+            .columns(["org_id", "account_id", "environment_id"])
+            .expression(this.db
+            .selectFrom("environments")
+            .select([
+            sql `${orgId}::text`.as("org_id"),
+            sql `${accountId}::text`.as("account_id"),
+            "id",
+        ])
+            .where("id", "=", environmentId)
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null))
+            .onConflict((oc) => oc
+            .columns(["org_id", "account_id"])
+            .doUpdateSet({ environment_id: environmentId, updated_at: new Date() }))
+            .executeTakeFirst();
+        if (Number(written.numInsertedOrUpdatedRows ?? 0) === 0)
+            throw environmentNotFound();
+    }
+    /**
+     * The person's live default environment in the org, if any, with what decides its provider;
+     * `lock` takes its row (`FOR NO KEY UPDATE`; a racing demotion makes it read none).
+     */
+    async defaultOf(orgId, accountId, lock = false) {
+        const row = await this.db
+            .selectFrom("environments as e")
+            .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .select([
+            "e.id",
+            "e.provider",
+            "i.provider as instance_provider",
+            "i.fs_status",
+            "i.handle",
+            "i.status",
+        ])
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.is_default", "=", true)
+            .where("e.deleted_at", "is", null)
+            .$if(lock, (q) => q.forNoKeyUpdate("e"))
+            .executeTakeFirst();
+        return (row && {
+            id: row.id,
+            provider: row.provider,
+            instanceProvider: row.instance_provider,
+            fsStatus: row.fs_status,
+            hasInstance: row.handle !== null,
+            status: row.status,
+        });
+    }
+    /** Its files or instance are kept by a provider that is not the current one. */
+    stranded(f) {
+        const current = this.providers.cloud()?.plugin;
+        return current !== undefined && environmentProvider(f, current) !== current;
+    }
+    /** The person's live environments (or the one `id`) as views. */
+    async views(orgId, accountId, id) {
+        // all of them even for one `id`: a former default's ordinal counts its siblings
+        const all = await this.db
+            .selectFrom("environments as e")
+            .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .leftJoin("environment_machines as m", (j) => j.onRef("m.environment_id", "=", "e.id").on("m.revoked_at", "is", null))
+            .select([
+            "e.id",
+            "e.name",
+            "e.is_default",
+            "e.source",
+            "e.provider",
+            "e.demoted_from_provider",
+            "e.created_at",
+            "m.id as machine_id",
+            "m.name as machine_name",
+            "m.os as machine_os",
+            "m.mode as machine_mode",
+            "m.program_version as machine_program_version",
+            "m.last_seen_at as machine_last_seen_at",
+            "m.session_isolation as machine_session_isolation",
+            "i.provider as instance_provider",
+            "i.fs_status",
+            "i.handle",
+            "i.status",
+            "i.last_used_at",
+        ])
+            .where("e.org_id", "=", orgId)
+            .where("e.owner_kind", "=", "personal")
+            .where("e.owner_account_id", "=", accountId)
+            .where("e.deleted_at", "is", null)
+            .orderBy("e.is_default", "desc")
+            .orderBy("e.created_at")
+            .orderBy("e.id")
+            .execute();
+        const rows = id === undefined ? all : all.filter((r) => r.id === id);
+        if (rows.length === 0)
+            return [];
+        const factsOf = (r) => ({
+            provider: r.provider,
+            instanceProvider: r.instance_provider,
+            fsStatus: r.fs_status,
+            hasInstance: r.handle !== null,
+        });
+        // a former default is labelled after the provider holding its resources, else its marker
+        const demoted = new Map(all.map((r) => [r.id, demotedProvider(r.demoted_from_provider, factsOf(r))]));
+        const ordinals = new Map();
+        const seen = new Map();
+        for (const r of [...all].sort((a, b) => a.created_at.getTime() - b.created_at.getTime() || a.id.localeCompare(b.id))) {
+            const from = demoted.get(r.id) ?? null;
+            if (from === null || r.name !== null)
+                continue;
+            const n = (seen.get(from) ?? 0) + 1;
+            seen.set(from, n);
+            ordinals.set(r.id, n);
+        }
+        const demotedProviders = [
+            ...new Set(rows.flatMap((r) => (demoted.get(r.id) ? [demoted.get(r.id)] : []))),
+        ];
+        const [limits, names] = await Promise.all([
+            this.sandbox.orgLimits(orgId),
+            this.displayNames.many(demotedProviders),
+        ]);
+        const current = this.providers.cloud()?.plugin;
+        // a device environment is online while a replica holds its machine's connection lease
+        const online = new Map(await Promise.all(rows
+            .filter((r) => r.source === "device")
+            .map(async (r) => [r.id, (await this.locks.holderOf(deviceLeaseKey(r.id))) !== null])));
+        return rows.map((r) => {
+            const provider = environmentProvider(factsOf(r), current);
+            const live = (r.status === "running" || r.status === "suspended") && r.last_used_at;
+            const from = demoted.get(r.id) ?? null;
+            return {
+                id: r.id,
+                name: r.name,
+                isDefault: r.is_default,
+                demotedFrom: from === null
+                    ? null
+                    : {
+                        provider: from,
+                        displayName: names.get(from) ?? null,
+                        ordinal: ordinals.get(r.id) ?? 1,
+                    },
+                ownerKind: "personal",
+                source: r.source,
+                provider,
+                available: provider !== null && isInternalProvider(provider)
+                    ? this.providers.forName(provider) !== undefined
+                    : current !== undefined && provider === current,
+                online: r.source === "device" ? (online.get(r.id) ?? false) : null,
+                machine: r.machine_id !== null && r.machine_name !== null && r.machine_os !== null
+                    ? {
+                        id: r.machine_id,
+                        name: r.machine_name,
+                        os: r.machine_os,
+                        mode: r.machine_mode,
+                        programVersion: r.machine_program_version,
+                        lastSeenAt: r.machine_last_seen_at?.toISOString() ?? null,
+                    }
+                    : null,
+                // a device environment's machine decides it; cloud environments have none in phase 2
+                sessionIsolation: r.machine_session_isolation ?? false,
+                filesLost: r.fs_status === "lost",
+                instance: live
+                    ? {
+                        status: r.status,
+                        lastUsedAt: r.last_used_at.toISOString(),
+                    }
+                    : null,
+                limits: { ...limits, allowHosts: [...limits.allowHosts] },
+                createdAt: r.created_at.toISOString(),
+            };
+        });
+    }
+    /**
+     * Serializes the person's environment writes in the org: the org row (`FOR SHARE`), then their
+     * membership row (`FOR NO KEY UPDATE`, or `FOR SHARE` with `mode` share: enough to keep the
+     * membership from being removed meanwhile), the order member removal locks them in. Not a
+     * member (any more) → `org.not_found`, as the org guard answers.
+     */
+    async lockMember(orgId, accountId, mode = "update") {
+        const org = await this.db
+            .selectFrom("orgs")
+            .select("id")
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .forShare()
+            .executeTakeFirst();
+        const m = org &&
+            (await this.db
+                .selectFrom("memberships")
+                .select("account_id")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .$if(mode === "update", (q) => q.forNoKeyUpdate())
+                .$if(mode === "share", (q) => q.forShare())
+                .executeTakeFirst());
+        if (!m)
+            throw new ApiError("org.not_found", "Organization not found");
+    }
+    /** Locks one of the person's live environments (after their membership); else `not_found`. */
+    async lockOwn(orgId, accountId, id) {
+        await this.lockMember(orgId, accountId);
+        const row = await this.db
+            .selectFrom("environments")
+            .select(["name", "is_default"])
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("owner_kind", "=", "personal")
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .forNoKeyUpdate()
+            .executeTakeFirst();
+        if (!row)
+            throw environmentNotFound();
+        return row;
+    }
+    async assertNameFree(orgId, accountId, name) {
+        const clash = await this.db
+            .selectFrom("environments")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("owner_account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .where(sql `lower(name) = lower(${name})`)
+            .executeTakeFirst();
+        if (clash)
+            throw nameTaken();
+    }
+};
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "insert", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "createDevice", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "renameIn", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "remove", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "recordReset", null);
+__decorate([
+    Transactional()
+], EnvironmentsService.prototype, "insertDefault", null);
+EnvironmentsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(SandboxProviders)),
+    __param(4, Inject(SandboxService)),
+    __param(5, Inject(SandboxJobs)),
+    __param(6, Inject(EnvironmentAccess)),
+    __param(7, Inject(ExtensionDisplayNames)),
+    __param(8, Inject(KERNEL_LOGGER)),
+    __param(9, Inject(LockService)),
+    __param(10, Inject(MachinesService))
+], EnvironmentsService);
+export { EnvironmentsService };
+/**
+ * Ruling R24: a connected environment's files are in a directory on its machine, which the
+ * platform never wipes; a lost directory comes back with `capybara-device logout` and a new `login` on the machine.
+ */
+function refuseDeviceReset(env) {
+    if (env.provider === DEVICE_PROVIDER) {
+        throw new ApiError("environment.files_on_device", "This environment's files are in a directory on its connected machine and cannot be reset from here. To start over, run capybara-device logout, then capybara-device login into this environment, on that machine.");
+    }
+}