docs(erp): explain multi-family shape matching

docs/design_docs/error-resource-profile.md

@@ -33,8 +33,9 @@ sketch-bench parameter/distribution sweep
     -> flat MergedRecord rows
     -> `approxbench erp`
     -> versioned ERP artifact
-    -> backend observes live cardinality/distribution shape
-    -> deployment supplies an exact or nearest ErpSelectionRequest
+    -> backend observes an empirical shape without assuming one true family
+    -> backend fits several known families and retains every plausible fit
+    -> deployment supplies an exact or bounded multi-fit selection request
     -> ASAPPlanner filters applicable and accurate records
     -> least estimated workload cost
     -> deployment maps the selected identity to runtime configuration
@@ -58,7 +59,8 @@ Each record contains:
 - memory plus per-operation update, merge, and query CPU.
 
 The canonical workload remains available as an opaque wire value for exact
-matching. Shape-aware records additionally carry:
+matching. Shape-aware benchmark records additionally carry the known generator
+shape:
 
 ```text
 erp_shape = {
@@ -70,12 +72,42 @@ erp_shape = {
 ```
 
 The family is explicit rather than encoding uniform as a missing Zipf
-parameter. Profiles from different families are never interpolated. Parameter
-keys must match before a distance is computed; this keeps the contract open to
-Zipf exponent, continuous power-law alpha/minimum, normal mean/deviation, and
-future synthetic or fitted families. Empirical/custom traces carry a stable
-family and descriptor and normally use exact matching rather than synthetic
-interpolation. `benchmark_events` is a sufficiency gate, not a distance axis.
+parameter. Parameter keys must match before a distance is computed; this keeps
+the contract open to Zipf exponent, continuous power-law alpha/minimum, normal
+mean/deviation, and future synthetic or fitted families. `benchmark_events` is
+a sufficiency gate, not a distance axis.
+
+The observed input does **not** claim that the live population belongs to one
+of those families. Observation and fitting are a separate layer:
+
+```text
+ErpShapeObservation = {
+  cardinality,
+  observed_events,
+  empirical_fingerprint?,
+  fits: [
+    {
+      family,
+      parameters,
+      goodness_of_fit,   // lower is better
+      confidence         // calibrated value in [0, 1]
+    },
+    ...
+  ]
+}
+```
+
+The observer may retain plausible uniform, Zipf, normal, power-law, or other
+hypotheses at the same time. Classification is approximate: the planner does
+not turn the best fit into a statement that the population was generated by
+that distribution.
+
+For an external/custom dataset, an exact immutable dataset fingerprint is the
+highest-confidence match when sketch-bench measured that same dataset. The
+target policy may next try its bounded known-family fits when no exact record
+exists. If neither path has sufficient evidence, selection fails closed. The
+current backend adapter remains exact-only for custom datasets; it must not
+claim this second step until it invokes the multi-fit selector explicitly.
 
 ## Selection
 
@@ -99,11 +131,29 @@ cpu_weight * (
 + byte_second_weight * retention_seconds * memory_bytes
 ```
 
-For shape-aware selection, records must first satisfy the benchmark-event floor
-and distribution-family constraint. Their normalized distance is the maximum
-of log2-cardinality distance and every family-specific parameter distance. Only
-candidates within all caller-supplied bounds are eligible; cost selects among
-those candidates.
+For observed-shape selection, the planner first filters fitted hypotheses by
+minimum confidence and maximum goodness-of-fit. The best hypothesis must exceed
+the second-best confidence by the configured margin; otherwise the observation
+is ambiguous and selection fails. This prevents a nearly tied uniform/Zipf fit,
+for example, from being treated as a reliable classification.
+
+For the selected unambiguous fit, benchmark records must satisfy the
+benchmark-event floor and have the same family and parameter-key schema. Their
+normalized distance is the maximum of log2-cardinality distance and every
+family-specific parameter distance. Only candidates within all caller-supplied
+bounds are eligible. The current selector chooses the highest-confidence
+unambiguous fit, then ranks its ERP records by shape distance, estimated
+workload cost, and stable record ID. Goodness-of-fit is an eligibility gate. It
+never interpolates measured error or resource values between ERP records.
+
+```text
+empirical observation
+    -> multiple fitted hypotheses
+    -> confidence / goodness / ambiguity gates
+    -> bounded nearest measured ERP records
+    -> accuracy and runtime-capability gates
+    -> least estimated workload cost
+```
 
 The least-cost accepted record wins. Missing error metrics, missing contexts,
 invalid values, and insufficient trials make a record inapplicable. Cost ties
@@ -158,14 +208,16 @@ retained sketches, outside the CPU equation.
 
 ## Distribution drift
 
-ERP selection is valid only while the observed shape remains inside the
-configured profile distance. The deployment periodically derives a signature
-and triggers replanning on mismatch. Insufficient benchmark volume, excessive
-shape distance, absent metrics, unsupported runtime parameters, and drift all
-fail closed. Bursts are explicit benchmark scenario provenance and are not
+ERP selection is valid only while the observation retains an unambiguous,
+sufficiently confident fit inside the configured profile distance. The
+deployment periodically derives a new immutable observation and triggers
+replanning when its fingerprint, fit set, confidence, or distance crosses a
+policy boundary. Insufficient benchmark volume, excessive shape distance,
+absent metrics, unsupported runtime parameters, ambiguity, poor fit, and drift
+all fail closed. Bursts are explicit benchmark scenario provenance and are not
 silently inferred or interpolated.
 
-Recommended future signatures are family-specific:
+Useful empirical features for future fitters and sketch-specific matching are:
 
 - CMS: cardinality, entropy, heavy-hitter mass, and L1 frequency;
 - CountSketch: F2/L2 tail energy;
@@ -203,10 +255,16 @@ optimality gap, planning time, total profiling cost, and behavior under
 distribution shift. A second experiment may add ASAPPlanner recurrence/window
 selection, but must identify that as capability beyond query-local sizing.
 
-## Future work
+## Current boundary and future work
+
+The shared planner contract represents multiple fits and enforces confidence,
+goodness-of-fit, ambiguity, distance, and evidence gates. Distribution fitting
+and calibration belong to the observer/backend; ERP measurements belong to
+sketch-bench. A production deployment must not claim runtime-observed matching
+until that observer publishes these records on the planning feedback path.
 
-- richer family-specific signatures beyond cardinality and Zipf exponent;
-- confidence/quantile error summaries from independent trials;
+- calibrated fitters and richer empirical features for each supported family;
+- confidence/quantile error summaries from independent benchmark trials;
 - environment descriptors and validity intervals in the ERP wire format;
 - multi-state error composition for merged windows and query DAGs;
 - Pareto-front compression of dominated profile points; and