table structure docs are made

common/src/proto/komp_ac.table_script.rs

@@ -1,21 +1,70 @@
 // This file is @generated by prost-build.
+/// Request to create or update a script bound to a specific table and column.
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PostTableScriptRequest {
+    /// Required. The metadata ID from table_definitions.id that identifies the
+    /// table this script belongs to. The table must exist; its schema determines
+    /// where referenced tables/columns are validated and where dependencies are stored.
     #[prost(int64, tag = "1")]
     pub table_definition_id: i64,
+    /// Required. The target column in the target table that this script computes.
+    /// Must be an existing user-defined column in that table (not a system column).
+    /// System columns are reserved: "id", "deleted", "created_at".
+    /// The column's data type must NOT be one of the prohibited target types:
+    ///    BIGINT, DATE, TIMESTAMPTZ
+    /// Note: BOOLEAN targets are allowed (values are converted to Steel #true/#false).
     #[prost(string, tag = "2")]
     pub target_column: ::prost::alloc::string::String,
+    /// Required. The script in the Steel DSL (S-expression style).
+    /// Syntax requirements:
+    ///    - Non-empty, must start with '('
+    ///    - Balanced parentheses
+    ///
+    /// Referencing data:
+    ///    - Structured table/column access (enforces link constraints):
+    ///        (steel_get_column "table_name" "column_name")
+    ///        (steel_get_column_with_index "table_name" index "column_name")
+    ///        • index must be a non-negative integer literal
+    ///        • self-references are allowed without links
+    ///        • other tables require an explicit link from the source table
+    ///          (table_definition_links) or the request fails
+    ///    - Raw SQL access (no link required, but still validated):
+    ///        (steel_query_sql "SELECT ...")
+    ///        • Basic checks disallow operations that imply prohibited types,
+    ///          e.g., EXTRACT(…), DATE_PART(…), ::DATE, ::TIMESTAMPTZ, ::BIGINT, CAST(…)
+    ///    - Self variable access in transformed scripts:
+    ///        (get-var "column_name") is treated as referencing the current table
+    ///
+    /// Math operations:
+    ///    - The script is transformed by steel_decimal; supported math forms include:
+    ///      +, -, *, /, ^, **, pow, sqrt, >, <, =, >=, <=, min, max, abs, round,
+    ///      ln, log, log10, exp, sin, cos, tan
+    ///    - Columns of the following types CANNOT be used inside math expressions:
+    ///      BIGINT, TEXT, BOOLEAN, DATE, TIMESTAMPTZ
+    ///
+    /// Dependency tracking and cycles:
+    ///    - Dependencies are extracted from steel_get_column(_with_index), get-var,
+    ///      and steel_query_sql and stored in script_dependencies with context
+    ///    - Cycles across tables are rejected (self-dependency is allowed)
     #[prost(string, tag = "3")]
     pub script: ::prost::alloc::string::String,
+    /// Optional. Free-text description stored alongside the script (no functional effect).
     #[prost(string, tag = "4")]
     pub description: ::prost::alloc::string::String,
 }
+/// Response after creating or updating a script.
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TableScriptResponse {
+    /// The ID of the script record in table_scripts (new or existing on upsert).
     #[prost(int64, tag = "1")]
     pub id: i64,
+    /// Human-readable warnings concatenated into a single string. Possible messages:
+    ///   - Warning if the script references itself (may affect first population)
+    ///   - Count of raw SQL queries present
+    ///   - Info about number of structured linked-table accesses
+    ///   - Warning if many dependencies may affect performance
     #[prost(string, tag = "2")]
     pub warnings: ::prost::alloc::string::String,
 }
@@ -30,6 +79,18 @@ pub mod table_script_client {
     )]
     use tonic::codegen::*;
     use tonic::codegen::http::Uri;
+    /// Manages column-computation scripts for user-defined tables.
+    /// Each script belongs to a single table (table_definition_id) and populates
+    /// exactly one target column in that table. The server:
+    /// - Validates script syntax (non-empty, balanced parentheses, starts with '(')
+    /// - Validates the target column (exists, not a system column, allowed type)
+    /// - Validates column/type usage inside math expressions
+    /// - Validates referenced tables/columns against the schema
+    /// - Enforces link constraints for structured access (see notes below)
+    /// - Analyzes dependencies and prevents cycles across the schema
+    /// - Transforms the script to decimal-safe math (steel_decimal)
+    /// - Upserts into table_scripts and records dependencies in script_dependencies
+    /// The whole operation is transactional.
     #[derive(Debug, Clone)]
     pub struct TableScriptClient<T> {
         inner: tonic::client::Grpc<T>,
@@ -110,6 +171,23 @@ pub mod table_script_client {
             self.inner = self.inner.max_encoding_message_size(limit);
             self
         }
+        /// Create or update a script for a specific table and target column.
+        ///
+        /// Behavior:
+        /// - Fetches the table by table_definition_id (must exist)
+        /// - Validates "script" (syntax), "target_column" (exists and type rules),
+        ///   and all referenced tables/columns (must exist in same schema)
+        /// - Validates math operations: prohibits using certain data types in math
+        /// - Enforces link constraints for structured table access:
+        ///    • Allowed always: self-references (same table)
+        ///    • Structured access via steel_get_column / steel_get_column_with_index
+        ///      requires an explicit link in table_definition_links
+        ///    • Raw SQL access via steel_query_sql is permitted (still validated)
+        /// - Detects and rejects circular dependencies across all scripts in the schema
+        ///   (self-references are allowed and not treated as cycles)
+        /// - Transforms the script to decimal-safe operations (steel_decimal)
+        /// - UPSERTS into table_scripts on (table_definitions_id, target_column)
+        ///   and saves a normalized dependency list into script_dependencies
         pub async fn post_table_script(
             &mut self,
             request: impl tonic::IntoRequest<super::PostTableScriptRequest>,
@@ -154,6 +232,23 @@ pub mod table_script_server {
     /// Generated trait containing gRPC methods that should be implemented for use with TableScriptServer.
     #[async_trait]
     pub trait TableScript: std::marker::Send + std::marker::Sync + 'static {
+        /// Create or update a script for a specific table and target column.
+        ///
+        /// Behavior:
+        /// - Fetches the table by table_definition_id (must exist)
+        /// - Validates "script" (syntax), "target_column" (exists and type rules),
+        ///   and all referenced tables/columns (must exist in same schema)
+        /// - Validates math operations: prohibits using certain data types in math
+        /// - Enforces link constraints for structured table access:
+        ///    • Allowed always: self-references (same table)
+        ///    • Structured access via steel_get_column / steel_get_column_with_index
+        ///      requires an explicit link in table_definition_links
+        ///    • Raw SQL access via steel_query_sql is permitted (still validated)
+        /// - Detects and rejects circular dependencies across all scripts in the schema
+        ///   (self-references are allowed and not treated as cycles)
+        /// - Transforms the script to decimal-safe operations (steel_decimal)
+        /// - UPSERTS into table_scripts on (table_definitions_id, target_column)
+        ///   and saves a normalized dependency list into script_dependencies
         async fn post_table_script(
             &self,
             request: tonic::Request<super::PostTableScriptRequest>,
@@ -162,6 +257,18 @@ pub mod table_script_server {
             tonic::Status,
         >;
     }
+    /// Manages column-computation scripts for user-defined tables.
+    /// Each script belongs to a single table (table_definition_id) and populates
+    /// exactly one target column in that table. The server:
+    /// - Validates script syntax (non-empty, balanced parentheses, starts with '(')
+    /// - Validates the target column (exists, not a system column, allowed type)
+    /// - Validates column/type usage inside math expressions
+    /// - Validates referenced tables/columns against the schema
+    /// - Enforces link constraints for structured access (see notes below)
+    /// - Analyzes dependencies and prevents cycles across the schema
+    /// - Transforms the script to decimal-safe math (steel_decimal)
+    /// - Upserts into table_scripts and records dependencies in script_dependencies
+    /// The whole operation is transactional.
     #[derive(Debug)]
     pub struct TableScriptServer<T> {
         inner: Arc<T>,