@timeax/digital-service-engine 0.0.5 → 0.0.7

package/dist/core/index.d.cts

@@ -1,7 +1,7 @@
 interface ButtonValue {
     id: string;
     value: string | number;
-    service_id?: number;
+    service_id?: ServiceIdRef;
     pricing_role?: "base" | "utility";
     meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
 }
@@ -10,16 +10,23 @@ type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
 type QuantityRule = {
     valueBy: "value" | "length" | "eval";
     code?: string;
+    multiply?: number;
+    clamp?: {
+        min?: number;
+        max?: number;
+    };
+    fallback?: number;
 };
 type UtilityLineItem = {
     nodeId: string;
     mode: UtilityMode;
     rate: number;
+    percentBase?: "service_total" | "base_service" | "all";
+    label?: string;
     inputs: {
         quantity: number;
         value?: Scalar | Scalar[];
-        valueBy?: "value" | "length" | "eval";
-        evalCodeUsed?: boolean;
+        valueBy?: "value" | "length";
     };
 };
 type ServiceFallbacks = ServiceFallback;
@@ -45,8 +52,16 @@ type SnapshotContext = {
     /** Client pruning policy used (so server can mirror/compare). */
     policy: {
         ratePolicy: {
-            kind: "lte_primary" | "none";
-            thresholdPct?: number;
+            kind: "eq_primary";
+        } | {
+            kind: "lte_primary";
+            pct: number;
+        } | {
+            kind: "within_pct";
+            pct: number;
+        } | {
+            kind: "at_least_pct_lower";
+            pct: number;
         };
         requireConstraintFit: boolean;
     };
@@ -154,7 +169,7 @@ type NodeRef = {
 };
 type NodeMap = Map<string, NodeRef>;
 
-type ValidationCode = "root_missing" | "cycle_in_tags" | "bad_bind_reference" | "duplicate_id" | "duplicate_tag_label" | "duplicate_field_name" | "label_missing" | "duplicate_visible_label" | "bad_option_key" | "option_include_exclude_conflict" | "service_field_missing_service_id" | "user_input_field_has_service_option" | "rate_mismatch_across_base" | "utility_without_base" | "unsupported_constraint" | "constraint_contradiction" | "custom_component_missing" | "policy_violation" | "field_unbound" | "constraint_overridden" | "unsupported_constraint_option" | "custom_component_unresolvable" | "quantity_multiple_markers" | "utility_with_service_id" | "utility_missing_rate" | "utility_invalid_mode" | "fallback_bad_node" | "fallback_unknown_service" | "fallback_cycle" | "fallback_no_primary" | "fallback_rate_violation" | "fallback_constraint_mismatch" | "fallback_no_tag_context";
+type ValidationCode = "root_missing" | "cycle_in_tags" | "bad_bind_reference" | "duplicate_id" | "duplicate_tag_label" | "duplicate_field_name" | "label_missing" | "duplicate_visible_label" | "bad_option_key" | "option_include_exclude_conflict" | "service_field_missing_service_id" | "user_input_field_has_service_option" | "rate_mismatch_across_base" | "rate_coherence_violation" | "utility_without_base" | "unsupported_constraint" | "constraint_contradiction" | "custom_component_missing" | "policy_violation" | "field_unbound" | "constraint_overridden" | "unsupported_constraint_option" | "custom_component_unresolvable" | "quantity_multiple_markers" | "utility_with_service_id" | "utility_missing_rate" | "utility_invalid_mode" | "fallback_bad_node" | "fallback_unknown_service" | "fallback_cycle" | "fallback_no_primary" | "fallback_rate_violation" | "fallback_constraint_mismatch" | "fallback_no_tag_context" | "field_validation_invalid_rule" | "field_validation_invalid_op" | "field_validation_eval_missing_code" | "field_validation_between_missing_bounds" | "field_validation_match_missing_pattern";
 type ValidationError = {
     code: ValidationCode;
     message: string;
@@ -210,7 +225,10 @@ type ValidatorOptions = {
     fallbackSettings?: FallbackSettings;
 };
 type RatePolicy = {
+    kind: "eq_primary";
+} | {
     kind: "lte_primary";
+    pct: number;
 } | {
     kind: "within_pct";
     pct: number;
@@ -221,7 +239,7 @@ type RatePolicy = {
 type FallbackSettings = {
     /** Require fallbacks to satisfy tag constraints (dripfeed/refill/cancel) when a tag context is known. Default: true */
     requireConstraintFit?: boolean;
-    /** Rate rule policy. Default: { kind: 'lte_primary' } i.e. candidate.rate <= primary.rate */
+    /** Rate rule policy. Default: { kind: 'lte_primary', pct: 5 }. */
     ratePolicy?: RatePolicy;
     /** When multiple candidates remain, choose first (priority) or cheapest. Default: 'priority' */
     selectionStrategy?: "priority" | "cheapest";
@@ -229,7 +247,6 @@ type FallbackSettings = {
     mode?: "strict" | "dev";
 };
 
-type ServiceIdRef = number | string;
 type NodeIdRef = string;
 type ServiceFallback = {
     /** Node-scoped fallbacks: prefer these when that node’s primary service fails */
@@ -322,6 +339,7 @@ type FallbackMutationOptions = {
     index?: number;
 };
 
+type ServiceIdRef = IdType;
 type PricingRole = "base" | "utility";
 type FieldType = "custom" | (string & {});
 /** ── Marker types (live inside meta; non-breaking) ───────────────────── */
@@ -357,11 +375,25 @@ interface BaseFieldUI {
     /** Host-defined prop names → runtime default values (untyped base) */
     defaults?: Record<string, unknown>;
 }
+type FieldValidationValueBy = "value" | "length" | "eval";
+type FieldValidationOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "nin" | "truthy" | "falsy" | "match";
+type FieldValidationRule = {
+    valueBy?: FieldValidationValueBy;
+    op: FieldValidationOp;
+    value?: unknown;
+    min?: number;
+    max?: number;
+    values?: unknown[];
+    pattern?: string;
+    flags?: string;
+    code?: string;
+    message?: string;
+};
 type FieldOption = {
     id: string;
     label: string;
     value?: string | number;
-    service_id?: number;
+    service_id?: ServiceIdRef;
     pricing_role?: PricingRole;
     meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
 };
@@ -374,6 +406,7 @@ type Field = BaseFieldUI & {
     description?: string;
     component?: string;
     pricing_role?: PricingRole;
+    validation?: FieldValidationRule[];
     meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
         multi?: boolean;
     };
@@ -382,14 +415,14 @@ type Field = BaseFieldUI & {
     service_id?: undefined;
 } | ({
     button: true;
-    service_id?: number;
+    service_id?: ServiceIdRef;
 } & WithQuantityDefault));
 type ConstraintKey = string;
 type Tag = {
     id: string;
     label: string;
     bind_id?: string;
-    service_id?: number;
+    service_id?: ServiceIdRef;
     includes?: string[];
     excludes?: string[];
     meta?: Record<string, unknown> & WithQuantityDefault;
@@ -475,6 +508,7 @@ type NormaliseOptions = {
     constraints?: string[];
 };
 declare function normalise(input: unknown, opts?: NormaliseOptions): ServiceProps;
+declare function normalizeFieldValidation(input: unknown): FieldValidationRule[] | undefined;
 
 /**
  * Core synchronous validate.
@@ -491,8 +525,6 @@ declare function validateAsync(props: ServiceProps, ctx?: ValidatorOptions): Pro
 /** Options you can set on the builder (used for validation/visibility) */
 type BuilderOptions = Omit<ValidatorOptions, "serviceMap"> & {
     serviceMap?: DgpServiceMap;
-    /** max history entries for undo/redo */
-    historyLimit?: number;
     /**
      * Field ids whose options should be shown as nodes in the graph.
      * If a field id is NOT in this set, its options are not materialized as nodes:
@@ -517,9 +549,6 @@ interface Builder {
     visibleFields(tagId: string, selectedOptionKeys?: string[]): string[];
     /** Update builder options (validator context etc.) */
     setOptions(patch: Partial<BuilderOptions>): void;
-    /** History */
-    undo(): boolean;
-    redo(): boolean;
     /** Access the current props (already normalised) */
     getProps(): ServiceProps;
     /** Service map for validation/rules */
@@ -583,48 +612,50 @@ declare function getFallbackRegistrationInfo(props: ServiceProps, nodeId: NodeId
     tagContexts: string[];
 };
 
-type BaseCandidate = {
+type SimulationAnchor = {
     kind: "field" | "option";
     id: string;
+    fieldId: string;
     label?: string;
-    service_id: number;
-    rate: number;
 };
-/** Result for each violation discovered during deep simulation. */
-type RateCoherenceDiagnostic = {
+type SharedDiagnostic = {
     scope: "visible_group";
     tagId: string;
-    /** The “primary” used for comparison in this simulation:
-     *  anchor service if present; otherwise, the first base service among simulated candidates.
-     *  (Tag service is never used as primary.)
-     */
-    primary: BaseCandidate;
-    /** The item that violated the policy against the primary. */
-    offender: {
-        kind: "field" | "option";
-        id: string;
+    nodeId: string;
+    message: string;
+    simulationAnchor?: SimulationAnchor;
+    invalidFieldIds: string[];
+};
+type RateCoherenceDiagnostic = (SharedDiagnostic & {
+    kind: "contextual";
+    primary: {
+        nodeId: string;
+        fieldId: string;
         label?: string;
-        service_id: number;
+        refKind: "single" | "multi";
+        service_id?: ServiceIdRef;
         rate: number;
     };
-    policy: RatePolicy["kind"];
-    policyPct?: number;
-    message: string;
-    /** Which button triggered this simulation */
-    simulationAnchor: {
-        kind: "field" | "option";
-        id: string;
+    offender: {
+        nodeId: string;
         fieldId: string;
         label?: string;
+        refKind: "single" | "multi";
+        service_id?: ServiceIdRef;
+        rate: number;
     };
-};
-/** Run deep rate-coherence validation by simulating each button selection in the active tag. */
+    policy: RatePolicy["kind"];
+    policyPct?: number;
+}) | (SharedDiagnostic & {
+    kind: "internal_field";
+    fieldId: string;
+});
 declare function validateRateCoherenceDeep(params: {
     builder: Builder;
     services: DgpServiceMap;
     tagId: string;
-    /** Optional rate policy (defaults to { kind: 'lte_primary' }) */
     ratePolicy?: RatePolicy;
+    invalidFieldIds?: Iterable<string>;
 }): RateCoherenceDiagnostic[];
 
 type NodeKind = "tag" | "field" | "option" | "unknown";
@@ -704,6 +735,47 @@ interface NodeIndex {
 }
 declare function createNodeIndex(builder: Builder): NodeIndex;
 
+type PolicyDiagnostic = {
+    ruleIndex: number;
+    ruleId?: string;
+    severity: "error" | "warning";
+    message: string;
+    path?: string;
+};
+
+type ServiceCheck = {
+    id: ServiceIdRef;
+    ok: boolean;
+    fitsConstraints: boolean;
+    passesRate: boolean;
+    passesPolicies: boolean;
+    policyErrors?: string[];
+    policyWarnings?: string[];
+    reasons: Array<"constraint_mismatch" | "rate_policy" | "policy_error" | "missing_capability">;
+    cap?: DgpServiceCapability;
+    rate?: number;
+};
+type FilterServicesForVisibleGroupInput = {
+    candidates: ServiceIdRef[];
+    context: {
+        tagId: string;
+        selectedButtons?: string[];
+        usedServiceIds: ServiceIdRef[];
+        effectiveConstraints?: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+        policies?: unknown;
+        fallback?: FallbackSettings;
+        strictSafety?: boolean;
+        enforcePolicies?: boolean;
+    };
+};
+type FilterServicesForVisibleGroupResult = {
+    checks: ServiceCheck[];
+    diagnostics?: PolicyDiagnostic[];
+};
+declare function filterServicesForVisibleGroup(input: FilterServicesForVisibleGroupInput, deps: {
+    builder: Builder;
+}): FilterServicesForVisibleGroupResult;
+
 type BuildOrderSnapshotSettings = {
     mode?: "prod" | "dev";
     hostDefaultQuantity?: number;
@@ -765,4 +837,4 @@ interface FallbackEditor {
 }
 declare function createFallbackEditor(options?: FallbackEditorOptions): FallbackEditor;
 
-export { type AncestryHit, type AnyNode, type Builder, type BuilderOptions, type FailedFallbackContext, type FallbackEditor, type FieldNode, type NodeIndex, type NodeKind, type NormaliseOptions, type OptionNode, type RateCoherenceDiagnostic, type RelKind, type TagNode, type UnknownNode, type WithAncestry, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createFallbackEditor, createNodeIndex, getEligibleFallbacks, getFallbackRegistrationInfo, normalise, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };
+export { type AncestryHit, type AnyNode, type Builder, type BuilderOptions, type FailedFallbackContext, type FallbackEditor, type FieldNode, type FilterServicesForVisibleGroupInput, type FilterServicesForVisibleGroupResult, type NodeIndex, type NodeKind, type NormaliseOptions, type OptionNode, type RateCoherenceDiagnostic, type RelKind, type ServiceCheck, type TagNode, type UnknownNode, type WithAncestry, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createFallbackEditor, createNodeIndex, filterServicesForVisibleGroup, getEligibleFallbacks, getFallbackRegistrationInfo, normalise, normalizeFieldValidation, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };

package/dist/core/index.d.ts

@@ -1,7 +1,7 @@
 interface ButtonValue {
     id: string;
     value: string | number;
-    service_id?: number;
+    service_id?: ServiceIdRef;
     pricing_role?: "base" | "utility";
     meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
 }
@@ -10,16 +10,23 @@ type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
 type QuantityRule = {
     valueBy: "value" | "length" | "eval";
     code?: string;
+    multiply?: number;
+    clamp?: {
+        min?: number;
+        max?: number;
+    };
+    fallback?: number;
 };
 type UtilityLineItem = {
     nodeId: string;
     mode: UtilityMode;
     rate: number;
+    percentBase?: "service_total" | "base_service" | "all";
+    label?: string;
     inputs: {
         quantity: number;
         value?: Scalar | Scalar[];
-        valueBy?: "value" | "length" | "eval";
-        evalCodeUsed?: boolean;
+        valueBy?: "value" | "length";
     };
 };
 type ServiceFallbacks = ServiceFallback;
@@ -45,8 +52,16 @@ type SnapshotContext = {
     /** Client pruning policy used (so server can mirror/compare). */
     policy: {
         ratePolicy: {
-            kind: "lte_primary" | "none";
-            thresholdPct?: number;
+            kind: "eq_primary";
+        } | {
+            kind: "lte_primary";
+            pct: number;
+        } | {
+            kind: "within_pct";
+            pct: number;
+        } | {
+            kind: "at_least_pct_lower";
+            pct: number;
         };
         requireConstraintFit: boolean;
     };
@@ -154,7 +169,7 @@ type NodeRef = {
 };
 type NodeMap = Map<string, NodeRef>;
 
-type ValidationCode = "root_missing" | "cycle_in_tags" | "bad_bind_reference" | "duplicate_id" | "duplicate_tag_label" | "duplicate_field_name" | "label_missing" | "duplicate_visible_label" | "bad_option_key" | "option_include_exclude_conflict" | "service_field_missing_service_id" | "user_input_field_has_service_option" | "rate_mismatch_across_base" | "utility_without_base" | "unsupported_constraint" | "constraint_contradiction" | "custom_component_missing" | "policy_violation" | "field_unbound" | "constraint_overridden" | "unsupported_constraint_option" | "custom_component_unresolvable" | "quantity_multiple_markers" | "utility_with_service_id" | "utility_missing_rate" | "utility_invalid_mode" | "fallback_bad_node" | "fallback_unknown_service" | "fallback_cycle" | "fallback_no_primary" | "fallback_rate_violation" | "fallback_constraint_mismatch" | "fallback_no_tag_context";
+type ValidationCode = "root_missing" | "cycle_in_tags" | "bad_bind_reference" | "duplicate_id" | "duplicate_tag_label" | "duplicate_field_name" | "label_missing" | "duplicate_visible_label" | "bad_option_key" | "option_include_exclude_conflict" | "service_field_missing_service_id" | "user_input_field_has_service_option" | "rate_mismatch_across_base" | "rate_coherence_violation" | "utility_without_base" | "unsupported_constraint" | "constraint_contradiction" | "custom_component_missing" | "policy_violation" | "field_unbound" | "constraint_overridden" | "unsupported_constraint_option" | "custom_component_unresolvable" | "quantity_multiple_markers" | "utility_with_service_id" | "utility_missing_rate" | "utility_invalid_mode" | "fallback_bad_node" | "fallback_unknown_service" | "fallback_cycle" | "fallback_no_primary" | "fallback_rate_violation" | "fallback_constraint_mismatch" | "fallback_no_tag_context" | "field_validation_invalid_rule" | "field_validation_invalid_op" | "field_validation_eval_missing_code" | "field_validation_between_missing_bounds" | "field_validation_match_missing_pattern";
 type ValidationError = {
     code: ValidationCode;
     message: string;
@@ -210,7 +225,10 @@ type ValidatorOptions = {
     fallbackSettings?: FallbackSettings;
 };
 type RatePolicy = {
+    kind: "eq_primary";
+} | {
     kind: "lte_primary";
+    pct: number;
 } | {
     kind: "within_pct";
     pct: number;
@@ -221,7 +239,7 @@ type RatePolicy = {
 type FallbackSettings = {
     /** Require fallbacks to satisfy tag constraints (dripfeed/refill/cancel) when a tag context is known. Default: true */
     requireConstraintFit?: boolean;
-    /** Rate rule policy. Default: { kind: 'lte_primary' } i.e. candidate.rate <= primary.rate */
+    /** Rate rule policy. Default: { kind: 'lte_primary', pct: 5 }. */
     ratePolicy?: RatePolicy;
     /** When multiple candidates remain, choose first (priority) or cheapest. Default: 'priority' */
     selectionStrategy?: "priority" | "cheapest";
@@ -229,7 +247,6 @@ type FallbackSettings = {
     mode?: "strict" | "dev";
 };
 
-type ServiceIdRef = number | string;
 type NodeIdRef = string;
 type ServiceFallback = {
     /** Node-scoped fallbacks: prefer these when that node’s primary service fails */
@@ -322,6 +339,7 @@ type FallbackMutationOptions = {
     index?: number;
 };
 
+type ServiceIdRef = IdType;
 type PricingRole = "base" | "utility";
 type FieldType = "custom" | (string & {});
 /** ── Marker types (live inside meta; non-breaking) ───────────────────── */
@@ -357,11 +375,25 @@ interface BaseFieldUI {
     /** Host-defined prop names → runtime default values (untyped base) */
     defaults?: Record<string, unknown>;
 }
+type FieldValidationValueBy = "value" | "length" | "eval";
+type FieldValidationOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "nin" | "truthy" | "falsy" | "match";
+type FieldValidationRule = {
+    valueBy?: FieldValidationValueBy;
+    op: FieldValidationOp;
+    value?: unknown;
+    min?: number;
+    max?: number;
+    values?: unknown[];
+    pattern?: string;
+    flags?: string;
+    code?: string;
+    message?: string;
+};
 type FieldOption = {
     id: string;
     label: string;
     value?: string | number;
-    service_id?: number;
+    service_id?: ServiceIdRef;
     pricing_role?: PricingRole;
     meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
 };
@@ -374,6 +406,7 @@ type Field = BaseFieldUI & {
     description?: string;
     component?: string;
     pricing_role?: PricingRole;
+    validation?: FieldValidationRule[];
     meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
         multi?: boolean;
     };
@@ -382,14 +415,14 @@ type Field = BaseFieldUI & {
     service_id?: undefined;
 } | ({
     button: true;
-    service_id?: number;
+    service_id?: ServiceIdRef;
 } & WithQuantityDefault));
 type ConstraintKey = string;
 type Tag = {
     id: string;
     label: string;
     bind_id?: string;
-    service_id?: number;
+    service_id?: ServiceIdRef;
     includes?: string[];
     excludes?: string[];
     meta?: Record<string, unknown> & WithQuantityDefault;
@@ -475,6 +508,7 @@ type NormaliseOptions = {
     constraints?: string[];
 };
 declare function normalise(input: unknown, opts?: NormaliseOptions): ServiceProps;
+declare function normalizeFieldValidation(input: unknown): FieldValidationRule[] | undefined;
 
 /**
  * Core synchronous validate.
@@ -491,8 +525,6 @@ declare function validateAsync(props: ServiceProps, ctx?: ValidatorOptions): Pro
 /** Options you can set on the builder (used for validation/visibility) */
 type BuilderOptions = Omit<ValidatorOptions, "serviceMap"> & {
     serviceMap?: DgpServiceMap;
-    /** max history entries for undo/redo */
-    historyLimit?: number;
     /**
      * Field ids whose options should be shown as nodes in the graph.
      * If a field id is NOT in this set, its options are not materialized as nodes:
@@ -517,9 +549,6 @@ interface Builder {
     visibleFields(tagId: string, selectedOptionKeys?: string[]): string[];
     /** Update builder options (validator context etc.) */
     setOptions(patch: Partial<BuilderOptions>): void;
-    /** History */
-    undo(): boolean;
-    redo(): boolean;
     /** Access the current props (already normalised) */
     getProps(): ServiceProps;
     /** Service map for validation/rules */
@@ -583,48 +612,50 @@ declare function getFallbackRegistrationInfo(props: ServiceProps, nodeId: NodeId
     tagContexts: string[];
 };
 
-type BaseCandidate = {
+type SimulationAnchor = {
     kind: "field" | "option";
     id: string;
+    fieldId: string;
     label?: string;
-    service_id: number;
-    rate: number;
 };
-/** Result for each violation discovered during deep simulation. */
-type RateCoherenceDiagnostic = {
+type SharedDiagnostic = {
     scope: "visible_group";
     tagId: string;
-    /** The “primary” used for comparison in this simulation:
-     *  anchor service if present; otherwise, the first base service among simulated candidates.
-     *  (Tag service is never used as primary.)
-     */
-    primary: BaseCandidate;
-    /** The item that violated the policy against the primary. */
-    offender: {
-        kind: "field" | "option";
-        id: string;
+    nodeId: string;
+    message: string;
+    simulationAnchor?: SimulationAnchor;
+    invalidFieldIds: string[];
+};
+type RateCoherenceDiagnostic = (SharedDiagnostic & {
+    kind: "contextual";
+    primary: {
+        nodeId: string;
+        fieldId: string;
         label?: string;
-        service_id: number;
+        refKind: "single" | "multi";
+        service_id?: ServiceIdRef;
         rate: number;
     };
-    policy: RatePolicy["kind"];
-    policyPct?: number;
-    message: string;
-    /** Which button triggered this simulation */
-    simulationAnchor: {
-        kind: "field" | "option";
-        id: string;
+    offender: {
+        nodeId: string;
         fieldId: string;
         label?: string;
+        refKind: "single" | "multi";
+        service_id?: ServiceIdRef;
+        rate: number;
     };
-};
-/** Run deep rate-coherence validation by simulating each button selection in the active tag. */
+    policy: RatePolicy["kind"];
+    policyPct?: number;
+}) | (SharedDiagnostic & {
+    kind: "internal_field";
+    fieldId: string;
+});
 declare function validateRateCoherenceDeep(params: {
     builder: Builder;
     services: DgpServiceMap;
     tagId: string;
-    /** Optional rate policy (defaults to { kind: 'lte_primary' }) */
     ratePolicy?: RatePolicy;
+    invalidFieldIds?: Iterable<string>;
 }): RateCoherenceDiagnostic[];
 
 type NodeKind = "tag" | "field" | "option" | "unknown";
@@ -704,6 +735,47 @@ interface NodeIndex {
 }
 declare function createNodeIndex(builder: Builder): NodeIndex;
 
+type PolicyDiagnostic = {
+    ruleIndex: number;
+    ruleId?: string;
+    severity: "error" | "warning";
+    message: string;
+    path?: string;
+};
+
+type ServiceCheck = {
+    id: ServiceIdRef;
+    ok: boolean;
+    fitsConstraints: boolean;
+    passesRate: boolean;
+    passesPolicies: boolean;
+    policyErrors?: string[];
+    policyWarnings?: string[];
+    reasons: Array<"constraint_mismatch" | "rate_policy" | "policy_error" | "missing_capability">;
+    cap?: DgpServiceCapability;
+    rate?: number;
+};
+type FilterServicesForVisibleGroupInput = {
+    candidates: ServiceIdRef[];
+    context: {
+        tagId: string;
+        selectedButtons?: string[];
+        usedServiceIds: ServiceIdRef[];
+        effectiveConstraints?: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+        policies?: unknown;
+        fallback?: FallbackSettings;
+        strictSafety?: boolean;
+        enforcePolicies?: boolean;
+    };
+};
+type FilterServicesForVisibleGroupResult = {
+    checks: ServiceCheck[];
+    diagnostics?: PolicyDiagnostic[];
+};
+declare function filterServicesForVisibleGroup(input: FilterServicesForVisibleGroupInput, deps: {
+    builder: Builder;
+}): FilterServicesForVisibleGroupResult;
+
 type BuildOrderSnapshotSettings = {
     mode?: "prod" | "dev";
     hostDefaultQuantity?: number;
@@ -765,4 +837,4 @@ interface FallbackEditor {
 }
 declare function createFallbackEditor(options?: FallbackEditorOptions): FallbackEditor;
 
-export { type AncestryHit, type AnyNode, type Builder, type BuilderOptions, type FailedFallbackContext, type FallbackEditor, type FieldNode, type NodeIndex, type NodeKind, type NormaliseOptions, type OptionNode, type RateCoherenceDiagnostic, type RelKind, type TagNode, type UnknownNode, type WithAncestry, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createFallbackEditor, createNodeIndex, getEligibleFallbacks, getFallbackRegistrationInfo, normalise, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };
+export { type AncestryHit, type AnyNode, type Builder, type BuilderOptions, type FailedFallbackContext, type FallbackEditor, type FieldNode, type FilterServicesForVisibleGroupInput, type FilterServicesForVisibleGroupResult, type NodeIndex, type NodeKind, type NormaliseOptions, type OptionNode, type RateCoherenceDiagnostic, type RelKind, type ServiceCheck, type TagNode, type UnknownNode, type WithAncestry, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createFallbackEditor, createNodeIndex, filterServicesForVisibleGroup, getEligibleFallbacks, getFallbackRegistrationInfo, normalise, normalizeFieldValidation, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };