@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/AgentChannelConformance.ts

@@ -0,0 +1,124 @@
+/** Public replay conformance suite for channel plugins, runnable with @effect/vitest. */
+import { Effect, Schema } from "effect";
+
+import * as AgentChannel from "./AgentChannel.ts";
+import * as DualRuntime from "./DualRuntime.ts";
+
+// Either protocol: the runtime checks each command against the Channel's own protocol.
+const Command = Schema.Union([
+  AgentChannel.commandSchema(Schema.Json),
+  AgentChannel.commandSchemaV2(Schema.Json),
+]);
+export const Fixture = Schema.Struct({
+  activate: Command,
+  channelId: AgentChannel.Key,
+  connectionId: Schema.optionalKey(AgentChannel.Key),
+  deactivate: Command,
+  definitionSettings: Schema.Json,
+  deliver: Command,
+  deploymentSettings: Schema.Json,
+  receive: Command,
+});
+export type Fixture = typeof Fixture.Type;
+export class ConformanceError extends Schema.TaggedError<ConformanceError>()(
+  "AgentChannelConformanceError",
+  {
+    command: Schema.Literals(["activate", "deactivate", "receive", "deliver"]),
+    rule: Schema.Literals(["command_kind", "stable_result", "stable_events", "boundary_rejection"]),
+  },
+) {}
+
+/**
+ * Replays operations that providers declare safe to replay. At-most-once delivery executes once;
+ * the durable host owns its replay prohibition. Use an isolated provider test installation: this
+ * suite performs provider effects. The host supplies stable keys; the plugin must recover the same
+ * external subscription and emit the same provider event keys, even for a fresh receipt key.
+ * Boundary rejection and feature/auth matrices are covered by the SDK's public runtime tests.
+ */
+export const run = Effect.fn("AgentChannelConformance.run")(function* (input: Fixture) {
+  const fixture = yield* Schema.decodeUnknownEffect(Fixture)(input, { onExcessProperty: "error" });
+  const runtime = yield* DualRuntime.Service;
+  const definition = yield* runtime.getAgentChannel({ channelId: fixture.channelId });
+  const { activate, receive, deliver, deactivate, ...config } = fixture;
+  const { connectionId: _connectionId, ...withoutConnection } = config;
+  const probes = [
+    { code: "invalid_input", input: { ...config, channelId: "", command: activate } },
+    {
+      // Invocation keys allow '/', but authored identifiers forbid it, so this cannot activate.
+      input: { ...config, channelId: "conformance/missing/channel", command: activate },
+      code: "not_found",
+    },
+    { code: "invalid_input", input: { ...config, command: { ...activate, operationKey: "" } } },
+    {
+      code: "invalid_input",
+      input: { ...config, agent: { id: "synthetic-authority" }, command: activate },
+    },
+    {
+      code: "invalid_auth",
+      input:
+        definition.authMethods.length === 0
+          ? { ...config, command: activate, connectionId: "unexpected" }
+          : { ...withoutConnection, command: activate },
+    },
+  ];
+  for (const probe of probes) {
+    const outcome = yield* Effect.suspend(() => runtime.executeAgentChannel(probe.input)).pipe(
+      Effect.result,
+    );
+    if (outcome._tag !== "Failure" || outcome.failure.code !== probe.code) {
+      return yield* new ConformanceError({ command: "activate", rule: "boundary_rejection" });
+    }
+  }
+  const commands = [
+    ["activate", activate],
+    ["receive", receive],
+    ["deliver", deliver],
+    ["deactivate", deactivate],
+  ] as const;
+  for (const [kind, command] of commands) {
+    if (command.kind !== kind) {
+      return yield* new ConformanceError({ command: kind, rule: "command_kind" });
+    }
+  }
+  const activated = yield* Effect.acquireRelease(
+    runtime.executeAgentChannel({ ...config, command: activate }),
+    result =>
+      runtime
+        .executeAgentChannel({
+          ...config,
+          command: {
+            ...deactivate,
+            ...(result.kind === "activate"
+              ? { installationKey: result.installationKey, state: result.state }
+              : {}),
+          },
+        })
+        .pipe(Effect.orDie),
+  );
+  for (const [kind, command] of commands) {
+    const first =
+      kind === "activate" ? activated : yield* runtime.executeAgentChannel({ ...config, command });
+    if (kind === "deliver" && definition.features.deliveryMode === "at-most-once") continue;
+    const second = yield* runtime.executeAgentChannel({ ...config, command });
+    const firstJson = yield* Schema.decodeUnknownEffect(Schema.Json)(first);
+    const secondJson = yield* Schema.decodeUnknownEffect(Schema.Json)(second);
+    if (!Schema.toEquivalence(Schema.Json)(firstJson, secondJson)) {
+      return yield* new ConformanceError({ command: kind, rule: "stable_result" });
+    }
+    if (kind === "receive") {
+      const nextReceipt = yield* runtime.executeAgentChannel({
+        ...config,
+        command: { ...command, operationKey: `${command.operationKey.slice(0, 500)}:replay` },
+      });
+      if (
+        first.kind !== "receive" ||
+        nextReceipt.kind !== "receive" ||
+        !Schema.toEquivalence(Schema.Array(AgentChannel.EventV2))(first.events, nextReceipt.events)
+      ) {
+        return yield* new ConformanceError({ command: kind, rule: "stable_events" });
+      }
+    }
+  }
+}, Effect.scoped);
+
+export * as AgentChannelConformance from "./AgentChannelConformance.ts";