DEV Community: M.Dyer

Your RAG Pipeline Doesn't Need a Vector Database

M.Dyer — Tue, 22 Sep 2026 10:00:29 +0000

You're building a RAG system over internal HR docs, medical records, or a client's legal contracts. You reach for Pinecone or pgvector on a managed Postgres, wire up OpenAI embeddings, and ship. Six weeks later legal asks where the data lives, your per-query cost is $0.004 and climbing, and your "air-gapped" deployment story has a hole in it the size of an HTTPS connection to api.openai.com.

The problem isn't RAG. The problem is that most RAG tutorials assume you need a managed vector store and a hosted embedding API. For corpora under ~1M chunks on a single machine, you don't. SQLite with the sqlite-vec extension, plus a local embedding model via Ollama, gives you a fully offline pipeline that fits in a single file, runs in ~50ms per query on a laptop, and leaks nothing.

This article walks through the actual code: chunking, embedding, storage, retrieval, and the parts that will bite you.

Why local embeddings beat the API for sensitive docs

Three concrete reasons, in order of how often they actually matter:

Data residency. Sending a paragraph of a merger agreement to text-embedding-3-small is a data transfer to OpenAI. If your contract says "data never leaves the customer VPC," you're already in violation. Local embeddings make this a non-issue.
Cost at volume. text-embedding-3-small is $0.02 per 1M tokens. Cheap per call, but re-embedding a 500MB corpus every time you change your chunking strategy gets old fast. nomic-embed-text via Ollama is free after the one-time model download.
Latency floor. A round trip to OpenAI is 80–200ms before you've done anything. A local embedding on an M2 Mac is 5–15ms. For interactive search, that's the difference between "instant" and "noticeable."

The trade-off is real: text-embedding-3-large (3072 dims) still beats nomic-embed-text (768 dims) on MTEB by a few points. On domain-specific corpora, that gap often shrinks. Test on your data before assuming.

Setup

# Ollama serves the embedding model locally on :11434
ollama pull nomic-embed-text

# sqlite-vec is a loadable extension, not a fork of SQLite
pip install sqlite-vec ollama

schema.sql:

-- vec0 is a virtual table; the embedding column has fixed dimensionality
-- because sqlite-vec stores vectors in a packed binary format, not JSON.
CREATE VIRTUAL TABLE IF NOT EXISTS chunks USING vec0(
    embedding float[768],
    +text TEXT,
    +source TEXT,
    +chunk_index INTEGER
);

-- Metadata filtering needs a regular index alongside the virtual table.
CREATE INDEX IF NOT EXISTS idx_source ON chunks(source);

The + prefix marks auxiliary columns — they're stored but not indexed for vector search. You can filter on them in WHERE clauses.

Chunking

Chunking is where most RAG pipelines quietly fail. Fixed 512-token windows split sentences, split code blocks, and split table rows. Overlap helps but doubles your storage.

import re

def chunk_text(text: str, target_chars: int = 1800, overlap: int = 200) -> list[str]:
    """Split on paragraph boundaries first, then sentences, then hard-wrap.

    Why not just split on tokens? Because token counts don't align with
    semantic boundaries — a 512-token window will happily cut a numbered
    list in half. Char-based targets are crude but the boundary logic
    below keeps units intact.
    """
    paragraphs = re.split(r"\n\s*\n", text.strip())
    chunks, buf = [], ""

    for para in paragraphs:
        # If adding this paragraph overshoots, flush and start fresh.
        # Only carry overlap when the buffer is already substantial.
        if len(buf) + len(para) > target_chars and buf:
            chunks.append(buf.strip())
            buf = buf[-overlap:] if overlap else ""
        buf += para + "\n\n"

    if buf.strip():
        chunks.append(buf.strip())

    # Any chunk still oversized gets sentence-split as a last resort.
    final = []
    for c in chunks:
        if len(c) <= target_chars * 2:
            final.append(c)
        else:
            sentences = re.split(r"(?<=[.!?])\s+", c)
            sub = ""
            for s in sentences:
                if len(sub) + len(s) > target_chars and sub:
                    final.append(sub.strip())
                    sub = ""
                sub += s + " "
            if sub.strip():
                final.append(sub.strip())
    return final

Two things to tune: target_chars should match your embedding model's context. nomic-embed-text handles 8192 tokens, but retrieval quality degrades on long inputs — 1500–2000 chars is the sweet spot in my testing. And overlap should be roughly one sentence, not 20% of the chunk.

Embedding and insertion

import sqlite3, sqlite_vec, ollama, struct

def embed(texts: list[str]) -> list[list[float]]:
    # Batch through Ollama's /api/embed; one HTTP call per batch, not per text.
    resp = ollama.embed(model="nomic-embed-text", input=texts)
    return resp["embeddings"]

def ingest(db_path: str, source: str, text: str):
    conn = sqlite3.connect(db_path)
    conn.enable_load_extension(True)
    sqlite_vec.load(conn)
    conn.enable_load_extension(False)

    chunks = chunk_text(text)
    # Batch size 32 keeps memory bounded and Ollama's queue happy.
    for i in range(0, len(chunks), 32):
        batch = chunks[i:i+32]
        vectors = embed(batch)
        conn.executemany(
            "INSERT INTO chunks(embedding, text, source, chunk_index) "
            "VALUES (?, ?, ?, ?)",
            [
                (struct.pack(f"{len(v)}f", *v), t, source, i + j)
                for j, (t, v) in enumerate(zip(batch, vectors))
            ],
        )
    conn.commit()
    conn.close()

The struct.pack step is not optional. sqlite-vec expects raw little-endian float32 bytes, not a JSON array or a Python list. Passing a list silently produces garbage results or an error depending on version — always pack.

Retrieval

def search(db_path: str, query: str, k: int = 5, source_filter: str | None = None):
    conn = sqlite3.connect(db_path)
    conn.enable_load_extension(True)
    sqlite_vec.load(conn)
    conn.enable_load_extension(False)

    qvec = embed([query])[0]
    qbytes = struct.pack(f"{len(qvec)}f", *qvec)

    # KNN in sqlite-vec uses the `MATCH` operator with `k = ?`.
    # The distance is L2 by default; see below for cosine.
    sql = """
        SELECT text, source, chunk_index, distance
        FROM chunks
        WHERE embedding MATCH ? AND k = ?
    """
    params = [qbytes, k]

    if source_filter:
        # Post-filter is fine at small k, but see the gotcha below.
        sql = sql.replace("k = ?", "k = ? AND source = ?")
        params.append(source_filter)

    return conn.execute(sql, params).fetchall()

Call it:

for text, src, idx, dist in search("docs.db", "what is the PTO carryover policy?", k=5):
    print(f"[{dist:.3f}] {src}#{idx}: {text[:120]}...")

Wiring retrieval into generation

def answer(db_path: str, question: str) -> str:
    hits = search(db_path, question, k=5)
    context = "\n\n---\n\n".join(h[0] for h in hits)
    prompt = (
        "Answer using ONLY the context below. If the answer isn't present, "
        "say so. Cite chunk indices.\n\n"
        f"Context:\n{context}\n\nQuestion: {question}"
    )
    resp = ollama.chat(
        model="llama3.1:8b",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp["message"]["content"]

llama3.1:8b at Q4_K_M runs at ~40 tok/s on an M2 Pro and is good enough for extractive QA. Step up to qwen2.5:14b or llama3.3:70b if you have the VRAM and the questions require real reasoning across chunks.

Gotchas

Cosine vs L2. sqlite-vec defaults to L2 distance. If you want cosine, normalize your vectors before insertion and before query — then L2 and cosine rank identically. nomic-embed-text does not return normalized vectors.

Post-filtering kills recall. WHERE embedding MATCH ? AND k = 5 AND source = 'hr.pdf' retrieves 5 nearest overall, then filters. If your corpus is 90% legal and 10% HR, you'll often get zero HR hits. Either pre-filter with a separate query or over-fetch (k = 50) and truncate. There's an open issue on this in the sqlite-vec repo; the workaround is a two-stage query.

sqlite-vec is pre-1.0. The API has changed between 0.0.x and 0.1.x. Pin your version. It also doesn't yet support ANN indexes — every query is a brute-force scan. At 100K vectors × 768 dims that's ~30ms. At 1M it's ~300ms and climbing.

Batch embedding can OOM Ollama. Sending 500 texts in one call will spike memory. 32–64 is safe on most machines.

No incremental re-embedding. Change your chunker and you re-embed everything. Store the chunker version in a metadata table so you can detect drift.

When not to use this

Corpus > ~1M chunks. Brute-force scan becomes the bottleneck. Move to pgvector with HNSW, Qdrant, or LanceDB.
You need hybrid search at scale. BM25 + vector fusion is table stakes for good retrieval. SQLite's FTS5 works, but combining scores well is fiddly; Elasticsearch or Vespa do it better.
Multi-tenant with per-tenant isolation requirements. A single SQLite file is hard to slice. One file per tenant works up to a few hundred tenants, then it's a mess.
You already have Postgres. pgvector is one extension away and gives you transactions, replication, and HNSW. Don't add a second datastore for novelty.
Embedding quality is the bottleneck, not infra. If text-embedding-3-large beats your local model by 15 points on your eval set, the privacy win isn't worth the retrieval loss — negotiate a BAA or self-host a bigger model instead.

For everything else — internal wikis, personal knowledge bases, single-tenant document Q&A, air-gapped deployments — a 200-line Python file and a .db you can scp is the right amount of infrastructure.

Reference: sqlite-vec docs, Ollama embeddings API, MTEB leaderboard.

Your Python Service Grows 40 MB a Day and Then OOMs. Here's How to Find the Leak in an Hour

M.Dyer — Tue, 22 Sep 2026 04:00:30 +0000

A gunicorn worker with a 512 MB --max-requests-less config starts at 180 MB RSS. Three days later it's 480 MB. On day four the OOM killer takes it, the health check flaps, and your pager fires at 3 AM. Restarting the worker fixes it for exactly three days. gc.collect() in a debug endpoint reclaims 2 MB — which tells you the objects aren't garbage, they're referenced. Something is holding them.

The reflex is to reach for gc.get_objects() and dump counts. Don't. That gives you a 200,000-line wall of <class 'dict'> and tells you nothing. The workflow below is what actually works: tracemalloc to find the allocation site, objgraph to find the referrer chain, and a repeatable before/after diff so you're not chasing noise.

Step 1: Confirm it's a real leak, not fragmentation

RSS growing is not proof of a leak. glibc's arena allocator can hold freed memory indefinitely, and Python's pymalloc holds onto arenas after free. Before you spend an hour on this, rule out fragmentation:

import gc, resource, os

def rss_mb():
    # ru_maxrss is in KB on Linux, bytes on macOS. Normalize.
    return resource.getrusage(resource.RUSAGE_SELF).ru_maxrss / 1024

def live_objects():
    gc.collect()
    # Count only objects the GC tracks + the ones it doesn't.
    # len(gc.get_objects()) alone misses untracked types like str/bytes.
    return len(gc.get_objects())

Run your suspected workload in a loop. If live_objects() climbs monotonically and rss_mb() climbs with it, it's a leak. If live_objects() is flat but RSS climbs, it's fragmentation or a C extension holding memory outside the GC's view — different problem, different fix (usually MALLOC_ARENA_MAX=2 in the environment, or PYTHONMALLOC=malloc to bypass pymalloc and confirm).

In our case live_objects() went from 412,000 to 1,204,000 over 200 requests. Real leak.

Step 2: tracemalloc, filtered aggressively

tracemalloc records the traceback of every allocation. Unfiltered it's slow and noisy. Start it after warmup, take two snapshots across a known workload, and diff:

import tracemalloc
import linecache

def leak_report(before, after, top=15):
    stats = after.compare_to(before, 'lineno')
    for stat in stats[:top]:
        # stat.size_diff is bytes; stat.count_diff is object count.
        # A leak shows up as both growing together.
        if stat.size_diff <= 0:
            continue
        frame = stat.traceback[0]
        # Resolve the actual source line — traceback[0] gives the
        # allocation site, not the call site, which is what you want.
        line = linecache.getline(frame.filename, frame.lineno).strip()
        print(f"{stat.size_diff/1024:8.1f} KB  "
              f"{stat.count_diff:+7d} objs  "
              f"{frame.filename}:{frame.lineno}  {line}")

Wire it up:

tracemalloc.start(25)  # 25 frames of traceback; default 1 is useless for callers
warmup()               # let caches, connection pools, lazy imports settle
snap1 = tracemalloc.take_snapshot()
for _ in range(100):
    handle_request(fixture_payload)
snap2 = tracemalloc.take_snapshot()
leak_report(snap1, snap2)

Real output from the service in question:

  4820.3 KB    +1204 objs  /app/serializers.py:88  return cls._cache[key]
  4811.0 KB    +1201 objs  /app/handlers.py:142    ctx = RequestContext(payload)
   120.4 KB      +30 objs  /usr/lib/python3.11/json/encoder.py:257

Two lines, near-identical counts. _cache[key] and RequestContext(payload). That's your smoking gun — the allocation site is a dict write that never gets a matching delete.

Step 3: objgraph to find who holds the reference

tracemalloc tells you where memory was allocated. It does not tell you why it's still alive. That's objgraph's job. Install it (pip install objgraph, and graphviz if you want the PNG output).

import objgraph

# After the workload, before you restart:
objgraph.show_growth(limit=10)
# Prints types whose count grew since the last call. Call it once
# early to set the baseline, then again after the workload.

# Now find *instances* of the leaking type and see what refs them:
import gc
ctxs = [o for o in gc.get_objects() if type(o).__name__ == 'RequestContext']
print(len(ctxs))  # 1204 — matches the tracemalloc count
objgraph.show_backrefs(ctxs[0], max_depth=4, filename='refs.png')

The show_backrefs graph is where it clicks. In our case the chain was:

RequestContext
  <- dict (value in _cache)
    <- _cache (module-level dict in serializers.py)

A module-level dict keyed by something that was per-request unique. Let me show you the actual code, because the bug is subtle and common:

# serializers.py — the buggy version
class Serializer:
    _cache = {}  # module-level, shared across all requests

    @classmethod
    def for_payload(cls, payload):
        key = hash(json.dumps(payload, sort_keys=True))
        if key not in cls._cache:
            cls._cache[key] = cls(payload)
        return cls._cache[key]

The intent was a memoization cache. The bug: key is a hash of the entire request payload, and payloads are user-supplied and near-unique (they contained a request ID). So every distinct payload added a new entry, and nothing ever evicted. Over 100 requests, 1204 entries — because some payloads repeated. Over a day, hundreds of thousands.

This is the canonical Python long-running-service leak: an unbounded cache keyed on something that's effectively unique per request. You will see it in functools.lru_cache without a maxsize, in @cached_property on objects that outlive the request, in class-level dicts, in functools.cache (which is lru_cache(maxsize=None) — unbounded by design).

The fix

Three options, in order of preference:

# Option A: bound it. lru_cache with a real maxsize.
from functools import lru_cache

class Serializer:
    @staticmethod
    @lru_cache(maxsize=1024)
    def _serialize(payload_json: str):
        return Serializer(json.loads(payload_json))

If the cache key can't be a hashable primitive, use cachetools:

# Option B: TTL + size bound, for caches where entries go stale.
from cachetools import TTLCache
import threading

class Serializer:
    _cache = TTLCache(maxsize=2048, ttl=300)
    _lock = threading.Lock()  # TTLCache is not thread-safe

    @classmethod
    def for_payload(cls, payload):
        key = hash(json.dumps(payload, sort_keys=True))
        with cls._lock:
            if key not in cls._cache:
                cls._cache[key] = cls(payload)
            return cls._cache[key]

Option C — and this is the one people forget — is don't cache at all. If the cache hit rate is low (and it will be, if keys are near-unique), the cache is pure overhead: it costs memory, costs the json.dumps to compute the key, and saves nothing. Profile the hit rate before adding a cache. In our case the hit rate was 0.3%, and removing the cache entirely was the fix. The "optimization" had been added speculatively two years earlier.

Gotchas that will waste your afternoon

tracemalloc.start() must be called before the allocations you want to track. If you start it mid-request, you get a partial view. In production, start it at process boot behind an env flag, or accept that you need to reproduce in staging.

tracemalloc adds ~30-50% overhead and holds tracebacks for every live allocation. Do not leave it on. In a 512 MB worker it will itself push you into OOM. Enable via signal, take snapshots, disable.

gc.get_objects() returns objects tracked by the GC. str, bytes, int, and tuples of untracked types are not tracked. If your leak is a giant str (e.g. accumulating log lines), objgraph will miss it. Use tracemalloc for those.

sys.getsizeof lies about container size. It returns the size of the container object, not its contents. A dict with 100,000 entries reports ~5 MB via getsizeof but holds far more. Use tracemalloc or pympler.asizeof for real numbers.

Reference cycles with __del__. In Python < 3.4 these were uncollectable; modern CPython handles them, but if you have a C extension holding a reference (a common pattern with some ORMs and HTTP clients), gc.collect() won't free it and neither will objgraph. That's when you reach for gc.get_referrers on the suspect object and read the raw gc.garbage list.

objgraph.show_backrefs on a large object graph is slow and can hang. Set max_depth=4 and pass a specific object, not a type.

When this workflow is the wrong tool

If live_objects() is flat and RSS still climbs, you have a C-extension leak or allocator fragmentation. tracemalloc and objgraph are blind to memory allocated by malloc inside a C extension that doesn't use Python's allocators. Check with PYTHONMALLOC=malloc valgrind --tool=memcheck on a short run, or heaptrack for a lower-overhead view. The Python-level tooling will show nothing, and you'll waste hours.

If the leak only manifests under production load and not in your fixture loop, the leak is likely concurrency-dependent — a lock held across an exception path, a queue that grows faster than it drains, a thread-local that never gets cleaned. tracemalloc snapshots from a single thread won't show the other threads' allocations. Use faulthandler.dump_traceback_later() and per-thread snapshots.

And if the service is short-lived (a cron job, a Lambda), stop. A leak that grows 2 MB over a 30-second invocation is not a leak, it's a working set. Don't fix what the process lifetime already bounds.

The one-line version

tracemalloc finds the allocation site; objgraph.show_backrefs finds the referrer. Leaks in long-running Python services are almost always an unbounded cache — a dict, an lru_cache without maxsize, or a functools.cache — keyed on something per-request-unique. Bound it, TTL it, or delete it. Then verify with the same before/after snapshot that found it, because if you don't, you'll be back here in three days.

Docs worth bookmarking: tracemalloc, gc, objgraph, cachetools, functools.lru_cache.

Your Backend Already Broke Your Frontend. You Just Don't Know Yet.

M.Dyer — Mon, 21 Sep 2026 09:11:07 +0000

A backend engineer renames user_id to userId in a response body. The OpenAPI spec changes. The PR passes CI. Three weeks later, a frontend feature silently renders undefined in production, and someone spends a day bisecting a deploy that had nothing to do with it. This is not a rare failure mode — it's the default one, because the contract between your services lives in a YAML file that nothing actually enforces.

The fix isn't discipline. It's making the compiler read the spec. If openapi-typescript generates a .d.ts from your spec on every build, a renamed field becomes a TypeScript error on the exact line that consumes it, in the PR that caused it, before merge. That's the entire pitch. The rest of this article is how to wire it up without creating a build system that everyone hates.

The shape of the problem

You have three artifacts that drift independently:

The actual HTTP responses your server sends.
The OpenAPI spec that's supposed to describe them.
The TypeScript types your frontend believes.

Most teams keep (1) and (2) roughly in sync by convention and let (3) be hand-written. Hand-written types are the failure point — they're written once, from a spec that was accurate on a Tuesday, and never revisited. The compiler can't help you because it has no idea what the truth is.

There are two ways to close the gap: generate types from the spec (spec is the source of truth), or generate the spec from the code (code is the source of truth). Both work. This article covers the first, because it's the one that scales to polyglot backends and lets you diff the contract in code review.

Generating types with openapi-typescript

openapi-typescript emits pure .d.ts — no runtime, no generated client class, no dependency in your bundle. That's the key design choice: you get types, you bring your own fetch wrapper.

npm install -D openapi-typescript
npx openapi-typescript ./openapi.yaml -o ./src/api/schema.d.ts

The output looks like this (abridged):

export interface paths {
  "/users/{id}": {
    get: operations["getUser"];
  };
}
export interface components {
  schemas: {
    User: {
      id: string;
      email: string;
      created_at: string; // ISO 8601
    };
  };
}
export interface operations {
  getUser: {
    parameters: {
      path: { id: string };
    };
    responses: {
      200: {
        content: {
          "application/json": components["schemas"]["User"];
        };
      };
      404: {
        content: {
          "application/json": { message: string };
        };
      };
    };
  };
}

Now you write a thin typed client. The why comments matter here — this is the code that makes the generated types actually usable:

import createClient from "openapi-fetch";
import type { paths } from "./schema";

// openapi-fetch is the runtime companion to openapi-typescript.
// It reads the generated `paths` type to constrain `client.GET` etc.
const client = createClient<paths>({ baseUrl: process.env.API_URL });

async function getUser(id: string) {
  const { data, error, response } = await client.GET("/users/{id}", {
    params: { path: { id } },
  });

  // openapi-fetch narrows `data` vs `error` off the status code.
  // If the spec says 404 returns {message: string}, `error` is typed
  // as that shape here — no `as` cast, no manual discriminated union.
  if (error) {
    throw new Error(`getUser failed: ${response.status} ${error.message}`);
  }
  return data; // typed as components["schemas"]["User"]
}

The important line is client.GET("/users/{id}", ...). If someone deletes that path from the spec, this call fails to compile. If they rename id to userId in the path params, this fails to compile. If they change the 200 response from User to UserV2 missing the email field, every consumer of data.email fails to compile. That's the whole value proposition, and it costs you one dev dependency.

Catching breaking changes in CI

Generation alone doesn't stop drift — you need to fail the build when the spec changes incompatibly. oasdiff does structural diffing between two specs:

# In CI, compare the spec on this branch against main.
# --fail-on ERR exits non-zero for breaking changes only.
oasdiff breaking \
  --base origin/main:openapi.yaml \
  --revision ./openapi.yaml \
  --fail-on ERR

Run that as a required check. Now a PR that removes a required field, narrows an enum, or makes an optional param required gets blocked at review time, not at runtime. oasdiff classifies changes as ERR (breaking), WARN, or INFO — tune --fail-on to your tolerance. The oasdiff docs list the full rule set; the enum-narrowing rule alone catches a class of bug that's nearly impossible to catch in test suites.

The second CI check regenerates types and fails if the committed .d.ts differs from what the current spec produces:

npx openapi-typescript ./openapi.yaml -o ./src/api/schema.d.ts
# --exit-code makes git diff non-zero if anything changed.
git diff --exit-code ./src/api/schema.d.ts || {
  echo "schema.d.ts is stale. Run 'npm run codegen' and commit."
  exit 1
}

This forces the generated file into git. Some teams hate that — it's a large diff on every spec change. The alternative (generate in a prebuild step, gitignore it) means a broken backend spec breaks your build with no obvious cause. Committing it keeps the contract change visible in the PR. Pick your poison.

Where this breaks down

The spec lies. If your server doesn't actually validate against the OpenAPI spec at runtime, the spec is aspirational and your types are fiction. The only durable fix is to generate the spec from your server code (FastAPI, tRPC, Hono, zod-to-openapi) or validate responses against it in tests. Type-checking against a wrong spec is worse than no type-checking, because it gives false confidence. Use express-openapi-validator or your framework's equivalent to enforce the contract at runtime, ideally in staging.

Large specs produce large types. A 5,000-line spec yields a .d.ts that TypeScript struggles to check. Generation takes seconds; tsc on a project that imports the whole schema can take a minute. Mitigate by generating per-tag or per-service slices, or by using --immutable-types to avoid deeply nested mapped types. If your spec is huge, budget for it.

anyOf/oneOf don't map cleanly. OpenAPI's composition keywords become TypeScript unions, which is usually fine, but allOf inheritance and additionalProperties interact badly with the type system. You'll occasionally get Record<string, unknown> where you wanted a concrete shape. The generated types are honest about ambiguity; your code has to narrow.

Discriminated unions require discriminator. If your spec uses oneOf without a discriminator field, you get a union with no discriminant, and every consumer needs a manual type guard. Fix the spec, not the client.

This is the wrong choice when the API is internal and co-deployed. If your frontend and backend ship from the same monorepo and the same commit, you don't need OpenAPI as an intermediary — use tRPC or a shared Zod schema. OpenAPI earns its keep when the boundary is real: separate teams, separate deploy cadences, third-party consumers, or a polyglot backend where the spec is the only lingua franca.

What it actually buys you

The measurable win is not "we have types." It's that a class of bug — the silent undefined from a renamed field — moves from production to CI. That's worth a dev dependency, a 30-line CI job, and a generated file in git. It is not worth fighting a spec that nobody maintains. Fix the spec pipeline first; the codegen is the easy part.