@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/contracts/payment.d.ts

@@ -17,6 +17,40 @@ export interface PaymentOrder {
     /** When this order/attempt expires, if the gateway reports one (PhonePe's `expireAt`). ISO-8601. */
     expiresAt?: string;
 }
+/**
+ * What the buyer was checking out, round-tripped through the gateway's own
+ * metadata so the confirmation path can rebuild the order.
+ *
+ * 🛑 This lived in `providers/payment-phonepe/index.ts` as
+ * `PhonePeCheckoutIntent`, and the name was the only gateway-shaped thing about
+ * it — every field is OURS. That naming forced generic checkout code to import
+ * a concrete provider for a type, which is the coupling Tier AK A4 exists to
+ * remove. PhonePe happens to carry it in `udf1..udf4`; another gateway would
+ * carry it some other way, and neither fact belongs in the type's name.
+ */
+export interface CheckoutIntentMetadata {
+    uid: string;
+    addressId?: string;
+    outOfStockPolicy?: string;
+    notes?: string;
+    /**
+     * Item 1.39 — the `buyerPolicyConsents` document id for the agreement taken
+     * at create-order time, BEFORE this capture was requested.
+     *
+     * 🛑 An ID, never the agreement itself. This map is flattened into the
+     * gateway's merchant passthrough channel (`notes` / `metaInfo` /
+     * `order_tags`) with a 10-key, 255-char cap and SILENT truncation — the same
+     * constraint that keeps split amounts out of here. Verbatim clause text
+     * would be truncated without an error and the order would carry a half
+     * sentence as its consent record.
+     *
+     * 🛑 Untrusted on the way back. `loadBuyerPolicyConsent` re-checks that the
+     * record belongs to the uid the order is being placed for, because a crafted
+     * passthrough could otherwise attach someone else's agreement to this
+     * purchase.
+     */
+    policyConsentId?: string;
+}
 export interface PaymentCapture {
     id: string;
     orderId: string;
@@ -132,6 +166,120 @@ export interface GatewayPaymentRecord {
     capturedAt?: Date;
     gateway: string;
 }
+/**
+ * A seller as a SPLITTING gateway needs to know them, normalised at the
+ * provider boundary.
+ *
+ * ## Why a split and not a payout
+ *
+ * A marketplace cannot be a payment aggregator and cannot commingle buyer
+ * funds with its own: RBI bars it, and no bank opens a nodal account for an
+ * unlicensed platform. So the lawful shape is buyer → aggregator escrow →
+ * seller, with the platform never holding the seller's share. For an
+ * aggregator to send a seller their share it must know them as a VENDOR, which
+ * means a registration call and an id it hands back — hence this type.
+ *
+ * 🛑 Every string here is PLAINTEXT at the moment of the call. `pan` and the
+ * bank/UPI details are ciphertext at rest and arrive through the named reveal
+ * accessors (`storeRepository.revealPan`, `userRepository.revealUser`). They
+ * must never be logged, never echoed into an error message, and never written
+ * back anywhere — the caller holds them for the duration of one HTTP request.
+ *
+ * 🛑 EXACTLY ONE destination, never both. A vendor with a bank account and a
+ * VPA is a vendor whose money could go to either, decided by whichever branch
+ * an aggregator happens to prefer — which is a silent choice about where real
+ * money lands. The seller picked one (`SellerPayoutDetails.method`); the
+ * adapter is handed that one.
+ */
+export interface SettlementVendorInput {
+    /**
+     * OUR id for this vendor, and what the gateway will know them by.
+     *
+     * 🛑 Always the `storeSlug`, supplied by us rather than generated by the
+     * gateway. That makes registration idempotent with no lookup, and it makes a
+     * split instruction buildable from a cart line's `storeId` with no extra
+     * read.
+     */
+    vendorId: string;
+    /** The store's own name — what the aggregator's dashboard will show. */
+    name: string;
+    /** PLAINTEXT. Revealed from the owner's user document. */
+    email: string;
+    /** PLAINTEXT. Revealed from the owner's user document. */
+    phone: string;
+    /**
+     * PLAINTEXT PAN. Absent for a seller who has not supplied one, which is a
+     * real state rather than an error — most aggregators require it for most
+     * entity types, so an absent PAN usually means the registration will be
+     * refused, and the refusal is the gateway's to make.
+     */
+    pan?: string;
+    /** The seller's own GSTIN, when they have one. Optional by design — blocker #5. */
+    gstin?: string;
+    /** Bank destination. Mutually exclusive with `upi`. */
+    bank?: {
+        /** PLAINTEXT, full account number. */
+        accountNumber: string;
+        ifsc: string;
+        accountHolderName: string;
+    };
+    /** UPI destination. Mutually exclusive with `bank`. */
+    upi?: {
+        /** PLAINTEXT VPA. */
+        vpa: string;
+        accountHolderName: string;
+    };
+}
+/**
+ * What a gateway said about a vendor.
+ *
+ * 🛑 THREE outcomes, and `pending` is not a failure. An aggregator may accept
+ * the registration and then run its own account verification asynchronously,
+ * so "we have them, we are checking" is a distinct and common answer.
+ * Collapsing it into `active` would let a split instruction be built against a
+ * vendor the gateway has not finished approving; collapsing it into `rejected`
+ * would send an operator to chase a refusal that never happened.
+ */
+export type SettlementVendorOutcome = "active" | "pending" | "rejected";
+export interface SettlementVendorResult {
+    /** The adapter that answered, so a mixed-gateway record stays attributable. */
+    gateway: string;
+    /** Echoed back, so the caller writes the id the gateway actually keyed on. */
+    vendorId: string;
+    outcome: SettlementVendorOutcome;
+    /**
+     * The gateway's own sentence, verbatim.
+     *
+     * 🛑 REQUIRED in practice for anything but `active`: a seller who cannot be
+     * paid, with no stated reason, is the failure this field exists to prevent.
+     * It is shown to the seller and the admin, so it must describe the
+     * DESTINATION (which the seller supplied) and never carry a credential.
+     */
+    message?: string;
+}
+/**
+ * One vendor's share of ONE capture.
+ *
+ * `amount` matches `createOrder`'s own `amount` exactly — whatever unit that
+ * carries, this carries, and the conversion to whatever the gateway wants
+ * happens at the adapter boundary, in one place. Stated as a relationship
+ * rather than as a unit name on purpose: tying the two together cannot drift,
+ * whereas naming a unit here would be a second claim about money that could
+ * disagree with `createOrder` silently.
+ *
+ * 🛑 A split instruction in the wrong unit is indistinguishable from a correct
+ * one until a seller is paid 100× too much — there is no type that separates
+ * them and no runtime check that could, so the only defence is that exactly
+ * one place converts.
+ */
+export interface SplitInstruction {
+    /** The gateway's vendor id — i.e. our `storeSlug`. */
+    vendorId: string;
+    /** For logs and reconciliation. Never sent as money. */
+    storeId: string;
+    /** Smallest currency unit. */
+    amount: number;
+}
 /**
  * Payment gateway adapter contract. An abstract base class rather than a
  * plain interface so every provider (manual, PhonePe, and any future
@@ -143,12 +291,97 @@ export interface GatewayPaymentRecord {
 export declare abstract class IPaymentProvider {
     /** Short discriminator used by admin dev tooling to confirm which provider is registered. */
     abstract readonly name: string;
+    /**
+     * Listing types this gateway's own merchant terms permit, where the default
+     * is that they do NOT.
+     *
+     * 🛑 FAIL-CLOSED, and that direction is the whole point. Razorpay and
+     * PhonePe both name *"Bidding/Auction houses"* in their prohibited-merchant
+     * lists; Cashfree's published terms do not. The penalty for getting it wrong
+     * is not a declined transaction — it is the merchant account frozen with the
+     * settlement balance held, which takes down payments for EVERY listing type,
+     * not just the offending one. So a gateway is assumed to prohibit a
+     * restricted type until it says otherwise, and a new adapter that forgets to
+     * declare this is safe by omission rather than dangerous by omission.
+     *
+     * 🛑 Declared HERE, on the provider, rather than tested by name at the gate.
+     * `activeGateway === "cashfree"` would restate the compliance rule at every
+     * call site and go quietly wrong the day a second permitted gateway is
+     * added — the ten-hand-written-enumerations shape of Root Cause #61. The
+     * gateway is the thing that knows what its contract allows, so it is the
+     * thing that declares it.
+     *
+     * 🛑 This is NOT the same question as `supportsSplit` in the consumer's
+     * gateway registry, and the two must not be collapsed. Razorpay Route splits
+     * perfectly well AND prohibits auctions; Cashfree happens to do both. One is
+     * a capability, the other is a permission.
+     *
+     * Empty for every provider that has not been checked against its terms.
+     */
+    readonly acceptsRestrictedListingTypes: readonly string[];
     abstract createOrder(amount: number, currency: string, metadata?: Record<string, JsonValue>): Promise<PaymentOrder>;
     /** Returns true if the webhook signature is valid. */
     abstract verifyWebhook(payload: string, signature: string): boolean;
+    /**
+     * Verify the BUYER-PRESENT checkout callback — a different exchange from a
+     * webhook, which is why `verifyWebhook` cannot serve it.
+     *
+     * A webhook is server-to-server and signed over a raw body. This is the
+     * redirect/callback the buyer's own browser hands back after paying
+     * (Razorpay's `razorpay_order_id` + `razorpay_payment_id` +
+     * `razorpay_signature`). Until this existed, generic checkout code imported
+     * Razorpay's verifier directly — a concrete gateway named in the one place
+     * that must work for every gateway.
+     *
+     * 🛑 MUST FAIL CLOSED. A gateway with no such handshake returns `false`, not
+     * `true`: this call is what decides whether a payment is genuine, so the
+     * default for "I cannot verify this" is rejection. Returning `true` would
+     * accept a forged callback.
+     *
+     * 🛑 The SECRET stays the caller's to resolve, deliberately. The call site
+     * already reads it from settings and fails closed when absent; moving that
+     * inside would change which code holds the key and what happens when it is
+     * missing, which is a bigger change than the dispatch this method is for.
+     *
+     * @param payload the gateway's callback fields, shape-checked by the provider
+     * @param secret  the key secret, resolved by the caller
+     */
+    abstract verifyCheckoutSignature(payload: Record<string, string>, secret: string): boolean;
     abstract capturePayment(orderId: string): Promise<PaymentCapture>;
     abstract refund(paymentId: string, amount?: number): Promise<Refund>;
     abstract getOrder(orderId: string): Promise<PaymentOrder>;
+    /**
+     * Register a seller as a vendor this gateway can settle money to.
+     *
+     * 🛑 Idempotent by contract. The caller passes a `vendorId` it can always
+     * recompute (the store slug), so a re-run must be safe — an adapter that
+     * creates a second vendor on a repeat call is wrong, and the registration job
+     * WILL re-run (jobs retry, and an admin can re-approve a store).
+     *
+     * 🛑 THROWS rather than returning `rejected` when the adapter has no
+     * implementation, and the distinction is load-bearing: `rejected` is a
+     * statement about the SELLER that an operator would act on by contacting
+     * them, while this is a statement about our own configuration. Reporting a
+     * missing implementation as a seller refusal would send a human to chase the
+     * wrong party.
+     */
+    registerSettlementVendor(input: SettlementVendorInput): Promise<SettlementVendorResult>;
+    /**
+     * Create an order, splitting the capture across vendors.
+     *
+     * 🛑 **CALL THIS, NOT `createOrder`, FROM THE CHECKOUT PATH** — always, even
+     * when `splits` is empty. One call site that cannot forget is what makes the
+     * refusal below reachable; a caller that chooses between two methods is a
+     * caller that will one day choose `createOrder` for a multi-vendor cart and
+     * collect the lot into the platform's own account.
+     *
+     * The base implementation refuses a NON-EMPTY list and otherwise delegates,
+     * so a single-vendor cart behaves exactly as it does today on every gateway.
+     *
+     * 🛑 `amount` and every `splits[].amount` are in the SMALLEST CURRENCY UNIT.
+     * The adapter converts, in one place, in both directions.
+     */
+    createOrderWithSplit(amount: number, currency: string, metadata?: Record<string, JsonValue>, splits?: readonly SplitInstruction[]): Promise<PaymentOrder>;
     /**
      * Every payment the gateway recorded in a window — the reconciliation feed.
      *
@@ -185,3 +418,50 @@ export declare abstract class IPaymentProvider {
      */
     abstract acceptDispute(disputeId: string, confirmIrrevocable: true): Promise<Dispute>;
 }
+/**
+ * One online gateway an admin has switched on, paired with the capability the
+ * per-cart resolver needs and the adapter cannot state.
+ *
+ * ## Why the registry grew a LIST beside its single `payment`
+ *
+ * `payment` is resolved ONCE per process from the site-settings flags, and
+ * that is correct for almost everything — a refund, a reconciliation sweep and
+ * a webhook all talk to whichever gateway is live. It cannot express "this
+ * cart needs a splitting gateway and that one doesn't", because the cart does
+ * not exist at module load. So the per-cart resolver needs every ENABLED
+ * gateway, not just the one that won the tie-break; with only the winner
+ * visible, an admin who had enabled both PhonePe and Cashfree would see every
+ * multi-vendor cart refused, because PhonePe sorts first.
+ *
+ * `payment` keeps its meaning and every existing caller keeps its behaviour.
+ * This is additive and optional.
+ *
+ * 🛑 `supportsSplit` lives HERE and not on `IPaymentProvider`, and that
+ * division is deliberate — see `acceptsRestrictedListingTypes`' own 🛑. Whether
+ * split settlement is available is a fact about the PRODUCT the business
+ * bought (Easy Split is a separately-onboarded Cashfree product, not an
+ * inherent property of the Cashfree API), so the consumer's own gateway
+ * registry is what knows it. Whether a listing type is permitted is a fact
+ * about the adapter's merchant TERMS, so the provider declares that. Razorpay
+ * Route splits perfectly well and prohibits auctions; collapsing the two
+ * fields would make one of those two gateways unrepresentable.
+ */
+export interface RegisteredPaymentGateway {
+    /** The adapter itself — this is what actually creates the order. */
+    provider: IPaymentProvider;
+    /**
+     * Can this gateway split ONE capture across several vendors, so the platform
+     * never holds the vendor's share?
+     *
+     * 🛑 `false` is the safe answer and must stay the default for anything not
+     * explicitly known to split. A wrong `true` collects a vendor's money into
+     * the platform's own account, which is the RBI commingling this field exists
+     * to prevent, and it presents as a completely successful checkout.
+     */
+    supportsSplit: boolean;
+    /**
+     * Tie-break when several gateways qualify for the same cart. Lower wins,
+     * matching the consumer registry's own `order`.
+     */
+    order: number;
+}

package/dist/contracts/payment.js

@@ -9,4 +9,129 @@
  * Implemented by the manual provider (default) and PhonePe.
  */
 export class IPaymentProvider {
+    constructor() {
+        /**
+         * Listing types this gateway's own merchant terms permit, where the default
+         * is that they do NOT.
+         *
+         * 🛑 FAIL-CLOSED, and that direction is the whole point. Razorpay and
+         * PhonePe both name *"Bidding/Auction houses"* in their prohibited-merchant
+         * lists; Cashfree's published terms do not. The penalty for getting it wrong
+         * is not a declined transaction — it is the merchant account frozen with the
+         * settlement balance held, which takes down payments for EVERY listing type,
+         * not just the offending one. So a gateway is assumed to prohibit a
+         * restricted type until it says otherwise, and a new adapter that forgets to
+         * declare this is safe by omission rather than dangerous by omission.
+         *
+         * 🛑 Declared HERE, on the provider, rather than tested by name at the gate.
+         * `activeGateway === "cashfree"` would restate the compliance rule at every
+         * call site and go quietly wrong the day a second permitted gateway is
+         * added — the ten-hand-written-enumerations shape of Root Cause #61. The
+         * gateway is the thing that knows what its contract allows, so it is the
+         * thing that declares it.
+         *
+         * 🛑 This is NOT the same question as `supportsSplit` in the consumer's
+         * gateway registry, and the two must not be collapsed. Razorpay Route splits
+         * perfectly well AND prohibits auctions; Cashfree happens to do both. One is
+         * a capability, the other is a permission.
+         *
+         * Empty for every provider that has not been checked against its terms.
+         */
+        this.acceptsRestrictedListingTypes = [];
+        /*
+         * 🛑 THERE IS NO `contestDispute` AND NO `submitEvidence`, AND THAT ABSENCE
+         * IS THE RULE — not an unimplemented stub.
+         *
+         * The Razorpay SDK has `disputes.contest(id, { shipping_proof, billing_proof,
+         * explanation_letter, … })`, verified present in the installed 2.9.8. We
+         * deliberately do not expose it.
+         *
+         * Submitting evidence is irreversible, it is judged by a third party, and it
+         * is the one decision a human must make while looking at the actual
+         * documents. Putting it on this contract would make it callable from a
+         * route, and from there from a bulk action.
+         *
+         * The correct surface is Razorpay's own dashboard. Reinforced three ways:
+         * nothing on this contract can call it, `acceptDispute` demands an explicit
+         * confirmation, and the ingest handler is READS ONLY. A later session wanting
+         * to "finish the dispute feature" should read this paragraph first — the
+         * feature is finished; this is the shape.
+         */
+    }
+    /*
+     * ── SPLIT SETTLEMENT ──────────────────────────────────────────────────────
+     *
+     * Both members below are CONCRETE and both REFUSE, which is the opposite of
+     * how the dispute members above are declared — and the asymmetry is the
+     * point.
+     *
+     * Making them `abstract` would break all four existing adapters and force
+     * each to state what it does, which is right for disputes: a gateway that
+     * stays silent on a chargeback is the expensive answer. Here silence is
+     * exactly what must NOT be possible. An optional method a non-splitting
+     * adapter simply does not implement would make `createOrder` drop the split
+     * instruction and collect the whole amount into the platform's account — a
+     * completely successful-looking checkout that is the RBI commingling this
+     * entire mechanism exists to prevent.
+     *
+     * So the base class refuses loudly on behalf of every adapter that has not
+     * overridden it, and `CashfreeProvider` overrides both.
+     *
+     * 🛑 This is NOT a second `supportsSplit`. That field lives on
+     * `RegisteredPaymentGateway` because whether split settlement is AVAILABLE is
+     * a fact about the product the business onboarded (Easy Split is separately
+     * onboarded, not an inherent property of the Cashfree API). What these
+     * methods encode is whether the ADAPTER has an implementation — a different
+     * question with a different owner, exactly as `acceptsRestrictedListingTypes`
+     * is a permission and `supportsSplit` a capability. The two compose: the
+     * resolver picks a split-capable gateway, and the adapter refuses anyway if
+     * it is handed splits it cannot execute. Defence in depth, because the
+     * failure is invisible.
+     */
+    /**
+     * Register a seller as a vendor this gateway can settle money to.
+     *
+     * 🛑 Idempotent by contract. The caller passes a `vendorId` it can always
+     * recompute (the store slug), so a re-run must be safe — an adapter that
+     * creates a second vendor on a repeat call is wrong, and the registration job
+     * WILL re-run (jobs retry, and an admin can re-approve a store).
+     *
+     * 🛑 THROWS rather than returning `rejected` when the adapter has no
+     * implementation, and the distinction is load-bearing: `rejected` is a
+     * statement about the SELLER that an operator would act on by contacting
+     * them, while this is a statement about our own configuration. Reporting a
+     * missing implementation as a seller refusal would send a human to chase the
+     * wrong party.
+     */
+    async registerSettlementVendor(input) {
+        throw Object.assign(new Error(`${this.name} does not implement split-settlement vendor registration, so ` +
+            `vendor "${input.vendorId}" cannot be onboarded through it. Enable a ` +
+            `gateway whose registry entry declares supportsSplit.`), { httpStatus: 501, code: "SPLIT_SETTLEMENT_UNSUPPORTED" });
+    }
+    /**
+     * Create an order, splitting the capture across vendors.
+     *
+     * 🛑 **CALL THIS, NOT `createOrder`, FROM THE CHECKOUT PATH** — always, even
+     * when `splits` is empty. One call site that cannot forget is what makes the
+     * refusal below reachable; a caller that chooses between two methods is a
+     * caller that will one day choose `createOrder` for a multi-vendor cart and
+     * collect the lot into the platform's own account.
+     *
+     * The base implementation refuses a NON-EMPTY list and otherwise delegates,
+     * so a single-vendor cart behaves exactly as it does today on every gateway.
+     *
+     * 🛑 `amount` and every `splits[].amount` are in the SMALLEST CURRENCY UNIT.
+     * The adapter converts, in one place, in both directions.
+     */
+    async createOrderWithSplit(amount, currency, metadata, splits) {
+        if (splits && splits.length > 0) {
+            throw Object.assign(new Error(`${this.name} cannot split a capture across vendors, and was handed ` +
+                `${splits.length} split instruction(s) for store(s) ` +
+                `${splits.map((s) => s.storeId || "(unnamed)").join(", ")}. ` +
+                `Collecting without them would settle those sellers' share into the ` +
+                `platform's own account, which is the commingling split settlement ` +
+                `exists to avoid — so the capture is refused instead.`), { httpStatus: 501, code: "SPLIT_SETTLEMENT_UNSUPPORTED" });
+        }
+        return this.createOrder(amount, currency, metadata);
+    }
 }

package/dist/contracts/registry.d.ts

@@ -1,12 +1,14 @@
 import type { IAuthProvider, ISessionProvider } from "./auth";
 import type { IEmailProvider } from "./email";
 import type { IStorageProvider } from "./storage";
-import type { IPaymentProvider } from "./payment";
+import type { IPaymentProvider, RegisteredPaymentGateway } from "./payment";
 import type { IShippingProvider } from "./shipping";
+import type { ITaxProvider } from "./tax";
 import type { ISearchProvider } from "./search";
 import type { ICacheProvider, IQueueProvider, IEventBus } from "./infra";
 import type { IStyleAdapter } from "./style";
 import type { IDbProvider } from "./repository";
+import type { IAssistantModelProvider } from "./ai";
 export interface IRbacProvider {
     /** Resolve the permission list for a user UID. Admin role returns []. */
     getPermissions: (uid: string) => Promise<string[]>;
@@ -21,12 +23,46 @@ export interface ProviderRegistry {
     style: IStyleAdapter;
     db?: IDbProvider;
     payment?: IPaymentProvider;
+    /**
+     * Every online gateway an admin has enabled — the input to the PER-CART
+     * gateway choice, which `payment` structurally cannot answer because it is
+     * one provider resolved at module load.
+     *
+     * 🛑 ABSENT is not "no gateways"; it is "this install has not adopted the
+     * per-cart resolver". The server helper that reads this treats absence by
+     * falling back to `[payment]` with `supportsSplit: false`, so an install that
+     * registers nothing here keeps its single-vendor behaviour exactly and is
+     * REFUSED for multi-vendor carts rather than silently commingling. That is
+     * the fail-closed direction; the alternative would make an un-migrated
+     * install look compliant.
+     *
+     * See `RegisteredPaymentGateway` for why `supportsSplit` is declared here and
+     * `acceptsRestrictedListingTypes` on the provider.
+     */
+    paymentGateways?: readonly RegisteredPaymentGateway[];
     shipping?: IShippingProvider;
+    /**
+     * Jurisdiction tax engine. Optional, and defaults to India GST at the call
+     * site rather than here — an install that never registers one keeps today's
+     * behaviour exactly, which is what makes adopting the seam safe one caller at
+     * a time instead of in a single 42-file sweep.
+     */
+    tax?: ITaxProvider;
     search?: ISearchProvider;
     cache?: ICacheProvider;
     queue?: IQueueProvider;
     eventBus?: IEventBus;
     rbac?: IRbacProvider;
+    /**
+     * Assistant model vendors, preference-ordered — an ARRAY like
+     * `paymentGateways`, not a single slot like `tax`/`search`, because
+     * `getAssistantProviders()`'s whole point is trying each in order and
+     * refusing (never silently falling back) rather than picking one at
+     * module load. Absent means the Assistant feature's own default
+     * (`[new GroqModelProvider()]`) — registering here is how a second vendor
+     * gets wired without editing `_internal/server/features/assistant/actions.ts`.
+     */
+    aiProviders?: readonly IAssistantModelProvider[];
 }
 export declare function registerProviders(registry: ProviderRegistry): void;
 export declare function getProviders(): ProviderRegistry;

package/dist/contracts/tax.d.ts

@@ -0,0 +1,118 @@
+/**
+ * The tax seam. Tier AK A3.
+ *
+ * ## Why this exists
+ *
+ * `gstRate`, `hsnCode` and `placeOfSupply` are read across 42 files, and
+ * CGST/SGST/IGST is an Indian GST concept — so appkit shipped an *Indian*
+ * ecommerce tax model rather than a tax model. A buyer of this package selling
+ * in the EU needs VAT with a reverse charge; in the US, destination sales tax
+ * with nexus. Neither is expressible as "split the rate in half when the states
+ * match".
+ *
+ * ## 🛑 The FIELDS DO NOT MOVE, and this is the whole reason the phase is cheap
+ *
+ * `gstRate` / `hsnCode` / `placeOfSupply` stay exactly where they are on
+ * `ProductDocument` and `OrderDocument`. They become the India provider's
+ * PAYLOAD rather than appkit's universal schema. That buys the seam with:
+ *
+ *   · no Firestore migration, so no stored document becomes wrong (Rule #3)
+ *   · no change to any index or query
+ *   · nothing to roll back if a buyer never needs a second jurisdiction
+ *
+ * A schema migration was the first plan and it was the wrong one: the goal is
+ * that appkit does not *compute* one country's tax, not that it forgets the
+ * country exists.
+ *
+ * ## 🛑 Implementations DELEGATE. They do not reimplement.
+ *
+ * `IndiaGstTaxProvider` calls the existing `calculateGst` /
+ * `calculateGstInclusive` / `allocateAcrossMembers`. It is a seam, not a
+ * rewrite — and that is deliberate, because the two existing functions split
+ * the half DIFFERENTLY and the difference is load-bearing:
+ *
+ *   calculateGst           cgst = sgst = round(gst / 2), gst RE-DERIVED as half*2
+ *   calculateGstInclusive  cgst = round(gst / 2), sgst = round(gst - cgst)
+ *
+ * On ₹66.67 at 18% inclusive that is cgst 5.09 / sgst 5.08, preserving the
+ * 10.17 total. A reimplementation that "tidied" the two into agreement would
+ * move a paisa on real invoices, and GST is filed on those figures.
+ *
+ * The gate for this phase is `.build-memory/tax-roundtrip.mjs`: 397 breakdowns
+ * across every slab, both supply directions and the rounding edges, required to
+ * be byte-identical before and after. One paisa of drift is a defect.
+ */
+/** A single tax component on a line, named by the jurisdiction's own vocabulary. */
+export interface TaxComponent {
+    /** `"cgst"`, `"sgst"`, `"igst"`, `"vat"`, `"salesTax"` — the provider's term. */
+    code: string;
+    /** Human label for an invoice line. */
+    label: string;
+    /** Percentage applied, e.g. `9` for half of an 18% intra-state GST. */
+    rate: number;
+    /** Money, in MAJOR currency units — `1.50`, never a minor-unit `150`. */
+    amount: number;
+}
+/**
+ * The result of taxing one amount.
+ *
+ * `components` sums to `taxAmount` exactly — providers are responsible for
+ * assigning any rounding remainder to one component rather than letting the
+ * parts disagree with the total.
+ */
+export interface TaxBreakdown {
+    /** The amount tax was computed ON (ex-tax base). */
+    taxableAmount: number;
+    /** Total tax. Equals the sum of `components`. */
+    taxAmount: number;
+    components: TaxComponent[];
+}
+/**
+ * Where a sale happens, in the only terms a tax engine actually needs.
+ *
+ * Deliberately NOT `placeOfSupply: string`. That is India's word for the
+ * destination state code, and naming the contract after it would re-import the
+ * jurisdiction this interface exists to abstract.
+ */
+export interface TaxJurisdiction {
+    /** Seller's region code — an Indian state code, a US state, an EU country. */
+    origin?: string;
+    /** Buyer's region code. */
+    destination?: string;
+    /** ISO 3166-1 alpha-2, when a provider needs to distinguish cross-border. */
+    country?: string;
+}
+/** What is being taxed. `taxCode` is the jurisdiction's classification (HSN, SIC, …). */
+export interface TaxableItem {
+    /** Rate as a percentage, e.g. `18`. Resolved by the caller from its own data. */
+    rate: number;
+    /** Jurisdiction classification code — India's HSN, and whatever elsewhere. */
+    taxCode?: string;
+}
+export declare abstract class ITaxProvider {
+    /** Stable id, e.g. `"india-gst"`. */
+    abstract readonly id: string;
+    /**
+     * Tax ADDED to an ex-tax amount.
+     *
+     * @param taxableAmount the ex-tax base, in major units
+     */
+    abstract onExclusive(item: TaxableItem, jurisdiction: TaxJurisdiction, taxableAmount: number): TaxBreakdown;
+    /**
+     * Tax EXTRACTED from a tax-inclusive amount.
+     *
+     * 🛑 Not derivable from `onExclusive` by the caller. Backing out of a gross
+     * figure and adding onto a net one round differently, and this codebase
+     * already relies on the difference — see the class docstring.
+     *
+     * @param gross the tax-inclusive total, in major units
+     */
+    abstract onInclusive(item: TaxableItem, jurisdiction: TaxJurisdiction, gross: number): TaxBreakdown;
+    /**
+     * Is this sale taxed as same-region? India splits CGST/SGST when it is and
+     * charges IGST when it is not; other jurisdictions may ignore the question
+     * entirely, which is why it is the provider's to answer and not a caller's
+     * boolean to pass around.
+     */
+    abstract isSameRegion(jurisdiction: TaxJurisdiction): boolean;
+}

package/dist/contracts/tax.js

@@ -0,0 +1,3 @@
+// --- Tax Shared Types ---------------------------------------------------------
+export class ITaxProvider {
+}

package/dist/core/CacheManager.d.ts

@@ -25,6 +25,27 @@ export declare class CacheManager {
     clear(): void;
     size(): number;
     keys(): string[];
+    /**
+     * Item 8 §18 (overhaul brief) — the admin cache page's real prerequisite.
+     * `.keys()`/`.clear()` already told a caller WHICH keys exist and how to
+     * wipe everything; neither told it how STALE an entry is, which is what
+     * a "current TTL" column needs. Returns `null` for a missing OR already
+     * logically-expired key — same "nothing to show" answer either way, so a
+     * caller never has to special-case the two.
+     */
+    getEntryMeta(key: string): {
+        ageMs: number;
+        ttl: number | undefined;
+        expiresInMs: number | null;
+    } | null;
+    /**
+     * Item 8 §18 — a repository whose cache is keyed per-id/per-slug (e.g.
+     * `products.repository.ts`) has no single key to `.delete()`; every entry
+     * sharing that repository's key prefix needs to go together. The admin
+     * page's "Clear all `<repo>` cache" button is this, not a loop the caller
+     * reimplements against `.keys()` itself.
+     */
+    clearByPrefix(prefix: string): number;
     cleanExpired(): number;
 }
 /** Default shared CacheManager singleton */