ankka-console 0.10.0 → 0.12.0

package/dist/testing/fake-control-plane.js

@@ -2,7 +2,8 @@
  * A control plane in one process: every route the console uses, over in-memory state, with the
  * control plane's rules as the console can observe them — who sees what, `404` rather than `403`
  * for an outsider, owner-only operations, tombstoned ids, `409` for a non-empty delete, a disabled
- * organization refusing changes, descriptor validation, a deploy token shown once.
+ * organization refusing changes, descriptor validation, a deploy token shown once, grants made,
+ * listed and ended with their effect, and machines registered with a secret shown once.
  *
  * It answers from state rather than from a script, so it cannot run out quietly. What a test needs
  * to steer is explicit: `script()` makes the next answer on one route a given status, `tick()` moves
@@ -11,7 +12,90 @@
  * template exercised, which the parity test reads.
  */
 import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+/** The entries a project secret must hold for a broker's shape, as the control plane checks. */
+const brokerNeeds = (shape) => shape === "certificate" ? ["ca.crt", "tls.crt", "tls.key"] : shape === "sasl" ? ["ca.crt", "username", "password"] : [];
+const topicSourceOnTheWire = (t) => ({
+    kind: t.kind,
+    component: t.component,
+    topic: t.topic,
+    group: t.group,
+    start: t.start ?? "earliest",
+    version: t.version ?? 1,
+    recordedVersion: null,
+    behind: false,
+    broker: t.broker ?? null,
+    contract: t.contract ?? null,
+    lag: t.lag ?? null,
+    failing: t.failing ?? null,
+    gap: t.gap ?? null,
+});
+const SettingNames = [
+    "retention",
+    "retentionSize",
+    "cleanup",
+    "tombstoneWindow",
+    "minCompactionLag",
+    "maxCompactionLag",
+    "copies",
+    "minInSync",
+];
+/** The installation's shipped defaults and bounds, as the control plane's reference.conf has them. */
+const TopicDefaults = {
+    retention: "7d",
+    retentionSize: "none",
+    cleanup: "delete",
+    tombstoneWindow: "1d",
+    minCompactionLag: "0s",
+    maxCompactionLag: "none",
+    copies: 1,
+    minInSync: 1,
+};
+const MostCopies = 3;
+const WarningThresholdMs = 30 * 86400000;
+const DurationUnits = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+/** Milliseconds, Infinity for everything; NaN for words that are not a duration. */
+const millis = (text) => {
+    if (text === "everything" || text === "none")
+        return Infinity;
+    const m = /^([0-9]{1,15})(ms|s|m|h|d)$/.exec(text.trim());
+    return m ? Number(m[1]) * DurationUnits[m[2]] : NaN;
+};
+const SizeUnits = { B: 1, KiB: 1024, MiB: 1024 ** 2, GiB: 1024 ** 3, TiB: 1024 ** 4 };
+const bytes = (text) => {
+    if (text === "none")
+        return Infinity;
+    const m = /^([0-9]{1,15})(B|KiB|MiB|GiB|TiB)$/.exec(text.trim());
+    return m ? Number(m[1]) * SizeUnits[m[2]] : NaN;
+};
+/** What a change removes, in the control plane's words, or nothing. */
+const removalOf = (before, after) => {
+    const deletes = after.cleanup !== "compact";
+    const parts = [];
+    const shorter = deletes && millis(after.retention) < millis(before.retention);
+    if (shorter)
+        parts.push(`messages older than ${after.retention}`);
+    if (!shorter && deletes && before.cleanup === "compact" && Number.isFinite(millis(after.retention)))
+        parts.push(`messages older than ${after.retention}, which compaction kept`);
+    if (deletes && bytes(after.retentionSize) < bytes(before.retentionSize))
+        parts.push(`messages beyond ${after.retentionSize} on a partition`);
+    return parts.length > 0 ? parts.join("; ") : undefined;
+};
+const checkOnTheWire = (c) => ({ service: c.service, component: c.component, direction: c.direction, stated: c.stated ?? null, state: c.state });
+/** A stable fingerprint of the right shape; the control plane's is RFC 8785 over the document, which the fake need not reproduce. */
+function fakeFingerprint(schema) {
+    const text = JSON.stringify(schema);
+    let h1 = 0x811c9dc5;
+    let h2 = 0x01000193;
+    for (let i = 0; i < text.length; i++) {
+        h1 = Math.imul(h1 ^ text.charCodeAt(i), 0x01000193) >>> 0;
+        h2 = Math.imul(h2 + text.charCodeAt(i), 0x9e3779b1) >>> 0;
+    }
+    const hex = (h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0")).repeat(4);
+    return `sha256:${hex}`;
+}
+/** The hostings whose pods hold the platform's container beside the developer's. */
+const twoContainers = (hosting) => hosting === "process" || hosting === "web";
 class HttpError extends Error {
     status;
     constructor(status, message) {
@@ -42,11 +126,15 @@ export async function fakeControlPlane(options = {}) {
     const services = new Map();
     const tokens = new Map();
     const tombstones = new Set();
+    const grants = new Map();
+    const machines = new Map();
     const visited = new Set();
     const counts = new Map();
     const scripted = new Map();
     let hideNew = false;
     let base = "";
+    let objectStore = "garage";
+    let cloud = null;
     const serviceKey = (p, n) => `${p}/${n}`;
     // ── Views of state ─────────────────────────────────────────────────────────
     const orgSummary = (org, caller) => {
@@ -68,6 +156,34 @@ export async function fakeControlPlane(options = {}) {
         };
     };
     const registrySummary = (r) => r ? { server: r.server, username: r.username, setAt: r.setAt, setBy: r.setBy ?? null } : null;
+    /** An apply, or a rollback when `rolledBackTo` is given: a new generation with this descriptor. */
+    const record = (s, descriptor, by, rolledBackTo) => {
+        const d = descriptor;
+        s.generation += 1;
+        s.image = d.service?.image ?? "";
+        // Object storage (feature 034), from the descriptor, so a rolled-back one says what it said then.
+        s.provisionObjectStorage = d.service?.provisionObjectStorage ?? false;
+        s.exposeObjectStorage = d.service?.exposeObjectStorage ?? false;
+        s.ownObjectStore = (d.service?.env ?? []).some((e) => e.name.startsWith("ANKKA_S3_"));
+        if (s.provisionObjectStorage && !s.objectStore) {
+            s.objectStore = objectStore;
+            if (objectStore === "gcs")
+                s.bucketLocation = projects.get(s.projectId)?.location ?? "europe-west2";
+        }
+        s.desiredInstances = d.service?.resources?.autoscaling?.minInstances ?? 1;
+        s.lifecycle = s.paused ? "Paused" : "UpdateInProgress";
+        s.descriptor = descriptor;
+        s.kept = [{ generation: s.generation, descriptor }, ...s.kept].slice(0, 50);
+        s.history.push({
+            kind: rolledBackTo === undefined ? "applied" : "rolled-back",
+            generation: s.generation,
+            actor: by,
+            at: now(),
+            image: s.image,
+            digest: digestOf(descriptor),
+            ...(rolledBackTo === undefined ? {} : { rolledBackTo }),
+        });
+    };
     const serviceStatus = (s) => {
         const org = organizations.get(projects.get(s.projectId)?.organizationId ?? "");
         const suspended = org?.disabled ?? false;
@@ -81,15 +197,64 @@ export async function fakeControlPlane(options = {}) {
             desiredInstances: s.desiredInstances,
             detail: s.detail ?? null,
             confirmed: true,
-            database: "provisioned",
+            database: s.hosting === "web" ? "none" : s.database,
             hostname: s.exposed ? `https://${s.name}-${s.projectId}.${options.baseDomain ?? "example.test"}` : null,
             exposed: s.exposed,
             suspended,
             paused: s.paused,
-            hosting: "embedded",
+            hosting: s.hosting ?? "embedded",
+            databaseCluster: s.databaseCluster ?? null,
             protocol: null,
+            mounts: s.mounts ?? [],
+            callers: s.callers ?? [],
+            processPort: s.processPort ?? null,
+            broker: s.broker ?? null,
+            undeclaredTopics: s.undeclaredTopics ?? null,
+            topicChecks: s.topicChecks ? s.topicChecks.map(checkOnTheWire) : null,
+            topicSources: s.topicSources ? s.topicSources.map(topicSourceOnTheWire) : null,
+            warnings: warningsOf(s),
+            objectStorage: s.provisionObjectStorage ? "provisioned" : s.ownObjectStore ? "supplied" : null,
+            bucket: s.provisionObjectStorage ? `${s.projectId}.${s.name}` : null,
+            bucketAddress: s.provisionObjectStorage && s.exposeObjectStorage
+                ? `https://storage.${options.baseDomain ?? "example.test"}/${s.projectId}.${s.name}`
+                : null,
+            objectStore: s.provisionObjectStorage ? (s.objectStore ?? "garage") : null,
+            bucketLocation: s.provisionObjectStorage && s.objectStore === "gcs" ? (s.bucketLocation ?? null) : null,
+            softDeleteDays: s.provisionObjectStorage && s.objectStore === "gcs" ? 7 : null,
+            storageMove: s.storageMove ?? null,
+            customHostnames: (s.customHostnames ?? []).map((hostname) => ({
+                hostname,
+                // The fake has no authority to wait for: an exposed service's hostnames serve at once.
+                state: s.exposed ? "serving" : "pending",
+                ...(s.exposed ? {} : { reason: "the service is not exposed" }),
+                ...(hostname.split(".").length === 2
+                    ? { note: "an apex cannot be a CNAME; this installation has published no address" }
+                    : { record: { name: hostname, kind: "CNAME", value: `${s.name}-${s.projectId}.${options.baseDomain ?? "example.test"}` } }),
+            })),
         };
     };
+    /** A read of one service carries the proof record its project's custom hostnames need. */
+    const oneService = (s) => ({
+        ...serviceStatus(s),
+        proofRecord: { name: "_ankka.<hostname>", kind: "TXT", value: `ankka-project=${s.projectId}` },
+    });
+    /** The control plane's refusals 1 to 5 (contracts/control-plane.md), in its words. */
+    const hostnameProblem = (requested) => {
+        const h = requested.trim().toLowerCase().replace(/\.$/, "");
+        const base = options.baseDomain ?? "example.test";
+        if (/[\/:\s]/.test(h))
+            return `a custom hostname is a name alone: '${requested}' has a scheme, a path or a port`;
+        if (h.includes("*"))
+            return "a custom hostname cannot be a wildcard";
+        const bad = h.split(".").find((l) => !/^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/.test(l));
+        if (bad !== undefined)
+            return `'${h}' is not a hostname: label '${bad}' must be letters, digits and '-', and cannot start or end with '-'`;
+        if (h.split(".").length < 2)
+            return `'${h}' is not a name on the internet: a custom hostname has at least two labels`;
+        if (h === base || h.endsWith(`.${base}`))
+            return `a custom hostname cannot be under the base domain '${base}': those names are the platform's`;
+        return null;
+    };
     // ── Authorization, the control plane's rules ──────────────────────────────
     const isAdmin = (c) => c.admin;
     function claimInvitations(c) {
@@ -112,6 +277,29 @@ export async function fakeControlPlane(options = {}) {
             throw new HttpError(404, `organization '${id}' not found`);
         return { org, role: member?.role };
     }
+    /**
+     * A warning for each view reading a topic its project declares to keep less than the installation's
+     * threshold (feature 043), worked out from the declarations as they are now, as the control plane does.
+     */
+    function warningsOf(s) {
+        const topics = projects.get(s.projectId)?.topics;
+        const warnings = (s.topicSources ?? []).flatMap((source) => {
+            const settings = topics?.get(source.topic)?.settings;
+            if (source.kind !== "view" || !settings || settings.cleanup !== "delete")
+                return [];
+            if (!(millis(settings.retention) < WarningThresholdMs))
+                return [];
+            return [
+                {
+                    kind: "retention",
+                    component: source.component,
+                    topic: source.topic,
+                    message: `view '${source.component}' reads topic '${source.topic}', which keeps ${settings.retention}; the installation warns below 30d`,
+                },
+            ];
+        });
+        return warnings.length > 0 ? warnings : null;
+    }
     function requireWrite(org) {
         if (org.disabled)
             throw new HttpError(409, `organization '${org.id}' is disabled`);
@@ -165,6 +353,26 @@ export async function fakeControlPlane(options = {}) {
                     .map((o) => ({ id: o.id, name: o.name, role: o.members.get(c.subject).role })),
         };
     });
+    // Feature 044: what the installation is. The wrapping key's name is shown only to an owner of an
+    // organization or a platform administrator, as the control plane decides in its endpoint.
+    route("GET", "/installation", (c) => {
+        const owns = isAdmin(c) || [...organizations.values()].some((o) => o.members.get(c.subject)?.role === "owner");
+        const { kmsKey, ...where } = cloud ?? { provider: "", account: "", location: "" };
+        return {
+            platformVersion: "0.0.0-fake",
+            ...(cloud ? { cloud: { ...where, ...(kmsKey && owns ? { kmsKey } : {}) } } : {}),
+            // Feature 038: where secrets are kept, as an installation that has said nothing answers.
+            secrets: { backend: "postgres", recordRetention: "365d", auditLog: "unknown" },
+            // Feature 041: where the backups go, as an installation with Garage and no copy says it.
+            backups: {
+                backupTarget: "object-store",
+                retentionDays: 30,
+                copyRequired: false,
+                sharesFailureDomain: true,
+                encryption: "none: Garage holds no key the archiver can send",
+            },
+        };
+    });
     route("GET", "/organizations", (c) => {
         claimInvitations(c);
         return [...organizations.values()]
@@ -432,11 +640,777 @@ export async function fakeControlPlane(options = {}) {
         project.registry = undefined;
         return "done";
     });
+    // A project's bucket location (feature 039): only where new buckets are made in Google Cloud Storage.
+    const requireGcs = () => {
+        if (objectStore !== "gcs")
+            throw new HttpError(409, "the installation keeps new buckets in Garage, which has no location to choose");
+    };
+    route("PUT", "/projects/{projectId}/location", (c, p, body) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        const location = (body.location ?? "").trim();
+        if (location === "")
+            throw new HttpError(400, "a location must name something");
+        requireGcs();
+        project.location = location;
+        return "done";
+    });
+    route("DELETE", "/projects/{projectId}/location", (c, p) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        requireGcs();
+        project.location = undefined;
+        return "done";
+    });
+    // Project secrets: the control plane's rules, its merge, and names only in what it answers.
+    const SecretName = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
+    const EntryName = /^[A-Za-z0-9._-]{1,253}$/;
+    const PlatformSuffixes = ["-db", "-cluster-tls", "-service-tls", "-database-tls", "-secret-key", "-mount-tls", "-storage"];
+    route("PUT", "/projects/{projectId}/secrets/{name}", (c, p, body) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        const name = p.name;
+        const entries = (body.entries ?? {});
+        const problems = [];
+        if (!SecretName.test(name) || name.length > 253)
+            problems.push(`project secret name '${name}' must be lowercase letters, digits, '-' and '.', begin and end with a letter or digit, and be at most 253 characters`);
+        else if (name.startsWith("ankka-") || PlatformSuffixes.some((s) => name.endsWith(s)))
+            problems.push(`project secret name '${name}' is one the platform uses for its own Secrets in a project`);
+        if (Object.keys(entries).length === 0)
+            problems.push("a project secret is set with at least one entry");
+        for (const [entry, value] of Object.entries(entries)) {
+            if (!EntryName.test(entry))
+                problems.push(`entry name '${entry}' must be 1 to 253 letters, digits, '.', '_' or '-'`);
+            if (value === "")
+                problems.push(`entry '${entry}' must not be empty`);
+        }
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        project.secrets ??= new Map();
+        const held = project.secrets.get(name)?.entries ?? new Map();
+        for (const [entry, value] of Object.entries(entries))
+            held.set(entry, value);
+        project.secrets.set(name, { entries: held, setAt: now(), setBy: c.name ?? c.subject });
+        return "done";
+    });
+    route("DELETE", "/projects/{projectId}/secrets/{name}", (c, p, _body, url) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        const entry = url.searchParams.get("entry") ?? "";
+        const secret = project.secrets?.get(p.name);
+        if (!secret?.entries.has(entry))
+            throw new HttpError(404, `project secret '${p.name}' has no entry '${entry}'`);
+        // A broker's credential is not pulled from under it: the broker goes first.
+        const naming = [...(project.brokers ?? new Map()).entries()].filter(([, b]) => b.secret === p.name && brokerNeeds(b.shape).includes(entry)).map(([name]) => `'${name}'`);
+        if (naming.length > 0)
+            throw new HttpError(409, `project secret '${p.name}' is the credential of broker ${naming.sort().join(", ")}; remove the broker first`);
+        secret.entries.delete(entry);
+        return "done";
+    });
+    route("GET", "/projects/{projectId}/secrets", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        return [...(project.secrets ?? new Map()).entries()]
+            .filter(([, s]) => s.entries.size > 0)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, s]) => ({ name, entries: [...s.entries.keys()].sort(), setAt: s.setAt, setBy: s.setBy }));
+    });
+    // Project topics: the control plane's rules, one declaration per name, never fewer partitions.
+    const TopicName = /^[a-z0-9]([a-z0-9.-]{0,98}[a-z0-9])?$/;
+    const TopicNameRule = 'a name is lower-case letters, digits, "-" and ".", starting and ending with a letter or digit, at most 100 characters';
+    const ContractName = /^[a-z0-9][a-z0-9._-]{0,98}[a-z0-9]$/;
+    const ContractNameRule = "[a-z0-9][a-z0-9._-]{0,98}[a-z0-9]";
+    route("PUT", "/projects/{projectId}/topics/{name}", (c, p, body) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        const name = p.name;
+        const request = body;
+        project.topics ??= new Map();
+        const current = project.topics.get(name);
+        if (request.partitions === undefined && current === undefined)
+            throw new HttpError(400, `topic '${name}': partitions is required for a new topic`);
+        const partitions = request.partitions === undefined ? current.partitions : Number(request.partitions);
+        const problems = [];
+        if (!TopicName.test(name))
+            problems.push(`topic '${name}': ${TopicNameRule}`);
+        if (!Number.isInteger(partitions) || partitions < 1 || partitions > 1000)
+            problems.push(`topic '${name}': partitions ${partitions} is outside the range 1-1000`);
+        // Settings (feature 043): the words, the bounds, fixed copies and an owner's removal.
+        for (const key of ["retention", "tombstoneWindow", "minCompactionLag", "maxCompactionLag"]) {
+            const value = request[key];
+            if (value !== undefined && Number.isNaN(millis(value)))
+                problems.push(`topic '${name}': ${key} "${value}" is not a duration`);
+        }
+        if (request.retentionSize !== undefined && Number.isNaN(bytes(request.retentionSize)))
+            problems.push(`topic '${name}': retentionSize "${request.retentionSize}" is not a size`);
+        if (request.cleanup !== undefined && !["delete", "compact", "compact,delete"].includes(request.cleanup))
+            problems.push(`topic '${name}': cleanup "${request.cleanup}" is not "delete", "compact" or "compact,delete"`);
+        if (request.compacted === true && request.cleanup === "delete")
+            problems.push(`topic '${name}': compacted and cleanup disagree`);
+        if (request.copies !== undefined && request.copies > MostCopies)
+            problems.push(`topic '${name}': copies ${request.copies} is more than the installation's most, ${MostCopies}`);
+        // A contract's own rules: its name, and a schema that is a JSON document (feature 037).
+        if (request.contract !== undefined && request.contract !== null) {
+            const contractName = String(request.contract.name ?? "");
+            if (!ContractName.test(contractName))
+                problems.push(`topic '${name}': contract name '${contractName}' is not ${ContractNameRule}`);
+            if (request.contract.schema === undefined || request.contract.schema === null)
+                problems.push(`topic '${name}': the contract's schema is missing`);
+        }
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        const has = current?.partitions;
+        if (has !== undefined && has > partitions)
+            throw new HttpError(409, `topic '${name}' has ${has} partitions and cannot have fewer; ${partitions} was asked`);
+        const asked = {};
+        for (const key of SettingNames)
+            if (request[key] !== undefined)
+                asked[key] = request[key];
+        if (request.compacted === true && asked.cleanup === undefined)
+            asked.cleanup = "compact";
+        const before = current?.settings;
+        if (before !== undefined) {
+            const fixed = (key) => asked[key] !== undefined && asked[key] !== before[key];
+            if (fixed("copies") || fixed("minInSync"))
+                throw new HttpError(409, `topic '${name}': copies and minimum in-sync copies are fixed when a topic is declared`);
+        }
+        const settings = { ...(before ?? TopicDefaults), ...asked };
+        const defaulted = (current?.defaulted ?? (before ? [] : [...SettingNames])).filter((s) => asked[s] === undefined);
+        const removal = before ? removalOf(before, settings) : undefined;
+        if (removal === undefined && request.removes !== undefined)
+            throw new HttpError(400, `topic '${name}': this declaration removes nothing`);
+        if (removal !== undefined) {
+            const { role } = requireOrg(c, org.id);
+            if (role !== "owner" && !isAdmin(c))
+                throw new HttpError(403, `owner role required: this declaration removes ${removal}`);
+            if (request.removes?.trim() !== removal)
+                throw new HttpError(400, `this declaration removes ${removal}; a declaration that removes messages says so with "removes"`);
+        }
+        const changes = before
+            ? SettingNames.flatMap((s) => String(before[s] ?? "the broker's") === String(settings[s] ?? "the broker's")
+                ? []
+                : [{ setting: s, from: String(before[s] ?? "the broker's"), to: String(settings[s] ?? "the broker's") }])
+            : [];
+        const contract = request.contract
+            ? { name: String(request.contract.name), schema: request.contract.schema, fingerprint: fakeFingerprint(request.contract.schema) }
+            : undefined;
+        const same = current !== undefined && current.partitions === partitions && changes.length === 0 &&
+            (current.contract?.fingerprint ?? null) === (contract?.fingerprint ?? null);
+        if (same)
+            return "done";
+        project.topics.set(name, {
+            ...(current ?? {}),
+            partitions,
+            compacted: settings.cleanup !== "delete",
+            contract,
+            settings,
+            defaulted,
+        });
+        project.history = [
+            { kind: current ? "topic-changed" : "topic-declared", topic: name, actor: actor(c), at: now(), changes },
+            ...(project.history ?? []),
+        ].slice(0, 50);
+        return "done";
+    });
+    // The schema a topic's contract was declared with (feature 037); 404 without a contract.
+    route("GET", "/projects/{projectId}/topics/{name}/schema", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        const topic = project.topics?.get(p.name);
+        if (!topic?.contract)
+            throw new HttpError(404, `project '${p.projectId}' declares no contract on topic '${p.name}'`);
+        return topic.contract.schema;
+    });
+    route("DELETE", "/projects/{projectId}/topics/{name}", (c, p) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        if (!project.topics?.delete(p.name))
+            throw new HttpError(404, `project '${p.projectId}' declares no topic '${p.name}'`);
+        return "done";
+    });
+    route("GET", "/projects/{projectId}/topics", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        // The sides the project's services were seeded with, by topic: the control plane reads them
+        // from every service's instances; the fake reads them from what it was told.
+        const checks = [...services.values()].filter((s) => s.projectId === p.projectId).flatMap((s) => s.topicChecks ?? []);
+        return [...(project.topics ?? new Map()).entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, t]) => ({
+            name,
+            partitions: t.partitions,
+            phase: t.phase,
+            detail: t.detail,
+            compacted: t.compacted ?? false,
+            contract: t.contract ? { name: t.contract.name, fingerprint: t.contract.fingerprint } : null,
+            checks: t.contract ? checks.filter((c) => c.topic === name).map(checkOnTheWire) : [],
+            settings: t.settings
+                ? {
+                    ...t.settings,
+                    copies: t.settings.copies ?? null,
+                    minInSync: t.settings.minInSync ?? null,
+                    defaulted: (t.defaulted ?? []).filter((s) => SettingNames.includes(s)),
+                }
+                : null,
+            copiesHeld: t.copiesHeld ?? t.settings?.copies ?? null,
+            brokerNodes: null,
+        }));
+    });
+    // Declared brokers (feature 037): the control plane's rules, and the secret's entries checked by name.
+    const BrokerBootstrap = /^[A-Za-z0-9._-]+:[0-9]+(,[A-Za-z0-9._-]+:[0-9]+)*$/;
+    route("PUT", "/projects/{projectId}/brokers/{name}", (c, p, body) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        const name = p.name;
+        const request = body;
+        const bootstrap = String(request.bootstrap ?? "").trim();
+        const shape = String(request.shape ?? "");
+        const secret = String(request.secret ?? "");
+        const problems = [];
+        if (!TopicName.test(name))
+            problems.push(`broker '${name}': ${TopicNameRule}`);
+        if (!BrokerBootstrap.test(bootstrap))
+            problems.push(`broker '${name}': bootstrap '${bootstrap}' is not host:port[,host:port]`);
+        if (shape !== "certificate" && shape !== "sasl")
+            problems.push(`broker '${name}': shape '${shape}' is not one of certificate, sasl`);
+        if (secret === "")
+            problems.push(`broker '${name}': secret a project secret needs a name`);
+        else if (secret.startsWith("ankka-") || PlatformSuffixes.some((s) => secret.endsWith(s)))
+            problems.push(`broker '${name}': secret project secret name '${secret}' is one the platform uses for its own Secrets in a project`);
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        const held = project.secrets?.get(secret);
+        if (!held)
+            throw new HttpError(400, `project '${p.projectId}' has no project secret '${secret}'`);
+        const missing = brokerNeeds(shape).filter((e) => !held.entries.has(e));
+        if (missing.length > 0)
+            throw new HttpError(400, `project secret '${secret}' lacks ${missing.map((m) => `'${m}'`).join(", ")}, which shape '${shape}' needs`);
+        project.brokers ??= new Map();
+        const declaredAt = project.brokers.get(name)?.declaredAt ?? now();
+        project.brokers.set(name, { bootstrap, shape, secret, declaredAt });
+        return "done";
+    });
+    route("DELETE", "/projects/{projectId}/brokers/{name}", (c, p) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        if (!project.brokers?.delete(p.name))
+            throw new HttpError(404, `project '${p.projectId}' declares no broker '${p.name}'`);
+        return "done";
+    });
+    route("GET", "/projects/{projectId}/brokers", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        return [...(project.brokers ?? new Map()).entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([name, b]) => ({ name, bootstrap: b.bootstrap, shape: b.shape, secret: b.secret, declaredAt: b.declaredAt }));
+    });
+    // Backups and recovery (feature 041). The fake's project database is backed up from a day ago to
+    // now, and a restore is verified the moment it is asked for, holding every service's database.
+    const restoreView = (project, r) => ({
+        name: r.name,
+        line: r.line,
+        moment: r.moment,
+        phase: [...services.values()].some((s) => s.projectId === project.id && s.databaseCluster === r.name) ? "InUse" : "Verified",
+        requestedBy: r.requestedBy,
+        requestedAt: r.requestedAt,
+        reachedAt: r.moment,
+        services: [...services.values()]
+            .filter((s) => s.projectId === project.id)
+            .map((s) => ({ name: s.name, present: true, journalRows: 1, highestSequence: 1 })),
+    });
+    const remember = (project, kind, c, detail) => {
+        project.databaseHistory ??= [];
+        project.databaseHistory.unshift({ kind, by: c.name ?? c.subject, at: now(), detail });
+    };
+    let hold;
+    route("GET", "/installation/restore", () => hold
+        ? { held: hold.releasedAt === undefined, targetTime: hold.targetTime, restoredAt: hold.targetTime, releasedAt: hold.releasedAt, releasedBy: hold.releasedBy, services: hold.releasedAt ? [] : (hold.services ?? []) }
+        : { held: false });
+    route("POST", "/installation/restore/release", (c) => {
+        if (!isAdmin(c))
+            throw new HttpError(403, "only a platform administrator releases a held control plane");
+        if (hold && hold.releasedAt === undefined)
+            hold = { ...hold, releasedAt: now(), releasedBy: c.name ?? c.subject };
+        return hold ? { held: false, targetTime: hold.targetTime, releasedAt: hold.releasedAt, releasedBy: hold.releasedBy } : { held: false };
+    });
+    route("GET", "/projects/{projectId}/restores", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        return (project.restores ?? []).map((r) => restoreView(project, r));
+    });
+    route("POST", "/projects/{projectId}/backups/credential", (c, p) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireOwner(c, org.id);
+        project.credentialGeneration = (project.credentialGeneration ?? 0) + 1;
+        remember(project, "backup-credential-reissued", c, `generation ${project.credentialGeneration}`);
+        return { project: project.id, generation: project.credentialGeneration };
+    });
+    // One history, newest first: the database's (feature 041) and the topics' (feature 043).
+    route("GET", "/projects/{projectId}/history", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        const topics = (project.history ?? []).map((h) => ({
+            kind: h.kind,
+            by: h.actor ? (h.actor.display ?? h.actor.subject) : undefined,
+            at: h.at,
+            topic: h.topic,
+            changes: h.changes,
+        }));
+        return [...(project.databaseHistory ?? []), ...topics].sort((a, b) => (b.at ?? "").localeCompare(a.at ?? ""));
+    });
+    route("GET", "/projects/{projectId}/database", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        return project.database ?? { replicas: 0, synchronous: false };
+    });
+    route("PUT", "/projects/{projectId}/database", (c, p, body) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        const b = body;
+        const setting = { replicas: b.replicas ?? 0, synchronous: b.synchronous ?? false, retentionDays: b.retentionDays, rehearse: b.rehearse };
+        const problems = [];
+        if (setting.replicas < 0 || setting.replicas > 4)
+            problems.push(`replicas must be between 0 and 4, not ${setting.replicas}`);
+        if (setting.synchronous && setting.replicas === 0)
+            problems.push("a synchronous database needs at least one replica to wait for");
+        if (setting.retentionDays !== undefined && setting.retentionDays < 30)
+            problems.push(`backups are kept at least 30 days on this installation, not ${setting.retentionDays}`);
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        project.database = setting;
+        remember(project, "database-set", c, `${setting.replicas} replica${setting.replicas === 1 ? "" : "s"}${setting.synchronous ? ", synchronous" : ""}`);
+        return setting;
+    });
+    const minuteName = (prefix) => `ankka-db-${prefix}${new Date().toISOString().replace(/[^0-9]/g, "").slice(0, 12)}`;
+    route("GET", "/projects/{projectId}/status", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        const day = new Date(Date.now() - 86_400_000).toISOString();
+        const onCluster = (name) => [...services.values()].filter((s) => s.projectId === project.id && (s.databaseCluster ?? "ankka-db") === name).map((s) => s.name);
+        const restores = project.restores ?? [];
+        return {
+            id: project.id,
+            backedUp: true,
+            target: "object-store",
+            lines: [{ line: "ankka-db", cluster: "ankka-db", phase: "backing up", lastBaseBackup: day, firstRestorable: day, lastRestorable: now() }],
+            database: { cluster: "ankka-db", instances: 1, readyInstances: 1, primary: "ankka-db-1" },
+            clusters: [
+                { name: "ankka-db", line: "ankka-db", phase: onCluster("ankka-db").length === 0 && restores.length > 0 ? "left" : "live", services: onCluster("ankka-db") },
+                ...restores.map((r) => ({ name: r.name, line: r.line, phase: "restore", services: onCluster(r.name), since: r.requestedAt })),
+            ],
+            restores: restores.map((r) => restoreView(project, r)),
+        };
+    });
+    route("POST", "/projects/{projectId}/restores", (c, p, body) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireOwner(c, org.id);
+        const request = body;
+        const moment = String(request.moment ?? "");
+        if (Number.isNaN(Date.parse(moment)) || Date.parse(moment) > Date.now() || Date.parse(moment) < Date.now() - 86_400_000)
+            throw new HttpError(400, `${project.id} can be restored between ${new Date(Date.now() - 86_400_000).toISOString()} and ${now()}`);
+        project.restores ??= [];
+        const restore = { name: minuteName("r"), line: request.line ?? "ankka-db", moment, requestedBy: c.name ?? c.subject, requestedAt: now() };
+        if (project.restores.some((r) => r.name === restore.name))
+            throw new HttpError(409, `a restore of ${project.id} is in progress: ${restore.name}`);
+        project.restores.push(restore);
+        remember(project, "restore-requested", c, `${restore.name}, of ${restore.line} at ${moment}`);
+        return { ...restoreView(project, restore), phase: "Restoring", services: [] };
+    });
+    route("GET", "/projects/{projectId}/restores/{name}", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        const restore = project.restores?.find((r) => r.name === p.name);
+        if (!restore)
+            throw new HttpError(404, `${project.id} has no restore named ${p.name}`);
+        return restoreView(project, restore);
+    });
+    route("POST", "/projects/{projectId}/rehearsals", (c, p) => {
+        const { project, org } = requireProject(c, p.projectId);
+        requireWrite(org);
+        project.rehearsals ??= [];
+        const rehearsal = { name: minuteName("x"), line: "ankka-db", moment: now(), requestedBy: c.name ?? c.subject, requestedAt: now() };
+        project.rehearsals.push(rehearsal);
+        remember(project, "rehearsal-requested", c, rehearsal.name);
+        return { ...rehearsal, outcome: "Running" };
+    });
+    route("GET", "/projects/{projectId}/rehearsals", (c, p) => {
+        const { project } = requireProject(c, p.projectId);
+        return (project.rehearsals ?? []).map((r) => ({ ...r, outcome: "Completed", elapsedSeconds: 118 }));
+    });
+    route("POST", "/services/{projectId}/{name}/switch", (c, p, body) => {
+        const { service, org } = requireService(c, p.projectId, p.name);
+        requireOwner(c, org.id);
+        const cluster = String(body.cluster ?? "");
+        const project = projects.get(p.projectId);
+        if (cluster !== "ankka-db" && !project.restores?.some((r) => r.name === cluster))
+            throw new HttpError(400, `${cluster} is not a restore of ${p.projectId} that can be switched to`);
+        const next = cluster === "ankka-db" ? undefined : cluster;
+        if (next !== service.databaseCluster) {
+            service.databaseCluster = next;
+            service.generation += 1;
+        }
+        return serviceStatus(service);
+    });
+    // ── Grants (feature 040): the control plane's rules and words ─────────────
+    const display = (c) => c.name ?? c.email ?? c.subject;
+    const noSuchProject = (id) => new HttpError(404, `no such project '${id}'`);
+    /** A project's grants are read by its organization's members and written by its owners; an outsider is told there is no project. */
+    function grantProject(c, id, owner) {
+        const project = projects.get(id);
+        if (!project)
+            throw noSuchProject(id);
+        const org = organizations.get(project.organizationId);
+        const role = org?.members.get(c.subject)?.role;
+        if (!org || (!role && !isAdmin(c)))
+            throw noSuchProject(id);
+        if (owner) {
+            if (role !== "owner" && !isAdmin(c))
+                throw new HttpError(403, `owner role required in organization '${org.id}'`);
+            requireWrite(org);
+        }
+        return { project, org };
+    }
+    const parseGrantee = (text) => {
+        const m = /^(service|machine):([^/]+)\/([^/]+)$/.exec(text);
+        return m ? { kind: m[1], scope: m[2], name: m[3] } : null;
+    };
+    const HttpMethods = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+    const GrpcMethod = /^[A-Za-z_][A-Za-z0-9_.]*\/[A-Za-z_][A-Za-z0-9_]*$/;
+    const MachineNameRule = "lowercase letters, digits and '-', starting with a letter";
+    const machineNameProblems = (name) => name === "" ? ["a machine needs a name"] : NameRule.test(name) ? [] : [`machine name '${name}' is invalid: ${MachineNameRule}`];
+    /** Everything wrong with the grantee and the target, all at once, as `GrantRules.problems` words it. */
+    function grantProblems(grantee, t) {
+        const problems = [];
+        const g = parseGrantee(grantee);
+        if (!g)
+            problems.push(`grantee '${grantee}' is not "service:<project>/<service>" or "machine:<organization>/<name>"`);
+        else if (g.kind === "service") {
+            if (!NameRule.test(g.scope))
+                problems.push(`grantee: project id '${g.scope}' is invalid: lowercase letters, digits and '-', starting with a letter`);
+            if (!NameRule.test(g.name))
+                problems.push(`grantee: service name '${g.name}' is invalid`);
+        }
+        else {
+            if (!NameRule.test(g.scope))
+                problems.push(`grantee: organization '${g.scope}' cannot have machines: an organization's id is part of a machine's name on the broker, so it must be lowercase letters, digits and '-', starting with a letter`);
+            problems.push(...machineNameProblems(g.name).map((p) => `grantee: ${p}`));
+        }
+        const none = (field) => (t[field] !== undefined ? [`a ${t.kind} target has no ${field}`] : []);
+        switch (t.kind) {
+            case "route":
+                if (!t.service)
+                    problems.push("a route target needs a service");
+                if (!t.method || !HttpMethods.includes(t.method))
+                    problems.push(`a route target's method is one of ${HttpMethods.join(", ")}`);
+                if (!t.path?.startsWith("/"))
+                    problems.push("a route target's path is a template beginning with '/'");
+                problems.push(...none("topic"), ...none("right"));
+                break;
+            case "method":
+                if (!t.service)
+                    problems.push("a method target needs a service");
+                if (!t.method || !GrpcMethod.test(t.method))
+                    problems.push('a method target\'s method is a gRPC method, "<Service>/<Method>"');
+                problems.push(...none("path"), ...none("topic"), ...none("right"));
+                break;
+            case "topic":
+                if (!t.topic)
+                    problems.push("a topic target needs a topic");
+                else if (!TopicName.test(t.topic))
+                    problems.push(`topic '${t.topic}': ${TopicNameRule}`);
+                if (t.right !== "consume" && t.right !== "produce")
+                    problems.push("a topic target's right is one of consume, produce");
+                problems.push(...none("service"), ...none("method"), ...none("path"));
+                break;
+            case "erasure":
+                problems.push(...none("service"), ...none("method"), ...none("path"), ...none("topic"), ...none("right"));
+                break;
+            default:
+                problems.push(`target kind '${t.kind}' is not one of route, method, topic, erasure`);
+        }
+        if (t.service !== undefined && !NameRule.test(t.service))
+            problems.push(`target: service name '${t.service}' is invalid`);
+        if (t.decrypt && !(t.kind === "topic" && t.right === "consume"))
+            problems.push("only a grant to consume a topic may allow decryption");
+        return problems;
+    }
+    /** The target as the wire carries it: only the fields it has, and `decrypt` always. */
+    const targetOnTheWire = (t) => ({
+        kind: t.kind,
+        ...(t.service === undefined ? {} : { service: t.service }),
+        ...(t.method === undefined ? {} : { method: t.method }),
+        ...(t.path === undefined ? {} : { path: t.path }),
+        ...(t.topic === undefined ? {} : { topic: t.topic }),
+        ...(t.right === undefined ? {} : { right: t.right }),
+        decrypt: t.decrypt ?? false,
+    });
+    const sameTarget = (a, b) => JSON.stringify(targetOnTheWire(a)) === JSON.stringify(targetOnTheWire(b));
+    const live = (g) => g.state === "pending" || g.state === "accepted";
+    /**
+     * Whether a grant opens what it names, or why not, as `GrantEffect` reads it — short of the
+     * instances' topology, which the fake does not have: a service with a ready instance that is not
+     * web-hosted is taken to have the route and to have mounted its grants.
+     */
+    function effectOf(g) {
+        if (g.state !== "accepted")
+            return g.state;
+        if (g.target.kind === "route" || g.target.kind === "method") {
+            const s = services.get(serviceKey(g.projectId, g.target.service ?? ""));
+            if (!s)
+                return "route not seen";
+            if (s.hosting === "web")
+                return "route not grantable";
+            if (s.paused || s.readyInstances < 1)
+                return "route not seen";
+            return "in effect";
+        }
+        if (g.target.kind === "topic" && g.grantee.startsWith("machine:") && !options.brokerBootstrap)
+            return "broker not exposed";
+        return "in effect";
+    }
+    const grantDetail = (g, effect) => ({
+        id: g.id,
+        grantee: g.grantee,
+        target: targetOnTheWire(g.target),
+        state: g.state,
+        effect,
+        granted: g.granted,
+        ...(g.answered ? { answered: g.answered } : {}),
+        ...(g.ended ? { ended: g.ended } : {}),
+    });
+    const receivedDetail = (g) => {
+        const granting = projects.get(g.projectId);
+        const topic = g.target.kind === "topic" && g.target.topic ? granting?.topics?.get(g.target.topic) : undefined;
+        return {
+            id: g.id,
+            grantingProject: g.projectId,
+            grantingOrganization: granting?.organizationId ?? "",
+            grantee: g.grantee,
+            target: targetOnTheWire(g.target),
+            state: g.state,
+            changes: g.changes,
+            ...(topic ? { topic: { partitions: topic.partitions, compacted: topic.compacted ?? false } } : {}),
+        };
+    };
+    const byGranted = (a, b) => a.granted.at.localeCompare(b.granted.at) || a.id.localeCompare(b.id);
+    function makeGrant(project, org, grantee, target, by, state) {
+        const g = parseGrantee(grantee);
+        const granteeOrg = g.kind === "service" ? projects.get(g.scope)?.organizationId : g.scope;
+        const pending = granteeOrg !== org.id;
+        const at = now();
+        const grant = {
+            id: randomBytes(8).toString("hex"),
+            projectId: project.id,
+            grantee,
+            target,
+            state: state ?? (pending ? "pending" : "accepted"),
+            granted: { by, at },
+            changes: [{ change: pending ? "offered" : "made", by, at }],
+        };
+        grants.set(grant.id, grant);
+        return grant;
+    }
+    route("POST", "/projects/{projectId}/grants", (c, p, body) => {
+        const { project, org } = grantProject(c, p.projectId, true);
+        const b = (body ?? {});
+        const grantee = String(b.grantee ?? "");
+        const raw = b.target ?? { kind: "" };
+        const target = {
+            kind: String(raw.kind ?? ""),
+            service: raw.service ?? undefined,
+            method: raw.method ?? undefined,
+            path: raw.path ?? undefined,
+            topic: raw.topic ?? undefined,
+            right: raw.right ?? undefined,
+            decrypt: raw.decrypt === true,
+        };
+        const problems = grantProblems(grantee, target);
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        const g = parseGrantee(grantee);
+        if (g.kind === "service" && !projects.has(g.scope))
+            throw noSuchProject(g.scope);
+        if (g.kind === "machine" && !organizations.has(g.scope))
+            throw new HttpError(404, `no such organization '${g.scope}'`);
+        if (target.kind === "topic" && !project.topics?.has(target.topic))
+            throw new HttpError(404, `project '${project.id}' has not declared the topic '${target.topic}'`);
+        if (g.kind === "service" && g.scope === project.id)
+            throw new HttpError(400, "a project's own services need no grant: name them in the route's ACL instead");
+        // Granting what a live grant already grants answers that grant.
+        const existing = [...grants.values()].find((x) => x.projectId === project.id && x.grantee === grantee && live(x) && sameTarget(x.target, target));
+        const grant = existing ?? makeGrant(project, org, grantee, target, display(c));
+        return grantDetail(grant, grant.state === "accepted" ? "in effect" : grant.state);
+    });
+    route("GET", "/projects/{projectId}/grants", (c, p) => {
+        const { project } = grantProject(c, p.projectId, false);
+        return [...grants.values()]
+            .filter((g) => g.projectId === project.id)
+            .sort(byGranted)
+            .map((g) => grantDetail(g, effectOf(g)));
+    });
+    route("GET", "/projects/{projectId}/grants/received", (c, p) => {
+        const { project } = grantProject(c, p.projectId, false);
+        return [...grants.values()]
+            .filter((g) => g.grantee.startsWith(`service:${project.id}/`))
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map(receivedDetail);
+    });
+    route("DELETE", "/projects/{projectId}/grants/{grantId}", (c, p) => {
+        const { project } = grantProject(c, p.projectId, true);
+        const g = grants.get(p.grantId);
+        if (!g || g.projectId !== project.id)
+            throw new HttpError(404, `project '${project.id}' has no grant '${p.grantId}'`);
+        const [to, verb, applies] = g.state === "pending" ? ["withdrawn", "withdraw", "a pending"] : ["revoked", "revoke", "an accepted"];
+        if (g.state !== "pending" && g.state !== "accepted")
+            throw new HttpError(409, `grant '${g.id}' is ${g.state}; ${verb} applies to ${applies} grant`);
+        const at = now();
+        g.state = to;
+        g.ended = { by: display(c), at };
+        g.changes.push({ change: to, by: display(c), at });
+        return "done";
+    });
+    /** The grants naming one of the organization's machines, or a service of one of its projects. */
+    function offeredTo(org) {
+        const own = new Set([...projects.values()].filter((x) => x.organizationId === org.id).map((x) => x.id));
+        return [...grants.values()]
+            .filter((g) => {
+            const grantee = parseGrantee(g.grantee);
+            return grantee !== null && (grantee.kind === "machine" ? grantee.scope === org.id : own.has(grantee.scope));
+        })
+            .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    route("GET", "/organizations/{organizationId}/grants", (c, p) => {
+        const { org } = requireOrg(c, p.organizationId);
+        return offeredTo(org).map(receivedDetail);
+    });
+    /**
+     * An owner of the grantee's organization answers a grant: a member is 403, a grant not offered to
+     * the organization 404 whoever asks (its id discloses nothing), a grant in the wrong state 409.
+     */
+    const answers = {
+        accept: { from: "pending", to: "accepted", applies: "a pending" },
+        decline: { from: "pending", to: "declined", applies: "a pending" },
+        relinquish: { from: "accepted", to: "relinquished", applies: "an accepted" },
+    };
+    for (const [verb, rule] of Object.entries(answers)) {
+        route("POST", `/organizations/{organizationId}/grants/{grantId}/${verb}`, (c, p) => {
+            const org = requireOwner(c, p.organizationId);
+            requireWrite(org);
+            const g = offeredTo(org).find((x) => x.id === p.grantId);
+            if (!g)
+                throw new HttpError(404, `no grant '${p.grantId}' is offered to '${org.id}'`);
+            if (g.state !== rule.from)
+                throw new HttpError(409, `grant '${g.id}' is ${g.state}; ${verb} applies to ${rule.applies} grant`);
+            const at = now();
+            const act = { by: display(c), at };
+            g.state = rule.to;
+            if (verb !== "relinquish")
+                g.answered = act;
+            if (verb !== "accept")
+                g.ended = act;
+            g.changes.push({ change: rule.to, ...act });
+            return "done";
+        });
+    }
+    // ── Machines (feature 040): an owner registers, limits and deletes; a member lists ──
+    const machineKey = (o, n) => `${o}/${n}`;
+    // `ankka.controlplane.machines.byte-rate-ceiling`, 32 MiB a second unless the installation says otherwise.
+    const ByteRateCeiling = options.byteRateCeiling ?? 33_554_432;
+    const machineSummary = (m) => ({
+        name: m.name,
+        clientId: `machine:${m.organizationId}/${m.name}`,
+        registeredBy: m.registeredBy,
+        registeredAt: m.registeredAt,
+        ...(m.byteRates ? { byteRates: m.byteRates } : {}),
+    });
+    route("GET", "/organizations/{organizationId}/machines", (c, p) => {
+        const { org } = requireOrg(c, p.organizationId);
+        return [...machines.values()]
+            .filter((m) => m.organizationId === org.id && !m.hidden)
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map(machineSummary);
+    });
+    route("POST", "/organizations/{organizationId}/machines", (c, p, body) => {
+        const org = requireOwner(c, p.organizationId);
+        requireWrite(org);
+        const name = String(body?.name ?? "");
+        const problems = machineNameProblems(name);
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        if (machines.has(machineKey(org.id, name)))
+            throw new HttpError(409, `machine '${name}' is already registered on '${org.id}'`);
+        machines.set(machineKey(org.id, name), { organizationId: org.id, name, registeredBy: display(c), registeredAt: now(), hidden: hideNew });
+        return {
+            name,
+            clientId: `machine:${org.id}/${name}`,
+            // 32 random bytes as hex: the only time the secret exists outside the machine that holds it.
+            clientSecret: randomBytes(32).toString("hex"),
+            tokenUrl: `${base}/oauth/token`,
+            ...(options.brokerBootstrap ? { brokerBootstrap: options.brokerBootstrap } : {}),
+        };
+    });
+    route("DELETE", "/organizations/{organizationId}/machines/{name}", (c, p) => {
+        const org = requireOwner(c, p.organizationId);
+        requireWrite(org);
+        if (!machines.delete(machineKey(org.id, p.name)))
+            throw new HttpError(404, `no such machine '${machineKey(org.id, p.name)}'`);
+        return "done";
+    });
+    route("PUT", "/organizations/{organizationId}/machines/{name}/byte-rates", (c, p, body) => {
+        const org = requireOwner(c, p.organizationId);
+        requireWrite(org);
+        const b = (body ?? {});
+        const produce = Number(b.produceBytesPerSecond ?? 0);
+        const consume = Number(b.consumeBytesPerSecond ?? 0);
+        const percentage = Number(b.requestPercentage ?? 0);
+        if (![produce, consume, percentage].every(Number.isInteger))
+            throw new HttpError(400, "byte rates and the request percentage are whole numbers");
+        const rate = (label, value) => value <= 0 ? [`${label} must be more than nothing`] : value > ByteRateCeiling ? [`${label} of ${value} bytes a second is over the installation's ceiling of ${ByteRateCeiling}`] : [];
+        const problems = [
+            ...rate("the produce byte rate", produce),
+            ...rate("the consume byte rate", consume),
+            ...(percentage < 1 || percentage > 100 ? ["the request percentage is from 1 to 100"] : []),
+        ];
+        if (problems.length > 0)
+            throw new HttpError(400, problems.join("; "));
+        const m = machines.get(machineKey(org.id, p.name));
+        if (!m)
+            throw new HttpError(404, `no such machine '${machineKey(org.id, p.name)}'`);
+        m.byteRates = { produceBytesPerSecond: produce, consumeBytesPerSecond: consume, requestPercentage: percentage };
+        return machineSummary(m);
+    });
     route("GET", "/services/{projectId}", (c, p) => {
         requireProject(c, p.projectId);
         return [...services.values()].filter((s) => s.projectId === p.projectId).map(serviceStatus);
     });
-    route("GET", "/services/{projectId}/{name}", (c, p) => serviceStatus(requireService(c, p.projectId, p.name).service));
+    route("GET", "/services/{projectId}/{name}", (c, p) => oneService(requireService(c, p.projectId, p.name).service));
+    // Custom hostnames (feature 045). A name whose first label is `unproved` stands for one that does not
+    // carry the project's proof record.
+    route("PUT", "/services/{projectId}/{name}/hostnames/{hostname}", (c, p) => {
+        const { service: s, org } = requireService(c, p.projectId, p.name);
+        requireWrite(org);
+        const hostname = p.hostname.trim().toLowerCase().replace(/\.$/, "");
+        const problem = hostnameProblem(p.hostname);
+        if (problem !== null)
+            throw new HttpError(409, problem);
+        const held = s.customHostnames ?? [];
+        if (held.includes(hostname))
+            return oneService(s);
+        if (!s.exposed)
+            throw new HttpError(409, `service '${s.name}' is not exposed`);
+        if (held.length >= 5)
+            throw new HttpError(409, `service '${s.name}' holds 5 custom hostnames, the most a service can hold`);
+        const holder = [...services.values()].find((o) => o !== s && (o.customHostnames ?? []).includes(hostname));
+        if (holder)
+            throw new HttpError(409, `'${hostname}' is held by service '${holder.name}' in project '${holder.projectId}'`);
+        if (hostname.split(".")[0] === "unproved")
+            throw new HttpError(409, `'${hostname}' does not carry the proof record of project '${s.projectId}': create TXT _ankka.${hostname} with the value "ankka-project=${s.projectId}"`);
+        s.customHostnames = [...held, hostname];
+        s.history.push({ kind: "hostname added", generation: s.generation, actor: actor(c), at: now(), hostname });
+        return oneService(s);
+    });
+    route("DELETE", "/services/{projectId}/{name}/hostnames/{hostname}", (c, p) => {
+        const { service: s, org } = requireService(c, p.projectId, p.name);
+        if (!isAdmin(c))
+            requireWrite(org);
+        const hostname = p.hostname.trim().toLowerCase().replace(/\.$/, "");
+        if ((s.customHostnames ?? []).includes(hostname)) {
+            s.customHostnames = (s.customHostnames ?? []).filter((h) => h !== hostname);
+            s.history.push({ kind: isAdmin(c) ? "hostname taken away" : "hostname removed", generation: s.generation, actor: actor(c), at: now(), hostname });
+        }
+        return oneService(s);
+    });
     route("PUT", "/services/{projectId}/{name}", (c, p, body) => {
         const { org } = requireProject(c, p.projectId);
         requireWrite(org);
@@ -463,18 +1437,58 @@ export async function fakeControlPlane(options = {}) {
             desiredInstances: instances,
             exposed: false,
             paused: false,
+            database: "provisioned",
             history: [],
+            kept: [],
             logs: new Map(),
             previousLogs: new Map(),
+            platformLogs: new Map(),
         };
-        s.image = d.service.image;
-        s.generation += 1;
-        s.desiredInstances = instances;
-        s.lifecycle = s.paused ? "Paused" : "UpdateInProgress";
-        s.history.push({ kind: "applied", generation: s.generation, actor: actor(c), at: now() });
+        record(s, d, actor(c));
         services.set(key, s);
         return serviceStatus(s);
     });
+    // Rollbacks, by the control plane's rules: the same refusals, in the same words and statuses. The
+    // digest need only be equal for equal descriptors; it is not the control plane's.
+    const descriptorAt = (s, n) => {
+        if (!Number.isInteger(n) || n < 1 || n > s.generation)
+            throw new HttpError(404, `service '${s.name}' has no generation ${n}`);
+        const found = s.kept.find((k) => k.generation === n);
+        if (found)
+            return found;
+        const oldest = s.kept.at(-1);
+        const ran = s.kept.find((k) => k.generation < n);
+        if (oldest && ran && n > oldest.generation)
+            throw new HttpError(409, `generation ${n} was a restart and ran the descriptor of generation ${ran.generation}`);
+        throw new HttpError(409, `the descriptor of generation ${n} is no longer kept; the oldest kept is generation ${oldest?.generation ?? s.generation}`);
+    };
+    route("POST", "/services/{projectId}/{name}/rollback", (c, p, body) => {
+        const { service: s, org } = requireService(c, p.projectId, p.name);
+        requireWrite(org);
+        const named = body?.generation;
+        const current = digestOf(s.descriptor);
+        let target;
+        if (named !== undefined) {
+            target = descriptorAt(s, named);
+            if (digestOf(target.descriptor) === current)
+                throw new HttpError(409, `service '${s.name}' already has the descriptor of generation ${named}`);
+        }
+        else {
+            const differs = s.kept.find((k) => digestOf(k.descriptor) !== current);
+            if (!differs)
+                throw new HttpError(409, `service '${s.name}' has no earlier generation with a different descriptor`);
+            target = differs;
+        }
+        record(s, target.descriptor, actor(c), target.generation);
+        return { rolledBackTo: target.generation, status: serviceStatus(s) };
+    });
+    route("GET", "/services/{projectId}/{name}/descriptor", (c, p, _body, url) => {
+        const { service: s } = requireService(c, p.projectId, p.name);
+        const raw = url.searchParams.get("generation");
+        if (raw === null)
+            throw new HttpError(400, "query parameter 'generation' is required");
+        return descriptorAt(s, Number(raw)).descriptor;
+    });
     const operation = (op) => (c, p) => {
         const { service: s, org } = requireService(c, p.projectId, p.name);
         requireWrite(org);
@@ -508,14 +1522,62 @@ export async function fakeControlPlane(options = {}) {
     for (const op of ["pause", "resume", "restart", "expose", "unexpose"]) {
         route("POST", `/services/{projectId}/{name}/${op}`, operation(op));
     }
+    // A service's storage (feature 039): the control plane's refusals, and the history it records.
+    const moving = (s) => s.storageMove !== undefined && s.storageMove !== "moved" && s.storageMove !== "move failed";
+    route("POST", "/services/{projectId}/{name}/storage-credential", (c, p) => {
+        const { service: s, org } = requireService(c, p.projectId, p.name);
+        requireWrite(org);
+        if (!s.provisionObjectStorage)
+            throw new HttpError(409, `service '${s.name}' has no storage credential to reissue: its descriptor asks for no bucket`);
+        if (moving(s))
+            throw new HttpError(409, `the storage of service '${s.name}' is moving`);
+        s.history.push({ kind: "storage-credential-reissued", generation: s.generation, actor: actor(c), at: now() });
+        return serviceStatus(s);
+    });
+    route("POST", "/services/{projectId}/{name}/storage/settings", (c, p) => {
+        const { service: s, org } = requireService(c, p.projectId, p.name);
+        requireWrite(org);
+        if (!s.provisionObjectStorage || s.objectStore !== "gcs")
+            throw new HttpError(409, `the bucket of service '${s.name}' is not in Google Cloud Storage; settings are reapplied there only`);
+        s.history.push({ kind: "storage-settings-reapplied", generation: s.generation, actor: actor(c), at: now() });
+        return serviceStatus(s);
+    });
+    route("POST", "/services/{projectId}/{name}/storage/move", (c, p, body) => {
+        const { service: s, org } = requireService(c, p.projectId, p.name);
+        requireWrite(org);
+        if (objectStore !== "gcs")
+            throw new HttpError(409, "the installation keeps new buckets in Garage; there is nowhere to move a bucket to");
+        if (!s.provisionObjectStorage)
+            throw new HttpError(409, `service '${s.name}' has no bucket to move: its descriptor asks for none`);
+        if (moving(s))
+            throw new HttpError(409, `the storage of service '${s.name}' is moving`);
+        if (s.objectStore === "gcs")
+            throw new HttpError(409, `the bucket of service '${s.name}' is in Google Cloud Storage already`);
+        const bound = body?.writePauseBound ?? "10m";
+        const m = /^(\d+)([smh])$/.exec(bound);
+        if (!m)
+            throw new HttpError(400, `writePauseBound '${bound}' is not a duration such as 90s, 10m or 2h`);
+        const seconds = Number(m[1]) * (m[2] === "s" ? 1 : m[2] === "m" ? 60 : 3600);
+        if (seconds < 60 || seconds > 86400)
+            throw new HttpError(400, `writePauseBound '${bound}' is outside one minute to 24 hours`);
+        // As the control plane says it: how long the write pause may last, from the moment it is asked.
+        const unit = m[2] === "s" ? "second" : m[2] === "m" ? "minute" : "hour";
+        const words = `${m[1]} ${unit}${m[1] === "1" ? "" : "s"}`;
+        s.storageMove = `waiting for its bucket in Google Cloud Storage; its write pause may last ${words} at most`;
+        s.history.push({ kind: "storage-moved", generation: s.generation, actor: actor(c), at: now() });
+        return serviceStatus(s);
+    });
     route("GET", "/services/{projectId}/{name}/logs", (c, p, _body, url) => {
         const { service: s } = requireService(c, p.projectId, p.name);
         if (s.paused || s.readyInstances === 0 && s.logs.size === 0)
             throw new HttpError(404, `service '${s.name}' has no running instance`);
         const previous = url.searchParams.get("previous") === "true";
+        const platform = url.searchParams.get("platform") === "true";
+        if (platform && !twoContainers(s.hosting))
+            throw new HttpError(400, "--platform applies to a service with process or web hosting");
         const tail = url.searchParams.get("tail");
         const only = url.searchParams.get("instance");
-        const source = previous ? s.previousLogs : s.logs;
+        const source = platform ? s.platformLogs : previous ? s.previousLogs : s.logs;
         const names = s.readyInstances > 0 ? Array.from({ length: s.readyInstances }, (_x, i) => `${s.name}-${i}`) : [...source.keys()];
         return {
             instances: names
@@ -527,6 +1589,32 @@ export async function fakeControlPlane(options = {}) {
             }),
         };
     });
+    // The control plane's rules: a non-member is told the service does not exist; no running instance
+    // is the logs route's 404; one instance that is not ok makes the result partial.
+    route("GET", "/services/{projectId}/{name}/topology", (c, p) => {
+        const { service: s } = requireService(c, p.projectId, p.name);
+        if (s.paused || s.readyInstances === 0)
+            throw new HttpError(404, `service '${s.name}' has no running instance; it may be paused`);
+        const t = s.topology ?? {
+            instances: Array.from({ length: s.readyInstances }, (_x, i) => ({ pod: `${s.name}-${i}`, status: "ok" })),
+            nodes: [{ id: s.name, kind: "EventSourcedEntity", layer: 1, platform: false, handlers: [] }],
+            declared: [],
+            calls: [],
+        };
+        const contributing = t.instances.filter((i) => i.status === "ok").length;
+        return {
+            service: s.name,
+            running: t.instances.length,
+            contributing,
+            partial: contributing < t.instances.length,
+            instances: t.instances.map((i) => ({ pod: i.pod, status: i.status, problem: i.problem ?? null, runtime: i.status === "ok" ? "0.0.0" : null, readAt: i.status === "ok" ? now() : null })),
+            window: t.window ?? { seconds: 600, since: now(), calls: 0, unanswered: 0 },
+            nodes: t.nodes,
+            declared: t.declared,
+            calls: t.calls,
+            differences: t.differences ?? [],
+        };
+    });
     route("GET", "/services/{projectId}/{name}/history", (c, p) => requireService(c, p.projectId, p.name).service.history);
     route("DELETE", "/services/{projectId}/{name}", (c, p) => {
         const { service: s, org } = requireService(c, p.projectId, p.name);
@@ -650,6 +1738,12 @@ export async function fakeControlPlane(options = {}) {
                 }
             }
         },
+        scriptTopology(projectId, name, topology) {
+            const s = services.get(serviceKey(projectId, name));
+            if (!s)
+                throw new Error(`no service ${projectId}/${name}`);
+            s.topology = topology;
+        },
         appendLog(projectId, name, line, instance) {
             const s = services.get(serviceKey(projectId, name));
             if (!s)
@@ -670,9 +1764,17 @@ export async function fakeControlPlane(options = {}) {
                 o.hidden = false;
             for (const p of projects.values())
                 p.hidden = false;
+            for (const m of machines.values())
+                m.hidden = false;
         },
-        state: { organizations, projects, services, tokens, tombstones },
+        state: { organizations, projects, services, tokens, tombstones, grants, machines },
         seed(seed) {
+            if (seed.objectStore)
+                objectStore = seed.objectStore;
+            if (seed.cloud !== undefined)
+                cloud = seed.cloud;
+            if (seed.held)
+                hold = { ...seed.held, releasedAt: undefined, releasedBy: undefined };
             for (const o of seed.organizations ?? []) {
                 const members = new Map();
                 for (const s of o.owners ?? [])
@@ -688,8 +1790,13 @@ export async function fakeControlPlane(options = {}) {
                 const n = s.instances ?? 1;
                 const ready = lifecycle === "Ready" ? n : 0;
                 const logs = new Map();
-                for (let i = 0; i < ready; i++)
+                const platformLogs = new Map();
+                for (let i = 0; i < ready; i++) {
                     logs.set(`${s.name}-${i}`, [`${s.name} started`]);
+                    if (twoContainers(s.hosting))
+                        platformLogs.set(`${s.name}-${i}`, [`${s.hosting === "web" ? "proxy" : "sidecar"} of ${s.name} started`]);
+                }
+                const seeded = { name: s.name, service: { image: s.image ?? `${s.name}:latest` } };
                 services.set(serviceKey(s.projectId, s.name), {
                     name: s.name,
                     projectId: s.projectId,
@@ -698,13 +1805,76 @@ export async function fakeControlPlane(options = {}) {
                     image: s.image ?? `${s.name}:latest`,
                     readyInstances: ready,
                     desiredInstances: n,
-                    exposed: false,
+                    exposed: s.exposed ?? false,
                     paused: lifecycle === "Paused",
-                    history: [{ kind: "applied", generation: 1, at: now() }],
+                    database: s.database === undefined ? "provisioned" : s.database,
+                    history: [{ kind: "applied", generation: 1, at: now(), image: s.image ?? `${s.name}:latest`, digest: digestOf(seeded) }],
+                    descriptor: seeded,
+                    kept: [{ generation: 1, descriptor: seeded }],
                     logs,
                     previousLogs: new Map(),
+                    platformLogs,
+                    hosting: s.hosting,
+                    mounts: s.mounts,
+                    callers: s.callers,
+                    processPort: s.processPort,
+                    broker: s.broker,
+                    undeclaredTopics: s.undeclaredTopics,
+                    topicChecks: s.topicChecks,
+                    topicSources: s.topicSources,
+                    provisionObjectStorage: s.provisionObjectStorage,
+                    exposeObjectStorage: s.exposeObjectStorage,
+                    ownObjectStore: s.ownObjectStore,
+                    objectStore: s.objectStore,
+                    bucketLocation: s.bucketLocation,
+                });
+            }
+            for (const sec of seed.secrets ?? []) {
+                const project = projects.get(sec.projectId);
+                if (!project)
+                    throw new Error(`no project ${sec.projectId}`);
+                project.secrets ??= new Map();
+                const held = project.secrets.get(sec.name)?.entries ?? new Map();
+                for (const [entry, value] of Object.entries(sec.entries))
+                    held.set(entry, value);
+                project.secrets.set(sec.name, { entries: held, setAt: now(), setBy: "seed" });
+            }
+            for (const b of seed.brokers ?? []) {
+                const project = projects.get(b.projectId);
+                if (!project)
+                    throw new Error(`no project ${b.projectId}`);
+                project.brokers ??= new Map();
+                project.brokers.set(b.name, { bootstrap: b.bootstrap, shape: b.shape, secret: b.secret, declaredAt: now() });
+            }
+            for (const t of seed.topics ?? []) {
+                const project = projects.get(t.projectId);
+                if (!project)
+                    throw new Error(`no project ${t.projectId}`);
+                project.topics ??= new Map();
+                project.topics.set(t.name, {
+                    partitions: t.partitions,
+                    phase: t.phase,
+                    detail: t.detail,
+                    compacted: t.compacted,
+                    contract: t.contract ? { ...t.contract, fingerprint: fakeFingerprint(t.contract.schema) } : undefined,
+                    settings: t.settings ? { ...TopicDefaults, ...t.settings } : undefined,
+                    defaulted: t.settings ? SettingNames.filter((s) => t.settings[s] === undefined) : undefined,
                 });
             }
+            for (const m of seed.machines ?? []) {
+                machines.set(machineKey(m.organizationId, m.name), { organizationId: m.organizationId, name: m.name, registeredBy: "seed", registeredAt: now(), byteRates: m.byteRates, hidden: false });
+            }
+            for (const g of seed.grants ?? []) {
+                const project = projects.get(g.projectId);
+                const org = project && organizations.get(project.organizationId);
+                if (!project || !org)
+                    throw new Error(`no project ${g.projectId}`);
+                if (!parseGrantee(g.grantee))
+                    throw new Error(`grantee ${g.grantee} is not service:<project>/<name> or machine:<organization>/<name>`);
+                const grant = makeGrant(project, org, g.grantee, g.target, g.by ?? "seed", g.state);
+                if (g.state && g.state !== "pending" && g.state !== "accepted")
+                    grant.ended = { by: g.by ?? "seed", at: grant.granted.at };
+            }
         },
         close: () => new Promise((resolve) => {
             server.closeAllConnections();
@@ -713,3 +1883,12 @@ export async function fakeControlPlane(options = {}) {
     };
     return fake;
 }
+/** Equal for equal descriptors, whatever order their keys were written in. */
+function digestOf(descriptor) {
+    const canonical = (v) => Array.isArray(v)
+        ? v.map(canonical)
+        : v && typeof v === "object"
+            ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])]))
+            : v;
+    return createHash("sha256").update(JSON.stringify(canonical(descriptor ?? null))).digest("hex");
+}