@cyc-seattle/platform 1.52.0 → 1.54.0

package/README.md

@@ -4,6 +4,9 @@ Pulumi stacks for CYC Community Sailing Center's shared Google Cloud platform: t
 app owns. The apps that run on it live in their own repos, such as
 [isthmia](https://github.com/cyc-seattle/isthmia).
 
+The [docs site](https://cyc-seattle.github.io/platform/) publishes [`docs/`](docs) from `main`: how the
+platform is built, its data model, and the planning engine.
+
 ## Stacks
 
 | Stack                           | Holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Applied by                                                                                                               |
@@ -164,9 +167,17 @@ login only when it isn't already set, so Actions' credentials win.
 mise run ci
 ```
 
-Runs the type check, Prettier, ESLint, and the unit tests. Tests mock Pulumi with
+Runs the type check, Prettier, ESLint, the unit tests, and the docs site's build. Tests mock Pulumi with
 `pulumi.runtime.setMocks` and never call a live API.
 
+```sh
+mise run docs-dev
+```
+
+Serves the docs site, from `docs-site/`, as you edit `docs/`. A page in `docs/` takes its title from
+its first heading, and a link to another file in the repo goes to GitHub. The build fails on a broken
+link. `.github/workflows/docs.yml` publishes it to GitHub Pages on every push to `main`.
+
 ```sh
 mise run integration
 ```

package/dist/planning/context.d.ts

@@ -35,8 +35,10 @@ export declare class Context {
     readonly planOfVersion: Map<Id, Plan>;
     readonly offeringsById: Map<Id, PlanOffering>;
     readonly offeringsByKey: Map<Id, PlanOffering>;
-    /** Enrollment per offering id. */
+    /** Expected enrollment per offering id, which the costs and revenue use. */
     readonly enrollment: Map<string, number>;
+    /** The most sailors each offering id takes, which the checks use. */
+    readonly maxEnrollment: Map<string, number>;
     /** Days per offering key: the dates it has an activity other than travel. */
     readonly days: Map<string, number>;
     readonly rates: PlanRates | undefined;

package/dist/planning/context.js

@@ -28,8 +28,10 @@ export class Context {
     planOfVersion;
     offeringsById;
     offeringsByKey;
-    /** Enrollment per offering id. */
+    /** Expected enrollment per offering id, which the costs and revenue use. */
     enrollment = new Map();
+    /** The most sailors each offering id takes, which the checks use. */
+    maxEnrollment = new Map();
     /** Days per offering key: the dates it has an activity other than travel. */
     days = new Map();
     rates;

package/dist/planning/engine.js

@@ -9,18 +9,77 @@ import { allocatePools } from "./pools.js";
 import { bookRevenue, countDays } from "./revenue.js";
 import { bookSalaries } from "./salaried.js";
 import { compareTerms, offeringTerms } from "./terms.js";
-import { enrollmentOf, round2, Staffing } from "./staffing.js";
+import { enrollmentOf, maxEnrollmentOf, round2, Staffing, } from "./staffing.js";
 /**
  * Calculates the plan year's P&L from a plan's rows. The steps run in the order
  * docs/planning-engine.md gives, each reading only what earlier steps recorded.
  */
 export function computePlan(data) {
+    const output = calculate(data, new Map());
+    for (const row of output.pnl) {
+        if (row.level !== "offering")
+            continue;
+        const offering = data.plan_offerings.find((o) => o.key === row.key);
+        if (offering !== undefined)
+            row.breakeven_enrollment = breakeven(data, offering, row.net_cents);
+    }
+    return output;
+}
+/**
+ * The fewest sailors, from 1 up to the offering's capacity, at which its net after shared costs is
+ * zero or more. Each number is tried in turn, since coaches and boats cost in steps. Recalculating the
+ * whole plan for each would take seconds, so only the offering's own slice is, and whatever lies
+ * outside it, such as its share of shared costs, stays as planned.
+ */
+function breakeven(data, offering, planned) {
+    if (offering.capacity == null)
+        return null;
+    const slice = sliceOf(data, offering);
+    const netAt = (n) => calculate(slice, new Map([[offering.id, n]])).pnl.find((p) => p.level === "offering" && p.key === offering.key)
+        ?.net_cents ?? 0;
+    const outside = planned - netAt(enrollmentOf(offering));
+    for (let n = 1; n <= offering.capacity; n++)
+        if (netAt(n) + outside >= 0)
+            return n;
+    return null;
+}
+/**
+ * The rows that change with an offering's sailors: it, its activities, trips and lines, and its
+ * blocks with the activities that share them. Pools, bonuses and bookings are left out.
+ */
+function sliceOf(data, offering) {
+    const own = data.plan_activities.filter((a) => a.offering_id === offering.id);
+    const blockIds = new Set(own.flatMap((a) => (a.block_id == null ? [] : [a.block_id])));
+    const activities = data.plan_activities.filter((a) => a.offering_id === offering.id || (a.block_id != null && blockIds.has(a.block_id)));
+    const offeringIds = new Set(activities.map((a) => a.offering_id).concat(offering.id));
+    const inBlocks = (rows) => rows.filter((r) => blockIds.has(r.block_id));
+    const onOffering = (rows) => rows.filter((r) => r.cost_center_type === "offering" && r.cost_center_key === offering.key);
+    return {
+        ...data,
+        plan_offerings: data.plan_offerings.filter((o) => offeringIds.has(o.id)),
+        plan_activities: activities,
+        plan_trips: data.plan_trips.filter((t) => t.offering_id === offering.id),
+        plan_activity_blocks: data.plan_activity_blocks.filter((b) => blockIds.has(b.id)),
+        plan_block_staff: inBlocks(data.plan_block_staff),
+        plan_block_boats: inBlocks(data.plan_block_boats),
+        plan_labor_lines: onOffering(data.plan_labor_lines),
+        plan_budget_lines: onOffering(data.plan_budget_lines),
+        plan_salaried_bookings: [],
+        plan_pools: [],
+        plan_bonus_owners: [],
+        plan_bonus_owner_products: [],
+    };
+}
+/** The plan with each offering's expected sailors, or the number `enrollment` gives it instead. */
+function calculate(data, enrollment) {
     const ctx = new Context(data);
-    for (const o of data.plan_offerings)
-        ctx.enrollment.set(o.id, enrollmentOf(o));
+    for (const o of data.plan_offerings) {
+        ctx.enrollment.set(o.id, enrollment.get(o.id) ?? enrollmentOf(o));
+        ctx.maxEnrollment.set(o.id, maxEnrollmentOf(o));
+    }
     checkAreas(ctx);
     const terms = offeringTerms(ctx);
-    const { activities, coaching, doubleBooked } = new Staffing(ctx).run(scheduleActivities(ctx));
+    const { activities, coaching, doubleBooked, holds } = new Staffing(ctx).run(scheduleActivities(ctx));
     countDays(ctx, activities);
     bookRevenue(ctx);
     const booker = new CostCenterBooker(ctx);
@@ -43,7 +102,7 @@ export function computePlan(data) {
     const organization = organizationTotals(ctx, lines);
     return {
         lines,
-        pnl: summarize(ctx, lines, mtdcByOffering, terms),
+        pnl: summarize(ctx, lines, mtdcByOffering, holds, terms),
         organization,
         activities,
         positions: summarizePositions(ctx, coaching, charged, bonusByPosition, doubleBooked),
@@ -183,8 +242,8 @@ function sumLines(ctx) {
         .filter((l) => l.amount_cents !== 0);
 }
 /** Each plan-year offering's P&L, then each product's, then each program area's, then each area's terms. */
-function summarize(ctx, lines, mtdcByOffering, terms) {
-    const pnl = (level, key, own, counts) => {
+function summarize(ctx, lines, mtdcByOffering, holds, terms) {
+    const pnl = (level, key, own, counts, limits = { max_enrollment: null, allocation_holds: null }) => {
         const byAccount = new Map();
         let revenue = 0;
         let expense = 0;
@@ -207,13 +266,15 @@ function summarize(ctx, lines, mtdcByOffering, terms) {
                 .map(([account_id, amount_cents]) => ({ account_id, amount_cents }))
                 .sort((a, b) => a.account_id.localeCompare(b.account_id)),
             ...counts,
+            ...limits,
+            breakeven_enrollment: null,
         };
     };
     const offerings = [...ctx.data.plan_offerings].sort((a, b) => a.key.localeCompare(b.key));
     const offeringPnl = offerings.map((o) => {
         const enrollment = ctx.enrollment.get(o.id) ?? 0;
         const days = ctx.days.get(o.key) ?? 0;
-        return pnl("offering", o.key, lines.filter((l) => l.cost_center_type === "offering" && l.cost_center_key === o.key), { mtdc_cents: Math.round(mtdcByOffering.get(o.key) ?? 0), enrollment, days, sailor_days: enrollment * days });
+        return pnl("offering", o.key, lines.filter((l) => l.cost_center_type === "offering" && l.cost_center_key === o.key), { mtdc_cents: Math.round(mtdcByOffering.get(o.key) ?? 0), enrollment, days, sailor_days: enrollment * days }, { max_enrollment: ctx.maxEnrollment.get(o.id) ?? 0, allocation_holds: holds.get(o.id) ?? null });
     });
     const productIds = new Set(offerings.map((o) => o.product_id));
     for (const l of lines)

package/dist/planning/in-force.d.ts

@@ -0,0 +1,9 @@
+/** A Financial Plan, as far as which one is in force: the date it's active from, if it's active. */
+export interface Activatable {
+    effective_from: string | null;
+}
+/**
+ * The plan in force on `on` (`YYYY-MM-DD`): of one organization's year's Financial Plans, the one with
+ * the latest date on or before it. None before the first one's date.
+ */
+export declare function planInForce<T extends Activatable>(sets: readonly T[], on: string): T | undefined;

package/dist/planning/in-force.js

@@ -0,0 +1,14 @@
+/**
+ * The plan in force on `on` (`YYYY-MM-DD`): of one organization's year's Financial Plans, the one with
+ * the latest date on or before it. None before the first one's date.
+ */
+export function planInForce(sets, on) {
+    let inForce;
+    for (const set of sets) {
+        if (set.effective_from === null || set.effective_from > on)
+            continue;
+        if (inForce === undefined || set.effective_from > inForce.effective_from)
+            inForce = set;
+    }
+    return inForce;
+}

package/dist/planning/index.d.ts

@@ -1,3 +1,5 @@
 export { computePlan, perDay, perSailorDay } from "./engine.ts";
 export type * from "./types.ts";
 export { PROGRAM_PALETTE, programColor } from "./colors.ts";
+export { planInForce } from "./in-force.ts";
+export type { Activatable } from "./in-force.ts";

package/dist/planning/index.js

@@ -1,2 +1,3 @@
 export { computePlan, perDay, perSailorDay } from "./engine.js";
 export { PROGRAM_PALETTE, programColor } from "./colors.js";
+export { planInForce } from "./in-force.js";

package/dist/planning/lines.js

@@ -55,6 +55,29 @@ function checkCostCenter(ctx, type, key, line) {
         ctx.warn("unknown_cost_center", `Line ${line} is charged to ${type.replace("_", " ")} ${key ?? ""}, which isn't in the plan`, line);
     return known;
 }
+/**
+ * Warns about a Program Plan line that moves a cost off its area's programs, for a Plan Admin to
+ * look over before making the plan active (cyc-seattle/platform#251). Only a Plan Admin changes the
+ * Operations Plan, so its lines never get these. Capital charged anywhere but the
+ * organization already has its own warning, `capital_off_org`.
+ */
+function warnCostShift(ctx, line) {
+    if (ctx.planOfVersion.get(line.version_id)?.kind !== "program_area")
+        return;
+    const warn = (message) => ctx.warn("cost_off_programs", message, line.key, { version_id: line.version_id });
+    const org = ctx.data.organization.name;
+    const capital = ctx.accountType(line.account_id) === "asset";
+    if (capital && line.cost_center_type === "org") {
+        warn(`${line.name} is capital, so ${org} pays for it, not this area's programs`);
+    }
+    else if (line.cost_center_type === "org")
+        warn(`${line.name} is charged to ${org}, not to this area's programs`);
+    else if (line.cost_center_type === "pool")
+        warn(`${line.name} is charged to shared costs, which every program area pays`);
+    if (line.in_mtdc === false) {
+        warn(`${line.name} is left out of the split of shared costs, so the other program areas pay more of them`);
+    }
+}
 /**
  * Records the plan year's `plan_budget_lines`. Capital, a line on an asset account, is the
  * organization's: fundraising pays for it, so it never reaches a program area or an offering.
@@ -67,6 +90,7 @@ export function bookBudgetLines(ctx, booker) {
             continue;
         const capital = ctx.accountType(line.account_id) === "asset";
         const onOrg = line.cost_center_type === "org" || capital;
+        warnCostShift(ctx, line);
         if (capital && line.cost_center_type !== "org") {
             ctx.warn("capital_off_org", `${line.name} is capital, so it's charged to ${ctx.data.organization.name}, which pays for all capital`, line.key);
         }
@@ -89,6 +113,7 @@ export function bookLaborLines(ctx, booker) {
     for (const line of ctx.data.plan_labor_lines) {
         if (!checkCostCenter(ctx, line.cost_center_type, line.cost_center_key, line.key))
             continue;
+        warnCostShift(ctx, line);
         const level = levels.get(line.staff_level_key);
         if (level === undefined) {
             ctx.warn("unknown_staff_level", `Labor line ${line.key} has a staff level that isn't in the Operations Plan, so it's left out`, line.key);

package/dist/planning/staffing.d.ts

@@ -18,8 +18,10 @@ export interface DoubleBooked {
     /** Dates it's on two blocks at once. */
     dates: number;
 }
-/** Whole kids: `target_enrollment` if set, otherwise `capacity × fill_rate` rounded. */
+/** Whole kids expected: `target_enrollment` if set, otherwise `capacity × fill_rate` rounded. */
 export declare function enrollmentOf(offering: PlanOffering): number;
+/** The most sailors an offering takes: its `capacity`, or else the sailors expected. */
+export declare function maxEnrollmentOf(offering: PlanOffering): number;
 export declare class Staffing {
     private readonly ctx;
     private readonly warned;
@@ -37,12 +39,20 @@ export declare class Staffing {
     /** Each program's settings, by its product. */
     private programs;
     /**
-     * Warns when a block's sailors are more than its staff or its boats can safely take. Each program's
+     * Warns when a block's sailors, with every offering full, are more than its staff or its boats can
+     * safely take, and records the most sailors of each offering the block can take. Each program's
      * sailors count against its own sailors per coach, and every coach on the block counts, at any
      * staff level or salaried: the ratio is required, a coach's level isn't (cyc-seattle/sail-team#82).
      * Boats count the ones sailors bring.
      */
     private checkCapacity;
+    /**
+     * The coaches a block pays for its expected sailors: Σ (each program's sailors ÷ its sailors per
+     * coach), rounded up, but never more than it's given. Salaried coaches on salary are always paid, so
+     * only the others are cut, each staff row by the same share. When a program has no sailors per
+     * coach, the block pays all it's given.
+     */
+    private coachesExpected;
     /** Books a cost on a block, split among its activities by their offerings' sailors. */
     private book;
     /**
@@ -66,10 +76,12 @@ export declare class Staffing {
         activities: ComputedActivity[];
         coaching: SalariedCoaching[];
         doubleBooked: Map<Id, DoubleBooked>;
+        /** The most sailors each offering id's blocks can take. */
+        holds: Map<Id, number>;
     };
     /**
-     * A trip's coaches each fly and stay; the miles are driven once. Its coaches are the staff on the
-     * block of its busiest travel day.
+     * A trip's coaches each fly and stay; the miles are driven once. Its coaches are the ones its
+     * expected sailors need on the block of its busiest travel day.
      */
     private bookTrips;
 }

package/dist/planning/staffing.js

@@ -1,9 +1,15 @@
-/** Whole kids: `target_enrollment` if set, otherwise `capacity × fill_rate` rounded. */
+/** Whole kids expected: `target_enrollment` if set, otherwise `capacity × fill_rate` rounded. */
 export function enrollmentOf(offering) {
     if (offering.target_enrollment != null)
         return Math.round(offering.target_enrollment);
     return Math.round((offering.capacity ?? 0) * (offering.fill_rate ?? 0));
 }
+/** The most sailors an offering takes: its `capacity`, or else the sailors expected. */
+export function maxEnrollmentOf(offering) {
+    return offering.capacity ?? enrollmentOf(offering);
+}
+/** `n` rounded up, so a share like 5.0000001 boats stays 5. */
+const ceil = (n) => Math.ceil(n - 1e-9);
 function sum(values) {
     let total = 0;
     for (const v of values)
@@ -93,6 +99,7 @@ export class Staffing {
             const byOffering = groupBy(list, (a) => a.offering.id);
             const total = sum([...byOffering.values()].map((own) => enrollment(own[0])));
             const share = (a) => (total > 0 ? enrollment(a) / total : 1 / byOffering.size) / byOffering.get(a.offering.id).length;
+            const most = sum([...byOffering.keys()].map((o) => this.ctx.maxEnrollment.get(o) ?? 0));
             result.set(id, {
                 row,
                 members: list,
@@ -104,6 +111,7 @@ export class Staffing {
                 staff: staff.get(id) ?? [],
                 boats: boats.get(id) ?? [],
                 shares: new Map(list.map((a) => [a, share(a)])),
+                fill: most > 0 ? Math.min(1, total / most) : 1,
             });
         }
         return result;
@@ -127,61 +135,98 @@ export class Staffing {
         return new Map(this.ctx.data.plan_programs.map((p) => [p.product_id, p]));
     }
     /**
-     * Warns when a block's sailors are more than its staff or its boats can safely take. Each program's
+     * Warns when a block's sailors, with every offering full, are more than its staff or its boats can
+     * safely take, and records the most sailors of each offering the block can take. Each program's
      * sailors count against its own sailors per coach, and every coach on the block counts, at any
      * staff level or salaried: the ratio is required, a coach's level isn't (cyc-seattle/sail-team#82).
      * Boats count the ones sailors bring.
      */
-    checkCapacity(block, programs) {
+    checkCapacity(block, programs, holds) {
         const { ctx } = this;
         const offerings = [
             ...new Map(block.members.filter((a) => a.kind !== "travel").map((a) => [a.offering.id, a.offering])).values(),
         ];
-        const sailors = sum(offerings.map((o) => ctx.enrollment.get(o.id) ?? 0));
-        if (sailors <= 0)
-            return;
+        const most = (o) => ctx.maxEnrollment.get(o.id) ?? 0;
+        const sailors = sum(offerings.map(most));
+        const warns = sailors > 0;
         const scope = { version_id: block.row.version_id, date: block.row.date };
-        // The block's offerings, with the verb that agrees with them: "Guppies Week 2 has".
-        const has = `${offeringsOf(block)} ${new Set(block.members.map((a) => a.offering.id)).size > 1 ? "have" : "has"}`;
-        // Coaches the block needs: each program's sailors over its sailors per coach.
-        let load = 0;
-        let counted = 0;
+        // The block's offerings, with the verbs that agree with them: "Guppies Week 2 is for", "has".
+        const several = new Set(block.members.map((a) => a.offering.id)).size > 1;
+        const is = `${offeringsOf(block)} ${several ? "are" : "is"} for up to`;
+        const has = several ? "have" : "has";
+        // Coaches each program's full number of sailors needs.
+        const needs = new Map();
+        const perCoach = new Map();
         for (const o of offerings) {
             const settings = programs.get(o.product_id);
             if (settings?.staff_level_key == null || settings.sailors_per_coach == null || settings.sailors_per_coach <= 0) {
-                this.warnOnce("no_program_settings", `${o.name}'s program has no staff level or sailors per coach. Add both to check that it has enough coaches`, o.product_id, { version_id: o.version_id, date: block.row.date });
+                if (warns) {
+                    this.warnOnce("no_program_settings", `${o.name}'s program has no staff level or sailors per coach. Add both to check that it has enough coaches`, o.product_id, { version_id: o.version_id, date: block.row.date });
+                }
                 continue;
             }
-            const n = ctx.enrollment.get(o.id) ?? 0;
-            load += n / settings.sailors_per_coach;
-            counted += n;
+            needs.set(o.id, most(o) / settings.sailors_per_coach);
+            perCoach.set(o.id, settings.sailors_per_coach);
         }
-        if (counted > 0) {
-            const covered = Math.min(load, sum(block.staff.map((s) => s.count)));
-            if (load > covered + 1e-9) {
-                ctx.warn("over_capacity", covered === 0
-                    ? `${has} ${countOf(counted, "sailor")} and no coach`
-                    : `${has} ${countOf(counted, "sailor")}, but enough coaches for only ${Math.floor((covered * counted) / load + 1e-9)}`, block.row.key, scope);
-            }
+        const coaches = sum(block.staff.map((s) => s.count));
+        const load = sum(needs.values());
+        const counted = sum(offerings.filter((o) => needs.has(o.id)).map(most));
+        if (warns && counted > 0 && load > coaches + 1e-9) {
+            ctx.warn("over_capacity", coaches === 0
+                ? `${is} ${countOf(counted, "sailor")} and ${has} no coach`
+                : `${is} ${countOf(counted, "sailor")}, but ${has} enough coaches for only ${Math.floor((coaches * counted) / load + 1e-9)}`, block.row.key, scope);
         }
-        if (!block.members.some((a) => a.uses_boats))
-            return;
-        const classes = new Map(ctx.data.boat_classes.map((c) => [c.id, c]));
+        const sails = block.members.some((a) => a.uses_boats);
         let seats = 0;
-        for (const b of block.boats) {
-            // A coach boat's class takes 0, without a warning.
-            const perBoat = classes.get(b.boat_class_id)?.max_capacity;
-            if (perBoat == null) {
-                this.warnOnce("no_max_capacity", `${classes.get(b.boat_class_id)?.name ?? b.boat_class_id} has no max capacity. Add it to check that the boats hold every sailor`, b.boat_class_id, scope);
-                continue;
+        if (sails) {
+            const classes = new Map(ctx.data.boat_classes.map((c) => [c.id, c]));
+            for (const b of block.boats) {
+                // A coach boat's class takes 0, without a warning.
+                const perBoat = classes.get(b.boat_class_id)?.max_capacity;
+                if (perBoat == null) {
+                    if (warns) {
+                        this.warnOnce("no_max_capacity", `${classes.get(b.boat_class_id)?.name ?? b.boat_class_id} has no max capacity. Add it to check that the boats hold every sailor`, b.boat_class_id, scope);
+                    }
+                    continue;
+                }
+                seats += (b.count + (b.chartered ?? 0) + (b.sailor_owned ?? 0)) * perBoat;
+            }
+            if (warns && sailors > seats) {
+                ctx.warn("over_capacity", seats === 0
+                    ? `${is} ${countOf(sailors, "sailor")} and ${has} no boats`
+                    : `${is} ${countOf(sailors, "sailor")}, but the boats hold only ${seats}`, block.row.key, scope);
             }
-            seats += (b.count + (b.chartered ?? 0) + (b.sailor_owned ?? 0)) * perBoat;
         }
-        if (sailors > seats) {
-            ctx.warn("over_capacity", seats === 0
-                ? `${has} ${countOf(sailors, "sailor")} and no boats`
-                : `${has} ${countOf(sailors, "sailor")}, but the boats hold only ${seats}`, block.row.key, scope);
+        // What's left for each offering once the others in the block are full.
+        for (const o of offerings) {
+            const own = needs.get(o.id);
+            const byCoaches = own === undefined ? Infinity : Math.floor((coaches - (load - own)) * perCoach.get(o.id) + 1e-9);
+            const byBoats = sails ? seats - (sailors - most(o)) : Infinity;
+            const n = Math.min(byCoaches, byBoats);
+            if (n === Infinity)
+                continue;
+            holds.set(o.id, Math.min(holds.get(o.id) ?? Infinity, Math.max(0, n)));
+        }
+    }
+    /**
+     * The coaches a block pays for its expected sailors: Σ (each program's sailors ÷ its sailors per
+     * coach), rounded up, but never more than it's given. Salaried coaches on salary are always paid, so
+     * only the others are cut, each staff row by the same share. When a program has no sailors per
+     * coach, the block pays all it's given.
+     */
+    coachesExpected(block, programs) {
+        const given = sum(block.staff.map((s) => s.count));
+        const salaried = sum(block.staff.filter((s) => s.position_key != null && s.pay !== "hourly").map((s) => s.count));
+        let load = 0;
+        for (const o of new Map(block.members.map((a) => [a.offering.id, a.offering])).values()) {
+            const perCoach = programs.get(o.product_id)?.sailors_per_coach;
+            if (perCoach == null || perCoach <= 0)
+                return { coaches: given, share: 1 };
+            load += (this.ctx.enrollment.get(o.id) ?? 0) / perCoach;
         }
+        const others = given - salaried;
+        const kept = Math.min(others, Math.max(0, ceil(load) - salaried));
+        return { coaches: salaried + kept, share: others > 0 ? kept / others : 1 };
     }
     /** Books a cost on a block, split among its activities by their offerings' sailors. */
     book(block, account, amount, line, name, explanation, mtdcShare = 1, wages = false) {
@@ -212,7 +257,11 @@ export class Staffing {
         const rates = new Map(ctx.data.plan_boat_rates.map((r) => [r.boat_class_id, r]));
         const classes = new Map(ctx.data.boat_classes.map((c) => [c.id, c]));
         for (const list of groupBy(blocks, (b) => b.row.date).values()) {
-            const chartered = list.flatMap((block) => block.boats.flatMap((b) => ((b.chartered ?? 0) > 0 ? [{ block, id: b.boat_class_id, n: b.chartered }] : [])));
+            const chartered = list.flatMap((block) => block.boats.flatMap((b) => {
+                // The boats the expected sailors use, as for its own boats.
+                const n = ceil((b.chartered ?? 0) * block.fill);
+                return n > 0 ? [{ block, id: b.boat_class_id, n }] : [];
+            }));
             for (const [id, uses] of groupBy(chartered, (c) => c.id)) {
                 const name = classes.get(id)?.name ?? id;
                 const rate = rates.get(id)?.charter_per_day_cents;
@@ -307,9 +356,10 @@ export class Staffing {
         const blocks = this.blocks(scheduled);
         this.checkUnallocated(scheduled, blocks);
         const programs = this.programs();
+        const holds = new Map();
         // By date, so a warning given once names the first date it's seen on.
         for (const block of byDate(blocks))
-            this.checkCapacity(block, programs);
+            this.checkCapacity(block, programs, holds);
         this.checkInventory(byDate(blocks));
         const doubleBooked = this.checkDoubleBooked([...blocks.values()]);
         const coaching = [];
@@ -318,10 +368,13 @@ export class Staffing {
         const boatClasses = new Map(ctx.data.boat_classes.map((c) => [c.id, c]));
         const boatRates = new Map(ctx.data.plan_boat_rates.map((r) => [r.boat_class_id, r]));
         const given = new Map();
+        const tripCoaches = new Map();
         for (const block of byDate(blocks)) {
             const scope = { version_id: block.row.version_id, date: block.row.date };
             const paidHours = block.paid_minutes / 60;
             const waterHours = block.on_water_minutes / 60;
+            const expected = this.coachesExpected(block, programs);
+            tripCoaches.set(block.row.id, expected.coaches);
             const book = (type, amount, line, name, explanation) => this.book(block, ctx.costAccount(type), amount, line, name, explanation, 1, type === "coach_wages");
             let wages = 0;
             for (const s of block.staff) {
@@ -329,8 +382,8 @@ export class Staffing {
                     continue;
                 if (s.position_key != null) {
                     const position = positions.get(s.position_key);
-                    const hours = s.count * paidHours;
                     if (s.pay === "hourly") {
+                        const hours = s.count * expected.share * paidHours;
                         const rate = position?.hourly_coaching_rate_cents;
                         if (position !== undefined && rate == null) {
                             this.warnOnce("no_hourly_rate", `${position.name} is paid by the hour to coach but has no own hourly coaching rate, so those hours cost nothing`, position.key, scope);
@@ -347,6 +400,7 @@ export class Staffing {
                         }
                     }
                     else {
+                        const hours = s.count * paidHours;
                         for (const [a, share] of block.shares) {
                             coaching.push({
                                 position_key: s.position_key,
@@ -364,16 +418,19 @@ export class Staffing {
                     this.warnOnce("unknown_staff_level", `${block.row.name} has staff at a staff level that isn't in the Operations Plan, so they cost nothing`, s.staff_level_key ?? s.key, scope);
                     continue;
                 }
-                if (level.pay_type !== "volunteer")
-                    wages += s.count * paidHours * (level.hourly_rate_cents ?? 0);
+                if (level.pay_type !== "volunteer") {
+                    wages += s.count * expected.share * paidHours * (level.hourly_rate_cents ?? 0);
+                }
             }
-            book("coach_wages", wages, "coach_wages", "Coach wages", "Staff × paid hours × each one's hourly rate");
+            book("coach_wages", wages, "coach_wages", "Coach wages", "Coaches the expected sailors need × paid hours × each one's hourly rate");
             for (const b of block.boats) {
                 const rate = boatRates.get(b.boat_class_id);
                 if (rate === undefined || b.count <= 0 || waterHours <= 0)
                     continue;
                 const boatClass = boatClasses.get(b.boat_class_id);
-                this.book(block, boatClass?.account_id ?? ctx.costAccount("boat_maintenance"), b.count * waterHours * (rate.maintenance_per_boat_hour_cents + (rate.fuel_per_hour_cents ?? 0)), `boats:${b.boat_class_id}`, `Boats: ${boatClass?.name ?? "boats"}`, "The organization's boats × on-water hours × the class's fuel and upkeep");
+                this.book(block, boatClass?.account_id ?? ctx.costAccount("boat_maintenance"), ceil(b.count * block.fill) *
+                    waterHours *
+                    (rate.maintenance_per_boat_hour_cents + (rate.fuel_per_hour_cents ?? 0)), `boats:${b.boat_class_id}`, `Boats: ${boatClass?.name ?? "boats"}`, "The organization's boats the expected sailors use × on-water hours × the class's fuel and upkeep");
             }
             const coaches = sum(block.staff.map((s) => s.count));
             const boats = sum(block.boats.map((b) => b.count + (b.chartered ?? 0)));
@@ -382,10 +439,11 @@ export class Staffing {
             }
         }
         this.bookCharters(byDate(blocks));
-        this.bookTrips(blocks, scheduled);
+        this.bookTrips(blocks, scheduled, tripCoaches);
         return {
             coaching,
             doubleBooked,
+            holds,
             activities: scheduled.map((a) => ({
                 offering_id: a.offering.id,
                 offering_key: a.offering.key,
@@ -403,10 +461,10 @@ export class Staffing {
         };
     }
     /**
-     * A trip's coaches each fly and stay; the miles are driven once. Its coaches are the staff on the
-     * block of its busiest travel day.
+     * A trip's coaches each fly and stay; the miles are driven once. Its coaches are the ones its
+     * expected sailors need on the block of its busiest travel day.
      */
-    bookTrips(blocks, scheduled) {
+    bookTrips(blocks, scheduled, coachesOf) {
         const { ctx } = this;
         for (const trip of ctx.data.plan_trips) {
             const offering = ctx.offeringsById.get(trip.offering_id);
@@ -414,8 +472,9 @@ export class Staffing {
                 continue;
             const travel = (a) => a.kind === "travel" && a.trip?.id === trip.id;
             const staffed = [...blocks.values()].filter((b) => b.members.some(travel));
-            const coaches = Math.max(0, ...staffed.map((b) => sum(b.staff.map((s) => s.count))));
-            if (coaches === 0 && ((trip.airfare_cents ?? 0) > 0 || (trip.nights ?? 0) > 0)) {
+            const coaches = Math.max(0, ...staffed.map((b) => coachesOf.get(b.row.id) ?? 0));
+            const given = Math.max(0, ...staffed.map((b) => sum(b.staff.map((s) => s.count))));
+            if (given === 0 && ((trip.airfare_cents ?? 0) > 0 || (trip.nights ?? 0) > 0)) {
                 const first = scheduled
                     .filter(travel)
                     .map((a) => a.date)

package/dist/planning/types.d.ts

@@ -367,6 +367,19 @@ export interface Pnl extends Totals {
     days: number;
     /** Enrollment × days. */
     sailor_days: number;
+    /** The most sailors an offering takes: its `capacity`, or else its enrollment. Null for a product or area. */
+    max_enrollment: number | null;
+    /**
+     * The most sailors an offering's blocks can take, with every other offering in them full. Null when
+     * it's in no block that limits it, and for a product or area.
+     */
+    allocation_holds: number | null;
+    /**
+     * The fewest sailors, from 1 up to its capacity, at which an offering's net after shared costs is
+     * zero or more, with its share of shared costs as planned. Null when it isn't, even when full, when
+     * it has no capacity, and for a product or area.
+     */
+    breakeven_enrollment: number | null;
 }
 /** An activity with the staffing the engine gave it. */
 export interface ComputedActivity {

package/dist/schema/index.d.ts

@@ -882,6 +882,10 @@ export interface PlanResultPnl {
     term_name: string | null;
     /** The term's first day, which puts the terms in order. */
     term_starts_on: string | null;
+    /** The most sailors an offering's blocks can take, with every other offering in them full. Empty for a product or program area. */
+    allocation_holds: number | null;
+    /** The fewest sailors, up to its capacity, at which an offering pays for itself, with its share of shared costs as planned. Empty when it doesn't even when full, and for a product or program area. */
+    breakeven_enrollment: number | null;
 }
 /** Each salaried position's pay for the year, in a Financial Plan. 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 PlanResultPositions {
@@ -1242,8 +1246,8 @@ export interface VersionSets {
     name: string;
     /** What it was for, such as "Reviewed with the board". You can change it after it's saved. */
     message: string | null;
-    /** Set it to saved to save the Financial Plan and all its plans. A saved Financial Plan never changes, apart from its name and note. Set a saved one to active to make it the one its organization runs for the year, which sets the one active before it back to saved. */
-    status: "draft" | "saved" | "active";
+    /** Set it to saved to save the Financial Plan and all its plans. A saved Financial Plan never changes, apart from its name, its note, the date it's active from, and whether it's archived. */
+    status: "draft" | "saved";
     /** The Financial Plan this one started as a copy of. Pick it when you add this one, and its plans are copied in. */
     parent_id: string | VersionSets | null;
     /** Set when the Financial Plan is saved. */
@@ -1252,7 +1256,9 @@ 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. */
+    /** The day the Financial Plan is in force from. Leave it empty for one that isn't active. On any day, the plan in force is the one for the year with the latest date on or before that day. A draft can be active. No two Financial Plans for a year can share a date. */
+    effective_from: string | null;
+    /** Set when the Financial Plan is archived, which hides it from Planning's list. Clear it to bring the plan back. The plan in force 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)[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyc-seattle/platform",
-  "version": "1.52.0",
+  "version": "1.54.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",
@@ -81,6 +81,7 @@
     "@types/js-yaml": "4.0.9",
     "@types/luxon": "^3.7.6",
     "@types/node": "^22.19.1",
+    "commander": "13.1.0",
     "esbuild": "0.28.2",
     "eslint": "^9.39.5",
     "google-auth-library": "^11.3.0",