@nicia-ai/typegraph 0.34.0 → 0.35.0

package/dist/chunk-KMI7LYAF.js

@@ -0,0 +1,1252 @@
+import { runInWriteTransaction, createNodeBatchValidationBackend, primeBatchValidationCaches } from './chunk-QNKSQTKQ.js';
+import { getNodeKinds, getEdgeKinds } from './chunk-QWEUYILR.js';
+import { applyNodeInsertSideEffectsBatch, applyNodeUpdate, checkUniquenessConstraints, applyNodeInsertSideEffects, validateEdgeEndpoints } from './chunk-CZQ3FO2Q.js';
+import { rowPropsToObject, isLiveNodeRow } from './chunk-JBTOYDMN.js';
+import { isCanonicalIsoDate, nowIso, validateOptionalCanonicalIsoDate } from './chunk-I7ZUZKFD.js';
+import { UniquenessError } from './chunk-MP2JQKSG.js';
+import { z } from 'zod';
+
+var FORMAT_VERSION = "1.0";
+var ValidityTimestampSchema = z.iso.datetime().refine((value) => isCanonicalIsoDate(value), {
+  message: "Expected canonical UTC ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ); convert with new Date(value).toISOString()."
+});
+var InterchangeNodeSchema = z.object({
+  kind: z.string().min(1),
+  id: z.string().min(1),
+  properties: z.record(z.string(), z.unknown()),
+  /**
+   * `undefined` (key absent): not requested (`includeTemporal: false`) —
+   * import defaults it to the import's own creation timestamp. `null`:
+   * requested and confirmed the row has no lower bound (e.g. a legacy row
+   * predating the "omitted validFrom defaults to creation time" fix) —
+   * import preserves that open-left validity instead of re-stamping it.
+   */
+  validFrom: ValidityTimestampSchema.nullable().optional(),
+  validTo: ValidityTimestampSchema.optional(),
+  meta: z.object({
+    version: z.number().int().positive().optional(),
+    createdAt: z.iso.datetime().optional(),
+    updatedAt: z.iso.datetime().optional()
+  }).optional()
+});
+var InterchangeEdgeSchema = z.object({
+  kind: z.string().min(1),
+  id: z.string().min(1),
+  from: z.object({
+    kind: z.string().min(1),
+    id: z.string().min(1)
+  }),
+  to: z.object({
+    kind: z.string().min(1),
+    id: z.string().min(1)
+  }),
+  properties: z.record(z.string(), z.unknown()).default({}),
+  /** See {@link InterchangeNodeSchema}'s `validFrom` for the null/undefined contract. */
+  validFrom: ValidityTimestampSchema.nullable().optional(),
+  validTo: ValidityTimestampSchema.optional(),
+  meta: z.object({
+    createdAt: z.iso.datetime().optional(),
+    updatedAt: z.iso.datetime().optional()
+  }).optional()
+});
+var ConflictStrategySchema = z.enum(["skip", "update", "error"]);
+var UnknownPropertyStrategySchema = z.enum([
+  "error",
+  "strip",
+  "allow"
+]);
+var ImportOptionsSchema = z.object({
+  /** How to handle existing nodes/edges with the same ID */
+  onConflict: ConflictStrategySchema,
+  /** How to handle properties not in the schema */
+  onUnknownProperty: UnknownPropertyStrategySchema.default("error"),
+  /** Whether to validate that edge endpoints exist */
+  validateReferences: z.boolean().default(true),
+  /**
+   * Number of items to process in each batch. Each batch pays fixed
+   * per-round-trip costs (existence probe, unique check, one multi-row
+   * insert), so undersized batches dominate import time on client/server
+   * engines: measured on PostgreSQL, 20k nodes + 5k edges import in
+   * 1,515ms at 100 vs 781ms at 1,000. Above ~1,000 the multi-row insert
+   * itself dominates and larger batches stop paying; SQLite is
+   * insensitive to the value (in-process, no round trips). The backend
+   * further splits inserts by its bind-parameter budget, so a large
+   * batch never overruns driver limits.
+   */
+  batchSize: z.number().int().positive().default(1e3),
+  /**
+   * Refresh planner statistics (ANALYZE) after an import that created or
+   * updated rows. Bulk loads otherwise run against stale statistics until
+   * the engine catches up on its own. Default: true.
+   */
+  refreshStatistics: z.boolean().optional(),
+  /**
+   * How a streamed import reacts when one chunk reports entity-level errors.
+   * `abort` is the safe default: earlier chunks are already committed, so
+   * callers must not mistake a partial stream for a successful retryable load.
+   * `continue` is reserved for explicit best-effort ingestion.
+   */
+  onStreamChunkError: z.enum(["abort", "continue"]).default("abort")
+});
+var GraphDataSourceSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("typegraph-export"),
+    graphId: z.string(),
+    schemaVersion: z.number().int().positive()
+  }),
+  z.object({
+    type: z.literal("external"),
+    description: z.string().optional()
+  })
+]);
+var GraphDataSchema = z.object({
+  formatVersion: z.literal(FORMAT_VERSION),
+  exportedAt: z.iso.datetime(),
+  source: GraphDataSourceSchema,
+  nodes: z.array(InterchangeNodeSchema),
+  edges: z.array(InterchangeEdgeSchema)
+});
+var GraphDataHeaderSchema = GraphDataSchema.omit({
+  nodes: true,
+  edges: true
+});
+var GraphInterchangeChunkSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("header"), header: GraphDataHeaderSchema }),
+  z.object({ type: z.literal("nodes"), nodes: z.array(InterchangeNodeSchema) }),
+  z.object({ type: z.literal("edges"), edges: z.array(InterchangeEdgeSchema) })
+]);
+var ImportErrorSchema = z.object({
+  entityType: z.enum(["node", "edge"]),
+  kind: z.string(),
+  id: z.string(),
+  error: z.string()
+});
+var ImportResultSchema = z.object({
+  success: z.boolean(),
+  nodes: z.object({
+    created: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative()
+  }),
+  edges: z.object({
+    created: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative()
+  }),
+  errors: z.array(ImportErrorSchema)
+});
+var ExportOptionsSchema = z.object({
+  /** Filter to specific node kinds (undefined = all) */
+  nodeKinds: z.array(z.string()).optional(),
+  /** Filter to specific edge kinds (undefined = all) */
+  edgeKinds: z.array(z.string()).optional(),
+  /** Include temporal fields (validFrom, validTo) */
+  includeTemporal: z.boolean().default(false),
+  /** Include metadata (version, timestamps) */
+  includeMeta: z.boolean().default(false),
+  /** Include soft-deleted records */
+  includeDeleted: z.boolean().default(false)
+});
+var ExportStreamOptionsSchema = ExportOptionsSchema.extend({
+  batchSize: z.number().int().positive().default(1e3)
+});
+
+// src/interchange/export.ts
+async function exportGraph(store, options) {
+  const nodes = [];
+  const edges = [];
+  let header;
+  for await (const chunk of exportGraphStream(store, options)) {
+    switch (chunk.type) {
+      case "header": {
+        header = chunk.header;
+        break;
+      }
+      case "nodes": {
+        nodes.push(...chunk.nodes);
+        break;
+      }
+      case "edges": {
+        edges.push(...chunk.edges);
+        break;
+      }
+    }
+  }
+  if (header === void 0) {
+    throw new Error("Graph export stream ended before emitting its header.");
+  }
+  return { ...header, nodes, edges };
+}
+async function* exportGraphStream(store, options) {
+  const resolved = ExportStreamOptionsSchema.parse(options ?? {});
+  const graphId = store.graphId;
+  const backend = store.backend;
+  const nodeKinds = resolved.nodeKinds ?? getNodeKinds(store.graph);
+  const edgeKinds = resolved.edgeKinds ?? getEdgeKinds(store.graph);
+  const schemaVersion = await backend.getActiveSchema(graphId);
+  yield {
+    type: "header",
+    header: {
+      formatVersion: FORMAT_VERSION,
+      exportedAt: nowIso(),
+      source: {
+        type: "typegraph-export",
+        graphId,
+        schemaVersion: schemaVersion?.version ?? 1
+      }
+    }
+  };
+  for (const kind of nodeKinds) {
+    yield* exportNodeChunks(backend, graphId, kind, resolved);
+  }
+  for (const kind of edgeKinds) {
+    yield* exportEdgeChunks(backend, graphId, kind, resolved);
+  }
+}
+async function* exportNodeChunks(backend, graphId, kind, options) {
+  let after;
+  for (; ; ) {
+    const rows = await backend.findNodesByKind({
+      graphId,
+      kind,
+      excludeDeleted: !options.includeDeleted,
+      orderBy: "id",
+      limit: options.batchSize,
+      ...after === void 0 ? {} : { after }
+    });
+    if (rows.length === 0) return;
+    const nodes = rows.map((row) => {
+      const node = {
+        kind: row.kind,
+        id: row.id,
+        properties: rowPropsToObject(row.props)
+      };
+      if (options.includeTemporal) {
+        const validFrom = (
+          // eslint-disable-next-line unicorn/no-null
+          row.valid_from ?? null
+        );
+        node.validFrom = validFrom;
+        if (row.valid_to) {
+          node.validTo = row.valid_to;
+        }
+      }
+      if (options.includeMeta) {
+        node.meta = {
+          version: row.version,
+          createdAt: row.created_at,
+          updatedAt: row.updated_at
+        };
+      }
+      return node;
+    });
+    yield { type: "nodes", nodes };
+    if (rows.length < options.batchSize) return;
+    after = rows.at(-1).id;
+  }
+}
+async function* exportEdgeChunks(backend, graphId, kind, options) {
+  let after;
+  for (; ; ) {
+    const rows = await backend.findEdgesByKind({
+      graphId,
+      kind,
+      excludeDeleted: !options.includeDeleted,
+      orderBy: "id",
+      limit: options.batchSize,
+      ...after === void 0 ? {} : { after }
+    });
+    if (rows.length === 0) return;
+    const edges = rows.map((row) => {
+      const edge = {
+        kind: row.kind,
+        id: row.id,
+        from: {
+          kind: row.from_kind,
+          id: row.from_id
+        },
+        to: {
+          kind: row.to_kind,
+          id: row.to_id
+        },
+        properties: rowPropsToObject(row.props)
+      };
+      if (options.includeTemporal) {
+        const validFrom = (
+          // eslint-disable-next-line unicorn/no-null
+          row.valid_from ?? null
+        );
+        edge.validFrom = validFrom;
+        if (row.valid_to) {
+          edge.validTo = row.valid_to;
+        }
+      }
+      if (options.includeMeta) {
+        edge.meta = {
+          createdAt: row.created_at,
+          updatedAt: row.updated_at
+        };
+      }
+      return edge;
+    });
+    yield { type: "edges", edges };
+    if (rows.length < options.batchSize) return;
+    after = rows.at(-1).id;
+  }
+}
+
+// src/interchange/import.ts
+async function importGraph(store, data, rawOptions) {
+  const options = ImportOptionsSchema.parse(rawOptions);
+  const result = emptyImportResult();
+  const errors = [];
+  const graph = store.graph;
+  const graphId = store.graphId;
+  const backend = store.backend;
+  const registry = store.registry;
+  const nodeSchemas = buildNodeSchemaMap(graph);
+  const edgeSchemas = buildEdgeSchemaMap(graph);
+  const importedNodeIds = /* @__PURE__ */ new Set();
+  await runInWriteTransaction(store, backend, async (target, lock) => {
+    await processNodes(
+      target,
+      graphId,
+      registry,
+      data.nodes,
+      nodeSchemas,
+      options,
+      result,
+      errors,
+      importedNodeIds,
+      lock
+    );
+    await processEdges(
+      target,
+      graphId,
+      registry,
+      data.edges,
+      edgeSchemas,
+      nodeSchemas,
+      options,
+      result,
+      errors,
+      importedNodeIds
+    );
+  });
+  await refreshStatisticsAfterImport(store, options, result, "importGraph");
+  return {
+    ...result,
+    success: errors.length === 0,
+    errors
+  };
+}
+async function importGraphStream(store, chunks, rawOptions) {
+  const options = ImportOptionsSchema.parse(rawOptions);
+  const result = emptyImportResult();
+  let header;
+  let receivedEdges = false;
+  for await (const chunk of chunks) {
+    switch (chunk.type) {
+      case "header": {
+        if (header !== void 0) {
+          throw new Error(
+            "Graph interchange stream emitted more than one header."
+          );
+        }
+        header = chunk.header;
+        break;
+      }
+      case "nodes": {
+        if (header === void 0) {
+          throw new Error("Graph interchange stream must start with a header.");
+        }
+        if (receivedEdges) {
+          throw new Error(
+            "Graph interchange stream cannot emit nodes after edges."
+          );
+        }
+        if (chunk.nodes.length === 0) break;
+        mergeImportResult(
+          result,
+          await importGraph(store, graphDataForChunk(header, chunk.nodes, []), {
+            ...options,
+            refreshStatistics: false
+          })
+        );
+        throwIfStreamChunkFailed(result, options);
+        break;
+      }
+      case "edges": {
+        if (header === void 0) {
+          throw new Error("Graph interchange stream must start with a header.");
+        }
+        receivedEdges = true;
+        if (chunk.edges.length === 0) break;
+        mergeImportResult(
+          result,
+          await importGraph(store, graphDataForChunk(header, [], chunk.edges), {
+            ...options,
+            refreshStatistics: false
+          })
+        );
+        throwIfStreamChunkFailed(result, options);
+        break;
+      }
+    }
+  }
+  if (header === void 0) {
+    throw new Error("Graph interchange stream ended before emitting a header.");
+  }
+  await refreshStatisticsAfterImport(
+    store,
+    options,
+    result,
+    "importGraphStream"
+  );
+  return { ...result, success: result.errors.length === 0 };
+}
+function throwIfStreamChunkFailed(result, options) {
+  if (options.onStreamChunkError === "continue" || result.errors.length === 0) {
+    return;
+  }
+  throw new Error(
+    'Graph interchange stream aborted after a chunk reported import errors. Earlier chunks remain committed; use onStreamChunkError: "continue" for best-effort ingestion.'
+  );
+}
+function emptyImportResult() {
+  return {
+    success: true,
+    nodes: { created: 0, updated: 0, skipped: 0 },
+    edges: { created: 0, updated: 0, skipped: 0 },
+    errors: []
+  };
+}
+function graphDataForChunk(header, nodes, edges) {
+  return { ...header, nodes, edges };
+}
+function mergeImportResult(target, source) {
+  target.nodes.created += source.nodes.created;
+  target.nodes.updated += source.nodes.updated;
+  target.nodes.skipped += source.nodes.skipped;
+  target.edges.created += source.edges.created;
+  target.edges.updated += source.edges.updated;
+  target.edges.skipped += source.edges.skipped;
+  target.errors.push(...source.errors);
+}
+async function refreshStatisticsAfterImport(store, options, result, surface) {
+  const mutationCount = result.nodes.created + result.nodes.updated + result.edges.created + result.edges.updated;
+  if ((options.refreshStatistics ?? true) && mutationCount > 0) {
+    try {
+      await store.refreshStatistics();
+    } catch (error) {
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn(
+          `[typegraph] ${surface} committed its rows but the follow-up statistics refresh failed; run store.refreshStatistics() to give the planner fresh statistics.`,
+          error
+        );
+      }
+    }
+  }
+}
+function buildNodeSchemaMap(graph) {
+  const map = /* @__PURE__ */ new Map();
+  for (const kindName of getNodeKinds(graph)) {
+    const registration = graph.nodes[kindName];
+    map.set(kindName, {
+      registration,
+      schema: registration.type.schema
+    });
+  }
+  return map;
+}
+function buildEdgeSchemaMap(graph) {
+  const map = /* @__PURE__ */ new Map();
+  for (const kindName of getEdgeKinds(graph)) {
+    const registration = graph.edges[kindName];
+    map.set(kindName, {
+      registration,
+      schema: registration.type.schema
+    });
+  }
+  return map;
+}
+async function processNodes(backend, graphId, registry, nodes, schemas, options, result, errors, importedNodeIds, lock) {
+  const batchSize = options.batchSize;
+  for (let index = 0; index < nodes.length; index += batchSize) {
+    const batch = nodes.slice(index, index + batchSize);
+    await processNodeSlice(
+      backend,
+      graphId,
+      registry,
+      batch,
+      schemas,
+      options,
+      result,
+      errors,
+      importedNodeIds,
+      lock
+    );
+  }
+}
+function recordNodeOutcome(node, outcome, result, errors, importedNodeIds) {
+  switch (outcome.status) {
+    case "created": {
+      result.nodes.created++;
+      importedNodeIds.add(makeNodeKey(node.kind, node.id));
+      break;
+    }
+    case "updated": {
+      result.nodes.updated++;
+      importedNodeIds.add(makeNodeKey(node.kind, node.id));
+      break;
+    }
+    case "skipped": {
+      result.nodes.skipped++;
+      if (outcome.liveTarget) {
+        importedNodeIds.add(makeNodeKey(node.kind, node.id));
+      }
+      break;
+    }
+    case "error": {
+      errors.push({
+        entityType: "node",
+        kind: node.kind,
+        id: node.id,
+        error: outcome.error
+      });
+      break;
+    }
+  }
+}
+async function processNodeSlice(backend, graphId, registry, batch, schemas, options, result, errors, importedNodeIds, lock) {
+  const record = (node, outcome) => {
+    recordNodeOutcome(node, outcome, result, errors, importedNodeIds);
+  };
+  const candidates = [];
+  const deferred = [];
+  const seenKeys = /* @__PURE__ */ new Set();
+  for (const node of batch) {
+    const schemaEntry = schemas.get(node.kind);
+    if (!schemaEntry) {
+      record(node, {
+        status: "error",
+        error: `Unknown node kind: ${node.kind}`
+      });
+      continue;
+    }
+    const propsResult = validateProperties(
+      node.properties,
+      schemaEntry.schema,
+      options.onUnknownProperty
+    );
+    if (!propsResult.success) {
+      record(node, { status: "error", error: propsResult.error });
+      continue;
+    }
+    const validityError = validateValidityWindow(node);
+    if (validityError !== void 0) {
+      record(node, { status: "error", error: validityError });
+      continue;
+    }
+    const key = makeNodeKey(node.kind, node.id);
+    if (seenKeys.has(key)) {
+      deferred.push(node);
+      continue;
+    }
+    seenKeys.add(key);
+    candidates.push({
+      node,
+      schemaEntry,
+      props: propsResult.data,
+      draft: {
+        kind: node.kind,
+        id: node.id,
+        nodeKind: schemaEntry.registration.type,
+        uniqueConstraints: schemaEntry.registration.unique ?? [],
+        validatedProps: propsResult.data,
+        // NodeCreateDraft.validFrom is string | undefined (never null) — it
+        // only feeds batch validation-cache priming, which never inspects
+        // it, so normalizing the explicit-NULL sentinel away here is inert.
+        // The actual insert (buildImportInsertParams) reads node.validFrom
+        // directly and preserves the null.
+        validFrom: node.validFrom ?? void 0,
+        validTo: node.validTo
+      }
+    });
+  }
+  const {
+    backend: validationBackend,
+    registerPendingNode,
+    registerPendingUniqueEntries,
+    registerAppliedNodeUpdate,
+    seedNodeRow,
+    seedUniqueRow
+  } = createNodeBatchValidationBackend(graphId, registry, backend);
+  await primeBatchValidationCaches(
+    { graphId, registry },
+    candidates.map((candidate) => candidate.draft),
+    backend,
+    { seedNodeRow, seedUniqueRow }
+  );
+  const writeContext = { graphId, registry, lock };
+  const accepted = [];
+  for (const candidate of candidates) {
+    const { node, schemaEntry, props } = candidate;
+    const uniqueConstraints = schemaEntry.registration.unique ?? [];
+    const existing = await validationBackend.getNode(
+      graphId,
+      node.kind,
+      node.id
+    );
+    if (existing) {
+      switch (options.onConflict) {
+        case "skip": {
+          record(node, {
+            status: "skipped",
+            liveTarget: isLiveNodeRow(existing)
+          });
+          break;
+        }
+        case "error": {
+          record(node, {
+            status: "error",
+            error: `Node already exists: ${node.kind}:${node.id}`
+          });
+          break;
+        }
+        case "update": {
+          if (!isLiveNodeRow(existing)) {
+            record(node, { status: "skipped", liveTarget: false });
+            break;
+          }
+          const updateResult = await catchUniquenessError(
+            () => applyNodeUpdate(
+              writeContext,
+              {
+                existing,
+                schema: schemaEntry.registration.type.schema,
+                validatedProps: props,
+                uniqueConstraints,
+                ...node.validTo !== void 0 && { validTo: node.validTo }
+              },
+              // The pending-aware overlay, not the raw backend: the update's
+              // uniqueness pre-check must see a unique value already reserved by
+              // an unflushed create EARLIER in this slice, so it degrades to a
+              // per-row error exactly as the sequential path does — rather than
+              // claiming the key on the real backend and colliding with that
+              // create at flush (which would throw and roll back the whole
+              // import). Writes still delegate to the real backend.
+              validationBackend
+            )
+          );
+          if (updateResult.ok) {
+            registerAppliedNodeUpdate(
+              node.kind,
+              node.id,
+              rowPropsToObject(existing.props),
+              props,
+              uniqueConstraints
+            );
+          }
+          record(
+            node,
+            updateResult.ok ? { status: "updated" } : { status: "error", error: updateResult.error }
+          );
+          break;
+        }
+      }
+      continue;
+    }
+    const uniquenessResult = await catchUniquenessError(
+      () => checkUniquenessConstraints(
+        { graphId, registry, backend: validationBackend },
+        node.kind,
+        node.id,
+        props,
+        uniqueConstraints
+      )
+    );
+    if (!uniquenessResult.ok) {
+      record(node, { status: "error", error: uniquenessResult.error });
+      continue;
+    }
+    registerPendingNode(buildImportInsertParams(graphId, candidate));
+    registerPendingUniqueEntries(node.kind, node.id, props, uniqueConstraints);
+    accepted.push(candidate);
+  }
+  if (accepted.length > 0) {
+    const insertParamsList = accepted.map(
+      (candidate) => buildImportInsertParams(graphId, candidate)
+    );
+    if (backend.insertNodesBatch === void 0) {
+      for (const params of insertParamsList) {
+        await backend.insertNode(params);
+      }
+    } else {
+      await backend.insertNodesBatch(insertParamsList);
+    }
+    await applyNodeInsertSideEffectsBatch(
+      writeContext,
+      accepted.map((candidate) => ({
+        kind: candidate.node.kind,
+        id: candidate.node.id,
+        schema: candidate.schemaEntry.registration.type.schema,
+        props: candidate.props,
+        uniqueConstraints: candidate.schemaEntry.registration.unique ?? []
+      })),
+      backend
+    );
+    for (const candidate of accepted) {
+      record(candidate.node, { status: "created" });
+    }
+  }
+  for (const node of deferred) {
+    record(
+      node,
+      await processNode(
+        backend,
+        graphId,
+        registry,
+        node,
+        schemas,
+        options,
+        lock
+      )
+    );
+  }
+}
+function buildImportInsertParams(graphId, candidate) {
+  const { node, props } = candidate;
+  return {
+    graphId,
+    kind: node.kind,
+    id: node.id,
+    props,
+    ...node.validFrom !== void 0 && { validFrom: node.validFrom },
+    ...node.validTo !== void 0 && { validTo: node.validTo }
+  };
+}
+async function catchUniquenessError(fn) {
+  try {
+    return { ok: true, value: await fn() };
+  } catch (error) {
+    if (error instanceof UniquenessError) {
+      return { ok: false, error: error.message };
+    }
+    throw error;
+  }
+}
+function validateValidityWindow(entity) {
+  try {
+    validateOptionalCanonicalIsoDate(
+      entity.validFrom ?? void 0,
+      "validFrom"
+    );
+    validateOptionalCanonicalIsoDate(entity.validTo, "validTo");
+    return void 0;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+async function processNode(backend, graphId, registry, node, schemas, options, lock) {
+  const schemaEntry = schemas.get(node.kind);
+  if (!schemaEntry) {
+    return { status: "error", error: `Unknown node kind: ${node.kind}` };
+  }
+  const propsResult = validateProperties(
+    node.properties,
+    schemaEntry.schema,
+    options.onUnknownProperty
+  );
+  if (!propsResult.success) {
+    return { status: "error", error: propsResult.error };
+  }
+  const validityError = validateValidityWindow(node);
+  if (validityError !== void 0) {
+    return { status: "error", error: validityError };
+  }
+  const { registration } = schemaEntry;
+  const uniqueConstraints = registration.unique ?? [];
+  const writeContext = { graphId, registry, lock };
+  const existing = await backend.getNode(graphId, node.kind, node.id);
+  if (existing) {
+    switch (options.onConflict) {
+      case "skip": {
+        return { status: "skipped", liveTarget: isLiveNodeRow(existing) };
+      }
+      case "error": {
+        return {
+          status: "error",
+          error: `Node already exists: ${node.kind}:${node.id}`
+        };
+      }
+      case "update": {
+        if (!isLiveNodeRow(existing)) {
+          return { status: "skipped", liveTarget: false };
+        }
+        const updateResult = await catchUniquenessError(
+          () => applyNodeUpdate(
+            writeContext,
+            {
+              existing,
+              schema: registration.type.schema,
+              validatedProps: propsResult.data,
+              uniqueConstraints,
+              ...node.validTo !== void 0 && { validTo: node.validTo }
+            },
+            backend
+          )
+        );
+        if (!updateResult.ok) {
+          return { status: "error", error: updateResult.error };
+        }
+        return { status: "updated" };
+      }
+    }
+  }
+  const uniquenessResult = await catchUniquenessError(
+    () => checkUniquenessConstraints(
+      { graphId, registry, backend },
+      node.kind,
+      node.id,
+      propsResult.data,
+      uniqueConstraints
+    )
+  );
+  if (!uniquenessResult.ok) {
+    return { status: "error", error: uniquenessResult.error };
+  }
+  await backend.insertNode({
+    graphId,
+    kind: node.kind,
+    id: node.id,
+    props: propsResult.data,
+    ...node.validFrom !== void 0 && { validFrom: node.validFrom },
+    ...node.validTo !== void 0 && { validTo: node.validTo }
+  });
+  await applyNodeInsertSideEffects(
+    writeContext,
+    {
+      kind: node.kind,
+      id: node.id,
+      schema: registration.type.schema,
+      props: propsResult.data,
+      uniqueConstraints
+    },
+    backend
+  );
+  return { status: "created" };
+}
+async function processEdges(backend, graphId, registry, edges, edgeSchemas, nodeSchemas, options, result, errors, importedNodeIds) {
+  const batchSize = options.batchSize;
+  for (let index = 0; index < edges.length; index += batchSize) {
+    const batch = edges.slice(index, index + batchSize);
+    await processEdgeSlice(
+      backend,
+      graphId,
+      registry,
+      batch,
+      edgeSchemas,
+      nodeSchemas,
+      options,
+      result,
+      errors,
+      importedNodeIds
+    );
+  }
+}
+function recordEdgeOutcome(edge, outcome, result, errors) {
+  switch (outcome.status) {
+    case "created": {
+      result.edges.created++;
+      break;
+    }
+    case "updated": {
+      result.edges.updated++;
+      break;
+    }
+    case "skipped": {
+      result.edges.skipped++;
+      break;
+    }
+    case "error": {
+      errors.push({
+        entityType: "edge",
+        kind: edge.kind,
+        id: edge.id,
+        error: outcome.error
+      });
+      break;
+    }
+  }
+}
+async function processEdgeSlice(backend, graphId, registry, batch, edgeSchemas, nodeSchemas, options, result, errors, importedNodeIds) {
+  const record = (edge, outcome) => {
+    recordEdgeOutcome(edge, outcome, result, errors);
+  };
+  const candidates = [];
+  const deferred = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const edge of batch) {
+    const schemaEntry = edgeSchemas.get(edge.kind);
+    if (!schemaEntry) {
+      record(edge, {
+        status: "error",
+        error: `Unknown edge kind: ${edge.kind}`
+      });
+      continue;
+    }
+    if (!nodeSchemas.has(edge.from.kind)) {
+      record(edge, {
+        status: "error",
+        error: `Unknown from node kind: ${edge.from.kind}`
+      });
+      continue;
+    }
+    if (!nodeSchemas.has(edge.to.kind)) {
+      record(edge, {
+        status: "error",
+        error: `Unknown to node kind: ${edge.to.kind}`
+      });
+      continue;
+    }
+    const endpointError = validateEdgeEndpoints(
+      edge.kind,
+      edge.from.kind,
+      edge.to.kind,
+      schemaEntry.registration,
+      registry
+    );
+    if (endpointError !== void 0) {
+      record(edge, { status: "error", error: endpointError.message });
+      continue;
+    }
+    const propsResult = validateProperties(
+      edge.properties,
+      schemaEntry.schema,
+      options.onUnknownProperty
+    );
+    if (!propsResult.success) {
+      record(edge, { status: "error", error: propsResult.error });
+      continue;
+    }
+    const validityError = validateValidityWindow(edge);
+    if (validityError !== void 0) {
+      record(edge, { status: "error", error: validityError });
+      continue;
+    }
+    if (seenIds.has(edge.id)) {
+      deferred.push(edge);
+      continue;
+    }
+    seenIds.add(edge.id);
+    candidates.push({ edge, props: propsResult.data });
+  }
+  const liveEndpointKeys = /* @__PURE__ */ new Set();
+  const checkedEndpointKeys = /* @__PURE__ */ new Set();
+  if (options.validateReferences && backend.getNodes !== void 0) {
+    const idsByKind = /* @__PURE__ */ new Map();
+    for (const { edge } of candidates) {
+      for (const endpoint of [edge.from, edge.to]) {
+        const key = makeNodeKey(endpoint.kind, endpoint.id);
+        if (importedNodeIds.has(key) || checkedEndpointKeys.has(key)) continue;
+        checkedEndpointKeys.add(key);
+        const ids = idsByKind.get(endpoint.kind) ?? /* @__PURE__ */ new Set();
+        ids.add(endpoint.id);
+        idsByKind.set(endpoint.kind, ids);
+      }
+    }
+    for (const [kind, ids] of idsByKind) {
+      const rows = await backend.getNodes(graphId, kind, [...ids]);
+      for (const row of rows) {
+        if (isLiveNodeRow(row)) {
+          liveEndpointKeys.add(makeNodeKey(kind, row.id));
+        }
+      }
+    }
+  }
+  const endpointIsLive = async (endpoint) => {
+    const key = makeNodeKey(endpoint.kind, endpoint.id);
+    if (importedNodeIds.has(key)) return true;
+    if (checkedEndpointKeys.has(key)) return liveEndpointKeys.has(key);
+    const row = await backend.getNode(graphId, endpoint.kind, endpoint.id);
+    return row !== void 0 && isLiveNodeRow(row);
+  };
+  const existingById = /* @__PURE__ */ new Map();
+  if (candidates.length > 0 && backend.getEdges !== void 0) {
+    const rows = await backend.getEdges(
+      graphId,
+      candidates.map((candidate) => candidate.edge.id)
+    );
+    for (const row of rows) {
+      existingById.set(row.id, row);
+    }
+    for (const { edge } of candidates) {
+      if (!existingById.has(edge.id)) existingById.set(edge.id, void 0);
+    }
+  }
+  const accepted = [];
+  for (const candidate of candidates) {
+    const { edge, props } = candidate;
+    if (options.validateReferences) {
+      if (!await endpointIsLive(edge.from)) {
+        record(edge, {
+          status: "error",
+          error: `From node not found: ${edge.from.kind}:${edge.from.id}`
+        });
+        continue;
+      }
+      if (!await endpointIsLive(edge.to)) {
+        record(edge, {
+          status: "error",
+          error: `To node not found: ${edge.to.kind}:${edge.to.id}`
+        });
+        continue;
+      }
+    }
+    const existing = existingById.has(edge.id) ? existingById.get(edge.id) : await backend.getEdge(graphId, edge.id);
+    if (existing) {
+      switch (options.onConflict) {
+        case "skip": {
+          record(edge, {
+            status: "skipped",
+            liveTarget: existing.deleted_at === void 0
+          });
+          break;
+        }
+        case "error": {
+          record(edge, {
+            status: "error",
+            error: `Edge already exists: ${edge.id}`
+          });
+          break;
+        }
+        case "update": {
+          if (existing.deleted_at !== void 0) {
+            record(edge, { status: "skipped"});
+            break;
+          }
+          await backend.updateEdge({
+            graphId,
+            id: edge.id,
+            props,
+            ...edge.validTo !== void 0 && { validTo: edge.validTo }
+          });
+          record(edge, { status: "updated" });
+          break;
+        }
+      }
+      continue;
+    }
+    accepted.push(candidate);
+  }
+  if (accepted.length > 0) {
+    const insertParamsList = accepted.map(({ edge, props }) => ({
+      graphId,
+      id: edge.id,
+      kind: edge.kind,
+      fromKind: edge.from.kind,
+      fromId: edge.from.id,
+      toKind: edge.to.kind,
+      toId: edge.to.id,
+      props,
+      ...edge.validFrom !== void 0 && { validFrom: edge.validFrom },
+      ...edge.validTo !== void 0 && { validTo: edge.validTo }
+    }));
+    if (backend.insertEdgesBatch === void 0) {
+      for (const params of insertParamsList) {
+        await backend.insertEdge(params);
+      }
+    } else {
+      await backend.insertEdgesBatch(insertParamsList);
+    }
+    for (const candidate of accepted) {
+      record(candidate.edge, { status: "created" });
+    }
+  }
+  for (const edge of deferred) {
+    record(
+      edge,
+      await processEdge(
+        backend,
+        graphId,
+        registry,
+        edge,
+        edgeSchemas,
+        nodeSchemas,
+        options,
+        importedNodeIds
+      )
+    );
+  }
+}
+async function processEdge(backend, graphId, registry, edge, edgeSchemas, nodeSchemas, options, importedNodeIds) {
+  const schemaEntry = edgeSchemas.get(edge.kind);
+  if (!schemaEntry) {
+    return { status: "error", error: `Unknown edge kind: ${edge.kind}` };
+  }
+  if (!nodeSchemas.has(edge.from.kind)) {
+    return {
+      status: "error",
+      error: `Unknown from node kind: ${edge.from.kind}`
+    };
+  }
+  if (!nodeSchemas.has(edge.to.kind)) {
+    return { status: "error", error: `Unknown to node kind: ${edge.to.kind}` };
+  }
+  const endpointError = validateEdgeEndpoints(
+    edge.kind,
+    edge.from.kind,
+    edge.to.kind,
+    schemaEntry.registration,
+    registry
+  );
+  if (endpointError !== void 0) {
+    return { status: "error", error: endpointError.message };
+  }
+  if (options.validateReferences) {
+    const fromKey = makeNodeKey(edge.from.kind, edge.from.id);
+    const toKey = makeNodeKey(edge.to.kind, edge.to.id);
+    if (!importedNodeIds.has(fromKey)) {
+      const fromExists = await backend.getNode(
+        graphId,
+        edge.from.kind,
+        edge.from.id
+      );
+      if (fromExists === void 0 || !isLiveNodeRow(fromExists)) {
+        return {
+          status: "error",
+          error: `From node not found: ${edge.from.kind}:${edge.from.id}`
+        };
+      }
+    }
+    if (!importedNodeIds.has(toKey)) {
+      const toExists = await backend.getNode(graphId, edge.to.kind, edge.to.id);
+      if (toExists === void 0 || !isLiveNodeRow(toExists)) {
+        return {
+          status: "error",
+          error: `To node not found: ${edge.to.kind}:${edge.to.id}`
+        };
+      }
+    }
+  }
+  const propsResult = validateProperties(
+    edge.properties,
+    schemaEntry.schema,
+    options.onUnknownProperty
+  );
+  if (!propsResult.success) {
+    return { status: "error", error: propsResult.error };
+  }
+  const validityError = validateValidityWindow(edge);
+  if (validityError !== void 0) {
+    return { status: "error", error: validityError };
+  }
+  const existing = await backend.getEdge(graphId, edge.id);
+  if (existing) {
+    switch (options.onConflict) {
+      case "skip": {
+        return {
+          status: "skipped",
+          liveTarget: existing.deleted_at === void 0
+        };
+      }
+      case "error": {
+        return { status: "error", error: `Edge already exists: ${edge.id}` };
+      }
+      case "update": {
+        if (existing.deleted_at !== void 0) {
+          return { status: "skipped", liveTarget: false };
+        }
+        await backend.updateEdge({
+          graphId,
+          id: edge.id,
+          props: propsResult.data,
+          ...edge.validTo !== void 0 && { validTo: edge.validTo }
+        });
+        return { status: "updated" };
+      }
+    }
+  }
+  await backend.insertEdge({
+    graphId,
+    id: edge.id,
+    kind: edge.kind,
+    fromKind: edge.from.kind,
+    fromId: edge.from.id,
+    toKind: edge.to.kind,
+    toId: edge.to.id,
+    props: propsResult.data,
+    ...edge.validFrom !== void 0 && { validFrom: edge.validFrom },
+    ...edge.validTo !== void 0 && { validTo: edge.validTo }
+  });
+  return { status: "created" };
+}
+function validateProperties(properties, schema, unknownStrategy) {
+  try {
+    const knownKeys = new Set(Object.keys(schema.shape));
+    const unknownKeys = Object.keys(properties).filter(
+      (key) => !knownKeys.has(key)
+    );
+    if (unknownKeys.length > 0) {
+      switch (unknownStrategy) {
+        case "error": {
+          return {
+            success: false,
+            error: `Unknown properties: ${unknownKeys.join(", ")}`
+          };
+        }
+        case "strip": {
+          const stripped = {};
+          for (const key of knownKeys) {
+            if (key in properties) {
+              stripped[key] = properties[key];
+            }
+          }
+          const result2 = schema.safeParse(stripped);
+          if (!result2.success) {
+            return {
+              success: false,
+              error: formatZodError(result2.error)
+            };
+          }
+          return {
+            success: true,
+            data: result2.data
+          };
+        }
+        case "allow": {
+          const result2 = schema.safeParse(properties);
+          if (!result2.success) {
+            return {
+              success: false,
+              error: formatZodError(result2.error)
+            };
+          }
+          return { success: true, data: properties };
+        }
+      }
+    }
+    const result = schema.safeParse(properties);
+    if (!result.success) {
+      return { success: false, error: formatZodError(result.error) };
+    }
+    return { success: true, data: result.data };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { success: false, error: `Validation error: ${message}` };
+  }
+}
+function formatZodError(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.join(".");
+    return path ? `${path}: ${issue.message}` : issue.message;
+  }).join("; ");
+}
+function makeNodeKey(kind, id) {
+  return `${kind}:${id}`;
+}
+
+export { ConflictStrategySchema, ExportOptionsSchema, ExportStreamOptionsSchema, FORMAT_VERSION, GraphDataHeaderSchema, GraphDataSchema, GraphDataSourceSchema, GraphInterchangeChunkSchema, ImportErrorSchema, ImportOptionsSchema, ImportResultSchema, InterchangeEdgeSchema, InterchangeNodeSchema, UnknownPropertyStrategySchema, exportGraph, exportGraphStream, importGraph, importGraphStream };
+//# sourceMappingURL=chunk-KMI7LYAF.js.map
+//# sourceMappingURL=chunk-KMI7LYAF.js.map