@marinoscar/kvox-eval 0.0.0-bootstrap → 0.1.0-next.0

package/dist/parity/index.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeParitySnapshot = exports.paritySnapshotPath = exports.loadParitySnapshot = exports.PARITY_SNAPSHOT_DIR = exports.PARITY_ASK_SNAPSHOT = exports.goldExtractionAnswer = exports.createParityScript = exports.runParityScenario = exports.PARITY_QUESTIONS = exports.PARITY_FIXTURES = exports.parityTaskModelSource = exports.parityModelState = exports.PARITY_USER_ID = exports.PARITY_TASK_MODELS = exports.PARITY_PROVIDER = exports.PARITY_MODELS = exports.PARITY_DEFAULT_MODEL = exports.PARITY_DEFAULT_EFFORT = void 0;
+/**
+ * `@marinoscar/kvox-eval/parity`: the harness-parity scenario.
+ *
+ * @remarks
+ * For the same input, two bindings of the model port (the web edition's, KVox
+ * Desktop's) must build byte-identical provider requests: system prompt, user
+ * prompt or input, JSON Schema, tool definitions, model, reasoning effort and output
+ * ceiling. `runParityScenario` drives the product's own notes, extraction,
+ * adjudication and Ask code through a port; the committed snapshots
+ * (`parity/requests.*.json`) are what each binding's recording must equal.
+ *
+ * @packageDocumentation
+ */
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "PARITY_DEFAULT_EFFORT", { enumerable: true, get: function () { return constants_js_1.PARITY_DEFAULT_EFFORT; } });
+Object.defineProperty(exports, "PARITY_DEFAULT_MODEL", { enumerable: true, get: function () { return constants_js_1.PARITY_DEFAULT_MODEL; } });
+Object.defineProperty(exports, "PARITY_MODELS", { enumerable: true, get: function () { return constants_js_1.PARITY_MODELS; } });
+Object.defineProperty(exports, "PARITY_PROVIDER", { enumerable: true, get: function () { return constants_js_1.PARITY_PROVIDER; } });
+Object.defineProperty(exports, "PARITY_TASK_MODELS", { enumerable: true, get: function () { return constants_js_1.PARITY_TASK_MODELS; } });
+Object.defineProperty(exports, "PARITY_USER_ID", { enumerable: true, get: function () { return constants_js_1.PARITY_USER_ID; } });
+Object.defineProperty(exports, "parityModelState", { enumerable: true, get: function () { return constants_js_1.parityModelState; } });
+Object.defineProperty(exports, "parityTaskModelSource", { enumerable: true, get: function () { return constants_js_1.parityTaskModelSource; } });
+var scenario_js_1 = require("./scenario.js");
+Object.defineProperty(exports, "PARITY_FIXTURES", { enumerable: true, get: function () { return scenario_js_1.PARITY_FIXTURES; } });
+Object.defineProperty(exports, "PARITY_QUESTIONS", { enumerable: true, get: function () { return scenario_js_1.PARITY_QUESTIONS; } });
+Object.defineProperty(exports, "runParityScenario", { enumerable: true, get: function () { return scenario_js_1.runParityScenario; } });
+var script_js_1 = require("./script.js");
+Object.defineProperty(exports, "createParityScript", { enumerable: true, get: function () { return script_js_1.createParityScript; } });
+Object.defineProperty(exports, "goldExtractionAnswer", { enumerable: true, get: function () { return script_js_1.goldExtractionAnswer; } });
+var snapshot_js_1 = require("./snapshot.js");
+Object.defineProperty(exports, "PARITY_ASK_SNAPSHOT", { enumerable: true, get: function () { return snapshot_js_1.PARITY_ASK_SNAPSHOT; } });
+Object.defineProperty(exports, "PARITY_SNAPSHOT_DIR", { enumerable: true, get: function () { return snapshot_js_1.PARITY_SNAPSHOT_DIR; } });
+Object.defineProperty(exports, "loadParitySnapshot", { enumerable: true, get: function () { return snapshot_js_1.loadParitySnapshot; } });
+Object.defineProperty(exports, "paritySnapshotPath", { enumerable: true, get: function () { return snapshot_js_1.paritySnapshotPath; } });
+Object.defineProperty(exports, "writeParitySnapshot", { enumerable: true, get: function () { return snapshot_js_1.writeParitySnapshot; } });

package/dist/parity/internals.d.ts

@@ -0,0 +1,8 @@
+import { internals as extractionInternals } from '@marinoscar/kvox-api/graph-extraction/testing';
+import { internals as askInternals } from '@marinoscar/kvox-api/ask/testing';
+export declare const buildExtractionContext: typeof extractionInternals.buildExtractionContext;
+export type ExtractionContext = extractionInternals.ExtractionContext;
+export declare const AskRespondHandler: typeof askInternals.AskRespondHandler, AskToolset: typeof askInternals.AskToolset, EntityBriefTool: typeof askInternals.EntityBriefTool, EvidenceTool: typeof askInternals.EvidenceTool, GetEntityTool: typeof askInternals.GetEntityTool, ListCommitmentsTool: typeof askInternals.ListCommitmentsTool, NeighborsTool: typeof askInternals.NeighborsTool, SearchTool: typeof askInternals.SearchTool, TimelineTool: typeof askInternals.TimelineTool;
+export type AskToolContext = askInternals.AskToolContext;
+export type HandleRegistry = InstanceType<typeof askInternals.HandleRegistry>;
+export declare const HandleRegistryClass: typeof askInternals.HandleRegistry;

package/dist/parity/internals.js

@@ -0,0 +1,16 @@
+"use strict";
+// =============================================================================
+// The slices' internals the parity scenario runs (issue #580)
+// =============================================================================
+//
+// Same rule as `kg/internals.ts`: the one place this slice names a function that
+// `@marinoscar/kvox-api` keeps internal (tagged `@internal`, no stability
+// promise). NOT EXPORTED from the package.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandleRegistryClass = exports.TimelineTool = exports.SearchTool = exports.NeighborsTool = exports.ListCommitmentsTool = exports.GetEntityTool = exports.EvidenceTool = exports.EntityBriefTool = exports.AskToolset = exports.AskRespondHandler = exports.buildExtractionContext = void 0;
+const testing_1 = require("@marinoscar/kvox-api/graph-extraction/testing");
+const testing_2 = require("@marinoscar/kvox-api/ask/testing");
+exports.buildExtractionContext = testing_1.internals.buildExtractionContext;
+exports.AskRespondHandler = testing_2.internals.AskRespondHandler, exports.AskToolset = testing_2.internals.AskToolset, exports.EntityBriefTool = testing_2.internals.EntityBriefTool, exports.EvidenceTool = testing_2.internals.EvidenceTool, exports.GetEntityTool = testing_2.internals.GetEntityTool, exports.ListCommitmentsTool = testing_2.internals.ListCommitmentsTool, exports.NeighborsTool = testing_2.internals.NeighborsTool, exports.SearchTool = testing_2.internals.SearchTool, exports.TimelineTool = testing_2.internals.TimelineTool;
+exports.HandleRegistryClass = testing_2.internals.HandleRegistry;

package/dist/parity/scenario.d.ts

@@ -0,0 +1,45 @@
+import type { KvoxAiPort } from '@marinoscar/kvox-api/ports';
+import type { ParityScript } from './script.js';
+/**
+ * The golden meetings the scenario covers by default.
+ *
+ * @stability experimental
+ */
+export declare const PARITY_FIXTURES: readonly string[];
+/**
+ * The Ask questions (ids in `ask-questions.json`) the scenario asks by default.
+ *
+ * @stability experimental
+ */
+export declare const PARITY_QUESTIONS: readonly string[];
+/**
+ * What {@link runParityScenario} covers.
+ *
+ * @stability experimental
+ */
+export interface ParityScenarioOptions {
+    /** Golden meeting ids to run notes, extraction and adjudication for. Default {@link PARITY_FIXTURES}; `[]` runs none. */
+    fixtures?: string[];
+    /** Ask question ids to ask. Default {@link PARITY_QUESTIONS}; `[]` asks none. */
+    questions?: string[];
+    /** The scripted provider to tell which meeting is current (it answers extraction from that meeting's labels). */
+    script?: Pick<ParityScript, 'focus'>;
+}
+/**
+ * Drives the product's own harness through `ai`: the calls notes generation, entity
+ * extraction, adjudication and the Ask loop make, for the golden meetings and Ask
+ * questions chosen. Call it once per binding with the SAME scripted provider under
+ * the binding, record what reaches the provider, and compare.
+ *
+ * @example
+ * ```ts
+ * const script = createParityScript();
+ * await runParityScenario(ai, { fixtures: ['m01'], questions: [], script });
+ * ```
+ *
+ * @param ai - the port under test (`createKvoxAi`, or a host's wrapper of it).
+ * @param opts - which meetings and questions.
+ * @throws when a stage cannot complete (a scripted answer failed validation): the scenario must run end to end, or a request could be missing from the comparison.
+ * @stability experimental
+ */
+export declare function runParityScenario(ai: KvoxAiPort, opts?: ParityScenarioOptions): Promise<void>;

package/dist/parity/scenario.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARITY_QUESTIONS = exports.PARITY_FIXTURES = void 0;
+exports.runParityScenario = runParityScenario;
+const ontology_1 = require("@marinoscar/kvox-contract/ontology");
+const core_1 = require("@marinoscar/kvox-api/core");
+const graph_1 = require("@marinoscar/kvox-api/graph");
+const graph_extraction_1 = require("@marinoscar/kvox-api/graph-extraction");
+const ask_1 = require("@marinoscar/kvox-api/ask");
+const testing_1 = require("@marinoscar/kvox-api/ask/testing");
+const templates_1 = require("@marinoscar/kvox-api/notes/templates");
+const notes_1 = require("@marinoscar/kvox-api/notes");
+const index_js_1 = require("../fixtures/index.js");
+const index_js_2 = require("../kg/index.js");
+const constants_js_1 = require("./constants.js");
+const internals_js_1 = require("./internals.js");
+// =============================================================================
+// The parity scenario: the real harness, driven through the model port (issue #580, part 2)
+// =============================================================================
+//
+// `runParityScenario(ai)` makes, through whatever `KvoxAiPort` it is handed, the
+// calls the product makes for ten golden meetings and three Ask questions:
+//
+//   notes.generate    the notes slice's own prompt builder (`assemblePrompt`) over a
+//                     built-in template and the meeting's transcript, sized with the
+//                     slice's own budget (`budgetFromTarget`), then `generateText`.
+//   graph.extract     the evaluation's own extraction call (`runExtraction`: the
+//                     graph-extraction slice's prompt, output schema and validator).
+//   graph.adjudicate  the graph-extraction slice's own `AdjudicationService`, over
+//                     pairs built from the extracted entities and the known ones.
+//   ask.respond       the Ask slice's own `AskRespondHandler`, with its real toolset
+//                     definitions, over the in-memory Ask tables and a stub tool run.
+//
+// Nothing here copies a prompt, a schema or a parser (ADR-0001): every one of them is
+// the package's. What differs between hosts is only the port, and that is the point.
+// =============================================================================
+/**
+ * The golden meetings the scenario covers by default.
+ *
+ * @stability experimental
+ */
+exports.PARITY_FIXTURES = Object.freeze(['m01', 'm02', 'm03', 'm04', 'm05', 'm06', 'm07', 'm08', 'm09', 'm10']);
+/**
+ * The Ask questions (ids in `ask-questions.json`) the scenario asks by default.
+ *
+ * @stability experimental
+ */
+exports.PARITY_QUESTIONS = Object.freeze(['q01', 'q02', 'q03']);
+/** The text of a transcript as a note source: one line per merged speaker turn, with its start time. */
+function transcriptText(fixture) {
+    const speakerName = new Map(fixture.speakers.map((s) => [s.id, s.displayName ?? s.label]));
+    const lines = [];
+    let last = null;
+    for (const segment of fixture.segments) {
+        const seconds = Math.floor(segment.startMs / 1000);
+        const stamp = `${String(Math.floor(seconds / 60)).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`;
+        if (segment.speakerId === last && lines.length > 0) {
+            lines[lines.length - 1] += ` ${segment.text}`;
+        }
+        else {
+            lines.push(`[${stamp}] ${speakerName.get(segment.speakerId) ?? 'Unknown speaker'}: ${segment.text}`);
+            last = segment.speakerId;
+        }
+    }
+    return lines.join('\n');
+}
+/** `notes.generate`: assemble, size, stream. */
+async function runNotes(ai, fixture) {
+    const ctx = { userId: constants_js_1.PARITY_USER_ID, orgId: null, feature: notes_1.NOTE_GENERATE_AI_FEATURE };
+    const target = await ai.resolveTask(ctx, notes_1.NOTE_GENERATE_AI_FEATURE);
+    const template = templates_1.NOTE_BUILTIN_TEMPLATES[0];
+    const prompt = (0, notes_1.assemblePrompt)({
+        templateInstructions: template.instructions,
+        templateOutputFormat: template.outputFormat,
+        templateBodyFormat: template.bodyFormat,
+        templateStructure: [...template.structure],
+        templateTone: template.tone,
+        templateLength: template.length,
+        contextText: fixture.contextText,
+        sourceText: transcriptText(fixture),
+    });
+    const budget = (0, notes_1.budgetFromTarget)(target, { maxInputTokens: null, maxOutputTokens: null });
+    if (budget === null)
+        throw new Error('The parity model reports no context window.');
+    const promptTokens = ai.countTokens(target, `${prompt.systemPrompt}\n${prompt.userContent}`);
+    let text = '';
+    for await (const event of ai.generateText(ctx, {
+        target,
+        system: prompt.systemPrompt,
+        user: prompt.userContent,
+        maxOutputTokens: (0, core_1.outputTokensForPrompt)(budget, promptTokens),
+    })) {
+        if (event.type === 'delta')
+            text += event.text;
+    }
+    if (text.length === 0)
+        throw new Error(`The scripted note for ${fixture.id} came back empty.`);
+}
+/** `graph.extract`: the evaluation's extraction call, on the model the task resolves to. */
+async function runExtract(ai, fixture) {
+    const target = await ai.resolveTask({ userId: constants_js_1.PARITY_USER_ID, orgId: null, feature: 'graph.extract' }, 'graph.extract');
+    const extracted = await (0, index_js_2.runExtraction)(ai, fixture, { model: target.model, provider: target.provider });
+    if (extracted === null)
+        throw new Error(`The scripted extraction for ${fixture.id} failed validation.`);
+    return extracted;
+}
+/** `graph.adjudicate`: the real service, over pairs of one extracted mention and one known entity of its type. */
+async function runAdjudicate(ai, fixture, rows) {
+    const known = fixture.knownEntities;
+    const pairs = [];
+    for (const row of rows) {
+        if (row.kind !== 'entity' || row.payload.ref === 'meeting')
+            continue;
+        const candidate = known.find((k) => k.type === row.payload.type && k.label !== row.payload.label);
+        if (candidate === undefined)
+            continue;
+        pairs.push({
+            pairId: `p${pairs.length + 1}`,
+            type: row.payload.type,
+            mention: {
+                label: row.payload.label,
+                aliases: row.payload.aliases,
+                props: {},
+                quotes: row.evidence.map((e) => e.quote),
+            },
+            candidate: {
+                entityId: candidate.id,
+                label: candidate.label,
+                aliases: candidate.aliases,
+                props: candidate.props,
+                quotes: [],
+                neighbourhood: fixture.knownRelations
+                    .filter((r) => r.from === candidate.id || r.to === candidate.id)
+                    .map((r) => `${r.type} ${r.from === candidate.id ? '→' : '←'} ${known.find((k) => k.id === (r.from === candidate.id ? r.to : r.from))?.label ?? 'unknown'}`),
+            },
+        });
+        if (pairs.length === 4)
+            break;
+    }
+    if (pairs.length === 0)
+        throw new Error(`${fixture.id} has no extracted entity with a same-type known entity to adjudicate.`);
+    const settings = {
+        readSystem: async () => ({ value: { graphEnabled: true, maxInputTokens: null, maxOutputTokens: null, reasoningEffort: constants_js_1.PARITY_DEFAULT_EFFORT }, version: 1 }),
+    };
+    const ontology = { effectiveSchemaFor: async () => (0, ontology_1.computeEffectiveSchema)({ enabledDomains: (0, index_js_1.fixtureDomains)(fixture), userAttributes: [] }) };
+    const service = new graph_extraction_1.AdjudicationService(undefined, new graph_1.GraphAiRunResolver(ai, settings), ai, ontology);
+    const verdicts = await service.adjudicate(constants_js_1.PARITY_USER_ID, pairs, { jobType: 'kg.resolve', jobId: 'parity-job' });
+    if (verdicts.size !== pairs.length)
+        throw new Error(`Expected ${pairs.length} adjudication verdicts, got ${verdicts.size}.`);
+}
+/** A dependency the tool never reaches: only a tool's definition is read, never its `run`. */
+const NONE = undefined;
+/** The real tool definitions, with a tool run that finds one entity. */
+function parityToolset() {
+    const real = new internals_js_1.AskToolset(new internals_js_1.SearchTool(NONE, NONE, NONE, NONE), new internals_js_1.GetEntityTool(NONE, NONE, NONE), new internals_js_1.NeighborsTool(NONE, NONE), new internals_js_1.TimelineTool(NONE, NONE), new internals_js_1.EvidenceTool(NONE, NONE), new internals_js_1.EntityBriefTool(NONE, NONE), new internals_js_1.ListCommitmentsTool(NONE), NONE);
+    return {
+        definitions: () => real.definitions(),
+        createContext: async (user, opts = {}) => ({
+            user,
+            handles: new internals_js_1.HandleRegistryClass(),
+            personalFactsAllowed: false,
+            scopeEntityId: opts.scopeEntityId ?? null,
+            now: opts.now ?? new Date(0),
+        }),
+        execute: async (ctx) => {
+            ctx.handles.register({ kind: 'ent', id: '55555555-5555-4555-8555-555555555555', label: 'Parity Entity' });
+            return {
+                ok: true,
+                result: { data: { entities: [] }, resultCount: 1, summary: 'Found 1 thing', truncated: false },
+                json: '{"entities":[{"ref":"ent1","label":"Parity Entity"}],"truncated":false}',
+            };
+        },
+    };
+}
+/** `ask.respond`: the real handler over the in-memory tables, for one question. */
+async function runAsk(ai, question) {
+    const mem = (0, testing_1.createInMemoryAskDb)();
+    const conversation = mem.addConversation({ ownerId: constants_js_1.PARITY_USER_ID });
+    mem.addMessage({ conversationId: conversation.id, role: 'user', content: question });
+    const assistant = mem.addMessage({ conversationId: conversation.id, role: 'assistant' });
+    const settings = {
+        readSystem: async () => ({ value: { graphEnabled: true, maxInputTokens: null, maxOutputTokens: null, reasoningEffort: constants_js_1.PARITY_DEFAULT_EFFORT }, version: 1 }),
+    };
+    const visibility = {
+        viewerFor: async (userId) => ({ userId }),
+        transcriptVisibleSql: () => core_1.Prisma.sql `true`,
+        run: (_viewer, fn) => fn(mem.db),
+    };
+    const handler = new internals_js_1.AskRespondHandler({ registerHandler: () => undefined }, mem.db, ai, { hasPermission: async () => true, authenticate: async () => null }, new graph_1.GraphAiRunResolver(ai, settings), parityToolset(), visibility, (0, ask_1.resolveAskOptions)());
+    // The system prompt carries today's date: a fixed clock keeps the request reproducible.
+    handler.clock = () => Date.UTC(2026, 8, 26, 12, 0, 0);
+    const payload = {
+        assistantMessageId: assistant.id,
+        conversationId: conversation.id,
+        userId: constants_js_1.PARITY_USER_ID,
+        model: 'gpt-parity-agent',
+        providerId: 'openai',
+        reasoningEffort: 'low',
+    };
+    const job = { id: 'parity-job', type: ask_1.ASK_RESPOND_JOB_TYPE, subjectType: 'ask_message', subjectId: assistant.id, payload, attempts: 0, orgId: null };
+    await handler.process(job);
+    const row = mem.messages.get(assistant.id);
+    if (row?.status !== 'complete')
+        throw new Error(`The Ask turn ended ${row?.status ?? 'missing'}: ${row?.errorClass ?? ''}`);
+    if (!Array.isArray(row.toolCalls) || row.toolCalls.length === 0)
+        throw new Error('The Ask turn called no tool.');
+}
+/**
+ * Drives the product's own harness through `ai`: the calls notes generation, entity
+ * extraction, adjudication and the Ask loop make, for the golden meetings and Ask
+ * questions chosen. Call it once per binding with the SAME scripted provider under
+ * the binding, record what reaches the provider, and compare.
+ *
+ * @example
+ * ```ts
+ * const script = createParityScript();
+ * await runParityScenario(ai, { fixtures: ['m01'], questions: [], script });
+ * ```
+ *
+ * @param ai - the port under test (`createKvoxAi`, or a host's wrapper of it).
+ * @param opts - which meetings and questions.
+ * @throws when a stage cannot complete (a scripted answer failed validation): the scenario must run end to end, or a request could be missing from the comparison.
+ * @stability experimental
+ */
+async function runParityScenario(ai, opts = {}) {
+    const ids = opts.fixtures ?? [...exports.PARITY_FIXTURES];
+    const meetings = ids.length > 0 ? (0, index_js_1.loadGoldenMeetings)(ids) : [];
+    for (const fixture of meetings) {
+        opts.script?.focus(fixture.id);
+        await runNotes(ai, fixture);
+        const extracted = await runExtract(ai, fixture);
+        await runAdjudicate(ai, fixture, extracted.rows);
+    }
+    opts.script?.focus(null);
+    const wanted = opts.questions ?? [...exports.PARITY_QUESTIONS];
+    if (wanted.length > 0) {
+        const questions = (0, index_js_1.loadGoldenAskQuestions)();
+        for (const id of wanted) {
+            const question = questions.find((q) => q.id === id);
+            if (question === undefined)
+                throw new Error(`Unknown Ask question id ${id}.`);
+            await runAsk(ai, question.question);
+        }
+    }
+}

package/dist/parity/script.d.ts

@@ -0,0 +1,44 @@
+import { type RecordingScript } from '@marinoscar/kvox-ai/testing';
+import { type GoldenFixture } from '../fixtures/index.js';
+import { type ExtractionContext } from './internals.js';
+/**
+ * The scripted provider: a `RecordingScript` (of `@marinoscar/kvox-ai/testing`) that also needs to know which golden meeting the scenario is on.
+ *
+ * @stability experimental
+ */
+export interface ParityScript extends Required<Pick<RecordingScript, 'stream' | 'create'>> {
+    /** The call id of the Ask tool call the script makes. */
+    readonly toolCallId: string;
+    /**
+     * Tells the script which meeting the scenario is on; its extraction answer is that meeting's gold labels.
+     *
+     * @param fixtureId - a golden meeting id, or `null` between meetings (the Ask questions).
+     */
+    focus(fixtureId: string | null): void;
+}
+/**
+ * The raw extraction answer a model that read the meeting perfectly would give: the
+ * fixture's gold entities, relations and items, with the prompt's own `s#`, `N` and
+ * `k#` ids. The Meeting entity and ATTENDED relations are the product's deterministic
+ * rows, never the model's, so they are left out.
+ *
+ * @param fixture - the golden meeting.
+ * @param ctx - the extraction context the prompt was built from.
+ * @returns the answer in the extraction output schema's shape.
+ * @stability experimental
+ */
+export declare function goldExtractionAnswer(fixture: GoldenFixture, ctx: ExtractionContext): Record<string, unknown>;
+/**
+ * Builds the scripted provider.
+ *
+ * @example
+ * ```ts
+ * const script = createParityScript();
+ * const adapter = createRecordingAdapter(script);
+ * await runParityScenario(ai, { fixtures: ['m01'], questions: [], script });
+ * ```
+ *
+ * @returns the script.
+ * @stability experimental
+ */
+export declare function createParityScript(): ParityScript;

package/dist/parity/script.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.goldExtractionAnswer = goldExtractionAnswer;
+exports.createParityScript = createParityScript;
+const testing_1 = require("@marinoscar/kvox-ai/testing");
+const index_js_1 = require("../fixtures/index.js");
+const internals_js_1 = require("./internals.js");
+const index_js_2 = require("../kg/index.js");
+/** The id of the one tool call the script makes. */
+const TOOL_CALL_ID = 'call_parity_1';
+/** The empty extraction answer. */
+const EMPTY_ANSWER = { meeting: { topics: [] }, entities: [], relations: [], items: [] };
+/**
+ * The raw extraction answer a model that read the meeting perfectly would give: the
+ * fixture's gold entities, relations and items, with the prompt's own `s#`, `N` and
+ * `k#` ids. The Meeting entity and ATTENDED relations are the product's deterministic
+ * rows, never the model's, so they are left out.
+ *
+ * @param fixture - the golden meeting.
+ * @param ctx - the extraction context the prompt was built from.
+ * @returns the answer in the extraction output schema's shape.
+ * @stability experimental
+ */
+function goldExtractionAnswer(fixture, ctx) {
+    const aliasOfSegment = new Map(ctx.segments.map((s) => [s.segmentId, s.alias]));
+    const aliasOfKnown = new Map(ctx.knownEntities.map((k) => [k.id, k.alias]));
+    const refOf = new Map(fixture.labels.entities.map((e) => [e.key, e.existingId !== null && aliasOfKnown.has(e.existingId) ? aliasOfKnown.get(e.existingId) : e.key]));
+    refOf.set('meeting', 'meeting');
+    const end = (key) => (key === null ? null : (refOf.get(key) ?? key));
+    const cites = (evidence) => evidence.map((e) => ({ source: e.source === 'segment' ? (aliasOfSegment.get(e.segmentId) ?? 'N') : 'N', quote: e.quote }));
+    return {
+        meeting: { topics: [fixture.title] },
+        entities: fixture.labels.entities
+            .filter((e) => e.type !== 'Meeting')
+            .map((e) => ({ ref: refOf.get(e.key), type: e.type, label: e.label, aliases: [...e.aliases], props: e.props, evidence: cites(e.evidence) })),
+        relations: fixture.labels.relations
+            .filter((r) => r.type !== 'ATTENDED')
+            .map((r) => ({
+            type: r.type,
+            from: end(r.from),
+            to: end(r.to),
+            props: r.props,
+            validFrom: r.validFrom,
+            validTo: r.validTo,
+            precision: r.precision,
+            evidence: cites(r.evidence),
+        })),
+        items: fixture.labels.items.map((i) => ({
+            kind: i.kind,
+            title: i.title,
+            statement: i.statement,
+            subject: end(i.subject),
+            owner: end(i.owner),
+            counterparty: end(i.counterparty),
+            status: i.status,
+            occurredAt: i.occurredAt,
+            dueAt: i.dueAt,
+            validFrom: null,
+            validTo: null,
+            precision: 'unknown',
+            sensitivity: i.sensitivity,
+            props: {},
+            evidence: cites(i.evidence),
+        })),
+    };
+}
+/** The text of the last user message of an Ask request. */
+function lastUserText(req) {
+    if (typeof req.input === 'string')
+        return req.input;
+    for (let i = req.input.length - 1; i >= 0; i -= 1) {
+        const item = req.input[i];
+        if (item.type === 'message' && item.role === 'user') {
+            return item.content.map((part) => ('text' in part ? String(part.text) : '')).join('');
+        }
+    }
+    return '';
+}
+/**
+ * Builds the scripted provider.
+ *
+ * @example
+ * ```ts
+ * const script = createParityScript();
+ * const adapter = createRecordingAdapter(script);
+ * await runParityScenario(ai, { fixtures: ['m01'], questions: [], script });
+ * ```
+ *
+ * @returns the script.
+ * @stability experimental
+ */
+function createParityScript() {
+    const fixtures = new Map();
+    let focused = null;
+    const extractionAnswer = () => {
+        if (focused === null)
+            return EMPTY_ANSWER;
+        if (!fixtures.has(focused))
+            for (const f of (0, index_js_1.loadGoldenMeetings)([focused]))
+                fixtures.set(f.id, f);
+        const fixture = fixtures.get(focused);
+        return goldExtractionAnswer(fixture, (0, internals_js_1.buildExtractionContext)((0, index_js_2.fixtureToInput)(fixture)));
+    };
+    return {
+        toolCallId: TOOL_CALL_ID,
+        focus(fixtureId) {
+            focused = fixtureId;
+        },
+        create(req) {
+            const name = req.structuredOutput?.name;
+            let parsed = { ok: true };
+            if (name === 'kg_extraction') {
+                parsed = extractionAnswer();
+            }
+            else if (name === 'kg_adjudication') {
+                const text = typeof req.input === 'string' ? req.input : '';
+                const ids = [...text.matchAll(/^## Pair (p\d+)/gm)].map((m) => m[1]);
+                const verdicts = ['same', 'different', 'uncertain'];
+                parsed = { verdicts: ids.map((pairId, i) => ({ pairId, verdict: verdicts[i % verdicts.length], rationale: `Parity verdict for ${pairId}.` })) };
+            }
+            return { parsed, outputText: JSON.stringify(parsed) };
+        },
+        stream(req) {
+            if (req.tools === undefined || req.tools.length === 0) {
+                return (0, testing_1.textAnswer)(`Parity note for ${focused ?? 'no meeting'}.\n\n- Everything said was written down once.`);
+            }
+            const hasResult = typeof req.input !== 'string' && req.input.some((item) => item.type === 'function_call_output');
+            if (!hasResult) {
+                const query = lastUserText(req).slice(0, 200) || 'parity';
+                const item = { type: 'function_call', callId: TOOL_CALL_ID, name: 'search', arguments: JSON.stringify({ query }) };
+                return [(0, testing_1.functionCallEvent)(item.callId, item.name, item.arguments), (0, testing_1.completedEvent)({ output: [item], finishReason: 'tool_calls' })];
+            }
+            return (0, testing_1.textAnswer)('The graph answers this directly and the search found it.[^ent1] That is the whole of what the parity script says.');
+        },
+    };
+}

package/dist/parity/snapshot.d.ts

@@ -0,0 +1,43 @@
+import type { RecordedProviderRequest } from '@marinoscar/kvox-ai/testing';
+/**
+ * The directory of the committed snapshots (`parity/` of the package).
+ *
+ * @stability experimental
+ */
+export declare const PARITY_SNAPSHOT_DIR: string;
+/**
+ * The name of the Ask snapshot, beside the fixture ids (`m01`...).
+ *
+ * @stability experimental
+ */
+export declare const PARITY_ASK_SNAPSHOT = "ask";
+/**
+ * The path of one snapshot file.
+ *
+ * @param name - a fixture id (`m01`) or {@link PARITY_ASK_SNAPSHOT}.
+ * @returns the absolute path of `requests.<name>.json`.
+ * @stability experimental
+ */
+export declare function paritySnapshotPath(name: string): string;
+/**
+ * Reads one committed snapshot: the provider-level requests a binding must build, in call order.
+ *
+ * @example
+ * ```ts
+ * expect(recorded).toEqual(loadParitySnapshot('m01'));
+ * ```
+ *
+ * @param name - a fixture id (`m01`) or {@link PARITY_ASK_SNAPSHOT}.
+ * @returns the records.
+ * @throws when the file is missing (run the direct spec with `KVOX_EVAL_UPDATE_PARITY=1` to write it).
+ * @stability experimental
+ */
+export declare function loadParitySnapshot(name: string): RecordedProviderRequest[];
+/**
+ * Writes one snapshot (the direct spec does, when `KVOX_EVAL_UPDATE_PARITY=1`).
+ *
+ * @param name - a fixture id (`m01`) or {@link PARITY_ASK_SNAPSHOT}.
+ * @param records - the provider-level records, normalized.
+ * @stability experimental
+ */
+export declare function writeParitySnapshot(name: string, records: readonly RecordedProviderRequest[]): void;

package/dist/parity/snapshot.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARITY_ASK_SNAPSHOT = exports.PARITY_SNAPSHOT_DIR = void 0;
+exports.paritySnapshotPath = paritySnapshotPath;
+exports.loadParitySnapshot = loadParitySnapshot;
+exports.writeParitySnapshot = writeParitySnapshot;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// =============================================================================
+// The committed request snapshots (issue #580, part 2)
+// =============================================================================
+//
+// `parity/requests.<fixture>.json` (one per golden meeting) and
+// `parity/requests.ask.json`, at the package root, shipped in `files`. They are the
+// single source of truth for "what the harness sends": the direct binding's spec
+// here, the web binding's spec in `apps/api`, and the Desktop repository's own
+// binding all compare against the same files.
+// =============================================================================
+/** `src/parity` and `dist/parity` both sit two levels below the package root. */
+const PACKAGE_ROOT = (0, node_path_1.resolve)(__dirname, '..', '..');
+/**
+ * The directory of the committed snapshots (`parity/` of the package).
+ *
+ * @stability experimental
+ */
+exports.PARITY_SNAPSHOT_DIR = (0, node_path_1.join)(PACKAGE_ROOT, 'parity');
+/**
+ * The name of the Ask snapshot, beside the fixture ids (`m01`...).
+ *
+ * @stability experimental
+ */
+exports.PARITY_ASK_SNAPSHOT = 'ask';
+/**
+ * The path of one snapshot file.
+ *
+ * @param name - a fixture id (`m01`) or {@link PARITY_ASK_SNAPSHOT}.
+ * @returns the absolute path of `requests.<name>.json`.
+ * @stability experimental
+ */
+function paritySnapshotPath(name) {
+    if (!/^[a-z0-9]+$/i.test(name))
+        throw new Error(`Not a parity snapshot name: ${JSON.stringify(name)}`);
+    return (0, node_path_1.join)(exports.PARITY_SNAPSHOT_DIR, `requests.${name}.json`);
+}
+/**
+ * Reads one committed snapshot: the provider-level requests a binding must build, in call order.
+ *
+ * @example
+ * ```ts
+ * expect(recorded).toEqual(loadParitySnapshot('m01'));
+ * ```
+ *
+ * @param name - a fixture id (`m01`) or {@link PARITY_ASK_SNAPSHOT}.
+ * @returns the records.
+ * @throws when the file is missing (run the direct spec with `KVOX_EVAL_UPDATE_PARITY=1` to write it).
+ * @stability experimental
+ */
+function loadParitySnapshot(name) {
+    return JSON.parse((0, node_fs_1.readFileSync)(paritySnapshotPath(name), 'utf8'));
+}
+/**
+ * Writes one snapshot (the direct spec does, when `KVOX_EVAL_UPDATE_PARITY=1`).
+ *
+ * @param name - a fixture id (`m01`) or {@link PARITY_ASK_SNAPSHOT}.
+ * @param records - the provider-level records, normalized.
+ * @stability experimental
+ */
+function writeParitySnapshot(name, records) {
+    (0, node_fs_1.mkdirSync)(exports.PARITY_SNAPSHOT_DIR, { recursive: true });
+    (0, node_fs_1.writeFileSync)(paritySnapshotPath(name), `${JSON.stringify(records, null, 2)}\n`, 'utf8');
+}

package/dist/real-data/index.d.ts

@@ -0,0 +1,2 @@
+export { assertOutsideRepo, canonicalPath, isInside, nextRealFixtureId, REAL_DATA_REFUSAL, RealDataPathError, repositoryRoots, } from './real-data.js';
+export type { AssertOutsideRepoOptions } from './real-data.js';