@diyor28/context 1.0.0

package/src/graph/context-graph.ts

@@ -0,0 +1,205 @@
+/**
+ * ContextGraph: Core data structure for managing context blocks and relationships.
+ *
+ * Holds blocks, tracks derivation/reference edges, supports querying and view creation.
+ */
+
+import type { ContextBlock, BlockRef } from '../types/block.js';
+import type { BlockQuery } from './queries.js';
+import type { ContextView, ViewOptions } from './views.js';
+import { createContextView } from './views.js';
+import { matchesQuery } from './queries.js';
+
+/**
+ * Edge types for block relationships.
+ */
+export interface ContextGraphEdges {
+  /** Derivation edges: blockHash -> parent BlockRefs (provenance tracking) */
+  derivedFrom: Map<string, BlockRef[]>;
+
+  /** Reference edges: blockHash -> referenced blockHashes (lightweight citations) */
+  references: Map<string, string[]>;
+}
+
+/**
+ * ContextGraph: Mutable graph of context blocks with relationship tracking.
+ *
+ * Responsibilities:
+ * - Store blocks by content-addressed hash
+ * - Track derivation and reference relationships
+ * - Support query-based block selection
+ * - Create deterministic views with stable ordering
+ */
+export class ContextGraph {
+  /** All blocks indexed by blockHash */
+  private readonly blocks: Map<string, ContextBlock<unknown>>;
+
+  /** Block relationship edges */
+  private readonly edges: ContextGraphEdges;
+
+  constructor() {
+    this.blocks = new Map();
+    this.edges = {
+      derivedFrom: new Map(),
+      references: new Map(),
+    };
+  }
+
+  /**
+   * Add a block to the graph.
+   * Idempotent: if block already exists (same hash), this is a no-op.
+   *
+   * @param block - Block to add
+   * @param derivedFrom - Optional parent blocks for provenance
+   * @param references - Optional referenced block hashes
+   */
+  addBlock<TPayload>(
+    block: ContextBlock<TPayload>,
+    derivedFrom?: BlockRef[],
+    references?: string[]
+  ): void {
+    const { blockHash } = block;
+
+    // Idempotent: skip if already exists
+    if (this.blocks.has(blockHash)) {
+      return;
+    }
+
+    // Add block
+    this.blocks.set(blockHash, block as ContextBlock<unknown>);
+
+    // Add derivation edges
+    if (derivedFrom && derivedFrom.length > 0) {
+      this.edges.derivedFrom.set(blockHash, derivedFrom);
+    }
+
+    // Add reference edges
+    if (references && references.length > 0) {
+      this.edges.references.set(blockHash, references);
+    }
+  }
+
+  /**
+   * Remove a block from the graph.
+   * Also removes associated edges.
+   *
+   * @param blockHash - Block hash to remove
+   * @returns True if block was removed, false if not found
+   */
+  removeBlock(blockHash: string): boolean {
+    const existed = this.blocks.delete(blockHash);
+
+    // Clean up edges
+    this.edges.derivedFrom.delete(blockHash);
+    this.edges.references.delete(blockHash);
+
+    return existed;
+  }
+
+  /**
+   * Get a block by hash.
+   *
+   * @param blockHash - Block hash
+   * @returns Block if found, undefined otherwise
+   */
+  getBlock<TPayload = unknown>(blockHash: string): ContextBlock<TPayload> | undefined {
+    return this.blocks.get(blockHash) as ContextBlock<TPayload> | undefined;
+  }
+
+  /**
+   * Check if a block exists in the graph.
+   *
+   * @param blockHash - Block hash
+   * @returns True if block exists
+   */
+  hasBlock(blockHash: string): boolean {
+    return this.blocks.has(blockHash);
+  }
+
+  /**
+   * Get all blocks in the graph (unordered).
+   *
+   * @returns Array of all blocks
+   */
+  getAllBlocks(): ContextBlock<unknown>[] {
+    return Array.from(this.blocks.values());
+  }
+
+  /**
+   * Get the number of blocks in the graph.
+   *
+   * @returns Block count
+   */
+  getBlockCount(): number {
+    return this.blocks.size;
+  }
+
+  /**
+   * Get parent blocks (provenance) for a given block.
+   *
+   * @param blockHash - Block hash
+   * @returns Array of parent BlockRefs, or empty array if none
+   */
+  getDerivedFrom(blockHash: string): BlockRef[] {
+    return this.edges.derivedFrom.get(blockHash) ?? [];
+  }
+
+  /**
+   * Get referenced block hashes for a given block.
+   *
+   * @param blockHash - Block hash
+   * @returns Array of referenced hashes, or empty array if none
+   */
+  getReferences(blockHash: string): string[] {
+    return this.edges.references.get(blockHash) ?? [];
+  }
+
+  /**
+   * Select blocks matching a query.
+   * Returns blocks in arbitrary order (use createView for deterministic ordering).
+   *
+   * @param query - Block query
+   * @returns Matching blocks
+   */
+  select(query: BlockQuery): ContextBlock<unknown>[] {
+    const allBlocks = this.getAllBlocks();
+    return allBlocks.filter((block) => matchesQuery(block, query, this));
+  }
+
+  /**
+   * Create a deterministic view of the graph.
+   * View is immutable snapshot with stable ordering (KIND_ORDER + lexicographic).
+   *
+   * @param options - View options (query, token budget, etc.)
+   * @returns ContextView with ordered blocks
+   */
+  async createView(options: ViewOptions): Promise<ContextView> {
+    return createContextView(this, options);
+  }
+
+  /**
+   * Clear all blocks and edges.
+   */
+  clear(): void {
+    this.blocks.clear();
+    this.edges.derivedFrom.clear();
+    this.edges.references.clear();
+  }
+
+  /**
+   * Get graph statistics.
+   *
+   * @returns Graph stats
+   */
+  getStats(): {
+    blockCount: number;
+    derivationEdgeCount: number;
+    referenceEdgeCount: number;
+  } {
+    return {
+      blockCount: this.blocks.size,
+      derivationEdgeCount: this.edges.derivedFrom.size,
+      referenceEdgeCount: this.edges.references.size,
+    };
+  }
+}

package/src/graph/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Graph utilities for @foundry/context
+ */
+
+export * from './kind-order.js';
+export * from './context-graph.js';
+export * from './queries.js';
+export * from './views.js';

package/src/graph/kind-order.ts

@@ -0,0 +1,125 @@
+/**
+ * KIND_ORDER: Deterministic block ordering for context compilation.
+ *
+ * This is the single source of truth for block ordering.
+ * All context compilation MUST respect this order.
+ */
+
+import type { BlockKind, ContextBlock } from '../types/block.js';
+
+/**
+ * Immutable block kind ordering (pinned → reference → memory → state → tool_output → history → turn).
+ *
+ * NEVER modify this array. It is the contract for deterministic compilation.
+ */
+export const KIND_ORDER: readonly BlockKind[] = Object.freeze([
+  'pinned',       // System rules, always first
+  'reference',    // Tool schemas, external docs
+  'memory',       // Long-term memory, RAG results
+  'state',        // Current workflow/session state
+  'tool_output',  // Tool execution results
+  'history',      // Conversation history
+  'turn',         // Current turn (user message)
+] as const);
+
+/**
+ * Get kind index for ordering comparison.
+ * Returns -1 if kind is not in KIND_ORDER.
+ *
+ * @param kind - Block kind
+ * @returns Index in KIND_ORDER, or -1 if not found
+ */
+export function getKindIndex(kind: BlockKind): number {
+  return KIND_ORDER.indexOf(kind);
+}
+
+/**
+ * Compare two block kinds for ordering.
+ * Returns negative if a < b, positive if a > b, zero if equal.
+ *
+ * @param a - First block kind
+ * @param b - Second block kind
+ * @returns Comparison result
+ */
+export function compareKinds(a: BlockKind, b: BlockKind): number {
+  const indexA = getKindIndex(a);
+  const indexB = getKindIndex(b);
+
+  // Throw if either kind is not in KIND_ORDER
+  if (indexA === -1) {
+    throw new Error(`Invalid block kind: ${a}`);
+  }
+  if (indexB === -1) {
+    throw new Error(`Invalid block kind: ${b}`);
+  }
+
+  return indexA - indexB;
+}
+
+/**
+ * Sort blocks by KIND_ORDER (stable sort, preserves relative order within same kind).
+ *
+ * @param blocks - Blocks to sort
+ * @returns Sorted blocks (new array)
+ */
+export function sortBlocksByKind<TPayload = unknown>(
+  blocks: ContextBlock<TPayload>[]
+): ContextBlock<TPayload>[] {
+  return [...blocks].sort((a, b) => compareKinds(a.meta.kind, b.meta.kind));
+}
+
+/**
+ * Validate that blocks are sorted by KIND_ORDER.
+ * Throws if blocks are not sorted correctly.
+ *
+ * @param blocks - Blocks to validate
+ */
+export function validateBlockOrder<TPayload = unknown>(
+  blocks: ContextBlock<TPayload>[]
+): void {
+  for (let i = 1; i < blocks.length; i++) {
+    const prev = blocks[i - 1];
+    const curr = blocks[i];
+
+    const comparison = compareKinds(prev.meta.kind, curr.meta.kind);
+    if (comparison > 0) {
+      throw new Error(
+        `Blocks not sorted by KIND_ORDER: ${prev.meta.kind} (index ${i - 1}) ` +
+        `comes before ${curr.meta.kind} (index ${i})`
+      );
+    }
+  }
+}
+
+/**
+ * Group blocks by kind (in KIND_ORDER).
+ * Returns a map of kind -> blocks.
+ *
+ * @param blocks - Blocks to group
+ * @returns Map of kind to blocks
+ */
+export function groupBlocksByKind<TPayload = unknown>(
+  blocks: ContextBlock<TPayload>[]
+): Map<BlockKind, ContextBlock<TPayload>[]> {
+  const groups = new Map<BlockKind, ContextBlock<TPayload>[]>();
+
+  for (const block of blocks) {
+    const kind = block.meta.kind;
+    if (!groups.has(kind)) {
+      groups.set(kind, []);
+    }
+    groups.get(kind)!.push(block);
+  }
+
+  return groups;
+}
+
+/**
+ * Check if a kind is valid (exists in KIND_ORDER).
+ *
+ * @param kind - Block kind to check
+ * @returns True if valid
+ */
+export function isValidKind(kind: string): kind is BlockKind {
+  return getKindIndex(kind as BlockKind) !== -1;
+}

package/src/graph/queries.ts

@@ -0,0 +1,306 @@
+/**
+ * BlockQuery: Filtering and selection of context blocks.
+ *
+ * Supports filtering by kind, tags, sensitivity, stability, provenance, and token budget.
+ */
+
+import type { BlockKind, SensitivityLevel, ContextBlock } from '../types/block.js';
+import type { ContextGraph } from './context-graph.js';
+
+/**
+ * Block query for filtering blocks in a ContextGraph.
+ */
+export interface BlockQuery {
+  /** Filter by block kinds (OR logic: match any) */
+  kinds?: BlockKind[];
+
+  /** Filter by tags (AND logic: block must have all tags) */
+  tags?: string[];
+
+  /** Filter by minimum sensitivity level */
+  minSensitivity?: SensitivityLevel;
+
+  /** Filter by maximum sensitivity level */
+  maxSensitivity?: SensitivityLevel;
+
+  /** Filter by source identifier */
+  source?: string;
+
+  /** Filter by minimum creation timestamp (Unix seconds) */
+  minCreatedAt?: number;
+
+  /** Filter by maximum creation timestamp (Unix seconds) */
+  maxCreatedAt?: number;
+
+  /** Filter by provenance: only blocks derived from given hashes */
+  derivedFromAny?: string[];
+
+  /** Filter by provenance: only blocks NOT derived from given hashes */
+  notDerivedFromAny?: string[];
+
+  /** Filter by references: only blocks referencing any of given hashes */
+  referencesAny?: string[];
+
+  /** Exclude blocks with given hashes */
+  excludeHashes?: string[];
+
+  /** Maximum token budget (requires token estimation - applied in views) */
+  maxTokens?: number;
+}
+
+/**
+ * Sensitivity level ordering (public < internal < restricted).
+ */
+const SENSITIVITY_ORDER: Record<SensitivityLevel, number> = {
+  public: 0,
+  internal: 1,
+  restricted: 2,
+};
+
+/**
+ * Compare two sensitivity levels.
+ *
+ * @param a - First sensitivity level
+ * @param b - Second sensitivity level
+ * @returns Negative if a < b, positive if a > b, zero if equal
+ */
+export function compareSensitivity(a: SensitivityLevel, b: SensitivityLevel): number {
+  return SENSITIVITY_ORDER[a] - SENSITIVITY_ORDER[b];
+}
+
+/**
+ * Check if a block matches a query.
+ * Does NOT apply token budget (that's done in view creation).
+ *
+ * @param block - Block to check
+ * @param query - Query to match
+ * @param graph - Context graph (for provenance/reference lookups)
+ * @returns True if block matches query
+ */
+export function matchesQuery(
+  block: ContextBlock<unknown>,
+  query: BlockQuery,
+  graph: ContextGraph
+): boolean {
+  // Filter by kinds (OR logic)
+  if (query.kinds && query.kinds.length > 0) {
+    if (!query.kinds.includes(block.meta.kind)) {
+      return false;
+    }
+  }
+
+  // Filter by tags (AND logic: block must have all query tags)
+  if (query.tags && query.tags.length > 0) {
+    const blockTags = new Set(block.meta.tags ?? []);
+    for (const tag of query.tags) {
+      if (!blockTags.has(tag)) {
+        return false;
+      }
+    }
+  }
+
+  // Filter by minimum sensitivity
+  if (query.minSensitivity !== undefined) {
+    if (compareSensitivity(block.meta.sensitivity, query.minSensitivity) < 0) {
+      return false;
+    }
+  }
+
+  // Filter by maximum sensitivity
+  if (query.maxSensitivity !== undefined) {
+    if (compareSensitivity(block.meta.sensitivity, query.maxSensitivity) > 0) {
+      return false;
+    }
+  }
+
+  // Filter by source
+  if (query.source !== undefined) {
+    if (block.meta.source !== query.source) {
+      return false;
+    }
+  }
+
+  // Filter by minimum creation timestamp
+  if (query.minCreatedAt !== undefined) {
+    if (block.meta.createdAt < query.minCreatedAt) {
+      return false;
+    }
+  }
+
+  // Filter by maximum creation timestamp
+  if (query.maxCreatedAt !== undefined) {
+    if (block.meta.createdAt > query.maxCreatedAt) {
+      return false;
+    }
+  }
+
+  // Filter by provenance: derivedFromAny
+  if (query.derivedFromAny && query.derivedFromAny.length > 0) {
+    const parents = graph.getDerivedFrom(block.blockHash);
+    const parentHashes = new Set(parents.map((p) => p.blockHash));
+
+    const hasMatch = query.derivedFromAny.some((hash) => parentHashes.has(hash));
+    if (!hasMatch) {
+      return false;
+    }
+  }
+
+  // Filter by provenance: notDerivedFromAny
+  if (query.notDerivedFromAny && query.notDerivedFromAny.length > 0) {
+    const parents = graph.getDerivedFrom(block.blockHash);
+    const parentHashes = new Set(parents.map((p) => p.blockHash));
+
+    const hasMatch = query.notDerivedFromAny.some((hash) => parentHashes.has(hash));
+    if (hasMatch) {
+      return false;
+    }
+  }
+
+  // Filter by references: referencesAny
+  if (query.referencesAny && query.referencesAny.length > 0) {
+    const refs = graph.getReferences(block.blockHash);
+    const refSet = new Set(refs);
+
+    const hasMatch = query.referencesAny.some((hash) => refSet.has(hash));
+    if (!hasMatch) {
+      return false;
+    }
+  }
+
+  // Exclude specific hashes
+  if (query.excludeHashes && query.excludeHashes.length > 0) {
+    if (query.excludeHashes.includes(block.blockHash)) {
+      return false;
+    }
+  }
+
+  // All filters passed
+  return true;
+}
+
+/**
+ * Create an empty query (matches all blocks).
+ *
+ * @returns Empty query
+ */
+export function emptyQuery(): BlockQuery {
+  return {};
+}
+
+/**
+ * Merge multiple queries (AND logic: block must match all queries).
+ *
+ * @param queries - Queries to merge
+ * @returns Merged query
+ */
+export function mergeQueries(...queries: BlockQuery[]): BlockQuery {
+  const merged: BlockQuery = {};
+
+  for (const query of queries) {
+    // Merge kinds (intersection)
+    if (query.kinds) {
+      if (merged.kinds) {
+        const kindSet = new Set(merged.kinds);
+        merged.kinds = query.kinds.filter((k) => kindSet.has(k));
+      } else {
+        merged.kinds = [...query.kinds];
+      }
+    }
+
+    // Merge tags (union - block must have all)
+    if (query.tags) {
+      merged.tags = [...(merged.tags ?? []), ...query.tags];
+    }
+
+    // Merge sensitivity (most restrictive)
+    if (query.minSensitivity !== undefined) {
+      if (merged.minSensitivity === undefined) {
+        merged.minSensitivity = query.minSensitivity;
+      } else {
+        // Take the higher minimum
+        if (compareSensitivity(query.minSensitivity, merged.minSensitivity) > 0) {
+          merged.minSensitivity = query.minSensitivity;
+        }
+      }
+    }
+
+    if (query.maxSensitivity !== undefined) {
+      if (merged.maxSensitivity === undefined) {
+        merged.maxSensitivity = query.maxSensitivity;
+      } else {
+        // Take the lower maximum
+        if (compareSensitivity(query.maxSensitivity, merged.maxSensitivity) < 0) {
+          merged.maxSensitivity = query.maxSensitivity;
+        }
+      }
+    }
+
+    // Merge source (must match - conflicting sources = no results)
+    if (query.source !== undefined) {
+      if (merged.source !== undefined && merged.source !== query.source) {
+        // Conflict: return impossible query
+        merged.kinds = [];
+      } else {
+        merged.source = query.source;
+      }
+    }
+
+    // Merge timestamps (most restrictive)
+    if (query.minCreatedAt !== undefined) {
+      if (merged.minCreatedAt === undefined) {
+        merged.minCreatedAt = query.minCreatedAt;
+      } else {
+        merged.minCreatedAt = Math.max(merged.minCreatedAt, query.minCreatedAt);
+      }
+    }
+
+    if (query.maxCreatedAt !== undefined) {
+      if (merged.maxCreatedAt === undefined) {
+        merged.maxCreatedAt = query.maxCreatedAt;
+      } else {
+        merged.maxCreatedAt = Math.min(merged.maxCreatedAt, query.maxCreatedAt);
+      }
+    }
+
+    // Merge provenance (union)
+    if (query.derivedFromAny) {
+      merged.derivedFromAny = [
+        ...(merged.derivedFromAny ?? []),
+        ...query.derivedFromAny,
+      ];
+    }
+
+    if (query.notDerivedFromAny) {
+      merged.notDerivedFromAny = [
+        ...(merged.notDerivedFromAny ?? []),
+        ...query.notDerivedFromAny,
+      ];
+    }
+
+    if (query.referencesAny) {
+      merged.referencesAny = [
+        ...(merged.referencesAny ?? []),
+        ...query.referencesAny,
+      ];
+    }
+
+    // Merge excludeHashes (union)
+    if (query.excludeHashes) {
+      merged.excludeHashes = [
+        ...(merged.excludeHashes ?? []),
+        ...query.excludeHashes,
+      ];
+    }
+
+    // Merge maxTokens (minimum)
+    if (query.maxTokens !== undefined) {
+      if (merged.maxTokens === undefined) {
+        merged.maxTokens = query.maxTokens;
+      } else {
+        merged.maxTokens = Math.min(merged.maxTokens, query.maxTokens);
+      }
+    }
+  }
+
+  return merged;
+}