@agifyai/leadify-mcp 8.6.3 → 8.6.5

package/dist/tools/personas.js

@@ -1,1165 +1,174 @@
 import { z } from "zod";
 import { getClient } from "../client.js";
-import { LeadifyApiError, toolResult, toolError, handleToolError } from "../types.js";
-// ─── Shared sub-schemas ────────────────────────────────────────────────────
-// hotCriteria / warmCriteria / coldCriteria / disqualifiedCriteria
-// Accept either a free-form string OR a structured {criteria, examples, weight} object.
-const criteriaTier = z.union([
-    z.string(),
-    z
-        .object({
-        criteria: z.string().optional(),
-        examples: z.string().optional(),
-        weight: z.number().optional(),
-    })
-        .passthrough(),
-]);
-const lookalikeClient = z.object({
-    name: z.string().describe("Client/company name (required)."),
-    sector: z.string().optional(),
-    size: z.string().optional(),
-    segment: z.string().optional(),
-    comparison_criteria: z
-        .string()
-        .optional()
-        .describe("Why this client is a useful reference."),
-});
-const painPoint = z.object({
-    title: z.string().optional(),
-    description: z.string().optional(),
-});
-const cardAnalysisSection = z.object({
-    id: z.string().optional(),
-    labels: z
-        .record(z.string())
-        .optional()
-        .describe("Multilingual labels, keyed by language code (e.g. { fr, en })."),
-    instructions: z.string().optional(),
-});
-const signalTierRule = z.object({
-    signal_id: z.string().optional(),
-    tier: z.enum(["hot", "warm", "cold"]).optional(),
-});
-// Persona v2 owns entity-specific qualification contracts. Keep their nested
-// shape forward-compatible here: the Leadify API remains the authority that
-// validates the versioned Company/Person contracts, while the MCP must never
-// silently strip them before forwarding the wholesale upsert.
-const companyQualification = z
-    .record(z.unknown())
-    .describe("Versioned Company Persona qualification contract forwarded unchanged to Leadify.");
-const personQualification = z
+import { LeadifyApiError, handleToolError, toolResult } from "../types.js";
+/**
+ * PRD-1423 hard cutover: Persona business content is represented only by the
+ * versioned `personaContract`. These tools deliberately do not expose any
+ * historical Persona field or field-specific patch operation.
+ */
+const contractSchema = z
     .record(z.unknown())
-    .describe("Versioned Person Persona qualification contract forwarded unchanged to Leadify.");
-const extraPromptPhase = z.object({
-    scope: z.enum(["qualify", "outreach"]).optional(),
-    insertion_point: z
-        .enum(["prefix", "phase_1_5", "phase_2_extra", "suffix"])
-        .describe("Where in the prompt to inject this snippet."),
-    content: z.string().describe("Snippet content."),
-});
-// ICP strategy — mental map consumed verbatim by the outreach agent preflight.
-const icpStrategyShape = {
-    dealType: z.string().optional(),
-    dreamOutcome: z.string().optional(),
-    mainPains: z.array(z.string()).optional(),
-    keyObjections: z.array(z.string()).optional(),
-    decisionDrivers: z.array(z.string()).optional(),
-};
-export const CRM_SCHEMA_PACKS = [
-    "base_person",
-    "base_company",
-    "healthcare",
-    "medtech",
-    "recruitment_hr",
-    "community_creator",
-];
-const optimisticPersonaMutationShape = {
+    .describe("Complete versioned Persona contract. Leadify validates its exact schema.");
+const tenantScope = {
     organization_id: z
         .string()
         .trim()
         .min(1)
-        .describe("Required organization ID; no tenant is inferred."),
+        .describe("Required organization ID. No tenant is inferred."),
+};
+const optimisticScope = {
+    ...tenantScope,
     expected_updated_at: z
         .string()
         .datetime({ offset: true })
-        .describe("Exact Persona updatedAt returned by the read that this edit is based on. A stale value is rejected with 409."),
-};
-const SECTOR_BASE_COMPATIBILITY = {
-    healthcare: ["base_person", "base_company"],
-    medtech: ["base_person", "base_company"],
-    recruitment_hr: ["base_person", "base_company"],
-    community_creator: ["base_person", "base_company"],
+        .describe("Exact updatedAt obtained from a preceding read."),
 };
-export function crmSchemaPackSelectionError(packs, workflowMode) {
-    const unknown = [...new Set(packs.filter(pack => !CRM_SCHEMA_PACKS.includes(pack)))];
-    if (unknown.length > 0)
-        return `Unknown CRM Schema Pack: ${unknown.sort().join(", ")}. Call list_crm_schema_packs first.`;
-    const selected = [...new Set(packs)];
-    const bases = selected.filter(pack => pack === "base_person" || pack === "base_company");
-    const sectors = selected.filter(pack => pack !== "base_person" && pack !== "base_company");
-    if (bases.length !== 1 || sectors.length > 1 || selected.length !== packs.length) {
-        return "Select exactly one base CRM Schema Pack and at most one sector pack; duplicates are not allowed.";
-    }
-    const base = bases[0];
-    if (workflowMode !== undefined && workflowMode !== null) {
-        const expectedBase = workflowMode === "company_first" ? "base_company" : "base_person";
-        if (base !== expectedBase)
-            return `${base} is incompatible with workflow_mode=${workflowMode}; use ${expectedBase}.`;
+function canonicalPersona(persona) {
+    if (!persona.personaContract || typeof persona.personaContract !== "object") {
+        throw new Error("PERSONA_CONTRACT_REQUIRED: run the audited Persona migration before using this MCP.");
     }
-    const incompatibleSector = sectors.find(sector => !SECTOR_BASE_COMPATIBILITY[sector].includes(base));
-    return incompatibleSector
-        ? `${incompatibleSector} is incompatible with ${base}. Call list_crm_schema_packs for compatible combinations.`
-        : null;
-}
-// camelCase mapping for nested objects that the backend expects as-is.
-function mapLookalikeClient(c) {
-    const out = { name: c.name };
-    if (c.sector !== undefined)
-        out.sector = c.sector;
-    if (c.size !== undefined)
-        out.size = c.size;
-    if (c.segment !== undefined)
-        out.segment = c.segment;
-    if (c.comparison_criteria !== undefined)
-        out.comparisonCriteria = c.comparison_criteria;
-    return out;
-}
-function mapCardSection(s) {
-    const out = {};
-    if (s.id !== undefined)
-        out.id = s.id;
-    if (s.labels !== undefined)
-        out.labels = s.labels;
-    if (s.instructions !== undefined)
-        out.instructions = s.instructions;
-    return out;
-}
-function mapSignalTierRule(r) {
-    const out = {};
-    if (r.signal_id !== undefined)
-        out.signalId = r.signal_id;
-    if (r.tier !== undefined)
-        out.tier = r.tier;
-    return out;
-}
-function mapExtraPromptPhase(p) {
-    const out = {
-        insertionPoint: p.insertion_point,
-        content: p.content,
+    return {
+        id: persona.id,
+        name: persona.name,
+        verticalId: persona.verticalId,
+        updatedAt: persona.updatedAt,
+        revision: persona.revision ?? 0,
+        status: persona.status,
+        contract: persona.personaContract,
     };
-    if (p.scope !== undefined)
-        out.scope = p.scope;
-    return out;
-}
-/**
- * Tag a thrown error with which RMW step failed (read vs write) and surface
- * the inner status / response body. Patch tools have a 2-step flow (GET-then-
- * POST) and a bare "Persona not found" gives no clue which call broke.
- */
-class PersonaPatchError extends Error {
-    step;
-    path;
-    statusCode;
-    responseBody;
-    hint;
-    constructor(step, path, statusCode, responseBody, hint) {
-        const inner = typeof responseBody === "object" &&
-            responseBody !== null &&
-            "error" in responseBody
-            ? String(responseBody.error)
-            : statusCode != null
-                ? `HTTP ${statusCode}`
-                : "request failed";
-        super(`[step: ${step}] ${path} → ${inner}${hint ? ` — ${hint}` : ""}`);
-        this.step = step;
-        this.path = path;
-        this.statusCode = statusCode;
-        this.responseBody = responseBody;
-        this.hint = hint;
-        this.name = "PersonaPatchError";
-    }
 }
-/**
- * Read a persona for the RMW patch flow.
- *
- * Backend asymmetry (verified empirically + documented in
- * `agentic/trigger_agify` LeadifyCrmClient comments):
- *   - GET /api/persona/{id}      → strict `persona.organizationId === user.organizationId`
- *   - POST /api/persona (upsert) → permissive `canAccessOrg(user, ...)`
- *   - GET /api/persona  (list)   → permissive via `buildOrgFilter`
- *
- * For super-admin keys or cross-org access, GET-by-id 404s while POST-upsert
- * succeeds. Without a fallback, every patch tool 404s in those cases even
- * when the user can clearly write to the persona via upsert.
- *
- * Strategy: fast-path the direct GET; on 404, fall back to the permissive
- * list endpoint and find by id. Other errors propagate immediately.
- */
-async function fetchPersona(id, organizationId, client = getClient()) {
-    const directPath = `/api/persona/${encodeURIComponent(id)}`;
+async function fetchPersona(id, organizationId, client) {
     try {
-        const data = await client.get(directPath, new URLSearchParams({ organizationId }));
-        if (!data || typeof data !== "object") {
-            throw new PersonaPatchError("read", directPath, null, data, "Unexpected response shape (expected an object).");
+        const result = await client.get(`/api/persona/${encodeURIComponent(id)}`, new URLSearchParams({ organizationId }));
+        const record = (result?.persona ?? result);
+        if (!record || typeof record !== "object" || typeof record.id !== "string") {
+            throw new Error("PERSONA_NOT_FOUND_IN_TENANT");
         }
-        // GET-by-id returns the persona body directly; defensive about a future
-        // projected/wrapped shape.
-        const persona = data.persona;
-        return persona ?? data;
+        return record;
     }
-    catch (err) {
-        if (!(err instanceof LeadifyApiError) || err.statusCode !== 404) {
-            throw err;
+    catch (error) {
+        if (error instanceof LeadifyApiError) {
+            throw new Error(`PERSONA_READ_FAILED:${error.statusCode}`);
         }
-        // 404 on direct GET — fall through to list-based lookup.
-    }
-    // Tenant-scoped fallback keeps the same explicit organization boundary.
-    const listPath = "/api/persona";
-    let listed;
-    try {
-        listed = await client.get(listPath, new URLSearchParams({ organizationId }));
+        throw error;
     }
-    catch (err) {
-        if (err instanceof LeadifyApiError) {
-            throw new PersonaPatchError("lookup", listPath, err.statusCode, err.responseBody, "Direct GET 404'd; fallback list lookup also failed.");
-        }
-        throw err;
-    }
-    const personas = listed?.personas;
-    if (!Array.isArray(personas)) {
-        throw new PersonaPatchError("lookup", listPath, null, listed, "List response missing 'personas' array.");
-    }
-    const found = personas.find((p) => p.id === id);
-    if (!found) {
-        throw new PersonaPatchError("lookup", directPath, 404, { error: "Persona not found" }, `Persona id "${id}" is not in your accessible personas. Verify the id with list_personas. ` +
-            `Note: GET /api/persona/{id} uses strict org-equality and 404s for cross-org access — ` +
-            `super-admin keys may need to operate via lead-group context. If list_personas returns this ` +
-            `id, the backend GET handler is the bug; tracker: align it with upsert's canAccessOrg semantics.`);
-    }
-    return found;
 }
-async function postPersonaUpdate(persona, fieldsToWrite, organizationId, expectedUpdatedAt, client = getClient()) {
-    const path = "/api/persona";
-    if (typeof persona.verticalId !== "string" || persona.verticalId.length === 0) {
-        throw new PersonaPatchError("write", path, 409, { error: "PERSONA_VERTICAL_REQUIRED" }, "Historical global/orphaned Personas cannot be edited.");
-    }
-    if (typeof persona.updatedAt !== "string" ||
-        new Date(persona.updatedAt).toISOString() !== new Date(expectedUpdatedAt).toISOString()) {
-        throw new PersonaPatchError("write", path, 409, {
-            error: "CONTEXT_ENTITY_UPDATE_CONFLICT",
-            expectedUpdatedAt,
-            actualUpdatedAt: persona.updatedAt,
-        }, "Re-read the Persona and reapply the intended patch.");
+function setContractPath(current, path, value) {
+    const parts = path.split(".").filter(Boolean);
+    if (parts.length === 0 ||
+        parts.some((part) => part === "__proto__" || part === "constructor" || part === "prototype")) {
+        throw new Error("CONTRACT_PATH_INVALID");
     }
-    try {
-        return await client.post(path, {
-            id: persona.id,
-            name: persona.name,
-            organizationId,
-            verticalId: persona.verticalId,
-            expectedUpdatedAt,
-            ...fieldsToWrite,
-        });
-    }
-    catch (err) {
-        if (err instanceof LeadifyApiError) {
-            throw new PersonaPatchError("write", path, err.statusCode, err.responseBody, `Fields written: ${Object.keys(fieldsToWrite).join(", ") || "(none beyond id+name)"}`);
-        }
-        throw err;
+    const next = structuredClone(current);
+    let cursor = next;
+    for (const part of parts.slice(0, -1)) {
+        const child = cursor[part];
+        if (!child || typeof child !== "object" || Array.isArray(child))
+            cursor[part] = {};
+        cursor = cursor[part];
     }
+    cursor[parts.at(-1)] = value;
+    return next;
 }
-function asObject(v) {
-    return v && typeof v === "object" && !Array.isArray(v)
-        ? v
-        : {};
-}
-function asArray(v) {
-    return Array.isArray(v) ? v : [];
-}
-/**
- * Error handler for persona tools. Serializes PersonaPatchError into
- * structured details (step, path, statusCode, responseBody, hint) so the
- * caller can see exactly which sub-call failed and why — useful for the
- * 12 patch tools' read-then-write flow. For other errors (LeadifyApiError
- * from the wholesale tools, plain Error), falls through to handleToolError.
- */
-function handlePersonaToolError(error) {
-    if (error instanceof PersonaPatchError) {
-        return toolError(error.message, {
-            step: error.step,
-            path: error.path,
-            statusCode: error.statusCode,
-            response: error.responseBody,
-            hint: error.hint,
-        });
+async function replaceContract(input) {
+    const persona = await fetchPersona(input.id, input.organizationId, input.client);
+    if (!persona.verticalId)
+        throw new Error("PERSONA_VERTICAL_REQUIRED");
+    if (persona.updatedAt !== input.expectedUpdatedAt) {
+        throw new Error("CONTEXT_ENTITY_UPDATE_CONFLICT");
     }
-    return handleToolError(error);
-}
-// ─── Tool registrations ────────────────────────────────────────────────────
-export function registerPersonaTools(server, client) {
-    // ════════════════════════════════════════════════════════════════════════
-    // ESCAPE HATCH — wholesale upsert
-    // ════════════════════════════════════════════════════════════════════════
-    // ── upsert_persona ─────────────────────────────────────────────────────
-    server.tool("upsert_persona", "WHOLESALE create-or-update for a persona. Use to CREATE (no id) or to fully " +
-        "rewrite a persona. For partial edits, ALWAYS prefer the granular " +
-        "update_persona_* tools — they do safe read-modify-write merges and avoid " +
-        "wiping JSON columns you didn't intend to touch (each JSON column passed in " +
-        "this tool is replaced wholesale, so omitted sub-keys are LOST). PRD-1415 requires " +
-        "one explicit organization and one explicit Vertical; global/orphaned Personas are rejected.", {
-        // core
-        id: z
-            .string()
-            .optional()
-            .describe("Persona ID to update an existing persona. Omit to create a new one."),
-        expected_updated_at: z
-            .string()
-            .datetime({ offset: true })
-            .optional()
-            .describe("Required on update: exact updatedAt from the Persona read this rewrite is based on. Omit on create."),
-        name: z.string().describe("Persona name (required)."),
-        organization_id: z
-            .string()
-            .trim()
-            .min(1)
-            .describe("Required target organization ID. There is no implicit tenant and no global Persona."),
-        vertical_id: z
-            .string()
-            .trim()
-            .min(1)
-            .describe("Required Vertical ID in the same organization."),
-        description: z.string().optional().describe("Detailed persona description."),
-        // Persona v2 qualification contracts
-        company_qualification: companyQualification.optional(),
-        person_qualification: personQualification.optional(),
-        // targeting
-        target_profile: z
-            .record(z.unknown())
-            .optional()
-            .describe("Target criteria. Common keys: job_titles, specialties, seniority_min, decision_maker, " +
-            "buying_power, target_company_types, min_company_size, interest_topics."),
-        disqualification_criteria: z
-            .record(z.unknown())
-            .optional()
-            .describe("Exclusion rules. Common keys: reasons (array of strings)."),
-        active_tools: z
-            .array(z.string())
-            .optional()
-            .describe("Active monitoring/sourcing tools for this persona."),
-        // scoring tiers
-        hot_criteria: criteriaTier
-            .optional()
-            .describe("Criteria that make a lead 'hot'. Either a free-form string or {criteria, examples, weight}."),
-        warm_criteria: criteriaTier.optional().describe("Criteria that make a lead 'warm'."),
-        cold_criteria: criteriaTier.optional().describe("Criteria that make a lead 'cold'."),
-        disqualified_criteria: criteriaTier
-            .optional()
-            .describe("Criteria that disqualify a lead entirely."),
-        // references + pains
-        lookalike_clients: z
-            .array(lookalikeClient)
-            .optional()
-            .describe("2–3 official lookalike clients. Each must have at least a name."),
-        pain_points: z
-            .array(painPoint)
-            .optional()
-            .describe("Structured business pain points ({title, description})."),
-        // ICP strategy — mental map consumed verbatim by the outreach agent preflight
-        icp_strategy: z
-            .object(icpStrategyShape)
-            .passthrough()
-            .optional()
-            .describe("ICP strategy. Mental map for the outreach agent: {dealType, dreamOutcome, mainPains[], keyObjections[], decisionDrivers[]}."),
-        // behaviour flags
-        strict_match: z
-            .boolean()
-            .optional()
-            .describe("If true, reject non-perfectly-aligned leads."),
-        workflow_mode: z
-            .enum(["company_first", "person_first"])
-            .nullable()
-            .optional()
-            .describe("Qualification mode."),
-        schema_packs: z
-            .array(z.enum(CRM_SCHEMA_PACKS))
-            .optional()
-            .describe("Canonical CRM Schema Packs. REQUIRED on create: exactly one base pack " +
-            "(base_person for person_first or base_company for company_first) and at most one " +
-            "compatible sector pack. Call list_crm_schema_packs before selecting values."),
-        output_language: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("AI output language code (fr, en, de, …)."),
-        enable_signals: z
-            .boolean()
-            .optional()
-            .describe("Enable business signal detection for this persona."),
-        // prompt engineering
-        normalization_rules: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Free-form markdown injected into the ICP prompt."),
-        decision_maker_keywords: z
-            .record(z.array(z.string()))
-            .optional()
-            .describe("Terms implying decision power, keyed by language code. Example: { fr: ['Directeur', 'Chef de pôle'] }."),
-        card_analysis_sections: z
-            .object({
-            required: z.array(cardAnalysisSection).optional(),
-            optional: z.array(cardAnalysisSection).optional(),
-        })
-            .optional()
-            .describe("Analysis blocks separated into 'required' and 'optional'."),
-        signal_guidance: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Free-form markdown injected verbatim into signal prompt."),
-        signal_tier_rules: z
-            .object({
-            rules: z.array(signalTierRule).optional(),
-        })
-            .optional()
-            .describe("Rules mapping signal → tier (hot/warm/cold)."),
-        context: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Free-form markdown appended to the ICP prompt."),
-        extra_prompt_phases: z
-            .array(extraPromptPhase)
-            .optional()
-            .describe("Snippets inserted at named points. scope: 'qualify' | 'outreach'; insertion_point: 'prefix' | 'phase_1_5' | 'phase_2_extra' | 'suffix'."),
-    }, async (params) => {
-        try {
-            if (!params.organization_id) {
-                throw new Error("organization_id is required; no implicit tenant or global Persona is allowed.");
-            }
-            if (!params.vertical_id) {
-                throw new Error("vertical_id is required; an orphan Persona cannot be created or updated.");
-            }
-            if (params.id !== undefined && params.expected_updated_at === undefined) {
-                throw new Error("expected_updated_at is required when updating a Persona. Re-read it first; stale writes are rejected with 409.");
-            }
-            if (params.id === undefined && params.schema_packs === undefined) {
-                throw new Error("schema_packs is required when creating a Persona. Call list_crm_schema_packs, then select exactly one base pack and at most one compatible sector pack.");
-            }
-            if (params.schema_packs !== undefined) {
-                const selectionError = crmSchemaPackSelectionError(params.schema_packs, params.workflow_mode ?? (params.id === undefined ? "person_first" : undefined));
-                if (selectionError)
-                    throw new Error(selectionError);
-            }
-            const body = {
-                name: params.name,
-                organizationId: params.organization_id,
-                verticalId: params.vertical_id,
-            };
-            if (params.id !== undefined)
-                body.id = params.id;
-            if (params.expected_updated_at !== undefined)
-                body.expectedUpdatedAt = params.expected_updated_at;
-            if (params.description !== undefined)
-                body.description = params.description;
-            if (params.company_qualification !== undefined)
-                body.companyQualification = params.company_qualification;
-            if (params.person_qualification !== undefined)
-                body.personQualification = params.person_qualification;
-            if (params.target_profile !== undefined)
-                body.targetProfile = params.target_profile;
-            if (params.disqualification_criteria !== undefined)
-                body.disqualificationCriteria = params.disqualification_criteria;
-            if (params.active_tools !== undefined)
-                body.activeTools = params.active_tools;
-            if (params.hot_criteria !== undefined)
-                body.hotCriteria = params.hot_criteria;
-            if (params.warm_criteria !== undefined)
-                body.warmCriteria = params.warm_criteria;
-            if (params.cold_criteria !== undefined)
-                body.coldCriteria = params.cold_criteria;
-            if (params.disqualified_criteria !== undefined)
-                body.disqualifiedCriteria = params.disqualified_criteria;
-            if (params.lookalike_clients !== undefined)
-                body.lookalikeClients = params.lookalike_clients.map(mapLookalikeClient);
-            if (params.pain_points !== undefined)
-                body.painPoints = params.pain_points;
-            if (params.icp_strategy !== undefined)
-                body.icpStrategy = params.icp_strategy;
-            if (params.strict_match !== undefined)
-                body.strictMatch = params.strict_match;
-            if (params.workflow_mode !== undefined)
-                body.workflowMode = params.workflow_mode;
-            if (params.schema_packs !== undefined)
-                body.schemaPacks = params.schema_packs;
-            if (params.output_language !== undefined)
-                body.outputLanguage = params.output_language;
-            if (params.enable_signals !== undefined)
-                body.enableSignals = params.enable_signals;
-            if (params.normalization_rules !== undefined)
-                body.normalizationRules = params.normalization_rules;
-            if (params.decision_maker_keywords !== undefined)
-                body.decisionMakerKeywords = params.decision_maker_keywords;
-            if (params.card_analysis_sections !== undefined) {
-                const cas = {};
-                if (params.card_analysis_sections.required !== undefined)
-                    cas.required = params.card_analysis_sections.required.map(mapCardSection);
-                if (params.card_analysis_sections.optional !== undefined)
-                    cas.optional = params.card_analysis_sections.optional.map(mapCardSection);
-                body.cardAnalysisSections = cas;
-            }
-            if (params.signal_guidance !== undefined)
-                body.signalGuidance = params.signal_guidance;
-            if (params.signal_tier_rules !== undefined) {
-                body.signalTierRules = {
-                    rules: (params.signal_tier_rules.rules ?? []).map(mapSignalTierRule),
-                };
-            }
-            if (params.context !== undefined)
-                body.context = params.context;
-            if (params.extra_prompt_phases !== undefined)
-                body.extraPromptPhases =
-                    params.extra_prompt_phases.map(mapExtraPromptPhase);
-            const data = await (client ?? getClient()).post("/api/persona", body);
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── update_persona_schema_packs ───────────────────────────────────────
-    server.tool("update_persona_schema_packs", "Safely replace one Persona's CRM Schema Packs without rewriting unrelated Persona sections. " +
-        "Reads the current Persona, validates exactly one workflow-compatible base and at most one " +
-        "compatible sector pack, then writes schemaPacks through the canonical Persona endpoint. " +
-        "The response includes the persisted Persona and readiness proofs for every linked group.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID to update."),
-        schema_packs: z
-            .array(z.enum(CRM_SCHEMA_PACKS))
-            .min(1)
-            .describe("Complete replacement selection. Call list_crm_schema_packs first."),
-    }, async ({ organization_id, expected_updated_at, id, schema_packs }) => {
-        try {
-            const api = client ?? getClient();
-            const persona = await fetchPersona(id, organization_id, api);
-            const workflowMode = persona.workflowMode === "company_first" ? "company_first" : "person_first";
-            const selectionError = crmSchemaPackSelectionError(schema_packs, workflowMode);
-            if (selectionError)
-                throw new Error(selectionError);
-            const data = await postPersonaUpdate(persona, { schemaPacks: schema_packs }, organization_id, expected_updated_at, api);
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── get_persona ────────────────────────────────────────────────────────
-    server.tool("get_persona", "Retrieve a single persona by ID, including all lead groups it's assigned to. " +
-        "SILO: the outreach trio (outreachTemplates, outreachSignalRouting, outreachFields) " +
-        "is STRIPPED by default to keep the response focused on the persona's targeting & " +
-        "qualification concerns (~37k chars instead of ~63k). Pass include_outreach=true to " +
-        "get the full payload — but for outreach-only reads prefer get_outreach_templates " +
-        "(a much smaller, dedicated read).", {
-        organization_id: z
-            .string()
-            .trim()
-            .min(1)
-            .describe("Required organization ID; no tenant is inferred."),
-        id: z.string().describe("Persona ID."),
-        include_outreach: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("If true, keep the outreach trio in the response (outreachTemplates, " +
-            "outreachSignalRouting, outreachFields). Default false (SILO: outreach lives " +
-            "in its own tool)."),
-    }, async ({ organization_id, id, include_outreach }) => {
-        try {
-            const data = await (client ?? getClient()).get(`/api/persona/${encodeURIComponent(id)}`, new URLSearchParams({ organizationId: organization_id }));
-            // SILO defense in depth: strip the outreach trio locally unless the
-            // caller explicitly opted in. Outreach data belongs to the dedicated
-            // outreach tools — never mix it with the persona read by default.
-            if (!include_outreach && data && typeof data === "object") {
-                const wrapper = data;
-                if (wrapper && typeof wrapper === "object") {
-                    delete wrapper.outreachTemplates;
-                    delete wrapper.outreachSignalRouting;
-                    delete wrapper.outreachFields;
-                }
-                // The persona can also be wrapped under {persona: {...}} depending
-                // on the API path. Strip there too.
-                const inner = wrapper.persona;
-                if (inner && typeof inner === "object") {
-                    delete inner.outreachTemplates;
-                    delete inner.outreachSignalRouting;
-                    delete inner.outreachFields;
-                }
-            }
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── get_outreach_templates ─────────────────────────────────────────────
-    server.tool("get_outreach_templates", "Read the persona's outreach trio ONLY (outreachSignalRouting, outreachTemplates, " +
-        "outreachFields). SILO: this is the dedicated read for outreach data — never call " +
-        "get_persona with include_outreach=true for routine reads. Returns a small payload " +
-        "regardless of persona size, so it's safe to call mid-session without saturating " +
-        "the LLM context. " +
-        "Resolves the persona from the lead group (lead_group_id → personaId → persona), " +
-        "then projects the trio. If the lead group has no persona, returns an error.", {
-        lead_group_id: z
-            .string()
-            .describe("Lead group ID. The persona is resolved server-side from the group's personaId."),
-    }, async ({ lead_group_id }) => {
-        try {
-            // Step 1: resolve the persona assigned to this lead group (slim view).
-            // We only need the persona's id from here — we re-fetch the full
-            // persona below to grab the outreach trio.
-            const groupPersona = (await (client ?? getClient()).get(`/api/lead-group/${encodeURIComponent(lead_group_id)}/persona`));
-            const personaId = groupPersona?.persona?.id;
-            const organizationId = groupPersona?.organizationId;
-            if (!personaId || !organizationId) {
-                return toolError(`No usable tenant-scoped Persona is assigned to lead group "${lead_group_id}". ` +
-                    `Assign one ACTIVE Persona linked to a Vertical before reading outreach templates.`);
-            }
-            // Step 2: fetch the full persona so we can project the trio.
-            const full = (await (client ?? getClient()).get(`/api/persona/${encodeURIComponent(personaId)}`, new URLSearchParams({ organizationId })));
-            // The API may return either a bare persona or {persona: {...}}.
-            const persona = full.persona ?? full;
-            const trio = {
-                outreachSignalRouting: persona.outreachSignalRouting ?? null,
-                outreachTemplates: persona.outreachTemplates ?? [],
-                outreachFields: persona.outreachFields ?? [],
-            };
-            return toolResult({
-                personaId,
-                ...trio,
-                _note: "SILO projection. To edit, use update_persona_outreach_template or " +
-                    "update_persona_outreach_signal_routing. Do NOT use upsert_persona for outreach " +
-                    "fields (SILO rejection).",
-            });
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── change_persona_status ─────────────────────────────────────────────
-    server.tool("change_persona_status", "Change one tenant-scoped Persona between DRAFT, ACTIVE, and ARCHIVED. " +
-        "The exact expected_updated_at from the caller's read is mandatory. Activation requires an ACTIVE Vertical " +
-        "plus qualification-ready content; archive is blocked while durable references remain; ARCHIVED can only return to DRAFT.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().min(1).describe("Persona ID."),
-        status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]),
-    }, async ({ organization_id, expected_updated_at, id, status }) => {
-        try {
-            const query = new URLSearchParams({ organizationId: organization_id });
-            const data = await (client ?? getClient()).post(`/api/persona/${encodeURIComponent(id)}/status?${query.toString()}`, { expectedUpdatedAt: expected_updated_at, status });
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
+    return input.client.post("/api/persona", {
+        id: persona.id,
+        name: persona.name,
+        organizationId: input.organizationId,
+        verticalId: persona.verticalId,
+        expectedUpdatedAt: input.expectedUpdatedAt,
+        personaContract: input.contract,
     });
-    // ── list_personas ──────────────────────────────────────────────────────
-    server.tool("list_personas", "List all usable Persona records in one explicit organization. Historical global/orphaned " +
-        "Personas are excluded and available only through the reviewed migration inventory. Use this to discover persona IDs before calling " +
-        "get_persona, upsert_persona (for updates), or assigning a persona to a lead group. " +
-        "Returns a COMPACT view by default (id, name, organizationId, truncated description) " +
-        "to avoid blowing up context — full persona objects can be heavy (~10k chars each). " +
-        "Pass verbose=true to get the full objects, or call get_persona(id) for a single full persona.", {
-        organization_id: z
-            .string()
-            .trim()
-            .min(1)
-            .describe("Required organization ID. The literal string 'null' and implicit tenant selection are forbidden."),
-        verbose: z
-            .boolean()
-            .optional()
-            .describe("If true, return full persona objects with every field. Defaults to false (compact view: id, name, organizationId, short description)."),
-    }, async ({ organization_id, verbose }) => {
+}
+export function registerPersonaTools(server, injectedClient) {
+    const client = injectedClient ?? getClient();
+    server.tool("list_persona_contracts", "List canonical Persona contract headers for one explicit organization.", tenantScope, async ({ organization_id }) => {
         try {
-            const params = new URLSearchParams({ organizationId: organization_id });
-            const data = await (client ?? getClient()).get("/api/persona", params);
-            if (verbose)
-                return toolResult(data);
-            // Project to compact view: id, name, organizationId, truncated description.
-            const personas = data && typeof data === "object" && "personas" in data
-                ? data.personas
-                : null;
+            const response = await client.get("/api/persona", new URLSearchParams({ organizationId: organization_id }));
+            const personas = response.personas;
             if (!Array.isArray(personas))
-                return toolResult(data); // unexpected shape → fall through
-            const DESC_MAX = 200;
-            const compact = personas.map((p) => {
-                const obj = p;
-                const desc = typeof obj.description === "string" ? obj.description : undefined;
-                return {
-                    id: obj.id,
-                    name: obj.name,
-                    organizationId: obj.organizationId,
-                    verticalId: obj.verticalId,
-                    status: obj.status,
-                    ...(desc !== undefined && {
-                        description: desc.length > DESC_MAX ? `${desc.slice(0, DESC_MAX)}…` : desc,
-                    }),
-                };
-            });
-            return toolResult({
-                personas: compact,
-                count: compact.length,
-                _note: "Compact view. Call get_persona(id) for full details, or list_personas with verbose=true.",
-            });
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ════════════════════════════════════════════════════════════════════════
-    // GRANULAR PATCH TOOLS — read-modify-write, scoped to one section each
-    // ════════════════════════════════════════════════════════════════════════
-    // ── update_persona_identity ────────────────────────────────────────────
-    server.tool("update_persona_identity", "Patch top-level scalar fields of a persona (name, description, " +
-        "output_language, workflow_mode, strict_match, enable_signals). " +
-        "Pass only the fields you want to change. Other persona sections are untouched.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        name: z.string().min(1).optional().describe("New persona name."),
-        description: z.string().nullable().optional().describe("Detailed description."),
-        output_language: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Output language code (fr, en, de, …)."),
-        workflow_mode: z
-            .enum(["company_first", "person_first"])
-            .nullable()
-            .optional()
-            .describe("Qualification mode."),
-        strict_match: z
-            .boolean()
-            .optional()
-            .describe("If true, reject non-perfectly-aligned leads."),
-        enable_signals: z
-            .boolean()
-            .optional()
-            .describe("Enable business signal detection for this persona."),
-    }, async ({ organization_id, expected_updated_at, id, name, description, output_language, workflow_mode, strict_match, enable_signals, }) => {
-        try {
-            if (name === undefined &&
-                description === undefined &&
-                output_language === undefined &&
-                workflow_mode === undefined &&
-                strict_match === undefined &&
-                enable_signals === undefined) {
-                return toolError("Provide at least one field to update.");
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const body = {};
-            if (description !== undefined)
-                body.description = description;
-            if (output_language !== undefined)
-                body.outputLanguage = output_language;
-            if (workflow_mode !== undefined)
-                body.workflowMode = workflow_mode;
-            if (strict_match !== undefined)
-                body.strictMatch = strict_match;
-            if (enable_signals !== undefined)
-                body.enableSignals = enable_signals;
-            const data = await postPersonaUpdate({ ...current, name: name ?? current.name }, body, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── update_persona_target_profile ──────────────────────────────────────
-    server.tool("update_persona_target_profile", "Patch the targetProfile JSON column. Reads current targetProfile, shallow-merges " +
-        "the keys you pass, optionally removes specified keys, then writes back. Common " +
-        "keys: job_titles, specialties, seniority_min, decision_maker, buying_power, " +
-        "target_company_types, min_company_size, interest_topics. Other targetProfile " +
-        "keys remain intact.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        patch: z
-            .record(z.unknown())
-            .optional()
-            .describe("Object whose keys are merged into the existing targetProfile (shallow). Keys you don't pass remain intact."),
-        remove_keys: z
-            .array(z.string())
-            .optional()
-            .describe("Keys to delete from targetProfile."),
-    }, async ({ organization_id, expected_updated_at, id, patch, remove_keys }) => {
-        try {
-            if ((patch === undefined || Object.keys(patch).length === 0) &&
-                (remove_keys === undefined || remove_keys.length === 0)) {
-                return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const next = { ...asObject(current.targetProfile), ...(patch ?? {}) };
-            for (const k of remove_keys ?? [])
-                delete next[k];
-            const data = await postPersonaUpdate(current, { targetProfile: next }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── update_persona_disqualification ────────────────────────────────────
-    server.tool("update_persona_disqualification", "Patch the disqualificationCriteria JSON column (shallow merge). Common key: " +
-        "reasons (array of strings). Other keys remain intact.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        patch: z
-            .record(z.unknown())
-            .optional()
-            .describe("Object whose keys are merged into existing disqualificationCriteria (shallow)."),
-        remove_keys: z
-            .array(z.string())
-            .optional()
-            .describe("Keys to delete from disqualificationCriteria."),
-    }, async ({ organization_id, expected_updated_at, id, patch, remove_keys }) => {
-        try {
-            if ((patch === undefined || Object.keys(patch).length === 0) &&
-                (remove_keys === undefined || remove_keys.length === 0)) {
-                return toolError("Provide at least one of: patch (non-empty), remove_keys (non-empty).");
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const next = { ...asObject(current.disqualificationCriteria), ...(patch ?? {}) };
-            for (const k of remove_keys ?? [])
-                delete next[k];
-            const data = await postPersonaUpdate(current, { disqualificationCriteria: next }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
-        }
-        catch (error) {
-            return handlePersonaToolError(error);
-        }
-    });
-    // ── update_persona_active_tools ────────────────────────────────────────
-    server.tool("update_persona_active_tools", "Replace the activeTools list wholesale, OR add/remove specific entries while " +
-        "preserving the rest. Use 'tools' to fully replace; use 'add' / 'remove' for " +
-        "incremental edits (deduped).", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        tools: z
-            .array(z.string())
-            .optional()
-            .describe("Full replacement list. Mutually exclusive with add/remove."),
-        add: z
-            .array(z.string())
-            .optional()
-            .describe("Tools to add (no-op if already present)."),
-        remove: z
-            .array(z.string())
-            .optional()
-            .describe("Tools to remove (no-op if absent)."),
-    }, async ({ organization_id, expected_updated_at, id, tools, add, remove }) => {
-        try {
-            if (tools === undefined && add === undefined && remove === undefined) {
-                return toolError("Provide one of: tools, add, remove.");
-            }
-            if (tools !== undefined && (add !== undefined || remove !== undefined)) {
-                return toolError("'tools' is mutually exclusive with 'add' / 'remove'.");
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            let next;
-            if (tools !== undefined) {
-                next = tools;
-            }
-            else {
-                const set = new Set(asArray(current.activeTools));
-                for (const t of add ?? [])
-                    set.add(t);
-                for (const t of remove ?? [])
-                    set.delete(t);
-                next = Array.from(set);
-            }
-            const data = await postPersonaUpdate(current, { activeTools: next }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
+                throw new Error("PERSONA_LIST_INVALID_RESPONSE");
+            return toolResult(personas.map(canonicalPersona));
         }
         catch (error) {
-            return handlePersonaToolError(error);
+            return handleToolError(error);
         }
     });
-    // ── update_persona_tier_criteria ───────────────────────────────────────
-    server.tool("update_persona_tier_criteria", "Patch a single qualification tier (hot, warm, cold, or disqualified) without " +
-        "touching the other three. Each tier accepts either a free-form string or " +
-        "{criteria, examples, weight}. When passing a structured patch, sub-fields are " +
-        "merged into the existing structured tier (if any) — pass only what you want " +
-        "to change. Passing a string REPLACES the tier entirely.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        tier: z
-            .enum(["hot", "warm", "cold", "disqualified"])
-            .describe("Which tier to patch."),
-        criteria: z
-            .union([
-            z.string(),
-            z
-                .object({
-                criteria: z.string().optional(),
-                examples: z.string().optional(),
-                weight: z.number().optional(),
-            })
-                .passthrough(),
-        ])
-            .describe("New tier value. String replaces wholesale; object is merged."),
-    }, async ({ organization_id, expected_updated_at, id, tier, criteria }) => {
+    server.tool("get_persona_contract", "Read one canonical Persona contract before editing it.", { ...tenantScope, id: z.string().min(1) }, async ({ organization_id, id }) => {
         try {
-            const fieldMap = {
-                hot: "hotCriteria",
-                warm: "warmCriteria",
-                cold: "coldCriteria",
-                disqualified: "disqualifiedCriteria",
-            };
-            const field = fieldMap[tier];
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            let nextValue;
-            if (typeof criteria === "string") {
-                nextValue = criteria;
-            }
-            else {
-                const existing = current[field];
-                const base = existing && typeof existing === "object" && !Array.isArray(existing)
-                    ? existing
-                    : {};
-                nextValue = { ...base, ...criteria };
-            }
-            const data = await postPersonaUpdate(current, { [field]: nextValue }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
+            return toolResult(canonicalPersona(await fetchPersona(id, organization_id, client)));
         }
         catch (error) {
-            return handlePersonaToolError(error);
+            return handleToolError(error);
         }
     });
-    // ── update_persona_lookalike_client ────────────────────────────────────
-    server.tool("update_persona_lookalike_client", "Add, replace, or remove a single lookalike client without re-sending the whole " +
-        "list. Lookups are by client `name` (case-sensitive exact match). Reads the " +
-        "current lookalikeClients array, mutates the matched entry, writes the full " +
-        "list back. Use this instead of upsert_persona to avoid wiping the others.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        action: z
-            .enum(["add", "replace", "remove"])
-            .describe("add = append (fails if name already exists); replace = overwrite by name; remove = delete by name."),
-        name: z
-            .string()
-            .optional()
-            .describe("Lookup key for replace/remove. Required for those actions. For 'add', the name is taken from the client payload."),
-        client: lookalikeClient
-            .optional()
-            .describe("Client payload. Required for 'add' and 'replace'. Schema: {name, sector?, size?, segment?, comparison_criteria?}."),
-    }, async ({ organization_id, expected_updated_at, id, action, name, client: lookalikeClientInput }) => {
+    server.tool("create_persona_contract", "Create a Persona from one complete canonical contract. Historical Persona fields are not accepted.", {
+        ...tenantScope,
+        vertical_id: z.string().trim().min(1),
+        name: z.string().trim().min(1),
+        description: z.string().optional(),
+        contract: contractSchema,
+    }, async ({ organization_id, vertical_id, name, description, contract }) => {
         try {
-            if ((action === "add" || action === "replace") && !lookalikeClientInput) {
-                return toolError(`client is required for action '${action}'.`);
-            }
-            if ((action === "replace" || action === "remove") && !name) {
-                return toolError(`name is required for action '${action}'.`);
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const list = asArray(current.lookalikeClients).map((c) => ({ ...c }));
-            if (action === "add") {
-                const newName = lookalikeClientInput.name;
-                if (list.some((c) => c.name === newName)) {
-                    return toolError(`A lookalike client with name "${newName}" already exists. Use action 'replace' instead.`);
-                }
-                list.push(mapLookalikeClient(lookalikeClientInput));
-            }
-            else if (action === "replace") {
-                const idx = list.findIndex((c) => c.name === name);
-                if (idx === -1) {
-                    return toolError(`No lookalike client found with name "${name}".`);
-                }
-                list[idx] = mapLookalikeClient(lookalikeClientInput);
-            }
-            else {
-                const before = list.length;
-                const filtered = list.filter((c) => c.name !== name);
-                if (filtered.length === before) {
-                    return toolError(`No lookalike client found with name "${name}".`);
-                }
-                list.length = 0;
-                list.push(...filtered);
-            }
-            const data = await postPersonaUpdate(current, { lookalikeClients: list }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
+            return toolResult(await client.post("/api/persona", {
+                organizationId: organization_id,
+                verticalId: vertical_id,
+                name,
+                ...(description !== undefined ? { description } : {}),
+                personaContract: contract,
+            }));
         }
         catch (error) {
-            return handlePersonaToolError(error);
+            return handleToolError(error);
         }
     });
-    // ── update_persona_pain_point ──────────────────────────────────────────
-    server.tool("update_persona_pain_point", "Add, replace, or remove a single pain point without re-sending the whole list. " +
-        "Pain points have no stable id — entries are addressed by zero-based index. " +
-        "Beware: indices shift after a remove, so re-fetch before chaining edits.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        action: z
-            .enum(["add", "replace", "remove"])
-            .describe("add = append; replace = overwrite at index; remove = delete at index."),
-        index: z
-            .number()
-            .int()
-            .nonnegative()
-            .optional()
-            .describe("Zero-based index. Required for 'replace' and 'remove'."),
-        pain: painPoint
-            .optional()
-            .describe("Pain payload {title?, description?}. Required for 'add' and 'replace'."),
-    }, async ({ organization_id, expected_updated_at, id, action, index, pain }) => {
+    server.tool("replace_persona_contract", "Replace the complete canonical contract using optimistic concurrency.", { ...optimisticScope, id: z.string().min(1), contract: contractSchema }, async ({ organization_id, id, expected_updated_at, contract }) => {
         try {
-            if ((action === "add" || action === "replace") && !pain) {
-                return toolError(`pain is required for action '${action}'.`);
-            }
-            if ((action === "replace" || action === "remove") && index === undefined) {
-                return toolError(`index is required for action '${action}'.`);
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const list = asArray(current.painPoints).map((p) => ({ ...p }));
-            if (action === "add") {
-                list.push(pain);
-            }
-            else if (action === "replace") {
-                if (index < 0 || index >= list.length) {
-                    return toolError(`Index ${index} out of bounds (list has ${list.length} entries).`);
-                }
-                list[index] = pain;
-            }
-            else {
-                if (index < 0 || index >= list.length) {
-                    return toolError(`Index ${index} out of bounds (list has ${list.length} entries).`);
-                }
-                list.splice(index, 1);
-            }
-            const data = await postPersonaUpdate(current, { painPoints: list }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
+            return toolResult(await replaceContract({
+                organizationId: organization_id,
+                id,
+                expectedUpdatedAt: expected_updated_at,
+                contract,
+                client,
+            }));
         }
         catch (error) {
-            return handlePersonaToolError(error);
+            return handleToolError(error);
         }
     });
-    // ── update_persona_prompt_engineering ──────────────────────────────────
-    server.tool("update_persona_prompt_engineering", "Patch free-form markdown prompt fields (normalization_rules, signal_guidance, " +
-        "tone_instructions, context). Each is a separate scalar JSON column — passing " +
-        "one replaces it (pass null to clear). Other prompt fields and persona sections " +
-        "remain intact.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        normalization_rules: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Markdown injected into the ICP prompt. Null clears it."),
-        signal_guidance: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Markdown injected into the signal prompt. Null clears it."),
-        tone_instructions: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Markdown for voice / tone guidance. Null clears it."),
-        context: z
-            .string()
-            .nullable()
-            .optional()
-            .describe("Markdown appended to the ICP prompt. Null clears it."),
-    }, async ({ organization_id, expected_updated_at, id, normalization_rules, signal_guidance, tone_instructions, context, }) => {
+    server.tool("patch_persona_contract", "Change one canonical contract path using optimistic concurrency. Removing a field is forbidden because the contract is strict and complete.", {
+        ...optimisticScope,
+        id: z.string().min(1),
+        path: z.string().trim().min(1),
+        value: z.unknown(),
+    }, async ({ organization_id, id, expected_updated_at, path, value }) => {
         try {
-            if (normalization_rules === undefined &&
-                signal_guidance === undefined &&
-                tone_instructions === undefined &&
-                context === undefined) {
-                return toolError("Provide at least one field to update.");
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const body = {};
-            if (normalization_rules !== undefined)
-                body.normalizationRules = normalization_rules;
-            if (signal_guidance !== undefined)
-                body.signalGuidance = signal_guidance;
-            if (tone_instructions !== undefined)
-                body.toneInstructions = tone_instructions;
-            if (context !== undefined)
-                body.context = context;
-            const data = await postPersonaUpdate(current, body, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
+            const persona = await fetchPersona(id, organization_id, client);
+            const contract = canonicalPersona(persona).contract;
+            return toolResult(await replaceContract({
+                organizationId: organization_id,
+                id,
+                expectedUpdatedAt: expected_updated_at,
+                contract: setContractPath(contract, path, value),
+                client,
+            }));
         }
         catch (error) {
-            return handlePersonaToolError(error);
+            return handleToolError(error);
         }
     });
-    // ── update_persona_icp_strategy ────────────────────────────────────────
-    server.tool("update_persona_icp_strategy", "Patch the icpStrategy JSON column. Mental map consumed verbatim by the outreach " +
-        "agent preflight: {dealType, dreamOutcome, mainPains[], keyObjections[], " +
-        "decisionDrivers[]}. Reads current icpStrategy, shallow-merges the keys you " +
-        "pass, optionally removes specified keys. Arrays (mainPains, keyObjections, " +
-        "decisionDrivers) are REPLACED wholesale when passed.", {
-        ...optimisticPersonaMutationShape,
-        id: z.string().describe("Persona ID."),
-        dealType: z
-            .string()
-            .optional()
-            .describe("Type of deal (e.g. 'midmarket', 'enterprise', 'self-serve')."),
-        dreamOutcome: z
-            .string()
-            .optional()
-            .describe("The aspirational result the lead wants."),
-        mainPains: z
-            .array(z.string())
-            .optional()
-            .describe("Replaces the mainPains array wholesale when passed."),
-        keyObjections: z
-            .array(z.string())
-            .optional()
-            .describe("Replaces the keyObjections array wholesale when passed."),
-        decisionDrivers: z
-            .array(z.string())
-            .optional()
-            .describe("Replaces the decisionDrivers array wholesale when passed."),
-        patch: z
-            .record(z.unknown())
-            .optional()
-            .describe("Escape hatch for any additional/forward-compat keys — shallow-merged after the named fields."),
-        remove_keys: z
-            .array(z.string())
-            .optional()
-            .describe("Keys to delete from icpStrategy."),
-    }, async ({ organization_id, expected_updated_at, id, dealType, dreamOutcome, mainPains, keyObjections, decisionDrivers, patch, remove_keys, }) => {
+    server.tool("change_persona_status", "Change only Persona lifecycle status; it never changes business contract content.", { ...optimisticScope, id: z.string().min(1), status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]) }, async ({ organization_id, id, expected_updated_at, status }) => {
         try {
-            if (dealType === undefined &&
-                dreamOutcome === undefined &&
-                mainPains === undefined &&
-                keyObjections === undefined &&
-                decisionDrivers === undefined &&
-                (patch === undefined || Object.keys(patch).length === 0) &&
-                (remove_keys === undefined || remove_keys.length === 0)) {
-                return toolError("Provide at least one field to update.");
-            }
-            const current = await fetchPersona(id, organization_id, client ?? getClient());
-            const next = { ...asObject(current.icpStrategy) };
-            if (dealType !== undefined)
-                next.dealType = dealType;
-            if (dreamOutcome !== undefined)
-                next.dreamOutcome = dreamOutcome;
-            if (mainPains !== undefined)
-                next.mainPains = mainPains;
-            if (keyObjections !== undefined)
-                next.keyObjections = keyObjections;
-            if (decisionDrivers !== undefined)
-                next.decisionDrivers = decisionDrivers;
-            if (patch !== undefined)
-                Object.assign(next, patch);
-            for (const k of remove_keys ?? [])
-                delete next[k];
-            const data = await postPersonaUpdate(current, { icpStrategy: next }, organization_id, expected_updated_at, client ?? getClient());
-            return toolResult(data);
+            return toolResult(await client.post(`/api/persona/${encodeURIComponent(id)}/status?organizationId=${encodeURIComponent(organization_id)}`, { expectedUpdatedAt: expected_updated_at, status }));
         }
         catch (error) {
-            return handlePersonaToolError(error);
+            return handleToolError(error);
         }
     });
 }