Research

.github/PULL_REQUEST_TEMPLATE.md

@@ -32,11 +32,9 @@ Fixes #
 
 <!-- Describe the tests you ran to verify your changes -->
 
-- [ ] All existing tests pass (`composer test`)
+- [ ] Root PHP validation passes (`composer test`)
+- [ ] Playground build passes (`cd playground && npm run build`) when relevant
 - [ ] Added new tests for the changes
-- [ ] Static analysis passes (`composer test:types`)
-- [ ] Code coverage remains at 100%
-- [ ] Mutation testing passes (`composer test:infection`)
 
 ## Code Quality Checklist
 
@@ -47,6 +45,7 @@ Fixes #
 - [ ] My changes generate no new warnings or errors
 - [ ] I have added tests that prove my fix is effective or that my feature works
 - [ ] New and existing unit tests pass locally with my changes
+- [ ] I have noted whether the change affects the root implementation, the playground, the spec, or `legacy/`
 
 ## Documentation
 

.github/copilot-instructions.md

@@ -1,224 +1,40 @@
-# Copilot Agent Instructions for Axiom Library
+# Copilot Agent Instructions for Axiom
 
 ## Repository Overview
 
-This is a proprietary PHP library for **data transformation, type validation, and expression evaluation**. The library provides a flexible framework for defining data schemas, transforming values, and evaluating complex expressions with type safety using functional programming principles.
+This repository is in transition toward a spec-driven Axiom v1 DSL project.
 
-**Repository Stats:**
-- **Language:** PHP (100%)
-- **Size:** ~30 source files, ~20 test files
-- **Type:** Library package (`gosuperscript/axiom`)
-- **Architecture:** Functional programming with monadic error handling
+There are three distinct surfaces:
 
-**Key Features:**
-- Type system for numbers, strings, booleans, lists, and dictionaries
-- Expression evaluation with infix and unary expressions
-- Pluggable resolver pattern for different data sources
-- Symbol registry for named value resolution
-- Operator overloading system
-- Built on Result and Option monads for error handling
+- `axiom-v1-spec.md`: the primary language source of truth
+- `src/` and `tests/`: the fresh root PHP implementation surface
+- `playground/`: the experimental TypeScript playground
 
-## Build and Validation Instructions
+The old PHP library has been archived under `legacy/`. Do not treat `legacy/`
+as the active implementation unless a task explicitly targets it.
 
-### Environment Requirements
-- **PHP:** 8.4+ (strictly enforced)
-- **Extensions:** ext-intl (required)
-- **Docker:** Recommended for development (8.4-cli-alpine image)
+## Working Rules
 
-### Setup Commands
-**ALWAYS run these commands in the specified order:**
+- Prefer the current Axiom v1 specification over legacy implementation behavior.
+- Keep the root PHP implementation small and deliberate.
+- Treat the playground as a validation tool, not as the language definition.
+- Avoid reintroducing old library abstractions just because they exist in
+  `legacy/`.
 
-1. **Install Dependencies:**
-   ```bash
-   composer install
-   ```
-   - **Precondition:** PHP 8.4+ must be available
-   - **Time:** ~30-60 seconds
-   - **Note:** May require GitHub token for private repositories
+## Validation
 
-2. **Docker Setup (if PHP 8.4 unavailable):**
-   ```bash
-   docker compose build
-   docker compose run --rm php composer install
-   ```
-   - **Time:** 2-5 minutes for initial build
-   - **Note:** Network connectivity required for base image
-
-### Testing Commands
-**100% code coverage is required for all new code.**
+For root PHP changes:
 
 ```bash
-# Run all tests (recommended)
 composer test
-
-# Individual test suites
-composer test:unit      # PHPUnit tests (requires 100% coverage)
-composer test:types     # PHPStan static analysis (level max)
-composer test:infection # Mutation testing (100% MSI required)
 ```
 
-**Test Execution Times:**
-- Unit tests: ~10-30 seconds
-- Static analysis: ~5-15 seconds  
-- Mutation testing: ~1-3 minutes
-
-### Code Quality Tools
-
-1. **PHPStan (Static Analysis):**
-   ```bash
-   vendor/bin/phpstan analyse
-   ```
-   - Level: max (strictest)
-   - **Always pass** before submitting changes
-
-2. **Laravel Pint (Code Formatting):**
-   ```bash
-   vendor/bin/pint
-   ```
-   - Preset: PER (PHP Evolving Recommendations)
-   - Auto-fixes code style issues
+For playground changes:
 
-3. **Infection (Mutation Testing):**
-   ```bash
-   vendor/bin/infection --threads=max --show-mutations
-   ```
-   - Minimum MSI: 100% (all mutants must be killed)
-   - **Critical:** Tests quality validation
-
-### Docker Environment
 ```bash
-# Build environment
-docker compose build
-
-# Run commands in container
-docker compose run --rm php composer install
-docker compose run --rm php composer test
-docker compose run --rm php vendor/bin/phpstan analyse
-```
-
-## Project Layout and Architecture
-
-### Core Architecture Patterns
-- **Strategy Pattern:** Different resolvers for different source types
-- **Chain of Responsibility:** DelegatingResolver chains multiple resolvers  
-- **Factory Pattern:** Type system creates appropriate transformations
-- **Functional Programming:** Result and Option monads throughout
-
-### Directory Structure
+cd playground
+npm run build
 ```
-src/
-├── Exceptions/          # Custom exception classes
-├── Operators/           # Operator overloading system
-├── Resolvers/           # Source resolution strategies
-├── Sources/             # Data source definitions
-├── Types/               # Type validation and transformation
-├── Source.php           # Base source interface
-└── SymbolRegistry.php   # Named value registry
-
-tests/
-├── KitchenSink/         # Integration tests
-├── Operators/           # Operator tests
-├── Resolvers/           # Resolver tests
-├── Types/               # Type system tests
-└── *Test.php            # Unit tests
-```
-
-### Key Source Files
-
-**Core Interfaces:**
-- `src/Source.php` - Base interface for all data sources
-- `src/Resolvers/Resolver.php` - Resolver interface template
-- `src/Types/Type.php` - Type transformation interface
-
-**Main Implementation:**
-- `src/Resolvers/DelegatingResolver.php` - Main resolver chain
-- `src/SymbolRegistry.php` - Symbol management
-- `src/Types/NumberType.php` - Example type implementation
-
-### Configuration Files
-
-**Build Configuration:**
-- `composer.json` - Dependencies and scripts
-- `phpunit.xml.dist` - Test configuration
-- `phpstan.neon.dist` - Static analysis rules
-- `infection.json5` - Mutation testing config
-- `pint.json` - Code style rules
-
-**Docker Configuration:**
-- `Dockerfile` - PHP 8.4 Alpine development environment
-- `docker-compose.yaml` - Development services
-
-### GitHub Workflows
-Located in `.github/workflows/tests.yaml`:
-- **Test Job:** Runs on PHP 8.4 with matrix for prefer-lowest/prefer-stable
-- **Types Job:** Static analysis validation
-- **Timeout:** 5 minutes per job
-- **Extensions:** Includes intl, bcmath, and testing extensions
-
-### Dependencies
-
-**Production:**
-- `azjezz/psl` - PHP Standard Library utilities
-- `brick/math` - Arbitrary precision mathematics
-- `gosuperscript/monads` - Result/Option monad implementation
-- `illuminate/container` - Dependency injection container
-- `sebastian/exporter` - Value exporting utilities
-
-**Development:**
-- `phpunit/phpunit` (v12.0+) - Testing framework
-- `phpstan/phpstan` (v2.1+) - Static analysis
-- `infection/infection` - Mutation testing
-- `laravel/pint` - Code formatting
-
-### Validation Pipeline
-
-**Local Development Checklist:**
-1. Run `composer test:types` (must pass)
-2. Run `composer test:unit` (100% coverage required)  
-3. Run `composer test:infection` (100% MSI required)
-4. Optionally run `vendor/bin/pint` for formatting
-
-**CI/CD Validation:**
-- All tests run on PHP 8.4 only
-- Matrix testing with prefer-lowest and prefer-stable
-- Parallel execution of unit tests and static analysis
-- **No deployment** - library package only
-
-### Common Patterns and Usage
-
-**Creating New Types:**
-- Implement `Type` interface with transform(), compare(), format()
-- Return `Result<Option<T>, Throwable>` from transform()
-- Use functional approach with Result monads
-
-**Creating New Resolvers:**
-- Implement `Resolver` interface 
-- Add static supports() method for source type checking
-- Register in DelegatingResolver constructor array
-
-**Error Handling:**
-- All operations return Result types (Ok/Err)
-- No exceptions for normal control flow
-- Option types handle null/empty values safely
-
-### Testing Requirements
-
-**Code Coverage:** 100% line coverage mandatory
-**Mutation Testing:** 100% Mutation Score Indicator required
-**Static Analysis:** PHPStan level max with no errors
-
-**Test Structure:**
-- Use PHPUnit 12+ attributes (`#[Test]`, `#[CoversClass]`)
-- Integration tests in `tests/KitchenSink/`
-- Unit tests mirror source structure
-- Use `#[CoversNothing]` for integration tests
-
----
-
-## Agent Instructions
-
-**Trust these instructions** and only search/explore when information is incomplete or incorrect. This repository requires PHP 8.4 and has strict quality requirements - always validate changes with the full test suite before submitting.
 
-**For type system changes:** Focus on functional programming patterns and monadic error handling.
-**For resolver changes:** Follow the chain of responsibility pattern and ensure proper source type checking.
-**For new features:** Maintain 100% test coverage and mutation score requirements.
+Run only the relevant validations for the surfaces you change, and say what you
+did not run.

.github/workflows/tests.yaml

@@ -1,18 +1,14 @@
-name: Tests
+name: Validation
 
 on:
   push:
+  pull_request:
 
 jobs:
-  test:
+  php:
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    strategy:
-      matrix:
-        php: [8.4]
-        stability: [prefer-lowest, prefer-stable]
-
-    name: P${{ matrix.php }} - ${{ matrix.stability }}
+    name: PHP
 
     steps:
       - name: Checkout code
@@ -21,54 +17,39 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: ${{ matrix.php }}
+          php-version: 8.4
           extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo
-          coverage: pcov
+          coverage: none
 
       - name: Setup problem matchers
         run: |
           echo "::add-matcher::${{ runner.tool_cache }}/php.json"
           echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
 
       - name: Install dependencies
-        run: composer update --${{ matrix.stability }} --prefer-dist --no-interaction
-
-      - name: List Installed Dependencies
-        run: composer show -D
-
-      - name: Execute unit tests
-        run: composer test:unit
+        run: composer install --prefer-dist --no-interaction
 
-      - name: Execute mutation tests
-        run: composer test:infection
+      - name: Execute PHP validation
+        run: composer test
 
-  types:
+  playground:
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    strategy:
-      matrix:
-        php: [8.4]
-
-    name: Static analysis
+    name: Playground
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
+      - name: Setup Node
+        uses: actions/setup-node@v4
         with:
-          php-version: ${{ matrix.php }}
-          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo
-          coverage: none
-
-      - name: Setup problem matchers
-        run: |
-          echo "::add-matcher::${{ runner.tool_cache }}/php.json"
-          echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
+          node-version: 22
 
       - name: Install dependencies
-        run: composer install --prefer-dist --no-interaction
+        working-directory: playground
+        run: npm install
 
-      - name: Execute type tests
-        run: composer test:types
+      - name: Build playground
+        working-directory: playground
+        run: npm run build

.gitignore

@@ -32,3 +32,18 @@ testbench.yaml
 /docs
 /coverage
 infection.log
+
+# Playground
+playground/dist
+playground/node_modules
+
+# Legacy archive
+legacy/vendor
+legacy/build
+legacy/.phpunit.cache
+legacy/.phpunit.result.cache
+legacy/composer.lock
+legacy/infection.log
+
+# Claude Code
+.claude/