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

import "common.proto";

// Introspects the physical PostgreSQL table for a given logical table
// (defined in table_definitions) and returns its column structure.
// The server validates that:
// - The profile (schema) exists in `schemas`
// - The table is defined for that profile in `table_definitions`
// It then queries information_schema for the physical table and returns
// normalized column metadata. If the physical table is missing despite
// a definition, the response may contain an empty `columns` list.
service TableStructureService {
  // Return the physical column list (name, normalized data_type,
  // nullability, primary key flag) for a table in a profile.
  //
  // Behavior:
  // - NOT_FOUND if profile doesn't exist in `schemas`
  // - NOT_FOUND if table 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 empty list if the table is validated but has no visible
  //   columns in information_schema (e.g., physical table missing)
  rpc GetTableStructure(GetTableStructureRequest)
      returns (TableStructureResponse);
}

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

  // Required. Table name within the profile. Must exist in `table_definitions`
  // for the given profile. The physical table is then introspected via
  // information_schema.
  string table_name = 2;
}

// Response with the ordered list of columns (by ordinal position).
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;
}