@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/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
+ }