cortad 0.3.11 → 0.4.1

package/lib/stores.mjs

@@ -1,433 +0,0 @@
-// Your app's database servers, kept out of the run's way. A run creates people, conversations and
-// records by the hundred; an app pointed at Postgres, Redis, MongoDB, Elasticsearch or a Qdrant
-// collection kept every one of them. So each store the app's settings name on this machine is copied
-// on its own server under a name of ours, or, where the app names its databases in its code, as a
-// whole server in a container of ours (lib/container.mjs); the app is started pointed at the copy
-// through the same settings, and the copy is deleted when this command ends. The original is only
-// ever read. A store no copy is made of holds Run until the person says yes to writing into it. A
-// store off this machine is copied where it can be (lib/hosted.mjs) and otherwise holds Run.
-import { createHash } from "node:crypto";
-import { copyName, removeCopy } from "./container.mjs";
-import { serveElastic } from "./elastic.mjs";
-import { hostedKeeper } from "./hosted.mjs";
-import { ledger } from "./ledger.mjs";
-import { cloneMongo, dropMongo, serveMongo, withDb } from "./mongo.mjs";
-import { clonePg, dropPg } from "./pg.mjs";
-import { cloneQdrant, dropQdrant } from "./qdrant.mjs";
-import { cloneRedis, dropRedis } from "./redis.mjs";
-
-export const ENGINE = { postgres: "Postgres", mysql: "MySQL", mongo: "MongoDB", redis: "Redis", qdrant: "Qdrant", chroma: "Chroma", milvus: "Milvus", weaviate: "Weaviate", elasticsearch: "Elasticsearch", meilisearch: "Meilisearch", typesense: "Typesense", neo4j: "Neo4j", sqlserver: "SQL Server", supabase: "Supabase", pinecone: "Pinecone", firestore: "Firestore" };
-// Where each listens when nothing else is said. Also how a connection the hook saw is named.
-export const PORT_OF = { postgres: 5432, mysql: 3306, mongo: 27017, redis: 6379, qdrant: 6333, chroma: 8000, milvus: 19530, weaviate: 8080, elasticsearch: 9200, meilisearch: 7700, typesense: 8108, neo4j: 7687, sqlserver: 1433 };
-// A connection is named by its port only where the port is the store's own: 8000 and 8080 are
-// every other web server's too.
-const ENGINE_AT = { ...Object.fromEntries(Object.entries(PORT_OF).filter(([e]) => e !== "chroma" && e !== "weaviate").map(([e, p]) => [p, e])), 6334: "qdrant" };
-export const isStorePort = (port) => Boolean(ENGINE_AT[port]);
-// Stores reached through their maker's SDK, which a setting rarely names: the hook sees the host.
-const HOSTED = [["supabase", /\.supabase\.(?:co|in|com)$/], ["mongo", /\.mongodb\.net$/], ["elasticsearch", /\.elastic-cloud\.com$|\.found\.io$|\.es\.amazonaws\.com$/], ["redis", /\.upstash\.io$|\.redis-cloud\.com$|\.redislabs\.com$/], ["postgres", /\.neon\.tech$/], ["pinecone", /\.pinecone\.io$/], ["qdrant", /\.qdrant\.io$/], ["firestore", /^firestore\.googleapis\.com$/]];
-// How each store we copy is copied and dropped: on its own server, under the name given.
-const COPY = {
-  postgres: { copy: (s, clone) => clonePg(s.conn, s.db, clone), drop: (s, clone) => dropPg(s.conn, clone) },
-  redis: { copy: (s, clone, marker) => cloneRedis(s.conn, s.db, marker), drop: (s, clone, marker) => dropRedis(s.conn, clone, marker) },
-  mongo: { copy: (s, clone) => cloneMongo(s.conn, s.db, clone), drop: (s, clone) => dropMongo(s.conn, clone, s.db) },
-  qdrant: { copy: (s, clone) => cloneQdrant(s.conn, s.db, clone), drop: (s, clone) => dropQdrant(s.conn, clone) },
-};
-// Stores whose app names its databases in its code are copied as a whole server instead.
-const SERVER = { mongo: (s, name) => serveMongo(s.conn, name), elasticsearch: (s, name) => serveElastic(s.conn, name) };
-const TOOLS = { postgres: "Postgres's own psql and pg_dump are", mongo: "MongoDB's own mongodump, mongorestore and mongosh are" };
-
-const SCHEME = /^(postgres(?:ql)?|mysql|mariadb|mongodb|rediss?|valkeys?|sqlserver|mssql)((?:\+\w+)*):\/\/([^/?#]*)(\/[^?#]*)?([?#].*)?$/i;
-const SCHEME_ENGINE = { postgres: "postgres", postgresql: "postgres", mysql: "mysql", mariadb: "mysql", mongodb: "mongo", redis: "redis", rediss: "redis", valkey: "redis", valkeys: "redis", sqlserver: "sqlserver", mssql: "sqlserver" };
-// A search or vector store is named by what its setting is called, since it speaks plain HTTP.
-const BY_NAME = [["qdrant", /QDRANT/], ["chroma", /CHROMA/], ["milvus", /MILVUS|ZILLIZ/], ["weaviate", /WEAVIATE/], ["elasticsearch", /ELASTIC|OPENSEARCH|^ES_/], ["meilisearch", /MEILI/], ["typesense", /TYPESENSE/], ["neo4j", /NEO4J/], ["supabase", /SUPABASE/]];
-const WORD_ENGINE = [["postgres", /^(?:PG|POSTGRES|PSQL)|POSTGRES/], ["mysql", /MYSQL|MARIA/], ["mongo", /MONGO/], ["redis", /REDIS|VALKEY/]];
-const SECRETISH = /(?:^|_)(?:KEY|TOKEN|SECRET|PASSWORD|PASS|PWD)$/;
-// Every engine's word in a setting's name, so a setting that carries one is that engine's own.
-const ENGINE_WORD = new RegExp([...Object.keys(ENGINE), ...[...BY_NAME, ...WORD_ENGINE].map(([, re]) => re.source)].join("|"), "i");
-// A settings file's values without the ones that name a store. An app the person started with
-// their own command is handed the rest: which databases it uses is that command's to say.
-const STORE_SETTING = new RegExp(`${ENGINE_WORD.source}|(?:^|_)(?:DB|DATABASE)(?:_|$)`, "i");
-export const withoutStoreSettings = (values) => Object.fromEntries(Object.entries(values).filter(([name]) => !STORE_SETTING.test(name)));
-export const storeSettings = (values) => Object.fromEntries(Object.entries(values).filter(([name]) => STORE_SETTING.test(name)));
-// Stores that hold no collections: a bare COLLECTION setting beside one of them is still Qdrant's.
-const NO_COLLECTIONS = new Set(["redis", "mysql", "sqlserver", "neo4j", "meilisearch", "pinecone"]);
-const LOOPBACK = /^(?:localhost|127(?:\.\d+){3}|::1|\[::1\]|0\.0\.0\.0|host\.docker\.internal)?$/i;
-// A socket path (host=/var/run/postgresql) is this machine too.
-export const onThisMachine = (host) => LOOPBACK.test(String(host ?? "")) || String(host).startsWith("/");
-// A Neon endpoint's pooled host is the same database as its direct one.
-const hostKey = (host) => (onThisMachine(host) ? "localhost" : String(host).toLowerCase().replace(/^(ep-[a-z0-9-]+?)-pooler\./, "$1."));
-const at = (s) => `${s.engine}|${hostKey(s.host)}|${s.port}`;
-
-// A part that is no percent-encoding (%DB%) is kept as its maker wrote it.
-const dec = (s) => { try { return decodeURIComponent(s); } catch { return s; } };
-const authority = (a) => {
-  const cut = a.lastIndexOf("@");
-  const cred = cut >= 0 ? a.slice(0, cut) : "";
-  // A replica set lists its hosts; the first answers for all of them.
-  const hostPort = (cut >= 0 ? a.slice(cut + 1) : a).split(",")[0];
-  const m = /^(\[[^\]]*\]|[^:]*)(?::(\d+))?$/.exec(hostPort);
-  if (!m) return null;
-  const [user, ...pass] = cred ? cred.split(":") : [];
-  return { host: m[1].replace(/^\[|\]$/g, ""), port: m[2] ? Number(m[2]) : null, user: user ? dec(user) : "", password: pass.length ? dec(pass.join(":")) : "" };
-};
-
-// A template the code fills (postgresql://%s:%s@localhost/%s, {}:{}) names no user or database of
-// its own: tried, it would be refused for a password the settings never carried.
-const TEMPLATE = /%s|%\(\w+\)s|\$\{\w+|\{\w*\}/;
-
-// One setting that is a whole address: postgresql+asyncpg://u:p@localhost:5432/app, redis://localhost/2.
-function fromUrl(name, value) {
-  const m = SCHEME.exec(value);
-  if (!m || TEMPLATE.test(value)) return null;
-  const engine = SCHEME_ENGINE[m[1].toLowerCase()];
-  const a = authority(m[3]);
-  if (!a) return null;
-  const query = new URLSearchParams((m[5] ?? "").replace(/^[?#]/, ""));
-  const path = dec((m[4] ?? "").replace(/^\//, ""));
-  const db = engine === "redis" ? Number(path || 0) : path;
-  const host = a.host || query.get("host") || "";
-  const port = a.port ?? PORT_OF[engine] ?? null;
-  return {
-    engine, host, port, db,
-    conn: { host, port, user: a.user, password: a.password, sslmode: query.get("sslmode") ?? "", tlsOn: /^(?:rediss|valkeys)$/i.test(m[1]), uri: value },
-    point: engine === "mongo" ? (to) => ({ [name]: withDb(value, to, db) }) : (to) => ({ [name]: `${m[1]}${m[2]}://${m[3]}/${encodeURIComponent(String(to))}${m[5] ?? ""}` }),
-    // The same address on another server: what a copy of the whole server is reached through.
-    move: (to, toPort) => ({ [name]: `${m[1]}${m[2]}://${m[3].slice(0, m[3].lastIndexOf("@") + 1)}${to}:${toPort}${m[4] ?? ""}${m[5] ?? ""}` }),
-  };
-}
-
-// A search or vector store's address: QDRANT_URL=http://localhost:6333, MILVUS_URI=localhost:19530,
-// ELASTICSEARCH_URL=http://elastic:pw@localhost:9200.
-function fromNamed(name, value) {
-  const engine = BY_NAME.find(([, re]) => re.test(name))?.[0];
-  if (!engine || SECRETISH.test(name)) return null;
-  const m = /^(?:(https?|grpc|bolt|neo4j):\/\/)?(?:([^@/\s]*)@)?([\w.-]+|\[[:\w]+\]):?(\d+)?([/?#].*)?$/i.exec(value);
-  if (!m || (!m[1] && !m[4])) return null;
-  const host = m[3].replace(/^\[|\]$/g, "");
-  const port = m[4] ? Number(m[4]) : m[1] === "https" ? 443 : PORT_OF[engine] ?? 80;
-  const [user, ...pass] = m[2] ? m[2].split(":") : [];
-  return {
-    engine, host, port, db: null,
-    conn: { base: `${m[1] === "https" ? "https" : "http"}://${host.includes(":") ? `[${host}]` : host}:${port}`, port, ...(user ? { user: dec(user), password: dec(pass.join(":")) } : {}) },
-    // A copy of the whole server speaks plain HTTP on this machine.
-    move: (to, toPort) => ({ [name]: `${m[1] ? "http://" : ""}${m[2] ? `${m[2]}@` : ""}${to}:${toPort}${m[5] ?? ""}` }),
-  };
-}
-
-// A search server's sign-in sits in settings beside its address: ELASTIC_PASSWORD, ES_API_KEY.
-const BY_NAME_ELASTIC = BY_NAME.find(([e]) => e === "elasticsearch")[1];
-function withLogin(store, values) {
-  if (store.conn.user) return store;
-  const own = (re) => values[Object.keys(values).find((n) => BY_NAME_ELASTIC.test(n) && re.test(n) && values[n])];
-  const apiKey = own(/API_?KEY$/);
-  const password = own(/(?:PASS|PASSWORD)$/);
-  if (apiKey) return { ...store, conn: { ...store.conn, apiKey } };
-  return password ? { ...store, conn: { ...store.conn, user: own(/USER(?:NAME)?$/) ?? "elastic", password } } : store;
-}
-
-// A vector store holds collections, and the app's settings name the ones it uses: QDRANT_COLLECTION,
-// COLLECTION_NAME. Each is its own store, pointed at its copy through that setting. A setting that
-// carries another engine's word (MONGODB_COLLECTION) is that engine's, and a bare one is this
-// store's only when no other store the settings name could own it. The key is the setting beside
-// it that ends in KEY.
-function withCollections(store, values, others) {
-  const word = new RegExp(store.engine, "i");
-  const shared = others.some((e) => e !== store.engine && !NO_COLLECTIONS.has(e));
-  const key = Object.keys(values).find((n) => word.test(n) && /KEY$/.test(n) && values[n]);
-  // QDRANT_HOST and QDRANT_PORT name the same server QDRANT_URL does.
-  const base = store.conn.base ?? `http://${store.host.includes(":") ? `[${store.host}]` : store.host}:${store.port}`;
-  const conn = { ...store.conn, base, ...(key ? { apiKey: values[key] } : {}) };
-  const named = Object.keys(values).filter((n) => /COLLECTION/.test(n) && !SECRETISH.test(n) && String(values[n] ?? "").trim() && (word.test(n) || (!ENGINE_WORD.test(n) && !shared)));
-  if (!named.length) return [{ ...store, conn }];
-  return named.map((n) => ({ ...store, conn, db: String(values[n]).trim(), names: [...store.names, n], point: (to) => ({ [n]: String(to) }) }));
-}
-
-// MongoDB's tools take one address: the parts' own, written as one.
-const mongoUri = (host, port, user, password) => `mongodb://${user ? `${encodeURIComponent(user)}:${encodeURIComponent(password ?? "")}@` : ""}${host || "127.0.0.1"}:${port}/`;
-
-// Settings that name one store in parts, grouped by what they share before the part:
-// POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB; DB_HOST, DB_NAME, DB_CONNECTION=pgsql; PGHOST, PGDATABASE.
-const HOST_PART = /^(.+?)_?(?:HOST(?:NAME)?|SERVER)$/;
-const PARTS = { port: /^PORT$/, user: /^USER(?:NAME)?$/, password: /^(?:PASS(?:WORD)?|PWD)$/, db: /^(?:DB|DATABASE|DBNAME|DB_?NAME|DATABASE_?NAME|NAME|INDEX)$/, kind: /^(?:ENGINE|DRIVER|DIALECT|CONNECTION|TYPE|CLIENT)$/ };
-const KIND_ENGINE = [["postgres", /pg|postgres/], ["mysql", /mysql|maria/], ["mongo", /mongo/], ["redis", /redis|valkey/]];
-function fromParts(values) {
-  const hosts = new Map();
-  for (const name of Object.keys(values)) { const m = HOST_PART.exec(name); if (m && !hosts.has(m[1])) hosts.set(m[1], name); }
-  // libpq's own settings need no host: without one it is the local socket.
-  if (!hosts.has("PG") && ["PGDATABASE", "PGUSER", "PGPORT"].some((n) => values[n])) hosts.set("PG", null);
-  const out = [];
-  for (const [p, hostName] of hosts) {
-    // A host setting left blank is a store the app is set up not to use (QDRANT_HOST= beside QDRANT_PATH).
-    if (hostName && !String(values[hostName] ?? "").trim()) continue;
-    // A host setting that holds a whole address (REDIS_HOST=redis://...) is fromUrl's, not a host.
-    if (hostName && String(values[hostName]).includes("://")) continue;
-    const parts = {};
-    for (const name of Object.keys(values)) {
-      if (!name.startsWith(p) || name === hostName) continue;
-      const rest = name.slice(p.length).replace(/^_/, "");
-      const part = Object.keys(PARTS).find((k) => PARTS[k].test(rest));
-      if (part && !parts[part]) parts[part] = name;
-    }
-    const [host = "", inline] = String(hostName ? values[hostName] : "").split(":");
-    const named = Number(values[parts.port] || inline) || null;
-    const kind = String(values[parts.kind] ?? "").toLowerCase();
-    const engine = WORD_ENGINE.find(([, re]) => re.test(p))?.[0] ?? KIND_ENGINE.find(([, re]) => re.test(kind))?.[0] ?? ENGINE_AT[named];
-    if (!engine) continue;
-    const port = named ?? PORT_OF[engine];
-    const db = parts.db ? (engine === "redis" ? Number(values[parts.db] || 0) : values[parts.db]) : engine === "redis" ? 0 : "";
-    out.push({
-      engine, host, port, db,
-      conn: { host, port, user: values[parts.user] ?? "", password: values[parts.password] ?? "", sslmode: p === "PG" ? values.PGSSLMODE ?? "" : "", ...(engine === "mongo" ? { uri: mongoUri(host, port, values[parts.user], values[parts.password]) } : {}) },
-      names: [hostName ?? parts.user ?? parts.port, parts.db].filter(Boolean),
-      // Only a setting that holds the database can point the app at another one.
-      point: parts.db ? (to) => ({ [parts.db]: String(to) }) : null,
-      move: !hostName ? null : parts.port ? (to, toPort) => ({ [hostName]: to, [parts.port]: String(toPort) }) : inline ? (to, toPort) => ({ [hostName]: `${to}:${toPort}` }) : null,
-    });
-  }
-  return out;
-}
-
-// Every store the app's settings name, one entry per database however many settings name it
-// (DATABASE_URL and DIRECT_URL, or DATABASE_URL beside POSTGRES_HOST and POSTGRES_DB). A setting
-// that names the server but no database (POSTGRES_USER for a container's first start) is the same
-// store as the one database its settings do name there.
-export function storesOf(values) {
-  const found = [];
-  for (const [name, raw] of Object.entries(values)) {
-    const value = String(raw ?? "").trim();
-    if (!value) continue;
-    const url = fromUrl(name, value);
-    if (url) { found.push({ ...url, names: [name] }); continue; }
-    const named = fromNamed(name, value);
-    if (named) found.push({ ...named, names: [name], point: null });
-  }
-  found.push(...fromParts(values));
-  const engines = found.map((s) => s.engine);
-  const each = found.flatMap((s) => (s.engine === "qdrant" ? withCollections(s, values, engines) : s.engine === "elasticsearch" ? [withLogin(s, values)] : [s]));
-  const byKey = new Map();
-  const merge = (held, s) => {
-    held.names = [...new Set([...held.names, ...s.names])];
-    if (s.point) held.points.push(s.point);
-    if (s.move) held.moves.push(s.move);
-    held.conn ??= s.conn;
-  };
-  const whole = each.filter((s) => s.db !== "" && s.db !== null);
-  for (const s of [...whole, ...each.filter((x) => !whole.includes(x))]) {
-    const key = `${at(s)}|${s.db ?? ""}`;
-    const held = byKey.get(key) ?? (s.db === "" || s.db === null ? [...byKey.values()].find((h) => at(h) === at(s)) : undefined);
-    if (held) { merge(held, s); continue; }
-    byKey.set(key, { ...s, key, points: s.point ? [s.point] : [], moves: s.move ? [s.move] : [] });
-  }
-  return [...byKey.values()];
-}
-
-// At most three by name, so a sentence stays one sentence.
-const listed = (names) => (names.length === 1 ? names[0] : names.length <= 3 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : `${names.slice(0, 2).join(", ")} and ${names.length - 2} more settings`);
-const unit = (s) => (s.engine === "qdrant" ? "collection" : "database");
-const whatOf = (s) => (s.engine === "redis" ? `Redis database ${s.db}` : s.db ? `${ENGINE[s.engine]} ${unit(s)} ${s.db}` : `${ENGINE[s.engine]} server`);
-const copied = [...new Set([...Object.keys(COPY), ...Object.keys(SERVER)])].map((e) => ENGINE[e]);
-const copiedList = `${copied.slice(0, -1).join(", ")} and ${copied.at(-1)}`;
-
-// Why no copy was made of a store on this machine, in a sentence of theirs, and the one thing to do.
-// The store's own words are never quoted: they name users and hosts.
-const HERE = {
-  started: () => ["your app was already running when this command started", "Stop your app"],
-  engine: (s) => [`we copy ${copiedList} for a run, not ${ENGINE[s.engine]}`, `Point ${s.names[0]} at a scratch ${s.db ? unit(s) : "server"}`],
-  fixed: (s) => [`no setting names its ${s.engine === "redis" ? "database number" : `${unit(s)} name`} to point the app at a copy`, `Put the ${s.engine === "redis" ? "database number" : `${unit(s)} name`} in a setting`],
-  auth: (s) => ["the password its settings carry was refused", `Check ${s.names[0]}`],
-  rights: () => ["the user it signs in as may not create databases", "Give that user the right to create databases"],
-  down: () => ["nothing answered at the address its settings give", "Start it"],
-  big: () => ["it is over the size a run copies", "Point it at a smaller scratch copy"],
-  missing: (s) => [`${TOOLS[s.engine] ?? "its own tools are"} not on this machine's PATH`, "Install them"],
-  version: () => ["this machine's copy of the store's own tools is older than the server", "Update them"],
-  oldServer: () => ["the server is older than Redis 6.2, which a copy needs", "Upgrade it"],
-  full: () => ["it has no empty database left to copy into", "Empty one of its databases"],
-  cluster: () => ["it runs as a cluster, which has one database only", "Point it at a scratch server"],
-  docker: () => ["a copy of it is made in Docker, which is not running on this machine", "Start Docker"],
-  login: (s) => ["your app signs in to it in a way a copy of it cannot be given", `Point ${s.names[0]} at a scratch server, or sign in with a user and password`],
-  container: () => ["Docker could not start a copy of it", "Check that Docker can pull and run its image"],
-  other: (s) => ["the copy did not go through", `Point ${s.names[0]} at a scratch ${s.db ? unit(s) : "server"}`],
-};
-const heldHere = (s, why) => {
-  const [reason, fix] = (HERE[why] ?? HERE.other)(s);
-  return `${listed(s.names)} ${s.names.length === 1 ? "points" : "point"} at the ${whatOf(s)} on this machine, and ${reason}, so test conversations would save into it. ${fix}, then run the connect command again.`;
-};
-const kept = (s, clone, how) => (s.engine === "redis"
-  ? `Your app runs against a copy of its Redis data in database ${clone} of the same server, through ${listed(s.names)}; database ${s.db} is not touched, and database ${clone} is emptied when this command ends and copied again at the next connect.`
-  : how === "empty"
-    ? `Your app makes its ${ENGINE[s.engine]} ${unit(s)} ${s.db} under the name ${clone} on the same server, through ${listed(s.names)}; the server holds no ${s.db} yet, and ${clone} is deleted when this command ends and made again empty at the next connect.`
-    : `Your app runs against a copy of its ${ENGINE[s.engine]} ${unit(s)} ${s.db}, made on the same server, through ${listed(s.names)}; the original is not touched, and the copy is deleted when this command ends and made again from the original at the next connect.`);
-const serverKept = (s) => `Your app runs against a copy of its whole ${ENGINE[s.engine]} server, made in a Docker container of ours, through ${listed(s.names)}; the original is not touched, and the container is deleted when this command ends and made again from the original at the next connect.`;
-
-// What holds Run for a store off this machine no copy could be made of, and the one thing to do.
-// The first reason is the most useful: a Neon store with no key says the key.
-const HELD = {
-  "neon-key": (s) => ["there is no NEON_API_KEY in its settings to make a branch with", `Set NEON_API_KEY, or point ${s.names[0]} at a database on this machine`],
-  neon: (s) => ["Neon did not make a branch of it", `Check NEON_API_KEY, or point ${s.names[0]} at a database on this machine`],
-  supabase: (s) => ["a local Supabase needs supabase/config.toml, Docker and the supabase command", `Add them, or point ${s.names[0]} at a local Supabase`],
-  engine: (s) => [`no copy of a hosted ${ENGINE[s.engine]} is made`, `Point ${s.names[0]} at a ${ENGINE[s.engine]} on this machine`],
-  parts: (s) => ["its settings name it in parts, which cannot be pointed at a copy", `Put its whole address in one setting, or point ${s.names[0]} at a database on this machine`],
-  "no-migrations": (s) => ["no migrations were found to build a copy on this machine from", `Point ${s.names[0]} at a database on this machine`],
-  "no-local": (s) => ["no Postgres on this machine let us make a database to build a copy in", "Start Postgres on this machine"],
-  migrations: (s, tool) => [`its ${tool} migrations did not run against a copy on this machine`, `Run them against a local database once by hand, or point ${s.names[0]} at one`],
-  started: () => ["your app was already running when this command started", "Stop your app"],
-  bypassed: () => ["your app reached it anyway, since it loads its settings file over the settings it was started with", "Load that file without overriding what is already set"],
-  other: (s) => ["the copy did not go through", `Point ${s.names[0]} at a database on this machine`],
-};
-// The fact and the way to keep the store out of the run, read by the person on the card and by their
-// agent in status. The other way, the owner's yes, is each surface's own to offer: the card as its
-// button, status in the sentence after this one (src/local/contact.ts heldLine). Written in here, the
-// card told the owner, on the card, that "the owner can say yes to it on the card in the browser".
-const heldWhy = (s, why, tool) => {
-  const [reason, fix] = (HELD[why] ?? HELD.other)(s, tool);
-  return `${listed(s.names)} ${s.names.length === 1 ? "points" : "point"} at ${s.engine === "redis" || s.db ? "the" : "a"} ${whatOf(s)} that is not on this machine, and ${reason}, so test conversations would save into it. ${fix}, then run the connect command again.`;
-};
-// A Qdrant server the app writes into is kept by the hook in the app instead of by a copy made here:
-// the first write a run makes into a collection copies that collection on the same server and the
-// app's later calls go to the copy (lib/trace.cjs, lib/pyhook/sitecustomize.py). So a hosted Qdrant
-// holds nothing, and neither does a local one whose collection no setting names.
-export const GUARDED_ENGINES = new Set(["qdrant"]);
-const guardedKept = (s) => `Your app's ${ENGINE[s.engine]} collections at ${listed(s.names)} are not written into by a run: the first time a run writes into one, that collection is copied on the same server and the app's calls go to the copy, which is deleted when this command ends.`;
-const hostedKept = (s, got) => (got.how === "neon"
-  ? `Your app runs against a Neon branch of its ${whatOf(s)}, made for this session through ${listed(s.names)}; the original is not touched, and the branch is deleted when this command ends and made again from the original at the next connect.`
-  : got.how === "supabase"
-    ? `Your app runs against a Supabase on this machine started from supabase/config.toml, through ${listed(s.names)}; the hosted one is not touched, and what test conversations create in the local one stays there${got.started ? ", and it is stopped when this command ends" : ""}.`
-    : `Your app runs against an empty ${ENGINE[s.engine]} database on this machine built by its own ${got.tool} migrations, through ${listed(s.names)}; the hosted one is not touched, and the copy is deleted when this command ends and built again empty at the next connect.`);
-// How the person's yes names a store off this machine: never its address.
-export const storeId = (s) => createHash("sha256").update(s.key).digest("hex").slice(0, 16);
-// A store off this machine the app was pointed at a copy of and reached anyway (dotenv's override):
-// trials write into the original, so it holds Run. `blocked`: the rows already holding it.
-export const bypassedOf = (connections, stores, blocked) => stores
-  .filter((s) => !onThisMachine(s.host) && !GUARDED_ENGINES.has(s.engine) && !blocked.some((b) => b.id === storeId(s)) && connections.some((c) => hostKey(c.host) === hostKey(s.host)))
-  .map((s) => ({ id: storeId(s), names: s.names, why: heldWhy(s, "bypassed") }));
-
-// A copy that throws is one that did not go through, said as such; it never stops the app starting.
-const drop = (s, clone, marker) => COPY[s.engine].drop(s, clone, marker).catch(() => false);
-const copy = (s, clone, marker) => COPY[s.engine].copy(s, clone, marker).catch(() => ({ why: "other" }));
-const serve = (s, name) => SERVER[s.engine](s, name).catch(() => ({ why: "other" }));
-const undo = (s, row) => (row.kind === "server" ? removeCopy(row.made) : drop(s, row.made, row.marker));
-const cloneName = (db) => `${String(db).slice(0, 40)}_cortad_${process.pid}`;
-// Refusals a copy of the whole server would meet the same way.
-const SERVER_TOO = new Set(["auth", "big", "down"]);
-
-// One session's copies. keep() copies the stores given that answer and says what it did; a store
-// nothing answers at yet is left out, unsaid, since trials cannot write into it: once it is started
-// (lib/backing.mjs), keep() is asked again for it. drop() deletes every copy, and copies a session
-// that died left behind are deleted by the next one, through the ledger. A store with no copy is
-// `blocked`, and `pass` names the hosts of the copies made off this machine.
-// `values`, `dirs`, `fetchFn` and `local` are lib/hosted.mjs's.
-export function storeKeeper({ ledgerFile, values = {}, dirs = [], fetchFn, local }) {
-  const book = ledger(ledgerFile);
-  const hosted = hostedKeeper({ values, dirs, book, fetchFn, local });
-  const made = [];
-  const done = new Set();
-  return {
-    async keep(stores, { started = true, down = () => false } = {}) {
-      for (const row of book.orphans("copy")) {
-        const s = stores.find((x) => x.key === row.key);
-        if (s && (await drop(s, row.made, row.marker))) book.remove(row);
-      }
-      for (const row of book.orphans("server")) if (await removeCopy(row.made)) book.remove(row);
-      await hosted.orphans();
-      const env = {};
-      const copies = [];
-      const blocked = [];
-      const pass = [];
-      for (const s of stores) {
-        if (done.has(s.key)) continue;
-        if (GUARDED_ENGINES.has(s.engine) && (!onThisMachine(s.host) || !s.points.length || !s.db)) {
-          if (await down(s)) continue;
-          done.add(s.key);
-          copies.push(guardedKept(s));
-          continue;
-        }
-        if (!onThisMachine(s.host)) {
-          done.add(s.key);
-          const got = started ? await hosted.keep(s).catch(() => ({ why: ["other"] })) : { why: ["started"] };
-          if (!got.env) { blocked.push({ id: storeId(s), names: s.names, why: heldWhy(s, got.why[0], got.tool) }); continue; }
-          Object.assign(env, got.env);
-          pass.push(...got.pass);
-          copies.push(hostedKept(s, got));
-          continue;
-        }
-        if (await down(s)) continue;
-        done.add(s.key);
-        if (!started) { blocked.push({ id: storeId(s), names: s.names, why: heldHere(s, "started") }); continue; }
-        let why = !COPY[s.engine] ? "engine" : !s.points.length || (s.engine !== "redis" && !s.db) ? "fixed" : null;
-        if (!why) {
-          const marker = `${process.pid}-${Date.now()}`;
-          // Recorded before the copy starts, so a session killed mid-copy leaves a row the next one
-          // undoes. A Redis copy's database is found by its marker then.
-          const row = { kind: "copy", key: s.key, made: s.engine === "redis" ? null : cloneName(s.db), marker };
-          book.add(row);
-          const got = await copy(s, cloneName(s.db), marker);
-          if (!got.why) {
-            const clone = got.index ?? cloneName(s.db);
-            made.push({ s, row });
-            for (const point of s.points) Object.assign(env, point(clone));
-            copies.push(kept(s, clone, got.how));
-            continue;
-          }
-          if (await drop(s, row.made, marker)) book.remove(row);
-          // A database the server does not hold is one trials cannot write into.
-          if (got.why === "gone") continue;
-          why = got.why;
-        }
-        // The app names its databases in its code, or this machine lacks the store's own tools: the
-        // whole server is copied into a container of ours and the app's address moved to it.
-        if (SERVER[s.engine] && s.moves.length && !SERVER_TOO.has(why)) {
-          const row = { kind: "server", key: s.key, made: copyName(s.engine) };
-          book.add(row);
-          const got = await serve(s, row.made);
-          if (got.port) {
-            made.push({ s, row });
-            for (const move of s.moves) Object.assign(env, move("127.0.0.1", got.port));
-            copies.push(serverKept(s));
-            continue;
-          }
-          if (await removeCopy(row.made)) book.remove(row);
-          why = got.why;
-        }
-        blocked.push({ id: storeId(s), names: s.names, why: heldHere(s, why) });
-      }
-      return { env, copies, blocked, pass };
-    },
-    drop: async () => {
-      for (const { s, row } of made.splice(0)) if (await undo(s, row)) book.remove(row);
-      await hosted.drop();
-    },
-    // The collections the hook in the app copied for a run's writes (lib/trace.cjs copyOf), deleted
-    // with the key the settings hold for that server. Each is in the ledger from the moment it is
-    // seen, so one a killed session left is deleted by the next.
-    // ponytail: a server no setting names a key for is asked without one; a copy that refuses stays
-    // under its _cortad_ name for the person to see. The key the app sent never leaves the app.
-    async dropCopies(copies, stores) {
-      const rows = copies.map((c) => ({ kind: "qdrant-copy", key: c.base, made: c.clone }));
-      for (const row of rows) book.add(row);
-      const hostOf = (base) => { try { return new URL(base).hostname; } catch { return base; } };
-      for (const row of [...rows, ...book.orphans("qdrant-copy")]) {
-        // The hook names the server with its port and QDRANT_URL may not: the key is the host's.
-        const conn = { base: row.key, apiKey: stores.find((s) => s.engine === "qdrant" && s.conn?.base && hostOf(s.conn.base) === hostOf(row.key))?.conn.apiKey };
-        if (await dropQdrant(conn, row.made)) book.remove(row);
-      }
-    },
-  };
-}
-
-// The stores the app reached that no setting names, as the hook saw each connection: a store written
-// into a config file rather than the environment, one its maker's SDK finds by itself, or the ones an
-// app started with the person's own command was given. No copy stands in for any of them, so each
-// holds Run for the person's yes, once. `blocked`: the rows already holding it.
-export function unnamedHeld(connections, stores, blocked) {
-  const rows = [];
-  for (const { host, port } of connections) {
-    const local = onThisMachine(host);
-    const engine = local ? ENGINE_AT[port] : HOSTED.find(([, re]) => re.test(String(host).toLowerCase()))?.[0] ?? ENGINE_AT[port];
-    if (!engine || GUARDED_ENGINES.has(engine) || stores.some((s) => (local ? `${hostKey(s.host)}:${s.port}` === `localhost:${port}` : s.engine === engine && !onThisMachine(s.host)))) continue;
-    const id = createHash("sha256").update(`${engine}|${local ? "localhost" : String(host).toLowerCase()}|${port}`).digest("hex").slice(0, 16);
-    if ([...blocked, ...rows].some((b) => b.id === id)) continue;
-    // Named by its engine where a setting's name would stand: the API takes a name, never an address.
-    rows.push({ id, names: [ENGINE[engine].replace(/\W+/g, "_")], why: `Your app reaches ${/^[AEIOU]/.test(ENGINE[engine]) ? "an" : "a"} ${ENGINE[engine]} server ${local ? "on" : "off"} this machine that it was not given a copy of, so the run would write what its test conversations create into it as it is. Start your app on a copy of it, then run the connect command again.` });
-  }
-  return rows;
-}