@blackwell-systems/gcf 0.6.1 → 1.0.0

package/src/generic.ts

@@ -1,164 +1,163 @@
 /**
- * Generic encoder: converts any JS value into GCF tabular format.
+ * Generic encoder: converts any JS value into GCF v2.0 generic profile.
  */
-
-function formatValue(value: unknown): string {
-  if (value === null || value === undefined) return '-';
-  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
-  const s = String(value);
-  if (s.includes('|') || s.includes('\n') || s === '') return JSON.stringify(s);
-  return s;
-}
+import { formatScalar, formatKey, ATTACHMENT } from './scalar.js';
 
 function indent(depth: number): string {
   return '  '.repeat(depth);
 }
 
-function isUniformObjectArray(arr: unknown[]): boolean {
-  if (arr.length === 0) return false;
-  const objects = arr.filter(
-    (item): item is Record<string, unknown> =>
-      typeof item === 'object' && item !== null && !Array.isArray(item),
-  );
-  if (objects.length !== arr.length) return false;
-
-  const referenceKeys = Object.keys(objects[0]).sort().join(',');
-  const sampleSize = Math.min(5, objects.length);
-  const refSet = new Set(Object.keys(objects[0]));
-
-  for (let i = 1; i < sampleSize; i++) {
-    const keys = Object.keys(objects[i]);
-    const currentSet = new Set(keys);
-    // 70% overlap check.
-    const union = new Set([...refSet, ...currentSet]);
-    const intersection = [...refSet].filter((k) => currentSet.has(k));
-    if (intersection.length / union.size < 0.7) return false;
-  }
+export function encodeGeneric(data: unknown): string {
+  let out = 'GCF profile=generic\n';
+  out += encodeRootValue(data);
+  return out;
+}
 
-  return true;
+function encodeRootValue(v: unknown): string {
+  if (v === null || v === undefined) return '=-\n';
+  if (Array.isArray(v)) return encodeRootArray(v);
+  if (typeof v === 'object') return encodeObject(v as Record<string, unknown>, 0);
+  return `=${formatScalar(v, 0)}\n`;
 }
 
-function encodeArray(
-  arr: unknown[],
-  name: string,
-  lines: string[],
-  depth: number,
-): void {
+function encodeObject(obj: Record<string, unknown>, depth: number): string {
   const prefix = indent(depth);
+  let out = '';
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    const fk = formatKey(key);
+    if (Array.isArray(value)) {
+      out += encodeNamedArray(fk, value, depth);
+    } else if (typeof value === 'object' && value !== null) {
+      out += `${prefix}## ${fk}\n`;
+      out += encodeObject(value as Record<string, unknown>, depth + 1);
+    } else {
+      out += `${prefix}${fk}=${formatScalar(value, 0)}\n`;
+    }
+  }
+  return out;
+}
 
-  if (isUniformObjectArray(arr)) {
-    const objects = arr as Record<string, unknown>[];
+function encodeRootArray(arr: unknown[]): string {
+  if (arr.length === 0) return '## [0]\n';
+  if (allPrimitives(arr)) {
+    const vals = arr.map(v => formatScalar(v, 0x2c));
+    return `## [${arr.length}]: ${vals.join(',')}\n`;
+  }
+  const fields = tabularFields(arr);
+  if (fields) return encodeTabular('## ', arr, fields, 0);
+  return encodeExpanded('## ', arr, 0);
+}
+
+function encodeNamedArray(name: string, arr: unknown[], depth: number): string {
+  const prefix = indent(depth);
+  if (arr.length === 0) return `${prefix}## ${name} [0]\n`;
+  if (allPrimitives(arr)) {
+    const vals = arr.map(v => formatScalar(v, 0x2c));
+    return `${prefix}${name}[${arr.length}]: ${vals.join(',')}\n`;
+  }
+  const fields = tabularFields(arr);
+  if (fields) return encodeTabular(`${prefix}## ${name} `, arr, fields, depth);
+  return encodeExpanded(`${prefix}## ${name} `, arr, depth);
+}
 
-    // Collect all keys across items.
-    const allKeys = new Set<string>();
-    for (const obj of objects) {
-      for (const k of Object.keys(obj)) allKeys.add(k);
+function tabularFields(arr: unknown[]): string[] | null {
+  if (arr.length === 0) return null;
+  const fieldOrder: string[] = [];
+  const seen = new Set<string>();
+  for (const item of arr) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) return null;
+    for (const k of Object.keys(item as Record<string, unknown>)) {
+      if (!seen.has(k)) { fieldOrder.push(k); seen.add(k); }
     }
+  }
+  return fieldOrder.length > 0 ? fieldOrder : null;
+}
 
-    // Separate primitive fields from nested fields.
-    const primitiveFields: string[] = [];
-    const nestedFields: string[] = [];
-    for (const key of allKeys) {
-      const sample = objects.find((o) => o[key] !== undefined)?.[key];
-      if (
-        typeof sample === 'object' &&
-        sample !== null
-      ) {
-        nestedFields.push(key);
+function encodeTabular(headerPrefix: string, arr: unknown[], fields: string[], depth: number): string {
+  const prefix = indent(depth);
+  const fmtFields = fields.map(f => formatKey(f));
+  let out = `${headerPrefix}[${arr.length}]{${fmtFields.join(',')}}\n`;
+
+  for (let i = 0; i < arr.length; i++) {
+    const obj = arr[i] as Record<string, unknown>;
+    const cells: string[] = [];
+    const attachments: { name: string; value: unknown }[] = [];
+    let rowHasAttachment = false;
+
+    for (const f of fields) {
+      if (!(f in obj)) { cells.push('~'); continue; }
+      const v = obj[f];
+      if (v === null || v === undefined) { cells.push('-'); continue; }
+      if (typeof v === 'object') {
+        cells.push('^');
+        attachments.push({ name: f, value: v });
+        rowHasAttachment = true;
       } else {
-        primitiveFields.push(key);
+        cells.push(formatScalar(v, 0x7c));
       }
     }
 
-    lines.push(`${prefix}## ${name} [${arr.length}]{${primitiveFields.join(',')}}`);
-
-    if (nestedFields.length === 0) {
-      // Pure flat rows: no @id prefix.
-      for (const obj of objects) {
-        const vals = primitiveFields.map((f) => formatValue(obj[f]));
-        lines.push(`${prefix}${vals.join('|')}`);
-      }
+    const row = cells.join('|');
+    if (rowHasAttachment) {
+      out += `${prefix}@${i} ${row}\n`;
     } else {
-      // Rows with nested fields: @N prefix.
-      for (let i = 0; i < objects.length; i++) {
-        const obj = objects[i];
-        const vals = primitiveFields.map((f) => formatValue(obj[f]));
-        lines.push(`${prefix}@${i} ${vals.join('|')}`);
-        for (const nk of nestedFields) {
-          const nv = obj[nk];
-          if (nv === undefined || nv === null) continue;
-          if (Array.isArray(nv)) {
-            encodeArray(nv, nk, lines, depth + 1);
-          } else if (typeof nv === 'object') {
-            encodeObject(nv as Record<string, unknown>, nk, lines, depth + 1);
-          }
-        }
-      }
+      out += `${prefix}${row}\n`;
     }
-  } else {
-    // Check if all items are primitives (inline as comma-separated).
-    const allPrimitive = arr.length > 0 && arr.every(
-      (item) => item === null || typeof item !== 'object',
-    );
-
-    if (allPrimitive) {
-      const vals = arr.map((item) => formatValue(item));
-      lines.push(`${prefix}${name}[${arr.length}]: ${vals.join(',')}`);
-    } else {
-      // Non-uniform with objects: per-item encoding.
-      lines.push(`${prefix}## ${name} [${arr.length}]`);
-      for (let i = 0; i < arr.length; i++) {
-        const item = arr[i];
-        if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
-          lines.push(`${prefix}@${i}`);
-          encodeObject(item as Record<string, unknown>, null, lines, depth + 1);
-        } else {
-          lines.push(`${prefix}@${i} ${formatValue(item)}`);
-        }
+
+    for (const att of attachments) {
+      const attPrefix = prefix + '  ';
+      const fk = formatKey(att.name);
+      if (Array.isArray(att.value)) {
+        out += encodeAttachmentArray(attPrefix, fk, att.value as unknown[], depth + 2);
+      } else {
+        out += `${attPrefix}.${fk} {}\n`;
+        out += encodeObject(att.value as Record<string, unknown>, depth + 2);
       }
     }
   }
+  return out;
 }
 
-function encodeObject(
-  obj: Record<string, unknown>,
-  name: string | null,
-  lines: string[],
-  depth: number,
-): void {
-  const prefix = indent(depth);
-
-  if (name !== null) {
-    lines.push(`${prefix}## ${name}`);
+function encodeAttachmentArray(attPrefix: string, fk: string, arr: unknown[], depth: number): string {
+  if (arr.length === 0) return `${attPrefix}.${fk} [0]\n`;
+  if (allPrimitives(arr)) {
+    const vals = arr.map(v => formatScalar(v, 0x2c));
+    return `${attPrefix}.${fk} [${arr.length}]: ${vals.join(',')}\n`;
   }
+  const fields = tabularFields(arr);
+  if (fields) return encodeTabular(`${attPrefix}.${fk} `, arr, fields, depth);
+  return encodeExpanded(`${attPrefix}.${fk} `, arr, depth);
+}
 
-  for (const [key, value] of Object.entries(obj)) {
-    if (Array.isArray(value)) {
-      encodeArray(value, key, lines, depth);
-    } else if (typeof value === 'object' && value !== null) {
-      encodeObject(value as Record<string, unknown>, key, lines, depth + 1);
+function encodeExpanded(headerPrefix: string, arr: unknown[], depth: number): string {
+  const prefix = indent(depth);
+  let out = `${headerPrefix}[${arr.length}]\n`;
+  for (let i = 0; i < arr.length; i++) {
+    const item = arr[i];
+    if (Array.isArray(item)) {
+      out += encodeExpandedArrayItem(prefix, i, item, depth);
+    } else if (typeof item === 'object' && item !== null) {
+      out += `${prefix}@${i} {}\n`;
+      out += encodeObject(item as Record<string, unknown>, depth + 1);
     } else {
-      lines.push(`${prefix}${key}=${formatValue(value)}`);
+      out += `${prefix}@${i} =${formatScalar(item, 0)}\n`;
     }
   }
+  return out;
 }
 
-/**
- * Encode any JS value into GCF tabular format.
- */
-export function encodeGeneric(data: unknown): string {
-  // Primitives.
-  if (data === null || data === undefined || typeof data !== 'object') {
-    return String(data);
-  }
-
-  const lines: string[] = [];
-
-  if (Array.isArray(data)) {
-    encodeArray(data, 'root', lines, 0);
-  } else {
-    encodeObject(data as Record<string, unknown>, null, lines, 0);
+function encodeExpandedArrayItem(prefix: string, idx: number, arr: unknown[], depth: number): string {
+  if (arr.length === 0) return `${prefix}@${idx} [0]\n`;
+  if (allPrimitives(arr)) {
+    const vals = arr.map(v => formatScalar(v, 0x2c));
+    return `${prefix}@${idx} [${arr.length}]: ${vals.join(',')}\n`;
   }
+  const fields = tabularFields(arr);
+  if (fields) return encodeTabular(`${prefix}@${idx} `, arr, fields, depth + 1);
+  return encodeExpanded(`${prefix}@${idx} `, arr, depth + 1);
+}
 
-  return lines.join('\n') + '\n';
+function allPrimitives(arr: unknown[]): boolean {
+  return arr.every(v => typeof v !== 'object' || v === null);
 }

package/src/index.ts

@@ -6,5 +6,6 @@ export { Session, encodeWithSession } from './session.js';
 export { encodeDelta } from './delta.js';
 export { encodeGeneric } from './generic.js';
 export { decodeGeneric } from './decode_generic.js';
+export { formatScalar, formatKey, parseScalar, needsQuote, quoteString } from './scalar.js';
 export { StreamEncoder, type StreamWriter, type StreamOptions } from './stream.js';
 export { GenericStreamEncoder } from './stream_generic.js';

package/src/scalar.ts

@@ -0,0 +1,249 @@
+/**
+ * Common scalar grammar for GCF v2.0.
+ * Shared between encoder, decoder, and streaming encoder.
+ */
+
+const JSON_NUMBER_RE = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+const NUMERIC_LIKE_RE = /^[+-]?\.?\d/;
+
+/** Check if a string value must be quoted per Section 2.4. */
+export function needsQuote(s: string): boolean {
+  if (s === '') return true;
+  if (s === '-' || s === '~' || s === '^' || s === 'true' || s === 'false') return true;
+  if (JSON_NUMBER_RE.test(s)) return true;
+  if (NUMERIC_LIKE_RE.test(s)) return true;
+  if (s[0] === ' ' || s[s.length - 1] === ' ') return true;
+  if (s[0] === '#' || s[0] === '@') return true;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 0x22 || c === 0x5c || c < 0x20 || c === 0x0a || c === 0x0d ||
+        c === 0x7c || c === 0x2c) return true; // " \ control \n \r | ,
+  }
+  return false;
+}
+
+/** Produce a JSON-compatible quoted string. */
+export function quoteString(s: string): string {
+  let out = '"';
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    switch (c) {
+      case 0x22: out += '\\"'; break;
+      case 0x5c: out += '\\\\'; break;
+      case 0x08: out += '\\b'; break;
+      case 0x0c: out += '\\f'; break;
+      case 0x0a: out += '\\n'; break;
+      case 0x0d: out += '\\r'; break;
+      case 0x09: out += '\\t'; break;
+      default:
+        if (c < 0x20) {
+          out += '\\u' + c.toString(16).padStart(4, '0');
+        } else {
+          out += s[i];
+        }
+    }
+  }
+  return out + '"';
+}
+
+/** Format a JS value as a GCF scalar. delimiter is '|', ',', or 0. */
+export function formatScalar(v: unknown, delimiter: number = 0): string {
+  if (v === null || v === undefined) return '-';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') return formatNumber(v);
+  const s = String(v);
+  if (needsQuote(s) || (delimiter && s.includes(String.fromCharCode(delimiter)))) {
+    return quoteString(s);
+  }
+  return s;
+}
+
+/** Format a number per Section 2.3 canonical rules. */
+export function formatNumber(f: number): string {
+  if (Object.is(f, -0)) return '-0';
+  if (f === 0) return '0';
+  const abs = Math.abs(f);
+  if (abs >= 1e-6 && abs < 1e21) {
+    return toPreciseDecimal(f);
+  }
+  // Exponent notation.
+  let s = f.toExponential();
+  // Normalize: lowercase e, no leading zeros in exponent.
+  s = s.replace(/[eE]\+?0*(\d)/, 'e+$1').replace(/[eE]-0*(\d)/, 'e-$1');
+  return s;
+}
+
+function toPreciseDecimal(f: number): string {
+  // String(f) produces the shortest representation that round-trips through parseFloat.
+  return String(f);
+}
+
+const BARE_KEY_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** Check if a key is a valid bare key. */
+export function isBareKey(s: string): boolean {
+  return BARE_KEY_RE.test(s);
+}
+
+/** Format a key, quoting if necessary. */
+export function formatKey(s: string): string {
+  return isBareKey(s) ? s : quoteString(s);
+}
+
+// --- Decoder scalar parsing ---
+
+/** Parse a GCF scalar token per Section 2.1 precedence. */
+export function parseScalar(s: string, tabularContext: boolean): any {
+  if (s === '') return '';
+
+  // 1. Quoted string.
+  if (s[0] === '"') return parseQuotedString(s);
+
+  // 2. Null.
+  if (s === '-') return null;
+
+  // 3. Missing (tabular only).
+  if (s === '~') {
+    if (!tabularContext) throw new Error('invalid_missing: ~ outside tabular row cell');
+    return MISSING;
+  }
+
+  // 4. Attachment (tabular only).
+  if (s === '^') {
+    if (!tabularContext) throw new Error('invalid_attachment_marker: ^ outside tabular row cell');
+    return ATTACHMENT;
+  }
+
+  // 5. Boolean.
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+
+  // 6. Number.
+  if (JSON_NUMBER_RE.test(s)) {
+    const f = Number(s);
+    if (!isNaN(f)) return f;
+  }
+
+  // 7. Bare string.
+  return s;
+}
+
+export const MISSING = Symbol('missing');
+export const ATTACHMENT = Symbol('attachment');
+
+/** Parse a JSON-compatible quoted string. */
+export function parseQuotedString(s: string): string {
+  if (s.length < 2 || s[0] !== '"') throw new Error('unterminated_quote');
+  let out = '';
+  let i = 1;
+  while (i < s.length) {
+    if (s[i] === '"') {
+      if (i + 1 !== s.length) throw new Error('trailing_characters: after closing quote');
+      return out;
+    }
+    if (s[i] === '\\') {
+      if (i + 1 >= s.length) throw new Error('unterminated_quote');
+      i++;
+      switch (s[i]) {
+        case '"': out += '"'; break;
+        case '\\': out += '\\'; break;
+        case '/': out += '/'; break;
+        case 'b': out += '\b'; break;
+        case 'f': out += '\f'; break;
+        case 'n': out += '\n'; break;
+        case 'r': out += '\r'; break;
+        case 't': out += '\t'; break;
+        case 'u': {
+          if (i + 4 >= s.length) throw new Error('invalid_escape: incomplete unicode');
+          const hex = s.slice(i + 1, i + 5);
+          const code = parseInt(hex, 16);
+          if (isNaN(code)) throw new Error(`invalid_escape: invalid unicode \\u${hex}`);
+          // Surrogate pair handling.
+          if (code >= 0xd800 && code <= 0xdbff) {
+            if (i + 10 >= s.length || s[i + 5] !== '\\' || s[i + 6] !== 'u') {
+              throw new Error('invalid_surrogate: isolated high surrogate');
+            }
+            const hex2 = s.slice(i + 7, i + 11);
+            const low = parseInt(hex2, 16);
+            if (isNaN(low) || low < 0xdc00 || low > 0xdfff) {
+              throw new Error('invalid_surrogate: invalid low surrogate');
+            }
+            out += String.fromCodePoint(0x10000 + (code - 0xd800) * 0x400 + (low - 0xdc00));
+            i += 11;
+            continue;
+          }
+          if (code >= 0xdc00 && code <= 0xdfff) {
+            throw new Error('invalid_surrogate: isolated low surrogate');
+          }
+          out += String.fromCharCode(code);
+          i += 5;
+          continue;
+        }
+        default: throw new Error(`invalid_escape: unknown \\${s[i]}`);
+      }
+      i++;
+      continue;
+    }
+    if (s.charCodeAt(i) < 0x20) {
+      throw new Error(`invalid_escape: unescaped control U+${s.charCodeAt(i).toString(16).padStart(4, '0')}`);
+    }
+    out += s[i];
+    i++;
+  }
+  throw new Error('unterminated_quote');
+}
+
+/** Split a string on a delimiter, respecting quoted strings. */
+export function splitRespectingQuotes(s: string, delim: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let inQuote = false;
+  let escaped = false;
+  for (let i = 0; i < s.length; i++) {
+    if (escaped) { current += s[i]; escaped = false; continue; }
+    if (s[i] === '\\' && inQuote) { current += s[i]; escaped = true; continue; }
+    if (s[i] === '"') { inQuote = !inQuote; current += s[i]; continue; }
+    if (s[i] === delim && !inQuote) { parts.push(current); current = ''; continue; }
+    current += s[i];
+  }
+  parts.push(current);
+  return parts;
+}
+
+/** Split a field declaration like {id,"display name","a,b"}. */
+export function splitFieldDecl(s: string): string[] {
+  if (s.length < 2 || s[0] !== '{') throw new Error('invalid field declaration');
+  const closeIdx = findClosingBrace(s);
+  if (closeIdx < 0) throw new Error('invalid field declaration');
+  const inner = s.slice(1, closeIdx);
+  if (!inner) return [];
+  const raw = splitRespectingQuotes(inner, ',');
+  const fields: string[] = [];
+  const seen = new Set<string>();
+  for (const f of raw) {
+    const trimmed = f.trim();
+    let name: string;
+    if (trimmed.length >= 2 && trimmed[0] === '"' && trimmed[trimmed.length - 1] === '"') {
+      name = parseQuotedString(trimmed);
+    } else {
+      if (!isBareKey(trimmed)) throw new Error(`invalid field name: ${trimmed}`);
+      name = trimmed;
+    }
+    if (seen.has(name)) throw new Error(`duplicate_field_name: ${name}`);
+    seen.add(name);
+    fields.push(name);
+  }
+  return fields;
+}
+
+function findClosingBrace(s: string): number {
+  let inQuote = false;
+  let escaped = false;
+  for (let i = 0; i < s.length; i++) {
+    if (escaped) { escaped = false; continue; }
+    if (s[i] === '\\' && inQuote) { escaped = true; continue; }
+    if (s[i] === '"') { inQuote = !inQuote; continue; }
+    if (s[i] === '}' && !inQuote) return i;
+  }
+  return -1;
+}

package/src/session.ts

@@ -80,7 +80,12 @@ export function encodeWithSession(p: Payload, sess: Session | null): string {
   const lines: string[] = [];
 
   // Header with session=true marker.
-  let header = `GCF tool=${p.tool} budget=${p.tokenBudget} tokens=${p.tokensUsed} symbols=${p.symbols.length} edges=${p.edges.length} session=true`;
+  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}`;
   }

package/src/stream.ts

@@ -48,7 +48,7 @@ export class StreamEncoder {
   }
 
   private writeHeader(tool: string, opts: StreamOptions): void {
-    const parts = [`GCF tool=${tool}`];
+    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}`);
@@ -125,25 +125,25 @@ export class StreamEncoder {
   }
 
   /**
-   * Emit the ## _summary trailer with final counts. Must be called after all
+   * Emit the ##! summary trailer with final counts. Must be called after all
    * symbols and edges have been written.
    */
   close(): void {
-    const sections: string[] = [];
+    const deferredCounts: number[] = [];
     const groupOrder = ['targets', 'related', 'extended'];
 
     for (const g of groupOrder) {
       const c = this.groupCounts.get(g);
-      if (c && c > 0) sections.push(`${g}:${c}`);
+      if (c && c > 0) deferredCounts.push(c);
     }
     for (const [g, c] of this.groupCounts) {
-      if (!groupOrder.includes(g) && c > 0) sections.push(`${g}:${c}`);
+      if (!groupOrder.includes(g) && c > 0) deferredCounts.push(c);
     }
     if (this.edgeCount > 0) {
-      sections.push(`edges:${this.edgeCount}`);
+      deferredCounts.push(this.edgeCount);
     }
 
-    this.w.write(`## _summary symbols=${this.nextID} edges=${this.edgeCount} sections=${sections.join(',')}\n`);
+    this.w.write(`##! summary symbols=${this.nextID} edges=${this.edgeCount} counts=${deferredCounts.join(',')}\n`);
   }
 
   /** Number of symbols written so far. */

package/src/stream_generic.ts

@@ -1,4 +1,5 @@
 import type { StreamWriter } from './stream.js';
+import { formatScalar } from './scalar.js';
 
 interface SectionCount {
   name: string;
@@ -78,7 +79,7 @@ export class GenericStreamEncoder {
     this.writer.write(`${name}[${values.length}]: ${parts.join(',')}\n`);
   }
 
-  /** Emit the ## _summary trailer with final counts. Must be called after all data. */
+  /** Emit the ##! summary trailer with final counts. Must be called after all data. */
   close(): void {
     if (this.current !== null) {
       this.endArrayInternal();
@@ -86,13 +87,8 @@ export class GenericStreamEncoder {
     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`);
+    const counts = this.sections.map(s => String(s.count));
+    this.writer.write(`##! summary counts=${counts.join(',')}\n`);
   }
 
   private endArrayInternal(): void {
@@ -105,23 +101,5 @@ export class GenericStreamEncoder {
 }
 
 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);
+  return formatScalar(v, 0x7c); // '|' context
 }