spawnfile 0.1.25 → 0.1.28

package/dist/training/optimization/protocol.d.ts

@@ -0,0 +1,532 @@
+import { z } from 'zod';
+import type { InferenceAttempt } from '../contracts/execution.js';
+export declare const DSPY_SCHEMA = "spawnfile.training.dspy.v2";
+export declare const DSPY_FRAME_BYTES: number;
+export declare const componentsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export declare const budgetSchema: z.ZodObject<{
+    maxMetricCalls: z.ZodNumber;
+    maxProposals: z.ZodNumber;
+}, z.core.$strict>;
+export declare const proposalPolicySchema: z.ZodObject<{
+    strategy: z.ZodOptional<z.ZodEnum<{
+        refine: "refine";
+        rewrite: "rewrite";
+    }>>;
+    min_change: z.ZodOptional<z.ZodNumber>;
+    max_attempts: z.ZodOptional<z.ZodNumber>;
+    history_entries: z.ZodOptional<z.ZodNumber>;
+    history_bytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const searchSchema: z.ZodPipe<z.ZodObject<{
+    variants: z.ZodNumber;
+    keep: z.ZodNumber;
+    rounds: z.ZodNumber;
+    selection: z.ZodDefault<z.ZodEnum<{
+        pareto: "pareto";
+        "top-k": "top-k";
+    }>>;
+    rewriteShare: z.ZodDefault<z.ZodNumber>;
+    minChange: z.ZodDefault<z.ZodNumber>;
+    hypothesisSimilarity: z.ZodDefault<z.ZodNumber>;
+    patience: z.ZodOptional<z.ZodNumber>;
+    boundaries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodTransform<{
+    patience: number;
+    variants: number;
+    keep: number;
+    rounds: number;
+    selection: "pareto" | "top-k";
+    rewriteShare: number;
+    minChange: number;
+    hypothesisSimilarity: number;
+    boundaries: string[];
+}, {
+    variants: number;
+    keep: number;
+    rounds: number;
+    selection: "pareto" | "top-k";
+    rewriteShare: number;
+    minChange: number;
+    hypothesisSimilarity: number;
+    boundaries: string[];
+    patience?: number | undefined;
+}>>;
+export declare const editScopeSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"whole-file">, z.ZodArray<z.ZodString>]>>;
+export declare const startSchema: z.ZodObject<{
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    kind: z.ZodLiteral<"optimize">;
+    id: z.ZodString;
+    components: z.ZodRecord<z.ZodString, z.ZodString>;
+    trainCaseIds: z.ZodArray<z.ZodString>;
+    validationCaseIds: z.ZodArray<z.ZodString>;
+    recovery: z.ZodOptional<z.ZodObject<{
+        evaluations: z.ZodNumber;
+        proposals: z.ZodNumber;
+    }, z.core.$strict>>;
+    checkpoint: z.ZodOptional<z.ZodObject<{
+        directory: z.ZodString;
+        identity: z.ZodString;
+        fork: z.ZodOptional<z.ZodObject<{
+            directory: z.ZodString;
+            identity: z.ZodString;
+            id: z.ZodString;
+            digest: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    proposal: z.ZodOptional<z.ZodObject<{
+        strategy: z.ZodOptional<z.ZodEnum<{
+            refine: "refine";
+            rewrite: "rewrite";
+        }>>;
+        min_change: z.ZodOptional<z.ZodNumber>;
+        max_attempts: z.ZodOptional<z.ZodNumber>;
+        history_entries: z.ZodOptional<z.ZodNumber>;
+        history_bytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    search: z.ZodOptional<z.ZodPipe<z.ZodObject<{
+        variants: z.ZodNumber;
+        keep: z.ZodNumber;
+        rounds: z.ZodNumber;
+        selection: z.ZodDefault<z.ZodEnum<{
+            pareto: "pareto";
+            "top-k": "top-k";
+        }>>;
+        rewriteShare: z.ZodDefault<z.ZodNumber>;
+        minChange: z.ZodDefault<z.ZodNumber>;
+        hypothesisSimilarity: z.ZodDefault<z.ZodNumber>;
+        patience: z.ZodOptional<z.ZodNumber>;
+        boundaries: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodTransform<{
+        patience: number;
+        variants: number;
+        keep: number;
+        rounds: number;
+        selection: "pareto" | "top-k";
+        rewriteShare: number;
+        minChange: number;
+        hypothesisSimilarity: number;
+        boundaries: string[];
+    }, {
+        variants: number;
+        keep: number;
+        rounds: number;
+        selection: "pareto" | "top-k";
+        rewriteShare: number;
+        minChange: number;
+        hypothesisSimilarity: number;
+        boundaries: string[];
+        patience?: number | undefined;
+    }>>>;
+    editScope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"whole-file">, z.ZodArray<z.ZodString>]>>>;
+    concurrency: z.ZodDefault<z.ZodNumber>;
+    budget: z.ZodObject<{
+        maxMetricCalls: z.ZodNumber;
+        maxProposals: z.ZodNumber;
+    }, z.core.$strict>;
+    seed: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const evaluationSchema: z.ZodObject<{
+    score: z.ZodNumber;
+    feedback: z.ZodString;
+    output: z.ZodString;
+    captureId: z.ZodString;
+}, z.core.$strict>;
+export declare const usageSchema: z.ZodNullable<z.ZodObject<{
+    inputTokens: z.ZodNullable<z.ZodNumber>;
+    cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+    outputTokens: z.ZodNullable<z.ZodNumber>;
+    cacheWriteInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cacheWrite5mInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cacheWrite1hInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    reasoningTokens: z.ZodNullable<z.ZodNumber>;
+    source: z.ZodString;
+}, z.core.$strict>>;
+/** Host-only evidence. Attempts never cross the strict Python response protocol. */
+export declare const inferenceSchema: z.ZodObject<{
+    text: z.ZodString;
+    model: z.ZodString;
+    usage: z.ZodNullable<z.ZodObject<{
+        inputTokens: z.ZodNullable<z.ZodNumber>;
+        cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+        outputTokens: z.ZodNullable<z.ZodNumber>;
+        cacheWriteInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        cacheWrite5mInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        cacheWrite1hInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        reasoningTokens: z.ZodNullable<z.ZodNumber>;
+        source: z.ZodString;
+    }, z.core.$strict>>;
+    route: z.ZodString;
+    modelBasis: z.ZodOptional<z.ZodEnum<{
+        "provider-reported": "provider-reported";
+        "requested-assumption": "requested-assumption";
+    }>>;
+    attempts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        ordinal: z.ZodNumber;
+        providerId: z.ZodString;
+        requestedModel: z.ZodString;
+        responseModel: z.ZodNullable<z.ZodString>;
+        responseRoute: z.ZodNullable<z.ZodString>;
+        outcome: z.ZodEnum<{
+            completed: "completed";
+            failed: "failed";
+        }>;
+        failureKind: z.ZodNullable<z.ZodEnum<{
+            unknown: "unknown";
+            timeout: "timeout";
+            cancelled: "cancelled";
+            quota: "quota";
+            transport: "transport";
+            unavailable: "unavailable";
+            authentication: "authentication";
+            "auth-stale": "auth-stale";
+            protocol: "protocol";
+            "invalid-response": "invalid-response";
+            unsupported: "unsupported";
+        }>>;
+        startedAt: z.ZodString;
+        completedAt: z.ZodString;
+        usage: z.ZodNullable<z.ZodObject<{
+            inputTokens: z.ZodNullable<z.ZodNumber>;
+            cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+            outputTokens: z.ZodNullable<z.ZodNumber>;
+            cacheWriteInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            cacheWrite5mInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            cacheWrite1hInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            reasoningTokens: z.ZodNullable<z.ZodNumber>;
+            source: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const evaluateParamsSchema: z.ZodObject<{
+    caseId: z.ZodString;
+    split: z.ZodEnum<{
+        validation: "validation";
+        train: "train";
+    }>;
+    components: z.ZodRecord<z.ZodString, z.ZodString>;
+    round: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const generateParamsSchema: z.ZodObject<{
+    purpose: z.ZodLiteral<"reflection">;
+    messages: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+        }>;
+        content: z.ZodString;
+    }, z.core.$strict>>;
+    options: z.ZodObject<{
+        responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const requestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"request">;
+    method: z.ZodLiteral<"evaluate">;
+    params: z.ZodObject<{
+        caseId: z.ZodString;
+        split: z.ZodEnum<{
+            validation: "validation";
+            train: "train";
+        }>;
+        components: z.ZodRecord<z.ZodString, z.ZodString>;
+        round: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"request">;
+    method: z.ZodLiteral<"generate">;
+    params: z.ZodObject<{
+        purpose: z.ZodLiteral<"reflection">;
+        messages: z.ZodArray<z.ZodObject<{
+            role: z.ZodEnum<{
+                system: "system";
+                user: "user";
+                assistant: "assistant";
+            }>;
+            content: z.ZodString;
+        }, z.core.$strict>>;
+        options: z.ZodObject<{
+            responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>], "method">;
+export declare const populationRoundSchema: z.ZodObject<{
+    round: z.ZodNumber;
+    parents: z.ZodArray<z.ZodNumber>;
+    kept: z.ZodArray<z.ZodNumber>;
+    variants: z.ZodArray<z.ZodObject<{
+        slot: z.ZodNumber;
+        parent: z.ZodNumber;
+        strategy: z.ZodEnum<{
+            refine: "refine";
+            rewrite: "rewrite";
+        }>;
+        hypothesis: z.ZodString;
+        targetedCriteria: z.ZodArray<z.ZodString>;
+        behavioralChange: z.ZodNullable<z.ZodNumber>;
+        lexicalChange: z.ZodNullable<z.ZodNumber>;
+        status: z.ZodEnum<{
+            rejected: "rejected";
+            accepted: "accepted";
+            empty: "empty";
+        }>;
+        rejectionReason: z.ZodNullable<z.ZodString>;
+        candidateIndex: z.ZodNullable<z.ZodNumber>;
+        attempts: z.ZodArray<z.ZodObject<{
+            behavioralChange: z.ZodNullable<z.ZodNumber>;
+            lexicalChange: z.ZodNullable<z.ZodNumber>;
+            status: z.ZodEnum<{
+                rejected: "rejected";
+                accepted: "accepted";
+            }>;
+            rejectionReason: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const resultSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"result">;
+    components: z.ZodRecord<z.ZodString, z.ZodString>;
+    provenance: z.ZodObject<{
+        optimizer: z.ZodPreprocess<z.ZodEnum<{
+            "training.population": "training.population";
+            "dspy.GEPA": "dspy.GEPA";
+        }>>;
+        dspyVersion: z.ZodLiteral<"3.3.1">;
+        gepaVersion: z.ZodLiteral<"0.1.4">;
+        seed: z.ZodNumber;
+        evaluations: z.ZodNumber;
+        proposals: z.ZodNumber;
+        selectedCandidateIndex: z.ZodNumber;
+        candidates: z.ZodArray<z.ZodObject<{
+            components: z.ZodRecord<z.ZodString, z.ZodString>;
+            parents: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+            validationScore: z.ZodNumber;
+            discoveryEvaluations: z.ZodNumber;
+            perCaseScores: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strict>>;
+        rounds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            round: z.ZodNumber;
+            parents: z.ZodArray<z.ZodNumber>;
+            kept: z.ZodArray<z.ZodNumber>;
+            variants: z.ZodArray<z.ZodObject<{
+                slot: z.ZodNumber;
+                parent: z.ZodNumber;
+                strategy: z.ZodEnum<{
+                    refine: "refine";
+                    rewrite: "rewrite";
+                }>;
+                hypothesis: z.ZodString;
+                targetedCriteria: z.ZodArray<z.ZodString>;
+                behavioralChange: z.ZodNullable<z.ZodNumber>;
+                lexicalChange: z.ZodNullable<z.ZodNumber>;
+                status: z.ZodEnum<{
+                    rejected: "rejected";
+                    accepted: "accepted";
+                    empty: "empty";
+                }>;
+                rejectionReason: z.ZodNullable<z.ZodString>;
+                candidateIndex: z.ZodNullable<z.ZodNumber>;
+                attempts: z.ZodArray<z.ZodObject<{
+                    behavioralChange: z.ZodNullable<z.ZodNumber>;
+                    lexicalChange: z.ZodNullable<z.ZodNumber>;
+                    status: z.ZodEnum<{
+                        rejected: "rejected";
+                        accepted: "accepted";
+                    }>;
+                    rejectionReason: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        stopReason: z.ZodOptional<z.ZodString>;
+        editScope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"whole-file">, z.ZodArray<z.ZodString>]>>>;
+        changeEvidence: z.ZodOptional<z.ZodLiteral<"bridge-reported-v2">>;
+        captures: z.ZodArray<z.ZodObject<{
+            caseId: z.ZodString;
+            split: z.ZodEnum<{
+                validation: "validation";
+                train: "train";
+            }>;
+            captureId: z.ZodString;
+        }, z.core.$strict>>;
+        generations: z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            usage: z.ZodNullable<z.ZodObject<{
+                inputTokens: z.ZodNullable<z.ZodNumber>;
+                cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+                outputTokens: z.ZodNullable<z.ZodNumber>;
+                cacheWriteInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                cacheWrite5mInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                cacheWrite1hInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                reasoningTokens: z.ZodNullable<z.ZodNumber>;
+                source: z.ZodString;
+            }, z.core.$strict>>;
+            modelBasis: z.ZodOptional<z.ZodEnum<{
+                "provider-reported": "provider-reported";
+                "requested-assumption": "requested-assumption";
+            }>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export declare const errorSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>;
+export declare const messageSchema: z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"request">;
+    method: z.ZodLiteral<"evaluate">;
+    params: z.ZodObject<{
+        caseId: z.ZodString;
+        split: z.ZodEnum<{
+            validation: "validation";
+            train: "train";
+        }>;
+        components: z.ZodRecord<z.ZodString, z.ZodString>;
+        round: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"request">;
+    method: z.ZodLiteral<"generate">;
+    params: z.ZodObject<{
+        purpose: z.ZodLiteral<"reflection">;
+        messages: z.ZodArray<z.ZodObject<{
+            role: z.ZodEnum<{
+                system: "system";
+                user: "user";
+                assistant: "assistant";
+            }>;
+            content: z.ZodString;
+        }, z.core.$strict>>;
+        options: z.ZodObject<{
+            responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>], "method">, z.ZodObject<{
+    kind: z.ZodLiteral<"result">;
+    components: z.ZodRecord<z.ZodString, z.ZodString>;
+    provenance: z.ZodObject<{
+        optimizer: z.ZodPreprocess<z.ZodEnum<{
+            "training.population": "training.population";
+            "dspy.GEPA": "dspy.GEPA";
+        }>>;
+        dspyVersion: z.ZodLiteral<"3.3.1">;
+        gepaVersion: z.ZodLiteral<"0.1.4">;
+        seed: z.ZodNumber;
+        evaluations: z.ZodNumber;
+        proposals: z.ZodNumber;
+        selectedCandidateIndex: z.ZodNumber;
+        candidates: z.ZodArray<z.ZodObject<{
+            components: z.ZodRecord<z.ZodString, z.ZodString>;
+            parents: z.ZodArray<z.ZodNullable<z.ZodNumber>>;
+            validationScore: z.ZodNumber;
+            discoveryEvaluations: z.ZodNumber;
+            perCaseScores: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strict>>;
+        rounds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            round: z.ZodNumber;
+            parents: z.ZodArray<z.ZodNumber>;
+            kept: z.ZodArray<z.ZodNumber>;
+            variants: z.ZodArray<z.ZodObject<{
+                slot: z.ZodNumber;
+                parent: z.ZodNumber;
+                strategy: z.ZodEnum<{
+                    refine: "refine";
+                    rewrite: "rewrite";
+                }>;
+                hypothesis: z.ZodString;
+                targetedCriteria: z.ZodArray<z.ZodString>;
+                behavioralChange: z.ZodNullable<z.ZodNumber>;
+                lexicalChange: z.ZodNullable<z.ZodNumber>;
+                status: z.ZodEnum<{
+                    rejected: "rejected";
+                    accepted: "accepted";
+                    empty: "empty";
+                }>;
+                rejectionReason: z.ZodNullable<z.ZodString>;
+                candidateIndex: z.ZodNullable<z.ZodNumber>;
+                attempts: z.ZodArray<z.ZodObject<{
+                    behavioralChange: z.ZodNullable<z.ZodNumber>;
+                    lexicalChange: z.ZodNullable<z.ZodNumber>;
+                    status: z.ZodEnum<{
+                        rejected: "rejected";
+                        accepted: "accepted";
+                    }>;
+                    rejectionReason: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        stopReason: z.ZodOptional<z.ZodString>;
+        editScope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"whole-file">, z.ZodArray<z.ZodString>]>>>;
+        changeEvidence: z.ZodOptional<z.ZodLiteral<"bridge-reported-v2">>;
+        captures: z.ZodArray<z.ZodObject<{
+            caseId: z.ZodString;
+            split: z.ZodEnum<{
+                validation: "validation";
+                train: "train";
+            }>;
+            captureId: z.ZodString;
+        }, z.core.$strict>>;
+        generations: z.ZodArray<z.ZodObject<{
+            model: z.ZodString;
+            usage: z.ZodNullable<z.ZodObject<{
+                inputTokens: z.ZodNullable<z.ZodNumber>;
+                cachedInputTokens: z.ZodNullable<z.ZodNumber>;
+                outputTokens: z.ZodNullable<z.ZodNumber>;
+                cacheWriteInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                cacheWrite5mInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                cacheWrite1hInputTokens: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                reasoningTokens: z.ZodNullable<z.ZodNumber>;
+                source: z.ZodString;
+            }, z.core.$strict>>;
+            modelBasis: z.ZodOptional<z.ZodEnum<{
+                "provider-reported": "provider-reported";
+                "requested-assumption": "requested-assumption";
+            }>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>;
+    schema: z.ZodPreprocess<z.ZodLiteral<"spawnfile.training.dspy.v2">>;
+    id: z.ZodString;
+}, z.core.$strict>]>;
+export type DspyStart = z.infer<typeof startSchema>;
+export type DspyRequest = z.infer<typeof requestSchema>;
+type DspyWireResult = z.infer<typeof resultSchema>;
+/** Trusted host enrichment is added only after validating the unextended bridge result. */
+export type DspyResult = Omit<DspyWireResult, 'provenance'> & {
+    provenance: Omit<DspyWireResult['provenance'], 'generations'> & {
+        generations: Array<DspyWireResult['provenance']['generations'][number] & {
+            attempts?: readonly InferenceAttempt[];
+        }>;
+    };
+};
+export type DspyEvaluation = z.infer<typeof evaluationSchema>;
+export type DspyEvaluateParams = z.infer<typeof evaluateParamsSchema>;
+export type DspyGenerateParams = z.infer<typeof generateParamsSchema>;
+export declare function encodeMessage(value: unknown): string;
+export declare function decodeMessage(line: string): z.infer<typeof messageSchema>;
+export declare function sameComponents(left: Record<string, string>, right: Record<string, string>): boolean;
+export {};

package/dist/training/optimization/protocol.js

@@ -0,0 +1,146 @@
+import { canonicalWireId, compatibleWireLiteral } from '../contracts/index.js';
+import { parseDocument } from 'yaml';
+import { z } from 'zod';
+export const DSPY_SCHEMA = 'spawnfile.training.dspy.v2';
+export const DSPY_FRAME_BYTES = 4 * 1024 * 1024;
+const id = z.string().min(1).max(4096);
+const count = z.number().int().nonnegative();
+const modelBasis = z.enum(['provider-reported', 'requested-assumption']).optional();
+export const componentsSchema = z.record(id, z.string().max(1024 * 1024))
+    .refine((value) => Object.keys(value).length > 0 && Object.keys(value).length <= 64, 'Expected 1–64 components');
+export const budgetSchema = z.object({
+    maxMetricCalls: z.number().int().min(1).max(10000), maxProposals: z.number().int().min(1).max(1000),
+}).strict();
+export const proposalPolicySchema = z.object({
+    strategy: z.enum(['refine', 'rewrite']).optional(), min_change: z.number().min(0).max(1).optional(),
+    max_attempts: z.number().int().min(1).max(5).optional(), history_entries: z.number().int().min(1).max(100).optional(),
+    history_bytes: z.number().int().min(1024).max(262144).optional(),
+}).strict();
+export const searchSchema = z.object({
+    variants: z.number().int().min(1).max(1000), keep: z.number().int().min(1).max(1000),
+    rounds: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER), selection: z.enum(['pareto', 'top-k']).default('pareto'),
+    rewriteShare: z.number().min(0).max(1).default(0.5), minChange: z.number().min(0).max(1).default(0.08),
+    hypothesisSimilarity: z.number().min(0).max(1).default(0.6), patience: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER).optional(),
+    boundaries: z.array(z.string().min(1).max(500)).max(50).default([]),
+}).strict().superRefine((value, context) => {
+    if (value.keep > value.variants)
+        context.addIssue({ code: 'custom', path: ['keep'], message: 'keep must not exceed variants' });
+}).transform(value => ({ ...value, patience: value.patience ?? value.rounds }));
+export const editScopeSchema = z.record(id, z.union([z.literal('whole-file'), z.array(id).min(1)]));
+export const startSchema = z.object({
+    schema: compatibleWireLiteral(DSPY_SCHEMA), kind: z.literal('optimize'), id, components: componentsSchema,
+    trainCaseIds: z.array(id).min(1).max(10000), validationCaseIds: z.array(id).min(1).max(10000),
+    recovery: z.object({ evaluations: count, proposals: count }).strict().optional(),
+    checkpoint: z.object({ directory: id, identity: id, fork: z.object({ directory: id, identity: id, id,
+            digest: z.string().regex(/^sha256:[a-f0-9]{64}$/) }).strict().optional() }).strict().optional(),
+    proposal: proposalPolicySchema.optional(), search: searchSchema.optional(), editScope: editScopeSchema.optional(),
+    concurrency: z.number().int().min(1).max(8).default(1),
+    budget: budgetSchema, seed: z.number().int().min(0).max(2 ** 32 - 1).default(0),
+}).strict().superRefine((value, context) => {
+    const train = new Set(value.trainCaseIds), validation = new Set(value.validationCaseIds);
+    if (train.size !== value.trainCaseIds.length || validation.size !== value.validationCaseIds.length
+        || value.trainCaseIds.some((caseId) => validation.has(caseId))) {
+        context.addIssue({ code: 'custom', message: 'Training and validation IDs must be unique and disjoint' });
+    }
+    if (value.search && value.budget.maxProposals < value.search.keep + value.search.variants) {
+        context.addIssue({ code: 'custom', path: ['budget', 'maxProposals'], message: 'maxProposals must cover keep + variants' });
+    }
+    if (value.search && value.budget.maxMetricCalls < validation.size + train.size) {
+        context.addIssue({ code: 'custom', path: ['budget', 'maxMetricCalls'], message: 'maxMetricCalls must cover seed validation and train cases' });
+    }
+    if (value.editScope && (Object.keys(value.editScope).length !== Object.keys(value.components).length
+        || Object.keys(value.components).some(key => !Object.hasOwn(value.editScope, key)))) {
+        context.addIssue({ code: 'custom', path: ['editScope'], message: 'editScope must describe every editable component' });
+    }
+    if (value.budget.maxMetricCalls < validation.size) {
+        context.addIssue({ code: 'custom', message: 'Budget must cover complete baseline validation' });
+    }
+});
+export const evaluationSchema = z.object({
+    score: z.number().min(0).max(1), feedback: z.string(), output: z.string(), captureId: id,
+}).strict();
+export const usageSchema = z.object({
+    inputTokens: count.nullable(), cachedInputTokens: count.nullable(), outputTokens: count.nullable(),
+    cacheWriteInputTokens: count.nullable().optional(), cacheWrite5mInputTokens: count.nullable().optional(),
+    cacheWrite1hInputTokens: count.nullable().optional(),
+    reasoningTokens: count.nullable(), source: id,
+}).strict().nullable();
+const inferenceAttemptSchema = z.object({
+    id, ordinal: z.number().int().positive(), providerId: id, requestedModel: id,
+    responseModel: id.nullable(), responseRoute: id.nullable(),
+    outcome: z.enum(['completed', 'failed']),
+    failureKind: z.enum(['quota', 'transport', 'unavailable', 'authentication', 'auth-stale', 'protocol', 'invalid-response', 'cancelled', 'timeout', 'unsupported', 'unknown']).nullable(),
+    startedAt: id, completedAt: id, usage: usageSchema,
+}).strict();
+/** Host-only evidence. Attempts never cross the strict Python response protocol. */
+export const inferenceSchema = z.object({ text: z.string().min(1), model: id, usage: usageSchema, route: id, modelBasis,
+    attempts: z.array(inferenceAttemptSchema).optional() }).strict();
+export const evaluateParamsSchema = z.object({
+    caseId: id, split: z.enum(['train', 'validation']), components: componentsSchema,
+    round: count.optional(),
+}).strict();
+export const generateParamsSchema = z.object({
+    purpose: z.literal('reflection'),
+    messages: z.array(z.object({ role: z.enum(['system', 'user', 'assistant']), content: z.string() }).strict()).min(1),
+    options: z.object({ responseSchema: z.record(z.string(), z.unknown()).optional() }).strict(),
+}).strict();
+const common = { schema: compatibleWireLiteral(DSPY_SCHEMA), id };
+export const requestSchema = z.discriminatedUnion('method', [
+    z.object({ ...common, kind: z.literal('request'), method: z.literal('evaluate'), params: evaluateParamsSchema }).strict(),
+    z.object({ ...common, kind: z.literal('request'), method: z.literal('generate'), params: generateParamsSchema }).strict(),
+]);
+const captureSchema = z.object({ caseId: id, split: z.enum(['train', 'validation']), captureId: id }).strict();
+const changeEvidenceSchema = z.object({
+    behavioralChange: z.number().min(0).max(1).nullable(), lexicalChange: z.number().min(0).max(1).nullable(),
+    status: z.enum(['accepted', 'rejected']), rejectionReason: z.string().nullable(),
+}).strict();
+export const populationRoundSchema = z.object({
+    round: count, parents: z.array(count), kept: z.array(count).min(1),
+    variants: z.array(z.object({
+        slot: count, parent: count, strategy: z.enum(['rewrite', 'refine']), hypothesis: z.string(),
+        targetedCriteria: z.array(id), behavioralChange: z.number().min(0).max(1).nullable(),
+        lexicalChange: z.number().min(0).max(1).nullable(), status: z.enum(['accepted', 'rejected', 'empty']),
+        rejectionReason: z.string().nullable(), candidateIndex: count.nullable(), attempts: z.array(changeEvidenceSchema),
+    }).strict()),
+}).strict();
+export const resultSchema = z.object({
+    ...common, kind: z.literal('result'), components: componentsSchema,
+    provenance: z.object({
+        optimizer: z.preprocess(canonicalWireId, z.enum(['dspy.GEPA', 'training.population'])), dspyVersion: z.literal('3.3.1'), gepaVersion: z.literal('0.1.4'),
+        seed: count, evaluations: count, proposals: count, selectedCandidateIndex: count,
+        candidates: z.array(z.object({
+            components: componentsSchema, parents: z.array(count.nullable()).min(1),
+            validationScore: z.number().min(0).max(1), discoveryEvaluations: count,
+            perCaseScores: z.record(id, z.number().min(0).max(1)).optional(),
+        }).strict()).min(1),
+        rounds: z.array(populationRoundSchema).optional(), stopReason: id.optional(), editScope: editScopeSchema.optional(),
+        changeEvidence: z.literal('bridge-reported-v2').optional(),
+        captures: z.array(captureSchema),
+        generations: z.array(z.object({ model: id, usage: usageSchema, modelBasis, text: z.string().optional() }).strict()),
+    }).strict(),
+}).strict();
+export const errorSchema = z.object({ ...common, kind: z.literal('error'),
+    error: z.object({ code: id, message: z.string() }).strict(),
+}).strict();
+export const messageSchema = z.union([requestSchema, resultSchema, errorSchema]);
+export function encodeMessage(value) {
+    const line = `${JSON.stringify(value)}\n`;
+    if (Buffer.byteLength(line) > DSPY_FRAME_BYTES)
+        throw new Error('DSPy JSONL frame exceeds its byte limit');
+    return line;
+}
+export function decodeMessage(line) {
+    if (Buffer.byteLength(line) + 1 > DSPY_FRAME_BYTES)
+        throw new Error('DSPy JSONL frame exceeds its byte limit');
+    const value = JSON.parse(line);
+    // JSON.parse overwrites duplicate keys. The existing YAML parser supplies a
+    // duplicate-key check after JSON syntax has already been required.
+    if (parseDocument(line, { uniqueKeys: true }).errors.length > 0)
+        throw new Error('DSPy JSONL has duplicate or invalid keys');
+    return messageSchema.parse(value);
+}
+export function sameComponents(left, right) {
+    const keys = Object.keys(left);
+    return keys.length === Object.keys(right).length && keys.every((key) => left[key] === right[key]);
+}
+//# sourceMappingURL=protocol.js.map