v0.5.10 is here, we removed the manualf debug and default in the canvas library and cleaned client from it

Cargo.lock

@@ -493,11 +493,12 @@ checksum = "d71b6127be86fdcfddb610f7182ac57211d4b18a3e9c82eb2d17662f2227ad6a"
 
 [[package]]
 name = "canvas"
-version = "0.5.0"
+version = "0.5.10"
 dependencies = [
  "anyhow",
  "async-trait",
  "crossterm",
+ "derivative",
  "once_cell",
  "ratatui",
  "regex",
@@ -584,7 +585,7 @@ dependencies = [
 
 [[package]]
 name = "client"
-version = "0.5.0"
+version = "0.5.10"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -601,6 +602,8 @@ dependencies = [
  "rstest",
  "serde",
  "serde_json",
+ "strum 0.27.2",
+ "strum_macros 0.27.2",
  "time",
  "tokio",
  "tokio-test",
@@ -635,7 +638,7 @@ dependencies = [
 
 [[package]]
 name = "common"
-version = "0.5.0"
+version = "0.5.10"
 dependencies = [
  "prost 0.13.5",
  "prost-build 0.14.1",
@@ -936,6 +939,17 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "derivative"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fcc3dd5e9e9c0b295d6e1e4d811fb6f157d5ffd784b8d202fc62eac8035a770b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
 [[package]]
 name = "digest"
 version = "0.10.7"
@@ -1959,11 +1973,11 @@ checksum = "08ab2867e3eeeca90e844d1940eab391c9dc5228783db2ed999acbc0a9ed375a"
 
 [[package]]
 name = "matchers"
-version = "0.1.0"
+version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8263075bb86c5a1b1427b5ae862e8889656f126e9f77c484496e8b47cf5c5558"
+checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9"
 dependencies = [
- "regex-automata 0.1.10",
+ "regex-automata",
 ]
 
 [[package]]
@@ -2080,12 +2094,11 @@ dependencies = [
 
 [[package]]
 name = "nu-ansi-term"
-version = "0.46.0"
+version = "0.50.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "77a8165726e8236064dbb45459242600304b42a5ea24ee2948e18e023bf7ba84"
+checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5"
 dependencies = [
- "overload",
+ "windows-sys 0.60.2",
- "winapi",
 ]
 
 [[package]]
@@ -2243,12 +2256,6 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
-[[package]]
-name = "overload"
-version = "0.1.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b15813163c1d831bf4a13c3610c05c0d03b39feb07f7e09fa234dac9b15aaf39"
-
 [[package]]
 name = "ownedbytes"
 version = "0.9.0"
@@ -2756,7 +2763,7 @@ dependencies = [
  "itertools 0.13.0",
  "lru",
  "paste",
- "strum",
+ "strum 0.26.3",
  "unicode-segmentation",
  "unicode-truncate",
  "unicode-width 0.2.0",
@@ -2810,17 +2817,8 @@ checksum = "b544ef1b4eac5dc2db33ea63606ae9ffcfac26c1416a2806ae0bf5f56b201191"
 dependencies = [
  "aho-corasick",
  "memchr",
- "regex-automata 0.4.9",
+ "regex-automata",
- "regex-syntax 0.8.5",
+ "regex-syntax",
-]
-
-[[package]]
-name = "regex-automata"
-version = "0.1.10"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6c230d73fb8d8c1b9c0b3135c5142a8acee3a0558fb8db5cf1cb65f8d7862132"
-dependencies = [
- "regex-syntax 0.6.29",
 ]
 
 [[package]]
@@ -2831,15 +2829,9 @@ checksum = "809e8dc61f6de73b46c85f4c96486310fe304c434cfa43669d7b40f711150908"
 dependencies = [
  "aho-corasick",
  "memchr",
- "regex-syntax 0.8.5",
+ "regex-syntax",
 ]
 
-[[package]]
-name = "regex-syntax"
-version = "0.6.29"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f162c6dd7b008981e4d40210aca20b4bd0f9b60ca9271061b07f78537722f2e1"
-
 [[package]]
 name = "regex-syntax"
 version = "0.8.5"
@@ -3100,7 +3092,7 @@ checksum = "1c107b6f4780854c8b126e228ea8869f4d7b71260f962fefb57b996b8959ba6b"
 
 [[package]]
 name = "search"
-version = "0.5.0"
+version = "0.5.10"
 dependencies = [
  "anyhow",
  "common",
@@ -3199,7 +3191,7 @@ dependencies = [
 
 [[package]]
 name = "server"
-version = "0.5.0"
+version = "0.5.10"
 dependencies = [
  "anyhow",
  "bcrypt",
@@ -3210,6 +3202,7 @@ dependencies = [
  "futures",
  "jsonwebtoken",
  "lazy_static",
+ "once_cell",
  "prost 0.13.5",
  "prost-build 0.14.1",
  "prost-types 0.13.5",
@@ -3234,6 +3227,7 @@ dependencies = [
  "tonic",
  "tonic-reflection",
  "tracing",
+ "tracing-subscriber",
  "uuid",
  "validator",
 ]
@@ -3756,9 +3750,15 @@ version = "0.26.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
 dependencies = [
- "strum_macros",
+ "strum_macros 0.26.4",
 ]
 
+[[package]]
+name = "strum"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af23d6f6c1a224baef9d3f61e287d2761385a5b88fdab4eb4c6f11aeb54c4bcf"
+
 [[package]]
 name = "strum_macros"
 version = "0.26.4"
@@ -3772,6 +3772,18 @@ dependencies = [
  "syn 2.0.104",
 ]
 
+[[package]]
+name = "strum_macros"
+version = "0.27.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7695ce3845ea4b33927c055a39dc438a45b059f7c1b3d91d38d10355fb8cbca7"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.104",
+]
+
 [[package]]
 name = "subtle"
 version = "2.6.1"
@@ -3830,7 +3842,7 @@ dependencies = [
  "fnv",
  "once_cell",
  "plist",
- "regex-syntax 0.8.5",
+ "regex-syntax",
  "serde",
  "serde_derive",
  "serde_json",
@@ -3936,7 +3948,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d60769b80ad7953d8a7b2c70cdfe722bbcdcac6bccc8ac934c40c034d866fc18"
 dependencies = [
  "byteorder",
- "regex-syntax 0.8.5",
+ "regex-syntax",
  "utf8-ranges",
 ]
 
@@ -4318,9 +4330,9 @@ checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
 
 [[package]]
 name = "tracing"
-version = "0.1.41"
+version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "784e0ac535deb450455cbfa28a6f0df145ea1bb7ae51b821cf5e7927fdcfbdd0"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
  "log",
  "pin-project-lite",
@@ -4330,9 +4342,9 @@ dependencies = [
 
 [[package]]
 name = "tracing-attributes"
-version = "0.1.30"
+version = "0.1.31"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "81383ab64e72a7a8b8e13130c49e3dab29def6d0c7d76a03087b3cf71c5c6903"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -4341,9 +4353,9 @@ dependencies = [
 
 [[package]]
 name = "tracing-core"
-version = "0.1.34"
+version = "0.1.36"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b9d12581f227e93f094d3af2ae690a574abb8a2b9b7a96e7cfe9647b2b617678"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
 dependencies = [
  "once_cell",
  "valuable",
@@ -4362,14 +4374,14 @@ dependencies = [
 
 [[package]]
 name = "tracing-subscriber"
-version = "0.3.19"
+version = "0.3.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8189decb5ac0fa7bc8b96b7cb9b2701d60d48805aca84a238004d665fcc4008"
+checksum = "2f30143827ddab0d256fd843b7a66d164e9f271cfa0dde49142c5ca0ca291f1e"
 dependencies = [
  "matchers",
  "nu-ansi-term",
  "once_cell",
- "regex",
+ "regex-automata",
  "sharded-slab",
  "smallvec",
  "thread_local",

Cargo.toml

@@ -5,7 +5,7 @@ resolver = "2"
 [workspace.package]
 # TODO: idk how to do the name, fix later
 # name = "komp_ac"
-version = "0.5.0"
+version = "0.5.10"
 edition = "2021"
 license = "GPL-3.0-or-later"
 authors = ["Filip Priečinský <filippriec@gmail.com>"]

README.md

@@ -16,10 +16,5 @@ cargo watch -x 'run --package client -- client'
 
 Client with tracing:
 ```
-ENABLE_TRACING=1 RUST_LOG=client=debug cargo watch -x 'run --package client -- client'
-```
-
-Client with debug that cant be traced
-```
 cargo run --package client --features ui-debug -- client
 ```

common/.gitignore

@@ -0,0 +1 @@
+docs/

common/Makefile

@@ -0,0 +1,11 @@
+DOC_OUT := docs/grpc_reference.html
+
+.PHONY: docs
+
+docs:
+	@echo "Generating gRPC documentation..."
+	mkdir -p $(dir $(DOC_OUT))
+	protoc \
+	  --doc_out=html,index.html:$(dir $(DOC_OUT)) \
+	  --proto_path=proto proto/*.proto
+	@echo "✅ Docs written to $(DOC_OUT)"

common/build.rs

@@ -20,6 +20,18 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             ".komp_ac.table_validation.TableValidationResponse",
             "#[derive(serde::Serialize, serde::Deserialize)]",
         )
+        .type_attribute(
+            ".komp_ac.table_validation.PatternRule",
+            "#[derive(serde::Serialize, serde::Deserialize)]",
+        )
+        .type_attribute(
+            ".komp_ac.table_validation.PatternRules",
+            "#[derive(serde::Serialize, serde::Deserialize)]",
+        )
+        .type_attribute(
+            ".komp_ac.table_validation.CustomFormatter",
+            "#[derive(serde::Serialize, serde::Deserialize)]",
+        )
         .type_attribute(
             ".komp_ac.table_validation.UpdateFieldValidationRequest",
             "#[derive(serde::Serialize, serde::Deserialize)]",

common/proto/common.proto

@@ -3,5 +3,9 @@ syntax = "proto3";
 package komp_ac.common;
 
 message Empty {}
-message CountResponse { int64 count = 1; }
+message CountResponse {
-message PositionRequest { int64 position = 1; }
+  int64 count = 1;
+}
+message PositionRequest {
+  int64 position = 1;
+}

common/proto/table_definition.proto

@@ -4,56 +4,136 @@ package komp_ac.table_definition;
 
 import "common.proto";
 
+// The TableDefinition service manages the entire lifecycle of user-defined
+// tables (stored as both metadata and physical PostgreSQL tables) inside
+// logical "profiles" (schemas). Each table has stored structure, links, and
+// validation rules.
 service TableDefinition {
+  // Creates a new table (and schema if missing) with system columns,
+  // linked-table foreign keys, user-defined columns, and optional indexes.
+  // Also inserts metadata and default validation rules. Entirely transactional.
   rpc PostTableDefinition(PostTableDefinitionRequest) returns (TableDefinitionResponse);
+
+  // Lists all profiles (schemas) and their tables with declared dependencies.
+  // This provides a tree-like overview of table relationships.
   rpc GetProfileTree(komp_ac.common.Empty) returns (ProfileTreeResponse);
+
+  // Drops a table and its metadata, then deletes the profile if it becomes empty.
   rpc DeleteTable(DeleteTableRequest) returns (DeleteTableResponse);
 }
 
+// A single link to another table within the same profile (schema).
 message TableLink {
+  // Name of an existing table within the same profile to link to.
+  // For each link, a "<linked>_id" column is created on the new table.
+  // That column references "<linked>"(id) and adds an index automatically.
   string linked_table_name = 1;
+
+  // If true, the generated foreign key column is NOT NULL.
+  // Otherwise the column allows NULL.
+  // Duplicate links to the same target table in one request are rejected.
   bool required = 2;
 }
 
+// Defines the input for creating a new table definition.
 message PostTableDefinitionRequest {
+  // Table name to create inside the target profile.
+  // Must be lowercase, alphanumeric with underscores,
+  // start with a letter, and be <= 63 chars.
+  // Forbidden names: "id", "deleted", "created_at", or ending in "_id".
   string table_name = 1;
+
+  // List of links (foreign keys) to existing tables in the same profile.
+  // Each will automatically get a "<linked>_id" column and an index.
   repeated TableLink links = 2;
+
+  // List of user-defined columns (adds to system/id/fk columns).
   repeated ColumnDefinition columns = 3;
+
+  // List of column names to be indexed (must match existing user-defined columns).
+  // Indexes can target only user-defined columns; system columns ("id", "deleted",
+  // "created_at") and automatically generated foreign key ("*_id") columns already
+  // have indexes. Requests trying to index those columns are rejected.
   repeated string indexes = 4;
+
+  // Name of profile (Postgres schema) where the table will be created.
+  // Same naming rules as table_name; cannot collide with reserved schemas
+  // like "public", "information_schema", or ones starting with "pg_".
   string profile_name = 5;
 }
 
+// Describes one user-defined column for a table.
 message ColumnDefinition {
+  // Column name that follows the same validation rules as table_name.
+  // Must be lowercase, start with a letter, no uppercase characters,
+  // and cannot be "id", "deleted", "created_at", or end with "_id".
   string name = 1;
+
+  // Logical column type. Supported values (case-insensitive):
+  //   TEXT / STRING
+  //   BOOLEAN
+  //   TIMESTAMP / TIMESTAMPTZ / TIME
+  //   MONEY (= NUMERIC(14,4))
+  //   INTEGER / INT
+  //   BIGINTEGER / BIGINT
+  //   DATE
+  //   DECIMAL(p,s) → NUMERIC(p,s)
+  // DECIMAL args must be integers (no sign, no dot, no leading zeros);
+  // s ≤ p and p ≥ 1.
   string field_type = 2;
 }
 
+// Response after table creation (success + DDL preview).
 message TableDefinitionResponse {
+  // True if all DB changes and metadata inserts succeeded.
   bool success = 1;
+
+  // The actual SQL executed: CREATE TABLE + CREATE INDEX statements.
   string sql = 2;
 }
 
+// Describes the tree of all profiles and their tables.
 message ProfileTreeResponse {
+  // Table entry in a profile.
   message Table {
+    // Internal ID from table_definitions.id (metadata record).
     int64 id = 1;
+
+    // Table name within the profile (schema).
     string name = 2;
+
+    // Other tables this one references (based on link definitions only).
     repeated string depends_on = 3;
   }
 
+  // Profile (schema) entry.
   message Profile {
+    // Name of the schema/profile (as stored in `schemas.name`).
     string name = 1;
+
+    // All tables in that schema and their dependencies.
     repeated Table tables = 2;
   }
 
+  // All profiles in the system.
   repeated Profile profiles = 1;
 }
 
+// Request to delete one table definition entirely.
 message DeleteTableRequest {
+  // Profile (schema) name owning the table (must exist).
   string profile_name = 1;
+
+  // Table to drop (must exist in the profile).
+  // Executes DROP TABLE "profile"."table" CASCADE and then removes metadata.
   string table_name = 2;
 }
 
+// Response after table deletion.
 message DeleteTableResponse {
+  // True if table and metadata were successfully deleted in one transaction.
   bool success = 1;
+
+  // Human-readable summary of what was removed.
   string message = 2;
 }

common/proto/table_script.proto

@@ -1,18 +1,101 @@
+// 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;
 }

common/proto/table_structure.proto

@@ -1,25 +1,69 @@
-// proto/table_structure.proto
+// common/proto/table_structure.proto
 syntax = "proto3";
 package komp_ac.table_structure;
 
 import "common.proto";
 
-message GetTableStructureRequest {
+// Introspects the physical PostgreSQL table for a given logical table
-  string profile_name = 1; // e.g., "default"
+// (defined in table_definitions) and returns its column structure.
-  string table_name = 2;   // e.g., "2025_adresar6"
+// 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;
-  string data_type = 2; // e.g., "TEXT", "BIGINT", "VARCHAR(255)", "TIMESTAMPTZ"
+
+  // 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;
 }
-
-service TableStructureService {
-  rpc GetTableStructure (GetTableStructureRequest) returns (TableStructureResponse);
-}

common/proto/table_validation.proto

@@ -22,7 +22,8 @@ message FieldValidation {
   // Current: only CharacterLimits. More rules can be added later.
   CharacterLimits limits = 10;
   // Future expansion:
-  // PatternRules pattern = 11;
+  PatternRules pattern = 11; // Validation 2
+  optional CustomFormatter formatter = 14; // Validation 4 – custom formatting logic
   DisplayMask mask = 3;
   // ExternalValidation external = 13;
   // CustomFormatter formatter = 14;
@@ -57,13 +58,45 @@ message DisplayMask {
   optional string template_char = 3; // e.g., "_"
 }
 
+// One position‑based validation rule, similar to CharacterFilter + PositionRange
+message PatternRule {
+  // Range descriptor: how far the rule applies
+  // Examples:
+  //  - "0"        → Single position 0
+  //  - "0-3"      → Range 0..3 inclusive
+  //  - "from:5"   → From position 5 onward
+  //  - "0,2,5"    → Multiple discrete positions
+  string range = 1;
+
+  // Character filter type, case‑insensitive keywords:
+  // "ALPHABETIC", "NUMERIC", "ALPHANUMERIC",
+  // "ONEOF(<chars>)", "EXACT(:)", "CUSTOM(<name>)"
+  string filter = 2;
+}
+
+message CustomFormatter {
+  // Formatter type identifier; handled client‑side.
+  // Examples: "PSCFormatter", "PhoneFormatter", "CreditCardFormatter", "DateFormatter"
+  string type = 1;
+
+  // Optional free‑text note or parameters (e.g. locale, pattern)
+  optional string description = 2;
+}
+
+// Collection of pattern rules for one field
+message PatternRules {
+  // All rules that make up the validation logic
+  repeated PatternRule rules = 1;
+
+  // Optional human‑readable description for UI/debug purposes
+  optional string description = 2;
+}
+
 // Service to fetch validations for a table
 service TableValidationService {
-  rpc GetTableValidation(GetTableValidationRequest)
+  rpc GetTableValidation(GetTableValidationRequest) returns (TableValidationResponse);
-      returns (TableValidationResponse);
 
-  rpc UpdateFieldValidation(UpdateFieldValidationRequest)
+  rpc UpdateFieldValidation(UpdateFieldValidationRequest) returns (UpdateFieldValidationResponse);
-      returns (UpdateFieldValidationResponse);
 }
 
 message UpdateFieldValidationRequest {

common/proto/tables_data.proto

@@ -5,67 +5,220 @@ package komp_ac.tables_data;
 import "common.proto";
 import "google/protobuf/struct.proto";
 
+// Read and write row data for user-defined tables inside profiles (schemas).
+// Operations are performed against the physical PostgreSQL table that
+// corresponds to the logical table definition and are scoped by profile
+// (schema). Deletions are soft (set deleted = true). Typed binding and
+// script-based validation are enforced consistently.
 service TablesData {
+  // Insert a new row into a table with strict type binding and script validation.
+  //
+  // Behavior:
+  // - Validates that profile (schema) exists and table is defined for it
+  // - Validates provided columns exist (user-defined or allowed system/FK columns)
+  // - For columns targeted by scripts in this table, the client MUST provide the
+  //   value, and it MUST equal the script’s calculated value (compared type-safely)
+  // - Binds values with correct SQL types, rejects invalid formats/ranges
+  // - Inserts the row and returns the new id; queues search indexing (best effort)
+  // - If the physical table is missing but the definition exists, returns INTERNAL
   rpc PostTableData(PostTableDataRequest) returns (PostTableDataResponse);
+
+  // Update existing row data with strict type binding and script validation.
+  //
+  // Behavior:
+  // - Validates profile and table, and that the record exists
+  // - If request data is empty, returns success without changing the row
+  // - For columns targeted by scripts:
+  //    • If included in update, provided value must equal the script result
+  //    • If not included, update must not cause the script result to differ
+  //      from the current stored value; otherwise FAILED_PRECONDITION is returned
+  // - Binds values with correct SQL types; rejects invalid formats/ranges
+  // - Updates the row and returns the id; queues search indexing (best effort)
   rpc PutTableData(PutTableDataRequest) returns (PutTableDataResponse);
+
+  // Soft-delete a single record (sets deleted = true) if it exists and is not already deleted.
+  //
+  // Behavior:
+  // - Validates profile and table definition
+  // - Updates only rows with deleted = false
+  // - success = true means a row was actually changed; false means nothing to delete
+  // - If the physical table is missing but the definition exists, returns INTERNAL
   rpc DeleteTableData(DeleteTableDataRequest) returns (DeleteTableDataResponse);
+
+  // Fetch a single non-deleted row by id as textified values.
+  //
+  // Behavior:
+  // - Validates profile and table definition
+  // - Returns all columns as strings (COALESCE(col::TEXT, '') AS col)
+  //   including: id, deleted, all user-defined columns, and FK columns
+  //   named "<linked_table>_id" for each table link
+  // - Fails with NOT_FOUND if record does not exist or is soft-deleted
+  // - If the physical table is missing but the definition exists, returns INTERNAL
   rpc GetTableData(GetTableDataRequest) returns (GetTableDataResponse);
+
+  // Count non-deleted rows in a table.
+  //
+  // Behavior:
+  // - Validates profile and table definition
+  // - Returns komp_ac.common.CountResponse.count with rows where deleted = FALSE
+  // - If the physical table is missing but the definition exists, returns INTERNAL
   rpc GetTableDataCount(GetTableDataCountRequest) returns (komp_ac.common.CountResponse);
+
+  // Fetch the N-th non-deleted row by id order (1-based), then return its full data.
+  //
+  // Behavior:
+  // - position is 1-based (position = 1 → first row by id ASC with deleted = FALSE)
+  // - Returns NOT_FOUND if position is out of bounds
+  // - Otherwise identical to GetTableData for the selected id
   rpc GetTableDataByPosition(GetTableDataByPositionRequest) returns (GetTableDataResponse);
 }
 
+// Insert a new row.
 message PostTableDataRequest {
+  // Required. Profile (PostgreSQL schema) name that owns the table.
+  // Must exist in the schemas table.
   string profile_name = 1;
+
+  // Required. Logical table (definition) name within the profile.
+  // Must exist in table_definitions for the given profile.
   string table_name = 2;
+
+  // Required. Key-value data for columns to insert.
+  //
+  // Allowed keys:
+  // - User-defined columns from the table definition
+  // - System/FK columns:
+  //    • "deleted" (BOOLEAN), optional; default FALSE if not provided
+  //    • "<linked_table>_id" (BIGINT) for each table link
+  //
+  // Type expectations by SQL type:
+  // - TEXT: string value; empty string is treated as NULL
+  // - BOOLEAN: bool value
+  // - TIMESTAMPTZ: ISO 8601/RFC 3339 string (parsed to TIMESTAMPTZ)
+  // - INTEGER: number with no fractional part and within i32 range
+  // - BIGINT: number with no fractional part and within i64 range
+  // - NUMERIC(p,s): string representation only; empty string becomes NULL
+  //   (numbers for NUMERIC are rejected to avoid precision loss)
+  //
+  // Script validation rules:
+  // - If a script exists for a target column, that column MUST be present here,
+  //   and its provided value MUST equal the script’s computed value (type-aware
+  //   comparison, e.g., decimals are compared numerically).
+  //
+  // Notes:
+  // - Unknown/invalid column names are rejected
+  // - Some application-specific validations may apply (e.g., max length for
+  //   certain fields like "telefon")
   map<string, google.protobuf.Value> data = 3;
 }
 
+// Insert response.
 message PostTableDataResponse {
+  // True if the insert succeeded.
   bool success = 1;
+
+  // Human-readable message.
   string message = 2;
+
+  // The id of the inserted row.
   int64 inserted_id = 3;
 }
 
+// Update an existing row.
 message PutTableDataRequest {
+  // Required. Profile (schema) name.
   string profile_name = 1;
+
+  // Required. Table name within the profile.
   string table_name = 2;
+
+  // Required. Id of the row to update.
   int64 id = 3;
+
+  // Required. Columns to update (same typing rules as PostTableDataRequest.data).
+  //
+  // Special script rules:
+  // - If a script targets column X and X is included here, the value for X must
+  //   equal the script’s result (type-aware).
+  // - If X is not included here but the update would cause the script’s result
+  //   to change compared to the current stored value, the update is rejected with
+  //   FAILED_PRECONDITION, instructing the caller to include X explicitly.
+  //
+  // Passing an empty map results in a no-op success response.
   map<string, google.protobuf.Value> data = 4;
 }
 
+// Update response.
 message PutTableDataResponse {
+  // True if the update succeeded (or no-op on empty data).
   bool success = 1;
+
+  // Human-readable message.
   string message = 2;
+
+  // The id of the updated row.
   int64 updated_id = 3;
 }
 
+// Soft-delete a single row.
 message DeleteTableDataRequest {
+  // Required. Profile (schema) name.
   string profile_name = 1;
+
+  // Required. Table name within the profile.
   string table_name = 2;
+
+  // Required. Row id to soft-delete.
   int64 record_id = 3;
 }
 
+// Soft-delete response.
 message DeleteTableDataResponse {
+  // True if a row was marked deleted (id existed and was not already deleted).
   bool success = 1;
 }
 
+// Fetch a single non-deleted row by id.
 message GetTableDataRequest {
+  // Required. Profile (schema) name.
   string profile_name = 1;
+
+  // Required. Table name within the profile.
   string table_name = 2;
+
+  // Required. Id of the row to fetch.
   int64 id = 3;
 }
 
+// Row payload: all columns returned as strings.
 message GetTableDataResponse {
+  // Map of column_name → stringified value for:
+  // - id, deleted
+  // - all user-defined columns from the table definition
+  // - FK columns named "<linked_table>_id" for each table link
+  //
+  // All values are returned as TEXT via col::TEXT and COALESCEed to empty string
+  // (NULL becomes ""). The row is returned only if deleted = FALSE.
   map<string, string> data = 1;
 }
 
+// Count non-deleted rows.
 message GetTableDataCountRequest {
+  // Required. Profile (schema) name.
   string profile_name = 1;
+
+  // Required. Table name within the profile.
   string table_name = 2;
 }
 
+// Fetch by ordinal position among non-deleted rows (1-based).
 message GetTableDataByPositionRequest {
+  // Required. Profile (schema) name.
   string profile_name = 1;
+
+  // Required. Table name within the profile.
   string table_name = 2;
+
+  // Required. 1-based position by id ascending among rows with deleted = FALSE.
   int32 position = 3;
 }

common/src/lib.rs

@@ -37,7 +37,6 @@ pub mod proto {
         pub mod table_validation {
             include!("proto/komp_ac.table_validation.rs");
         }
-        pub const FILE_DESCRIPTOR_SET: &[u8] =
+        pub const FILE_DESCRIPTOR_SET: &[u8] = include_bytes!("proto/descriptor.bin");
-            include_bytes!("proto/descriptor.bin");
     }
 }

common/src/proto/komp_ac.table_definition.rs

@@ -1,77 +1,133 @@
 // This file is @generated by prost-build.
+/// A single link to another table within the same profile (schema).
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TableLink {
+    /// Name of an existing table within the same profile to link to.
+    /// For each link, a "<linked>_id" column is created on the new table.
+    /// That column references "<linked>"(id) and adds an index automatically.
     #[prost(string, tag = "1")]
     pub linked_table_name: ::prost::alloc::string::String,
+    /// If true, the generated foreign key column is NOT NULL.
+    /// Otherwise the column allows NULL.
+    /// Duplicate links to the same target table in one request are rejected.
     #[prost(bool, tag = "2")]
     pub required: bool,
 }
+/// Defines the input for creating a new table definition.
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PostTableDefinitionRequest {
+    /// Table name to create inside the target profile.
+    /// Must be lowercase, alphanumeric with underscores,
+    /// start with a letter, and be <= 63 chars.
+    /// Forbidden names: "id", "deleted", "created_at", or ending in "_id".
     #[prost(string, tag = "1")]
     pub table_name: ::prost::alloc::string::String,
+    /// List of links (foreign keys) to existing tables in the same profile.
+    /// Each will automatically get a "<linked>_id" column and an index.
     #[prost(message, repeated, tag = "2")]
     pub links: ::prost::alloc::vec::Vec<TableLink>,
+    /// List of user-defined columns (adds to system/id/fk columns).
     #[prost(message, repeated, tag = "3")]
     pub columns: ::prost::alloc::vec::Vec<ColumnDefinition>,
+    /// List of column names to be indexed (must match existing user-defined columns).
+    /// Indexes can target only user-defined columns; system columns ("id", "deleted",
+    /// "created_at") and automatically generated foreign key ("*_id") columns already
+    /// have indexes. Requests trying to index those columns are rejected.
     #[prost(string, repeated, tag = "4")]
     pub indexes: ::prost::alloc::vec::Vec<::prost::alloc::string::String>,
+    /// Name of profile (Postgres schema) where the table will be created.
+    /// Same naming rules as table_name; cannot collide with reserved schemas
+    /// like "public", "information_schema", or ones starting with "pg_".
     #[prost(string, tag = "5")]
     pub profile_name: ::prost::alloc::string::String,
 }
+/// Describes one user-defined column for a table.
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ColumnDefinition {
+    /// Column name that follows the same validation rules as table_name.
+    /// Must be lowercase, start with a letter, no uppercase characters,
+    /// and cannot be "id", "deleted", "created_at", or end with "_id".
     #[prost(string, tag = "1")]
     pub name: ::prost::alloc::string::String,
+    /// Logical column type. Supported values (case-insensitive):
+    ///    TEXT / STRING
+    ///    BOOLEAN
+    ///    TIMESTAMP / TIMESTAMPTZ / TIME
+    ///    MONEY (= NUMERIC(14,4))
+    ///    INTEGER / INT
+    ///    BIGINTEGER / BIGINT
+    ///    DATE
+    ///    DECIMAL(p,s) → NUMERIC(p,s)
+    /// DECIMAL args must be integers (no sign, no dot, no leading zeros);
+    /// s ≤ p and p ≥ 1.
     #[prost(string, tag = "2")]
     pub field_type: ::prost::alloc::string::String,
 }
+/// Response after table creation (success + DDL preview).
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TableDefinitionResponse {
+    /// True if all DB changes and metadata inserts succeeded.
     #[prost(bool, tag = "1")]
     pub success: bool,
+    /// The actual SQL executed: CREATE TABLE + CREATE INDEX statements.
     #[prost(string, tag = "2")]
     pub sql: ::prost::alloc::string::String,
 }
+/// Describes the tree of all profiles and their tables.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ProfileTreeResponse {
+    /// All profiles in the system.
     #[prost(message, repeated, tag = "1")]
     pub profiles: ::prost::alloc::vec::Vec<profile_tree_response::Profile>,
 }
 /// Nested message and enum types in `ProfileTreeResponse`.
 pub mod profile_tree_response {
+    /// Table entry in a profile.
     #[derive(Clone, PartialEq, ::prost::Message)]
     pub struct Table {
+        /// Internal ID from table_definitions.id (metadata record).
         #[prost(int64, tag = "1")]
         pub id: i64,
+        /// Table name within the profile (schema).
         #[prost(string, tag = "2")]
         pub name: ::prost::alloc::string::String,
+        /// Other tables this one references (based on link definitions only).
         #[prost(string, repeated, tag = "3")]
         pub depends_on: ::prost::alloc::vec::Vec<::prost::alloc::string::String>,
     }
+    /// Profile (schema) entry.
     #[derive(Clone, PartialEq, ::prost::Message)]
     pub struct Profile {
+        /// Name of the schema/profile (as stored in `schemas.name`).
         #[prost(string, tag = "1")]
         pub name: ::prost::alloc::string::String,
+        /// All tables in that schema and their dependencies.
         #[prost(message, repeated, tag = "2")]
         pub tables: ::prost::alloc::vec::Vec<Table>,
     }
 }
+/// Request to delete one table definition entirely.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct DeleteTableRequest {
+    /// Profile (schema) name owning the table (must exist).
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Table to drop (must exist in the profile).
+    /// Executes DROP TABLE "profile"."table" CASCADE and then removes metadata.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
 }
+/// Response after table deletion.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct DeleteTableResponse {
+    /// True if table and metadata were successfully deleted in one transaction.
     #[prost(bool, tag = "1")]
     pub success: bool,
+    /// Human-readable summary of what was removed.
     #[prost(string, tag = "2")]
     pub message: ::prost::alloc::string::String,
 }
@@ -86,6 +142,10 @@ pub mod table_definition_client {
     )]
     use tonic::codegen::*;
     use tonic::codegen::http::Uri;
+    /// The TableDefinition service manages the entire lifecycle of user-defined
+    /// tables (stored as both metadata and physical PostgreSQL tables) inside
+    /// logical "profiles" (schemas). Each table has stored structure, links, and
+    /// validation rules.
     #[derive(Debug, Clone)]
     pub struct TableDefinitionClient<T> {
         inner: tonic::client::Grpc<T>,
@@ -166,6 +226,9 @@ pub mod table_definition_client {
             self.inner = self.inner.max_encoding_message_size(limit);
             self
         }
+        /// Creates a new table (and schema if missing) with system columns,
+        /// linked-table foreign keys, user-defined columns, and optional indexes.
+        /// Also inserts metadata and default validation rules. Entirely transactional.
         pub async fn post_table_definition(
             &mut self,
             request: impl tonic::IntoRequest<super::PostTableDefinitionRequest>,
@@ -195,6 +258,8 @@ pub mod table_definition_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Lists all profiles (schemas) and their tables with declared dependencies.
+        /// This provides a tree-like overview of table relationships.
         pub async fn get_profile_tree(
             &mut self,
             request: impl tonic::IntoRequest<super::super::common::Empty>,
@@ -224,6 +289,7 @@ pub mod table_definition_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Drops a table and its metadata, then deletes the profile if it becomes empty.
         pub async fn delete_table(
             &mut self,
             request: impl tonic::IntoRequest<super::DeleteTableRequest>,
@@ -268,6 +334,9 @@ pub mod table_definition_server {
     /// Generated trait containing gRPC methods that should be implemented for use with TableDefinitionServer.
     #[async_trait]
     pub trait TableDefinition: std::marker::Send + std::marker::Sync + 'static {
+        /// Creates a new table (and schema if missing) with system columns,
+        /// linked-table foreign keys, user-defined columns, and optional indexes.
+        /// Also inserts metadata and default validation rules. Entirely transactional.
         async fn post_table_definition(
             &self,
             request: tonic::Request<super::PostTableDefinitionRequest>,
@@ -275,6 +344,8 @@ pub mod table_definition_server {
             tonic::Response<super::TableDefinitionResponse>,
             tonic::Status,
         >;
+        /// Lists all profiles (schemas) and their tables with declared dependencies.
+        /// This provides a tree-like overview of table relationships.
         async fn get_profile_tree(
             &self,
             request: tonic::Request<super::super::common::Empty>,
@@ -282,6 +353,7 @@ pub mod table_definition_server {
             tonic::Response<super::ProfileTreeResponse>,
             tonic::Status,
         >;
+        /// Drops a table and its metadata, then deletes the profile if it becomes empty.
         async fn delete_table(
             &self,
             request: tonic::Request<super::DeleteTableRequest>,
@@ -290,6 +362,10 @@ pub mod table_definition_server {
             tonic::Status,
         >;
     }
+    /// The TableDefinition service manages the entire lifecycle of user-defined
+    /// tables (stored as both metadata and physical PostgreSQL tables) inside
+    /// logical "profiles" (schemas). Each table has stored structure, links, and
+    /// validation rules.
     #[derive(Debug)]
     pub struct TableDefinitionServer<T> {
         inner: Arc<T>,

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>,

common/src/proto/komp_ac.table_structure.rs

@@ -1,27 +1,46 @@
 // This file is @generated by prost-build.
+/// Request identifying the profile (schema) and table to inspect.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct GetTableStructureRequest {
-    /// e.g., "default"
+    /// Required. Profile (PostgreSQL schema) name. Must exist in `schemas`.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
-    /// e.g., "2025_adresar6"
+    /// Required. Table name within the profile. Must exist in `table_definitions`
+    /// for the given profile. The physical table is then introspected via
+    /// information_schema.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
 }
+/// Response with the ordered list of columns (by ordinal position).
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct 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.
     #[prost(message, repeated, tag = "1")]
     pub columns: ::prost::alloc::vec::Vec<TableColumn>,
 }
+/// One physical column entry as reported by information_schema.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct TableColumn {
+    /// Column name exactly as defined in PostgreSQL.
     #[prost(string, tag = "1")]
     pub name: ::prost::alloc::string::String,
-    /// e.g., "TEXT", "BIGINT", "VARCHAR(255)", "TIMESTAMPTZ"
+    /// 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)"
     #[prost(string, tag = "2")]
     pub data_type: ::prost::alloc::string::String,
+    /// True if information_schema reports the column as nullable.
     #[prost(bool, tag = "3")]
     pub is_nullable: bool,
+    /// True if the column is part of the table's PRIMARY KEY.
+    /// Typically true for the "id" column created by the system.
     #[prost(bool, tag = "4")]
     pub is_primary_key: bool,
 }
@@ -36,6 +55,14 @@ pub mod table_structure_service_client {
     )]
     use tonic::codegen::*;
     use tonic::codegen::http::Uri;
+    /// 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.
     #[derive(Debug, Clone)]
     pub struct TableStructureServiceClient<T> {
         inner: tonic::client::Grpc<T>,
@@ -116,6 +143,16 @@ pub mod table_structure_service_client {
             self.inner = self.inner.max_encoding_message_size(limit);
             self
         }
+        /// 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)
         pub async fn get_table_structure(
             &mut self,
             request: impl tonic::IntoRequest<super::GetTableStructureRequest>,
@@ -160,6 +197,16 @@ pub mod table_structure_service_server {
     /// Generated trait containing gRPC methods that should be implemented for use with TableStructureServiceServer.
     #[async_trait]
     pub trait TableStructureService: std::marker::Send + std::marker::Sync + 'static {
+        /// 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)
         async fn get_table_structure(
             &self,
             request: tonic::Request<super::GetTableStructureRequest>,
@@ -168,6 +215,14 @@ pub mod table_structure_service_server {
             tonic::Status,
         >;
     }
+    /// 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.
     #[derive(Debug)]
     pub struct TableStructureServiceServer<T> {
         inner: Arc<T>,

common/src/proto/komp_ac.table_validation.rs

@@ -26,7 +26,13 @@ pub struct FieldValidation {
     #[prost(message, optional, tag = "10")]
     pub limits: ::core::option::Option<CharacterLimits>,
     /// Future expansion:
-    /// PatternRules pattern = 11;
+    ///
+    /// Validation 2
+    #[prost(message, optional, tag = "11")]
+    pub pattern: ::core::option::Option<PatternRules>,
+    /// Validation 4 – custom formatting logic
+    #[prost(message, optional, tag = "14")]
+    pub formatter: ::core::option::Option<CustomFormatter>,
     #[prost(message, optional, tag = "3")]
     pub mask: ::core::option::Option<DisplayMask>,
     /// ExternalValidation external = 13;
@@ -65,6 +71,46 @@ pub struct DisplayMask {
     #[prost(string, optional, tag = "3")]
     pub template_char: ::core::option::Option<::prost::alloc::string::String>,
 }
+/// One position‑based validation rule, similar to CharacterFilter + PositionRange
+#[derive(serde::Serialize, serde::Deserialize)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct PatternRule {
+    /// Range descriptor: how far the rule applies
+    /// Examples:
+    ///   - "0"        → Single position 0
+    ///   - "0-3"      → Range 0..3 inclusive
+    ///   - "from:5"   → From position 5 onward
+    ///   - "0,2,5"    → Multiple discrete positions
+    #[prost(string, tag = "1")]
+    pub range: ::prost::alloc::string::String,
+    /// Character filter type, case‑insensitive keywords:
+    /// "ALPHABETIC", "NUMERIC", "ALPHANUMERIC",
+    /// "ONEOF(<chars>)", "EXACT(:)", "CUSTOM(<name>)"
+    #[prost(string, tag = "2")]
+    pub filter: ::prost::alloc::string::String,
+}
+#[derive(serde::Serialize, serde::Deserialize)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct CustomFormatter {
+    /// Formatter type identifier; handled client‑side.
+    /// Examples: "PSCFormatter", "PhoneFormatter", "CreditCardFormatter", "DateFormatter"
+    #[prost(string, tag = "1")]
+    pub r#type: ::prost::alloc::string::String,
+    /// Optional free‑text note or parameters (e.g. locale, pattern)
+    #[prost(string, optional, tag = "2")]
+    pub description: ::core::option::Option<::prost::alloc::string::String>,
+}
+/// Collection of pattern rules for one field
+#[derive(serde::Serialize, serde::Deserialize)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct PatternRules {
+    /// All rules that make up the validation logic
+    #[prost(message, repeated, tag = "1")]
+    pub rules: ::prost::alloc::vec::Vec<PatternRule>,
+    /// Optional human‑readable description for UI/debug purposes
+    #[prost(string, optional, tag = "2")]
+    pub description: ::core::option::Option<::prost::alloc::string::String>,
+}
 #[derive(serde::Serialize, serde::Deserialize)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct UpdateFieldValidationRequest {

common/src/proto/komp_ac.tables_data.rs

@@ -1,92 +1,170 @@
 // This file is @generated by prost-build.
+/// Insert a new row.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PostTableDataRequest {
+    /// Required. Profile (PostgreSQL schema) name that owns the table.
+    /// Must exist in the schemas table.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Required. Logical table (definition) name within the profile.
+    /// Must exist in table_definitions for the given profile.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
+    /// Required. Key-value data for columns to insert.
+    ///
+    /// Allowed keys:
+    /// - User-defined columns from the table definition
+    /// - System/FK columns:
+    ///     • "deleted" (BOOLEAN), optional; default FALSE if not provided
+    ///     • "<linked_table>_id" (BIGINT) for each table link
+    ///
+    /// Type expectations by SQL type:
+    /// - TEXT: string value; empty string is treated as NULL
+    /// - BOOLEAN: bool value
+    /// - TIMESTAMPTZ: ISO 8601/RFC 3339 string (parsed to TIMESTAMPTZ)
+    /// - INTEGER: number with no fractional part and within i32 range
+    /// - BIGINT: number with no fractional part and within i64 range
+    /// - NUMERIC(p,s): string representation only; empty string becomes NULL
+    ///    (numbers for NUMERIC are rejected to avoid precision loss)
+    ///
+    /// Script validation rules:
+    /// - If a script exists for a target column, that column MUST be present here,
+    ///    and its provided value MUST equal the script’s computed value (type-aware
+    ///    comparison, e.g., decimals are compared numerically).
+    ///
+    /// Notes:
+    /// - Unknown/invalid column names are rejected
+    /// - Some application-specific validations may apply (e.g., max length for
+    ///    certain fields like "telefon")
     #[prost(map = "string, message", tag = "3")]
     pub data: ::std::collections::HashMap<
         ::prost::alloc::string::String,
         ::prost_types::Value,
     >,
 }
+/// Insert response.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PostTableDataResponse {
+    /// True if the insert succeeded.
     #[prost(bool, tag = "1")]
     pub success: bool,
+    /// Human-readable message.
     #[prost(string, tag = "2")]
     pub message: ::prost::alloc::string::String,
+    /// The id of the inserted row.
     #[prost(int64, tag = "3")]
     pub inserted_id: i64,
 }
+/// Update an existing row.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PutTableDataRequest {
+    /// Required. Profile (schema) name.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Required. Table name within the profile.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
+    /// Required. Id of the row to update.
     #[prost(int64, tag = "3")]
     pub id: i64,
+    /// Required. Columns to update (same typing rules as PostTableDataRequest.data).
+    ///
+    /// Special script rules:
+    /// - If a script targets column X and X is included here, the value for X must
+    ///    equal the script’s result (type-aware).
+    /// - If X is not included here but the update would cause the script’s result
+    ///    to change compared to the current stored value, the update is rejected with
+    ///    FAILED_PRECONDITION, instructing the caller to include X explicitly.
+    ///
+    /// Passing an empty map results in a no-op success response.
     #[prost(map = "string, message", tag = "4")]
     pub data: ::std::collections::HashMap<
         ::prost::alloc::string::String,
         ::prost_types::Value,
     >,
 }
+/// Update response.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct PutTableDataResponse {
+    /// True if the update succeeded (or no-op on empty data).
     #[prost(bool, tag = "1")]
     pub success: bool,
+    /// Human-readable message.
     #[prost(string, tag = "2")]
     pub message: ::prost::alloc::string::String,
+    /// The id of the updated row.
     #[prost(int64, tag = "3")]
     pub updated_id: i64,
 }
+/// Soft-delete a single row.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct DeleteTableDataRequest {
+    /// Required. Profile (schema) name.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Required. Table name within the profile.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
+    /// Required. Row id to soft-delete.
     #[prost(int64, tag = "3")]
     pub record_id: i64,
 }
+/// Soft-delete response.
 #[derive(Clone, Copy, PartialEq, ::prost::Message)]
 pub struct DeleteTableDataResponse {
+    /// True if a row was marked deleted (id existed and was not already deleted).
     #[prost(bool, tag = "1")]
     pub success: bool,
 }
+/// Fetch a single non-deleted row by id.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct GetTableDataRequest {
+    /// Required. Profile (schema) name.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Required. Table name within the profile.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
+    /// Required. Id of the row to fetch.
     #[prost(int64, tag = "3")]
     pub id: i64,
 }
+/// Row payload: all columns returned as strings.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct GetTableDataResponse {
+    /// Map of column_name → stringified value for:
+    /// - id, deleted
+    /// - all user-defined columns from the table definition
+    /// - FK columns named "<linked_table>_id" for each table link
+    ///
+    /// All values are returned as TEXT via col::TEXT and COALESCEed to empty string
+    /// (NULL becomes ""). The row is returned only if deleted = FALSE.
     #[prost(map = "string, string", tag = "1")]
     pub data: ::std::collections::HashMap<
         ::prost::alloc::string::String,
         ::prost::alloc::string::String,
     >,
 }
+/// Count non-deleted rows.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct GetTableDataCountRequest {
+    /// Required. Profile (schema) name.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Required. Table name within the profile.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
 }
+/// Fetch by ordinal position among non-deleted rows (1-based).
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct GetTableDataByPositionRequest {
+    /// Required. Profile (schema) name.
     #[prost(string, tag = "1")]
     pub profile_name: ::prost::alloc::string::String,
+    /// Required. Table name within the profile.
     #[prost(string, tag = "2")]
     pub table_name: ::prost::alloc::string::String,
+    /// Required. 1-based position by id ascending among rows with deleted = FALSE.
     #[prost(int32, tag = "3")]
     pub position: i32,
 }
@@ -101,6 +179,11 @@ pub mod tables_data_client {
     )]
     use tonic::codegen::*;
     use tonic::codegen::http::Uri;
+    /// Read and write row data for user-defined tables inside profiles (schemas).
+    /// Operations are performed against the physical PostgreSQL table that
+    /// corresponds to the logical table definition and are scoped by profile
+    /// (schema). Deletions are soft (set deleted = true). Typed binding and
+    /// script-based validation are enforced consistently.
     #[derive(Debug, Clone)]
     pub struct TablesDataClient<T> {
         inner: tonic::client::Grpc<T>,
@@ -181,6 +264,16 @@ pub mod tables_data_client {
             self.inner = self.inner.max_encoding_message_size(limit);
             self
         }
+        /// Insert a new row into a table with strict type binding and script validation.
+        ///
+        /// Behavior:
+        /// - Validates that profile (schema) exists and table is defined for it
+        /// - Validates provided columns exist (user-defined or allowed system/FK columns)
+        /// - For columns targeted by scripts in this table, the client MUST provide the
+        ///   value, and it MUST equal the script’s calculated value (compared type-safely)
+        /// - Binds values with correct SQL types, rejects invalid formats/ranges
+        /// - Inserts the row and returns the new id; queues search indexing (best effort)
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         pub async fn post_table_data(
             &mut self,
             request: impl tonic::IntoRequest<super::PostTableDataRequest>,
@@ -207,6 +300,17 @@ pub mod tables_data_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Update existing row data with strict type binding and script validation.
+        ///
+        /// Behavior:
+        /// - Validates profile and table, and that the record exists
+        /// - If request data is empty, returns success without changing the row
+        /// - For columns targeted by scripts:
+        ///    • If included in update, provided value must equal the script result
+        ///    • If not included, update must not cause the script result to differ
+        ///      from the current stored value; otherwise FAILED_PRECONDITION is returned
+        /// - Binds values with correct SQL types; rejects invalid formats/ranges
+        /// - Updates the row and returns the id; queues search indexing (best effort)
         pub async fn put_table_data(
             &mut self,
             request: impl tonic::IntoRequest<super::PutTableDataRequest>,
@@ -233,6 +337,13 @@ pub mod tables_data_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Soft-delete a single record (sets deleted = true) if it exists and is not already deleted.
+        ///
+        /// Behavior:
+        /// - Validates profile and table definition
+        /// - Updates only rows with deleted = false
+        /// - success = true means a row was actually changed; false means nothing to delete
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         pub async fn delete_table_data(
             &mut self,
             request: impl tonic::IntoRequest<super::DeleteTableDataRequest>,
@@ -259,6 +370,15 @@ pub mod tables_data_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Fetch a single non-deleted row by id as textified values.
+        ///
+        /// Behavior:
+        /// - Validates profile and table definition
+        /// - Returns all columns as strings (COALESCE(col::TEXT, '') AS col)
+        ///   including: id, deleted, all user-defined columns, and FK columns
+        ///   named "<linked_table>_id" for each table link
+        /// - Fails with NOT_FOUND if record does not exist or is soft-deleted
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         pub async fn get_table_data(
             &mut self,
             request: impl tonic::IntoRequest<super::GetTableDataRequest>,
@@ -285,6 +405,12 @@ pub mod tables_data_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Count non-deleted rows in a table.
+        ///
+        /// Behavior:
+        /// - Validates profile and table definition
+        /// - Returns komp_ac.common.CountResponse.count with rows where deleted = FALSE
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         pub async fn get_table_data_count(
             &mut self,
             request: impl tonic::IntoRequest<super::GetTableDataCountRequest>,
@@ -314,6 +440,12 @@ pub mod tables_data_client {
                 );
             self.inner.unary(req, path, codec).await
         }
+        /// Fetch the N-th non-deleted row by id order (1-based), then return its full data.
+        ///
+        /// Behavior:
+        /// - position is 1-based (position = 1 → first row by id ASC with deleted = FALSE)
+        /// - Returns NOT_FOUND if position is out of bounds
+        /// - Otherwise identical to GetTableData for the selected id
         pub async fn get_table_data_by_position(
             &mut self,
             request: impl tonic::IntoRequest<super::GetTableDataByPositionRequest>,
@@ -358,6 +490,16 @@ pub mod tables_data_server {
     /// Generated trait containing gRPC methods that should be implemented for use with TablesDataServer.
     #[async_trait]
     pub trait TablesData: std::marker::Send + std::marker::Sync + 'static {
+        /// Insert a new row into a table with strict type binding and script validation.
+        ///
+        /// Behavior:
+        /// - Validates that profile (schema) exists and table is defined for it
+        /// - Validates provided columns exist (user-defined or allowed system/FK columns)
+        /// - For columns targeted by scripts in this table, the client MUST provide the
+        ///   value, and it MUST equal the script’s calculated value (compared type-safely)
+        /// - Binds values with correct SQL types, rejects invalid formats/ranges
+        /// - Inserts the row and returns the new id; queues search indexing (best effort)
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         async fn post_table_data(
             &self,
             request: tonic::Request<super::PostTableDataRequest>,
@@ -365,6 +507,17 @@ pub mod tables_data_server {
             tonic::Response<super::PostTableDataResponse>,
             tonic::Status,
         >;
+        /// Update existing row data with strict type binding and script validation.
+        ///
+        /// Behavior:
+        /// - Validates profile and table, and that the record exists
+        /// - If request data is empty, returns success without changing the row
+        /// - For columns targeted by scripts:
+        ///    • If included in update, provided value must equal the script result
+        ///    • If not included, update must not cause the script result to differ
+        ///      from the current stored value; otherwise FAILED_PRECONDITION is returned
+        /// - Binds values with correct SQL types; rejects invalid formats/ranges
+        /// - Updates the row and returns the id; queues search indexing (best effort)
         async fn put_table_data(
             &self,
             request: tonic::Request<super::PutTableDataRequest>,
@@ -372,6 +525,13 @@ pub mod tables_data_server {
             tonic::Response<super::PutTableDataResponse>,
             tonic::Status,
         >;
+        /// Soft-delete a single record (sets deleted = true) if it exists and is not already deleted.
+        ///
+        /// Behavior:
+        /// - Validates profile and table definition
+        /// - Updates only rows with deleted = false
+        /// - success = true means a row was actually changed; false means nothing to delete
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         async fn delete_table_data(
             &self,
             request: tonic::Request<super::DeleteTableDataRequest>,
@@ -379,6 +539,15 @@ pub mod tables_data_server {
             tonic::Response<super::DeleteTableDataResponse>,
             tonic::Status,
         >;
+        /// Fetch a single non-deleted row by id as textified values.
+        ///
+        /// Behavior:
+        /// - Validates profile and table definition
+        /// - Returns all columns as strings (COALESCE(col::TEXT, '') AS col)
+        ///   including: id, deleted, all user-defined columns, and FK columns
+        ///   named "<linked_table>_id" for each table link
+        /// - Fails with NOT_FOUND if record does not exist or is soft-deleted
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         async fn get_table_data(
             &self,
             request: tonic::Request<super::GetTableDataRequest>,
@@ -386,6 +555,12 @@ pub mod tables_data_server {
             tonic::Response<super::GetTableDataResponse>,
             tonic::Status,
         >;
+        /// Count non-deleted rows in a table.
+        ///
+        /// Behavior:
+        /// - Validates profile and table definition
+        /// - Returns komp_ac.common.CountResponse.count with rows where deleted = FALSE
+        /// - If the physical table is missing but the definition exists, returns INTERNAL
         async fn get_table_data_count(
             &self,
             request: tonic::Request<super::GetTableDataCountRequest>,
@@ -393,6 +568,12 @@ pub mod tables_data_server {
             tonic::Response<super::super::common::CountResponse>,
             tonic::Status,
         >;
+        /// Fetch the N-th non-deleted row by id order (1-based), then return its full data.
+        ///
+        /// Behavior:
+        /// - position is 1-based (position = 1 → first row by id ASC with deleted = FALSE)
+        /// - Returns NOT_FOUND if position is out of bounds
+        /// - Otherwise identical to GetTableData for the selected id
         async fn get_table_data_by_position(
             &self,
             request: tonic::Request<super::GetTableDataByPositionRequest>,
@@ -401,6 +582,11 @@ pub mod tables_data_server {
             tonic::Status,
         >;
     }
+    /// Read and write row data for user-defined tables inside profiles (schemas).
+    /// Operations are performed against the physical PostgreSQL table that
+    /// corresponds to the logical table definition and are scoped by profile
+    /// (schema). Deletions are soft (set deleted = true). Typed binding and
+    /// script-based validation are enforced consistently.
     #[derive(Debug)]
     pub struct TablesDataServer<T> {
         inner: Arc<T>,

common/src/search.rs

@@ -48,8 +48,7 @@ pub fn register_slovak_tokenizers(index: &Index) -> tantivy::Result<()> {
     let tokenizer_manager = index.tokenizers();
 
     // TOKENIZER for `prefix_edge`: Edge N-gram (1-4 chars)
-    let edge_tokenizer =
+    let edge_tokenizer = TextAnalyzer::builder(NgramTokenizer::new(1, 4, true)?)
-        TextAnalyzer::builder(NgramTokenizer::new(1, 4, true)?)
         .filter(RemoveLongFilter::limit(40))
         .filter(LowerCaser)
         .filter(AsciiFoldingFilter)
@@ -57,8 +56,7 @@ pub fn register_slovak_tokenizers(index: &Index) -> tantivy::Result<()> {
     tokenizer_manager.register("slovak_prefix_edge", edge_tokenizer);
 
     // TOKENIZER for `prefix_full`: Simple word tokenizer
-    let full_tokenizer =
+    let full_tokenizer = TextAnalyzer::builder(SimpleTokenizer::default())
-        TextAnalyzer::builder(SimpleTokenizer::default())
         .filter(RemoveLongFilter::limit(40))
         .filter(LowerCaser)
         .filter(AsciiFoldingFilter)
@@ -66,8 +64,7 @@ pub fn register_slovak_tokenizers(index: &Index) -> tantivy::Result<()> {
     tokenizer_manager.register("slovak_prefix_full", full_tokenizer);
 
     // NGRAM TOKENIZER: For substring matching.
-    let ngram_tokenizer =
+    let ngram_tokenizer = TextAnalyzer::builder(NgramTokenizer::new(3, 3, false)?)
-        TextAnalyzer::builder(NgramTokenizer::new(3, 3, false)?)
         .filter(RemoveLongFilter::limit(40))
         .filter(LowerCaser)
         .filter(AsciiFoldingFilter)

flake.nix

@@ -14,12 +14,17 @@
       {
         devShells.default = pkgs.mkShell {
           buildInputs = with pkgs; [
+            mermaid-cli
             # Rust toolchain
             rustc
             cargo
             rustfmt
             clippy
             cargo-watch
+	    rust-analyzer
+	    cargo-tarpaulin
+	    cargo-flamegraph
+	    rust-code-analysis
 
             # C build tools (for your linker issue)
             gcc
@@ -36,6 +41,8 @@
             
             # Protocol Buffers compiler for gRPC
             protobuf
+            protoc-gen-doc
+	    buf
           ];
 
           shellHook = ''

search/src/lib.rs

@@ -4,18 +4,15 @@ use std::collections::HashMap;
 use std::path::Path;
 use tantivy::collector::TopDocs;
 use tantivy::query::{
-    BooleanQuery, BoostQuery, FuzzyTermQuery, Occur, Query, QueryParser,
+    BooleanQuery, BoostQuery, FuzzyTermQuery, Occur, Query, QueryParser, TermQuery,
-    TermQuery,
 };
 use tantivy::schema::{IndexRecordOption, Value};
 use tantivy::{Index, TantivyDocument, Term};
 use tonic::{Request, Response, Status};
 
-use common::proto::komp_ac::search::{
-    search_response::Hit, SearchRequest, SearchResponse,
-};
-pub use common::proto::komp_ac::search::searcher_server::SearcherServer;
 use common::proto::komp_ac::search::searcher_server::Searcher;
+pub use common::proto::komp_ac::search::searcher_server::SearcherServer;
+use common::proto::komp_ac::search::{search_response::Hit, SearchRequest, SearchResponse};
 use common::search::register_slovak_tokenizers;
 use sqlx::{PgPool, Row};
 use tracing::info;
@@ -86,22 +83,15 @@ impl Searcher for SearcherService {
                 qualified_table
             );
 
-            let rows = sqlx::query(&sql)
+            let rows = sqlx::query(&sql).fetch_all(&self.pool).await.map_err(|e| {
-                .fetch_all(&self.pool)
+                Status::internal(format!("DB query for default results failed: {}", e))
-                .await
-                .map_err(|e| {
-                    Status::internal(format!(
-                        "DB query for default results failed: {}",
-                        e
-                    ))
             })?;
 
             let hits: Vec<Hit> = rows
                 .into_iter()
                 .map(|row| {
                     let id: i64 = row.try_get("id").unwrap_or_default();
-                    let json_data: serde_json::Value =
+                    let json_data: serde_json::Value = row.try_get("data").unwrap_or_default();
-                        row.try_get("data").unwrap_or_default();
                     Hit {
                         id,
                         // Score is 0.0 as this is not a relevance-ranked search
@@ -111,7 +101,10 @@ impl Searcher for SearcherService {
                 })
                 .collect();
 
-            info!("--- SERVER: Successfully processed empty query. Returning {} default hits. ---", hits.len());
+            info!(
+                "--- SERVER: Successfully processed empty query. Returning {} default hits. ---",
+                hits.len()
+            );
             return Ok(Response::new(SearchResponse { hits }));
         }
         // --- END OF MODIFIED LOGIC ---
@@ -131,15 +124,15 @@ impl Searcher for SearcherService {
             Status::internal(format!("Failed to register Slovak tokenizers: {}", e))
         })?;
 
-        let reader = index.reader().map_err(|e| {
+        let reader = index
-            Status::internal(format!("Failed to create index reader: {}", e))
+            .reader()
-        })?;
+            .map_err(|e| Status::internal(format!("Failed to create index reader: {}", e)))?;
         let searcher = reader.searcher();
         let schema = index.schema();
 
-        let pg_id_field = schema.get_field("pg_id").map_err(|_| {
+        let pg_id_field = schema
-            Status::internal("Schema is missing the 'pg_id' field.")
+            .get_field("pg_id")
-        })?;
+            .map_err(|_| Status::internal("Schema is missing the 'pg_id' field."))?;
 
         // --- Query Building Logic (no changes here) ---
         let prefix_edge_field = schema.get_field("prefix_edge").unwrap();
@@ -158,25 +151,17 @@ impl Searcher for SearcherService {
         {
             let mut must_clauses: Vec<(Occur, Box<dyn Query>)> = Vec::new();
             for word in &words {
-                let edge_term =
+                let edge_term = Term::from_field_text(prefix_edge_field, word);
-                    Term::from_field_text(prefix_edge_field, word);
+                let full_term = Term::from_field_text(prefix_full_field, word);
-                let full_term =
-                    Term::from_field_text(prefix_full_field, word);
 
                 let per_word_query = BooleanQuery::new(vec![
                     (
                         Occur::Should,
-                        Box::new(TermQuery::new(
+                        Box::new(TermQuery::new(edge_term, IndexRecordOption::Basic)),
-                            edge_term,
-                            IndexRecordOption::Basic,
-                        )),
                     ),
                     (
                         Occur::Should,
-                        Box::new(TermQuery::new(
+                        Box::new(TermQuery::new(full_term, IndexRecordOption::Basic)),
-                            full_term,
-                            IndexRecordOption::Basic,
-                        )),
                     ),
                 ]);
                 must_clauses.push((Occur::Must, Box::new(per_word_query) as Box<dyn Query>));
@@ -184,8 +169,7 @@ impl Searcher for SearcherService {
 
             if !must_clauses.is_empty() {
                 let prefix_query = BooleanQuery::new(must_clauses);
-                let boosted_query =
+                let boosted_query = BoostQuery::new(Box::new(prefix_query), 4.0);
-                    BoostQuery::new(Box::new(prefix_query), 4.0);
                 query_layers.push((Occur::Should, Box::new(boosted_query)));
             }
         }
@@ -195,8 +179,7 @@ impl Searcher for SearcherService {
         // ===============================
         {
             let last_word = words.last().unwrap();
-            let fuzzy_term =
+            let fuzzy_term = Term::from_field_text(prefix_full_field, last_word);
-                Term::from_field_text(prefix_full_field, last_word);
             let fuzzy_query = FuzzyTermQuery::new(fuzzy_term, 2, true);
             let boosted_query = BoostQuery::new(Box::new(fuzzy_query), 3.0);
             query_layers.push((Occur::Should, Box::new(boosted_query)));
@@ -206,8 +189,7 @@ impl Searcher for SearcherService {
         // LAYER 3: PHRASE MATCHING WITH SLOP (MEDIUM PRIORITY, Boost: 2.0)
         // ===============================
         if words.len() > 1 {
-            let slop_parser =
+            let slop_parser = QueryParser::for_index(&index, vec![prefix_full_field]);
-                QueryParser::for_index(&index, vec![prefix_full_field]);
             let slop_query_str = format!("\"{}\"~3", normalized_query);
             if let Ok(slop_query) = slop_parser.parse_query(&slop_query_str) {
                 let boosted_query = BoostQuery::new(slop_query, 2.0);
@@ -219,11 +201,8 @@ impl Searcher for SearcherService {
         // LAYER 4: NGRAM SUBSTRING MATCHING (LOWEST PRIORITY, Boost: 1.0)
         // ===============================
         {
-            let ngram_parser =
+            let ngram_parser = QueryParser::for_index(&index, vec![text_ngram_field]);
-                QueryParser::for_index(&index, vec![text_ngram_field]);
+            if let Ok(ngram_query) = ngram_parser.parse_query(&normalized_query) {
-            if let Ok(ngram_query) =
-                ngram_parser.parse_query(&normalized_query)
-            {
                 let boosted_query = BoostQuery::new(ngram_query, 1.0);
                 query_layers.push((Occur::Should, Box::new(boosted_query)));
             }
@@ -244,9 +223,9 @@ impl Searcher for SearcherService {
         // Step 1: Extract (score, pg_id) from Tantivy results.
         let mut scored_ids: Vec<(f32, u64)> = Vec::new();
         for (score, doc_address) in top_docs {
-            let doc: TantivyDocument = searcher.doc(doc_address).map_err(|e| {
+            let doc: TantivyDocument = searcher
-                Status::internal(format!("Failed to retrieve document: {}", e))
+                .doc(doc_address)
-            })?;
+                .map_err(|e| Status::internal(format!("Failed to retrieve document: {}", e)))?;
             if let Some(pg_id_value) = doc.get_first(pg_id_field) {
                 if let Some(pg_id) = pg_id_value.as_u64() {
                     scored_ids.push((score, pg_id));
@@ -255,8 +234,7 @@ impl Searcher for SearcherService {
         }
 
         // Step 2: Fetch all corresponding rows from Postgres in a single query.
-        let pg_ids: Vec<i64> =
+        let pg_ids: Vec<i64> = scored_ids.iter().map(|(_, id)| *id as i64).collect();
-            scored_ids.iter().map(|(_, id)| *id as i64).collect();
         let qualified_table = format!("gen.\"{}\"", table_name);
         let query_str = format!(
             "SELECT id, to_jsonb(t) AS data FROM {} t WHERE id = ANY($1)",
@@ -267,9 +245,7 @@ impl Searcher for SearcherService {
             .bind(&pg_ids)
             .fetch_all(&self.pool)
             .await
-            .map_err(|e| {
+            .map_err(|e| Status::internal(format!("Database query failed: {}", e)))?;
-                Status::internal(format!("Database query failed: {}", e))
-            })?;
 
         // Step 3: Map the database results by ID for quick lookup.
         let mut content_map: HashMap<i64, String> = HashMap::new();
@@ -284,9 +260,7 @@ impl Searcher for SearcherService {
         let hits: Vec<Hit> = scored_ids
             .into_iter()
             .filter_map(|(score, pg_id)| {
-                content_map
+                content_map.get(&(pg_id as i64)).map(|content_json| Hit {
-                    .get(&(pg_id as i64))
-                    .map(|content_json| Hit {
                     id: pg_id as i64,
                     score,
                     content_json: content_json.clone(),
@@ -294,7 +268,10 @@ impl Searcher for SearcherService {
             })
             .collect();
 
-        info!("--- SERVER: Successfully processed search. Returning {} hits. ---", hits.len());
+        info!(
+            "--- SERVER: Successfully processed search. Returning {} hits. ---",
+            hits.len()
+        );
 
         let response = SearchResponse { hits };
         Ok(Response::new(response))