pinesandbox 0.3.18 → 0.3.19

data/lib/pinesandbox/adapters/coordinator_adapter.rb

@@ -1,6 +1,7 @@
 require "faraday"
 require "json"
 require "securerandom"
+require "tempfile"
 require "uri"
 require_relative "../clock"
 require_relative "../errors"
@@ -14,8 +15,9 @@ require_relative "../response_handler"
 module PineSandbox
   module Adapters
     # @api private — the SDK's HTTP client for the Computer API, reached at the
-    # runtime's own host `https://<runtime_id>.computer.<zone>`. The subdomain
-    # selects the runtime and the PATH selects the role (the API at root);
+    # Computer sandbox's own host `https://<sandbox_id>.computer.<zone>`. The
+    # subdomain selects the Computer sandbox and the PATH selects the role (the
+    # API at root);
     # the host is port-less and header-less — no routing header.
     #
     # The bearer goes in `Authorization: Bearer`. The Computer gates every
@@ -36,24 +38,28 @@ module PineSandbox
       DEFAULT_OPEN_TIMEOUT = 5
       # A non-2xx stream answer keeps this much of its body for the error.
       STREAM_ERROR_BODY_CAP = 64 * 1024
-
-      # The runtime is reached at its own host `https://<runtime_id>.computer.<zone>`
-      # (derived from `zone`), port-less and header-less: the subdomain selects the
-      # runtime and the PATH selects the role. `zone` is a PineSandbox::Zone.
-      # `host` is the per-runtime data-plane host `<runtime_id>.computer.<zone>`
+      # Chunk size for passing on a body that was spooled to a temp file.
+      SPOOL_READ_SIZE = 64 * 1024
+      # An event stream silent this long (three missed keepalives) is reopened.
+      STREAM_IDLE_TIMEOUT = 60
+
+      # The Computer sandbox is reached at its own host
+      # `https://<sandbox_id>.computer.<zone>` (derived from `zone`), port-less and
+      # header-less: the subdomain selects the Computer sandbox and the PATH
+      # selects the role. `zone` is a PineSandbox::Zone.
+      # `host` is the Computer sandbox's data-plane host `<sandbox_id>.computer.<zone>`
       # (scheme-less). `scheme` is http for a .localhost zone (local-dev loop),
       # https otherwise. `clock` paces retries and reconnects.
-      attr_reader :runtime_id, :host, :scheme, :clock
+      attr_reader :sandbox_id, :host, :scheme, :clock
 
       # discovery_token is the Computer token that reads the capability
       # manifest when a request's own token, such as a session's, cannot. An
       # adopted binding passes it; #bind records the one it issues.
-      # `sandbox_id:` is the deprecated spelling of `runtime_id:`.
-      def initialize(zone:, runtime_id: nil, sandbox_id: nil, discovery_token: nil, clock: PineSandbox::SYSTEM_CLOCK)
-        @runtime_id = runtime_id || sandbox_id
-        raise ArgumentError, "runtime_id required" if @runtime_id.to_s.empty?
+      def initialize(zone:, sandbox_id: nil, discovery_token: nil, clock: PineSandbox::SYSTEM_CLOCK)
+        @sandbox_id = sandbox_id
+        raise ArgumentError, "sandbox_id required" if @sandbox_id.to_s.empty?
 
-        @host = zone.data_host(@runtime_id)
+        @host = zone.data_host(@sandbox_id)
         @scheme = zone.http_scheme # http for a .localhost zone (local-dev loop), https otherwise
         @discovery_token = discovery_token
         @clock = clock
@@ -63,13 +69,7 @@ module PineSandbox
         @zone = zone
       end
 
-      # Deprecated: use #runtime_id.
-      def sandbox_id
-        PineSandbox.deprecated_name("CoordinatorAdapter#sandbox_id", "#runtime_id")
-        @runtime_id
-      end
-
-      # The full data-plane origin `<scheme>://<runtime_id>.computer.<zone>` — the
+      # The full data-plane origin `<scheme>://<sandbox_id>.computer.<zone>` — the
       # DelegatedConnection's `computer_host` is a complete URI per the Computer API,
       # so the web SDK derives the desktop's ws/wss scheme from it (no guessing).
       def base_url
@@ -77,7 +77,7 @@ module PineSandbox
       end
 
       # Bind handshake. Posts the portal-issued bind_token JWS to
-      # /v1/coord/bind and returns the runtime's `ct_` from the response.
+      # /v1/coord/bind and returns the Computer token (`ct_`) from the response.
       #
       # Auth model: bind_token's Ed25519 signature IS the auth — no
       # bearer token is presented here (the bind endpoint refuses
@@ -85,7 +85,7 @@ module PineSandbox
       #
       # @param bind_token [String] compact JWS Ed25519 token minted by the
       #   portal attach-credentials endpoint (AttachCredentialsSource).
-      # @param pod_uid [String] echoed runtime identity (must match the token).
+      # @param pod_uid [String] echoed Computer sandbox identity (must match the token).
       # @param coord_boot_id [String] echoed process boot id.
       # @param ciphertext [String] base64url HPKE wire (enc || aead_ct).
       # @return [Hash] { "computer_token" => ct_, "epoch" => Integer }.
@@ -109,7 +109,7 @@ module PineSandbox
       end
 
       # Fetches the Computer's per-process ephemeral HPKE public key and
-      # runtime identity. Public route — no token. The SDK seals the bind
+      # Computer sandbox identity. Public route — no token. The SDK seals the bind
       # payload to this key and echoes pod_uid/coord_boot_id back on bind.
       #
       # @return [Hash] { "pod_uid", "coord_boot_id", "ephem_pub_x25519"
@@ -192,22 +192,6 @@ module PineSandbox
         true
       end
 
-      # Orphan downloads: browser downloads no session owns (ct_ only).
-      def list_orphan_downloads(token:)
-        get("downloads/orphans", token: token).body
-      end
-
-      def claim_orphan_download(token:, guid:, session_name:, filename: nil)
-        body = { session_name: session_name }
-        body[:filename] = filename if filename
-        post("downloads/orphans/#{escape(guid)}/claim", token: token, json: body).body
-      end
-
-      def discard_orphan_download(token:, guid:)
-        delete("downloads/orphans/#{escape(guid)}", token: token)
-        true
-      end
-
       def create_session(token:, name: nil, label: nil, browser: false, blind: false)
         # Omit :name when blank so the coordinator mints a friendly name; only
         # send :label when the caller set one. Name stays first so the on-wire
@@ -300,7 +284,7 @@ module PineSandbox
       # ----- Artifacts: list / read / zip / upload -----
 
       # GET /v1/sessions/{name}/artifacts?turn_id= — the session's artifacts
-      # (uploads + claimed downloads + every completed turn's durably-captured
+      # (uploads + browser downloads + every completed turn's durably-captured
       # agent outputs).
       def list_artifacts(token:, name:, turn_id: nil)
         route = "v1/sessions/#{escape(name)}/artifacts"
@@ -525,7 +509,7 @@ module PineSandbox
                   event.data["exitCode"] || event.data[:exitCode]
             exit_code = raw unless raw.nil?
           end
-          block.call(event) if block
+          pass_to_block(block, event) if block
         end
         # Clamp the HTTP timeout above timeout_ms so the client waits for
         # the server's own timeout to fire an execution_complete event
@@ -541,7 +525,13 @@ module PineSandbox
             req.headers["Accept"] = "text/event-stream"
             req.body = body.to_json
             req.options.on_data = proc do |chunk, _received, env|
-              if env.nil? || env.status.to_i.between?(200, 299)
+              if env.nil?
+                # faraday-net_http before 3.0 passes no env, so the status is
+                # known only at the end: parse the chunk and keep it in case
+                # the answer is an error.
+                parser.parse(chunk)
+                keep_error_body(error_body, chunk)
+              elsif env.status.to_i.between?(200, 299)
                 parser.parse(chunk)
               else
                 keep_error_body(error_body, chunk)
@@ -568,6 +558,8 @@ module PineSandbox
         end
         ExecResult.new(stdout: stdout, stderr: stderr, exit_code: exit_code,
                        error_message: error_msg)
+      rescue BlockError => e
+        raise e.error
       end
 
       # Minimal struct surfaced by #exec. Matches the shape tests expect:
@@ -701,7 +693,7 @@ module PineSandbox
       end
 
       # Explicit qualification for a binding. No cache, downgrade or mutation.
-      # A missing discovery route is an old runtime; the gateway's typed
+      # A missing discovery route is an old Computer sandbox; the gateway's typed
       # sandbox-not-found response remains a lifecycle failure.
       def require_agent_protocol!(token:)
         manifest = capabilities(token: token)
@@ -709,7 +701,7 @@ module PineSandbox
 
         self
       rescue NotFoundError => e
-        raise if e.is_a?(RuntimeGoneError)
+        raise if e.is_a?(SandboxGoneError)
 
         raise AgentProtocolUnsupported
       end
@@ -899,7 +891,13 @@ module PineSandbox
           req.headers["Accept"] = "text/event-stream"
           req.headers["Last-Event-ID"] = last_event_id.to_s unless last_event_id.to_s.empty?
           req.options.on_data = proc do |chunk, _bytes, env|
-            if env.nil? || env.status.to_i.between?(200, 299)
+            if env.nil?
+              # faraday-net_http before 3.0 passes no env, so the status is
+              # known only at the end: parse the chunk and keep it in case the
+              # answer is an error.
+              parser.feed(chunk) { |frame| yield frame }
+              keep_error_body(error_body, chunk)
+            elsif env.status.to_i.between?(200, 299)
               parser.feed(chunk) { |frame| yield frame }
             else
               keep_error_body(error_body, chunk)
@@ -927,6 +925,16 @@ module PineSandbox
       end
       private_constant :BlockError
 
+      # Runs the caller's block on one piece of a streamed answer from inside
+      # Faraday's read loop, which would turn an IOError or EPIPE from the
+      # block into a dropped connection. The streaming method raises the
+      # block's error again as it was.
+      def pass_to_block(block, value)
+        block.call(value)
+      rescue StandardError => e
+        raise BlockError.new(e)
+      end
+
       # The resuming event-stream engine. Each connection opens from the last
       # event id seen; frames advance the cursor before any decode, so a
       # skipped frame is never replayed. A dropped connection (a transport
@@ -1008,24 +1016,45 @@ module PineSandbox
       # raises, before any chunk. A transport fault after the first chunk
       # raises too, so the caller knows the body is incomplete. The default
       # connection's read timeout bounds each wait for the next chunk.
-      def stream_bytes(path, token:, accept:)
+      def stream_bytes(path, token:, accept:, &block)
         error_body = +""
+        # faraday-net_http before 3.0 passes no env and learns the status only
+        # after the body, so a chunk can't be told from an error body until the
+        # response ends. Those chunks go to a temp file, not memory, and are
+        # passed on once the status is known.
+        spool = nil
         with_transport_norm("GET", path) do
           response = connection.get(route_path(path)) do |req|
             apply_token(req, token)
             req.headers["Accept"] = accept
             req.options.on_data = proc do |chunk, _received, env|
-              if env.status.to_i.between?(200, 299)
-                yield chunk.b unless chunk.empty?
+              if env.nil?
+                (spool ||= Tempfile.new("pinesandbox-read", binmode: true)).write(chunk)
+              elsif env.status.to_i.between?(200, 299)
+                pass_to_block(block, chunk.b) unless chunk.empty?
               else
                 keep_error_body(error_body, chunk)
               end
             end
           end
+          if spool
+            spool.rewind
+            if response.success?
+              while (chunk = spool.read(SPOOL_READ_SIZE))
+                yield chunk
+              end
+            else
+              keep_error_body(error_body, spool.read(STREAM_ERROR_BODY_CAP).to_s)
+            end
+          end
           response.env.body = error_body if !response.success? && response.body.to_s.empty?
           ensure_success!(response, token: token) unless response.success?
         end
         nil
+      rescue BlockError => e
+        raise e.error
+      ensure
+        spool&.close!
       end
 
       def get(path, token:, accept: "application/json", headers: nil)
@@ -1105,7 +1134,7 @@ module PineSandbox
       end
 
       def normalize_transport_fault(error, method, path)
-        suffix = context_suffix(@runtime_id, op_from_route(method, path), nil)
+        suffix = context_suffix(@sandbox_id, op_from_route(method, path), nil)
         if error.is_a?(Faraday::TimeoutError)
           PineSandbox::TimeoutError.new("Computer request timed out: #{error.message}#{suffix}")
         else
@@ -1123,7 +1152,7 @@ module PineSandbox
 
       # The coord route path on the gateway host. The gateway routes by subdomain
       # and selects the role by PATH, so the path is just the coord route — no
-      # proxy prefix, no runtime id, no port.
+      # proxy prefix, no sandbox id, no port.
       def route_path(suffix)
         "/#{suffix}"
       end
@@ -1151,12 +1180,12 @@ module PineSandbox
       def classify_failure!(response, token)
         check_success!(response)
       rescue NotFoundError => original
-        raise if original.is_a?(RuntimeGoneError) || !original.problem_type.to_s.empty?
+        raise if original.is_a?(SandboxGoneError) || !original.problem_type.to_s.empty?
 
-        # The session list is served by every live runtime, so an untyped 404
+        # The session list is served by every live Computer sandbox, so an untyped 404
         # there means the gateway no longer routes to it.
         operation = Operations.match(:computer, response.env.method.to_s.upcase, response.env.url.path)
-        raise RuntimeGoneError.new(original), cause: original if operation&.id == "listSessions"
+        raise SandboxGoneError.new(original), cause: original if operation&.id == "listSessions"
 
         # Healthy V2 calls need no discovery round trip. Qualify only an
         # ambiguous 404, without retrying the original operation.
@@ -1185,7 +1214,7 @@ module PineSandbox
         # edge / the ingress), fall back to the older shape so
         # existing callers that rescue ApiError / UnauthorizedError /
         # NotFoundError keep working unchanged.
-        # The RESOURCE spine for every error this adapter raises: WHICH Computer (@runtime_id,
+        # The RESOURCE spine for every error this adapter raises: WHICH Computer (@sandbox_id,
         # held by the adapter) and WHICH operation ("<METHOD> <path>", off the Faraday env). We
         # attach it to EVERY raised path so an integrator's generic handler sees the resource +
         # op with no extra plumbing. request_id is the secondary precision handle.
@@ -1200,9 +1229,9 @@ module PineSandbox
           begin
             raise_for_status!(response)
           rescue PineSandbox::ApiError => e
-            e.attach_context!(runtime_id: @runtime_id, op: op)
+            e.attach_context!(sandbox_id: @sandbox_id, op: op)
             if e.problem_type == "/errors/sandbox-not-found"
-              raise PineSandbox::RuntimeGoneError.new(e), cause: e
+              raise PineSandbox::SandboxGoneError.new(e), cause: e
             end
             raise
           end
@@ -1222,7 +1251,7 @@ module PineSandbox
         if response.status == 408 || response.status == 504
           message = parse_legacy_error_message(response.body)
           timeout = PineSandbox::TimeoutError.new(
-            "Computer request failed: status=#{response.status} message=#{message}#{context_suffix(@runtime_id, op, rid)}"
+            "Computer request failed: status=#{response.status} message=#{message}#{context_suffix(@sandbox_id, op, rid)}"
           )
           timeout.retry_after = retry_after_seconds(response)
           raise timeout
@@ -1240,7 +1269,7 @@ module PineSandbox
           else PineSandbox::ApiError
           end
         ext = {}
-        ext["sandbox_id"] = @runtime_id if @runtime_id && !@runtime_id.to_s.empty?
+        ext["sandbox_id"] = @sandbox_id if @sandbox_id && !@sandbox_id.to_s.empty?
         ext["op"] = op if op && !op.to_s.empty?
         ext["request_id"] = rid if rid
         raise klass.new(
@@ -1274,11 +1303,11 @@ module PineSandbox
       end
 
       # Resource-first troubleshooting suffix for the message-only error paths (TimeoutError
-      # has no problem_extensions): runtime (WHICH Computer runtime) → op (WHICH operation) →
+      # has no problem_extensions): sandbox (WHICH Computer sandbox) → op (WHICH operation) →
       # request_id. Each part only when present; "" when all absent.
-      def context_suffix(runtime_id, op, rid)
+      def context_suffix(sandbox_id, op, rid)
         parts = []
-        parts << "runtime=#{runtime_id}" if runtime_id && !runtime_id.to_s.empty?
+        parts << "sandbox=#{sandbox_id}" if sandbox_id && !sandbox_id.to_s.empty?
         parts << "op=#{op}" if op && !op.to_s.empty?
         parts << "request_id=#{rid}" if rid && !rid.to_s.empty?
         parts.empty? ? "" : " (#{parts.join(', ')})"
@@ -1297,7 +1326,7 @@ module PineSandbox
       end
 
       # Faraday connection to the Computer's gateway host. The base URL sets the
-      # Host (and TLS SNI) to `<runtime_id>.computer.<zone>` — covered by the
+      # Host (and TLS SNI) to `<sandbox_id>.computer.<zone>` — covered by the
       # gateway wildcard cert `*.computer.<zone>`. Port-less and header-less: the
       # gateway routes the subdomain to the pod and the PATH selects the role; no
       # API key (coord gates every route on the bearer).
@@ -1310,18 +1339,14 @@ module PineSandbox
         end
       end
 
-      # Long-lived stream connection — disables the read timeout. The default
-      # `connection` above ships a 30s `options.timeout`; for SSE that's a
-      # papercut (a model-thinking turn or sparse control-event stream
-      # legitimately exceeds 30s of silence). Coord ships periodic `: ka`
-      # keepalive comments (every 20s) which reset Net::HTTP's read timer,
-      # so even with the default this rarely fires in practice — but the
-      # principled fix is to make the streaming socket actually long-lived.
+      # Long-lived stream connection. Its read timeout is an idle watchdog: coord
+      # sends a `: ka` keepalive comment every 20s, and each read resets the
+      # timer, so a quiet but healthy stream never trips it. A connection that
+      # sends nothing for STREAM_IDLE_TIMEOUT is half-open; the timeout raises
+      # Faraday::TimeoutError and follow_events reconnects from the cursor.
       #
-      # Faraday 2.x trap: `req.options.timeout = nil` does NOT mean "no
-      # timeout" on the Net::HTTP adapter. faraday-net_http 3.x only sets
-      # `http.read_timeout` when the option is truthy; nil falls through to
-      # Ruby's 60s default. The fix is to set it explicitly via the adapter
+      # Faraday 2.x trap: `req.options.timeout` is not honored the way it reads
+      # on the Net::HTTP adapter, so the read timeout is set in the adapter
       # block, which the adapter calls AFTER applying request_timeout.
       def streaming_connection
         @streaming_connection ||= @zone.faraday(@host) do |conn|
@@ -1329,7 +1354,7 @@ module PineSandbox
           conn.options.open_timeout = DEFAULT_OPEN_TIMEOUT
           # DELIBERATELY no conn.options.timeout — adapter block is authoritative.
           conn.adapter Faraday.default_adapter do |http|
-            http.read_timeout = nil
+            http.read_timeout = STREAM_IDLE_TIMEOUT
           end
         end
       end

data/lib/pinesandbox/agent_events.rb

@@ -165,11 +165,11 @@ module PineSandbox
     end
 
     # How the turn ended, including with a question (a `result` frame): the
-    # same Hash the turn's "result" holds, or nil for another event.
+    # same AgentResult the turn's #result returns, or nil for another event.
     def result
       return nil unless type == "result" && payload.is_a?(Hash)
 
-      payload
+      AgentResult.wrap(payload)
     end
 
     private

data/lib/pinesandbox/agent_turn.rb

@@ -1,6 +1,28 @@
 require "time"
 
 module PineSandbox
+  # How a turn ended (spec PublicTurnResult), from AgentTurn#result and
+  # AgentEvent#result: the result's own string-keyed Hash, extended with these
+  # readers. It stays a plain Hash, so a change to it is kept and YAML and JSON
+  # store it as they did before the readers existed. A frozen result can't be
+  # extended, so it reads as a frozen copy.
+  module AgentResult
+    def self.wrap(value)
+      return value unless value.is_a?(Hash)
+      return value if value.is_a?(self)
+      return value.dup.extend(self).freeze if value.frozen?
+
+      value.extend(self)
+    end
+
+    def terminal_reason = self["terminal_reason"]
+    # The agent's closing message; the question for "needs_input".
+    def summary = self["summary"]
+    def artifacts = self["artifacts"]
+    def author = self["author"]
+    def usage = self["usage"]
+  end
+
   # One unit of agent work (spec PublicTurn), returned by AgentMode#run,
   # #wait, #answer, #steer and #cancel. A turn starts when a run or an answer is
   # accepted and ends when the agent finishes, fails, is canceled or asks a
@@ -25,8 +47,8 @@ module PineSandbox
     def state = self["state"]
     # The turn this turn's answer opened; present once it is "answered".
     def next_turn_id = self["next_turn_id"]
-    # How the turn ended, with "usage"; nil while it runs.
-    def result = self["result"]
+    # How the turn ended, an AgentResult with its usage; nil while it runs.
+    def result = AgentResult.wrap(self["result"])
     def first_event_id = self["first_event_id"]
     def last_event_id = self["last_event_id"]
 

data/lib/pinesandbox/attach_credentials_source.rb

@@ -12,17 +12,17 @@ module PineSandbox
   #   * POST /v1/computers                                — optional legacy
   #     pre-registration helper. Normal attach does not require it.
   #   * POST /v1/computers/:computer_id/attach-credentials — body carries the
-  #     runtime coordinates {pod_uid, coord_boot_id}; returns {bind_token,
+  #     start's coordinates {pod_uid, coord_boot_id}; returns {bind_token,
   #     broker_grant, key_assertion, binding_revision}. The portal authenticates
   #     the pk_ and atomically creates/rechecks its minimal authorization row,
   #     advances the key floor, supersedes the prior binding, and mints.
   #   * DELETE /v1/computers/:computer_id                 — permanent delete.
   #     204 for deleted, already deleted, unknown, and cross-project ids alike.
   #
-  # This source caches nothing. Computer#run_bind calls it exactly once for a
-  # sandbox, then convergence retries re-send the held envelope verbatim
-  # (the bind is idempotent on jti + ciphertext). A runtime-identity shift
-  # requires a fresh sandbox; it never authorizes the same sandbox twice.
+  # This source caches nothing. Computer#run_bind calls it exactly once for each
+  # start, then convergence retries re-send the held envelope verbatim
+  # (the bind is idempotent on jti + ciphertext). A change of pod_uid or
+  # coord_boot_id requires a new start; it never authorizes the same start twice.
   # The pk_ never appears in #inspect.
   class AttachCredentialsSource
     REGISTER_PATH = "/v1/computers"
@@ -97,7 +97,7 @@ module PineSandbox
       payload
     end
 
-    # One authorization-registry read before Start; never a runtime status poll.
+    # One authorization-registry read before Start; never a Computer status poll.
     def current_binding(computer_id)
       resp = get("#{REGISTER_PATH}/#{computer_id}", op: "computer binding lookup")
       if resp.status == 404
@@ -134,9 +134,9 @@ module PineSandbox
       end
     end
 
-    # Mint the per-attach credentials for one runtime + boot. `sandbox_id` is the
-    # provisioned sandbox this attach targets — the portal records the
-    # sandbox→computer attribution at mint (its renewal gate keys off it).
+    # Mint the per-attach credentials for one Computer sandbox and boot. `sandbox_id`
+    # is the sandbox id this attach targets — the portal records which Computer it
+    # belongs to at mint (its renewal gate keys off it).
     # Returns a Hash with string keys: "bind_token", "broker_grant",
     # "key_assertion", "binding_revision", and the effective "location"
     # (plus expiry metadata).
@@ -214,7 +214,7 @@ module PineSandbox
             problem["current_binding_revision"], problem["current_sandbox_id"]
           ),
           current_binding_revision: problem["current_binding_revision"],
-          current_runtime_id: problem["current_sandbox_id"],
+          current_sandbox_id: problem["current_sandbox_id"],
           **error_attributes(resp)
         )
       else
@@ -347,12 +347,12 @@ module PineSandbox
 
     # The attach revision is a fence against two live attaches of one
     # Computer, so the SDK never retries past it; the message says what to do.
-    def binding_conflict_message(message, current_revision, current_runtime_id)
+    def binding_conflict_message(message, current_revision, current_sandbox_id)
       return message unless current_revision.is_a?(Integer)
 
-      holder = current_runtime_id.to_s.empty? ? "" : " (runtime #{current_runtime_id})"
+      holder = current_sandbox_id.to_s.empty? ? "" : " (Computer sandbox #{current_sandbox_id})"
       "#{message}. Another start changed the Computer binding#{holder}. " \
-        "Do not retry automatically. Check the current runtime before starting again."
+        "Do not retry automatically. Check whether the Computer is still running before starting again."
     end
 
     def error_message(resp, default)

data/lib/pinesandbox/bind_hpke.rb

@@ -15,7 +15,7 @@ module PineSandbox
     module_function
 
     # info binds the sealed payload to the receiving process identity so a
-    # ciphertext sealed for one runtime/boot cannot be opened by another.
+    # ciphertext sealed for one Computer sandbox/boot cannot be opened by another.
     # MUST byte-match the receiver's info string.
     #
     # @param pod_uid [String]
@@ -26,8 +26,8 @@ module PineSandbox
     end
 
     # restore_info is the two-round v3 restore's round-2 domain: the
-    # integrator-unwrapped component secrets sealed back to the same runtime
-    # key. Same suite, DISTINCT domain — a bind ciphertext can never be
+    # integrator-unwrapped component secrets sealed back to the same Computer
+    # sandbox key. Same suite, DISTINCT domain — a bind ciphertext can never be
     # replayed as a secrets payload or vice versa. MUST byte-match the
     # receiver's restore info string.
     def restore_info(pod_uid, coord_boot_id)
@@ -36,7 +36,7 @@ module PineSandbox
 
     # seal encrypts plaintext to the recipient's raw 32-byte X25519 public
     # key. The AAD is fixed empty (the portal attach path carries no nonce —
-    # payload-to-runtime binding lives in the info string).
+    # payload-to-sandbox binding lives in the info string).
     #
     # @param recipient_pub_raw [String] 32 raw bytes (NOT base64).
     # @param plaintext [String] bytes to seal.