axhub-sdk 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 572be1a63c2d4f482f151942ba1b90e92c82789be69b56eee536d3b2c7ea9a3d
-  data.tar.gz: f93cb282b2c3919ac41633345bf3a396879d0228c3b635d4be032aa4894f3b59
+  metadata.gz: 85d987bf30aef83087acd96efae5f26be3edb75bab6db845b2b03e20855e022f
+  data.tar.gz: 9a9f21590240febb36affc2af156007840ccb0d273a279a89bd520544fa5c97c
 SHA512:
-  metadata.gz: fd0379f32050fdd452634e294d775af5291799c0370c7e4b4a696882335de68dda77560ea83a965445bffff368839ff6e3d2b87f5d3e8f45b45b0215449dd647
-  data.tar.gz: bae059dbb674d23c7a584912367b0b644e6a5ef5fc0790e44f02b68f5ec3145027dcec11afda99436cd2c950f646ac428363797f570ae403ed92135e6da87207
+  metadata.gz: ff15d439f50d8b4b28f79307c951f52b4581a234c7d50c58735153d090ceb8a44885852a37ec03760254a92ade0362633780641df75b1e3e5fbaf6279984a8b2
+  data.tar.gz: 8b0ec9cf0a69d1b702e859ee033f1b2d35eb3df213434f8acaceb5f208206b043300e526f60134f5f1274bbfb6cc3a21592c3fa432ca431b8c25e07aa8120269

data/README.md

@@ -1,12 +1,162 @@
 # AX Hub Ruby SDK
 
-AX Hub Ruby SDK for AX Hub (`https://api.axhub.ai`).
+AX Hub Ruby SDK for `https://api.axhub.ai`. It gives agents a dependency-light client, generated backend route metadata, bounded-context operation clients, typed error metadata, conformance tests, and a live-testable app/data workflow.
 
-This SDK exposes generated AX Hub API route metadata, typed error metadata, bounded-context route facades, regression/conformance tests, and a local test app.
+## Install
 
-## Verify
+```bash
+gem install axhub-sdk -v 0.2.0
+```
+
+Local development:
+
+```bash
+bundle install
+ruby -Ilib test/client_test.rb
+```
+
+## Required environment for agent work
+
+```bash
+export AXHUB_TOKEN="<short-lived PAT>"
+export AXHUB_TENANT_ID="cc1e58f1-8e46-4ac7-96c1-190c4cdd5b70"   # test tenant
+export AXHUB_TENANT_SLUG="test"
+```
+
+PAT mode is explicit: `token_type: :pat` sends `X-Api-Key`. JWT mode is `token_type: :jwt` and sends `Authorization: Bearer`.
+
+## Agent quickstart: create a disposable app and table
+
+```ruby
+require 'axhub_sdk'
+
+client = AxHub::Client.new(
+  base_url: 'https://api.axhub.ai',
+  token: ENV.fetch('AXHUB_TOKEN'),
+  token_type: :pat,
+  default_tenant_id: ENV.fetch('AXHUB_TENANT_ID'),
+  default_tenant_slug: ENV.fetch('AXHUB_TENANT_SLUG', 'test')
+)
+
+me = client.request('authGetApiV1Me')
+user_id = me['userId'] || (me['user'] || {})['id']
+raise 'authGetApiV1Me did not return a user id' if user_id.nil? || user_id.empty?
+
+suffix = (Time.now.to_f * 1000).to_i.to_s[-8, 8]
+slug = "agent-rb-#{suffix}"
+table = "items#{suffix[-6, 6]}"
+
+app = client.apps.create(
+  slug: slug,
+  name: 'Agent Ruby README QA',
+  visibility: 'private',
+  auth_mode: 'anonymous',
+  resource_tier: 'S',
+  deploy_method: 'docker',
+  subdomain: slug
+)
+app_id = app['id']
+
+client.request(
+  'schemaPostApiV1AppsByAppIDTables',
+  path_params: { appID: app_id },
+  body: {
+    table_name: table,
+    owner_column: 'owner_id',
+    columns: [
+      { name: 'owner_id', type: 'uuid', nullable: false },
+      { name: 'title', type: 'text', nullable: false },
+      { name: 'status', type: 'text', nullable: false }
+    ]
+  }
+)
+
+row = client.request(
+  'schemaPostDataByTenantSlugByAppSlugByTable',
+  path_params: { tenantSlug: 'test', appSlug: slug, table: table },
+  body: { owner_id: user_id, title: 'hello', status: 'new' }
+)
+puts "created #{app_id} #{table} #{row['id']}"
+```
+
+## How to call the full API surface
+
+- High-level app create: `client.apps.create(**body)` uses `default_tenant_id`.
+- Any route by operation id: `client.request(operation_id, path_params: {}, query: {}, body: nil)`.
+- Generated facade: `client.data.schema_post_data_by_tenant_slug_by_app_slug_by_table(path_params: {}, body: {...})`.
+- Route inventory: `AxHub::ROUTES`, `AxHub::CONTEXT_ROUTES`, `AxHub::ERROR_CODES`, and `AxHub::OPERATION_METHODS`.
+- Errors: catch `AxHub::Error` and branch on `code`, `category`, `status`, and `retryable`.
+
+## Dynamic app, schema, and data operations
+
+Use the high-level `apps.create` helper for the first app, then use generated operation IDs for every backend route. Request bodies use backend wire keys, usually `snake_case`. Responses are normalized to camelCase in this SDK family, so read `tableName`, `requestId`, `revokedAt`, and similar keys from responses.
+
+| Task | Operation ID | Required path params | Success assertion |
+|------|--------------|----------------------|-------------------|
+| Create env var | `appsPostApiV1AppsByAppIDEnvVars` | `appID` | `env.list` includes `key` |
+| Delete env var | `appsDeleteApiV1AppsByAppIDEnvVarsByKey` | `appID`, `key` | `env.list` no longer includes `key` |
+| Create table | `schemaPostApiV1AppsByAppIDTables` | `appID` | response `tableName` equals requested name |
+| Inspect table | `schemaGetApiV1AppsByAppIDTablesByTableName` | `appID`, `tableName` | response `id` and `tableName` match |
+| Add column | `schemaPostApiV1AppsByAppIDTablesByTableNameColumns` | `appID`, `tableName` | inspect contains column name |
+| Drop column | `schemaDeleteApiV1AppsByAppIDTablesByTableNameColumnsByColumnName` | `appID`, `tableName`, `columnName` | inspect no longer contains column name |
+| Add table grant | `schemaPostApiV1AppsByAppIDTablesByTableNameGrants` | `appID`, `tableName` | response has grant `id` |
+| List grants | `schemaGetApiV1AppsByAppIDTablesByTableNameGrants` | `appID`, `tableName` | list contains grant `id` |
+| Revoke/delete grant | `schemaDeleteApiV1AppsByAppIDTablesByTableNameGrantsByGrantID` | `appID`, `tableName`, `grantID` | list still contains grant with `revokedAt` set |
+| Insert row | `schemaPostDataByTenantSlugByAppSlugByTable` | `tenantSlug`, `appSlug`, `table` | response has row `id` and submitted fields |
+| Get row | `schemaGetDataByTenantSlugByAppSlugByTableById` | `tenantSlug`, `appSlug`, `table`, `id` | response row `id` matches |
+| Update row | `schemaPatchDataByTenantSlugByAppSlugByTableById` | `tenantSlug`, `appSlug`, `table`, `id` | response contains patched fields |
+| List rows | `schemaGetDataByTenantSlugByAppSlugByTable` | `tenantSlug`, `appSlug`, `table` | `items` contains row `id` |
+| Count rows | `schemaGetDataByTenantSlugByAppSlugByTableCount` | `tenantSlug`, `appSlug`, `table` | `count` matches expected fixture count |
+| Browse admin rows | `schemaGetApiV1AppsByAppIDTablesByTableNameRows` | `appID`, `tableName` | response has `rows` and `columns` arrays |
+| Delete row | `schemaDeleteDataByTenantSlugByAppSlugByTableById` | `tenantSlug`, `appSlug`, `table`, `id` | follow-up get returns `404` or `410` |
+| Delete table | `schemaDeleteApiV1AppsByAppIDTablesByTableName` | `appID`, `tableName` | follow-up inspect returns `404` or `410` |
+| Delete app | `appsDeleteApiV1AppsByAppID`, then `appsDeleteApiV1AppsByAppIDPermanent` | `appID` | app is soft-deleted, then permanently deleted |
+
+Important semantics from live QA:
+
+- Row delete is hard enough for client assertions: a follow-up row get returns `404 not_found` or `410`.
+- Table delete is hard enough for client assertions: a follow-up table inspect returns `404 not_found` or `410`.
+- Table grant delete is a soft revoke: the grant can remain in `listGrants`, but the same grant id must have `revokedAt` set. Do not assert disappearance.
+- Deployment creation without a connected git/bootstrap source can return a precondition-style 4xx. That verifies SDK error handling, not a deploy bug.
+
+
+## Live QA evidence agents can trust
+
+The SDK behavior documented here reflects live production QA against the AX Hub `test` tenant on 2026-06-08.
+
+- Tenant used for destructive QA: slug `test`, id `cc1e58f1-8e46-4ac7-96c1-190c4cdd5b70`.
+- Go, Java, Kotlin, Python, and Ruby each ran the generated all-operation sweep against 189 backend routes: SDK exceptions `0`, backend 5xx `0`.
+- Go, Java, Kotlin, Python, and Ruby each passed strict destructive DB QA: 22 live steps, 17 assertions, 7 cleanup calls. The flow created an app, env var, table, column, table grant, row, then updated, listed, counted, browsed, deleted, and re-read to prove deletion semantics.
+- Node ran the full production mutation suite and a real app bootstrap/deploy wait. Deployment id `d3a48ce3-0f9c-4bab-aa07-863c31c44460` finished `succeeded`, then the app was deleted permanently.
+
+Do not print tokens. Use short-lived PATs for agent QA and revoke them after the run.
+
+
+## Verification commands
+
+Use local tests for every docs/code change. Run live tests only when you intentionally want destructive QA against `test`.
+
+
+```bash
+ruby -Ilib test/client_test.rb
+
+# Destructive live all-operation sweep, only with a disposable PAT.
+AXHUB_LIVE_ALL_METHODS=1 \
+AXHUB_TOKEN="$AXHUB_TOKEN" \
+AXHUB_LIVE_TENANT_ID="$AXHUB_TENANT_ID" \
+AXHUB_LIVE_TENANT_SLUG="$AXHUB_TENANT_SLUG" \
+ruby test/live_all_operations_e2e_test.rb
+```
+
+## Troubleshooting for agents
+
+- `tenant_id_required`: pass `defaultTenantId` / `AXHUB_TENANT_ID` before calling `apps.create`.
+- `tokenType must be explicit`: set PAT mode when using a PAT. PATs are sent as `X-Api-Key`; JWTs are sent as `Authorization: Bearer`.
+- `slug_taken` or `schema_name_taken`: append a timestamp suffix and retry. Never reuse fixture names in live destructive QA.
+- `permission_denied` / `not_admin`: the SDK is working. The token lacks the role for that route.
+- `precondition_failed` on deploy: connect git or use the app bootstrap flow first.
+- 4xx responses are expected for negative assertions. SDK bugs are unexpected exceptions, response decode failures, or backend 5xx during a valid call.
 
-See `.github/workflows/ci.yml` for the canonical CI commands.
 
 ## Release
 

data/axhub-sdk.gemspec

@@ -21,4 +21,7 @@ Gem::Specification.new do |spec|
     'bug_tracker_uri' => "#{spec.homepage}/issues",
     'rubygems_mfa_required' => 'true'
   }
+
+  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
 end

data/lib/axhub_sdk/data/client.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'dsl/schema'
+require_relative 'dsl/validation'
+require_relative 'errors'
+require_relative 'pagination'
+require_relative 'projection'
+require_relative 'schema_cache'
+require_relative 'where_serializer'
+require_relative 'discover'
+
+module AxHub
+  module Data
+    # Ergonomic data layer: fluent builder + dynamic-table CRUD + offset
+    # pagination (mirrors node index.ts DataClient / TenantDataFactory /
+    # AppDataFactory / DataTableClient).
+    #
+    # Wire paths (EXACTLY as node, via the raw-path transport so row bodies and
+    # the list envelope are returned verbatim, no snake->camel rewriting):
+    #   list / insert         GET|POST          /data/{tenant}/{app}/{table}
+    #   get / update / delete  GET|PATCH|DELETE  /data/{tenant}/{app}/{table}/{id}
+    #   count                 GET               /data/{tenant}/{app}/{table}/_count
+    module_function
+
+    def _encode(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+
+    def _clamp_per_page(value)
+      return nil if value.nil?
+      return 100 unless value.is_a?(Numeric) && value.finite?
+
+      [100, [1, value.to_i].max].min
+    end
+
+    def _reject_legacy_page_options(after, before, direction, _table_name)
+      return if after.nil? && before.nil? && direction.nil?
+
+      raise LegacyCursorError.new(
+        'after/before keyset cursors are not supported by the live AX Hub data API; use cursor/page numeric offset pagination'
+      )
+    end
+
+    def _validate_plain_cursor(cursor, _table_name)
+      if cursor.length > MAX_CURSOR_TOKEN_LENGTH
+        raise InvalidCursorError.new("Cursor token exceeds maximum size (#{MAX_CURSOR_TOKEN_LENGTH} chars)")
+      end
+      if cursor.start_with?('v1:')
+        raise LegacyCursorError.new(
+          'Legacy v1: cursor token is not compatible with AX Hub offset-only pagination; restart pagination without cursor'
+        )
+      end
+      if Data.is_v2_cursor(cursor)
+        raise LegacyCursorError.new(
+          'v2 keyset cursors are not supported by the live AX Hub data API; restart pagination and use the numeric cursor returned by list()'
+        )
+      end
+      unless cursor.match?(/\A-?\d+\z/)
+        raise InvalidCursorError.new('Plain cursor must be a positive integer page or a v2: keyset token')
+      end
+      parsed = cursor.to_i
+      raise InvalidCursorError.new('Plain cursor must be a positive integer page or a v2: keyset token') if parsed < 1
+    end
+
+    def _resolve_offset_page(cursor, page, table_name)
+      unless cursor.nil?
+        _validate_plain_cursor(cursor, table_name)
+        return cursor.to_i
+      end
+      return 1 if page.nil?
+      raise InvalidCursorError.new('page must be a positive integer') unless page.is_a?(Integer) && page >= 1
+
+      page
+    end
+  end
+
+  module Data
+    # Client bound to one {tenant}/{app}/{table} with CRUD + pagination.
+    class DataTableClient
+      attr_reader :schema
+
+      def initialize(client, tenant_slug, app_slug, table_name, schema = nil)
+        @client = client
+        @tenant_slug = tenant_slug
+        @app_slug = app_slug
+        @table_name = table_name
+        @schema = schema
+      end
+
+      def list(where: nil, order_by: nil, select: nil, page: nil, page_size: nil, limit: nil, cursor: nil, after: nil, before: nil, direction: nil)
+        Data.validate_select_columns(@schema, select)
+        Data._reject_legacy_page_options(after, before, direction, @table_name)
+        resolved_page = Data._resolve_offset_page(cursor, page, @table_name)
+        per_page = Data._clamp_per_page(page_size.nil? ? limit : page_size)
+        query = Data.serialize_where(where).dup
+        query['per_page'] = per_page unless per_page.nil?
+        query['page'] = resolved_page if resolved_page != 1
+        sort = Data.serialize_order_by(order_by)
+        query['sort'] = sort if sort && sort != ''
+        serialized_select = Data.serialize_select(select)
+        query['_select'] = serialized_select unless serialized_select.nil?
+        raw = Data.map_where_required('list') { @client.request_raw('GET', _path, query: query) } || {}
+        items = Data.project_rows(raw['items'] || [], select)
+        # mirrors node: current_page falls back to the requested page, has_next
+        # reads the backend `has_more` flag verbatim, has_prev derives client-side.
+        current_page = raw['page'].nil? ? resolved_page : raw['page']
+        has_next = !!(raw['has_more'] || false)
+        has_prev = current_page > 1
+        PaginatedList.new(
+          items: items,
+          next_cursor: has_next ? (current_page + 1).to_s : nil,
+          first_cursor: has_prev ? (current_page - 1).to_s : nil,
+          has_next: has_next,
+          has_prev: has_prev,
+          total_is_exact: false
+        )
+      end
+
+      def list_all(where: nil, order_by: nil, select: nil, page_size: nil, limit: nil, &block)
+        base = { where: where, order_by: order_by, select: select, limit: limit }
+        fetcher = lambda do |p|
+          kwargs = base.reject { |_k, v| v.nil? }
+          kwargs[:cursor] = p[:cursor] unless p[:cursor].nil?
+          ps = p[:page_size].nil? ? page_size : p[:page_size]
+          kwargs[:page_size] = ps unless ps.nil?
+          list(**kwargs)
+        end
+        Data.list_all(fetcher, { page_size: page_size }, &block)
+      end
+
+      def count(where: nil)
+        raw = Data.map_where_required('count') { @client.request_raw('GET', "#{_path}/_count", query: Data.serialize_where(where)) } || {}
+        raw['count']
+      end
+
+      def get(row_id, select: nil)
+        Data.validate_select_columns(@schema, select)
+        serialized_select = Data.serialize_select(select)
+        query = serialized_select.nil? ? {} : { '_select' => serialized_select }
+        row = @client.request_raw('GET', _path(row_id), query: query) || {}
+        Data.project_row(row, select)
+      end
+
+      def insert(row)
+        Data.run_schema_validation(@schema, row, 'insert')
+        @client.request_raw('POST', _path, body: row)
+      end
+
+      def insert_many(rows)
+        rows.each { |row| Data.run_schema_validation(@schema, row, 'insert') }
+        # mirrors node: no bulk endpoint exists, so insertMany loops single
+        # inserts and returns { items, count }.
+        items = rows.map { |row| insert(row) }
+        { 'items' => items, 'count' => items.length }
+      end
+
+      def update(row_id, patch)
+        Data.run_schema_validation(@schema, patch, 'update')
+        @client.request_raw('PATCH', _path(row_id), body: patch)
+      end
+
+      def delete(row_id)
+        @client.request_raw('DELETE', _path(row_id))
+        nil
+      end
+
+      private
+
+      def _path(row_id = nil)
+        base = "/data/#{Data._encode(@tenant_slug)}/#{Data._encode(@app_slug)}/#{Data._encode(@table_name)}"
+        row_id.nil? ? base : "#{base}/#{Data._encode(row_id)}"
+      end
+    end
+
+    class AppDataFactory
+      def initialize(data, tenant_slug, app_slug)
+        @data = data
+        @tenant_slug = tenant_slug
+        @app_slug = app_slug
+      end
+
+      def table(table)
+        @data.table(@tenant_slug, @app_slug, table)
+      end
+
+      def discover(table, fresh: nil, ttl_ms: nil)
+        @data.discover(@tenant_slug, @app_slug, table, fresh: fresh, ttl_ms: ttl_ms)
+      end
+
+      def invalidate_schema(table = nil)
+        if table.nil?
+          @data.invalidate_schema
+        else
+          @data.invalidate_schema(@tenant_slug, @app_slug, table)
+        end
+      end
+    end
+
+    class TenantDataFactory
+      def initialize(data, tenant_slug)
+        @data = data
+        @tenant_slug = tenant_slug
+      end
+
+      def app(app_slug)
+        AppDataFactory.new(@data, @tenant_slug, app_slug)
+      end
+    end
+
+    # Entry point for the ergonomic data layer; holds the per-client schema cache
+    # used by discover() (mirrors node DataClient).
+    class DataClient
+      def initialize(client, schema_cache: nil)
+        @client = client
+        @schema_cache = case schema_cache
+                        when SchemaCache then schema_cache
+                        when Hash then SchemaCache.new(**schema_cache.transform_keys(&:to_sym))
+                        else SchemaCache.new
+                        end
+      end
+
+      def table(tenant_slug, app_slug, table)
+        schema = table.is_a?(DataTableSchema) ? table : nil
+        table_name = table.is_a?(DataTableSchema) ? table.table : table
+        DataTableClient.new(@client, tenant_slug, app_slug, table_name, schema)
+      end
+
+      def scoped(tenant_slug)
+        TenantDataFactory.new(self, tenant_slug)
+      end
+
+      def discover(tenant_slug, app_slug, table, fresh: nil, ttl_ms: nil)
+        key = Data.schema_cache_key(tenant_slug, app_slug, table)
+        schema = @schema_cache.get_or_set(key, fresh: fresh, ttl_ms: ttl_ms) do
+          Data.fetch_discovered_schema(@client, tenant_slug, app_slug, table, fresh: fresh, ttl_ms: ttl_ms)
+        end
+        DataTableClient.new(@client, tenant_slug, app_slug, schema.table, schema)
+      end
+
+      def invalidate_schema(tenant_slug = nil, app_slug = nil, table = nil)
+        if !tenant_slug.nil? && !app_slug.nil? && !table.nil?
+          @schema_cache.invalidate(Data.schema_cache_key(tenant_slug, app_slug, table))
+          return
+        end
+        @schema_cache.invalidate
+      end
+    end
+  end
+end

data/lib/axhub_sdk/data/discover.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'dsl/schema'
+require_relative 'errors'
+
+module AxHub
+  module Data
+    # Runtime schema introspection, with appId-resolution PRIMARY and the slug
+    # /inspect endpoint as a best-effort fallback, plus error normalization
+    # (mirrors node/python discover).
+    #
+    # Primary:  GET /api/v1/apps?tenant_slug=... -> GET /api/v1/apps/{appId}/tables/{table}
+    # Fallback: GET /api/v1/tenants/{t}/apps/{a}/tables/{table}/inspect
+    # Neither endpoint has a generated operation-id, so discover goes through the
+    # raw-path transport. camelize: true here so table_name/tableName both resolve
+    # (inspect payload is metadata, not user row data).
+    APP_LOOKUP_PAGE_SIZE = 100
+    APP_LOOKUP_MAX_PAGES = 10
+    APP_LOOKUP_BUDGET_MS = 5_000
+
+    FORBIDDEN_COLUMN_NAMES = %w[__proto__ constructor prototype].freeze
+    COLUMN_NAME_RE = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    module_function
+
+    def _encode(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+
+    def fetch_discovered_schema(client, tenant_slug, app_slug, table, fresh: nil, ttl_ms: nil)
+      # The appId path is the route the `axhub` CLI uses and is verified to work
+      # with a data-ring PAT (2026-06). The slug `/inspect` route rejects a slug
+      # in the {tenant} path segment on the live backend ("tenant_id 형식이 잘못됐어요",
+      # HTTP 400) — a 400 not a 404, so the old slug-first order never reached the
+      # working path. appId is primary; slug inspect is a best-effort fallback. The
+      # appId error is the meaningful one, so it is what surfaces.
+      begin
+        _fetch_app_id_inspect(client, tenant_slug, app_slug, table)
+      rescue StandardError => err
+        begin
+          _fetch_slug_inspect(client, tenant_slug, app_slug, table)
+        rescue StandardError
+          raise _normalize_discover_error(err, table)
+        end
+      end
+    end
+
+    def _fetch_slug_inspect(client, tenant_slug, app_slug, table)
+      path = "/api/v1/tenants/#{_encode(tenant_slug)}/apps/#{_encode(app_slug)}/tables/#{_encode(table)}/inspect"
+      raw = client.request_raw('GET', path, camelize: true)
+      schema_from_inspect_result(table, raw)
+    end
+
+    def _fetch_app_id_inspect(client, tenant_slug, app_slug, table)
+      app_id = _resolve_app_id(client, tenant_slug, app_slug)
+      raise TableNotFoundError.new("Dynamic data table '#{table}' was not found") if app_id.nil? || app_id.empty?
+
+      path = "/api/v1/apps/#{_encode(app_id)}/tables/#{_encode(table)}"
+      raw = client.request_raw('GET', path, camelize: true)
+      schema_from_inspect_result(table, raw)
+    end
+
+    def _resolve_app_id(client, tenant_slug, app_slug)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0
+      cursor = nil
+      APP_LOOKUP_MAX_PAGES.times do |page|
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000.0 - started_at > APP_LOOKUP_BUDGET_MS
+          raise IntrospectFailedError.new(
+            "app lookup budget exceeded (#{APP_LOOKUP_BUDGET_MS}ms) while searching for slug '#{app_slug}' in tenant '#{tenant_slug}'"
+          )
+        end
+        query = { 'tenant_slug' => tenant_slug, 'limit' => APP_LOOKUP_PAGE_SIZE }
+        query['cursor'] = cursor if cursor
+        raw = client.request_raw('GET', '/api/v1/apps', query: query, camelize: true)
+        raw ||= {}
+        items = raw['items'] || []
+        match = items.find { |app| app['slug'] == app_slug && app['id'].is_a?(String) }
+        return match['id'] if match && match['id']
+
+        # Empty page on the first request means the tenant truly has no apps.
+        return nil if page.zero? && items.empty?
+
+        next_cursor = raw['next_cursor'] || raw['nextCursor']
+        return nil if next_cursor.nil? || next_cursor == ''
+
+        cursor = next_cursor
+      end
+      raise ScanLimitExceededError.new(
+        "App lookup exceeded #{APP_LOOKUP_MAX_PAGES} pages x #{APP_LOOKUP_PAGE_SIZE} apps without finding slug '#{app_slug}'"
+      )
+    end
+
+    def _normalize_discover_error(err, table)
+      return err if err.is_a?(TableNotFoundError) || err.is_a?(IntrospectFailedError) || err.is_a?(ScanLimitExceededError)
+
+      if _not_found?(err)
+        return TableNotFoundError.new(
+          "Dynamic data table '#{table}' was not found",
+          request_id: (err.respond_to?(:request_id) ? err.request_id : nil)
+        )
+      end
+      status = err.respond_to?(:status) ? err.status : nil
+      if status.is_a?(Integer) && status >= 500
+        return IntrospectFailedError.new(
+          "Failed to introspect dynamic data table '#{table}'",
+          status: status,
+          retryable: (err.respond_to?(:retryable) ? !!err.retryable : false),
+          request_id: (err.respond_to?(:request_id) ? err.request_id : nil)
+        )
+      end
+      err
+    end
+
+    def schema_from_inspect_result(table, raw)
+      raw ||= {}
+      columns = raw['columns'] || []
+      shape = {}
+      columns.each do |column|
+        name = column['name']
+        next if FORBIDDEN_COLUMN_NAMES.include?(name)
+        next unless name.is_a?(String) && COLUMN_NAME_RE.match?(name)
+
+        shape[name] = _column_type_to_def(column['type'])
+      end
+      table_name = raw['tableName'] || raw['table_name'] || raw['name'] || table
+      Data.define_schema({ 'table' => table_name, 'columns' => shape })
+    end
+
+    def _column_type_to_def(col_type)
+      case col_type
+      when 'uuid' then 'uuid'
+      when 'int', 'integer', 'bigint' then 'integer'
+      when 'float', 'numeric', 'double precision', 'real' then 'number'
+      when 'bool', 'boolean' then 'boolean'
+      when 'timestamp', 'timestamptz', 'timestamp with time zone' then 'timestamp'
+      when 'json', 'jsonb' then 'json'
+      else 'string' # text / varchar / character varying / unknown -> string
+      end
+    end
+
+    def _not_found?(err)
+      return true if err.is_a?(TableNotFoundError)
+
+      err.is_a?(AxHub::Error) && err.respond_to?(:status) && err.status == 404
+    end
+  end
+end