edsger 0.69.0 → 0.71.0

package/dist/phases/sequence-diagram/index.js

@@ -0,0 +1,290 @@
+/**
+ * sequence-diagram phase: clone the product's repo, ask Claude to trace one
+ * scenario through the code and map the participants (actor / service /
+ * component / database / queue / external) and the ordered messages between
+ * them into a structured SequenceDiagramExtraction, then persist the result
+ * to diagrams / diagram_nodes / diagram_edges (rows tagged `type = 'sequence'`) via the
+ * Supabase SDK.
+ *
+ * Companion to data-flow / screen-flow / er-diagram: same generation pattern
+ * (workspace clone + Claude Agent SDK + in-process MCP server), same storage
+ * tables, different domain. Message ordering is persisted in the edge's
+ * `metadata.order`.
+ */
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { getRepositoryBasics } from '../../api/github.js';
+import { DEFAULT_MODEL } from '../../constants.js';
+import { getSupabase } from '../../supabase/client.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cleanupIssueRepo } from '../../workspace/workspace-manager.js';
+import { cloneDiagramRepos, describeRepoScope, } from '../diagram-shared/clone-repos.js';
+import { fetchProductBasics } from '../find-shared/mcp.js';
+import { createPromptGenerator, extractTextFromContent, tryExtractResult, } from '../pr-shared/agent-utils.js';
+import { createSequenceDiagramCaptureState, createSequenceDiagramMcpServer, validateConsistency, } from './mcp-server.js';
+import { createSequenceDiagramSystemPrompt, createSequenceDiagramUserPrompt, } from './prompts.js';
+import { isSequenceDiagramExtraction, } from './types.js';
+const WORKSPACE_KEY = 'sequence-diagram';
+const MAX_TURNS = 150;
+// Auto-layout: participants laid out left-to-right as lifeline columns; users
+// can drag afterwards and we persist positions.
+const COLUMN_WIDTH = 280;
+export async function runSequenceDiagramPhase(options) {
+    const { productId, repoId, diagramId, guidance, verbose } = options;
+    const repoOnly = !productId && Boolean(repoId);
+    if (productId) {
+        logInfo(`Starting sequence-diagram generation for product ${productId}`);
+    }
+    else {
+        logInfo(`Starting sequence-diagram generation for repository ${repoId}`);
+    }
+    const supabase = getSupabase();
+    await markDiagramRunning(supabase, diagramId);
+    const repositoryIds = await getDiagramRepositoryIds(supabase, diagramId);
+    const cloneResult = await cloneDiagramRepos({
+        productId,
+        repoId,
+        repositoryIds,
+        workspaceKey: WORKSPACE_KEY,
+        verbose,
+    });
+    if (!cloneResult.ok) {
+        await markDiagramFailed(supabase, diagramId, cloneResult.message);
+        return { status: 'error', message: cloneResult.message };
+    }
+    const { projectDir, cleanupDir, repos } = cloneResult;
+    let succeeded = false;
+    try {
+        const product = repoOnly
+            ? await resolveRepoBasics(repoId, repos)
+            : await fetchProductBasics(productId);
+        const systemPrompt = await createSequenceDiagramSystemPrompt({
+            projectDir,
+            hasCodebase: true,
+        });
+        const repoScope = describeRepoScope(repos);
+        const userPrompt = createSequenceDiagramUserPrompt({
+            productName: product.name,
+            productDescription: product.description,
+            guidance: [guidance, repoScope].filter(Boolean).join('\n\n') || undefined,
+        });
+        logInfo('Running Claude sequence-diagram extraction...');
+        const captureState = createSequenceDiagramCaptureState();
+        const mcpServer = createSequenceDiagramMcpServer(captureState, {
+            onProgress: ({ phase, message }) => {
+                logInfo(`[${phase}] ${message}`);
+            },
+        });
+        let lastAssistantResponse = '';
+        let extraction = null;
+        for await (const message of query({
+            prompt: createPromptGenerator(userPrompt),
+            options: {
+                systemPrompt: {
+                    type: 'preset',
+                    preset: 'claude_code',
+                    append: systemPrompt,
+                },
+                model: DEFAULT_MODEL,
+                maxTurns: MAX_TURNS,
+                permissionMode: 'bypassPermissions',
+                cwd: projectDir,
+                mcpServers: {
+                    'sequence-diagram': mcpServer,
+                },
+            },
+        })) {
+            const { assistantBuffer, extraction: nextExtraction } = processSdkMessage(message, lastAssistantResponse, captureState, verbose);
+            lastAssistantResponse = assistantBuffer;
+            if (nextExtraction) {
+                extraction = nextExtraction;
+            }
+        }
+        if (!extraction) {
+            const msg = 'Sequence diagram extraction failed: agent did not call submit_sequence_diagram and no parseable sequence_diagram block was found in the response';
+            await markDiagramFailed(supabase, diagramId, msg);
+            return { status: 'error', message: msg };
+        }
+        logInfo(`Extraction produced ${extraction.participants.length} participants / ${extraction.messages.length} messages`);
+        const { nodesCreated, edgesCreated } = await persistDiagram(supabase, diagramId, extraction);
+        await markDiagramSuccess(supabase, diagramId, extraction.summary);
+        succeeded = true;
+        logSuccess(`Sequence diagram generated: ${nodesCreated} participants, ${edgesCreated} messages`);
+        return {
+            status: 'success',
+            message: `Sequence diagram generated (${nodesCreated} participants, ${edgesCreated} messages)`,
+            nodesCreated,
+            edgesCreated,
+            summary: extraction.summary,
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logError(`Sequence diagram failed: ${errorMessage}`);
+        await markDiagramFailed(supabase, diagramId, errorMessage);
+        return { status: 'error', message: errorMessage };
+    }
+    finally {
+        if (succeeded) {
+            cleanupIssueRepo(cleanupDir);
+        }
+    }
+}
+/**
+ * Build "product basics" for repo-only mode from the repositories row,
+ * falling back to the cloned repo's full name when the row has no name.
+ */
+async function resolveRepoBasics(repositoryId, repos) {
+    const basics = await getRepositoryBasics(repositoryId).catch(() => null);
+    return {
+        name: basics?.fullName ?? repos[0]?.fullName ?? repositoryId,
+        description: basics?.description ?? undefined,
+    };
+}
+/** Read the ordered repo set a diagram was scoped to (may be empty). */
+async function getDiagramRepositoryIds(supabase, diagramId) {
+    const { data } = await supabase
+        .from('diagrams')
+        .select('repository_ids')
+        .eq('id', diagramId)
+        .single();
+    return (data?.repository_ids ?? []).filter(Boolean);
+}
+function processSdkMessage(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+message, assistantBuffer, captureState, verbose) {
+    if (message.type === 'assistant') {
+        const next = assistantBuffer +
+            extractTextFromContent(message.message?.content ?? [], verbose);
+        return { assistantBuffer: next, extraction: null };
+    }
+    if (message.type === 'user' && verbose) {
+        const userContent = message.message?.content;
+        if (Array.isArray(userContent)) {
+            extractTextFromContent(userContent, verbose);
+        }
+        return { assistantBuffer, extraction: null };
+    }
+    if (message.type !== 'result') {
+        return { assistantBuffer, extraction: null };
+    }
+    if (captureState.captured) {
+        return { assistantBuffer, extraction: captureState.captured };
+    }
+    const fallback = tryFallbackParse(message, assistantBuffer);
+    if (fallback) {
+        logWarning('Agent emitted a fenced sequence_diagram block instead of calling submit_sequence_diagram; using the parsed text as a fallback.');
+        return { assistantBuffer, extraction: fallback };
+    }
+    if (message.subtype !== 'success') {
+        logError(`Extraction incomplete: ${message.subtype}`);
+    }
+    return { assistantBuffer, extraction: null };
+}
+function tryFallbackParse(resultMessage, assistantText) {
+    const responseText = resultMessage.subtype === 'success'
+        ? resultMessage.result || assistantText
+        : assistantText;
+    const parsed = tryExtractResult(responseText, 'sequence_diagram');
+    if (!isSequenceDiagramExtraction(parsed)) {
+        return null;
+    }
+    const { error } = validateConsistency(parsed);
+    if (error) {
+        logWarning(`Fallback extraction failed consistency check: ${error}`);
+        return null;
+    }
+    return parsed;
+}
+// ============================================================================
+// Persistence
+// ============================================================================
+async function markDiagramRunning(supabase, diagramId) {
+    const { error } = await supabase
+        .from('diagrams')
+        .update({ status: 'running', error: null })
+        .eq('id', diagramId);
+    if (error) {
+        logWarning(`Could not mark diagram as running: ${error.message}`);
+    }
+}
+async function markDiagramFailed(supabase, diagramId, errorMessage) {
+    await supabase
+        .from('diagrams')
+        .update({
+        status: 'failed',
+        error: errorMessage,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', diagramId);
+}
+async function markDiagramSuccess(supabase, diagramId, summary) {
+    await supabase
+        .from('diagrams')
+        .update({
+        status: 'success',
+        summary,
+        error: null,
+        completed_at: new Date().toISOString(),
+    })
+        .eq('id', diagramId);
+}
+async function persistDiagram(supabase, diagramId, extraction) {
+    await supabase.from('diagram_edges').delete().eq('diagram_id', diagramId);
+    await supabase.from('diagram_nodes').delete().eq('diagram_id', diagramId);
+    if (extraction.participants.length === 0) {
+        return { nodesCreated: 0, edgesCreated: 0 };
+    }
+    const nodeRows = extraction.participants.map((p, i) => buildNodeRow(diagramId, p, i));
+    const { data: insertedNodes, error: nodesError } = await supabase
+        .from('diagram_nodes')
+        .insert(nodeRows)
+        .select('id, slug');
+    if (nodesError) {
+        throw new Error(`Failed to insert participants: ${nodesError.message}`);
+    }
+    const slugToId = new Map((insertedNodes ?? []).map((n) => [n.slug, n.id]));
+    const edgeRows = extraction.messages
+        .map((m) => buildEdgeRow(diagramId, m, slugToId))
+        .filter((e) => e !== null);
+    if (edgeRows.length > 0) {
+        const { error: edgesError } = await supabase
+            .from('diagram_edges')
+            .insert(edgeRows);
+        if (edgesError) {
+            throw new Error(`Failed to insert messages: ${edgesError.message}`);
+        }
+    }
+    return {
+        nodesCreated: nodeRows.length,
+        edgesCreated: edgeRows.length,
+    };
+}
+function buildNodeRow(diagramId, participant, index) {
+    return {
+        diagram_id: diagramId,
+        slug: participant.slug,
+        name: participant.name,
+        kind: participant.kind,
+        schema: participant,
+        // Lifelines sit in a single row, ordered left-to-right by emission order.
+        position_x: index * COLUMN_WIDTH,
+        position_y: 0,
+    };
+}
+function buildEdgeRow(diagramId, message, slugToId) {
+    const fromId = slugToId.get(message.fromSlug);
+    const toId = slugToId.get(message.toSlug);
+    if (!fromId || !toId) {
+        return null;
+    }
+    return {
+        diagram_id: diagramId,
+        from_node_id: fromId,
+        to_node_id: toId,
+        label: message.label ?? null,
+        source_anchor: message.sourceFile ?? null,
+        kind: message.kind,
+        // Message timeline position — the renderer sorts edges by this.
+        metadata: { order: message.order },
+    };
+}

package/dist/phases/sequence-diagram/mcp-server.d.ts

@@ -0,0 +1,64 @@
+/**
+ * In-process MCP server for the sequence-diagram phase. Exposes a single
+ * tool — `submit_sequence_diagram` — that the agent calls with the structured
+ * extraction, plus `record_progress` for streaming status messages.
+ *
+ * Mirrors the shape of phases/data-flow/mcp-server.ts; see that file for
+ * the design rationale (zod schema + cross-field consistency + capture state).
+ */
+import { z } from 'zod';
+import type { SequenceDiagramExtraction } from './types.js';
+export interface SequenceDiagramCaptureState {
+    captured: SequenceDiagramExtraction | null;
+}
+export declare function createSequenceDiagramCaptureState(): SequenceDiagramCaptureState;
+export type SequenceDiagramProgressSink = (event: {
+    phase: 'detection' | 'enumeration' | 'participants' | 'messages' | 'submission';
+    message: string;
+}) => void;
+export declare function validateConsistency(extraction: SequenceDiagramExtraction): {
+    error: string | null;
+};
+export declare function createSubmitSequenceDiagramTool(state: SequenceDiagramCaptureState): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    summary: z.ZodString;
+    participants: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            service: "service";
+            external: "external";
+            queue: "queue";
+            actor: "actor";
+            component: "component";
+            database: "database";
+        }>;
+        file: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    messages: z.ZodArray<z.ZodObject<{
+        fromSlug: z.ZodString;
+        toSlug: z.ZodString;
+        kind: z.ZodEnum<{
+            sync: "sync";
+            async: "async";
+            return: "return";
+            self: "self";
+        }>;
+        order: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        sourceFile: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}>;
+export declare function createRecordProgressTool(sink?: SequenceDiagramProgressSink): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    phase: z.ZodEnum<{
+        detection: "detection";
+        enumeration: "enumeration";
+        submission: "submission";
+        participants: "participants";
+        messages: "messages";
+    }>;
+    message: z.ZodString;
+}>;
+export declare function createSequenceDiagramMcpServer(state: SequenceDiagramCaptureState, options?: {
+    onProgress?: SequenceDiagramProgressSink;
+}): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/phases/sequence-diagram/mcp-server.js

@@ -0,0 +1,134 @@
+/**
+ * In-process MCP server for the sequence-diagram phase. Exposes a single
+ * tool — `submit_sequence_diagram` — that the agent calls with the structured
+ * extraction, plus `record_progress` for streaming status messages.
+ *
+ * Mirrors the shape of phases/data-flow/mcp-server.ts; see that file for
+ * the design rationale (zod schema + cross-field consistency + capture state).
+ */
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+export function createSequenceDiagramCaptureState() {
+    return { captured: null };
+}
+// ---------------------------------------------------------------------------
+// Zod schemas (mirror types.ts)
+// ---------------------------------------------------------------------------
+const participantSchema = z.object({
+    slug: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum([
+        'actor',
+        'service',
+        'component',
+        'database',
+        'queue',
+        'external',
+    ]),
+    file: z.string().optional(),
+    description: z.string().optional(),
+});
+const messageSchema = z.object({
+    fromSlug: z.string().min(1),
+    toSlug: z.string().min(1),
+    kind: z.enum(['sync', 'async', 'return', 'self']),
+    order: z.number().int(),
+    label: z.string().optional(),
+    sourceFile: z.string().optional(),
+});
+export function validateConsistency(extraction) {
+    const slugs = new Set();
+    for (const participant of extraction.participants) {
+        if (slugs.has(participant.slug)) {
+            return {
+                error: `Duplicate participant slug "${participant.slug}". Each participant.slug MUST be unique within the diagram. Re-call submit_sequence_diagram with deduplicated participants.`,
+            };
+        }
+        slugs.add(participant.slug);
+    }
+    for (const message of extraction.messages) {
+        if (!slugs.has(message.fromSlug)) {
+            return {
+                error: `Message fromSlug "${message.fromSlug}" → "${message.toSlug}" does not match any participant slug. Either add the missing participant or drop the message, then re-call submit_sequence_diagram.`,
+            };
+        }
+        if (!slugs.has(message.toSlug)) {
+            return {
+                error: `Message fromSlug "${message.fromSlug}" → toSlug "${message.toSlug}" does not match any participant slug. Either add the missing participant or drop the message, then re-call submit_sequence_diagram.`,
+            };
+        }
+    }
+    return { error: null };
+}
+export function createSubmitSequenceDiagramTool(state) {
+    return tool('submit_sequence_diagram', [
+        'Submit the final sequence diagram. Call this EXACTLY once, when you',
+        'have finished mapping every participant and the ordered messages',
+        'between them. Pass the full structured diagram as the argument. After',
+        'this call succeeds, end your turn — do NOT also paste the same data as',
+        'a fenced code block. If validation fails, the error message tells you',
+        'what to fix; call the tool again with corrected data.',
+    ].join(' '), {
+        summary: z
+            .string()
+            .min(1)
+            .describe('1-3 sentence narrative of the scenario this diagram captures and the participants involved.'),
+        participants: z
+            .array(participantSchema)
+            .describe('Every participant / lifeline: actor / service / component / database / queue / external. participant.slug MUST be unique within the diagram.'),
+        messages: z
+            .array(messageSchema)
+            .describe('The ordered interactions. Each message has a 1-based `order` defining its position in the timeline. fromSlug = sender, toSlug = receiver. Every fromSlug / toSlug MUST reference a slug present in participants; drop messages whose endpoints you did not emit.'),
+    }, async (args) => {
+        const extraction = {
+            summary: args.summary,
+            participants: args.participants,
+            messages: args.messages,
+        };
+        const { error } = validateConsistency(extraction);
+        if (error) {
+            return {
+                content: [{ type: 'text', text: error }],
+                isError: true,
+            };
+        }
+        state.captured = extraction;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Captured ${extraction.participants.length} participants / ${extraction.messages.length} messages. End your turn now.`,
+                },
+            ],
+        };
+    });
+}
+export function createRecordProgressTool(sink) {
+    return tool('record_progress', 'Send a short status update to the user. Does not affect the extraction. Call it at each phase boundary so the user sees progress.', {
+        phase: z
+            .enum([
+            'detection',
+            'enumeration',
+            'participants',
+            'messages',
+            'submission',
+        ])
+            .describe('Which phase the message belongs to.'),
+        message: z.string().min(1).describe('Human-readable status update.'),
+    }, async (args) => {
+        sink?.({ phase: args.phase, message: args.message });
+        return {
+            content: [{ type: 'text', text: 'ok' }],
+        };
+    });
+}
+export function createSequenceDiagramMcpServer(state, options) {
+    return createSdkMcpServer({
+        name: 'sequence-diagram',
+        version: '1.0.0',
+        tools: [
+            createSubmitSequenceDiagramTool(state),
+            createRecordProgressTool(options?.onProgress),
+        ],
+    });
+}

package/dist/phases/sequence-diagram/prompts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Prompts for the sequence-diagram phase. Loads the system prompt body from
+ * `skills/phase/sequence-diagram/SKILL.md` (with optional project override)
+ * and appends the JSON output contract.
+ */
+export declare function createSequenceDiagramSystemPrompt(options?: {
+    projectDir?: string;
+    hasCodebase?: boolean;
+}): Promise<string>;
+export declare function createSequenceDiagramUserPrompt(args: {
+    productName: string;
+    productDescription?: string;
+    guidance?: string;
+}): string;

package/dist/phases/sequence-diagram/prompts.js

@@ -0,0 +1,36 @@
+/**
+ * Prompts for the sequence-diagram phase. Loads the system prompt body from
+ * `skills/phase/sequence-diagram/SKILL.md` (with optional project override)
+ * and appends the JSON output contract.
+ */
+import { processConditionals, resolveSkill, } from '../../services/skill-resolver.js';
+import { OUTPUT_CONTRACTS } from '../output-contracts.js';
+export async function createSequenceDiagramSystemPrompt(options) {
+    const skill = await resolveSkill('phase/sequence-diagram', {
+        projectDir: options?.projectDir,
+    });
+    if (!skill) {
+        throw new Error('Failed to load skill: phase/sequence-diagram');
+    }
+    const prompt = processConditionals(skill.prompt, {
+        hasCodebase: options?.hasCodebase ?? true,
+    });
+    return `${prompt}
+
+${OUTPUT_CONTRACTS['sequence-diagram']}`;
+}
+export function createSequenceDiagramUserPrompt(args) {
+    const scenarioBlock = args.guidance
+        ? `\n\n**Scenario to map** (human guidance — diagram THIS interaction):\n${args.guidance}`
+        : '\n\nNo specific scenario was given — pick the single most central end-to-end interaction in the product (e.g. the primary user action, request lifecycle, or auth flow) and map that one.';
+    const descBlock = args.productDescription
+        ? `\n**Product description**: ${args.productDescription}`
+        : '';
+    return `Map a sequence diagram for **${args.productName}**.${descBlock}${scenarioBlock}
+
+A sequence diagram captures ONE scenario / flow of control as an ordered series of messages between participants. Start by detecting the stack, then trace the chosen scenario through the code — the entry point (route handler / event handler / CLI command), the services and components it calls, the datastores and external systems it touches — following the call chain in order. Read just enough per step to label each message accurately.
+
+Call \`mcp__sequence-diagram__record_progress\` at each phase boundary so the user can see your progress (otherwise the CLI looks frozen).
+
+When you are done, return the result by **calling the \`mcp__sequence-diagram__submit_sequence_diagram\` tool exactly once** with \`summary\`, \`participants\`, and \`messages\` as arguments. Number the messages with a 1-based \`order\` that reflects execution order. Do not paste the JSON as a fenced text block — the tool call is the deliverable. If the tool returns an error, fix the issue it describes and call the tool again.`;
+}

package/dist/phases/sequence-diagram/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Sequence Diagram domain types.
+ *
+ * A SequenceParticipant is one lifeline in an interaction — an actor, a
+ * service, a database, an external system, a queue, or an internal
+ * component. A SequenceMessage is one ordered interaction between two
+ * participants (a call, an async send, a return, or a self-message).
+ *
+ * A sequence diagram captures ONE scenario / flow of control (e.g. "user
+ * checkout", "OAuth login"); the user's guidance picks the scenario. The CLI
+ * extracts it from source code (call sites, handlers, SDK calls) and the
+ * desktop renders participants as lifelines with the messages ordered by the
+ * `order` field.
+ *
+ * Companion to DataNodeSchema / ErEntity: same flow-graph shape (nodes +
+ * edges sharing the `diagrams` table storing the JSONB schema), different domain.
+ */
+export type SequenceParticipantKind = 'actor' | 'service' | 'component' | 'database' | 'queue' | 'external';
+export interface SequenceParticipant {
+    /** Stable slug within the diagram (e.g. 'user', 'auth-service'). */
+    slug: string;
+    /** Human-readable name. */
+    name: string;
+    kind: SequenceParticipantKind;
+    /** Source file path (jump anchor) where the participant is defined. */
+    file?: string;
+    /** One-sentence description of the participant's role. */
+    description?: string;
+}
+/**
+ * Message kinds describe the nature of the interaction arrow.
+ */
+export type SequenceMessageKind = 'sync' | 'async' | 'return' | 'self';
+export interface SequenceMessage {
+    /** Sender participant slug. */
+    fromSlug: string;
+    /** Receiver participant slug. */
+    toSlug: string;
+    kind: SequenceMessageKind;
+    /** 1-based position of this message in the interaction timeline. */
+    order: number;
+    /** The call / message text ('POST /login', 'validateToken()', 'rows'). */
+    label?: string;
+    /** File + line where this call happens (for jump-to-code). */
+    sourceFile?: string;
+}
+export interface SequenceDiagramExtraction {
+    summary: string;
+    participants: SequenceParticipant[];
+    messages: SequenceMessage[];
+}
+export declare function isSequenceDiagramExtraction(value: unknown): value is SequenceDiagramExtraction;

package/dist/phases/sequence-diagram/types.js

@@ -0,0 +1,93 @@
+/**
+ * Sequence Diagram domain types.
+ *
+ * A SequenceParticipant is one lifeline in an interaction — an actor, a
+ * service, a database, an external system, a queue, or an internal
+ * component. A SequenceMessage is one ordered interaction between two
+ * participants (a call, an async send, a return, or a self-message).
+ *
+ * A sequence diagram captures ONE scenario / flow of control (e.g. "user
+ * checkout", "OAuth login"); the user's guidance picks the scenario. The CLI
+ * extracts it from source code (call sites, handlers, SDK calls) and the
+ * desktop renders participants as lifelines with the messages ordered by the
+ * `order` field.
+ *
+ * Companion to DataNodeSchema / ErEntity: same flow-graph shape (nodes +
+ * edges sharing the `diagrams` table storing the JSONB schema), different domain.
+ */
+// ============================================================================
+// Runtime validation for AI-produced extraction
+// ============================================================================
+const PARTICIPANT_KINDS = new Set([
+    'actor',
+    'service',
+    'component',
+    'database',
+    'queue',
+    'external',
+]);
+const MESSAGE_KINDS = new Set([
+    'sync',
+    'async',
+    'return',
+    'self',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isSequenceParticipant(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.slug !== 'string' || value.slug.length === 0) {
+        return false;
+    }
+    if (typeof value.name !== 'string' || value.name.length === 0) {
+        return false;
+    }
+    if (typeof value.kind !== 'string' ||
+        !PARTICIPANT_KINDS.has(value.kind)) {
+        return false;
+    }
+    return true;
+}
+function isSequenceMessage(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.fromSlug !== 'string') {
+        return false;
+    }
+    if (typeof value.toSlug !== 'string') {
+        return false;
+    }
+    if (typeof value.kind !== 'string' ||
+        !MESSAGE_KINDS.has(value.kind)) {
+        return false;
+    }
+    if (typeof value.order !== 'number') {
+        return false;
+    }
+    return true;
+}
+export function isSequenceDiagramExtraction(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (typeof value.summary !== 'string') {
+        return false;
+    }
+    if (!Array.isArray(value.participants)) {
+        return false;
+    }
+    if (!Array.isArray(value.messages)) {
+        return false;
+    }
+    if (!value.participants.every(isSequenceParticipant)) {
+        return false;
+    }
+    if (!value.messages.every(isSequenceMessage)) {
+        return false;
+    }
+    return true;
+}