SDS-002: Semantic Core & DSL Management Service

sds: id: SDS-002 title: Semantic Core & DSL Management Service bounded_context: semantic-core satisfies_prds: [PRD-001, PRD-003] satisfies_adrs: [ADR-001, ADR-002] version: 1.1.0 status: approved owners: [“sea-core-team”] created: 2025-12-01 —

Addresses Requirements

• PRD-001: Unified Business Semantics
• PRD-003: Automated Rule Enforcement

Related ADRs

• ADR-001: Foundational Isomorphic Architecture
• ADR-002: Semantic Core Formalization

MVP Status

✅ MVP

Component Description

This service is responsible for managing the core DSL definitions and policies. It provides APIs for defining, validating, and retrieving semantic concepts and rules, ensuring a single source of truth for business semantics across the enterprise. It also includes a Policy Evaluator for automated enforcement.

Technical Details

Interfaces

Protocols

• REST API (JSON) - External access
• Internal gRPC - High-performance rule evaluation

Data Model

Refer to SDS-001: Data Model Schemas for:

• Entity schema
• Resource schema
• Flow schema
• Instance schema
• Policy schema

API Specification

Endpoints

Request/Response

Define DSL Concept

1
2
3
4
5
6
7
8
POST /dsl/define
{
  "concept": {
    "name": "Customer",
    "type": "Entity",
    "attributes": {...}
  }
}

Evaluate Policy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
POST /policy/evaluate
{
  "policyId": "order-minimum-value",
  "data": {
    "orderId": "123",
    "totalValue": 5.00
  }
}

// Response
{
  "valid": false,
  "violations": [
    {
      "rule": "order-minimum-value",
      "message": "Order total must be at least $10"
    }
  ]
}

Error Codes

Dependencies

Port Reference

This service integrates with the following hexagonal ports:

The PolicyEnginePort provides:

• evaluate(input: PolicyInput): Promise<PolicyDecision> — Evaluate policy rules
• isAllowed(user, action, resource): Promise<boolean> — Authorization check
• listPolicies(): Promise<string[]> — List available policies

Error Handling

• Detailed error messages for semantic inconsistencies and rule violations
• Robust transaction management for DSL updates
• Rollback capability for failed batch operations

Performance Considerations

• Optimized query performance for semantic concepts
• Low-latency rule evaluation for critical business processes
• Caching of frequently accessed concepts
• Indexed lookups for rule matching

Security Considerations

• Access control for defining and modifying core semantics
• Role-based permissions (Admin, Editor, Viewer)
• Secure storage of sensitive business rules
• Audit logging for all modifications

Testing Strategy

• Unit Tests: DSL parsing and Policy validation
• Integration Tests: Rule enforcement against various data scenarios
• Performance Tests: Rule evaluation latency under load
• Contract Tests: API compatibility verification

8. Semantic Authority Protocol

This section defines the versioning and synchronization contract that ensures downstream consumers (particularly the Isomorphic Semantic Compiler, SDS-027) operate on consistent semantic model snapshots.

8.1. Version Counter

Every mutation to the semantic model increments a monotonic version counter:

8.2. Versioned Query API

Stale Query Behavior:

• If requested_version < current_version: Return 409 Conflict with message "Semantic model has advanced to v{current}"
• If requested_version == current_version: Return normal response
• If requested_version > current_version: Return 400 Bad Request (future version requested)

8.3. Change Notification Events

On every semantic model mutation, emit:

1
2
3
4
5
6
7
8
9
10
11
{
  "type": "governance.semantic-model.updated",
  "source": "//core/semantic-registry",
  "data": {
    "previousVersion": 5,
    "currentVersion": 6,
    "changedConcepts": ["Customer", "Order"],
    "changedPolicies": ["order-minimum-value"],
    "timestamp": "2025-12-31T10:00:00Z"
  }
}

8.4. Consumer Contract

Downstream services (e.g., SDS-027 Isomorphic Semantic Compiler) MUST:

1. Query with explicit version parameter
2. Subscribe to governance.semantic-model.updated for cache invalidation
3. Include semanticVersion in output provenance for audit trail

8.5. Related Specifications

• SDS-027 §10: Semantic Authority Integration — Compiler-side version binding