wave6: the reference half of the coordinated pass (supersedes #77)

.doc_surface_floor

@@ -1 +1 @@
-64.7
+100.0

.github/workflows/doc-audit.yml

@@ -59,21 +59,36 @@ jobs:
       # deleted livewire member stops resolving instead of staying excused by a stale
       # committed file. Mirrors run-ci.sh's SURFACE-NATIVE gate (DOC-AUDIT deps on it).
       - name: Regenerate the native-only doc-audit sidecar
+        # `python` (the setup-python shim), not bare `python3` — see the PACKAGE-SMOKE
+        # note in multi-os.yml. This job is ubuntu-only, where setup-python front-loads
+        # its dir so both names currently resolve to the toolcache; using the shim keeps
+        # that true if this workflow ever gains a macOS runner, where bare `python3`
+        # resolves to the framework Python instead.
         run: |
-          python3 signalwire-python/scripts/emit_surface_native.py \
+          python signalwire-python/scripts/emit_surface_native.py \
             --out signalwire-python/port_surface_native.json
 
       - name: Run audit_docs.py against the Python surface
         # --native-names is load-bearing: signalwire.livewire.* is excluded from the
         # surface oracle by design, but livewire/ docs are in this perimeter, so its
         # real members only resolve via the sidecar. See scripts/emit_surface_native.py.
         run: |
-          python3 porting-sdk/scripts/audit_docs.py \
+          python porting-sdk/scripts/audit_docs.py \
             --root signalwire-python \
             --surface porting-sdk/python_surface.json \
             --ignore signalwire-python/DOC_AUDIT_IGNORE.md \
             --native-names signalwire-python/port_surface_native.json
 
+      # The DRIFT half of the regenerate/check pair, mirroring run-ci.sh's
+      # SURFACE-NATIVE-FRESH. Runs AFTER the audit has consumed the fresh file. On CI
+      # this cannot leak into a commit (the checkout is ephemeral), but it is what
+      # makes a STALE committed sidecar fail loudly here instead of passing unnoticed
+      # and then drifting further.
+      - name: Committed sidecar matches the regenerated one (no drift)
+        run: |
+          cd signalwire-python
+          git diff --exit-code -- port_surface_native.json
+
       - name: Summary
         if: always()
         run: |

.github/workflows/multi-os.yml

@@ -65,4 +65,16 @@ jobs:
       - name: PACKAGE-SMOKE (build + install + import from the built artifact)
         shell: bash
         working-directory: signalwire-python
-        run: python3 ../porting-sdk/scripts/package_smoke.py --port python --repo .
+        # `python`, not `python3`: use the SAME name `pip` above pairs with, so this
+        # step provably runs the interpreter the deps were installed into. (On the
+        # macOS/arm64 runner BOTH names resolve to the pre-installed framework Python
+        # — setup-python does not win PATH there — and `pip` is that Python's pip, so
+        # the whole job is consistently one interpreter. Pinning the name keeps it that
+        # way if the image's precedence ever changes.)
+        #
+        # The nightly failure (run 30238061313, macos-latest) was
+        # "No module named build" — NOT an interpreter mismatch: `build` was never a
+        # declared dependency at all, so the gate silently relied on the runner image
+        # shipping it. Now declared in requirements-dev.txt, which the step above
+        # installs. package_smoke.py is not at fault; it correctly uses sys.executable.
+        run: python ../porting-sdk/scripts/package_smoke.py --port python --repo .

docs/api_reference.md

@@ -2331,32 +2331,6 @@ data_map.webhook(
 )
 ```
 
-##### `body(data: Dict[str, Any]) -> DataMap`
-Set the JSON body for POST/PUT requests.
-
-**Parameters:**
-- `data` (Dict[str, Any]): JSON body data (supports `${variable}` substitution)
-
-**Usage:**
-```python
-# Static body with parameter substitution
-data_map.body({
-    'query': '${args.search_term}',
-    'limit': 5,
-    'filters': {
-        'category': '${args.category}',
-        'active': True
-    }
-})
-
-# Body with call-related data (NOT sensitive info)
-data_map.body({
-    'customer_id': '${global_data.customer_id}',
-    'request_id': '${meta_data.call_id}',
-    'search': '${args.query}'
-})
-```
-
 ##### `params(data: Dict[str, Any]) -> DataMap`
 Set URL query parameters.
 
@@ -2624,7 +2598,7 @@ search_tool = (DataMap('search_knowledge')
         'https://api.company.com/search',
         headers={'Authorization': 'Bearer TOKEN'}
     )
-    .body({
+    .params({
         'query': '${args.query}',
         'category': '${args.category}',
         'limit': 5
@@ -2695,7 +2669,7 @@ agent.register_swaig_function(swaig_function)
 
 The SDK provides helper functions for common DataMap patterns:
 
-##### `create_simple_api_tool(name: str, url: str, response_template: str, parameters: Optional[Dict[str, Dict]] = None, method: str = "GET", headers: Optional[Dict[str, str]] = None, body: Optional[Dict[str, Any]] = None, error_keys: Optional[List[str]] = None) -> DataMap`
+##### `create_simple_api_tool(name: str, url: str, response_template: str, parameters: Optional[Dict[str, Dict]] = None, method: str = "GET", headers: Optional[Dict[str, str]] = None, error_keys: Optional[List[str]] = None) -> DataMap`
 
 Create a simple API integration tool.
 
@@ -2706,7 +2680,6 @@ Create a simple API integration tool.
 - `parameters` (Optional[Dict[str, Dict]]): Parameter definitions
 - `method` (str): HTTP method (default: "GET")
 - `headers` (Optional[Dict[str, str]]): HTTP headers
-- `body` (Optional[Dict[str, Any]]): Request body
 - `error_keys` (Optional[List[str]]): Error field names
 
 **Usage:**

docs/configuration.md

@@ -193,6 +193,17 @@ All services share the same security configuration options:
 }
 ```
 
+### TLS misconfiguration fails hard
+
+When SSL is enabled (`ssl_enabled: true` / `SWML_SSL_ENABLED=true`) but the
+certificate or key is missing or unreadable, the server **refuses to start** and
+raises a `RuntimeError`. It does not fall back to plain HTTP.
+
+A silent downgrade would give an operator who asked for encryption a cleartext
+listener — carrying, among other things, the Basic-auth credentials — with no
+error and nothing in the logs to notice. If you want plain HTTP, disable SSL
+explicitly.
+
 ## Migration Guide
 
 ### From Environment Variables Only

eng/validate_schema.py

@@ -6,29 +6,28 @@
 
 Licensed under the MIT License.
 See LICENSE file in the project root for full license information.
-"""
 
-"""
 Validate a JSON file against a JSON Schema.
 
 Usage:
     python validate_schema.py <schema_file> <json_file>
-    
+
 Example:
     python validate_schema.py schema.json steps3.json
 """
 
+import argparse
 import json
 import sys
-import argparse
 from pathlib import Path
-from jsonschema import validate, ValidationError, Draft7Validator
+
+from jsonschema import Draft7Validator, ValidationError, validate
 
 
 def load_json_file(filepath):
     """Load and parse a JSON file."""
     try:
-        with open(filepath, 'r') as f:
+        with Path(filepath).open() as f:
             return json.load(f)
     except FileNotFoundError:
         print(f"❌ Error: File '{filepath}' not found")
@@ -43,57 +42,59 @@ def validate_json(schema_file, json_file, verbose=False):
     # Load files
     print(f"Loading schema from: {schema_file}")
     schema = load_json_file(schema_file)
-    
+
     print(f"Loading JSON from: {json_file}")
     data = load_json_file(json_file)
-    
+
     # Try to validate
     try:
         validate(instance=data, schema=schema)
         print("\n✅ Validation PASSED!")
         return True
-        
+
     except ValidationError as e:
-        print(f"\n❌ Validation FAILED!")
+        print("\n❌ Validation FAILED!")
         print(f"\nError: {e.message}")
-        
+
         # Show the path where the error occurred
         if e.path:
             path_str = " -> ".join(str(p) for p in e.path)
             print(f"Location: {path_str}")
-        
+
         # Show the failing value if verbose
         if verbose and e.instance is not None:
             print(f"\nFailing value: {json.dumps(e.instance, indent=2)[:200]}...")
-        
+
         # Show all errors if there are multiple
         validator = Draft7Validator(schema)
         errors = list(validator.iter_errors(data))
-        
+
         if len(errors) > 1:
             print(f"\nFound {len(errors)} validation errors:")
             for i, error in enumerate(errors, 1):
                 print(f"\n{i}. {error.message}")
                 if error.path:
                     path_str = " -> ".join(str(p) for p in error.path)
                     print(f"   Location: {path_str}")
-                
+
                 # Show schema constraint that failed
                 if verbose and error.validator:
                     print(f"   Failed constraint: {error.validator}")
                     if error.validator_value is not None:
-                        print(f"   Expected: {json.dumps(error.validator_value, indent=2)[:100]}...")
-
+                        print(
+                            f"   Expected: {json.dumps(error.validator_value, indent=2)[:100]}..."
+                        )
+
         return False
-        
+
     except Exception as e:
         print(f"\n❌ Unexpected error: {e}")
         return False
 
 
 def main():
     parser = argparse.ArgumentParser(
-        description='Validate a JSON file against a JSON Schema',
+        description="Validate a JSON file against a JSON Schema",
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
@@ -105,79 +106,83 @@ def main():
 
   # Validate AI config extracted from SWML
   python validate_schema.py --extract-ai schema.json steps3.json
-        """
+        """,
     )
-
-    parser.add_argument('schema', help='Path to the JSON Schema file')
-    parser.add_argument('json_file', help='Path to the JSON file to validate')
-    parser.add_argument('-v', '--verbose', action='store_true',
-                        help='Show detailed error information')
-    parser.add_argument('--extract-ai', action='store_true',
-                        help='Extract and validate just the AI config from SWML format')
-
+
+    parser.add_argument("schema", help="Path to the JSON Schema file")
+    parser.add_argument("json_file", help="Path to the JSON file to validate")
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Show detailed error information"
+    )
+    parser.add_argument(
+        "--extract-ai",
+        action="store_true",
+        help="Extract and validate just the AI config from SWML format",
+    )
+
     args = parser.parse_args()
-    
+
     # Check if files exist
     if not Path(args.schema).exists():
         print(f"❌ Error: Schema file '{args.schema}' not found")
         sys.exit(1)
-    
+
     if not Path(args.json_file).exists():
         print(f"❌ Error: JSON file '{args.json_file}' not found")
         sys.exit(1)
-    
+
     # Special handling for AI config extraction
     if args.extract_ai:
         print("Extracting AI config from SWML format...")
         data = load_json_file(args.json_file)
         schema = load_json_file(args.schema)
-        
+
         # Extract AI config
         ai_config = None
-        if 'sections' in data and 'main' in data.get('sections', {}):
-            main_section = data.get('sections', {}).get('main', [])
+        if "sections" in data and "main" in data.get("sections", {}):
+            main_section = data.get("sections", {}).get("main", [])
             for item in main_section:
-                if isinstance(item, dict) and 'ai' in item:
-                    ai_config = item['ai']
+                if isinstance(item, dict) and "ai" in item:
+                    ai_config = item["ai"]
                     break
-        
+
         if not ai_config:
             print("❌ Error: No AI config found in SWML format")
             sys.exit(1)
-        
+
         # Extract AI schema
         ai_schema = None
-        if '$defs' in schema and 'AI' in schema['$defs']:
-            ai_def = schema['$defs']['AI']
-            if 'properties' in ai_def and 'ai' in ai_def['properties']:
-                ai_schema = ai_def['properties']['ai'].copy()
+        if "$defs" in schema and "AI" in schema["$defs"]:
+            ai_def = schema["$defs"]["AI"]
+            if "properties" in ai_def and "ai" in ai_def["properties"]:
+                ai_schema = ai_def["properties"]["ai"].copy()
                 # Create a new schema with only necessary definitions
                 ai_schema_full = {
                     "$schema": "http://json-schema.org/draft-07/schema#",
                     **ai_schema,
-                    "$defs": schema['$defs']
+                    "$defs": schema["$defs"],
                 }
-        
+
         if not ai_schema:
             print("❌ Error: Could not extract AI schema")
             sys.exit(1)
-        
+
         # Validate directly without writing temp files
         try:
             validate(instance=ai_config, schema=ai_schema_full)
             print("\n✅ AI config validation PASSED!")
             success = True
         except ValidationError as e:
-            print(f"\n❌ AI config validation FAILED!")
+            print("\n❌ AI config validation FAILED!")
             print(f"\nFirst error: {e.message}")
             if e.path:
                 path_str = " -> ".join(str(p) for p in e.path)
                 print(f"Location: {path_str}")
-            
+
             # Show all errors
             validator = Draft7Validator(ai_schema_full)
             errors = list(validator.iter_errors(ai_config))
-            
+
             if len(errors) > 1:
                 print(f"\nFound {len(errors)} validation errors in total:")
                 for i, error in enumerate(errors, 1):
@@ -187,14 +192,14 @@ def main():
                         print(f"   Location: {path_str}")
                     if args.verbose and error.validator:
                         print(f"   Failed constraint: {error.validator}")
-            
+
             success = False
     else:
         # Normal validation
         success = validate_json(args.schema, args.json_file, args.verbose)
-    
+
     sys.exit(0 if success else 1)
 
 
-if __name__ == '__main__':
-    main()
+if __name__ == "__main__":
+    main()

examples/data_map_demo.py

@@ -115,7 +115,7 @@ def setup(self):
                     "Content-Type": "application/json",
                 },
             )
-            .body({"query": "${query}", "limit": "${limit}"})
+            .params({"query": "${query}", "limit": "${limit}"})
             .foreach(
                 {
                     "input_key": "${response.results}",
@@ -271,7 +271,7 @@ def print_data_map_examples():
             "https://api.docs.com/search",
             headers={"Authorization": "Bearer TOKEN"},
         )
-        .body({"query": "${query}", "limit": 3})
+        .params({"query": "${query}", "limit": 3})
         .foreach(
             {
                 "input_key": "${response.results}",