@openparser/lineage 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# @openparser/lineage
+
+## 1.0.2
+
+### Minor Changes
+
+- e7bd767: Grounded extraction now makes every output field explainable. The extraction API can return a portable `lineage@1` derivation DAG connecting values to source text, page geometry, the closest recognition confidence supplied by the OCR model, and every operation that produced them. Downstream systems can append normalization, calculation, inference, and review activities without losing the original evidence.
+
+  The new `@openparser/lineage` package provides runtime schemas, graph validation, traversal and builder helpers, and W3C PROV interoperability for using the same lineage protocol beyond document extraction. `fields()` and `fieldTrace()` return an output field, its confidence, and its supporting evidence directly, so per-field explanations do not require walking the graph.
+
+  Lineage documents stay small enough to return with every extraction. Each field points back to the passage it came from and a single confidence for that passage, without repeating the word-by-word parse that already ships beside it. A typical multi-field result is now a few kilobytes per field, so full evidence arrives with the result rather than being dropped when it grows too large.
+
+  `fields()` and `fieldTrace()` fill in the rest on demand — a field's display path, whether its confidence was reported or derived, and whether it is grounded — so consumers do not have to reconstruct those answers themselves. The document names the model behind each step and keeps the original evidence, not presentation strings.
+
+  OpenParser Studio starts new Playground sessions with field grounding, so clicking a value immediately reveals where it came from. New review endpoints, SDK helpers, and `openparser jobs review` commands let teams confirm field values, or approve or reject a whole extraction, while preserving the original machine output and an attributed event history.
+
+- e7bd767: A field's parse confidence now reflects the words that value was actually read from, instead of the worst word anywhere near it. When one sentence supplies two fields — a square footage and a street address, say — a street name the scanner struggled with used to drag the crisply scanned number down with it, and both fields reported the same low number. Each field is now scored on its own words, discounted a little when the surrounding text scanned poorly, so a value that reads cleanly reads as confident and reviewers can trust a low score to mean that particular value is worth a look.
+
+  Lineage keeps both readings, because they answer different questions. A cited region still reports how that region scanned as a whole, and each field that quotes it reports how clearly _its_ wording came through — so two fields from the same sentence can have different confidence, and reviewers are not asked to treat them as one score.
+
+  Pipelines that build their own lineage can apply the same per-field scoring instead of inventing a parallel rule.
+
+- e7bd767: Extraction review now asks a reviewer for one thing: confirm what a field should say. If the value is right, confirming it signs it off; if it is wrong, correct it in the same box and confirming records the correction and the sign-off together. There is no longer a separate approve step to remember, and no way to end up with an approval that describes a value nobody agreed to — a sign-off always names the exact value it was given.
+
+  Confirming keeps you on the field, so the confirmation you just made is there to read, and Previous and Next below it move through the queue in the order the field list shows — lowest confidence first — for working a run field by field without going back to the list between each one.
+
+  Once a field is confirmed, the card that asked for the confirmation says so plainly: it turns green, carries a tick and the number of reviewers behind the value, and names whether the value was confirmed as it stood or corrected. Revisiting a field never leaves you hunting through its history to work out whether you already signed it off.
+
+  Each confirmation survives a refresh, appears in the field's history next to what it changed, and names the person who made it and when. Several reviewers can confirm the same field and each is counted separately, so a team can require two people on anything below a confidence threshold before treating it as settled. A field shows how many reviewers stand behind its current value, and you are still asked for your own confirmation on a field a colleague has already confirmed. Confirming is not a one-way door: a reviewer can still take back an eligible confirmation.
+
+  Reviewers can take back their own most recent confirmation on a field — and only that one. Withdrawing a signature from a value someone else also confirmed leaves that value standing; withdrawing one that introduced a value restores exactly what the field said before. Neither erases anything: the withdrawal is kept in the review trail. A confirmation cannot be taken back once another value has been built on top of it, and signing the run off freezes every field until the run is reopened.
+
+  Confirmations apply to anything lineage can describe, not just output fields, so teams reviewing pages or extracted regions record sign-off the same way. A confirmation covers only what it names: confirming a field makes no claim about the region it was read from.
+
+  `openparser jobs review-update` follows the same shape: `--confirm-json` takes the `{ path, value }` entries that used to go to `--changes-json`, and a value that differs from the current one corrects the field as it signs it off.
+
+- e7bd767: Grounded extraction now records a short reason for every extracted field, explaining what in the source supports that value. Reviewers can see why the model produced each answer, not only where it came from. A reason belongs to the step that made the claim, so a field whose wording was reformatted explains the passage it read and the conversion it applied separately, each shown with the step it describes.
+- e7bd767: `@openparser/lineage` now ships the `lineage@1` format on its own, with OpenParser's own conventions in a separate profile import. The format describes what a value was derived from, by which step, under which agent — a description that should hold whoever produced the document. Two rules did not belong to it: how an OCR word's score becomes a field's score, and when cited evidence counts as sufficient. The second reads an `openparser:`-namespaced attribute, so only one producer could ever satisfy it, and a format that claims to be neutral while quietly requiring a vendor's attributes is a format you cannot adopt without adopting the vendor.
+
+  Those rules moved to `@openparser/lineage/openparser`, which also gains `fieldGrounding()` — grounded, partial, or ungrounded for a field, read off the graph rather than stored. The package root keeps the schemas, validation, traversal, builder, and PROV export, and knows nothing about OpenParser.
+
+  If you scored words or read grounding status through this package, import from `@openparser/lineage/openparser`; `fieldTrace()` still returns a field's evidence and activities, which is the part of the question the format itself can answer. If you only build or validate documents, nothing changes.
+
+- e7bd767: When a model does not copy a value straight off the page — your schema asks for a date, the contract says "20 day of May 2025", the result is `2025-05-20` — extraction still records the wording that was actually read. That read is verified by locating it in the page and discarded when it cannot be found. What the model turned the wording into is a second step, which nothing can verify, because performing that conversion mechanically is the work the model was asked to do.
+
+  Each step carries its own confidence, so a reviewer can see which half of the claim is solid. The read scores like any other verbatim match. The conversion carries the model's own reported score when the model gives one, and no score at all when it does not, because nothing measured it — a figure invented for it would be indistinguishable from the ones that mean something. What tells you a value was rewritten is the transform step being there, not a number chosen to look doubtful. One blended score would describe neither half: not that the read checked out, and not that the formatting rests on the model's word alone.
+
+  The wording is looked for first in the regions the model cited for it, so a short value that happens to appear elsewhere in the document is not treated as exactly grounded in a passage it was never read from. That holds for the quote too: wording found only outside the regions a field cites is reported as a loose match rather than a verified read of them.
+
+  A rewrite is recognised by the value differing from the verified wording, not by the value failing to resemble it. A currency amount rendered as a plain number, a name recased, a figure with its thousands separators dropped — these still resemble the text they came from, and each is now a read plus a conversion with its own account, where previously it was presented as a direct read and the model's explanation of the conversion was dropped.
+
+  In practice a reformatted value is no longer uniformly doubtful. You can highlight the exact passage a date came from at full confidence and still route the conversion to a human, and a consumer that scores a field by the weakest step in its history now gets the read's score — a true statement about the wording on the page — with the unverifiable step declaring itself in the trace rather than dragging that number down by a fixed amount.
+
+  The two steps are also explained separately. Extraction now asks the model for two accounts instead of one: why the quote it picked is the right passage, and — only when the value is not that quote as written — a bounded structured claim about how the quote became the value. Both appear in the grounding output, as `reason` and `transform_claim`, and a rewritten field's trace no longer explains a conversion in the step that merely read the page. Reviewers can accept the citation and question the formatting, which was previously one sentence covering both.
+
+  A rewritten field's trace therefore has two steps in the graph and one request on the wire: the verified wording from the page, then a transform attributed to the same model call that did the extraction. Values that appear in the document as written are a single extraction.
+
+- e7bd767: Signing a whole run off is now unmistakable and reversible. An approved run reads as approved at a glance — the card turns green and carries the decision — and a rejected one turns red, so nobody has to hunt through a field trace to find out where a run stands. The job list and each job's own page show the same verdict, so a reviewer can see which runs are settled and which still need someone before opening any of them.
+
+  Job rows also stopped shouting the obvious. A finished job no longer wears a "succeeded" badge that looks just like an approval; instead the row's icon carries where the job is — spinning while it runs, waiting while it is queued — and a failure tints the whole row red. That leaves green and red on a job row meaning what a person decided, not a second copy of what the machine did.
+
+  A sign-off is no longer a one-way door. The reviewer who approved or rejected a run can reopen it, which returns the run to pending and unfreezes its fields for another pass — useful when a correction arrives after sign-off, or when the wrong button was clicked. Only the reviewer who signed the run off can reopen it, so one person cannot quietly undo another's decision.
+
+  Reopening hides nothing. Both the sign-off and the reopening stay in the review trail, attributed and timestamped, and the run's lineage reflects the decision that currently stands rather than every decision ever made. An auditor can still see that a run was approved on Tuesday, reopened on Wednesday, and rejected on Thursday.
+
+  `POST /jobs/{id}/review/reopen` exposes this to API, SDK, and CLI callers, and both `GET /jobs` and `GET /jobs/{id}` now report `review_status`, omitting it entirely for jobs nobody has reviewed. `GET /jobs/{id}` also reports `completed_at`, so clients can measure processing time without later review activity changing it. `openparser jobs review-reopen` does the same from the command line.
+
+  Reformatted values now carry confidence that says what was actually checked. OpenParser gives a transform full confidence only when a declared transform plan permits a versioned validator and that validator proves its narrow claim. Date/time formatting, exact decimal and unit conversions, quantity magnitudes, currency policies, aliases, and controlled text normalization can be checked without another model call. Otherwise the structured transform claim keeps the extraction model's coarse `low`, `medium`, or `high` assessment visibly reported and uncalibrated, and confidence stays unknown when nobody measured the rewrite.
+
+- e7bd767: A correction made during extraction review is now visible at a glance. The reviewed output is what the field list and the JSON view show, so a corrected field no longer displays the value the model first produced, and a small pencil beside its name says a person changed it — hover the pencil to read that edit without leaving the list. Confidence badges now take their colour from sign-off rather than from the score, so a confirmed field wears the same green a confident one does while still reporting what the extraction scored.
+
+  Opening a corrected field shows the edit itself, character by character: the wording that was removed struck through in red, what replaced it in green. A single-letter fix in a street name is now as obvious as a rewritten sentence. When a value was replaced outright rather than touched up, the original and the correction are shown in full instead of an unreadable letter-by-letter comparison.
+
+  Each field's trace reads as one story again. A confirmation appears as a single review step naming the person who made it and when, in place of two near-identical entries, and each step shows the change that step made — so a field corrected twice reports what each pass did rather than only where it ended up. Confirming a value without changing it is a review step too — it names the person and the time, and shows no value, because nothing about the value changed. So a field several people signed off on says who they were, and the value extraction originally produced stays on that field's Output step.
+
+  Several corrections made by the same person in one sitting read as one step showing the net change, with the individual passes a click away, so settling on a value no longer buries the rest of the trace. A sitting that ends where it started reports no change at all.
+
+  The confirmation a reviewer is about to make now reads as the last step in the field's story, in the same card style as the steps above it, and stays fixed to the bottom of the panel — so a field with a long history no longer pushes the only thing there is to do out of sight. Once you have confirmed a field, that card says so and offers to withdraw it, which is the one place withdrawal is offered rather than something repeated in the history above.
+
+### Patch Changes
+
+- e7bd767: The first stage of the pipeline is now called Parse everywhere it is named, replacing the mix of "OCR" and "parse" in labels, option descriptions, and lineage step names. Model names keep their own spelling, so a route such as Mistral OCR 4 still appears exactly as its vendor calls it. Option keys, request and response fields, and model ids are unchanged, so nothing needs updating in existing integrations.
+
+## 1.0.1
+
+### Patch Changes
+
+- Initial public release of `lineage@1`: Zod schemas, strict DAG validation,
+  traversal helpers, `LineageBuilder`, and W3C PROV-JSON mapping.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may accept and charge a
+      fee for, or grant any of the foregoing rights, accept support,
+      warranty, indemnity, or other liability obligations and/or rights
+      consistent with this License. However, in accepting such obligations,
+      You may act only on Your own behalf and on Your sole responsibility,
+      not on behalf of any other Contributor, and only if You agree to
+      indemnify, defend, and hold each Contributor harmless for any
+      liability incurred by, or claims asserted against, such Contributor
+      by reason of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Eigenpal
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,211 @@
+# @openparser/lineage
+
+Zod schemas, TypeScript types, strict validation, traversal helpers, and a small
+builder for **`lineage@1`** — a complete, developer-friendly data-derivation DAG.
+
+The format records _what was produced from what, by which process, under which
+agents_, with optional confidence and semantic relations. Semantics are grounded
+in [W3C PROV-DM](https://www.w3.org/TR/prov-dm/) while the JSON stays ergonomic
+for application code.
+
+[OpenParser](https://openparser.dev) · [Docs](https://docs.openparser.dev)
+
+## Install
+
+```bash
+npm install @openparser/lineage
+```
+
+Import schemas and helpers from the package root:
+
+```ts
+import {
+  LINEAGE_FORMAT,
+  LineageBuilder,
+  parseLineageDocument,
+  topologicalEntityOrder,
+  toProvJson,
+  type LineageDocument,
+} from '@openparser/lineage';
+```
+
+The package also ships the Draft 2020-12 JSON Schema at
+`@openparser/lineage/schema.json`, with canonical id
+`https://docs.openparser.dev/schemas/lineage/v1/schema.json`. JSON Schema validates
+the wire shape. `parseLineageDocument` additionally enforces reference
+resolution, unique producers, and acyclicity.
+
+The package root is `lineage@1` and only `lineage@1`. Rules that read a
+namespaced attribute, or that decide what a named confidence method computes,
+belong to a profile and ship separately — OpenParser's own live at
+`@openparser/lineage/openparser`. Producers other than OpenParser use the root
+and need none of it.
+
+## Why `lineage@1`
+
+Many systems need a portable record of how values, files, evidence, and
+decisions were derived — not only “this job ran,” but the full dependency graph
+of intermediate results. `lineage@1` is that graph:
+
+| Concept        | Role                                                                    |
+| -------------- | ----------------------------------------------------------------------- |
+| **Entity**     | A value, artifact, evidence item, decision, or collection               |
+| **Activity**   | A process that used and/or generated entities                           |
+| **Agent**      | A person, organization, or software actor                               |
+| **Derivation** | Output-centric edge: one activity produced one output from typed inputs |
+| **Relation**   | `member_of`, `specialization_of`, `alternate_of` outside the DAG        |
+| **Outputs**    | Which entities are primary results of the document                      |
+
+Derivations are **output-centric**: each derived entity has at most one producer.
+Inputs carry optional roles and a `direct` / `indirect` effect flag. Activities
+use an open `type` string so profiles can name domain operations without a
+format bump.
+
+Append operations preserve existing entities, activities, agents, derivations,
+and relations. `outputs` is the current result projection, so an application can
+replace that list when a newer derived value becomes its returned result.
+
+Entity `path` values are
+[RFC 6901 JSON Pointers](https://www.rfc-editor.org/rfc/rfc6901). A pointer
+identifies one exact value; use JSONPath separately when you need a query that
+can match several values.
+
+## Example
+
+```ts
+import { LineageBuilder, toProvJson } from '@openparser/lineage';
+
+const doc = new LineageBuilder()
+  .withId('invoice-extract-1')
+  .agent('model', { type: 'software', name: 'extractor@2' })
+  .entity('pdf', {
+    kind: 'artifact',
+    name: 'invoice.pdf',
+    locator: { uri: 's3://bucket/invoice.pdf', mediaType: 'application/pdf' },
+    digest: { algorithm: 'sha256', value: '…' },
+  })
+  .entity('total', {
+    kind: 'value',
+    path: '/total',
+    value: 42.5,
+    confidence: [
+      {
+        score: 0.97,
+        scale: { min: 0, max: 1 },
+        kind: 'reported',
+        scope: 'extraction',
+        calibrated: false,
+      },
+    ],
+  })
+  .activity('extract', {
+    type: 'ai.extract',
+    status: 'ended',
+    startedAt: '2024-06-01T12:00:00.000Z',
+    endedAt: '2024-06-01T12:00:02.000Z',
+    associations: [{ agent: 'model', role: 'executor' }],
+    parameters: { fields: ['total'] },
+  })
+  .derive({
+    id: 'd-total',
+    output: 'total',
+    activity: 'extract',
+    inputs: [{ entity: 'pdf', role: 'document', effect: 'direct' }],
+  })
+  .withOutputs('total')
+  .build();
+
+const prov = toProvJson(doc);
+```
+
+## Complete DAG semantics
+
+A document is valid only when the graph is coherent:
+
+- IDs are globally distinct across entities, activities, agents, and derivations
+- Every reference resolves (derivation I/O, associations, attributions, confidence sources, outputs, relations)
+- Derivation IDs and derived outputs are unique — **one producer per derived output**
+- An output cannot appear as its own input
+- `member_of` targets must be `collection` entities
+- The entity dependency graph induced by derivations is **acyclic**
+- Activity timestamps must be RFC 3339 (offset required); `endedAt` must not precede `startedAt`
+
+`parseLineageDocument` and `LineageBuilder.build()` enforce these rules.
+Traversal helpers (`topologicalEntityOrder`, `entityAncestors`,
+`entityDescendants`) operate on the validated derivation DAG.
+
+## Confidence
+
+Confidence is a first-class assertion, not a naked float:
+
+- `score` plus an explicit numeric `scale` (`min` / `max`) — **not** forced to 0..1, so original provider scales remain representable
+- `kind`: `reported` | `derived` | `assessed`
+- `scope`, optional `granularity`, `calibrated` flag
+- optional typed `sources` (entity, activity, or agent refs), `method`, and `sampleCount`
+
+Uncalibrated scores from different scopes or producers must not be treated as
+interchangeable probabilities.
+
+## Extension and profiles
+
+`profiles` lists URIs or short names that declare additional vocabulary for
+activity types, selector types, attribute keys, and entity conventions. The core
+format stays stable; profiles layer domain meaning.
+
+Derivation inputs reuse OpenLineage's `direct` / `indirect` distinction, and its
+transformation vocabulary reads well in `Transformation.type`: `identity`,
+`transformation`, `aggregation`, `join`, `group_by`, `filter`,
+`sort`, `window`, and `conditional`. `Transformation.type` remains extensible
+for domain profiles, and `masking` records whether an operation obscured its
+input.
+
+OpenParser extraction lineage uses
+`https://docs.openparser.dev/lineage/openparser` to
+identify its document-region selectors and extraction conventions.
+
+All published object schemas are **strict**. Incompatible shape changes require a
+new `format` revision (`lineage@2`, …).
+
+## W3C PROV mapping
+
+`toProvJson` projects a validated document into [PROV-JSON](https://www.w3.org/Submission/2013/SUBM-prov-json-20130424/)
+structures:
+
+| lineage@1                            | PROV-JSON                          |
+| ------------------------------------ | ---------------------------------- |
+| entities / activities / agents       | `entity` / `activity` / `agent`    |
+| derivation (per input)               | `wasDerivedFrom`                   |
+| derivation output ← activity         | `wasGeneratedBy`                   |
+| derivation input ← activity          | `used`                             |
+| activity associations                | `wasAssociatedWith`                |
+| entity attributions                  | `wasAttributedTo`                  |
+| `member_of`                          | `hadMember`                        |
+| `specialization_of` / `alternate_of` | `specializationOf` / `alternateOf` |
+
+Arbitrary lineage ids are deterministically encoded as qualified names in the
+declared `lineage` namespace. Entity, activity, and agent records retain their
+original id in `lineage:id`.
+
+**Status note:** PROV-JSON is a W3C _Member Submission_. The underlying data model,
+[PROV-DM](https://www.w3.org/TR/prov-dm/), is a W3C _Recommendation_. This package
+uses PROV-JSON as an interchange projection while treating PROV-DM as the
+semantic reference.
+
+## Complementary systems
+
+`lineage@1` records **complete data derivation**. That complements, rather than
+replaces:
+
+- **[OpenLineage](https://openlineage.io/)** — job/run and dataset facet events for
+  data-platform observability; map runs to activities and datasets to entities
+  when you need operational event streams alongside a closed derivation DAG.
+- **[OpenTelemetry](https://opentelemetry.io/)** — distributed traces, metrics, and
+  logs for runtime performance and debugging; span/trace ids can sit in activity
+  `attributes` without conflating telemetry with provenance.
+
+Use those systems for where/when work ran in a fleet; use `lineage@1` for what
+each datum depended on.
+
+## License
+
+[Apache-2.0](./LICENSE)

package/dist/activity.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+/** How an agent relates to an activity (PROV wasAssociatedWith). */
+export declare const AssociationSchema: z.ZodObject<{
+    agent: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type Association = z.infer<typeof AssociationSchema>;
+export declare const ACTIVITY_STATUSES: readonly ["scheduled", "started", "ended", "failed", "cancelled"];
+export declare const ActivityStatusSchema: z.ZodEnum<{
+    scheduled: "scheduled";
+    started: "started";
+    ended: "ended";
+    failed: "failed";
+    cancelled: "cancelled";
+}>;
+export type ActivityStatus = z.infer<typeof ActivityStatusSchema>;
+/**
+ * Optional description of the concrete implementation that performed an
+ * activity (library, model, service, script, binary, …).
+ */
+export declare const ImplementationSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    uri: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type Implementation = z.infer<typeof ImplementationSchema>;
+/**
+ * A process that used and/or generated entities. `type` is an open string so
+ * profiles can introduce domain-specific activity types without a format bump.
+ *
+ * Map keys in `LineageDocument.activities` are the authoritative activity ids.
+ */
+export declare const ActivitySchema: z.ZodObject<{
+    type: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        scheduled: "scheduled";
+        started: "started";
+        ended: "ended";
+        failed: "failed";
+        cancelled: "cancelled";
+    }>>;
+    startedAt: z.ZodOptional<z.ZodISODateTime>;
+    endedAt: z.ZodOptional<z.ZodISODateTime>;
+    implementation: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        uri: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    }, z.core.$strict>>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    associations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agent: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        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 Activity = z.infer<typeof ActivitySchema>;
+/**
+ * An agent (person, organization, software, service) that acts or is
+ * attributed. Map keys in `LineageDocument.agents` are the authoritative ids.
+ */
+export declare const AgentSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type Agent = z.infer<typeof AgentSchema>;
+//# sourceMappingURL=activity.d.ts.map

package/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,oEAAoE;AACpE,eAAO,MAAM,iBAAiB;;;;kBAMnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,iBAAiB,mEAAoE,CAAC;AACnG,eAAO,MAAM,oBAAoB;;;;;;EAA4B,CAAC;AAC9D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;kBAQtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;kBAYhB,CAAC;AACZ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;kBAMb,CAAC;AACZ,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/approval.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/**
+ * Who currently stands behind this entity's value.
+ *
+ * An assertion names an agent and a time; it does not change the entity.
+ * OpenParser extraction review projects this from confirmations rather than
+ * storing a separate approve event: an actor counts when their newest live
+ * confirmation on this path names the value this entity holds. Confirming a
+ * matching value adds standing without minting a new entity; confirming a
+ * different value mints a new entity, and standing on the predecessor is left
+ * behind. That is why a sign-off never describes a value nobody confirmed.
+ *
+ * Standing is per entity and does not propagate. Confirming a field says
+ * nothing about the region it was read from — that region carries its own
+ * standing if someone confirms it.
+ */
+export declare const ApprovalAssertionSchema: z.ZodObject<{
+    agent: z.ZodString;
+    at: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type ApprovalAssertion = z.infer<typeof ApprovalAssertionSchema>;
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB;;;;;kBAQzB,CAAC;AACZ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}