tool-construction — construction cost, schedule, and quality ledger

@@ -11,16 +11,16 @@ status: active
audience: vendor-public
bcsc_class: forward-looking
language_protocol: PROSE-TOPIC
last_edited: 2026-09-03
last_edited: 2026-09-07
editor: pointsav-engineering
paired_with: tool-construction.es.md
short_description: "A flat-file, owner-held ledger for construction cost, schedule, and quality control, built on the same double-entry discipline as tool-accounting; the core engine now runs as a real CLI, posting a live pilot's estimates through all four cost-type chains — estimate-stage only, with no console surface yet."
short_description: "A flat-file, owner-held ledger for construction cost, schedule, and quality control, built on the same double-entry discipline as tool-accounting; both the quantity and money ledgers now run as a real CLI against a live pilot, rendering more than a dozen reports across kick-off, ongoing-monitoring, and job-completion cadences — no console surface yet."
cites: []
---

`tool-construction` is a flat-file, owner-held ledger for construction cost, schedule, and quality control, built on the same double-entry discipline as the sibling accounting engine, [[tool-accounting]]. It is designed to serve three audiences at once: an implementation reference for developers building the platform out (including developers with no construction background), a technical overview for evaluating the business the software supports, and a decision document for a contractor or property owner evaluating adoption.

**What exists today.** The engine is real and running. `tool-construction-core` implements the quantity-side ledger in full — vector-valued journal entries, non-fungible units, and all four cost-type chains (labour, material, equipment, subcontract) — verified by golden-value tests that reproduce the architecture's own worked examples number for number. A pilot binary crate drives it as a command-line toolchain of five binaries that build a cost estimate bottom-up from work packages, compute a critical-path schedule, post the estimate into the ledger, and render reports as HTML and PDF. It runs against a real pilot: a live development project whose work packages are posted as real budget locks, with zero trial-balance identity failures. Two boundaries are just as real. The toolchain is CLI-only — no terminal or console surface exists, and none has been granted a build slot. And it is estimate-stage only: the ledger carries real estimates and budgets, not actuals, because no invoice, payment, or payroll record has entered the pipeline yet.
**What exists today.** The engine is real and running, on both sides of its ledger. `tool-construction-core` implements the quantity-side ledger in full — vector-valued journal entries, non-fungible units, and all four cost-type chains (labour, material, equipment, subcontract) — and now also implements a genuine money-denominated cost ledger (below), both verified by golden-value tests that reproduce the architecture's own worked examples number for number. A pilot binary crate drives the whole engine as a command-line toolchain of report and pipeline binaries that build a cost estimate bottom-up from work packages, compute a critical-path schedule, post the estimate into the ledger, and render more than a dozen real reports as HTML and PDF. It runs against a real pilot: a live development project whose work packages are posted as real budget locks, with zero trial-balance identity failures. One boundary is still real: the toolchain is CLI-only — no terminal or console surface exists, and none has been granted a build slot.

---

@@ -44,11 +44,13 @@ Material consumption is built around **backflush costing**: rather than tracking

---

## One journal, two projections
## One journal, two ledgers, both real

The engine keeps two ledgers, denominated differently on purpose. The **production ledger** holds physical quantities — hours, cubic metres, tonnes, schedule-of-values fractions. The **cost ledger** is designed to hold dollars, fed only by real payroll and accounts-payable postings, never by converting the production ledger's quantities through a rate. A lump-sum subcontractor's obligation is a function of the contract and the percentage certified complete, not of the hours their own crew worked — two ledgers keep that case honest, rather than forcing an invented dollar figure or an hours-based approximation. The quantity-side ledger is implemented in full; the dollar-side ledger is deliberately deferred until real payable and payroll data exists to feed it, rather than being built against invented figures.
The engine keeps two ledgers, denominated differently on purpose — and both are now built, not just designed. The **production ledger** holds physical quantities — hours, cubic metres, tonnes, schedule-of-values fractions. The **cost ledger** holds dollars, fed only by real payroll and accounts-payable postings, never by converting the production ledger's quantities through a rate. A lump-sum subcontractor's obligation is a function of the contract and the percentage certified complete, not of the hours their own crew worked — two ledgers keep that case honest, rather than forcing an invented dollar figure or an hours-based approximation.

The two ledgers are named projections of one journal, not separate books — an approach with production precedent (SAP's own Material Ledger was eventually folded into a single Universal Journal). Within that one journal, different kinds of quantity are never summed together. The unit type makes this a compile-and-runtime guarantee rather than a convention:
The cost ledger uses its own chart of accounts, deliberately numbered so it can never collide with the quantity ledger's own — job-cost direct-cost accounts by cost type, accrued payroll, trade payables, and a dedicated subcontract-retainage-payable account that tracks statutory holdback per contract. On the current pilot, every cost-ledger balance is a real, computed zero: no invoice, payment, or payroll record has entered the pipeline yet, so the ledger correctly reports nothing rather than an estimate. A real zero from an empty ledger and a genuinely unmeasured figure are treated as different facts throughout this engine — see the reporting rule below.

The two ledgers are named projections of one journal, not separate books — an approach with production precedent (SAP's own Material Ledger was eventually folded into a single Universal Journal). Within the quantity ledger specifically, different kinds of quantity are never summed together. The unit type makes this a compile-and-runtime guarantee rather than a convention:

```rust
pub enum Unit {
@@ -59,9 +61,9 @@ pub enum Unit {
}
```

A journal entry is vector-valued — one real-world event, such as a day's work reported, posts across several units at once in a single atomic entry — and the balance check runs componentwise, each unit's debits and credits required to balance independently. Adding across units is refused, not discouraged. Ledger state is never stored as a running total: every run folds the full journal fresh into account markings, so the trial-balance identities are re-proved from first entries on every execution.
A journal entry in the production ledger is vector-valued — one real-world event, such as a day's work reported, posts across several units at once in a single atomic entry — and the balance check runs componentwise, each unit's debits and credits required to balance independently. Adding across units is refused, not discouraged. Neither ledger's state is ever stored as a running total: every run folds the full journal fresh into account markings, so the trial-balance identities are re-proved from first entries on every execution.

**Why it matters:** the ledger cannot silently blend hours into cubic metres or either into dollars, and any corruption of state would fail loudly on the next fold instead of compounding quietly.
**Why it matters:** the ledgers cannot silently blend hours into cubic metres, either into dollars, or one project's dollars into another's, and any corruption of state would fail loudly on the next fold instead of compounding quietly.

---

@@ -79,7 +81,7 @@ The **subcontract chain** models a schedule-of-values line as a fraction-of-lump

## Whose ledger it is

A job-cost ledger only means something from one seat: the party actually performing the work is the only party that can observe labour hours, material consumption, and certification facts. The engine makes this explicit with a small set of party roles — performer, contracting owner, certifier, subcontractor, supplier — with exactly one performer per deployment, whose books the ledger is. Party identity attaches to a posting only where the posting's meaning genuinely depends on who asserted it (the subcontract certification chain); labour, material, and equipment postings are facts about the work, not about a relationship, and carry no party at all. A regression guard runs the same subcontract lifecycle twice, once with real party names and once with opaque identifiers, and asserts identical balances — mechanical proof that the ledger's arithmetic is independent of who the parties are.
A job-cost ledger only means something from one seat: the party actually performing the work is the only party that can observe labour hours, material consumption, and certification facts. The engine makes this explicit with a small set of party roles — performer, contracting owner, certifier, subcontractor, supplier — with exactly one performer per deployment, whose books the ledger is. Party identity attaches to a posting only where the posting's meaning genuinely depends on who asserted it (the subcontract certification chain, and the money ledger's own retainage tracking, which is kept per contracting relationship); labour, material, and equipment postings are facts about the work, not about a relationship, and carry no party at all. A regression guard runs the same subcontract lifecycle twice, once with real party names and once with opaque identifiers, and asserts identical balances — mechanical proof that the ledger's arithmetic is independent of who the parties are.

On the current pilot, the performer is MCorp — the platform's reference customer, whose staff carry out the construction work and operate the pilot ledger. The development programme the project belongs to is Woodfine's; the ledger models the performing party's books, not the owner's.

@@ -89,9 +91,15 @@ On the current pilot, the performer is MCorp — the platform's reference custom

## Reports, and the rule that a zero is a claim

The pilot toolchain renders its reports — a cost estimate, a critical-path schedule with a Gantt timeline, a materials listing, and a monthly project status report — as HTML and PDF through `tool-typeset`, the platform's shared zero-dependency document renderer, from a single compute layer per report. Every rendered PDF is verified visually, not just by build success — a discipline adopted after passing builds produced an unreadable timeline.
The pilot toolchain renders more than a dozen real reports as HTML and PDF through `tool-typeset`, the platform's shared zero-dependency document renderer, from a single compute layer per report. Every rendered PDF is verified visually, not just by build success — a discipline adopted after passing builds produced an unreadable timeline. The reports fall into three cadences, matching how a real project actually gets reviewed:

**Kick-off**, produced once at project start: a bottom-up cost estimate, a critical-path schedule with a Gantt timeline, the materials/work-package list, and a correspondence register that cites every logged transmittal by content hash rather than copying message content into the engine's own records.

**Ongoing project monitoring**, produced on a recurring cadence: a monthly project status report; a data-currency exception register that flags every work package or schedule phase with no actual or progress update this period; a cost-to-complete forecast across three industry-standard estimate-at-completion formulas; a blocked-work / change-order exposure register; a subcontract commitment and certification-status register; an equipment utilisation and recovery register; a monthly safety-activity register aggregating site inspections, toolbox talks, incident counts, and hours by category; and a multi-building roll-up for a legal entity that owns more than one building (see below).

Two characteristics of the reporting are worth stating because they are unusual. First, the engine computes its outputs bottom-up from work-package primitives — the way a contractor's own estimating and scheduling software would — and then reconciles them against the pilot's independently prepared professional estimates and its known schedule dates, which serve as an answer key rather than as data the reports merely reformat. Second, the status report refuses to fabricate. Where no real measurement exists — an actual cost with no invoice behind it, a percent complete with no observed progress, an incident count with no safety register — the report prints an en dash, never a zero and never a projection dressed as an observation. A zero in an incident column would itself be a safety claim; a blank is the honest state of the data.
**Job completion**, produced once a project or a phase of one nears completion: a weighted operational scorecard spanning six categories — safety, quality, client relationships, cost control, schedule, and documentation — with an evidence-automation layer that answers the small subset of its questions a real register can confirm mechanically (for example, whether a required monthly submission exists on file for the period) while leaving every question that calls for human judgment marked as exactly that, never auto-scored; and a job-completion checklist and post-project review pack.

Two characteristics of the reporting are worth stating because they are unusual. First, the engine computes its outputs bottom-up from work-package primitives — the way a contractor's own estimating and scheduling software would — and then reconciles them against the pilot's independently prepared professional estimates and its known schedule dates, which serve as an answer key rather than as data the reports merely reformat. Second, every report refuses to fabricate. Where no real measurement exists — an actual cost with no invoice behind it, a percent complete with no observed progress, an incident count with no safety register entry, a second building under a TitleCo that hasn't been added yet — the report prints an en dash or a real, honest zero-of-total count, never a projection dressed as an observation. A zero in an incident column would itself be a safety claim; a blank is the honest state of the data. Several reports in the ongoing-monitoring and job-completion groups above render this way today: the underlying engine and chart of accounts are real and tested, and the report is structurally ready the moment real data exists, but no real transaction or submission has occurred yet for this pilot.

**Why it matters:** a report from this engine is either traceable to a real input or visibly empty — there is no third state, and that property is enforced by the compute layer, not by reviewer diligence.

@@ -99,9 +107,9 @@ Two characteristics of the reporting are worth stating because they are unusual.

## Holdback, the lien period, and statutory clocks

Construction contracts are subject to statutory holdback (retainage) — a defined percentage of every certified payment withheld by the owner, released once a lien period during which unpaid suppliers can register a claim against the building expires with no claims registered. The design accounts for three consequences this creates: holdback applies against a certified payment application as a whole, not just against subcontract work; different kinds of work carry different lien periods, so parties on the same project become releasable on different dates; and the relevant statutory clocks run in working days, not calendar days, making a correct working-day calendar a legal requirement of the software rather than a scheduling convenience. The subcontract chain's certification and retainage mechanics are built; the working-day calendar and statutory-clock model is the largest piece of this section still unimplemented, and it gates the payment-cycle reporting that would sit on top of it.
Construction contracts are subject to statutory holdback (retainage) — a defined percentage of every certified payment withheld by the owner, released once a lien period during which unpaid suppliers can register a claim against the building expires with no claims registered. The money ledger's own chart of accounts tracks this per contracting relationship, and a named, explicit retainage-fund policy (one holdback fund per contract, versus one pooled fund across every trade on a project) is a configurable decision this engine makes visible rather than a silent assumption — the real statutory question of which model applies to a multi-trade project with no single prime contractor is, in the jurisdiction this pilot is grounded in, genuinely unresolved by case law, and the engine reflects that by making the choice a named setting rather than picking a side quietly. A large-contract threshold that triggers a legal requirement for progressive holdback release on a phased or annual basis, rather than only at final completion, is also modeled as a structural fact the engine checks, not a computed release amount.

**Why it matters:** a holdback released one day early, or a lien period miscounted by even one working day, is a real compliance failure under lien law, not a rounding error the software can quietly absorb — which is exactly why the calendar model is treated as a legal requirement rather than a scheduling nicety.
The actual statutory payment clock — cascading a real due date for the owner's payment and then the general contractor's payment to its subcontractor from the date a proper invoice is received — is computed in the sibling accounting engine's own reporting; see [[tool-accounting]] for that half of the mechanism. The two engines deliberately do not duplicate this logic: retainage policy and fund tracking live here, against the physical-work ledger; statutory date arithmetic lives there, against the money side of the same relationship.

---

@@ -115,7 +123,9 @@ Three pieces of the engine's domain were deliberately built as standalone platfo

## Product topology and the free/paid boundary

`tool-construction` is one component in a larger family: the construction ledger itself; the sibling accounting engine, [[tool-accounting]], which is designed to receive a one-way feed of dollar cost from it; `tool-typeset`, the shared document renderer now doing the production rendering for both engines; and the proposed [[tool-payroll]] engine, which is designed to receive a one-way feed of hours and labour class from the construction ledger as timecards. Pilot-scoped sibling crates for the accounting and payroll engines are scaffolded alongside the construction pilot, but the cross-engine feeds themselves are not yet wired — the dollar-side and payroll integrations wait on the real actuals data described above.
`tool-construction` is one component in a larger family: the construction ledger itself; the sibling accounting engine, [[tool-accounting]], which is designed to receive a one-way feed of dollar cost from it; `tool-typeset`, the shared document renderer now doing the production rendering for both engines; and the proposed [[tool-payroll]] engine, which is designed to receive a one-way feed of hours and labour class from the construction ledger as timecards. Pilot-scoped sibling crates for the accounting and payroll engines are scaffolded alongside the construction pilot, but the cross-engine feeds themselves are not yet wired.

A distinct question from any of the above is what happens when a legal entity owns more than one building, or when a contractor operates more than one project at once — two genuinely different cases the engine keeps separate. Several buildings under one legal entity, each with its own construction cost and schedule but sharing one set of financial and statutory obligations, is handled within this engine's own reporting: one construction ledger per building, rolling up to whatever financial reporting that entity's accounting engine already produces. A contractor or property manager operating several separate, legally distinct developments at once is a different, platform-wide capability rather than something this engine builds for itself — see [[financial-and-construction-tools-overview]] for the fuller treatment of both cases and how the platform's broader aggregation layer fits in.

The platform's archive substrate and terminal are free (Apache-2.0); cross-archive aggregation is the paid boundary that applies platform-wide. `tool-construction` is designed as a separate, second commercial surface on top of that — what would be sold is the domain engineering itself (the quality-scoring schema, the earned-value mathematics, the ledger mechanism), not a markup on infrastructure that is already free.

@@ -133,13 +143,14 @@ The platform's distribution rules classify `tool-*` components as internal opera

## What is not yet built

The boundaries stated at the top are worth restating precisely. Not yet built: the dollar-side cost ledger (payables, payroll postings, holdback dollars) and with it any actual-cost reporting — the pilot has no invoice, payment, or payroll document in its pipeline, and the engine reports that absence rather than modelling around it; an independent installed-quantity measurement source, which gates real earned-value reporting; the working-day calendar and statutory-clock model; the one-way feeds into [[tool-accounting]] and [[tool-payroll]]; the archive storage adapter that would persist ledger data through the platform's own record store; the sale-transition access-transfer mechanism; and any console or terminal surface — the two proposed screens (a ledger table view and a work-package/quality panel) remain without a build slot on the platform's fixed twelve-function-key terminal, and the toolchain is operated entirely from the command line.
The boundaries stated at the top are worth restating precisely. Not yet built: an independent installed-quantity measurement source, which gates real earned-value reporting; the one-way feeds into [[tool-accounting]] and [[tool-payroll]]; the archive storage adapter that would persist ledger data through the platform's own record store; the sale-transition access-transfer mechanism; and any console or terminal surface — the two proposed screens (a ledger table view and a work-package/quality panel) remain without a build slot on the platform's fixed twelve-function-key terminal, and the toolchain is operated entirely from the command line. Also not yet built: a real, prospective portfolio-roll-up view is only meaningful once a legal entity's second building exists to roll up against it — the reporting machinery is real and tested, but today's pilot has exactly one building on file.

Open design questions that remain genuinely unresolved include whether quality sign-offs need cryptographic signing given their potential legal weight in a defect claim, whether individual-performance scoring belongs inside this system or stays a separate concern, and what triggers and authorizes the sale-transition access transfer and interfaces with a real legal closing process.
Open design questions that remain genuinely unresolved include whether quality sign-offs need cryptographic signing given their potential legal weight in a defect claim, whether individual-performance scoring belongs inside this system or stays a separate concern, what triggers and authorizes the sale-transition access transfer and interfaces with a real legal closing process, and — a real, unresolved statutory question, not an engineering gap — whether a multi-trade project with no single prime contractor should hold one pooled retainage fund or one fund per contract, a choice case law does not yet settle in the jurisdiction this pilot is grounded in.

**Why it matters:** none of these gaps is hidden inside a passing test or a silent fallback — each is named here so a reader evaluating the engine knows precisely which claims are proven today and which are still stated intent.

## See also

- [[tool-accounting]] — the sibling accounting engine designed to receive a one-way cost feed from this ledger
- [[tool-accounting]] — the sibling accounting engine designed to receive a one-way cost feed from this ledger, and where the statutory payment-clock computation this article's holdback section refers to actually lives
- [[tool-payroll]] — the proposed payroll engine designed to receive a one-way timecard feed from this ledger
- [[financial-and-construction-tools-overview]] — the fuller treatment of multi-building and multi-project aggregation this article's Product topology section refers to