@classytic/labs 0.6.0 → 0.7.0

package/dist/domains/accounting/trial-balance/model.mjs

@@ -0,0 +1,569 @@
+import { defineLabModel } from "../../../model/define.mjs";
+import { formatMoney, formatNumber, groupingFor } from "../../../model/money.mjs";
+import { refuse } from "../../../model/index.mjs";
+import { z } from "zod";
+import { applyTrialBalanceErrorEffect, diagnoseTrialBalanceError, placeBalanceClass, prepareTrialBalance, trialBalanceErrorEffectFits } from "@classytic/stage/finance/accounting";
+
+//#region src/domains/accounting/trial-balance/model.ts
+/**
+* The trial balance (balance method), built row by row from ledger balances, then tested against errors.
+*
+* Build: the learner takes the ledger balances one at a time and puts each in the debit column, the credit column,
+* or leaves it out. The right column is never authored: it follows from the balance's class and that class's place in
+* the extended equation (stage `placeBalanceClass`). A left term (assets) and a term subtracted on the right
+* (drawings, expenses) carry debit balances; a right term (liabilities, capital, income) a credit balance; a provision
+* against an asset reduces that asset, so it is a credit; an item that is not a ledger balance on the date (closing
+* stock, a contingent item) stays out. The book's inclusion rules are classes plus a lesson-written `why`
+* (opening stock is an expense, rent with no "paid" or "received" is taken as paid). A right placement lands the row
+* in the drawn trial balance; a wrong one stays in the rack with the reason. When every balance is placed the totals
+* agree and are double-ruled.
+*
+* Errors: the finished trial balance and a list of errors. For each the learner predicts whether the totals still
+* agree, then sees the error's effect on both totals. This is the book's "errors the trial balance finds, and those
+* it cannot". Each error's effect is authored and checked against its kind (stage `trialBalanceErrorEffectFits`).
+*
+* Headings and sentences are the lesson's (it writes Bangla); the lab's own buttons stay English.
+*/
+const balanceClass = z.enum([
+	"asset",
+	"liability",
+	"capital",
+	"drawings",
+	"income",
+	"expense",
+	"contra-asset",
+	"excluded"
+]);
+const errorKind = z.enum([
+	"one-sided-entry",
+	"same-side-entry",
+	"unequal-entry",
+	"balance-error",
+	"transfer-error",
+	"casting-error",
+	"balance-omitted",
+	"complete-omission",
+	"original-entry",
+	"commission",
+	"compensating",
+	"principle",
+	"complete-reversal"
+]);
+const text = (max) => z.string().trim().min(1).max(max);
+const id = z.string().trim().min(1).max(40).regex(/^[A-Za-z0-9_-]+$/, "ids use letters, digits, - and _");
+const accountSchema = z.object({
+	id,
+	name: text(60).describe("the account title as the lesson writes it"),
+	balance: z.number().positive().finite().max(1e9).describe("the ledger balance"),
+	class: balanceClass.describe("what the balance is; the column follows from it: asset, drawings, expense debit; liability, capital, income, contra-asset credit; excluded stays out"),
+	code: text(12).optional().describe("the account code; rows are numbered 1, 2, 3 without one"),
+	folio: text(12).optional().describe("the ledger folio (L.F.) shown in its column"),
+	why: text(200).optional().describe("the rule for this balance, shown when it is placed (opening stock, rent with no paid or received)")
+});
+const errorSchema = z.object({
+	id,
+	text: text(240).describe("the error as the lesson tells it"),
+	kind: errorKind.describe("the kind of error; checked against its effect"),
+	effect: z.object({
+		debit: z.number().finite().describe("how much the debit total moves (negative when understated)"),
+		credit: z.number().finite().describe("how much the credit total moves")
+	}).describe("what the error does to the two totals"),
+	why: text(240).optional().describe("the explanation shown after the prediction")
+});
+const DEFAULT_ACCOUNTS = [
+	{
+		id: "cash",
+		name: "Cash",
+		balance: 18e3,
+		class: "asset"
+	},
+	{
+		id: "furniture",
+		name: "Furniture",
+		balance: 25e3,
+		class: "asset"
+	},
+	{
+		id: "opening-stock",
+		name: "Opening stock",
+		balance: 12e3,
+		class: "expense",
+		why: "Opening stock is an expense here."
+	},
+	{
+		id: "purchases",
+		name: "Purchases",
+		balance: 4e4,
+		class: "expense"
+	},
+	{
+		id: "rent",
+		name: "Rent",
+		balance: 6e3,
+		class: "expense",
+		why: "No \"paid\" or \"received\": taken as paid."
+	},
+	{
+		id: "receivable",
+		name: "Accounts receivable",
+		balance: 15e3,
+		class: "asset"
+	},
+	{
+		id: "bad-debt-provision",
+		name: "Provision for bad debts",
+		balance: 1e3,
+		class: "contra-asset"
+	},
+	{
+		id: "payable",
+		name: "Accounts payable",
+		balance: 9e3,
+		class: "liability"
+	},
+	{
+		id: "sales",
+		name: "Sales",
+		balance: 7e4,
+		class: "income"
+	},
+	{
+		id: "capital",
+		name: "Capital",
+		balance: 4e4,
+		class: "capital"
+	},
+	{
+		id: "drawings",
+		name: "Drawings",
+		balance: 4e3,
+		class: "drawings"
+	},
+	{
+		id: "closing-stock",
+		name: "Closing stock",
+		balance: 14e3,
+		class: "excluded",
+		why: "Closing stock is not a ledger balance yet."
+	},
+	{
+		id: "contingent",
+		name: "Contingent liability",
+		balance: 5e3,
+		class: "excluded",
+		why: "Not certain, so it stays out."
+	}
+];
+const DEFAULT_ERRORS = [
+	{
+		id: "one-sided",
+		text: "Cash paid to a supplier, 5,000, was never posted to cash.",
+		kind: "one-sided-entry",
+		effect: {
+			debit: 5e3,
+			credit: 0
+		}
+	},
+	{
+		id: "omitted",
+		text: "A credit sale of 5,000 was never recorded.",
+		kind: "complete-omission",
+		effect: {
+			debit: -5e3,
+			credit: -5e3
+		}
+	},
+	{
+		id: "wrong-account",
+		text: "Cash from Kalam Traders, 2,000, was credited to Salam Traders.",
+		kind: "commission",
+		effect: {
+			debit: 0,
+			credit: 0
+		}
+	},
+	{
+		id: "cast",
+		text: "The sales journal was added up 1,000 short.",
+		kind: "casting-error",
+		effect: {
+			debit: 0,
+			credit: -1e3
+		}
+	},
+	{
+		id: "compensating",
+		text: "Rent was debited 500 short and sales credited 500 short.",
+		kind: "compensating",
+		effect: {
+			debit: -500,
+			credit: -500
+		}
+	},
+	{
+		id: "principle",
+		text: "Furniture repairs, 3,000, were debited to furniture.",
+		kind: "principle",
+		effect: {
+			debit: 0,
+			credit: 0
+		}
+	},
+	{
+		id: "transfer",
+		text: "The provision, 1,000, was written in the debit column.",
+		kind: "transfer-error",
+		effect: {
+			debit: 1e3,
+			credit: -1e3
+		}
+	}
+];
+const CLASSES = balanceClass.options;
+const perClass = z.object(Object.fromEntries(CLASSES.map((c) => [c, text(200).optional()]))).default({});
+const trialBalanceParamsSchema = z.object({
+	mode: z.enum(["build", "errors"]).default("build").describe("build the trial balance from the balances, or test the finished one against errors"),
+	business: text(60).default("Nadia Traders").describe("the business named at the top"),
+	asAt: text(80).default("as at 31 December 2025").describe("the date line under the title, as printed"),
+	currency: z.string().min(1).max(6).default("$").describe("printed before amounts; Tk groups in lakhs"),
+	accounts: z.array(accountSchema).min(2).max(16).default(DEFAULT_ACCOUNTS).describe("the ledger balances, in the order the trial balance lists them"),
+	difference: z.boolean().default(false).describe("build mode: the balances deliberately do not agree, so the learner meets a difference"),
+	errors: z.array(errorSchema).max(8).default(DEFAULT_ERRORS).describe("errors mode: the errors the learner judges, one at a time"),
+	headings: z.object({
+		title: text(40).default("Trial balance"),
+		serial: text(24).default("Sl. no."),
+		account: text(40).default("Account title"),
+		folio: text(12).default("L.F."),
+		debit: text(24).optional().describe("defaults to \"Debit\" with the currency"),
+		credit: text(24).optional().describe("defaults to \"Credit\" with the currency"),
+		total: text(24).default("Total"),
+		out: text(40).default("Left out")
+	}).default({
+		title: "Trial balance",
+		serial: "Sl. no.",
+		account: "Account title",
+		folio: "L.F.",
+		total: "Total",
+		out: "Left out"
+	}).describe("every heading of the printed trial balance (the lesson passes Bangla)"),
+	phrases: z.object({
+		agree: text(80).default("The totals agree."),
+		differ: text(80).default("The totals differ by"),
+		found: text(160).default("The totals disagree: the trial balance finds this error."),
+		hidden: text(160).default("The totals still agree: the trial balance cannot find this error."),
+		reasons: perClass.describe("the reason a wrong placement shows, per class (defaults read the equation)")
+	}).default({
+		agree: "The totals agree.",
+		differ: "The totals differ by",
+		found: "The totals disagree: the trial balance finds this error.",
+		hidden: "The totals still agree: the trial balance cannot find this error.",
+		reasons: {}
+	}).describe("the sentences the lab writes under the trial balance")
+});
+const TERM_NAME = {
+	assets: "Assets",
+	liabilities: "Liabilities",
+	capital: "Capital",
+	drawings: "Drawings",
+	revenue: "Income",
+	expenses: "Expenses"
+};
+/** Why a class takes its column, read off its place in the equation (stage `placeBalanceClass`). */
+function classReason(cls) {
+	const p = placeBalanceClass(cls);
+	if (p.column === "out") return "This is not a ledger balance on the trial balance date, so it stays out.";
+	const name = TERM_NAME[p.term];
+	if (p.reduces) return `It reduces ${name.toLowerCase()}, which sit left of the equals sign, so its balance is on the other side: credit.`;
+	if (p.position === "left") return `${name} sit left of the equals sign, so an asset has a debit balance.`;
+	if (p.position === "subtracted") return `${name} are subtracted on the right of the equation, so they have a debit balance.`;
+	return `${name} sit right of the equals sign, so ${name.toLowerCase()} have a credit balance.`;
+}
+const COLUMN_LABEL = {
+	debit: "Debit",
+	credit: "Credit",
+	out: "Leave out"
+};
+function firstUnplaced(s, placed, after) {
+	const start = after ? s.rows.findIndex((r) => r.id === after) + 1 : 0;
+	const order = [...s.rows.slice(start), ...s.rows.slice(0, start)];
+	return order.find((r) => placed[r.id] === undefined)?.id ?? s.rows[s.rows.length - 1].id;
+}
+function duplicate(ids) {
+	const seen = new Set();
+	for (const x of ids) {
+		if (seen.has(x)) return x;
+		seen.add(x);
+	}
+	return undefined;
+}
+const trialBalanceModel = defineLabModel({
+	id: "trial-balance",
+	params: trialBalanceParamsSchema,
+	resolve(p) {
+		const twiceAccount = duplicate(p.accounts.map((a) => a.id));
+		if (twiceAccount) return refuse("duplicate-id", `Two accounts share the id "${twiceAccount}".`);
+		const twiceError = duplicate(p.errors.map((e) => e.id));
+		if (twiceError) return refuse("duplicate-id", `Two errors share the id "${twiceError}".`);
+		const prepared = prepareTrialBalance(p.accounts.map((a) => ({
+			id: a.id,
+			balance: a.balance,
+			class: a.class
+		})));
+		const columns = new Set(prepared.lines.map((l) => l.column));
+		if (!columns.has("debit") || !columns.has("credit")) return refuse("column-empty", "A trial balance needs at least one debit balance and one credit balance.");
+		const truth = {
+			debitTotal: prepared.debitTotal,
+			creditTotal: prepared.creditTotal,
+			difference: prepared.difference,
+			agrees: prepared.agrees
+		};
+		const totals = `debit ${prepared.debitTotal}, credit ${prepared.creditTotal}`;
+		if (p.mode === "build" && !p.difference && !truth.agrees) return refuse("totals-disagree", `The balances do not agree (${totals}). Fix them, or set difference to show a trial balance that does not agree.`);
+		if (p.mode === "build" && p.difference && truth.agrees) return refuse("difference-missing", `difference is set, but the balances agree (${totals}).`);
+		if (p.mode === "errors" && !truth.agrees) return refuse("errors-need-agreement", `Errors are judged against a trial balance that agrees; this one has ${totals}.`);
+		if (p.mode === "errors" && p.errors.length === 0) return refuse("errors-missing", "Errors mode needs at least one error.");
+		const errors = [];
+		for (const e of p.mode === "errors" ? p.errors : []) {
+			if (!trialBalanceErrorEffectFits(e.kind, e.effect)) {
+				const finds = diagnoseTrialBalanceError(e.kind).affectsAgreement;
+				return refuse("effect-contradicts-kind", `Error "${e.id}" is a ${e.kind}, which ${finds ? "moves the two totals apart" : "moves both totals together"}; its effect (debit ${e.effect.debit}, credit ${e.effect.credit}) does not.`);
+			}
+			let after;
+			try {
+				after = applyTrialBalanceErrorEffect(truth, e.effect);
+			} catch {
+				return refuse("effect-impossible", `Error "${e.id}" would take a total below zero.`);
+			}
+			errors.push({
+				id: e.id,
+				text: e.text,
+				kind: e.kind,
+				effect: e.effect,
+				verdict: after.agrees ? "agree" : "disagree",
+				after,
+				why: e.why ?? diagnoseTrialBalanceError(e.kind).reason
+			});
+		}
+		const rows = p.accounts.map((a, i) => ({
+			id: a.id,
+			name: a.name,
+			balance: a.balance,
+			class: a.class,
+			column: prepared.lines[i].column,
+			code: a.code,
+			folio: a.folio,
+			why: a.why,
+			reason: p.phrases.reasons[a.class] ?? classReason(a.class)
+		}));
+		const unit = p.currency.trim();
+		return {
+			mode: p.mode,
+			business: p.business,
+			asAt: p.asAt,
+			currency: p.currency,
+			rows,
+			truth,
+			errors,
+			headings: {
+				title: p.headings.title,
+				serial: p.headings.serial,
+				account: p.headings.account,
+				folio: p.headings.folio,
+				debit: p.headings.debit ?? `Debit (${unit})`,
+				credit: p.headings.credit ?? `Credit (${unit})`,
+				total: p.headings.total,
+				out: p.headings.out
+			},
+			phrases: {
+				agree: p.phrases.agree,
+				differ: p.phrases.differ,
+				found: p.phrases.found,
+				hidden: p.phrases.hidden
+			},
+			hasFolio: p.accounts.some((a) => a.folio !== undefined)
+		};
+	},
+	initial: (s) => ({
+		focus: s.rows[0].id,
+		open: s.errors[0]?.id ?? "",
+		placed: s.mode === "errors" ? Object.fromEntries(s.rows.map((r) => [r.id, r.column])) : {},
+		wrong: null,
+		last: null,
+		misses: 0,
+		verdicts: {}
+	}),
+	controls: (c) => ({
+		account: c.choice({
+			label: "Balance in hand",
+			when: (s) => s.mode === "build",
+			options: (s) => s.rows.map((r) => ({
+				value: r.id,
+				label: r.name
+			})),
+			get: (st) => st.focus,
+			set: (st, value, s) => s.rows.some((r) => r.id === value) && st.placed[value] === undefined ? {
+				...st,
+				focus: value,
+				wrong: null
+			} : st
+		}),
+		column: c.choice({
+			unset: true,
+			label: (s, st) => `Column for ${s.rows.find((r) => r.id === st.focus)?.name ?? "this balance"}`,
+			when: (s) => s.mode === "build",
+			options: () => [
+				"debit",
+				"credit",
+				"out"
+			].map((v) => ({
+				value: v,
+				label: COLUMN_LABEL[v]
+			})),
+			get: () => "",
+			set: (st, value, s) => {
+				const row = s.rows.find((r) => r.id === st.focus);
+				if (!row || st.placed[row.id] !== undefined) return st;
+				const column = value;
+				if (column !== row.column) return {
+					...st,
+					wrong: {
+						id: row.id,
+						column
+					},
+					misses: st.misses + 1
+				};
+				const placed = {
+					...st.placed,
+					[row.id]: column
+				};
+				return {
+					...st,
+					placed,
+					wrong: null,
+					last: row.id,
+					focus: firstUnplaced(s, placed, row.id)
+				};
+			}
+		}),
+		error: c.choice({
+			label: "Error",
+			when: (s) => s.mode === "errors",
+			unset: true,
+			options: (s) => s.errors.map((e, i) => ({
+				value: e.id,
+				label: String(i + 1)
+			})),
+			get: (st) => st.open,
+			set: (st, value, s) => s.errors.some((e) => e.id === value) ? {
+				...st,
+				open: value
+			} : st
+		}),
+		verdict: c.choice({
+			unset: true,
+			label: "Your prediction",
+			when: (s) => s.mode === "errors",
+			options: () => [{
+				value: "agree",
+				label: "Totals agree"
+			}, {
+				value: "disagree",
+				label: "Totals disagree"
+			}],
+			get: (st) => st.verdicts[st.open] ?? "",
+			set: (st, value, s) => s.errors.some((e) => e.id === st.open) && st.verdicts[st.open] === undefined ? {
+				...st,
+				verdicts: {
+					...st.verdicts,
+					[st.open]: value
+				}
+			} : st
+		}),
+		next: c.action({
+			label: "Next error",
+			when: (s) => s.mode === "errors",
+			enabled: (s, st) => st.verdicts[st.open] !== undefined && s.errors.some((e) => st.verdicts[e.id] === undefined),
+			run: (s, st) => {
+				const i = s.errors.findIndex((e) => e.id === st.open);
+				const order = [...s.errors.slice(i + 1), ...s.errors.slice(0, i + 1)];
+				const next = order.find((e) => st.verdicts[e.id] === undefined);
+				return next ? {
+					...st,
+					open: next.id
+				} : st;
+			}
+		})
+	}),
+	read(s, st) {
+		const inHand = s.rows.find((r) => r.id === st.focus && st.placed[r.id] === undefined);
+		const landed = s.rows.filter((r) => st.placed[r.id] !== undefined);
+		const live = prepareTrialBalance(landed.map((r) => ({
+			id: r.id,
+			balance: r.balance,
+			class: r.class
+		})));
+		const complete = landed.length === s.rows.length;
+		const wrongRow = st.wrong ? s.rows.find((r) => r.id === st.wrong.id) : undefined;
+		const lastRow = st.last ? s.rows.find((r) => r.id === st.last) : undefined;
+		const error = s.mode === "errors" ? s.errors.find((e) => e.id === st.open) : undefined;
+		const verdict = error ? st.verdicts[error.id] : undefined;
+		const judged = s.errors.filter((e) => st.verdicts[e.id] !== undefined).length;
+		const rightVerdicts = s.errors.filter((e) => st.verdicts[e.id] === e.verdict).length;
+		const shown = error && verdict ? error.after : s.truth;
+		return {
+			mode: s.mode,
+			inHand,
+			placedCount: landed.length,
+			complete,
+			/** Build: the live totals of the rows landed so far. Errors: the totals with the open error in them, once judged. */
+			totals: s.mode === "errors" ? shown : live,
+			wrong: wrongRow ? {
+				row: wrongRow,
+				column: st.wrong.column
+			} : undefined,
+			last: lastRow,
+			misses: st.misses,
+			error,
+			errorIndex: error ? s.errors.indexOf(error) : -1,
+			verdict,
+			verdictRight: error && verdict ? verdict === error.verdict : undefined,
+			judged,
+			rightVerdicts,
+			allJudged: s.errors.length > 0 && judged === s.errors.length
+		};
+	},
+	goals: {
+		built: (r) => r.mode !== "build" || r.complete,
+		errorsJudged: (r) => r.mode !== "errors" || r.allJudged
+	},
+	witness: (s) => ({
+		focus: s.rows[s.rows.length - 1].id,
+		open: s.errors[s.errors.length - 1]?.id ?? "",
+		placed: Object.fromEntries(s.rows.map((r) => [r.id, r.column])),
+		wrong: null,
+		last: null,
+		misses: 0,
+		verdicts: Object.fromEntries(s.errors.map((e) => [e.id, e.verdict]))
+	}),
+	describe: (s, _st, r) => {
+		const money = (v) => formatMoney(v, { currency: s.currency });
+		const totals = `Debit total ${money(r.totals.debitTotal)}, credit total ${money(r.totals.creditTotal)}.`;
+		if (s.mode === "errors") {
+			if (!r.error) return totals;
+			const head = `Error ${r.errorIndex + 1} of ${s.errors.length}: ${r.error.text}`;
+			if (!r.verdict) return `${head} Do the totals still agree?`;
+			return `${head} You said the totals ${r.verdict}. ${totals} ${r.totals.agrees ? s.phrases.hidden : s.phrases.found}`;
+		}
+		const wrong = r.wrong ? ` ${r.wrong.row.name} does not go in ${COLUMN_LABEL[r.wrong.column]}: ${r.wrong.row.why ?? r.wrong.row.reason}` : "";
+		const hand = r.inHand ? ` In hand: ${r.inHand.name}, ${money(r.inHand.balance)}.` : "";
+		const done = r.complete ? ` ${r.totals.agrees ? s.phrases.agree : `${s.phrases.differ} ${money(Math.abs(r.totals.difference))}.`}` : "";
+		return `${r.placedCount} of ${s.rows.length} balances placed. ${totals}${done}${hand}${wrong}`;
+	}
+});
+/** An amount as the trial balance prints it: grouped by the currency, no symbol (the heading names it). */
+function tbAmount(value, currency) {
+	return formatNumber(value, { grouping: groupingFor(currency) });
+}
+
+//#endregion
+export { classReason, tbAmount, trialBalanceModel, trialBalanceParamsSchema };

package/dist/domains/accounting/trial-balance/runtime.mjs

@@ -0,0 +1,24 @@
+'use client';
+
+import { useLab } from "../../../runtime/use-lab.mjs";
+import { AuthoredActivityRuntime } from "../../../kit/authored-activity-runtime.mjs";
+import { trialBalanceModel } from "./model.mjs";
+import { trialBalanceActivity } from "./activity.mjs";
+import { TrialBalanceScene } from "./scene.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/domains/accounting/trial-balance/runtime.tsx
+function TrialBalance(props) {
+	const lab = useLab(trialBalanceModel, props);
+	return /* @__PURE__ */ jsx(AuthoredActivityRuntime, {
+		lab,
+		activity: trialBalanceActivity,
+		layout: "stack",
+		keyControls: [],
+		sceneLabel: "A trial balance built from ledger balances",
+		children: /* @__PURE__ */ jsx(TrialBalanceScene, {})
+	});
+}
+
+//#endregion
+export { TrialBalance as default };