@mohasinac/appkit 4.62.1 → 4.63.1

package/dist/_internal/shared/features/payouts/pay-period.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Pay periods for employee payouts — ONE resolver, two cadences.
+ *
+ * ## 🛑 Why this is a module and not a ternary at each call site
+ *
+ * Two cadences means two period-boundary rules, and a reopened ticket can
+ * straddle a boundary differently per employee: the same reopen is inside the
+ * period for a monthly payee and across it for a weekly one. A branch written
+ * at each call site is two chances per site to disagree about where a week
+ * starts — and the symptom is a payslip that is quietly short, which nobody
+ * reports as a bug because nobody has the other number to compare it to.
+ *
+ * So the period is resolved once, from a date and a cadence, and every caller
+ * takes the pair it returns.
+ *
+ * ## 🛑 Go-forward, no clawback
+ *
+ * A payslip is final once issued. If a ticket is reopened after the period it
+ * was paid in has closed, the money is not recovered and the period is not
+ * recomputed — the ticket simply does not count again in the period where it
+ * is next resolved. Recomputing a closed period would mean an employee's pay
+ * changing after they were told what it was, which is a worse failure than
+ * occasionally paying for work that was later reopened.
+ */
+export type PayCadence = "weekly" | "monthly";
+export declare const PAY_CADENCE_VALUES: readonly ["weekly", "monthly"];
+export interface PayPeriod {
+    start: Date;
+    /** EXCLUSIVE. See the note below — this is the half-open convention. */
+    end: Date;
+    cadence: PayCadence;
+}
+/**
+ * The period containing `when`.
+ *
+ * ## 🛑 Half-open: `start <= t < end`
+ *
+ * An inclusive end means the last millisecond of a period is also the first of
+ * the next, so a ticket resolved exactly at midnight is counted twice — paid
+ * in two periods — or, if one side uses `<` and the other `<=`, in neither.
+ * Half-open makes both impossible by construction, and every consumer must
+ * compare with `< end`, never `<= end`.
+ *
+ * ## 🛑 Weeks start MONDAY
+ *
+ * `Date.getDay()` returns 0 for Sunday, so the naive `d - d.getDay()` produces
+ * a Sunday-start week. India's working week is Monday–Saturday and a support
+ * rota is read that way, so a Sunday boundary would split every weekend across
+ * two payslips. The `(day + 6) % 7` shift is what makes Monday day 0.
+ *
+ * ## 🛑 Local midnight, not UTC
+ *
+ * Wages are a human-calendar concept: an employee's Monday is their Monday.
+ * `setHours(0,0,0,0)` is local, and the server runs in the deployment's zone —
+ * which is why `periodLabel` renders the same boundary a payslip prints.
+ */
+export declare function payPeriodFor(when: Date, cadence: PayCadence): PayPeriod;
+/** The period immediately before the one containing `when`. */
+export declare function previousPayPeriod(when: Date, cadence: PayCadence): PayPeriod;
+/** Half-open membership. The ONLY correct way to ask; see `payPeriodFor`. */
+export declare function isWithinPeriod(t: Date, period: PayPeriod): boolean;
+/**
+ * What a payslip prints.
+ *
+ * 🛑 Renders the end as the LAST DAY INSIDE the period, not the exclusive
+ * boundary. "1 Jan – 1 Feb" on a January payslip reads as an overlap with
+ * February's and invites someone to "fix" the half-open convention that makes
+ * the arithmetic correct.
+ */
+export declare function periodLabel(period: PayPeriod, locale?: string): string;
+/**
+ * The tickets a period actually pays for.
+ *
+ * 🛑 **Tickets STILL RESOLVED at period end — not tickets closed during it.**
+ * Paying per ticket closed rewards closing rather than resolving: close it,
+ * let the buyer reopen it, close it again, and it pays twice. So a ticket
+ * counts only when it is resolved, was resolved inside the period, and is
+ * still resolved when the period ends.
+ *
+ * A reopen therefore removes the ticket from that period even if the reopen
+ * happened after the resolution — which is why this takes the whole ticket
+ * rather than a timestamp, and why `resolvedBy` must be CLEARED on reopen.
+ */
+export interface PayableTicket {
+    id: string;
+    resolvedAt?: Date | null;
+    resolvedBy?: string | null;
+    /** The live status, read at the moment the period is computed. */
+    isResolved: boolean;
+}
+export declare function resolvedTicketsForPeriod(tickets: readonly PayableTicket[], employeeUid: string, period: PayPeriod): string[];

package/dist/_internal/shared/features/payouts/pay-period.js

@@ -0,0 +1,104 @@
+/**
+ * Pay periods for employee payouts — ONE resolver, two cadences.
+ *
+ * ## 🛑 Why this is a module and not a ternary at each call site
+ *
+ * Two cadences means two period-boundary rules, and a reopened ticket can
+ * straddle a boundary differently per employee: the same reopen is inside the
+ * period for a monthly payee and across it for a weekly one. A branch written
+ * at each call site is two chances per site to disagree about where a week
+ * starts — and the symptom is a payslip that is quietly short, which nobody
+ * reports as a bug because nobody has the other number to compare it to.
+ *
+ * So the period is resolved once, from a date and a cadence, and every caller
+ * takes the pair it returns.
+ *
+ * ## 🛑 Go-forward, no clawback
+ *
+ * A payslip is final once issued. If a ticket is reopened after the period it
+ * was paid in has closed, the money is not recovered and the period is not
+ * recomputed — the ticket simply does not count again in the period where it
+ * is next resolved. Recomputing a closed period would mean an employee's pay
+ * changing after they were told what it was, which is a worse failure than
+ * occasionally paying for work that was later reopened.
+ */
+export const PAY_CADENCE_VALUES = ["weekly", "monthly"];
+/** A cadence absent here is a compile error, not a silently unpayable employee. */
+const _CADENCE_COVERS_UNION = { weekly: true, monthly: true };
+void _CADENCE_COVERS_UNION;
+/**
+ * The period containing `when`.
+ *
+ * ## 🛑 Half-open: `start <= t < end`
+ *
+ * An inclusive end means the last millisecond of a period is also the first of
+ * the next, so a ticket resolved exactly at midnight is counted twice — paid
+ * in two periods — or, if one side uses `<` and the other `<=`, in neither.
+ * Half-open makes both impossible by construction, and every consumer must
+ * compare with `< end`, never `<= end`.
+ *
+ * ## 🛑 Weeks start MONDAY
+ *
+ * `Date.getDay()` returns 0 for Sunday, so the naive `d - d.getDay()` produces
+ * a Sunday-start week. India's working week is Monday–Saturday and a support
+ * rota is read that way, so a Sunday boundary would split every weekend across
+ * two payslips. The `(day + 6) % 7` shift is what makes Monday day 0.
+ *
+ * ## 🛑 Local midnight, not UTC
+ *
+ * Wages are a human-calendar concept: an employee's Monday is their Monday.
+ * `setHours(0,0,0,0)` is local, and the server runs in the deployment's zone —
+ * which is why `periodLabel` renders the same boundary a payslip prints.
+ */
+export function payPeriodFor(when, cadence) {
+    const start = new Date(when.getTime());
+    start.setHours(0, 0, 0, 0);
+    if (cadence === "weekly") {
+        const mondayIndex = (start.getDay() + 6) % 7;
+        start.setDate(start.getDate() - mondayIndex);
+        const end = new Date(start.getTime());
+        end.setDate(end.getDate() + 7);
+        return { start, end, cadence };
+    }
+    start.setDate(1);
+    const end = new Date(start.getTime());
+    /*
+     * `setMonth(+1)` on the 1st is safe; it is only unsafe on day 29–31, which
+     * `setDate(1)` above has already removed. Doing it the other way round is
+     * the classic bug — 31 January + 1 month is 3 March.
+     */
+    end.setMonth(end.getMonth() + 1);
+    return { start, end, cadence };
+}
+/** The period immediately before the one containing `when`. */
+export function previousPayPeriod(when, cadence) {
+    const current = payPeriodFor(when, cadence);
+    const justBefore = new Date(current.start.getTime() - 1);
+    return payPeriodFor(justBefore, cadence);
+}
+/** Half-open membership. The ONLY correct way to ask; see `payPeriodFor`. */
+export function isWithinPeriod(t, period) {
+    const ms = t.getTime();
+    return ms >= period.start.getTime() && ms < period.end.getTime();
+}
+/**
+ * What a payslip prints.
+ *
+ * 🛑 Renders the end as the LAST DAY INSIDE the period, not the exclusive
+ * boundary. "1 Jan – 1 Feb" on a January payslip reads as an overlap with
+ * February's and invites someone to "fix" the half-open convention that makes
+ * the arithmetic correct.
+ */
+export function periodLabel(period, locale = "en-IN") {
+    const lastDay = new Date(period.end.getTime() - 1);
+    const fmt = (d) => d.toLocaleDateString(locale, { dateStyle: "medium" });
+    return `${fmt(period.start)} – ${fmt(lastDay)}`;
+}
+export function resolvedTicketsForPeriod(tickets, employeeUid, period) {
+    return tickets
+        .filter((t) => t.isResolved &&
+        t.resolvedBy === employeeUid &&
+        t.resolvedAt != null &&
+        isWithinPeriod(t.resolvedAt, period))
+        .map((t) => t.id);
+}

package/dist/_internal/shared/features/points/accepts.d.ts

@@ -22,14 +22,7 @@
  * discounts they never agreed to. A tri-state would be worse still — a buyer
  * cannot tell a seller who declined from one who has not been asked.
  */
-/**
- * The platform's own storefront.
- *
- * Hard-coded deliberately: this is an identity, not a setting. It is the same
- * id `realListingsOnly` and the seed's `REAL_STORE_IDS` already treat as the
- * platform's own.
- */
-export declare const PLATFORM_STORE_ID = "store-letitrip-official";
+export { PLATFORM_STORE_ID } from "../../../../features/stores/schemas/firestore";
 export declare function storeAcceptsPoints(store: {
     id?: string;
     acceptsPoints?: boolean;

package/dist/_internal/shared/features/points/accepts.js

@@ -22,14 +22,20 @@
  * discounts they never agreed to. A tri-state would be worse still — a buyer
  * cannot tell a seller who declined from one who has not been asked.
  */
-/**
- * The platform's own storefront.
+/*
+ * 🛑 `PLATFORM_STORE_ID` is DECLARED in `features/stores/schemas/firestore.ts`
+ * and re-exported here, not defined here.
  *
- * Hard-coded deliberately: this is an identity, not a setting. It is the same
- * id `realListingsOnly` and the seed's `REAL_STORE_IDS` already treat as the
- * platform's own.
+ * It is still an identity rather than a setting — that reasoning is unchanged
+ * and is recorded at the declaration. What moved, and why: a brand-bearing
+ * literal inside `_internal/` is what `audit-ssr-in-appkit` Rule 3 blocks,
+ * because a consumer of appkit would inherit OUR store id with no seam to
+ * override it. The stores schema is also where the matching `acceptsPoints`
+ * docstring already explains the always-accepts rule, so the constant and its
+ * justification now sit together.
  */
-export const PLATFORM_STORE_ID = "store-letitrip-official";
+export { PLATFORM_STORE_ID } from "../../../../features/stores/schemas/firestore.js";
+import { PLATFORM_STORE_ID } from "../../../../features/stores/schemas/firestore.js";
 export function storeAcceptsPoints(store, storeId) {
     /*
      * The id is taken from either source so a caller holding only an id (the

package/dist/_internal/shared/features/pricing/rate-registry.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The pricing registry — every rate the platform charges, in one place, with
+ * its tier and who may change it.
+ *
+ * ## Why this exists
+ *
+ * Before it, a rate was a field on `siteSettings` and nothing said what KIND
+ * of thing it was. A GST percentage, a policy ceiling the owner sets, and an
+ * operational commission a back-office agent tunes all looked identical in the
+ * schema and in the admin form — so the only thing standing between an agent
+ * and editing a statutory tax rate was that nobody had tried.
+ *
+ * It is also the destination `audit-money-paths`' R6 needs. That rule is
+ * specified as "a percentage or fee literal in logic, not in the pricing
+ * registry", and was deliberately NOT implemented in 9a because the registry
+ * did not exist: a rule whose remedy is "move it somewhere that isn't there"
+ * can only produce noise.
+ *
+ * ## 🛑 Three tiers, and the top one is NOT editable here at all
+ *
+ * | Tier | Who | Why |
+ * |---|---|---|
+ * | `statutory` | **nobody** | A GST rate is not ours to choose. It is read from `/admin/tax-codes`, which is sourced per HSN, and a writable copy here would be a second place for a filed tax figure to disagree with itself |
+ * | `policy` | admin only, reason required | A ceiling the owner decides — `platformFeeMax`, the OTP threshold, `minPayoutAmount`. Changing one changes what the business promises, not what it charges today |
+ * | `operational` | back-office | Commission, COD handling, the add-on fees. Tuned, audited, and reversible |
+ *
+ * ## 🛑 EVERY CHANGE IS FORWARD-ONLY. This is the load-bearing rule.
+ *
+ * A rate answers *"what do we charge from now on"* and never *"what did we
+ * charge"*. Historical paths read the record's own snapshot — `order.gst`,
+ * `order.platformFee`, `appliedDiscounts` — which is why those fields are
+ * snapshotted at all, and `audit-money-paths`' R7 blocks a live read in a
+ * payout, invoice or GSTR-1 path.
+ *
+ * Without that, lowering a commission would silently restate every historical
+ * payout, and an invoice reprinted after a GST change would state a tax that
+ * was never charged. **Invoices are FILED.** The failure is not a wrong screen;
+ * it is a wrong return.
+ *
+ * ## 🛑 A rate appearing here does NOT make it public
+ *
+ * `gatewayFeePercent`, `payoutHoldDays`, `minPayoutAmount` and
+ * `surchargeSellerSharePercent` are seller-side economics and stay in
+ * `PRIVATE_*_FIELDS` (Root Cause #70 — a deny-list projection once shipped all
+ * 25 commission fields to anonymous callers). This registry describes an ADMIN
+ * surface. Buyer-facing display goes through `toBuyerFacingFees()` /
+ * `toBuyerEmiSettings()`, and `audit-guest-price-leak`'s R6 blocks a seller
+ * rate reaching a buyer path.
+ */
+/** Who may change a rate, and what the change costs in ceremony. */
+export type RateTier = "statutory" | "policy" | "operational";
+/**
+ * Render order: most constrained first.
+ *
+ * 🛑 A runtime array with the type DERIVED from it would be the usual pattern
+ * here, but it is inverted on purpose — `RateTier` is the union the registry
+ * and `canEditRate` switch on, and this array is only a presentation order.
+ * Typing it `readonly RateTier[]` makes a missing tier a silent omission from
+ * the page rather than a compile error, so it is `Record`-checked below.
+ */
+export declare const RATE_TIER_ORDER: readonly ["statutory", "policy", "operational"];
+/** How to read and render the number. */
+export type RateUnit = "percent" | "rupees" | "days" | "minutes" | "count";
+export interface RateDescriptor {
+    /**
+     * Dotted path inside `siteSettings`, e.g. `commissions.platformFeePercent`.
+     *
+     * 🛑 The path IS the identity. A registry keyed on a prettier id would be a
+     * second name for one field, and the two would drift the first time a field
+     * moved — the mirror problem (Root Cause #42) applied to money.
+     */
+    path: string;
+    label: string;
+    /** What this rate actually does, in the operator's words rather than the field's. */
+    description: string;
+    tier: RateTier;
+    unit: RateUnit;
+    /**
+     * `true` when the value is seller-side economics.
+     *
+     * Not a display hint — it is what keeps `audit-guest-price-leak` honest
+     * about which rates may never reach a buyer-facing path.
+     */
+    sellerOnly?: boolean;
+}
+/**
+ * Every rate, in the order an operator would look for them.
+ *
+ * 🛑 **Statutory rates are deliberately ABSENT rather than listed read-only.**
+ *
+ * The first draft included GST as `tier: "statutory", editable: false`, and
+ * that is the worse design: a read-only row on this page is a SECOND place GST
+ * appears, and the day the two disagree the page is the one an operator
+ * believes. `/admin/tax-codes` owns per-HSN rates, sourced and effective-dated
+ * already. This page links there instead of mirroring it.
+ *
+ * The tier remains in the union because the DISTINCTION is what the page has
+ * to teach — and because a future statutory value that genuinely has no other
+ * home needs somewhere honest to go.
+ */
+export declare const RATE_REGISTRY: readonly RateDescriptor[];
+/** Lookup by path. `undefined` for a field nobody registered. */
+export declare function rateByPath(path: string): RateDescriptor | undefined;
+/**
+ * Who may change this rate.
+ *
+ * 🛑 `statutory` returns `false` for EVERYONE, admins included. That is not a
+ * permission check that happens to exclude admins — it is the statement that
+ * this value is not ours to choose. An admin who needs a different GST rate
+ * needs a different HSN code, which is a different screen and a different
+ * kind of decision.
+ */
+export declare function canEditRate(tier: RateTier, isAdmin: boolean): boolean;
+/**
+ * One recorded rate change. Appended, never overwritten.
+ *
+ * ## 🛑 `effectiveFrom` is forward-only and the WRITE must enforce it
+ *
+ * A backdated rate is indistinguishable from a correction in the data and
+ * catastrophic in effect: every historical read that honours effective dates
+ * would restate figures already invoiced and already paid out. The field exists
+ * so a change can be SCHEDULED, not so history can be edited.
+ *
+ * `reason` is required on a `policy` change and optional otherwise, which is
+ * the whole difference in ceremony between the two tiers.
+ */
+export interface RateChange {
+    path: string;
+    previousValue: number | null;
+    newValue: number;
+    /** Never earlier than the moment of the write. */
+    effectiveFrom: Date;
+    changedByUid: string;
+    changedByName: string;
+    reason?: string;
+    changedAt: Date;
+}
+/**
+ * Is this `effectiveFrom` acceptable?
+ *
+ * Returns a MESSAGE rather than a boolean so the caller can say which rule was
+ * broken — "that date is in the past" and "nothing to change" are different
+ * corrections, and a bare `false` makes the form guess.
+ */
+export declare function rejectRateChange(input: {
+    effectiveFrom: Date;
+    previousValue: number | null;
+    newValue: number;
+    reason?: string;
+}, tier: RateTier, now: Date): string | null;

package/dist/_internal/shared/features/pricing/rate-registry.js

@@ -0,0 +1,246 @@
+/**
+ * The pricing registry — every rate the platform charges, in one place, with
+ * its tier and who may change it.
+ *
+ * ## Why this exists
+ *
+ * Before it, a rate was a field on `siteSettings` and nothing said what KIND
+ * of thing it was. A GST percentage, a policy ceiling the owner sets, and an
+ * operational commission a back-office agent tunes all looked identical in the
+ * schema and in the admin form — so the only thing standing between an agent
+ * and editing a statutory tax rate was that nobody had tried.
+ *
+ * It is also the destination `audit-money-paths`' R6 needs. That rule is
+ * specified as "a percentage or fee literal in logic, not in the pricing
+ * registry", and was deliberately NOT implemented in 9a because the registry
+ * did not exist: a rule whose remedy is "move it somewhere that isn't there"
+ * can only produce noise.
+ *
+ * ## 🛑 Three tiers, and the top one is NOT editable here at all
+ *
+ * | Tier | Who | Why |
+ * |---|---|---|
+ * | `statutory` | **nobody** | A GST rate is not ours to choose. It is read from `/admin/tax-codes`, which is sourced per HSN, and a writable copy here would be a second place for a filed tax figure to disagree with itself |
+ * | `policy` | admin only, reason required | A ceiling the owner decides — `platformFeeMax`, the OTP threshold, `minPayoutAmount`. Changing one changes what the business promises, not what it charges today |
+ * | `operational` | back-office | Commission, COD handling, the add-on fees. Tuned, audited, and reversible |
+ *
+ * ## 🛑 EVERY CHANGE IS FORWARD-ONLY. This is the load-bearing rule.
+ *
+ * A rate answers *"what do we charge from now on"* and never *"what did we
+ * charge"*. Historical paths read the record's own snapshot — `order.gst`,
+ * `order.platformFee`, `appliedDiscounts` — which is why those fields are
+ * snapshotted at all, and `audit-money-paths`' R7 blocks a live read in a
+ * payout, invoice or GSTR-1 path.
+ *
+ * Without that, lowering a commission would silently restate every historical
+ * payout, and an invoice reprinted after a GST change would state a tax that
+ * was never charged. **Invoices are FILED.** The failure is not a wrong screen;
+ * it is a wrong return.
+ *
+ * ## 🛑 A rate appearing here does NOT make it public
+ *
+ * `gatewayFeePercent`, `payoutHoldDays`, `minPayoutAmount` and
+ * `surchargeSellerSharePercent` are seller-side economics and stay in
+ * `PRIVATE_*_FIELDS` (Root Cause #70 — a deny-list projection once shipped all
+ * 25 commission fields to anonymous callers). This registry describes an ADMIN
+ * surface. Buyer-facing display goes through `toBuyerFacingFees()` /
+ * `toBuyerEmiSettings()`, and `audit-guest-price-leak`'s R6 blocks a seller
+ * rate reaching a buyer path.
+ */
+/**
+ * Render order: most constrained first.
+ *
+ * 🛑 A runtime array with the type DERIVED from it would be the usual pattern
+ * here, but it is inverted on purpose — `RateTier` is the union the registry
+ * and `canEditRate` switch on, and this array is only a presentation order.
+ * Typing it `readonly RateTier[]` makes a missing tier a silent omission from
+ * the page rather than a compile error, so it is `Record`-checked below.
+ */
+export const RATE_TIER_ORDER = ["statutory", "policy", "operational"];
+/** A tier absent from `RATE_TIER_ORDER` is a compile error, not a missing section. */
+const _TIER_ORDER_COVERS_UNION = {
+    statutory: true,
+    policy: true,
+    operational: true,
+};
+void _TIER_ORDER_COVERS_UNION;
+/**
+ * Every rate, in the order an operator would look for them.
+ *
+ * 🛑 **Statutory rates are deliberately ABSENT rather than listed read-only.**
+ *
+ * The first draft included GST as `tier: "statutory", editable: false`, and
+ * that is the worse design: a read-only row on this page is a SECOND place GST
+ * appears, and the day the two disagree the page is the one an operator
+ * believes. `/admin/tax-codes` owns per-HSN rates, sourced and effective-dated
+ * already. This page links there instead of mirroring it.
+ *
+ * The tier remains in the union because the DISTINCTION is what the page has
+ * to teach — and because a future statutory value that genuinely has no other
+ * home needs somewhere honest to go.
+ */
+export const RATE_REGISTRY = [
+    // ── Policy ceilings: the owner's decisions ──────────────────────────────
+    {
+        path: "commissions.platformFeeMax",
+        label: "Platform fee cap",
+        description: "The most we take from one checkout, before GST on it. Applied before the tax, because GST is levied on the commission actually charged.",
+        tier: "policy",
+        unit: "rupees",
+    },
+    {
+        path: "payment.otpCheckoutThreshold",
+        label: "OTP threshold",
+        description: "Order value above which a buyer must confirm by one-time code. Measured on the WHOLE checkout, not each resulting per-seller order — otherwise a big cart dodges it by spanning sellers.",
+        tier: "policy",
+        unit: "rupees",
+    },
+    {
+        path: "payment.codMaxOrderValue",
+        label: "COD ceiling",
+        description: "The largest order we will hand over against cash on delivery.",
+        tier: "policy",
+        unit: "rupees",
+    },
+    {
+        path: "commissions.minPayoutAmount",
+        label: "Minimum payout",
+        description: "A seller's balance must reach this before a payout runs.",
+        tier: "policy",
+        unit: "rupees",
+        sellerOnly: true,
+    },
+    {
+        path: "commissions.payoutHoldDays",
+        label: "Payout hold",
+        description: "How long a seller's money waits after delivery, so a dispute can still be raised against it.",
+        tier: "policy",
+        unit: "days",
+        sellerOnly: true,
+    },
+    // ── Operational: tuned, audited, reversible ─────────────────────────────
+    {
+        path: "commissions.platformFeePercent",
+        label: "Platform commission",
+        description: "Our cut of a checkout, before the cap above is applied.",
+        tier: "operational",
+        unit: "percent",
+    },
+    {
+        path: "commissions.minimumTransactionFee",
+        label: "Minimum transaction fee",
+        description: "The floor under the commission, so a very small order still covers its own cost.",
+        tier: "operational",
+        unit: "rupees",
+    },
+    {
+        path: "commissions.gatewayFeePercent",
+        label: "Gateway fee",
+        description: "What the payment provider takes. Recorded so a payout can account for it.",
+        tier: "operational",
+        unit: "percent",
+        sellerOnly: true,
+    },
+    {
+        path: "commissions.codHandlingFeePercent",
+        label: "COD handling fee",
+        description: "Charged to the buyer for paying cash on delivery.",
+        tier: "operational",
+        unit: "percent",
+    },
+    {
+        path: "commissions.codHandlingFeeCap",
+        label: "COD handling cap",
+        description: "The most the COD handling fee can reach on one order.",
+        tier: "operational",
+        unit: "rupees",
+    },
+    {
+        path: "commissions.codDepositPercent",
+        label: "COD token",
+        description: "Paid up front on a cash-on-delivery order; the rest is collected at the door.",
+        tier: "operational",
+        unit: "percent",
+    },
+    {
+        path: "commissions.giftWrapFee",
+        label: "Gift wrap",
+        description: "Per-store add-on. Charged once per seller in the cart, never once per cart.",
+        tier: "operational",
+        unit: "rupees",
+    },
+    {
+        path: "commissions.shipmentProtectionFeePercent",
+        label: "Shipment protection",
+        description: "Transit cover, charged per store. Claimable within 48 hours of delivery.",
+        tier: "operational",
+        unit: "percent",
+    },
+    {
+        path: "commissions.shipmentProtectionFeeMin",
+        label: "Shipment protection floor",
+        description: "The minimum transit-cover premium on any one order.",
+        tier: "operational",
+        unit: "rupees",
+    },
+    {
+        path: "commissions.saleProtectionFeePercent",
+        label: "Sale protection",
+        description: "Cover against the sale itself going wrong. A different window from transit cover.",
+        tier: "operational",
+        unit: "percent",
+    },
+    {
+        path: "commissions.saleProtectionFeeMin",
+        label: "Sale protection floor",
+        description: "The minimum sale-cover premium on any one order.",
+        tier: "operational",
+        unit: "rupees",
+    },
+];
+/** Lookup by path. `undefined` for a field nobody registered. */
+export function rateByPath(path) {
+    return RATE_REGISTRY.find((r) => r.path === path);
+}
+/**
+ * Who may change this rate.
+ *
+ * 🛑 `statutory` returns `false` for EVERYONE, admins included. That is not a
+ * permission check that happens to exclude admins — it is the statement that
+ * this value is not ours to choose. An admin who needs a different GST rate
+ * needs a different HSN code, which is a different screen and a different
+ * kind of decision.
+ */
+export function canEditRate(tier, isAdmin) {
+    if (tier === "statutory")
+        return false;
+    if (tier === "policy")
+        return isAdmin;
+    return true;
+}
+/**
+ * Is this `effectiveFrom` acceptable?
+ *
+ * Returns a MESSAGE rather than a boolean so the caller can say which rule was
+ * broken — "that date is in the past" and "nothing to change" are different
+ * corrections, and a bare `false` makes the form guess.
+ */
+export function rejectRateChange(input, tier, now) {
+    if (!Number.isFinite(input.newValue))
+        return "That is not a number.";
+    if (input.newValue < 0)
+        return "A rate cannot be negative.";
+    if (input.previousValue === input.newValue)
+        return "That is already the current value.";
+    /*
+     * A minute of slack, because a form submitted at 14:59:59 against a server
+     * clock at 15:00:00 is not an attempt to backdate anything.
+     */
+    if (input.effectiveFrom.getTime() < now.getTime() - 60000) {
+        return "A rate change cannot be backdated — it would restate invoices already filed.";
+    }
+    if (tier === "policy" && !input.reason?.trim()) {
+        return "A policy ceiling needs a reason.";
+    }
+    return null;
+}