feat(policy): add obligation tables

service/policy/db/migrations/20250703000000_obligations.md

@@ -0,0 +1,75 @@
+[ADR for Obligations](https://github.com/opentdf/platform/issues/1933)
+
+This migration adds the obligation tables for definitions, values, triggers, fulfillers, and action attribute value relationships.
+
+```mermaid
+erDiagram
+    attribute_namespaces ||--o{ obligation_definitions : "belongs_to"
+    obligation_definitions ||--o{ obligation_values_standard : "has_many"
+    obligation_values_standard ||--o{ obligation_triggers : "has_many"
+    obligation_values_standard ||--o{ obligation_fulfillers : "has_many"
+    obligation_values_standard ||--o{ obligation_action_attribute_values : "has_many"
+    attribute_values ||--o{ obligation_triggers : "triggers"
+    actions ||--o{ obligation_action_attribute_values : "requires"
+    attribute_values ||--o{ obligation_action_attribute_values : "requires"
+
+    attribute_namespaces {
+        UUID id PK
+        string name
+    }
+
+    obligation_definitions {
+        UUID id PK
+        UUID namespace_id FK
+        string name
+        jsonb metadata
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    obligation_values_standard {
+        UUID id PK
+        UUID obligation_definition_id FK
+        string value
+        jsonb metadata
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    obligation_triggers {
+        UUID id PK
+        UUID attribute_value_id FK
+        UUID obligation_value_id FK
+        jsonb metadata
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    obligation_fulfillers {
+        UUID id PK
+        UUID obligation_value_id FK
+        jsonb conditionals
+        jsonb metadata
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    obligation_action_attribute_values {
+        UUID id PK
+        UUID obligation_value_id FK
+        UUID action_id FK
+        UUID attribute_value_id FK
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    attribute_values {
+        UUID id PK
+        string value
+    }
+
+    actions {
+        UUID id PK
+        string name
+    }
+```

service/policy/db/migrations/20250703000000_obligations.sql

@@ -0,0 +1,115 @@
+-- +goose Up
+-- +goose StatementBegin
+
+CREATE TABLE IF NOT EXISTS obligation_definitions
+(
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    namespace_id UUID NOT NULL REFERENCES attribute_namespaces(id),
+    -- name is a unique identifier for the obligation definition within the namespace
+    name VARCHAR NOT NULL UNIQUE,
+    -- implicit index on unique (namespace_id, name) combo
+    -- index name: obligation_definitions_namespace_id_name_key
+    UNIQUE (namespace_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS obligation_values_standard
+(
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    obligation_definition_id UUID NOT NULL REFERENCES obligation_definitions(id),
+    -- value is a unique identifier for the obligation value within the definition
+    value VARCHAR NOT NULL UNIQUE,
+    -- implicit index on unique (obligation_definition_id, value) combo
+    -- index name: obligation_values_standard_obligation_definition_id_value_key
+    UNIQUE (obligation_definition_id, value)
+);
+
+CREATE TABLE IF NOT EXISTS obligation_triggers
+(
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    attribute_value_id UUID NOT NULL REFERENCES attribute_values(id),
+    obligation_value_id UUID NOT NULL REFERENCES obligation_values_standard(id)
+);
+
+CREATE TABLE IF NOT EXISTS obligation_fulfillers
+(
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    obligation_value_id UUID NOT NULL REFERENCES obligation_values_standard(id),
+    conditionals JSONB
+);
+
+CREATE TABLE IF NOT EXISTS obligation_action_attribute_values
+(
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    obligation_value_id UUID NOT NULL REFERENCES obligation_values_standard(id),
+    action_id UUID NOT NULL REFERENCES actions(id),
+    attribute_value_id UUID NOT NULL REFERENCES attribute_values(id),
+    UNIQUE(obligation_value_id, action_id, attribute_value_id)
+);
+
+CREATE OR REPLACE FUNCTION get_obligation_tables()
+RETURNS text[] AS $$
+BEGIN
+    RETURN ARRAY['obligation_definitions', 'obligation_values_standard', 
+                 'obligation_triggers', 'obligation_fulfillers', 
+                 'obligation_action_attribute_values'];
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION standardize_table(table_name regclass)
+RETURNS void AS $$
+BEGIN
+    -- Add standard columns to the table
+    EXECUTE FORMAT('
+        ALTER TABLE %I 
+        ADD COLUMN metadata JSONB,
+        ADD COLUMN created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        ADD COLUMN updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+    ', table_name);
+
+    -- Create trigger for updating updated_at column
+    EXECUTE FORMAT('
+        CREATE TRIGGER %I_updated_at
+        BEFORE UPDATE ON %I
+        FOR EACH ROW
+        EXECUTE FUNCTION update_updated_at()
+    ', table_name, table_name);    
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION standardize_tables(tables text[])
+RETURNS void AS $$
+DECLARE table_name text;
+BEGIN 
+    FOREACH table_name IN ARRAY tables
+    LOOP
+        PERFORM standardize_table(table_name::regclass);
+    END LOOP;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE OR REPLACE FUNCTION drop_tables(tables text[])
+RETURNS void AS $$
+DECLARE table_name text;
+BEGIN
+    FOREACH table_name IN ARRAY tables
+    LOOP
+        EXECUTE FORMAT('DROP TABLE IF EXISTS %I', table_name);
+    END LOOP;
+END;
+$$ LANGUAGE plpgsql;
+
+SELECT standardize_tables(get_obligation_tables());
+ALTER TABLE obligation_action_attribute_values DROP COLUMN IF EXISTS metadata;
+
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+
+SELECT drop_tables(get_obligation_tables());
+DROP FUNCTION IF EXISTS get_obligation_tables;
+DROP FUNCTION IF EXISTS standardize_table;
+DROP FUNCTION IF EXISTS standardize_tables;
+DROP FUNCTION IF EXISTS drop_tables;
+
+-- +goose StatementEnd

service/policy/db/schema_erd.md

@@ -132,6 +132,51 @@ erDiagram
         character_varying uri UK "URI of the KAS"
     }
 
+    obligation_action_attribute_values {
+        uuid action_id FK,UK 
+        uuid attribute_value_id FK,UK 
+        timestamp_with_time_zone created_at 
+        uuid id PK 
+        uuid obligation_value_id FK,UK 
+        timestamp_with_time_zone updated_at 
+    }
+
+    obligation_definitions {
+        timestamp_with_time_zone created_at 
+        uuid id PK 
+        jsonb metadata 
+        character_varying name UK 
+        uuid namespace_id FK,UK 
+        timestamp_with_time_zone updated_at 
+    }
+
+    obligation_fulfillers {
+        jsonb conditionals 
+        timestamp_with_time_zone created_at 
+        uuid id PK 
+        jsonb metadata 
+        uuid obligation_value_id FK 
+        timestamp_with_time_zone updated_at 
+    }
+
+    obligation_triggers {
+        uuid attribute_value_id FK 
+        timestamp_with_time_zone created_at 
+        uuid id PK 
+        jsonb metadata 
+        uuid obligation_value_id FK 
+        timestamp_with_time_zone updated_at 
+    }
+
+    obligation_values_standard {
+        timestamp_with_time_zone created_at 
+        uuid id PK 
+        jsonb metadata 
+        uuid obligation_definition_id FK,UK 
+        timestamp_with_time_zone updated_at 
+        character_varying value UK 
+    }
+
     provider_config {
         jsonb config "Configuration details for the key provider"
         timestamp_with_time_zone created_at "Timestamp when the provider configuration was created"
@@ -223,6 +268,7 @@ erDiagram
         timestamp_with_time_zone updated_at "Timestamp when the key was last updated"
     }
 
+    obligation_action_attribute_values }o--|| actions : "action_id"
     registered_resource_action_attribute_values }o--|| actions : "action_id"
     subject_mapping_actions }o--|| actions : "action_id"
     asym_key }o--|| provider_config : "provider_config_id"
@@ -239,17 +285,24 @@ erDiagram
     attribute_namespace_key_access_grants }o--|| key_access_servers : "key_access_server_id"
     attribute_namespace_public_key_map }o--|| attribute_namespaces : "namespace_id"
     attribute_namespace_public_key_map }o--|| key_access_server_keys : "key_access_server_key_id"
+    obligation_definitions }o--|| attribute_namespaces : "namespace_id"
     resource_mapping_groups }o--|| attribute_namespaces : "namespace_id"
     attribute_value_key_access_grants }o--|| attribute_values : "attribute_value_id"
     attribute_value_key_access_grants }o--|| key_access_servers : "key_access_server_id"
     attribute_value_public_key_map }o--|| attribute_values : "value_id"
     attribute_value_public_key_map }o--|| key_access_server_keys : "key_access_server_key_id"
+    obligation_action_attribute_values }o--|| attribute_values : "attribute_value_id"
+    obligation_triggers }o--|| attribute_values : "attribute_value_id"
     registered_resource_action_attribute_values }o--|| attribute_values : "attribute_value_id"
     resource_mappings }o--|| attribute_values : "attribute_value_id"
     subject_mappings }o--|| attribute_values : "attribute_value_id"
     base_keys }o--|| key_access_server_keys : "key_access_server_key_id"
     key_access_server_keys }o--|| key_access_servers : "key_access_server_id"
     key_access_server_keys }o--|| provider_config : "provider_config_id"
+    obligation_action_attribute_values }o--|| obligation_values_standard : "obligation_value_id"
+    obligation_values_standard }o--|| obligation_definitions : "obligation_definition_id"
+    obligation_fulfillers }o--|| obligation_values_standard : "obligation_value_id"
+    obligation_triggers }o--|| obligation_values_standard : "obligation_value_id"
     sym_key }o--|| provider_config : "provider_config_id"
     registered_resource_action_attribute_values }o--|| registered_resource_values : "registered_resource_value_id"
     registered_resource_values }o--|| registered_resources : "registered_resource_id"