Capabilities & Providers

The Abstraction Model

PatternOps separates what from how using two concepts:

• Capability — A stable, technology-independent contract defining operations
• Provider — A pluggable implementation that fulfils a capability using a specific technology

graph LR
    subgraph "Stable (never changes)"
        C[Capability Contract]
    end
    subgraph "Pluggable (swap freely)"
        P1[Provider: Spark]
        P2[Provider: Snowflake]
        P3[Provider: dbt]
    end
    C --> P1
    C --> P2
    C --> P3

Base Provider Contract

Every provider must implement the base lifecycle:

public interface BaseProviderContract {
    ValidationResult validateConfig(Map<String, Object> config);
    void initialise(Map<String, Object> config);
    HealthStatus healthCheck();
    List<MetricsEnvelope> metrics();
    void cleanup();
}

Lifecycle: validateConfig → initialise → (operational methods) → cleanup

Capability Catalogue

PatternOps defines 21 capability contracts:

Capability	Contract Methods	Sub-capabilities
Source Acquisition	connect, discover_schema, acquire, checkpoint, resume, disconnect	—
Execution	validate_pipeline, submit, status, cancel, metrics, logs, cleanup	—
Orchestration	submit, schedule, retry, cancel, pause, resume, observe, recover	—
Messaging	publish, consume, acknowledge, dead_letter, replay, metrics	—
State Management	write, read, query, delete, checkpoint, restore	—
Storage	write, read, list, commit, validate_path, apply_retention, apply_security	—
Replication	replicate, synchronise, verify, resume, monitor	—
Security	—	Classification, Encryption, Tokenisation, Secret Management
Data Quality	profile, validate, monitor, trend, detect_anomaly	—
Transformation	validate, execute, explain, lineage, optimise	—
Extension	execute, validate, supported_hook_types	—
Observability	export_traces, export_metrics, export_logs, health_status, configure_alerts	—
Lineage	emit_lineage, publish_lineage, query_lineage, export_lineage	—
Metrics	emit_metric	—
Data Contract	generate_contract, validate_contract, publish_contract, check_compatibility, deprecate	—
Schema Registry	—	Messaging (Kafka-style), General (datasets/APIs)
Version Control	commit, get_version, get_latest, list_versions, diff, rollback, tag	—

Security Sub-Capabilities

Security is split into four independent contracts:

// Classification
interface ClassificationContract extends BaseProviderContract {
    ClassificationResult classify(String fieldId, Object value);
    void tag(String fieldId, String classification);
    RiskScore scoreRisk(String fieldId);
}

// Encryption
interface EncryptionContract extends BaseProviderContract {
    EncryptionResult encrypt(byte[] data, String keyReference);
    byte[] decrypt(byte[] ciphertext, String keyReference);
    void rotateKeys(String keyReference);
}

// Tokenisation
interface TokenisationContract extends BaseProviderContract {
    String tokenise(String sensitiveValue);
    String detokenise(String token);
    boolean validate(String token);
}

// Secret Management
interface SecretManagementContract extends BaseProviderContract {
    String resolveSecret(String secretId);
    void rotateSecret(String secretId);
    boolean validateAccess(String secretId, String principal);
}

Schema Registry Sub-Capabilities

Two specialised registries:

Registry	Use Case	Key Operations
Messaging	Kafka-style subject/version schemas	register, get, check_compatibility, list_subjects
General	Datasets, APIs, configs	register, evolve, compare_versions, deprecate

Implementing a Provider

public class PostgresStateProvider implements StateManagementContract {

    @Override
    public ValidationResult validateConfig(Map<String, Object> config) {
        // Validate connection string, pool size, etc.
    }

    @Override
    public void initialise(Map<String, Object> config) {
        // Create connection pool
    }

    @Override
    public void write(String key, Object state) {
        // INSERT or UPDATE in PostgreSQL
    }

    @Override
    public Object read(String key) {
        // SELECT from PostgreSQL
    }

    // ... remaining contract methods
}

Provider Resolution

The Provider Registry resolves capabilities at runtime:

// Resolve by capability
BaseProviderContract provider = registry.resolve("source-acquisition", tenancyContext);

// Resolve by sub-capability
BaseProviderContract encryptor = registry.resolveSubCapability(
    "security", "encryption", tenancyContext);

Resolution is scoped by tenancy and namespace, enabling different providers per tenant.

Provider Registration

ProviderDescriptor descriptor = new ProviderDescriptor(
    "postgres-state-v1",           // id
    "PostgreSQL State Provider",    // name
    "state-management",             // capability
    null,                           // sub-capability (none)
    "1.0.0",                        // version
    List.of("write", "read", "query", "delete", "checkpoint", "restore"),
    Map.of("connectionUrl", "jdbc:postgresql://..."),
    List.of(ComputePlatformProfile.AWS_NATIVE, ComputePlatformProfile.AZURE_NATIVE)
);

registry.register(descriptor);