Operator Workflow
The seven steps from a database estate's sources to reconciled marts, and the human sign-off that gates the second half.
For a database estate, EKOS defines seven operator steps on top of the compilation pipeline. Steps 1–3 belong to EKOS core; steps 4–7 to the EKOS Lakehouse extension, whose binary is EKOS plus its lakehouse commands.
| Step | The operator… | What runs | Model |
|---|---|---|---|
| 1 Analyse sources | adds code, docs and databases, then compiles | connectors and static analyzers, live database catalogs | none |
| 2 Documentation | generates the estate's documentation | ekos docs generate --layout estate |
none |
| 3 Review and sign-off | settles scope, PII, conflicts, identity, write behaviour and glossary, then signs each subject off | decisions and sign-offs become ledger facts bound to a digest | none |
| 4 Requirements | describes the marts wanted, in plain words | a model drafts the metadata; EKOS resolves every term against the plan | yes, only here |
| 5 Extraction and landing | reviews how each table lands in bronze and approves the plan | the planner, from write behaviour and step 3 | none |
| 6 Bronze and silver | generates the pipeline and runs it | SQL, dbt-trino silver, Dagster, reconciliation | none |
| 7 Marts | proposes, merges, builds and reconciles each mart | dbt gold from approved requirements, Dagster, Trino | none |
The gate
ekos workflow status (and the step bar on every project page in the console) shows each step as todo, partial, done or blocked. Steps 4–7 are blocked until every review subject of step 3 has a valid sign-off, and an extension's step command can call the same gate before it writes (EKOS Lakehouse does when require-signoff = true). A sign-off is valid only while the digest of the facts it signed still matches; it is recomputed on every read, so a change in the source — a new column in the database — makes the affected sign-off stale at once. Agents read the state through ekos_signoff_status; no MCP tool can decide, sign off or approve.
What it guarantees
- Read-only on the source. Database sessions are read-only, with a user EKOS reports if it can write; the source tree is never written.
- No secret or data value stored. Passwords stay in environment variables or the keychain. Profiles keep counts and bounds of numbers and dates, never text values. Run logs and estate pages carry no value.
- Human-only decisions. Review decisions, sign-offs, step-5 approvals, requirement approvals and merging a mart are review-class commands: the console runs them as the signed-in person and refuses them to API tokens.
- No model call in steps 1–3. Every pipeline command ends its run log with its model-call count; step 4 refuses a metered model route without explicit permission.
- Everything decided is a ledger fact with its evidence and digest, so a later change says what it invalidated.
Status
The workflow was built and measured on the iDempiere ERP with a live Oracle testbed. Not yet done: a complete step-3 sign-off there (195 conflicts await a person), publishing the generated documentation to its public target, the full pipeline run (step 6 was run on a 165-table subset), and optional CDC.