k9o 1.4.0 → 1.5.2

data/lib/k9o/vault.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'base64'
 require 'uri'
 
 module K9o
@@ -81,7 +80,7 @@ module K9o
     # `metadata` (`Hash[String, String]`) are passed through verbatim.
     def create(name:, value:, region: nil, visibility: nil, metadata: nil)
       slug = require_project_slug
-      body = { 'value' => Base64.strict_encode64(value) }
+      body = { 'value' => [value].pack('m0') }
       body['visibility'] = visibility if visibility
       body['metadata'] = metadata if metadata
       HttpTransport.request(
@@ -119,7 +118,7 @@ module K9o
       )
       data = envelope.data
       if data.is_a?(Hash) && data.key?('value')
-        data = data.merge('value' => Base64.decode64(data['value']))
+        data = data.merge('value' => data['value'].unpack1('m'))
       end
       Envelope.new(data: data, meta: envelope.meta)
     end
@@ -132,7 +131,7 @@ module K9o
     # schema claims — call `get` afterward if the full summary is needed.
     def update(name, value:, region: nil, metadata: nil)
       slug = require_project_slug
-      body = { 'value' => Base64.strict_encode64(value) }
+      body = { 'value' => [value].pack('m0') }
       body['metadata'] = metadata if metadata
       HttpTransport.request(
         config: @config, method: 'PUT',

data/lib/k9o/vectors.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module K9o
+  # Vector collections: k9o.vectors.* store embeddings you computed yourself, next to the text and metadata they came
+  # from, and find the nearest ones.
+  #
+  #   nearest(collection, query_vector, top_k:, min_score:, metric:, filters:)  POST /@<slug>/vectors/<collection>/search
+  #   upsert(collection, rows)                                                  POST /@<slug>/vectors/<collection>/upsert
+  #
+  # Both send the vector in the request body, so they take real embeddings of any common size (up to 16000 numbers).
+  # The collection name must start with +_+. The first upsert creates the collection and fixes its dimension; every
+  # later vector must have the same length. Searching a collection that was never upserted answers 404
+  # K9O_COLLECTION_NOT_FOUND.
+  class Vectors
+    METRICS = %w[cosine euclidean dot].freeze
+    MAX_VECTOR = 16_000
+    MAX_ROWS = 1000
+    # Snake_case spellings accepted for the camelCase wire keys of a row and of its +_source+.
+    ROW_ALIASES = { 'content_hash' => 'contentHash', 'subject_ids' => 'subjectIds' }.freeze
+    SOURCE_ALIASES = { 'chunk_index' => 'chunkIndex' }.freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    # The rows nearest to +query_vector+ (1 to 16000 numbers), closest first. +top_k+ is 1 to 1000 (the gateway
+    # defaults to 10); +min_score+ drops results scoring below it; +metric+ is cosine (default), euclidean or dot;
+    # +filters+ is a Hash of equality checks on +id+, +contentHash+, +source.<key>+ and +metadata.<key>+.
+    # +data+ is { 'results' => [...], 'collection' => name }.
+    def nearest(collection, query_vector, top_k: nil, min_score: nil, metric: nil, filters: nil)
+      route = path(collection, 'search')
+      check_vector(query_vector, 'query_vector')
+      body = { 'queryVector' => query_vector.to_a }
+      unless top_k.nil?
+        unless top_k.is_a?(Integer) && top_k >= 1 && top_k <= 1000
+          raise invalid('top_k must be a whole number from 1 to 1000', top_k: top_k)
+        end
+
+        body['topK'] = top_k
+      end
+      unless min_score.nil?
+        raise invalid('min_score must be a number', min_score: min_score) unless finite?(min_score)
+
+        body['minScore'] = min_score
+      end
+      body['metric'] = ApprovalChecks.enum!(metric, METRICS, 'metric') unless metric.nil?
+      unless filters.nil?
+        raise invalid('filters must be a Hash of path to value') unless filters.is_a?(Hash)
+
+        body['filters'] = filters.transform_keys(&:to_s)
+      end
+      call(route, body)
+    end
+
+    # Insert or overwrite 1 to 1000 rows in one request; the first upsert creates the collection. A row is a Hash
+    # with +vector+ and +_source+ ({ handle:, chunkIndex: }), and optionally +id+, +contentHash+, +text+, +metadata+
+    # and +subjectIds+ (one end-user id, ["eu_..."]; required unless the collection was declared shared). Keys may
+    # be strings or symbols, and +content_hash+, +subject_ids+ and +chunk_index+ are accepted for the camelCase
+    # names. A single row may be passed on its own, with or without braces. +data+ is { 'upserted' => n,
+    # 'collection' => name }.
+    def upsert(collection, rows = nil, **row)
+      route = path(collection, 'upsert')
+      rows = [row] if rows.nil? && !row.empty?
+      rows = [rows] if rows.is_a?(Hash)
+      unless rows.is_a?(Array) && rows.size >= 1 && rows.size <= MAX_ROWS
+        raise invalid("rows must be an array of 1 to #{MAX_ROWS} rows")
+      end
+
+      wire = rows.each_with_index.map do |entry, index|
+        raise invalid("rows[#{index}] must be a Hash") unless entry.is_a?(Hash)
+
+        normalize_row(entry, index)
+      end
+      call(route, 'rows' => wire)
+    end
+
+    private
+
+    def normalize_row(entry, index)
+      row = entry.each_with_object({}) do |(key, value), out|
+        name = key.to_s
+        out[ROW_ALIASES.fetch(name, name)] = value
+      end
+      check_vector(row['vector'], "rows[#{index}].vector")
+      source = row['_source']
+      if source.is_a?(Hash)
+        row['_source'] = source.each_with_object({}) do |(key, value), out|
+          name = key.to_s
+          out[SOURCE_ALIASES.fetch(name, name)] = value
+        end
+      end
+      row['vector'] = row['vector'].to_a
+      row
+    end
+
+    def check_vector(vector, name)
+      unless vector.is_a?(Array) && vector.size >= 1 && vector.size <= MAX_VECTOR
+        raise invalid("#{name} must be an array of 1 to #{MAX_VECTOR} numbers")
+      end
+      return if vector.all? { |n| finite?(n) }
+
+      raise invalid("#{name} must contain only finite numbers")
+    end
+
+    def finite?(value)
+      value.is_a?(Numeric) && !value.is_a?(Complex) && (!value.respond_to?(:finite?) || value.finite?)
+    end
+
+    def invalid(message, context = {})
+      ApprovalChecks.invalid(message, context)
+    end
+
+    def call(route, body)
+      HttpTransport.request(config: @config, method: 'POST', path: route, body: body)
+    end
+
+    def path(collection, tail)
+      raise invalid('a vector collection name must start with _', collection: collection) unless collection.is_a?(String) && collection.start_with?('_')
+
+      slug = Studio.require_project_slug(@config, 'vectors')
+      UrlGrammar.project_path(slug, "vectors/#{::URI.encode_www_form_component(collection).gsub('+', '%20')}/#{tail}")
+    end
+  end
+end

data/lib/k9o/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module K9o
-  VERSION = '1.4.0'
+  VERSION = '1.5.2'
 end

data/lib/k9o.rb

@@ -31,6 +31,7 @@ require_relative 'k9o/http_transport'
 require_relative 'k9o/data'
 require_relative 'k9o/query'
 require_relative 'k9o/projects'
+require_relative 'k9o/locate'
 require_relative 'k9o/gate'
 require_relative 'k9o/studio'
 require_relative 'k9o/compute'
@@ -42,6 +43,16 @@ require_relative 'k9o/approvals'
 require_relative 'k9o/schema'
 require_relative 'k9o/migrations'
 require_relative 'k9o/functions'
+require_relative 'k9o/schedules'
+require_relative 'k9o/vectors'
+require_relative 'k9o/metadata'
+require_relative 'k9o/rampart'
+require_relative 'k9o/moat'
+require_relative 'k9o/custody'
+require_relative 'k9o/analytics'
+require_relative 'k9o/keys'
+require_relative 'k9o/crypto'
+require_relative 'k9o/end_users'
 require_relative 'k9o/policies'
 require_relative 'k9o/audit'
 require_relative 'k9o/orgs'
@@ -50,6 +61,8 @@ require_relative 'k9o/org'
 # kibo ZK BYOK/HYOK crypto — self-guards its native binding (LoadError-safe), so
 # requiring k9o never breaks on a platform without the kibo native lib.
 require_relative 'k9o/kibo'
+require_relative 'k9o/kibo_client_core'
+require_relative 'k9o/kibo_ffi_core'
 # kibo vault REST surface (client.kibo.vault.secrets) —.
 require_relative 'k9o/vault'
 # Barbican guardrail SDK — self-guards its native binding (LoadError-safe), so

data/sig/k9o/approvals.rbs

@@ -11,17 +11,39 @@ module K9o
   end
 
   class Approvals
+    attr_reader comments: ApprovalComments
     def initialize: (untyped config) -> void
-    # Not paginated: only `limit` (1 to 200, default 50) caps the result.
-    def list: (?status: (String | Symbol)?, ?limit: Integer?) -> Envelope
+    # One page, newest first. `limit` is 1 to 200 (default 50); pass `meta.cursor.next` back as `cursor`
+    # (nil on the last page).
+    def list: (?status: (String | Symbol)?, ?limit: Integer?, ?cursor: String?) -> Envelope
     def get: (String id) -> Envelope
     # `status` on the answer stays "pending_approval" while more approvers are needed.
     def approve: (String id, ?reason: String?) -> Envelope
     def reject: (String id, reason: String) -> Envelope
-    # Failed rows are skipped without a report: compare `affectedIds` with what you intended.
+    # HTTP 200 even when rows fail: `data["failed"]` is an Array of { "id", "code", "reason" } (empty when none).
+    # Compare `affectedIds` with what you intended.
     def bulk: (action: (String | Symbol), criteria: Hash[(String | Symbol), untyped], ?reason: String?) -> Envelope
   end
 
+  # `approvals.comments`. Posting needs a session (a personal access token alone is refused, K9O_RBAC_DENY).
+  class ApprovalComments
+    VISIBILITIES: Array[String]
+    BODY_MAX: Integer
+
+    # An Envelope whose data is the Array of comments, oldest first; `next_cursor` is nil on the last page.
+    # A comment is { "id", "caseId", "authorId", "visibility", "body", "createdAt" }.
+    class Page < Envelope
+      attr_reader next_cursor: String?
+      def initialize: (data: untyped, meta: Meta, ?next_cursor: String?) -> void
+    end
+
+    def initialize: (untyped config) -> void
+    # `body` is 1 to 4000 characters; `visibility` is "everyone" or "approvers_only", fixed once posted. HTTP 201.
+    def add: (String pending_id, body: String, visibility: (String | Symbol)) -> Envelope
+    # `limit` is 1 to 200 (default 50); pass `next_cursor` back as `cursor`.
+    def list: (String pending_id, ?limit: Integer?, ?cursor: String?) -> Page
+  end
+
   class ApprovalPolicies
     COLLECTION_RE: Regexp
 

data/sig/k9o/datasets.rbs

@@ -0,0 +1,125 @@
+# RBS signatures for `client.analytics` (datasets), `client.rollups` and `client.keys`.
+
+module K9o
+  class Download
+    attr_reader body: String
+    attr_reader content_type: String?
+    def initialize: (body: String, ?content_type: String?) -> void
+  end
+
+  class AnalyticsRollups
+    def initialize: (untyped config) -> void
+    def create: (String dataset_slug, slug: String, source: String, measures: Array[Hash[Symbol | String, untyped]], window_seconds: Integer,
+                 ?dimensions: Array[String]?, ?subject_field: String?, ?non_personal: bool?, ?reattest_interval_days: Integer?) -> Envelope
+    def list: (String dataset_slug) -> Envelope
+    def delete: (String dataset_slug, String rollup_id) -> Envelope
+    # People only: a service, workload or extension token gets 403 K9O_RBAC_DENY (reason human_only).
+    def reattest: (String dataset_slug, String rollup_id, ?reattest_interval_days: Integer?) -> Envelope
+  end
+
+  class AnalyticsSchedules
+    def initialize: (untyped config) -> void
+    def create: (String dataset_slug, from_collection: String, interval_seconds: Integer, ?reattest_interval_days: Integer?) -> Envelope
+    def list: (String dataset_slug) -> Envelope
+    def delete: (String dataset_slug, String schedule_id) -> Envelope
+    def reattest: (String dataset_slug, String schedule_id, ?reattest_interval_days: Integer?) -> Envelope
+  end
+
+  class Analytics
+    attr_reader rollups: AnalyticsRollups
+    attr_reader schedules: AnalyticsSchedules
+    def initialize: (untyped config) -> void
+    def list: () -> Envelope
+    def query: (String sql, Array[String] datasets) -> Envelope
+    def create: (String slug, display_name: String, columns: Array[Hash[Symbol | String, untyped]], residency_class: (String | Symbol),
+                 ?partition_by: Array[String]?, ?storage_target: Hash[Symbol | String, untyped]?) -> Envelope
+    def get: (String slug) -> Envelope
+    def delete: (String slug) -> Envelope
+    def materialize: (String slug, ?from_collection: String?, ?from_query: String?) -> Envelope
+    def read: (String slug, ?partition_filter: Hash[Symbol | String, untyped]?, ?cursor: String?, ?limit: Integer?) -> Envelope
+    def write: (String slug, (Array[Hash[Symbol | String, untyped]] | String) rows, ?on_error: (String | Symbol)?) -> Envelope
+    def upload: (String slug, (String | IO) data, format: (String | Symbol), ?filename: String, ?manifest: Hash[Symbol | String, untyped]?,
+                 ?dry_run: bool?, ?on_error: (String | Symbol)?, ?delimiter: String?, ?encoding: String?, ?has_header: bool?) -> Envelope
+    def download_original: (String slug) -> Download
+  end
+
+  class Rollups
+    def initialize: (untyped config) -> void
+    def list: () -> Envelope
+    def read: (String rollup_slug, ?from: (String | Time)?, ?to: (String | Time)?, ?dims: (Array[String] | String)?) -> Envelope
+    def subscribe: (String rollup_slug, ?from_sequence: Integer?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+  end
+
+  class Keys
+    STATUSES: Array[String]
+    def initialize: (untyped config) -> void
+    # data: { "items" => [key] } (not paged)
+    def list: (?status: (String | Symbol)?) -> Envelope
+    def get: (String key_id) -> Envelope
+    # data: { "keyId", "previousVersion", "newVersion", "status" => "rotated" }
+    # step_up: ^(StepUpChallenge, String, String) -> { method: String, proof: String }
+    def rotate: (String key_id, ?step_up: untyped, ?headers: Hash[String, String]?) -> Envelope
+
+    class StepUpChallenge < Struct[untyped]
+      attr_reader scope_set_root: String
+      attr_reader nonce: String
+      attr_reader min_tier: String?
+      attr_reader methods: Array[String]
+      attr_reader max_age_sec: Integer?
+      attr_reader single_use: bool?
+      attr_reader rp_id: String?
+    end
+  end
+
+  class Crypto
+    def initialize: (untyped config) -> void
+    def encrypt: (String crypt, Array[Hash[Symbol | String, untyped] | String] items) -> Envelope
+    def decrypt: (String crypt, Array[Hash[Symbol | String, untyped] | String] items) -> Envelope
+    def rewrap: (String crypt, Array[Hash[Symbol | String, untyped] | String] items) -> Envelope
+    def self.text: (Hash[String, untyped] item) -> String?
+    # Reads the project's custody mode; every encrypt does this first, with no cache.
+    def mode: () -> Mode
+    # Registers the Kibo client core (an object with encrypt, decrypt and rewrap); nil removes it.
+    def use_client_core: (untyped core) -> untyped
+    def self.check_expected_key_refs: (Array[String]? refs) -> Array[String]?
+    def self.key_ref_matches?: (String key_ref, Array[String] expected, provider: (:aws | :gcp | :azure | :vault)) -> bool
+
+    # Ask for a short-lived federated token for +op+ ("encrypt", "decrypt" or "rewrap") on +crypt+.
+    def federated_token: (String crypt, String op) -> FederatedToken
+
+    # Crypts: data is { "crypts" => [...] } (list) or one { "name", "status", "createdAt", "retiredAt" } Hash.
+    def crypts_list: () -> Envelope
+    def crypts_create: (String name) -> Envelope
+    def crypts_retire: (String name) -> Envelope
+
+    class Mode < Struct[untyped]
+      def custody_mode: () -> String?
+      def epoch: () -> String?
+    end
+
+    # +provider+ and +project_id+ are nil unless the gateway names them; they are only checked against configuration.
+    class FederatedToken < Struct[untyped]
+      attr_reader token: String
+      attr_reader expires_at: String
+      attr_reader issuer: String
+      attr_reader subject: String
+      attr_reader audience: String
+      attr_reader kid: String
+      attr_reader provider: String?
+      attr_reader project_id: String?
+    end
+  end
+
+  class Audit
+    # Yields { "auditEventId", "type", "actorType", "occurredAt", "outcome", "eventId" }.
+    def tail: (?types: (Array[String | Symbol] | String | Symbol)?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+    def replay: (?topic: String, ?after_audit_event_id: String?, ?from_sequence: Integer?, ?until_sequence: Integer?, ?limit: Integer?) -> Envelope
+  end
+
+  class K9oClient
+    attr_reader analytics: Analytics
+    attr_reader rollups: Rollups
+    attr_reader keys: Keys
+    attr_reader crypto: Crypto
+  end
+end

data/sig/k9o/gate.rbs

@@ -7,6 +7,8 @@ module K9o
     # The refresh token is required: the gateway answers 400 without it.
     def sign_out: (refresh_token: String) -> Envelope
     def whoami: () -> Envelope
+    def revoke_all_sessions: () -> Envelope
+    # `data` is `{ accessToken, refreshToken, expiresAt }`; the refresh token sent stops working, so store the new one.
     def refresh_token: (refresh_token: String) -> Envelope
   end
 end

data/sig/k9o/kerror.rbs

@@ -0,0 +1,24 @@
+# RBS signatures for the error type raised by every call.
+
+module K9o
+  class KError < StandardError
+    attr_reader code: String
+    attr_reader context: Hash[untyped, untyped]
+    # Suggested next step as text, or nil.
+    attr_reader recommendation: String?
+    attr_reader status: Integer?
+    attr_reader request_id: String?
+    # Seconds the gateway asks the caller to wait before retrying, or nil.
+    attr_reader retry_after_sec: Numeric?
+    # The step-up challenge of a 401 K9O_STEP_UP_REQUIRED, or nil.
+    def step_up: () -> Keys::StepUpChallenge?
+
+    def initialize: (code: String, message: String, ?context: Hash[untyped, untyped], ?recommendation: String?, ?status: Integer?, ?request_id: String?, ?retry_after_sec: Numeric?) -> void
+    def with_recommendation: (String? rec) -> KError
+    def message: () -> String
+    def to_s: () -> String
+    def self.from_wire: (Hash[String, untyped] wire, Integer? status) -> KError
+    def self.recommendation_text: (untyped raw) -> String?
+    def self.retry_after: (untyped raw) -> Numeric?
+  end
+end

data/sig/k9o/kibo_client_core.rbs

@@ -0,0 +1,25 @@
+# RBS signatures for the Kibo client core of client.crypto (BYOK and HYOK projects).
+
+module K9o
+  class KiboClientCore
+    EXCHANGE_TIMEOUT: String
+    CORE_FUNCTIONS: Array[Symbol]
+    PROVIDER_WIRE: Hash[Symbol, String]
+    SKEW_SECS: Integer
+    DEFAULT_DEADLINE_SECS: Integer
+
+    # +core+ responds to app_crypto_seal_blocking, app_crypto_open_blocking, acquire_kms_credential_blocking and
+    # core_capabilities (the generated KiboKmsRestFfi module does). +federated_token+ answers call(crypt, op) with a
+    # Crypto::FederatedToken.
+    def initialize: (provider: (:aws | :gcp | :azure | :vault), posture: (:byok | :hyok), key_ref: Hash[Symbol, untyped],
+                     federation: Hash[Symbol | String, untyped], expected_key_refs: Array[String], federated_token: untyped, core: untyped,
+                     ?project_id: String?, ?provider_config: Hash[Symbol | String, String?], ?exchange_deadline: Numeric,
+                     ?now: ^() -> Integer) -> void
+    def enforces_expected_key_refs?: () -> true
+    def encrypt: (String crypt, Array[Hash[Symbol, untyped]] items, **untyped options) -> Hash[String, Array[Hash[String, untyped]]]
+    def decrypt: (String crypt, Array[Hash[Symbol, untyped]] items, **untyped options) -> Hash[String, Array[Hash[String, untyped]]]
+    def rewrap: (String crypt, Array[Hash[Symbol, untyped]] items, **untyped options) -> Hash[String, Array[Hash[String, untyped]]]
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+end

data/sig/k9o/metadata.rbs

@@ -0,0 +1,54 @@
+# RBS signatures for `client.metadata`.
+
+module K9o
+  class Metadata
+    # An Envelope whose data is the Array of rows; `cursor` is the next page's cursor, or nil on the last page.
+    # A row is { "surface", "scope", "recordId" (collection) or "eventId" (telemetry), "metadata" => { column => value } }.
+    class Page < Envelope
+      def cursor: () -> String?
+    end
+
+    OPS: Array[String]
+    METRICS: Array[String]
+    SLICES: Array[String]
+    PREFIX: String
+    MAX_COLUMNS: Integer
+    MAX_LIMIT: Integer
+    TELEMETRY_FIELDS: Array[String]
+
+    attr_reader vectors: MetadataVectors
+    attr_reader index: MetadataIndex
+
+    def initialize: (untyped config) -> void
+    # surfaces: ["collection:posts"]; where: [{ field:, op:, value: }]; limit 1..1000; cursor only with one surface.
+    # Options may be keyword arguments or one Hash.
+    def filter: (?Hash[String | Symbol, untyped]? input, ?surfaces: Array[String], ?where: Array[Hash[String | Symbol, untyped]]?, ?limit: Integer?, ?cursor: String?) -> Page
+    # data is the whole updated record. Columns may be keyword arguments or one Hash.
+    def set: (String | Symbol collection, String id, ?Hash[String | Symbol, untyped]? columns, **untyped extra) -> Envelope
+    def search: (?Hash[String | Symbol, untyped]? input, ?surface: String, ?field: String | Symbol, ?q: String, ?limit: Integer?) -> Page
+    # Yields { "topic", "eventType", "payload" => { "collection", "id" }, "occurredAt", "eventId"? }.
+    def subscribe: (String surface, ?Hash[String | Symbol, untyped]? input, ?from_sequence: Integer?, ?fromSequence: Integer?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+  end
+
+  class MetadataVectors
+    def initialize: (untyped config) -> void
+    # Rows carry no score; at most 50 rows come back whatever k is.
+    def nearest: (?Hash[String | Symbol, untyped]? input, ?surface: String, ?column: String | Symbol, ?embedding: Array[Numeric], ?k: Integer?, ?metric: (String | Symbol)?, ?where: Array[Hash[String | Symbol, untyped]]?) -> Metadata::Page
+  end
+
+  class MetadataIndex
+    def initialize: (untyped config) -> void
+    # data is { "collection" => String, "columns" => [{ "column" => String, "indexed" => bool }] }.
+    def get: (String | Symbol collection) -> Envelope
+    def declare: (String | Symbol collection, Array[Hash[String | Symbol, untyped]] columns) -> Envelope
+  end
+
+  class Realtime
+    # The reconnecting reader behind subscribe; initial_query applies to the first connection only.
+    def feed: (String route, Hash[String, untyped] q, Hash[String, untyped]? initial_query, (^(Hash[String, untyped]) -> untyped)? on_resync) -> Enumerator[Hash[String, untyped], untyped]
+  end
+
+  class K9oClient
+    attr_reader metadata: Metadata
+  end
+end

data/sig/k9o/moat.rbs

@@ -0,0 +1,29 @@
+# RBS signatures for Moat, the local guard around a model call.
+
+module K9o
+  module Moat
+    REASONS: Array[Symbol]
+
+    # Raised when Moat refuses input or output. `reason` is :role_marker, :input_schema, :output_schema or :pii.
+    class Refusal < StandardError
+      attr_reader reason: Symbol
+      attr_reader detail: String
+      def initialize: (Symbol reason, String detail) -> void
+    end
+
+    class ConfigError < ArgumentError
+    end
+
+    class SchemaError < ConfigError
+    end
+
+    def self.new: (prompt: String, ?input_schema: Hash[String | Symbol, untyped]?, ?output_schema: Hash[String | Symbol, untyped]?, ?filters: Hash[Symbol | String, ^(String) -> untyped]?) -> Guard
+
+    class Guard
+      def initialize: (prompt: String, ?input_schema: Hash[String | Symbol, untyped]?, ?output_schema: Hash[String | Symbol, untyped]?, ?filters: Hash[Symbol | String, ^(String) -> untyped]?) -> void
+      def messages: (untyped untrusted_input) -> Array[{ role: String, content: String }]
+      def check_output: (untyped model_output) -> untyped
+      def prompt_sha256: () -> String
+    end
+  end
+end

data/sig/k9o/rampart.rbs

@@ -0,0 +1,59 @@
+# RBS signatures for Rampart classification and receipt verification.
+
+module K9o
+  module Jcs
+    class Error < ArgumentError
+      attr_reader kind: Symbol
+      def initialize: (String message, ?Symbol kind) -> void
+    end
+
+    def self.canonicalize: (untyped value) -> String
+    def self.canonical_bytes: (untyped value) -> String
+  end
+
+  module Ed25519
+    def self.verify: (String public_key, String message, String signature) -> bool
+    def self.native?: () -> bool
+  end
+
+  class Rampart
+    RECEIPT_TYP: String
+    CLASSIFICATIONS: Array[String]
+    DEFAULT_CLOCK_SKEW: Integer
+    REASONS: Array[Symbol]
+
+    # Raised by verify_receipt. `reason` is one of REASONS: :malformed, :key_unknown, :alg, :typ, :signature,
+    # :issuer, :project_unknown, :project, :expired, :not_yet_valid, :input_hash.
+    class ReceiptRefusal < KError
+      attr_reader reason: Symbol
+      def initialize: (Symbol reason, String detail) -> void
+    end
+
+    class Verdict < Struct[untyped]
+      attr_accessor classification: String
+      attr_accessor risk_bp: Integer
+      attr_accessor confidence_bp: Integer
+      attr_accessor categories: Array[String]
+      attr_accessor project_id: String
+      attr_accessor calibration_version: String
+      attr_accessor input_sha256: String
+      attr_accessor issued_at: Time
+      attr_accessor expires_at: Time
+      attr_accessor kid: String
+      attr_accessor windows: Integer?
+    end
+
+    def initialize: (untyped config) -> void
+    # data: { "classification", "riskScore", "confidence", "categories", "calibrationVersion", "classificationReceipt", "projectId" }.
+    def classify: (Hash[String | Symbol, untyped] input, ?label: String?) -> Envelope
+    # data: { "keys" => [ { "kid", "kty", "crv", "x", ... } ], "issuer" => "<issuer>/rampart" }. Public: no credential is sent.
+    def jwks: () -> Envelope
+    # `receipt` is the Envelope classify returned (it carries the receipt and its projectId) or the bare receipt String.
+    def verify_receipt: ((Envelope | String) receipt, Hash[String | Symbol, untyped] input, ?key_set: (Hash[untyped, untyped] | Array[Hash[untyped, untyped]])?, ?issuer: String?, ?project_id: String?, ?clock_skew: Numeric, ?clock: (Time | Numeric | ^() -> (Time | Numeric))?) -> Verdict
+    def input_digest: (Hash[String | Symbol, untyped] input) -> String
+  end
+
+  class K9oClient
+    attr_reader rampart: Rampart
+  end
+end

data/sig/k9o/realtime.rbs

@@ -0,0 +1,34 @@
+# RBS signatures for `client.realtime`.
+
+module K9o
+  class Realtime
+    DEFAULT_RETRY_MS: Integer
+    SEEN_LIMIT: Integer
+
+    # Seconds without any bytes after which a connection is abandoned (default 45).
+    def self.idle_timeout: () -> Numeric
+    def self.idle_timeout=: (Numeric) -> Numeric
+    # Longest reconnect delay in seconds (default 30).
+    def self.max_backoff: () -> Numeric
+    def self.max_backoff=: (Numeric) -> Numeric
+    def self.sleeper: () -> ^(Numeric) -> void
+    def self.sleeper=: (^(Numeric) -> void) -> ^(Numeric) -> void
+
+    def initialize: (untyped config) -> void
+    # Yields { "topic", "eventType", "payload", "occurredAt", "eventId" }. Reconnects with `Last-Event-ID`, drops
+    # events already delivered, and calls `on_resync` with { "reason", "action" } when the position is lost.
+    def subscribe: (String topic, ?filter: Hash[untyped, untyped]?, ?on_resync: (^(Hash[String, untyped]) -> untyped)?) -> Enumerator[Hash[String, untyped], untyped]
+
+    # POST /@<slug>/realtime/replay: data is { "events", "nextCursor", "hasMore" } plus "resync" when the topic has no stored history.
+    def replay: (String topic, ?from_sequence: Integer?, ?until_sequence: Integer?, ?limit: Integer?) -> Envelope
+
+    module Topic
+      def self.collection: (String collection) -> String
+      def self.workflow_runs: () -> String
+      def self.query_executed: (String query_id) -> String
+      def self.dashboard_refresh: (String dashboard_id) -> String
+      def self.function_invocations: (String function_id) -> String
+      def self.audit_org: (String event_family) -> String
+    end
+  end
+end