توطين الصالات الرياضية بـ TypeScript: محرّك الـ 15% لكل منفذ

// Ministerial Decision 72002 of 27/05/1447 AH and its procedural guide (HRSD).
 
/** Saudis required as a share of workers in the targeted occupations. */
export const RATE_PERCENT = 15;
 
/** The decision bites only at four or more workers in the targeted occupations. */
export const MIN_TARGETED_WORKERS = 4;
 
/** End of the 12-month grace period: 18/11/2026 = 8/6/1448 AH. */
export const ENFORCEMENT_FROM = '2026-11-18';
 
/** ISIC4 activity codes, guide table 1. */
export const TARGETED_ACTIVITIES: Readonly<Record<string, string>> = {
  '931221': "Men's sports halls and centres",
  '931222': "Women's sports halls and centres",
};
 
/** Saudi Standard Classification of Occupations codes, guide table 2. */
export const TARGETED_OCCUPATIONS: Readonly<Record<string, string>> = {
  '342201': 'Sports coach',
  '342203': 'Professional football coach',
  '342205': 'Professional ball sports coach',
  '342207': 'Professional self-defence coach',
  '342209': 'Professional racket sports coach',
  '342211': 'Professional aquatic sports coach',
  '342213': 'Professional ice sports coach',
  '342217': 'Professional equestrian coach',
  '342219': 'Professional athletics coach',
  '342221': 'Sports supervisor',
  '342301': 'Fitness trainer',
  '342302': 'Personal trainer',
};
 
export function isTargetedOccupation(code: string): boolean {
  return Object.prototype.hasOwnProperty.call(TARGETED_OCCUPATIONS, code);
}

import { MIN_TARGETED_WORKERS, RATE_PERCENT } from './rules';
 
/**
 * Saudis required in one outlet. The guide rounds to the nearest whole
 * number: 0.49 and below goes down, 0.50 and above goes up. Integer-only,
 * so no float ever enters.
 */
export function requiredSaudis(targetedWorkers: number): number {
  if (!Number.isInteger(targetedWorkers) || targetedWorkers < 0) {
    throw new RangeError(`targetedWorkers must be a whole number, got ${targetedWorkers}`);
  }
  if (targetedWorkers < MIN_TARGETED_WORKERS) return 0;
  return Math.floor((targetedWorkers * RATE_PERCENT + 50) / 100);
}

import { ENFORCEMENT_FROM, TARGETED_ACTIVITIES, isTargetedOccupation } from './rules';
import { requiredSaudis } from './required';
 
export interface Worker {
  id: string;
  /** The occupation code registered on the contract in Qiwa, not the floor title. */
  occupationCode: string;
  saudi: boolean;
}
 
export interface Outlet {
  /** Ministry of Sport licence number. One licence = one outlet. */
  licenceNo: string;
  name: string;
  /** ISIC4 activity on the commercial registration or licence. */
  registeredActivity: string;
  /** What the outlet actually runs, in ISIC4 codes. */
  actualActivities: string[];
  workers: Worker[];
}
 
export type OutletStatus = 'OUT_OF_SCOPE_ACTIVITY' | 'BELOW_THRESHOLD' | 'COMPLIANT' | 'SHORT';
 
export interface OutletAssessment {
  licenceNo: string;
  status: OutletStatus;
  targeted: number;
  saudis: number;
  required: number;
  gap: number;
  /** In scope only because of what it actually does, not what it registered. */
  scopeFromActualActivity: boolean;
  /** False during the grace period: the rate applies, the penalties do not. */
  enforceable: boolean;
}
 
const isTargetedActivity = (code: string): boolean =>
  Object.prototype.hasOwnProperty.call(TARGETED_ACTIVITIES, code);
 
export function assessOutlet(outlet: Outlet, asOf: string): OutletAssessment {
  const byRegistration = isTargetedActivity(outlet.registeredActivity);
  const byActual = outlet.actualActivities.some(isTargetedActivity);
  const targetedWorkers = outlet.workers.filter((w) => isTargetedOccupation(w.occupationCode));
  const targeted = targetedWorkers.length;
  const saudis = targetedWorkers.filter((w) => w.saudi).length;
  const required = requiredSaudis(targeted);
  const gap = Math.max(0, required - saudis);
 
  let status: OutletStatus;
  if (!byRegistration && !byActual) status = 'OUT_OF_SCOPE_ACTIVITY';
  else if (required === 0) status = 'BELOW_THRESHOLD';
  else status = gap === 0 ? 'COMPLIANT' : 'SHORT';
 
  return {
    licenceNo: outlet.licenceNo,
    status,
    targeted,
    saudis,
    required: status === 'OUT_OF_SCOPE_ACTIVITY' ? 0 : required,
    gap: status === 'SHORT' ? gap : 0,
    scopeFromActualActivity: !byRegistration && byActual,
    enforceable: asOf >= ENFORCEMENT_FROM,
  };
}

import { isTargetedOccupation } from './rules';
import { Outlet, OutletAssessment, Worker, assessOutlet } from './outlet';
 
/** One coaching act from the class timetable or the PT booking system. */
export interface Session {
  licenceNo: string;
  instructorId: string;
}
 
/**
 * Non-Saudis registered outside the 12 codes who nonetheless lead sessions.
 * Section 7 of the guide treats giving them a targeted job's tasks, under
 * any other title, as a breach.
 */
export function disguisedCoaches(outlet: Outlet, sessions: Session[]): Worker[] {
  const leading = new Set(
    sessions.filter((s) => s.licenceNo === outlet.licenceNo).map((s) => s.instructorId),
  );
  return outlet.workers.filter(
    (w) => !w.saudi && !isTargetedOccupation(w.occupationCode) && leading.has(w.id),
  );
}
 
/** Re-assess as an inspector would if each disguised coach counted as a sports coach. */
export function exposure(outlet: Outlet, sessions: Session[], asOf: string): OutletAssessment {
  const flagged = new Set(disguisedCoaches(outlet, sessions).map((w) => w.id));
  const workers = outlet.workers.map((w) =>
    flagged.has(w.id) ? { ...w, occupationCode: '342201' } : w,
  );
  return assessOutlet({ ...outlet, workers }, asOf);
}

import { requiredSaudis } from './required';
 
export interface Remediation {
  /** Replace non-Saudis in targeted seats: the denominator stays put. */
  byReplacement: number;
  /** Add Saudis on top: every hire also grows the denominator. */
  byHiringOnly: number;
}
 
export function remediation(targeted: number, saudis: number): Remediation {
  const byReplacement = Math.max(0, requiredSaudis(targeted) - saudis);
  let byHiringOnly = 0;
  while (saudis + byHiringOnly < requiredSaudis(targeted + byHiringOnly)) byHiringOnly++;
  return { byReplacement, byHiringOnly };
}
 
/**
 * How many Saudis in targeted seats could leave this outlet with it still
 * meeting the rate. Each departure shrinks the denominator as well.
 */
export function spareSaudis(targeted: number, saudis: number): number {
  let k = 0;
  while (k < saudis && saudis - (k + 1) >= requiredSaudis(targeted - (k + 1))) k++;
  return k;
}

import { isTargetedOccupation } from './rules';
import { Outlet, assessOutlet } from './outlet';
import { Remediation, remediation, spareSaudis } from './gap';
 
export interface Move {
  workerId: string;
  from: string;
  to: string;
}
 
export interface ChainPlan {
  moves: Move[];
  stillShort: Array<{ licenceNo: string } & Remediation>;
}
 
const clone = (outlets: Outlet[]): Outlet[] =>
  outlets.map((o) => ({ ...o, workers: o.workers.map((w) => ({ ...w })) }));
 
/**
 * Greedy plan: move a spare Saudi from the outlet with most room to the
 * outlet with the largest gap, re-assess both, repeat. Whatever is left
 * is priced as replacement or hiring.
 */
export function planChain(input: Outlet[], asOf: string): ChainPlan {
  const outlets = clone(input);
  const moves: Move[] = [];
  const saudiSeats = outlets.flatMap((o) => o.workers).filter((w) => w.saudi).length;
 
  // Each Saudi moves at most once per pass; the cap makes termination obvious.
  for (let pass = 0; pass < saudiSeats; pass++) {
    const rows = outlets.map((o) => ({ o, a: assessOutlet(o, asOf) }));
    const short = rows
      .filter((r) => r.a.status === 'SHORT')
      .sort((x, y) => y.a.gap - x.a.gap)[0];
    if (!short) break;
    const donor = rows
      .filter((r) => r.o !== short.o && r.a.status !== 'OUT_OF_SCOPE_ACTIVITY')
      .map((r) => ({ ...r, spare: spareSaudis(r.a.targeted, r.a.saudis) }))
      .filter((r) => r.spare > 0)
      .sort((x, y) => y.spare - x.spare)[0];
    if (!donor) break;
 
    const i = donor.o.workers.findIndex((w) => w.saudi && isTargetedOccupation(w.occupationCode));
    const [worker] = donor.o.workers.splice(i, 1);
    short.o.workers.push(worker);
    moves.push({ workerId: worker.id, from: donor.o.licenceNo, to: short.o.licenceNo });
  }
 
  const stillShort = outlets
    .map((o) => assessOutlet(o, asOf))
    .filter((a) => a.status === 'SHORT')
    .map((a) => ({ licenceNo: a.licenceNo, ...remediation(a.targeted, a.saudis) }));
 
  return { moves, stillShort };
}

import { Outlet, assessOutlet } from './outlet';
import { Session, disguisedCoaches, exposure } from './disguised';
import { planChain } from './chain';
 
const staff = (prefix: string, code: string, n: number, saudi: boolean) =>
  Array.from({ length: n }, (_, i) => ({ id: `${prefix}${i + 1}`, occupationCode: code, saudi }));
 
const chain: Outlet[] = [
  {
    licenceNo: 'RYD-01', name: 'Riyadh North (men)',
    registeredActivity: '931221', actualActivities: ['931221'],
    workers: [
      ...staff('r1-pt-', '342302', 10, false),
      ...staff('r1-fit-', '342301', 5, false),
      ...staff('r1-sup-', '342221', 1, true),
      ...staff('r1-desk-', '422601', 3, false),
    ],
  },
  {
    licenceNo: 'RYD-02', name: 'Riyadh East (women)',
    registeredActivity: '931222', actualActivities: ['931222'],
    workers: [
      ...staff('r2-fit-', '342301', 15, false),
      ...staff('r2-sa-', '342201', 5, true),
    ],
  },
  {
    licenceNo: 'JED-01', name: 'Jeddah Corniche',
    registeredActivity: '477310', actualActivities: ['477310', '931221'],
    workers: [
      ...staff('j1-pt-', '342302', 8, false),
      ...staff('j1-sa-', '342201', 1, true),
      ...staff('j1-desk-', '422601', 2, false),
    ],
  },
];
 
const sessions: Session[] = [
  { licenceNo: 'JED-01', instructorId: 'j1-desk-1' },
  { licenceNo: 'JED-01', instructorId: 'j1-pt-1' },
];
 
const asOf = '2026-11-18';
for (const o of chain) {
  const a = assessOutlet(o, asOf);
  console.log(`${a.licenceNo}  ${a.status.padEnd(9)} targeted=${a.targeted} saudis=${a.saudis} required=${a.required} gap=${a.gap}${a.scopeFromActualActivity ? '  (in scope by actual activity)' : ''}`);
}
 
const jed = chain[2];
const hidden = disguisedCoaches(jed, sessions).map((w) => w.id);
const exp = exposure(jed, sessions, asOf);
console.log(`JED-01 disguised coaches: ${hidden.join(', ')} -> ${exp.status} required=${exp.required} gap=${exp.gap}`);
 
const plan = planChain(chain, asOf);
for (const m of plan.moves) console.log(`move ${m.workerId}: ${m.from} -> ${m.to}`);
console.log('still short:', JSON.stringify(plan.stillShort));

RYD-01  SHORT     targeted=16 saudis=1 required=2 gap=1
RYD-02  COMPLIANT targeted=20 saudis=5 required=3 gap=0
JED-01  COMPLIANT targeted=9 saudis=1 required=1 gap=0  (in scope by actual activity)
JED-01 disguised coaches: j1-desk-1 -> SHORT required=2 gap=1
move r2-sa-1: RYD-02 -> RYD-01
move r2-sa-2: RYD-02 -> RYD-01
still short: []

import { test } from 'node:test';
import { strict as assert } from 'node:assert';
import { TARGETED_ACTIVITIES, TARGETED_OCCUPATIONS } from '../src/rules';
import { requiredSaudis } from '../src/required';
import { Outlet, assessOutlet } from '../src/outlet';
import { remediation, spareSaudis } from '../src/gap';
import { disguisedCoaches, exposure } from '../src/disguised';
import { planChain } from '../src/chain';
 
// Guide table 3, transcribed: targeted workers 4..40 -> Saudis required.
const TABLE_3: Array<[number, number]> = [
  [4, 1], [5, 1], [6, 1], [7, 1], [8, 1], [9, 1],
  [10, 2], [11, 2], [12, 2], [13, 2], [14, 2], [15, 2], [16, 2],
  [17, 3], [18, 3], [19, 3], [20, 3], [21, 3], [22, 3], [23, 3],
  [24, 4], [25, 4], [26, 4], [27, 4], [28, 4], [29, 4],
  [30, 5], [31, 5], [32, 5], [33, 5], [34, 5], [35, 5], [36, 5],
  [37, 6], [38, 6], [39, 6], [40, 6],
];
 
const staff = (prefix: string, code: string, n: number, saudi: boolean) =>
  Array.from({ length: n }, (_, i) => ({ id: `${prefix}${i + 1}`, occupationCode: code, saudi }));
 
const outlet = (licenceNo: string, targeted: number, saudis: number, extra = 0): Outlet => ({
  licenceNo, name: licenceNo, registeredActivity: '931221', actualActivities: ['931221'],
  workers: [
    ...staff(`${licenceNo}-n`, '342301', targeted - saudis, false),
    ...staff(`${licenceNo}-s`, '342201', saudis, true),
    ...staff(`${licenceNo}-x`, '241101', extra, false),
  ],
});
 
test('reference tables have the shape the guide prints', () => {
  const codes = Object.keys(TARGETED_OCCUPATIONS);
  assert.equal(codes.length, 12);
  assert.ok(codes.every((c) => /^342[23]\d{2}$/.test(c)), 'codes are six digits in 3422xx or 3423xx');
  assert.deepEqual(Object.keys(TARGETED_ACTIVITIES).sort(), ['931221', '931222']);
});
 
test('requiredSaudis reproduces guide table 3 for every printed column', () => {
  for (const [targeted, saudis] of TABLE_3) assert.equal(requiredSaudis(targeted), saudis, `at ${targeted}`);
});
 
test('below four targeted workers nothing is required', () => {
  assert.equal(requiredSaudis(0), 0);
  assert.equal(requiredSaudis(3), 0);
  assert.throws(() => requiredSaudis(2.5), RangeError);
});
 
test('guide example 1: 23 staff, 10 in targeted jobs, 2 Saudis required', () => {
  const o: Outlet = {
    licenceNo: 'A', name: 'A', registeredActivity: '931221', actualActivities: ['931221'],
    workers: [
      ...staff('sales', '122101', 2, false), ...staff('coach', '342201', 6, false),
      ...staff('fit', '342301', 4, false), ...staff('acct', '241101', 3, false),
      ...staff('desk', '422601', 4, false), ...staff('guard', '541401', 4, false),
    ],
  };
  const a = assessOutlet(o, '2026-11-18');
  assert.equal(o.workers.length, 23);
  assert.deepEqual([a.status, a.targeted, a.required, a.gap], ['SHORT', 10, 2, 2]);
});
 
test('threshold counts targeted workers, not headcount', () => {
  const a = assessOutlet(outlet('B', 3, 0, 20), '2026-11-18');
  assert.equal(a.status, 'BELOW_THRESHOLD');
});
 
test('scope follows actual activity even when the registration says otherwise', () => {
  const o = { ...outlet('C', 6, 0), registeredActivity: '477310', actualActivities: ['477310', '931222'] };
  const a = assessOutlet(o, '2026-11-18');
  assert.equal(a.status, 'SHORT');
  assert.equal(a.scopeFromActualActivity, true);
  const out = assessOutlet({ ...o, actualActivities: ['477310'] }, '2026-11-18');
  assert.equal(out.status, 'OUT_OF_SCOPE_ACTIVITY');
});
 
test('penalties start on 18 November 2026, not the day before', () => {
  assert.equal(assessOutlet(outlet('D', 10, 0), '2026-11-17').enforceable, false);
  assert.equal(assessOutlet(outlet('D', 10, 0), '2026-11-18').enforceable, true);
});
 
test('at 16 targeted, one hire does not close a gap of one', () => {
  assert.deepEqual(remediation(16, 1), { byReplacement: 1, byHiringOnly: 2 });
  assert.deepEqual(remediation(10, 0), { byReplacement: 2, byHiringOnly: 2 });
  assert.deepEqual(remediation(20, 3), { byReplacement: 0, byHiringOnly: 0 });
});
 
test('spare Saudis account for the shrinking denominator', () => {
  assert.equal(spareSaudis(20, 5), 2);
  assert.equal(spareSaudis(17, 3), 1);
  assert.equal(spareSaudis(9, 1), 0);
  assert.equal(spareSaudis(4, 1), 1);
});
 
test('a non-Saudi receptionist who leads classes is flagged and changes the result', () => {
  const o = outlet('E', 9, 1);
  o.workers.push({ id: 'desk1', occupationCode: '422601', saudi: false });
  o.workers.push({ id: 'desk2', occupationCode: '422601', saudi: true });
  const sessions = [
    { licenceNo: 'E', instructorId: 'desk1' },
    { licenceNo: 'E', instructorId: 'desk2' },
    { licenceNo: 'OTHER', instructorId: 'E-n1' },
  ];
  assert.deepEqual(disguisedCoaches(o, sessions).map((w) => w.id), ['desk1']);
  assert.equal(assessOutlet(o, '2026-11-18').status, 'COMPLIANT');
  const x = exposure(o, sessions, '2026-11-18');
  assert.deepEqual([x.status, x.targeted, x.required], ['SHORT', 10, 2]);
});
 
test('chain plan needs two moves to close one gap at 16, and leaves the donor compliant', () => {
  const plan = planChain([outlet('R1', 16, 1), outlet('R2', 20, 5)], '2026-11-18');
  assert.equal(plan.moves.length, 2);
  assert.ok(plan.moves.every((m) => m.from === 'R2' && m.to === 'R1'));
  assert.deepEqual(plan.stillShort, []);
});
 
test('chain plan prices what transfers cannot cover and never mutates its input', () => {
  const input = [outlet('S1', 12, 0), outlet('S2', 9, 1)];
  const plan = planChain(input, '2026-11-18');
  assert.deepEqual(plan.moves, []);
  assert.deepEqual(plan.stillShort, [{ licenceNo: 'S1', byReplacement: 2, byHiringOnly: 2 }]);
  assert.equal(input[1].workers.length, 9);
});