spawnfile 0.1.25 → 0.1.28

package/dist/training/viewer/projection.js

@@ -0,0 +1,98 @@
+import { compatibleWireLiteral } from '../contracts/index.js';
+import { z } from 'zod';
+import { judgeFailureCauses } from '../contracts/index.js';
+const text = z.string().max(16384);
+const id = text.min(1);
+const count = z.number().int().nonnegative();
+const score = z.number().min(0).max(1).nullable();
+const strings = z.array(id).max(1000);
+const range = z.object({ low: z.number().nonnegative(), high: z.number().nonnegative() })
+    .refine(value => value.high >= value.low, 'Invalid cost range');
+const price = z.object({ checkedAt: text, source: z.url().refine(value => {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !url.username && !url.password;
+    }, 'Price links must use HTTPS without credentials').nullable() }).nullable();
+const costTokens = z.object({ inputTokens: count.nullable(), cachedInputTokens: count.nullable(),
+    cacheWriteInputTokens: count.nullable(), cacheWrite5mInputTokens: count.nullable(), cacheWrite1hInputTokens: count.nullable(),
+    outputTokens: count.nullable(), reasoningTokens: count.nullable(), invalid: z.boolean() }).nullable();
+const costs = z.object({
+    planned: z.object({ total: range.nullable(), knownSubtotal: range, coverage: z.enum(['estimated', 'partial']),
+        lines: z.array(z.object({ role: id, name: text, phase: id, model: text, provider: text.nullable(),
+            plannedCalls: count, amount: range.nullable(), price })).max(1000) }).optional(),
+    observed: z.object({ total: range.nullable(), knownSubtotal: range, completeness: z.enum(['complete', 'incomplete']),
+        usageCoverage: z.enum(['observed-only', 'incomplete']),
+        groups: z.array(z.object({ role: id, name: text, entryCount: count, amount: range.nullable(), knownSubtotal: range })).max(1000),
+        lines: z.array(z.object({ role: id, name: text, model: text.nullable(), requestedModel: text.nullable(),
+            modelBasis: z.enum(['provider-reported', 'requested-assumption', 'unknown']),
+            provider: text.nullable(), route: text.nullable(), outcome: id, usage: costTokens, valuationStatus: id,
+            amount: range.nullable(), price })).max(1000) }).optional(),
+});
+// Closed vocabulary and identities only. The object schema strips what it does not
+// declare, so a prompt, an article, a response body or a grant token has no field
+// to travel in even if a future caller hands one to the projection.
+const judgeFailure = z.object({ cause: z.enum(judgeFailureCauses), judge: id,
+    providerId: id.nullable(), requestedModel: id.nullable(), responseModel: id.nullable(), responseRoute: id.nullable(),
+    kind: z.enum(['quota', 'transport', 'unavailable', 'authentication', 'auth-stale', 'protocol',
+        'invalid-response', 'cancelled', 'timeout', 'unsupported', 'unknown']).optional(),
+    status: z.number().int().positive().max(599).optional() }).strict();
+const check = z.lazy(() => z.object({
+    weight: z.number().finite().nonnegative().optional(), weightedContribution: z.number().min(0).max(1).nullable().optional(),
+    judgeFailure: judgeFailure.optional(),
+    id, label: text, status: z.enum(['pass', 'fail', 'unknown', 'error', 'skipped']), score,
+    evidenceIds: strings, children: z.array(check).max(1000),
+}));
+const schema = z.object({
+    schema: compatibleWireLiteral('spawnfile.training.viewer.v1'),
+    experiment: z.object({ id, title: text, status: id,
+        phase: z.enum(['evaluation', 'train', 'validation', 'final-test', 'replay']), updatedAt: text }),
+    cases: z.array(z.object({ id, split: z.enum(['train', 'validation', 'test']), label: text.optional() })).max(1000),
+    trials: z.array(z.object({
+        id, caseId: id, candidateId: id, status: id, score,
+        coverage: z.array(z.object({ channel: z.enum(['tools', 'output', 'usage']),
+            completeness: z.enum(['complete', 'partial', 'absent']), ordering: z.enum(['source', 'causal', 'none']) })).max(3),
+        checks: z.array(check).max(1000),
+        events: z.array(z.object({ id, type: id, timestamp: text, summary: text })).max(1000),
+    })).max(1000),
+    candidates: z.array(z.object({ id, label: text.optional(), nativeId: id.optional(), parentIds: strings, validationScore: score,
+        discoveryEvaluations: count, editablePaths: strings })).max(1000),
+    usage: z.array(z.object({ purpose: z.enum(['subject', 'optimizer', 'judge', 'embedding']),
+        model: text.nullable(), modelBasis: z.enum(['provider-reported', 'requested-assumption']).optional(), route: text.nullable(), usage: z.object({
+            inputTokens: count.nullable(), cachedInputTokens: count.nullable(), outputTokens: count.nullable(),
+            reasoningTokens: count.nullable(), source: id,
+            cacheWriteInputTokens: count.nullable().optional(), cacheWrite5mInputTokens: count.nullable().optional(),
+            cacheWrite1hInputTokens: count.nullable().optional(),
+        }).nullable() })).max(1000),
+    optimizer: z.object({ name: id, status: id, evaluations: count, proposals: count,
+        maxMetricCalls: count, maxProposals: count, selectedCandidateId: id.optional() }).optional(),
+    heldOut: z.array(z.object({ candidateId: id, meanScore: z.number().min(0).max(1),
+        trialScores: z.array(z.number().min(0).max(1)).max(10000).optional(),
+        standardError: z.number().finite().nonnegative().nullable().optional() })).max(2).optional(),
+    costs: costs.optional(),
+    activity: z.object({ trialId: id, caseId: id, phase: z.enum(['train', 'validation', 'test']), status: id,
+        toolCalls: count, judgeCalls: count, measurements: z.array(z.object({ stageId: id, criterionId: id,
+            kind: z.enum(['criterion', 'gate', 'score']), status: id, score,
+            weight: z.number().finite().nonnegative().optional(), weightedContribution: score.optional(),
+            judgeFailure: judgeFailure.optional() })).max(1000),
+    }).optional(),
+});
+/** Strip undeclared fields, bound check trees and reject invalid projections. */
+export function projectViewerData(input) {
+    if (Buffer.byteLength(JSON.stringify(input)) > 8 * 1024 * 1024)
+        throw new Error('Viewer projection exceeds 8 MiB');
+    const pending = input.trials.flatMap((trial) => trial.checks.map((value) => ({ value, depth: 0 })));
+    let nodes = 0;
+    while (pending.length > 0) {
+        const { value, depth } = pending.pop();
+        if (++nodes > 5000 || depth > 24)
+            throw new Error('Viewer check tree exceeds its display bounds');
+        pending.push(...value.children.map((child) => ({ value: child, depth: depth + 1 })));
+    }
+    const data = schema.parse(input);
+    const candidateIds = new Set(data.candidates.map((candidate) => candidate.id));
+    if (candidateIds.size !== data.candidates.length
+        || data.candidates.some((candidate) => candidate.parentIds.includes(candidate.id))) {
+        throw new Error('Viewer candidate identities must be unique without self-parent relationships');
+    }
+    return data;
+}
+//# sourceMappingURL=projection.js.map

package/dist/training/viewer/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../../../src/training/viewer/projection.ts"],"names":[],"mappings":"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"}

package/dist/training/viewer/server.d.ts

@@ -0,0 +1,3 @@
+import type { ViewerOptions, ViewerServer } from './types.js';
+/** Local presentation. A container-wide bind requires caller-enforced host-loopback publication. */
+export declare function startViewer(options: ViewerOptions): Promise<ViewerServer>;

package/dist/training/viewer/server.js

@@ -0,0 +1,80 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { renderViewer } from './page.js';
+import { projectViewerData } from './projection.js';
+import { streamSnapshots } from './stream.js';
+function respond(response, status, text, type) {
+    if (response.destroyed || response.writableEnded)
+        return;
+    response.writeHead(status, { 'Content-Type': `${type}; charset=utf-8`, 'Content-Length': Buffer.byteLength(text),
+        'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer',
+        'Cross-Origin-Resource-Policy': 'same-origin' });
+    response.end(text);
+}
+/** Local presentation. A container-wide bind requires caller-enforced host-loopback publication. */
+export async function startViewer(options) {
+    const requestedPort = options.port ?? 0;
+    const bindHost = options.bindHost ?? '127.0.0.1';
+    if (!['127.0.0.1', '0.0.0.0'].includes(bindHost))
+        throw new Error('Unsupported viewer bind host');
+    if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535)
+        throw new Error('Viewer port must be 0–65535');
+    let port = 0;
+    const streams = new Map();
+    const server = createServer(async (request, response) => {
+        if (request.headers.host !== `127.0.0.1:${port}`)
+            return respond(response, 403, 'Invalid local host.', 'text/plain');
+        if (request.method !== 'GET') {
+            response.setHeader('Allow', 'GET');
+            return respond(response, 405, 'Read-only viewer: GET required.', 'text/plain');
+        }
+        const metric = /^\/\?metric=(\d{1,4})$/.exec(request.url ?? '');
+        const streamMetric = /^\/api\/events(?:\?metric=(\d{1,4}))?$/.exec(request.url ?? '');
+        if (streamMetric) {
+            if (streams.size >= 16)
+                return respond(response, 503, 'Stream capacity reached.', 'text/plain');
+            const stream = streamSnapshots(response, options.load, () => { streams.delete(response); });
+            streams.set(response, { stream, metric: Number(streamMetric[1] ?? 0) });
+            return;
+        }
+        if (request.url !== '/' && request.url !== '/api/data' && !metric)
+            return respond(response, 404, 'Not found.', 'text/plain');
+        try {
+            const data = projectViewerData(await options.load());
+            if (response.destroyed || response.writableEnded)
+                return;
+            if (request.url === '/api/data')
+                return respond(response, 200, JSON.stringify(data), 'application/json');
+            const nonce = randomBytes(18).toString('hex');
+            response.setHeader('Content-Security-Policy', `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'`);
+            return respond(response, 200, renderViewer(data, nonce, metric ? Number(metric[1]) : 0), 'text/html');
+        }
+        catch {
+            // Loader errors may contain private paths or prompt text. Never serialize them.
+            return respond(response, 503, 'Snapshot unavailable. Refresh to retry.', 'text/plain');
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(requestedPort, bindHost, () => { server.off('error', reject); resolve(); });
+    });
+    // listen completed on an explicit TCP host, so the address is an AddressInfo.
+    port = server.address().port;
+    let closing;
+    return { url: `http://127.0.0.1:${port}`, port, close: (finalSnapshot) => {
+            closing ??= (async () => {
+                const stopped = new Promise(resolve => server.close(() => resolve()));
+                let data;
+                try {
+                    if (finalSnapshot !== undefined)
+                        data = projectViewerData(finalSnapshot);
+                }
+                catch { /* Never expose invalid projections. */ }
+                await Promise.all([...streams.values()].map(({ stream, metric }) => stream.close(data === undefined ? undefined : renderViewer(data, '', metric))));
+                server.closeAllConnections();
+                await stopped;
+            })();
+            return closing;
+        } };
+}
+//# sourceMappingURL=server.js.map

package/dist/training/viewer/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/training/viewer/server.ts"],"names":[],"mappings":"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"}

package/dist/training/viewer/stream.d.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from 'node:http';
+import type { ViewerData } from './types.js';
+export interface SnapshotStream {
+    close(finalHtml?: string): Promise<void>;
+}
+/** Revisions of persisted, phase-filtered snapshots. Never streams raw trial events. */
+export declare function streamSnapshots(response: ServerResponse, load: () => Promise<ViewerData>, closed: () => void): SnapshotStream;

package/dist/training/viewer/stream.js

@@ -0,0 +1,70 @@
+import { createHash } from 'node:crypto';
+import { projectViewerData } from './projection.js';
+/** Revisions of persisted, phase-filtered snapshots. Never streams raw trial events. */
+export function streamSnapshots(response, load, closed) {
+    response.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff', 'Cross-Origin-Resource-Policy': 'same-origin', Connection: 'close' });
+    response.flushHeaders();
+    let ended = false, revision = '';
+    let closing;
+    let timer;
+    response.once('close', () => { ended = true; clearTimeout(timer); closed(); });
+    response.once('error', () => response.destroy());
+    const send = (text) => {
+        if (ended || response.writableEnded || response.destroyed)
+            return;
+        // A slow reader reconnects to the newest snapshot; never queue unbounded history.
+        try {
+            if (!response.write(text))
+                response.destroy();
+        }
+        catch {
+            response.destroy();
+        }
+    };
+    const tick = async () => {
+        if (ended || response.writableEnded || response.destroyed)
+            return;
+        try {
+            const data = projectViewerData(await load());
+            const next = createHash('sha256').update(JSON.stringify(data)).digest('hex');
+            if (ended)
+                return;
+            if (next !== revision) {
+                revision = next;
+                send(`event: snapshot\ndata: ${JSON.stringify({ revision })}\n\n`);
+            }
+            else
+                send(': heartbeat\n\n');
+        }
+        catch {
+            send('event: unavailable\ndata: {}\n\n');
+        }
+        if (!ended && !response.writableEnded && !response.destroyed)
+            timer = setTimeout(() => { void tick(); }, 1000);
+    };
+    void tick();
+    return { close(finalHtml) {
+            if (closing)
+                return closing;
+            ended = true;
+            clearTimeout(timer);
+            closing = new Promise(resolve => {
+                if (response.destroyed) {
+                    resolve();
+                    return;
+                }
+                // This is an I/O deadline, not a grace sleep: normal readers close immediately.
+                const deadline = setTimeout(() => response.destroy(), 1000);
+                response.once('close', () => { clearTimeout(deadline); resolve(); });
+                try {
+                    response.end(`event: final\ndata: ${JSON.stringify({ html: finalHtml ?? null })}\n\n`);
+                }
+                catch {
+                    response.destroy();
+                }
+            });
+            return closing;
+        } };
+}
+//# sourceMappingURL=stream.js.map

package/dist/training/viewer/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/training/viewer/stream.ts"],"names":[],"mappings":"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"}

package/dist/training/viewer/types.d.ts

@@ -0,0 +1,172 @@
+import type { InferenceModelBasis, JudgeFailure, ObservationCoverage, Usage } from '../contracts/index.js';
+/** A caller-filtered presentation projection. Never pass raw captures or prompts. */
+export interface ViewerData {
+    schema: 'spawnfile.training.viewer.v1';
+    experiment: {
+        id: string;
+        title: string;
+        status: string;
+        phase: 'evaluation' | 'train' | 'validation' | 'final-test' | 'replay';
+        updatedAt: string;
+    };
+    cases: {
+        id: string;
+        split: 'train' | 'validation' | 'test';
+        label?: string;
+    }[];
+    trials: {
+        id: string;
+        caseId: string;
+        candidateId: string;
+        status: string;
+        score: number | null;
+        coverage: ObservationCoverage[];
+        checks: ViewerCheck[];
+        events: ViewerEvent[];
+    }[];
+    candidates: {
+        id: string;
+        /** Explicit authored arm name; absent for historical optimizer candidates. */
+        label?: string;
+        /** Native content identity; distinct GEPA discoveries may use identical bytes. */
+        nativeId?: string;
+        parentIds: string[];
+        validationScore: number | null;
+        discoveryEvaluations: number;
+        editablePaths: string[];
+    }[];
+    usage: ViewerUsage[];
+    costs?: ViewerCosts;
+    activity?: ViewerActivity;
+    heldOut?: {
+        candidateId: string;
+        meanScore: number;
+        trialScores?: number[];
+        standardError?: number | null;
+    }[];
+    optimizer?: {
+        name: string;
+        status: string;
+        evaluations: number;
+        proposals: number;
+        maxMetricCalls: number;
+        maxProposals: number;
+        selectedCandidateId?: string;
+    };
+}
+export interface ViewerActivity {
+    trialId: string;
+    caseId: string;
+    phase: 'train' | 'validation' | 'test';
+    status: string;
+    toolCalls: number;
+    judgeCalls: number;
+    measurements: {
+        stageId: string;
+        criterionId: string;
+        kind: 'criterion' | 'gate' | 'score';
+        status: string;
+        score: number | null;
+        weight?: number;
+        weightedContribution?: number | null;
+        judgeFailure?: JudgeFailure;
+    }[];
+}
+export interface ViewerCheck {
+    weight?: number;
+    weightedContribution?: number | null;
+    /** Why an errored judge produced no score, as a closed vocabulary. Absent on every other verdict. */
+    judgeFailure?: JudgeFailure;
+    id: string;
+    label: string;
+    status: 'pass' | 'fail' | 'unknown' | 'error' | 'skipped';
+    score: number | null;
+    evidenceIds: string[];
+    children: ViewerCheck[];
+}
+export interface ViewerEvent {
+    id: string;
+    type: string;
+    timestamp: string;
+    summary: string;
+}
+export interface ViewerUsage {
+    purpose: 'subject' | 'optimizer' | 'judge' | 'embedding';
+    model: string | null;
+    modelBasis?: InferenceModelBasis;
+    route: string | null;
+    usage: Usage | null;
+}
+export interface ViewerCostRange {
+    low: number;
+    high: number;
+}
+export interface ViewerPriceSource {
+    checkedAt: string;
+    source: string | null;
+}
+export interface ViewerCostTokens {
+    inputTokens: number | null;
+    cachedInputTokens: number | null;
+    cacheWriteInputTokens: number | null;
+    cacheWrite5mInputTokens: number | null;
+    cacheWrite1hInputTokens: number | null;
+    outputTokens: number | null;
+    reasoningTokens: number | null;
+    invalid: boolean;
+}
+export interface ViewerCosts {
+    planned?: {
+        total: ViewerCostRange | null;
+        knownSubtotal: ViewerCostRange;
+        coverage: 'estimated' | 'partial';
+        lines: {
+            role: string;
+            name: string;
+            phase: string;
+            model: string;
+            provider: string | null;
+            plannedCalls: number;
+            amount: ViewerCostRange | null;
+            price: ViewerPriceSource | null;
+        }[];
+    };
+    observed?: {
+        total: ViewerCostRange | null;
+        knownSubtotal: ViewerCostRange;
+        completeness: 'complete' | 'incomplete';
+        usageCoverage: 'observed-only' | 'incomplete';
+        groups: {
+            role: string;
+            name: string;
+            entryCount: number;
+            amount: ViewerCostRange | null;
+            knownSubtotal: ViewerCostRange;
+        }[];
+        lines: {
+            role: string;
+            name: string;
+            model: string | null;
+            requestedModel: string | null;
+            modelBasis: 'provider-reported' | 'requested-assumption' | 'unknown';
+            provider: string | null;
+            route: string | null;
+            outcome: string;
+            usage: ViewerCostTokens | null;
+            valuationStatus: string;
+            amount: ViewerCostRange | null;
+            price: ViewerPriceSource | null;
+        }[];
+    };
+}
+export interface ViewerOptions {
+    load: () => Promise<ViewerData>;
+    port?: number;
+    /** Explicit container listener only; caller must publish on host loopback. */
+    bindHost?: '127.0.0.1' | '0.0.0.0';
+}
+export interface ViewerServer {
+    url: string;
+    port: number;
+    close(finalSnapshot?: ViewerData): Promise<void>;
+}

package/dist/training/viewer/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/training/viewer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/training/viewer/types.ts"],"names":[],"mappings":""}

package/examples/training/AGENTS.md

@@ -0,0 +1,19 @@
+# Authoring Examples
+
+Owns readable integration examples used to refine Spawnfile training's YAML authoring surface.
+These are draft YAML/native declarations with Markdown explanations, separate from
+implemented task corpora in evals/.
+
+- Group examples by project or coherent scenario family, with one overview README.
+- Keep one README with native source/environment files and inline-record datasets
+  in adjacent evals/. Spawnfile examples include the proposed .spawnignore policy.
+  Do not require agent/runtime/experiment YAML or case-per-file layouts. Reference
+  external project inputs; do not copy private corpora, credentials or runtime state.
+- Mark proposed fields and missing fixtures explicitly. YAML syntax acceptance is
+  not schema validation, adapter support or evidence of a successful agent run.
+- Keep each document focused and under 400 lines. Add nested guides and CLAUDE.md
+  symlinks as responsibilities grow; inherit the root development rules.
+- Verify relative Markdown links, YAML syntax and existing source references.
+- Example YAML and native declarations are authorized; product implementation stays
+  paused until authoring approval. Do not mount evaluator-facing examples, rubrics
+  or held-out answers into subject workspaces.

package/examples/training/fixed-questions/AGENTS.md

@@ -0,0 +1,7 @@
+# Fixed-question example
+
+Owns a generic, evaluator-only fixed-question grader and its dataset example.
+Public seam: README.md and evals/. No private data, provider calls or subject
+runtime implementation belongs here. Keep grounding and expected answers outside
+subject workspaces. Verify through the case/CLI grader tests, strict dataset
+resolution and TypeScript/lint checks; live model quality is not established.

package/examples/training/fixed-questions/README.md

@@ -0,0 +1,19 @@
+# Fixed reader questions
+
+`evals/delivery.spawnfile-training.yaml` shows mechanical code checks, fixed decision-model
+questions and the existing LLM rubric in one record. `item.grader.yaml` contains
+six human-authored questions. Each additional case selects its own frozen grader
+file through record.checks and supplies its own record.context.grounding.
+
+The YAML resolves with a host-declared `prose` judge route. A native integration
+must collect the actual `article.json` artifact and supply the public task inputs;
+this directory does not implement a native runtime or a delivery task environment.
+The article JSON must contain a `body` string or array of paragraph strings.
+
+Grounding, questions and expected answers are evaluator-only. Do not mount them
+into the subject workspace; the prompt here is illustrative. TypeSafe is explicitly
+API billed, with a declared cap and operator-managed authentication. No live calls
+or model-quality acceptance are claimed by this example.
+
+See [the fixed-question contract](../../docs/fixed-questions.md) for exact semantics,
+private-hook requirements, offline grading and deterministic-check limitations.

package/examples/training/fixed-questions/evals/AGENTS.md

@@ -0,0 +1,7 @@
+# Fixed-question datasets
+
+Owns inline synthetic records illustrating all three evaluator families.
+Public seam: *.spawnfile-training.yaml. No credentials, native runtime dependencies or
+production data. Resolve through the public case loader with an explicit judge
+route; never give grader files or record context to the subject. Validate this
+example in the adjacent case/CLI tests, not by invoking a live model.

package/examples/training/fixed-questions/evals/delivery.spawnfile-training.yaml

@@ -0,0 +1,33 @@
+schema: spawnfile.training.dataset.v1
+id: fixed-delivery
+records:
+  - id: item
+    input: { prompt: Write a short delivery notice from the supplied public task materials. }
+    outputs: { article: article.json }
+    context:
+      grounding: >-
+        A delivery of 10 items to the community library is planned for Monday.
+        Total price: USD 25. The delivery has not arrived.
+    checks:
+      - id: length
+        eval: word-count
+        input: artifact:article#/body
+        ignore: ['\[E\d+\]']
+        min: 15
+        max: 100
+      - id: values
+        eval: values-in-source
+        input: artifact:article#/body
+        source: context:grounding
+        ignore: ['\[E\d+\]']
+      - id: reader
+        eval: grader
+        grader: item.grader.yaml
+        input: artifact:article
+        context: { grounding: 'context:grounding' }
+      - id: clarity
+        eval: llm-rubric
+        input: artifact:article#/body
+        judge: prose
+        rubric: { prompt: Assess clarity and readability; quote the article as evidence. }
+        minimum: 0.7

package/examples/training/fixed-questions/evals/item.grader.yaml

@@ -0,0 +1,41 @@
+schema: spawnfile.training.grader.v1
+id: item-reader
+calibration: identity
+context:
+  grounding: { description: Frozen human-authored facts for this case }
+model: { backend: typesafe, name: jev-1.13.0 }
+max_spend_usd: 0.50
+questions:
+  - id: quantity
+    type: yes-no
+    ask: Does the article tell the reader that the delivery contains 10 items?
+    expected: 'yes'
+    weight: 2
+    reads: [context.grounding, output.body]
+  - id: price
+    type: yes-no
+    ask: Does the article tell the reader the total price is USD 25?
+    expected: 'yes'
+    reads: [context.grounding, output.body]
+  - id: recipient
+    type: yes-no
+    ask: Does the article identify the recipient as the community library?
+    expected: 'yes'
+    reads: [context.grounding, output.body]
+  - id: delivered
+    type: yes-no
+    ask: Does the article say the delivery has already arrived?
+    expected: 'no'
+    reads: [context.grounding, output.body]
+  - id: timing
+    type: yes-no
+    ask: Does the article explain that delivery is planned for Monday?
+    expected: 'yes'
+    reads: [context.grounding, output.body]
+  - id: supported
+    type: yes-no
+    ask: Are all factual assertions in the article supported by the grounding?
+    expected: 'yes'
+    weight: 2
+    reads: [context.grounding, output.body]
+score: { method: weighted, pass_at: 0.8 }

package/examples/training/native-formatting/AGENTS.md

@@ -0,0 +1,10 @@
+# Native Formatting Acceptance
+
+Owns a minimal native instruction-optimization example, its two adjacent datasets,
+and measured-use documentation. Keep fixture truth outside subject workspaces.
+Only PROMPT.md is editable; SOUL.md is locked. This example demonstrates formatting
+and adapter parity, not production newsroom or memory parity. Native receipts live
+under ignored .runtime/native-training-proof/. Use public Training module APIs.
+
+Validate both datasets with the strict resolver and matching shared plan; native
+completion, exact outputs, usage and unchanged source hashes are separate evidence.

package/examples/training/native-formatting/PROMPT.md

@@ -0,0 +1,4 @@
+# Response policy
+
+When the user supplies `Token: VALUE`, return VALUE exactly as written.
+Return only that token, without explanation, quotes or Markdown.