Conduit

Conduit is the data module — capability area data, labelled Conduit (data) in the capability catalog. A workspace registers scoped, read-only connectors (PostgreSQL, MySQL, Snowflake) and a set of named queries: human-authored, single-statement SQL templates with typed parameters. Callers pick a query by slug and supply parameter values; they never supply SQL.

Every execution is checked against a read-only statement policy, capped by the connector's maxRows and timeoutMs, and recorded as an append-only data_calls row. The id of that row comes back as dataCallId — the anchor a [Dn] citation points at. Separately, a query can be bound to a graph entity or entity type, which is what lets other modules resolve "the current numbers for this thing" without anyone writing SQL at answer time.

Use it standalone

Conduit's public surface is three HTTP operations and one React component. Adopting it needs no documents, no knowledge graph, no embeddings, and no chat model.

React components

@eli-ai/react/data exports exactly one component, EliLiveData, plus its two label/prop types (EliLiveDataProps, EliLiveDataLabels). There is no separate connector-management or binding-editor component in the package.

EliLiveData

A single surface that loads the workspace's connectors and named queries on mount, renders the connectors as badges (the package's positive tone when enabled, neutral otherwise), and renders a form with a query select, a JSON textarea for parameters, and a submit button. Options for disabled queries render but are non-selectable, and each option is labelled title (falling back to slug) followed by its connector name when that connector is in the list. On success it renders a results table with the returned columns as headers, plus badges for rowCount, durationMs, and a "Truncated" badge when the row cap was hit. Cells that are objects or arrays are JSON-stringified; null and undefined render as an em dash.

The component issues one data:read call per list on mount and one data:run call per submit. The parameter textarea starts at {} and must parse to a JSON object: invalid JSON reports "Parameters are not valid JSON." and a JSON array or null reports "Parameters must be a JSON object." — both inline, before any request is made.

HTTP API

Three operations, all under /api/v1/data. Failures use the shared envelope { "error", "message" }; a body that fails validation adds an issues array. Because the apex 308-redirects, pass -L on the non-GET call so curl replays the POST body.

config is the non-secret connection shape for that kind: Postgres and MySQL carry host · port · database · user (plus sslMode or ssl); Snowflake carries account · database · warehouse · user (plus optional schema and role). schemaSnapshot, when present, holds the discovered tables with their columns (name · dataType · nullable) and a nullable rowEstimate.

Each entry in params declares name, a type of string | number | boolean | date, and optionally required, default, and description. Order is meaningful: the executor binds params[0] to $1, and so on.

truncated is true when the connector's maxRows cap clipped the result — the rows you received are a prefix, not the whole answer. Data-layer failures map their code to a status:

• 404 query-not-found — no query with that slug or id; connector-not-found— the query's connector row is gone.
• 409 connector-disabled — emitted when either the query or its connector has enabled: false. The message names which one.
• 400 invalid-params — a missing required param or a value that will not coerce to its declared type; not-read-only — the stored template failed the statement gate.
• 502 execution-failed and 504 timeout — the external engine errored or exceeded timeoutMs.
• 401 unauthorized; 403 insufficient_scope or insufficient_capability; 400 invalid_json / invalid_body from the shared gate.

Data elements

Four tables. All four are workspace-scoped and carry a row-level-security policy keyed on workspace_id for every operation, so a query outside the workspace transaction context returns nothing — the API's scope check and RLS are two independent gates.

Feature map

Everything the surfaces above expose reduces to six feature areas. Each area names the concrete components that deliver it — the same components the code map and the invariants below locate in the repository — and the surfaces where a consumer meets it.

System architecture

The module is one executor with several front doors. Reads hit the catalog; every execution — REST, MCP, structured answer, or agent tool — converges on the same governed executor, which is the only component that talks to an external engine and the only one that writes provenance.

Where the logic lives

The code map below locates each component from the feature map. Table names appear in the notes; they are all defined in the schema module and carry a workspace row-level-security policy.

Primary runtime flow

The highest-value path is runDataQuery: one governed execution from slug and params to rows and a provenance anchor. The same tail — gate, caps, provenance — runs identically when the caller is the MCP lookup tool or the structured-answer data bridge.

Internals and invariants

Connector registry

A connector row is the unit of trust: engine kind, non-secret config, an encrypted credential, the row and timeout caps, and an optional discovered schema snapshot. The catalog service owns writes and always masks reads; adapters own engine specifics behind one shared interface, so the executor stays engine-agnostic.

• Invariant — connector credentials never leave the server: they encrypt at write time and every read path substitutes the hasCredential boolean, with decryption confined to call time. Enforced in src/server/data/connectors.ts and src/server/data/executor.ts.
• Invariant — an adapter cannot widen the gate: statement policy, parameter coercion, caps, and provenance all run above the adapter layer, which receives already-validated SQL and values. Enforced by the registry in src/server/data/adapters.

Named queries with typed params

A named query binds a single-statement template to an ordered, typed parameter spec: params[0] feeds $1, and so on. Save time validates that every placeholder has a spec; run time coerces caller values to the declared types, applies defaults, rejects missing required values, and silently drops unknown keys.

• Invariant — a template placeholder without a matching parameter spec cannot be saved, so an executable query always has a complete typed signature. Enforced by validateTemplateParams in src/server/data/executor.ts.

Read-only execution policy

The policy is layered. A static check strips literals and comments, then requires exactly one statement beginning with SELECT or WITH and free of data-modifying, DDL, and session keywords — which is what rejects writing CTEs and SELECT INTO. Below it, each adapter adds what its engine offers: read-only transactions or sessions where they exist, and the engine's statement timeout everywhere.

• Invariant — no statement reaches an engine without passing the static read-only gate in the same process, and a rejection is itself recorded as a blocked provenance row. Enforced by assertReadOnlySql in src/server/data/executor.ts.

Entity bindings

A binding attaches one named query to exactly one entity or one entity type, with a param map whose sources are the entity's name, a stored constant, or a model-supplied value. Resolution for an entity returns its direct bindings plus the ones inherited from its type; the structured pipeline executes only bindings whose params resolve without a model source.

• Invariant — a binding targets exactly one of entityId or entityType, never both and never neither. Enforced by createBinding in src/server/data/bindings.ts.

Per-user entitlements

A query whose entitlement parameter is set is client-scoped: execution requires a user principal holding a matching grant, a single grant is injected automatically when the value is omitted, and any value outside the grant set is refused. Workspace service keys and system machinery are the two named bypasses — an absent principal is never silently equivalent to either.

• Invariant — entitlement-scoped execution fails closed, and every denial is recorded as a blocked provenance row so refusals are as auditable as executions. Enforced inside src/server/data/executor.ts, with grants administered in src/server/data/entitlements.ts.

Provenance and [Dn] citations

Every attempt appends one row: the exact executed statement, the params used, the outcome status, and timing. Successful calls additionally freeze a bounded sample of the returned rows plus a hash over the full normalized row set, so a figure cited in a produced artifact stays provable after the live data moves on. The structured pipeline reads these rows back to enrich each [Dn] with a connector name and execution timestamp.

• Invariant — one execution attempt, one append-only data_calls row, on every path and every outcome; there is no update or delete path. Enforced by the provenance recorder in src/server/data/executor.ts and consumed by src/server/query/data-bridge.ts.

For a self-hosting team the safe extension points are the edges, not the gate: contribute an additional engine through a plugin data adapter (the read-only policy, coercion, caps, and provenance stay host-owned), build your own surface on the headless data client instead of EliLiveData, and subscribe to the module's published events for downstream automation. The executor's policy layers and the append-only provenance contract are the parts everything else assumes and are not designed to be replaced.

How it composes

Conduit runs entirely on its own for the slug-and-params use case. What the other modules add is binding — the ability to go from a thing in the graph to the live numbers about it without a caller knowing which query to run.

With Atlas — bindings become available

entity_bindings resolves against entity rows: a binding matches either the entity's id or its type, and a lookup for one entity returns its direct bindings plus the ones inherited from its type. Without Atlas there are no entities to bind to, so the binding table stays empty and the param_map source entity_name has nothing to resolve. Everything in the three v1 routes still works unchanged — those never touch bindings.

With Lens — live rows join the cited answer

POST /api/v1/query takes an includeData boolean. When true, the pipeline resolves bindings for the entities it detected in the question, executes those whose params fully resolve without a model source, and returns them as dataCalls — each entry carrying id · dataCallId · connectorName · queryTitle · rowCount · executedAt. It is capped at three data calls per answer, a per-binding failure never blocks the document-grounded answer, and that route gates on agents:run and needs a configured chat model — both things Conduit alone does not. See Lens.

With Warrant — data evidence can overturn an abstain

In the same pipeline, a retrieval-floor verdict of abstain_with_pointers is overridden to proceed when live data actually ran, and the override is recorded on the decision. That is a Warrant policy behaviour reacting to Conduit evidence; it does not exist if you use Conduit by itself.

With Ports — two MCP tools

The MCP server exposes kb_data_discover (accepts data:read or data:run) to list the bindings that apply to a named entity along with the params the caller still has to supply, and kb_data_lookup (requires data:run) to execute one, selected by bindingId or bindingLabel. Omitting both works only when exactly one binding applies. Both mirror the REST scope map rather than bypassing it, and the lookup returns the same eight fields as the run endpoint. See Ports.

With Lineage — the [Dn] trail

data_calls is the provenance substrate a Lineage trace follows for a live figure, the way a document chunk backs an [Sn] citation. Conduit writes those rows unconditionally, so the trail exists whether or not you have adopted the module that reads it.