fullstackgtm 0.17.0 → 0.19.0

package/dist/connector.js

@@ -23,6 +23,124 @@ export async function applyPatchPlan(connector, plan, options) {
     const results = [];
     let attempted = 0;
     let applied = 0;
+    let appliedSinceRecheck = 0;
+    // Pass 0 — snapshot-backed checks: plan-level guards and per-record
+    // filter re-verification, both against a FRESH snapshot. Cross-record
+    // eligibility ("the account still has no open contractsent deal") cannot
+    // be checked through per-operation field reads.
+    //
+    // These checks are NOT one-shot: a concurrent edit can land mid-apply,
+    // after the initial verification but before later writes (the TOCTOU
+    // window). Providers offer no compare-and-swap, so the window cannot be
+    // closed — but it can be shrunk: re-run the snapshot checks after the
+    // first write and every `recheckEvery` writes, conflicting out any
+    // operation whose record went stale mid-run.
+    const needsSnapshot = ((plan.guards && plan.guards.length > 0) || plan.filter) && connector.fetchSnapshot;
+    const recheckEvery = Math.max(1, options.recheckEvery ?? 25);
+    const staleIds = new Set();
+    let guardFailure = null;
+    const refreshSnapshotChecks = async () => {
+        if (!needsSnapshot)
+            return;
+        const { evaluateGuard, eligibleIds } = await import("./bulkUpdate.js");
+        const liveSnapshot = await connector.fetchSnapshot();
+        if (plan.filter) {
+            const stillEligible = eligibleIds(liveSnapshot, plan.filter.objectType, plan.filter.where);
+            staleIds.clear();
+            for (const operation of plan.operations) {
+                if (!stillEligible.has(operation.objectId))
+                    staleIds.add(operation.objectId);
+            }
+        }
+        for (const guard of plan.guards ?? []) {
+            const failure = evaluateGuard(liveSnapshot, guard);
+            if (failure) {
+                guardFailure = failure;
+                return;
+            }
+        }
+    };
+    await refreshSnapshotChecks();
+    if (guardFailure) {
+        for (const operation of plan.operations) {
+            results.push({
+                operationId: operation.id,
+                status: approved.has(operation.id) ? "conflict" : "skipped",
+                detail: approved.has(operation.id)
+                    ? `${guardFailure} No operation in this plan was applied — re-plan against current data.`
+                    : "Operation was not approved.",
+            });
+        }
+        return {
+            planId: plan.id,
+            provider: connector.provider,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            status: "rejected",
+            results,
+        };
+    }
+    const staleByFilter = plan.filter ? staleIds : null;
+    // Pass 1 — conflict detection. Re-read the written field (beforeValue
+    // compare-and-set) and any explicit preconditions. A conflicted operation
+    // never writes; if it carries a groupId, the whole group is poisoned so
+    // multi-record changes stay all-or-nothing.
+    const conflicts = new Map();
+    const poisonedGroups = new Set();
+    if (staleByFilter && staleByFilter.size > 0) {
+        for (const operation of plan.operations) {
+            if (!approved.has(operation.id) || !staleByFilter.has(operation.objectId))
+                continue;
+            conflicts.set(operation.id, {
+                operationId: operation.id,
+                status: "conflict",
+                detail: `Record ${operation.objectType}/${operation.objectId} no longer matches the plan's filter [${plan.filter.where.join(" AND ")}] — it changed since the plan was built. Re-plan against current data.`,
+            });
+            if (operation.groupId)
+                poisonedGroups.add(operation.groupId);
+        }
+    }
+    if (checkConflicts && connector.readField) {
+        for (const operation of plan.operations) {
+            if (!approved.has(operation.id) || conflicts.has(operation.id))
+                continue;
+            let conflict = null;
+            if (operation.field && FIELD_WRITE_OPERATIONS.has(operation.operation)) {
+                const current = await connector.readField(operation.objectType, operation.objectId, operation.field);
+                const expected = normalizeForComparison(operation.beforeValue);
+                const found = normalizeForComparison(current);
+                if (expected !== found) {
+                    conflict = {
+                        operationId: operation.id,
+                        status: "conflict",
+                        detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+                        providerData: { currentValue: current ?? null },
+                    };
+                }
+            }
+            if (!conflict && operation.preconditions) {
+                for (const precondition of operation.preconditions) {
+                    const current = await connector.readField(operation.objectType, operation.objectId, precondition.field);
+                    const expected = normalizeForComparison(precondition.expectedValue);
+                    const found = normalizeForComparison(current);
+                    if (expected !== found) {
+                        conflict = {
+                            operationId: operation.id,
+                            status: "conflict",
+                            detail: `Precondition failed: ${precondition.field} was ${expected ?? "∅"} when the plan was built, found ${found ?? "∅"} now. The record changed — re-plan before writing.`,
+                            providerData: { preconditionField: precondition.field, currentValue: current ?? null },
+                        };
+                        break;
+                    }
+                }
+            }
+            if (conflict) {
+                conflicts.set(operation.id, conflict);
+                if (operation.groupId)
+                    poisonedGroups.add(operation.groupId);
+            }
+        }
+    }
     for (const operation of plan.operations) {
         if (!approved.has(operation.id)) {
             results.push({
@@ -41,30 +159,53 @@ export async function applyPatchPlan(connector, plan, options) {
             });
             continue;
         }
-        if (checkConflicts &&
-            connector.readField &&
-            operation.field &&
-            FIELD_WRITE_OPERATIONS.has(operation.operation)) {
-            const current = await connector.readField(operation.objectType, operation.objectId, operation.field);
-            const expected = normalizeForComparison(operation.beforeValue);
-            const found = normalizeForComparison(current);
-            if (expected !== found) {
-                results.push({
-                    operationId: operation.id,
-                    status: "conflict",
-                    detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
-                    providerData: { currentValue: current ?? null },
-                });
-                continue;
-            }
+        if (guardFailure) {
+            results.push({
+                operationId: operation.id,
+                status: "conflict",
+                detail: `${guardFailure} Detected mid-apply — this and all remaining operations were not applied.`,
+            });
+            continue;
+        }
+        const conflict = conflicts.get(operation.id);
+        if (conflict) {
+            results.push(conflict);
+            continue;
+        }
+        if (staleByFilter && staleByFilter.has(operation.objectId)) {
+            results.push({
+                operationId: operation.id,
+                status: "conflict",
+                detail: `Record ${operation.objectType}/${operation.objectId} no longer matches the plan's filter [${plan.filter.where.join(" AND ")}] (changed mid-apply). Not applied — re-plan against current data.`,
+            });
+            if (operation.groupId)
+                poisonedGroups.add(operation.groupId);
+            continue;
+        }
+        if (operation.groupId && poisonedGroups.has(operation.groupId)) {
+            results.push({
+                operationId: operation.id,
+                status: "skipped",
+                detail: `Skipped: another operation in group ${operation.groupId} hit a conflict — the group applies all-or-nothing.`,
+            });
+            continue;
         }
         const resolved = override === undefined ? operation : { ...operation, afterValue: override };
         attempted += 1;
         try {
             const result = await connector.applyOperation(resolved);
             results.push(result);
-            if (result.status === "applied")
+            if (result.status === "applied") {
                 applied += 1;
+                appliedSinceRecheck += 1;
+                // shrink the TOCTOU window: first write fires a re-check (a
+                // concurrent editor reacting to our changes shows up immediately),
+                // then re-check on a fixed cadence
+                if (applied === 1 || appliedSinceRecheck >= recheckEvery) {
+                    appliedSinceRecheck = 0;
+                    await refreshSnapshotChecks();
+                }
+            }
         }
         catch (error) {
             results.push({

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export { buildBulkUpdatePlan, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export { CONFIG_FILE_NAME, loadConfig, mergePolicy, resolveConfiguredRules, type FullstackgtmConfig, type LoadedConfig, } from "./config.ts";
 export { applyPatchPlan, type ApplyPatchPlanOptions } from "./connector.ts";
 export { createHubspotConnector, type HubspotConnectorOptions } from "./connectors/hubspot.ts";
@@ -17,9 +18,10 @@ export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mapp
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.ts";
 export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, suggestCallDeal, summarizeInsights, type CallDealSuggestion, type CallInsightType, type ExtractedCallInsight, type ParsedCall, type ParsedTranscriptSegment, } from "./calls.ts";
 export { sampleSnapshot } from "./sampleData.ts";
-export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
+export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
 export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
-export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, type CaptureEntry, type CaptureOptions, type ClaimFront, type ClaimIntensity, type FrontDrift, type FrontState, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type SpanVerificationFailure, } from "./market.ts";
+export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, type CaptureEntry, type CaptureOptions, type ClaimFront, type ClaimIntensity, type FrontDrift, type FrontState, type MarketAxis, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type SpanVerificationFailure, } from "./market.ts";
+export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, type AxesReport, type AxisAssessment, type AxisPairing, type PrincipalComponent, } from "./marketAxes.ts";
 export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type ClassifyMarketResult, type MarketWorksheet, } from "./marketClassify.ts";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { auditSnapshot, defaultPolicy } from "./audit.js";
+export { buildBulkUpdatePlan, parseWhere } from "./bulkUpdate.js";
 export { CONFIG_FILE_NAME, loadConfig, mergePolicy, resolveConfiguredRules, } from "./config.js";
 export { applyPatchPlan } from "./connector.js";
 export { createHubspotConnector } from "./connectors/hubspot.js";
@@ -17,9 +18,10 @@ export { HUBSPOT_DEFAULT_FIELD_MAPPINGS, SALESFORCE_DEFAULT_FIELD_MAPPINGS, mapp
 export { accountSingleSourceRule, activeDealAccountWithoutContactsRule, auditFindingId, buildSnapshotIndex, builtinAuditRules, closingSoonInactiveRule, duplicateAccountDomainRule, duplicateContactEmailRule, duplicateOpenDealRule, missingDealAccountRule, missingDealAmountRule, missingDealOwnerRule, orphanAccountRule, pastCloseDateRule, patchOperationId, provenanceSummary, requiresHumanInput, staleDealRule, } from "./rules.js";
 export { extractCallInsights, normalizeTranscript, parseCall, parseTranscript, suggestCallDeal, summarizeInsights, } from "./calls.js";
 export { sampleSnapshot } from "./sampleData.js";
-export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
+export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 export { resolveRecord } from "./resolve.js";
 export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, } from "./marketAxes.js";
 export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
 export { marketMapToHtml, marketMapToMarkdown } from "./marketReport.js";
 export { suggestValues } from "./suggest.js";

package/dist/market.d.ts

@@ -41,6 +41,18 @@ export type MarketVendor = {
     };
     notes?: string;
 };
+export type MarketAxis = {
+    id: string;
+    label: string;
+    negativePole: string;
+    positivePole: string;
+    /** How a human scores a claim on this axis — the axis IS this rubric. */
+    rubric: string;
+    /** e.g. "validated", "proposal", "proposal (PC2-validated)". Reviewer-facing. */
+    status?: string;
+    /** claimId → score in [-1, 1]; null = the axis does not apply to this claim. */
+    claimScores: Record<string, number | null>;
+};
 export type MarketConfig = {
     category: string;
     anchorVendor?: string;
@@ -48,6 +60,10 @@ export type MarketConfig = {
     claims: MarketClaim[];
     /** The LOUD/QUIET/ABSENT/UNOBSERVABLE judging rule, stated for reviewers. */
     surfaceRule?: string;
+    /** Strategic axes as claim-scoring rubrics — config, not code. */
+    axes?: MarketAxis[];
+    /** [xAxisId, yAxisId] for the report's strategic map. */
+    primaryAxes?: [string, string];
 };
 export type MarketObservation = {
     /** stableHash(category, runLabel, vendorId, claimId) — deterministic. */

package/dist/market.js

@@ -49,6 +49,33 @@ export function parseMarketConfig(raw) {
     if (config.anchorVendor && !config.vendors.some((v) => v.id === config.anchorVendor)) {
         throw new Error(`market config: anchorVendor "${config.anchorVendor}" is not in vendors`);
     }
+    if (config.axes) {
+        const claimIds = new Set(config.claims.map((claim) => claim.id));
+        const axisIds = new Set();
+        for (const axis of config.axes) {
+            if (!axis.id)
+                throw new Error("market config: axis missing id");
+            if (axisIds.has(axis.id))
+                throw new Error(`market config: duplicate axis id "${axis.id}"`);
+            axisIds.add(axis.id);
+            if (!axis.negativePole || !axis.positivePole) {
+                throw new Error(`market config: axis "${axis.id}" needs negativePole and positivePole labels (the strategic map renders them as axis ends)`);
+            }
+            for (const claimId of Object.keys(axis.claimScores ?? {})) {
+                if (!claimIds.has(claimId)) {
+                    throw new Error(`market config: axis "${axis.id}" scores unknown claim "${claimId}"`);
+                }
+            }
+        }
+        if (config.primaryAxes) {
+            if (config.primaryAxes.length !== 2 || config.primaryAxes.some((id) => !axisIds.has(id))) {
+                throw new Error(`market config: primaryAxes must name two configured axes (got ${JSON.stringify(config.primaryAxes)})`);
+            }
+        }
+    }
+    else if (config.primaryAxes) {
+        throw new Error("market config: primaryAxes set but no axes configured");
+    }
     return config;
 }
 export function loadMarketConfig(path) {

package/dist/marketAxes.d.ts

@@ -0,0 +1,77 @@
+import type { MarketAxis, MarketConfig, MarketObservation, ObservationSet } from "./market.ts";
+/**
+ * Axis discovery for a market map — the method that earns a strategic 2x2
+ * instead of asserting one. Axes are claim-scoring rubrics in the config
+ * (reviewable, versioned); a vendor's position on an axis is the
+ * intensity-weighted mean of the scores of claims it voices. Two checks keep
+ * axes honest, both computed deterministically from the stored observations:
+ *
+ *  1. Triangulation — PCA over the vendor × claim intensity matrix gives the
+ *     category's own top variance directions; a real axis correlates with a
+ *     principal component (it is derivable from the data, not just felt).
+ *  2. Orthogonality — two configured axes that correlate ≥ ~0.75 at the
+ *     vendor level are one axis twice. Sometimes that redundancy is the
+ *     finding: the category couples the two ideas, and the empty quadrant is
+ *     the strategic white space.
+ *
+ * Everything here is pure math over the store: same observations, same map.
+ */
+export declare const VOICE_WEIGHT: Record<string, number>;
+/**
+ * Intensity-weighted mean of claim scores over claims the vendor voices.
+ * Claims scored null on the axis are excluded; returns null if the vendor
+ * voices nothing scoreable (e.g. fully unobservable).
+ */
+export declare function axisPosition(vendorId: string, claimScores: Record<string, number | null>, observations: MarketObservation[]): number | null;
+/** Share of the claim space voiced (loud + half-weight quiet) over observable claims. */
+export declare function messageBreadth(vendorId: string, observations: MarketObservation[]): {
+    breadth: number | null;
+    loudCount: number;
+};
+export declare function pearson(xs: number[], ys: number[]): number;
+export type PrincipalComponent = {
+    /** claimId → loading. Sign is arbitrary; read poles from the extremes. */
+    loadings: Array<{
+        claimId: string;
+        loading: number;
+    }>;
+    /** vendorId → score on this component. */
+    scores: Array<{
+        vendorId: string;
+        score: number;
+    }>;
+};
+export declare function pcaTop2(config: MarketConfig, set: ObservationSet): {
+    vendors: string[];
+    pc1: PrincipalComponent;
+    pc2: PrincipalComponent;
+};
+export type AxisVendorPosition = {
+    vendorId: string;
+    position: number | null;
+};
+export type AxisAssessment = {
+    axis: MarketAxis;
+    positions: AxisVendorPosition[];
+    /** Standard deviation of placeable vendor positions — does the axis separate anyone? */
+    spread: number;
+    rVsPc1: number;
+    rVsPc2: number;
+};
+export type AxisPairing = {
+    aId: string;
+    bId: string;
+    r: number;
+    verdict: "near-orthogonal" | "correlated — weak pair" | "redundant — same axis twice";
+};
+export type AxesReport = {
+    vendors: string[];
+    pc1: PrincipalComponent;
+    pc2: PrincipalComponent;
+    assessments: AxisAssessment[];
+    /** Includes the derived breadth axis in pairings. */
+    pairings: AxisPairing[];
+};
+export declare function pairingVerdict(r: number): AxisPairing["verdict"];
+export declare function assessAxes(config: MarketConfig, set: ObservationSet): AxesReport;
+export declare function axesReportToText(report: AxesReport): string;

package/dist/marketAxes.js

@@ -0,0 +1,199 @@
+/**
+ * Axis discovery for a market map — the method that earns a strategic 2x2
+ * instead of asserting one. Axes are claim-scoring rubrics in the config
+ * (reviewable, versioned); a vendor's position on an axis is the
+ * intensity-weighted mean of the scores of claims it voices. Two checks keep
+ * axes honest, both computed deterministically from the stored observations:
+ *
+ *  1. Triangulation — PCA over the vendor × claim intensity matrix gives the
+ *     category's own top variance directions; a real axis correlates with a
+ *     principal component (it is derivable from the data, not just felt).
+ *  2. Orthogonality — two configured axes that correlate ≥ ~0.75 at the
+ *     vendor level are one axis twice. Sometimes that redundancy is the
+ *     finding: the category couples the two ideas, and the empty quadrant is
+ *     the strategic white space.
+ *
+ * Everything here is pure math over the store: same observations, same map.
+ */
+export const VOICE_WEIGHT = { loud: 1.0, quiet: 0.5 };
+/**
+ * Intensity-weighted mean of claim scores over claims the vendor voices.
+ * Claims scored null on the axis are excluded; returns null if the vendor
+ * voices nothing scoreable (e.g. fully unobservable).
+ */
+export function axisPosition(vendorId, claimScores, observations) {
+    let num = 0;
+    let den = 0;
+    for (const obs of observations) {
+        if (obs.vendorId !== vendorId)
+            continue;
+        const score = claimScores[obs.claimId];
+        if (score === null || score === undefined)
+            continue;
+        const weight = VOICE_WEIGHT[obs.intensity] ?? 0;
+        if (weight > 0) {
+            num += score * weight;
+            den += weight;
+        }
+    }
+    return den > 0 ? num / den : null;
+}
+/** Share of the claim space voiced (loud + half-weight quiet) over observable claims. */
+export function messageBreadth(vendorId, observations) {
+    let voiced = 0;
+    let observable = 0;
+    let loudCount = 0;
+    for (const obs of observations) {
+        if (obs.vendorId !== vendorId)
+            continue;
+        if (obs.intensity === "unobservable")
+            continue;
+        observable += 1;
+        voiced += VOICE_WEIGHT[obs.intensity] ?? 0;
+        if (obs.intensity === "loud")
+            loudCount += 1;
+    }
+    return { breadth: observable > 0 ? voiced / observable : null, loudCount };
+}
+export function pearson(xs, ys) {
+    const n = xs.length;
+    if (n < 3)
+        return 0;
+    const mx = xs.reduce((sum, x) => sum + x, 0) / n;
+    const my = ys.reduce((sum, y) => sum + y, 0) / n;
+    const sx = Math.sqrt(xs.reduce((sum, x) => sum + (x - mx) ** 2, 0));
+    const sy = Math.sqrt(ys.reduce((sum, y) => sum + (y - my) ** 2, 0));
+    if (!sx || !sy)
+        return 0;
+    return xs.reduce((sum, x, i) => sum + (x - mx) * (ys[i] - my), 0) / (sx * sy);
+}
+export function pcaTop2(config, set) {
+    const claimIds = config.claims.map((claim) => claim.id);
+    const byCell = new Map(set.observations.map((obs) => [`${obs.vendorId}|${obs.claimId}`, obs]));
+    // Exclude fully-unobservable vendors: they carry no information, only zeros.
+    const vendors = config.vendors
+        .map((vendor) => vendor.id)
+        .filter((vendorId) => claimIds.some((claimId) => {
+        const obs = byCell.get(`${vendorId}|${claimId}`);
+        return obs !== undefined && obs.intensity !== "unobservable";
+    }));
+    const matrix = vendors.map((vendorId) => claimIds.map((claimId) => VOICE_WEIGHT[byCell.get(`${vendorId}|${claimId}`)?.intensity ?? ""] ?? 0));
+    const means = claimIds.map((_, j) => matrix.reduce((sum, row) => sum + row[j], 0) / vendors.length);
+    const centered = matrix.map((row) => row.map((value, j) => value - means[j]));
+    const component = (deflate) => {
+        let v = new Array(claimIds.length).fill(1 / Math.sqrt(claimIds.length));
+        for (let iteration = 0; iteration < 300; iteration += 1) {
+            if (deflate) {
+                const dot = v.reduce((sum, x, k) => sum + x * deflate[k], 0);
+                v = v.map((x, k) => x - dot * deflate[k]);
+            }
+            const scores = centered.map((row) => row.reduce((sum, x, j) => sum + x * v[j], 0));
+            v = claimIds.map((_, j) => centered.reduce((sum, row, i) => sum + row[j] * scores[i], 0));
+            const norm = Math.sqrt(v.reduce((sum, x) => sum + x * x, 0)) || 1;
+            v = v.map((x) => x / norm);
+        }
+        return { loadings: v, scores: centered.map((row) => row.reduce((sum, x, j) => sum + x * v[j], 0)) };
+    };
+    const first = component();
+    const second = component(first.loadings);
+    const shape = (raw) => ({
+        loadings: claimIds.map((claimId, j) => ({ claimId, loading: raw.loadings[j] })),
+        scores: vendors.map((vendorId, i) => ({ vendorId, score: raw.scores[i] })),
+    });
+    return { vendors, pc1: shape(first), pc2: shape(second) };
+}
+export function pairingVerdict(r) {
+    const magnitude = Math.abs(r);
+    if (magnitude < 0.4)
+        return "near-orthogonal";
+    if (magnitude < 0.75)
+        return "correlated — weak pair";
+    return "redundant — same axis twice";
+}
+export function assessAxes(config, set) {
+    const { vendors, pc1, pc2 } = pcaTop2(config, set);
+    const pcScore = (pc) => new Map(pc.scores.map((entry) => [entry.vendorId, entry.score]));
+    const pc1ByVendor = pcScore(pc1);
+    const pc2ByVendor = pcScore(pc2);
+    const axes = config.axes ?? [];
+    const positionsById = new Map();
+    const assessments = axes.map((axis) => {
+        const positions = vendors.map((vendorId) => ({
+            vendorId,
+            position: axisPosition(vendorId, axis.claimScores, set.observations),
+        }));
+        const placeable = positions.filter((entry) => entry.position !== null);
+        positionsById.set(axis.id, new Map(placeable.map((entry) => [entry.vendorId, entry.position])));
+        const values = placeable.map((entry) => entry.position);
+        const mean = values.reduce((sum, x) => sum + x, 0) / Math.max(values.length, 1);
+        const spread = Math.sqrt(values.reduce((sum, x) => sum + (x - mean) ** 2, 0) / Math.max(values.length, 1));
+        const aligned = placeable.filter((entry) => pc1ByVendor.has(entry.vendorId));
+        return {
+            axis,
+            positions,
+            spread,
+            rVsPc1: pearson(aligned.map((entry) => entry.position), aligned.map((entry) => pc1ByVendor.get(entry.vendorId))),
+            rVsPc2: pearson(aligned.map((entry) => entry.position), aligned.map((entry) => pc2ByVendor.get(entry.vendorId))),
+        };
+    });
+    // Derived breadth axis joins the orthogonality screen (it's free and often
+    // the only near-orthogonal partner early on).
+    const breadthPositions = new Map();
+    for (const vendorId of vendors) {
+        const { breadth } = messageBreadth(vendorId, set.observations);
+        if (breadth !== null)
+            breadthPositions.set(vendorId, breadth);
+    }
+    positionsById.set("breadth", breadthPositions);
+    const ids = [...axes.map((axis) => axis.id), "breadth"];
+    const pairings = [];
+    for (let i = 0; i < ids.length; i += 1) {
+        for (let j = i + 1; j < ids.length; j += 1) {
+            const a = positionsById.get(ids[i]);
+            const b = positionsById.get(ids[j]);
+            const shared = vendors.filter((vendorId) => a.has(vendorId) && b.has(vendorId));
+            const r = pearson(shared.map((vendorId) => a.get(vendorId)), shared.map((vendorId) => b.get(vendorId)));
+            pairings.push({ aId: ids[i], bId: ids[j], r, verdict: pairingVerdict(r) });
+        }
+    }
+    return { vendors, pc1, pc2, assessments, pairings };
+}
+export function axesReportToText(report) {
+    const lines = [];
+    for (const [label, pc] of [
+        ["PC1", report.pc1],
+        ["PC2", report.pc2],
+    ]) {
+        lines.push(`=== ${label} — claim loadings (extremes; sign is arbitrary, read the poles) ===`);
+        const ordered = [...pc.loadings].sort((a, b) => a.loading - b.loading);
+        for (const entry of ordered.slice(0, 5)) {
+            lines.push(`  ${entry.loading >= 0 ? "+" : ""}${entry.loading.toFixed(2)}  ${entry.claimId}`);
+        }
+        lines.push("   ...");
+        for (const entry of ordered.slice(-5)) {
+            lines.push(`  ${entry.loading >= 0 ? "+" : ""}${entry.loading.toFixed(2)}  ${entry.claimId}`);
+        }
+        lines.push(`  vendor scores: ${[...pc.scores]
+            .sort((a, b) => a.score - b.score)
+            .map((entry) => `${entry.vendorId}=${entry.score >= 0 ? "+" : ""}${entry.score.toFixed(2)}`)
+            .join("  ")}`);
+        lines.push("");
+    }
+    if (report.assessments.length > 0) {
+        lines.push("=== configured axes vs PCA (triangulation: a real axis is derivable from the data) ===");
+        for (const assessment of report.assessments) {
+            lines.push(`  ${assessment.axis.id.padEnd(20)} spread=${assessment.spread.toFixed(3)}  r(PC1)=${assessment.rVsPc1 >= 0 ? "+" : ""}${assessment.rVsPc1.toFixed(2)}  r(PC2)=${assessment.rVsPc2 >= 0 ? "+" : ""}${assessment.rVsPc2.toFixed(2)}  [${assessment.axis.status ?? ""}]`);
+        }
+        lines.push("");
+        lines.push("=== orthogonality screen (|r|>0.75 = redundant pair) ===");
+        for (const pairing of report.pairings) {
+            const flag = pairing.verdict === "redundant — same axis twice" ? "  <-- redundant" : "";
+            lines.push(`  ${pairing.aId.padEnd(18)} x ${pairing.bId.padEnd(18)} r=${pairing.r >= 0 ? "+" : ""}${pairing.r.toFixed(2)}${flag}`);
+        }
+    }
+    else {
+        lines.push("No axes configured. Read the PC loadings above, name the two directions, and add them");
+        lines.push("to market.config.json as axes: [{ id, label, negativePole, positivePole, rubric, claimScores }].");
+    }
+    return `${lines.join("\n")}\n`;
+}