@vantran-se/openchamber-web 2.0.4 → 2.0.5

package/server/lib/spaces/space-records.js

@@ -0,0 +1,150 @@
+// What the host remembers about a space beside the runtime's labels: the network choice the user
+// made, so the host can say it again to a gatekeeper that starts with an empty memory, and where
+// the code went in, so the history and the result find the same repository later.
+//
+// The labels stay the source of truth about which spaces exist: a record without a space is
+// forgotten, and a space without a record is listed with nothing known about it. No secret is
+// ever in a record; the design keeps secret values out of the host's disk.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { z } from 'zod';
+
+import { requireSpaceId } from './labels.js';
+
+const RECORDS_DIRECTORY = path.join('spaces', 'records');
+
+const NETWORK_MODES = Object.freeze(['allowlist', 'open']);
+// The allowlist's own rule for a name: labels of letters, digits and hyphens, with a real last label.
+const DOMAIN_PATTERN = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]$/;
+const MAX_DOMAINS = 200;
+
+export const networkSchema = z.object({
+  mode: z.enum(NETWORK_MODES),
+  domains: z.array(z.string().regex(DOMAIN_PATTERN)).max(MAX_DOMAINS).default([]),
+});
+
+const historySchema = z.enum(['pending', 'sent', 'already_complete', 'host_shallow', 'failed']);
+
+const GRANT_ID_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+// zod runs the refinement even when `.url()` failed, so the parse of the URL must not throw here.
+const isHttpUrl = (value) => {
+  try {
+    return /^https?:$/.test(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+};
+const upstreamSchema = z.string().url().refine(isHttpUrl, 'http or https');
+/** Where the host finds a secret again, never the secret: an environment variable of the host's by name, or the user typed it once. */
+export const secretSourceSchema = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('env'), name: z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,255}$/) }).strict(),
+  z.object({ kind: z.literal('typed') }).strict(),
+]);
+/**
+ * A grant as the host remembers it. Strict, so a value under any name is refused rather than
+ * written: a record holds where a secret comes from and never what it is (decision 5).
+ */
+export const grantSchema = z.discriminatedUnion('kind', [
+  z.object({
+    kind: z.literal('model'),
+    id: z.string().regex(GRANT_ID_PATTERN),
+    provider: z.string().regex(GRANT_ID_PATTERN),
+    upstream: upstreamSchema,
+    header: z.string().regex(/^[a-z0-9-]{1,64}$/),
+    source: secretSourceSchema,
+  }).strict(),
+  z.object({
+    kind: z.literal('domain'),
+    id: z.string().regex(GRANT_ID_PATTERN),
+    upstream: upstreamSchema,
+  }).strict(),
+]);
+const MAX_GRANTS = 100;
+
+const recordSchema = z.object({
+  version: z.literal(1),
+  network: networkSchema,
+  /** The host repository the code came from, as the user's project names it. */
+  repository: z.string().min(1).nullable().default(null),
+  /** The project path inside the space that code in returned. */
+  spacePath: z.string().min(1).nullable().default(null),
+  /** The commit the snapshot was taken from, which the history is sent behind. */
+  base: z.string().regex(/^[0-9a-f]{40}$|^[0-9a-f]{64}$/).nullable().default(null),
+  history: historySchema.default('pending'),
+  /** The grants the user gave, said again to the gatekeeper after every start. */
+  grants: z.array(grantSchema).max(MAX_GRANTS).default([]),
+});
+
+/**
+ * Per-space records under the host's data directory, one JSON file each, readable by the user only.
+ * A record that cannot be read as one is reported as `null` with a warning, never as a fresh one:
+ * a bad file must not make the host forget a network choice and leave a space more open than asked.
+ */
+export function createSpaceRecords({ dataDir, logger = console }) {
+  const directory = path.join(dataDir, RECORDS_DIRECTORY);
+  const fileOf = (spaceId) => path.join(directory, `${requireSpaceId(spaceId)}.json`);
+
+  /**
+   * One grant the host cannot read, from a later version that knows another kind among the
+   * reasons, is dropped with a warning and never takes the network, the repository and the
+   * history of the record with it: the space then shows that grant as missing, not as unknown.
+   */
+  const withReadableGrants = (spaceId, raw) => {
+    if (!(raw instanceof Object) || !Array.isArray(raw.grants)) return raw;
+    const grants = raw.grants.filter((grant) => grantSchema.safeParse(grant).success);
+    if (grants.length < raw.grants.length) {
+      logger.warn?.(`[spaces] the record of space ${spaceId} holds ${raw.grants.length - grants.length} grant(s) this host cannot read; they are left out`);
+    }
+    return { ...raw, grants };
+  };
+
+  const read = (spaceId) => {
+    const file = fileOf(spaceId);
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') return { status: 'missing', record: null };
+      logger.warn?.(`[spaces] could not read the record of space ${spaceId}: ${error?.code ?? error?.message ?? error}`);
+      return { status: 'unreadable', record: null };
+    }
+    try {
+      const parsed = recordSchema.safeParse(withReadableGrants(spaceId, JSON.parse(text)));
+      if (parsed.success) return { status: 'ok', record: parsed.data };
+    } catch {
+      // Reported below.
+    }
+    logger.warn?.(`[spaces] the record of space ${spaceId} is not one this host wrote`);
+    return { status: 'unreadable', record: null };
+  };
+
+  const write = (spaceId, record) => {
+    const checked = recordSchema.parse({ version: 1, ...record });
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const file = fileOf(spaceId);
+    // Through a temporary name, so a crash in the middle never leaves half a record.
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(checked, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(temporary, file);
+    return checked;
+  };
+
+  /** Changes some fields of a record that exists. A record that is missing or unreadable is not written. */
+  const update = (spaceId, changes) => {
+    const current = read(spaceId);
+    if (current.status !== 'ok') return current;
+    return { status: 'ok', record: write(spaceId, { ...current.record, ...changes }) };
+  };
+
+  const remove = (spaceId) => {
+    try {
+      fs.rmSync(fileOf(spaceId), { force: true });
+    } catch (error) {
+      logger.warn?.(`[spaces] could not remove the record of space ${spaceId}: ${error?.code ?? error?.message ?? error}`);
+    }
+  };
+
+  return { read, write, update, remove };
+}

package/server/lib/spaces/space-records.test.js

@@ -0,0 +1,113 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createSpaceRecords, networkSchema } from './space-records.js';
+
+const ID = 'a1b2c3d4e5f6';
+const folders = [];
+const temporary = () => {
+  const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-space-records-'));
+  folders.push(folder);
+  return folder;
+};
+const quiet = { warn: () => {} };
+
+afterEach(() => {
+  for (const folder of folders.splice(0)) fs.rmSync(folder, { recursive: true, force: true });
+});
+
+describe('space records', () => {
+  it('writes a record readable by the user only, reads it back, changes a field and removes it', () => {
+    const dataDir = temporary();
+    const records = createSpaceRecords({ dataDir, logger: quiet });
+    expect(records.read(ID)).toEqual({ status: 'missing', record: null });
+
+    const written = records.write(ID, { network: { mode: 'allowlist', domains: ['api.anthropic.com'] }, repository: '/home/me/project' });
+    expect(written).toEqual({ version: 1, network: { mode: 'allowlist', domains: ['api.anthropic.com'] }, repository: '/home/me/project', spacePath: null, base: null, history: 'pending', grants: [] });
+    const file = path.join(dataDir, 'spaces', 'records', `${ID}.json`);
+    if (process.platform !== 'win32') expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    expect(fs.readdirSync(path.dirname(file))).toEqual([`${ID}.json`]);
+
+    expect(records.update(ID, { spacePath: `/spaces/${ID}/project`, base: 'a'.repeat(40) }).record).toMatchObject({ spacePath: `/spaces/${ID}/project`, base: 'a'.repeat(40), history: 'pending' });
+    expect(records.update(ID, { history: 'sent' }).record.history).toBe('sent');
+    expect(records.read(ID)).toEqual({ status: 'ok', record: expect.objectContaining({ history: 'sent', network: { mode: 'allowlist', domains: ['api.anthropic.com'] } }) });
+
+    records.remove(ID);
+    expect(records.read(ID)).toEqual({ status: 'missing', record: null });
+    records.remove(ID);
+  });
+
+  it('reports a file it cannot read as unreadable, never as a fresh record, and does not write over it', () => {
+    const dataDir = temporary();
+    const records = createSpaceRecords({ dataDir, logger: quiet });
+    const directory = path.join(dataDir, 'spaces', 'records');
+    fs.mkdirSync(directory, { recursive: true });
+    fs.writeFileSync(path.join(directory, `${ID}.json`), '{ "version": 1, "network": { "mode": "everything" } }');
+    expect(records.read(ID)).toEqual({ status: 'unreadable', record: null });
+    fs.writeFileSync(path.join(directory, `${ID}.json`), 'not json');
+    expect(records.read(ID)).toEqual({ status: 'unreadable', record: null });
+    expect(records.update(ID, { history: 'sent' })).toEqual({ status: 'unreadable', record: null });
+    expect(fs.readFileSync(path.join(directory, `${ID}.json`), 'utf8')).toBe('not json');
+  });
+
+  it('remembers a grant without its value, and refuses one that carries a value under any name', () => {
+    const records = createSpaceRecords({ dataDir: temporary(), logger: quiet });
+    const model = { kind: 'model', id: 'anthropic', provider: 'anthropic', upstream: 'https://api.anthropic.com/v1', header: 'x-api-key', source: { kind: 'env', name: 'ANTHROPIC_API_KEY' } };
+    const typed = { ...model, id: 'openai', provider: 'openai', upstream: 'https://api.openai.com/v1', header: 'authorization', source: { kind: 'typed' } };
+    const domain = { kind: 'domain', id: 'open-0a1b2c3d4e5f', upstream: 'https://registry.example.com/npm/' };
+    const written = records.write(ID, { network: { mode: 'open' }, grants: [model, typed, domain] });
+    expect(written.grants).toEqual([model, typed, domain]);
+    expect(records.read(ID).record.grants).toEqual([model, typed, domain]);
+
+    for (const bad of [
+      { ...model, secret: 'sk-live-1' },
+      { ...model, value: 'sk-live-1' },
+      { ...model, source: { kind: 'typed', value: 'sk-live-1' } },
+      { ...model, source: { kind: 'env', name: 'ANTHROPIC_API_KEY', value: 'sk-live-1' } },
+      { ...domain, secret: 'sk-live-1' },
+      { ...domain, header: 'authorization' },
+      { ...model, upstream: 'file:///etc/passwd' },
+      { ...model, header: 'X-Api-Key' },
+      { ...model, id: '../x' },
+      { ...model, source: { kind: 'file', name: '/tmp/key' } },
+    ]) {
+      expect(() => records.write(ID, { network: { mode: 'open' }, grants: [bad] }), JSON.stringify(bad)).toThrow();
+    }
+    // A grant this host cannot read, from a later version, is left out; the rest of the record stays.
+    const later = temporary();
+    const withUnknown = createSpaceRecords({ dataDir: later, logger: quiet });
+    fs.mkdirSync(path.join(later, 'spaces', 'records'), { recursive: true });
+    fs.writeFileSync(path.join(later, 'spaces', 'records', `${ID}.json`), JSON.stringify({ version: 1, network: { mode: 'allowlist', domains: ['a.example.com'] }, repository: '/home/me/project', history: 'sent', grants: [{ kind: 'git', id: 'github' }, domain] }));
+    expect(withUnknown.read(ID)).toEqual({ status: 'ok', record: expect.objectContaining({ network: { mode: 'allowlist', domains: ['a.example.com'] }, repository: '/home/me/project', history: 'sent', grants: [domain] }) });
+    // A malformed upstream is refused, not thrown.
+    expect(() => records.write(ID, { network: { mode: 'open' }, grants: [{ ...domain, upstream: 'not a url' }] })).toThrow();
+
+    // A record written before grants existed reads back with none.
+    const dataDir = temporary();
+    const older = createSpaceRecords({ dataDir, logger: quiet });
+    fs.mkdirSync(path.join(dataDir, 'spaces', 'records'), { recursive: true });
+    fs.writeFileSync(path.join(dataDir, 'spaces', 'records', `${ID}.json`), JSON.stringify({ version: 1, network: { mode: 'open', domains: [] } }));
+    expect(older.read(ID)).toEqual({ status: 'ok', record: expect.objectContaining({ grants: [] }) });
+  });
+
+  it('refuses a record that is not one, and an id that is not a space id', () => {
+    const records = createSpaceRecords({ dataDir: temporary(), logger: quiet });
+    expect(() => records.write(ID, { network: { mode: 'open', domains: ['not a name'] } })).toThrow();
+    expect(() => records.write('../etc', { network: { mode: 'open' } })).toThrow(/space id/i);
+    expect(() => records.read('../etc')).toThrow(/space id/i);
+  });
+
+  it('takes domain names the allowlist takes, and nothing else', () => {
+    const accepted = (domains) => networkSchema.safeParse({ mode: 'allowlist', domains }).success;
+    expect(accepted(['api.anthropic.com', 'registry.npmjs.org', 'a-b.example'])).toBe(true);
+    expect(accepted([])).toBe(true);
+    for (const bad of [['localhost'], ['10.0.0.1'], ['Api.Example.com'], ['a_b.example'], ['-a.example'], ['a.example.'], ['a..example'], ['https://a.example'], ['a.example/path']]) {
+      expect(accepted(bad), bad[0]).toBe(false);
+    }
+    expect(networkSchema.safeParse({ mode: 'open' }).data).toEqual({ mode: 'open', domains: [] });
+    expect(networkSchema.safeParse({ mode: 'all' }).success).toBe(false);
+  });
+});

package/server/lib/spaces/space-sessions.js

@@ -0,0 +1,210 @@
+// The merged session list and the rules for what a space may claim in it or in its events.
+// Pure: no Express, no transport. `host.js` feeds it what the spaces answered and the proxy
+// asks it for the merged answer.
+//
+// A space's list and events are untrusted. A record or an event may name a directory under
+// that space's own root only, and never a session id the host has: the host's id wins, the
+// space's record is dropped and logged as a code, without its body. A space that does not
+// answer keeps its last known sessions, marked stale; a missing answer never means deletion.
+
+import { z } from 'zod';
+
+import { sanitizeSessionListItem } from '../opencode/proxy.js';
+import { isDirectoryOfSpace } from './dispatcher.js';
+
+// How many host session ids are remembered for the collision rule. Older ones are forgotten
+// first; a session the host listed or created recently is always among them.
+const HOST_ID_MEMORY = 50_000;
+
+/** Why a record or an event of a space was dropped. Logged as a code, never with the body. */
+export const SPACE_DROP_CODES = Object.freeze({
+  malformed: 'space_session_malformed',
+  outsideRoot: 'space_session_outside_root',
+  hostId: 'space_session_host_id',
+  claimed: 'space_session_claimed',
+  eventHostSession: 'space_event_host_session',
+  eventOutsideRoot: 'space_event_outside_root',
+});
+
+// What the host reads of a record or an event before it decides; every other field is carried, not read.
+const directorySchema = z.string().min(1);
+const idSchema = z.string().min(1);
+const recordSchema = z.object({ id: idSchema, location: z.object({ directory: directorySchema }).passthrough() }).passthrough();
+const eventSchema = z.object({
+  type: z.string(),
+  data: z.object({ sessionID: idSchema.optional(), location: z.object({ directory: z.unknown() }).passthrough().optional() }).passthrough().optional(),
+  location: z.object({ directory: z.unknown() }).passthrough().optional(),
+}).passthrough();
+const isRecord = (value) => z.object({}).passthrough().safeParse(value).success;
+
+/**
+ * The records of one space's list, kept or dropped one by one. `isHostSessionId` answers the
+ * host's ids, `claimedBy` names the space that already listed an id. Duplicates within the list
+ * keep the first. Resolves `{ records, dropped }`, `dropped` counting each code.
+ */
+export function filterSpaceSessionRecords({ spaceId, records, isHostSessionId, claimedBy }) {
+  const kept = [];
+  const dropped = {};
+  const seen = new Set();
+  const drop = (code) => { dropped[code] = (dropped[code] ?? 0) + 1; };
+  for (const record of records) {
+    const parsed = recordSchema.safeParse(record);
+    if (!parsed.success) {
+      // A record without an id is malformed; one with an id and no usable directory lies outside every root.
+      drop(idSchema.safeParse(record?.id).success ? SPACE_DROP_CODES.outsideRoot : SPACE_DROP_CODES.malformed);
+      continue;
+    }
+    const { id, location } = parsed.data;
+    if (!isDirectoryOfSpace(location.directory, spaceId)) { drop(SPACE_DROP_CODES.outsideRoot); continue; }
+    if (isHostSessionId(id)) { drop(SPACE_DROP_CODES.hostId); continue; }
+    const owner = claimedBy(id);
+    if (owner !== null && owner !== spaceId) { drop(SPACE_DROP_CODES.claimed); continue; }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    kept.push(sanitizeSessionListItem(record));
+  }
+  return { records: kept, dropped };
+}
+
+/**
+ * Whether one event of a space may pass: the session it names is not the host's, and every
+ * directory it carries, on the event or on the created session, lies under the space's root.
+ * Execution events carry no location and pass on their session id alone. Answers the drop
+ * code, or null when the event passes.
+ */
+export function spaceEventDropCode({ spaceId, payload, isHostSessionId }) {
+  const parsed = eventSchema.safeParse(payload);
+  if (!parsed.success) return SPACE_DROP_CODES.malformed;
+  const { data, location } = parsed.data;
+  for (const directory of [location?.directory, data?.location?.directory]) {
+    if (directory === undefined || directory === null) continue;
+    if (!directorySchema.safeParse(directory).success || !isDirectoryOfSpace(directory, spaceId)) return SPACE_DROP_CODES.eventOutsideRoot;
+  }
+  if (data?.sessionID !== undefined && isHostSessionId(data.sessionID)) return SPACE_DROP_CODES.eventHostSession;
+  return null;
+}
+
+/**
+ * The host's list with every space's records after it. `spaces` marks each space's answer:
+ * `complete`, `partial` when the space had more pages than the host read, `stale` when the
+ * last known list stands in for an answer that did not come, and `unknown` when the space
+ * never answered. A host payload without spaces goes back as it came, untouched.
+ */
+export function mergeSessionLists(hostPayload, spaceLists) {
+  if (spaceLists.length === 0) return hostPayload;
+  const records = spaceLists.flatMap((entry) => entry.records);
+  // The mark names the space for the client: its label name, the host project it was made for,
+  // as the host resolved it from the label, and the project's path inside, or null for both when
+  // the project is no longer registered on this host.
+  const spaces = spaceLists.map((entry) => ({
+    id: entry.spaceId,
+    name: entry.name ?? '',
+    state: entry.state,
+    sessions: entry.records.length,
+    projectDirectory: entry.projectDirectory ?? null,
+    directory: entry.directory ?? null,
+  }));
+  if (Array.isArray(hostPayload)) return [...hostPayload, ...records];
+  if (isRecord(hostPayload) && Array.isArray(hostPayload.data)) {
+    return { ...hostPayload, data: [...hostPayload.data, ...records], spaces };
+  }
+  return hostPayload;
+}
+
+/**
+ * What the host knows about sessions across the boundary: the host's own ids, and per space
+ * the last list it accepted and the state of that answer. One per host process.
+ */
+export function createSpaceSessionIndex({ logger = console } = {}) {
+  const hostIds = new Map();
+  const spaces = new Map();
+  const claims = new Map();
+
+  const rememberHostId = (id) => {
+    if (!idSchema.safeParse(id).success) return;
+    hostIds.delete(id);
+    hostIds.set(id, true);
+    if (hostIds.size > HOST_ID_MEMORY) hostIds.delete(hostIds.keys().next().value);
+  };
+  const isHostSessionId = (id) => hostIds.has(id);
+  const claimedBy = (id) => claims.get(id) ?? null;
+
+  const logDropped = (spaceId, dropped) => {
+    for (const [code, count] of Object.entries(dropped)) {
+      logger.warn?.(`[spaces] dropped ${count} record(s) of space ${spaceId}: ${code}`);
+    }
+  };
+
+  const entryOf = (spaceId) => {
+    let entry = spaces.get(spaceId);
+    if (!entry) {
+      entry = { spaceId, records: [], state: 'unknown' };
+      spaces.set(spaceId, entry);
+    }
+    return entry;
+  };
+
+  const releaseClaims = (spaceId) => {
+    for (const [id, owner] of claims) if (owner === spaceId) claims.delete(id);
+  };
+
+  return {
+    isHostSessionId,
+    claimedBy,
+    /** The host's list passed through the proxy: its ids are the host's from now on. */
+    observeHostRecords(records) {
+      for (const record of records) if (isRecord(record)) rememberHostId(record.id);
+    },
+    /** A host event that names a session: a created one is the host's from now on. */
+    observeHostEvent(payload) {
+      const parsed = eventSchema.safeParse(payload);
+      if (!parsed.success || parsed.data.type !== 'session.created') return;
+      rememberHostId(parsed.data.data?.sessionID);
+    },
+    /** A space answered its list, whole or in part. The records that pass replace the last known ones. */
+    acceptSpaceList(spaceId, records, { complete }) {
+      const filtered = filterSpaceSessionRecords({ spaceId, records, isHostSessionId, claimedBy });
+      logDropped(spaceId, filtered.dropped);
+      releaseClaims(spaceId);
+      for (const record of filtered.records) claims.set(record.id, spaceId);
+      const entry = entryOf(spaceId);
+      entry.records = filtered.records;
+      entry.state = complete ? 'complete' : 'partial';
+      return entry;
+    },
+    /** A space did not answer: its last known list stands, marked stale. */
+    markUnreachable(spaceId) {
+      const entry = entryOf(spaceId);
+      if (entry.state !== 'unknown') entry.state = 'stale';
+      return entry;
+    },
+    /** A space is gone: nothing of it is listed or claimed any more. */
+    forget(spaceId) {
+      spaces.delete(spaceId);
+      releaseClaims(spaceId);
+    },
+    /** Whether one event of a space passes. A created session that passes is claimed for the space. */
+    acceptSpaceEvent(spaceId, payload) {
+      const code = spaceEventDropCode({ spaceId, payload, isHostSessionId });
+      if (code !== null) {
+        logger.warn?.(`[spaces] dropped an event of space ${spaceId}: ${code}`);
+        return false;
+      }
+      const sessionID = payload.data?.sessionID;
+      if (idSchema.safeParse(sessionID).success) {
+        // A session another space listed or made is that space's: no other space speaks for it.
+        const owner = claimedBy(sessionID);
+        if (owner !== null && owner !== spaceId) {
+          logger.warn?.(`[spaces] dropped an event of space ${spaceId}: ${SPACE_DROP_CODES.claimed}`);
+          return false;
+        }
+        if (payload.type === 'session.created') claims.set(sessionID, spaceId);
+      }
+      return true;
+    },
+    /** Every space's last accepted list with its state, for the merge. */
+    snapshot() {
+      return Array.from(spaces.values(), (entry) => ({ spaceId: entry.spaceId, state: entry.state, records: entry.records }));
+    },
+  };
+}

package/server/lib/spaces/space-sessions.test.js

@@ -0,0 +1,161 @@
+// The rules of the merged session list: what a space may claim in its list and in its events.
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  SPACE_DROP_CODES,
+  createSpaceSessionIndex,
+  filterSpaceSessionRecords,
+  mergeSessionLists,
+  spaceEventDropCode,
+} from './space-sessions.js';
+
+const ID = 'a1b2c3d4e5f6';
+const OTHER = '0f0f0f0f0f0f';
+const record = (id, directory, extra = {}) => ({ id, location: { directory }, title: id, ...extra });
+const never = () => false;
+const nobody = () => null;
+
+describe('filterSpaceSessionRecords', () => {
+  it.each([
+    ['its own root', record('s1', `/spaces/${ID}/repo`), true],
+    ['its own root, deeper', record('s2', `/spaces/${ID}/repo/src`), true],
+    ['the root itself', record('s3', `/spaces/${ID}`), true],
+    ['a path outside every space', record('s4', '/home/me/project'), false],
+    ['another space', record('s5', `/spaces/${OTHER}/repo`), false],
+    ['a climb out of its root', record('s6', `/spaces/${ID}/../${OTHER}/repo`), false],
+    ['a sibling with the same prefix', record('s7', `/spaces/${ID}x/repo`), false],
+    ['no directory at all', { id: 's8', title: 'no location' }, false],
+    ['a directory that is not text', record('s9', 42), false],
+    ['no id', { location: { directory: `/spaces/${ID}/repo` } }, false],
+    ['not an object', 'text', false],
+  ])('keeps a record only when its directory lies under the space\'s root: %s', (_name, entry, kept) => {
+    const result = filterSpaceSessionRecords({ spaceId: ID, records: [entry], isHostSessionId: never, claimedBy: nobody });
+    expect(result.records.map((item) => item.id)).toEqual(kept ? [entry.id] : []);
+    if (!kept) expect(Object.values(result.dropped).reduce((sum, count) => sum + count, 0)).toBe(1);
+  });
+
+  it('never lets a space record overwrite a host session id, and logs it as a code', () => {
+    const result = filterSpaceSessionRecords({
+      spaceId: ID,
+      records: [record('host-1', `/spaces/${ID}/repo`, { title: 'I am the host session now' }), record('mine', `/spaces/${ID}/repo`)],
+      isHostSessionId: (id) => id === 'host-1',
+      claimedBy: nobody,
+    });
+    expect(result.records.map((item) => item.id)).toEqual(['mine']);
+    expect(result.dropped).toEqual({ [SPACE_DROP_CODES.hostId]: 1 });
+  });
+
+  it('drops a record whose id another space already listed, and a duplicate within the list', () => {
+    const result = filterSpaceSessionRecords({
+      spaceId: ID,
+      records: [record('theirs', `/spaces/${ID}/repo`), record('mine', `/spaces/${ID}/repo`), record('mine', `/spaces/${ID}/repo`)],
+      isHostSessionId: never,
+      claimedBy: (id) => (id === 'theirs' ? OTHER : id === 'mine' ? ID : null),
+    });
+    expect(result.records.map((item) => item.id)).toEqual(['mine']);
+    expect(result.dropped).toEqual({ [SPACE_DROP_CODES.claimed]: 1 });
+  });
+
+  it('keeps only the fields a session list may carry', () => {
+    const result = filterSpaceSessionRecords({
+      spaceId: ID,
+      records: [record('s1', `/spaces/${ID}/repo`, { permissions: { edit: 'allow' }, revert: { messageID: 'm', files: ['x'] } })],
+      isHostSessionId: never,
+      claimedBy: nobody,
+    });
+    expect(result.records[0]).toEqual({ id: 's1', location: { directory: `/spaces/${ID}/repo` }, title: 's1', revert: { messageID: 'm' } });
+  });
+});
+
+describe('spaceEventDropCode', () => {
+  const event = (type, data, location) => {
+    const payload = { type, data };
+    if (location) payload.location = { directory: location };
+    return payload;
+  };
+  it.each([
+    ['an event of its own directory', event('session.created', { sessionID: 's1', location: { directory: `/spaces/${ID}/repo` } }, `/spaces/${ID}/repo`), null],
+    ['an execution event with no location', event('session.execution.started', { sessionID: 's1' }), null],
+    ['an event of another space', event('session.created', { sessionID: 's1' }, `/spaces/${OTHER}/repo`), SPACE_DROP_CODES.eventOutsideRoot],
+    ['an event of a host directory', event('session.renamed', { sessionID: 's1' }, '/home/me/project'), SPACE_DROP_CODES.eventOutsideRoot],
+    ['a created session that lands outside', event('session.created', { sessionID: 's1', location: { directory: '/home/me' } }, `/spaces/${ID}/repo`), SPACE_DROP_CODES.eventOutsideRoot],
+    ['a moved session that lands outside', event('session.moved', { sessionID: 's1', location: { directory: `/spaces/${OTHER}` } }, `/spaces/${ID}/repo`), SPACE_DROP_CODES.eventOutsideRoot],
+    ['an event that names a host session', event('session.execution.started', { sessionID: 'host-1' }), SPACE_DROP_CODES.eventHostSession],
+    ['not an object', 'text', SPACE_DROP_CODES.malformed],
+  ])('%s', (_name, payload, code) => {
+    expect(spaceEventDropCode({ spaceId: ID, payload, isHostSessionId: (id) => id === 'host-1' })).toBe(code);
+  });
+});
+
+describe('mergeSessionLists', () => {
+  const host = { data: [record('h1', '/home/me')], cursor: { next: 'abc' } };
+  it('returns the host payload untouched, the same object, when there is no space', () => {
+    expect(mergeSessionLists(host, [])).toBe(host);
+  });
+
+  it('lists the host first, then each space, with a mark per space', () => {
+    const merged = mergeSessionLists(host, [
+      { spaceId: ID, state: 'complete', records: [record('s1', `/spaces/${ID}/repo`)], name: 'First', projectDirectory: '/home/me/repo', directory: `/spaces/${ID}/repo` },
+      { spaceId: OTHER, state: 'stale', records: [record('s2', `/spaces/${OTHER}/repo`), record('s3', `/spaces/${OTHER}/repo`)] },
+    ]);
+    expect(merged.data.map((item) => item.id)).toEqual(['h1', 's1', 's2', 's3']);
+    expect(merged.cursor).toEqual({ next: 'abc' });
+    // A space whose project is not registered on this host is marked with no project and no directory.
+    expect(merged.spaces).toEqual([
+      { id: ID, name: 'First', state: 'complete', sessions: 1, projectDirectory: '/home/me/repo', directory: `/spaces/${ID}/repo` },
+      { id: OTHER, name: '', state: 'stale', sessions: 2, projectDirectory: null, directory: null },
+    ]);
+  });
+});
+
+describe('createSpaceSessionIndex', () => {
+  const quiet = { warn: () => {} };
+
+  it('answers empty for a space that answered empty, and keeps the last list for one that did not answer', () => {
+    const index = createSpaceSessionIndex({ logger: quiet });
+    index.acceptSpaceList(ID, [record('s1', `/spaces/${ID}/repo`)], { complete: true });
+    expect(index.snapshot()).toEqual([{ spaceId: ID, state: 'complete', records: [expect.objectContaining({ id: 's1' })] }]);
+    index.markUnreachable(ID);
+    expect(index.snapshot()).toEqual([{ spaceId: ID, state: 'stale', records: [expect.objectContaining({ id: 's1' })] }]);
+    index.acceptSpaceList(ID, [], { complete: true });
+    expect(index.snapshot()).toEqual([{ spaceId: ID, state: 'complete', records: [] }]);
+    // A space that never answered is unknown, with nothing to show, and is not an empty answer.
+    index.markUnreachable(OTHER);
+    expect(index.snapshot()[1]).toEqual({ spaceId: OTHER, state: 'unknown', records: [] });
+  });
+
+  it('marks a list that had more pages than were read as partial', () => {
+    const index = createSpaceSessionIndex({ logger: quiet });
+    index.acceptSpaceList(ID, [record('s1', `/spaces/${ID}/repo`)], { complete: false });
+    expect(index.snapshot()[0].state).toBe('partial');
+  });
+
+  it('learns the host\'s ids from its list and its events, and lets no space take them', () => {
+    const logs = [];
+    const index = createSpaceSessionIndex({ logger: { warn: (line) => logs.push(line) } });
+    index.observeHostRecords([record('h1', '/home/me')]);
+    index.observeHostEvent({ type: 'session.created', data: { sessionID: 'h2' } });
+    const entry = index.acceptSpaceList(ID, [record('h1', `/spaces/${ID}/repo`, { title: 'stolen' }), record('h2', `/spaces/${ID}/repo`), record('s1', `/spaces/${ID}/repo`)], { complete: true });
+    expect(entry.records.map((item) => item.id)).toEqual(['s1']);
+    expect(index.acceptSpaceEvent(ID, { type: 'session.execution.started', data: { sessionID: 'h1' } })).toBe(false);
+    expect(index.acceptSpaceEvent(ID, { type: 'session.execution.started', data: { sessionID: 's1' } })).toBe(true);
+    expect(logs.join('\n')).toContain(SPACE_DROP_CODES.hostId);
+    expect(logs.join('\n')).toContain(SPACE_DROP_CODES.eventHostSession);
+    expect(logs.join('\n')).not.toContain('stolen');
+  });
+
+  it('claims a created session for the space that made it, and releases claims when the space is forgotten', () => {
+    const index = createSpaceSessionIndex({ logger: quiet });
+    expect(index.acceptSpaceEvent(ID, { type: 'session.created', data: { sessionID: 's1', location: { directory: `/spaces/${ID}/repo` } } })).toBe(true);
+    expect(index.claimedBy('s1')).toBe(ID);
+    expect(index.acceptSpaceEvent(OTHER, { type: 'session.created', data: { sessionID: 's1', location: { directory: `/spaces/${OTHER}/repo` } } })).toBe(false);
+    // Nor may another space speak for it in any other event.
+    expect(index.acceptSpaceEvent(OTHER, { type: 'session.execution.started', data: { sessionID: 's1' } })).toBe(false);
+    expect(index.acceptSpaceEvent(ID, { type: 'session.execution.started', data: { sessionID: 's1' } })).toBe(true);
+    expect(index.acceptSpaceList(OTHER, [record('s1', `/spaces/${OTHER}/repo`)], { complete: true }).records).toEqual([]);
+    index.forget(ID);
+    expect(index.claimedBy('s1')).toBeNull();
+    expect(index.snapshot().map((entry) => entry.spaceId)).toEqual([OTHER]);
+  });
+});