@cyc-seattle/platform 1.43.1 → 1.45.0

package/dist/planning/capital.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from "./context.ts";
+import type { CostCenterBooker } from "./lines.ts";
+import type { CapitalRank, CostLine, OrganizationTotals } from "./types.ts";
+/** Records each planned purchase as capital on the organization, which pays for all capital. */
+export declare function bookCapitalItems(ctx: Context, booker: CostCenterBooker): void;
+/**
+ * The capital purchases in rank order, each with the running total and whether the year's operating
+ * and fundraising nets cover it. Capital entered as a budget line comes after the ranked items, with
+ * a warning, since it has no rank.
+ */
+export declare function rankCapital(ctx: Context, lines: CostLine[], organization: OrganizationTotals): CapitalRank[];

package/dist/planning/capital.js

@@ -0,0 +1,60 @@
+const byRank = (a, b) => (a.sort ?? Number.POSITIVE_INFINITY) - (b.sort ?? Number.POSITIVE_INFINITY) || a.name.localeCompare(b.name);
+/** The capital items on an asset account, most needed first. The rest are left out, with a warning. */
+function rankedItems(ctx) {
+    return (ctx.data.plan_capital_items ?? [])
+        .filter((item) => {
+        if (ctx.accountType(item.account_id) === "asset")
+            return true;
+        ctx.warn("capital_not_asset", `${item.name} isn't on an asset account, so it's left out of capital`, item.key);
+        return false;
+    })
+        .sort(byRank);
+}
+/** Records each planned purchase as capital on the organization, which pays for all capital. */
+export function bookCapitalItems(ctx, booker) {
+    for (const item of rankedItems(ctx)) {
+        booker.add({
+            cost_center_type: "org",
+            cost_center_key: null,
+            account_id: item.account_id,
+            function: ctx.functionFor(item.account_id, null, "org"),
+            amount: item.amount_cents,
+            line_key: `capital:${item.key}`,
+            line_name: item.name,
+            explanation: item.name,
+            mtdc_share: 0,
+        });
+    }
+}
+/**
+ * The capital purchases in rank order, each with the running total and whether the year's operating
+ * and fundraising nets cover it. Capital entered as a budget line comes after the ranked items, with
+ * a warning, since it has no rank.
+ */
+export function rankCapital(ctx, lines, organization) {
+    const budget = lines
+        .filter((l) => l.line_key.startsWith("budget:") && ctx.accountType(l.account_id) === "asset")
+        .sort((a, b) => a.line_name.localeCompare(b.line_name));
+    for (const l of budget) {
+        ctx.warn("capital_unranked", `${l.line_name} is capital entered as a budget line, so it comes after the ranked capital list`, l.line_key.slice("budget:".length));
+    }
+    const available = organization.operating.net_cents + organization.fundraising.net_cents;
+    let running = 0;
+    return [
+        ...rankedItems(ctx).map((i) => ({
+            key: i.key,
+            name: i.name,
+            account_id: i.account_id,
+            amount_cents: i.amount_cents,
+        })),
+        ...budget.map((l) => ({
+            key: l.line_key.slice("budget:".length),
+            name: l.line_name,
+            account_id: l.account_id,
+            amount_cents: l.amount_cents,
+        })),
+    ].map((item, i) => {
+        running += item.amount_cents;
+        return { rank: i + 1, ...item, running_cents: running, funded: running <= available };
+    });
+}

package/dist/planning/engine.js

@@ -1,5 +1,6 @@
 import { scheduleActivities } from "./activities.js";
 import { bookBonuses } from "./bonus.js";
+import { bookCapitalItems, rankCapital } from "./capital.js";
 import { Context } from "./context.js";
 import { bookBudgetLines, bookLaborLines, CostCenterBooker } from "./lines.js";
 import { mtdc } from "./measures.js";
@@ -22,6 +23,7 @@ export function computePlan(data) {
     bookRevenue(ctx);
     const booker = new CostCenterBooker(ctx);
     bookBudgetLines(ctx, booker);
+    bookCapitalItems(ctx, booker);
     bookLaborLines(ctx, booker);
     const charged = bookSalaries(ctx, coaching, booker);
     booker.flush();
@@ -30,12 +32,14 @@ export function computePlan(data) {
     allocatePools(ctx);
     const bonuses = bookBonuses(ctx);
     const lines = sumLines(ctx);
+    const organization = organizationTotals(ctx, lines);
     return {
         lines,
         pnl: summarize(ctx, lines, mtdcByOffering),
-        organization: organizationTotals(ctx, lines),
+        organization,
         activities,
         positions: summarizePositions(ctx, coaching, charged, bonuses, doubleBooked),
+        capital: rankCapital(ctx, lines, organization),
         warnings: ctx.warnings,
     };
 }

package/dist/planning/pools.d.ts

@@ -1,7 +1,9 @@
 import type { Context } from "./context.ts";
 /**
- * Divides everything in each pool among all of the plan year's offerings by MTDC, keeping each
- * amount's account and function. Shared costs never count toward MTDC, so one pool's split never shifts
+ * Divides everything in each pool among the plan year's programs' offerings by MTDC, keeping each
+ * amount's account and function. Non-program's net offsets the pools first (cyc-seattle/platform#242):
+ * that part of each pooled amount stays with the organization, so a gain shrinks every program's
+ * share and a loss grows it. Shared costs never count toward MTDC, so one pool's split never shifts
  * another's.
  */
 export declare function allocatePools(ctx: Context): void;

package/dist/planning/pools.js

@@ -1,11 +1,38 @@
 import { mtdc } from "./measures.js";
+/** Whether an offering is a program's. Every other offering is non-program, such as a charter. */
+function isProgram(ctx, productId) {
+    return ctx.products.get(productId)?.kind === "program";
+}
+/** Non-program's net before the pools: its offerings' revenue less their own costs. */
+function nonProgramNet(ctx) {
+    const keys = new Set(ctx
+        .fyOfferings()
+        .filter((o) => !isProgram(ctx, o.product_id))
+        .map((o) => o.key));
+    let net = 0;
+    for (const e of ctx.entries) {
+        if (e.cost_center_type !== "offering" || !keys.has(e.cost_center_key ?? ""))
+            continue;
+        const type = ctx.accountType(e.account_id);
+        if (type === "revenue")
+            net += e.amount;
+        else if (type === "expense")
+            net -= e.amount;
+    }
+    return net;
+}
 /**
- * Divides everything in each pool among all of the plan year's offerings by MTDC, keeping each
- * amount's account and function. Shared costs never count toward MTDC, so one pool's split never shifts
+ * Divides everything in each pool among the plan year's programs' offerings by MTDC, keeping each
+ * amount's account and function. Non-program's net offsets the pools first (cyc-seattle/platform#242):
+ * that part of each pooled amount stays with the organization, so a gain shrinks every program's
+ * share and a loss grows it. Shared costs never count toward MTDC, so one pool's split never shifts
  * another's.
  */
 export function allocatePools(ctx) {
-    const weights = new Map(ctx.fyOfferings().map((o) => [o.key, Math.max(0, mtdc(ctx, o.key))]));
+    const weights = new Map(ctx
+        .fyOfferings()
+        .filter((o) => isProgram(ctx, o.product_id))
+        .map((o) => [o.key, Math.max(0, mtdc(ctx, o.key))]));
     const total = [...weights.values()].reduce((t, w) => t + w, 0);
     const pools = new Map(ctx.data.plan_pools.map((p) => [p.key, p]));
     const pooled = [];
@@ -14,27 +41,52 @@ export function allocatePools(ctx) {
         (e.cost_center_type === "pool" ? pooled : kept).push(e);
     if (pooled.length === 0)
         return;
+    const net = nonProgramNet(ctx);
     ctx.entries.splice(0, ctx.entries.length, ...kept);
+    const overhead = pooled.reduce((t, e) => t + e.amount, 0);
+    // Each pooled amount gives up the same fraction, so the offset falls on each pool in proportion to its size.
+    let offset = overhead > 0 ? net / overhead : 0;
+    if (offset > 1) {
+        ctx.warn("non_program_exceeds_pools", `Non-program makes more than all the shared costs, so ${ctx.data.organization.name} keeps all of them`);
+        offset = 1;
+    }
     if (total <= 0) {
-        ctx.warn("no_mtdc", `No offering this year has costs that count toward MTDC, so ${ctx.data.organization.name} keeps all the shared costs`);
+        ctx.warn("no_mtdc", `No program's offering this year has costs that count toward MTDC, so ${ctx.data.organization.name} keeps all the shared costs`);
     }
     for (const e of pooled) {
-        const pool = pools.get(e.cost_center_key ?? "");
+        const name = pools.get(e.cost_center_key ?? "")?.name ?? "Pool";
         const base = {
             account_id: e.account_id,
             function: e.function,
-            line_key: `pool:${e.cost_center_key}:${e.line_key}`,
-            line_name: `${pool?.name ?? "Pool"} share: ${e.line_name}`,
-            explanation: `${pool?.name ?? "Pool"}: ${e.explanation}`,
             stage: "pool",
             mtdc_share: 0,
         };
+        const share = {
+            ...base,
+            line_key: `pool:${e.cost_center_key}:${e.line_key}`,
+            line_name: `${name} share: ${e.line_name}`,
+            explanation: `${name}: ${e.explanation}`,
+        };
         if (total <= 0) {
-            ctx.book({ ...base, cost_center_type: "org", cost_center_key: null, amount: e.amount });
+            ctx.book({ ...share, cost_center_type: "org", cost_center_key: null, amount: e.amount });
             continue;
         }
+        ctx.book({
+            ...base,
+            cost_center_type: "org",
+            cost_center_key: null,
+            amount: e.amount * offset,
+            line_key: `offset:${e.cost_center_key}:${e.line_key}`,
+            line_name: `${name} covered by non-program: ${e.line_name}`,
+            explanation: `${name}: ${e.explanation}, the part non-program's net covers`,
+        });
         for (const [key, w] of weights) {
-            ctx.book({ ...base, cost_center_type: "offering", cost_center_key: key, amount: (e.amount * w) / total });
+            ctx.book({
+                ...share,
+                cost_center_type: "offering",
+                cost_center_key: key,
+                amount: (e.amount * (1 - offset) * w) / total,
+            });
         }
     }
 }

package/dist/planning/types.d.ts

@@ -188,6 +188,18 @@ export interface PlanBudgetLine extends Versioned {
     excluded_from_mtdc: boolean;
     note: string | null;
 }
+/**
+ * Something lasting the Operations Plan means to buy, ranked by `sort` with the most needed first.
+ * Its account is an asset account.
+ */
+export interface PlanCapitalItem extends Versioned {
+    name: string;
+    amount_cents: number;
+    account_id: Id;
+    sort: number | null;
+    note?: string | null;
+    link?: string | null;
+}
 /** The year's rates. An Operations plan version has at most one row. */
 export interface PlanRates extends Versioned {
     /** Employer payroll costs, as a share of wages. */
@@ -308,6 +320,7 @@ export interface PlanData {
     plan_bonus_owners: PlanBonusOwner[];
     plan_bonus_owner_products: PlanBonusOwnerProduct[];
     plan_closed_dates?: PlanClosedDate[];
+    plan_capital_items?: PlanCapitalItem[];
 }
 /** One line of cost or revenue for the plan year, on one offering, product, pool or the organization. */
 export interface CostLine {
@@ -388,6 +401,22 @@ export interface OrganizationTotals {
     /** Operating net, plus fundraising net, less capital. */
     total_cents: number;
 }
+/**
+ * One planned purchase in the ranked capital list: what's left of the year's money after operations
+ * and fundraising pays for each in rank order, as far as it goes.
+ */
+export interface CapitalRank {
+    rank: number;
+    /** The `plan_capital_items` key, or for capital entered as a budget line, that line's key. */
+    key: Id;
+    name: string;
+    account_id: Id;
+    amount_cents: number;
+    /** This item's amount plus every item ranked above it. */
+    running_cents: number;
+    /** Whether the operating net plus the fundraising net covers `running_cents`. */
+    funded: boolean;
+}
 /** One salaried position's year: what it's paid, and where its hours went. */
 export interface PositionSummary {
     position_key: Id;
@@ -421,5 +450,7 @@ export interface EngineOutput {
     activities: ComputedActivity[];
     /** Each salaried position's pay for the year. */
     positions: PositionSummary[];
+    /** The planned capital purchases, most needed first. */
+    capital: CapitalRank[];
     warnings: EngineWarning[];
 }

package/dist/schema/index.d.ts

@@ -39,6 +39,7 @@ export interface Schema {
     plan_bonus_owner_products: PlanBonusOwnerProducts[];
     plan_bonus_owners: PlanBonusOwners[];
     plan_budget_lines: PlanBudgetLines[];
+    plan_capital_items: PlanCapitalItems[];
     plan_closed_dates: PlanClosedDates[];
     plan_labor_lines: PlanLaborLines[];
     plan_offerings: PlanOfferings[];
@@ -46,6 +47,7 @@ export interface Schema {
     plan_programs: PlanPrograms[];
     plan_rates: PlanRates[];
     plan_resources: PlanResources[];
+    plan_result_capital: PlanResultCapital[];
     plan_result_lines: PlanResultLines[];
     plan_result_pnl: PlanResultPnl[];
     plan_result_positions: PlanResultPositions[];
@@ -646,6 +648,26 @@ export interface PlanBudgetLines {
     excluded_from_mtdc: boolean;
     note: string | null;
 }
+/** Something lasting CSC means to buy, ranked with the most needed first. */
+export interface PlanCapitalItems {
+    id: string;
+    /** The version this row belongs to. Capital goes in the Operations Plan's. */
+    version_id: string | PlanVersions;
+    /** Stays the same across versions. Copy it where another row asks for this one's Key. */
+    key: string;
+    /** What to buy, such as a coach boat. */
+    name: string;
+    /** In cents: 12500 is $125.00. */
+    amount_cents: number;
+    /** The asset account it goes on, such as Equipment. */
+    account_id: string | Accounts;
+    /** 1 is the most needed. Drag rows in the table to reorder them. */
+    sort: number | null;
+    /** Why CSC needs it. */
+    note: string | null;
+    /** A quote or listing for it, as a web address. */
+    link: string | null;
+}
 /** A day the organization is closed, such as Labor Day. The P&L warns about an activity on one. */
 export interface PlanClosedDates {
     id: string;
@@ -760,6 +782,22 @@ export interface PlanResources {
     /** Set for a rental, whose cost is left out of modified total direct costs (MTDC). */
     excluded_from_mtdc: boolean;
 }
+/** The capital list in rank order, in a Financial Plan, with what the year's money covers. A draft's are worked out again a moment after each change to it, and a saved one's when it's saved, and then never change. */
+export interface PlanResultCapital {
+    id: string;
+    /** The Financial Plan these results are for. */
+    version_set_id: string | VersionSets;
+    /** 1 is the most needed. */
+    rank: number | null;
+    item_key: string;
+    name: string | null;
+    /** In cents: 12500 is $125.00. */
+    amount_cents: number | null;
+    /** This and everything ranked above it. In cents: 12500 is $125.00. */
+    running_cents: number | null;
+    /** Whether what's left after operations and fundraising covers it, with everything ranked above it. */
+    funded: boolean | null;
+}
 /** Each cost and revenue line in a Financial Plan's P&L. A draft's are worked out again a moment after each change to it, and a saved one's when it's saved, and then never change. */
 export interface PlanResultLines {
     id: string;
@@ -1160,6 +1198,8 @@ export interface VersionSets {
     saved_at: string | null;
     /** The version of the planning engine that calculated its numbers. */
     platform_version: string | null;
+    /** Set when the Financial Plan is archived, which hides it from Planning's list. Clear it to bring the plan back. An active Financial Plan can't be archived. */
+    archived_at: string | null;
     /** Each plan in the Financial Plan. Add or remove one only while it's a draft. */
     members: (string | VersionSetMembers)[];
     /** The organization's P&L. A draft's is worked out again a moment after each change to it. A saved one's is what it showed when it was saved, worked out a moment after. One with none means working it out failed, and the logs say why. An admin can fill in a saved one's. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyc-seattle/platform",
-  "version": "1.43.1",
+  "version": "1.45.0",
   "description": "Pulumi components for CYC's shared Google Cloud platform: WebService, the platform outputs reader, and the stacks that build the platform",
   "author": "CYC Community Sailing Center",
   "license": "Apache-2.0",