@nicia-ai/typegraph 0.45.0 → 0.46.1

package/dist/chunk-WQZLUGVR.js

@@ -0,0 +1,2057 @@
+import { createNodeBatchValidationBackend, primeBatchValidationCaches } from './chunk-L65OU2U3.js';
+import { storeBackend, storeRuntime, applyNodeInsertSideEffectsBatch, applyNodeUpdate, checkUniquenessConstraints, applyNodeInsertSideEffects } from './chunk-M3WP7RQZ.js';
+import { runInWriteTransaction, encodeTupleKey, IDENTITY_IMPORT_PROGRESS, IDENTITY_IMPORT_FAILED_ASSERTION } from './chunk-GF3KXUTW.js';
+import { acquireSerializedStreamLease, snapshotExportContention, isLiveNodeRow, rowPropsToObject } from './chunk-AKLS3BYZ.js';
+import { getNodeKinds, getEdgeKinds } from './chunk-775A4ZMN.js';
+import { validateEdgeEndpoints } from './chunk-WDGA7IYB.js';
+import { isCanonicalIsoDate, nowIso, assertWritableValidityWindow, validateOptionalCanonicalIsoDate, assertOrderedValidityWindow } from './chunk-XL7SLCXS.js';
+import { ConfigurationError, ValidationError, ExportStreamCancelledError, NodeNotFoundError, IdentityContradictionError, DatabaseOperationError, UniquenessError, INVERTED_VALIDITY_WINDOW_CODE, IMMUTABLE_VALIDITY_LOWER_BOUND_CODE } from './chunk-J3WZ3FA2.js';
+import { requireDefined, createDataKeyedBag, hasOwnKey } from './chunk-DYATYRY4.js';
+import { z } from 'zod';
+
+var FORMAT_VERSION = "2.0";
+var AcceptedFormatVersionSchema = z.enum(["1.0", "2.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 IdentityInterchangeModeSchema = z.enum(["state", "archival"]);
+var InterchangeIdentityAssertionSchema = z.object({
+  id: z.string().min(1),
+  relation: z.enum(["same", "different"]),
+  a: z.object({ kind: z.string().min(1), id: z.string().min(1) }),
+  b: z.object({ kind: z.string().min(1), id: z.string().min(1) }),
+  validFrom: ValidityTimestampSchema,
+  validTo: ValidityTimestampSchema.optional(),
+  /**
+   * The node whose soft-delete cascade ended this assertion — the ledger's
+   * stored cause, carried so an `archival` round-trip preserves WHY each
+   * ending happened and not merely that it did. Absent on open rows and on
+   * explicit retractions; when present it names one of `a` / `b` and requires
+   * `validTo`. Import rejects both violations with an attributed error.
+   */
+  endedBy: z.object({ kind: z.string().min(1), id: z.string().min(1) }).optional()
+});
+var InterchangeIdentitySchema = z.object({
+  profile: z.literal("typegraph-identity-v1"),
+  mode: IdentityInterchangeModeSchema,
+  assertions: z.array(InterchangeIdentityAssertionSchema)
+});
+var InterchangeIdentityHeaderSchema = InterchangeIdentitySchema.omit({
+  assertions: true
+});
+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: AcceptedFormatVersionSchema,
+  exportedAt: z.iso.datetime(),
+  source: GraphDataSourceSchema,
+  nodes: z.array(InterchangeNodeSchema),
+  edges: z.array(InterchangeEdgeSchema),
+  identity: InterchangeIdentitySchema.optional()
+});
+var GraphDataHeaderSchema = GraphDataSchema.omit({
+  nodes: true,
+  edges: true,
+  identity: true
+}).extend({
+  identity: InterchangeIdentityHeaderSchema.optional()
+});
+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) }),
+  z.object({
+    type: z.literal("identity"),
+    assertions: z.array(InterchangeIdentityAssertionSchema)
+  })
+]);
+var ImportErrorSchema = z.object({
+  entityType: z.enum(["node", "edge", "identity"]),
+  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()
+  }),
+  identity: z.object({
+    created: 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),
+  /** Operational Identity export mode. Defaults to current state only. */
+  identityMode: IdentityInterchangeModeSchema.default("state"),
+  /**
+   * Cancels the export: whatever it had opened is settled — on a backend with
+   * `capabilities.transactions` that means its repeatable-read snapshot is
+   * rolled back and the serialized connection's stream lease released; on one
+   * without, there is no transaction and no lease, and the remaining reads are
+   * simply abandoned. Either way the consumer is rejected with an
+   * `ExportStreamCancelledError` (`code:
+   * "INTERCHANGE_EXPORT_STREAM_ABORTED"`), whose message states which of the
+   * two happened, carrying the signal's own `reason` as `cause`. Aborting
+   * before the first read refuses the export outright: nothing is opened and
+   * nothing claimed.
+   *
+   * On `exportGraph` this is a convenience — the call rejects instead of
+   * running to completion. On {@link exportGraphStream} it is the ONLY
+   * contract-grade way to stop a stream a consumer will not finish pulling:
+   * an async generator's `finally` does not run on garbage collection, so a
+   * consumer that pulls `next()` and then drops the iterator — the
+   * `Promise.race([iterator.next(), timeout])` pattern — otherwise holds the
+   * snapshot transaction, and with it the connection's exclusive stream lease,
+   * until the process exits. `break` / `throw` out of a `for await` and an
+   * explicit `iterator.return()` settle the stream cooperatively and need no
+   * signal; a race that abandons the iterator needs one.
+   */
+  signal: z.instanceof(AbortSignal).optional()
+});
+var ExportStreamOptionsSchema = ExportOptionsSchema.extend({
+  batchSize: z.number().int().positive().default(1e3)
+});
+
+// src/interchange/stream-source.ts
+var EXPORT_STREAM_BACKENDS = /* @__PURE__ */ new WeakMap();
+function markExportStreamBackend(stream, backend) {
+  EXPORT_STREAM_BACKENDS.set(stream, backend);
+  return stream;
+}
+function exportStreamBackend(stream) {
+  return EXPORT_STREAM_BACKENDS.get(stream);
+}
+
+// src/interchange/import.ts
+async function importGraph(store, data, rawOptions) {
+  const options = ImportOptionsSchema.parse(rawOptions);
+  return withImportStreamLease(
+    store,
+    () => importGraphData(store, data, options)
+  );
+}
+async function withImportStreamLease(store, run) {
+  const lease = acquireSerializedStreamLease(
+    storeBackend(store),
+    "import-stream"
+  );
+  if (!lease.acquired) {
+    throw serializedStreamRefusal({
+      graphId: store.graphId,
+      requested: "import-stream",
+      heldBy: lease.heldBy
+    });
+  }
+  try {
+    return await run();
+  } finally {
+    lease.release();
+  }
+}
+async function importGraphData(store, data, options) {
+  assertIdentityImportSupported(store, data.identity !== void 0);
+  validateIdentitySection(data.identity);
+  const result = emptyImportResult();
+  const errors = [];
+  const graph = store.graph;
+  const graphId = store.graphId;
+  const backend = storeBackend(store);
+  const runtime = storeRuntime(store);
+  const registry = store.registry;
+  const nodeSchemas = buildNodeSchemaMap(graph);
+  const edgeSchemas = buildEdgeSchemaMap(graph);
+  const importedNodeIds = /* @__PURE__ */ new Set();
+  await runInWriteTransaction(
+    {
+      graphId,
+      schemaVersion: store.introspect().schemaVersion,
+      historyEnabled: store.historyEnabled,
+      revisionTrackingEnabled: store.revisionTrackingEnabled,
+      revisionSchema: store.revisionSchema
+    },
+    backend,
+    async (target, lock) => {
+      await runtime.lockIdentityImportTarget(target);
+      await processNodes(
+        target,
+        graphId,
+        registry,
+        data.nodes,
+        nodeSchemas,
+        options,
+        result,
+        errors,
+        importedNodeIds,
+        lock
+      );
+      await runtime.foldImportedIdentityNodes(
+        target,
+        data.nodes.filter(
+          (node) => importedNodeIds.has(makeNodeKey(node.kind, node.id))
+        ).map((node) => ({ kind: node.kind, id: node.id }))
+      );
+      await processEdges(
+        target,
+        graphId,
+        registry,
+        data.edges,
+        edgeSchemas,
+        nodeSchemas,
+        options,
+        result,
+        errors,
+        importedNodeIds
+      );
+      if (data.identity !== void 0) {
+        await importIdentitySection(
+          runtime,
+          target,
+          graphId,
+          data.identity,
+          result,
+          errors
+        );
+      }
+    }
+  );
+  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 sourceBackend = exportStreamBackend(chunks);
+  const targetBackend = storeBackend(store);
+  const contention = sourceBackend === void 0 ? void 0 : snapshotExportContention(sourceBackend, targetBackend);
+  if (contention !== void 0) {
+    throw serializedStreamRefusal({
+      graphId: store.graphId,
+      requested: "import-stream",
+      heldBy: "export-snapshot",
+      detector: contention
+    });
+  }
+  const result = emptyImportResult();
+  let header;
+  let receivedEdges = false;
+  let receivedIdentity = false;
+  let releaseImportLease;
+  try {
+    for await (const chunk of chunks) {
+      if (releaseImportLease === void 0) {
+        const lease = acquireSerializedStreamLease(
+          targetBackend,
+          "import-stream"
+        );
+        if (!lease.acquired) {
+          throw serializedStreamRefusal({
+            graphId: store.graphId,
+            requested: "import-stream",
+            heldBy: lease.heldBy
+          });
+        }
+        releaseImportLease = lease.release;
+      }
+      switch (chunk.type) {
+        case "header": {
+          if (header !== void 0) {
+            throw new Error(
+              "Graph interchange stream emitted more than one header."
+            );
+          }
+          validateStreamHeader(chunk.header);
+          assertIdentityImportSupported(
+            store,
+            chunk.header.identity !== void 0
+          );
+          header = chunk.header;
+          break;
+        }
+        case "nodes": {
+          if (header === void 0) {
+            throw new Error(
+              "Graph interchange stream must start with a header."
+            );
+          }
+          if (receivedEdges || receivedIdentity) {
+            throw new Error(
+              `Graph interchange stream cannot emit nodes after ${receivedEdges ? "edges" : "identity assertions"}.`
+            );
+          }
+          if (chunk.nodes.length === 0) break;
+          mergeImportResult(
+            result,
+            await importGraphData(
+              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."
+            );
+          }
+          if (receivedIdentity) {
+            throw new Error(
+              "Graph interchange stream cannot emit edges after identity assertions."
+            );
+          }
+          receivedEdges = true;
+          if (chunk.edges.length === 0) break;
+          mergeImportResult(
+            result,
+            await importGraphData(
+              store,
+              graphDataForChunk(header, [], chunk.edges, []),
+              {
+                ...options,
+                refreshStatistics: false
+              }
+            )
+          );
+          throwIfStreamChunkFailed(result, options);
+          break;
+        }
+        case "identity": {
+          if (header === void 0) {
+            throw new Error(
+              "Graph interchange stream must start with a header."
+            );
+          }
+          if (header.identity === void 0) {
+            throw new Error(
+              "Graph interchange stream emitted identity rows without an identity header."
+            );
+          }
+          receivedIdentity = true;
+          if (chunk.assertions.length === 0) break;
+          mergeImportResult(
+            result,
+            await importGraphData(
+              store,
+              graphDataForChunk(header, [], [], chunk.assertions),
+              { ...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"
+    );
+  } finally {
+    releaseImportLease?.();
+  }
+  return { ...result, success: result.errors.length === 0 };
+}
+function serializedStreamRefusal(input) {
+  const { graphId, requested, heldBy, detector } = input;
+  const code = heldBy === "import-stream" ? SERIALIZED_IMPORT_IN_PROGRESS_CODE : detector === "same-sqlite-backend" ? "INTERCHANGE_SAME_SQLITE_BACKEND_SNAPSHOT" : "INTERCHANGE_SHARED_SERIALIZED_BACKEND_SNAPSHOT";
+  const { message, suggestion } = serializedStreamRefusalText(
+    requested,
+    heldBy
+  );
+  return new ConfigurationError(
+    message,
+    { code, graphId, requested, heldBy },
+    { suggestion }
+  );
+}
+var SERIALIZED_IMPORT_IN_PROGRESS_CODE = "INTERCHANGE_SERIALIZED_IMPORT_IN_PROGRESS";
+function serializedStreamRefusalText(requested, heldBy) {
+  if (heldBy === "export-snapshot") {
+    return requested === "import-stream" ? {
+      message: "A snapshot export cannot be streamed into a target that writes through the same serialized database connection: the export's read transaction holds that connection open for the whole stream, so this import can never take the writer slot it needs.",
+      suggestion: "Export to a file first, or import the stream into an independent backend."
+    } : {
+      message: "A snapshot export cannot open on a serialized database connection while another snapshot export is streaming from it: the second export's read transaction would have to nest inside the first one on the single connection they share.",
+      suggestion: "Await the export already in flight before starting the next one, or export from an independent backend."
+    };
+  }
+  return requested === "export-snapshot" ? {
+    message: "A snapshot export cannot open on a serialized database connection while a streaming import is writing through it: the export's read transaction would hold the one connection the import's next chunk has to write on.",
+    suggestion: "Await the import before exporting, or export from an independent backend."
+  } : {
+    message: "A streaming import cannot open on a serialized database connection while another streaming import is writing through it: the two imports commit their chunks on the single connection they share, so the second one's chunk transaction would have to nest inside the first one's.",
+    suggestion: "Await the import already in flight before starting the next one, or import into an independent backend."
+  };
+}
+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 assertIdentityImportSupported(store, hasIdentitySection) {
+  if (hasIdentitySection && store.graph.identity === void 0) {
+    throw new ConfigurationError(
+      "Cannot import identity assertions into an identity-disabled graph.",
+      { code: "IDENTITY_IMPORT_REQUIRES_PROFILE", graphId: store.graphId }
+    );
+  }
+}
+function validateIdentitySection(identity) {
+  if (identity === void 0) return;
+  const parsed = InterchangeIdentitySchema.safeParse(identity);
+  if (parsed.success) return;
+  throw new ValidationError(
+    `Invalid identity interchange section: ${parsed.error.message}`,
+    {
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path.join("."),
+        message: issue.message,
+        code: issue.code
+      }))
+    },
+    { cause: parsed.error }
+  );
+}
+var IDENTITY_IMPORT_ERROR_ENTITY_TYPE = "identity";
+var IDENTITY_IMPORT_ERROR_PATH = "identity.assertions";
+var UNATTRIBUTED_IDENTITY_ERROR_KIND = "assertion";
+var IDENTITY_IMPORT_ID_CONFLICT_CODE = "IDENTITY_IMPORT_ID_CONFLICT";
+function identityImportError(assertion, graphId, message) {
+  const path = assertion === void 0 ? IDENTITY_IMPORT_ERROR_PATH : `${IDENTITY_IMPORT_ERROR_PATH}[${assertion.id}]`;
+  return {
+    entityType: IDENTITY_IMPORT_ERROR_ENTITY_TYPE,
+    kind: assertion?.relation ?? UNATTRIBUTED_IDENTITY_ERROR_KIND,
+    id: assertion?.id ?? graphId,
+    error: `${path}: ${message}`
+  };
+}
+function isIdConflictError(error) {
+  return error instanceof ConfigurationError && error.details["code"] === IDENTITY_IMPORT_ID_CONFLICT_CODE;
+}
+function touchesRef(assertion, ref) {
+  return assertion.a.kind === ref.kind && assertion.a.id === ref.id || assertion.b.kind === ref.kind && assertion.b.id === ref.id;
+}
+function asIdentityImportError(assertions, graphId, error) {
+  const tagged = taggedAssertion(assertions, error);
+  if (error instanceof NodeNotFoundError) {
+    const ref = error.details;
+    const assertion = tagged ?? assertions.find((candidate) => touchesRef(candidate, ref));
+    return identityImportError(assertion, graphId, error.message);
+  }
+  if (error instanceof IdentityContradictionError) {
+    const { a, b } = error.details;
+    const assertion = tagged ?? assertions.find(
+      (candidate) => touchesRef(candidate, a) && touchesRef(candidate, b)
+    );
+    return identityImportError(assertion, graphId, error.message);
+  }
+  if (isIdConflictError(error)) {
+    const assertion = assertions.find(
+      (candidate) => candidate.id === error.details["assertionId"]
+    );
+    return identityImportError(assertion, graphId, error.message);
+  }
+  if (isIdentityAssertionValidationError(error)) {
+    const issue = error.details.issues[0];
+    const message = issue === void 0 ? error.message : `${error.message} (${issue.message})`;
+    return identityImportError(
+      assertions.find((candidate) => candidate.id === issue?.assertionId),
+      graphId,
+      message
+    );
+  }
+  return void 0;
+}
+function taggedAssertion(assertions, error) {
+  if (typeof error !== "object" || error === null) return void 0;
+  const id = error[IDENTITY_IMPORT_FAILED_ASSERTION];
+  if (typeof id !== "string") return void 0;
+  return assertions.find((candidate) => candidate.id === id);
+}
+function isIdentityAssertionValidationError(error) {
+  return error instanceof ValidationError && error.details.issues.length > 0 && error.details.issues.every(
+    (issue) => issue.path === "identity.assertions" && issue.assertionId !== void 0
+  );
+}
+async function importIdentitySection(runtime, target, graphId, identity, result, errors) {
+  try {
+    const summary = await runtime.importIdentityAssertionsAtTarget(
+      target,
+      identity.assertions,
+      identity.mode
+    );
+    result.identity.created += summary.created;
+    result.identity.skipped += summary.skipped;
+  } catch (error) {
+    const entry = asIdentityImportError(identity.assertions, graphId, error);
+    if (entry === void 0) throw error;
+    const progress = identityImportProgress(error);
+    result.identity.created += progress.created;
+    result.identity.skipped += progress.skipped;
+    errors.push(entry);
+  }
+}
+function identityImportProgress(error) {
+  if (typeof error !== "object" || error === null) {
+    return { created: 0, skipped: 0 };
+  }
+  const progress = error[IDENTITY_IMPORT_PROGRESS];
+  if (typeof progress !== "object" || progress === null || !("created" in progress) || typeof progress.created !== "number" || !("skipped" in progress) || typeof progress.skipped !== "number") {
+    return { created: 0, skipped: 0 };
+  }
+  return { created: progress.created, skipped: progress.skipped };
+}
+function validateStreamHeader(header) {
+  const parsed = GraphDataHeaderSchema.safeParse(header);
+  if (parsed.success) return;
+  throw new ValidationError(
+    `Invalid graph interchange stream header: ${parsed.error.message}`,
+    {
+      issues: parsed.error.issues.map((issue) => ({
+        path: issue.path.join("."),
+        message: issue.message,
+        code: issue.code
+      }))
+    },
+    { cause: parsed.error }
+  );
+}
+function emptyImportResult() {
+  return {
+    success: true,
+    nodes: { created: 0, updated: 0, skipped: 0 },
+    edges: { created: 0, updated: 0, skipped: 0 },
+    identity: { created: 0, skipped: 0 },
+    errors: []
+  };
+}
+function graphDataForChunk(header, nodes, edges, assertions) {
+  const { identity, ...headerWithoutIdentity } = header;
+  return {
+    ...headerWithoutIdentity,
+    nodes,
+    edges,
+    ...identity === void 0 ? {} : {
+      identity: { ...identity, assertions: [...assertions] }
+    }
+  };
+}
+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.identity.created += source.identity.created;
+  target.identity.skipped += source.identity.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 + result.identity.created;
+  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,
+        // Interchange rows always carry an explicit id.
+        idProvided: true,
+        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 updateWindow = validateUpdateValidityWindow(
+            node,
+            existing.valid_from
+          );
+          if (!updateWindow.ok) {
+            record(node, { status: "error", error: updateWindow.error });
+            break;
+          }
+          const updateError = await updateImportedNode(
+            writeContext,
+            // 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,
+            node,
+            {
+              existing,
+              schema: schemaEntry.registration.type.schema,
+              validatedProps: props,
+              uniqueConstraints,
+              windowFence: updateWindow.value
+            }
+          );
+          if (updateError === void 0) {
+            registerAppliedNodeUpdate(
+              node.kind,
+              node.id,
+              rowPropsToObject(existing.props),
+              props,
+              uniqueConstraints
+            );
+          }
+          record(
+            node,
+            updateError === void 0 ? { status: "updated" } : { status: "error", error: updateError }
+          );
+          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;
+  }
+}
+var NODE_UPDATE_TARGET_CHANGED_CODE = "INTERCHANGE_NODE_UPDATE_TARGET_CHANGED";
+async function updateImportedNode(writeContext, backend, node, args) {
+  try {
+    const result = await catchUniquenessError(
+      () => applyNodeUpdate(
+        writeContext,
+        {
+          existing: args.existing,
+          schema: args.schema,
+          validatedProps: args.validatedProps,
+          uniqueConstraints: args.uniqueConstraints,
+          ...args.windowFence,
+          ...node.validTo !== void 0 && { validTo: node.validTo }
+        },
+        backend
+      )
+    );
+    return result.ok ? void 0 : result.error;
+  } catch (error) {
+    if (!(error instanceof DatabaseOperationError) || error.details.reason !== "no_row_returned") {
+      throw error;
+    }
+    return `${NODE_UPDATE_TARGET_CHANGED_CODE}: Node "${node.kind}:${node.id}" was not updated: no live node matching the id and the validity bound this import checked remained when the write ran, so the row changed or was removed after it was checked. Re-export the source and retry.`;
+  }
+}
+var EDGE_IDENTITY_CONFLICT_CODE = "INTERCHANGE_EDGE_KIND_CONFLICT";
+function edgeIdentityConflict(edge, existing) {
+  const differences = [
+    ...existing.kind === edge.kind ? [] : [`kind "${existing.kind}" (document states "${edge.kind}")`],
+    ...existing.from_kind === edge.from.kind && existing.from_id === edge.from.id ? [] : [
+      `from "${existing.from_kind}:${existing.from_id}" (document states "${edge.from.kind}:${edge.from.id}")`
+    ],
+    ...existing.to_kind === edge.to.kind && existing.to_id === edge.to.id ? [] : [
+      `to "${existing.to_kind}:${existing.to_id}" (document states "${edge.to.kind}:${edge.to.id}")`
+    ]
+  ];
+  if (differences.length === 0) return void 0;
+  return `${EDGE_IDENTITY_CONFLICT_CODE}: Edge "${edge.id}" already exists with a different immutable identity \u2014 ${differences.join("; ")}. Edge ids are unique per graph, so the incoming edge can neither update nor be created under that id. Give it a distinct id, or import it under the identity the stored row already carries.`;
+}
+async function updateImportedEdge(backend, graphId, edge, props, windowFence) {
+  try {
+    await backend.updateEdge({
+      graphId,
+      id: edge.id,
+      kind: edge.kind,
+      fromKind: edge.from.kind,
+      fromId: edge.from.id,
+      toKind: edge.to.kind,
+      toId: edge.to.id,
+      props,
+      ...windowFence,
+      ...edge.validTo !== void 0 && { validTo: edge.validTo }
+    });
+    return void 0;
+  } catch (error) {
+    if (!(error instanceof DatabaseOperationError) || error.details.reason !== "no_row_returned") {
+      throw error;
+    }
+    return `${EDGE_IDENTITY_CONFLICT_CODE}: Edge "${edge.id}" of kind "${edge.kind}" from "${edge.from.kind}:${edge.from.id}" to "${edge.to.kind}:${edge.to.id}" was not updated: no live edge matching the identity and the validity bound this import checked remained when the write ran, so the row changed or was removed after it was checked. Re-export the source and retry.`;
+  }
+}
+function windowResultOf(assert) {
+  try {
+    return { ok: true, value: assert() };
+  } catch (error) {
+    if (error instanceof ValidationError) {
+      const coded = error.details.issues.find(
+        (issue) => issue.code === INVERTED_VALIDITY_WINDOW_CODE || issue.code === IMMUTABLE_VALIDITY_LOWER_BOUND_CODE
+      );
+      if (coded !== void 0) {
+        return { ok: false, error: `${coded.code}: ${error.message}` };
+      }
+    }
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function windowErrorOf(assert) {
+  const result = windowResultOf(assert);
+  return result.ok ? void 0 : result.error;
+}
+function validateValidityWindow(entity) {
+  return windowErrorOf(() => {
+    validateOptionalCanonicalIsoDate(
+      entity.validFrom ?? void 0,
+      "validFrom"
+    );
+    validateOptionalCanonicalIsoDate(entity.validTo, "validTo");
+    assertOrderedValidityWindow(
+      `${entity.kind} "${entity.id}"`,
+      entity.validFrom ?? void 0,
+      entity.validTo
+    );
+  });
+}
+function validateUpdateValidityWindow(entity, storedValidFrom) {
+  const verdict = windowResultOf(
+    () => assertWritableValidityWindow(
+      `${entity.kind} "${entity.id}"`,
+      entity.validFrom ?? void 0,
+      {
+        effectiveValidFrom: storedValidFrom,
+        appliesStatedValidFrom: false,
+        // Import updates a LIVE row in place, so the effective bound is always
+        // the one the row already stores.
+        effectiveBoundIsStored: true
+      },
+      entity.validTo
+    )
+  );
+  return verdict.ok ? { ok: true, value: verdict.value.storedLowerBoundFence } : verdict;
+}
+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 updateWindow = validateUpdateValidityWindow(
+          node,
+          existing.valid_from
+        );
+        if (!updateWindow.ok) {
+          return { status: "error", error: updateWindow.error };
+        }
+        const updateError = await updateImportedNode(
+          writeContext,
+          backend,
+          node,
+          {
+            existing,
+            schema: registration.type.schema,
+            validatedProps: propsResult.data,
+            uniqueConstraints,
+            windowFence: updateWindow.value
+          }
+        );
+        if (updateError !== void 0) {
+          return { status: "error", error: updateError };
+        }
+        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) {
+      const identityConflict = edgeIdentityConflict(edge, existing);
+      if (identityConflict !== void 0) {
+        record(edge, { status: "error", error: identityConflict });
+        continue;
+      }
+      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;
+          }
+          const updateWindow = validateUpdateValidityWindow(
+            edge,
+            existing.valid_from
+          );
+          if (!updateWindow.ok) {
+            record(edge, { status: "error", error: updateWindow.error });
+            break;
+          }
+          const updateError = await updateImportedEdge(
+            backend,
+            graphId,
+            edge,
+            props,
+            updateWindow.value
+          );
+          if (updateError !== void 0) {
+            record(edge, { status: "error", error: updateError });
+            break;
+          }
+          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) {
+    const identityConflict = edgeIdentityConflict(edge, existing);
+    if (identityConflict !== void 0) {
+      return { status: "error", error: identityConflict };
+    }
+    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 };
+        }
+        const updateWindow = validateUpdateValidityWindow(
+          edge,
+          existing.valid_from
+        );
+        if (!updateWindow.ok) {
+          return { status: "error", error: updateWindow.error };
+        }
+        const updateError = await updateImportedEdge(
+          backend,
+          graphId,
+          edge,
+          propsResult.data,
+          updateWindow.value
+        );
+        if (updateError !== void 0) {
+          return { status: "error", error: updateError };
+        }
+        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 = createDataKeyedBag();
+          for (const key of knownKeys) {
+            if (hasOwnKey(properties, key)) {
+              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 encodeTupleKey([kind, id]);
+}
+
+// src/interchange/export.ts
+async function exportGraph(store, options) {
+  const nodes = [];
+  const edges = [];
+  const identityAssertions = [];
+  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;
+      }
+      case "identity": {
+        identityAssertions.push(...chunk.assertions);
+        break;
+      }
+    }
+  }
+  if (header === void 0) {
+    throw new Error("Graph export stream ended before emitting its header.");
+  }
+  const { identity, ...headerWithoutIdentity } = header;
+  return {
+    ...headerWithoutIdentity,
+    nodes,
+    edges,
+    ...identity === void 0 ? {} : {
+      identity: { ...identity, assertions: identityAssertions }
+    }
+  };
+}
+function exportGraphStream(store, options) {
+  const backend = storeBackend(store);
+  return markExportStreamBackend(
+    exportGraphStreamFromBackend(store, backend, options),
+    backend
+  );
+}
+async function* exportGraphStreamFromBackend(store, backend, options) {
+  const resolved = ExportStreamOptionsSchema.parse(options ?? {});
+  const signal = resolved.signal;
+  const channel = createRendezvousChannel();
+  const abortStream = () => {
+    channel.abort(
+      exportStreamCancelled(
+        "mid-stream",
+        store.graphId,
+        signal,
+        backend.capabilities.transactions
+      )
+    );
+  };
+  const unsubscribeFromSignal = () => {
+    signal?.removeEventListener("abort", abortStream);
+  };
+  signal?.addEventListener("abort", abortStream, { once: true });
+  if (signal?.aborted === true) {
+    unsubscribeFromSignal();
+    throw exportStreamCancelled(
+      "before-open",
+      store.graphId,
+      signal,
+      backend.capabilities.transactions
+    );
+  }
+  const produce = async (target) => {
+    await produceExportChunks(
+      store,
+      target,
+      resolved,
+      (chunk) => channel.push(chunk)
+    );
+  };
+  const beginProducer = () => {
+    try {
+      const releaseSnapshotExport = backend.capabilities.transactions ? claimSnapshotExportLeaseOrRefuse(store.graphId, backend) : () => {
+      };
+      try {
+        const started = backend.capabilities.transactions ? backend.transaction((target) => produce(target), {
+          isolationLevel: "repeatable_read",
+          accessMode: "read_only"
+        }) : produce(backend);
+        return started.then(
+          () => {
+            releaseSnapshotExport();
+            channel.finish();
+          },
+          (error) => {
+            releaseSnapshotExport();
+            channel.fail(error);
+          }
+        );
+      } catch (error) {
+        releaseSnapshotExport();
+        throw error;
+      }
+    } catch (error) {
+      unsubscribeFromSignal();
+      throw error;
+    }
+  };
+  const producer = beginProducer();
+  try {
+    for (; ; ) {
+      const delivery = await channel.take();
+      if (delivery === void 0) return;
+      yield delivery.value;
+      delivery.acknowledge();
+    }
+  } finally {
+    unsubscribeFromSignal();
+    channel.cancel();
+    await producer;
+  }
+}
+function exportStreamCancelled(phase, graphId, signal, framed) {
+  const message = phase === "before-open" ? "The graph export stream was aborted through its AbortSignal before it opened: no snapshot transaction was started and no database connection claimed." : framed ? "The graph export stream was aborted through its AbortSignal: its repeatable-read snapshot has been rolled back and the connection it held released." : "The graph export stream was aborted through its AbortSignal: its remaining reads were abandoned. This backend does not support transactions, so the export held no snapshot and no connection \u2014 and the chunks already delivered were never guaranteed to agree with one another.";
+  const cause = signal?.reason;
+  const suggestion = phase === "before-open" ? "Start a new export; the aborted one claimed nothing." : framed ? "Start a new export; the aborted one released its snapshot transaction and the connection it held." : "Start a new export; nothing was held, but discard the chunks already delivered unless partial, mutually-inconsistent data is acceptable.";
+  return new ExportStreamCancelledError(
+    message,
+    { graphId },
+    {
+      suggestion,
+      ...cause === void 0 ? {} : { cause }
+    }
+  );
+}
+function claimSnapshotExportLeaseOrRefuse(graphId, backend) {
+  const lease = acquireSerializedStreamLease(backend, "export-snapshot");
+  if (!lease.acquired) {
+    throw serializedStreamRefusal({
+      graphId,
+      requested: "export-snapshot",
+      heldBy: lease.heldBy
+    });
+  }
+  return lease.release;
+}
+async function produceExportChunks(store, backend, options, emit) {
+  const graphId = store.graphId;
+  const nodeKinds = options.nodeKinds ?? getNodeKinds(store.graph);
+  const edgeKinds = options.edgeKinds ?? getEdgeKinds(store.graph);
+  const schemaVersion = await backend.getActiveSchema(graphId);
+  await emit({
+    type: "header",
+    header: {
+      formatVersion: FORMAT_VERSION,
+      exportedAt: nowIso(),
+      source: {
+        type: "typegraph-export",
+        graphId,
+        schemaVersion: schemaVersion?.version ?? 1
+      },
+      ...store.graph.identity === void 0 ? {} : {
+        identity: {
+          profile: "typegraph-identity-v1",
+          mode: options.identityMode
+        }
+      }
+    }
+  });
+  for (const kind of nodeKinds) {
+    for await (const chunk of exportNodeChunks(
+      backend,
+      graphId,
+      kind,
+      options
+    )) {
+      await emit(chunk);
+    }
+  }
+  for (const kind of edgeKinds) {
+    for await (const chunk of exportEdgeChunks(
+      backend,
+      graphId,
+      kind,
+      options
+    )) {
+      await emit(chunk);
+    }
+  }
+  if (store.graph.identity === void 0) return;
+  let after;
+  for (; ; ) {
+    const page = await storeRuntime(store).readIdentityAssertionPageAtTarget(
+      backend,
+      options.identityMode,
+      {
+        ...options.nodeKinds === void 0 ? {} : { nodeKinds },
+        includeDeleted: options.includeDeleted,
+        ...after === void 0 ? {} : { after },
+        limit: options.batchSize
+      }
+    );
+    if (page.assertions.length > 0) {
+      await emit({ type: "identity", assertions: [...page.assertions] });
+    }
+    if (page.done) return;
+    after = requireDefined(page.nextAfter);
+  }
+}
+function createRendezvousChannel() {
+  const consumerCancelledError = new Error("Export stream consumer cancelled.");
+  let pendingPush;
+  let pendingTake;
+  let inFlightReject;
+  let terminal;
+  let producerUnwindError;
+  function push(value) {
+    if (producerUnwindError !== void 0) {
+      return Promise.reject(producerUnwindError);
+    }
+    if (terminal !== void 0 || pendingPush !== void 0) {
+      return Promise.reject(
+        new Error("Cannot push to a completed or occupied export channel.")
+      );
+    }
+    return new Promise((resolve, reject) => {
+      const delivery = {
+        value,
+        acknowledge: () => {
+          inFlightReject = void 0;
+          resolve();
+        }
+      };
+      if (pendingTake !== void 0) {
+        const take2 = pendingTake;
+        pendingTake = void 0;
+        inFlightReject = reject;
+        take2.resolve(delivery);
+        return;
+      }
+      pendingPush = { delivery, reject };
+    });
+  }
+  function take() {
+    if (pendingPush !== void 0) {
+      const push2 = pendingPush;
+      pendingPush = void 0;
+      inFlightReject = push2.reject;
+      return Promise.resolve(push2.delivery);
+    }
+    if (terminal !== void 0) {
+      return terminal.error === void 0 ? Promise.resolve(void 0) : Promise.reject(terminal.error);
+    }
+    if (pendingTake !== void 0) {
+      return Promise.reject(
+        new Error("Export channel already has a consumer.")
+      );
+    }
+    return new Promise((resolve, reject) => {
+      pendingTake = { resolve, reject };
+    });
+  }
+  function finish() {
+    if (producerUnwindError !== void 0) return;
+    terminal = {};
+    if (pendingTake !== void 0) {
+      const take2 = pendingTake;
+      pendingTake = void 0;
+      take2.resolve(void 0);
+    }
+  }
+  function fail(error) {
+    if (producerUnwindError !== void 0 && error === producerUnwindError) {
+      return;
+    }
+    if (terminal !== void 0) return;
+    const exportError = error instanceof Error ? error : new Error("Graph export failed.", { cause: error });
+    terminal = { error: exportError };
+    if (pendingTake !== void 0) {
+      const take2 = pendingTake;
+      pendingTake = void 0;
+      take2.reject(exportError);
+    }
+  }
+  function cancel() {
+    if (producerUnwindError !== void 0) return;
+    producerUnwindError = consumerCancelledError;
+    if (pendingPush !== void 0) {
+      const push2 = pendingPush;
+      pendingPush = void 0;
+      push2.reject(consumerCancelledError);
+    }
+    if (inFlightReject !== void 0) {
+      const reject = inFlightReject;
+      inFlightReject = void 0;
+      reject(consumerCancelledError);
+    }
+    if (pendingTake !== void 0) {
+      const take2 = pendingTake;
+      pendingTake = void 0;
+      take2.resolve(void 0);
+    }
+  }
+  function abort(error) {
+    if (terminal !== void 0 || producerUnwindError !== void 0) return;
+    producerUnwindError = error;
+    terminal = { error };
+    if (pendingPush !== void 0) {
+      const push2 = pendingPush;
+      pendingPush = void 0;
+      push2.reject(error);
+    }
+    if (inFlightReject !== void 0) {
+      const reject = inFlightReject;
+      inFlightReject = void 0;
+      reject(error);
+    }
+    if (pendingTake !== void 0) {
+      const take2 = pendingTake;
+      pendingTake = void 0;
+      take2.reject(error);
+    }
+  }
+  return { push, take, finish, fail, cancel, abort };
+}
+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 = requireDefined(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 = requireDefined(rows.at(-1)).id;
+  }
+}
+
+export { ConflictStrategySchema, ExportOptionsSchema, ExportStreamOptionsSchema, FORMAT_VERSION, GraphDataHeaderSchema, GraphDataSchema, GraphDataSourceSchema, GraphInterchangeChunkSchema, IdentityInterchangeModeSchema, ImportErrorSchema, ImportOptionsSchema, ImportResultSchema, InterchangeEdgeSchema, InterchangeIdentityAssertionSchema, InterchangeIdentitySchema, InterchangeNodeSchema, UnknownPropertyStrategySchema, exportGraph, exportGraphStream, exportStreamBackend, importGraph, importGraphStream, serializedStreamRefusal, withImportStreamLease };
+//# sourceMappingURL=chunk-WQZLUGVR.js.map
+//# sourceMappingURL=chunk-WQZLUGVR.js.map