@openparser/lineage 1.0.2

package/dist/builder.d.ts

@@ -0,0 +1,48 @@
+import type { Activity, Agent } from './activity.js';
+import type { ConfidenceAssertion } from './confidence.js';
+import { type Derivation, type DerivationInput, type Transformation } from './derivation.js';
+import type { LineageDocument } from './document.js';
+import type { Entity } from './entity.js';
+import type { Relation } from './relation.js';
+type EntityInput = Entity;
+type ActivityInput = Activity;
+type AgentInput = Agent;
+/**
+ * Ergonomic builder for `lineage@1` documents. Validates on {@link build}.
+ */
+export declare class LineageBuilder {
+    private id?;
+    private profiles?;
+    private readonly entities;
+    private readonly activities;
+    private readonly agents;
+    private readonly derivations;
+    private relations?;
+    private outputs;
+    private attributes?;
+    withId(id: string): this;
+    withProfiles(...profiles: string[]): this;
+    withAttributes(attributes: NonNullable<LineageDocument['attributes']>): this;
+    entity(id: string, entity: EntityInput): this;
+    activity(id: string, activity: ActivityInput): this;
+    agent(id: string, agent: AgentInput): this;
+    /**
+     * Record that `activityId` produced `outputId` from `inputs`.
+     */
+    derive(args: {
+        /** Optional, as in the wire format: the output already identifies it. */
+        id?: string;
+        output: string;
+        activity: string;
+        inputs?: Array<DerivationInput | string>;
+        transformation?: Transformation;
+        confidence?: ConfidenceAssertion;
+        attributes?: Derivation['attributes'];
+    }): this;
+    relation(relation: Relation): this;
+    withOutputs(...entityIds: string[]): this;
+    /** Assemble and strictly validate the document. */
+    build(): LineageDocument;
+}
+export {};
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EAEpB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,KAAK,WAAW,GAAG,MAAM,CAAC;AAC1B,KAAK,aAAa,GAAG,QAAQ,CAAC;AAC9B,KAAK,UAAU,GAAG,KAAK,CAAC;AAExB;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,EAAE,CAAC,CAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,UAAU,CAAC,CAAgC;IAEnD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxB,YAAY,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI;IAKzC,cAAc,CAAC,UAAU,EAAE,WAAW,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC,GAAG,IAAI;IAK5E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAQ7C,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAQnD,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAQ1C;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE;QACX,yEAAyE;QACzE,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,KAAK,CAAC,eAAe,GAAG,MAAM,CAAC,CAAC;QACzC,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,UAAU,CAAC,EAAE,mBAAmB,CAAC;QACjC,UAAU,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;KACvC,GAAG,IAAI;IAoBR,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAKlC,WAAW,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAKzC,mDAAmD;IACnD,KAAK,IAAI,eAAe;CAczB"}

package/dist/common.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+/** Non-empty identifier used as a map key or cross-reference. */
+export declare const LineageIdSchema: z.ZodString;
+export type LineageId = z.infer<typeof LineageIdSchema>;
+/** JSON-safe attribute bags and free-form parameter objects. */
+export declare const JsonValueSchema: z.ZodJSONSchema;
+export type JsonValue = z.infer<typeof JsonValueSchema>;
+export declare const AttributesSchema: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+export type Attributes = z.infer<typeof AttributesSchema>;
+/**
+ * Structural equality for JSON values: whether two values say the same thing.
+ * Object key order is not part of what a JSON value says, so it is normalised
+ * away rather than compared.
+ */
+export declare function jsonValuesEqual(left: JsonValue, right: JsonValue): boolean;
+/**
+ * RFC 6901 JSON Pointer. The empty string addresses the whole document.
+ * JSONPath is useful for queries, but pointers give lineage entities one
+ * unambiguous location.
+ */
+export declare const JsonPointerSchema: z.ZodString;
+export type JsonPointer = z.infer<typeof JsonPointerSchema>;
+/** Wire format tag for this package. */
+export declare const LINEAGE_FORMAT: "lineage@1";
+export declare const LineageFormatSchema: z.ZodLiteral<"lineage@1">;
+export type LineageFormat = z.infer<typeof LineageFormatSchema>;
+/**
+ * RFC 3339 timestamp string. Offset is required (`Z` or `±HH:mm`). Calendar
+ * dates that are not real days are rejected rather than rolled over.
+ * Start/end ordering is enforced at the document graph level.
+ */
+export declare const TimestampSchema: z.ZodISODateTime;
+export type Timestamp = z.infer<typeof TimestampSchema>;
+//# sourceMappingURL=common.d.ts.map

package/dist/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iEAAiE;AACjE,eAAO,MAAM,eAAe,aAAoC,CAAC;AACjE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,eAAe,iBAAW,CAAC;AACxC,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,gBAAgB,2CAA+C,CAAC;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAK1E;AAYD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,aAGgD,CAAC;AAC/E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,wCAAwC;AACxC,eAAO,MAAM,cAAc,EAAG,WAAoB,CAAC;AACnD,eAAO,MAAM,mBAAmB,2BAA4B,CAAC;AAC7D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,eAAe,kBAA2C,CAAC;AACxE,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/confidence.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+/**
+ * Explicit numeric scale for a confidence score.
+ *
+ * Scores are not forced into 0..1 so original provider scales remain
+ * representable without lossy normalization.
+ */
+export declare const ConfidenceScaleSchema: z.ZodObject<{
+    min: z.ZodNumber;
+    max: z.ZodNumber;
+}, z.core.$strict>;
+export type ConfidenceScale = z.infer<typeof ConfidenceScaleSchema>;
+export declare const CONFIDENCE_KINDS: readonly ["reported", "derived", "assessed"];
+export declare const ConfidenceKindSchema: z.ZodEnum<{
+    reported: "reported";
+    derived: "derived";
+    assessed: "assessed";
+}>;
+export type ConfidenceKind = z.infer<typeof ConfidenceKindSchema>;
+export declare const ConfidenceSourceSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        agent: "agent";
+        entity: "entity";
+        activity: "activity";
+    }>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export type ConfidenceSource = z.infer<typeof ConfidenceSourceSchema>;
+/**
+ * Generic confidence assertion attached to entities, derivations, or other
+ * statements. `score` must lie within `scale`; comparison across uncalibrated
+ * assertions is not implied.
+ */
+export declare const ConfidenceAssertionSchema: z.ZodObject<{
+    score: z.ZodNumber;
+    scale: z.ZodObject<{
+        min: z.ZodNumber;
+        max: z.ZodNumber;
+    }, z.core.$strict>;
+    kind: z.ZodEnum<{
+        reported: "reported";
+        derived: "derived";
+        assessed: "assessed";
+    }>;
+    scope: z.ZodString;
+    granularity: z.ZodOptional<z.ZodString>;
+    calibrated: z.ZodDefault<z.ZodBoolean>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            agent: "agent";
+            entity: "entity";
+            activity: "activity";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>>>;
+    method: z.ZodOptional<z.ZodString>;
+    sampleCount: z.ZodOptional<z.ZodNumber>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type ConfidenceAssertion = z.infer<typeof ConfidenceAssertionSchema>;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidence.d.ts","sourceRoot":"","sources":["../src/confidence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;kBAc9B,CAAC;AACL,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,gBAAgB,8CAA+C,CAAC;AAC7E,eAAO,MAAM,oBAAoB;;;;EAA2B,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,sBAAsB;;;;;;;kBAKxB,CAAC;AACZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;kBA2BlC,CAAC;AACL,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/derivation.d.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+export declare const DERIVATION_EFFECTS: readonly ["direct", "indirect"];
+export declare const MAX_DERIVATION_INPUTS = 1024;
+export declare const DerivationEffectSchema: z.ZodEnum<{
+    direct: "direct";
+    indirect: "indirect";
+}>;
+export type DerivationEffect = z.infer<typeof DerivationEffectSchema>;
+/**
+ * An input entity reference on a derivation, with optional role and whether
+ * the influence on the output is direct or indirect (PROV: Revision /
+ * Quotation / PrimarySource style distinctions are profile-level; here we
+ * keep the general direct/indirect effect flag).
+ *
+ * `confidence` measures this input's contribution to this one output, which is
+ * not the same statement as the input entity's own confidence. A shared source
+ * region is read once but cited by several outputs, and each output may draw on
+ * a different, differently legible part of it — so how well one output was
+ * recognized in that region belongs on the edge, not on the region.
+ */
+export declare const DerivationInputSchema: z.ZodObject<{
+    entity: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+    effect: z.ZodDefault<z.ZodEnum<{
+        direct: "direct";
+        indirect: "indirect";
+    }>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        score: z.ZodNumber;
+        scale: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strict>;
+        kind: z.ZodEnum<{
+            reported: "reported";
+            derived: "derived";
+            assessed: "assessed";
+        }>;
+        scope: z.ZodString;
+        granularity: z.ZodOptional<z.ZodString>;
+        calibrated: z.ZodDefault<z.ZodBoolean>;
+        sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                agent: "agent";
+                entity: "entity";
+                activity: "activity";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>>;
+        method: z.ZodOptional<z.ZodString>;
+        sampleCount: z.ZodOptional<z.ZodNumber>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type DerivationInput = z.infer<typeof DerivationInputSchema>;
+/**
+ * Optional descriptor of how inputs were transformed into the output.
+ *
+ * `type` is an open string. OpenLineage's column-lineage vocabulary —
+ * `identity`, `transformation`, `aggregation`, `join`, `group_by`, `filter`,
+ * `sort`, `window`, `conditional` — reads well here, and profiles may use their
+ * own namespaced values instead.
+ */
+export declare const TransformationSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    expression: z.ZodOptional<z.ZodString>;
+    masking: z.ZodOptional<z.ZodBoolean>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type Transformation = z.infer<typeof TransformationSchema>;
+/**
+ * Output-centric derivation: one activity produced exactly one output entity
+ * from zero or more typed inputs. A derived entity has at most one producer
+ * derivation in a document (enforced by graph validation).
+ *
+ * `output` already identifies the derivation uniquely, so `id` is optional and
+ * normally omitted — use {@link derivationId} to resolve one. Producers with
+ * their own stable identifiers may still set it.
+ */
+export declare const DerivationSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    output: z.ZodString;
+    activity: z.ZodString;
+    inputs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        entity: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        effect: z.ZodDefault<z.ZodEnum<{
+            direct: "direct";
+            indirect: "indirect";
+        }>>;
+        confidence: z.ZodOptional<z.ZodObject<{
+            score: z.ZodNumber;
+            scale: z.ZodObject<{
+                min: z.ZodNumber;
+                max: z.ZodNumber;
+            }, z.core.$strict>;
+            kind: z.ZodEnum<{
+                reported: "reported";
+                derived: "derived";
+                assessed: "assessed";
+            }>;
+            scope: z.ZodString;
+            granularity: z.ZodOptional<z.ZodString>;
+            calibrated: z.ZodDefault<z.ZodBoolean>;
+            sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodEnum<{
+                    agent: "agent";
+                    entity: "entity";
+                    activity: "activity";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strict>>>;
+            method: z.ZodOptional<z.ZodString>;
+            sampleCount: z.ZodOptional<z.ZodNumber>;
+            attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        }, z.core.$strict>>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>>;
+    transformation: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        expression: z.ZodOptional<z.ZodString>;
+        masking: z.ZodOptional<z.ZodBoolean>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    confidence: z.ZodOptional<z.ZodObject<{
+        score: z.ZodNumber;
+        scale: z.ZodObject<{
+            min: z.ZodNumber;
+            max: z.ZodNumber;
+        }, z.core.$strict>;
+        kind: z.ZodEnum<{
+            reported: "reported";
+            derived: "derived";
+            assessed: "assessed";
+        }>;
+        scope: z.ZodString;
+        granularity: z.ZodOptional<z.ZodString>;
+        calibrated: z.ZodDefault<z.ZodBoolean>;
+        sources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            type: z.ZodEnum<{
+                agent: "agent";
+                entity: "entity";
+                activity: "activity";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>>>;
+        method: z.ZodOptional<z.ZodString>;
+        sampleCount: z.ZodOptional<z.ZodNumber>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type Derivation = z.infer<typeof DerivationSchema>;
+/**
+ * Stable identifier for a derivation: its explicit `id` when the producer set
+ * one, otherwise `derivation:<output>`. Because one derivation produces one
+ * output, that fallback is unique within a document.
+ */
+export declare function derivationId(derivation: Pick<Derivation, 'id' | 'output'>): string;
+//# sourceMappingURL=derivation.d.ts.map

package/dist/derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../src/derivation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,kBAAkB,iCAAkC,CAAC;AAClE,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAC3C,eAAO,MAAM,sBAAsB;;;EAA6B,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQvB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;;kBAQtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAUlB,CAAC;AACZ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG,MAAM,CAElF"}