《独立开发者的商业指南·资本与退出》8.1 交割清单与资金流

// file: src/capital/closing.ts
// tier: L1
// verify: node --test test/capital/closing.test.ts

import { type Cents } from "../core/money.ts";
import { type Bps, applyRate, divide } from "../core/rate.ts";
import { type Result, fail, ok } from "../core/result.ts";

export type ChecklistCategory =
  | "corporate-resolution"
  | "contract-signature"
  | "payment-proof"
  | "asset-delivery"
  | "third-party-consent"
  | "escrow-arrangement";

export const CHECKLIST_CATEGORIES: ChecklistCategory[] = [
  "corporate-resolution",
  "contract-signature",
  "payment-proof",
  "asset-delivery",
  "third-party-consent",
  "escrow-arrangement",
];

export type ChecklistItem = {
  category: ChecklistCategory;
  label: string;
  done: boolean;
  blocking: boolean;
};

export type ClosingInput = {
  priceCents: Cents;
  cashAtClosingBps: Bps;
  escrowBps: Bps;
  escrowMonths: number;
  delayDays: number;
  annualCapitalCostBps: Bps;
  monthlyOperatingCents: Cents;
  items: ChecklistItem[];
};

export type CategoryProgress = {
  total: number;
  done: number;
  pending: number;
};

export type ClosingOutcome = {
  itemCount: number;
  doneCount: number;
  pendingCount: number;
  completionBps: Bps;
  blockingPending: number;
  missingCategories: ChecklistCategory[];
  categoryProgress: Record<ChecklistCategory, CategoryProgress>;
  readyToClose: boolean;
  cashPortionCents: Cents;
  earnOutCents: Cents;
  escrowCents: Cents;
  sellerCashAtClosingCents: Cents;
  deferredCents: Cents;
  closingCashShareBps: Bps;
  delayInterestCents: Cents;
  cashOccupancyCents: Cents;
  delayCostCents: Cents;
  escrowReleaseMonth: number;
};

function checkAmount(value: Cents, label: string): string | null {
  if (!Number.isInteger(value) || value < 0) {
    return `${label} must be a non-negative integer amount in cents`;
  }
  return null;
}

function checkBps(value: Bps, label: string): string | null {
  if (!Number.isInteger(value) || value < 0 || value > 10000) {
    return `${label} must be between 0 and 10000 bps`;
  }
  return null;
}

function emptyProgress(): Record<ChecklistCategory, CategoryProgress> {
  return {
    "corporate-resolution": { total: 0, done: 0, pending: 0 },
    "contract-signature": { total: 0, done: 0, pending: 0 },
    "payment-proof": { total: 0, done: 0, pending: 0 },
    "asset-delivery": { total: 0, done: 0, pending: 0 },
    "third-party-consent": { total: 0, done: 0, pending: 0 },
    "escrow-arrangement": { total: 0, done: 0, pending: 0 },
  };
}

/**
 * Closing has two independent questions. The checklist answers "can the deal
 * legally close": all six categories must be represented, and no blocking item
 * may remain open. The funds flow answers "how much cash arrives on the day":
 * the escrow and the earn-out are withheld from the headline price, so the
 * seller's closing cash is smaller than the number in the agreement.
 */
export function closingChecklist(input: ClosingInput): Result<ClosingOutcome> {
  const priceError = checkAmount(input.priceCents, "price");
  if (priceError) {
    return fail(priceError);
  }
  if (input.priceCents === 0) {
    return fail("price must be positive");
  }
  for (const [value, label] of [
    [input.cashAtClosingBps, "cash at closing"],
    [input.escrowBps, "escrow"],
    [input.annualCapitalCostBps, "annual capital cost"],
  ] as Array<[Bps, string]>) {
    const error = checkBps(value, label);
    if (error) {
      return fail(error);
    }
  }
  if (input.escrowBps > input.cashAtClosingBps) {
    return fail("escrow cannot exceed the cash portion paid at closing");
  }
  if (!Number.isInteger(input.escrowMonths) || input.escrowMonths < 0) {
    return fail("escrow months must be a non-negative integer");
  }
  if (
    !Number.isInteger(input.delayDays) ||
    input.delayDays < 0 ||
    input.delayDays > 365
  ) {
    return fail("delay days must be an integer between 0 and 365");
  }
  const operatingError = checkAmount(
    input.monthlyOperatingCents,
    "monthly operating cost",
  );
  if (operatingError) {
    return fail(operatingError);
  }
  if (input.items.length === 0) {
    return fail("checklist must contain at least one item");
  }

  const categoryProgress = emptyProgress();
  let doneCount = 0;
  let blockingPending = 0;
  for (const item of input.items) {
    if (!CHECKLIST_CATEGORIES.includes(item.category)) {
      return fail(`unknown checklist category: ${item.category}`);
    }
    const progress = categoryProgress[item.category];
    progress.total += 1;
    if (item.done) {
      progress.done += 1;
      doneCount += 1;
    } else {
      progress.pending += 1;
      if (item.blocking) {
        blockingPending += 1;
      }
    }
  }

  const missingCategories = CHECKLIST_CATEGORIES.filter(
    (category) => categoryProgress[category].total === 0,
  );
  const itemCount = input.items.length;
  const pendingCount = itemCount - doneCount;

  const cashPortionCents = applyRate(input.priceCents, input.cashAtClosingBps);
  const earnOutCents = input.priceCents - cashPortionCents;
  const escrowCents = applyRate(input.priceCents, input.escrowBps);
  const sellerCashAtClosingCents = cashPortionCents - escrowCents;
  const deferredCents = input.priceCents - sellerCashAtClosingCents;
  const delayInterestCents = Math.round(
    (sellerCashAtClosingCents *
      input.annualCapitalCostBps *
      input.delayDays) /
      (10000 * 365),
  );
  const cashOccupancyCents = Math.round(
    (input.monthlyOperatingCents * input.delayDays) / 30,
  );

  return ok({
    itemCount,
    doneCount,
    pendingCount,
    completionBps: divide(doneCount, itemCount),
    blockingPending,
    missingCategories,
    categoryProgress,
    readyToClose: blockingPending === 0 && missingCategories.length === 0,
    cashPortionCents,
    earnOutCents,
    escrowCents,
    sellerCashAtClosingCents,
    deferredCents,
    closingCashShareBps: divide(sellerCashAtClosingCents, input.priceCents),
    delayInterestCents,
    cashOccupancyCents,
    delayCostCents: delayInterestCents + cashOccupancyCents,
    escrowReleaseMonth: input.escrowMonths,
  });
}