@nicia-ai/typegraph 0.45.0 → 0.46.0

package/dist/{chunk-DXEEHSGN.js → chunk-7VQXLT5O.js}

@@ -1,15 +1,14 @@
-import { formatPostgresTimestamp, coerceNumericScore, nowIso } from './chunk-YMTXMPV6.js';
-import { runtimeStrategyContributions } from './chunk-BGYJW37L.js';
-import { toDrizzleSql } from './chunk-EFEOOCJ3.js';
-import { chunk } from './chunk-35S6P5ZU.js';
-import { createBackendOverlay } from './chunk-55ITBQJI.js';
-import { sortedReplacer } from './chunk-UR7W5YQK.js';
-import { parseDimensionMismatch, isMissingTableError } from './chunk-V34A6R5V.js';
+import { formatPostgresTimestamp, coerceNumericScore, nowIso } from './chunk-NMWDXFPH.js';
+import { runtimeStrategyContributions } from './chunk-5UVRGXD3.js';
+import { toDrizzleSql } from './chunk-UV3SN74I.js';
+import { sortedReplacer } from './chunk-JBQQ7THH.js';
+import { parseDimensionMismatch, chunk, isDuplicatePrimaryKeyError, isMissingTableError } from './chunk-JZUR7ZWE.js';
+import { createBackendOverlay } from './chunk-AKLS3BYZ.js';
 import { sha256Hex } from './chunk-K34OPSJK.js';
-import { getDialect } from './chunk-PVUI6KGR.js';
-import { sql as sql$1, asCompiledStatementSql, isSqlFragment } from './chunk-6DCB664D.js';
-import { isPresent } from './chunk-QMQLUA66.js';
-import { EmbeddingDimensionChangedError, ConfigurationError, StaleVersionError, MigrationError, SchemaContentConflictError, DatabaseOperationError, UniquenessError, TrustedImportError, StoreNotInitializedError } from './chunk-4MB3AQAQ.js';
+import { buildFulltextGraphDelete, buildForeignFulltextGraphProbe, getDialect } from './chunk-YDFDBE6D.js';
+import { sql as sql$1, asCompiledStatementSql, asCompiledRowsSql, isSqlFragment } from './chunk-PQBQG7IM.js';
+import { EmbeddingDimensionChangedError, ConfigurationError, StaleVersionError, MigrationError, SchemaContentConflictError, DatabaseOperationError, UniquenessError, TrustedImportError, ContributionRebuildUnsupportedError, StoreNotInitializedError } from './chunk-J3WZ3FA2.js';
+import { isPresent } from './chunk-DYATYRY4.js';
 import { sql, is, getTableName } from 'drizzle-orm';
 
 // src/backend/edge-endpoint-sets.ts
@@ -225,6 +224,20 @@ function diagnoseContribution(row, signature, tableExists) {
     }
   }
 }
+var PROBE_PROJECTION_ORDER = [
+  "fulltext",
+  "vector"
+];
+var PROBE_DETAIL_PHRASE = {
+  "orphaned-marker": "storage is missing",
+  "missing-marker": "storage is not attested by a durable marker",
+  "failed-materialization": "provisioning failed and produced no storage",
+  stale: "storage exists at a different shape than the current declaration"
+};
+function describeProbeDiagnostic(diagnostic) {
+  const subject = diagnostic.kind === void 0 || diagnostic.fieldPath === void 0 ? `table "${diagnostic.physicalName}"` : `${diagnostic.kind}.${diagnostic.fieldPath}`;
+  return `${subject}: ${PROBE_DETAIL_PHRASE[diagnostic.state]} (${diagnostic.state})`;
+}
 function identityOf(graphId, contribution) {
   return {
     graphId,
@@ -285,6 +298,13 @@ function gateFulltext(tx, assert) {
     gateFulltextMethods(tx, assert)
   );
 }
+function contributionRebuildSupported(fulltextStrategy, fulltextTableName, transactional) {
+  return transactional && runtimeStrategyContributions(fulltextStrategy, fulltextTableName).every(
+    (contribution) => contribution.dropDdl !== void 0
+  );
+}
+var CONTRIBUTION_DDL_LOCK_KEY = "typegraph:contribution-ddl";
+var FOREIGN_GRAPH_REPORT_LIMIT = 5;
 var CONTRIBUTION_KEY_SEPARATOR = String.fromCodePoint(0);
 function contributionKey(graphId, contribution) {
   return [
@@ -354,7 +374,7 @@ function createContributionMaterializer(deps) {
       );
       await deps.recordMarker({
         ...identity,
-        signature,
+        signature: existing.signature,
         attemptedAt: nowIso(),
         materializedAt: void 0,
         error: error.message
@@ -533,7 +553,7 @@ function createContributionMaterializer(deps) {
       else existing.push(target);
     }
     for (const contribution of runtimeContributions()) {
-      addTarget(graphId, { contribution });
+      addTarget(graphId, { contribution, projection: "fulltext" });
     }
     const { vectorStrategy } = deps;
     if (vectorStrategy !== void 0) {
@@ -541,6 +561,7 @@ function createContributionMaterializer(deps) {
         for (const contribution of vectorStrategy.ownedTables(slot)) {
           addTarget(slot.graphId, {
             contribution,
+            projection: "vector",
             kind: slot.nodeKind,
             fieldPath: slot.fieldPath
           });
@@ -549,8 +570,7 @@ function createContributionMaterializer(deps) {
     }
     return targets;
   }
-  async function diagnoseContributions(graphId, vectorSlots) {
-    const targetsByGraph = verificationTargetsByGraph(graphId, vectorSlots);
+  async function diagnoseTargets(targetsByGraph) {
     const probes = /* @__PURE__ */ new Map();
     function tableExists(tableName) {
       const pending = probes.get(tableName);
@@ -563,7 +583,7 @@ function createContributionMaterializer(deps) {
     for (const [id, targets] of targetsByGraph) {
       const read = await readMarkerRows(id);
       const rows = read.kind === "rows" ? read.rows : /* @__PURE__ */ new Map();
-      for (const { contribution, kind, fieldPath } of targets) {
+      for (const { contribution, projection, kind, fieldPath } of targets) {
         const key = contributionKey(id, contribution);
         const row = rows.get(key);
         const state = diagnoseContribution(
@@ -575,6 +595,7 @@ function createContributionMaterializer(deps) {
         diagnosed.push({
           graphId: id,
           contribution,
+          projection,
           diagnostic: {
             owner: contribution.owner,
             logicalName: contribution.logicalName,
@@ -593,14 +614,46 @@ function createContributionMaterializer(deps) {
     }
     return diagnosed;
   }
+  async function diagnoseContributions(graphId, vectorSlots) {
+    return diagnoseTargets(verificationTargetsByGraph(graphId, vectorSlots));
+  }
   async function verifyContributions(graphId, vectorSlots) {
     const diagnosed = await diagnoseContributions(graphId, vectorSlots);
     return diagnosed.map((entry) => entry.diagnostic);
   }
+  async function probeContributions(graphId, vectorSlots) {
+    const targetsByGraph = verificationTargetsByGraph(graphId, vectorSlots);
+    const declared = /* @__PURE__ */ new Set();
+    for (const targets of targetsByGraph.values()) {
+      for (const target of targets) declared.add(target.projection);
+    }
+    const diagnosed = await diagnoseTargets(targetsByGraph);
+    const entries = [];
+    for (const projection of PROBE_PROJECTION_ORDER) {
+      if (!declared.has(projection)) continue;
+      const problems = diagnosed.filter(
+        (entry) => entry.projection === projection
+      );
+      if (problems.length === 0) {
+        entries.push({ contribution: projection, state: "ready" });
+        continue;
+      }
+      entries.push({
+        contribution: projection,
+        state: "degraded",
+        detail: problems.map((entry) => describeProbeDiagnostic(entry.diagnostic)).join("; ")
+      });
+    }
+    return entries;
+  }
   async function repairContributions(graphId, vectorSlots) {
     const diagnosed = await diagnoseContributions(graphId, vectorSlots);
     const results = [];
-    for (const { graphId: targetGraphId, contribution, diagnostic } of diagnosed) {
+    for (const {
+      graphId: targetGraphId,
+      contribution,
+      diagnostic
+    } of diagnosed) {
       if (diagnostic.state === "stale" || diagnostic.state === "orphaned-marker") {
         results.push({ diagnostic, status: "requires-rebuild" });
         continue;
@@ -623,6 +676,156 @@ function createContributionMaterializer(deps) {
       remaining: await verifyContributions(graphId, vectorSlots)
     };
   }
+  async function lockContributionDdl(tx) {
+    if (dialect !== "postgres") return;
+    await tx.execute(
+      asCompiledRowsSql(
+        sql$1`SELECT pg_advisory_xact_lock(hashtext(${CONTRIBUTION_DDL_LOCK_KEY}), 0)`
+      )
+    );
+  }
+  async function lockSharedFulltextTable(tx, tableName) {
+    if (dialect !== "postgres") return;
+    await tx.executeStatement(
+      asCompiledStatementSql(
+        sql$1`LOCK TABLE ${sql$1.identifier(tableName)} IN ACCESS EXCLUSIVE MODE`
+      )
+    );
+  }
+  async function readForeignGraphIds(tx, tableName, graphId) {
+    const rows = await tx.execute(
+      asCompiledRowsSql(
+        buildForeignFulltextGraphProbe(
+          tableName,
+          graphId,
+          FOREIGN_GRAPH_REPORT_LIMIT
+        )
+      )
+    );
+    return rows.map((row) => String(row.graph_id));
+  }
+  async function rebuildContribution(graphId, scope, repopulate) {
+    if (scope === "vector") {
+      throw new ContributionRebuildUnsupportedError(
+        "vector-source-unavailable",
+        { graphId, contribution: scope }
+      );
+    }
+    const contributions = runtimeContributions();
+    const withoutTeardown = contributions.find(
+      (contribution) => contribution.dropDdl === void 0
+    );
+    if (withoutTeardown !== void 0) {
+      throw new ContributionRebuildUnsupportedError("no-drop-ddl", {
+        graphId,
+        contribution: scope,
+        owner: withoutTeardown.owner,
+        logicalName: withoutTeardown.logicalName,
+        physicalName: withoutTeardown.tableName
+      });
+    }
+    const fence = deps.schemaWriteTransaction;
+    if (fence === void 0) {
+      throw new ContributionRebuildUnsupportedError("no-schema-fence", {
+        graphId,
+        contribution: scope,
+        backend: dialect
+      });
+    }
+    const stamps = await Promise.all(
+      contributions.map(async (contribution) => {
+        const key = contributionKey(graphId, contribution);
+        return {
+          contribution,
+          key,
+          signature: await resolveContributionSignature(key, contribution)
+        };
+      })
+    );
+    await deps.ensureMarkerTable();
+    const markers = indexMarkerRows(graphId, await deps.getMarkers(graphId));
+    const sharedTable = deps.fulltextTableName;
+    const sharedTableExisted = await deps.tableExists(sharedTable);
+    const rebuilt = await fence(graphId, async (tx) => {
+      const record = tx.recordContributionMaterialization;
+      if (record === void 0) {
+        throw new ConfigurationError(
+          "rebuildContribution requires a transaction-scoped backend that can write contribution markers; without it the drop, recreate, and stamp could not commit together.",
+          {
+            backend: dialect,
+            capability: "contributions",
+            operation: "rebuild"
+          }
+        );
+      }
+      await lockContributionDdl(tx);
+      const unlockedForeignGraphIds = sharedTableExisted ? await readForeignGraphIds(tx, sharedTable, graphId) : [];
+      const mayRecreate = sharedTableExisted && unlockedForeignGraphIds.length === 0;
+      if (mayRecreate) await lockSharedFulltextTable(tx, sharedTable);
+      const foreignGraphIds = mayRecreate ? await readForeignGraphIds(tx, sharedTable, graphId) : unlockedForeignGraphIds;
+      const recreateStorage = mayRecreate && foreignGraphIds.length === 0;
+      if (!recreateStorage) {
+        const staleStamp = stamps.find(
+          ({ key, signature }) => diagnoseContribution(
+            markers.get(key),
+            signature,
+            sharedTableExisted
+          ) === "stale"
+        );
+        if (staleStamp !== void 0) {
+          throw new ContributionRebuildUnsupportedError(
+            "shared-storage-in-use",
+            {
+              graphId,
+              contribution: scope,
+              owner: staleStamp.contribution.owner,
+              logicalName: staleStamp.contribution.logicalName,
+              physicalName: staleStamp.contribution.tableName,
+              otherGraphIds: foreignGraphIds
+            }
+          );
+        }
+      }
+      for (const { contribution } of stamps) {
+        if (recreateStorage) {
+          for (const statement of contribution.dropDdl ?? []) {
+            await tx.executeSchemaDdl(statement);
+          }
+        }
+        for (const statement of contribution.createDdl) {
+          await tx.executeSchemaDdl(statement);
+        }
+      }
+      if (!recreateStorage) {
+        await tx.executeStatement(
+          asCompiledStatementSql(
+            buildFulltextGraphDelete(sharedTable, graphId)
+          )
+        );
+      }
+      const stats = await repopulate(tx);
+      const now = nowIso();
+      for (const { contribution, signature } of stamps) {
+        await record({
+          ...identityOf(graphId, contribution),
+          signature,
+          attemptedAt: now,
+          materializedAt: now,
+          error: void 0
+        });
+      }
+      return {
+        rebuilt: stamps.map(({ contribution }) => contribution.tableName),
+        processed: stats.processed,
+        repopulated: stats.repopulated,
+        skipped: stats.skipped
+      };
+    });
+    for (const { key, signature } of stamps) {
+      cacheInitializedSignature(key, signature);
+    }
+    return rebuilt;
+  }
   function evictVectorSlot(slot) {
     if (deps.vectorStrategy === void 0) return;
     for (const contribution of deps.vectorStrategy.ownedTables(slot)) {
@@ -652,7 +855,9 @@ function createContributionMaterializer(deps) {
     dropVectorSlot,
     evictVectorSlot,
     verifyContributions,
-    repairContributions
+    repairContributions,
+    probeContributions,
+    rebuildContribution
   };
 }
 var SQLITE_INDEX_MAT_TIMESTAMPS = {
@@ -759,6 +964,30 @@ function buildKindRemovalOnConflictSet(removedAtColumn, paramsRemovedAt) {
     lastError: sql`excluded.${sql.identifier("last_error")}`
   };
 }
+function primaryKeyConstraintNames(relation, keyColumns) {
+  return [`${relation}_pkey`, `${relation}_${keyColumns.join("_")}_pk`];
+}
+function nodePrimaryKeyConstraint(nodes) {
+  const relation = getTableName(nodes);
+  return {
+    table: relation,
+    constraintNames: primaryKeyConstraintNames(relation, [
+      nodes.graphId.name,
+      nodes.kind.name,
+      nodes.id.name
+    ])
+  };
+}
+function edgePrimaryKeyConstraint(edges) {
+  const relation = getTableName(edges);
+  return {
+    table: relation,
+    constraintNames: primaryKeyConstraintNames(relation, [
+      edges.graphId.name,
+      edges.id.name
+    ])
+  };
+}
 function sqlNull(value) {
   return value ?? sql.raw("NULL");
 }
@@ -766,6 +995,11 @@ function resolveValidFrom(validFrom, timestamp) {
   if (validFrom === null) return void 0;
   return validFrom ?? timestamp;
 }
+function expectedValidFromPredicate(column, expected) {
+  if (expected === void 0) return sql.empty();
+  if (expected === null) return sql` AND ${column} IS NULL`;
+  return sql` AND ${column} = ${expected}`;
+}
 function quotedColumn(column) {
   return sql.raw(`"${column.name.replaceAll('"', '""')}"`);
 }
@@ -898,9 +1132,16 @@ function mapHybridSearchRow(row, toNodeRow) {
   };
 }
 function buildClearGraph(tables, graphId) {
-  const fulltext = quotedTableName(tables.fulltextTableName);
   return [
-    { query: sql`DELETE FROM ${fulltext} WHERE "graph_id" = ${graphId}` },
+    // The fulltext table is shared by every graph in the database, so its
+    // graph-scoped delete is owned by one builder the destructive
+    // contribution rebuild calls too — see `buildFulltextGraphDelete`.
+    { query: buildFulltextGraphDelete(tables.fulltextTableName, graphId) },
+    {
+      query: sql`DELETE FROM ${tables.recordedIdentityAssertions} WHERE ${tables.recordedIdentityAssertions.graphId} = ${graphId}`,
+      ignoreMissingTable: true,
+      requiredTableName: getTableName(tables.recordedIdentityAssertions)
+    },
     {
       query: sql`DELETE FROM ${tables.recordedEdges} WHERE ${tables.recordedEdges.graphId} = ${graphId}`,
       ignoreMissingTable: true,
@@ -916,6 +1157,21 @@ function buildClearGraph(tables, graphId) {
       ignoreMissingTable: true,
       requiredTableName: getTableName(tables.recordedClock)
     },
+    {
+      query: sql`DELETE FROM ${tables.identitySeparation} WHERE ${tables.identitySeparation.graphId} = ${graphId}`,
+      ignoreMissingTable: true,
+      requiredTableName: getTableName(tables.identitySeparation)
+    },
+    {
+      query: sql`DELETE FROM ${tables.identityClosure} WHERE ${tables.identityClosure.graphId} = ${graphId}`,
+      ignoreMissingTable: true,
+      requiredTableName: getTableName(tables.identityClosure)
+    },
+    {
+      query: sql`DELETE FROM ${tables.identityAssertions} WHERE ${tables.identityAssertions.graphId} = ${graphId}`,
+      ignoreMissingTable: true,
+      requiredTableName: getTableName(tables.identityAssertions)
+    },
     {
       query: sql`DELETE FROM ${tables.uniques} WHERE ${tables.uniques.graphId} = ${graphId}`
     },
@@ -1252,6 +1508,17 @@ function buildGetEdges(tables, graphId, ids) {
   )})
   `;
 }
+function expectedIdentityPredicate(tables, expected) {
+  const { edges } = tables;
+  const parts = [
+    expected.kind === void 0 ? void 0 : sql` AND ${edges.kind} = ${expected.kind}`,
+    expected.fromKind === void 0 ? void 0 : sql` AND ${edges.fromKind} = ${expected.fromKind}`,
+    expected.fromId === void 0 ? void 0 : sql` AND ${edges.fromId} = ${expected.fromId}`,
+    expected.toKind === void 0 ? void 0 : sql` AND ${edges.toKind} = ${expected.toKind}`,
+    expected.toId === void 0 ? void 0 : sql` AND ${edges.toId} = ${expected.toId}`
+  ].filter((part) => part !== void 0);
+  return parts.length === 0 ? sql.empty() : sql.join(parts, sql``);
+}
 function buildUpdateEdge(tables, params, timestamp) {
   const { edges } = tables;
   const propsJson = JSON.stringify(params.props);
@@ -1259,19 +1526,29 @@ function buildUpdateEdge(tables, params, timestamp) {
     sql`${quotedColumn(edges.props)} = ${propsJson}`,
     sql`${quotedColumn(edges.updatedAt)} = ${timestamp}`
   ];
-  if (params.validTo !== void 0) {
+  if (params.clearDeleted && params.validFrom !== void 0) {
+    setParts.push(
+      sql`${quotedColumn(edges.validFrom)} = ${sqlNull(resolveValidFrom(params.validFrom, timestamp))}`,
+      sql`${quotedColumn(edges.validTo)} = ${sqlNull(params.validTo)}`
+    );
+  } else if (params.validTo !== void 0) {
     setParts.push(sql`${quotedColumn(edges.validTo)} = ${params.validTo}`);
   }
   if (params.clearDeleted) {
     setParts.push(sql`${quotedColumn(edges.deletedAt)} = NULL`);
   }
   const setClause = sql.join(setParts, sql`, `);
+  const expectedIdentity = expectedIdentityPredicate(tables, params);
+  const expectedValidFrom = expectedValidFromPredicate(
+    edges.validFrom,
+    params.expectedValidFrom
+  );
   if (params.clearDeleted) {
     return sql`
       UPDATE ${edges}
       SET ${setClause}
       WHERE ${edges.graphId} = ${params.graphId}
-        AND ${edges.id} = ${params.id}
+        AND ${edges.id} = ${params.id}${expectedIdentity}${expectedValidFrom}
       RETURNING *
     `;
   }
@@ -1279,7 +1556,7 @@ function buildUpdateEdge(tables, params, timestamp) {
     UPDATE ${edges}
     SET ${setClause}
     WHERE ${edges.graphId} = ${params.graphId}
-      AND ${edges.id} = ${params.id}
+      AND ${edges.id} = ${params.id}${expectedIdentity}${expectedValidFrom}
       AND ${edges.deletedAt} IS NULL
     RETURNING *
   `;
@@ -1290,7 +1567,7 @@ function buildDeleteEdge(tables, params, timestamp) {
     UPDATE ${edges}
     SET ${quotedColumn(edges.deletedAt)} = ${timestamp}
     WHERE ${edges.graphId} = ${params.graphId}
-      AND ${edges.id} = ${params.id}
+      AND ${edges.id} = ${params.id}${expectedIdentityPredicate(tables, params.kind === void 0 ? {} : { kind: params.kind })}
       AND ${edges.deletedAt} IS NULL
   `;
 }
@@ -1323,7 +1600,7 @@ function buildHardDeleteEdge(tables, params) {
   return sql`
     DELETE FROM ${edges}
     WHERE ${edges.graphId} = ${params.graphId}
-      AND ${edges.id} = ${params.id}
+      AND ${edges.id} = ${params.id}${expectedIdentityPredicate(tables, params.kind === void 0 ? {} : { kind: params.kind })}
   `;
 }
 function buildHardDeleteEdgesByNode(tables, graphId, nodeKind, nodeId) {
@@ -1536,20 +1813,30 @@ function buildUpdateNode(tables, params, timestamp) {
       sql`${quotedColumn(nodes.version)} = ${quotedColumn(nodes.version)} + 1`
     );
   }
-  if (params.validTo !== void 0) {
+  if (params.clearDeleted) {
+    setParts.push(
+      sql`${quotedColumn(nodes.validFrom)} = ${sqlNull(resolveValidFrom(params.validFrom, timestamp))}`,
+      sql`${quotedColumn(nodes.validTo)} = ${sqlNull(params.validTo)}`
+    );
+  } else if (params.validTo !== void 0) {
     setParts.push(sql`${quotedColumn(nodes.validTo)} = ${params.validTo}`);
   }
   if (params.clearDeleted) {
     setParts.push(sql`${quotedColumn(nodes.deletedAt)} = NULL`);
   }
   const setClause = sql.join(setParts, sql`, `);
+  const expectedValidFrom = expectedValidFromPredicate(
+    nodes.validFrom,
+    params.expectedValidFrom
+  );
   if (params.clearDeleted) {
     return sql`
       UPDATE ${nodes}
       SET ${setClause}
       WHERE ${nodes.graphId} = ${params.graphId}
         AND ${nodes.kind} = ${params.kind}
-        AND ${nodes.id} = ${params.id}
+        AND ${nodes.id} = ${params.id}${expectedValidFrom}
+        AND ${nodes.deletedAt} IS NOT NULL
       RETURNING *
     `;
   }
@@ -1558,7 +1845,7 @@ function buildUpdateNode(tables, params, timestamp) {
     SET ${setClause}
     WHERE ${nodes.graphId} = ${params.graphId}
       AND ${nodes.kind} = ${params.kind}
-      AND ${nodes.id} = ${params.id}
+      AND ${nodes.id} = ${params.id}${expectedValidFrom}
       AND ${nodes.deletedAt} IS NULL
     RETURNING *
   `;
@@ -1894,6 +2181,9 @@ function buildCheckUniqueBatch(tables, params) {
 }
 
 // src/backend/drizzle/operations/strategy.ts
+function nullableText(value) {
+  return value === void 0 ? sql`NULL` : sql`${value}`;
+}
 function bindTableOperationBuilders(tables, builders) {
   const boundEntries = Object.entries(builders).map(([name, builder]) => {
     function boundBuilder(...args) {
@@ -2016,6 +2306,24 @@ function createCommonOperationStrategy(tables, dialect, fulltextStrategy) {
       });
     }
   };
+  function buildInsertContributionMaterialization(params) {
+    return sql`
+      INSERT INTO ${contributionMaterializations}
+        (graph_id, logical_name, owner, table_name, signature,
+         materialized_at, last_attempted_at, last_error)
+      VALUES (
+        ${params.graphId}, ${params.logicalName}, ${params.owner},
+        ${params.tableName}, ${params.signature},
+        ${nullableText(params.materializedAt)}, ${params.attemptedAt},
+        ${nullableText(params.error)}
+      )
+      ON CONFLICT (graph_id, logical_name, owner, table_name) DO UPDATE SET
+        signature = excluded.signature,
+        materialized_at = excluded.materialized_at,
+        last_attempted_at = excluded.last_attempted_at,
+        last_error = excluded.last_error
+    `;
+  }
   function buildDeleteContributionMaterialization(identity) {
     return sql`
       DELETE FROM ${contributionMaterializations}
@@ -2028,10 +2336,15 @@ function createCommonOperationStrategy(tables, dialect, fulltextStrategy) {
   return {
     ...tableOperations,
     ...fulltextBuilders,
+    primaryKeyConstraints: {
+      nodes: nodePrimaryKeyConstraint(tables.nodes),
+      edges: edgePrimaryKeyConstraint(tables.edges)
+    },
     buildUpdateNodeSet(params, timestamp) {
       return buildUpdateNodeSet(tables, dialect, params, timestamp);
     },
     buildDeleteContributionMaterialization,
+    buildInsertContributionMaterialization,
     buildInsertUnique(params) {
       return buildInsertUnique(tables, dialect, params);
     },
@@ -2112,6 +2425,26 @@ function assertAdoptedDialect(externalTx, brand, backend) {
     { backend, capability: "adoptTransaction" }
   );
 }
+async function withDuplicateKeyClassification(run, context) {
+  try {
+    return await run();
+  } catch (error) {
+    if (!isDuplicatePrimaryKeyError(error, context.relation)) throw error;
+    throw new DatabaseOperationError(
+      `Insert ${context.entity} failed: a row with this identity already exists`,
+      {
+        operation: "insert",
+        entity: context.entity,
+        reason: "duplicate_key",
+        attempted: context.attempted
+      },
+      { cause: error }
+    );
+  }
+}
+function attemptedInserts(params) {
+  return params.map((item) => ({ kind: item.kind, id: item.id }));
+}
 function verifyExpectedActiveVersion(graphId, expected, actualActiveVersion) {
   const expectedVersion = expected.kind === "active" ? expected.version : 0;
   assertActiveSchemaVersion(graphId, expectedVersion, actualActiveVersion);
@@ -2201,11 +2534,22 @@ function createCommonOperationBackend(options) {
     async insertNode(params) {
       const timestamp = nowIso2();
       const query = operationStrategy.buildInsertNode(params, timestamp);
-      const row = await execution.execGet(query);
+      const row = await withDuplicateKeyClassification(
+        () => execution.execGet(query),
+        {
+          entity: "node",
+          relation: operationStrategy.primaryKeyConstraints.nodes,
+          attempted: attemptedInserts([params])
+        }
+      );
       if (!row)
         throw new DatabaseOperationError(
           "Insert node failed: no row returned",
-          { operation: "insert", entity: "node" }
+          {
+            operation: "insert",
+            entity: "node",
+            reason: "no_row_returned"
+          }
         );
       return rowMappers.toNodeRow(row);
     },
@@ -2215,7 +2559,11 @@ function createCommonOperationBackend(options) {
         params,
         timestamp
       );
-      await execution.execRun(query);
+      await withDuplicateKeyClassification(() => execution.execRun(query), {
+        entity: "node",
+        relation: operationStrategy.primaryKeyConstraints.nodes,
+        attempted: attemptedInserts([params])
+      });
     },
     async insertNodesBatch(params) {
       if (params.length === 0) {
@@ -2224,7 +2572,11 @@ function createCommonOperationBackend(options) {
       const timestamp = nowIso2();
       for (const chunk2 of chunk(params, batchConfig.nodeInsertBatchSize)) {
         const query = operationStrategy.buildInsertNodesBatch(chunk2, timestamp);
-        await execution.execRun(query);
+        await withDuplicateKeyClassification(() => execution.execRun(query), {
+          entity: "node",
+          relation: operationStrategy.primaryKeyConstraints.nodes,
+          attempted: attemptedInserts(chunk2)
+        });
       }
     },
     async insertNodesBatchReturning(params) {
@@ -2238,7 +2590,14 @@ function createCommonOperationBackend(options) {
           chunk2,
           timestamp
         );
-        const rows = await execution.execAll(query);
+        const rows = await withDuplicateKeyClassification(
+          () => execution.execAll(query),
+          {
+            entity: "node",
+            relation: operationStrategy.primaryKeyConstraints.nodes,
+            attempted: attemptedInserts(chunk2)
+          }
+        );
         allRows.push(...rows.map((row) => rowMappers.toNodeRow(row)));
       }
       return allRows;
@@ -2265,7 +2624,11 @@ function createCommonOperationBackend(options) {
       if (!row)
         throw new DatabaseOperationError(
           "Update node failed: no row returned",
-          { operation: "update", entity: "node" }
+          {
+            operation: "update",
+            entity: "node",
+            reason: "no_row_returned"
+          }
         );
       return rowMappers.toNodeRow(row);
     },
@@ -2329,11 +2692,22 @@ function createCommonOperationBackend(options) {
     async insertEdge(params) {
       const timestamp = nowIso2();
       const query = operationStrategy.buildInsertEdge(params, timestamp);
-      const row = await execution.execGet(query);
+      const row = await withDuplicateKeyClassification(
+        () => execution.execGet(query),
+        {
+          entity: "edge",
+          relation: operationStrategy.primaryKeyConstraints.edges,
+          attempted: attemptedInserts([params])
+        }
+      );
       if (!row)
         throw new DatabaseOperationError(
           "Insert edge failed: no row returned",
-          { operation: "insert", entity: "edge" }
+          {
+            operation: "insert",
+            entity: "edge",
+            reason: "no_row_returned"
+          }
         );
       return rowMappers.toEdgeRow(row);
     },
@@ -2343,7 +2717,11 @@ function createCommonOperationBackend(options) {
         params,
         timestamp
       );
-      await execution.execRun(query);
+      await withDuplicateKeyClassification(() => execution.execRun(query), {
+        entity: "edge",
+        relation: operationStrategy.primaryKeyConstraints.edges,
+        attempted: attemptedInserts([params])
+      });
     },
     async insertEdgesBatch(params) {
       if (params.length === 0) {
@@ -2352,7 +2730,11 @@ function createCommonOperationBackend(options) {
       const timestamp = nowIso2();
       for (const chunk2 of chunk(params, batchConfig.edgeInsertBatchSize)) {
         const query = operationStrategy.buildInsertEdgesBatch(chunk2, timestamp);
-        await execution.execRun(query);
+        await withDuplicateKeyClassification(() => execution.execRun(query), {
+          entity: "edge",
+          relation: operationStrategy.primaryKeyConstraints.edges,
+          attempted: attemptedInserts(chunk2)
+        });
       }
     },
     async insertEdgesBatchReturning(params) {
@@ -2366,7 +2748,14 @@ function createCommonOperationBackend(options) {
           chunk2,
           timestamp
         );
-        const rows = await execution.execAll(query);
+        const rows = await withDuplicateKeyClassification(
+          () => execution.execAll(query),
+          {
+            entity: "edge",
+            relation: operationStrategy.primaryKeyConstraints.edges,
+            attempted: attemptedInserts(chunk2)
+          }
+        );
         allRows.push(...rows.map((row) => rowMappers.toEdgeRow(row)));
       }
       return allRows;
@@ -2393,7 +2782,11 @@ function createCommonOperationBackend(options) {
       if (!row)
         throw new DatabaseOperationError(
           "Update edge failed: no row returned",
-          { operation: "update", entity: "edge" }
+          {
+            operation: "update",
+            entity: "edge",
+            reason: "no_row_returned"
+          }
         );
       return rowMappers.toEdgeRow(row);
     },
@@ -2978,6 +3371,6 @@ function getOrCreateLru(cache, key, cacheMax, create) {
   return value;
 }
 
-export { EMBEDDING_UPSERT_PARAM_COUNT, FIND_EDGES_ENDPOINT_FIXED_PARAM_COUNT, POSTGRES_CONTRIBUTION_MAT_TIMESTAMPS, POSTGRES_INDEX_MAT_TIMESTAMPS, POSTGRES_KIND_REMOVAL_TIMESTAMPS, SQLITE_CONTRIBUTION_MAT_TIMESTAMPS, SQLITE_INDEX_MAT_TIMESTAMPS, SQLITE_KIND_REMOVAL_TIMESTAMPS, analyzeImportedTables, assertActiveSchemaVersion, assertAdoptedDialect, assertTrustedImportDatabaseEmpty, buildContributionInsertValues, buildContributionOnConflictSet, buildKindRemovalInsertValues, buildKindRemovalOnConflictSet, buildLiveNodeCandidates, buildMaterializationInsertValues, buildMaterializationOnConflictSet, commitSchemaVersionIfKindsEmpty, createCachedTableExistence, createCommonOperationBackend, createContributionMaterializer, createPostgresOperationStrategy, createPostgresTrustedImportSession, createSqliteOperationStrategy, createSqliteTrustedImportSession, gateFulltext, gateFulltextMethods, getOrCreateLru, lockPostgresTrustedImportTables, mapContributionMaterializationRow, mapHybridSearchRow, mapKindRemovalRow, mapMaterializationRow, mapVectorWriteError, restoreSecondaryIndexes, suspendPostgresSecondaryIndexes, suspendSqliteSecondaryIndexes, tableExistsFromRow, vectorSlotFromCreateIndexParams, vectorSlotFromDropIndexParams, vectorSlotFromParams };
-//# sourceMappingURL=chunk-DXEEHSGN.js.map
-//# sourceMappingURL=chunk-DXEEHSGN.js.map
+export { EMBEDDING_UPSERT_PARAM_COUNT, FIND_EDGES_ENDPOINT_FIXED_PARAM_COUNT, POSTGRES_CONTRIBUTION_MAT_TIMESTAMPS, POSTGRES_INDEX_MAT_TIMESTAMPS, POSTGRES_KIND_REMOVAL_TIMESTAMPS, SQLITE_CONTRIBUTION_MAT_TIMESTAMPS, SQLITE_INDEX_MAT_TIMESTAMPS, SQLITE_KIND_REMOVAL_TIMESTAMPS, analyzeImportedTables, assertActiveSchemaVersion, assertAdoptedDialect, assertTrustedImportDatabaseEmpty, buildContributionInsertValues, buildContributionOnConflictSet, buildKindRemovalInsertValues, buildKindRemovalOnConflictSet, buildLiveNodeCandidates, buildMaterializationInsertValues, buildMaterializationOnConflictSet, commitSchemaVersionIfKindsEmpty, contributionRebuildSupported, createCachedTableExistence, createCommonOperationBackend, createContributionMaterializer, createPostgresOperationStrategy, createPostgresTrustedImportSession, createSqliteOperationStrategy, createSqliteTrustedImportSession, gateFulltext, gateFulltextMethods, getOrCreateLru, lockPostgresTrustedImportTables, mapContributionMaterializationRow, mapHybridSearchRow, mapKindRemovalRow, mapMaterializationRow, mapVectorWriteError, restoreSecondaryIndexes, suspendPostgresSecondaryIndexes, suspendSqliteSecondaryIndexes, tableExistsFromRow, vectorSlotFromCreateIndexParams, vectorSlotFromDropIndexParams, vectorSlotFromParams };
+//# sourceMappingURL=chunk-7VQXLT5O.js.map
+//# sourceMappingURL=chunk-7VQXLT5O.js.map