@timeax/digital-service-engine 0.0.3 → 0.0.4

package/dist/core/index.d.cts

@@ -1,198 +1,3 @@
-type PricingRole = "base" | "utility";
-type FieldType = "custom" | (string & {});
-/** ── Marker types (live inside meta; non-breaking) ───────────────────── */
-type QuantityMark = {
-    quantity?: {
-        valueBy: "value" | "length" | "eval";
-        code?: string;
-        multiply?: number;
-        clamp?: {
-            min?: number;
-            max?: number;
-        };
-        fallback?: number;
-    };
-};
-type UtilityMark = {
-    utility?: {
-        rate: number;
-        mode: "flat" | "per_quantity" | "per_value" | "percent";
-        valueBy?: "value" | "length";
-        percentBase?: "service_total" | "base_service" | "all";
-        label?: string;
-    };
-};
-type WithQuantityDefault = {
-    quantityDefault?: number;
-};
-/** ---------------- Core schema (as you designed) ---------------- */
-interface BaseFieldUI {
-    name?: string;
-    label: string;
-    required?: boolean;
-    /** Host-defined prop names → runtime default values (untyped base) */
-    defaults?: Record<string, unknown>;
-}
-type FieldOption = {
-    id: string;
-    label: string;
-    value?: string | number;
-    service_id?: number;
-    pricing_role?: PricingRole;
-    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
-};
-type Field = BaseFieldUI & {
-    id: string;
-    type: FieldType;
-    bind_id?: string | string[];
-    name?: string;
-    options?: FieldOption[];
-    description?: string;
-    component?: string;
-    pricing_role?: PricingRole;
-    meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
-        multi?: boolean;
-    };
-} & ({
-    button?: false;
-    service_id?: undefined;
-} | ({
-    button: true;
-    service_id?: number;
-} & WithQuantityDefault));
-type ConstraintKey = string;
-type Tag = {
-    id: string;
-    label: string;
-    bind_id?: string;
-    service_id?: number;
-    includes?: string[];
-    excludes?: string[];
-    meta?: Record<string, unknown> & WithQuantityDefault;
-    /**
-     * Which flags are set for this tag. If a flag is not set, it's inherited from the nearest ancestor with a value set.
-     */
-    constraints?: Partial<Record<ConstraintKey, boolean>>;
-    /** Which ancestor defined the *effective* value for each flag (nearest source). */
-    constraints_origin?: Partial<Record<ConstraintKey, string>>;
-    /**
-     * Present only when a child explicitly set a different value but was overridden
-     * by an ancestor during normalisation.
-     */
-    constraints_overrides?: Partial<Record<ConstraintKey, {
-        from: boolean;
-        to: boolean;
-        origin: string;
-    }>>;
-};
-type ServiceProps = {
-    order_for_tags?: Record<string, string[]>;
-    filters: Tag[];
-    fields: Field[];
-    includes_for_buttons?: Record<string, string[]>;
-    excludes_for_buttons?: Record<string, string[]>;
-    schema_version?: string;
-    fallbacks?: ServiceFallback;
-    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";
-/**
- * “label” is lightweight + UI-friendly (best, sale, hot, etc).
- * Others remain semantic / governance oriented.
- */
-type NoticeKind = "label" | "warning" | "deprecation" | "compat" | "migration" | "policy";
-type NoticeTarget = {
-    scope: "global";
-} | {
-    scope: "node";
-    node_kind: "tag" | "field" | "option";
-    node_id: string;
-};
-interface ServicePropsNotice {
-    id: string;
-    type: NoticeType;
-    kind: NoticeKind;
-    severity: NoticeSeverity;
-    target: NoticeTarget;
-    title: string;
-    description?: string;
-    reason?: string;
-    marked_at?: string;
-    icon?: string;
-    color?: string;
-    meta?: Record<string, unknown>;
-}
-
-type NodeKind$1 = "tag" | "field" | "comment" | "option";
-type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
-type GraphNode = {
-    id: string;
-    kind: NodeKind$1;
-    bind_type?: "bound" | "utility" | null;
-    errors?: string[];
-    label: string;
-};
-type GraphEdge = {
-    from: string;
-    to: string;
-    kind: EdgeKind;
-    meta?: Record<string, unknown>;
-};
-type GraphSnapshot = {
-    nodes: GraphNode[];
-    edges: GraphEdge[];
-};
-
-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>;
-
 interface ButtonValue {
     id: string;
     value: string | number;
@@ -217,6 +22,7 @@ type UtilityLineItem = {
         evalCodeUsed?: boolean;
     };
 };
+type ServiceFallbacks = ServiceFallback;
 type FallbackDiagnostics = {
     scope: "node" | "global";
     nodeId?: string;
@@ -273,10 +79,7 @@ type OrderSnapshot = {
     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>>;
-    };
+    fallbacks?: ServiceFallbacks;
     utilities?: UtilityLineItem[];
     warnings?: {
         utility?: Array<{
@@ -295,6 +98,46 @@ type OrderSnapshot = {
     };
 };
 
+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 = {
     kind: "tag";
     id: string;
@@ -386,6 +229,246 @@ 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 */
+    nodes?: Record<NodeIdRef, ServiceIdRef[]>;
+    /** Primary→fallback list used when no node-scoped entry is present */
+    global?: Record<ServiceIdRef, ServiceIdRef[]>;
+};
+type FallbackEditorServiceMap = DgpServiceMap;
+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 FallbackEditorOptions = {
+    /**
+     * The editable payload.
+     * The editor clones this and never mutates the caller’s object directly.
+     */
+    fallbacks?: ServiceFallback;
+    /**
+     * Optional read-only source used to resolve node→service ownership
+     * and validate node-scoped registrations.
+     */
+    props?: ServiceProps;
+    /**
+     * Optional runtime context enhancer.
+     * Useful for ambiguous node contexts / diagnostics.
+     */
+    snapshot?: OrderSnapshot;
+    /**
+     * Optional service map used for rate / existence validation.
+     */
+    services?: FallbackEditorServiceMap;
+    /**
+     * Optional fallback policy.
+     */
+    settings?: FallbackSettings;
+};
+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) ───────────────────── */
+type QuantityMark = {
+    quantity?: {
+        valueBy: "value" | "length" | "eval";
+        code?: string;
+        multiply?: number;
+        clamp?: {
+            min?: number;
+            max?: number;
+        };
+        fallback?: number;
+    };
+};
+type UtilityMark = {
+    utility?: {
+        rate: number;
+        mode: "flat" | "per_quantity" | "per_value" | "percent";
+        valueBy?: "value" | "length";
+        percentBase?: "service_total" | "base_service" | "all";
+        label?: string;
+    };
+};
+type WithQuantityDefault = {
+    quantityDefault?: number;
+};
+/** ---------------- Core schema (as you designed) ---------------- */
+interface BaseFieldUI {
+    name?: string;
+    label: string;
+    required?: boolean;
+    /** Host-defined prop names → runtime default values (untyped base) */
+    defaults?: Record<string, unknown>;
+}
+type FieldOption = {
+    id: string;
+    label: string;
+    value?: string | number;
+    service_id?: number;
+    pricing_role?: PricingRole;
+    meta?: Record<string, unknown> & UtilityMark & WithQuantityDefault;
+};
+type Field = BaseFieldUI & {
+    id: string;
+    type: FieldType;
+    bind_id?: string | string[];
+    name?: string;
+    options?: FieldOption[];
+    description?: string;
+    component?: string;
+    pricing_role?: PricingRole;
+    meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
+        multi?: boolean;
+    };
+} & ({
+    button?: false;
+    service_id?: undefined;
+} | ({
+    button: true;
+    service_id?: number;
+} & WithQuantityDefault));
+type ConstraintKey = string;
+type Tag = {
+    id: string;
+    label: string;
+    bind_id?: string;
+    service_id?: number;
+    includes?: string[];
+    excludes?: string[];
+    meta?: Record<string, unknown> & WithQuantityDefault;
+    /**
+     * Which flags are set for this tag. If a flag is not set, it's inherited from the nearest ancestor with a value set.
+     */
+    constraints?: Partial<Record<ConstraintKey, boolean>>;
+    /** Which ancestor defined the *effective* value for each flag (nearest source). */
+    constraints_origin?: Partial<Record<ConstraintKey, string>>;
+    /**
+     * Present only when a child explicitly set a different value but was overridden
+     * by an ancestor during normalisation.
+     */
+    constraints_overrides?: Partial<Record<ConstraintKey, {
+        from: boolean;
+        to: boolean;
+        origin: string;
+    }>>;
+};
+type ServiceProps = {
+    order_for_tags?: Record<string, string[]>;
+    filters: Tag[];
+    fields: Field[];
+    includes_for_buttons?: Record<string, string[]>;
+    excludes_for_buttons?: Record<string, string[]>;
+    schema_version?: string;
+    fallbacks?: ServiceFallback;
+    name?: string;
+    notices?: ServicePropsNotice[];
+};
+type NoticeType = "public" | "private";
+type NoticeSeverity = "info" | "warning" | "error";
+/**
+ * “label” is lightweight + UI-friendly (best, sale, hot, etc).
+ * Others remain semantic / governance oriented.
+ */
+type NoticeKind = "label" | "warning" | "deprecation" | "compat" | "migration" | "policy";
+type NoticeTarget = {
+    scope: "global";
+} | {
+    scope: "node";
+    node_kind: "tag" | "field" | "option";
+    node_id: string;
+};
+interface ServicePropsNotice {
+    id: string;
+    type: NoticeType;
+    kind: NoticeKind;
+    severity: NoticeSeverity;
+    target: NoticeTarget;
+    title: string;
+    description?: string;
+    reason?: string;
+    marked_at?: string;
+    icon?: string;
+    color?: string;
+    meta?: Record<string, unknown>;
+}
+
+type NodeKind$1 = "tag" | "field" | "comment" | "option";
+type EdgeKind = "child" | "bind" | "include" | "exclude" | "error" | "anchor";
+type GraphNode = {
+    id: string;
+    kind: NodeKind$1;
+    bind_type?: "bound" | "utility" | null;
+    errors?: string[];
+    label: string;
+};
+type GraphEdge = {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    meta?: Record<string, unknown>;
+};
+type GraphSnapshot = {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+
 type NormaliseOptions = {
     /** default pricing role for fields/options when missing */
     defaultPricingRole?: PricingRole;
@@ -495,6 +578,10 @@ declare function getEligibleFallbacks(params: {
     unique?: boolean;
     limit?: number;
 }): ServiceIdRef[];
+declare function getFallbackRegistrationInfo(props: ServiceProps, nodeId: NodeIdRef): {
+    primary?: ServiceIdRef;
+    tagContexts: string[];
+};
 
 type BaseCandidate = {
     kind: "field" | "option";
@@ -644,4 +731,38 @@ type BuildOrderSelection = {
 };
 declare function buildOrderSnapshot(props: ServiceProps, builder: Builder, selection: BuildOrderSelection, services: DgpServiceMap, settings?: BuildOrderSnapshotSettings): OrderSnapshot;
 
-export { type AncestryHit, type AnyNode, type Builder, type BuilderOptions, type FailedFallbackContext, type FieldNode, type NodeIndex, type NodeKind, type NormaliseOptions, type OptionNode, type RateCoherenceDiagnostic, type RelKind, type TagNode, type UnknownNode, type WithAncestry, buildOrderSnapshot, collectFailedFallbacks, createBuilder, createNodeIndex, getEligibleFallbacks, normalise, resolveServiceFallback, validate, validateAsync, validateRateCoherenceDeep };
+/**
+ * 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 {
+    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;
+    /**
+     * Optional helper for picker UIs:
+     * shows candidates that the core fallback resolver would currently accept.
+     */
+    eligible(context: FallbackScopeRef, options?: {
+        exclude?: ServiceIdRef[];
+        unique?: boolean;
+        limit?: number;
+    }): ServiceIdRef[];
+}
+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 };