@juzser/blacksmith 0.1.0

package/factory/orchestrator/dist/scheduler.js

@@ -0,0 +1,408 @@
+// Deterministic scheduler pass (architecture §12 "Recheck scheduling" +
+// "Scheduled growth passes"; `smith scheduler run`). Reads the event log
+// (via db/projector.ts's already-owned task fold — no reason to re-derive
+// task-lifecycle state a second time) and proposes work; it NEVER dispatches
+// an agent and never widens scope itself — every output here is a
+// `*-proposed`/`growth-review-due` event for a human or a later planner
+// session to act on.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { globsOverlap } from './claims.js';
+import { foldTasks, taskIdCanonicalizer } from './db/projector.js';
+import { SmithError } from './errors.js';
+import { appendEvent } from './events.js';
+import { SCHEDULER_POLICY_PATH } from './paths.js';
+export class SchedulerError extends SmithError {
+}
+/**
+ * Every knob, checked rather than trusted (D-203 for the two `lessons` ones).
+ *
+ * `??` defaults on null/undefined only, so a YAML typo -- `days_elapsed:
+ * fourteen`, `cadence_days: monthly` -- arrived at the comparison as itself,
+ * with the declared `number` type saying otherwise. Nothing then failed. The
+ * comparison simply answered differently, in a different direction at each
+ * knob it reaches, which is the same defect cli.ts already reasoned out for a
+ * mistyped `--now` (D-209):
+ *
+ *   - `999 >= 'fourteen'` is false, so a task untouched for three years never
+ *     proposes `time-elapsed`. Fails CLOSED: the operator asks what is due and
+ *     the typo answers "nothing".
+ *   - `0.001 < 'monthly'` is false, so `proposeGrowthReview` never returns
+ *     null and the review fires on every pass. Fails OPEN, from the same typo.
+ *   - `shingle_size: 0` makes `shingles()` emit one empty gram per statement,
+ *     so any two score a Jaccard of 1.0 and `smith dream` auto-rejects every
+ *     checkpoint it extracts.
+ *   - a non-numeric novelty threshold makes `score >= threshold` a NaN
+ *     comparison, always false, so nothing is ever redundant.
+ *
+ * A wrong *number* still passes, deliberately: `days_elapsed: 1` proposes more
+ * rechecks and the operator reads them, so it argues with itself in the open.
+ * A wrong *type* argues in silence. Finiteness is part of the type check, not
+ * a range rule -- `.inf` is a number that no count can ever reach.
+ *
+ * The refusal names the value because a policy file is hand-edited.
+ */
+const READS_SILENTLY = 'A value the comparison cannot read does not fail the run, it changes what the run proposes.';
+const VOIDS_THE_GATE = 'The novelty gate reads this directly and a degenerate value voids it silently.';
+const TRUTHY_IS_NOT_TRUE = 'YAML 1.2 reads `on`/`off`/`yes`/`no` as strings, and every non-empty string is truthy — an operator who typed `off` would have switched the gate ON.';
+function checkKnob(field, value, expected, note, ok = () => true) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || !ok(value)) {
+        throw new SchedulerError('scheduler.invalid-policy', `scheduler.yml ${field} must be ${expected}; got ${JSON.stringify(value)}. ${note}`, { field, value });
+    }
+    return value;
+}
+/** A knob whose only rule is that a comparison can read it. */
+function count(field, value) {
+    return checkKnob(field, value, 'a finite number', READS_SILENTLY);
+}
+/** A knob the code branches on directly, where any string at all would read as `true`. */
+function flag(field, value, note) {
+    if (typeof value !== 'boolean') {
+        throw new SchedulerError('scheduler.invalid-policy', `scheduler.yml ${field} must be true or false; got ${JSON.stringify(value)}. ${note}`, { field, value });
+    }
+    return value;
+}
+/**
+ * The closed vocabularies the `autonomy:` whitelists draw from. Closed on
+ * purpose: a name that matches nothing would fail closed, which is the safe
+ * direction and exactly why it has to be loud — `maintenence` would leave
+ * autonomy switched on and admitting nothing, and the log would say only that
+ * the operator was never asked.
+ */
+const PROPOSAL_KINDS = [
+    'recheck',
+    'maintenance',
+    'growth-review-due',
+];
+const RECHECK_REASONS = [
+    'merge-threshold',
+    'time-elapsed',
+    'low-confidence',
+];
+const A_LIST_IS_NOT_A_STRING = 'A bare scalar spreads into its characters here, so `recheck` would read as seven kinds that match nothing.';
+/** A whitelist: a list of strings, every one of them a name this code knows. */
+function vocabList(field, value, vocabulary) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new SchedulerError('scheduler.invalid-policy', `scheduler.yml ${field} must be a list of strings; got ${JSON.stringify(value)}. ${A_LIST_IS_NOT_A_STRING}`, { field, value });
+    }
+    const entries = value;
+    const unknown = entries.filter((entry) => !vocabulary.includes(entry));
+    if (unknown.length > 0) {
+        throw new SchedulerError('scheduler.invalid-policy', `scheduler.yml ${field} lists ${unknown.map((u) => JSON.stringify(u)).join(', ')}, which is not one of: ${vocabulary.join(', ')}. A name nothing matches disables silently.`, { field, value: unknown });
+    }
+    return [...entries];
+}
+export function parseSchedulerPolicy(yamlText) {
+    const doc = (parseYaml(yamlText) ?? {});
+    if (!doc.recheck || !doc.maintenance || !doc.growth) {
+        throw new SchedulerError('scheduler.invalid-policy', 'scheduler.yml is missing one of recheck/maintenance/growth.');
+    }
+    return {
+        recheck: {
+            mergeThreshold: count('recheck.merge_threshold', doc.recheck.merge_threshold ?? 5),
+            daysElapsed: count('recheck.days_elapsed', doc.recheck.days_elapsed ?? 14),
+            confidenceThreshold: count('recheck.confidence_threshold', doc.recheck.confidence_threshold ?? 0.6),
+        },
+        maintenance: {
+            autoScheduleConfidence: count('maintenance.auto_schedule_confidence', doc.maintenance.auto_schedule_confidence ?? 0.8),
+            majorBumpConfidence: count('maintenance.major_bump_confidence', doc.maintenance.major_bump_confidence ?? 0.5),
+            minorOrPatchConfidence: count('maintenance.minor_or_patch_confidence', doc.maintenance.minor_or_patch_confidence ?? 0.9),
+        },
+        growth: { cadenceDays: count('growth.cadence_days', doc.growth.cadence_days ?? 30) },
+        // Every default fails closed. A scheduler.yml written before autonomy
+        // existed, or one a downstream project trimmed, must not inherit this
+        // repo's answer to "what may run without me": absent means off, and off
+        // means an empty whitelist behind it.
+        autonomy: {
+            enabled: flag('autonomy.enabled', doc.autonomy?.enabled ?? false, TRUTHY_IS_NOT_TRUE),
+            autoDispatchKinds: vocabList('autonomy.auto_dispatch_kinds', doc.autonomy?.auto_dispatch_kinds ?? [], PROPOSAL_KINDS),
+            autoDispatchRecheckReasons: vocabList('autonomy.auto_dispatch_recheck_reasons', doc.autonomy?.auto_dispatch_recheck_reasons ?? [], RECHECK_REASONS),
+            confidenceFloor: checkKnob('autonomy.confidence_floor', doc.autonomy?.confidence_floor ?? 0.8, 'a number in [0, 1]', READS_SILENTLY, (n) => n >= 0 && n <= 1),
+        },
+        lessons: {
+            noveltyJaccardThreshold: checkKnob('lessons.novelty_jaccard_threshold', doc.lessons?.novelty_jaccard_threshold ?? 0.8, 'a number in (0, 1]', VOIDS_THE_GATE, (n) => n > 0 && n <= 1),
+            shingleSize: checkKnob('lessons.shingle_size', doc.lessons?.shingle_size ?? 3, 'an integer >= 1', VOIDS_THE_GATE, (n) => Number.isInteger(n) && n >= 1),
+            noveltyLengthAware: flag('lessons.novelty_length_aware', doc.lessons?.novelty_length_aware ?? true, TRUTHY_IS_NOT_TRUE),
+        },
+    };
+}
+export function loadSchedulerPolicy(filePath = SCHEDULER_POLICY_PATH) {
+    return parseSchedulerPolicy(readFileSync(filePath, 'utf8'));
+}
+/**
+ * task_id -> confidence from its task-result-recorded event, default 1 (full
+ * confidence) when absent.
+ *
+ * Keyed by the canonical id, because `smith gate run <taskId>` stamps whatever
+ * spelling the operator typed: the same task reaches the log qualified from
+ * `task-added` and bare from its result. `proposeRechecks` reads this map with
+ * the canonical id `foldTasks` folded the row under, so a raw key would miss,
+ * fall back to full confidence, and make `low-confidence` unfireable (D-182).
+ */
+function confidenceByTask(events) {
+    const byTask = new Map();
+    const canonical = taskIdCanonicalizer(events);
+    for (const { record } of events) {
+        if (record.event_type !== 'task-result-recorded')
+            continue;
+        const p = record.payload;
+        const taskId = record.task_id ?? p.task_id;
+        const confidence = p.structured_output?.confidence;
+        if (taskId !== undefined && typeof confidence === 'number') {
+            byTask.set(canonical(taskId), confidence);
+        }
+    }
+    return byTask;
+}
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/**
+ * `taskId` -> the event-array index of its MOST RECENT `recheck-proposed`
+ * event (this scheduler's own prior output — `runScheduler()` appends this
+ * event type verbatim from `RecheckProposal`, which uses `taskId`, camelCase
+ * — a deliberate deviation from this file's `task_id` snake_case elsewhere,
+ * since the payload here isn't a required-taxonomy-dimension record; noted,
+ * not renamed, to avoid an unrelated payload-shape change in this fix).
+ */
+function latestRecheckProposalIndex(events) {
+    const latest = new Map();
+    events.forEach(({ record }, index) => {
+        if (record.event_type !== 'recheck-proposed')
+            return;
+        const p = record.payload;
+        if (p.taskId)
+            latest.set(p.taskId, index);
+    });
+    return latest;
+}
+/**
+ * A prior `recheck-proposed` for `taskId` counts as RESOLVED once one of two
+ * events for it appears LATER in the log:
+ *   (a) `task-added` whose payload.recheck_of === taskId — a real recheck
+ *       task was created for it (the convention `/bs plan`'s playbook
+ *       follows when it turns a proposal into a task), or
+ *   (b) `recheck-declined` whose payload.task_id === taskId — the operator
+ *       explicitly said no.
+ * Deliberately NARROW: no other event touching taskId resolves a pending
+ * proposal. Idempotency must fail closed — re-proposing the same recheck is
+ * harmless noise the operator/planner can ignore; silently losing a real,
+ * still-open recheck need because some unrelated event happened to
+ * reference the task would not be.
+ */
+function isRecheckResolved(taskId, eventsAfterProposal) {
+    for (const { record } of eventsAfterProposal) {
+        if (record.event_type === 'task-added') {
+            const p = record.payload;
+            if (p.recheck_of === taskId)
+                return true;
+        }
+        else if (record.event_type === 'recheck-declined') {
+            const p = record.payload;
+            if (p.task_id === taskId)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * §12 recheck policy over already-completed features: for each completed,
+ * non-recheck-origin task, count LATER-completed tasks whose claims overlap
+ * it (mergeCount), days elapsed since it completed, and its completion
+ * confidence (from task-result-recorded, default 1). Proposes a recheck when
+ * any one of the three thresholds trips; `reasons` lists every one that did
+ * — UNLESS an earlier `recheck-proposed` for the same task is still
+ * unresolved (isRecheckResolved), in which case it is skipped: re-running
+ * this pass must never emit a duplicate proposal for the same open recheck.
+ */
+export function proposeRechecks(events, now, policy) {
+    const tasks = foldTasks(events);
+    const completed = tasks.filter((t) => t.taskStatus === 'completed' && t.origin !== 'recheck');
+    const confidence = confidenceByTask(events);
+    const latestProposalIndex = latestRecheckProposalIndex(events);
+    const proposals = [];
+    for (const task of completed) {
+        const mergeCount = countLaterOverlappingMerges(task, tasks);
+        const daysElapsed = (now.getTime() - Date.parse(task.updatedAt)) / MS_PER_DAY;
+        const taskConfidence = confidence.get(task.taskId) ?? 1;
+        const reasons = [];
+        if (mergeCount >= policy.mergeThreshold)
+            reasons.push('merge-threshold');
+        if (daysElapsed >= policy.daysElapsed)
+            reasons.push('time-elapsed');
+        if (taskConfidence < policy.confidenceThreshold)
+            reasons.push('low-confidence');
+        if (reasons.length === 0)
+            continue;
+        const priorIndex = latestProposalIndex.get(task.taskId);
+        if (priorIndex !== undefined) {
+            const eventsAfter = events.slice(priorIndex + 1);
+            if (!isRecheckResolved(task.taskId, eventsAfter))
+                continue; // still pending -> skip, idempotent
+        }
+        proposals.push({
+            kind: 'recheck',
+            taskId: task.taskId,
+            epicId: task.epicId,
+            reasons,
+            mergeCount,
+            daysElapsed: Math.floor(daysElapsed),
+            confidence: taskConfidence,
+        });
+    }
+    return proposals.sort((a, b) => a.taskId.localeCompare(b.taskId));
+}
+function countLaterOverlappingMerges(task, allTasks) {
+    if (!task.claims || task.claims.length === 0)
+        return 0;
+    let count = 0;
+    for (const other of allTasks) {
+        if (other.taskId === task.taskId)
+            continue;
+        if (other.taskStatus !== 'completed')
+            continue;
+        if (Date.parse(other.updatedAt) <= Date.parse(task.updatedAt))
+            continue;
+        if (!other.claims || other.claims.length === 0)
+            continue;
+        const overlaps = task.claims.some((a) => other.claims?.some((b) => globsOverlap(a, b)));
+        if (overlaps)
+            count++;
+    }
+    return count;
+}
+export function parsePnpmOutdated(json) {
+    const doc = JSON.parse(json);
+    return Object.entries(doc)
+        .filter(([, v]) => v.current && v.wanted && v.latest)
+        .map(([name, v]) => ({
+        name,
+        current: v.current,
+        wanted: v.wanted,
+        latest: v.latest,
+    }));
+}
+/** Best-effort `pnpm outdated --json` in `projectDir`; null when pnpm/lockfile is unavailable ("when available"). */
+export function runPnpmOutdated(projectDir) {
+    let stdout;
+    try {
+        // pnpm outdated exits 1 when it finds outdated packages — the JSON is
+        // still on stdout, so a non-zero exit is read from the error, not treated
+        // as failure. A genuinely missing pnpm/lockfile throws with no stdout.
+        // stdio explicit for the same reason as git.ts: without it execFileSync
+        // sends pnpm's stderr to the operator's terminal, and "No dependencies
+        // found" on a fresh project reads as a factory failure (P9-16b).
+        stdout = execFileSync('pnpm', ['outdated', '--json'], {
+            cwd: projectDir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const withStdout = err;
+        if (!withStdout.stdout)
+            return null;
+        stdout = withStdout.stdout;
+    }
+    try {
+        return parsePnpmOutdated(stdout);
+    }
+    catch {
+        return null; // not valid JSON — nothing to propose, not a crash
+    }
+}
+function majorVersion(semver) {
+    const match = semver.replace(/^[^0-9]*/, '').match(/^(\d+)/);
+    return match ? Number.parseInt(match[1], 10) : 0;
+}
+/** origin: inferred (agent-constraints.md "planner / Growth passes") — auto-schedulable only at high confidence. */
+export function proposeMaintenance(projectDir, packages, policy) {
+    if (packages.length === 0)
+        return null;
+    const hasMajorBump = packages.some((p) => majorVersion(p.latest) > majorVersion(p.current));
+    const confidence = hasMajorBump ? policy.majorBumpConfidence : policy.minorOrPatchConfidence;
+    return {
+        kind: 'maintenance',
+        projectDir: path.resolve(projectDir),
+        packages: [...packages],
+        confidence,
+        autoSchedulable: confidence >= policy.autoScheduleConfidence,
+    };
+}
+/**
+ * Emits the TRIGGER only — architecture §12: "product-growth proposals
+ * always wait for an operator tick"; the planner session (not this
+ * scheduler) reads the living spec/analytics and proposes scope. Fires once
+ * cadenceDays have elapsed since the last growth-review-due event in this
+ * log (or immediately, if none has ever fired).
+ */
+export function proposeGrowthReview(events, now, policy) {
+    let lastReviewAt = null;
+    for (const { record } of events) {
+        if (record.event_type === 'growth-review-due')
+            lastReviewAt = record.ts;
+    }
+    if (lastReviewAt === null) {
+        return { kind: 'growth-review-due', cadenceDays: policy.cadenceDays, lastReviewAt: null };
+    }
+    const daysSince = (now.getTime() - Date.parse(lastReviewAt)) / MS_PER_DAY;
+    if (daysSince < policy.cadenceDays)
+        return null;
+    return { kind: 'growth-review-due', cadenceDays: policy.cadenceDays, lastReviewAt };
+}
+/** Pure: computes every proposal this pass would make, without touching the event log. */
+export function computeProposals(input) {
+    const policy = input.policy ?? loadSchedulerPolicy();
+    const now = input.now ?? new Date();
+    const readOutdated = input.readOutdated ?? runPnpmOutdated;
+    const proposals = [...proposeRechecks(input.events, now, policy.recheck)];
+    // In the order the repos were given, and one repo's silence costs only that
+    // repo: "when available" is a property of each lockfile, so a child project
+    // that has never been installed must not take the reading on all the others
+    // down with it.
+    for (const projectDir of input.projectDirs ?? []) {
+        const outdated = readOutdated(projectDir);
+        if (!outdated)
+            continue;
+        const maintenance = proposeMaintenance(projectDir, outdated, policy.maintenance);
+        if (maintenance)
+            proposals.push(maintenance);
+    }
+    const growth = proposeGrowthReview(input.events, now, policy.growth);
+    if (growth)
+        proposals.push(growth);
+    return proposals;
+}
+/** event_type per proposal kind — free strings, same taxonomy precedent as dispatch_decision/gate-outcome. */
+function eventTypeFor(proposal) {
+    if (proposal.kind === 'recheck')
+        return 'recheck-proposed';
+    if (proposal.kind === 'maintenance')
+        return 'maintenance-proposed';
+    return 'growth-review-due';
+}
+/**
+ * Runs computeProposals() and, unless `dryRun`, appends one event per
+ * proposal (chained causal_parent) — the scheduler's only write. Never
+ * dispatches an agent itself (architecture §12).
+ */
+export async function runScheduler(input, ctx, opts = {}, dryRun = false) {
+    const proposals = computeProposals(input);
+    const eventIds = [];
+    if (!dryRun) {
+        let parent = ctx.causalParent;
+        for (const proposal of proposals) {
+            const event = await appendEvent({
+                session_id: ctx.sessionId,
+                actor: ctx.actor ?? 'system',
+                event_type: eventTypeFor(proposal),
+                plan_version: ctx.planVersion,
+                causal_parent: parent,
+                payload: proposal,
+            }, opts);
+            parent = event.event_id;
+            eventIds.push(event.event_id);
+        }
+    }
+    return { proposals, eventIds };
+}

package/factory/orchestrator/dist/schemas.js

@@ -0,0 +1,195 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import addFormatsImport from 'ajv-formats';
+// ajv-formats ships a .d.ts written as an ES module (`export default`) but its
+// package.json has no "type": "module", so under NodeNext resolution its
+// declared type is the whole CJS module namespace, not the callable plugin
+// function it actually is at runtime (verified: module.exports is the
+// function itself). Narrow it back to the callable shape here, once.
+const addFormats = addFormatsImport;
+import { SmithError } from './errors.js';
+import { SCHEMA_DIR } from './paths.js';
+import { validateTag } from './taxonomy.js';
+export class SchemaError extends SmithError {
+}
+function schemaNameFromFile(fileName) {
+    // "task-spec.schema.json" -> "task-spec"
+    return fileName.replace(/\.schema\.json$/, '');
+}
+/**
+ * Recursively collect every `x-taxonomy`-annotated field path in a JSON Schema.
+ * A `[]` segment stands for "every element of the array here" — see
+ * `resolveAtPath`, which is the half that has to know how to walk it.
+ */
+function collectTaxonomyPointers(node, segments = [], schemaPath = '') {
+    if (!node || typeof node !== 'object')
+        return [];
+    const found = [];
+    const obj = node;
+    const properties = obj.properties;
+    if (properties && typeof properties === 'object') {
+        for (const [key, propSchema] of Object.entries(properties)) {
+            const childSegments = [...segments, key];
+            const childPath = `${schemaPath}/properties/${key}`;
+            const prop = propSchema;
+            if (typeof prop['x-taxonomy'] === 'string') {
+                found.push({
+                    segments: childSegments,
+                    dimension: prop['x-taxonomy'],
+                    schemaPath: childPath,
+                });
+            }
+            found.push(...collectTaxonomyPointers(prop, childSegments, childPath));
+        }
+    }
+    const items = obj.items;
+    if (items && typeof items === 'object') {
+        const itemSegments = [...segments, '[]'];
+        const itemPath = `${schemaPath}/items`;
+        // An array of tag strings has no property to hang the annotation on, so
+        // it goes on `items` itself. Only entries of `properties` were read for
+        // one, which meant that whole shape was invisible (D-194).
+        const item = items;
+        if (typeof item['x-taxonomy'] === 'string') {
+            found.push({ segments: itemSegments, dimension: item['x-taxonomy'], schemaPath: itemPath });
+        }
+        found.push(...collectTaxonomyPointers(items, itemSegments, itemPath));
+    }
+    return found;
+}
+/**
+ * Every `x-taxonomy` in the document, wherever it sits, as JSON pointers.
+ * Deliberately keyword-blind: it walks the raw JSON, so it sees the ones
+ * `collectTaxonomyPointers` walks past as well as the ones it collects. The
+ * difference between the two lists is the hole.
+ */
+function annotationPathsAnywhere(node, schemaPath = '') {
+    if (!node || typeof node !== 'object')
+        return [];
+    if (Array.isArray(node)) {
+        return node.flatMap((child, i) => annotationPathsAnywhere(child, `${schemaPath}/${i}`));
+    }
+    const found = [];
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'x-taxonomy' && typeof value === 'string') {
+            found.push(schemaPath);
+            continue;
+        }
+        found.push(...annotationPathsAnywhere(value, `${schemaPath}/${key}`));
+    }
+    return found;
+}
+/**
+ * Every value a pointer names. One for a plain field; one per element for a
+ * `[]` segment, which is why this returns a list rather than a value — a
+ * pointer under an array is a question about each element, and the answer has
+ * to say which one.
+ */
+function resolveAtPath(data, segments, prefix = []) {
+    const [segment, ...rest] = segments;
+    if (segment === undefined)
+        return [{ path: prefix, value: data }];
+    if (segment === '[]') {
+        if (!Array.isArray(data))
+            return [];
+        return data.flatMap((element, i) => resolveAtPath(element, rest, [...prefix, String(i)]));
+    }
+    if (data === null || data === undefined || typeof data !== 'object')
+        return [];
+    return resolveAtPath(data[segment], rest, [...prefix, segment]);
+}
+export function loadSchemaFiles(dir = SCHEMA_DIR) {
+    const files = readdirSync(dir).filter((f) => f.endsWith('.schema.json'));
+    const schemas = new Map();
+    for (const file of files) {
+        const text = readFileSync(path.join(dir, file), 'utf8');
+        schemas.set(schemaNameFromFile(file), JSON.parse(text));
+    }
+    return schemas;
+}
+export function compileSchemas(_taxonomy, dir = SCHEMA_DIR) {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const raw = loadSchemaFiles(dir);
+    const compiled = new Map();
+    for (const [name, schema] of raw) {
+        const taxonomyPointers = collectTaxonomyPointers(schema);
+        assertEveryAnnotationReachable(name, schema, taxonomyPointers);
+        compiled.set(name, {
+            name,
+            validate: ajv.compile(schema),
+            taxonomyPointers,
+        });
+    }
+    return compiled;
+}
+/**
+ * Refuse a schema that annotates a field the pointer walker cannot reach.
+ *
+ * The walker reads `properties` and `items`. A subschema can also live under
+ * `$defs` behind a `$ref`, in a `oneOf`/`anyOf`/`allOf` branch, under
+ * `patternProperties` -- and mcp-manifest.schema.json already uses four of
+ * those. An annotation there used to be collected by nobody and reported by
+ * nobody: the record validated, the unknown tag went in, and the field simply
+ * stopped being governed by the taxonomy. Nothing distinguishes that from a
+ * field nobody annotated.
+ *
+ * The fix is the error, not reference resolution. Resolving `$ref` means
+ * owning a second schema engine -- cycles, remote ids, `$dynamicRef` -- to
+ * serve a shape no committed schema uses. Refusing at compile time costs one
+ * comparison and tells the schema author the one thing they need to know, at
+ * the moment they need it, instead of leaving them a validator that silently
+ * agrees with everything.
+ */
+function assertEveryAnnotationReachable(name, schema, pointers) {
+    const reachable = new Set(pointers.map((p) => p.schemaPath));
+    const unreachable = annotationPathsAnywhere(schema).filter((p) => !reachable.has(p));
+    if (unreachable.length === 0)
+        return;
+    throw new SchemaError('schema.unreachable-taxonomy', `Schema "${name}" annotates ${unreachable.length} field(s) with x-taxonomy where the ` +
+        `pointer walker cannot see them: ${unreachable.join(', ')}. It reads \`properties\` and ` +
+        '`items` only, so an annotation under `$defs`, `$ref`, `oneOf`, `anyOf`, `allOf` or ' +
+        '`patternProperties` would never be checked and the field would go ungoverned. Move it ' +
+        'onto the property (or onto `items`) that carries the value.', { schema: name, paths: unreachable });
+}
+function ajvErrorToIssue(err) {
+    return { path: err.instancePath || '/', message: `${err.instancePath} ${err.message}`.trim() };
+}
+/**
+ * Validate a record against a compiled schema by name, then resolve every
+ * x-taxonomy annotated field against the taxonomy so a schema-valid record
+ * with an unknown taxonomy value still fails.
+ */
+export function validateRecord(schemas, taxonomy, schemaName, record) {
+    const compiled = schemas.get(schemaName);
+    if (!compiled) {
+        throw new SchemaError('schema.unknown-name', `Unknown schema "${schemaName}".`, {
+            schemaName,
+            known: [...schemas.keys()],
+        });
+    }
+    const errors = [];
+    const schemaValid = compiled.validate(record);
+    if (!schemaValid) {
+        for (const err of compiled.validate.errors ?? []) {
+            errors.push(ajvErrorToIssue(err));
+        }
+    }
+    for (const pointer of compiled.taxonomyPointers) {
+        for (const hit of resolveAtPath(record, pointer.segments)) {
+            if (hit.value === undefined)
+                continue; // absence is the schema's job, not ours
+            const pathStr = `/${hit.path.join('/')}`;
+            try {
+                validateTag(taxonomy, pointer.dimension, String(hit.value));
+            }
+            catch (err) {
+                errors.push({ path: pathStr, message: err instanceof Error ? err.message : String(err) });
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { valid: false, errors };
+    return { valid: true };
+}