@timeax/digital-service-engine 0.0.3 → 0.0.5

package/dist/react/index.d.ts

@@ -1,7 +1,313 @@
-import { NodeProps } from 'reactflow';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { ReactNode } from 'react';
 
+type EventMap = Record<string, unknown>;
+declare class EventBus<E extends EventMap> {
+    private listeners;
+    on<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
+    once<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
+    emit<K extends keyof E>(event: K, payload: E[K]): void;
+    clear(): void;
+}
+
+interface ButtonValue {
+    id: string;
+    value: string | number;
+    service_id?: number;
+    pricing_role?: "base" | "utility";
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+}
+type Scalar = string | number | boolean | ButtonValue | null;
+type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
+type QuantityRule$1 = {
+    valueBy: "value" | "length" | "eval";
+    code?: string;
+};
+type UtilityLineItem = {
+    nodeId: string;
+    mode: UtilityMode;
+    rate: number;
+    inputs: {
+        quantity: number;
+        value?: Scalar | Scalar[];
+        valueBy?: "value" | "length" | "eval";
+        evalCodeUsed?: boolean;
+    };
+};
+type ServiceFallbacks = ServiceFallback;
+type FallbackDiagnostics = {
+    scope: "node" | "global";
+    nodeId?: string;
+    primary: string | number;
+    candidate: string | number;
+    reasons: Array<"rate_violation" | "constraint_mismatch" | "unknown_service" | "ambiguous_context">;
+};
+type SnapshotContext = {
+    /** The single active tag id for this order */
+    tag: string;
+    /** Effective (post-propagation) constraints on that tag */
+    constraints: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+    /**
+     * Per-node evaluation context:
+     * - For the active tag node itself: the same tag id.
+     * - For an option node: parent's field.bind_id must include this tag to be applicable; otherwise null.
+     * - For a field node (optional to include later): same rule as option, derived from field.bind_id.
+     */
+    nodeContexts: Record<string, string | null>;
+    /** Client pruning policy used (so server can mirror/compare). */
+    policy: {
+        ratePolicy: {
+            kind: "lte_primary" | "none";
+            thresholdPct?: number;
+        };
+        requireConstraintFit: boolean;
+    };
+};
+type OrderSnapshot = {
+    version: "1";
+    mode: "prod" | "dev";
+    builtAt: string;
+    selection: {
+        tag: string;
+        buttons: string[];
+        fields: Array<{
+            id: string;
+            type: string;
+            selectedOptions?: string[];
+        }>;
+    };
+    inputs: {
+        form: Record<string, Scalar | Scalar[]>;
+        selections: Record<string, string[]>;
+    };
+    quantity: number;
+    quantitySource: {
+        kind: "field" | "tag" | "option" | "default";
+        id?: string;
+        rule?: QuantityRule$1;
+        defaultedFromHost?: boolean;
+    };
+    min: number;
+    max: number;
+    services: Array<string | number>;
+    serviceMap: Record<string, Array<string | number>>;
+    fallbacks?: ServiceFallbacks;
+    utilities?: UtilityLineItem[];
+    warnings?: {
+        utility?: Array<{
+            nodeId: string;
+            reason: string;
+        }>;
+        fallbacks?: FallbackDiagnostics[];
+    };
+    meta?: {
+        schema_version?: string;
+        workspaceId?: string;
+        builder?: {
+            commit?: string;
+        };
+        context?: SnapshotContext;
+    };
+};
+
+type TimeRangeEstimate = {
+    min_seconds?: number;
+    max_seconds?: number;
+    label?: string;
+    meta?: Record<string, unknown>;
+};
+type SpeedEstimate = {
+    amount?: number;
+    per?: "minute" | "hour" | "day" | "week" | "month";
+    unit?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+};
+type ServiceEstimates = {
+    start?: TimeRangeEstimate;
+    speed?: SpeedEstimate;
+    average?: TimeRangeEstimate;
+    meta?: Record<string, unknown>;
+};
+type ServiceFlag = {
+    enabled: boolean;
+    description: string;
+    meta?: Record<string, unknown>;
+};
+type IdType = string | number;
+type ServiceFlags = Record<string, ServiceFlag>;
+type DgpServiceCapability = {
+    id: IdType;
+    name?: string;
+    rate: number;
+    min?: number;
+    max?: number;
+    category?: string;
+    flags?: ServiceFlags;
+    estimates?: ServiceEstimates;
+    meta?: Record<string, unknown>;
+    [x: string]: any;
+};
+type DgpServiceMap = Record<string, DgpServiceCapability> & Record<number, DgpServiceCapability>;
+
+type NodeRef$1 = {
+    kind: "tag";
+    id: string;
+    node: Tag;
+} | {
+    kind: "field";
+    id: string;
+    node: Field;
+} | {
+    kind: "option";
+    id: string;
+    node: FieldOption;
+    fieldId: string;
+};
+type NodeMap = Map<string, NodeRef$1>;
+
+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 ValidationError = {
+    code: ValidationCode;
+    message: string;
+    severity: "error" | "warning" | "info";
+    nodeId?: string;
+    details?: Record<string, unknown> & {
+        affectedIds?: string[];
+    };
+};
+type ServiceWhereOp = "eq" | "neq" | "in" | "nin" | "exists" | "truthy" | "falsy" | "sw";
+/**
+ * Host-extensible service filter clause.
+ * `path` should usually be "service.<prop>" or "service.meta.<prop>" etc.
+ */
+type ServiceWhereClause = {
+    path: string;
+    op?: ServiceWhereOp;
+    value?: unknown;
+};
+type DynamicRule = {
+    id: string;
+    label?: string;
+    scope: "global" | "visible_group";
+    subject: "services";
+    /**
+     * Package-level filter surface:
+     * - role/tag/field are core to the builder schema
+     * - where[] allows hosts to filter against extra service properties (handler_id/platform_id/type/key/category_id/etc.)
+     */
+    filter?: {
+        role?: "base" | "utility" | "both";
+        tag_id?: string | string[];
+        field_id?: string | string[];
+        where?: ServiceWhereClause[];
+    };
+    /**
+     * Projection is intentionally open:
+     * hosts may project custom service properties.
+     */
+    projection?: "service.id" | "service.name" | "service.rate" | "service.min" | "service.max" | "service.category" | string;
+    op: "all_equal" | "unique" | "no_mix" | "all_true" | "any_true" | "max_count" | "min_count";
+    value?: number | boolean;
+    severity?: "error" | "warning";
+    message?: string;
+};
+type ValidatorOptions = {
+    serviceMap?: DgpServiceMap;
+    nodeMap?: NodeMap;
+    allowUnsafe?: boolean;
+    selectedOptionKeys?: string[];
+    globalUtilityGuard?: boolean;
+    policies?: DynamicRule[];
+    fallbackSettings?: FallbackSettings;
+};
+type RatePolicy = {
+    kind: "lte_primary";
+} | {
+    kind: "within_pct";
+    pct: number;
+} | {
+    kind: "at_least_pct_lower";
+    pct: number;
+};
+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 */
+    ratePolicy?: RatePolicy;
+    /** When multiple candidates remain, choose first (priority) or cheapest. Default: 'priority' */
+    selectionStrategy?: "priority" | "cheapest";
+    /** Validation mode: 'strict' → node-scoped violations reported as ValidationError; 'dev' → only collect diagnostics. Default: 'strict' */
+    mode?: "strict" | "dev";
+};
+
+type ServiceIdRef = number | string;
+type NodeIdRef = string;
+type ServiceFallback = {
+    /** Node-scoped fallbacks: prefer these when that node’s primary service fails */
+    nodes?: Record<NodeIdRef, ServiceIdRef[]>;
+    /** Primary→fallback list used when no node-scoped entry is present */
+    global?: Record<ServiceIdRef, ServiceIdRef[]>;
+};
+type FallbackRegistrationScope = "global" | "node";
+type FallbackScopeRef = {
+    scope: "global";
+    primary: ServiceIdRef;
+} | {
+    scope: "node";
+    nodeId: NodeIdRef;
+};
+type FallbackRegistration = {
+    scope: FallbackRegistrationScope;
+    /**
+     * For node scope => node id
+     * For global scope => omitted
+     */
+    scopeId?: NodeIdRef;
+    /**
+     * The primary DGP service this registration belongs to.
+     * For global scope, this is the global key.
+     * For node scope, this is resolved from ServiceProps/snapshot context.
+     */
+    primary: ServiceIdRef;
+    /** Registered fallback services */
+    services: ServiceIdRef[];
+};
+type FallbackCheckReason = "duplicate" | "self_reference" | "unknown_primary" | "unknown_candidate" | "missing_snapshot" | "node_scope_not_supported" | "node_primary_unresolved" | "ambiguous_context" | "invalid_candidate" | "unknown_service" | "no_primary" | "rate_violation" | "constraint_mismatch" | "cycle" | "no_tag_context" | "missing_service_props" | "node_not_found";
+type FallbackCandidateCheck = {
+    candidate: ServiceIdRef;
+    ok: boolean;
+    reasons: FallbackCheckReason[];
+};
+type FallbackCheckResult = {
+    context: FallbackScopeRef;
+    /**
+     * Resolved primary when known.
+     * For global scope this should normally equal context.primary.
+     */
+    primary?: ServiceIdRef;
+    allowed: ServiceIdRef[];
+    rejected: FallbackCandidateCheck[];
+    warnings: FallbackCheckReason[];
+};
+type FallbackEditorState = {
+    original: ServiceFallback;
+    current: ServiceFallback;
+    changed: boolean;
+};
+type FallbackMutationOptions = {
+    /**
+     * When true, reject candidates failing validation.
+     * When false, keep structurally valid values and return warnings.
+     */
+    strict?: boolean;
+    /**
+     * Optional insert position for add/addMany.
+     * Omit to append.
+     */
+    index?: number;
+};
+
 type PricingRole = "base" | "utility";
 type FieldType = "custom" | (string & {});
 /** ── Marker types (live inside meta; non-breaking) ───────────────────── */
@@ -106,46 +412,6 @@ interface UiObject {
     required?: string[];
     order?: string[];
 }
-/** ---------------- Typed defaults helpers ---------------- */
-/**
- * UiValue<U>: given a Ui node U, infer the runtime value type.
- */
-type UiValue<U extends Ui> = U extends {
-    type: "string";
-} ? string : U extends {
-    type: "number";
-} ? number : U extends {
-    type: "boolean";
-} ? boolean : U extends {
-    type: "anyOf";
-    multiple: true;
-} ? Array<U["items"][number]["value"]> : U extends {
-    type: "anyOf";
-} ? U["items"][number]["value"] : U extends {
-    type: "array";
-    item: infer I extends Ui;
-} ? Array<UiValue<I>> : U extends {
-    type: "array";
-    items: infer T extends Ui[];
-} ? {
-    [K in keyof T]: UiValue<T[K]>;
-} : U extends {
-    type: "object";
-    fields: infer F extends Record<string, Ui>;
-} ? {
-    [K in keyof F]?: UiValue<F[K]>;
-} : unknown;
-/**
- * FieldWithTypedDefaults<T>: same shape as BaseFieldUI, but:
- *  - ui is a concrete map T (propName → Ui node)
- *  - defaults are auto-typed from T via UiValue
- */
-type FieldWithTypedDefaults<T extends Record<string, Ui>> = Omit<BaseFieldUI, "ui" | "defaults"> & {
-    ui: T;
-    defaults?: Partial<{
-        [K in keyof T]: UiValue<T[K]>;
-    }>;
-};
 type FieldOption = {
     id: string;
     label: string;
@@ -174,11 +440,6 @@ type Field = BaseFieldUI & {
     service_id?: number;
 } & WithQuantityDefault));
 type ConstraintKey = string;
-/**
- * Back-compat alias: older code may still import FlagKey.
- * Keeping this prevents a wave of TS errors while still allowing any string key.
- */
-type FlagKey = ConstraintKey;
 type Tag = {
     id: string;
     label: string;
@@ -214,14 +475,6 @@ type ServiceProps = {
     name?: string;
     notices?: ServicePropsNotice[];
 };
-type ServiceIdRef = number | string;
-type NodeIdRef = string;
-type ServiceFallback = {
-    /** Node-scoped fallbacks: prefer these when that node’s primary service fails */
-    nodes?: Record<NodeIdRef, ServiceIdRef[]>;
-    /** Primary→fallback list used when no node-scoped entry is present */
-    global?: Record<ServiceIdRef, ServiceIdRef[]>;
-};
 type NoticeType = "public" | "private";
 type NoticeSeverity = "info" | "warning" | "error";
 /**
@@ -270,10 +523,6 @@ type GraphSnapshot = {
     nodes: GraphNode[];
     edges: GraphEdge[];
 };
-type FlowNode = NodeProps<{
-    node: GraphNode;
-    [x: string]: any;
-}>;
 
 type CommentId = string;
 type ThreadId = string;
@@ -391,193 +640,58 @@ type CanvasEvents = {
     "comment:select": {
         threadId?: string;
     };
-    "edge:change": EdgeKind;
-    "comment:sync": {
-        op: "create_thread" | "add_message" | "edit_message" | "delete_message" | "move_thread" | "resolve_thread" | "delete_thread";
-        threadId: string;
-        messageId?: string;
-        status: "scheduled" | "retrying" | "succeeded" | "failed" | "cancelled";
-        attempt: number;
-        nextDelayMs?: number;
-        error?: any;
-    };
-};
-type NodeView = GraphNode & {
-    position?: NodePos;
-};
-type EdgeView = GraphEdge;
-type CanvasOptions = {
-    initialViewport?: Partial<Viewport>;
-    autoEmitState?: boolean;
-};
-
-type CommentNode = {
-    id: string;
-    text: string;
-    status: "open" | "resolved";
-    anchor?: {
-        kind: "tag" | "field" | "option";
-        id: string;
-    };
-    replies?: Array<{
-        id: string;
-        text: string;
-        created_at: string;
-        author?: string;
-    }>;
-    xy?: {
-        x: number;
-        y: number;
-    };
-    meta?: Record<string, unknown>;
-};
-type EdgeRoute = {
-    id: string;
-    points: Array<{
-        x: number;
-        y: number;
-    }>;
-};
-type LayoutState = {
-    canvas: CanvasState;
-    edges?: EdgeRoute[];
-};
-type EditorSnapshot = {
-    props: ServiceProps;
-    layout?: LayoutState;
-    comments?: CommentNode[];
-    meta?: Record<string, unknown>;
-};
-
-type TimeRangeEstimate = {
-    min_seconds?: number;
-    max_seconds?: number;
-    label?: string;
-    meta?: Record<string, unknown>;
-};
-type SpeedEstimate = {
-    amount?: number;
-    per?: "minute" | "hour" | "day" | "week" | "month";
-    unit?: string;
-    label?: string;
-    meta?: Record<string, unknown>;
-};
-type ServiceEstimates = {
-    start?: TimeRangeEstimate;
-    speed?: SpeedEstimate;
-    average?: TimeRangeEstimate;
-    meta?: Record<string, unknown>;
-};
-type ServiceFlag = {
-    enabled: boolean;
-    description: string;
-    meta?: Record<string, unknown>;
-};
-type IdType = string | number;
-type ServiceFlags = Record<string, ServiceFlag>;
-type DgpServiceCapability = {
-    id: IdType;
-    name?: string;
-    rate: number;
-    min?: number;
-    max?: number;
-    category?: string;
-    flags?: ServiceFlags;
-    estimates?: ServiceEstimates;
-    meta?: Record<string, unknown>;
-    [x: string]: any;
-};
-type DgpServiceMap = Record<string, DgpServiceCapability> & Record<number, DgpServiceCapability>;
-
-type NodeRef$1 = {
-    kind: "tag";
-    id: string;
-    node: Tag;
-} | {
-    kind: "field";
-    id: string;
-    node: Field;
-} | {
-    kind: "option";
-    id: string;
-    node: FieldOption;
-    fieldId: string;
-};
-type NodeMap = Map<string, NodeRef$1>;
-
-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 ValidationError = {
-    code: ValidationCode;
-    message: string;
-    severity: "error" | "warning" | "info";
-    nodeId?: string;
-    details?: Record<string, unknown> & {
-        affectedIds?: string[];
-    };
+    "edge:change": EdgeKind;
+    "comment:sync": {
+        op: "create_thread" | "add_message" | "edit_message" | "delete_message" | "move_thread" | "resolve_thread" | "delete_thread";
+        threadId: string;
+        messageId?: string;
+        status: "scheduled" | "retrying" | "succeeded" | "failed" | "cancelled";
+        attempt: number;
+        nextDelayMs?: number;
+        error?: any;
+    };
 };
-type ServiceWhereOp = "eq" | "neq" | "in" | "nin" | "exists" | "truthy" | "falsy" | "sw";
-/**
- * Host-extensible service filter clause.
- * `path` should usually be "service.<prop>" or "service.meta.<prop>" etc.
- */
-type ServiceWhereClause = {
-    path: string;
-    op?: ServiceWhereOp;
-    value?: unknown;
+type CanvasOptions = {
+    initialViewport?: Partial<Viewport>;
+    autoEmitState?: boolean;
 };
-type DynamicRule = {
+
+type CommentNode = {
     id: string;
-    label?: string;
-    scope: "global" | "visible_group";
-    subject: "services";
-    /**
-     * Package-level filter surface:
-     * - role/tag/field are core to the builder schema
-     * - where[] allows hosts to filter against extra service properties (handler_id/platform_id/type/key/category_id/etc.)
-     */
-    filter?: {
-        role?: "base" | "utility" | "both";
-        tag_id?: string | string[];
-        field_id?: string | string[];
-        where?: ServiceWhereClause[];
+    text: string;
+    status: "open" | "resolved";
+    anchor?: {
+        kind: "tag" | "field" | "option";
+        id: string;
     };
-    /**
-     * Projection is intentionally open:
-     * hosts may project custom service properties.
-     */
-    projection?: "service.id" | "service.name" | "service.rate" | "service.min" | "service.max" | "service.category" | string;
-    op: "all_equal" | "unique" | "no_mix" | "all_true" | "any_true" | "max_count" | "min_count";
-    value?: number | boolean;
-    severity?: "error" | "warning";
-    message?: string;
+    replies?: Array<{
+        id: string;
+        text: string;
+        created_at: string;
+        author?: string;
+    }>;
+    xy?: {
+        x: number;
+        y: number;
+    };
+    meta?: Record<string, unknown>;
 };
-type ValidatorOptions = {
-    serviceMap?: DgpServiceMap;
-    nodeMap?: NodeMap;
-    allowUnsafe?: boolean;
-    selectedOptionKeys?: string[];
-    globalUtilityGuard?: boolean;
-    policies?: DynamicRule[];
-    fallbackSettings?: FallbackSettings;
+type EdgeRoute = {
+    id: string;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
 };
-type RatePolicy = {
-    kind: "lte_primary";
-} | {
-    kind: "within_pct";
-    pct: number;
-} | {
-    kind: "at_least_pct_lower";
-    pct: number;
+type LayoutState = {
+    canvas: CanvasState;
+    edges?: EdgeRoute[];
 };
-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 */
-    ratePolicy?: RatePolicy;
-    /** When multiple candidates remain, choose first (priority) or cheapest. Default: 'priority' */
-    selectionStrategy?: "priority" | "cheapest";
-    /** Validation mode: 'strict' → node-scoped violations reported as ValidationError; 'dev' → only collect diagnostics. Default: 'strict' */
-    mode?: "strict" | "dev";
+type EditorSnapshot = {
+    props: ServiceProps;
+    layout?: LayoutState;
+    comments?: CommentNode[];
+    meta?: Record<string, unknown>;
 };
 
 /** Options you can set on the builder (used for validation/visibility) */
@@ -628,111 +742,38 @@ interface Builder {
     getNodeMap(): NodeMap;
 }
 
-interface ButtonValue {
-    id: string;
-    value: string | number;
-    service_id?: number;
-    pricing_role?: "base" | "utility";
-    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
-}
-type Scalar = string | number | boolean | ButtonValue | null;
-type UtilityMode = "flat" | "per_quantity" | "per_value" | "percent";
-type QuantityRule$1 = {
-    valueBy: "value" | "length" | "eval";
-    code?: string;
-};
-type UtilityLineItem = {
-    nodeId: string;
-    mode: UtilityMode;
-    rate: number;
-    inputs: {
-        quantity: number;
-        value?: Scalar | Scalar[];
-        valueBy?: "value" | "length" | "eval";
-        evalCodeUsed?: boolean;
-    };
-};
-type ServiceFallbacks = {
-    nodes?: Record<string, Array<string | number>>;
-    global?: Record<string | number, Array<string | number>>;
-};
-type FallbackDiagnostics = {
-    scope: "node" | "global";
-    nodeId?: string;
-    primary: string | number;
-    candidate: string | number;
-    reasons: Array<"rate_violation" | "constraint_mismatch" | "unknown_service" | "ambiguous_context">;
-};
-type SnapshotContext = {
-    /** The single active tag id for this order */
-    tag: string;
-    /** Effective (post-propagation) constraints on that tag */
-    constraints: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
+/**
+ * Keep the editor contract exactly as discussed:
+ * - mutates only ServiceFallback (internal clone)
+ * - props are read-only context
+ * - get(serviceId) is service-centric
+ * - getScope(context) is raw scope access
+ */
+interface FallbackEditor$1 {
+    state(): FallbackEditorState;
+    value(): ServiceFallback;
+    reset(): FallbackEditorState;
+    /** Service-centric: all registrations that belong to this primary service */
+    get(serviceId: ServiceIdRef): FallbackRegistration[];
+    /** Exact/raw scope access */
+    getScope(context: FallbackScopeRef): ServiceIdRef[];
+    /** Validation preview */
+    check(context: FallbackScopeRef, candidates?: ServiceIdRef[]): FallbackCheckResult;
+    add(context: FallbackScopeRef, candidate: ServiceIdRef, options?: FallbackMutationOptions): FallbackEditorState;
+    addMany(context: FallbackScopeRef, candidates: ServiceIdRef[], options?: FallbackMutationOptions): FallbackEditorState;
+    remove(context: FallbackScopeRef, candidate: ServiceIdRef): FallbackEditorState;
+    replace(context: FallbackScopeRef, candidates: ServiceIdRef[], options?: FallbackMutationOptions): FallbackEditorState;
+    clear(context: FallbackScopeRef): FallbackEditorState;
     /**
-     * Per-node evaluation context:
-     * - For the active tag node itself: the same tag id.
-     * - For an option node: parent's field.bind_id must include this tag to be applicable; otherwise null.
-     * - For a field node (optional to include later): same rule as option, derived from field.bind_id.
+     * Optional helper for picker UIs:
+     * shows candidates that the core fallback resolver would currently accept.
      */
-    nodeContexts: Record<string, string | null>;
-    /** Client pruning policy used (so server can mirror/compare). */
-    policy: {
-        ratePolicy: {
-            kind: "lte_primary" | "none";
-            thresholdPct?: number;
-        };
-        requireConstraintFit: boolean;
-    };
-};
-type OrderSnapshot = {
-    version: "1";
-    mode: "prod" | "dev";
-    builtAt: string;
-    selection: {
-        tag: string;
-        buttons: string[];
-        fields: Array<{
-            id: string;
-            type: string;
-            selectedOptions?: string[];
-        }>;
-    };
-    inputs: {
-        form: Record<string, Scalar | Scalar[]>;
-        selections: Record<string, string[]>;
-    };
-    quantity: number;
-    quantitySource: {
-        kind: "field" | "tag" | "option" | "default";
-        id?: string;
-        rule?: QuantityRule$1;
-        defaultedFromHost?: boolean;
-    };
-    min: number;
-    max: number;
-    services: Array<string | number>;
-    serviceMap: Record<string, Array<string | number>>;
-    fallbacks?: {
-        nodes?: Record<string, Array<string | number>>;
-        global?: Record<string | number, Array<string | number>>;
-    };
-    utilities?: UtilityLineItem[];
-    warnings?: {
-        utility?: Array<{
-            nodeId: string;
-            reason: string;
-        }>;
-        fallbacks?: FallbackDiagnostics[];
-    };
-    meta?: {
-        schema_version?: string;
-        workspaceId?: string;
-        builder?: {
-            commit?: string;
-        };
-        context?: SnapshotContext;
-    };
-};
+    eligible(context: FallbackScopeRef, options?: {
+        exclude?: ServiceIdRef[];
+        unique?: boolean;
+        limit?: number;
+    }): ServiceIdRef[];
+}
 
 type Env = "client" | "workspace";
 type VisibleGroup = {
@@ -816,30 +857,6 @@ declare class Selection {
     private findOptionById;
 }
 
-type EditorEvents = {
-    "editor:command": {
-        name: string;
-        payload?: any;
-    };
-    "editor:change": {
-        props: ServiceProps;
-        reason: string;
-        command?: string;
-    };
-    "editor:undo": {
-        stackSize: number;
-        index: number;
-    };
-    "editor:redo": {
-        stackSize: number;
-        index: number;
-    };
-    "editor:error": {
-        message: string;
-        code?: string;
-        meta?: any;
-    };
-};
 type Command = {
     name: string;
     do(): void;
@@ -856,19 +873,6 @@ type EditorOptions = {
     policiesRaw?: unknown;
     selectionProps?: SelectionOptions;
 };
-type ConnectKind = "bind" | "include" | "exclude";
-
-/** Exported alias so the schema generator can target an array */
-type AdminPolicies = DynamicRule[];
-
-type EventMap = Record<string, unknown>;
-declare class EventBus<E extends EventMap> {
-    private listeners;
-    on<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
-    once<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
-    emit<K extends keyof E>(event: K, payload: E[K]): void;
-    clear(): void;
-}
 
 type PolicyDiagnostic = {
     ruleIndex: number;
@@ -1852,4 +1856,208 @@ declare function useOrderFlow(): UseOrderFlowReturn;
  */
 declare function registerEntries(registry: Registry): void;
 
-export { type Adapter, type AdapterCtx, type AdminPolicies, type BaseFieldUI, type ButtonValue, CanvasAPI, type CanvasEvents, type CanvasOptions, type CanvasState, type Command, type CommentAnchor, type CommentId, type CommentMessage, type CommentNode, type CommentThread, type ConnectKind, type ConstraintKey, type DgpServiceCapability, type DgpServiceMap, type DraftWire, type DynamicRule, type EdgeKind, type EdgeRoute, type EdgeView, type EditorEvents, type EditorOptions, type EditorSnapshot, EventBus, type EventMap, type FallbackDiagnostics, type FallbackSettings, type Field, type FieldOption, type FieldType, type FieldWithTypedDefaults, type FlagKey, type FlowNode, type FormApi, FormProvider, type FormProviderProps, type FormSnapshot, type GraphEdge, type GraphNode, type GraphSnapshot, type IdType, type InputDescriptor, type InputKind, type InputVariant, type InputWrapperProps, type LayoutState, type NodeIdRef, type NodeKind, type NodePos, type NodePositions, type NodeView, type NoticeKind, type NoticeSeverity, type NoticeTarget, type NoticeType, OrderFlowProvider, type OrderSnapshot, type PricingRole, Provider, type QuantityMark, type QuantityRule$1 as QuantityRule, type RatePolicy, type Registry, type Scalar, type ServiceEstimates, type ServiceFallback, type ServiceFallbacks, type ServiceFlag, type ServiceFlags, type ServiceIdRef, type ServiceProps, type ServicePropsNotice, type ServiceWhereClause, type ServiceWhereOp, type SnapshotContext, type SpeedEstimate, type Tag, type ThreadId, type TimeRangeEstimate, type Ui, type UiAnyOf, type UiArray, type UiBoolean, type UiNumber, type UiObject, type UiString, type UiValue, type UtilityLineItem, type UtilityMark, type UtilityMode, type ValidationCode, type ValidationError, type ValidatorOptions, type Viewport, type WithQuantityDefault, Wrapper, createInputRegistry, registerEntries, resolveInputDescriptor, useFormApi, useInputs, useOptionalFormApi, useOrderFlow, useOrderFlowContext };
+type Props$4 = {
+    className?: string;
+    fallbacks?: ServiceProps["fallbacks"];
+    props?: ServiceProps;
+    snapshot?: OrderSnapshot;
+    primaryServices?: DgpServiceMap;
+    eligibleServices?: DgpServiceMap;
+    settings?: FallbackSettings;
+    initialServiceId?: ServiceIdRef;
+    onSettingsChange?: FallbackEditorProviderProps["onSettingsChange"];
+    onSave?: FallbackEditorProviderProps["onSave"];
+    onValidate?: FallbackEditorProviderProps["onValidate"];
+    onReset?: FallbackEditorProviderProps["onReset"];
+};
+declare function FallbackEditor({ className, fallbacks, props, snapshot, primaryServices, eligibleServices, settings, initialServiceId, onSettingsChange, onSave, onValidate, onReset, }: Props$4): react_jsx_runtime.JSX.Element;
+
+declare function useFallbackEditor(): {
+    editor: FallbackEditor$1;
+    version: number;
+    serviceProps?: ServiceProps;
+    snapshot?: OrderSnapshot;
+    primaryServices: DgpServiceMap;
+    eligibleServices: DgpServiceMap;
+    activeServiceId?: ServiceIdRef;
+    setActiveServiceId: React.Dispatch<React.SetStateAction<ServiceIdRef | undefined>>;
+    activeTab: "registrations" | "settings";
+    setActiveTab: React.Dispatch<React.SetStateAction<"registrations" | "settings">>;
+    state: ReturnType<FallbackEditor$1["state"]>;
+    value: ReturnType<FallbackEditor$1["value"]>;
+    settings: FallbackSettings;
+    settingsSaving: boolean;
+    headerSaving: boolean;
+    headerValidating: boolean;
+    headerResetting: boolean;
+    saveSettings: (next: FallbackSettings) => Promise<FallbackSettings>;
+    saveFallbacks: () => Promise<ServiceProps["fallbacks"] | void>;
+    validateFallbacks: () => Promise<void>;
+    resetEditor: () => Promise<void>;
+    reset: () => void;
+    get: FallbackEditor$1["get"];
+    getScope: FallbackEditor$1["getScope"];
+    check: FallbackEditor$1["check"];
+    eligible: FallbackEditor$1["eligible"];
+    add: FallbackEditor$1["add"];
+    addMany: FallbackEditor$1["addMany"];
+    remove: FallbackEditor$1["remove"];
+    replace: FallbackEditor$1["replace"];
+    clear: FallbackEditor$1["clear"];
+};
+declare function useActiveFallbackRegistrations(): FallbackRegistration[];
+declare function usePrimaryServiceList(): {
+    id: ServiceIdRef;
+    name?: string;
+    platform?: string;
+    rate?: number;
+}[];
+declare function useEligibleServiceList(): {
+    id: ServiceIdRef;
+    name?: string;
+    platform?: string;
+    rate?: number;
+}[];
+
+type Item = {
+    id: ServiceIdRef;
+    name?: string;
+    platform?: string;
+    rate?: number;
+};
+type Props$3 = {
+    items: Item[];
+    selected: Set<string>;
+    onToggle: (id: ServiceIdRef) => void;
+    height?: number;
+    rowHeight?: number;
+    emptyText?: string;
+};
+declare function VirtualServiceList({ items, selected, onToggle, height, rowHeight, emptyText, }: Props$3): react_jsx_runtime.JSX.Element;
+
+type EditorSettings = {
+    requireConstraintFit: boolean;
+    ratePolicy: "lte_primary" | "ignore";
+    selectionStrategy: "priority" | "cheapest";
+    mode: "strict" | "dev";
+};
+type ServiceSummary = {
+    id: ServiceIdRef;
+    name: string;
+    platform?: string;
+    rate?: number;
+    flags?: Record<string, boolean>;
+    description?: string;
+};
+type RegistrationScope = "global" | "node";
+type RegistrationItem = {
+    primary: ServiceIdRef;
+    scope: RegistrationScope;
+    scopeId?: string;
+    nodeKind?: "tag" | "field" | "option";
+    nodeLabel?: string;
+    services: ServiceIdRef[];
+};
+type ValidationTone = "ok" | "warn" | "error";
+type ValidationMessage = {
+    primary: ServiceIdRef;
+    scope: RegistrationScope;
+    scopeId?: string;
+    candidate?: ServiceIdRef;
+    tone: ValidationTone;
+    title: string;
+    message: string;
+};
+type FallbackEditorData = {
+    services: ServiceSummary[];
+    registrations: RegistrationItem[];
+    diagnostics: ValidationMessage[];
+    settings: EditorSettings;
+};
+
+declare function FallbackDetailsPanel(): react_jsx_runtime.JSX.Element;
+
+type Props$2 = {
+    onReset?: () => void | Promise<void>;
+    onValidate?: () => void | Promise<void>;
+    onSave?: () => void | Promise<void>;
+    resetting?: boolean;
+    validating?: boolean;
+    saving?: boolean;
+};
+declare function FallbackEditorHeader({ onReset, onValidate, onSave, resetting, validating, saving, }: Props$2): react_jsx_runtime.JSX.Element;
+
+declare function FallbackSettingsPanel(): react_jsx_runtime.JSX.Element;
+
+type TabKey = "registrations" | "settings";
+type FallbackEditorProviderProps = {
+    children: React.ReactNode;
+    fallbacks?: ServiceProps["fallbacks"];
+    props?: ServiceProps;
+    snapshot?: OrderSnapshot;
+    primaryServices?: DgpServiceMap;
+    eligibleServices?: DgpServiceMap;
+    settings?: FallbackSettings;
+    initialServiceId?: ServiceIdRef;
+    initialTab?: TabKey;
+    onSettingsChange?: (next: FallbackSettings) => Promise<FallbackSettings> | FallbackSettings;
+    onSave?: (next: ServiceProps["fallbacks"]) => Promise<ServiceProps["fallbacks"] | void> | ServiceProps["fallbacks"] | void;
+    onValidate?: (next: ServiceProps["fallbacks"]) => Promise<void> | void;
+    onReset?: () => Promise<void> | void;
+};
+type FallbackEditorContextValue = {
+    editor: FallbackEditor$1;
+    version: number;
+    serviceProps?: ServiceProps;
+    snapshot?: OrderSnapshot;
+    primaryServices: DgpServiceMap;
+    eligibleServices: DgpServiceMap;
+    activeServiceId?: ServiceIdRef;
+    setActiveServiceId: React.Dispatch<React.SetStateAction<ServiceIdRef | undefined>>;
+    activeTab: TabKey;
+    setActiveTab: React.Dispatch<React.SetStateAction<TabKey>>;
+    state: ReturnType<FallbackEditor$1["state"]>;
+    value: ReturnType<FallbackEditor$1["value"]>;
+    settings: FallbackSettings;
+    settingsSaving: boolean;
+    headerSaving: boolean;
+    headerValidating: boolean;
+    headerResetting: boolean;
+    saveSettings: (next: FallbackSettings) => Promise<FallbackSettings>;
+    saveFallbacks: () => Promise<ServiceProps["fallbacks"] | void>;
+    validateFallbacks: () => Promise<void>;
+    resetEditor: () => Promise<void>;
+    reset: () => void;
+    get: FallbackEditor$1["get"];
+    getScope: FallbackEditor$1["getScope"];
+    check: FallbackEditor$1["check"];
+    eligible: FallbackEditor$1["eligible"];
+    add: FallbackEditor$1["add"];
+    addMany: FallbackEditor$1["addMany"];
+    remove: FallbackEditor$1["remove"];
+    replace: FallbackEditor$1["replace"];
+    clear: FallbackEditor$1["clear"];
+};
+declare function FallbackEditorProvider({ children, fallbacks, props, snapshot, primaryServices, eligibleServices, settings: initialSettings, initialServiceId, initialTab, onSettingsChange, onSave, onValidate, onReset, }: FallbackEditorProviderProps): react_jsx_runtime.JSX.Element;
+declare function useFallbackEditorContext(): FallbackEditorContextValue;
+
+declare function FallbackServiceSidebar(): react_jsx_runtime.JSX.Element;
+
+declare function FallbackRegistrationsPanel(): react_jsx_runtime.JSX.Element;
+
+type Props$1 = {
+    open: boolean;
+    onClose: () => void;
+    context: FallbackScopeRef | null;
+    primaryId?: ServiceIdRef;
+};
+declare function FallbackAddCandidatesDialog({ open, onClose, context, primaryId, }: Props$1): react_jsx_runtime.JSX.Element | null;
+
+type Props = {
+    open: boolean;
+    onClose: () => void;
+    onSelect: (context: FallbackScopeRef, primaryId: ServiceIdRef) => void;
+};
+declare function FallbackAddRegistrationDialog({ open, onClose, onSelect, }: Props): react_jsx_runtime.JSX.Element | null;
+
+export { type Adapter, type AdapterCtx, CanvasAPI, type EditorSettings, EventBus, type EventMap, FallbackAddCandidatesDialog, FallbackAddRegistrationDialog, FallbackDetailsPanel, FallbackEditor, type FallbackEditorData, FallbackEditorHeader, FallbackEditorProvider, type FallbackEditorProviderProps, FallbackRegistrationsPanel, FallbackServiceSidebar, FallbackSettingsPanel, type FormApi, FormProvider, type FormProviderProps, type FormSnapshot, type InputDescriptor, type InputKind, type InputVariant, type InputWrapperProps, OrderFlowProvider, Provider, type RegistrationItem, type RegistrationScope, type Registry, type ServiceSummary, type ValidationMessage, type ValidationTone, VirtualServiceList, Wrapper, createInputRegistry, registerEntries, resolveInputDescriptor, useActiveFallbackRegistrations, useEligibleServiceList, useFallbackEditor, useFallbackEditorContext, useFormApi, useInputs, useOptionalFormApi, useOrderFlow, useOrderFlowContext, usePrimaryServiceList };