@harness-engineering/graph 0.4.2 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.d.mts +58 -10
  2. package/dist/index.d.ts +58 -10
  3. package/dist/index.js +110 -3
  4. package/dist/index.mjs +107 -3
  5. package/package.json +1 -1
package/dist/index.d.mts CHANGED
@@ -1,8 +1,8 @@
1
1
  import { z } from 'zod';
2
2
 
3
- declare const NODE_TYPES: readonly ["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement"];
3
+ declare const NODE_TYPES: readonly ["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement", "packed_summary"];
4
4
  type NodeType = (typeof NODE_TYPES)[number];
5
- declare const EDGE_TYPES: readonly ["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by"];
5
+ declare const EDGE_TYPES: readonly ["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by", "caches"];
6
6
  type EdgeType = (typeof EDGE_TYPES)[number];
7
7
  declare const OBSERVABILITY_TYPES: ReadonlySet<NodeType>;
8
8
  interface SourceLocation {
@@ -68,9 +68,18 @@ interface GraphMetadata {
68
68
  readonly edgeCount: number;
69
69
  }
70
70
  declare const CURRENT_SCHEMA_VERSION = 1;
71
+ /** Stability classification for prompt caching -- mirrors StabilityTier from @harness-engineering/types. */
72
+ type GraphStabilityTier = 'static' | 'session' | 'ephemeral';
73
+ /**
74
+ * Maps graph node types to their caching stability tier.
75
+ * Used by provider cache adapters to determine cache directives.
76
+ *
77
+ * Node types not listed here default to 'ephemeral' at resolution time.
78
+ */
79
+ declare const NODE_STABILITY: Record<string, GraphStabilityTier>;
71
80
  declare const GraphNodeSchema: z.ZodObject<{
72
81
  id: z.ZodString;
73
- type: z.ZodEnum<["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement"]>;
82
+ type: z.ZodEnum<["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement", "packed_summary"]>;
74
83
  name: z.ZodString;
75
84
  path: z.ZodOptional<z.ZodString>;
76
85
  location: z.ZodOptional<z.ZodObject<{
@@ -99,7 +108,7 @@ declare const GraphNodeSchema: z.ZodObject<{
99
108
  lastModified: z.ZodOptional<z.ZodString>;
100
109
  }, "strip", z.ZodTypeAny, {
101
110
  id: string;
102
- type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement";
111
+ type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement" | "packed_summary";
103
112
  name: string;
104
113
  metadata: Record<string, unknown>;
105
114
  path?: string | undefined;
@@ -116,7 +125,7 @@ declare const GraphNodeSchema: z.ZodObject<{
116
125
  lastModified?: string | undefined;
117
126
  }, {
118
127
  id: string;
119
- type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement";
128
+ type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement" | "packed_summary";
120
129
  name: string;
121
130
  metadata: Record<string, unknown>;
122
131
  path?: string | undefined;
@@ -135,17 +144,17 @@ declare const GraphNodeSchema: z.ZodObject<{
135
144
  declare const GraphEdgeSchema: z.ZodObject<{
136
145
  from: z.ZodString;
137
146
  to: z.ZodString;
138
- type: z.ZodEnum<["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by"]>;
147
+ type: z.ZodEnum<["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by", "caches"]>;
139
148
  confidence: z.ZodOptional<z.ZodNumber>;
140
149
  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
141
150
  }, "strip", z.ZodTypeAny, {
142
- type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by";
151
+ type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by" | "caches";
143
152
  from: string;
144
153
  to: string;
145
154
  metadata?: Record<string, unknown> | undefined;
146
155
  confidence?: number | undefined;
147
156
  }, {
148
- type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by";
157
+ type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by" | "caches";
149
158
  from: string;
150
159
  to: string;
151
160
  metadata?: Record<string, unknown> | undefined;
@@ -245,6 +254,45 @@ interface SerializedGraph {
245
254
  declare function saveGraph(dirPath: string, nodes: readonly GraphNode[], edges: readonly GraphEdge[]): Promise<void>;
246
255
  declare function loadGraph(dirPath: string): Promise<SerializedGraph | null>;
247
256
 
257
+ /**
258
+ * Minimal PackedEnvelope shape -- avoids circular dep on @harness-engineering/core.
259
+ * Canonical type: packages/core/src/compaction/envelope.ts — keep in sync.
260
+ */
261
+ interface PackedEnvelope {
262
+ meta: {
263
+ strategy: string[];
264
+ originalTokenEstimate: number;
265
+ compactedTokenEstimate: number;
266
+ reductionPct: number;
267
+ cached: boolean;
268
+ };
269
+ sections: Array<{
270
+ source: string;
271
+ content: string;
272
+ }>;
273
+ }
274
+
275
+ /** Normalize an intent string for deterministic cache keying. */
276
+ declare function normalizeIntent(intent: string): string;
277
+ /** Reads/writes PackedSummary nodes in the GraphStore. Validates via TTL + source freshness. */
278
+ declare class PackedSummaryCache {
279
+ private readonly store;
280
+ private readonly ttlMs;
281
+ constructor(store: GraphStore, ttlMs?: number);
282
+ /** Returns cached envelope with `cached: true` if valid, or null if miss/stale. */
283
+ get(intent: string): PackedEnvelope | null;
284
+ /** Parse and validate createdAt. Returns epoch ms or null if missing/malformed (GC-002). */
285
+ private parseCreatedMs;
286
+ /** GC-001: Checks source nodes exist and are unmodified since cache creation. */
287
+ private areSourcesFresh;
288
+ /** Parse envelope JSON and set cached: true. Returns null on invalid JSON. */
289
+ private parseEnvelope;
290
+ /** Write a PackedSummary node with caches edges to source nodes. */
291
+ set(intent: string, envelope: PackedEnvelope, sourceNodeIds: string[]): void;
292
+ /** Explicitly invalidate a cached packed summary. */
293
+ invalidate(intent: string): void;
294
+ }
295
+
248
296
  declare class ContextQL {
249
297
  private readonly store;
250
298
  constructor(store: GraphStore);
@@ -1171,6 +1219,6 @@ declare class CascadeSimulator {
1171
1219
  private buildResult;
1172
1220
  }
1173
1221
 
1174
- declare const VERSION = "0.4.1";
1222
+ declare const VERSION = "0.4.3";
1175
1223
 
1176
- export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type CascadeLayer, type CascadeNode, type CascadeResult, type CascadeSimulationOptions, CascadeSimulator, type ClassificationResult, CodeIngestor, CompositeProbabilityStrategy, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, type GraphCoverageReport, type GraphDeadCodeData, type GraphDependencyData, type GraphDriftData, type GraphEdge, GraphEdgeSchema, GraphEntropyAdapter, GraphFeedbackAdapter, type GraphFilterResult, type GraphHarnessCheckData, type GraphImpactData, type GraphLayerViolation, type GraphMetadata, type GraphNode, GraphNodeSchema, type GraphSnapshotSummary, GraphStore, type HttpClient, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeCategory, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, type PairResult, type ProbabilityStrategy, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, classifyNodeCategory, groupNodesByImpact, linkToCode, loadGraph, project, queryTraceability, saveGraph };
1224
+ export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type PackedEnvelope as CacheableEnvelope, type CascadeLayer, type CascadeNode, type CascadeResult, type CascadeSimulationOptions, CascadeSimulator, type ClassificationResult, CodeIngestor, CompositeProbabilityStrategy, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, type GraphCoverageReport, type GraphDeadCodeData, type GraphDependencyData, type GraphDriftData, type GraphEdge, GraphEdgeSchema, GraphEntropyAdapter, GraphFeedbackAdapter, type GraphFilterResult, type GraphHarnessCheckData, type GraphImpactData, type GraphLayerViolation, type GraphMetadata, type GraphNode, GraphNodeSchema, type GraphSnapshotSummary, type GraphStabilityTier, GraphStore, type HttpClient, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_STABILITY, NODE_TYPES, type NodeCategory, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, PackedSummaryCache, type PairResult, type ProbabilityStrategy, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, classifyNodeCategory, groupNodesByImpact, linkToCode, loadGraph, normalizeIntent, project, queryTraceability, saveGraph };
package/dist/index.d.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  import { z } from 'zod';
2
2
 
3
- declare const NODE_TYPES: readonly ["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement"];
3
+ declare const NODE_TYPES: readonly ["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement", "packed_summary"];
4
4
  type NodeType = (typeof NODE_TYPES)[number];
5
- declare const EDGE_TYPES: readonly ["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by"];
5
+ declare const EDGE_TYPES: readonly ["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by", "caches"];
6
6
  type EdgeType = (typeof EDGE_TYPES)[number];
7
7
  declare const OBSERVABILITY_TYPES: ReadonlySet<NodeType>;
8
8
  interface SourceLocation {
@@ -68,9 +68,18 @@ interface GraphMetadata {
68
68
  readonly edgeCount: number;
69
69
  }
70
70
  declare const CURRENT_SCHEMA_VERSION = 1;
71
+ /** Stability classification for prompt caching -- mirrors StabilityTier from @harness-engineering/types. */
72
+ type GraphStabilityTier = 'static' | 'session' | 'ephemeral';
73
+ /**
74
+ * Maps graph node types to their caching stability tier.
75
+ * Used by provider cache adapters to determine cache directives.
76
+ *
77
+ * Node types not listed here default to 'ephemeral' at resolution time.
78
+ */
79
+ declare const NODE_STABILITY: Record<string, GraphStabilityTier>;
71
80
  declare const GraphNodeSchema: z.ZodObject<{
72
81
  id: z.ZodString;
73
- type: z.ZodEnum<["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement"]>;
82
+ type: z.ZodEnum<["repository", "module", "file", "class", "interface", "function", "method", "variable", "adr", "decision", "learning", "failure", "issue", "document", "skill", "conversation", "commit", "build", "test_result", "span", "metric", "log", "layer", "pattern", "constraint", "violation", "design_token", "aesthetic_intent", "design_constraint", "requirement", "packed_summary"]>;
74
83
  name: z.ZodString;
75
84
  path: z.ZodOptional<z.ZodString>;
76
85
  location: z.ZodOptional<z.ZodObject<{
@@ -99,7 +108,7 @@ declare const GraphNodeSchema: z.ZodObject<{
99
108
  lastModified: z.ZodOptional<z.ZodString>;
100
109
  }, "strip", z.ZodTypeAny, {
101
110
  id: string;
102
- type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement";
111
+ type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement" | "packed_summary";
103
112
  name: string;
104
113
  metadata: Record<string, unknown>;
105
114
  path?: string | undefined;
@@ -116,7 +125,7 @@ declare const GraphNodeSchema: z.ZodObject<{
116
125
  lastModified?: string | undefined;
117
126
  }, {
118
127
  id: string;
119
- type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement";
128
+ type: "function" | "repository" | "module" | "file" | "class" | "interface" | "method" | "variable" | "adr" | "decision" | "learning" | "failure" | "issue" | "document" | "skill" | "conversation" | "commit" | "build" | "test_result" | "span" | "metric" | "log" | "layer" | "pattern" | "constraint" | "violation" | "design_token" | "aesthetic_intent" | "design_constraint" | "requirement" | "packed_summary";
120
129
  name: string;
121
130
  metadata: Record<string, unknown>;
122
131
  path?: string | undefined;
@@ -135,17 +144,17 @@ declare const GraphNodeSchema: z.ZodObject<{
135
144
  declare const GraphEdgeSchema: z.ZodObject<{
136
145
  from: z.ZodString;
137
146
  to: z.ZodString;
138
- type: z.ZodEnum<["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by"]>;
147
+ type: z.ZodEnum<["contains", "imports", "calls", "implements", "inherits", "references", "applies_to", "caused_by", "resolved_by", "documents", "violates", "specifies", "decided", "co_changes_with", "triggered_by", "failed_in", "executed_by", "measured_by", "uses_token", "declares_intent", "violates_design", "platform_binding", "requires", "verified_by", "tested_by", "caches"]>;
139
148
  confidence: z.ZodOptional<z.ZodNumber>;
140
149
  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
141
150
  }, "strip", z.ZodTypeAny, {
142
- type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by";
151
+ type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by" | "caches";
143
152
  from: string;
144
153
  to: string;
145
154
  metadata?: Record<string, unknown> | undefined;
146
155
  confidence?: number | undefined;
147
156
  }, {
148
- type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by";
157
+ type: "contains" | "imports" | "calls" | "implements" | "inherits" | "references" | "applies_to" | "caused_by" | "resolved_by" | "documents" | "violates" | "specifies" | "decided" | "co_changes_with" | "triggered_by" | "failed_in" | "executed_by" | "measured_by" | "uses_token" | "declares_intent" | "violates_design" | "platform_binding" | "requires" | "verified_by" | "tested_by" | "caches";
149
158
  from: string;
150
159
  to: string;
151
160
  metadata?: Record<string, unknown> | undefined;
@@ -245,6 +254,45 @@ interface SerializedGraph {
245
254
  declare function saveGraph(dirPath: string, nodes: readonly GraphNode[], edges: readonly GraphEdge[]): Promise<void>;
246
255
  declare function loadGraph(dirPath: string): Promise<SerializedGraph | null>;
247
256
 
257
+ /**
258
+ * Minimal PackedEnvelope shape -- avoids circular dep on @harness-engineering/core.
259
+ * Canonical type: packages/core/src/compaction/envelope.ts — keep in sync.
260
+ */
261
+ interface PackedEnvelope {
262
+ meta: {
263
+ strategy: string[];
264
+ originalTokenEstimate: number;
265
+ compactedTokenEstimate: number;
266
+ reductionPct: number;
267
+ cached: boolean;
268
+ };
269
+ sections: Array<{
270
+ source: string;
271
+ content: string;
272
+ }>;
273
+ }
274
+
275
+ /** Normalize an intent string for deterministic cache keying. */
276
+ declare function normalizeIntent(intent: string): string;
277
+ /** Reads/writes PackedSummary nodes in the GraphStore. Validates via TTL + source freshness. */
278
+ declare class PackedSummaryCache {
279
+ private readonly store;
280
+ private readonly ttlMs;
281
+ constructor(store: GraphStore, ttlMs?: number);
282
+ /** Returns cached envelope with `cached: true` if valid, or null if miss/stale. */
283
+ get(intent: string): PackedEnvelope | null;
284
+ /** Parse and validate createdAt. Returns epoch ms or null if missing/malformed (GC-002). */
285
+ private parseCreatedMs;
286
+ /** GC-001: Checks source nodes exist and are unmodified since cache creation. */
287
+ private areSourcesFresh;
288
+ /** Parse envelope JSON and set cached: true. Returns null on invalid JSON. */
289
+ private parseEnvelope;
290
+ /** Write a PackedSummary node with caches edges to source nodes. */
291
+ set(intent: string, envelope: PackedEnvelope, sourceNodeIds: string[]): void;
292
+ /** Explicitly invalidate a cached packed summary. */
293
+ invalidate(intent: string): void;
294
+ }
295
+
248
296
  declare class ContextQL {
249
297
  private readonly store;
250
298
  constructor(store: GraphStore);
@@ -1171,6 +1219,6 @@ declare class CascadeSimulator {
1171
1219
  private buildResult;
1172
1220
  }
1173
1221
 
1174
- declare const VERSION = "0.4.1";
1222
+ declare const VERSION = "0.4.3";
1175
1223
 
1176
- export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type CascadeLayer, type CascadeNode, type CascadeResult, type CascadeSimulationOptions, CascadeSimulator, type ClassificationResult, CodeIngestor, CompositeProbabilityStrategy, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, type GraphCoverageReport, type GraphDeadCodeData, type GraphDependencyData, type GraphDriftData, type GraphEdge, GraphEdgeSchema, GraphEntropyAdapter, GraphFeedbackAdapter, type GraphFilterResult, type GraphHarnessCheckData, type GraphImpactData, type GraphLayerViolation, type GraphMetadata, type GraphNode, GraphNodeSchema, type GraphSnapshotSummary, GraphStore, type HttpClient, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_TYPES, type NodeCategory, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, type PairResult, type ProbabilityStrategy, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, classifyNodeCategory, groupNodesByImpact, linkToCode, loadGraph, project, queryTraceability, saveGraph };
1224
+ export { type AnomalyDetectionOptions, type AnomalyReport, type ArticulationPoint, type AskGraphResult, type AssembledContext, Assembler, CIConnector, CURRENT_SCHEMA_VERSION, type PackedEnvelope as CacheableEnvelope, type CascadeLayer, type CascadeNode, type CascadeResult, type CascadeSimulationOptions, CascadeSimulator, type ClassificationResult, CodeIngestor, CompositeProbabilityStrategy, type ConflictDetail, type ConflictPrediction, ConflictPredictor, type ConflictSeverity, ConfluenceConnector, type ConnectorConfig, ContextQL, type ContextQLParams, type ContextQLResult, DesignConstraintAdapter, DesignIngestor, type DesignStrictness, type DesignViolation, EDGE_TYPES, type EdgeQuery, type EdgeType, EntityExtractor, EntityResolver, FusionLayer, type FusionResult, GitIngestor, type GitRunner, GraphAnomalyAdapter, type GraphBudget, GraphComplexityAdapter, type GraphComplexityHotspot, type GraphComplexityResult, type GraphConnector, GraphConstraintAdapter, GraphCouplingAdapter, type GraphCouplingFileData, type GraphCouplingResult, type GraphCoverageReport, type GraphDeadCodeData, type GraphDependencyData, type GraphDriftData, type GraphEdge, GraphEdgeSchema, GraphEntropyAdapter, GraphFeedbackAdapter, type GraphFilterResult, type GraphHarnessCheckData, type GraphImpactData, type GraphLayerViolation, type GraphMetadata, type GraphNode, GraphNodeSchema, type GraphSnapshotSummary, type GraphStabilityTier, GraphStore, type HttpClient, INTENTS, type ImpactGroups, type IndependenceCheckParams, type IndependenceResult, type IngestResult, type Intent, IntentClassifier, JiraConnector, KnowledgeIngestor, type LinkResult, NODE_STABILITY, NODE_TYPES, type NodeCategory, type NodeQuery, type NodeType, OBSERVABILITY_TYPES, type OverlapDetail, PackedSummaryCache, type PairResult, type ProbabilityStrategy, type ProjectionSpec, type RequirementCoverage, RequirementIngestor, type ResolvedEntity, ResponseFormatter, SlackConnector, type SourceLocation, type StatisticalOutlier, SyncManager, type SyncMetadata, type TaskDefinition, TaskIndependenceAnalyzer, TopologicalLinker, type TraceabilityOptions, type TraceabilityResult, type TracedFile, VERSION, type VectorSearchResult, VectorStore, askGraph, classifyNodeCategory, groupNodesByImpact, linkToCode, loadGraph, normalizeIntent, project, queryTraceability, saveGraph };
package/dist/index.js CHANGED
@@ -59,8 +59,10 @@ __export(index_exports, {
59
59
  IntentClassifier: () => IntentClassifier,
60
60
  JiraConnector: () => JiraConnector,
61
61
  KnowledgeIngestor: () => KnowledgeIngestor,
62
+ NODE_STABILITY: () => NODE_STABILITY,
62
63
  NODE_TYPES: () => NODE_TYPES,
63
64
  OBSERVABILITY_TYPES: () => OBSERVABILITY_TYPES,
65
+ PackedSummaryCache: () => PackedSummaryCache,
64
66
  RequirementIngestor: () => RequirementIngestor,
65
67
  ResponseFormatter: () => ResponseFormatter,
66
68
  SlackConnector: () => SlackConnector,
@@ -74,6 +76,7 @@ __export(index_exports, {
74
76
  groupNodesByImpact: () => groupNodesByImpact,
75
77
  linkToCode: () => linkToCode,
76
78
  loadGraph: () => loadGraph,
79
+ normalizeIntent: () => normalizeIntent,
77
80
  project: () => project,
78
81
  queryTraceability: () => queryTraceability,
79
82
  saveGraph: () => saveGraph
@@ -119,7 +122,9 @@ var NODE_TYPES = [
119
122
  "aesthetic_intent",
120
123
  "design_constraint",
121
124
  // Traceability
122
- "requirement"
125
+ "requirement",
126
+ // Cache
127
+ "packed_summary"
123
128
  ];
124
129
  var EDGE_TYPES = [
125
130
  // Code relationships
@@ -152,10 +157,21 @@ var EDGE_TYPES = [
152
157
  // Traceability relationships
153
158
  "requires",
154
159
  "verified_by",
155
- "tested_by"
160
+ "tested_by",
161
+ // Cache relationships
162
+ "caches"
156
163
  ];
157
164
  var OBSERVABILITY_TYPES = /* @__PURE__ */ new Set(["span", "metric", "log"]);
158
165
  var CURRENT_SCHEMA_VERSION = 1;
166
+ var NODE_STABILITY = {
167
+ File: "session",
168
+ Function: "session",
169
+ Class: "session",
170
+ Constraint: "session",
171
+ PackedSummary: "session",
172
+ SkillDefinition: "static",
173
+ ToolDefinition: "static"
174
+ };
159
175
  var GraphNodeSchema = import_zod.z.object({
160
176
  id: import_zod.z.string(),
161
177
  type: import_zod.z.enum(NODE_TYPES),
@@ -491,6 +507,94 @@ var VectorStore = class _VectorStore {
491
507
  }
492
508
  };
493
509
 
510
+ // src/store/PackedSummaryCache.ts
511
+ var DEFAULT_TTL_MS = 60 * 60 * 1e3;
512
+ function normalizeIntent(intent) {
513
+ return intent.trim().toLowerCase().replace(/\s+/g, " ");
514
+ }
515
+ function cacheNodeId(normalizedIntent) {
516
+ return `packed_summary:${normalizedIntent}`;
517
+ }
518
+ var PackedSummaryCache = class {
519
+ constructor(store, ttlMs = DEFAULT_TTL_MS) {
520
+ this.store = store;
521
+ this.ttlMs = ttlMs;
522
+ }
523
+ store;
524
+ ttlMs;
525
+ /** Returns cached envelope with `cached: true` if valid, or null if miss/stale. */
526
+ get(intent) {
527
+ const normalized = normalizeIntent(intent);
528
+ const nodeId = cacheNodeId(normalized);
529
+ const node = this.store.getNode(nodeId);
530
+ if (!node) return null;
531
+ const createdMs = this.parseCreatedMs(node.metadata["createdAt"]);
532
+ if (createdMs === null) return null;
533
+ if (Date.now() - createdMs > this.ttlMs) return null;
534
+ if (!this.areSourcesFresh(nodeId, node, createdMs)) return null;
535
+ return this.parseEnvelope(node.metadata["envelope"]);
536
+ }
537
+ /** Parse and validate createdAt. Returns epoch ms or null if missing/malformed (GC-002). */
538
+ parseCreatedMs(createdAt) {
539
+ if (!createdAt) return null;
540
+ const ms = new Date(createdAt).getTime();
541
+ return Number.isNaN(ms) ? null : ms;
542
+ }
543
+ /** GC-001: Checks source nodes exist and are unmodified since cache creation. */
544
+ areSourcesFresh(nodeId, node, createdMs) {
545
+ const sourceNodeIds = node.metadata["sourceNodeIds"];
546
+ const edges = this.store.getEdges({ from: nodeId, type: "caches" });
547
+ if (sourceNodeIds && edges.length < sourceNodeIds.length) return false;
548
+ for (const edge of edges) {
549
+ const sourceNode = this.store.getNode(edge.to);
550
+ if (!sourceNode) return false;
551
+ if (sourceNode.lastModified) {
552
+ const sourceModMs = new Date(sourceNode.lastModified).getTime();
553
+ if (sourceModMs > createdMs) return false;
554
+ }
555
+ }
556
+ return true;
557
+ }
558
+ /** Parse envelope JSON and set cached: true. Returns null on invalid JSON. */
559
+ parseEnvelope(raw) {
560
+ try {
561
+ const envelope = JSON.parse(raw);
562
+ return { ...envelope, meta: { ...envelope.meta, cached: true } };
563
+ } catch {
564
+ return null;
565
+ }
566
+ }
567
+ /** Write a PackedSummary node with caches edges to source nodes. */
568
+ set(intent, envelope, sourceNodeIds) {
569
+ const normalized = normalizeIntent(intent);
570
+ const nodeId = cacheNodeId(normalized);
571
+ this.store.removeNode(nodeId);
572
+ this.store.addNode({
573
+ id: nodeId,
574
+ type: "packed_summary",
575
+ name: normalized,
576
+ metadata: {
577
+ envelope: JSON.stringify(envelope),
578
+ createdAt: (/* @__PURE__ */ new Date()).toISOString(),
579
+ sourceNodeIds
580
+ }
581
+ });
582
+ for (const sourceId of sourceNodeIds) {
583
+ this.store.addEdge({
584
+ from: nodeId,
585
+ to: sourceId,
586
+ type: "caches"
587
+ });
588
+ }
589
+ }
590
+ /** Explicitly invalidate a cached packed summary. */
591
+ invalidate(intent) {
592
+ const normalized = normalizeIntent(intent);
593
+ const nodeId = cacheNodeId(normalized);
594
+ this.store.removeNode(nodeId);
595
+ }
596
+ };
597
+
494
598
  // src/query/ContextQL.ts
495
599
  function edgeKey2(e) {
496
600
  return `${e.from}|${e.to}|${e.type}`;
@@ -5180,7 +5284,7 @@ var ConflictPredictor = class {
5180
5284
  };
5181
5285
 
5182
5286
  // src/index.ts
5183
- var VERSION = "0.4.1";
5287
+ var VERSION = "0.4.3";
5184
5288
  // Annotate the CommonJS export names for ESM import in node:
5185
5289
  0 && (module.exports = {
5186
5290
  Assembler,
@@ -5212,8 +5316,10 @@ var VERSION = "0.4.1";
5212
5316
  IntentClassifier,
5213
5317
  JiraConnector,
5214
5318
  KnowledgeIngestor,
5319
+ NODE_STABILITY,
5215
5320
  NODE_TYPES,
5216
5321
  OBSERVABILITY_TYPES,
5322
+ PackedSummaryCache,
5217
5323
  RequirementIngestor,
5218
5324
  ResponseFormatter,
5219
5325
  SlackConnector,
@@ -5227,6 +5333,7 @@ var VERSION = "0.4.1";
5227
5333
  groupNodesByImpact,
5228
5334
  linkToCode,
5229
5335
  loadGraph,
5336
+ normalizeIntent,
5230
5337
  project,
5231
5338
  queryTraceability,
5232
5339
  saveGraph
package/dist/index.mjs CHANGED
@@ -37,7 +37,9 @@ var NODE_TYPES = [
37
37
  "aesthetic_intent",
38
38
  "design_constraint",
39
39
  // Traceability
40
- "requirement"
40
+ "requirement",
41
+ // Cache
42
+ "packed_summary"
41
43
  ];
42
44
  var EDGE_TYPES = [
43
45
  // Code relationships
@@ -70,10 +72,21 @@ var EDGE_TYPES = [
70
72
  // Traceability relationships
71
73
  "requires",
72
74
  "verified_by",
73
- "tested_by"
75
+ "tested_by",
76
+ // Cache relationships
77
+ "caches"
74
78
  ];
75
79
  var OBSERVABILITY_TYPES = /* @__PURE__ */ new Set(["span", "metric", "log"]);
76
80
  var CURRENT_SCHEMA_VERSION = 1;
81
+ var NODE_STABILITY = {
82
+ File: "session",
83
+ Function: "session",
84
+ Class: "session",
85
+ Constraint: "session",
86
+ PackedSummary: "session",
87
+ SkillDefinition: "static",
88
+ ToolDefinition: "static"
89
+ };
77
90
  var GraphNodeSchema = z.object({
78
91
  id: z.string(),
79
92
  type: z.enum(NODE_TYPES),
@@ -409,6 +422,94 @@ var VectorStore = class _VectorStore {
409
422
  }
410
423
  };
411
424
 
425
+ // src/store/PackedSummaryCache.ts
426
+ var DEFAULT_TTL_MS = 60 * 60 * 1e3;
427
+ function normalizeIntent(intent) {
428
+ return intent.trim().toLowerCase().replace(/\s+/g, " ");
429
+ }
430
+ function cacheNodeId(normalizedIntent) {
431
+ return `packed_summary:${normalizedIntent}`;
432
+ }
433
+ var PackedSummaryCache = class {
434
+ constructor(store, ttlMs = DEFAULT_TTL_MS) {
435
+ this.store = store;
436
+ this.ttlMs = ttlMs;
437
+ }
438
+ store;
439
+ ttlMs;
440
+ /** Returns cached envelope with `cached: true` if valid, or null if miss/stale. */
441
+ get(intent) {
442
+ const normalized = normalizeIntent(intent);
443
+ const nodeId = cacheNodeId(normalized);
444
+ const node = this.store.getNode(nodeId);
445
+ if (!node) return null;
446
+ const createdMs = this.parseCreatedMs(node.metadata["createdAt"]);
447
+ if (createdMs === null) return null;
448
+ if (Date.now() - createdMs > this.ttlMs) return null;
449
+ if (!this.areSourcesFresh(nodeId, node, createdMs)) return null;
450
+ return this.parseEnvelope(node.metadata["envelope"]);
451
+ }
452
+ /** Parse and validate createdAt. Returns epoch ms or null if missing/malformed (GC-002). */
453
+ parseCreatedMs(createdAt) {
454
+ if (!createdAt) return null;
455
+ const ms = new Date(createdAt).getTime();
456
+ return Number.isNaN(ms) ? null : ms;
457
+ }
458
+ /** GC-001: Checks source nodes exist and are unmodified since cache creation. */
459
+ areSourcesFresh(nodeId, node, createdMs) {
460
+ const sourceNodeIds = node.metadata["sourceNodeIds"];
461
+ const edges = this.store.getEdges({ from: nodeId, type: "caches" });
462
+ if (sourceNodeIds && edges.length < sourceNodeIds.length) return false;
463
+ for (const edge of edges) {
464
+ const sourceNode = this.store.getNode(edge.to);
465
+ if (!sourceNode) return false;
466
+ if (sourceNode.lastModified) {
467
+ const sourceModMs = new Date(sourceNode.lastModified).getTime();
468
+ if (sourceModMs > createdMs) return false;
469
+ }
470
+ }
471
+ return true;
472
+ }
473
+ /** Parse envelope JSON and set cached: true. Returns null on invalid JSON. */
474
+ parseEnvelope(raw) {
475
+ try {
476
+ const envelope = JSON.parse(raw);
477
+ return { ...envelope, meta: { ...envelope.meta, cached: true } };
478
+ } catch {
479
+ return null;
480
+ }
481
+ }
482
+ /** Write a PackedSummary node with caches edges to source nodes. */
483
+ set(intent, envelope, sourceNodeIds) {
484
+ const normalized = normalizeIntent(intent);
485
+ const nodeId = cacheNodeId(normalized);
486
+ this.store.removeNode(nodeId);
487
+ this.store.addNode({
488
+ id: nodeId,
489
+ type: "packed_summary",
490
+ name: normalized,
491
+ metadata: {
492
+ envelope: JSON.stringify(envelope),
493
+ createdAt: (/* @__PURE__ */ new Date()).toISOString(),
494
+ sourceNodeIds
495
+ }
496
+ });
497
+ for (const sourceId of sourceNodeIds) {
498
+ this.store.addEdge({
499
+ from: nodeId,
500
+ to: sourceId,
501
+ type: "caches"
502
+ });
503
+ }
504
+ }
505
+ /** Explicitly invalidate a cached packed summary. */
506
+ invalidate(intent) {
507
+ const normalized = normalizeIntent(intent);
508
+ const nodeId = cacheNodeId(normalized);
509
+ this.store.removeNode(nodeId);
510
+ }
511
+ };
512
+
412
513
  // src/query/ContextQL.ts
413
514
  function edgeKey2(e) {
414
515
  return `${e.from}|${e.to}|${e.type}`;
@@ -5098,7 +5199,7 @@ var ConflictPredictor = class {
5098
5199
  };
5099
5200
 
5100
5201
  // src/index.ts
5101
- var VERSION = "0.4.1";
5202
+ var VERSION = "0.4.3";
5102
5203
  export {
5103
5204
  Assembler,
5104
5205
  CIConnector,
@@ -5129,8 +5230,10 @@ export {
5129
5230
  IntentClassifier,
5130
5231
  JiraConnector,
5131
5232
  KnowledgeIngestor,
5233
+ NODE_STABILITY,
5132
5234
  NODE_TYPES,
5133
5235
  OBSERVABILITY_TYPES,
5236
+ PackedSummaryCache,
5134
5237
  RequirementIngestor,
5135
5238
  ResponseFormatter,
5136
5239
  SlackConnector,
@@ -5144,6 +5247,7 @@ export {
5144
5247
  groupNodesByImpact,
5145
5248
  linkToCode,
5146
5249
  loadGraph,
5250
+ normalizeIntent,
5147
5251
  project,
5148
5252
  queryTraceability,
5149
5253
  saveGraph
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@harness-engineering/graph",
3
- "version": "0.4.2",
3
+ "version": "0.4.3",
4
4
  "license": "MIT",
5
5
  "description": "Knowledge graph for context assembly in Harness Engineering",
6
6
  "main": "./dist/index.js",