elecevm 0.1.0__py3-none-any.whl

elecevm/__init__.py

@@ -0,0 +1,30 @@
+"""elecevm — an earned value management engine for electrical construction.
+
+Reference implementation of *Earned Value Management for Electrical
+Construction — A Recommended Practice for Specialty Contractors*
+(``docs/standard.md``).  Pure Python; charts and .xlsx ingest are optional extras.
+"""
+
+__version__ = "0.1.0"
+
+from .calendar import WeekCalendar, WorkCalendar  # noqa: E402
+from .models import (Activity, Budget, ChangeOrder, CostTransaction, CostType, Discipline,  # noqa: E402
+                     EVMethod, QuantityRecord)
+from .config import ACBasisRule, Project, load_project, project_from_dict  # noqa: E402
+from .allocation import Baseline, allocate_hours, build_baseline, forecast_remaining  # noqa: E402
+from .actuals import WeeklyActuals, apply_basis, bucket_transactions, reconcile, restatements  # noqa: E402
+from .rules_of_credit import DEFAULT_RULES, RuleOfCredit, earned_fraction, get_rule  # noqa: E402
+from .evm import StatusSnapshot, compute_status, health_checks, measure_activities  # noqa: E402
+from .status_log import LockedWeekError, StatusLog  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "WeekCalendar", "WorkCalendar",
+    "Activity", "Budget", "ChangeOrder", "CostTransaction", "CostType", "Discipline", "EVMethod", "QuantityRecord",
+    "ACBasisRule", "Project", "load_project", "project_from_dict",
+    "Baseline", "allocate_hours", "build_baseline", "forecast_remaining",
+    "WeeklyActuals", "apply_basis", "bucket_transactions", "reconcile", "restatements",
+    "DEFAULT_RULES", "RuleOfCredit", "earned_fraction", "get_rule",
+    "StatusSnapshot", "compute_status", "health_checks", "measure_activities",
+    "LockedWeekError", "StatusLog",
+]

elecevm/actuals.py

@@ -0,0 +1,230 @@
+"""Actual cost: transaction-date bucketing, basis rules, reconciliation (RP §7)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from .calendar import WeekCalendar
+from .config import ACBasisRule
+from .models import CostTransaction, CostType
+
+Key = Tuple[str, str]  # (discipline, CostType value)
+
+
+@dataclass
+class ACBucket:
+    hours: float = 0.0
+    amount: float = 0.0
+
+    def add(self, hours: float, amount: float) -> None:
+        self.hours += hours
+        self.amount += amount
+
+    def copy(self) -> "ACBucket":
+        return ACBucket(self.hours, self.amount)
+
+
+@dataclass
+class WeeklyActuals:
+    """Actual cost by payroll week, discipline and cost type through the status week."""
+
+    status_week: int
+    buckets: Dict[int, Dict[Key, ACBucket]] = field(default_factory=dict)
+    post_status: List[CostTransaction] = field(default_factory=list)
+    source_totals: Dict[str, ACBucket] = field(default_factory=dict)  # by cost type value
+    notes: List[str] = field(default_factory=list)
+
+    def _iter(self, week: int, discipline: Optional[str], cost_type: Optional[CostType]):
+        for (disc, ct), b in self.buckets.get(week, {}).items():
+            if discipline is not None and disc != discipline:
+                continue
+            if cost_type is not None and ct != cost_type.value:
+                continue
+            yield b
+
+    def weekly(self, week: int, discipline: Optional[str] = None,
+               cost_type: Optional[CostType] = None) -> ACBucket:
+        out = ACBucket()
+        for b in self._iter(week, discipline, cost_type):
+            out.add(b.hours, b.amount)
+        return out
+
+    def cumulative(self, through: int, discipline: Optional[str] = None,
+                   cost_type: Optional[CostType] = None) -> ACBucket:
+        out = ACBucket()
+        for w in range(1, through + 1):
+            b = self.weekly(w, discipline, cost_type)
+            out.add(b.hours, b.amount)
+        return out
+
+    def totals_by_cost_type(self) -> Dict[str, ACBucket]:
+        out: Dict[str, ACBucket] = {}
+        for week in self.buckets.values():
+            for (_, ct), b in week.items():
+                out.setdefault(ct, ACBucket()).add(b.hours, b.amount)
+        return out
+
+    def disciplines(self) -> List[str]:
+        seen: List[str] = []
+        for week in self.buckets.values():
+            for (disc, _) in week:
+                if disc not in seen:
+                    seen.append(disc)
+        return seen
+
+    def to_dict(self) -> dict:
+        return {
+            "status_week": self.status_week,
+            "buckets": {str(w): {f"{d}:{ct}": [b.hours, b.amount] for (d, ct), b in row.items()} for w, row in self.buckets.items()},
+            "source_totals": {ct: [b.hours, b.amount] for ct, b in self.source_totals.items()},
+            "post_status_count": len(self.post_status),
+            "notes": list(self.notes),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "WeeklyActuals":
+        out = cls(int(data["status_week"]))
+        for w, row in data.get("buckets", {}).items():
+            for key, (h, amt) in row.items():
+                d, ct = key.rsplit(":", 1)
+                out.buckets.setdefault(int(w), {})[(d, ct)] = ACBucket(float(h), float(amt))
+        out.source_totals = {ct: ACBucket(float(h), float(amt)) for ct, (h, amt) in data.get("source_totals", {}).items()}
+        out.notes = list(data.get("notes", []))
+        return out
+
+    def copy(self) -> "WeeklyActuals":
+        return WeeklyActuals(
+            self.status_week,
+            {w: {k: b.copy() for k, b in row.items()} for w, row in self.buckets.items()},
+            list(self.post_status),
+            {k: b.copy() for k, b in self.source_totals.items()},
+            list(self.notes),
+        )
+
+
+def bucket_transactions(transactions: Iterable[CostTransaction], week_cal: WeekCalendar,
+                        status_week: int) -> WeeklyActuals:
+    """Bucket ledger lines by *transaction date* into payroll weeks (RP §7.1).
+
+    Lines dated after the status week-ending date are kept aside in
+    ``post_status`` — they are real cost, but they belong to the next status
+    period and must not leak into this one.  Lines dated before the project
+    start land in week 1.
+    """
+    actuals = WeeklyActuals(status_week=status_week)
+    for t in transactions:
+        week = week_cal.week_of(t.trans_date)
+        key = (t.discipline, CostType.parse(t.cost_type).value)
+        # raw totals of the whole pull, post-status lines included — what the source report prints
+        actuals.source_totals.setdefault(key[1], ACBucket()).add(float(t.hours), float(t.amount))
+        if week > status_week:
+            actuals.post_status.append(t)
+            continue
+        actuals.buckets.setdefault(week, {}).setdefault(key, ACBucket()).add(float(t.hours), float(t.amount))
+    return actuals
+
+
+def reconcile(actuals: WeeklyActuals, expected: Dict[str, Tuple[float, float]],
+              tolerance: float = 0.01) -> List[str]:
+    """Compare the raw totals of the pull with the source report's totals by cost type.
+
+    ``expected`` maps a cost type value (``"L"``, ``"M"`` …) to ``(hours, amount)``
+    as printed on the job-cost report.  The comparison uses the raw ledger
+    amounts captured at bucketing time (before any AC basis rule is applied)
+    and includes lines dated after the status week, because the report
+    includes them too.  Returns a list of mismatch messages; empty means the
+    pull reconciles exactly (RP §7.1).
+    """
+    issues: List[str] = []
+    totals = actuals.source_totals
+    for ct, (hours, amount) in expected.items():
+        got = totals.get(ct, ACBucket())
+        if abs(got.hours - hours) > tolerance:
+            issues.append(f"{ct}: hours {got.hours:,.2f} vs source {hours:,.2f}")
+        if abs(got.amount - amount) > tolerance:
+            issues.append(f"{ct}: amount {got.amount:,.2f} vs source {amount:,.2f}")
+    for ct in totals:
+        if ct not in expected:
+            issues.append(f"{ct}: in the pull but absent from source totals")
+    return issues
+
+
+def apply_basis(actuals: WeeklyActuals, rules: Dict[CostType, ACBasisRule],
+                billed_to_date: Optional[Dict[CostType, float]] = None) -> WeeklyActuals:
+    """Apply the per-cost-type AC basis (RP §7.3) and return a new table.
+
+    * ``raw``: unchanged.
+    * ``markup``: every week's amount × markup.
+    * ``billed``: weeks before status at ledger × markup; the status week is
+      replaced so the cumulative equals the supplied billed-to-date value.
+      The residual is shared across the status week's disciplines in
+      proportion to their status-week ledger amounts (or their cumulative
+      amounts if the status week is empty).  Hours are never adjusted.
+    """
+    out = actuals.copy()
+    billed_to_date = billed_to_date or {}
+    status = out.status_week
+    for ct, rule in rules.items():
+        if rule.method == "raw":
+            continue
+        factor = rule.markup
+        for week, row in out.buckets.items():
+            for key, b in row.items():
+                if key[1] == ct.value:
+                    b.amount *= factor
+        if rule.method == "billed" and ct not in billed_to_date:
+            out.notes.append(f"{ct.label}: billed basis declared but no billed-to-date value supplied; "
+                             f"carried at ledger × {factor:g}")
+        if rule.method == "billed" and ct in billed_to_date and status >= 1:
+            billed = float(billed_to_date[ct])
+            prior = sum(out.weekly(w, None, ct).amount for w in range(1, status))
+            residual = billed - prior
+            status_row = out.buckets.setdefault(status, {})
+            shares = {k: b.amount for k, b in status_row.items() if k[1] == ct.value}
+            if sum(shares.values()) <= 0:
+                shares = {}
+                for w in range(1, status + 1):
+                    for k, b in out.buckets.get(w, {}).items():
+                        if k[1] == ct.value:
+                            shares[k] = shares.get(k, 0.0) + b.amount
+            total_share = sum(shares.values())
+            if total_share <= 0:
+                disc = out.disciplines()[0] if out.disciplines() else "ALL"
+                shares = {(disc, ct.value): 1.0}
+                total_share = 1.0
+            for k, share in shares.items():
+                b = status_row.setdefault(k, ACBucket())
+                b.amount = residual * share / total_share
+            out.notes.append(
+                f"{ct.label}: status week {status} carries the billed-basis residual "
+                f"{residual:,.2f} (billed-to-date {billed:,.2f} − prior weeks {prior:,.2f})")
+    return out
+
+
+@dataclass
+class Restatement:
+    week: int
+    discipline: str
+    cost_type: str
+    delta_hours: float
+    delta_amount: float
+
+
+def restatements(previous: WeeklyActuals, current: WeeklyActuals, locked_through: int,
+                 tolerance: float = 0.005) -> List[Restatement]:
+    """Late postings: differences in weeks already statused (RP §7.2).
+
+    These are logged, and the affected weeks' AC buckets are restated to the
+    transaction week; the locked status-log rows for those weeks are *not*
+    changed (RP §9.1).
+    """
+    out: List[Restatement] = []
+    for week in range(1, locked_through + 1):
+        keys = set(previous.buckets.get(week, {})) | set(current.buckets.get(week, {}))
+        for key in sorted(keys):
+            before = previous.buckets.get(week, {}).get(key, ACBucket())
+            after = current.buckets.get(week, {}).get(key, ACBucket())
+            dh, da = after.hours - before.hours, after.amount - before.amount
+            if abs(dh) > tolerance or abs(da) > tolerance:
+                out.append(Restatement(week, key[0], key[1], dh, da))
+    return out

elecevm/allocation.py

@@ -0,0 +1,381 @@
+"""Cost-loaded schedule, allocation and the time-phased baseline (RP §5).
+
+The baseline is built in four steps:
+
+1. **Allocate** each discipline's budget labor hours to its schedule activities,
+   by resource-loaded budget hours when the schedule carries them, otherwise by
+   a *score* (original duration × hours/day × area weight × activity factor).
+   The allocation ties to the discipline budget exactly (RP §5.2).
+2. **Spread** each activity's hours evenly over its working days and sum them
+   into payroll weeks (RP §5.3).
+3. **Level** (optional) the total labor curve under a crew cap, delay-only (RP §5.4).
+4. **Price** the weekly hours at the effective discipline rate and phase
+   material, subcontract, equipment and other budgets on the configured
+   profile so that terminal PV equals BAC (RP §5.5).
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+from . import curves
+from .calendar import WeekCalendar, WorkCalendar
+from .config import Project
+from .models import Activity, BudgetKey, CostType
+
+ALLOCATION_TOLERANCE = 1e-6
+
+
+def activity_score(a: Activity, work_cal: WorkCalendar) -> Tuple[float, str]:
+    """Return (score, basis) for an activity: budget hours if loaded, else duration-based."""
+    if a.budget_hours is not None and a.budget_hours > 0:
+        return float(a.budget_hours), "budget_hours"
+    od = a.original_duration if a.original_duration else work_cal.workdays_between(a.start, a.finish)
+    od = max(od, 1)
+    return od * a.hours_per_day * a.area_weight * a.activity_factor, "score"
+
+
+def allocate_hours(activities: Iterable[Activity], bac_hours: Dict[str, float],
+                   work_cal: WorkCalendar) -> Dict[str, float]:
+    """Allocate discipline budget hours to activities; ties exactly per discipline."""
+    acts = list(activities)
+    by_disc: Dict[str, List[Activity]] = {}
+    for a in acts:
+        by_disc.setdefault(a.discipline, []).append(a)
+
+    allocation: Dict[str, float] = {}
+    for disc, group in by_disc.items():
+        target = float(bac_hours.get(disc, 0.0))
+        scored = {a.id: activity_score(a, work_cal) for a in group}
+        bases = {basis for _, basis in scored.values()}
+        if len(bases) > 1:
+            unloaded = sorted(aid for aid, (_, basis) in scored.items() if basis == "score")
+            raise ValueError(
+                f"discipline {disc} mixes resource-loaded and unloaded activities; "
+                f"activities with no budget hours: {unloaded} (RP §5.1: a data error, not a zero allocation)")
+        scores = {aid: s for aid, (s, _) in scored.items()}
+        total_score = sum(scores.values())
+        if total_score <= 0:
+            for a in group:
+                allocation[a.id] = 0.0
+            continue
+        running = 0.0
+        for a in group:
+            allocation[a.id] = target * scores[a.id] / total_score
+            running += allocation[a.id]
+        # absorb floating-point residual on the largest activity so the tie is exact
+        residual = target - running
+        if group and abs(residual) > 0:
+            biggest = max(group, key=lambda x: scores[x.id])
+            allocation[biggest.id] += residual
+    return allocation
+
+
+def spread_hours(hours: float, start: date, finish: date, work_cal: WorkCalendar,
+                 week_cal: WeekCalendar) -> Dict[int, float]:
+    """Spread ``hours`` evenly over the working days in [start, finish], by payroll week."""
+    days = work_cal.workday_dates(start, finish)
+    out: Dict[int, float] = {}
+    if hours == 0:
+        return out
+    if not days:
+        out[week_cal.week_of(start)] = hours
+        return out
+    per_day = hours / len(days)
+    for d in days:
+        w = week_cal.week_of(d)
+        out[w] = out.get(w, 0.0) + per_day
+    # exact conservation
+    residual = hours - sum(out.values())
+    if residual:
+        last = max(out)
+        out[last] += residual
+    return out
+
+
+@dataclass
+class Baseline:
+    """A versioned time-phased plan: allocation, weekly hours and dollars, BAC."""
+
+    version: int
+    created: date
+    note: str
+    basis: str
+    allocation: Dict[str, float]
+    allocation_basis: Dict[str, str]
+    activity_weeks: Dict[str, Dict[int, float]]
+    hours: Dict[int, Dict[str, float]]                 # week -> discipline -> labor hours
+    dollars: Dict[int, Dict[BudgetKey, float]]         # week -> (disc, ct) -> $
+    bac: Dict[BudgetKey, float]
+    bac_hours: Dict[str, float]
+    rates: Dict[str, float]
+    leveled: bool = False
+    bcr_log: List[dict] = field(default_factory=list)
+    unleveled_hours: Dict[int, Dict[str, float]] = field(default_factory=dict)  # schedule demand before leveling
+
+    # -- shape -----------------------------------------------------------
+    @property
+    def weeks(self) -> int:
+        candidates = [w for w, v in self.hours.items() if sum(v.values()) > 0]
+        candidates += [w for w, v in self.dollars.items() if sum(v.values()) > 0]
+        return max(candidates) if candidates else 0
+
+    @property
+    def disciplines(self) -> List[str]:
+        seen: List[str] = []
+        for d in list(self.bac_hours) + [k[0] for k in self.bac]:
+            if d not in seen:
+                seen.append(d)
+        return seen
+
+    # -- weekly values ---------------------------------------------------
+    def weekly_hours(self, week: int, discipline: Optional[str] = None) -> float:
+        row = self.hours.get(week, {})
+        if discipline is None:
+            return sum(row.values())
+        return row.get(discipline, 0.0)
+
+    def weekly_demand(self, week: int, discipline: Optional[str] = None) -> float:
+        """Unleveled schedule demand for the week (equals weekly_hours when not leveled)."""
+        table = self.unleveled_hours if self.leveled and self.unleveled_hours else self.hours
+        row = table.get(week, {})
+        return sum(row.values()) if discipline is None else row.get(discipline, 0.0)
+
+    def weekly_dollars(self, week: int, discipline: Optional[str] = None,
+                       cost_type: Optional[CostType] = None) -> float:
+        total = 0.0
+        for (disc, ct), amount in self.dollars.get(week, {}).items():
+            if discipline is not None and disc != discipline:
+                continue
+            if cost_type is not None and ct != cost_type.value:
+                continue
+            total += amount
+        return total
+
+    # -- cumulative values -----------------------------------------------
+    def pv(self, through: int, discipline: Optional[str] = None,
+           cost_type: Optional[CostType] = None) -> float:
+        return sum(self.weekly_dollars(w, discipline, cost_type) for w in range(1, through + 1))
+
+    def pv_hours(self, through: int, discipline: Optional[str] = None) -> float:
+        return sum(self.weekly_hours(w, discipline) for w in range(1, through + 1))
+
+    def activity_pv_fraction(self, activity_id: str, through: int) -> float:
+        total = self.allocation.get(activity_id, 0.0)
+        if total <= 0:
+            return 0.0
+        done = sum(h for w, h in self.activity_weeks.get(activity_id, {}).items() if w <= through)
+        return min(max(done / total, 0.0), 1.0)
+
+    @property
+    def terminal_pv(self) -> float:
+        return self.pv(self.weeks)
+
+    @property
+    def total_bac(self) -> float:
+        return sum(self.bac.values())
+
+    @property
+    def total_bac_hours(self) -> float:
+        return sum(self.bac_hours.values())
+
+    # -- persistence -----------------------------------------------------
+    def to_dict(self) -> dict:
+        return {
+            "version": self.version,
+            "created": self.created.isoformat(),
+            "note": self.note,
+            "basis": self.basis,
+            "leveled": self.leveled,
+            "allocation": self.allocation,
+            "allocation_basis": self.allocation_basis,
+            "activity_weeks": {k: {str(w): h for w, h in v.items()} for k, v in self.activity_weeks.items()},
+            "hours": {str(w): v for w, v in self.hours.items()},
+            "dollars": {str(w): {f"{d}:{ct}": amt for (d, ct), amt in v.items()} for w, v in self.dollars.items()},
+            "bac": {f"{d}:{ct}": amt for (d, ct), amt in self.bac.items()},
+            "bac_hours": self.bac_hours,
+            "rates": self.rates,
+            "bcr_log": self.bcr_log,
+            "unleveled_hours": {str(w): v for w, v in self.unleveled_hours.items()},
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Baseline":
+        def split(key: str) -> BudgetKey:
+            d, ct = key.rsplit(":", 1)
+            return (d, ct)
+
+        return cls(
+            version=int(data["version"]),
+            created=date.fromisoformat(data["created"]),
+            note=str(data.get("note", "")),
+            basis=str(data.get("basis", "estimated")),
+            allocation={k: float(v) for k, v in data["allocation"].items()},
+            allocation_basis={k: str(v) for k, v in data.get("allocation_basis", {}).items()},
+            activity_weeks={k: {int(w): float(h) for w, h in v.items()} for k, v in data["activity_weeks"].items()},
+            hours={int(w): {d: float(h) for d, h in v.items()} for w, v in data["hours"].items()},
+            dollars={int(w): {split(k): float(a) for k, a in v.items()} for w, v in data["dollars"].items()},
+            bac={split(k): float(v) for k, v in data["bac"].items()},
+            bac_hours={k: float(v) for k, v in data["bac_hours"].items()},
+            rates={k: float(v) for k, v in data.get("rates", {}).items()},
+            leveled=bool(data.get("leveled", False)),
+            bcr_log=list(data.get("bcr_log", [])),
+            unleveled_hours={int(w): {d: float(h) for d, h in v.items()} for w, v in data.get("unleveled_hours", {}).items()},
+        )
+
+    def save(self, path) -> None:
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path) -> "Baseline":
+        return cls.from_dict(json.loads(Path(path).read_text(encoding="utf-8")))
+
+
+def _phase_dollars(total: float, weights_by_week: Dict[int, float]) -> Dict[int, float]:
+    if total == 0 or not weights_by_week:
+        return {}
+    weeks = sorted(weights_by_week)
+    values = curves.scale_to_total([weights_by_week[w] for w in weeks], total)
+    return {w: v for w, v in zip(weeks, values) if v != 0}
+
+
+def build_baseline(project: Project, activities: Iterable[Activity], version: int = 1,
+                   note: str = "Initial baseline", created: Optional[date] = None,
+                   level: Optional[bool] = None) -> Baseline:
+    """Build the time-phased baseline for ``project`` from its schedule activities."""
+    acts = list(activities)
+    if not acts:
+        raise ValueError("no activities to build a baseline from")
+    budget = project.budget
+    work_cal, week_cal = project.work_cal, project.week_cal
+
+    discs_with_acts = sorted({a.discipline for a in acts})
+    bac_hours = {d: budget.bac_hours(d) for d in discs_with_acts}
+    missing = [d for d in budget.disciplines() if d not in discs_with_acts and (budget.bac(d) > 0 or budget.bac_hours(d) > 0)]
+    if missing:
+        raise ValueError(f"budget carries disciplines with no schedule activities to phase against: {missing}")
+
+    allocation = allocate_hours(acts, bac_hours, work_cal)
+    allocation_basis = {a.id: activity_score(a, work_cal)[1] for a in acts}
+
+    activity_weeks: Dict[str, Dict[int, float]] = {}
+    hours: Dict[int, Dict[str, float]] = {}
+    for a in acts:
+        weekly = spread_hours(allocation[a.id], a.start, a.finish, work_cal, week_cal)
+        activity_weeks[a.id] = weekly
+        for w, h in weekly.items():
+            hours.setdefault(w, {})
+            hours[w][a.discipline] = hours[w].get(a.discipline, 0.0) + h
+
+    leveled = False
+    unleveled: Dict[int, Dict[str, float]] = {}
+    do_level = project.crew_cap_hours is not None if level is None else level
+    if do_level and project.crew_cap_hours:
+        unleveled = {w: dict(v) for w, v in hours.items()}
+        # level every activity's own curve under the shared cap, then rebuild the discipline table
+        by_activity: Dict[int, Dict[str, float]] = {}
+        for aid, weekly in activity_weeks.items():
+            for w, h in weekly.items():
+                by_activity.setdefault(w, {})[aid] = h
+        leveled_acts = curves.level_by_group(by_activity, project.crew_cap_hours)
+        disc_of = {a.id: a.discipline for a in acts}
+        activity_weeks = {aid: {} for aid in activity_weeks}
+        hours = {}
+        for w, row in leveled_acts.items():
+            for aid, h in row.items():
+                activity_weeks[aid][w] = h
+                hours.setdefault(w, {})
+                hours[w][disc_of[aid]] = hours[w].get(disc_of[aid], 0.0) + h
+        leveled = True
+
+    rates = {d: project.rate(d) for d in discs_with_acts}
+    dollars: Dict[int, Dict[BudgetKey, float]] = {}
+    bac: Dict[BudgetKey, float] = {}
+
+    for d in discs_with_acts:
+        # labor $ = hours × effective rate (ties to budget labor $ when both are budgeted)
+        labor_bac = budget.bac(d, CostType.LABOR)
+        if labor_bac <= 0 and bac_hours[d] > 0:
+            labor_bac = bac_hours[d] * rates[d]
+        if labor_bac > 0:
+            weights = {w: hours[w].get(d, 0.0) for w in hours if hours[w].get(d, 0.0) > 0}
+            for w, amt in _phase_dollars(labor_bac, weights).items():
+                dollars.setdefault(w, {})[(d, CostType.LABOR.value)] = amt
+            bac[(d, CostType.LABOR.value)] = labor_bac
+
+        for ct in (CostType.MATERIAL, CostType.SUBCONTRACT, CostType.EQUIPMENT, CostType.OTHER):
+            total = budget.bac(d, ct)
+            if total <= 0:
+                continue
+            bac[(d, ct.value)] = total
+            span = [w for w in sorted(hours) if hours[w].get(d, 0.0) > 0]
+            if not span:
+                continue
+            if project.material_phasing == "follow_labor":
+                weights = {w: hours[w][d] for w in span}
+            else:
+                first, last = span[0], span[-1]
+                n = last - first + 1
+                shape = curves.bell(n) if project.material_phasing == "bell" else curves.linear(n)
+                weights = {first + i: shape[i] for i in range(n)}
+            for w, amt in _phase_dollars(total, weights).items():
+                dollars.setdefault(w, {})[(d, ct.value)] = amt
+
+    return Baseline(
+        version=version,
+        created=created or date.today(),
+        note=note,
+        basis=budget.basis,
+        allocation=allocation,
+        allocation_basis=allocation_basis,
+        activity_weeks=activity_weeks,
+        hours=hours,
+        dollars=dollars,
+        bac=bac,
+        bac_hours=bac_hours,
+        rates=rates,
+        leveled=leveled,
+        bcr_log=[{"version": version, "date": (created or date.today()).isoformat(), "note": note}],
+        unleveled_hours=unleveled,
+    )
+
+
+def forecast_remaining(project: Project, baseline: Baseline, activities: Iterable[Activity],
+                       earned_hours: Dict[str, float], status_week: int,
+                       etc_hours: Optional[Dict[str, float]] = None) -> Dict[int, Dict[str, float]]:
+    """Phase the estimate-to-complete hours after the status week (RP §8.4).
+
+    Each activity's remaining hours (allocation − earned, or a supplied ETC by
+    discipline shared by remaining allocation) are spread over the working days
+    from the week after status through the activity's current finish.  Finished
+    or exhausted activities contribute nothing; activities whose finish is
+    already past are pushed into the week after status.
+    """
+    week_cal, work_cal = project.week_cal, project.work_cal
+    cutoff = week_cal.week_end(status_week)
+    acts = list(activities)
+    remaining_by_act = {a.id: max(baseline.allocation.get(a.id, 0.0) - earned_hours.get(a.id, 0.0), 0.0) for a in acts}
+    if etc_hours:
+        by_disc: Dict[str, float] = {}
+        for a in acts:
+            by_disc[a.discipline] = by_disc.get(a.discipline, 0.0) + remaining_by_act[a.id]
+        for a in acts:
+            share = by_disc.get(a.discipline, 0.0)
+            if share > 0 and a.discipline in etc_hours:
+                remaining_by_act[a.id] = etc_hours[a.discipline] * remaining_by_act[a.id] / share
+    out: Dict[int, Dict[str, float]] = {}
+    for a in acts:
+        rem = remaining_by_act[a.id]
+        if rem <= 0:
+            continue
+        # a schedule-complete activity with unearned hours still owes them: next week
+        start = max(a.current_start, cutoff + timedelta(days=1))
+        finish = max(a.current_finish, start)
+        weekly = spread_hours(rem, start, finish, work_cal, week_cal)
+        for w, h in weekly.items():
+            out.setdefault(w, {})
+            out[w][a.discipline] = out[w].get(a.discipline, 0.0) + h
+    return out