Merge pull request #7 from gram-data/006-gram-hs-migration

006 gram hs migration

Author: akollegger

.cursor/rules/specify-rules.mdc

@@ -9,6 +9,8 @@ Auto-generated from all feature plans. Last updated: 2025-12-19
 - Haskell (GHC 9.10.3), Cabal build system + gram-hs (source repository), text, containers, megaparsec, mtl, hspec, QuickCheck (004-implementation-consistency-review)
 - N/A (documentation review, no data storage) (004-implementation-consistency-review)
 - N/A - In-memory data structures only (005-keywords-maps-sets)
+- Haskell (GHC 9.10.3, base >=4.18 && <5) + gram-hs library (pattern, subject, gram packages), Cabal build system (006-gram-hs-migration)
+- N/A (in-memory pattern structures) (006-gram-hs-migration)
 
 - Haskell with GHC 9.6.3 (see research.md for version selection rationale) + gram-hs (source repository from GitHub), text, containers, megaparsec, mtl, hspec, QuickCheck (001-pattern-lisp-init)
 
@@ -29,9 +31,9 @@ tests/
 Haskell with GHC 9.6.3 (see research.md for version selection rationale): Follow standard conventions
 
 ## Recent Changes
+- 006-gram-hs-migration: Added Haskell (GHC 9.10.3, base >=4.18 && <5) + gram-hs library (pattern, subject, gram packages), Cabal build system
 - 005-keywords-maps-sets: Added Haskell (GHC 9.10.3)
 - 004-implementation-consistency-review: Added Haskell (GHC 9.10.3), Cabal build system + gram-hs (source repository), text, containers, megaparsec, mtl, hspec, QuickCheck
-- 003-pattern-state-functions: Added Haskell with GHC 9.10.3 (as per existing project setup)
 
 
 <!-- MANUAL ADDITIONS START -->

.github/workflows/build-and-test.yml

@@ -48,7 +48,8 @@ jobs:
           ${{ runner.os }}-dist-${{ matrix.ghc-version }}-
     
     - name: Configure Cabal
-      run: cabal update
+      run: |
+        cabal update
     
     - name: Build project
       run: cabal build --ghc-options="-Wall" all

docs/pattern-state-lisp-design.md

@@ -38,7 +38,7 @@ Where:
 ```scheme
 ;; Pure function, runtime handles state threading
 (lambda (state)
-  (pattern-with 
+  (pattern 
     (pattern-value state)
     (cons new-item (pattern-elements state))))
 ```
@@ -54,7 +54,7 @@ Tools in Pattern Agents are naturally `Pattern v -> Pattern v` transformations:
 (lambda (state)
   (let* ((user (pattern-find state is-user?))
          (name (pattern-query user "$.name")))
-    (pattern-with 
+    (pattern 
       {:greeting (string-append "Hello, " name)}
       (pattern-elements state))))
 ```
@@ -72,7 +72,7 @@ Tools compose as functions:
 (define format-greeting
   (lambda (state)
     (let ((user (get-user state)))
-      (pattern {:greeting (string-append "Hello, " (pattern-value user))}))))
+      (pure {:greeting (string-append "Hello, " (pattern-value user))}))))
 
 ;; Compose: format-greeting ∘ get-user
 (define greet-user 
@@ -177,8 +177,8 @@ Pattern is a **native Lisp value type**, not accessed through host-calls.
 
 ```scheme
 ;; Pattern construction
-(pattern value)                    ; Atomic pattern
-(pattern-with value elements)      ; Pattern with elements
+(pure value)                       ; Atomic pattern
+(pattern value elements)          ; Pattern with elements
 (from-list value [v1 v2 v3])      ; Convenience constructor
 
 ;; Pattern transformation (returns new pattern)
@@ -220,7 +220,7 @@ Since programs are pure, **host-calls** are the only mechanism for side effects:
                         "SELECT * FROM users WHERE id = ?" 
                         user-id)))
       ;; Incorporate result into new state pattern
-      (pattern-with 
+      (pattern 
         {:query-result db-result}
         (pattern-elements state)))))
 ```
@@ -316,12 +316,12 @@ executeTool toolName runtime = do
              (db-result (host-call 'db-query 
                           "SELECT * FROM orders WHERE id = ?" 
                           order-id))
-             (order-pattern (pattern-with 
+             (order-pattern (pattern 
                              {:type "Order"
                               :id order-id
                               :data db-result}
                              [])))
-        (pattern-with
+        (pattern
           (pattern-value state)
           (cons order-pattern (pattern-elements state)))))
   ]
@@ -337,14 +337,14 @@ executeTool toolName runtime = do
          (db-result (host-call 'db-query 
                       "SELECT * FROM orders WHERE id = ?" 
                       order-id))
-         (order-pattern (pattern-with 
-                         {:type "Order"
-                          :id order-id
-                          :data db-result}
-                         [])))
-    (pattern-with
-      (pattern-value state)
-      (cons order-pattern (pattern-elements state)))))
+             (order-pattern (pattern 
+                             {:type "Order"
+                              :id order-id
+                              :data db-result}
+                             [])))
+        (pattern
+          (pattern-value state)
+          (cons order-pattern (pattern-elements state)))))
 ```
 
 ## Benefits for Pattern Agents

docs/plisp-serialization-design.md

@@ -606,7 +606,7 @@ Every Pattern Lisp runtime provides a standard environment (`initialEnv`) contai
 - Arithmetic primitives: `+`, `-`, `*`, `/`
 - Comparison primitives: `>`, `<`, `=`, `/=`
 - String primitives: `string-append`, `string-length`, `substring`
-- Pattern primitives: `pattern`, `pattern-with`, `pattern-value`, etc.
+- Pattern primitives: `pure`, `pattern`, `pattern-value`, etc.
 
 ### Environment Filtering
 
@@ -1245,10 +1245,10 @@ Pattern Subject → Check Label:
 **S-expression**:
 ```scheme
 (lambda (state)
-  (pattern-with
+  (pattern
     (pattern-value state)
     (cons
-      (pattern "new-item")
+      (pure "new-item")
       (pattern-elements state))))
 ```
 
@@ -1262,7 +1262,7 @@ Pattern Subject → Check Label:
     [:Parameters | state],
     [:Body |
       [:List |
-        [:Symbol {name: "pattern-with"}],
+        [:Symbol {name: "pattern"}],
         [:List | [:Symbol {name: "pattern-value"}], state],
         [:List |
           [:Symbol {name: "cons"}],

examples/pattern-basics.plisp

@@ -2,10 +2,10 @@
 ;; Demonstrates creating and querying Pattern values
 
 ;; Create an atomic pattern
-(define hello (pattern "hello"))
+(define hello (pure "hello"))
 
 ;; Create a pattern with elements (empty for now)
-(define root (pattern-with "root" '()))
+(define root (pattern "root" '()))
 
 ;; Query pattern decoration
 (pattern-value hello)

examples/pattern-predicates.plisp

@@ -9,9 +9,9 @@
 ;; ============================================================================
 
 ;; Create some atomic patterns for testing
-(define p1 (pattern 10))
-(define p2 (pattern 20))
-(define p3 (pattern 30))
+(define p1 (pure 10))
+(define p2 (pure 20))
+(define p3 (pure 30))
 
 ;; pattern-find: Find the first matching subpattern
 ;; Returns the matching pattern, or empty list if no match

specs/003-pattern-state-functions/quickstart.md

@@ -35,11 +35,11 @@ cabal build all
 
 ```scheme
 ;; Create an atomic pattern
-(define atomic (pattern "hello"))
+(define atomic (pure "hello"))
 
 ;; Create a pattern with elements
-(define with-elements (pattern-with "root" 
-  (list (pattern "child1") (pattern "child2"))))
+(define with-elements (pattern "root" 
+  (list (pure "child1") (pure "child2"))))
 ```
 
 ### 2. Querying Pattern Values
@@ -64,10 +64,10 @@ All tools must follow the canonical form `(lambda (state) ...)`:
 ```scheme
 ;; Simple tool that adds a greeting
 (lambda (state)
-  (pattern-with 
+  (pattern 
     (pattern-value state)  ; Preserve decoration
     (cons 
-      (pattern "Hello from Pattern Lisp!")
+      (pure "Hello from Pattern Lisp!")
       (pattern-elements state))))
 ```
 
@@ -173,13 +173,13 @@ Deserializes runtime from a Gram file and resumes execution.
 (lambda (state)
   (let ((count (pattern-size state))
         (depth (pattern-depth state)))
-    (pattern-with
+    (pattern
       (pattern-value state)
-      (cons 
-        (pattern-with "summary" 
-          (list 
-            (pattern count)
-            (pattern depth)))
+      (cons
+        (pattern "summary" 
+          (list
+            (pure count)
+            (pure depth)))
         (pattern-elements state)))))
 
 ;; 2. Save to file: state-reader.plisp
@@ -269,13 +269,13 @@ it "round-trips closures" $ do
 ;; Define multiple tools
 (define add-timestamp
   (lambda (state)
-    (pattern-with (pattern-value state)
-      (cons (pattern "timestamp") (pattern-elements state)))))
+    (pattern (pattern-value state)
+      (cons (pure "timestamp") (pattern-elements state)))))
 
 (define add-metadata
   (lambda (state)
-    (pattern-with (pattern-value state)
-      (cons (pattern "metadata") (pattern-elements state)))))
+    (pattern (pattern-value state)
+      (cons (pure "metadata") (pattern-elements state)))))
 
 ;; Compose tools
 (lambda (state)
@@ -289,9 +289,9 @@ it "round-trips closures" $ do
 (lambda (state)
   (let ((incrementer (lambda (x) (+ x 1)))
         (doubler (lambda (x) (* x 2))))
-    (pattern-with "functions"
-      (list (pattern incrementer)
-            (pattern doubler)))))
+    (pattern "functions"
+      (list (pure incrementer)
+            (pure doubler)))))
 ```
 
 ### State Filtering
@@ -302,7 +302,7 @@ it "round-trips closures" $ do
   (let ((filtered (pattern-find state 
                     (lambda (p) 
                       (> (pattern-size p) 1)))))
-    (pattern-with "filtered" (list filtered))))
+    (pattern "filtered" (list filtered))))
 ```
 
 ## Troubleshooting

specs/006-gram-hs-migration/checklists/requirements.md

@@ -0,0 +1,38 @@
+# Specification Quality Checklist: Gram-HS Library Migration
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-01-28
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Migration is a technical task but has been framed from developer/user perspective
+- Success criteria include measurable outcomes (100% test pass rate, zero occurrences of old API)
+- Edge cases cover nested patterns, closures, and serialization scenarios
+- Scope is clearly bounded to constructor migration only
+

specs/006-gram-hs-migration/contracts/README.md

@@ -0,0 +1,40 @@
+# Contracts: Gram-HS Constructor Migration
+
+**Date**: 2025-01-28
+
+## Overview
+
+This migration is an internal refactoring task that updates constructor function names. No external API contracts change - this is purely an internal implementation detail.
+
+## Internal API Changes
+
+### Pattern Constructor Functions
+
+**Before**:
+- `pattern :: v -> Pattern v` (atomic)
+- `patternWith :: v -> [Pattern v] -> Pattern v` (with elements)
+
+**After**:
+- `point :: v -> Pattern v` (atomic)
+- `pattern :: v -> [Pattern v] -> Pattern v` (with elements)
+
+## Impact
+
+- **External API**: No changes - Pattern Lisp public API unchanged
+- **Internal API**: Constructor function names changed
+- **Serialization Format**: Unchanged - gram notation format unchanged
+- **Behavior**: Unchanged - only constructor names differ
+
+## Migration Contract
+
+All internal code using Pattern constructors must:
+1. Use `point` for atomic patterns
+2. Use `pattern` for patterns with elements
+3. Import `Pattern.Core (point, pattern, ...)` instead of `Pattern.Core (pattern, patternWith, ...)`
+
+## Verification
+
+- Type checker enforces correct usage
+- Test suite verifies functional correctness
+- No external contract changes required
+