@ebowwa/logic-spec 1.0.0

package/SPEC.md

@@ -0,0 +1,783 @@
+# Logic Specification (logic.yaml) v1.0
+
+A language-agnostic standard for extracting pure logic from implementations.
+
+## Overview
+
+`logic.yaml` captures the **what** and **how** of a system's behavior without the **syntax** of any particular language. This enables:
+
+- AI agents to understand logic without reading implementation code
+- Portability across languages and runtimes
+- Automated validation, testing, and documentation generation
+- Clear contracts between system components
+
+## Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **I/O at edges** | Logic blocks are pure functions - no side effects, no hidden state |
+| **Algorithm as text** | Steps described in human-readable prose, not code syntax |
+| **Types explicit** | All data shapes defined with schemas for validation |
+| **State first-class** | State machines declared explicitly, not inferred |
+| **Constraints separate** | Performance/reliability requirements not buried in code |
+| **Failures declared** | Error conditions and recovery strategies part of contract |
+| **Composable blocks** | Logic chains into flows, not monolithic procedures |
+| **Versioned spec** | Schema can evolve without breaking consumers |
+| **Observable** | Hooks for metrics, logging, tracing built-in |
+| **Testable** | Assertions defined alongside logic |
+
+## Specification
+
+### Document Structure
+
+```yaml
+# logic.yaml v1.0
+
+meta:          # Required - Document metadata
+inputs:        # Required - System inputs
+outputs:       # Required - System outputs
+types:         # Optional - Type definitions
+logic:         # Required - Pure logic blocks
+state:         # Optional - State machine definition
+flows:         # Optional - Logic composition
+failures:      # Optional - Error handling
+constraints:   # Optional - Performance/reliability bounds
+dependencies:  # Optional - External service contracts
+observability: # Optional - Metrics/logging hooks
+tests:         # Optional - Built-in assertions
+```
+
+---
+
+### `meta`
+
+Required. Identifies and versions the specification.
+
+```yaml
+meta:
+  spec_version: "1.0"           # Required - Logic spec version
+  name: string                   # Required - System/module name
+  version: string                # Required - Semantic version of this logic
+  description: string            # Optional - Human description
+  language_target: string | any  # Optional - Target language(s)
+  author: string                 # Optional - Creator
+  license: string                # Optional - License identifier
+```
+
+**Example:**
+```yaml
+meta:
+  spec_version: "1.0"
+  name: user-authenticator
+  version: "2.1.0"
+  description: Handles user authentication flows
+  language_target: any
+```
+
+---
+
+### `inputs`
+
+Required. Defines what enters the system.
+
+```yaml
+inputs:
+  - name: string           # Required - Input identifier
+    type: string           # Required - Type name or primitive
+    required: boolean      # Optional - Default: true
+    default: any           # Optional - Default value if not required
+    description: string    # Optional - Purpose of this input
+    schema:                # Optional - Detailed structure
+      field: type
+    validation:            # Optional - Validation rules
+      min: number
+      max: number
+      pattern: regex
+```
+
+**Primitive types:** `string`, `number`, `boolean`, `array`, `object`, `null`, `any`
+
+**Example:**
+```yaml
+inputs:
+  - name: credentials
+    type: Credentials
+    required: true
+    schema:
+      username: string
+      password: string
+      totp_code: string
+
+  - name: session_duration
+    type: number
+    required: false
+    default: 3600
+    validation:
+      min: 300
+      max: 86400
+```
+
+---
+
+### `outputs`
+
+Required. Defines what leaves the system.
+
+```yaml
+outputs:
+  - name: string           # Required - Output identifier
+    type: string           # Required - Type name or primitive
+    description: string    # Optional - Purpose
+    schema: object         # Optional - Detailed structure
+```
+
+**Example:**
+```yaml
+outputs:
+  - name: auth_result
+    type: AuthResult
+    schema:
+      success: boolean
+      token: string
+      expires_at: number
+      user_id: string
+```
+
+---
+
+### `types`
+
+Optional. Defines custom types referenced elsewhere.
+
+```yaml
+types:
+  TypeName:
+    description: string    # Optional
+    fields:                # Required for object types
+      field_name: type
+    enum:                  # Required for enum types
+      - value1
+      - value2
+    generic:               # Optional - Generic type params
+      - T
+```
+
+**Example:**
+```yaml
+types:
+  Credentials:
+    fields:
+      username: string
+      password: string
+      totp_code: string | null
+
+  AuthResult:
+    fields:
+      success: boolean
+      token: string | null
+      expires_at: number
+      user_id: string | null
+      error: AuthError | null
+
+  AuthError:
+    enum:
+      - INVALID_CREDENTIALS
+      - ACCOUNT_LOCKED
+      - TOTP_REQUIRED
+      - TOTP_INVALID
+```
+
+---
+
+### `logic`
+
+Required. Pure logic blocks - no I/O, no side effects.
+
+```yaml
+logic:
+  - id: string             # Required - Unique identifier
+    type: string           # Required - Block type
+    description: string    # Optional - What this does
+    input: string | array  # Required - Input name(s)
+    output: string         # Required - Output name
+    algorithm: string      # Required - Steps in prose
+    complexity: string     # Optional - Big-O notation
+```
+
+**Block types:**
+| Type | Purpose |
+|------|---------|
+| `transform` | Pure data transformation |
+| `validate` | Input validation |
+| `compute` | Calculation/derivation |
+| `decision` | Conditional logic, branching |
+| `aggregate` | Combining multiple inputs |
+| `inference` | AI/ML model invocation |
+| `query` | External data fetch (marked, not pure) |
+
+**Example:**
+```yaml
+logic:
+  - id: validate_credentials
+    type: validate
+    input: credentials
+    output: validation_result
+    algorithm: |
+      1. Check username format: 3-64 chars, alphanumeric + underscore
+      2. Check password length: >= 12 chars
+      3. If totp_code present, validate 6-digit format
+      4. Return {valid: boolean, errors: string[]}
+
+  - id: hash_password
+    type: transform
+    input: credentials.password
+    output: hashed_password
+    algorithm: |
+      1. Generate salt: 16 random bytes
+      2. Apply Argon2id with salt
+      3. Return base64-encoded hash
+    complexity: O(1)
+
+  - id: verify_password
+    type: decision
+    input: [credentials, stored_hash]
+    output: password_valid
+    algorithm: |
+      1. Extract salt from stored_hash
+      2. Hash input password with same salt
+      3. Compare with constant-time comparison
+      4. Return boolean
+```
+
+---
+
+### `state`
+
+Optional. State machine definition.
+
+```yaml
+state:
+  initial: string          # Required - Starting state
+  persist: boolean         # Optional - Persist across runs
+  states:                  # Optional - State definitions
+    state_name:
+      description: string
+  transitions:             # Required - State transitions
+    - from: string | array
+      to: string
+      trigger: string      # Event or condition
+      action: string       # Optional - Logic block to execute
+      guard: string        # Optional - Condition that must be true
+```
+
+**Example:**
+```yaml
+state:
+  initial: unauthenticated
+  persist: true
+  states:
+    unauthenticated:
+      description: No active session
+    authenticating:
+      description: Login in progress
+    authenticated:
+      description: Valid session active
+    locked:
+      description: Account locked due to failures
+
+  transitions:
+    - from: unauthenticated
+      to: authenticating
+      trigger: login_attempt
+      action: validate_credentials
+
+    - from: authenticating
+      to: authenticated
+      trigger: credentials_valid
+      action: create_session
+      guard: attempts < 5
+
+    - from: authenticating
+      to: locked
+      trigger: too_many_failures
+      guard: attempts >= 5
+
+    - from: authenticated
+      to: unauthenticated
+      trigger: logout | session_expired
+      action: destroy_session
+```
+
+---
+
+### `flows`
+
+Optional. Composition of logic blocks into sequences.
+
+```yaml
+flows:
+  - name: string           # Required - Flow identifier
+    description: string    # Optional
+    steps: array           # Required - Logic block IDs in order
+    parallel: boolean      # Optional - Run steps in parallel
+    timeout_ms: number     # Optional - Max execution time
+    retry:                 # Optional - Retry configuration
+      count: number
+      backoff: linear | exponential
+      delay_ms: number
+```
+
+**Example:**
+```yaml
+flows:
+  - name: authenticate_user
+    description: Full authentication flow
+    steps:
+      - validate_credentials
+      - verify_password
+      - check_account_status
+      - create_session
+    parallel: false
+    timeout_ms: 5000
+
+  - name: parallel_validation
+    steps:
+      - validate_credentials
+      - check_rate_limit
+      - check_ip_reputation
+    parallel: true
+    timeout_ms: 1000
+```
+
+---
+
+### `failures`
+
+Optional. Error conditions and recovery strategies.
+
+```yaml
+failures:
+  - code: string           # Required - Error code
+    condition: string      # Required - When this occurs
+    severity: critical | error | warning | info
+    recovery:              # Optional - Recovery strategy
+      strategy: retry | fallback | escalate | ignore
+      retry_count: number  # For retry strategy
+      fallback_to: string  # For fallback strategy
+    message: string        # Optional - Human-readable message
+```
+
+**Example:**
+```yaml
+failures:
+  - code: E001
+    condition: "database.connection_timeout > 5000ms"
+    severity: error
+    recovery:
+      strategy: retry
+      retry_count: 3
+    message: Database connection timed out
+
+  - code: E002
+    condition: "password_hash.failure"
+    severity: critical
+    recovery:
+      strategy: escalate
+    message: Password hashing failed - possible security issue
+
+  - code: E003
+    condition: "rate_limit.exceeded"
+    severity: warning
+    recovery:
+      strategy: fallback
+      fallback_to: cached_response
+    message: Rate limit exceeded
+```
+
+---
+
+### `constraints`
+
+Optional. Performance and reliability bounds.
+
+```yaml
+constraints:
+  latency_max_ms: number        # Max response time
+  throughput_min_rps: number    # Min requests per second
+  memory_limit_mb: number       # Max memory usage
+  cpu_limit_percent: number     # Max CPU usage
+  availability_percent: number  # Uptime requirement
+  data_retention_days: number   # Data storage duration
+```
+
+**Example:**
+```yaml
+constraints:
+  latency_max_ms: 500
+  throughput_min_rps: 1000
+  memory_limit_mb: 512
+  availability_percent: 99.9
+```
+
+---
+
+### `dependencies`
+
+Optional. External service contracts.
+
+```yaml
+dependencies:
+  - name: string           # Required - Service name
+    type: string           # Required - Service type
+    contract: string       # Optional - Interface name
+    required: boolean      # Optional - Default: true
+    endpoint: string       # Optional - Service URL
+    timeout_ms: number     # Optional - Request timeout
+    auth: string           # Optional - Auth method
+```
+
+**Example:**
+```yaml
+dependencies:
+  - name: user_database
+    type: database
+    contract: UserStore
+    required: true
+    timeout_ms: 1000
+
+  - name: cache
+    type: cache
+    contract: KeyValueStore
+    required: false
+
+  - name: gemini_api
+    type: external_service
+    contract: VisionAPI
+    required: true
+    timeout_ms: 30000
+    auth: api_key
+```
+
+---
+
+### `observability`
+
+Optional. Metrics, logging, and tracing hooks.
+
+```yaml
+observability:
+  metrics:
+    - name: string         # Required - Metric name
+      type: counter | gauge | histogram
+      unit: string         # Optional - Unit of measurement
+      labels: array        # Optional - Dimension labels
+
+  logs:
+    level: debug | info | warn | error
+    include: array         # Fields to include in logs
+    exclude: array         # Fields to redact
+
+  traces:
+    enabled: boolean
+    sample_rate: number    # 0.0 to 1.0
+```
+
+**Example:**
+```yaml
+observability:
+  metrics:
+    - name: auth_attempts_total
+      type: counter
+      labels: [status, method]
+    - name: auth_duration_ms
+      type: histogram
+      unit: ms
+
+  logs:
+    level: info
+    include: [user_id, method, duration_ms]
+    exclude: [password, token]
+
+  traces:
+    enabled: true
+    sample_rate: 0.1
+```
+
+---
+
+### `tests`
+
+Optional. Built-in assertions and test cases.
+
+```yaml
+tests:
+  - name: string           # Required - Test name
+    description: string    # Optional
+    given: object          # Required - Input values
+    when: string           # Optional - Action/flow to execute
+    expect: object         # Required - Expected outputs
+    timeout_ms: number     # Optional
+```
+
+**Matchers in `expect`:**
+| Syntax | Meaning |
+|--------|---------|
+| `value` | Exact match |
+| `">= n"` | Greater than or equal |
+| `"<= n"` | Less than or equal |
+| `"type:typename"` | Type check |
+| `"/regex/"` | Regex match |
+| `"!null"` | Not null |
+| `"any"` | Any value (just check presence) |
+
+**Example:**
+```yaml
+tests:
+  - name: valid_login
+    description: Successful authentication with valid credentials
+    given:
+      credentials:
+        username: testuser
+        password: correct_password_123
+    when: authenticate_user
+    expect:
+      auth_result.success: true
+      auth_result.token: "!null"
+      auth_result.expires_at: ">= 0"
+
+  - name: invalid_password
+    given:
+      credentials:
+        username: testuser
+        password: wrong_password
+    when: authenticate_user
+    expect:
+      auth_result.success: false
+      auth_result.error: INVALID_CREDENTIALS
+
+  - name: rate_limited
+    given:
+      credentials:
+        username: testuser
+        password: any_password
+      rate_limit_exceeded: true
+    expect:
+      auth_result.success: false
+      auth_result.error: RATE_LIMITED
+```
+
+---
+
+## Complete Example
+
+```yaml
+# logic.yaml - User Authentication Module
+
+meta:
+  spec_version: "1.0"
+  name: user-auth
+  version: "1.0.0"
+  description: User authentication with password and TOTP
+  language_target: any
+
+inputs:
+  - name: credentials
+    type: Credentials
+    required: true
+  - name: client_ip
+    type: string
+    required: true
+  - name: session_duration
+    type: number
+    default: 3600
+
+outputs:
+  - name: auth_result
+    type: AuthResult
+
+types:
+  Credentials:
+    fields:
+      username: string
+      password: string
+      totp_code: string | null
+
+  AuthResult:
+    fields:
+      success: boolean
+      token: string | null
+      expires_at: number
+      user_id: string | null
+      error: AuthError | null
+
+  AuthError:
+    enum: [INVALID_CREDENTIALS, ACCOUNT_LOCKED, TOTP_REQUIRED, TOTP_INVALID, RATE_LIMITED]
+
+logic:
+  - id: validate_input
+    type: validate
+    input: credentials
+    output: validation
+    algorithm: |
+      1. Validate username format
+      2. Validate password length >= 12
+      3. Return {valid: boolean, errors: string[]}
+
+  - id: check_rate_limit
+    type: decision
+    input: client_ip
+    output: rate_ok
+    algorithm: |
+      1. Count recent attempts from IP
+      2. Return true if under limit, false otherwise
+
+  - id: verify_credentials
+    type: decision
+    input: [credentials, stored_user]
+    output: credentials_valid
+    algorithm: |
+      1. Fetch stored hash for username
+      2. Compare passwords with constant-time comparison
+      3. If TOTP enabled, verify code
+      4. Return boolean
+
+  - id: create_session
+    type: transform
+    input: [user_id, session_duration]
+    output: auth_result
+    algorithm: |
+      1. Generate secure random token
+      2. Set expiration = now + session_duration
+      3. Store session in cache
+      4. Return AuthResult with success=true
+
+state:
+  initial: idle
+  transitions:
+    - from: idle
+      to: validating
+      trigger: login_attempt
+    - from: validating
+      to: authenticating
+      trigger: input_valid
+    - from: validating
+      to: idle
+      trigger: input_invalid
+    - from: authenticating
+      to: success
+      trigger: credentials_valid
+    - from: authenticating
+      to: failed
+      trigger: credentials_invalid
+    - from: success
+      to: idle
+      trigger: logout
+
+flows:
+  - name: authenticate
+    steps: [validate_input, check_rate_limit, verify_credentials, create_session]
+    timeout_ms: 5000
+
+failures:
+  - code: E001
+    condition: "rate_limit.exceeded"
+    recovery:
+      strategy: fallback
+      fallback_to: rate_limit_response
+  - code: E002
+    condition: "database.unavailable"
+    recovery:
+      strategy: retry
+      retry_count: 3
+
+constraints:
+  latency_max_ms: 500
+  throughput_min_rps: 1000
+  availability_percent: 99.9
+
+dependencies:
+  - name: user_db
+    type: database
+    contract: UserStore
+  - name: session_cache
+    type: cache
+    contract: KeyValueStore
+  - name: rate_limiter
+    type: service
+    contract: RateLimiter
+
+observability:
+  metrics:
+    - name: auth_attempts
+      type: counter
+      labels: [status, method]
+    - name: auth_latency
+      type: histogram
+      unit: ms
+  logs:
+    level: info
+    include: [user_id, client_ip, duration_ms]
+    exclude: [password, token]
+
+tests:
+  - name: happy_path
+    given:
+      credentials: {username: alice, password: secure_password_123}
+      client_ip: 192.168.1.1
+    expect:
+      auth_result.success: true
+      auth_result.token: "!null"
+
+  - name: wrong_password
+    given:
+      credentials: {username: alice, password: wrong_password}
+      client_ip: 192.168.1.1
+    expect:
+      auth_result.success: false
+      auth_result.error: INVALID_CREDENTIALS
+```
+
+---
+
+## Validation Rules
+
+A valid `logic.yaml` must pass these checks:
+
+1. **Required fields present**: `meta`, `inputs`, `outputs`, `logic`
+2. **Unique identifiers**: All `logic[].id`, `types` keys, `inputs[].name`, `outputs[].name` must be unique
+3. **Type references**: All referenced types must be defined in `types` or be primitives
+4. **Input/output connectivity**: Each `logic[].input` must reference a defined input or another logic block's output
+5. **State transitions**: All states in `transitions` must be defined
+6. **Test coverage**: Each `flow` should have at least one test case
+
+---
+
+## Versioning
+
+The spec uses semantic versioning:
+
+- **Major**: Breaking changes to required structure
+- **Minor**: New optional fields added
+- **Patch**: Clarifications, no structural changes
+
+Current version: **1.0.0**
+
+---
+
+## Tooling
+
+Recommended tooling for `logic.yaml`:
+
+| Tool | Purpose |
+|------|---------|
+| `logic-validate` | Validate spec against schema |
+| `logic-generate` | Generate code from spec |
+| `logic-docs` | Generate documentation |
+| `logic-test` | Run built-in test cases |
+| `logic-visualize` | Generate state/flow diagrams |
+
+---
+
+## License
+
+This specification is released under the MIT License.