c64-kb 0.17.0

package/dist/tools/query/recipes.js

@@ -0,0 +1,214 @@
+/**
+ * Recipe tools: one recipe with its listing, and the recipe index by
+ * toolchain, region, technique or file format.
+ */
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+import { getFalkor, getAnalytics } from "../../context.js";
+import { config } from "../../config.js";
+import { effectiveChips } from "../../graph/machine-variants.js";
+import { describeFilter, names, parseRows, searchChunks, suggestNames, toDocChunk } from "./shared.js";
+const VerifiedOnRow = z.object({
+    variant: z.string(),
+    vic: z.string(),
+    sid: z.string(),
+    cia: z.string(),
+    region: z.string(),
+    model: z.string(),
+    cycles: z.number().int(),
+    shot: z.string(),
+    flags: z.string(),
+    pinned: z.boolean(),
+});
+/**
+ * The runs of one recipe, each with the chips it actually had: a chip flag
+ * in runs.json (cia-revision-detect's `-ciamodel 0`) replaces the variant's
+ * chip, and `overrides` says which.
+ */
+async function verifiedOnOf(name) {
+    const f = await getFalkor();
+    const rows = parseRows(VerifiedOnRow, await f.roQuery(`MATCH (:Recipe {name: $name})-[e:VERIFIED_ON]->(v:MachineVariant)
+       RETURN v.name AS variant, v.vic AS vic, v.sid AS sid, v.cia AS cia, v.region AS region,
+              e.model AS model, e.cycles AS cycles, e.shot AS shot, e.flags AS flags, e.pinned AS pinned
+       ORDER BY variant`, { name }));
+    return rows.map((r) => ({ ...r, ...effectiveChips(r, r.flags) }));
+}
+function verifiedOnText(rows) {
+    if (rows.length === 0)
+        return `**Verified on:** no VICE run is compared with a committed screenshot for this recipe\n`;
+    const parts = rows.map((v) => `${v.variant} (${v.vic}, ${v.sid}, ${v.cia}; runs.json "${v.model}"${v.flags ? ` ${v.flags}` : ""}${v.overrides.length ? `; the flags replace the variant's chips: ${v.overrides.join(", ")}` : ""}) at ${v.cycles.toLocaleString("en-GB")} cycles${v.pinned ? "" : ", no pinned run: verify:recipes defaults"}`);
+    return `**Verified on:** ${parts.join("; ")}. verify:recipes compares each run's exit screenshot with ${rows.map((v) => v.shot).join(", ")} pixel for pixel\n`;
+}
+const RecipeRow = z.object({
+    toolchain: z.string(),
+    output_format: z.string(),
+    region: z.string(),
+    source_doc: z.string(),
+    toolchain_version_verified: z.string().nullable(),
+});
+async function recipeNotFound(name) {
+    const f = await getFalkor();
+    const all = names(await f.roQuery(`MATCH (r:Recipe) RETURN r.name AS name ORDER BY r.name`));
+    const suggestions = suggestNames(name, all, "-");
+    getAnalytics().logQuery({ tool: "c64_recipe_lookup", query: name, resultCount: 0 });
+    const empty = {
+        name: "",
+        toolchain: "",
+        output_format: "",
+        region: "",
+        source_doc: "",
+        documentation: [],
+    };
+    const text = `Recipe \`${name}\` not found.${suggestions.length > 0 ? `\n\nDid you mean: ${suggestions.join(", ")}?` : ""}\n\nList all recipes with \`c64-kb recipes-for\` (no filter).`;
+    return { structured: empty, text };
+}
+export async function recipeLookup(name) {
+    const f = await getFalkor();
+    const row = parseRows(RecipeRow, await f.roQuery(`MATCH (r:Recipe {name: $name})
+       OPTIONAL MATCH (r)-[:REQUIRES_TOOL]->(tool:Tool)
+       RETURN r.toolchain AS toolchain, r.output_format AS output_format,
+              r.region AS region, r.source_doc AS source_doc,
+              tool.version_verified AS toolchain_version_verified`, { name })).at(0);
+    if (!row)
+        return recipeNotFound(name);
+    const { toolchain, output_format, region, source_doc } = row;
+    const toolchain_version_verified = row.toolchain_version_verified ?? undefined;
+    // Pull doc context
+    const { chunks: ctx } = await searchChunks({ query: name, limit: 5 });
+    const documentation = ctx
+        .filter((c) => c.source === source_doc)
+        .slice(0, 5)
+        .map(toDocChunk);
+    getAnalytics().logQuery({ tool: "c64_recipe_lookup", query: name, resultCount: 1 });
+    // The listing itself. The vector chunks carry Build, Synopsis and Expected
+    // output; a caller with no file access (an MCP client on another machine,
+    // or a small model that will not open a page) could never copy the code.
+    // Three of the night's build arms proved it: the two that read the page
+    // file shipped the recipe, the one that trusted this answer built from
+    // prose (2026-09-22).
+    const source_code = readRecipeListing(source_doc);
+    const verified_on = await verifiedOnOf(name);
+    const structured = {
+        name,
+        toolchain,
+        output_format,
+        region,
+        source_doc,
+        ...(toolchain_version_verified ? { toolchain_version_verified } : {}),
+        documentation,
+        ...(source_code ? { source_code } : {}),
+        verified_on,
+    };
+    let out = `# Recipe: ${name}\n\n`;
+    out += `**Toolchain:** ${toolchain}${toolchain_version_verified ? ` (the repo's gates build it with ${toolchain_version_verified})` : ""}\n`;
+    out += `**Output:** ${output_format}\n`;
+    out += `**Region:** ${region}\n`;
+    out += `**Source:** \`${source_doc}\`\n`;
+    out += `${verifiedOnText(verified_on)}\n`;
+    for (const d of documentation) {
+        out += `## ${d.section}\n${d.text}\n\n---\n\n`;
+    }
+    if (source_code)
+        out += renderListing(source_code);
+    return { structured, text: out };
+}
+function renderListing(source_code) {
+    const { language, text } = source_code;
+    return (`## Source listing (${language}, ${text.split("\n").length} lines, copy as-is)\n\n` +
+        "```" +
+        language +
+        "\n" +
+        text +
+        (text.endsWith("\n") ? "" : "\n") +
+        "```\n");
+}
+function isNotFound(err) {
+    return err instanceof Error && "code" in err && (err.code === "ENOENT" || err.code === "ENOTDIR");
+}
+/**
+ * The first buildable fence on a recipe page: its Source listing. The
+ * listing gate builds exactly this fence, so it is the code the pinned
+ * screenshot was made from. Returns null when the page is not on disk.
+ */
+function readRecipeListing(source_doc) {
+    let page;
+    try {
+        page = fs.readFileSync(path.join(config.docs.dir, source_doc), "utf-8");
+    }
+    catch (err) {
+        if (isNotFound(err))
+            return null;
+        throw err;
+    }
+    const m = /```(c|asm|kick|kickassembler|kickass)\r?\n([\s\S]*?)```/.exec(page);
+    if (!m)
+        return null;
+    const [, fence = "", text = ""] = m;
+    const language = fence === "kick" || fence === "kickassembler" || fence === "kickass" ? "asm" : fence;
+    return { language, text };
+}
+const RecipeListRow = RecipeRow.omit({ toolchain_version_verified: true }).extend({ name: z.string() });
+function recipesForCypher(filter) {
+    const where = [];
+    const params = {};
+    if (filter.toolchain) {
+        where.push("r.toolchain = $toolchain");
+        params.toolchain = filter.toolchain;
+    }
+    if (filter.region) {
+        where.push("(r.region = $region OR r.region = 'both')");
+        params.region = filter.region;
+    }
+    let cypher = `MATCH (r:Recipe)`;
+    if (filter.technique) {
+        cypher += ` -[:IMPLEMENTS]-> (t:Technique {name: $technique})`;
+        params.technique = filter.technique;
+    }
+    if (filter.file_format) {
+        cypher += ` , (r)-[:PRODUCES]->(f:FileFormat {name: $file_format})`;
+        params.file_format = filter.file_format;
+    }
+    if (filter.verified_on) {
+        cypher += ` MATCH (r)-[:VERIFIED_ON]->(vv:MachineVariant)`;
+        where.push("(vv.name = $verified_on OR toUpper(vv.region) = toUpper($verified_on))");
+        params.verified_on = filter.verified_on;
+    }
+    if (where.length > 0)
+        cypher += ` WHERE ${where.join(" AND ")}`;
+    cypher += ` WITH DISTINCT r RETURN r.name AS name, r.toolchain AS toolchain, r.output_format AS output_format, r.region AS region, r.source_doc AS source_doc ORDER BY r.name`;
+    return { cypher, params };
+}
+export async function recipesFor(filter) {
+    const f = await getFalkor();
+    const { cypher, params } = recipesForCypher(filter);
+    const recipes = parseRows(RecipeListRow, await f.roQuery(cypher, params)).map((r) => ({
+        name: r.name,
+        toolchain: r.toolchain,
+        output_format: r.output_format,
+        region: r.region,
+        source_doc: r.source_doc,
+    }));
+    getAnalytics().logQuery({
+        tool: "c64_recipes_for",
+        query: JSON.stringify(filter),
+        resultCount: recipes.length,
+    });
+    const structured = { filter, recipes };
+    let out = `# Recipes`;
+    const flt = describeFilter({ ...filter });
+    if (flt)
+        out += ` (filter: ${flt})`;
+    out += `\n\n`;
+    if (recipes.length === 0) {
+        out += `No recipes match. Try a broader filter or no filter at all.`;
+    }
+    else {
+        out += `| Recipe | Toolchain | Output | Region |\n|--------|-----------|--------|--------|\n`;
+        for (const r of recipes) {
+            out += `| ${r.name} | ${r.toolchain} | ${r.output_format} | ${r.region} |\n`;
+        }
+    }
+    return { structured, text: out };
+}
+//# sourceMappingURL=recipes.js.map

package/dist/tools/query/recipes.js.map

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

package/dist/tools/query/retrieval.js

@@ -0,0 +1,128 @@
+/**
+ * Tools that answer from the document vectors: free search, opcode
+ * lookup, PAL/NTSC differences and the toolchain hint.
+ */
+import { z } from "zod";
+import { getFalkor, getAnalytics } from "../../context.js";
+import { parseRows, renderDocBlocks, searchChunks, toDocChunk } from "./shared.js";
+function confidenceLabel(score, isVector) {
+    if (!isVector)
+        return "UNSCORED";
+    if (score >= 0.7)
+        return "HIGH";
+    if (score >= 0.4)
+        return "MEDIUM";
+    return "LOW";
+}
+function normalizeQuery(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+export async function search(query, limit = 5, filterSource) {
+    const normalized = normalizeQuery(query);
+    const { chunks: results, isVector } = await searchChunks({ query: normalized, limit, filterSource });
+    getAnalytics().logQuery({
+        tool: "c64_search",
+        query,
+        resultCount: results.length,
+        searchMode: isVector ? "vector" : "keyword",
+        resultScores: results.map((r) => r.score),
+        resultSources: results.map((r) => r.source),
+    });
+    const hits = results.map((r) => ({
+        ...toDocChunk(r),
+        confidence: confidenceLabel(r.score, isVector),
+    }));
+    const structured = { query, hits };
+    if (results.length === 0) {
+        return { structured, text: `No results for: "${query}". This gap has been logged.` };
+    }
+    const text = hits
+        .map((h) => `## [${h.confidence}] ${h.source} > ${h.section}\n` + `(score: ${h.score.toFixed(3)})\n\n${h.text}`)
+        .join("\n\n---\n\n");
+    return { structured, text };
+}
+export async function lookupOpcode(byteOrMnemonic) {
+    // The opcode docs use `### $XX — MNEMONIC #addressing — description` headings, so
+    // we search for the byte form or the mnemonic and rank by score.
+    const term = byteOrMnemonic.trim().toUpperCase();
+    const { chunks: results } = await searchChunks({
+        query: `6510 opcode ${term}`,
+        limit: 5,
+        keywordText: term,
+    });
+    // Prefer results from the opcode docs
+    const opcodeDocs = results.filter((r) => r.source.includes("6510-cpu") || r.source.includes("illegal-opcodes"));
+    const final = opcodeDocs.length > 0 ? opcodeDocs : results;
+    getAnalytics().logQuery({ tool: "c64_lookup_opcode", query: byteOrMnemonic, resultCount: final.length });
+    const top = final.slice(0, 3);
+    const structured = { query: byteOrMnemonic, results: top.map(toDocChunk) };
+    if (final.length === 0) {
+        return {
+            structured,
+            text: `No opcode information found for "${byteOrMnemonic}".\n\n` +
+                `Try \`c64_search\` for fuzzy lookup, or use a mnemonic like "LDA" or a byte like "$A9".`,
+        };
+    }
+    return { structured, text: `# Opcode lookup: ${byteOrMnemonic}\n\n${renderDocBlocks(top, "##")}` };
+}
+const RegionRow = z.object({ name: z.string(), hz: z.number(), lines: z.number(), cycles: z.number() });
+export async function palNtscDiff(topic, region = "both") {
+    const f = await getFalkor();
+    const regionRows = await f.roQuery(`MATCH (r:Region) RETURN r.name AS name, r.refresh_hz AS hz,
+            r.lines_per_frame AS lines, r.cycles_per_line AS cycles
+     ORDER BY r.name`);
+    const queryStr = region === "both" ? `PAL NTSC ${topic}` : `${region.toUpperCase()} ${topic}`;
+    const { chunks: ctx } = await searchChunks({ query: queryStr, limit: 5 });
+    getAnalytics().logQuery({ tool: "c64_pal_ntsc_diff", query: topic, resultCount: ctx.length });
+    const allRegions = parseRows(RegionRow, regionRows).map((row) => ({
+        name: row.name,
+        refresh_hz: row.hz,
+        lines_per_frame: row.lines,
+        cycles_per_line: row.cycles,
+    }));
+    const regions = region === "both" ? allRegions : allRegions.filter((r) => r.name.toLowerCase() === region);
+    const top = ctx.slice(0, 3);
+    const structured = { topic, regions, documentation: top.map(toDocChunk) };
+    let out = `# PAL vs NTSC — ${topic}\n\n`;
+    out += `## Regions\n\n| Region | Refresh | Lines | Cycles/line |\n|--------|---------|-------|-------------|\n`;
+    for (const r of regions) {
+        out += `| ${r.name} | ${r.refresh_hz} Hz | ${r.lines_per_frame} | ${r.cycles_per_line} |\n`;
+    }
+    if (ctx.length > 0) {
+        out += `\n## Topic-specific documentation\n\n${renderDocBlocks(top)}`;
+    }
+    return { structured, text: out };
+}
+const OSCAR64_BIAS = "oscar64";
+export async function toolchainHint(toolchain, intent) {
+    const tc = toolchain ?? OSCAR64_BIAS;
+    const { chunks: ctx } = await searchChunks({ query: `${tc} ${intent}`, limit: 5 });
+    getAnalytics().logQuery({ tool: "c64_toolchain_hint", query: `${tc}:${intent}`, resultCount: ctx.length });
+    const sources = ctx.slice(0, 3).map(toDocChunk);
+    const top = sources.at(0);
+    const related = sources.slice(1);
+    const rationale = toolchain === undefined
+        ? `No toolchain specified; defaulting to ${OSCAR64_BIAS} per c64-kb's primary-toolchain policy. Pass toolchain explicitly to override.`
+        : `Toolchain ${tc} requested.`;
+    const structured = {
+        toolchain: tc,
+        intent,
+        snippet: top ? top.text : "(no snippet found — consider adding a recipe or pattern doc)",
+        rationale,
+        sources,
+    };
+    let out = `# Toolchain hint: ${tc} — ${intent}\n\n${rationale}\n\n`;
+    if (!top) {
+        out += `No idiomatic snippet found in the KB. This is a coverage gap — consider adding a recipe under \`docs/recipes/${tc}/\`.\n`;
+    }
+    else {
+        out += `## Canonical snippet (top match)\n\n${top.text}\n\n`;
+        if (related.length > 0) {
+            out += `## Related context\n\n`;
+            for (const s of related)
+                out += `### ${s.source} > ${s.section}\n${s.text}\n\n---\n\n`;
+        }
+    }
+    return { structured, text: out };
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/tools/query/retrieval.js.map

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

package/dist/tools/query/shared.js

@@ -0,0 +1,121 @@
+/**
+ * Helpers shared by the query tools: the BM25 encoder, the hybrid
+ * document search every lookup ends with, row validation for graph
+ * results, and the small formatters the renderers have in common.
+ */
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+import { getQdrant } from "../../context.js";
+import { embed } from "../../services/embeddings.js";
+import { BM25Encoder } from "../../services/bm25.js";
+import { config } from "../../config.js";
+const VOCAB_FILE = path.resolve(config.analytics.dbPath, "../bm25-vocab.json");
+const VocabFileSchema = z.object({
+    vocab: z.array(z.tuple([z.string(), z.number()])),
+    df: z.array(z.tuple([z.number(), z.number()])),
+    avgDocLen: z.number(),
+    numDocs: z.number(),
+    k1: z.number(),
+    b: z.number(),
+});
+let bm25Cache; // undefined = not yet attempted
+function getBM25() {
+    if (bm25Cache !== undefined)
+        return bm25Cache;
+    bm25Cache = null;
+    if (!fs.existsSync(VOCAB_FILE))
+        return null;
+    try {
+        const data = VocabFileSchema.parse(JSON.parse(fs.readFileSync(VOCAB_FILE, "utf-8")));
+        bm25Cache = BM25Encoder.fromJSON(data);
+    }
+    catch (err) {
+        // A corrupt vocab file degrades search to dense-only; say so on stderr.
+        console.error(`[query] ${VOCAB_FILE} unreadable, sparse vectors off: ${String(err)}`);
+    }
+    return bm25Cache;
+}
+function encodeSparse(text) {
+    const enc = getBM25();
+    return enc ? enc.encode(text) : { indices: [], values: [] };
+}
+/**
+ * Hybrid (dense + BM25) search, or the keyword index when the embedder is
+ * down. `keywordText` is what the keyword fallback searches for when it
+ * differs from the dense query.
+ */
+export async function searchChunks(opts) {
+    const q = await getQdrant();
+    const vector = await embed(opts.query);
+    const chunks = vector
+        ? await q.hybridSearch(vector, encodeSparse(opts.query), opts.limit, opts.filterSource)
+        : await q.searchByText(opts.keywordText ?? opts.query, opts.limit, opts.filterSource);
+    return { chunks, isVector: vector !== null };
+}
+/**
+ * Strip the leading "${section}\n\n" prefix from a chunk's stored
+ * text so it isn't rendered twice (once in the formatter heading,
+ * once at the top of the body). Phase 1.5 prepended the prefix to
+ * the stored text so the Qdrant text index catches heading tokens;
+ * the display layer strips it back out.
+ */
+function stripSectionPrefix(section, text) {
+    const prefix = `${section}\n\n`;
+    return text.startsWith(prefix) ? text.slice(prefix.length) : text;
+}
+/** A chunk as the structured outputs carry it: section prefix removed. */
+export function toDocChunk(c) {
+    return {
+        source: c.source,
+        section: c.section,
+        text: stripSectionPrefix(c.section, c.text),
+        score: c.score,
+    };
+}
+/** `### source > section` blocks separated by rules, as the lookups print them. */
+export function renderDocBlocks(chunks, heading = "###") {
+    return chunks
+        .map((c) => `${heading} ${c.source} > ${c.section}\n${stripSectionPrefix(c.section, c.text)}\n\n---\n\n`)
+        .join("");
+}
+/**
+ * Validate graph rows against a schema. FalkorDB returns untyped rows; a
+ * row that does not match is a graph defect, so this throws with the path.
+ */
+export function parseRows(schema, result) {
+    return z.array(schema).parse(result.data);
+}
+/** Rows that carry one `name` column. */
+const NameRow = z.object({ name: z.string().nullable() });
+export function names(result) {
+    return parseRows(NameRow, result)
+        .map((r) => r.name)
+        .filter((n) => Boolean(n));
+}
+/** "k=v, k=v" over the keys of a filter that were given. */
+export function describeFilter(filter) {
+    return Object.entries(filter)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${v ?? ""}`)
+        .join(", ");
+}
+/**
+ * Up to five names that contain the query, or whose tail after the first
+ * `sep`-separated word the query contains. Nothing for queries under
+ * three characters.
+ */
+export function suggestNames(query, all, sep) {
+    if (query.length < 3)
+        return [];
+    const lname = query.toLowerCase();
+    return all
+        .filter((n) => {
+        if (n.includes(lname))
+            return true;
+        const stem = n.split(sep).slice(1).join(sep);
+        return stem !== "" && lname.includes(stem);
+    })
+        .slice(0, 5);
+}
+//# sourceMappingURL=shared.js.map

package/dist/tools/query/shared.js.map

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