Lineage

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.

Feature map

Five feature areas make up the module — two on the write path that produce the trail, three on the read path that assemble and project it. Each names the concrete modules and tables that deliver it, and the same names reappear in the code map and internals below.

System architecture

The module splits cleanly into a write path that produces the trail and a read path that assembles it. Rectangles are API routes and services, cylinders are tables and the job queue; there is no model node because assembling a trail makes zero model calls. The dotted edge is the fire-and-forget enrichment handoff.

Where the logic lives

The code map is the module boundary in file terms. Every path is real; table names are stated in the notes because tables are defined in the schema module, not in files of their own.

Primary runtime flow

The highest-value flow is the namesake read. Message labels use the operation names from the HTTP API section above.

Internals and invariants

Document catalog and write path

Every write lands through the vault: the path is normalized and jailed, the id is spliced into frontmatter, the title is re-extracted from the saved content, the body is hashed, and chunks are written synchronously in the same operation. Deletes are soft for the document and hard for its chunks and graph contribution.

• Invariant — Vault-relative paths cannot escape the vault: normalization and the path jail reject traversal at the boundary, enforced in src/server/vault/paths.ts.
• Invariant — Chunks are written in the synchronous save path, never a deferred job, so chunkCount is accurate the moment a save returns, enforced through src/server/vault/index.ts and src/server/ingest/chunking.ts.

Revision and audit capture

The revision recorder runs inside the caller's already-open save transaction: a metadata snapshot, a field-level diff against the previous revision, an optional content snapshot for diffing, and the actor and activity channel. The matching audit event is appended in the same transaction.

• Invariant — A revision is written atomically with the document mutation it records — never a partial history — enforced by recordDocumentRevision in src/server/vault/revisions.ts.
• Invariant — Revision content snapshots are bounded: bodies over 256 KB store metadata only, and oversized diffs collapse to a coarse summary, enforced in src/server/vault/revisions.ts.

Trail assembly

The assembler is deliberately boring: one workspace transaction, each sub-query filtered by workspace id on top of row-level security, deterministic ordering everywhere, and fixed caps. Plugin-contributed sections run after the core projection with a strict budget and can only append.

• Invariant — The lineage read performs no model, network, or file I/O and returns the same payload for the same document state, enforced in src/server/lineage/index.ts.
• Invariant — Contributed sections are purely additive under the src/server/plugins/limits.ts budget (three-second default, eight-second cap); a failing or overrunning plugin costs its section and sets partial, never the read, enforced in src/server/lineage/index.ts.

Origin and governance projection

Origin classification is a left join: a null source id means vault, a markdown_upload source means upload, anything else means connector, with the newest sync runs attached. Governance reads the verification column group and computes reviewOverdue from the stored due date.

• Invariant — The ACL is checked before assembly, so unknown, cross-workspace, deleted, and restricted ids are indistinguishable 404s, enforced in src/app/api/v1/documents/[id]/lineage via src/server/authz/content-acl.ts.

Derived and downstream projection

Derived knowledge rolls document mentions up to canonical heads with authority and lifecycle labels and counts live relations whose evidence cites the document. Downstream impact counts persisted assistant messages whose source registry contains the document and lists dependent semantic-cache entries with their invalidation state.

• Invariant — Derived concepts exclude deleted entities and resolve merges to canonical heads before counting, enforced by the rollup queries in src/server/lineage/index.ts.

For a self-hosting team the safe extension points are the seams the module already exposes: append a titled section to the trail with a lineageSections plugin contribution (budgeted, additive, never load-bearing), swap the vault body store in src/server/vault/storebetween filesystem and Postgres, and tune the enrichment queue's consumers. The transactional revision capture, the ACL-before-assembly rule, and the payload caps are load-bearing and not configurable.

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.