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

package/dist/kg/run-kg-eval.d.ts

@@ -0,0 +1,77 @@
+import type { KvoxAiPort } from '@marinoscar/kvox-api/ports';
+import { type KgEvalPrediction } from './prediction-schema.js';
+import { type KgEvalReport } from './report.js';
+/**
+ * What {@link runKgEval} is asked to do.
+ *
+ * @stability experimental
+ */
+export interface RunKgEvalOptions {
+    /**
+     * Where predictions come from: `gold` (the default when no `predictionsDir` is
+     * given), or a registered live runner (`extract`, `extract-resolve` /
+     * `extract+resolve`, or a test's own), which needs `ai` and `model`.
+     */
+    runner?: string;
+    /** Score the prediction files of this directory instead of running anything. */
+    predictionsDir?: string;
+    /** The model port a live runner calls. Never needed for `gold` or `predictionsDir`. */
+    ai?: KvoxAiPort;
+    /** The model a live runner targets (required for one). */
+    model?: string;
+    /** The provider a live runner targets. Default `openai`. */
+    provider?: string;
+    /** Fixture ids to keep (`--only`); omitted or empty keeps all. */
+    fixtures?: readonly string[];
+    /** A tag every kept fixture carries (`--tag`). */
+    tag?: string;
+    /** Throw {@link KgEvalTargetsError} when a §6 target fails. Default `false` (report only). */
+    enforce?: boolean;
+    /** The directory the golden set is read from. Default the committed synthetic set. */
+    fixturesDir?: string;
+    /** Called with every prediction a live runner produced, in fixture order (the CLI writes it to `--out`). */
+    onPrediction?: (fixtureId: string, prediction: KgEvalPrediction) => void | Promise<void>;
+    /** Called for every fixture a `predictionsDir` has no file for (scored as empty). */
+    onMissingPrediction?: (fixtureId: string, dir: string) => void;
+}
+/**
+ * A run asked to enforce the §6 targets missed one. Carries the full report.
+ *
+ * @stability experimental
+ */
+export declare class KgEvalTargetsError extends Error {
+    readonly report: KgEvalReport;
+    /**
+     * @param report - the run's report (`targetsMet` is `false`).
+     */
+    constructor(report: KgEvalReport);
+}
+/**
+ * A run that cannot start: no runner of that name, a live runner without a model
+ * or a port, both a runner and a predictions directory, an empty selection. The
+ * CLI maps it to exit code 2.
+ *
+ * @stability experimental
+ */
+export declare class KgEvalUsageError extends Error {
+}
+/**
+ * Runs one knowledge-graph evaluation and returns its report.
+ *
+ * @example
+ * ```ts
+ * const report = await runKgEval({ runner: 'gold' });
+ * report.targetsMet; // true: the self-test scores 1.000 everywhere
+ *
+ * const live = await runKgEval({ runner: 'extract', ai, model: 'gpt-5-mini', fixtures: ['m01'] });
+ * ```
+ *
+ * @param opts - what to score and how.
+ * @returns the report (`formatReport` prints it).
+ * @throws {@link KgEvalUsageError} for a run that cannot start; `KgEvalLoadError`
+ *   for a golden set or prediction file that does not load; {@link KgEvalTargetsError}
+ *   with `enforce` when a target fails. A live call's failure is the port's
+ *   `KvoxAiError`, which carries no key.
+ * @stability experimental
+ */
+export declare function runKgEval(opts?: RunKgEvalOptions): Promise<KgEvalReport>;

package/dist/kg/run-kg-eval.js

@@ -0,0 +1,137 @@
+"use strict";
+// =============================================================================
+// runKgEval: one knowledge-graph evaluation run, start to report (issue #580)
+// =============================================================================
+//
+// The one code path behind `kvox-eval kg`, `npm run kg:eval` and a host that
+// calls the package directly. Three ways to get the predictions it scores:
+//
+//   gold             synthesised from the labels (`goldPrediction`): the
+//                    harness's self-test, 1.000 everywhere or a bug;
+//   predictionsDir   `<dir>/<fixtureId>.json` written by an earlier run (a
+//                    missing file is scored as empty, and reported);
+//   a live runner    `extract` / `extract+resolve` over the `ai` port, one
+//                    structured call per fixture.
+//
+// PURE OF ENVIRONMENT: nothing here reads `process.env`, prints, or writes a
+// file. A live run is handed a `KvoxAiPort` (the CLI builds one with
+// `createLiveKvoxAi`, which owns the key); the hooks tell the caller about each
+// prediction and each missing file, so the CLI can persist and print them.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KgEvalUsageError = exports.KgEvalTargetsError = void 0;
+exports.runKgEval = runKgEval;
+const index_js_1 = require("../fixtures/index.js");
+const gold_runner_js_1 = require("./gold-runner.js");
+const prediction_schema_js_1 = require("./prediction-schema.js");
+const predictions_js_1 = require("./predictions.js");
+const report_js_1 = require("./report.js");
+const runner_js_1 = require("./runner.js");
+const scorer_js_1 = require("./scorer.js");
+/**
+ * A run asked to enforce the §6 targets missed one. Carries the full report.
+ *
+ * @stability experimental
+ */
+class KgEvalTargetsError extends Error {
+    report;
+    /**
+     * @param report - the run's report (`targetsMet` is `false`).
+     */
+    constructor(report) {
+        super('one or more §6 targets failed (--enforce)');
+        this.report = report;
+    }
+}
+exports.KgEvalTargetsError = KgEvalTargetsError;
+/**
+ * A run that cannot start: no runner of that name, a live runner without a model
+ * or a port, both a runner and a predictions directory, an empty selection. The
+ * CLI maps it to exit code 2.
+ *
+ * @stability experimental
+ */
+class KgEvalUsageError extends Error {
+}
+exports.KgEvalUsageError = KgEvalUsageError;
+/**
+ * Runs one knowledge-graph evaluation and returns its report.
+ *
+ * @example
+ * ```ts
+ * const report = await runKgEval({ runner: 'gold' });
+ * report.targetsMet; // true: the self-test scores 1.000 everywhere
+ *
+ * const live = await runKgEval({ runner: 'extract', ai, model: 'gpt-5-mini', fixtures: ['m01'] });
+ * ```
+ *
+ * @param opts - what to score and how.
+ * @returns the report (`formatReport` prints it).
+ * @throws {@link KgEvalUsageError} for a run that cannot start; `KgEvalLoadError`
+ *   for a golden set or prediction file that does not load; {@link KgEvalTargetsError}
+ *   with `enforce` when a target fails. A live call's failure is the port's
+ *   `KvoxAiError`, which carries no key.
+ * @stability experimental
+ */
+async function runKgEval(opts = {}) {
+    const predictionsDir = opts.predictionsDir;
+    const runnerArg = opts.runner ?? (predictionsDir === undefined ? 'gold' : undefined);
+    if (predictionsDir !== undefined && runnerArg !== undefined) {
+        throw new KgEvalUsageError('pass either a predictions directory or a runner, not both');
+    }
+    // An unregistered runner is reported before anything is loaded.
+    const live = runnerArg !== undefined && runnerArg !== 'gold' ? (0, runner_js_1.findKgEvalRunner)(runnerArg) : null;
+    if (runnerArg !== undefined && runnerArg !== 'gold' && live === null) {
+        throw new KgEvalUsageError(`no runner '${runnerArg}' registered (known: ${Object.keys(runner_js_1.KG_EVAL_RUNNERS).join(', ')})`);
+    }
+    if (live !== null && !opts.model)
+        throw new KgEvalUsageError(`the '${live.name}' runner needs a model`);
+    if (live !== null && opts.ai === undefined)
+        throw new KgEvalUsageError(`the '${live.name}' runner needs a model port (ai)`);
+    const fixtures = selectedFixtures(opts);
+    const predictions = new Map();
+    let runnerLabel;
+    let model = null;
+    if (live !== null) {
+        model = opts.model;
+        const runner = await live.factory({ ai: opts.ai });
+        runnerLabel = runner.name;
+        for (const fixture of fixtures) {
+            const pred = prediction_schema_js_1.kgEvalPredictionSchema.parse(await runner.run(fixture, { model, ...(opts.provider !== undefined ? { provider: opts.provider } : {}) }));
+            predictions.set(fixture.id, pred);
+            await opts.onPrediction?.(fixture.id, pred);
+        }
+    }
+    else if (predictionsDir === undefined) {
+        runnerLabel = 'gold';
+        for (const f of fixtures)
+            predictions.set(f.id, (0, gold_runner_js_1.goldPrediction)(f));
+    }
+    else {
+        runnerLabel = 'predictions';
+        for (const f of fixtures) {
+            const pred = (0, predictions_js_1.loadPredictionFile)(predictionsDir, f.id);
+            if (pred === null)
+                opts.onMissingPrediction?.(f.id, predictionsDir);
+            predictions.set(f.id, pred ?? (0, prediction_schema_js_1.emptyPrediction)(f.id));
+            model ??= pred?.model ?? null;
+        }
+    }
+    const report = (0, report_js_1.buildReport)((0, scorer_js_1.scoreRun)(fixtures, predictions), {
+        runner: runnerLabel,
+        model,
+        fixtureIds: fixtures.map((f) => f.id),
+    });
+    if (opts.enforce && !report.targetsMet)
+        throw new KgEvalTargetsError(report);
+    return report;
+}
+/** The golden set narrowed by `fixtures` and `tag`; an empty selection is a usage error. */
+function selectedFixtures(opts) {
+    const all = (0, index_js_1.loadGoldenSet)(opts.fixturesDir ?? index_js_1.GOLDEN_MEETINGS_DIR);
+    const only = opts.fixtures && opts.fixtures.length > 0 ? [...opts.fixtures] : null;
+    const selected = (0, index_js_1.selectFixtures)(all, only, opts.tag ?? null);
+    if (selected.length === 0)
+        throw new KgEvalUsageError('no fixtures selected');
+    return selected;
+}

package/dist/kg/runner.d.ts

@@ -0,0 +1,72 @@
+import type { KvoxAiPort } from '@marinoscar/kvox-api/ports';
+import type { GoldenFixture } from '../fixtures/index.js';
+import type { KgEvalPrediction } from './prediction-schema.js';
+/**
+ * What one live run is made with.
+ *
+ * @stability experimental
+ */
+export interface KgEvalRunOptions {
+    /** The provider's model id. */
+    model: string;
+    /** The provider id the call targets (`openai`, `openai-compatible`). Default `openai`. */
+    provider?: string;
+}
+/**
+ * What a runner factory is handed.
+ *
+ * @stability experimental
+ */
+export interface KgEvalRunnerDeps {
+    /** The model port every structured call goes through. */
+    ai: KvoxAiPort;
+}
+/**
+ * Turns one golden fixture into one prediction.
+ *
+ * @extensionPoint
+ * @stability experimental
+ */
+export interface KgEvalRunner {
+    /** `extract` (#363), `extract+resolve` (#364): the report's `runner` column. */
+    readonly name: string;
+    /**
+     * One fixture's prediction.
+     *
+     * @param fixture - the fixture.
+     * @param opts - the model (and provider) to run on.
+     * @returns the prediction (it carries `model`, never a key).
+     */
+    run(fixture: GoldenFixture, opts: KgEvalRunOptions): Promise<KgEvalPrediction>;
+}
+/**
+ * A lazy runner factory.
+ *
+ * @stability experimental
+ */
+export type KgEvalRunnerFactory = (deps: KgEvalRunnerDeps) => Promise<KgEvalRunner>;
+/**
+ * The registered runners, by name. Lazy factories, so a `--predictions` run never
+ * loads the extraction code. A test may add an entry (and delete it afterwards).
+ *
+ * @stability experimental
+ */
+export declare const KG_EVAL_RUNNERS: Record<string, KgEvalRunnerFactory>;
+/**
+ * Spellings a command line accepts for a registered runner (`extract-resolve`,
+ * a shell-friendly `extract+resolve`).
+ *
+ * @stability experimental
+ */
+export declare const KG_EVAL_RUNNER_ALIASES: Readonly<Record<string, string>>;
+/**
+ * The registered runner a name (or an alias) means, or `null`.
+ *
+ * @param name - a runner name or alias.
+ * @returns the factory and the registered name, or `null` when none is registered.
+ * @stability experimental
+ */
+export declare function findKgEvalRunner(name: string): {
+    name: string;
+    factory: KgEvalRunnerFactory;
+} | null;

package/dist/kg/runner.js

@@ -0,0 +1,51 @@
+"use strict";
+// =============================================================================
+// The kg:eval runner seam (issue #362; #580 moved it onto the model port).
+//
+// A runner turns one fixture into one prediction. The extraction runner
+// (`extract`) is kg.extract's own pipeline (#363); resolution extends it
+// (`extract+resolve`, #364). A runner registers itself by adding an entry below
+// from its own file (`kg/runners/*.ts`) — a lazy factory, so a `--predictions`
+// run never loads the extraction code.
+//
+// #580: a runner is built over a `KvoxAiPort` (`createKvoxAi` of
+// `@marinoscar/kvox-ai`, or a fake in a test) and never sees a key. Whoever
+// builds the port owns the key (`live/`: the environment, never a flag); a
+// prediction carries `model` alone.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KG_EVAL_RUNNER_ALIASES = exports.KG_EVAL_RUNNERS = void 0;
+exports.findKgEvalRunner = findKgEvalRunner;
+/**
+ * The registered runners, by name. Lazy factories, so a `--predictions` run never
+ * loads the extraction code. A test may add an entry (and delete it afterwards).
+ *
+ * @stability experimental
+ */
+exports.KG_EVAL_RUNNERS = {
+    // `require`, not `import()`: under NodeNext a dynamic import stays a native
+    // ESM import, which cannot load a `.ts` file through ts-node or ts-jest.
+    extract: async (deps) => require('./runners/extract-runner.js').createExtractRunner(deps),
+    // #364: extraction, then in-memory resolution against `knownEntities`.
+    'extract+resolve': async (deps) => require('./runners/extract-resolve-runner.js').createExtractResolveRunner(deps),
+};
+/**
+ * Spellings a command line accepts for a registered runner (`extract-resolve`,
+ * a shell-friendly `extract+resolve`).
+ *
+ * @stability experimental
+ */
+exports.KG_EVAL_RUNNER_ALIASES = Object.freeze({ 'extract-resolve': 'extract+resolve' });
+/**
+ * The registered runner a name (or an alias) means, or `null`.
+ *
+ * @param name - a runner name or alias.
+ * @returns the factory and the registered name, or `null` when none is registered.
+ * @stability experimental
+ */
+function findKgEvalRunner(name) {
+    const registered = Object.prototype.hasOwnProperty.call(exports.KG_EVAL_RUNNER_ALIASES, name) ? exports.KG_EVAL_RUNNER_ALIASES[name] : name;
+    if (!Object.prototype.hasOwnProperty.call(exports.KG_EVAL_RUNNERS, registered))
+        return null;
+    return { name: registered, factory: exports.KG_EVAL_RUNNERS[registered] };
+}

package/dist/kg/runners/extract-resolve-runner.d.ts

@@ -0,0 +1,40 @@
+import type { ProposedRow } from '../internals.js';
+import { type GraphPreferences } from '@marinoscar/kvox-api/graph';
+import type { GoldenFixture } from '../../fixtures/index.js';
+import type { KgEvalRunner, KgEvalRunnerDeps } from '../runner.js';
+/**
+ * `pg_trgm`'s `similarity(a, b)`: shared trigrams over the union.
+ *
+ * @stability experimental
+ */
+export declare function trigramSimilarity(a: string, b: string): number;
+/**
+ * PURE. Resolve every proposed entity row (in place, on copies) against the
+ * fixture's known entities. The Meeting row and anything without a type match
+ * keep what extraction decided.
+  *
+  * @stability experimental
+ */
+export declare function resolveRowsInMemory(fixture: GoldenFixture, rows: readonly ProposedRow[], prefs?: GraphPreferences): ProposedRow[];
+/**
+ * PURE. #365's relation dedup and closing plan, in memory, against the
+ * fixture's prior edges: `known` rows flagged (and so pre-accepted), `overlaps`
+ * / `unordered` copied from #353's plan, and closings counted.
+  *
+  * @stability experimental
+ */
+export declare function applyDedupStagesInMemory(fixture: GoldenFixture, rows: readonly ProposedRow[]): {
+    rows: ProposedRow[];
+    stats: {
+        known: number;
+        closings: number;
+        overlaps: number;
+        unordered: number;
+    };
+};
+/**
+ * The `extract+resolve` runner over `deps.ai`.
+ *
+ * @stability experimental
+ */
+export declare function createExtractResolveRunner(deps: KgEvalRunnerDeps): KgEvalRunner;

package/dist/kg/runners/extract-resolve-runner.js

@@ -0,0 +1,199 @@
+"use strict";
+// =============================================================================
+// The `extract+resolve` kg:eval runner (#364; docs/specs/ontology.md §6, §7)
+// =============================================================================
+//
+// `extract` (#363), then resolution of every proposed entity against the
+// fixture's `knownEntities` — so auto-link PRECISION is measured, the number
+// that gates any future lowering of the 0.90 default (#362's target).
+//
+// NO DATABASE: an in-memory implementation of the candidate arms feeds the
+// production `score.ts` and `decide()`:
+//
+//   A  exact — `normalizeAlias` (#355) over label + aliases, as in SQL
+//   B  trigram — a JS port of `pg_trgm`'s `similarity()` (lowercased words,
+//      padded "  w ", trigram-set Jaccard), threshold 0.4
+//   C  vector — skipped (no embeddings in an eval run)
+//
+// Context: `sameMeeting` for a known Person a fixture speaker is identified as
+// (what #356 produces); the speaker shortcut links such a Person outright, as
+// production does. Adjudication is OFF — the eval measures the deterministic
+// bands; a middle-band row is `possible_duplicate` and never pre-checked.
+//
+// #365: after resolution, the pure cores of `work-item-dedup` (relations) and
+// `temporal-closing` run against the fixture's `knownRelations` through #353's
+// planner, so a restated edge is `known`, an overlap is flagged and a closing
+// is counted (`stats.closings`) exactly as production would propose them.
+// Item dedup needs an embedding and an adjudication call, neither of which an
+// eval run makes; it is covered by the stage's own tests instead.
+//
+// ⚠ The runner never sees a key: the port it is handed owns it (#580).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trigramSimilarity = trigramSimilarity;
+exports.resolveRowsInMemory = resolveRowsInMemory;
+exports.applyDedupStagesInMemory = applyDedupStagesInMemory;
+exports.createExtractResolveRunner = createExtractResolveRunner;
+const internals_js_1 = require("../internals.js");
+const ontology_1 = require("@marinoscar/kvox-contract/ontology");
+const graph_1 = require("@marinoscar/kvox-api/graph");
+const index_js_1 = require("../../fixtures/index.js");
+const extract_runner_js_1 = require("./extract-runner.js");
+const TRIGRAM_THRESHOLD = 0.4;
+function trigrams(text) {
+    const out = new Set();
+    for (const word of text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean)) {
+        const padded = `  ${word} `;
+        for (let i = 0; i + 3 <= padded.length; i += 1)
+            out.add(padded.slice(i, i + 3));
+    }
+    return out;
+}
+/**
+ * `pg_trgm`'s `similarity(a, b)`: shared trigrams over the union.
+ *
+ * @stability experimental
+ */
+function trigramSimilarity(a, b) {
+    const x = trigrams(a);
+    const y = trigrams(b);
+    if (x.size === 0 || y.size === 0)
+        return 0;
+    let shared = 0;
+    for (const t of x)
+        if (y.has(t))
+            shared += 1;
+    return shared / (x.size + y.size - shared);
+}
+function safeNormalize(name) {
+    try {
+        return (0, graph_1.normalizeAlias)(name);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * PURE. Resolve every proposed entity row (in place, on copies) against the
+ * fixture's known entities. The Meeting row and anything without a type match
+ * keep what extraction decided.
+  *
+  * @stability experimental
+ */
+function resolveRowsInMemory(fixture, rows, prefs = graph_1.GRAPH_PREFERENCE_DEFAULTS) {
+    const input = (0, extract_runner_js_1.fixtureToInput)(fixture);
+    const speakerPersons = new Set(input.speakers.map((s) => s.personEntityId).filter((id) => !!id));
+    const personBySpeakerName = new Map(input.speakers.filter((s) => s.personEntityId && s.displayName).map((s) => [(0, internals_js_1.normalizeForMatch)(s.displayName), s.personEntityId]));
+    const known = fixture.knownEntities.map((k) => ({
+        ...k,
+        names: [k.label, ...k.aliases],
+        normalized: new Set([k.label, ...k.aliases].map(safeNormalize).filter((n) => n !== null)),
+    }));
+    return rows.map((row) => {
+        if (row.kind !== 'entity' || row.payload.ref === 'meeting' || row.resolution?.source === 'meeting')
+            return row;
+        const p = row.payload;
+        if (p.type === 'Person') {
+            const speakerPerson = [p.label, ...p.aliases].map((n) => personBySpeakerName.get((0, internals_js_1.normalizeForMatch)(n))).find(Boolean);
+            if (speakerPerson) {
+                return { ...row, resolution: { ref: speakerPerson, score: 1, source: 'speaker', candidates: [], adjudication: null } };
+            }
+        }
+        const mentionNames = [p.label, ...p.aliases].map(safeNormalize).filter((n) => n !== null);
+        const scored = known
+            .filter((k) => k.type === p.type)
+            .map((k) => {
+            const aliasExact = mentionNames.some((n) => k.normalized.has(n));
+            const best = Math.max(0, ...k.names.map((n) => trigramSimilarity(p.label, n)));
+            return {
+                entityId: k.id,
+                label: k.label,
+                type: k.type,
+                ...(0, internals_js_1.scoreCandidate)({
+                    aliasExact,
+                    trigram: best >= TRIGRAM_THRESHOLD ? best : null,
+                    cosine: null,
+                    sameMeeting: speakerPersons.has(k.id),
+                    orgCoMention: false,
+                    sharedNeighbour: false,
+                    recent: false,
+                }),
+            };
+        })
+            .filter((c) => c.arm !== null);
+        const ranked = (0, internals_js_1.rankCandidates)(scored, prefs.resolution);
+        const decision = (0, internals_js_1.decide)({ candidates: ranked.candidates, ambiguous: ranked.ambiguous, band: (0, internals_js_1.bandFor)(ranked.candidates[0]?.score ?? null, prefs.resolution) }, prefs.resolution, null);
+        return { ...row, resolution: decision.resolution, flags: [...new Set([...row.flags, ...decision.flags])] };
+    });
+}
+/**
+ * PURE. #365's relation dedup and closing plan, in memory, against the
+ * fixture's prior edges: `known` rows flagged (and so pre-accepted), `overlaps`
+ * / `unordered` copied from #353's plan, and closings counted.
+  *
+  * @stability experimental
+ */
+function applyDedupStagesInMemory(fixture, rows) {
+    const schema = (0, ontology_1.computeEffectiveSchema)({ enabledDomains: (0, index_js_1.fixtureDomains)(fixture), userAttributes: [] });
+    const prior = fixture.knownRelations.map((r) => {
+        const { range, precision } = (0, internals_js_1.proposedRelationRange)(r, 'state');
+        return { id: r.id, type: r.type, fromId: r.from, toId: r.to, props: r.props, valid: range, precision, reviewStatus: 'accepted' };
+    });
+    const entities = new Map();
+    for (const row of rows)
+        if (row.kind === 'entity')
+            entities.set(row.payload.ref, (0, internals_js_1.entityView)(row.payload, row.resolution));
+    const stats = { known: 0, closings: 0, overlaps: 0, unordered: 0 };
+    const closed = new Set();
+    const out = rows.map((row) => {
+        if (row.kind !== 'relation')
+            return row;
+        const p = row.payload;
+        const type = schema.relationType(p.type);
+        const fromId = (0, internals_js_1.existingId)((0, internals_js_1.resolveEndpoint)(p.from, entities));
+        if (!type || !fromId)
+            return row;
+        const rule = (0, internals_js_1.ruleForEffectiveRelation)(type);
+        const to = (0, internals_js_1.resolveEndpoint)(p.to, entities);
+        const toId = (0, internals_js_1.existingId)(to);
+        if (toId && (0, internals_js_1.relationKnown)(prior, p, fromId, toId, rule).known) {
+            stats.known += 1;
+            return { ...row, flags: [...new Set([...row.flags, 'known'])] };
+        }
+        if (!(0, internals_js_1.isExclusiveTemporal)(rule))
+            return row;
+        const plan = (0, graph_1.planTemporalInsert)(prior, (0, internals_js_1.candidateEdge)(p, fromId, (0, internals_js_1.placeholderId)(to), rule), rule);
+        if (plan.action !== 'create')
+            return row;
+        for (const c of plan.closes)
+            if (!closed.has(c.edgeId))
+                closed.add(c.edgeId);
+        const flags = plan.flags.filter((f) => f === 'overlaps' || f === 'unordered');
+        if (flags.includes('overlaps'))
+            stats.overlaps += 1;
+        if (flags.includes('unordered'))
+            stats.unordered += 1;
+        return flags.length > 0 ? { ...row, flags: [...new Set([...row.flags, ...flags])] } : row;
+    });
+    stats.closings = closed.size;
+    return { rows: out, stats };
+}
+/**
+ * The `extract+resolve` runner over `deps.ai`.
+ *
+ * @stability experimental
+ */
+function createExtractResolveRunner(deps) {
+    return {
+        name: 'extract+resolve',
+        async run(fixture, opts) {
+            const extracted = await (0, extract_runner_js_1.runExtraction)(deps.ai, fixture, opts);
+            if (!extracted) {
+                return { fixtureId: fixture.id, model: opts.model, entities: [], relations: [], items: [], stats: { invalidOutput: 1 } };
+            }
+            const resolved = resolveRowsInMemory(fixture, extracted.rows);
+            const deduped = applyDedupStagesInMemory(fixture, resolved);
+            return (0, extract_runner_js_1.precheckToPrediction)(fixture.id, opts.model, deduped.rows, { ...extracted.stats, ...deduped.stats });
+        },
+    };
+}

package/dist/kg/runners/extract-runner.d.ts

@@ -0,0 +1,65 @@
+import { type ExtractionInput, type ProposedRow } from '../internals.js';
+import type { KvoxAiPort } from '@marinoscar/kvox-api/ports';
+import type { GoldenFixture } from '../../fixtures/index.js';
+import type { KgEvalPrediction } from '../prediction-schema.js';
+import type { KgEvalRunner, KgEvalRunnerDeps, KgEvalRunOptions } from '../runner.js';
+/**
+ * The completion ceiling an eval run uses (a production run takes it from policy).
+ *
+ * @stability experimental
+ */
+export declare const EVAL_MAX_OUTPUT_TOKENS = 16000;
+/**
+ * How long one structured call may take before the run gives up on it.
+ *
+ * @stability experimental
+ */
+export declare const EVAL_TIMEOUT_MS = 180000;
+/**
+ * The context window an eval target reports (the port's target carries one; a direct runtime never reads it).
+ *
+ * @stability experimental
+ */
+export declare const EVAL_CONTEXT_WINDOW_TOKENS = 128000;
+/**
+ * The user id an eval call carries (there is no signed-in user).
+ *
+ * @stability experimental
+ */
+export declare const EVAL_USER_ID = "kg-eval";
+/**
+ * The one fixture → input mapping. Pure.
+ *
+ * @stability experimental
+ */
+export declare function fixtureToInput(fixture: GoldenFixture): ExtractionInput;
+/**
+ * Proposal rows (with their pre-check decisions) → a kg:eval prediction. Pure.
+ *
+ * @stability experimental
+ */
+export declare function rowsToPrediction(fixtureId: string, model: string | null, rows: ProposedRow[], decisions: string[], stats: Record<string, number>): KgEvalPrediction;
+/**
+ * The shared half of every runner: one `generateStructured` call and the
+ * validator, returning the proposal rows before any pre-check. `null` when the
+ * model's answer fails validation (`invalidOutput`). #364's `extract+resolve`
+ * runner resolves these rows before the pre-check runs.
+  *
+  * @stability experimental
+ */
+export declare function runExtraction(ai: Pick<KvoxAiPort, 'generateStructured'>, fixture: GoldenFixture, opts: KgEvalRunOptions): Promise<{
+    rows: ProposedRow[];
+    stats: Record<string, number>;
+} | null>;
+/**
+ * Pre-check the rows with default preferences and turn them into a prediction.
+ *
+ * @stability experimental
+ */
+export declare function precheckToPrediction(fixtureId: string, model: string, rows: ProposedRow[], stats: Record<string, number>): KgEvalPrediction;
+/**
+ * The `extract` runner over `deps.ai`.
+ *
+ * @stability experimental
+ */
+export declare function createExtractRunner(deps: KgEvalRunnerDeps): KgEvalRunner;