quonfig 0.0.6 → 0.0.8

data/test/integration/test_telemetry.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 #
 # AUTO-GENERATED from integration-test-data/tests/eval/telemetry.yaml.
-# Regenerate with `bundle exec ruby scripts/generate_integration_tests.rb`.
+# Regenerate with:
+#   cd integration-test-data/generators && npm run generate -- --target=ruby
+# Source: integration-test-data/generators/src/targets/ruby.ts
 # Do NOT edit by hand — changes will be overwritten.
 
 require 'test_helper'
@@ -14,101 +16,141 @@ class TestTelemetry < Minitest::Test
 
   # reason is STATIC for config with no targeting rules
   def test_reason_is_static_for_config_with_no_targeting_rules
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.string"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.string", "type" => "CONFIG", "value" => "hello.world", "value_type" => "string", "count" => 1, "reason" => 1, "selected_value" => {"string" => "hello.world"}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # reason is STATIC for feature flag with only ALWAYS_TRUE rules
   def test_reason_is_static_for_feature_flag_with_only_always_true_rules
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["always.true"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "always.true", "type" => "FEATURE_FLAG", "value" => true, "value_type" => "bool", "count" => 1, "reason" => 1, "selected_value" => {"bool" => true}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # reason is TARGETING_MATCH when config has targeting rules but evaluation falls through
   def test_reason_is_targeting_match_when_config_has_targeting_rules_but_evaluation_falls_through
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["my-test-key"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "my-test-key", "type" => "CONFIG", "value" => "my-test-value", "value_type" => "string", "count" => 1, "reason" => 2, "selected_value" => {"string" => "my-test-value"}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 1}}], endpoint: "/api/v1/telemetry")
   end
 
   # reason is TARGETING_MATCH when a targeting rule matches
   def test_reason_is_targeting_match_when_a_targeting_rule_matches
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["feature-flag.integer"]}, contexts: {"user" => {"key" => "michael"}})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "feature-flag.integer", "type" => "FEATURE_FLAG", "value" => 5, "value_type" => "int", "count" => 1, "reason" => 2, "selected_value" => {"int" => 5}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # reason is SPLIT for weighted value evaluation
   def test_reason_is_split_for_weighted_value_evaluation
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["feature-flag.weighted"]}, contexts: {"user" => {"tracking_id" => "92a202f2"}})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "feature-flag.weighted", "type" => "FEATURE_FLAG", "value" => 2, "value_type" => "int", "count" => 1, "reason" => 3, "selected_value" => {"int" => 2}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0, "weighted_value_index" => 2}}], endpoint: "/api/v1/telemetry")
   end
 
   # reason is TARGETING_MATCH for feature flag fallthrough with targeting rules
   def test_reason_is_targeting_match_for_feature_flag_fallthrough_with_targeting_rules
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["feature-flag.integer"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "feature-flag.integer", "type" => "FEATURE_FLAG", "value" => 3, "value_type" => "int", "count" => 1, "reason" => 2, "selected_value" => {"int" => 3}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 1}}], endpoint: "/api/v1/telemetry")
   end
 
   # evaluation summary deduplicates identical evaluations
   def test_evaluation_summary_deduplicates_identical_evaluations
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.string", "brand.new.string", "brand.new.string", "brand.new.string", "brand.new.string"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.string", "type" => "CONFIG", "value" => "hello.world", "value_type" => "string", "count" => 5, "reason" => 1, "selected_value" => {"string" => "hello.world"}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # evaluation summary creates separate counters for different rules of same config
   def test_evaluation_summary_creates_separate_counters_for_different_rules_of_same_config
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["feature-flag.integer"], "keys_without_context" => ["feature-flag.integer"]}, contexts: {"user" => {"key" => "michael"}})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "feature-flag.integer", "type" => "FEATURE_FLAG", "value" => 5, "value_type" => "int", "count" => 1, "reason" => 2, "selected_value" => {"int" => 5}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}, {"key" => "feature-flag.integer", "type" => "FEATURE_FLAG", "value" => 3, "value_type" => "int", "count" => 1, "reason" => 2, "selected_value" => {"int" => 3}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 1}}], endpoint: "/api/v1/telemetry")
   end
 
   # evaluation summary groups by config key
   def test_evaluation_summary_groups_by_config_key
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.string", "always.true"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.string", "type" => "CONFIG", "value" => "hello.world", "value_type" => "string", "count" => 1, "reason" => 1, "selected_value" => {"string" => "hello.world"}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}, {"key" => "always.true", "type" => "FEATURE_FLAG", "value" => true, "value_type" => "bool", "count" => 1, "reason" => 1, "selected_value" => {"bool" => true}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # selectedValue wraps string correctly
   def test_selectedvalue_wraps_string_correctly
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.string"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.string", "type" => "CONFIG", "value" => "hello.world", "value_type" => "string", "count" => 1, "reason" => 1, "selected_value" => {"string" => "hello.world"}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # selectedValue wraps boolean correctly
   def test_selectedvalue_wraps_boolean_correctly
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.boolean"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.boolean", "type" => "CONFIG", "value" => false, "value_type" => "bool", "count" => 1, "reason" => 1, "selected_value" => {"bool" => false}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # selectedValue wraps int correctly
   def test_selectedvalue_wraps_int_correctly
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.int"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.int", "type" => "CONFIG", "value" => 123, "value_type" => "int", "count" => 1, "reason" => 1, "selected_value" => {"int" => 123}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # selectedValue wraps double correctly
   def test_selectedvalue_wraps_double_correctly
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.double"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "brand.new.double", "type" => "CONFIG", "value" => 123.99, "value_type" => "double", "count" => 1, "reason" => 1, "selected_value" => {"double" => 123.99}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # selectedValue wraps string list correctly
   def test_selectedvalue_wraps_string_list_correctly
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["my-string-list-key"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, [{"key" => "my-string-list-key", "type" => "CONFIG", "value" => ["a", "b", "c"], "value_type" => "string_list", "count" => 1, "reason" => 1, "selected_value" => {"stringList" => ["a", "b", "c"]}, "summary" => {"config_row_index" => 0, "conditional_value_index" => 0}}], endpoint: "/api/v1/telemetry")
   end
 
   # context shape merges fields across multiple records
   def test_context_shape_merges_fields_across_multiple_records
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:context_shape, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :context_shape, [{"user" => {"name" => "alice", "age" => 30}}, {"user" => {"name" => "bob", "score" => 9.5}, "team" => {"name" => "engineering"}}], contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :context_shape, [{"name" => "user", "field_types" => {"name" => 2, "age" => 1, "score" => 4}}, {"name" => "team", "field_types" => {"name" => 2}}], endpoint: "/api/v1/context-shapes")
   end
 
   # example contexts deduplicates by key value
   def test_example_contexts_deduplicates_by_key_value
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:example_contexts, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :example_contexts, [{"user" => {"key" => "user-123", "name" => "alice"}}, {"user" => {"key" => "user-123", "name" => "bob"}}], contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :example_contexts, {"user" => {"key" => "user-123", "name" => "alice"}}, endpoint: "/api/v1/telemetry")
   end
 
   # telemetry disabled emits nothing
   def test_telemetry_disabled_emits_nothing
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {"collect_evaluation_summaries" => false, "context_upload_mode" => ":none"})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["brand.new.string"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, nil, endpoint: "/api/v1/telemetry")
   end
 
   # shapes only mode reports shapes but not examples
   def test_shapes_only_mode_reports_shapes_but_not_examples
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:context_shape, {"context_upload_mode" => ":shape_only"})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :context_shape, {"user" => {"name" => "alice", "key" => "alice-123"}}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :context_shape, [{"name" => "user", "field_types" => {"name" => 2, "key" => 2}}], endpoint: "/api/v1/context-shapes")
   end
 
   # log level evaluations are excluded from telemetry
   def test_log_level_evaluations_are_excluded_from_telemetry
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:evaluation_summary, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :evaluation_summary, {"keys" => ["log-level.prefab.criteria_evaluator"]}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :evaluation_summary, nil, endpoint: "/api/v1/telemetry")
   end
 
   # empty context produces no context telemetry
   def test_empty_context_produces_no_context_telemetry
-    skip("telemetry aggregator integration not yet wired in sdk-ruby (qfg-dk6.x)")
+    aggregator = IntegrationTestHelpers.build_aggregator(:context_shape, {})
+    IntegrationTestHelpers.feed_aggregator(aggregator, :context_shape, {}, contexts: {})
+    IntegrationTestHelpers.assert_aggregator_post(aggregator, :context_shape, nil, endpoint: "/api/v1/context-shapes")
   end
 end

data/test/test_client_telemetry.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+# Verifies that Quonfig::Client#get feeds every evaluation into the
+# telemetry reporter's evaluation_summaries aggregator.
+class TestClientTelemetry < Minitest::Test
+  CONFIG_KEY = 'my.flag'
+
+  class FakeHttpConnection
+    FakeResponse = Struct.new(:status)
+    attr_reader :posts
+    def initialize; @posts = []; end
+    def post(path, body); @posts << [path, body]; FakeResponse.new(200); end
+  end
+
+  # Plain ConfigResponse-shaped hash (matches Datadir.to_config_response).
+  def make_config(key:, value:, type: 'string', criteria: nil)
+    {
+      'id' => 'cid-abc',
+      'key' => key,
+      'type' => 'config',
+      'valueType' => type,
+      'sendToClientSdk' => false,
+      'default' => {
+        'rules' => [
+          {
+            'criteria' => criteria || [{ 'operator' => 'ALWAYS_TRUE' }],
+            'value' => { 'type' => type, 'value' => value }
+          }
+        ]
+      },
+      'environment' => nil
+    }
+  end
+
+  def make_client_with_telemetry(store)
+    client = Quonfig::Client.new(Quonfig::Options.new, store: store)
+
+    # The store-injection path skips initialize_telemetry by design (it's
+    # for test/bootstrap mode), so we attach the reporter + aggregators
+    # here explicitly to exercise the record path.
+    summaries_agg = Quonfig::Telemetry::EvaluationSummariesAggregator.new(max_keys: 100)
+    shape_agg = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 100)
+    example_agg = Quonfig::Telemetry::ExampleContextsAggregator.new(max_contexts: 100)
+
+    options = Quonfig::Options.new(
+      sdk_key: 'qf_sk_dev_abc_deadbeef',
+      environment: 'development',
+      api_urls: ['https://primary.example.com'],
+      enable_sse: false,
+      enable_polling: false,
+      on_init_failure: Quonfig::Options::ON_INITIALIZATION_FAILURE::RETURN
+    ).tap { |o| o.instance_variable_set(:@telemetry_destination, 'https://t.example.com') }
+
+    fake_conn = FakeHttpConnection.new
+    reporter = Quonfig::Telemetry::TelemetryReporter.new(
+      options: options,
+      instance_hash: client.instance_hash,
+      context_shape_aggregator: shape_agg,
+      example_contexts_aggregator: example_agg,
+      evaluation_summaries_aggregator: summaries_agg,
+      http_connection: fake_conn
+    )
+    client.instance_variable_set(:@telemetry_reporter, reporter)
+
+    [client, reporter, summaries_agg, fake_conn]
+  end
+
+  def test_get_pushes_evaluation_into_summaries_aggregator
+    store = Quonfig::ConfigStore.new
+    store.set(CONFIG_KEY, make_config(key: CONFIG_KEY, value: 'hello'))
+
+    client, _reporter, summaries_agg, _conn = make_client_with_telemetry(store)
+    client.get(CONFIG_KEY, Quonfig::NO_DEFAULT_PROVIDED, 'user' => { 'key' => 'u1' })
+
+    event = summaries_agg.drain_event
+    refute_nil event, 'expected an evaluation_summaries event after Client#get'
+
+    summary = event['summaries']['summaries'][0]
+    assert_equal CONFIG_KEY, summary['key']
+    assert_equal 'config',   summary['type']
+
+    counter = summary['counters'][0]
+    assert_equal 'cid-abc',                 counter['configId']
+    assert_equal 0,                         counter['conditionalValueIndex']
+    assert_equal 1,                         counter['count']
+    assert_equal({ 'string' => 'hello' },   counter['selectedValue'])
+    # ALWAYS_TRUE on the only rule → STATIC (1)
+    assert_equal 1, counter['reason']
+  end
+
+  def test_get_with_targeting_rule_reports_targeting_match
+    store = Quonfig::ConfigStore.new
+    store.set(CONFIG_KEY, make_config(
+      key: CONFIG_KEY,
+      value: 'targeted',
+      criteria: [{
+        'operator' => 'PROP_IS_ONE_OF',
+        'propertyName' => 'user.tier',
+        'valueToMatch' => { 'type' => 'string_list', 'value' => ['pro'] }
+      }]
+    ))
+
+    client, _reporter, summaries_agg, _conn = make_client_with_telemetry(store)
+    client.get(CONFIG_KEY, 'fallback', 'user' => { 'key' => 'u1', 'tier' => 'pro' })
+
+    counter = summaries_agg.drain_event['summaries']['summaries'][0]['counters'][0]
+    # Config has a non-ALWAYS_TRUE rule → TARGETING_MATCH (2)
+    assert_equal 2, counter['reason']
+  end
+
+  def test_repeated_get_increments_count_not_new_counters
+    store = Quonfig::ConfigStore.new
+    store.set(CONFIG_KEY, make_config(key: CONFIG_KEY, value: 'hello'))
+
+    client, _reporter, summaries_agg, _conn = make_client_with_telemetry(store)
+    3.times { client.get(CONFIG_KEY, Quonfig::NO_DEFAULT_PROVIDED, 'user' => { 'key' => 'u1' }) }
+
+    counters = summaries_agg.drain_event['summaries']['summaries'][0]['counters']
+    assert_equal 1, counters.size, 'same evaluation should dedupe into one counter'
+    assert_equal 3, counters[0]['count']
+  end
+
+  def test_missing_key_does_not_record_evaluation
+    store = Quonfig::ConfigStore.new
+    client, _reporter, summaries_agg, _conn = make_client_with_telemetry(store)
+
+    client.get('does.not.exist', 'fallback')
+    assert_nil summaries_agg.drain_event
+  end
+end

data/test/test_context.rb

@@ -90,7 +90,10 @@ class TestContext < Minitest::Test
       team: { key: 't1' }
     )
 
-    assert_equal 'team:t1|user:u1', context.grouped_key
+    # Mirrors sdk-node groupedKey: just the key/trackingId values, sorted
+    # and pipe-joined. Contexts without a key/trackingId contribute
+    # nothing — so the example aggregator drops anonymous contexts.
+    assert_equal 't1|u1', context.grouped_key
   end
 
   def test_named_context_lookup_returns_namedcontext

data/test/test_context_shape.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class TestContextShape < Minitest::Test
+  class Email; end
+
+  def test_field_type_number
+    [
+      [1, 1],
+      [99_999_999_999_999_999_999_999_999_999_999_999_999_999_999, 1],
+      [-99_999_999_999_999_999_999_999_999_999_999_999_999_999_999, 1],
+
+      ['a', 2],
+      ['99999999999999999999999999999999999999999999', 2],
+
+      [1.0, 4],
+      [99_999_999_999_999_999_999_999_999_999_999_999_999_999_999.0, 4],
+      [-99_999_999_999_999_999_999_999_999_999_999_999_999_999_999.0, 4],
+
+      [true, 5],
+      [false, 5],
+
+      [[], 10],
+      [[1, 2, 3], 10],
+      [%w[a b c], 10],
+
+      # Unknown / custom types fall back to "string" (2).
+      [Email.new, 2]
+    ].each do |value, expected|
+      actual = Quonfig::Telemetry::ContextShape.field_type_number(value)
+
+      refute_nil actual, "Expected a value for input: #{value.inspect}"
+      assert_equal expected, actual, "Expected #{expected} for #{value.inspect}"
+    end
+  end
+end

data/test/test_context_shape_aggregator.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class TestContextShapeAggregator < Minitest::Test
+  CONTEXT_1 = Quonfig::Context.new(
+    'user' => {
+      'name' => 'user-name',
+      'email' => 'user.email',
+      'age' => 42.5
+    },
+    'subscription' => {
+      'plan' => 'advanced',
+      'free' => false
+    }
+  ).freeze
+
+  CONTEXT_2 = Quonfig::Context.new(
+    'user' => {
+      'name' => 'other-user-name',
+      'dob' => '2020-01-01'
+    },
+    'device' => {
+      'name' => 'device-name',
+      'os' => 'os-name',
+      'version' => 3
+    }
+  ).freeze
+
+  CONTEXT_3 = Quonfig::Context.new(
+    'subscription' => {
+      'plan' => 'pro',
+      'trial' => true
+    }
+  ).freeze
+
+  def test_push_respects_max_shapes
+    aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 9)
+
+    aggregator.push(CONTEXT_1)
+    aggregator.push(CONTEXT_2)
+    assert_equal 9, aggregator.data.size
+
+    # At the limit — further shapes get dropped.
+    aggregator.push(CONTEXT_3)
+    assert_equal 9, aggregator.data.size
+
+    tuples = aggregator.data.to_a
+    assert_includes tuples, ['user', 'name', 2]
+    assert_includes tuples, ['user', 'email', 2]
+    assert_includes tuples, ['user', 'age', 4]
+    assert_includes tuples, ['subscription', 'plan', 2]
+    assert_includes tuples, ['subscription', 'free', 5]
+    assert_includes tuples, ['device', 'name', 2]
+    assert_includes tuples, ['device', 'os', 2]
+    assert_includes tuples, ['device', 'version', 1]
+  end
+
+  def test_prepare_data_folds_tuples_and_clears
+    aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 1000)
+
+    aggregator.push(CONTEXT_1)
+    aggregator.push(CONTEXT_2)
+    aggregator.push(CONTEXT_3)
+
+    data = aggregator.prepare_data
+
+    assert_equal %w[user subscription device].sort, data.keys.sort
+
+    assert_equal(
+      { 'name' => 2, 'email' => 2, 'dob' => 2, 'age' => 4 },
+      data['user']
+    )
+
+    assert_equal(
+      { 'plan' => 2, 'trial' => 5, 'free' => 5 },
+      data['subscription']
+    )
+
+    assert_equal(
+      { 'name' => 2, 'os' => 2, 'version' => 1 },
+      data['device']
+    )
+
+    assert_equal [], aggregator.data.to_a
+  end
+
+  def test_drain_event_emits_api_telemetry_wire_shape
+    aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 1000)
+    aggregator.push(Quonfig::Context.new('user' => { 'key' => 'abc', 'age' => 42 }))
+
+    event = aggregator.drain_event
+
+    refute_nil event
+    assert event.key?('contextShapes')
+    shapes = event['contextShapes']['shapes']
+    assert_equal 1, shapes.size
+    assert_equal 'user', shapes[0]['name']
+    assert_equal({ 'key' => 2, 'age' => 1 }, shapes[0]['fieldTypes'])
+  end
+
+  def test_drain_event_nil_when_empty
+    aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 1000)
+    assert_nil aggregator.drain_event
+  end
+
+  def test_push_dedupes_identical_shapes
+    aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 1000)
+
+    aggregator.push(Quonfig::Context.new('user' => { 'key' => 'a', 'age' => 1 }))
+    aggregator.push(Quonfig::Context.new('user' => { 'key' => 'b', 'age' => 2 }))
+
+    # Same (name, key, type) tuples should have been deduped by the Set.
+    assert_equal 2, aggregator.data.size
+  end
+
+  def test_accepts_plain_hash_context
+    aggregator = Quonfig::Telemetry::ContextShapeAggregator.new(max_shapes: 1000)
+
+    aggregator.push('user' => { 'key' => 'abc', 'is_admin' => true })
+
+    event = aggregator.drain_event
+    refute_nil event
+    assert_equal({ 'key' => 2, 'is_admin' => 5 }, event['contextShapes']['shapes'][0]['fieldTypes'])
+  end
+end

data/test/test_datadir.rb

@@ -147,7 +147,9 @@ class TestDatadir < Minitest::Test
   end
 
   def test_raises_when_no_environment
-    err = assert_raises(ArgumentError) { Quonfig::Datadir.load_envelope(@tmpdir, nil) }
+    err = assert_raises(Quonfig::Errors::MissingEnvironmentError) do
+      Quonfig::Datadir.load_envelope(@tmpdir, nil)
+    end
     assert_match(/Environment required for datadir mode/, err.message)
   end
 
@@ -159,7 +161,9 @@ class TestDatadir < Minitest::Test
   end
 
   def test_raises_when_environment_not_in_workspace
-    err = assert_raises(ArgumentError) { Quonfig::Datadir.load_envelope(@tmpdir, 'NotAnEnv') }
+    err = assert_raises(Quonfig::Errors::InvalidEnvironmentError) do
+      Quonfig::Datadir.load_envelope(@tmpdir, 'NotAnEnv')
+    end
     assert_match(/Environment "NotAnEnv" not found/, err.message)
     assert_match(/Production/, err.message)
   end