komp_ac/common/proto/table_definition.proto

// common/proto/table_definition.proto
syntax = "proto3";
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);

  // Explicitly creates the optional administrator-managed exchange-rate table
  // in an existing profile. The server owns its core shape and constraints.
  rpc CreateCustomExchangeRatesTable(CreateCustomExchangeRatesTableRequest) returns (CreateCustomExchangeRatesTableResponse);

  // Creates a regular user-table bundle from the restricted komp_ac_fields
  // contract embedded in a Typst invoice template. This is invoked explicitly
  // by the user; templates do not provision tables merely by existing.
  rpc CreateInvoiceTemplateTable(CreateInvoiceTemplateTableRequest) returns (CreateInvoiceTemplateTableResponse);

  // Appends new user-defined columns to an existing table.
  // Existing columns, links, and table logic are never changed by this call.
  rpc AddTableColumns(AddTableColumnsRequest) returns (TableDefinitionResponse);

  // Atomically removes selected columns and appends new columns to an empty
  // dynamic table. Column identities come from GetProfileDetails. The call is
  // rejected after any row, including a soft-deleted row, has been stored.
  rpc PutTableDefinition(PutTableDefinitionRequest) returns (PutTableDefinitionResponse);

  // 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);

  // Lists the tables visible in one data-entry scope. When profile_name is
  // absent, only global tables are returned.
  rpc GetTableCatalog(GetTableCatalogRequest) returns (GetTableCatalogResponse);

  // Lists every column type a table may declare, along with the SQL type it
  // maps to. Pure data retrieval - no business logic.
  rpc ListColumnTypes(komp_ac.common.Empty) returns (ListColumnTypesResponse);

  // Fetches all tables with their columns and scripts for a specific profile.
  // Pure data retrieval - no business logic.
  rpc GetProfileDetails(GetProfileDetailsRequest) returns (GetProfileDetailsResponse);

  // Copies one complete profile into a new profile without copying table data.
  rpc CopyProfile(CopyProfileRequest) returns (CopyProfileResponse);

  // Returns the stored rename history for column aliases in one profile.
  rpc GetColumnAliasRenameHistory(GetColumnAliasRenameHistoryRequest) returns (GetColumnAliasRenameHistoryResponse);

  // Atomically replaces the aliases and presentation order of a table's columns.
  // Physical column names and identities remain unchanged.
  rpc SetColumnPresentation(SetColumnPresentationRequest) returns (SetColumnPresentationResponse);

  // Shows or hides one column in bundled data-entry forms. This is presentation
  // metadata only: hidden columns remain available to data APIs, scripts and
  // backend calculations.
  rpc SetColumnFormVisibility(SetColumnFormVisibilityRequest) returns (SetColumnFormVisibilityResponse);

  // Drops a table and its metadata, then deletes the profile if it becomes empty.
  rpc DeleteTable(DeleteTableRequest) returns (DeleteTableResponse);
}

message CreateCustomExchangeRatesTableRequest {
  string profile_name = 1;
}

message CreateCustomExchangeRatesTableResponse {
  int64 table_definition_id = 1;
  bool created = 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 include the system columns and tables owned by dedicated
  // server operations, such as "custom_exchange_rates". The "_id" suffix is
  // allowed.
  string table_name = 1;

  // The table's columns, including its links and stored linked projections.
  // A projection uses field_type FROM(link_column.source_column); its physical
  // type and money metadata are inferred from the linked source column.
  repeated ColumnDefinition columns = 3;

  // Column names to index, matching names declared above. System columns
  // ("id", "deleted", "created_at", "row_revision") already have indexes, and
  // a LINK column is indexed when it is created. Requests naming either 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;

  // Columns whose values identify a row to users in pickers, in the order
  // they are shown. Each must name one of the user-defined columns above.
  // Empty means the row is identified by its id alone.
  repeated string row_display_columns = 7;

  // ISO-4217 currency the profile keeps its accounting in. A profile is one
  // accounting entity and keeps one set of books, so this is required only when
  // the request creates the profile, and is ignored afterwards. It is unrelated
  // to individual MONEY-column currencies: tables may hold money in any currency, and amounts convert
  // to this one when they reach the ledger.
  string accounting_currency = 8;

  // Initial compiled direct-rate provider. It is enabled for each initial
  // foreign currency below; more provider/currency bindings may be appended later.
  string rate_source_id = 11;

  // Append-only foreign currencies initially enabled for this profile.
  repeated string foreign_currencies = 12;

  // When true, the table is stored once in the global physical schema and is
  // visible from every profile. profile_name and accounting_currency are ignored.
  bool global = 9;

  // Names for the columns a definition row generates, in place of the ones the
  // backend would give them. See GeneratedColumnAlias.
  repeated GeneratedColumnAlias generated_aliases = 10;

}

// Renames one column a definition row generates, at the moment it is created.
//
// A generated column cannot be named in the column list -- the definition row
// is required to be named after its own type, and what it expands into is the
// backend's to decide. The name is only ever a display name over a physical
// column, though, so it is free to be anything: this is where that choice is
// made, instead of a SetColumnPresentation call afterwards.
//
// ACCOUNTING, PHONE and IBAN generated columns may be renamed: their
// relationships are recorded by physical column, so the rest of the system can
// find them without knowing their display names. ACCOUNTING_TRANSFER connectors
// are the exception and are refused here exactly as SetColumnPresentation refuses
// them.
message GeneratedColumnAlias {
  // The name the backend would otherwise give the column: one of ACCOUNTING's
  // "name", "tax_point_date", "debit", "credit" or "account", or a PHONE or
  // IBAN companion such as "work_phone_ext". Must name a column the request
  // really generates -- an alias for anything else is rejected rather than
  // ignored, so a typo cannot pass silently.
  string generated_name = 1;

  // What the column should be called instead. Preserved exactly for display.
  // Aliases may contain Unicode letters, numbers, spaces, punctuation and
  // symbols, but not leading/trailing whitespace or control characters, and
  // are limited to 63 UTF-8 bytes. Uniqueness and lookup use a compatibility-
  // normalized, Unicode-case-folded key that collapses whitespace and ignores
  // emoji while keeping punctuation significant.
  string alias = 2;
}

// Defines the input for explicitly creating tables backed by one invoice
// Enables a stored global Typst template for one profile and immediately
// creates the input-table family declared by that template.
message CreateInvoiceTemplateTableRequest {
  string profile_name = 1;
  string template_name = 2;
  repeated string row_display_columns = 3;
}

// One physical dynamic table created for an invoice template scope. The root
// has an empty collection_path and parent_table_name. Each [] scope names its
// collection and the generated table that owns those repeated rows.
message GeneratedInvoiceTemplateTable {
  string table_name = 1;
  string collection_path = 2;
  string parent_table_name = 3;
  string sql = 4;
}

// Reports the complete table bundle created from one invoice template.
message CreateInvoiceTemplateTableResponse {
  bool success = 1;
  repeated GeneratedInvoiceTemplateTable tables = 2;
}

// Defines append-only column additions for an existing table.
message AddTableColumnsRequest {
  // Existing profile/schema name.
  string profile_name = 1;

  // Existing table name in the profile.
  string table_name = 2;

  // New user-defined columns only. Existing columns cannot be changed here.
  // Stored linked projections use field_type FROM(link_column.source_column).
  repeated ColumnDefinition columns = 3;

  // Optional indexes for the new columns only.
  repeated string indexes = 4;

  // Names for the columns the appended definition rows generate, exactly as on
  // PostTableDefinitionRequest.
  repeated GeneratedColumnAlias generated_aliases = 5;

}

// One atomic structural edit to an existing empty table.
//
// Removals use stable column IDs rather than aliases. Generated companion
// columns must be removed together with their generating column. New columns
// follow the same contract as AddTableColumns.
message PutTableDefinitionRequest {
  string profile_name = 1;
  string table_name = 2;
  repeated int64 remove_column_ids = 3;
  repeated ColumnDefinition add_columns = 4;
  repeated string add_indexes = 5;
  repeated GeneratedColumnAlias generated_aliases = 6;

  // Revision returned by GetProfileDetails. Prevents a stale editor from
  // overwriting a newer structural or presentation change.
  int64 expected_row_version = 7;

  // New physical/catalog name. Empty, or equal to table_name, keeps the
  // current name for backwards-compatible callers.
  string new_table_name = 8;
}

message PutTableDefinitionResponse {
  bool success = 1;
  string sql = 2;
  int64 row_version = 3;
  repeated int64 removed_column_ids = 4;
}

enum MoneyRounding {
  MONEY_ROUNDING_NONE = 0;
  MONEY_ROUNDING_HALF_UP = 1;
}

// Describes one user-defined column for a table.
message ColumnDefinition {
  // Must be lowercase, start with a letter, and use only lowercase letters,
  // digits and underscores.
  //
  // Cannot be "id", "deleted", "created_at" or "row_revision": those are
  // system columns, and a data request names system and user columns in one
  // namespace. Any other name is free, including one ending in "_id" -- no
  // column name is derived from a table name, so nothing collides.
  string name = 1;

  // Logical column type. Supported values (case-insensitive):
  //   TEXT
  //   BOOLEAN
  //   INSTANT (local input resolved in the authenticated user's timezone
  //            and displayed in the viewer timezone)
  //   USER_DATETIME (local input resolved in the user's timezone)
  //   RAW_DATETIME (timezone-free civil datetime)
  //   PHONE (international or national phone number; generates extension/type/country/calling-code companions)
  //   TIME (timezone-free time of day)
  //   MONEY (= unconstrained NUMERIC; currency is declared below)
  //   ACCOUNTING (creates schema-managed name, account, debit, and credit fields;
  //               account always selects a row from the profile's managed ledger_accounts table;
  //               name is limited to 10 characters and one stored row contributes
  //               one line to the profile journal)
  //   ACCOUNTING_TRANSFER (creates automatic source-period/account/book/
  //               denomination fields and writable target equivalents; one
  //               table may contain only one accounting transfer definition)
  //   INT
  //   BIGINT
  //   DATE
  //   DURATION
  //   PERIOD
  //   LINK(table) → BIGINT referencing that table in the same profile, indexed
  //                 automatically. A table may hold several links to the same
  //                 target as long as the columns are named differently.
  //   FROM(link.source) → stored, read-only copy of an atomic column reached
  //                 through another column in this definition whose type is
  //                 LINK(...). SQL type and money metadata are inferred.
  string field_type = 2;

  // MONEY rounding applied before a value is stored.
  MoneyRounding rounding = 3;

  // When true, this numeric column is server-owned and projected
  // from quantity-ledger contributions.
  bool quantity_ledger = 4;

  // Canonical uppercase ISO-4217 currency code. Required for MONEY and forbidden
  // for every other field type.
  string currency = 5;

  // When true, the server rejects omitted or explicitly null values.
  bool required = 6;

  // Enables a Boolean ledger on Boolean columns. ANY means
  // one true contribution wins; ALL means one false contribution wins.
  BooleanLedgerOperator boolean_ledger = 7;
}

enum BooleanLedgerOperator {
  BOOLEAN_LEDGER_OPERATOR_UNSPECIFIED = 0;
  BOOLEAN_LEDGER_OPERATOR_ANY = 1;
  BOOLEAN_LEDGER_OPERATOR_ALL = 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 {
  // One link: the table it points at, and the column carrying it.
  message Dependency {
    // Table being referenced.
    string table_name = 1;

    // Column holding the reference, named by whoever declared the link. This
    // is what identifies the link, since a table may point at one target
    // several times.
    string column_name = 2;
  }

  // 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;

    // Links this table declares. One entry per link, so a table that names the
    // same target twice appears twice.
    repeated Dependency depends_on = 3;

    // Columns whose values make up the human-readable row label, in order.
    repeated string row_display_columns = 4;

    // "dynamic" for user-defined tables, "system" for backend-managed tables.
    string table_kind = 5;

    // True when this table is shared by every profile.
    bool global = 6;

    // Profile (schema) the table is actually stored in. A global table is
    // listed under every profile it is visible from, so this names the one it
    // belongs to rather than the one it was reached through, and callers can
    // use it as the table's identity without deciding anything themselves.
    string profile_name = 7;
  }

  // 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;

  // The profile holding the tables every profile shares. Callers browse this
  // one when the user has not chosen a profile, so the name is reported here
  // rather than being known in advance.
  string shared_profile_name = 2;
}

message GetTableCatalogRequest {
  // Selected profile. Omit this field to request the global-only scope.
  optional string profile_name = 1;
}

message GetTableCatalogResponse {
  repeated ProfileTreeResponse.Table tables = 1;
}

// Request to fetch all tables, columns and scripts for a profile.
message GetProfileDetailsRequest {
  // Profile (schema) name to fetch details for.
  string profile_name = 1;
}

// Response with all tables, columns and scripts for a profile.
message GetProfileDetailsResponse {
  string profile_name = 1;
  repeated TableDetail tables = 2;
}

// Request to copy one full profile into a new profile.
message CopyProfileRequest {
  string source_profile_name = 1;
  string target_profile_name = 2;
  repeated string table_names = 3;
}

// Response after copying a profile.
message CopyProfileResponse {
  bool success = 1;
  string message = 2;
  int32 tables_copied = 3;
  int32 scripts_copied = 4;
}

// Request to fetch recorded column alias rename history for one profile.
message GetColumnAliasRenameHistoryRequest {
  string profile_name = 1;

  // Filter. When omitted, returns all tables in the profile.
  optional int64 table_definition_id = 2;
}

// One recorded column alias rename.
message ColumnAliasRenameHistoryEntry {
  int64 id = 1;
  string profile_name = 2;
  int64 table_definition_id = 3;
  string table_name = 4;
  string old_column_name = 5;
  string new_column_name = 6;
  string created_at = 7;
}

// Response with stored column alias rename history rows.
message GetColumnAliasRenameHistoryResponse {
  string profile_name = 1;
  repeated ColumnAliasRenameHistoryEntry entries = 2;
}

// Describes a table with its columns and associated scripts.
message TableDetail {
  string name = 1;
  int64 id = 2;
  repeated ColumnDefinition columns = 3;
  repeated ScriptInfo scripts = 4;
  repeated string row_display_columns = 6;
  map<string, ColumnBehavior> column_behaviors = 7;
  string table_kind = 8;
  bool global = 9;
  // Revision of this table definition for optimistic concurrency control.
  int64 row_version = 10;

  // Profile (schema) the table is actually stored in, which is not the
  // requested profile when a global table is being listed. See
  // ProfileTreeResponse.Table.profile_name.
  string profile_name = 11;

  // True when the physical table contains at least one row, including a
  // soft-deleted row. Populated tables are append-only: PutTableDefinition is
  // no longer available, while AddTableColumns remains available.
  bool has_data = 12;
}

// Server-owned behavior for one logical column returned in table details.
message ColumnBehavior {
  // True when the server created the column as a companion of another column.
  bool generated = 1;

  // True when clients must display but never submit edits for the column.
  bool read_only = 2;

  // Logical source column name, empty for ordinary user-defined columns.
  string generated_from = 3;

  // True when clients may offer this column in an alias rename picker.
  bool renameable = 4;

  // Stable public identity used when updating this column's presentation.
  int64 column_id = 5;

  // True when bundled data-entry clients should not render this column.
  // This is not an authorization boundary; data APIs still expose the column.
  bool hidden_from_forms = 6;
}

// A script that targets a specific column in a table.
message ScriptInfo {
  int64 script_id = 1;
  string target_column = 2;
  string target_column_type = 3;
  string script = 4;
  string description = 5;
}

// One column's desired public presentation. Its position in the containing
// repeated field is its presentation order.
message ColumnPresentation {
  // Stable public identity of the table_definition_columns row.
  int64 column_id = 1;
  string alias = 2;
}

// Atomically replaces every user-visible column alias and their order.
message SetColumnPresentationRequest {
  string profile_name = 1;
  string table_name = 2;
  repeated ColumnPresentation columns = 3;
  // Row version returned by GetProfileDetails when this presentation was read.
  int64 expected_row_version = 4;
}

message SetColumnPresentationResponse {
  bool success = 1;
  string message = 2;
  repeated ColumnPresentation columns = 3;
  // New row version after the update.
  int64 row_version = 4;
}

message SetColumnFormVisibilityRequest {
  string profile_name = 1;
  string table_name = 2;
  int64 column_id = 3;
  bool hidden_from_forms = 4;
  // Row version returned by GetProfileDetails when the column was read.
  int64 expected_row_version = 5;
}

message SetColumnFormVisibilityResponse {
  bool success = 1;
  string message = 2;
  int64 column_id = 3;
  bool hidden_from_forms = 4;
  // New row version after the update.
  int64 row_version = 5;
}

// 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;
}

// How a column type is spelled in ColumnDefinition.field_type.
enum ColumnTypeSpelling {
  // The name is the whole spelling: "text", "money", "gtin_13".
  COLUMN_TYPE_SPELLING_BARE = 0;

  reserved 1;

  // The name takes the name of another table in the same profile:
  // "link(adresar)". The column holds that table's id, and the server creates
  // the foreign key and its index. A picker offers the profile's other tables
  // as the argument.
  COLUMN_TYPE_SPELLING_LINK = 2;
}

// Response describing the whole column-type vocabulary.
//
// This is the authority a client builds its column-type picker from: every rule
// a client would otherwise hardcode about what a type means is a field here. The
// list covers types clients may NOT declare as well (see `declarable`), so that
// the same call also explains the types GetProfileDetails reports back for
// server-generated companion columns.
message ListColumnTypesResponse {
  // One column type and everything a client needs to know to offer it.
  message ColumnType {
    // Logical column type (e.g. "money", "instant"). Passed to the server as
    // ColumnDefinition.field_type — see `spelling`, which is what says whether
    // this name is the whole spelling.
    string name = 1;

    // Underlying PostgreSQL type the logical type maps to (e.g. "NUMERIC").
    // Empty when `compound` is true.
    string sql_type = 2;

    // False for types the server generates on its own and rejects when a client
    // declares them: the phone and IBAN companions, and the accounting-transfer
    // connectors. A column-type picker must offer only declarable types.
    bool declarable = 3;

    // True when the type is a definition row rather than a column: it expands
    // into several schema-managed companion columns and no column of this name
    // survives. A compound type can therefore never be indexed, never be a row
    // display column, and has no single sql_type of its own.
    bool compound = 4;

    // Whether `name` is the whole spelling or takes arguments.
    ColumnTypeSpelling spelling = 5;

    // Whether ColumnDefinition.currency is required. Currency is rejected on
    // every type where this is false.
    bool requires_currency = 6;

    // True when the type may only be chosen while the table is being created.
    // AddTableColumns rejects these, because they bring schema-managed columns
    // that cannot be bolted onto a table that already exists.
    bool creation_only = 7;

    // Whether ColumnDefinition.quantity_ledger may be set on this type.
    bool allows_quantity_ledger = 8;
    // Whether ColumnDefinition.boolean_ledger may be set on this type.
    bool allows_boolean_ledger = 11;

    // Optional name grouping several types a client offers behind one choice —
    // "temporal" for the date and time types, "gtin" for the GTIN lengths.
    // Empty when the type stands on its own.
    string group = 9;

    // One column a compound type expands into.
    message GeneratedColumn {
      // Name the server gives the column. Fixed, and reserved: a table
      // declaring a compound type may not also declare a column of this name.
      string name = 1;

      // The generated column's own logical type, as this same catalog
      // describes it.
      string field_type = 2;

      // Whether the generated column carries the currency and rounding
      // declared on the definition row.
      bool inherits_currency = 3;
    }

    // What this type expands into, in the order the server creates the
    // columns. Populated for compound types only, where the generated names
    // are fixed; empty for every other type, including the ones whose
    // companions are named after the declared column (phone, iban).
    //
    // A picker offering a compound type shows these, so choosing it is not a
    // blind choice. The columns stay the server's to create — none of them may
    // be declared.
    repeated GeneratedColumn generated_columns = 10;
  }

  // Every column type, declarable or not, ordered by name.
  repeated ColumnType column_types = 1;
}