@mnmal-ai/substrate 0.0.0-stage → 1.0.0-alpha.0

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.
Files changed (46) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +119 -2
  3. package/dist/agent-token-BIboWOU0.js +200 -0
  4. package/dist/client.d.ts +782 -0
  5. package/dist/client.js +7 -0
  6. package/dist/cluster-worker.js +35 -0
  7. package/dist/content-type-C7T28xNb.js +25 -0
  8. package/dist/dataset-BXkus75W.js +1527 -0
  9. package/dist/env-utils-B7SGmoeJ.js +21 -0
  10. package/dist/errors-D4vKuwz8.d.ts +130 -0
  11. package/dist/fake-DUVtKVSE.js +36 -0
  12. package/dist/index-D7mSOFlM.d.ts +69 -0
  13. package/dist/pack.d.ts +192 -0
  14. package/dist/pack.js +5 -0
  15. package/dist/plugin-j1jt1l3n.js +3844 -0
  16. package/dist/plugin-t2g2wX0b.d.ts +1568 -0
  17. package/dist/proposals-bootstrap.js +37 -0
  18. package/dist/proposals.config.schema.json +20 -0
  19. package/dist/proposals.d.ts +118 -0
  20. package/dist/proposals.default-config.json +4 -0
  21. package/dist/proposals.js +4 -0
  22. package/dist/recall-bootstrap.js +451 -0
  23. package/dist/recall.config.schema.json +232 -0
  24. package/dist/recall.d.ts +1981 -0
  25. package/dist/recall.default-config.json +4 -0
  26. package/dist/recall.js +5 -0
  27. package/dist/repl-C52wyfMs.js +2213 -0
  28. package/dist/row-ByLFE2Wx.d.ts +719 -0
  29. package/dist/row-DK7lPZVe.js +732 -0
  30. package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
  31. package/dist/schema-g4FQLr0V.d.ts +433 -0
  32. package/dist/sdk.d.ts +694 -0
  33. package/dist/sdk.js +112 -0
  34. package/dist/src-C4DzaIQZ.js +837 -0
  35. package/dist/src-CrEgiMJQ.js +1015 -0
  36. package/dist/src-CzxvmhFn.js +2327 -0
  37. package/dist/src-D88LvCX8.js +1797 -0
  38. package/dist/src-D91yij6C.js +13523 -0
  39. package/dist/src-DuopV8u7.js +2408 -0
  40. package/dist/substrate-admin.js +808 -0
  41. package/dist/substrate.js +5477 -0
  42. package/dist/testing.d.ts +1240 -0
  43. package/dist/testing.js +702 -0
  44. package/dist/types-8c0gtnd2.d.ts +35 -0
  45. package/dist/ws-C72iVS5T.d.ts +143 -0
  46. package/package.json +117 -3
@@ -0,0 +1,3844 @@
1
+ import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
+ import { L as applyObligations, Q as buildContext, et as jsonResponse, wt as ResolverFrameError } from "./src-D91yij6C.js";
3
+ import { Worker } from "node:worker_threads";
4
+
5
+ //#region ../../plugins/substrate-recall/src/candidate-selection.ts
6
+ /**
7
+ * Ceiling on one selection, with headroom under `WasmClusterer`'s
8
+ * `WASM_MAX_ROWS` refusal limit.
9
+ */
10
+ const SELECT_CANDIDATES_MAX_LIMIT = 2e4;
11
+ function bad$3(message) {
12
+ throw Object.assign(new Error(message), { code: "bad_request" });
13
+ }
14
+ function nonEmptyString$2(value) {
15
+ return typeof value === "string" && value.length > 0;
16
+ }
17
+ function validateSelector(value) {
18
+ if (value === null || typeof value !== "object") bad$3("a selection filter is required — crystallise refuses to cluster everything by default");
19
+ const raw = value;
20
+ if (!Array.isArray(raw.scopes)) bad$3("\"select.scopes\" must be an array of { namespace, type }");
21
+ if (raw.scopes.length === 0) bad$3("\"select.scopes\" must name at least one scope — there is no cluster-everything default");
22
+ const parsedScopes = raw.scopes.map((entry, i) => {
23
+ const s = entry;
24
+ if (s === null || typeof s !== "object") bad$3(`"select.scopes[${i}]" must be an object`);
25
+ if (!nonEmptyString$2(s.namespace)) bad$3(`"select.scopes[${i}].namespace" must be a non-empty string`);
26
+ if (!nonEmptyString$2(s.type)) bad$3(`"select.scopes[${i}].type" must be a non-empty string`);
27
+ return {
28
+ namespace: s.namespace,
29
+ type: s.type
30
+ };
31
+ });
32
+ const seenScopes = /* @__PURE__ */ new Set();
33
+ const scopes = [];
34
+ for (const s of parsedScopes) {
35
+ const k = `${s.namespace}/${s.type}`;
36
+ if (seenScopes.has(k)) continue;
37
+ seenScopes.add(k);
38
+ scopes.push(s);
39
+ }
40
+ let excludeTextPrefixes = [];
41
+ if (raw.excludeTextPrefixes !== void 0) {
42
+ if (!Array.isArray(raw.excludeTextPrefixes)) bad$3("\"select.excludeTextPrefixes\" must be an array of { field, prefix }");
43
+ excludeTextPrefixes = raw.excludeTextPrefixes.map((entry, i) => {
44
+ const e = entry;
45
+ if (e === null || typeof e !== "object") bad$3(`"select.excludeTextPrefixes[${i}]" must be an object`);
46
+ if (!nonEmptyString$2(e.field)) bad$3(`"select.excludeTextPrefixes[${i}].field" must be a non-empty string`);
47
+ if (!nonEmptyString$2(e.prefix)) bad$3(`"select.excludeTextPrefixes[${i}].prefix" must be a non-empty string`);
48
+ return {
49
+ field: e.field,
50
+ prefix: e.prefix
51
+ };
52
+ });
53
+ }
54
+ let limit = SELECT_CANDIDATES_MAX_LIMIT;
55
+ if (raw.limit !== void 0) {
56
+ if (typeof raw.limit !== "number" || !Number.isInteger(raw.limit) || raw.limit < 1) bad$3("\"select.limit\" must be a positive integer");
57
+ limit = Math.min(raw.limit, SELECT_CANDIDATES_MAX_LIMIT);
58
+ }
59
+ return {
60
+ scopes,
61
+ excludeTextPrefixes,
62
+ limit
63
+ };
64
+ }
65
+
66
+ //#endregion
67
+ //#region ../../plugins/substrate-recall/src/cluster-store.ts
68
+ /** Canonical key for a member ref — the form `claimedMembers` returns. */
69
+ function memberKey(ref) {
70
+ return `${ref.namespace}/${ref.type}/${ref.id}`;
71
+ }
72
+
73
+ //#endregion
74
+ //#region ../../plugins/substrate-recall/src/clusterer-version.ts
75
+ /**
76
+ * Which clusterer produced a clustering. Recorded in every cluster's
77
+ * provenance, because two backends produce different assignments on
78
+ * identical input — and, decisively, so does the same backend on
79
+ * differently-rounded input.
80
+ *
81
+ * The version is a hand-maintained constant rather than a read of the
82
+ * dependency's package.json, because `@mnmal-ai/holomap-clusterer` exports
83
+ * only `"."` — there is no `./package.json` subpath to require. Drift is
84
+ * prevented by `test/clusterer-version.test.ts`, which reads the installed
85
+ * package directly and fails if this constant disagrees.
86
+ */
87
+ const CLUSTERER_BACKEND = "wasm";
88
+ const CLUSTERER_BACKEND_VERSION = "0.2.1";
89
+
90
+ //#endregion
91
+ //#region ../../plugins/substrate-recall/src/cosine.ts
92
+ /**
93
+ * Cosine similarity over Float32 vectors. Shared by the in-process knn search
94
+ * (`InMemoryEmbeddingsStore`) and recall's expansion re-scoring so the two
95
+ * paths can't drift.
96
+ */
97
+ function cosineSimilarity(a, b) {
98
+ const len = Math.min(a.length, b.length);
99
+ let dot = 0;
100
+ let na = 0;
101
+ let nb = 0;
102
+ for (let i = 0; i < len; i++) {
103
+ const av = a[i] ?? 0;
104
+ const bv = b[i] ?? 0;
105
+ dot += av * bv;
106
+ na += av * av;
107
+ nb += bv * bv;
108
+ }
109
+ if (na === 0 || nb === 0) return 0;
110
+ return dot / (Math.sqrt(na) * Math.sqrt(nb));
111
+ }
112
+
113
+ //#endregion
114
+ //#region ../../plugins/substrate-recall/src/l2normalize.ts
115
+ /**
116
+ * L2 normalisation for the crystallise input path.
117
+ *
118
+ * A byte-for-byte copy of `l2normalize` in `@mnmal-ai/holomap-clusterer`'s
119
+ * `npm/test/fixture.ts`, because the corpus regression gate measures against
120
+ * figures that function produced; the clustering pipeline is sensitive enough
121
+ * that an equivalent-in-the-limit function is not the same function.
122
+ *
123
+ * `sum` accumulates in f64 over the f32 values and only re-rounds on store.
124
+ * Do NOT "simplify" this to operate on the pre-cast values: it looks like a
125
+ * cleanup and changes the results.
126
+ */
127
+ function l2normalize(vectors) {
128
+ return vectors.map((v) => {
129
+ let sum = 0;
130
+ for (const x of v) sum += x * x;
131
+ const norm = Math.sqrt(sum);
132
+ if (norm === 0) return new Float32Array(v);
133
+ const out = new Float32Array(v.length);
134
+ for (let i = 0; i < v.length; i++) out[i] = v[i] / norm;
135
+ return out;
136
+ });
137
+ }
138
+
139
+ //#endregion
140
+ //#region ../../plugins/substrate-recall/src/labelling.ts
141
+ /**
142
+ * The indexed, retrieval-tuned handle fields. Long-form fields (`body`,
143
+ * `summary`, `notes`, `rationale`) are deliberately excluded — they are
144
+ * unindexed by convention, and their length would swamp document frequency.
145
+ */
146
+ const HANDLE_FIELDS = [
147
+ "name",
148
+ "title",
149
+ "topic",
150
+ "synopsis",
151
+ "description"
152
+ ];
153
+ const STOPWORDS = /* @__PURE__ */ new Set([
154
+ "the",
155
+ "and",
156
+ "for",
157
+ "with",
158
+ "that",
159
+ "this",
160
+ "from",
161
+ "into",
162
+ "not",
163
+ "but",
164
+ "are",
165
+ "was",
166
+ "were",
167
+ "has",
168
+ "have",
169
+ "had",
170
+ "its",
171
+ "their",
172
+ "our",
173
+ "you",
174
+ "your",
175
+ "they",
176
+ "them",
177
+ "all",
178
+ "any",
179
+ "can",
180
+ "will",
181
+ "would",
182
+ "should",
183
+ "when",
184
+ "what",
185
+ "which",
186
+ "who",
187
+ "why",
188
+ "how",
189
+ "via",
190
+ "per",
191
+ "off",
192
+ "out",
193
+ "over",
194
+ "under",
195
+ "than",
196
+ "then",
197
+ "now",
198
+ "one",
199
+ "two",
200
+ "get",
201
+ "set",
202
+ "use",
203
+ "used",
204
+ "using",
205
+ "add",
206
+ "added",
207
+ "new",
208
+ "old"
209
+ ]);
210
+ const MIN_TERM_LENGTH = 3;
211
+ const MAX_LABEL_LENGTH = 120;
212
+ const MAX_EXEMPLAR_LENGTH = 60;
213
+ const DEFAULT_TERM_COUNT = 3;
214
+ /** Concatenated handle text for one row; empty string when it has none. */
215
+ function handleText(row) {
216
+ const parts = [];
217
+ for (const field of HANDLE_FIELDS) {
218
+ const value = row[field];
219
+ if (typeof value === "string" && value.length > 0) parts.push(value);
220
+ }
221
+ return parts.join(" ");
222
+ }
223
+ /** The single best exemplar string for a row — first non-empty handle field. */
224
+ function exemplarText(input) {
225
+ for (const field of HANDLE_FIELDS) {
226
+ const value = input.row[field];
227
+ if (typeof value === "string" && value.trim().length > 0) return value.trim();
228
+ }
229
+ return null;
230
+ }
231
+ function tokenise(text) {
232
+ const out = /* @__PURE__ */ new Set();
233
+ for (const token of text.toLowerCase().split(/[^a-z0-9]+/)) {
234
+ if (token.length < MIN_TERM_LENGTH) continue;
235
+ if (STOPWORDS.has(token)) continue;
236
+ out.add(token);
237
+ }
238
+ return out;
239
+ }
240
+ function medoidOf(members, centroid) {
241
+ let best = null;
242
+ let bestScore = Number.NEGATIVE_INFINITY;
243
+ for (const member of members) {
244
+ const score = cosineSimilarity(member.vector, centroid);
245
+ if (score > bestScore || score === bestScore && best !== null && member.id < best.id) {
246
+ best = member;
247
+ bestScore = score;
248
+ }
249
+ }
250
+ return best;
251
+ }
252
+ function distinguishingTerms(members, corpus, count = DEFAULT_TERM_COUNT) {
253
+ if (members.length === 0) return [];
254
+ const memberTokens = members.map((m) => tokenise(handleText(m.row)));
255
+ const corpusTokens = corpus.map((c) => tokenise(handleText(c.row)));
256
+ const inDf = /* @__PURE__ */ new Map();
257
+ for (const tokens of memberTokens) for (const t of tokens) inDf.set(t, (inDf.get(t) ?? 0) + 1);
258
+ const corpusDf = /* @__PURE__ */ new Map();
259
+ for (const tokens of corpusTokens) for (const t of tokens) corpusDf.set(t, (corpusDf.get(t) ?? 0) + 1);
260
+ const scored = [];
261
+ for (const [term, df] of inDf) {
262
+ const score = df / members.length - (corpus.length === 0 ? 0 : (corpusDf.get(term) ?? 0) / corpus.length);
263
+ if (score <= 0) continue;
264
+ scored.push({
265
+ term,
266
+ score
267
+ });
268
+ }
269
+ scored.sort((a, b) => b.score - a.score || a.term.localeCompare(b.term));
270
+ return scored.slice(0, count).map((s) => s.term);
271
+ }
272
+ function buildLabel(members, corpus, centroid) {
273
+ const medoid = medoidOf(members, centroid);
274
+ const terms = distinguishingTerms(members, corpus);
275
+ const exemplar = medoid === null ? null : exemplarText(medoid) ?? `${medoid.namespace}/${medoid.type}/${medoid.id}`;
276
+ return (terms.length === 0 ? exemplar ?? "unlabelled" : exemplar === null ? terms.join(" / ") : `${terms.join(" / ")} — ${exemplar.slice(0, MAX_EXEMPLAR_LENGTH)}`).slice(0, MAX_LABEL_LENGTH);
277
+ }
278
+
279
+ //#endregion
280
+ //#region ../../plugins/substrate-recall/src/row-visibility.ts
281
+ /**
282
+ * Row-scoped read policy on the recall surfaces.
283
+ *
284
+ * A `row()` policy allows a (namespace, type) and attaches `row-filter`
285
+ * obligations. The surfaces evaluate them per row with the caller's request
286
+ * context, through the engine's own evaluator (`applyObligations`), against
287
+ * the full stored row body.
288
+ */
289
+ /** The context of a caller with no transport identity (the MCP tool). */
290
+ function anonymousCaller() {
291
+ return {
292
+ identity: null,
293
+ now: /* @__PURE__ */ new Date(),
294
+ headers: {},
295
+ meta: {}
296
+ };
297
+ }
298
+ const NO_TRUSTED_PROXIES = /* @__PURE__ */ new Set();
299
+ /** The caller context the engine would build for this HTTP request. */
300
+ function callerFromRequest(req) {
301
+ return {
302
+ ...anonymousCaller(),
303
+ ...buildContext(req, NO_TRUSTED_PROXIES)
304
+ };
305
+ }
306
+ /** A frame resolver's ctx, as a caller context. */
307
+ function callerFromContext(ctx) {
308
+ const { namespace: _ns, operation: _op, entry: _entry, verb: _verb, ...caller } = ctx;
309
+ return caller;
310
+ }
311
+ /** `check`, evaluated at most once per (namespace, type). */
312
+ function memoCheck(check) {
313
+ if (check === void 0) return void 0;
314
+ const seen = /* @__PURE__ */ new Map();
315
+ return (ns, type) => {
316
+ const key = `${ns}/${type}`;
317
+ let decision = seen.get(key);
318
+ if (decision === void 0) {
319
+ decision = check(ns, type);
320
+ seen.set(key, decision);
321
+ }
322
+ return decision;
323
+ };
324
+ }
325
+ const STAND_INS = /* @__PURE__ */ new WeakSet();
326
+ /**
327
+ * Marks `row` as a stand-in for a body the store could not resolve. A scope
328
+ * with row filters never admits a stand-in, since the filter would judge a
329
+ * body that is not the row's.
330
+ */
331
+ function unresolvedRow(row) {
332
+ STAND_INS.add(row);
333
+ return row;
334
+ }
335
+ function hasRowFilters(decision) {
336
+ return decision.obligations?.some((o) => o.kind === "row-filter") ?? false;
337
+ }
338
+ /**
339
+ * Keeps the items the caller may read, in order: a denied scope drops all of
340
+ * its items, and an allowed one keeps those whose `row` its row-filter
341
+ * obligations admit (never an {@link unresolvedRow} stand-in). Without a
342
+ * check everything is kept.
343
+ */
344
+ function visibleRows(items, check, caller) {
345
+ if (check === void 0) return [...items];
346
+ const byScope = /* @__PURE__ */ new Map();
347
+ for (const item of items) {
348
+ const scope = `${item.namespace}/${item.type}`;
349
+ let entry = byScope.get(scope);
350
+ if (entry === void 0) {
351
+ entry = {
352
+ decision: check(item.namespace, item.type),
353
+ items: []
354
+ };
355
+ byScope.set(scope, entry);
356
+ }
357
+ entry.items.push(item);
358
+ }
359
+ const kept = /* @__PURE__ */ new Set();
360
+ for (const { decision, items: scoped } of byScope.values()) {
361
+ if (!decision.allow) continue;
362
+ const first = scoped[0];
363
+ const ctx = {
364
+ ...caller ?? anonymousCaller(),
365
+ namespace: first.namespace,
366
+ operation: "query",
367
+ entry: first.type
368
+ };
369
+ const admitted = new Set(applyObligations(decision, scoped.map((i) => i.row), ctx));
370
+ const filtered = hasRowFilters(decision);
371
+ for (const item of scoped) if (admitted.has(item.row) && !(filtered && STAND_INS.has(item.row))) kept.add(item);
372
+ }
373
+ return items.filter((i) => kept.has(i));
374
+ }
375
+ /**
376
+ * `visibleRows` for refs that carry no body. Refs in a row-scoped scope are
377
+ * judged on the body stored with their embedding under `model`; one with no
378
+ * such embedding, or with no `model`, is dropped.
379
+ */
380
+ async function visibleRefs(refs, check, caller, store, model) {
381
+ if (check === void 0) return [...refs];
382
+ const decisions = /* @__PURE__ */ new Map();
383
+ const decide = (r) => {
384
+ const scope = `${r.namespace}/${r.type}`;
385
+ let d = decisions.get(scope);
386
+ if (d === void 0) {
387
+ d = check(r.namespace, r.type);
388
+ decisions.set(scope, d);
389
+ }
390
+ return d;
391
+ };
392
+ const scoped = refs.filter((r) => {
393
+ const d = decide(r);
394
+ return d.allow && hasRowFilters(d);
395
+ });
396
+ const admitted = /* @__PURE__ */ new Set();
397
+ if (scoped.length > 0 && model !== void 0) {
398
+ const fetched = await store.fetchEmbeddings(scoped, model);
399
+ for (const f of visibleRows(fetched, check, caller)) admitted.add(`${f.namespace}/${f.type}/${f.id}`);
400
+ }
401
+ return refs.filter((r) => {
402
+ const d = decide(r);
403
+ if (!d.allow) return false;
404
+ return !hasRowFilters(d) || admitted.has(`${r.namespace}/${r.type}/${r.id}`);
405
+ });
406
+ }
407
+ const STORE_MAX_K = 100;
408
+ /**
409
+ * Collects up to `k` visible items from a ranked source. With no row filter
410
+ * one fetch of `k` suffices; otherwise it refetches at 2k, 4k, ... up to 10k
411
+ * (and never past the stores' 100-row clamp), stopping once k are visible or
412
+ * the source runs dry.
413
+ *
414
+ * shortcut: when the cap is hit it returns fewer than k even if more visible
415
+ * rows rank further down; push the predicate into the store query if callers
416
+ * hit it.
417
+ */
418
+ async function fillVisible(k, decision, fetch, keep) {
419
+ if (decision === void 0 || !hasRowFilters(decision)) return keep(await fetch(k));
420
+ const cap = Math.max(k, Math.min(k * 10, STORE_MAX_K));
421
+ for (let n = Math.min(k * 2, cap);; n = Math.min(n * 2, cap)) {
422
+ const raw = await fetch(n);
423
+ const kept = keep(raw);
424
+ if (kept.length >= k || raw.length < n || n === cap) return kept.slice(0, k);
425
+ }
426
+ }
427
+
428
+ //#endregion
429
+ //#region ../../plugins/substrate-recall/src/spawn-cluster-worker.ts
430
+ /**
431
+ * The production `ClusterSpawn`: one Worker per pass, torn down on
432
+ * completion.
433
+ *
434
+ * No pool: crystallisation is rare and worker startup is small beside a
435
+ * CPU-bound clustering run.
436
+ *
437
+ * Wall-clock timeout: a hung worker would never settle, so
438
+ * `CrystalliseGuard.runExclusive` would never clear its in-flight flag and
439
+ * every later crystallise call would 409 for the life of the process. The
440
+ * timeout is a runaway guard, not a performance bound, hence the generous
441
+ * default.
442
+ */
443
+ /**
444
+ * 10 minutes. A guard rail to catch a hung worker, not a cap on a
445
+ * slow-but-legitimate pass.
446
+ */
447
+ const DEFAULT_CLUSTER_WORKER_TIMEOUT_MS = 6e5;
448
+ function createSpawnClusterWorker(opts = {}) {
449
+ const timeoutMs = opts.timeoutMs ?? 6e5;
450
+ return (payload) => new Promise((resolve, reject) => {
451
+ const worker = new Worker(new URL("./cluster-worker.js", import.meta.url));
452
+ let settled = false;
453
+ let timer;
454
+ const finish = (fn) => {
455
+ if (settled) return;
456
+ settled = true;
457
+ if (timer !== void 0) clearTimeout(timer);
458
+ worker.terminate();
459
+ fn();
460
+ };
461
+ timer = setTimeout(() => {
462
+ finish(() => reject(/* @__PURE__ */ new Error(`cluster worker exceeded ${timeoutMs}ms without replying — terminated to release the crystallise guard`)));
463
+ }, timeoutMs);
464
+ timer.unref?.();
465
+ worker.on("message", (reply) => {
466
+ finish(() => {
467
+ if (reply.ok && reply.assignments !== void 0) {
468
+ resolve(reply.assignments);
469
+ return;
470
+ }
471
+ reject(new Error(reply.message ?? "cluster worker failed without a message"));
472
+ });
473
+ });
474
+ worker.on("error", (err) => finish(() => reject(err)));
475
+ worker.on("exit", (code) => finish(() => reject(/* @__PURE__ */ new Error(`cluster worker exited with code ${code} before replying`))));
476
+ try {
477
+ worker.postMessage(payload, [payload.flat.buffer]);
478
+ } catch (err) {
479
+ finish(() => reject(err instanceof Error ? err : new Error(String(err))));
480
+ }
481
+ });
482
+ }
483
+ const spawnClusterWorker = createSpawnClusterWorker();
484
+
485
+ //#endregion
486
+ //#region ../../plugins/substrate-recall/src/run-clusterer.ts
487
+ /**
488
+ * Marshalling + worker orchestration for a clustering pass.
489
+ *
490
+ * The `spawn` seam keeps this module testable in-process: the flattening,
491
+ * validation and result-shape checks are ordinary unit-tested code, and the
492
+ * real `worker_threads` boundary is exercised separately by
493
+ * `test/cluster-worker-isolation.test.ts`.
494
+ */
495
+ async function runClusterer(vectors, params, deps = {}) {
496
+ if (vectors.length === 0) return [];
497
+ const dims = vectors[0].length;
498
+ for (const [i, v] of vectors.entries()) if (v.length !== dims) throw new Error(`runClusterer: vector ${i} has dimension ${v.length}, expected ${dims} — every candidate must come from the same embedder model`);
499
+ const flat = new Float32Array(vectors.length * dims);
500
+ for (let i = 0; i < vectors.length; i++) flat.set(vectors[i], i * dims);
501
+ const assignments = await (deps.spawn ?? spawnClusterWorker)({
502
+ flat,
503
+ rows: vectors.length,
504
+ dims,
505
+ params
506
+ });
507
+ if (assignments.length !== vectors.length) throw new Error(`runClusterer: assignment count ${assignments.length} != input count ${vectors.length}`);
508
+ return Array.from(assignments);
509
+ }
510
+
511
+ //#endregion
512
+ //#region ../../plugins/substrate-recall/src/crystallise-core.ts
513
+ const DEFAULT_CRYSTALLISE_CONFIG = {
514
+ nComponents: 10,
515
+ nNeighbors: 15,
516
+ minClusterSize: 5,
517
+ seed: 42,
518
+ accretionThreshold: .6
519
+ };
520
+ function bad$2(message) {
521
+ throw Object.assign(new Error(message), { code: "bad_request" });
522
+ }
523
+ /**
524
+ * Returns `raw[key]` as an integer, or undefined when absent. Throws
525
+ * `bad_request` if it is not an integer or is below `opts.min`.
526
+ *
527
+ * `min` mirrors `CrystalliseSchema` (bootstrap.ts), which guards only the
528
+ * config file; this guards the per-request override. An out-of-range value can
529
+ * hang the clusterer worker, and `minClusterSize: 0` retires every cluster.
530
+ */
531
+ function integerOverride(raw, key, opts = {}) {
532
+ const value = raw[key];
533
+ if (value === void 0) return void 0;
534
+ if (typeof value !== "number" || !Number.isInteger(value)) bad$2(`"params.${key}" must be an integer`);
535
+ if (opts.min !== void 0 && value < opts.min) bad$2(`"params.${key}" must be >= ${opts.min}`);
536
+ return value;
537
+ }
538
+ function validateCrystalliseInput(value) {
539
+ const raw = value ?? {};
540
+ const mode = raw.mode ?? "accrete";
541
+ if (mode !== "form" && mode !== "accrete") bad$2("\"mode\" must be \"form\" or \"accrete\"");
542
+ const select = validateSelector(raw.select);
543
+ let params;
544
+ if (raw.params !== void 0) {
545
+ if (raw.params === null || typeof raw.params !== "object") bad$2("\"params\" must be an object");
546
+ const p = raw.params;
547
+ const overrides = {};
548
+ const nComponents = integerOverride(p, "nComponents", { min: 0 });
549
+ const nNeighbors = integerOverride(p, "nNeighbors", { min: 1 });
550
+ const minClusterSize = integerOverride(p, "minClusterSize", { min: 1 });
551
+ const seed = integerOverride(p, "seed");
552
+ if (nComponents !== void 0) overrides.nComponents = nComponents;
553
+ if (nNeighbors !== void 0) overrides.nNeighbors = nNeighbors;
554
+ if (minClusterSize !== void 0) overrides.minClusterSize = minClusterSize;
555
+ if (seed !== void 0) overrides.seed = seed;
556
+ params = overrides;
557
+ }
558
+ return {
559
+ mode,
560
+ select,
561
+ ...params !== void 0 ? { params } : {}
562
+ };
563
+ }
564
+ /** Mean of the members' vectors, in whatever space they were handed in. */
565
+ function meanVector(vectors) {
566
+ const dims = vectors[0].length;
567
+ const sums = new Float64Array(dims);
568
+ for (const v of vectors) for (let i = 0; i < dims; i++) sums[i] += v[i];
569
+ const out = new Float32Array(dims);
570
+ for (let i = 0; i < dims; i++) out[i] = sums[i] / vectors.length;
571
+ return out;
572
+ }
573
+ function assertScopesReadable(select, check) {
574
+ if (check === void 0) return;
575
+ for (const scope of select.scopes) {
576
+ const decision = check(scope.namespace, scope.type);
577
+ if (decision.allow) continue;
578
+ throw Object.assign(/* @__PURE__ */ new Error(`read policy denies ${scope.namespace}/${scope.type}${decision.reason === void 0 ? "" : ` — ${decision.reason}`}`), { code: "policy_denied" });
579
+ }
580
+ }
581
+ /**
582
+ * Mark departed members and retire clusters that fell below the floor.
583
+ *
584
+ * Returns the counts departed and retired. No-op when `deps.rowsMissing` is
585
+ * absent.
586
+ *
587
+ * Runs first in both modes, so accretion never attaches to a cluster about to
588
+ * retire. Departure marks rather than removes, keeping membership auditable.
589
+ *
590
+ * Retirement also departs the cluster's survivors: `claimedMembers` ignores
591
+ * `retiredAt` and there is no un-retire, so they would otherwise stay claimed
592
+ * forever. `retire()` and `markDeparted()` are not one transaction, so every
593
+ * pass re-checks already-retired clusters and departs any stranded survivors.
594
+ */
595
+ async function sweepStaleMembership(deps, stamp) {
596
+ const probe = deps.rowsMissing;
597
+ if (probe === void 0) return {
598
+ departed: 0,
599
+ retired: 0
600
+ };
601
+ const membersByCluster = /* @__PURE__ */ new Map();
602
+ for (const member of await deps.clusters.listAllMembers()) {
603
+ const ref = {
604
+ namespace: member.memberNs,
605
+ type: member.memberType,
606
+ id: member.memberId
607
+ };
608
+ const bucket = membersByCluster.get(member.clusterId);
609
+ if (bucket === void 0) membersByCluster.set(member.clusterId, [ref]);
610
+ else bucket.push(ref);
611
+ }
612
+ const attached = (await deps.clusters.listClusters()).flatMap((cluster) => membersByCluster.get(cluster.id) ?? []);
613
+ const missing = attached.length === 0 ? /* @__PURE__ */ new Set() : await probe(attached);
614
+ const gone = attached.filter((ref) => missing.has(memberKey(ref)));
615
+ const goneKeys = new Set(gone.map(memberKey));
616
+ const departed = gone.length === 0 ? 0 : await deps.clusters.markDeparted(gone, stamp);
617
+ let retired = 0;
618
+ for (const cluster of await deps.clusters.listClusters({ includeRetired: true })) {
619
+ if (cluster.retiredAt === null) {
620
+ const floor = cluster.provenance.params.minClusterSize;
621
+ if (cluster.memberCount >= floor) continue;
622
+ await deps.clusters.retire(cluster.id, stamp);
623
+ retired++;
624
+ }
625
+ const survivors = (membersByCluster.get(cluster.id) ?? []).filter((ref) => !goneKeys.has(memberKey(ref)));
626
+ if (survivors.length > 0) await deps.clusters.markDeparted(survivors, stamp);
627
+ }
628
+ return {
629
+ departed,
630
+ retired
631
+ };
632
+ }
633
+ async function handleCrystallise(input, deps) {
634
+ assertScopesReadable(input.select, deps.checkReadPolicy);
635
+ const now = deps.now ?? (() => /* @__PURE__ */ new Date());
636
+ const newId = deps.newId ?? (() => crypto.randomUUID());
637
+ const decay = await sweepStaleMembership(deps, now());
638
+ const candidates = visibleRows(await deps.embeddings.selectCandidates(input.select, deps.model), deps.checkReadPolicy, deps.caller);
639
+ const claimed = await deps.clusters.claimedMembers(candidates.map((c) => ({
640
+ namespace: c.namespace,
641
+ type: c.type,
642
+ id: c.id
643
+ })));
644
+ const unclaimed = candidates.filter((c) => !claimed.has(memberKey(c)));
645
+ const empty = {
646
+ mode: input.mode,
647
+ candidates: candidates.length,
648
+ considered: unclaimed.length,
649
+ clustersFormed: 0,
650
+ clustersAccretedInto: 0,
651
+ membersAttached: 0,
652
+ noise: 0,
653
+ clusters: [],
654
+ departed: decay.departed,
655
+ retired: decay.retired
656
+ };
657
+ if (unclaimed.length === 0) return empty;
658
+ if (input.mode === "accrete") return accrete(unclaimed, empty, deps, now(), newId);
659
+ const params = {
660
+ nComponents: input.params?.nComponents ?? deps.config.nComponents,
661
+ nNeighbors: input.params?.nNeighbors ?? deps.config.nNeighbors,
662
+ minClusterSize: input.params?.minClusterSize ?? deps.config.minClusterSize,
663
+ seed: input.params?.seed ?? deps.config.seed
664
+ };
665
+ const normalised = l2normalize(unclaimed.map((c) => c.vector));
666
+ const assignments = await (deps.runClusterer ?? ((v, p) => runClusterer(v, p)))(normalised, params);
667
+ const groups = /* @__PURE__ */ new Map();
668
+ let noise = 0;
669
+ for (const [i, label] of assignments.entries()) {
670
+ if (label < 0) {
671
+ noise++;
672
+ continue;
673
+ }
674
+ const bucket = groups.get(label);
675
+ if (bucket === void 0) groups.set(label, [unclaimed[i]]);
676
+ else bucket.push(unclaimed[i]);
677
+ }
678
+ const provenance = {
679
+ backend: CLUSTERER_BACKEND,
680
+ backendVersion: CLUSTERER_BACKEND_VERSION,
681
+ regime: "normalised",
682
+ seed: params.seed,
683
+ params: {
684
+ nComponents: params.nComponents,
685
+ nNeighbors: params.nNeighbors,
686
+ minClusterSize: params.minClusterSize
687
+ },
688
+ model: deps.model
689
+ };
690
+ const summaries = [];
691
+ let membersAttached = 0;
692
+ const stamp = now();
693
+ for (const label of Array.from(groups.keys()).sort((a, b) => a - b)) {
694
+ const members = groups.get(label);
695
+ const centroid = meanVector(members.map((m) => m.vector));
696
+ const similarities = members.map((m) => cosineSimilarity(m.vector, centroid));
697
+ const cohesion = similarities.reduce((a, b) => a + b, 0) / similarities.length;
698
+ const cluster = await deps.clusters.createCluster({
699
+ id: newId(),
700
+ centroid,
701
+ cohesion,
702
+ label: buildLabel(members, unclaimed, centroid),
703
+ labelledBy: "medoid",
704
+ provenance,
705
+ now: stamp
706
+ });
707
+ const attachments = members.map((m, i) => ({
708
+ id: newId(),
709
+ clusterId: cluster.id,
710
+ ref: {
711
+ namespace: m.namespace,
712
+ type: m.type,
713
+ id: m.id
714
+ },
715
+ origin: "formation",
716
+ similarity: similarities[i],
717
+ now: stamp
718
+ }));
719
+ await deps.clusters.attachMembers(attachments);
720
+ membersAttached += attachments.length;
721
+ summaries.push({
722
+ id: cluster.id,
723
+ label: cluster.label,
724
+ memberCount: attachments.length,
725
+ cohesion
726
+ });
727
+ }
728
+ return {
729
+ ...empty,
730
+ clustersFormed: summaries.length,
731
+ membersAttached,
732
+ noise,
733
+ clusters: summaries
734
+ };
735
+ }
736
+ /**
737
+ * Attach unclaimed rows to the nearest live centroid within the threshold.
738
+ *
739
+ * Never runs the clusterer, never touches an existing membership, and never
740
+ * considers a retired cluster. An exact scan over live centroids.
741
+ */
742
+ async function accrete(unclaimed, empty, deps, stamp, newId) {
743
+ const live = await deps.clusters.listClusters();
744
+ if (live.length === 0) return empty;
745
+ const attachments = [];
746
+ const touched = /* @__PURE__ */ new Set();
747
+ for (const candidate of unclaimed) {
748
+ let bestId = null;
749
+ let bestScore = Number.NEGATIVE_INFINITY;
750
+ for (const cluster of live) {
751
+ const score = cosineSimilarity(candidate.vector, cluster.centroid);
752
+ if (score > bestScore) {
753
+ bestScore = score;
754
+ bestId = cluster.id;
755
+ }
756
+ }
757
+ if (bestId === null || bestScore < deps.config.accretionThreshold) continue;
758
+ attachments.push({
759
+ id: newId(),
760
+ clusterId: bestId,
761
+ ref: {
762
+ namespace: candidate.namespace,
763
+ type: candidate.type,
764
+ id: candidate.id
765
+ },
766
+ origin: "accretion",
767
+ similarity: bestScore,
768
+ now: stamp
769
+ });
770
+ touched.add(bestId);
771
+ }
772
+ if (attachments.length === 0) return empty;
773
+ await deps.clusters.attachMembers(attachments);
774
+ const summaries = [];
775
+ for (const clusterId of touched) {
776
+ const cluster = await deps.clusters.getCluster(clusterId);
777
+ if (cluster === null) continue;
778
+ summaries.push({
779
+ id: cluster.id,
780
+ label: cluster.label,
781
+ memberCount: cluster.memberCount,
782
+ cohesion: cluster.cohesion
783
+ });
784
+ }
785
+ return {
786
+ ...empty,
787
+ clustersAccretedInto: touched.size,
788
+ membersAttached: attachments.length,
789
+ clusters: summaries
790
+ };
791
+ }
792
+
793
+ //#endregion
794
+ //#region ../../plugins/substrate-recall/src/crystallise-guard.ts
795
+ /**
796
+ * Mutual exclusion for crystallise passes: concurrent passes would each see the
797
+ * same rows as unclaimed and form duplicate clusters.
798
+ *
799
+ * One instance must be shared by both transports (the route and the
800
+ * `recall/crystallise` frame); `createRecallPlugin` builds it once. An
801
+ * in-process flag covers this binary, and the optional `crossProcess` lock
802
+ * (`ClusterStore.withFormationLock`) covers other binaries on the same store.
803
+ * Either refusing throws `crystallise_in_flight`.
804
+ */
805
+ const CRYSTALLISE_IN_FLIGHT_CODE = "crystallise_in_flight";
806
+ function inFlightError() {
807
+ return Object.assign(/* @__PURE__ */ new Error("a crystallise pass is already running — retry when it completes"), { code: CRYSTALLISE_IN_FLIGHT_CODE });
808
+ }
809
+ function createCrystalliseGuard(opts = {}) {
810
+ let inFlight = false;
811
+ return { async runExclusive(fn) {
812
+ if (inFlight) throw inFlightError();
813
+ inFlight = true;
814
+ try {
815
+ return opts.crossProcess === void 0 ? await fn() : await opts.crossProcess(fn);
816
+ } finally {
817
+ inFlight = false;
818
+ }
819
+ } };
820
+ }
821
+
822
+ //#endregion
823
+ //#region ../../plugins/substrate-recall/src/embeddings-store.ts
824
+ /** Field names a row filter may name: plain identifiers, so they are safe to address in SQL. */
825
+ const ROW_FILTER_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/;
826
+ /** Why `value` is not a usable row filter, or null when it is. */
827
+ function rowFilterProblem(value) {
828
+ if (value === null || typeof value !== "object" || Array.isArray(value)) return "must be an object of field -> { eq } | { in }";
829
+ const scalar = (x) => x === null || [
830
+ "string",
831
+ "number",
832
+ "boolean"
833
+ ].includes(typeof x);
834
+ for (const [field, pred] of Object.entries(value)) {
835
+ if (!ROW_FILTER_FIELD.test(field)) return `field '${field}' is not a plain identifier`;
836
+ if (pred === null || typeof pred !== "object") return `'${field}' needs { eq } or { in }`;
837
+ const keys = Object.keys(pred);
838
+ if (keys.length !== 1 || !["eq", "in"].includes(keys[0])) return `'${field}' takes exactly one of eq / in`;
839
+ const v = pred[keys[0]];
840
+ if (keys[0] === "eq" && !scalar(v)) return `'${field}'.eq must be a scalar or null`;
841
+ if (keys[0] === "in" && (!Array.isArray(v) || v.length === 0 || !v.every(scalar))) return `'${field}'.in must be a non-empty array of scalars`;
842
+ }
843
+ return null;
844
+ }
845
+ /** Does a row body satisfy the filter? The in-memory store's semantics, mirrored by pg's SQL. */
846
+ function matchesRowFilter(row, filter) {
847
+ const same = (a, b) => b === null ? a === null || a === void 0 : a !== null && a !== void 0 && String(a) === String(b);
848
+ const value = (field) => Object.hasOwn(row, field) ? row[field] : void 0;
849
+ return Object.entries(filter).every(([field, pred]) => pred.in !== void 0 ? pred.in.some((v) => same(value(field), v)) : same(value(field), pred.eq ?? null));
850
+ }
851
+
852
+ //#endregion
853
+ //#region ../../plugins/substrate-recall/src/rrf.ts
854
+ /**
855
+ * Reciprocal Rank Fusion over an arbitrary number of retrieval arms.
856
+ *
857
+ * Ranks, not scores: the arms' scores are on incomparable scales (cosine,
858
+ * `ts_rank`, term counts), and a rank is the one thing every arm agrees on.
859
+ *
860
+ * Union, not intersection: a row only one arm found still enters the pool,
861
+ * so the lexical arm can surface rows the dense arm missed.
862
+ *
863
+ * A missing arm contributes no term, not a penalty term, so enabling an arm
864
+ * cannot demote rows it says nothing about.
865
+ */
866
+ /**
867
+ * The RRF constant from Cormack et al. It damps the
868
+ * difference between adjacent top ranks, so a row needs agreement across arms
869
+ * rather than a narrow win within one to move.
870
+ */
871
+ const RRF_K = 60;
872
+ /**
873
+ * Fuse ordered arms into a score per id.
874
+ *
875
+ * Each arm is an ordered list of row ids, best first. Ranks are 1-based and
876
+ * counted PER ARM — a row leading the second arm scores as a leader, not as
877
+ * though it were buried behind the first arm's length.
878
+ *
879
+ * Duplicates within one arm are ignored rather than summed: a store returning
880
+ * the same row twice is reporting one hit, and double-counting would let a
881
+ * buggy arm outvote a correct one.
882
+ */
883
+ function fuseByRank(arms, k = 60) {
884
+ const out = /* @__PURE__ */ new Map();
885
+ for (const arm of arms) for (const [id, rank] of rankArm(arm)) out.set(id, (out.get(id) ?? 0) + 1 / (k + rank));
886
+ return out;
887
+ }
888
+ /**
889
+ * Map each id in one arm to its 1-based rank, skipping repeats of an id
890
+ * already seen. Shared by fusion and the diagnostics so both report the rank
891
+ * that was actually scored.
892
+ */
893
+ function rankArm(arm) {
894
+ const ranks = /* @__PURE__ */ new Map();
895
+ for (const id of arm) if (!ranks.has(id)) ranks.set(id, ranks.size + 1);
896
+ return ranks;
897
+ }
898
+ /**
899
+ * Per-arm ranks for one id, for the opt-in diagnostic envelope.
900
+ *
901
+ * `null` means the arm did not return the row; ranks are 1-based and count
902
+ * each id once, matching the rank `fuseByRank` scored.
903
+ */
904
+ function armRanks(id, dense, lexical) {
905
+ return {
906
+ dense: rankArm(dense).get(id) ?? null,
907
+ lexical: rankArm(lexical).get(id) ?? null
908
+ };
909
+ }
910
+
911
+ //#endregion
912
+ //#region ../../plugins/substrate-recall/src/recall/types.ts
913
+ function bindPolicy(check, caller) {
914
+ if (check === void 0) return void 0;
915
+ return (ns, type) => check(ns, type, caller.identity, caller);
916
+ }
917
+ /** Default salience config: off (weight=0, 7-day half-life, 0.3 damping). */
918
+ const DEFAULT_SALIENCE_CONFIG = {
919
+ weight: 0,
920
+ halfLifeHours: 168,
921
+ spreadDamping: .3
922
+ };
923
+
924
+ //#endregion
925
+ //#region ../../plugins/substrate-recall/src/recall/handler.ts
926
+ /**
927
+ * The transport-agnostic recall core. `handleRecallRequest` is shared by the
928
+ * HTTP route, the `recall/Hit` frame surface and the `recall` MCP tool.
929
+ */
930
+ function clamp(n, min, max) {
931
+ if (!Number.isFinite(n)) return min;
932
+ if (n < min) return min;
933
+ if (n > max) return max;
934
+ return n;
935
+ }
936
+ /** Longest accepted recall query text, on every surface. */
937
+ const MAX_RECALL_QUERY_CHARS = 8192;
938
+ async function handleRecallRequest(input, deps) {
939
+ const { embedder, store, lexicalStore, lexicalSources, embedSources, salience = DEFAULT_SALIENCE_CONFIG, spreadResolver = null, expansionResolver = null, expansionEnabled = true, stats, checkWritePolicy, caller } = deps;
940
+ const checkReadPolicy = memoCheck(deps.checkReadPolicy);
941
+ const denseArm = embedder !== void 0 && store !== void 0;
942
+ const lexicalWhyIfOff = lexicalStore === void 0 ? "no-store" : "disabled-by-request";
943
+ const lexicalArm = lexicalStore !== void 0 && input.lexical !== false;
944
+ if (!denseArm && !lexicalArm) throw Object.assign(/* @__PURE__ */ new Error(`recall has no arm to run. dense: off (${embedder === void 0 ? "no embedder" : "no EmbeddingsStore"}). lexical: off (${lexicalWhyIfOff}). Wire an embedder + EmbeddingsStore, wire a LexicalStore and declare \`lexical.source\` on the type, or drop \`lexical: false\` from the request.`), { code: lexicalWhyIfOff === "no-store" ? "embedder_unavailable" : "no_retrieval_arm" });
945
+ const namespace = input.namespace ?? process.env.SUBSTRATE_NAMESPACE;
946
+ if (namespace === void 0 || namespace === "") throw Object.assign(/* @__PURE__ */ new Error("recall: no namespace to search. Pass `namespace` on the request, or set SUBSTRATE_NAMESPACE in the server environment. There is no default — guessing one silently searches a namespace that may not exist and returns an empty result that looks like a miss."), { code: "missing_namespace" });
947
+ const where = input.where;
948
+ if (where !== void 0) {
949
+ const problem = rowFilterProblem(where);
950
+ if (problem !== null) throw Object.assign(/* @__PURE__ */ new Error(`"where" ${problem}`), { code: "bad_request" });
951
+ }
952
+ const type = input.type;
953
+ if (type === void 0 || type === "") throw Object.assign(/* @__PURE__ */ new Error("recall: pass `type`, the type to search. There is no default."), { code: "bad_request" });
954
+ if (input.query.length > 8192) throw Object.assign(/* @__PURE__ */ new Error(`recall: query is longer than ${MAX_RECALL_QUERY_CHARS} characters`), { code: "bad_request" });
955
+ const k = clamp(input.k ?? 10, 1, 100);
956
+ const threshold = typeof input.threshold === "number" ? input.threshold : 0;
957
+ const lexicalThreshold = typeof input.lexicalThreshold === "number" ? input.lexicalThreshold : threshold;
958
+ const decision = checkReadPolicy?.(namespace, type);
959
+ if (decision !== void 0) {
960
+ if (!decision.allow) throw Object.assign(new Error(decision.reason ?? "policy denied"), { code: "policy_denied" });
961
+ }
962
+ const embedSourceMissing = embedSources !== void 0 && embedSources.size() > 0 && embedSources.get(namespace, type) === void 0;
963
+ const denseRan = denseArm && !embedSourceMissing;
964
+ const denseWhy = denseRan ? "ran" : !denseArm ? embedder === void 0 ? "no-embedder" : "no-store" : "no-source";
965
+ const t0 = performance.now();
966
+ const returnVector = input.returnVector === true;
967
+ let t1 = t0;
968
+ let t2 = t0;
969
+ let vector;
970
+ let candidates = [];
971
+ if (denseRan && embedder !== void 0 && store !== void 0) {
972
+ vector = await embedder.embed(input.query);
973
+ t1 = performance.now();
974
+ const knnInput = {
975
+ namespace,
976
+ type,
977
+ model: embedder.modelId,
978
+ vector,
979
+ k
980
+ };
981
+ if (threshold > 0) knnInput.threshold = threshold;
982
+ if (returnVector) knnInput.returnVector = true;
983
+ if (where !== void 0) knnInput.rowFilter = where;
984
+ candidates = await fillVisible(k, decision, async (n) => (await store.knnSearch({
985
+ ...knnInput,
986
+ k: n
987
+ })).map((r) => ({
988
+ row: r.row,
989
+ namespace,
990
+ type,
991
+ score: r.score,
992
+ _salience: r.salience,
993
+ _blendedScore: r.score,
994
+ ...returnVector && r.vector !== void 0 ? { vector: r.vector } : {}
995
+ })), (rows) => visibleRows(rows, checkReadPolicy, caller));
996
+ t2 = performance.now();
997
+ }
998
+ if (input.expand === true && expansionEnabled && expansionResolver !== null && vector !== void 0 && embedder !== void 0 && store !== void 0) try {
999
+ const sources = candidates.map((c) => ({
1000
+ namespace,
1001
+ type,
1002
+ id: String(c.row.id ?? ""),
1003
+ row: c.row
1004
+ }));
1005
+ const neighbours = await expansionResolver(sources);
1006
+ if (neighbours.length > 0) {
1007
+ const fetched = await store.fetchEmbeddings(neighbours.map((n) => ({
1008
+ namespace: n.namespace,
1009
+ type: n.type,
1010
+ id: n.id
1011
+ })), embedder.modelId);
1012
+ const seenKeys = new Set(sources.map((s) => `${s.namespace}/${s.type}/${s.id}`));
1013
+ const byKey = /* @__PURE__ */ new Map();
1014
+ for (const n of neighbours) byKey.set(`${n.namespace}/${n.type}/${n.id}`, n);
1015
+ const readable = new Set(visibleRows(fetched, checkReadPolicy, caller));
1016
+ for (const f of fetched) {
1017
+ const neighbour = byKey.get(`${f.namespace}/${f.type}/${f.id}`);
1018
+ if (f.namespace !== namespace) continue;
1019
+ if (f.type !== type && neighbour?.allowsCrossType !== true) continue;
1020
+ if (!readable.has(f)) continue;
1021
+ if (where !== void 0 && !matchesRowFilter(f.row, where)) continue;
1022
+ const fkey = `${f.namespace}/${f.type}/${String(f.row.id ?? "")}`;
1023
+ if (seenKeys.has(fkey)) continue;
1024
+ seenKeys.add(fkey);
1025
+ const cos = cosineSimilarity(vector, f.vector);
1026
+ const candidate = {
1027
+ row: f.row,
1028
+ namespace: f.namespace,
1029
+ type: f.type,
1030
+ score: cos,
1031
+ _salience: 0,
1032
+ _blendedScore: cos,
1033
+ ...returnVector ? { vector: Array.from(f.vector) } : {}
1034
+ };
1035
+ if (neighbour !== void 0) candidate._expandedFrom = {
1036
+ namespace,
1037
+ type,
1038
+ id: neighbour.seedId
1039
+ };
1040
+ candidates.push(candidate);
1041
+ }
1042
+ candidates.sort((a, b) => b.score - a.score);
1043
+ candidates = candidates.slice(0, k);
1044
+ }
1045
+ } catch (err) {
1046
+ const msg = err instanceof Error ? err.message : String(err);
1047
+ process.stderr.write(`recall route expansion failure: ${msg}\n`);
1048
+ stats?.recordExpansionFailure();
1049
+ }
1050
+ const weight = salience.weight;
1051
+ let blended;
1052
+ if (weight > 0) {
1053
+ blended = candidates.map((c) => ({
1054
+ ...c,
1055
+ _blendedScore: c.score * (1 + weight * Math.log(1 + Math.max(0, c._salience)))
1056
+ }));
1057
+ blended.sort((a, b) => b._blendedScore - a._blendedScore);
1058
+ } else blended = candidates;
1059
+ let fusedRows = blended;
1060
+ let lexicalRan = false;
1061
+ let lexicalWhy = "no-store";
1062
+ if (lexicalStore !== void 0) {
1063
+ if (input.lexical === false) lexicalWhy = "disabled-by-request";
1064
+ else if (lexicalSources !== void 0 && lexicalSources.size() > 0 && lexicalSources.get(namespace, type) === void 0) lexicalWhy = "no-source";
1065
+ else {
1066
+ const hits = await fillVisible(k, decision, (n) => lexicalStore.search({
1067
+ namespace,
1068
+ type,
1069
+ query: input.query,
1070
+ k: n,
1071
+ ...where !== void 0 ? { rowFilter: where } : {}
1072
+ }), (found) => visibleRows(found.map((hit) => ({
1073
+ namespace,
1074
+ type,
1075
+ row: hit.row,
1076
+ hit
1077
+ })), checkReadPolicy, caller).map((v) => v.hit));
1078
+ lexicalRan = true;
1079
+ lexicalWhy = "ran";
1080
+ const denseIds = blended.map((r) => String(r.row.id ?? ""));
1081
+ const lex = await floorLexicalHits(hits, new Set(denseIds), lexicalThreshold, {
1082
+ namespace,
1083
+ type,
1084
+ vector,
1085
+ store,
1086
+ model: embedder?.modelId
1087
+ });
1088
+ const lexicalIds = lex.map((h) => h.rowId);
1089
+ if (lexicalIds.length === 0) fusedRows = blended.map((r, i) => ({
1090
+ ...r,
1091
+ ...input.explain === true ? {
1092
+ _arms: armRanks(denseIds[i], denseIds, lexicalIds),
1093
+ _denseScore: r.score
1094
+ } : {}
1095
+ }));
1096
+ else {
1097
+ const fused = fuseByRank([denseIds, lexicalIds]);
1098
+ const byId = /* @__PURE__ */ new Map();
1099
+ for (const [i, r] of blended.entries()) byId.set(denseIds[i], r);
1100
+ const denseRanked = new Set(denseIds);
1101
+ for (const h of lex) {
1102
+ if (byId.has(h.rowId)) continue;
1103
+ byId.set(h.rowId, {
1104
+ row: h.row,
1105
+ namespace,
1106
+ type,
1107
+ score: 0,
1108
+ _salience: 0,
1109
+ _blendedScore: 0
1110
+ });
1111
+ }
1112
+ fusedRows = [...fused.entries()].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).slice(0, k).flatMap(([id, fusedScore]) => {
1113
+ const base = byId.get(id);
1114
+ if (base === void 0) return [];
1115
+ const denseScore = denseRanked.has(id) ? base.score : null;
1116
+ return [{
1117
+ ...base,
1118
+ score: fusedScore,
1119
+ _blendedScore: fusedScore,
1120
+ ...input.explain === true ? {
1121
+ _arms: armRanks(id, denseIds, lexicalIds),
1122
+ _denseScore: denseScore
1123
+ } : {}
1124
+ }];
1125
+ });
1126
+ }
1127
+ }
1128
+ }
1129
+ const directRows = fusedRows.filter((r) => r._expandedFrom === void 0);
1130
+ const targets = extractTargets(namespace, type, directRows);
1131
+ const mayWrite = (ns, ty) => checkWritePolicy?.(ns, ty).allow ?? false;
1132
+ if (input.boost !== false && targets.length > 0 && store !== void 0 && mayWrite(namespace, type)) {
1133
+ store.boostSalience(targets, salience.halfLifeHours).catch((err) => {
1134
+ const msg = err instanceof Error ? err.message : String(err);
1135
+ process.stderr.write(`recall route boostSalience failure: ${msg}\n`);
1136
+ });
1137
+ if (spreadResolver !== null && salience.spreadDamping > 0) {
1138
+ const sources = directRows.map((r) => ({
1139
+ namespace,
1140
+ type,
1141
+ id: String(r.row.id ?? ""),
1142
+ row: r.row
1143
+ }));
1144
+ Promise.resolve().then(async () => {
1145
+ const spreadTargets = await spreadResolver(sources);
1146
+ if (spreadTargets.length === 0) return;
1147
+ const seen = /* @__PURE__ */ new Map();
1148
+ const permitted = spreadTargets.filter((t) => {
1149
+ const scope = `${t.namespace}/${t.type}`;
1150
+ const cached = seen.get(scope);
1151
+ if (cached !== void 0) return cached;
1152
+ const allow = mayWrite(t.namespace, t.type);
1153
+ seen.set(scope, allow);
1154
+ return allow;
1155
+ });
1156
+ const readable = await visibleRefs(permitted, checkReadPolicy, caller, store, embedder?.modelId);
1157
+ if (readable.length === 0) return;
1158
+ await store.boostSalience(readable, salience.halfLifeHours, salience.spreadDamping);
1159
+ }).catch((err) => {
1160
+ const msg = err instanceof Error ? err.message : String(err);
1161
+ process.stderr.write(`recall route spread boost failure: ${msg}\n`);
1162
+ });
1163
+ }
1164
+ }
1165
+ const t3 = performance.now();
1166
+ return {
1167
+ rows: fusedRows,
1168
+ model: denseRan ? embedder?.modelId ?? "" : "",
1169
+ arms: {
1170
+ dense: denseRan,
1171
+ denseWhy,
1172
+ lexical: lexicalRan,
1173
+ lexicalWhy
1174
+ },
1175
+ timings: {
1176
+ embed_ms: t1 - t0,
1177
+ knn_ms: t2 - t1,
1178
+ total_ms: t3 - t0
1179
+ }
1180
+ };
1181
+ }
1182
+ /**
1183
+ * Applies the cosine `threshold` to lexical hits the dense arm did not rank,
1184
+ * scoring each against its stored vector. A hit with no stored vector cannot
1185
+ * meet a floor and is dropped. Returns `hits` unchanged when there is no
1186
+ * floor or no query vector (the dense arm did not run).
1187
+ */
1188
+ async function floorLexicalHits(hits, denseIds, threshold, ctx) {
1189
+ const { namespace, type, vector, store, model } = ctx;
1190
+ if (threshold <= 0 || vector === void 0 || store === void 0 || model === void 0) return hits;
1191
+ const unranked = hits.filter((h) => !denseIds.has(h.rowId));
1192
+ if (unranked.length === 0) return hits;
1193
+ const fetched = await store.fetchEmbeddings(unranked.map((h) => ({
1194
+ namespace,
1195
+ type,
1196
+ id: h.rowId
1197
+ })), model);
1198
+ const passing = new Set(fetched.filter((f) => cosineSimilarity(vector, f.vector) >= threshold).map((f) => f.id));
1199
+ return hits.filter((h) => denseIds.has(h.rowId) || passing.has(h.rowId));
1200
+ }
1201
+ function extractTargets(namespace, type, rows) {
1202
+ const out = [];
1203
+ for (const r of rows) {
1204
+ const id = r.row.id;
1205
+ if (typeof id === "string" && id.length > 0) out.push({
1206
+ namespace,
1207
+ type,
1208
+ id
1209
+ });
1210
+ }
1211
+ return out;
1212
+ }
1213
+
1214
+ //#endregion
1215
+ //#region ../../plugins/substrate-recall/src/params.ts
1216
+ /**
1217
+ * Unknown-parameter refusal, shared by every recall surface. Each surface keeps
1218
+ * its own allowed set (the frame spells the search text `to`, the route
1219
+ * `query`); the refusal logic is shared.
1220
+ *
1221
+ * Refused rather than dropped: a silently ignored flag is indistinguishable
1222
+ * from one that ran and did nothing.
1223
+ */
1224
+ /** Keys present on `obj` that are not in `allowed`, in the caller's order. */
1225
+ function unknownParams(obj, allowed) {
1226
+ const ok = new Set(allowed);
1227
+ return Object.keys(obj).filter((key) => !ok.has(key));
1228
+ }
1229
+ /**
1230
+ * The refusal text. Names both the offending keys and the allowed set, the
1231
+ * latter generated from the array the parser uses.
1232
+ */
1233
+ function unknownParamMessage(unknown, allowed) {
1234
+ return `unknown ${unknown.length === 1 ? "parameter" : "parameters"}: ${unknown.join(", ")}. This surface accepts: ${[...allowed].sort().join(", ")}. Unknown parameters are refused rather than ignored: a silently dropped flag is indistinguishable from one that ran and did nothing.`;
1235
+ }
1236
+ /** `null` when every key is known, otherwise the refusal text. */
1237
+ function checkParams(obj, allowed) {
1238
+ const unknown = unknownParams(obj, allowed);
1239
+ return unknown.length === 0 ? null : unknownParamMessage(unknown, allowed);
1240
+ }
1241
+
1242
+ //#endregion
1243
+ //#region ../../plugins/substrate-recall/src/recall/route.ts
1244
+ /**
1245
+ * `POST /substrate/v1/recall` HTTP transport.
1246
+ *
1247
+ * KernelRouteClaim handler factory. Body parsing + error-code mapping live
1248
+ * here; retrieval itself is `handleRecallRequest` in `./handler.js`.
1249
+ */
1250
+ /**
1251
+ * Everything `POST /substrate/v1/recall` accepts. The refusal message is generated
1252
+ * from this array, so the two cannot disagree.
1253
+ */
1254
+ const ROUTE_PARAMS = [
1255
+ "query",
1256
+ "k",
1257
+ "namespace",
1258
+ "type",
1259
+ "threshold",
1260
+ "lexicalThreshold",
1261
+ "expand",
1262
+ "boost",
1263
+ "returnVector",
1264
+ "lexical",
1265
+ "explain",
1266
+ "where"
1267
+ ];
1268
+ function parseBody$3(req) {
1269
+ const raw = req.body;
1270
+ if (raw === null || Buffer.isBuffer(raw) && raw.length === 0) return { error: "request body is required" };
1271
+ const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
1272
+ if (text.trim().length === 0) return { error: "request body is required" };
1273
+ let parsed;
1274
+ try {
1275
+ parsed = JSON.parse(text);
1276
+ } catch (err) {
1277
+ return { error: err instanceof Error ? err.message : "invalid JSON" };
1278
+ }
1279
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return { error: "request body must be a JSON object" };
1280
+ const obj = parsed;
1281
+ const unknown = checkParams(obj, ROUTE_PARAMS);
1282
+ if (unknown !== null && obj.to === void 0) return { error: unknown };
1283
+ if (typeof obj.query !== "string" || obj.query.length === 0) return { error: typeof obj.to === "string" ? "\"query\" must be a non-empty string — this is the ROUTE, which spells the search text `query`; you passed `to`, which is the spelling the `recall/Hit` frame uses" : "\"query\" must be a non-empty string (the route and the MCP tool spell the search text `query`; the `recall/Hit` frame calls it `to`)" };
1284
+ const input = { query: obj.query };
1285
+ if (obj.k !== void 0) {
1286
+ if (typeof obj.k !== "number") return { error: "\"k\" must be a number" };
1287
+ input.k = obj.k;
1288
+ }
1289
+ if (obj.namespace !== void 0) {
1290
+ if (typeof obj.namespace !== "string") return { error: "\"namespace\" must be a string" };
1291
+ input.namespace = obj.namespace;
1292
+ }
1293
+ if (obj.type !== void 0) {
1294
+ if (typeof obj.type !== "string") return { error: "\"type\" must be a string" };
1295
+ input.type = obj.type;
1296
+ }
1297
+ if (obj.threshold !== void 0) {
1298
+ if (typeof obj.threshold !== "number") return { error: "\"threshold\" must be a number" };
1299
+ input.threshold = obj.threshold;
1300
+ }
1301
+ if (obj.lexicalThreshold !== void 0) {
1302
+ if (typeof obj.lexicalThreshold !== "number") return { error: "\"lexicalThreshold\" must be a number" };
1303
+ input.lexicalThreshold = obj.lexicalThreshold;
1304
+ }
1305
+ if (obj.expand !== void 0) {
1306
+ if (typeof obj.expand !== "boolean") return { error: "\"expand\" must be a boolean" };
1307
+ input.expand = obj.expand;
1308
+ }
1309
+ if (obj.boost !== void 0) {
1310
+ if (typeof obj.boost !== "boolean") return { error: "\"boost\" must be a boolean" };
1311
+ input.boost = obj.boost;
1312
+ }
1313
+ if (obj.returnVector !== void 0) {
1314
+ if (typeof obj.returnVector !== "boolean") return { error: "\"returnVector\" must be a boolean" };
1315
+ input.returnVector = obj.returnVector;
1316
+ }
1317
+ if (obj.lexical !== void 0) {
1318
+ if (typeof obj.lexical !== "boolean") return { error: "\"lexical\" must be a boolean" };
1319
+ input.lexical = obj.lexical;
1320
+ }
1321
+ if (obj.explain !== void 0) {
1322
+ if (typeof obj.explain !== "boolean") return { error: "\"explain\" must be a boolean" };
1323
+ input.explain = obj.explain;
1324
+ }
1325
+ if (obj.where !== void 0) input.where = obj.where;
1326
+ return input;
1327
+ }
1328
+ /**
1329
+ * KernelRouteClaim handler factory.
1330
+ *
1331
+ * Returns an `HttpHandler` for `POST /substrate/v1/recall`. Pass to
1332
+ * `KernelRouteClaim.handler` when building the substrate plugin's
1333
+ * `kernelRoutes` array.
1334
+ *
1335
+ * @example
1336
+ * ```ts
1337
+ * kernelRoutes: [
1338
+ * { path: 'recall', method: 'POST', handler: recallRouteHandler({ embedder, store }) }
1339
+ * ]
1340
+ * ```
1341
+ */
1342
+ function recallRouteHandler(cfg) {
1343
+ return async (req) => {
1344
+ const parsed = parseBody$3(req);
1345
+ if ("error" in parsed) return jsonResponse(400, {
1346
+ code: "bad_request",
1347
+ message: parsed.error
1348
+ });
1349
+ try {
1350
+ const unbound = cfg.checkReadPolicy;
1351
+ const unboundWrite = cfg.checkWritePolicy;
1352
+ const caller = callerFromRequest(req);
1353
+ const out = await handleRecallRequest(parsed, {
1354
+ ...cfg.embedder !== void 0 ? { embedder: cfg.embedder } : {},
1355
+ ...cfg.store !== void 0 ? { store: cfg.store } : {},
1356
+ ...cfg.lexicalStore !== void 0 ? { lexicalStore: cfg.lexicalStore } : {},
1357
+ ...cfg.lexicalSources !== void 0 ? { lexicalSources: cfg.lexicalSources } : {},
1358
+ ...cfg.embedSources !== void 0 ? { embedSources: cfg.embedSources } : {},
1359
+ salience: cfg.salience ?? DEFAULT_SALIENCE_CONFIG,
1360
+ spreadResolver: cfg.spreadResolver ?? null,
1361
+ expansionResolver: cfg.expansionResolver ?? null,
1362
+ expansionEnabled: cfg.expansionEnabled ?? true,
1363
+ ...cfg.stats !== void 0 ? { stats: cfg.stats } : {},
1364
+ ...unbound !== void 0 ? { checkReadPolicy: bindPolicy(unbound, caller) } : {},
1365
+ ...unboundWrite !== void 0 ? { checkWritePolicy: bindPolicy(unboundWrite, caller) } : {},
1366
+ caller
1367
+ });
1368
+ return jsonResponse(200, out);
1369
+ } catch (err) {
1370
+ const code = err?.code;
1371
+ const message = err instanceof Error ? err.message : String(err);
1372
+ if (code === "bad_request") return jsonResponse(400, {
1373
+ code: "bad_request",
1374
+ message
1375
+ });
1376
+ if (code === "missing_namespace") return jsonResponse(400, {
1377
+ code,
1378
+ message
1379
+ });
1380
+ if (code === "policy_denied") return jsonResponse(403, { error: {
1381
+ code: "policy_denied",
1382
+ message
1383
+ } });
1384
+ if (code === "unavailable" || code === "invalid_response") return jsonResponse(503, { error: {
1385
+ code: `embedder_${code}`,
1386
+ message
1387
+ } });
1388
+ if (code === "embedder_unavailable") return jsonResponse(503, { error: {
1389
+ code,
1390
+ message
1391
+ } });
1392
+ if (code === "no_retrieval_arm") return jsonResponse(400, { error: {
1393
+ code,
1394
+ message
1395
+ } });
1396
+ process.stderr.write(`recall route failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
1397
+ return jsonResponse(500, { error: {
1398
+ code: "internal",
1399
+ message: "recall failed"
1400
+ } });
1401
+ }
1402
+ };
1403
+ }
1404
+
1405
+ //#endregion
1406
+ //#region ../../plugins/substrate-recall/src/cluster-frame-surface.ts
1407
+ const scalar$1 = (type) => ({
1408
+ kind: "scalar",
1409
+ type
1410
+ });
1411
+ /**
1412
+ * Published shape of a `recall/Cluster` row.
1413
+ *
1414
+ * `centroid` is deliberately absent: it is a full embedding vector per row,
1415
+ * raw vector content that `/substrate/v1/embeddings/fetch` serves under its own gate.
1416
+ */
1417
+ const CLUSTER_FIELDS = {
1418
+ id: scalar$1("string"),
1419
+ shortId: scalar$1("number"),
1420
+ memberCount: scalar$1("number"),
1421
+ departedCount: scalar$1("number"),
1422
+ cohesion: scalar$1("number"),
1423
+ label: scalar$1("string"),
1424
+ labelledBy: scalar$1("string"),
1425
+ provenance: scalar$1("json"),
1426
+ formedAt: scalar$1("date"),
1427
+ lastAccretedAt: scalar$1("date"),
1428
+ retiredAt: scalar$1("date")
1429
+ };
1430
+ const CLUSTER_MEMBER_FIELDS = {
1431
+ id: scalar$1("string"),
1432
+ shortId: scalar$1("number"),
1433
+ cluster: scalar$1("string"),
1434
+ memberNs: scalar$1("string"),
1435
+ memberType: scalar$1("string"),
1436
+ memberId: scalar$1("string"),
1437
+ origin: scalar$1("string"),
1438
+ similarity: scalar$1("number"),
1439
+ attachedAt: scalar$1("date"),
1440
+ departedAt: scalar$1("date")
1441
+ };
1442
+ function bad$1(message) {
1443
+ throw new ResolverFrameError("bad_request", message);
1444
+ }
1445
+ /** Mirror of `frame-surface.ts`'s projectHit — same strip-all semantics. */
1446
+ function project(row, fields) {
1447
+ if (fields === void 0) return row;
1448
+ const keep = Object.entries(fields).filter(([, v]) => v === true).map(([k]) => k);
1449
+ const out = {};
1450
+ for (const k of keep) if (k in row) out[k] = row[k];
1451
+ return out;
1452
+ }
1453
+ /**
1454
+ * `counts` overrides the record's own `memberCount`/`departedCount` — see
1455
+ * `resolveClusterVisibility`: policy-filtered when a read policy is wired,
1456
+ * otherwise identical to the record's stored counts.
1457
+ */
1458
+ function clusterRow(c, counts) {
1459
+ return {
1460
+ id: c.id,
1461
+ shortId: c.shortId,
1462
+ memberCount: counts.memberCount,
1463
+ departedCount: counts.departedCount,
1464
+ cohesion: c.cohesion,
1465
+ label: counts.labelReadable ? c.label : null,
1466
+ labelledBy: c.labelledBy,
1467
+ provenance: c.provenance,
1468
+ formedAt: c.formedAt,
1469
+ lastAccretedAt: c.lastAccretedAt,
1470
+ retiredAt: c.retiredAt
1471
+ };
1472
+ }
1473
+ function memberRow(m) {
1474
+ return {
1475
+ id: m.id,
1476
+ shortId: m.shortId,
1477
+ cluster: m.clusterId,
1478
+ memberNs: m.memberNs,
1479
+ memberType: m.memberType,
1480
+ memberId: m.memberId,
1481
+ origin: m.origin,
1482
+ similarity: m.similarity,
1483
+ attachedAt: m.attachedAt,
1484
+ departedAt: m.departedAt
1485
+ };
1486
+ }
1487
+ function rethrowCoded$1(err) {
1488
+ const code = err?.code;
1489
+ const message = err instanceof Error ? err.message : String(err);
1490
+ if (code === "policy_denied" || code === "bad_request" || code === "crystallise_in_flight") throw new ResolverFrameError(code, message);
1491
+ throw err;
1492
+ }
1493
+ /**
1494
+ * Returns whether `record` is visible to this caller, plus its
1495
+ * policy-filtered `memberCount` / `departedCount`. Shared by `clusterResolver`
1496
+ * (silent filter) and `labelClusterResolver` (loud denial).
1497
+ *
1498
+ * Visible if the caller can read at least one LIVE member's
1499
+ * `(memberNs, memberType)` scope, or if there are no live members (nothing
1500
+ * left to leak). Without `checkReadPolicy`, always visible with stored counts
1501
+ * and no member query. One `listMembers({ includeDeparted: true })` call
1502
+ * answers both visibility and counts; `check` is cached per scope.
1503
+ */
1504
+ async function resolveClusterVisibility(record, deps, ctx) {
1505
+ if (deps.checkReadPolicy === void 0) return {
1506
+ visible: true,
1507
+ memberCount: record.memberCount,
1508
+ departedCount: record.departedCount,
1509
+ labelReadable: true
1510
+ };
1511
+ const members = await deps.clusters.listMembers(record.id, { includeDeparted: true });
1512
+ const readable = await readableMembers(members, deps, ctx);
1513
+ let liveTotal = 0;
1514
+ let memberCount = 0;
1515
+ let departedCount = 0;
1516
+ let labelReadable = true;
1517
+ for (const m of members) {
1518
+ const canRead = readable.has(m);
1519
+ if (!canRead) labelReadable = false;
1520
+ if (m.departedAt === null) {
1521
+ liveTotal++;
1522
+ if (canRead) memberCount++;
1523
+ } else if (canRead) departedCount++;
1524
+ }
1525
+ return {
1526
+ visible: liveTotal === 0 || memberCount > 0,
1527
+ memberCount,
1528
+ departedCount,
1529
+ labelReadable
1530
+ };
1531
+ }
1532
+ /**
1533
+ * The members this caller can read: their scope's read policy allows them,
1534
+ * and its row filters admit the member's stored row body.
1535
+ */
1536
+ async function readableMembers(members, deps, ctx) {
1537
+ const check = deps.checkReadPolicy;
1538
+ if (check === void 0) return new Set(members);
1539
+ const refs = members.map((m) => ({
1540
+ namespace: m.memberNs,
1541
+ type: m.memberType,
1542
+ id: m.memberId,
1543
+ member: m
1544
+ }));
1545
+ const caller = callerFromContext(ctx);
1546
+ const kept = await visibleRefs(refs, (ns, type) => check(ns, type, caller.identity, caller), caller, deps.embeddings, deps.model);
1547
+ return new Set(kept.map((r) => r.member));
1548
+ }
1549
+ function buildClusterSurface(deps) {
1550
+ const guard = deps.guard ?? createCrystalliseGuard();
1551
+ const clusterResolver = async (ctx, args) => {
1552
+ const p = args.params ?? {};
1553
+ if (p.includeRetired !== void 0 && typeof p.includeRetired !== "boolean") bad$1("\"includeRetired\" must be a boolean");
1554
+ if (typeof p.id === "string") {
1555
+ const one = await deps.clusters.getCluster(p.id);
1556
+ if (one === null) return [];
1557
+ const vis = await resolveClusterVisibility(one, deps, ctx);
1558
+ if (!vis.visible) return [];
1559
+ return [project(clusterRow(one, vis), args.fields)];
1560
+ }
1561
+ const rows = await deps.clusters.listClusters(p.includeRetired === true ? { includeRetired: true } : {});
1562
+ const visible = [];
1563
+ for (const c of rows) {
1564
+ const vis = await resolveClusterVisibility(c, deps, ctx);
1565
+ if (vis.visible) visible.push(project(clusterRow(c, vis), args.fields));
1566
+ }
1567
+ return visible;
1568
+ };
1569
+ const memberResolver = async (ctx, args) => {
1570
+ const p = args.params ?? {};
1571
+ const readable = async (rows) => {
1572
+ const keep = await readableMembers(rows, deps, ctx);
1573
+ return rows.filter((m) => keep.has(m));
1574
+ };
1575
+ if (typeof p.cluster === "string") return (await readable(await deps.clusters.listMembers(p.cluster, p.includeDeparted === true ? { includeDeparted: true } : {}))).map((m) => project(memberRow(m), args.fields));
1576
+ if (typeof p.memberNs === "string" && typeof p.memberType === "string" && typeof p.memberId === "string") return (await readable(await deps.clusters.findClustersForMember({
1577
+ namespace: p.memberNs,
1578
+ type: p.memberType,
1579
+ id: p.memberId
1580
+ }))).map((m) => project(memberRow(m), args.fields));
1581
+ bad$1("recall/ClusterMember requires either \"cluster\" or the full (\"memberNs\", \"memberType\", \"memberId\") triple");
1582
+ };
1583
+ const crystalliseResolver = async (ctx, args) => {
1584
+ const bound = bindPolicy(deps.checkReadPolicy, callerFromContext(ctx));
1585
+ try {
1586
+ const input = validateCrystalliseInput(args.params);
1587
+ return {
1588
+ id: "crystallise",
1589
+ ...await guard.runExclusive(() => handleCrystallise(input, {
1590
+ embeddings: deps.embeddings,
1591
+ clusters: deps.clusters,
1592
+ model: deps.model,
1593
+ config: deps.config,
1594
+ ...deps.runClusterer !== void 0 ? { runClusterer: deps.runClusterer } : {},
1595
+ ...deps.rowsMissing !== void 0 ? { rowsMissing: deps.rowsMissing } : {},
1596
+ ...bound !== void 0 ? { checkReadPolicy: bound } : {},
1597
+ caller: callerFromContext(ctx)
1598
+ }))
1599
+ };
1600
+ } catch (err) {
1601
+ rethrowCoded$1(err);
1602
+ }
1603
+ };
1604
+ const labelClusterResolver = async (ctx, args) => {
1605
+ const p = args.params ?? {};
1606
+ if (typeof p.id !== "string" || p.id.length === 0) bad$1("\"id\" must be a non-empty string");
1607
+ if (typeof p.label !== "string" || p.label.trim().length === 0) bad$1("\"label\" must be a non-empty string");
1608
+ const before = await deps.clusters.getCluster(p.id);
1609
+ if (before === null) bad$1(`no cluster with id '${p.id}'`);
1610
+ const preVis = await resolveClusterVisibility(before, deps, ctx);
1611
+ if (!preVis.visible) throw new ResolverFrameError("policy_denied", `read policy denies cluster '${p.id}'`);
1612
+ const updated = await deps.clusters.relabel(p.id, p.label.trim());
1613
+ if (updated === null) bad$1(`no cluster with id '${p.id}'`);
1614
+ return clusterRow(updated, {
1615
+ ...preVis,
1616
+ labelReadable: true
1617
+ });
1618
+ };
1619
+ return {
1620
+ types: {
1621
+ Cluster: {
1622
+ fields: CLUSTER_FIELDS,
1623
+ resolver: clusterResolver
1624
+ },
1625
+ ClusterMember: {
1626
+ fields: CLUSTER_MEMBER_FIELDS,
1627
+ resolver: memberResolver
1628
+ }
1629
+ },
1630
+ mutations: {
1631
+ crystallise: { resolver: crystalliseResolver },
1632
+ labelCluster: { resolver: labelClusterResolver }
1633
+ }
1634
+ };
1635
+ }
1636
+
1637
+ //#endregion
1638
+ //#region ../../plugins/substrate-recall/src/crystallise-route.ts
1639
+ /**
1640
+ * POST /substrate/v1/crystallise — cluster embedded rows into first-class rows with
1641
+ * provenance.
1642
+ *
1643
+ * There is deliberately no schedule: the CALLER decides when to crystallise,
1644
+ * because *when* is policy and recall owns only the mechanism.
1645
+ *
1646
+ * READ-POLICY GATE: clustering reads row bodies and vectors across whole
1647
+ * scopes, so it uses the same `ReadPolicyCheck` as recall, fetch and boost.
1648
+ * Denial is LOUD: the caller named explicit scopes, so a denied scope fails
1649
+ * the whole request 403.
1650
+ *
1651
+ * CONCURRENCY: a second crystallise while one is in flight is refused with
1652
+ * 409 rather than queued, since concurrent passes would form duplicate
1653
+ * clusters. The exclusion lives in `crystallise-guard.ts`, not here, because
1654
+ * the `recall/crystallise` frame mutation reaches the same core and must share
1655
+ * the guard instance.
1656
+ */
1657
+ const UNAVAILABLE_MESSAGE = "crystallise unavailable: no ClusterStore is wired (recall was composed without one).";
1658
+ function parseBody$2(req) {
1659
+ const raw = req.body;
1660
+ if (raw === null || Buffer.isBuffer(raw) && raw.length === 0) return { error: "request body is required" };
1661
+ try {
1662
+ return { ok: JSON.parse(Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw)) };
1663
+ } catch (err) {
1664
+ return { error: err instanceof Error ? err.message : "invalid JSON" };
1665
+ }
1666
+ }
1667
+ function crystalliseRouteHandler(cfg) {
1668
+ const guard = cfg.guard ?? createCrystalliseGuard();
1669
+ return async (req) => {
1670
+ const clusters = cfg.clusters;
1671
+ if (clusters === void 0) return jsonResponse(503, { error: {
1672
+ code: "crystallise_unavailable",
1673
+ message: UNAVAILABLE_MESSAGE
1674
+ } });
1675
+ const parsed = parseBody$2(req);
1676
+ if ("error" in parsed) return jsonResponse(400, {
1677
+ code: "bad_request",
1678
+ message: parsed.error
1679
+ });
1680
+ let input;
1681
+ try {
1682
+ input = validateCrystalliseInput(parsed.ok);
1683
+ } catch (err) {
1684
+ return jsonResponse(400, {
1685
+ code: "bad_request",
1686
+ message: err instanceof Error ? err.message : String(err)
1687
+ });
1688
+ }
1689
+ const bound = bindPolicy(cfg.checkReadPolicy, callerFromRequest(req));
1690
+ try {
1691
+ const out = await guard.runExclusive(() => handleCrystallise(input, {
1692
+ embeddings: cfg.embeddings,
1693
+ clusters,
1694
+ model: cfg.model,
1695
+ config: cfg.config,
1696
+ ...cfg.runClusterer !== void 0 ? { runClusterer: cfg.runClusterer } : {},
1697
+ ...cfg.rowsMissing !== void 0 ? { rowsMissing: cfg.rowsMissing } : {},
1698
+ ...bound !== void 0 ? { checkReadPolicy: bound } : {},
1699
+ caller: callerFromRequest(req)
1700
+ }));
1701
+ return jsonResponse(200, out);
1702
+ } catch (err) {
1703
+ const code = err?.code;
1704
+ const message = err instanceof Error ? err.message : String(err);
1705
+ if (code === "policy_denied") return jsonResponse(403, { error: {
1706
+ code: "policy_denied",
1707
+ message
1708
+ } });
1709
+ if (code === "bad_request") return jsonResponse(400, {
1710
+ code: "bad_request",
1711
+ message
1712
+ });
1713
+ if (code === "crystallise_in_flight") return jsonResponse(409, { error: {
1714
+ code: CRYSTALLISE_IN_FLIGHT_CODE,
1715
+ message
1716
+ } });
1717
+ process.stderr.write(`crystallise route failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
1718
+ return jsonResponse(500, { error: {
1719
+ code: "internal",
1720
+ message: "crystallise failed"
1721
+ } });
1722
+ }
1723
+ };
1724
+ }
1725
+
1726
+ //#endregion
1727
+ //#region ../../plugins/substrate-recall/src/embed-and-store.ts
1728
+ const LOG_PREFIX$1 = "substrate-recall.embed:";
1729
+ /**
1730
+ * Embed one row and return what happened, without touching stats or stderr.
1731
+ * Never throws: failures come back as `{ status: 'failed' }`.
1732
+ */
1733
+ async function embedRowReporting(row, opts) {
1734
+ const id = typeof row.id === "string" ? row.id : typeof row.id === "number" ? String(row.id) : null;
1735
+ if (id === null) return { status: "no-id" };
1736
+ const now = /* @__PURE__ */ new Date();
1737
+ try {
1738
+ let source;
1739
+ if (opts.serializeRow) source = await opts.serializeRow(row);
1740
+ else if (opts.fields && opts.fields.length > 0) source = opts.fields.map((f) => row[f]).filter((v) => typeof v === "string" && v.length > 0).join("\n");
1741
+ else source = "";
1742
+ if (source === null || source === void 0) {
1743
+ await opts.store.delete({
1744
+ rowNamespace: opts.namespace,
1745
+ rowType: opts.type,
1746
+ rowId: id
1747
+ });
1748
+ return { status: "unindexable" };
1749
+ }
1750
+ const vector = await opts.embedder.embed(source);
1751
+ await opts.store.upsert({
1752
+ rowNamespace: opts.namespace,
1753
+ rowType: opts.type,
1754
+ rowId: id,
1755
+ vector,
1756
+ model: opts.embedder.modelId,
1757
+ now
1758
+ });
1759
+ return { status: "embedded" };
1760
+ } catch (err) {
1761
+ const error = err instanceof Error ? err.message : String(err);
1762
+ const code = embedErrorCode(err);
1763
+ return code === void 0 ? {
1764
+ status: "failed",
1765
+ error
1766
+ } : {
1767
+ status: "failed",
1768
+ error,
1769
+ code
1770
+ };
1771
+ }
1772
+ }
1773
+ /**
1774
+ * The code of an `EmbedError`, matched by name rather than `instanceof` so a
1775
+ * second copy of substrate-embedder in the tree still matches.
1776
+ */
1777
+ function embedErrorCode(err) {
1778
+ if (!(err instanceof Error) || err.name !== "EmbedError") return void 0;
1779
+ const code = err.code;
1780
+ return code === "unavailable" || code === "invalid_response" ? code : void 0;
1781
+ }
1782
+ async function embedAndStore(row, opts) {
1783
+ const outcome = await embedRowReporting(row, opts);
1784
+ switch (outcome.status) {
1785
+ case "embedded":
1786
+ opts.stats?.recordSuccess();
1787
+ return;
1788
+ case "unindexable":
1789
+ opts.stats?.recordSkip();
1790
+ return;
1791
+ case "no-id": return;
1792
+ case "failed": {
1793
+ const id = typeof row.id === "string" ? row.id : "<no-id>";
1794
+ process.stderr.write(`${LOG_PREFIX$1} failed to embed ${opts.type} id=${id}: ${outcome.error}\n`);
1795
+ opts.stats?.recordFailure(id, outcome.error);
1796
+ return;
1797
+ }
1798
+ }
1799
+ }
1800
+ function bindingToOptions(args) {
1801
+ const ctx = args.embedSourceContext;
1802
+ return {
1803
+ namespace: args.namespace,
1804
+ type: args.type,
1805
+ serializeRow: (r) => args.source(r, ctx),
1806
+ embedder: args.embedder,
1807
+ store: args.store,
1808
+ ...args.stats !== void 0 ? { stats: args.stats } : {}
1809
+ };
1810
+ }
1811
+ /**
1812
+ * Wrap `embedAndStore` into a PostWriteHook that embeds every successfully
1813
+ * written row. Never throws, so it cannot break the postWrite chain.
1814
+ */
1815
+ function makeEmbedPostWrite(args) {
1816
+ return async (row, _ctx) => {
1817
+ await embedAndStore(row, bindingToOptions(args));
1818
+ };
1819
+ }
1820
+ /**
1821
+ * Returns a re-embed function built from the same binding as
1822
+ * `makeEmbedPostWrite`, so a backfill writes the same vector the write path
1823
+ * would. Reports each outcome instead of swallowing errors.
1824
+ */
1825
+ function makeReembed(args) {
1826
+ return async (row) => embedRowReporting(row, bindingToOptions(args));
1827
+ }
1828
+
1829
+ //#endregion
1830
+ //#region ../../plugins/substrate-recall/src/embed-source-registry.ts
1831
+ var EmbedSourceRegistry = class {
1832
+ #byKey = /* @__PURE__ */ new Map();
1833
+ /**
1834
+ * Register one embedded type. Idempotent on (namespace, type) — a re-install
1835
+ * overwrites rather than duplicating, because the LATEST registration
1836
+ * reflects the currently-composed namespace definition.
1837
+ */
1838
+ add(entry) {
1839
+ this.#byKey.set(`${entry.namespace}/${entry.type}`, entry);
1840
+ }
1841
+ /** The hook for one type, or undefined when the type carries no `embed.source`. */
1842
+ get(namespace, type) {
1843
+ return this.#byKey.get(`${namespace}/${type}`);
1844
+ }
1845
+ /** Every embedded type, sorted by (namespace, type) so audit runs diff cleanly. */
1846
+ types() {
1847
+ return [...this.#byKey.values()].map(({ namespace, type }) => ({
1848
+ namespace,
1849
+ type
1850
+ })).sort((a, b) => a.namespace.localeCompare(b.namespace) || a.type.localeCompare(b.type));
1851
+ }
1852
+ size() {
1853
+ return this.#byKey.size;
1854
+ }
1855
+ };
1856
+
1857
+ //#endregion
1858
+ //#region ../../plugins/substrate-recall/src/embed-stats.ts
1859
+ /**
1860
+ * Build a fresh EmbedStats instance. Each `createRecallPlugin(...)` call
1861
+ * gets its own counter unless one is supplied.
1862
+ */
1863
+ function createEmbedStats(now = () => /* @__PURE__ */ new Date()) {
1864
+ const since = now().toISOString();
1865
+ let writes = 0;
1866
+ let successes = 0;
1867
+ let failures = 0;
1868
+ let skips = 0;
1869
+ let expansionFailures = 0;
1870
+ let lastFailure = null;
1871
+ return {
1872
+ recordSuccess() {
1873
+ writes++;
1874
+ successes++;
1875
+ },
1876
+ recordFailure(rowId, error) {
1877
+ writes++;
1878
+ failures++;
1879
+ lastFailure = {
1880
+ rowId,
1881
+ error,
1882
+ at: now().toISOString()
1883
+ };
1884
+ },
1885
+ recordSkip() {
1886
+ writes++;
1887
+ skips++;
1888
+ },
1889
+ recordExpansionFailure() {
1890
+ expansionFailures++;
1891
+ },
1892
+ snapshot() {
1893
+ return {
1894
+ since,
1895
+ writes,
1896
+ successes,
1897
+ failures,
1898
+ skips,
1899
+ lastFailure,
1900
+ expansionFailures
1901
+ };
1902
+ }
1903
+ };
1904
+ }
1905
+
1906
+ //#endregion
1907
+ //#region ../../plugins/substrate-recall/src/lexical-coverage-core.ts
1908
+ /** Page size for the internal scan. Matches LEXICAL_REINDEX_DEFAULT_LIMIT. */
1909
+ const LEXICAL_COVERAGE_PAGE_LIMIT = 500;
1910
+ function fail$2(code, message) {
1911
+ throw Object.assign(new Error(message), { code });
1912
+ }
1913
+ function validateLexicalCoverageInput(raw) {
1914
+ if (raw === null || raw === void 0) return {};
1915
+ if (typeof raw !== "object" || Array.isArray(raw)) fail$2("bad_request", "coverage filter must be an object with optional namespace + type");
1916
+ const obj = raw;
1917
+ const out = {};
1918
+ if (obj.namespace !== void 0) {
1919
+ if (typeof obj.namespace !== "string" || obj.namespace.length === 0) fail$2("bad_request", "coverage namespace must be a non-empty string");
1920
+ out.namespace = obj.namespace;
1921
+ }
1922
+ if (obj.type !== void 0) {
1923
+ if (typeof obj.type !== "string" || obj.type.length === 0) fail$2("bad_request", "coverage type must be a non-empty string");
1924
+ out.type = obj.type;
1925
+ }
1926
+ if (out.namespace === void 0 !== (out.type === void 0)) fail$2("bad_request", "coverage namespace and type must be given together");
1927
+ return out;
1928
+ }
1929
+ async function handleLexicalCoverage(input, deps) {
1930
+ if (deps.resolveDataset === void 0) fail$2("unavailable", "no dataset resolver is wired; cannot scan rows for coverage");
1931
+ const targets = input.namespace !== void 0 && input.type !== void 0 ? [{
1932
+ namespace: input.namespace,
1933
+ type: input.type
1934
+ }] : deps.registry.types().map((t) => ({
1935
+ namespace: t.namespace,
1936
+ type: t.type
1937
+ }));
1938
+ const types = [];
1939
+ for (const target of targets) {
1940
+ const entry = deps.registry.get(target.namespace, target.type);
1941
+ if (entry === void 0) {
1942
+ const known = deps.registry.types().map((t) => `${t.namespace}/${t.type}`).join(", ");
1943
+ fail$2("unknown_type", `${target.namespace}/${target.type} declares no lexical.source; lexically-indexed types are: ${known === "" ? "(none)" : known}`);
1944
+ }
1945
+ const indexed = await deps.lexicalStore.countIndexed(target.namespace, target.type);
1946
+ if (entry.classify === void 0) {
1947
+ types.push({
1948
+ namespace: target.namespace,
1949
+ type: target.type,
1950
+ scanned: 0,
1951
+ indexed,
1952
+ unindexable: null,
1953
+ failed: 0
1954
+ });
1955
+ continue;
1956
+ }
1957
+ const dataset = deps.resolveDataset(target.namespace);
1958
+ if (dataset === null) fail$2("unknown_type", `no dataset is registered for namespace ${target.namespace}`);
1959
+ let scanned = 0;
1960
+ let unindexable = 0;
1961
+ let failed = 0;
1962
+ let cursor;
1963
+ for (;;) {
1964
+ const page = await dataset.read(target.type, {
1965
+ limit: 500,
1966
+ ...cursor !== void 0 ? { cursor } : {}
1967
+ });
1968
+ for (const row of page.rows) {
1969
+ scanned++;
1970
+ switch ((await entry.classify(row)).status) {
1971
+ case "indexable": break;
1972
+ case "unindexable":
1973
+ unindexable++;
1974
+ break;
1975
+ case "no-id":
1976
+ case "failed": failed++;
1977
+ }
1978
+ }
1979
+ if (!page.hasMore) break;
1980
+ cursor = page.nextCursor;
1981
+ }
1982
+ types.push({
1983
+ namespace: target.namespace,
1984
+ type: target.type,
1985
+ scanned,
1986
+ indexed,
1987
+ unindexable,
1988
+ failed
1989
+ });
1990
+ }
1991
+ return { types };
1992
+ }
1993
+
1994
+ //#endregion
1995
+ //#region ../../plugins/substrate-recall/src/embed-stats-route.ts
1996
+ /**
1997
+ * `GET /substrate/v1/embed-stats` — read the in-memory counter that observes
1998
+ * embed write outcomes.
1999
+ *
2000
+ * Returns the snapshot shape directly, plus an `enabled` flag so callers
2001
+ * can distinguish "recall wasn't configured" from "configured but no
2002
+ * failures yet" (both render as zero-count). Counts reset on plugin
2003
+ * restart.
2004
+ *
2005
+ * `handleEmbedStatsRequest` is the pure data handler; `embedStatsRouteHandler`
2006
+ * wraps it as an `HttpHandler` for a `KernelRouteClaim`.
2007
+ */
2008
+ function emptySnapshot() {
2009
+ return {
2010
+ since: (/* @__PURE__ */ new Date(0)).toISOString(),
2011
+ writes: 0,
2012
+ successes: 0,
2013
+ failures: 0,
2014
+ skips: 0,
2015
+ lastFailure: null,
2016
+ expansionFailures: 0
2017
+ };
2018
+ }
2019
+ /**
2020
+ * Pure handler. Inputs are the optional stats instance, source registries and
2021
+ * composition facts; output is the JSON body shape (without coverage).
2022
+ */
2023
+ function handleEmbedStatsRequest(stats, registry, lexicalRegistry, composition) {
2024
+ return {
2025
+ ...stats?.snapshot() ?? emptySnapshot(),
2026
+ enabled: stats !== void 0,
2027
+ embeddedTypes: registry?.types() ?? [],
2028
+ ...lexicalRegistry !== void 0 ? { lexicalTypes: lexicalRegistry.types() } : {},
2029
+ ...composition?.lexicalEnabled !== void 0 ? { lexicalEnabled: composition.lexicalEnabled } : {}
2030
+ };
2031
+ }
2032
+ /**
2033
+ * KernelRouteClaim handler factory.
2034
+ *
2035
+ * Returns an `HttpHandler` that serialises the current embed stats snapshot
2036
+ * as JSON. Pass to `KernelRouteClaim.handler` when building the substrate
2037
+ * plugin's `kernelRoutes` array.
2038
+ *
2039
+ * @example
2040
+ * ```ts
2041
+ * kernelRoutes: [
2042
+ * { path: 'embed-stats', method: 'GET', handler: embedStatsRouteHandler(stats) }
2043
+ * ]
2044
+ * ```
2045
+ */
2046
+ function embedStatsRouteHandler(stats, registry, lexicalRegistry, composition) {
2047
+ return (req) => {
2048
+ const base = handleEmbedStatsRequest(stats, registry, lexicalRegistry, composition);
2049
+ if (!wantsCoverage(req)) return jsonResponse(200, base);
2050
+ return coverageResponse(base, lexicalRegistry, composition);
2051
+ };
2052
+ }
2053
+ async function coverageResponse(base, lexicalRegistry, composition) {
2054
+ const coverageDeps = toCoverageDeps(lexicalRegistry, composition);
2055
+ if (coverageDeps === null) return jsonResponse(503, { error: {
2056
+ code: "unavailable",
2057
+ message: "lexical coverage needs a lexical store and a dataset resolver; one is not wired"
2058
+ } });
2059
+ try {
2060
+ const coverage = await handleLexicalCoverage({}, coverageDeps);
2061
+ return jsonResponse(200, {
2062
+ ...base,
2063
+ lexicalCoverage: coverage.types
2064
+ });
2065
+ } catch (err) {
2066
+ const code = err?.code;
2067
+ const message = err instanceof Error ? err.message : String(err);
2068
+ if (code === "unknown_type") return jsonResponse(400, { error: {
2069
+ code,
2070
+ message
2071
+ } });
2072
+ if (code === "unavailable") return jsonResponse(503, { error: {
2073
+ code,
2074
+ message
2075
+ } });
2076
+ process.stderr.write(`embed-stats coverage failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
2077
+ return jsonResponse(500, { error: {
2078
+ code: "internal",
2079
+ message: "lexical coverage failed"
2080
+ } });
2081
+ }
2082
+ }
2083
+ /** `?coverage=true` (or `?coverage=1`) opts into the per-type dry-run scan. Absent/false → stats only. */
2084
+ function wantsCoverage(req) {
2085
+ return req.query?.coverage === "true" || req.query?.coverage === "1";
2086
+ }
2087
+ function toCoverageDeps(lexicalRegistry, composition) {
2088
+ if (lexicalRegistry === void 0 || composition?.lexicalStore === void 0 || composition?.resolveDataset === void 0) return null;
2089
+ return {
2090
+ registry: lexicalRegistry,
2091
+ lexicalStore: composition.lexicalStore,
2092
+ resolveDataset: composition.resolveDataset
2093
+ };
2094
+ }
2095
+
2096
+ //#endregion
2097
+ //#region ../../plugins/substrate-recall/src/embeddings-fetch-core.ts
2098
+ /**
2099
+ * Per-request ref cap. Bounds both the response payload and the store's
2100
+ * batched lookup.
2101
+ */
2102
+ const EMBEDDINGS_FETCH_MAX_REFS = 500;
2103
+ function badRequest$1(message) {
2104
+ throw Object.assign(new Error(message), { code: "bad_request" });
2105
+ }
2106
+ /**
2107
+ * Validate + normalise a raw fetch payload into an `EmbeddingsFetchInput`.
2108
+ * Throws `{ code: 'bad_request' }` on any shape/cap violation.
2109
+ */
2110
+ function validateFetchInput(raw) {
2111
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) badRequest$1("request body must be a JSON object");
2112
+ const obj = raw;
2113
+ if (!Array.isArray(obj.refs) || obj.refs.length === 0) badRequest$1("\"refs\" must be a non-empty array of { namespace, type, id }");
2114
+ if (obj.refs.length > 500) badRequest$1(`"refs" exceeds the per-request cap of ${500}`);
2115
+ const refs = [];
2116
+ for (const r of obj.refs) {
2117
+ if (r === null || typeof r !== "object") badRequest$1("each ref must be an object with string namespace, type, id");
2118
+ const { namespace, type, id } = r;
2119
+ if (typeof namespace !== "string" || typeof type !== "string" || typeof id !== "string") badRequest$1("each ref must be an object with string namespace, type, id");
2120
+ refs.push({
2121
+ namespace,
2122
+ type,
2123
+ id
2124
+ });
2125
+ }
2126
+ if (obj.model !== void 0 && typeof obj.model !== "string") badRequest$1("\"model\" must be a string");
2127
+ if (obj.boost !== void 0 && typeof obj.boost !== "boolean") badRequest$1("\"boost\" must be a boolean");
2128
+ return {
2129
+ refs,
2130
+ ...obj.model !== void 0 ? { model: obj.model } : {},
2131
+ ...obj.boost !== void 0 ? { boost: obj.boost } : {}
2132
+ };
2133
+ }
2134
+ /**
2135
+ * Fetch stored embeddings for the named refs. Resolves the model (explicit
2136
+ * input → embedder default → `bad_request`), gates each distinct
2137
+ * (namespace, type) scope once against the bound read policy (first denial
2138
+ * throws `policy_denied` naming the scope), then runs one batched store
2139
+ * lookup. Returns `{ vectors, model }`; refs without an embedding under the
2140
+ * resolved model are silently absent (store contract).
2141
+ *
2142
+ * With `boost: true`, the returned rows are reinforced fire-and-forget, so
2143
+ * `_salience` on the response is the value before this call, not after.
2144
+ */
2145
+ async function handleEmbeddingsFetch(input, deps) {
2146
+ const checkReadPolicy = memoCheck(deps.checkReadPolicy);
2147
+ const model = input.model ?? deps.embedder?.modelId;
2148
+ if (model === void 0) badRequest$1("\"model\" is required when no embedder is configured");
2149
+ if (checkReadPolicy !== void 0) {
2150
+ const seen = /* @__PURE__ */ new Set();
2151
+ for (const r of input.refs) {
2152
+ const scope = `${r.namespace}/${r.type}`;
2153
+ if (seen.has(scope)) continue;
2154
+ seen.add(scope);
2155
+ const decision = checkReadPolicy(r.namespace, r.type);
2156
+ if (!decision.allow) throw Object.assign(/* @__PURE__ */ new Error(`${scope}: ${decision.reason ?? "policy denied"}`), { code: "policy_denied" });
2157
+ }
2158
+ }
2159
+ const fetched = visibleRows(await deps.store.fetchEmbeddings(input.refs, model), checkReadPolicy, deps.caller);
2160
+ if (input.boost === true && fetched.length > 0) {
2161
+ const writable = /* @__PURE__ */ new Map();
2162
+ const targets = fetched.filter((f) => {
2163
+ const scope = `${f.namespace}/${f.type}`;
2164
+ const cached = writable.get(scope);
2165
+ if (cached !== void 0) return cached;
2166
+ const allow = deps.checkWritePolicy?.(f.namespace, f.type).allow ?? false;
2167
+ writable.set(scope, allow);
2168
+ return allow;
2169
+ }).map((f) => ({
2170
+ namespace: f.namespace,
2171
+ type: f.type,
2172
+ id: f.id
2173
+ }));
2174
+ if (targets.length > 0) {
2175
+ const halfLifeHours = (deps.salience ?? DEFAULT_SALIENCE_CONFIG).halfLifeHours;
2176
+ deps.store.boostSalience(targets, halfLifeHours).catch((err) => {
2177
+ const msg = err instanceof Error ? err.message : String(err);
2178
+ process.stderr.write(`embeddings-fetch boostSalience failure: ${msg}\n`);
2179
+ });
2180
+ }
2181
+ }
2182
+ return {
2183
+ vectors: fetched.map((f) => ({
2184
+ namespace: f.namespace,
2185
+ type: f.type,
2186
+ id: f.id,
2187
+ row: f.row,
2188
+ vector: Array.from(f.vector),
2189
+ _salience: f.salience
2190
+ })),
2191
+ model
2192
+ };
2193
+ }
2194
+
2195
+ //#endregion
2196
+ //#region ../../plugins/substrate-recall/src/embeddings-fetch-route.ts
2197
+ /**
2198
+ * POST /substrate/v1/embeddings/fetch — thin HTTP exposure of
2199
+ * `EmbeddingsStore.fetchEmbeddings`: callers name explicit (namespace, type,
2200
+ * id) refs and get row bodies joined to stored vectors. Refs without an
2201
+ * embedding under the resolved model are silently absent.
2202
+ *
2203
+ * Raw vectors leak content geometry, so the route applies the same read
2204
+ * policy as /substrate/v1/recall. Any denied scope fails the whole request with 403
2205
+ * `policy_denied`: the caller named explicit refs, so a silent empty result
2206
+ * would hide an actionable error.
2207
+ *
2208
+ * With `boost: true`, the returned rows are reinforced, gated by write policy.
2209
+ */
2210
+ function parseBody$1(req) {
2211
+ const raw = req.body;
2212
+ if (raw === null || Buffer.isBuffer(raw) && raw.length === 0) return { error: "request body is required" };
2213
+ try {
2214
+ return { ok: JSON.parse(Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw)) };
2215
+ } catch (err) {
2216
+ return { error: err instanceof Error ? err.message : "invalid JSON" };
2217
+ }
2218
+ }
2219
+ /**
2220
+ * KernelRouteClaim handler factory for `POST /substrate/v1/embeddings/fetch`.
2221
+ * Registered by `createRecallPlugin` alongside the recall route. Thin
2222
+ * transport adapter over `handleEmbeddingsFetch` — JSON-parse + bind identity,
2223
+ * then map coded throws (bad_request → 400, policy_denied → 403) to envelopes.
2224
+ */
2225
+ function embeddingsFetchRouteHandler(cfg) {
2226
+ return async (req) => {
2227
+ const parsed = parseBody$1(req);
2228
+ if ("error" in parsed) return jsonResponse(400, {
2229
+ code: "bad_request",
2230
+ message: parsed.error
2231
+ });
2232
+ let input;
2233
+ try {
2234
+ input = validateFetchInput(parsed.ok);
2235
+ } catch (err) {
2236
+ return jsonResponse(400, {
2237
+ code: "bad_request",
2238
+ message: err instanceof Error ? err.message : String(err)
2239
+ });
2240
+ }
2241
+ const unbound = cfg.checkReadPolicy;
2242
+ const unboundWrite = cfg.checkWritePolicy;
2243
+ const caller = callerFromRequest(req);
2244
+ try {
2245
+ const out = await handleEmbeddingsFetch(input, {
2246
+ store: cfg.store,
2247
+ ...cfg.embedder !== void 0 ? { embedder: cfg.embedder } : {},
2248
+ ...cfg.salience !== void 0 ? { salience: cfg.salience } : {},
2249
+ ...unbound !== void 0 ? { checkReadPolicy: bindPolicy(unbound, caller) } : {},
2250
+ ...unboundWrite !== void 0 ? { checkWritePolicy: bindPolicy(unboundWrite, caller) } : {},
2251
+ caller
2252
+ });
2253
+ return jsonResponse(200, out);
2254
+ } catch (err) {
2255
+ const code = err?.code;
2256
+ const message = err instanceof Error ? err.message : String(err);
2257
+ if (code === "bad_request") return jsonResponse(400, {
2258
+ code: "bad_request",
2259
+ message
2260
+ });
2261
+ if (code === "policy_denied") return jsonResponse(403, { error: {
2262
+ code: "policy_denied",
2263
+ message
2264
+ } });
2265
+ process.stderr.write(`embeddings-fetch route failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
2266
+ return jsonResponse(500, { error: {
2267
+ code: "internal",
2268
+ message: "embeddings fetch failed"
2269
+ } });
2270
+ }
2271
+ };
2272
+ }
2273
+
2274
+ //#endregion
2275
+ //#region ../../plugins/substrate-recall/src/filter-operator.ts
2276
+ function embeddingSimilarOperator(deps) {
2277
+ const { embedder, store } = deps;
2278
+ return {
2279
+ computedFields: ["_score", "_vector"],
2280
+ validate: (value) => {
2281
+ if (typeof value !== "object" || value === null) return {
2282
+ ok: false,
2283
+ reason: "embeddingSimilar value must be an object"
2284
+ };
2285
+ const v = value;
2286
+ if (typeof v.to !== "string" || v.to.length === 0) return {
2287
+ ok: false,
2288
+ reason: "embeddingSimilar.to must be a non-empty string"
2289
+ };
2290
+ if (v.to.length > 8192) return {
2291
+ ok: false,
2292
+ reason: `embeddingSimilar.to is longer than ${MAX_RECALL_QUERY_CHARS} characters`
2293
+ };
2294
+ if (v.threshold !== void 0 && typeof v.threshold !== "number") return {
2295
+ ok: false,
2296
+ reason: "embeddingSimilar.threshold must be a number"
2297
+ };
2298
+ if (v.where !== void 0) {
2299
+ const problem = rowFilterProblem(v.where);
2300
+ if (problem !== null) return {
2301
+ ok: false,
2302
+ reason: `embeddingSimilar.where ${problem}`
2303
+ };
2304
+ }
2305
+ if (v.k !== void 0 && typeof v.k !== "number") return {
2306
+ ok: false,
2307
+ reason: "embeddingSimilar.k must be a number"
2308
+ };
2309
+ if (v.boost !== void 0 && v.boost !== false) return {
2310
+ ok: false,
2311
+ reason: "embeddingSimilar.boost: a query does not boost salience; use POST /substrate/v1/recall or /substrate/v1/salience/boost"
2312
+ };
2313
+ return {
2314
+ ok: true,
2315
+ value: {
2316
+ to: v.to,
2317
+ ...v.threshold !== void 0 ? { threshold: v.threshold } : {},
2318
+ ...v.k !== void 0 ? { k: v.k } : {},
2319
+ ...v.where !== void 0 ? { where: v.where } : {}
2320
+ }
2321
+ };
2322
+ },
2323
+ execute: async (value, context) => {
2324
+ const v = value;
2325
+ const handle = context;
2326
+ if (handle.namespace === void 0 || handle.type === void 0) throw new Error("embeddingSimilar requires operator context context to specify namespace + type");
2327
+ const namespace = handle.namespace;
2328
+ const type = handle.type;
2329
+ const k = Math.min(100, Math.max(1, Math.floor(v.k ?? handle.k ?? 50)));
2330
+ const queryVector = await embedder.embed(v.to);
2331
+ const results = await store.knnSearch({
2332
+ namespace,
2333
+ type,
2334
+ model: embedder.modelId,
2335
+ vector: queryVector,
2336
+ k,
2337
+ ...typeof v.threshold === "number" && v.threshold > 0 ? { threshold: v.threshold } : {},
2338
+ ...handle.returnVector === true ? { returnVector: true } : {},
2339
+ ...v.where !== void 0 ? { rowFilter: v.where } : {}
2340
+ });
2341
+ const hits = [];
2342
+ for (const r of results) {
2343
+ const id = String(r.row.id ?? "");
2344
+ if (id.length === 0) continue;
2345
+ hits.push({
2346
+ id,
2347
+ score: r.score,
2348
+ ...r.vector !== void 0 ? { vector: r.vector } : {}
2349
+ });
2350
+ }
2351
+ return { hits };
2352
+ }
2353
+ };
2354
+ }
2355
+
2356
+ //#endregion
2357
+ //#region ../../plugins/substrate-recall/src/lexical-index.ts
2358
+ const LOG_PREFIX = "substrate-recall.lexical:";
2359
+ /** Index one row and REPORT what happened, without logging. */
2360
+ async function lexicalRowReporting(row, binding) {
2361
+ const id = typeof row.id === "string" ? row.id : null;
2362
+ if (id === null) return { status: "no-id" };
2363
+ const now = /* @__PURE__ */ new Date();
2364
+ try {
2365
+ const text = await binding.source(row);
2366
+ if (text === null || text === void 0) {
2367
+ await binding.store.delete({
2368
+ rowNamespace: binding.namespace,
2369
+ rowType: binding.type,
2370
+ rowId: id
2371
+ });
2372
+ return { status: "unindexable" };
2373
+ }
2374
+ await binding.store.upsert({
2375
+ rowNamespace: binding.namespace,
2376
+ rowType: binding.type,
2377
+ rowId: id,
2378
+ text,
2379
+ now
2380
+ });
2381
+ return { status: "indexed" };
2382
+ } catch (err) {
2383
+ return {
2384
+ status: "failed",
2385
+ error: err instanceof Error ? err.message : String(err)
2386
+ };
2387
+ }
2388
+ }
2389
+ /** Build the post-write hook that keeps one type's lexical index current. */
2390
+ function makeLexicalPostWrite(binding) {
2391
+ return async (row) => {
2392
+ const outcome = await lexicalRowReporting(row, binding);
2393
+ if (outcome.status === "failed") {
2394
+ const id = typeof row.id === "string" ? row.id : "<no-id>";
2395
+ process.stderr.write(`${LOG_PREFIX} ${binding.namespace}/${binding.type} ${id}: ${outcome.error}\n`);
2396
+ }
2397
+ };
2398
+ }
2399
+ /**
2400
+ * Build the re-index function a backfill runs on. Shares the hook's binding,
2401
+ * so a backfilled row matches a written one.
2402
+ */
2403
+ function makeLexicalReindex(binding) {
2404
+ return (row) => lexicalRowReporting(row, binding);
2405
+ }
2406
+ /**
2407
+ * Build the pure classifier a dry-run coverage scan runs on. Shares the hook's
2408
+ * binding; evaluates the source and reports, touching no store.
2409
+ */
2410
+ function makeLexicalClassify(binding) {
2411
+ return async (row) => {
2412
+ if ((typeof row.id === "string" ? row.id : null) === null) return { status: "no-id" };
2413
+ try {
2414
+ const text = await binding.source(row);
2415
+ return text === null || text === void 0 ? { status: "unindexable" } : { status: "indexable" };
2416
+ } catch (err) {
2417
+ return {
2418
+ status: "failed",
2419
+ error: err instanceof Error ? err.message : String(err)
2420
+ };
2421
+ }
2422
+ };
2423
+ }
2424
+
2425
+ //#endregion
2426
+ //#region ../../plugins/substrate-recall/src/mcp-tool.ts
2427
+ /**
2428
+ * Everything `recall` accepts. Spells the search text `query`, matching
2429
+ * the route rather than the frame — the MCP tool is a route-shaped surface.
2430
+ * `boost` and `returnVector` are accepted because the core honours them,
2431
+ * even though the declared inputSchema does not advertise them.
2432
+ */
2433
+ const MCP_PARAMS = [
2434
+ "query",
2435
+ "k",
2436
+ "namespace",
2437
+ "type",
2438
+ "threshold",
2439
+ "lexicalThreshold",
2440
+ "expand",
2441
+ "boost",
2442
+ "returnVector",
2443
+ "lexical",
2444
+ "explain",
2445
+ "where"
2446
+ ];
2447
+ function recallMcpTool(cfg) {
2448
+ return {
2449
+ name: "recall",
2450
+ description: "Semantic recall over embedded Substrate records. Returns top-K records by cosine similarity to the natural-language query. Provide a query plus optional namespace/type filters. Requires an embedder configured in substrate-recall.config.json. AN EMPTY RESULT IS NOT NECESSARILY A MISS: read `arms` on the response. `denseWhy: 'no-source'` means the type declares no `embed.source`, so it has no vectors and this query could never have matched — ask GET /substrate/v1/embed-stats which types are embedded, rather than concluding nothing is recorded. Set `expand:true` to additionally walk opt-in `spread` crossRefs from the top-K hits, fetch neighbour embeddings, compute fresh cosine, and merge into the re-ranked top-K. Off by default; preserves byte-identical behaviour when omitted.",
2451
+ inputSchema: {
2452
+ type: "object",
2453
+ properties: {
2454
+ query: {
2455
+ type: "string",
2456
+ description: "Natural-language query to embed and match against."
2457
+ },
2458
+ namespace: {
2459
+ type: "string",
2460
+ description: "Namespace to search. Falls back to $SUBSTRATE_NAMESPACE; required if that is unset."
2461
+ },
2462
+ type: {
2463
+ type: "string",
2464
+ description: "Type to search. Required: there is no default."
2465
+ },
2466
+ k: {
2467
+ type: "number",
2468
+ description: "Max results. Default 10."
2469
+ },
2470
+ threshold: {
2471
+ type: "number",
2472
+ description: "Minimum cosine similarity (0..1). Default 0."
2473
+ },
2474
+ lexicalThreshold: {
2475
+ type: "number",
2476
+ description: "Cosine floor for hits only the lexical arm found. Default: same as threshold. 0 keeps them unfloored, including rows with no stored vector."
2477
+ },
2478
+ expand: {
2479
+ type: "boolean",
2480
+ description: "When true, walk opt-in crossRefs from the top-K hits and include neighbour scores. Default false."
2481
+ },
2482
+ lexical: {
2483
+ type: "boolean",
2484
+ description: "Set false to DISABLE the lexical (keyword) arm for this call. On by default wherever a lexical store is wired and the type declares a `lexical.source` — the declaration is the opt-in, so this exists to turn the arm off, not on. The response `arms` field reports what actually ran."
2485
+ },
2486
+ explain: {
2487
+ type: "boolean",
2488
+ description: "Return per-arm ranks (`_arms`) and the pre-fusion dense score (`_denseScore`) on each row. A fused score alone cannot say which arm put a row where it is."
2489
+ },
2490
+ where: {
2491
+ type: "object",
2492
+ description: "Row-field filter applied inside every candidate source, so k fills with matching rows: field -> { eq: scalar | null } or { in: [scalar | null, ...] }, every field must match. eq null matches a missing or null field. Example: { \"project\": { \"in\": [\"substrate\", null] } }."
2493
+ }
2494
+ },
2495
+ required: ["query", "type"]
2496
+ },
2497
+ handler: async (input) => {
2498
+ if (input !== null && typeof input === "object" && !Array.isArray(input)) {
2499
+ const unknown = checkParams(input, MCP_PARAMS);
2500
+ if (unknown !== null) return { error: {
2501
+ code: "bad_request",
2502
+ message: unknown
2503
+ } };
2504
+ }
2505
+ const unbound = cfg.checkReadPolicy;
2506
+ const unboundWrite = cfg.checkWritePolicy;
2507
+ try {
2508
+ const caller = anonymousCaller();
2509
+ return await handleRecallRequest(input, {
2510
+ ...cfg.embedder !== void 0 ? { embedder: cfg.embedder } : {},
2511
+ store: cfg.store,
2512
+ ...cfg.lexicalStore !== void 0 ? { lexicalStore: cfg.lexicalStore } : {},
2513
+ ...cfg.lexicalSources !== void 0 ? { lexicalSources: cfg.lexicalSources } : {},
2514
+ ...cfg.embedSources !== void 0 ? { embedSources: cfg.embedSources } : {},
2515
+ salience: cfg.salience ?? DEFAULT_SALIENCE_CONFIG,
2516
+ spreadResolver: cfg.spreadResolver ?? null,
2517
+ expansionResolver: cfg.expansionResolver ?? null,
2518
+ expansionEnabled: cfg.expansionEnabled ?? true,
2519
+ ...cfg.stats !== void 0 ? { stats: cfg.stats } : {},
2520
+ ...unbound !== void 0 ? { checkReadPolicy: bindPolicy(unbound, caller) } : {},
2521
+ ...unboundWrite !== void 0 ? { checkWritePolicy: bindPolicy(unboundWrite, caller) } : {},
2522
+ caller
2523
+ });
2524
+ } catch (err) {
2525
+ const code = err?.code;
2526
+ if (code === "bad_request" || code === "policy_denied" || code === "embedder_unavailable" || code === "no_retrieval_arm") return { error: {
2527
+ code,
2528
+ message: err instanceof Error ? err.message : code
2529
+ } };
2530
+ throw err;
2531
+ }
2532
+ }
2533
+ };
2534
+ }
2535
+
2536
+ //#endregion
2537
+ //#region ../../plugins/substrate-recall/src/migrations/0001_embeddings.ts
2538
+ const DEFAULT_DIM$1 = 768;
2539
+ const DEFAULT_HNSW_M = 16;
2540
+ const DEFAULT_HNSW_EF_CONSTRUCTION = 64;
2541
+ function assertPositiveInt(name, value) {
2542
+ if (!Number.isInteger(value) || value <= 0) throw new Error(`embeddingsMigration: ${name} must be a positive integer (got ${value})`);
2543
+ }
2544
+ function embeddingsMigration(opts = {}) {
2545
+ const dimension = opts.dimension ?? DEFAULT_DIM$1;
2546
+ const hnswM = opts.hnswM ?? DEFAULT_HNSW_M;
2547
+ const hnswEfConstruction = opts.hnswEfConstruction ?? DEFAULT_HNSW_EF_CONSTRUCTION;
2548
+ assertPositiveInt("dimension", dimension);
2549
+ assertPositiveInt("hnswM", hnswM);
2550
+ assertPositiveInt("hnswEfConstruction", hnswEfConstruction);
2551
+ return {
2552
+ id: "0001_embeddings",
2553
+ apply: async ({ sql }) => {
2554
+ if (sql === null) return;
2555
+ const s = sql;
2556
+ await s`CREATE EXTENSION IF NOT EXISTS vector`;
2557
+ await s.unsafe(`
2558
+ CREATE TABLE IF NOT EXISTS embeddings (
2559
+ row_namespace text NOT NULL,
2560
+ row_type text NOT NULL,
2561
+ row_id text NOT NULL,
2562
+ embedding vector(${dimension}) NOT NULL,
2563
+ model text NOT NULL,
2564
+ updated_at timestamptz NOT NULL DEFAULT now(),
2565
+ salience float8 NOT NULL DEFAULT 0,
2566
+ salience_updated_at timestamptz NOT NULL DEFAULT now(),
2567
+ PRIMARY KEY (row_namespace, row_type, row_id)
2568
+ )
2569
+ `);
2570
+ await s.unsafe(`
2571
+ CREATE INDEX IF NOT EXISTS embeddings_hnsw
2572
+ ON embeddings USING hnsw (embedding vector_cosine_ops)
2573
+ WITH (m = ${hnswM}, ef_construction = ${hnswEfConstruction})
2574
+ `);
2575
+ },
2576
+ rollback: async ({ sql }) => {
2577
+ if (sql === null) return;
2578
+ await sql`DROP TABLE IF EXISTS embeddings CASCADE`;
2579
+ }
2580
+ };
2581
+ }
2582
+
2583
+ //#endregion
2584
+ //#region ../../plugins/substrate-recall/src/migrations/0002_recall_clusters.ts
2585
+ const DEFAULT_DIM = 768;
2586
+ function recallClustersMigration(opts = {}) {
2587
+ const dimension = opts.dimension ?? DEFAULT_DIM;
2588
+ if (!Number.isInteger(dimension) || dimension <= 0) throw new Error(`recallClustersMigration: dimension must be a positive integer (got ${dimension})`);
2589
+ return {
2590
+ id: "0002_recall_clusters",
2591
+ apply: async ({ sql }) => {
2592
+ if (sql === null) return;
2593
+ const s = sql;
2594
+ await s`CREATE EXTENSION IF NOT EXISTS vector`;
2595
+ await s.unsafe(`
2596
+ CREATE TABLE IF NOT EXISTS recall_clusters (
2597
+ id text PRIMARY KEY,
2598
+ short_id bigint GENERATED ALWAYS AS IDENTITY,
2599
+ centroid vector(${dimension}) NOT NULL,
2600
+ member_count integer NOT NULL DEFAULT 0,
2601
+ departed_count integer NOT NULL DEFAULT 0,
2602
+ cohesion double precision NOT NULL,
2603
+ label text NOT NULL,
2604
+ labelled_by text NOT NULL,
2605
+ provenance jsonb NOT NULL,
2606
+ formed_at timestamptz NOT NULL DEFAULT now(),
2607
+ last_accreted_at timestamptz,
2608
+ retired_at timestamptz
2609
+ )
2610
+ `);
2611
+ await s.unsafe(`
2612
+ CREATE INDEX IF NOT EXISTS recall_clusters_live
2613
+ ON recall_clusters (retired_at)
2614
+ `);
2615
+ await s.unsafe(`
2616
+ CREATE TABLE IF NOT EXISTS recall_cluster_members (
2617
+ id text PRIMARY KEY,
2618
+ short_id bigint GENERATED ALWAYS AS IDENTITY,
2619
+ cluster_id text NOT NULL
2620
+ REFERENCES recall_clusters(id) ON DELETE CASCADE,
2621
+ member_ns text NOT NULL,
2622
+ member_type text NOT NULL,
2623
+ member_id text NOT NULL,
2624
+ origin text NOT NULL,
2625
+ similarity double precision NOT NULL,
2626
+ attached_at timestamptz NOT NULL DEFAULT now(),
2627
+ departed_at timestamptz
2628
+ )
2629
+ `);
2630
+ await s.unsafe(`
2631
+ CREATE UNIQUE INDEX IF NOT EXISTS recall_cluster_members_unique
2632
+ ON recall_cluster_members (cluster_id, member_ns, member_type, member_id)
2633
+ `);
2634
+ await s.unsafe(`
2635
+ CREATE INDEX IF NOT EXISTS recall_cluster_members_member
2636
+ ON recall_cluster_members (member_ns, member_type, member_id)
2637
+ `);
2638
+ },
2639
+ rollback: async ({ sql }) => {
2640
+ if (sql === null) return;
2641
+ const s = sql;
2642
+ await s`DROP TABLE IF EXISTS recall_cluster_members CASCADE`;
2643
+ await s`DROP TABLE IF EXISTS recall_clusters CASCADE`;
2644
+ }
2645
+ };
2646
+ }
2647
+
2648
+ //#endregion
2649
+ //#region ../../plugins/substrate-recall/src/migrations/0003_lexical.ts
2650
+ const DEFAULT_TS_CONFIG = "english";
2651
+ /**
2652
+ * Only identifier-safe configuration names are accepted. The value is
2653
+ * interpolated into DDL (a generated column expression cannot take a bind
2654
+ * parameter), so this is the boundary that keeps it from being a SQL
2655
+ * injection seam.
2656
+ */
2657
+ function assertSafeConfigName(name) {
2658
+ if (!/^[a-z_][a-z0-9_]*$/.test(name)) throw new Error(`lexicalMigration: textSearchConfig must be a bare lowercase identifier (got '${name}')`);
2659
+ }
2660
+ function lexicalMigration(opts = {}) {
2661
+ const tsConfig = opts.textSearchConfig ?? DEFAULT_TS_CONFIG;
2662
+ assertSafeConfigName(tsConfig);
2663
+ return {
2664
+ id: "0003_lexical",
2665
+ apply: async ({ sql }) => {
2666
+ if (sql === null) return;
2667
+ const s = sql;
2668
+ await s.unsafe(`
2669
+ CREATE TABLE IF NOT EXISTS lexical (
2670
+ row_namespace text NOT NULL,
2671
+ row_type text NOT NULL,
2672
+ row_id text NOT NULL,
2673
+ content text NOT NULL,
2674
+ tsv tsvector GENERATED ALWAYS AS (to_tsvector('${tsConfig}', content)) STORED,
2675
+ updated_at timestamptz NOT NULL DEFAULT now(),
2676
+ PRIMARY KEY (row_namespace, row_type, row_id)
2677
+ )
2678
+ `);
2679
+ await s`
2680
+ CREATE INDEX IF NOT EXISTS lexical_tsv
2681
+ ON lexical USING gin (tsv)
2682
+ `;
2683
+ await s`
2684
+ CREATE INDEX IF NOT EXISTS lexical_scope
2685
+ ON lexical (row_namespace, row_type)
2686
+ `;
2687
+ },
2688
+ rollback: async ({ sql }) => {
2689
+ if (sql === null) return;
2690
+ await sql`DROP TABLE IF EXISTS lexical CASCADE`;
2691
+ }
2692
+ };
2693
+ }
2694
+
2695
+ //#endregion
2696
+ //#region ../../plugins/substrate-recall/src/align-dimension.ts
2697
+ async function columnDim(s, table, column) {
2698
+ if ((await s.unsafe(`SELECT to_regclass('${table}') AS t`))[0]?.t == null) return null;
2699
+ return (await s.unsafe(`SELECT (regexp_match(format_type(atttypid, atttypmod), '\\((\\d+)\\)'))[1]::int AS dim
2700
+ FROM pg_attribute WHERE attrelid = '${table}'::regclass AND attname = '${column}'`))[0]?.dim ?? null;
2701
+ }
2702
+ async function isEmpty(s, table) {
2703
+ return (await s.unsafe(`SELECT NOT EXISTS (SELECT 1 FROM ${table}) AS empty`))[0]?.empty === true;
2704
+ }
2705
+ async function alignColumn(s, table, column, dimension, after) {
2706
+ const found = await columnDim(s, table, column);
2707
+ if (found === null) return { state: "absent" };
2708
+ if (found === dimension) return {
2709
+ state: "match",
2710
+ found
2711
+ };
2712
+ await s.unsafe(`LOCK TABLE ${table} IN ACCESS EXCLUSIVE MODE`);
2713
+ if (!await isEmpty(s, table)) return {
2714
+ state: "populated",
2715
+ found
2716
+ };
2717
+ await s.unsafe(`ALTER TABLE ${table} ALTER COLUMN ${column} TYPE vector(${dimension})`);
2718
+ if (after !== void 0) await after();
2719
+ return {
2720
+ state: "aligned",
2721
+ found
2722
+ };
2723
+ }
2724
+ async function alignVectorDimensions(s, opts) {
2725
+ const { dimension } = opts;
2726
+ if (!Number.isInteger(dimension) || dimension <= 0) throw new Error(`alignVectorDimensions: dimension must be a positive integer (got ${dimension})`);
2727
+ return await s.begin(async (tx) => {
2728
+ await tx`SELECT pg_advisory_xact_lock(hashtext('substrate-recall-align'))`;
2729
+ return alignLocked(tx, opts);
2730
+ });
2731
+ }
2732
+ async function alignLocked(s, opts) {
2733
+ const { dimension } = opts;
2734
+ const m = opts.hnswM ?? 16;
2735
+ const ef = opts.hnswEfConstruction ?? 64;
2736
+ const embeddings = await alignColumn(s, "embeddings", "embedding", dimension, async () => {
2737
+ await s.unsafe(`DROP INDEX IF EXISTS embeddings_hnsw`);
2738
+ await s.unsafe(`
2739
+ CREATE INDEX IF NOT EXISTS embeddings_hnsw
2740
+ ON embeddings USING hnsw (embedding vector_cosine_ops)
2741
+ WITH (m = ${m}, ef_construction = ${ef})
2742
+ `);
2743
+ });
2744
+ const centroids = await alignColumn(s, "recall_clusters", "centroid", dimension);
2745
+ return {
2746
+ embeddings: embeddings.state,
2747
+ centroids: centroids.state,
2748
+ found: {
2749
+ ...embeddings.found !== void 0 ? { embeddings: embeddings.found } : {},
2750
+ ...centroids.found !== void 0 ? { centroids: centroids.found } : {}
2751
+ }
2752
+ };
2753
+ }
2754
+
2755
+ //#endregion
2756
+ //#region ../../plugins/substrate-recall/src/expansion-resolver.ts
2757
+ function makeExpansionResolver(registry, edges, cfg) {
2758
+ return async (sources) => {
2759
+ if (sources.length === 0) return [];
2760
+ const seen = /* @__PURE__ */ new Set();
2761
+ const out = [];
2762
+ const seedKeys = new Set(sources.map((s) => `${s.namespace}/${s.type}/${s.id}`));
2763
+ for (const src of sources) {
2764
+ let pushedForThisSeed = 0;
2765
+ const tryPush = (n) => {
2766
+ if (out.length >= cfg.maxTotalNeighbours) return false;
2767
+ if (pushedForThisSeed >= cfg.maxNeighboursPerSeed) return false;
2768
+ const k = `${n.namespace}/${n.type}/${n.id}`;
2769
+ if (seedKeys.has(k)) return true;
2770
+ if (seen.has(k)) return true;
2771
+ seen.add(k);
2772
+ out.push(n);
2773
+ pushedForThisSeed++;
2774
+ return true;
2775
+ };
2776
+ const specs = registry.forType(src.namespace, src.type);
2777
+ for (const spec of specs) {
2778
+ if (out.length >= cfg.maxTotalNeighbours) break;
2779
+ const value = src.row[spec.fieldName];
2780
+ if (typeof value === "string" && value.length > 0) tryPush({
2781
+ namespace: spec.targetNs,
2782
+ type: spec.targetType,
2783
+ id: value,
2784
+ seedId: src.id,
2785
+ allowsCrossType: false
2786
+ });
2787
+ }
2788
+ }
2789
+ if (edges !== null) {
2790
+ const inboundBySeed = /* @__PURE__ */ new Map();
2791
+ const allInbound = await edges.findEdgesToMany(sources.map((s) => ({
2792
+ ns: s.namespace,
2793
+ type: s.type,
2794
+ id: s.id
2795
+ })));
2796
+ for (const edge of allInbound) {
2797
+ const tk = `${edge.to.ns}/${edge.to.type}/${String(edge.to.id)}`;
2798
+ const list = inboundBySeed.get(tk);
2799
+ if (list === void 0) inboundBySeed.set(tk, [edge]);
2800
+ else list.push(edge);
2801
+ }
2802
+ for (const src of sources) {
2803
+ if (out.length >= cfg.maxTotalNeighbours) break;
2804
+ const inbound = inboundBySeed.get(`${src.namespace}/${src.type}/${src.id}`) ?? [];
2805
+ let pushedForThisSeed = 0;
2806
+ for (const edge of inbound) {
2807
+ if (out.length >= cfg.maxTotalNeighbours) break;
2808
+ if (pushedForThisSeed >= cfg.maxNeighboursPerSeed) break;
2809
+ const optInSpec = registry.forType(edge.from.ns, edge.from.type).find((s) => s.fieldName === edge.fieldName && s.targetNs === src.namespace && s.targetType === src.type);
2810
+ if (optInSpec === void 0) continue;
2811
+ const k = `${edge.from.ns}/${edge.from.type}/${edge.from.id}`;
2812
+ if (seedKeys.has(k)) continue;
2813
+ if (seen.has(k)) continue;
2814
+ seen.add(k);
2815
+ out.push({
2816
+ namespace: edge.from.ns,
2817
+ type: edge.from.type,
2818
+ id: String(edge.from.id),
2819
+ seedId: src.id,
2820
+ allowsCrossType: optInSpec.expandCrossType === true
2821
+ });
2822
+ pushedForThisSeed++;
2823
+ }
2824
+ }
2825
+ }
2826
+ return out;
2827
+ };
2828
+ }
2829
+
2830
+ //#endregion
2831
+ //#region ../../plugins/substrate-recall/src/salience-boost-core.ts
2832
+ /** Per-request target cap — bounds the batched store write. */
2833
+ const SALIENCE_BOOST_MAX_TARGETS = 500;
2834
+ function badRequest(message) {
2835
+ throw Object.assign(new Error(message), { code: "bad_request" });
2836
+ }
2837
+ /**
2838
+ * Validate + normalise a raw boost payload into a `SalienceBoostInput`.
2839
+ * Throws `{ code: 'bad_request' }` on any shape/cap violation.
2840
+ */
2841
+ function validateBoostInput(raw) {
2842
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) badRequest("request body must be a JSON object");
2843
+ const obj = raw;
2844
+ if (!Array.isArray(obj.targets) || obj.targets.length === 0) badRequest("\"targets\" must be a non-empty array of { namespace, type, id }");
2845
+ if (obj.targets.length > 500) badRequest(`"targets" exceeds the per-request cap of ${500}`);
2846
+ const targets = [];
2847
+ for (const t of obj.targets) {
2848
+ if (t === null || typeof t !== "object") badRequest("each target must be an object with string namespace, type, id");
2849
+ const { namespace, type, id } = t;
2850
+ if (typeof namespace !== "string" || typeof type !== "string" || typeof id !== "string") badRequest("each target must be an object with string namespace, type, id");
2851
+ if (namespace.length === 0 || type.length === 0 || id.length === 0) badRequest("target namespace, type, id must be non-empty strings");
2852
+ targets.push({
2853
+ namespace,
2854
+ type,
2855
+ id
2856
+ });
2857
+ }
2858
+ if (obj.bump !== void 0) {
2859
+ if (typeof obj.bump !== "number" || !Number.isFinite(obj.bump) || obj.bump <= 0) badRequest("\"bump\" must be a finite number > 0");
2860
+ return {
2861
+ targets,
2862
+ bump: obj.bump
2863
+ };
2864
+ }
2865
+ return { targets };
2866
+ }
2867
+ /**
2868
+ * Reinforce salience for the named targets. Gates each distinct
2869
+ * (namespace, type) scope once against the bound read and write policies
2870
+ * (first denial throws `policy_denied` naming the scope), then awaits the
2871
+ * batched store write.
2872
+ */
2873
+ async function handleSalienceBoost(input, deps) {
2874
+ const checkReadPolicy = memoCheck(deps.checkReadPolicy);
2875
+ const seen = /* @__PURE__ */ new Set();
2876
+ for (const t of input.targets) {
2877
+ const scope = `${t.namespace}/${t.type}`;
2878
+ if (seen.has(scope)) continue;
2879
+ seen.add(scope);
2880
+ if (checkReadPolicy !== void 0) {
2881
+ const decision = checkReadPolicy(t.namespace, t.type);
2882
+ if (!decision.allow) throw Object.assign(/* @__PURE__ */ new Error(`${scope}: ${decision.reason ?? "policy denied"}`), { code: "policy_denied" });
2883
+ }
2884
+ const write = deps.checkWritePolicy?.(t.namespace, t.type) ?? {
2885
+ allow: false,
2886
+ reason: "write policy not wired"
2887
+ };
2888
+ if (!write.allow) throw Object.assign(/* @__PURE__ */ new Error(`${scope}: ${write.reason ?? "policy denied"}`), { code: "policy_denied" });
2889
+ }
2890
+ const readable = await visibleRefs(input.targets, checkReadPolicy, deps.caller, deps.store, deps.model);
2891
+ const applied = await deps.store.boostSalience(readable, deps.halfLifeHours, input.bump);
2892
+ const hit = new Set(applied.map((t) => `${t.namespace}/${t.type}/${t.id}`));
2893
+ const missing = input.targets.filter((t) => !hit.has(`${t.namespace}/${t.type}/${t.id}`));
2894
+ return {
2895
+ ok: true,
2896
+ requested: input.targets.length,
2897
+ applied: applied.length,
2898
+ missing
2899
+ };
2900
+ }
2901
+
2902
+ //#endregion
2903
+ //#region ../../plugins/substrate-recall/src/frame-surface.ts
2904
+ const scalar = (type) => ({
2905
+ kind: "scalar",
2906
+ type
2907
+ });
2908
+ /** Published field shape for a `recall/Hit` row. Names mirror the resolver output exactly. */
2909
+ const HIT_FIELDS = {
2910
+ id: scalar("string"),
2911
+ namespace: scalar("string"),
2912
+ type: scalar("string"),
2913
+ score: scalar("number"),
2914
+ salience: scalar("number"),
2915
+ blendedScore: scalar("number"),
2916
+ kind: scalar("string"),
2917
+ expandedFrom: scalar("json"),
2918
+ vector: scalar("json"),
2919
+ row: scalar("json")
2920
+ };
2921
+ function bad(message) {
2922
+ throw new ResolverFrameError("bad_request", message);
2923
+ }
2924
+ /**
2925
+ * Everything the `recall/Hit` frame accepts. Deliberately spells the search
2926
+ * text `to` — THIS surface's name for it — so a refusal tells a caller what to
2927
+ * send here rather than what the route wants. The message is generated from
2928
+ * this array, so the two cannot disagree.
2929
+ */
2930
+ const FRAME_PARAMS = [
2931
+ "to",
2932
+ "k",
2933
+ "namespace",
2934
+ "type",
2935
+ "threshold",
2936
+ "lexicalThreshold",
2937
+ "expand",
2938
+ "boost",
2939
+ "returnVector",
2940
+ "lexical",
2941
+ "explain",
2942
+ "where"
2943
+ ];
2944
+ /**
2945
+ * Parse + validate the `recall/Hit` params into a `RecallInput`. Matches the
2946
+ * RecallInput surface exactly (to → query, k, namespace, type, threshold,
2947
+ * expand, boost, returnVector, lexical, explain, where). Wrong types throw
2948
+ * `bad_request`; `where` is passed through for the core to validate.
2949
+ */
2950
+ function parseHitParams(params) {
2951
+ const p = params ?? {};
2952
+ const unknown = checkParams(p, FRAME_PARAMS);
2953
+ if (unknown !== null && p.query === void 0) bad(unknown);
2954
+ if (typeof p.to !== "string" || p.to.length === 0) bad(typeof p.query === "string" && p.query.length > 0 ? "\"to\" must be a non-empty string — this is the FRAME surface, which spells the search text `to`; you passed `query`, which is the spelling POST /substrate/v1/recall and the MCP tool use" : "\"to\" must be a non-empty string (the FRAME surface spells the search text `to`; POST /substrate/v1/recall and the MCP tool call it `query`)");
2955
+ const input = { query: p.to };
2956
+ if (p.k !== void 0) {
2957
+ if (typeof p.k !== "number") bad("\"k\" must be a number");
2958
+ input.k = p.k;
2959
+ }
2960
+ if (p.namespace !== void 0) {
2961
+ if (typeof p.namespace !== "string") bad("\"namespace\" must be a string");
2962
+ input.namespace = p.namespace;
2963
+ }
2964
+ if (p.type !== void 0) {
2965
+ if (typeof p.type !== "string") bad("\"type\" must be a string");
2966
+ input.type = p.type;
2967
+ }
2968
+ if (p.threshold !== void 0) {
2969
+ if (typeof p.threshold !== "number") bad("\"threshold\" must be a number");
2970
+ input.threshold = p.threshold;
2971
+ }
2972
+ if (p.lexicalThreshold !== void 0) {
2973
+ if (typeof p.lexicalThreshold !== "number") bad("\"lexicalThreshold\" must be a number");
2974
+ input.lexicalThreshold = p.lexicalThreshold;
2975
+ }
2976
+ if (p.expand !== void 0) {
2977
+ if (typeof p.expand !== "boolean") bad("\"expand\" must be a boolean");
2978
+ input.expand = p.expand;
2979
+ }
2980
+ if (p.boost !== void 0) {
2981
+ if (typeof p.boost !== "boolean") bad("\"boost\" must be a boolean");
2982
+ input.boost = p.boost;
2983
+ }
2984
+ if (p.returnVector !== void 0) {
2985
+ if (typeof p.returnVector !== "boolean") bad("\"returnVector\" must be a boolean");
2986
+ input.returnVector = p.returnVector;
2987
+ }
2988
+ if (p.lexical !== void 0) {
2989
+ if (typeof p.lexical !== "boolean") bad("\"lexical\" must be a boolean");
2990
+ input.lexical = p.lexical;
2991
+ }
2992
+ if (p.explain !== void 0) {
2993
+ if (typeof p.explain !== "boolean") bad("\"explain\" must be a boolean");
2994
+ input.explain = p.explain;
2995
+ }
2996
+ if (p.where !== void 0) input.where = p.where;
2997
+ return input;
2998
+ }
2999
+ /**
3000
+ * Re-raise a coded core throw as a `ResolverFrameError` so the engine surfaces
3001
+ * the same code the HTTP route maps to a status. `policy_denied` / `bad_request`
3002
+ * pass through verbatim; embedder `unavailable` / `invalid_response` become
3003
+ * `embedder_*` (route 503 parity). Anything uncoded rethrows raw.
3004
+ */
3005
+ function rethrowCoded(err) {
3006
+ const code = err?.code;
3007
+ const message = err instanceof Error ? err.message : String(err);
3008
+ if (code === "policy_denied" || code === "bad_request") throw new ResolverFrameError(code, message);
3009
+ if (code === "unavailable" || code === "invalid_response") throw new ResolverFrameError(`embedder_${code}`, message);
3010
+ if (code === "embedder_unavailable" || code === "no_retrieval_arm") throw new ResolverFrameError(code, message);
3011
+ throw err;
3012
+ }
3013
+ /**
3014
+ * Keep only the `=== true` keys of `fields`; `undefined` fields = passthrough.
3015
+ * `fields: {}` strips every key, matching the compose layer's projectEnvelope.
3016
+ */
3017
+ function projectHit(row, fields) {
3018
+ if (fields === void 0) return row;
3019
+ const keep = Object.entries(fields).filter(([, v]) => v === true).map(([k]) => k);
3020
+ const out = {};
3021
+ for (const k of keep) if (k in row) out[k] = row[k];
3022
+ return out;
3023
+ }
3024
+ function hitRow(r) {
3025
+ return {
3026
+ id: String(r.row.id ?? ""),
3027
+ namespace: r.namespace,
3028
+ type: r.type,
3029
+ score: r.score,
3030
+ salience: r._salience,
3031
+ blendedScore: r._blendedScore,
3032
+ kind: r._expandedFrom === void 0 ? "seed" : "expansion",
3033
+ ...r._expandedFrom !== void 0 ? { expandedFrom: r._expandedFrom } : {},
3034
+ ...r.vector !== void 0 ? { vector: r.vector } : {},
3035
+ row: r.row
3036
+ };
3037
+ }
3038
+ function buildRecallFrameSurface(deps) {
3039
+ const salience = deps.salience ?? DEFAULT_SALIENCE_CONFIG;
3040
+ const hitResolver = async (ctx, args) => {
3041
+ const input = parseHitParams(args.params);
3042
+ const bound = bindPolicy(deps.checkReadPolicy, callerFromContext(ctx));
3043
+ const boundWrite = bindPolicy(deps.checkWritePolicy, callerFromContext(ctx));
3044
+ let out;
3045
+ try {
3046
+ out = await handleRecallRequest(input, {
3047
+ ...deps.embedder !== void 0 ? { embedder: deps.embedder } : {},
3048
+ store: deps.store,
3049
+ ...deps.lexicalStore !== void 0 ? { lexicalStore: deps.lexicalStore } : {},
3050
+ ...deps.lexicalSources !== void 0 ? { lexicalSources: deps.lexicalSources } : {},
3051
+ ...deps.embedSources !== void 0 ? { embedSources: deps.embedSources } : {},
3052
+ salience,
3053
+ spreadResolver: deps.spreadResolver,
3054
+ expansionResolver: deps.expansionResolver,
3055
+ expansionEnabled: deps.expansionEnabled,
3056
+ ...boundWrite !== void 0 ? { checkWritePolicy: boundWrite } : {},
3057
+ ...deps.stats !== void 0 ? { stats: deps.stats } : {},
3058
+ ...bound !== void 0 ? { checkReadPolicy: bound } : {},
3059
+ caller: callerFromContext(ctx)
3060
+ });
3061
+ } catch (err) {
3062
+ rethrowCoded(err);
3063
+ }
3064
+ return out.rows.map((r) => projectHit(hitRow(r), args.fields));
3065
+ };
3066
+ const boostResolver = async (ctx, args) => {
3067
+ const bound = bindPolicy(deps.checkReadPolicy, callerFromContext(ctx));
3068
+ const boundWrite = bindPolicy(deps.checkWritePolicy, callerFromContext(ctx));
3069
+ try {
3070
+ const input = validateBoostInput(args.params);
3071
+ return {
3072
+ id: "ack",
3073
+ ...await handleSalienceBoost(input, {
3074
+ store: deps.store,
3075
+ halfLifeHours: salience.halfLifeHours,
3076
+ ...bound !== void 0 ? { checkReadPolicy: bound } : {},
3077
+ ...boundWrite !== void 0 ? { checkWritePolicy: boundWrite } : {},
3078
+ caller: callerFromContext(ctx),
3079
+ ...deps.embedder !== void 0 ? { model: deps.embedder.modelId } : {}
3080
+ })
3081
+ };
3082
+ } catch (err) {
3083
+ rethrowCoded(err);
3084
+ }
3085
+ };
3086
+ const fetchEmbeddingsResolver = async (ctx, args) => {
3087
+ const bound = bindPolicy(deps.checkReadPolicy, callerFromContext(ctx));
3088
+ const boundWrite = bindPolicy(deps.checkWritePolicy, callerFromContext(ctx));
3089
+ try {
3090
+ const input = validateFetchInput(args.params);
3091
+ return {
3092
+ id: "embeddings",
3093
+ ...await handleEmbeddingsFetch(input, {
3094
+ store: deps.store,
3095
+ salience,
3096
+ ...deps.embedder !== void 0 ? { embedder: deps.embedder } : {},
3097
+ ...bound !== void 0 ? { checkReadPolicy: bound } : {},
3098
+ ...boundWrite !== void 0 ? { checkWritePolicy: boundWrite } : {},
3099
+ caller: callerFromContext(ctx)
3100
+ })
3101
+ };
3102
+ } catch (err) {
3103
+ rethrowCoded(err);
3104
+ }
3105
+ };
3106
+ const clusterSurface = deps.clusterSurface === void 0 ? void 0 : buildClusterSurface(deps.clusterSurface);
3107
+ return {
3108
+ namespace: "recall",
3109
+ types: {
3110
+ Hit: {
3111
+ fields: HIT_FIELDS,
3112
+ resolver: hitResolver
3113
+ },
3114
+ ...clusterSurface?.types ?? {}
3115
+ },
3116
+ mutations: {
3117
+ boost: { resolver: boostResolver },
3118
+ fetchEmbeddings: { resolver: fetchEmbeddingsResolver },
3119
+ ...clusterSurface?.mutations ?? {}
3120
+ }
3121
+ };
3122
+ }
3123
+
3124
+ //#endregion
3125
+ //#region ../../plugins/substrate-recall/src/lexical-reindex-core.ts
3126
+ /** Rows per call when the caller does not say. */
3127
+ const LEXICAL_REINDEX_DEFAULT_LIMIT = 500;
3128
+ /**
3129
+ * Hard ceiling per call. Higher than the embed reindex's because a lexical row
3130
+ * costs a database write rather than an embedder round-trip — but still
3131
+ * bounded, because an unbounded page is an unbounded request.
3132
+ */
3133
+ const LEXICAL_REINDEX_MAX_LIMIT = 5e3;
3134
+ function fail$1(code, message) {
3135
+ throw Object.assign(new Error(message), { code });
3136
+ }
3137
+ function nonEmptyString$1(value, field) {
3138
+ if (typeof value !== "string" || value.length === 0) fail$1("bad_request", `${field} must be a non-empty string`);
3139
+ return value;
3140
+ }
3141
+ /** Throws `{ code: 'bad_request' }` on any shape violation. */
3142
+ function validateLexicalReindexInput(raw) {
3143
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) fail$1("bad_request", "body must be a JSON object");
3144
+ const obj = raw;
3145
+ const namespace = nonEmptyString$1(obj.namespace, "namespace");
3146
+ const type = nonEmptyString$1(obj.type, "type");
3147
+ let limit = 500;
3148
+ if (obj.limit !== void 0) {
3149
+ if (typeof obj.limit !== "number" || !Number.isInteger(obj.limit) || obj.limit < 1) fail$1("bad_request", "limit must be a positive integer");
3150
+ if (obj.limit > 5e3) fail$1("bad_request", `limit exceeds the maximum of ${LEXICAL_REINDEX_MAX_LIMIT}`);
3151
+ limit = obj.limit;
3152
+ }
3153
+ if (obj.cursor !== void 0 && typeof obj.cursor !== "string") fail$1("bad_request", "cursor must be a string");
3154
+ return {
3155
+ namespace,
3156
+ type,
3157
+ limit,
3158
+ ...typeof obj.cursor === "string" ? { cursor: obj.cursor } : {}
3159
+ };
3160
+ }
3161
+ async function handleLexicalReindex(input, deps) {
3162
+ const entry = deps.registry.get(input.namespace, input.type);
3163
+ if (entry === void 0) {
3164
+ const known = deps.registry.types().map((t) => `${t.namespace}/${t.type}`).join(", ");
3165
+ fail$1("unknown_type", `${input.namespace}/${input.type} declares no lexical.source; lexically-indexed types are: ${known === "" ? "(none)" : known}`);
3166
+ }
3167
+ if (entry.reindex === void 0) fail$1("unavailable", `${input.namespace}/${input.type} was registered without a re-index binding`);
3168
+ if (deps.resolveDataset === void 0) fail$1("unavailable", "no dataset resolver is wired; cannot read rows to re-index");
3169
+ const dataset = deps.resolveDataset(input.namespace);
3170
+ if (dataset === null) fail$1("unknown_type", `no dataset is registered for namespace ${input.namespace}`);
3171
+ const limit = input.limit ?? 500;
3172
+ const page = await dataset.read(input.type, {
3173
+ limit,
3174
+ ...input.cursor !== void 0 ? { cursor: input.cursor } : {}
3175
+ });
3176
+ const failures = [];
3177
+ let indexed = 0;
3178
+ let unindexable = 0;
3179
+ for (const row of page.rows) {
3180
+ const outcome = await entry.reindex(row);
3181
+ switch (outcome.status) {
3182
+ case "indexed":
3183
+ indexed++;
3184
+ break;
3185
+ case "unindexable":
3186
+ unindexable++;
3187
+ break;
3188
+ case "no-id":
3189
+ failures.push({
3190
+ id: "<no-id>",
3191
+ error: "row has no string id"
3192
+ });
3193
+ break;
3194
+ case "failed": failures.push({
3195
+ id: typeof row.id === "string" ? String(row.id) : "<no-id>",
3196
+ error: outcome.error
3197
+ });
3198
+ }
3199
+ }
3200
+ return {
3201
+ namespace: input.namespace,
3202
+ type: input.type,
3203
+ scanned: page.rows.length,
3204
+ indexed,
3205
+ unindexable,
3206
+ failed: failures.length,
3207
+ failures,
3208
+ hasMore: page.hasMore,
3209
+ ...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {}
3210
+ };
3211
+ }
3212
+
3213
+ //#endregion
3214
+ //#region ../../plugins/substrate-recall/src/lexical-reindex-route.ts
3215
+ /**
3216
+ * POST /substrate/v1/lexical/reindex — admin-gated server-side lexical backfill.
3217
+ * Thin transport adapter over `handleLexicalReindex`.
3218
+ *
3219
+ * Capability is `admin`, not `mutate`: it rewrites indexed text across a
3220
+ * whole type, and `admin` is the only capability compose enforces under
3221
+ * `mode: 'attribute'` — a `mutate` claim would leave the route open there.
3222
+ */
3223
+ function lexicalReindexRouteHandler(cfg) {
3224
+ return async (req) => {
3225
+ const raw = req.body;
3226
+ if (raw === null || Buffer.isBuffer(raw) && raw.length === 0) return jsonResponse(400, {
3227
+ code: "bad_request",
3228
+ message: "request body is required"
3229
+ });
3230
+ let parsed;
3231
+ try {
3232
+ parsed = JSON.parse(Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw));
3233
+ } catch (err) {
3234
+ return jsonResponse(400, {
3235
+ code: "bad_request",
3236
+ message: err instanceof Error ? err.message : "invalid JSON"
3237
+ });
3238
+ }
3239
+ try {
3240
+ return jsonResponse(200, await handleLexicalReindex(validateLexicalReindexInput(parsed), cfg));
3241
+ } catch (err) {
3242
+ const code = err?.code;
3243
+ const message = err instanceof Error ? err.message : String(err);
3244
+ if (code === "bad_request" || code === "unknown_type") return jsonResponse(400, { error: {
3245
+ code,
3246
+ message
3247
+ } });
3248
+ if (code === "unavailable") return jsonResponse(503, { error: {
3249
+ code,
3250
+ message
3251
+ } });
3252
+ process.stderr.write(`lexical reindex route failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
3253
+ return jsonResponse(500, { error: {
3254
+ code: "internal",
3255
+ message: "lexical reindex failed"
3256
+ } });
3257
+ }
3258
+ };
3259
+ }
3260
+
3261
+ //#endregion
3262
+ //#region ../../plugins/substrate-recall/src/lexical-source-registry.ts
3263
+ var LexicalSourceRegistry = class {
3264
+ #byKey = /* @__PURE__ */ new Map();
3265
+ /**
3266
+ * Register one lexically-indexed type. Idempotent on (namespace, type) — a
3267
+ * re-install overwrites, because the LATEST registration reflects the
3268
+ * currently-composed namespace definition.
3269
+ */
3270
+ add(entry) {
3271
+ this.#byKey.set(`${entry.namespace}/${entry.type}`, entry);
3272
+ }
3273
+ /** The entry for one type, or undefined when it declares no `lexical.source`. */
3274
+ get(namespace, type) {
3275
+ return this.#byKey.get(`${namespace}/${type}`);
3276
+ }
3277
+ /** Every lexically-indexed type, sorted by (namespace, type) so audit runs diff cleanly. */
3278
+ types() {
3279
+ return [...this.#byKey.values()].map(({ namespace, type }) => ({
3280
+ namespace,
3281
+ type
3282
+ })).sort((a, b) => a.namespace.localeCompare(b.namespace) || a.type.localeCompare(b.type));
3283
+ }
3284
+ size() {
3285
+ return this.#byKey.size;
3286
+ }
3287
+ };
3288
+
3289
+ //#endregion
3290
+ //#region ../../plugins/substrate-recall/src/reindex-core.ts
3291
+ /** Rows per call when the caller does not say. */
3292
+ const REINDEX_DEFAULT_LIMIT = 100;
3293
+ /**
3294
+ * Hard ceiling per call. Each row costs one embedder round-trip, so an
3295
+ * unbounded page is an unbounded request; the cursor is how a caller reaches
3296
+ * the rest of the corpus.
3297
+ */
3298
+ const REINDEX_MAX_LIMIT = 1e3;
3299
+ function fail(code, message) {
3300
+ throw Object.assign(new Error(message), { code });
3301
+ }
3302
+ function nonEmptyString(value, field) {
3303
+ if (typeof value !== "string" || value.length === 0) fail("bad_request", `${field} must be a non-empty string`);
3304
+ return value;
3305
+ }
3306
+ /** Throws `{ code: 'bad_request' }` on any shape violation. */
3307
+ function validateReindexInput(raw) {
3308
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) fail("bad_request", "body must be a JSON object");
3309
+ const obj = raw;
3310
+ const namespace = nonEmptyString(obj.namespace, "namespace");
3311
+ const type = nonEmptyString(obj.type, "type");
3312
+ let limit = 100;
3313
+ if (obj.limit !== void 0) {
3314
+ if (typeof obj.limit !== "number" || !Number.isInteger(obj.limit) || obj.limit < 1) fail("bad_request", "limit must be a positive integer");
3315
+ if (obj.limit > 1e3) fail("bad_request", `limit exceeds the maximum of ${REINDEX_MAX_LIMIT}`);
3316
+ limit = obj.limit;
3317
+ }
3318
+ if (obj.cursor !== void 0 && typeof obj.cursor !== "string") fail("bad_request", "cursor must be a string");
3319
+ return {
3320
+ namespace,
3321
+ type,
3322
+ limit,
3323
+ ...typeof obj.cursor === "string" ? { cursor: obj.cursor } : {}
3324
+ };
3325
+ }
3326
+ async function handleReindex(input, deps) {
3327
+ const entry = deps.registry.get(input.namespace, input.type);
3328
+ if (entry === void 0) {
3329
+ const known = deps.registry.types().map((t) => `${t.namespace}/${t.type}`).join(", ");
3330
+ fail("unknown_type", `${input.namespace}/${input.type} declares no embed.source; embedded types are: ${known === "" ? "(none)" : known}`);
3331
+ }
3332
+ if (entry.reembed === void 0) fail("unavailable", `${input.namespace}/${input.type} was registered without a re-embed binding`);
3333
+ if (deps.resolveDataset === void 0) fail("unavailable", "no dataset resolver is wired; cannot read rows to re-embed");
3334
+ const dataset = deps.resolveDataset(input.namespace);
3335
+ if (dataset === null) fail("unknown_type", `no dataset is registered for namespace ${input.namespace}`);
3336
+ const limit = input.limit ?? 100;
3337
+ const page = await dataset.read(input.type, {
3338
+ limit,
3339
+ ...input.cursor !== void 0 ? { cursor: input.cursor } : {}
3340
+ });
3341
+ const failures = [];
3342
+ let embedded = 0;
3343
+ let unindexable = 0;
3344
+ for (const row of page.rows) {
3345
+ const outcome = await entry.reembed(row);
3346
+ switch (outcome.status) {
3347
+ case "embedded":
3348
+ embedded++;
3349
+ break;
3350
+ case "unindexable":
3351
+ unindexable++;
3352
+ break;
3353
+ case "no-id":
3354
+ failures.push({
3355
+ id: "<no-id>",
3356
+ error: "row has no string or number id"
3357
+ });
3358
+ break;
3359
+ case "failed":
3360
+ if (outcome.code === "unavailable") fail("unavailable", `embedder unavailable after ${embedded} of ${page.rows.length} rows: ${outcome.error}`);
3361
+ failures.push({
3362
+ id: typeof row.id === "string" ? String(row.id) : "<no-id>",
3363
+ error: outcome.error
3364
+ });
3365
+ }
3366
+ }
3367
+ return {
3368
+ namespace: input.namespace,
3369
+ type: input.type,
3370
+ scanned: page.rows.length,
3371
+ embedded,
3372
+ unindexable,
3373
+ failed: failures.length,
3374
+ failures,
3375
+ hasMore: page.hasMore,
3376
+ ...page.nextCursor !== void 0 ? { nextCursor: page.nextCursor } : {}
3377
+ };
3378
+ }
3379
+
3380
+ //#endregion
3381
+ //#region ../../plugins/substrate-recall/src/reindex-route.ts
3382
+ /**
3383
+ * POST /substrate/v1/embed/reindex — admin-gated server-side re-embed. Thin
3384
+ * transport adapter over `handleReindex`.
3385
+ *
3386
+ * Capability is `admin`, not `mutate`: `admin` is the only capability compose
3387
+ * enforces under `mode: 'attribute'`, so a `mutate` claim would leave the
3388
+ * route open to any caller there. See `KernelRouteClaim.capability`.
3389
+ */
3390
+ function reindexRouteHandler(cfg) {
3391
+ return async (req) => {
3392
+ const raw = req.body;
3393
+ if (raw === null || Buffer.isBuffer(raw) && raw.length === 0) return jsonResponse(400, {
3394
+ code: "bad_request",
3395
+ message: "request body is required"
3396
+ });
3397
+ let parsed;
3398
+ try {
3399
+ parsed = JSON.parse(Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw));
3400
+ } catch (err) {
3401
+ return jsonResponse(400, {
3402
+ code: "bad_request",
3403
+ message: err instanceof Error ? err.message : "invalid JSON"
3404
+ });
3405
+ }
3406
+ try {
3407
+ return jsonResponse(200, await handleReindex(validateReindexInput(parsed), cfg));
3408
+ } catch (err) {
3409
+ const code = err?.code;
3410
+ const message = err instanceof Error ? err.message : String(err);
3411
+ if (code === "bad_request" || code === "unknown_type") return jsonResponse(400, { error: {
3412
+ code,
3413
+ message
3414
+ } });
3415
+ if (code === "unavailable") return jsonResponse(503, { error: {
3416
+ code,
3417
+ message
3418
+ } });
3419
+ process.stderr.write(`reindex route failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
3420
+ return jsonResponse(500, { error: {
3421
+ code: "internal",
3422
+ message: "reindex failed"
3423
+ } });
3424
+ }
3425
+ };
3426
+ }
3427
+
3428
+ //#endregion
3429
+ //#region ../../plugins/substrate-recall/src/salience-boost-route.ts
3430
+ /**
3431
+ * POST /substrate/v1/salience/boost — explicit, consumer-driven salience
3432
+ * reinforcement (the write-side mirror of /substrate/v1/recall).
3433
+ *
3434
+ * Callers name the rows they actually used and bump their salience; the
3435
+ * explicit counterpart to recall's auto-boost (opt out with `boost:false`).
3436
+ *
3437
+ * Gated on both read and write policy. Denial is LOUD: the caller named
3438
+ * explicit targets, so a denied (namespace, type) scope fails the whole
3439
+ * request 403 `policy_denied`.
3440
+ *
3441
+ * Unlike the recall route's fire-and-forget boost, this AWAITS the store so
3442
+ * the caller gets a confirmation it can sequence against.
3443
+ */
3444
+ function parseBody(req) {
3445
+ const raw = req.body;
3446
+ if (raw === null || Buffer.isBuffer(raw) && raw.length === 0) return { error: "request body is required" };
3447
+ try {
3448
+ return { ok: JSON.parse(Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw)) };
3449
+ } catch (err) {
3450
+ return { error: err instanceof Error ? err.message : "invalid JSON" };
3451
+ }
3452
+ }
3453
+ /**
3454
+ * KernelRouteClaim handler factory for `POST /substrate/v1/salience/boost`.
3455
+ * Registered by `createRecallPlugin` alongside the recall route. Thin
3456
+ * transport adapter over `handleSalienceBoost` — JSON-parse + bind identity,
3457
+ * then map coded throws (bad_request → 400, policy_denied → 403) to envelopes.
3458
+ */
3459
+ function salienceBoostRouteHandler(cfg) {
3460
+ return async (req) => {
3461
+ const parsed = parseBody(req);
3462
+ if ("error" in parsed) return jsonResponse(400, {
3463
+ code: "bad_request",
3464
+ message: parsed.error
3465
+ });
3466
+ let input;
3467
+ try {
3468
+ input = validateBoostInput(parsed.ok);
3469
+ } catch (err) {
3470
+ return jsonResponse(400, {
3471
+ code: "bad_request",
3472
+ message: err instanceof Error ? err.message : String(err)
3473
+ });
3474
+ }
3475
+ const unbound = cfg.checkReadPolicy;
3476
+ const unboundWrite = cfg.checkWritePolicy;
3477
+ const caller = callerFromRequest(req);
3478
+ try {
3479
+ const out = await handleSalienceBoost(input, {
3480
+ store: cfg.store,
3481
+ halfLifeHours: (cfg.salience ?? DEFAULT_SALIENCE_CONFIG).halfLifeHours,
3482
+ ...unbound !== void 0 ? { checkReadPolicy: bindPolicy(unbound, caller) } : {},
3483
+ ...unboundWrite !== void 0 ? { checkWritePolicy: bindPolicy(unboundWrite, caller) } : {},
3484
+ caller,
3485
+ ...cfg.model !== void 0 ? { model: cfg.model } : {}
3486
+ });
3487
+ return jsonResponse(200, out);
3488
+ } catch (err) {
3489
+ const code = err?.code;
3490
+ const message = err instanceof Error ? err.message : String(err);
3491
+ if (code === "policy_denied") return jsonResponse(403, { error: {
3492
+ code: "policy_denied",
3493
+ message
3494
+ } });
3495
+ process.stderr.write(`salience-boost route failure: ${message}\n${err instanceof Error && err.stack ? err.stack : ""}\n`);
3496
+ return jsonResponse(500, { error: {
3497
+ code: "internal",
3498
+ message: "salience boost failed"
3499
+ } });
3500
+ }
3501
+ };
3502
+ }
3503
+
3504
+ //#endregion
3505
+ //#region ../../plugins/substrate-recall/src/spread-resolver.ts
3506
+ /**
3507
+ * Registry of opt-in spread edges, keyed by source `"ns/type"`. The plugin's
3508
+ * `contributePostWrites(namespace)` populates this as namespaces register.
3509
+ * Forward lookups read by source-row's `ns/type`; backward lookups read by
3510
+ * inbound-edge's `from.ns/from.type` to decide whether the edge is opt-in.
3511
+ */
3512
+ var SpreadEdgeRegistry = class {
3513
+ #byTypeKey = /* @__PURE__ */ new Map();
3514
+ /**
3515
+ * Register one opt-in edge. Idempotent on (ns, type, fieldName) — duplicate
3516
+ * registrations from re-installs are merged silently.
3517
+ */
3518
+ add(ns, type, spec) {
3519
+ const key = `${ns}/${type}`;
3520
+ const existing = this.#byTypeKey.get(key) ?? [];
3521
+ if (existing.some((s) => s.fieldName === spec.fieldName)) return;
3522
+ existing.push(spec);
3523
+ this.#byTypeKey.set(key, existing);
3524
+ }
3525
+ /**
3526
+ * Look up the opt-in crossRef fields for a given (ns, type). Returns an
3527
+ * empty array when nothing is registered — caller short-circuits cleanly.
3528
+ */
3529
+ forType(ns, type) {
3530
+ return this.#byTypeKey.get(`${ns}/${type}`) ?? [];
3531
+ }
3532
+ /** Total registered edges, for tests + introspection. */
3533
+ size() {
3534
+ let total = 0;
3535
+ for (const arr of this.#byTypeKey.values()) total += arr.length;
3536
+ return total;
3537
+ }
3538
+ };
3539
+ /**
3540
+ * Build a resolver that enumerates spread targets for a batch of boosted
3541
+ * rows. Closes over the registry + an EdgesStore handle so the recall route
3542
+ * can call it without taking on either dependency directly.
3543
+ *
3544
+ * When `edges` is `null`, the backward direction is a no-op; forward still
3545
+ * works because it only reads `row` field values.
3546
+ *
3547
+ * The returned function dedupes targets across sources: if A and B both
3548
+ * forward-link to the same Concept, the Concept appears once in the output.
3549
+ */
3550
+ function makeSpreadResolver(registry, edges) {
3551
+ return async (sources) => {
3552
+ if (sources.length === 0) return [];
3553
+ const seen = /* @__PURE__ */ new Set();
3554
+ const out = [];
3555
+ const sourceKeys = new Set(sources.map((s) => `${s.namespace}/${s.type}/${s.id}`));
3556
+ const push = (t) => {
3557
+ const k = `${t.namespace}/${t.type}/${t.id}`;
3558
+ if (sourceKeys.has(k)) return;
3559
+ if (seen.has(k)) return;
3560
+ seen.add(k);
3561
+ out.push(t);
3562
+ };
3563
+ for (const src of sources) {
3564
+ const specs = registry.forType(src.namespace, src.type);
3565
+ for (const spec of specs) {
3566
+ const value = src.row[spec.fieldName];
3567
+ if (typeof value === "string" && value.length > 0) push({
3568
+ namespace: spec.targetNs,
3569
+ type: spec.targetType,
3570
+ id: value
3571
+ });
3572
+ }
3573
+ }
3574
+ if (edges !== null) {
3575
+ const inbound = await edges.findEdgesToMany(sources.map((s) => ({
3576
+ ns: s.namespace,
3577
+ type: s.type,
3578
+ id: s.id
3579
+ })));
3580
+ for (const edge of inbound) {
3581
+ if (!registry.forType(edge.from.ns, edge.from.type).some((s) => s.fieldName === edge.fieldName && s.targetNs === edge.to.ns && s.targetType === edge.to.type)) continue;
3582
+ push({
3583
+ namespace: edge.from.ns,
3584
+ type: edge.from.type,
3585
+ id: String(edge.from.id)
3586
+ });
3587
+ }
3588
+ }
3589
+ return out;
3590
+ };
3591
+ }
3592
+
3593
+ //#endregion
3594
+ //#region ../../plugins/substrate-recall/src/plugin.ts
3595
+ const DEFAULT_CLUSTER_DIMENSION = 768;
3596
+ const DEFAULT_QUERY_EMBED_TIMEOUT_MS = 3e4;
3597
+ /** `embedder` with `timeoutMs` applied to every call that does not set its own. */
3598
+ function withQueryTimeout(embedder, timeoutMs) {
3599
+ return {
3600
+ modelId: embedder.modelId,
3601
+ dimension: embedder.dimension,
3602
+ embed: (text, opts) => embedder.embed(text, {
3603
+ ...opts,
3604
+ timeoutMs: opts?.timeoutMs ?? timeoutMs
3605
+ })
3606
+ };
3607
+ }
3608
+ /**
3609
+ * Run two post-write hooks in sequence as one.
3610
+ *
3611
+ * Sequential rather than concurrent because each hook already swallows its own
3612
+ * failures, so there is nothing to race and ordering keeps the stderr trail
3613
+ * readable when both arms fail on the same row.
3614
+ */
3615
+ function composeHooks(first, second) {
3616
+ if (first === void 0) return second;
3617
+ return async (row, ctx) => {
3618
+ await first(row, ctx);
3619
+ await second(row, ctx);
3620
+ };
3621
+ }
3622
+ /**
3623
+ * Build the EmbedSourceContext factory threaded into each embedded type's
3624
+ * postWrite. The factory is invoked once per postWrite call, so the
3625
+ * closure stays small; the dataset lookup happens at `ctx.read(...)` time
3626
+ * inside the source function.
3627
+ */
3628
+ function makeEmbedSourceContext(resolveDataset) {
3629
+ return { read: async (ns, type, params) => {
3630
+ const dataset = resolveDataset(ns);
3631
+ if (dataset === null) return null;
3632
+ return (await dataset.read(type, { id: params.id })).rows[0] ?? null;
3633
+ } };
3634
+ }
3635
+ function createRecallPlugin(cfg) {
3636
+ const stats = cfg.stats ?? createEmbedStats();
3637
+ const queryEmbedder = cfg.embedder === void 0 ? void 0 : withQueryTimeout(cfg.embedder, cfg.queryEmbedTimeoutMs ?? 3e4);
3638
+ const spreadRegistry = new SpreadEdgeRegistry();
3639
+ const embedSourceRegistry = new EmbedSourceRegistry();
3640
+ const lexicalSourceRegistry = new LexicalSourceRegistry();
3641
+ const spreadResolver = makeSpreadResolver(spreadRegistry, cfg.edges ?? null);
3642
+ const expansionResolver = makeExpansionResolver(spreadRegistry, cfg.edges ?? null, {
3643
+ maxNeighboursPerSeed: cfg.expansion?.maxNeighboursPerSeed ?? 8,
3644
+ maxTotalNeighbours: cfg.expansion?.maxTotalNeighbours ?? 50
3645
+ });
3646
+ const recallCoreDeps = {
3647
+ ...queryEmbedder !== void 0 ? { embedder: queryEmbedder } : {},
3648
+ store: cfg.store,
3649
+ ...cfg.lexicalStore !== void 0 ? { lexicalStore: cfg.lexicalStore } : {},
3650
+ lexicalSources: lexicalSourceRegistry,
3651
+ embedSources: embedSourceRegistry,
3652
+ ...cfg.salience !== void 0 ? { salience: cfg.salience } : {},
3653
+ spreadResolver,
3654
+ expansionResolver,
3655
+ expansionEnabled: cfg.expansion?.enabled ?? true,
3656
+ ...cfg.embedder !== void 0 ? { stats } : {},
3657
+ ...cfg.checkReadPolicy !== void 0 ? { checkReadPolicy: cfg.checkReadPolicy } : {},
3658
+ ...cfg.checkWritePolicy !== void 0 ? { checkWritePolicy: cfg.checkWritePolicy } : {}
3659
+ };
3660
+ const formationLock = cfg.clusters?.withFormationLock?.bind(cfg.clusters);
3661
+ const crystalliseGuard = createCrystalliseGuard(formationLock === void 0 ? {} : { crossProcess: formationLock });
3662
+ const crystalliseDeps = cfg.clusters === void 0 ? void 0 : {
3663
+ embeddings: cfg.store,
3664
+ clusters: cfg.clusters,
3665
+ model: cfg.embedder?.modelId ?? "unknown",
3666
+ config: cfg.crystallise ?? DEFAULT_CRYSTALLISE_CONFIG,
3667
+ guard: crystalliseGuard,
3668
+ ...cfg.rowsMissing !== void 0 ? { rowsMissing: cfg.rowsMissing } : {},
3669
+ ...cfg.checkReadPolicy !== void 0 ? { checkReadPolicy: cfg.checkReadPolicy } : {},
3670
+ ...cfg.runClusterer !== void 0 ? { runClusterer: cfg.runClusterer } : {}
3671
+ };
3672
+ return {
3673
+ name: "substrate-recall",
3674
+ contractVersion: ">=1.0.0-alpha.0 <2.0.0",
3675
+ async onKernelReady(ctx) {
3676
+ if (cfg.embedder === void 0 || ctx.sql === null) return;
3677
+ const report = await alignVectorDimensions(ctx.sql, {
3678
+ dimension: cfg.embedder.dimension,
3679
+ ...cfg.migration?.hnswM !== void 0 ? { hnswM: cfg.migration.hnswM } : {},
3680
+ ...cfg.migration?.hnswEfConstruction !== void 0 ? { hnswEfConstruction: cfg.migration.hnswEfConstruction } : {}
3681
+ });
3682
+ for (const [column, state] of [["embeddings.embedding", report.embeddings], ["recall_clusters.centroid", report.centroids]]) {
3683
+ if (state !== "populated") continue;
3684
+ const found = column.startsWith("embeddings") ? report.found.embeddings : report.found.centroids;
3685
+ ctx.metric("recall_dimension_mismatch", {
3686
+ column,
3687
+ stored: found,
3688
+ embedder: cfg.embedder.dimension,
3689
+ model: cfg.embedder.modelId
3690
+ });
3691
+ process.emitWarning(`${column} is vector(${found}) and holds rows, but the embedder is ${cfg.embedder.modelId} at ${cfg.embedder.dimension}. Writes to it will fail until the rows are cleared (they are derived) and re-embedded: delete them, restart, then POST /substrate/v1/embed/reindex.`, { code: "RECALL_DIMENSION_MISMATCH" });
3692
+ }
3693
+ },
3694
+ migrations: [
3695
+ embeddingsMigration(cfg.migration ?? {}),
3696
+ recallClustersMigration({ dimension: cfg.migration?.dimension ?? DEFAULT_CLUSTER_DIMENSION }),
3697
+ lexicalMigration(cfg.lexicalMigration ?? {})
3698
+ ],
3699
+ filterOperators: queryEmbedder !== void 0 ? { embeddingSimilar: embeddingSimilarOperator({
3700
+ embedder: queryEmbedder,
3701
+ store: cfg.store
3702
+ }) } : {},
3703
+ kernelRoutes: [
3704
+ {
3705
+ path: "recall",
3706
+ method: "POST",
3707
+ capability: "read",
3708
+ handler: recallRouteHandler(recallCoreDeps)
3709
+ },
3710
+ {
3711
+ path: "embed-stats",
3712
+ method: "GET",
3713
+ capability: "read",
3714
+ handler: embedStatsRouteHandler(cfg.embedder !== void 0 ? stats : void 0, embedSourceRegistry, lexicalSourceRegistry, {
3715
+ lexicalEnabled: cfg.lexicalStore !== void 0,
3716
+ ...cfg.lexicalStore !== void 0 ? { lexicalStore: cfg.lexicalStore } : {},
3717
+ ...cfg.resolveDataset !== void 0 ? { resolveDataset: cfg.resolveDataset } : {}
3718
+ })
3719
+ },
3720
+ {
3721
+ path: "embeddings/fetch",
3722
+ method: "POST",
3723
+ capability: "read",
3724
+ handler: embeddingsFetchRouteHandler({
3725
+ store: cfg.store,
3726
+ ...cfg.embedder !== void 0 ? { embedder: cfg.embedder } : {},
3727
+ ...cfg.salience !== void 0 ? { salience: cfg.salience } : {},
3728
+ ...cfg.checkReadPolicy !== void 0 ? { checkReadPolicy: cfg.checkReadPolicy } : {},
3729
+ ...cfg.checkWritePolicy !== void 0 ? { checkWritePolicy: cfg.checkWritePolicy } : {}
3730
+ })
3731
+ },
3732
+ {
3733
+ path: "salience/boost",
3734
+ method: "POST",
3735
+ capability: "mutate",
3736
+ handler: salienceBoostRouteHandler({
3737
+ store: cfg.store,
3738
+ ...cfg.embedder !== void 0 ? { model: cfg.embedder.modelId } : {},
3739
+ ...cfg.salience !== void 0 ? { salience: cfg.salience } : {},
3740
+ ...cfg.checkReadPolicy !== void 0 ? { checkReadPolicy: cfg.checkReadPolicy } : {},
3741
+ ...cfg.checkWritePolicy !== void 0 ? { checkWritePolicy: cfg.checkWritePolicy } : {}
3742
+ })
3743
+ },
3744
+ {
3745
+ path: "crystallise",
3746
+ method: "POST",
3747
+ capability: "mutate",
3748
+ handler: crystalliseRouteHandler({
3749
+ embeddings: cfg.store,
3750
+ ...cfg.clusters !== void 0 ? { clusters: cfg.clusters } : {},
3751
+ model: crystalliseDeps?.model ?? "unknown",
3752
+ config: cfg.crystallise ?? DEFAULT_CRYSTALLISE_CONFIG,
3753
+ guard: crystalliseGuard,
3754
+ ...cfg.rowsMissing !== void 0 ? { rowsMissing: cfg.rowsMissing } : {},
3755
+ ...cfg.checkReadPolicy !== void 0 ? { checkReadPolicy: cfg.checkReadPolicy } : {},
3756
+ ...cfg.runClusterer !== void 0 ? { runClusterer: cfg.runClusterer } : {}
3757
+ })
3758
+ },
3759
+ {
3760
+ path: "embed/reindex",
3761
+ method: "POST",
3762
+ capability: "admin",
3763
+ handler: reindexRouteHandler({
3764
+ registry: embedSourceRegistry,
3765
+ ...cfg.resolveDataset !== void 0 ? { resolveDataset: cfg.resolveDataset } : {}
3766
+ })
3767
+ },
3768
+ {
3769
+ path: "lexical/reindex",
3770
+ method: "POST",
3771
+ capability: "admin",
3772
+ handler: lexicalReindexRouteHandler({
3773
+ registry: lexicalSourceRegistry,
3774
+ ...cfg.resolveDataset !== void 0 ? { resolveDataset: cfg.resolveDataset } : {}
3775
+ })
3776
+ }
3777
+ ],
3778
+ mcpTools: [recallMcpTool(recallCoreDeps)],
3779
+ kernelNamespace: buildRecallFrameSurface({
3780
+ ...recallCoreDeps,
3781
+ ...crystalliseDeps !== void 0 ? { clusterSurface: crystalliseDeps } : {}
3782
+ }),
3783
+ contributePostWrites(namespace) {
3784
+ for (const [typeName, typeDef] of Object.entries(namespace.types ?? {})) {
3785
+ const fields = typeDef.fields ?? {};
3786
+ for (const [fieldName, fieldDef] of Object.entries(fields)) {
3787
+ if (fieldDef.kind !== "crossRef") continue;
3788
+ if (fieldDef.spread !== true) continue;
3789
+ spreadRegistry.add(namespace.namespace, typeName, {
3790
+ fieldName,
3791
+ targetNs: fieldDef.ns,
3792
+ targetType: fieldDef.type,
3793
+ ...fieldDef.expandCrossType === true ? { expandCrossType: true } : {}
3794
+ });
3795
+ }
3796
+ }
3797
+ const out = {};
3798
+ if (cfg.lexicalStore !== void 0) for (const [typeName, typeDef] of Object.entries(namespace.types ?? {})) {
3799
+ if (typeDef.lexical?.source === void 0) continue;
3800
+ const binding = {
3801
+ namespace: namespace.namespace,
3802
+ type: typeName,
3803
+ source: typeDef.lexical.source,
3804
+ store: cfg.lexicalStore
3805
+ };
3806
+ const hook = makeLexicalPostWrite(binding);
3807
+ out[typeName] = hook;
3808
+ lexicalSourceRegistry.add({
3809
+ namespace: namespace.namespace,
3810
+ type: typeName,
3811
+ hook,
3812
+ reindex: makeLexicalReindex(binding),
3813
+ classify: makeLexicalClassify(binding)
3814
+ });
3815
+ }
3816
+ if (cfg.embedder === void 0) return out;
3817
+ const embedSourceContext = cfg.resolveDataset !== void 0 ? makeEmbedSourceContext(cfg.resolveDataset) : void 0;
3818
+ for (const [typeName, typeDef] of Object.entries(namespace.types ?? {})) {
3819
+ if (typeDef.embed?.source === void 0) continue;
3820
+ const binding = {
3821
+ namespace: namespace.namespace,
3822
+ type: typeName,
3823
+ source: typeDef.embed.source,
3824
+ embedder: cfg.embedder,
3825
+ store: cfg.store,
3826
+ stats,
3827
+ ...embedSourceContext !== void 0 ? { embedSourceContext } : {}
3828
+ };
3829
+ const hook = makeEmbedPostWrite(binding);
3830
+ out[typeName] = composeHooks(out[typeName], hook);
3831
+ embedSourceRegistry.add({
3832
+ namespace: namespace.namespace,
3833
+ type: typeName,
3834
+ hook,
3835
+ reembed: makeReembed(binding)
3836
+ });
3837
+ }
3838
+ return out;
3839
+ }
3840
+ };
3841
+ }
3842
+
3843
+ //#endregion
3844
+ export { CLUSTERER_BACKEND_VERSION as $, CLUSTER_MEMBER_FIELDS as A, ROW_FILTER_FIELD as B, EmbedSourceRegistry as C, makeReembed as D, makeEmbedPostWrite as E, unknownParams as F, DEFAULT_CRYSTALLISE_CONFIG as G, CRYSTALLISE_IN_FLIGHT_CODE as H, handleRecallRequest as I, runClusterer as J, handleCrystallise as K, RRF_K as L, recallRouteHandler as M, checkParams as N, crystalliseRouteHandler as O, unknownParamMessage as P, CLUSTERER_BACKEND as Q, armRanks as R, createEmbedStats as S, embedRowReporting as T, createCrystalliseGuard as U, matchesRowFilter as V, inFlightError as W, l2normalize as X, unresolvedRow as Y, cosineSimilarity as Z, EMBEDDINGS_FETCH_MAX_REFS as _, REINDEX_MAX_LIMIT as a, handleLexicalCoverage as b, SALIENCE_BOOST_MAX_TARGETS as c, embeddingsMigration as d, memberKey as et, recallMcpTool as f, embeddingsFetchRouteHandler as g, embeddingSimilarOperator as h, REINDEX_DEFAULT_LIMIT as i, buildClusterSurface as j, CLUSTER_FIELDS as k, lexicalMigration as l, makeLexicalPostWrite as m, salienceBoostRouteHandler as n, validateSelector as nt, handleReindex as o, makeLexicalClassify as p, validateCrystalliseInput as q, reindexRouteHandler as r, validateReindexInput as s, createRecallPlugin as t, SELECT_CANDIDATES_MAX_LIMIT as tt, recallClustersMigration as u, embedStatsRouteHandler as v, embedAndStore as w, validateLexicalCoverageInput as x, handleEmbedStatsRequest as y, fuseByRank as z };