Purpose: This document is the analyst-facing reference for how governed source data becomes TAM, SAM, SOM, price, cost, price-response, elasticity, market-pressure, and vendor campaign target values in the analytics database.
This reference consolidates:
src/analytics/ in the server source baseline dated 2026-08-03.The executable code and deployed database schema remain the final technical authority. This document is the single analyst reference that explains those executable contracts in one place.
Only the active source tree is authoritative:
src/analytics/
Do not use dated backup directories such as:
src/analytics.before-downstream-seaorm-*/
src/analytics.pre_seaorm_alignment_*/
Those directories are historical artifacts and may differ from the running implementation.
This document covers:
The original frontend demonstration values were retained as draft assumptions for interface compatibility. They were not inserted into canonical calculated-result tables. Analysts must not treat a value as calculated merely because it appeared in a frontend card.
A calculated result must be traceable to one of the following:
analytics.calculation_run_resultanalytics.calculation_run_curve_pointanalytics.calculation_run_constraintanalytics.vendor_campaign_targetanalytics.market_size_resultThe implementation contains two related but distinct calculation surfaces.
This surface reads normalized public data directly from the warehouse database and writes immutable inputs and results to the application analytics database.
It currently drives the explicit warehouse TAM, SAM, SOM, and VCT APIs.
Primary code:
src/analytics/shared/warehouse_store.rs
src/analytics/shared/warehouse_sam_store.rs
src/analytics/shared/warehouse_som_vct_store.rs
src/analytics/shared/database_functions.rs
src/analytics/shared/workflow_command_store.rs
Primary control-plane tables:
analytics.calculation_pattern
analytics.calculation_input_snapshot
analytics.calculation_input_component
analytics.calculation_run
analytics.calculation_run_input_snapshot
analytics.calculation_run_result
analytics.calculation_run_curve_point
analytics.calculation_run_constraint
analytics.calculation_run_methodology
analytics.calculation_run_lineage
analytics.vendor_campaign_target
This surface uses governed analytics-domain objects and conformed observations inside the analytics schema. The main engines are established by PostgreSQL migrations.
It contains:
Primary domain-run tables:
analytics.metric_definition
analytics.metric_calculation_run
analytics.market_size_result
analytics.metric_run_diagnostic
Important distinction:
analytics.calculation_runandanalytics.metric_calculation_runare different run systems. Analysts must identify which execution surface produced a result before querying lineage.
The warehouse is opened once at server startup and stored as AppState.db_warehouse.
Relevant code:
src/main.rs:336-347
src/main.rs:375-385
src/state.rs:35-47
src/analytics/shared/warehouse_connections.rs:20-48
The warehouse is the source of truth for normalized Census and BLS data. The application does not call Census or BLS APIs during calculation execution.
Representative warehouse relations:
| Source | County relation | State relation | U.S. relation | Primary values |
|---|---|---|---|---|
| ACS 5-year 2024 | norm.acs5_2024_co |
norm.acs5_2024_st |
norm.acs5_2024_us |
Estimate, margin, metric, geography |
| BLS CEX | norm.bls_cex |
— | — | Annual expenditure observation |
| BLS CPI | norm.bls_cpi |
— | — | Consumer price index |
| BLS PPI | norm.bls_ppi |
— | — | Producer price index |
| CBP 2023 | norm.cbp_2023_co |
norm.cbp_2023_st |
norm.cbp_2023_us |
Establishments, employment, payroll |
| Economic Census 2022 | norm.ecn_2022_co |
norm.ecn_2022_st |
norm.ecn_2022_us |
Establishments, employment, receipts |
| Nonemployer Statistics 2023 | norm.nes_2023_co |
norm.nes_2023_st |
norm.nes_2023_us |
Nonemployer establishments and receipts |
The corresponding SeaORM entities are under:
src/analytics/entity/warehouse/
AppState.db_generic is the application database connection used to store governed definitions, snapshots, runs, results, and reports.
Relevant code:
src/main.rs:340-347
src/main.rs:375-385
src/state.rs:43-46
The governed pipeline is:
Market definition
→ exact source selection
→ immutable input snapshot
→ calculation run
→ algorithm execution
→ scalar result / curve / constraint ledger
→ methodology and lineage
→ validation
→ optional report publication
Rust resolves exact warehouse rows by:
Source rows carry stable identifiers and hashes such as:
id
unique_hash
date_uploaded
The common snapshot record is:
analytics.calculation_input_snapshot
SeaORM entity:
src/analytics/entity/calculation_input_snapshot.rs
Important fields:
| Field | Meaning |
|---|---|
id |
Immutable snapshot UUID |
target_id / target_version_id |
Governed market target and version |
snapshot_key |
Human-readable stable snapshot key |
execution_mode |
How the inputs are executed |
geography_geoids |
Exact geographic scope |
input_row_count |
Number of source rows |
aggregate_value / aggregate_unit |
Optional precomputed baseline |
confidence_json |
Confidence and uncertainty metadata |
snapshot_json |
Complete frozen input document |
snapshot_hash |
Hash of the frozen input state |
algorithm_key |
Shared-input materialization algorithm |
query_plan_json |
Frozen source query description |
source_fingerprint_json |
Source relation and row-hash evidence |
input_rows_json |
Exact source rows or row references |
Each logical input is also stored separately in:
analytics.calculation_input_component
SeaORM entity:
src/analytics/entity/calculation_input_component.rs
The component table identifies whether an input is observed, assumed, derived, a parent result, or a proxy.
Important fields:
| Field | Meaning |
|---|---|
component_key |
Stable name such as base_demand_units |
component_type |
Source measure, model assumption, derived value, etc. |
origin_type |
observed, assumption, derived, prior_result, or proxy |
source_relation |
Warehouse relation or domain relation |
source_series_id |
BLS or other source series |
source_year / source_period |
Exact source period |
numeric_value / value_unit |
Stored value and unit |
source_row_ids |
Exact source row UUIDs |
source_hash |
Source fingerprint |
lineage_json |
Formula and transformation metadata |
Runs are linked to snapshots through:
analytics.calculation_run_input_snapshot
The link includes an input_role, allowing a run to identify the role played by each snapshot.
Warehouse/control-plane runs are stored in:
analytics.calculation_run
Important fields:
| Field | Meaning |
|---|---|
id |
Run UUID |
target_version_id |
Market target version |
run_type |
Calculation type |
run_status |
draft, queued, running, succeeded, failed, etc. |
calculation_hash |
Hash of the run configuration |
input_snapshot_json |
Run-level input summary |
generated_plan_json |
Execution plan |
validation_issues_json |
Pre- or post-run issues |
error_json |
Failure details |
| timestamps | Queue, start, completion, and publication times |
Algorithms are registered in:
analytics.calculation_pattern
SeaORM entity:
src/analytics/entity/calculation_pattern.rs
The registry stores:
pattern_keytarget_typestatusinput_contractoutput_contractvalidation_guardrailsexecution_handler_keyalgorithm_familyalgorithm_versionformula_expressionmethodology_jsonbenchmark_policy_jsonA calculation should be interpreted according to the pattern frozen into its run methodology, not merely according to the current registry row.
Rust inserts a typed command into:
analytics.calculation_execution_command
Implementation:
src/analytics/shared/database_functions.rs:14-84
The migration-installed AFTER INSERT trigger executes synchronously and updates the command row.
Rust inserts a typed command into:
analytics.workflow_execution_command
Implementation:
src/analytics/shared/workflow_command_store.rs:21-69
The worker dispatch is in:
src/analytics/shared/jobs/worker.rs:619-673
Dispatch logic:
tam → execute_warehouse_tam_run
sam → command_type = warehouse_sam
som / vct → command_type = warehouse_som_vct
| Output class | Table |
|---|---|
| Scalar or structured result | analytics.calculation_run_result |
| Price-response point | analytics.calculation_run_curve_point |
| SOM/VCT constraint | analytics.calculation_run_constraint |
| Frozen method | analytics.calculation_run_methodology |
| Ordered operation lineage | analytics.calculation_run_lineage |
| Vendor deliverable | analytics.vendor_campaign_target |
| Stage | Algorithm key or metric key | Purpose | Main executor |
|---|---|---|---|
| TAM | tam.warehouse_acs_metric_sum.v1 |
Add an ACS measure across non-overlapping geographies | Rust materialization + DB run publication |
| TAM | tam.warehouse_acs_joint_metric.v1 |
Sum a direct ACS joint-cohort measure | Rust materialization + DB run publication |
| TAM | tam.warehouse_acs_ratio_chain.v1 |
Approximate a joint cohort by applying governed ratios | Rust materialization + DB run publication |
| TAM | consumer_tam_cex_acs_v1 |
Model annual consumer spending from ACS and CEX | PostgreSQL domain engine |
| TAM | industry_revenue_tam_ecn_v1 |
Sum direct Economic Census product receipts | PostgreSQL domain engine |
| TAM | consumer_tam_real_cex_acs_v1 |
Restate nominal consumer TAM in real dollars | PostgreSQL domain engine |
| TAM | tam_reconciliation_v1 |
Compare or reconcile consumer and industry TAM | PostgreSQL domain engine |
| SAM | sam.warehouse_constant_elasticity.v1 |
Constant-elasticity price-response curve | PostgreSQL snapshot executor |
| SAM | sam.warehouse_linear_elasticity.v1 |
Linear local price-response approximation | PostgreSQL snapshot executor |
| SAM | sam.warehouse_logistic_affordability.v1 |
Budget-threshold affordability curve | PostgreSQL snapshot executor |
| SOM | som.warehouse_conservative_min.v1 |
Smallest defensible capacity constraint | PostgreSQL snapshot executor |
| SOM | som.warehouse_weighted_capacity.v1 |
Weighted producer proxy with utilization | PostgreSQL snapshot executor |
| VCT | vct.sam_contactable.v1 |
Contactable portion of SAM | PostgreSQL snapshot executor |
| VCT | vct.som_contactable.v1 |
Contactable portion of constrained SOM | PostgreSQL snapshot executor |
| Elasticity | price_response_loglog_association_v1 |
Uncontrolled log-price/log-quantity association | PostgreSQL domain engine |
| Elasticity | controlled_price_elasticity_external_v1 |
Store a reviewed external controlled estimate | PostgreSQL registration function |
The warehouse TAM API accepts:
src/analytics/shared/warehouse_models.rs:68-106
Principal request fields:
geography_levelgeography_idsbase_metric_codealgorithm_keymetric_match_rationalecriteriaThe active algorithm allowlist and validation are in:
src/analytics/shared/warehouse_store.rs:1049-1114
How many people, households, or other countable units are represented by one additive ACS metric across the selected non-overlapping geographies?
For geographies (g):
[
TAM = \sum_g Estimate_g
]
ACS margins of error are converted to standard errors:
[
SE_g = \frac{MOE_g}{1.645}
]
Under the non-overlapping-geography independence assumption:
[
SE_{total} = \sqrt{\sum_g SE_g^2}
]
Approximate 95% interval:
[
Lower = \max(0, TAM - 1.96SE_{total})
]
[
Upper = TAM + 1.96SE_{total}
]
src/analytics/shared/warehouse_store.rs:1233-1310
Key operations:
aggregate += row.estimate;
let standard_error = row.margin / 1.645;
variance += standard_error * standard_error;
let standard_error = variance.sqrt();
let lower = (aggregate - 1.96 * standard_error).max(0.0);
let upper = aggregate + 1.96 * standard_error;
Observed:
Assumed:
Snapshot:
analytics.calculation_input_snapshot
Source and derived components:
analytics.calculation_input_component
Final scalar result:
analytics.calculation_run_result
Methodology and uncertainty:
analytics.calculation_run_methodology
analytics.calculation_run_lineage
How many people or households satisfy the market criteria when an ACS table cell directly represents the full joint cohort?
[
TAM = \sum_g JointEstimate_g
]
The uncertainty calculation is the same as the additive method.
The arithmetic is similar, but the methodological assertion is different:
Rust requires a substantive metric_match_rationale so the analyst records why the selected ACS measure represents the joint cohort.
Validation:
src/analytics/shared/warehouse_store.rs:1068-1099
Do not label a marginal demographic count as a joint cohort merely because it is convenient. The metric rationale must identify the table concept and explain how it matches the governed population.
How large is an approximate cohort when a direct joint ACS measure is unavailable?
For geography (g):
[
Adjusted_g = Base_g \times \prod_i Ratio_{g,i}
]
Where each ratio is:
[
Ratio_{g,i} =
\frac{\sum NumeratorMetric_{g,i}}
{\sum DenominatorMetric_{g,i}}
]
Then:
[
TAM = \sum_g Adjusted_g
]
src/analytics/shared/warehouse_store.rs:1312-1430
Key operations:
let numerator = sum_metrics(rows, &numerator_codes);
let denominator = sum_metrics(rows, &denominator_codes);
let ratio = numerator / denominator;
adjusted *= ratio;
aggregate += adjusted;
Each criterion stores:
The engine does not manufacture a confidence interval for a ratio chain. A valid interval would require covariance or a direct joint estimate.
The ratio-chain result is a modeled approximation. It must not be described as a directly observed joint population.
Consumer-demand TAM is implemented by the canonical SQL domain engine rather than by the active Rust warehouse stores.
Primary migration:
20260701_006_consumer_tam_engine_up.sql
Primary metric:
consumer_tam_cex_acs_v1
What is the modeled annual spending opportunity for a governed local population and product scope?
For each geography, demographic segment, and product mapping:
[
Contribution =
H
\times W_g
\times W_m
\times W_b
\times F_{cu}
\times E
\times W_p
\times W_x
]
Where:
| Symbol | Meaning |
|---|---|
| (H) | Eligible ACS households reported |
| (W_g) | Geography inclusion weight |
| (W_m) | Market-segment weight |
| (W_b) | ACS-to-CEX segment bridge weight |
| (F_{cu}) | Household-to-consumer-unit equivalency factor |
| (E) | Annual CEX expenditure per consumer unit |
| (W_p) | Product-scope weight |
| (W_x) | CEX UCC-to-NAPCS crosswalk allocation weight |
Total:
[
Consumer\ TAM = \sum Contribution
]
analytics.consumer_tam_component
Important columns:
| Column | Meaning |
|---|---|
geography_id |
Governed local geography |
market_demographic_segment_id |
Market segment |
acs_demographic_segment_id |
ACS-side segment |
cex_demographic_segment_id |
CEX-side segment |
napcs_node_id |
Target product |
cex_ucc_node_id |
CEX source category |
acs_observation_id |
Exact ACS conformed observation |
cex_observation_id |
Exact CEX conformed observation |
eligible_households_reported |
ACS household count |
geography_weight |
Partial geography weight |
market_segment_weight |
Segment allocation |
segment_bridge_weight |
ACS-to-CEX mapping |
consumer_unit_equivalency_factor |
Household/CEX-unit conversion |
annual_expenditure_per_consumer_unit |
CEX value |
product_scope_weight |
Product allocation |
crosswalk_allocation_weight |
UCC-to-NAPCS allocation |
crosswalk_coverage_ratio |
Mapping coverage |
mapping_confidence_score |
Mapping confidence |
contribution_nominal |
Component result |
Run:
analytics.metric_calculation_run
Total:
analytics.market_size_result
Expected result identity:
measure_code = 'tam'
measure_basis = 'consumer_demand'
economic_layer = 'household'
Diagnostics:
analytics.metric_run_diagnostic
Summary view:
analytics.vw_consumer_tam_run_summary
The v1 engine deliberately caps the result at confidence grade C because national or regional CEX behavior is localized to ACS households.
The grade is reduced when:
Consumer TAM is modeled annual demand expenditure. It is not observed local sales.
Primary migration:
04_industry_revenue_tam_and_reconciliation.sql
Primary metric:
industry_revenue_tam_ecn_v1
What product receipts are reported by suppliers in the governed industry, geography, product scope, and economic layer?
[
Contribution =
ReportedReceipts
\times GeographyWeight
\times ProductScopeWeight
]
[
Industry\ TAM = \sum Contribution
]
analytics.industry_revenue_tam_input_binding
This binding fixes:
The v1 binding requires Economic Census product receipts.
analytics.industry_revenue_tam_component
Important fields:
geography_idnapcs_node_idnaics_node_idsupplier_rolereceipt_observation_idreceipts_reportedgeography_weightproduct_scope_weightcontribution_nominalRun:
analytics.metric_calculation_run
Result:
analytics.market_size_result
Expected result identity:
measure_code = 'tam'
measure_basis = 'industry_revenue'
Industry TAM is supplier-side receipt value at one declared economic layer. Do not add producer, wholesale, and retail values together unless the methodology explicitly addresses value-chain duplication.
Primary configuration:
analytics.tam_reconciliation_configuration
Primary output:
analytics.tam_reconciliation_component
[
GapRatio =
\frac{|ConsumerTAM - IndustryTAM|}
{\max(ConsumerTAM, IndustryTAM)}
]
When both values are zero, the implementation treats the gap as zero.
within_tolerance when GapRatio ≤ tolerance_ratio
outside_tolerance otherwise
not_comparable when layer or period requirements fail
| Mode | Output |
|---|---|
comparison_only |
No manufactured point estimate |
consumer_anchor |
Consumer TAM |
industry_anchor |
Industry TAM |
weighted_midpoint |
Weighted consumer/industry value |
Weighted midpoint:
[
Reconciled =
ConsumerTAM \times ConsumerWeight
+
IndustryTAM \times IndustryWeight
]
Constraint:
[
ConsumerWeight + IndustryWeight = 1
]
The engine verifies:
Reconciliation is a governed comparison. The default does not average unlike estimates merely because both exist.
Primary migration:
20260701_008_price_deflation_engine_up.sql
Primary function:
analytics.run_consumer_tam_real_v1(...)
For each nominal component:
[
RealContribution =
NominalContribution
\times
\frac{BasePeriodIndex}{ObservationPeriodIndex}
]
[
RealTAM = \sum RealContribution
]
Registry:
analytics.price_series
Observations:
analytics.price_series_observation
Market-specific binding:
analytics.price_adjustment_binding
Bindings are classified as:
product_matchedmarket_defaultbroad_fallbackanalytics.consumer_tam_real_component
Each row links:
The real-TAM confidence is the worse of:
Product-matched coverage, mapping confidence, and fallback use affect the price-binding grade.
This engine restates an existing nominal consumer TAM. It does not change the source population, product scope, or nominal calculation.
Rust builds the shared SAM input snapshot in:
src/analytics/shared/warehouse_sam_store.rs:254-314
The request contract is:
src/analytics/shared/warehouse_sam_models.rs:45-80
Observed source data:
Governed assumptions:
[
CPIRatio =
\frac{CPITarget}{CPIBase}
]
[
AdjustedCEX =
ObservedCEX \times CPIRatio
]
Rust:
let cpi_ratio = cpi_target.value / cpi_base.value;
let adjusted_cex = cex.value * cpi_ratio;
[
PPIRatio =
\frac{PPITarget}{PPIBase}
]
If no PPI pair is supplied, the current Rust materialization uses:
[
PPIRatio = 1
]
Rust:
let ppi_ratio = match (&ppi_base, &ppi_target) {
(Some(b), Some(t)) if b.value > 0.0 => t.value / b.value,
_ => 1.0,
};
[
ConsumerUnits =
\frac{ParentTAMPopulation}{PeoplePerConsumerUnit}
]
[
ProductBudget =
AdjustedCEX \times CategoryCaptureRate
]
[
Q_0 =
\frac{
ConsumerUnits
\times ProductBudget
\times ParticipationRate
}{
ReferencePrice
}
]
Rust:
let consumer_units = parent.population / request.people_per_consumer_unit;
let product_budget = adjusted_cex * request.category_capture_rate;
let base_demand_units =
consumer_units
* product_budget
* request.participation_rate
/ request.reference_price;
Snapshot:
analytics.calculation_input_snapshot
The snapshot JSON stores:
Components include:
Relevant Rust:
src/analytics/shared/warehouse_sam_store.rs:286-314
src/analytics/shared/warehouse_sam_store.rs:393-459
The active Rust API allowlist is:
src/analytics/api/warehouse_sam.rs:35-49
Algorithms:
sam.warehouse_constant_elasticity.v1
sam.warehouse_linear_elasticity.v1
sam.warehouse_logistic_affordability.v1
Rust freezes the common input. The full price-grid arithmetic is executed by the migration-managed PostgreSQL function:
analytics.execute_warehouse_sam_run(run_id, input_snapshot_id, algorithm_key)
[
Q(P) = Q_0 \left(\frac{P}{P_0}\right)^\epsilon
]
Where:
Likely buyers:
[
Buyers(P) =
\min\left(
TAMPopulation,
\frac{Q(P)}{VisitsPerBuyer}
\right)
]
Interpretation:
[
Q(P) =
\max\left(
0,
Q_0
\left[
1 +
\epsilon
\frac{P-P_0}{P_0}
\right]
\right)
]
Likely buyers:
[
Buyers(P) =
\min\left(
TAMPopulation,
\frac{Q(P)}{VisitsPerBuyer}
\right)
]
Interpretation:
Annual offer cost:
[
AnnualOfferCost(P) = P \times VisitsPerBuyer
]
Affordability share:
[
Affordability(P) =
\frac{1}{
1 +
\exp\left[
k
\frac{
AnnualOfferCost(P)-ProductBudget
}{
ProductBudget
}
\right]
}
]
Likely buyers:
[
Buyers(P) =
\min\left(
TAMPopulation,
TAMPopulation
\times ParticipationRate
\times Affordability(P)
\right)
]
Demand:
[
Q(P) = Buyers(P) \times VisitsPerBuyer
]
Where (k) is the logistic steepness.
All methods enforce an effective upper bound:
[
Q(P) \le TAMPopulation \times VisitsPerBuyer
]
This prevents the demand curve from implying more annual demand than the modeled population and visit frequency support.
Supply and cost are assumption-backed in the current warehouse SAM surface.
The request fields are in:
src/analytics/shared/warehouse_sam_models.rs:45-55
[
Supply(P) =
\max\left(
0,
BaseSupply +
(P-P_0) \times SupplySlope
\right)
]
Inputs:
base_supply_unitssupply_slope_units_per_dollar[
UnitCost(P) =
\max\left(
0,
BaseUnitCost \times PPIRatio
+
(P-P_0) \times CostSlope
\right)
]
Inputs:
base_unit_costcost_slopeppi_ratio[
Revenue(P) = Q(P) \times P
]
Q(P) \times UnitCost(P)
]
[
MarketGap(P) = Supply(P) - Q(P)
]
Interpretation:
analytics.calculation_run_curve_point
Fields:
| Field | Meaning |
|---|---|
curve_kind |
Curve classification |
algorithm_key |
Price-response method |
point_ordinal |
Ordered price point |
price |
Tested price |
demand_units |
Modeled demand |
likely_buyers |
Modeled buyers |
supply_units |
Modeled supply |
revenue |
Price × demand |
marginal_cost |
Modeled unit cost |
contribution |
Revenue less modeled variable cost |
market_gap |
Supply minus demand |
is_selected_price |
Whether this is the analyst-selected price |
point_json |
Additional calculation details |
The current implementation evaluates a governed price grid. It does not independently choose a final price.
The analyst may identify:
The server currently requires selected_price as an input and marks that point in the curve.
Rust materializes the shared SOM/VCT snapshot in:
src/analytics/shared/warehouse_som_vct_store.rs
Request contract:
src/analytics/shared/warehouse_som_vct_models.rs:59-110
The SOM snapshot carries forward:
planned_reach_people
qualification_rate
conversion_rate
open_capacity_units
utilization_rate
contactable_rate
campaign_days
channel_codes
vendor_name
campaign_name
Rust reads exact normalized producer rows from:
The request may use dataset-specific NAICS codes because CBP and ECN/NES use different NAICS vintages.
Rust computes the source-visible proxies in:
src/analytics/shared/warehouse_som_vct_store.rs:193-209
[
CBPProxy =
Establishments \times UnitsPerEstablishment
+
Employment \times UnitsPerEmployee
]
[
ECNProxy =
\frac{
Receipts
\times ReceiptsUnitMultiplier
}{
RevenuePerUnit
}
]
[
NESProxy =
\frac{
Receipts
\times ReceiptsUnitMultiplier
}{
RevenuePerUnit
}
]
The default receipts multiplier is:
1,000
This reflects source units where receipts may be reported in thousands.
[
ConservativeProxy =
PositiveMinimum(CBPProxy, ECNProxy + NESProxy)
]
The helper ignores non-positive candidates and returns the smallest positive value.
Implementation:
src/analytics/shared/warehouse_som_vct_store.rs:1246-1256
[
WeightedProxy =
\frac{
CBPProxy \times w_{cbp}
+
ECNProxy \times w_{ecn}
+
NESProxy \times w_{nes}
}{
w_{cbp}+w_{ecn}+w_{nes}
}
]
Only positive weights contribute.
Implementation:
src/analytics/shared/warehouse_som_vct_store.rs:1258-1267
These are capacity proxies derived from public producer activity. They are not confirmed bookable inventory.
Observed:
Assumed:
Derived:
The active Rust API allowlist is:
src/analytics/api/warehouse_som_vct.rs:36-40
Algorithms:
som.warehouse_conservative_min.v1
som.warehouse_weighted_capacity.v1
The full constraint arithmetic is executed by:
analytics.execute_warehouse_som_vct_run(...)
Qualified people:
[
QualifiedPeople =
\min(SAMBuyers, PlannedReach)
\times QualificationRate
]
Forecast buyers:
[
ForecastBuyers =
QualifiedPeople \times ConversionRate
]
Forecast units:
[
ForecastUnits =
ForecastBuyers \times VisitsPerBuyer
]
Public cap:
[
PublicCap = ConservativeProxy
]
SOM units:
[
SOMUnits =
\min(
SAMDemandUnits,
ForecastUnits,
OpenCapacityUnits,
PublicCap
)
]
SOM buyers:
[
SOMBuyers =
\frac{SOMUnits}{VisitsPerBuyer}
]
Weighted public cap:
[
PublicCap =
WeightedProxy \times UtilizationRate
]
Operational cap:
[
OperationalCap =
OpenCapacityUnits \times UtilizationRate
]
SOM units:
[
SOMUnits =
\min(
SAMDemandUnits,
ForecastUnits,
OperationalCap,
PublicCap
)
]
SOM buyers:
[
SOMBuyers =
\frac{SOMUnits}{VisitsPerBuyer}
]
analytics.calculation_run_constraint
Each candidate cap is stored with:
is_binding.The binding constraint is persisted by the executor. The frontend should not infer it independently.
Constraint types include:
market_demand
campaign_forecast
operational_capacity
warehouse_supply_proxy
utilization_cap
contactable_universe
VCT is a deliverable audience model, not a market-size estimate.
Algorithms:
vct.sam_contactable.v1
vct.som_contactable.v1
[
VCTPeople =
SelectedPriceSAMBuyers
\times ContactableRate
]
This represents the contactable subset of the complete selected-price SAM buyer universe.
[
VCTPeople =
ObtainableSOMBuyers
\times ContactableRate
]
This represents the contactable subset after campaign and capacity constraints.
analytics.vendor_campaign_target
Important fields:
targetable_people is not:
It is a governed planning universe.
The system distinguishes scenario elasticity from empirical elasticity.
The value in:
MaterializeWarehouseSamRequest.elasticity
is an explicit model input.
Rust contract:
src/analytics/shared/warehouse_sam_models.rs:57-80
Rust stores it as an analyst-supplied assumption in:
src/analytics/shared/warehouse_sam_store.rs:439-449
It becomes empirical only when linked to reviewed evidence.
Primary migration:
20260701_011_elasticity_evidence_layer_up.sql
Dataset builder:
analytics.build_elasticity_dataset_v1(...)
Association estimator:
analytics.run_price_response_loglog_association_v1(...)
Model:
[
\ln(Q) = \alpha + \beta\ln(P) + \varepsilon
]
The slope is:
[
\beta =
\frac{Cov(\ln P,\ln Q)}{Var(\ln P)}
]
The implementation uses PostgreSQL regression functions such as:
regr_slope
regr_intercept
regr_r2
The result is labeled:
uncontrolled_log_log_price_quantity_association
It is not publishable as causal elasticity.
Candidate observations may be excluded for:
Input observations:
analytics.sales_observation
analytics.competitor_price_observation
Specification:
analytics.elasticity_model_specification
Dataset build:
analytics.elasticity_dataset_build
Observation inclusion ledger:
analytics.elasticity_model_observation
Result:
analytics.elasticity_model_result
General run:
analytics.metric_calculation_run
Controlled models are estimated externally and registered through:
analytics.record_controlled_elasticity_estimate_v1(...)
Supported estimator categories include:
The registration requires:
Publication remains blocked until methodology review approval.
A controlled coefficient is not automatically causal. Causality depends on the identification strategy, data-generating process, instruments, controls, and diagnostics.
These are domain SQL engines rather than active Rust warehouse calculations.
The supplier-footprint engine preserves source-native measures separately:
General aggregation:
[
SupplierMeasure =
\sum(
SourceObservation
\times SupplierGeographyWeight
)
]
Do not add unlike measures into one undifferentiated “supply” number.
[
SupplierDensity =
\frac{TotalSupplierEstablishments}
{EffectiveEligibleHouseholds}
\times DensityDenominator
]
[
DemandPerHousehold =
\frac{ConsumerTAM}
{EffectiveEligibleHouseholds}
]
[
TAMPerSupplier =
\frac{ConsumerTAM}
{TotalSupplierEstablishments}
]
[
NonemployerShare =
\frac{NonemployerEstablishments}
{TotalEstablishments}
]
Market-pressure results are descriptive structural proxies. They are not equilibrium, shortage, surplus, or causal competition models.
| Purpose | File | Relevant lines |
|---|---|---|
| Open generic and warehouse DBs | src/main.rs |
336-347 |
| Store DB connections in state | src/main.rs |
375-385 |
| App state fields | src/state.rs |
35-47 |
| Warehouse URL/TLS/pool plug-in | src/analytics/shared/warehouse_connections.rs |
20-107 |
| Purpose | File | Relevant lines |
|---|---|---|
| TAM materialize/execute routes | src/analytics/routes.rs |
262-283 |
| SAM materialize/execute/curve/compare | src/analytics/routes.rs |
285-317 |
| SOM/VCT materialize/execute/constraints | src/analytics/routes.rs |
318-362 |
| Purpose | File | Relevant lines |
|---|---|---|
| TAM request structs | src/analytics/shared/warehouse_models.rs |
68-106 |
| Algorithm validation | src/analytics/shared/warehouse_store.rs |
1049-1114 |
| Snapshot materialization | src/analytics/shared/warehouse_store.rs |
370-589 |
| Metric/joint aggregation | src/analytics/shared/warehouse_store.rs |
1233-1310 |
| Ratio-chain calculation | src/analytics/shared/warehouse_store.rs |
1312-1430 |
| TAM API handlers | src/analytics/api/warehouse.rs |
120-180 |
| Typed DB execution command | src/analytics/shared/database_functions.rs |
14-84 |
| Purpose | File | Relevant lines |
|---|---|---|
| Request and response structs | src/analytics/shared/warehouse_sam_models.rs |
29-156 |
| Baseline CPI/PPI/CEX calculation | src/analytics/shared/warehouse_sam_store.rs |
254-314 |
| Component persistence | src/analytics/shared/warehouse_sam_store.rs |
393-459 |
| Algorithm allowlist | src/analytics/api/warehouse_sam.rs |
35-49 |
| Materialize and execute handlers | src/analytics/api/warehouse_sam.rs |
50-145 |
| Curve response | src/analytics/shared/warehouse_sam_models.rs |
118-142 |
| Purpose | File | Relevant lines |
|---|---|---|
| Request and response structs | src/analytics/shared/warehouse_som_vct_models.rs |
59-197 |
| Producer proxy calculations | src/analytics/shared/warehouse_som_vct_store.rs |
193-209 |
| Snapshot and component persistence | src/analytics/shared/warehouse_som_vct_store.rs |
217-377 |
| Positive minimum helper | src/analytics/shared/warehouse_som_vct_store.rs |
1246-1256 |
| Weighted average helper | src/analytics/shared/warehouse_som_vct_store.rs |
1258-1267 |
| Algorithm allowlist | src/analytics/api/warehouse_som_vct.rs |
36-40 |
| Materialize and execute handlers | src/analytics/api/warehouse_som_vct.rs |
108-260 |
| Purpose | File | Relevant lines |
|---|---|---|
| Worker target dispatch | src/analytics/shared/jobs/worker.rs |
619-673 |
| Workflow command insertion | src/analytics/shared/workflow_command_store.rs |
21-69 |
| Calculation command insertion | src/analytics/shared/database_functions.rs |
39-84 |
| Algorithm registry entity | src/analytics/entity/calculation_pattern.rs |
3-24 |
| Table | Purpose |
|---|---|
analytics.market_target |
Named TAM/SAM/SOM/VCT target |
analytics.market_target_version |
Immutable target configuration version |
analytics.calculation_pattern |
Algorithm registry |
analytics.analytic_mapping |
Governed source-to-concept mapping |
analytics.criterion_binding |
Market criterion binding |
analytics.source_dataset |
Source dataset metadata |
analytics.warehouse_object |
Warehouse relation contract |
| Table | Purpose |
|---|---|
analytics.calculation_input_snapshot |
Frozen complete input set |
analytics.calculation_input_component |
Individually classified inputs |
analytics.calculation_run_input_snapshot |
Run-to-snapshot relationship |
analytics.warehouse_query_execution |
Warehouse query execution evidence |
analytics.warehouse_validation_run |
Validation operation |
analytics.warehouse_validation_check |
Individual validation checks |
analytics.warehouse_source_coverage |
Source coverage metrics |
| Table | Purpose |
|---|---|
analytics.calculation_run |
Warehouse/control-plane run |
analytics.calculation_execution_command |
Typed TAM/general calculation command |
analytics.workflow_execution_command |
Typed SAM/SOM/VCT workflow command |
analytics.calculation_run_result |
Scalar and structured outputs |
analytics.calculation_run_curve_point |
Price curve |
analytics.calculation_run_constraint |
SOM/VCT constraint ledger |
analytics.calculation_run_methodology |
Frozen algorithm and formula |
analytics.calculation_run_lineage |
Ordered transformation graph |
analytics.vendor_campaign_target |
VCT deliverable |
| Table | Purpose |
|---|---|
analytics.metric_definition |
Domain metric catalog |
analytics.metric_calculation_run |
Domain metric run |
analytics.market_size_result |
TAM/SAM/SOM-style domain result |
analytics.metric_run_diagnostic |
Warnings and failures |
analytics.consumer_tam_component |
Consumer TAM components |
analytics.consumer_tam_real_component |
Real-dollar adjustment components |
analytics.industry_revenue_tam_component |
Industry TAM components |
analytics.tam_reconciliation_component |
Consumer/industry comparison |
analytics.supplier_footprint_result |
Source-native supplier indicators |
analytics.market_pressure_result |
Structural market-pressure indicators |
analytics.elasticity_model_result |
Price-response evidence results |
Use the run UUID from analytics.calculation_run.
SELECT
r.id AS calculation_run_id,
r.run_type,
r.run_status,
r.calculation_hash,
r.started_at,
r.completed_at,
ris.input_role,
s.id AS input_snapshot_id,
s.snapshot_key,
s.algorithm_key AS input_algorithm_key,
s.snapshot_hash,
s.input_row_count,
s.aggregate_value,
s.aggregate_unit,
s.source_fingerprint_json,
s.query_plan_json
FROM analytics.calculation_run r
LEFT JOIN analytics.calculation_run_input_snapshot ris
ON ris.calculation_run_id = r.id
LEFT JOIN analytics.calculation_input_snapshot s
ON s.id = ris.calculation_input_snapshot_id
WHERE r.id = :run_id
ORDER BY ris.input_role;
SELECT
c.component_key,
c.component_type,
c.origin_type,
c.source_relation,
c.source_series_id,
c.source_year,
c.source_period,
c.numeric_value,
c.value_unit,
c.source_row_ids,
c.source_hash,
c.lineage_json
FROM analytics.calculation_run_input_snapshot ris
JOIN analytics.calculation_input_component c
ON c.calculation_input_snapshot_id = ris.calculation_input_snapshot_id
WHERE ris.calculation_run_id = :run_id
ORDER BY ris.input_role, c.component_key;
SELECT
m.algorithm_key,
m.algorithm_version,
m.formula_expression,
m.methodology_snapshot_json,
m.performance_json
FROM analytics.calculation_run_methodology m
WHERE m.calculation_run_id = :run_id;
SELECT
result_key,
result_measure,
result_value,
result_unit,
confidence_interval_json,
validation_status,
result_json
FROM analytics.calculation_run_result
WHERE calculation_run_id = :run_id
ORDER BY result_key;
SELECT
point_ordinal,
price,
demand_units,
likely_buyers,
supply_units,
revenue,
marginal_cost,
contribution,
market_gap,
is_selected_price,
point_json
FROM analytics.calculation_run_curve_point
WHERE calculation_run_id = :run_id
ORDER BY point_ordinal;
SELECT
sequence_number,
constraint_key,
constraint_type,
constraint_value,
constraint_unit,
is_binding,
source_component_key,
details_json
FROM analytics.calculation_run_constraint
WHERE calculation_run_id = :run_id
ORDER BY sequence_number;
SELECT
sequence_number,
node_key,
node_type,
label,
upstream_node_keys,
operation,
formula_expression,
input_value_json,
output_value_json,
unit,
confidence_json,
duration_ms,
attributes
FROM analytics.calculation_run_lineage
WHERE calculation_run_id = :run_id
ORDER BY sequence_number;
SELECT *
FROM analytics.vendor_campaign_target
WHERE calculation_run_id = :run_id;
Use the UUID from analytics.metric_calculation_run.
SELECT
r.*,
msr.measure_code,
msr.measure_basis,
msr.economic_layer,
msr.value_nominal,
msr.value_real,
msr.currency_code,
msr.confidence_grade,
msr.coverage_ratio,
msr.methodology_note
FROM analytics.metric_calculation_run r
LEFT JOIN analytics.market_size_result msr
ON msr.calculation_run_id = r.calculation_run_id
WHERE r.calculation_run_id = :calculation_run_id;
SELECT
severity,
diagnostic_code,
diagnostic_message,
details
FROM analytics.metric_run_diagnostic
WHERE calculation_run_id = :calculation_run_id
ORDER BY severity, diagnostic_code;
SELECT *
FROM analytics.consumer_tam_component
WHERE calculation_run_id = :calculation_run_id
ORDER BY geography_id, market_demographic_segment_id, napcs_node_id, cex_ucc_node_id;
SELECT *
FROM analytics.consumer_tam_real_component
WHERE calculation_run_id = :calculation_run_id
ORDER BY consumer_tam_component_id;
SELECT *
FROM analytics.industry_revenue_tam_component
WHERE calculation_run_id = :calculation_run_id
ORDER BY geography_id, napcs_node_id, naics_node_id;
SELECT *
FROM analytics.tam_reconciliation_component
WHERE calculation_run_id = :calculation_run_id;
Analysts should classify every input before interpreting a result.
| Classification | Definition | Examples |
|---|---|---|
observed |
Direct source measurement | ACS estimate, CEX expenditure, CPI, PPI, CBP establishment count |
assumption |
Analyst or business parameter | Participation rate, elasticity, units per establishment |
derived |
Deterministic transformation | CPI ratio, adjusted CEX, product budget |
proxy |
Indirect estimate derived from observed data and assumptions | ECN receipt-to-capacity units |
prior_result |
Output of an upstream governed run | TAM population passed to SAM |
A result with extensive observed data may still be model-dependent when key transformations rely on assumptions.
Use:
Do not use:
SAM elasticity is normally assumption-backed.
It is not automatically populated from the elasticity evidence layer.
Supply and cost schedules are assumption-backed.
PPI indexes base cost, but base cost and slopes are not discovered from warehouse transactions.
Public producer capacity is a proxy.
CBP, ECN, and NES do not report directly bookable operational capacity.
Selected price is an input.
The engine evaluates a grid but does not yet persist an automatic optimal-price decision rule.
Consumer-demand TAM localizes broader expenditure behavior.
It is not observed local transaction revenue.
Two run frameworks coexist.
Analysts must not join calculation_run and metric_calculation_run merely because both contain a “calculation run” concept.
Rust compilation is not sufficient evidence that SQL executors are current.
SAM, SOM, VCT, real-TAM, reconciliation, and elasticity depend on migration-installed database functions and triggers.
Backup source directories may contain stale implementations.
Use only active src/analytics.
When an algorithm changes, update all applicable layers.
calculation_pattern or metric_definition.Update this document when any of the following changes:
Do not silently change the meaning of an approved algorithm key.
Preferred approach:
sam.warehouse_constant_elasticity.v1
sam.warehouse_constant_elasticity.v2
or increment the stored algorithm_version when the key is intentionally stable under the governance policy.
Before accepting a value:
The analytical chain is:
[
TAM
\rightarrow
SAM(P)
\rightarrow
SOM(P, Campaign, Capacity)
\rightarrow
VCT
]
In words:
The exact path constants are defined in:
src/analytics/constants.rs
Key route purposes:
| Purpose | Path pattern |
|---|---|
| List target snapshots | /api/analytics/targets/:target_id/input-snapshots |
| Materialize TAM | Target warehouse TAM materialize route |
| Create TAM run | Target warehouse TAM runs route |
| Execute TAM | Run warehouse TAM execute route |
| Materialize SAM | Target warehouse SAM materialize route |
| Create SAM run | Target warehouse SAM runs route |
| Read SAM curve | /api/analytics/runs/:run_id/demand-curve |
| Compare SAM curves | /api/analytics/runs/compare-demand-curves |
| Materialize SOM | Target warehouse SOM materialize route |
| Create SOM run | Target warehouse SOM runs route |
| Create VCT run | Target warehouse VCT runs route |
| Read constraints | /api/analytics/runs/:run_id/constraints |
| Read vendor target | Run vendor campaign target route |
| Compare SOM | /api/analytics/runs/compare-som-constraints |
| Value | Typical unit |
|---|---|
| Population TAM | People or households |
| Consumer TAM | USD/year |
| Industry TAM | USD/year |
| Real TAM | Base-period USD/year |
| SAM buyers | Buyers/year |
| SAM demand | Units/year or visits/year |
| Supply | Proxy or modeled units/year |
| Revenue | USD/year |
| Unit cost | USD/unit |
| Contribution | USD/year |
| SOM buyers | Buyers/forecast period or annualized basis, according to snapshot |
| SOM units | Units/forecast period or annualized basis, according to snapshot |
| VCT | People |
| Elasticity | Unitless coefficient |
| Supplier density | Establishments per configured denominator |
| Demand per household | USD/household |
| TAM per supplier | USD/establishment |
The domain algorithms described in this document are established by migration artifacts including:
20260701_006_consumer_tam_engine_up.sql
20260701_008_price_deflation_engine_up.sql
20260701_011_elasticity_evidence_layer_up.sql
04_industry_revenue_tam_and_reconciliation.sql
20260716_warehouse_som_vct.sql
The SAM snapshot executor is established by the warehouse SAM price-discovery migration that creates:
analytics.execute_warehouse_sam_run(uuid, uuid, text)
analytics.calculation_run_curve_point
analytics.vw_warehouse_sam_run_summary
Rust implementation baseline:
src/main.rs
src/state.rs
src/analytics/constants.rs
src/analytics/routes.rs
src/analytics/api/warehouse.rs
src/analytics/api/warehouse_sam.rs
src/analytics/api/warehouse_som_vct.rs
src/analytics/shared/warehouse_connections.rs
src/analytics/shared/warehouse_models.rs
src/analytics/shared/warehouse_store.rs
src/analytics/shared/warehouse_sam_models.rs
src/analytics/shared/warehouse_sam_store.rs
src/analytics/shared/warehouse_som_vct_models.rs
src/analytics/shared/warehouse_som_vct_store.rs
src/analytics/shared/database_functions.rs
src/analytics/shared/workflow_command_store.rs
src/analytics/shared/jobs/worker.rs
src/analytics/entity/
src/analytics/entity/warehouse/
| Version | Date | Change |
|---|---|---|
| 0.01 | 2026-08-03 | Initial consolidated analyst reference for algorithms, Rust implementation, schema storage, provenance, and interpretation boundaries. |