Hub Data Dictionary

What the Hub stores about runs, and how to query it. Written for people and AI assistants that answer questions such as "what failed last night, and where?". Start with the views; the tables behind them are listed after.

Query them with kinenix hub query (hub.md, Querying Runs), for example kinenix hub query v_failures --since yesterday, or with any SQLite tool on ~/.kinenix/hub.db. User views (custom_*) are added from ~/.kinenix/hub_views/.

A test (kinenix-hub/tests/test_data_dictionary.py) fails when a table, view, column, or details key exists without a row here, or the other way round. kinenix hub query --describe shows this document's meanings, from a copy in the package (kinenix-hub/kinenix_hub/hub_data.md); copy this file there after editing it, a test checks that they are the same.

How the data gets here

A worker sends one execution log per run when the flow ends (logging.md). The Hub keeps the log whole in executions.raw_log and stores its facts as rows: one in executions, one in step_results per executed step (also every loop iteration, subflow steps, and On Error and Finally steps), and one in failures per failure (also failures the flow continued after).

• The worker removes secrets and personal data before sending (logging.md, Redaction).
• Step outputs and step errors are stored at most 500 characters long, ending with ... when cut; the full log stays in executions.raw_log.
• Runs from workers older than 0.2.0b4 have fewer facts: no run id, Kinenix version, work items, line, path, subflow, loop item, or retries. Their step outputs are not stored, because those workers did not redact them. Only the failure that stopped such a run has handled = stopped; other failed steps have an empty handled.
• When the Hub is upgraded, runs it already stored get their rows from raw_log once, at the first start.

Conventions

• Times are UTC, stored as text YYYY-MM-DD HH:MM:SS.ffffff, so they sort and compare as text: failed_at >= datetime('now', '-1 day').
• section is where a step is in flow.md: steps, on_error (## On Error), or finally (## Finally).
• handled is what happened after a step failed: stopped (the run stopped; On Error ran), continued (on_error: continue, or a step in On Error or Finally), fallback (fallback_step_id ran).
• details columns are JSON with a version key v; the views expose their keys as columns. The views exist on SQLite only.

Views

v_runs

One row per run. Answers: how many runs, which failed, success rate and duration per flow and worker, how many work items were done.

v_failures

One row per failure. Answers: what failed, where, on which item, how it was handled, and what to do about it.

v_steps

One row per executed step. Answers: slowest steps, steps that fail most, what a run did in order, which items were skipped and why.

Tables

executions

One row per run, written when the worker sends the run.

executions.details

step_results

One row per executed step.

step_results.details

failures

One row per failure, also failures the flow continued after, so a run that succeeded can still report failed items. A flow.call step whose subflow failed has no row of its own: the failure is the subflow step's.

failures.details

workers

One row per worker, updated by its heartbeats.

schema_version

Schema changes applied to this database (hub.md, Upgrades).

Run report

Each run gets a short Markdown report in executions.details.report_md (v_runs.report_md), for people, e-mail, and AI. Times are the worker's local time. kinenix hub report --flow NAME prints the report of a flow's latest run.

# TIPH Quotes, 2026-10-12 02:00 +07:00 (failed)
- Worker: rpi4, Kinenix 0.2.0b4, duration 14 min
- Items: 6 of 12 done, 1 failed, 5 not reached
- Failed: R007 HONDA HR-V at "Choose Brand" (subflow process_one, line 42, after 2 retries), continued: Timeout 30000ms exceeded
- Failed: "Save Quotes" (line 60), run stopped: File is open in Excel
- On Error: Capture Screen succeeded, Email Error succeeded
- Finally: Close Browser succeeded

At most 10 failures are listed; the rest are counted. A run without failures says - No failures.

Example questions

-- What failed since yesterday, and where?
SELECT failed_at, flow_name, worker_id, step_path, loop_item, handled, message
FROM v_failures WHERE failed_at >= datetime('now', '-1 day') ORDER BY failed_at;

-- Success rate and average duration per flow over the last 7 days
SELECT flow_name, COUNT(*) AS runs, AVG(status = 'success') AS success_rate, AVG(duration_seconds) AS avg_seconds
FROM v_runs WHERE started_at >= datetime('now', '-7 days') GROUP BY flow_name;

-- Steps that fail most
SELECT flow_name, step_name, action, COUNT(*) AS failures
FROM v_failures GROUP BY flow_name, step_name, action ORDER BY failures DESC LIMIT 10;

-- Slowest steps on average
SELECT flow_name, step_name, AVG(duration_seconds) AS avg_seconds, COUNT(*) AS runs
FROM v_steps WHERE status = 'success' GROUP BY flow_name, step_name ORDER BY avg_seconds DESC LIMIT 10;