refactor: separate schema-forge engine from ILR domain types

- Create IlrMappingConfig extending generic MappingConfig for ILR-specific
  fields (famTemplates, appFinTemplates, employmentStatuses, aimDetectionField)
- Rename ColumnMapping.aimNumber to generic .group
- Narrow csvValidator parameter to { mappings: ColumnMapping[] }
- Move ILR-specific xmlGenerator.legacy.ts and xmlParser.ts to mappings/legacy/
- Remove all ILR/ESFA references from engine comments
- Engine files now contain zero domain-specific code or comments

https://claude.ai/code/session_01Di85VVVGikJ1vnpwjmF6H4

Author: claude

src/lib/mappings/aimUtils.ts

@@ -33,7 +33,7 @@ export function generateAimMappings(templates: AimFieldTemplate[]): ColumnMappin
 				csvColumn: template.csv.replace('{n}', String(aimNumber)),
 				xsdPath: template.xsd,
 				transform: template.transform,
-				aimNumber,
+				group: aimNumber,
 			});
 		}
 	}

src/lib/mappings/builders.ts

@@ -9,7 +9,7 @@ import type {
 	AppFinTemplate,
 	EmploymentStatusConfig,
 	EsmField,
-} from '../types/schemaTypes';
+} from '../types/ilrMappingTypes';
 import { getTransform } from '../transforms/registry';
 
 /**

src/lib/mappings/compatibility.ts

@@ -3,7 +3,7 @@
  * Loads schema, builds registry, and validates compatibility in one call.
  */
 
-import type { MappingConfig } from '../types/schemaTypes';
+import type { IlrMappingConfig } from '../types/ilrMappingTypes';
 import type { IrisStorage } from '../storage';
 import { buildSchemaRegistry } from '../schema/registryBuilder';
 import { validateSchemaCompatibility, type CompatibilityResult } from '../schema/schemaCompatibility';
@@ -20,7 +20,7 @@ export interface MappingCompatibilityResult {
  * Loads the schema, builds registry, and checks compatibility.
  */
 export async function validateMappingCompatibility(params: {
-	mapping: MappingConfig;
+	mapping: IlrMappingConfig;
 	schemaFile: string;
 	storage: IrisStorage;
 }): Promise<MappingCompatibilityResult> {

src/lib/mappings/fac-airtable-2025.ts

@@ -4,10 +4,10 @@
  *  |================================================================|
  */
 
-import type { MappingConfig } from '../types/schemaTypes';
+import type { IlrMappingConfig } from '../types/ilrMappingTypes';
 import { generateAimMappings } from './aimUtils';
 
-export const facAirtableMapping: MappingConfig = {
+export const facAirtableMapping: IlrMappingConfig = {
 	id: 'fac-airtable-2025',
 	name: 'Founders and Coders Airtable Export (2025-26)',
 	mappingVersion: '2.0.0',

src/lib/mappings/ilrColumnMapper.ts

@@ -1,4 +1,5 @@
-import type { ColumnMapping, MappingConfig } from '../types/schemaTypes';
+import type { ColumnMapping } from '../types/schemaTypes';
+import type { IlrMappingConfig } from '../types/ilrMappingTypes';
 import type { SchemaRegistry } from '../types/interpreterTypes';
 import { mapCsvToSchema } from '../schema/columnMapper';
 import { getTransform } from '../transforms/registry';
@@ -24,21 +25,21 @@ import { generateUUID } from '../utils/uuid';
  */
 export function mapCsvToSchemaWithAims(
 	csvRow: Record<string, string>,
-	config: MappingConfig,
+	config: IlrMappingConfig,
 	registry: SchemaRegistry
 ): Record<string, unknown> {
 	// Separate learner-level and aim-specific mappings
-	const learnerMappings = config.mappings.filter((m) => !m.aimNumber);
-	const aimMappings = config.mappings.filter((m) => m.aimNumber);
+	const learnerMappings = config.mappings.filter((m) => !m.group);
+	const aimMappings = config.mappings.filter((m) => m.group);
 
 	// Group aim mappings by aim number
 	const aimGroups = new Map<number, ColumnMapping[]>();
 	for (const mapping of aimMappings) {
-		if (!mapping.aimNumber) continue;
-		if (!aimGroups.has(mapping.aimNumber)) {
-			aimGroups.set(mapping.aimNumber, []);
+		if (!mapping.group) continue;
+		if (!aimGroups.has(mapping.group)) {
+			aimGroups.set(mapping.group, []);
 		}
-		aimGroups.get(mapping.aimNumber)!.push(mapping);
+		aimGroups.get(mapping.group)!.push(mapping);
 	}
 
 	// Apply learner-level mappings using generic mapper

src/lib/mappings/ilrValidation.ts

@@ -11,8 +11,8 @@ import { hasAimData } from './aimUtils';
  */
 export function createAimSkipFilter(detectionField: string = 'Programme aim {n} Learning ref') {
 	return (mapping: ColumnMapping, row?: Record<string, string>): boolean => {
-		if (!mapping.aimNumber) return false;
+		if (!mapping.group) return false;
 		if (!row) return true; // header-level: skip all aim mappings
-		return !hasAimData(row, mapping.aimNumber, detectionField);
+		return !hasAimData(row, mapping.group, detectionField);
 	};
 }

src/lib/utils/xml/xmlGenerator.legacy.ts …b/mappings/legacy/xmlGenerator.legacy.tssrc/lib/utils/xml/xmlGenerator.legacy.ts renamed to src/lib/mappings/legacy/xmlGenerator.legacy.ts src/lib/utils/xml/xmlGenerator.legacy.ts renamed to src/lib/mappings/legacy/xmlGenerator.legacy.ts

@@ -86,7 +86,7 @@ export function validateMappingStructure(mapping: unknown): MappingValidationRes
 			if (typeof e.xsdPath !== 'string' || e.xsdPath.trim() === '') {
 				issues.push({ field: `mappings[${index}].xsdPath`, message: 'Must be a non-empty string' });
 			}
-			// transform and aimNumber are optional, no validation needed
+			// transform and group are optional, no validation needed
 		});
 	}
 

src/lib/utils/xml/xmlParser.ts src/lib/mappings/legacy/xmlParser.tssrc/lib/utils/xml/xmlParser.ts renamed to src/lib/mappings/legacy/xmlParser.ts

@@ -42,8 +42,8 @@ export function mapCsvToSchema(
  * - Uses registry to determine if an element should be an array
  *
  * @example
- * setNestedValue({}, "Message.Learner.LearnRefNumber", "12345", registry)
- * // Returns: { Message: { Learner: [{ LearnRefNumber: "12345" }] } }
+ * setNestedValue({}, "Root.Parent.Field", "12345", registry)
+ * // Returns: { Root: { Parent: [{ Field: "12345" }] } }
  */
 function setNestedValue(
 	obj: Record<string, unknown>,