c64-kb 0.17.0

package/dist/services/falkor/nodes.js.map

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

package/dist/services/falkor/params.js

@@ -0,0 +1,45 @@
+/**
+ * Query-parameter types and small helpers shared by the FalkorDB service.
+ * The falkordb package does not export its QueryParams type, so it is
+ * derived here once from Graph.query's signature.
+ */
+/**
+ * Check a caller's parameter record against what the client can serialise.
+ * The client throws the same TypeError for anything else (undefined, a
+ * function, a symbol), so this changes where the error is raised, not whether.
+ */
+function toQueryParam(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(toQueryParam);
+    if (typeof value === "object")
+        return toQueryParams(value);
+    throw new TypeError(`Unexpected param type ${typeof value}`);
+}
+export function toQueryParams(params) {
+    const out = {};
+    for (const [key, value] of Object.entries(params))
+        out[key] = toQueryParam(value);
+    return out;
+}
+/** "$D011" -> 0xD011; -1 when the string is not a 16-bit hex address (the graph stores -1, not null). */
+export function hexAddr(s) {
+    if (!s)
+        return -1;
+    const m = /^\$?([0-9A-Fa-f]{1,4})$/.exec(s.trim());
+    return m?.[1] ? parseInt(m[1], 16) : -1;
+}
+/** The numeric `n` column of the first row, or 0. */
+export function firstCount(rows, column = "n") {
+    const row = rows[0];
+    if (typeof row !== "object" || row === null)
+        return 0;
+    const v = Reflect.get(row, column);
+    return typeof v === "number" ? v : Number(v ?? 0);
+}
+//# sourceMappingURL=params.js.map

package/dist/services/falkor/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../../src/services/falkor/params.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;;;GAIG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,QAAQ;QACzB,OAAO,KAAK,KAAK,SAAS,EAC1B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAC3D,MAAM,IAAI,SAAS,CAAC,yBAAyB,OAAO,KAAK,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAClF,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,OAAO,CAAC,CAAqB;IAC3C,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IAClB,MAAM,CAAC,GAAG,yBAAyB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACnD,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,MAAM,GAAG,GAAG;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,CAAC,CAAC;IACtD,MAAM,CAAC,GAAY,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC5C,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/services/falkor/schema.js

@@ -0,0 +1,77 @@
+/**
+ * Graph schema: one table of node labels drives the range indexes, the
+ * unique constraints and the labels clean() wipes. The three lists used to
+ * be written out separately. Keep the table aligned with docs/ONTOLOGY.md §4.1.
+ */
+import { ConstraintType, EntityType } from "falkordb";
+const LABELS = [
+    { label: "KernalRoutine", key: "name", unique: true, cleanable: true },
+    { label: "Register", key: "name", unique: true, cleanable: true },
+    { label: "MemoryRegion", key: "name", unique: true, cleanable: true },
+    { label: "Chip", key: "name", unique: true, cleanable: false },
+    { label: "Region", key: "name", unique: true, cleanable: false },
+    { label: "Technique", key: "name", unique: true, cleanable: true },
+    { label: "Pitfall", key: "name", unique: true, cleanable: true },
+    { label: "CrashPattern", key: "symptom", unique: true, cleanable: true },
+    { label: "Tool", key: "name", unique: true, cleanable: true },
+    { label: "Recipe", key: "name", unique: true, cleanable: true },
+    { label: "FileFormat", key: "name", unique: true, cleanable: true },
+    // Resource has a range index but no uniqueness constraint, as before the table existed.
+    { label: "Resource", key: "name", unique: false, cleanable: true },
+    { label: "Archetype", key: "name", unique: true, cleanable: true },
+    // Whole-game compositions from docs/game-design/designs (schema 28).
+    { label: "GameDesign", key: "name", unique: true, cleanable: true },
+    // Seeds (schema 25) that CLAIMS edges point at; ensureSchema re-MERGEs them.
+    { label: "HardwareUnit", key: "name", unique: true, cleanable: false },
+    // Seeds (schema 29): the models VICE runs; VERIFIED_ON edges point at them.
+    { label: "MachineVariant", key: "name", unique: true, cleanable: false },
+];
+export const CLEANABLE_LABELS = LABELS.filter((l) => l.cleanable).map((l) => l.label);
+// Full-text indexes for "find a thing that does X" queries.
+const FULLTEXT_INDEXES = [["KernalRoutine", "description"]];
+export const CHIPS = [
+    { name: "VIC-II", variants: "6569 PAL / 6567 NTSC", role: "Graphics + raster" },
+    { name: "SID", variants: "6581 / 8580", role: "Audio synthesis" },
+    { name: "CIA1", variants: "6526", role: "Keyboard / joystick / timer-A IRQ" },
+    { name: "CIA2", variants: "6526", role: "VIC bank / RS-232 / timer-B NMI" },
+    { name: "6510", variants: "MOS 6510", role: "CPU (6502-compatible + I/O port at $00/$01)" },
+];
+export const REGIONS = [
+    { name: "PAL", refresh_hz: 50, lines_per_frame: 312, cycles_per_line: 63 },
+    { name: "NTSC", refresh_hz: 60, lines_per_frame: 263, cycles_per_line: 65 },
+];
+/**
+ * ensureSchema is re-run on every connect, so "already there" is expected.
+ * Messages measured against FalkorDB graph module 4.18.7: "Attribute 'x' is
+ * already indexed", "Constraint already exists". Anything else is rethrown;
+ * the bare catch here used to hide every error, not just these.
+ */
+async function unlessExists(op) {
+    try {
+        await op();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!/already indexed|already exists/i.test(msg))
+            throw err;
+    }
+}
+/**
+ * Range index on every label's key, then the unique constraints (FalkorDB
+ * requires the supporting range index first), then the full-text indexes.
+ * Every unique key is also the indexed key, so the pass that used to add a
+ * supporting index for a constraint on another property had nothing to do
+ * and is gone.
+ */
+export async function createIndexes(g) {
+    for (const { label, key } of LABELS) {
+        await unlessExists(() => g.createNodeRangeIndex(label, key));
+    }
+    for (const { label, key } of LABELS.filter((l) => l.unique)) {
+        await unlessExists(() => g.constraintCreate(ConstraintType.UNIQUE, EntityType.NODE, label, key));
+    }
+    for (const [label, prop] of FULLTEXT_INDEXES) {
+        await unlessExists(() => g.createNodeFulltextIndex(label, prop));
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/services/falkor/schema.js.map

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

package/dist/services/falkor.js

@@ -0,0 +1,100 @@
+/**
+ * FalkorDB client for the C64 knowledge graph.
+ *
+ * The class is layered so no file carries all of it: falkor/base.ts holds the
+ * connection and the read/write helpers, falkor/nodes.ts the node upserts,
+ * falkor/links.ts the edge writes, falkor/schema.ts the label table. This
+ * file adds schema setup, cleaning and stats, and stays the import path.
+ */
+import { HARDWARE_UNITS } from "../graph/claims.js";
+import { MACHINE_VARIANTS } from "../graph/machine-variants.js";
+import { firstCount } from "./falkor/params.js";
+import { FalkorLinks } from "./falkor/links.js";
+import { CHIPS, CLEANABLE_LABELS, REGIONS, createIndexes } from "./falkor/schema.js";
+export class FalkorService extends FalkorLinks {
+    /** Indexes, constraints and the Chip and Region seed nodes. Safe to re-run. */
+    async ensureSchema() {
+        await createIndexes(this.graph());
+        for (const chip of CHIPS) {
+            await this.upsertNode({
+                label: "Chip",
+                name: chip.name,
+                props: { variants: chip.variants, role: chip.role },
+            });
+        }
+        for (const region of REGIONS) {
+            const { name, ...props } = region;
+            await this.upsertNode({ label: "Region", name, props });
+        }
+        await this.seedHardwareUnits();
+        for (const v of MACHINE_VARIANTS) {
+            const { name, ...props } = v;
+            await this.upsertNode({
+                label: "MachineVariant",
+                name,
+                props: { ...props, vice_flag: `-model ${name}` },
+            });
+        }
+    }
+    /**
+     * HardwareUnit seeds (schema 25): the pieces of hardware a CLAIMS edge
+     * names. Seeded, like Chip and Region, so a Claims line can only point at
+     * a unit that exists; BELONGS_TO its chip where it has one.
+     */
+    async seedHardwareUnits() {
+        for (const u of HARDWARE_UNITS) {
+            await this.upsertNode({
+                label: "HardwareUnit",
+                name: u.name,
+                props: { kind: u.kind, addresses: u.addresses, chip: u.chip ?? "" },
+            });
+            if (u.chip) {
+                await this.write(`MATCH (h:HardwareUnit {name: $name}) MATCH (c:Chip {name: $chip}) MERGE (h)-[:BELONGS_TO]->(c)`, { name: u.name, chip: u.chip });
+            }
+        }
+    }
+    /**
+     * Per-label DETACH DELETE for all C64 entity nodes. Preserves the
+     * graph itself + indexes + constraints + Chip/Region/HardwareUnit/MachineVariant seeds (which
+     * are re-MERGED by ensureSchema on next connect).
+     */
+    async clean() {
+        for (const label of CLEANABLE_LABELS) {
+            await this.write(`MATCH (n:${label}) DETACH DELETE n`);
+        }
+    }
+    /**
+     * Drop the entire graph (GRAPH.DELETE). Removes all nodes, edges,
+     * indexes, and constraints. Use in tests that need to verify schema
+     * from a pristine state; NOT safe to call during normal ingest.
+     */
+    async dropGraph() {
+        try {
+            await this.graph().delete();
+        }
+        catch (err) {
+            // A graph that was never created: "Invalid graph operation on empty key".
+            if (!(err instanceof Error && err.message.includes("empty key")))
+                throw err;
+        }
+    }
+    /**
+     * Node and edge totals. A failed query throws: this used to return zeros,
+     * and health then reported an unreachable graph as a healthy empty one.
+     */
+    async getStats() {
+        const nodes = await this.roQuery("MATCH (n) RETURN count(n) AS cnt");
+        const edges = await this.roQuery("MATCH ()-[r]->() RETURN count(r) AS cnt");
+        return { nodes: firstCount(nodes.data, "cnt"), edges: firstCount(edges.data, "cnt") };
+    }
+    /**
+     * Phase 7 coverage tooling will implement per-label orphan queries
+     * (Register without BELONGS_TO any Chip, Technique without USES any
+     * Register, and so on). Until then the gap is explicit rather than a
+     * silent [].
+     */
+    findOrphans(label) {
+        return Promise.reject(new Error(`findOrphans(${label}) is not implemented until Phase 7 coverage tooling. Planned for Phase 7.`));
+    }
+}
+//# sourceMappingURL=falkor.js.map

package/dist/services/falkor.js.map

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

package/dist/services/qdrant.js

@@ -0,0 +1,238 @@
+import { QdrantClient } from "@qdrant/js-client-rest";
+import { z } from "zod";
+import { config } from "../config.js";
+const COLLECTION = config.qdrant.collection;
+// Extra fused points fetched so a tie at the cut is broken by id, not by Qdrant's order.
+const TIE_MARGIN = 20;
+const VECTOR_SIZE = config.qdrant.vectorSize;
+// The payload fields every chunk is written with (see upsertChunks); others pass through.
+const ChunkPayloadSchema = z.looseObject({
+    source: z.string(),
+    section: z.string(),
+    text: z.string(),
+    ingested_at: z.string(),
+});
+/** Check a point's payload at the boundary instead of casting it. */
+function toChunk(payload) {
+    return ChunkPayloadSchema.parse(payload);
+}
+function sourceFilter(source) {
+    return { must: [{ key: "source", match: { value: source } }] };
+}
+// Upper bound on distinct source files returned by one facet request.
+const FACET_LIMIT = 100_000;
+// Group by category using the c64-kb docs taxonomy: top-level directory if
+// it's one we know, "core" for top-level .md files, "other" for anything
+// else. Matches the WALK_PRIORITY order in src/ingest.ts so dashboard
+// buckets line up with ingest order.
+const C64_BUCKETS = [
+    ["hardware/", "hardware"],
+    ["toolchains/", "toolchains"],
+    ["runtime/", "runtime"],
+    ["formats/", "formats"],
+    ["recipes/", "recipes"],
+    ["techniques/", "techniques"],
+];
+function categoryOf(source) {
+    const bucket = C64_BUCKETS.find(([prefix]) => source.startsWith(prefix));
+    if (bucket)
+        return bucket[1];
+    return source.includes("/") ? "other" : "core";
+}
+/** Sorted by total chunks desc, with alphabetical tiebreakers so equal counts order the same every run. */
+function groupSources(counts) {
+    const categories = new Map();
+    for (const [source, chunks] of counts) {
+        const category = categoryOf(source);
+        const list = categories.get(category) ?? [];
+        list.push({ source, chunks });
+        categories.set(category, list);
+    }
+    return Array.from(categories.entries())
+        .map(([category, sources]) => {
+        sources.sort((a, b) => b.chunks - a.chunks || a.source.localeCompare(b.source));
+        return {
+            category,
+            sources,
+            totalChunks: sources.reduce((n, x) => n + x.chunks, 0),
+            totalDocs: sources.length,
+        };
+    })
+        .sort((a, b) => b.totalChunks - a.totalChunks || a.category.localeCompare(b.category));
+}
+export class QdrantService {
+    client;
+    constructor(url = config.qdrant.url) {
+        this.client = new QdrantClient({ url });
+    }
+    async ensureCollection() {
+        const collections = await this.client.getCollections();
+        const exists = collections.collections.some((c) => c.name === COLLECTION);
+        if (!exists) {
+            await this.client.createCollection(COLLECTION, {
+                vectors: {
+                    dense: { size: VECTOR_SIZE, distance: "Cosine" },
+                },
+                sparse_vectors: {
+                    bm25: { modifier: "idf" },
+                },
+            });
+            // Payload indexes for filtering
+            await this.client.createPayloadIndex(COLLECTION, {
+                field_name: "source",
+                field_schema: "keyword",
+            });
+            // Full-text index kept for legacy searchByText fallback path
+            await this.client.createPayloadIndex(COLLECTION, {
+                field_name: "text",
+                field_schema: {
+                    type: "text",
+                    tokenizer: "word",
+                    lowercase: true,
+                },
+            });
+        }
+    }
+    async upsertChunks(chunks) {
+        // Batch in groups of 100
+        for (let i = 0; i < chunks.length; i += 100) {
+            const batch = chunks.slice(i, i + 100);
+            await this.client.upsert(COLLECTION, {
+                points: batch.map((c) => ({
+                    id: c.id,
+                    vector: {
+                        dense: c.dense,
+                        bm25: c.sparse,
+                    },
+                    payload: c.payload,
+                })),
+            });
+        }
+    }
+    async search(vector, limit = 5, filterSource) {
+        const filter = filterSource ? sourceFilter(filterSource) : undefined;
+        const results = await this.client.query(COLLECTION, {
+            query: vector,
+            using: "dense",
+            limit,
+            ...(filter ? { filter } : {}),
+            with_payload: true,
+        });
+        return results.points.map((r) => ({ ...toChunk(r.payload), score: r.score }));
+    }
+    async searchByText(text, limit = 5, filterSource) {
+        // Full-text search fallback using Qdrant's text index (word tokenized)
+        const must = [{ key: "text", match: { text } }];
+        if (filterSource) {
+            must.push({ key: "source", match: { value: filterSource } });
+        }
+        const results = await this.client.scroll(COLLECTION, {
+            filter: { must },
+            limit,
+            with_payload: true,
+            with_vector: false,
+        });
+        return results.points.map((r) => ({ ...toChunk(r.payload), score: 1.0 }));
+    }
+    /**
+     * Native Qdrant hybrid search via the Query API. Issues a single
+     * request with two prefetches (dense + sparse) and fuses results
+     * server-side using RRF.
+     *
+     * If `sparseVec` is empty (cold-start, no BM25 vocab yet), the
+     * sparse prefetch is omitted and the query degrades to dense-only.
+     */
+    async hybridSearch(denseVec, sparseVec, limit = 5, filterSource) {
+        const filter = filterSource ? sourceFilter(filterSource) : undefined;
+        const prefetch = [
+            {
+                query: denseVec,
+                using: "dense",
+                limit: Math.max(limit, 20),
+                ...(filter ? { filter } : {}),
+            },
+        ];
+        if (sparseVec.indices.length > 0) {
+            prefetch.push({
+                query: sparseVec,
+                using: "bm25",
+                limit: Math.max(limit, 20),
+                ...(filter ? { filter } : {}),
+            });
+        }
+        // RRF scores tie often (a point first in one list and absent from the
+        // other scores the same as its mirror), and Qdrant returns tied points in
+        // no fixed order: the same query gave four different top-5s in four runs.
+        // Fetch past the cut, then order by score and id so ties break the same
+        // way every time.
+        const results = await this.client.query(COLLECTION, {
+            prefetch,
+            query: { fusion: "rrf" },
+            limit: limit + TIE_MARGIN,
+            with_payload: true,
+        });
+        return results.points
+            .map((r) => ({ id: String(r.id), score: r.score, payload: toChunk(r.payload) }))
+            .sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+            .slice(0, limit)
+            .map((r) => ({ ...r.payload, score: r.score }));
+    }
+    async deleteBySource(source) {
+        // wait: the client defaults to not waiting, so an upsert or a search right
+        // after could still see the old points.
+        await this.client.delete(COLLECTION, {
+            wait: true,
+            filter: sourceFilter(source),
+        });
+    }
+    /** Drop the whole collection. `ingest --clean` follows this with ensureCollection(). */
+    async dropCollection() {
+        const collections = await this.client.getCollections();
+        if (collections.collections.some((c) => c.name === COLLECTION)) {
+            await this.client.deleteCollection(COLLECTION);
+        }
+    }
+    async getStats() {
+        const info = await this.client.getCollection(COLLECTION);
+        return {
+            total_points: info.points_count ?? 0,
+            segments: info.segments_count,
+        };
+    }
+    /**
+     * Scroll chunks with an exact `source` match.
+     * Used by self-improvement heuristics to fetch doc-chunks for a
+     * specific source file without a vector query.
+     *
+     * Returns up to `limit` points (default 20).
+     */
+    async scrollBySource(source, limit = 20) {
+        const result = await this.client.scroll(COLLECTION, {
+            filter: sourceFilter(source),
+            limit,
+            with_payload: true,
+            with_vector: false,
+        });
+        return result.points.map((r) => toChunk(r.payload));
+    }
+    /**
+     * Chunk counts per source file, grouped by top-level docs directory.
+     * One exact facet request on the keyword-indexed `source` field; this used
+     * to scroll every point to count them.
+     */
+    async getSourceBreakdown() {
+        const [facet, info] = await Promise.all([
+            this.client.facet(COLLECTION, { key: "source", exact: true, limit: FACET_LIMIT }),
+            this.client.getCollection(COLLECTION),
+        ]);
+        const counts = new Map();
+        for (const hit of facet.hits)
+            counts.set(String(hit.value), hit.count);
+        // A point with no `source` is absent from the facet; the scroll counted it as "unknown".
+        const missing = (info.points_count ?? 0) - facet.hits.reduce((n, h) => n + h.count, 0);
+        if (missing > 0)
+            counts.set("unknown", (counts.get("unknown") ?? 0) + missing);
+        return groupSources(counts);
+    }
+}
+//# sourceMappingURL=qdrant.js.map

package/dist/services/qdrant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qdrant.js","sourceRoot":"","sources":["../../src/services/qdrant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAgB,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;AAC5C,yFAAyF;AACzF,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;AAiB7C,0FAA0F;AAC1F,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC;IACvC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC;AAEH,qEAAqE;AACrE,SAAS,OAAO,CAAC,OAAgB;IAC/B,OAAO,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,sEAAsE;AACtE,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,2EAA2E;AAC3E,yEAAyE;AACzE,sEAAsE;AACtE,qCAAqC;AACrC,MAAM,WAAW,GAA2C;IAC1D,CAAC,WAAW,EAAE,UAAU,CAAC;IACzB,CAAC,aAAa,EAAE,YAAY,CAAC;IAC7B,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,UAAU,EAAE,SAAS,CAAC;IACvB,CAAC,aAAa,EAAE,YAAY,CAAC;CAC9B,CAAC;AAEF,SAAS,UAAU,CAAC,MAAc;IAChC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACzE,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AACjD,CAAC;AAED,2GAA2G;AAC3G,SAAS,YAAY,CAAC,MAAmC;IACvD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAgD,CAAC;IAC3E,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;QACpC,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAC9B,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;SACpC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,EAAE;QAC3B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QAChF,OAAO;YACL,QAAQ;YACR,OAAO;YACP,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;YACtD,SAAS,EAAE,OAAO,CAAC,MAAM;SAC1B,CAAC;IACJ,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;AAC3F,CAAC;AAED,MAAM,OAAO,aAAa;IAChB,MAAM,CAAe;IAE7B,YAAY,MAAc,MAAM,CAAC,MAAM,CAAC,GAAG;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QACvD,MAAM,MAAM,GAAG,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;QAC1E,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE;gBAC7C,OAAO,EAAE;oBACP,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE;iBACjD;gBACD,cAAc,EAAE;oBACd,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE;iBAC1B;aACF,CAAC,CAAC;YACH,gCAAgC;YAChC,MAAM,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE;gBAC/C,UAAU,EAAE,QAAQ;gBACpB,YAAY,EAAE,SAAS;aACxB,CAAC,CAAC;YACH,6DAA6D;YAC7D,MAAM,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,UAAU,EAAE;gBAC/C,UAAU,EAAE,MAAM;gBAClB,YAAY,EAAE;oBACZ,IAAI,EAAE,MAAM;oBACZ,SAAS,EAAE,MAAM;oBACjB,SAAS,EAAE,IAAI;iBAChB;aACF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,MAKG;QAEH,yBAAyB;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC;YACvC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;gBACnC,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACxB,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,MAAM,EAAE;wBACN,KAAK,EAAE,CAAC,CAAC,KAAK;wBACd,IAAI,EAAE,CAAC,CAAC,MAAM;qBACf;oBACD,OAAO,EAAE,CAAC,CAAC,OAAO;iBACnB,CAAC,CAAC;aACJ,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CACV,MAAgB,EAChB,KAAK,GAAG,CAAC,EACT,YAAqB;QAErB,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAErE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE;YAClD,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,OAAO;YACd,KAAK;YACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,IAAY,EACZ,KAAK,GAAG,CAAC,EACT,YAAqB;QAErB,uEAAuE;QACvE,MAAM,IAAI,GAAgC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7E,IAAI,YAAY,EAAE,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC;QAC/D,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;YACnD,MAAM,EAAE,EAAE,IAAI,EAAE;YAChB,KAAK;YACL,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,KAAK;SACnB,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,QAAkB,EAClB,SAAkD,EAClD,KAAK,GAAG,CAAC,EACT,YAAqB;QAErB,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAErE,MAAM,QAAQ,GAA0B;YACtC;gBACE,KAAK,EAAE,QAAQ;gBACf,KAAK,EAAE,OAAO;gBACd,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;gBAC1B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B;SACF,CAAC;QAEF,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,MAAM;gBACb,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC;gBAC1B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9B,CAAC,CAAC;QACL,CAAC;QAED,sEAAsE;QACtE,0EAA0E;QAC1E,0EAA0E;QAC1E,wEAAwE;QACxE,kBAAkB;QAClB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE;YAClD,QAAQ;YACR,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;YACxB,KAAK,EAAE,KAAK,GAAG,UAAU;YACzB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC,MAAM;aAClB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;aAC/E,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAC7E,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;aACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,MAAc;QACjC,2EAA2E;QAC3E,wCAAwC;QACxC,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;YACnC,IAAI,EAAE,IAAI;YACV,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;SAC7B,CAAC,CAAC;IACL,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,cAAc;QAClB,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QACvD,IAAI,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACzD,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC;YACpC,QAAQ,EAAE,IAAI,CAAC,cAAc;SAC9B,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAAC,MAAc,EAAE,KAAK,GAAG,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;YAClD,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;YAC5B,KAAK;YACL,YAAY,EAAE,IAAI;YAClB,WAAW,EAAE,KAAK;SACnB,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,kBAAkB;QACtB,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;YACjF,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC;SACtC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;QACzC,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QACvE,yFAAyF;QACzF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACvF,IAAI,OAAO,GAAG,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC;QAC/E,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/services/versions.js

@@ -0,0 +1,73 @@
+/**
+ * Version helpers. Reads the repo-root VERSION file + package.json so
+ * the CLI, MCP server, and health check all surface the same numbers.
+ *
+ * Three axes track independently — see VERSION for definitions.
+ */
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+const SELF_DIR = dirname(fileURLToPath(import.meta.url));
+// dist/services/ at runtime, src/services/ during tests — both walk up 2.
+const REPO_ROOT = resolve(SELF_DIR, "..", "..");
+const VERSION_KEYS = [
+    ["KB_DATA_VERSION", "kb_data"],
+    ["KB_SCHEMA_VERSION", "kb_schema"],
+    ["MCP_TOOL_VERSION", "mcp_tool"],
+];
+const PackageJson = z.object({ version: z.string() });
+function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The file's text, or null when it cannot be read. A missing file is
+ * expected in a partial install and stays quiet; any other failure is
+ * reported on stderr (never stdout: the MCP server reaches this).
+ */
+function readOptional(name) {
+    try {
+        return readFileSync(resolve(REPO_ROOT, name), "utf-8");
+    }
+    catch (err) {
+        const code = err instanceof Error && "code" in err ? err.code : undefined;
+        if (code !== "ENOENT")
+            console.error(`[versions] cannot read ${name}: ${message(err)}`);
+        return null;
+    }
+}
+function parseVersionFile(txt, v) {
+    for (const line of txt.split("\n")) {
+        for (const [key, field] of VERSION_KEYS) {
+            const value = line.startsWith(`${key}=`) ? line.slice(key.length + 1).trim() : "";
+            if (value)
+                v[field] = value;
+        }
+    }
+}
+function parsePackageVersion(txt) {
+    try {
+        const parsed = PackageJson.safeParse(JSON.parse(txt));
+        return parsed.success ? parsed.data.version : null;
+    }
+    catch (err) {
+        console.error(`[versions] package.json is not valid JSON: ${message(err)}`);
+        return null;
+    }
+}
+let cached = null;
+export function getVersions() {
+    if (cached)
+        return cached;
+    const v = { kb_data: "?", kb_schema: "?", mcp_tool: "?", package: "?" };
+    const versionTxt = readOptional("VERSION");
+    if (versionTxt !== null)
+        parseVersionFile(versionTxt, v);
+    const pkgTxt = readOptional("package.json");
+    const pkgVersion = pkgTxt === null ? null : parsePackageVersion(pkgTxt);
+    if (pkgVersion !== null)
+        v.package = pkgVersion;
+    cached = v;
+    return v;
+}
+//# sourceMappingURL=versions.js.map

package/dist/services/versions.js.map

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

package/dist/services/vice-bin.js

@@ -0,0 +1,51 @@
+/**
+ * Which x64sc to run.
+ *
+ * The GTK build of VICE opens a window on every launch and takes the
+ * desktop's focus; a verifier pass over sixty recipes makes that constant.
+ * VICE 3.10 also builds a headless front end (--enable-headlessui) with no
+ * window at all whose exit screenshots are byte-identical to the GTK build's
+ * (measured 2026-09-22 on the pinned recipes, PAL and NTSC, disk-backed
+ * included). `npm run vice:headless` builds one into .tools/vice-headless/
+ * and everything that launches the emulator picks it up from here.
+ *
+ * Order: X64SC_BIN if set; the repo's own headless build if present; the
+ * x64sc on PATH, which is almost certainly the windowed one.
+ */
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+const here = path.dirname(fileURLToPath(import.meta.url));
+// src/services or dist/services: the repo root is two levels up either way.
+const repoRoot = path.resolve(here, "..", "..");
+const HEADLESS_X64SC = path.join(repoRoot, ".tools", "vice-headless", "bin", "x64sc");
+export function resolveX64sc() {
+    const env = process.env.X64SC_BIN;
+    if (env && existsSync(env))
+        return { path: env, kind: "env", windowed: false };
+    if (existsSync(HEADLESS_X64SC))
+        return { path: HEADLESS_X64SC, kind: "headless", windowed: false };
+    try {
+        const found = execSync("which x64sc", { stdio: ["ignore", "pipe", "ignore"] })
+            .toString()
+            .trim();
+        if (found)
+            return { path: found, kind: "path", windowed: true };
+    }
+    catch {
+        // no x64sc anywhere
+    }
+    return null;
+}
+/** One line for a script's banner, so a windowed run is never a surprise. */
+export function describeX64sc(choice) {
+    if (!choice)
+        return "x64sc: not found (set X64SC_BIN or run `npm run vice:headless`)";
+    if (choice.kind === "env")
+        return `x64sc: ${choice.path} (X64SC_BIN)`;
+    if (choice.kind === "headless")
+        return `x64sc: ${choice.path} (windowless build)`;
+    return `x64sc: ${choice.path} (PATH; this build opens a window per run; "npm run vice:headless" builds one that does not)`;
+}
+//# sourceMappingURL=vice-bin.js.map