@tiqian/precompute 0.0.0-stage → 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/load.js ADDED
@@ -0,0 +1,38 @@
1
+ // Loads the platform-specific build of the addon on the current system.
2
+ // The four platforms are the first-version targets of ADR 0050. The debug
3
+ // path serves local builds placed by `neon dist` (`bun run debug:native`);
4
+ // when it is absent the proxy falls back to the installed platform package.
5
+ import { readFileSync } from "node:fs";
6
+ import { createRequire } from "node:module";
7
+ import { currentPlatform, proxy } from "@neon-rs/load";
8
+ import { loadLinuxAddon } from "./nixos.js";
9
+ // `proxy` needs synchronous CommonJS requires for the platform packages and
10
+ // the local `.node` file, so this ESM module carries its own require.
11
+ const require = createRequire(import.meta.url);
12
+ // The platform packages resolve under the scope of this package's own name,
13
+ // so a snapshot publication under a different scope loads without a source
14
+ // patch (GitHub Packages requires the npm scope to equal the repository
15
+ // owner; the snapshot workflow swaps the manifests temporarily).
16
+ const manifestUrl = new URL("../package.json", import.meta.url);
17
+ const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
18
+ const ownName = typeof manifest.name === "string" ? manifest.name : "";
19
+ const slash = ownName.indexOf("/");
20
+ const ownScope = ownName.startsWith("@") && slash > 0 ? ownName.slice(0, slash) : null;
21
+ const platformPackage = (platform) => {
22
+ if (ownScope === null) {
23
+ throw new Error("PlatformPackageScopeMissing");
24
+ }
25
+ return `${ownScope}/precompute-${platform}`;
26
+ };
27
+ export const addon = proxy({
28
+ platforms: {
29
+ "win32-x64-msvc": () => require(platformPackage("win32-x64-msvc")),
30
+ "darwin-arm64": () => require(platformPackage("darwin-arm64")),
31
+ // The linux loaders pass through the NixOS fallback of `nixos.ts`: on a
32
+ // failed dlopen they repair the runpath instead of surfacing a bare
33
+ // "cannot open shared object file".
34
+ "linux-x64-gnu": () => loadLinuxAddon(require, platformPackage("linux-x64-gnu")),
35
+ "linux-arm64-gnu": () => loadLinuxAddon(require, platformPackage("linux-arm64-gnu")),
36
+ },
37
+ debug: () => require(`../platforms/${currentPlatform()}/index.node`),
38
+ });
package/lib/nixos.d.ts ADDED
@@ -0,0 +1,26 @@
1
+ /** The `os-release(5)` ID value written by NixOS activation. */
2
+ export declare function isNixOsReleaseText(text: string): boolean;
3
+ /** True when the running system is NixOS proper, not nix on another distro. */
4
+ export declare function isNixOs(): boolean;
5
+ /** The DT_NEEDED library names of an ELF64 little-endian image, or null. */
6
+ export declare function readElfNeeded(bytes: Buffer): string[] | null;
7
+ /** Basenames of every mapped shared object in a `/proc/self/maps` dump. */
8
+ export declare function parseLoadedSonames(mapsText: string): Set<string>;
9
+ /** Directories of the nix store libraries the current process mapped. */
10
+ export declare function parseMapsLibraryDirs(mapsText: string): string[];
11
+ /** The soname-to-path entries of `ldconfig -p` output. */
12
+ export declare function parseLdconfigEntries(text: string): Map<string, string>;
13
+ /** Library directories of the fixed NixOS profiles, most specific first. */
14
+ export declare function profileLibraryDirs(home: string): string[];
15
+ /**
16
+ * Extra library directories from the environment, for nix-shell runspaces
17
+ * and other store prefixes the fixed profiles do not cover.
18
+ */
19
+ export declare function environmentLibraryDirs(): string[];
20
+ /**
21
+ * Loads a linux platform package and, on NixOS, retries a failed load with a
22
+ * repaired runpath. `requireFn` is the CommonJS require of `load.ts`; the
23
+ * addon is cached under `~/.cache/tiqian-precompute/nix-rpath` keyed by the
24
+ * source file digest, so the patchelf run happens once per addon build.
25
+ */
26
+ export declare function loadLinuxAddon(requireFn: NodeJS.Require, spec: string): ReturnType<NodeJS.Require>;
package/lib/nixos.js ADDED
@@ -0,0 +1,315 @@
1
+ // NixOS fallback for loading the linux addon. The platform binaries are
2
+ // built by CI against a plain glibc and carry no runpath, so every
3
+ // DT_NEEDED entry must resolve through the running process: either the
4
+ // runtime already loaded the same SONAME, or the dynamic loader finds it in
5
+ // its search path. Plain Linux distributions provide the C++ runtime in a
6
+ // default directory; NixOS has none, and the libraries live in store paths
7
+ // that only the profiles know about. When the plain load fails on NixOS
8
+ // this module names the unresolved libraries and, when patchelf is
9
+ // available, loads a cached copy of the addon with a repaired runpath.
10
+ //
11
+ // Two mechanisms were measured and rejected on 2026-08-22 (ADR 0050):
12
+ // setting LD_LIBRARY_PATH in JS before require has no effect, because glibc
13
+ // parses the variable once at process startup; and preloading the missing
14
+ // library by absolute path needs dlopen of a plain shared object, which
15
+ // Node refuses ("Module did not self-register") and undoes.
16
+ import { spawnSync } from "node:child_process";
17
+ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
18
+ import { dirname, join } from "node:path";
19
+ import { homedir } from "node:os";
20
+ import { createHash } from "node:crypto";
21
+ /** The `os-release(5)` ID value written by NixOS activation. */
22
+ export function isNixOsReleaseText(text) {
23
+ return /^ID=["']?nixos["']?$/m.test(text);
24
+ }
25
+ /** True when the running system is NixOS proper, not nix on another distro. */
26
+ export function isNixOs() {
27
+ try {
28
+ return isNixOsReleaseText(readFileSync("/etc/os-release", "utf8"));
29
+ }
30
+ catch {
31
+ return false;
32
+ }
33
+ }
34
+ // ---------------------------------------------------------------------------
35
+ // ELF64 reading: only the DT_NEEDED names are needed here, and reading them
36
+ // without spawning a tool keeps the diagnosis working on minimal profiles.
37
+ // The parser accepts exactly what our addons are: 64-bit little-endian
38
+ // ELF shared objects. Anything else returns null and the caller rethrows.
39
+ const PT_LOAD = 1;
40
+ const PT_DYNAMIC = 2;
41
+ const DT_NULL = 0;
42
+ const DT_NEEDED = 1;
43
+ const DT_STRTAB = 5;
44
+ const DT_STRSZ = 10;
45
+ /** The DT_NEEDED library names of an ELF64 little-endian image, or null. */
46
+ export function readElfNeeded(bytes) {
47
+ if (bytes.length < 64 || bytes[0] !== 0x7f || bytes[1] !== 0x45 || bytes[2] !== 0x4c || bytes[3] !== 0x46) {
48
+ return null;
49
+ }
50
+ if (bytes[4] !== 2 || bytes[5] !== 1) {
51
+ return null;
52
+ }
53
+ const phoff = Number(bytes.readBigUInt64LE(0x20));
54
+ const phentsize = bytes.readUInt16LE(0x36);
55
+ const phnum = bytes.readUInt16LE(0x38);
56
+ let dynamicOffset = -1;
57
+ const loads = [];
58
+ for (let index = 0; index < phnum; index += 1) {
59
+ const header = phoff + index * phentsize;
60
+ if (header + 56 > bytes.length) {
61
+ return null;
62
+ }
63
+ const type = bytes.readUInt32LE(header);
64
+ if (type === PT_DYNAMIC) {
65
+ dynamicOffset = Number(bytes.readBigUInt64LE(header + 8));
66
+ }
67
+ else if (type === PT_LOAD) {
68
+ loads.push({
69
+ offset: Number(bytes.readBigUInt64LE(header + 8)),
70
+ vaddr: Number(bytes.readBigUInt64LE(header + 16)),
71
+ filesz: Number(bytes.readBigUInt64LE(header + 32)),
72
+ });
73
+ }
74
+ }
75
+ if (dynamicOffset < 0 || loads.length === 0) {
76
+ return null;
77
+ }
78
+ const vaddrToOffset = (vaddr) => {
79
+ for (const load of loads) {
80
+ if (vaddr >= load.vaddr && vaddr < load.vaddr + load.filesz) {
81
+ return vaddr - load.vaddr + load.offset;
82
+ }
83
+ }
84
+ return null;
85
+ };
86
+ let strtabOffset = -1;
87
+ let strsz = 0;
88
+ const neededOffsets = [];
89
+ for (let cursor = dynamicOffset; cursor + 16 <= bytes.length; cursor += 16) {
90
+ const tag = bytes.readBigInt64LE(cursor);
91
+ const value = Number(bytes.readBigUInt64LE(cursor + 8));
92
+ if (tag === BigInt(DT_NULL)) {
93
+ break;
94
+ }
95
+ if (tag === BigInt(DT_STRTAB)) {
96
+ const offset = vaddrToOffset(value);
97
+ if (offset === null) {
98
+ return null;
99
+ }
100
+ strtabOffset = offset;
101
+ }
102
+ else if (tag === BigInt(DT_STRSZ)) {
103
+ strsz = value;
104
+ }
105
+ else if (tag === BigInt(DT_NEEDED)) {
106
+ neededOffsets.push(value);
107
+ }
108
+ }
109
+ if (strtabOffset < 0 || strtabOffset + strsz > bytes.length) {
110
+ return null;
111
+ }
112
+ const names = [];
113
+ for (const offset of neededOffsets) {
114
+ const start = strtabOffset + offset;
115
+ if (start < strtabOffset || start >= strtabOffset + strsz) {
116
+ return null;
117
+ }
118
+ const end = bytes.indexOf(0, start);
119
+ if (end < 0 || end >= strtabOffset + strsz) {
120
+ return null;
121
+ }
122
+ names.push(bytes.toString("utf8", start, end));
123
+ }
124
+ return names;
125
+ }
126
+ // ---------------------------------------------------------------------------
127
+ // Library search. The dynamic loader consults, in order: the loaded images,
128
+ // the addon runpath, LD_LIBRARY_PATH (fixed at process startup), the
129
+ // ldconfig cache, and the default directories. NixOS has no default
130
+ // directories, so the last two sources cover only the system profile. The
131
+ // extra sources below are the ones glibc never looks at: the store
132
+ // directories of libraries the running process already mapped, and the
133
+ // user profile library directories.
134
+ // The pathname is the sixth column and may carry a trailing " (deleted)"
135
+ // marker with a space inside it, so the field cannot be split by whitespace.
136
+ const mapsPath = (line) => {
137
+ const match = line.match(/^\s*(?:\S+\s+){5}(\/\S.*)$/u);
138
+ if (match === null) {
139
+ return null;
140
+ }
141
+ return match[1].replace(/\s+\(deleted\)$/u, "");
142
+ };
143
+ /** Basenames of every mapped shared object in a `/proc/self/maps` dump. */
144
+ export function parseLoadedSonames(mapsText) {
145
+ const names = new Set();
146
+ for (const line of mapsText.split("\n")) {
147
+ const pathField = mapsPath(line);
148
+ if (pathField === null || !pathField.includes(".so")) {
149
+ continue;
150
+ }
151
+ names.add(pathField.slice(pathField.lastIndexOf("/") + 1));
152
+ }
153
+ return names;
154
+ }
155
+ /** Directories of the nix store libraries the current process mapped. */
156
+ export function parseMapsLibraryDirs(mapsText) {
157
+ const dirs = new Set();
158
+ for (const line of mapsText.split("\n")) {
159
+ const pathField = mapsPath(line);
160
+ if (pathField !== null && pathField.startsWith("/nix/store/") && pathField.includes(".so")) {
161
+ dirs.add(dirname(pathField));
162
+ }
163
+ }
164
+ return [...dirs];
165
+ }
166
+ /** The soname-to-path entries of `ldconfig -p` output. */
167
+ export function parseLdconfigEntries(text) {
168
+ const entries = new Map();
169
+ for (const line of text.split("\n")) {
170
+ const match = line.match(/^\s*(\S*\.so\S*)\s+\([^)]*\)\s+=>\s+(\S+)/u);
171
+ if (match) {
172
+ entries.set(match[1], match[2]);
173
+ }
174
+ }
175
+ return entries;
176
+ }
177
+ /** Library directories of the fixed NixOS profiles, most specific first. */
178
+ export function profileLibraryDirs(home) {
179
+ // Forward slashes on purpose: the directories exist on NixOS only, and the
180
+ // literal spelling keeps the output identical on every platform the test
181
+ // suite runs on.
182
+ return [
183
+ "/run/current-system/sw/lib",
184
+ "/nix/var/nix/profiles/default/lib",
185
+ `${home}/.local/state/nix/profiles/profile/lib`,
186
+ `${home}/.nix-profile/lib`,
187
+ ];
188
+ }
189
+ /**
190
+ * Extra library directories from the environment, for nix-shell runspaces
191
+ * and other store prefixes the fixed profiles do not cover.
192
+ */
193
+ export function environmentLibraryDirs() {
194
+ const value = process.env.TIQIAN_PRECOMPUTE_NIX_LIB_DIRS ?? "";
195
+ return value.split(":").filter((dir) => dir !== "");
196
+ }
197
+ const planRepair = (addonPath, home) => {
198
+ const needed = readElfNeeded(readFileSync(addonPath));
199
+ if (needed === null) {
200
+ return null;
201
+ }
202
+ const readMapsText = () => {
203
+ try {
204
+ return readFileSync("/proc/self/maps", "utf8");
205
+ }
206
+ catch {
207
+ return "";
208
+ }
209
+ };
210
+ const mapsText = readMapsText();
211
+ const loaded = parseLoadedSonames(mapsText);
212
+ const ldconfig = spawnSync("ldconfig", ["-p"], { encoding: "utf8" });
213
+ const cacheEntries = ldconfig.status === 0 ? parseLdconfigEntries(ldconfig.stdout) : new Map();
214
+ // ldconfig entries contribute candidate directories. A nix-built runtime
215
+ // links the store glibc, whose loader reads the cache at
216
+ // <glibc-store-path>/etc/ld.so.cache; on NixOS that file does not exist, so
217
+ // the host cache reported by `ldconfig -p` takes no part in resolution
218
+ // (ADR 0050). This function runs only after a real load failure, so only a
219
+ // SONAME the process already loaded counts as resolved.
220
+ const ldconfigDirs = [...new Set([...cacheEntries.values()].map(dirname))];
221
+ const candidateDirs = [
222
+ ...environmentLibraryDirs(),
223
+ ...parseMapsLibraryDirs(mapsText),
224
+ ...profileLibraryDirs(home),
225
+ ...ldconfigDirs,
226
+ ];
227
+ const unresolved = [];
228
+ const runpathDirs = new Set();
229
+ for (const library of needed) {
230
+ if (loaded.has(library)) {
231
+ continue;
232
+ }
233
+ const directory = candidateDirs.find((dir) => existsSync(join(dir, library)));
234
+ if (directory === undefined) {
235
+ unresolved.push(library);
236
+ continue;
237
+ }
238
+ runpathDirs.add(directory);
239
+ }
240
+ if (unresolved.length === 0 && runpathDirs.size === 0) {
241
+ // Every dependency already resolves; the failure has another cause and
242
+ // the original error says more about it than a runpath repair would.
243
+ return null;
244
+ }
245
+ return { unresolved, runpathDirs: [...runpathDirs] };
246
+ };
247
+ const runPatchelf = (arguments_) => {
248
+ for (const candidate of ["patchelf", "/run/current-system/sw/bin/patchelf"]) {
249
+ const result = spawnSync(candidate, arguments_, { encoding: "utf8" });
250
+ if (result.error === undefined) {
251
+ return { status: result.status, error: undefined };
252
+ }
253
+ }
254
+ return { status: null, error: new Error("patchelf not found") };
255
+ };
256
+ const cacheDirectory = (home) => join(home, ".cache", "tiqian-precompute", "nix-rpath");
257
+ /**
258
+ * Loads a linux platform package and, on NixOS, retries a failed load with a
259
+ * repaired runpath. `requireFn` is the CommonJS require of `load.ts`; the
260
+ * addon is cached under `~/.cache/tiqian-precompute/nix-rpath` keyed by the
261
+ * source file digest, so the patchelf run happens once per addon build.
262
+ */
263
+ export function loadLinuxAddon(requireFn, spec) {
264
+ try {
265
+ return requireFn(spec);
266
+ }
267
+ catch (failure) {
268
+ if (!isNixOs()) {
269
+ throw failure;
270
+ }
271
+ let addonPath;
272
+ try {
273
+ addonPath = requireFn.resolve(spec);
274
+ }
275
+ catch {
276
+ throw failure;
277
+ }
278
+ const home = homedir();
279
+ const source = readFileSync(addonPath);
280
+ const digest = createHash("sha256").update(source).digest("hex");
281
+ const repaired = join(cacheDirectory(home), `${digest}.node`);
282
+ // A previous run already repaired this exact addon build; the diagnosis
283
+ // below stays skipped so a repeat load works even when the environment
284
+ // that produced the repair is gone.
285
+ if (!existsSync(repaired)) {
286
+ const plan = planRepair(addonPath, home);
287
+ if (plan === null) {
288
+ throw failure;
289
+ }
290
+ if (plan.unresolved.length > 0) {
291
+ throw new Error(`TiqianPrecomputeNixLibraryMissing: the addon ${addonPath} needs ` +
292
+ `${plan.unresolved.join(", ")}; no directory among the loaded images, ` +
293
+ `the ldconfig cache, and the profile library directories provides it. ` +
294
+ `Install the package that ships the library, or start the process with ` +
295
+ `LD_LIBRARY_PATH pointing at its directory.`, { cause: failure });
296
+ }
297
+ const staging = `${repaired}.tmp-${process.pid}`;
298
+ const runpath = plan.runpathDirs.join(":");
299
+ mkdirSync(dirname(repaired), { recursive: true });
300
+ writeFileSync(staging, source);
301
+ const applied = runPatchelf(["--set-rpath", runpath, staging]);
302
+ if (applied.error !== undefined) {
303
+ throw new Error(`TiqianPrecomputeNixPatchelfMissing: the addon needs the runpath ` +
304
+ `${runpath}, and patchelf was not found. Install it ` +
305
+ `(nix profile install nixpkgs#patchelf) and retry.`, { cause: failure });
306
+ }
307
+ if (applied.status !== 0) {
308
+ throw new Error(`TiqianPrecomputeNixPatchelfFailed: patchelf --set-rpath ${runpath} ` +
309
+ `failed with status ${String(applied.status)}.`, { cause: failure });
310
+ }
311
+ renameSync(staging, repaired);
312
+ }
313
+ return requireFn(repaired);
314
+ }
315
+ }
@@ -0,0 +1,127 @@
1
+ import type { FontContractInput, PreparedEntry, SnapshotParagraphInput } from "./precompute.js";
2
+ import type { CacheBridge } from "./cache.js";
3
+ /**
4
+ * One host-owned address-to-bytes store. Addresses and record bytes are
5
+ * opaque: the SDK derives an address from the precomputer context and the
6
+ * content hash, and the value is the bridge's serialized record form. Reads
7
+ * return only the addresses the store actually holds.
8
+ */
9
+ export interface PersistentCacheStore {
10
+ read(addresses: readonly string[]): Map<string, Uint8Array> | Promise<Map<string, Uint8Array>>;
11
+ write(entries: readonly (readonly [string, Uint8Array])[]): void | Promise<void>;
12
+ /**
13
+ * Records article-index rows, replacing the rows of the same article
14
+ * keys (ADR 0052 Article layer). One call must carry an article's full
15
+ * hash set for the context: the replacement drops whatever the article
16
+ * recorded before.
17
+ */
18
+ recordArticles?(context: string, articles: readonly ArticleIndexRecord[]): void | Promise<void>;
19
+ /** Reads every article row of one context. */
20
+ readArticles?(context: string): ArticleIndexRecord[] | Promise<ArticleIndexRecord[]>;
21
+ /** Deletes article rows by key; returns the row count removed. */
22
+ deleteArticles?(context: string, articleKeys: readonly string[]): number | Promise<number>;
23
+ /**
24
+ * Drops entries of one context that are not in the keep list. Article
25
+ * rows are index data, not entries, so a prune leaves them alone.
26
+ */
27
+ prune?(context: string, keep: readonly string[]): number | Promise<number>;
28
+ /**
29
+ * Bucket-scoped eviction (ADR 0052 BucketIntersectionEviction): the host
30
+ * hands one bucket id plus that bucket's current content hashes, and the
31
+ * store deletes the entries the bucket's article rows attribute but the
32
+ * list omits, protecting entries other buckets' rows still reference.
33
+ * The bucket's hash rows are trimmed to the list and emptied article rows
34
+ * are dropped. Returns the entry count removed. Sweeping every bucket
35
+ * converges on the whole-context union keep set, one bounded list per call.
36
+ */
37
+ pruneBucket?(context: string, bucket: string, keep: readonly string[]): number | Promise<number>;
38
+ }
39
+ /**
40
+ * One article-index row (ADR 0052 Article layer): the unit of invalidation
41
+ * and whole-article load. `bucket` is a host-chosen group tag; content
42
+ * hashes are the hex form the cache addresses derive from.
43
+ */
44
+ export interface ArticleIndexRecord {
45
+ readonly articleKey: string;
46
+ readonly bucket: string;
47
+ readonly contentHashes: readonly string[];
48
+ }
49
+ /** The persistence front of one precomputer. */
50
+ export interface PersistentCache {
51
+ /** The context fingerprint as hex; namespaces this cache's addresses. */
52
+ context(): string;
53
+ /** Pushes stored records into the memory tier without rendering. */
54
+ warmSnapshots(inputs: readonly SnapshotParagraphInput[]): Promise<number>;
55
+ /** The contract form of {@link PersistentCache.warmSnapshots}. */
56
+ warmContracts(inputs: readonly FontContractInput[]): Promise<number>;
57
+ /**
58
+ * Hash-first render: stored entries hydrate the memory tier and resolve
59
+ * from the local copies after digest verification, so their content never
60
+ * crosses the bridge; the rest carry content once and compute. Entries
61
+ * match the JSON lanes byte for byte.
62
+ */
63
+ renderSnapshots(inputs: readonly SnapshotParagraphInput[]): Promise<PreparedEntry[]>;
64
+ /** The contract form of {@link PersistentCache.renderSnapshots}. */
65
+ renderContracts(inputs: readonly FontContractInput[]): Promise<PreparedEntry[]>;
66
+ /**
67
+ * The background egress of {@link PersistentCache.renderSnapshots}: queues
68
+ * every item at the back of the render pool and returns once queued, so a
69
+ * host can warm content ahead of the waiting lanes. Failures surface when
70
+ * the same content arrives through a waiting lane.
71
+ */
72
+ prefillSnapshots(inputs: readonly SnapshotParagraphInput[]): number;
73
+ /** The contract form of {@link PersistentCache.prefillSnapshots}. */
74
+ prefillContracts(inputs: readonly FontContractInput[]): number;
75
+ /**
76
+ * Records one article's full content-hash set for this cache's context
77
+ * (ADR 0052 Article layer). Both input lists together must carry
78
+ * everything this lane rendered for the article: the row replaces the
79
+ * article's previously recorded hashes. Returns the hash list it recorded,
80
+ * so a host assembles bucket prune keep lists without re-deriving them.
81
+ */
82
+ recordArticle(articleKey: string, bucket: string, inputs: {
83
+ snapshots?: readonly SnapshotParagraphInput[];
84
+ contracts?: readonly FontContractInput[];
85
+ }): Promise<readonly string[]>;
86
+ /** The stored hash set of one article, or null when the article is unrecorded. */
87
+ articleHashes(articleKey: string): Promise<readonly string[] | null>;
88
+ /**
89
+ * Whole-article load: reads the article's stored records through the
90
+ * index and pushes them into the memory tier. Each copy verifies
91
+ * against its address hash and digest before warming, so a corrupt row
92
+ * is a skip, not poison. Returns the record count warmed.
93
+ */
94
+ warmArticle(articleKey: string): Promise<number>;
95
+ /**
96
+ * Bucket-intersection eviction: keeps the union of every recorded
97
+ * article's hashes and drops this context's other entries. Articles in
98
+ * `dropArticles` lose their index rows before the union, so entries only
99
+ * those articles referenced go with them. Returns the entry count
100
+ * removed.
101
+ */
102
+ pruneUnreferencedEntries(dropArticles?: readonly string[]): Promise<number>;
103
+ /**
104
+ * Bucket-scoped eviction (ADR 0052 BucketIntersectionEviction): `keep`
105
+ * carries every content hash the bucket should retain (hex, the form
106
+ * {@link PersistentCache.recordArticle} returns). The store deletes the
107
+ * entries the bucket's article rows attribute but the list omits and no
108
+ * other bucket's row references, trims the bucket's hash rows to the
109
+ * list and drops emptied article rows. One call carries one bucket's
110
+ * list; sweeping every bucket replaces the whole-context union prune for
111
+ * hosts that group articles into buckets. Returns the entry count
112
+ * removed.
113
+ */
114
+ pruneBucket(bucket: string, keep: readonly string[]): Promise<number>;
115
+ /** Persists the buffered writes; returns the record count written. */
116
+ flush(): Promise<number>;
117
+ }
118
+ /**
119
+ * The lane host of {@link createPersistentCache}: any precomputer-like
120
+ * object with a cache bridge. The SDK binds to the bridge alone, so hosts
121
+ * can drive the Article index over a store without an engine attached.
122
+ */
123
+ export type CacheLaneHost = {
124
+ readonly cache: CacheBridge;
125
+ };
126
+ /** Binds one lane host to one host store. */
127
+ export declare function createPersistentCache(host: CacheLaneHost, store: PersistentCacheStore): PersistentCache;