feat(crm): lead convert endpoint (M10.6)

Salesforce-style lead conversion that creates an Account + Contact (+
optional Opportunity) and atomically marks the lead converted with
pointer fields and timestamp.

  POST /api/v1/data/lead/:id/convert
  {
    "accountId":         optional — reuse existing account
    "contactId":         optional — reuse existing contact
    "createOpportunity": optional boolean, default true
    "opportunity":       optional { name, amount, close_date, stage }
    "convertedStatus":   optional, default 'converted'
  }

Behavior:
- Loads the lead via the caller's execution context (SecurityPlugin
  still gates reads). Rejects with 404 LEAD_NOT_FOUND if missing and
  409 LEAD_ALREADY_CONVERTED if is_converted is already true so the
  UI can disable the action without polling.
- Creates account from lead.company/industry/annual_revenue/website/
  phone/address/owner unless accountId given.
- Creates contact from lead identity + email/phone/mobile/title/owner,
  linked to the account, unless contactId given.
- Creates opportunity (stage='qualification', close_date=+30d,
  amount=annual_revenue) linked to account + primary_contact unless
  createOpportunity:false. Caller can override via 'opportunity'.
- Updates lead: is_converted=true, converted_{account,contact,
  opportunity}, converted_date=now, status='converted'.

Atomicity: best-effort compensating delete in reverse order (opp →
contact → account) when any step throws after partial writes. True
transactional execution is only available via ScopedContext and is
not yet wired through the protocol layer — tracked separately.

Verified end-to-end against running app-crm:
  * Alice Martinez (NextGen Retail) → account, contact, opportunity,
    lead.status=converted, all pointer fields populated.
  * Re-convert → 409 LEAD_ALREADY_CONVERTED.
  * Unknown lead id → 404 LEAD_NOT_FOUND.
  * createOpportunity:false → opportunity=null, account & contact
    created, lead.is_converted=true.

All 232 objectql tests + 53 rest tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: hotlong

packages/objectql/src/protocol.ts

@@ -1020,6 +1020,196 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         };
     }
 
+    // ==========================================
+    // Lead Convert (M10.6)
+    // ==========================================
+    /**
+     * Convert a qualified Lead into an Account + Contact (+ optional
+     * Opportunity) and mark the Lead as converted. Mirrors the Salesforce
+     * lead-conversion model:
+     *
+     *   - If `accountId` is provided, the lead's company info is NOT used
+     *     to create a new account; the new contact and opportunity link to
+     *     the existing account instead.
+     *   - If `contactId` is provided, no new contact is created either —
+     *     useful when the lead is a new contact at an existing account.
+     *   - `createOpportunity` defaults to true; pass `false` to convert
+     *     without producing an opportunity (some teams convert "logos
+     *     only" first).
+     *   - Lead is updated atomically: `is_converted=true`,
+     *     `converted_account`/`converted_contact`/`converted_opportunity`
+     *     pointers, `converted_date`, and `status='converted'`.
+     *
+     * Atomicity is enforced via the default driver's transaction support
+     * when available; otherwise a best-effort compensation (delete
+     * already-created child records on failure) is attempted. Permission
+     * checks on each child object are inherited from the caller's
+     * execution context so SecurityPlugin still gates account/contact/
+     * opportunity creates.
+     */
+    async convertLead(request: {
+        leadId: string;
+        accountId?: string;
+        contactId?: string;
+        createOpportunity?: boolean;
+        opportunity?: {
+            name?: string;
+            amount?: number;
+            close_date?: string;
+            stage?: string;
+        };
+        convertedStatus?: string;
+        context?: any;
+    }): Promise<{
+        lead: any;
+        account: any;
+        contact: any;
+        opportunity: any | null;
+    }> {
+        const leadId = String(request.leadId || '').trim();
+        if (!leadId) {
+            const err: any = new Error('leadId is required');
+            err.status = 400;
+            err.code = 'INVALID_REQUEST';
+            throw err;
+        }
+        const ctx = request.context;
+        const ctxOpt = ctx !== undefined ? { context: ctx } : undefined;
+
+        // Load lead
+        const lead = await this.engine.findOne('lead', { where: { id: leadId }, ...(ctxOpt as any) } as any);
+        if (!lead) {
+            const err: any = new Error(`Lead '${leadId}' not found`);
+            err.status = 404;
+            err.code = 'LEAD_NOT_FOUND';
+            throw err;
+        }
+        if (lead.is_converted) {
+            const err: any = new Error(`Lead '${leadId}' is already converted`);
+            err.status = 409;
+            err.code = 'LEAD_ALREADY_CONVERTED';
+            throw err;
+        }
+
+        const createdAccountIds: string[] = [];
+        const createdContactIds: string[] = [];
+        const createdOpportunityIds: string[] = [];
+
+        const rollback = async () => {
+            for (const id of createdOpportunityIds) {
+                try { await this.engine.delete('opportunity', { where: { id } } as any); } catch { /* ignore */ }
+            }
+            for (const id of createdContactIds) {
+                try { await this.engine.delete('contact', { where: { id } } as any); } catch { /* ignore */ }
+            }
+            for (const id of createdAccountIds) {
+                try { await this.engine.delete('account', { where: { id } } as any); } catch { /* ignore */ }
+            }
+        };
+
+        try {
+            // 1) Account
+            let account: any;
+            if (request.accountId) {
+                account = await this.engine.findOne('account', { where: { id: request.accountId }, ...(ctxOpt as any) } as any);
+                if (!account) {
+                    const err: any = new Error(`Account '${request.accountId}' not found`);
+                    err.status = 404;
+                    err.code = 'ACCOUNT_NOT_FOUND';
+                    throw err;
+                }
+            } else {
+                const accountPayload: Record<string, any> = {
+                    name: lead.company || `${lead.first_name ?? ''} ${lead.last_name ?? ''}`.trim() || 'Untitled Account',
+                };
+                if (lead.industry)        accountPayload.industry = lead.industry;
+                if (lead.annual_revenue)  accountPayload.annual_revenue = lead.annual_revenue;
+                if (lead.number_of_employees) accountPayload.employees = lead.number_of_employees;
+                if (lead.website)         accountPayload.website = lead.website;
+                if (lead.phone)           accountPayload.phone = lead.phone;
+                if (lead.address)         accountPayload.billing_address = lead.address;
+                if (lead.owner)           accountPayload.owner = lead.owner;
+                account = await this.engine.insert('account', accountPayload, ctxOpt as any);
+                if (account?.id) createdAccountIds.push(account.id);
+            }
+
+            // 2) Contact
+            let contact: any;
+            if (request.contactId) {
+                contact = await this.engine.findOne('contact', { where: { id: request.contactId }, ...(ctxOpt as any) } as any);
+                if (!contact) {
+                    const err: any = new Error(`Contact '${request.contactId}' not found`);
+                    err.status = 404;
+                    err.code = 'CONTACT_NOT_FOUND';
+                    throw err;
+                }
+            } else {
+                const contactPayload: Record<string, any> = {
+                    first_name: lead.first_name ?? '',
+                    last_name:  lead.last_name  ?? lead.company ?? 'Unknown',
+                };
+                if (lead.salutation) contactPayload.salutation = lead.salutation;
+                if (lead.email)      contactPayload.email = lead.email;
+                if (lead.phone)      contactPayload.phone = lead.phone;
+                if (lead.mobile)     contactPayload.mobile = lead.mobile;
+                if (lead.title)      contactPayload.title = lead.title;
+                if (lead.address)    contactPayload.mailing_address = lead.address;
+                if (lead.owner)      contactPayload.owner = lead.owner;
+                if (account?.id)     contactPayload.account = account.id;
+                contact = await this.engine.insert('contact', contactPayload, ctxOpt as any);
+                if (contact?.id) createdContactIds.push(contact.id);
+            }
+
+            // 3) Opportunity (optional)
+            let opportunity: any | null = null;
+            const shouldCreateOpp = request.createOpportunity !== false;
+            if (shouldCreateOpp) {
+                const oppOverrides = request.opportunity ?? {};
+                const defaultName = oppOverrides.name
+                    || `${account?.name ?? lead.company ?? 'Lead'} - New Opportunity`;
+                const defaultClose = oppOverrides.close_date
+                    || new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+                const oppPayload: Record<string, any> = {
+                    name: defaultName,
+                    stage: oppOverrides.stage ?? 'qualification',
+                    close_date: defaultClose,
+                };
+                if (oppOverrides.amount !== undefined)  oppPayload.amount = oppOverrides.amount;
+                else if (lead.annual_revenue)            oppPayload.amount = lead.annual_revenue;
+                if (account?.id)  oppPayload.account = account.id;
+                if (contact?.id)  oppPayload.primary_contact = contact.id;
+                if (lead.owner)   oppPayload.owner = lead.owner;
+                if (lead.lead_source) oppPayload.lead_source = lead.lead_source;
+                opportunity = await this.engine.insert('opportunity', oppPayload, ctxOpt as any);
+                if (opportunity?.id) createdOpportunityIds.push(opportunity.id);
+            }
+
+            // 4) Mark lead converted
+            const leadUpdate: Record<string, any> = {
+                is_converted: true,
+                status: request.convertedStatus ?? 'converted',
+                converted_account:     account?.id ?? null,
+                converted_contact:     contact?.id ?? null,
+                converted_opportunity: opportunity?.id ?? null,
+                converted_date:        new Date().toISOString(),
+            };
+            const updatedLead = await this.engine.update('lead', leadUpdate, {
+                where: { id: leadId },
+                ...(ctxOpt as any),
+            } as any);
+
+            return {
+                lead: updatedLead ?? { ...lead, ...leadUpdate },
+                account,
+                contact,
+                opportunity,
+            };
+        } catch (err) {
+            await rollback();
+            throw err;
+        }
+    }
+
     // ==========================================
     // Metadata Caching
     // ==========================================

packages/rest/src/rest-server.ts

@@ -829,6 +829,7 @@ export class RestServer {
             if (this.config.api.enableSearch ?? true) {
                 this.registerSearchEndpoints(bp);
             }
+            this.registerDataActionEndpoints(bp);
             if (this.config.api.enableBatch) {
                 this.registerBatchEndpoints(bp);
             }
@@ -1415,6 +1416,57 @@ export class RestServer {
         }
     }
 
+    /**
+     * Register object-specific action endpoints that don't fit the
+     * generic CRUD shape. These are domain operations (Salesforce
+     * convertLead, etc.) where the protocol implementation does its own
+     * multi-record orchestration and we just need a thin HTTP route.
+     *
+     * POST {basePath}/data/lead/:id/convert — M10.6 lead conversion.
+     */
+    private registerDataActionEndpoints(basePath: string): void {
+        const isScoped = basePath.includes('/projects/:projectId');
+        const { crud } = this.config;
+        const dataPath = `${basePath}${crud.dataPrefix}`;
+
+        // POST /data/lead/:id/convert
+        this.routeManager.register({
+            method: 'POST',
+            path: `${dataPath}/lead/:id/convert`,
+            handler: async (req: any, res: any) => {
+                try {
+                    const projectId = isScoped ? req.params?.projectId : undefined;
+                    const p = await this.resolveProtocol(projectId, req);
+                    const context = await this.resolveExecCtx(projectId, req);
+                    if (this.enforceAuth(req, res, context)) return;
+                    const convertLead = (p as any).convertLead;
+                    if (typeof convertLead !== 'function') {
+                        res.status(501).json({ code: 'NOT_IMPLEMENTED', error: 'Lead convert not supported by this protocol' });
+                        return;
+                    }
+                    const body = req.body ?? {};
+                    const result = await convertLead.call(p, {
+                        leadId: req.params.id,
+                        accountId: body.accountId,
+                        contactId: body.contactId,
+                        createOpportunity: body.createOpportunity,
+                        opportunity: body.opportunity,
+                        convertedStatus: body.convertedStatus,
+                        ...(context ? { context } : {}),
+                    });
+                    res.json(result);
+                } catch (error: any) {
+                    logError('[REST] Unhandled error:', error);
+                    sendError(res, error, 'lead');
+                }
+            },
+            metadata: {
+                summary: 'Convert a Lead into Account + Contact (+ optional Opportunity)',
+                tags: ['data', 'lead'],
+            },
+        });
+    }
+
     /**
      * Register global cross-object search endpoint (M10.5).
      * GET {basePath}/search?q=acme&objects=lead,account&limit=20&perObject=5