Configuration

Three things are read: the configuration file, the ledger, and the tax tables folder. --config (default rachuba.toml) and --ledger (default ledger.toml) name the first two, relative to the current directory. rachuba init writes both, with every configuration field present and explained.

init copies the invented template from examples/rachuba.toml in the source repository. Keep the resulting rachuba.toml and ledger.toml in your own private repository, not in the distributed source. The source repository ignores both filenames at any depth; it contains no real payer, employee or household records. Custom names passed through --config or --ledger are not covered by that ignore rule and must stay in your private repository or outside the public checkout.

The template uses 00-0000000 and 0000 as invalid EIN and SSN-last-four placeholders. Commands that load the configuration refuse them until you enter the assigned EIN and actual last four digits. The complete SSN is not stored.

[company]

• legal_name, address.
• ein, written 12-3456789.
• state, a two-letter uppercase postal code; it selects tables/state-<code>-<year>/. Supported: CA, NY.
• deposit_schedule, monthly or semiweekly, as the lookback period decides.
• sui_rate_ppm, the state unemployment rate from the employer's own rate notice, in parts per million (3.4% is 34000). Required.
• futa_credit_reduction_ppm, the rate from the tax year's Schedule A (Form 940) for a credit reduction state. Default 0 is not a forecast. For California, run and check warn while the rate is undetermined, even with an estimated value; after determination they warn if the configured value differs from the final rate. Revisit the year's Form 940 liability after updating it.
• round_withholding_to_dollar, default false.
• state_annualized_method, default true. Hold it for a whole year.

[employee] and [employee.w4]

• name, address, ssn_last4 (exactly four digits; the full number is never stored).
• pay_frequency: weekly, biweekly, semimonthly, monthly, quarterly, semiannually, annually or daily.
• gross_per_period, positive.
• age_this_year, optional; it decides the 401(k) catch-up.
• state_flags (nyc_resident, yonkers_resident), state_allowances, state_estimated_allowances, state_additional_withholding, state_filing_status.
• [employee.w4]: filing_status (single, married_filing_jointly, married_filing_separately, head_of_household), step2_checkbox, step3_credits, step4a_other_income, step4b_deductions (annual) and step4c_extra_withholding (per period).

[retirement_401k]

pretax, roth and employer are each { none = {} }, { percent = { ppm = 100000 } } or { per_period = { amount = "1500.00" } }. prior_year_ss_wages decides whether catch-up deferrals must be Roth. A payroll run never defers past the year's ceiling and never pays an employer contribution past 25% of compensation or the section 415(c) limit.

[household]

Optional, read only by rachuba return: filing_status; spouse_wages (Form W-2 box 1) and spouse_medicare_wages (box 5, required when spouse wages are positive) on a joint return; spouse_covered_by_plan, spouse_age_this_year; other_income, interest_and_ordinary_dividends, qualified_dividends, short_term_capital_gains, long_term_capital_gains; adjustments, itemized_deductions, aged_or_blind_boxes, credits; other_withholding; prior_year_tax and prior_year_agi (both or neither); and one [[household.estimated_payment]] block, with paid_on and amount, per Form 1040-ES payment.

The ledger

ledger.toml holds every committed run in pay-date order with every figure it produced, and the dates its taxes were deposited and its deferral remitted. It is the source of year-to-date totals, wage bases and form lines. Every command except init refuses to run without it:

no payroll ledger at <path>. Run `rachuba init` to write an empty one, or name the committed ledger with --ledger.

The tables folder

The folder holding federal-<year> and state-<code>-<year> is RACHUBA_TABLES when that is set, otherwise tables beside the configuration file. federal-<year> carries Publication 15-T, FICA, FUTA and the retirement limits, and form-1040.toml and ira.toml for the return projection.

Refusals

Each exits 1 before anything is written.

no configuration at <path>. Run `rachuba init` to write a starting file.

company.state must be a two-letter uppercase postal code, got <value>

company.ein must look like 12-3456789, got <value>

employee.ssn_last4 must be exactly four digits

employee.gross_per_period must be positive

company.sui_rate_ppm cannot be negative

retirement_401k.<field>: <n> ppm is not between 0% and 100%

retirement_401k.<field>: amount cannot be negative

RACHUBA_TABLES names <path>, which is not a directory. Point it at the folder holding federal-<year> and state-<code>-<year>, or unset it to use the tables folder beside the configuration file.

no tables directory at <path>. Put the per-year table folders there, or set RACHUBA_TABLES to the directory holding them.

no federal tax table for <year> at <path>. Tax tables are per-year data folders; transcribe that year's Publication 15-T into section files there before running payroll.

no state engine for <code>. Supported: CA, NY. Adding a state needs both a data folder at <path> and a computation module, because withholding methods differ in shape between states and cannot be derived from a rate table alone.

<path> is not a .toml section file. A table folder holds only the transcribed sections of one year's publications; move anything else out of it.

<key> is defined in both <file> and <file>. A key belongs to exactly one section file; delete one of the two definitions.

The [household] refusals are on rachuba return.