@cstack-protocol/pingala 1.0.0

package/src/core/methodology.ts

@@ -0,0 +1,256 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import process from "node:process";
+
+/**
+ * Methodology Loader: Runtime consumer of cs-agent-core definitions.
+ * 
+ * Source Priority:
+ * 1. CSTACK_AGENT_CORE_PATH (Creator Mode - local path)
+ * 2. CSTACK_API_KEY (Public Mode - fetch from API, TODO)
+ * 3. Hardcoded fallback (resilience)
+ */
+
+export interface CSIPillar {
+    name: string;
+    description: string;
+    weight: number;
+}
+
+export interface Protocol531Rules {
+    maxTools: number;
+    anchorCount: number;
+    activeCount: number;
+    supportingCount: number;
+    rawDescription?: string; // e.g. "1 Anchor, 3 Active, 5 Supporting"
+}
+
+export interface BaguaCategory {
+    name: string;
+    description: string;
+    userFacingLabel?: string;
+}
+
+export interface InnerDiamondCategory {
+    name: string;
+    description: string;
+    userFacingLabel?: string;
+}
+
+export interface ConsentPrompts {
+    l2: string;
+    l3: string;
+}
+
+export class MethodologyLoader {
+    private static basePath: string | null = null;
+    private static apiKey: string | null = null;
+
+    /**
+     * Initialize the loader by detecting the methodology source.
+     */
+    static init(): void {
+        this.basePath = process.env.CSTACK_AGENT_CORE_PATH || null;
+        this.apiKey = process.env.CSTACK_API_KEY || null;
+
+        if (this.basePath) {
+            console.error(`[MethodologyLoader] Creator Mode: Loading from ${this.basePath}`);
+        } else if (this.apiKey) {
+            console.error(`[MethodologyLoader] Public Mode: API key detected (API fetch TODO)`);
+        } else {
+            console.error(`[MethodologyLoader] Fallback Mode: Using hardcoded defaults`);
+        }
+    }
+
+    /**
+     * Load CSI Pillars from stack-auditor.md or fallback.
+     */
+    static loadCSIPillars(): CSIPillar[] {
+        if (this.basePath) {
+            const filePath = path.join(this.basePath, "stack-auditor.md");
+            if (fs.existsSync(filePath)) {
+                // Parse from file (simplified for MVP)
+                // TODO: Proper markdown parsing
+                return this.parseCSIPillarsFromFile(filePath);
+            }
+        }
+
+        // Hardcoded fallback (from stack-auditor.md - CSI-Lite)
+        return [
+            { name: "Attention Depth (AD)", description: "Quality of deep work and focus (0–100)", weight: 0.35 },
+            { name: "Dependency Exposure (DE)", description: "Workflow independence from non-sovereign AI (0–100)", weight: 0.35 },
+            { name: "Decision Provenance (DP)", description: "Rationale clarity and protocol adherence (0–100)", weight: 0.30 },
+            { name: "Alignment (SAS)", description: "Adherence to CSP (5:3:1 Node) constraints", weight: 0.00 } // Alignment score is secondary
+        ];
+    }
+
+    /**
+     * Load 5:3:1 Rule constraints from identity.md or stack-auditor.md.
+     */
+    static load531Rules(): Protocol531Rules {
+        const defaults: Protocol531Rules = {
+            maxTools: 9,
+            anchorCount: 1,
+            activeCount: 3,
+            supportingCount: 5,
+            rawDescription: "1 Anchor, 3 Active, 5 Supporting"
+        };
+
+        if (this.basePath) {
+            const identityPath = path.join(this.basePath, "identity.md");
+            if (fs.existsSync(identityPath)) {
+                try {
+                    const content = fs.readFileSync(identityPath, "utf-8");
+                    const match = content.match(/\d+:\d+:\d+ Rule.*?\((.*?)\)/i);
+                    if (match && match[1]) {
+                        const desc = match[1]; // e.g. "1 Anchor, 3 Active tools, 5 Support elements"
+                        return {
+                            ...defaults,
+                            rawDescription: desc
+                        };
+                    }
+                } catch (e) {
+                    console.error("[MethodologyLoader] Error parsing 531 rules:", e);
+                }
+            }
+        }
+
+        return defaults;
+    }
+
+    /**
+     * Load Bāguà categories from architecture.md or fallback.
+     */
+    static loadBaguaCategories(): BaguaCategory[] {
+        if (this.basePath) {
+            const filePath = path.join(this.basePath, "architecture.md");
+            if (fs.existsSync(filePath)) {
+                return this.parseBaguaCategoriesFromFile(filePath);
+            }
+        }
+
+        // Hardcoded fallback
+        return [
+            { name: "Li", description: "Fame, reputation, how one is seen by the world.", userFacingLabel: "Social Connection & Visibility" },
+            { name: "Kun", description: "Love, partnerships, and intimate energy management.", userFacingLabel: "Relationships & Self-Care" },
+            { name: "Dui", description: "Creativity, joy, projects, and the 'inner child.'", userFacingLabel: "Creative Expression & Hobbies" },
+            { name: "Qian", description: "Helpful people, travel, and external systems.", userFacingLabel: "Communication & Networking" },
+            { name: "Kan", description: "Life path, professional trajectory, and deep purpose.", userFacingLabel: "Career & Goals" },
+            { name: "Gen", description: "Self-cultivation, knowledge, and wisdom building.", userFacingLabel: "Learning & Growth" },
+            { name: "Zhen", description: "Ancestry, fundamental support systems, and family.", userFacingLabel: "Family & Roots" },
+            { name: "Xun", description: "Wealth, abundance, and resource flow.", userFacingLabel: "Financial Management" },
+            { name: "Tai Ji", description: "The 'Operating System,' physical health, and core stability.", userFacingLabel: "Physical Health & Routines" }
+        ];
+    }
+
+    /**
+     * Load Inner Diamond categories for L3.
+     */
+    static loadInnerDiamondCategories(): InnerDiamondCategory[] {
+        // For now, these are not in architecture.md usually, so we use fallback
+        return [
+            { name: "Identity", description: "How your digital choices reflect who you are becoming.", userFacingLabel: "Identity Reflection" },
+            { name: "Purpose", description: "Alignment between your daily actions and your sovereign mission.", userFacingLabel: "Purpose Alignment" },
+            { name: "Sovereignty", description: "Your capacity to act independently of algorithmic nudge.", userFacingLabel: "Sovereignty Forecast" }
+        ];
+    }
+
+    /**
+     * Load Consent Prompts from consent-prompts.md.
+     */
+    static loadConsentPrompts(): ConsentPrompts {
+        const defaults: ConsentPrompts = {
+            l2: "Would you like me to include a life balance view?",
+            l3: "Want to explore your inner operating system?"
+        };
+
+        if (this.basePath) {
+            const filePath = path.join(this.basePath, "consent-prompts.md");
+            if (fs.existsSync(filePath)) {
+                try {
+                    const content = fs.readFileSync(filePath, "utf-8");
+                    const l2Match = content.match(/## Level 2.*?Prompt:\s*> "(.*?)"/s);
+                    const l3Match = content.match(/## Level 3.*?Prompt:\s*> "(.*?)"/s);
+                    return {
+                        l2: l2Match ? l2Match[1].trim() : defaults.l2,
+                        l3: l3Match ? l3Match[1].trim() : defaults.l3
+                    };
+                } catch (e) {
+                    console.error("[MethodologyLoader] Error parsing consent prompts:", e);
+                }
+            }
+        }
+
+        return defaults;
+    }
+
+    /**
+     * Parse CSI pillars from a markdown file.
+     * Simplified parser for MVP.
+     */
+    private static parseCSIPillarsFromFile(filePath: string): CSIPillar[] {
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+
+            // Look for the CSI section (simplified pattern matching)
+            const csiMatch = content.match(/### Step 3: Compute CSI[\s\S]*?(?=###|$)/);
+            if (!csiMatch) {
+                return this.loadCSIPillars(); // Fallback
+            }
+
+            const pillars: CSIPillar[] = [];
+            const pillarPattern = /\d+\.\s*\*\*(\w+)\*\*:\s*(.+)/g;
+            let match;
+
+            while ((match = pillarPattern.exec(csiMatch[0])) !== null) {
+                pillars.push({
+                    name: match[1],
+                    description: match[2].trim(),
+                    weight: 0.25 // Equal weight for now
+                });
+            }
+
+            return pillars.length > 0 ? pillars : this.loadCSIPillars();
+        } catch {
+            return this.loadCSIPillars();
+        }
+    }
+
+    /**
+     * Parse Bagua categories from architecture.md.
+     */
+    private static parseBaguaCategoriesFromFile(filePath: string): BaguaCategory[] {
+        try {
+            const content = fs.readFileSync(filePath, "utf-8");
+            const categories: BaguaCategory[] = [];
+
+            // Match table rows: | Li | Social Connection & Visibility | Description... |
+            const tablePattern = /\|\s*\*\*?(\w+)\*\*?\s*\|\s*([^|]+)\s*\|\s*([^|]+)\s*\|/g;
+            let match;
+
+            while ((match = tablePattern.exec(content)) !== null) {
+                categories.push({
+                    name: match[1],
+                    userFacingLabel: match[2].trim(),
+                    description: match[3].trim()
+                });
+            }
+
+            return categories.length > 0 ? categories : this.loadBaguaCategories();
+        } catch {
+            return this.loadBaguaCategories();
+        }
+    }
+
+    /**
+     * Check if methodology source is available.
+     */
+    static getSourceMode(): "creator" | "api" | "fallback" {
+        if (this.basePath) return "creator";
+        if (this.apiKey) return "api";
+        return "fallback";
+    }
+}
+
+// Initialize on module load
+MethodologyLoader.init();

package/src/core/pingala.ts

@@ -0,0 +1,77 @@
+import { Rule531 } from './531-rule.js';
+import { MethodologyLoader } from './methodology.js';
+import { Governor } from './governor.js';
+import type { StackConfiguration } from './531-rule.js';
+import { EngagementAnalyzer } from './engagement-analyzer.js';
+
+import { performSDKValidation } from './sdk-adapter.js';
+
+/**
+ * Pingala Engine: The "Governor" intelligence.
+ * Responsible for high-level diagnosis and Conscious Stack Index (CSI) computation.
+ */
+export interface DiagnoseOptions extends StackConfiguration {
+    scores?: {
+        attention_depth: number;
+        dependency_exposure: number;
+    };
+}
+
+export class PingalaEngine {
+    /**
+     * Diagnoses a workspace and computes the CSI using CSI-Lite pillars.
+     */
+    static async diagnose(config: DiagnoseOptions) {
+        // Run SDK Validation (Patterns, 5:3:1, CSI)
+        const sdkResult = await performSDKValidation(config.tools);
+
+        const sourceMode = MethodologyLoader.getSourceMode();
+        const state = Governor.getMaturityState();
+
+        // CSI Pillars (Augmented with SDK data, supporting stateless overrides)
+        const ad = config.scores?.attention_depth ?? state.telemetry?.attention_depth ?? 50;
+        const de = config.scores?.dependency_exposure ?? state.telemetry?.dependency_exposure ?? 50;
+        const dp = Governor.getDecisionProvenanceScore();
+        const fs = EngagementAnalyzer.getFragmentationScore(config.tools);
+
+        // Blend Pingala's internal scoring with SDK's logic-based CSI
+        const blendedCsi = Math.round((sdkResult.csi * 0.7) + (fs * 0.3));
+
+        Governor.updateCsi(blendedCsi);
+
+        return {
+            engine: "Pingala v0.3.0 (Powered by CSTACK SDK)",
+            methodology_source: sourceMode,
+            csi_score: blendedCsi,
+            pillars: {
+                attention_depth: ad,
+                dependency_exposure: de,
+                decision_provenance: dp,
+                fragmentation_score: fs
+            },
+            risk_band: this.getRiskBand(blendedCsi),
+            status: this.getStatusLabel(blendedCsi),
+            protocol_analysis: {
+                isValid: sdkResult.status === 'approved',
+                score: sdkResult.csi,
+                violations: sdkResult.violations.map(v => `${v.name}: ${v.description}`),
+                recommendations: sdkResult.recommendations
+            },
+            attribution: "CSI framework powered by the Conscious Stack Protocol (CSP) Registry."
+        };
+    }
+
+    static getRiskBand(csi: number): string {
+        if (csi >= 85) return "safe";
+        if (csi >= 70) return "stable";
+        if (csi >= 50) return "erosion";
+        return "system_risk";
+    }
+
+    private static getStatusLabel(score: number): string {
+        if (score >= 85) return "Sovereign Resonance";
+        if (score >= 70) return "Aligned Flow";
+        if (score >= 50) return "Congested Flux";
+        return "Conscious Debt Crisis";
+    }
+}

package/src/core/sdk-adapter.ts

@@ -0,0 +1,52 @@
+import { ToolInstance } from './531-rule.js';
+import { validate as sdkValidate, initTelemetry as sdkInitTelemetry } from '@cstack-protocol/sdk';
+import type { StackProfile, Tool, StackRole } from '@cstack-protocol/sdk';
+
+/**
+ * Maps Pingala's ToolInstance to the SDK's Tool schema.
+ * Handles the casing and naming differences in roles.
+ */
+function mapRole(role: string): StackRole {
+    switch (role) {
+        case 'Anchor': return 'anchor';
+        case 'Active': return 'utility';
+        case 'Supporting': return 'periphery';
+        default: return 'periphery';
+    }
+}
+
+/**
+ * Converts Pingala's internal tool list to an SDK-compatible StackProfile.
+ */
+export function mapToSDK(tools: ToolInstance[], operatorId?: string): StackProfile {
+    return {
+        id: `pingala-${Date.now()}`,
+        operatorId: operatorId || 'anonymous-pingala',
+        tools: tools.map((t, idx) => ({
+            id: t.functionId || `t-${idx}`,
+            name: t.name,
+            category: t.category,
+            role: mapRole(t.role)
+        })),
+        createdAt: new Date(),
+        updatedAt: new Date()
+    };
+}
+
+/**
+ * Bridge for the validation logic.
+ * Wraps the SDK's async validate() for use within Pingala's diagnostic loop.
+ */
+export async function performSDKValidation(tools: ToolInstance[], operatorId?: string) {
+    const profile = mapToSDK(tools, operatorId);
+    return await sdkValidate(profile);
+}
+
+/**
+ * Initializes the telemetry system for Pingala.
+ */
+export function initPingalaTelemetry(consentTier: 'observer' | 'contributor' | 'sentinel' = 'contributor') {
+    sdkInitTelemetry({ consentTier });
+    console.log(`🛡️ Pingala: Telemetry initialized with tier: ${consentTier}`);
+}
+export { getRegistryMode, flushTelemetry } from '@cstack-protocol/sdk';