@diyor28/context 1.0.0

package/dist/codecs/tool-schema.codec.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Tool schema codec (kind: 'reference').
+ *
+ * Tool definitions for function calling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolSchemaCodec = exports.ToolSchemaPayloadSchema = void 0;
+const zod_1 = require("zod");
+const base_js_1 = require("./base.js");
+/**
+ * Tool schema payload schema (JSON Schema-like).
+ */
+exports.ToolSchemaPayloadSchema = zod_1.z.object({
+    /** Tool name */
+    name: zod_1.z.string(),
+    /** Tool description */
+    description: zod_1.z.string(),
+    /** Input schema (JSON Schema) */
+    inputSchema: zod_1.z.record(zod_1.z.unknown()),
+    /** Optional cache control hint */
+    cacheable: zod_1.z.boolean().optional(),
+});
+/**
+ * Tool schema codec implementation.
+ */
+exports.ToolSchemaCodec = {
+    codecId: 'tool-schema',
+    version: '1.0.0',
+    payloadSchema: exports.ToolSchemaPayloadSchema,
+    canonicalize(payload) {
+        // Sort keys for deterministic hashing
+        return (0, base_js_1.sortObjectKeys)({
+            name: payload.name,
+            description: payload.description.trim(),
+            inputSchema: (0, base_js_1.sortObjectKeys)(payload.inputSchema),
+            cacheable: payload.cacheable ?? false,
+        });
+    },
+    hash(canonicalized) {
+        return (0, base_js_1.defaultHash)(canonicalized);
+    },
+    render(block) {
+        const { name, description, inputSchema, cacheable } = block.payload;
+        return {
+            // Anthropic: tool definition
+            anthropic: {
+                name,
+                description,
+                input_schema: inputSchema,
+                ...(cacheable && { cache_control: { type: 'ephemeral' } }),
+            },
+            // OpenAI: function definition
+            openai: {
+                type: 'function',
+                function: {
+                    name,
+                    description,
+                    parameters: inputSchema,
+                },
+            },
+            // Gemini: function declaration
+            gemini: {
+                name,
+                description,
+                parameters: inputSchema,
+            },
+        };
+    },
+    validate(payload) {
+        return exports.ToolSchemaPayloadSchema.parse(payload);
+    },
+};
+//# sourceMappingURL=tool-schema.codec.js.map

package/dist/codecs/tool-schema.codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.codec.js","sourceRoot":"","sources":["../../src/codecs/tool-schema.codec.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,6BAAwB;AAGxB,uCAAwD;AAExD;;GAEG;AACU,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C,gBAAgB;IAChB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAEhB,uBAAuB;IACvB,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE;IAEvB,iCAAiC;IACjC,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,OAAO,EAAE,CAAC;IAElC,kCAAkC;IAClC,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAIH;;GAEG;AACU,QAAA,eAAe,GAAkC;IAC5D,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,OAAO;IAChB,aAAa,EAAE,+BAAuB;IAEtC,YAAY,CAAC,OAA0B;QACrC,sCAAsC;QACtC,OAAO,IAAA,wBAAc,EAAC;YACpB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE;YACvC,WAAW,EAAE,IAAA,wBAAc,EAAC,OAAO,CAAC,WAAsC,CAAC;YAC3E,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK;SACtC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,aAAsB;QACzB,OAAO,IAAA,qBAAW,EAAC,aAAa,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC;QAEpE,OAAO;YACL,6BAA6B;YAC7B,SAAS,EAAE;gBACT,IAAI;gBACJ,WAAW;gBACX,YAAY,EAAE,WAAW;gBACzB,GAAG,CAAC,SAAS,IAAI,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,CAAC;aAC3D;YAED,8BAA8B;YAC9B,MAAM,EAAE;gBACN,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI;oBACJ,WAAW;oBACX,UAAU,EAAE,WAAW;iBACxB;aACF;YAED,+BAA+B;YAC/B,MAAM,EAAE;gBACN,IAAI;gBACJ,WAAW;gBACX,UAAU,EAAE,WAAW;aACxB;SACF,CAAC;IACJ,CAAC;IAED,QAAQ,CAAC,OAAgB;QACvB,OAAO,+BAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAC"}

package/dist/codecs/unsafe-text.codec.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Unsafe text codec (any kind).
+ *
+ * Raw text passthrough without validation. Use with caution.
+ */
+import { z } from 'zod';
+import type { BlockCodec } from '../types/codec.js';
+/**
+ * Unsafe text payload schema.
+ */
+export declare const UnsafeTextPayloadSchema: z.ZodObject<{
+    /** Raw text content */
+    text: z.ZodString;
+    /** Optional role override (user, assistant, system) */
+    role: z.ZodOptional<z.ZodEnum<["user", "assistant", "system"]>>;
+}, "strip", z.ZodTypeAny, {
+    text: string;
+    role?: "user" | "assistant" | "system" | undefined;
+}, {
+    text: string;
+    role?: "user" | "assistant" | "system" | undefined;
+}>;
+export type UnsafeTextPayload = z.infer<typeof UnsafeTextPayloadSchema>;
+/**
+ * Unsafe text codec implementation.
+ */
+export declare const UnsafeTextCodec: BlockCodec<UnsafeTextPayload>;
+//# sourceMappingURL=unsafe-text.codec.d.ts.map

package/dist/codecs/unsafe-text.codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsafe-text.codec.d.ts","sourceRoot":"","sources":["../../src/codecs/unsafe-text.codec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAmB,MAAM,mBAAmB,CAAC;AAIrE;;GAEG;AACH,eAAO,MAAM,uBAAuB;IAClC,uBAAuB;;IAGvB,uDAAuD;;;;;;;;EAEvD,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,CAAC,iBAAiB,CA8CzD,CAAC"}

package/dist/codecs/unsafe-text.codec.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Unsafe text codec (any kind).
+ *
+ * Raw text passthrough without validation. Use with caution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsafeTextCodec = exports.UnsafeTextPayloadSchema = void 0;
+const zod_1 = require("zod");
+const base_js_1 = require("./base.js");
+/**
+ * Unsafe text payload schema.
+ */
+exports.UnsafeTextPayloadSchema = zod_1.z.object({
+    /** Raw text content */
+    text: zod_1.z.string(),
+    /** Optional role override (user, assistant, system) */
+    role: zod_1.z.enum(['user', 'assistant', 'system']).optional(),
+});
+/**
+ * Unsafe text codec implementation.
+ */
+exports.UnsafeTextCodec = {
+    codecId: 'unsafe-text',
+    version: '1.0.0',
+    payloadSchema: exports.UnsafeTextPayloadSchema,
+    canonicalize(payload) {
+        // Canonicalize: trim whitespace and normalize role
+        return {
+            text: payload.text.trim(),
+            role: payload.role ?? 'user',
+        };
+    },
+    hash(canonicalized) {
+        return (0, base_js_1.defaultHash)(canonicalized);
+    },
+    render(block) {
+        const { text, role = 'user' } = block.payload;
+        return {
+            // Anthropic: message with specified role
+            anthropic: {
+                role: role === 'system' ? 'user' : role,
+                content: role === 'system'
+                    ? [{ type: 'text', text }]
+                    : text,
+            },
+            // OpenAI: message with specified role
+            openai: {
+                role: role === 'system' ? 'system' : role,
+                content: text,
+            },
+            // Gemini: convert role to user/model
+            gemini: {
+                role: role === 'assistant' ? 'model' : 'user',
+                parts: [{ text }],
+            },
+        };
+    },
+    validate(payload) {
+        return exports.UnsafeTextPayloadSchema.parse(payload);
+    },
+};
+//# sourceMappingURL=unsafe-text.codec.js.map

package/dist/codecs/unsafe-text.codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unsafe-text.codec.js","sourceRoot":"","sources":["../../src/codecs/unsafe-text.codec.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,6BAAwB;AAGxB,uCAAwC;AAExC;;GAEG;AACU,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C,uBAAuB;IACvB,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAEhB,uDAAuD;IACvD,IAAI,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE;CACzD,CAAC,CAAC;AAIH;;GAEG;AACU,QAAA,eAAe,GAAkC;IAC5D,OAAO,EAAE,aAAa;IACtB,OAAO,EAAE,OAAO;IAChB,aAAa,EAAE,+BAAuB;IAEtC,YAAY,CAAC,OAA0B;QACrC,mDAAmD;QACnD,OAAO;YACL,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE;YACzB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,MAAM;SAC7B,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,aAAsB;QACzB,OAAO,IAAA,qBAAW,EAAC,aAAa,CAAC,CAAC;IACpC,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC;QAE9C,OAAO;YACL,yCAAyC;YACzC,SAAS,EAAE;gBACT,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI;gBACvC,OAAO,EAAE,IAAI,KAAK,QAAQ;oBACxB,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;oBAC1B,CAAC,CAAC,IAAI;aACT;YAED,sCAAsC;YACtC,MAAM,EAAE;gBACN,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;gBACzC,OAAO,EAAE,IAAI;aACd;YAED,qCAAqC;YACrC,MAAM,EAAE;gBACN,IAAI,EAAE,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;gBAC7C,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;aAClB;SACF,CAAC;IACJ,CAAC;IAED,QAAQ,CAAC,OAAgB;QACvB,OAAO,+BAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;CACF,CAAC"}

package/dist/graph/context-graph.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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';
+/**
+ * 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 declare class ContextGraph {
+    /** All blocks indexed by blockHash */
+    private readonly blocks;
+    /** Block relationship edges */
+    private readonly edges;
+    constructor();
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Get a block by hash.
+     *
+     * @param blockHash - Block hash
+     * @returns Block if found, undefined otherwise
+     */
+    getBlock<TPayload = unknown>(blockHash: string): ContextBlock<TPayload> | undefined;
+    /**
+     * Check if a block exists in the graph.
+     *
+     * @param blockHash - Block hash
+     * @returns True if block exists
+     */
+    hasBlock(blockHash: string): boolean;
+    /**
+     * Get all blocks in the graph (unordered).
+     *
+     * @returns Array of all blocks
+     */
+    getAllBlocks(): ContextBlock<unknown>[];
+    /**
+     * Get the number of blocks in the graph.
+     *
+     * @returns Block count
+     */
+    getBlockCount(): number;
+    /**
+     * 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[];
+    /**
+     * 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[];
+    /**
+     * 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>[];
+    /**
+     * 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
+     */
+    createView(options: ViewOptions): Promise<ContextView>;
+    /**
+     * Clear all blocks and edges.
+     */
+    clear(): void;
+    /**
+     * Get graph statistics.
+     *
+     * @returns Graph stats
+     */
+    getStats(): {
+        blockCount: number;
+        derivationEdgeCount: number;
+        referenceEdgeCount: number;
+    };
+}
+//# sourceMappingURL=context-graph.d.ts.map

package/dist/graph/context-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-graph.d.ts","sourceRoot":"","sources":["../../src/graph/context-graph.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI3D;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAErC,mFAAmF;IACnF,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAE5D,+BAA+B;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;;IAU1C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EACf,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,EAC7B,WAAW,CAAC,EAAE,QAAQ,EAAE,EACxB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,IAAI;IAsBP;;;;;;OAMG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAUvC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,SAAS;IAInF;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAIpC;;;;OAIG;IACH,YAAY,IAAI,YAAY,CAAC,OAAO,CAAC,EAAE;IAIvC;;;;OAIG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,EAAE;IAI7C;;;;;OAKG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IAI1C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE;IAKlD;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAI5D;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,kBAAkB,EAAE,MAAM,CAAC;KAC5B;CAOF"}

package/dist/graph/context-graph.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * ContextGraph: Core data structure for managing context blocks and relationships.
+ *
+ * Holds blocks, tracks derivation/reference edges, supports querying and view creation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextGraph = void 0;
+const views_js_1 = require("./views.js");
+const queries_js_1 = require("./queries.js");
+/**
+ * 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
+ */
+class ContextGraph {
+    /** All blocks indexed by blockHash */
+    blocks;
+    /** Block relationship edges */
+    edges;
+    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(block, derivedFrom, references) {
+        const { blockHash } = block;
+        // Idempotent: skip if already exists
+        if (this.blocks.has(blockHash)) {
+            return;
+        }
+        // Add block
+        this.blocks.set(blockHash, block);
+        // 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) {
+        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(blockHash) {
+        return this.blocks.get(blockHash);
+    }
+    /**
+     * Check if a block exists in the graph.
+     *
+     * @param blockHash - Block hash
+     * @returns True if block exists
+     */
+    hasBlock(blockHash) {
+        return this.blocks.has(blockHash);
+    }
+    /**
+     * Get all blocks in the graph (unordered).
+     *
+     * @returns Array of all blocks
+     */
+    getAllBlocks() {
+        return Array.from(this.blocks.values());
+    }
+    /**
+     * Get the number of blocks in the graph.
+     *
+     * @returns Block count
+     */
+    getBlockCount() {
+        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) {
+        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) {
+        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) {
+        const allBlocks = this.getAllBlocks();
+        return allBlocks.filter((block) => (0, queries_js_1.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) {
+        return (0, views_js_1.createContextView)(this, options);
+    }
+    /**
+     * Clear all blocks and edges.
+     */
+    clear() {
+        this.blocks.clear();
+        this.edges.derivedFrom.clear();
+        this.edges.references.clear();
+    }
+    /**
+     * Get graph statistics.
+     *
+     * @returns Graph stats
+     */
+    getStats() {
+        return {
+            blockCount: this.blocks.size,
+            derivationEdgeCount: this.edges.derivedFrom.size,
+            referenceEdgeCount: this.edges.references.size,
+        };
+    }
+}
+exports.ContextGraph = ContextGraph;
+//# sourceMappingURL=context-graph.js.map

package/dist/graph/context-graph.js.map

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

package/dist/graph/index.d.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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

package/dist/graph/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Graph utilities for @foundry/context
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./kind-order.js"), exports);
+__exportStar(require("./context-graph.js"), exports);
+__exportStar(require("./queries.js"), exports);
+__exportStar(require("./views.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/graph/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,kDAAgC;AAChC,qDAAmC;AACnC,+CAA6B;AAC7B,6CAA2B"}

package/dist/graph/kind-order.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare const KIND_ORDER: readonly BlockKind[];
+/**
+ * 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 declare function getKindIndex(kind: BlockKind): number;
+/**
+ * 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 declare function compareKinds(a: BlockKind, b: BlockKind): number;
+/**
+ * Sort blocks by KIND_ORDER (stable sort, preserves relative order within same kind).
+ *
+ * @param blocks - Blocks to sort
+ * @returns Sorted blocks (new array)
+ */
+export declare function sortBlocksByKind<TPayload = unknown>(blocks: ContextBlock<TPayload>[]): ContextBlock<TPayload>[];
+/**
+ * Validate that blocks are sorted by KIND_ORDER.
+ * Throws if blocks are not sorted correctly.
+ *
+ * @param blocks - Blocks to validate
+ */
+export declare function validateBlockOrder<TPayload = unknown>(blocks: ContextBlock<TPayload>[]): void;
+/**
+ * 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 declare function groupBlocksByKind<TPayload = unknown>(blocks: ContextBlock<TPayload>[]): Map<BlockKind, ContextBlock<TPayload>[]>;
+/**
+ * Check if a kind is valid (exists in KIND_ORDER).
+ *
+ * @param kind - Block kind to check
+ * @returns True if valid
+ */
+export declare function isValidKind(kind: string): kind is BlockKind;
+//# sourceMappingURL=kind-order.d.ts.map

package/dist/graph/kind-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind-order.d.ts","sourceRoot":"","sources":["../../src/graph/kind-order.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,SAAS,EAQhC,CAAC;AAEZ;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAa/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAG,OAAO,EACjD,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,GAC/B,YAAY,CAAC,QAAQ,CAAC,EAAE,CAE1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EACnD,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,GAC/B,IAAI,CAaN;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAClD,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,GAC/B,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,CAY1C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,CAE3D"}