@crewhaus/tool-state 0.7.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.
- package/README.md +268 -0
- package/dist/index.d.ts +43 -0
- package/dist/index.js +1858 -0
- package/dist/lib/bm25.d.ts +117 -0
- package/dist/lib/bm25.js +245 -0
- package/dist/lib/jsonl.d.ts +47 -0
- package/dist/lib/jsonl.js +102 -0
- package/dist/lib/names.d.ts +41 -0
- package/dist/lib/names.js +144 -0
- package/dist/lib/records.d.ts +66 -0
- package/dist/lib/records.js +106 -0
- package/dist/paths.d.ts +52 -0
- package/dist/paths.js +203 -0
- package/dist/store.d.ts +128 -0
- package/dist/store.js +502 -0
- package/dist/vector.d.ts +248 -0
- package/dist/vector.js +445 -0
- package/package.json +45 -0
package/dist/vector.js
ADDED
|
@@ -0,0 +1,445 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `VectorDelete`'s seam: the vector store it deletes from, the selection it
|
|
3
|
+
* runs against that store, and the two observations it is able to make.
|
|
4
|
+
*
|
|
5
|
+
* WHY THIS IS ITS OWN MODULE. Every other tool in this package touches files
|
|
6
|
+
* under the workspace and nothing else — `index.ts` says so, and
|
|
7
|
+
* `index.test.ts` asserts `scope: "internal"` with no `ioCapability` for all
|
|
8
|
+
* twenty members of `STATE_TOOLS`. A vector store is not that: one interface
|
|
9
|
+
* covers an in-process Map, a file-backed lance index and an HTTP collection
|
|
10
|
+
* on qdrant, pinecone or weaviate. `VectorDelete` therefore declares
|
|
11
|
+
* `scope: "external"` + `ioCapability: "network"`, and is deliberately NOT a
|
|
12
|
+
* member of `STATE_TOOLS` — that list's membership is exactly what the
|
|
13
|
+
* no-boundary test checks, and a list that quietly stopped meaning what it
|
|
14
|
+
* says would be worse than no test at all. `VECTOR_TOOLS` holds it instead.
|
|
15
|
+
*
|
|
16
|
+
* WHY NOTHING HERE IMPORTS `@crewhaus/vector-store`. {@link VectorDeleteTarget}
|
|
17
|
+
* is the structural slice of that package's `VectorStore` a delete needs, and
|
|
18
|
+
* every store it builds already satisfies it — so the tool costs this package
|
|
19
|
+
* no new runtime dependency. The price is that the store must be handed in by
|
|
20
|
+
* whoever built it ({@link registerVectorTarget}, the seam
|
|
21
|
+
* `@crewhaus/tool-retrieve` already uses as `registerRetrieveConfig`): nothing
|
|
22
|
+
* here can construct a store from a backend name. There is deliberately NO
|
|
23
|
+
* ambient fallback — with nothing registered the tool refuses, because an
|
|
24
|
+
* implicit empty in-process store would let a right-to-erasure call report a
|
|
25
|
+
* clean success having deleted nothing at all.
|
|
26
|
+
*
|
|
27
|
+
* WHAT CANNOT BE KNOWN HERE, and so is never claimed. The store interface
|
|
28
|
+
* exposes neither `exists` nor `get`, so per-id truth is unobtainable: a
|
|
29
|
+
* `delete(id)` that resolves means the store ACCEPTED the request, not that
|
|
30
|
+
* the id was there or that the vector is now gone. Every name below says
|
|
31
|
+
* "attempted" or "acknowledged" for that reason, and there is no
|
|
32
|
+
* deleted/missing split anywhere — a caller erasing someone's data on legal
|
|
33
|
+
* request has to be able to read this result without being misled by it.
|
|
34
|
+
* `count()` is not a way round that either: on the HTTP backends it is
|
|
35
|
+
* eventually consistent, so a count taken immediately after a delete can
|
|
36
|
+
* equal the one before it for deletes that did land.
|
|
37
|
+
*/
|
|
38
|
+
import { CrewhausError } from "@crewhaus/errors";
|
|
39
|
+
import { compareStrings, validateKey } from "./lib/names";
|
|
40
|
+
/** Most ids one call takes. Bounds the work, and the result, per call. */
|
|
41
|
+
export const MAX_VECTOR_IDS = 1_000;
|
|
42
|
+
/** Most entries echoed back in the `idsRejected` / `deletesErrored` lists. */
|
|
43
|
+
const MAX_LISTED = 20;
|
|
44
|
+
/** Longest store-error message carried into a result. A failing HTTP backend
|
|
45
|
+
* can hand back a whole error page, and a result is a model's context. */
|
|
46
|
+
const MAX_STORE_ERROR_CHARS = 200;
|
|
47
|
+
/** Longest id echoed back in a rejection. A rejected id is DISPLAY ONLY — it
|
|
48
|
+
* is never the thing acted on — so truncating it here cannot mis-target a
|
|
49
|
+
* delete, while echoing a 100 kB id would cost the caller its whole context. */
|
|
50
|
+
const MAX_REJECTED_ID_CHARS = 80;
|
|
51
|
+
/** Raised when the registration itself is unusable. */
|
|
52
|
+
export class VectorTargetError extends CrewhausError {
|
|
53
|
+
name = "VectorTargetError";
|
|
54
|
+
constructor(message, cause) {
|
|
55
|
+
super("config", message, cause);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
let activeTarget;
|
|
59
|
+
/**
|
|
60
|
+
* Replace the registered vector store. The host calls this at boot with the
|
|
61
|
+
* store it already built for retrieval, so a delete and a search address the
|
|
62
|
+
* same collection.
|
|
63
|
+
*
|
|
64
|
+
* The shape is checked HERE rather than at the first call: a missing method
|
|
65
|
+
* discovered during an erasure request is discovered at the worst moment. The
|
|
66
|
+
* SAME argument covers the other three fields, which is why they are checked
|
|
67
|
+
* here too rather than trusted to the type: `collection` and
|
|
68
|
+
* `protectedCollections` are the whole of the gate, and `countConsistency`
|
|
69
|
+
* decides how strong a claim the result makes. Each of them used to fail
|
|
70
|
+
* OPEN when it was not what it said it was — see the three refusals below.
|
|
71
|
+
*/
|
|
72
|
+
export function registerVectorTarget(registration) {
|
|
73
|
+
const store = registration?.store;
|
|
74
|
+
if (store === undefined ||
|
|
75
|
+
typeof store.delete !== "function" ||
|
|
76
|
+
typeof store.count !== "function") {
|
|
77
|
+
throw new VectorTargetError("registerVectorTarget needs a store with delete(id) and count() — pass the same VectorStore the retriever uses");
|
|
78
|
+
}
|
|
79
|
+
const { collection, protectedCollections, countConsistency } = registration;
|
|
80
|
+
// An empty or non-string name is not a name. Read as one it was worse than
|
|
81
|
+
// absent: `collection: ""` is `!== undefined`, so the gate called the
|
|
82
|
+
// collection KNOWN, compared "" against the protection list, matched
|
|
83
|
+
// nothing and allowed the delete — where an absent name would have refused.
|
|
84
|
+
// A non-string one got as far as `collection.toLowerCase()` and threw a
|
|
85
|
+
// TypeError out of `execute` mid-erasure.
|
|
86
|
+
if (collection !== undefined && (typeof collection !== "string" || collection.length === 0)) {
|
|
87
|
+
throw new VectorTargetError(`registerVectorTarget's \`collection\` must be a non-empty string when given, not ${describeStoreValue(collection)} — a name the gate cannot compare must be omitted, so that it refuses instead of passing`);
|
|
88
|
+
}
|
|
89
|
+
// NOT a truthiness check, and not `for (const x of list)` either: a bare
|
|
90
|
+
// string is iterable, so `protectedCollections: "audit"` spread into
|
|
91
|
+
// ["a","u","d","i","t"] and left "audit" itself unprotected — a deny-list
|
|
92
|
+
// silently replaced by one that denies nothing it names.
|
|
93
|
+
if (protectedCollections !== undefined &&
|
|
94
|
+
(!Array.isArray(protectedCollections) ||
|
|
95
|
+
protectedCollections.some((name) => typeof name !== "string" || name.length === 0))) {
|
|
96
|
+
throw new VectorTargetError("registerVectorTarget's `protectedCollections` must be an array of non-empty strings — a bare string is read one character at a time and protects nothing it names");
|
|
97
|
+
}
|
|
98
|
+
// Anything but the two known words used to come out as `=== "eventual"` is
|
|
99
|
+
// false, i.e. as the STRONGER claim: a typo made `countAfter` sound
|
|
100
|
+
// authoritative on qdrant. An unreadable setting is not the confident one.
|
|
101
|
+
if (countConsistency !== undefined &&
|
|
102
|
+
countConsistency !== "immediate" &&
|
|
103
|
+
countConsistency !== "eventual") {
|
|
104
|
+
throw new VectorTargetError(`registerVectorTarget's \`countConsistency\` must be "immediate" or "eventual", not ${describeStoreValue(countConsistency)}`);
|
|
105
|
+
}
|
|
106
|
+
activeTarget = registration;
|
|
107
|
+
}
|
|
108
|
+
export function getVectorTarget() {
|
|
109
|
+
return activeTarget;
|
|
110
|
+
}
|
|
111
|
+
/** Test-only — back to "nothing registered", which is the shipped default. */
|
|
112
|
+
export function _resetVectorTarget() {
|
|
113
|
+
activeTarget = undefined;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Backends whose `count()` reads back its own writes. Everything else —
|
|
117
|
+
* qdrant, pinecone, weaviate, lance, and any store that does not name itself —
|
|
118
|
+
* falls through to "indicative", which is the fail-closed answer: claiming a
|
|
119
|
+
* count is authoritative when it is not is the overclaim this tool exists to
|
|
120
|
+
* avoid.
|
|
121
|
+
*/
|
|
122
|
+
const IMMEDIATE_COUNT_BACKENDS = new Set(["in-memory"]);
|
|
123
|
+
/**
|
|
124
|
+
* The store's self-reported backend NAME, or `undefined` when it did not give
|
|
125
|
+
* one. Only a non-empty string is a name: a store whose `backend` is an
|
|
126
|
+
* object has not named itself, and `undefined` is the honest reading of that.
|
|
127
|
+
*
|
|
128
|
+
* One function, so the name the result REPORTS and the name
|
|
129
|
+
* {@link countIsIndicative} DECIDES on are the same reading of the same field.
|
|
130
|
+
*/
|
|
131
|
+
function backendName(store) {
|
|
132
|
+
const backend = store.backend;
|
|
133
|
+
return typeof backend === "string" && backend.length > 0 ? backend : undefined;
|
|
134
|
+
}
|
|
135
|
+
/** Longest backend name echoed into a result. Display only — the decision in
|
|
136
|
+
* {@link countIsIndicative} uses the whole name, so a long one cannot be
|
|
137
|
+
* truncated into a match for a shorter one. */
|
|
138
|
+
const MAX_BACKEND_CHARS = 60;
|
|
139
|
+
/** The backend name for the result, bounded, or `"unknown"`. */
|
|
140
|
+
export function describeBackend(store) {
|
|
141
|
+
const name = backendName(store);
|
|
142
|
+
if (name === undefined)
|
|
143
|
+
return "unknown";
|
|
144
|
+
return name.length > MAX_BACKEND_CHARS ? `${name.slice(0, MAX_BACKEND_CHARS)}…` : name;
|
|
145
|
+
}
|
|
146
|
+
/** Is `countAfter` indicative only? An explicit registration wins over the
|
|
147
|
+
* backend name, which is only a self-report. */
|
|
148
|
+
export function countIsIndicative(registration) {
|
|
149
|
+
if (registration.countConsistency !== undefined) {
|
|
150
|
+
// Written as "anything that is not the word `immediate`", never as
|
|
151
|
+
// `=== "eventual"`: a target built without going through
|
|
152
|
+
// `registerVectorTarget` can still carry a typo, and the typo must come
|
|
153
|
+
// out as the CAUTIOUS answer. `=== "eventual"` gave the confident one.
|
|
154
|
+
return registration.countConsistency !== "immediate";
|
|
155
|
+
}
|
|
156
|
+
const backend = backendName(registration.store);
|
|
157
|
+
return backend === undefined || !IMMEDIATE_COUNT_BACKENDS.has(backend);
|
|
158
|
+
}
|
|
159
|
+
/** A non-negative decimal integer, and nothing else.
|
|
160
|
+
*
|
|
161
|
+
* `Number.parseInt` would read "12abc" as 12 and "0x10" as 0 — it stops at
|
|
162
|
+
* the first character it cannot use, which turns a malformed id into a
|
|
163
|
+
* plausible one. This refuses the whole string instead. */
|
|
164
|
+
function parseNonNegativeInt(text) {
|
|
165
|
+
if (!/^(?:0|[1-9][0-9]*)$/.test(text))
|
|
166
|
+
return undefined;
|
|
167
|
+
const value = Number(text);
|
|
168
|
+
return Number.isSafeInteger(value) ? value : undefined;
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* Parse a chunk id, or `undefined` when it is not one.
|
|
172
|
+
*
|
|
173
|
+
* Read from the RIGHT. A docId is routinely a URL or a path
|
|
174
|
+
* (`https://example.com/a:0:400`, `C:\docs\x.md:3:120`), so it contains
|
|
175
|
+
* colons of its own: splitting on the first colon, or demanding exactly three
|
|
176
|
+
* colon-separated fields, mis-parses those ids. The survey sketch this tool
|
|
177
|
+
* came from specified that naive split; the two numeric fields are the LAST
|
|
178
|
+
* two, and everything before them is the docId.
|
|
179
|
+
*/
|
|
180
|
+
export function parseChunkId(id) {
|
|
181
|
+
const last = id.lastIndexOf(":");
|
|
182
|
+
if (last <= 0)
|
|
183
|
+
return undefined;
|
|
184
|
+
const prev = id.lastIndexOf(":", last - 1);
|
|
185
|
+
if (prev <= 0)
|
|
186
|
+
return undefined;
|
|
187
|
+
const index = parseNonNegativeInt(id.slice(prev + 1, last));
|
|
188
|
+
const startOffset = parseNonNegativeInt(id.slice(last + 1));
|
|
189
|
+
if (index === undefined || startOffset === undefined)
|
|
190
|
+
return undefined;
|
|
191
|
+
return { docId: id.slice(0, prev), index, startOffset };
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Turn the caller's `ids` into the selection a run acts on. The dry run and
|
|
195
|
+
* the real run call THIS — there is no second, kinder preview path, which is
|
|
196
|
+
* how a dry run ends up predicting something the real run will not do.
|
|
197
|
+
*
|
|
198
|
+
* Nothing is trimmed, case-folded or otherwise normalised. A store may hold an
|
|
199
|
+
* id with a trailing space; "delete a near-miss of what you asked for" is not
|
|
200
|
+
* a thing an erasure tool may do, so the id validated is the id deleted and
|
|
201
|
+
* the id reported.
|
|
202
|
+
*/
|
|
203
|
+
export function selectVectorIds(ids, opts) {
|
|
204
|
+
const seen = new Set();
|
|
205
|
+
const kept = [];
|
|
206
|
+
const rejected = [];
|
|
207
|
+
let duplicatesCollapsed = 0;
|
|
208
|
+
for (const id of ids) {
|
|
209
|
+
const bad = validateKey("id", id);
|
|
210
|
+
if (bad !== undefined) {
|
|
211
|
+
rejected.push({ id: previewId(id), reason: bad });
|
|
212
|
+
continue;
|
|
213
|
+
}
|
|
214
|
+
if (opts.requireChunkIdShape && parseChunkId(id) === undefined) {
|
|
215
|
+
rejected.push({
|
|
216
|
+
id: previewId(id),
|
|
217
|
+
reason: "not a '<docId>:<index>:<startOffset>' chunk id",
|
|
218
|
+
});
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
if (seen.has(id)) {
|
|
222
|
+
duplicatesCollapsed += 1;
|
|
223
|
+
continue;
|
|
224
|
+
}
|
|
225
|
+
seen.add(id);
|
|
226
|
+
kept.push(id);
|
|
227
|
+
}
|
|
228
|
+
// Sorted, so a half-finished run is reproducible and resumable: the same
|
|
229
|
+
// input always attempts the same ids in the same order. Plain code-unit
|
|
230
|
+
// order, never `localeCompare`, like every other listing in this package.
|
|
231
|
+
kept.sort(compareStrings);
|
|
232
|
+
return { ids: kept, rejected, duplicatesCollapsed };
|
|
233
|
+
}
|
|
234
|
+
function previewId(id) {
|
|
235
|
+
return id.length > MAX_REJECTED_ID_CHARS ? `${id.slice(0, MAX_REJECTED_ID_CHARS)}…` : id;
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* The one gate, run ONCE before anything is deleted.
|
|
239
|
+
*
|
|
240
|
+
* Per-id would be worse than useless: a refusal on the fourth of ten ids
|
|
241
|
+
* leaves three deleted and a dry run that predicted none of it. So this
|
|
242
|
+
* answers before the first `delete()` — before the store is touched at all —
|
|
243
|
+
* and a refusal means nothing happened.
|
|
244
|
+
*
|
|
245
|
+
* Two fail-closed rules:
|
|
246
|
+
*
|
|
247
|
+
* - An UNKNOWN collection with a protection list is a refusal, not a pass.
|
|
248
|
+
* "Could not determine" is not "no": if the host did not say which
|
|
249
|
+
* collection the store is bound to, this cannot prove it is not the
|
|
250
|
+
* protected one.
|
|
251
|
+
* - A name that matches a protected one except in case is refused as
|
|
252
|
+
* protected. Collection names are case-sensitive on the real backends, so
|
|
253
|
+
* `Chunks` and `chunks` are different collections — but a protection list
|
|
254
|
+
* that misses by a capital letter is a config slip whose cost is deleted
|
|
255
|
+
* data, while a needless refusal costs one edit.
|
|
256
|
+
*/
|
|
257
|
+
export function checkCollection(args) {
|
|
258
|
+
const { collection, protectedCollections, expectCollection } = args;
|
|
259
|
+
if (expectCollection !== undefined) {
|
|
260
|
+
if (collection === undefined) {
|
|
261
|
+
return {
|
|
262
|
+
code: "collection-unknown",
|
|
263
|
+
message: `the registered store declares no collection, so it cannot be confirmed to be "${expectCollection}"`,
|
|
264
|
+
};
|
|
265
|
+
}
|
|
266
|
+
if (collection !== expectCollection) {
|
|
267
|
+
return {
|
|
268
|
+
code: "collection-mismatch",
|
|
269
|
+
message: `the registered store is bound to "${collection}", not the "${expectCollection}" you expected`,
|
|
270
|
+
};
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
if (protectedCollections.length === 0)
|
|
274
|
+
return undefined;
|
|
275
|
+
if (collection === undefined) {
|
|
276
|
+
return {
|
|
277
|
+
code: "collection-unknown",
|
|
278
|
+
message: "the registered store declares no collection, so it cannot be shown not to be one of the protected ones — register the store with its collection name, or drop the protection list",
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
if (protectedCollections.includes(collection)) {
|
|
282
|
+
return { code: "protected-collection", message: `"${collection}" is a protected collection` };
|
|
283
|
+
}
|
|
284
|
+
const nearMiss = protectedCollections.find((name) => name.toLowerCase() === collection.toLowerCase());
|
|
285
|
+
if (nearMiss !== undefined) {
|
|
286
|
+
return {
|
|
287
|
+
code: "protected-collection",
|
|
288
|
+
message: `"${collection}" differs only in case from the protected "${nearMiss}" — refused rather than guessed; make the two agree`,
|
|
289
|
+
};
|
|
290
|
+
}
|
|
291
|
+
return undefined;
|
|
292
|
+
}
|
|
293
|
+
/**
|
|
294
|
+
* The per-call `tool_config.vectorDelete` block, when a serving profile
|
|
295
|
+
* declares one (0.6.0 §4.4, the seam `@crewhaus/tool-fetch` reads the same
|
|
296
|
+
* way). Both spellings of the key are accepted so a spec block can be passed
|
|
297
|
+
* verbatim.
|
|
298
|
+
*
|
|
299
|
+
* It differs from tool-fetch's block in one way, on purpose: fetch's is an
|
|
300
|
+
* ALLOW-list and REPLACES the registered one, while this is a DENY-list and is
|
|
301
|
+
* UNIONED with the registration's and the caller's. Replacing a deny-list
|
|
302
|
+
* would let a narrower block widen what may be deleted, which is the wrong
|
|
303
|
+
* direction for a gate whose failure costs data.
|
|
304
|
+
*
|
|
305
|
+
* A malformed block is a refusal, never a silent empty list — an unreadable
|
|
306
|
+
* policy is not an absent policy.
|
|
307
|
+
*/
|
|
308
|
+
export function readVectorToolConfig(override) {
|
|
309
|
+
if (override === undefined || override === null)
|
|
310
|
+
return { ok: true, protectedCollections: [] };
|
|
311
|
+
if (typeof override !== "object" || Array.isArray(override)) {
|
|
312
|
+
return { ok: false, reason: "tool_config for VectorDelete is not an object" };
|
|
313
|
+
}
|
|
314
|
+
const block = override;
|
|
315
|
+
// BOTH spellings are read, each is validated on its own, and the two are
|
|
316
|
+
// UNIONED. Reading only the camelCase one when both were present — which is
|
|
317
|
+
// what this did first — silently dropped the `protected_collections` list a
|
|
318
|
+
// verbatim spec block carried beside it, and deleted from the collection
|
|
319
|
+
// that list named. Accepting two spellings and acting on one is the
|
|
320
|
+
// validate-here-act-there shape, in the one place here that costs data.
|
|
321
|
+
const names = [];
|
|
322
|
+
for (const key of ["protectedCollections", "protected_collections"]) {
|
|
323
|
+
// Keyed on PRESENCE, not on truthiness: a block that carries the key with
|
|
324
|
+
// a null or undefined value has said something unreadable about the
|
|
325
|
+
// policy, and reading that as "no policy" is the weakening this whole
|
|
326
|
+
// function is here to prevent.
|
|
327
|
+
if (!Object.hasOwn(block, key))
|
|
328
|
+
continue;
|
|
329
|
+
const raw = block[key];
|
|
330
|
+
if (!Array.isArray(raw) || raw.some((name) => typeof name !== "string" || name.length === 0)) {
|
|
331
|
+
return {
|
|
332
|
+
ok: false,
|
|
333
|
+
reason: `tool_config.${key} is not a list of non-empty collection names`,
|
|
334
|
+
};
|
|
335
|
+
}
|
|
336
|
+
names.push(...raw);
|
|
337
|
+
}
|
|
338
|
+
return { ok: true, protectedCollections: names };
|
|
339
|
+
}
|
|
340
|
+
/**
|
|
341
|
+
* One `count()`, as an observation that may have failed.
|
|
342
|
+
*
|
|
343
|
+
* A failed count comes back as `null` WITH a reason, never as 0: "I could not
|
|
344
|
+
* read the count" and "the collection is empty" are opposite answers, and a
|
|
345
|
+
* caller reading a fabricated 0 would conclude the erasure was complete.
|
|
346
|
+
*/
|
|
347
|
+
export async function observeCount(store) {
|
|
348
|
+
try {
|
|
349
|
+
const value = await store.count();
|
|
350
|
+
if (typeof value !== "number" || !Number.isFinite(value)) {
|
|
351
|
+
// Rendered BOUNDED, like every other store-controlled string here: a
|
|
352
|
+
// backend that answers `count()` with a parsed error page put all of it
|
|
353
|
+
// — 50 kB in the case that found this — straight into the result, and a
|
|
354
|
+
// result is a model's context.
|
|
355
|
+
return { count: null, error: `count() returned ${describeStoreValue(value)}` };
|
|
356
|
+
}
|
|
357
|
+
return { count: value };
|
|
358
|
+
}
|
|
359
|
+
catch (err) {
|
|
360
|
+
return { count: null, error: describeStoreError(err) };
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
/**
|
|
364
|
+
* Delete each selected id, one at a time, in the selection's order.
|
|
365
|
+
*
|
|
366
|
+
* Sequential rather than `Promise.all`: the order has to be the sorted one for
|
|
367
|
+
* a partial run to be resumable, `attempted` has to mean "these ones, up to
|
|
368
|
+
* here", and a thousand parallel requests is not a thing to do to somebody's
|
|
369
|
+
* qdrant during an erasure.
|
|
370
|
+
*
|
|
371
|
+
* An id whose `delete()` throws is recorded and the run CONTINUES. A caller
|
|
372
|
+
* erasing data on request wants the other nine ids attempted, not abandoned
|
|
373
|
+
* because the fourth timed out — and the error is reported per id, so nothing
|
|
374
|
+
* is hidden. Note what the error does NOT mean: a request that failed after
|
|
375
|
+
* reaching the backend may still have deleted the vector.
|
|
376
|
+
*/
|
|
377
|
+
export async function applyVectorDeletes(store, ids, signal) {
|
|
378
|
+
let attempted = 0;
|
|
379
|
+
let acknowledged = 0;
|
|
380
|
+
const errors = [];
|
|
381
|
+
for (const id of ids) {
|
|
382
|
+
// Checked between deletes, never mid-request: an abort stops the run and
|
|
383
|
+
// the result says where it stopped, rather than reporting a clean finish
|
|
384
|
+
// over a list that was never attempted.
|
|
385
|
+
if (signal?.aborted === true) {
|
|
386
|
+
return { attempted, acknowledged, errors, halted: true };
|
|
387
|
+
}
|
|
388
|
+
attempted += 1;
|
|
389
|
+
try {
|
|
390
|
+
await store.delete(id);
|
|
391
|
+
acknowledged += 1;
|
|
392
|
+
}
|
|
393
|
+
catch (err) {
|
|
394
|
+
errors.push({ id, error: describeStoreError(err) });
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
return { attempted, acknowledged, errors, halted: false };
|
|
398
|
+
}
|
|
399
|
+
/** A store failure as one readable, bounded line. */
|
|
400
|
+
export function describeStoreError(err) {
|
|
401
|
+
const raw = err instanceof Error ? err.message : String(err);
|
|
402
|
+
const flat = raw.replace(/\s+/g, " ").trim();
|
|
403
|
+
if (flat.length === 0)
|
|
404
|
+
return "the store threw a value carrying no message";
|
|
405
|
+
return flat.length > MAX_STORE_ERROR_CHARS ? `${flat.slice(0, MAX_STORE_ERROR_CHARS)}…` : flat;
|
|
406
|
+
}
|
|
407
|
+
/**
|
|
408
|
+
* A value the store (or the host) handed over, as one bounded line — for
|
|
409
|
+
* saying what arrived when what arrived was the wrong thing.
|
|
410
|
+
*
|
|
411
|
+
* Neither shortcut is safe alone: `JSON.stringify` returns `undefined` for
|
|
412
|
+
* `undefined`, a function or a symbol, and THROWS on a BigInt; `String()`
|
|
413
|
+
* throws on a symbol. So the type name is the fallback, and nothing here can
|
|
414
|
+
* itself fail while describing a failure.
|
|
415
|
+
*/
|
|
416
|
+
export function describeStoreValue(value) {
|
|
417
|
+
if (value === undefined)
|
|
418
|
+
return "undefined";
|
|
419
|
+
let raw;
|
|
420
|
+
try {
|
|
421
|
+
raw = JSON.stringify(value) ?? typeof value;
|
|
422
|
+
}
|
|
423
|
+
catch {
|
|
424
|
+
raw = typeof value === "bigint" ? `${value}n` : typeof value;
|
|
425
|
+
}
|
|
426
|
+
const flat = raw.replace(/\s+/g, " ").trim();
|
|
427
|
+
if (flat.length === 0)
|
|
428
|
+
return typeof value;
|
|
429
|
+
return flat.length > MAX_STORE_ERROR_CHARS ? `${flat.slice(0, MAX_STORE_ERROR_CHARS)}…` : flat;
|
|
430
|
+
}
|
|
431
|
+
/** Union of the three protection lists, de-duplicated and sorted. */
|
|
432
|
+
export function unionProtected(...lists) {
|
|
433
|
+
const all = new Set();
|
|
434
|
+
for (const list of lists) {
|
|
435
|
+
for (const name of list ?? [])
|
|
436
|
+
all.add(name);
|
|
437
|
+
}
|
|
438
|
+
return [...all].sort(compareStrings);
|
|
439
|
+
}
|
|
440
|
+
/** Cap a reported list, saying so rather than silently shortening it. */
|
|
441
|
+
export function capList(items) {
|
|
442
|
+
return items.length > MAX_LISTED
|
|
443
|
+
? { listed: items.slice(0, MAX_LISTED), truncated: true }
|
|
444
|
+
: { listed: items, truncated: false };
|
|
445
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@crewhaus/tool-state",
|
|
3
|
+
"version": "0.7.0",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "Deterministic harness state tools: key-value storage, counters, checkpoints, journals, blackboards and lexical search over local notes",
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"scripts": {
|
|
15
|
+
"test": "bun test src"
|
|
16
|
+
},
|
|
17
|
+
"dependencies": {
|
|
18
|
+
"@crewhaus/errors": "0.7.0",
|
|
19
|
+
"@crewhaus/tool-builder": "0.7.0",
|
|
20
|
+
"@crewhaus/tool-catalog": "0.7.0",
|
|
21
|
+
"zod": "^3.23.8"
|
|
22
|
+
},
|
|
23
|
+
"devDependencies": {
|
|
24
|
+
"@crewhaus/tool-executor": "workspace:*"
|
|
25
|
+
},
|
|
26
|
+
"license": "Apache-2.0",
|
|
27
|
+
"author": {
|
|
28
|
+
"name": "Max Meier",
|
|
29
|
+
"email": "max@crewhaus.ai",
|
|
30
|
+
"url": "https://crewhaus.ai"
|
|
31
|
+
},
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "git+https://github.com/crewhaus/factory.git",
|
|
35
|
+
"directory": "packages/tool-state"
|
|
36
|
+
},
|
|
37
|
+
"homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-state#readme",
|
|
38
|
+
"bugs": {
|
|
39
|
+
"url": "https://github.com/crewhaus/factory/issues"
|
|
40
|
+
},
|
|
41
|
+
"publishConfig": {
|
|
42
|
+
"access": "public"
|
|
43
|
+
},
|
|
44
|
+
"files": ["dist", "README.md", "LICENSE", "NOTICE"]
|
|
45
|
+
}
|