SPEC-ECON-003: Economic Engine Calculation and Reference Specification

1. Purpose

This specification is the single canonical technical source for the Economic Engine’s calculations, reference values, and unified CWI Helper presentation contract.

The Economic Engine exists to remove pricing guesswork from classroom economy setup by deriving coherent numbers from class context instead of requiring teachers to invent them manually.

This document defines the canonical calculations, ratios, bands, and constraints used by the engine.

2. Scope

This specification governs:

• CWI derivation,
• policy-mode ratio bands,
• Store economic-role reference bands,
• weekly savings targets,
• interest doubling-time constraints,
• interest-growth formulas,
• the insurance premium pricing envelope and the separation of premium pricing (economic-mode axis) from coverage contract (insurance-tier axis) for the three canonical insurance products,
• economic solvency and coherence checks,
• deterministic reference values used by the engine.
• the unified teacher-facing CWI Helper information and consequence primitives for every pricing surface.

V2 deliberately retains weekly CWI, Tight/Default/Comfortable modes, the existing insurance period semantics, and the interest doubling-time model. Store Basic/Standard/Premium/Luxury price tiers are replaced in v2 by the three economic roles defined in § 4.7. Dynamic economic cycles, cycle-relative CWI, survivability-first modeling, replacement Store roles, removal of Economic Modes, and predictive student-behavior modeling are deferred to v2.5 and are not introduced by this revision.

This specification does NOT govern:

• class identity,
• class existence,
• policy lineage,
• FEAT orchestration,
• ledger posting,
• execution timing,
• or feature activation mechanics.

Those responsibilities remain with the relevant DOM-*, SPEC-*, and FEAT-* documents.

3. Governing Authority

This specification is subordinate to:

• INV-CORE-000
• INV-CORE-001
• INV-ARC-009
• INV-ARC-015
• DOM-CORE-001
• DOM-CLASS-001
• DOM-CLASS-002
• DOM-CLASS-003
• SPEC-ECON-001
• SPEC-ECON-002

This specification is authoritative over:

• the Economic Engine’s calculation model,
• the canonical economic reference values,
• the banding rules used for class-economic recommendations,
• the derivation constraints for teacher-facing output.

4. Core Calculations

4.1 Classroom Wage Index

The Classroom Wage Index (CWI) is the base weekly economic reference for a class.

CWI SHALL be derived from expected weekly earning capacity.

Canonical definition:

CWI = hourly_pay_rate × expected_weekly_hours

Where:

• hourly_pay_rate is the canonical pay rate for the class configuration.
• expected_weekly_hours is the expected number of earning hours available in a typical week.

CWI is the normalization base for all ratio-based economic outputs in this specification.

4.2 Weekly Savings Target

The engine SHALL provide a canonical weekly savings target as a percentage of CWI.

Formula:

weekly_savings_target = CWI × savings_rate

4.3 Weekly Rent

The engine SHALL provide a canonical weekly rent band as a percentage of CWI.

Formula:

weekly_rent = CWI × rent_rate

with rent_rate constrained to the mode-specific band.

4.4 Insurance

Insurance is not a single product. FEAT-STOR-003 defines three canonical insurance products, each with a distinct claim lifecycle and therefore a distinct economic reference model:

• TRANSACTION
• PRODUCTIVITY
• NON_MONETARY

This section is referenced to FEAT-STOR-003 only to establish why the Economic Engine must model these three products separately. FEAT-STOR-003 remains authoritative over claim submission, validation, approval, and compensation execution. This specification is authoritative only over the CWI-relative economic reference values used to price and bound insurance.

4.4.1 Two Independent Axes

Insurance economics are governed by two axes that MUST be kept separate:

1. Insurance tier (coverage axis). For products that use tiers, Basic, Mid, and Premium define the insurance contract / benefit — what the policy covers and its coverage limits. Tier is the coverage axis.

2. Economic policy mode (pricing axis). tight, default, and comfortable affect the recommended premium — what the coverage costs. Economic mode is the pricing axis.

Axis-separation rule (normative). Economic mode governs pricing recommendations only. Product and tier configuration govern coverage parameters only. Economic mode MUST NOT silently change any configured coverage parameter — reimbursement percentage, payout multiple, claim allowance, maximum claimed basis, waiting period, or coverage boundary. For example, if a Premium PRODUCTIVITY definition reimburses X% of validated lost wages, X% is identical in tight, default, and comfortable.

Derived monetary exposure is not a coverage parameter. For monetary products whose ceiling is derived as maximum_policy_payout = premium × payout_multiple, economic mode legitimately changes the resulting dollar ceiling because it changed the premium, which is an economic input. This is intentional and is not a violation of the axis-separation rule. What mode MUST NOT change is the configured payout_multiple (or reimbursement %, claim allowance, etc.) itself. Consequently, this specification does not claim that a given tier yields the same dollar benefit across modes — only the same coverage parameters.

Depending on product type, tier-controlled (coverage-axis) values MAY include:

• reimbursement percentage;
• payout multiple (where the ceiling is derived as premium × payout_multiple);
• claim allowance;
• maximum claim basis;
• maximum payout;
• waiting period;
• other product-specific coverage limits.

The exact numerical coverage values for each tier are defined per product in the canonical preset tables (§ 4.4.3–§ 4.4.5), selected deterministically per § 4.4.8. Implementations MUST source them from this document and MUST NOT invent or override them.

4.4.2 Premium Pricing Envelope (economic-mode axis)

The engine SHALL price insurance premiums CWI-relative, within the canonical mode-specific premium envelope:

These bands are the recommended pricing envelope for insurance premium recommendations across all three products and all tiers. Teachers MAY configure a premium outside the recommended band; the band is engine guidance, not a hard cap.

Constraints on premium derivation:

• premium pricing MUST be CWI-relative;
• economic mode determines the lawful/recommended premium envelope;
• product and tier coverage determine the benefit contract, never the premium envelope;
• the recommended premium MUST be deterministic;
• the premium is an economic input that MAY, for monetary products, feed a derived payout ceiling (maximum_policy_payout = premium × payout_multiple).

The envelope is not independently immutable. It is contingent on the coverage models it prices, and it MUST be re-evaluated as each product’s coverage economics are settled:

• PRODUCTIVITY — coverage model is now sufficiently settled (§ 4.4.4) that the envelope can be tested against real exposure. The hard weekly boundaries in § 4.4.4 bound exposure independently of the premium.
• TRANSACTION — coverage economics remain unresolved (§ 4.4.3); the envelope is provisional for this product until they are settled.
• NON_MONETARY — the envelope is affordability guidance only, not an exposure-based price (§ 4.4.5).

The deterministic premium-selection rule for the canonical presets is defined in § 4.4.8. No risk_factor, premium = liability × risk_factor, or equivalent exposure-multiplier formula is canonical under this specification; the preset premium is selected directly from the mode band by tier (band bottom / midpoint / top).

Coverage period normalization (all period-priced products). The premium envelope above is expressed per canonical week. When a policy’s coverage period is longer than one week, period-level economic values scale by the actual duration of the coverage interval, not by a fixed constant.

Monthly coverage MUST NOT be defined as a fixed 4-week economic period. A monthly policy runs from one canonical renewal boundary to the next; its economic week-equivalent is derived from the actual number of class-local calendar days in that interval:

coverage_week_equivalent = covered_class_local_calendar_days / 7

The coverage interval is half-open: [coverage_start, next_renewal). The start day is covered; the next renewal boundary belongs to the following cycle and is not double-counted. For the Aug 25 → Sep 25 example this yields 31 covered class-local calendar days (Aug 25 through Sep 24 inclusive), with Sep 25 opening the next cycle.

Weekly coverage has a coverage_week_equivalent of exactly 1.

Period-normalized values then derive from the actual duration, e.g.:

period_allowance      = ceil(weekly_allowance × coverage_week_equivalent)   # § 4.4.8
maximum_policy_payout = period_premium × payout_multiple      # where applicable

Example: a policy renewing August 25 → September 25 covers 31 class-local days, so coverage_week_equivalent = 31 / 7 ≈ 4.4286.

The premium is the exception. The premium charged for each billing period is the frozen contractual amount of the purchased policy version. It does not scale with the number of days in any particular period: a monthly policy charges the same premium for a 28-day period and a 31-day period, as a real insurance contract does. period_premium in the formulas of this section denotes that frozen per-period premium. The per-week envelope and coverage_week_equivalent inform the Economic Engine Helper’s premium recommendation while a policy is being authored (§ 4.9); once authored, the premium is fixed for every period of that policy version.

Covered-day derivation and renewal boundaries MUST use canonical class-local temporal resolution — never elapsed seconds — so that DST or timezone transitions do not distort the economic period.

The upcoming renewal period MUST be calculable before renewal. Student-facing insurance UI SHALL surface the next coverage interval, the next premium, and other derived renewal values ahead of the charge so students can plan for renewal.

4.4.3 TRANSACTION Insurance

TRANSACTION insurance reimburses part of a single posted Ledger transaction. Consistent with FEAT-STOR-003, one claim covers exactly one canonical Ledger transaction. Its monetary model mirrors PRODUCTIVITY: reimbursement is a percentage of the covered transaction loss, the period ceiling is period_premium × payout_multiple, and premiums are selected from the mode band per § 4.4.8.

Canonical preset values (per week-equivalent; scale monthly per § 4.4.2):

Eligibility hard contract (non-overridable). Independent of the tier/coverage values, a TRANSACTION claim is eligible only when the referenced transaction is:

• a negative (debit) transaction;
• inside the configured filing window;
• not on CTH’s global disallowed list;
• not previously claimed;
• not obligation-related;
• not collective-goal-related;
• not a transfer;
• and, when item-related, tied to an item/entitlement that was actually purchased and used, but not revoked or expired.

These are mechanical eligibility gates only; the teacher retains approval authority per FEAT-STOR-003.

4.4.4 PRODUCTIVITY Insurance

PRODUCTIVITY is the canonical product name for attendance / lost-wage insurance.

Its purpose is to reimburse some portion of wages the covered student could potentially have earned on eligible class-local dates where the student had no clock-in / productivity session. It compensates the economic consequence of lost productivity; it does not assert that the student actually worked the claimed hours.

Intended claim model (economic reference view; execution semantics remain in FEAT-STOR-003):

1. Student selects an otherwise eligible class-local date with no clock-in / productivity session.
2. Student enters the number of hours being claimed for that date.
3. Backend validates the claim against the configured insurance contract and authoritative Productivity / Payroll facts.
4. The teacher retains approval / rejection authority as defined by FEAT-STOR-003.
5. Approval compensates through the canonical MANUAL_CREDIT lifecycle.
6. Historical attendance, productivity sessions, worked minutes, and ordinary payroll remain unchanged.

Loss and reimbursement basis. CTH does not derive a daily wage and does not divide CWI across an assumed number of school days. Validated loss is computed directly from the student’s own claimed hours:

validated_claimed_loss = validated_claimed_hours × hourly_pay_rate
reimbursement          = validated_claimed_loss × reimbursement_percentage

Payout ceiling. The policy’s payout ceiling is derived from the premium:

maximum_policy_payout = premium × payout_multiple

Effective payout (period capacity is the monetary ceiling). A single approval’s actual payout is bounded by the insurance-contract period ceiling:

actual_payout = min(
    gross_reimbursement,               # validated_claimed_loss × reimbursement_percentage
    remaining_period_payout_capacity   # insurance-contract ceiling (period)
)

The period capacity is the insurance-contract ceiling (derived from maximum_policy_payout, period-normalized per § 4.4.2) and is the monetary ceiling on any single approval’s payout. Approval-time payout bounding — including the two-resource rule (remaining claim allowance and remaining period payout capacity) — is execution semantics owned by FEAT-STOR-003 per the scope boundary in § 4.4; this specification states the CWI-relative economic reference values only and does not impose an additional approval-time weekly payout clamp.

Engine-recommended, teacher-configurable. The Engine recommends ranges for the reimbursement percentage, payout multiple, premium, and other applicable limits. Teachers MAY configure values outside the recommended ranges.

Economic-coherence guidance (advisory). The following are CWI-relative economic reference comparisons. They are advisory guidance — surfaced to inform the teacher and the student, not enforced as approval-time or submission-time denials by this specification:

• comparing total_validated_PRODUCTIVITY_claimed_hours_week against expected_weekly_hours within a canonical class-local week yields a non-blocking guidance signal when exceeded;
• comparing cumulative PRODUCTIVITY payout against CWI within a canonical class-local week is an economic-coherence reference, not a payout clamp;
• unused weekly guidance capacity does not carry forward.

The mechanical submission-time hours ceiling is the configured daily payroll limit, applied at submission per FEAT-STOR-003. The monetary ceiling on payout is the remaining period payout capacity (above). The expected_weekly_hours / CWI comparisons above do not add a further mechanical cap.

Actual worked hours do NOT invalidate a claim. expected_weekly_hours is an Economic Engine input and economic-coherence guidance. It is not proof that a student could not have earned additional hours in a given week. CTH SHALL NOT automatically compute actual_worked_hours + claimed_lost_hours <= expected_weekly_hours and reject or reduce a claim on that basis. The weekly comparison against expected_weekly_hours is advisory guidance surfaced to the deciding teacher, not a mechanical cap; recorded worked hours are separate authoritative facts that inform adjudication.

Example: a student with 4 recorded worked hours this week, expected_weekly_hours = 5, who selects an eligible no-session date and claims 3 lost hours, MUST NOT be auto-rejected merely because 4 + 3 > 5. Instead CTH surfaces authoritative context to the deciding teacher — claimed lost hours, recorded worked hours for the canonical week, configured expected_weekly_hours, requested/derived reimbursement, and applicable policy limits — and the teacher decides whether the counterfactual lost-hour claim is credible. This is consistent with the lifecycle rule that mechanical eligibility lets a claim be considered but never mandates approval. CTH enforces objective limits and surfaces evidence; it does not convert an economic modeling input into an automated judgment about whether the claimed lost opportunity actually existed.

Coverage period. Coverage may be weekly or monthly. Monthly period pricing follows the week-equivalent normalization in § 4.4.2. A monthly policy’s total ceiling is expected to exceed 1× CWI because the interval spans multiple week-equivalents; this is valid. The weekly economic-coherence guidance above is evaluated independently within each canonical class-local week — a larger monthly ceiling does not change the per-week expected_weekly_hours or weekly CWI reference comparisons, which remain advisory in any individual week.

Tiering is optional. A teacher MAY offer a single PRODUCTIVITY configuration or a Basic / Mid / Premium set. payout_multiple belongs exclusively to the product/tier coverage axis: a single offering configures one multiple; a tiered offering gives each tier its own recommended/configured multiple. Economic mode SHALL NOT derive, alter, or select payout_multiple. Economic mode affects only the premium recommendation; the derived monetary ceiling (premium × payout_multiple) may therefore change with mode because the premium changed — this is intentional and is not a change to the coverage parameter.

Recommendation coherence. The Engine SHOULD avoid internally nonsensical recommendations, distinguishing the policy-period ceiling from the weekly CWI economic reference:

• Weekly coverage — a recommended premium/multiple combination SHOULD NOT normally imply a policy ceiling above the weekly CWI payout reference.
• Monthly coverage — a total ceiling above 1× CWI is expected and valid; the weekly CWI reference is still evaluated independently inside the period.

Teachers MAY configure outside Engine recommendations. If a teacher’s selected premium/multiple yields a nominal policy ceiling above what the remaining period payout capacity could actually pay, CTH MUST NOT silently rewrite the configuration; it MUST surface both the calculated dollar policy ceiling and the applicable weekly CWI reference clearly.

Canonical preset values (per week-equivalent; scale monthly per § 4.4.2):

premium × payout_multiple yields the period ceiling; a single approval’s payout is bounded by the remaining period payout capacity (actual_payout above), and submission is bounded by the configured daily payroll limit and remaining claim allowance per FEAT-STOR-003. The weekly 1 CWI and expected_weekly_hours figures are advisory economic-coherence guidance, not mechanical caps. These preset values are settled; only the monthly allowance rounding convention was flagged for confirmation and is fixed in § 4.4.8.

4.4.5 NON_MONETARY Insurance

NON_MONETARY is the external-benefit insurance product. CTH records the lawful claim decision but does not own, price the reimbursement of, or verify the external benefit itself.

Premium band is affordability guidance only. Because this product has no economic payout and CTH cannot value the external benefit, the generic CWI-relative premium envelope of § 4.4.2 is applied here as affordability guidance, not as an exposure-based price. The Engine’s recommendation is of the form:

Suggested premium: $X–$Y based on your configured class economy. Because this benefit occurs outside CTH, CTH cannot estimate its monetary value. Consider the value of the external benefit when selecting the final premium.

The teacher remains free to set the premium outside that recommendation.

Mechanically governable contract. CTH MAY govern only what it can actually enforce:

• premium;
• weekly or monthly coverage period;
• claim allowance;
• timing / waiting restrictions where applicable;
• the teacher-defined external benefit descriptor.

NON_MONETARY MUST have no:

• reimbursement percentage;
• payout multiple;
• monetary payout ceiling;
• actuarial / risk calculation.

Canonical preset values (per week-equivalent; scale monthly per § 4.4.2):

The premium figures are affordability guidance, not calculated fair value; CTH cannot value the external benefit. The Single column uses the mode-band midpoint (equivalent to Mid) per § 4.4.8. All other coverage numbers here are mechanical limits only.

4.4.6 Resolution Status

As of v1.2 the insurance economic model is numerically complete. The canonical preset tables for all three products (§ 4.4.3, § 4.4.4, § 4.4.5), the deterministic premium-selection rule, and the monthly allowance rounding convention (§ 4.4.8) are settled.

No insurance numerical value remains intentionally TBD. Any future change to these values is a normative amendment to this specification, not an implementation choice. Implementations MUST source these values from this document and MUST NOT invent or override them in code.

4.4.7 Presentation of Economic Values

CWI percentages and multiples are the Engine’s internal normalization and calculation mechanism. Teacher-facing surfaces SHALL present the consequences of a configuration primarily in classroom currency, with CWI-relative figures as secondary context.

For example, given a $40 premium and a teacher-selected 7× payout multiple, the surface SHALL present $280 maximum policy payout as the primary result, and MAY show 56% CWI as secondary context. This presentation rule does not change any calculation; it governs how results are displayed.

4.4.8 Deterministic Premium Selection and Period Scaling

For the canonical presets, the premium is selected directly from the mode band by tier — no risk_factor or exposure-multiplier formula is used:

• Basic → bottom of the mode premium band;
• Mid → midpoint of the mode premium band;
• Premium → top of the mode premium band;
• Single → midpoint (equivalent to Mid).

recommended_premium_rate(mode, tier) ∈ { band_lower_bound, band_midpoint, band_upper_bound }

coverage_week_equivalent = covered_class_local_calendar_days / 7   # half-open [start, next_renewal)

period_premium = CWI × recommended_premium_rate × coverage_week_equivalent

This is the Helper’s premium recommendation while a policy is authored. The teacher’s authored premium is then frozen with the policy version and charged unchanged for every billing period, whatever that period’s length (§ 4.4.2).

Monthly authoring normalization. No concrete period exists while a monthly policy is authored, so the recommendation uses a fixed normalization of 30 class-local calendar days: coverage_week_equivalent = 30 / 7 for a MONTHLY recommendation. This constant applies to authoring recommendations only. It never defines a billing period (periods come from anchored recurrence, SPEC-TIME-001 § IX.12), and it never replaces the actual covered-day count used for claim allowances and payout-period scaling.

For monetary products (TRANSACTION, PRODUCTIVITY):

maximum_policy_payout = period_premium × payout_multiple

Allowance rounding (settled). Integer per-period allowances (claims per week-equivalent, claimable days per week-equivalent) scale to the coverage interval by rounding up:

period_allowance = ceil(weekly_allowance × coverage_week_equivalent)

ceil is chosen deliberately: it keeps monthly allowances at least proportional to the weekly value, and — because every individual approval is still bounded by the remaining period payout capacity (§ 4.4.4) — a slightly generous claim count cannot inflate total economic exposure. Rounding governs how many separate claims may be filed, never how much may be paid.

4.5 Fines

The engine SHALL provide a canonical fine band as a percentage of CWI.

Formula:

fine = CWI × fine_rate

4.5.1 Internal Fines

Fines such as overdraft or non-sufficient funds (NSF) fees and late fees shall use the same formula as generic classroom fines recommendations — fine = CWI × rate. These recommendations shall surface the recommended price range of the fines, not a single recommended price.

An internal fine may be configured in one of two shapes, and the two are priced against different reference sets:

• Flat. Persisted as flat_overdraft_fee. A flat internal fee is an ordinary fine and SHALL be recommended against the generic fine band of § 4.5.
• Progressive. Persisted as the precomputed progressive_overdraft_fee JSON object, using the escalating schedule below.

Economic engine table shall persist the chosen overdraft fee under flat_overdraft_fee or persist the precomputed progressive_overdraft_fee as json object with the following fine schedule

This progressive schedule is a self-contained reference set, not a subdivision of the § 4.5 generic fine band. Its purpose is escalation across repeat occurrences, so its upper tiers are expected to sit above the generic band’s ceiling and its first tier may sit below the generic band’s floor. Implementations MUST NOT clamp, rescale, or validate the progressive tiers against the § 4.5 band, and MUST NOT raise an out-of-band finding for a progressive tier that falls outside it. The § 8 instruction that system-defined fines reference the canonical table applies to the flat shape; the progressive shape is governed by this table.

The two schedules also order the economic modes differently, and this is deliberate. The generic band of § 4.5 rises from tight to comfortable alongside rent and the savings target. The progressive schedule instead escalates hardest under tight, because repeat-occurrence pressure is the lever a leaner economy uses. A mode that carries a lower generic fine band may therefore carry a higher tier-3 internal fee.

Internal fines are only active if their value is not NULL for the economic policy being enforced. When disabling fines, the backend shall create a new economic policy with the value set to NULL

4.5.1.1 Overdraft / NSF Fee Applicability

No overdraft or non-sufficient-funds (NSF) fee is assessed (owner ruling 2026-10-07; DOM-OBL-001 3.3 §II.C). A payment toward an existing obligation (e.g. rent, insurance premium) that cannot be covered by the seat’s spendable funds leaves the obligation unpaid: it remains owed, accumulates with later assessments, and is subject to late fees under its own policy. An NSF fee was never an obligation: it is a Ledger fee, a side effect of a negative balance, and a historical one may be reversed like any other fee (DOM-OBL-001 §II.C).

The rest of §4.5.1.1 (the fee’s scope, amount and recording) and the economic engine’s overdraft-fee settings describe the retired fee and are superseded by the paragraph above; they are removed in the next revision of this specification. §4.5.1.1A (charge and deduction funding, including overdraft protection) is unaffected.

A Store purchase is not charged an NSF fee (owner ruling 2026-10-07). A purchase requires sufficient funds: when checking, together with any full overdraft-protection transfer under §4.5.1.1A, does not cover it, the Store refuses it before anything posts (FEAT-STOR-001 §VI.E). No agreement was formed, so there is no failed agreement and no fee, as a declined card purchase costs nothing.

An NSF fee SHALL NOT be charged for:

• Transfers — a transfer is a lateral movement between the seat’s OWN accounts (e.g. checking↔savings). It is not spending and not an agreement. On insufficient funds a transfer is simply invalid: it does not proceed and incurs no fee.
• Penalties — a teacher-applied deduction (an admin adjustment / fine) is itself a penalty, neither a purchase nor an obligation. A penalty cannot generate a fine; it posts as a direct debit (settling below zero if the balance cannot cover it), after applying the shared protection rule of §4.5.1.1A. Savings eligibility for funding and fee applicability are separate decisions.
• Payroll corrections — interval or residual recovery is a separately authorized corrective debit, not a failed agreement. It incurs no NSF fee and creates no obligation or deferred deduction.

Fee amount (authority): the teacher sets the fee amount. The Economic Engine does not determine it; per §4.5.1 the CWI helper surfaces a CWI-normed recommended range for the teacher’s reference (not a single value) and displays a warning when the chosen amount falls outside that range. The teacher’s chosen value is persisted on the engine (flat_overdraft_fee / progressive_overdraft_fee); when a fee is charged, the Ledger posts that teacher-set amount.

Recording and layering (informative): the Ledger posts the fee debit and stays domain-blind (DOM-LED-001 §II). Because the NSF fee is a fine, it is also an obligation (DOM-OBL-001 §II.C, immediate charge), recorded by the originating business FEAT’s cross-domain orchestration — never by the Ledger resolution primitive. This resolves the overdraft/NSF ownership question previously open in DOM-ITR-001 §XIII.c.

4.5.1.1A Universal Charge and Deduction Funding

This technical rule is explicitly incorporated by DOM-CLASS-001 §X, DOM-CLASS-002 §VII, and FEAT-LED-000 §XI.5, deriving from INV-CORE-000 §III.3, INV-ARC-009 §V and INV-ARC-021 §V, VII. It applies to every independently authorized checking charge or deduction, including purchases, obligation payments, penalties, fees and payroll corrections. It does not itself authorize the underlying business action.

For integer-cent checking balance B, savings balance S, and a lawful debit D > 0, define shortfall = max(0, D - B). When protection is enabled, shortfall > 0, and savings can cover the entire shortfall (S >= shortfall), the resolved plan transfers exactly shortfall cents from savings to checking and applies the debit atomically. Otherwise it transfers nothing, leaves savings untouched and applies the debit to checking, which may become negative. Partial savings sweeps are prohibited. Resolution uses current authoritative available balances while holding the seat serialization lock through posting.

Own-account transfers are excluded: insufficient source funds deny the transfer, with no protection transfer or fee. A Store purchase is eligible only when this rule leaves checking at or above zero (FEAT-STOR-001 §VI.E); a purchase never takes the “applies the debit to checking, which may become negative” branch. Fee applicability remains the separate failed-agreement test in §4.5.1.1. Funding an NSF fee does not generate another NSF fee. A payroll correction always has zero NSF fee and cannot generate an obligation, deferred debt or future deduction.

All funding legs and the charge commit or roll back together. This revision supersedes the prior penalty-specific savings exclusion; penalties still cannot generate NSF fees. The originating FEAT records any independently authorized failed-agreement obligation through its owning domain commands, never through Ledger resolution. No existing fee amount or interest formula changes.

4.6 Collective Goals

The engine SHALL provide a canonical collective-goal band as a multiple of CWI.

Formula:

collective_goal = CWI × goal_multiple

4.7 Store Economic Roles

Store products MUST select exactly one economic role. Roles describe the intended economic meaning of a purchase; they do not force a price and do not silently reclassify a teacher’s choice.

The v2 roles replace Basic/Standard/Premium/Luxury. Their reference bands are non-overlapping and are advisory, not enforcement boundaries:

The teacher-configured price remains authoritative. A price outside the selected role’s reference band MUST remain valid unless another authority prohibits it; the Helper reports the position and consequence without reclassifying the product.

The price calculation is not derived from the role:

store_price_share = store_price / CWI

The Helper MUST show one, two, three, or teacher-selected purchase scenarios. Multipacks remain one Store unit under existing Store semantics. Scenarios MUST NOT predict student behavior.

The economic role carries no purchase authority. When overdue-rent Store gating is enabled, the product’s own available_with_overdue_obligations flag decides access, per SPEC-STORE-001 §IV.D; DOM-STORE-001 §XII, which outranks this specification on Store entitlement authority, makes the role configuration guidance only. Necessity is the role a teacher SHOULD select for a product they also mark essential, and the Helper MAY report a mismatch between the two as guidance; selecting Necessity MUST NOT grant the exemption, and selecting Convenience or Add-on MUST NOT withhold it.

4.8 Economy Pricing Rebalance Review

The Economic Engine MAY present one coordinated review of teacher-configured prices across Rent, Store products, Insurance premiums, and Fines/Fees. This is a review and orchestration surface, not a new owner of those policies.

class_id
  -> resolve latest effective policy for each priced feature
  -> calculate each feature's canonical CWI/range constraint
  -> show only out-of-range configured prices
  -> teacher selects midpoint or enters a bounded custom amount
  -> owning FEAT validates and supersedes that feature's policy/version
  -> historical facts remain bound to their original policy/version

Each row MUST identify its owning settings page and MUST use that domain’s canonical validator. A midpoint is a proposed value, never an implicit write; custom values MUST remain within the owning feature’s permitted range unless the teacher explicitly uses the feature’s documented bypass/configuration path. The review MUST be idempotent, class-scoped, append-only, and atomic per selected feature. A failure in one selected feature MUST NOT partially rewrite another feature’s history.

4.9 Unified CWI Helper contract

Every teacher-facing pricing or economic surface MUST answer the same questions: what is configured, how large is it relative to current earning capacity, where it sits relative to reference guidance, and what consequence follows from that value. Currency is primary; CWI notation is secondary.

For every monetary value, the Helper MUST expose:

1. configured amount in classroom currency;
2. current CWI in classroom currency;
3. configured amount as a CWI share;
4. canonical reference range in currency and CWI terms;
5. position relative to the reference (below, within, or above);
6. the applicable surface-specific consequence.

Reference bands are advisory. Being inside a band MUST NOT be presented as proof of affordability or appropriateness, and an out-of-band value MUST still receive the same consequence calculation.

The only canonical consequence primitives are:

The Helper MUST label scenarios as modeled scenarios and MUST NOT predict student behavior. Its surface mapping is normative:

For Collective Goals, price is per participating student. The participant threshold is a separate coordination condition and MUST NOT divide the price. Savings-horizon results MUST be expressed as modeled contributing cycles, not a prediction of elapsed completion time. Savings is reserved wealth, not consumption.

For monetary Insurance, the Helper MUST show both liquidity cost and protection:

maximum_policy_payout = premium × payout_multiple

For NON_MONETARY Insurance, CTH MUST NOT assign a monetary value to the external benefit. Rebalance MUST remain review-only where changing premium changes downstream payout, and MUST route the teacher to Insurance Management.

5. Interest Calculations

5.1 Purpose of Interest Constraints

Interest MUST remain meaningful without becoming a passive-income money printer.

The canonical constraint is not an arbitrary APY cap. It is a minimum doubling-time rule.

5.2 Doubling-Time Rule

The engine SHALL enforce the following minimum doubling times:

Interest rates and compounding settings MUST NOT allow savings to double faster than the configured mode permits.

5.3 Compound Growth Formula

Canonical compound growth:

A = P × (1 + r/n)^(n×t)

Where:

• A is the future amount,
• P is the principal,
• r is the annual rate,
• n is the compounding frequency per year,
• t is time in years.

5.4 Doubling-Time Rearrangement

To calculate the maximum lawful rate for a given doubling-time target:

2 = (1 + r/n)^(n×t)

Therefore:

r = n × (2^(1/(n×t)) - 1)

Where:

• t is the minimum allowed doubling time in years,
• n is the compounding frequency per year.

5.5 Daily Accrual

For daily accrual, the engine SHALL use a daily rate derived from the annual rate.

Canonical form:

daily_accrual = eligible_balance × (APR / 365)

Equivalent formulations MAY be used only if they are mathematically identical and deterministic.

5.6 Compound Frequency Persistence

The EconomicEngine.compound_frequency field persists the compound frequency choice per SPEC-ECON-001 § 6.1.

Supported values:

Implementations that consume this field MUST validate against the persisted enum constraint:

CHECK (compound_frequency IS NULL OR compound_frequency IN ('never', 'daily', 'weekly', 'monthly'))

6. Normalization Rules

6.1 Weekly Basis

All ratio comparisons in this specification SHALL normalize to a weekly comparison basis unless explicitly stated otherwise.

6.2 Class-Relative Comparison

All values SHALL be derived relative to CWI.

Absolute economy values with no class-relative basis are prohibited as canonical reference values.

7. Economic Coherence Rules

7.1 Relational Values

The engine MUST keep values proportional to one another.

Examples:

• rent must not be so high that routine savings become impossible,
• Store role references must remain distinct and non-overlapping,
• insurance must create a meaningful tradeoff,
• goals must require sustained effort,
• interest must reward savings without overtaking labor as the dominant money source.

7.2 Rebalance Consistency

If the class economy changes, affected outputs MUST be recalculated together.

The engine MUST NOT allow related values to drift independently.

7.3 Determinism

The same authoritative inputs MUST produce the same outputs.

Duplicated formulas, hidden overrides, and implementation-specific recalculation paths are prohibited.

8. Canonical Economic Reference Table

The following table is the canonical reference set for the Economic Engine.

The Insurance premium row is the premium pricing envelope only (the economic-mode / cost axis of § 4.4), and is engine guidance rather than a hard cap. It does not define any coverage, reimbursement percentage, payout cap, or claim allowance. Those belong to the insurance-tier / coverage axis and are defined by the canonical preset tables in § 4.4.3–§ 4.4.5 with the deterministic selection rule in § 4.4.8; this table MUST NOT be read as a complete insurance economic model. For NON_MONETARY this band is affordability guidance only (§ 4.4.5). For PRODUCTIVITY the settled mechanical bounds in § 4.4.4 (remaining period payout capacity and remaining claim allowance, with the configured daily payroll limit as the submission-time hours ceiling) bound exposure independently of this row; the weekly expected_weekly_hours and CWI figures are advisory economic-coherence guidance.

System-defined fines such as rent late fees and overdraft fees shall use the above table for reference when making recommendations, where those fines are configured as a single flat amount. Progressive internal fee schedules are the one exception: they are priced against the self-contained tier table in § 4.5.1 and are not bounded by the Fine row above. Actual configured fine amount shall persist on economic_engine for overdraft fines and rent_settings for rent late fees.

Store economic-role reference:

Interest reference:

9. Prohibited Patterns

The engine MUST NOT:

• use arbitrary fixed prices unrelated to CWI,
• recompute one value without updating dependent values,
• derive Store prices from a retired Basic/Standard/Premium/Luxury tier,
• let interest exceed the doubling-time constraint,
• allow hidden or undocumented formulas to become canonical,
• duplicate these calculations in consuming code as alternate authority.
• present CWI notation without classroom-currency context;
• treat reference-band membership as proof of affordability;
• predict Store purchases, Insurance enrollment, fines, or Collective Goal saving;
• divide a Collective Goal price by its participant threshold;
• assign a monetary benefit value to NON_MONETARY insurance;
• treat savings as consumption or a one-time fine as recurring;
• let Rebalance mutate Insurance when premium changes monetary protection;
• introduce the deferred v2.5 dynamic-cycle, survivability-first, or replacement-Store model.

10. Relationship to Other Documents

DOM-CLASS-001 owns the class boundary and the economic-engine table.

DOM-CLASS-002 owns the class-economy posture and supported modes.

DOM-CLASS-003 owns economics policy lineage and activation legality.

SPEC-ECON-001 owns savings-interest runtime semantics.

SPEC-ECON-002 owns disclosure and visibility requirements.

This document owns the technical calculations and reference values used by the Economic Engine.

11. Amendment

Revisions to this document must:

1. preserve the recovered calculation set,
2. keep the table and formulas deterministic,
3. remain consistent with the class-economy authority chain.

Revision history

• 2.3 (2026-10-07), owner rulings 2026-10-07: no overdraft or NSF fee is assessed; a failed obligation payment leaves the obligation unpaid, accumulating, and subject to late fees (§4.5.1.1; DOM-OBL-001 3.3). A Store purchase requires sufficient funds and is refused before posting, with no fee, when checking and any full protection transfer do not cover it (§4.5.1.1, §4.5.1.1A; FEAT-STOR-001 3.2). Funding semantics for authorized charges are unchanged.

• 2.2 (2026-10-03) — Introduces §4.5.1.1A universal full-shortfall-or-no-transfer protection for charges and deductions. Supersedes the penalty savings exclusion in 2.1 and earlier. Preserves transfer sufficient-funds rules and independent failed-agreement fees; payroll correction has zero NSF fee and creates no obligation or deferred deduction. Documentation-only authority, not runtime certification.

• 2.1 (2026-09-24) — The premium charged each billing period is the frozen contractual amount of the purchased policy version and does not scale with that period’s length (§ 4.4.2); period_premium denotes it, and § 4.4.8’s scaled formula is the authoring recommendation, normalized to 30 days for MONTHLY. Claim allowance and payout formulas are unchanged.

• 2.0 (2026-09-13) — Preserves the complete v2 Economic Engine model and adds a unified CWI Helper contract, finite consequence primitives, consistent surface mapping, explicit non-prediction semantics, Collective Goal per-student and contributing-cycle rules, monetary Insurance protection tradeoff, and the v2.5 scope boundary. Replaces Store price tiers with Necessity, Convenience, and Add-on role references (1–10%, 11–20%, and 21–30% CWI), and recalibrates rent, fine, and Collective Goal reference values.

• 1.5 (2026-08-30) — Corrects the § 4.6.1.1 fee-amount note: the teacher sets the overdraft/NSF fee amount (persisted on the engine as flat_overdraft_fee / progressive_overdraft_fee). The Economic Engine does not determine it — per § 4.6.1 the CWI helper surfaces a CWI-normed recommended range for reference and warns when the chosen amount is out of range. The prior wording (“resolved from the Economic Engine”) wrongly implied the engine sets the amount. Applicability scope and layering unchanged.

• 1.4 (2026-08-30) — Clarifies overdraft/NSF fee applicability. Adds § 4.6.1.1: an NSF fee is a fine charged only for a failed agreement — a transaction meant to fulfill an intended purchase (Store) or an existing obligation (rent, insurance) that funds cannot cover. It is NOT charged for transfers (lateral movement between the seat’s own accounts; invalid on insufficient funds, no fee) or for penalties (a teacher admin adjustment is itself a penalty and cannot generate a fine; it posts as a direct debit and does not draw on savings). Records the layering: the Ledger domain posts the fee and stays domain-blind (DOM-LED-001 §II), while the fine, being an immediate obligation (DOM-OBL-001 §II.C), is recorded by the originating business FEAT — resolving the overdraft/NSF ownership question previously open in DOM-ITR-001 §XIII.c. Codifies landed behavior; no change to fee amounts.

• 1.3 (2026-08-29) — Scope/authority correction, not a runtime-behavior change. § 4.5.4 previously carried PRODUCTIVITY approval- and submission-time execution semantics that the section’s own scope boundary (§ 4.5) assigns to FEAT-STOR-003. This revision: (a) removes remaining_weekly_CWI_capacity from the approval-time actual_payout composition, leaving the two-term min(gross_reimbursement, remaining_period_payout_capacity); (b) reclassifies the weekly CWI payout comparison and the weekly expected_weekly_hours comparison from non-overridable hard boundaries to advisory economic-coherence guidance; (c) identifies the configured daily payroll limit as the mechanical submission-time hours ceiling; and (d) updates all dependent references (hard-boundary list, preset “Mechanical bound” column, composition and rounding notes, and the premium-envelope note). The landed implementation (FEAT-STOR-003 v1.1 and the PRODUCTIVITY claim-approval code) already implements this contract; runtime behavior is unchanged. Governed downstream by the INV → DOM → FEAT hierarchy (INV-CORE-001); the resulting monetary rule remains deterministic and traceable per INV-CORE-000.