Estimate service

​

Overview

​

Multiple estimates (PRD 210)

​

Schema (migrations 0089, 0090, 0093)

• estimate_work_items_source_suggestion_estimate_live_unique — (organisation_id, estimate_id, source_suggestion_id).
• estimate_bid_rates_source_suggestion_package_live_unique — (organisation_id, package_id, source_suggestion_id).

​

Project estimate routes and the Multiple estimates setting

• GET /projects/:projectId/estimates — the project’s live tender and Delivery estimates, primary first; hidden estimates only with includeHidden=true; saved versions never. The response also carries multipleEstimatesEnabled.
• POST /projects/:projectId/estimates — a new, non-primary tender: blank, or a draft copy of a live tender of this project (from.estimateId) or of a saved version (from.versionId). from.revisionId returns 422 copy_from_revision_unsupported.
• PATCH /estimates/:id — rename, unique per project, case-insensitive.
• POST /estimates/:id/make-primary — refused for hidden, Delivery and deleted estimates. After the commit, it pushes the new primary to api-rates as the project’s default estimate (PUT /estimate-rates/defaults).
• DELETE /estimates/:id — a soft delete (deleted_at, deleted_by). Refused for the primary (estimate_is_primary), a Delivery estimate, the won estimate, and an estimate with a committed tender revision (estimate_has_revision). A repeat DELETE is a 204 no-op.

​

Project lifecycle lock

​

Two-service copy job (§9.2)

1. An estimate_copy_jobs row is inserted as pending, with the target id chosen and the job id as the correlation id.
2. The project is backfilled into api-rates (idempotent). The backfill must finish before the graph copy: api-rates reads an estimate-less project row as belonging to any of the project’s estimates, so a copy made first would let the new estimate read the source’s rate rows. The backfill records the project’s primary as api-rates’ default estimate if none is recorded. What matters is that api-rates records some default, not which: since api-rates’ contract migration (0059) every project row carries its estimate and the copy names the source explicitly, so a default that lags the primary after make-primary or an award is fine. Only a project with no recorded default is refused, with 409 rates_default_estimate_mismatch (the code name predates this rule). The project rates are then copied onto the target id and api-rates’ id maps are stored on the job (rates_copied). api-rates replays the same maps for the same (target, correlation) pair.
3. One estimate transaction at repeatable read: the header, the full graph (copyEstimateGraph), the parity assertion, the caller’s own rows (for example the estimate_versions row), and the job marked done. Parity asserts that the copied totals match the source to the cent and that work-item, calculator, acceptance and override counts match; a mismatch throws 500 copy_parity_failed and nothing is half-copied.
4. After the commit, carried rate-exception acceptances are re-fingerprinted through the copy’s id maps (src/estimates/acceptanceRefingerprint.ts). This is best-effort: a failure leaves the acceptances as copied and the copy stands.

​

Saved versions as estimate graphs

• keep — rows are copied exactly, with no recompute. Prices match what the version captured.
• reprice — rows are copied and recomputeEstimateTotals runs against today’s rates.

​

Quote numbers (migration 0110)

​

Tender revision versions (migration 0109)

• The version is named Tender revision N (submitted D MMM YYYY) from the latest committed estimate_revisions row. The date uses the project’s effective timezone when the caller is a user, otherwise Pacific/Auckland. recompute is off, so the version carries the submitted totals.
• The transition body’s optional versionName (trimmed, max 200 characters) replaces that default name; blank falls back to it. feature-estimate’s Revise tender side sheet (ReviseTenderSheet.tsx) prefills the default and sends what the estimator leaves. Reopen arrives from api-global, which does not forward a name, so it always takes the default. A version already saved for the same tender revision keeps its name.
• estimate_versions.tender_revision_id with the partial unique index estimate_versions_tender_revision_unique keeps one version per tender revision. A replay, a retry after a refused transition, or a concurrent revise reuses the existing version.
• An estimate with no committed revision saves nothing and transitions as before.
• If the save fails, nothing is transitioned: 503 for revise and 422 for reopen (so api-global refuses the reopen and shows the message as is), both with code: "tender_revision_not_saved". The refusal gate in src/lifecycle/transitionEngine.ts returns a refused boolean rather than the reply: a Fastify reply is thenable, so await reply.send(...) resolves to undefined and would read as “not refused”, letting the handler carry on into the transition.
• GET /estimates/:id/versions items carry tenderRevision and tenderRevisionId. GET /estimates/:id/revisions items carry tenderPrice (the snapshot header’s contract total, excluding GST), totalCost (the sum of top-level items’ frozen cost) and version (the linked saved version, or null).

​

Tender copies and download log

• estimate_tender_download_options: one row per estimate holding the Tender download tab’s saved choices (sections, documentIds, includeSubItems, includeCostBreakdown, leavePricesOut). A row that no longer parses reads as never saved.
• estimate_tender_copies: the as-submitted files, one row per revision and format (pdf, xlsx, docx; 0116 added docx), stored as bytea with a SHA-256, the options the file was drawn with and, since 0115, the tender layout. The unique index estimate_tender_copies_revision_format_unique makes inserts idempotent (ON CONFLICT DO NOTHING); rows are never updated.
• estimate_tender_downloads: every tender file download, with revision, copy (stored, live or draft), format, pricesLeftOut, who and when.

​

Project rates scoped per estimate

​

Multi-estimate project lifecycle (phase 3)

• submit calls the global submit_tender peer only when the count goes from 0 to 1. Later submits find the project already submitted and commit locally.
• revise calls the global revise_tender peer only when the count goes from 1 to 0. Revising while other submitted estimates remain commits locally.

• keeps its status (submitted stays submitted, as the record of what was tendered);
• is read-only — any write returns 409 estimate_frozen with hidden: true;
• is excluded from the project-level fan-out actions.

• reject (mark lost) — estimates in draft, review or submitted.
• archive — every non-archived active estimate.
• reopen and unarchive — only the estimates the most recent reject or archive fan-out moved, so an estimate rejected or archived individually earlier is not revived.

​

Estimate soft delete and retention

​

Delivery estimate (PRD 210 phase 4)

​

Delivery routes

​

Delivery copy

• kind = 'delivery', not primary, no outcome, source_estimate_id = won estimate, source_revision_id = won revision.
• contingency_pct = 0 (R17: contingency is not carried into Delivery).
• Every rate-exception acceptance in force on the won estimate is re-fingerprinted through the copy’s id maps, so accepted exceptions hold on Delivery.
• A parity assertion after the copy confirms that Σ top-level total_price, Σ total_cost, Σ tracking sell, and accepted rate-exception count all match the won revision to the cent. Any mismatch rolls the whole copy back as 500 copy_parity_failed.

​

Tracking sell

​

Sign-off state machine

draft ──request_sign_off──▶ in_sign_off ──approve (any ONE lead)──▶ signed_off
  ▲                           │  reject (any lead) / withdraw            │
  └───────────────────────────┘                                          │
  └──────────────────────────── reopen (any lead) ───────────────────────┘

​

Delivery edits

​

EstimateAwarded event consumer

• With ESTIMATE_DELIVERY_ENABLED off: the event is acknowledged and nothing is created. A later “Create delivery” request against the same project reads the won revision from the active baseline.
• With the switch on: createDeliveryForProject runs. The copy is idempotent, so a redelivered event finds and returns the existing Delivery.

​

Award reversal

​

Estimate list fields

​

Migration 0091

​

Billing access guard

• ORG#<orgId>: the company’s billing entitlement.
• LINK#<linkId>: the contractor-company link state, read on every request from a contractor person. Without the LINK#* grant the read is AccessDenied and the guard answers 503 billing_unavailable.

​

Required startup configuration

​

Lambda database pools

• max: 2 — one connection for the request’s transaction, one spare so a nested checkout does not deadlock against itself.
• connectionTimeoutMillis: 5000 — a pool checkout that cannot acquire a slot within 5 seconds throws, which the safe error handler returns as a retryable 503 with Retry-After: 5.

​

Lambda connection pool management

​

Estimate lazy-create flag

​

ProjectCreated event consumer

​

How it works

​

Deduplication and atomicity

• If the insert is new, the handler runs and both writes commit together.
• If the insert conflicts (duplicate delivery or a backfill republish), the handler is skipped. The estimate insert’s ON CONFLICT DO NOTHING means a second event for the same project is also a no-op.
• If the handler throws, both the dedupe row and the estimate insert roll back, and the record is redelivered.

​

Tenant scope

​

Billing

​

Local development

​

Infrastructure

​

ProjectRatesChanged event consumer

​

How it works

1. Mints an estimate-reprice service token for the event’s organisation through api-global’s mint-for-estimate-reprice alias (src/service-tokens/repriceServiceToken.ts). An event has no user, so the peer reads carry this token instead of a user bearer.
2. Runs the shared re-price, which reads current state from stralos-api-rates and stralos-api-global within the 8-second peer budget and writes only the lines that change.

​

Deduplication and atomicity

​

Outcomes

​

Infrastructure

​

Supplier and location name sync

​

Name write guard

• The stored version is NULL (a selection made while api-global was unreachable, or a row that has not yet been through reference fill).
• The stored version is older than the incoming version.
• The stored version equals the incoming version but the stored name differs. This case repairs a name that the reference fill stamped at the current version without writing the name — leaving a wrong or NULL name that looked current to a version-only guard.

​

PartyChanged / LocationChanged event consumer

​

Daily name reconcile

1. Discovery — on the BYPASSRLS platform connection, find every organisation that has a live line on an editable estimate carrying a supplier or location reference, or a selection with no scope.
2. Reference fill — for editable lines that carry a price selection but no scope (a UI price pick before PRD 211 PR C scoped its own writes), run fillOrganisationReferences using the runtime role and an estimate-reprice token for the api-rates read. This fill writes scope, ids, and versions but never a name; the repair step in step 4 brings the names.
3. Read current names — for each organisation, collect the distinct stored (supplier id, version, name) and (location id, version, name) triples on live lines of editable estimates, then read the current names and versions from api-global rate-references/resolve-batch. A failure on this read fails that organisation and writes nothing more for it.
4. Repair — apply every id whose stored pair is stale using the same applyNameChange guard the event consumer uses. A non-zero namesChanged count on an environment with a live consumer means an event was lost or is still in flight.

​

DocumentUsagesChanged event publisher

​

Soft-delete programme (migration 0067)

• estimate_work_items
• estimate_work_item_components
• estimate_sections
• estimate_takeoff_measurements
• estimate_tender_clauses
• estimate_programme_items
• estimate_programme_dependencies
• estimate_variations
• estimate_variation_lines
• estimate_calculators

• DELETE returns 204 No Content on success. A repeat DELETE on an already-deleted row also returns 204 and changes nothing. The calculator delete is the exception: it keeps its 200 with counts, and a repeat returns 0 for both.
• GET by ID returns the row with deletedAt set; it is not filtered out.
• Any write (PUT, sub-item, component creation, etc.) to a deleted row returns 409 { code: "deleted" }.
• List and aggregate endpoints exclude deleted rows; callers see only live rows.

• A work-item delete still detaches its takeoff links and removes it from subcontract package membership. A later restore would not bring either back.
• A section delete still moves its items to Unsectioned (it clears section_id explicitly).
• Pricing, tag, bid, rate-attachment, calculator-link and baseline rows stay attached to a deleted item; readers look past them.
• Re-accepting a bid suggestion whose target item was deleted returns 409. The bid-rate PUT and DELETE routes, which also returned 409 deleted here, are retired.
• A version restore (restoreSavedVersion in src/versions/versionRestore.ts) stamps every live row of the working copy with one shared stamp, then copies in the rows from the version’s frozen estimate graph. This covers work items, components, sections, tender clauses, takeoff measurements, map sheets, subcontract packages, bid rates, programme items, and programme dependencies. Tag links and pricing rows are derived and are still replaced. A version’s graph holds only live rows and leaves out bids of deleted items. Versions saved before build 0089 have no graph copy and are read-only; a restore attempt returns 409 version_read_only.
• Stale calculator rows swept by the reconcile are soft-deleted (stamped), not hard-deleted. When a re-resolve or a project-rate re-price retires a managed ticked companion, it stamps the companion and every live row hanging off it (children and companions, to any depth) with one shared stamp, using liveComponentSubtree and stampComponents in src/pricing/retiredComponents.ts. A component delete still strips its pricing overrides.
• A deleted work item keeps its number, and a later live item may take the same number.

​

Subcontract packages and bid rates (migration 0071)

• The bid-rate CRUD routes (/subcontract-bid-rates and GET /subcontract-packages/:id/bid-rates) are retired and return 404. DELETE /subcontract-bid-rates/:id used to stamp the bid and its mirror component with one stamp and fall the work item’s pricing back to internal. Bids now arrive only through the contractor portal and accept-bid-suggestion. A bid already stamped deleted is still excluded from the return review and cannot be selected as a pricing source. The estimate_subcontract_bid_rates table and components.subcontract_bid_rate_id stay.
• There is no package delete route. A package becomes deleted through a version restore, and any bid write under a deleted package returns 409 { code: "deleted" }.
• The bid source-suggestion unique index is now live-only, so a deleted bid does not block a fresh accept of the same document suggestion.
• estimate_subcontract_packages_token_unique deliberately still spans deleted rows: a deleted package keeps its portal token, and no other package can be issued it.

​

Takeoff map sheets (migration 0073)

​

Snap attachments

{ measurementId: string /* uuid */; vertex: number }             // integer >= 0
{ measurementId: string /* uuid */; segment: number; t: number } // segment integer >= 0, t in 0..1

​

Map takeoff (migrations 0073 and 0074)

​

Provisional sum enforcement (migrations 0077 and 0081)

​

Provisional sum rule (migration 0077)

• Data half. Every live provisional sum in a draft or review estimate loses what it carried: live components, live sub-items, calculator links and defaults, project-rate attachments, and pricing overrides are removed or soft-deleted. The item’s quantity is forced to 1 and its pricing row is reset to internal. Frozen estimates are left untouched.
• Trigger backstop. Database triggers (SQLSTATE PS001) refuse any later write that would store a live component, live sub-item, or quantity link on a provisional sum, or convert an item into a provisional sum while it still carries build-up. handleRouteError maps PS001 to 422 provisional_sum_no_build_up. Routes assert this themselves first; the triggers catch the twenty-odd other build-up writers so a missed path fails loudly.

​

Legacy row conversion (migration 0081)

1. Sub-items (with their programme subtree, measurements, package membership, and components) are soft-deleted first, while the parent still qualifies.
2. The parent’s live components are soft-deleted.
3. Calculator links and defaults pointed at the parent are removed.
4. Project-rate attachments are removed.
5. The pricing row is reset to internal with no overrides.
6. Last, the item’s item_kind flips to provisional_sum with allowance = old total_price, quantity = 1, cost = price = allowance, and quantity_link = NULL. The kind flips last so 0077’s trigger cannot fire while the row still carries build-up.

​

Retention Lambda

• Org purge. An organisation that api-global reports as disabled for at least ORG_OFFBOARDING_PURGE_AFTER_DAYS (default 90) has all of its estimate data hard-deleted, including soft-deleted rows and frozen estimates. Status is checked through the estimate-offboarding service token and re-checked before deleting. The clock lives in estimate_org_offboarding (migration 0070), whose purged_at records that the purge ran.
• erase-user. api-estimate stores user ids only as audit references, with no names, emails, or phone numbers, so the handler returns empty counts.

​

Build-up lines in an activity

• A time-unit line (hour, day, week, month) wraps by its own duration, as POST /work-items/:id/time-resource-activity does. An hourly line wraps into a per-day activity at the estimate’s hours per day.
• Any other line wraps into a one-day activity with daily production equal to the item quantity (or 1), and the line inside is charged whole_activity.

• POST /work-item-components and POST /work-items/:id/day-rate-lines take an optional wrapInActivity: true at the top level. With it, a quantityBasis is 422 wrap_quantity_basis_not_allowed, and on components a delivery link is 422 wrap_delivery_link_not_allowed. The component response carries activityContainer (null when not wrapped). The flag is opt-in on the API; feature-estimate sends it for every new top-level line from the quick-add row, the line editor and a day-rate pick (WorkItemsPanel.tsx, dayRateLines.ts). Edits and lines added inside an activity never carry it. A new time-based labour or plant rate still goes through time-resource-activity.
• POST /estimates/:estimateId/work-items/insert-project-rate (src/routes/projectRateRoutes.ts): a target naming parentComponentId adds the line at the end of that activity (library activities included; the line inherits its activityId). Only total is accepted there (422 insert_per_unit_in_activity); the line is charged whole_activity in an activity with daily production, otherwise stored per unit of the item so its total is the typed quantity. Without parentComponentId the line goes into a new activity named after the rate, a per_unit quantity becoming quantity × the item’s quantity. Other refusals: insert_target_not_activity, insert_activity_deleted, insert_fixed_price_package, insert_zero_quantity_item.
• Calculators always wrap. A new default destination, or a new layer link, that names a work item without an activity creates one activity per calculator per item, named after the calculator. Links and defaults that already sat on the bare item are left.

​

Pricing route error handling

​

Price choice status on materialised lines

​

Database columns

​

Materialise response

• status — 'pinned', 'single_option', 'choice_required', 'no_options', or 'unavailable'.
• candidateOptionCount — how many live options were available when the status was assessed (set on 'choice_required' and 'no_options'; null for other statuses).
• suggestedRateOptionId — the id of the suggested option when exactly one option is at the project location and status is 'choice_required'; null otherwise.

​

Materialisation: null unit cost for lines needing a choice (D10)

​

Tender submission gate (D10)

• Status: 422 Unprocessable Entity
• Code: price_choice_required
• Message: This tender can't be submitted: N line(s) still need a price choice. Choose a price for: <item number item name: component name>; ...
• Body: { lines: [{ componentId, componentName, workItemId, workItemNumber, workItemName }] } — live rows only, ordered by work item sort order then component sort order.

​

Activity promotion: no unit cost for unresolved choice lines (D10)

​

Write-path behaviour

This line needs a price choice: choose which rate option it takes for this project.

​

Price-selection columns and value overrides (PRD 211, migrations 0086–0095)

​

Drop of work_items.pricing_source (migration 0086)

​

Price-selection columns (migration 0087)

​

Manual value overrides table (estimate_component_value_overrides)

​

PUT /work-item-components/:id/value-overrides route

• The server diffs each supplied field against the line’s current original. Only fields that differ from the original are stored as override rows. A field supplied with its current original value is a no-op for that field.
• A quantity override on an activity-instance child is refused with 422.
• A unit or unitCost override on a line with a frozen pricing selection is refused with 422.
• The estimate is recomputed after every successful write.

​

Saved versions and tender snapshots

• v32 (PR A, 0087) — component nodes carry the selection columns, and each work-item node gains componentValueOverrides, the item’s active manual value overrides.
• v33 (PR C, 0094) — the pricing node loses componentOverrides, and the component node’s rateOptionId is the generated pin.
• v34 (migration 0097) — component nodes carry the day-rate provenance columns.

​

Tender check

​

Backend contract tests

pnpm test:contract

NODE_OPTIONS=--max-old-space-size=768 nice -n 19 pnpm test:contract

​

Test boundaries

​

Covered contracts

​

Sending contracts

​

BC-08: Pricing fan-out (estimate → rates)

​

BC-09: Pricing geography and organisation settings (estimate → global)

​

BC-14: Project lifecycle transition (estimate → global)

​

BC-15: Tender check jobs (estimate → documents)

​

Receiving contracts

​

BC-02: stralos-api-assistant → stralos-api-estimate

​

BC-13: stralos-api-global → stralos-api-estimate

​

Frozen estimate writes

​

Adding new contracts

• A valid request with a representative response.
• Required and optional parameters.
• Wrong types and out-of-bounds values.
• Status codes.
• Non-empty response data.
• Null and omitted fields.
• Error response shapes.