@ultrst-armada/kloks 0.0.0-stage → 1.0.0

package/packages/state-graph/dist/rules/index.d.ts

@@ -0,0 +1,86 @@
+import { c as CompatibilityRule, C as CompatibilityResolution } from '../CompatibilityMatrix-DX307_vS.js';
+export { a as CompatibilityMatrix, b as CompatibilityResolverDelegate } from '../CompatibilityMatrix-DX307_vS.js';
+import { j as NodeDefinition, a as BaseHandle, g as HandleDirection, H as HandleCategory, f as HandleDefinition } from '../BaseNode-1HCEqmap.js';
+
+interface HandleTypeDefinition {
+    dataType: string;
+    category: 'DATA' | 'VIEW';
+    description?: string;
+    color?: string;
+}
+declare class HandleTypeRegistry {
+    private static types;
+    static register(typeDef: HandleTypeDefinition): void;
+    static get(dataType: string): HandleTypeDefinition | undefined;
+    static has(dataType: string): boolean;
+    static list(): HandleTypeDefinition[];
+    static clear(): void;
+}
+
+interface WireTypeDefinition {
+    wireType: string;
+    color: string;
+    strokeWidth: number;
+    dashArray?: string;
+    style?: 'bezier' | 'straight' | 'step';
+    description?: string;
+}
+declare class WireTypeRegistry {
+    private static wireTypes;
+    static register(def: WireTypeDefinition): void;
+    static get(wireType: string): WireTypeDefinition | undefined;
+    static list(): WireTypeDefinition[];
+    static clear(): void;
+}
+
+declare function initializeDefaultGraphRules(): void;
+
+interface HandleDescriptor {
+    dataType?: string;
+    direction?: HandleDirection | 'input' | 'output';
+    handleCategory?: HandleCategory;
+}
+/**
+ * ConnectionRuleStore — Central authoritative store for:
+ * 1. Handle types
+ * 2. Wire types
+ * 3. Node types & schemas
+ * 4. Inter-handle compatibility and connection rules
+ */
+declare class ConnectionRuleStore {
+    private static nodeTypes;
+    private static listeners;
+    private static initialized;
+    static initializeDefaults(): void;
+    static isInitialized(): boolean;
+    static subscribe(listener: () => void): () => void;
+    private static notify;
+    static registerNodeType(def: NodeDefinition): void;
+    static registerNodeTypes(defs: NodeDefinition[]): void;
+    static getNodeType(type: string): NodeDefinition | undefined;
+    static listNodeTypes(): NodeDefinition[];
+    static hasNodeType(type: string): boolean;
+    static registerHandleType(def: HandleTypeDefinition): void;
+    static getHandleType(dataType: string): HandleTypeDefinition | undefined;
+    static listHandleTypes(): HandleTypeDefinition[];
+    static hasHandleType(dataType: string): boolean;
+    static registerWireType(def: WireTypeDefinition): void;
+    static getWireType(wireType: string): WireTypeDefinition | undefined;
+    static listWireTypes(): WireTypeDefinition[];
+    static registerRule(rule: CompatibilityRule): void;
+    static resolve(sourceHandle: Pick<BaseHandle, 'handleCategory' | 'dataType' | 'direction'>, targetHandle: Pick<BaseHandle, 'handleCategory' | 'dataType' | 'direction'>): CompatibilityResolution;
+    static canConnect(sourceHandle: Pick<BaseHandle, 'handleCategory' | 'dataType' | 'direction'>, targetHandle: Pick<BaseHandle, 'handleCategory' | 'dataType' | 'direction'>): boolean;
+    /**
+     * Returns all node definitions that have at least one socket compatible with the dragged handle.
+     * If source handle is OUTPUT, checks candidate node INPUT sockets.
+     * If source handle is INPUT, checks candidate node OUTPUT sockets.
+     */
+    static getCompatibleNodeTypes(sourceHandle: HandleDescriptor, candidateNodes?: NodeDefinition[]): NodeDefinition[];
+    /**
+     * Find compatible sockets on a given target node for a dragged source handle.
+     */
+    static findCompatibleSockets(sourceHandle: HandleDescriptor, targetNode: NodeDefinition): HandleDefinition[];
+    static clear(): void;
+}
+
+export { CompatibilityResolution, CompatibilityRule, ConnectionRuleStore, type HandleDescriptor, type HandleTypeDefinition, HandleTypeRegistry, type WireTypeDefinition, WireTypeRegistry, initializeDefaultGraphRules };

package/packages/state-graph/dist/rules/index.js

@@ -0,0 +1,17 @@
+import {
+  ConnectionRuleStore,
+  HandleTypeRegistry,
+  WireTypeRegistry,
+  initializeDefaultGraphRules
+} from "../chunk-QN74PLMF.js";
+import {
+  CompatibilityMatrix
+} from "../chunk-ISFNY7EZ.js";
+import "../chunk-3RG5ZIWI.js";
+export {
+  CompatibilityMatrix,
+  ConnectionRuleStore,
+  HandleTypeRegistry,
+  WireTypeRegistry,
+  initializeDefaultGraphRules
+};

package/packages/state-graph/dist/spatial/index.d.ts

@@ -0,0 +1,55 @@
+import { B as BaseNode, a as BaseHandle, i as HandlePosition, N as NodePosition } from '../BaseNode-1HCEqmap.js';
+import { T as Trace } from '../TraceEngine-CJVpUb80.js';
+export { a as TraceEngine } from '../TraceEngine-CJVpUb80.js';
+import { S as SolidConnection } from '../BaseConnection-CMRrL6Fe.js';
+import '../CompatibilityMatrix-DX307_vS.js';
+
+declare class SpatialEngine {
+    static calculateEffectiveHandlePosition(node: BaseNode, handle: BaseHandle): HandlePosition;
+    static calculateDistance(p1: HandlePosition, p2: HandlePosition): number;
+    static calculateOffsetMagnitude(handle: BaseHandle): number;
+}
+
+declare class AutoSolidify {
+    static resolve(nodes: BaseNode[], traces: Trace[], existingConnections: SolidConnection[]): SolidConnection[];
+}
+
+declare class AttractionEngine {
+    static computeSimilarity(nodeA: BaseNode, nodeB: BaseNode): number;
+    static calculateStep(nodes: BaseNode[], strength?: number, speed?: number): Map<string, NodePosition>;
+}
+
+interface SocketCoordOptions {
+    cardWidth: number;
+    cardHeight?: number;
+    isOutput: boolean;
+    clearance?: number;
+    nudge?: {
+        x: number;
+        y: number;
+    };
+}
+interface SocketCoordResult {
+    baseX: number;
+    effectiveX: number;
+    effectiveY: number;
+    nudge: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Calculates socket handle coordinates enforcing that the handle always appears just
+ * outside the node body edge on spawn and cannot be pushed into the node body area.
+ */
+declare function calculateSocketCoordinates(baseY: number, options: SocketCoordOptions): SocketCoordResult;
+/**
+ * Dual-layered polygon beam points helper for tapered energy beam tethers.
+ * Tapers from thick at base (node body) to a fine point at head (displaced handle).
+ */
+declare const getBeamPoints: (nudge: {
+    x: number;
+    y: number;
+}, baseW?: number, headW?: number) => string;
+
+export { AttractionEngine, AutoSolidify, type SocketCoordOptions, type SocketCoordResult, SpatialEngine, Trace, calculateSocketCoordinates, getBeamPoints };

package/packages/state-graph/dist/spatial/index.js

@@ -0,0 +1,21 @@
+import {
+  AttractionEngine,
+  calculateSocketCoordinates,
+  getBeamPoints
+} from "../chunk-YTWCH6P2.js";
+import {
+  AutoSolidify,
+  SpatialEngine,
+  TraceEngine
+} from "../chunk-OV4JVTNY.js";
+import "../chunk-OYN4ZEZC.js";
+import "../chunk-ISFNY7EZ.js";
+import "../chunk-3RG5ZIWI.js";
+export {
+  AttractionEngine,
+  AutoSolidify,
+  SpatialEngine,
+  TraceEngine,
+  calculateSocketCoordinates,
+  getBeamPoints
+};

package/packages/state-graph/dist/state/index.d.ts

@@ -0,0 +1,109 @@
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * @file types.ts
+ * @description Formal TypeScript types for SKIPO_STATE system.
+ * Conforms strictly to SKIPO::STATE_EXECUTION_ARCHITECTURE and L9 (<=200L).
+ */
+type LifecycleScopeType = 'COMPONENT' | 'PAGE' | 'APP' | 'COMPONENT_DEPENDENCY' | 'STATE_DEPENDENCY';
+interface LifecycleDescriptor {
+    type: LifecycleScopeType;
+    targetId?: string;
+    retainCount?: number;
+    createdAt?: number;
+}
+interface StateEntry<T = unknown> {
+    id: string;
+    owner: string;
+    lifecycle: LifecycleDescriptor;
+    value: T;
+    dependencies: string[];
+}
+interface StateDeclaration<T = unknown> {
+    id: string;
+    initialValue: T;
+    lifecycle: LifecycleDescriptor;
+}
+type StateUpdater<T> = (prev: T) => T;
+interface LifecycleGraphNode {
+    id: string;
+    type: LifecycleScopeType;
+    dependencies: Set<string>;
+    dependents: Set<string>;
+}
+interface SkipoStateApi {
+    create<T = unknown>(owner: string, lifecycle: LifecycleDescriptor, initialValue: T, id?: string): string;
+    get<T = unknown>(id: string): T | undefined;
+    set<T = unknown>(id: string, value: T): void;
+    update<T = unknown>(id: string, updater: StateUpdater<T>): void;
+    destroy(id: string): void;
+    bind(stateId: string, lifecycleTarget: string): void;
+    unbind(stateId: string, lifecycleTarget: string): void;
+    lifecycle(stateId: string): LifecycleDescriptor | undefined;
+    subscribe<T = unknown>(id: string, listener: (value: T | undefined) => void): () => void;
+    getAllEntries(): Record<string, StateEntry<unknown>>;
+    clear(): void;
+}
+
+/**
+ * @file LifecycleGraph.ts
+ * @description Directed Acyclic Graph (DAG) for state and component lifecycles.
+ * Enforces cycle invalidation and recursive cascade destruction.
+ */
+
+declare class LifecycleCycleError extends Error {
+    constructor(source: string, target: string);
+}
+declare class LifecycleGraph {
+    private nodes;
+    registerNode(id: string, type: LifecycleScopeType): LifecycleGraphNode;
+    getNode(id: string): LifecycleGraphNode | undefined;
+    hasCycle(start: string, target: string): boolean;
+    addDependency(sourceId: string, targetId: string): void;
+    removeDependency(sourceId: string, targetId: string): void;
+    destroyCascade(rootId: string): string[];
+    clear(): void;
+}
+
+/**
+ * @file SkipoState.ts
+ * @description Canonical SKIPO_STATE singleton backed by Zustand and LifecycleGraph.
+ * Satisfies Invariants I1-I6 and L9 (<=200L).
+ */
+
+interface InternalStateStore {
+    entries: Record<string, StateEntry<unknown>>;
+    setEntry: (id: string, entry: StateEntry<unknown>) => void;
+    removeEntry: (id: string) => void;
+    clearAll: () => void;
+}
+declare class SkipoStateEngine implements SkipoStateApi {
+    private graph;
+    private store;
+    constructor();
+    create<T = unknown>(owner: string, lifecycle: LifecycleDescriptor, initialValue: T, explicitId?: string): string;
+    get<T = unknown>(id: string): T | undefined;
+    set<T = unknown>(id: string, value: T): void;
+    update<T = unknown>(id: string, updater: StateUpdater<T>): void;
+    destroy(id: string): void;
+    bind(stateId: string, lifecycleTarget: string): void;
+    unbind(stateId: string, lifecycleTarget: string): void;
+    lifecycle(stateId: string): LifecycleDescriptor | undefined;
+    subscribe<T = unknown>(id: string, listener: (value: T | undefined) => void): () => void;
+    getAllEntries(): Record<string, StateEntry<unknown>>;
+    getZustandStore(): StoreApi<InternalStateStore>;
+    clear(): void;
+}
+declare const SKIPO_STATE: SkipoStateEngine;
+
+/**
+ * @file hooks.ts
+ * @description React integration hooks for SKIPO_STATE.
+ * Enforces component lifecycle binding, automatic unmount cleanup, and zero local useState.
+ */
+
+declare function useSkipoState<T>(id: string, initialValue?: T | (() => T), lifecycle?: LifecycleDescriptor): [T, (valOrUpdater: T | StateUpdater<T>) => void];
+declare function useLifecycleScope(scopeId: string, scopeType?: LifecycleScopeType): void;
+declare function useSkipoBind(stateId: string, lifecycleTarget: string): void;
+
+export { LifecycleCycleError, type LifecycleDescriptor, LifecycleGraph, type LifecycleGraphNode, type LifecycleScopeType, SKIPO_STATE, type SkipoStateApi, SkipoStateEngine, type StateDeclaration, type StateEntry, type StateUpdater, useLifecycleScope, useSkipoBind, useSkipoState };

package/packages/state-graph/dist/state/index.js

@@ -0,0 +1,20 @@
+import "../chunk-Q5I42UX7.js";
+import {
+  LifecycleCycleError,
+  LifecycleGraph,
+  SKIPO_STATE,
+  SkipoStateEngine,
+  useLifecycleScope,
+  useSkipoBind,
+  useSkipoState
+} from "../chunk-SHIBCPGQ.js";
+import "../chunk-3RG5ZIWI.js";
+export {
+  LifecycleCycleError,
+  LifecycleGraph,
+  SKIPO_STATE,
+  SkipoStateEngine,
+  useLifecycleScope,
+  useSkipoBind,
+  useSkipoState
+};

package/packages/state-graph/dist/store/index.d.ts

@@ -0,0 +1,6 @@
+export { C as CommandApi, a as GhostStore, b as GhostStoreListener, d as GraphListener, e as GraphStore } from '../index-CiekWEH3.js';
+import '../BaseNode-1HCEqmap.js';
+import '../BaseConnection-CMRrL6Fe.js';
+import '../BaseGraph-Bl2f7Pqx.js';
+import '../TraceEngine-CJVpUb80.js';
+import '../CompatibilityMatrix-DX307_vS.js';

package/packages/state-graph/dist/store/index.js

@@ -0,0 +1,15 @@
+import {
+  CommandApi,
+  GhostStore,
+  GraphStore
+} from "../chunk-4UVGXFEM.js";
+import "../chunk-KG6QYS26.js";
+import "../chunk-OV4JVTNY.js";
+import "../chunk-OYN4ZEZC.js";
+import "../chunk-ISFNY7EZ.js";
+import "../chunk-3RG5ZIWI.js";
+export {
+  CommandApi,
+  GhostStore,
+  GraphStore
+};

package/packages/state-graph/kloks.manifest.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://skipo.dev/schemas/kloks-manifest.v1.json",
+  "package": "@kloks/state-graph",
+  "version": "1.0.0",
+  "services": [
+    {
+      "id": "state-lifecycle",
+      "name": "State & Lifecycle Service",
+      "version": "1.0.0",
+      "description": "Zustand state engine and explicit lifecycle state-graph service.",
+      "backend": {
+        "package": "@kloks/state-graph",
+        "export": "StateLifecycleServiceFacade",
+        "facade": "StateLifecycleServiceFacade"
+      },
+      "modes": ["backend"],
+      "targets": { "backend": ["BackendFacade.services"] }
+    },
+    {
+      "id": "node-graph",
+      "name": "Node Graph Rules & Spatial Engine",
+      "version": "1.0.0",
+      "description": "Non-UI node graph rule verification, spatial positioning, and ghost routing engine.",
+      "backend": {
+        "package": "@kloks/state-graph",
+        "export": "NodeGraphEngineServiceFacade",
+        "facade": "NodeGraphEngineServiceFacade"
+      },
+      "ui": {
+        "package": "@floks/canvas-ui",
+        "components": ["InfiniteCanvas"]
+      },
+      "modes": ["backend", "fullstack"],
+      "targets": {
+        "backend": ["BackendFacade.services"],
+        "frontend": ["App.main-content"]
+      }
+    }
+  ]
+}

package/packages/state-graph/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@kloks/state-graph",
+  "version": "1.0.0",
+  "description": "Kloks Non-UI State, Execution & Node-Graph Domain/Rules/Spatial Services built on KrnlTS",
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "skipoManifest": "./kloks.manifest.json",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./state": {
+      "import": "./dist/state/index.js",
+      "types": "./dist/state/index.d.ts",
+      "default": "./dist/state/index.js"
+    },
+    "./execution": {
+      "import": "./dist/execution/index.js",
+      "types": "./dist/execution/index.d.ts",
+      "default": "./dist/execution/index.js"
+    },
+    "./domain": {
+      "import": "./dist/domain/index.js",
+      "types": "./dist/domain/index.d.ts",
+      "default": "./dist/domain/index.js"
+    },
+    "./rules": {
+      "import": "./dist/rules/index.js",
+      "types": "./dist/rules/index.d.ts",
+      "default": "./dist/rules/index.js"
+    },
+    "./spatial": {
+      "import": "./dist/spatial/index.js",
+      "types": "./dist/spatial/index.d.ts",
+      "default": "./dist/spatial/index.js"
+    },
+    "./store": {
+      "import": "./dist/store/index.js",
+      "types": "./dist/store/index.d.ts",
+      "default": "./dist/store/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/state/index.ts src/execution/index.ts src/domain/index.ts src/rules/index.ts src/spatial/index.ts src/store/index.ts --format esm --dts --clean --external zustand --external bullmq --external react --external ws",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@kloks/functions": "^1.0.0",
+    "bullmq": "^6.3.8",
+    "zustand": "^5.0.15"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@dinilmusick/krnl": "^1.0.0"
+  }
+}