// common/proto/table_structure.proto
syntax = "proto3";
package komp_ac.table_structure;

import "common.proto";

// Introspects the physical PostgreSQL tables for one or more logical tables
// (defined in table_definitions) and returns their column structures.
// The server validates that:
// - The profile (schema) exists in `schemas`
// - Every table is defined for that profile in `table_definitions`
// It then queries information_schema for the physical tables and returns
// normalized column metadata.
service TableStructureService {
  // Return the physical column list (name, normalized data_type,
  // nullability, primary key flag) for one or more tables in a profile.
  //
  // Behavior:
  // - NOT_FOUND if profile doesn't exist in `schemas`
  // - NOT_FOUND if any table is not defined for that profile in `table_definitions`
  // - Queries information_schema.columns ordered by ordinal position
  // - Normalizes data_type text (details under TableColumn.data_type)
  // - Returns an error if any validated table has no visible columns in
  //   information_schema (e.g., physical table missing)
  rpc GetTableStructure(GetTableStructureRequest) returns (GetTableStructureResponse);
}

// Request identifying the profile (schema) and tables to inspect.
message GetTableStructureRequest {
  // Required. Profile (PostgreSQL schema) name. Must exist in `schemas`.
  string profile_name = 1;

  // Required. Table names within the profile. Each must exist in
  // `table_definitions` for the given profile. The physical tables are then
  // introspected via information_schema.
  repeated string table_names = 2;
}

// Batched response keyed by table name.
message GetTableStructureResponse {
  // Per-table physical column lists keyed by requested table name.
  map<string, TableStructureResponse> table_structures = 1;
}

// Response with the ordered list of columns (by ordinal position) for one table.
message TableStructureResponse {
  // Columns of the physical table, including system columns (id, deleted,
  // created_at), user-defined columns, and any foreign-key columns such as
  // "<linked_table>_id". May be empty if the physical table is missing.
  repeated TableColumn columns = 1;
}

// One physical column entry as reported by information_schema.
message TableColumn {
  // Column name exactly as defined in PostgreSQL.
  string name = 1;

  // Normalized data type string derived from information_schema:
  // - VARCHAR(n) when udt_name='varchar' with character_maximum_length
  // - CHAR(n) when udt_name='bpchar' with character_maximum_length
  // - NUMERIC(p,s) when udt_name='numeric' with precision and scale
  // - NUMERIC(p) when udt_name='numeric' with precision only
  // - <TYPE>[] for array types (udt_name starting with '_', e.g., INT[] )
  // - Otherwise UPPER(udt_name), e.g., TEXT, BIGINT, TIMESTAMPTZ
  // Examples: "TEXT", "BIGINT", "VARCHAR(255)", "TIMESTAMPTZ", "NUMERIC(14,4)"
  string data_type = 2;

  // True if information_schema reports the column as nullable.
  bool is_nullable = 3;

  // True if the column is part of the table's PRIMARY KEY.
  // Typically true for the "id" column created by the system.
  bool is_primary_key = 4;
}