# SCX Canonical Project Model and Verification Engine

## Purpose

The canonical model is the controlled engineering source of truth for an SCX crane-system project. It normalises existing layouts, workflow datasets, engineering plans, BOMs and inspection registers into one versioned model with stable IDs, trace links, verification results and a content hash.

Open `http://127.0.0.1:8840/scx_canonical_project_manager.html` or select **Canonical Project Model & Verification** from the landing page.

## Model structure

- `project` — identity, revision, owner, SI unit system and release state.
- `requirements` — identified requirements with acceptance and verification criteria.
- `site` — grid scale, coordinate basis, stations, walls, doors, keep-outs and storage bays.
- `crane_systems` — runway-centred system groupings and asset references.
- `assets` — normalised runways, bridges, trolleys and fixtures with geometry, classifications and SWL.
- `demand` — movements, station relationships, allocations, loads, timings and operations.
- `engineering` — inputs, calculations, assumptions and standards register.
- `bom` — controlled BOM items and summary.
- `lifecycle` — inspection assets/records, defects, commissioning and documents.
- `risks` — hazards, controls, owners and residual-risk information.
- `traceability` — typed links between movements, stations, assets and BOM items.
- `provenance` — source formats, source hash, migration details and engine version.
- `model_hash` — SHA-256 content identity excluding generation timestamp.

## Verification

The deterministic engine checks schema compatibility, project/release state, units, stable IDs, asset relationships, same-height runway crossings, movement references, schedule consistency, load versus allocated SWL, BOM completeness, requirements, risks and release evidence.

Every finding includes:

- Stable rule and finding IDs
- Severity and category
- Evidence and affected object IDs
- JSON model paths
- Required corrective action

Repeated instances are grouped by rule for manageable review while the complete instance list remains in the audit report.

## Release control

Supported release states are:

1. Draft
2. Engineering review
3. Independent check
4. Approved for tender
5. Approved for manufacture
6. As built
7. In service
8. Superseded

Draft and engineering-review models may be committed with critical findings so incomplete work remains auditable. Later release states are rejected while critical findings remain. There is no API force bypass.

## Repository behaviour

Committing from the manager creates or updates:

- `canonical-project`
- `verification-report`
- `impact-report` when the model changed from the previous version

Saving a project from Planning Tool V2 also synchronises a canonical project and verification report automatically. Matching repository BOM, engineering-plan and inspection-register artifacts are incorporated when their names match the project name.

## Change-impact analysis

Set or load a baseline, modify/import/rebuild the current model, and select **Analyse Change Impact**. The report lists changed JSON paths and affected engineering areas such as routing, structural calculations, drives, BOM, drawings, documents, approvals and verification.

## API endpoints

- `GET /api/canonical/schema`
- `GET /api/canonical/current`
- `GET /api/canonical/project?id=<artifact-id>`
- `POST /api/canonical/build`
- `POST /api/canonical/verify`
- `POST /api/canonical/impact`
- `POST /api/canonical/commit`

The API uses JSON request and response bodies. Canonical and verification records are stored in the existing SQLite repository with version history and audit events.

## Assurance boundary

This engine provides deterministic design-assurance support. It does not replace competent engineering review, independent checking, statutory duties, applicable standards or approval by the responsible organisation.