memtrails 0.3.0 → 0.4.1

package/dist/core/extract.d.ts

@@ -111,6 +111,8 @@ export interface ExtractOptions {
     observations?: boolean;
     /** Passages of other conversations related to this part (consolidate.ts): what a description refers to is named. */
     known?: string[];
+    /** Aborted when the answer is no longer wanted: passed to each ask, and no further part is asked. */
+    signal?: AbortSignal;
 }
 /** Read one window. `unavailable`/`busy` come back as they are, so the worker can pause. */
 export declare function extractWindow(win: ReadableRequest[], meta: {
@@ -133,6 +135,7 @@ export declare function observeWindow(win: ReadableRequest[], before: ReadableRe
     ask?: Ask;
     chars: number;
     known?: string[];
+    signal?: AbortSignal;
 }): Promise<{
     observations: Observation[];
 } | {

package/dist/core/extract.js

@@ -39,15 +39,15 @@ what was decided, done, built, changed, fixed, deployed or found, and when. One
 several in one, none left out to keep the list short. Facts said in passing inside another request count; a small or
 one-off event counts; when in doubt, keep it. In a conversation between people, the replies are another person's words:
 what they tell about themselves counts as much. For each:
-- text: 10 to 60 words that stand alone — the event or fact itself, as told ("Melanie took her family camping in the
-  mountains"), never "On <date>, X said that …" (the date has its own field). Name who and what (names, never "he",
+- text: 10 to 60 words that stand alone — the event or fact itself, as told ("Rosa took her nephews kayaking on Lake
+  Bled"), never "On <date>, X said that …" (the date has its own field). Name who and what (names, never "he",
   "she", "it", "they"); keep every proper noun, title, number and quoted phrase exactly. A time said relatively stays
   as said, with the date it means, read off the Calendar line of the day it was said: "last week (the week before 26 June
   2023)", "yesterday (7 May 2023)", "on Friday (12 April 2024)". When the part names something only by description
-  ("the book you recommended", "my home country", "the kids") and KNOWN FROM OTHER CONVERSATIONS names it, write the name too ("Becoming Nicole",
-  "Sweden", "her three children") — never a fact from KNOWN that this part does not tell. What the person or a speaker
+  ("the book you recommended", "my home country", "the kids") and KNOWN FROM OTHER CONVERSATIONS names it, write the name too ("The Overstory",
+  "Portugal", "her three children") — never a fact from KNOWN that this part does not tell. What the person or a speaker
   says about their own life is true as told: no commentary on what the conversation did or did not confirm. A plan is
-  written as a plan ("Melanie planned to go swimming with the kids"). When it replaces something said before, say both
+  written as a plan ("Rosa planned to take the kids to the aquarium"). When it replaces something said before, say both
   (now X — before, Y).
 - about: who or what it is about, named as the conversation names them ("the person" for the one whose requests these
   are, unless the conversation names them).
@@ -336,6 +336,7 @@ export function partsOf(text, max = WINDOW_CHARS) {
     return out;
 }
 const outcomeIn = (x) => (OUTCOMES.includes(String(x?.outcome)) ? x.outcome : undefined);
+const STOPPED = { unavailable: 'the ask was stopped, so this part of the conversation waits to be consolidated' };
 /** What the model reads before the part: where it comes from, the calendar of its days, and what other conversations
  *  say that it may refer to. */
 function headerOf(win, meta, known) {
@@ -349,10 +350,13 @@ function headerOf(win, meta, known) {
 }
 async function askExtraction(prompt, opts) {
     const withObservations = opts.observations !== false;
+    if (opts.signal?.aborted)
+        return STOPPED;
     const r = await (opts.ask ?? defaultAsk)({
         purpose: 'memory', system: withObservations ? SYSTEM : SYSTEM_WITHOUT_OBSERVATIONS, prompt: redactString(prompt),
         schema: (withObservations ? SCHEMA : SCHEMA_WITHOUT_OBSERVATIONS), name: 'memory_consolidation',
         maxTokens: EXTRACT_MAX_TOKENS, timeoutMs: 300_000, consequence: 'so this part of the conversation waits to be consolidated',
+        ...(opts.signal ? { signal: opts.signal } : {}),
     });
     if ('unavailable' in r || 'busy' in r)
         return r;
@@ -440,9 +444,12 @@ export async function observeWindow(win, before, meta, opts) {
     for (const [k, text] of parts.entries()) {
         const earlier = k === 0 ? context : parts[k - 1].slice(-Math.floor(opts.chars / 2));
         const prompt = `${header}\n\n${earlier ? `JUST BEFORE (context only):\n${earlier}\n\n` : ''}TO READ${parts.length > 1 ? ` (part ${k + 1} of ${parts.length})` : ''}:\n${text}`;
+        if (opts.signal?.aborted)
+            return STOPPED;
         const r = await (opts.ask ?? defaultAsk)({
             purpose: 'memory', system: OBSERVE_SYSTEM, prompt: redactString(prompt), schema: OBSERVE_SCHEMA,
             name: 'memory_observations', maxTokens: 16_000, timeoutMs: 300_000, consequence: 'so this part of the conversation waits to be consolidated',
+            ...(opts.signal ? { signal: opts.signal } : {}),
         });
         if ('unavailable' in r || 'busy' in r)
             return r;

package/dist/core/gather.d.ts

@@ -10,6 +10,9 @@ export interface Gathered {
     /** With `notes`: what the kept memories say that answers the question, a few short lines (empty otherwise). Show them
      *  before the memories, as notes on them: on LoCoMo this took 79.5 to 80.9 (docs/BENCHMARKS.md). */
     notes: string[];
+    /** Set when the model did not read some candidates (none configured, unreachable, busy): why. They are all kept, by
+     *  rank — the result is then a wide search, not a gathered set. */
+    paused?: string;
 }
 /** `from`/`to`: the time the question asks about ("on 10 April 2022", "in October 2023"). What happened then is searched
  *  for besides everything else and read first — not instead: a question also names dates it only counts from ("as of

package/dist/core/gather.js

@@ -1,7 +1,7 @@
 /**
  * Gathering: a SET of memories for a question, not a top-k.
  *
- * A question that counts, lists, totals or compares ("how many doctors did I see", "what did I spend on luxury items")
+ * A question that counts, lists, totals or compares ("how many plumbers did we call", "what did I spend on camera gear")
  * needs every instance, and one ranked below the cut is a wrong answer however good the rest are — measured on
  * LongMemEval's multi-session questions: every fact our answers missed was in the store, as a dated observation, and not
  * in the room. Mem0 and Graphiti hand the reader a fixed number by similarity; here the fast model reads them:
@@ -14,7 +14,7 @@
  * the model did not answer keeps all of its candidates.
  */
 import { redactString } from './redact.js';
-import { defaultAsk } from '../llm.js';
+import { allOrAbort, defaultAsk } from '../llm.js';
 import { PROFILE_SHOWN } from './profiles.js';
 import { memorySearch, MAX_SEARCH } from './recall.js';
 import { cut } from './text.js';
@@ -34,7 +34,7 @@ cancelled, sold, replaced, ended, a new amount) or dates it. When unsure, keep i
 wrong, an extra one does not.
 
 In "searches", write up to ${MORE} short searches for instances the question could count that none of these memories
-shows — other kinds, other words for the same thing (for "luxury items": "designer handbag", "jewelry", "watch") —
+shows — other kinds, other words for the same thing (for "camera gear": "lens", "tripod", "memory card") —
 in the language of the question. Leave it empty when nothing is missing. Never translate.`;
 const SCHEMA = {
     type: 'object', additionalProperties: false, required: ['keep', 'searches'],
@@ -48,7 +48,7 @@ const SCHEMA = {
 const NOTES_RULE = `
 
 In "notes", write what the memories you kept say that answers the question, in a few short lines: every instance with
-its date as the memories give it ("Books Tim has read: Harry Potter (2023-08-02), The Name of the Wind (2023-08-11)"),
+its date as the memories give it ("Concerts Lena went to: a jazz trio at the Blue Room (2024-03-02), the orchestra's Mahler night (2024-04-19)"),
 names, numbers and words as written. Only what they state, as plain statements: never write that something is not said,
 not given, unclear or unknown — leave it out instead, since other memories may hold it — and never a guess. Leave notes
 empty when the memories you kept say nothing about it. In the language of the question.`;
@@ -70,24 +70,28 @@ async function pick(ask, question, list, notes = false) {
     const size = notes ? NOTES_PART : PART;
     for (let i = 0; i < list.length; i += size)
         parts.push(list.slice(i, i + size));
-    const answers = await Promise.all(parts.map(async (part) => {
+    // The parts asked at once; one that throws stops the others (allOrAbort).
+    const answers = await allOrAbort(parts.map((part) => async (signal) => {
         const prompt = `Question: ${question}\n\nMemories:\n${part.map((h, n) => line(h, n + 1)).join('\n')}`;
         const a = await ask({
             purpose: 'memory', system: notes ? SYSTEM + NOTES_RULE : SYSTEM, prompt: redactString(prompt),
             schema: (notes ? NOTES_SCHEMA : SCHEMA),
             name: 'memory_gather', maxTokens: 40 * part.length + (notes ? 1400 : 600), timeoutMs: 120_000, consequence: 'so these memories are kept unread',
+            signal,
         });
         if (!('answer' in a))
-            return { keep: part.map((h) => h.id), searches: [], notes: [] };
+            return { keep: part.map((h) => h.id), searches: [], notes: [], paused: 'unavailable' in a ? a.unavailable : 'the fast model is busy' };
         const got = a.answer;
         const ids = Array.isArray(got.keep) ? got.keep.filter((x) => typeof x === 'string') : [];
-        const keep = ids.map((x) => part[Number(x.replace(/^m/, '')) - 1]?.id).filter((x) => !!x);
+        // A small model can quote the line it means ("[m3] (2023-06-03) …"), so the label is looked for, not assumed to be all of it.
+        const keep = ids.map((x) => part[Number(/\bm(\d+)/.exec(x)?.[1] ?? 0) - 1]?.id).filter((x) => !!x);
         const searches = Array.isArray(got.searches) ? got.searches.filter((x) => typeof x === 'string' && !!x.trim()) : [];
         const said = notes && Array.isArray(got.notes) ? got.notes.filter((x) => typeof x === 'string' && !!x.trim()).map((x) => redactString(x.trim())) : [];
-        return { keep, searches, notes: said };
+        return { keep, searches, notes: said, paused: undefined };
     }));
+    const paused = answers.find((a) => a.paused !== undefined)?.paused;
     return { keep: new Set(answers.flatMap((a) => a.keep)), searches: [...new Set(answers.flatMap((a) => a.searches.map((s) => s.trim())))],
-        notes: answers.flatMap((a) => a.notes) };
+        notes: answers.flatMap((a) => a.notes), ...(paused !== undefined ? { paused } : {}) };
 }
 /** `from`/`to`: the time the question asks about ("on 10 April 2022", "in October 2023"). What happened then is searched
  *  for besides everything else and read first — not instead: a question also names dates it only counts from ("as of
@@ -114,5 +118,7 @@ export async function memoryGather(d, q, o) {
     const all = [...first, ...more];
     const kept = all.filter((h) => one.keep.has(h.id) || two.keep.has(h.id));
     const keptIds = new Set(kept.map((h) => h.id));
-    return { found: [...kept, ...all.filter((h) => !keptIds.has(h.id))], kept: kept.map((h) => h.id), searches, notes: [...one.notes, ...two.notes] };
+    const paused = one.paused ?? two.paused;
+    return { found: [...kept, ...all.filter((h) => !keptIds.has(h.id))], kept: kept.map((h) => h.id), searches, notes: [...one.notes, ...two.notes],
+        ...(paused !== undefined ? { paused } : {}) };
 }

package/dist/core/model.d.ts

@@ -1,3 +1,4 @@
+import { type DownloadOptions } from './qdrant-binary.js';
 export declare const MODEL_REPO = "onnx-community/embeddinggemma-300m-ONNX";
 export declare const MODEL_REVISION = "5090578d9565bb06545b4552f76e6bc2c93e4a66";
 export declare const MODEL_FILES: ReadonlyArray<{
@@ -6,11 +7,15 @@ export declare const MODEL_FILES: ReadonlyArray<{
     sha256: string;
 }>;
 export declare function defaultModelDir(): string;
+/** Every file in place at its pinned size, the marker written after the last of them was verified, and no one else could
+ *  have changed any of them since (the folders, the files and the marker this user's alone, as the Qdrant binary's). */
 export declare function modelReady(dir?: string): boolean;
-/** The model in `dir` (fetched and checked unless it is already there); the directory, ready for `modelDir`. */
-export declare function ensureModel(opts?: {
+/**
+ * The model in `dir` (fetched and checked unless it is already there); the directory, ready for `modelDir`. Each file
+ * is fetched to a temp of its own, checked on disk and renamed into place; one run at a time per `dir` (withLock), and
+ * the marker is taken away first, so a set left half-replaced is never taken as ready.
+ */
+export declare function ensureModel(opts?: DownloadOptions & {
     dir?: string;
     log?: (line: string) => void;
-    fetchImpl?: typeof fetch;
-    signal?: AbortSignal;
 }): Promise<string>;

package/dist/core/model.js

@@ -4,12 +4,10 @@
  * pinned size and SHA-256. 218 MB. The model is Google's, under the Gemma Terms of Use (ai.google.dev/gemma/terms);
  * memtrails does not ship it.
  */
-import { createHash } from 'node:crypto';
-import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { Readable } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
 import { cacheDir } from './paths.js';
+import { downloadVerified, ownedSafely, privateDir, withLock } from './qdrant-binary.js';
 export const MODEL_REPO = 'onnx-community/embeddinggemma-300m-ONNX';
 export const MODEL_REVISION = '5090578d9565bb06545b4552f76e6bc2c93e4a66';
 export const MODEL_FILES = [
@@ -22,53 +20,54 @@ export function defaultModelDir() {
     return join(cacheDir(), `embeddinggemma-300m-${MODEL_REVISION.slice(0, 8)}`);
 }
 const marker = (dir) => join(dir, '.verified');
+/** The model's folder and the folders its files are in. */
+const folders = (dir) => [...new Set([dir, ...MODEL_FILES.map((f) => dirname(join(dir, f.rel)))])];
 const stamp = MODEL_FILES.map((f) => `${f.rel}:${f.size}:${f.sha256}`).join('\n');
+/** Every file in place at its pinned size, the marker written after the last of them was verified, and no one else could
+ *  have changed any of them since (the folders, the files and the marker this user's alone, as the Qdrant binary's). */
 export function modelReady(dir = defaultModelDir()) {
     try {
-        return readFileSync(marker(dir), 'utf8') === stamp && MODEL_FILES.every((f) => existsSync(join(dir, f.rel)));
+        return readFileSync(marker(dir), 'utf8') === stamp &&
+            MODEL_FILES.every((f) => existsSync(join(dir, f.rel)) && statSync(join(dir, f.rel)).size === f.size) &&
+            [...folders(dir), marker(dir), ...MODEL_FILES.map((f) => join(dir, f.rel))].every(ownedSafely);
     }
     catch {
         return false;
     }
 }
-/** The model in `dir` (fetched and checked unless it is already there); the directory, ready for `modelDir`. */
+/**
+ * The model in `dir` (fetched and checked unless it is already there); the directory, ready for `modelDir`. Each file
+ * is fetched to a temp of its own, checked on disk and renamed into place; one run at a time per `dir` (withLock), and
+ * the marker is taken away first, so a set left half-replaced is never taken as ready.
+ */
 export async function ensureModel(opts = {}) {
     const dir = opts.dir ?? defaultModelDir();
     if (modelReady(dir))
         return dir;
-    opts.log?.(`[memtrails] fetching ${MODEL_REPO} (218 MB, Gemma Terms of Use)`);
-    for (const f of MODEL_FILES) {
-        const path = join(dir, f.rel);
-        mkdirSync(dirname(path), { recursive: true });
-        const part = `${path}.part`;
-        rmSync(part, { force: true });
-        const res = await (opts.fetchImpl ?? fetch)(`https://huggingface.co/${MODEL_REPO}/resolve/${MODEL_REVISION}/${f.rel}`, { signal: opts.signal, redirect: 'follow' });
-        if (!res.ok || !res.body)
-            throw new Error(`HTTP ${res.status} for ${f.rel}`);
-        const hash = createHash('sha256');
-        let size = 0;
-        try {
-            await pipeline(Readable.fromWeb(res.body), async function* (src) {
-                for await (const chunk of src) {
-                    const b = chunk;
-                    hash.update(b);
-                    size += b.length;
-                    yield b;
-                }
-            }, createWriteStream(part));
-        }
-        catch (err) {
-            rmSync(part, { force: true });
-            throw err;
+    // Made private, or refused when others could change them: what is verified in them is loaded later. A set already
+    // there in folders made before this is ready once they are private (checked again under the lock).
+    if (!opts.dir)
+        privateDir(cacheDir());
+    for (const d of folders(dir))
+        privateDir(d);
+    return withLock(dir, async () => {
+        if (modelReady(dir))
+            return dir; // another run finished it while this one waited
+        opts.log?.(`[memtrails] fetching ${MODEL_REPO} (218 MB, Gemma Terms of Use)`);
+        rmSync(marker(dir), { force: true });
+        for (const f of MODEL_FILES) {
+            const path = join(dir, f.rel);
+            const { file, tmp } = await downloadVerified(`https://huggingface.co/${MODEL_REPO}/resolve/${MODEL_REVISION}/${f.rel}`, dirname(path), f, opts);
+            try {
+                renameSync(file, path);
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
         }
-        const digest = hash.digest('hex');
-        if (size !== f.size || digest !== f.sha256) {
-            rmSync(part, { force: true });
-            throw new Error(`${f.rel}: got ${size} bytes sha256 ${digest}, expected ${f.size} ${f.sha256}`);
-        }
-        renameSync(part, path);
-    }
-    writeFileSync(marker(dir), stamp);
-    opts.log?.('[memtrails] embedding model ready');
-    return dir;
+        writeFileSync(marker(dir), stamp, { mode: 0o644 });
+        chmodSync(marker(dir), 0o644); // whatever the umask: a marker others could write is not trusted
+        opts.log?.('[memtrails] embedding model ready');
+        return dir;
+    }, { signal: opts.signal });
 }

package/dist/core/profiles.d.ts

@@ -1,4 +1,4 @@
-import type { ConsolidateDeps } from './consolidate.js';
+import { type ConsolidateDeps } from './consolidate.js';
 import type { MemoryItem, MemoryScope } from './store.js';
 export declare const PROFILE_MIN_ITEMS = 3;
 export declare const PROFILE_BROAD = 0.2;

package/dist/core/profiles.js

@@ -1,8 +1,8 @@
 /**
  * Profiles — what memory knows about one subject, gathered in one place (sleep's last step).
  *
- * A question about a subject whose facts were told over many conversations ("when did John join the brigade, and what
- * did he do there?") needs the dated facts of all of them, and a top 10 holds a few. For every concept enough long-term
+ * A question about a subject whose facts were told over many conversations ("when did Dana join the choir, and what
+ * did she sing there?") needs the dated facts of all of them, and a top 10 holds a few. For every concept enough long-term
  * items share — at least PROFILE_MIN_ITEMS of a project's items, and on at most PROFILE_BROAD of them (not the person
  * themselves, not the project's own name) — the fast model gathers what they say into one dated list of facts, word for
  * word: a `profile` item, keyed and searched like any other, whose provenance is every source it read.
@@ -17,7 +17,8 @@
  */
 import { createHash } from 'node:crypto';
 import { redactString } from './redact.js';
-import { defaultAsk } from '../llm.js';
+import { allOrAbort, defaultAsk } from '../llm.js';
+import { stamped } from './consolidate.js';
 import { conceptKey, cut } from './text.js';
 import { writeLtm } from './writer.js';
 export const PROFILE_MIN_ITEMS = 3;
@@ -86,15 +87,15 @@ export function profileSubjects(items, sizes) {
     return out;
 }
 const promptOf = (s) => `SUBJECT: ${s.concept}\n\nMEMORIES:\n${s.read.map((it) => `- (${when(it)}) ${it.title}: ${cut(it.summary.replace(/\s+/g, ' '), PROFILE_LINE)}`).join('\n')}`;
-function profileItem(s, title, facts) {
+function profileItem(s, title, facts, now) {
     const newest = s.read[s.read.length - 1];
-    return {
+    return stamped({
         uid: s.uid, kind: 'profile', scope: s.scope, project: s.project, engine: newest.engine, session: null, cwd: newest.cwd,
         where: s.concept, ts: Math.max(...s.read.map((it) => it.ts)), firstTs: Math.min(...s.read.map((it) => it.firstTs || it.ts)),
         title: cut(title.trim() || s.concept, 120), summary: facts.join('\n'), body: '', files: [], appliesWhen: '',
         confidence: 'curated', importance: 3, status: 'active', provenance: [...new Set(s.read.flatMap((it) => it.provenance))],
         seen: 1, fingerprint: s.fingerprint, concepts: [s.concept],
-    };
+    }, now);
 }
 /** Profiles written for the subjects whose items changed (at most `max`, several asks at once), and archived for the
  *  subjects that no longer qualify. An ask the model did not answer stops the night's profiles; the next night asks
@@ -122,12 +123,14 @@ export async function writeProfiles(d, max = PROFILES_PER_SLEEP) {
     }
     const todo = subjects.filter((s) => { const m = d.ltm.meta(s.uid); return m?.status !== 'active' || m.fp !== s.fingerprint; }).slice(0, max);
     let next = 0;
-    await Promise.all(Array.from({ length: Math.min(PROFILE_IN_FLIGHT, todo.length) }, async () => {
-        while (!r.paused && next < todo.length && !d.aborted()) {
+    // A lane that throws stops the others, their asks too (allOrAbort).
+    await allOrAbort(Array.from({ length: Math.min(PROFILE_IN_FLIGHT, todo.length) }, () => async (signal) => {
+        while (!r.paused && next < todo.length && !d.aborted() && !signal.aborted) {
             const s = todo[next++];
             const a = await (d.ask ?? defaultAsk)({
                 purpose: 'memory', system: PROFILE_SYSTEM, prompt: redactString(promptOf(s)), schema: PROFILE_SCHEMA,
                 name: 'memory_profile', maxTokens: 3000, timeoutMs: 180_000, consequence: "so this subject's profile waits for the next night",
+                signal,
             });
             if (!('answer' in a)) {
                 r.paused = 'unavailable' in a ? a.unavailable : 'busy';
@@ -137,7 +140,7 @@ export async function writeProfiles(d, max = PROFILES_PER_SLEEP) {
             const facts = (Array.isArray(answer.facts) ? answer.facts : []).filter((f) => typeof f === 'string' && !!f.trim()).map((f) => f.trim());
             if (!facts.length)
                 continue;
-            const it = profileItem(s, typeof answer.title === 'string' ? answer.title : '', facts);
+            const it = profileItem(s, typeof answer.title === 'string' ? answer.title : '', facts, (d.now ?? Date.now)());
             await writeLtm(d, [it]);
             d.ltm.put([it]);
             r.profiled++;

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

@@ -12,14 +12,61 @@ export declare function qdrantAsset(platform?: string, arch?: string): QdrantAss
 export declare function qdrantDir(): string;
 export declare function qdrantBinaryPath(a?: QdrantAsset | null): string | null;
 export declare const QDRANT_RELEASE_BASE = "https://github.com/qdrant/qdrant/releases/download/v1.20.0";
-/** The binary is in place and its archive was verified when it was unpacked. */
+/**
+ * Run only what this user alone could have put there: the cache, the folder, the binary and its marker owned by this
+ * user, no symlink, writable by no one else. The archive's hash is pinned but not the unpacked binary's (that needs every
+ * platform's archive to compute), so on a shared machine this is what stops a binary swapped in after unpacking.
+ * Windows has no owner bits; there the user's profile ACLs keep others out.
+ */
+export declare function ownedSafely(path: string): boolean;
+/**
+ * The folder made (0700) or made private, and this user's alone — or refused. What is verified in it is run or loaded
+ * later: a folder others could write to lets them swap a binary between its check and its run, or a download between
+ * its hash and its unpacking. (`mkdirSync`'s mode applies only to a folder it makes.)
+ */
+export declare function privateDir(dir: string): void;
+/** The binary is in place, its archive was verified when it was unpacked, and no one else could have changed it since. */
 export declare function qdrantReady(a?: QdrantAsset | null): boolean;
+/** A download given up after this long without a byte (the answer's headers included). */
+export declare const DOWNLOAD_STALL_MS = 60000;
+export interface DownloadOptions {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+    stallMs?: number;
+}
 /**
- * Fetch, verify and unpack the binary unless it is already there. Throws on a network failure, a size or hash
- * mismatch (the download is deleted), or a platform Qdrant does not ship for; the caller retries with backoff.
+ * `url` fetched into a fresh temp folder inside `dir`, never to a fixed name: two first runs at once (two processes, or
+ * two memories opened together in one) wrote the same `.part` and could rename each other's half-written file. The
+ * file is then checked as it is on disk, not as it streamed past, against its pinned size and SHA-256. Returns the
+ * file and its folder; the caller renames the file into place and removes the folder. Throws (leaving nothing) on a
+ * failure, a mismatch, or `stallMs` without a byte.
  */
-export declare function ensureQdrant(opts?: {
+export declare function downloadVerified(url: string, dir: string, pin: {
+    size: number;
+    sha256: string;
+}, o?: DownloadOptions): Promise<{
+    file: string;
+    tmp: string;
+}>;
+/** A lock not touched for this long is a dead holder's (the holder touches it every quarter of this). */
+export declare const LOCK_STALE_MS = 120000;
+/**
+ * `f` run holding `<path>.lock`, created with O_EXCL: a second first run, in another process or this one, waits and
+ * then finds the first one's result. A lock whose process is gone, or untouched for `staleMs`, is taken over. Nothing
+ * rests on the lock for correctness (every file is verified in a private temp and renamed into place); it keeps two
+ * runs from fetching the same hundreds of MB, and from swapping folders under each other.
+ */
+export declare function withLock<T>(path: string, f: () => Promise<T>, o?: {
     signal?: AbortSignal;
+    staleMs?: number;
+    pollMs?: number;
+}): Promise<T>;
+/**
+ * Fetch, verify and unpack the binary unless it is already there. Throws on a network failure or stall, a size or
+ * hash mismatch (the download is deleted), a platform Qdrant does not ship for, or a folder others could change; the
+ * caller retries with backoff. `asset` is for tests: another archive with its own pins.
+ */
+export declare function ensureQdrant(opts?: DownloadOptions & {
     log?: (line: string) => void;
-    fetchImpl?: typeof fetch;
+    asset?: QdrantAsset;
 }): Promise<string>;