docs(plans): correct spike findings — SDK works via ESM

CJS bug only affects CJS consumers. All dev-agent packages use ESM
("type": "module"), so @antfly/sdk works fine. Use it directly instead
of building a raw fetch() wrapper.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: prosdev

.claude/da-plans/core/phase-1-antfly-migration/1.1-spike-findings.md

@@ -14,7 +14,7 @@
 | 4 | What does `client.tables.get()` return? | Returns table info including `storage_status.disk_usage` (bytes), index configs, and shard info. **No direct doc count** — need to use a query with limit to count. |
 | 5 | Latency of lookup vs vector search? | Lookup is near-instant. Semantic search ~1-2ms for 10 docs. Both fast at this scale. |
 | 6 | Can we full-scan without a query vector? | **Yes** — use the global `/api/v1/query` endpoint with just `table` and `limit`, no `semantic_search`. Returns all docs. |
-| 7 | Does the SDK handle connection errors gracefully? | **SDK has a CJS/ESM interop bug** — `TypeError: (0 , import_openapi_fetch.default) is not a function`. Direct REST API works fine. See SDK issues section below. |
+| 7 | Does the SDK handle connection errors gracefully? | **SDK works fine via ESM** (our default). CJS build has a bug with `openapi-fetch` default export — only affects CJS consumers. See SDK notes below. |
 | 8 | What happens when antfly server is not running? | curl gets `ECONNREFUSED`. Clear and fast failure. |
 | 9 | Does `getAll()` paginate beyond 10000 docs? | Not tested at scale in this spike. The query endpoint accepts `limit` — likely works up to a reasonable size. Need to test with a real repo index. |
 | 10 | Does `dev index` need to wait for embedding completion? | **Yes.** There's a ~2s delay between insert and searchability. For a full index run, we should wait for all embeddings to complete before declaring success. Poll embedding status or add a brief wait. |
@@ -75,28 +75,23 @@ not found. This is a massive improvement over the current `get()` implementation
 `client.tables.get()` returns `storage_status.disk_usage` in bytes. This can replace
 the `storageSize` field in `VectorStats` (currently reads local LanceDB directory).
 
-## SDK Issues
+## SDK Notes
 
-### CJS/ESM interop bug
+### CJS build has a bug (doesn't affect us)
 
-The `@antfly/sdk` v0.0.14 fails when imported in a CJS context (e.g., via `tsx`):
+The SDK's CJS bundle (`dist/index.cjs`) fails because `openapi-fetch` is ESM-only.
+`tsup` wraps it with `__toESM(require("openapi-fetch"))` and accesses `.default`,
+which is `undefined` in CJS context.
 
-```
-TypeError: (0 , import_openapi_fetch.default) is not a function
-```
+**This doesn't affect dev-agent.** All our packages use `"type": "module"` (ESM).
+The ESM import path (`dist/index.js`) works correctly.
 
-The SDK's CJS bundle (`dist/index.cjs`) doesn't correctly handle the `openapi-fetch`
-default export.
+The spike error was from `npx tsx` which loaded the CJS path — not representative
+of our actual runtime.
 
-**Workaround options:**
-1. Use ESM imports only (our packages use ESM anyway)
-2. Use the REST API directly with `fetch()` instead of the SDK
-3. Report the bug to antfly team (the user's friend built it)
-
-**Recommendation:** Start with direct REST API calls via `fetch()`. The SDK is thin
-(just openapi-fetch wrapper) and we need only 6-7 endpoints. Building our own thin
-client gives us full control and avoids SDK version coupling. We can adopt the SDK
-later when it stabilizes (v0.0.x is very early).
+**Recommendation:** Use `@antfly/sdk` directly. It's type-safe, auto-generated from
+OpenAPI spec, and works fine via ESM. Worth mentioning the CJS bug to the antfly
+team (fix: `noExternal: ['openapi-fetch']` in tsup config) for other consumers.
 
 ## Docker Findings
 
@@ -119,7 +114,7 @@ Need to verify Docker image + `swarm` command works end-to-end.
 
 ## Impact on Plan
 
-1. **Use direct REST API instead of SDK** — avoids CJS/ESM bug and early SDK instability
+1. **Use `@antfly/sdk` directly** — ESM works fine, type-safe, auto-generated from OpenAPI
 2. **Model pull: use default variant** (not `--variants i8`) until i8 is fixed
 3. **`dev index` must wait for embeddings** — poll or add brief sleep after batch insert
 4. **Table info provides disk_usage** — can populate `VectorStats.storageSize`