ts-knowledge-graph 0.1.2 → 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/kuzu_store.d.ts

@@ -1,12 +1,58 @@
 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;

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

@@ -1 +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;AAO9C,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;IAuB3D,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"}
+{"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"}

package/dist/store/kuzu_store.js

@@ -2,8 +2,9 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { Connection, Database } from 'kuzu';
 const SCHEMA = [
-    'CREATE NODE TABLE IF NOT EXISTS GraphNode (id STRING, kind STRING, name STRING, filePath STRING, exported BOOLEAN, startLine INT64, endLine INT64, PRIMARY KEY (id))',
-    'CREATE REL TABLE IF NOT EXISTS Edge (FROM GraphNode TO GraphNode, kind STRING)',
+    'CREATE NODE TABLE IF NOT EXISTS GraphNode (id STRING, kind STRING, name STRING, filePath STRING, exported BOOLEAN, startLine INT64, endLine INT64, metadata STRING, PRIMARY KEY (id))',
+    'CREATE REL TABLE IF NOT EXISTS Edge (FROM GraphNode TO GraphNode, kind STRING, metadata STRING)',
+    'CREATE NODE TABLE IF NOT EXISTS GraphMeta (key STRING, value STRING, PRIMARY KEY (key))',
 ];
 export class KuzuStore {
     constructor(dbPath) {
@@ -17,7 +18,7 @@ export class KuzuStore {
         }
     }
     async load(nodes, edges) {
-        const nodeStmt = await this.conn.prepare('MERGE (n:GraphNode {id: $id}) SET n.kind = $kind, n.name = $name, n.filePath = $filePath, n.exported = $exported, n.startLine = $startLine, n.endLine = $endLine');
+        const nodeStmt = await this.conn.prepare('MERGE (n:GraphNode {id: $id}) SET n.kind = $kind, n.name = $name, n.filePath = $filePath, n.exported = $exported, n.startLine = $startLine, n.endLine = $endLine, n.metadata = $metadata');
         for (const node of nodes) {
             KuzuStore.closeResults(await this.conn.execute(nodeStmt, {
                 id: node.id,
@@ -27,11 +28,100 @@ export class KuzuStore {
                 exported: node.exported ?? false,
                 startLine: node.range?.startLine ?? 0,
                 endLine: node.range?.endLine ?? 0,
+                metadata: KuzuStore.encodeMetadata(node.metadata),
             }));
         }
-        const edgeStmt = await this.conn.prepare('MATCH (f:GraphNode {id: $from}), (t:GraphNode {id: $to}) MERGE (f)-[:Edge {kind: $kind}]->(t)');
+        const edgeStmt = await this.conn.prepare('MATCH (f:GraphNode {id: $from}), (t:GraphNode {id: $to}) MERGE (f)-[e:Edge {kind: $kind}]->(t) SET e.metadata = $metadata');
         for (const edge of edges) {
-            KuzuStore.closeResults(await this.conn.execute(edgeStmt, { from: edge.from, to: edge.to, kind: edge.kind }));
+            KuzuStore.closeResults(await this.conn.execute(edgeStmt, {
+                from: edge.from,
+                to: edge.to,
+                kind: edge.kind,
+                metadata: KuzuStore.encodeMetadata(edge.metadata),
+            }));
+        }
+    }
+    /**
+     * 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.
+     */
+    async readNodes() {
+        const rows = await this.run('MATCH (n:GraphNode) RETURN n.id AS id, n.kind AS kind, n.name AS name, n.filePath AS filePath, n.startLine AS startLine, n.endLine AS endLine, n.metadata AS metadata');
+        return rows.map((row) => ({
+            id: String(row.id),
+            kind: String(row.kind),
+            name: String(row.name),
+            filePath: String(row.filePath),
+            startLine: Number(row.startLine),
+            endLine: Number(row.endLine),
+            metadata: KuzuStore.decodeMetadata(row.metadata),
+        }));
+    }
+    /**
+     * 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.
+     */
+    async writeNodeMetadata(entries) {
+        if (entries.length === 0) {
+            return;
+        }
+        const stmt = await this.conn.prepare('MATCH (n:GraphNode {id: $id}) SET n.metadata = $metadata');
+        for (const entry of entries) {
+            KuzuStore.closeResults(await this.conn.execute(stmt, {
+                id: entry.id,
+                metadata: KuzuStore.encodeMetadata(entry.metadata),
+            }));
+        }
+    }
+    /**
+     * 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.
+     */
+    async writeGraphMeta(key, value) {
+        const stmt = await this.conn.prepare('MERGE (m:GraphMeta {key: $key}) SET m.value = $value');
+        KuzuStore.closeResults(await this.conn.execute(stmt, { key, value: KuzuStore.encodeMetadata(value) }));
+    }
+    /** Reads the graph-level metadata record stored under `key`, decoded, or null when absent. */
+    async readGraphMeta(key) {
+        const rows = await this.run('MATCH (m:GraphMeta {key: $key}) RETURN m.value AS value', { key });
+        if (rows.length === 0) {
+            return null;
+        }
+        return KuzuStore.decodeMetadata(rows[0].value);
+    }
+    /** Removes the graph-level metadata record stored under `key`, if any. */
+    async clearGraphMeta(key) {
+        const stmt = await this.conn.prepare('MATCH (m:GraphMeta {key: $key}) DELETE m');
+        KuzuStore.closeResults(await this.conn.execute(stmt, { key }));
+    }
+    /**
+     * 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.
+     */
+    static encodeMetadata(metadata) {
+        return JSON.stringify(metadata ?? {});
+    }
+    /**
+     * 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.
+     */
+    static decodeMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null) {
+                return parsed;
+            }
+            return {};
+        }
+        catch {
+            return {};
         }
     }
     async run(cypher, params) {

package/dist/store/kuzu_store.js.map

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