@a-company/paradigm 1.5.0

package/templates/paradigm/docs/decisions/000-template.md

@@ -0,0 +1,47 @@
+# ADR 000: [Title]
+
+**Status:** Proposed | Accepted | Deprecated | Superseded  
+**Date:** YYYY-MM-DD  
+**Decision Makers:** [Names]
+
+## Context
+
+[What is the issue that we're seeing that motivates this decision?]
+
+## Decision
+
+[What is the change that we're proposing and/or doing?]
+
+## Rationale
+
+[Why did we choose this option? What factors were considered?]
+
+| Factor | Option A | Option B | Winner |
+|--------|----------|----------|--------|
+| [Factor 1] | ... | ... | ... |
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Mitigations
+- [How we'll handle negative consequences]
+
+## Alternatives Considered
+
+[What other options were considered and why were they rejected?]
+
+## References
+
+- [Link to relevant documentation]
+- [Link to related ADRs]
+
+---
+
+*ADR format based on [Michael Nygard's template](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)*

package/templates/paradigm/docs/decisions/README.md

@@ -0,0 +1,26 @@
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records that document significant technical decisions made in this project.
+
+## What is an ADR?
+
+An ADR captures a single decision about the architecture or design of the system. It explains:
+- **Context:** What problem or situation prompted the decision?
+- **Decision:** What was decided?
+- **Consequences:** What are the trade-offs?
+
+## ADR Template
+
+Copy `000-template.md` when creating a new ADR.
+
+## Index
+
+| # | Title | Status | Date |
+|---|-------|--------|------|
+| 000 | Template | Template | - |
+
+*Add new ADRs to this index.*
+
+---
+
+*Part of Paradigm v1.0*

package/templates/paradigm/docs/error-patterns.md

@@ -0,0 +1,215 @@
+# Error Patterns
+
+> Standard error handling across the project (Language-Agnostic)
+
+## Error Response Format
+
+All APIs/services return errors in this format:
+
+```
+// Error response
+{
+  error: string       // Human-readable message
+  code?: string       // Machine-readable code (optional)
+}
+
+// Success response  
+{
+  success?: true      // Optional confirmation
+  data?: any          // Response payload
+}
+```
+
+## Standard Error Codes
+
+| Code | Meaning | When to Use |
+|------|---------|-------------|
+| `INVALID_REQUEST` | Malformed input | Missing fields, wrong types |
+| `INVALID_CREDENTIALS` | Auth validation failed | Wrong password, expired token |
+| `UNAUTHORIZED` | Not authenticated | Missing/expired session |
+| `FORBIDDEN` | Authenticated but denied | Insufficient permissions |
+| `NOT_FOUND` | Resource doesn't exist | Unknown ID, deleted item |
+| `CONFLICT` | State conflict | Duplicate entry, version mismatch |
+| `RATE_LIMITED` | Too many requests | Brute force protection |
+| `SERVER_ERROR` | Internal error | Database down, unexpected crash |
+| `UNAVAILABLE` | Service unavailable | Maintenance, overloaded |
+
+## Patterns (Pseudocode)
+
+### Basic Error Return
+
+```
+// Simple error
+return error_response("Invalid request", status=400)
+
+// With code
+return error_response("Too many attempts", code="RATE_LIMITED", status=429)
+```
+
+### Input Validation
+
+```
+function handle_request(request):
+    data = parse_json(request.body)
+    
+    if data is null:
+        return error_response("Invalid request body", status=400)
+    
+    if not valid_email(data.email):
+        return error_response("Valid email required", status=400)
+    
+    // Continue processing...
+```
+
+### Auth Check
+
+```
+function require_auth(request):
+    user = get_user_from_session(request)
+    
+    if user is null:
+        return error_response("Unauthorized", status=401)
+    
+    return user
+```
+
+### Resource Access
+
+```
+function get_resource(id):
+    resource = database.find(id)
+    
+    if resource is null:
+        return error_response("Not found", status=404)
+    
+    if not user_can_access(resource):
+        return error_response("Forbidden", status=403)
+    
+    return success_response(resource)
+```
+
+### Database Operations
+
+```
+function query_database(query, params):
+    try:
+        result = db.execute(query, params)
+        return result
+    catch DatabaseError as error:
+        log.component('#database').error('Query failed', { error })
+        return error_response("Database error", status=500)
+```
+
+## Error Handling Flow
+
+```
+┌─────────────────┐
+│  Receive Input  │
+└────────┬────────┘
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Validate Input  │────▶│ 400 Bad Request │
+└────────┬────────┘ no  └─────────────────┘
+         │ yes
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│   Check Auth    │────▶│ 401 Unauthorized│
+└────────┬────────┘ no  └─────────────────┘
+         │ yes
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Check Permission│────▶│  403 Forbidden  │
+└────────┬────────┘ no  └─────────────────┘
+         │ yes
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│  Find Resource  │────▶│  404 Not Found  │
+└────────┬────────┘ no  └─────────────────┘
+         │ yes
+         ▼
+┌─────────────────┐     ┌─────────────────┐
+│ Execute Action  │────▶│ 500 Server Error│
+└────────┬────────┘ fail└─────────────────┘
+         │ ok
+         ▼
+┌─────────────────┐
+│  200 Success    │
+└─────────────────┘
+```
+
+## Logging Errors
+
+Always use the Paradigm logger:
+
+```
+// Component context (features)
+log.component('#checkout').error('Payment failed', { reason, order_id })
+
+// Component context (infrastructure)
+log.component('#database').error('Connection lost', { host })
+
+// Gate context
+log.gate('^auth').warn('Access denied', { user_id, resource })
+
+// Component context (integrations)
+log.component('#stripe-client').error('API error', { status, message })
+```
+
+## Graceful Degradation
+
+When non-critical features fail, don't block the user:
+
+```
+// Bad: crashes if optional feature fails
+data = fetch_optional_feature()  // throws on error
+
+// Good: graceful fallback
+data = null
+try:
+    data = fetch_optional_feature()
+catch:
+    log.component('#optional').debug('Feature unavailable, using fallback')
+
+// Continue with or without optional data
+```
+
+## Client-Side Handling
+
+```
+function api_call(endpoint, options):
+    try:
+        response = http.request(endpoint, options)
+        
+        if not response.ok:
+            return { error: response.data.error or "Request failed" }
+        
+        return { data: response.data }
+    catch NetworkError:
+        return { error: "Connection error" }
+```
+
+## Error State in UI
+
+```
+// State
+error = null
+
+function submit():
+    error = null  // Clear previous error
+    
+    result = api_call('/endpoint', data)
+    
+    if result.error:
+        error = result.error
+        return
+    
+    // Success handling...
+
+// Display
+if error:
+    show_error_message(error)
+```
+
+---
+
+*Part of Paradigm v2.0 - Language Agnostic*

package/templates/paradigm/docs/patterns.md

@@ -0,0 +1,358 @@
+# Paradigm Coding Patterns
+
+Common patterns for working with Paradigm symbols and the logger.
+
+---
+
+## Component Pattern (Features)
+
+Components with `[feature]` tag are user-facing operations. They should be logged at entry and exit.
+
+```
+// Component: #login-handler [feature]
+
+function login(email, password):
+    // 1. Log entry with start() for duration tracking
+    tracker = log.component('#login-handler').start('Starting login', { email })
+
+    try:
+        // 2. Perform the operation
+        user = authenticate(email, password)
+
+        // 3. Emit success signal
+        log.signal('!login-success').info('User authenticated', {
+            userId: user.id
+        })
+
+        // 4. Log successful completion with duration
+        tracker.success('Login completed', { userId: user.id })
+
+        return user
+
+    catch error:
+        // 5. Emit failure signal
+        log.signal('!login-failed').warn('Login failed', {
+            email,
+            error: error.message
+        })
+
+        // 6. Log failure with duration
+        tracker.error('Login failed', { error: error.message })
+
+        throw error
+```
+
+**Key points:**
+- Use `log.component('#name').start()` at entry
+- Emit `!success` and `!failed` signals
+- Always call `tracker.success()` or `tracker.error()`
+
+---
+
+## Gate Pattern
+
+Gates (`^`) are authorization checkpoints. Log before and after the check.
+
+```
+// Gate: ^authenticated
+
+function requireAuth(request, next):
+    // 1. Log gate check start
+    log.gate('^authenticated').debug('Checking ^authenticated', {
+        path: request.path,
+        method: request.method
+    })
+
+    // 2. Perform authorization check
+    user = getSessionUser(request)
+
+    if not user:
+        // 3. Log denial
+        log.gate('^authenticated').warn('Access denied - no session', {
+            path: request.path,
+            ip: request.ip
+        })
+        return unauthorized("Authentication required")
+
+    // 4. Log success
+    log.gate('^authenticated').debug('Gate passed', {
+        userId: user.id,
+        path: request.path
+    })
+
+    // 5. Continue to next handler
+    return next()
+```
+
+**Key points:**
+- Log at `debug` level for routine checks
+- Log at `warn` level for denials
+- Include context (path, userId) for debugging
+
+---
+
+## Component Pattern
+
+Components (`#`) are reusable infrastructure. Log operations and errors.
+
+```
+// Component: #database
+
+class Database:
+    function query(sql, params):
+        // 1. Start duration tracking
+        tracker = log.component('#database').start('Executing query')
+        
+        try:
+            // 2. Perform operation
+            result = this.connection.execute(sql, params)
+            
+            // 3. Log success with metrics
+            tracker.success('Query completed', {
+                rows: result.length,
+                table: extractTable(sql)
+            })
+            
+            return result
+            
+        catch error:
+            // 4. Log failure
+            tracker.error('Query failed', {
+                error: error.message,
+                sql: sql.substring(0, 100)  // Truncate for safety
+            })
+            throw error
+    
+    function connect():
+        log.component('#database').info('Connecting to database', {
+            host: this.config.host,
+            database: this.config.database
+        })
+        
+        // ... connection logic
+        
+        log.component('#database').info('Database connected')
+```
+
+**Key points:**
+- Use duration tracking for async operations
+- Log connection lifecycle events
+- Include relevant metrics (rows, duration)
+
+---
+
+## State Component Pattern
+
+State components (`#` with `[state]` tag) manage application state. Log changes with before/after values.
+
+```
+// Component: #user-store [state]
+
+class AuthStore:
+    authenticated = false
+    user = null
+
+    function login(token, userData):
+        // 1. Log state change with context
+        log.component('#user-store').info('Authenticating user', {
+            from: this.authenticated,
+            to: true,
+            userId: userData.id
+        })
+
+        // 2. Update state
+        this.authenticated = true
+        this.user = userData
+        this.token = token
+
+        // 3. Emit signal
+        log.signal('!login-success').info('User session established', {
+            userId: userData.id
+        })
+
+    function logout():
+        previousUser = this.user?.id
+
+        log.component('#user-store').info('Logging out user', {
+            from: this.authenticated,
+            to: false,
+            userId: previousUser
+        })
+
+        this.authenticated = false
+        this.user = null
+        this.token = null
+
+        log.signal('!logout').info('User session ended', {
+            userId: previousUser
+        })
+```
+
+**Key points:**
+- Include `from` and `to` values
+- Pair state changes with signals
+- Log at `info` level for visibility
+
+---
+
+## Flow Pattern
+
+Flows (`$`) are multi-step processes. Log step transitions.
+
+```
+// Flow: $checkout-flow
+// Steps: cart → shipping → payment → confirmation
+
+class CheckoutFlow:
+    currentStep = 'cart'
+    
+    function startFlow(cartId):
+        log.flow('$checkout-flow').info('Flow started', {
+            cartId,
+            step: 'cart'
+        })
+        this.currentStep = 'cart'
+    
+    function nextStep():
+        steps = ['cart', 'shipping', 'payment', 'confirmation']
+        currentIndex = steps.indexOf(this.currentStep)
+        
+        if currentIndex < steps.length - 1:
+            previousStep = this.currentStep
+            this.currentStep = steps[currentIndex + 1]
+            
+            log.flow('$checkout-flow').info('Step completed', {
+                from: previousStep,
+                to: this.currentStep,
+                progress: `${currentIndex + 1}/${steps.length}`
+            })
+    
+    function completeFlow(orderId):
+        log.flow('$checkout-flow').info('Flow completed', {
+            orderId,
+            totalSteps: 4
+        })
+        log.signal('!checkout-complete').info('Order placed', { orderId })
+```
+
+**Key points:**
+- Log flow start and completion
+- Log step transitions with from/to
+- Include progress indicators
+
+---
+
+## Signal Pattern
+
+Signals (`!`) are events. Use them consistently for important occurrences.
+
+```
+// Signals for authentication
+log.signal('!login-success').info('User logged in', { userId })
+log.signal('!login-failed').warn('Login attempt failed', { email, reason })
+log.signal('!logout').info('User logged out', { userId })
+log.signal('!session-expired').warn('Session expired', { userId })
+
+// Signals for payments
+log.signal('!payment-success').info('Payment processed', { orderId, amount })
+log.signal('!payment-failed').error('Payment declined', { orderId, reason })
+log.signal('!refund-issued').info('Refund processed', { orderId, amount })
+
+// Signals for system events
+log.signal('!rate-limit-exceeded').warn('Rate limit hit', { ip, endpoint })
+log.signal('!cache-miss').debug('Cache miss', { key })
+log.signal('!email-sent').info('Email dispatched', { to, template })
+```
+
+**Key points:**
+- Use consistent naming: `!noun-verb` or `!noun-state`
+- Choose appropriate level (info/warn/error)
+- Include relevant context
+
+---
+
+## Error Handling Pattern
+
+Consistent error handling with Paradigm logging:
+
+```
+function riskyOperation():
+    tracker = log.component('#risky-op').start('Starting operation')
+    
+    try:
+        // Happy path
+        result = doSomethingRisky()
+        tracker.success('Operation completed', { result })
+        return result
+        
+    catch KnownError as error:
+        // Expected error - warn level
+        log.signal('!known-error').warn('Expected error occurred', {
+            type: error.type,
+            message: error.message
+        })
+        tracker.error('Operation failed (known)', { error: error.type })
+        return fallbackValue
+        
+    catch error:
+        // Unexpected error - error level
+        log.signal('!unexpected-error').error('Unexpected error', {
+            message: error.message,
+            stack: error.stack
+        })
+        tracker.error('Operation failed (unexpected)', { 
+            error: error.message 
+        })
+        throw error
+```
+
+---
+
+## Middleware Pattern
+
+Logging in request middleware:
+
+```
+function loggingMiddleware(request, next):
+    correlationId = request.headers['x-correlation-id'] or generateId()
+    
+    return withCorrelation(correlationId, async () => {
+        tracker = log.component('#' + request.path).start('Request started', {
+            method: request.method,
+            path: request.path
+        })
+        
+        try:
+            response = await next()
+            
+            tracker.success('Request completed', {
+                status: response.status
+            })
+            
+            return response
+            
+        catch error:
+            tracker.error('Request failed', {
+                error: error.message
+            })
+            throw error
+    })
+```
+
+---
+
+## Testing Pattern
+
+When testing, you may want to suppress or capture logs:
+
+```
+// In tests, set LOG_LEVEL=error to reduce noise
+// Or mock the logger to capture calls
+
+beforeEach:
+    originalLogLevel = process.env.LOG_LEVEL
+    process.env.LOG_LEVEL = 'error'
+
+afterEach:
+    process.env.LOG_LEVEL = originalLogLevel
+```