@x12i/analytix-tiers 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { CataloxCommonFields } from "@x12i/analytix-contracts";
+export interface TierDefinition extends CataloxCommonFields {
+    tierId: string;
+    levels: Array<{
+        level: number;
+        analytics: string[];
+    }>;
+    materialization: {
+        enabled: boolean;
+        storeIntermediateOutputs: boolean;
+        reuseWithinRun: boolean;
+    };
+}
+export declare class TierEngine {
+    static compileTierDag(tierDef: TierDefinition, resolveDependencies: (id: string) => string[]): string[];
+    static executeTier(tierDef: TierDefinition, executionOrder: string[], runNode: (id: string) => Promise<any>, materializationStore: Map<string, any>): Promise<Record<string, any>>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,KAAK,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC,CAAC;IACH,eAAe,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,wBAAwB,EAAE,OAAO,CAAC;QAClC,cAAc,EAAE,OAAO,CAAC;KACzB,CAAC;CACH;AAED,qBAAa,UAAU;IACrB,MAAM,CAAC,cAAc,CACnB,OAAO,EAAE,cAAc,EACvB,mBAAmB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,EAAE,GAC5C,MAAM,EAAE;WAuFE,WAAW,CACtB,OAAO,EAAE,cAAc,EACvB,cAAc,EAAE,MAAM,EAAE,EACxB,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,EACrC,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CA8BhC"}

package/dist/index.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TierEngine = void 0;
+class TierEngine {
+    static compileTierDag(tierDef, resolveDependencies) {
+        // 1. Validation: levels are contiguous starting at 1
+        const levels = [...tierDef.levels].sort((a, b) => a.level - b.level);
+        for (let i = 0; i < levels.length; i++) {
+            if (levels[i].level !== i + 1) {
+                throw new Error("CATALOX_VALIDATION_FAILED");
+            }
+        }
+        // 2. Collect all nodes in this tier
+        const allNodes = new Set();
+        const nodeToLevel = new Map();
+        for (const lvl of levels) {
+            for (const ref of lvl.analytics) {
+                if (allNodes.has(ref)) {
+                    throw new Error("CATALOX_VALIDATION_FAILED"); // Analytic in multiple levels
+                }
+                allNodes.add(ref);
+                nodeToLevel.set(ref, lvl.level);
+            }
+        }
+        const inDegree = new Map();
+        const graph = new Map();
+        for (const node of allNodes) {
+            inDegree.set(node, 0);
+            graph.set(node, []);
+        }
+        // 3. Build adjacency list and in-degrees
+        for (const node of allNodes) {
+            const deps = resolveDependencies(node);
+            const level = nodeToLevel.get(node);
+            for (const dep of deps) {
+                // Ignore tier-0 source database refs
+                if (dep === "main-events-db" || dep.startsWith("source:")) {
+                    continue;
+                }
+                // Dependency must be in the tier
+                if (!allNodes.has(dep)) {
+                    throw new Error("TIER_DEPENDENCY_MISSING");
+                }
+                // Dependency level must be strictly less than node level
+                const depLevel = nodeToLevel.get(dep);
+                if (depLevel >= level) {
+                    throw new Error("TIER_DEPENDENCY_MISSING");
+                }
+                // dep -> node edge
+                graph.get(dep).push(node);
+                inDegree.set(node, inDegree.get(node) + 1);
+            }
+        }
+        // 4. Kahn's Algorithm
+        const queue = [];
+        for (const node of allNodes) {
+            if (inDegree.get(node) === 0) {
+                queue.push(node);
+            }
+        }
+        const order = [];
+        while (queue.length > 0) {
+            const u = queue.shift();
+            order.push(u);
+            const neighbors = graph.get(u) || [];
+            for (const v of neighbors) {
+                inDegree.set(v, inDegree.get(v) - 1);
+                if (inDegree.get(v) === 0) {
+                    queue.push(v);
+                }
+            }
+        }
+        if (order.length !== allNodes.size) {
+            throw new Error("TIER_CYCLE_DETECTED");
+        }
+        return order;
+    }
+    static async executeTier(tierDef, executionOrder, runNode, materializationStore) {
+        const results = {};
+        for (const id of executionOrder) {
+            // Sibling reuse within run check
+            if (tierDef.materialization.reuseWithinRun && materializationStore.has(id)) {
+                results[id] = materializationStore.get(id);
+                continue;
+            }
+            try {
+                const output = await runNode(id);
+                results[id] = output;
+                if (tierDef.materialization.storeIntermediateOutputs) {
+                    materializationStore.set(id, output);
+                }
+            }
+            catch (err) {
+                const errorDetails = {
+                    code: "TIER_DEPENDENCY_MISSING",
+                    message: `Tier execution failed at dependency: ${id}`,
+                    failedDependency: id,
+                    upstreamError: err.message,
+                };
+                throw new Error(JSON.stringify(errorDetails));
+            }
+        }
+        return results;
+    }
+}
+exports.TierEngine = TierEngine;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@x12i/analytix-tiers",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@x12i/analytix-contracts": "^1.0.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}