inputlayer-js-dev 0.1.0-dev.ec507e7

package/dist/index.mjs

@@ -0,0 +1,2034 @@
+import {
+  aggExpr,
+  and,
+  arithmetic,
+  column,
+  comparison,
+  inExpr,
+  isAggExpr,
+  isAnd,
+  isArithmetic,
+  isColumn,
+  isComparison,
+  isFuncCall,
+  isInExpr,
+  isLiteral,
+  isMatchExpr,
+  isNegatedIn,
+  isNot,
+  isOr,
+  isOrderedColumn,
+  literal,
+  matchExpr,
+  negatedIn,
+  not,
+  or,
+  orderedColumn
+} from "./chunk-S3PNNRWY.mjs";
+
+// src/types.ts
+var Timestamp = class _Timestamp {
+  constructor(ms) {
+    this.ms = Math.floor(ms);
+  }
+  static now() {
+    return new _Timestamp(Date.now());
+  }
+  static fromDate(date) {
+    return new _Timestamp(date.getTime());
+  }
+  toDate() {
+    return new Date(this.ms);
+  }
+  valueOf() {
+    return this.ms;
+  }
+  toString() {
+    return String(this.ms);
+  }
+};
+
+// src/naming.ts
+function camelToSnake(name) {
+  let s = name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2");
+  s = s.replace(/([a-z0-9])([A-Z])/g, "$1_$2");
+  return s.toLowerCase();
+}
+function snakeToCamel(name) {
+  return name.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function columnToVariable(columnName) {
+  return snakeToCamel(columnName);
+}
+
+// src/proxy.ts
+function wrap(value) {
+  if (value instanceof ColumnProxy) {
+    return value.toAst();
+  }
+  if (value !== null && typeof value === "object" && "_tag" in value) {
+    return value;
+  }
+  return literal(value);
+}
+var ColumnProxy = class {
+  constructor(relation2, name, refAlias) {
+    this.relation = relation2;
+    this.name = name;
+    this.refAlias = refAlias;
+  }
+  toAst() {
+    return column(this.relation, this.name, this.refAlias);
+  }
+  // ── Comparison operators -> BoolExpr ────────────────────────────
+  eq(other) {
+    return comparison("=", this.toAst(), wrap(other));
+  }
+  ne(other) {
+    return comparison("!=", this.toAst(), wrap(other));
+  }
+  lt(other) {
+    return comparison("<", this.toAst(), wrap(other));
+  }
+  le(other) {
+    return comparison("<=", this.toAst(), wrap(other));
+  }
+  gt(other) {
+    return comparison(">", this.toAst(), wrap(other));
+  }
+  ge(other) {
+    return comparison(">=", this.toAst(), wrap(other));
+  }
+  // ── Arithmetic operators -> Expr ────────────────────────────────
+  add(other) {
+    return arithmetic("+", this.toAst(), wrap(other));
+  }
+  sub(other) {
+    return arithmetic("-", this.toAst(), wrap(other));
+  }
+  mul(other) {
+    return arithmetic("*", this.toAst(), wrap(other));
+  }
+  div(other) {
+    return arithmetic("/", this.toAst(), wrap(other));
+  }
+  mod(other) {
+    return arithmetic("%", this.toAst(), wrap(other));
+  }
+  // ── Membership ──────────────────────────────────────────────────
+  in(other) {
+    return inExpr(this.toAst(), other.toAst());
+  }
+  notIn(other) {
+    return negatedIn(this.toAst(), other.toAst());
+  }
+  // ── Ordering ────────────────────────────────────────────────────
+  asc() {
+    return orderedColumn(this.toAst(), false);
+  }
+  desc() {
+    return orderedColumn(this.toAst(), true);
+  }
+  // ── Multi-column match ──────────────────────────────────────────
+  matches(relationName, on) {
+    const bindings = {};
+    for (const [targetCol, sourceColName] of Object.entries(on)) {
+      bindings[targetCol] = column(this.relation, sourceColName, this.refAlias);
+    }
+    return matchExpr(relationName, bindings, false);
+  }
+  notMatches(relationName, on) {
+    const bindings = {};
+    for (const [targetCol, sourceColName] of Object.entries(on)) {
+      bindings[targetCol] = column(this.relation, sourceColName, this.refAlias);
+    }
+    return matchExpr(relationName, bindings, true);
+  }
+};
+function AND(left, right) {
+  return and(left, right);
+}
+function OR(left, right) {
+  return or(left, right);
+}
+function NOT(operand) {
+  return not(operand);
+}
+var RelationProxy = class {
+  constructor(relationName, refAlias) {
+    this.relationName = relationName;
+    this.refAlias = refAlias;
+  }
+  /** Get a ColumnProxy for the named column. */
+  col(name) {
+    return new ColumnProxy(this.relationName, name, this.refAlias);
+  }
+};
+var RelationRef = class {
+  constructor(schema, alias) {
+    this.schema = schema;
+    this.alias = alias;
+    this.relationName = schema.name ?? camelToSnake(alias);
+  }
+  /** Get a ColumnProxy for the named column. */
+  col(name) {
+    return new ColumnProxy(this.relationName, name, this.alias);
+  }
+};
+
+// src/relation.ts
+var RelationDef = class {
+  constructor(className, columnTypes, name) {
+    this.className = className;
+    this.relationName = name ?? camelToSnake(className);
+    this.columns = Object.keys(columnTypes);
+    this.columnTypes = { ...columnTypes };
+  }
+  /** Get a ColumnProxy for a column (for query building). */
+  col(name) {
+    if (!(name in this.columnTypes)) {
+      throw new Error(
+        `Column '${name}' does not exist on relation '${this.relationName}'. Available: ${this.columns.join(", ")}`
+      );
+    }
+    return new ColumnProxy(this.relationName, name);
+  }
+  /**
+   * Create multiple independent references for self-joins.
+   *
+   * Usage:
+   *   const [r1, r2] = Follow.refs(2);
+   *   kg.query({ select: [r1.col("follower"), r2.col("followee")], join: [r1, r2], ... });
+   */
+  refs(n) {
+    const refs = [];
+    for (let i = 1; i <= n; i++) {
+      refs.push(
+        new RelationRef(
+          { name: this.relationName, columns: this.columns.map((c) => ({ name: c, type: this.columnTypes[c] })) },
+          `${this.relationName}_${i}`
+        )
+      );
+    }
+    return refs;
+  }
+};
+function relation(className, columnTypes, opts) {
+  return new RelationDef(className, columnTypes, opts?.name);
+}
+function compileValue(value) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (value instanceof Timestamp) {
+    return String(value.ms);
+  }
+  if (typeof value === "number") {
+    if (Number.isInteger(value)) {
+      return String(value);
+    }
+    return String(value);
+  }
+  if (typeof value === "string") {
+    const escaped = value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return `"${escaped}"`;
+  }
+  if (Array.isArray(value)) {
+    const inner = value.map(compileValue).join(", ");
+    return `[${inner}]`;
+  }
+  throw new TypeError(
+    `Cannot compile value of type ${typeof value}: ${String(value)}`
+  );
+}
+function resolveRelationName(r) {
+  if (typeof r === "string") return r;
+  return r.relationName;
+}
+function getColumns(r) {
+  return r.columns;
+}
+function getColumnTypes(r) {
+  return r.columnTypes;
+}
+
+// src/derived.ts
+var FromWhere = class {
+  constructor(relations, condition) {
+    this.relations = relations;
+    this.condition = condition;
+  }
+  /**
+   * Map derived columns to body expressions.
+   * Keys must match the derived relation's column names.
+   */
+  select(columns) {
+    const selectMap = {};
+    for (const [name, val] of Object.entries(columns)) {
+      if (val instanceof ColumnProxy) {
+        selectMap[name] = val.toAst();
+      } else {
+        selectMap[name] = val;
+      }
+    }
+    return {
+      relations: this.relations,
+      selectMap,
+      condition: this.condition
+    };
+  }
+};
+var FromBuilder = class {
+  constructor(rels) {
+    this.relations = rels.map((r) => {
+      if (r instanceof RelationDef) {
+        return { name: r.relationName, def: r, alias: void 0 };
+      }
+      return {
+        name: r.relationName,
+        def: {
+          relationName: r.relationName,
+          columns: r.schema.columns.map((c) => c.name),
+          columnTypes: {}
+        },
+        alias: r.alias
+      };
+    });
+  }
+  /**
+   * Add a filter/join condition.
+   * Accepts a BoolExpr or a callback receiving RelationProxy objects.
+   */
+  where(condition) {
+    let resolved;
+    if (typeof condition === "function") {
+      const proxies = this.relations.map(
+        (r) => new RelationProxy(r.name, r.alias)
+      );
+      resolved = condition(...proxies);
+    } else {
+      resolved = condition;
+    }
+    return new FromWhere(this.relations, resolved);
+  }
+  /**
+   * Map derived columns to body expressions (no filter).
+   * Keys must match the derived relation's column names.
+   */
+  select(columns) {
+    const selectMap = {};
+    for (const [name, val] of Object.entries(columns)) {
+      if (val instanceof ColumnProxy) {
+        selectMap[name] = val.toAst();
+      } else {
+        selectMap[name] = val;
+      }
+    }
+    return {
+      relations: this.relations,
+      selectMap,
+      condition: void 0
+    };
+  }
+};
+function from(...relations) {
+  return new FromBuilder(relations);
+}
+
+// src/aggregations.ts
+function toExpr(col) {
+  if ("toAst" in col && typeof col.toAst === "function") {
+    return col.toAst();
+  }
+  return col;
+}
+function count(column2) {
+  if (column2 === void 0) {
+    return aggExpr({ func: "count" });
+  }
+  return aggExpr({ func: "count", column: toExpr(column2) });
+}
+function countDistinct(column2) {
+  return aggExpr({ func: "count_distinct", column: toExpr(column2) });
+}
+function sum(column2) {
+  return aggExpr({ func: "sum", column: toExpr(column2) });
+}
+function min(column2) {
+  return aggExpr({ func: "min", column: toExpr(column2) });
+}
+function max(column2) {
+  return aggExpr({ func: "max", column: toExpr(column2) });
+}
+function avg(column2) {
+  return aggExpr({ func: "avg", column: toExpr(column2) });
+}
+function topK(opts) {
+  return aggExpr({
+    func: "top_k",
+    params: [opts.k],
+    passthrough: (opts.passthrough ?? []).map(toExpr),
+    orderColumn: toExpr(opts.orderBy),
+    desc: opts.desc ?? true
+  });
+}
+function topKThreshold(opts) {
+  return aggExpr({
+    func: "top_k_threshold",
+    params: [opts.k, opts.threshold],
+    passthrough: (opts.passthrough ?? []).map(toExpr),
+    orderColumn: toExpr(opts.orderBy),
+    desc: opts.desc ?? true
+  });
+}
+function withinRadius(opts) {
+  return aggExpr({
+    func: "within_radius",
+    params: [opts.maxDistance],
+    passthrough: (opts.passthrough ?? []).map(toExpr),
+    orderColumn: toExpr(opts.distance),
+    desc: !(opts.asc ?? true)
+  });
+}
+
+// src/index-def.ts
+var HnswIndex = class {
+  constructor(opts) {
+    this.name = opts.name;
+    this.relation = opts.relation;
+    this.column = opts.column;
+    this.metric = opts.metric ?? "cosine";
+    this.m = opts.m ?? 16;
+    this.efConstruction = opts.efConstruction ?? 100;
+    this.efSearch = opts.efSearch ?? 50;
+  }
+  /** Compile this index definition to an IQL meta command. */
+  toIQL() {
+    const relName = resolveRelationName(this.relation);
+    return `.index create ${this.name} on ${relName}(${this.column}) type hnsw metric ${this.metric} m ${this.m} ef_construction ${this.efConstruction} ef_search ${this.efSearch}`;
+  }
+};
+
+// src/errors.ts
+var InputLayerError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InputLayerError";
+  }
+};
+var ConnectionError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionError";
+  }
+};
+var AuthenticationError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+};
+var SchemaConflictError = class extends InputLayerError {
+  constructor(message, opts) {
+    super(message);
+    this.name = "SchemaConflictError";
+    this.existingSchema = opts?.existingSchema;
+    this.proposedSchema = opts?.proposedSchema;
+    this.conflicts = opts?.conflicts ?? [];
+  }
+};
+var ValidationError = class extends InputLayerError {
+  constructor(message, opts) {
+    super(message);
+    this.name = "ValidationError";
+    this.details = opts?.details ?? [];
+  }
+};
+var QueryTimeoutError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "QueryTimeoutError";
+  }
+};
+var PermissionError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "PermissionError";
+  }
+};
+var KnowledgeGraphNotFoundError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "KnowledgeGraphNotFoundError";
+  }
+};
+var KnowledgeGraphExistsError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "KnowledgeGraphExistsError";
+  }
+};
+var CannotDropError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "CannotDropError";
+  }
+};
+var RelationNotFoundError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "RelationNotFoundError";
+  }
+};
+var RuleNotFoundError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "RuleNotFoundError";
+  }
+};
+var IndexNotFoundError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "IndexNotFoundError";
+  }
+};
+var InternalError = class extends InputLayerError {
+  constructor(message) {
+    super(message);
+    this.name = "InternalError";
+  }
+};
+
+// src/result.ts
+var ResultSet = class {
+  constructor(opts) {
+    this.columns = opts.columns;
+    this.rows = opts.rows;
+    this.rowCount = opts.rowCount ?? opts.rows.length;
+    this.totalCount = opts.totalCount ?? this.rowCount;
+    this.truncated = opts.truncated ?? false;
+    this.executionTimeMs = opts.executionTimeMs ?? 0;
+    this.rowProvenance = opts.rowProvenance;
+    this.hasEphemeral = opts.hasEphemeral ?? false;
+    this.ephemeralSources = opts.ephemeralSources ?? [];
+    this.warnings = opts.warnings ?? [];
+  }
+  /** Number of result rows. */
+  get length() {
+    return this.rowCount;
+  }
+  /** True if there are any results. */
+  get isEmpty() {
+    return this.rowCount === 0;
+  }
+  /** Get a single row as a keyed object. */
+  get(index) {
+    return this.rowToObj(this.rows[index]);
+  }
+  /** Get the first row or undefined if empty. */
+  first() {
+    if (this.rows.length === 0) return void 0;
+    return this.rowToObj(this.rows[0]);
+  }
+  /** Return the single value from a 1x1 result. */
+  scalar() {
+    if (this.rows.length === 0 || this.rows[0].length === 0) {
+      throw new Error("No results to extract scalar from");
+    }
+    return this.rows[0][0];
+  }
+  /** Convert all rows to a list of keyed objects. */
+  toDicts() {
+    return this.rows.map((row) => this.rowToObj(row));
+  }
+  /** Convert all rows to a list of tuples (arrays). */
+  toTuples() {
+    return this.rows.map((row) => [...row]);
+  }
+  /** Iterate over rows as keyed objects. */
+  [Symbol.iterator]() {
+    let i = 0;
+    const self = this;
+    return {
+      next() {
+        if (i < self.rows.length) {
+          return { value: self.rowToObj(self.rows[i++]), done: false };
+        }
+        return { value: void 0, done: true };
+      }
+    };
+  }
+  rowToObj(row) {
+    const obj = {};
+    for (let i = 0; i < this.columns.length && i < row.length; i++) {
+      obj[this.columns[i]] = row[i];
+    }
+    return obj;
+  }
+};
+
+// src/connection.ts
+import WebSocket from "ws";
+
+// src/protocol.ts
+function serializeMessage(msg) {
+  return JSON.stringify(msg);
+}
+function deserializeMessage(data) {
+  const obj = JSON.parse(data);
+  const type = obj.type;
+  if (type === "authenticated") {
+    return obj;
+  }
+  if (type === "auth_error") {
+    return obj;
+  }
+  if (type === "result") {
+    return obj;
+  }
+  if (type === "error") {
+    return obj;
+  }
+  if (type === "result_start") {
+    return obj;
+  }
+  if (type === "result_chunk") {
+    return obj;
+  }
+  if (type === "result_end") {
+    return obj;
+  }
+  if (type === "pong") {
+    return obj;
+  }
+  if (type === "persistent_update" || type === "rule_change" || type === "kg_change" || type === "schema_change") {
+    return obj;
+  }
+  throw new Error(`Unknown message type: ${type}`);
+}
+
+// src/notifications.ts
+var NotificationDispatcher = class {
+  constructor() {
+    this.callbacks = [];
+    this._lastSeq = 0;
+    this.waiters = [];
+  }
+  get lastSeq() {
+    return this._lastSeq;
+  }
+  /**
+   * Register a callback for notifications.
+   *
+   * @param eventType - Filter by event type (e.g. "persistent_update")
+   * @param opts - Additional filters
+   * @param callback - Function to call when a matching event arrives
+   */
+  on(eventType, opts, callback) {
+    this.callbacks.push({
+      eventType,
+      relation: opts.relation,
+      knowledgeGraph: opts.knowledgeGraph,
+      callback
+    });
+  }
+  /** Remove a previously registered callback. */
+  off(callback) {
+    this.callbacks = this.callbacks.filter((e) => e.callback !== callback);
+  }
+  /** Dispatch a notification to matching callbacks. */
+  dispatch(event) {
+    this._lastSeq = Math.max(this._lastSeq, event.seq);
+    for (const waiter of this.waiters) {
+      waiter(event);
+    }
+    this.waiters = [];
+    for (const entry of this.callbacks) {
+      if (entry.eventType !== void 0 && event.type !== entry.eventType) continue;
+      if (entry.relation !== void 0 && event.relation !== entry.relation) continue;
+      if (entry.knowledgeGraph !== void 0 && event.knowledgeGraph !== entry.knowledgeGraph) continue;
+      try {
+        entry.callback(event);
+      } catch {
+      }
+    }
+  }
+  /** Wait for the next notification event. */
+  next() {
+    return new Promise((resolve) => {
+      this.waiters.push(resolve);
+    });
+  }
+  /**
+   * Create an async iterable of notification events.
+   *
+   * Usage:
+   *   for await (const event of dispatcher.events()) { ... }
+   */
+  async *events() {
+    while (true) {
+      yield await this.next();
+    }
+  }
+};
+
+// src/connection.ts
+var Connection = class {
+  constructor(opts) {
+    this.ws = null;
+    this._connected = false;
+    this._dispatcher = new NotificationDispatcher();
+    this.url = opts.url;
+    this.username = opts.username;
+    this.password = opts.password;
+    this.apiKey = opts.apiKey;
+    this.autoReconnect = opts.autoReconnect ?? true;
+    this.reconnectDelay = opts.reconnectDelay ?? 1;
+    this.maxReconnectAttempts = opts.maxReconnectAttempts ?? 10;
+    this.initialKg = opts.initialKg;
+    this._lastSeq = opts.lastSeq;
+  }
+  // ── Properties ──────────────────────────────────────────────────
+  get connected() {
+    return this._connected;
+  }
+  get sessionId() {
+    return this._sessionId;
+  }
+  get serverVersion() {
+    return this._serverVersion;
+  }
+  get role() {
+    return this._role;
+  }
+  get currentKg() {
+    return this._currentKg;
+  }
+  /** Force-set the current KG (used by KnowledgeGraph after .kg use). */
+  setCurrentKg(name) {
+    this._currentKg = name;
+  }
+  get dispatcher() {
+    return this._dispatcher;
+  }
+  get lastSeq() {
+    return this._dispatcher.lastSeq;
+  }
+  // ── Connection lifecycle ────────────────────────────────────────
+  async connect() {
+    let wsUrl = this.url;
+    const params = [];
+    if (this.initialKg) {
+      params.push(`kg=${this.initialKg}`);
+    }
+    if (this._lastSeq !== void 0) {
+      params.push(`last_seq=${this._lastSeq}`);
+    }
+    if (params.length > 0) {
+      const separator = wsUrl.includes("?") ? "&" : "?";
+      wsUrl = `${wsUrl}${separator}${params.join("&")}`;
+    }
+    try {
+      this.ws = await this.createWebSocket(wsUrl);
+    } catch (e) {
+      throw new ConnectionError(`Failed to connect to ${wsUrl}: ${e}`);
+    }
+    await this.authenticate();
+    this._connected = true;
+    this.ws.on("message", (data) => {
+      try {
+        const msg = deserializeMessage(String(data));
+        if (this.pendingResolve) {
+          this.pendingResolve(msg);
+          this.pendingResolve = void 0;
+        } else if (this.isNotification(msg)) {
+          this.dispatchNotification(msg);
+        }
+      } catch {
+      }
+    });
+    this.ws.on("close", () => {
+      this._connected = false;
+      if (this.autoReconnect) {
+        this.reconnect().catch(() => {
+        });
+      }
+    });
+    this.ws.on("error", () => {
+    });
+  }
+  async close() {
+    this._connected = false;
+    if (this.ws) {
+      this.ws.removeAllListeners();
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+  // ── Authentication ──────────────────────────────────────────────
+  async authenticate() {
+    if (!this.ws) throw new ConnectionError("Not connected");
+    let msg;
+    if (this.apiKey) {
+      msg = { type: "authenticate", api_key: this.apiKey };
+    } else if (this.username && this.password) {
+      msg = { type: "login", username: this.username, password: this.password };
+    } else {
+      throw new AuthenticationError(
+        "No credentials provided (need username/password or apiKey)"
+      );
+    }
+    this.ws.send(serializeMessage(msg));
+    const response = await this.receiveOne();
+    if (response.type === "auth_error") {
+      throw new AuthenticationError(response.message);
+    }
+    if (response.type === "authenticated") {
+      this._sessionId = response.session_id;
+      this._serverVersion = response.version;
+      this._role = response.role;
+      this._currentKg = response.knowledge_graph;
+      return;
+    }
+    throw new AuthenticationError(`Unexpected auth response: ${JSON.stringify(response)}`);
+  }
+  // ── Command execution ───────────────────────────────────────────
+  /**
+   * Send a program/command and wait for the result.
+   * Transparently assembles streamed results (result_start -> chunks -> result_end).
+   */
+  async execute(program) {
+    if (!this._connected || !this.ws) {
+      throw new ConnectionError("Not connected");
+    }
+    const msg = { type: "execute", program };
+    this.ws.send(serializeMessage(msg));
+    return this.readResult();
+  }
+  async readResult() {
+    while (true) {
+      const response = await this.receiveMessage();
+      if (this.isNotification(response)) {
+        this.dispatchNotification(response);
+        continue;
+      }
+      if (response.type === "pong") {
+        continue;
+      }
+      if (response.type === "result") {
+        if (response.switched_kg) {
+          this._currentKg = response.switched_kg;
+        }
+        return response;
+      }
+      if (response.type === "error") {
+        return {
+          type: "result",
+          columns: ["error"],
+          rows: [[response.message]],
+          row_count: 1,
+          total_count: 1,
+          truncated: false,
+          execution_time_ms: 0
+        };
+      }
+      if (response.type === "result_start") {
+        return this.assembleStream(response);
+      }
+      throw new InternalError(
+        `Unexpected message during result read: ${JSON.stringify(response)}`
+      );
+    }
+  }
+  async assembleStream(start) {
+    const allRows = [];
+    const allProvenance = [];
+    while (true) {
+      const response = await this.receiveMessage();
+      if (this.isNotification(response)) {
+        this.dispatchNotification(response);
+        continue;
+      }
+      if (response.type === "result_chunk") {
+        allRows.push(...response.rows);
+        if (response.row_provenance) {
+          allProvenance.push(...response.row_provenance);
+        }
+        continue;
+      }
+      if (response.type === "result_end") {
+        if (start.switched_kg) {
+          this._currentKg = start.switched_kg;
+        }
+        return {
+          type: "result",
+          columns: start.columns,
+          rows: allRows,
+          row_count: response.row_count,
+          total_count: start.total_count,
+          truncated: start.truncated,
+          execution_time_ms: start.execution_time_ms,
+          row_provenance: allProvenance.length > 0 ? allProvenance : void 0,
+          metadata: start.metadata,
+          switched_kg: start.switched_kg
+        };
+      }
+      throw new InternalError(
+        `Unexpected message during streaming: ${JSON.stringify(response)}`
+      );
+    }
+  }
+  // ── Notification handling ───────────────────────────────────────
+  isNotification(msg) {
+    return msg.type === "persistent_update" || msg.type === "rule_change" || msg.type === "kg_change" || msg.type === "schema_change";
+  }
+  dispatchNotification(notif) {
+    const event = {
+      type: notif.type,
+      seq: notif.seq,
+      timestampMs: notif.timestamp_ms,
+      sessionId: notif.session_id,
+      knowledgeGraph: notif.knowledge_graph,
+      relation: notif.relation,
+      operation: notif.operation,
+      count: notif.count,
+      ruleName: notif.rule_name,
+      entity: notif.entity
+    };
+    this._dispatcher.dispatch(event);
+  }
+  // ── Reconnection ────────────────────────────────────────────────
+  async reconnect() {
+    let delay = this.reconnectDelay;
+    for (let attempt = 0; attempt < this.maxReconnectAttempts; attempt++) {
+      await sleep(delay * 1e3);
+      try {
+        this._lastSeq = this._dispatcher.lastSeq;
+        await this.connect();
+        return;
+      } catch {
+        delay = Math.min(delay * 2, 60);
+      }
+    }
+    throw new ConnectionError(
+      `Failed to reconnect after ${this.maxReconnectAttempts} attempts`
+    );
+  }
+  // ── Keep-alive ──────────────────────────────────────────────────
+  async ping() {
+    if (!this.ws) throw new ConnectionError("Not connected");
+    this.ws.send(serializeMessage({ type: "ping" }));
+  }
+  // ── WebSocket helpers ───────────────────────────────────────────
+  createWebSocket(url) {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url);
+      ws.once("open", () => resolve(ws));
+      ws.once("error", (err) => reject(err));
+    });
+  }
+  /** Receive exactly one message (used during auth before handler is set up). */
+  receiveOne() {
+    return new Promise((resolve, reject) => {
+      if (!this.ws) return reject(new ConnectionError("Not connected"));
+      const handler = (data) => {
+        this.ws?.removeListener("message", handler);
+        try {
+          resolve(deserializeMessage(String(data)));
+        } catch (e) {
+          reject(e);
+        }
+      };
+      this.ws.on("message", handler);
+    });
+  }
+  /** Receive the next message via the pendingResolve mechanism. */
+  receiveMessage() {
+    return new Promise((resolve) => {
+      this.pendingResolve = resolve;
+    });
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/compiler.ts
+var VarEnv = class {
+  constructor() {
+    this.map = /* @__PURE__ */ new Map();
+    this.counter = 0;
+    this.parent = /* @__PURE__ */ new Map();
+  }
+  find(key) {
+    let current = key;
+    while (true) {
+      const p = this.parent.get(current) ?? current;
+      if (p === current) return current;
+      const gp = this.parent.get(p) ?? p;
+      this.parent.set(current, gp);
+      current = gp;
+    }
+  }
+  union(a, b) {
+    const ra = this.find(a);
+    const rb = this.find(b);
+    if (ra !== rb) {
+      this.parent.set(rb, ra);
+    }
+  }
+  getVar(col) {
+    const key = `${col.refAlias ?? col.relation}.${col.name}`;
+    const root = this.find(key);
+    const existing = this.map.get(root);
+    if (existing !== void 0) return existing;
+    let varName = columnToVariable(col.name);
+    const usedVars = new Set(this.map.values());
+    if (usedVars.has(varName)) {
+      this.counter++;
+      varName = `${varName}_${this.counter}`;
+    }
+    this.map.set(root, varName);
+    return varName;
+  }
+  unify(colA, colB) {
+    const keyA = `${colA.refAlias ?? colA.relation}.${colA.name}`;
+    const keyB = `${colB.refAlias ?? colB.relation}.${colB.name}`;
+    this.union(keyA, keyB);
+    const root = this.find(keyA);
+    const existing = this.map.get(root);
+    if (existing !== void 0) return existing;
+    let varName = columnToVariable(colA.name);
+    const usedVars = new Set(this.map.values());
+    if (usedVars.has(varName)) {
+      this.counter++;
+      varName = `${varName}_${this.counter}`;
+    }
+    this.map.set(root, varName);
+    return varName;
+  }
+  lookup(col) {
+    const key = `${col.refAlias ?? col.relation}.${col.name}`;
+    const root = this.find(key);
+    return this.map.get(root);
+  }
+  /** Direct-set a variable for conditional delete setup. */
+  set(key, varName) {
+    this.map.set(key, varName);
+  }
+};
+function compileExpr(expr, env) {
+  if (isColumn(expr)) {
+    return env.getVar(expr);
+  }
+  if (isLiteral(expr)) {
+    return compileValue(expr.value);
+  }
+  if (isArithmetic(expr)) {
+    const left = compileExpr(expr.left, env);
+    const right = compileExpr(expr.right, env);
+    return `${left} ${expr.op} ${right}`;
+  }
+  if (isFuncCall(expr)) {
+    const args = expr.args.map((a) => compileExpr(a, env)).join(", ");
+    return `${expr.name}(${args})`;
+  }
+  if (isOrderedColumn(expr)) {
+    const varStr = compileExpr(expr.column, env);
+    const suffix = expr.descending ? ":desc" : ":asc";
+    return `${varStr}${suffix}`;
+  }
+  if (isAggExpr(expr)) {
+    return compileAggExpr(expr, env);
+  }
+  throw new TypeError(`Cannot compile expression: ${JSON.stringify(expr)}`);
+}
+function compileAggExpr(agg, env) {
+  const parts = [];
+  for (const p of agg.params) {
+    parts.push(compileValue(p));
+  }
+  for (const pt of agg.passthrough) {
+    parts.push(compileExpr(pt, env));
+  }
+  if (agg.orderColumn !== void 0) {
+    const orderVar = compileExpr(agg.orderColumn, env);
+    const suffix = agg.desc ? ":desc" : ":asc";
+    parts.push(`${orderVar}${suffix}`);
+  } else if (agg.column !== void 0) {
+    parts.push(compileExpr(agg.column, env));
+  }
+  const inner = parts.join(", ");
+  return `${agg.func}<${inner}>`;
+}
+function compileBoolExpr(expr, env) {
+  if (isComparison(expr)) {
+    return [compileComparison(expr, env)];
+  }
+  if (isAnd(expr)) {
+    return [...compileBoolExpr(expr.left, env), ...compileBoolExpr(expr.right, env)];
+  }
+  if (isOr(expr)) {
+    throw new Error(
+      "OR conditions require query splitting. Use compileOrBranches() instead."
+    );
+  }
+  if (isNot(expr)) {
+    const innerParts = compileBoolExpr(expr.operand, env);
+    return [`!(${innerParts.join(", ")})`];
+  }
+  if (isInExpr(expr)) {
+    return [compileIn(expr.column, expr.targetColumn, false, env)];
+  }
+  if (isNegatedIn(expr)) {
+    return [compileIn(expr.column, expr.targetColumn, true, env)];
+  }
+  if (isMatchExpr(expr)) {
+    return [compileMatch(expr, env)];
+  }
+  throw new TypeError(`Cannot compile boolean expression: ${JSON.stringify(expr)}`);
+}
+function compileComparison(comp, env) {
+  if (comp.op === "=" && isColumn(comp.left) && isColumn(comp.right)) {
+    env.unify(comp.left, comp.right);
+    return "";
+  }
+  const left = compileExpr(comp.left, env);
+  const right = compileExpr(comp.right, env);
+  return `${left} ${comp.op} ${right}`;
+}
+function compileIn(col, target, negated, env) {
+  if (isColumn(col) && isColumn(target)) {
+    env.unify(col, target);
+    const tgtVar = env.getVar(target);
+    const prefix2 = negated ? "!" : "";
+    return `${prefix2}${target.relation}(..., ${tgtVar}, ...)`;
+  }
+  const srcVar = compileExpr(col, env);
+  const prefix = negated ? "!" : "";
+  return `${prefix}(..., ${srcVar}, ...)`;
+}
+function compileMatch(match, env) {
+  const parts = [];
+  for (const [, sourceExpr] of Object.entries(match.bindings)) {
+    parts.push(compileExpr(sourceExpr, env));
+  }
+  const prefix = match.negated ? "!" : "";
+  return `${prefix}${match.relation}(${parts.join(", ")})`;
+}
+function compileOrBranches(expr, env) {
+  if (isOr(expr)) {
+    return [
+      ...compileOrBranches(expr.left, env),
+      ...compileOrBranches(expr.right, env)
+    ];
+  }
+  return [compileBoolExpr(expr, env)];
+}
+function compileSchema(rel) {
+  const name = rel.relationName;
+  const cols = rel.columns;
+  const colTypes = rel.columnTypes;
+  const parts = cols.map((c) => {
+    const type = colTypes[c].replace(/\[(\d+)\]/, "($1)");
+    return `${c}: ${type}`;
+  });
+  return `+${name}(${parts.join(", ")})`;
+}
+function compileInsert(rel, fact, persistent = true) {
+  const name = rel.relationName;
+  const values = rel.columns.map((c) => compileValue(fact[c]));
+  const prefix = persistent ? "+" : "";
+  return `${prefix}${name}(${values.join(", ")})`;
+}
+function compileBulkInsert(rel, facts, persistent = true) {
+  const name = rel.relationName;
+  const tuples = facts.map((fact) => {
+    const values = rel.columns.map((c) => compileValue(fact[c]));
+    return `(${values.join(", ")})`;
+  });
+  const prefix = persistent ? "+" : "";
+  return `${prefix}${name}[${tuples.join(", ")}]`;
+}
+function compileDelete(rel, fact) {
+  const name = rel.relationName;
+  const values = rel.columns.map((c) => compileValue(fact[c]));
+  return `-${name}(${values.join(", ")})`;
+}
+function compileConditionalDelete(rel, condition) {
+  const name = rel.relationName;
+  const cols = rel.columns;
+  const vars = cols.map((_, i) => `X${i}`);
+  const head = `-${name}(${vars.join(", ")})`;
+  const env = new VarEnv();
+  for (let i = 0; i < cols.length; i++) {
+    env.set(`${name}.${cols[i]}`, vars[i]);
+  }
+  const bodyRel = `${name}(${vars.join(", ")})`;
+  const condParts = compileBoolExpr(condition, env).filter((p) => p !== "");
+  const allBody = [bodyRel, ...condParts];
+  return `${head} <- ${allBody.join(", ")}`;
+}
+function hasOr(expr) {
+  if (isOr(expr)) return true;
+  if (isAnd(expr)) return hasOr(expr.left) || hasOr(expr.right);
+  if (isNot(expr)) return hasOr(expr.operand);
+  return false;
+}
+function processJoinCondition(condition, env) {
+  if (isComparison(condition) && condition.op === "=") {
+    if (isColumn(condition.left) && isColumn(condition.right)) {
+      env.unify(condition.left, condition.right);
+      return;
+    }
+  }
+  if (isAnd(condition)) {
+    processJoinCondition(condition.left, env);
+    processJoinCondition(condition.right, env);
+  }
+}
+function compileQuery(opts) {
+  const env = new VarEnv();
+  const allRelations = [];
+  if (opts.join) {
+    for (const r of opts.join) {
+      if (r instanceof RelationDef) {
+        allRelations.push({ name: r.relationName, def: r, alias: void 0 });
+      } else {
+        allRelations.push({
+          name: r.relationName,
+          def: {
+            relationName: r.relationName,
+            columns: r.schema.columns.map((c) => c.name),
+            columnTypes: {}
+          },
+          alias: r.alias
+        });
+      }
+    }
+  }
+  if (opts.on) {
+    processJoinCondition(opts.on, env);
+  }
+  let whereParts = [];
+  let orBranches;
+  if (opts.where) {
+    if (hasOr(opts.where)) {
+      orBranches = compileOrBranches(opts.where, env);
+    } else {
+      whereParts = compileBoolExpr(opts.where, env).filter((p) => p !== "");
+    }
+  }
+  const hasAgg = opts.select.some((s) => isAggExpr(s));
+  const computed = opts.computed ?? {};
+  const hasComputedAgg = Object.values(computed).some((v) => isAggExpr(v));
+  if (hasAgg || hasComputedAgg) {
+    return compileAggQuery(
+      opts.select,
+      env,
+      allRelations,
+      whereParts,
+      orBranches,
+      opts.orderBy,
+      opts.limit,
+      opts.offset,
+      computed
+    );
+  }
+  const headParts = [];
+  const bodyAtoms = [];
+  const fullRelations = [];
+  for (const s of opts.select) {
+    if (s instanceof RelationDef) {
+      fullRelations.push({ name: s.relationName, def: s, alias: void 0 });
+    }
+  }
+  if (fullRelations.length > 0) {
+    for (const { name, def, alias } of fullRelations) {
+      for (const col of def.columns) {
+        const astCol = column(name, col, alias);
+        headParts.push(env.getVar(astCol));
+      }
+      if (!allRelations.some((r) => r.name === name && r.alias === alias)) {
+        allRelations.push({ name, def, alias });
+      }
+    }
+  }
+  for (const s of opts.select) {
+    if (!(s instanceof RelationDef) && isColumn(s)) {
+      headParts.push(env.getVar(s));
+    } else if (!(s instanceof RelationDef) && !isColumn(s) && "_tag" in s) {
+      headParts.push(compileExpr(s, env));
+    }
+  }
+  for (const [, expr] of Object.entries(computed)) {
+    headParts.push(compileExpr(expr, env));
+  }
+  if (opts.orderBy !== void 0) {
+    if (isOrderedColumn(opts.orderBy)) {
+      const orderVar = compileExpr(opts.orderBy.column, env);
+      const suffix = opts.orderBy.descending ? ":desc" : ":asc";
+      for (let i = 0; i < headParts.length; i++) {
+        if (headParts[i] === orderVar) {
+          headParts[i] = `${orderVar}${suffix}`;
+          break;
+        }
+      }
+    } else if (isColumn(opts.orderBy)) {
+      const orderVar = env.getVar(opts.orderBy);
+      for (let i = 0; i < headParts.length; i++) {
+        if (headParts[i] === orderVar) {
+          headParts[i] = `${orderVar}:asc`;
+          break;
+        }
+      }
+    }
+  }
+  for (const { name, def, alias } of allRelations) {
+    const cols = def.columns;
+    const atomParts = cols.map((col) => {
+      const astCol = column(name, col, alias);
+      return env.lookup(astCol) ?? "_";
+    });
+    bodyAtoms.push(`${name}(${atomParts.join(", ")})`);
+  }
+  const allBody = [...bodyAtoms, ...whereParts];
+  if (opts.limit !== void 0) {
+    if (opts.offset !== void 0) {
+      allBody.push(`limit(${opts.limit}, ${opts.offset})`);
+    } else {
+      allBody.push(`limit(${opts.limit})`);
+    }
+  }
+  const headStr = headParts.join(", ");
+  if (orBranches !== void 0) {
+    return orBranches.map((branchParts) => {
+      const filtered = branchParts.filter((p) => p !== "");
+      const branchBody = [...bodyAtoms, ...filtered];
+      if (opts.limit !== void 0) {
+        if (opts.offset !== void 0) {
+          branchBody.push(`limit(${opts.limit}, ${opts.offset})`);
+        } else {
+          branchBody.push(`limit(${opts.limit})`);
+        }
+      }
+      return `?${headStr} <- ${branchBody.join(", ")}`;
+    });
+  }
+  if (allBody.length > 0) {
+    return `?${headStr} <- ${allBody.join(", ")}`;
+  }
+  return `?${headStr}`;
+}
+function compileAggQuery(select, env, allRelations, whereParts, orBranches, orderBy, limit, offset, computed) {
+  const headParts = [];
+  const aggParts = [];
+  for (const s of select) {
+    if (s instanceof RelationDef) {
+      for (const col of s.columns) {
+        const astCol = column(s.relationName, col);
+        headParts.push(env.getVar(astCol));
+      }
+    } else if (isAggExpr(s)) {
+      aggParts.push(compileExpr(s, env));
+    } else if (isColumn(s)) {
+      headParts.push(env.getVar(s));
+    }
+  }
+  for (const [, expr] of Object.entries(computed)) {
+    if (isAggExpr(expr)) {
+      aggParts.push(compileExpr(expr, env));
+    } else {
+      headParts.push(compileExpr(expr, env));
+    }
+  }
+  const bodyAtoms = [];
+  for (const { name, def, alias } of allRelations) {
+    const cols = def.columns;
+    const atomParts = cols.map((col) => {
+      const astCol = column(name, col, alias);
+      return env.lookup(astCol) ?? "_";
+    });
+    bodyAtoms.push(`${name}(${atomParts.join(", ")})`);
+  }
+  const allBody = [...bodyAtoms, ...whereParts];
+  if (limit !== void 0) {
+    if (offset !== void 0) {
+      allBody.push(`limit(${limit}, ${offset})`);
+    } else {
+      allBody.push(`limit(${limit})`);
+    }
+  }
+  const allHead = [...headParts, ...aggParts];
+  const headStr = allHead.join(", ");
+  if (allBody.length > 0) {
+    return `?${headStr} <- ${allBody.join(", ")}`;
+  }
+  return `?${headStr}`;
+}
+function compileRule(headName, headColumns, clause, persistent = true) {
+  const env = new VarEnv();
+  if (clause.condition) {
+    processJoinCondition(clause.condition, env);
+  }
+  const headParts = headColumns.map((col) => {
+    const expr = clause.selectMap[col];
+    if (expr !== void 0) {
+      return compileExpr(expr, env);
+    }
+    return columnToVariable(col);
+  });
+  const bodyAtoms = [];
+  for (const { name, def, alias } of clause.relations) {
+    const cols = def.columns;
+    const atomParts = cols.map((col) => {
+      const astCol = column(name, col, alias);
+      return env.lookup(astCol) ?? "_";
+    });
+    bodyAtoms.push(`${name}(${atomParts.join(", ")})`);
+  }
+  let condParts = [];
+  if (clause.condition) {
+    condParts = compileBoolExpr(clause.condition, env).filter((p) => p !== "");
+  }
+  const allBody = [...bodyAtoms, ...condParts];
+  const prefix = persistent ? "+" : "";
+  const headStr = `${prefix}${headName}(${headParts.join(", ")})`;
+  return `${headStr} <- ${allBody.join(", ")}`;
+}
+
+// src/session.ts
+var Session = class {
+  constructor(connection) {
+    this.conn = connection;
+  }
+  /** Insert ephemeral session facts (no + prefix). */
+  async insert(rel, facts) {
+    const factList = Array.isArray(facts) ? facts : [facts];
+    if (factList.length === 0) return;
+    let iql;
+    if (factList.length === 1) {
+      iql = compileInsert(rel, factList[0], false);
+    } else {
+      iql = compileBulkInsert(rel, factList, false);
+    }
+    await this.conn.execute(iql);
+  }
+  /** Define session-scoped rules (no + prefix). */
+  async defineRules(headName, headColumns, clauses) {
+    for (const clause of clauses) {
+      const iql = compileRule(headName, headColumns, clause, false);
+      await this.conn.execute(iql);
+    }
+  }
+  /** List session rules. */
+  async listRules() {
+    const result = await this.conn.execute(".session list");
+    return result.rows.length > 0 ? result.rows.map((row) => String(row[0])) : [];
+  }
+  /** Drop a session rule by name, or a specific clause by index. */
+  async dropRule(name, index) {
+    if (index !== void 0) {
+      await this.conn.execute(`.session remove ${name} ${index}`);
+    } else {
+      await this.conn.execute(`.session drop ${name}`);
+    }
+  }
+  /** Clear all session facts and rules. */
+  async clear() {
+    await this.conn.execute(".session clear");
+  }
+};
+
+// src/knowledge-graph.ts
+var KnowledgeGraph = class {
+  constructor(name, connection) {
+    this.kgActive = false;
+    this._name = name;
+    this.conn = connection;
+    this._session = new Session(connection);
+  }
+  get name() {
+    return this._name;
+  }
+  get session() {
+    return this._session;
+  }
+  /** Ensure the connection is using this knowledge graph. */
+  async ensureKg() {
+    if (this.conn.currentKg === this._name) return;
+    await this.conn.execute(`.kg create ${this._name}`);
+    await this.conn.execute(`.kg use ${this._name}`);
+    this.conn.setCurrentKg(this._name);
+  }
+  // ── Schema ──────────────────────────────────────────────────────
+  /** Deploy schema definitions. Idempotent. */
+  async define(...relations) {
+    await this.ensureKg();
+    for (const rel of relations) {
+      const iql = compileSchema(rel);
+      await this.conn.execute(iql);
+    }
+  }
+  /** List all relations in this KG. */
+  async relations() {
+    await this.ensureKg();
+    const result = await this.conn.execute(".rel");
+    return result.rows.map((row) => ({
+      name: String(row[0]),
+      rowCount: row.length > 1 ? Number(row[1]) : 0
+    }));
+  }
+  /** Describe a relation's schema. */
+  async describe(relation2) {
+    await this.ensureKg();
+    const name = typeof relation2 === "string" ? relation2 : relation2.relationName;
+    const result = await this.conn.execute(`.rel ${name}`);
+    const columns = result.rows.map((row) => ({
+      name: String(row[0]),
+      type: String(row[1])
+    }));
+    return { name, columns, rowCount: 0, sample: [] };
+  }
+  /** Drop a relation and all its data. */
+  async dropRelation(relation2) {
+    await this.ensureKg();
+    const name = typeof relation2 === "string" ? relation2 : relation2.relationName;
+    await this.conn.execute(`.rel drop ${name}`);
+  }
+  // ── Insert ──────────────────────────────────────────────────────
+  /** Insert facts into the knowledge graph. */
+  async insert(rel, facts) {
+    await this.ensureKg();
+    const factList = Array.isArray(facts) ? facts : [facts];
+    if (factList.length === 0) return { count: 0 };
+    let iql;
+    if (factList.length === 1) {
+      iql = compileInsert(rel, factList[0]);
+    } else {
+      iql = compileBulkInsert(rel, factList);
+    }
+    const result = await this.conn.execute(iql);
+    return { count: result.rows.length };
+  }
+  // ── Delete ──────────────────────────────────────────────────────
+  /**
+   * Delete facts from the knowledge graph.
+   *
+   * @param rel - The relation definition
+   * @param factsOrCondition - Either specific facts to delete, or a BoolExpr condition
+   */
+  async delete(rel, factsOrCondition) {
+    await this.ensureKg();
+    if (typeof factsOrCondition === "object" && factsOrCondition !== null && "_tag" in factsOrCondition) {
+      const iql = compileConditionalDelete(rel, factsOrCondition);
+      const result = await this.conn.execute(iql);
+      return { count: result.rows.length };
+    }
+    const facts = Array.isArray(factsOrCondition) ? factsOrCondition : [factsOrCondition];
+    for (const fact of facts) {
+      const iql = compileDelete(rel, fact);
+      await this.conn.execute(iql);
+    }
+    return { count: facts.length };
+  }
+  // ── Query ───────────────────────────────────────────────────────
+  /**
+   * Query the knowledge graph.
+   *
+   * @example
+   * // Simple query
+   * const result = await kg.query({ select: [Employee] });
+   *
+   * // Filter
+   * const result = await kg.query({
+   *   select: [Employee.col("name"), Employee.col("salary")],
+   *   join: [Employee],
+   *   where: Employee.col("department").eq("eng"),
+   * });
+   *
+   * // Join
+   * const result = await kg.query({
+   *   select: [Employee.col("name"), Department.col("budget")],
+   *   join: [Employee, Department],
+   *   on: Employee.col("department").eq(Department.col("name")),
+   * });
+   */
+  async query(opts) {
+    await this.ensureKg();
+    const iql = compileQuery(opts);
+    if (Array.isArray(iql)) {
+      const allRows = [];
+      let columns = [];
+      for (const q of iql) {
+        const result2 = await this.conn.execute(q);
+        if (columns.length === 0) {
+          columns = result2.columns;
+        }
+        allRows.push(...result2.rows);
+      }
+      return new ResultSet({ columns, rows: allRows });
+    }
+    const result = await this.conn.execute(iql);
+    const rs = new ResultSet({
+      columns: result.columns,
+      rows: result.rows,
+      rowCount: result.row_count,
+      totalCount: result.total_count,
+      truncated: result.truncated,
+      executionTimeMs: result.execution_time_ms,
+      rowProvenance: result.row_provenance
+    });
+    if (result.metadata) {
+      rs.hasEphemeral = result.metadata.has_ephemeral ?? false;
+      rs.ephemeralSources = result.metadata.ephemeral_sources ?? [];
+      rs.warnings = result.metadata.warnings ?? [];
+    }
+    return rs;
+  }
+  /**
+   * Stream query results in batches.
+   *
+   * Returns an async generator yielding arrays of rows.
+   */
+  async *queryStream(opts) {
+    const batchSize = opts.batchSize ?? 1e3;
+    const result = await this.query(opts);
+    for (let i = 0; i < result.rows.length; i += batchSize) {
+      const batch = result.rows.slice(i, i + batchSize);
+      yield batch.map((row) => {
+        const obj = {};
+        for (let j = 0; j < result.columns.length && j < row.length; j++) {
+          obj[result.columns[j]] = row[j];
+        }
+        return obj;
+      });
+    }
+  }
+  // ── Vector search ───────────────────────────────────────────────
+  /**
+   * Perform a vector similarity search.
+   */
+  async vectorSearch(opts) {
+    await this.ensureKg();
+    const rel = opts.relation;
+    const relName = rel.relationName;
+    const cols = rel.columns;
+    let vecColumn = opts.column;
+    if (!vecColumn) {
+      for (const [name, type] of Object.entries(rel.columnTypes)) {
+        if (type === "vector" || type.startsWith("vector[")) {
+          vecColumn = name;
+          break;
+        }
+      }
+      if (!vecColumn) {
+        throw new Error(`No vector column found in ${relName}`);
+      }
+    }
+    const vecStr = `[${opts.queryVec.join(", ")}]`;
+    const distFn = {
+      cosine: "cosine",
+      euclidean: "euclidean",
+      manhattan: "manhattan",
+      dot_product: "dot"
+    };
+    const fnName = distFn[opts.metric ?? "cosine"] ?? "cosine";
+    const colVars = cols.map((_, i) => `X${i}`).join(", ");
+    const vecVar = `X${cols.indexOf(vecColumn)}`;
+    const distAssign = `Dist = ${fnName}(${vecVar}, ${vecStr})`;
+    let query;
+    if (opts.k !== void 0) {
+      query = `?top_k<${opts.k}, ${colVars}, Dist:asc> <- ${relName}(${colVars}), ${distAssign}`;
+    } else if (opts.radius !== void 0) {
+      query = `?within_radius<${opts.radius}, ${colVars}, Dist:asc> <- ${relName}(${colVars}), ${distAssign}`;
+    } else {
+      throw new Error("Must specify either k or radius");
+    }
+    const result = await this.conn.execute(query);
+    return new ResultSet({
+      columns: result.columns,
+      rows: result.rows,
+      rowCount: result.row_count,
+      totalCount: result.total_count,
+      truncated: result.truncated,
+      executionTimeMs: result.execution_time_ms
+    });
+  }
+  // ── Rules ───────────────────────────────────────────────────────
+  /** Deploy persistent rule definitions. */
+  async defineRules(headName, headColumns, clauses) {
+    await this.ensureKg();
+    for (const clause of clauses) {
+      const iql = compileRule(headName, headColumns, clause, true);
+      await this.conn.execute(iql);
+    }
+  }
+  /** List all rules in this KG. */
+  async listRules() {
+    await this.ensureKg();
+    const result = await this.conn.execute(".rule list");
+    return result.rows.map((row) => ({
+      name: String(row[0]),
+      clauseCount: row.length > 1 ? Number(row[1]) : 1
+    }));
+  }
+  /** Get the IQL definition of a rule. */
+  async ruleDefinition(name) {
+    await this.ensureKg();
+    const result = await this.conn.execute(`.rule show ${name}`);
+    return result.rows.map((row) => String(row[0]));
+  }
+  /** Drop all clauses of a rule. */
+  async dropRule(name) {
+    await this.ensureKg();
+    await this.conn.execute(`.rule drop ${name}`);
+  }
+  /** Remove a specific clause from a rule (1-based index). */
+  async dropRuleClause(name, index) {
+    await this.ensureKg();
+    await this.conn.execute(`.rule remove ${name} ${index}`);
+  }
+  /** Replace a specific rule clause (remove + re-add). */
+  async editRuleClause(name, index, headColumns, clause) {
+    await this.dropRuleClause(name, index);
+    const iql = compileRule(name, headColumns, clause, true);
+    await this.conn.execute(iql);
+  }
+  /** Clear a rule's materialized data. */
+  async clearRule(name) {
+    await this.ensureKg();
+    await this.conn.execute(`.rule clear ${name}`);
+  }
+  /** Drop all rules whose names start with prefix. */
+  async dropRulesByPrefix(prefix) {
+    await this.ensureKg();
+    await this.conn.execute(`.rule drop prefix ${prefix}`);
+  }
+  // ── Indexes ─────────────────────────────────────────────────────
+  /** Create an HNSW vector index. */
+  async createIndex(index) {
+    await this.ensureKg();
+    await this.conn.execute(index.toIQL());
+  }
+  /** List all indexes. */
+  async listIndexes() {
+    await this.ensureKg();
+    const result = await this.conn.execute(".index list");
+    return result.rows.map((row) => ({
+      name: String(row[0]),
+      relation: row.length > 1 ? String(row[1]) : "",
+      column: row.length > 2 ? String(row[2]) : "",
+      metric: row.length > 3 ? String(row[3]) : "",
+      rowCount: row.length > 4 ? Number(row[4]) : 0
+    }));
+  }
+  /** Get statistics for an index. */
+  async indexStats(name) {
+    await this.ensureKg();
+    const result = await this.conn.execute(`.index stats ${name}`);
+    const row = result.rows[0] ?? [name, 0, 0, 0];
+    return {
+      name: String(row[0]),
+      rowCount: row.length > 1 ? Number(row[1]) : 0,
+      layers: row.length > 2 ? Number(row[2]) : 0,
+      memoryBytes: row.length > 3 ? Number(row[3]) : 0
+    };
+  }
+  /** Drop an index. */
+  async dropIndex(name) {
+    await this.ensureKg();
+    await this.conn.execute(`.index drop ${name}`);
+  }
+  /** Rebuild an index. */
+  async rebuildIndex(name) {
+    await this.ensureKg();
+    await this.conn.execute(`.index rebuild ${name}`);
+  }
+  // ── ACL ─────────────────────────────────────────────────────────
+  /** Grant per-KG access. */
+  async grantAccess(username, role) {
+    await this.conn.execute(`.kg acl grant ${this._name} ${username} ${role}`);
+  }
+  /** Revoke per-KG access. */
+  async revokeAccess(username) {
+    await this.conn.execute(`.kg acl revoke ${this._name} ${username}`);
+  }
+  /** List ACL entries. */
+  async listAcl() {
+    const result = await this.conn.execute(`.kg acl list ${this._name}`);
+    return result.rows.filter((row) => row.length >= 2).map((row) => ({
+      username: String(row[0]),
+      role: String(row[1])
+    }));
+  }
+  // ── Meta ────────────────────────────────────────────────────────
+  /** Show the query plan without executing. */
+  async explain(opts) {
+    await this.ensureKg();
+    let iql = compileQuery(opts);
+    if (Array.isArray(iql)) {
+      iql = iql[0];
+    }
+    const result = await this.conn.execute(`.explain ${iql}`);
+    const planText = result.rows.map((row) => String(row[0])).join("\n");
+    return { iql, plan: planText };
+  }
+  /** Trigger storage compaction. */
+  async compact() {
+    await this.ensureKg();
+    await this.conn.execute(".compact");
+  }
+  /** Get server status. */
+  async status() {
+    await this.ensureKg();
+    const result = await this.conn.execute(".status");
+    const row = result.rows[0] ?? ["unknown", "unknown"];
+    return {
+      version: row.length > 0 ? String(row[0]) : "unknown",
+      knowledgeGraph: row.length > 1 ? String(row[1]) : this._name
+    };
+  }
+  /** Load data from a file on the server. */
+  async load(path, mode) {
+    await this.ensureKg();
+    let cmd = `.load ${path}`;
+    if (mode) cmd += ` ${mode}`;
+    await this.conn.execute(cmd);
+  }
+  /** Clear all relations matching a prefix. */
+  async clearPrefix(prefix) {
+    await this.ensureKg();
+    const result = await this.conn.execute(`.clear prefix ${prefix}`);
+    const details = result.rows.filter((row) => row.length > 1).map((row) => [String(row[0]), Number(row[1])]);
+    return {
+      relationsCleared: result.rows.length,
+      factsCleared: details.reduce((sum2, [, count2]) => sum2 + count2, 0),
+      details
+    };
+  }
+  /** Execute raw IQL. */
+  async execute(iql) {
+    await this.ensureKg();
+    const result = await this.conn.execute(iql);
+    return new ResultSet({
+      columns: result.columns,
+      rows: result.rows,
+      rowCount: result.row_count,
+      totalCount: result.total_count,
+      truncated: result.truncated,
+      executionTimeMs: result.execution_time_ms
+    });
+  }
+};
+
+// src/auth.ts
+function compileCreateUser(username, password, role = "viewer") {
+  return `.user create ${username} ${password} ${role}`;
+}
+function compileDropUser(username) {
+  return `.user drop ${username}`;
+}
+function compileSetPassword(username, newPassword) {
+  return `.user password ${username} ${newPassword}`;
+}
+function compileSetRole(username, role) {
+  return `.user role ${username} ${role}`;
+}
+function compileListUsers() {
+  return ".user list";
+}
+function compileCreateApiKey(label) {
+  return `.apikey create ${label}`;
+}
+function compileListApiKeys() {
+  return ".apikey list";
+}
+function compileRevokeApiKey(label) {
+  return `.apikey revoke ${label}`;
+}
+
+// src/client.ts
+var InputLayer = class {
+  constructor(opts) {
+    this.kgs = /* @__PURE__ */ new Map();
+    this.conn = new Connection({
+      url: opts.url,
+      username: opts.username,
+      password: opts.password,
+      apiKey: opts.apiKey,
+      autoReconnect: opts.autoReconnect,
+      reconnectDelay: opts.reconnectDelay,
+      maxReconnectAttempts: opts.maxReconnectAttempts,
+      initialKg: opts.initialKg,
+      lastSeq: opts.lastSeq
+    });
+  }
+  // ── Connection lifecycle ────────────────────────────────────────
+  /** Connect and authenticate. */
+  async connect() {
+    await this.conn.connect();
+  }
+  /** Close the connection. */
+  async close() {
+    await this.conn.close();
+  }
+  // ── Properties ──────────────────────────────────────────────────
+  get connected() {
+    return this.conn.connected;
+  }
+  get sessionId() {
+    return this.conn.sessionId;
+  }
+  get serverVersion() {
+    return this.conn.serverVersion;
+  }
+  get role() {
+    return this.conn.role;
+  }
+  get lastSeq() {
+    return this.conn.lastSeq;
+  }
+  // ── KG management ───────────────────────────────────────────────
+  /** Get a KnowledgeGraph handle. Switches the session's active KG. */
+  knowledgeGraph(name) {
+    let kg = this.kgs.get(name);
+    if (!kg) {
+      kg = new KnowledgeGraph(name, this.conn);
+      this.kgs.set(name, kg);
+    }
+    return kg;
+  }
+  /** List all knowledge graphs. */
+  async listKnowledgeGraphs() {
+    const result = await this.conn.execute(".kg list");
+    return result.rows.length > 0 ? result.rows.map((row) => String(row[0])) : [];
+  }
+  /** Drop a knowledge graph. */
+  async dropKnowledgeGraph(name) {
+    await this.conn.execute(`.kg drop ${name}`);
+    this.kgs.delete(name);
+  }
+  // ── User management ─────────────────────────────────────────────
+  async createUser(username, password, role = "viewer") {
+    await this.conn.execute(compileCreateUser(username, password, role));
+  }
+  async dropUser(username) {
+    await this.conn.execute(compileDropUser(username));
+  }
+  async setPassword(username, newPassword) {
+    await this.conn.execute(compileSetPassword(username, newPassword));
+  }
+  async setRole(username, role) {
+    await this.conn.execute(compileSetRole(username, role));
+  }
+  async listUsers() {
+    const result = await this.conn.execute(compileListUsers());
+    return result.rows.filter((row) => row.length >= 2).map((row) => ({
+      username: String(row[0]),
+      role: String(row[1])
+    }));
+  }
+  // ── API key management ──────────────────────────────────────────
+  /** Create an API key. Returns the key string. */
+  async createApiKey(label) {
+    const result = await this.conn.execute(compileCreateApiKey(label));
+    if (result.rows.length > 0 && result.rows[0].length > 0) {
+      return String(result.rows[0][0]);
+    }
+    return "";
+  }
+  async listApiKeys() {
+    const result = await this.conn.execute(compileListApiKeys());
+    return result.rows.map((row) => ({
+      label: String(row[0]),
+      createdAt: row.length > 1 ? String(row[1]) : ""
+    }));
+  }
+  async revokeApiKey(label) {
+    await this.conn.execute(compileRevokeApiKey(label));
+  }
+  // ── Notifications ───────────────────────────────────────────────
+  /**
+   * Register a notification callback.
+   *
+   * @param eventType - Filter by event type (e.g. "persistent_update")
+   * @param callback - Function to call when event arrives
+   * @param opts - Additional filters
+   */
+  on(eventType, callback, opts) {
+    this.conn.dispatcher.on(eventType, opts ?? {}, callback);
+  }
+  /** Remove a notification callback. */
+  off(callback) {
+    this.conn.dispatcher.off(callback);
+  }
+  /** Async iterator yielding notification events. */
+  async *notifications() {
+    yield* this.conn.dispatcher.events();
+  }
+};
+export {
+  AND,
+  AuthenticationError,
+  CannotDropError,
+  ColumnProxy,
+  Connection,
+  ConnectionError,
+  HnswIndex,
+  IndexNotFoundError,
+  InputLayer,
+  InputLayerError,
+  InternalError,
+  KnowledgeGraph,
+  KnowledgeGraphExistsError,
+  KnowledgeGraphNotFoundError,
+  NOT,
+  NotificationDispatcher,
+  OR,
+  PermissionError,
+  QueryTimeoutError,
+  RelationDef,
+  RelationNotFoundError,
+  RelationProxy,
+  RelationRef,
+  ResultSet,
+  RuleNotFoundError,
+  SchemaConflictError,
+  Session,
+  Timestamp,
+  ValidationError,
+  avg,
+  camelToSnake,
+  columnToVariable,
+  compileBoolExpr,
+  compileBulkInsert,
+  compileConditionalDelete,
+  compileDelete,
+  compileExpr,
+  compileInsert,
+  compileQuery,
+  compileRule,
+  compileSchema,
+  compileValue,
+  count,
+  countDistinct,
+  deserializeMessage,
+  from,
+  getColumnTypes,
+  getColumns,
+  max,
+  min,
+  relation,
+  resolveRelationName,
+  serializeMessage,
+  snakeToCamel,
+  sum,
+  topK,
+  topKThreshold,
+  withinRadius,
+  wrap
+};