@nicia-ai/typegraph 0.32.0 → 0.34.0

package/dist/provenance/index.cjs

@@ -0,0 +1,591 @@
+'use strict';
+
+var chunkZ5HBYM7U_cjs = require('../chunk-Z5HBYM7U.cjs');
+var chunk5IQIX7LU_cjs = require('../chunk-5IQIX7LU.cjs');
+var chunkUNNPKQUG_cjs = require('../chunk-UNNPKQUG.cjs');
+var chunkYC6PWTHY_cjs = require('../chunk-YC6PWTHY.cjs');
+require('../chunk-RHZWOJVA.cjs');
+require('../chunk-YAZE7QZR.cjs');
+require('../chunk-NAUA4PW5.cjs');
+require('../chunk-JQGIPGVL.cjs');
+require('../chunk-3E7SNSIA.cjs');
+var chunkDI74SMXS_cjs = require('../chunk-DI74SMXS.cjs');
+var chunkJIEJCTDS_cjs = require('../chunk-JIEJCTDS.cjs');
+require('../chunk-FLRCVI2G.cjs');
+
+// src/provenance/index.ts
+var DEFAULT_RETRACTED_FIELD = "retracted";
+var KEY_SEPARATOR = "\0";
+function refKey(ref) {
+  return `${ref.kind}${KEY_SEPARATOR}${ref.id}`;
+}
+function rowKey(row) {
+  return refKey({ kind: row.kind, id: row.id });
+}
+function edgeFromKey(edge) {
+  return refKey({ kind: edge.from_kind, id: edge.from_id });
+}
+function edgeToKey(edge) {
+  return refKey({ kind: edge.to_kind, id: edge.to_id });
+}
+function keyToRef(key) {
+  const separatorIndex = key.indexOf(KEY_SEPARATOR);
+  if (separatorIndex === -1) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      "Invalid provenance identity key.",
+      { key },
+      {
+        suggestion: "Report this TypeGraph provenance bug with the graph roles that produced the key."
+      }
+    );
+  }
+  const kind = key.slice(0, separatorIndex);
+  const id = key.slice(separatorIndex + KEY_SEPARATOR.length);
+  return { kind, id };
+}
+function sortedReferences(keys) {
+  return [...keys].toSorted((left, right) => chunkZ5HBYM7U_cjs.compareStrings(left, right)).map((key) => keyToRef(key));
+}
+function parseNodeProps(row) {
+  const parsed = JSON.parse(row.props);
+  if (!chunkDI74SMXS_cjs.isPlainObject(parsed)) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      `Node ${row.kind}/${row.id} props are not an object.`,
+      { kind: row.kind, id: row.id }
+    );
+  }
+  return parsed;
+}
+function sourceRetractedState(row, retractedField) {
+  const props = parseNodeProps(row);
+  const value = props[retractedField];
+  if (value === void 0) return "available";
+  if (typeof value !== "boolean") {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      `Provenance source field "${retractedField}" must contain a boolean value.`,
+      { kind: row.kind, id: row.id, field: retractedField },
+      {
+        suggestion: "Use a source node schema with a boolean retracted flag, for example z.boolean().default(false)."
+      }
+    );
+  }
+  return value ? "retracted" : "available";
+}
+function normalizeConfig(graph, config) {
+  const sourceKinds = sourceKindsFromConfig(config.source);
+  const justificationKind = config.justification.kind;
+  const factKinds = [...config.fact.kinds];
+  const premiseOfKind = config.premiseOf.kind;
+  const derivesKind = config.derives.kind;
+  const retractedField = config.source.retractedField ?? DEFAULT_RETRACTED_FIELD;
+  if (sourceKinds.length === 0) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      "Provenance retraction requires at least one source kind.",
+      { role: "source" }
+    );
+  }
+  if (factKinds.length === 0) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      "Provenance retraction requires at least one fact kind.",
+      { role: "fact" }
+    );
+  }
+  const duplicateSourceKinds = duplicateValues(sourceKinds);
+  if (duplicateSourceKinds.length > 0) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError("Provenance source kinds must be unique.", {
+      duplicateSourceKinds
+    });
+  }
+  const duplicateFactKinds = duplicateValues(factKinds);
+  if (duplicateFactKinds.length > 0) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError("Provenance fact kinds must be unique.", {
+      duplicateFactKinds
+    });
+  }
+  for (const kind of sourceKinds) {
+    assertKind(graph.nodes, kind, "source", "node", graph.id);
+  }
+  assertKind(graph.nodes, justificationKind, "justification", "node", graph.id);
+  for (const kind of factKinds) {
+    assertKind(graph.nodes, kind, "fact", "node", graph.id);
+  }
+  for (const kind of sourceKinds)
+    assertSourceField(graph, kind, retractedField);
+  assertKind(graph.edges, premiseOfKind, "premiseOf", "edge", graph.id);
+  assertKind(graph.edges, derivesKind, "derives", "edge", graph.id);
+  if (factKinds.some(
+    (kind) => sourceKinds.includes(kind) || kind === justificationKind
+  )) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      "Provenance fact kinds must be distinct from source and justification kinds.",
+      { sourceKinds, justificationKind, factKinds }
+    );
+  }
+  assertEdgeEndpoints(graph, premiseOfKind, {
+    role: "premiseOf",
+    fromKinds: sourceKinds,
+    toKinds: [justificationKind]
+  });
+  assertEdgeEndpoints(graph, derivesKind, {
+    role: "derives",
+    fromKinds: [justificationKind],
+    toKinds: factKinds
+  });
+  return {
+    sourceKinds,
+    retractedField,
+    justificationKind,
+    factKinds,
+    premiseOfKind,
+    derivesKind
+  };
+}
+function sourceKindsFromConfig(source) {
+  if ("kinds" in source) return [...source.kinds];
+  return [source.kind];
+}
+function duplicateValues(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicates = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      duplicates.add(value);
+      continue;
+    }
+    seen.add(value);
+  }
+  return [...duplicates].toSorted((left, right) => chunkZ5HBYM7U_cjs.compareStrings(left, right));
+}
+function assertKind(records, kind, role, noun, graphId) {
+  if (Object.hasOwn(records, kind)) return;
+  throw new chunkJIEJCTDS_cjs.ConfigurationError(
+    `Provenance ${role} kind "${kind}" is not a ${noun} kind in this graph.`,
+    { role, kind, graphId }
+  );
+}
+function assertSourceField(graph, sourceKind, retractedField) {
+  const registration = graph.nodes[sourceKind];
+  if (registration === void 0) return;
+  if (Object.hasOwn(registration.type.schema.shape, retractedField)) return;
+  throw new chunkJIEJCTDS_cjs.ConfigurationError(
+    `Provenance source kind "${sourceKind}" must include field "${retractedField}".`,
+    { sourceKind, retractedField },
+    {
+      suggestion: "Add a boolean retracted flag to the source node schema or pass source.retractedField."
+    }
+  );
+}
+function assertEdgeEndpoints(graph, edgeKind, expected) {
+  const registration = graph.edges[edgeKind];
+  if (registration === void 0) return;
+  const fromKinds = new Set(registration.from.map((node) => node.kind));
+  const toKinds = new Set(registration.to.map((node) => node.kind));
+  for (const kind of expected.fromKinds) {
+    if (fromKinds.has(kind)) continue;
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      `Provenance ${expected.role} edge "${edgeKind}" cannot start at "${kind}".`,
+      { edgeKind, role: expected.role, expectedFrom: kind }
+    );
+  }
+  for (const kind of expected.toKinds) {
+    if (toKinds.has(kind)) continue;
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      `Provenance ${expected.role} edge "${edgeKind}" cannot end at "${kind}".`,
+      { edgeKind, role: expected.role, expectedTo: kind }
+    );
+  }
+}
+function isValidAt(row, asOf) {
+  return (row.valid_from === void 0 || row.valid_from <= asOf) && (row.valid_to === void 0 || row.valid_to > asOf);
+}
+async function findNodeRows(backend, graphId, kind, options) {
+  if (options.includeTombstones) {
+    const rows = await backend.findNodesByKind({
+      graphId,
+      kind,
+      excludeDeleted: false,
+      temporalMode: "includeTombstones",
+      orderBy: "id"
+    });
+    return rows.filter((row) => isValidAt(row, options.asOf));
+  }
+  return backend.findNodesByKind({
+    graphId,
+    kind,
+    excludeDeleted: true,
+    temporalMode: "current",
+    asOf: options.asOf,
+    orderBy: "id"
+  });
+}
+async function findEdgeRows(backend, graphId, kind, asOf) {
+  return backend.findEdgesByKind({
+    graphId,
+    kind,
+    excludeDeleted: true,
+    temporalMode: "current",
+    asOf,
+    orderBy: "id"
+  });
+}
+async function readRoles(backend, graphId, config, asOf) {
+  const [justificationRows, factRowsByKind, premiseEdges, deriveEdges] = await Promise.all([
+    findNodeRows(backend, graphId, config.justificationKind, {
+      includeTombstones: false,
+      asOf
+    }),
+    Promise.all(
+      config.factKinds.map(
+        (kind) => findNodeRows(backend, graphId, kind, {
+          includeTombstones: true,
+          asOf
+        })
+      )
+    ),
+    findEdgeRows(backend, graphId, config.premiseOfKind, asOf),
+    findEdgeRows(backend, graphId, config.derivesKind, asOf)
+  ]);
+  const factRows = factRowsByKind.flat();
+  return {
+    justifications: rowsByKey(justificationRows),
+    facts: rowsByKey(factRows),
+    premiseEdges,
+    deriveEdges
+  };
+}
+function rowsByKey(rows) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const row of rows) byKey.set(rowKey(row), row);
+  return byKey;
+}
+function appendGroupedValue(groups, key, value) {
+  const group = groups.get(key);
+  if (group === void 0) {
+    groups.set(key, [value]);
+    return;
+  }
+  if (group.includes(value)) return;
+  group.push(value);
+}
+function buildSupportEdges(config, rows) {
+  const premisesByJustification = /* @__PURE__ */ new Map();
+  const factsByJustification = /* @__PURE__ */ new Map();
+  const justificationsByPremise = /* @__PURE__ */ new Map();
+  for (const edge of rows.premiseEdges) {
+    if (edge.to_kind !== config.justificationKind) continue;
+    if (!isPremiseKind(config, edge.from_kind)) continue;
+    const premiseKey = edgeFromKey(edge);
+    const justificationKey = edgeToKey(edge);
+    appendGroupedValue(premisesByJustification, justificationKey, premiseKey);
+    appendGroupedValue(justificationsByPremise, premiseKey, justificationKey);
+  }
+  for (const edge of rows.deriveEdges) {
+    if (edge.from_kind !== config.justificationKind) continue;
+    if (!config.factKinds.includes(edge.to_kind)) continue;
+    appendGroupedValue(
+      factsByJustification,
+      edgeFromKey(edge),
+      edgeToKey(edge)
+    );
+  }
+  return {
+    premisesByJustification,
+    factsByJustification,
+    justificationsByPremise
+  };
+}
+async function loadSupportGraph(backend, graphId, config) {
+  const asOf = chunkYC6PWTHY_cjs.nowIso();
+  const roles = await readRoles(backend, graphId, config, asOf);
+  const supportEdges = buildSupportEdges(config, roles);
+  const sourceRowsByKind = await Promise.all(
+    config.sourceKinds.map(
+      (kind) => findNodeRows(backend, graphId, kind, { includeTombstones: false, asOf })
+    )
+  );
+  return { roles, supportEdges, sourceRows: sourceRowsByKind.flat() };
+}
+function availableSourceKeys(sourceRows, retractedField) {
+  const available = /* @__PURE__ */ new Set();
+  for (const row of sourceRows) {
+    if (sourceRetractedState(row, retractedField) === "available") {
+      available.add(rowKey(row));
+    }
+  }
+  return available;
+}
+function computeSupportSnapshot(graph, available) {
+  const { roles, supportEdges } = graph;
+  const supported = /* @__PURE__ */ new Set();
+  const inSet = new Set(available);
+  const firingJustifications = /* @__PURE__ */ new Set();
+  const firingJustificationKeysByFact = /* @__PURE__ */ new Map();
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [justificationKey] of roles.justifications) {
+      if (firingJustifications.has(justificationKey)) continue;
+      const premises = supportEdges.premisesByJustification.get(justificationKey) ?? [];
+      if (!allPremisesSupported(premises, inSet)) continue;
+      firingJustifications.add(justificationKey);
+      const derivedFacts = supportEdges.factsByJustification.get(justificationKey) ?? [];
+      for (const factKey of derivedFacts) {
+        if (!roles.facts.has(factKey)) continue;
+        appendGroupedValue(
+          firingJustificationKeysByFact,
+          factKey,
+          justificationKey
+        );
+        if (supported.has(factKey)) continue;
+        supported.add(factKey);
+        inSet.add(factKey);
+        changed = true;
+      }
+    }
+  }
+  const believed = /* @__PURE__ */ new Set();
+  for (const key of supported) {
+    const row = roles.facts.get(key);
+    if (row !== void 0 && row.deleted_at === void 0) believed.add(key);
+  }
+  return {
+    facts: roles.facts,
+    supportedFactKeys: supported,
+    believedFactKeys: believed,
+    firingJustificationKeysByFact,
+    affectedFactKeys(targets) {
+      return computeAffectedFactKeys(targets, roles, supportEdges);
+    }
+  };
+}
+async function computeSupport(backend, graphId, config) {
+  const graph = await loadSupportGraph(backend, graphId, config);
+  return computeSupportSnapshot(
+    graph,
+    availableSourceKeys(graph.sourceRows, config.retractedField)
+  );
+}
+function isPremiseKind(config, kind) {
+  return config.sourceKinds.includes(kind) || config.factKinds.includes(kind);
+}
+function allPremisesSupported(premises, supported) {
+  for (const premise of premises) {
+    if (!supported.has(premise)) return false;
+  }
+  return true;
+}
+function computeAffectedFactKeys(sources, roles, supportEdges) {
+  const affected = /* @__PURE__ */ new Set();
+  const frontier = sources.map((source) => refKey(source));
+  const seen = new Set(frontier);
+  while (frontier.length > 0) {
+    const current = frontier.shift();
+    if (current === void 0) continue;
+    const justifications = supportEdges.justificationsByPremise.get(current) ?? [];
+    for (const justificationKey of justifications) {
+      const derivedFacts = supportEdges.factsByJustification.get(justificationKey) ?? [];
+      for (const factKey of derivedFacts) {
+        if (!roles.facts.has(factKey)) continue;
+        affected.add(factKey);
+        if (seen.has(factKey)) continue;
+        seen.add(factKey);
+        frontier.push(factKey);
+      }
+    }
+  }
+  return affected;
+}
+function buildReport(before, after, affected) {
+  const believedBefore = [...before.believedFactKeys];
+  const died = sortedReferences(
+    believedBefore.filter((key) => !after.supportedFactKeys.has(key))
+  );
+  const unaffected = sortedReferences(
+    believedBefore.filter((key) => !affected.has(key))
+  );
+  const survivedVia = [...affected].filter((key) => after.supportedFactKeys.has(key)).toSorted((left, right) => chunkZ5HBYM7U_cjs.compareStrings(left, right)).map((key) => ({
+    fact: keyToRef(key),
+    via: sortedReferences(
+      after.firingJustificationKeysByFact.get(key) ?? []
+    )
+  }));
+  return { died, survivedVia, unaffected };
+}
+async function forEachAffectedFact(snapshot, affected, isTargetKey, isTargetRow, action) {
+  const rows = [];
+  for (const [key, row] of snapshot.facts) {
+    if (!affected.has(key)) continue;
+    if (!isTargetKey(key)) continue;
+    if (!isTargetRow(row)) continue;
+    rows.push(row);
+  }
+  await Promise.all(rows.map((row) => action(row)));
+}
+async function synchronizeFactCurrency(backend, store, runHooks, snapshot, affected, lock) {
+  await forEachAffectedFact(
+    snapshot,
+    affected,
+    (key) => !snapshot.supportedFactKeys.has(key),
+    chunkUNNPKQUG_cjs.isLiveNodeRow,
+    (row) => closeFactCurrency(backend, store, runHooks, row, lock)
+  );
+  await forEachAffectedFact(
+    snapshot,
+    affected,
+    (key) => snapshot.supportedFactKeys.has(key),
+    chunkUNNPKQUG_cjs.isTombstonedNodeRow,
+    (row) => reopenFactCurrency(backend, store, runHooks, row, lock)
+  );
+}
+function getFactRegistration(store, row) {
+  const registration = store.graph.nodes[row.kind];
+  if (registration !== void 0) return registration;
+  throw new chunkJIEJCTDS_cjs.ConfigurationError(
+    `Provenance fact kind "${row.kind}" is not a node kind in this graph.`,
+    { kind: row.kind, graphId: store.graphId }
+  );
+}
+async function closeFactCurrency(backend, store, runHooks, row, lock) {
+  await runHooks("delete", row.kind, row.id, async () => {
+    const registration = getFactRegistration(store, row);
+    await chunk5IQIX7LU_cjs.applyNodeSoftDelete(
+      chunk5IQIX7LU_cjs.createNodeWriteContext(store.graphId, store.registry, lock),
+      {
+        existing: row,
+        schema: registration.type.schema,
+        uniqueConstraints: registration.unique ?? [],
+        onDelete: registration.onDelete
+      },
+      backend,
+      { enforceDeleteBehavior: false }
+    );
+  });
+}
+async function reopenFactCurrency(backend, store, runHooks, row, lock) {
+  await runHooks("update", row.kind, row.id, async () => {
+    const registration = getFactRegistration(store, row);
+    await chunk5IQIX7LU_cjs.applyNodeResurrect(
+      chunk5IQIX7LU_cjs.createNodeWriteContext(store.graphId, store.registry, lock),
+      {
+        existing: row,
+        schema: registration.type.schema,
+        uniqueConstraints: registration.unique ?? []
+      },
+      backend
+    );
+  });
+}
+function getTransactionNodeCollection(tx, kind) {
+  const collection = tx.getNodeCollection(kind);
+  if (collection !== void 0) return collection;
+  throw new chunkJIEJCTDS_cjs.ConfigurationError(
+    `Provenance source kind "${kind}" is not available on this transaction.`,
+    { kind }
+  );
+}
+async function setSourceRetractionState(tx, config, source, retracted) {
+  const collection = getTransactionNodeCollection(tx, source.kind);
+  await collection.update(source.id, { [config.retractedField]: retracted });
+}
+async function runTransition(store, config, sources, retracted) {
+  const uniqueSources = uniqueNodeReferences(sources);
+  for (const source of uniqueSources) {
+    if (config.sourceKinds.includes(source.kind)) continue;
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      `Provenance retraction source must be one of: ${config.sourceKinds.join(", ")}.`,
+      { expectedKinds: config.sourceKinds, actualKind: source.kind }
+    );
+  }
+  return store.transaction(async (tx) => {
+    const lock = await chunk5IQIX7LU_cjs.lockRecordedGraphWrite(tx.backend, store.graphId);
+    const rows = await Promise.all(
+      uniqueSources.map(
+        (source) => tx.backend.getNode(store.graphId, source.kind, source.id)
+      )
+    );
+    const sourceRows = uniqueSources.map((source, index) => {
+      const sourceRow = rows[index];
+      if (sourceRow === void 0 || sourceRow.deleted_at !== void 0) {
+        throw new chunkJIEJCTDS_cjs.NodeNotFoundError(source.kind, source.id);
+      }
+      return { source, row: sourceRow };
+    });
+    const supportGraph = await loadSupportGraph(
+      tx.backend,
+      store.graphId,
+      config
+    );
+    const availableBefore = availableSourceKeys(
+      supportGraph.sourceRows,
+      config.retractedField
+    );
+    const before = computeSupportSnapshot(supportGraph, availableBefore);
+    const nextState = retracted ? "retracted" : "available";
+    const availableAfter = new Set(availableBefore);
+    for (const { source, row } of sourceRows) {
+      const currentState = sourceRetractedState(row, config.retractedField);
+      if (currentState === nextState) continue;
+      await setSourceRetractionState(tx, config, source, retracted);
+      if (nextState === "available") {
+        availableAfter.add(refKey(source));
+      } else {
+        availableAfter.delete(refKey(source));
+      }
+    }
+    const after = computeSupportSnapshot(supportGraph, availableAfter);
+    const affected = after.affectedFactKeys(uniqueSources);
+    await synchronizeFactCurrency(
+      tx.backend,
+      store,
+      tx.runNodeOperationHooks,
+      after,
+      affected,
+      lock
+    );
+    return buildReport(before, after, affected);
+  });
+}
+function uniqueNodeReferences(references) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const reference of references) {
+    byKey.set(refKey(reference), reference);
+  }
+  return [...byKey.values()];
+}
+function createRetractionCapability(store, config) {
+  const historyEnabled = store.historyEnabled;
+  if (!historyEnabled) {
+    throw new chunkJIEJCTDS_cjs.ConfigurationError(
+      "createRetractionCapability requires a store created with { history: true }.",
+      { graphId: store.graphId },
+      {
+        suggestion: "Use createStoreWithSchema(graph, backend, { history: true }) so retraction mutations are captured and queryable with asOfRecorded()."
+      }
+    );
+  }
+  const normalized = normalizeConfig(store.graph, config);
+  const transition = (sources, retracted) => runTransition(store, normalized, sources, retracted);
+  return {
+    retract: (source) => transition([source], true),
+    retractMany: (sources) => transition(sources, true),
+    unRetract: (source) => transition([source], false),
+    unRetractMany: (sources) => transition(sources, false),
+    async holding() {
+      return store.transaction(async (tx) => {
+        await chunk5IQIX7LU_cjs.lockRecordedGraphWrite(tx.backend, store.graphId);
+        const snapshot = await computeSupport(
+          tx.backend,
+          store.graphId,
+          normalized
+        );
+        return sortedReferences(
+          snapshot.believedFactKeys
+        );
+      });
+    }
+  };
+}
+
+exports.createRetractionCapability = createRetractionCapability;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map