@blackwell-systems/gcf 0.5.0 → 0.6.1

package/README.md

@@ -6,9 +6,9 @@
 
 # gcf-typescript
 
-TypeScript implementation of [GCF (Graph Compact Format)](https://gcformat.com/) — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
+TypeScript implementation of [GCF](https://gcformat.com/) — the most token-efficient wire format for LLMs. A drop-in alternative to JSON and TOON for any structured data.
 
-**79% fewer input tokens than JSON. 75% fewer output tokens. 52% smaller than TOON. 100% LLM comprehension at 500 symbols, where JSON scores 76.9% and TOON scores 92.3%.**
+**79% fewer input tokens than JSON. 63% fewer output tokens. 90.5% average comprehension accuracy across 10 models and 3 providers (four models hit 100%). 1,300+ LLM evaluations. Zero training.**
 
 Docs: [gcformat.com](https://gcformat.com/) · [Playground](https://gcformat.com/playground.html) · [GCF vs TOON](https://gcformat.com/guide/vs-toon.html)
 
@@ -190,33 +190,18 @@ Works on objects, arrays, and primitives. Arrays of uniform objects get tabular
 | `Session` | Tracker for multi-call deduplication |
 | `KIND_ABBREV` / `KIND_EXPAND` | Bidirectional kind abbreviation maps |
 
-## Comprehension Eval
+## Benchmarks
 
-Rigorous 3-way benchmark (GCF vs TOON vs JSON) at 500 symbols, 200 edges. 13 structured extraction questions sent to an LLM with zero format instructions:
+1,300+ LLM evaluations across 10 models, 3 providers, and 51 independent test runs.
 
-| Format | Accuracy | Tokens | vs JSON |
-|--------|----------|--------|---------|
-| **GCF** | **100%** (13/13) | **11,090** | **79% fewer** |
-| TOON | 92.3% (12/13) | 16,378 | 69% fewer |
-| JSON | 76.9% (10/13) | 53,341 | baseline |
+| | GCF | TOON | JSON |
+|---|---|---|---|
+| **Comprehension** (23 runs, 10 models) | **90.5%** | 68.5% | 53.6% |
+| **Generation** (28 runs, 9 models) | **5/5** | 1.0/5 | 5.0/5 |
+| **Input tokens** (500 symbols) | **11,090** | 16,378 | 53,341 |
+| **Output tokens** (100 symbols) | **5,976** | 8,937 | 16,121 |
 
-GCF is the only format with perfect accuracy at scale, at 32% fewer tokens than TOON.
-
-Reproduce: `git clone https://github.com/blackwell-systems/gcf-go && cd gcf-go/eval && GOWORK=off go test -run TestComprehension -v -timeout 0`
-
-## Token Efficiency (TOON's Own Benchmark)
-
-Running [TOON's benchmark harness](https://github.com/blackwell-systems/toon/tree/gcf-comparison) with GCF inserted (their datasets, their tokenizer):
-
-| Track | GCF | TOON | Result |
-|-------|-----|------|--------|
-| Mixed-structure (nested, semi-uniform) | 170,367 | 227,896 | **GCF 34% smaller** |
-| Flat-only (tabular) | 66,029 | 67,837 | **GCF 3% smaller** |
-| Semi-uniform event logs | 108,158 | 154,032 | **GCF 42% smaller** |
-
-GCF wins all 6 datasets. On semi-uniform data (the most common real-world pattern), GCF uses 42% fewer tokens than TOON.
-
-Reproduce: `git clone https://github.com/blackwell-systems/toon && cd toon && git checkout gcf-comparison && cd benchmarks && pnpm install && pnpm benchmark:tokens`
+GCF wins all 6 datasets on [TOON's own benchmark](https://github.com/blackwell-systems/toon/tree/gcf-comparison). Full results: [gcformat.com/guide/benchmarks](https://gcformat.com/guide/benchmarks.html)
 
 ## Links
 

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export { encodeDelta } from './delta.js';
 export { encodeGeneric } from './generic.js';
 export { decodeGeneric } from './decode_generic.js';
 export { StreamEncoder, type StreamWriter, type StreamOptions } from './stream.js';
+export { GenericStreamEncoder } from './stream_generic.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -6,4 +6,5 @@ export { encodeDelta } from './delta.js';
 export { encodeGeneric } from './generic.js';
 export { decodeGeneric } from './decode_generic.js';
 export { StreamEncoder } from './stream.js';
+export { GenericStreamEncoder } from './stream_generic.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAyC,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAyC,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/stream_generic.d.ts

@@ -0,0 +1,38 @@
+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;
+}
+//# sourceMappingURL=stream_generic.d.ts.map

package/dist/stream_generic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream_generic.d.ts","sourceRoot":"","sources":["../src/stream_generic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAahD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,OAAO,CAA4B;gBAE/B,MAAM,EAAE,YAAY;IAIhC,6DAA6D;IAC7D,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAQhD,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IASjC,4DAA4D;IAC5D,QAAQ,IAAI,IAAI;IAIhB,yCAAyC;IACzC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAI1C,8CAA8C;IAC9C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOhC,6DAA6D;IAC7D,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAKvD,qFAAqF;IACrF,KAAK,IAAI,IAAI;IAgBb,OAAO,CAAC,gBAAgB;CAOzB"}

package/dist/stream_generic.js

@@ -0,0 +1,105 @@
+/**
+ * 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 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;
+        }
+        let totalRows = 0;
+        const sectionParts = [];
+        for (const s of this.sections) {
+            sectionParts.push(`${s.name}:${s.count}`);
+            totalRows += s.count;
+        }
+        this.writer.write(`## _summary rows=${totalRows} sections=${sectionParts.join(',')}\n`);
+    }
+    endArrayInternal() {
+        if (this.current === null) {
+            return;
+        }
+        this.sections.push({ name: this.current.name, count: this.current.count });
+        this.current = null;
+    }
+}
+function formatValue(v) {
+    if (v === null || v === undefined) {
+        return '-';
+    }
+    if (typeof v === 'boolean') {
+        return v ? 'true' : 'false';
+    }
+    if (typeof v === 'number') {
+        return String(v);
+    }
+    if (typeof v === 'string') {
+        if (v === '') {
+            return '""';
+        }
+        if (v.includes('|') || v.includes('\n')) {
+            return `"${v.replace(/"/g, '\\"')}"`;
+        }
+        return v;
+    }
+    return String(v);
+}
+//# sourceMappingURL=stream_generic.js.map

package/dist/stream_generic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream_generic.js","sourceRoot":"","sources":["../src/stream_generic.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,oBAAoB;IACd,MAAM,CAAe;IAC9B,QAAQ,GAAmB,EAAE,CAAC;IAC9B,OAAO,GAAuB,IAAI,CAAC;IAE3C,YAAY,MAAoB;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,6DAA6D;IAC7D,UAAU,CAAC,IAAY,EAAE,MAAgB;QACvC,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,QAAQ,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,oDAAoD;IACpD,QAAQ,CAAC,MAAiB;QACxB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,4DAA4D;IAC5D,QAAQ;QACN,IAAI,CAAC,gBAAgB,EAAE,CAAC;IAC1B,CAAC;IAED,yCAAyC;IACzC,OAAO,CAAC,GAAW,EAAE,KAAc;QACjC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtD,CAAC;IAED,8CAA8C;IAC9C,YAAY,CAAC,IAAY;QACvB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,6DAA6D;IAC7D,gBAAgB,CAAC,IAAY,EAAE,MAAiB;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvE,CAAC;IAED,qFAAqF;IACrF,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC1B,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC/B,OAAO;QACT,CAAC;QACD,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC9B,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YAC1C,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oBAAoB,SAAS,aAAa,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1F,CAAC;IAEO,gBAAgB;QACtB,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF;AAED,SAAS,WAAW,CAAC,CAAU;IAC7B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QAClC,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC;YACb,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;QACvC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackwell-systems/gcf",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "TypeScript implementation of GCF (Graph Compact Format) - token-optimized wire format for LLM tool responses",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -7,3 +7,4 @@ export { encodeDelta } from './delta.js';
 export { encodeGeneric } from './generic.js';
 export { decodeGeneric } from './decode_generic.js';
 export { StreamEncoder, type StreamWriter, type StreamOptions } from './stream.js';
+export { GenericStreamEncoder } from './stream_generic.js';

package/src/stream_generic.ts

@@ -0,0 +1,127 @@
+import type { StreamWriter } from './stream.js';
+
+interface SectionCount {
+  name: string;
+  count: number;
+}
+
+interface ActiveArray {
+  name: string;
+  fields: string[];
+  count: number;
+}
+
+/**
+ * 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 class GenericStreamEncoder {
+  private readonly writer: StreamWriter;
+  private sections: SectionCount[] = [];
+  private current: ActiveArray | null = null;
+
+  constructor(writer: StreamWriter) {
+    this.writer = writer;
+  }
+
+  /** Start a tabular array section with deferred count [?]. */
+  beginArray(name: string, fields: string[]): void {
+    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: unknown[]): void {
+    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(): void {
+    this.endArrayInternal();
+  }
+
+  /** Emit a key=value line immediately. */
+  writeKV(key: string, value: unknown): void {
+    this.writer.write(`${key}=${formatValue(value)}\n`);
+  }
+
+  /** Start a nested object section (## key). */
+  writeSection(name: string): void {
+    if (this.current !== null) {
+      this.endArrayInternal();
+    }
+    this.writer.write(`## ${name}\n`);
+  }
+
+  /** Emit a primitive array inline: name[N]: val1,val2,val3 */
+  writeInlineArray(name: string, values: unknown[]): void {
+    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(): void {
+    if (this.current !== null) {
+      this.endArrayInternal();
+    }
+    if (this.sections.length === 0) {
+      return;
+    }
+    let totalRows = 0;
+    const sectionParts: string[] = [];
+    for (const s of this.sections) {
+      sectionParts.push(`${s.name}:${s.count}`);
+      totalRows += s.count;
+    }
+    this.writer.write(`## _summary rows=${totalRows} sections=${sectionParts.join(',')}\n`);
+  }
+
+  private endArrayInternal(): void {
+    if (this.current === null) {
+      return;
+    }
+    this.sections.push({ name: this.current.name, count: this.current.count });
+    this.current = null;
+  }
+}
+
+function formatValue(v: unknown): string {
+  if (v === null || v === undefined) {
+    return '-';
+  }
+  if (typeof v === 'boolean') {
+    return v ? 'true' : 'false';
+  }
+  if (typeof v === 'number') {
+    return String(v);
+  }
+  if (typeof v === 'string') {
+    if (v === '') {
+      return '""';
+    }
+    if (v.includes('|') || v.includes('\n')) {
+      return `"${v.replace(/"/g, '\\"')}"`;
+    }
+    return v;
+  }
+  return String(v);
+}