fix: toCode() join/set-op missing tableFn prefix; add docs and 4 new tests

- Fix extractChainBody to preserve the tableFn (e.g. "qm") prefix in nested
  join and set operation code generation (was producing invalid bare ".table()")
- Add toCode/toDescriptor to terminal methods table in dataframe-api docs
- Add dedicated "Query decompilation" section with examples to dataframe-api docs
- Update README to mention .toCode() decompiler
- 4 new tests: join tableFn prefix, set-op tableFn prefix, special char escaping,
  multiple windows

Author: teamchong

README.md

@@ -243,7 +243,7 @@ npx tsx examples/nextjs-api-route.ts
 
 - **TypeScript orchestration** — Durable Object lifecycle, R2 range reads, footer caching, request routing
 - **Zig WASM engine** (`wasm/`) — column decoding, SIMD ops, SQL execution, vector search, fragment writing, compiles to `querymode.wasm`
-- **Code-first query API** — `.table().filter().select().sort().limit().exec()` or `.sql("SELECT ...")`
+- **Code-first query API** — `.table().filter().select().sort().limit().exec()` or `.sql("SELECT ...")`, with `.toCode()` decompiler for logging and LLM context compression
 - **Write path** — `append(rows, { path, metadata })` with CAS-based manifest coordination via Master DO, `dropTable()` for cleanup
 - **Master/Query DO split** — single-writer Master broadcasts footer invalidations to per-region Query DOs
 - **Footer caching** — table footers (~4KB each) cached in DO memory with VIP eviction (hot tables protected from eviction)

docs/src/content/docs/dataframe-api.mdx

@@ -172,6 +172,8 @@ These execute the query and return results:
 | `stream(batchSize)` | `AsyncGenerator<Row[]>` | Async generator over result batches |
 | `cursor({ batchSize })` | `AsyncIterable<Row[]>` | Async iterable over batches |
 | `materialize()` | `DataFrame` | Execute and re-wrap as in-memory DataFrame |
+| `toCode(opts?)` | `string` | Convert query to fluent builder TypeScript code |
+| `toDescriptor()` | `QueryDescriptor` | Serializable query plan (JSON) |
 | `append(rows, opts?)` | `AppendResult` | Write rows (CAS-coordinated) |
 | `dropTable()` | `DropResult` | Delete table and all fragments |
 
@@ -202,6 +204,45 @@ const csv = await df.toCSV({ delimiter: "\t" })
 
 These are all sugar over existing methods — `shape()` calls `explain()`, `valueCounts()` uses `groupBy().aggregate()`, `fillNull()` and `cast()` use `computed()`.
 
+## Query decompilation (toCode)
+
+Convert any query back to readable, copy-pasteable fluent builder TypeScript. Useful for logging, debugging, and LLM context compression (~50x smaller than raw QueryDescriptor JSON).
+
+```typescript
+const df = qm
+  .table("orders")
+  .filter("category", "eq", "Electronics")
+  .filter("amount", "gte", 100)
+  .select("id", "amount", "region")
+  .sort("amount", "desc")
+  .limit(20)
+
+console.log(df.toCode())
+// const result = await qm
+//   .table("orders")
+//   .filter("category", "eq", "Electronics")
+//   .filter("amount", "gte", 100)
+//   .select("id", "amount", "region")
+//   .sort("amount", "desc")
+//   .limit(20)
+//   .collect()
+```
+
+Customize the output variable name and table function:
+
+```typescript
+df.toCode({ variableName: "data", tableFn: "db" })
+// const data = await db
+//   .table("orders")
+//   ...
+
+// Or use the static method on a raw descriptor:
+import { descriptorToCode } from "querymode"
+descriptorToCode(someDescriptor)
+```
+
+Handles all features: filters (all 14 ops with shorthand methods), aggregates, groupBy, joins, window functions, set operations, vector search, distinct, sort, limit/offset, version, cache, computed columns, pipe stages.
+
 ## Progress tracking
 
 For long-running queries, track progress with a callback:

src/descriptor-to-code.test.ts

@@ -225,6 +225,19 @@ describe("descriptorToCode", () => {
     expect(code).toContain('"left"');
   });
 
+  it("join — right side has tableFn prefix (not bare .table())", () => {
+    const code = descriptorToCode(makeDesc({
+      join: {
+        right: makeDesc({ table: "users" }),
+        leftKey: "user_id",
+        rightKey: "id",
+        type: "left",
+      },
+    }));
+    // The join argument must start with "qm" (or custom tableFn), not bare ".table()"
+    expect(code).toMatch(/\.join\(\s*\n\s*qm\s*\n/);
+  });
+
   it("join — inner (default) omits type", () => {
     const code = descriptorToCode(makeDesc({
       join: {
@@ -246,6 +259,13 @@ describe("descriptorToCode", () => {
     expect(code).toContain('.table("archive_orders")');
   });
 
+  it("set operation — right side has tableFn prefix", () => {
+    const code = descriptorToCode(makeDesc({
+      setOperation: { mode: "union", right: makeDesc({ table: "archive" }) },
+    }), { tableFn: "db" });
+    expect(code).toMatch(/\.union\(\s*\n\s*db\s*\n/);
+  });
+
   it("set operation — union all", () => {
     const code = descriptorToCode(makeDesc({
       setOperation: { mode: "union_all", right: makeDesc({ table: "archive" }) },
@@ -386,6 +406,26 @@ describe("descriptorToCode", () => {
     expect(code).toContain(".limit(0)");
   });
 
+  it("string values with special characters are properly escaped", () => {
+    const code = descriptorToCode(makeDesc({
+      filters: [{ column: "name", op: "eq", value: 'O\'Brien "Bob"' }],
+    }));
+    expect(code).toContain('.filter("name", "eq", "O\'Brien \\"Bob\\"")');
+  });
+
+  it("multiple windows produce multiple .window() calls", () => {
+    const code = descriptorToCode(makeDesc({
+      windows: [
+        { fn: "row_number", partitionBy: ["a"], orderBy: [{ column: "b", direction: "asc" }], alias: "rn" },
+        { fn: "sum", column: "val", partitionBy: ["a"], orderBy: [], alias: "running_sum" },
+      ],
+    }));
+    const windowMatches = code.match(/\.window\(/g);
+    expect(windowMatches).toHaveLength(2);
+    expect(code).toContain('alias: "rn"');
+    expect(code).toContain('alias: "running_sum"');
+  });
+
   it("offset 0 is NOT emitted (falsy)", () => {
     const code = descriptorToCode(makeDesc({ offset: 0 }));
     expect(code).not.toContain(".offset(");

src/descriptor-to-code.ts

@@ -176,10 +176,15 @@ export function descriptorToCode(
 
 /** Extract the fluent chain body from generated code (strips variable declaration and terminal). */
 function extractChainBody(code: string): string {
-  return code.split("\n")
-    .map(l => l.trim())
-    .filter(l => l && !l.startsWith("const ") && l !== ".collect()")
-    .join("\n    ");
+  // Strip "const <var> = await " prefix and trailing ".collect()"
+  const awaitIdx = code.indexOf("await ");
+  const body = awaitIdx >= 0 ? code.slice(awaitIdx + 6) : code;
+  const lines = body.split("\n").map(l => l.trim()).filter(Boolean);
+  // Remove trailing .collect()
+  if (lines.length > 0 && lines[lines.length - 1] === ".collect()") {
+    lines.pop();
+  }
+  return lines.join("\n    ");
 }
 
 function str(v: unknown): string {