cometric 0.3.0__tar.gz → 0.4.0__tar.gz

cometric-0.4.0/.hypothesis/constants/1452a68a7516a238

@@ -0,0 +1,4 @@
+# file: /home/runner/work/cometric/cometric/src/cometric/core/api.py
+# hypothesis_version: 6.170.14
+
+[10000, '...', '/', '/...', '/actuals', '/actuals/term', '/assumption', '/candidates', '/constraints', '/cost_policy', '/detail', '/driver', '/name', '/objective', '/objective/sense', '/parameters', '/pointer', '/pointers', '/precision', '/results', '/risk_premium', '/scenarios', '/search_spec', '/target_margin', '/tolerance_absolute', '/tolerance_relative', '/transform', '/values', '0', '0.01', '0.15', '0.2', '100', '100000', '140', '20', '90000', '; ', '?', 'BAD_CONSTRAINT', 'BAD_POINTER', 'BASE', 'BEST_AT_GRID_EDGE', 'COSTS_NOT_EVALUATED', 'COST_POLICY_REQUIRED', 'DUPLICATE_ID', 'ERROR', 'INTERNAL_POLICY', 'MEAN', 'NO_RESULTS', 'PARAMETER_SPEC', 'PENDING_HUMAN_REVIEW', 'RANGE', 'RATE', 'RISK_MISMATCH', 'RISK_PREMIUM_RANGE', 'SCENARIO_INFEASIBLE', 'SCHEMA', 'TARGET_MARGIN_RANGE', 'TERM', 'UNKNOWN_DRIVER', 'UNKNOWN_METRIC', 'UNKNOWN_QUANTITY', 'WORST', '_doc', 'absolute', 'accumulation_period', 'actual', 'actuals', 'add', 'aggregation', 'allowances', 'approval_state', 'assumption', 'assumptions', 'base', 'base_client_price', 'base_contribution', 'base_fee', 'base_scenario', 'base_scenario_id', 'baseline', 'best', 'best_under_objective', 'binding_constraints', 'calculate_periods', 'calculated', 'calculations', 'candidates', 'capacity', 'client_downside', 'client_price', 'closest_value_slack', 'code', 'cometric_higher', 'cometric_lower', 'commitment_shortfall', 'compared', 'component', 'computed', 'constraints', 'contract_facts', 'contractual_fee', 'contribution_margin', 'contribution_profit', 'cost_per_unit', 'cost_policy', 'costs', 'costs_by_category', 'costs_evaluated', 'costs_in_floor', 'counts', 'currency', 'current', 'current_fee', 'declared_bearer', 'decreasing', 'definitions', 'derived_bearer', 'derived_quantities', 'description', 'detail', 'deviations', 'difference', 'direct_delivery_cost', 'direction', 'discrepancies', 'display', 'distribution', 'dominated_by', 'driver', 'dry_run', 'edge', 'engagement', 'engagement_id', 'engine_version', 'entitlement', 'enumerated', 'errors', 'estimated_seconds', 'evaluated', 'exact', 'explanation', 'failing_constraints', 'feasible', 'fee_change', 'fee_line_items', 'fee_total', 'fees', 'fingerprints', 'flat', 'floors', 'formula', 'from', 'frontier', 'frontier_metrics', 'frontier_truncated', 'full', 'full_cost_profit', 'grid_edges', 'grid_size', 'gross_margin', 'gross_profit', 'gt', 'gte', 'headroom', 'horizon', 'id', 'include_baseline', 'increasing', 'infeasible', 'input_fingerprint', 'invalid', 'invalid_reasons', 'issues', 'kind', 'labels', 'leaf_true', 'ledger', 'line_items', 'lower', 'lt', 'lte', 'max', 'max_candidates', 'max_returned', 'measured', 'mechanisms_priced', 'message', 'metric', 'metrics', 'min', 'minimums', 'money_policy', 'month', 'must not be negative', 'name', 'non_dominated', 'not', 'note', 'nothing_compared', 'objective', 'objective_values', 'ok', 'on_frontier', 'op', 'operation', 'origin', 'outcome_fee', 'overage_fee', 'overage_recognition', 'packs', 'parameter', 'parameters', 'path', 'percent', 'period', 'periods', 'pointer', 'pointers', 'precision', 'price_floor', 'profile', 'provider_downside', 'publishable_summary', 'quantity_spreading', 'range', 'ranking', 'rate', 'rate_assumptions', 'reason', 'reconcile', 'reconciled', 'record_type', 'reference', 'rejected', 'relative', 'relative_difference', 'results', 'risk', 'risk_exposure', 'risk_premium', 'rollover', 'rounding', 'rows', 'rules_fired', 'scale', 'scenario', 'scenario_id', 'scenarios', 'schema_version', 'scope', 'sense', 'set', 'severity', 'shortfall_rule', 'standard', 'standard_value', 'status', 'step', 'summary', 'target_margin', 'term', 'termination', 'tested_against', 'threshold', 'thresholds', 'tie_breakers', 'time_period', 'to', 'tolerance', 'transform', 'type', 'unit', 'unit_contribution', 'unit_floor', 'upper', 'valid', 'value', 'values', 'values_per_parameter', 'volume', 'volume_quantity', 'vs_baseline', 'warnings', 'whole', 'within_limit', 'within_tolerance', 'worked_hours', 'years', '~', '~0', '~1']

cometric-0.4.0/.hypothesis/constants/5c08095823382694

@@ -0,0 +1,4 @@
+# file: /home/runner/work/cometric/cometric/src/cometric/core/quantities.py
+# hypothesis_version: 6.170.14
+
+[' + ', ' - ', ' / ', ' x ', '(', ')', '..', '/const', '/expression', '/name', '/profile', '/q', '/rounding', '/time_period', '/unit', '/value', 'ASSUMPTION_OVERLAP', 'BAD_EXPRESSION', 'DEPENDENCY_CYCLE', 'DIVISION_BY_ZERO', 'DUPLICATE_ID', 'NEGATIVE_QUANTITY', 'NOT_ALLOCATABLE', 'PROFILE_LENGTH', 'ROUNDING_REQUIRED', 'TERM', 'UNKNOWN_QUANTITY', 'UNKNOWN_UNIT', '^\\d{4}$', 'assumptions', 'const', 'count', 'currency', 'derived', 'difference', 'expression', 'flag', 'fte', 'hours', 'product', 'q', 'quotient', 'ratio', 'scenario', 'scenario.', 'sum']

cometric-0.4.0/.hypothesis/constants/5e3c558a497b7b3b

@@ -0,0 +1,4 @@
+# file: /home/runner/work/cometric/cometric/src/cometric/core/schema.py
+# hypothesis_version: 6.170.14
+
+[10000, '$schema', ', ', '.', '0', '0.15', '110', 'A bare engagement', 'Actuals (reconcile)', 'BASE', 'Default display', 'Default summary', 'MEAN', 'SearchSpec', 'WORST', 'actuals', 'add', 'adjustment', 'aggregation', 'all', 'arrangement_version', 'array', 'assumption', 'base_scenario', 'boolean', 'by_reference', 'candidate', 'commitment', 'commitment_shortfall', 'constraint', 'constraint_paths', 'constraints', 'contractual_fee', 'contribution_margin', 'contribution_profit', 'cost_component', 'cost_policy', 'delivery_plan', 'derived_quantities', 'description', 'detail', 'direct_delivery_cost', 'display', 'dry_run', 'engagement', 'entitlement', 'enum', 'error_paths', 'exact', 'examples', 'fee_component', 'from', 'frontier_metrics', 'full', 'gross_margin', 'gross_profit', 'gt', 'id', 'include_baseline', 'integer', 'items', 'lt', 'lte', 'max', 'max_candidates', 'max_returned', 'maximum', 'metric', 'min', 'name', 'not', 'object', 'objective', 'oneOf', 'outcome_fee', 'overage_fee', 'parameters', 'path', 'paths', 'periods', 'pointer', 'pointers', 'precision', 'properties', 'quantity_source', 'range', 'rate_schedule', 'required', 'rule_paths', 'scale', 'scenario', 'scenarios', 'schema_version', 'search_parameters', 'search_spec', 'sense', 'set', 'standard', 'step', 'string', 'summary', 'term', 'tie_breakers', 'title', 'to', 'tolerance_policy', 'transform', 'type', 'values', '{metric: "amount"}']

cometric-0.4.0/.hypothesis/constants/6eef135e443dc63b

@@ -0,0 +1,4 @@
+# file: /home/runner/work/cometric/cometric/src/cometric/core/enums.py
+# hypothesis_version: 6.170.14
+
+['AI_INFERENCE', 'ALLOWANCE_OVERAGE', 'ALL_ELIGIBLE', 'ALL_UNITS', 'AMORTIZED', 'ANNUAL', 'APPROVAL_REQUIRED', 'AVOIDABLE', 'A_DIRECT', 'BACKLOG', 'BONUS', 'B_CORROBORATED', 'CALENDAR_DAYS', 'CAP', 'CAPACITY', 'CLIENT', 'COLLAR', 'COMPONENT', 'CONTRACTED', 'CONTRACT_YEAR', 'CORPORATE_OVERHEAD', 'COST', 'COST_PLUS', 'COUNT', 'CUMULATIVE', 'C_INFERENCE', 'DEDICATED', 'DEDICATED_LABOR', 'DEDICATED_RESOURCE', 'DELIVERY_MANAGEMENT', 'DIRECT_DELIVERY', 'DISCOUNT', 'DOWN', 'D_PROPOSED', 'EMERGING', 'ENGAGEMENT', 'ENGAGEMENT_AVOIDABLE', 'ENGAGEMENT_OVERHEAD', 'ENTIRE_SUBTOTAL', 'ERROR', 'ESTABLISHED_COMMON', 'ESTIMATED', 'EVENT', 'EXCESS_ONLY', 'FIXED', 'FIXED_PROJECT', 'FIXED_RECURRING', 'FLAT', 'FTE_MONTHS', 'FULL_MONTH_FROM_NEXT', 'GRADUATED_BLOCK', 'GROSS', 'HALF_EVEN', 'HALF_UP', 'HIGHER_IS_BETTER', 'HOLDBACK', 'HOURS', 'HYBRID', 'IDLE_POOLED_CAPACITY', 'ILLUSTRATIVE', 'INCURRED', 'INDEXATION', 'INFEASIBLE', 'INFO', 'INTERNAL_POLICY', 'JOINT', 'LINE_ITEM', 'LOWER_IS_BETTER', 'MARGINAL', 'METER', 'MINIMUM_SPEND', 'MINIMUM_VOLUME', 'MONTH', 'MONTHLY', 'NET_OF_CREDITS', 'NET_OF_DISCOUNTS', 'NEXT_PERIOD', 'NONE', 'NONE_ADVERSE', 'OBSERVED', 'ONE_TIME', 'OUTCOME', 'OUTCOME_ADJUSTMENT', 'OUTPUT', 'OVERFLOW_COST', 'PERCENT_OF_OUTCOME', 'PERIOD_END', 'PERIOD_END_TRUE_UP', 'PERIOD_TOTAL', 'PER_SEGMENT', 'PLATFORM_OPERATIONS', 'POOLED', 'POOLED_LABOR', 'PORTFOLIO_SHARED', 'PREPAID_CREDIT', 'PROFILE', 'PRORATE', 'PROVIDER', 'QA_REWORK', 'QUARTER', 'QUARTERLY', 'RATE', 'REBATE', 'REMAINDER_DUE', 'RESERVED_CAPACITY', 'RESOURCE', 'REUSABLE_ENGINEERING', 'SERVICE', 'SHARE', 'SHARED', 'SLA_CREDIT', 'STEP', 'SUBCONTRACTOR', 'SUCCESS', 'TERM', 'THIRD_PARTY', 'TIERED_VARIABLE', 'TIME', 'TOTAL', 'TRANSITION', 'UNAVOIDABLE', 'UNIT_OUTPUT', 'UNKNOWN', 'UNVERIFIED', 'UP', 'USAGE', 'USAGE_TRIGGERED', 'VARIABLE', 'WAIVED', 'WARNING', 'WEIGHTED', 'WEIGHTED_UNIT_OUTPUT', 'YEAR']

cometric-0.4.0/.hypothesis/constants/f19d2aecb94f07ec

@@ -0,0 +1,4 @@
+# file: /home/runner/work/cometric/cometric/src/cometric/core/quickstart.py
+# hypothesis_version: 6.170.14
+
+['0.10', '0.20', '100000', '110', '12000', '1200000', '130', '140.00', '15000', '2027-01', '40', '40000', '9000', '90000', 'DEDICATED_LABOR', 'ESTIMATED', 'EX-ALT', 'FIXED', 'MEAN', 'MONTHLY', 'POOLED_LABOR', 'TERM', 'VARIABLE', 'WORST', 'accepted_units', 'actuals', 'aggregation', 'amount', 'arguments', 'arrangement_versions', 'assumptions', 'base', 'base_fee', 'behavior', 'break_even', 'by_reference', 'calculate_periods', 'candidates', 'category', 'compare_arrangements', 'components', 'constraints', 'contractual_fee', 'contribution_profit', 'conventions', 'cost_components', 'cost_policy', 'counting_rules', 'current', 'decimals', 'delivery_plan', 'derive_risk_exposure', 'detail', 'detail_and_precision', 'driver', 'engagement', 'engagement_id', 'errors', 'examples', 'explain_fee', 'fixed_amount', 'get_template', 'high', 'how', 'id', 'lookup_concept', 'low', 'lower_base', 'lt', 'max', 'metric', 'name', 'next', 'no_arithmetic', 'not', 'notes', 'objective', 'origin', 'overage_rate', 'parameters', 'path', 'patterns', 'per_review', 'period', 'periods', 'pointer', 'price_floor', 'quantities', 'rate', 'rate_schedules', 'reconcile', 'reference', 'references', 'results', 'scenario', 'scenarios', 'search_dry_run', 'search_spec', 'search_structures', 'sense', 'spec_example.json', 'summary', 'target_margin', 'team', 'term', 'termination', 'tie_breakers', 'tiers', 'time_period', 'tool', 'tools_with_examples', 'unit', 'validate_engagement', 'value', 'values']

{cometric-0.3.0 → cometric-0.4.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.4.0 (2026-11-05)
+
+Additive; no breaking changes. `ENGINE_VERSION` stays 0.3.0 because no existing calculation changed. Fingerprints of existing scenarios still change, because the scenario schema gained fields with default values (`derived`, and `basis` on assumptions) that are part of the fingerprint.
+
+- Counting rules: assumptions with `basis: RATE` apply every month unchanged; scenarios can declare `derived` quantities (sum, difference, product, quotient over other quantities and constants), evaluated each month in dependency order, with explicit rounding for COUNT units. Results list derived formulas under `definitions`.
+- Search parameters can set a named scenario assumption in every scenario (`"assumption": "reissue_rate"`).
+- ALSP pack: counting-rule concepts (CNT-001 to CNT-003) and `pattern_counting_rules`.
+
 ## 0.3.0 (2026-11-05)
 
 ### Breaking changes

{cometric-0.3.0 → cometric-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cometric
-Version: 0.3.0
+Version: 0.4.0
 Summary: Commercial Intelligence Engine: model, simulate, and optimize the economics of service engagements.
 Project-URL: Homepage, https://github.com/mfbaig35r/cometric
 Project-URL: Repository, https://github.com/mfbaig35r/cometric

{cometric-0.3.0 → cometric-0.4.0}/docs/COMETRIC_SPEC_v0.3.md

@@ -1,6 +1,6 @@
 # Cometric | Commercial Intelligence Engine
 
-**Engineering Requirements v0.3 (as built for 0.3.0)**
+**Engineering Requirements v0.3 (as built for 0.4.0)**
 
 Cometric does three things:
 
@@ -13,7 +13,7 @@ It is built for any service relationship priced through a composite arrangement:
 | | |
 |---|---|
 | Project | Cometric (`cometric` on PyPI; CLI and MCP server `cometric`) |
-| Status | Normative for `cometric` 0.3.0 (0.1.0 released 2026-11-04; 0.2.0 and 0.3.0 on 2026-11-05). Open-source project. Where this document and the code disagree, the code's tests are the tiebreaker and the disagreement is a defect in one of them. |
+| Status | Normative for `cometric` 0.4.0 (0.1.0 released 2026-11-04; 0.2.0, 0.3.0, and 0.4.0 on 2026-11-05). Open-source project. Where this document and the code disagree, the code's tests are the tiebreaker and the disagreement is a defect in one of them. |
 | License | Apache-2.0 |
 | Date | November 4, 2026 |
 | Supersedes | `COMETRIC_SPEC_v0.2.md` (kept for history, with the v0.1 to v0.2 change log) |
@@ -57,6 +57,7 @@ v0.3 records what was built. Most changes resolve questions v0.2 left implicit;
 | V3-22 | App. D | Evidence verification status replaces the v0.2 priority list. |
 | V3-23 | 4.2, 9 | ALL_UNITS cliff bands compare every earlier tier with each threshold, with an inclusive lower bound where a band starts at a tier edge (0.2.0). |
 | V3-24 | 8.3, 9, 10 | `reconcile` operation for M6, with a publishable summary (0.2.0). |
+| V3-30 | 6.1, 6.4, 9 | Counting rules through RATE assumptions and derived quantities; search parameters can set a named assumption (0.4.0). |
 | V3-28 | 4.4, 6.1, 9 | Termination scenarios: `termination_date` on a scenario, `termination_rule` on minimums, `termination_fee` on a version (0.3.0). |
 | V3-29 | 3.4, 6.3, App. C | ALSP template `tiered_units_annual_minimum` and five worked patterns (`docs/PATTERNS.md`); "pending human review" defined (0.3.0). |
 | V3-27 | 6.2, 6.4, 8.3, 11 | Search returns best results first with full figures, tie-breakers, constraint results, grid-edge warnings, and baseline differences; dry run; linked and scaled parameters; detail and precision levels; the server stays stateless (0.3.0). |
@@ -660,6 +661,8 @@ A scenario is an immutable snapshot of arrangement version, cost policy, demand
 
 Assumptions stated over a longer period than a month MUST declare a `demand_distribution`: `FLAT` (exact allocation per §4.7) or an explicit monthly profile.
 
+**Rates and derived quantities** `[V3-30]`. An assumption with `basis: RATE` applies its value to every month of its time period unchanged (rates, shares, ratios); the default `TOTAL` spreads a total. A scenario's `derived` list computes quantities each month from assumptions and other derived quantities with a small expression language: `{"q": name}`, `{"const": "1"}`, `{"sum": [...]}`, `{"difference": [a, b]}`, `{"product": [...]}`, `{"quotient": [a, b]}`. Derived quantities are evaluated in dependency order (cycles are errors), may be used anywhere a `quantity_source` or cost driver is, and must declare `rounding` (`NONE`, `HALF_UP`, `DOWN`, `UP`) when their unit is a COUNT unit. Counting rules such as "re-issued documents are billed once" or "a bundle is billed once at its highest tier" are written this way, so the rule's assumptions stay visible, labelled, and searchable. Results list rate assumptions and each derived quantity's formula under `definitions`.
+
 v1 SHALL support low/base/high scenarios and deterministic one-way sensitivity analysis. Probability distributions and Monte Carlo are deferred until calibrated data is available.
 
 ### 6.2 Candidate comparison
@@ -715,7 +718,7 @@ In Cometric, "optimize" means a deterministic search over a space of candidate s
 
 **Output** `[V3-27]`: the best results come first. With an objective, `best` lists every candidate tied at the top after applying `objective.tie_breakers` in order, each with its parameter values, objective values, key metrics per scenario, difference from the baseline per scenario, the result of each constraint leaf, provider and client downside per deviation, `grid_edges` (parameters whose winning value is the lowest or highest in the grid), and calculation fingerprints. A `BEST_AT_GRID_EDGE` warning says when the grid should be widened before calling a result optimal. The baseline (default on) is the search_spec engagement as given. Then come counts (enumerated, invalid, infeasible, failing constraints, on frontier), invalid reasons, and the unranked frontier. If the frontier exceeds `max_returned` (default 20), the result says so. It never applies an undeclared ranking.
 
-**Parameters and sizing** `[V3-27]`: a parameter may write one `pointer` or several `pointers`, with `transform` `set` (write the value), `scale` (base × (1 + value)), or `add` (base + value), so "the same uplift on every tier" is one parameter instead of a combinatorial grid. `dry_run: true` returns grid size, calculation count, and an estimated time without running the search, so the user can confirm first.
+**Parameters and sizing** `[V3-27]`: a parameter may set a named scenario assumption in every scenario (`assumption`, `[V3-30]`), or write one `pointer` or several `pointers`, with `transform` `set` (write the value), `scale` (base × (1 + value)), or `add` (base + value), so "the same uplift on every tier" is one parameter instead of a combinatorial grid. `dry_run: true` returns grid size, calculation count, and an estimated time without running the search, so the user can confirm first.
 
 **Detail and precision** `[V3-27]`: `detail` is `summary` (default: best results in full, frontier as parameter sets, key metrics only, empty nested fields dropped), `standard`, or `full`; `precision` is `display` (default: ratios to 4 places, prices to 2) or `exact`. Fingerprints are unaffected.
 
@@ -1048,6 +1051,7 @@ The test suite MUST include:
 | T-044 | LLM-feedback fixes `[V3-26]` | Threshold discount and rebate: EXCESS_ONLY 3,175,000 and ENTIRE_SUBTOTAL 2,925,000 on a 3,250,000 gross with a 2,500,000 threshold; the excess discount starts in the crossing month; missing scope or period is an error with an example; several unit types give a null unit price with a warning, and `client_value_unit` with `+` sums them; bare-engagement candidates work and bad ones get a pointer; the constraint `op` alias works; no tool returns an unstructured error; every quickstart payload runs through the MCP server |
 | T-045 | Termination `[V3-28]` | PRORATE charges the shortfall against 150,000 x 181/365 at a 30 June termination; REMAINDER_DUE charges 90,000 for one year and 240,000 with a second year, and owes later years at a period-end termination; WAIVED charges none; the fee posts; quantities spread over the original term; unamortized transition is written off; a cut-short outcome fee is not charged; a missing rule, an out-of-range date, and a mid-month date without proration are errors |
 | T-046 | Patterns `[V3-29]` | Every pattern file matches figures computed by hand in `scripts/build_alsp.py`; the ALSP template round-trips |
+| T-047 | Counting rules `[V3-30]` | A RATE assumption applies each month; a derived billable quantity prices correctly; rounding is required for COUNT units and applied per month; bad expressions, unknown references, cycles, division by zero, negative results, and name clashes are errors with paths; search can vary an assumption; the counting-rules pattern matches its hand-computed fee |
 | T-042 | Reconciliation `[V3-24]` | Actuals equal to computed figures reconcile; a changed July invoice is reported at month 7 with the mechanism that priced it; the publishable summary contains no amounts, dates, or names; relative tolerance and unknown metrics are honored |
 
 **Property tests** SHOULD verify: non-negative accepted units; non-overlapping effective dates; contiguous tiers; under `MARGINAL` tier schedules with non-negative rates, the pre-credit fee never decreases when eligible consumption increases, holding other terms fixed. Under `ALL_UNITS` schedules the property holds outside every band reported by `TIER_CLIFF` and is not asserted inside them. T-033 runs only when the private research report is present; CI skips it.

{cometric-0.3.0 → cometric-0.4.0}/docs/PATTERNS.md

@@ -54,3 +54,14 @@ To keep a transition fee outside the minimum, give the minimum `aggregation_scop
 | base | 3,154,000 |
 
 Other termination rules: `REMAINDER_DUE` charges this period's full minimum and every later period's; `WAIVED` charges none. Outcome fees and rebates whose period termination cuts short are not charged, with a `TERMINATED_MID_PERIOD` warning, because the contract decides what is owed.
+
+## 6. Counting rules
+
+`pattern_counting_rules`. Pattern 1's volumes with two counting rules, written as derived quantities so every assumption is visible:
+
+- **Re-issues billed once:** a `RATE` assumption `reissue_rate` of 5%, and `unique_k = submitted_k x (1 - reissue_rate)` for each tier.
+- **Bundles billed once at the highest tier:** `bundle_share` (10% of lower-tier documents arrive in bundles) and `docs_per_bundle` (4) as `RATE` assumptions. Each lower tier keeps `unique_k - bundled_k`; tier 4 gets `unique_4 + bundles`, where `bundles = (bundled_1 + bundled_2 + bundled_3) / docs_per_bundle`.
+
+Monthly billable units become 42.75 / 17.1 / 51.3 / 79.0875 instead of 50 / 20 / 60 / 80, so the year bills 3,552,525 before the discount and 3,497,272.50 after it, against 3,972,000 without the rules. The counts are fractional expected values (`rounding: NONE`); use `HALF_UP`, `DOWN`, or `UP` to bill whole units each month.
+
+Monthly totals cannot show which documents arrive together, so the bundle share and size are assumptions, not facts. Search them by adding a parameter such as `{"name": "reissue", "assumption": "reissue_rate", "values": ["0", "0.05", "0.10"]}`.

{cometric-0.3.0 → cometric-0.4.0}/docs/STATUS.md

@@ -1,6 +1,6 @@
 # Cometric implementation status
 
-Version `0.3.0` (0.1.0 released 2026-11-04; 0.2.0 added reconciliation and the fixes from two code reviews; 0.3.0 adds termination scenarios, the ALSP tiered-minimum template and patterns, and the fixes from an LLM-driven pricing analysis). The normative specification is `COMETRIC_SPEC_v0.3.md`, which incorporates every clarification below.
+Version `0.4.0` (0.1.0 released 2026-11-04; 0.4.0 adds counting rules through rate assumptions and derived quantities; 0.2.0 added reconciliation and the fixes from two code reviews; 0.3.0 adds termination scenarios, the ALSP tiered-minimum template and patterns, and the fixes from an LLM-driven pricing analysis). The normative specification is `COMETRIC_SPEC_v0.3.md`, which incorporates every clarification below.
 
 ## Milestones
 

{cometric-0.3.0 → cometric-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cometric"
-version = "0.3.0"
+version = "0.4.0"
 description = "Commercial Intelligence Engine: model, simulate, and optimize the economics of service engagements."
 readme = "README.md"
 license = "Apache-2.0"

{cometric-0.3.0 → cometric-0.4.0}/scripts/build_alsp.py

@@ -395,6 +395,125 @@ def patterns(t: dict) -> dict[str, dict]:
             "base": {"contractual_fee": str(base9 - (base9 - 3_000_000) // 10 + 100_000)},
         },
     }
+    # 6. counting rules: re-issues counted once, bundles billed once at the highest tier
+    from decimal import Decimal as Dm
+
+    e6 = copy.deepcopy(filled)
+    e6["engagement_id"] = "PATTERN-COUNTING-RULES"
+    monthly = {"tier_1": Dm(50), "tier_2": Dm(20), "tier_3": Dm(60), "tier_4": Dm(80)}
+    reissue, share, per_bundle = Dm("0.05"), Dm("0.10"), Dm(4)
+    unique = {t: v * (1 - reissue) for t, v in monthly.items()}
+    bundled = {t: unique[t] * share for t in TIERS[:3]}
+    billable = {t: unique[t] - bundled[t] for t in TIERS[:3]}
+    billable["tier_4"] = unique["tier_4"] + sum(bundled.values()) / per_bundle
+    month_fee = sum(billable[t] * Dm(RATES[t]) for t in TIERS)
+    gross6 = month_fee * 12
+    fee6 = gross6 - (gross6 - 3_000_000) * Dm("0.10")
+    sub = {"submitted_" + t.split("_")[1]: str(int(v) * 12) for t, v in monthly.items()}
+    assumptions = [
+        {
+            "name": n,
+            "value": v,
+            "unit": "tier_" + n.split("_")[1],
+            "time_period": "2027",
+            "origin": "ILLUSTRATIVE",
+        }
+        for n, v in sub.items()
+    ]
+    assumptions += [
+        {
+            "name": "reissue_rate",
+            "value": "0.05",
+            "unit": "ratio",
+            "time_period": "TERM",
+            "basis": "RATE",
+            "origin": "ESTIMATED",
+        },
+        {
+            "name": "bundle_share",
+            "value": "0.10",
+            "unit": "ratio",
+            "time_period": "TERM",
+            "basis": "RATE",
+            "origin": "ESTIMATED",
+        },
+        {
+            "name": "docs_per_bundle",
+            "value": "4",
+            "unit": "ratio",
+            "time_period": "TERM",
+            "basis": "RATE",
+            "origin": "ESTIMATED",
+        },
+    ]
+    derived = []
+    for t in TIERS:
+        k = t.split("_")[1]
+        derived.append(
+            {
+                "name": f"unique_{k}",
+                "unit": t,
+                "rounding": "NONE",
+                "description": "submitted less re-issues (re-issued documents are billed once)",
+                "expression": {
+                    "product": [
+                        {"q": f"submitted_{k}"},
+                        {"difference": [{"const": "1"}, {"q": "reissue_rate"}]},
+                    ]
+                },
+            }
+        )
+    for t in TIERS[:3]:
+        k = t.split("_")[1]
+        derived.append(
+            {
+                "name": f"bundled_{k}",
+                "unit": t,
+                "rounding": "NONE",
+                "description": "documents that arrive inside a bundle",
+                "expression": {"product": [{"q": f"unique_{k}"}, {"q": "bundle_share"}]},
+            }
+        )
+        derived.append(
+            {
+                "name": t,
+                "unit": t,
+                "rounding": "NONE",
+                "description": "billable documents in this tier",
+                "expression": {"difference": [{"q": f"unique_{k}"}, {"q": f"bundled_{k}"}]},
+            }
+        )
+    derived.append(
+        {
+            "name": "bundles",
+            "unit": "tier_4",
+            "rounding": "NONE",
+            "description": "bundles, each billed once at the highest tier",
+            "expression": {
+                "quotient": [
+                    {"sum": [{"q": "bundled_1"}, {"q": "bundled_2"}, {"q": "bundled_3"}]},
+                    {"q": "docs_per_bundle"},
+                ]
+            },
+        }
+    )
+    derived.append(
+        {
+            "name": "tier_4",
+            "unit": "tier_4",
+            "rounding": "NONE",
+            "description": "billable highest-tier documents plus bundles",
+            "expression": {"sum": [{"q": "unique_4"}, {"q": "bundles"}]},
+        }
+    )
+    out["pattern_counting_rules"] = {
+        "case": "pattern_counting_rules",
+        "title": "The tiered minimum with counting rules: 5% re-issues billed once; 10% of lower-tier documents arrive in bundles of 4, each billed once at the highest tier",
+        "engagement": e6,
+        "scenarios": [{"id": "base", "assumptions": assumptions, "derived": derived}],
+        "cost_policies": {},
+        "expected": {"base": {"contractual_fee": format(fee6, "f")}},
+    }
     return out
 
 

{cometric-0.3.0 → cometric-0.4.0}/src/cometric/core/api.py

@@ -170,7 +170,7 @@ def calculate_periods(
         },
         "term": data["term"],
         "years": data["years"],
-        "definitions": definitions(e, result),
+        "definitions": definitions(e, result, s),
     }
     if "termination" in result.extras:
         out["termination"] = result.extras["termination"]
@@ -193,7 +193,7 @@ QUANTITY_SPREADING = (
 )
 
 
-def definitions(e: Engagement, result: CalculationResult) -> dict:
+def definitions(e: Engagement, result: CalculationResult, s: Scenario | None = None) -> dict:
     """The conventions a reader needs to quote these figures correctly."""
     term = result.data["term"]
     basis = term.get("client_value_quantity")
@@ -243,6 +243,23 @@ def definitions(e: Engagement, result: CalculationResult) -> dict:
         out["allowances"] = recognition
     if minimums:
         out["minimums"] = minimums
+    if s is not None:
+        rates = sorted({a.name for a in s.assumptions if a.basis == "RATE"})
+        if rates:
+            out["rate_assumptions"] = rates
+        if s.derived:
+            from .quantities import expr_text
+
+            out["derived_quantities"] = [
+                {
+                    "name": d.name,
+                    "unit": d.unit,
+                    "formula": expr_text(d.expression),
+                    "rounding": d.rounding,
+                    "description": d.description,
+                }
+                for d in s.derived
+            ]
     return out
 
 
@@ -823,18 +840,37 @@ def validate_search_spec(spec: Any, issues: Issues) -> None:
         if not isinstance(p.get("name"), str):
             issues.error("SCHEMA", "parameter needs a name", path + "/name")
         names.append(p.get("name"))
-        ptrs = p.get("pointers") if "pointers" in p else [p.get("pointer")]
-        if (
-            not isinstance(ptrs, list)
-            or not ptrs
-            or not all(isinstance(x, str) and x.startswith("/") for x in ptrs)
-        ):
-            issues.error(
-                "SCHEMA",
-                "parameter needs pointer (a JSON Pointer into the engagement, starting with /) or pointers (a list of them)",
-                path + ("/pointers" if "pointers" in p else "/pointer"),
-                example="/arrangement_versions/0/components/0/fixed_amount",
-            )
+        if "assumption" in p:
+            if not isinstance(p["assumption"], str):
+                issues.error(
+                    "SCHEMA",
+                    "assumption is the name of a scenario assumption to set in every scenario",
+                    path + "/assumption",
+                )
+            elif not any(
+                a.get("name") == p["assumption"]
+                for sc in (spec.get("scenarios") or [])
+                if isinstance(sc, dict)
+                for a in sc.get("assumptions", [])
+            ):
+                issues.error(
+                    "UNKNOWN_QUANTITY",
+                    f"no scenario has an assumption named {p['assumption']!r}",
+                    path + "/assumption",
+                )
+        else:
+            ptrs = p.get("pointers") if "pointers" in p else [p.get("pointer")]
+            if (
+                not isinstance(ptrs, list)
+                or not ptrs
+                or not all(isinstance(x, str) and x.startswith("/") for x in ptrs)
+            ):
+                issues.error(
+                    "SCHEMA",
+                    "parameter needs pointer (a JSON Pointer into the engagement, starting with /), pointers (a list of them), or assumption (a scenario assumption name)",
+                    path + ("/pointers" if "pointers" in p else "/pointer"),
+                    example="/arrangement_versions/0/components/0/fixed_amount",
+                )
         if p.get("transform", "set") not in ("set", "scale", "add"):
             issues.error(
                 "SCHEMA",
@@ -917,7 +953,7 @@ def search_structures(search_spec: dict) -> dict:
     max_returned = int(spec.get("max_returned", 20))
     try:
         grids = [_param_values(p) for p in params]
-        writes = [_param_writes(base_engagement, p) for p in params]
+        writes = [[] if "assumption" in p else _param_writes(base_engagement, p) for p in params]
     except _SpecError as exc:
         return to_jsonable({"status": "invalid", "issues": {"errors": [exc.as_issue()]}})
     except (KeyError, ValueError) as exc:
@@ -957,12 +993,20 @@ def search_structures(search_spec: dict) -> dict:
     for combo in itertools.product(*grids):
         counts["enumerated"] += 1
         eng = copy.deepcopy(base_engagement)
+        cand_scenarios = scenarios
         values = {}
         for p, write, v in zip(params, writes, combo, strict=True):
             for ptr, transform in write:
                 _set_pointer(eng, ptr, transform(v))
+            if "assumption" in p:
+                if cand_scenarios is scenarios:
+                    cand_scenarios = copy.deepcopy(scenarios)
+                for sc in cand_scenarios:
+                    for a in sc.get("assumptions", []):
+                        if a.get("name") == p["assumption"]:
+                            a["value"] = v
             values[p["name"]] = v
-        ev = _evaluate_candidate(eng, scenarios, cost_policy)
+        ev = _evaluate_candidate(eng, cand_scenarios, cost_policy)
         if not ev["valid"]:
             counts["invalid"] += 1
             for r in ev["results"]:

{cometric-0.3.0 → cometric-0.4.0}/src/cometric/core/enums.py

@@ -216,6 +216,18 @@ class Origin(StrEnum):
     INTERNAL_POLICY = "INTERNAL_POLICY"
 
 
+class AssumptionBasis(StrEnum):
+    TOTAL = "TOTAL"  # the value is a total for the time period, spread across its months
+    RATE = "RATE"  # the value applies to every month of the time period unchanged
+
+
+class DerivedRounding(StrEnum):
+    NONE = "NONE"  # keep fractional values (expected-value counts)
+    HALF_UP = "HALF_UP"
+    DOWN = "DOWN"
+    UP = "UP"
+
+
 class Distribution(StrEnum):
     FLAT = "FLAT"
     PROFILE = "PROFILE"

{cometric-0.3.0 → cometric-0.4.0}/src/cometric/core/models.py

@@ -13,6 +13,7 @@ from .enums import (
     AccumulationPeriod,
     AdjustmentType,
     AggregationScope,
+    AssumptionBasis,
     Avoidability,
     BillingBasis,
     BreachMode,
@@ -23,6 +24,7 @@ from .enums import (
     CostBehavior,
     CostCategory,
     CostPeriod,
+    DerivedRounding,
     Distribution,
     MarginLayer,
     Origin,
@@ -421,6 +423,10 @@ class Assumption(Model):
     unit: str
     time_period: str = Field(description="YYYY-MM, YYYY, YYYY-MM..YYYY-MM, or TERM")
     origin: Origin
+    basis: AssumptionBasis = Field(
+        default=AssumptionBasis.TOTAL,
+        description="TOTAL (default): value is the total for time_period, spread across its months. RATE: value applies to every month unchanged (use for rates and shares such as a re-issue rate).",
+    )
     distribution: Distribution = Distribution.FLAT
     profile: list[Dec] = []
 
@@ -437,10 +443,33 @@ class Assumption(Model):
         raise ValueError("time_period must be YYYY-MM, YYYY, YYYY-MM..YYYY-MM, or TERM")
 
 
+class DerivedQuantity(Model):
+    """A quantity computed each month from other quantities, e.g. billable units after a counting rule.
+
+    expression: {"q": name} | {"const": "1"} | {"sum": [e, ...]} | {"difference": [a, b]} |
+    {"product": [e, ...]} | {"quotient": [a, b]}. Derived quantities may use other derived ones.
+    """
+
+    name: str
+    unit: str
+    expression: dict
+    rounding: DerivedRounding | None = Field(
+        default=None,
+        description="Required for COUNT units: NONE keeps fractional expected values; HALF_UP, DOWN, or UP round each month",
+    )
+    description: str | None = Field(
+        default=None, description="The counting rule or assumption this expresses, in words"
+    )
+
+
 class Scenario(Model):
     id: str
     horizon: Horizon | None = None
     assumptions: list[Assumption] = []
+    derived: list[DerivedQuantity] = Field(
+        default=[],
+        description="Quantities computed each month from assumptions, e.g. counting rules; usable anywhere a quantity_source is",
+    )
     breach_mode: BreachMode | None = None
     termination_date: date | None = Field(
         default=None,