Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

test(e2e): real-backend harness that compares graphs after edits with a fresh ingest

KageBinarya463ed17da49
diff --git a/ix-cli/package.json b/ix-cli/package.json
index 669517d0..40a57654 100644
--- a/ix-cli/package.json
+++ b/ix-cli/package.json
@@ -20,6 +20,9 @@
"test": "node scripts/build-core-ingestion.mjs && vitest run && node test/parser.smoke.mjs",
"test:unit": "vitest run",
"test:coverage": "vitest run --coverage",
+ "test:e2e": "npm run build && vitest run --config vitest.e2e.config.ts",
+ "e2e:up": "docker compose -f test/e2e/compose.e2e.yml up -d --wait --wait-timeout 240",
+ "e2e:down": "docker compose -f test/e2e/compose.e2e.yml down -v",
"smoke": "node test/parser.smoke.mjs",
"typecheck": "tsc --noEmit",
"lint": "eslint src",
diff --git a/ix-cli/test/e2e/README.md b/ix-cli/test/e2e/README.md
new file mode 100644
index 00000000..23820d2a
--- /dev/null
+++ b/ix-cli/test/e2e/README.md
@@ -0,0 +1,133 @@
+
+# Real-backend harness
+
+These scenarios drive the built CLI against a real memory-layer and ArangoDB and
+check one property: **after any sequence of edits and `ix map` runs, the graph
+equals a fresh ingest of the same tree.** They compare graph signatures read
+straight from ArangoDB, so they catch a graph that is wrong but looks healthy.
+
+The unit suite (`npm test`) never runs them: scenario files end in `.e2e.ts`,
+which the default vitest config does not collect.
+
+## Run it
+
+```sh
+cd ix-cli
+npm run e2e:up # throwaway stack on 8290 / 8729
+IX_E2E=1 npm run test:e2e # builds dist/, then runs the scenarios (~40 s)
+npm run e2e:down # removes the containers and the volume
+```
+
+`test:e2e` runs `npm run build` first, because the scenarios execute
+`dist/cli/main.js`. To skip the build, run
+`IX_E2E=1 npx vitest run --config vitest.e2e.config.ts`.
+
+Every scenario starts with `POST /v1/reset`, which empties the whole database.
+The harness therefore refuses to run unless `IX_E2E=1` is set, and refuses any
+endpoint that is not loopback or that uses a port of a stack with real data:
+8090, 8091, 8099, 8100, 8190 (backends) and 8529, 8530, 8539, 8540, 8629
+(ArangoDB).
+
+## Configuration
+
+| Variable | Default | Used by |
+|---|---|---|
+| `IX_E2E` | unset | must be `1` to run |
+| `IX_E2E_PROJECT` | `ix-e2e` | compose project name |
+| `IX_E2E_BACKEND_PORT` | `8290` | compose and harness: host port of the memory-layer |
+| `IX_E2E_ARANGO_PORT` | `8729` | compose and harness: host port of ArangoDB |
+| `IX_E2E_BACKEND_IMAGE` | `ghcr.io/ix-infrastructure/ix-memory-layer:1.0.31@sha256:7f972fb0…` | compose: the backend under test |
+| `IX_E2E_ENDPOINT` | `http://127.0.0.1:$IX_E2E_BACKEND_PORT` | harness: backend URL, overrides the port |
+| `IX_E2E_ARANGO_URL` | `http://127.0.0.1:$IX_E2E_ARANGO_PORT` | harness and `graph-sig.mjs`: ArangoDB URL |
+| `IX_E2E_DIFF_DIR` | unset | harness: write every graph difference to `<dir>/<scenario>.txt` |
+| `IX_TOKEN` | unset | harness: sent as `Authorization: Bearer` on the reset call |
+
+Set the same `IX_E2E_*` values for `e2e:up`, `test:e2e` and `e2e:down`.
+
+### Several stacks at once
+
+Each stack needs its own project name and ports. One stack is capped at about
+2.7 GB (ArangoDB 1200 MB, backend 1500 MB), so keep at most two up on a laptop
+and always finish with `e2e:down`.
+
+| Who | `IX_E2E_PROJECT` | `IX_E2E_BACKEND_PORT` | `IX_E2E_ARANGO_PORT` |
+|---|---|---|---|
+| default, CI | `ix-e2e` | 8290 | 8729 |
+| second stack | `ix-e2e-2` | 8291 | 8730 |
+| third stack | `ix-e2e-3` | 8292 | 8731 |
+
+```sh
+export IX_E2E_PROJECT=ix-e2e-3 IX_E2E_BACKEND_PORT=8292 IX_E2E_ARANGO_PORT=8731
+npm run e2e:up && IX_E2E=1 npm run test:e2e; npm run e2e:down
+```
+
+### Testing a backend change
+
+Build an image from an Ix-memory checkout and point the stack at it:
+
+```sh
+cd <ix-memory checkout>
+sbt assembly # target/scala-2.13/ix-memory-layer.jar
+docker build -f Dockerfile.core -t ix-memory-layer:my-fix .
+cd <ix checkout>/ix-cli
+IX_E2E_BACKEND_IMAGE=ix-memory-layer:my-fix npm run e2e:up
+IX_E2E=1 npm run test:e2e
+npm run e2e:down
+```
+
+Do not run Ix-memory's own `sbt test` on the host network next to other
+stacks: the specs truncate whichever ArangoDB answers on `localhost:8529`.
+
+## Scenarios
+
+`scenarios.e2e.ts`. Each one copies a fixture to a temp dir, commits it with
+git and uses a temp `IX_HOME`.
+
+| Scenario | Compared with |
+|---|---|
+| A → B → A | the graph of A |
+| rename a function and back | the original graph |
+| delete a file and restore it | the original graph |
+| branch round trip (rename, add, delete across files) | the graph of the starting branch |
+| two workspaces sharing `README.md`, `package.json`, `.github/workflows/ci.yml` | the first workspace's graph before the second was mapped |
+| edit one Python file; edit one TypeScript file; rename a file; add a file | a fresh map of the edited tree |
+| map twice | the first map |
+
+The fresh reference maps the same directory from a new, empty `IX_HOME`. The
+directory has to stay the same: the workspace id, and with it the ids of
+unresolved call targets, derive from the path.
+
+### Known failures
+
+A scenario that fails today until a fix lands is wrapped in `failsUntil([...])`
+and titled `[fails until <task ids>]`. It passes while the graphs differ. It
+turns red when they match, with a message asking for the marker to be removed,
+so the PR that lands the last listed fix unwraps it. A fix that lands earlier
+removes its own id from the title and the list. Any other error, such as a
+crashed `ix map` or an unreachable database, fails the run either way.
+
+To see what a marked scenario still gets wrong, set `IX_E2E_DIFF_DIR`.
+
+## Fixtures
+
+`fixtures/polyglot/` has 23 files: Python with cross-file calls (`app/`),
+TypeScript with import-bound calls (`web/src/`), Java (`server/`), and
+`README.md`, `package.json` and `.github/workflows/ci.yml`.
+`fixtures/polyglot-b/` shares those last three names and nothing else. Other
+tests may reuse them; keep them small.
+
+## Graph signatures by hand
+
+`graph-sig.mjs` is a Node port of the audit's `gsig.py` and `gdiff.py`:
+
+```sh
+export IX_E2E_ARANGO_URL=http://127.0.0.1:8729
+node test/e2e/graph-sig.mjs sig <workspace_id> before.json
+node test/e2e/graph-sig.mjs sig <workspace_id> after.json
+node test/e2e/graph-sig.mjs diff before.json after.json 20 # exit 1 when they differ
+```
+
+A node prints as `kind|name|source_uri|line_start|line_end`, an edge as
+`predicate|<src kind:name@uri>|<dst kind:name@uri>|source_uri`. An endpoint that
+is not a live node of the workspace prints as `?<first 8 characters of its id>`.
+Region nodes and `IN_REGION` edges are left out.
diff --git a/ix-cli/test/e2e/compose.e2e.yml b/ix-cli/test/e2e/compose.e2e.yml
new file mode 100644
index 00000000..15268d38
--- /dev/null
+++ b/ix-cli/test/e2e/compose.e2e.yml
@@ -0,0 +1,78 @@
+# Copyright 2026 Ix Infrastructure Inc.
+#
+# Throwaway backend for the real-backend harness (test/e2e). Every scenario
+# resets this database, so it gets its own compose project and ports and must
+# never be pointed at a stack anything else uses. See test/e2e/README.md.
+#
+# IX_E2E_PROJECT compose project name (default ix-e2e)
+# IX_E2E_BACKEND_PORT host port of memory-layer (default 8290)
+# IX_E2E_ARANGO_PORT host port of ArangoDB (default 8729)
+# IX_E2E_BACKEND_IMAGE memory-layer image (default: v1.0.31, pinned by digest)
+#
+# Memory is capped: ArangoDB's caches otherwise size themselves from host RAM
+# (a 9 GB block cache on a 30 GB host). The whole stack stays under ~2.7 GB.
+
+name: ${IX_E2E_PROJECT:-ix-e2e}
+
+services:
+ arangodb:
+ image: arangodb:3.12.11
+ networks: [backend]
+ ports:
+ # Published only for the graph-signature reads in graph-sig.mjs.
+ - "127.0.0.1:${IX_E2E_ARANGO_PORT:-8729}:8529"
+ environment:
+ ARANGO_NO_AUTH: "1"
+ # Every default derived from "physical memory" derives from this instead.
+ ARANGODB_OVERRIDE_DETECTED_TOTAL_MEMORY: "1G"
+ command:
+ - arangod
+ - --server.endpoint=tcp://0.0.0.0:8529
+ - --vector-index=true
+ - --rocksdb.block-cache-size=268435456 # 256 MB
+ - --rocksdb.enforce-block-cache-size-limit=true
+ - --rocksdb.total-write-buffer-size=134217728 # 128 MB
+ - --cache.size=67108864 # 64 MB edge/document cache
+ - --query.memory-limit=536870912 # 512 MB per query
+ - --query.global-memory-limit=805306368 # 768 MB all queries
+ mem_limit: 1200m
+ memswap_limit: 1200m
+ volumes:
+ - arangodb-data:/var/lib/arangodb3
+ healthcheck:
+ test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8529/_api/version || exit 1"]
+ interval: 5s
+ timeout: 5s
+ start_period: 60s
+ retries: 15
+
+ memory-layer:
+ image: ${IX_E2E_BACKEND_IMAGE:-ghcr.io/ix-infrastructure/ix-memory-layer:1.0.31@sha256:7f972fb084d9667ef1b7cd7e7c40b24aad76fb4cb38d1cc07a0319444c0ab979}
+ networks: [backend]
+ ports:
+ - "127.0.0.1:${IX_E2E_BACKEND_PORT:-8290}:8090"
+ environment:
+ ARANGO_HOST: arangodb
+ ARANGO_PORT: "8529"
+ ARANGO_DATABASE: ix_memory
+ ARANGO_USER: root
+ ARANGO_PASSWORD: ""
+ PORT: "8090"
+ JAVA_TOOL_OPTIONS: "-Xmx512m"
+ mem_limit: 1500m
+ memswap_limit: 1500m
+ depends_on:
+ arangodb:
+ condition: service_healthy
+ healthcheck:
+ test: ["CMD", "curl", "-sf", "http://localhost:8090/v1/health"]
+ interval: 5s
+ timeout: 3s
+ start_period: 15s
+ retries: 12
+
+volumes:
+ arangodb-data:
+
+networks:
+ backend:
diff --git a/ix-cli/test/e2e/fixtures/polyglot-b/.github/workflows/ci.yml b/ix-cli/test/e2e/fixtures/polyglot-b/.github/workflows/ci.yml
new file mode 100644
index 00000000..be7cde7b
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot-b/.github/workflows/ci.yml
@@ -0,0 +1,9 @@
+name: CI
+on: [push]
+jobs:
+ lint:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Lint scheduler
+ run: pip install ruff && ruff lib
diff --git a/ix-cli/test/e2e/fixtures/polyglot-b/README.md b/ix-cli/test/e2e/fixtures/polyglot-b/README.md
new file mode 100644
index 00000000..2fe61d08
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot-b/README.md
@@ -0,0 +1,8 @@
+# polyglot-b
+
+Second fixture for the Ix real-backend harness. It shares `README.md`,
+`package.json` and `.github/workflows/ci.yml` with `polyglot/`, so mapping it
+into the same backend tests that one workspace's ingest leaves the other's
+graph alone.
+
+See [the scheduler](lib/scheduler.py).
diff --git a/ix-cli/test/e2e/fixtures/polyglot-b/lib/__init__.py b/ix-cli/test/e2e/fixtures/polyglot-b/lib/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/ix-cli/test/e2e/fixtures/polyglot-b/lib/clock.py b/ix-cli/test/e2e/fixtures/polyglot-b/lib/clock.py
new file mode 100644
index 00000000..e28c5b6e
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot-b/lib/clock.py
@@ -0,0 +1,5 @@
+import time
+
+
+def now():
+ return int(time.time())
diff --git a/ix-cli/test/e2e/fixtures/polyglot-b/lib/scheduler.py b/ix-cli/test/e2e/fixtures/polyglot-b/lib/scheduler.py
new file mode 100644
index 00000000..58b77e44
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot-b/lib/scheduler.py
@@ -0,0 +1,13 @@
+from lib.clock import now
+
+
+class Scheduler:
+ def __init__(self):
+ self.jobs = []
+
+ def every(self, seconds, job):
+ self.jobs.append((now() + seconds, job))
+
+ def due(self):
+ current = now()
+ return [job for at, job in self.jobs if at <= current]
diff --git a/ix-cli/test/e2e/fixtures/polyglot-b/package.json b/ix-cli/test/e2e/fixtures/polyglot-b/package.json
new file mode 100644
index 00000000..3ec8d0a1
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot-b/package.json
@@ -0,0 +1,12 @@
+{
+ "name": "polyglot-b-fixture",
+ "version": "2.0.0",
+ "private": true,
+ "description": "Second fixture for the Ix real-backend harness",
+ "scripts": {
+ "lint": "ruff lib"
+ },
+ "dependencies": {
+ "is-odd": "^3.0.1"
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/.github/workflows/ci.yml b/ix-cli/test/e2e/fixtures/polyglot/.github/workflows/ci.yml
new file mode 100644
index 00000000..65a9606b
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/.github/workflows/ci.yml
@@ -0,0 +1,18 @@
+name: CI
+on:
+ push:
+ branches: [main]
+ pull_request:
+jobs:
+ python:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Test billing
+ run: python -m pytest app
+ web:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - name: Build cart
+ run: npm ci && npm run build
diff --git a/ix-cli/test/e2e/fixtures/polyglot/README.md b/ix-cli/test/e2e/fixtures/polyglot/README.md
new file mode 100644
index 00000000..ddadb35c
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/README.md
@@ -0,0 +1,9 @@
+# polyglot
+
+Fixture for the Ix real-backend harness (`ix-cli/test/e2e`). A small shop in
+three languages: a Python billing service (`app/`), a TypeScript cart
+(`web/src/`) and a Java greeting server (`server/`). Every module calls into
+at least one other file, so cross-file `CALLS` and `IMPORTS` edges exist in
+each language.
+
+See [the web cart](web/src/cart.ts) and [the billing service](app/services.py).
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/__init__.py b/ix-cli/test/e2e/fixtures/polyglot/app/__init__.py
new file mode 100644
index 00000000..3661d4f2
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/__init__.py
@@ -0,0 +1 @@
+"""Billing service for the polyglot fixture."""
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/api.py b/ix-cli/test/e2e/fixtures/polyglot/app/api.py
new file mode 100644
index 00000000..ac6e4867
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/api.py
@@ -0,0 +1,22 @@
+"""Entry points the CLI calls."""
+
+from app.events import subscribe
+from app.services import BillingService, receipt
+
+_service = BillingService()
+_log = []
+
+
+def _record(payload):
+ _log.append(payload)
+
+
+def register():
+ subscribe("order.charged", _record)
+ return _service
+
+
+def checkout(name, email, items):
+ service = register()
+ user = service.create_user(name, email)
+ return receipt(service, user, items)
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/cli.py b/ix-cli/test/e2e/fixtures/polyglot/app/cli.py
new file mode 100644
index 00000000..7b1d6ccb
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/cli.py
@@ -0,0 +1,15 @@
+"""Command-line front end."""
+
+import sys
+
+from app.api import checkout
+
+
+def main(argv=None):
+ args = argv if argv is not None else sys.argv[1:]
+ name = args[0] if args else "Ada Lovelace"
+ print(checkout(name, "[email protected]", [("book", 1250), ("pen", 300)]))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/events.py b/ix-cli/test/e2e/fixtures/polyglot/app/events.py
new file mode 100644
index 00000000..2d459962
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/events.py
@@ -0,0 +1,13 @@
+"""A tiny event bus."""
+
+_handlers = {}
+
+
+def subscribe(name, handler):
+ _handlers.setdefault(name, []).append(handler)
+
+
+def publish(name, payload):
+ for handler in _handlers.get(name, []):
+ handler(payload)
+ return len(_handlers.get(name, []))
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/models.py b/ix-cli/test/e2e/fixtures/polyglot/app/models.py
new file mode 100644
index 00000000..4ee3b6f7
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/models.py
@@ -0,0 +1,25 @@
+"""Plain data models."""
+
+from app.utils import slugify
+
+
+class User:
+ def __init__(self, name, email):
+ self.name = name
+ self.email = email
+ self.slug = slugify(name)
+
+ def display_name(self):
+ return f"{self.name} <{self.email}>"
+
+
+class Order:
+ def __init__(self, user, items):
+ self.user = user
+ self.items = list(items)
+
+ def subtotal(self):
+ return sum(price for _, price in self.items)
+
+ def describe(self):
+ return f"{self.user.display_name()}: {len(self.items)} items"
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/pricing.py b/ix-cli/test/e2e/fixtures/polyglot/app/pricing.py
new file mode 100644
index 00000000..5e207a87
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/pricing.py
@@ -0,0 +1,17 @@
+"""Discounts and tax."""
+
+from app.utils import clamp
+
+TAX_RATE = 0.08
+
+
+def apply_discount(amount, percent):
+ return int(amount * (100 - clamp(percent, 0, 100)) / 100)
+
+
+def add_tax(amount):
+ return int(round(amount * (1 + TAX_RATE)))
+
+
+def total_for(order, percent=0):
+ return add_tax(apply_discount(order.subtotal(), percent))
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/repository.py b/ix-cli/test/e2e/fixtures/polyglot/app/repository.py
new file mode 100644
index 00000000..23f4a8e6
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/repository.py
@@ -0,0 +1,16 @@
+"""In-memory persistence."""
+
+from app.utils import to_snake_case
+
+
+class Repository:
+ def __init__(self):
+ self._rows = {}
+
+ def save(self, entity):
+ key = to_snake_case(type(entity).__name__)
+ self._rows.setdefault(key, []).append(entity)
+ return len(self._rows[key])
+
+ def find_all(self, kind):
+ return list(self._rows.get(to_snake_case(kind), []))
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/services.py b/ix-cli/test/e2e/fixtures/polyglot/app/services.py
new file mode 100644
index 00000000..7c28415c
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/services.py
@@ -0,0 +1,29 @@
+"""Billing use cases."""
+
+from app.events import publish
+from app.models import Order, User
+from app.pricing import total_for
+from app.repository import Repository
+from app.utils import format_money
+
+
+class BillingService:
+ def __init__(self, repository=None):
+ self.repository = repository or Repository()
+
+ def create_user(self, name, email):
+ user = User(name, email)
+ self.repository.save(user)
+ publish("user.created", user)
+ return user
+
+ def charge(self, user, items, percent=0):
+ order = Order(user, items)
+ self.repository.save(order)
+ amount = total_for(order, percent)
+ publish("order.charged", order)
+ return format_money(amount)
+
+
+def receipt(service, user, items):
+ return service.charge(user, items) + " for " + user.display_name()
diff --git a/ix-cli/test/e2e/fixtures/polyglot/app/utils.py b/ix-cli/test/e2e/fixtures/polyglot/app/utils.py
new file mode 100644
index 00000000..bc837c6a
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/app/utils.py
@@ -0,0 +1,24 @@
+"""String and money helpers shared by the billing modules."""
+
+import re
+
+
+def to_snake_case(name):
+ """Convert CamelCase to snake_case."""
+ first = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
+ return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", first).lower()
+
+
+def slugify(text):
+ """Lower-case, dash-separated identifier for a display name."""
+ return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+
+
+def format_money(cents, currency="USD"):
+ """Render an integer amount of cents."""
+ return f"{currency} {cents // 100}.{cents % 100:02d}"
+
+
+def clamp(value, low, high):
+ """Bound value to [low, high]."""
+ return max(low, min(high, value))
diff --git a/ix-cli/test/e2e/fixtures/polyglot/package.json b/ix-cli/test/e2e/fixtures/polyglot/package.json
new file mode 100644
index 00000000..09ab5273
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/package.json
@@ -0,0 +1,17 @@
+{
+ "name": "polyglot-fixture",
+ "version": "1.0.0",
+ "private": true,
+ "description": "Fixture for the Ix real-backend harness",
+ "main": "web/src/index.ts",
+ "scripts": {
+ "build": "tsc -p web",
+ "test": "python -m pytest app"
+ },
+ "dependencies": {
+ "left-pad": "^1.3.0"
+ },
+ "devDependencies": {
+ "typescript": "^5.6.0"
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/Greeter.java b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/Greeter.java
new file mode 100644
index 00000000..549e9a2c
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/Greeter.java
@@ -0,0 +1,13 @@
+package com.example;
+
+public class Greeter {
+ private final String greeting;
+
+ public Greeter(String greeting) {
+ this.greeting = greeting;
+ }
+
+ public String greet(String name) {
+ return greeting + ", " + name + "!";
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/GreetingService.java b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/GreetingService.java
new file mode 100644
index 00000000..12339fdd
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/GreetingService.java
@@ -0,0 +1,22 @@
+package com.example;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+public class GreetingService {
+ private final Greeter greeter;
+ private final NameRepository repository;
+
+ public GreetingService(Greeter greeter, NameRepository repository) {
+ this.greeter = greeter;
+ this.repository = repository;
+ }
+
+ public void register(String name) {
+ repository.add(name);
+ }
+
+ public List<String> greetAll() {
+ return repository.all().stream().map(greeter::greet).collect(Collectors.toList());
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/Main.java b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/Main.java
new file mode 100644
index 00000000..33b2cd54
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/Main.java
@@ -0,0 +1,12 @@
+package com.example;
+
+public class Main {
+ public static void main(String[] args) {
+ GreetingService service = new GreetingService(new Greeter("Hello"), new NameRepository());
+ service.register("Ada");
+ service.register("Grace");
+ for (String line : service.greetAll()) {
+ System.out.println(line);
+ }
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/NameRepository.java b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/NameRepository.java
new file mode 100644
index 00000000..aa6602f0
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/server/src/main/java/com/example/NameRepository.java
@@ -0,0 +1,16 @@
+package com.example;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class NameRepository {
+ private final List<String> names = new ArrayList<>();
+
+ public void add(String name) {
+ names.add(name);
+ }
+
+ public List<String> all() {
+ return new ArrayList<>(names);
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/cart.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/cart.ts
new file mode 100644
index 00000000..3fa5572a
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/cart.ts
@@ -0,0 +1,26 @@
+import { add, multiply } from "./math";
+import { formatPrice } from "./format";
+import { Store } from "./store";
+import type { LineItem } from "./types";
+
+export class Cart {
+ private readonly lines: LineItem[] = [];
+
+ constructor(private readonly store: Store<LineItem[]>) {}
+
+ addLine(line: LineItem): void {
+ this.lines.push(line);
+ }
+
+ total(): number {
+ return this.lines.reduce((sum, line) => add(sum, multiply(line.price, line.quantity)), 0);
+ }
+
+ summary(): string {
+ return `${this.lines.length} items, ${formatPrice(this.total())}`;
+ }
+
+ save(id: string): void {
+ this.store.set(id, [...this.lines]);
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/events.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/events.ts
new file mode 100644
index 00000000..92acb830
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/events.ts
@@ -0,0 +1,12 @@
+import type { Listener } from "./types";
+
+const listeners: Listener[] = [];
+
+export function on(listener: Listener): void {
+ listeners.push(listener);
+}
+
+export function emit(event: string, payload: unknown): number {
+ for (const listener of listeners) listener(event, payload);
+ return listeners.length;
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/format.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/format.ts
new file mode 100644
index 00000000..118aae37
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/format.ts
@@ -0,0 +1,9 @@
+import { clamp, multiply } from "./math";
+
+export function formatPercent(ratio: number): string {
+ return `${Math.round(multiply(clamp(ratio, 0, 1), 100))}%`;
+}
+
+export function formatPrice(cents: number): string {
+ return `$${(cents / 100).toFixed(2)}`;
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/index.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/index.ts
new file mode 100644
index 00000000..9746c9ca
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/index.ts
@@ -0,0 +1,12 @@
+import { Cart } from "./cart";
+import { on } from "./events";
+import { formatPercent } from "./format";
+import { Store } from "./store";
+
+export function run(): string {
+ on((event) => console.log(event));
+ const cart = new Cart(new Store());
+ cart.addLine({ sku: "book", price: 1250, quantity: 1 });
+ cart.save("demo");
+ return `${cart.summary()} (${formatPercent(0.08)} tax)`;
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/math.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/math.ts
new file mode 100644
index 00000000..9656b54f
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/math.ts
@@ -0,0 +1,11 @@
+export function add(a: number, b: number): number {
+ return a + b;
+}
+
+export function multiply(a: number, b: number): number {
+ return a * b;
+}
+
+export function clamp(value: number, low: number, high: number): number {
+ return Math.max(low, Math.min(high, value));
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/store.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/store.ts
new file mode 100644
index 00000000..d9f87e8d
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/store.ts
@@ -0,0 +1,14 @@
+import { emit } from "./events";
+
+export class Store<T> {
+ private readonly items = new Map<string, T>();
+
+ get(key: string): T | undefined {
+ return this.items.get(key);
+ }
+
+ set(key: string, value: T): void {
+ this.items.set(key, value);
+ emit("store.set", key);
+ }
+}
diff --git a/ix-cli/test/e2e/fixtures/polyglot/web/src/types.ts b/ix-cli/test/e2e/fixtures/polyglot/web/src/types.ts
new file mode 100644
index 00000000..de447fc8
--- /dev/null
+++ b/ix-cli/test/e2e/fixtures/polyglot/web/src/types.ts
@@ -0,0 +1,7 @@
+export interface LineItem {
+ sku: string;
+ price: number;
+ quantity: number;
+}
+
+export type Listener = (event: string, payload: unknown) => void;
diff --git a/ix-cli/test/e2e/graph-sig.mjs b/ix-cli/test/e2e/graph-sig.mjs
new file mode 100644
index 00000000..0c0d71c9
--- /dev/null
+++ b/ix-cli/test/e2e/graph-sig.mjs
@@ -0,0 +1,165 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+// Graph signature of one workspace's live graph, read straight from ArangoDB.
+//
+// Node and edge ids are content hashes that change with paths and extractor
+// versions, so two graphs of the same tree are compared by NAME instead:
+// node kind|name|source_uri|line_start|line_end
+// edge predicate|<src kind:name@uri>|<dst kind:name@uri>|source_uri
+// An edge whose endpoint is not a live node of the workspace prints as
+// "?<first 8 of id>", so dangling edges show up in a diff instead of vanishing.
+// Region nodes and IN_REGION edges are left out: they belong to the map, not
+// to the code graph.
+//
+// Module use (the harness): graphSignature(arangoUrl, workspaceId), diffSignatures(a, b)
+// Command line:
+// node graph-sig.mjs sig <workspace_id> [out.json] # prints counts + hashes
+// node graph-sig.mjs diff <a.json> <b.json> [limit] # prints what differs
+// The ArangoDB URL comes from IX_E2E_ARANGO_URL (default http://127.0.0.1:8729).
+
+/* global fetch, process, console */
+
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+const DATABASE = "ix_memory";
+
+const NODES_AQL = `FOR n IN nodes
+ FILTER n.workspace_id == @w AND n.deleted_rev == null AND n.kind != "region"
+ RETURN [n.id, n.kind, n.name, n.provenance.source_uri, n.attrs.line_start, n.attrs.line_end]`;
+
+const EDGES_AQL = `FOR e IN edges
+ FILTER e.workspace_id == @w AND e.deleted_rev == null AND e.predicate != "IN_REGION"
+ RETURN [e.predicate, e.src, e.dst, e.provenance.source_uri]`;
+
+async function post(url, body) {
+ const res = await fetch(url, {
+ method: body === undefined ? "PUT" : "POST",
+ headers: { "content-type": "application/json" },
+ body: body === undefined ? undefined : JSON.stringify(body),
+ });
+ const json = await res.json().catch(() => ({}));
+ if (!res.ok || json.error) {
+ throw new Error(`ArangoDB ${res.status} at ${url}: ${json.errorMessage ?? res.statusText}`);
+ }
+ return json;
+}
+
+/** Run one AQL query to completion, following the cursor. */
+export async function aql(arangoUrl, query, bindVars) {
+ const base = `${arangoUrl.replace(/\/$/, "")}/_db/${DATABASE}/_api/cursor`;
+ let page = await post(base, { query, bindVars, batchSize: 20000 });
+ const out = [...page.result];
+ while (page.hasMore) {
+ page = await post(`${base}/${page.id}`);
+ out.push(...page.result);
+ }
+ return out;
+}
+
+// String(null) is "null" and String(undefined) is "undefined" -- the Python
+// tool printed "None" for both. Normalise so a missing attribute reads the
+// same whichever way the backend omitted it.
+const cell = (v) => (v === null || v === undefined ? "None" : String(v));
+
+function sorted(list) {
+ // Plain code-unit order, the same order Python's sorted() gives.
+ return [...list].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+export function hashOf(lines) {
+ return createHash("sha256").update(lines.join("\n")).digest("hex").slice(0, 12);
+}
+
+/**
+ * Signature of the live graph of `workspaceId`:
+ * `{ nodes: string[], edges: string[] }`, each sorted.
+ */
+export async function graphSignature(arangoUrl, workspaceId) {
+ const nodes = await aql(arangoUrl, NODES_AQL, { w: workspaceId });
+ const edges = await aql(arangoUrl, EDGES_AQL, { w: workspaceId });
+ const byId = new Map(nodes.map((n) => [n[0], n]));
+ const name = (id) => {
+ const n = byId.get(id);
+ return n ? `${n[1]}:${n[2]}@${n[3]}` : `?${String(id).slice(0, 8)}`;
+ };
+ return {
+ nodes: sorted(nodes.map((n) => n.slice(1).map(cell).join("|"))),
+ edges: sorted(edges.map((e) => `${e[0]}|${name(e[1])}|${name(e[2])}|${cell(e[3])}`)),
+ };
+}
+
+function multisetMinus(a, b) {
+ const counts = new Map();
+ for (const x of b) counts.set(x, (counts.get(x) ?? 0) + 1);
+ const out = [];
+ for (const x of a) {
+ const c = counts.get(x) ?? 0;
+ if (c > 0) counts.set(x, c - 1);
+ else out.push(x);
+ }
+ return out;
+}
+
+/**
+ * Multiset difference of two signatures. `equal` is true only when both the
+ * node and the edge multisets match exactly.
+ */
+export function diffSignatures(a, b) {
+ const part = (k) => ({ onlyA: multisetMinus(a[k], b[k]), onlyB: multisetMinus(b[k], a[k]) });
+ const nodes = part("nodes");
+ const edges = part("edges");
+ const equal = [nodes, edges].every((d) => d.onlyA.length === 0 && d.onlyB.length === 0);
+ return { equal, nodes, edges };
+}
+
+/** Human-readable diff, `limit` lines per side and kind. */
+export function formatDiff(a, b, limit = 8) {
+ const d = diffSignatures(a, b);
+ const lines = [];
+ for (const k of ["nodes", "edges"]) {
+ lines.push(
+ `${k}: A=${a[k].length} B=${b[k].length} onlyA=${d[k].onlyA.length} onlyB=${d[k].onlyB.length}`,
+ );
+ for (const x of d[k].onlyA.slice(0, limit)) lines.push(` -A ${x.slice(0, 170)}`);
+ for (const x of d[k].onlyB.slice(0, limit)) lines.push(` +B ${x.slice(0, 170)}`);
+ }
+ return lines.join("\n");
+}
+
+export function summary(sig) {
+ return `nodes=${sig.nodes.length} edges=${sig.edges.length} nodeHash=${hashOf(sig.nodes)} edgeHash=${hashOf(sig.edges)}`;
+}
+
+async function main(argv) {
+ const [cmd, ...rest] = argv;
+ if (cmd === "sig" && rest[0]) {
+ const url = process.env.IX_E2E_ARANGO_URL ?? "http://127.0.0.1:8729";
+ const sig = await graphSignature(url, rest[0]);
+ if (rest[1]) writeFileSync(rest[1], JSON.stringify(sig));
+ console.log(`${rest[0]}: ${summary(sig)}`);
+ return 0;
+ }
+ if (cmd === "diff" && rest[1]) {
+ const read = (p) => JSON.parse(readFileSync(p, "utf8"));
+ const a = read(rest[0]);
+ const b = read(rest[1]);
+ console.log(formatDiff(a, b, rest[2] ? Number(rest[2]) : 4));
+ return diffSignatures(a, b).equal ? 0 : 1;
+ }
+ console.error(
+ "usage: graph-sig.mjs sig <workspace_id> [out.json] | diff <a.json> <b.json> [limit]",
+ );
+ return 2;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+ main(process.argv.slice(2)).then(
+ (code) => process.exit(code),
+ (err) => {
+ console.error(err instanceof Error ? err.message : err);
+ process.exit(2);
+ },
+ );
+}
diff --git a/ix-cli/test/e2e/harness.ts b/ix-cli/test/e2e/harness.ts
new file mode 100644
index 00000000..edeec998
--- /dev/null
+++ b/ix-cli/test/e2e/harness.ts
@@ -0,0 +1,274 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+// Helpers for the real-backend scenarios in this directory. A scenario works on
+// a copy of a fixture in a temp dir (git-initialised, with its own IX_HOME),
+// drives the built CLI against the e2e backend, and compares graph signatures
+// read straight from that backend's ArangoDB.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+ cpSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ realpathSync,
+ rmSync,
+ writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+// @ts-expect-error -- plain .mjs module, also run on its own from the command line
+import { diffSignatures, formatDiff, graphSignature, summary } from "./graph-sig.mjs";
+
+export interface Signature {
+ nodes: string[];
+ edges: string[];
+}
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const FIXTURES = join(HERE, "fixtures");
+const CLI = resolve(HERE, "../../dist/cli/main.js");
+
+// Ports of stacks that hold someone's real graph. Every scenario resets the
+// whole database, so the harness refuses to run against any of them:
+// 8090/8529 the default install (and ix-bench), 8091/8530 helm-eval,
+// 8100/8540 a personal backend, 8099/8539 the benchmark RAM stack,
+// 8190/8629 the audit stack.
+const PROTECTED_PORTS = new Set([8090, 8091, 8099, 8100, 8190, 8529, 8530, 8539, 8540, 8629]);
+
+export interface E2eEnv {
+ endpoint: string;
+ arangoUrl: string;
+ token?: string;
+}
+
+function checkUrl(name: string, raw: string): URL {
+ const url = new URL(raw);
+ const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+ if (!["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)) {
+ throw new Error(`${name}=${raw}: the e2e harness only runs against a loopback backend`);
+ }
+ if (PROTECTED_PORTS.has(port)) {
+ throw new Error(
+ `${name}=${raw}: port ${port} belongs to a shared stack and every scenario resets the database. ` +
+ "Use the e2e stack's own ports (see test/e2e/README.md).",
+ );
+ }
+ return url;
+}
+
+/** Reads and checks the environment. Throws instead of touching a shared stack. */
+export function e2eEnv(): E2eEnv {
+ if (process.env.IX_E2E !== "1") {
+ throw new Error(
+ "Set IX_E2E=1 to run the real-backend harness: every scenario resets the backend's database.",
+ );
+ }
+ const backendPort = process.env.IX_E2E_BACKEND_PORT ?? "8290";
+ const arangoPort = process.env.IX_E2E_ARANGO_PORT ?? "8729";
+ const endpoint = process.env.IX_E2E_ENDPOINT ?? `http://127.0.0.1:${backendPort}`;
+ const arangoUrl = process.env.IX_E2E_ARANGO_URL ?? `http://127.0.0.1:${arangoPort}`;
+ checkUrl("backend endpoint", endpoint);
+ checkUrl("ArangoDB URL", arangoUrl);
+ if (!existsSync(CLI)) throw new Error(`${CLI} not found: run npm run build first`);
+ return {
+ endpoint: endpoint.replace(/\/$/, ""),
+ arangoUrl,
+ token: process.env.IX_TOKEN || undefined,
+ };
+}
+
+function headers(env: E2eEnv): Record<string, string> {
+ const h: Record<string, string> = { "content-type": "application/json" };
+ if (env.token) h.authorization = `Bearer ${env.token}`;
+ return h;
+}
+
+/** POST /v1/reset: empties the whole e2e database. */
+export async function resetBackend(env: E2eEnv): Promise<void> {
+ const res = await fetch(`${env.endpoint}/v1/reset`, {
+ method: "POST",
+ headers: headers(env),
+ body: "{}",
+ });
+ if (!res.ok) throw new Error(`POST /v1/reset: ${res.status} ${await res.text()}`);
+}
+
+/** A working copy: a git repo in a temp dir plus the IX_HOME the CLI uses for it. */
+export interface Checkout {
+ dir: string;
+ ixHome: string;
+}
+
+const scratchRoots: string[] = [];
+
+/** Removes every temp dir made by this process's checkouts. */
+export function cleanupScratch(): void {
+ for (const root of scratchRoots.splice(0)) rmSync(root, { recursive: true, force: true });
+}
+
+export function git(dir: string, ...args: string[]): string {
+ return execFileSync(
+ "git",
+ [
+ "-c",
+ "user.name=ix-e2e",
+ "-c",
+ "-c",
+ "commit.gpgsign=false",
+ ...args,
+ ],
+ { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] },
+ );
+}
+
+/**
+ * Copies `fixture` (a directory under fixtures/, or an absolute path) to
+ * `<tmp>/<name>` and commits it on branch main. The directory name defaults to
+ * the fixture's, so a fresh reference copy and the edited copy share a basename.
+ */
+export function checkout(fixture: string, name = basename(fixture)): Checkout {
+ const root = mkdtempSync(join(tmpdir(), "ix-e2e-"));
+ scratchRoots.push(root);
+ const dir = join(root, name);
+ const src = fixture.startsWith("/") ? fixture : join(FIXTURES, fixture);
+ cpSync(src, dir, { recursive: true, filter: (p) => basename(p) !== ".git" });
+ const ixHome = join(root, "ix-home");
+ mkdirSync(ixHome);
+ git(dir, "init", "-q", "-b", "main");
+ git(dir, "add", "-A");
+ git(dir, "commit", "-q", "-m", "fixture");
+ return { dir: realpathSync(dir), ixHome };
+}
+
+export interface IxResult {
+ status: number;
+ stdout: string;
+ stderr: string;
+}
+
+/** Runs the built CLI in `co.dir`. Throws on a non-zero exit unless `allowFail`. */
+export function ix(env: E2eEnv, co: Checkout, args: string[], allowFail = false): IxResult {
+ const res = spawnSync(process.execPath, [CLI, ...args], {
+ cwd: co.dir,
+ encoding: "utf8",
+ timeout: 120_000,
+ env: {
+ ...process.env,
+ IX_HOME: co.ixHome,
+ IX_ENDPOINT: env.endpoint,
+ IX_NO_UPDATE_CHECK: "1",
+ NO_COLOR: "1",
+ },
+ });
+ const out = { status: res.status ?? -1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+ if (!allowFail && out.status !== 0) {
+ throw new Error(
+ `ix ${args.join(" ")} exited ${out.status}${res.error ? ` (${res.error.message})` : ""}\n${out.stderr}${out.stdout}`,
+ );
+ }
+ return out;
+}
+
+/** `ix map <dir> --silent`: ingest (incrementally after the first run) and persist the map. */
+export function map(env: E2eEnv, co: Checkout): IxResult {
+ return ix(env, co, ["map", co.dir, "--silent"]);
+}
+
+/** The workspace id the CLI registered for `co.dir` in its IX_HOME. */
+export function workspaceId(co: Checkout): string {
+ const config = parseYaml(readFileSync(join(co.ixHome, "config.yaml"), "utf8")) as {
+ workspaces?: Array<{ workspace_id: unknown; root_path: string }>;
+ };
+ const real = (p: string) => {
+ try {
+ return realpathSync(p);
+ } catch {
+ return resolve(p);
+ }
+ };
+ const ws = (config.workspaces ?? []).find((w) => real(w.root_path) === co.dir);
+ if (!ws) throw new Error(`no workspace for ${co.dir} in ${co.ixHome}/config.yaml`);
+ return String(ws.workspace_id);
+}
+
+/** Signature of the live graph of `co`'s workspace. Refuses an empty graph. */
+export async function signature(env: E2eEnv, co: Checkout): Promise<Signature> {
+ const sig = (await graphSignature(env.arangoUrl, workspaceId(co))) as Signature;
+ if (sig.nodes.length === 0) {
+ throw new Error(
+ `workspace of ${co.dir} has no live nodes in ${env.arangoUrl}: ` +
+ "is IX_E2E_ARANGO_PORT the database behind IX_E2E_BACKEND_PORT?",
+ );
+ }
+ return sig;
+}
+
+/**
+ * The reference graph for `co`'s current tree: reset the backend and map the
+ * same directory once from a new, empty IX_HOME (which holds the CLI's mtime
+ * cache and map baseline), so nothing incremental is left. The directory stays
+ * the same because the workspace id, and with it the ids of unresolved call
+ * targets, derive from the path. Resets again afterwards, so the caller's
+ * backend is empty.
+ */
+export async function freshSignature(env: E2eEnv, co: Checkout): Promise<Signature> {
+ await resetBackend(env);
+ const root = mkdtempSync(join(tmpdir(), "ix-e2e-home-"));
+ scratchRoots.push(root);
+ const ref: Checkout = { dir: co.dir, ixHome: root };
+ map(env, ref);
+ const sig = await signature(env, ref);
+ await resetBackend(env);
+ return sig;
+}
+
+/**
+ * Throws, with the difference in the message, unless the two graphs match
+ * exactly. With IX_E2E_DIFF_DIR set, every difference is also written to
+ * `<dir>/<label>.txt`: an `it.fails` scenario swallows its error, and that
+ * file is the only way to see what still differs.
+ */
+export class GraphMismatch extends Error {}
+
+export function expectSameGraph(label: string, actual: Signature, expected: Signature): void {
+ const d = diffSignatures(actual, expected) as { equal: boolean };
+ if (d.equal) return;
+ const text = `[${label}] graph differs (A = after the edits, B = expected)\n${formatDiff(actual, expected, 6)}`;
+ const dir = process.env.IX_E2E_DIFF_DIR;
+ if (dir) {
+ mkdirSync(dir, { recursive: true });
+ writeFileSync(
+ join(dir, `${label.replace(/[^\w.-]+/g, "_")}.txt`),
+ formatDiff(actual, expected, 1000) + "\n",
+ );
+ }
+ throw new GraphMismatch(text);
+}
+
+/**
+ * Wraps a scenario that is known to fail until `tasks` land. Unlike
+ * `it.fails`, only a graph mismatch counts as the expected failure: a crashed
+ * `ix map` or an unreachable database still fails the run. Once the graphs
+ * match, the scenario fails and asks for the marker to be removed.
+ */
+export function failsUntil(tasks: string[], scenario: () => Promise<void>): () => Promise<void> {
+ return async () => {
+ try {
+ await scenario();
+ } catch (err) {
+ if (err instanceof GraphMismatch) return;
+ throw err;
+ }
+ throw new Error(
+ `This scenario now passes. If ${tasks.join(" / ")} landed, turn it back into a plain it(...) ` +
+ "(or drop the landed ids from its title) in the same PR.",
+ );
+ };
+}
+
+export { summary };
diff --git a/ix-cli/test/e2e/scenarios.e2e.ts b/ix-cli/test/e2e/scenarios.e2e.ts
new file mode 100644
index 00000000..18a0ef83
--- /dev/null
+++ b/ix-cli/test/e2e/scenarios.e2e.ts
@@ -0,0 +1,217 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+// Real-backend correctness scenarios: after any sequence of edits and maps the
+// graph must equal a fresh ingest of the same tree. Run with
+// `IX_E2E=1 npm run test:e2e` against the stack from `npm run e2e:up`
+// (test/e2e/README.md).
+//
+// A scenario whose fix has not landed is wrapped in failsUntil([...]) and
+// titled "[fails until <task ids>]" with every plan task it waits for. It
+// passes while the graphs differ and turns red as soon as they match, so the
+// PR that lands the last of those fixes has to unwrap it. A fix that lands
+// earlier takes its own id out of the title and the list. Any other error (a
+// crashed map, an unreachable database) fails the run either way.
+
+import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, beforeEach, describe, it } from "vitest";
+import {
+ type Checkout,
+ type E2eEnv,
+ checkout,
+ cleanupScratch,
+ e2eEnv,
+ freshSignature,
+ git,
+ map,
+ resetBackend,
+ expectSameGraph,
+ failsUntil,
+ signature,
+} from "./harness.js";
+
+let env: E2eEnv;
+
+beforeAll(() => {
+ env = e2eEnv();
+});
+
+beforeEach(async () => {
+ await resetBackend(env);
+});
+
+afterAll(() => {
+ cleanupScratch();
+});
+
+function edit(co: Checkout, rel: string, change: (text: string) => string): void {
+ const path = join(co.dir, rel);
+ const before = readFileSync(path, "utf8");
+ const after = change(before);
+ if (after === before) throw new Error(`edit of ${rel} changed nothing`);
+ writeFileSync(path, after);
+}
+
+const replaceAll = (from: string, to: string) => (text: string) => text.split(from).join(to);
+
+describe("revert to earlier content", () => {
+ it(
+ "[fails until BEW-03] A -> B -> A equals A",
+ failsUntil(["BEW-03"], async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ const a = await signature(env, co);
+
+ edit(
+ co,
+ "app/pricing.py",
+ (t) => t + "\n\ndef surcharge(amount):\n return add_tax(amount) + 100\n",
+ );
+ map(env, co);
+ edit(co, "app/pricing.py", (t) => t.slice(0, t.indexOf("\n\ndef surcharge")));
+ map(env, co);
+
+ expectSameGraph("A->B->A", await signature(env, co), a);
+ }),
+ );
+
+ it(
+ "[fails until BEW-03] rename a function and back equals the original",
+ failsUntil(["BEW-03"], async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ const a = await signature(env, co);
+
+ for (const f of ["app/utils.py", "app/repository.py"])
+ edit(co, f, replaceAll("to_snake_case", "to_snake_case_renamed"));
+ map(env, co);
+ git(co.dir, "checkout", "--", ".");
+ map(env, co);
+
+ expectSameGraph("rename and back", await signature(env, co), a);
+ }),
+ );
+
+ it(
+ "[fails until BEW-03, IN-04] delete a file and restore it equals the original",
+ failsUntil(["BEW-03", "IN-04"], async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ const a = await signature(env, co);
+
+ rmSync(join(co.dir, "app/pricing.py"));
+ map(env, co);
+ git(co.dir, "checkout", "--", "app/pricing.py");
+ map(env, co);
+
+ expectSameGraph("delete and restore", await signature(env, co), a);
+ }),
+ );
+
+ it(
+ "[fails until BEW-03, IN-04, IN-10] branch round trip equals the starting branch",
+ failsUntil(["BEW-03", "IN-04", "IN-10"], async () => {
+ const co = checkout("polyglot");
+ git(co.dir, "checkout", "-q", "-b", "feature");
+ edit(co, "app/services.py", replaceAll("def charge(", "def charge_order("));
+ edit(co, "app/services.py", replaceAll("service.charge(", "service.charge_order("));
+ edit(co, "web/src/cart.ts", replaceAll("summary()", "describe()"));
+ edit(co, "web/src/index.ts", replaceAll("cart.summary()", "cart.describe()"));
+ rmSync(join(co.dir, "app/events.py"));
+ writeFileSync(
+ join(co.dir, "app/audit.py"),
+ "from app.utils import slugify\n\n\ndef audit_key(name):\n return slugify(name)\n",
+ );
+ git(co.dir, "add", "-A");
+ git(co.dir, "commit", "-q", "-m", "feature");
+ git(co.dir, "checkout", "-q", "main");
+
+ map(env, co);
+ const main = await signature(env, co);
+ git(co.dir, "checkout", "-q", "feature");
+ map(env, co);
+ git(co.dir, "checkout", "-q", "main");
+ map(env, co);
+
+ expectSameGraph("branch round trip", await signature(env, co), main);
+ }),
+ );
+});
+
+describe("two workspaces in one backend", () => {
+ it("mapping a second workspace leaves the first one's graph alone (BEW-01, backend 1.0.31)", async () => {
+ const one = checkout("polyglot");
+ const two = checkout("polyglot-b");
+ // Both register in one IX_HOME, as two repos on one machine would.
+ const shared: Checkout = { dir: two.dir, ixHome: one.ixHome };
+
+ map(env, one);
+ const before = await signature(env, one);
+ map(env, shared);
+ await signature(env, shared); // the second workspace really was ingested
+
+ expectSameGraph("first workspace after the second maps", await signature(env, one), before);
+ });
+});
+
+describe("incremental equals fresh", () => {
+ it(
+ "[fails until IN-10] edit one Python file",
+ failsUntil(["IN-10"], async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ edit(co, "app/services.py", (t) => t + "\n# edited\n");
+ map(env, co);
+ const incremental = await signature(env, co);
+
+ expectSameGraph("python edit", incremental, await freshSignature(env, co));
+ }),
+ );
+
+ it("edit one TypeScript file", async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ edit(co, "web/src/cart.ts", (t) => t + "\n// edited\n");
+ map(env, co);
+ const incremental = await signature(env, co);
+
+ expectSameGraph("typescript edit", incremental, await freshSignature(env, co));
+ });
+
+ it(
+ "[fails until IN-04, IN-10] rename a file",
+ failsUntil(["IN-04", "IN-10"], async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ renameSync(join(co.dir, "app/events.py"), join(co.dir, "app/bus.py"));
+ for (const f of ["app/services.py", "app/api.py"])
+ edit(co, f, replaceAll("from app.events import", "from app.bus import"));
+ map(env, co);
+ const incremental = await signature(env, co);
+
+ expectSameGraph("file rename", incremental, await freshSignature(env, co));
+ }),
+ );
+
+ it("add a file", async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ writeFileSync(
+ join(co.dir, "app/refunds.py"),
+ "from app.pricing import add_tax\nfrom app.utils import format_money\n\n\ndef refund(amount):\n return format_money(-add_tax(amount))\n",
+ );
+ map(env, co);
+ const incremental = await signature(env, co);
+
+ expectSameGraph("file add", incremental, await freshSignature(env, co));
+ });
+
+ it("map twice gives the same graph", async () => {
+ const co = checkout("polyglot");
+ map(env, co);
+ const first = await signature(env, co);
+ map(env, co);
+
+ expectSameGraph("map twice", await signature(env, co), first);
+ });
+});
diff --git a/ix-cli/vitest.e2e.config.ts b/ix-cli/vitest.e2e.config.ts
new file mode 100644
index 00000000..c21bd42b
--- /dev/null
+++ b/ix-cli/vitest.e2e.config.ts
@@ -0,0 +1,16 @@
+// Copyright 2026 Ix Infrastructure Inc.
+
+import { defineConfig } from "vitest/config";
+
+// Real-backend harness (test/e2e). Kept out of `npm test`: its files end in
+// .e2e.ts, which the default config's include pattern does not match. Every
+// scenario resets one shared database, so files and tests run one at a time.
+export default defineConfig({
+ test: {
+ include: ["test/e2e/**/*.e2e.ts"],
+ fileParallelism: false,
+ sequence: { concurrent: false },
+ testTimeout: 300_000,
+ hookTimeout: 60_000,
+ },
+});