@timeax/digital-service-engine 0.0.5 → 0.0.7

package/dist/workspace/index.d.cts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Node, Edge } from '@xyflow/react';
 
 type TimeRangeEstimate = {
     min_seconds?: number;
@@ -58,7 +59,7 @@ type NodeRef$1 = {
 };
 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 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;
@@ -114,7 +115,10 @@ type ValidatorOptions = {
     fallbackSettings?: FallbackSettings;
 };
 type RatePolicy = {
+    kind: "eq_primary";
+} | {
     kind: "lte_primary";
+    pct: number;
 } | {
     kind: "within_pct";
     pct: number;
@@ -125,7 +129,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";
@@ -133,7 +137,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 */
@@ -142,6 +145,7 @@ type ServiceFallback = {
     global?: Record<ServiceIdRef, ServiceIdRef[]>;
 };
 
+type ServiceIdRef = IdType;
 type PricingRole = "base" | "utility";
 type FieldType = "custom" | (string & {});
 /** ── Marker types (live inside meta; non-breaking) ───────────────────── */
@@ -177,11 +181,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;
 };
@@ -194,6 +212,7 @@ type Field = BaseFieldUI & {
     description?: string;
     component?: string;
     pricing_role?: PricingRole;
+    validation?: FieldValidationRule[];
     meta?: Record<string, unknown> & QuantityMark & UtilityMark & {
         multi?: boolean;
     };
@@ -202,14 +221,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;
@@ -330,140 +349,9 @@ type CommentThread = {
     _sync?: "pending" | "synced" | "error";
 };
 
-type Viewport = {
-    x: number;
-    y: number;
-    zoom: number;
-};
-type NodePos = {
-    x: number;
-    y: number;
-};
-type NodePositions = Record<string, NodePos>;
-type DraftWire = {
-    from: string;
-    kind: EdgeKind;
-};
-type CanvasState = {
-    graph: GraphSnapshot;
-    positions: NodePositions;
-    selection: Set<string>;
-    highlighted: Set<string>;
-    hoverId?: string;
-    viewport: Viewport;
-    draftWire?: DraftWire;
-    version: number;
-};
-type CanvasEvents = {
-    "graph:update": GraphSnapshot;
-    "state:change": CanvasState;
-    "selection:change": {
-        ids: string[];
-    };
-    "viewport:change": Viewport;
-    "hover:change": {
-        id?: string;
-    };
-    "wire:preview": {
-        from: string;
-        to?: string;
-        kind: EdgeKind;
-    };
-    "wire:commit": {
-        from: string;
-        to: string;
-        kind: EdgeKind;
-    };
-    "wire:cancel": {
-        from: string;
-    };
-    error: {
-        message: string;
-        code?: string;
-        meta?: any;
-    };
-    "comment:thread:create": {
-        thread: CommentThread;
-    };
-    "comment:thread:update": {
-        thread: CommentThread;
-    };
-    "comment:thread:delete": {
-        threadId: string;
-    };
-    "comment:message:create": {
-        threadId: string;
-        message: CommentMessage;
-    };
-    "comment:resolve": {
-        thread: CommentThread;
-        resolved: boolean;
-    };
-    "comment:move": {
-        thread: CommentThread;
-    };
-    "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 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>;
-};
-
 /** 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:
@@ -488,9 +376,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 */
@@ -582,6 +467,27 @@ interface NodeIndex {
     getOption(id: string): OptionNode | undefined;
 }
 
+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 Env = "client" | "workspace";
 type VisibleGroup = {
     tagId?: string;
@@ -664,6 +570,92 @@ declare class Selection {
     private findOptionById;
 }
 
+type CatalogId = string;
+type CatalogServiceId = string | number;
+type CatalogSmartRule = {
+    type: "service-field";
+    field: string;
+    op: "eq" | "neq" | "in" | "contains" | "startsWith" | "endsWith" | "gt" | "gte" | "lt" | "lte" | "between" | "exists";
+    value?: unknown;
+    min?: number;
+    max?: number;
+} | {
+    type: "policy-family";
+    key: string;
+    value?: unknown;
+} | {
+    type: "compatibility";
+    scope: "tag" | "field" | "option" | "visible-group";
+    targetId?: string;
+    mode: "safe" | "assignable" | "same-family" | "conflicts";
+};
+type CatalogNodeBase = {
+    id: CatalogId;
+    label: string;
+    parentId?: CatalogId;
+    description?: string;
+    order?: number;
+    color?: string;
+    icon?: string;
+    collapsed?: boolean;
+    meta?: Record<string, unknown>;
+};
+type CatalogGroupNode = CatalogNodeBase & {
+    kind: "group";
+    serviceIds: CatalogServiceId[];
+};
+type CatalogSmartGroupNode = CatalogNodeBase & {
+    kind: "smart-group";
+    rules: CatalogSmartRule[];
+    match: "all" | "any";
+    resolvedServiceIds?: CatalogServiceId[];
+    resolvedAt?: number;
+};
+type CatalogNode = CatalogGroupNode | CatalogSmartGroupNode;
+type CatalogViewMode = "all" | "grouped" | "smart" | "assigned";
+interface ServiceCatalogState {
+    version: 1;
+    nodes: CatalogNode[];
+    activeNodeId?: CatalogId;
+    expandedIds?: CatalogId[];
+    pinnedNodeIds?: CatalogId[];
+    selectedServiceId?: CatalogServiceId;
+    viewMode?: CatalogViewMode;
+    meta?: Record<string, unknown>;
+}
+
+type EditorEvents = {
+    "editor:command": {
+        name: string;
+        payload?: any;
+    };
+    "editor:change": {
+        props: ServiceProps;
+        reason: string;
+        command?: string;
+        snapshot: EditorSnapshot;
+    };
+    "editor:undo": {
+        stackSize: number;
+        index: number;
+    };
+    "editor:redo": {
+        stackSize: number;
+        index: number;
+    };
+    "editor:error": {
+        message: string;
+        code?: string;
+        meta?: any;
+    };
+    "catalog:change": {
+        catalog?: ServiceCatalogState;
+        reason: string;
+    };
+    "catalog:active-change": {
+        activeNodeId?: string;
+    };
+};
 type Command = {
     name: string;
     do(): void;
@@ -681,12 +673,134 @@ type EditorOptions = {
     selectionProps?: SelectionOptions;
 };
 
-type PolicyDiagnostic = {
-    ruleIndex: number;
-    ruleId?: string;
-    severity: "error" | "warning";
-    message: string;
-    path?: string;
+type Viewport = {
+    x: number;
+    y: number;
+    zoom: number;
+};
+type NodePos = {
+    x: number;
+    y: number;
+};
+type NodePositions = Record<string, NodePos>;
+type DraftWire = {
+    from: string;
+    kind: EdgeKind;
+};
+type CanvasState = {
+    graph: GraphSnapshot;
+    positions: NodePositions;
+    selection: Set<string>;
+    highlighted: Set<string>;
+    hoverId?: string;
+    viewport: Viewport;
+    draftWire?: DraftWire;
+    version: number;
+};
+type CanvasEvents = {
+    "graph:update": GraphSnapshot;
+    "state:change": CanvasState;
+    "selection:change": {
+        ids: string[];
+    };
+    "viewport:change": Viewport;
+    "hover:change": {
+        id?: string;
+    };
+    "wire:preview": {
+        from: string;
+        to?: string;
+        kind: EdgeKind;
+    };
+    "wire:commit": {
+        from: string;
+        to: string;
+        kind: EdgeKind;
+    };
+    "wire:cancel": {
+        from: string;
+    };
+    error: {
+        message: string;
+        code?: string;
+        meta?: any;
+    };
+    "comment:thread:create": {
+        thread: CommentThread;
+    };
+    "comment:thread:update": {
+        thread: CommentThread;
+    };
+    "comment:thread:delete": {
+        threadId: string;
+    };
+    "comment:message:create": {
+        threadId: string;
+        message: CommentMessage;
+    };
+    "comment:resolve": {
+        thread: CommentThread;
+        resolved: boolean;
+    };
+    "comment:move": {
+        thread: CommentThread;
+    };
+    "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;
+    };
+} & EditorEvents;
+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[];
+    catalog?: ServiceCatalogState;
+    meta?: Record<string, unknown>;
 };
 
 interface BackendError {
@@ -1192,7 +1306,7 @@ interface CommentsSliceApi {
     readonly threads: Loadable<readonly CommentThread[]>;
     readonly refreshThreads: (params?: Readonly<{
         branchId?: string;
-    }>) => Promise<void>;
+    }>) => Promise<BackendResult<readonly CommentThread[]>>;
     readonly createThread: (input: Readonly<{
         anchor?: CommentAnchor;
         body: string;
@@ -1242,7 +1356,7 @@ type PoliciesSlice = {
     readonly refreshPolicies: (params?: Readonly<{
         since?: number | string;
         branchId?: string;
-    }>) => Promise<void>;
+    }>) => Promise<BackendResult<readonly DynamicRule[]>>;
     readonly savePolicies: (rules: readonly DynamicRule[], params?: Readonly<{
         branchId?: string;
     }>) => Result<Readonly<{
@@ -1270,6 +1384,32 @@ type RunErr = {
     errors: BackendError[];
 };
 type RunResult = RunOk | RunErr;
+type WorkspaceBootSection = "authors" | "permissions" | "branches" | "services" | "participants" | "templates" | "snapshotPointers" | "snapshotBody" | "policies" | "comments";
+type WorkspaceBootSectionStatus = "idle" | "loading" | "success" | "error";
+interface WorkspaceBootSectionState {
+    readonly status: WorkspaceBootSectionStatus;
+    readonly error?: BackendError;
+    readonly updatedAt?: number;
+}
+interface WorkspaceBootState {
+    readonly sections: Readonly<Record<WorkspaceBootSection, WorkspaceBootSectionState>>;
+    readonly isBooting: boolean;
+    readonly isReady: boolean;
+    readonly hasErrors: boolean;
+    readonly hasPartialFailure: boolean;
+    readonly lastError?: BackendError;
+    readonly errorsBySection: Readonly<Partial<Record<WorkspaceBootSection, BackendError>>>;
+    readonly isSeededView: boolean;
+    readonly isLiveConfirmed: boolean;
+    readonly completedSections: number;
+    readonly succeededSections: number;
+    readonly failedSections: number;
+    readonly totalSections: number;
+    retryAll(opts?: {
+        strict?: boolean;
+    }): Promise<RunResult>;
+    retrySection(section: WorkspaceBootSection): Promise<BackendResult<void>>;
+}
 interface WorkspaceProviderProps {
     readonly backend: WorkspaceBackend;
     readonly actor: Actor;
@@ -1325,6 +1465,7 @@ interface SnapshotSlice {
 interface WorkspaceAPI {
     readonly info: WorkspaceInfo;
     readonly actor: Actor;
+    readonly boot: WorkspaceBootState;
     readonly authors: Loadable<readonly Author[]>;
     readonly permissions: Loadable<PermissionsMap>;
     readonly branches: BranchesSlice;
@@ -1343,7 +1484,11 @@ interface WorkspaceAPI {
         branches(): Promise<void>;
         services(): Promise<void>;
         /** Current branch-scoped refreshers */
-        branchContext(): Promise<void>;
+        branchContext(opts?: Readonly<{
+            branchId?: string;
+            strict?: boolean;
+            includeWorkspaceData?: boolean;
+        }>): Promise<void>;
         templates(params?: Partial<Pick<TemplatesListParams, "branchId" | "since">>): Promise<void>;
         participants(params?: Partial<{
             branchId: string;
@@ -1413,6 +1558,7 @@ interface WorkspaceAPI {
 declare const WorkspaceContext: React.Context<WorkspaceAPI | null>;
 declare function useWorkspace(): WorkspaceAPI;
 declare function useWorkspaceMaybe(): WorkspaceAPI | null;
+declare function useWorkspaceBoot(): WorkspaceBootState;
 
 declare function WorkspaceProvider(props: WorkspaceProviderProps): React.JSX.Element;
 
@@ -1497,9 +1643,39 @@ type DuplicateOptions = {
     nameStrategy?: (old?: string) => string | undefined;
     optionIdStrategy?: (old: string) => string;
 };
+type EditorNodeLookup = {
+    kind: "tag";
+    data?: Tag;
+    owners: {
+        parentTagId?: string;
+    };
+} | {
+    kind: "field";
+    data?: Field;
+    owners: {
+        bindTagIds: string[];
+    };
+} | {
+    kind: "option";
+    data?: any;
+    owners: {
+        fieldId?: string;
+    };
+};
+type QuantityRule = {
+    valueBy: "value" | "length" | "eval";
+    code?: string;
+    multiply?: number;
+    clamp?: {
+        min?: number;
+        max?: number;
+    };
+    fallback?: number;
+};
+
 declare class Editor {
-    private builder;
-    private api;
+    private readonly builder;
+    private readonly api;
     private readonly opts;
     private history;
     private index;
@@ -1507,6 +1683,7 @@ declare class Editor {
     private txnLabel?;
     private stagedBefore?;
     private _lastPolicyDiagnostics?;
+    private catalog?;
     constructor(builder: Builder, api: CanvasAPI, opts?: EditorOptions);
     isTagId(id: string): boolean;
     isFieldId(id: string): boolean;
@@ -1518,31 +1695,9 @@ declare class Editor {
     redo(): boolean;
     clearService(id: string): void;
     duplicate(ref: NodeRef, opts?: DuplicateOptions): string;
-    /**
-     * Update the display label for a node and refresh the graph so node labels stay in sync.
-     * Supports: tag ("t:*"), field ("f:*"), option ("o:*").
-     * IDs are NOT changed; only the human-readable label.
-     */
     reLabel(id: string, nextLabel: string): void;
-    /**
-     * Assign or change a field's `name`. Only allowed when the field (and its options) have NO service mapping.
-     * - If `nextName` is empty/blank → removes the `name`.
-     * - Emits an error if the field or any of its options carry a `service_id`.
-     * - Emits an error if `nextName` collides with an existing field's name (case-sensitive).
-     */
     setFieldName(fieldId: string, nextName: string | null | undefined): void;
     getLastPolicyDiagnostics(): PolicyDiagnostic[] | undefined;
-    private duplicateTag;
-    private duplicateField;
-    private duplicateOption;
-    private uniqueId;
-    private uniqueOptionId;
-    /**
-     * Reorder a node:
-     * - Tag: among its siblings (same bind_id) inside filters[]
-     * - Field: inside order_for_tags[scopeTagId] (you must pass scopeTagId)
-     * - Option: use placeOption() instead
-     */
     placeNode(id: string, opts: {
         scopeTagId?: string;
         beforeId?: string;
@@ -1557,20 +1712,20 @@ declare class Editor {
     addOption(fieldId: string, input: {
         id?: string;
         label: string;
-        service_id?: number;
+        service_id?: ServiceIdRef;
         pricing_role?: "base" | "utility" | "addon";
         [k: string]: any;
     }): string;
     updateOption(optionId: string, patch: Partial<{
         label: string;
-        service_id: number;
+        service_id: ServiceIdRef;
         pricing_role: "base" | "utility" | "addon";
     } & Record<string, any>>): void;
     removeOption(optionId: string): void;
     editLabel(id: string, label: string): void;
     editName(fieldId: string, name: string | undefined): void;
     setService(id: string, input: {
-        service_id?: number;
+        service_id?: ServiceIdRef;
         pricing_role?: "base" | "utility";
     }): void;
     addTag(partial: Omit<Tag, "id" | "label"> & {
@@ -1579,6 +1734,11 @@ declare class Editor {
     }): void;
     updateTag(id: string, patch: Partial<Tag>): void;
     removeTag(id: string): void;
+    addNotice(input: Omit<ServicePropsNotice, "id"> & {
+        id?: string;
+    }): string;
+    updateNotice(id: string, patch: Partial<ServicePropsNotice>): void;
+    removeNotice(id: string): void;
     addField(partial: Omit<Field, "id" | "label" | "type"> & {
         id?: string;
         label: string;
@@ -1587,45 +1747,76 @@ declare class Editor {
     updateField(id: string, patch: Partial<Field>): void;
     removeField(id: string): void;
     remove(id: string): void;
-    getNode(id: string): {
-        kind: "tag";
-        data?: Tag;
-        owners: {
-            parentTagId?: string;
-        };
-    } | {
-        kind: "field";
-        data?: Field;
-        owners: {
-            bindTagIds: string[];
-        };
-    } | {
-        kind: "option";
-        data?: any;
-        owners: {
-            fieldId?: string;
-        };
-    };
+    getNode(id: string): EditorNodeLookup;
     getFieldQuantityRule(id: string): QuantityRule | undefined;
     setFieldQuantityRule(id: string, rule: unknown): void;
     clearFieldQuantityRule(id: string): void;
-    /** Walk ancestors for a tag and detect if parent→child would create a cycle */
-    private wouldCreateTagCycle;
-    private wouldCreateIncludeExcludeCycle;
     include(receiverId: string, idOrIds: string | string[]): void;
     exclude(receiverId: string, idOrIds: string | string[]): void;
     connect(kind: WireKind, fromId: string, toId: string): void;
     disconnect(kind: WireKind, fromId: string, toId: string): void;
     setConstraint(tagId: string, flag: string, value: boolean | undefined): void;
-    /**
-     * Clear a constraint override by removing the local constraint that conflicts with an ancestor.
-     */
     clearConstraintOverride(tagId: string, flag: string): void;
-    /**
-     * Clear a constraint from a tag and its descendants.
-     * If a descendant has an override, it assigns that override's value as local.
-     */
     clearConstraint(tagId: string, flag: string): void;
+    getFieldValidation(id: string): FieldValidationRule[] | undefined;
+    setFieldValidation(id: string, rules: unknown): void;
+    clearFieldValidation(id: string): void;
+    getCatalog(): ServiceCatalogState | undefined;
+    setCatalog(next?: ServiceCatalogState): void;
+    clearCatalog(): void;
+    ensureCatalog(): ServiceCatalogState;
+    createCatalogGroup(input: {
+        id?: string;
+        label: string;
+        parentId?: string;
+        description?: string;
+        serviceIds?: CatalogServiceId[];
+        collapsed?: boolean;
+        order?: number;
+        color?: string;
+        icon?: string;
+    }): string;
+    createSmartCatalogGroup(input: {
+        id?: string;
+        label: string;
+        parentId?: string;
+        description?: string;
+        rules: CatalogSmartRule[];
+        match?: "all" | "any";
+        collapsed?: boolean;
+        order?: number;
+        color?: string;
+        icon?: string;
+    }): string;
+    updateCatalogNode(id: CatalogId, patch: Partial<Omit<CatalogNode, "id" | "kind">>): void;
+    removeCatalogNode(id: CatalogId, opts?: {
+        cascade?: boolean;
+    }): void;
+    moveCatalogNode(nodeId: CatalogId, opts: {
+        parentId?: CatalogId;
+        beforeId?: CatalogId;
+        afterId?: CatalogId;
+        index?: number;
+    }): void;
+    assignServicesToCatalogGroup(nodeId: CatalogId, serviceIds: CatalogServiceId[], mode?: "append" | "replace" | "remove"): void;
+    setActiveCatalogNode(id?: CatalogId): void;
+    setCatalogViewMode(mode: ServiceCatalogState["viewMode"]): void;
+    setSelectedCatalogService(serviceId?: CatalogServiceId): void;
+    toggleCatalogExpanded(id: CatalogId): void;
+    setCatalogExpanded(id: CatalogId, expanded: boolean): void;
+    toggleCatalogPinned(id: CatalogId): void;
+    resolveSmartCatalogGroup(nodeId: CatalogId, candidates: CatalogServiceId[], matchers: {
+        serviceField?: (candidate: CatalogServiceId, rule: Extract<CatalogSmartRule, {
+            type: "service-field";
+        }>) => boolean;
+        policyFamily?: (candidate: CatalogServiceId, rule: Extract<CatalogSmartRule, {
+            type: "policy-family";
+        }>) => boolean;
+        compatibility?: (candidate: CatalogServiceId, rule: Extract<CatalogSmartRule, {
+            type: "compatibility";
+        }>) => boolean;
+    }): CatalogServiceId[];
+    private replaceCatalog;
     private replaceProps;
     private patchProps;
     private afterMutation;
@@ -1633,47 +1824,17 @@ declare class Editor {
     private makeSnapshot;
     private loadSnapshot;
     private pushHistory;
-    private genId;
     private emit;
-    /**
-     * Suggest/filter candidate services against the current visible-group
-     * (single tag) context.
-     *
-     * - Excludes services already used in this group.
-     * - Applies capability presence, tag constraints, rate policy, and compiled policies.
-     *
-     * @param candidates    service ids to evaluate
-     * @param ctx
-     * @param ctx.tagId     active visible-group tag id
-     * @param ctx.usedServiceIds  services already selected for this visible group (first is treated as "primary" for rate policy)
-     * @param ctx.effectiveConstraints  effective constraints for the active tag (dripfeed/refill/cancel)
-     * @param ctx.policies  raw JSON policies (will be compiled via compilePolicies)
-     * @param ctx.fallback  fallback/rate settings (defaults applied if omitted)
-     */
     filterServicesForVisibleGroup(candidates: Array<number | string>, ctx: {
         tagId: string;
+        selectedButtons?: string[];
         usedServiceIds: Array<number | string>;
         effectiveConstraints?: Partial<Record<"refill" | "cancel" | "dripfeed", boolean>>;
         policies?: unknown;
         fallback?: FallbackSettings;
     }): ServiceCheck[];
+    private moduleCtx;
 }
-type QuantityRule = {
-    valueBy: "value" | "length" | "eval";
-    code?: string;
-};
-type ServiceCheck = {
-    id: number | string;
-    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;
-};
 
 declare class CanvasAPI {
     private bus;
@@ -1684,8 +1845,8 @@ declare class CanvasAPI {
     readonly comments: CommentsAPI;
     readonly selection: Selection;
     constructor(builder: Builder, opts?: CanvasOptions & CanvasBackendOptions);
-    on: <K extends keyof CanvasEvents>(event: K, handler: (payload: CanvasEvents[K]) => void) => () => void;
-    once: <K extends keyof CanvasEvents>(event: K, handler: (payload: CanvasEvents[K]) => void) => () => void;
+    on: <K extends "error" | "graph:update" | "state:change" | "selection:change" | "viewport:change" | "hover:change" | "wire:preview" | "wire:commit" | "wire:cancel" | "comment:thread:create" | "comment:thread:update" | "comment:thread:delete" | "comment:message:create" | "comment:resolve" | "comment:move" | "comment:select" | "edge:change" | "comment:sync" | keyof EditorEvents>(event: K, handler: (payload: CanvasEvents[K]) => void) => () => void;
+    once: <K extends "error" | "graph:update" | "state:change" | "selection:change" | "viewport:change" | "hover:change" | "wire:preview" | "wire:commit" | "wire:cancel" | "comment:thread:create" | "comment:thread:update" | "comment:thread:delete" | "comment:message:create" | "comment:resolve" | "comment:move" | "comment:select" | "edge:change" | "comment:sync" | keyof EditorEvents>(event: K, handler: (payload: CanvasEvents[K]) => void) => () => void;
     emit<K extends keyof CanvasEvents>(event: K, payload: CanvasEvents[K]): void;
     snapshot(): CanvasState;
     getGraph(): GraphSnapshot;
@@ -1694,7 +1855,7 @@ declare class CanvasAPI {
     refreshGraph(): void;
     setPositions(pos: NodePositions): void;
     setPosition(id: string, x: number, y: number): void;
-    select(ids: string[] | Set<string>): void;
+    select(ids: string[] | Set<string>, primary?: string): void;
     addToSelection(ids: string[] | Set<string>): void;
     toggleSelection(id: string): void;
     clearSelection(): void;
@@ -1708,7 +1869,6 @@ declare class CanvasAPI {
     cancelWire(): void;
     private bump;
     dispose(): void;
-    undo(): void;
     private edgeRel;
     getEdgeRel(): EdgeKind;
     setEdgeRel(rel: EdgeKind): void;
@@ -1739,46 +1899,25 @@ declare class CanvasAPI {
     getServiceProps(): ServiceProps;
 }
 
-/** Managed props (back-compat): host provides the API instance. */
 type CanvasProviderManagedProps = {
     api: CanvasAPI;
     children: ReactNode;
 };
-/** Workspace-aware props: host omits `api`, we attach to Workspace on demand. */
 type CanvasProviderWorkspaceProps = {
     children: ReactNode;
-    /** Optional Builder options (e.g., historyLimit, serviceMap if you already have one). */
     builderOpts?: BuilderOptions;
-    /** Canvas view/backend options for CanvasAPI ctor. */
     canvasOpts?: CanvasOptions & CanvasBackendOptions;
-    /** If false, we won’t attempt to read Workspace; will throw if no api is provided. */
     attachToWorkspace?: boolean;
 };
 type CanvasProviderProps = CanvasProviderManagedProps | CanvasProviderWorkspaceProps;
-/**
- * CanvasProvider
- * - Managed mode (existing): <CanvasProvider api={api}>{...}</CanvasProvider>
- * - Workspace-aware mode (new): if no `api` and inside a Workspace, auto-create Builder+CanvasAPI and load snapshot props.
- */
 declare function CanvasProvider(props: CanvasProviderProps): react_jsx_runtime.JSX.Element;
 declare function useCanvasAPI(): CanvasAPI;
-/**
- * Create & memoize a CanvasAPI from a Builder.
- * - Disposes the previous API when builder changes.
- * - Accepts both view/state options and backend options.
- * - Warns (DEV only) if `opts` identity is changing every render.
- */
 declare function useCanvasFromBuilder(builder: Builder, opts?: CanvasOptions & CanvasBackendOptions): CanvasAPI;
-/**
- * Use an existing CanvasAPI instance without creating/disposing anything.
- * Useful when the host fully manages the API lifecycle (e.g., from a parent).
- */
 declare function useCanvasFromExisting(api: CanvasAPI): CanvasAPI;
 type UseCanvasOwnedReturn = {
     api: CanvasAPI;
     builder: Builder;
 };
-/** Creates a Builder once, loads initial props, and owns the CanvasAPI lifecycle. */
 declare function useCanvasOwned(initialProps?: ServiceProps, canvasOpts?: CanvasOptions & CanvasBackendOptions, builderOpts?: BuilderOptions): UseCanvasOwnedReturn;
 
 /** Tree node */
@@ -1937,6 +2076,34 @@ interface CreateMemoryWorkspaceBackendOptions {
 
 declare function createMemoryWorkspaceBackend(opts: CreateMemoryWorkspaceBackendOptions): WorkspaceBackend;
 
+type AdapterOptions = {
+    beforeConnect?: (arg: {
+        from: string;
+        to: string;
+        kind: EdgeKind;
+        api: CanvasAPI;
+    }) => {
+        ok: boolean;
+        reason?: string;
+    };
+    afterConnect?: (arg: {
+        from: string;
+        to: string;
+        kind: EdgeKind;
+        created: boolean;
+        api: CanvasAPI;
+    }) => void;
+    allowEdgeDelete?: boolean;
+    enableShortcuts?: boolean;
+    snapToGrid?: boolean | {
+        x: number;
+        y: number;
+    };
+    throttleMs?: number;
+    nodeDecorators?: (nodeId: string) => Partial<Node>;
+    edgeDecorators?: (edgeId: string) => Partial<Edge>;
+};
+
 type ToolKind = 'command' | 'toggle' | 'mode' | 'menu';
 type ToolGroup = 'relation' | 'viewport' | 'view' | 'edit' | (string & {});
 type EnabledState = boolean | {
@@ -1944,6 +2111,7 @@ type EnabledState = boolean | {
     reason?: string;
 };
 type ToolbarIcon = string | ((active: boolean, disabled: boolean) => React__default.ReactNode);
+type LabelPlacement = 'tooltip' | 'inline' | 'below' | 'none';
 type ToolDescriptor = {
     id: string;
     kind: ToolKind;
@@ -1992,6 +2160,69 @@ type ToolsConfig = {
     hidden?: string[];
 };
 
+type ToolbarProps = {
+    api: CanvasAPI;
+    mode?: "dev" | "prod";
+    showGrid: boolean;
+    setShowGrid: (v: boolean) => void;
+    showMiniMap: boolean;
+    setShowMiniMap: (v: boolean) => void;
+    tools?: ToolsConfig;
+    /** Default: 'tooltip' (hidden label, shown as native tooltip) */
+    labelPlacement?: LabelPlacement;
+    /** Optional custom button renderer */
+    renderButton?: (t: ToolRender, key: string) => React__default.ReactNode;
+};
+type ToolRender = {
+    id: string;
+    label?: string;
+    icon?: React__default.ReactNode;
+    active: boolean;
+    disabled: boolean;
+    disabledReason?: string;
+    onClick: () => void;
+    group?: string;
+    hasMenu?: boolean;
+    open?: boolean;
+    onToggleMenu?: () => void;
+    children?: ToolRender[];
+};
+declare function Toolbar({ api, mode, showGrid, setShowGrid, showMiniMap, setShowMiniMap, tools, labelPlacement, renderButton, }: ToolbarProps): react_jsx_runtime.JSX.Element;
+
+type ReactFlowCanvasProps = {
+    api: CanvasAPI;
+    options?: AdapterOptions;
+    showToolbar?: boolean;
+    tools?: ToolsConfig;
+    labelPlacement?: LabelPlacement;
+    renderTool?: Parameters<typeof Toolbar>[0]["renderButton"];
+    initialShowGrid?: boolean;
+    initialShowMiniMap?: boolean;
+    /** absolute position classes relative to the ReactFlow canvas */
+    toolbarPositionClassName?: string;
+    children?: React__default.ReactNode;
+};
+declare function Canvas({ api, options, showToolbar, tools, labelPlacement, renderTool, initialShowGrid, initialShowMiniMap, toolbarPositionClassName, children, }: ReactFlowCanvasProps): react_jsx_runtime.JSX.Element;
+
+type FlowCanvasProps = {
+    tools?: ToolsConfig;
+    /** 'dev' enables richer UX; 'prod' can hide some helpers */
+    mode?: "dev" | "prod";
+    /** Show/position the toolbar (inside the ReactFlow surface) */
+    showToolbar?: boolean;
+    toolbarPositionClassName?: string;
+    /** How labels render on buttons: tooltip | inline | below | none */
+    labelPlacement?: LabelPlacement;
+    /** Pass custom renderer for individual tool buttons */
+    renderTool?: React__default.ComponentProps<typeof Canvas>["renderTool"];
+    /** Initial layer toggles */
+    initialShowGrid?: boolean;
+    initialShowMiniMap?: boolean;
+    /** Adapter options (snapping etc.) */
+    options?: AdapterOptions;
+    children?: React__default.ReactNode;
+};
+
 /**
  * Props for the Workspace wrapper. Mirrors WorkspaceProvider options.
  */
@@ -2021,4 +2252,4 @@ interface WorkspaceProps {
  */
 declare function Workspace(props: WorkspaceProps): React.JSX.Element;
 
-export { type Actor, type Author, type AuthorsBackend, type BackendError, type BackendResult, type BackendScope, type Branch, type BranchAccessBackend, type BranchParticipant, type BranchesBackend, type BranchesSlice, CanvasProvider, type CanvasSelection, type ClearTarget, type CommentsBackend, type Commit, type CreateMemoryWorkspaceBackendOptions, type Draft, type ErrorKind, type ErrorLog, type FieldTemplate, type LiveOptions, type Loadable, type MemoryBackendSeed, type MemorySeedBranchSnapshots, type MemorySeedComments, type MemorySeedParticipants, type MergeResult, type MergedErrors, type PermissionsBackend, type PermissionsMap, type PoliciesBackend, type PoliciesLoadResult, type PolicyScope, type Result, type ServiceSnapshot, type ServicesBackend, type ServicesInput, type SnapshotSlice, type SnapshotsBackend, type SnapshotsLoadResult, type TemplateCreateInput, type TemplateUpdatePatch, type TemplateValidator, type TemplatesBackend, type TemplatesListParams, type TreeNode, type UseCanvasReturn, type UseErrorsOptions, type UseErrorsReturn, type ValidationRow, Workspace, type WorkspaceAPI, type WorkspaceBackend, WorkspaceContext, type WorkspaceEvent, type WorkspaceInfo, type WorkspaceLiveAdapter, type WorkspaceLiveAdapterContext, type WorkspaceLiveAdapterHandlers, type WorkspaceLiveAdapterRegistry, type WorkspaceLiveStatus, type WorkspaceLiveTick, type WorkspaceProps, WorkspaceProvider, type WorkspaceProviderProps, createMemoryWorkspaceBackend, createPollAdapter, useCanvas, useCanvasAPI, useCanvasFromBuilder, useCanvasFromExisting, useCanvasOwned, useErrors, useWorkspace, useWorkspaceMaybe };
+export { type Actor, type AdapterOptions, type Author, type AuthorsBackend, type BackendError, type BackendResult, type BackendScope, type Branch, type BranchAccessBackend, type BranchParticipant, type BranchesBackend, type BranchesSlice, Canvas, CanvasProvider, type CanvasSelection, type ClearTarget, type CommentsBackend, type Commit, type CreateMemoryWorkspaceBackendOptions, type Draft, type ErrorKind, type ErrorLog, type FieldTemplate, type FlowCanvasProps, type LabelPlacement, type LiveOptions, type Loadable, type MemoryBackendSeed, type MemorySeedBranchSnapshots, type MemorySeedComments, type MemorySeedParticipants, type MergeResult, type MergedErrors, type PermissionsBackend, type PermissionsMap, type PoliciesBackend, type PoliciesLoadResult, type PolicyScope, type Result, type ServiceSnapshot, type ServicesBackend, type ServicesInput, type SnapshotSlice, type SnapshotsBackend, type SnapshotsLoadResult, type TemplateCreateInput, type TemplateUpdatePatch, type TemplateValidator, type TemplatesBackend, type TemplatesListParams, type ToolsConfig, type TreeNode, type UseCanvasReturn, type UseErrorsOptions, type UseErrorsReturn, type ValidationRow, Workspace, type WorkspaceAPI, type WorkspaceBackend, type WorkspaceBootSection, type WorkspaceBootSectionState, type WorkspaceBootSectionStatus, type WorkspaceBootState, WorkspaceContext, type WorkspaceEvent, type WorkspaceInfo, type WorkspaceLiveAdapter, type WorkspaceLiveAdapterContext, type WorkspaceLiveAdapterHandlers, type WorkspaceLiveAdapterRegistry, type WorkspaceLiveStatus, type WorkspaceLiveTick, type WorkspaceProps, WorkspaceProvider, type WorkspaceProviderProps, createMemoryWorkspaceBackend, createPollAdapter, useCanvas, useCanvasAPI, useCanvasFromBuilder, useCanvasFromExisting, useCanvasOwned, useErrors, useWorkspace, useWorkspaceBoot, useWorkspaceMaybe };