Lineage module

Lineage is the provenance-and-impact slice. It ships as one SDK entry — @eli-ai/react/documents over @eli-ai/client/documents — and one API area, /api/v1/documents. The API operation catalog files both under a single capability it labels Documents and lineage. This page is the adoption reference: what you import, what props exist, what the endpoints actually return, and which tables move. For the conceptual tour of the trail itself, read Data lineage.

What it does

Lineage answers one question about a document in a single read: where did it come from, what knowledge did it produce, and what breaks if it changes. The server assembles that from pure SQL aggregates — upstream origin and governance, an immutable revision summary, the document.* audit trail, the chunks and concepts the document derived, and the answers, cache entries, and live concepts that now depend on it. No model call, no network, no file I/O; deterministic ordering and bounded caps, so the same document yields the same payload every time.

The module also owns the document catalog itself — list, read, create, update, soft-delete — because that write path is what produces the trail: every save appends a revision row and an audit row inside the same transaction as the document update.

Use it standalone

1. Mint a key with kb:read

   The lineage read and both catalog reads accept kb:read. The lineage read additionally accepts the legacy runs:read grant (it is an any-of guard). Add kb:write only if you also want to create, update, or delete documents. A workspace key (eli_sk_) carries its workspace, so no X-Workspace-Id header is needed; a user key (eli_uk_) that spans several workspaces must send one.

2. Install two packages, import one module

   @eli-ai/client plus @eli-ai/contracts is enough for the headless path. Add @eli-ai/react only if you want the rendered surfaces. Contracts are imported by capability subpath, so a Lineage integration never pulls in agent, graph, or data types.

3. Read a document, then read its trail

   createDocumentsClient(transport) exposes six methods: list, get, create, update, remove, and lineage.

npm install @eli-ai/client @eli-ai/contracts

import { createEliTransport } from "@eli-ai/client/core";
import { createDocumentsClient } from "@eli-ai/client/documents";
import type { DocumentLineage } from "@eli-ai/contracts/documents";

const documents = createDocumentsClient(
  createEliTransport({
    baseUrl: "https://eli.ai",
    apiKey: () => process.env.ELI_API_KEY!,
    // Only needed for eli_uk_ keys that can reach more than one workspace.
    workspaceId: process.env.ELI_WORKSPACE_ID,
  }),
);

const page = await documents.list({ limit: 20 });          // { items, total, limit, offset }
const first = page.items[0];
if (!first) throw new Error("no documents in this workspace");

const trail: DocumentLineage = await documents.lineage(first.id);

console.log(trail.origin.kind);                 // "connector" | "vault" | "upload"
console.log(trail.governance.verification);     // "unverified" | "verified" | "certified" | "deprecated"
console.log(trail.derived.chunkCount, trail.derived.relationCount);
console.log(trail.downstream.citedByAnswers, trail.downstream.impactedEntities);

React components

@eli-ai/react/documents exports exactly two components — EliDocuments and EliDocumentLineage — plus the types EliDocumentsProps, EliDocumentLineageProps, and EliDocumentsLabels. Both are client components and both read the transport from EliProvider. Neither is re-exported from the package root, so @eli-ai/react/documents is the import path.

EliDocuments

The catalog surface. It renders a titled section containing: an optional create form (path, title, content) behind a toggle button; a filter input; a table of one row per document — title over path as a selectable button, then version, then a localized updated timestamp; and, once a row is selected, the inline lineage panel for that document. It calls GET /api/v1/documents once (query key includes limit), POST /api/v1/documents on submit, and GET /api/v1/documents/{id}/lineage for the selected row.

// packages/react/src/documents/index.tsx — DEFAULT_LABELS.
// Pass `labels` with any subset; it is spread over these.
const DEFAULT_LABELS: EliDocumentsLabels = {
  title: "Documents",
  description: "Browse source material and inspect its provenance from intake to downstream use.",
  filter: "Filter documents",
  create: "New document",
  closeCreate: "Cancel",
  path: "Path",
  documentTitle: "Title",      // create-form field AND the first table column header
  content: "Content",
  save: "Create document",
  empty: "No documents yet",
  emptyDescription: "Create a document or sync a content connector to begin.",
  lineage: "Lineage",          // default header of <EliDocumentLineage>
  origin: "Origin",            // the four KPI tile labels
  revisions: "Revisions",
  derived: "Derived knowledge",
  downstream: "Downstream impact",
};

import { createEliTransport } from "@eli-ai/client/core";
import { EliProvider } from "@eli-ai/react/provider";
import { EliDocuments } from "@eli-ai/react/documents";
import "@eli-ai/react/styles.css";

// The injected fetch is the trust boundary: point it at a same-origin route
// that attaches the Bearer key server-side. Never ship an eli_sk_ key to a browser.
const transport = createEliTransport({ fetch: sameOriginProxyFetch });

export function DocumentCatalog({ workspaceId }: { workspaceId: string }) {
  return (
    <EliProvider transport={transport} workspaceId={workspaceId}>
      <EliDocuments
        limit={100}
        allowCreate={false}
        labels={{ title: "Source material", downstream: "Blast radius" }}
        onLineageLoaded={(lineage) => {
          console.log(lineage.origin.kind, lineage.downstream.impactedEntities);
        }}
      />
    </EliProvider>
  );
}

EliDocumentLineage

The lineage panel for one document id, in its own titled section. It renders a badge row (the verification tier, tinted as a warning when governance.reviewOverdue is true; the origin kind; the document version), four KPI tiles, and up to the first six revision items as version · change kind with a timestamp. The tiles are: Origin (origin.sourceType falling back to origin.kind, plus origin.lastSyncedAt), Revisions (revisions.total), Derived knowledge (the number of derived.entities, with chunk and relation counts underneath), and Downstream impact (downstream.citedByAnswers).

import { EliProvider } from "@eli-ai/react/provider";
import { EliDocumentLineage } from "@eli-ai/react/documents";

export function ProvenancePanel({ docId }: { docId: string }) {
  return (
    <EliProvider transport={transport}>
      <EliDocumentLineage
        documentId={docId}
        title="Provenance"
        errorLabel="We could not load this document's trail."
        onLoaded={(lineage) => {
          if (lineage.governance.reviewOverdue) flagForReview(lineage.document.id);
        }}
      />
    </EliProvider>
  );
}

HTTP API

Six operations, all under /api/v1/documents. The workspace is resolved from the bearer key and never appears in the URL or the body. Every failure uses the shared envelope { error, message } — plus issues on body-validation failures — so a consumer can branch on error. Codes you will actually see here: unauthorized (401), insufficient_scope and insufficient_capability (403), not_found (404), invalid_pagination, invalid_json, invalid_body, and invalid_path (400).

curl -s https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/lineage \
  -H "Authorization: Bearer $ELI_KEY" \
  | jq '{origin: .origin.kind, revisions: .revisions.total, citedBy: .downstream.citedByAnswers}'

{
  "document": {
    "id": "01KY10AAAAAAAAAAAAAAAAAAAA",
    "path": "ops/order-platform-runbook.md",
    "title": "Order Platform incident runbook",
    "version": 4,
    "contentHash": "9f2b1c…",
    "createdAt": "2026-06-02T14:20:00.000Z",
    "updatedAt": "2026-07-18T09:05:00.000Z",
    "createdBy": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
    "updatedBy": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z"
  },
  "governance": {
    "verification": "certified",
    "verifiedBy": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
    "verifiedAt": "2026-07-01T00:00:00.000Z",
    "nextVerifyAt": "2026-12-28T00:00:00.000Z",
    "reviewOverdue": false
  },
  "origin": {
    "kind": "connector",
    "sourceId": "01KY0V000CONNECTOR00000001",
    "sourceType": "confluence",
    "externalId": "CONF-88213",
    "sourceVersion": "17",
    "lastSyncedAt": "2026-07-18T09:00:00.000Z",
    "recentSyncRuns": [
      { "id": "01KY18…", "kind": "incremental", "startedAt": "2026-07-18T09:00:00.000Z", "finishedAt": "2026-07-18T09:00:12.000Z", "error": null }
    ]
  },
  "revisions": {
    "total": 4,
    "items": [
      {
        "id": "01KY17…", "version": 4, "changeKind": "update",
        "changedFields": ["contentHash", "title"],
        "hasContent": true, "activity": "api",
        "changedBy": "usr_01KY0Z9M…", "note": null,
        "createdAt": "2026-07-18T09:05:00.000Z"
      }
    ]
  },
  "audit": [
    { "event": "document.verify", "actor": "usr_01KY0Z9M…", "at": "2026-07-01T00:00:00.000Z", "meta": { "from": "verified", "to": "certified" } },
    { "event": "document.update", "actor": "usr_01KY0Z9M…", "at": "2026-07-18T09:05:00.000Z", "meta": { "path": "ops/order-platform-runbook.md" } }
  ],
  "derived": {
    "chunkCount": 12,
    "entities": [
      { "id": "01KY0ZW3…", "name": "Order Platform", "type": "system", "authority": "certified", "lifecycleStatus": "published", "mentionCount": 9 }
    ],
    "relationCount": 5
  },
  "downstream": {
    "citedByAnswers": 14,
    "cachedAnswers": [
      { "entryId": "01KY19…", "question": "how do we handle stuck orders?", "invalidated": false }
    ],
    "impactedEntities": 7
  }
}

curl -s "https://eli.ai/api/v1/documents?limit=2&offset=0" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "items": [
    {
      "id": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "path": "ops/order-platform-runbook.md",
      "title": "Order Platform incident runbook",
      "contentHash": "9f2b1c…",
      "version": 4,
      "updatedAt": "2026-07-18T09:05:00.000Z"
    }
  ],
  "total": 137,
  "limit": 2,
  "offset": 0
}

curl -s https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY"

{
  "id": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "ops/order-platform-runbook.md",
  "title": "Order Platform incident runbook",
  "contentHash": "9f2b1c…",
  "version": 4,
  "updatedAt": "2026-07-18T09:05:00.000Z",
  "content": "---\nid: 01KY10AAAAAAAAAAAAAAAAAAAA\n---\n\n# Order Platform incident runbook\n…",
  "missing": false
}

curl -L -X POST https://eli.ai/api/v1/documents \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"ops/order-platform-runbook.md","title":"Order Platform incident runbook","content":"# Order Platform incident runbook\n\nRequeue stuck orders after 24h."}'

{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "ops/order-platform-runbook.md",
  "contentHash": "9f2b1c…",
  "title": "Order Platform incident runbook"
}

curl -L -X PATCH https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"# Order Platform incident runbook\n\nRequeue stuck orders after 12h."}'

{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "ops/order-platform-runbook.md",
  "contentHash": "4c81ae…",
  "title": "Order Platform incident runbook"
}

curl -L -X DELETE https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY"

{ "deleted": true, "id": "01KY10AAAAAAAAAAAAAAAAAAAA" }

One more route sits under this path prefix but belongs to a different module. The operation catalog files verifyDocument under the governance capability, and its handler requires the governance:write capability rather than the document one. It is documented here because it is the only writer of the governance block that Lineage reads back.

curl -L -X POST https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification":"certified"}'

{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "verification": "certified",
  "verifiedBy": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
  "verifiedAt": "2026-07-01T00:00:00.000Z",
  "nextVerifyAt": "2026-12-28T00:00:00.000Z"
}

Data elements

Every table below is a tenant table: it carries workspace_id as the leading index column and exactly one row-level-security policy comparing it to the workspace GUC, with FORCE ROW LEVEL SECURITY applied by companion migrations. The lineage assembler runs every one of its queries inside a workspace transaction and filters workspace_id explicitly in the SQL. There is no non-tenant table in this module.

How it composes

Lineage is the module that reads everyone else's trail. Adopted alone it works and is useful — you get identity, revisions, audit, and chunk counts for every document you write — but four of its sections are genuinely filled in by other modules, and this is what they look like without them.

• With Intake — origin becomes real provenance: kind of connector or upload, the source type, the external id, the source version, the last sync time, and the recent sync runs. Without it, kind is vault, every other origin field is null, and recentSyncRuns is empty. This one genuinely needs Intake — there is no other writer of those columns.
• With Warrant — governance carries a real tier plus reviewOverdue, and the badge in EliDocumentLineage turns amber when a review is past due. Without it, verification stays unverified and reviewOverdue is always false. Note the package-level relationship too: the documents capability declares a dependency on governance, but that is a type dependency only — the verification, authority, and lifecycle unions are imported from @eli-ai/contracts/governance. The wire read needs no governance scope.
• With Atlas — derived.entities, derived.relationCount, and downstream.impactedEntities become the real knowledge the document produced and the concepts a deprecation would touch. Without it, entities is empty and both counts are zero — chunkCount is still accurate, because chunking happens in the synchronous save path, not in extraction.
• With Lens — downstream.citedByAnswers counts persisted messages whose [Sn] source registry includes this document, and cachedAnswers lists the semantic-cache entries that depend on it. Without it, both are zero and empty: nothing has cited the document yet. This is the section that most rewards adopting Lens alongside Lineage — impact analysis is only interesting once answers exist.
• With Ports — the identical trail is exposed as the MCP tool kb_document_lineage, so an agent can trace provenance mid-run without your application brokering the call. Without it, the REST endpoint and the SDK are the surfaces.
• Conduit and Crucible — honestly, nothing. No field of DocumentLineage is populated by live-data connectors or by evals. They compose at the product level, not in this payload.