039 representation map

[akollegger]

This pull request introduces the new "RepresentationMap" feature to the Pattern library, enabling named, invertible, composable mappings between different kinds of pattern shapes. It adds the concept of "pattern kinds" (named subtypes of patterns) and provides a framework for defining and composing isomorphisms between them. The changes include new modules, API extensions, and corresponding test scaffolding, all without introducing new dependencies.

Core library enhancements:

• Added the PatternKind type and checkKind function to Pattern.Core, allowing for named, scope-aware classification of pattern families. This enables predicates and runtime compatibility checks for pattern kinds. [1] [2] [3] [4]
• Introduced the new module Pattern.RepresentationMap, which defines the RepresentationMap type for invertible mappings between pattern kinds, and provides the compose function for safe composition of compatible maps. [1] [2] [3] [4] [5]

Testing and documentation:

• Added Spec.Pattern.RepresentationMapSpec to the test suite and integrated it into the test runner, ensuring that RepresentationMap functionality is covered by property and unit tests. [1] [2] [3]
• Updated documentation and feature tracking files (CLAUDE.md, specification checklists, and contracts) to reflect the new feature, its requirements, and API contracts. [1] [2] [3] [4]

Project configuration:

• Enabled tests for the pattern package in cabal.project and ensured no new dependencies were introduced for this feature.

These changes lay the groundwork for future development of declarative, machine-checkable representation maps and enable richer pattern shape transformations within the Pattern library.

[kilo-code-bot]

Code Review Summary

Status: All Issues Resolved | Recommendation: Merge

Previous Issues (Resolved)

File	Line	Status
libs/pattern/src/Pattern/RepresentationMap.hs	49	✅ Resolved - Record selectors renamed to prefixed scheme (repMapName, repMapDomain, etc.)
libs/pattern/tests/Spec/Pattern/RepresentationMapSpec.hs	N/A	✅ Resolved - graphNodeFromSubject removed
libs/pattern/tests/Spec/Pattern/RepresentationMapSpec.hs	N/A	✅ Resolved - Unused Property import removed

Files Reviewed (8 files)

• libs/pattern/src/Pattern/Core.hs - Added PatternKind type and checkKind function
• libs/pattern/src/Pattern/RepresentationMap.hs - New module with RepresentationMap type (now using prefixed record selectors) and compose function
• libs/pattern/tests/Spec/Pattern/RepresentationMapSpec.hs - Comprehensive test suite (now warning-clean)
• libs/pattern/pattern.cabal - Package configuration updates
• libs/pattern/src/Pattern.hs - Module re-exports
• cabal.project - Test enablement for pattern package
• CLAUDE.md - Documentation updates
• specs/039-representation-map/ - Feature specification documents

---

Review Details:

The PR implements the RepresentationMap feature with:

1. PatternKind (Pattern.Core) - A named, scope-aware classification of pattern families with a membership predicate and canonical example
2. RepresentationMap (Pattern.RepresentationMap) - An invertible mapping between pattern kinds with forward/inverse transforms and round-trip verification (now using repMapName, repMapDomain, repMapCodomain, repMapForward, repMapInverse, repMapRoundTrip)
3. compose - Function to combine compatible representation maps with proper error handling for incompatible kinds
4. Comprehensive tests - Unit tests and QuickCheck property-based tests validating kind membership, transforms, and round-trip correctness

No security vulnerabilities, runtime errors, or logic bugs were identified. All previously identified issues have been addressed. The implementation follows Haskell best practices and the existing codebase patterns.

[Copilot]

Pull request overview

This PR introduces a new “RepresentationMap” abstraction to the pattern library, adding a way to name pattern “kinds” and define invertible, composable mappings between them, with accompanying tests and spec documentation.

Changes:

• Added PatternKind + checkKind to Pattern.Core for named, scope-aware shape classification.
• Added Pattern.RepresentationMap with RepresentationMap and compose for safe map composition.
• Wired in a new HSpec/QuickCheck test module validating kind checks, composition, and a concrete diagnosticMap round-trip.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
libs/pattern/src/Pattern/Core.hs	Adds PatternKind and checkKind to the core API alongside ScopeQuery.
libs/pattern/src/Pattern/RepresentationMap.hs	Introduces RepresentationMap and compose for invertible, composable mappings.
libs/pattern/src/Pattern.hs	Re-exports Pattern.RepresentationMap from the main convenience module.
libs/pattern/pattern.cabal	Exposes Pattern.RepresentationMap and includes the new spec in the test suite.
libs/pattern/tests/Test.hs	Registers Spec.Pattern.RepresentationMapSpec in the test runner.
libs/pattern/tests/Spec/Pattern/RepresentationMapSpec.hs	Adds unit + property tests plus a concrete diagnosticMap example.
cabal.project	Enables tests for the pattern package at the project level.
specs/039-representation-map/spec.md	Feature specification for RepresentationMap.
specs/039-representation-map/plan.md	Implementation plan and acceptance criteria.
specs/039-representation-map/tasks.md	Task breakdown by phase/user story.
specs/039-representation-map/research.md	Design decisions (String vs Text, QuickCheck, RankNTypes, etc.).
specs/039-representation-map/data-model.md	Data model + invariants for PatternKind / RepresentationMap.
specs/039-representation-map/quickstart.md	Quick reference and usage snippets for the new APIs.
specs/039-representation-map/contracts/Pattern.Core.hs	Contract doc for PatternKind additions.
specs/039-representation-map/contracts/Pattern.RepresentationMap.hs	Contract doc for RepresentationMap + compose.
specs/039-representation-map/checklists/requirements.md	Requirements/spec quality checklist for the feature.
proposals/representation-map-proposal.md	Broader proposal/design context captured for future work.
CLAUDE.md	Updates feature tracking/tech notes to mention 039 work.