@adjudicate/adapter-core 0.1.0

package/tests/bridge.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import type { Plan } from "@adjudicate/core/llm";
+import {
+  buildEnvelopeFromToolUse,
+  classifyIncomingToolUse,
+} from "../src/bridge.js";
+
+const plan: Plan = {
+  visibleReadTools: ["list_charges", "get_charge"],
+  allowedIntents: ["pix.charge.create", "pix.charge.refund"],
+};
+
+describe("classifyIncomingToolUse", () => {
+  it("classifies a planner-advertised READ tool", () => {
+    const result = classifyIncomingToolUse(
+      { name: "list_charges", input: { limit: 5 } },
+      plan,
+    );
+    expect(result).toEqual({
+      kind: "read",
+      name: "list_charges",
+      input: { limit: 5 },
+    });
+  });
+
+  it("classifies a planner-advertised intent kind", () => {
+    const result = classifyIncomingToolUse(
+      { name: "pix.charge.create", input: { amountCentavos: 5000 } },
+      plan,
+    );
+    expect(result).toEqual({
+      kind: "intent",
+      intentKind: "pix.charge.create",
+      payload: { amountCentavos: 5000 },
+    });
+  });
+
+  it("returns out_of_plan for an unknown tool name", () => {
+    const result = classifyIncomingToolUse(
+      { name: "make_coffee", input: {} },
+      plan,
+    );
+    expect(result).toEqual({ kind: "out_of_plan", name: "make_coffee" });
+  });
+
+  it("does not let a TRUSTED-only kind leak when planner has not advertised it", () => {
+    // pix.charge.confirm is TRUSTED-only; the planner correctly omits it.
+    // The bridge must surface this as out_of_plan, not as an intent.
+    const restrictivePlan: Plan = {
+      visibleReadTools: [],
+      allowedIntents: ["pix.charge.create"],
+        };
+    const result = classifyIncomingToolUse(
+      { name: "pix.charge.confirm", input: { chargeId: "x" } },
+      restrictivePlan,
+    );
+    expect(result.kind).toBe("out_of_plan");
+  });
+});
+
+describe("buildEnvelopeFromToolUse", () => {
+  it("constructs an envelope with principal=llm and supplied taint", () => {
+    const envelope = buildEnvelopeFromToolUse({
+      intentKind: "pix.charge.create",
+      payload: { amountCentavos: 5000 },
+      sessionId: "s-1",
+      taint: "UNTRUSTED",
+      nonce: "tu-abc-123",
+    });
+    expect(envelope.kind).toBe("pix.charge.create");
+    expect(envelope.actor).toEqual({ principal: "llm", sessionId: "s-1" });
+    expect(envelope.taint).toBe("UNTRUSTED");
+    expect(envelope.nonce).toBe("tu-abc-123");
+    expect(envelope.intentHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("produces a stable intentHash across retries with the same nonce", () => {
+    const a = buildEnvelopeFromToolUse({
+      intentKind: "pix.charge.create",
+      payload: { amountCentavos: 5000 },
+      sessionId: "s-1",
+      taint: "UNTRUSTED",
+      nonce: "tu-stable",
+    });
+    const b = buildEnvelopeFromToolUse({
+      intentKind: "pix.charge.create",
+      payload: { amountCentavos: 5000 },
+      sessionId: "s-1",
+      taint: "UNTRUSTED",
+      nonce: "tu-stable",
+    });
+    expect(a.intentHash).toBe(b.intentHash);
+  });
+
+  it("produces different intentHash when the nonce changes", () => {
+    const a = buildEnvelopeFromToolUse({
+      intentKind: "pix.charge.create",
+      payload: { amountCentavos: 5000 },
+      sessionId: "s-1",
+      taint: "UNTRUSTED",
+      nonce: "tu-nonce-a",
+    });
+    const b = buildEnvelopeFromToolUse({
+      intentKind: "pix.charge.create",
+      payload: { amountCentavos: 5000 },
+      sessionId: "s-1",
+      taint: "UNTRUSTED",
+      nonce: "tu-nonce-b",
+    });
+    expect(a.intentHash).not.toBe(b.intentHash);
+  });
+});

package/tests/decisions.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  decisionDefer,
+  decisionEscalate,
+  decisionExecute,
+  decisionRefuse,
+  decisionRequestConfirmation,
+  decisionRewrite,
+  refuse,
+  type IntentEnvelope,
+} from "@adjudicate/core";
+import { translateDecision } from "../src/decisions.js";
+import {
+  createInMemoryConfirmationStore,
+  createInMemoryDeferStore,
+} from "../src/persistence.js";
+import type { AdopterExecutor } from "../src/types.js";
+
+interface Payload {
+  amountCentavos: number;
+}
+interface State {
+  // intentionally empty — kernel state is not exercised in these unit tests
+}
+
+const envelope: IntentEnvelope<"pix.charge.refund", Payload> = {
+  version: 2,
+  kind: "pix.charge.refund",
+  payload: { amountCentavos: 5000 },
+  createdAt: new Date().toISOString(),
+  nonce: "n-1",
+  actor: { principal: "llm", sessionId: "s-1" },
+  taint: "UNTRUSTED",
+  intentHash: "f".repeat(64),
+};
+
+const rewrittenEnvelope: IntentEnvelope<"pix.charge.refund", Payload> = {
+  ...envelope,
+  payload: { amountCentavos: 3000 },
+  intentHash: "e".repeat(64),
+};
+
+function buildContext(opts?: { executor?: AdopterExecutor<"pix.charge.refund", Payload, State> }) {
+  const executor: AdopterExecutor<"pix.charge.refund", Payload, State> =
+    opts?.executor ?? {
+      invokeRead: vi.fn(async () => ({})),
+      invokeIntent: vi.fn(async () => ({ refundId: "r-1", refunded: 5000 })),
+    };
+  return {
+    envelope,
+    toolUseId: "tu-1",
+    sessionId: "s-1",
+    state: {} as State,
+    executor,
+    deferStore: createInMemoryDeferStore(),
+    confirmationStore: createInMemoryConfirmationStore<unknown>(),
+    historySnapshot: [] as unknown,
+    rk: (raw: string) => raw,
+    generateToken: () => "ct-fixed",
+  };
+}
+
+describe("translateDecision (adapter-core)", () => {
+  it("EXECUTE → invokes executor, returns JSON tool_result, continues", async () => {
+    const ctx = buildContext();
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionExecute([]),
+    });
+    expect(t.loopAction).toEqual({ kind: "continue" });
+    expect(t.toolResult?.toolUseId).toBe("tu-1");
+    expect(t.toolResult?.isError).toBeUndefined();
+    expect(ctx.executor.invokeIntent).toHaveBeenCalledWith(envelope, {});
+    const content = JSON.parse(t.toolResult?.content as string);
+    expect(content).toMatchObject({
+      ok: true,
+      result: { refundId: "r-1" },
+    });
+  });
+
+  it("REFUSE → tool_result with userFacing text, isError=true, continues", async () => {
+    const ctx = buildContext();
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionRefuse(
+        refuse(
+          "BUSINESS_RULE",
+          "pix.charge.amount_invalid",
+          "That amount is not allowed.",
+        ),
+        [],
+      ),
+    });
+    expect(t.loopAction).toEqual({ kind: "continue" });
+    expect(t.toolResult?.isError).toBe(true);
+    expect(t.toolResult?.content).toBe("That amount is not allowed.");
+    expect(ctx.executor.invokeIntent).not.toHaveBeenCalled();
+  });
+
+  it("REWRITE → invokes executor with rewritten envelope, surfaces note, continues", async () => {
+    const ctx = buildContext();
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionRewrite(rewrittenEnvelope, "amount clamped to original", []),
+    });
+    expect(t.loopAction).toEqual({ kind: "continue" });
+    expect(ctx.executor.invokeIntent).toHaveBeenCalledWith(
+      rewrittenEnvelope,
+      {},
+    );
+    const content = JSON.parse(t.toolResult?.content as string);
+    expect(content).toMatchObject({
+      ok: true,
+      note: expect.stringContaining("amount clamped to original"),
+    });
+  });
+
+  it("REQUEST_CONFIRMATION → persists pending entry, returns pause_for_user_confirmation", async () => {
+    const ctx = buildContext();
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionRequestConfirmation(
+        "Confirm a refund of R$ 600?",
+        [],
+      ),
+    });
+    expect(t.loopAction).toEqual({
+      kind: "pause_for_user_confirmation",
+      prompt: "Confirm a refund of R$ 600?",
+      token: "ct-fixed",
+    });
+    const taken = await ctx.confirmationStore.take("ct-fixed");
+    expect(taken).not.toBeNull();
+    expect(taken?.envelope).toEqual(envelope);
+    expect(t.toolResult?.content).toContain("Confirm a refund of R$ 600?");
+    expect(ctx.executor.invokeIntent).not.toHaveBeenCalled();
+  });
+
+  it("ESCALATE → returns complete_for_escalation; executor not called", async () => {
+    const ctx = buildContext();
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionEscalate(
+        "supervisor",
+        "Refund above threshold",
+        [],
+      ),
+    });
+    expect(t.loopAction).toEqual({
+      kind: "complete_for_escalation",
+      to: "supervisor",
+      reason: "Refund above threshold",
+    });
+    expect(t.toolResult?.content).toContain("Escalated to supervisor");
+    expect(ctx.executor.invokeIntent).not.toHaveBeenCalled();
+  });
+
+  it("DEFER → parks in deferStore, returns pause_for_defer", async () => {
+    const ctx = buildContext();
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionDefer("payment.confirmed", 15 * 60 * 1000, []),
+    });
+    expect(t.loopAction).toEqual({
+      kind: "pause_for_defer",
+      signal: "payment.confirmed",
+      intentHash: envelope.intentHash,
+    });
+    // Parked envelope should be retrievable from the store.
+    const parkedRaw = await ctx.deferStore.get("defer:pending:s-1");
+    expect(parkedRaw).not.toBeNull();
+    const parked = JSON.parse(parkedRaw as string);
+    expect(parked.envelope.intentHash).toBe(envelope.intentHash);
+    expect(parked.signal).toBe("payment.confirmed");
+    expect(ctx.executor.invokeIntent).not.toHaveBeenCalled();
+  });
+
+  it("EXECUTE with throwing executor → isError tool_result, loop continues", async () => {
+    const executor: AdopterExecutor<"pix.charge.refund", Payload, State> = {
+      invokeRead: vi.fn(async () => ({})),
+      invokeIntent: vi.fn(async () => {
+        throw new Error("provider down");
+      }),
+    };
+    const ctx = buildContext({ executor });
+    const t = await translateDecision({
+      ...ctx,
+      decision: decisionExecute([]),
+    });
+    expect(t.loopAction).toEqual({ kind: "continue" });
+    expect(t.toolResult?.isError).toBe(true);
+    expect(t.toolResult?.content).toContain("provider down");
+  });
+});

package/tests/persistence-redis.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Redis-backed `ConfirmationStore` — restart-durable pending confirmations.
+ *
+ * Tests cover:
+ *   - Put + take roundtrip preserves envelope, sessionId, history, prompt
+ *   - History serialization uses the configurable serializer
+ *   - take() is single-use (idempotent yes-then-yes returns null)
+ *   - Missing token returns null
+ *   - Malformed wire payload returns null without throwing
+ *   - Key namespacing is applied via keyFor
+ *   - TTL is forwarded to Redis as `EX`
+ */
+
+import { describe, expect, it } from "vitest";
+import type { IntentEnvelope } from "@adjudicate/core";
+import { createRedisConfirmationStore } from "../src/persistence-redis.js";
+import type { PendingConfirmation } from "../src/persistence.js";
+
+interface Entry {
+  readonly value: string;
+  readonly expiresAt: number | null;
+}
+
+function fakeRedis() {
+  const store = new Map<string, Entry>();
+  const calls: Array<{ op: string; key: string; ttl?: number }> = [];
+  return {
+    store,
+    calls,
+    client: {
+      async get(key: string) {
+        calls.push({ op: "get", key });
+        const e = store.get(key);
+        if (e === undefined) return null;
+        if (e.expiresAt !== null && e.expiresAt < Date.now()) {
+          store.delete(key);
+          return null;
+        }
+        return e.value;
+      },
+      async set(
+        key: string,
+        value: string,
+        opts?: { NX?: boolean; EX?: number },
+      ) {
+        calls.push({ op: "set", key, ttl: opts?.EX });
+        const expiresAt =
+          opts?.EX !== undefined ? Date.now() + opts.EX * 1000 : null;
+        store.set(key, { value, expiresAt });
+        return "OK";
+      },
+      async del(key: string) {
+        calls.push({ op: "del", key });
+        return store.delete(key) ? 1 : 0;
+      },
+    },
+  };
+}
+
+function envelopeOf(): IntentEnvelope {
+  return {
+    version: 2,
+    kind: "test.intent",
+    payload: { amount: 100 },
+    createdAt: "2026-05-20T00:00:00.000Z",
+    nonce: "nonce-1",
+    actor: { principal: "user", sessionId: "s-1" },
+    taint: "UNTRUSTED",
+    intentHash: "deadbeef",
+  };
+}
+
+function pendingOf(overrides: Partial<PendingConfirmation<string[]>> = {}): PendingConfirmation<string[]> {
+  return {
+    envelope: envelopeOf(),
+    sessionId: "s-1",
+    assistantHistorySnapshot: ["turn-1", "turn-2"],
+    toolUseId: "tu-1",
+    prompt: "Confirm transfer of 100?",
+    ...overrides,
+  };
+}
+
+describe("createRedisConfirmationStore", () => {
+  it("put + take roundtrip preserves the full pending confirmation", async () => {
+    const { client } = fakeRedis();
+    const store = createRedisConfirmationStore<string[]>({ client });
+
+    await store.put("tok-1", pendingOf(), 300);
+    const taken = await store.take("tok-1");
+
+    expect(taken).not.toBeNull();
+    expect(taken!.envelope.intentHash).toBe("deadbeef");
+    expect(taken!.sessionId).toBe("s-1");
+    expect(taken!.assistantHistorySnapshot).toEqual(["turn-1", "turn-2"]);
+    expect(taken!.toolUseId).toBe("tu-1");
+    expect(taken!.prompt).toBe("Confirm transfer of 100?");
+  });
+
+  it("take() is single-use — second take returns null", async () => {
+    const { client } = fakeRedis();
+    const store = createRedisConfirmationStore<string[]>({ client });
+
+    await store.put("tok-1", pendingOf(), 300);
+    const first = await store.take("tok-1");
+    const second = await store.take("tok-1");
+
+    expect(first).not.toBeNull();
+    expect(second).toBeNull();
+  });
+
+  it("missing token returns null without throwing", async () => {
+    const { client } = fakeRedis();
+    const store = createRedisConfirmationStore<string[]>({ client });
+
+    const taken = await store.take("never-existed");
+    expect(taken).toBeNull();
+  });
+
+  it("malformed wire payload returns null", async () => {
+    const { client, store } = fakeRedis();
+    store.set("confirm:tok-1", { value: "not-json", expiresAt: null });
+    const confirmStore = createRedisConfirmationStore<string[]>({ client });
+    const taken = await confirmStore.take("tok-1");
+    expect(taken).toBeNull();
+  });
+
+  it("keyFor namespaces the key in Redis", async () => {
+    const { client, calls } = fakeRedis();
+    const store = createRedisConfirmationStore<string[]>({
+      client,
+      keyFor: (s) => `ENV:adjudicate:${s}`,
+    });
+
+    await store.put("tok-1", pendingOf(), 300);
+    expect(calls.some((c) => c.key === "ENV:adjudicate:confirm:tok-1")).toBe(true);
+  });
+
+  it("TTL is forwarded to Redis as EX seconds", async () => {
+    const { client, calls } = fakeRedis();
+    const store = createRedisConfirmationStore<string[]>({ client });
+
+    await store.put("tok-1", pendingOf(), 900);
+    const setCall = calls.find((c) => c.op === "set");
+    expect(setCall?.ttl).toBe(900);
+  });
+
+  it("custom history serializer is honored on both put and take", async () => {
+    interface RichHistory {
+      readonly entries: ReadonlyArray<{ readonly role: string; readonly text: string }>;
+    }
+    const { client } = fakeRedis();
+    let serialized = 0;
+    let deserialized = 0;
+    const store = createRedisConfirmationStore<RichHistory>({
+      client,
+      serializeHistory: (h) => {
+        serialized++;
+        return JSON.stringify(h);
+      },
+      deserializeHistory: (s) => {
+        deserialized++;
+        return JSON.parse(s) as RichHistory;
+      },
+    });
+
+    const history: RichHistory = {
+      entries: [
+        { role: "user", text: "send 100" },
+        { role: "assistant", text: "Confirming..." },
+      ],
+    };
+
+    await store.put("tok-1", {
+      envelope: envelopeOf(),
+      sessionId: "s-1",
+      assistantHistorySnapshot: history,
+      toolUseId: "tu-1",
+      prompt: "Confirm?",
+    }, 300);
+    expect(serialized).toBe(1);
+
+    const taken = await store.take("tok-1");
+    expect(deserialized).toBe(1);
+    expect(taken!.assistantHistorySnapshot).toEqual(history);
+  });
+
+  it("a Redis TTL expiry during take returns null", async () => {
+    const { client, store } = fakeRedis();
+    const confirmStore = createRedisConfirmationStore<string[]>({ client });
+
+    // Put with an expired entry directly
+    store.set("confirm:tok-1", {
+      value: JSON.stringify({
+        envelope: envelopeOf(),
+        sessionId: "s-1",
+        historyJson: JSON.stringify([]),
+        toolUseId: "tu-1",
+        prompt: "?",
+      }),
+      expiresAt: Date.now() - 1000,
+    });
+
+    const taken = await confirmStore.take("tok-1");
+    expect(taken).toBeNull();
+  });
+});

package/tests/persistence.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import {
+  createInMemoryConfirmationStore,
+  createInMemoryDeferStore,
+  type PendingConfirmation,
+} from "../src/persistence.js";
+import type { IntentEnvelope } from "@adjudicate/core";
+
+describe("createInMemoryDeferStore — DeferRedis surface", () => {
+  it("set with NX returns OK on first write, null on collision", async () => {
+    const store = createInMemoryDeferStore();
+    const a = await store.set("k", "v1", { NX: true, EX: 60 });
+    const b = await store.set("k", "v2", { NX: true, EX: 60 });
+    expect(a).toBe("OK");
+    expect(b).toBeNull();
+    expect(await store.get("k")).toBe("v1");
+  });
+
+  it("set with EX expires the value", async () => {
+    const store = createInMemoryDeferStore();
+    await store.set("ek", "v", { NX: true, EX: 0 });
+    // EX=0 → expiresAt = Date.now(); subsequent get sees expired entry.
+    // Wait one event-loop tick to be defensive in case the comparison
+    // uses strict `>`.
+    await new Promise((r) => setTimeout(r, 1));
+    expect(await store.get("ek")).toBeNull();
+  });
+
+  it("get returns null for unknown key", async () => {
+    const store = createInMemoryDeferStore();
+    expect(await store.get("missing")).toBeNull();
+  });
+
+  it("del removes the key", async () => {
+    const store = createInMemoryDeferStore();
+    await store.set("k", "v", { NX: true, EX: 60 });
+    expect(await store.del("k")).toBe(1);
+    expect(await store.get("k")).toBeNull();
+    expect(await store.del("k")).toBe(0);
+  });
+});
+
+describe("createInMemoryDeferStore — ParkRedis surface", () => {
+  it("incr returns the new value; decr brings it back", async () => {
+    const store = createInMemoryDeferStore();
+    expect(await store.incr("c")).toBe(1);
+    expect(await store.incr("c")).toBe(2);
+    expect(await store.decr("c")).toBe(1);
+    expect(await store.decr("c")).toBe(0);
+    expect(await store.decr("c")).toBe(-1); // negative is allowed by spec
+  });
+
+  it("set with EX (no NX) writes unconditionally", async () => {
+    const store = createInMemoryDeferStore();
+    const result = await store.set("p", "envelope-blob", { EX: 60 });
+    expect(result).toBe("OK");
+    expect(await store.get("p")).toBe("envelope-blob");
+  });
+});
+
+describe("createInMemoryConfirmationStore", () => {
+  const stubEnvelope: IntentEnvelope = {
+    version: 2,
+    kind: "test.kind",
+    payload: {},
+    createdAt: new Date().toISOString(),
+    nonce: "n",
+    actor: { principal: "llm", sessionId: "s-1" },
+    taint: "UNTRUSTED",
+    intentHash: "0".repeat(64),
+  };
+  const pending: PendingConfirmation = {
+    envelope: stubEnvelope,
+    sessionId: "s-1",
+    assistantHistorySnapshot: [],
+    toolUseId: "tu-1",
+    prompt: "Confirm?",
+  };
+
+  it("put then take returns the pending entry once", async () => {
+    const store = createInMemoryConfirmationStore();
+    await store.put("token-1", pending, 60);
+    const taken = await store.take("token-1");
+    expect(taken).toEqual(pending);
+  });
+
+  it("second take of the same token returns null (idempotent yes-then-yes)", async () => {
+    const store = createInMemoryConfirmationStore();
+    await store.put("token-1", pending, 60);
+    await store.take("token-1");
+    expect(await store.take("token-1")).toBeNull();
+  });
+
+  it("take returns null after TTL expiry", async () => {
+    const store = createInMemoryConfirmationStore();
+    await store.put("token-expire", pending, 0);
+    await new Promise((r) => setTimeout(r, 1));
+    expect(await store.take("token-expire")).toBeNull();
+  });
+
+  it("take returns null for an unknown token", async () => {
+    const store = createInMemoryConfirmationStore();
+    expect(await store.take("nope")).toBeNull();
+  });
+});