restless-sdk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1147b0604f0fdb6ca8b2cdd39ffe03819391d0e5d663b70fa845fbe4b4b72b27
-  data.tar.gz: f1bd487a972936ae678151d03f27edecb476b8c1f7b755ff5a88157f5d015e4e
+  metadata.gz: a346b73df699fa4b309117f63c42f284a971d392fff96ac0321510c9b5c06327
+  data.tar.gz: a57d20173e1a974bc5fde6b9c7dd6c20e4239f4f7c70cd572863f97628d9ddfc
 SHA512:
-  metadata.gz: f7508f1e2f878289a16930cd56db0a0c5e150dc6fd5772a0c221cb97792a703f130f15d6a99e401b81bb713edbceba5adc835da4d994600248911f4d7f86b558
-  data.tar.gz: c6e94661d61836cdb2dc408beefc0e5323afd17ffb3c5ec2e68beb2ec5ab1687af64ae72a6a8726d97e265d4a1343b04dea320687e0b952a7c392f279851e71d
+  metadata.gz: 34762d9a43d3294b0448c75a683a158d5ce241d88961177bfbcc215969bf9b4a6f6e0f362cfdb31973e8d05de827a8c56d243ab224132b0f3f3a96c4f7ba0c1b
+  data.tar.gz: bbc49f5ffc1a24e563a4cc609cc6f3a95d43b3f3d4090c78826b83c68cdb4ec5d4aab36cfd7b795ce033ed2e5796d56f0a89c3196d40b49b6227affa0ee13487

data/CONFORMANCE.md

@@ -2,7 +2,7 @@
 
 | | |
 |---|---|
-| **Spec version** | 1.0.0 |
+| **Spec version** | 1.0.1 |
 | **Level** | L2 (core + batching, caches, injection, safety) |
 | **Reference** | `restlesshq/node` (`@restlessai/sdk`) |
 | **Driver** | `ruby exe/restless-conformance` |
@@ -12,7 +12,7 @@ Declared in `lib/restless/version.rb` (META-001).
 ## Verifying
 
 The harness and vectors live in the reference SDK, so the commands below
-assume it is checked out as a sibling (`../node-sdk`), which is how
+assume it is checked out as a sibling (`../node`), which is how
 `setup.sh` in the install repo arranges things. The vectors in `spec/` here
 are a pinned copy, so `ruby -Ilib -Itest test/all.rb` alone works without it.
 
@@ -22,11 +22,11 @@ are a pinned copy, so `ruby -Ilib -Itest test/all.rb` alone works without it.
 ruby -Ilib -Itest test/all.rb
 
 # the shared cross-language harness
-node ../node-sdk/spec/harness/run-vectors.mjs -- ruby exe/restless-conformance
+node ../node/spec/harness/run-vectors.mjs -- ruby exe/restless-conformance
 
 # differential fuzz against the reference implementation
-node ../node-sdk/spec/harness/fuzz.mjs \
-  --ref  "node ../node-sdk/spec/driver/.build/node.js" \
+node ../node/spec/harness/fuzz.mjs \
+  --ref  "node ../node/spec/driver/.build/node.js" \
   --test "ruby exe/restless-conformance" \
   --iterations 8000 --seed 24301
 ```

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright © 2026 Restless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,3 +1,16 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/restless-init-dark.svg">
+  <img width="100%" src="docs/restless-init.svg" alt="Restless">
+</picture>
+
+Run in your codebase to get started:
+
+```sh
+npx restless init
+```
+
+This scans your project, figures out your framework, generates an OpenAPI spec, and automatically wires the SDK into your server.
+
 # restless-sdk
 
 Capture your API traffic and send it to [Restless](https://restless.ai).
@@ -5,7 +18,9 @@ Capture your API traffic and send it to [Restless](https://restless.ai).
 One Rack middleware covers **Rails**, **Sinatra**, **Hanami**, **Grape**,
 **Roda** and anything else that speaks Rack. Ruby 2.6+. No dependencies.
 
-## Install
+## Manual installation
+
+If you'd rather wire it up by hand:
 
 ```sh
 gem install restless-sdk
@@ -68,8 +83,8 @@ and body your app produced rather than an inner layer's.
   and friends are redacted before anything leaves your process. Bodies with
   nothing to redact are passed through byte for byte, so your payloads are
   never re-serialized on the way out.
-- **Error triage.** 4xx/5xx responses get `x-log-url` and `x-debug` headers
-  and a `debug` block in the JSON body. If someone attaches a "next steps"
+- **Error triage.** Every response gets `x-log-url` and `x-debug` headers,
+  and 4xx/5xx responses also get a `debug` block in the JSON body. If someone attaches a "next steps"
   message to an error in the dashboard, the SDK injects it as
   `debug.recovery` - read synchronously from an in-process cache, never
   blocking the response on a network call. A 5xx that groups by its throw
@@ -144,5 +159,4 @@ differential fuzzer run against the reference implementation. See
 [CONFORMANCE.md](./CONFORMANCE.md).
 
 ## License
-
-ISC
+MIT

data/exe/restless-conformance

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# The Ruby conformance driver. See node-sdk/spec/driver/PROTOCOL.md.
+# The Ruby conformance driver. See sdk/node/spec/driver/PROTOCOL.md.
 #
 # Dev-only: it is a thin shell over Restless::Conformance, which
 # test/test_vectors.rb also uses, so the vectors cannot describe behaviour the

data/install.md

@@ -191,7 +191,7 @@ api_key: CLIENT.mask(request.header("Authorization") || "anonymous")
 
 ## 7. `.restless/settings.json`
 
-Read at startup, walking up from the working directory. Created and owned by the `api` CLI (`npx api setup`). Every Restless SDK reads the same file with the same camelCase keys, so a polyglot repo needs only one.
+Read at startup, walking up from the working directory. Created and owned by the `restless` CLI (`npx restless init`). Every Restless SDK reads the same file with the same camelCase keys, so a polyglot repo needs only one.
 
 ```json
 {
@@ -247,7 +247,8 @@ Bodies are capped at **256 KiB** (UTF-8 bytes) and truncated with `[...TRUNCATED
 
 - Request IDs are v4 UUIDs, never time-based, so they leak no ordering.
 - Every response gets `x-restless-id`. `x-request-id` is set only if the caller did not send one, and an incoming value is never reused as ours.
-- On status **>= 400** the SDK adds `x-log-url` and `x-debug` headers, and merges a `debug` key into a JSON body. There is no user-configurable hook for this.
+- On **every** status the SDK adds `x-log-url` and `x-debug` headers; on status **>= 400** it also merges a `debug` key into a JSON body. There is no user-configurable hook for this.
+- `x-log-url` points at your project's public docs host, which the server tells the SDK on each upload. Until the first upload round-trips it is omitted rather than guessed: a URL that 404s is worse than no URL. The ingest host is never used for it.
 
 ## 10. Blocking
 
@@ -295,5 +296,5 @@ Batching is fixed: 10 requests per batch, a 5000 ms flush interval, a 1000-entry
 1. `restless-sdk` appears in the `Gemfile`, and `bundle list` finds it.
 2. `CLIENT.rack` is mounted in `config.ru` or `config/application.rb`, as far out as possible.
 3. A `CLIENT.setup` block exists and reads its header via `request.header(...)`.
-4. `.restless/settings.json` exists (created by `npx api setup`).
+4. `.restless/settings.json` exists (created by `npx restless init`).
 5. Starting the server and curling any endpoint returns an `x-restless-id` response header.

data/lib/restless/capture.rb

@@ -25,7 +25,7 @@ module Restless
       @redact = redact || {}
       @enrich_cache = EnrichCache.new
       @recovery_cache = RecoveryCache.new
-      @docs_url = nil
+      @portal_url = nil
       @docs_mutex = Mutex.new
       @callback = nil
       @uploader = Uploader.new(
@@ -43,8 +43,11 @@ module Restless
 
     # INJECT-006. The latest server-resolved docs origin, or nil when no batch
     # has round-tripped yet.
-    def docs_url
-      @docs_mutex.synchronize { @docs_url }
+    # INJECT-006. The server-published portal origin every injected URL is
+    # built on. Nil before the first upload round-trip, and then nothing is
+    # emitted rather than a guess.
+    def portal_url
+      @docs_mutex.synchronize { @portal_url }
     end
 
     def flush
@@ -61,7 +64,9 @@ module Restless
       docs = body["docsUrl"]
       if docs.is_a?(String) && !docs.empty?
         # Origin only; strip trailing slashes so the server can be lax.
-        @docs_mutex.synchronize { @docs_url = docs.sub(%r{/+\z}, "") }
+        # The wire key stays `docsUrl`: every already-deployed SDK reads it,
+        # so renaming would strand them all with no portal origin (WIRE-023).
+        @docs_mutex.synchronize { @portal_url = docs.sub(%r{/+\z}, "") }
       end
 
       messages = body["recoveryMessages"].is_a?(Hash) ? body["recoveryMessages"] : {}

data/lib/restless/conformance.rb

@@ -16,7 +16,7 @@ module Restless
   # through this one file, so it is impossible for the vectors to describe
   # behaviour the driver does not exhibit.
   #
-  # See node-sdk/spec/driver/PROTOCOL.md. Internal: never part of the public
+  # See sdk/node/spec/driver/PROTOCOL.md. Internal: never part of the public
   # API, never shipped behaviour a customer depends on.
   module Conformance
     # An input this implementation's language cannot represent or parse. The
@@ -79,6 +79,8 @@ module Restless
       # --- injection (section 10) ---
       when "recoverySlug"
         Injection.recovery_slug(str_or_nil(input["method"]), str_or_nil(input["path"]))
+      when "debugInjection"
+        debug_injection(input)
 
       # --- HAR (section 7) ---
       when "harEntry"
@@ -89,6 +91,21 @@ module Restless
       end
     end
 
+    # The observable surface only: the headers, and the `debug` object the
+    # adapter would merge (nil when there is nothing to merge).
+    def debug_injection(input)
+      built = Injection.build(
+        status: input["status"].to_i,
+        request_id: str(input["requestId"]),
+        prefix: str_or_nil(input["prefix"]),
+        recovery: str_or_nil(input["recovery"]),
+        method: str_or_nil(input["method"]),
+        path: str_or_nil(input["path"]),
+        portal_url: str_or_nil(input["portalUrl"])
+      )
+      { "headers" => built[:headers], "debug" => built[:debug] }
+    end
+
     def fingerprint(input)
       stack = stack_text(input["stackTrace"])
       if !stack.empty? && v8_dialect?(stack)

data/lib/restless/injection.rb

@@ -31,19 +31,37 @@ module Restless
       flat.empty? ? m : "#{m}-#{flat}"
     end
 
+    # INJECT-002. The debug response headers, which ship on every status.
+    #
+    # `x-log-url` is omitted with no portal origin; `x-debug` carries no URL,
+    # so it always ships.
+    def headers(request_id:, prefix: nil, portal_url: nil)
+      display = RequestId.format_request_id(request_id, prefix)
+      out = { "x-debug" => "npx api debug #{display}" }
+      out["x-log-url"] = "#{portal_url}/logs/#{request_id}" unless portal_url.nil? || portal_url.empty?
+      out
+    end
+
     # INJECT-001..004, INJECT-006. Returns the headers to set plus the `debug`
-    # object to merge into a JSON body, or nil when nothing should be injected.
-    def build(status:, request_id:, base_url:, prefix: nil, recovery: nil,
-              method: nil, path: nil, docs_url: nil)
-      return nil if status < 400 # INJECT-001
+    # object to merge into a JSON body (nil when there is nothing to merge).
+    #
+    # `portal_url` is the project's public portal origin, published by the
+    # server. It is NOT the ingest base URL, which serves `/v1/*` and would
+    # 404 both paths, and there is deliberately no fallback to it: with no
+    # portal origin we emit `x-debug` alone. A caller cannot tell a broken URL
+    # from a missing one, and one fetched 404 teaches an agent to stop
+    # following the link.
+    def build(status:, request_id:, prefix: nil, recovery: nil,
+              method: nil, path: nil, portal_url: nil)
+      hdrs = headers(request_id: request_id, prefix: prefix, portal_url: portal_url)
 
-      display = RequestId.format_request_id(request_id, prefix)
-      # INJECT-006: the server-supplied docsUrl when one has been learned,
-      # else the configured base URL. One batch of staleness after a
-      # docs-domain change is accepted.
-      log_host = docs_url.nil? || docs_url.empty? ? base_url : docs_url
-      log_url = "#{log_host}/logs/#{request_id}"
-      debug_cmd = "npx api debug #{display}"
+      # INJECT-001. The body object is 4xx/5xx only: a successful body is the
+      # caller's data, not ours to reshape. With no portal origin there is no
+      # URL to put in one either (INJECT-006).
+      return { headers: hdrs, debug: nil } if status < 400 || portal_url.nil? || portal_url.empty?
+
+      log_url = hdrs["x-log-url"]
+      debug_cmd = hdrs["x-debug"]
 
       # Per-request "dig-in" URL the calling agent (often an AI) can fetch for
       # concrete next steps. Deliberately LEGIBLE: it ends in `<slug>.md` so it
@@ -52,7 +70,7 @@ module Restless
       # can correlate the follow-up without any new tracking token.
       slug = recovery_slug(method, path)
       dig_in = "For the accepted parameters and next steps, " \
-               "fetch #{log_host}/p/#{request_id}/#{slug}.md"
+               "fetch #{portal_url}/p/#{request_id}/#{slug}.md"
       # INJECT-004: a cached recovery message precedes the dig-in line,
       # separated by a blank line.
       recovery_text =
@@ -63,10 +81,7 @@ module Restless
         end
 
       {
-        headers: {
-          "x-log-url" => log_url, # INJECT-002
-          "x-debug" => debug_cmd
-        },
+        headers: hdrs,
         debug: {
           "log" => log_url,
           "cli" => debug_cmd,

data/lib/restless/rack.rb

@@ -242,6 +242,18 @@ module Restless
                        options[:request_id_prefix], options[:has_api_key]
                      ))
 
+      # INJECT-002. The headers ship on every status; only the body work below
+      # is 4xx/5xx, and fingerprinting a success would be wasted.
+      if inject && status.to_i < 400
+        headers.merge!(safely({}) do
+          Injection.headers(
+            request_id: our_id,
+            prefix: options[:request_id_prefix],
+            portal_url: @engine.portal_url
+          )
+        end)
+      end
+
       if inject && status.to_i >= 400
         # INJECT-009: the fingerprint is computed against the customer's RAW
         # response, snapshotted before any injected header or body field.
@@ -257,18 +269,18 @@ module Restless
           Injection.build(
             status: status.to_i,
             request_id: our_id,
-            base_url: options[:base_url],
             prefix: options[:request_id_prefix],
             recovery: recovery,
             method: env["REQUEST_METHOD"],
             path: captured["routePattern"],
-            docs_url: @engine.docs_url
+            portal_url: @engine.portal_url
           )
         end
 
         if injection
           headers.merge!(injection[:headers]) # INJECT-002
-          rewritten = Injection.apply_body(body_text, headers["content-type"],
+          rewritten = injection[:debug] &&
+                      Injection.apply_body(body_text, headers["content-type"],
                                            injection[:debug]) # INJECT-003
           if rewritten && !rewritten.equal?(body_text) && rewritten != body_text
             body = [rewritten]

data/lib/restless/settings.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Restless
   # CONTRACT.md section 12. `.restless/settings.json` is created and owned by
-  # the `api` CLI (`npx api setup`); the SDK consumes exactly two fields of it
+  # the `restless` CLI (`npx restless init`); the SDK consumes exactly two fields of it
   # at runtime (CONFIG-015).
   module Settings
     class ConfigError < StandardError; end

data/lib/restless/version.rb

@@ -6,7 +6,7 @@ module Restless
   # META-001: the spec version an SDK implements must be recorded in a
   # machine-readable form alongside its conformance level.
 
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 
   # WIRE-016: distinct per implementation, so the ingest can attribute a
   # payload to a language.
@@ -17,7 +17,7 @@ module Restless
   # REDACT-010 requires full Unicode name folding
   # to require full Unicode lowercase. Keep this in step with
   # spec/VECTORS_VERSION.
-  SPEC_VERSION = "1.0.0"
+  SPEC_VERSION = "1.0.1"
 
   # CONTRACT.md 1.1: L1 is the pure functions, L2 adds batching, caches,
   # injection and the safety guarantees.

data/spec/VECTORS_VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

data/spec/vectors/debug-injection.json

@@ -0,0 +1,219 @@
+{
+  "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
+  "$contract": "spec/CONTRACT.md",
+  "specVersion": "1.0.1",
+  "cases": [
+    {
+      "id": "inject/2xx-headers-only",
+      "requirement": "INJECT-001",
+      "op": "debugInjection",
+      "input": {
+        "status": 200,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com",
+        "method": "GET",
+        "path": "/car/{id}"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": null
+      },
+      "note": "Headers on every status; the body object stays 4xx/5xx only."
+    },
+    {
+      "id": "inject/2xx-301",
+      "requirement": "INJECT-001",
+      "op": "debugInjection",
+      "input": {
+        "status": 301,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": null
+      }
+    },
+    {
+      "id": "inject/4xx-full",
+      "requirement": "INJECT-002",
+      "op": "debugInjection",
+      "input": {
+        "status": 404,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com",
+        "method": "GET",
+        "path": "/car/{id}"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": {
+          "log": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "cli": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "recovery": "For the accepted parameters and next steps, fetch https://acme.restlessdocs.com/p/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f/get-car-id.md"
+        }
+      },
+      "note": "Both URLs share the portal origin."
+    },
+    {
+      "id": "inject/5xx-full",
+      "requirement": "INJECT-002",
+      "op": "debugInjection",
+      "input": {
+        "status": 500,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com",
+        "method": "POST",
+        "path": "/orders"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": {
+          "log": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "cli": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "recovery": "For the accepted parameters and next steps, fetch https://acme.restlessdocs.com/p/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f/post-orders.md"
+        }
+      }
+    },
+    {
+      "id": "inject/no-portal-2xx",
+      "requirement": "INJECT-006",
+      "op": "debugInjection",
+      "input": {
+        "status": 200,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+      },
+      "expected": {
+        "headers": {
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": null
+      },
+      "note": "No portal origin: x-debug only, and never a URL on the ingest host."
+    },
+    {
+      "id": "inject/no-portal-4xx",
+      "requirement": "INJECT-006",
+      "op": "debugInjection",
+      "input": {
+        "status": 404,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "method": "GET",
+        "path": "/car/{id}"
+      },
+      "expected": {
+        "headers": {
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": null
+      },
+      "note": "No portal origin means no debug object at all, so no dig-in line."
+    },
+    {
+      "id": "inject/prefix",
+      "requirement": "INJECT-002",
+      "op": "debugInjection",
+      "input": {
+        "status": 404,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "prefix": "TST",
+        "portalUrl": "https://acme.restlessdocs.com"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug TST-9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": {
+          "log": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "cli": "npx api debug TST-9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "recovery": "For the accepted parameters and next steps, fetch https://acme.restlessdocs.com/p/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f/unknown.md"
+        }
+      },
+      "note": "x-log-url carries the RAW id; only the CLI hint is prefixed."
+    },
+    {
+      "id": "inject/authored-recovery",
+      "requirement": "INJECT-004",
+      "op": "debugInjection",
+      "input": {
+        "status": 402,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com",
+        "recovery": "Try another card.",
+        "method": "POST",
+        "path": "/charge"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": {
+          "log": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "cli": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "recovery": "Try another card.\n\nFor the accepted parameters and next steps, fetch https://acme.restlessdocs.com/p/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f/post-charge.md"
+        }
+      },
+      "note": "The authored hint precedes the dig-in line, separated by a blank line."
+    },
+    {
+      "id": "inject/unknown-slug",
+      "requirement": "INJECT-005",
+      "op": "debugInjection",
+      "input": {
+        "status": 404,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com",
+        "method": "GET"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": {
+          "log": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "cli": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "recovery": "For the accepted parameters and next steps, fetch https://acme.restlessdocs.com/p/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f/unknown.md"
+        }
+      }
+    },
+    {
+      "id": "inject/trailing-slash-origin",
+      "requirement": "WIRE-023",
+      "op": "debugInjection",
+      "input": {
+        "status": 404,
+        "requestId": "9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+        "portalUrl": "https://acme.restlessdocs.com",
+        "method": "GET",
+        "path": "/x"
+      },
+      "expected": {
+        "headers": {
+          "x-log-url": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "x-debug": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f"
+        },
+        "debug": {
+          "log": "https://acme.restlessdocs.com/logs/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "cli": "npx api debug 9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f",
+          "recovery": "For the accepted parameters and next steps, fetch https://acme.restlessdocs.com/p/9f18a0e2-1c3d-4b5a-8e7f-0a1b2c3d4e5f/get-x.md"
+        }
+      },
+      "note": "The origin is stripped of trailing slashes on ingest (WIRE-023), so the SDK appends directly."
+    }
+  ]
+}

data/spec/vectors/fingerprint.json

@@ -1,7 +1,7 @@
 {
   "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
   "$contract": "spec/CONTRACT.md",
-  "specVersion": "1.0.0",
+  "specVersion": "1.0.1",
   "cases": [
     {
       "id": "fp/404-parameterized",

data/spec/vectors/har.json

@@ -1,7 +1,7 @@
 {
   "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
   "$contract": "spec/CONTRACT.md",
-  "specVersion": "1.0.0",
+  "specVersion": "1.0.1",
   "cases": [
     {
       "id": "har/basic",

data/spec/vectors/mask.json

@@ -1,7 +1,7 @@
 {
   "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
   "$contract": "spec/CONTRACT.md",
-  "specVersion": "1.0.0",
+  "specVersion": "1.0.1",
   "cases": [
     {
       "id": "mask/ascii",

data/spec/vectors/recovery-slug.json

@@ -1,7 +1,7 @@
 {
   "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
   "$contract": "spec/CONTRACT.md",
-  "specVersion": "1.0.0",
+  "specVersion": "1.0.1",
   "cases": [
     {
       "id": "slug/basic",

data/spec/vectors/redact.json

@@ -1,7 +1,7 @@
 {
   "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
   "$contract": "spec/CONTRACT.md",
-  "specVersion": "1.0.0",
+  "specVersion": "1.0.1",
   "cases": [
     {
       "id": "redactValue/long",

data/spec/vectors/request-id.json

@@ -1,7 +1,7 @@
 {
   "$generated": "GENERATED FILE - do not edit by hand. Inputs live in spec/cases.ts; run `npm run spec:vectors` to regenerate.",
   "$contract": "spec/CONTRACT.md",
-  "specVersion": "1.0.0",
+  "specVersion": "1.0.1",
   "cases": [
     {
       "id": "reqid/format-with-prefix",

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: restless-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Restless
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
   Rack middleware that captures API traffic, redacts secrets before anything
@@ -16,14 +15,14 @@ description: |
   recovered from, and uploads the result to Restless. Works with Rails,
   Sinatra, Hanami, Grape, Roda and anything else that speaks Rack.
 
-  Implements version 1.0.0 of the Restless SDK Contract at
+  Implements version 1.0.1 of the Restless SDK Contract at
   level L2.
-email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - CONFORMANCE.md
+- LICENSE
 - README.md
 - exe/restless-conformance
 - install.md
@@ -46,6 +45,7 @@ files:
 - lib/restless/uploader.rb
 - lib/restless/version.rb
 - spec/VECTORS_VERSION
+- spec/vectors/debug-injection.json
 - spec/vectors/fingerprint.json
 - spec/vectors/har.json
 - spec/vectors/mask.json
@@ -54,13 +54,12 @@ files:
 - spec/vectors/request-id.json
 homepage: https://restless.ai
 licenses:
-- ISC
+- MIT
 metadata:
   source_code_uri: https://github.com/restlesshq/ruby
   bug_tracker_uri: https://github.com/restlesshq/ruby/issues
-  restless_spec_version: 1.0.0
+  restless_spec_version: 1.0.1
   restless_conformance_level: L2
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -75,8 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Capture your API traffic and send it to Restless.
 test_files: []