@theromans/convex-dobty 0.1.0

package/dist/component/potentialAnalysis.js

@@ -0,0 +1,1035 @@
+/**
+ * 5DoBT Potential Value Analysis — CRUD + Compute functions.
+ * Implements the 7-step process (FR-D-PA.1 through FR-D-PA.7).
+ */
+import { mutation, query } from "./_generated/server.js";
+import { v } from "convex/values";
+import { isValidSubArea } from "../data/influence-areas.js";
+import { DEFAULT_SENSITIVITY, DEFAULT_LIFETIME } from "../data/types.js";
+// ── Analysis Lifecycle ──
+/** Create a new 5DoBT Potential Analysis */
+export const createAnalysis = mutation({
+    args: {
+        workspaceId: v.string(),
+        userId: v.string(),
+        name: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        const id = await ctx.db.insert("potentialAnalyses", {
+            workspaceId: args.workspaceId,
+            name: args.name,
+            currentStep: 1,
+            status: "draft",
+            createdBy: args.userId,
+            createdAt: now,
+            updatedAt: now,
+        });
+        return { analysisId: id };
+    },
+});
+/** Get a full analysis with all step data */
+export const getAnalysis = query({
+    args: { analysisId: v.id("potentialAnalyses") },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            return null;
+        const charter = await ctx.db
+            .query("paProjectCharters")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        const definitionsOfDone = await ctx.db
+            .query("paDefinitionsOfDone")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const influenceAreas = await ctx.db
+            .query("paInfluenceAreas")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const pointsOfChanges = await ctx.db
+            .query("paPointsOfChanges")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const fieldsOfAction = await ctx.db
+            .query("paFieldsOfAction")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const potentialStatuses = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const factsFigures = await ctx.db
+            .query("paFactsFigures")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const calculations = await ctx.db
+            .query("paCalculations")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const summary = await ctx.db
+            .query("paCalculationSummaries")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        return {
+            ...analysis,
+            charter,
+            definitionsOfDone: definitionsOfDone.sort((a, b) => a.number - b.number),
+            influenceAreas,
+            pointsOfChanges,
+            fieldsOfAction,
+            potentialStatuses,
+            factsFigures,
+            calculations,
+            summary,
+        };
+    },
+});
+/** Get analysis status summary */
+export const getAnalysisStatus = query({
+    args: { analysisId: v.id("potentialAnalyses") },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            return null;
+        const charter = await ctx.db
+            .query("paProjectCharters")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        const dods = await ctx.db
+            .query("paDefinitionsOfDone")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const areas = await ctx.db
+            .query("paInfluenceAreas")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const pocs = await ctx.db
+            .query("paPointsOfChanges")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const foas = await ctx.db
+            .query("paFieldsOfAction")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const statuses = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        // Per-dimension counts
+        const dimensionCounts = {};
+        for (const foa of foas) {
+            if (!dimensionCounts[foa.dobt_dimension]) {
+                dimensionCounts[foa.dobt_dimension] = { foas: 0, sp: 0, nsp: 0 };
+            }
+            dimensionCounts[foa.dobt_dimension].foas++;
+            if (foa.influence_type === "SP")
+                dimensionCounts[foa.dobt_dimension].sp++;
+            else
+                dimensionCounts[foa.dobt_dimension].nsp++;
+        }
+        // Status lifecycle counts
+        const statusCounts = {};
+        for (const s of statuses) {
+            statusCounts[s.status] = (statusCounts[s.status] ?? 0) + 1;
+        }
+        return {
+            currentStep: analysis.currentStep,
+            status: analysis.status,
+            name: analysis.name,
+            steps: {
+                1: { complete: !!charter, label: "Project Charter" },
+                2: { complete: dods.length > 0, count: dods.length, label: "Definition of Done" },
+                3: { complete: areas.length > 0, count: areas.length, label: "Influence Areas" },
+                4: { complete: pocs.length > 0, count: pocs.length, label: "Points of Changes" },
+                5: { complete: foas.length > 0, count: foas.length, label: "Fields of Action" },
+                6: { complete: statuses.length > 0, count: statuses.length, label: "Potential Status" },
+                7: { complete: false, label: "Calculation Summary" },
+            },
+            dimensionCounts,
+            statusCounts,
+            totals: {
+                sp: foas.filter((f) => f.influence_type === "SP").length,
+                nsp: foas.filter((f) => f.influence_type === "NSP").length,
+            },
+        };
+    },
+});
+// ── Step I: Project Charter ──
+/** Create or update Project Charter */
+export const updateProjectCharter = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        name: v.string(),
+        date: v.string(),
+        business_case: v.string(),
+        problem_statement: v.string(),
+        goal: v.string(),
+        scope_in: v.string(),
+        scope_out: v.string(),
+        objectives: v.any(),
+        conditions: v.optional(v.string()),
+        risks: v.optional(v.any()),
+        costs: v.optional(v.string()),
+        milestones: v.optional(v.any()),
+        project_team: v.optional(v.any()),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        const existing = await ctx.db
+            .query("paProjectCharters")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        const { analysisId, ...charterData } = args;
+        if (existing) {
+            await ctx.db.replace(existing._id, { analysisId, ...charterData });
+            return { charterId: existing._id, updated: true };
+        }
+        else {
+            const id = await ctx.db.insert("paProjectCharters", { analysisId, ...charterData });
+            // Update analysis name from charter
+            await ctx.db.patch(args.analysisId, {
+                name: args.name,
+                status: "in_progress",
+                updatedAt: Date.now(),
+            });
+            return { charterId: id, updated: false };
+        }
+    },
+});
+// ── Step II: Definition of Done ──
+/** Add a Definition of Done item */
+export const addDefinitionOfDone = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        definition: v.string(),
+        description: v.string(),
+        effect_type: v.string(),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        const validTypes = ["organizational", "process_method", "systemic"];
+        if (!validTypes.includes(args.effect_type)) {
+            throw new Error(`effect_type must be one of: ${validTypes.join(", ")}`);
+        }
+        // Auto-increment number
+        const existing = await ctx.db
+            .query("paDefinitionsOfDone")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const nextNumber = existing.length > 0
+            ? Math.max(...existing.map((d) => d.number)) + 1
+            : 1;
+        const id = await ctx.db.insert("paDefinitionsOfDone", {
+            analysisId: args.analysisId,
+            number: nextNumber,
+            definition: args.definition,
+            description: args.description,
+            effect_type: args.effect_type,
+        });
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { dodId: id, number: nextNumber };
+    },
+});
+/** Update a Definition of Done item */
+export const updateDefinitionOfDone = mutation({
+    args: {
+        dodId: v.id("paDefinitionsOfDone"),
+        definition: v.optional(v.string()),
+        description: v.optional(v.string()),
+        effect_type: v.optional(v.string()),
+    },
+    handler: async (ctx, args) => {
+        const dod = await ctx.db.get(args.dodId);
+        if (!dod)
+            throw new Error("Definition of Done not found");
+        if (args.effect_type) {
+            const validTypes = ["organizational", "process_method", "systemic"];
+            if (!validTypes.includes(args.effect_type)) {
+                throw new Error(`effect_type must be one of: ${validTypes.join(", ")}`);
+            }
+        }
+        const update = {};
+        if (args.definition !== undefined)
+            update.definition = args.definition;
+        if (args.description !== undefined)
+            update.description = args.description;
+        if (args.effect_type !== undefined)
+            update.effect_type = args.effect_type;
+        await ctx.db.patch(args.dodId, update);
+        await ctx.db.patch(dod.analysisId, { updatedAt: Date.now() });
+    },
+});
+/** Delete a Definition of Done item */
+export const deleteDefinitionOfDone = mutation({
+    args: { dodId: v.id("paDefinitionsOfDone") },
+    handler: async (ctx, args) => {
+        const dod = await ctx.db.get(args.dodId);
+        if (!dod)
+            return;
+        await ctx.db.delete(args.dodId);
+        await ctx.db.patch(dod.analysisId, { updatedAt: Date.now() });
+    },
+});
+// ── Step III: Influence Areas ──
+/** Select an influence area */
+export const selectInfluenceArea = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        dobt_dimension: v.string(),
+        sub_area_key: v.string(),
+        potential_description: v.string(),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        if (!isValidSubArea(args.dobt_dimension, args.sub_area_key)) {
+            throw new Error(`Invalid sub-area: ${args.dobt_dimension}/${args.sub_area_key}`);
+        }
+        // Check if already selected
+        const existing = await ctx.db
+            .query("paInfluenceAreas")
+            .withIndex("by_analysis_dimension", (q) => q.eq("analysisId", args.analysisId).eq("dobt_dimension", args.dobt_dimension))
+            .collect();
+        const duplicate = existing.find((a) => a.sub_area_key === args.sub_area_key);
+        if (duplicate) {
+            // Update description
+            await ctx.db.patch(duplicate._id, { potential_description: args.potential_description });
+            return { areaId: duplicate._id, updated: true };
+        }
+        const id = await ctx.db.insert("paInfluenceAreas", {
+            analysisId: args.analysisId,
+            dobt_dimension: args.dobt_dimension,
+            sub_area_key: args.sub_area_key,
+            potential_description: args.potential_description,
+        });
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { areaId: id, updated: false };
+    },
+});
+/** Deselect an influence area */
+export const deselectInfluenceArea = mutation({
+    args: { areaId: v.id("paInfluenceAreas") },
+    handler: async (ctx, args) => {
+        const area = await ctx.db.get(args.areaId);
+        if (!area)
+            return;
+        await ctx.db.delete(args.areaId);
+        await ctx.db.patch(area.analysisId, { updatedAt: Date.now() });
+    },
+});
+// ── Step IV: Points of Changes ──
+/** Add a Point of Change */
+export const addPointOfChange = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        influence_area_ref: v.id("paInfluenceAreas"),
+        poc_description: v.string(),
+        definition_of_done_refs: v.any(),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        const area = await ctx.db.get(args.influence_area_ref);
+        if (!area)
+            throw new Error("Influence area not found");
+        const id = await ctx.db.insert("paPointsOfChanges", {
+            analysisId: args.analysisId,
+            influence_area_ref: args.influence_area_ref,
+            poc_description: args.poc_description,
+            definition_of_done_refs: args.definition_of_done_refs,
+        });
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { pocId: id };
+    },
+});
+/** Delete a Point of Change */
+export const deletePointOfChange = mutation({
+    args: { pocId: v.id("paPointsOfChanges") },
+    handler: async (ctx, args) => {
+        const poc = await ctx.db.get(args.pocId);
+        if (!poc)
+            return;
+        await ctx.db.delete(args.pocId);
+        await ctx.db.patch(poc.analysisId, { updatedAt: Date.now() });
+    },
+});
+// ── Step V: Fields of Action ──
+/** Add a Field of Action */
+export const addFieldOfAction = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        poc_ref: v.id("paPointsOfChanges"),
+        potential_description: v.string(),
+        dobt_dimension: v.string(),
+        influence_type: v.string(),
+        foa_description: v.string(),
+        kpi_influence: v.string(),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        const validDimensions = ["sales", "efficiency", "direct_cost", "risk", "innovation"];
+        if (!validDimensions.includes(args.dobt_dimension)) {
+            throw new Error(`dobt_dimension must be one of: ${validDimensions.join(", ")}`);
+        }
+        if (args.influence_type !== "SP" && args.influence_type !== "NSP") {
+            throw new Error("influence_type must be SP or NSP");
+        }
+        const poc = await ctx.db.get(args.poc_ref);
+        if (!poc)
+            throw new Error("Point of Change not found");
+        const id = await ctx.db.insert("paFieldsOfAction", {
+            analysisId: args.analysisId,
+            poc_ref: args.poc_ref,
+            potential_description: args.potential_description,
+            dobt_dimension: args.dobt_dimension,
+            influence_type: args.influence_type,
+            foa_description: args.foa_description,
+            kpi_influence: args.kpi_influence,
+        });
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { foaId: id };
+    },
+});
+/** Delete a Field of Action */
+export const deleteFieldOfAction = mutation({
+    args: { foaId: v.id("paFieldsOfAction") },
+    handler: async (ctx, args) => {
+        const foa = await ctx.db.get(args.foaId);
+        if (!foa)
+            return;
+        // Also delete associated potential status
+        const status = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_foa", (q) => q.eq("foa_ref", args.foaId))
+            .first();
+        if (status)
+            await ctx.db.delete(status._id);
+        await ctx.db.delete(args.foaId);
+        await ctx.db.patch(foa.analysisId, { updatedAt: Date.now() });
+    },
+});
+// ── Step VI: Potential Status ──
+/** Set or update potential status for an FOA */
+export const setPotentialStatus = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        foa_ref: v.id("paFieldsOfAction"),
+        status: v.string(),
+        validation_level: v.optional(v.string()),
+        estimation_value: v.optional(v.number()),
+        estimation_risk: v.optional(v.number()),
+        estimation_explanation: v.optional(v.string()),
+        calculation_ref: v.optional(v.id("paCalculations")),
+        calculation_result: v.optional(v.number()),
+        committed_value_result: v.optional(v.number()),
+        committed_responsible_business_owner: v.optional(v.string()),
+        measured_potential_value: v.optional(v.number()),
+    },
+    handler: async (ctx, args) => {
+        const validStatuses = ["validated", "estimated", "calculated", "committed", "measured"];
+        if (!validStatuses.includes(args.status)) {
+            throw new Error(`status must be one of: ${validStatuses.join(", ")}`);
+        }
+        // Compute estimation_result for estimated status
+        let estimation_result;
+        if (args.status === "estimated" && args.estimation_value !== undefined && args.estimation_risk !== undefined) {
+            estimation_result = args.estimation_value * (1 - args.estimation_risk);
+        }
+        const data = {
+            analysisId: args.analysisId,
+            foa_ref: args.foa_ref,
+            status: args.status,
+            validation_level: args.validation_level,
+            estimation_value: args.estimation_value,
+            estimation_risk: args.estimation_risk,
+            estimation_explanation: args.estimation_explanation,
+            estimation_result,
+            calculation_ref: args.calculation_ref,
+            calculation_result: args.calculation_result,
+            committed_value_result: args.committed_value_result,
+            committed_responsible_business_owner: args.committed_responsible_business_owner,
+            measured_potential_value: args.measured_potential_value,
+        };
+        const existing = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_foa", (q) => q.eq("foa_ref", args.foa_ref))
+            .first();
+        let statusId;
+        if (existing) {
+            await ctx.db.replace(existing._id, data);
+            statusId = existing._id;
+        }
+        else {
+            statusId = await ctx.db.insert("paPotentialStatuses", data);
+        }
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { statusId, estimation_result };
+    },
+});
+// ── Step VII: Facts & Figures ──
+/** Add a Facts & Figures entry */
+export const addFactFigure = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        name: v.string(),
+        unit: v.string(),
+        value: v.number(),
+    },
+    handler: async (ctx, args) => {
+        const id = await ctx.db.insert("paFactsFigures", {
+            analysisId: args.analysisId,
+            name: args.name,
+            unit: args.unit,
+            value: args.value,
+        });
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { factId: id };
+    },
+});
+/** Delete a Facts & Figures entry */
+export const deleteFactFigure = mutation({
+    args: { factId: v.id("paFactsFigures") },
+    handler: async (ctx, args) => {
+        const fact = await ctx.db.get(args.factId);
+        if (!fact)
+            return;
+        await ctx.db.delete(args.factId);
+        await ctx.db.patch(fact.analysisId, { updatedAt: Date.now() });
+    },
+});
+/** Add a calculation entry */
+export const addCalculation = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        dobt_dimension: v.string(),
+        potential_description: v.string(),
+        assumptions: v.any(),
+        formula: v.string(),
+        result: v.number(),
+    },
+    handler: async (ctx, args) => {
+        const id = await ctx.db.insert("paCalculations", {
+            analysisId: args.analysisId,
+            dobt_dimension: args.dobt_dimension,
+            potential_description: args.potential_description,
+            assumptions: args.assumptions,
+            formula: args.formula,
+            result: args.result,
+        });
+        await ctx.db.patch(args.analysisId, { updatedAt: Date.now() });
+        return { calculationId: id };
+    },
+});
+/** Delete a calculation entry */
+export const deleteCalculation = mutation({
+    args: { calcId: v.id("paCalculations") },
+    handler: async (ctx, args) => {
+        const calc = await ctx.db.get(args.calcId);
+        if (!calc)
+            return;
+        await ctx.db.delete(args.calcId);
+        await ctx.db.patch(calc.analysisId, { updatedAt: Date.now() });
+    },
+});
+// ── Step VII: Calculation Summary ──
+/** Compute and cache the Calculation Summary */
+export const computeCalculationSummary = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        sensitivity: v.optional(v.any()),
+        lifetime: v.optional(v.any()),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        const sensitivity = args.sensitivity ?? DEFAULT_SENSITIVITY;
+        const lifetime = args.lifetime ?? DEFAULT_LIFETIME;
+        // Load all FOAs and their statuses
+        const foas = await ctx.db
+            .query("paFieldsOfAction")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const statuses = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const statusByFoa = new Map(statuses.map((s) => [s.foa_ref.toString(), s]));
+        // Build dimension totals matrix
+        const dimensions = ["sales", "efficiency", "direct_cost", "risk", "innovation"];
+        const dimension_totals = {};
+        for (const dim of dimensions) {
+            dimension_totals[dim] = { sp_total: 0, nsp_total: 0, total: 0 };
+        }
+        const validated_potentials = [];
+        for (const foa of foas) {
+            const ps = statusByFoa.get(foa._id.toString());
+            if (!ps)
+                continue;
+            // Skip validated (qualitative only)
+            if (ps.status === "validated") {
+                validated_potentials.push({
+                    foa_ref: foa._id.toString(),
+                    potential_description: foa.potential_description,
+                    dobt_dimension: foa.dobt_dimension,
+                    validation_level: ps.validation_level ?? "medium",
+                });
+                continue;
+            }
+            // Get the monetary value based on status
+            let value = 0;
+            if (ps.status === "estimated") {
+                value = ps.estimation_result ?? 0;
+            }
+            else if (ps.status === "calculated") {
+                value = ps.calculation_result ?? 0;
+            }
+            else if (ps.status === "committed") {
+                value = ps.committed_value_result ?? 0;
+            }
+            else if (ps.status === "measured") {
+                value = ps.measured_potential_value ?? 0;
+            }
+            const dt = dimension_totals[foa.dobt_dimension];
+            if (!dt)
+                continue;
+            if (foa.influence_type === "SP") {
+                dt.sp_total += value;
+            }
+            else {
+                dt.nsp_total += value;
+            }
+            dt.total += value;
+        }
+        // Grand totals
+        let grand_total_sp = 0;
+        let grand_total_nsp = 0;
+        let grand_total = 0;
+        for (const dt of Object.values(dimension_totals)) {
+            grand_total_sp += dt.sp_total;
+            grand_total_nsp += dt.nsp_total;
+            grand_total += dt.total;
+        }
+        // Sensitivity analytics — margin effects from SP totals only
+        const sensitivityMap = {
+            sales: sensitivity.revenue_to_margin,
+            efficiency: sensitivity.efficiency_to_margin,
+            direct_cost: sensitivity.direct_cost_to_margin,
+            risk: sensitivity.risk_to_margin,
+            innovation: sensitivity.innovation_to_margin,
+        };
+        const margin_effects = {};
+        let total_margin_effect = 0;
+        for (const dim of dimensions) {
+            const me = dimension_totals[dim].sp_total * (sensitivityMap[dim] ?? 0);
+            margin_effects[dim] = Math.round(me);
+            total_margin_effect += Math.round(me);
+        }
+        // 3-year projection
+        const years = ["year_1", "year_2", "year_3"];
+        const yearRates = [lifetime.year_1, lifetime.year_2, lifetime.year_3];
+        const projection = {};
+        const projectionTotals = {};
+        for (const dim of dimensions) {
+            projectionTotals[dim] = 0;
+        }
+        let grandProjectionTotal = 0;
+        for (let yi = 0; yi < years.length; yi++) {
+            const yearKey = years[yi];
+            const rate = yearRates[yi];
+            projection[yearKey] = {};
+            let yearTotal = 0;
+            for (const dim of dimensions) {
+                const val = Math.round(margin_effects[dim] * rate);
+                projection[yearKey][dim] = val;
+                projectionTotals[dim] += val;
+                yearTotal += val;
+            }
+            projection[yearKey].total = yearTotal;
+            grandProjectionTotal += yearTotal;
+        }
+        projection.total = { ...projectionTotals, grand_total: grandProjectionTotal };
+        // Store summary
+        const summaryData = {
+            analysisId: args.analysisId,
+            dimension_totals,
+            grand_total_sp: Math.round(grand_total_sp),
+            grand_total_nsp: Math.round(grand_total_nsp),
+            grand_total: Math.round(grand_total),
+            sensitivity,
+            margin_effects,
+            total_margin_effect,
+            lifetime,
+            projection,
+            validated_potentials,
+            calculatedAt: Date.now(),
+        };
+        const existing = await ctx.db
+            .query("paCalculationSummaries")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        if (existing) {
+            await ctx.db.replace(existing._id, summaryData);
+            return { summaryId: existing._id };
+        }
+        else {
+            const id = await ctx.db.insert("paCalculationSummaries", summaryData);
+            return { summaryId: id };
+        }
+    },
+});
+// ── Step Navigation ──
+/** Advance to the next step with validation */
+export const advanceStep = mutation({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        targetStep: v.number(),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            throw new Error("Analysis not found");
+        if (args.targetStep < 1 || args.targetStep > 7) {
+            throw new Error("targetStep must be between 1 and 7");
+        }
+        // Allow going back without validation
+        if (args.targetStep <= analysis.currentStep) {
+            return { currentStep: analysis.currentStep };
+        }
+        // Validate each step that must be complete
+        for (let step = analysis.currentStep; step < args.targetStep; step++) {
+            if (step === 1) {
+                const charter = await ctx.db
+                    .query("paProjectCharters")
+                    .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+                    .first();
+                if (!charter)
+                    throw new Error("Step I: Project Charter is required before advancing");
+            }
+            else if (step === 2) {
+                const dods = await ctx.db
+                    .query("paDefinitionsOfDone")
+                    .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+                    .collect();
+                if (dods.length === 0)
+                    throw new Error("Step II: At least one Definition of Done is required");
+            }
+            else if (step === 3) {
+                const areas = await ctx.db
+                    .query("paInfluenceAreas")
+                    .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+                    .collect();
+                if (areas.length === 0)
+                    throw new Error("Step III: At least one Influence Area must be selected");
+            }
+            else if (step === 4) {
+                const pocs = await ctx.db
+                    .query("paPointsOfChanges")
+                    .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+                    .collect();
+                if (pocs.length === 0)
+                    throw new Error("Step IV: At least one Point of Change is required");
+            }
+            else if (step === 5) {
+                const foas = await ctx.db
+                    .query("paFieldsOfAction")
+                    .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+                    .collect();
+                if (foas.length === 0)
+                    throw new Error("Step V: At least one Field of Action is required");
+            }
+            else if (step === 6) {
+                const statuses = await ctx.db
+                    .query("paPotentialStatuses")
+                    .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+                    .collect();
+                if (statuses.length === 0)
+                    throw new Error("Step VI: At least one Potential Status must be set");
+            }
+        }
+        const newStatus = args.targetStep === 7 ? "completed" : "in_progress";
+        await ctx.db.patch(args.analysisId, {
+            currentStep: args.targetStep,
+            status: newStatus,
+            updatedAt: Date.now(),
+        });
+        return { currentStep: args.targetStep };
+    },
+});
+/** List analyses for a workspace */
+export const listAnalyses = query({
+    args: { workspaceId: v.string() },
+    handler: async (ctx, args) => {
+        return await ctx.db
+            .query("potentialAnalyses")
+            .withIndex("by_workspace", (q) => q.eq("workspaceId", args.workspaceId))
+            .collect();
+    },
+});
+// ── AI Tool Queries (Section 7) ──
+/** Suggest influence areas based on analysis context (AI tool data provider) */
+export const suggestInfluenceAreas = query({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            return null;
+        const charter = await ctx.db
+            .query("paProjectCharters")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        const dods = await ctx.db
+            .query("paDefinitionsOfDone")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        // Already selected areas
+        const selected = await ctx.db
+            .query("paInfluenceAreas")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const selectedKeys = new Set(selected.map((a) => `${a.dobt_dimension}/${a.sub_area_key}`));
+        // Return all available areas with selection state + context for AI reasoning
+        const { DOBT_DIMENSIONS } = await import("../data/influence-areas.js");
+        const availableAreas = DOBT_DIMENSIONS.flatMap((dim) => dim.subAreas.map((sa) => ({
+            dimension: dim.key,
+            dimensionLabel: dim.label,
+            subAreaKey: sa.key,
+            subAreaLabel: sa.label,
+            alreadySelected: selectedKeys.has(`${dim.key}/${sa.key}`),
+        })));
+        return {
+            charter: charter
+                ? {
+                    name: charter.name,
+                    business_case: charter.business_case,
+                    problem_statement: charter.problem_statement,
+                    goal: charter.goal,
+                    scope_in: charter.scope_in,
+                }
+                : null,
+            definitionsOfDone: dods.map((d) => ({
+                definition: d.definition,
+                description: d.description,
+                effect_type: d.effect_type,
+            })),
+            availableAreas,
+            selectedCount: selected.length,
+        };
+    },
+});
+/** Provide estimation context for a Field of Action (AI tool data provider) */
+export const estimatePotential = query({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+        foaId: v.optional(v.id("paFieldsOfAction")),
+    },
+    handler: async (ctx, args) => {
+        const analysis = await ctx.db.get(args.analysisId);
+        if (!analysis)
+            return null;
+        // Load all FOAs with their statuses for context
+        const foas = await ctx.db
+            .query("paFieldsOfAction")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const statuses = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const statusByFoa = new Map(statuses.map((s) => [s.foa_ref.toString(), s]));
+        // Build context with existing estimations for reference
+        const existingEstimations = foas
+            .filter((f) => {
+            const s = statusByFoa.get(f._id.toString());
+            return s && (s.status === "estimated" || s.status === "calculated");
+        })
+            .map((f) => {
+            const s = statusByFoa.get(f._id.toString());
+            return {
+                dimension: f.dobt_dimension,
+                influence_type: f.influence_type,
+                description: f.foa_description,
+                value: s.estimation_result ?? s.calculation_result ?? 0,
+            };
+        });
+        // Target FOA details if specified
+        let targetFoa = null;
+        if (args.foaId) {
+            const foa = await ctx.db.get(args.foaId);
+            if (foa) {
+                const ps = statusByFoa.get(foa._id.toString());
+                targetFoa = {
+                    ...foa,
+                    currentStatus: ps ?? null,
+                };
+            }
+        }
+        // Facts & figures for financial context
+        const facts = await ctx.db
+            .query("paFactsFigures")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        return {
+            targetFoa,
+            existingEstimations,
+            factsFigures: facts,
+            totalFoas: foas.length,
+            estimatedCount: statuses.filter((s) => s.status !== "validated").length,
+        };
+    },
+});
+/** Get full calculation summary (AI tool data provider) */
+export const getCalculationSummary = query({
+    args: {
+        analysisId: v.id("potentialAnalyses"),
+    },
+    handler: async (ctx, args) => {
+        const summary = await ctx.db
+            .query("paCalculationSummaries")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .first();
+        if (!summary)
+            return null;
+        // Include FOA count breakdown by dimension
+        const foas = await ctx.db
+            .query("paFieldsOfAction")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", args.analysisId))
+            .collect();
+        const foasByDimension = {};
+        for (const foa of foas) {
+            if (!foasByDimension[foa.dobt_dimension]) {
+                foasByDimension[foa.dobt_dimension] = { sp: 0, nsp: 0 };
+            }
+            if (foa.influence_type === "SP")
+                foasByDimension[foa.dobt_dimension].sp++;
+            else
+                foasByDimension[foa.dobt_dimension].nsp++;
+        }
+        return {
+            ...summary,
+            foasByDimension,
+        };
+    },
+});
+// ── Dashboard Query (Section 8) ──
+/** Get 5DoBT Potential Analysis dashboard data */
+export const getPotentialAnalysisDashboard = query({
+    args: {
+        workspaceId: v.string(),
+        analysisId: v.optional(v.id("potentialAnalyses")),
+    },
+    handler: async (ctx, args) => {
+        // If no specific analysis, get the most recent one
+        let analysis;
+        if (args.analysisId) {
+            analysis = await ctx.db.get(args.analysisId);
+        }
+        else {
+            const analyses = await ctx.db
+                .query("potentialAnalyses")
+                .withIndex("by_workspace", (q) => q.eq("workspaceId", args.workspaceId))
+                .collect();
+            if (analyses.length === 0)
+                return null;
+            // Most recent by updatedAt
+            analysis = analyses.sort((a, b) => b.updatedAt - a.updatedAt)[0];
+        }
+        if (!analysis)
+            return null;
+        const analysisId = analysis._id;
+        // Step progress
+        const charter = await ctx.db
+            .query("paProjectCharters")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .first();
+        const dods = await ctx.db
+            .query("paDefinitionsOfDone")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .collect();
+        const areas = await ctx.db
+            .query("paInfluenceAreas")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .collect();
+        const pocs = await ctx.db
+            .query("paPointsOfChanges")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .collect();
+        const foas = await ctx.db
+            .query("paFieldsOfAction")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .collect();
+        const statuses = await ctx.db
+            .query("paPotentialStatuses")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .collect();
+        const summary = await ctx.db
+            .query("paCalculationSummaries")
+            .withIndex("by_analysis", (q) => q.eq("analysisId", analysisId))
+            .first();
+        // Dimension distribution
+        const dimensionDistribution = {};
+        for (const foa of foas) {
+            if (!dimensionDistribution[foa.dobt_dimension]) {
+                dimensionDistribution[foa.dobt_dimension] = { sp: 0, nsp: 0, total: 0 };
+            }
+            dimensionDistribution[foa.dobt_dimension].total++;
+            if (foa.influence_type === "SP")
+                dimensionDistribution[foa.dobt_dimension].sp++;
+            else
+                dimensionDistribution[foa.dobt_dimension].nsp++;
+        }
+        // Status lifecycle counts
+        const statusLifecycle = {};
+        for (const s of statuses) {
+            statusLifecycle[s.status] = (statusLifecycle[s.status] ?? 0) + 1;
+        }
+        return {
+            analysis: {
+                _id: analysis._id,
+                name: analysis.name,
+                currentStep: analysis.currentStep,
+                status: analysis.status,
+                createdAt: analysis.createdAt,
+                updatedAt: analysis.updatedAt,
+            },
+            stepProgress: {
+                1: { complete: !!charter, label: "Project Charter" },
+                2: { complete: dods.length > 0, count: dods.length, label: "Definition of Done" },
+                3: { complete: areas.length > 0, count: areas.length, label: "Influence Areas" },
+                4: { complete: pocs.length > 0, count: pocs.length, label: "Points of Changes" },
+                5: { complete: foas.length > 0, count: foas.length, label: "Fields of Action" },
+                6: { complete: statuses.length > 0, count: statuses.length, label: "Potential Status" },
+                7: { complete: !!summary, label: "Calculation Summary" },
+            },
+            dimensionDistribution,
+            statusLifecycle,
+            totals: {
+                sp: foas.filter((f) => f.influence_type === "SP").length,
+                nsp: foas.filter((f) => f.influence_type === "NSP").length,
+            },
+            calculationSummary: summary
+                ? {
+                    dimension_totals: summary.dimension_totals,
+                    grand_total_sp: summary.grand_total_sp,
+                    grand_total_nsp: summary.grand_total_nsp,
+                    grand_total: summary.grand_total,
+                    margin_effects: summary.margin_effects,
+                    total_margin_effect: summary.total_margin_effect,
+                    projection: summary.projection,
+                }
+                : null,
+        };
+    },
+});
+//# sourceMappingURL=potentialAnalysis.js.map