c64-kb 0.17.0

package/dist/server/tools-recipes.js

@@ -0,0 +1,296 @@
+/** Toolchain, recipe and technique tools. */
+import { z } from "zod";
+import { toolchainHint, recipeLookup, recipesFor, techniqueLookup, techniquesFor, checkCompatibility, timingBudget, planBudgetTool as planBudgetRun, budgetRegion, BUDGET_REGION, } from "../tools/query.js";
+import { ToolchainHintSchema, RecipeLookupSchema, RecipesForSchema, TechniqueLookupSchema, TechniquesForSchema, CompatibilityCheckSchema, TimingBudgetSchema, PlanBudgetSchema, } from "../schemas/tool-outputs.js";
+import { defineTool, READ_ONLY } from "./define-tool.js";
+import { definedOnly } from "./defined-only.js";
+export const toolchainHintTool = defineTool({
+    name: "c64_toolchain_hint",
+    title: "Toolchain-idiomatic snippet",
+    description: `Surface an idiomatic code snippet for a (toolchain, intent) pair. Defaults to Oscar64 when no toolchain is specified — c64-kb's primary-toolchain bias enforcer.
+
+Purpose: Returns a ranked set of documentation chunks most relevant to the intent, scoped to the requested toolchain. The structured output carries the snippet text plus the bias-rationale string so the consuming agent can surface it to the user.
+
+Inputs: 'toolchain' is optional (oscar64 | kickassembler | cc65). Omitting it triggers the Oscar64 default and annotates the rationale. 'intent' is a free-form description of what you want to do (e.g. "raster irq", "sprite multiplex", "disk load").
+
+Output: {toolchain, intent, snippet, rationale, sources[]}. 'snippet' is the text of the top-matching chunk. 'rationale' explains the toolchain choice. 'sources' carries up to 3 ranked chunks.
+
+When to use: When you need toolchain-idiomatic code patterns rather than hardware-register semantics. For register/opcode/kernal questions use the dedicated lookup tools.
+
+Examples: {"intent": "raster irq"} → Oscar64 rasterirq.h snippet. {"toolchain": "kickassembler", "intent": "raster irq"} → KickAssembler raster setup.
+
+See also: c64_recipe_lookup for complete buildable examples. c64_search for broad topic queries.
+
+Limitations: Snippet quality depends on corpus coverage. If a pattern doc is missing, the rationale will note a coverage gap. Does not execute or validate code.`,
+    inputSchema: {
+        toolchain: z
+            .enum(["oscar64", "kickassembler", "cc65"])
+            .optional()
+            .describe("Target toolchain (default: oscar64)"),
+        intent: z.string().describe("What you want to do (e.g. 'raster irq', 'sprite multiplex', 'disk load')"),
+    },
+    outputSchema: ToolchainHintSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ toolchain, intent }) => toolchainHint(toolchain, intent),
+});
+export const recipeLookupTool = defineTool({
+    name: "c64_recipe_lookup",
+    title: "Look up a buildable recipe",
+    description: `Look up a complete, buildable C64 recipe by canonical name (e.g. 'oscar64-hello-world'). Returns structured metadata plus the recipe doc body (synopsis, source, build command, expected output, rationale).
+
+Purpose: Gives the agent a ready-to-use, verified example with build instructions rather than requiring it to synthesize code from raw documentation chunks.
+
+Inputs: 'name' is the canonical recipe identifier — toolchain prefix + hyphen + recipe slug (e.g. 'oscar64-hello-world', 'kickassembler-hello-world', 'cc65-hello-world-conio'). Case-sensitive.
+
+Output: {name, toolchain, output_format, region, source_doc, toolchain_version_verified?, documentation[], source_code?, verified_on[{variant, vic, sid, cia, region, model, cycles, shot, flags, pinned, overrides[]}]}. toolchain_version_verified is the toolchain version this repo's gates built the recipe with (e.g. '5.25' for KickAssembler); a different version may or may not build it. verified_on lists the VICE machine variants verify:recipes runs the recipe on and compares with a committed screenshot pixel for pixel (from docs/recipes/runs.json): a runs.json "pal" run is VICE's default machine, which is the c64c variant (VIC-II 8565, SID 8580, CIA 8521), not a 6569; "ntsc" is the 6567R8 with a 6581 and 6526. vic, sid and cia are the chips the run had: a chip flag in 'flags' (-ciamodel, -cia1model, -cia2model, -sidmodel, -VICIImodel) replaces the variant's chip, and 'overrides' names each one replaced (cia-revision-detect runs the c64c with -ciamodel 0, so its CIA is the 6526). pinned false means the run uses verify:recipes' defaults. An empty list means no run is compared. On not-found, 'name' is empty and 'text' lists near-match suggestions.
+
+When to use: When you know the specific recipe name or have already identified the toolchain + intent from c64_toolchain_hint and want a complete worked example.
+
+Examples: {"name": "oscar64-hello-world"} returns the Oscar64 hello-world recipe metadata + doc. {"name": "oscar64-hello"} returns not-found with 'oscar64-hello-world' as a suggestion.
+
+See also: c64_recipes_for to enumerate available recipes. c64_toolchain_hint for pattern snippets.
+
+Limitations: Only recipes explicitly ingested into the KB are available. Partial name matches trigger suggestions but do not auto-resolve.`,
+    inputSchema: {
+        name: z
+            .string()
+            .describe("Canonical recipe name (e.g. 'oscar64-hello-world', 'kickassembler-hello-world')"),
+    },
+    outputSchema: RecipeLookupSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ name }) => recipeLookup(name),
+});
+export const recipesForTool = defineTool({
+    name: "c64_recipes_for",
+    title: "List recipes by filter",
+    description: `List all recipes matching an optional set of filters: toolchain, region, technique, or file format. Returns a structured table of matching Recipe nodes from FalkorDB.
+
+Purpose: Lets the agent discover what buildable examples are available before committing to a specific recipe. All filters are optional — omitting all returns the full recipe catalog.
+
+Inputs: All optional. 'toolchain' is one of oscar64 | kickassembler | cc65. 'region' is pal | ntsc | both (note: recipes with region='both' appear for any region filter). 'verified_on' is a MachineVariant name (c64c, ntsc, oldntsc, ...) or a region word (PAL, NTSC): only recipes verify:recipes runs on that variant, or on any variant of that region. 'technique' is an exact Technique.title match (Phase 2: no techniques yet — omit for now). 'file_format' is an exact FileFormat.name match (e.g. 'PRG').
+
+Output: {filter, recipes[{name, toolchain, output_format, region, source_doc}]}. Empty recipes array means no matches — try a broader filter.
+
+When to use: Before calling c64_recipe_lookup, use this to discover what names exist. Also useful to audit coverage gaps.
+
+Examples: {"toolchain": "oscar64"} → table of all Oscar64 recipes. {} → full catalog. {"region": "pal"} → PAL-compatible recipes. {"verified_on": "oldntsc"} → the recipes run on the 6567R56A.
+
+See also: c64_recipe_lookup to fetch a specific recipe's full content. c64_toolchain_hint for pattern snippets without a complete recipe.
+
+Limitations: Returns graph metadata only — use c64_recipe_lookup to get the actual source code. technique filter is a no-op in Phase 2 (no Technique nodes yet).`,
+    inputSchema: {
+        toolchain: z.enum(["oscar64", "kickassembler", "cc65"]).optional().describe("Filter by toolchain"),
+        region: z
+            .enum(["pal", "ntsc", "both"])
+            .optional()
+            .describe("Filter by region (recipes with region='both' match any value)"),
+        technique: z.string().optional().describe("Filter by Technique title (exact match)"),
+        file_format: z.string().optional().describe("Filter by FileFormat name (e.g. 'PRG')"),
+        verified_on: z
+            .string()
+            .optional()
+            .describe("MachineVariant name (c64c, ntsc, oldntsc) or region word (PAL, NTSC): recipes run in VICE on it"),
+    },
+    outputSchema: RecipesForSchema.shape,
+    annotations: READ_ONLY,
+    run: (args) => recipesFor(definedOnly(args)),
+});
+export const techniqueLookupTool = defineTool({
+    name: "c64_technique_lookup",
+    title: "Look up a technique",
+    description: `Look up a Commodore 64 programming technique by canonical snake_case name (e.g. 'stable_raster_irq'). Returns technique metadata, chip, region requirements, all USES edges to Registers and KERNAL routines, the techniques it REQUIRES (must be set up before, or run underneath, it) and those that require it, the pitfalls it is the Fix for (MITIGATED_BY), the list of recipes that implement it, and the top documentation chunks.
+
+Guidelines: Use when you know a specific technique name and want its full profile — registers it touches, KERNAL calls it makes, what it presupposes (text_zoom requires stable_raster_irq on every scanline of its zone), and buildable recipe examples. For discovery ("what raster techniques exist?", "what builds on stable_raster_irq?"), use c64_techniques_for instead.
+
+Limitations: Returns structured data from FalkorDB; documentation chunks from Qdrant. Technique must be indexed (ingested from docs/techniques/). Partial or hyphenated names trigger a suggestion list.
+
+Param notes: 'name' is the exact snake_case Technique.name (e.g. 'stable_raster_irq', 'sprite_multiplex_8'). Case-sensitive.
+
+Expected length: 1 technique header + register/kernal/recipe lists + up to 3 doc chunks (~200-600 words total).
+
+Example: {"name": "stable_raster_irq"} returns the stable raster IRQ technique with its register list (D011, D012, D019), recipes, and documentation.
+
+Returns structured: {name, title, category, complexity, chip?, requires_region?, uses_registers[], uses_kernal[], recipes[], requires[{name,title}], required_by[{name,title}], mitigates[{name,title,severity}], documentation[], cost?}. requires/required_by are direct REQUIRES edges authored from **Requires:** lines (CONVENTIONS-techniques.md); a variant of a technique (double_irq of stable_raster_irq) is not a prerequisite and does not appear here. 'cost' is present only when the page carries a **Cost:** line: {cycles_per_line?, cycles_per_frame?, lines_active?, bytes_code?, bytes_data?, zp_bytes?, irq_slots?, basis}, integers, with only the keys the page stated; 'basis' is one of measured-vice, derived-listing, arithmetic, estimated and says how the figures were obtained (measured-vice means run in VICE; estimated means a judgement). Cycles are per PAL frame of 19,656 unless the page says otherwise; bytes are the built recipe's segments. 'claims' [{unit, mode, ranges?, relocatable?}] lists the HardwareUnits the technique holds (**Claims:** line; units such as sid_voice_2, sprite_0..7, vic_raster_irq, irq_vector_0314, zero_page with ranges like "E0-EF"); mode is owns, shares (writes under the owner's protocol), reads or init (once, before the frame loop). 'claims_stated' is stated, none (claims no unit) or unknown (the page states nothing: never read unknown as none); 'claims_basis' is measured-vice, derived-listing or estimated.`,
+    inputSchema: {
+        name: z
+            .string()
+            .describe("Canonical snake_case technique name (e.g. 'stable_raster_irq', 'sprite_multiplex_8')"),
+    },
+    outputSchema: TechniqueLookupSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ name }) => techniqueLookup(name),
+});
+export const techniquesForTool = defineTool({
+    name: "c64_techniques_for",
+    title: "List techniques by filter",
+    description: `List C64 techniques matching an optional set of filters: category, chip, region, register, recipe, requires, or claims. All filters are optional — omitting all returns the full technique catalog.
+
+Purpose: Lets the agent discover what techniques are documented before committing to a specific one. Use before c64_technique_lookup to find the right technique name.
+
+Inputs: All optional. 'category' is one of raster | sprite | scroll | bitmap | effect | music | cpu | banking | loader. 'chip' is a chip name (e.g. 'VIC-II', 'SID'). 'region' is PAL or NTSC (techniques locked to that region by a REQUIRES_REGION edge). 'register' is a register name (e.g. 'D011') to find techniques that USE it. 'recipe' is a recipe canonical name to find what techniques it implements. 'requires' is a technique name to find what builds on it — techniques whose REQUIRES chain reaches it directly or through other techniques. 'claims' is a HardwareUnit name (e.g. 'sid_voice_3', 'vic_raster_irq', 'zero_page') to find the techniques that claim it in any mode; a technique whose page states no claims is not listed, which does not mean it leaves the unit alone.
+
+Output: {filter, techniques[{name, title, category, complexity}]}. Empty array means no matches.
+
+Examples: {"category": "raster"} → all raster techniques. {"chip": "VIC-II"} → ~30+ rows. {"register": "D011"} → techniques that use SCROLY. {"requires": "stable_raster_irq"} → every technique that presupposes a stable raster IRQ.
+
+See also: c64_technique_lookup for full profile of a specific technique.
+
+Limitations: region filter matches only techniques with an explicit REQUIRES_REGION edge (PAL/NTSC-locked). Most techniques work on both regions and won't appear in a region filter. The requires filter follows REQUIRES edges only and does not unify variants: double_irq is a variant of stable_raster_irq with no edge between them, so {"requires": "stable_raster_irq"} does not list sideborder_open (which requires double_irq) — ask for double_irq as well. Chains longer than twelve edges are not followed.`,
+    inputSchema: {
+        category: z
+            .string()
+            .optional()
+            .describe("Technique category (raster | sprite | scroll | bitmap | effect | music | cpu | banking | loader)"),
+        chip: z.string().optional().describe("Chip name (e.g. 'VIC-II', 'SID', '6510')"),
+        region: z
+            .string()
+            .optional()
+            .describe("Region requirement filter: PAL or NTSC (matches REQUIRES_REGION edge)"),
+        register: z
+            .string()
+            .optional()
+            .describe("Register name (e.g. 'D011') — returns techniques that USE this register"),
+        recipe: z
+            .string()
+            .optional()
+            .describe("Recipe canonical name — returns techniques that this recipe implements"),
+        requires: z
+            .string()
+            .optional()
+            .describe("Technique name — returns techniques whose REQUIRES chain reaches it (what builds on it)"),
+        claims: z
+            .string()
+            .optional()
+            .describe("HardwareUnit name (e.g. 'sid_voice_3', 'vic_raster_irq') — returns techniques with a CLAIMS edge to it"),
+    },
+    outputSchema: TechniquesForSchema.shape,
+    annotations: READ_ONLY,
+    run: (args) => techniquesFor(definedOnly(args)),
+});
+export const checkCompatibilityTool = defineTool({
+    name: "c64_check_compatibility",
+    title: "Check technique compatibility",
+    description: `Check whether two or more C64 techniques can be combined. Hard conflicts come from authored resource demands on the techniques (DEMANDS edges): two techniques that each need every CPU cycle on their lines, a cycle-exact technique against one that takes interrupts mid-frame, a constant-sprite-set technique against a multiplexer, a KERNAL-out technique against KERNAL calls, and PAL-vs-NTSC requirements. Soft conflicts come from shared registers and shared KERNAL routines. The check also takes each technique's REQUIRES closure — the techniques it must have set up underneath it — and runs the demand and unit rules between one technique's prerequisites and the other technique, reporting a hit as prerequisite_conflict with the rule that fired in underlying_kind and its own severity (hard, soft or info); a technique is never reported against a prerequisite it declared itself (kernal_clobbers_zp excepted, below), and no technique's own demand set is changed by this.
+
+Inputs: 'techniques' is an array of 2+ canonical technique names (snake_case). Order doesn't matter — all pairwise combinations are checked.
+
+Output: {techniques[], conflicts[], band_separated[], shared_infrastructure[], data_coverage[], verdict}. verdict is 'incompatible' if any hard conflict exists (each carries a 'resolution' saying how to separate the two, usually by raster region), 'warnings' if only soft conflicts exist, 'compatible' otherwise. A prerequisite_conflict names the input techniques in a/b, the implied ones in 'via', and the rule in 'underlying_kind'. shared_infrastructure gains a 'missing_prerequisite' entry (with required_by[]) for every technique the set leans on through REQUIRES without naming it. data_coverage says, per technique, how many registers, KERNAL routines and demands the graph holds for it — implied techniques appear with implied_by[]; a technique with known=false cannot conflict with anything by construction, and the verdict is silent about it rather than a clearance.
+
+Conflict kinds: cpu_exclusive, cpu_vs_irq, sprite_set, kernal_banked_out, serial_bus_busy (a resident fast loader against KERNAL disk I/O), region_mismatch (hard); shared_register, shared_kernal (soft); prerequisite_conflict (the severity of its underlying_kind).
+
+Unit claims (**Claims:** lines, CLAIMS edges to HardwareUnit nodes): unit_contention (hard: both own the same unit, e.g. two raster-IRQ owners, since there is one raster compare, or two owners of sprite_0..7); zero_page_overlap (hard, soft when either side is relocatable; 'shared' lists the bytes); unit_shared (soft: one owns and the other shares, e.g. SFX on voice 2 beside a music player, or stable_raster_irq, a way into a handler, beside a raster effect that owns the compare; a resident loader beside a VIC bank owner says not to write $DD00 raw); unit_read_while_driven (soft: one reads a port the other drives); init_order (info: one uses the unit once at start-up; info does not change the verdict). Between a technique and its own prerequisite, unit_contention and zero_page_overlap do not run, and unit_shared runs only when the sharer is the one that requires the owner. A prerequisite's claims on units its input holds are the input's and are not reported again. kernal_clobbers_zp (soft): one technique calls a KERNAL routine (**Uses kernal:**) whose zero-page may set (CLOBBERS_ZP, a static walk of the ROM through the power-on vectors, an upper bound) overlaps bytes the other claims; 'shared' lists the bytes and the routines. It also runs inside one input's own chain, the technique against itself and against its own prerequisites, since a KERNAL call clobbers the bytes whoever declared them; such a finding has a = b = that input (a prerequisite_conflict with the prerequisites in 'via' when they are involved). A routine hit already reported for the same inputs, routine and bytes is not repeated through a prerequisite. Only technique claims are checked: the zero-page bytes and vectors a recipe chooses are not yet (issue #22, step 8). data_coverage carries claims: stated | none | unknown per technique, and the text says for how many inputs claims are stated; an unknown claim set is never treated as "claims nothing", so a unit conflict with it cannot be ruled out.
+
+Examples: {"techniques": ["fli_image", "sprite_multiplex_24"]} → incompatible (cpu_vs_irq, sprite_set and unit_contention on vic_raster_irq; resolution: multiplex outside the FLI region, in one interrupt chain). {"techniques": ["stable_raster_irq", "raster_bars"]} → warnings (unit_shared on vic_raster_irq: the stable entry runs inside raster_bars' handler; shared registers). {"techniques": ["fli_image", "digi_4bit"]} → incompatible (cpu_vs_irq: continuous interrupts inside the FLI region).
+
+Raster bands: a technique page may state the raster lines it holds the CPU on (**Raster band:**, e.g. fli_image 45-250). When both techniques state line bands and they share no line, the line-sharing rules (cpu_exclusive, cpu_vs_irq through mid-frame IRQs or sprite-set changes, sprite_set) do not fire; the pair is listed in band_separated[] {a, b, a_band, b_band, rules[]} instead. A missing band, or one the program chooses ('movable'), keeps the conflict, and its rationale names the unknown side. data_coverage carries each technique's raster_band.
+
+Limitations: demands and prerequisites are authored per technique in docs/techniques (see CONVENTIONS-techniques.md); a technique without them only participates in the soft checks. Named techniques are checked as named even when one requires the other. Where bands are not stated, 'incompatible' means 'not on the same raster lines', and the resolution says so.`,
+    inputSchema: {
+        techniques: z
+            .array(z.string())
+            .min(2)
+            .describe("Array of 2+ canonical technique names to check (e.g. ['stable_raster_irq', 'raster_bars'])"),
+    },
+    outputSchema: CompatibilityCheckSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ techniques }) => checkCompatibility(techniques),
+});
+export const timingBudgetTool = defineTool({
+    name: "c64_timing_budget",
+    title: "Per-scanline cycle budget",
+    description: `Compute the per-scanline cycle budget for a C64 technique on a given region (PAL or NTSC). Returns the canonical cycle constants plus IRQ overhead and net user-available cycles.
+
+Purpose: Gives the agent the authoritative cycle math for raster-critical technique implementations. Use before writing or evaluating cycle-tight C64 raster code.
+
+Inputs: 'technique' is the canonical technique name (e.g. 'stable_raster_irq'). 'region' is 'pal' or 'ntsc' (case-insensitive). 'sprites_per_line' (optional, 0-8) is the number of sprites displayed on the line; without it the technique's own Cost sprites_per_line is used, and without that sprite DMA is not counted and a note says so.
+
+Output: {technique, region, cycles_per_line, cycles_per_frame, badline_cycles_lost, irq_overhead_cycles, sprites_per_line, sprites_source ('input' | 'technique' | 'none'), sprite_dma_cycles, user_cycles_per_line_normal, user_cycles_per_line_badline, notes[]}.
+
+Constants: PAL: 63 cycles/line × 312 lines = 19656 cycles/frame. NTSC: 65 cycles/line × 263 lines = 17095 cycles/frame. Badline: 43 cycles to plan on (the VIC holds the bus for cycles 15-54 and BA drops on cycle 12; only writes fit in 12-14). Default IRQ overhead: 36 cycles (7 interrupt sequence + 29 KERNAL dispatcher at $FF48 via $0314). Sprite DMA: 3 + 2 per sprite for sprites numbered without gaps (5 for one, 19 for eight, measured in VICE x64sc); each gap adds up to 3.
+
+Examples: {"technique": "stable_raster_irq", "region": "pal"} → cycles_per_line=63, user_cycles_per_line_normal=27, user_cycles_per_line_badline=0 (a handler entered on a badline through the KERNAL vector has nothing left on that line). {"technique": "stable_raster_irq", "region": "pal", "sprites_per_line": 8} → sprite_dma_cycles=19, user_cycles_per_line_normal=8.
+
+Limitations: irq_overhead is the default 36 cycles for every technique (an earlier version of this line said it was read from a Technique irq_overhead property; nothing writes one, and the read was removed in tools 1.25.0); a handler on $FFFE with the KERNAL banked out pays 7 plus its own register saves. An earlier version of this description said 23 badline cycles and 14 overhead, which was not what the tool computed. An earlier version did not subtract sprite DMA at all.`,
+    inputSchema: {
+        technique: z.string().describe("Canonical technique name (e.g. 'stable_raster_irq')"),
+        region: z
+            .string()
+            .optional()
+            .default("pal")
+            .describe("Region: 'pal' or 'ntsc' (case-insensitive, default: 'pal')"),
+        sprites_per_line: z
+            .number()
+            .int()
+            .min(0)
+            .max(8)
+            .optional()
+            .describe("Sprites displayed on the line (0-8). Overrides the technique's Cost sprites_per_line."),
+    },
+    outputSchema: TimingBudgetSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ technique, region, sprites_per_line }) => timingBudget({ technique, region, ...definedOnly({ sprites_per_line }) }),
+});
+export const planBudgetTool = defineTool({
+    name: "c64_plan_budget",
+    title: "Frame budget for a set of techniques",
+    description: `Add a set of techniques up against a frame, honestly: per phase and region, a cycle range, what was left out and why, what is unknown, and a verdict.
+
+Purpose: Answers "does this combination fit a frame?" before code is written. It does not sum blindly: a missing figure is never counted as zero, a figure above one frame is never summed, work one figure already includes is not counted twice, and every figure names the recipe it was measured on.
+
+Inputs: 'techniques' is a list of canonical technique names, each optionally with a phase: "name" (play), "name:play", "name:transition" (level decode, wipe) or "name:init" (one-off setup). Each phase is budgeted alone. 'design' is a GameDesign name (a whole game from docs/game-design/designs, e.g. "platformer_scaffold_oscar64"): its COMPOSES edges, each in its phase, are budgeted first, then any 'techniques' given; its region is the default. Give 'techniques', 'design' or both. 'region' is 'pal', 'ntsc' or 'both' (default: PAL unless every region-locked member is NTSC-locked). 'screen' is 'on' (default) or 'off'. 'sprites_per_line' (0-8) and 'sprite_lines' (default 200) charge sprite DMA, 3 + 2n cycles a line.
+
+Output: {design{name, title, region, instance_of[], realised_by[], composes[{technique, phase}], source_doc, measured[{phase, region, worst, typical, basis, source, predicted{low, high, fixed, verdict, missing[]}, position: below_low | within | within_incomplete | above_high | not_predicted, finding}]} | null, design_not_found?{requested, known[]}, techniques, refused[], region, screen, sprites, phases[{phase, region, frame, contributors[{name, low, high, every_frame, basis, charge, measured_on, conditions}], excluded[{name, reason: multi_frame | included_by | inside_band_of, by?, cycles?}], unknown[], not_found[], to_measure[{technique, recipe, why}], fixed_losses{badlines, sprite_dma, charged_for[], badlines_in_bands, floor}, worst_only[], low, high, floor, verdict, weakest_basis, irq_slots, notes[]}], bytes{sum, contributors, excluded (whole_program), inside[{name, by}], without_bytes}, verdict, assumptions[]}. A design's position places its measured worst against [low, high + fixed]: within_incomplete is inside that range while predicted.missing is non-empty, so the uncounted members could move the range past it and it is not agreement; above_high with members missing may be explained by them; below_low stands, since a missing member can only raise the range.
+
+Rules: low sums each member's cycles_per_frame_typical where the page states a measured one, else its cycles_per_frame; high sums cycles_per_frame (worst frames). A member with no cycles figure goes to unknown and to_measure, with the recipe to measure it on. A figure above the frame (19,656 PAL, 17,095 NTSC) is excluded as multi_frame. A member named in another's **Cost includes:**, followed through the graph (a includes b, b includes c), is excluded as included_by, unless the including member is itself multi-frame; of two members that include each other the first listed is kept. A name listed twice in one phase is counted once and the repeat is listed in refused. A technique that holds every cycle of a stated raster band (cycles_per_line 63 and a line band) is charged band lines × line length, and its REQUIRES closure in the set is excluded as inside_band_of. With the screen on, the badlines (lines 51-243, every eighth, 25 × 43 = 1,075 cycles) outside any band charge, and the stated sprite DMA, are charged as fixed losses unless every summed figure is a band charge or is measured with measured-on conditions that say the screen was on; a figure measured blanked, one that does not say, and an arithmetic, derived-listing or estimated one are all charged. A stall takes its cycles wherever the code runs, so the charge is exact when no summed figure already holds stalls and too high by what a screen-on figure holds; fixed_losses.floor is the part no figure can hold. The low end is not a floor: a typical figure is a common frame or a real run's worst, and worst_only lists members with no typical at all. floor is the band and per-line charges, which run every frame, plus fixed_losses.floor. Verdict per phase: fits when nothing is unknown, missing or multi-frame and high + fixed losses fit the frame; over when floor passes the frame; otherwise undetermined. The overall verdict is the worst phase's. Bytes flagged "(whole PRG)" on their measured-on line are not summed; a member whose work is inside another's figure that states bytes is listed in inside, not summed. 'region' other than pal, ntsc or both is refused.
+
+Examples: {"techniques": ["wave_director", "object_pool"]} → object_pool excluded (included_by wave_director); 1,170-3,188 plus 1,075 fixed, floor 1,075; fits. {"techniques": ["fli_image", "stable_raster_irq", "double_irq"]} → fli_image charged 207 lines × 63 = 13,041; the two prerequisites inside its band; all 25 badlines are inside the band, so no fixed loss. {"techniques": ["soft_scroll_h", "sid_play_routine_pattern"]} → soft_scroll_h multi_frame; undetermined. {"design": "falling_blocks_oscar64", "region": "pal"} → init and play phases; play undetermined (text_mode_overlay_render and others unknown); the design's measured PAL worst frame, 6,276 cycles, is set beside the predicted range with where it falls.
+
+See also: c64_timing_budget for the cycles left on one raster line; c64_check_compatibility for hardware claims, zero page and raster-line conflicts; c64_game_briefing, whose budget block uses the same rules on a proposed set in one play phase.
+
+Limitations: the figures are the pages' own, each measured on one recipe; a different implementation costs differently. Figures are mostly PAL measurements, judged against the NTSC frame unchanged. Claims, zero page and memory are not judged here. Most compositions give undetermined rather than over: only work that runs every frame is a floor.`,
+    inputSchema: {
+        techniques: z
+            .array(z.string())
+            .min(1)
+            .optional()
+            .describe('Technique names, each "name" or "name:phase" (phase: play, transition, init)'),
+        design: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("GameDesign name (e.g. 'platformer_scaffold_oscar64'): budgets its composed techniques by phase"),
+        region: z
+            .string()
+            .regex(BUDGET_REGION, "region is pal, ntsc or both")
+            .optional()
+            .describe("Region: 'pal', 'ntsc' or 'both' (case-insensitive; default PAL unless every region-locked member is NTSC)"),
+        screen: z.enum(["on", "off"]).optional().describe("Display on (default) or blanked"),
+        sprites_per_line: z
+            .number()
+            .int()
+            .min(0)
+            .max(8)
+            .optional()
+            .describe("Sprites displayed on each sprite line (0-8)"),
+        sprite_lines: z
+            .number()
+            .int()
+            .min(0)
+            .max(312)
+            .optional()
+            .describe("Raster lines with sprites on them (default 200)"),
+    },
+    outputSchema: PlanBudgetSchema.shape,
+    annotations: READ_ONLY,
+    run: ({ techniques, design, region, screen, sprites_per_line, sprite_lines }) => planBudgetRun({
+        ...definedOnly({
+            techniques,
+            design,
+            region: budgetRegion(region),
+            screen,
+            sprites_per_line,
+            sprite_lines,
+        }),
+    }),
+});
+//# sourceMappingURL=tools-recipes.js.map

package/dist/server/tools-recipes.js.map

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

package/dist/server/tools-runtime.js

@@ -0,0 +1,48 @@
+/** Runtime tools (the eval substrate): run a built PRG in VICE. */
+import { runGame, RunGameInputSchema, RunGameOutputSchema } from "../tools/run-game.js";
+import { defineTool } from "./define-tool.js";
+/** c64_run_game kills the x64sc on monitor port 6502 and starts a new one. */
+const RUN_GAME = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+};
+async function runGameReply(args) {
+    const r = await runGame(args);
+    const summary = `c64_run_game: ${r.exit_reason} after ${r.duration_ms}ms\n` +
+        `  state @ $${r.state_address.toString(16).padStart(4, "0")} (size ${r.state_size})\n` +
+        `  ${r.frames_observed} polls, ${r.inputs_fired}/${args.inputs.length} inputs fired\n` +
+        (r.error ? `  error: ${r.error}\n` : "") +
+        (r.final_screen ? `\n--- final screen ---\n${r.final_screen}\n` : "");
+    // A caught VICE failure comes back as exit_reason "error"; without
+    // isError an MCP client read it as success.
+    return { text: summary, structured: r, isError: r.exit_reason === "error" };
+}
+export const runGameTool = defineTool({
+    name: "c64_run_game",
+    title: "Run a PRG in VICE and trace its state",
+    description: `Spawn x64sc with -autostart for the given .prg, drive it via the parallel-input-cell harness pattern (writeMemory into the game's state struct), and return a state trace + final screen render. The eval substrate primitive — used to verify a built game reaches expected states.
+
+Inputs:
+  - prg_path (required): absolute path to the .prg to run
+  - dbj_path (required): absolute path to the matching .dbj (typed debug info; oscar64 -g produces this)
+  - state_symbol (optional, default "state"): top-level state struct symbol name
+  - state_read_len (optional, default 16): bytes to read per poll
+  - inputs (optional): scheduled writes into the state struct — each {after_ms, offset_in_state, bytes}. Use this to drive harness inputs (e.g. write 1 to state.start_request to simulate a "press fire").
+  - poll_every_ms (optional, default 250): state-polling cadence
+  - max_duration_ms (optional, default 20000): session hard cap
+  - autostart_wait_ms (optional, default 5000): time after x64sc launch before harness loop starts (lets autostart settle)
+  - capture_screen (optional, default true): render the final screen
+
+Output: structured RunGameOutput with state_address, state_size, frames_observed, inputs_fired, trace[{at_ms, bytes}], final_screen, exit_reason.
+
+Limitations: kills any existing x64sc on the machine to ensure clean state. Assumes x64sc binary is on PATH. Designed for the parallel-input-cell pattern (see loop/demo/unlock-trap.c); BP-driven games don't fit.
+
+Example: {"prg_path": "/.../unlock-trap.prg", "dbj_path": "/.../unlock-trap.dbj", "inputs": [{"after_ms": 1000, "offset_in_state": 9, "bytes": [1]}, {"after_ms": 2000, "offset_in_state": 8, "bytes": [1]}], "max_duration_ms": 8000}`,
+    inputSchema: RunGameInputSchema,
+    outputSchema: RunGameOutputSchema,
+    annotations: RUN_GAME,
+    run: runGameReply,
+});
+//# sourceMappingURL=tools-runtime.js.map

package/dist/server/tools-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-runtime.js","sourceRoot":"","sources":["../../src/server/tools-runtime.ts"],"names":[],"mappings":"AAAA,mEAAmE;AAGnE,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,UAAU,EAAkB,MAAM,kBAAkB,CAAC;AAE9D,8EAA8E;AAC9E,MAAM,QAAQ,GAAoB;IAChC,YAAY,EAAE,KAAK;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,KAAK;IACrB,aAAa,EAAE,KAAK;CACrB,CAAC;AAIF,KAAK,UAAU,YAAY,CAAC,IAAiB;IAC3C,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,OAAO,GACX,iBAAiB,CAAC,CAAC,WAAW,UAAU,CAAC,CAAC,WAAW,MAAM;QAC3D,cAAc,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,UAAU,KAAK;QACtF,KAAK,CAAC,CAAC,eAAe,WAAW,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,iBAAiB;QACtF,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE,mEAAmE;IACnE,4CAA4C;IAC5C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,WAAW,KAAK,OAAO,EAAE,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;IACpC,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,uCAAuC;IAC9C,WAAW,EAAE;;;;;;;;;;;;;;;;;uOAiBwN;IACrO,WAAW,EAAE,kBAAkB;IAC/B,YAAY,EAAE,mBAAmB;IACjC,WAAW,EAAE,QAAQ;IACrB,GAAG,EAAE,YAAY;CAClB,CAAC,CAAC"}

package/dist/server/tools.js

@@ -0,0 +1,43 @@
+/**
+ * Every MCP tool, in the order tools/list has always returned them. The
+ * definitions live in one file per tool family; this list is the only place
+ * the order is decided.
+ */
+import { healthTool, searchTool, lookupRegisterTool, lookupKernalTool, memoryMapTool, lookupOpcodeTool, palNtscDiffTool, } from "./tools-lookup.js";
+import { toolchainHintTool, recipeLookupTool, recipesForTool, techniqueLookupTool, techniquesForTool, checkCompatibilityTool, timingBudgetTool, planBudgetTool, } from "./tools-recipes.js";
+import { pitfallsForTool, lintSourceTool, failureDiagnoseTool } from "./tools-pitfalls.js";
+import { demoBriefingTool, gameBriefingTool } from "./tools-briefings.js";
+import { ingestDocTool, coverageTool, suggestLinksTool, reportGapTool } from "./tools-maintenance.js";
+import { runGameTool } from "./tools-runtime.js";
+import { memorizationTool } from "../tools/memorization-mcp.js";
+export const TOOLS = [
+    healthTool,
+    searchTool,
+    ingestDocTool,
+    lookupRegisterTool,
+    lookupKernalTool,
+    memoryMapTool,
+    lookupOpcodeTool,
+    palNtscDiffTool,
+    toolchainHintTool,
+    recipeLookupTool,
+    recipesForTool,
+    techniqueLookupTool,
+    techniquesForTool,
+    checkCompatibilityTool,
+    timingBudgetTool,
+    planBudgetTool,
+    pitfallsForTool,
+    lintSourceTool,
+    failureDiagnoseTool,
+    demoBriefingTool,
+    gameBriefingTool,
+    coverageTool,
+    suggestLinksTool,
+    reportGapTool,
+    // Runtime tools (Layer 1: eval substrate)
+    runGameTool,
+    // SID Phase A: memorization detection. Absent where the Python analyzer is not installed.
+    ...(memorizationTool ? [memorizationTool] : []),
+];
+//# sourceMappingURL=tools.js.map

package/dist/server/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/server/tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACtG,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,MAAM,CAAC,MAAM,KAAK,GAA+B;IAC/C,UAAU;IACV,UAAU;IACV,aAAa;IACb,kBAAkB;IAClB,gBAAgB;IAChB,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,iBAAiB;IACjB,gBAAgB;IAChB,cAAc;IACd,mBAAmB;IACnB,iBAAiB;IACjB,sBAAsB;IACtB,gBAAgB;IAChB,cAAc;IACd,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,YAAY;IACZ,gBAAgB;IAChB,aAAa;IACb,0CAA0C;IAC1C,WAAW;IACX,0FAA0F;IAC1F,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CAChD,CAAC"}

package/dist/server.js

@@ -0,0 +1,95 @@
+/**
+ * c64-kb MCP server: a thin wrapper over the tool functions in src/tools/.
+ *
+ * Structured tools return `structuredContent` matching a Zod
+ * `outputSchema`, alongside a `content[0].text` markdown blob. Closed-set
+ * string args use `z.enum()`. Tool descriptions follow the 6-component
+ * template: purpose, guidelines, limitations, param notes, expected length,
+ * example. `c64_health` lists the live surface; the list is not repeated
+ * here because it went stale.
+ *
+ * The tools themselves are defined in src/server/ (one file per family) and
+ * registered by one loop; src/server/tools.ts fixes their order.
+ */
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getVersions } from "./services/versions.js";
+import { closeAll } from "./context.js";
+import { registerTools } from "./server/define-tool.js";
+import { TOOLS } from "./server/tools.js";
+import { STATIC_RESOURCES, readStaticResource, readRegisterResource } from "./tools/resources.js";
+import { demoBriefPrompt, gameBriefPrompt, demoBriefArgs, gameBriefArgs } from "./tools/prompts.js";
+export async function startMcpServer() {
+    // The version said "0.1.0" through package 0.8.0.
+    const server = new McpServer({ name: "c64-kb", version: getVersions().package }, {
+        instructions: "Commodore 64 knowledge base. Call c64_health first to see what the stores hold; c64_demo_briefing and c64_game_briefing plan a whole program in one call.",
+    });
+    registerTools(server, TOOLS);
+    registerResources(server);
+    registerPrompts(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    exitWhenStdinCloses(server);
+}
+function registerResources(server) {
+    for (const r of STATIC_RESOURCES) {
+        server.registerResource(r.name, r.uri, { description: r.description, mimeType: "text/markdown" }, () => {
+            const res = readStaticResource(r.uri);
+            return { contents: res ? [res] : [] };
+        });
+    }
+    // Template resource for per-register structured lookup.
+    server.registerResource("register", new ResourceTemplate("c64://register/{name}", { list: undefined }), {
+        description: "Per-register structured data (name, address, chip, R/W, aliases). Useful for direct attach when the consuming agent already knows which register it cares about.",
+    }, async (uri, vars) => {
+        const raw = vars.name;
+        const name = typeof raw === "string" ? raw : Array.isArray(raw) ? (raw.at(0) ?? "") : "";
+        const res = await readRegisterResource(uri.toString(), name);
+        return { contents: res ? [res] : [] };
+    });
+}
+function registerPrompts(server) {
+    server.registerPrompt("c64_demo_brief", {
+        description: "Design a C64 demo from a natural-language brief. Templated body guides the agent through technique identification, register/KERNAL lookup, pitfall surfacing, build order, and toolchain split (Oscar64 vs KickAssembler). Prefer the c64_demo_briefing tool, which runs the lookups itself.",
+        argsSchema: demoBriefArgs,
+    }, demoBriefPrompt);
+    server.registerPrompt("c64_game_brief", {
+        description: "Design a C64 game from a natural-language brief. Templated body guides the agent through archetype matching, architecture sketch, technique selection, SID approach, KERNAL usage, and toolchain split. Prefer the c64_game_briefing tool, which runs the lookups itself.",
+        argsSchema: gameBriefArgs,
+    }, gameBriefPrompt);
+}
+/**
+ * A stdio client shuts the server down by closing stdin (MCP spec,
+ * transports/stdio); the SDK's transport does not listen for that, and the
+ * open FalkorDB socket kept the process alive. Close everything and exit.
+ */
+function exitWhenStdinCloses(server) {
+    let closing = false;
+    const shutdown = (code) => {
+        if (closing)
+            return;
+        closing = true;
+        const force = setTimeout(() => process.exit(code), 3000);
+        force.unref();
+        void server
+            .close()
+            .catch((e) => {
+            console.error("c64-kb: closing the MCP server failed:", e);
+        })
+            .then(() => closeAll())
+            .finally(() => process.exit(code));
+    };
+    process.stdin.on("end", () => {
+        shutdown(0);
+    });
+    process.stdin.on("close", () => {
+        shutdown(0);
+    });
+    process.on("SIGINT", () => {
+        shutdown(0);
+    });
+    process.on("SIGTERM", () => {
+        shutdown(0);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAClG,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEpG,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,kDAAkD;IAClD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,OAAO,EAAE,EAClD;QACE,YAAY,EACV,2JAA2J;KAC9J,CACF,CAAC;IAEF,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7B,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1B,eAAe,CAAC,MAAM,CAAC,CAAC;IAExB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,iBAAiB,CAAC,MAAiB;IAC1C,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACjC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,eAAe,EAAE,EAAE,GAAG,EAAE;YACrG,MAAM,GAAG,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACxC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,wDAAwD;IACxD,MAAM,CAAC,gBAAgB,CACrB,UAAU,EACV,IAAI,gBAAgB,CAAC,uBAAuB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAClE;QACE,WAAW,EACT,kKAAkK;KACrK,EACD,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACzF,MAAM,GAAG,GAAG,MAAM,oBAAoB,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,CAAC;QAC7D,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACxC,CAAC,CACF,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,MAAiB;IACxC,MAAM,CAAC,cAAc,CACnB,gBAAgB,EAChB;QACE,WAAW,EACT,8RAA8R;QAChS,UAAU,EAAE,aAAa;KAC1B,EACD,eAAe,CAChB,CAAC;IAEF,MAAM,CAAC,cAAc,CACnB,gBAAgB,EAChB;QACE,WAAW,EACT,2QAA2Q;QAC7Q,UAAU,EAAE,aAAa;KAC1B,EACD,eAAe,CAChB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,MAAiB;IAC5C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAE;QAChC,IAAI,OAAO;YAAE,OAAO;QACpB,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QACzD,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,KAAK,MAAM;aACR,KAAK,EAAE;aACP,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;YACpB,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;aACtB,OAAO,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;QAC3B,QAAQ,CAAC,CAAC,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QAC7B,QAAQ,CAAC,CAAC,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;QACxB,QAAQ,CAAC,CAAC,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACzB,QAAQ,CAAC,CAAC,CAAC,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/services/analytics/schema.js

@@ -0,0 +1,78 @@
+/**
+ * The analytics database's tables. CREATE ... IF NOT EXISTS, then ALTERs
+ * for columns added after the first release, so an old file upgrades in place.
+ */
+function addColumnIfMissing(db, table, column, type) {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (!cols.some((c) => c.name === column)) {
+        db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+    }
+}
+export function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS query_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool TEXT NOT NULL,
+      query TEXT NOT NULL,
+      result_count INTEGER NOT NULL,
+      timestamp TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS gaps (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      query TEXT NOT NULL,
+      tool TEXT NOT NULL,
+      hit_count INTEGER DEFAULT 1,
+      first_seen TEXT DEFAULT (datetime('now')),
+      last_seen TEXT DEFAULT (datetime('now')),
+      resolved INTEGER DEFAULT 0,
+      resolved_at TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_gaps_query ON gaps(query);
+    CREATE INDEX IF NOT EXISTS idx_gaps_resolved ON gaps(resolved);
+    CREATE INDEX IF NOT EXISTS idx_query_log_tool ON query_log(tool);
+
+    CREATE TABLE IF NOT EXISTS hydration_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool TEXT NOT NULL,
+      doc_path TEXT,
+      title TEXT,
+      timestamp TEXT DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS episodes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      started_at TEXT,
+      ended_at TEXT,
+      query_log_ids TEXT,
+      resolution TEXT DEFAULT 'open',
+      resolution_summary TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS learning_candidates (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      evidence TEXT,
+      confidence TEXT,
+      status TEXT DEFAULT 'proposed',
+      source_episodes TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      promoted_at TEXT,
+      related_apis TEXT,
+      promote_manifest TEXT
+    );
+  `);
+    // Upgrade existing query_log with new columns (safe if already present)
+    addColumnIfMissing(db, "query_log", "result_scores", "TEXT");
+    addColumnIfMissing(db, "query_log", "search_mode", "TEXT");
+    addColumnIfMissing(db, "query_log", "result_sources", "TEXT");
+    // Upgrade existing gaps with pending_verify column
+    addColumnIfMissing(db, "gaps", "pending_verify", "INTEGER DEFAULT 0");
+    // Upgrade existing gaps with user_reported + notes columns (P7a-1)
+    addColumnIfMissing(db, "gaps", "user_reported", "INTEGER DEFAULT 0");
+    addColumnIfMissing(db, "gaps", "notes", "TEXT");
+}
+//# sourceMappingURL=schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/services/analytics/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,SAAS,kBAAkB,CAAC,EAAqB,EAAE,KAAa,EAAE,MAAc,EAAE,IAAY;IAC5F,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAuB,qBAAqB,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IACnF,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,CAAC;QACzC,EAAE,CAAC,IAAI,CAAC,eAAe,KAAK,eAAe,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,EAAqB;IAC9C,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDP,CAAC,CAAC;IAEH,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;IAC7D,kBAAkB,CAAC,EAAE,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;IAC3D,kBAAkB,CAAC,EAAE,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAE9D,mDAAmD;IACnD,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,mBAAmB,CAAC,CAAC;IAEtE,mEAAmE;IACnE,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,mBAAmB,CAAC,CAAC;IACrE,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}