{
  "schema_version": 1,
  "suite_id": "securities-essential-matching-mix",
  "title": "Essential securities workload matrix for exchange-matching and anonymous point-get profile comparison",
  "status": "ready_to_run_contract_not_evidence",
  "purpose": "Prepare at least ten reusable essential data and workload combinations for write-heavy exchange-matching behavior, hotspot sensitivity, and an anonymized short-transaction point-get profile signal without treating raw tenant identifiers, raw schemas, or raw SQL as product test data. The master canonical TPC-E workload remains the standard reference and is not counted as an essential matching case.",
  "pass_warning": "This suite is an input contract only. It does not prove that any pressure run passed, and it does not claim parity with the anonymous external profile until fresh attempt-root evidence reports the required metrics.",
  "anonymized_external_profile_signal": {
    "profile_ref": "anonymous-short-transaction-point-get-20260609",
    "source_handling": "Only the metric shape is retained. Raw tenant names, raw database names, raw schema names, raw SQL text, and private paths are intentionally excluded.",
    "sql_type_ratio_targets": [
      {
        "sql_type": "Select",
        "observed_share": 0.43,
        "interpretation": "Mostly primary-key or unique-index point lookups that should map to TiKV get rather than coprocessor-heavy scans."
      },
      {
        "sql_type": "general",
        "observed_share": 0.28,
        "interpretation": "Protocol overhead from per-statement StmtPrepare, StmtExecute, and StmtClose behavior. This is not a business SQL family."
      },
      {
        "sql_type": "Update",
        "observed_share": 0.10,
        "interpretation": "Short pessimistic write path with lock_keys pressure."
      },
      {
        "sql_type": "Insert",
        "observed_share": 0.04,
        "interpretation": "Short insert path inside high-commit-rate transactions."
      },
      {
        "sql_type": "Begin",
        "observed_share": 0.03,
        "interpretation": "Short transaction boundary rate."
      },
      {
        "sql_type": "Commit",
        "observed_share": 0.03,
        "interpretation": "Short transaction boundary rate with two-phase commit visibility."
      }
    ],
    "sql_type_ratio_residual": {
      "observed_share": 0.09,
      "interpretation": "Residual anonymized SQL type share outside the six disclosed monitoring buckets. It is intentionally not expanded because raw tenant SQL categories remain private, and the suite treats it as residual profile distance rather than rounding."
    },
    "latency_reference_p99_ms": {
      "Select_avg": 6.7,
      "Select_max": 9.8,
      "Update_avg": 3.0,
      "Update_max": 4.6,
      "Insert_avg": 2.8,
      "Insert_max": 3.3,
      "Commit_avg": 14.1,
      "Commit_max": 49.2,
      "general_avg": 0.3,
      "general_max": 0.4
    },
    "p999_contract": "Every essential run must capture Select, general, Update, Insert, Begin, and Commit p999 when Clinic or Prometheus exposes the buckets. The external signal above supplies p99 values for Select, Update, Insert, Commit, and general only, so p999 and Begin latency are observed comparison fields rather than pass thresholds in this suite.",
    "kv_path_targets": {
      "dominant_kv_command": "get",
      "write_lock_signal": "lock_keys",
      "transaction_signal": "commit",
      "batch_get_expectation": "low",
      "distsql_coprocessor_expectation": "near_zero_for_point_get_cases"
    }
  },
  "current_product_support": {
    "executable_workload_mix_values": [
      "tpce",
      "exchange_matching"
    ],
    "master_standard_tpce_reference": {
      "workload_mix": "tpce",
      "workload_profile": {
        "name": "canonical"
      },
      "role": "Standard master baseline for canonical TPC-E securities behavior. It is a reference outside this essential exchange-matching case matrix."
    },
    "exchange_matching_ce_family_target": {
      "Trade-Order": 0.80,
      "Trade-Status": 0.05,
      "Trade-Lookup": 0.05,
      "Market-Watch": 0.05,
      "Security-Detail": 0.05
    },
    "current_sql_protocol_behavior": {
      "driver_surface": "database/sql ExecContext and QueryContext with text SQL execution and multi-statement read batching where supported",
      "not_modeled_by_current_pressure_spec": [
        "per-statement StmtPrepare to StmtExecute to StmtClose behavior",
        "prepared statement cache reuse policy",
        "non-prepared plan cache toggle as a workload contract"
      ],
      "equivalence_boundary": "The anonymous point-get cases can compare SQL type, KV path, and latency shape, but they cannot reproduce the external general metric until protocol-mode support is added."
    }
  },
  "environment_binding_template": {
    "profile": "essential",
    "attempt_root_pattern": "runs/essential-matching-mix/<testcase_id>/<attempt_id>",
    "remote_attempt_root_pattern": "runs/essential-matching-mix/<testcase_id>/<attempt_id>",
    "object_store_uri_pattern": "s3://<essential-bucket>/essential-matching-mix/<testcase_id>/<attempt_id>",
    "global_sort_uri_pattern": "s3://<essential-bucket>/essential-matching-mix/<testcase_id>/<attempt_id>/global-sort",
    "br_storage_uri_pattern": "s3://<essential-bucket>/essential-matching-mix/<testcase_id>/<attempt_id>/br",
    "metadata_path_pattern": "runs/essential-matching-mix/<testcase_id>/<attempt_id>/run-profile.manifest.json",
    "restore_policy": "restore_before_case_from_prepare_end_br",
    "prepare_ops": [
      "generate",
      "import",
      "add-index",
      "backup"
    ],
    "source_kind": "generated_tpce",
    "source_format": "csv",
    "import_executor": "tidb_import_into_file",
    "csv_object_target_bytes": 536870912,
    "load_unit_size": 1000,
    "random_capacity_budget": "lcg64-64bit"
  },
  "default_measurement_contract": {
    "duration_seconds": 300,
    "warmup_seconds": 60,
    "cooldown_seconds": 30,
    "progress_interval_secs": 30,
    "warmup_excluded_from_measurement": true,
    "restore_baseline": "prepare_end_br",
    "case_result_status": "observed_or_blocked_only",
    "formal_pass_requires": [
      "fresh init, prepare, run, and cleanup attempt-root evidence",
      "zero blocked runtime statements",
      "run receipt and global closeout generated by the same committed binary",
      "attempt-root guard success"
    ]
  },
  "required_report_fields": [
    "testcase_id",
    "target_size",
    "database",
    "source_object_count",
    "catalog_table_count",
    "prepared_table_count",
    "imported_non_empty_table_count",
    "empty_prepare_tables",
    "restore_policy",
    "restore_receipt",
    "warmup_seconds",
    "measurement_seconds",
    "concurrency",
    "pressure_node_count",
    "pressure_worker_count",
    "sql_pool_size",
    "ce_worker_limit",
    "workload_mix",
    "workload_profile",
    "observed_distribution_summary",
    "executed_statement_count",
    "statement_qps",
    "blocked_statement_count",
    "blocked_root_cause",
    "sql_type_qps_select",
    "sql_type_qps_general",
    "sql_type_qps_update",
    "sql_type_qps_insert",
    "sql_type_qps_begin",
    "sql_type_qps_commit",
    "sql_type_p99_ms_select",
    "sql_type_p999_ms_select",
    "sql_type_p99_ms_general",
    "sql_type_p999_ms_general",
    "sql_type_p99_ms_update",
    "sql_type_p999_ms_update",
    "sql_type_p99_ms_insert",
    "sql_type_p999_ms_insert",
    "sql_type_p99_ms_begin",
    "sql_type_p999_ms_begin",
    "sql_type_p99_ms_commit",
    "sql_type_p999_ms_commit",
    "protocol_stmt_prepare_qps",
    "protocol_stmt_execute_qps",
    "protocol_stmt_close_qps",
    "protocol_query_qps",
    "plan_cache_hit_qps",
    "plan_cache_miss_qps",
    "kv_get_qps",
    "kv_batch_get_qps",
    "kv_lock_keys_qps",
    "kv_commit_qps",
    "kv_rollback_qps",
    "distsql_coprocessor_p99_ms",
    "tidb_cpu",
    "tidb_memory_rss",
    "tidb_active_connections",
    "tikv_cpu",
    "tikv_grpc_rate",
    "tikv_write_stall_max",
    "pd_region_symptoms",
    "slow_query_qps",
    "error_qps",
    "pressure_node_cpu",
    "pressure_node_memory",
    "pressure_node_network",
    "bottleneck_interpretation",
    "external_profile_fit_assessment"
  ],
  "case_matrix": [
    {
      "testcase_id": "essential-e01-10g-exchange-c064",
      "family": "exchange_matching_low_concurrency",
      "objective": "Establish the low-concurrency exchange-matching baseline without consuming an essential case on standard TPC-E.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 64,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "canonical"
        },
        "pressure_node_count": 2,
        "per_node_sql_pool_size": 32,
        "per_node_ce_worker_limit": 64
      },
      "observation_focus": [
        "Trade-Order dominated CE mix at low concurrency",
        "baseline exchange-matching p99 and p999 latency",
        "baseline TiKV get, lock_keys, and commit split"
      ],
      "external_profile_fit_assessment": "partial_business_mix_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e02-10g-exchange-c128",
      "family": "exchange_matching_baseline",
      "objective": "Measure the write-heavy exchange-matching CE mix at low concurrency and compare its SQL type distribution with the anonymous short-transaction profile.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 128,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "canonical"
        },
        "pressure_node_count": 2,
        "per_node_sql_pool_size": 64,
        "per_node_ce_worker_limit": 128
      },
      "observation_focus": [
        "Trade-Order dominated CE mix",
        "Update, Insert, Begin, and Commit shares",
        "lock_keys and commit rate"
      ],
      "external_profile_fit_assessment": "partial_business_mix_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e03-10g-exchange-c256",
      "family": "exchange_matching_medium_concurrency",
      "objective": "Raise exchange-matching pressure on the 10G dataset and compare the SQL type and KV command shape against the lower-concurrency exchange cases.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 256,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "canonical"
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 96,
        "per_node_ce_worker_limit": 192
      },
      "observation_focus": [
        "statement QPS before the c512 step",
        "select p999 under moderate write-heavy pressure",
        "commit p999 and lock_keys growth"
      ],
      "external_profile_fit_assessment": "partial_business_mix_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e04-10g-exchange-c512",
      "family": "exchange_matching_capacity",
      "objective": "Increase exchange-matching pressure on the 10G dataset and determine whether p999 select or commit latency becomes the first limit.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 512,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "canonical"
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 128,
        "per_node_ce_worker_limit": 256
      },
      "observation_focus": [
        "statement QPS ceiling",
        "select p999 under write-heavy pressure",
        "commit p999 and TiKV lock pressure"
      ],
      "external_profile_fit_assessment": "partial_business_mix_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e05-10g-exchange-hot-account-c256",
      "family": "hotspot_sensitivity",
      "objective": "Bias account lineage inside the write-heavy mix to expose row-lock and commit sensitivity without hardcoding SQL literals.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 256,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "hot-account",
          "hot_dimensions": [
            "account"
          ],
          "hot_set_size": 1024,
          "skew_percent": 80,
          "skew_function": "hotset_uniform",
          "lineage_seed": 1105
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 96,
        "per_node_ce_worker_limit": 192
      },
      "observation_focus": [
        "lock_keys p999",
        "commit p999",
        "hot account observed distribution"
      ],
      "external_profile_fit_assessment": "contention_probe_not_direct_profile_fit"
    },
    {
      "testcase_id": "essential-e06-10g-exchange-hot-symbol-c256",
      "family": "point_get_hotset",
      "objective": "Bias symbol and security lineage to compare point-get locality with the anonymous profile's get-dominated read path.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 256,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "hot-symbol",
          "hot_dimensions": [
            "symbol",
            "security"
          ],
          "hot_set_size": 2048,
          "skew_percent": 80,
          "skew_function": "hotset_uniform",
          "lineage_seed": 1106
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 96,
        "per_node_ce_worker_limit": 192
      },
      "observation_focus": [
        "kv_get_qps",
        "distsql coprocessor p99",
        "select p99 and p999"
      ],
      "external_profile_fit_assessment": "partial_read_path_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e07-10g-exchange-pointget-fit-c384",
      "family": "anonymous_profile_fit",
      "objective": "Use a mixed customer, account, symbol, and security hot set to approximate short point-get locality while preserving securities transaction causality.",
      "dataset": {
        "target_size": "10G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 384,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "anonymous-pointget-fit",
          "hot_dimensions": [
            "customer",
            "account",
            "symbol",
            "security"
          ],
          "hot_set_size": 4096,
          "skew_percent": 70,
          "skew_function": "hotset_uniform",
          "lineage_seed": 1107
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 128,
        "per_node_ce_worker_limit": 256
      },
      "observation_focus": [
        "SQL type shares against anonymous profile",
        "kv_get dominance",
        "protocol general gap"
      ],
      "external_profile_fit_assessment": "best_current_executable_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e08-50g-exchange-c256",
      "family": "exchange_matching_scale_baseline",
      "objective": "Establish a 50G exchange-matching scale baseline because prior securities pressure samples did not demonstrate low-millisecond p99 behavior.",
      "dataset": {
        "target_size": "50G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 256,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "canonical"
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 128,
        "per_node_ce_worker_limit": 256
      },
      "observation_focus": [
        "dataset scale effect on exchange-matching p99",
        "dataset scale effect on exchange-matching p999",
        "TiKV get, lock_keys, commit, and coprocessor balance"
      ],
      "external_profile_fit_assessment": "partial_business_mix_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e09-50g-exchange-c512",
      "family": "exchange_matching_scale",
      "objective": "Measure exchange-matching behavior on 50G data and compare the SQL type and KV command shape with the 10G exchange-matching case.",
      "dataset": {
        "target_size": "50G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 512,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "canonical"
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 128,
        "per_node_ce_worker_limit": 256
      },
      "observation_focus": [
        "scale impact on statement QPS",
        "select p999 under write-heavy pressure",
        "commit and lock_keys pressure"
      ],
      "external_profile_fit_assessment": "partial_business_mix_fit_protocol_gap_expected"
    },
    {
      "testcase_id": "essential-e10-50g-exchange-pointget-fit-c512",
      "family": "anonymous_profile_fit_scale",
      "objective": "Run the best current executable anonymous point-get fit at 50G scale and make the remaining protocol-mode and latency gaps explicit.",
      "dataset": {
        "target_size": "50G",
        "csv_object_target_bytes": 536870912
      },
      "pressure": {
        "duration_seconds": 300,
        "warmup_seconds": 60,
        "cooldown_seconds": 30,
        "progress_interval_secs": 30,
        "concurrency": 512,
        "workload_mix": "exchange_matching",
        "workload_profile": {
          "name": "anonymous-pointget-fit",
          "hot_dimensions": [
            "customer",
            "account",
            "symbol",
            "security"
          ],
          "hot_set_size": 8192,
          "skew_percent": 70,
          "skew_function": "hotset_uniform",
          "lineage_seed": 1110
        },
        "pressure_node_count": 4,
        "per_node_sql_pool_size": 128,
        "per_node_ce_worker_limit": 256
      },
      "observation_focus": [
        "external profile fit at larger scale",
        "protocol general gap",
        "p999 select and commit gap"
      ],
      "external_profile_fit_assessment": "best_current_executable_fit_protocol_gap_expected"
    }
  ],
  "non_executable_gap_to_close_before_exact_external_profile": [
    {
      "gap": "protocol_prepare_execute_close_mode",
      "reason": "The anonymous external signal's general metric is produced by per-statement prepared-statement protocol overhead, while the current pressure spec has no protocol mode switch for that behavior.",
      "minimum_required_capability": "Expose a manifest-visible runtime protocol profile that can choose text protocol, prepare-per-statement, prepared statement reuse, and plan-cache policy without changing securities transaction semantics."
    }
  ]
}