memtrails 0.3.0 → 0.4.0

package/dist/core/qdrant-client.js

@@ -10,27 +10,19 @@
  * A query ranks items once per query vector and once by keywords (each hit grouped by item, so an item found through
  * several children counts once), then fuses those item rankings by rank (RRF). Only `active` items are ever returned
  * to recall; superseded and archived ones stay in the log, out of the index.
- *
- * MANY USERS (a server holding a memory per user): one collection for all of them, its `user` field a
- * tenant index (`is_tenant`). A client made with `tenant` adds that user to every query, count, scroll, update and
- * delete, stamps it on every point it writes, and keys each point by user and item, so two users' identical items are
- * two points. The user comes from the caller's context (whose work this is), never from a query's words; a call made
- * with no user is refused before it reaches Qdrant.
  */
 import { createHash } from 'node:crypto';
 import { MEMORY_EMBEDDER } from './embedder.js';
 export const COLLECTION = 'memory';
-/** The payload field a tenant client keys every point by, and the original point id it keeps beside the scoped one. */
-export const TENANT_FIELD = 'user';
-const TENANT_PID = 'pid';
 export const DIMS = MEMORY_EMBEDDER.dims;
 /** What the index is made of; a change empties it and it is written in again from the logs (rebuild.ts).
  *  2: binary quantisation with rescoring (½ the RAM of int8, recall 0.98–1.00 measured at 1–3M points), keyword terms
  *  folded and segmented for every language (text.ts); 3: on-disk binary copy, HNSW and payload indexes;
  *  4: remote EmbeddingGemma GPU vectors (768 dimensions, explicit runtime/pooling tag in embedder.ts); 5: nothing cut —
  *  every chunk of a body (no 12-chunk limit), short-term entries chunked too, cues numbered below the key, full payloads;
- *  6: every captured request indexed for good — however old, consolidated or not (the raw record is the truth). */
-export const INDEX_LAYOUT = 6;
+ *  6: every captured request indexed for good — however old, consolidated or not (the raw record is the truth);
+ *  7: a record's kind (`engine`) on every point of it and indexed, so a kinds filter finds a record by its chunks. */
+export const INDEX_LAYOUT = 7;
 /** The memory-mapped 1-bit copy finds candidates; full vectors on disk re-score 3× as many as asked. */
 const RESCORE = { quantization: { rescore: true, oversampling: 3.0 } };
 /** Two segments: Qdrant's default is one a core, which costs a laptop RAM and per-query work for nothing at memory's
@@ -65,42 +57,13 @@ export class QdrantError extends Error {
 export class QdrantClient {
     endpoint;
     timeoutMs;
-    opts;
-    collection;
+    /** `/collections/<name>`, the name encoded: a name you give is a path segment, never more of the path. */
+    at;
     /** `endpoint` may start Qdrant (the service runs it only while memory has work): every call waits for it. */
     constructor(endpoint, timeoutMs = 10_000, opts = {}) {
         this.endpoint = endpoint;
         this.timeoutMs = timeoutMs;
-        this.opts = opts;
-        this.collection = opts.collection ?? COLLECTION;
-    }
-    /** The user this call is for (a tenant client), or null (one person's own index). Throws when a tenant client has none. */
-    user() {
-        if (!this.opts.tenant)
-            return null;
-        const u = this.opts.tenant();
-        if (!u)
-            throw new QdrantError('memory index: this call names no user, so it is refused', 403);
-        return u;
-    }
-    /** A filter with the user added — unchanged for one person's own index. */
-    scoped(filter, user) {
-        if (user === null)
-            return filter;
-        return { ...filter, must: [{ key: TENANT_FIELD, match: { value: user } }, ...(filter?.must ?? [])] };
-    }
-    /** A point's id in a shared collection: the user's and the item's (pointId of both), so users never share a point. */
-    scopedId(id, user) {
-        return user === null ? id : pointId(`${user}\u0000${id}`, 0);
-    }
-    /** What a read hands back: the point's own id (as the writer named it) and only this user's points. */
-    own(points, user) {
-        if (user === null)
-            return points;
-        return points.filter((p) => p.payload[TENANT_FIELD] === user).map((p) => {
-            const { [TENANT_FIELD]: _u, [TENANT_PID]: pid, ...payload } = p.payload;
-            return { ...p, id: String(pid ?? p.id), payload };
-        });
+        this.at = `/collections/${encodeURIComponent(opts.collection ?? COLLECTION)}`;
     }
     async call(method, path, body, timeoutMs = this.timeoutMs) {
         const e = await this.endpoint();
@@ -138,7 +101,7 @@ export class QdrantClient {
     }
     /** Drop the whole collection: the index is derived, written again from the logs (rebuild.ts). */
     async dropCollection() {
-        await this.call('DELETE', `/collections/${this.collection}`).catch(() => undefined);
+        await this.call('DELETE', this.at).catch(() => undefined);
     }
     /** The collection and its payload indexes, made if missing — an index added since a collection was made is added to
      *  it in place. All of it on disk, memory-mapped — the vectors, their 1-bit copy, the graph, the payloads and their
@@ -148,14 +111,14 @@ export class QdrantClient {
     async ensureCollection() {
         let info = null;
         try {
-            info = (await this.call('GET', `/collections/${this.collection}`)) ?? {};
+            info = (await this.call('GET', this.at)) ?? {};
         }
         catch (err) {
             if (!(err instanceof QdrantError) || err.status !== 404)
                 throw err;
         }
         if (!info) {
-            await this.call('PUT', `/collections/${this.collection}`, {
+            await this.call('PUT', this.at, {
                 vectors: { dense: { size: DIMS, distance: 'Cosine', on_disk: true } },
                 sparse_vectors: { bm25: { modifier: 'idf', index: { on_disk: true } } },
                 quantization_config: { binary: { always_ram: false } },
@@ -167,41 +130,34 @@ export class QdrantClient {
         }
         else if (info.config?.optimizer_config?.default_segment_number !== SMALL.optimizers_config.default_segment_number) {
             // Made before: two segments from now on (the optimiser merges them in the background).
-            await this.call('PATCH', `/collections/${this.collection}`, { optimizers_config: SMALL.optimizers_config });
+            await this.call('PATCH', this.at, { optimizers_config: SMALL.optimizers_config });
         }
         const have = info.payload_schema ?? {};
-        // Many users: the user field first, as Qdrant's tenant index (its points kept together on disk, searched per user).
-        if (this.opts.tenant && !(TENANT_FIELD in have)) {
-            await this.call('PUT', `/collections/${this.collection}/index?wait=true`, { field_name: TENANT_FIELD, field_schema: { type: 'keyword', is_tenant: true, on_disk: true } });
-        }
         for (const [field_name, field_schema] of [['item', 'keyword'], ['part', 'keyword'], ['tier', 'keyword'], ['status', 'keyword'],
-            ['kind', 'keyword'], ['scope', 'keyword'], ['project', 'keyword'], ['session', 'keyword'], ['ts', 'integer'],
+            ['kind', 'keyword'], ['engine', 'keyword'], ['scope', 'keyword'], ['project', 'keyword'], ['session', 'keyword'], ['ts', 'integer'],
             ['synthetic', 'bool'], ['concepts', 'keyword'], ['eventFrom', 'integer'], ['eventTo', 'integer']]) {
             const schema = field_schema === 'keyword' || field_schema === 'integer' ? { type: field_schema, on_disk: true } : field_schema;
             if (!(field_name in have))
-                await this.call('PUT', `/collections/${this.collection}/index?wait=true`, { field_name, field_schema: schema });
+                await this.call('PUT', `${this.at}/index?wait=true`, { field_name, field_schema: schema });
         }
     }
     async upsert(points, wait = false) {
         if (!points.length)
             return;
-        const user = this.user();
-        const out = user === null ? points
-            : points.map((p) => ({ ...p, id: this.scopedId(p.id, user), payload: { ...p.payload, [TENANT_FIELD]: user, [TENANT_PID]: p.id } }));
-        await this.call('PUT', `/collections/${this.collection}/points?wait=${wait}`, { points: out }, 60_000);
+        await this.call('PUT', `${this.at}/points?wait=${wait}`, { points }, 60_000);
     }
     /** Every point of these items — before an item is written again (its children may be fewer now). */
     async deleteItems(items) {
         if (!items.length)
             return;
-        await this.call('POST', `/collections/${this.collection}/points/delete?wait=true`, { filter: this.scoped({ must: [{ key: 'item', match: { any: items } }] }, this.user()) }, 60_000);
+        await this.call('POST', `${this.at}/points/delete?wait=true`, { filter: { must: [{ key: 'item', match: { any: items } }] } }, 60_000);
     }
     /** One kind of point of these items (`cue`), before that part is written again. */
     async deleteParts(items, part) {
         if (!items.length)
             return;
-        await this.call('POST', `/collections/${this.collection}/points/delete?wait=true`, {
-            filter: this.scoped({ must: [{ key: 'item', match: { any: items } }, { key: 'part', match: { value: part } }] }, this.user()),
+        await this.call('POST', `${this.at}/points/delete?wait=true`, {
+            filter: { must: [{ key: 'item', match: { any: items } }, { key: 'part', match: { value: part } }] },
         }, 60_000);
     }
     /** Change some payload fields of these items' points (status, a merged key's display fields). */
@@ -211,13 +167,13 @@ export class QdrantClient {
         const must = [{ key: 'item', match: { any: items } }];
         if (keyOnly)
             must.push({ key: 'part', match: { value: 'key' } });
-        await this.call('POST', `/collections/${this.collection}/points/payload?wait=true`, { payload, filter: this.scoped({ must }, this.user()) }, 60_000);
+        await this.call('POST', `${this.at}/points/payload?wait=true`, { payload, filter: { must } }, 60_000);
     }
     /** The nearest key points to one vector (consolidation's "do I know this already?"), with their cosine. */
     async neighbors(vector, filter, limit = 5) {
         const must = [...(filter.must ?? []), { key: 'part', match: { value: 'key' } }];
-        const r = await this.call('POST', `/collections/${this.collection}/points/query`, {
-            query: vector, using: 'dense', limit, params: RESCORE, filter: this.scoped({ ...filter, must }, this.user()), with_payload: ['item', 'title', 'summary', 'kind', 'scope', 'project', 'status'],
+        const r = await this.call('POST', `${this.at}/points/query`, {
+            query: vector, using: 'dense', limit, params: RESCORE, filter: { ...filter, must }, with_payload: ['item', 'title', 'summary', 'kind', 'scope', 'project', 'status'],
         });
         return (r?.points ?? []).map((p) => ({ item: String(p.payload?.item ?? ''), score: p.score, payload: p.payload ?? {} }));
     }
@@ -226,50 +182,44 @@ export class QdrantClient {
     async bestPerItem(vector, items, part, timeoutMs = 2000) {
         if (!items.length)
             return new Map();
-        const r = await this.call('POST', `/collections/${this.collection}/points/query/groups`, {
+        const r = await this.call('POST', `${this.at}/points/query/groups`, {
             query: vector, using: 'dense', params: RESCORE,
-            filter: this.scoped({ must: [{ key: 'item', match: { any: items } }, { key: 'part', match: { value: part } }] }, this.user()),
+            filter: { must: [{ key: 'item', match: { any: items } }, { key: 'part', match: { value: part } }] },
             group_by: 'item', group_size: 1, limit: items.length, with_payload: false,
         }, timeoutMs);
         return new Map((r?.groups ?? []).map((g) => [String(g.id), g.hits[0]?.score ?? 0]));
     }
     /** `nearest` for several vectors in one call. */
-    /** `fields`: only these payload fields (and the item and its user), for a caller that needs no more — a walk over
+    /** `fields`: only these payload fields (and the item), for a caller that needs no more — a walk over
      *  many neighbours reads ids, not the bodies of long requests. */
     async nearestMany(vectors, filter, limit = 10, timeoutMs = 5000, fields) {
         if (!vectors.length)
             return [];
-        const user = this.user();
-        const withPayload = fields ? [...new Set([...fields, 'item', TENANT_FIELD])] : true;
-        const r = await this.call('POST', `/collections/${this.collection}/points/query/batch`, {
-            searches: vectors.map((v) => ({ query: v, using: 'dense', limit, params: RESCORE, filter: this.scoped(filter, user), with_payload: withPayload })),
+        const withPayload = fields ? [...new Set([...fields, 'item'])] : true;
+        const r = await this.call('POST', `${this.at}/points/query/batch`, {
+            searches: vectors.map((v) => ({ query: v, using: 'dense', limit, params: RESCORE, filter, with_payload: withPayload })),
         }, timeoutMs);
-        return (r ?? []).map((x) => this.own((x?.points ?? []).map((p) => ({ id: '', payload: p.payload ?? {}, score: p.score })), user)
-            .map((p) => ({ item: String(p.payload.item ?? ''), score: p.score, payload: p.payload })));
+        return (r ?? []).map((x) => (x?.points ?? []).map((p) => ({ item: String(p.payload?.item ?? ''), score: p.score, payload: p.payload ?? {} })));
     }
     /** Points within a filter, with their payload (and dense vector when asked) — at most `limit`. */
     async scroll(filter, limit = 256, withVector = false, timeoutMs = 5000) {
-        const user = this.user();
-        const r = await this.call('POST', `/collections/${this.collection}/points/scroll`, {
-            filter: this.scoped(filter, user), limit, with_payload: true, with_vector: withVector ? ['dense'] : false,
+        const r = await this.call('POST', `${this.at}/points/scroll`, {
+            filter, limit, with_payload: true, with_vector: withVector ? ['dense'] : false,
         }, timeoutMs);
-        return this.own((r?.points ?? []).map((p) => ({ id: String(p.id), payload: p.payload ?? {}, ...(p.vector?.dense ? { vector: p.vector.dense } : {}) })), user);
+        return (r?.points ?? []).map((p) => ({ id: String(p.id), payload: p.payload ?? {}, ...(p.vector?.dense ? { vector: p.vector.dense } : {}) }));
     }
     async count(filter) {
-        const scoped = this.scoped(filter, this.user());
-        const r = await this.call('POST', `/collections/${this.collection}/points/count`, { exact: false, ...(scoped ? { filter: scoped } : {}) });
+        const r = await this.call('POST', `${this.at}/points/count`, { exact: false, ...(filter ? { filter } : {}) });
         return r?.count ?? 0;
     }
     /** The items behind `ids` (key points), with their payload — and their dense vector when asked. */
     async retrieve(ids, withVector = false) {
         if (!ids.length)
             return [];
-        const user = this.user();
-        const r = await this.call('POST', `/collections/${this.collection}/points`, {
-            ids: ids.map((id) => this.scopedId(id, user)), with_payload: true, with_vector: withVector ? ['dense'] : false,
+        const r = await this.call('POST', `${this.at}/points`, {
+            ids, with_payload: true, with_vector: withVector ? ['dense'] : false,
         });
-        // A point is fetched by its id alone; another user's (a hash of their id and the item) is dropped all the same.
-        return this.own((r ?? []).map((p) => ({ id: String(p.id), payload: p.payload ?? {}, ...(p.vector?.dense ? { vector: p.vector.dense } : {}) })), user);
+        return (r ?? []).map((p) => ({ id: String(p.id), payload: p.payload ?? {}, ...(p.vector?.dense ? { vector: p.vector.dense } : {}) }));
     }
     /** The best items for the query, fused by rank — each with the point that matched best (`point`: its key, a chunk of
      *  its text, or a cue), so a caller can show the passage that matched. Each channel (a query vector, the keywords)
@@ -277,8 +227,7 @@ export class QdrantClient {
     async fusedItems(q, timeoutMs = 3000) {
         const limit = q.limit ?? 40;
         const per = q.per ?? Math.max(limit, 50);
-        const user = this.user();
-        const filter = this.scoped(q.filter, user);
+        const filter = q.filter;
         const channels = [];
         const sparse = q.sparse?.indices.length ? q.sparse : null;
         const denseWeight = (sparse ? DENSE_SHARE : 1) / Math.max(1, q.dense.length);
@@ -292,24 +241,23 @@ export class QdrantClient {
             channels.push({ query: sparse, using: 'bm25', weight: 1 - DENSE_SHARE });
         if (!channels.length)
             return [];
-        const lists = await Promise.all(channels.map((c) => this.call('POST', `/collections/${this.collection}/points/query/groups`, {
+        const lists = await Promise.all(channels.map((c) => this.call('POST', `${this.at}/points/query/groups`, {
             query: c.query, using: c.using, ...(c.params ? { params: c.params } : {}),
             ...(c.filter ?? filter ? { filter: c.filter ?? filter } : {}),
             group_by: 'item',
             group_size: 1,
             limit: per,
-            // A shared collection's point ids are scoped: the writer's own id is in the payload.
-            with_payload: user === null ? false : [TENANT_FIELD, TENANT_PID],
+            with_payload: false,
         }, timeoutMs)));
         const fused = new Map();
         lists.forEach((r, c) => {
-            const groups = (r?.groups ?? []).filter((g) => user === null || g.hits[0]?.payload?.[TENANT_FIELD] === user);
+            const groups = r?.groups ?? [];
             const scores = groups.map((g) => g.hits[0]?.score ?? 0);
             const lo = Math.min(...scores);
             const hi = Math.max(...scores);
             groups.forEach((g, rank) => {
                 const item = String(g.id);
-                const raw = user === null ? g.hits[0]?.id : g.hits[0]?.payload?.[TENANT_PID];
+                const raw = g.hits[0]?.id;
                 const at = fused.get(item) ?? { score: 0, rank: Infinity };
                 // A channel whose items all score alike (or that found one) counts each of them fully.
                 at.score += channels[c].weight * (hi > lo ? (scores[rank] - lo) / (hi - lo) : 1);

package/dist/core/qdrant-process.d.ts

@@ -4,6 +4,12 @@ export interface QdrantEndpoint {
 }
 /** The config file: what environment variables cannot say (gRPC off is `grpc_port: null`). */
 export declare function qdrantConfig(storage: string, port: number): string;
+/** When this machine started, in ms: a pid written down before a reboot names some other process now. */
+export declare function bootTime(): number;
+/** The same boot as `boot` (bootTime() of then): a minute apart at most, uptime being in whole seconds on some systems. */
+export declare function sameBoot(boot: unknown): boolean;
+/** A process with this pid exists — one of another user's too (EPERM). */
+export declare function alive(pid: number): boolean;
 export declare class QdrantProcess {
     private child;
     private endpoint;
@@ -20,10 +26,25 @@ export declare class QdrantProcess {
     });
     /** Where it answers, once it does; null while it starts or after it stopped. */
     current(): QdrantEndpoint | null;
+    /** Up and proven ours (owned), or it throws — and then nothing of this start keeps running or is started again: the
+     *  caller was told, and may not be there to stop it. */
     start(): Promise<QdrantEndpoint>;
-    /** Answering `/readyz` within 30 s, or the start failed. */
+    /** The pid file, and the child tracked for the host's exit; the file goes when that child does. */
+    private recordPid;
+    /** A Qdrant left running on this storage by a host that died without `close()` (a crash, a kill): stopped before
+     *  another starts on it. Only when the pid is still the process written down — this boot, its command naming this
+     *  folder's config — never an unrelated process that has the pid since. */
+    private reapLeftover;
+    /** Answering `/readyz` within 30 s, or the start failed. /readyz asks no key, so none is sent: what answers may not be
+     *  ours (owned). */
     private ready;
+    /** The port was free when picked, not when Qdrant bound it: another local process may have taken it, answered
+     *  /readyz, and would be handed the key and every document. Ours is still running, refuses a wrong key and takes
+     *  this run's — the wrong key asked first, so a process that takes any key never sees the real one. */
+    private owned;
     private exited;
+    /** Started again after a growing pause; a restart that fails counts as another death. */
+    private restartLater;
     stop(): void;
     /** Stop and wait for the process to be gone — before its storage is deleted. */
     stopAndWait(ms?: number): Promise<void>;

package/dist/core/qdrant-process.js

@@ -1,8 +1,9 @@
+import { execFileSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { closeSync, mkdirSync, openSync, statSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:net';
+import { uptime } from 'node:os';
 import { join, resolve } from 'node:path';
-import { spawn } from 'node:child_process';
 /** A port the OS says is free on loopback. */
 async function freePort() {
     return new Promise((resolve, reject) => {
@@ -39,7 +40,9 @@ export function qdrantConfig(storage, port) {
     ].join('\n');
 }
 const LOG_MAX = 4 * 1024 * 1024;
-/** The process's log beside its data, rotated once at start when it has grown past 4 MB. */
+/** Beside the storage: the pid of the Qdrant running on it, with its config and the machine's boot (reapLeftover). */
+const PID_FILE = 'qdrant.pid';
+/** The process's log beside its data, rotated once at start when it has grown past 4 MB. Private: it names paths. */
 function openLog(dir) {
     const path = join(dir, 'qdrant.log');
     try {
@@ -47,8 +50,75 @@ function openLog(dir) {
             renameSync(path, `${path}.1`);
     }
     catch { /* none yet */ }
-    mkdirSync(dir, { recursive: true });
-    return openSync(path, 'a');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const fd = openSync(path, 'a', 0o600);
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* not ours to change: written all the same */ }
+    return fd;
+}
+/** When this machine started, in ms: a pid written down before a reboot names some other process now. */
+export function bootTime() {
+    return Date.now() - uptime() * 1000;
+}
+/** The same boot as `boot` (bootTime() of then): a minute apart at most, uptime being in whole seconds on some systems. */
+export function sameBoot(boot) {
+    return typeof boot === 'number' && Math.abs(bootTime() - boot) < 60_000;
+}
+/** A process with this pid exists — one of another user's too (EPERM). */
+export function alive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A running process's command line, or null when it cannot be read (no /proc and no ps, Windows). */
+function commandOf(pid) {
+    try {
+        return readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').join(' ');
+    }
+    catch { /* not Linux */ }
+    if (process.platform === 'win32')
+        return null;
+    try {
+        return execFileSync('ps', ['-ww', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+    }
+    catch {
+        return null;
+    }
+}
+/** What Qdrant gets of the environment: what a process needs to run and the key. None of the host's secrets, and none
+ *  of its QDRANT__* variables — they override the config (QDRANT__SERVICE__HOST=0.0.0.0 would open it to the network). */
+function childEnv(apiKey) {
+    const env = {};
+    for (const k of ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'SystemRoot', 'USERPROFILE'])
+        if (process.env[k] !== undefined)
+            env[k] = process.env[k];
+    return { ...env, QDRANT__SERVICE__API_KEY: apiKey, QDRANT__TELEMETRY_DISABLED: 'true' };
+}
+/** Every Qdrant this process started and has not seen exit: stopped when the host exits without `close()` (an 'exit'
+ *  handler can only send the signal; a host killed outright leaves its Qdrant to the next start's reapLeftover). */
+const running = new Set();
+let exitHook = false;
+function track(child) {
+    running.add(child);
+    child.once('exit', () => running.delete(child));
+    if (exitHook)
+        return;
+    exitHook = true;
+    process.on('exit', () => { for (const c of running) {
+        try {
+            c.kill('SIGTERM');
+        }
+        catch { /* gone */ }
+    } });
 }
 export class QdrantProcess {
     child = null;
@@ -65,13 +135,16 @@ export class QdrantProcess {
     current() {
         return this.endpoint;
     }
+    /** Up and proven ours (owned), or it throws — and then nothing of this start keeps running or is started again: the
+     *  caller was told, and may not be there to stop it. */
     async start() {
         this.stopping = false;
         if (this.endpoint && this.child && this.child.exitCode === null)
             return this.endpoint;
+        mkdirSync(this.opts.dir, { recursive: true, mode: 0o700 });
+        await this.reapLeftover();
         const port = await freePort();
         const apiKey = randomBytes(24).toString('hex');
-        mkdirSync(this.opts.dir, { recursive: true });
         const config = join(this.opts.dir, 'config.yaml');
         writeFileSync(config, qdrantConfig(this.opts.dir, port), { mode: 0o600 });
         const fd = openLog(this.opts.dir);
@@ -80,46 +153,135 @@ export class QdrantProcess {
             child = spawn(this.opts.binary, ['--config-path', config, '--disable-telemetry'], {
                 cwd: this.opts.dir,
                 stdio: ['ignore', fd, fd],
-                // Only the key: the rest is in the config file.
-                env: { ...process.env, QDRANT__SERVICE__API_KEY: apiKey, QDRANT__TELEMETRY_DISABLED: 'true' },
+                env: childEnv(apiKey),
             });
         }
         finally {
             closeSync(fd);
         }
         this.child = child;
+        // A binary that is missing or cannot run is an 'error', never an 'exit' — unheard, it is thrown in the host.
+        let failed = null;
+        child.on('error', (err) => { failed ??= err; });
         child.once('exit', (code, signal) => this.exited(child, code, signal));
+        if (child.pid)
+            this.recordPid(child, config);
         const endpoint = { url: `http://127.0.0.1:${port}`, apiKey };
-        await this.ready(endpoint, child);
+        try {
+            await this.ready(endpoint, child, () => failed);
+            await this.owned(endpoint, child);
+            if (this.child !== child)
+                throw new Error('Qdrant was stopped while it started');
+        }
+        catch (err) {
+            if (this.child === child)
+                this.child = null; // exited() then schedules nothing
+            if (child.pid && child.exitCode === null && child.signalCode === null)
+                child.kill('SIGTERM');
+            throw err;
+        }
         this.endpoint = endpoint;
         this.opts.log(`[memory] Qdrant up on 127.0.0.1:${port}`);
         return endpoint;
     }
-    /** Answering `/readyz` within 30 s, or the start failed. */
-    async ready(e, child) {
+    /** The pid file, and the child tracked for the host's exit; the file goes when that child does. */
+    recordPid(child, config) {
+        const file = join(this.opts.dir, PID_FILE);
+        writeFileSync(file, JSON.stringify({ pid: child.pid, config, boot: bootTime() }), { mode: 0o600 });
+        track(child);
+        child.once('exit', () => {
+            try {
+                if (JSON.parse(readFileSync(file, 'utf8')).pid === child.pid)
+                    rmSync(file, { force: true });
+            }
+            catch { /* none */ }
+        });
+    }
+    /** A Qdrant left running on this storage by a host that died without `close()` (a crash, a kill): stopped before
+     *  another starts on it. Only when the pid is still the process written down — this boot, its command naming this
+     *  folder's config — never an unrelated process that has the pid since. */
+    async reapLeftover() {
+        const file = join(this.opts.dir, PID_FILE);
+        let rec;
+        try {
+            rec = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            return;
+        }
+        const pid = Number(rec.pid);
+        const config = join(this.opts.dir, 'config.yaml');
+        if (rec.config === config && sameBoot(rec.boot) && pid !== this.child?.pid && alive(pid) && commandOf(pid)?.includes(config)) {
+            this.opts.log(`[memory] stopping the Qdrant left running on ${this.opts.dir} (pid ${pid})`);
+            for (const [signal, ms] of [['SIGTERM', 10_000], ['SIGKILL', 2000]]) {
+                try {
+                    process.kill(pid, signal);
+                }
+                catch { /* gone */ }
+                for (const until = Date.now() + ms; alive(pid) && Date.now() < until;)
+                    await pause(50);
+                if (!alive(pid))
+                    break;
+            }
+        }
+        rmSync(file, { force: true });
+    }
+    /** Answering `/readyz` within 30 s, or the start failed. /readyz asks no key, so none is sent: what answers may not be
+     *  ours (owned). */
+    async ready(e, child, failed) {
         const until = Date.now() + 30_000;
         while (Date.now() < until) {
-            if (child.exitCode !== null)
-                throw new Error(`Qdrant exited (${child.exitCode}) while starting — see ${join(this.opts.dir, 'qdrant.log')}`);
+            const err = failed();
+            if (err)
+                throw new Error(`Qdrant could not be started (${this.opts.binary}): ${err.message}`);
+            if (child.exitCode !== null || child.signalCode !== null)
+                throw new Error(`Qdrant exited (${child.signalCode ?? child.exitCode}) while starting — see ${join(this.opts.dir, 'qdrant.log')}`);
             try {
-                const r = await fetch(`${e.url}/readyz`, { headers: { 'api-key': e.apiKey }, signal: AbortSignal.timeout(1000) });
+                const r = await fetch(`${e.url}/readyz`, { signal: AbortSignal.timeout(1000) });
+                await r.arrayBuffer().catch(() => undefined);
                 if (r.ok)
                     return;
             }
             catch { /* not listening yet */ }
-            await new Promise((r) => setTimeout(r, 100));
+            await pause(100);
         }
-        child.kill('SIGTERM');
         throw new Error('Qdrant did not answer within 30 s');
     }
+    /** The port was free when picked, not when Qdrant bound it: another local process may have taken it, answered
+     *  /readyz, and would be handed the key and every document. Ours is still running, refuses a wrong key and takes
+     *  this run's — the wrong key asked first, so a process that takes any key never sees the real one. */
+    async owned(e, child) {
+        const status = async (key) => {
+            const r = await fetch(`${e.url}/collections`, { headers: { 'api-key': key }, signal: AbortSignal.timeout(5000) });
+            await r.arrayBuffer().catch(() => undefined);
+            return r.status;
+        };
+        const gone = () => child.exitCode !== null || child.signalCode !== null;
+        const notOurs = `what answers on ${e.url} is not this memory's Qdrant`;
+        if (gone())
+            throw new Error(`${notOurs}: ours exited — see ${join(this.opts.dir, 'qdrant.log')}`);
+        const wrong = await status(randomBytes(24).toString('hex'));
+        if (wrong !== 401 && wrong !== 403)
+            throw new Error(`${notOurs}: it took a wrong key (${wrong})`);
+        const right = await status(e.apiKey);
+        if (right !== 200)
+            throw new Error(`${notOurs}: it refused this run's key (${right})`);
+        if (gone())
+            throw new Error(`${notOurs}: ours exited — see ${join(this.opts.dir, 'qdrant.log')}`);
+    }
     exited(child, code, signal) {
         if (this.child !== child)
             return;
+        // One that never came up is its start()'s to report: that start rejects, and schedules nothing.
+        const wasUp = this.endpoint !== null;
         this.child = null;
         this.endpoint = null;
-        if (this.stopping)
+        if (this.stopping || !wasUp)
             return;
-        const why = `Qdrant stopped (${signal ?? code})`;
+        this.restartLater(`Qdrant stopped (${signal ?? code})`);
+    }
+    /** Started again after a growing pause; a restart that fails counts as another death. */
+    restartLater(why) {
         this.opts.log(`[memory] ${why}`);
         const now = Date.now();
         this.deaths = [...this.deaths.filter((t) => now - t < 10 * 60_000), now];
@@ -127,11 +289,17 @@ export class QdrantProcess {
             this.opts.onDown?.(`${why}; five times in ten minutes, so it is left stopped`);
             return;
         }
-        const pause = Math.min(60_000, 1000 * 2 ** (this.deaths.length - 1));
+        const wait = Math.min(60_000, 1000 * 2 ** (this.deaths.length - 1));
         this.restartTimer = setTimeout(() => {
             this.restartTimer = null;
-            this.start().catch((err) => this.opts.onDown?.(err.message));
-        }, pause);
+            if (this.stopping)
+                return;
+            this.start().catch((err) => {
+                this.opts.onDown?.(err.message);
+                if (!this.stopping)
+                    this.restartLater(err.message);
+            });
+        }, wait);
         this.restartTimer.unref?.();
     }
     stop() {
@@ -150,7 +318,7 @@ export class QdrantProcess {
     async stopAndWait(ms = 10_000) {
         const c = this.child;
         this.stop();
-        if (!c || c.exitCode !== null)
+        if (!c || c.exitCode !== null || c.signalCode !== null)
             return;
         await new Promise((resolve) => {
             const t = setTimeout(resolve, ms);

package/dist/core/rebuild.d.ts

@@ -14,13 +14,17 @@ interface RebuildDeps {
 export declare class MemoryRebuild {
     private readonly d;
     private running;
+    /** The generation `running` was started for: a run() of the same one joins it, a later one waits for it. */
+    private runningFor;
     private generation;
     constructor(d: RebuildDeps);
     cancel(): void;
     settled(): Promise<void>;
     pending(): boolean;
-    /** Written BEFORE clearing an old index. A crash at any later point leaves a resumable rebuild. */
+    /** Written BEFORE clearing an old index. A crash at any later point leaves a resumable rebuild. A run in flight is
+     *  cancelled: it wrote into the index about to be cleared, and must neither move nor delete the new checkpoint. */
     begin(): void;
+    /** Joins the run in flight for the same begin(); after a newer begin(), waits for the cancelled one to stop first. */
     run(): Promise<void>;
     private save;
     /** One phase from its checkpoint: batches of `size`, up to `concurrency` written at once, the checkpoint moved over