@aikoql/client 0.0.0-stage → 0.2.3

package/src/tx.ts

@@ -0,0 +1,83 @@
+// Tx implements the §3.5 transaction handle: the txn_id is a first-class
+// field here — it never leaks as a bare tool argument that a caller
+// threads between call sites. The four txn_* tools are reachable only
+// through Tx methods. Mirrors the Go SDK's transactions.go and the Rust
+// reference (crates/sdk/rust/src/tx.rs).
+
+import type { Client } from "./client.ts";
+import { McpError } from "./error.ts";
+
+/** One staged write (the txn_stage op shape). */
+export interface StagedOp {
+  action: string;
+  type_name?: string;
+  koid?: string;
+  properties?: Record<string, unknown>;
+}
+
+/** The txn_commit outcome: the staged write results and whether this
+ * commit was a retry of an already-committed txn_id. */
+export interface CommitResult {
+  results?: unknown[];
+  deduped?: boolean;
+}
+
+/**
+ * A staged write handle: begin on the Client, execute stages ops, commit
+ * or rollback closes it. A closed handle refuses further use with
+ * INVALID_ARGUMENT.
+ */
+export class Tx {
+  private c: Client;
+  private txId: string;
+  private closed = false;
+
+  constructor(c: Client, txnId: string) {
+    this.c = c;
+    this.txId = txnId;
+  }
+
+  /** The txn_id (for retries — commit dedupes by it, P5-M20). */
+  id(): string {
+    return this.txId;
+  }
+
+  /** True once commit or rollback closed the handle (the pool's session
+   * reset checks this). */
+  done(): boolean {
+    return this.closed;
+  }
+
+  /** Stages one write. */
+  async execute(op: StagedOp, opts: { signal?: AbortSignal } = {}): Promise<void> {
+    await this.step("txn_stage", { txn_id: this.txId, op }, opts);
+  }
+
+  /** Applies the staged writes and closes the handle. A commit that errors
+   * leaves the handle open: the server dedupes by txn_id, so the caller
+   * may retry commit or begin with the same id (P5-M20). */
+  async commit(opts: { signal?: AbortSignal } = {}): Promise<CommitResult> {
+    const raw = await this.step("txn_commit", { txn_id: this.txId }, opts);
+    return (raw ?? {}) as CommitResult;
+  }
+
+  /** Discards the staged writes and closes the handle. */
+  async rollback(opts: { signal?: AbortSignal } = {}): Promise<void> {
+    await this.step("txn_rollback", { txn_id: this.txId }, opts);
+  }
+
+  private async step(
+    name: string,
+    args: Record<string, unknown>,
+    opts: { signal?: AbortSignal },
+  ): Promise<unknown> {
+    if (this.closed) {
+      throw McpError.invalidArgument(`transaction ${this.txId} is closed`);
+    }
+    const raw = await this.c.callTool(name, args, opts);
+    if (name === "txn_commit" || name === "txn_rollback") {
+      this.closed = true;
+    }
+    return raw;
+  }
+}

package/tests/conformance.test.ts

@@ -0,0 +1,60 @@
+// D-13: the shared conformance runner, typescript arm (§7, §23). This
+// test pins only the CLI contract — the vectors carry the semantics.
+// Mirrors crates/sdk/rust/tests/conformance.rs.
+
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import test from "node:test";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Native→"bash" spawns the WSL shim on Windows (its PATH has no cargo/
+// node); where.exe is a plain PATH walk and finds Git's bash. Prefer its
+// Git hit; plain "bash" elsewhere (CI Linux).
+async function bashExe(): Promise<string> {
+  if (process.platform !== "win32") return "bash";
+  try {
+    const { stdout } = await new Promise<{ stdout: string }>((resolve, reject) =>
+      execFile("where.exe", ["bash"], { encoding: "utf8" }, (err, stdout) =>
+        err ? reject(err) : resolve({ stdout }),
+      ),
+    );
+    const hits = stdout
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .filter(Boolean);
+    return hits.find((h) => h.toLowerCase().includes("git")) ?? hits[0] ?? "bash";
+  } catch {
+    return "bash";
+  }
+}
+
+function run(args: string[], env: Record<string, string>): Promise<{ code: number; out: string }> {
+  return new Promise((resolve, reject) => {
+    execFile(args[0]!, args.slice(1), { encoding: "utf8", env }, (err, stdout, stderr) => {
+      if (err && (err as { code?: number }).code === undefined) reject(err);
+      else resolve({ code: (err as { code?: number } | null)?.code ?? 0, out: `${stdout}${stderr}` });
+    });
+  });
+}
+
+test("sdk-conformance --language typescript", async () => {
+  const script = path.resolve(__dirname, "..", "..", "..", "..", "scripts", "sdk-conformance.sh");
+  // crates/sdk/typescript/tests → repo root is four levels up.
+  assert.ok(
+    (await import("node:fs")).existsSync(script),
+    `sdk-conformance runner missing at ${script} — D-13 RED`,
+  );
+  const bin = process.env.AIKOQL_MCP_BIN;
+  if (!bin) {
+    process.stderr.write("AIKOQL_MCP_BIN not set — real-server conformance skipped\n");
+    return;
+  }
+  const { code, out } = await run(
+    [await bashExe(), script, "--language", "typescript"],
+    { ...process.env, AIKOQL_MCP_BIN: bin },
+  );
+  assert.equal(code, 0, `sdk-conformance --language typescript failed (exit ${code}):\n${out}`);
+});

package/tests/corpus-pin.test.ts

@@ -0,0 +1,96 @@
+// The §16 pin: the cross-language golden corpus spec exists at
+// sdk-fuzz-corpus/corpus.json and this SDK's column holds for every case.
+// Removing a case id is a detected coverage loss; a column mismatch is a
+// wire-behavior drift (or an undocumented divergence — document it in the
+// spec's note and re-stamp). Real primitives run where they exist
+// (parseVersion/classifyID/rpcError/streamNotify); the request verdicts
+// are restated inline at their client.ts lines.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { classifyID, parseVersion, rpcError, streamNotify } from "../src/client.ts";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CORPUS = path.resolve(__dirname, "..", "..", "..", "..", "sdk-fuzz-corpus", "corpus.json");
+
+const CASE_IDS = [
+  "corp-v01", "corp-v02", "corp-v03", "corp-v04", "corp-v05",
+  "corp-e01", "corp-e02", "corp-e03", "corp-e04", "corp-e05",
+  "corp-r01", "corp-r02", "corp-n01",
+  "corp-s01", "corp-s02", "corp-s03",
+  "corp-c01", "corp-c02", "corp-c03", "corp-c04",
+];
+const SURFACES = ["version", "rpc_error", "response_id", "nonfinite", "notify", "correlation"];
+
+function load(): { cases: Array<{ id: string; surface: string; input: unknown; expected: Record<string, unknown> }> } {
+  let raw: string;
+  try {
+    raw = readFileSync(CORPUS, "utf8");
+  } catch (err) {
+    throw new Error(
+      `the §16 corpus is absent (${CORPUS}): the D-16 golden-corpus slice is missing — ${String(err)}`,
+    );
+  }
+  return JSON.parse(raw) as never;
+}
+
+function classify(surface: string, input: unknown): unknown {
+  switch (surface) {
+    case "version":
+      return parseVersion(input as string);
+    case "rpc_error": {
+      const frame = JSON.parse(input as string) as { error?: { code?: unknown; message?: string } };
+      // The real error renderer: rpcError + the McpError ctor decoration.
+      const e = rpcError(frame.error as { code: unknown; message: string });
+      return { code: e.code, message: e.message };
+    }
+    case "response_id":
+    case "nonfinite": {
+      // The request loop's verdict, restated (client.ts ~:300-315, want=1):
+      // non-numeric ids skip (JSON.parse throws on garbage → skip), and a
+      // numeric id goes through classifyID.
+      let frame: { id?: unknown };
+      try {
+        frame = JSON.parse(input as string) as { id?: unknown };
+      } catch {
+        return "skip";
+      }
+      const rid = frame.id;
+      if (typeof rid !== "number") return "skip";
+      return classifyID(1, rid);
+    }
+    case "notify": {
+      // The real primitive: streamNotify (client.ts) — the same verdict
+      // the aikoqlStream loop runs; ts yields the raw params object as-is.
+      const frame = JSON.parse(input as string) as Record<string, unknown>;
+      const p = streamNotify(frame, "s1");
+      if (p === null) return { verdict: "skip", pair: null };
+      return { verdict: "yield", pair: p };
+    }
+    case "correlation": {
+      const pair = input as { want: number; got: number };
+      return classifyID(pair.want, pair.got);
+    }
+  }
+  throw new Error(`unknown surface ${surface}`);
+}
+
+test("the §16 corpus pin", () => {
+  const spec = load();
+  const byId = new Map(spec.cases.map((c) => [c.id, c]));
+  for (const id of CASE_IDS) {
+    assert.ok(byId.has(id), `case ${id} is gone from the §16 corpus — a removed case is a coverage loss`);
+  }
+  const haveSurfaces = new Set(spec.cases.map((c) => c.surface));
+  for (const s of SURFACES) {
+    assert.ok(haveSurfaces.has(s), `surface ${s} has no cases in the §16 corpus`);
+  }
+  for (const c of spec.cases) {
+    assert.ok("typescript" in c.expected, `case ${c.id} has no typescript column in the §16 corpus`);
+    const got = classify(c.surface, c.input);
+    const want = c.expected.typescript;
+    assert.deepEqual(got, want, `case ${c.id} (${c.surface}): typescript column drift — got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`);
+  }
+});

package/tests/fault-matrix.test.ts

@@ -0,0 +1,298 @@
+// D-16 fault matrix (line wire): the §18 fault proxy sits between the SDK
+// and a real server and mangles the newline-delimited JSON-RPC wire (§7 of
+// the testing plan: every SDK passes the same matrix against the same
+// misbehaving server). Frame accounting: client line #1 = initialize, #2 =
+// the victim call, #3 = the follow-up (no HELLO/AUTH frames on the MCP
+// wire). Mirrors crates/sdk/rust/tests/fault.rs on the line wire.
+//
+// The contracts GREEN must make hold (the proxy --wire line arm + the
+// client's MAX_FRAME cap and closed latch):
+//   drop-request/drop-response → victim TIMEOUT (retryable), follow-up ok
+//   delay-response → tight deadline TIMEOUT; generous deadline ok
+//   duplicate-response → both ok (id correlation skips the duplicate)
+//   reorder-response → victim TIMEOUT (response held), follow-up ok
+//   truncate-frame → victim TIMEOUT (the missing bytes never arrive),
+//     follow-up ok (the wire is self-delimiting)
+//   corrupt-frame → the line is noise per the frozen §3.3 semantics →
+//     victim TIMEOUT, follow-up ok
+//   inject-notification → both ok (an id-less frame is never a response)
+//   inject-stale-response → both ok (stale id skipped)
+//   close/half-close → victim ok, follow-up fails fast (never TIMEOUT),
+//     the client latches closed → UNAVAILABLE from then on
+//   slow-server → tight deadline TIMEOUT
+//   oversized-response → FRAME_TOO_LARGE before buffering past the 1 MiB
+//     cap (§19: a malicious server cannot cause unbounded client memory),
+//     follow-up UNAVAILABLE (the stream is desynced — latched)
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+import { test, type TestContext } from "node:test";
+import { Client, McpError, withDeadline } from "../src/index.ts";
+
+const TOKEN = "test-token";
+// npm test / node --test run from the package dir → 3 ups = the repo root.
+const ROOT = path.resolve(process.cwd(), "..", "..", "..");
+
+function findBin(name: string): string | undefined {
+  const p = path.join(ROOT, "target", "debug", name + (process.platform === "win32" ? ".exe" : ""));
+  return fs.existsSync(p) ? p : undefined;
+}
+
+const MCP_BIN = process.env.AIKOQL_MCP_BIN ?? findBin("aikoql-mcp");
+const PROXY_BIN = process.env.AIKOQL_FAULT_PROXY ?? findBin("aikoql-fault-proxy");
+
+function requireBins(t: TestContext): boolean {
+  if (!MCP_BIN || !PROXY_BIN) {
+    t.skip("AIKOQL_MCP_BIN / aikoql-fault-proxy not built — real-server fault matrix skipped");
+    return false;
+  }
+  return true;
+}
+
+function probe(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const s = net.connect(port, "127.0.0.1");
+    s.once("connect", () => {
+      s.destroy();
+      resolve(true);
+    });
+    s.once("error", () => resolve(false));
+  });
+}
+
+async function waitUp(port: number, child: ChildProcess, errFile: string, what: string): Promise<void> {
+  for (let i = 0; i < 100; i++) {
+    if (child.exitCode !== null) {
+      const err = await fs.promises.readFile(errFile, "utf8").catch(() => "");
+      throw new Error(`${what} exited early (${child.exitCode}):\n${err}`);
+    }
+    if (await probe(port)) return;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error(`${what} never listened on 127.0.0.1:${port}`);
+}
+
+/** A real server + one fault-proxy instance (one fault mode) behind the
+ * proxy address. The port-probe idiom races → 3 spawn attempts. */
+async function faultEnv(
+  mode: string,
+  extra: string[],
+): Promise<{ addr: string; stop: () => void }> {
+  let last: Error | undefined;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "aikoql-ts-fault-"));
+    const cleanup = async () => {
+      await fs.promises.rm(dir, { recursive: true, force: true }).catch(() => {});
+    };
+    let srv: ChildProcess | undefined;
+    let px: ChildProcess | undefined;
+    try {
+      const srvPort = await freePort();
+      const db = path.join(dir, "db.aikoql"); // does not exist → auto-create (aikoql-v2)
+      srv = spawn(MCP_BIN!, ["serve", db, "--listen", `127.0.0.1:${srvPort}`, "--tcp-token", `${TOKEN}::admin`], {
+        stdio: ["ignore", "ignore", fs.openSync(path.join(dir, "srv.err"), "w")],
+        windowsHide: true,
+      });
+      await waitUp(srvPort, srv, path.join(dir, "srv.err"), "aikoql-mcp");
+
+      const pxPort = await freePort();
+      const errFile = path.join(dir, "proxy.err");
+      px = spawn(
+        PROXY_BIN!,
+        ["--listen", `127.0.0.1:${pxPort}`, "--target", `127.0.0.1:${srvPort}`, "--wire", "line", "--mode", mode, ...extra],
+        { stdio: ["ignore", "ignore", fs.openSync(errFile, "w")], windowsHide: true },
+      );
+      await waitUp(pxPort, px, errFile, "aikoql-fault-proxy");
+      const addr = `127.0.0.1:${pxPort}`;
+      return {
+        addr,
+        stop: () => {
+          px!.kill();
+          srv!.kill();
+          void cleanup();
+        },
+      };
+    } catch (e) {
+      last = e as Error;
+      px?.kill();
+      srv?.kill();
+      await cleanup();
+    }
+  }
+  throw last;
+}
+
+async function freePort(): Promise<number> {
+  const probeSrv = net.createServer();
+  await new Promise<void>((resolve, reject) => {
+    probeSrv.once("error", reject);
+    probeSrv.listen(0, "127.0.0.1", resolve);
+  });
+  const port = (probeSrv.address() as net.AddressInfo).port;
+  await new Promise<void>((resolve) => probeSrv.close(() => resolve()));
+  return port;
+}
+
+async function dial(t: TestContext, addr: string): Promise<Client> {
+  const c = (await Client.dial(addr)).withToken(TOKEN);
+  t.after(() => {
+    void c.close().catch(() => {});
+  });
+  await c.initialize();
+  return c;
+}
+
+/** Runs fn under the deadline and returns the error code ("" = ok). */
+async function codeOf(fn: (signal: AbortSignal) => Promise<unknown>): Promise<string> {
+  try {
+    await withDeadline(5000, fn);
+    return "";
+  } catch (e) {
+    if (e instanceof McpError) return e.code;
+    return "raw:" + String(e);
+  }
+}
+
+const call = (c: Client) => (signal: AbortSignal) => c.callTool("health", {}, { signal });
+
+async function victim(c: Client, ms: number): Promise<string> {
+  try {
+    await withDeadline(ms, (signal) => c.callTool("health", {}, { signal }));
+    return "";
+  } catch (e) {
+    if (e instanceof McpError) return e.code;
+    return "raw:" + String(e);
+  }
+}
+
+test("fault matrix: drop-request", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("drop-request", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  const code = await victim(c, 200);
+  assert.equal(code, "TIMEOUT");
+  assert.equal(await codeOf(call(c)), ""); // the follow-up survives
+});
+
+test("fault matrix: drop-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("drop-response", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  const code = await victim(c, 200);
+  assert.equal(code, "TIMEOUT");
+  assert.equal(await codeOf(call(c)), "");
+});
+
+test("fault matrix: delay-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("delay-response", ["--from", "2", "--delay-ms", "400"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  const code = await victim(c, 200);
+  assert.equal(code, "TIMEOUT");
+  const { addr: addr2, stop: stop2 } = await faultEnv("delay-response", ["--from", "2", "--delay-ms", "400"]);
+  t.after(stop2);
+  const c2 = await dial(t, addr2);
+  assert.equal(await victim(c2, 2000), ""); // a generous deadline absorbs the delay
+});
+
+test("fault matrix: duplicate-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("duplicate-response", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 2000), "");
+  assert.equal(await codeOf(call(c)), ""); // the duplicate is a stale id — skipped
+});
+
+test("fault matrix: reorder-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("reorder-response", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 200), "TIMEOUT");
+  assert.equal(await codeOf(call(c)), ""); // request #3 releases response #2
+});
+
+test("fault matrix: truncate-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("truncate-response", ["--n", "2", "--bytes", "8"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 200), "TIMEOUT");
+  assert.equal(await codeOf(call(c)), ""); // the wire is self-delimiting
+});
+
+test("fault matrix: corrupt-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("corrupt-response", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 200), "TIMEOUT"); // noise-skip, never a fast error
+  assert.equal(await codeOf(call(c)), "");
+});
+
+test("fault matrix: inject-notification", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("inject-notification", ["--after", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 2000), "");
+  assert.equal(await codeOf(call(c)), ""); // an id-less frame is never a response
+});
+
+test("fault matrix: inject-stale-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("inject-stale-response", ["--after", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 2000), "");
+  assert.equal(await codeOf(call(c)), ""); // the replayed initialize response is stale
+});
+
+test("fault matrix: close-after", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("close-after", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 2000), "");
+  const follow = await codeOf(call(c));
+  assert.notEqual(follow, "");
+  assert.notEqual(follow, "TIMEOUT"); // fails fast, never hangs
+  assert.equal(await codeOf(call(c)), "UNAVAILABLE"); // latched
+});
+
+test("fault matrix: half-close-after", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("half-close-after", ["--n", "2"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 2000), "");
+  const follow = await codeOf(call(c));
+  assert.notEqual(follow, "");
+  assert.notEqual(follow, "TIMEOUT");
+  assert.equal(await codeOf(call(c)), "UNAVAILABLE");
+});
+
+test("fault matrix: slow-server", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("slow-server", ["--from", "2", "--bytes", "4", "--delay-ms", "25"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 200), "TIMEOUT");
+});
+
+test("fault matrix: oversized-response", async (t) => {
+  if (!requireBins(t)) return;
+  const { addr, stop } = await faultEnv("oversized-response", ["--n", "2", "--claim", "67108864"]);
+  t.after(stop);
+  const c = await dial(t, addr);
+  assert.equal(await victim(c, 5000), "FRAME_TOO_LARGE"); // the 1 MiB cap, not 64 MiB
+  assert.equal(await codeOf(call(c)), "UNAVAILABLE"); // the stream is desynced — latched
+});

package/tests/fuzz-estate-pin.test.ts

@@ -0,0 +1,32 @@
+// D-16 §10: the TS fuzz estate's own pin (the F-04 pattern — a removed
+// target is a detected coverage loss, never silent). The estate lives in
+// tests/fuzz-estate.test.ts: fast-check property tests over the frozen
+// mirrors (version parse, error mapping, id correlation, frame cap,
+// envelope decode) plus the §17 command model
+// (DISCONNECTED→CONNECTED→INITIALIZED→TRANSACTION→STREAMING→CLOSED).
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import test from "node:test";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const estate = path.join(__dirname, "fuzz-estate.test.ts");
+
+// The five property tests and the §17 model, by name.
+const pins = [
+  "the version-parse property",
+  "the error-mapping property",
+  "the id-correlation property",
+  "the frame-cap property",
+  "the envelope property",
+  "the §17 command model",
+];
+
+test("the fuzz-estate pin", () => {
+  const src = readFileSync(estate, "utf8");
+  for (const pin of pins) {
+    assert.ok(src.includes(pin), `§10 fuzz target missing: ${pin}`);
+  }
+});