@blackwell-systems/gcf 0.1.0

package/src/decode.ts

@@ -0,0 +1,208 @@
+import type { Edge, Payload, Symbol } from './types.js';
+import { KIND_EXPAND } from './constants.js';
+
+/**
+ * Decode parses GCF text back into a Payload.
+ */
+export function decode(input: string): Payload {
+  const lines = input.split('\n');
+  if (lines.length === 0) {
+    throw new Error('gcf: empty input');
+  }
+
+  const header = lines[0];
+  if (!header.startsWith('GCF ')) {
+    throw new Error(`gcf: invalid header, expected 'GCF ...' got "${header}"`);
+  }
+
+  const p: Payload = {
+    tool: '',
+    tokenBudget: 0,
+    tokensUsed: 0,
+    symbols: [],
+    edges: [],
+  };
+
+  // Parse header fields.
+  parseHeader(header.slice(4), p);
+
+  // Parse body: symbols and edges.
+  const symbols: Symbol[] = [];
+  const symByID = new Map<number, Symbol>();
+  let currentDistance = 0;
+  let inEdges = false;
+
+  for (let i = 1; i < lines.length; i++) {
+    let line = lines[i].replace(/\r$/, '');
+    if (line === '') continue;
+
+    // Group header.
+    if (line.startsWith('## ')) {
+      const group = line.slice(3);
+      inEdges = group === 'edges';
+      if (!inEdges) {
+        switch (group) {
+          case 'targets':
+            currentDistance = 0;
+            break;
+          case 'related':
+            currentDistance = 1;
+            break;
+          case 'extended':
+            currentDistance = 2;
+            break;
+          default:
+            if (group.startsWith('distance_')) {
+              const d = parseInt(group.slice(9), 10);
+              if (!isNaN(d)) {
+                currentDistance = d;
+              }
+            }
+            break;
+        }
+      }
+      continue;
+    }
+
+    // Comment.
+    if (line.startsWith('# ')) {
+      continue;
+    }
+
+    if (inEdges) {
+      const edge = parseEdgeLine(line, symByID);
+      p.edges.push(edge);
+    } else {
+      const { symbol, id } = parseSymbolLine(line, currentDistance);
+      symbols.push(symbol);
+      symByID.set(id, symbol);
+    }
+  }
+
+  p.symbols = symbols;
+  return p;
+}
+
+function parseHeader(fields: string, p: Payload): void {
+  const parts = fields.split(/\s+/);
+  for (const part of parts) {
+    const eqIdx = part.indexOf('=');
+    if (eqIdx < 0) continue;
+    const key = part.slice(0, eqIdx);
+    const value = part.slice(eqIdx + 1);
+
+    switch (key) {
+      case 'tool':
+        p.tool = value;
+        break;
+      case 'budget': {
+        const v = parseInt(value, 10);
+        if (isNaN(v)) throw new Error(`gcf: invalid budget "${value}"`);
+        p.tokenBudget = v;
+        break;
+      }
+      case 'tokens': {
+        const v = parseInt(value, 10);
+        if (isNaN(v)) throw new Error(`gcf: invalid tokens "${value}"`);
+        p.tokensUsed = v;
+        break;
+      }
+      case 'pack_root':
+        p.packRoot = value;
+        break;
+      case 'symbols':
+        // Informational, reconstructed from parsed symbols.
+        break;
+    }
+  }
+}
+
+function parseSymbolLine(
+  line: string,
+  distance: number
+): { symbol: Symbol; id: number } {
+  if (!line.startsWith('@')) {
+    throw new Error(`gcf: expected symbol line starting with @, got "${line}"`);
+  }
+
+  const parts = line.split(/\s+/);
+  if (parts.length < 5) {
+    throw new Error(
+      `gcf: symbol line needs at least 5 fields, got ${parts.length} in "${line}"`
+    );
+  }
+
+  const idStr = parts[0].slice(1); // strip @
+  const id = parseInt(idStr, 10);
+  if (isNaN(id)) {
+    throw new Error(`gcf: invalid symbol id "${idStr}"`);
+  }
+
+  let kind = parts[1];
+  if (KIND_EXPAND[kind]) {
+    kind = KIND_EXPAND[kind];
+  }
+
+  const qname = parts[2];
+
+  const score = parseFloat(parts[3]);
+  if (isNaN(score)) {
+    throw new Error(`gcf: invalid score "${parts[3]}"`);
+  }
+
+  const provenance = parts[4];
+
+  return {
+    symbol: {
+      qualifiedName: qname,
+      kind,
+      score,
+      provenance,
+      distance,
+    },
+    id,
+  };
+}
+
+function parseEdgeLine(line: string, symByID: Map<number, Symbol>): Edge {
+  const parts = line.split(/\s+/);
+  if (parts.length < 2) {
+    throw new Error(`gcf: edge line needs at least 2 fields, got "${line}"`);
+  }
+
+  const ref = parts[0];
+  const ltIdx = ref.indexOf('<');
+  if (ltIdx < 0) {
+    throw new Error(`gcf: edge line missing '<' separator in "${ref}"`);
+  }
+
+  const targetIDStr = ref.slice(1, ltIdx); // strip leading @
+  const sourceIDStr = ref.slice(ltIdx + 2); // strip <@
+
+  const targetID = parseInt(targetIDStr, 10);
+  if (isNaN(targetID)) {
+    throw new Error(`gcf: invalid target id "${targetIDStr}"`);
+  }
+  const sourceID = parseInt(sourceIDStr, 10);
+  if (isNaN(sourceID)) {
+    throw new Error(`gcf: invalid source id "${sourceIDStr}"`);
+  }
+
+  const targetSym = symByID.get(targetID);
+  const sourceSym = symByID.get(sourceID);
+  if (!targetSym || !sourceSym) {
+    throw new Error(
+      `gcf: edge references unknown symbol id(s): target=${targetID} source=${sourceID}`
+    );
+  }
+
+  const edgeType = parts[1];
+  const status = parts.length >= 3 ? parts[2] : undefined;
+
+  return {
+    source: sourceSym.qualifiedName,
+    target: targetSym.qualifiedName,
+    edgeType,
+    status,
+  };
+}

package/src/delta.ts

@@ -0,0 +1,55 @@
+import type { DeltaPayload } from './types.js';
+import { KIND_ABBREV } from './constants.js';
+
+/**
+ * EncodeDelta serializes a DeltaPayload into GCF delta format.
+ */
+export function encodeDelta(d: DeltaPayload): string {
+  const lines: string[] = [];
+
+  // Header.
+  let savings = 0;
+  if (d.fullTokens > 0) {
+    savings = Math.round(100 * (1 - d.deltaTokens / d.fullTokens));
+  }
+  lines.push(
+    `GCF tool=${d.tool} delta=true base_root=${d.baseRoot} new_root=${d.newRoot} tokens=${d.deltaTokens} savings=${savings}%`
+  );
+
+  // Removed symbols: short references (consumer already has the full declaration).
+  if (d.removed.length > 0) {
+    lines.push('## removed');
+    for (const s of d.removed) {
+      const kind = KIND_ABBREV[s.kind] || s.kind;
+      lines.push(`${kind} ${s.qualifiedName}`);
+    }
+  }
+
+  // Added symbols: full declarations (consumer doesn't have these).
+  if (d.added.length > 0) {
+    lines.push('## added');
+    for (let i = 0; i < d.added.length; i++) {
+      const s = d.added[i];
+      const kind = KIND_ABBREV[s.kind] || s.kind;
+      lines.push(`@${i} ${kind} ${s.qualifiedName} ${s.score.toFixed(2)} ${s.provenance}`);
+    }
+  }
+
+  // Removed edges.
+  if (d.removedEdges.length > 0) {
+    lines.push('## edges_removed');
+    for (const e of d.removedEdges) {
+      lines.push(`${e.source} -> ${e.target} ${e.edgeType}`);
+    }
+  }
+
+  // Added edges.
+  if (d.addedEdges.length > 0) {
+    lines.push('## edges_added');
+    for (const e of d.addedEdges) {
+      lines.push(`${e.source} -> ${e.target} ${e.edgeType}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}

package/src/encode.ts

@@ -0,0 +1,84 @@
+import type { Payload, Symbol } from './types.js';
+import { KIND_ABBREV } from './constants.js';
+
+interface DistanceGroup {
+  distance: number;
+  symbols: Symbol[];
+}
+
+function groupByDistance(symbols: Symbol[]): DistanceGroup[] {
+  if (symbols.length === 0) return [];
+
+  const groups: DistanceGroup[] = [];
+  let current: DistanceGroup | null = 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 serializes a Payload into GCF text format.
+ */
+export function encode(p: Payload): string {
+  const lines: string[] = [];
+
+  // Header line.
+  let header = `GCF tool=${p.tool} budget=${p.tokenBudget} tokens=${p.tokensUsed} symbols=${p.symbols.length}`;
+  if (p.packRoot) {
+    header += ` pack_root=${p.packRoot}`;
+  }
+  lines.push(header);
+
+  // Build symbol index for edge references.
+  const symIndex = new Map<string, number>();
+  for (let i = 0; i < p.symbols.length; i++) {
+    symIndex.set(p.symbols[i].qualifiedName, i);
+  }
+
+  // Group symbols 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: string;
+    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 = symIndex.get(s.qualifiedName)!;
+      const kind = KIND_ABBREV[s.kind] || s.kind;
+      lines.push(`@${idx} ${kind} ${s.qualifiedName} ${s.score.toFixed(2)} ${s.provenance}`);
+    }
+  }
+
+  // Edges section.
+  if (p.edges.length > 0) {
+    lines.push('## edges');
+    for (const e of p.edges) {
+      const srcIdx = symIndex.get(e.source);
+      const tgtIdx = symIndex.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);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export type { Symbol, Edge, Payload, DeltaPayload, Components } from './types.js';
+export { KIND_ABBREV, KIND_EXPAND } from './constants.js';
+export { encode } from './encode.js';
+export { decode } from './decode.js';
+export { Session, encodeWithSession } from './session.js';
+export { encodeDelta } from './delta.js';

package/src/session.ts

@@ -0,0 +1,147 @@
+import type { Payload, Symbol } from './types.js';
+import { KIND_ABBREV } from './constants.js';
+import { encode } from './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.
+ */
+export class Session {
+  private symbols: Map<string, number> = new Map();
+  private nextID: number = 0;
+
+  /** Returns true if the symbol has been sent in a previous response. */
+  transmitted(qname: string): boolean {
+    return this.symbols.has(qname);
+  }
+
+  /** Returns the session-global ID for a previously transmitted symbol, or -1 if not found. */
+  getID(qname: string): number {
+    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: Symbol[]): void {
+    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(): number {
+    return this.symbols.size;
+  }
+
+  /** Clears the session state. */
+  reset(): void {
+    this.symbols.clear();
+    this.nextID = 0;
+  }
+}
+
+interface DistanceGroup {
+  distance: number;
+  symbols: Symbol[];
+}
+
+function groupByDistance(symbols: Symbol[]): DistanceGroup[] {
+  if (symbols.length === 0) return [];
+  const groups: DistanceGroup[] = [];
+  let current: DistanceGroup | null = 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.
+ */
+export function encodeWithSession(p: Payload, sess: Session | null): string {
+  if (!sess) {
+    return encode(p);
+  }
+
+  const lines: string[] = [];
+
+  // Header with session=true marker.
+  let header = `GCF tool=${p.tool} budget=${p.tokenBudget} tokens=${p.tokensUsed} symbols=${p.symbols.length} session=true`;
+  if (p.packRoot) {
+    header += ` pack_root=${p.packRoot}`;
+  }
+  lines.push(header);
+
+  // Build local ID mapping for this response.
+  const localIndex = new Map<string, number>();
+  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: Symbol[] = [];
+
+  // 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: string;
+    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 = 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');
+    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';
+}

package/src/types.ts

@@ -0,0 +1,79 @@
+/**
+ * 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;
+}