@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/dist/modules/workspace/bounded-matcher.d.ts

@@ -0,0 +1,79 @@
+import { type IPatternMatcher, type IPatternSearch } from './pattern-matcher.contract.js';
+/**
+ * The one place a CALLER'S regular expression is run (see
+ * {@link IPatternMatcher}).
+ *
+ * The pattern never runs on the request thread: the lines go to a worker, the
+ * worker answers which of them match, and a search whose matching outlives its
+ * budget has its worker terminated (which interrupts even a regex
+ * mid-backtrack) and is answered with {@link PatternTooExpensiveError}.
+ * Nothing partial is returned: a search that blew its budget answers the 400
+ * alone.
+ *
+ * The semantics are the engine's own — the worker compiles the same source with
+ * the same flags and calls `test` on each line — so a pattern within budget
+ * matches exactly the lines it always did.
+ *
+ * The pool is this instance's own: the composition root builds one per graph
+ * and closes it when the graph stops, so no worker outlives what it served.
+ */
+export interface WorkerPatternMatcherOptions {
+    /** Matching time one search may spend, summed over every file it searches. Default 5 s. */
+    budgetMs?: number;
+    /** Workers kept for searches at once; a search past this waits for one to free up. Default 4. */
+    poolMax?: number;
+    /**
+     * Searches that may wait for a worker at once. A waiting search holds the
+     * lines it was handed, so the queue is capped: past it a search is refused
+     * with a 503 rather than piling file contents up in memory. Default 16.
+     */
+    maxWaiting?: number;
+    /**
+     * Longest pattern accepted. The pattern is compiled on the request thread
+     * (that is how a syntax error earns its 400 there), so its length is what
+     * bounds that. Default 1000.
+     */
+    maxPatternLength?: number;
+    /**
+     * Characters handed to the worker in one message. Posting a message copies
+     * it on the request thread, so a large file goes over in pieces of about
+     * this size rather than in one copy that would stall every other request.
+     * A single line longer than this is not posted at all: it is written into
+     * shared memory this many characters at a time, yielding between pieces,
+     * and the worker reads it from there. Default 1 MB.
+     */
+    batchChars?: number;
+    /**
+     * Lines handed to the worker in one message. Each line is an entry the
+     * copy has to walk whatever its length, so a file of empty lines is bounded
+     * by this, not by `batchChars`. Default 10,000.
+     */
+    batchLines?: number;
+}
+export declare class WorkerPatternMatcher implements IPatternMatcher {
+    private readonly budgetMs;
+    private readonly poolMax;
+    private readonly maxWaiting;
+    private readonly maxPatternLength;
+    private readonly batchChars;
+    private readonly batchLines;
+    private readonly idle;
+    private readonly all;
+    private readonly waiting;
+    private closed;
+    private readonly lease;
+    constructor(opts?: WorkerPatternMatcherOptions);
+    search(source: string, flags: string): IPatternSearch;
+    close(): Promise<void>;
+    /**
+     * Where the batch starting at `from` ends: about `batchChars` characters on,
+     * at most `batchLines` lines on, and never empty. A batch of one line past
+     * `batchChars` is handed over through shared memory instead (see
+     * {@link BoundedSearch.matchBatch}).
+     */
+    private batchEnd;
+    private acquire;
+    private release;
+    private spawn;
+}
+//# sourceMappingURL=bounded-matcher.d.ts.map

package/dist/modules/workspace/bounded-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-matcher.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/bounded-matcher.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,cAAc,EAGpB,MAAM,+BAA+B,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4CD,qBAAa,oBAAqB,YAAW,eAAe;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;gBAElB,IAAI,GAAE,2BAAgC;IAiBlD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc;IAgB/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;YAQF,OAAO;IAcrB,OAAO,CAAC,OAAO;IAQf,OAAO,CAAC,KAAK;CAcd"}

package/dist/modules/workspace/bounded-matcher.js

@@ -0,0 +1,261 @@
+import { Worker } from 'node:worker_threads';
+import { ToolError } from '../tool-helpers/tool.contract.js';
+import { PatternTooExpensiveError, SearchBusyError, } from './pattern-matcher.contract.js';
+/**
+ * Slack on top of the remaining budget before a batch is given up on: the
+ * budget counts only the worker's own matching time, so handing the lines over
+ * and the answer back must not be what trips it.
+ */
+const TRANSFER_GRACE_MS = 250;
+/** The worker: compiles the pattern it is handed and answers the indices of the lines it matches. */
+const WORKER_SOURCE = `
+const { parentPort } = require('node:worker_threads');
+const { performance } = require('node:perf_hooks');
+let cached = { key: null, re: null };
+parentPort.on('message', ({ source, flags, lines, shared, limit }) => {
+  try {
+    // One line too long to post, written into shared memory as raw UTF-16 code units.
+    if (shared) lines = [Buffer.from(shared).toString('utf16le')];
+    const key = flags + '/' + source;
+    if (cached.key !== key) cached = { key, re: new RegExp(source, flags) };
+    const re = cached.re;
+    const started = performance.now();
+    const hits = [];
+    for (let i = 0; i < lines.length && hits.length < limit; i++) {
+      re.lastIndex = 0;
+      if (re.test(lines[i])) hits.push(i);
+    }
+    parentPort.postMessage({ hits, elapsed: performance.now() - started });
+  } catch (err) {
+    parentPort.postMessage({ error: String(err && err.message ? err.message : err) });
+  }
+});
+`;
+export class WorkerPatternMatcher {
+    budgetMs;
+    poolMax;
+    maxWaiting;
+    maxPatternLength;
+    batchChars;
+    batchLines;
+    idle = [];
+    all = new Set();
+    waiting = [];
+    closed = false;
+    lease;
+    constructor(opts = {}) {
+        this.budgetMs = option('budgetMs', opts.budgetMs ?? 5_000, 1, MAX_TIMER_MS - TRANSFER_GRACE_MS);
+        // A pool of none would leave every search waiting for a worker that never comes.
+        this.poolMax = option('poolMax', opts.poolMax ?? 4, 1);
+        // No queue at all is allowed: every search past the pool is refused busy.
+        this.maxWaiting = option('maxWaiting', opts.maxWaiting ?? 16, 0);
+        this.maxPatternLength = option('maxPatternLength', opts.maxPatternLength ?? 1_000, 1);
+        this.batchChars = option('batchChars', opts.batchChars ?? 1_000_000, 1);
+        this.batchLines = option('batchLines', opts.batchLines ?? 10_000, 1);
+        this.lease = {
+            acquire: () => this.acquire(),
+            release: (w) => this.release(w),
+            batchEnd: (lines, from) => this.batchEnd(lines, from),
+            batchChars: this.batchChars,
+        };
+    }
+    search(source, flags) {
+        if (source.length > this.maxPatternLength) {
+            throw new ToolError(`Pattern too long: ${source.length} characters, and a search pattern may have at most ${this.maxPatternLength}.`, 400, { code: 'pattern_too_long' });
+        }
+        try {
+            new RegExp(source, flags);
+        }
+        catch (err) {
+            throw new ToolError(`Invalid regex: ${err.message}`, 400);
+        }
+        return new BoundedSearch(this.lease, source, flags, this.budgetMs);
+    }
+    async close() {
+        this.closed = true;
+        for (const waiter of this.waiting.splice(0))
+            waiter.reject(new SearchBusyError());
+        const workers = [...this.all];
+        this.idle.length = 0;
+        await Promise.all(workers.map((w) => w.terminate()));
+    }
+    /**
+     * Where the batch starting at `from` ends: about `batchChars` characters on,
+     * at most `batchLines` lines on, and never empty. A batch of one line past
+     * `batchChars` is handed over through shared memory instead (see
+     * {@link BoundedSearch.matchBatch}).
+     */
+    batchEnd(lines, from) {
+        let to = from;
+        let chars = 0;
+        const last = Math.min(lines.length, from + this.batchLines);
+        while (to < last && (to === from || chars + lines[to].length <= this.batchChars))
+            chars += lines[to++].length;
+        return to;
+    }
+    async acquire() {
+        if (this.closed)
+            throw new SearchBusyError();
+        if (this.idle.length === 0 && this.all.size >= this.poolMax && this.waiting.length >= this.maxWaiting) {
+            throw new SearchBusyError();
+        }
+        const w = this.idle.pop() ??
+            (this.all.size < this.poolMax
+                ? this.spawn()
+                : await new Promise((resolve, reject) => this.waiting.push({ resolve, reject })));
+        w.ref();
+        return w;
+    }
+    release(w) {
+        const next = this.waiting.shift();
+        if (next)
+            return next.resolve(w);
+        // An idle worker must not hold a process's exit open.
+        w.unref();
+        this.idle.push(w);
+    }
+    spawn() {
+        const w = new Worker(WORKER_SOURCE, { eval: true });
+        this.all.add(w);
+        // A worker that dies — terminated over budget, or out of memory — leaves the pool.
+        w.once('exit', () => {
+            this.all.delete(w);
+            const at = this.idle.indexOf(w);
+            if (at >= 0)
+                this.idle.splice(at, 1);
+            if (this.closed)
+                return;
+            const next = this.waiting.shift();
+            if (next)
+                next.resolve(this.spawn());
+        });
+        return w;
+    }
+}
+/** One search: a caller's pattern, matched off the event loop under one budget. */
+class BoundedSearch {
+    pool;
+    source;
+    flags;
+    budgetMs;
+    spentMs = 0;
+    constructor(pool, source, flags, budgetMs) {
+        this.pool = pool;
+        this.source = source;
+        this.flags = flags;
+        this.budgetMs = budgetMs;
+    }
+    async matchingLines(lines, limit) {
+        if (limit <= 0 || lines.length === 0)
+            return [];
+        if (this.spentMs >= this.budgetMs)
+            throw new PatternTooExpensiveError(this.source, this.budgetMs);
+        const w = await this.pool.acquire();
+        const hits = [];
+        try {
+            for (let from = 0; from < lines.length && hits.length < limit;) {
+                const to = this.pool.batchEnd(lines, from);
+                for (const i of await this.matchBatch(w, lines.slice(from, to), limit - hits.length))
+                    hits.push(from + i);
+                from = to;
+            }
+        }
+        catch (err) {
+            // Terminating is what stops a regex mid-backtrack; the pool replaces it.
+            void w.terminate();
+            throw err;
+        }
+        this.pool.release(w);
+        return hits;
+    }
+    /**
+     * One handoff to the worker, charged to this search's budget. No handoff
+     * copies more than `batchChars` characters on the request thread at once: a
+     * line longer than that goes over in shared memory, not in the message.
+     */
+    async matchBatch(w, lines, limit) {
+        if (this.spentMs >= this.budgetMs)
+            throw new PatternTooExpensiveError(this.source, this.budgetMs);
+        const oversized = lines.length === 1 && lines[0].length > this.pool.batchChars;
+        const payload = oversized ? { shared: await shareLine(w, lines[0], this.pool.batchChars) } : { lines };
+        const remaining = this.budgetMs - this.spentMs;
+        const reply = await run(w, { source: this.source, flags: this.flags, ...payload, limit }, remaining + TRANSFER_GRACE_MS);
+        if (reply === 'timeout') {
+            this.spentMs = this.budgetMs;
+            throw new PatternTooExpensiveError(this.source, this.budgetMs);
+        }
+        if ('error' in reply)
+            throw new ToolError(`Invalid regex: ${reply.error}`, 400);
+        this.spentMs += reply.elapsed;
+        if (this.spentMs > this.budgetMs)
+            throw new PatternTooExpensiveError(this.source, this.budgetMs);
+        return reply.hits;
+    }
+}
+/**
+ * A line as raw UTF-16 code units in shared memory, which a message hands the
+ * worker without copying. It is written `chunkChars` at a time with a turn of
+ * the event loop between, so a line of any length never holds the request
+ * thread for longer than one chunk. Raw code units keep the line exact, lone
+ * surrogates included.
+ *
+ * The worker it is meant for can be terminated by `close()` during those turns,
+ * before {@link run} listens for its exit; a message posted to it then would
+ * never be answered. So its exit is watched here too: writing stops and the
+ * search is answered busy, as one terminated under `run` is.
+ */
+async function shareLine(w, line, chunkChars) {
+    let exited = false;
+    const onExit = () => {
+        exited = true;
+    };
+    w.once('exit', onExit);
+    try {
+        const shared = new SharedArrayBuffer(line.length * 2);
+        const bytes = Buffer.from(shared);
+        for (let at = 0; at < line.length && !exited; at += chunkChars) {
+            if (at > 0)
+                await new Promise((resolve) => setImmediate(resolve));
+            bytes.write(line.slice(at, at + chunkChars), at * 2, 'utf16le');
+        }
+        if (exited)
+            throw new SearchBusyError();
+        return shared;
+    }
+    finally {
+        w.off('exit', onExit);
+    }
+}
+function run(w, message, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const settle = (fn) => {
+            clearTimeout(timer);
+            w.off('message', onMessage);
+            w.off('error', onError);
+            w.off('exit', onExit);
+            fn();
+        };
+        const onMessage = (reply) => settle(() => resolve(reply));
+        const onError = (err) => settle(() => reject(err));
+        // Terminated under the search by `close()`: answered as busy, not left hanging until the timer.
+        const onExit = () => settle(() => reject(new SearchBusyError()));
+        const timer = setTimeout(() => settle(() => resolve('timeout')), timeoutMs);
+        w.on('message', onMessage);
+        w.on('error', onError);
+        w.on('exit', onExit);
+        w.postMessage(message);
+    });
+}
+/**
+ * The longest delay `setTimeout` honours. A longer one fires after 1 ms, so a
+ * budget past this (less the grace added to it) would stop every search at once.
+ */
+const MAX_TIMER_MS = 2_147_483_647;
+/** A sizing option as given, refused at construction unless it is an integer from `min` to `max`. */
+function option(name, value, min, max = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new RangeError(`WorkerPatternMatcher: ${name} must be an integer from ${min} to ${max}, got ${value}.`);
+    }
+    return value;
+}
+//# sourceMappingURL=bounded-matcher.js.map

package/dist/modules/workspace/bounded-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-matcher.js","sourceRoot":"","sources":["../../../src/modules/workspace/bounded-matcher.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/fetch-instant.d.ts

@@ -0,0 +1,9 @@
+/**
+ * An instant on the one clock that fetch starts and `fetchedSince` instants
+ * are read from. Milliseconds, like `Date.now()`, but strictly increasing in
+ * call order: two readings never compare equal, so a fetch started in the
+ * same millisecond as a listing is still ordered before or after it, and
+ * "started after the instant" is a strict comparison that cannot be a tie.
+ */
+export declare function fetchInstant(): number;
+//# sourceMappingURL=fetch-instant.d.ts.map

package/dist/modules/workspace/fetch-instant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-instant.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/fetch-instant.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAGrC"}

package/dist/modules/workspace/fetch-instant.js

@@ -0,0 +1,13 @@
+let last = 0;
+/**
+ * An instant on the one clock that fetch starts and `fetchedSince` instants
+ * are read from. Milliseconds, like `Date.now()`, but strictly increasing in
+ * call order: two readings never compare equal, so a fetch started in the
+ * same millisecond as a listing is still ordered before or after it, and
+ * "started after the instant" is a strict comparison that cannot be a tie.
+ */
+export function fetchInstant() {
+    last = Math.max(Date.now(), last + 0.001);
+    return last;
+}
+//# sourceMappingURL=fetch-instant.js.map

package/dist/modules/workspace/fetch-instant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-instant.js","sourceRoot":"","sources":["../../../src/modules/workspace/fetch-instant.ts"],"names":[],"mappings":"AAAA,IAAI,IAAI,GAAG,CAAC,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/modules/workspace/index.d.ts

@@ -7,4 +7,13 @@
  */
 export { FileReaderRegistry, type FileKind, type FileReader, type ReadResult, } from './file-readers/file-reader.js';
 export { OCTET_STREAM, rawExtensionOf, rawMimeFor } from './file-readers/raw-mime.js';
+/**
+ * The knowledge base's one repository, every branch workspace a worktree of
+ * it. (Where a checkout's git directory is — its `.git` folder, or the
+ * folder its `.git` FILE names — is `kb-fs/git-dir.ts`.)
+ */
+export { KbRepository, repositoryDirFor, workingCopyShape, type WorkingCopyShape, } from './kb-repository.js';
+export type { AddWorktreeOptions, FetchOptions, IKbRepository } from './kb-repository.contract.js';
+export { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_DESCRIPTION, SESSION_ID_INPUT, ToolDescriptionNotes, type AgentAccessGate, } from './agent-access.gate.js';
+export { SpillStore } from './spill-store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/workspace/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,kBAAkB,EAClB,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACtF;;;;GAIG;AACH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAGnG,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/modules/workspace/index.js

@@ -7,4 +7,14 @@
  */
 export { FileReaderRegistry, } from './file-readers/file-reader.js';
 export { OCTET_STREAM, rawExtensionOf, rawMimeFor } from './file-readers/raw-mime.js';
+/**
+ * The knowledge base's one repository, every branch workspace a worktree of
+ * it. (Where a checkout's git directory is — its `.git` folder, or the
+ * folder its `.git` FILE names — is `kb-fs/git-dir.ts`.)
+ */
+export { KbRepository, repositoryDirFor, workingCopyShape, } from './kb-repository.js';
+// The agent-access gate: what a module's agent tools take to tell the
+// deployment's hooks of a read or a write, and the session input they declare.
+export { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_DESCRIPTION, SESSION_ID_INPUT, ToolDescriptionNotes, } from './agent-access.gate.js';
+export { SpillStore } from './spill-store.js';
 //# sourceMappingURL=index.js.map

package/dist/modules/workspace/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/workspace/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,kBAAkB,GAInB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/modules/workspace/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,kBAAkB,GAInB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACtF;;;;GAIG;AACH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAE5B,sEAAsE;AACtE,+EAA+E;AAC/E,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,GAErB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/modules/workspace/kb-repository.contract.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The knowledge base's one repository, every branch workspace a worktree of
+ * it — the contract its consumers (the workspace service, the KB startup
+ * phase, the set-aside of a moved repository, the git layer) depend on.
+ * `KbRepository` (`kb-repository.ts`) is the implementation, a bare
+ * repository driven by the git CLI; the composition root makes ONE and
+ * injects it everywhere, so that one fetch serves every workspace and the
+ * repository's administration — its creation, the writes to its one config
+ * file, its worktree list, a set-aside — is serialized in one place.
+ *
+ * Nothing else is serialized by the application: git was built for many
+ * worktrees of one repository, and protects the refs, `packed-refs` and the
+ * object store with its own locks. The worktree list (`worktrees/`) it does
+ * not lock, which is why adding, removing and pruning worktrees are
+ * administration here. Two worktrees run side by side, as two developers'
+ * worktrees of one repository do.
+ */
+export interface FetchOptions {
+    /** A fetch that SUCCEEDED this recently is fresh enough; nothing runs. */
+    maxAgeMs: number;
+    /**
+     * An instant (`fetchInstant()`): a success counts as fresh only when
+     * its fetch started after it, however young it is (a fetch from before a listing may lack
+     * what the listing saw). A fetch in flight that started before it is
+     * waited for, not joined, and a fresh one runs.
+     */
+    fetchedSince?: number;
+    /** Skip the freshness window (the in-flight join still applies). */
+    force?: boolean;
+    /**
+     * A fetch that FAILED this recently is not retried: the answer is the
+     * failure. For pollers, so a host that is down is not asked again on every
+     * request. Absent, a failure is retried on the next call.
+     */
+    failureBackoffMs?: number;
+}
+export interface AddWorktreeOptions {
+    /** A converted clone whose branch was never pushed: its local ref is enough. */
+    allowLocalOnly?: boolean;
+    /** A conversion: a local ref behind the remote stays where it is. */
+    keepLocalTip?: boolean;
+    /**
+     * Reuse the repository's own fetch when it started after this instant
+     * (`fetchInstant()`)
+     * and knows the branch. An instant, not an age: it is compared inside the
+     * reservation, so time spent waiting for it cannot age a fetch out.
+     */
+    fetchedSince?: number;
+}
+export interface IKbRepository {
+    /** The bare repository's folder. */
+    readonly dir: string;
+    /**
+     * Run `fn` as the repository's one administrator for its duration: no
+     * creation of the repository, no write to its one config file (git refuses
+     * a second writer of it rather than waiting), no change to its worktree
+     * list (which git does not lock: a prune beside a `worktree add` can take
+     * the entry being made), and no set-aside runs beside it. Git operations
+     * in the worktrees are not held back — git's own locks cover them — so a
+     * caller that moves the repository's folders holds those off itself (the
+     * startup phase runs before anything is served; the workspace service
+     * wraps a set-aside in what surrounds one). Never nested: `fn` must not
+     * call `exclusive` again, nor a method that does (`ensure`,
+     * `refreshCredentials`, `writeConfig`, `addWorktree`, `removeWorktree`,
+     * `forgetWorktrees`, `prune`, `setOriginUrl`).
+     */
+    exclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /** Whether the repository is on disk and finished (its first fetch landed). */
+    exists(): Promise<boolean>;
+    /** Create the repository and fetch it once when it is not there. Throws with git's words, redacted. */
+    ensure(): Promise<void>;
+    /** Re-stamp the credential helper when the deployment's credential changed. */
+    refreshCredentials(): Promise<void>;
+    /** Run `git config` writes against the shared configuration, one writer at a time. */
+    writeConfig(cwd: string, argLists: readonly string[][]): Promise<void>;
+    /**
+     * Garbage-collect the repository when git finds it worth it (`gc --auto`
+     * with git's default thresholds). Automatic collection is off on the
+     * repository — a commit in one worktree would otherwise collect beside
+     * every other worktree's work — so the startup phase runs this once, when
+     * nothing else does. Never throws.
+     */
+    maintain(): Promise<void>;
+    /** The last time the repository reached the remote and whether it worked; null before any attempt. */
+    lastContact(): {
+        at: number;
+        ok: boolean;
+    } | null;
+    /** Why the last fetch failed, redacted; null when it did not. */
+    lastFetchFailure(): string | null;
+    /**
+     * `git fetch --prune origin`, once for every workspace: throttled, and
+     * joined while in flight. Answers whether the remote-tracking refs are
+     * provably fresh. Never throws.
+     */
+    fetch(opts: FetchOptions): Promise<boolean>;
+    /** Forget what this process knows of the repository (it was set aside). */
+    forget(): void;
+    /** Add the worktree of `branch` at `checkoutDir`, copying no history. */
+    addWorktree(branch: string, checkoutDir: string, opts?: AddWorktreeOptions): Promise<void>;
+    /** Remove and prune the worktree at `checkoutDir`, with its branch's local ref; nothing else. */
+    removeWorktree(checkoutDir: string, branch: string): Promise<void>;
+    /** Prune worktrees whose folders were deleted by hand, and drop their branches' local refs. */
+    forgetWorktrees(branches: readonly string[]): Promise<void>;
+    /** `git worktree prune`. */
+    prune(): Promise<void>;
+    /** The folders of the repository's worktrees, as git lists them. */
+    listWorktrees(): Promise<string[]>;
+    /** Import the tip of `branch` from the full clone at `cloneDir` (unpushed commits included); answers the tip. */
+    importBranch(cloneDir: string, branch: string): Promise<string>;
+    /**
+     * Import the full clone's stash entries and its other local refs (not its own
+     * branch, not remote-tracking ones) under `refs/kb-converted/<workspaceId>/`,
+     * leaving the clone as it was; answers the refs written.
+     */
+    importLocalRefs(cloneDir: string, branch: string, workspaceId: string): Promise<string[]>;
+    /** The address the repository fetches from, or null when it cannot be read. */
+    originUrl(): Promise<string | null>;
+    /** Re-link a repository and its worktrees that were moved together; answers the worktrees that could not be. */
+    relinkMovedCopy(movedRepository: string, movedWorktrees: readonly string[]): Promise<string[]>;
+    /** Point the repository at `url`, forgetting the old address's fetch freshness. */
+    setOriginUrl(url: string): Promise<void>;
+}
+//# sourceMappingURL=kb-repository.contract.d.ts.map

package/dist/modules/workspace/kb-repository.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-repository.contract.d.ts","sourceRoot":"","sources":["../../../src/modules/workspace/kb-repository.contract.ts"],"names":[],"mappings":"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"}

package/dist/modules/workspace/kb-repository.contract.js

@@ -0,0 +1,19 @@
+/**
+ * The knowledge base's one repository, every branch workspace a worktree of
+ * it — the contract its consumers (the workspace service, the KB startup
+ * phase, the set-aside of a moved repository, the git layer) depend on.
+ * `KbRepository` (`kb-repository.ts`) is the implementation, a bare
+ * repository driven by the git CLI; the composition root makes ONE and
+ * injects it everywhere, so that one fetch serves every workspace and the
+ * repository's administration — its creation, the writes to its one config
+ * file, its worktree list, a set-aside — is serialized in one place.
+ *
+ * Nothing else is serialized by the application: git was built for many
+ * worktrees of one repository, and protects the refs, `packed-refs` and the
+ * object store with its own locks. The worktree list (`worktrees/`) it does
+ * not lock, which is why adding, removing and pruning worktrees are
+ * administration here. Two worktrees run side by side, as two developers'
+ * worktrees of one repository do.
+ */
+export {};
+//# sourceMappingURL=kb-repository.contract.js.map

package/dist/modules/workspace/kb-repository.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-repository.contract.js","sourceRoot":"","sources":["../../../src/modules/workspace/kb-repository.contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}