import crypto from "node:crypto"; import type { SaudiLawDomain, SaudiLawRoutingResult, } from "./saudiLawRouting"; export const SAUDI_OFFICIAL_SOURCE_HOSTS = [ "laws.boe.gov.sa", "boe.gov.sa", "laws.moj.gov.sa", "moj.gov.sa", "misa.gov.sa", "bankruptcy.gov.sa", "mc.gov.sa", "sama.gov.sa", ] as const; export type SaudiLawSourceSnippet = { article: string; text: string; keywords: string[]; }; export type SaudiLawOfficialSource = { sourceId: string; domain: SaudiLawDomain; title: string; authority: string; language: "en" | "ar"; url: string; alternateUrls?: string[]; articles: string[]; snippets: SaudiLawSourceSnippet[]; }; export type SaudiLawSourcePacket = { packetId: string; domain: SaudiLawDomain; sources: SaudiLawOfficialSource[]; snippets: Array< SaudiLawSourceSnippet & { sourceId: string; title: string; url: string; language: "en" | "ar"; } >; }; export type SaudiLawSourcePacketUse = { packet_available: boolean; source_packet_source_ids: string[]; source_packet_cited_source_ids: string[]; official_source_packet_cited: boolean; source_packet_article_mentioned: boolean; }; const SOURCE_REGISTRY: SaudiLawOfficialSource[] = [ { sourceId: "SRC-CL-EN-001", domain: "companies", title: "Companies Law", authority: "Ministry of Investment / official English translation", language: "en", url: "https://misa.gov.sa/app/uploads/2025/07/Companies-Law.pdf", alternateUrls: [ "https://laws.boe.gov.sa/BoeLaws/Laws/LawDetails/a8376aea-1bc3-49d4-9027-aed900b555af/1", "https://mc.gov.sa/ar/Documents/CompaniesLaw.pdf", ], articles: ["4", "7", "8", "9", "35", "45", "75", "132", "156", "162"], snippets: [ { article: "4", text: "Article 4 lists the permitted company forms: general partnership, limited partnership, joint-stock company, simplified joint-stock company, and limited liability company.", keywords: ["company forms", "recognized", "forms"], }, { article: "7(3)", text: "Article 7(3) states that articles of incorporation or articles of association must be in Arabic and may be accompanied by a translation into another language.", keywords: ["arabic", "articles of incorporation", "articles of association"], }, { article: "8(4)", text: "Article 8(4) states that articles of incorporation, articles of association, or amendments may not be used as evidence against third parties before Commercial Register registration; unregistered information is not valid against third parties.", keywords: ["third party", "commercial register", "amendment", "registered"], }, { article: "9(1)", text: "Article 9(1) states that a company acquires legal personality upon registration with the Commercial Register, with limited incorporation-period personality only as needed to complete incorporation.", keywords: ["legal personality", "commercial register", "registration"], }, { article: "9(2)-(3)", text: "Article 9(2) transfers contracts and transactions made by incorporators on behalf of the company to the company after Commercial Register registration. Article 9(3) makes the acting persons personally and jointly liable to third parties if incorporation procedures are not completed.", keywords: ["incorporator", "before registration", "pre-incorporation", "contract"], }, { article: "35", text: "Article 35 defines a general partnership as a company whose partners are jointly and personally liable for the company's debts and liabilities.", keywords: ["general partnership", "debts", "liabilities", "personally liable"], }, { article: "45(1)", text: "Article 45(1) states that a new partner joining with a new contribution is personally and jointly liable for past and future company debts, unless unanimously relieved from past debts; that relief is valid against creditors from Commercial Register registration and publication.", keywords: ["new partner", "joins", "past debts", "future debts"], }, { article: "45(2)", text: "Article 45(2) states that a withdrawing or removed partner is not liable for debts incurred after registration and publication of the withdrawal/removal, but remains liable for prior debts unless the partners and creditors agree to release him.", keywords: ["withdraws", "withdrawal", "later debts", "earlier debts"], }, { article: "75", text: "Article 75 requires general assembly approval for sale of company assets whose value exceeds 50% of total assets, whether by one transaction or more; the percentage is calculated from the first transaction within the previous 12 months.", keywords: ["55%", "50%", "assets", "12 months", "board approval"], }, { article: "132", text: "Article 132 requires the board, when joint-stock company losses reach half of issued capital, to announce the losses and recommendations within 60 days of knowledge, and call an extraordinary general assembly within 180 days to consider continuation with remedial measures or dissolution.", keywords: ["losses", "50%", "issued capital", "60 days", "180 days"], }, { article: "156", text: "Article 156 states that an LLC's assets and liabilities are separate from those of its partners or owner; the company alone is liable for its debts, and owners/partners are liable only in proportion to their interests in the capital.", keywords: ["limited liability company", "llc", "personally liable", "company debts"], }, { article: "162(2)-(3)", text: "Article 162(2) states that appointing, replacing, or restricting an LLC manager is not valid against third parties until registered with the Commercial Register. Article 162(3) states that the company is bound by the manager's acts within the company's purposes.", keywords: ["manager", "authority", "restriction", "third party", "company purposes"], }, ], }, { sourceId: "SRC-CPL-AR-001", domain: "commercial_papers", title: "Commercial Papers Law", authority: "Bureau of Experts at the Council of Ministers", language: "ar", url: "https://laws.boe.gov.sa/BoeLaws/Laws/LawDetails/4763eb94-047b-46f1-9697-a9a700f1b7ed/1", alternateUrls: [ "https://laws.boe.gov.sa/Files/Download/?attId=4fc2998b-1a55-4c16-bde7-adbb0119b96d", ], articles: ["87", "88", "91", "92", "102"], snippets: [ { article: "87", text: "Article 87 requires a promissory note to include the phrase for promissory note in the body of the instrument and in the language in which it is written.", keywords: ["promissory note", "requirements", "body"], }, { article: "88(a)", text: "Article 88(a) states that if a promissory note lacks a maturity date, it is deemed payable at sight.", keywords: ["promissory note", "maturity", "no maturity date", "payable"], }, { article: "91", text: "Article 91 requires a check to include the word check in the body of the instrument and in the language in which it is written.", keywords: ["check", "cheque", "body", "word check"], }, { article: "92", text: "Article 92 states that an instrument lacking one of the required particulars in Article 91 is not considered a check except in the stated exceptions.", keywords: ["check", "missing particulars", "not considered"], }, { article: "102", text: "Article 102 states that a check is payable on sight, and if presented before the date written as its issue date, it must be paid on the day of presentation.", keywords: ["future issue date", "post-dated", "payable", "presented"], }, ], }, { sourceId: "SRC-CCL-EN-001", domain: "commercial_courts", title: "Law of Commercial Courts", authority: "Ministry of Justice / official English translation", language: "en", url: "https://www.moj.gov.sa/Documents/Regulations/pdf/En/96.pdf", alternateUrls: [ "https://laws.moj.gov.sa/ar/legislation/5-3nY9odCRxj7FPBTXJG0Q", ], articles: ["16", "19", "38"], snippets: [ { article: "16(1)-(2)", text: "Article 16 covers disputes between merchants arising from original or ancillary commercial activities, and certain original claims above the statutory/regulatory threshold.", keywords: ["commercial court", "jurisdiction", "merchant", "threshold"], }, { article: "19(1)", text: "Article 19(1) requires written pre-action notice at least 15 days before filing for lawsuits identified by the Implementing Regulations.", keywords: ["pre-action notice", "15 days", "filing"], }, { article: "38(2)-(5)", text: "Article 38 provides that no specific evidentiary form is required to prove liability unless the parties agree otherwise; the court validates agreed evidentiary rules that do not violate public policy, and parties may agree to shift burden of proof where the Law is silent.", keywords: ["evidence", "specific form", "liability", "burden of proof"], }, ], }, { sourceId: "SRC-CCL-REG-EN-001", domain: "commercial_courts", title: "Implementing Regulations of the Commercial Courts Law", authority: "Ministry of Justice", language: "en", url: "https://www.moj.gov.sa/Documents/Regulations/pdf/En/pdf/The%20Implementing%20Regulations%20of%20the%20Commercial%20Courts%20Law.pdf", alternateUrls: [ "https://laws.moj.gov.sa/ar/legislation/s6IDjaBqLFPEFLlY8MedIg", ], articles: ["31", "69", "70", "71", "72"], snippets: [ { article: "31", text: "Article 31 sets the operative original-claim threshold for relevant Commercial Courts Law Article 16(2) claims at more than SAR 500,000.", keywords: ["threshold", "500,000", "commercial court"], }, { article: "69-72", text: "Articles 69-72 identify covered and excluded claims, required notice contents, delivery methods, and proof-of-notice requirements for commercial-court pre-action notice.", keywords: ["pre-action notice", "delivery", "proof", "exclusions"], }, ], }, { sourceId: "SRC-BL-AR-052", domain: "bankruptcy", title: "Bankruptcy Law", authority: "Bureau of Experts at the Council of Ministers", language: "ar", url: "https://laws.boe.gov.sa/BoeLaws/Laws/LawDetails/68204119-84f1-4789-8fad-a9ec014c3788/1", articles: ["52"], snippets: [ { article: "52", text: "Article 52 includes trustee/expert conflict restrictions involving debtor creditors, spouse, in-laws/relatives to the fourth degree, partners, employees, auditors, and agents during the prior two years, with removal and fee consequences.", keywords: ["bankruptcy", "trustee", "expert", "conflict", "relative"], }, ], }, { sourceId: "SRC-BL-THRESH-001", domain: "bankruptcy", title: "Bankruptcy Commission official threshold materials", authority: "Bankruptcy Commission", language: "ar", url: "https://www.bankruptcy.gov.sa/ar/KnowledgeCenter/FAQ/Pages/FAQ.aspx", alternateUrls: [ "https://bankruptcy.gov.sa/ar/BankruptcyLaw/BankruptcyProcedures/Pages/Liquidation-Procedure.aspx", "https://bankruptcy.gov.sa/ar/BankruptcyLaw/BankruptcyProcedures/Pages/Small-Debtors%27-Liquidation-Procedure.aspx", ], articles: ["Creditor liquidation threshold"], snippets: [ { article: "Creditor liquidation threshold", text: "Official Bankruptcy Commission materials conflict on the exact minimum-debt boundary: one FAQ describes SAR 50,000, while liquidation procedure pages say the claimed debt must exceed SAR 50,000.", keywords: ["50,000", "liquidation", "threshold", "creditor"], }, ], }, { sourceId: "SRC-CTL-EN-001", domain: "civil_transactions", title: "Civil Transactions Law", authority: "Ministry of Investment / official English translation", language: "en", url: "https://misa.gov.sa/app/uploads/2025/07/Civil-Transactions-Law.pdf", alternateUrls: [ "https://laws.boe.gov.sa/BoeLaws/Laws/LawDetails/655fdb42-8c96-422b-b8c4-b04f0095c94c/1", ], articles: ["2", "41-43", "95-97", "104", "107", "110-113", "128", "167", "172", "174", "178-179", "461-478"], snippets: [ { article: "general", text: "Use the current official Arabic Civil Transactions Law text as controlling authority; the official English translation is guidance only.", keywords: ["civil transactions", "contract", "good faith", "contractor"], }, ], }, ]; function articleTokens(values: readonly string[] = []): string[] { return values .flatMap((value) => String(value).match(/\d+/g) ?? []) .filter(Boolean); } function sourceScore( source: SaudiLawOfficialSource, input: { text: string; sourceSnapshotIds: Set; articleHints: string[]; }, ): number { let score = 0; if (input.sourceSnapshotIds.has(source.sourceId)) score += 100; const sourceArticles = new Set(articleTokens(source.articles)); for (const article of articleTokens(input.articleHints)) { if (sourceArticles.has(article)) score += 12; } const lower = input.text.toLowerCase(); for (const snippet of source.snippets) { if (snippet.keywords.some((kw) => lower.includes(kw.toLowerCase()))) { score += 4; } } return score; } function snippetScore( snippet: SaudiLawSourceSnippet, input: { text: string; articleHints: string[] }, ): number { let score = 0; const lower = input.text.toLowerCase(); if (snippet.keywords.some((kw) => lower.includes(kw.toLowerCase()))) { score += 10; } const snippetArticles = new Set(articleTokens([snippet.article])); for (const article of articleTokens(input.articleHints)) { if (snippetArticles.has(article)) score += 20; } return score; } function packetHash(value: unknown): string { return crypto .createHash("sha256") .update(JSON.stringify(value)) .digest("hex") .slice(0, 12); } export function buildSaudiLawSourcePacket(input: { routing: SaudiLawRoutingResult; userText: string; sourceSnapshotIds?: string[]; articleHints?: string[]; }): SaudiLawSourcePacket { const text = input.userText ?? ""; const articleHints = input.articleHints ?? []; const sourceSnapshotIds = new Set(input.sourceSnapshotIds ?? []); const domainSources = SOURCE_REGISTRY.filter( (source) => source.domain === input.routing.domain || sourceSnapshotIds.has(source.sourceId), ); const scoredSources = domainSources .map((source) => ({ source, score: sourceScore(source, { text, sourceSnapshotIds, articleHints }), })) .sort((a, b) => b.score - a.score || a.source.sourceId.localeCompare(b.source.sourceId)); const selectedSources = scoredSources .filter((row) => row.score > 0) .map((row) => row.source); const fallbackSources = selectedSources.length > 0 ? selectedSources : domainSources.slice(0, input.routing.domain === "unknown" ? 0 : 2); const sources = fallbackSources.slice(0, 4); const snippets = sources .flatMap((source) => source.snippets.map((snippet) => ({ ...snippet, sourceId: source.sourceId, title: source.title, url: source.url, language: source.language, score: snippetScore(snippet, { text, articleHints }), })), ) .sort((a, b) => b.score - a.score || a.sourceId.localeCompare(b.sourceId)) .slice(0, 8) .map(({ score: _score, ...snippet }) => snippet); return { packetId: `saudi-source-packet-v1-${packetHash({ domain: input.routing.domain, sources: sources.map((source) => source.sourceId), snippets: snippets.map((snippet) => `${snippet.sourceId}:${snippet.article}`), })}`, domain: input.routing.domain, sources, snippets, }; } export function summarizeSaudiLawSourcePacket( packet: SaudiLawSourcePacket | null | undefined, ): Record | null { if (!packet) return null; return { packet_id: packet.packetId, domain: packet.domain, source_ids: packet.sources.map((source) => source.sourceId), snippet_count: packet.snippets.length, articles: packet.snippets.map((snippet) => snippet.article), }; } export function renderSaudiLawSourcePacketHintsBanner( packet: SaudiLawSourcePacket, ): string { if (packet.sources.length === 0) { return ""; } const sourceLines = packet.sources .map((source) => { const alternates = source.alternateUrls?.length ? `; alternates: ${source.alternateUrls.join(", ")}` : ""; return `- ${source.sourceId} | ${source.title} | ${source.authority} | ${source.language} | ${source.url}${alternates}`; }) .join("\n"); const articleHints = packet.snippets.length ? [...new Set(packet.snippets.map((snippet) => snippet.article))].join( ", ", ) : "none matched"; return ( "[SYSTEM NOTIFICATION: SAUDI LAW OFFICIAL SOURCE PACKET HINTS]\n" + `Packet ID: ${packet.packetId}\n` + "These are routing hints only — not pre-loaded rule text. Do not answer from memory; use web_search and backend-fetched evidence to find the controlling provisions.\n" + "Cite source IDs, article numbers, and official URLs from live grounding when available.\n" + "If hints do not cover the needed provision, search official Saudi domains before answering.\n\n" + "Official packet sources:\n" + `${sourceLines}\n\n` + `Relevant article hints: ${articleHints}` ); } export function renderSaudiLawSourcePacketBanner( packet: SaudiLawSourcePacket, ): string { if (packet.sources.length === 0) { return ""; } const sourceLines = packet.sources .map((source) => { const alternates = source.alternateUrls?.length ? `; alternates: ${source.alternateUrls.join(", ")}` : ""; return `- ${source.sourceId} | ${source.title} | ${source.authority} | ${source.language} | ${source.url}${alternates}`; }) .join("\n"); const snippetLines = packet.snippets.length ? packet.snippets .map( (snippet) => `- [${snippet.sourceId} Art. ${snippet.article}] ${snippet.text}`, ) .join("\n") : "- No article-level excerpt matched the user question. Use only the source URLs as starting points, then search official sites."; return ( "[SYSTEM NOTIFICATION: SAUDI LAW OFFICIAL SOURCE PACKET]\n" + `Packet ID: ${packet.packetId}\n` + "Use this packet as the first official evidence layer for the Saudi-law answer. Keep web_search enabled for currentness checks and gaps, but do not ignore matching packet excerpts.\n" + "When a packet excerpt answers the question, cite the source ID and article in the answer, e.g. [SRC-CL-EN-001 Art. 9]. If web search provides a newer or conflicting official source, explain the conflict and prefer the current official Arabic source.\n" + "If the packet does not cover the needed provision, say the packet does not cover it and search official Saudi domains before answering. Do not fill gaps from memory.\n\n" + "Official packet sources:\n" + `${sourceLines}\n\n` + "Relevant packet excerpts:\n" + `${snippetLines}` ); } export function evaluateSaudiLawSourcePacketUse( text: string, packet: SaudiLawSourcePacket | null | undefined, articleHints: string[] = [], ): SaudiLawSourcePacketUse { const sourceIds = packet?.sources.map((source) => source.sourceId) ?? []; const citedSourceIds = sourceIds.filter((sourceId) => text.includes(sourceId), ); const citedUrls = packet?.sources.filter((source) => [source.url, ...(source.alternateUrls ?? [])].some((url) => text.includes(url), ), ) ?? []; const articleMentioned = articleHints.length === 0 || articleTokens(articleHints).some((article) => new RegExp(`\\b(?:article|art\\.?|المادة)\\s*${article}\\b`, "i").test(text), ); return { packet_available: sourceIds.length > 0, source_packet_source_ids: sourceIds, source_packet_cited_source_ids: citedSourceIds, official_source_packet_cited: citedSourceIds.length > 0 || citedUrls.length > 0, source_packet_article_mentioned: articleMentioned, }; }