@shrkcrft/compress 0.1.0-alpha.16

package/dist/table/apply-value-dictionaries.js

@@ -0,0 +1,99 @@
+/**
+ * Per-column value-dictionary (enum) encoding for the columnar table — a
+ * lossless token reduction for low-cardinality columns. The columnar form
+ * already hoists the schema (column names written once), but a column like the
+ * knowledge graph's `kind`/`relation`/`source` still writes its value once per
+ * row. This pass replaces those repeats with a one-time dictionary plus a small
+ * integer index per row.
+ *
+ * Disambiguation: a cell is a dict INDEX iff its column name is a key of the
+ * returned `dict` (decided structurally, never by the cell's value/type), so a
+ * literal-number column and a dict-encoded numeric enum never collide. Absent
+ * cells get no index (they stay in `absent` and are skipped before any deref).
+ *
+ * Pure and deterministic (dict values in first-appearance order). Two guards
+ * ensure it NEVER inflates: a per-column byte check, and a table-level byte
+ * fallback that returns the dict-free rows when the dict didn't actually shrink.
+ */
+/** Minimum present cells in a column before a dictionary can pay for itself. */
+const MIN_DICT_CELLS = 4;
+/** Cheap cap on distinct values; the byte net-check is the real gate. */
+const MAX_DICT_CARDINALITY = 64;
+/** Canonical structural identity of a JSON value (absent cells are pre-filtered). */
+function canon(value) {
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * Dictionary-encode every low-cardinality column that strictly shrinks. Returns
+ * the (possibly unchanged) rows and an optional `dict`. The input `rows` is
+ * never mutated — it is cloned lazily only if a column is encoded.
+ */
+export function applyValueDictionaries(cols, rows, absent) {
+    const width = cols.length;
+    if (width === 0 || rows.length < MIN_DICT_CELLS)
+        return { rows: rows };
+    const absentSet = new Set(absent.map(([r, c]) => r * width + c));
+    const dict = {};
+    let newRows = null;
+    for (let c = 0; c < width; c += 1) {
+        const name = cols[c];
+        // Present cells for this column, ascending row order, with canonical keys.
+        const presentRows = [];
+        const presentKeys = [];
+        for (let r = 0; r < rows.length; r += 1) {
+            if (absentSet.has(r * width + c))
+                continue;
+            presentRows.push(r);
+            presentKeys.push(canon(rows[r][c]));
+        }
+        if (presentRows.length < MIN_DICT_CELLS)
+            continue;
+        // Intern distinct values in first-appearance order; record each cell's index.
+        const indexOf = new Map();
+        const values = [];
+        const indices = [];
+        for (let i = 0; i < presentRows.length; i += 1) {
+            const key = presentKeys[i];
+            let idx = indexOf.get(key);
+            if (idx === undefined) {
+                idx = values.length;
+                indexOf.set(key, idx);
+                values.push(rows[presentRows[i]][c]);
+            }
+            indices.push(idx);
+        }
+        const k = values.length;
+        if (k > MAX_DICT_CARDINALITY || k >= presentRows.length)
+            continue;
+        // Per-column net check (exact bytes). The rows structure (commas/brackets)
+        // is identical either way, so only the per-cell value vs index bytes plus
+        // the new `"name":[…]` dict entry matter.
+        let inlineBytes = 0;
+        let indexBytes = 0;
+        for (let i = 0; i < presentRows.length; i += 1) {
+            inlineBytes += presentKeys[i].length;
+            indexBytes += String(indices[i]).length;
+        }
+        const dictEntryBytes = JSON.stringify(name).length + JSON.stringify(values).length + 2;
+        if (indexBytes + dictEntryBytes >= inlineBytes)
+            continue;
+        // Commit: rewrite this column's cells to indices (absent cells → unread 0).
+        if (!newRows)
+            newRows = rows.map((row) => row.slice());
+        for (let i = 0; i < presentRows.length; i += 1)
+            newRows[presentRows[i]][c] = indices[i];
+        for (let r = 0; r < rows.length; r += 1)
+            if (absentSet.has(r * width + c))
+                newRows[r][c] = 0;
+        dict[name] = values;
+    }
+    if (!newRows)
+        return { rows: rows };
+    // Table-level byte fallback: account for the shared `,"dict":{…}` wrapper that
+    // the per-column check doesn't. If the dict didn't actually shrink the table,
+    // ship the dict-free rows so the encoding can never inflate.
+    const withDict = JSON.stringify(newRows).length + JSON.stringify(dict).length + 8;
+    if (withDict >= JSON.stringify(rows).length)
+        return { rows: rows };
+    return { rows: newRows, dict };
+}

package/dist/table/column-presence.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared column-presence logic for the homogeneous-shape compactors
+ * ({@link compactObjectArray}, {@link compactObjectMap}). Hoisting a schema out
+ * of every record only pays off when most columns are present on most records;
+ * these pure helpers compute that gate and order the columns deterministically,
+ * keeping the threshold tuning in one place.
+ */
+/** True for a plain (non-array, non-null) object — the only shape these compactors hoist. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Count, per key, how many records have it set (undefined counts as absent, per JSON). */
+export declare function buildPresenceMap(records: ReadonlyArray<Record<string, unknown>>): Map<string, number>;
+/**
+ * Whether columns are broadly-enough shared that hoisting a schema is worth it:
+ * a non-empty presence map where ≥ `CORE_RATIO` of columns are present on ≥
+ * `CORE_PRESENCE` of the records.
+ */
+export declare function passesHeterogeneityGate(presence: Map<string, number>, recordCount: number): boolean;
+/** Deterministic column order: most-present first, ties broken by name. */
+export declare function sortColumnsByPresence(presence: Map<string, number>): string[];
+//# sourceMappingURL=column-presence.d.ts.map

package/dist/table/column-presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-presence.d.ts","sourceRoot":"","sources":["../../src/table/column-presence.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,6FAA6F;AAC7F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC9C,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASrB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,WAAW,EAAE,MAAM,GAClB,OAAO,CAMT;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAO7E"}

package/dist/table/column-presence.js

@@ -0,0 +1,52 @@
+/**
+ * Shared column-presence logic for the homogeneous-shape compactors
+ * ({@link compactObjectArray}, {@link compactObjectMap}). Hoisting a schema out
+ * of every record only pays off when most columns are present on most records;
+ * these pure helpers compute that gate and order the columns deterministically,
+ * keeping the threshold tuning in one place.
+ */
+/** A column is "core" when present on at least this fraction of records. */
+const CORE_PRESENCE = 0.8;
+/** Compaction only helps when at least this fraction of columns are core. */
+const CORE_RATIO = 0.5;
+/** True for a plain (non-array, non-null) object — the only shape these compactors hoist. */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Count, per key, how many records have it set (undefined counts as absent, per JSON). */
+export function buildPresenceMap(records) {
+    const presence = new Map();
+    for (const record of records) {
+        for (const key of Object.keys(record)) {
+            if (record[key] === undefined)
+                continue;
+            presence.set(key, (presence.get(key) ?? 0) + 1);
+        }
+    }
+    return presence;
+}
+/**
+ * Whether columns are broadly-enough shared that hoisting a schema is worth it:
+ * a non-empty presence map where ≥ `CORE_RATIO` of columns are present on ≥
+ * `CORE_PRESENCE` of the records.
+ */
+export function passesHeterogeneityGate(presence, recordCount) {
+    if (presence.size === 0)
+        return false;
+    const coreThreshold = recordCount * CORE_PRESENCE;
+    let coreCols = 0;
+    for (const count of presence.values())
+        if (count >= coreThreshold)
+            coreCols += 1;
+    return coreCols / presence.size >= CORE_RATIO;
+}
+/** Deterministic column order: most-present first, ties broken by name. */
+export function sortColumnsByPresence(presence) {
+    return [...presence.keys()].sort((a, b) => {
+        const pa = presence.get(a) ?? 0;
+        const pb = presence.get(b) ?? 0;
+        if (pa !== pb)
+            return pb - pa;
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+}

package/dist/table/columnar-json.d.ts

@@ -0,0 +1,24 @@
+import type { ITableCompaction } from './table-compaction.js';
+import type { IColumnarTable } from './columnar-table.js';
+/**
+ * Encode a compacted table as a valid-JSON columnar object. Only the fields a
+ * decoder needs are emitted — `cols`, `rows`, `absent` (and an optional `dict`).
+ * The per-column type hints and the source count (== `rows.length`) are
+ * encoder-side only and never read off the wire, so they're omitted to save
+ * tokens. Low-cardinality columns are value-dictionary encoded (never inflates).
+ */
+export declare function tableToColumnar(table: ITableCompaction): IColumnarTable;
+/**
+ * Compact an object array straight to columnar JSON, or `null` if it doesn't
+ * qualify. Convenience for the common "compact this list for output" path.
+ */
+export declare function compactArrayToColumnar(items: unknown): IColumnarTable | null;
+/** Type guard: is `value` a columnar table envelope? */
+export declare function isColumnarTable(value: unknown): value is IColumnarTable;
+/**
+ * Reconstruct the original object array from a columnar envelope. Inverse of
+ * {@link tableToColumnar} ∘ {@link compactObjectArray} up to JSON semantics
+ * (an absent key stays absent; key order is not significant).
+ */
+export declare function expandColumnar(table: IColumnarTable): Array<Record<string, unknown>>;
+//# sourceMappingURL=columnar-json.d.ts.map

package/dist/table/columnar-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnar-json.d.ts","sourceRoot":"","sources":["../../src/table/columnar-json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,CAWvE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAG5E;AAED,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAYvE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAiCpF"}

package/dist/table/columnar-json.js

@@ -0,0 +1,83 @@
+import { compactObjectArray } from "./compact-object-array.js";
+import { applyValueDictionaries } from "./apply-value-dictionaries.js";
+/**
+ * Encode a compacted table as a valid-JSON columnar object. Only the fields a
+ * decoder needs are emitted — `cols`, `rows`, `absent` (and an optional `dict`).
+ * The per-column type hints and the source count (== `rows.length`) are
+ * encoder-side only and never read off the wire, so they're omitted to save
+ * tokens. Low-cardinality columns are value-dictionary encoded (never inflates).
+ */
+export function tableToColumnar(table) {
+    const cols = table.cols.map((c) => c.name);
+    const { rows, dict } = applyValueDictionaries(cols, table.rows, table.absent);
+    return {
+        _table: {
+            cols,
+            rows,
+            absent: table.absent,
+            ...(dict ? { dict } : {}),
+        },
+    };
+}
+/**
+ * Compact an object array straight to columnar JSON, or `null` if it doesn't
+ * qualify. Convenience for the common "compact this list for output" path.
+ */
+export function compactArrayToColumnar(items) {
+    const table = compactObjectArray(items);
+    return table ? tableToColumnar(table) : null;
+}
+/** Type guard: is `value` a columnar table envelope? */
+export function isColumnarTable(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const t = value._table;
+    if (typeof t !== 'object' || t === null)
+        return false;
+    const r = t;
+    return (Array.isArray(r.cols) &&
+        Array.isArray(r.rows) &&
+        Array.isArray(r.absent) &&
+        (r.dict === undefined ||
+            (typeof r.dict === 'object' && r.dict !== null && !Array.isArray(r.dict))));
+}
+/**
+ * Reconstruct the original object array from a columnar envelope. Inverse of
+ * {@link tableToColumnar} ∘ {@link compactObjectArray} up to JSON semantics
+ * (an absent key stays absent; key order is not significant).
+ */
+export function expandColumnar(table) {
+    const { cols, rows, absent, dict } = table._table;
+    const width = cols.length;
+    const absentSet = new Set(absent.map(([r, c]) => r * width + c));
+    const out = [];
+    for (let r = 0; r < rows.length; r += 1) {
+        const row = rows[r] ?? [];
+        const obj = {};
+        for (let c = 0; c < width; c += 1) {
+            if (absentSet.has(r * width + c))
+                continue;
+            const name = cols[c];
+            if (name === undefined)
+                continue;
+            // A dict-encoded column holds an index into dict[name]; deref it. `hasOwnProperty`
+            // (not `in`) so a column literally named "toString" only matches a real own key.
+            const raw = row[c];
+            const value = dict && Object.prototype.hasOwnProperty.call(dict, name)
+                ? dict[name][raw]
+                : raw;
+            // `obj[name] = …` would invoke the Object.prototype `__proto__` setter
+            // for a column literally named "__proto__" (a real own key after
+            // JSON.parse), silently dropping it and breaking the lossless guarantee.
+            // defineProperty always creates an own enumerable data property.
+            Object.defineProperty(obj, name, {
+                value,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        out.push(obj);
+    }
+    return out;
+}

package/dist/table/columnar-table.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Valid-JSON columnar encoding of a compacted table. Unlike the dense text
+ * form ({@link renderTable}), this stays parseable JSON — a programmatic
+ * client can reconstruct the original objects with {@link expandColumnar} —
+ * while still deduplicating the schema out of every row. This is what shrk's
+ * MCP tools emit so JSON-parsing agents keep working.
+ */
+export interface IColumnarTable {
+    _table: {
+        /** Column names, in schema order. */
+        cols: string[];
+        /** Row-major values; `rows[r][c]` aligns to `cols[c]`. */
+        rows: unknown[][];
+        /** `[row, col]` positions whose key was absent on the source object. */
+        absent: Array<[number, number]>;
+        /**
+         * Optional per-column value dictionaries (low-cardinality de-duplication).
+         * When a column name is a key here, that column's cells in `rows` are
+         * integer indices into `dict[name]` — deref to recover the real value.
+         */
+        dict?: Record<string, unknown[]>;
+    };
+}
+//# sourceMappingURL=columnar-table.d.ts.map

package/dist/table/columnar-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnar-table.d.ts","sourceRoot":"","sources":["../../src/table/columnar-table.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE;QACN,qCAAqC;QACrC,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,0DAA0D;QAC1D,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;QAClB,wEAAwE;QACxE,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAChC;;;;WAIG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;KAClC,CAAC;CACH"}

package/dist/table/columnar-table.js

@@ -0,0 +1 @@
+export {};

package/dist/table/compact-object-array.d.ts

@@ -0,0 +1,12 @@
+import type { ITableCompaction } from './table-compaction.js';
+/**
+ * Compact a homogeneous array of objects into a lossless columnar table.
+ * Returns `null` when the input doesn't qualify (too few rows, non-objects,
+ * or too heterogeneous to benefit). A JSON value (`undefined` treated as an
+ * absent key, matching JSON semantics) round-trips exactly through
+ * {@link expandColumnar}.
+ *
+ * Deterministic: columns are ordered by descending presence, then by name.
+ */
+export declare function compactObjectArray(items: unknown): ITableCompaction | null;
+//# sourceMappingURL=compact-object-array.d.ts.map

package/dist/table/compact-object-array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact-object-array.d.ts","sourceRoot":"","sources":["../../src/table/compact-object-array.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAqC9D;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAwC1E"}

package/dist/table/compact-object-array.js

@@ -0,0 +1,88 @@
+import { isPlainObject, buildPresenceMap, passesHeterogeneityGate, sortColumnsByPresence, } from "./column-presence.js";
+/** Minimum rows before a table is worth its schema header. */
+const MIN_ROWS = 2;
+function inferType(values) {
+    let sawNonNull = false;
+    let allBool = true;
+    let allInt = true;
+    let allNumber = true;
+    let allString = true;
+    for (const v of values) {
+        if (v === null || v === undefined)
+            continue;
+        sawNonNull = true;
+        if (typeof v !== 'boolean')
+            allBool = false;
+        if (typeof v !== 'number') {
+            allInt = false;
+            allNumber = false;
+        }
+        else if (!Number.isInteger(v)) {
+            allInt = false;
+        }
+        if (typeof v !== 'string')
+            allString = false;
+    }
+    if (!sawNonNull)
+        return 'null';
+    if (allBool)
+        return 'bool';
+    if (allInt)
+        return 'int';
+    if (allNumber)
+        return 'float';
+    if (allString)
+        return 'str';
+    return 'json';
+}
+/**
+ * Compact a homogeneous array of objects into a lossless columnar table.
+ * Returns `null` when the input doesn't qualify (too few rows, non-objects,
+ * or too heterogeneous to benefit). A JSON value (`undefined` treated as an
+ * absent key, matching JSON semantics) round-trips exactly through
+ * {@link expandColumnar}.
+ *
+ * Deterministic: columns are ordered by descending presence, then by name.
+ */
+export function compactObjectArray(items) {
+    if (!Array.isArray(items) || items.length < MIN_ROWS)
+        return null;
+    for (const item of items)
+        if (!isPlainObject(item))
+            return null;
+    const rowsIn = items;
+    // Column presence + heterogeneity gate (shared with the object-map compactor).
+    const presence = buildPresenceMap(rowsIn);
+    if (!passesHeterogeneityGate(presence, rowsIn.length))
+        return null;
+    const colNames = sortColumnsByPresence(presence);
+    const rows = [];
+    const absent = [];
+    for (let r = 0; r < rowsIn.length; r += 1) {
+        const item = rowsIn[r];
+        const row = [];
+        for (let c = 0; c < colNames.length; c += 1) {
+            const key = colNames[c];
+            const present = key in item && item[key] !== undefined;
+            if (!present) {
+                absent.push([r, c]);
+                row.push(null);
+            }
+            else {
+                row.push(item[key]);
+            }
+        }
+        rows.push(row);
+    }
+    const cols = colNames.map((name, c) => {
+        const columnValues = rows.map((row) => row[c]);
+        const presentCount = presence.get(name) ?? 0;
+        const hasNull = columnValues.some((v) => v === null);
+        return {
+            name,
+            type: inferType(columnValues),
+            nullable: presentCount < rowsIn.length || hasNull,
+        };
+    });
+    return { cols, rows, absent, originalCount: rowsIn.length };
+}

package/dist/table/field-spec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * One column of a compacted table — its name plus coarse type/nullability
+ * hints lifted out of the rows so they aren't repeated per row.
+ */
+export interface IFieldSpec {
+    /** Column (object key) name. */
+    name: string;
+    /** Coarse type hint: `bool` | `int` | `float` | `str` | `json` | `null`. */
+    type: string;
+    /** True when at least one source object omits the key or has it null. */
+    nullable: boolean;
+}
+//# sourceMappingURL=field-spec.d.ts.map

package/dist/table/field-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-spec.d.ts","sourceRoot":"","sources":["../../src/table/field-spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;CACnB"}

package/dist/table/field-spec.js

@@ -0,0 +1 @@
+export {};

package/dist/table/object-map.d.ts

@@ -0,0 +1,28 @@
+/** The hoisted form of a homogeneous keyed object. */
+export interface IObjectMap {
+    /** The map's own keys, in original insertion order. */
+    keys: string[];
+    /** Hoisted field names, ordered by descending presence then name. */
+    cols: string[];
+    /** `rows[i][c]` is entry `keys[i]`'s value for `cols[c]` (null when absent). */
+    rows: unknown[][];
+    /** `[i, c]` pairs whose key was absent on that entry (distinguishes null vs missing). */
+    absent: Array<[number, number]>;
+}
+/**
+ * Compact a homogeneous keyed object into a columnar {@link IObjectMap}, or
+ * return `null` when it doesn't qualify (not a plain object, too few entries,
+ * a non-object value, or too heterogeneous to benefit). Deterministic.
+ */
+export declare function compactObjectMap(value: unknown): IObjectMap | null;
+/** True when `value` is a `{ _omap: IObjectMap }` envelope. */
+export declare function isObjectMap(value: unknown): value is {
+    _omap: IObjectMap;
+};
+/**
+ * Inverse of {@link compactObjectMap}: rebuild the original keyed object.
+ * Accepts either a bare {@link IObjectMap} or a `{ _omap }` envelope. Returns
+ * `null` when the input isn't a valid object map.
+ */
+export declare function expandObjectMap(value: unknown): Record<string, unknown> | null;
+//# sourceMappingURL=object-map.d.ts.map

package/dist/table/object-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-map.d.ts","sourceRoot":"","sources":["../../src/table/object-map.ts"],"names":[],"mappings":"AAyBA,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qEAAqE;IACrE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gFAAgF;IAChF,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAClB,yFAAyF;IACzF,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAmClE;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI;IAAE,KAAK,EAAE,UAAU,CAAA;CAAE,CAU1E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAmB9E"}

package/dist/table/object-map.js

@@ -0,0 +1,119 @@
+/**
+ * Lossless columnar compaction for an OBJECT keyed by id whose values share a
+ * schema — a very common API/registry shape (`{ n1:{kind,score}, n2:{…}, … }`)
+ * that {@link compactObjectArray} (arrays only) leaves untouched. The shared
+ * field names are hoisted out of every entry into `cols`, written once; each
+ * entry becomes a positional `rows[i]` aligned to its key in `keys[i]`. Absent
+ * keys are tracked in `absent` so `null`-vs-absent round-trips exactly.
+ *
+ * The encoding is still valid JSON and exactly reconstructable via
+ * {@link expandObjectMap}: `null`, absent keys, and all JSON values round-trip
+ * exactly. A property whose value is `undefined` is treated as absent — matching
+ * `JSON.stringify` and {@link compactObjectArray} — since `undefined` is not a
+ * JSON value and cannot survive any JSON envelope. Net-loss is guarded by the
+ * caller (`compressJson`).
+ */
+import { isPlainObject, buildPresenceMap, passesHeterogeneityGate, sortColumnsByPresence, } from "./column-presence.js";
+/** Minimum keyed entries before the hoisted schema pays for itself. */
+const MIN_ENTRIES = 2;
+/**
+ * Compact a homogeneous keyed object into a columnar {@link IObjectMap}, or
+ * return `null` when it doesn't qualify (not a plain object, too few entries,
+ * a non-object value, or too heterogeneous to benefit). Deterministic.
+ */
+export function compactObjectMap(value) {
+    if (!isPlainObject(value))
+        return null;
+    const keys = Object.keys(value);
+    if (keys.length < MIN_ENTRIES)
+        return null;
+    const entries = [];
+    for (const key of keys) {
+        const v = value[key];
+        if (!isPlainObject(v))
+            return null;
+        entries.push(v);
+    }
+    // Column presence + heterogeneity gate (shared with the array compactor).
+    const presence = buildPresenceMap(entries);
+    if (!passesHeterogeneityGate(presence, entries.length))
+        return null;
+    const cols = sortColumnsByPresence(presence);
+    const rows = [];
+    const absent = [];
+    for (let r = 0; r < entries.length; r += 1) {
+        const entry = entries[r];
+        const row = [];
+        for (let c = 0; c < cols.length; c += 1) {
+            const key = cols[c];
+            if (key in entry && entry[key] !== undefined) {
+                row.push(entry[key]);
+            }
+            else {
+                absent.push([r, c]);
+                row.push(null);
+            }
+        }
+        rows.push(row);
+    }
+    return { keys, cols, rows, absent };
+}
+/** True when `value` is a `{ _omap: IObjectMap }` envelope. */
+export function isObjectMap(value) {
+    if (!isPlainObject(value))
+        return false;
+    const m = value._omap;
+    return (isPlainObject(m) &&
+        Array.isArray(m.keys) &&
+        Array.isArray(m.cols) &&
+        Array.isArray(m.rows) &&
+        Array.isArray(m.absent));
+}
+/**
+ * Inverse of {@link compactObjectMap}: rebuild the original keyed object.
+ * Accepts either a bare {@link IObjectMap} or a `{ _omap }` envelope. Returns
+ * `null` when the input isn't a valid object map.
+ */
+export function expandObjectMap(value) {
+    const map = isObjectMap(value)
+        ? value._omap
+        : isBareObjectMap(value)
+            ? value
+            : undefined;
+    if (!map)
+        return null;
+    const absent = new Set(map.absent.map(([r, c]) => `${r},${c}`));
+    const out = {};
+    for (let r = 0; r < map.keys.length; r += 1) {
+        const obj = {};
+        for (let c = 0; c < map.cols.length; c += 1) {
+            if (absent.has(`${r},${c}`))
+                continue;
+            setOwn(obj, map.cols[c], map.rows[r]?.[c]);
+        }
+        setOwn(out, map.keys[r], obj);
+    }
+    return out;
+}
+/**
+ * Assign an own enumerable data property. Plain `obj[key] = value` would invoke
+ * the `Object.prototype.__proto__` setter for a column name or map key literally
+ * equal to `"__proto__"` (a real own key after `JSON.parse`), silently dropping
+ * the value and breaking the lossless round-trip. The array path
+ * ({@link expandColumnar}) hardens against this the same way.
+ */
+function setOwn(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+}
+function isBareObjectMap(value) {
+    return (isPlainObject(value) &&
+        Array.isArray(value.keys) &&
+        Array.isArray(value.cols) &&
+        Array.isArray(value.rows) &&
+        Array.isArray(value.absent));
+}

package/dist/table/render-table.d.ts

@@ -0,0 +1,11 @@
+import type { ITableCompaction } from './table-compaction.js';
+/**
+ * Render a compacted table as a dense, model-readable text block. The header
+ * lifts the schema once (`name?` marks a nullable column); rows are
+ * pipe-delimited values with the delimiter / newlines / backslashes escaped.
+ * This is the densest representation — used by `shrk compress` and the
+ * `compress_context` tool, where the consumer reads text rather than parsing
+ * JSON. For a parseable form, use {@link tableToColumnar}.
+ */
+export declare function renderTable(table: ITableCompaction): string;
+//# sourceMappingURL=render-table.d.ts.map

package/dist/table/render-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-table.d.ts","sourceRoot":"","sources":["../../src/table/render-table.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA0B9D;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAS3D"}

package/dist/table/render-table.js

@@ -0,0 +1,39 @@
+const CELL_DELIM = '|';
+function escapeCell(text) {
+    return text
+        .replace(/\\/g, '\\\\')
+        .replace(/\|/g, '\\|')
+        .replace(/\r?\n/g, '\\n');
+}
+// Column names are arbitrary object keys (anything after JSON.parse), so the
+// header must escape the same chars as a cell PLUS the `,` separator and the
+// trailing-`?` nullable marker — otherwise a key like `a,b` or `a\n` or `a?`
+// would shatter or misrepresent the schema line.
+function escapeHeaderName(name) {
+    return escapeCell(name).replace(/,/g, '\\,').replace(/\?/g, '\\?');
+}
+function renderCell(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'string')
+        return escapeCell(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return escapeCell(JSON.stringify(value) ?? '');
+}
+/**
+ * Render a compacted table as a dense, model-readable text block. The header
+ * lifts the schema once (`name?` marks a nullable column); rows are
+ * pipe-delimited values with the delimiter / newlines / backslashes escaped.
+ * This is the densest representation — used by `shrk compress` and the
+ * `compress_context` tool, where the consumer reads text rather than parsing
+ * JSON. For a parseable form, use {@link tableToColumnar}.
+ */
+export function renderTable(table) {
+    const head = `⟦table n=${table.originalCount} c=${table.cols.length}⟧`;
+    const schema = table.cols
+        .map((c) => (c.nullable ? `${escapeHeaderName(c.name)}?` : escapeHeaderName(c.name)))
+        .join(',');
+    const lines = table.rows.map((row) => table.cols.map((_, c) => renderCell(row[c])).join(CELL_DELIM));
+    return [head, schema, ...lines].join('\n');
+}