@functional-systems/memdrive 0.0.0-stage → 0.1.0-dev.5

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 (97) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/LICENSE +201 -0
  3. package/README.md +229 -2
  4. package/dist/commonjs/chunking.d.ts +7 -0
  5. package/dist/commonjs/chunking.d.ts.map +1 -0
  6. package/dist/commonjs/chunking.js +46 -0
  7. package/dist/commonjs/chunking.js.map +1 -0
  8. package/dist/commonjs/errors.d.ts +17 -0
  9. package/dist/commonjs/errors.d.ts.map +1 -0
  10. package/dist/commonjs/errors.js +44 -0
  11. package/dist/commonjs/errors.js.map +1 -0
  12. package/dist/commonjs/filter.d.ts +30 -0
  13. package/dist/commonjs/filter.d.ts.map +1 -0
  14. package/dist/commonjs/filter.js +224 -0
  15. package/dist/commonjs/filter.js.map +1 -0
  16. package/dist/commonjs/index.d.ts +8 -0
  17. package/dist/commonjs/index.d.ts.map +1 -0
  18. package/dist/commonjs/index.js +343 -0
  19. package/dist/commonjs/index.js.map +1 -0
  20. package/dist/commonjs/package.json +3 -0
  21. package/dist/commonjs/storage.d.ts +274 -0
  22. package/dist/commonjs/storage.d.ts.map +1 -0
  23. package/dist/commonjs/storage.js +861 -0
  24. package/dist/commonjs/storage.js.map +1 -0
  25. package/dist/commonjs/tools/definitions.d.ts +5 -0
  26. package/dist/commonjs/tools/definitions.d.ts.map +1 -0
  27. package/dist/commonjs/tools/definitions.js +129 -0
  28. package/dist/commonjs/tools/definitions.js.map +1 -0
  29. package/dist/commonjs/tools/index.d.ts +6 -0
  30. package/dist/commonjs/tools/index.d.ts.map +1 -0
  31. package/dist/commonjs/tools/index.js +104 -0
  32. package/dist/commonjs/tools/index.js.map +1 -0
  33. package/dist/commonjs/tools/types.d.ts +50 -0
  34. package/dist/commonjs/tools/types.d.ts.map +1 -0
  35. package/dist/commonjs/tools/types.js +3 -0
  36. package/dist/commonjs/tools/types.js.map +1 -0
  37. package/dist/commonjs/types.d.ts +277 -0
  38. package/dist/commonjs/types.d.ts.map +1 -0
  39. package/dist/commonjs/types.js +3 -0
  40. package/dist/commonjs/types.js.map +1 -0
  41. package/dist/commonjs/values.d.ts +17 -0
  42. package/dist/commonjs/values.d.ts.map +1 -0
  43. package/dist/commonjs/values.js +90 -0
  44. package/dist/commonjs/values.js.map +1 -0
  45. package/dist/esm/chunking.d.ts +7 -0
  46. package/dist/esm/chunking.d.ts.map +1 -0
  47. package/dist/esm/chunking.js +42 -0
  48. package/dist/esm/chunking.js.map +1 -0
  49. package/dist/esm/errors.d.ts +17 -0
  50. package/dist/esm/errors.d.ts.map +1 -0
  51. package/dist/esm/errors.js +36 -0
  52. package/dist/esm/errors.js.map +1 -0
  53. package/dist/esm/filter.d.ts +30 -0
  54. package/dist/esm/filter.d.ts.map +1 -0
  55. package/dist/esm/filter.js +209 -0
  56. package/dist/esm/filter.js.map +1 -0
  57. package/dist/esm/index.d.ts +8 -0
  58. package/dist/esm/index.d.ts.map +1 -0
  59. package/dist/esm/index.js +335 -0
  60. package/dist/esm/index.js.map +1 -0
  61. package/dist/esm/package.json +3 -0
  62. package/dist/esm/storage.d.ts +274 -0
  63. package/dist/esm/storage.d.ts.map +1 -0
  64. package/dist/esm/storage.js +845 -0
  65. package/dist/esm/storage.js.map +1 -0
  66. package/dist/esm/tools/definitions.d.ts +5 -0
  67. package/dist/esm/tools/definitions.d.ts.map +1 -0
  68. package/dist/esm/tools/definitions.js +126 -0
  69. package/dist/esm/tools/definitions.js.map +1 -0
  70. package/dist/esm/tools/index.d.ts +6 -0
  71. package/dist/esm/tools/index.d.ts.map +1 -0
  72. package/dist/esm/tools/index.js +101 -0
  73. package/dist/esm/tools/index.js.map +1 -0
  74. package/dist/esm/tools/types.d.ts +50 -0
  75. package/dist/esm/tools/types.d.ts.map +1 -0
  76. package/dist/esm/tools/types.js +2 -0
  77. package/dist/esm/tools/types.js.map +1 -0
  78. package/dist/esm/types.d.ts +277 -0
  79. package/dist/esm/types.d.ts.map +1 -0
  80. package/dist/esm/types.js +2 -0
  81. package/dist/esm/types.js.map +1 -0
  82. package/dist/esm/values.d.ts +17 -0
  83. package/dist/esm/values.d.ts.map +1 -0
  84. package/dist/esm/values.js +87 -0
  85. package/dist/esm/values.js.map +1 -0
  86. package/docs/tools.md +163 -0
  87. package/package.json +100 -4
  88. package/src/chunking.ts +32 -0
  89. package/src/errors.ts +40 -0
  90. package/src/filter.ts +189 -0
  91. package/src/index.ts +323 -0
  92. package/src/storage.ts +765 -0
  93. package/src/tools/definitions.ts +156 -0
  94. package/src/tools/index.ts +97 -0
  95. package/src/tools/types.ts +45 -0
  96. package/src/types.ts +273 -0
  97. package/src/values.ts +103 -0
@@ -0,0 +1,861 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.sourceDocumentId = void 0;
4
+ exports.validateMem = validateMem;
5
+ exports.validateVector = validateVector;
6
+ exports.validateVectorMem = validateVectorMem;
7
+ exports.publicMatch = publicMatch;
8
+ exports.sourceMatch = sourceMatch;
9
+ exports.validateChunk = validateChunk;
10
+ exports.validateSource = validateSource;
11
+ exports.vectorSource = vectorSource;
12
+ exports.vectorMatch = vectorMatch;
13
+ exports.createBackend = createBackend;
14
+ exports.openBackend = openBackend;
15
+ exports.listBackends = listBackends;
16
+ const indexconfigsunion_js_1 = require("@functional-systems/lambdadb/models/indexconfigsunion.js");
17
+ const chunking_js_1 = require("./chunking.js");
18
+ const errors_js_1 = require("./errors.js");
19
+ const filter_js_1 = require("./filter.js");
20
+ // Keep v0 until release; recreate development stores after incompatible layout changes.
21
+ const format = 'mems-v0';
22
+ const encoder = new TextEncoder();
23
+ const requestBytes = 6029312;
24
+ const documentBytes = 5 * 1024 * 1024;
25
+ const defaultBranch = 'main';
26
+ const validBranchName = (name) => typeof name === 'string' && /^[A-Za-z0-9_-]{3,52}$/.test(name);
27
+ function checkBranch(name) { (0, errors_js_1.requireInput)(validBranchName(name), 'Branch name must be 3–52 letters, digits, underscores or hyphens.'); }
28
+ const systemIndexes = {
29
+ memId: { type: 'keyword' },
30
+ kind: { type: 'keyword' },
31
+ embedding: { type: 'vector', managedEmbedding: true, embedding: {
32
+ provider: 'openai', model: 'text-embedding-3-small', sourceField: 'content', dimensions: 1536, similarity: 'cosine',
33
+ } },
34
+ timestamp: { type: 'datetime' },
35
+ };
36
+ const types = { string: 'keyword', 'string[]': 'keyword', number: 'double', boolean: 'boolean', datetime: 'datetime' };
37
+ const bytes = (value) => encoder.encode(JSON.stringify(value)).length;
38
+ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
39
+ const keysOnly = (value, keys) => (0, filter_js_1.isObject)(value) && Object.keys(value).every(key => keys.includes(key));
40
+ const keywordNames = (schema) => Object.entries(schema).filter(([, value]) => ['string', 'string[]'].includes(value.type)).map(([key]) => key).sort();
41
+ const supportedAnalyzers = new Set(Object.values(indexconfigsunion_js_1.Analyzer));
42
+ const validAnalyzers = (names) => Array.isArray(names) && names.length > 0
43
+ && new Set(names).size === names.length && [...names].every(name => supportedAnalyzers.has(name));
44
+ function validateTextSearch(value) {
45
+ if (value === undefined)
46
+ return undefined;
47
+ (0, errors_js_1.requireInput)(keysOnly(value, ['analyzers']) && validAnalyzers(value.analyzers), 'textSearch requires a nonempty array of distinct supported lowercase analyzers.');
48
+ return { analyzers: [...value.analyzers] };
49
+ }
50
+ function storedTextSearch(config) {
51
+ if (config === undefined)
52
+ return undefined;
53
+ const names = (0, filter_js_1.isObject)(config) ? config.analyzers ?? ['standard'] : undefined;
54
+ if (!(0, filter_js_1.isObject)(config) || config.type !== 'text' || !validAnalyzers(names))
55
+ throw new errors_js_1.MemDriveError('INCOMPATIBLE_STORE', 'The content text index must use distinct supported analyzers.');
56
+ return { analyzers: [...names] };
57
+ }
58
+ const managedEmbedding = Object.freeze({ mode: 'managed', provider: 'openai', model: 'text-embedding-3-small',
59
+ dimensions: 1536, similarity: 'cosine' });
60
+ function validateEmbedding(value) {
61
+ if (value === undefined || ((0, filter_js_1.isObject)(value) && value.mode === 'managed')) {
62
+ (0, errors_js_1.requireInput)(value === undefined || keysOnly(value, ['mode']), 'Managed embedding accepts only mode; its model settings are fixed.');
63
+ return managedEmbedding;
64
+ }
65
+ (0, errors_js_1.requireInput)(keysOnly(value, ['mode', 'dimensions', 'similarity', 'identity']) && value.mode === 'external'
66
+ && typeof value.dimensions === 'number' && Number.isInteger(value.dimensions) && value.dimensions >= 64 && value.dimensions <= 4096
67
+ && value.similarity === 'cosine' && typeof value.identity === 'string' && value.identity.trim().length > 0
68
+ && value.identity.length <= 127 && !/[:#,]/.test(value.identity), 'External embedding requires dimensions 64–4096, cosine similarity and a nonblank identity of at most 127 characters without :, # or comma.');
69
+ return Object.freeze({ mode: 'external', dimensions: value.dimensions, similarity: 'cosine', identity: value.identity });
70
+ }
71
+ function storedEmbedding(collection) {
72
+ const candidate = collection.indexConfigs?.embedding;
73
+ const vector = (0, filter_js_1.isObject)(candidate) ? candidate : undefined;
74
+ const rawEmbedding = vector?.embedding;
75
+ const embedding = (0, filter_js_1.isObject)(rawEmbedding) ? rawEmbedding : undefined;
76
+ if (vector?.type === 'vector' && rawEmbedding === undefined && vector.managedEmbedding !== true) {
77
+ try {
78
+ return validateEmbedding({ mode: 'external', dimensions: vector.dimensions,
79
+ similarity: vector.similarity, identity: collection.tags?.['memory.embedding'] });
80
+ }
81
+ catch (cause) {
82
+ throw new errors_js_1.MemDriveError('INCOMPATIBLE_STORE', 'Invalid external embedding configuration.', { cause });
83
+ }
84
+ }
85
+ if (vector?.type !== 'vector' || vector.managedEmbedding === false || embedding?.provider !== managedEmbedding.provider
86
+ || embedding.model !== managedEmbedding.model || embedding.sourceField !== 'content'
87
+ || embedding.dimensions !== managedEmbedding.dimensions || embedding.similarity !== managedEmbedding.similarity
88
+ || vector.dimensions !== undefined || vector.similarity !== undefined || collection.tags?.['memory.embedding'] !== undefined)
89
+ throw new errors_js_1.MemDriveError('INCOMPATIBLE_STORE', 'Invalid managed embedding configuration.');
90
+ return managedEmbedding;
91
+ }
92
+ function indexConfigs(schema, textSearch, embedding) {
93
+ const result = structuredClone(systemIndexes);
94
+ if (embedding.mode === 'external')
95
+ result.embedding = { type: 'vector', dimensions: embedding.dimensions, similarity: embedding.similarity };
96
+ if (textSearch)
97
+ result.content = { type: 'text', analyzers: [...textSearch.analyzers] };
98
+ if (Object.keys(schema).length)
99
+ result.metadata = { type: 'object', objectIndexConfigs: Object.fromEntries(Object.entries(schema).map(([key, { type, description }]) => [key, { type: types[type],
100
+ ...(description === undefined ? {} : { description }) }])) };
101
+ return result;
102
+ }
103
+ // Native tags allow five short values, not an arbitrary JSON schema. Native index
104
+ // types recover scalar types; this canonical bitmap preserves array cardinality
105
+ // over sorted keyword metadata names. Changing that order regenerates the bitmap.
106
+ function arrayTag(schema) {
107
+ const names = keywordNames(schema), bits = new Uint8Array(Math.ceil(names.length / 8));
108
+ names.forEach((key, i) => { if (schema[key].type === 'string[]')
109
+ bits[i >> 3] = bits[i >> 3] | 1 << (i % 8); });
110
+ const encoded = bits.length ? btoa(String.fromCharCode(...bits)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '') : '-';
111
+ (0, errors_js_1.requireInput)(encoded.length <= 127, 'Metadata keyword declarations exceed the native format-tag capacity.');
112
+ return encoded;
113
+ }
114
+ function validateLabels(labels = {}) {
115
+ // Match native Java whitespace exactly, including control separators.
116
+ // eslint-disable-next-line no-control-regex
117
+ const blank = /^[\u0009-\u000d\u001c-\u0020\u1680\u2000-\u2006\u2008-\u200a\u2028\u2029\u205f\u3000]*$/u;
118
+ (0, errors_js_1.requireInput)((0, filter_js_1.isObject)(labels) && Object.keys(labels).length <= 5 && Object.entries(labels).every(([key, value]) => /^[A-Za-z0-9_.-]{1,63}$/.test(key) && !key.startsWith('memory.') && typeof value === 'string'
119
+ && value.length >= 1 && value.length <= 127 && !/[:#,]/.test(value) && !blank.test(value)), 'Labels must use native-safe tag names and values; memory.* names are reserved.');
120
+ return structuredClone(labels);
121
+ }
122
+ function collectionLabels(collection) {
123
+ try {
124
+ (0, errors_js_1.requireInput)((0, filter_js_1.isObject)(collection.tags) && Object.keys(collection.tags).length <= 5, 'Invalid collection tags.');
125
+ return validateLabels(Object.fromEntries(Object.entries(collection.tags).filter(([key]) => !key.startsWith('memory.'))));
126
+ }
127
+ catch (cause) {
128
+ throw new errors_js_1.MemDriveError('INCOMPATIBLE_STORE', 'Invalid MemDrive labels.', { cause });
129
+ }
130
+ }
131
+ function descriptor(collection) {
132
+ const metadataSchema = schemaFromCollection(collection, collection.collectionName);
133
+ const textSearch = storedTextSearch(collection.indexConfigs.content);
134
+ return { name: collection.collectionName, ...(collection.description === undefined ? {} : { description: collection.description }),
135
+ labels: collectionLabels(collection), metadataSchema,
136
+ ...(textSearch ? { textSearch } : {}), embedding: structuredClone(storedEmbedding(collection)) };
137
+ }
138
+ function tags(schema, embedding) {
139
+ return { 'memory.format': format, 'memory.arrays': arrayTag(schema),
140
+ ...(embedding.mode === 'external' ? { 'memory.embedding': embedding.identity } : {}) };
141
+ }
142
+ function schemaFromCollection(collection, name) {
143
+ const fail = condition => { if (!condition)
144
+ throw new errors_js_1.MemDriveError('INCOMPATIBLE_STORE', 'Collection is not a compatible MemDrive.'); };
145
+ fail((0, filter_js_1.isObject)(collection) && collection.collectionName === name && collection.defaultBranchName === defaultBranch
146
+ && collection.tags?.['memory.format'] === format
147
+ && collection.partitionConfig === undefined && (collection.numPartitions === undefined || collection.numPartitions === 1));
148
+ try {
149
+ (0, filter_js_1.validateDescription)(collection.description);
150
+ }
151
+ catch {
152
+ fail(false);
153
+ }
154
+ const configs = collection.indexConfigs;
155
+ fail((0, filter_js_1.isObject)(configs) && Object.keys(configs).every(key => ['id', 'content', ...Object.keys(systemIndexes), 'metadata'].includes(key)));
156
+ storedTextSearch(configs.content);
157
+ fail(configs.memId?.type === 'keyword' && configs.kind?.type === 'keyword'
158
+ && configs.timestamp?.type === 'datetime' && (configs.id === undefined || configs.id.type === 'keyword'));
159
+ const embedding = storedEmbedding(collection);
160
+ fail(embedding.mode !== 'external' || configs.content === undefined);
161
+ fail(configs.metadata === undefined || (configs.metadata.type === 'object' && (0, filter_js_1.isObject)(configs.metadata.objectIndexConfigs)));
162
+ fail(Object.values(configs.metadata?.type === 'object' ? configs.metadata.objectIndexConfigs : {}).every((config) => (0, filter_js_1.isObject)(config)
163
+ && typeof config.type === 'string' && ['keyword', 'double', 'boolean', 'datetime'].includes(config.type)));
164
+ const metadataConfigs = configs.metadata?.type === 'object' ? configs.metadata.objectIndexConfigs : {};
165
+ const publicTypes = { keyword: 'string', double: 'number', boolean: 'boolean', datetime: 'datetime' };
166
+ const declarations = Object.fromEntries(Object.entries(metadataConfigs).map(([key, config]) => {
167
+ // The allowed native types were checked above; validate the complete public declaration below.
168
+ fail((0, filter_js_1.isObject)(config) && typeof config.type === 'string' && Object.hasOwn(publicTypes, config.type));
169
+ return [key, { type: publicTypes[config.type],
170
+ ...(config.description === undefined ? {} : { description: config.description }) }];
171
+ }));
172
+ let schema;
173
+ try {
174
+ schema = (0, filter_js_1.validateMetadataSchema)(declarations);
175
+ }
176
+ catch {
177
+ fail(false);
178
+ }
179
+ const names = keywordNames(schema), encoded = collection.tags['memory.arrays'];
180
+ fail(typeof encoded === 'string' && encoded.length <= 127 && (encoded === '-' || /^[A-Za-z0-9_-]+$/.test(encoded)));
181
+ let raw = '';
182
+ try {
183
+ raw = encoded === '-' ? '' : atob(encoded.replaceAll('-', '+').replaceAll('_', '/'));
184
+ }
185
+ catch {
186
+ fail(false);
187
+ }
188
+ fail(raw.length === Math.ceil(names.length / 8));
189
+ names.forEach((key, i) => { if (raw.charCodeAt(i >> 3) & (1 << (i % 8)))
190
+ schema[key].type = 'string[]'; });
191
+ fail(arrayTag(schema) === encoded); // Reject padding bits and noncanonical encodings.
192
+ return schema;
193
+ }
194
+ function validateAttributes(mem, schema, requireId) {
195
+ if (requireId || Object.hasOwn(mem, 'id'))
196
+ (0, errors_js_1.requireInput)(typeof mem.id === 'string'
197
+ && mem.id.trim().length > 0 && mem.id.length <= 512, 'Mem id must be nonempty text of at most 512 characters.');
198
+ if (Object.hasOwn(mem, 'timestamp'))
199
+ (0, errors_js_1.requireInput)((0, filter_js_1.validScalar)(mem.timestamp, 'datetime'), 'timestamp must be RFC 3339 text.');
200
+ if (Object.hasOwn(mem, 'metadata')) {
201
+ (0, errors_js_1.requireInput)((0, filter_js_1.isObject)(mem.metadata), 'metadata must be an object.');
202
+ for (const [key, value] of Object.entries(mem.metadata)) {
203
+ (0, errors_js_1.requireInput)(Object.hasOwn(schema, key), 'Mem includes undeclared metadata.');
204
+ const { type } = schema[key];
205
+ (0, errors_js_1.requireInput)(type === 'string[]' ? Array.isArray(value) && value.every(item => (0, filter_js_1.validScalar)(item, 'string'))
206
+ : (0, filter_js_1.validScalar)(value, type), 'Metadata value does not match its declared type or indexing limits.');
207
+ }
208
+ }
209
+ }
210
+ function validateMem(mem, schema, { requireId = false } = {}) {
211
+ (0, errors_js_1.requireInput)(keysOnly(mem, ['id', 'content', 'timestamp', 'metadata']), 'Mem accepts only id, content, timestamp and metadata.');
212
+ (0, errors_js_1.requireInput)(typeof mem.content === 'string' && mem.content.trim().length > 0, 'Mem content must be nonempty text.');
213
+ validateAttributes(mem, schema, requireId);
214
+ (0, errors_js_1.requireInput)(bytes(mem) <= documentBytes, 'Mem exceeds the native document byte limit.');
215
+ return structuredClone(mem);
216
+ }
217
+ function validateVector(vector, embedding) {
218
+ (0, errors_js_1.requireInput)(Array.isArray(vector) && vector.length === embedding.dimensions
219
+ && [...vector].every(value => typeof value === 'number' && Number.isFinite(value))
220
+ && vector.some(value => value !== 0), 'Embedding must be a dense, finite, nonzero vector with the configured dimensions.');
221
+ return [...vector];
222
+ }
223
+ function validateVectorMem(mem, schema, embedding, { requireId = false } = {}) {
224
+ (0, errors_js_1.requireInput)(keysOnly(mem, ['id', 'embedding', 'timestamp', 'metadata']), 'External Mem accepts only id, embedding, timestamp and metadata.');
225
+ validateAttributes(mem, schema, requireId);
226
+ const result = { ...structuredClone(mem), embedding: validateVector(mem.embedding, embedding) };
227
+ (0, errors_js_1.requireInput)(bytes(result) <= documentBytes, 'Mem exceeds the native document byte limit.');
228
+ return result;
229
+ }
230
+ const digest = async (id) => [...new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', encoder.encode(id)))]
231
+ .map(value => value.toString(16).padStart(2, '0')).join('');
232
+ const sourceDocumentId = async (id) => `mem:${await digest(id)}`;
233
+ exports.sourceDocumentId = sourceDocumentId;
234
+ const chunkDocumentId = (sourceId, ordinal) => `chunk:${sourceId.slice(4)}:${ordinal}`;
235
+ function attributes(mem) {
236
+ return { ...(mem.timestamp === undefined ? {} : { timestamp: mem.timestamp }),
237
+ ...(mem.metadata === undefined ? {} : { metadata: structuredClone(mem.metadata) }) };
238
+ }
239
+ function publicMatch(evidence) {
240
+ const { id: _id, ...match } = evidence;
241
+ return structuredClone(match);
242
+ }
243
+ async function sourceMatch(mem) {
244
+ return { id: await (0, exports.sourceDocumentId)(mem.id), kind: 'mem', memId: mem.id, content: mem.content,
245
+ start: 0, end: mem.content.length, ...attributes(mem) };
246
+ }
247
+ async function validateChunk(doc, schema) {
248
+ if ((0, filter_js_1.isObject)(doc) && doc.kind === 'mem') {
249
+ (0, errors_js_1.requireInput)(Object.hasOwn(doc, 'content'), 'A Mem without searchable content is not a search result.');
250
+ return sourceMatch(await validateSource(doc, schema));
251
+ }
252
+ (0, errors_js_1.requireInput)(keysOnly(doc, ['id', 'kind', 'memId', 'content', 'start', 'end', 'timestamp', 'metadata'])
253
+ && doc.kind === 'chunk', 'Expected a stored chunk.');
254
+ const mem = validateMem({ id: doc.memId, content: doc.content, ...attributes(doc) }, schema, { requireId: true });
255
+ (0, errors_js_1.requireInput)(typeof doc.start === 'number' && Number.isSafeInteger(doc.start) && doc.start >= 0 && typeof doc.end === 'number' && Number.isSafeInteger(doc.end)
256
+ && doc.end > doc.start && doc.end - doc.start === mem.content.length
257
+ && [...mem.content].length <= 800, 'Invalid chunk source span.');
258
+ const prefix = `chunk:${await digest(mem.id)}:`;
259
+ (0, errors_js_1.requireInput)(typeof doc.id === 'string' && doc.id.startsWith(prefix)
260
+ && /^(0|[1-9][0-9]*)$/.test(doc.id.slice(prefix.length))
261
+ && Number.isSafeInteger(Number(doc.id.slice(prefix.length))), 'Invalid chunk identity.');
262
+ return { id: doc.id, kind: 'chunk', memId: mem.id, content: mem.content, start: doc.start, end: doc.end, ...attributes(mem) };
263
+ }
264
+ async function validateSource(doc, schema) {
265
+ const whole = (0, filter_js_1.isObject)(doc) && Object.hasOwn(doc, 'content');
266
+ (0, errors_js_1.requireInput)(keysOnly(doc, ['id', 'kind', 'memId', whole ? 'content' : 'memContent', 'chunkCount', 'chunkSlots', 'chunkingPolicy', 'timestamp', 'metadata'])
267
+ && doc.kind === 'mem' && doc.chunkingPolicy === chunking_js_1.CHUNKING_POLICY, 'Expected a compatible stored original Mem.');
268
+ const mem = validateMem({ id: doc.memId, content: whole ? doc.content : doc.memContent, ...attributes(doc) }, schema, { requireId: true });
269
+ (0, errors_js_1.requireInput)(typeof doc.id === 'string' && doc.id === await (0, exports.sourceDocumentId)(mem.id) && typeof doc.chunkCount === 'number' && Number.isSafeInteger(doc.chunkCount) && doc.chunkCount >= 1
270
+ && typeof doc.chunkSlots === 'number' && Number.isSafeInteger(doc.chunkSlots) && doc.chunkSlots >= (whole ? 0 : doc.chunkCount)
271
+ && (!whole || (doc.chunkCount === 1 && [...mem.content].length <= 800)), 'Invalid original Mem manifest.');
272
+ const smallestSlot = { id: chunkDocumentId(doc.id, 0), kind: 'chunk', memId: mem.id, ...attributes(mem) };
273
+ (0, errors_js_1.requireInput)(bytes(doc) <= documentBytes && bytes(doc) + doc.chunkSlots * (bytes(smallestSlot) + 1) <= requestBytes, 'Original Mem manifest exceeds the complete replacement limit.');
274
+ return mem;
275
+ }
276
+ async function vectorSource(doc, schema) {
277
+ (0, errors_js_1.requireInput)(keysOnly(doc, ['id', 'kind', 'memId', 'timestamp', 'metadata']) && doc.kind === 'mem', 'Expected an external original Mem without vector values.');
278
+ const candidate = { id: doc.memId, ...attributes(doc) };
279
+ validateAttributes(candidate, schema, true);
280
+ const mem = candidate;
281
+ (0, errors_js_1.requireInput)(doc.id === await (0, exports.sourceDocumentId)(mem.id) && bytes(doc) <= documentBytes, 'Invalid external original Mem.');
282
+ return mem;
283
+ }
284
+ async function vectorMatch(doc, schema) {
285
+ const mem = await vectorSource(doc, schema);
286
+ return { id: doc.id, kind: 'mem', memId: mem.id, ...attributes(mem) };
287
+ }
288
+ function originalIds(request) {
289
+ (0, errors_js_1.requireInput)(keysOnly(request, ['ids']) && Array.isArray(request.ids) && request.ids.length > 0
290
+ && request.ids.every(id => typeof id === 'string' && id.trim().length > 0 && id.length <= 512)
291
+ && new Set(request.ids).size === request.ids.length, 'read requires distinct nonempty Mem IDs.');
292
+ return [...request.ids];
293
+ }
294
+ function databaseError(error, message, details) {
295
+ if (error instanceof errors_js_1.MemDriveError) {
296
+ if (details !== undefined)
297
+ error.details = { ...error.details, ...details };
298
+ return error;
299
+ }
300
+ const result = new errors_js_1.MemDriveError('DATABASE_ERROR', message, { cause: error, details });
301
+ const remote = error;
302
+ const status = remote?.statusCode ?? remote?.status ?? remote?.httpStatus;
303
+ if (typeof status === 'number' && Number.isInteger(status))
304
+ result.status = status;
305
+ return result;
306
+ }
307
+ function validateConnection({ client, name }) {
308
+ (0, errors_js_1.requireInput)(client && typeof client.collection === 'function', 'Provide an initialized LambdaDB client.');
309
+ (0, errors_js_1.requireInput)(typeof name === 'string' && /^[A-Za-z0-9_-]{3,52}$/.test(name), 'MemDrive name must be 3–52 letters, digits, underscores or hyphens.');
310
+ }
311
+ async function nativeRequest(operation, signal) {
312
+ (0, errors_js_1.checkAbort)(signal);
313
+ try {
314
+ return await operation();
315
+ }
316
+ catch (cause) {
317
+ throw (0, errors_js_1.abortError)(cause, signal);
318
+ }
319
+ }
320
+ const nativeOptions = (signal) => signal === undefined ? {} : { signal };
321
+ const guarded = (assertActive, signal) => () => { (0, errors_js_1.checkAbort)(signal); assertActive(); };
322
+ async function load(handle, name, options) {
323
+ const { signal } = (0, errors_js_1.operationOptions)(options);
324
+ let result;
325
+ try {
326
+ result = await nativeRequest(() => handle.get(nativeOptions(signal)), signal);
327
+ }
328
+ catch (error) {
329
+ throw databaseError(error, 'Could not inspect the MemDrive.');
330
+ }
331
+ (0, errors_js_1.checkAbort)(signal);
332
+ const schema = schemaFromCollection(result?.collection, name);
333
+ collectionLabels(result.collection);
334
+ return { result: structuredClone(result), schema, embedding: storedEmbedding(result.collection),
335
+ textSearch: storedTextSearch(result.collection.indexConfigs.content) };
336
+ }
337
+ function backend(handle, name, initial) {
338
+ let schema = initial.schema, textSearch = initial.textSearch, generation = 0, deleted = false;
339
+ const embedding = initial.embedding;
340
+ const decodeSource = (doc) => embedding.mode === 'external' ? vectorSource(doc, schema) : validateSource(doc, schema);
341
+ let schemaUpdates = Promise.resolve();
342
+ const branchEpochs = new Map();
343
+ const epoch = (branch) => branchEpochs.get(branch) ?? 0;
344
+ const retire = (branch) => { branchEpochs.set(branch, epoch(branch) + 1); generation++; };
345
+ const active = () => { if (deleted)
346
+ throw new errors_js_1.MemDriveError('STORE_DELETED', 'This MemDrive has been deleted.'); };
347
+ const refresh = async (options) => {
348
+ const { signal } = (0, errors_js_1.operationOptions)(options);
349
+ const check = guarded(active, signal);
350
+ check();
351
+ const state = await load(handle, name, nativeOptions(signal));
352
+ check();
353
+ if (!same(embedding, state.embedding))
354
+ throw new errors_js_1.MemDriveError('INCOMPATIBLE_STORE', 'Embedding configuration changed; reopen the MemDrive.');
355
+ if (!same(schema, state.schema) || !same(textSearch, state.textSearch))
356
+ generation++;
357
+ schema = state.schema;
358
+ textSearch = state.textSearch;
359
+ return state.result;
360
+ };
361
+ const fetchOriginals = async (ids, branch, assertActive, execute = operation => operation(), signal) => {
362
+ const found = new Map();
363
+ for (let start = 0; start < ids.length; start += 1000) {
364
+ assertActive();
365
+ const batch = ids.slice(start, start + 1000), expected = new Set(batch);
366
+ const documentIds = await Promise.all(batch.map(exports.sourceDocumentId));
367
+ assertActive();
368
+ let response;
369
+ try {
370
+ response = await execute(() => {
371
+ assertActive();
372
+ return nativeRequest(() => handle.docs.fetch({ ids: documentIds,
373
+ ref: { kind: 'branch', name: branch }, consistentRead: true, includeVectors: false }, nativeOptions(signal)), signal);
374
+ });
375
+ }
376
+ catch (error) {
377
+ throw databaseError(error, 'Could not read original Mems.');
378
+ }
379
+ assertActive();
380
+ if (response?.isDocsInline === false || !Array.isArray(response?.docs) || response.docs.length > batch.length)
381
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'Original read returned an invalid document envelope.');
382
+ for (const hit of response.docs) {
383
+ try {
384
+ (0, errors_js_1.requireInput)(hit.collection === undefined || hit.collection === name, 'Original read returned another collection.');
385
+ const mem = await decodeSource(hit.doc);
386
+ (0, errors_js_1.requireInput)(expected.has(mem.id) && !found.has(mem.id), 'Original read returned unexpected or duplicate Mems.');
387
+ found.set(mem.id, structuredClone(hit.doc));
388
+ }
389
+ catch (cause) {
390
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'Original read returned an invalid Mem.', { cause });
391
+ }
392
+ }
393
+ }
394
+ assertActive();
395
+ return found;
396
+ };
397
+ const api = {
398
+ get metadataSchema() { return structuredClone(schema); },
399
+ get textSearch() { return structuredClone(textSearch); },
400
+ get embedding() { return Object.freeze(structuredClone(embedding)); },
401
+ get generation() { return generation; },
402
+ assertActive: active,
403
+ describe: refresh,
404
+ async describeDescriptor(options) {
405
+ const { signal } = (0, errors_js_1.operationOptions)(options);
406
+ const result = await refresh({ signal });
407
+ guarded(active, signal)();
408
+ return descriptor(result.collection);
409
+ },
410
+ at(branch) {
411
+ active();
412
+ checkBranch(branch);
413
+ const version = epoch(branch);
414
+ const assertActive = () => {
415
+ active();
416
+ if (version !== epoch(branch))
417
+ throw new errors_js_1.MemDriveError('BRANCH_INVALIDATED', 'This branch handle was invalidated by deletion; select the branch again.');
418
+ };
419
+ return {
420
+ get metadataSchema() { return api.metadataSchema; },
421
+ get textSearch() { return api.textSearch; },
422
+ get embedding() { return api.embedding; },
423
+ get generation() { return generation; },
424
+ assertActive,
425
+ describe: async (options) => { assertActive(); const result = await refresh(options); guarded(assertActive, options?.signal)(); return result; },
426
+ describeDescriptor: async (options) => { assertActive(); const result = await api.describeDescriptor(options); guarded(assertActive, options?.signal)(); return result; },
427
+ async query(body, options) { assertActive(); const result = await api.query(body, options, branch, assertActive); guarded(assertActive, options?.signal)(); return result; },
428
+ remember: (request, options) => { assertActive(); return api.remember(request, options, branch, assertActive); },
429
+ list: (request, options) => { assertActive(); return api.list(request, options, branch, assertActive); },
430
+ read: (request, execute, options) => { assertActive(); return api.read(request, execute, options, branch, assertActive); },
431
+ forget: (request, options) => { assertActive(); return api.forget(request, options, branch, assertActive); },
432
+ };
433
+ },
434
+ branches: {
435
+ async create(request, options) {
436
+ const { signal } = (0, errors_js_1.operationOptions)(options);
437
+ const check = guarded(active, signal);
438
+ check();
439
+ (0, errors_js_1.requireInput)(keysOnly(request, ['name', 'source']), 'Use name and optional source for branch creation.');
440
+ checkBranch(request.name);
441
+ const source = request.source === undefined ? { branch: defaultBranch } : request.source;
442
+ (0, errors_js_1.requireInput)(keysOnly(source, ['branch']), 'A branch source must contain only branch.');
443
+ checkBranch(source.branch);
444
+ generation++;
445
+ try {
446
+ const response = await nativeRequest(() => handle.branches.create({ branchName: request.name,
447
+ source: { kind: 'branch', name: source.branch } }, nativeOptions(signal)), signal);
448
+ check();
449
+ if (!(0, filter_js_1.isObject)(response?.branch) || response.branch.name !== request.name)
450
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'Branch creation returned an invalid branch.');
451
+ return structuredClone(response.branch);
452
+ }
453
+ catch (error) {
454
+ const wrapped = databaseError(error, 'MemDrive branch creation failed.');
455
+ if (wrapped.status === 404)
456
+ wrapped.code = 'BRANCH_NOT_FOUND';
457
+ if (wrapped.status === 409)
458
+ wrapped.code = 'BRANCH_EXISTS';
459
+ throw wrapped;
460
+ }
461
+ finally {
462
+ generation++;
463
+ }
464
+ },
465
+ async list(options) {
466
+ const { signal } = (0, errors_js_1.operationOptions)(options);
467
+ const check = guarded(active, signal);
468
+ check();
469
+ let response;
470
+ try {
471
+ response = await nativeRequest(() => handle.branches.list(nativeOptions(signal)), signal);
472
+ }
473
+ catch (error) {
474
+ throw databaseError(error, 'Could not list MemDrive branches.');
475
+ }
476
+ check();
477
+ if (!Array.isArray(response?.branches) || !response.branches.every(item => (0, filter_js_1.isObject)(item) && validBranchName(item.name))
478
+ || new Set(response.branches.map(item => item.name)).size !== response.branches.length)
479
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'Branch listing returned invalid branches.');
480
+ return structuredClone(response.branches);
481
+ },
482
+ async delete(branch, options) {
483
+ const { signal } = (0, errors_js_1.operationOptions)(options);
484
+ const check = guarded(active, signal);
485
+ check();
486
+ checkBranch(branch);
487
+ (0, errors_js_1.requireInput)(branch !== defaultBranch, 'The main branch cannot be deleted independently of its MemDrive.');
488
+ generation++;
489
+ try {
490
+ await nativeRequest(() => handle.branches.delete(branch, nativeOptions(signal)), signal);
491
+ }
492
+ catch (error) {
493
+ const wrapped = databaseError(error, 'MemDrive branch deletion failed.');
494
+ // A missing or uncertain deletion must not let old handles
495
+ // silently bind to a later branch with the same name.
496
+ if (wrapped.status === 404 || !(wrapped.status !== undefined && wrapped.status >= 400 && wrapped.status < 500))
497
+ retire(branch);
498
+ if (wrapped.status === 404)
499
+ wrapped.code = 'BRANCH_NOT_FOUND';
500
+ if (wrapped.status === 409)
501
+ wrapped.code = 'BRANCH_CONFLICT';
502
+ throw wrapped;
503
+ }
504
+ finally {
505
+ generation++;
506
+ }
507
+ retire(branch);
508
+ check();
509
+ },
510
+ },
511
+ async query(body, options, branch = defaultBranch, assertActive = active) {
512
+ const { signal } = (0, errors_js_1.operationOptions)(options);
513
+ const check = guarded(assertActive, signal);
514
+ check();
515
+ (0, errors_js_1.requireInput)(keysOnly(body, ['query', 'size', 'candidateSize', 'rerank', 'facets']), 'Query cannot override the managed read settings.');
516
+ try {
517
+ const result = await nativeRequest(() => handle.query({ ...structuredClone(body),
518
+ ref: { kind: 'branch', name: branch }, consistentRead: true, includeVectors: false }, nativeOptions(signal)), signal);
519
+ check();
520
+ return result;
521
+ }
522
+ catch (error) {
523
+ throw databaseError(error, 'MemDrive query failed.');
524
+ }
525
+ },
526
+ async read(request, execute, options, branch = defaultBranch, assertActive = active) {
527
+ const { signal } = (0, errors_js_1.operationOptions)(options);
528
+ assertActive = guarded(assertActive, signal);
529
+ assertActive();
530
+ const ids = originalIds(request);
531
+ const originals = await fetchOriginals(ids, branch, assertActive, execute, signal);
532
+ const mems = await Promise.all(ids.filter(id => originals.has(id)).map(id => decodeSource(originals.get(id))));
533
+ assertActive();
534
+ return { mems };
535
+ },
536
+ async list(request = {}, options, branch = defaultBranch, assertActive = active) {
537
+ const { signal } = (0, errors_js_1.operationOptions)(options);
538
+ assertActive = guarded(assertActive, signal);
539
+ assertActive();
540
+ (0, errors_js_1.requireInput)(keysOnly(request, ['cursor', 'limit']), 'list accepts cursor and limit only.');
541
+ const limit = request.limit ?? 100;
542
+ (0, errors_js_1.requireInput)(Number.isInteger(limit) && limit >= 1 && limit <= 1000, 'list limit must be between 1 and 1000.');
543
+ (0, errors_js_1.requireInput)(request.cursor === undefined || (typeof request.cursor === 'string' && request.cursor.length > 0), 'list cursor must be a nonempty opaque token.');
544
+ let response;
545
+ try {
546
+ response = await nativeRequest(() => handle.docs.list({ size: limit, ...(request.cursor === undefined ? {} : { pageToken: request.cursor }),
547
+ includeVectors: false, ref: { kind: 'branch', name: branch } }, nativeOptions(signal)), signal);
548
+ }
549
+ catch (error) {
550
+ throw databaseError(error, 'Could not list Mems.');
551
+ }
552
+ assertActive();
553
+ if (response?.isDocsInline === false || !Array.isArray(response?.docs) || response.docs.length > limit
554
+ || (response.nextPageToken !== undefined && (typeof response.nextPageToken !== 'string' || !response.nextPageToken
555
+ || response.nextPageToken === request.cursor)))
556
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'Mem listing returned an invalid page.');
557
+ const mems = [], seen = new Set();
558
+ for (const hit of response.docs) {
559
+ try {
560
+ (0, errors_js_1.requireInput)((hit.collection === undefined || hit.collection === name) && (0, filter_js_1.isObject)(hit.doc)
561
+ && typeof hit.doc.kind === 'string' && ['mem', 'chunk'].includes(hit.doc.kind) && typeof hit.doc.id === 'string' && !seen.has(hit.doc.id), 'Listing returned an unexpected or duplicate document.');
562
+ seen.add(hit.doc.id);
563
+ if (hit.doc.kind === 'mem')
564
+ mems.push(await decodeSource(hit.doc));
565
+ }
566
+ catch (cause) {
567
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'Mem listing returned an invalid document.', { cause });
568
+ }
569
+ }
570
+ assertActive();
571
+ return { mems, ...(response.nextPageToken === undefined ? {} : { nextCursor: response.nextPageToken }) };
572
+ },
573
+ async remember(request, options, branch = defaultBranch, assertActive = active) {
574
+ const { signal } = (0, errors_js_1.operationOptions)(options);
575
+ assertActive = guarded(assertActive, signal);
576
+ assertActive();
577
+ (0, errors_js_1.requireInput)(keysOnly(request, ['mems']) && Array.isArray(request.mems) && request.mems.length > 0, 'remember requires a nonempty mems array.');
578
+ const external = embedding.mode === 'external';
579
+ const validate = (mem, options) => external ? validateVectorMem(mem, schema, embedding, options) : validateMem(mem, schema, options);
580
+ const mems = request.mems.map(mem => {
581
+ const validated = validate(mem);
582
+ validated.id ??= globalThis.crypto.randomUUID();
583
+ return (external ? validateVectorMem(validated, schema, embedding, { requireId: true })
584
+ : validateMem(validated, schema, { requireId: true }));
585
+ });
586
+ const ids = mems.map(mem => mem.id);
587
+ (0, errors_js_1.requireInput)(new Set(ids).size === ids.length, 'Mem IDs must be unique within remember.');
588
+ let originals;
589
+ try {
590
+ originals = external ? new Map() : await fetchOriginals(ids, branch, assertActive, undefined, signal);
591
+ }
592
+ catch (error) {
593
+ if (error instanceof errors_js_1.MemDriveError && error.code === 'ABORTED')
594
+ throw databaseError(error, 'MemDrive write was aborted before dispatch.', {
595
+ ids, completedIds: [], uncertainIds: [], notAttemptedIds: [...ids],
596
+ });
597
+ throw error;
598
+ }
599
+ const replacements = await Promise.all(mems.map(async (mem) => {
600
+ const id = await (0, exports.sourceDocumentId)(mem.id), shared = { memId: mem.id, ...attributes(mem) };
601
+ let docs;
602
+ if ('embedding' in mem)
603
+ docs = [{ id, kind: 'mem', ...shared, embedding: mem.embedding }];
604
+ else {
605
+ const spans = (0, chunking_js_1.chunkSpans)(mem.content).filter(span => span.text.trim());
606
+ const whole = spans.length === 1 && spans[0].start === 0 && spans[0].end === mem.content.length;
607
+ const chunkSlots = Math.max(originals.get(mem.id)?.chunkSlots ?? 0, whole ? 0 : spans.length);
608
+ docs = [{ id, kind: 'mem', ...shared, ...(whole ? { content: mem.content } : { memContent: mem.content }),
609
+ chunkCount: spans.length, chunkSlots, chunkingPolicy: chunking_js_1.CHUNKING_POLICY }];
610
+ for (let ordinal = 0; ordinal < chunkSlots; ordinal++) {
611
+ const span = whole ? undefined : spans[ordinal];
612
+ docs.push({ id: chunkDocumentId(id, ordinal), kind: 'chunk', ...shared,
613
+ ...(span ? { content: span.text, start: span.start, end: span.end } : {}) });
614
+ }
615
+ }
616
+ (0, errors_js_1.requireInput)(docs.every(doc => bytes(doc) <= documentBytes) && bytes({ docs, branch }) <= requestBytes, 'A complete Mem replacement exceeds the native request or document byte limit.');
617
+ return { ids: [mem.id], docs };
618
+ }));
619
+ // Greedily pack complete Mem replacements. No request may contain
620
+ // only part of a replacement, and all requests validate before writes.
621
+ const batches = [];
622
+ let batch = { ids: [], docs: [] }, size = bytes({ docs: [], branch });
623
+ for (const replacement of replacements) {
624
+ const addition = replacement.docs.reduce((sum, doc) => sum + bytes(doc) + 1, 0);
625
+ const nextSize = size + addition - (batch.docs.length ? 0 : 1);
626
+ if (batch.docs.length && nextSize > requestBytes) {
627
+ batches.push(batch);
628
+ batch = { ids: [], docs: [] };
629
+ size = bytes({ docs: [], branch });
630
+ }
631
+ size += addition - (batch.docs.length ? 0 : 1);
632
+ batch.ids.push(...replacement.ids);
633
+ batch.docs.push(...replacement.docs);
634
+ }
635
+ if (batch.docs.length)
636
+ batches.push(batch);
637
+ const completedIds = [];
638
+ const checkWritable = () => {
639
+ try {
640
+ assertActive();
641
+ }
642
+ catch (error) {
643
+ throw databaseError(error, 'MemDrive branch changed during write.', {
644
+ ids, completedIds: [...completedIds], uncertainIds: [], notAttemptedIds: ids.slice(completedIds.length),
645
+ });
646
+ }
647
+ };
648
+ for (const batch of batches) {
649
+ checkWritable();
650
+ generation++;
651
+ try {
652
+ await nativeRequest(() => handle.docs.upsert({ docs: batch.docs, branch }, nativeOptions(signal)), signal);
653
+ }
654
+ catch (error) {
655
+ throw databaseError(error, 'MemDrive write failed; some mems may already have been accepted.', {
656
+ ids, completedIds: [...completedIds], uncertainIds: [...batch.ids],
657
+ notAttemptedIds: ids.slice(completedIds.length + batch.ids.length),
658
+ });
659
+ }
660
+ finally {
661
+ generation++;
662
+ }
663
+ completedIds.push(...batch.ids);
664
+ }
665
+ checkWritable();
666
+ return { ids };
667
+ },
668
+ async forget(request, options, branch = defaultBranch, assertActive = active) {
669
+ const { signal } = (0, errors_js_1.operationOptions)(options);
670
+ const check = guarded(assertActive, signal);
671
+ check();
672
+ (0, errors_js_1.requireInput)(keysOnly(request, ['ids', 'filter']) && Object.keys(request).length === 1, 'forget requires exactly one of ids or filter.');
673
+ let body;
674
+ if (Object.hasOwn(request, 'ids')) {
675
+ (0, errors_js_1.requireInput)(Array.isArray(request.ids) && request.ids.length > 0
676
+ && request.ids.every(id => typeof id === 'string' && id.trim().length > 0 && id.length <= 512)
677
+ && new Set(request.ids).size === request.ids.length, 'forget IDs must be nonempty and unique.');
678
+ body = { filter: (0, filter_js_1.compileFilter)({ field: 'id', op: 'in', value: [...request.ids] }, schema), branch };
679
+ }
680
+ else {
681
+ (0, errors_js_1.requireInput)(request.filter !== undefined, 'forget filter must be an explicit expression.');
682
+ body = { filter: (0, filter_js_1.compileFilter)(request.filter, schema), branch };
683
+ }
684
+ generation++;
685
+ try {
686
+ await nativeRequest(() => handle.docs.delete(body, nativeOptions(signal)), signal);
687
+ }
688
+ catch (error) {
689
+ throw databaseError(error, 'Mem deletion failed.');
690
+ }
691
+ finally {
692
+ generation++;
693
+ }
694
+ check();
695
+ },
696
+ async configure(request, options) {
697
+ const { signal } = (0, errors_js_1.operationOptions)(options);
698
+ const check = guarded(active, signal);
699
+ check();
700
+ (0, errors_js_1.requireInput)(keysOnly(request, ['metadataSchema', 'description'])
701
+ && (Object.hasOwn(request, 'metadataSchema') || request.description !== undefined), 'configure requires metadataSchema, description, or both.');
702
+ const desired = Object.hasOwn(request, 'metadataSchema') ? (0, filter_js_1.validateMetadataSchema)(request.metadataSchema) : undefined;
703
+ const description = (0, filter_js_1.validateDescription)(request.description);
704
+ const desiredTags = desired === undefined ? undefined : tags(desired, embedding); // Check format capacity before remote operations.
705
+ // Serialize this handle's read/validate/write/verify sequence. Native
706
+ // PATCH has no CAS for tags: applications must use one schema writer
707
+ // across handles/processes; this queue is not a distributed lock.
708
+ const update = schemaUpdates.then(async () => {
709
+ check();
710
+ const current = await refresh({ signal });
711
+ const before = schemaFromCollection(current.collection, name);
712
+ (0, errors_js_1.requireInput)(desired === undefined || Object.entries(before).every(([key, value]) => desired[key]?.type === value.type), 'Schema updates may add fields but cannot omit or change existing fields.');
713
+ const expected = desired === undefined ? before : Object.fromEntries(Object.entries(desired).map(([key, value]) => [key,
714
+ { ...before[key], ...value, ...(value.description === undefined && before[key]?.description !== undefined
715
+ ? { description: before[key].description } : {}) }]));
716
+ const nextIndexes = structuredClone(current.collection.indexConfigs);
717
+ const previousMetadata = nextIndexes.metadata?.type === 'object' ? nextIndexes.metadata : undefined;
718
+ if (desired !== undefined && Object.keys(desired).length)
719
+ nextIndexes.metadata = {
720
+ ...(previousMetadata ?? { type: 'object' }),
721
+ objectIndexConfigs: { ...previousMetadata?.objectIndexConfigs,
722
+ ...Object.fromEntries(Object.entries(expected).map(([key, value]) => [key, {
723
+ ...previousMetadata?.objectIndexConfigs?.[key], type: types[value.type],
724
+ ...(value.description === undefined ? {} : { description: value.description }),
725
+ }])) },
726
+ };
727
+ const nextTags = { ...current.collection.tags, ...desiredTags };
728
+ (0, errors_js_1.requireInput)(Object.keys(nextTags).length <= 5, 'Collection tags exceed the native limit.');
729
+ generation++;
730
+ const updateRequest = desired === undefined
731
+ ? { description: description }
732
+ : { indexConfigs: nextIndexes, tags: nextTags, ...(description === undefined ? {} : { description }) };
733
+ try {
734
+ await nativeRequest(() => handle.update(updateRequest, nativeOptions(signal)), signal);
735
+ }
736
+ catch (error) {
737
+ throw databaseError(error, 'MemDrive schema update failed; reopen to verify its outcome.');
738
+ }
739
+ // Catch an observed conflicting writer; a later writer still needs
740
+ // application coordination because native PATCH has no condition.
741
+ check();
742
+ const updated = (await refresh({ signal })).collection;
743
+ const actual = schemaFromCollection(updated, name);
744
+ if (Object.keys(actual).length !== Object.keys(expected).length
745
+ || !Object.entries(expected).every(([key, value]) => actual[key]?.type === value.type
746
+ && (actual[key]?.description ?? '') === (value.description ?? ''))
747
+ || (updated.description ?? '') !== (description ?? current.collection.description ?? ''))
748
+ throw new errors_js_1.MemDriveError('SCHEMA_CONFLICT', 'Stored schema changed concurrently; reopen before proceeding.');
749
+ });
750
+ const settled = update.finally(() => { generation++; });
751
+ schemaUpdates = settled.catch(() => { });
752
+ return settled;
753
+ },
754
+ async destroy(options) {
755
+ const { signal } = (0, errors_js_1.operationOptions)(options);
756
+ const check = guarded(active, signal);
757
+ check();
758
+ generation++;
759
+ try {
760
+ await nativeRequest(() => handle.delete(nativeOptions(signal)), signal);
761
+ deleted = true;
762
+ (0, errors_js_1.checkAbort)(signal);
763
+ }
764
+ catch (error) {
765
+ throw databaseError(error, 'MemDrive deletion failed.');
766
+ }
767
+ },
768
+ };
769
+ return api;
770
+ }
771
+ async function createBackend(options, requestOptions) {
772
+ const { signal } = (0, errors_js_1.operationOptions)(requestOptions);
773
+ (0, errors_js_1.checkAbort)(signal);
774
+ validateConnection(options);
775
+ (0, errors_js_1.requireInput)(typeof options.client.createCollection === 'function', 'Client must support collection creation.');
776
+ const schema = (0, filter_js_1.validateMetadataSchema)(options.metadataSchema);
777
+ const textSearch = validateTextSearch(options.textSearch);
778
+ const embedding = validateEmbedding(options.embedding);
779
+ (0, errors_js_1.requireInput)(embedding.mode !== 'external' || textSearch === undefined, 'External embedding does not support a content text index.');
780
+ const labels = validateLabels(options.labels);
781
+ const description = (0, filter_js_1.validateDescription)(options.description);
782
+ const allTags = { ...labels, ...tags(schema, embedding) };
783
+ (0, errors_js_1.requireInput)(Object.keys(allTags).length <= 5, 'Labels and reserved MemDrive tags exceed the native five-tag limit.');
784
+ const request = { collectionName: options.name, indexConfigs: indexConfigs(schema, textSearch, embedding), tags: allTags,
785
+ ...(description === undefined ? {} : { description }) };
786
+ try {
787
+ await nativeRequest(() => options.client.createCollection(request, nativeOptions(signal)), signal);
788
+ }
789
+ catch (error) {
790
+ const wrapped = databaseError(error, 'Could not create the MemDrive.');
791
+ if (wrapped.status === 409)
792
+ wrapped.code = 'STORE_EXISTS';
793
+ throw wrapped;
794
+ }
795
+ (0, errors_js_1.checkAbort)(signal);
796
+ return openBackend(options, nativeOptions(signal));
797
+ }
798
+ async function openBackend(options, requestOptions) {
799
+ const { signal } = (0, errors_js_1.operationOptions)(requestOptions);
800
+ (0, errors_js_1.checkAbort)(signal);
801
+ validateConnection(options);
802
+ const handle = options.client.collection(options.name);
803
+ let state;
804
+ try {
805
+ state = await load(handle, options.name, nativeOptions(signal));
806
+ }
807
+ catch (error) {
808
+ if (error instanceof errors_js_1.MemDriveError && error.status === 404)
809
+ error.code = 'STORE_NOT_FOUND';
810
+ throw error;
811
+ }
812
+ (0, errors_js_1.checkAbort)(signal);
813
+ return backend(handle, options.name, state);
814
+ }
815
+ async function listBackends(request, options) {
816
+ const { signal } = (0, errors_js_1.operationOptions)(options);
817
+ (0, errors_js_1.checkAbort)(signal);
818
+ (0, errors_js_1.requireInput)(keysOnly(request, ['client', 'limit', 'cursor', 'labels']) && typeof request.client?.listCollections === 'function'
819
+ && typeof request.client?.collection === 'function', 'Provide a LambdaDB client and documented catalog arguments.');
820
+ const { client, cursor } = request;
821
+ const limit = request.limit ?? 10, labels = validateLabels(request.labels);
822
+ (0, errors_js_1.requireInput)(Number.isInteger(limit) && limit >= 1 && limit <= 100, 'Catalog limit must be between 1 and 100.');
823
+ (0, errors_js_1.requireInput)(cursor === undefined || (typeof cursor === 'string' && cursor.length > 0), 'Catalog cursor must be a nonempty opaque token.');
824
+ let page;
825
+ try {
826
+ page = await nativeRequest(() => client.listCollections({ size: limit,
827
+ ...(cursor === undefined ? {} : { pageToken: cursor }) }, nativeOptions(signal)), signal);
828
+ }
829
+ catch (error) {
830
+ throw databaseError(error, 'Could not list MemDrives.');
831
+ }
832
+ (0, errors_js_1.checkAbort)(signal);
833
+ if (!Array.isArray(page?.collections) || page.collections.length > limit
834
+ || !page.collections.every(item => (0, filter_js_1.isObject)(item) && typeof item.collectionName === 'string'
835
+ && /^[A-Za-z0-9_-]{3,52}$/.test(item.collectionName))
836
+ || new Set(page.collections.map(item => item.collectionName)).size !== page.collections.length
837
+ || (page.nextPageToken !== undefined && (typeof page.nextPageToken !== 'string'
838
+ || !page.nextPageToken || page.nextPageToken === cursor)))
839
+ throw new errors_js_1.MemDriveError('INVALID_RESULT', 'MemDrive catalog returned an invalid page.');
840
+ const drives = [];
841
+ const matches = (collection) => Object.entries(labels).every(([key, value]) => collection.tags?.[key] === value);
842
+ for (let collection of page.collections) {
843
+ (0, errors_js_1.checkAbort)(signal);
844
+ if (collection.tags?.['memory.format'] !== format || !matches(collection))
845
+ continue;
846
+ try {
847
+ if (collection.indexConfigs === undefined)
848
+ collection = (await load(client.collection(collection.collectionName), collection.collectionName, nativeOptions(signal))).result.collection;
849
+ const drive = descriptor(collection);
850
+ if (matches(collection))
851
+ drives.push(drive);
852
+ }
853
+ catch (error) {
854
+ if (!(error instanceof errors_js_1.MemDriveError) || error.code !== 'INCOMPATIBLE_STORE')
855
+ throw error;
856
+ }
857
+ }
858
+ (0, errors_js_1.checkAbort)(signal);
859
+ return { drives, ...(page.nextPageToken === undefined ? {} : { nextCursor: page.nextPageToken }) };
860
+ }
861
+ //# sourceMappingURL=storage.js.map