c64-kb 0.17.0

package/dist/services/falkor/base.js

@@ -0,0 +1,85 @@
+/**
+ * Connection, read and write plumbing for FalkorService. Every write goes
+ * through `write`; node upserts and edge merges through `upsertNode`,
+ * `setNode` and `mergeEdge`, so the Cypher shape of each lives in one place.
+ */
+import { FalkorDB } from "falkordb";
+import { config } from "../../config.js";
+import { toQueryParams } from "./params.js";
+function matchEnd(alias, end) {
+    if ("register" in end) {
+        return {
+            clause: `MATCH (${alias}:Register) WHERE ${alias}.name = $${alias} OR ${alias}.address = $${alias}Addr OR $${alias} IN ${alias}.aliases`,
+            params: { [alias]: end.register, [`${alias}Addr`]: `$${end.register}` },
+        };
+    }
+    if ("symptom" in end) {
+        return { clause: `MATCH (${alias}:CrashPattern {symptom: $${alias}})`, params: { [alias]: end.symptom } };
+    }
+    const verb = end.create ? "MERGE" : "MATCH";
+    return { clause: `${verb} (${alias}:${end.label} {name: $${alias}})`, params: { [alias]: end.name } };
+}
+export class FalkorBase {
+    db = null;
+    graphName = config.falkor.graphName;
+    async connect(host = config.falkor.host, port = config.falkor.port) {
+        this.db = await FalkorDB.connect({ socket: { host, port } });
+        // The client re-emits socket errors as 'error' events. With no listener
+        // Node throws them, so a FalkorDB restart would kill a long-lived MCP
+        // server; the client reconnects on its own once the socket returns.
+        this.db.on("error", (err) => {
+            console.error("[falkor] connection error:", err instanceof Error ? err.message : err);
+        });
+    }
+    async close() {
+        if (this.db) {
+            await this.db.close();
+            this.db = null;
+        }
+    }
+    graph() {
+        if (!this.db)
+            throw new Error("Not connected to FalkorDB");
+        return this.db.selectGraph(this.graphName);
+    }
+    /** Run a write query; returns the result rows (empty when it returns none). */
+    async write(cypher, params) {
+        const result = await this.graph().query(cypher, params ? { params } : undefined);
+        return result.data ?? [];
+    }
+    async roQuery(cypher, params, schema) {
+        const options = params ? { params: toQueryParams(params) } : undefined;
+        const result = await this.graph().roQuery(cypher, options);
+        const rows = result.data ?? [];
+        return { data: schema ? rows.map((r) => schema.parse(r)) : rows };
+    }
+    /**
+     * MERGE on the key, then `+=` the properties, stamping created_at or
+     * updated_at. `clear` names properties to set to NULL, so a value the page
+     * dropped does not outlive it.
+     */
+    async upsertNode(opts) {
+        const clear = opts.clear ?? [];
+        const clearClause = clear.length > 0 ? `SET ${clear.map((p) => `n.${p} = NULL`).join(", ")}` : "";
+        await this.write(`MERGE (n:${opts.label} {name: $name})
+       ON CREATE SET n += $props, n.created_at = timestamp()
+       ON MATCH SET n += $props, n.updated_at = timestamp()
+       ${clearClause}`, { name: opts.name, props: opts.props });
+    }
+    /** MERGE on the key and overwrite the given properties, with no timestamps. */
+    async setNode(label, key, props) {
+        const [prop, value] = "name" in key ? ["name", key.name] : ["symptom", key.symptom];
+        await this.write(`MERGE (n:${label} {${prop}: $key}) SET n += $props`, { key: value, props });
+    }
+    /** MERGE one edge between two ends. Returns whether it landed (both ends found). */
+    async mergeEdge(spec) {
+        const a = matchEnd("a", spec.from);
+        const b = matchEnd("b", spec.to);
+        const rows = await this.write(`${a.clause}
+       ${b.clause}
+       MERGE (a)-[:${spec.rel}]->(b)
+       RETURN 1`, { ...a.params, ...b.params });
+        return rows.length > 0;
+    }
+}
+//# sourceMappingURL=base.js.map

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

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

package/dist/services/falkor/links.js

@@ -0,0 +1,361 @@
+/**
+ * Edge writes. Most are one mergeEdge call; the MATCH-both links warn by
+ * name when an end is missing, because a reference that names no node is a
+ * defect in the doc, not a debug detail.
+ */
+import { FalkorNodes } from "./nodes.js";
+import { firstCount } from "./params.js";
+/** Labels linkBelongsTo accepts: the ones with a `name` key that can belong to a Chip. */
+const CHIP_MEMBER_LABELS = ["Register", "KernalRoutine", "Technique", "Tool"];
+function isChipMemberLabel(s) {
+    return CHIP_MEMBER_LABELS.includes(s);
+}
+function causeEnd(targetName, targetKind) {
+    return targetKind === "Register" ? { register: targetName } : { label: targetKind, name: targetName };
+}
+export class FalkorLinks extends FalkorNodes {
+    /** mergeEdge, plus the standard warning when the edge did not land. */
+    async mergeOrWarn(opts) {
+        const landed = await this.mergeEdge(opts);
+        if (!landed)
+            console.warn(`[falkor] ${opts.warn}, edge dropped`);
+        return landed;
+    }
+    /**
+     * IN_REGION: every Register and KernalRoutine whose address falls inside a
+     * MemoryRegion. Run once after all nodes exist. Without this the 220
+     * MemoryRegion nodes had no edges at all.
+     */
+    async linkAddressesToRegions() {
+        const link = async (label) => firstCount(await this.write(`MATCH (x:${label}), (m:MemoryRegion)
+           WHERE x.addr_n >= 0 AND m.start_n >= 0 AND x.addr_n >= m.start_n AND x.addr_n <= m.end_n
+           MERGE (x)-[:IN_REGION]->(m)
+           RETURN count(*) AS n`));
+        return { registers: await link("Register"), kernal: await link("KernalRoutine") };
+    }
+    /** OCCUPIES: a recipe loads code or data into [start, end]; link every MemoryRegion that overlaps. */
+    async linkRecipeOccupies(recipeName, start, end) {
+        const rows = await this.write(`MATCH (r:Recipe {name: $recipeName})
+       MATCH (m:MemoryRegion)
+       WHERE m.start_n >= 0 AND m.start_n <= $end AND m.end_n >= $start
+       MERGE (r)-[:OCCUPIES]->(m)
+       RETURN count(m) AS n`, { recipeName, start, end });
+        return firstCount(rows);
+    }
+    /** DEMANDS: a technique needs a machine-level resource while active (see CONVENTIONS-techniques.md). */
+    async linkTechniqueDemands(techniqueName, resource, description) {
+        await this.write(`MATCH (t:Technique {name: $techniqueName})
+       MERGE (res:Resource {name: $resource})
+       ON CREATE SET res.description = $description, res.created_at = timestamp()
+       MERGE (t)-[:DEMANDS]->(res)`, { techniqueName, resource, description });
+    }
+    /**
+     * The label is spliced into the Cypher text, so it is checked against a
+     * fixed list: this used to interpolate any string it was given.
+     */
+    async linkBelongsTo(entityType, entityName, chip) {
+        if (!isChipMemberLabel(entityType)) {
+            throw new Error(`linkBelongsTo: "${entityType}" is not one of ${CHIP_MEMBER_LABELS.join(", ")}`);
+        }
+        await this.mergeEdge({
+            from: { label: entityType, name: entityName },
+            rel: "BELONGS_TO",
+            to: { label: "Chip", name: chip },
+        });
+    }
+    async linkPairsWith(a, b) {
+        const linked = await this.mergeEdge({
+            from: { label: "KernalRoutine", name: a },
+            rel: "PAIRS_WITH",
+            to: { label: "KernalRoutine", name: b },
+        });
+        // Gated behind INGEST_VERBOSE so MCP-host stderr stays clean. Set
+        // INGEST_VERBOSE=1 during a clean re-ingest to surface per-pair details
+        // in kernal-routines-reference.md.
+        if (!linked && process.env.INGEST_VERBOSE) {
+            console.warn(`linkPairsWith: ${a} -> ${b} skipped (one or both KernalRoutines not in graph)`);
+        }
+        return { linked };
+    }
+    async linkProduces(toolName, formatName) {
+        await this.mergeEdge({
+            from: { label: "Tool", name: toolName },
+            rel: "PRODUCES",
+            to: { label: "FileFormat", name: formatName },
+        });
+    }
+    async linkConsumes(toolName, formatName) {
+        await this.mergeEdge({
+            from: { label: "Tool", name: toolName },
+            rel: "CONSUMES",
+            to: { label: "FileFormat", name: formatName },
+        });
+    }
+    async linkTargets(toolName, chipName) {
+        await this.mergeEdge({
+            from: { label: "Tool", name: toolName },
+            rel: "TARGETS",
+            to: { label: "Chip", name: chipName },
+        });
+    }
+    async linkRecipeImplements(recipeName, techniqueName) {
+        await this.mergeEdge({
+            from: { label: "Recipe", name: recipeName },
+            rel: "IMPLEMENTS",
+            to: { label: "Technique", name: techniqueName, create: true },
+        });
+    }
+    /**
+     * SCAFFOLDS: the recipe's frontmatter names this archetype as one it is a
+     * starting point for. Both ends MATCHed, never MERGEd, so an archetype
+     * name the graph does not have drops the edge with a warning instead of
+     * creating a stub. Returns whether the edge landed.
+     */
+    async linkRecipeScaffolds(recipeName, archetypeName) {
+        return this.mergeOrWarn({
+            from: { label: "Recipe", name: recipeName },
+            rel: "SCAFFOLDS",
+            to: { label: "Archetype", name: archetypeName },
+            warn: `linkRecipeScaffolds: ${recipeName} -> ${archetypeName} (Archetype) — recipe or archetype not found`,
+        });
+    }
+    async linkRecipeProducesFormat(recipeName, formatName) {
+        await this.mergeEdge({
+            from: { label: "Recipe", name: recipeName },
+            rel: "PRODUCES",
+            to: { label: "FileFormat", name: formatName },
+        });
+    }
+    async linkRecipeUsesKernal(recipeName, kernalName) {
+        await this.mergeEdge({
+            from: { label: "Recipe", name: recipeName },
+            rel: "USES",
+            to: { label: "KernalRoutine", name: kernalName },
+        });
+    }
+    async linkRecipeUsesRegister(recipeName, registerName) {
+        await this.mergeEdge({
+            from: { label: "Recipe", name: recipeName },
+            rel: "USES",
+            to: { register: registerName },
+        });
+    }
+    // The recipe-to-tool link is REQUIRES_TOOL, as the ontology defines it. Until
+    // data 713 this wrote USES, which left REQUIRES_TOOL populated by nothing.
+    async linkRecipeUsesTool(recipeName, toolName) {
+        await this.mergeEdge({
+            from: { label: "Recipe", name: recipeName },
+            rel: "REQUIRES_TOOL",
+            to: { label: "Tool", name: toolName, create: true },
+        });
+    }
+    async linkTechniqueUsesRegister(techniqueName, registerName) {
+        await this.mergeEdge({
+            from: { label: "Technique", name: techniqueName },
+            rel: "USES",
+            to: { register: registerName },
+        });
+    }
+    async linkTechniqueUsesKernal(techniqueName, kernalName) {
+        await this.mergeEdge({
+            from: { label: "Technique", name: techniqueName },
+            rel: "USES",
+            to: { label: "KernalRoutine", name: kernalName },
+        });
+    }
+    async linkTechniqueRequiresRegion(techniqueName, regionName) {
+        await this.mergeEdge({
+            from: { label: "Technique", name: techniqueName },
+            rel: "REQUIRES_REGION",
+            to: { label: "Region", name: regionName },
+        });
+    }
+    async linkTechniqueBelongsTo(techniqueName, chipName) {
+        await this.linkBelongsTo("Technique", techniqueName, chipName);
+    }
+    /**
+     * REQUIRES: a technique presupposes another one being set up before, or
+     * running underneath, it (see CONVENTIONS-techniques.md). Both ends must
+     * already exist — a MERGE on the target, as linkRecipeImplements does,
+     * would manufacture a stub Technique out of a typo. A reference that would
+     * close a cycle (the required technique already requires this one, directly
+     * or through others) is refused, as is a self-reference. The back-path
+     * check walks at most twelve REQUIRES edges, the same bound as
+     * techniquesFor's chain filter; a longer chain would not be checked. The
+     * longest authored chain is two. Returns whether the edge landed; every
+     * refusal is warned about by name.
+     */
+    async linkTechniqueRequires(techniqueName, requiresName) {
+        if (techniqueName === requiresName) {
+            console.warn(`[falkor] linkTechniqueRequires: ${techniqueName} -> itself — refused`);
+            return false;
+        }
+        const back = await this.roQuery(`MATCH (p:Technique {name: $requiresName})-[:REQUIRES*1..12]->(t:Technique {name: $techniqueName})
+       RETURN 1 LIMIT 1`, { techniqueName, requiresName });
+        if (back.data.length > 0) {
+            console.warn(`[falkor] linkTechniqueRequires: ${techniqueName} -> ${requiresName} would close a cycle (${requiresName} already requires ${techniqueName}) — refused`);
+            return false;
+        }
+        return this.mergeOrWarn({
+            from: { label: "Technique", name: techniqueName },
+            rel: "REQUIRES",
+            to: { label: "Technique", name: requiresName },
+            warn: `linkTechniqueRequires: ${techniqueName} -> ${requiresName} — one or both techniques not found`,
+        });
+    }
+    /**
+     * CLAIMS (schema 25): a technique holds a HardwareUnit in a mode (owns,
+     * shares, reads, init); zero_page carries its byte ranges. Both ends must
+     * exist: the unit is a seed and the technique came from pass 1, so a MERGE
+     * could only manufacture a stub out of a typo. Returns whether it landed.
+     */
+    async linkClaims(c) {
+        const rows = await this.write(`MATCH (t:${c.ownerKind} {name: $owner})
+       MATCH (h:HardwareUnit {name: $unit})
+       MERGE (t)-[e:CLAIMS]->(h)
+       SET e.mode = $mode, e.ranges = $ranges, e.relocatable = $relocatable, e.basis = $basis
+       RETURN 1`, {
+            owner: c.owner,
+            unit: c.unit,
+            mode: c.mode,
+            ranges: c.ranges ?? null,
+            relocatable: c.relocatable === true,
+            basis: c.basis,
+        });
+        if (rows.length > 0)
+            return true;
+        console.warn(`[falkor] linkClaims: ${c.owner} -> ${c.unit} — ${c.ownerKind} or HardwareUnit not found, edge dropped`);
+        return false;
+    }
+    /**
+     * CLOBBERS_ZP (schema 26): the zero-page bytes a KERNAL routine may write
+     * (bound may, the ROM walk) or did write in a VICE trace (bound must, one
+     * edge per traced call, keyed by its basis). Both ends must exist: the
+     * routine came from pass 1, zero_page is a seed.
+     */
+    async linkKernalClobbersZp(c) {
+        const rows = await this.write(`MATCH (k:KernalRoutine {name: $routine})
+       MATCH (z:HardwareUnit {name: 'zero_page'})
+       MERGE (k)-[e:CLOBBERS_ZP {bound: $bound, basis: $basis}]->(z)
+       SET e.ranges = $ranges
+       RETURN 1`, c);
+        if (rows.length > 0)
+            return true;
+        console.warn(`[falkor] linkKernalClobbersZp: ${c.routine} — KernalRoutine or zero_page unit not found, edge dropped`);
+        return false;
+    }
+    async linkTriggeredBy(pitfallName, targetName, targetKind) {
+        return this.mergeOrWarn({
+            from: { label: "Pitfall", name: pitfallName },
+            rel: "TRIGGERED_BY",
+            to: causeEnd(targetName, targetKind),
+            warn: `linkTriggeredBy: ${pitfallName} -> ${targetName} (${targetKind}) — target not found`,
+        });
+    }
+    /**
+     * MITIGATED_BY: applying this technique is the pitfall's Fix (see
+     * CONVENTIONS-pitfalls.md). Technique targets only; both ends are MATCHed,
+     * never MERGEd, so a misspelt name drops the edge with a warning instead
+     * of creating a stub node. Returns whether the edge landed.
+     */
+    async linkMitigatedBy(pitfallName, techniqueName) {
+        return this.mergeOrWarn({
+            from: { label: "Pitfall", name: pitfallName },
+            rel: "MITIGATED_BY",
+            to: { label: "Technique", name: techniqueName },
+            warn: `linkMitigatedBy: ${pitfallName} -> ${techniqueName} (Technique) — pitfall or technique not found`,
+        });
+    }
+    /**
+     * FEATURES: the archetype's technique fingerprint names this technique.
+     * Both ends MATCHed, never MERGEd, so a name the graph does not have drops
+     * the edge with a warning instead of creating a stub. Returns whether it landed.
+     */
+    async linkArchetypeFeatures(archetypeName, techniqueName) {
+        return this.mergeOrWarn({
+            from: { label: "Archetype", name: archetypeName },
+            rel: "FEATURES",
+            to: { label: "Technique", name: techniqueName },
+            warn: `linkArchetypeFeatures: ${archetypeName} -> ${techniqueName} (Technique) — archetype or technique not found`,
+        });
+    }
+    /**
+     * RISKS: the archetype's common-pitfalls line names this pitfall. Same
+     * MATCH-both discipline as FEATURES. Returns whether the edge landed.
+     */
+    async linkArchetypeRisks(archetypeName, pitfallName) {
+        return this.mergeOrWarn({
+            from: { label: "Archetype", name: archetypeName },
+            rel: "RISKS",
+            to: { label: "Pitfall", name: pitfallName },
+            warn: `linkArchetypeRisks: ${archetypeName} -> ${pitfallName} (Pitfall) — archetype or pitfall not found`,
+        });
+    }
+    /**
+     * COMPOSES (schema 28): the design runs this technique in this phase.
+     * Keyed by phase, so one technique may be composed in two phases. Both
+     * ends MATCHed, never MERGEd.
+     */
+    async linkComposes(design, technique, phase) {
+        const rows = await this.write(`MATCH (g:GameDesign {name: $design})
+       MATCH (t:Technique {name: $technique})
+       MERGE (g)-[:COMPOSES {phase: $phase}]->(t)
+       RETURN 1`, { design, technique, phase });
+        if (rows.length > 0)
+            return true;
+        console.warn(`[falkor] linkComposes: ${design} -> ${technique} (Technique) — game design or technique not found, edge dropped`);
+        return false;
+    }
+    /** INSTANCE_OF (schema 28): the design is a game of this archetype. MATCH both. */
+    async linkInstanceOf(design, archetype) {
+        return this.mergeOrWarn({
+            from: { label: "GameDesign", name: design },
+            rel: "INSTANCE_OF",
+            to: { label: "Archetype", name: archetype },
+            warn: `linkInstanceOf: ${design} -> ${archetype} (Archetype) — game design or archetype not found`,
+        });
+    }
+    /** REALISED_BY (schema 28): this recipe builds the design. MATCH both. */
+    async linkRealisedBy(design, recipe) {
+        return this.mergeOrWarn({
+            from: { label: "GameDesign", name: design },
+            rel: "REALISED_BY",
+            to: { label: "Recipe", name: recipe },
+            warn: `linkRealisedBy: ${design} -> ${recipe} (Recipe) — game design or recipe not found`,
+        });
+    }
+    /**
+     * VERIFIED_ON (schema 29): verify:recipes runs this recipe page on this
+     * variant and compares the committed screenshot pixel for pixel. Built
+     * from docs/recipes/runs.json after every ingest, never from a page, so
+     * the old edges are removed first: replaceVerifiedOn owns the edge type.
+     */
+    async replaceVerifiedOn(edges) {
+        await this.write(`MATCH ()-[e:VERIFIED_ON]->() DELETE e`);
+        let landed = 0;
+        const dropped = [];
+        for (const e of edges) {
+            const rows = await this.write(`MATCH (r:Recipe {source_doc: $source_doc})
+         MATCH (v:MachineVariant {name: $variant})
+         MERGE (r)-[x:VERIFIED_ON {model: $model}]->(v)
+         SET x.cycles = $cycles, x.shot = $shot, x.flags = $flags, x.pinned = $pinned
+         RETURN 1`, e);
+            if (rows.length > 0)
+                landed++;
+            else
+                dropped.push(`${e.source_doc} -> ${e.variant}`);
+        }
+        if (dropped.length > 0)
+            console.warn(`[falkor] replaceVerifiedOn: ${dropped.length} edge(s) dropped: ${dropped.join(", ")}`);
+        return { landed, dropped };
+    }
+    async linkCausedBy(symptom, targetName, targetKind) {
+        return this.mergeOrWarn({
+            from: { label: "CrashPattern", symptom },
+            rel: "CAUSED_BY",
+            to: causeEnd(targetName, targetKind),
+            warn: `linkCausedBy: ${symptom} -> ${targetName} (${targetKind}) — target not found`,
+        });
+    }
+}
+//# sourceMappingURL=links.js.map

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

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

package/dist/services/falkor/nodes.js

@@ -0,0 +1,183 @@
+/**
+ * Node writes: one method per node type. Each is an upsert keyed on the
+ * label's primary key (see schema.ts).
+ */
+import { FalkorBase } from "./base.js";
+import { hexAddr } from "./params.js";
+const COST_KEYS = [
+    "cycles_per_line",
+    "cycles_per_frame",
+    "cycles_per_frame_typical",
+    "lines_active",
+    "bytes_code",
+    "bytes_data",
+    "zp_bytes",
+    "irq_slots",
+    "sprites_per_line",
+];
+/** Set `key` to `value` when it is present, or mark it to clear. */
+function setOrClear(props, clear, key, value) {
+    const empty = value === undefined || value === "" || (Array.isArray(value) && value.length === 0);
+    if (empty)
+        clear.push(key);
+    else
+        props[key] = value;
+}
+/** The Cost line's properties (schema 22, provenance schema 27); all of them clear when the line is gone. */
+function costProps(t, props, clear) {
+    for (const k of COST_KEYS) {
+        const v = t.cost?.[k];
+        setOrClear(props, clear, `cost_${k}`, typeof v === "number" && Number.isInteger(v) ? v : undefined);
+    }
+    const costed = Boolean(t.cost && t.cost_basis);
+    setOrClear(props, clear, "cost_basis", costed ? t.cost_basis : undefined);
+    setOrClear(props, clear, "cost_recipe", costed ? t.cost_recipe : undefined);
+    setOrClear(props, clear, "cost_conditions", costed ? t.cost_conditions : undefined);
+    setOrClear(props, clear, "cost_includes", costed ? t.cost_includes : undefined);
+}
+/** The technique's stored properties, and the ones to clear because the page no longer sets them. */
+function techniqueProps(t) {
+    const props = {
+        title: t.title,
+        category: t.category,
+        complexity: t.complexity ?? "",
+    };
+    const clear = [];
+    costProps(t, props, clear);
+    setOrClear(props, clear, "raster_band", t.raster_band);
+    if (t.claims_stated && t.claims_basis) {
+        props.claims_stated = t.claims_stated;
+        props.claims_basis = t.claims_basis;
+    }
+    else
+        clear.push("claims_stated", "claims_basis");
+    return { props, clear };
+}
+export class FalkorNodes extends FalkorBase {
+    async addRegister(...args) {
+        const [name, address, chip, rw, aliases = []] = args.length === 1 ? [args[0].name, args[0].address, args[0].chip, args[0].rw, args[0].aliases] : args;
+        await this.upsertNode({
+            label: "Register",
+            name,
+            props: { address, chip, rw, aliases, addr_n: hexAddr(address) },
+        });
+    }
+    async addKernalRoutine(name, address, description) {
+        await this.upsertNode({
+            label: "KernalRoutine",
+            name,
+            props: { address, description, addr_n: hexAddr(address) },
+        });
+        // The page owns the routine's CLOBBERS_ZP edges (schema 26): drop the
+        // old ones so a line the page no longer carries leaves no edge behind.
+        await this.write(`MATCH (k:KernalRoutine {name: $name})-[e:CLOBBERS_ZP]->(:HardwareUnit) DELETE e`, {
+            name,
+        });
+    }
+    async addMemoryRegion(...args) {
+        const m = args.length === 1
+            ? args[0]
+            : { name: args[0], start: args[1], end: args[2], defaultUse: args[3], bankSwitchable: args[4] };
+        await this.upsertNode({
+            label: "MemoryRegion",
+            name: m.name,
+            props: {
+                start: m.start,
+                end: m.end,
+                default_use: m.defaultUse,
+                bank_switchable: m.bankSwitchable,
+                start_n: hexAddr(m.start),
+                end_n: hexAddr(m.end),
+            },
+        });
+    }
+    async addTool(t) {
+        const props = {
+            kind: t.kind,
+            maintainer: t.maintainer ?? "",
+            license: t.license ?? "",
+            home_url: t.home_url,
+        };
+        if (t.version_verified)
+            props.version_verified = t.version_verified;
+        await this.upsertNode({
+            label: "Tool",
+            name: t.name,
+            props,
+            clear: t.version_verified ? [] : ["version_verified"],
+        });
+    }
+    async addFileFormat(name, description) {
+        // Description is SET only on first creation. The ingest walk priority
+        // puts docs/formats/c64-file-formats.md first, so the catalog's
+        // authoritative description wins over the shorter blurbs in per-toolchain
+        // docs that subsequently reference the same FileFormat.
+        await this.write(`MERGE (f:FileFormat {name: $name})
+       ON CREATE SET f.description = $description, f.created_at = timestamp()
+       ON MATCH SET f.updated_at = timestamp()`, { name, description });
+    }
+    async addRecipe(r) {
+        // Named field by field: callers pass whole extracted entities, whose other fields must not land.
+        const props = {
+            toolchain: r.toolchain,
+            output_format: r.output_format,
+            region: r.region,
+            source_doc: r.source_doc,
+        };
+        await this.upsertNode({ label: "Recipe", name: r.name, props });
+    }
+    async addTechnique(t) {
+        const { props, clear } = techniqueProps(t);
+        await this.upsertNode({ label: "Technique", name: t.name, props, clear });
+        // The page owns its CLAIMS edges outright: drop the old ones so a claim
+        // the page stopped making does not outlive it (pass 2 re-adds the rest).
+        await this.write(`MATCH (t:Technique {name: $name})-[c:CLAIMS]->(:HardwareUnit) DELETE c`, {
+            name: t.name,
+        });
+    }
+    async addPitfall(p) {
+        const props = { title: p.title, severity: p.severity, region: p.region, category: p.category };
+        await this.setNode("Pitfall", { name: p.name }, props);
+    }
+    /**
+     * Archetype: a game or demo shape from docs/game-design/c64-game-archetypes.md
+     * (docs/CONVENTIONS-archetypes.md). Keyed by snake_case name.
+     * brief_words is always written, empty when the page has no line, so a
+     * page that drops its line stops routing briefs.
+     */
+    async addArchetype(a) {
+        const props = {
+            title: a.title,
+            kind: a.kind,
+            source_doc: a.source_doc,
+            brief_words: [...(a.brief_words ?? [])],
+            // null clears a starter line a page stopped carrying.
+            starter: a.starter ?? null,
+        };
+        await this.setNode("Archetype", { name: a.name }, props);
+    }
+    /**
+     * GameDesign (schema 28): a whole game from docs/game-design/designs
+     * (docs/CONVENTIONS-game-designs.md). `measured` is the page's Measured
+     * frame lines as JSON; a page that drops its region or its measurements
+     * clears them.
+     */
+    async addGameDesign(g) {
+        const props = {
+            title: g.title,
+            source_doc: g.source_doc,
+            ...(g.region ? { region: g.region } : {}),
+            ...(g.measured.length > 0 ? { measured: JSON.stringify(g.measured) } : {}),
+        };
+        const clear = [...(g.region ? [] : ["region"]), ...(g.measured.length > 0 ? [] : ["measured"])];
+        await this.upsertNode({ label: "GameDesign", name: g.name, props, clear });
+    }
+    async addCrashPattern(c) {
+        await this.setNode("CrashPattern", { symptom: c.symptom }, {
+            description: c.description,
+            likely_causes: JSON.stringify(c.likely_causes),
+            diagnosis_steps: c.diagnosis_steps,
+        });
+    }
+}
+//# sourceMappingURL=nodes.js.map