Domain model

​

Published packages

• base — no first-party dependencies. Owns EntityId, shared primitives, rate-group taxonomy, build-up grouping, duration helpers, the stored-config contract (WorkItemComponentCalculator and its full type closure), and the organisation/project time-zone resolver and date-in-zone helpers (base 1.5.0).
• calculators — depends on base. Re-exports every name from the stored-config contract unchanged so its public surface is identical to pre-D85.
• pricing — depends on base.
• domain — depends on base and pricing only. It no longer depends on calculators.

​

Core entities

• Project
• Project membership (ProjectDirectoryEntry, ProjectAccessRequest)
• Project contract profile
• Party (companies register: unified client, supplier, and subcontractor record)
• Client, Supplier, Contractor (legacy compatibility types retained for consumers still being migrated)
• Rate item, rate option, and rate option scope (RateOptionScope)
• Activity and activity component
• Estimate
• Estimate section
• Takeoff measurement
• Work item and work item component
• Programme item and dependency
• Subcontractor package and bid rate
• Contract baseline and baseline item
• Variation, variation line, variation revision, and variation event
• Drive source, sync connection, sync run, and synced file (cloud-drive document sync)
• Scheduler person, plant, crew, assignment, unavailability, project requirement, project resource (crew-scheduling M1), and plan task (plan M0)

​

Modelling rules

• Project is the root for project-specific workflows.
• IDs are strings.
• Geotagged entities use a shared geotag shape.
• Money, units, dates, quantities, and confidence values use explicit fields.
• Module APIs reference shared records by ID rather than copying source records.

​

Project fields

​

Project membership access

​

ProjectRoleCode

type ProjectRoleCode = "member" | "lead";

​

ProjectDirectoryEntry

​

ProjectAccessRequest

​

Project readiness wire contract

​

Companies register

​

Status lifecycles

​

Project status

• M1 added the full enum (lost, archived) and the server-ownership guard that prevents status changes via the project update endpoint.
• M2 adds POST /projects/:id/transition with four standalone actions (begin_estimating, revert_to_lead, start_project, complete), the admin override action (admin_set_status), and the append-only project_status_history table. Coupled actions (submit_tender, revise_tender, mark_won, mark_lost, reopen, archive, and unarchive) returned 501 until M3.
• M3 added coupled actions that orchestrate a matching status change in stralos-api-estimate under the same correlationId. Each action uses an intent-first protocol: tx1 records one pending transition, the peer service runs its guarded action, and tx2 atomically commits history and the project status. Definitive peer rejections abort; ambiguous failures stay pending for the lifecycle sweeper. The partial unique index on pending history enforces one in-flight transition per project. archived_from preserves the status restored by unarchive, and admin overrides targeting awarded run the same baseline guard as mark_won.
• M4 adds GET /projects/stats, which returns current project counts by status (countsByStatus) and a win-rate summary (winRate) over a configurable time window. Window boundaries are calendar days in the organisation’s IANA timezone (organisations.timezone, defaulting to Pacific/Auckland). The timezone field is server-owned and not editable via the API.
• Crew-scheduling M3 (current) adds GET /projects/statuses (batch S2S read for the scheduler service), the nullable endDate project window field, and nullable colour fields on both projects and companies.
• Nav M5 (0.11.0) adds projectStatusLabels.ts — the single authoritative resolver for project status display names. See Project status display names below.

​

Project status display names

1. If the setting list is still loading, failed to load, or returned empty, isFallback is true and resolveProjectStatusLabel humanises the raw enum value using formatStatusLabel (e.g. "estimating" → "Estimating", "IN_PROGRESS" → "In progress"). Do not echo the raw fallback label verbatim — it is lowercase and intended only as a built-in placeholder.
2. If the list loaded, the setting-list label is used verbatim. A platform-admin relabel (e.g. "estimating" → "Tendering") wins over any seeded or code-side value.
3. If the loaded list has no row for a given value (a status added to the enum before the list was reseeded), resolveProjectStatusLabel falls back to formatStatusLabel.

​

Estimate kind

​

Estimate outcome

​

Estimate status

​

Estimate PRD 210 fields

• M1 added the server-ownership guard that prevents setting status or version on create or update.
• M3 added POST /estimates/:id/transition with the full state machine, tender revision snapshots (estimate_revisions table), status history (estimate_status_history table), the pending-transition sweeper, and baseline-bound award logic.
• Org-security M3 applied FORCE RLS and organisation_id to all twenty estimate tenant tables, introduced the three-connection runtime layer, and added the SECURITY DEFINER portal resolver for the unauthenticated subcontractor portal. See Organisation security for the isolation model and Runbooks for the deployment sequence.
• Domain 3.9.0 (PRD 210 phase 1) added EstimateKind, EstimateOutcome, TenderEstimateStatus, DeliveryEstimateStatus, and the kind, isPrimary, outcome, hiddenAt, and sourceEstimateId fields on Estimate. EstimateStatus widened from the six tender values to TenderEstimateStatus | DeliveryEstimateStatus.
• PRD 210 phase 2 lifted the one-tender-per-project constraint (migration 0093). A project may hold multiple tender estimates while its Multiple estimates project setting is on.
• PRD 210 phase 3 implemented the multi-estimate award action: several tender estimates can be submitted at once. Marking the project won names one estimate as the winner (outcome: 'won', isPrimary: true); the others receive outcome: 'not_awarded' and are hidden. Project-level actions (reject, archive, reopen, unarchive) fan out to the active tender estimates under one correlation ID.
• PRD 210 phase 4 implemented the Delivery copy, tracking sell and sign-off state machine. The Delivery routes are live only where ESTIMATE_DELIVERY_ENABLED is on (dev; off in test and prod).

​

Deprecated Estimate fields

​

Work item component calculator

​

Crew scheduling model

​

Project rate rules

​

Rate-group taxonomy

​

Wire tokens and display labels

• Use the labels exactly as listed above: Plant & Vehicles and Materials, not slash-separated or “Other Materials” variants.
• The subcontractors group describes a rate item that is priced from a subcontractor’s rate. It is not the same as the subcontract-BID pricing mechanism (pricing_source = "subcontract:{bidRateId}"), which uses separate mirror rows that are excluded from totals.
• The disposal group is authoritative-only. No legacy sniff vocabulary exists for it, so a NULL-group rate can never fall through to disposal. Only rates carrying an explicit disposal token reach that group.
• The category name column on a rate item is a display mirror of the referenced category, refreshed by the read-path reconcile. A rate whose reference no longer resolves has a NULL group and shows in the rates page’s Unresolved category queue — NULL means “the category no longer resolves”, not “nobody classified it”.

​

Item-category taxonomy

​

Classifier

​

Rate-group contract

​

Rate option ownership and locations

​

RateOptionScope

type RateOptionScope = "organisation" | "supplier";

​

RateOption

• scope: "organisation" — our own price list. supplierId is null; the organisation’s identity comes from the shell’s membership projection, not from a field on the option.
• scope: "supplier" — a supplier’s price. supplierId is a parties.id in api-global. null is not permitted.

​

Rate option normalisation

1. If the option carries both conversionNumeratorUnit and conversionDenominatorUnit, those define the scalar’s meaning — no inference is performed.
2. Otherwise, orientation is inferred from the rate group only: t/m³ for quarry_materials. No other pair inference is applied.

• disposal options carry no conversionFactor. A disposal option that carries one is excluded as conversion_missing. A valid disposal option priced in a different unit from the target is excluded as disposal_unit_by_substance, with its own price and unit retained for display.
• quarry_materials options require a positive, finite conversionFactor no greater than 1,000,000, including for an equal-unit comparison.
• Both non-empty orientation halves override inference. Exactly one non-empty half is corrupt and returns conversion_missing; neither half falls back to category and unit-pair inference.
• Normalisation accepts NZD only. Any other currency returns currency_mismatch.

​

Whole-stock per-run ordering (domain 3.5.0)

​

RateItem.unit retirement

​

RateSummary.modeUnit

​

RateSummary.suppliers and hasOrganisationOptions

​

Calculations

​

Time zones

​

The effective time zone

effective = project.timezone ?? organisation.timezone ?? DEFAULT_TIME_ZONE

​

Exported functions

​

Usage rules

• Always store the result of normaliseTimeZone — never store the user’s raw input, which may have inconsistent casing.
• A value missing from listTimeZones() at read time should still be offered by the caller as the current selection; do not silently drop it.
• dateInTimeZone and todayInTimeZone are the authoritative source for "valid from" comparisons and schedule day logic. Do not use toISOString().slice(0, 10).
• resolveEffectiveTimeZone is the only resolver. Do not re-implement the three-level fallback in a service or remote.

​

Contract variations model

• One active baseline per estimate (enforced by a partial unique index on estimate_id WHERE superseded_at IS NULL).
• Variation references (VO-001, VO-002, …) are allocated from a per-estimate monotonic counter — never client-supplied.
• draft, assessed, and priced resting statuses are server-derived from line count and assessment state; submit, withdraw, approve, and reject require an explicit action.
• Every line mutation and status transition appends a row to the estimate_variation_events table (append-only).
• Submitting a variation freezes an immutable revision snapshot. Revisions are numbered per variation and cannot be altered.
• Line valuation follows NZS 3910 clause 9.3 using exact scaled-integer arithmetic with a single half-up rounding to the cent.

​

Cloud-drive document sync

• A document’s estimateId is EntityId | null. A synced document starts project-scoped and unrouted (null). Route it via POST /documents/:id/route to assign it to an estimate.
• SyncedFileStatus distinguishes a transient error (retried up to five times per version marker) from a terminal failed (quarantined until a new version marker or explicit re-include).
• CreateSyncConnectionResponse is a three-way discriminated union: created: true (fresh insert), reactivated: true (soft-deleted mapping reactivated), or neither (idempotent no-op on an already-live mapping).
• The raw proof nonce is not stored in domain types or returned as its own API field. Registration returns only the derived proof file name while verification is pending.

​

Package activity domain contract

​

Activity package fields

​

ActivityComponent optionality fields

​

WorkItemComponent package snapshot fields

​

packageAddons entry shape

​

WorkItemComponent day-rate fields

​

WorkItemComponentDayRate shape

​

Pricing behaviour

​

Workbook mapping