@vantran-se/openchamber-web 2.0.4 → 2.0.6

package/server/lib/spaces/journey.js

@@ -0,0 +1,552 @@
+// The journey of a space as the host drives it: made with its network choice and the project's
+// code, listed with its state, started again with its network said again to a gatekeeper that
+// forgot it, stopped, removed with everything the host kept for it, its journal read, and its
+// work brought out and applied. Everything here is written once on top of the manager, the
+// gatekeeper channel, code in and code out; the routes in `routes.js` only translate HTTP.
+//
+// A creation runs in the background: the request comes back at once with the space's id, and the
+// steps are announced as `openchamber:space-progress` events on the host's hub, so the group in
+// the sidebar can say what is happening now (DESIGN.md, journey step 2). A creation that fails
+// after the containers exist removes them again, and its failure stays listed until the user
+// dismisses it, so an error is never silent.
+//
+// Grants, since 5b: a model key the gatekeeper's window adds to the provider's requests, or an
+// opened domain the window forwards to with no credential. The host keeps the grant without its
+// value (decision 5) and says it again to the gatekeeper after every start; a value it cannot
+// find again leaves the space "needs access" until the user grants once more.
+
+import crypto from 'node:crypto';
+
+import { z } from 'zod';
+
+import { SpaceError } from './errors.js';
+import { createSpaceId, hashProjectDirectory } from './labels.js';
+import { spaceProjectPath, spaceWindowUrl } from './layout.js';
+import { grantSchema, networkSchema, secretSourceSchema } from './space-records.js';
+
+// The four choices of the create dialog, parsed at the boundary. Each field refuses with a code
+// of its own, so the dialog can point at the field.
+const createRequestSchema = z.object({
+  projectDirectory: z.string().min(1),
+  name: z.string().trim().min(1),
+  start: z.enum(['clean', 'uncommitted']).default('uncommitted'),
+  network: networkSchema.default({ mode: 'allowlist', domains: [] }),
+});
+const CREATE_REFUSALS = {
+  projectDirectory: ['project_not_registered', 'A space is made for a project this OpenChamber knows. Add the project first, then create the space.'],
+  name: ['invalid_space_name', 'A space needs a name.'],
+  start: ['invalid_snapshot_mode', 'A space starts from a clean commit or with the uncommitted changes.'],
+  network: ['invalid_network', 'The network of a space is allowlist or open, with a list of domain names for the allowlist.'],
+};
+// The grant dialog's request, parsed at the boundary. A model grant names the provider as the
+// host's catalog does, the provider's API as the upstream, and where the key comes from: typed
+// once, or an environment variable of the host's by name. The value of a typed key is used now
+// and remembered nowhere. An opened domain has no key.
+const MAX_SECRET_LENGTH = 8192;
+const grantRequestSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('model'),
+    provider: grantSchema.options[0].shape.provider,
+    upstream: grantSchema.options[0].shape.upstream,
+    secret: z.discriminatedUnion('kind', [
+      z.object({ kind: z.literal('typed'), value: z.string().min(1).max(MAX_SECRET_LENGTH) }).strict(),
+      secretSourceSchema.options[0],
+    ]),
+  }).strict(),
+  z.object({ kind: z.literal('domain'), upstream: grantSchema.options[1].shape.upstream }).strict(),
+]);
+// The header the window sets for a provider: what its API reads a key from. Only providers
+// named here are taken: one that reads its key another way or signs its requests, Azure,
+// Bedrock or Vertex, would take the grant and fail every turn with a 401 upstream.
+const HEADER_BY_PROVIDER = new Map([
+  ['anthropic', 'x-api-key'],
+  ['google', 'x-goog-api-key'],
+  ...['openai', 'openrouter', 'groq', 'mistral', 'deepseek', 'xai'].map((provider) => [provider, 'authorization']),
+]);
+
+const applyRequestSchema = z.discriminatedUnion('as', [
+  z.object({ as: z.literal('branch'), branch: z.string(), removeAfterwards: z.boolean().default(false) }),
+  z.object({ as: z.literal('changes'), removeAfterwards: z.boolean().default(false) }),
+]);
+
+const failureOf = (error) => ({
+  code: error instanceof SpaceError ? error.code : 'space_journey_failed',
+  message: error?.message ?? String(error),
+  details: error instanceof SpaceError ? error.details ?? null : null,
+});
+
+/**
+ * `listProjectDirectories` answers the host's registered projects; a space is made for one of them
+ * and its label carries the project's hash. `announce(spaceId, payload)` enters an event into the
+ * host's hub, `onSpacesChanged()` tells the host to read its list again at once. `spaceOpenCode`
+ * writes OpenCode's files inside a space, and `readHostSecret(name)` is how a key named by an
+ * environment variable of the host's is found again: its value or undefined, never stored.
+ */
+export function createSpaceJourney({
+  manager,
+  place,
+  gatekeeper,
+  codeIn,
+  codeOut,
+  records,
+  spaceOpenCode,
+  listProjectDirectories,
+  readHostSecret = () => undefined,
+  announce = () => {},
+  onSpacesChanged = () => {},
+  logger = console,
+  now = () => new Date(),
+}) {
+  // Creations under way or failed, by space id, until they succeed or the user dismisses them.
+  const pending = new Map();
+  // Spaces with an action under way: start, stop, remove, journal or apply. One at a time per space,
+  // so a remove cannot pull the refs from under an apply that is writing them.
+  const busy = new Set();
+  // Set while the switch is being turned off: no creation may slip in between the stop of the
+  // spaces and the moment the feature is gone.
+  let closing = false;
+
+  const exclusive = async (spaceId, work) => {
+    if (busy.has(spaceId)) throw new SpaceError('space_busy', 'Another action on this space is still running. Wait for it to finish.');
+    busy.add(spaceId);
+    try {
+      return await work();
+    } finally {
+      busy.delete(spaceId);
+    }
+  };
+
+  /** Refuses an action on a creation under way, and names a failed one for what it is. */
+  const requireNotPending = (spaceId) => {
+    const waiting = pending.get(spaceId);
+    if (!waiting) return;
+    if (waiting.state === 'failed') throw new SpaceError('space_creation_failed', 'Making this space failed. Dismiss it, then create a new one.');
+    throw new SpaceError('space_preparing', 'This space is still being made.');
+  };
+
+  const registeredProjects = async () => {
+    const directories = await listProjectDirectories();
+    return new Map(directories.map((directory) => [hashProjectDirectory(directory), directory]));
+  };
+
+  const requireRegisteredProject = async (directory) => {
+    const projects = await registeredProjects();
+    if (projects.get(hashProjectDirectory(directory)) !== directory) {
+      throw new SpaceError(...CREATE_REFUSALS.projectDirectory);
+    }
+    return directory;
+  };
+
+  const progress = (entry, step, failure = null) => {
+    entry.step = step;
+    entry.state = step === 'failed' ? 'failed' : step === 'ready' ? 'running' : 'preparing';
+    entry.failure = failure;
+    announce(entry.id, { type: 'openchamber:space-progress', properties: { spaceId: entry.id, step, failure, timestamp: now().getTime() } });
+  };
+
+  /** Removes the space and everything the host kept for it, and says what did not go. */
+  const removeEverything = async (spaceId, repository) => {
+    const outcome = { removed: false, refsRemoved: null, failures: [] };
+    try {
+      await manager.removeSpace({ placeId: place.id, spaceId });
+      outcome.removed = true;
+    } catch (error) {
+      outcome.failures.push(failureOf(error));
+    }
+    if (repository) {
+      try {
+        await codeIn.removeSpaceRefs({ repository, spaceId });
+        outcome.refsRemoved = true;
+      } catch (error) {
+        outcome.refsRemoved = false;
+        outcome.failures.push(failureOf(error));
+      }
+    }
+    records.remove(spaceId);
+    return outcome;
+  };
+
+  const sendHistoryInBackground = ({ repository, spaceId, spacePath, base }) => {
+    codeIn.sendHistory({ repository, spaceId, spacePath, base })
+      .then((result) => { records.update(spaceId, { history: result.status }); })
+      .catch((error) => {
+        logger.warn?.(`[spaces] the history of space ${spaceId} did not arrive: ${error?.details?.cause ?? error?.code ?? error?.message}`);
+        records.update(spaceId, { history: 'failed' });
+      });
+  };
+
+  const prepare = async (entry, { projectDirectory, name, start, network }) => {
+    let created = false;
+    try {
+      progress(entry, 'checking_place');
+      const check = await place.check();
+      if (!check.available) throw new SpaceError(check.code, check.message);
+      if (network.mode === 'allowlist' && check.hostIsolation !== true) {
+        throw new SpaceError('place_cannot_restrict_network', 'This place cannot keep a space away from the machine it runs on, so an allowlist would not hold. Use a newer Docker engine, or choose the open network with that in mind.');
+      }
+      progress(entry, 'creating');
+      await manager.createSpace({ id: entry.id, placeId: place.id, projectDirectory, name });
+      created = true;
+      records.write(entry.id, { network, repository: projectDirectory });
+      progress(entry, 'setting_network');
+      await gatekeeper.setNetwork(entry.id, network);
+      progress(entry, 'bringing_code');
+      const arrived = await codeIn.bringCodeIn({ repository: projectDirectory, spaceId: entry.id, mode: start });
+      records.update(entry.id, { spacePath: arrived.spacePath, base: arrived.base });
+      entry.identityCopied = arrived.identityCopied;
+      pending.delete(entry.id);
+      progress(entry, 'ready');
+      onSpacesChanged();
+      sendHistoryInBackground({ repository: projectDirectory, spaceId: entry.id, spacePath: arrived.spacePath, base: arrived.base });
+    } catch (error) {
+      const failure = failureOf(error);
+      if (created) {
+        const cleanup = await removeEverything(entry.id, projectDirectory);
+        if (cleanup.failures.length > 0) failure.cleanup = cleanup.failures;
+      }
+      logger.warn?.(`[spaces] creating space ${entry.id} failed at ${entry.step}: ${failure.code}`);
+      progress(entry, 'failed', failure);
+    }
+  };
+
+  /**
+   * Starts making a space and answers at once with the entry the list will carry. The four
+   * choices of the create dialog come in: the project, the name, the starting point and the
+   * network. The place is checked inside, as decision 19 asks: nothing probes a runtime before
+   * the user acts.
+   */
+  const createSpace = async (request) => {
+    if (closing) throw new SpaceError('isolated_spaces_off', 'Isolated spaces are being turned off.');
+    const parsed = createRequestSchema.safeParse(request ?? {});
+    if (!parsed.success) {
+      const [code, message] = CREATE_REFUSALS[parsed.error.issues[0]?.path?.[0]] ?? CREATE_REFUSALS.network;
+      throw new SpaceError(code, message);
+    }
+    const { name, start, network } = parsed.data;
+    const projectDirectory = await requireRegisteredProject(parsed.data.projectDirectory);
+    const id = createSpaceId();
+    const entry = {
+      id,
+      name,
+      placeId: place.id,
+      projectDirectory,
+      directory: spaceProjectPath(id, projectDirectory),
+      created: now().toISOString(),
+      state: 'preparing',
+      step: 'checking_place',
+      failure: null,
+      network,
+    };
+    pending.set(entry.id, entry);
+    void prepare(entry, { projectDirectory, name, start, network });
+    return describePending(entry);
+  };
+
+  /** A grant as the list and the grant route show it: everything the record holds, which holds no value. */
+  const describeGrant = (grant) => ({ ...grant, url: spaceWindowUrl(grant.id) });
+
+  /**
+   * Says one grant of the record to the gatekeeper. Resolves whether it could: a typed key is
+   * not remembered and needs the user again, and so does an environment variable that is not set
+   * now; a gatekeeper that refuses or does not answer counts the same way and is logged, because
+   * the space runs either way and the list must say that its access is missing.
+   */
+  const deliverGrant = async (spaceId, grant) => {
+    let secret = null;
+    if (grant.kind === 'model') {
+      if (grant.source.kind === 'typed') return false;
+      secret = readHostSecret(grant.source.name);
+      if (typeof secret !== 'string' || secret === '') return false;
+    }
+    try {
+      await gatekeeper.addGrant(spaceId, { id: grant.id, upstream: grant.upstream, header: grant.kind === 'model' ? grant.header : null, secret });
+      return true;
+    } catch (error) {
+      logger.warn?.(`[spaces] the grant ${grant.id} of space ${spaceId} could not be said again: ${error?.code ?? error?.message ?? error}`);
+      return false;
+    }
+  };
+
+  /**
+   * OpenCode's configuration inside, written again from the record at a start: it survives a
+   * stop in the home volume, but a write that failed at the grant is repaired only here. It
+   * cooperates and enforces nothing, so a failure is logged and the start goes on.
+   */
+  const rewriteProviderConfig = async (spaceId, grants) => {
+    if (!grants.some((grant) => grant.kind === 'model')) return;
+    try {
+      await spaceOpenCode.writeProviderConfig(spaceId, grants);
+    } catch (error) {
+      logger.warn?.(`[spaces] the provider configuration of space ${spaceId} was not written again: ${error?.code ?? error?.message ?? error}`);
+    }
+  };
+
+  /** Every grant of the record said again after a start. Resolves the ids that went and the ids that need the user. */
+  const restoreGrants = async (spaceId, grants) => {
+    const restored = [];
+    const needsAccess = [];
+    for (const grant of grants) {
+      (await deliverGrant(spaceId, grant) ? restored : needsAccess).push(grant.id);
+    }
+    return { restored, needsAccess };
+  };
+
+  /**
+   * Which grants of the record a running gatekeeper holds now, read from the gatekeeper itself:
+   * after a machine restart it holds none, and the space "needs access" (DESIGN.md, Gatekeeper).
+   * A gatekeeper that cannot be asked leaves the answer unknown, never "granted".
+   */
+  const readAccess = async (space, grants) => {
+    // A start that is still saying the grants again, or a grant on its way, would read as
+    // "needs access" for a moment; while an action holds the space the answer is not given.
+    if (space.state !== 'running' || grants.length === 0 || busy.has(space.id)) return { access: null, needsAccess: [] };
+    try {
+      const held = new Set((await gatekeeper.readPolicy(space.id)).grants);
+      const needsAccess = grants.filter((grant) => !held.has(grant.id)).map((grant) => grant.id);
+      return { access: needsAccess.length === 0 ? 'granted' : 'needs_access', needsAccess };
+    } catch (error) {
+      logger.warn?.(`[spaces] the gatekeeper of space ${space.id} did not say what it holds: ${error?.code ?? error?.message ?? error}`);
+      return { access: 'unknown', needsAccess: [] };
+    }
+  };
+
+  const describePending = (entry) => ({
+    id: entry.id,
+    name: entry.name,
+    placeId: entry.placeId,
+    projectDirectory: entry.projectDirectory,
+    directory: entry.directory,
+    created: entry.created,
+    state: entry.state,
+    step: entry.step,
+    failure: entry.failure,
+    network: entry.network,
+    history: 'pending',
+    grants: [],
+    access: null,
+    needsAccess: [],
+    damaged: false,
+    missing: [],
+    orphans: [],
+  });
+
+  /**
+   * Every space of this host: the place's list with what the host remembers about each, the
+   * creations under way in their place, and the failed ones after it. A record the host cannot read leaves `network` null,
+   * which the UI must show as "unknown" and never as "open". With `access` each running space
+   * with grants is asked what its gatekeeper holds, one request per such space, so the list can
+   * say "needs access"; without it `access` stays null.
+   */
+  const listSpaces = async ({ access = false } = {}) => {
+    const [spaces, projects] = await Promise.all([manager.listSpaces({ placeId: place.id }), registeredProjects()]);
+    const listed = await Promise.all(spaces.map(async (space) => {
+      const projectDirectory = projects.get(space.project) ?? null;
+      const { record } = records.read(space.id);
+      const grants = record?.grants ?? [];
+      return {
+        id: space.id,
+        name: space.name,
+        placeId: space.placeId,
+        projectDirectory,
+        directory: projectDirectory === null ? null : spaceProjectPath(space.id, projectDirectory),
+        created: space.created,
+        state: space.state,
+        step: null,
+        failure: null,
+        network: record?.network ?? null,
+        history: record?.history ?? 'unknown',
+        grants: grants.map(describeGrant),
+        ...(access ? await readAccess(space, grants) : { access: null, needsAccess: [] }),
+        damaged: space.damaged,
+        missing: space.missing,
+        orphans: space.orphans,
+      };
+    }));
+    // A creation under way wins over the place's view of it: the containers run before the code is there.
+    const waiting = new Map(Array.from(pending.values(), (entry) => [entry.id, describePending(entry)]));
+    const merged = listed.map((space) => waiting.get(space.id) ?? space);
+    const known = new Set(listed.map((space) => space.id));
+    return [...merged, ...Array.from(waiting.values()).filter((entry) => !known.has(entry.id))];
+  };
+
+  const requireListed = async (spaceId) => {
+    const space = (await listSpaces()).find((entry) => entry.id === spaceId);
+    if (!space) throw new SpaceError('space_not_found', `There is no space ${spaceId}`);
+    return space;
+  };
+
+  /**
+   * Starts a stopped space. Its gatekeeper comes up allowing nothing, so the network the user
+   * chose is said again from the record; without a readable record the space stays closed, and
+   * the answer says so with `networkRestored` false.
+   */
+  const startSpace = (spaceId) => exclusive(spaceId, async () => {
+    // As for a creation: no start may slip in while the switch is stopping the spaces one by one.
+    if (closing) throw new SpaceError('isolated_spaces_off', 'Isolated spaces are being turned off.');
+    requireNotPending(spaceId);
+    await manager.startSpace({ placeId: place.id, spaceId });
+    const { record } = records.read(spaceId);
+    let networkRestored = false;
+    let grants = { restored: [], needsAccess: [] };
+    if (record) {
+      await gatekeeper.setNetwork(spaceId, record.network);
+      networkRestored = true;
+      grants = await restoreGrants(spaceId, record.grants);
+      await rewriteProviderConfig(spaceId, record.grants);
+      // A history that never arrived, or that failed, is sent again: a stop right after the
+      // creation is the usual way it fails, and the space would otherwise stay shallow for good.
+      if ((record.history === 'pending' || record.history === 'failed') && record.repository && record.spacePath && record.base) {
+        sendHistoryInBackground({ repository: record.repository, spaceId, spacePath: record.spacePath, base: record.base });
+      }
+    }
+    onSpacesChanged();
+    return { ...(await requireListed(spaceId)), networkRestored, grantsRestored: grants.restored, needsAccess: grants.needsAccess };
+  });
+
+  /**
+   * Gives a running space a grant: the key goes to the gatekeeper, the grant without its value
+   * goes to the record, and for a model grant OpenCode inside is told to send that provider's
+   * calls through the window. A second grant for the same provider replaces the first, which is
+   * how a key is changed; a grant is never taken back (decision 4). The value of a typed key is
+   * in this request and in the gatekeeper's memory, and nowhere else afterwards.
+   */
+  const grantAccess = (spaceId, request) => exclusive(spaceId, async () => {
+    requireNotPending(spaceId);
+    const parsed = grantRequestSchema.safeParse(request ?? {});
+    if (!parsed.success) throw new SpaceError('invalid_grant_request', 'A grant is a model key for a provider, typed or named by a host environment variable, or an opened domain.');
+    const space = await requireListed(spaceId);
+    if (space.state !== 'running') throw new SpaceError('space_not_running', 'A grant goes to the gatekeeper of a running space. Start the space, then grant.');
+    const current = records.read(spaceId);
+    if (current.status !== 'ok') throw new SpaceError('space_record_unreadable', 'The host\'s record of this space cannot be read, so a grant could not be remembered. Remove the space and create it again.');
+
+    const asked = parsed.data;
+    if (asked.kind === 'model' && !HEADER_BY_PROVIDER.has(asked.provider)) {
+      throw new SpaceError('provider_not_supported', `A key for ${asked.provider} cannot be given through the gatekeeper yet: it reads its key in a way the gatekeeper does not know.`);
+    }
+    let grant;
+    let secret = null;
+    if (asked.kind === 'model') {
+      const source = asked.secret.kind === 'typed' ? { kind: 'typed' } : { kind: 'env', name: asked.secret.name };
+      secret = asked.secret.kind === 'typed' ? asked.secret.value : readHostSecret(asked.secret.name);
+      if (typeof secret !== 'string' || secret === '') {
+        throw new SpaceError('secret_source_missing', `The environment variable ${asked.secret.name} is not set for OpenChamber, so there is no key to give.`);
+      }
+      grant = { kind: 'model', id: asked.provider, provider: asked.provider, upstream: asked.upstream, header: HEADER_BY_PROVIDER.get(asked.provider), source };
+    } else {
+      grant = { kind: 'domain', id: `open-${crypto.randomBytes(6).toString('hex')}`, upstream: asked.upstream };
+    }
+    await gatekeeper.addGrant(spaceId, { id: grant.id, upstream: grant.upstream, header: grant.kind === 'model' ? grant.header : null, secret });
+    const grants = [...current.record.grants.filter((entry) => entry.id !== grant.id), grant];
+    if (records.update(spaceId, { grants }).status !== 'ok') {
+      throw new SpaceError('space_record_unreadable', 'The grant reached the gatekeeper and could not be remembered, so it is gone at the next start. Remove the space and create it again.');
+    }
+    // A failure here answers the grant with it; the key is in the gatekeeper and the record, and
+    // the next start writes the configuration again.
+    if (grant.kind === 'model') await spaceOpenCode.writeProviderConfig(spaceId, grants);
+    return { grant: describeGrant(grant) };
+  });
+
+  const stopSpace = (spaceId) => exclusive(spaceId, async () => {
+    requireNotPending(spaceId);
+    await manager.stopSpace({ placeId: place.id, spaceId });
+    onSpacesChanged();
+    return requireListed(spaceId);
+  });
+
+  /**
+   * Removes a space and everything the host kept for it: the containers, networks and volumes,
+   * the service refs in the user's repository and the record. A failed creation is forgotten here.
+   * The chat archive of decision 9 is a later stage; today the sessions go with the space.
+   */
+  const removeUnlocked = async (spaceId) => {
+    const waiting = pending.get(spaceId);
+    if (waiting) {
+      if (waiting.state !== 'failed') throw new SpaceError('space_preparing', 'This space is still being made. Wait for it, then remove it.');
+      pending.delete(spaceId);
+      // A failed creation whose clean-up failed still has containers; those go now, or the space
+      // comes back in the list as damaged. One that was cleaned up has nothing left to remove.
+      const still = (await manager.listSpaces({ placeId: place.id })).some((space) => space.id === spaceId);
+      if (!still) return { id: spaceId, removed: true, refsRemoved: null, failures: [] };
+      return { id: spaceId, ...(await removeEverything(spaceId, waiting.projectDirectory)) };
+    }
+    const space = await requireListed(spaceId);
+    const { record } = records.read(spaceId);
+    const outcome = await removeEverything(spaceId, record?.repository ?? space.projectDirectory);
+    onSpacesChanged();
+    return { id: spaceId, ...outcome };
+  };
+  const removeSpace = (spaceId) => exclusive(spaceId, () => removeUnlocked(spaceId));
+
+  /**
+   * Stops every running space, for the switch being turned off. Each space is tried on its own:
+   * one that could not be stopped is reported as still running, never counted as stopped.
+   */
+  const stopAllSpaces = async () => {
+    const preparing = Array.from(pending.values()).filter((entry) => entry.state === 'preparing');
+    if (preparing.length > 0) throw new SpaceError('space_preparing', `${preparing.length === 1 ? 'A space is' : `${preparing.length} spaces are`} still being made. Wait for that to finish first.`, { spaces: preparing.map((entry) => entry.id) });
+    closing = true;
+    const spaces = await manager.listSpaces({ placeId: place.id });
+    const stopped = [];
+    const stillRunning = [];
+    for (const space of spaces) {
+      if (space.state !== 'running') continue;
+      try {
+        await manager.stopSpace({ placeId: place.id, spaceId: space.id });
+        stopped.push({ id: space.id, name: space.name });
+      } catch (error) {
+        stillRunning.push({ id: space.id, name: space.name, ...failureOf(error) });
+      }
+    }
+    return { stopped, stillRunning };
+  };
+
+  /** For a turn-off that did not go through after the spaces were stopped: creations are taken again. */
+  const reopen = () => { closing = false; };
+
+  /** What the gatekeeper allowed and refused since it last started; a stopped space has no journal. */
+  const readJournal = (spaceId) => exclusive(spaceId, async () => {
+    const space = await requireListed(spaceId);
+    if (space.state !== 'running') {
+      throw new SpaceError('space_not_running', 'The journal lives in the memory of the space\'s gatekeeper and is gone with a stop. Start the space to record new attempts.');
+    }
+    return gatekeeper.readJournal(spaceId);
+  });
+
+  const requireRepository = async (spaceId) => {
+    requireNotPending(spaceId);
+    const space = await requireListed(spaceId);
+    const { record } = records.read(spaceId);
+    const repository = record?.repository ?? space.projectDirectory;
+    if (!repository) throw new SpaceError('project_not_registered', 'The project this space was made for is no longer registered, so its work has nowhere to go.');
+    return { space, repository, spacePath: record?.spacePath ?? space.directory };
+  };
+
+  /** Brings the work out and describes what an apply would do, for the apply dialog. */
+  const previewApply = (spaceId) => exclusive(spaceId, async () => {
+    const { repository, spacePath } = await requireRepository(spaceId);
+    const brought = await codeOut.bringCodeOut({ repository, spaceId, spacePath });
+    const state = await codeOut.describeApplyState({ repository, spaceId });
+    return { ...brought, ...state };
+  });
+
+  /**
+   * Brings the work out once more and applies it as a branch or as uncommitted changes. What is
+   * applied is what this call fetched, whatever a preview showed. With `removeAfterwards` the
+   * space goes once the apply went through, and only then.
+   */
+  const applySpace = (spaceId, request) => exclusive(spaceId, async () => {
+    const parsed = applyRequestSchema.safeParse(request ?? {});
+    if (!parsed.success) throw new SpaceError('invalid_apply_request', 'The work is applied as a branch, with its name, or as uncommitted changes.');
+    const { as, removeAfterwards } = parsed.data;
+    const branch = as === 'branch' ? parsed.data.branch : null;
+    const { repository, spacePath } = await requireRepository(spaceId);
+    const brought = await codeOut.bringCodeOut({ repository, spaceId, spacePath });
+    const applied = as === 'branch'
+      ? { status: 'applied', ...(await codeOut.applyAsBranch({ repository, spaceId, branch })) }
+      : await codeOut.applyAsChanges({ repository, spaceId });
+    const removal = removeAfterwards && applied.status === 'applied' ? await removeUnlocked(spaceId) : null;
+    return { brought, applied, removal };
+  });
+
+  return { createSpace, listSpaces, startSpace, stopSpace, removeSpace, stopAllSpaces, reopen, grantAccess, readJournal, previewApply, applySpace };
+}