@10kdevs/matha 0.1.0

package/dist/brain/dopamine.js

@@ -0,0 +1,184 @@
+import * as path from 'path';
+import { readJsonOrNull } from '../storage/reader.js';
+import { writeAtomic } from '../storage/writer.js';
+const DEFAULT_TIERS = {
+    'rename/crud': { tier: 'lightweight', budget: 2000 },
+    'business_logic': { tier: 'capable', budget: 8000 },
+    'architecture': { tier: 'capable', budget: 16000 },
+    'frozen_component': { tier: 'capable', budget: 16000 },
+    'unknown': { tier: 'mid', budget: 4000 }
+};
+export async function analyseDeltas(mathaDir) {
+    const emptyAnalysis = {
+        analysedAt: new Date().toISOString(),
+        sessionCount: 0,
+        routingRules: [],
+        componentConfidence: [],
+        globalAvgTokenDelta: 0,
+        overBudgetRate: 0
+    };
+    try {
+        const deltasPath = path.join(mathaDir, 'dopamine/deltas.json');
+        const deltas = await readJsonOrNull(deltasPath);
+        if (!deltas || !Array.isArray(deltas) || deltas.length === 0) {
+            return emptyAnalysis;
+        }
+        const validDeltas = deltas.filter(d => d.token_delta !== null);
+        let globalAvgTokenDelta = 0;
+        let overBudgetRate = 0;
+        if (validDeltas.length > 0) {
+            const sum = validDeltas.reduce((acc, d) => acc + d.token_delta, 0);
+            globalAvgTokenDelta = sum / validDeltas.length;
+            const overBudgetCount = validDeltas.filter(d => d.token_delta > 0).length;
+            overBudgetRate = overBudgetCount / validDeltas.length;
+        }
+        return {
+            analysedAt: new Date().toISOString(),
+            sessionCount: deltas.length,
+            routingRules: buildRoutingRules(deltas),
+            componentConfidence: buildConfidence(deltas),
+            globalAvgTokenDelta,
+            overBudgetRate
+        };
+    }
+    catch {
+        return emptyAnalysis;
+    }
+}
+export function buildRoutingRules(deltas) {
+    const groups = {};
+    for (const d of deltas) {
+        if (!groups[d.operation_type]) {
+            groups[d.operation_type] = [];
+        }
+        groups[d.operation_type].push(d);
+    }
+    const rules = [];
+    for (const [opType, records] of Object.entries(groups)) {
+        if (records.length < 3)
+            continue;
+        const validRecords = records.filter(r => r.token_delta !== null);
+        if (validRecords.length === 0)
+            continue;
+        const sum = validRecords.reduce((acc, r) => acc + r.token_delta, 0);
+        const avgTokenDelta = sum / validRecords.length;
+        const defaultDef = DEFAULT_TIERS[opType] || DEFAULT_TIERS['unknown'];
+        let recommendedTier = defaultDef.tier;
+        if (avgTokenDelta > 5000) {
+            if (recommendedTier === 'lightweight')
+                recommendedTier = 'mid';
+            else if (recommendedTier === 'mid')
+                recommendedTier = 'capable';
+        }
+        else if (avgTokenDelta < -2000) {
+            if (recommendedTier === 'capable')
+                recommendedTier = 'mid';
+            else if (recommendedTier === 'mid')
+                recommendedTier = 'lightweight';
+        }
+        let recommendedBudget = defaultDef.budget + avgTokenDelta;
+        if (recommendedBudget < 500) {
+            recommendedBudget = 500;
+        }
+        let confidence = 'low';
+        if (records.length >= 10)
+            confidence = 'high';
+        else if (records.length >= 5)
+            confidence = 'medium';
+        rules.push({
+            operation_type: opType,
+            component_pattern: '', // global rule
+            recommended_tier: recommendedTier,
+            recommended_budget: recommendedBudget,
+            confidence,
+            sample_size: records.length,
+            avg_token_delta: avgTokenDelta,
+            last_updated: new Date().toISOString()
+        });
+    }
+    return rules;
+}
+export function buildConfidence(deltas) {
+    const groups = {};
+    for (const d of deltas) {
+        if (!groups[d.model_tier_used]) {
+            groups[d.model_tier_used] = [];
+        }
+        groups[d.model_tier_used].push(d);
+    }
+    const confidences = [];
+    for (const [tier, records] of Object.entries(groups)) {
+        const defaultVal = 0.0;
+        let adjustment = 0.0;
+        let violationCount = 0;
+        const validTokens = records.filter(r => r.token_delta !== null);
+        let avgTokenDelta = 0;
+        if (validTokens.length > 0) {
+            avgTokenDelta = validTokens.reduce((s, r) => s + r.token_delta, 0) / validTokens.length;
+        }
+        for (const r of records) {
+            if (r.contract_result === 'violated' || r.contract_result === 'partial') {
+                violationCount++;
+            }
+            if (r.contract_result === 'passed')
+                adjustment += 0.1;
+            else if (r.contract_result === 'violated')
+                adjustment -= 0.2;
+            else if (r.contract_result === 'partial')
+                adjustment -= 0.1;
+            if (r.token_delta !== null) {
+                if (r.token_delta > 5000)
+                    adjustment -= 0.1;
+                else if (r.token_delta < 0)
+                    adjustment += 0.05;
+            }
+        }
+        adjustment = Math.max(-1.0, Math.min(1.0, adjustment));
+        confidences.push({
+            component: tier,
+            confidence_adjustment: adjustment,
+            violation_rate: violationCount / records.length,
+            avg_token_delta: avgTokenDelta,
+            session_count: records.length,
+            last_updated: new Date().toISOString()
+        });
+    }
+    return confidences;
+}
+export async function getRecommendation(mathaDir, operationType) {
+    try {
+        const rulesPath = path.join(mathaDir, 'dopamine/routing-rules.json');
+        const analysis = await readJsonOrNull(rulesPath);
+        if (analysis && Array.isArray(analysis.routingRules)) {
+            const rule = analysis.routingRules.find(r => r.operation_type === operationType);
+            if (rule) {
+                return {
+                    tier: rule.recommended_tier,
+                    budget: rule.recommended_budget,
+                    source: 'learned',
+                    confidence: rule.confidence,
+                    sample_size: rule.sample_size
+                };
+            }
+        }
+    }
+    catch {
+        // silently fallback
+    }
+    const def = DEFAULT_TIERS[operationType] || DEFAULT_TIERS['unknown'];
+    return {
+        tier: def.tier,
+        budget: def.budget,
+        source: 'default',
+        confidence: null
+    };
+}
+export async function persistAnalysis(mathaDir, analysis) {
+    try {
+        const rulesPath = path.join(mathaDir, 'dopamine/routing-rules.json');
+        await writeAtomic(rulesPath, analysis, { overwrite: true });
+    }
+    catch {
+        // silently fail
+    }
+}

package/dist/brain/frontal-lobe.js

@@ -0,0 +1,219 @@
+/**
+ * Runs an individual frontal-lobe gate.
+ * Never throws on malformed input; returns completed: false instead.
+ */
+export function runGate(gateId, context, input) {
+    try {
+        switch (gateId) {
+            case 1:
+                return {
+                    gateId,
+                    completed: isNonEmptyString(input),
+                    output: input,
+                };
+            case 2:
+                return {
+                    gateId,
+                    completed: isNonEmptyStringArray(input),
+                    output: input,
+                };
+            case 3: {
+                const orient = isNonEmptyObject(input) || isNonEmptyObject(context.stabilityData);
+                return {
+                    gateId,
+                    completed: orient,
+                    output: isNonEmptyObject(input) ? input : context.stabilityData ?? {},
+                };
+            }
+            case 4:
+                return {
+                    gateId,
+                    completed: isPresent(input),
+                    output: input,
+                };
+            case 5:
+                return {
+                    gateId,
+                    completed: isNonEmptyStringArray(input),
+                    output: input,
+                };
+            case 6:
+                return {
+                    gateId,
+                    completed: isPresent(input),
+                    output: input,
+                };
+            case 7: {
+                const states = Array.isArray(input) ? input : [];
+                const missing = findMissingRequiredBuildGates(states);
+                const readyToBuild = missing.length === 0;
+                return {
+                    gateId,
+                    completed: readyToBuild,
+                    output: { readyToBuild, missing },
+                };
+            }
+            case 8:
+                return {
+                    gateId,
+                    completed: isPresent(input),
+                    output: input,
+                };
+            default:
+                return {
+                    gateId,
+                    completed: false,
+                    output: input,
+                };
+        }
+    }
+    catch {
+        return {
+            gateId,
+            completed: false,
+            output: input,
+        };
+    }
+}
+/**
+ * Validates that gates 01-06 are completed.
+ */
+export function validateSequence(states) {
+    const missing = [];
+    for (let gateId = 1; gateId <= 6; gateId++) {
+        const state = states.find((s) => s.gateId === gateId);
+        if (!state || !state.completed) {
+            missing.push(gateId);
+        }
+    }
+    return {
+        valid: missing.length === 0,
+        missing,
+    };
+}
+/**
+ * Builds the session brief from gate outputs and hippocampus danger zone lookup.
+ */
+export async function generateBrief(context, states, hippocampus) {
+    const stateMap = new Map();
+    for (const s of states)
+        stateMap.set(s.gateId, s);
+    const why = asString(stateMap.get(1)?.output);
+    const bounds = asStringArray(stateMap.get(2)?.output);
+    const contract = asStringArray(stateMap.get(5)?.output);
+    const dangerZones = await hippocampus.getDangerZones(context.scope);
+    const routing = routeOperation(context.operationType);
+    const gate7 = stateMap.get(7);
+    const readyFromGate7 = typeof gate7?.output === 'object' &&
+        gate7?.output !== null &&
+        'readyToBuild' in gate7.output
+        ? Boolean(gate7.output.readyToBuild)
+        : undefined;
+    const readyToBuild = readyFromGate7 ?? findMissingRequiredBuildGates(states).length === 0;
+    return {
+        sessionId: context.sessionId,
+        scope: context.scope,
+        operationType: context.operationType,
+        why,
+        bounds,
+        dangerZones,
+        contract,
+        modelTier: routing.modelTier,
+        tokenBudget: routing.tokenBudget,
+        gatesCompleted: states.filter((s) => s.completed).map((s) => s.gateId),
+        readyToBuild,
+    };
+}
+/**
+ * Gate 08 write-back.
+ * Writes discovery to hippocampus if correction and/or danger pattern are present.
+ */
+export async function runWriteBack(context, discovery, hippocampus) {
+    const correction = discovery.correction?.trim() ?? '';
+    const dangerPattern = discovery.dangerPattern?.trim() ?? '';
+    if (!correction && !dangerPattern)
+        return;
+    if (correction) {
+        const timestamp = new Date().toISOString();
+        const decision = {
+            id: `${context.sessionId}-${Date.now()}-decision`,
+            timestamp,
+            component: context.scope,
+            previous_assumption: discovery.previousAssumption?.trim() || 'No previous assumption recorded',
+            correction,
+            trigger: discovery.trigger?.trim() || 'Session write-back',
+            confidence: discovery.confidence ?? 'probable',
+            status: 'active',
+            supersedes: null,
+            session_id: context.sessionId,
+        };
+        await hippocampus.recordDecision(hippocampus.mathaDir, decision);
+    }
+    if (dangerPattern) {
+        const zone = {
+            id: `${context.sessionId}-${Date.now()}-danger`,
+            component: context.scope,
+            pattern: dangerPattern,
+            description: discovery.dangerDescription?.trim() ||
+                'Discovered during session write-back',
+        };
+        await hippocampus.recordDangerZone(hippocampus.mathaDir, zone);
+    }
+}
+function findMissingRequiredBuildGates(states) {
+    const required = [1, 2, 3, 4, 5];
+    const missing = [];
+    for (const gateId of required) {
+        const state = states.find((s) => s.gateId === gateId);
+        if (!state || !state.completed)
+            missing.push(gateId);
+    }
+    return missing;
+}
+function routeOperation(operationType) {
+    switch (operationType) {
+        case 'rename':
+        case 'crud':
+            return { modelTier: 'lightweight', tokenBudget: 2000 };
+        case 'business_logic':
+            return { modelTier: 'capable', tokenBudget: 8000 };
+        case 'architecture':
+        case 'frozen_component':
+            return { modelTier: 'capable', tokenBudget: 16000 };
+        default:
+            return { modelTier: 'mid', tokenBudget: 4000 };
+    }
+}
+function isPresent(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isNonEmptyStringArray(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((item) => typeof item === 'string' && item.trim().length > 0));
+}
+function isNonEmptyObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length > 0);
+}
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((v) => typeof v === 'string')
+        : [];
+}

package/dist/brain/hippocampus.js

@@ -0,0 +1,134 @@
+import * as path from 'path';
+import { readJsonOrNull } from '../storage/reader.js';
+import { writeAtomic } from '../storage/writer.js';
+import * as fs from 'fs/promises';
+// ── INTENT ───────────────────────────────────────────────────────────
+/**
+ * Returns the project intent, or null if not yet defined.
+ */
+export async function getIntent(mathaDir) {
+    const intentPath = path.join(mathaDir, 'hippocampus', 'intent.json');
+    return await readJsonOrNull(intentPath);
+}
+// ── RULES ────────────────────────────────────────────────────────────
+/**
+ * Returns all non-negotiable business rules, or an empty array if none exist.
+ */
+export async function getRules(mathaDir) {
+    const rulesPath = path.join(mathaDir, 'hippocampus', 'rules.json');
+    const data = await readJsonOrNull(rulesPath);
+    return data?.rules ?? [];
+}
+// ── DECISIONS ────────────────────────────────────────────────────────
+/**
+ * Records a decision entry to the decision log.
+ * Decision log is append-only: never modifies existing entries.
+ *
+ * @throws if a decision with the same id already exists
+ */
+export async function recordDecision(mathaDir, entry) {
+    const decisionsDir = path.join(mathaDir, 'hippocampus', 'decisions');
+    const decisionPath = path.join(decisionsDir, `${entry.id}.json`);
+    // Guard: reject if decision with this id already exists
+    try {
+        await fs.access(decisionPath);
+        throw new Error(`Decision with id '${entry.id}' already exists`);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        // File does not exist — proceed
+    }
+    await writeAtomic(decisionPath, entry);
+}
+/**
+ * Returns all decision entries, optionally filtered by component.
+ * Results are sorted by timestamp descending (most recent first).
+ *
+ * @param component - Optional filter by component name
+ * @param limit - Optional limit on number of results
+ */
+export async function getDecisions(mathaDir, component, limit) {
+    const decisionsDir = path.join(mathaDir, 'hippocampus', 'decisions');
+    let files;
+    try {
+        files = await fs.readdir(decisionsDir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
+    const entries = [];
+    for (const file of jsonFiles) {
+        const filePath = path.join(decisionsDir, file);
+        try {
+            const entry = await readJsonOrNull(filePath);
+            if (entry)
+                entries.push(entry);
+        }
+        catch {
+            // Skip malformed files
+        }
+    }
+    // Filter by component if provided
+    let filtered = component
+        ? entries.filter((e) => e.component === component)
+        : entries;
+    // Sort by timestamp descending (most recent first)
+    filtered.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    // Apply limit if provided
+    if (limit !== undefined && limit > 0) {
+        filtered = filtered.slice(0, limit);
+    }
+    return filtered;
+}
+// ── DANGER ZONES ─────────────────────────────────────────────────────
+/**
+ * Returns all danger zones, optionally filtered by context string.
+ *
+ * Context matching checks both component and description fields
+ * (case-insensitive).
+ *
+ * @param context - Optional context string to filter by
+ */
+export async function getDangerZones(mathaDir, context) {
+    const dangerZonesPath = path.join(mathaDir, 'hippocampus', 'danger-zones.json');
+    const data = await readJsonOrNull(dangerZonesPath);
+    const zones = data?.zones ?? [];
+    if (!context)
+        return zones;
+    const contextLower = context.toLowerCase();
+    return zones.filter((zone) => zone.component.toLowerCase().includes(contextLower) ||
+        zone.description.toLowerCase().includes(contextLower));
+}
+/**
+ * Records a new danger zone.
+ */
+export async function recordDangerZone(mathaDir, zone) {
+    const dangerZonesPath = path.join(mathaDir, 'hippocampus', 'danger-zones.json');
+    const existing = await readJsonOrNull(dangerZonesPath);
+    const zones = existing?.zones ?? [];
+    zones.push(zone);
+    await writeAtomic(dangerZonesPath, { zones }, { overwrite: true });
+}
+// ── OPEN QUESTIONS ───────────────────────────────────────────────────
+/**
+ * Returns all open questions, or an empty array if none exist.
+ */
+export async function getOpenQuestions(mathaDir) {
+    const questionsPath = path.join(mathaDir, 'hippocampus', 'open-questions.json');
+    const data = await readJsonOrNull(questionsPath);
+    return data?.questions ?? [];
+}
+/**
+ * Records a new open question.
+ */
+export async function recordOpenQuestion(mathaDir, question) {
+    const questionsPath = path.join(mathaDir, 'hippocampus', 'open-questions.json');
+    const existing = await readJsonOrNull(questionsPath);
+    const questions = existing?.questions ?? [];
+    questions.push(question);
+    await writeAtomic(questionsPath, { questions }, { overwrite: true });
+}