@diyor28/context 1.0.0

package/dist/graph/kind-order.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KIND_ORDER = void 0;
+exports.getKindIndex = getKindIndex;
+exports.compareKinds = compareKinds;
+exports.sortBlocksByKind = sortBlocksByKind;
+exports.validateBlockOrder = validateBlockOrder;
+exports.groupBlocksByKind = groupBlocksByKind;
+exports.isValidKind = isValidKind;
+/**
+ * Immutable block kind ordering (pinned → reference → memory → state → tool_output → history → turn).
+ *
+ * NEVER modify this array. It is the contract for deterministic compilation.
+ */
+exports.KIND_ORDER = 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)
+]);
+/**
+ * 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
+ */
+function getKindIndex(kind) {
+    return exports.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
+ */
+function compareKinds(a, b) {
+    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)
+ */
+function sortBlocksByKind(blocks) {
+    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
+ */
+function validateBlockOrder(blocks) {
+    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
+ */
+function groupBlocksByKind(blocks) {
+    const groups = new Map();
+    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
+ */
+function isValidKind(kind) {
+    return getKindIndex(kind) !== -1;
+}
+//# sourceMappingURL=kind-order.js.map

package/dist/graph/kind-order.js.map

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

package/dist/graph/queries.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;
+}
+/**
+ * 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 declare function compareSensitivity(a: SensitivityLevel, b: SensitivityLevel): number;
+/**
+ * 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 declare function matchesQuery(block: ContextBlock<unknown>, query: BlockQuery, graph: ContextGraph): boolean;
+/**
+ * Create an empty query (matches all blocks).
+ *
+ * @returns Empty query
+ */
+export declare function emptyQuery(): BlockQuery;
+/**
+ * Merge multiple queries (AND logic: block must match all queries).
+ *
+ * @param queries - Queries to merge
+ * @returns Merged query
+ */
+export declare function mergeQueries(...queries: BlockQuery[]): BlockQuery;
+//# sourceMappingURL=queries.d.ts.map

package/dist/graph/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/graph/queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IAEpB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,0CAA0C;IAC1C,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAElC,0CAA0C;IAC1C,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAElC,kCAAkC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,uCAAuC;IACvC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IAEzB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAWD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAEnF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,EAC5B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,YAAY,GAClB,OAAO,CA+FT;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,UAAU,CAEvC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,GAAG,UAAU,CA8GjE"}

package/dist/graph/queries.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * BlockQuery: Filtering and selection of context blocks.
+ *
+ * Supports filtering by kind, tags, sensitivity, stability, provenance, and token budget.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareSensitivity = compareSensitivity;
+exports.matchesQuery = matchesQuery;
+exports.emptyQuery = emptyQuery;
+exports.mergeQueries = mergeQueries;
+/**
+ * Sensitivity level ordering (public < internal < restricted).
+ */
+const SENSITIVITY_ORDER = {
+    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
+ */
+function compareSensitivity(a, b) {
+    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
+ */
+function matchesQuery(block, query, graph) {
+    // 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
+ */
+function emptyQuery() {
+    return {};
+}
+/**
+ * Merge multiple queries (AND logic: block must match all queries).
+ *
+ * @param queries - Queries to merge
+ * @returns Merged query
+ */
+function mergeQueries(...queries) {
+    const merged = {};
+    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;
+}
+//# sourceMappingURL=queries.js.map

package/dist/graph/queries.js.map

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

package/dist/graph/views.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ContextView: Immutable, deterministically-ordered snapshot of context blocks.
+ *
+ * Views provide stable ordering (KIND_ORDER + lexicographic) and token estimation.
+ */
+import type { ContextBlock } from '../types/block.js';
+import type { ContextGraph } from './context-graph.js';
+import type { BlockQuery } from './queries.js';
+import type { TokenEstimator } from '../adapters/token-estimator.js';
+/**
+ * View options for creating a ContextView.
+ */
+export interface ViewOptions {
+    /** Query to filter blocks (default: all blocks) */
+    query?: BlockQuery;
+    /** Token estimator for budget enforcement (optional) */
+    tokenEstimator?: TokenEstimator;
+    /** Maximum token budget (requires tokenEstimator) */
+    maxTokens?: number;
+}
+/**
+ * Token estimation result for a view.
+ */
+export interface ViewTokenEstimate {
+    /** Estimated token count */
+    tokens: number;
+    /** Confidence level */
+    confidence: 'exact' | 'high' | 'low';
+    /** Whether token budget was exceeded (blocks were truncated) */
+    truncated: boolean;
+}
+/**
+ * ContextView: Immutable snapshot of blocks with deterministic ordering.
+ *
+ * Ordering rules:
+ * 1. Primary: KIND_ORDER (pinned → reference → memory → state → tool_output → history → turn)
+ * 2. Secondary: Lexicographic by blockHash within same kind
+ */
+export interface ContextView {
+    /** Ordered blocks (immutable) */
+    readonly blocks: ReadonlyArray<ContextBlock<unknown>>;
+    /** Token estimation (if estimator provided) */
+    readonly tokenEstimate?: ViewTokenEstimate;
+    /**
+     * Stable prefix hash (computed from ordered block hashes).
+     * Two views with identical ordered blocks have identical prefix hashes.
+     */
+    readonly stablePrefixHash: string;
+    /** View creation timestamp */
+    readonly createdAt: number;
+}
+/**
+ * Sort blocks deterministically by KIND_ORDER + lexicographic.
+ *
+ * @param blocks - Blocks to sort
+ * @returns Sorted blocks (new array)
+ */
+export declare function sortBlocksDeterministic(blocks: ContextBlock<unknown>[]): ContextBlock<unknown>[];
+/**
+ * Compute stable prefix hash from ordered block hashes.
+ *
+ * @param blocks - Ordered blocks
+ * @returns Hex-encoded SHA-256 hash
+ */
+export declare function computeStablePrefixHash(blocks: ReadonlyArray<ContextBlock<unknown>>): string;
+/**
+ * Create a ContextView from a graph and options.
+ *
+ * @param graph - Context graph
+ * @param options - View options
+ * @returns ContextView
+ */
+export declare function createContextView(graph: ContextGraph, options: ViewOptions): Promise<ContextView>;
+/**
+ * Check if two views have identical content (same blocks in same order).
+ *
+ * @param a - First view
+ * @param b - Second view
+ * @returns True if views have identical content
+ */
+export declare function viewsEqual(a: ContextView, b: ContextView): boolean;
+/**
+ * Merge multiple views into a single view (preserves ordering).
+ * Deduplicates blocks by hash.
+ *
+ * @param views - Views to merge
+ * @returns Merged view
+ */
+export declare function mergeViews(...views: ContextView[]): ContextView;
+//# sourceMappingURL=views.d.ts.map

package/dist/graph/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/graph/views.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB,wDAAwD;IACxD,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IAEf,uBAAuB;IACvB,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IAErC,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAEtD,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,GAC9B,YAAY,CAAC,OAAO,CAAC,EAAE,CAWzB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,GAAG,MAAM,CAU5F;AA6DD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,OAAO,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,CAwB/D"}