cpp-cpm-engine

# cpm-engine

[![npm version](https://img.shields.io/npm/v/cpp-cpm-engine.svg)](https://www.npmjs.com/package/cpp-cpm-engine)
[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![tests: 1273 passing](https://img.shields.io/badge/tests-1273%20passing-brightgreen.svg)](cpm-engine.test.js)
[![crossval: JS↔Python 1009/1015](https://img.shields.io/badge/JS%E2%86%94Python-1009%2F1015-brightgreen.svg)](DAUBERT.md#31-independent-verification)
[![coverage: 93%](https://img.shields.io/badge/coverage-93%25%20stmts%20%2F%2083%25%20branches-brightgreen.svg)](DAUBERT.md#21-test-coverage-v2940-baseline)
[![verify](https://github.com/danafitkowski/cpp-cpm-engine/actions/workflows/verify.yml/badge.svg)](https://github.com/danafitkowski/cpp-cpm-engine/actions/workflows/verify.yml)
[![Daubert: disclosed](https://img.shields.io/badge/Daubert-disclosed-blueviolet.svg)](DAUBERT.md)
[![AACE: 29R--03 / 49R--06 / 52R--06](https://img.shields.io/badge/AACE-29R--03%20%7C%2049R--06%20%7C%2052R--06-orange.svg)](docs/citations.md)

An open-source CPM engine with AACE-aligned methodology and a published [Daubert disclosure](DAUBERT.md).
**Open source. AACE-aligned. Daubert-disclosed. 1,273 JS unit tests, plus JS/Python parity on 1009 of 1015 enumerated cross-validation comparisons; the remaining 6 are not compared because neither engine emits the field on a completed activity (see [DAUBERT.md §3.1](DAUBERT.md#31-independent-verification)).**

Court-facing usage: pair this engine with the analyst-application discipline in [`FORENSIC_USE_SOP.md`](FORENSIC_USE_SOP.md), the verification chain in [`VERIFY_RELEASE.md`](VERIFY_RELEASE.md), the per-release receipts in [`release-evidence/`](release-evidence/), and the field-level P6 comparison framework in [`validation/p6-comparison/`](validation/p6-comparison/). Do NOT cite README in a court-facing report — cite the documents listed in [DAUBERT.md](DAUBERT.md) and [`FORENSIC_USE_SOP.md` §Required pairing](FORENSIC_USE_SOP.md).

Maintained by [Critical Path Partners](https://criticalpathpartners.ca) — a forensic-scheduling consultancy.

---

## Quick start

**The npm package lags this repository.** npm `latest` is 2.9.19, published 2026-05-17 — that is the number the npm badge above renders, and nothing has been published to npm since, while 22 tagged releases have shipped here. `npm install cpp-cpm-engine` therefore does **not** give you the engine described by DAUBERT.md, by the [`release-evidence/`](release-evidence/) packets, or by any version reference in these docs. Install from the git tag:

```bash
git clone https://github.com/danafitkowski/cpp-cpm-engine.git
cd cpp-cpm-engine
git checkout v2.9.43
```

The engine has zero runtime dependencies, so a clone is all it needs. This is the same install path [`VERIFY_RELEASE.md`](VERIFY_RELEASE.md) gives an opposing expert.

```js
const E = require('./cpm-engine.js');

const result = E.computeCPM(
    [
        { code: 'A', duration_days: 5, early_start: '2026-01-05', clndr_id: 'MF' },
        { code: 'B', duration_days: 3, clndr_id: 'MF' },
        { code: 'C', duration_days: 4, clndr_id: 'MF' },
    ],
    [
        { from_code: 'A', to_code: 'B', type: 'FS', lag_days: 0 },
        { from_code: 'B', to_code: 'C', type: 'FS', lag_days: 0 },
    ],
    {
        dataDate: '2026-01-05',
        calMap: { MF: { work_days: [1, 2, 3, 4, 5], holidays: [] } },
    }
);

console.log('Project finish:', result.projectFinish);     // 2026-01-21
console.log('Critical path:', result.criticalCodesArray); // ['A', 'B', 'C']
console.log('Engine version:', result.manifest.engine_version); // 2.9.43
```

That's it. Forward pass, backward pass, total float, free float, calendar arithmetic, P6-conventional date math, multi-jurisdiction holidays — all done.

---

## Why this engine?

| Capability | cpm-engine |
|------------|:----------:|
| Open source                                            | yes |
| AACE-canonical method labels (29R-03 / 49R-06 / 52R-06)| yes |
| Daubert / FRE 702 disclosure (built-in `DAUBERT.md`)   | yes |
| JS-Python bit-identical parity on enumerated CPM surface | yes |
| Topology fingerprint hash (SHA-256, copy-detection signal) | yes |
| Kinematic delay dynamics (pre-publication, JS-only)    | yes |
| Bayesian update with hierarchical pooling (pre-publication, JS-only) | yes |
| 66 default holiday rule sets (multi-jurisdiction; framework-aligned defaults, **not** legally certified — see [`docs/jurisdictions.md`](docs/jurisdictions.md)) | yes |
| MIT licensed                                           | yes |

*(Vendor comparison removed in the v2.9.33 audit cycle. Comparisons against specific commercial CPM tools should be supplied by an independent reviewer, not authored by the engine's maintainer.)*

The engine math is a commodity. What carries a forensic schedule analysis is the **workflow, the methodology discipline, and the Daubert disclosure posture** — not the forward pass itself. Critical Path Partners open-sources the engine so any academic, any solo forensic scheduler, any contractor's internal scheduler can build on a transparent, citable foundation.

---

## What you can build

- **Forensic delay analysis primitives** — CPM forward/backward pass that supports analyses under AACE 29R-03 MIPs 3.3 (windows), 3.6/3.7 (prospective TIA single-base / multi-base), and 3.8 (collapsed as-built). The engine provides the CPM math; full method implementations (period selection, fragnet integration, as-built reconstruction) live in the CPP forensic skill suite — this OSS engine is the math core they build on, not the full method.
- **Claim packages** — owner-submission EOT bundles with cover letter, exhibits, mitigation logs
- **Daubert disclosures** — FRCP 26(a)(2)(B) reports, FRE 702/707 four-prong methodology statements
- **Schedule risk primitives** — Bayesian posterior estimation (`computeBayesianUpdate`); per-iteration CPM (`runCPM`) suitable as an inner loop for Monte Carlo wrappers built on top of this engine. Full Monte Carlo / QRAMM scoring lives in the CPP forensic skill suite (`schedule-risk-analysis`), built atop this primitive.
- **Schedule health** — DCMA-14 assessment, A-F auto-grade, baseline-vs-current diff
- **Multi-jurisdiction calendars** — 66 default holiday rule sets (CA-FED + 13 provinces/territories, US-FED + 50 states + DC). These are framework-aligned defaults sufficient for general-purpose date math — see [`docs/jurisdictions.md`](docs/jurisdictions.md) for the per-jurisdiction reference table and forensic-use verification guidance. They are **not** legally certified calendars; for forensic use, override with the project's contract calendar via `opts.calendar`.

---

## AACE alignment

The engine implements the math behind these AACE Recommended Practices:

| RP            | Title                                                          | Method labels emitted |
|---------------|----------------------------------------------------------------|-----------------------|
| 29R-03        | Forensic Schedule Analysis                                     | MIP 3.3 / 3.6 / 3.7 / 3.8 |
| 49R-06        | Identifying the Critical Path                                  | LPM, TFM, MFP        |
| 52R-06        | Prospective Time Impact Analysis                               | MIP 3.6 (Single Base) / MIP 3.7 (Multiple Base) |
| 122R-22       | Quantitative Risk Analysis Maturity Model (QRAMM)              | (badge surface)       |
| PPG #20 (2nd Ed 2024) | Forensic Schedule Analysis Practice Guide              | (general acceptance)  |

Method labels are emitted in `result.manifest.methodology` — exactly the strings AACE peer-reviewers and opposing experts expect.

---

## Verifiable provenance

Every computation emits a manifest:

```js
result.manifest = {
    engine_version: '2.9.43',
    method_id: 'computeCPM',
    activity_count: 3,
    relationship_count: 2,
    data_date: '2026-01-05',
    calendar_count: 1,
    computed_at: '2026-05-10T14:32:01.847Z',
}
```

Plus, for forensic provenance, every input carries a SHA-256 topology hash:

```js
const hash = E.computeTopologyHash(activities, relationships);
console.log(hash.topology_hash);  // 64-char hex over canonical (code, duration, sorted preds + types + lags)
// Two XERs with identical hashes have IDENTICAL CANONICALIZED TOPOLOGY under the hashed-field
// set (activity codes, durations, predecessor links + types + lags). NOT a forensic-equivalence
// statement — different calendars, resources, WBS, names, or constraints can still produce
// different schedules under the same hash. The hash is a signal, not a schedule-equivalence proof.
```

This is the engine's network-topology fingerprint. **Bid-collusion signal, retroactive-manipulation signal, and copy-detection signal across XERs all rely on it.** It is also the foundation that lets opposing counsel verify topology-level integrity of a CPP analysis post-hoc — they can recompute the hash from the same XER and confirm the activity/relationship network was not altered between submission and review.

---

## JavaScript - Python parity

The engine has a Python sibling (`_cpp_common/scripts/cpm.py`) used by every CPP forensic skill. The two implementations are kept bit-identical via cross-validation:

```bash
npm run crossval
# 46 fixtures, 1009 checks executed, 0 deviations, measured 2026-09-02.
# A further 6 comparisons on the enumerated surface (1015 total) are skipped rather than failed by the harness field guards, all on ff_signed / ff_signed_working_days on completed activities, where NEITHER engine emits the field.
```

Plus a 282-activity real-XER stress test reports 0 mismatches. That XER is a single non-public reference file, is not committed, and the run is not independently reproducible from this repo (see [DAUBERT.md §2](DAUBERT.md#2-methodology-tested)).

This means a forensic analysis run in JavaScript (browser, Node) produces the same numbers as one run in Python (claims-preparatio