@specific.dev/spectest 0.38.0 → 0.41.0

package/src/harness/protocol.test.ts

@@ -0,0 +1,148 @@
+/**
+ * The TypeScript half of the protocol's anti-drift contract.
+ *
+ * `protocols/supervisor-harness/frames.json` is the single definition of the
+ * supervisor↔harness messages. This suite and
+ * `crates/spectest-vm-agent/src/protocol.rs`'s tests both parse it, so a
+ * field added on one side and forgotten on the other fails here rather
+ * than in a VM — the failure mode the `config.rs` ↔ `sdk/src/index.ts`
+ * mirrored pair had no defence against.
+ *
+ * Run with `bun test` from `sdk/`.
+ */
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  KNOWN_METHODS,
+  PROTOCOL_VERSION,
+  decodeFrame,
+  encodeFrame,
+  fail,
+  ok,
+  type Frame,
+  type Hello,
+} from "./protocol";
+
+const FIXTURES = join(import.meta.dir, "../../../protocols/supervisor-harness/frames.json");
+
+function fixtures(): { name: string; frame: unknown }[] {
+  const doc = JSON.parse(readFileSync(FIXTURES, "utf8"));
+  return doc.frames;
+}
+
+describe("shared fixtures", () => {
+  test("the fixture file is reachable and non-empty", () => {
+    expect(fixtures().length).toBeGreaterThan(0);
+  });
+
+  test("every shared fixture decodes", () => {
+    for (const { name, frame } of fixtures()) {
+      const line = JSON.stringify(frame);
+      expect(() => decodeFrame(line), `fixture ${name}`).not.toThrow();
+    }
+  });
+
+  test("every fixture round-trips through encode", () => {
+    for (const { name, frame } of fixtures()) {
+      const decoded = decodeFrame(JSON.stringify(frame));
+      const line = encodeFrame(decoded);
+      expect(line.endsWith("\n"), `fixture ${name} must be newline-terminated`).toBe(true);
+      expect(line.trimEnd().includes("\n"), `fixture ${name} must be one line`).toBe(false);
+      expect(() => decodeFrame(line.trimEnd()), `fixture ${name} re-decode`).not.toThrow();
+    }
+  });
+
+  /** Catches the drift this file exists to prevent: a method used in the
+   *  fixtures that this build never learned about. */
+  test("every method used by a request fixture is known here", () => {
+    for (const { name, frame } of fixtures()) {
+      const f = frame as { kind: string; method?: string };
+      if (f.kind !== "request" && f.kind !== "event") continue;
+      if (name === "unknown-method-is-parseable") continue; // deliberately unknown
+      expect(KNOWN_METHODS.has(f.method!), `fixture ${name} uses unknown method ${f.method}`).toBe(
+        true,
+      );
+    }
+  });
+
+  test("the handshake fixture matches this build's version", () => {
+    const hello = fixtures().find((f) => f.name === "hello-request")!;
+    const params = (hello.frame as { params: Hello }).params;
+    expect(params.protocolVersion).toBe(PROTOCOL_VERSION);
+    // The capability slot must exist even when empty — a release that
+    // announces nothing can only ever be treated as "oldest".
+    expect(Array.isArray(params.capabilities)).toBe(true);
+  });
+});
+
+describe("forward compatibility", () => {
+  /** A newer peer's extra fields must survive, not be rejected or stripped:
+   *  a frame this build forwards should not lose data it didn't understand. */
+  test("unknown fields are ignored and preserved", () => {
+    const line = JSON.stringify({
+      kind: "request",
+      id: "1",
+      method: "run",
+      params: { caseId: "a", laterField: { x: 1 } },
+      alsoLater: 42,
+    });
+    const frame = decodeFrame(line) as Frame & { alsoLater?: number };
+    expect(frame.kind).toBe("request");
+    expect(frame.alsoLater).toBe(42);
+    expect((frame as { params: Record<string, unknown> }).params.laterField).toEqual({ x: 1 });
+  });
+
+  /** Parsing and dispatch are separate concerns. Dropping the frame would
+   *  hang the sender forever. */
+  test("an unknown method parses so it can be answered with an error", () => {
+    const frame = decodeFrame(
+      JSON.stringify({ kind: "request", id: "11", method: "somethingInventedLater", params: {} }),
+    );
+    expect(frame.kind).toBe("request");
+    const req = frame as { id: string; method: string };
+    expect(req.id).toBe("11");
+    expect(KNOWN_METHODS.has(req.method)).toBe(false);
+    // …and the id survives, which is what makes the error correlatable.
+    expect(fail(req.id, "unsupported method", "unknown_method").id).toBe("11");
+  });
+
+  test("hello parses with capabilities absent (an older peer)", () => {
+    const frame = decodeFrame(
+      JSON.stringify({ kind: "request", id: "1", method: "hello", params: { protocolVersion: 1 } }),
+    ) as unknown as { params: Hello };
+    expect(frame.params.protocolVersion).toBe(1);
+    expect(frame.params.capabilities).toBeUndefined();
+  });
+});
+
+describe("routing failures", () => {
+  test.each([
+    ["malformed JSON", "{not json"],
+    ["not an object", '"a string"'],
+    ["unknown frame kind", '{"kind":"telepathy"}'],
+    ["request with no id", '{"kind":"request","method":"run"}'],
+    ["request with no method", '{"kind":"request","id":"1"}'],
+    ["response with no ok", '{"kind":"response","id":"1"}'],
+    ["event with no method", '{"kind":"event"}'],
+  ])("%s is rejected", (_name, line) => {
+    expect(() => decodeFrame(line)).toThrow();
+  });
+});
+
+describe("replies", () => {
+  test("ok carries the id and result", () => {
+    expect(ok("7", { a: 1 })).toEqual({ kind: "response", id: "7", ok: true, result: { a: 1 } });
+  });
+
+  test("fail always carries the id, so a caller is never left waiting", () => {
+    expect(fail("7", "boom")).toEqual({
+      kind: "response",
+      id: "7",
+      ok: false,
+      error: { message: "boom" },
+    });
+    expect(fail("7", "boom", "c")!.error!.code).toBe("c");
+  });
+});

package/src/harness/protocol.ts

@@ -0,0 +1,163 @@
+/**
+ * The supervisor↔harness protocol — TypeScript half.
+ *
+ * Mirrors `crates/spectest-vm-agent/src/protocol.rs`. Read that file's
+ * header for the design; the rules that matter when editing this one:
+ *
+ *  - `hello` carries a protocol version AND a capability list in both
+ *    directions, from the first release. A release that announces nothing
+ *    can only ever be treated as "oldest".
+ *  - **Unknown fields are ignored in both directions.** Nothing here
+ *    validates against a closed field set, deliberately — that is the
+ *    mistake `config.rs` made, where a newer SDK's config was rejected
+ *    outright by an older server.
+ *  - A message never changes meaning. It only gains optional fields.
+ *  - An unrecognised *method* must still parse, so the receiver can answer
+ *    with an error instead of dropping the frame and hanging the sender.
+ *
+ * Anti-drift: the messages are defined once in
+ * `protocols/supervisor-harness/frames.json`, and both this module's test suite and
+ * the Rust one parse that file. A field added on one side and forgotten on
+ * the other fails there rather than in a VM.
+ */
+
+/** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
+export const PROTOCOL_VERSION = 1;
+
+/** Methods either side can send. */
+export type Method =
+  // down: supervisor → harness
+  | "hello"
+  | "load"
+  | "loadTests"
+  | "fingerprint"
+  | "bootstrap"
+  | "run"
+  | "eval"
+  | "teardown"
+  | "shutdown"
+  // up: harness → supervisor
+  | "createArtifact"
+  | "completeArtifact"
+  | "progress"
+  | "step";
+
+/** Methods this build knows how to dispatch. A method outside this set still
+ *  *parses* — it is answered with an error, never dropped. */
+export const KNOWN_METHODS: ReadonlySet<string> = new Set<Method>([
+  "hello",
+  "load",
+  "loadTests",
+  "fingerprint",
+  "bootstrap",
+  "run",
+  "eval",
+  "teardown",
+  "shutdown",
+  "createArtifact",
+  "completeArtifact",
+  "progress",
+  "step",
+]);
+
+export interface ProtocolError {
+  message: string;
+  code?: string;
+}
+
+export interface RequestFrame {
+  kind: "request";
+  /** Correlates the response. */
+  id: string;
+  /** Typed as `string`, not `Method`: a newer peer's method must parse. */
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface ResponseFrame {
+  kind: "response";
+  id: string;
+  ok: boolean;
+  result?: Record<string, unknown>;
+  error?: ProtocolError;
+}
+
+/** Fire-and-forget. No id, no reply — progress that blocked on an ack would
+ *  make the UI a correctness dependency. */
+export interface EventFrame {
+  kind: "event";
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export type Frame = RequestFrame | ResponseFrame | EventFrame;
+
+/** `hello` payload, sent in both directions. `sdkVersion` is on the
+ *  harness's reply only. */
+export interface Hello {
+  protocolVersion: number;
+  capabilities?: string[];
+  sdkVersion?: string;
+}
+
+/** One contribution to the L2 declared cache key. The supervisor hashes
+ *  these without interpreting them — a fingerprint it could interpret
+ *  would just be the schema coupling again. */
+export interface Contribution {
+  id: string;
+  kind: string;
+  key: string;
+}
+
+/**
+ * Parse one NDJSON line.
+ *
+ * Throws only on frames that cannot be *routed* — malformed JSON, or a
+ * missing `kind`/`id`/`method`. An unknown method is not such a case: it
+ * parses, and the dispatcher answers with an error. Unknown *fields* are
+ * left untouched on the returned object rather than stripped, so a value
+ * this build ignores still round-trips if forwarded.
+ */
+export function decodeFrame(line: string): Frame {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(line);
+  } catch (e) {
+    throw new Error(`harness protocol: malformed JSON frame: ${(e as Error).message}`);
+  }
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("harness protocol: frame is not an object");
+  }
+  const f = raw as Record<string, unknown>;
+  switch (f.kind) {
+    case "request":
+      if (typeof f.id !== "string") throw new Error("harness protocol: request has no id");
+      if (typeof f.method !== "string") throw new Error("harness protocol: request has no method");
+      return f as unknown as RequestFrame;
+    case "response":
+      if (typeof f.id !== "string") throw new Error("harness protocol: response has no id");
+      if (typeof f.ok !== "boolean") throw new Error("harness protocol: response has no ok");
+      return f as unknown as ResponseFrame;
+    case "event":
+      if (typeof f.method !== "string") throw new Error("harness protocol: event has no method");
+      return f as unknown as EventFrame;
+    default:
+      throw new Error(`harness protocol: unknown frame kind ${JSON.stringify(f.kind)}`);
+  }
+}
+
+/** Encode one frame as a single NDJSON line, newline included. */
+export function encodeFrame(frame: Frame): string {
+  return `${JSON.stringify(frame)}\n`;
+}
+
+/** A successful reply to `id`. */
+export function ok(id: string, result: Record<string, unknown> = {}): ResponseFrame {
+  return { kind: "response", id, ok: true, result };
+}
+
+/** A failed reply to `id`. Always carries the id: a request that failed must
+ *  never leave its caller waiting. */
+export function fail(id: string, message: string, code?: string): ResponseFrame {
+  return { kind: "response", id, ok: false, error: code ? { message, code } : { message } };
+}

package/src/harness/ready-poll.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  RAMP_DEFAULT,
+  RAMP_EXEC,
+  delayForAttempt,
+  pollUntilReady,
+  rampFor,
+} from "./ready-poll";
+
+/** A controllable clock, so timing rules are asserted rather than waited on. */
+function fakeClock() {
+  let t = 1_000;
+  return {
+    now: () => t,
+    sleep: async (ms: number) => {
+      t += ms;
+    },
+    advance: (ms: number) => {
+      t += ms;
+    },
+  };
+}
+
+describe("ramp selection", () => {
+  test("exec probes start slower, because each attempt spawns a docker exec", () => {
+    expect(rampFor("exec")).toEqual(RAMP_EXEC);
+    expect(rampFor("tcp")).toEqual(RAMP_DEFAULT);
+    expect(rampFor("http")).toEqual(RAMP_DEFAULT);
+    expect(RAMP_EXEC[0]).toBeGreaterThan(RAMP_DEFAULT[0]!);
+  });
+
+  /** The first probes are fast so a service that is ready in 60ms is
+   *  reported at ~60ms rather than rounded up to a flat interval —
+   *  an error that compounds down a dependsOn chain. */
+  test("the ramp starts small and increases", () => {
+    for (let i = 1; i < RAMP_DEFAULT.length; i++) {
+      expect(RAMP_DEFAULT[i]!).toBeGreaterThanOrEqual(RAMP_DEFAULT[i - 1]!);
+    }
+    expect(RAMP_DEFAULT[0]).toBeLessThanOrEqual(50);
+  });
+
+  test("the last delay repeats forever rather than running off the end", () => {
+    const last = RAMP_DEFAULT[RAMP_DEFAULT.length - 1]!;
+    expect(delayForAttempt(RAMP_DEFAULT, 99)).toBe(last);
+    expect(delayForAttempt(RAMP_DEFAULT, 0)).toBe(RAMP_DEFAULT[0]);
+  });
+});
+
+describe("pollUntilReady", () => {
+  test("a service already up is reported on the first attempt", async () => {
+    const clock = fakeClock();
+    const out = await pollUntilReady(async () => true, { kind: "tcp", ...clock });
+    expect(out).toMatchObject({ ready: true, attempts: 1 });
+    expect(out.elapsedMs).toBe(0);
+  });
+
+  test("retries until the probe succeeds", async () => {
+    const clock = fakeClock();
+    let n = 0;
+    const out = await pollUntilReady(async () => ++n >= 4, { kind: "tcp", ...clock });
+    expect(out.ready).toBe(true);
+    expect(out.attempts).toBe(4);
+    // 50 + 100 + 150 of ramp delay before the 4th attempt.
+    expect(out.elapsedMs).toBe(300);
+  });
+
+  test("gives up at the deadline", async () => {
+    const clock = fakeClock();
+    const out = await pollUntilReady(async () => false, {
+      kind: "tcp",
+      timeoutSecs: 1,
+      ...clock,
+    });
+    expect(out.ready).toBe(false);
+    expect(out.elapsedMs).toBeLessThanOrEqual(1000);
+  });
+
+  /** A deadline check before the first probe would make timeoutSecs: 0
+   *  mean "never check" — which reads as "no timeout" to whoever wrote it,
+   *  and would fail a service that was ready all along. */
+  test("always probes at least once, even with a zero timeout", async () => {
+    const clock = fakeClock();
+    let probed = 0;
+    const out = await pollUntilReady(
+      async () => {
+        probed++;
+        return true;
+      },
+      { kind: "tcp", timeoutSecs: 0, ...clock },
+    );
+    expect(probed).toBe(1);
+    expect(out.ready).toBe(true);
+  });
+
+  test("a negative timeout still probes once and then gives up", async () => {
+    const clock = fakeClock();
+    let probed = 0;
+    const out = await pollUntilReady(
+      async () => {
+        probed++;
+        return false;
+      },
+      { kind: "tcp", timeoutSecs: -5, ...clock },
+    );
+    expect(probed).toBe(1);
+    expect(out.ready).toBe(false);
+  });
+
+  /** Two properties at once: it must not sleep PAST the deadline, and it
+   *  must not stop probing BEFORE it. An earlier version gave up as soon
+   *  as now+delay would overshoot, which abandoned up to a full ramp step
+   *  (500ms) of the timeout the caller asked for — fine when everything is
+   *  fast, and exactly wrong under load, when readiness is marginal. */
+  test("keeps probing right up to the deadline without overshooting it", async () => {
+    const clock = fakeClock();
+    let probes = 0;
+    const out = await pollUntilReady(
+      async () => {
+        probes++;
+        return false;
+      },
+      {
+        kind: "tcp",
+        timeoutSecs: 0.2,
+        now: clock.now,
+        sleep: async (ms) => clock.advance(ms),
+      },
+    );
+    expect(out.ready).toBe(false);
+    // 200ms with a 50,100,150,… ramp: the clamped final sleep must let it
+    // use the whole budget rather than stopping at 150ms.
+    expect(out.elapsedMs).toBe(200);
+    expect(probes).toBeGreaterThanOrEqual(3);
+  });
+
+  test("the total time slept never exceeds the timeout", async () => {
+    const clock = fakeClock();
+    const slept: number[] = [];
+    const out = await pollUntilReady(async () => false, {
+      kind: "tcp",
+      timeoutSecs: 0.2, // 200ms: ramp is 50,100,150,… so the third would overshoot
+      now: clock.now,
+      sleep: async (ms) => {
+        slept.push(ms);
+        clock.advance(ms);
+      },
+    });
+    expect(out.ready).toBe(false);
+    const total = slept.reduce((a, b) => a + b, 0);
+    // `<= 200`, not `< 200`: using the full budget is correct. The earlier
+    // assertion encoded the very bug it should have caught — stopping
+    // short of the timeout the caller asked for.
+    expect(total).toBeLessThanOrEqual(200);
+  });
+
+  test("a probe that throws propagates rather than being read as not-ready", async () => {
+    const clock = fakeClock();
+    await expect(
+      pollUntilReady(async () => {
+        throw new Error("docker gone");
+      }, { kind: "exec", ...clock }),
+    ).rejects.toThrow("docker gone");
+  });
+
+  test("exec probes use the slower ramp", async () => {
+    const clock = fakeClock();
+    let n = 0;
+    const out = await pollUntilReady(async () => ++n >= 2, { kind: "exec", ...clock });
+    expect(out.elapsedMs).toBe(RAMP_EXEC[0]);
+  });
+});

package/src/harness/ready-poll.ts

@@ -0,0 +1,93 @@
+/**
+ * The polling schedule behind a readiness probe.
+ *
+ * Ported out of `daemon.ts`, separated from the probes themselves so the
+ * timing rules can be tested without opening a socket or spawning a
+ * `docker exec`.
+ *
+ * Why a ramp rather than a fixed interval: a flat 500 ms delay quantises
+ * *every* service's measured ready latency to a multiple of 500 ms, and
+ * that error compounds down a `dependsOn` chain — a four-deep chain of
+ * services that are each genuinely ready in 60 ms reports two seconds.
+ * Probing fast at first catches quick services honestly; ramping up caps
+ * the polling load on genuinely slow ones.
+ *
+ * Exec probes keep a higher floor because each attempt spawns a
+ * `docker exec`, which costs far more than a TCP connect.
+ */
+
+export type ProbeKind = "tcp" | "http" | "exec";
+
+/** Delays between attempts, in ms. The last entry repeats forever. */
+export const RAMP_DEFAULT: readonly number[] = [50, 100, 150, 250, 400, 500];
+export const RAMP_EXEC: readonly number[] = [250, 250, 400, 400, 500];
+
+export const DEFAULT_TIMEOUT_SECS = 60;
+
+export function rampFor(kind: ProbeKind): readonly number[] {
+  return kind === "exec" ? RAMP_EXEC : RAMP_DEFAULT;
+}
+
+/** Delay before attempt number `attempt` (0-based), clamped to the ramp's tail. */
+export function delayForAttempt(ramp: readonly number[], attempt: number): number {
+  return ramp[Math.min(attempt, ramp.length - 1)]!;
+}
+
+export interface PollOptions {
+  kind: ProbeKind;
+  timeoutSecs?: number;
+  /** Injectable for tests; defaults to the wall clock. */
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface PollResult {
+  ready: boolean;
+  attempts: number;
+  elapsedMs: number;
+}
+
+/**
+ * Poll `probe` until it returns true or the deadline passes.
+ *
+ * The probe is **always attempted at least once**, even with a zero or
+ * negative timeout. A deadline check placed before the first attempt
+ * would make `timeoutSecs: 0` mean "never check", which reads as "no
+ * timeout" to anyone writing it — and would fail a service that was
+ * ready all along.
+ */
+export async function pollUntilReady(
+  probe: () => Promise<boolean>,
+  opts: PollOptions,
+): Promise<PollResult> {
+  const now = opts.now ?? Date.now;
+  const sleep = opts.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const timeoutSecs = opts.timeoutSecs ?? DEFAULT_TIMEOUT_SECS;
+  const ramp = rampFor(opts.kind);
+
+  const started = now();
+  const deadline = started + timeoutSecs * 1000;
+  let attempts = 0;
+
+  for (;;) {
+    attempts++;
+    if (await probe()) {
+      return { ready: true, attempts, elapsedMs: now() - started };
+    }
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      return { ready: false, attempts, elapsedMs: now() - started };
+    }
+    // Clamp rather than give up early. An earlier version returned as soon
+    // as `now + delay` passed the deadline, which stopped probing up to a
+    // full ramp step (500 ms) BEFORE the timeout the user asked for — so a
+    // service that became ready in that final window was reported as
+    // failed. Harmless when everything is fast, and exactly wrong under
+    // load, which is when readiness is marginal in the first place.
+    //
+    // Clamping keeps the original "probe until the deadline" behaviour and
+    // still never sleeps past it.
+    const delay = Math.min(delayForAttempt(ramp, attempts - 1), remaining);
+    await sleep(delay);
+  }
+}

package/src/harness/service-graph.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+
+import { topologicalOrder, validateServiceGraph } from "./service-graph";
+
+const svc = (name: string, dependsOn?: string[]) => ({ name, dependsOn });
+
+describe("validateServiceGraph", () => {
+  test("returns a name→service map for a clean graph", () => {
+    const map = validateServiceGraph([svc("db"), svc("api", ["db"])]);
+    expect(map.get("api")!.dependsOn).toEqual(["db"]);
+    expect(map.size).toBe(2);
+  });
+
+  test("a dependency on a service that doesn't exist names both sides", () => {
+    expect(() => validateServiceGraph([svc("api", ["db"])])).toThrow(
+      /api depends on unknown service db/,
+    );
+  });
+
+  test("a service depending on itself is rejected", () => {
+    expect(() => validateServiceGraph([svc("api", ["api"])])).toThrow(/depends on itself/);
+  });
+
+  test("a cycle is rejected", () => {
+    expect(() => validateServiceGraph([svc("a", ["b"]), svc("b", ["a"])])).toThrow(/cycle/);
+  });
+
+  /** The old message was just "service dependency cycle", leaving the user
+   *  to find it by eye in a large services map. */
+  test("the cycle error names the loop", () => {
+    let msg = "";
+    try {
+      validateServiceGraph([svc("a", ["b"]), svc("b", ["c"]), svc("c", ["a"])]);
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain("a");
+    expect(msg).toContain("b");
+    expect(msg).toContain("c");
+    expect(msg).toContain("→");
+  });
+
+  /** Previously the map was built without checking, so a repeated name
+   *  silently replaced the earlier definition and the graph lied about
+   *  what was running. */
+  test("a duplicate service name is rejected rather than shadowing", () => {
+    expect(() => validateServiceGraph([svc("api"), svc("api")])).toThrow(/duplicate service name/);
+  });
+
+  test("a diamond is fine — shared dependencies are not cycles", () => {
+    const graph = [svc("db"), svc("a", ["db"]), svc("b", ["db"]), svc("web", ["a", "b"])];
+    expect(() => validateServiceGraph(graph)).not.toThrow();
+  });
+
+  test("an empty graph is valid", () => {
+    expect(validateServiceGraph([]).size).toBe(0);
+  });
+
+  test("two independent components are both walked", () => {
+    // A cycle in the second component must still be found, i.e. the walk
+    // does not stop after the first root.
+    expect(() =>
+      validateServiceGraph([svc("solo"), svc("a", ["b"]), svc("b", ["a"])]),
+    ).toThrow(/cycle/);
+  });
+});
+
+describe("topologicalOrder", () => {
+  test("every service follows its dependencies", () => {
+    const order = topologicalOrder([
+      svc("web", ["api"]),
+      svc("api", ["db"]),
+      svc("db"),
+    ]).map((s) => s.name);
+    expect(order.indexOf("db")).toBeLessThan(order.indexOf("api"));
+    expect(order.indexOf("api")).toBeLessThan(order.indexOf("web"));
+  });
+
+  test("a shared dependency appears once", () => {
+    const order = topologicalOrder([
+      svc("a", ["db"]),
+      svc("b", ["db"]),
+      svc("db"),
+    ]).map((s) => s.name);
+    expect(order.filter((n) => n === "db")).toHaveLength(1);
+    expect(order).toHaveLength(3);
+  });
+
+  test("independent services keep declaration order, so the result is stable", () => {
+    const order = topologicalOrder([svc("z"), svc("y"), svc("x")]).map((s) => s.name);
+    expect(order).toEqual(["z", "y", "x"]);
+  });
+
+  test("it validates too — a cycle throws rather than looping forever", () => {
+    expect(() => topologicalOrder([svc("a", ["b"]), svc("b", ["a"])])).toThrow(/cycle/);
+  });
+});