ADR-008: Cognitive Artifact DSL (CADSL) for Generative UI

Status: Accepted Version: 1.0 Date: 2025-10-01 Supersedes: N/A Related ADRs: ADR-001, ADR-002, ADR-005, ADR-006 Related PRDs: PRD-010, PRD-011

Context

To enable the dynamic, AI-driven generation and rendering of interactive cognitive artifacts.

CADSL is not “just another UI schema” — it is the presentation projection of the Semantic Core and Knowledge Layer into the Cognitive Extension Layer, generated by the Artifact Engine and rendered by the CADSL Runtime.

Key constraints:

Part of isomorphic architecture — Semantic Core (DSL + SBVR) is canonical meaning; CADSL artifacts are projections
Cognitive Extension Layer contract — Dynamic artifacts to manage attention and intention
Runtime roles — Artifact Engine generates CADSL; Runtime parses, renders, captures interactions
ACE-compatible — Artifacts as evolving playbooks with small, composable units

Decision

Develop a Cognitive Artifact DSL (CADSL) based on a Mutually Exclusive, Collectively Exhaustive (MECE) set of symbolic elements, using a Semantic-first approach with optional layering.

Approach Selected: Semantic-First CADSL (Option B with Option C layering)

CADSL is primarily a cognitive artifact language, not a raw UI description. Low-level elements are present, but the language is centered on semantic structures that map to the Semantic Core and Knowledge Graph.

Approach Options Considered

Option	Description	Verdict
A: Thin UI DSL	CADSL as typed component tree, minimal semantics	❌ Undershoots SEA™’s semantic-first promise
B: Semantic-first CADSL	Cognitive artifacts as first-class, UI as projection	✅ Selected — Aligns with ADR-001/002/005/006
C: Hybrid/Layered	CADSL-S (Semantic) + CADSL-V (View) layers	✅ Incorporated as capability
D: Graph-native	Artifacts as views over CALM + KGS with queries	⏳ Future Phase 2/3 extension

Schema Requirements

Base CadslElement Schema

Every CADSL element must support:

id — Unique identifier within the artifact
type — Discriminator for element kind
semanticRef — Binding to Semantic Core / KGS / CALM elements
- Can be simple string (DSL/SBVR ID) or structured object with kind, id, source, label
- Kinds: Entity, Concept, Rule, Policy, Metric, GraphNode, GraphEdge, Other
cognitiveRole — How this element functions cognitively
- Values: note, input, output, control, decision, constraint, metric, context, example, annotation, navigation, other
metadata — Key-value pairs for element-specific metadata

CognitiveArtifact Schema

Every artifact must specify:

artifactType — Semantic type (e.g., project-planner, risk-assessment, adr-workbench)
purpose — Cognitive purpose (plan, decide, review, explore, learn)
cognitiveRole — High-level role (planning, decision-support, review, learning, monitoring, exploration, documentation)
semanticRefs — Artifact-level semantic bindings
canvas — Root-level CADSL elements

Implementation Approach

Tag MECE elements by role and layer — Content/Structural/Interactive/Annotation/Temporal/Feedback/Collaboration
Introduce semantic artifact type vocabulary — MVP: ProjectChecklist, RiskAssessment, ADRWorkbench, ArchitectureView
Artifact Engine generates semantic artifacts first — Then decorates with layout
Individual elements are stable, addressable units — Support ACE-style evolution (append, mark helpful/harmful, version)

Rationale

CADSL provides a structured, declarative language for defining cognitive artifacts, allowing the Artifact Engine to generate them programmatically. The MECE principle ensures comprehensive coverage of artifact types while avoiding redundancy, facilitating both generation and rendering across various user interfaces.

The semantic-first approach ensures:

Artifacts are views over semantic structures, not just pretty widgets
Knowledge Graph is genuinely useful — artifacts bound to DSL/SBVR concepts
Agentic context engineering — ACE-style “bullets” map to CADSL elements
Automated validation (SHACL, CALM) applies to artifacts via explicit semantics

Alternatives Considered

Hardcoded UI Templates

Rejected - Lack of flexibility and inability to support dynamic, context-aware artifact generation.

General-Purpose UI Frameworks

Rejected - Do not provide the semantic grounding or structured elements necessary for AI-driven artifact construction.

Constraints

MUST use semantic-first approach with CADSL artifacts as projections of Semantic Core
MUST support MECE set of symbolic elements
MUST bind artifacts to Semantic Core / KGS / CALM elements via semanticRef
MUST support ACE-style evolution (append, mark helpful/harmful, version)
MUST NOT treat CADSL as raw UI description language
MUST NOT use hardcoded UI templates

Quality Attributes

Highly flexible and dynamic artifact generation
Consistent artifact structure
Simplified UI rendering
Improved human-AI interaction
Direct binding to Semantic Core enables graph-aware artifacts
Same definition can render across platforms (web, chat, PDF)

Bounded Contexts Impacted

Cognitive Extension Layer
Semantic Core
Knowledge Layer
Artifact Engine
CADSL Runtime

Consequences

Positive

Highly flexible and dynamic artifact generation
Consistent artifact structure
Simplified UI rendering
Improved human-AI interaction
Direct binding to Semantic Core enables graph-aware artifacts
Same definition can render across platforms (web, chat, PDF)

Negative

Requires careful design of the CADSL and its elements
Development of a CADSL parser/renderer
More up-front taxonomy work for semantic artifact types
Requires tight integration with Semantic Core & KGS from day one

Additional Notes

REF-CE-001: CADSL Language Specification
SDS-002: Artifact Engine Service
SDS-003: CADSL Runtime & Renderer

✅ MVP