ts-knowledge-graph 0.1.1 → 0.1.4

package/dist/schema/edge.d.ts

@@ -1,22 +1,57 @@
 import { z } from 'zod';
-export declare const EDGE_KINDS: readonly ["CONTAINS", "IMPORTS", "EXPORTS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "CALLS", "INSTANTIATES", "OVERRIDES", "READS", "WRITES"];
-export declare const EdgeKindSchema: z.ZodEnum<["CONTAINS", "IMPORTS", "EXPORTS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "CALLS", "INSTANTIATES", "OVERRIDES", "READS", "WRITES"]>;
+/**
+ * The closed edge vocabulary, grouped by layer (mirrors the README graph-model
+ * table).
+ *
+ * Decision (#31 Part 0): keep a closed `z.enum` rather than an extensible kind
+ * registry — simple and explicit. Kùzu stores `kind` as a `STRING`, so a new kind
+ * needs no schema migration; its only real costs are this enum, the extractor that
+ * emits it, and — for edges — whether it joins {@link REFERENCE_EDGE_KINDS}.
+ */
+export declare const EDGE_KINDS: readonly ["CONTAINS", "IMPORTS", "EXPORTS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "CALLS", "INSTANTIATES", "OVERRIDES", "READS", "WRITES", "READS_CONFIG", "CALLS_EXTERNAL", "HANDLES"];
+export declare const EdgeKindSchema: z.ZodEnum<["CONTAINS", "IMPORTS", "EXPORTS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "CALLS", "INSTANTIATES", "OVERRIDES", "READS", "WRITES", "READS_CONFIG", "CALLS_EXTERNAL", "HANDLES"]>;
 export type EdgeKind = z.infer<typeof EdgeKindSchema>;
+/**
+ * One-line, onboarding-oriented descriptions for every {@link EdgeKind}, keyed by
+ * kind. This is the single source of truth surfaced as hover tooltips in the web
+ * visualisation; the `Record<EdgeKind, string>` type makes adding an edge kind
+ * without describing it a compile error.
+ */
+export declare const EDGE_KIND_DESCRIPTIONS: Record<EdgeKind, string>;
+/**
+ * The edge kinds that count as a *reference* to their target — the single source
+ * of truth for {@link GraphQuery.references} and the {@link GraphQuery.deadExports}
+ * liveness check (the query layer derives its Cypher list from this array).
+ *
+ * An edge kind is a reference when its presence means the target symbol is *used*:
+ * a call, a heritage link, a type mention, an instantiation, a value read, a method
+ * override (an override uses the base member it replaces), or an endpoint→handler
+ * link (`HANDLES` — a route uses the function that handles it). Deliberately
+ * excluded:
+ * - `CONTAINS` / `IMPORTS` — containment and module wiring, not use;
+ * - `EXPORTS` — marks a symbol as exported; counting it would give every export an
+ *   inbound edge from its module and defeat dead-export detection;
+ * - `WRITES` — mutating a binding is not using its value;
+ * - `READS_CONFIG` / `CALLS_EXTERNAL` — their targets are synthesized system-level
+ *   nodes (a `ConfigFlag`, an `ExternalAPI`), not code symbols subject to
+ *   dead-export analysis.
+ */
+export declare const REFERENCE_EDGE_KINDS: readonly ["CALLS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "INSTANTIATES", "READS", "OVERRIDES", "HANDLES"];
 export declare const GraphEdgeSchema: z.ZodObject<{
     id: z.ZodString;
-    kind: z.ZodEnum<["CONTAINS", "IMPORTS", "EXPORTS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "CALLS", "INSTANTIATES", "OVERRIDES", "READS", "WRITES"]>;
+    kind: z.ZodEnum<["CONTAINS", "IMPORTS", "EXPORTS", "EXTENDS", "IMPLEMENTS", "USES_TYPE", "RETURNS", "PARAM_TYPE", "CALLS", "INSTANTIATES", "OVERRIDES", "READS", "WRITES", "READS_CONFIG", "CALLS_EXTERNAL", "HANDLES"]>;
     from: z.ZodString;
     to: z.ZodString;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    kind: "CONTAINS" | "IMPORTS" | "EXPORTS" | "EXTENDS" | "IMPLEMENTS" | "USES_TYPE" | "RETURNS" | "PARAM_TYPE" | "CALLS" | "INSTANTIATES" | "OVERRIDES" | "READS" | "WRITES";
+    kind: "CONTAINS" | "IMPORTS" | "EXPORTS" | "EXTENDS" | "IMPLEMENTS" | "USES_TYPE" | "RETURNS" | "PARAM_TYPE" | "CALLS" | "INSTANTIATES" | "OVERRIDES" | "READS" | "WRITES" | "READS_CONFIG" | "CALLS_EXTERNAL" | "HANDLES";
     from: string;
     to: string;
     metadata?: Record<string, unknown> | undefined;
 }, {
     id: string;
-    kind: "CONTAINS" | "IMPORTS" | "EXPORTS" | "EXTENDS" | "IMPLEMENTS" | "USES_TYPE" | "RETURNS" | "PARAM_TYPE" | "CALLS" | "INSTANTIATES" | "OVERRIDES" | "READS" | "WRITES";
+    kind: "CONTAINS" | "IMPORTS" | "EXPORTS" | "EXTENDS" | "IMPLEMENTS" | "USES_TYPE" | "RETURNS" | "PARAM_TYPE" | "CALLS" | "INSTANTIATES" | "OVERRIDES" | "READS" | "WRITES" | "READS_CONFIG" | "CALLS_EXTERNAL" | "HANDLES";
     from: string;
     to: string;
     metadata?: Record<string, unknown> | undefined;

package/dist/schema/edge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/schema/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,qKAcb,CAAC;AAEX,eAAO,MAAM,cAAc,uKAAqB,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;EAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/schema/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,kNAqBb,CAAC;AAEX,eAAO,MAAM,cAAc,oNAAqB,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAiB3D,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,oIAWO,CAAC;AAEzC,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;EAM1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/schema/edge.js

@@ -1,20 +1,90 @@
 import { z } from 'zod';
+/**
+ * The closed edge vocabulary, grouped by layer (mirrors the README graph-model
+ * table).
+ *
+ * Decision (#31 Part 0): keep a closed `z.enum` rather than an extensible kind
+ * registry — simple and explicit. Kùzu stores `kind` as a `STRING`, so a new kind
+ * needs no schema migration; its only real costs are this enum, the extractor that
+ * emits it, and — for edges — whether it joins {@link REFERENCE_EDGE_KINDS}.
+ */
 export const EDGE_KINDS = [
+    // Structural — cheap, always emitted (no symbol resolution).
     'CONTAINS',
     'IMPORTS',
     'EXPORTS',
+    // Type — require symbol resolution, emitted with `--semantic`.
     'EXTENDS',
     'IMPLEMENTS',
     'USES_TYPE',
     'RETURNS',
     'PARAM_TYPE',
+    // Behavioral — require symbol resolution, emitted with `--semantic`.
     'CALLS',
     'INSTANTIATES',
     'OVERRIDES',
     'READS',
     'WRITES',
+    // System-level — detection-gated entities (#31 Part 2+).
+    'READS_CONFIG',
+    'CALLS_EXTERNAL',
+    'HANDLES',
 ];
 export const EdgeKindSchema = z.enum(EDGE_KINDS);
+/**
+ * One-line, onboarding-oriented descriptions for every {@link EdgeKind}, keyed by
+ * kind. This is the single source of truth surfaced as hover tooltips in the web
+ * visualisation; the `Record<EdgeKind, string>` type makes adding an edge kind
+ * without describing it a compile error.
+ */
+export const EDGE_KIND_DESCRIPTIONS = {
+    CONTAINS: 'Structural nesting: the source declares or encloses the target (a module contains a class, which contains a method).',
+    IMPORTS: 'The source module imports the target.',
+    EXPORTS: 'The source module exports the target symbol.',
+    EXTENDS: 'The source class or interface extends the target (inheritance).',
+    IMPLEMENTS: 'The source class implements the target interface.',
+    USES_TYPE: 'The source references the target in a type position.',
+    RETURNS: 'The target type appears in the source function or method return type.',
+    PARAM_TYPE: 'The target type appears in one of the source parameter types.',
+    CALLS: 'The source function or method calls the target.',
+    INSTANTIATES: 'The source constructs the target class with new.',
+    OVERRIDES: 'The source method overrides the base-class member it replaces.',
+    READS: 'The source reads the value of the target variable or property.',
+    WRITES: 'The source assigns to the target variable or property.',
+    READS_CONFIG: 'The source reads the target configuration flag (an environment variable).',
+    CALLS_EXTERNAL: 'The source makes an outbound HTTP call to the target external API.',
+    HANDLES: 'Links an HTTP endpoint to the function that handles it (route to handler).',
+};
+/**
+ * The edge kinds that count as a *reference* to their target — the single source
+ * of truth for {@link GraphQuery.references} and the {@link GraphQuery.deadExports}
+ * liveness check (the query layer derives its Cypher list from this array).
+ *
+ * An edge kind is a reference when its presence means the target symbol is *used*:
+ * a call, a heritage link, a type mention, an instantiation, a value read, a method
+ * override (an override uses the base member it replaces), or an endpoint→handler
+ * link (`HANDLES` — a route uses the function that handles it). Deliberately
+ * excluded:
+ * - `CONTAINS` / `IMPORTS` — containment and module wiring, not use;
+ * - `EXPORTS` — marks a symbol as exported; counting it would give every export an
+ *   inbound edge from its module and defeat dead-export detection;
+ * - `WRITES` — mutating a binding is not using its value;
+ * - `READS_CONFIG` / `CALLS_EXTERNAL` — their targets are synthesized system-level
+ *   nodes (a `ConfigFlag`, an `ExternalAPI`), not code symbols subject to
+ *   dead-export analysis.
+ */
+export const REFERENCE_EDGE_KINDS = [
+    'CALLS',
+    'EXTENDS',
+    'IMPLEMENTS',
+    'USES_TYPE',
+    'RETURNS',
+    'PARAM_TYPE',
+    'INSTANTIATES',
+    'READS',
+    'OVERRIDES',
+    'HANDLES',
+];
 export const GraphEdgeSchema = z.object({
     id: z.string(),
     kind: EdgeKindSchema,

package/dist/schema/edge.js.map

@@ -1 +1 @@
-{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../src/schema/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG;IACzB,UAAU;IACV,SAAS;IACT,SAAS;IACT,SAAS;IACT,YAAY;IACZ,WAAW;IACX,SAAS;IACT,YAAY;IACZ,OAAO;IACP,cAAc;IACd,WAAW;IACX,OAAO;IACP,QAAQ;CACC,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAGjD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../src/schema/edge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACzB,6DAA6D;IAC7D,UAAU;IACV,SAAS;IACT,SAAS;IACT,+DAA+D;IAC/D,SAAS;IACT,YAAY;IACZ,WAAW;IACX,SAAS;IACT,YAAY;IACZ,qEAAqE;IACrE,OAAO;IACP,cAAc;IACd,WAAW;IACX,OAAO;IACP,QAAQ;IACR,yDAAyD;IACzD,cAAc;IACd,gBAAgB;IAChB,SAAS;CACA,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAGjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA6B;IAC/D,QAAQ,EAAE,sHAAsH;IAChI,OAAO,EAAE,uCAAuC;IAChD,OAAO,EAAE,8CAA8C;IACvD,OAAO,EAAE,iEAAiE;IAC1E,UAAU,EAAE,mDAAmD;IAC/D,SAAS,EAAE,sDAAsD;IACjE,OAAO,EAAE,uEAAuE;IAChF,UAAU,EAAE,+DAA+D;IAC3E,KAAK,EAAE,iDAAiD;IACxD,YAAY,EAAE,kDAAkD;IAChE,SAAS,EAAE,gEAAgE;IAC3E,KAAK,EAAE,gEAAgE;IACvE,MAAM,EAAE,wDAAwD;IAChE,YAAY,EAAE,2EAA2E;IACzF,cAAc,EAAE,oEAAoE;IACpF,OAAO,EAAE,4EAA4E;CACrF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IACnC,OAAO;IACP,SAAS;IACT,YAAY;IACZ,WAAW;IACX,SAAS;IACT,YAAY;IACZ,cAAc;IACd,OAAO;IACP,WAAW;IACX,SAAS;CAC8B,CAAC;AAEzC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}

package/dist/schema/node.d.ts

@@ -1,7 +1,22 @@
 import { z } from 'zod';
-export declare const NODE_KINDS: readonly ["Module", "Class", "Interface", "TypeAlias", "Enum", "Function", "Method", "Property", "Parameter", "Variable", "ExternalModule"];
-export declare const NodeKindSchema: z.ZodEnum<["Module", "Class", "Interface", "TypeAlias", "Enum", "Function", "Method", "Property", "Parameter", "Variable", "ExternalModule"]>;
+/**
+ * The closed node vocabulary. See {@link EDGE_KINDS} in `edge.ts` for the
+ * closed-enum-vs-registry decision (#31 Part 0); the same reasoning applies here.
+ *
+ * The system-level group grows one detection-gated extractor at a time (#31).
+ * `ConfigFlag` (environment variables) is the first; `Endpoint`, `DatabaseTable`,
+ * `QueueTopic`, and `ExternalAPI` arrive in later slices.
+ */
+export declare const NODE_KINDS: readonly ["Module", "Class", "Interface", "TypeAlias", "Enum", "Function", "Method", "Property", "Parameter", "Variable", "ExternalModule", "ConfigFlag", "ExternalAPI", "Endpoint"];
+export declare const NodeKindSchema: z.ZodEnum<["Module", "Class", "Interface", "TypeAlias", "Enum", "Function", "Method", "Property", "Parameter", "Variable", "ExternalModule", "ConfigFlag", "ExternalAPI", "Endpoint"]>;
 export type NodeKind = z.infer<typeof NodeKindSchema>;
+/**
+ * One-line, onboarding-oriented descriptions for every {@link NodeKind}, keyed by
+ * kind. This is the single source of truth surfaced as hover tooltips in the web
+ * visualisation; the `Record<NodeKind, string>` type makes adding a node kind
+ * without describing it a compile error.
+ */
+export declare const NODE_KIND_DESCRIPTIONS: Record<NodeKind, string>;
 export declare const RangeSchema: z.ZodObject<{
     startLine: z.ZodNumber;
     startColumn: z.ZodNumber;
@@ -21,7 +36,7 @@ export declare const RangeSchema: z.ZodObject<{
 export type Range = z.infer<typeof RangeSchema>;
 export declare const GraphNodeSchema: z.ZodObject<{
     id: z.ZodString;
-    kind: z.ZodEnum<["Module", "Class", "Interface", "TypeAlias", "Enum", "Function", "Method", "Property", "Parameter", "Variable", "ExternalModule"]>;
+    kind: z.ZodEnum<["Module", "Class", "Interface", "TypeAlias", "Enum", "Function", "Method", "Property", "Parameter", "Variable", "ExternalModule", "ConfigFlag", "ExternalAPI", "Endpoint"]>;
     name: z.ZodString;
     filePath: z.ZodString;
     range: z.ZodOptional<z.ZodObject<{
@@ -44,7 +59,7 @@ export declare const GraphNodeSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    kind: "Module" | "Class" | "Interface" | "TypeAlias" | "Enum" | "Function" | "Method" | "Property" | "Parameter" | "Variable" | "ExternalModule";
+    kind: "Module" | "Class" | "Interface" | "TypeAlias" | "Enum" | "Function" | "Method" | "Property" | "Parameter" | "Variable" | "ExternalModule" | "ConfigFlag" | "ExternalAPI" | "Endpoint";
     name: string;
     filePath: string;
     metadata?: Record<string, unknown> | undefined;
@@ -57,7 +72,7 @@ export declare const GraphNodeSchema: z.ZodObject<{
     exported?: boolean | undefined;
 }, {
     id: string;
-    kind: "Module" | "Class" | "Interface" | "TypeAlias" | "Enum" | "Function" | "Method" | "Property" | "Parameter" | "Variable" | "ExternalModule";
+    kind: "Module" | "Class" | "Interface" | "TypeAlias" | "Enum" | "Function" | "Method" | "Property" | "Parameter" | "Variable" | "ExternalModule" | "ConfigFlag" | "ExternalAPI" | "Endpoint";
     name: string;
     filePath: string;
     metadata?: Record<string, unknown> | undefined;

package/dist/schema/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/schema/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,6IAYb,CAAC;AAEX,eAAO,MAAM,cAAc,+IAAqB,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;EAKtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQ1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/schema/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,sLAkBb,CAAC;AAEX,eAAO,MAAM,cAAc,wLAAqB,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAe3D,CAAC;AAEF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;EAKtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQ1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/schema/node.js

@@ -1,5 +1,14 @@
 import { z } from 'zod';
+/**
+ * The closed node vocabulary. See {@link EDGE_KINDS} in `edge.ts` for the
+ * closed-enum-vs-registry decision (#31 Part 0); the same reasoning applies here.
+ *
+ * The system-level group grows one detection-gated extractor at a time (#31).
+ * `ConfigFlag` (environment variables) is the first; `Endpoint`, `DatabaseTable`,
+ * `QueueTopic`, and `ExternalAPI` arrive in later slices.
+ */
 export const NODE_KINDS = [
+    // Code structure.
     'Module',
     'Class',
     'Interface',
@@ -10,9 +19,36 @@ export const NODE_KINDS = [
     'Property',
     'Parameter',
     'Variable',
+    // External dependencies, as one opaque node per import specifier.
     'ExternalModule',
+    // System-level entities — detection-gated (#31 Part 2+).
+    'ConfigFlag',
+    'ExternalAPI',
+    'Endpoint',
 ];
 export const NodeKindSchema = z.enum(NODE_KINDS);
+/**
+ * One-line, onboarding-oriented descriptions for every {@link NodeKind}, keyed by
+ * kind. This is the single source of truth surfaced as hover tooltips in the web
+ * visualisation; the `Record<NodeKind, string>` type makes adding a node kind
+ * without describing it a compile error.
+ */
+export const NODE_KIND_DESCRIPTIONS = {
+    Module: 'A source file in the codebase.',
+    Class: 'A class declaration.',
+    Interface: 'An interface declaration.',
+    TypeAlias: 'A type alias declaration.',
+    Enum: 'An enum declaration.',
+    Function: 'A standalone, module-level function.',
+    Method: 'A function that belongs to a class or interface.',
+    Property: 'A field declared on a class or interface.',
+    Parameter: 'A parameter of a function or method.',
+    Variable: 'A module- or block-level variable binding.',
+    ExternalModule: 'An imported third-party or Node.js module, recorded as one opaque node per import specifier.',
+    ConfigFlag: 'An environment-variable configuration flag, detected from process.env reads.',
+    ExternalAPI: 'An outbound HTTP host called through fetch(), with one node per host.',
+    Endpoint: 'An HTTP route registered by the app, such as app.get("/users", handler).',
+};
 export const RangeSchema = z.object({
     startLine: z.number().int(),
     startColumn: z.number().int(),

package/dist/schema/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/schema/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG;IACzB,QAAQ;IACR,OAAO;IACP,WAAW;IACX,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,UAAU;IACV,WAAW;IACX,UAAU;IACV,gBAAgB;CACP,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAGjD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC3B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,WAAW,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/schema/node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACzB,kBAAkB;IAClB,QAAQ;IACR,OAAO;IACP,WAAW;IACX,WAAW;IACX,MAAM;IACN,UAAU;IACV,QAAQ;IACR,UAAU;IACV,WAAW;IACX,UAAU;IACV,kEAAkE;IAClE,gBAAgB;IAChB,yDAAyD;IACzD,YAAY;IACZ,aAAa;IACb,UAAU;CACD,CAAC;AAEX,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAGjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA6B;IAC/D,MAAM,EAAE,gCAAgC;IACxC,KAAK,EAAE,sBAAsB;IAC7B,SAAS,EAAE,2BAA2B;IACtC,SAAS,EAAE,2BAA2B;IACtC,IAAI,EAAE,sBAAsB;IAC5B,QAAQ,EAAE,sCAAsC;IAChD,MAAM,EAAE,kDAAkD;IAC1D,QAAQ,EAAE,2CAA2C;IACrD,SAAS,EAAE,sCAAsC;IACjD,QAAQ,EAAE,4CAA4C;IACtD,cAAc,EAAE,8FAA8F;IAC9G,UAAU,EAAE,8EAA8E;IAC1F,WAAW,EAAE,uEAAuE;IACpF,QAAQ,EAAE,0EAA0E;CACpF,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC7B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC3B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,WAAW,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC1C,CAAC,CAAC"}

package/dist/schema/runtime_manifest.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+/**
+ * The `GraphMeta` key under which the runtime ingest manifest is stored. It lives
+ * at the graph level — one record for the whole graph — rather than on a node,
+ * which is why it does not collide with the per-node `metadata.runtime`.
+ */
+export declare const RUNTIME_MANIFEST_KEY = "runtime";
+/**
+ * Graph-level coverage facts recorded by `enrich`: how much of the profiled cost
+ * was attributed to graph nodes versus dropped by the join. Persisted so a later
+ * query — `cost` in particular — can report **coverage** (the fraction of total
+ * measured cost the attribution actually accounts for) instead of silently
+ * presenting a partial picture. `total*` are profile-wide; `matched*` are the part
+ * attached to nodes; the difference is what the join dropped.
+ */
+export declare const RuntimeManifestSchema: z.ZodObject<{
+    source: z.ZodString;
+    totalSamples: z.ZodNumber;
+    matchedSamples: z.ZodNumber;
+    totalSelfMicros: z.ZodNumber;
+    matchedSelfMicros: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    source: string;
+    totalSamples: number;
+    matchedSamples: number;
+    totalSelfMicros: number;
+    matchedSelfMicros: number;
+}, {
+    source: string;
+    totalSamples: number;
+    matchedSamples: number;
+    totalSelfMicros: number;
+    matchedSelfMicros: number;
+}>;
+export type RuntimeManifest = z.infer<typeof RuntimeManifestSchema>;
+//# sourceMappingURL=runtime_manifest.d.ts.map

package/dist/schema/runtime_manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_manifest.d.ts","sourceRoot":"","sources":["../../src/schema/runtime_manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;EAMhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/schema/runtime_manifest.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * The `GraphMeta` key under which the runtime ingest manifest is stored. It lives
+ * at the graph level — one record for the whole graph — rather than on a node,
+ * which is why it does not collide with the per-node `metadata.runtime`.
+ */
+export const RUNTIME_MANIFEST_KEY = 'runtime';
+/**
+ * Graph-level coverage facts recorded by `enrich`: how much of the profiled cost
+ * was attributed to graph nodes versus dropped by the join. Persisted so a later
+ * query — `cost` in particular — can report **coverage** (the fraction of total
+ * measured cost the attribution actually accounts for) instead of silently
+ * presenting a partial picture. `total*` are profile-wide; `matched*` are the part
+ * attached to nodes; the difference is what the join dropped.
+ */
+export const RuntimeManifestSchema = z.object({
+    source: z.string(),
+    totalSamples: z.number(),
+    matchedSamples: z.number(),
+    totalSelfMicros: z.number(),
+    matchedSelfMicros: z.number(),
+});
+//# sourceMappingURL=runtime_manifest.js.map

package/dist/schema/runtime_manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_manifest.js","sourceRoot":"","sources":["../../src/schema/runtime_manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAE9C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE;CAC7B,CAAC,CAAC"}

package/dist/store/{jsonl-reader.d.ts → jsonl_reader.d.ts}

@@ -8,4 +8,4 @@ export declare class JsonlReader {
     static read(dir: string): Promise<GraphData>;
     private static readLines;
 }
-//# sourceMappingURL=jsonl-reader.d.ts.map
+//# sourceMappingURL=jsonl_reader.d.ts.map

package/dist/store/{jsonl-reader.d.ts.map → jsonl_reader.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"jsonl-reader.d.ts","sourceRoot":"","sources":["../../src/store/jsonl-reader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACnB,CAAC;AAEF,qBAAa,WAAW;WACV,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;mBAM7B,SAAS;CAO9B"}
+{"version":3,"file":"jsonl_reader.d.ts","sourceRoot":"","sources":["../../src/store/jsonl_reader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAmB,MAAM,mBAAmB,CAAC;AAE/D,MAAM,MAAM,SAAS,GAAG;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;CACnB,CAAC;AAEF,qBAAa,WAAW;WACV,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;mBAM7B,SAAS;CAO9B"}

package/dist/store/{jsonl-reader.js → jsonl_reader.js}

@@ -16,4 +16,4 @@ export class JsonlReader {
             .map((line) => schema.parse(JSON.parse(line)));
     }
 }
-//# sourceMappingURL=jsonl-reader.js.map
+//# sourceMappingURL=jsonl_reader.js.map

package/dist/store/{jsonl-reader.js.map → jsonl_reader.js.map}

@@ -1 +1 @@
-{"version":3,"file":"jsonl-reader.js","sourceRoot":"","sources":["../../src/store/jsonl-reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAO/D,MAAM,OAAO,WAAW;IACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAW;QAC5B,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAI,IAAY,EAAE,MAAoB;QACnE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,OAAO;aACZ,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;aACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;CACD"}
+{"version":3,"file":"jsonl_reader.js","sourceRoot":"","sources":["../../src/store/jsonl_reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAa,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAO/D,MAAM,OAAO,WAAW;IACvB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAW;QAC5B,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,eAAe,CAAC,CAAC;QACrF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAI,IAAY,EAAE,MAAoB;QACnE,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,OAAO;aACZ,KAAK,CAAC,IAAI,CAAC;aACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;aACxC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;CACD"}

package/dist/store/{jsonl-store.d.ts → jsonl_store.d.ts}

@@ -4,4 +4,4 @@ export declare class JsonlStore {
     static write(outDir: string, nodes: GraphNode[], edges: GraphEdge[]): Promise<void>;
     private static serialize;
 }
-//# sourceMappingURL=jsonl-store.d.ts.map
+//# sourceMappingURL=jsonl_store.d.ts.map

package/dist/store/{jsonl-store.d.ts.map → jsonl_store.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"jsonl-store.d.ts","sourceRoot":"","sources":["../../src/store/jsonl-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,qBAAa,UAAU;WACT,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzF,OAAO,CAAC,MAAM,CAAC,SAAS;CAGxB"}
+{"version":3,"file":"jsonl_store.d.ts","sourceRoot":"","sources":["../../src/store/jsonl_store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,qBAAa,UAAU;WACT,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzF,OAAO,CAAC,MAAM,CAAC,SAAS;CAGxB"}

package/dist/store/{jsonl-store.js → jsonl_store.js}

@@ -10,4 +10,4 @@ export class JsonlStore {
         return rows.map((row) => JSON.stringify(row)).join('\n') + '\n';
     }
 }
-//# sourceMappingURL=jsonl-store.js.map
+//# sourceMappingURL=jsonl_store.js.map

package/dist/store/{jsonl-store.js.map → jsonl_store.js.map}

@@ -1 +1 @@
-{"version":3,"file":"jsonl-store.js","sourceRoot":"","sources":["../../src/store/jsonl-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,MAAM,OAAO,UAAU;IACtB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,KAAkB,EAAE,KAAkB;QACxE,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAClF,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAEO,MAAM,CAAC,SAAS,CAAC,IAAe;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,CAAC;CACD"}
+{"version":3,"file":"jsonl_store.js","sourceRoot":"","sources":["../../src/store/jsonl_store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,MAAM,OAAO,UAAU;IACtB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,MAAc,EAAE,KAAkB,EAAE,KAAkB;QACxE,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAClF,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IACnF,CAAC;IAEO,MAAM,CAAC,SAAS,CAAC,IAAe;QACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjE,CAAC;CACD"}

package/dist/store/kuzu_store.d.ts

@@ -0,0 +1,66 @@
+import type { KuzuValue } from 'kuzu';
+import { GraphEdge } from '../schema/edge.js';
+import { GraphNode } from '../schema/node.js';
+/** A stored node read back from Kùzu, with its metadata decoded to a record. */
+export type StoredNode = {
+    id: string;
+    kind: string;
+    name: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    metadata: Record<string, unknown>;
+};
+export declare class KuzuStore {
+    private readonly db;
+    private readonly conn;
+    constructor(dbPath: string);
+    initSchema(): Promise<void>;
+    load(nodes: GraphNode[], edges: GraphEdge[]): Promise<void>;
+    /**
+     * Reads every node back from the store, decoding the `metadata` column. Used
+     * by enrichment to resolve profile frames against the loaded graph's ranges
+     * and to merge new metadata onto existing records.
+     */
+    readNodes(): Promise<StoredNode[]>;
+    /**
+     * Overwrites the `metadata` column for the given nodes. The caller is
+     * responsible for merging so that only the intended keys change; passing the
+     * full record keeps the write idempotent for unchanged keys.
+     */
+    writeNodeMetadata(entries: {
+        id: string;
+        metadata: Record<string, unknown>;
+    }[]): Promise<void>;
+    /**
+     * Writes a graph-level metadata record under `key` (a `GraphMeta` row), encoding
+     * the value as JSON. Used for facts about the whole graph rather than one node —
+     * e.g. the runtime ingest manifest `enrich` records for coverage reporting.
+     */
+    writeGraphMeta(key: string, value: Record<string, unknown>): Promise<void>;
+    /** Reads the graph-level metadata record stored under `key`, decoded, or null when absent. */
+    readGraphMeta(key: string): Promise<Record<string, unknown> | null>;
+    /** Removes the graph-level metadata record stored under `key`, if any. */
+    clearGraphMeta(key: string): Promise<void>;
+    /**
+     * Serializes an optional metadata record to a JSON string for storage in the
+     * `metadata` column. Absent metadata is stored as an empty object so the
+     * column is never null.
+     */
+    private static encodeMetadata;
+    /**
+     * Decodes the JSON `metadata` column back into a record. A missing, empty, or
+     * malformed value decodes to an empty object so callers always receive a record.
+     */
+    private static decodeMetadata;
+    run(cypher: string, params?: Record<string, KuzuValue>): Promise<Record<string, KuzuValue>[]>;
+    close(): Promise<void>;
+    private static first;
+    /**
+     * Releases the native memory behind one or more query results. Results left
+     * unclosed are finalized after the database shuts down at process exit,
+     * which crashes the kuzu native module with a segmentation fault.
+     */
+    private static closeResults;
+}
+//# sourceMappingURL=kuzu_store.d.ts.map

package/dist/store/kuzu_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kuzu_store.d.ts","sourceRoot":"","sources":["../../src/store/kuzu_store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAQF,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAW;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;gBAEtB,MAAM,EAAE,MAAM;IAMpB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BjE;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAexC;;;;OAIG;IACG,iBAAiB,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAapG;;;;OAIG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhF,8FAA8F;IACxF,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAQzE,0EAA0E;IACpE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKhD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAI7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAevB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;IAW7F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,OAAO,CAAC,MAAM,CAAC,KAAK;IAIpB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;CAK3B"}