@openparser/lineage 1.0.2

package/dist/index.js

@@ -0,0 +1,870 @@
+// src/activity.ts
+import { z as z2 } from "zod";
+
+// src/common.ts
+import { z } from "zod";
+var LineageIdSchema = z.string().trim().min(1).max(512);
+var JsonValueSchema = z.json();
+var AttributesSchema = z.record(z.string().min(1), JsonValueSchema);
+function jsonValuesEqual(left, right) {
+  if (left === right) return true;
+  if (left === null || right === null) return false;
+  if (typeof left !== "object" || typeof right !== "object") return false;
+  return canonicalJson(left) === canonicalJson(right);
+}
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value).filter(([, member]) => member !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, member]) => `${JSON.stringify(key)}:${canonicalJson(member)}`);
+  return `{${entries.join(",")}}`;
+}
+var JsonPointerSchema = z.string().max(2048).regex(/^(?:\/(?:[^~/]|~0|~1)*)*$/, "path must be an RFC 6901 JSON Pointer");
+var LINEAGE_FORMAT = "lineage@1";
+var LineageFormatSchema = z.literal(LINEAGE_FORMAT);
+var TimestampSchema = z.iso.datetime({ offset: true }).max(64);
+
+// src/activity.ts
+var AssociationSchema = z2.object({
+  agent: LineageIdSchema,
+  role: z2.string().trim().min(1).max(128).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var ACTIVITY_STATUSES = ["scheduled", "started", "ended", "failed", "cancelled"];
+var ActivityStatusSchema = z2.enum(ACTIVITY_STATUSES);
+var ImplementationSchema = z2.object({
+  type: z2.string().trim().min(1).max(128).optional(),
+  name: z2.string().trim().min(1).max(512).optional(),
+  version: z2.string().trim().min(1).max(128).optional(),
+  uri: z2.string().trim().min(1).max(4096).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var ActivitySchema = z2.object({
+  type: z2.string().trim().min(1).max(256),
+  name: z2.string().trim().min(1).max(512).optional(),
+  status: ActivityStatusSchema.optional(),
+  startedAt: TimestampSchema.optional(),
+  endedAt: TimestampSchema.optional(),
+  implementation: ImplementationSchema.optional(),
+  parameters: z2.record(z2.string().min(1), JsonValueSchema).optional(),
+  associations: z2.array(AssociationSchema).max(64).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var AgentSchema = z2.object({
+  type: z2.string().trim().min(1).max(128).optional(),
+  name: z2.string().trim().min(1).max(512).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+
+// src/approval.ts
+import { z as z3 } from "zod";
+var ApprovalAssertionSchema = z3.object({
+  /** Agent in `LineageDocument.agents` that signed off. */
+  agent: LineageIdSchema,
+  at: z3.string().datetime(),
+  note: z3.string().trim().min(1).max(2e3).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+
+// src/derivation.ts
+import { z as z5 } from "zod";
+
+// src/confidence.ts
+import { z as z4 } from "zod";
+var ConfidenceScaleSchema = z4.object({
+  min: z4.number().finite(),
+  max: z4.number().finite()
+}).strict().superRefine((scale, ctx) => {
+  if (!(scale.max > scale.min)) {
+    ctx.addIssue({
+      code: "custom",
+      message: "confidence scale max must be greater than min",
+      path: ["max"]
+    });
+  }
+});
+var CONFIDENCE_KINDS = ["reported", "derived", "assessed"];
+var ConfidenceKindSchema = z4.enum(CONFIDENCE_KINDS);
+var ConfidenceSourceSchema = z4.object({
+  type: z4.enum(["entity", "activity", "agent"]),
+  id: LineageIdSchema
+}).strict();
+var ConfidenceAssertionSchema = z4.object({
+  score: z4.number().finite(),
+  scale: ConfidenceScaleSchema,
+  kind: ConfidenceKindSchema,
+  /** What the score measures (e.g. recognition, classification, quality). */
+  scope: z4.string().trim().min(1).max(128),
+  /** Optional finer grain within scope (e.g. field, page, token). */
+  granularity: z4.string().trim().min(1).max(128).optional(),
+  /** When false, scores must not be treated as calibrated probabilities. */
+  calibrated: z4.boolean().default(false),
+  /** Entities, activities, or agents that substantiate or produced this assertion. */
+  sources: z4.array(ConfidenceSourceSchema).max(256).optional(),
+  method: z4.string().trim().min(1).max(256).optional(),
+  sampleCount: z4.number().int().positive().optional(),
+  attributes: AttributesSchema.optional()
+}).strict().superRefine((assertion, ctx) => {
+  const { score, scale } = assertion;
+  if (score < scale.min || score > scale.max) {
+    ctx.addIssue({
+      code: "custom",
+      message: `confidence score ${score} is outside scale [${scale.min}, ${scale.max}]`,
+      path: ["score"]
+    });
+  }
+});
+
+// src/derivation.ts
+var DERIVATION_EFFECTS = ["direct", "indirect"];
+var MAX_DERIVATION_INPUTS = 1024;
+var DerivationEffectSchema = z5.enum(DERIVATION_EFFECTS);
+var DerivationInputSchema = z5.object({
+  entity: LineageIdSchema,
+  role: z5.string().trim().min(1).max(128).optional(),
+  effect: DerivationEffectSchema.default("direct"),
+  confidence: ConfidenceAssertionSchema.optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var TransformationSchema = z5.object({
+  type: z5.string().trim().min(1).max(128).optional(),
+  description: z5.string().trim().min(1).max(4096).optional(),
+  expression: z5.string().trim().min(1).max(8192).optional(),
+  masking: z5.boolean().optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var DerivationSchema = z5.object({
+  id: LineageIdSchema.optional(),
+  output: LineageIdSchema,
+  activity: LineageIdSchema,
+  inputs: z5.array(DerivationInputSchema).max(MAX_DERIVATION_INPUTS).default([]),
+  transformation: TransformationSchema.optional(),
+  confidence: ConfidenceAssertionSchema.optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+function derivationId(derivation) {
+  return derivation.id ?? `derivation:${derivation.output}`;
+}
+
+// src/document.ts
+import { z as z8 } from "zod";
+
+// src/entity.ts
+import { z as z6 } from "zod";
+var AttributionSchema = z6.object({
+  agent: LineageIdSchema,
+  role: z6.string().trim().min(1).max(128).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var DigestSchema = z6.object({
+  algorithm: z6.string().trim().min(1).max(64),
+  value: z6.string().trim().min(1).max(512)
+}).strict();
+var LocatorSchema = z6.object({
+  uri: z6.string().trim().min(1).max(4096),
+  mediaType: z6.string().trim().min(1).max(256).optional(),
+  digest: DigestSchema.optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+var SelectorSchema = z6.object({
+  type: z6.string().trim().min(1).max(128),
+  value: JsonValueSchema,
+  attributes: AttributesSchema.optional()
+}).strict();
+var ENTITY_KINDS = ["value", "artifact", "evidence", "decision", "collection"];
+var EntityKindSchema = z6.enum(ENTITY_KINDS);
+var EntitySchema = z6.object({
+  kind: EntityKindSchema,
+  name: z6.string().trim().min(1).max(512).optional(),
+  /** Inline JSON value when the entity is a materialized datum. */
+  value: JsonValueSchema.optional(),
+  /** Unambiguous location within a larger JSON value (RFC 6901). */
+  path: JsonPointerSchema.optional(),
+  /** Optional JSON Schema (or profile schema object) describing `value`. */
+  schema: z6.record(z6.string(), JsonValueSchema).optional(),
+  locator: LocatorSchema.optional(),
+  selector: SelectorSchema.optional(),
+  digest: DigestSchema.optional(),
+  confidence: z6.array(ConfidenceAssertionSchema).max(64).optional(),
+  /**
+   * Who stands behind this value. Standing is per entity and does not
+   * propagate. OpenParser extraction review projects this from confirmations.
+   */
+  approvals: z6.array(ApprovalAssertionSchema).max(64).optional(),
+  attributions: z6.array(AttributionSchema).max(64).optional(),
+  attributes: AttributesSchema.optional()
+}).strict();
+
+// src/relation.ts
+import { z as z7 } from "zod";
+var RELATION_TYPES = ["member_of", "specialization_of", "alternate_of"];
+var RelationTypeSchema = z7.enum(RELATION_TYPES);
+var RelationSchema = z7.object({
+  type: RelationTypeSchema,
+  source: LineageIdSchema,
+  target: LineageIdSchema,
+  attributes: AttributesSchema.optional()
+}).strict().superRefine((relation, ctx) => {
+  if (relation.source === relation.target) {
+    ctx.addIssue({
+      code: "custom",
+      message: "relation source and target must be distinct",
+      path: ["target"]
+    });
+  }
+});
+
+// src/validate.ts
+var LineageValidationError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(issues.join("; "));
+    this.name = "LineageValidationError";
+    this.issues = issues;
+  }
+};
+function validateLineageGraph(doc) {
+  const issues = [];
+  const entityIds = new Set(Object.keys(doc.entities));
+  const activityIds = new Set(Object.keys(doc.activities));
+  const agentIds = new Set(Object.keys(doc.agents));
+  const idsOfKind = { entity: entityIds, activity: activityIds, agent: agentIds };
+  const requireRef = (kind, id, where) => {
+    if (!idsOfKind[kind].has(id)) issues.push(`${where}: ${kind} "${id}" does not exist`);
+  };
+  const requireConfidenceRefs = (confidence, where) => {
+    for (const source of confidence?.sources ?? []) {
+      requireRef(source.type, source.id, `${where}.sources`);
+    }
+  };
+  const claimed = /* @__PURE__ */ new Map();
+  for (const [bucket, ids] of [
+    ["entities", entityIds],
+    ["activities", activityIds],
+    ["agents", agentIds]
+  ]) {
+    for (const id of ids) {
+      const prior = claimed.get(id);
+      if (prior) {
+        issues.push(`id "${id}" collides across ${prior} and ${bucket}`);
+      } else {
+        claimed.set(id, bucket);
+      }
+    }
+  }
+  const derivationIds = /* @__PURE__ */ new Set();
+  const outputProducers = /* @__PURE__ */ new Map();
+  for (let i = 0; i < doc.derivations.length; i++) {
+    const derivation = doc.derivations[i];
+    const path = `derivations[${i}]`;
+    const id = derivationId(derivation);
+    if (derivationIds.has(id)) {
+      issues.push(`${path}: duplicate derivation id "${id}"`);
+    }
+    derivationIds.add(id);
+    if (claimed.has(id)) {
+      issues.push(`${path}: derivation id "${id}" collides with ${claimed.get(id)}`);
+    }
+    if (!entityIds.has(derivation.output)) {
+      issues.push(`${path}: output entity "${derivation.output}" does not exist`);
+    } else {
+      const prior = outputProducers.get(derivation.output);
+      if (prior) {
+        issues.push(
+          `${path}: entity "${derivation.output}" already has producer derivation "${prior}" (one producer per derived output)`
+        );
+      } else {
+        outputProducers.set(derivation.output, id);
+      }
+    }
+    requireRef("activity", derivation.activity, path);
+    const inputEntities = /* @__PURE__ */ new Set();
+    for (let j = 0; j < derivation.inputs.length; j++) {
+      const input = derivation.inputs[j];
+      const inputPath = `${path}.inputs[${j}]`;
+      requireRef("entity", input.entity, inputPath);
+      if (input.entity === derivation.output) {
+        issues.push(`${inputPath}: output cannot be its own input`);
+      }
+      if (inputEntities.has(input.entity)) {
+        issues.push(`${inputPath}: duplicate input entity "${input.entity}"`);
+      }
+      inputEntities.add(input.entity);
+      requireConfidenceRefs(input.confidence, `${inputPath}.confidence`);
+    }
+    requireConfidenceRefs(derivation.confidence, `${path}.confidence`);
+  }
+  const seenOutputs = /* @__PURE__ */ new Set();
+  for (let i = 0; i < doc.outputs.length; i++) {
+    const outputId = doc.outputs[i];
+    if (!entityIds.has(outputId)) {
+      issues.push(`outputs[${i}]: entity "${outputId}" does not exist`);
+    }
+    if (seenOutputs.has(outputId)) {
+      issues.push(`outputs[${i}]: duplicate entity "${outputId}"`);
+    }
+    seenOutputs.add(outputId);
+  }
+  for (const [entityId, entity] of Object.entries(doc.entities)) {
+    const entityPath = `entities.${entityId}`;
+    entity.attributions?.forEach((attribution, i) => {
+      requireRef("agent", attribution.agent, `${entityPath}.attributions[${i}]`);
+    });
+    entity.approvals?.forEach((approval, i) => {
+      requireRef("agent", approval.agent, `${entityPath}.approvals[${i}]`);
+    });
+    entity.confidence?.forEach((assertion, i) => {
+      requireConfidenceRefs(assertion, `${entityPath}.confidence[${i}]`);
+    });
+  }
+  for (const [activityId, activity] of Object.entries(doc.activities)) {
+    activity.associations?.forEach((association, i) => {
+      requireRef("agent", association.agent, `activities.${activityId}.associations[${i}]`);
+    });
+    const { startedAt, endedAt } = activity;
+    if (startedAt !== void 0 && endedAt !== void 0) {
+      const startedMs = Date.parse(startedAt);
+      const endedMs = Date.parse(endedAt);
+      if (Number.isNaN(startedMs) || Number.isNaN(endedMs)) {
+        issues.push(
+          `activities.${activityId}: startedAt or endedAt is not a valid RFC 3339 timestamp`
+        );
+      } else if (endedMs < startedMs) {
+        issues.push(`activities.${activityId}: endedAt precedes startedAt`);
+      }
+    }
+  }
+  for (let i = 0; i < doc.relations.length; i++) {
+    const relation = doc.relations[i];
+    const path = `relations[${i}]`;
+    requireRef("entity", relation.source, `${path}.source`);
+    requireRef("entity", relation.target, `${path}.target`);
+    if (relation.type === "member_of" && entityIds.has(relation.target) && doc.entities[relation.target]?.kind !== "collection") {
+      issues.push(`${path}: member_of target "${relation.target}" must be a collection entity`);
+    }
+  }
+  const dependents = /* @__PURE__ */ new Map();
+  for (const id of entityIds) dependents.set(id, []);
+  for (const derivation of doc.derivations) {
+    if (!entityIds.has(derivation.output)) continue;
+    for (const input of derivation.inputs) {
+      if (!entityIds.has(input.entity)) continue;
+      dependents.get(input.entity).push(derivation.output);
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const cyclePath = [];
+  const visit = (id) => {
+    if (visited.has(id)) return false;
+    if (visiting.has(id)) {
+      cyclePath.push(id);
+      return true;
+    }
+    visiting.add(id);
+    for (const next of dependents.get(id) ?? []) {
+      if (visit(next)) {
+        cyclePath.push(id);
+        return true;
+      }
+    }
+    visiting.delete(id);
+    visited.add(id);
+    return false;
+  };
+  for (const id of entityIds) {
+    if (visit(id)) {
+      const cycle = [...new Set(cyclePath.reverse())].join(" \u2192 ");
+      issues.push(`entity dependency cycle detected: ${cycle}`);
+      break;
+    }
+  }
+  if (issues.length > 0) {
+    throw new LineageValidationError(issues);
+  }
+}
+
+// src/document.ts
+var LineageDocumentShapeSchema = z8.object({
+  format: LineageFormatSchema,
+  id: LineageIdSchema.optional(),
+  /** Profile URIs or short names declaring extension semantics. */
+  profiles: z8.array(z8.string().trim().min(1).max(1024)).max(64).optional(),
+  entities: z8.record(LineageIdSchema, EntitySchema).default({}),
+  activities: z8.record(LineageIdSchema, ActivitySchema).default({}),
+  agents: z8.record(LineageIdSchema, AgentSchema).default({}),
+  derivations: z8.array(DerivationSchema).max(1e5).default([]),
+  relations: z8.array(RelationSchema).max(1e5).default([]),
+  /** Entity ids that are primary outputs of this document. */
+  outputs: z8.array(LineageIdSchema).max(1e4).default([]),
+  attributes: AttributesSchema.optional()
+}).strict();
+function parseLineageDocument(input) {
+  const doc = LineageDocumentShapeSchema.parse(input);
+  validateLineageGraph(doc);
+  return doc;
+}
+function safeParseLineageDocument(input) {
+  const shape = LineageDocumentShapeSchema.safeParse(input);
+  if (!shape.success) {
+    return { success: false, error: shape.error };
+  }
+  try {
+    validateLineageGraph(shape.data);
+    return { success: true, data: shape.data };
+  } catch (error) {
+    if (error instanceof LineageValidationError) {
+      return { success: false, error };
+    }
+    throw error;
+  }
+}
+var LineageDocumentSchema = LineageDocumentShapeSchema.superRefine((doc, ctx) => {
+  try {
+    validateLineageGraph(doc);
+  } catch (error) {
+    if (error instanceof LineageValidationError) {
+      for (const message of error.issues) {
+        ctx.addIssue({ code: "custom", message });
+      }
+      return;
+    }
+    throw error;
+  }
+});
+
+// src/builder.ts
+var LineageBuilder = class {
+  id;
+  profiles;
+  entities = /* @__PURE__ */ new Map();
+  activities = /* @__PURE__ */ new Map();
+  agents = /* @__PURE__ */ new Map();
+  derivations = [];
+  relations;
+  outputs = [];
+  attributes;
+  withId(id) {
+    this.id = id;
+    return this;
+  }
+  withProfiles(...profiles) {
+    this.profiles = [...this.profiles ?? [], ...profiles];
+    return this;
+  }
+  withAttributes(attributes) {
+    this.attributes = attributes;
+    return this;
+  }
+  entity(id, entity) {
+    if (this.entities.has(id)) {
+      throw new Error(`entity "${id}" already registered`);
+    }
+    this.entities.set(id, entity);
+    return this;
+  }
+  activity(id, activity) {
+    if (this.activities.has(id)) {
+      throw new Error(`activity "${id}" already registered`);
+    }
+    this.activities.set(id, activity);
+    return this;
+  }
+  agent(id, agent) {
+    if (this.agents.has(id)) {
+      throw new Error(`agent "${id}" already registered`);
+    }
+    this.agents.set(id, agent);
+    return this;
+  }
+  /**
+   * Record that `activityId` produced `outputId` from `inputs`.
+   */
+  derive(args) {
+    const id = derivationId(args);
+    if (this.derivations.some((d) => derivationId(d) === id)) {
+      throw new Error(`derivation "${id}" already registered`);
+    }
+    const inputs = (args.inputs ?? []).map(
+      (input) => typeof input === "string" ? { entity: input, effect: "direct" } : input
+    );
+    this.derivations.push({
+      ...args.id ? { id: args.id } : {},
+      output: args.output,
+      activity: args.activity,
+      inputs,
+      ...args.transformation ? { transformation: args.transformation } : {},
+      ...args.confidence ? { confidence: args.confidence } : {},
+      ...args.attributes ? { attributes: args.attributes } : {}
+    });
+    return this;
+  }
+  relation(relation) {
+    this.relations = [...this.relations ?? [], relation];
+    return this;
+  }
+  withOutputs(...entityIds) {
+    this.outputs = [...this.outputs, ...entityIds];
+    return this;
+  }
+  /** Assemble and strictly validate the document. */
+  build() {
+    return parseLineageDocument({
+      format: LINEAGE_FORMAT,
+      ...this.id ? { id: this.id } : {},
+      ...this.profiles && this.profiles.length > 0 ? { profiles: this.profiles } : {},
+      entities: Object.fromEntries(this.entities),
+      activities: Object.fromEntries(this.activities),
+      agents: Object.fromEntries(this.agents),
+      derivations: this.derivations,
+      ...this.relations && this.relations.length > 0 ? { relations: this.relations } : {},
+      outputs: this.outputs,
+      ...this.attributes ? { attributes: this.attributes } : {}
+    });
+  }
+};
+
+// src/prov.ts
+var LINEAGE_PROV_NAMESPACE = "https://openparser.dev/ns/lineage#";
+function lineageIdToProvQualifiedName(id) {
+  const encoded = [...new TextEncoder().encode(id)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `lineage:id_${encoded}`;
+}
+var qname = lineageIdToProvQualifiedName;
+function toProvJson(doc) {
+  const out = {
+    prefix: {
+      prov: "http://www.w3.org/ns/prov#",
+      lineage: LINEAGE_PROV_NAMESPACE
+    }
+  };
+  const entities = {};
+  for (const [id, entity] of Object.entries(doc.entities)) {
+    const record = flattenAttrs(entity.attributes);
+    record["prov:type"] = entity.kind;
+    record["lineage:id"] = id;
+    if (entity.name) record["prov:label"] = entity.name;
+    if (entity.value !== void 0) record["lineage:value"] = entity.value;
+    if (entity.path !== void 0) record["lineage:path"] = entity.path;
+    if (entity.locator?.uri) record["prov:location"] = entity.locator.uri;
+    if (entity.digest) {
+      record["lineage:digestAlgorithm"] = entity.digest.algorithm;
+      record["lineage:digestValue"] = entity.digest.value;
+    }
+    entities[qname(id)] = record;
+  }
+  if (Object.keys(entities).length > 0) out.entity = entities;
+  const activities = {};
+  for (const [id, activity] of Object.entries(doc.activities)) {
+    const record = flattenAttrs(activity.attributes);
+    record["prov:type"] = activity.type;
+    record["lineage:id"] = id;
+    if (activity.name) record["prov:label"] = activity.name;
+    if (activity.startedAt) record["prov:startTime"] = activity.startedAt;
+    if (activity.endedAt) record["prov:endTime"] = activity.endedAt;
+    activities[qname(id)] = record;
+  }
+  if (Object.keys(activities).length > 0) out.activity = activities;
+  const agents = {};
+  for (const [id, agent] of Object.entries(doc.agents)) {
+    const record = flattenAttrs(agent.attributes);
+    record["lineage:id"] = id;
+    if (agent.type) record["prov:type"] = agent.type;
+    if (agent.name) record["prov:label"] = agent.name;
+    agents[qname(id)] = record;
+  }
+  if (Object.keys(agents).length > 0) out.agent = agents;
+  const wasDerivedFrom = {};
+  const wasGeneratedBy = {};
+  const used = {};
+  const wasAssociatedWith = {};
+  const wasAttributedTo = {};
+  const hadMember = {};
+  const specializationOf = {};
+  const alternateOf = {};
+  for (const derivation of doc.derivations) {
+    const id = derivationId(derivation);
+    const genId = qname(`gen:${id}`);
+    wasGeneratedBy[genId] = {
+      "prov:entity": qname(derivation.output),
+      "prov:activity": qname(derivation.activity)
+    };
+    for (let i = 0; i < derivation.inputs.length; i++) {
+      const input = derivation.inputs[i];
+      const derId = qname(`wdf:${id}:${i}`);
+      wasDerivedFrom[derId] = {
+        "prov:generatedEntity": qname(derivation.output),
+        "prov:usedEntity": qname(input.entity),
+        "prov:activity": qname(derivation.activity),
+        ...input.role ? { "prov:role": input.role } : {},
+        "lineage:effect": input.effect
+      };
+      const usedId = qname(`used:${id}:${i}`);
+      used[usedId] = {
+        "prov:activity": qname(derivation.activity),
+        "prov:entity": qname(input.entity),
+        ...input.role ? { "prov:role": input.role } : {}
+      };
+    }
+  }
+  for (const [activityId, activity] of Object.entries(doc.activities)) {
+    for (let i = 0; i < (activity.associations?.length ?? 0); i++) {
+      const association = activity.associations[i];
+      wasAssociatedWith[qname(`assoc:${activityId}:${i}`)] = {
+        "prov:activity": qname(activityId),
+        "prov:agent": qname(association.agent),
+        ...association.role ? { "prov:role": association.role } : {}
+      };
+    }
+  }
+  for (const [entityId, entity] of Object.entries(doc.entities)) {
+    for (let i = 0; i < (entity.attributions?.length ?? 0); i++) {
+      const attribution = entity.attributions[i];
+      wasAttributedTo[qname(`attr:${entityId}:${i}`)] = {
+        "prov:entity": qname(entityId),
+        "prov:agent": qname(attribution.agent),
+        ...attribution.role ? { "prov:role": attribution.role } : {}
+      };
+    }
+  }
+  for (let i = 0; i < (doc.relations?.length ?? 0); i++) {
+    const relation = doc.relations[i];
+    if (relation.type === "member_of") {
+      hadMember[qname(`mem:${i}`)] = {
+        "prov:collection": qname(relation.target),
+        "prov:entity": qname(relation.source)
+      };
+    } else if (relation.type === "specialization_of") {
+      specializationOf[qname(`spec:${i}`)] = {
+        "prov:specificEntity": qname(relation.source),
+        "prov:generalEntity": qname(relation.target)
+      };
+    } else if (relation.type === "alternate_of") {
+      alternateOf[qname(`alt:${i}`)] = {
+        "prov:alternate1": qname(relation.source),
+        "prov:alternate2": qname(relation.target)
+      };
+    }
+  }
+  if (Object.keys(wasDerivedFrom).length > 0) out.wasDerivedFrom = wasDerivedFrom;
+  if (Object.keys(wasGeneratedBy).length > 0) out.wasGeneratedBy = wasGeneratedBy;
+  if (Object.keys(used).length > 0) out.used = used;
+  if (Object.keys(wasAssociatedWith).length > 0) out.wasAssociatedWith = wasAssociatedWith;
+  if (Object.keys(wasAttributedTo).length > 0) out.wasAttributedTo = wasAttributedTo;
+  if (Object.keys(hadMember).length > 0) out.hadMember = hadMember;
+  if (Object.keys(specializationOf).length > 0) out.specializationOf = specializationOf;
+  if (Object.keys(alternateOf).length > 0) out.alternateOf = alternateOf;
+  return out;
+}
+function flattenAttrs(attrs) {
+  const out = {};
+  for (const [key, value] of Object.entries(attrs ?? {})) {
+    out[key.startsWith("prov:") || key.startsWith("lineage:") ? key : qname(`attribute:${key}`)] = value;
+  }
+  return out;
+}
+
+// src/traverse.ts
+function buildForwardEdges(doc) {
+  const edges = /* @__PURE__ */ new Map();
+  for (const id of Object.keys(doc.entities)) edges.set(id, []);
+  for (const derivation of doc.derivations) {
+    if (!(derivation.output in doc.entities)) continue;
+    for (const input of derivation.inputs) {
+      if (!(input.entity in doc.entities)) continue;
+      edges.get(input.entity).push(derivation.output);
+    }
+  }
+  return edges;
+}
+function buildReverseEdges(doc) {
+  const edges = /* @__PURE__ */ new Map();
+  for (const id of Object.keys(doc.entities)) edges.set(id, []);
+  for (const derivation of doc.derivations) {
+    if (!(derivation.output in doc.entities)) continue;
+    for (const input of derivation.inputs) {
+      if (!(input.entity in doc.entities)) continue;
+      edges.get(derivation.output).push(input.entity);
+    }
+  }
+  return edges;
+}
+function topologicalEntityOrder(doc) {
+  const forward = buildForwardEdges(doc);
+  const indegree = /* @__PURE__ */ new Map();
+  for (const id of Object.keys(doc.entities)) indegree.set(id, 0);
+  for (const [, targets] of forward) {
+    for (const t of targets) {
+      indegree.set(t, (indegree.get(t) ?? 0) + 1);
+    }
+  }
+  const queue = [];
+  for (const id of Object.keys(doc.entities)) {
+    if ((indegree.get(id) ?? 0) === 0) queue.push(id);
+  }
+  const order = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    order.push(id);
+    for (const next of forward.get(id) ?? []) {
+      const nextDeg = (indegree.get(next) ?? 0) - 1;
+      indegree.set(next, nextDeg);
+      if (nextDeg === 0) queue.push(next);
+    }
+  }
+  if (order.length !== Object.keys(doc.entities).length) {
+    throw new Error("entity dependency graph contains a cycle");
+  }
+  return order;
+}
+function collectReachable(start, edges) {
+  if (!edges.has(start)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [...edges.get(start) ?? []];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    for (const next of edges.get(id) ?? []) {
+      if (!seen.has(next)) stack.push(next);
+    }
+  }
+  return [...seen];
+}
+function entityAncestors(doc, entityId) {
+  return collectReachable(entityId, buildReverseEdges(doc));
+}
+function entityDescendants(doc, entityId) {
+  return collectReachable(entityId, buildForwardEdges(doc));
+}
+
+// src/fields.ts
+function fieldPointer(entity) {
+  return entity.path ?? "";
+}
+function fieldConfidence(entity) {
+  const assertions = entity.confidence;
+  if (!assertions || assertions.length === 0) return void 0;
+  return assertions.find((assertion) => assertion.scope === "extraction") ?? assertions[0];
+}
+function dottedPathFromPointer(pointer) {
+  if (pointer === "" || pointer === "/") return "";
+  return pointer.replace(/^\//, "").split("/").map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~")).join(".");
+}
+function pointerFromDottedPath(dottedPath) {
+  if (dottedPath === "") return "";
+  return `/${dottedPath.split(".").map((segment) => segment.replaceAll("~", "~0").replaceAll("/", "~1")).join("/")}`;
+}
+function fieldEntityByPointer(doc, pointer) {
+  const matching = Object.entries(doc.entities).filter(([, entity]) => entity.path === pointer);
+  if (matching.length === 0) return void 0;
+  const matchingIds = new Set(matching.map(([id]) => id));
+  const outputId = doc.outputs.find((id) => matchingIds.has(id));
+  if (outputId) {
+    const entity = doc.entities[outputId];
+    if (entity) return { id: outputId, entity };
+  }
+  const ranked = matching.toSorted(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+  const decision = ranked.find(([, entity]) => entity.kind === "decision");
+  const chosen = decision ?? ranked[0];
+  return chosen ? { id: chosen[0], entity: chosen[1] } : void 0;
+}
+function toField(id, entity) {
+  const pointer = fieldPointer(entity);
+  const confidence = fieldConfidence(entity);
+  return {
+    id,
+    pointer,
+    dottedPath: dottedPathFromPointer(pointer),
+    value: entity.value,
+    confidence,
+    confidenceOrigin: confidence ? confidence.kind : "not_reported",
+    entity
+  };
+}
+function fields(doc) {
+  const result = [];
+  for (const id of doc.outputs) {
+    const entity = doc.entities[id];
+    if (!entity) continue;
+    if (fieldPointer(entity) === "") continue;
+    result.push(toField(id, entity));
+  }
+  return result;
+}
+function fieldTrace(doc, pointer) {
+  const field = fields(doc).find((candidate) => candidate.pointer === pointer);
+  if (!field) return void 0;
+  const ancestorIds = entityAncestors(doc, field.id);
+  const evidence = ancestorIds.filter((id) => {
+    const entity = doc.entities[id];
+    return entity?.kind === "collection" || entity?.kind === "evidence";
+  }).sort().map((id) => ({ id, entity: doc.entities[id] }));
+  const relevant = /* @__PURE__ */ new Set([field.id, ...ancestorIds]);
+  const activities = [
+    ...new Set(doc.derivations.filter((d) => relevant.has(d.output)).map((d) => d.activity))
+  ].sort();
+  return { field, evidence, activities };
+}
+
+// src/labels.ts
+function activityLabel(activity) {
+  return activity.name ?? activity.type;
+}
+export {
+  ACTIVITY_STATUSES,
+  ActivitySchema,
+  ActivityStatusSchema,
+  AgentSchema,
+  ApprovalAssertionSchema,
+  AssociationSchema,
+  AttributesSchema,
+  AttributionSchema,
+  CONFIDENCE_KINDS,
+  ConfidenceAssertionSchema,
+  ConfidenceKindSchema,
+  ConfidenceScaleSchema,
+  ConfidenceSourceSchema,
+  DERIVATION_EFFECTS,
+  DerivationEffectSchema,
+  DerivationInputSchema,
+  DerivationSchema,
+  DigestSchema,
+  ENTITY_KINDS,
+  EntityKindSchema,
+  EntitySchema,
+  ImplementationSchema,
+  JsonPointerSchema,
+  JsonValueSchema,
+  LINEAGE_FORMAT,
+  LINEAGE_PROV_NAMESPACE,
+  LineageBuilder,
+  LineageDocumentSchema,
+  LineageDocumentShapeSchema,
+  LineageFormatSchema,
+  LineageIdSchema,
+  LineageValidationError,
+  LocatorSchema,
+  MAX_DERIVATION_INPUTS,
+  RELATION_TYPES,
+  RelationSchema,
+  RelationTypeSchema,
+  SelectorSchema,
+  TimestampSchema,
+  TransformationSchema,
+  activityLabel,
+  derivationId,
+  dottedPathFromPointer,
+  entityAncestors,
+  entityDescendants,
+  fieldEntityByPointer,
+  fieldTrace,
+  fields,
+  jsonValuesEqual,
+  lineageIdToProvQualifiedName,
+  parseLineageDocument,
+  pointerFromDottedPath,
+  safeParseLineageDocument,
+  toProvJson,
+  topologicalEntityOrder,
+  validateLineageGraph
+};