Enumerations Reference

Status: v1.14 (living document — updated as enums evolve) Owner: datapipelines.co core Purpose: Single source of truth for every enum value used across the system. Prevents spelling drift across specs and across the codebase.

How to use this document

• Every enum used in datapipelines.co is cataloged here.
• Specs may inline enum values for readability, but this document is the authoritative reference.
• If a value appears in code or a spec that doesn't match this document, the spec/code is wrong.
• When adding a new enum value: add it here first, then propagate to specs and code.
• Values are additive-only per the stability promises in individual specs.
• Each enum has exactly ONE authoring spec (see the cross-reference table). Other specs are consumers.
• Values marked (reserved) are registered for future use — they MUST NOT appear in generated code or be accepted by validators in v1.

Case & serialization convention

The strings cataloged here are the wire values — what appears in JSON payloads, exactly as written (case included). Kotlin enum classes use UPPER_SNAKE_CASE constants with an explicit mapping to the wire value:

enum class WriteMode(@JsonValue val wire: String) {
    REPLACE("replace"),
    APPEND("append");

    companion object {
        @JsonCreator @JvmStatic
        fun fromWire(v: String) = entries.firstOrNull { it.wire == v }
            ?: throw IllegalArgumentException("Unknown WriteMode: $v")
    }
}

Where the cataloged value is already UPPER (DQL, POSTGRES, SUCCESS), wire and constant coincide. Never rely on default Enum.name serialization for lowercase/kebab/snake wire values — the explicit @JsonValue mapping is mandatory so the catalog string stays the single source of truth.

1. LogicalType — canonical data types

Source: Type System §3 Used by: every spec — this is the foundational type vocabulary.

Excluded from parameters declarations: NULL (only the other 10 may be parameter types).

2. NodeType — pipeline node SQL category

Source: Pipeline Contract §4.6 Used by: pipeline-contract, dag-executor.

Reserved for future: EXPRESSION, HTTP (non-SQL node types — see ROADMAP).

3. OutputTarget — where a DQL node's ResultSet goes

Source: Pipeline Contract §4.7 Used by: pipeline-contract, dag-executor, staging.

Reserved for future: kafka, s3, email, webhook (see ROADMAP).

4. WriteMode — for output.target: "datasource"

Source: Pipeline Contract §4.7 Used by: pipeline-contract, dag-executor.

5. Dialect — supported source database dialects

Source: Type System §5 (single authority) Used by: datasources (driver dispatch), templates (template targets a dialect), pipeline-contract (validation: template dialect must match datasource dialect).

Reserved for future: SNOWFLAKE, BIGQUERY, REDSHIFT (see ROADMAP).

5A. CredentialKind — what a datasource's stored credential IS

Source: Datasources §3.4 (single authority) Used by: datasources (validation, pool build, encryption), rest-api (POST /api/v1/datasources), mcp-server (datasources_get reports the kind; there is no MCP create — MCP Server §6.2.22), metadata-db (datasources.credential_kind).

Wire values are lowercase snake_case, so the @JsonValue mapping is explicit per the case convention above.

These are not (reserved) values in the enums.md sense: all five are accepted by the validator and stored by the column. What a shipped dialect can USE is narrower and is the adapter's declaration (supportedCredentialKinds, Datasources §3.4) — a kind outside a dialect's set is refused at save with datasource.validation.properties_invalid, never stored and ignored.

6. TemplateEngine — template language

Source: Templates §4 Used by: templates (engine dispatch).

Reserved for future: pebble, handlebars, thymeleaf-sql, none (raw SQL with no template processing — see ROADMAP).

6A. TemplateType — template kind

Source: Template Hierarchy §5 Used by: templates (engine-configuration dispatch, type/dialect consistency), pipeline-contract (reference legality).

Fixed at template create and identical on every version of a template (template.validation.type_immutable). Serialization is the lowercase wire value ("sql" / "html"), per the case convention above. There are no reserved future values — component sub-typing (kpi, aggrid, svg, form, …) belongs to the future dashboard abstraction and is deliberately absent here (design §2).

7. StagingEngine — tempdb engine

Source: Pipeline Contract §5 Used by: pipeline-contract (settings.tempdb.engine), staging (factory dispatch), dag-executor (instantiation).

Reserved for future: DUCKDB (in-memory DuckDB — better for analytical workloads; see ROADMAP).

Declaration reality (2026-08-08). The frozen module dependency graph (module-structure §4.2) makes the "pipeline-contract authors, staging consumes" line above impossible: staging depends only on typesystem, so it cannot see a type declared in pipeline-contract. In v1 the enum has a single value (H2), so pipeline-contract declares it (for the settings.tempdb.engine wire value, with @JsonValue) and staging declares an identical local enum class StagingEngine { H2 } for StagingFactory dispatch; dag (which depends on both) maps between them — trivial while there is one value. Consolidation is a P4/dag decision: when a second engine (DUCKDB) lands, move StagingEngine into typesystem (the shared lower layer, exactly as Dialect resolved the same class of problem) so there is one authority. Until then the duplication is bounded to a single constant and dag owns the mapping.

8. Scope — API key authorization scope

Source: Auth §7.5 Used by: auth, every endpoint and MCP tool (scope enforcement — see the scope↔operation matrix in auth.md).

Hierarchical: admin ⊃ author ⊃ execute ⊃ read. A key with a higher scope has all lower scopes too.

This is the CREDENTIAL axis, and since RBAC round 1 it is an API-key property only — a session JWT carries no scopes claim. What a signed-in person may do is Capability in the active workspace. Both axes are enforced for a key: its scope AND its issuer's current role (Auth §7.6).

8B. Capability — what a membership may do

Source: Auth §11A (the role table), Auth §7.6 (the per-operation minimums) Used by: auth (ScopeMatrix.allowed), every REST handler and MCP tool.

The ROLE axis. It travels with a membership, not with a credential (RBAC design D-R1): the same person is a viewer in one workspace and an author in another, which is why it cannot live on the user.

Deliberately NOT a hierarchy, unlike Scope. An author may not release and a promoter may not author, so neither dominates the other — each value is a predicate over the membership row's three flags (author, promoter, admin; all false = viewer), never an ordinal comparison.

admin → author is a database CHECK (chk_workspace_member_admin_authors, metadata-db §4.12), so author reads straight off the row rather than re-spelling the implication at each predicate.

Where the two axes disagree, and neither is redundant: execute is the second SCOPE but the viewer-level CAPABILITY — a read key may not execute, a viewer's session may. The datasource probes run the other way: author scope (a read key must not reach row data) but view capability (a viewer gets capped read-only SELECT by design).

8A. ApiKeyKind — what an API key IS

Source: Auth §7.7 Used by: auth, web, mcp-server, persistence (api_keys.kind).

A kind is not a scope and is deliberately not modelled as one. Scopes answer "how much may this credential do?" along one hierarchy; a kind answers "what kind of credential is this?", and the two axes do not compose — an endpoint key is not "a user key with fewer scopes". The wire form is the lowercase name, as with Scope.

A server key authenticates nothing outside the promotion routes. Presented as an ordinary DP-API-Key it is refused on every route — REST, htmx partials, /mcp and every UI page — with endpoint.key_kind_refused. Same rule as the endpoint kind, different family.

An endpoint key with no binding on any ancestor of the path it presents at authorises nothing. The absence of a binding is never a fall-through to the user-key rule; if it were, publishing a new endpoint would silently widen every existing endpoint key's reach at the moment of publication.

9. NodeStatus — per-node execution outcome

Source: DAG Executor §7 Used by: dag-executor (node_stats), rest-api (response envelope).

10. ExecutionStatus — whole-pipeline execution outcome

Source: REST API §6.4, DAG Executor §5 Used by: rest-api, dag-executor, mcp-server, persistence (pipeline_executions.status).

Reserved for future: PARTIAL (partial-result mode where some nodes succeeded but a non-critical path failed — see ROADMAP).

Declaration reality (2026-08-10). Declared in the dag module, for the same layering reason SseEventType is (§11): web implements rest-api at layer 5 and depends on dag at layer 3, never the reverse (module-structure §4.2). The executor is what produces the status and what writes pipeline_executions.status, so the enum lives at the lowest layer that needs it and web consumes it. This document, rest-api and metadata-db remain the wire authorities — the declaration site is an implementation consequence, not a change of ownership.

11. SseEventType — pipeline execution event types

Source: REST API §6.4, DAG Executor §10 Used by: rest-api (SSE endpoint), dag-executor (event emitter), mcp-server (event forwarding).

Order guarantees: see REST API §6.5.

Reserved for future: data_chunk (streaming row chunks for incremental processing — see ROADMAP).

12. ResultDelivery — REMOVED (v1.1)

Removed 2026-08-07 (SPEC-REVIEW-2026-08, decision D9). The inline-vs-claim-check split no longer exists: every caller result is stored in Redis and data_ready always carries schema + inline first page + result_url cursor. See REST API §7. Section number retained so later sections keep their numbering.

13. ResultFormat — wire format for result data

Source: REST API §7 Used by: rest-api, mcp-server.

14. SslMode — datasource TLS mode

Source: Datasources §5 Used by: datasources (PG-idiomatic; analogous config for other dialects).

15. AuthAuditEvent — auth audit log events

Source: Auth §10.1 Used by: auth, observability.

Password and lockout events exist only for the optional local accounts (Auth §5A); an OIDC-only deployment never writes them. No event in this table ever carries credential material.

Datasource audit events (same audit_log table, defined in Datasources §7.4):

Promotion audit events (same audit_log table, defined in Versioning §10):

MCP audit events (same audit_log table, defined in MCP §14):

Version lifecycle audit events (same audit_log table, defined in Versioning §3; emitted by the 101 REST verbs, all session-only — an API key cannot produce one):

Learned-semantics audit events (same audit_log table, defined in the learned-semantic-layer design record §9; emitted by SemanticsService for the semantics_record / semantics_retire MCP tools — 118):

Mail audit events (same audit_log table, defined in Auth §5A.8; emitted by MailNotifier off the request thread, after the transport answered — 137):

16. Error Code Domains (prefix catalog)

Source: Pipeline Contract §13 — the ONLY catalog of concrete error codes. This section registers domains; deliberately no code list here, so there is exactly one place a code can drift from. Used by: every spec that defines error codes.

Error codes follow {domain}.{entity}.{failure} — three segments, all lowercase snake_case, dot-separated, ASCII. Two-segment codes exist only where the domain has no entity dimension (datasource.in_use, datasource.driver_not_loaded, datasource.not_found, datasource.lease_in_transaction, datasource.table_not_found, datasource.table_forbidden, template.not_found, rate_limit.exceeded, rate_limit.unavailable, every semantics.* code — a learned fact has no sub-entity — and mcp.doc_not_found). Additive-only — never reused, never renamed.

Removed 2026-08-07 (D5): the auth.rate_limit.* domain (folded into rate_limit.exceeded), the template.import.* domain (folded into template.validation.*), the idempotency_key.* spelling (now idempotency.*), and result.claim_check_expired (now result.expired under the D9 result model).

17. HTTP Status Code Conventions

Source: REST API §2 Used by: every spec that defines HTTP behavior.

18. ExecutionTrigger — how execution was initiated

Source: REST API §10.2 Used by: rest-api, mcp-server, persistence.

Declaration reality (2026-08-10). Declared in the dag module, for the same layering reason as ExecutionStatus (§10) and SseEventType (§11): the executor owns the execution repository that persists pipeline_executions.trigger, and it sits below web. This document, rest-api and metadata-db remain the wire authorities.

19. LearnedFactKind — what a learned fact is about

Source: Learned semantic layer design §4 (the ruling); the chk_learned_facts_kind CHECK of Metadata DB §4.18 is the enforcing copy. Used by: datasources (LearnedFactKind, the recorder), mcp-server (semantics_record's kind enum, derived), the introspection enrichment, the UI.

Closed. No type, nullable, key, comment, partition or row_count kind exists and none will (D-S2: nothing JDBC metadata already provides is stored — introspection stays the source for those and is what facts are checked against). Each kind belongs to exactly one scope; the database states the same rule in chk_learned_facts_kind_scope. Three sources — this table, the CHECK's list, the Kotlin enum — are held to one truth by LearnedFactKindSpecDriftTest.

Trust (the companion state, design §5 — not an enum a caller supplies): asserted (no evidence — or a definition/exclusion/preference, a choice, whatever it carries; C.2 2026-09-13) → observed (evidence ran at record time, data-kind facts only) → verified (a human confirmed); the mechanical demotions needs_review (the table's column set changed around a still-resolving ref) and stale (a referenced column or table no longer exists); and retired (explicit, with a reason — never a delete). Written as the chk_learned_facts_trust CHECK.

20. CheckRunVerdict — a release check's outcome (140)

Source: pipeline-contract §13.17; the chk_pipeline_check_runs_verdict CHECK of Metadata DB §4.20 is the enforcing copy; the Kotlin enum is CheckRunVerdict (pipeline-contract ReleaseCheckGate.kt). Used by: pipeline-contract (the release gate), application (the check runner), mcp-server (pipelines_run_checks), rest-api (§5.16), the UI.

Closed. A release refuses on fail OR error alike (versioning §5.3 precondition 4) — the distinction exists for the human reading the dialog, not for the gate.

21. CheckRunVia — who commissioned a check run (140)

Source: pipeline-contract §13.17; the chk_pipeline_check_runs_via CHECK of Metadata DB §4.20; the Kotlin enum is CheckRunVia. Used by: application (the check runner), mcp-server, rest-api, the UI.

Closed. The run rows are append-only; via is the record of WHICH surface commissioned each one.

Cross-Reference: Where Each Enum Is Authored

Validation Discipline

When a spec or code change introduces or renames an enum value:

1. Update this document first. This is the source of truth.
2. Search all specs for the old spelling — grep for the value across docs/*.md.
3. Search the codebase — grep for the value across modules/**/*.kt.
4. Bump the spec's schema_version if the change is non-additive (per the spec's stability promise).
5. Document the change in the spec's Change Log appendix and in ROADMAP if it was previously tracked there.
6. Run scripts/docs-audit.sh — it mechanically enforces steps 2's doc sweep (cross-references, error codes, config keys, forbidden legacy spellings) and must exit 0 before the change lands.

This document itself is additive-only — values are never removed (only marked deprecated). The authoring spec governs its own stability promise; this doc tracks usage.

Appendix A: Change Log