# Core Machine Integration Audit

_Last updated: Milestone 5 final catalogue expansion pass._

## Result

The Phase 1 catalogue is now wired as a full 28-machine data set across catalogue metadata, learning dossiers, procedural blueprints, animation mappings, and replacement-point documentation. The final integration gap from the previous pass was the learning dossier lookup: mechanism dossiers and structural/other dossiers now participate in the shared dossier registry through `src/modules/machines/dossiers/registry.ts` and the public dossier barrel at `src/modules/machines/dossiers/index.ts`.

## Dossier Registry Integration

The dossier registry imports all five Phase 1 dossier families:

- `./engines`
- `./gearboxesAndDrives`
- `./pumpsAndFluid`
- `./mechanisms`
- `./structuralOther`

It exposes these stable lookup utilities:

```ts
import {
  getCoreMachineDossier,
  requireCoreMachineDossier,
  coreMachineDossierLookup,
  coreMachineDossiers,
  auditCoreMachineDossierCoverage,
} from '@/modules/machines/dossiers';
```

The registry collector supports array exports, record exports, and wrapped category exports, so dossier category files can evolve without forcing viewer or control-panel code changes. Duplicate machine IDs from different dossier source files are reported through `duplicateCoreMachineDossierIds` and through the `auditCoreMachineDossierCoverage` report.

## Automated Consistency Audit

Run the catalogue audit from the repository root:

```bash
node scripts/validate-core-machine-catalogue.mjs
```

The script performs these checks without requiring a TypeScript runtime loader:

1. Extracts machine definitions from the five catalogue files and verifies the Phase 1 category counts:
   - Engines: 8
   - Gearboxes & Drives: 6
   - Pumps & Fluid Systems: 4
   - Mechanisms: 6
   - Structural / Other: 4
2. Verifies 28 unique machine IDs are present.
3. Checks that each machine ID appears in:
   - `src/animations/coreMachineAnimations.ts`
   - `src/modules/machines/procedural/coreMachineBlueprints.ts`
   - the dossier data files
4. Checks that the dossier registry imports mechanisms and structural/other dossiers.
5. Checks that guided-tour, label, exploded-view, dossier, animation, and blueprint `partId` / `partIds` references resolve to declared catalogue part IDs where they can be scoped to one machine.
6. Checks procedural blueprints expose replacement-point metadata so diagrammatic assemblies can be swapped for professional GLB assets later.

Because the validator reads TypeScript as source text, it is intentionally conservative: hard coverage failures are errors, while non-fatal shape concerns are warnings for maintainers to inspect.

## Phase 1 Machine Coverage Matrix

| Family | Machines covered |
| --- | --- |
| Engines | Four Stroke Petrol Engine; Two Stroke Engine; Diesel Engine; V8 Engine; Wankel Rotary Engine; Steam Engine; Jet Engine / Turbojet; Turbofan Engine |
| Gearboxes & Drives | Planetary Gearbox; Differential Gear; Manual Gearbox (5-speed); CVT; Worm Gear Drive; Bevel Gear Set |
| Pumps & Fluid Systems | Centrifugal Pump; Gear Pump; Piston Pump; Hydraulic Cylinder |
| Mechanisms | Scotch Yoke; Geneva Drive; Cam and Follower; Rack and Pinion; Slider Crank; Toggle Clamp |
| Structural / Other | Ball Bearing; Roller Bearing; Disc Brake Caliper; Turbocharger |

## Replacement-Point Audit

Every procedural blueprint is expected to declare replacement metadata for its major assemblies and externally visible parts. Those replacement points are the contract for swapping the clean procedural/diagrammatic geometry with production GLB or GLTF assets:

- Keep the machine ID unchanged.
- Keep part IDs unchanged.
- Replace the procedural node or primitive referenced by the replacement point with the loaded GLB scene subtree.
- Preserve transform origin semantics so animation modules continue to drive pistons, shafts, valves, rotors, gears, or linkages without viewer-code changes.

This keeps the current educational models useful immediately while leaving a clean professional asset pipeline for CAD-derived geometry.

## Manual Cross-File Audit Notes

The final pass reviewed the following cross-file contracts:

- Machine IDs are data-driven from catalogue entries and are the single join key for dossiers, animation modules, and procedural blueprints.
- Part IDs in catalogue component hierarchies are the single join key for tooltips, detail drawers, visibility controls, opacity controls, labels, guided-tour highlights, exploded-view offsets, and blueprint replacement points.
- Animation modules remain machine-specific behind the shared animation interface; the viewer/player does not need to branch on individual machine mechanics.
- Dossier files are optional to render the 3D viewer, but `requireCoreMachineDossier` provides a strict path for pages that need guaranteed learning content.
- Mechanism and structural/other dossiers are now first-class in the same lookup path as engines, drives, and pumps.

## Build-Hygiene Notes

No new third-party dependencies are required for this audit layer. The validation script uses only Node built-ins (`fs`, `path`, and `url`), and the dossier registry uses only local TypeScript modules.