Warrant — authority, lifecycle & gated change

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.

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.