@blackwell-systems/gcf 2.1.0 → 2.1.1

package/dist/cjs/session.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+exports.encodeWithSession = encodeWithSession;
+const constants_js_1 = require("./constants.js");
+const encode_js_1 = require("./encode.js");
+/**
+ * Session tracks symbols that have been transmitted to a client, enabling
+ * subsequent responses to reference them by ID without full retransmission.
+ * This makes multi-call workflows progressively cheaper.
+ */
+class Session {
+    symbols = new Map();
+    nextID = 0;
+    /** Returns true if the symbol has been sent in a previous response. */
+    transmitted(qname) {
+        return this.symbols.has(qname);
+    }
+    /** Returns the session-global ID for a previously transmitted symbol, or -1 if not found. */
+    getID(qname) {
+        const id = this.symbols.get(qname);
+        return id !== undefined ? id : -1;
+    }
+    /**
+     * Record marks symbols as transmitted and assigns session-global IDs.
+     * Call this after a successful encode to register newly-sent symbols.
+     */
+    record(symbols) {
+        for (const sym of symbols) {
+            if (!this.symbols.has(sym.qualifiedName)) {
+                this.symbols.set(sym.qualifiedName, this.nextID);
+                this.nextID++;
+            }
+        }
+    }
+    /** Returns the number of symbols tracked in this session. */
+    size() {
+        return this.symbols.size;
+    }
+    /** Clears the session state. */
+    reset() {
+        this.symbols.clear();
+        this.nextID = 0;
+    }
+}
+exports.Session = Session;
+function groupByDistance(symbols) {
+    if (symbols.length === 0)
+        return [];
+    const groups = [];
+    let current = null;
+    for (const s of symbols) {
+        if (current === null || current.distance !== s.distance) {
+            current = { distance: s.distance, symbols: [] };
+            groups.push(current);
+        }
+        current.symbols.push(s);
+    }
+    return groups;
+}
+/**
+ * Encode a payload using GCF with session deduplication.
+ * Symbols that were already transmitted in prior responses are emitted as
+ * bare references (`@N  # previously transmitted`) instead of full declarations.
+ * After encoding, newly-sent symbols are recorded in the session.
+ */
+function encodeWithSession(p, sess) {
+    if (!sess) {
+        return (0, encode_js_1.encode)(p);
+    }
+    const lines = [];
+    // Header with session=true marker.
+    let header = `GCF profile=graph tool=${p.tool}`;
+    if (p.tokenBudget)
+        header += ` budget=${p.tokenBudget}`;
+    if (p.tokensUsed)
+        header += ` tokens=${p.tokensUsed}`;
+    header += ` symbols=${p.symbols.length}`;
+    if (p.edges.length > 0)
+        header += ` edges=${p.edges.length}`;
+    header += ' session=true';
+    if (p.packRoot) {
+        header += ` pack_root=${p.packRoot}`;
+    }
+    lines.push(header);
+    // Build local ID mapping for this response.
+    const localIndex = new Map();
+    for (let i = 0; i < p.symbols.length; i++) {
+        localIndex.set(p.symbols[i].qualifiedName, i);
+    }
+    // Track which symbols are new for recording after encode.
+    const newSymbols = [];
+    // Group by distance.
+    const groups = groupByDistance(p.symbols);
+    const groupNames = ['targets', 'related', 'extended'];
+    for (const g of groups) {
+        if (g.symbols.length === 0)
+            continue;
+        let name;
+        if (g.distance < groupNames.length) {
+            name = groupNames[g.distance];
+        }
+        else {
+            name = `distance_${g.distance}`;
+        }
+        lines.push(`## ${name}`);
+        for (const s of g.symbols) {
+            const idx = localIndex.get(s.qualifiedName);
+            if (sess.transmitted(s.qualifiedName)) {
+                // Bare reference: symbol was sent in a prior response.
+                lines.push(`@${idx}  # previously transmitted`);
+            }
+            else {
+                // Full declaration.
+                const kind = constants_js_1.KIND_ABBREV[s.kind] || s.kind;
+                lines.push(`@${idx} ${kind} ${s.qualifiedName} ${s.score.toFixed(2)} ${s.provenance}`);
+                newSymbols.push(s);
+            }
+        }
+    }
+    // Edges section.
+    if (p.edges.length > 0) {
+        lines.push(`## edges [${p.edges.length}]`);
+        for (const e of p.edges) {
+            const srcIdx = localIndex.get(e.source);
+            const tgtIdx = localIndex.get(e.target);
+            if (srcIdx === undefined || tgtIdx === undefined)
+                continue;
+            let line = `@${tgtIdx}<@${srcIdx} ${e.edgeType}`;
+            if (e.status && e.status !== 'unchanged') {
+                line += ` ${e.status}`;
+            }
+            lines.push(line);
+        }
+    }
+    // Record all new symbols in the session.
+    sess.record(newSymbols);
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=session.js.map

package/dist/cjs/session.js.map

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

package/dist/cjs/stream.d.ts

@@ -0,0 +1,66 @@
+import type { Symbol, Edge } from './types.js';
+/**
+ * Options for the streaming encoder.
+ */
+export interface StreamOptions {
+    tokenBudget?: number;
+    tokensUsed?: number;
+    packRoot?: string;
+    session?: boolean;
+}
+/**
+ * A writable sink for streaming output. Accepts string chunks.
+ * Compatible with Node.js streams, web WritableStreams, or simple callbacks.
+ */
+export interface StreamWriter {
+    write(chunk: string): void;
+}
+/**
+ * StreamEncoder writes GCF output incrementally as symbols and edges arrive.
+ * Zero buffering: each symbol/edge is written immediately. A trailer summary
+ * is emitted on close() with the final counts.
+ *
+ * @example
+ * ```ts
+ * const chunks: string[] = [];
+ * const enc = new StreamEncoder({ write: (s) => chunks.push(s) }, 'context_for_task', { tokenBudget: 5000 });
+ * enc.writeSymbol({ qualifiedName: 'pkg.Auth', kind: 'function', score: 0.95, provenance: 'lsp', distance: 0 });
+ * enc.writeEdge({ source: 'pkg.Server', target: 'pkg.Auth', edgeType: 'calls' });
+ * enc.close();
+ * ```
+ */
+export declare class StreamEncoder {
+    private w;
+    private symIndex;
+    private nextID;
+    private currentGroup;
+    private groupCounts;
+    private edgeCount;
+    private edgesStarted;
+    constructor(w: StreamWriter, tool: string, opts?: StreamOptions);
+    private writeHeader;
+    /**
+     * Emit a symbol line immediately. Group headers are emitted automatically
+     * when the distance changes.
+     */
+    writeSymbol(s: Symbol): void;
+    /**
+     * Emit an edge line immediately. The edges section header is emitted
+     * automatically on the first edge (with [?] deferred count).
+     * Source and target must reference previously-written symbols.
+     */
+    writeEdge(e: Edge): void;
+    /**
+     * Emit a bare reference for a previously-transmitted symbol (session mode).
+     */
+    writeBareRef(qname: string, distance: number): void;
+    /**
+     * Emit the ##! summary trailer with final counts. Must be called after all
+     * symbols and edges have been written.
+     */
+    close(): void;
+    /** Number of symbols written so far. */
+    get symbolCount(): number;
+    /** Number of edges written so far. */
+    get edgeCount_(): number;
+}

package/dist/cjs/stream.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamEncoder = void 0;
+const constants_js_1 = require("./constants.js");
+/**
+ * StreamEncoder writes GCF output incrementally as symbols and edges arrive.
+ * Zero buffering: each symbol/edge is written immediately. A trailer summary
+ * is emitted on close() with the final counts.
+ *
+ * @example
+ * ```ts
+ * const chunks: string[] = [];
+ * const enc = new StreamEncoder({ write: (s) => chunks.push(s) }, 'context_for_task', { tokenBudget: 5000 });
+ * enc.writeSymbol({ qualifiedName: 'pkg.Auth', kind: 'function', score: 0.95, provenance: 'lsp', distance: 0 });
+ * enc.writeEdge({ source: 'pkg.Server', target: 'pkg.Auth', edgeType: 'calls' });
+ * enc.close();
+ * ```
+ */
+class StreamEncoder {
+    w;
+    symIndex = new Map();
+    nextID = 0;
+    currentGroup = '';
+    groupCounts = new Map();
+    edgeCount = 0;
+    edgesStarted = false;
+    constructor(w, tool, opts = {}) {
+        this.w = w;
+        this.writeHeader(tool, opts);
+    }
+    writeHeader(tool, opts) {
+        const parts = [`GCF profile=graph tool=${tool}`];
+        if (opts.tokenBudget)
+            parts.push(`budget=${opts.tokenBudget}`);
+        if (opts.tokensUsed)
+            parts.push(`tokens=${opts.tokensUsed}`);
+        if (opts.packRoot)
+            parts.push(`pack_root=${opts.packRoot}`);
+        if (opts.session)
+            parts.push('session=true');
+        this.w.write(parts.join(' ') + '\n');
+    }
+    /**
+     * Emit a symbol line immediately. Group headers are emitted automatically
+     * when the distance changes.
+     */
+    writeSymbol(s) {
+        const groupNames = ['targets', 'related', 'extended'];
+        const groupName = s.distance < groupNames.length
+            ? groupNames[s.distance]
+            : `distance_${s.distance}`;
+        if (groupName !== this.currentGroup) {
+            this.w.write(`## ${groupName}\n`);
+            this.currentGroup = groupName;
+        }
+        const id = this.nextID++;
+        this.symIndex.set(s.qualifiedName, id);
+        const kind = constants_js_1.KIND_ABBREV[s.kind] || s.kind;
+        this.w.write(`@${id} ${kind} ${s.qualifiedName} ${s.score.toFixed(2)} ${s.provenance}\n`);
+        this.groupCounts.set(groupName, (this.groupCounts.get(groupName) || 0) + 1);
+    }
+    /**
+     * Emit an edge line immediately. The edges section header is emitted
+     * automatically on the first edge (with [?] deferred count).
+     * Source and target must reference previously-written symbols.
+     */
+    writeEdge(e) {
+        const srcIdx = this.symIndex.get(e.source);
+        const tgtIdx = this.symIndex.get(e.target);
+        if (srcIdx === undefined || tgtIdx === undefined)
+            return;
+        if (!this.edgesStarted) {
+            this.w.write('## edges [?]\n');
+            this.edgesStarted = true;
+        }
+        let line = `@${tgtIdx}<@${srcIdx} ${e.edgeType}`;
+        if (e.status && e.status !== 'unchanged') {
+            line += ` ${e.status}`;
+        }
+        this.w.write(line + '\n');
+        this.edgeCount++;
+    }
+    /**
+     * Emit a bare reference for a previously-transmitted symbol (session mode).
+     */
+    writeBareRef(qname, distance) {
+        const groupNames = ['targets', 'related', 'extended'];
+        const groupName = distance < groupNames.length
+            ? groupNames[distance]
+            : `distance_${distance}`;
+        if (groupName !== this.currentGroup) {
+            this.w.write(`## ${groupName}\n`);
+            this.currentGroup = groupName;
+        }
+        const id = this.nextID++;
+        this.symIndex.set(qname, id);
+        this.w.write(`@${id}  # previously transmitted\n`);
+        this.groupCounts.set(groupName, (this.groupCounts.get(groupName) || 0) + 1);
+    }
+    /**
+     * Emit the ##! summary trailer with final counts. Must be called after all
+     * symbols and edges have been written.
+     */
+    close() {
+        const deferredCounts = [];
+        const groupOrder = ['targets', 'related', 'extended'];
+        for (const g of groupOrder) {
+            const c = this.groupCounts.get(g);
+            if (c && c > 0)
+                deferredCounts.push(c);
+        }
+        for (const [g, c] of this.groupCounts) {
+            if (!groupOrder.includes(g) && c > 0)
+                deferredCounts.push(c);
+        }
+        if (this.edgeCount > 0) {
+            deferredCounts.push(this.edgeCount);
+        }
+        this.w.write(`##! summary symbols=${this.nextID} edges=${this.edgeCount} counts=${deferredCounts.join(',')}\n`);
+    }
+    /** Number of symbols written so far. */
+    get symbolCount() { return this.nextID; }
+    /** Number of edges written so far. */
+    get edgeCount_() { return this.edgeCount; }
+}
+exports.StreamEncoder = StreamEncoder;
+//# sourceMappingURL=stream.js.map

package/dist/cjs/stream.js.map

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

package/dist/cjs/stream_generic.d.ts

@@ -0,0 +1,37 @@
+import type { StreamWriter } from './stream.js';
+/**
+ * GenericStreamEncoder writes GCF tabular output incrementally as rows arrive.
+ * Zero buffering: each row is written immediately. A trailer summary is
+ * emitted on close() with the final counts.
+ *
+ * @example
+ * ```ts
+ * const enc = new GenericStreamEncoder({ write: (s) => process.stdout.write(s) });
+ * enc.beginArray('employees', ['id', 'name', 'department', 'salary']);
+ * enc.writeRow([1, 'Alice', 'Engineering', 95000]);
+ * enc.writeRow([2, 'Bob', 'Sales', 72000]);
+ * enc.endArray();
+ * enc.close();
+ * ```
+ */
+export declare class GenericStreamEncoder {
+    private readonly writer;
+    private sections;
+    private current;
+    constructor(writer: StreamWriter);
+    /** Start a tabular array section with deferred count [?]. */
+    beginArray(name: string, fields: string[]): void;
+    /** Emit a single pipe-separated row immediately. */
+    writeRow(values: unknown[]): void;
+    /** Close the current array section and record its count. */
+    endArray(): void;
+    /** Emit a key=value line immediately. */
+    writeKV(key: string, value: unknown): void;
+    /** Start a nested object section (## key). */
+    writeSection(name: string): void;
+    /** Emit a primitive array inline: name[N]: val1,val2,val3 */
+    writeInlineArray(name: string, values: unknown[]): void;
+    /** Emit the ##! summary trailer with final counts. Must be called after all data. */
+    close(): void;
+    private endArrayInternal;
+}

package/dist/cjs/stream_generic.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericStreamEncoder = void 0;
+const scalar_js_1 = require("./scalar.js");
+/**
+ * GenericStreamEncoder writes GCF tabular output incrementally as rows arrive.
+ * Zero buffering: each row is written immediately. A trailer summary is
+ * emitted on close() with the final counts.
+ *
+ * @example
+ * ```ts
+ * const enc = new GenericStreamEncoder({ write: (s) => process.stdout.write(s) });
+ * enc.beginArray('employees', ['id', 'name', 'department', 'salary']);
+ * enc.writeRow([1, 'Alice', 'Engineering', 95000]);
+ * enc.writeRow([2, 'Bob', 'Sales', 72000]);
+ * enc.endArray();
+ * enc.close();
+ * ```
+ */
+class GenericStreamEncoder {
+    writer;
+    sections = [];
+    current = null;
+    constructor(writer) {
+        this.writer = writer;
+    }
+    /** Start a tabular array section with deferred count [?]. */
+    beginArray(name, fields) {
+        if (this.current !== null) {
+            this.endArrayInternal();
+        }
+        this.writer.write(`## ${name} [?]{${fields.join(',')}}\n`);
+        this.current = { name, fields, count: 0 };
+    }
+    /** Emit a single pipe-separated row immediately. */
+    writeRow(values) {
+        if (this.current === null) {
+            return;
+        }
+        const parts = values.map(formatValue);
+        this.writer.write(`${parts.join('|')}\n`);
+        this.current.count++;
+    }
+    /** Close the current array section and record its count. */
+    endArray() {
+        this.endArrayInternal();
+    }
+    /** Emit a key=value line immediately. */
+    writeKV(key, value) {
+        this.writer.write(`${key}=${formatValue(value)}\n`);
+    }
+    /** Start a nested object section (## key). */
+    writeSection(name) {
+        if (this.current !== null) {
+            this.endArrayInternal();
+        }
+        this.writer.write(`## ${name}\n`);
+    }
+    /** Emit a primitive array inline: name[N]: val1,val2,val3 */
+    writeInlineArray(name, values) {
+        const parts = values.map(formatValue);
+        this.writer.write(`${name}[${values.length}]: ${parts.join(',')}\n`);
+    }
+    /** Emit the ##! summary trailer with final counts. Must be called after all data. */
+    close() {
+        if (this.current !== null) {
+            this.endArrayInternal();
+        }
+        if (this.sections.length === 0) {
+            return;
+        }
+        const counts = this.sections.map(s => String(s.count));
+        this.writer.write(`##! summary counts=${counts.join(',')}\n`);
+    }
+    endArrayInternal() {
+        if (this.current === null) {
+            return;
+        }
+        this.sections.push({ name: this.current.name, count: this.current.count });
+        this.current = null;
+    }
+}
+exports.GenericStreamEncoder = GenericStreamEncoder;
+function formatValue(v) {
+    return (0, scalar_js_1.formatScalar)(v, 0x7c); // '|' context
+}
+//# sourceMappingURL=stream_generic.js.map

package/dist/cjs/stream_generic.js.map

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

package/dist/cjs/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Symbol represents a node in a GCF payload.
+ */
+export interface Symbol {
+    /** Fully qualified identifier (e.g., "pkg/auth.Middleware") */
+    qualifiedName: string;
+    /** Node type: "function", "type", "method", etc. */
+    kind: string;
+    /** Relevance score (0.0 to 1.0) */
+    score: number;
+    /** Discovery method: "lsp_resolved", "ast_inferred", etc. */
+    provenance: string;
+    /** Hops from query center (0=target, 1=related, 2+=extended) */
+    distance: number;
+    /** Optional: function/method signature */
+    signature?: string;
+    /** Optional: score breakdown */
+    components?: Components;
+}
+/**
+ * Components holds the score breakdown for a symbol.
+ */
+export interface Components {
+    blastRadius: number;
+    confidence: number;
+    recency: number;
+    distance: number;
+}
+/**
+ * Edge represents a directed relationship in a GCF payload.
+ */
+export interface Edge {
+    /** Qualified name of source symbol */
+    source: string;
+    /** Qualified name of target symbol */
+    target: string;
+    /** Relationship type (e.g., "calls", "imports", "implements") */
+    edgeType: string;
+    /** Optional: "added", "removed", "unchanged" (for diff responses) */
+    status?: string;
+}
+/**
+ * Payload is the input/output structure for GCF encoding/decoding.
+ */
+export interface Payload {
+    /** Producing tool name (e.g., "context_for_task") */
+    tool: string;
+    /** Token budget requested by the consumer */
+    tokenBudget: number;
+    /** Actual tokens consumed by this payload */
+    tokensUsed: number;
+    /** Content-addressed identity (hex SHA-256), enables delta encoding */
+    packRoot?: string;
+    /** Ordered by score descending within each distance group */
+    symbols: Symbol[];
+    /** Directed relationships between symbols */
+    edges: Edge[];
+}
+/**
+ * DeltaPayload represents the diff between a prior context pack and the
+ * current result. Used for incremental context delivery.
+ */
+export interface DeltaPayload {
+    tool: string;
+    /** pack_root the consumer has */
+    baseRoot: string;
+    /** pack_root of the current result */
+    newRoot: string;
+    removed: Symbol[];
+    added: Symbol[];
+    removedEdges: Edge[];
+    addedEdges: Edge[];
+    deltaTokens: number;
+    fullTokens: number;
+}

package/dist/cjs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackwell-systems/gcf",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Drop-in JSON replacement for AI pipelines. 79% fewer tokens. 90.7% comprehension across 10 models. Zero dependencies.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,7 +9,8 @@
     ".": {
       "types": "./dist/index.d.ts",
       "browser": "./dist/browser.js",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.cjs"
     },
     "./browser": {
       "types": "./dist/browser.d.ts",
@@ -27,10 +28,10 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npx esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/cjs/index.cjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "tsc"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "gcf",