《独立开发者的商业指南·资本与退出》9.3 交接期与知识转移

// file: src/capital/knowledge-transfer.ts
// tier: L1
// verify: node --test test/capital/knowledge-transfer.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 Milestone = {
  day: number;
  deliverable: string;
  weightBps: Bps;
};

export type HandoverInput = {
  founderHoursPerDay: number;
  handoverDays: number;
  founderRateCents: Cents;
  documentationHours: number;
  buyerPmHours: number;
  buyerPmRateCents: Cents;
  priceCents: Cents;
  holdbackBps: Bps;
  acceptanceDays: number;
  milestones: Milestone[];
};

export type MilestoneRelease = {
  day: number;
  deliverable: string;
  weightBps: Bps;
  releaseCents: Cents;
};

export type HandoverOutcome = {
  founderHours: number;
  founderCostCents: Cents;
  documentationCostCents: Cents;
  buyerPmCostCents: Cents;
  totalCostCents: Cents;
  totalCostBpsOfPrice: Bps;
  costPerHandoverDayCents: Cents;
  holdbackCents: Cents;
  finalReleaseCents: Cents;
  milestoneCount: number;
  milestoneWeightBps: Bps;
  releases: MilestoneRelease[];
};

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;
}

/**
 * A handover is a cost with a release schedule. Founder shadowing, written
 * documentation and buyer-side project management all consume hours that have
 * an opportunity cost, while the buyer holds back part of the price until the
 * milestones are met. The model prices the handover, splits the holdback by
 * milestone weight and keeps the two numbers separate: handover cost is what
 * the seller spends, holdback is what the buyer has not yet paid. This is a
 * teaching model, not a legal or tax opinion.
 */
export function handoverPlan(input: HandoverInput): Result<HandoverOutcome> {
  if (
    !Number.isFinite(input.founderHoursPerDay) ||
    input.founderHoursPerDay <= 0 ||
    input.founderHoursPerDay > 24
  ) {
    return fail("founder hours per day must be between 0 and 24");
  }
  if (
    !Number.isInteger(input.handoverDays) ||
    input.handoverDays < 1 ||
    input.handoverDays > 365
  ) {
    return fail("handover days must be an integer between 1 and 365");
  }
  if (!Number.isInteger(input.founderRateCents) || input.founderRateCents <= 0) {
    return fail("founder rate must be a positive integer amount in cents");
  }
  if (
    !Number.isFinite(input.documentationHours) ||
    input.documentationHours < 0 ||
    input.documentationHours > 10000
  ) {
    return fail("documentation hours must be between 0 and 10000");
  }
  if (
    !Number.isFinite(input.buyerPmHours) ||
    input.buyerPmHours < 0 ||
    input.buyerPmHours > 10000
  ) {
    return fail("buyer PM hours must be between 0 and 10000");
  }
  if (
    !Number.isInteger(input.buyerPmRateCents) ||
    input.buyerPmRateCents <= 0
  ) {
    return fail("buyer PM rate must be a positive integer amount in cents");
  }
  if (!Number.isInteger(input.priceCents) || input.priceCents <= 0) {
    return fail("price must be a positive integer amount in cents");
  }
  const holdbackError = checkBps(input.holdbackBps, "holdback");
  if (holdbackError) {
    return fail(holdbackError);
  }
  if (
    !Number.isInteger(input.acceptanceDays) ||
    input.acceptanceDays < input.handoverDays ||
    input.acceptanceDays > 365
  ) {
    return fail("acceptance days must be an integer from handover to 365");
  }
  if (!Array.isArray(input.milestones) || input.milestones.length === 0) {
    return fail("at least one acceptance milestone is required");
  }

  let milestoneWeightBps = 0;
  for (const milestone of input.milestones) {
    if (
      !Number.isInteger(milestone.day) ||
      milestone.day < 1 ||
      milestone.day > input.acceptanceDays
    ) {
      return fail("milestone day must fall inside the acceptance window");
    }
    if (
      typeof milestone.deliverable !== "string" ||
      milestone.deliverable.trim() === ""
    ) {
      return fail("each milestone needs a deliverable label");
    }
    const weightError = checkBps(milestone.weightBps, "milestone weight");
    if (weightError) {
      return fail(weightError);
    }
    milestoneWeightBps += milestone.weightBps;
  }
  if (milestoneWeightBps !== 10000) {
    return fail("milestone weights must add up to 10000 bps");
  }

  const founderHours = input.founderHoursPerDay * input.handoverDays;
  const founderCostCents = Math.round(
    founderHours * input.founderRateCents,
  );
  const documentationCostCents = Math.round(
    input.documentationHours * input.founderRateCents,
  );
  const buyerPmCostCents = Math.round(
    input.buyerPmHours * input.buyerPmRateCents,
  );
  const totalCostCents =
    founderCostCents + documentationCostCents + buyerPmCostCents;
  const holdbackCents = applyRate(input.priceCents, input.holdbackBps);
  const releases = input.milestones.map((milestone) => ({
    day: milestone.day,
    deliverable: milestone.deliverable,
    weightBps: milestone.weightBps,
    releaseCents: applyRate(holdbackCents, milestone.weightBps),
  }));

  return ok({
    founderHours,
    founderCostCents,
    documentationCostCents,
    buyerPmCostCents,
    totalCostCents,
    totalCostBpsOfPrice: divide(totalCostCents, input.priceCents),
    costPerHandoverDayCents: Math.round(totalCostCents / input.handoverDays),
    holdbackCents,
    finalReleaseCents: input.priceCents - holdbackCents,
    milestoneCount: input.milestones.length,
    milestoneWeightBps,
    releases,
  });
}

export type AcceptanceCriterion = {
  key: string;
  met: boolean;
};

export type AcceptanceOutcome = {
  total: number;
  met: number;
  metBps: Bps;
  passed: boolean;
  missing: string[];
};

/**
 * A handover is complete when the buyer can run the business without the
 * seller, not when the seller has sent the last file. The gate counts explicit
 * criteria and requires all of them; a percentage above the threshold is not
 * enough, because the one missing criterion is usually the one that transfers
 * customer trust. The criteria are inputs so each deal can define its own.
 */
export function acceptanceGate(
  criteria: AcceptanceCriterion[],
  thresholdBps: Bps,
): Result<AcceptanceOutcome> {
  if (!Array.isArray(criteria) || criteria.length === 0) {
    return fail("at least one acceptance criterion is required");
  }
  const thresholdError = checkBps(thresholdBps, "acceptance threshold");
  if (thresholdError) {
    return fail(thresholdError);
  }
  const seen = new Set<string>();
  let met = 0;
  const missing: string[] = [];
  for (const criterion of criteria) {
    if (
      typeof criterion.key !== "string" ||
      criterion.key.trim() === ""
    ) {
      return fail("each acceptance criterion needs a key");
    }
    if (seen.has(criterion.key)) {
      return fail("acceptance criterion keys must be unique");
    }
    seen.add(criterion.key);
    if (criterion.met) {
      met += 1;
    } else {
      missing.push(criterion.key);
    }
  }
  const metBps = divide(met, criteria.length);
  return ok({
    total: criteria.length,
    met,
    metBps,
    passed: met === criteria.length && metBps >= thresholdBps,
    missing,
  });
}