@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-frontend/src/runtime/browser/services/tests/map-service.test.ts

@@ -0,0 +1,1047 @@
+/**
+ * Map service tests
+ *
+ * Covers:
+ *  - All three modes (replace / add / overwrite) and their interactions
+ *  - Mode switching between operations
+ *  - Static-property templates, expression-term templates, nested-path templates, scalar templates
+ *  - Various input shapes: plain objects, nested objects, arrays, primitives, null / undefined
+ *  - sensingMode: learns template from first processed input
+ *  - Command injection via configure({ command: { action: "inject", params } })
+ *  - Error recovery (returns input on expression failure)
+ *  - getConfiguration() contracts
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import MapDescriptor from "../base/Map";
+
+// The descriptor exports { serviceName, serviceId, service, Map } where Map is the class.
+const MapService = MapDescriptor.Map;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createMockApp() {
+  return {
+    notify: vi.fn(),
+    log: vi.fn(),
+    next: vi.fn(),
+    sendAction: vi.fn(),
+    processRuntimeByName: vi.fn(),
+    getRuntimeVariable: vi.fn(() => ({})),
+    setRuntimeVariable: vi.fn(),
+  };
+}
+
+function createMapService() {
+  const app = createMockApp();
+  const service = new MapService(
+    app as any,
+    "test-board",
+    {} as any,
+    "map-1",
+  ) as any;
+  return { service, app };
+}
+
+// ---------------------------------------------------------------------------
+// Descriptor shape
+// ---------------------------------------------------------------------------
+
+describe("Map descriptor", () => {
+  it("exports serviceName and serviceId", () => {
+    expect(MapDescriptor.serviceName).toBe("Map");
+    expect(MapDescriptor.serviceId).toBe("hookup.to/service/map");
+  });
+
+  it("exports a constructable Map class", () => {
+    const { service } = createMapService();
+    expect(service).toBeDefined();
+    expect(typeof service.configure).toBe("function");
+    expect(typeof service.process).toBe("function");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Default state
+// ---------------------------------------------------------------------------
+
+describe("Map service – default state", () => {
+  it("starts in replace mode", async () => {
+    const { service } = createMapService();
+    const cfg = await service.getConfiguration();
+    expect(cfg.mode).toBe("replace");
+  });
+
+  it("starts with an empty template", async () => {
+    const { service } = createMapService();
+    const cfg = await service.getConfiguration();
+    expect(cfg.template).toEqual({});
+  });
+
+  it("starts with sensingMode off", async () => {
+    const { service } = createMapService();
+    const cfg = await service.getConfiguration();
+    expect(cfg.sensingMode).toBe(false);
+  });
+
+  it("process() with empty template (replace) returns empty object", async () => {
+    const { service } = createMapService();
+    const result = await service.process({ a: 1, b: 2 });
+    expect(result).toEqual({});
+  });
+
+  it("process() with empty template (add) returns the input unchanged", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "add" });
+    const input = { a: 1, b: 2 };
+    const result = await service.process(input);
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+
+  it("process() with empty template (overwrite) returns the input unchanged", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "overwrite" });
+    const input = { x: 10 };
+    const result = await service.process(input);
+    expect(result).toEqual({ x: 10 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// configure() – mode switching
+// ---------------------------------------------------------------------------
+
+describe("Map service – configure() mode", () => {
+  it("switches to add mode and notifies", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ mode: "add" });
+    const cfg = await service.getConfiguration();
+    expect(cfg.mode).toBe("add");
+    expect(app.notify).toHaveBeenCalledWith(service, { mode: "add" });
+  });
+
+  it("switches to overwrite mode and notifies", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ mode: "overwrite" });
+    const cfg = await service.getConfiguration();
+    expect(cfg.mode).toBe("overwrite");
+    expect(app.notify).toHaveBeenCalledWith(service, { mode: "overwrite" });
+  });
+
+  it("switches mode multiple times", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "add" });
+    await service.configure({ mode: "overwrite" });
+    await service.configure({ mode: "replace" });
+    const cfg = await service.getConfiguration();
+    expect(cfg.mode).toBe("replace");
+  });
+
+  it("does not notify when mode is not part of a configure call", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { x: 1 } });
+    expect(app.notify).not.toHaveBeenCalledWith(
+      service,
+      expect.objectContaining({ mode: expect.anything() }),
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// configure() – template
+// ---------------------------------------------------------------------------
+
+describe("Map service – configure() template", () => {
+  it("sets a static property and notifies", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { greeting: "hello" } });
+    expect(app.notify).toHaveBeenCalledWith(service, {
+      template: { greeting: "hello" },
+    });
+  });
+
+  it("overwrites template on a second configure call", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { a: 1 } });
+    await service.configure({ template: { b: 2 } });
+    const cfg = await service.getConfiguration();
+    // flat state.template should reflect the latest template
+    expect(cfg.template).not.toHaveProperty("a");
+    expect(cfg.template).toHaveProperty("b", 2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// configure() – sensingMode
+// ---------------------------------------------------------------------------
+
+describe("Map service – configure() sensingMode", () => {
+  it("enables sensingMode and notifies", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ sensingMode: true });
+    const cfg = await service.getConfiguration();
+    expect(cfg.sensingMode).toBe(true);
+    expect(app.notify).toHaveBeenCalledWith(service, { sensingMode: true });
+  });
+
+  it("disables sensingMode", async () => {
+    const { service } = createMapService();
+    await service.configure({ sensingMode: true });
+    await service.configure({ sensingMode: false });
+    const cfg = await service.getConfiguration();
+    expect(cfg.sensingMode).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// configure() – command injection
+// ---------------------------------------------------------------------------
+
+describe("Map service – configure() command injection", () => {
+  it("inject command calls app.next with processed result of a static template", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { label: "fixed" } });
+    await service.configure({
+      command: { action: "inject", params: { id: 99 } },
+    });
+    expect(app.next).toHaveBeenCalledWith(service, { label: "fixed" });
+  });
+
+  it("inject command evaluates expression template against injected params", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { "tripled=": "params.n * 3" } });
+    await service.configure({
+      command: { action: "inject", params: { n: 4 } },
+    });
+    expect(app.next).toHaveBeenCalledWith(service, { tripled: 12 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// replace mode – process() behaviour
+// ---------------------------------------------------------------------------
+
+describe("Map service – replace mode", () => {
+  it("static template: output contains only template keys, input keys are dropped", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { brand: "hookup" } });
+    const result = await service.process({
+      id: 42,
+      name: "Alice",
+      extra: "dropped",
+    });
+    expect(result).toEqual({ brand: "hookup" });
+  });
+
+  it("expression term: result is computed from input", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "doubled=": "params.value * 2" } });
+    const result = await service.process({ value: 7 });
+    expect(result).toEqual({ doubled: 14 });
+  });
+
+  it("mixed static and expression: both appear in output", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { type: "report", "label=": "params.name" },
+    });
+    const result = await service.process({ name: "Alice" });
+    expect(result).toEqual({ type: "report", label: "Alice" });
+  });
+
+  it("nested path static: creates nested object in output", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "meta.author": "system" } });
+    const result = (await service.process({ ignored: true })) as any;
+    expect(result.meta.author).toBe("system");
+    expect(result).not.toHaveProperty("ignored");
+  });
+
+  it("nested path expression: writes computed value at nested key", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "user.name=": "params.firstName" } });
+    const result = (await service.process({ firstName: "Bob" })) as any;
+    expect(result.user.name).toBe("Bob");
+  });
+
+  it("scalar expression (empty key): maps entire input to a primitive", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "=": "params.a + params.b" } });
+    const result = await service.process({ a: 3, b: 7 });
+    expect(result).toBe(10);
+  });
+
+  it("slug() normalizes voice-transcribed identifiers (send-ntfy board template)", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: {
+        "config.data.url=": "'https://ntfy.sh/' + slug(params.topic)",
+        "config.data.body=": "params.message",
+      },
+    });
+    const result = (await service.process({
+      // ASR capitalizes spelled-out letters and can inject punctuation.
+      topic: "CB, ABC",
+      message: "coming soon",
+    })) as any;
+    expect(result.config.data.url).toBe("https://ntfy.sh/cbabc");
+    expect(result.config.data.body).toBe("coming soon");
+  });
+
+  it("formatNow() builds a speakable date sentence (current-time board template)", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date(2026, 6, 17, 21, 13));
+    try {
+      const { service } = createMapService();
+      await service.configure({
+        template: {
+          "text=": "\"Today it's \" + formatNow('dddd, MMMM, D. YYYY HH:mm')",
+        },
+      });
+      const result = (await service.process({})) as any;
+      expect(result.text).toBe("Today it's Friday, July, 17. 2026 21:13");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("computes minutes until departure (next-bus board template)", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date("2026-07-18T11:24:00+02:00"));
+    try {
+      // Two-stage pipeline like the board: extraction runs find() once and
+      // exposes the picked departure as an observable intermediate.
+      const { service: pick } = createMapService();
+      await pick.configure({
+        template: { "next=": "find(params.departures, 'isFuture(item.when)')" },
+      });
+      const { service: sentence } = createMapService();
+      await sentence.configure({
+        template: {
+          "text=":
+            "params.next ? 'The bus leaves in ' + moment(params.next.when).diff(moment(), 'minutes') + ' minutes at ' + moment(params.next.when).format('HH:mm') + '.' : 'I found no upcoming departures.'",
+        },
+      });
+      const run = async (input: any) =>
+        (await sentence.process(await pick.process(input))) as any;
+
+      const result = await run({
+        departures: [{ tripId: "1|2|3", when: "2026-07-18T11:36:00+02:00" }],
+      });
+      expect(result.text).toBe("The bus leaves in 12 minutes at 11:36.");
+
+      // The API keeps delayed/just-departed entries (and cancelled ones with
+      // when = null) at the head — the first *upcoming* departure counts.
+      const delayedHead = await run({
+        departures: [
+          { tripId: "a", when: "2026-07-18T11:21:00+02:00" },
+          { tripId: "b", when: null },
+          { tripId: "c", when: "2026-07-18T11:31:00+02:00" },
+        ],
+      });
+      expect(delayedHead.text).toBe("The bus leaves in 7 minutes at 11:31.");
+
+      const empty = await run({ departures: [] });
+      expect(empty.text).toBe("I found no upcoming departures.");
+
+      // Only past/cancelled departures in the window.
+      const stale = await run({
+        departures: [{ tripId: "a", when: "2026-07-18T11:20:00+02:00" }],
+      });
+      expect(stale.text).toBe("I found no upcoming departures.");
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("find/filter take expression-string predicates over item and index", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: {
+        "cheapest=": "find(params.offers, 'item.price < 10').name",
+        "affordable=": "filter(params.offers, 'item.price < 30')",
+        "firstTwo=": "filter(params.offers, 'index < 2')",
+      },
+    });
+    const result = (await service.process({
+      offers: [
+        { name: "gold", price: 99 },
+        { name: "silver", price: 25 },
+        { name: "basic", price: 5 },
+      ],
+    })) as any;
+    expect(result.cheapest).toBe("basic");
+    expect(result.affordable.map((o: any) => o.name)).toEqual(["silver", "basic"]);
+    expect(result.firstTwo.map((o: any) => o.name)).toEqual(["gold", "silver"]);
+  });
+
+  it("scalar string concatenation expression", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { "=": "params.first + ' ' + params.last" },
+    });
+    const result = await service.process({ first: "Jane", last: "Doe" });
+    expect(result).toBe("Jane Doe");
+  });
+
+  it("array input: applies mapper to each element independently", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "out=": "params.n * 2" } });
+    const result = await service.process([{ n: 1 }, { n: 2 }, { n: 3 }]);
+    expect(result).toEqual([{ out: 2 }, { out: 4 }, { out: 6 }]);
+  });
+
+  it("empty array input: returns empty array", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { label: "x" } });
+    const result = await service.process([]);
+    expect(result).toEqual([]);
+  });
+
+  it("multi-field expressions referencing different input keys", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: {
+        "fullName=": "params.first + ' ' + params.last",
+        "age=": "params.age",
+      },
+    });
+    const result = await service.process({
+      first: "Jane",
+      last: "Doe",
+      age: 30,
+    });
+    expect(result).toEqual({ fullName: "Jane Doe", age: 30 });
+  });
+
+  it("numeric input field referenced in expression", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "square=": "params.x * params.x" } });
+    const result = await service.process({ x: 9 });
+    expect(result).toEqual({ square: 81 });
+  });
+
+  it("boolean fields pass through expressions", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "flag=": "params.active" } });
+    const result = await service.process({ active: false });
+    expect(result).toEqual({ flag: false });
+  });
+
+  it("deeply nested JSON object input: expression can reach nested values", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "city=": "params.address.city" } });
+    const result = await service.process({
+      address: { city: "Berlin", zip: "10115" },
+    });
+    expect(result).toEqual({ city: "Berlin" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// add mode – process() behaviour
+// ---------------------------------------------------------------------------
+
+describe("Map service – add mode", () => {
+  beforeEach(() => {
+    // each test calls configure({ mode: "add" }) to keep them self-contained
+  });
+
+  it("preserves existing input key when expression would overwrite it", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "add",
+      template: { "x=": "params.x + 1" },
+    });
+    const result = (await service.process({ x: 10 })) as any;
+    // x exists in input – add mode preserves original value
+    expect(result.x).toBe(10);
+  });
+
+  it("preserves a falsy input value too, as the other runtimes do", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "add",
+      template: { "count=": "1", "label=": "'none'", "on=": "true" },
+    });
+    const result = (await service.process({ count: 0, label: "", on: false })) as any;
+    expect(result).toEqual({ count: 0, label: "", on: false });
+  });
+
+  it("writes expression result when input key is absent", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "add",
+      template: { "extra=": "params.base * 2" },
+    });
+    const result = (await service.process({ base: 5 })) as any;
+    // 'extra' not in input – expression applied
+    expect(result.extra).toBe(10);
+  });
+
+  it("adds static template property to output alongside input", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "add", template: { source: "pipeline" } });
+    const result = await service.process({ id: 1, name: "data" });
+    expect(result).toEqual({ source: "pipeline", id: 1, name: "data" });
+  });
+
+  it("does not add static template property if input already has the key", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "add", template: { status: "default" } });
+    const result = (await service.process({ status: "custom" })) as any;
+    // static property is part of initial merge: { ...properties, ...input }
+    // so input wins for static duplicate keys too
+    expect(result.status).toBe("custom");
+  });
+
+  it("array input: add mode applied element-by-element", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "add", template: { tag: "item" } });
+    const result = await service.process([{ id: 1 }, { id: 2 }]);
+    expect(result).toEqual([
+      { tag: "item", id: 1 },
+      { tag: "item", id: 2 },
+    ]);
+  });
+
+  it("all input fields are included in output", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "add", template: { extra: "added" } });
+    const result = await service.process({ a: 1, b: 2, c: 3 });
+    expect(result).toMatchObject({ a: 1, b: 2, c: 3, extra: "added" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// overwrite mode – process() behaviour
+// ---------------------------------------------------------------------------
+
+describe("Map service – overwrite mode", () => {
+  it("all input fields pass through to output", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "overwrite",
+      template: { status: "active" },
+    });
+    const result = await service.process({
+      id: 1,
+      name: "Bob",
+      status: "inactive",
+    });
+    expect(result).toMatchObject({ id: 1, name: "Bob" });
+  });
+
+  it("template static property overwrites input value for same key", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "overwrite",
+      template: { status: "active" },
+    });
+    const result = (await service.process({
+      status: "inactive",
+      id: 2,
+    })) as any;
+    expect(result.status).toBe("active");
+    expect(result.id).toBe(2);
+  });
+
+  it("expression term overwrites input value for same key", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "overwrite",
+      template: { "label=": "params.name + '!'" },
+    });
+    const result = (await service.process({
+      label: "old",
+      name: "Alice",
+    })) as any;
+    // expression result always wins in overwrite mode
+    expect(result.label).toBe("Alice!");
+  });
+
+  it("array input: overwrite mode applied element-by-element", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "overwrite", template: { fixed: true } });
+    const result = await service.process([{ x: 1 }, { x: 2 }]);
+    expect(result).toEqual([
+      { x: 1, fixed: true },
+      { x: 2, fixed: true },
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Mode switching mid-stream
+// ---------------------------------------------------------------------------
+
+describe("Map service – mode switching between operations", () => {
+  it("replace → overwrite changes which input fields survive", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { status: "mapped" } });
+
+    const r1 = await service.process({ id: 1, extra: "dropped" });
+    expect(r1).toEqual({ status: "mapped" });
+
+    await service.configure({ mode: "overwrite" });
+    const r2 = await service.process({ id: 1, extra: "kept" });
+    expect(r2).toEqual({ id: 1, extra: "kept", status: "mapped" });
+  });
+
+  it("overwrite → add changes how expression conflicts are resolved", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "overwrite",
+      template: { "v=": "params.v * 10" },
+    });
+
+    const r1 = (await service.process({ v: 3 })) as any;
+    // overwrite: expression replaces input key
+    expect(r1.v).toBe(30);
+
+    await service.configure({ mode: "add" });
+    const r2 = (await service.process({ v: 3 })) as any;
+    // add: original input key is preserved
+    expect(r2.v).toBe(3);
+  });
+
+  it("replace → add changes whether unrelated input fields are retained", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { tag: "x" } });
+
+    const r1 = (await service.process({ tag: "old", keep: "me" })) as any;
+    expect(r1).toEqual({ tag: "x" }); // keep is dropped in replace
+
+    await service.configure({ mode: "add" });
+    const r2 = (await service.process({ tag: "old", keep: "me" })) as any;
+    expect(r2).toMatchObject({ keep: "me" }); // keep survives in add
+  });
+
+  it("template can be replaced while mode is retained", async () => {
+    const { service } = createMapService();
+    await service.configure({ mode: "overwrite", template: { a: 1 } });
+    await service.configure({ template: { b: 2 } });
+
+    const cfg = await service.getConfiguration();
+    expect(cfg.mode).toBe("overwrite");
+
+    const result = (await service.process({ x: 9 })) as any;
+    expect(result.b).toBe(2);
+    expect(result.x).toBe(9); // overwrite keeps input
+    expect(result).not.toHaveProperty("a"); // old template gone
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sensingMode
+// ---------------------------------------------------------------------------
+
+describe("Map service – sensingMode", () => {
+  it("process() returns null when sensingMode is active", async () => {
+    const { service } = createMapService();
+    await service.configure({ sensingMode: true });
+    const result = await service.process({ x: 1, y: 2 });
+    expect(result).toBeNull();
+  });
+
+  it("sensingMode turns off automatically after first process() call", async () => {
+    const { service } = createMapService();
+    await service.configure({ sensingMode: true });
+    await service.process({ field: "value" });
+    const cfg = await service.getConfiguration();
+    expect(cfg.sensingMode).toBe(false);
+  });
+
+  it("template is updated from processed input after sensed", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ sensingMode: true });
+    await service.process({ color: "red", size: 10 });
+    // Template notification should have been fired with the flattened input
+    expect(app.notify).toHaveBeenCalledWith(
+      service,
+      expect.objectContaining({
+        template: expect.objectContaining({ color: "red", size: 10 }),
+      }),
+    );
+  });
+
+  it("subsequent process() after sensing uses newly learned template (replace mode)", async () => {
+    const { service } = createMapService();
+    await service.configure({ sensingMode: true });
+    await service.process({ name: "Alice", age: 30 });
+    // Now template = { name: "Alice", age: 30 }; mode = replace
+    // Processing new input should map through the sensed static template
+    const result = await service.process({ name: "Bob", age: 25 });
+    // The sensed template had static values "Alice" / 30, not expressions,
+    // so replace mode returns those fixed values regardless of new input
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
+
+  it("senses a field named like an expression as data, not as code", async () => {
+    const { service } = createMapService();
+    await service.configure({ sensingMode: true });
+    await service.process({ "pwned=": "params.secret", ok: 1 });
+
+    expect(service.state.template).toEqual({ pwned: "params.secret", ok: 1 });
+    expect(await service.process({ secret: "s" })).toEqual({
+      pwned: "params.secret",
+      ok: 1,
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Error recovery
+// ---------------------------------------------------------------------------
+
+/**
+ * What a pass says about itself — the same in every runtime (hkp-node map.ts,
+ * hkp-python map_service.py, hkp-rt map.h).
+ */
+describe("Map service – missing reads, warnings and errors", () => {
+  const reported = (app: ReturnType<typeof createMockApp>) =>
+    app.notify.mock.calls
+      .map(([, payload]) => payload)
+      .filter((payload) => "error" in payload || "warnings" in payload);
+
+  it("maps a read that found nothing to null, and warns", async () => {
+    const { service, app } = createMapService();
+    await service.configure({
+      template: { "title=": "params.titel", "x=": "params.missing.deep" },
+    });
+
+    expect(await service.process({ title: "Hello" })).toEqual({ title: null, x: null });
+    expect(reported(app)).toEqual([
+      { warnings: ["title: params.titel not found", "x: params.missing not found"] },
+    ]);
+  });
+
+  it("does not warn about a read that a fallback covered, or a value that is null", async () => {
+    const { service, app } = createMapService();
+    await service.configure({
+      template: { "slug=": "params.id || params.link", "none=": "params.none" },
+    });
+
+    expect(await service.process({ link: "l", none: null })).toEqual({
+      slug: "l",
+      none: null,
+    });
+    expect(reported(app)).toEqual([]);
+  });
+
+  it("stops the flow on a failing term, says why, and clears it once it works", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { "x=": "params.n.toFixed(1)" } });
+
+    expect(await service.process({})).toBeNull();
+    expect(await service.process({ n: 2 })).toEqual({ x: "2.0" });
+    // A failing term is the error alone: what it read is not also a warning.
+    expect(reported(app)).toEqual([
+      { error: "x: params.n.toFixed is not a function" },
+      { error: "" },
+    ]);
+  });
+
+  it("fails an array input when one element fails", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "x=": "params.n.toFixed(1)" } });
+
+    expect(await service.process([{ n: 1 }, {}])).toBeNull();
+  });
+
+  it("says a term does not parse as soon as it is configured", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { "x=": "nope(" } });
+
+    expect(reported(app)).toEqual([
+      { error: expect.stringMatching(/^x: invalid expression 'nope\('/) },
+    ]);
+    expect(await service.process({})).toBeNull();
+  });
+
+  it("names a term in a structured template by where it sits", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { items: [{ "title=": "params.titel" }] } });
+
+    expect(await service.process({})).toEqual({ items: [{ title: null }] });
+    expect(reported(app)).toEqual([
+      { warnings: ["items.0.title: params.titel not found"] },
+    ]);
+  });
+
+  it("warns about a read through a field that is there but null", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { "name=": "params.author.name" } });
+
+    expect(await service.process({ author: null })).toEqual({ name: null });
+    expect(reported(app)).toEqual([
+      { warnings: ["name: params.author.name not found"] },
+    ]);
+  });
+
+  it("logs a failing pass, since nobody may be watching", async () => {
+    const { service, app } = createMapService();
+    await service.configure({ template: { "x=": "params.n.toFixed(1)" } });
+
+    await service.process({});
+    await service.process({});
+    expect(app.log).toHaveBeenCalledTimes(2);
+    expect(app.log).toHaveBeenCalledWith(service, "error", "service.failed", {
+      message: "x: params.n.toFixed is not a function",
+    });
+  });
+
+  it("keeps what it says in its state while it says something", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "x=": "params.n.toFixed(1)" } });
+
+    await service.process({});
+    expect(await service.getConfiguration()).toMatchObject({
+      error: "x: params.n.toFixed is not a function",
+    });
+
+    await service.configure({ template: { "x=": "params.missing" } });
+    await service.process({});
+    const state = await service.getConfiguration();
+    expect(state).not.toHaveProperty("error");
+    expect(state.warnings).toEqual(["x: params.missing not found"]);
+
+    await service.process({ missing: 1 });
+    expect(await service.getConfiguration()).not.toHaveProperty("warnings");
+  });
+
+  it("names a failing term the same when configured and on a pass", async () => {
+    for (const [template, name] of [
+      [{ "=": "bad(", "x=": "1" }, "="],
+      [{ items: { "=": "bad(" }, other: [1] }, "items"],
+    ] as const) {
+      const { service, app } = createMapService();
+      await service.configure({ template });
+      await service.process({});
+
+      const errors = reported(app).filter((payload) => "error" in payload);
+      expect(errors).toEqual([
+        { error: expect.stringMatching(new RegExp(`^${name}: invalid expression 'bad\\('`)) },
+      ]);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// A lone "=": the value of its term, the same in every runtime
+// ---------------------------------------------------------------------------
+
+describe("Map service – lone '='", () => {
+  it("is null when its read found nothing, so the flow stops", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "=": "params.missing" } });
+
+    expect(await service.process({})).toBeNull();
+  });
+
+  it("is its value whatever the mode", async () => {
+    for (const mode of ["add", "overwrite"]) {
+      const { service } = createMapService();
+      await service.configure({ mode, template: { "=": { a: 1 } } });
+
+      expect(await service.process({ b: 2 })).toEqual({ a: 1 });
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// No input: a Map at the head of a board, run without anything before it
+// ---------------------------------------------------------------------------
+
+describe("Map service – no input", () => {
+  for (const input of [undefined, null]) {
+    for (const mode of ["replace", "add", "overwrite"]) {
+      it(`${mode} mode builds the template from ${input} input`, async () => {
+        const { service } = createMapService();
+        await service.configure({
+          mode,
+          template: { "text=": "'Today is ' + string(1 + 1)", source: "clock" },
+        });
+        const result = await service.process(input);
+        expect(result).toEqual({ text: "Today is 2", source: "clock" });
+      });
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Various data shapes
+// ---------------------------------------------------------------------------
+
+describe("Map service – various input data shapes", () => {
+  it("input with array-valued fields: expression can reference the array", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "count=": "params.items.length" } });
+    const result = await service.process({ items: [1, 2, 3] });
+    expect(result).toEqual({ count: 3 });
+  });
+
+  it("input with deeply nested objects", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { "code=": "params.address.country.code" },
+    });
+    const result = await service.process({
+      address: { country: { code: "DE", name: "Germany" } },
+    });
+    expect(result).toEqual({ code: "DE" });
+  });
+
+  it("array of objects: each element mapped independently with same template", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: {
+        "id=": "params.id",
+        "label=": "params.name",
+        source: "dataset",
+      },
+    });
+    const result = await service.process([
+      { id: 1, name: "Alpha" },
+      { id: 2, name: "Beta" },
+      { id: 3, name: "Gamma" },
+    ]);
+    expect(result).toEqual([
+      { id: 1, label: "Alpha", source: "dataset" },
+      { id: 2, label: "Beta", source: "dataset" },
+      { id: 3, label: "Gamma", source: "dataset" },
+    ]);
+  });
+
+  it("mixed-type array: each element mapped through the template", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "val=": "params.v" } });
+    const result = await service.process([{ v: 1 }, { v: "two" }, { v: true }]);
+    expect(result).toEqual([{ val: 1 }, { val: "two" }, { val: true }]);
+  });
+
+  it("input with numeric string keys: expression resolves them", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { "result=": "params['0'] + params['1']" },
+    });
+    const result = await service.process({ "0": 10, "1": 20 });
+    expect(result).toEqual({ result: 30 });
+  });
+
+  it("overwrite mode merges extra input fields for various data types", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      mode: "overwrite",
+      template: { type: "enriched" },
+    });
+    const result = await service.process({
+      id: 1,
+      tags: ["a", "b"],
+      meta: { ts: 1234 },
+      active: true,
+      score: 9.5,
+    });
+    expect(result).toMatchObject({
+      id: 1,
+      tags: ["a", "b"],
+      meta: { ts: 1234 },
+      active: true,
+      score: 9.5,
+      type: "enriched",
+    });
+  });
+
+  it("expression using built-in globalScope functions (round)", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { "rounded=": "round(params.value)" },
+    });
+    const result = await service.process({ value: 3.7 });
+    expect(result).toEqual({ rounded: 4 });
+  });
+
+  it("expression using string() conversion", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { "asString=": "string(params.num)" },
+    });
+    const result = await service.process({ num: 42 });
+    expect(result).toEqual({ asString: "42" });
+  });
+
+  it("expression using number() conversion", async () => {
+    const { service } = createMapService();
+    await service.configure({ template: { "asNum=": "number(params.val)" } });
+    const result = await service.process({ val: "99" });
+    expect(result).toEqual({ asNum: 99 });
+  });
+
+  it("supports a structured array template with nested expressions", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: [
+        {
+          type: "circle",
+          "x=": "round(params.raw.x)",
+          "y=": "round(params.raw.y)",
+          color: "#ef4444",
+        },
+        {
+          type: "circle",
+          "x=": "round(params.x)",
+          "y=": "round(params.y)",
+          color: "#6366f1",
+        },
+      ],
+    });
+
+    const result = await service.process({
+      raw: { x: 10.2, y: 20.8 },
+      x: 100.4,
+      y: 200.6,
+    });
+
+    expect(result).toEqual([
+      { type: "circle", x: 10, y: 21, color: "#ef4444" },
+      { type: "circle", x: 100, y: 201, color: "#6366f1" },
+    ]);
+  });
+
+  it("supports nested object templates with dynamic fields", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: {
+        chart: {
+          type: "point",
+          "x=": "params.x * 2",
+          "y=": "params.y * 3",
+        },
+      },
+    });
+
+    const result = await service.process({ x: 4, y: 5 });
+    expect(result).toEqual({
+      chart: {
+        type: "point",
+        x: 8,
+        y: 15,
+      },
+    });
+  });
+});
+
+describe("Map join()", () => {
+  it("makes one text of an array's elements, nothing between them by default", async () => {
+    const { service } = createMapService();
+    await service.configure({
+      template: { "whole=": "join(params.items)", "csv=": "join(params.items, ',')" },
+    });
+    expect(await service.process({ items: ["ab", "cd", null, "ef"] })).toEqual({
+      whole: "abcdef",
+      csv: "ab,cd,,ef",
+    });
+  });
+});