bus-validate — validate workspace datasets and invariants
bus-validate — validate workspace datasets and invariants
Synopsis
bus validate [--format <text|tsv>] [-C <dir>] [global flags]
bus validate parity --source <file> [--max-abs-delta <n>] [--max-count-delta <n>] [--dry-run] [--bucket-thresholds <file>] [-C <dir>] [-o <file>] [global flags]
bus validate journal-gap --source <file> [--max-abs-delta <n>] [--dry-run] [--bucket-thresholds <file>] [-C <dir>] [-o <file>] [global flags]
bus validate evidence-coverage [-C <dir>] [-o <file>] [global flags]
Description
Command names follow CLI command naming.
bus validate checks workspace datasets against schemas and cross-table invariants (for example balanced debits/credits, valid references, and period integrity).
It does not modify data.
Use it before period close and filing. Diagnostics go to stderr; stdout is empty on success.
The module also provides first-class parity and journal-gap checks through bus validate parity and bus validate journal-gap, plus evidence coverage auditing through bus validate evidence-coverage.
Commands
Run bus validate from the workspace (or use -C <dir>) for workspace-wide validation. Subcommands parity and journal-gap provide first-class migration checks; see Parity and gap checks (first-class) below. Subcommand evidence-coverage provides evidence link coverage totals and missing IDs; see Evidence coverage below.
Options
--format text (default) or --format tsv controls diagnostics format. TSV columns are dataset, record_id, field, rule, message. Global flags are defined in Standard global flags. For bus validate, stdout is empty on success and --output has no effect (no result set). For help, run bus validate --help.
Parity and gap checks (first-class)
bus validate parity --source <file> runs deterministic source-import parity checks.
bus validate journal-gap --source <file> runs deterministic journal gap checks.
Both commands consume a deterministic source-summary artifact with stable columns. That source artifact can be produced by bus-reports or by scripts.
Threshold flags (for example --max-abs-delta and --max-count-delta) control pass/fail behavior.
When a row exceeds threshold, the command exits non-zero.
--dry-run prints planned scope and thresholds to stderr without result output.
Per-bucket thresholds (optional). --bucket-thresholds <file> defines bucket-specific thresholds (for example operational, financing, internal transfer).
When provided, gap checks are evaluated per bucket and fail when any configured threshold is exceeded.
Without this file, only aggregate thresholds apply.
For extended capability notes, see Suggested capabilities.
Script-based diagnostics (e.g. exports/2024/022-erp-parity-2024.sh) remain available as an alternative.
Evidence coverage
bus validate evidence-coverage audits attachments coverage for journal vouchers, bank transactions, and invoices using attachment-links.csv. The command emits a deterministic TSV result set with columns row_kind, scope, source_id, voucher_id, bank_txn_id, invoice_id, total, linked, missing. Summary rows provide totals per scope; missing rows list uncovered IDs. It exits 0 when all scopes are fully covered and 1 when any missing evidence exists.
Files
Reads all workspace datasets and schemas. Does not write.
Examples
bus validate --format tsv
bus validate parity --source ./imports/legacy/parity-2026-01.csv --max-abs-delta 0.01
bus validate journal-gap --source ./imports/legacy/journal-gap-2026q1.csv --max-abs-delta 0.01 --bucket-thresholds ./config/gap-thresholds.csv
bus validate parity --source ./imports/legacy/parity-2026-01.csv --dry-run
bus validate evidence-coverage
Exit status
0 when the workspace is valid. Non-zero on invalid usage or when schema or invariant violations are found. bus validate evidence-coverage exits 0 only when all scopes are fully covered; missing evidence exits 1.
Using from .bus files
Inside a .bus file, write this module target without the bus prefix.
# same as: bus validate --format tsv
validate --format tsv
# same as: bus validate parity --source ./imports/legacy/parity-2026-01.csv --max-abs-delta 0.01
validate parity --source ./imports/legacy/parity-2026-01.csv --max-abs-delta 0.01
# same as: bus validate journal-gap --source ./imports/legacy/journal-gap-2026q1.csv --max-abs-delta 0.01 --bucket-thresholds ./config/gap-thresholds.csv
validate journal-gap --source ./imports/legacy/journal-gap-2026q1.csv --max-abs-delta 0.01 --bucket-thresholds ./config/gap-thresholds.csv
Development state
Value promise: Validate workspace datasets and invariants so the accounting workflow can run a single check before period close and filing and get deterministic diagnostics.
Use cases: Accounting workflow, Finnish bookkeeping and tax-audit compliance, Finnish company reorganisation (yrityssaneeraus) — audit and evidence pack.
Completeness: high — Run and schema/invariant checks are test-verified; user can complete pre-close validation and get pass/fail and diagnostics. Stdout is empty on success; --format text (default) and --format tsv control diagnostics to stderr; --output is a no-op for bus validate (no result set). First-class parity and journal-gap subcommands are implemented with thresholds and CI exit behavior.
Use case readiness: Accounting workflow: high — run, schema/invariant checks, empty stdout, format, and output no-op are in place; parity and journal-gap available. Finnish bookkeeping and tax-audit compliance: high — workspace validation and migration checks available; audit and closed-period would strengthen. Finnish company reorganisation: high — same as above.
Current: Workspace validation, parity, and journal-gap flows are test-verified, including threshold and dry-run behavior. Detailed test matrix and implementation notes are maintained in Module SDD: bus-validate.
Planned next: Table Schema min/max and audit/closed-period checks for Finnish bookkeeping and tax-audit compliance and Finnish company reorganisation. Class-aware gap reporting with per-bucket thresholds (see Suggested capabilities in the module SDD) as a possible extension.
Blockers: None known.
Depends on: None.
Used by: Run before bus-period close and bus-filing; workflows assume validation is available.
See Development status.