@volter/twin-tunnel 1.0.0 → 1.0.1

package/dist/journeys/customer-life.outline.md

@@ -0,0 +1,34 @@
+# A shared Harness demo
+
+Ada runs Harness on her laptop. Her relay account's token grants her connector
+the right to register her demo tunnel. Bob first visits its public URL without a
+relay credential: Ada deliberately shares an unauthenticated remote-access demo.
+Later Bob creates his own account, whose token can register his own tunnel but
+cannot take Ada's reserved name. The story takes place in one sitting; it uses
+neither metered quotas nor a credential with a limited grant.
+
+1. Ada signs up and gives Harness the account token she was shown. Harness
+   connects its named tunnel and shares the visitor URL returned by the relay.
+2. Bob mistypes the tunnel name from Ada's invitation and cannot reach a
+   connector there. He follows the actual shared URL to correct the mistake. Harness receives the page request and answers it with
+   the page from Ada's local server. Bob's remote viewer asks permission to send its command headers and runs a demo command;
+   Harness streams progress and completion, and Bob receives the complete output.
+3. While setting up a second Harness connector for the demo, Ada first uses a
+   separate diagnostic client speaking the relay's documented control protocol.
+   It registers the existing name without requesting replacement and is refused.
+   She then starts the actual Harness connector, whose SDK requests replacement
+   automatically; the previous connector closes, the URL stays stable, and Bob
+   checks that the restarted local server answers.
+4. Bob creates his own relay account. He copied Ada's tunnel name and discovers
+   that his account cannot claim it. He corrects the name but pastes an incomplete
+   token. After that is rejected, he reconnects using the token actually returned
+   by his account and receives his own demo URL.
+5. Bob requests a final command just as Ada closes the connector at the end of
+   the demonstration. The pending command reports the disconnect. Bob uses the local relay's direct
+   addressing diagnostic to check his separate connector still answers, then
+   closes his own connector.
+
+The account act uses the World account door. Registration and reconnection use
+the control socket. A visitor's request is started while the local client answers
+its control frame, then its completed HTTP response is checked. Both buffered
+and streamed replies therefore occur in the executable story.

package/dist/journeys/customer-life.outline.verdict.json

@@ -0,0 +1,42 @@
+{
+  "sha256": "fd151bd1155b27b8cf5a0503e5dd0ce08fdcc442264417ce2e95fa2c49c783de",
+  "plausible": true,
+  "bar": "829132787d94a2d4",
+  "judge": {
+    "name": "Contributor 44",
+    "agent": "Contributor 20"
+  },
+  "authors": [
+    "Contributor 43",
+    "Contributor 1"
+  ],
+  "rounds": 1,
+  "rulings": [
+    {
+      "id": "R1",
+      "acts": [
+        3
+      ],
+      "required": "Identify separate protocol diagnostic and SDK automatic replacement"
+    }
+  ],
+  "doubts": [
+    "See independent exhaustive report in the retained independent review"
+  ],
+  "applied": {
+    "from": "e68d21e7aa7caceefff49ebbd2b1b7d7be2130188cc92b3e4fe63083ff0a0d83",
+    "wasPlausible": false,
+    "steps": [
+      "3"
+    ],
+    "rulings": [
+      {
+        "id": "R1",
+        "acts": [
+          3
+        ],
+        "required": "Identify separate protocol diagnostic and SDK automatic replacement"
+      }
+    ]
+  }
+}

package/dist/journeys/customer-life.verdict.json

@@ -0,0 +1,51 @@
+{
+  "sha256": "02196737197b84f01e56a4d431cfc09afb99a180ec2f9df96ce7bdf6fc08fbe8",
+  "plausible": true,
+  "bar": "829132787d94a2d4",
+  "judge": {
+    "name": "Contributor 44",
+    "agent": "Contributor 20"
+  },
+  "authors": [
+    "Contributor 43",
+    "Contributor 1"
+  ],
+  "rounds": 1,
+  "rulings": [
+    {
+      "id": "R1",
+      "steps": [
+        15,
+        16,
+        17,
+        18
+      ],
+      "required": "Identify diagnostic and actual SDK actors; judge report uses human 1-based steps 16–19"
+    }
+  ],
+  "doubts": [
+    "See independent exhaustive report in the retained independent review"
+  ],
+  "applied": {
+    "from": "f9de0bd56dbfc8921cfc34a03df6c7382d6859c71b5fc06f84ad47800206c506",
+    "wasPlausible": false,
+    "steps": [
+      "15",
+      "16",
+      "17",
+      "18"
+    ],
+    "rulings": [
+      {
+        "id": "R1",
+        "steps": [
+          15,
+          16,
+          17,
+          18
+        ],
+        "required": "Identify diagnostic and actual SDK actors; judge report uses human 1-based steps 16–19"
+      }
+    ]
+  }
+}

package/dist/journeys/decisions.json

@@ -0,0 +1,23 @@
+{
+  "about": "tunnel's decision table (the P3 procedure). The relay is a protocol, not an API: a client's control socket (the manifest's socket `control`, semantics/sockets.ts) and the public requests the relay sends down it (the pack's front, semantics/around.ts, over the kernel's request-answered-by-a-session mechanism). The spec's one operation, the apex's status, is called by nothing and answers the gap. An account and its token are the World's door.",
+  "decisions": [
+    {
+      "operation": "door:accounts",
+      "demand": "Volter Harness's TUNNEL_SECRET",
+      "mechanism": "door",
+      "why": "an account and its token are made on the relay's signup, not through its protocol"
+    },
+    {
+      "operation": "socket:control",
+      "demand": "Volter Harness createTunnel",
+      "mechanism": "handler",
+      "why": "the declared socket engine speaks the vendor control protocol"
+    },
+    {
+      "operation": "front:public-request",
+      "demand": "a visitor opens Harness remote-access URL",
+      "mechanism": "handler",
+      "why": "around sends the request to the registered client and awaits its response frames"
+    }
+  ]
+}

package/dist/journeys/demand.json

@@ -0,0 +1,24 @@
+{
+ "measured": "the demand scan (twin-world scripts/demand-scan.ts, the products volter.ai names) finds the tunnel in Volter Harness (volter-ai/supercode @ 62620578c014c4c0b1d4c34e1268e4112c9dd331): its remote access, given a stable relay (SUPERCODE_TUNNEL_SERVER_URL or TUNNEL_SERVER_URL), opens a tunnel with @volter/tunnel's client for a loopback port, with TUNNEL_SECRET when set, a stable tunnel id and authRequired false, and shares the tunnel URL's origin. The client (volter-ai/volter-tunnel @ c14b6e3, client/tunnel-client.ts) opens the control WebSocket at <host>/ws?id=<tunnelId>, registers, and answers each request frame from the local server; the public side is whoever opens the shared URL. The relay's own /api/status is called by nothing: it answers the gap.",
+ "applications": [
+  {
+   "name": "volter-ai/supercode (Volter Harness)",
+   "commit": "62620578c014c4c0b1d4c34e1268e4112c9dd331",
+   "client": "@volter/tunnel's createTunnel (the control WebSocket), and whoever opens the tunnel's URL; configuration read at sdk/remote-access/index.mjs:324,343",
+   "backend": [
+    {
+     "call": "the control WebSocket at <relay>/ws?id=<tunnelId>: register (tunnelId, secret, authRequired false), then each request frame answered with the local server's response",
+     "operation": "socket:control",
+     "evidence": "sdk/remote-access/index.mjs:348"
+    }
+   ],
+   "frontend": [
+    {
+     "call": "a person opens the shared remote-access URL: every request forwarded to the Harness's local server through the control socket",
+     "operation": "front:public-request",
+     "evidence": "sdk/remote-access/index.mjs:362"
+    }
+   ]
+  }
+ ]
+}

package/dist/journeys/score.json

@@ -0,0 +1,134 @@
+{
+  "vendor": "tunnel",
+  "life": {
+    "steps": 40,
+    "verdict": "plausible",
+    "judge": "Contributor 20",
+    "authors": [
+      "Contributor 43",
+      "Contributor 1"
+    ]
+  },
+  "failures": [],
+  "flags": [],
+  "coverage": {
+    "vendor": "tunnel",
+    "missing": 9,
+    "stale": [],
+    "code": {
+      "lines": 255,
+      "run": 242,
+      "recorded": 4,
+      "missing": 9
+    },
+    "state": {
+      "declared": 0,
+      "reached": 0,
+      "recorded": 0,
+      "missing": [],
+      "undeclared": []
+    },
+    "files": [
+      {
+        "file": "semantics/doors.ts",
+        "lines": {
+          "found": 13,
+          "hit": 13
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/sockets.ts",
+        "lines": {
+          "found": 82,
+          "hit": 74
+        },
+        "missing": [
+          {
+            "from": 114,
+            "to": 118,
+            "fn": "expireStream"
+          },
+          {
+            "from": 123,
+            "to": 125,
+            "fn": "cancelStream"
+          }
+        ]
+      },
+      {
+        "file": "semantics/shared.ts",
+        "lines": {
+          "found": 46,
+          "hit": 46
+        },
+        "missing": []
+      },
+      {
+        "file": "semantics/around.ts",
+        "lines": {
+          "found": 40,
+          "hit": 39
+        },
+        "missing": [
+          {
+            "from": 66,
+            "to": 66,
+            "fn": "timeout"
+          }
+        ]
+      },
+      {
+        "file": "semantics/index.ts",
+        "lines": {
+          "found": 2,
+          "hit": 2
+        },
+        "missing": []
+      },
+      {
+        "file": "manifest.ts",
+        "lines": {
+          "found": 43,
+          "hit": 43
+        },
+        "missing": []
+      },
+      {
+        "file": "index.ts",
+        "lines": {
+          "found": 7,
+          "hit": 7
+        },
+        "missing": []
+      },
+      {
+        "file": "server.ts",
+        "lines": {
+          "found": 6,
+          "hit": 2
+        },
+        "missing": []
+      },
+      {
+        "file": "fetch.ts",
+        "lines": {
+          "found": 16,
+          "hit": 16
+        },
+        "missing": []
+      }
+    ]
+  },
+  "examples": {
+    "done": true,
+    "replayed": true,
+    "verdict": "plausible",
+    "failures": [],
+    "line": "examples: 0 published, 0 of patch-removed operations, 0 of operations the twin does not serve, 0 replayed, 0 recorded; 0 failing   done: yes"
+  },
+  "breadth": {
+    "operations": 1,
+    "gap": 1
+  }
+}

package/dist/journeys/unreachable.json

@@ -0,0 +1,12 @@
+{
+  "code": [
+    {
+      "file": "server.ts",
+      "declarations": [
+        "createTunnelTwinServer"
+      ],
+      "world": "host-process",
+      "why": "The in-memory life invokes the pack fetch, not its HTTP listener factory. Standalone and served-life conformance exercise this factory separately."
+    }
+  ]
+}

package/dist/journeys/vendor-examples.json

@@ -0,0 +1,7 @@
+{
+  "vendor": "tunnel",
+  "author": "Contributor 71",
+  "host": "voltertest.xyz",
+  "about": "No request/response examples exist for a served HTTP spec operation: getStatus is unmodeled. Upstream README createTunnel is a client program; its control protocol and visitor round trip are walked by customer-life.json. See spec/SOURCE.md for the pages read.",
+  "steps": []
+}

package/dist/journeys/vendor-examples.verdict.json

@@ -0,0 +1,18 @@
+{
+  "sha256": "d92b8e9a39a133ab6c07149d3f75795ea5c14ecba53b0bb60e2fa06d59419ace",
+  "plausible": true,
+  "bar": "829132787d94a2d4",
+  "judge": {
+    "name": "Contributor 44",
+    "agent": "Contributor 20"
+  },
+  "authors": [
+    "Contributor 43",
+    "Contributor 1"
+  ],
+  "rounds": 1,
+  "rulings": [],
+  "doubts": [
+    "See independent exhaustive report in the retained independent review"
+  ]
+}

package/dist/spec/SOURCE.md

@@ -1,14 +1,30 @@
-# volter-tunnel relay spec — provenance
-
-- **Why this document:** the relay publishes no OpenAPI document. Its contract is volter-ai/volter-tunnel at
-  `c14b6e3` (2026-09-28): `packages/core/src/protocol.ts` (the control channel's frames, "the single source of truth
-  for the messages exchanged over the control WebSocket between a client and the relay") and the Cloudflare relay,
-  `server-cf/src/worker.ts` (routing: the control channel at `/ws?id=<tunnelId>`; a tunnel at `<tunnelId>.<domain>`,
-  or `?__tunnel=<id>` on a direct host such as localhost; `/api/status` at the apex) and `server-cf/src/tunnel-do.ts`
-  (registration: `registered` with `url: https://<tunnelId>.<domain>`, a rejected credential `{type:"error"}` then
-  close 4003, a replaced client closed 4001 "Replaced by new client"; a public request: 502 "Tunnel not connected",
-  504 "Tunnel timeout" after 30 s, 413 over 750000 bytes of body; the reply frames `response`, `response-start`,
-  `response-chunk`, `response-end`). The domain is `voltertest.xyz` (`server-cf/wrangler.jsonc`, `TUNNEL_DOMAIN`).
-- **Corrections:** none.
-- **Read by:** the twin orchestrator, 2026-09-30.
-- **Vendored bytes (sha256):** `openapi.json` `b4fcdc3d599026bef687c946cea3c8837c63ff982e5d899df1425e585832aebd`.
+# Relay contract provenance
+
+The relay publishes no OpenAPI document. `openapi.json` describes its HTTP status
+operation and carries the verbatim upstream reference sources under `x-reference`.
+These sources were read with GitHub's contents API at
+`c14b6e36722b20cbb3ee7245c7f555b5c12b376e`, on 2026-10-01.
+
+Upstream: https://github.com/volter-ai/volter-tunnel/tree/c14b6e36722b20cbb3ee7245c7f555b5c12b376e
+
+- `packages/core/src/protocol.ts`: control-channel frames.
+- `server-cf/src/worker.ts`: control and visitor routing, reserved hosts and status.
+- `server-cf/src/tunnel-do.ts`: registration, refusals, forwarding, buffering and streaming.
+- `server-cf/src/credits.ts`: account-slug validation.
+- `server-cf/src/auth.ts`: visitor cookie and query sanitization.
+- `server-cf/wrangler.jsonc`: relay domain.
+- `README.md` and `client/tunnel-client.ts`: the published client usage and its relay connection.
+
+Version: relay protocol 2. Corrections: none. The HTTP document was written
+from these sources; the reference strings preserve the upstream bytes, without
+changing the vendor's contract to match the twin.
+
+Vendored bytes (sha256): `openapi.json` `e9dc4d9a6396473c3f1e1d14b5fbfb4567e0fbe23fb16e2f47fc3bf3b9b5ea73`.
+
+The served contract is Harness's public, unauthenticated HTTP relay. The management
+API, visitor WebSocket bridging, quotas, JWT/basic-auth gates, inspector, usage
+snapshots and reservation expiry are outside the demand represented here.
+No HTTP API operation is served; the status operation is an explicit gap.
+The vendor publishes no request/answer examples for a served HTTP operation:
+the client sample is a program, not an HTTP request/answer example the replay tool
+can route. The customer life exercises the control frames and visitor responses.