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

// 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.
service TableScript {
  // 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
  rpc PostTableScript(PostTableScriptRequest) returns (TableScriptResponse);
}

// Request to create or update a script bound to a specific table and column.
message 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.
  int64 table_definition_id = 1;

  // 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).
  string target_column = 2;

  // 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)
  string script = 3;

  // Optional. Free-text description stored alongside the script (no functional effect).
  string description = 4;
}

// Response after creating or updating a script.
message TableScriptResponse {
  // The ID of the script record in table_scripts (new or existing on upsert).
  int64 id = 1;

  // 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
  string warnings = 2;
}