writing/tutorial/2026/11
● TutorialNov 18, 2026·20 min read

Procurement Saudization at 70%: a TypeScript Check for 12 Codes

Ministerial Decision 77050 has required 70% Saudis in procurement professions since 31 May 2026, and its guide doubles the list to 12 codes, including storekeepers and warehouse staff. Build the check in TypeScript: scope, rounding, replacement versus hiring, and a diff against the 2023 rules.

On 30 November 2025 the Ministry of Human Resources and Social Development issued Ministerial Decision 77050 and a procedural guide for procurement professions. The six-month grace period ended on 31 May 2026. Since then, every private establishment with three or more workers in those professions must have 70% of them Saudi.

Many HR systems still hold the rule from 2023: Decision 141612, 50%, six occupations. Moving the rate from 50 to 70 is a one-line change. The bigger change is the list. The 2026 guide names twelve occupations, and the six new ones are not buyers: storekeepers, warehouse managers and specialists, a logistics services manager, an e-commerce specialist and a market research specialist. A company whose purchasing team was compliant in 2025 can be out of compliance today because of its warehouse.

This tutorial builds the check in TypeScript, from the two official guides, with tests you can run. It is written for the developer or HR systems lead who has to make the numbers correct. Because the decision is already enforced, the module reports how long an entity has been out of compliance, not how much time is left.

Prerequisites

  • Node.js 20 or later and TypeScript 5
  • An export of your workforce with, for each worker: nationality, the occupation code registered in Qiwa, the branch, and the entity it belongs to
  • One column most exports do not have: whether the person actually does the work of the occupation. You get it from line managers, not from the system
  • Basic familiarity with Qiwa and Nitaqat terms

What You'll Build

A small module that answers five questions for each entity:

  1. How many workers are in scope under the 2026 guide, and does the decision apply at all?
  2. How many Saudis are required, with the guide's rounding?
  3. What is the gap if you replace non-Saudis, and what is it if you only hire?
  4. Who joined the scope on 31 May 2026, compared with the 2023 rules your system may still hold?
  5. Which workers create risk because their code and their actual work disagree?

The output is an action plan HR can read, split between purchasing roles and the warehouse, logistics and market roles that joined the list.

Step 1: What the Guide Actually Says

Everything below comes from the seven-page procedural guide published on the ministry's site for Decision 77050, read alongside the 2023 guide it replaces.

The rate. 70% in establishments where three or more workers hold procurement professions from the table (section 3.1).

The scope. Section 3.3 applies the decision to private establishments in the Saudi market with three or more workers in the professions of table 2. An establishment with two is outside it. The definitions add that the targeted establishment is an entity registered with the ministry, and the rate is counted in the establishment as a whole.

The professions. Table 2 lists twelve codes from the Saudi Unified Classification of Occupations:

CodeOccupation
132417Procurement manager
332302Procurement representative
122105Contracts manager
243104Tenders specialist
243102Procurement specialist
332301Private-label supply specialist
132415Logistics services manager
132418Warehouse manager
313907Storekeeper
243107E-commerce specialist
243108Market research specialist
241110Warehouse specialist

The guide gives one table. Splitting it into "purchasing" (the first six, all present in 2023) and "supply chain" (the six new ones) is our own grouping, used only to make the report readable.

The rounding. Section 4 says the required number is rounded to the nearest whole number: 0.49 and below goes down, 0.5 and above goes up. Its worked example takes 70 workers in the targeted professions, 20 of them Saudi, in an establishment of 500. 70 times 70% is 49 Saudis, so the establishment must employ 29 more Saudis in those professions. Note that the 500 total plays no part in the calculation. A footnote adds that the establishment must keep the achieved rate when it replaces or hires.

Overlap. If earlier or later decisions target procurement professions at different rates, the higher rate applies (section 3.3). The FAQ says the same about regional Saudization memoranda signed with the emirates of the regions.

Dates. Issued 30 November 2025, a six-month grace period, application from 31 May 2026 (the guide's "grace period" section and its timeline). After that, the penalties apply to every establishment below the rate.

Penalties. Section 6 applies the violations table of Ministerial Decision 75913 (19/5/1445 AH) and Ministerial Decision 44558 (3/4/1446 AH). It also names a specific breach: assigning any task of these professions to a non-Saudi, directly or indirectly, under any other job title.

The FAQ adds three points that matter for code:

  • The decision applies whatever the establishment's Nitaqat band, and the band does not change how the procurement rate is computed.
  • It applies to the occupation titles and to the actual work of the worker.
  • The ministry reviews the rates periodically. Treat 70% as a value that will change, not a constant.

What changed from the 2023 guide

The 2023 guide for Decision 141612 (11/09/1444 AH) set 50% after a nine-month grace period ending 11/06/1445 AH (24 December 2023). It differs in four ways:

  • Six occupations, not twelve. Procurement manager, procurement representative, contracts manager, private-label supply specialist, tenders specialist and procurement specialist. The six supply chain codes did not exist in it.
  • Nine codes for those six. Three occupations also carried an older seven-digit code: 1214041 procurement manager, 5112033 procurement representative and 1217361 contracts manager. The 2026 table drops all three.
  • 50% instead of 70%. Its own worked example used the same 70 workers and 20 Saudis: 35 required, 15 to hire.
  • Different penalties. It referred to Decision 92768 (5/5/1443 AH) and to a table of Qiwa services that are suspended, such as work permits and recruitment.

Neither guide sets a minimum wage for a Saudi to count. Unlike the project management and engineering decisions, there is no GOSI floor to model here.

Step 2: The Rules as Data

Keep each guide as a record, never as constants spread through the code. When the ministry publishes the next update, you add a record and the tests tell you what changed.

// src/rules.ts
export type Family = "purchasing" | "supply-chain";
 
export interface Occupation {
  title: string;
  family: Family;
}
 
export interface QuotaRule {
  decision: string;
  guideIssued: string;   // ISO date
  effectiveFrom: string; // ISO date, end of the grace period
  ratePercent: number;   // whole percent, e.g. 70
  minWorkers: number;    // the rule applies from this many workers in scope
  codes: Record<string, Occupation>;
}
 
// Procedural guide for Ministerial Decision 77050 (30 Nov 2025)
export const PROC_2026: QuotaRule = {
  decision: "77050",
  guideIssued: "2025-11-30",
  effectiveFrom: "2026-05-31",
  ratePercent: 70,
  minWorkers: 3,
  codes: {
    "132417": { title: "Procurement manager", family: "purchasing" },
    "332302": { title: "Procurement representative", family: "purchasing" },
    "122105": { title: "Contracts manager", family: "purchasing" },
    "243104": { title: "Tenders specialist", family: "purchasing" },
    "243102": { title: "Procurement specialist", family: "purchasing" },
    "332301": { title: "Private-label supply specialist", family: "purchasing" },
    "132415": { title: "Logistics services manager", family: "supply-chain" },
    "132418": { title: "Warehouse manager", family: "supply-chain" },
    "313907": { title: "Storekeeper", family: "supply-chain" },
    "243107": { title: "E-commerce specialist", family: "supply-chain" },
    "243108": { title: "Market research specialist", family: "supply-chain" },
    "241110": { title: "Warehouse specialist", family: "supply-chain" },
  },
};
 
// Procedural guide for Ministerial Decision 141612 (11/09/1444 AH),
// enforced from 11/06/1445 AH (24 Dec 2023)
export const PROC_2023: QuotaRule = {
  decision: "141612",
  guideIssued: "2023-04-02",
  effectiveFrom: "2023-12-24",
  ratePercent: 50,
  minWorkers: 3,
  codes: {
    "132417": { title: "Procurement manager", family: "purchasing" },
    "1214041": { title: "Procurement manager (old code)", family: "purchasing" },
    "332302": { title: "Procurement representative", family: "purchasing" },
    "5112033": { title: "Procurement representative (old code)", family: "purchasing" },
    "122105": { title: "Contracts manager", family: "purchasing" },
    "1217361": { title: "Contracts manager (old code)", family: "purchasing" },
    "332301": { title: "Private-label supply specialist", family: "purchasing" },
    "243104": { title: "Tenders specialist", family: "purchasing" },
    "243102": { title: "Procurement specialist", family: "purchasing" },
  },
};

The rate is a whole percent on purpose. Step 3 explains why.

Step 3: Rounding Without Floating Point

In JavaScript, 45 * 0.7 gives 31.499999999999996, not 31.5. Math.round then returns 31 where the guide's rule gives 32: one Saudi short, with a report that says you comply. The same happens at 85, 165 and 175 workers. Working in whole percents avoids the problem: multiply the headcount by 70, add 50, divide by 100 and drop the remainder. That is rounding to the nearest whole number with halves going up, as the guide describes.

// src/quota.ts
// Saudis required for a headcount, rounded to the nearest whole number
// (0.49 and below goes down, 0.5 and above goes up, as the guide says).
// Integer arithmetic only: 45 * 0.7 is 31.499999999999996 in floating point.
export function requiredSaudis(headcount: number, ratePercent: number): number {
  return Math.floor((headcount * ratePercent + 50) / 100);
}
 
// Replacement: swap non-Saudis for Saudis, headcount stays the same.
export function gapByReplacement(
  headcount: number,
  saudis: number,
  ratePercent: number,
): number {
  return Math.max(0, requiredSaudis(headcount, ratePercent) - saudis);
}
 
// Hiring only: each new Saudi raises both sides of the ratio.
export function gapByHiring(
  headcount: number,
  saudis: number,
  ratePercent: number,
): number {
  if (ratePercent >= 100) {
    return saudis >= headcount ? 0 : Number.POSITIVE_INFINITY;
  }
  let hires = 0;
  while (saudis + hires < requiredSaudis(headcount + hires, ratePercent)) {
    hires += 1;
  }
  return hires;
}

The two gap functions answer different questions. Replacement keeps the headcount: swap a non-Saudi for a Saudi and only the numerator moves. Hiring adds people: each new Saudi raises the numerator and the denominator together.

The difference at 70% is large. On the guide's own example, 70 workers with 20 Saudis, replacement needs 29 people. Hiring alone needs 96, because every Saudi you add also adds to the total that the 70% is taken from. The guide's phrase "employ 29 Saudis" only holds if 29 non-Saudis leave those roles at the same time. The loop stops because at any rate under 100% the share of Saudis keeps rising with each hire. The 100% guard lets the same function serve decisions that reserve a profession entirely.

Step 4: Scope Is the Code and the Work

The FAQ is explicit that the decision applies to the classified title and to the actual work. That gives two failure cases, and the module records both:

  • A worker carries one of the twelve codes but does none of that work. We leave that worker out of scope. The right fix is to correct the registration, and the report should make that visible rather than count the person.
  • A worker does procurement or warehouse work under another code. For a non-Saudi, section 6 calls this a breach in its own right. For a Saudi, it is a lost count: the person helps your rate only once the right code is registered.

The second case is common in warehouses. A storekeeper registered as a general labourer, or a logistics coordinator registered under an administrative code, is invisible to the count and visible to an inspector.

// src/assess.ts
import { Family, QuotaRule } from "./rules";
import { requiredSaudis, gapByReplacement, gapByHiring } from "./quota";
 
export interface Worker {
  id: string;
  entityId: string;          // the establishment as the ministry groups it
  branchId: string;
  saudi: boolean;
  occupationCode: string;    // as registered in Qiwa / GOSI
  doesProcurementWork: boolean; // what the person actually does, from the line manager
}
 
export interface Finding {
  kind: "title-mismatch";
  workerId: string;
  saudi: boolean;
}
 
export interface EntityResult {
  entityId: string;
  inScope: number;
  saudis: number;
  applies: boolean;
  required: number;
  rate: number;              // percent, one decimal
  byReplacement: number;
  byHiring: number;
  byFamily: Record<Family, { inScope: number; saudis: number }>;
  findings: Finding[];
}
 
export function assessEntity(
  entityId: string,
  workers: Worker[],
  rule: QuotaRule,
): EntityResult {
  const mine = workers.filter((w) => w.entityId === entityId);
  const findings: Finding[] = [];
 
  // Duties without the code. For a non-Saudi the guide calls this a breach;
  // a Saudi in the same position is simply not counted.
  for (const w of mine) {
    if (w.doesProcurementWork && !(w.occupationCode in rule.codes)) {
      findings.push({ kind: "title-mismatch", workerId: w.id, saudi: w.saudi });
    }
  }
 
  // Scope is the registered code AND the actual work.
  const scoped = mine.filter(
    (w) => w.occupationCode in rule.codes && w.doesProcurementWork,
  );
  const byFamily: EntityResult["byFamily"] = {
    purchasing: { inScope: 0, saudis: 0 },
    "supply-chain": { inScope: 0, saudis: 0 },
  };
  for (const w of scoped) {
    const f = byFamily[rule.codes[w.occupationCode].family];
    f.inScope += 1;
    if (w.saudi) f.saudis += 1;
  }
 
  const n = scoped.length;
  const s = scoped.filter((w) => w.saudi).length;
  const applies = n >= rule.minWorkers;
  return {
    entityId,
    inScope: n,
    saudis: s,
    applies,
    required: applies ? requiredSaudis(n, rule.ratePercent) : 0,
    rate: n === 0 ? 0 : Math.round((s / n) * 1000) / 10,
    byReplacement: applies ? gapByReplacement(n, s, rule.ratePercent) : 0,
    byHiring: applies ? gapByHiring(n, s, rule.ratePercent) : 0,
    byFamily,
    findings,
  };
}

Three details in this function come straight from the guide:

  • Workers are filtered by entityId, not by branch, so the threshold of three and the 70% are both computed across the establishment's branches.
  • The threshold test is n >= rule.minWorkers. Two workers is out, three is in, and only workers in the twelve codes count toward it.
  • byFamily does not affect compliance. It shows HR where the gap sits, which matters because hiring a Saudi storekeeper and hiring a Saudi tenders specialist are very different searches.

The rate is reported to one decimal, but compliance never uses it. Compliance compares counts, because the guide works in whole people.

Step 5: When Two Decisions Cover One Code

The guide and its FAQ both say the higher rate wins when another decision or a regional memorandum targets the same profession. The resolver below does not guess which other decisions exist; it applies that rule to whatever decisions you feed it, considering only those already in force on the date you ask about.

// src/overlap.ts
import { QuotaRule } from "./rules";
 
// When two decisions cover the same code, the higher rate applies.
// Only decisions already in force on the date are considered.
export function ruleFor(
  code: string,
  onDate: string,
  rules: QuotaRule[],
): QuotaRule | undefined {
  return rules
    .filter((r) => code in r.codes && r.effectiveFrom <= onDate)
    .sort((a, b) => b.ratePercent - a.ratePercent)[0];
}

This also handles the transition. Until 30 May 2026, the 2023 rule at 50% governed the six purchasing occupations and nothing governed the warehouse codes. From 31 May, the 2026 rule at 70% governs all twelve. If you keep history, run the resolver per date and your reports for the first half of 2026 stay correct.

Step 6: Diff the 2023 and 2026 Lists

This is the step that catches the expensive mistakes. Run the old and the new rule over the same workforce and list who moved.

// src/diff.ts
import { QuotaRule } from "./rules";
import { Worker } from "./assess";
 
export interface RuleDiff {
  codesAdded: string[];
  codesRemoved: string[];
  workersJoining: string[];  // in scope under the new rule only
  workersLeaving: string[];  // in scope under the old rule only
  rateChange: [number, number];
}
 
export function diffRules(
  oldRule: QuotaRule,
  newRule: QuotaRule,
  workers: Worker[],
): RuleDiff {
  const oldCodes = Object.keys(oldRule.codes);
  const newCodes = Object.keys(newRule.codes);
  const inOld = (w: Worker) => w.occupationCode in oldRule.codes;
  const inNew = (w: Worker) => w.occupationCode in newRule.codes;
  return {
    codesAdded: newCodes.filter((c) => !oldCodes.includes(c)),
    codesRemoved: oldCodes.filter((c) => !newCodes.includes(c)),
    workersJoining: workers.filter((w) => inNew(w) && !inOld(w)).map((w) => w.id),
    workersLeaving: workers.filter((w) => inOld(w) && !inNew(w)).map((w) => w.id),
    rateChange: [oldRule.ratePercent, newRule.ratePercent],
  };
}

What to expect when you run it on a real export:

  • Workers joining: everyone registered as 132415, 132418, 313907, 243107, 243108 or 241110. In a distribution or retail company this can be several times the size of the purchasing team, and it can bring an entity that was below the threshold of three in 2023 above it now.
  • Workers leaving: everyone still on 1214041, 5112033 or 1217361. These are codes from the older classification. Before you enjoy a smaller denominator, check what Qiwa holds for those people today. If they were migrated to 132417, 332302 or 122105, they never left.
  • Rate: 50 to 70. On its own this adds about one Saudi for every five workers in scope.

One trap from writing this step: the codes are object keys that look like integers, and JavaScript returns integer-like keys in numeric order, not in the order you wrote them. If you compare lists, sort them or test against the numeric order.

Step 7: From Findings to an Action Plan

HR does not read objects. Turn the result into lines they can act on. Because 31 May 2026 has passed, the plan counts days in breach.

// src/plan.ts
import { EntityResult } from "./assess";
 
export function phaseOn(today: string, effectiveFrom: string): "grace" | "enforced" {
  return today < effectiveFrom ? "grace" : "enforced";
}
 
export function daysBetween(from: string, to: string): number {
  return Math.round((Date.parse(to) - Date.parse(from)) / 86_400_000);
}
 
export function actionPlan(r: EntityResult, today: string, effectiveFrom: string): string[] {
  const lines: string[] = [];
  if (!r.applies) {
    lines.push(`Entity ${r.entityId}: ${r.inScope} in scope, below the threshold. Re-run on every hire.`);
    return lines;
  }
  lines.push(
    `Entity ${r.entityId}: ${r.saudis}/${r.inScope} Saudi (${r.rate}%), ` +
      `${r.required} required.`,
  );
  const sc = r.byFamily["supply-chain"];
  if (sc.inScope > 0) {
    lines.push(`Warehouse, logistics and market roles: ${sc.saudis}/${sc.inScope} Saudi.`);
  }
  if (r.byReplacement > 0) {
    lines.push(`Replace ${r.byReplacement}, or hire ${r.byHiring} additional Saudis.`);
    lines.push(
      phaseOn(today, effectiveFrom) === "grace"
        ? `${daysBetween(today, effectiveFrom)} days of grace left.`
        : `Grace ended ${effectiveFrom}: in breach for ${daysBetween(effectiveFrom, today)} days.`,
    );
  }
  for (const f of r.findings) {
    lines.push(
      f.saudi
        ? `Worker ${f.workerId} is Saudi and not counted: register the right code in Qiwa.`
        : `Worker ${f.workerId} does procurement work under another code: fix the role or the code.`,
    );
  }
  return lines;
}

Testing Your Implementation

These tests pin every number the guide states, plus the edge cases around them. Run them with npx tsx --test src/assess.test.ts.

// src/assess.test.ts
import { test } from "node:test";
import assert from "node:assert/strict";
import { PROC_2023, PROC_2026 } from "./rules";
import { requiredSaudis, gapByReplacement, gapByHiring } from "./quota";
import { assessEntity, Worker } from "./assess";
import { ruleFor } from "./overlap";
import { diffRules } from "./diff";
import { actionPlan, daysBetween } from "./plan";
 
const w = (id: string, saudi: boolean, code = "243102", extra: Partial<Worker> = {}): Worker => ({
  id, entityId: "E1", branchId: "B1", saudi, occupationCode: code,
  doesProcurementWork: true, ...extra,
});
 
test("guide example: 70 in scope, 20 Saudi, 49 required, 29 to replace", () => {
  assert.equal(requiredSaudis(70, 70), 49);
  assert.equal(gapByReplacement(70, 20, 70), 29);
  assert.equal(gapByReplacement(70, 60, 70), 0); // above the rate: no negative gap
});
 
test("the 2023 guide example at 50% still holds", () => {
  assert.equal(requiredSaudis(70, 50), 35);
  assert.equal(gapByReplacement(70, 20, 50), 15);
});
 
test("rounding is to the nearest whole number", () => {
  assert.equal(requiredSaudis(3, 70), 2);   // 2.1
  assert.equal(requiredSaudis(4, 70), 3);   // 2.8
  assert.equal(requiredSaudis(5, 70), 4);   // 3.5
  assert.equal(requiredSaudis(15, 70), 11); // 10.5
  assert.equal(requiredSaudis(45, 70), 32); // 45 * 0.7 is 31.499999999999996
});
 
test("hiring only needs far more people than replacement", () => {
  assert.equal(gapByHiring(70, 20, 70), 96);
  assert.equal(gapByHiring(5, 2, 70), 4);
  assert.equal(gapByHiring(10, 7, 70), 0);
  assert.equal(gapByHiring(3, 1, 100), Number.POSITIVE_INFINITY);
});
 
test("below three workers in scope the decision does not apply", () => {
  const r = assessEntity("E1", [w("a", false), w("b", false)], PROC_2026);
  assert.equal(r.applies, false);
  assert.equal(r.required, 0);
  assert.equal(r.byReplacement, 0);
});
 
test("only workers in the 12 codes count toward the threshold", () => {
  const ws = [w("a", false), w("b", false), w("c", false, "263101", { doesProcurementWork: false })];
  assert.equal(assessEntity("E1", ws, PROC_2026).applies, false);
});
 
test("branches of one entity are counted together, other entities are not", () => {
  const ws = [
    w("a", true),
    w("b", false, "132418", { branchId: "B2" }),
    w("c", false, "313907", { branchId: "B3" }),
    w("x", false, "243102", { entityId: "E2" }),
  ];
  const r = assessEntity("E1", ws, PROC_2026);
  assert.equal(r.inScope, 3);
  assert.equal(r.required, 2);
  assert.equal(r.byReplacement, 1);
  assert.deepEqual(r.byFamily, {
    purchasing: { inScope: 1, saudis: 1 },
    "supply-chain": { inScope: 2, saudis: 0 },
  });
});
 
test("a code without the work is out of scope; work without the code is flagged", () => {
  const ws = [
    w("a", true), w("b", true), w("c", false),
    w("d", false, "243102", { doesProcurementWork: false }),
    w("e", false, "263101"),
    w("f", true, "263101"),
    w("g", false, "263101", { doesProcurementWork: false }),
  ];
  const r = assessEntity("E1", ws, PROC_2026);
  assert.equal(r.inScope, 3);
  assert.equal(r.saudis, 2);
  assert.equal(r.rate, 66.7);
  assert.deepEqual(r.findings, [
    { kind: "title-mismatch", workerId: "e", saudi: false },
    { kind: "title-mismatch", workerId: "f", saudi: true },
  ]);
});
 
test("warehouse staff were outside the 2023 rule and are inside the 2026 one", () => {
  const ws = [w("a", true), w("b", false, "313907"), w("c", false, "132418"), w("d", false, "241110")];
  assert.equal(assessEntity("E1", ws, PROC_2023).applies, false);
  const now = assessEntity("E1", ws, PROC_2026);
  assert.equal(now.inScope, 4);
  assert.equal(now.byReplacement, 2);
});
 
test("diff between the 2023 and 2026 lists", () => {
  // Codes are integer-like keys: Object.keys returns them in numeric order.
  const ws = [w("a", true, "313907"), w("b", false, "1214041"), w("c", false, "132417")];
  const d = diffRules(PROC_2023, PROC_2026, ws);
  assert.deepEqual(d.codesAdded, ["132415", "132418", "241110", "243107", "243108", "313907"]);
  assert.deepEqual(d.codesRemoved, ["1214041", "1217361", "5112033"]);
  assert.deepEqual(d.workersJoining, ["a"]);
  assert.deepEqual(d.workersLeaving, ["b"]);
  assert.deepEqual(d.rateChange, [50, 70]);
});
 
test("higher rate wins only once in force", () => {
  assert.equal(ruleFor("243102", "2026-05-30", [PROC_2023, PROC_2026])?.decision, "141612");
  assert.equal(ruleFor("243102", "2026-05-31", [PROC_2023, PROC_2026])?.decision, "77050");
  assert.equal(ruleFor("313907", "2026-05-30", [PROC_2023, PROC_2026]), undefined);
  assert.equal(ruleFor("999999", "2026-06-01", [PROC_2026]), undefined);
});
 
test("action plan: grace days before 31 May 2026, breach days after", () => {
  assert.equal(daysBetween("2025-11-30", "2026-05-31"), 182);
  const r = assessEntity("E1", [w("a", true), w("b", false, "313907"), w("c", false)], PROC_2026);
  const before = actionPlan(r, "2026-05-01", PROC_2026.effectiveFrom);
  assert.match(before[1], /Warehouse, logistics and market roles: 0\/1 Saudi/);
  assert.match(before[2], /Replace 1, or hire 3/);
  assert.match(before[3], /30 days of grace left/);
  const now = actionPlan(r, "2026-11-18", PROC_2026.effectiveFrom);
  assert.match(now[3], /in breach for 171 days/);
  const firstDay = actionPlan(r, "2026-05-31", PROC_2026.effectiveFrom);
  assert.match(firstDay[3], /in breach for 0 days/);
});
 
test("an entity that meets the rate gets no gap lines", () => {
  const r = assessEntity("E1", [w("a", true), w("b", true), w("c", false)], PROC_2026);
  assert.deepEqual(actionPlan(r, "2026-11-18", PROC_2026.effectiveFrom), [
    "Entity E1: 2/3 Saudi (66.7%), 2 required.",
  ]);
});

Thirteen tests, all passing on Node 20 and later with tsc --strict clean. We also changed the code on purpose (rounding by 49 instead of 50, floating-point multiplication by 0.7, a strict threshold, dropping the actual-work filter, dropping the entity filter, ignoring the effective date, the wrong sort order, a missing code, a code in the wrong family, the grace boundary off by one day, a negative gap, flagging mismatches without the work) and checked that at least one test fails for each change. Removing the 100% guard makes the hiring test loop forever, which is why the guard is there.

One check the tests cannot do: compare the module's result with what Qiwa shows for the same entity. The ministry computes from its own records. If the two disagree, the cause is almost always the data: a code registered differently in Qiwa than in your HR system, or a branch attached to a different entity.

Troubleshooting

Qiwa shows more workers in scope than your export. Look for warehouse and logistics staff first. They are the six codes your 2023 logic does not know.

A Saudi buyer is not counted. Check the registered code. A Saudi who runs purchasing under a generic administrative code does not count, whatever their real job. The title-mismatch finding with saudi: true is that case.

The numbers jumped in your June 2026 report. That is the resolver switching from the 50% rule to the 70% rule on 31 May, and the six new codes entering the denominator on the same day.

You track several decisions and the counts look doubled. Each worker should be assessed under one rule on a given date. Use ruleFor to assign the rule per worker, then group by rule before calling assessEntity.

The guide's example says hire 29, your module says 96. Both are right for different moves. 29 is the gap if 29 non-Saudis leave those roles. 96 is the number if nobody leaves. Most real plans are a mix; run both and price the mix.

Next Steps

Conclusion

The 70% figure is the headline, but it is not where systems go wrong. They go wrong on the list (twelve codes now, half of them in the warehouse and logistics rather than in purchasing), on the old seven-digit codes that may or may not have been migrated, on counting by branch instead of by establishment, and on workers whose title and real work do not match. Each of these is a few lines of code and one test, and the diff in Step 6 shows you, on your own data, which ones touch you.

The grace period is over, so every week out of compliance is a week of exposure. Correcting registrations in Qiwa costs nothing and can change the count before you hire anyone.

If you want this check wired to your HR system and run before every hire, book a free diagnostic session and we will review your data against the 2026 guide with you.

Send us your project

We reply within one working day.