biz-a-cli 2.3.80-15419 → 2.3.80

package/engine/fina/documents/jvWrite.js

@@ -1,260 +0,0 @@
-/*
- * Doc 8 M5a — how a Journal Voucher is WRITTEN (contract §2.1, §2.1a; appendix F-03). Server-owned: what a browser sends
- * is a request; the numbers, the order and the shape FINA receives are made here.
- *
- * - normalize: debit / credit → one signed GLAMOUNT (4 decimals, C19); PRIMEAMOUNT = base ÷ rate (D6, C16); blank
- *   lines dropped (V21); each problem named by the request's own line number.
- * - validate: what needs FINA's data — the accounts (V25), the rate of the default currency (#7) or of a fixed rate
- *   (F-18), the subsidiary of an AR / AP line (V28–V30), departments and projects (V36, V38, D5), and the balance,
- *   in total (V20) and per department / project (F-05, D7).
- * - payload: json2fina's data. ⚠️ ORDER MATTERS (spike 2026-10-10): a line is GLAccount, Rate, PrimeAmount, GLAmount —
- *   base last, or FINA recomputes it from prime; on edit EVERY line sends `seq` first (a new one max+1 …) — sent
- *   account-first, a new line overwrites a line on the same account; a FINA line no longer carried is deleted.
- */
-import { createHash } from "node:crypto";
-import { toDateOnly } from "../lock.js";
-import { sqlString } from "../sql.js";
-
-const round4 = (n) => Math.round(Number(n) * 10000) / 10000;
-const TOLERANCE = 0.0005;
-const MAX_AMOUNT = 1e14;
-const TEXT_MAX = 80;
-const AR = 8;
-const AP = 13;
-
-/* A number from the request: a number, or invariant text ("1500.5"). Empty → null; anything else → NaN. */
-const num = (v) => {
-	if (v === null || v === undefined || v === "") return null;
-	if (typeof v === "number") return v;
-	const s = String(v).trim();
-	if (s === "") return null;
-	return /^[+-]?\d+(\.\d+)?$/.test(s) ? Number(s) : NaN;
-};
-const text = (v) => {
-	const s = v === null || v === undefined ? "" : String(v).trim();
-	return s === "" ? null : s;
-};
-const extOf = (row) => Object.fromEntries(Object.entries(row ?? {}).filter(([k]) => /^ext_(lookup|customfield)\d+$/.test(k)));
-
-export const normalize = (masterIn = {}, linesIn = []) => {
-	const problems = [];
-	const transdate = toDateOnly(masterIn?.transdate);
-	if (!transdate) problems.push("The date is required.");
-	const transdescription = text(masterIn?.transdescription);
-	if (transdescription && transdescription.length > TEXT_MAX) problems.push(`The description is longer than ${TEXT_MAX} characters.`);
-	const templateid = Number.isInteger(Number(masterIn?.templateid)) && Number(masterIn?.templateid) > 0 ? Number(masterIn.templateid) : null;
-
-	const lines = [];
-	(Array.isArray(linesIn) ? linesIn : []).forEach((raw, i) => {
-		const n = i + 1;
-		const glaccount = text(raw?.glaccount);
-		const debit = num(raw?.debit);
-		const credit = num(raw?.credit);
-		if (!glaccount && !debit && !credit) return;
-		if (!glaccount) problems.push(`Line ${n}: the account is required.`);
-		if (Number.isNaN(debit) || Number.isNaN(credit)) {
-			problems.push(`Line ${n}: the amount is not a number.`);
-			return;
-		}
-		if (debit && credit) {
-			problems.push(`Line ${n}: has both a debit and a credit.`);
-			return;
-		}
-		const base = round4((debit ?? 0) - (credit ?? 0));
-		if (Math.abs(base) >= MAX_AMOUNT) problems.push(`Line ${n}: the amount is too big.`);
-		else if (base === 0) problems.push(`Line ${n}: the amount is zero.`);
-		const rateIn = num(raw?.rate);
-		const rate = rateIn === null ? 1 : rateIn;
-		if (Number.isNaN(rate) || rate < 0) problems.push(`Line ${n}: the rate is not a number.`);
-		else if (rate === 0) problems.push(`Line ${n}: the rate cannot be zero.`);
-		const description = text(raw?.description);
-		if (description && description.length > TEXT_MAX) problems.push(`Line ${n}: the memo is longer than ${TEXT_MAX} characters.`);
-		const seq = Number.isInteger(Number(raw?.seq)) && raw?.seq !== null && raw?.seq !== "" && Number(raw.seq) >= 0 ? Number(raw.seq) : null;
-		lines.push({
-			n,
-			seq,
-			glaccount,
-			glamount: base,
-			rate: Number.isNaN(rate) ? 1 : rate,
-			primeamount: rate > 0 ? round4(base / rate) : base,
-			description,
-			personno: text(raw?.personno),
-			deptno: text(raw?.deptno),
-			projectno: text(raw?.projectno),
-			...extOf(raw),
-		});
-	});
-	if (lines.length === 0 && !problems.some((p) => p.startsWith("Line "))) problems.push("The detail has not been entered.");
-	return { master: { transdate, transdescription, templateid, ...extOf(masterIn) }, lines, problems };
-};
-
-const inList = (values) => [...new Set(values)].map((v) => sqlString(v)).join(", ");
-const yes = (v) => v === true || v === 1 || String(v ?? "").trim() === "1";
-
-/* Everything that needs FINA's data, one query per kind; every problem in one list. */
-export const validate = async ({ client, lines, settings, features }) => {
-	const problems = [];
-	const jv = settings?.jv ?? {};
-	const multiDept = !!features?.multiDept;
-	const multiProject = !!features?.multiProject;
-
-	const company = (await client.executeSql("SELECT DEFAULTCURRENCYID FROM COMPANY"))?.[0] ?? {};
-	const defaultCurrency = Number(company.defaultcurrencyid ?? 1);
-
-	const accounts = new Map();
-	const codes = lines.map((l) => l.glaccount).filter(Boolean);
-	if (codes.length > 0) {
-		const rows =
-			(await client.executeSql(
-				"SELECT A.GLACCOUNT, A.CURRENCYID, A.ACCOUNTTYPE, A.SUSPENDED, C.EXCHANGERATE, " +
-					"(SELECT COUNT(*) FROM GLACCNT S WHERE S.PARENTACCOUNT = A.GLACCOUNT) AS CHILDREN " +
-					`FROM GLACCNT A LEFT JOIN CURRENCY C ON C.CURRENCYID = A.CURRENCYID WHERE A.GLACCOUNT IN (${inList(codes)})`,
-			)) ?? [];
-		for (const r of rows) accounts.set(String(r.glaccount).trim(), r);
-	}
-
-	const persons = new Map();
-	const personCodes = lines.map((l) => l.personno).filter(Boolean);
-	if (personCodes.length > 0) {
-		const rows = (await client.executeSql(`SELECT PERSONNO, CURRENCYID, SUSPENDED FROM PERSONDATA WHERE PERSONNO IN (${inList(personCodes)})`)) ?? [];
-		for (const r of rows) persons.set(String(r.personno).trim(), r);
-	}
-
-	const depts = new Map();
-	const deptCodes = lines.map((l) => l.deptno).filter(Boolean);
-	if (deptCodes.length > 0) {
-		const rows =
-			(await client.executeSql(
-				"SELECT D.DEPTNO, D.SUSPENDED, (SELECT COUNT(*) FROM DEPARTMENT S WHERE S.SUBDEPTID = D.DEPTID AND S.DEPTID <> D.DEPTID) AS CHILDREN " +
-					`FROM DEPARTMENT D WHERE D.DEPTNO IN (${inList(deptCodes)})`,
-			)) ?? [];
-		for (const r of rows) depts.set(String(r.deptno).trim(), r);
-	}
-
-	const projects = new Map();
-	const projectCodes = lines.map((l) => l.projectno).filter(Boolean);
-	if (projectCodes.length > 0) {
-		const rows =
-			(await client.executeSql(
-				"SELECT P.PROJECTNO, P.SUSPENDED, P.FINISHED, (SELECT COUNT(*) FROM PROJECT S WHERE S.SUBPROJECTID = P.PROJECTID AND S.PROJECTID <> P.PROJECTID) AS CHILDREN " +
-					`FROM PROJECT P WHERE P.PROJECTNO IN (${inList(projectCodes)})`,
-			)) ?? [];
-		for (const r of rows) projects.set(String(r.projectno).trim(), r);
-	}
-
-	for (const l of lines) {
-		const at = `Line ${l.n}`;
-		if (l.glaccount) {
-			const a = accounts.get(l.glaccount);
-			if (!a) problems.push(`${at}: account ${l.glaccount} does not exist in FINA.`);
-			else {
-				if (yes(a.suspended)) problems.push(`${at}: account ${l.glaccount} is suspended.`);
-				if (Number(a.children) > 0) problems.push(`${at}: account ${l.glaccount} is a parent account; use one of its sub-accounts.`);
-				const currency = a.currencyid === null || a.currencyid === undefined ? defaultCurrency : Number(a.currencyid);
-				if (currency === defaultCurrency && l.rate !== 1) problems.push(`${at}: the rate of an account in the default currency is 1.`);
-				else if (currency !== defaultCurrency && jv.rateEditable === false && l.rate !== Number(a.exchangerate)) {
-					problems.push(`${at}: the rate is fixed at the currency rate ${Number(a.exchangerate)}.`);
-				}
-				const type = Number(a.accounttype);
-				if ((type === AR || type === AP) && !l.personno) problems.push(`${at}: account ${l.glaccount} needs a subsidiary (customer or vendor).`);
-				if (l.personno) {
-					const p = persons.get(l.personno);
-					if (!p) problems.push(`${at}: subsidiary ${l.personno} does not exist in FINA.`);
-					else {
-						if (yes(p.suspended)) problems.push(`${at}: subsidiary ${l.personno} is suspended.`);
-						const personCurrency = p.currencyid === null || p.currencyid === undefined ? defaultCurrency : Number(p.currencyid);
-						if (personCurrency !== currency) problems.push(`${at}: the currency of subsidiary ${l.personno} does not match the account's.`);
-					}
-				}
-			}
-		}
-		if (l.deptno) {
-			const d = depts.get(l.deptno);
-			if (!d) problems.push(`${at}: department ${l.deptno} does not exist in FINA.`);
-			else if (yes(d.suspended)) problems.push(`${at}: department ${l.deptno} is suspended.`);
-			else if (Number(d.children) > 0) problems.push(`${at}: department ${l.deptno} is a parent; use one of its sub-departments.`);
-		} else if (multiDept && jv.deptMandatory) problems.push(`${at}: the department is required.`);
-		if (l.projectno) {
-			const p = projects.get(l.projectno);
-			if (!p) problems.push(`${at}: project ${l.projectno} does not exist in FINA.`);
-			else if (yes(p.suspended)) problems.push(`${at}: project ${l.projectno} is suspended.`);
-			else if (yes(p.finished)) problems.push(`${at}: project ${l.projectno} is finished.`);
-			else if (Number(p.children) > 0) problems.push(`${at}: project ${l.projectno} is a parent; use one of its sub-projects.`);
-		} else if (multiProject && jv.projectMandatory) problems.push(`${at}: the project is required.`);
-	}
-
-	const out = (sum) => round4(sum);
-	const total = out(lines.reduce((s, l) => s + l.glamount, 0));
-	if (Math.abs(total) > TOLERANCE) problems.push(`Debits and credits are out of balance by ${Math.abs(total)}.`);
-	const byDimension = (key, label) => {
-		const sums = new Map();
-		for (const l of lines) if (l[key]) sums.set(l[key], (sums.get(l[key]) ?? 0) + l.glamount);
-		for (const [code, sum] of sums) if (Math.abs(out(sum)) > TOLERANCE) problems.push(`${label} ${code} is out of balance by ${Math.abs(out(sum))}.`);
-	};
-	if (multiDept) byDimension("deptno", "Department");
-	if (multiProject) byDimension("projectno", "Project");
-	return problems;
-};
-
-const str = (v) => (v === null || v === undefined ? null : String(v));
-const extKeyOf = (mapping) => `extended.${mapping.field}`;
-
-const lineFields = (l, before, isEdit, mappings) => {
-	const out = { GLAccount: str(l.glaccount), Rate: str(l.rate), PrimeAmount: str(l.primeamount), GLAmount: str(l.glamount) };
-	/* An optional value: sent when set; on an edited line also when it was set and is now cleared (null). */
-	const optional = (name, value, was) => {
-		if (value !== null && value !== undefined && value !== "") out[name] = String(value);
-		else if (isEdit && was !== null && was !== undefined && was !== "") out[name] = null;
-	};
-	optional("Description", l.description, before?.description);
-	optional("PersonNo", l.personno, before?.personno);
-	optional("DeptNo", l.deptno, before?.deptno);
-	optional("ProjectNo", l.projectno, before?.projectno);
-	for (const m of mappings.filter((x) => x.part === "detail")) optional(extKeyOf(m), l[m.key], before?.[m.key]);
-	return out;
-};
-
-export const payload = ({ isNew, master, lines, current, mappings = [] }) => {
-	const m = { TransDate: master.transdate, TransDescription: master.transdescription ?? "" };
-	if (master.templateid) m.TemplateID = String(master.templateid);
-	for (const mapping of mappings.filter((x) => x.part === "master")) {
-		if (!(mapping.key in master)) continue;
-		const v = master[mapping.key];
-		if (v === null || v === undefined || v === "") {
-			if (!isNew) m[extKeyOf(mapping)] = null;
-		} else m[extKeyOf(mapping)] = String(v);
-	}
-
-	if (isNew) {
-		m.detail = lines.map((l) => lineFields(l, null, false, mappings));
-		return { master: m };
-	}
-
-	const existing = new Map((current?.lines ?? []).map((l) => [Number(l.seq), l]));
-	let next = Math.max(-1, ...existing.keys()) + 1;
-	const carried = new Set();
-	const detail = lines.map((l) => {
-		if (l.seq !== null && existing.has(l.seq) && !carried.has(l.seq)) {
-			carried.add(l.seq);
-			return { seq: String(l.seq), ...lineFields(l, existing.get(l.seq), true, mappings) };
-		}
-		return { seq: String(next++), ...lineFields(l, null, false, mappings) };
-	});
-	for (const seq of existing.keys()) if (!carried.has(seq)) detail.push({ seq: String(seq), delete: "1" });
-	m.detail = detail;
-	return { master: m };
-};
-
-/* What a JV looked like when it was read: an edit sent against another version is refused (DOCUMENT_CHANGED). */
-export const version = (document) => {
-	const m = document?.master ?? {};
-	const core = {
-		d: toDateOnly(m.transdate),
-		t: m.transdescription ?? null,
-		p: m.templateid ?? null,
-		l: (document?.lines ?? []).map((l) => [l.seq, l.glaccount, Number(l.glamount), Number(l.rate), Number(l.primeamount), l.description ?? null, l.deptno ?? null, l.projectno ?? null, l.personno ?? null]),
-	};
-	return createHash("sha1").update(JSON.stringify(core)).digest("hex").slice(0, 16);
-};
-
-export default { normalize, validate, payload, version };

package/engine/fina/documents/si.js

@@ -1,40 +0,0 @@
-/*
- * Doc 8 M4 — the Sales Invoice: the proof of T-03 (a second form from its descriptor, with no change to the template
- * engine). Read and printed only; Biz-A writes no invoice. Rights: FINA's SALES columns (C/E/R).
- *
- * `ARINVOICEID` drives its report (verified live on template 5, 2026-10-10).
- */
-const number = (v) => (v === null || v === undefined || v === "" ? null : Number(v));
-
-export default {
-	name: "si",
-	label: "Sales Invoice",
-	rights: "sales",
-	templateType: 0,
-	master: {
-		table: "ARINV",
-		key: "ARINVOICEID",
-		select:
-			"M.ARINVOICEID, M.INVOICENO, M.INVOICEDATE, P.PERSONNO AS CUSTOMERNO, P.NAME AS CUSTOMERNAME, M.FOB, M.SHIPVIA, M.SHIPDATE, " +
-			"M.PURCHASEORDERNO, M.DESCRIPTION, M.INVOICEAMOUNT, M.TEMPLATEID, M.EXTENDEDID",
-		from: "ARINV M LEFT JOIN PERSONDATA P ON P.ID = M.CUSTOMERID",
-		filter: null,
-	},
-	detail: {
-		select: "D.SEQ, D.ITEMNO, I.ITEMDESCRIPTION, D.QUANTITY, D.ITEMUNIT, D.UNITPRICE, D.ITEMDISCPC, D.TAXCODES, D.EXTENDEDID",
-		from: "ARINVDET D LEFT JOIN ITEM I ON I.ITEMNO = D.ITEMNO",
-		key: "D.ARINVOICEID",
-		order: "D.SEQ",
-		/* The line amount as the screen shows it; a discount FINA keeps as a formula (10+5) is left to FINA. */
-		line: (row) => {
-			const gross = (number(row.quantity) ?? 0) * (number(row.unitprice) ?? 0);
-			const text = String(row.itemdiscpc ?? "").trim();
-			const disc = /^\d+(\.\d+)?$/.test(text) ? Number(text) : 0;
-			return { ...row, amount: Math.round(gross * (1 - disc / 100) * 10000) / 10000 };
-		},
-	},
-	extended: { master: "ARINV", detail: "ARINVDET" },
-	print: {
-		dictionary: async ({ id }) => [{ param: "ARINVOICEID", value: String(id) }],
-	},
-};

package/engine/fina/errors.js

@@ -1,17 +0,0 @@
-/*
- * Doc 8 — engine/fina's errors carry a CODE, which is what a route answers with (`{ok:false, code, error}`).
- *
- * - UNAUTHENTICATED / FORBIDDEN / NOT_CONFIGURED / FINA_CLOUD_NEEDS_POSTGRES: who may call.
- * - INVALID: the payload, with every reason in the message.
- * - FINA_UNREACHABLE / FINA_ERROR / FINA_REFUSED: the FINA API (down, broken, or said no — its own message).
- * - FEATURE_IN_USE / FEATURES_CHANGED: the features console (C-12, a concurrent desktop write).
- */
-export class FinaError extends Error {
-	constructor(code, message) {
-		super(message);
-		this.name = "FinaError";
-		this.code = code;
-	}
-}
-
-export const finaError = (code, message) => new FinaError(code, message);

package/engine/fina/features.js

@@ -1,86 +0,0 @@
-/*
- * Doc 8 C-04 / C-05 / C-12, D3 — the FINA features the console shows and sets.
- *
- * - Multi Department and Multi Project are characters 9 and 10 of COMPANY.RESERVED1, in Delphi's 1-based string
- *   index (BankConst.pas: idxMultiDept = 9, idxMultiProject = 10, RESERVED1LEN = 19; ReadWriteFeatures.pas). The
- *   console reads and writes the very column the desktop does, so both always agree (C-05).
- * - Multi Currency has NO flag (D3): it is active when CURRENCY holds more than one currency, and the console only
- *   shows it.
- *
- * ⚠️ ONLY CHARACTERS 9 AND 10 ARE WRITTEN. The desktop's Write_Features rebuilds the whole string from every flag it
- * knows; Biz-A knows two, so it keeps every other character exactly as stored (warehouse, serial numbers, rounding…).
- *
- * ⚠️ OPTIMISTIC: the UPDATE matches the value read, then the row is read again. If the desktop wrote in between, the
- * answer is FEATURES_CHANGED ("reload"), never a silent overwrite of the desktop's change.
- *
- * ⚠️ C-12: switching a feature OFF is refused while GL history carries a department / project. Switching ON is
- * always allowed. (The desktop itself has no such check; this is Biz-A's rule.)
- */
-import { finaError } from "./errors.js";
-
-const POSITION = { multiDept: 9, multiProject: 10 };
-const DIGITS = /^[0-9]*$/;
-
-const flagAt = (raw, position) => String(raw ?? "").charAt(position - 1) === "1";
-
-export const readFlags = (raw) => ({ multiDept: flagAt(raw, POSITION.multiDept), multiProject: flagAt(raw, POSITION.multiProject) });
-
-export const withFlags = (raw, { multiDept, multiProject }) => {
-	const chars = String(raw ?? "").padEnd(POSITION.multiProject, "0").split("");
-	chars[POSITION.multiDept - 1] = multiDept ? "1" : "0";
-	chars[POSITION.multiProject - 1] = multiProject ? "1" : "0";
-	return chars.join("");
-};
-
-const IN_USE = {
-	multiDept: { column: "DEPTID", label: "Multi Department", what: "a department" },
-	multiProject: { column: "PROJECTID", label: "Multi Project", what: "a project" },
-};
-
-export const createFeatures = ({ client }) => {
-	const readRaw = async () => {
-		const rows = await client.executeSql("SELECT RESERVED1 FROM COMPANY");
-		const value = rows?.[0]?.reserved1;
-		return value === undefined ? null : value;
-	};
-
-	const read = async () => {
-		const raw = await readRaw();
-		const count = Number((await client.executeSql("SELECT COUNT(*) AS N FROM CURRENCY"))?.[0]?.n ?? 0);
-		return { ...readFlags(raw), multiCurrency: { active: count > 1, count } };
-	};
-
-	const save = async ({ multiDept, multiProject } = {}) => {
-		if (typeof multiDept !== "boolean" || typeof multiProject !== "boolean") {
-			throw finaError("INVALID", "multiDept and multiProject must be true or false.");
-		}
-		const raw = await readRaw();
-		if (raw !== null && !DIGITS.test(String(raw))) {
-			throw finaError("INVALID", "COMPANY.RESERVED1 holds something other than digits; it is left as it is. Check it from FINA desktop.");
-		}
-		const current = readFlags(raw);
-		const wanted = { multiDept, multiProject };
-
-		for (const key of ["multiDept", "multiProject"]) {
-			if (!current[key] || wanted[key]) continue;
-			const { column, label, what } = IN_USE[key];
-			const used = await client.executeSql(`SELECT FIRST 1 1 AS X FROM GLHIST WHERE ${column} IS NOT NULL`);
-			if (used.length > 0) {
-				throw finaError("FEATURE_IN_USE", `${label} cannot be switched off: the general ledger already has entries with ${what}.`);
-			}
-		}
-
-		/* Nothing to change → nothing written. */
-		if (current.multiDept === multiDept && current.multiProject === multiProject) return read();
-
-		const next = withFlags(raw, wanted);
-		const old = raw === null ? "NULL" : `'${raw}'`;
-		await client.block(`EXECUTE BLOCK AS BEGIN UPDATE COMPANY SET RESERVED1 = '${next}' WHERE RESERVED1 IS NOT DISTINCT FROM ${old}; END`);
-		if ((await readRaw()) !== next) {
-			throw finaError("FEATURES_CHANGED", "The FINA features were changed meanwhile (from FINA desktop?). Reload and try again.");
-		}
-		return read();
-	};
-
-	return { read, save };
-};

package/engine/fina/guard.js

@@ -1,102 +0,0 @@
-/*
- * Doc 8 D2 / S-03 — a browser may not write to the FINA Cloud database directly.
- *
- * Every FINA write from Biz-A goes through engine/fina: verified user → FINA user → right → Biz-A date lock → FINA
- * API (which adds FINA's own period lock). The CLI also forwards a browser's raw DataSnap calls to FINA
- * (bin/hubEvent.js forwardToApi, engine/orm/finaEndpoint.js); left open, one hand-made `json2fina` or `block` would
- * skip all of it. So, for the FINA Cloud database only, this lets READS through and refuses everything else.
- *
- * - Reads: `list`, `lookup`, `lookuptotal`, and `orm` with method `get`. Login (`get_valid_user_id`) is a read of its
- *   own and always passes.
- * - ⚠️⚠️ A request is FINA-bound when ANY database index it carries is FINA's — the lookup's, the object's or its own,
- *   `dbIndex` or the legacy `dbindex`. Routing takes them in that order (engine/orm/index.js resolveDbIndex, Delphi's
- *   order too), so a browser reading FINA puts the index INSIDE the object while the outer one names its tenant.
- *   Reading only the outer one let an `orm put` with the tenant outside and FINA inside through to FINA (found
- *   planning Doc 8 M3).
- * - ⚠️ A read that names FINA's USERS table anywhere (a column, a join, a filter subquery) is refused: it holds every
- *   FINA user's password and rights (Agung 2026-10-09; the full read policy is Doc 8 M5).
- * - Refused: `block`, `orm` put / delete / deletemd, `ExecuteSQL`, `genId`, `json2fina`, `template` — anything not
- *   on the read list, including endpoints this file has never heard of.
- * - ⚠️ FAIL CLOSED: while FINA Cloud is on, a FINA-bound request whose database cannot be read from it is refused.
- *   An unreadable request is exactly what a bypass would look like; a legitimate one can be taught to the parsers.
- * - Other databases are untouched, and with FINA Cloud off (no --finaCloudDbindex) this does nothing at all.
- *
- * The request is parsed with the ORM router's own parsers (engine/orm/apiRoute.js), so the guard and the router
- * can never disagree about what a request is.
- */
-import { parseAuthRequest, parseDataSnapRequest, parseExecuteSqlRequest, parseGenIdRequest } from "../orm/apiRoute.js";
-
-export const FINA_WRITE_REFUSED = "FINA_WRITE_REFUSED";
-export const FINA_READ_REFUSED = "FINA_READ_REFUSED";
-
-const ENDPOINT = /\/fina\/rest\/\w+\/(?:%22|")(\w+)(?:%22|")/i;
-const endpointOf = (path) => ENDPOINT.exec(String(path ?? ""))?.[1] ?? String(path ?? "");
-
-const refuse = (what) => ({
-	status: 403,
-	body: {
-		code: FINA_WRITE_REFUSED,
-		error:
-			`FINA Cloud: ${what} is refused. Changes to the FINA database go through Biz-A's FINA engine, ` +
-			"which checks the user's FINA rights and the date lock; they cannot be sent to FINA directly.",
-	},
-});
-
-const READ_ENDPOINTS = new Set(["list", "lookup", "lookuptotal"]);
-const isRead = ({ endpoint, param }) => READ_ENDPOINTS.has(endpoint) || (endpoint === "orm" && String(param?.method ?? "").toLowerCase() === "get");
-
-/* Every database index the request carries, wherever the router could take one from. */
-const INDEX_KEYS = ["dbIndex", "dbindex"];
-const indexesOf = (param) => {
-	const found = [];
-	for (const holder of [param, param?.object, param?.lookup]) {
-		if (!holder || typeof holder !== "object") continue;
-		for (const key of INDEX_KEYS) {
-			const value = Number(holder[key]);
-			if (Number.isInteger(value) && value > 0) found.push(value);
-		}
-	}
-	return found;
-};
-
-const USERS_TABLE = /\bUSERS\b/i;
-const refuseUsersRead = () => ({
-	status: 403,
-	body: {
-		code: FINA_READ_REFUSED,
-		error: "FINA Cloud: reading FINA's USERS table from the browser is refused.",
-	},
-});
-
-/*
- * Doc 8 M8 — is this a browser READ of the FINA Cloud database (`target`)? The read policy (readPolicy.js) asks HERE,
- * with the guard's own parsing, so the two can never disagree about what a request is. A login is not one.
- */
-export const finaBoundRead = (path, body, target) => {
-	if (parseAuthRequest(path, body)) return false;
-	const request = parseDataSnapRequest(path, body);
-	if (!request) return false;
-	return indexesOf(request.param).includes(Number(target)) && isRead(request);
-};
-
-export const refuseFinaCloudWrite = ({ path, body, finaCloudDbIndex }) => {
-	const target = Number(finaCloudDbIndex);
-	if (finaCloudDbIndex === null || finaCloudDbIndex === undefined || finaCloudDbIndex === "" || !Number.isInteger(target) || target <= 0) {
-		return null;
-	}
-
-	if (parseAuthRequest(path, body)) return null;
-
-	const genId = parseGenIdRequest(path);
-	if (genId) return genId.dbIndex === null || genId.dbIndex === target ? refuse("genId") : null;
-
-	const sql = parseExecuteSqlRequest(path, body);
-	if (sql) return sql.dbIndex === null || sql.dbIndex === target ? refuse("ExecuteSQL") : null;
-
-	const request = parseDataSnapRequest(path, body);
-	const indexes = request ? indexesOf(request.param) : [];
-	if (!request || indexes.length === 0) return refuse(`${endpointOf(path)} (its database cannot be read from the request)`);
-	if (!indexes.includes(target)) return null;
-	if (!isRead(request)) return refuse(request.endpoint === "orm" ? `orm ${String(request.param?.method ?? "")}` : request.endpoint);
-	return USERS_TABLE.test(JSON.stringify(request.param ?? {})) ? refuseUsersRead() : null;
-};

package/engine/fina/identity.js

@@ -1,87 +0,0 @@
-/*
- * Doc 8 S-01 / S-02, D4 — who the caller is in FINA, and what they may do there.
- *
- * The VERIFIED Biz-A user (context.js; never an id from a request) → FINA$USER_MAP → FINA's USERS row.
- *
- * Rights are FINA's own columns, one per module × {C create, E edit, R report}. There is no delete or view
- * right in FINA; the desktop uses E for delete (D4): create = C, edit = E, delete = E, print = R, view = every
- * mapped user. Currency has no rights column — the desktop's Kurs menu needs user level 0 or 1 (appendix E-09).
- *
- * ⚠️ An inactive FINA user (USERPASSWORD '-1' or USERLEVEL -1, as FINA marks one) counts as UNMAPPED, so a FINA
- * user switched off on the desktop loses Biz-A access too. USERPASSWORD is filtered on, never selected.
- */
-import { finaError } from "./errors.js";
-
-/* Doc 8 M4: SALES, the Sales Invoice (read and printed for the T-03 proof). */
-const MODULES = { jv: "JV", coa: "COA", dept: "DEPT", proj: "PROJ", sales: "SALES" };
-const NONE = Object.freeze({ create: false, edit: false, delete: false, print: false });
-
-const on = (v) => v === true || v === 1 || String(v ?? "").trim() === "1";
-
-export const ACTIVE_FINA_USER = "USERPASSWORD <> '-1' AND USERLEVEL <> -1";
-
-export const rightsFromUserRow = (row = {}) => {
-	const rights = {};
-	for (const [key, prefix] of Object.entries(MODULES)) {
-		const c = on(row[`${prefix.toLowerCase()}c`]);
-		const e = on(row[`${prefix.toLowerCase()}e`]);
-		const r = on(row[`${prefix.toLowerCase()}r`]);
-		rights[key] = { create: c, edit: e, delete: e, print: r };
-	}
-	const level = Number(row.userlevel);
-	rights.currency = level === 0 || level === 1 ? { create: true, edit: true, delete: true, print: true } : { ...NONE };
-	return rights;
-};
-
-const RIGHT_COLUMNS = Object.values(MODULES)
-	.flatMap((p) => [`${p}C`, `${p}E`, `${p}R`])
-	.join(", ");
-
-/*
- * Doc 8 M3 — the server's own check of a FINA right (S-02, S-03; FINA's master datasets check none, appendix E-09).
- * `action` null = only a mapped FINA user (D4: view is every mapped user). Answers the identity it was given.
- */
-export const requireRight = (identity, module, action) => {
-	if (!identity?.mapped) {
-		throw finaError(
-			"FORBIDDEN",
-			identity?.reason ?? "Your Biz-A user is not mapped to a FINA user. An administrator maps it in the FINA Cloud console.",
-		);
-	}
-	if (action && identity.rights?.[module]?.[action] !== true) {
-		throw finaError("FORBIDDEN", `Your FINA user ${identity.finaUser?.name ?? ""} may not ${action} ${module} records.`.replace(/\s+/g, " "));
-	}
-	return identity;
-};
-
-export const verifiedUserId = (principal) => {
-	const raw = principal?.userId;
-	const id = Number(raw);
-	if (raw === null || raw === undefined || typeof raw === "boolean" || !Number.isInteger(id) || !/^\d+$/.test(String(raw))) {
-		throw finaError("UNAUTHENTICATED", "No verified Biz-A user — sign in again.");
-	}
-	return id;
-};
-
-export const createIdentity = ({ exec, client }) => ({
-	resolve: async (principal) => {
-		const userId = verifiedUserId(principal);
-		const mapped = (await exec(`SELECT FINA_USER_ID FROM FINA$USER_MAP WHERE BIZA_USER_ID = ${userId}`)) ?? [];
-		if (mapped.length === 0) return { mapped: false };
-
-		const finaUserId = Number(mapped[0].fina_user_id);
-		if (!Number.isInteger(finaUserId)) return { mapped: false, reason: "The FINA user mapping is unreadable." };
-		const rows = await client.executeSql(
-			`SELECT USERID, USERNAME, USERLEVEL, ${RIGHT_COLUMNS} FROM USERS WHERE USERID = ${finaUserId} AND ${ACTIVE_FINA_USER}`,
-		);
-		if (!rows?.length) {
-			return { mapped: false, reason: `FINA user ${finaUserId} does not exist or is inactive in FINA.` };
-		}
-		const row = rows[0];
-		return {
-			mapped: true,
-			finaUser: { id: Number(row.userid), name: String(row.username ?? ""), userLevel: Number(row.userlevel) },
-			rights: rightsFromUserRow(row),
-		};
-	},
-});

package/engine/fina/live.js

@@ -1,19 +0,0 @@
-/*
- * Doc 8 — engine/fina's live dependencies: this hub's PostgreSQL database and the FINA API.
- *
- * Kept apart from the routes so a test hands its own (`context.deps`) and never opens a pool or a socket.
- */
-import { execPostgres, execPostgresStatements, withPostgresTransaction } from "../domain/dialect.js";
-import { resolveIsAdministrator } from "../orm/userGroups.js";
-import { createFinaClient } from "./client.js";
-
-export const createLiveFinaDeps = (config) => {
-	const tenant = config.tenantDbIndex;
-	return {
-		exec: (sql) => execPostgres(sql, tenant),
-		execStatements: (statements) => execPostgresStatements(statements, tenant),
-		transaction: (fn) => withPostgresTransaction(tenant, fn),
-		client: createFinaClient({ url: config.url, dbIndex: config.dbIndex }),
-		isAdministrator: (userId) => resolveIsAdministrator({ exec: execPostgres, dbIndex: tenant, userId }),
-	};
-};

package/engine/fina/lock.js

@@ -1,35 +0,0 @@
-/*
- * Doc 8 C-14 / D2a — the Biz-A date lock.
- *
- * From Biz-A, nothing dated ON OR BEFORE "locked up to" may be created, edited, deleted or mass-edited. It is
- * Biz-A's only (FINA desktop is unchanged); FINA's own period lock (C-15) stays in the FINA API.
- *
- * ⚠️ CALENDAR DAYS, compared as `YYYY-MM-DD` strings. A Date is read in the server's local zone and a string by its
- * first ten characters, so no conversion can move a document to the day before.
- */
-const DAY = /^(\d{4})-(\d{2})-(\d{2})/;
-
-const pad = (n) => String(n).padStart(2, "0");
-
-export const toDateOnly = (value) => {
-	if (value instanceof Date) {
-		return Number.isNaN(value.getTime()) ? null : `${value.getFullYear()}-${pad(value.getMonth() + 1)}-${pad(value.getDate())}`;
-	}
-	const match = DAY.exec(String(value ?? "").trim());
-	if (!match) return null;
-	const [, y, m, d] = match.map(Number);
-	const check = new Date(y, m - 1, d);
-	/* 2026-02-30 rolls over to March: not a day. */
-	if (check.getFullYear() !== y || check.getMonth() !== m - 1 || check.getDate() !== d) return null;
-	return match[0];
-};
-
-/* ⚠️ With a lock set, a date that cannot be read is LOCKED: refusing is recoverable, a write that slipped past the
-   lock is not. */
-export const isDateLocked = (date, upTo) => {
-	const lock = toDateOnly(upTo);
-	if (!lock) return false;
-	const day = toDateOnly(date);
-	if (!day) return true;
-	return day <= lock;
-};