Merge pull request 'Test structured prompts and guard trusted releases' (#1) from test/structured-async-payload-alpha7 into main

Document evidence-based OpenCode compatibility

.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 jobs:
   push:
+    if: ${{ github.server_url == 'https://github.com' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write

CHANGELOG.md

@@ -100,5 +100,7 @@ First public alpha. HTTP + SSE client for OpenCode REST API.
 ### Compatibility
 
 - Ruby ≥ 3.2
-- OpenCode server ≥ 1.15 (tested against the message bus schema in `packages/opencode/src/session/message-v2.ts`)
+- OpenCode targeted the then-current 1.15 message-bus shape. This historical
+  target was not a blanket SemVer compatibility guarantee; use the README's
+  current compatibility evidence for deployment decisions.
 - Runtime dependency: `activesupport (>= 6.1)` for `blank?`/`present?`/`presence`/`truncate`/`duplicable?`/`megabytes`. ActiveSupport is *not* Rails — it's a standalone helpers gem.

README.md

@@ -67,7 +67,9 @@ child = client.create_session(
 
 Model strings use OpenCode's `provider/model` form; a preformatted model hash
 with `providerID` and `id` keys is also accepted. These configured-session
-fields require OpenCode 1.16.1 or newer.
+fields first appeared in OpenCode 1.16.1. That is an API-introduction note,
+not evidence that every later server is compatible; use the
+[certified compatibility evidence](#compatibility) for deployment choices.
 
 ### Streaming (the headline)
 
@@ -106,8 +108,9 @@ client.update_session(session_id, permissions: permission_rules)
 
 OpenCode appends PATCHed permission rules and evaluates the last matching
 rule. Hosts should send a complete ordered policy and fingerprint it so the
-same policy is not appended on every turn. This endpoint requires OpenCode
+same policy is not appended on every turn. This endpoint first appeared in
-1.16.1 or newer; the rest of the client remains compatible with 1.15.
+OpenCode 1.16.1; that version floor describes endpoint availability, not
+compatibility with every later server.
 
 ### Lower-level event firehose
 
@@ -199,9 +202,29 @@ Want every OpenCode endpoint auto-generated from the OpenAPI spec? Use [`opencod
 ## Compatibility
 
 - Ruby ≥ 3.2
-- OpenCode server ≥ 1.15
 - Runtime dependency: `activesupport (>= 6.1)` — *not* Rails. ActiveSupport is a standalone helpers gem (`blank?`, `present?`, `presence`, `truncate`, etc.).
 
+OpenCode server compatibility is evidence-based, not an open-ended SemVer
+promise. OpenCode's HTTP, SSE, and runtime behavior can change independently
+of a numeric version floor, so this gem does not infer compatibility from a
+constraint such as `>= 1.15`.
+
+Use the [OpenCode compatibility corpus](https://github.com/ajaynomics/opencode-compat)
+as the source of current evidence. Its
+[image matrix](https://github.com/ajaynomics/opencode-compat/blob/main/manifests/image-matrix.json)
+records the exact gem commit and immutable OpenCode OCI digest exercised by
+the `ruby-rest-sse` profile. Its
+[runtime tuples](https://github.com/ajaynomics/opencode-compat/blob/main/manifests/runtime-tuples.json)
+add the exact consumer commit and canary evidence needed for promotion and
+rollback. A version label or image tag is provenance only, never the execution
+coordinate.
+
+A combination absent from passing evidence is **unverified**, not necessarily
+incompatible. Run the corpus against the exact gem, image digest, and consumer
+commit before adopting or promoting it. See the
+[certification policy](https://github.com/ajaynomics/opencode-compat/blob/main/docs/certification.md)
+for the full process.
+
 ## Development
 
 ```sh
@@ -213,10 +236,13 @@ The smoke suite covers Client end-to-end against WebMock-stubbed OpenCode
 endpoints, including subscription-before-prompt ordering and
 reconnect-without-repost.
 
-Releases use RubyGems trusted publishing. After the repository's
+The repository contains a tag-triggered `release.yml` workflow intended for
-`release.yml` workflow is registered as a trusted publisher with the `release`
+RubyGems trusted publishing, but its RubyGems trusted-publisher registration is
-environment, pushing a `v*` tag builds, attests, and publishes the gem without
+not configured as of `0.0.1.alpha7`; that release was published manually. A
-a long-lived RubyGems API key.
+`v*` tag push therefore does not currently guarantee publication. Before a
+future release, verify the RubyGems registry result explicitly. Once the
+workflow is registered as a trusted publisher for the `release` environment,
+it can build, attest, and publish without a long-lived RubyGems API key.
 
 ## License
 

test/opencode/smoke_test.rb

@@ -126,6 +126,57 @@ class SmokeTest < Minitest::Test
     assert_equal({}, response)
   end
 
+  def test_send_message_async_serializes_a_structured_child_prompt
+    schema = {
+      type: "object",
+      properties: {
+        requirement_suggestions: {
+          type: "array",
+          items: { type: "string" }
+        }
+      },
+      required: [ "requirement_suggestions" ],
+      additionalProperties: false
+    }
+    invocation_query =
+      "Complete the bounded structured request from the preloaded worker skill and immutable Rails context."
+    expected_body = {
+      messageID: "msg_worker_1",
+      parts: [ { type: "text", text: invocation_query } ],
+      agent: "destination-list-curator",
+      format: {
+        type: "json_schema",
+        schema: schema,
+        retryCount: 0
+      },
+      system: "Immutable Rails context"
+    }
+    serialized_body = nil
+
+    prompt = stub_request(:post, "#{BASE}/session/#{SESSION_ID}/prompt_async")
+      .with(body: expected_body.to_json)
+      .to_return do |request|
+        serialized_body = request.body
+        { status: 204, body: "" }
+      end
+
+    @client.send_message_async(
+      SESSION_ID,
+      invocation_query,
+      agent: "destination-list-curator",
+      system: "Immutable Rails context",
+      message_id: "msg_worker_1",
+      format: {
+        type: "json_schema",
+        schema: schema,
+        retryCount: 0
+      }
+    )
+
+    assert_equal expected_body.to_json, serialized_body
+    assert_requested prompt, times: 1
+  end
+
   def test_stream_returns_typed_Reply_Result_with_full_text
     stub_request(:post, "#{BASE}/session/#{SESSION_ID}/prompt_async")
       .to_return(status: 204, body: "")

test/readme_contract_test.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ReadmeContractTest < Minitest::Test
+  README = File.read(File.expand_path("../README.md", __dir__))
+
+  def test_server_compatibility_points_to_exact_certification_evidence
+    assert_includes README, "https://github.com/ajaynomics/opencode-compat"
+    assert_includes README, "manifests/image-matrix.json"
+    assert_includes README, "manifests/runtime-tuples.json"
+    refute_match(/OpenCode server\s*(?:>=|≥)\s*\d/, README)
+  end
+
+  def test_release_guidance_does_not_claim_trusted_publishing_is_configured
+    assert_includes README, "not configured as of `0.0.1.alpha7`"
+    assert_includes README, "does not currently guarantee publication"
+  end
+end

test/release_workflow_test.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "yaml"
+
+class ReleaseWorkflowTest < Minitest::Test
+  ROOT = File.expand_path("..", __dir__)
+  WORKFLOW_PATH = File.join(ROOT, ".github", "workflows", "release.yml")
+
+  def workflow
+    @workflow ||= YAML.safe_load(File.read(WORKFLOW_PATH), aliases: false)
+  end
+
+  def push_job
+    workflow.fetch("jobs").fetch("push")
+  end
+
+  def test_release_job_is_inert_on_non_github_runners
+    assert_equal "${{ github.server_url == 'https://github.com' }}", push_job.fetch("if")
+  end
+
+  def test_release_job_keeps_the_trusted_publisher_boundary
+    assert_equal "release", push_job.fetch("environment")
+    assert_equal(
+      { "contents" => "write", "id-token" => "write" },
+      push_job.fetch("permissions")
+    )
+
+    steps = push_job.fetch("steps")
+    assert_equal 1, steps.count { |step| step["uses"] == "rubygems/release-gem@v1" }
+    refute steps.any? { |step| step.fetch("run", "").match?(/\bgem\s+push\b/) }
+  end
+end