Warrant

Warrant is the module that answers who vouches for this, and who is allowed to change it. Adopt it alone if you already have concepts or documents somewhere and you need a review queue, an authority tier, an owner, and a trail you can defend.

What it does

Warrant tracks four things about a concept: its authority tier (machine_extracted → asserted → curated → certified), its lifecycle (draft, pending_review, published, deprecated, superseded), its owner and stewards, and its review clock. Destructive or schema-level edits do not happen in place: they are proposed as change requests that a reviewer approves, rejects, or that the proposer withdraws. Every accepted change appends an immutable revision carrying a full snapshot and a field-level diff. Documents get a parallel, simpler treatment — a verification stamp with a re-verify due date.

Nothing in this module calls a model. All of it is transactional database work inside a workspace transaction.

Use it standalone

1. Issue a key with the scopes Warrant actually checks

   Reads (the change-request queue, the revision trail) require kb:read. Every mutation — propose, approve, reject, withdraw, certify, review, set authority, set owner, deprecate, verify a document — requires kb:write. There is no governance:* scope; the scope taxonomy is agents:run, runs:read, kb:read, kb:write, data:read, data:run, reports:read, reports:write.

   Delegated user keys (eli_uk_…) are additionally narrowed by the owner's live workspace role: these routes name the capability governance:read or governance:write, and a 403 insufficient_capability comes back if the owner has lost it. Workspace keys (eli_sk_…) carry no role, so the capability check does not apply to them.

2. Install two packages and import one entry

   Headless: @eli-ai/client/governance. React: @eli-ai/react/governance. Neither pulls in query, agents, data, reports, connectors or evals code.

3. Call it

   The client is a thin typed wrapper over /api/v1. The transport takes an origin, a credential resolver and an optional workspace id; it makes no authorization decision of its own.

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

import { createEliTransport } from "@eli-ai/client/core";
import { createGovernanceClient } from "@eli-ai/client/governance";

const transport = createEliTransport({
  baseUrl: "https://eli.ai",
  apiKey: () => process.env.ELI_API_KEY!, // eli_sk_… or eli_uk_…
  // workspaceId is only needed for a user key that can reach several workspaces
});

const governance = createGovernanceClient(transport);

// 1 — propose a gated edit instead of writing it directly
const proposal = await governance.proposeChangeRequest({
  kind: "update",
  entityId: "01KZ40AAAAAAAAAAAAAAAAAAAA",
  payload: { description: "Recurring revenue retained from existing customers over 12 months." },
  note: "Aligning the definition with the FY26 board deck",
});

// 2 — a reviewer applies it. Approve returns the request AND the entity it landed on.
const { request, appliedEntityId } = await governance.approveChangeRequest(proposal.id, {
  note: "Matches the finance definition",
});

// 3 — the append-only trail, newest first
const { revisions } = await governance.listEntityRevisions(appliedEntityId!, { limit: 10 });
console.log(request.status, revisions[0]?.changeKind, revisions[0]?.diff);

React components

The React package exports exactly one component for this module, plus its two types. EliGovernance is a client component ("use client") that renders the open change-request queue and, optionally, a proposal form. It uses scoped eli-* class names and ships no styling of its own — import @eli-ai/react/styles.css or provide your own rules for those classes.

EliGovernance

What it renders, top to bottom:

• a titled surface with a Propose change / Cancel toggle button (only when canPropose);
• when toggled open, a form with a kind select (create, update, deprecate, supersede, delete), an Entity ID input (required for every kind except create), a Review note textarea, and a Proposed fields (JSON) textarea that must parse to a JSON object — an array, a scalar or invalid JSON is rejected inline before any request is sent;
• one card per open request: a kind badge (critical tone for delete, warning otherwise), the entity name — falling back to the entity id, then to "New concept" — the created date, the request note, the names of the keys in payload, and the proposer;
• when canReview, a per-request note input plus Approve and Reject buttons; a non-empty note is sent as the request body, an empty one is omitted;
• loading, error (with a retry button) and empty states.

It calls four operations only: listChangeRequests({ status: "open" }) on mount and after every successful mutation, proposeChangeRequest, approveChangeRequest and rejectChangeRequest. The status filter is fixed to open and is not a prop.

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

// EliProvider has no API-key prop by design. In the browser, point the transport at a
// same-origin route of your own that injects the Bearer key server-side.
const transport = createEliTransport({ fetch: sameOriginProxyFetch });

export function ReviewQueue({ workspaceId, isSteward }: { workspaceId: string; isSteward: boolean }) {
  return (
    <EliProvider transport={transport} workspaceId={workspaceId}>
      <EliGovernance
        canReview={isSteward}
        labels={{ title: "Change review", empty: "Nothing waiting on you" }}
        onRequestReviewed={(id, decision) => track("cr_reviewed", { id, decision })}
        onError={(error) => report(error)}
      />
    </EliProvider>
  );
}

HTTP API

Twelve operations. Every one authenticates with a Bearer key; the scope column below is what the route enforces, and delegated user keys additionally need the named capability. All examples use https://eli.ai with -L on non-GET calls, because the apex issues a 308 redirect that curl will not follow for a POST without it.

Change requests

curl -s https://eli.ai/api/v1/change-requests?status=open \
  -H "Authorization: Bearer $ELI_KEY"

{
  "requests": [
    {
      "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
      "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
      "kind": "update",
      "payload": { "description": "Recurring revenue retained from existing customers over 12 months." },
      "status": "open",
      "proposedBy": "usr_01H8…",
      "note": "Aligning the definition with the FY26 board deck",
      "reviewedBy": null,
      "reviewNote": null,
      "createdAt": "2026-07-21T09:00:00.000Z",
      "reviewedAt": null,
      "appliedAt": null,
      "entityName": "Net Revenue Retention"
    }
  ]
}

curl -s -L -X POST https://eli.ai/api/v1/change-requests \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "update",
    "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
    "payload": { "description": "Recurring revenue retained from existing customers over 12 months." },
    "note": "Aligning the definition with the FY26 board deck"
  }'

{
  "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
  "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
  "kind": "update",
  "payload": { "description": "Recurring revenue retained from existing customers over 12 months." },
  "status": "open",
  "proposedBy": "usr_01H8…",
  "note": "Aligning the definition with the FY26 board deck",
  "reviewedBy": null,
  "reviewNote": null,
  "createdAt": "2026-07-21T09:00:00.000Z",
  "reviewedAt": null,
  "appliedAt": null,
  "entityName": "Net Revenue Retention"
}

curl -s -L -X POST https://eli.ai/api/v1/change-requests/01KZ41BBBBBBBBBBBBBBBBBBBB/approve \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Matches the finance definition"}'

{
  "request": {
    "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
    "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
    "kind": "update",
    "payload": { "description": "Recurring revenue retained from existing customers over 12 months." },
    "status": "approved",
    "proposedBy": "usr_01H8…",
    "note": "Aligning the definition with the FY26 board deck",
    "reviewedBy": "usr_01J2…",
    "reviewNote": "Matches the finance definition",
    "createdAt": "2026-07-21T09:00:00.000Z",
    "reviewedAt": "2026-07-21T09:05:00.000Z",
    "appliedAt": "2026-07-21T09:05:00.000Z",
    "entityName": "Net Revenue Retention"
  },
  "appliedEntityId": "01KZ40AAAAAAAAAAAAAAAAAAAA"
}

curl -s -L -X POST https://eli.ai/api/v1/change-requests/01KZ41BBBBBBBBBBBBBBBBBBBB/reject \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Superseded by the ontology rework"}'

{
  "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
  "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
  "kind": "update",
  "status": "rejected",
  "reviewedBy": "usr_01J2…",
  "reviewNote": "Superseded by the ontology rework",
  "reviewedAt": "2026-07-21T09:06:00.000Z",
  "appliedAt": null,
  "entityName": "Net Revenue Retention"
}

curl -s -L -X POST https://eli.ai/api/v1/change-requests/01KZ41BBBBBBBBBBBBBBBBBBBB/withdraw \
  -H "Authorization: Bearer $ELI_KEY"

{
  "id": "01KZ41BBBBBBBBBBBBBBBBBBBB",
  "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
  "kind": "update",
  "status": "withdrawn",
  "reviewedBy": "usr_01H8…",
  "reviewNote": null,
  "reviewedAt": "2026-07-21T09:07:00.000Z",
  "appliedAt": null,
  "entityName": "Net Revenue Retention"
}

Concept authority & lifecycle

These five mutations all return the same CurationMeta object and all append a revision. They are the direct path — use them for the states a change request does not cover (authority, owner, review stamps), and use change requests for edits you want reviewed.

curl -s -L -X POST https://eli.ai/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note": "Signed off by the finance data owner"}'

{
  "authority": "certified",
  "lifecycleStatus": "published",
  "ownerId": "usr_01J2…",
  "stewardIds": ["usr_01K4…"],
  "version": 8,
  "lastReviewedAt": "2026-07-21T09:10:00.000Z",
  "nextReviewAt": "2027-01-17T09:10:00.000Z",
  "supersededBy": null,
  "sourceRefs": [{ "label": "FY26 board deck", "url": "https://example.com/fy26" }],
  "editorialNote": null
}

curl -s -L -X POST https://eli.ai/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/review \
  -H "Authorization: Bearer $ELI_KEY"

{
  "authority": "curated",
  "lifecycleStatus": "published",
  "ownerId": null,
  "stewardIds": [],
  "version": 4,
  "lastReviewedAt": "2026-07-21T09:12:00.000Z",
  "nextReviewAt": "2027-01-17T09:12:00.000Z",
  "supersededBy": null,
  "sourceRefs": [],
  "editorialNote": null
}

curl -s -L -X POST https://eli.ai/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/authority \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"authority": "curated"}'

{
  "authority": "curated",
  "lifecycleStatus": "published",
  "ownerId": "usr_01J2…",
  "stewardIds": [],
  "version": 9,
  "lastReviewedAt": "2026-07-21T09:10:00.000Z",
  "nextReviewAt": "2027-01-17T09:10:00.000Z",
  "supersededBy": null,
  "sourceRefs": [],
  "editorialNote": null
}

curl -s -L -X POST https://eli.ai/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/owner \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ownerId": "usr_01J2…", "stewardIds": ["usr_01K4…"]}'

{
  "authority": "curated",
  "lifecycleStatus": "published",
  "ownerId": "usr_01J2…",
  "stewardIds": ["usr_01K4…"],
  "version": 10,
  "lastReviewedAt": "2026-07-21T09:10:00.000Z",
  "nextReviewAt": "2027-01-17T09:10:00.000Z",
  "supersededBy": null,
  "sourceRefs": [],
  "editorialNote": null
}

curl -s -L -X POST https://eli.ai/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/deprecate \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"supersededBy": "01KZ44CCCCCCCCCCCCCCCCCCCC", "note": "Replaced by the FY26 definition"}'

{
  "authority": "curated",
  "lifecycleStatus": "superseded",
  "ownerId": "usr_01J2…",
  "stewardIds": [],
  "version": 11,
  "lastReviewedAt": "2026-07-21T09:10:00.000Z",
  "nextReviewAt": "2027-01-17T09:10:00.000Z",
  "supersededBy": "01KZ44CCCCCCCCCCCCCCCCCCCC",
  "sourceRefs": [],
  "editorialNote": null
}

Revision trail

curl -s "https://eli.ai/api/v1/entities/01KZ40AAAAAAAAAAAAAAAAAAAA/revisions?limit=2" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
  "revisions": [
    {
      "id": "01KZ45DDDDDDDDDDDDDDDDDDDD",
      "workspaceId": "ws_01H7…",
      "entityId": "01KZ40AAAAAAAAAAAAAAAAAAAA",
      "version": 8,
      "changeKind": "certify",
      "snapshot": {
        "name": "Net Revenue Retention",
        "type": "metric",
        "attrs": {},
        "authority": "certified",
        "lifecycleStatus": "published",
        "ownerId": "usr_01J2…",
        "stewardIds": ["usr_01K4…"],
        "aliases": ["NRR"],
        "sourceRefs": [],
        "supersededBy": null
      },
      "diff": { "authority": { "from": "curated", "to": "certified" } },
      "activity": null,
      "changedBy": "usr_01J2…",
      "note": "Signed off by the finance data owner",
      "createdAt": "2026-07-21T09:10:00.000Z"
    }
  ]
}

changeKind is one of create, update, review, certify, set_authority, set_owner, deprecate, supersede, delete, change_request, verify. activity records where the change came from — api for the authority and deprecate endpoints, and change_request:<id> for anything applied by an approval.

Document verification

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

{
  "docId": "01KZ50EEEEEEEEEEEEEEEEEEEE",
  "verification": "certified",
  "verifiedBy": "usr_01J2…",
  "verifiedAt": "2026-07-21T09:20:00.000Z",
  "nextVerifyAt": "2027-01-17T09:20:00.000Z"
}

Data elements

Warrant owns two tables outright, owns a column group on two more, and appends to the audit log. Every one of the five carries a workspace_id and a <table>_tenant_isolation row-level-security policy whose USING and WITH CHECK clauses both require workspace_id to equal the workspace of the current transaction. There is no cross-workspace read path: a wrong-workspace id is simply invisible, which is why several routes return 404 where you might expect 403.

Two details worth knowing before you build on these rows. First, editorial_note is steward-only: it is stored on the entity but deliberately excluded from the revision snapshot and diff, so it never travels into a history view. Second, entity_revisions.version is bumped with an atomic UPDATE … RETURNING that takes the entity row lock, so two concurrent mutations can never mint the same version number.

Feature map

Five feature areas make up the module. Each names the concrete modules and tables that deliver it, and the same names reappear in the code map and internals below, so every behavioural claim on this page is traceable to the code that enforces it.

System architecture

The module is three route groups over four services and five stores — and no model anywhere. Rectangles are API routes and services, cylinders are tables; the two append-only cylinders (entity_revisions, audit_log) are what make the trail defensible.

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 an approval, because it exercises the reviewer gate, the claim, the apply, and the trail in one call. Message labels use the operation names from the HTTP API section above.

Internals and invariants

Gated change through change requests

A proposal validates its payload against a strict per-kind schema — unknown fields are a 400, not a silent drop — and lands as an open row. Approval is claim-then-apply across transactions: the claim serializes reviewers, the apply runs through the ordinary graph writers, and the appliedAt stamp is deliberately last.

• Invariant — A change request is applied at most once: the open-to-approved claim is the lock, a failed apply reverts to open, and appliedAt is stamped only after the apply commits, enforced in src/server/graph/change-requests.ts.
• Invariant — When a concept has an owner or stewards, only those identities may approve or reject its requests (409 otherwise), enforced by the reviewer gate in src/server/graph/change-requests.ts.

Direct curation mutations

The five direct endpoints are one workspace transaction each: load the live entity, mutate the governance columns, record the revision, append the audit row. Review stamps derive their due date from the workspace review interval, which is read before the transaction opens.

• Invariant — Applied updates promote authority to at least curated and never demote a certified concept; explicit demotion exists only on the authority endpoint, enforced in src/server/graph/change-requests.ts and src/server/graph/curation.ts.
• Invariant — Only a published concept can be deprecated or superseded, and a supersession target must be live, unmerged, and published, enforced in src/server/graph/curation.ts.

Append-only revision trail

Every accepted change appends one revision carrying a full snapshot and a field-level diff against the previous one. The version number is minted with an atomic bump that takes the entity row lock, and the table deliberately has no foreign key to entities.

• Invariant — Revision rows are never updated or deleted, and two concurrent mutations can never mint the same version number, enforced by recordRevision in src/server/graph/curation.ts.
• Invariant — The steward-only editorial note is excluded from revision snapshots and diffs, so it never travels into a history view, enforced in src/server/graph/curation.ts.

Document verification

Verification is a single-row state machine on the document: verified and certified stamp who, when, and a re-verify due date; unverified and deprecated clear all three. The route applies the caller's content ACL first, so a restricted document is indistinguishable from a missing one.

• Invariant — Setting verified or certified always stamps verified_by, verified_at, and next_verify_at together, and the other two states always clear them, enforced by verifyDocument in src/server/vault/verification.ts.

Reviewer gating, audit, and access

Every route resolves the bearer key to a workspace, checks scope by exact membership, and re-checks the live capability for delegated user keys. Every mutation appends an audit event named for what happened, and all reads and writes run under row-level security.

• Invariant — Every governance mutation appends an audit_log event in the same transaction as the change it records, enforced across src/server/graph/curation.ts, src/server/graph/change-requests.ts, and src/server/vault/verification.ts.
• Invariant — A cross-workspace id is invisible rather than forbidden: tenant RLS policies on every table turn it into a 404, enforced through src/server/db/tenant.ts.

For a self-hosting team the safe extension points are observation and policy, not the state machine: attach read-only policy observers, read stale-concept and curation summaries through the plugin facade, and drive markReviewed / setAuthority / deprecateEntity through it so every change still appends the same revisions. Adjusting the review cadence is a workspace setting. The claim-then-apply protocol, the promote-only floor, and the append-only trail are load-bearing and not configurable.

How it composes

Warrant is usable on its own — the state it records is meaningful whether or not anything reads it. What follows is what each neighbour adds, and what genuinely breaks without it.

With Atlas — the concepts being governed

Atlas owns the entities row; Warrant owns its governance columns. This is the one real dependency: a change request of kind update, deprecate, supersede or delete, and every one of the five authority/lifecycle endpoints, needs a live entity to point at. Approving a create request is how you get one without touching Atlas's write API at all — the entity is created by the approval, at authority curated.

With Lens — where the state changes answers

This is where governance stops being paperwork. Retrieval's graph-fusion stage excludes entities whose lifecycle_status is draft or pending_review, so drafting a concept keeps it out of answer context. On the document side, documents.verification is a direct input to the answer policy's confidence features — ranked unverified 0, verified 1, certified 2, and deprecated −1, so a deprecated source counts against the answer — and when no cited document is verified or certified the policy raises a no_verified_source caveat. Entity authority participates too: the feature set tracks whether any detected concept is certified. Without Lens, all of this is recorded and simply not consumed.

With Lineage — the trail, assembled

entity_revisions and the audit rows are Warrant's, and GET /api/v1/entities/{id}/revisions reads them without any Lineage code. Lineage is what stitches them together with document revisions, extraction runs and citations into a single provenance view. Note that createGovernanceClient also exposes documentLineage(id), which calls GET /api/v1/documents/{id}/lineage— that endpoint is Lineage's, not Warrant's, and is documented there.

With Intake — verification on ingested content

Connector-ingested documents arrive at the default verification of unverified. Warrant's verify endpoint is the human stamp on top of that. No connector is required to use it — any document row will do.

With Crucible — the policy decision log

GET /api/v1/policy/decisions and GET /api/v1/policy/stats are guarded by the same governance:read capability as this module's reads (accepting either kb:read or runs:read), and their wire types PolicyDecision / PolicyStats live in @eli-ai/contracts/governance. Their client methods, however, are on the quality entry — createQualityClient(transport).listPolicyDecisions() — so they are documented with Crucible. Adopt Warrant alone and you still get the write-side governance state; you do not get the decision log unless you also take that entry.

With Ports — two approvals that are not the same thing

Agent runs have their own human-in-the-loop approval at POST /api/v1/runs/{id}/approve, gated on agents:run. It has no relationship to the change-request queue: different table, different scope, different lifecycle. Do not wire one to the other expecting shared state. Separately, the SKOS/PROV-O export at GET /api/v1/export/skos is reachable from createGovernanceClient(transport).exportSkos() but guards on graph:read — it is a graph export whose contents are lifecycle-shaped (published, deprecated and superseded concepts only; drafts never export).

With Conduit

No coupling. Live-data connectors and governed queries neither read nor write any Warrant table, and Warrant needs nothing from them.