《独立开发者的商业指南·资本与退出》2.1 股权结构与表决权

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

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

export type Holder = {
  name: string;
  shares: number;
  votesPerShare: number;
  dividendUnits?: number;
};

export type EquityLayer = {
  name: string;
  ownershipBps: Bps;
  votingBps: Bps;
  dividendBps: Bps;
};

export type EquityStructure = {
  holders: EquityLayer[];
  totalShares: number;
  totalVotes: number;
  totalDividendUnits: number;
  dualClass: boolean;
};

export type VotingPower = {
  name: string;
  powerBps: Bps;
};

function validate(holders: Holder[]): Result<null> {
  if (holders.length === 0) {
    return fail("at least one holder is required");
  }
  const names = new Set<string>();
  for (const holder of holders) {
    if (holder.name.trim() === "") {
      return fail("holder name must not be empty");
    }
    if (names.has(holder.name)) {
      return fail(`duplicate holder: ${holder.name}`);
    }
    names.add(holder.name);
    if (!Number.isInteger(holder.shares) || holder.shares <= 0) {
      return fail(`invalid shares for ${holder.name}`);
    }
    if (!Number.isInteger(holder.votesPerShare) || holder.votesPerShare < 0) {
      return fail(`invalid votes for ${holder.name}`);
    }
    const units = holder.dividendUnits ?? holder.shares;
    if (!Number.isInteger(units) || units < 0) {
      return fail(`invalid dividend units for ${holder.name}`);
    }
  }
  return ok(null);
}

/**
 * Three layers of the same cap table: ownership by shares, voting by
 * votes, and dividends by dividend units. By default one share carries
 * one vote and one dividend unit; both can be overridden per holder.
 */
export function equityLayers(holders: Holder[]): Result<EquityStructure> {
  const checked = validate(holders);
  if (!checked.ok) {
    return checked;
  }
  const totalShares = holders.reduce((acc, holder) => acc + holder.shares, 0);
  const totalVotes = holders.reduce(
    (acc, holder) => acc + holder.shares * holder.votesPerShare,
    0,
  );
  const totalDividendUnits = holders.reduce(
    (acc, holder) => acc + (holder.dividendUnits ?? holder.shares),
    0,
  );
  if (totalVotes <= 0) {
    return fail("total votes must be positive");
  }
  if (totalDividendUnits <= 0) {
    return fail("total dividend units must be positive");
  }

  const layers = holders.map((holder) => ({
    name: holder.name,
    ownershipBps: divide(holder.shares, totalShares),
    votingBps: divide(holder.shares * holder.votesPerShare, totalVotes),
    dividendBps: divide(
      holder.dividendUnits ?? holder.shares,
      totalDividendUnits,
    ),
  }));
  const dualClass = new Set(holders.map((holder) => holder.votesPerShare)).size > 1;

  return ok({
    holders: layers,
    totalShares,
    totalVotes,
    totalDividendUnits,
    dualClass,
  });
}

/** Add a newly issued holder without changing anyone else's share count. */
export function issueShares(
  holders: Holder[],
  name: string,
  newShares: number,
  votesPerShare: number,
  dividendUnits?: number,
): Result<EquityStructure> {
  if (!Number.isInteger(newShares) || newShares <= 0) {
    return fail("new shares must be a positive integer");
  }
  const candidate: Holder = { name, shares: newShares, votesPerShare };
  if (dividendUnits !== undefined) {
    candidate.dividendUnits = dividendUnits;
  }
  return equityLayers([...holders, candidate]);
}

/** SDE lost while a decision waits, using a straight months/12 proration. */
export function deadlockCost(
  annualSdeCents: Cents,
  months: number,
): Result<Cents> {
  if (!Number.isInteger(annualSdeCents) || annualSdeCents < 0) {
    return fail("annual SDE must be a non-negative integer amount");
  }
  if (!Number.isInteger(months) || months < 0) {
    return fail("months must be a non-negative integer");
  }
  return ok(Math.round((annualSdeCents * months) / 12));
}

/** Present-value loss from delaying a sale, with an explicit discount rate. */
export function delayCost(
  valueCents: Cents,
  months: number,
  annualDiscountBps: Bps,
): Result<Cents> {
  if (!Number.isInteger(valueCents) || valueCents < 0) {
    return fail("value must be a non-negative integer amount");
  }
  if (!Number.isInteger(months) || months < 0) {
    return fail("months must be a non-negative integer");
  }
  if (!Number.isInteger(annualDiscountBps) || annualDiscountBps < 0) {
    return fail("discount rate must be a non-negative integer in basis points");
  }
  const years = months / 12;
  const factor = 1 - 1 / Math.pow(1 + annualDiscountBps / 10000, years);
  return ok(Math.round(valueCents * factor));
}

/**
 * Banzhaf power for a small cap table: count the winning coalitions in
 * which each holder is pivotal, then divide by all pivotal appearances.
 * A 10% holder can carry a third of the power when the other two are tied.
 */
export function banzhaf(holders: Holder[]): Result<VotingPower[]> {
  const checked = validate(holders);
  if (!checked.ok) {
    return checked;
  }
  if (holders.length > 12) {
    return fail("banzhaf supports at most 12 holders");
  }
  const votes = holders.map((holder) => holder.shares * holder.votesPerShare);
  const totalVotes = votes.reduce((acc, value) => acc + value, 0);
  if (totalVotes <= 0) {
    return fail("total votes must be positive");
  }
  const majority = Math.floor(totalVotes / 2) + 1;
  const pivotal = new Array<number>(holders.length).fill(0);
  const subsets = 1 << holders.length;

  for (let mask = 1; mask < subsets; mask += 1) {
    let coalition = 0;
    for (let i = 0; i < holders.length; i += 1) {
      if (mask & (1 << i)) {
        coalition += votes[i];
      }
    }
    if (coalition < majority) {
      continue;
    }
    for (let i = 0; i < holders.length; i += 1) {
      if ((mask & (1 << i)) && coalition - votes[i] < majority) {
        pivotal[i] += 1;
      }
    }
  }

  const totalPivotal = pivotal.reduce((acc, value) => acc + value, 0);
  if (totalPivotal === 0) {
    return fail("no pivotal votes in this cap table");
  }
  return ok(
    holders.map((holder, index) => ({
      name: holder.name,
      powerBps: divide(pivotal[index], totalPivotal),
    })),
  );
}