wave6: retire dead ctor entries (ALLOWLIST_DISCIPLINE §495, shared-diff fold)

.doc_surface_floor

@@ -1 +1 @@
-51.8
+100.0

.github/workflows/nightly.yml

@@ -119,6 +119,24 @@ jobs:
           pip install -e porting-sdk/test_harness/mock_relay
           pip install -e porting-sdk/test_harness/mock_signalwire
 
+      # ruff backs the PY-LINT / PY-FMT gates over the hand-written Python in
+      # scripts/ (the 5 code generators, the surface enumerator, _gen_format.py).
+      # scripts/_env.sh fails LOUD when ruff is absent rather than skipping, so
+      # the gate cannot pass vacuously on a runner that lacks it.
+      #
+      # VERSION PINNED, in lockstep with SW_RUFF_VERSION in scripts/_env.sh.
+      # A bare `pip install ruff` resolved the newest release at CI time while a
+      # contributor ran whatever they installed months ago, so a ruff that adds a
+      # rule or changes a format heuristic reds PY-LINT/PY-FMT on code that never
+      # changed — and no local run reproduces it. _env.sh asserts the same version
+      # at gate time, so a pin that silently did not take is caught rather than
+      # quietly producing a different verdict.
+      - name: Install ruff (PY-LINT / PY-FMT gates)
+        run: |
+          pip install ruff==0.15.21
+          ruff --version
+          ruff --version | grep -qw '0\.15\.21' || { echo "FATAL: ruff is not the pinned 0.15.21" >&2; exit 1; }
+
       # EMISSION needs `import signalwire` (the oracle). Install from the
       # adjacent checkout only if not already importable.
       - name: Install signalwire-python (EMISSION oracle) if not importable
@@ -197,6 +215,24 @@ jobs:
           pip install -e porting-sdk/test_harness/mock_relay
           pip install -e porting-sdk/test_harness/mock_signalwire
 
+      # ruff backs the PY-LINT / PY-FMT gates over the hand-written Python in
+      # scripts/ (the 5 code generators, the surface enumerator, _gen_format.py).
+      # scripts/_env.sh fails LOUD when ruff is absent rather than skipping, so
+      # the gate cannot pass vacuously on a runner that lacks it.
+      #
+      # VERSION PINNED, in lockstep with SW_RUFF_VERSION in scripts/_env.sh.
+      # A bare `pip install ruff` resolved the newest release at CI time while a
+      # contributor ran whatever they installed months ago, so a ruff that adds a
+      # rule or changes a format heuristic reds PY-LINT/PY-FMT on code that never
+      # changed — and no local run reproduces it. _env.sh asserts the same version
+      # at gate time, so a pin that silently did not take is caught rather than
+      # quietly producing a different verdict.
+      - name: Install ruff (PY-LINT / PY-FMT gates)
+        run: |
+          pip install ruff==0.15.21
+          ruff --version
+          ruff --version | grep -qw '0\.15\.21' || { echo "FATAL: ruff is not the pinned 0.15.21" >&2; exit 1; }
+
       # A clean-bundle require + the full suite on the forward Ruby: -w surfaces any
       # deprecation warning from a stdlib gem that was extracted from the defaults.
       - name: Require smoke + gemspec-dependency honesty (extracted-stdlib deps)

.github/workflows/publish.yml

@@ -48,6 +48,25 @@ jobs:
           pip install -e porting-sdk/test_harness/mock_relay
           pip install -e porting-sdk/test_harness/mock_signalwire
 
+      # ruff backs the PY-LINT / PY-FMT gates over the hand-written Python in
+      # scripts/ (the 5 code generators, the surface enumerator, _gen_format.py).
+      # scripts/_env.sh fails LOUD when ruff is absent rather than skipping, so
+      # the gate cannot pass vacuously on a runner that lacks it.
+      #
+      # VERSION PINNED, in lockstep with SW_RUFF_VERSION in scripts/_env.sh.
+      # A bare `pip install ruff` resolved the newest release at CI time while a
+      # contributor ran whatever they installed months ago, so a ruff that adds a
+      # rule or changes a format heuristic reds PY-LINT/PY-FMT on code that never
+      # changed — and no local run reproduces it. That matters most HERE: this
+      # workflow gates a RELEASE, so a floating linter could block a publish on a
+      # tag whose tree was green when it was cut. _env.sh asserts the same version
+      # at gate time, so a pin that silently did not take is caught.
+      - name: Install ruff (PY-LINT / PY-FMT gates)
+        run: |
+          pip install ruff==0.15.21
+          ruff --version
+          ruff --version | grep -qw '0\.15\.21' || { echo "FATAL: ruff is not the pinned 0.15.21" >&2; exit 1; }
+
       - name: Run CI gate script (full run-ci.sh — the same gate set as PR CI)
         working-directory: signalwire-ruby
         env:

.github/workflows/test.yml

@@ -61,6 +61,29 @@ jobs:
           pip install -e porting-sdk/test_harness/mock_relay
           pip install -e porting-sdk/test_harness/mock_signalwire
 
+      # ruff backs the PY-LINT / PY-FMT gates over the hand-written Python in
+      # scripts/ (the 5 code generators, the surface enumerator, _gen_format.py).
+      # scripts/_env.sh fails LOUD when ruff is absent rather than skipping, so
+      # the gate cannot pass vacuously on a runner that lacks it — hence this
+      # explicit install rather than relying on it being preinstalled.
+      #
+      # VERSION PINNED, in lockstep with SW_RUFF_VERSION in scripts/_env.sh.
+      # A bare `pip install ruff` resolved the newest release at CI time while a
+      # contributor ran whatever they installed months ago, so a ruff that adds a
+      # rule or changes a format heuristic reds PY-LINT/PY-FMT on code that never
+      # changed — and no local run reproduces it. This repo already paid for that
+      # shape through rubocop: an open floor ('>= 1.80') let CI resolve 1.89.0
+      # against a local 1.88.0, and 1.89's tightened
+      # Layout/MultilineMethodCallIndentation failed CI with 3 offenses on a
+      # commit whose local run reported "no offenses detected". _env.sh asserts
+      # the same version at gate time, so a pin that silently did not take is
+      # caught rather than quietly producing a different verdict.
+      - name: Install ruff (PY-LINT / PY-FMT gates)
+        run: |
+          pip install ruff==0.15.21
+          ruff --version
+          ruff --version | grep -qw '0\.15\.21' || { echo "FATAL: ruff is not the pinned 0.15.21" >&2; exit 1; }
+
       # EMISSION needs `import signalwire` (the oracle). Install from the
       # adjacent checkout only if not already importable.
       - name: Install signalwire-python (EMISSION oracle) if not importable

.rubocop.yml

@@ -23,34 +23,15 @@ AllCops:
   TargetRubyVersion: 3.2
   SuggestExtensions: false
   Exclude:
-    # Demo programs, not library surface — excluded from the blocking gate the way
-    # signalwire-go tags its examples //go:build ignore. They are not part of the
-    # audited public surface and are free to read as tutorial-style code.
-    - 'examples/**/*'
-    - 'relay/examples/**/*'
-    - 'rest/examples/**/*'
+    # THIRD-PARTY code we do not own. This is the ONLY directory-level carve-out.
+    # Everything else in this repo — lib/, tests/, examples/, relay/examples/,
+    # rest/examples/, bin/ (including the *-dump programs), scripts/ — is linted
+    # and formatted at the SAME bar as the shipped library. Owner ruling
+    # 2026-07-30: "examples and tests are shipping code too ... all at the levels
+    # the shipping code gets." The prior "tutorial-style / not audited public
+    # surface" rationale was about PUBLIC-SURFACE AUDITING, not about whether the
+    # code should be well-formed; it is not a reason to hold it below the bar.
     - 'vendor/**/*'
-    # Layer-D cross-port dump programs (bin/*-dump) — the per-surface behavioral
-    # differ tooling, mirroring the Go reference's cmd/*-dump. Tutorial-style
-    # port-native dispatch programs, not audited library surface; same rationale
-    # as examples/ above and go's //go:build ignore dumps.
-    - 'bin/wire-dump'
-    - 'bin/swml-dump'
-    - 'bin/state-dump'
-    - 'bin/http-dump'
-    - 'bin/envelope-dump'
-    - 'bin/wire-relay-dump'
-    - 'bin/wait-liveness-dump'
-    - 'bin/secure-default-dump'
-    - 'bin/relay-liveness-dump'
-    - 'bin/pagination-dump'
-    - 'bin/secret-scrub-dump'
-    - 'bin/ai-chat-dump'
-    # Cross-port gate fixture-replay tooling, same category as the bin/*-dump
-    # programs above: doc_wire_runner.rb only DRIVES the documented REST calls
-    # against the DOC-WIRE flag-mode mock so it journals the wire shape. Not
-    # audited library surface.
-    - 'scripts/doc_wire_runner.rb'
     # NOTE: the machine-generated trees (REST resource layer, READ-SIDE typed
     # payload trees, and the full-mock REST wire-test suite) are DELIBERATELY NOT
     # excluded here — generated code is linted like hand-written code so a
@@ -195,6 +176,38 @@ Metrics/ModuleLength:
 Metrics/MethodLength:
   Exclude:
     - 'lib/signalwire/skills/builtin/mcp_gateway.rb'
+    # signature_dump.rb's Ripper default-value extractor: same DATA-SHAPE (not
+    # logic) rationale. Its size is a 1:1 DISPATCH over Ruby's literal AST node
+    # types (int/float/keyword/string/symbol/array/hash), one arm per node kind
+    # the parser can emit. The arms were already extracted into named
+    # per-node-type helpers (ripper_string_literal / ripper_array_literal /
+    # ripper_hash_literal / ...); what remains is the irreducible dispatch itself
+    # plus each helper's exhaustive shape-guard chain. Splitting further would
+    # scatter one node type's handling across two methods and make it HARDER to
+    # confirm the extractor rejects every non-literal — which is the property
+    # that keeps it from emitting a fabricated default. Size only; no naming or
+    # type idiom is being suppressed.
+    - 'scripts/signature_dump.rb'
+
+# Same scope + same rationale as the Metrics/MethodLength entry above, for the
+# same file. A literal-AST extractor's "complexity" is entirely SHAPE-GUARDING:
+# every branch asks "is this node actually the literal it looks like?" (is it an
+# Array, is its head the expected tag, does a string contain an interpolation,
+# is every array element itself a literal). Those guards are the correctness
+# property — each one is a place the extractor declines to invent a value it
+# cannot prove — so collapsing them to satisfy a branch count would trade the
+# gate's honesty for a metric. Scoped to this file only.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'scripts/signature_dump.rb'
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'scripts/signature_dump.rb'
+
+Metrics/AbcSize:
+  Exclude:
+    - 'scripts/signature_dump.rb'
 
 # Prefer keyword args for boolean defaults — a good cop in general, but a known
 # false positive on FLUENT SINGLE-ARGUMENT TOGGLES, which is exactly these sites:

.version-frozen

@@ -0,0 +1,38 @@
+# VERSION FREEZE — TEMPORARY. DELETE THIS FILE BEFORE RELEASING.
+#
+# Ruled by the owner 2026-07-28. This port declares version 3.0.0, and its SemVer
+# release floor (port_signatures.baseline.json -> baseline_version) is pinned at
+# 3.0.0 with the recorded surface payload overwritten to match today's surface.
+#
+# THIS FILE IS DOCUMENTATION ONLY (owner ruling, 2026-07-28). No gate reads it and
+# nothing fails if it is present. It exists so that neither a person nor a future
+# session has to re-derive why the versions look the way they do — and so nobody
+# casually bumps one.
+#
+# WHY THE FREEZE: versions had drifted to 3.0.2 / 3.2.0 / 3.2.1 / 3.3.0 / 4.0.0
+# across the fleet with NOTHING EVER PUBLISHED above v2.x. `git ls-remote --tags
+# origin` tops out at v1.1.2 for rust/dotnet and v2.0.x for most others; php's
+# v3.2.0 tag is local-only, zero remote matches. That scatter was never a release
+# history, so collapsing it rewrote nothing real.
+#
+# WHILE THIS FILE EXISTS:
+#   - do NOT bump this port's version
+#   - do NOT re-anchor its release floor
+#   - DO land surface changes freely. The floor is a snapshot of the 3.0.0 wave,
+#     not of a published release, so SEMVER-DIFF will not flag anything already in
+#     today's surface. Anything added AFTER the freeze is still caught normally.
+#
+# BEFORE CUTTING A RELEASE:
+#   1. DELETE this file in every port.
+#   2. Re-anchor each port_signatures.baseline.json to the actual released
+#      commit/tag and regenerate its surface payload from that point.
+#   3. Re-enable enforcement: ports invoke SEMVER-DIFF with --report-only today
+#      (the D5 "re-anchor at cut" setting). Dropping that flag turns semver
+#      enforcement back on.
+#
+# NOTE: perl is deliberately NOT floor-pinned. It is the only port anchored to a
+# genuinely published tag (v2.0.2, sha 83376ff) and already passes at 3.0.0;
+# overwriting it would destroy the fleet's only real release anchor.
+#
+# Owner rulings: porting-sdk tasks #143 (version) and #146 (floor).
+# Full context: porting-sdk/SESSION_HANDOFF_2026-07-28.md

CHANGELOG.md

@@ -3,32 +3,28 @@
 All notable changes to the SignalWire AI Agents SDK for Ruby (`signalwire-sdk`)
 are documented here. This project adheres to [Semantic Versioning](https://semver.org).
 
-## 3.2.0
+## 3.0.0
 
-### Added
-- `client.messages` — the new `/api/messaging/messages` send/redact REST
-  resource (`create` to send an SMS/MMS message, `update` to redact a message
-  body). Distinct from the `client.logs.messages` message-log namespace.
-  Generated from the canonical `messages` REST spec with full success + error
-  wire-test coverage.
-
-## 3.1.0
+Parity release aligning the Ruby SDK with the Python reference SDK across the
+REST, RELAY, SWML, and SWAIG surfaces, and the fleet-wide convergence version:
+every SignalWire SDK port declares 3.0.0. Nothing in the 3.x range was ever
+published — this port's published tags top out at `v2.0.0` — so the
+previously-drafted unreleased 3.0.2 / 3.1.0 / 3.2.0 entries are consolidated
+here rather than shipped as a staggered series.
 
 ### Added
+- Spec-generated REST surface: a typed REST client with generated typed I/O and
+  full success + error wire-test coverage across the SignalWire REST namespaces.
 - `client.projects` — the new `/api/projects` full-CRUD project-management REST
   resource (list / create / get / update / delete subprojects, plus
   `rotate_signing_key`). Distinct from the singular `client.project` token
   namespace. Generated from the canonical `projects` REST spec with full
   success + error wire-test coverage.
-
-## 3.0.2
-
-Parity release aligning the Ruby SDK with the Python reference SDK across the
-REST, RELAY, SWML, and SWAIG surfaces.
-
-### Added
-- Spec-generated REST surface: a typed REST client with generated typed I/O and
-  full success + error wire-test coverage across the SignalWire REST namespaces.
+- `client.messages` — the new `/api/messaging/messages` send/redact REST
+  resource (`create` to send an SMS/MMS message, `update` to redact a message
+  body). Distinct from the `client.logs.messages` message-log namespace.
+  Generated from the canonical `messages` REST spec with full success + error
+  wire-test coverage.
 - `paginate()` parity on read resources via a `PaginatedIterator`.
 - Typed SWAIG `ParameterSchema` builder for `define_tool`, and typed RELAY state
   enums (`Device`, `CollectConfig`, record/tap direction/format/codec, skill names).

CLAUDE.md

@@ -86,7 +86,7 @@ ruby bin/sw-search ./docs --output knowledge.swsearch
 #### Agent Creation
 Agents inherit from `SignalWire::AgentBase` and define:
 - Prompt Object Model (POM) sections via `prompt_add_section`
-- SWAIG functions via `define_tool` with block handlers
+- SWAIG functions via `define_tool` (`handler:` is a required keyword; pass `handler: nil` to use a block)
 - Skills integration via `add_skill` method
 - All configuration methods return `self` for chaining
 
@@ -97,7 +97,8 @@ agent.define_tool(
   description: 'Get current weather',
   parameters: {
     'city' => { 'type' => 'string', 'description' => 'City name' }
-  }
+  },
+  handler: nil
 ) do |args, raw_data|
   SignalWire::Swaig::FunctionResult.new("Weather in #{args['city']}: 72F")
 end

Gemfile

@@ -19,7 +19,16 @@ group :development, :test do
   gem 'rack-test', '>= 2.0'
   gem 'rake', '>= 13.0'
   # Lint/format quality floor (FMT + LINT gates in scripts/run-ci.sh).
-  gem 'rubocop', '>= 1.80'
-  gem 'rubocop-minitest', '>= 0.38'
-  gem 'rubocop-performance', '>= 1.25'
+  #
+  # These carry an upper bound on the MINOR version, not just a floor. With an
+  # open floor ('>= 1.80'), CI resolves the newest release while local runs use
+  # the committed Gemfile.lock, so a rubocop release that adds or tightens a cop
+  # turns CI red with no code change and local FMT/LINT cannot reproduce it.
+  # That happened with 1.89.0, which tightened
+  # Layout/MultilineMethodCallIndentation: local 1.88.0 reported 0 offenses on
+  # the exact commit CI failed with 3. Bump these deliberately (and fix the new
+  # offenses in the same commit) rather than letting CI float.
+  gem 'rubocop', '>= 1.89', '< 1.90'
+  gem 'rubocop-minitest', '>= 0.40', '< 0.41'
+  gem 'rubocop-performance', '>= 1.26', '< 1.27'
 end