warm-sdk 0.0.0-stage → 0.2.1

package/dist/index.cjs

@@ -0,0 +1,676 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryClient: () => MemoryClient,
+  WarmClient: () => WarmClient,
+  WarmError: () => WarmError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/validation.ts
+var MAX_BYTES = 16 * 1024 * 1024;
+var JsonSizeError = class extends RangeError {
+};
+var encoder = new TextEncoder();
+var byteLength = (value) => encoder.encode(value).byteLength;
+function string(value, name, max = MAX_BYTES, nonempty = false) {
+  if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+  for (let i = 0; i < value.length; i += 1) {
+    const unit = value.charCodeAt(i);
+    if (unit >= 55296 && unit <= 56319) {
+      const next = value.charCodeAt(++i);
+      if (!(next >= 56320 && next <= 57343)) throw new TypeError(`${name} must be valid Unicode`);
+    } else if (unit >= 56320 && unit <= 57343) throw new TypeError(`${name} must be valid Unicode`);
+  }
+  if (value.length > max || byteLength(value) > max || nonempty && !value.trim()) {
+    throw new RangeError(`${name} has an invalid byte length`);
+  }
+  return value;
+}
+function integer(value, name, min = 0, max = Number.MAX_SAFE_INTEGER) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer`);
+  if (value < min || value > max) throw new RangeError(`${name} is outside its supported range`);
+  return value;
+}
+function number(value, name, min = -Infinity, max = Infinity) {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new TypeError(`${name} must be finite`);
+  if (value < min || value > max) throw new RangeError(`${name} is outside its supported range`);
+  return value;
+}
+function boolean(value, name) {
+  if (typeof value !== "boolean") throw new TypeError(`${name} must be a boolean`);
+  return value;
+}
+function record(value, name, keys) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype) throw new TypeError(`${name} must be a plain object`);
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (typeof key !== "string" || !("value" in descriptor) || !descriptor.enumerable || keys && !keys.includes(key)) {
+      throw new TypeError(`${name} contains an unsupported property`);
+    }
+  }
+  return value;
+}
+function array(value, name, max = 1048576, min = 0) {
+  if (!Array.isArray(value)) throw new TypeError(`${name} must be an array`);
+  if (value.length < min || value.length > max) throw new RangeError(`${name} has an invalid length`);
+  for (let i = 0; i < value.length; i += 1) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+    if (!descriptor || !("value" in descriptor)) throw new TypeError(`${name} must not contain holes or accessors`);
+  }
+  if (Reflect.ownKeys(value).length !== value.length + 1) throw new TypeError(`${name} contains extra properties`);
+  return value;
+}
+function id(value) {
+  const result = string(value, "id", 256);
+  if (!result.length) throw new RangeError("id must not be empty");
+  if (/[\u0000-\u001f\u007f-\u009f]/.test(result) || result.startsWith("hms:")) throw new TypeError("id contains a reserved prefix or control character");
+  return result;
+}
+function segment(value) {
+  const result = id(value);
+  if (result === "." || result === "..") throw new TypeError("Dot-only document IDs cannot be addressed through a URL path");
+  return encodeURIComponent(result).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function vector(value) {
+  const values = array(value, "embedding", 1048576, 1).map((item) => number(item, "embedding value"));
+  if (values.every((item) => item === 0)) throw new RangeError("Embedding must not be all zeros");
+  return values;
+}
+function choice(value, name, values) {
+  if (typeof value !== "string" || !values.includes(value)) throw new TypeError(`${name} has an unsupported value`);
+  return value;
+}
+function json(value, limit = MAX_BYTES) {
+  const ancestors = /* @__PURE__ */ new Set();
+  let bytes = 0;
+  const add = (size) => {
+    bytes += size;
+    if (bytes > limit) throw new JsonSizeError("JSON exceeds its byte limit");
+  };
+  const visit = (item, depth) => {
+    if (depth > 64) throw new RangeError("JSON nesting exceeds 64 levels");
+    if (item === null || typeof item === "boolean") {
+      add(item === null ? 4 : item ? 4 : 5);
+      return item;
+    }
+    if (typeof item === "number") {
+      number(item, "JSON number");
+      add(String(item).length);
+      return item;
+    }
+    if (typeof item === "string") {
+      string(item, "JSON string", limit);
+      add(byteLength(JSON.stringify(item)));
+      return item;
+    }
+    if (typeof item !== "object") throw new TypeError("JSON contains an unsupported value");
+    if (ancestors.has(item)) throw new TypeError("JSON must not contain cycles");
+    ancestors.add(item);
+    let result;
+    if (Array.isArray(item)) {
+      const items = array(item, "JSON array");
+      add(2 + Math.max(0, items.length - 1));
+      result = items.map((entry) => visit(entry, depth + 1));
+    } else {
+      const source = record(item, "JSON object");
+      const entries = Object.entries(source);
+      add(2 + Math.max(0, entries.length - 1));
+      const target = /* @__PURE__ */ Object.create(null);
+      for (const [key, entry] of entries) {
+        string(key, "JSON key", limit);
+        add(byteLength(JSON.stringify(key)) + 1);
+        target[key] = visit(entry, depth + 1);
+      }
+      result = target;
+    }
+    ancestors.delete(item);
+    return result;
+  };
+  return visit(value, 0);
+}
+function metadata(value, reserved = false) {
+  const object = record(value, "metadata");
+  if (reserved && Object.hasOwn(object, "_mem")) throw new TypeError("metadata._mem is reserved");
+  return json(object, 64 * 1024);
+}
+function signal(value) {
+  if (value === void 0) return void 0;
+  if (value === null || typeof value !== "object" || typeof value.aborted !== "boolean" || typeof value.addEventListener !== "function" || typeof value.removeEventListener !== "function") {
+    throw new TypeError("signal must be an AbortSignal");
+  }
+  return value;
+}
+function requestSignal(options) {
+  return signal(record(options, "request options", ["signal"]).signal);
+}
+
+// src/responses.ts
+var text = (value) => {
+  string(value, "response string");
+};
+var numeric = (value) => {
+  number(value, "response number");
+};
+var count = (value) => {
+  integer(value, "response count");
+};
+var millis = (value) => {
+  integer(value, "response time", Number.MIN_SAFE_INTEGER);
+};
+var bool = (value) => {
+  boolean(value, "response boolean");
+};
+var anything = (value) => {
+  if (value === void 0) throw new TypeError("Missing response value");
+};
+var optional = (check) => (value) => {
+  if (value !== void 0) check(value);
+};
+var nullable = (check) => (value) => {
+  if (value !== null) check(value);
+};
+var maybe = (check) => optional(nullable(check));
+var list = (check) => (value) => {
+  array(value, "response array").forEach(check);
+};
+var strings = list(text);
+var shape = (fields) => (value) => {
+  const object = record(value, "response");
+  for (const [key, check] of Object.entries(fields)) check(object[key]);
+};
+var status = (value) => {
+  choice(value, "fact status", ["current", "superseded", "expired", "not-yet-valid"]);
+};
+var remembered = shape({ id: text, created: bool, supersedes: strings, supersededBy: strings, ingestTime: millis });
+var chain = shape({ id: text, relation: (value) => {
+  choice(value, "chain relation", ["predecessor", "successor"]);
+}, effectiveFrom: millis, ingestTime: millis });
+var explanation = shape({
+  retrieved: bool,
+  rank: maybe(count),
+  lexicalScore: maybe(numeric),
+  semanticScore: maybe(numeric),
+  retrievalScore: maybe(numeric),
+  lexicalWeight: numeric,
+  semanticWeight: numeric,
+  fusion: text,
+  matchedTerms: strings,
+  recencyFactor: numeric,
+  historicalFactor: numeric,
+  finalScore: maybe(numeric),
+  status,
+  asOf: millis,
+  knownAt: maybe(millis),
+  validFrom: maybe(millis),
+  validTo: maybe(millis),
+  withinValidity: bool,
+  chain: list(chain)
+});
+var factFields = {
+  id: text,
+  text: maybe(text),
+  status,
+  ingestTime: maybe(millis),
+  eventTime: maybe(millis),
+  validFrom: maybe(millis),
+  validTo: maybe(millis),
+  subject: maybe(text),
+  entities: strings,
+  supersedes: strings,
+  supersededBy: strings,
+  metadata: anything
+};
+var fact = shape({ ...factFields, effectiveFrom: millis });
+var recalled = shape({ ...factFields, score: numeric, sourceUri: maybe(text), explanation: maybe(explanation) });
+var vectorIndex = shape({ rows: count, graph: bool, current: bool, staleMutations: count, rebuildRecommended: bool });
+var schemas = {
+  added: shape({ added: count }),
+  deleted: shape({ deleted: bool }),
+  chunk: shape({ revision: text, document: shape({ id: text, version: text, metadata: anything, chunkCount: count, sourceUri: maybe(text) }), index: count, id: text, startByte: count, endByte: count, text: maybe(text) }),
+  query: shape({ matches: list(shape({ id: text, text, metadata: anything, score: numeric })) }),
+  stats: shape({ tenant: text, documents: count, vectors: count, documentIndexTrained: bool, vectorIndex, usedBytes: numeric, capacityBytes: numeric }),
+  maintained: shape({ documentIndexTrained: bool, vectorIndex }),
+  capabilities: shape({ capabilities: shape({ contractVersion: count, profile: text, operations: strings, temporalQueries: bool, exactMetadataFilters: bool, subjectEntityFilters: bool, documentPagination: bool, committedErrorCode: text }) }),
+  remembered: shape({ remembered: list(remembered) }),
+  recalled: shape({ results: list(recalled) }),
+  explained: shape({ explanation }),
+  get: shape({ fact: nullable(fact) }),
+  history: shape({ history: list(fact) }),
+  forgotten: shape({ forgotten: strings, dryRun: bool, purged: bool }),
+  consolidated: shape({ created: list(remembered), forgotten: strings, dryRun: bool })
+};
+function response(schema) {
+  return (value) => {
+    schema(value);
+    return value;
+  };
+}
+function envelope(schema, key) {
+  return (value) => {
+    schema(value);
+    return value[key];
+  };
+}
+
+// src/transport.ts
+var WarmError = class extends Error {
+  code;
+  status;
+  statusCode;
+  requestId;
+  constructor(message, code, status2, requestId) {
+    super(message);
+    this.name = "WarmError";
+    this.code = code;
+    this.status = status2;
+    this.statusCode = status2;
+    this.requestId = requestId;
+  }
+};
+var Transport = class {
+  url;
+  #fetch;
+  #headers;
+  #timeout;
+  #secrets;
+  constructor(options) {
+    const config = record(options, "client options", ["url", "apiKey", "tenantId", "timeoutMs", "fetch"]);
+    const supplied = config.url === void 0 ? "http://localhost:8080" : string(config.url, "url", 8192, true);
+    let parsed;
+    try {
+      parsed = new URL(supplied);
+    } catch {
+      throw new TypeError("url must be an absolute HTTP(S) URL");
+    }
+    if (!/^https?:\/\//i.test(supplied) || !["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || supplied.slice(supplied.indexOf("//") + 2).split("/")[0].includes("@") || supplied.includes("?") || supplied.includes("#") || /[\u0000-\u0020\u007f\\]/.test(supplied)) {
+      throw new TypeError("url must be HTTP(S) without userinfo, a query, fragment, whitespace or backslash");
+    }
+    this.url = parsed.href.replace(/\/+$/, "");
+    this.#headers = new Headers({ Accept: "application/json", "Content-Type": "application/json" });
+    this.#secrets = [];
+    if (config.apiKey !== void 0) {
+      const key = string(config.apiKey, "apiKey", 8192, true);
+      if (!/^[\x21-\x7e]+$/.test(key)) throw new TypeError("apiKey must contain visible ASCII without whitespace");
+      this.#headers.set("Authorization", `Bearer ${key}`);
+      this.#secrets = [key, encodeURIComponent(key)];
+    }
+    if (config.tenantId !== void 0) {
+      const tenant = string(config.tenantId, "tenantId", 64, true);
+      if (!/^[A-Za-z0-9_-]+$/.test(tenant)) throw new TypeError("tenantId must contain only letters, digits, underscores or hyphens");
+      this.#headers.set("X-Tenant-ID", tenant);
+    }
+    this.#timeout = config.timeoutMs === void 0 ? 3e4 : integer(config.timeoutMs, "timeoutMs", 1, 2147483647);
+    const implementation = config.fetch === void 0 ? globalThis.fetch : config.fetch;
+    if (typeof implementation !== "function") throw new TypeError("A Fetch API implementation is required");
+    const fetcher = implementation;
+    this.#fetch = config.fetch === void 0 ? fetcher.bind(globalThis) : fetcher;
+  }
+  #safe(value, fallback, max) {
+    if (typeof value !== "string" || /[<>]/.test(value)) return fallback;
+    let result = value;
+    for (const secret of this.#secrets) result = result.split(secret).join("[redacted]");
+    return result.replace(/Bearer\s+[^\s,;]+/gi, "Bearer [redacted]").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").slice(0, max) || fallback;
+  }
+  #error(response2, body) {
+    const value = body !== null && typeof body === "object" && !Array.isArray(body) ? body : {};
+    const legacy = value.error !== null && typeof value.error === "object" && !Array.isArray(value.error) ? value.error : {};
+    const rawCode = this.#safe(value.code ?? legacy.code, "http_error", 64);
+    const code = /^[A-Za-z0-9_.:-]+$/.test(rawCode) ? rawCode : "http_error";
+    const message = this.#safe(value.detail ?? legacy.message, `WARM request failed (HTTP ${response2.status})`, 1024);
+    const identifier = this.#safe(response2.headers.get("x-request-id") ?? value.request_id, "", 128);
+    return new WarmError(message, code, response2.status, /^[A-Za-z0-9_.:-]+$/.test(identifier) ? identifier : void 0);
+  }
+  async request(method, path, payload, signal2, decode) {
+    let body;
+    if (payload !== void 0) {
+      try {
+        body = JSON.stringify(json(payload));
+      } catch (error) {
+        if (error instanceof JsonSizeError) throw new WarmError("Request exceeds 16 MiB", "request_too_large");
+        throw error;
+      }
+      if (byteLength(body) > MAX_BYTES) throw new WarmError("Request exceeds 16 MiB", "request_too_large");
+    }
+    if (signal2?.aborted) throw new WarmError("Request was aborted", "aborted");
+    const controller = new AbortController();
+    let timedOut = false;
+    let rejectAbort;
+    const aborted = new Promise((_, reject) => {
+      rejectAbort = reject;
+    });
+    const abort = () => {
+      controller.abort();
+      rejectAbort(new WarmError(timedOut ? "Request timed out" : "Request was aborted", timedOut ? "timeout" : "aborted"));
+    };
+    signal2?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      abort();
+    }, this.#timeout);
+    let response2;
+    let reader;
+    let finished = false;
+    try {
+      if (signal2?.aborted) abort();
+      const fetched = Promise.resolve().then(() => {
+        if (controller.signal.aborted) throw new WarmError("Request was aborted", "aborted");
+        return this.#fetch(`${this.url}${path}`, {
+          method,
+          headers: new Headers(this.#headers),
+          body,
+          signal: controller.signal,
+          redirect: "manual",
+          credentials: "omit",
+          referrerPolicy: "no-referrer"
+        });
+      }).then((value) => {
+        if (controller.signal.aborted) void value.body?.cancel().catch(() => {
+        });
+        return value;
+      });
+      response2 = await Promise.race([fetched, aborted]);
+      if (response2.type === "opaqueredirect" || response2.redirected || response2.status >= 300 && response2.status < 400) {
+        throw new WarmError("WARM redirects are not followed", "redirect_error", response2.status || void 0);
+      }
+      const declared = response2.headers.get("content-length");
+      if (declared && /^\d+$/.test(declared) && Number(declared) > MAX_BYTES) throw new WarmError("Response exceeds 16 MiB", "response_too_large", response2.status);
+      const chunks = [];
+      let length = 0;
+      if (response2.body) {
+        reader = response2.body.getReader();
+        for (; ; ) {
+          const chunk = await Promise.race([reader.read(), aborted]);
+          if (chunk.done) break;
+          length += chunk.value.byteLength;
+          if (length > MAX_BYTES) throw new WarmError("Response exceeds 16 MiB", "response_too_large", response2.status);
+          chunks.push(chunk.value);
+        }
+      }
+      finished = true;
+      const bytes = new Uint8Array(length);
+      let offset = 0;
+      for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+      } catch {
+        if (!response2.ok) throw this.#error(response2, void 0);
+        throw new WarmError("WARM returned an invalid JSON response", "invalid_response", response2.status);
+      }
+      if (!response2.ok) throw this.#error(response2, parsed);
+      try {
+        json(parsed);
+        return decode(parsed);
+      } catch {
+        throw new WarmError("WARM returned a response outside the documented contract", "invalid_response", response2.status);
+      }
+    } catch (error) {
+      if (error instanceof WarmError) throw error;
+      if (controller.signal.aborted) throw new WarmError(timedOut ? "Request timed out" : "Request was aborted", timedOut ? "timeout" : "aborted");
+      throw new WarmError("Unable to complete the WARM request", "network_error");
+    } finally {
+      clearTimeout(timer);
+      signal2?.removeEventListener("abort", abort);
+      if (!finished) {
+        if (reader) void reader.cancel().catch(() => {
+        });
+        else if (response2?.body) void response2.body.cancel().catch(() => {
+        });
+      }
+      reader?.releaseLock();
+    }
+  }
+};
+
+// src/client.ts
+var time = (value) => integer(value, "time", Number.MIN_SAFE_INTEGER);
+var text2 = (value) => string(value, "text", 64 * 1024);
+var optionalString = (value) => string(value, "string");
+var filter = (value) => json(record(value, "filter"));
+var bool2 = (value) => boolean(value, "option");
+var rememberKeys = ["id", "eventTime", "validFrom", "validTo", "subject", "supersedes", "entities", "metadata", "embedding", "sourceUri"];
+var recallKeys = ["k", "asOf", "knownAt", "history", "subject", "entities", "filter", "embedding", "lexicalWeight", "semanticWeight", "minSemanticScore", "fusion", "candidateLimit", "explain"];
+function copy(source, target, key, validate, wire = key, nullable2 = true) {
+  if (source[key] !== void 0) target[wire] = source[key] === null && nullable2 ? null : validate(source[key]);
+}
+function label(value) {
+  const result = string(value, "label");
+  string(result.trim(), "label", 1024, true);
+  if (result.includes("\0")) throw new TypeError("Labels must not contain NUL");
+  return result;
+}
+function labels(value) {
+  const items = array(value, "entities").map(label);
+  if (new Set(items.map((item) => item.trim())).size > 256) throw new RangeError("At most 256 distinct entities are supported");
+  return items;
+}
+function links(value) {
+  const items = array(value, "supersedes").map(id);
+  if (new Set(items).size > 256) throw new RangeError("At most 256 distinct supersedes IDs are supported");
+  return items;
+}
+function fact2(source, content) {
+  const out = { text: string(content, "text", 64 * 1024, true) };
+  copy(source, out, "id", id);
+  for (const key of ["eventTime", "validFrom", "validTo"]) copy(source, out, key, time);
+  copy(source, out, "subject", label);
+  copy(source, out, "supersedes", links);
+  copy(source, out, "entities", labels);
+  copy(source, out, "metadata", (value) => metadata(value, true));
+  copy(source, out, "embedding", vector);
+  copy(source, out, "sourceUri", optionalString);
+  if (typeof out.validFrom === "number" && typeof out.validTo === "number" && out.validFrom >= out.validTo) throw new RangeError("validFrom must be before validTo");
+  return out;
+}
+function recall(source, query) {
+  const out = { query: string(query, "query", 8192) };
+  copy(source, out, "k", (value) => integer(value, "k", 1, 1e3));
+  copy(source, out, "candidateLimit", (value) => integer(value, "candidateLimit", 1, 4096));
+  for (const key of ["asOf", "knownAt"]) copy(source, out, key, time);
+  copy(source, out, "history", (value) => choice(value, "history", ["current", "all", "historical"]));
+  copy(source, out, "subject", label);
+  copy(source, out, "entities", labels);
+  copy(source, out, "filter", filter);
+  copy(source, out, "embedding", vector);
+  for (const key of ["lexicalWeight", "semanticWeight"]) copy(source, out, key, (value) => number(value, key, 0));
+  copy(source, out, "minSemanticScore", (value) => number(value, "minSemanticScore", -1, 1));
+  copy(source, out, "fusion", (value) => choice(value, "fusion", ["blend", "rrf"]));
+  copy(source, out, "explain", bool2, "explain", false);
+  if (typeof out.k === "number" && typeof out.candidateLimit === "number" && out.candidateLimit < out.k) throw new RangeError("candidateLimit must be at least k");
+  const weight = (out.lexicalWeight ?? 1) + (out.semanticWeight ?? 1);
+  if (!Number.isFinite(weight) || weight <= 0) throw new RangeError("Search weights must have a finite positive sum");
+  return out;
+}
+function forgetOptions(options, dryRun) {
+  return {
+    includeChain: options.includeChain === void 0 ? false : boolean(options.includeChain, "includeChain"),
+    dryRun: options.dryRun === void 0 ? dryRun : boolean(options.dryRun, "dryRun"),
+    purge: options.purge === void 0 ? false : boolean(options.purge, "purge")
+  };
+}
+function boundedBatch(values, convert, overhead) {
+  const items = array(values, "batch", 4096);
+  let bytes = overhead + Math.max(0, items.length - 1);
+  return items.map((value) => {
+    const item = convert(value);
+    bytes += byteLength(JSON.stringify(item));
+    if (bytes > MAX_BYTES) throw new WarmError("Request exceeds 16 MiB", "request_too_large");
+    return item;
+  });
+}
+var WarmClient = class {
+  url;
+  #transport;
+  #memory;
+  constructor(options = {}) {
+    this.#transport = new Transport(options);
+    this.url = this.#transport.url;
+    this.#memory = new MemoryClient(this.#transport);
+  }
+  get memory() {
+    return this.#memory;
+  }
+  async addDocuments(documents, options = {}) {
+    const signal2 = requestSignal(options);
+    const payload = boundedBatch(documents, (item) => {
+      const source = record(item, "document", ["id", "text", "vector", "metadata", "importIdentity", "importAdoptLegacy"]);
+      const out = { id: id(source.id) };
+      copy(source, out, "text", text2);
+      copy(source, out, "vector", vector);
+      copy(source, out, "metadata", (value) => metadata(value));
+      copy(source, out, "importIdentity", (value) => {
+        const identity = string(value, "importIdentity", 64);
+        if (!/^[0-9a-f]{64}$/.test(identity)) throw new TypeError("importIdentity must be a lowercase SHA-256 digest");
+        return identity;
+      }, "import_identity");
+      copy(source, out, "importAdoptLegacy", bool2, "import_adopt_legacy", false);
+      const stamp = out.metadata == null ? void 0 : out.metadata.warm_import_identity;
+      if (out.import_identity != null || stamp !== void 0 || out.import_adopt_legacy === true) {
+        if (typeof out.import_identity !== "string" || stamp !== out.import_identity) throw new TypeError("importIdentity must match metadata.warm_import_identity");
+      }
+      if (out.vector == null && !(typeof out.text === "string" && out.text.trim())) throw new TypeError("A document requires a vector or nonempty text for a server-side embedder");
+      return out;
+    }, 2);
+    if (payload.length === 0) {
+      if (signal2?.aborted) throw new WarmError("Request was aborted", "aborted");
+      return { added: 0 };
+    }
+    return this.#transport.request("POST", "/api/v1/documents/batch", payload, signal2, response(schemas.added));
+  }
+  async deleteDocument(id2, options = {}) {
+    return this.#transport.request("DELETE", `/api/v1/documents/${segment(id2)}`, void 0, requestSignal(options), response(schemas.deleted));
+  }
+  async readDocumentChunk(id2, index = 0, options = {}) {
+    const path = `/api/v1/documents/${segment(id2)}/chunks/${integer(index, "chunk index")}`;
+    return this.#transport.request("GET", path, void 0, requestSignal(options), response(schemas.chunk));
+  }
+  async stats(options = {}) {
+    return this.#transport.request("GET", "/api/v1/stats", void 0, requestSignal(options), response(schemas.stats));
+  }
+  async maintainDocumentIndex(options = {}) {
+    return this.#transport.request("POST", "/api/v1/index/maintain", {}, requestSignal(options), response(schemas.maintained));
+  }
+  async query(input, options = {}) {
+    const source = record(input, "query input", ["query", "queryVector", "today", "topK", "filter", "documentIds", "index", "ef"]);
+    const out = { top_k: source.topK === void 0 ? 3 : source.topK === null ? null : integer(source.topK, "topK", 1) };
+    copy(source, out, "query", (value) => string(value, "query", 8192, true));
+    copy(source, out, "queryVector", vector, "query_vector");
+    copy(source, out, "today", optionalString);
+    copy(source, out, "filter", filter);
+    copy(source, out, "documentIds", (value) => {
+      const ids = array(value, "documentIds", 1e3, 1).map(id);
+      if (new Set(ids).size !== ids.length) throw new TypeError("documentIds must be unique");
+      return ids;
+    }, "document_ids");
+    copy(source, out, "index", (value) => choice(value, "index", ["auto", "exact", "graph"]));
+    copy(source, out, "ef", (value) => integer(value, "ef", 1, 4096));
+    if (out.query == null && out.query_vector == null) throw new TypeError("query requires query or queryVector");
+    return this.#transport.request("POST", "/api/v1/query", out, requestSignal(options), response(schemas.query));
+  }
+};
+var MemoryClient = class {
+  #transport;
+  constructor(transport) {
+    this.#transport = transport;
+  }
+  async capabilities(contractVersion = 1, options = {}) {
+    const payload = { contractVersion: integer(contractVersion, "contractVersion", 1, 4294967295) };
+    return this.#transport.request("POST", "/api/v1/memory/capabilities", payload, requestSignal(options), envelope(schemas.capabilities, "capabilities"));
+  }
+  async remember(text3, options = {}) {
+    const source = record(options, "remember options", [...rememberKeys, "signal"]);
+    const payload = fact2(source, text3);
+    return this.#transport.request("POST", "/api/v1/memory/remember", payload, signal(source.signal), (value) => {
+      const items = envelope(schemas.remembered, "remembered")(value);
+      if (items.length !== 1) throw new TypeError("Expected one remembered fact");
+      return items[0];
+    });
+  }
+  async rememberMany(facts, options = {}) {
+    const values = boundedBatch(facts, (item) => {
+      const source = record(item, "fact", ["text", ...rememberKeys]);
+      return fact2(source, source.text);
+    }, 12);
+    if (!values.length) throw new RangeError("rememberMany requires at least one fact");
+    return this.#transport.request("POST", "/api/v1/memory/remember", { facts: values }, requestSignal(options), (value) => {
+      const items = envelope(schemas.remembered, "remembered")(value);
+      if (items.length !== values.length) throw new TypeError("Remembered count does not match submitted facts");
+      return items;
+    });
+  }
+  async recall(query, options = {}) {
+    const source = record(options, "recall options", [...recallKeys, "signal"]);
+    return this.#transport.request("POST", "/api/v1/memory/recall", recall(source, query), signal(source.signal), envelope(schemas.recalled, "results"));
+  }
+  async explain(query, id2, options = {}) {
+    const source = record(options, "explain options", [...recallKeys, "signal"]);
+    const payload = { ...recall(source, query), id: id(id2) };
+    return this.#transport.request("POST", "/api/v1/memory/explain", payload, signal(source.signal), envelope(schemas.explained, "explanation"));
+  }
+  async forget(scope, options = {}) {
+    const source = record(scope, "forget scope");
+    const kind = choice(source.kind, "scope kind", ["ids", "subject", "entity", "ingestedBefore", "eventBefore", "matching"]);
+    let chosen;
+    if (kind === "ids") {
+      record(source, "forget scope", ["kind", "ids"]);
+      chosen = { kind, ids: array(source.ids, "ids").map(id) };
+    } else if (kind === "subject" || kind === "entity") {
+      record(source, "forget scope", ["kind", kind]);
+      chosen = { kind, [kind]: label(source[kind]) };
+    } else if (kind === "matching") {
+      record(source, "forget scope", ["kind", "filter"]);
+      const matching = record(source.filter, "filter");
+      if (!Object.keys(matching).length || Object.hasOwn(matching, "_mem")) throw new TypeError("Forget filter must be nonempty and must not contain reserved metadata._mem");
+      chosen = { kind, filter: filter(matching) };
+    } else {
+      record(source, "forget scope", ["kind", "time"]);
+      chosen = { kind, time: time(source.time) };
+    }
+    const settings = record(options, "forget options", ["includeChain", "dryRun", "purge", "signal"]);
+    return this.#transport.request("POST", "/api/v1/memory/forget", { scope: chosen, ...forgetOptions(settings, false) }, signal(settings.signal), response(schemas.forgotten));
+  }
+  async get(id2, options = {}) {
+    return this.#transport.request("POST", "/api/v1/memory/get", { id: id(id2) }, requestSignal(options), envelope(schemas.get, "fact"));
+  }
+  async history(id2, options = {}) {
+    return this.#transport.request("POST", "/api/v1/memory/history", { id: id(id2) }, requestSignal(options), envelope(schemas.history, "history"));
+  }
+  async applyForgetting(options = {}) {
+    const source = record(options, "forgetting options", ["includeChain", "dryRun", "purge", "signal"]);
+    return this.#transport.request("POST", "/api/v1/memory/applyForgetting", forgetOptions(source, true), signal(source.signal), response(schemas.forgotten));
+  }
+  async consolidate(options = {}) {
+    const source = record(options, "consolidation options", ["dryRun", "allowDestructive", "signal"]);
+    const payload = {
+      dryRun: source.dryRun === void 0 ? true : boolean(source.dryRun, "dryRun"),
+      allowDestructive: source.allowDestructive === void 0 ? false : boolean(source.allowDestructive, "allowDestructive")
+    };
+    return this.#transport.request("POST", "/api/v1/memory/consolidate", payload, signal(source.signal), response(schemas.consolidated));
+  }
+};
+//# sourceMappingURL=index.cjs.map