openapi.yaml

openapi: 3.0.3
info:
  title: TML Always Memory API
  description: |
    Universal accountability framework for AI systems
    **Architecture**: Always Memory with immutable logging and Sacred Zero enforcement
    **Principle**: No memory = No action
    **Creator**: Lev Goukassian (ORCID: 0009-0006-5966-1243)
  version: 5.0.0
  contact:
    name: Lev Goukassian
    email: leogouk@gmail.com
    url: https://orcid.org/0009-0006-5966-1243
  license:
    name: MIT-Attribution-Required
    url: https://github.com/FractonicMind/TernaryMoralLogic/blob/main/LICENSE

servers:
  - url: https://api.tml-framework.org/v5
    description: Production Always Memory API
  - url: http://localhost:8000
    description: Local development

paths:
  /memory/create:
    post:
      summary: Create Always Memory log
      description: Creates an immutable memory log before AI action execution
      operationId: createMemory
      tags:
        - Memory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemoryRequest'
      responses:
        '200':
          description: Memory successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemoryResponse'
        '403':
          description: Action refused (classification = -1)
        '429':
          description: Backpressure - retry after delay
          headers:
            Retry-After:
              schema:
                type: integer

  /memory/{memory_id}:
    get:
      summary: Retrieve memory log
      operationId: getMemory
      tags:
        - Memory
      parameters:
        - name: memory_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Memory log retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MoralTraceLog'

  /sacred-zero/trigger:
    post:
      summary: Trigger Sacred Zero
      description: Manually trigger Sacred Zero for moral complexity
      operationId: triggerSacredZero
      tags:
        - Sacred Zero
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SacredZeroEvent'
      responses:
        '200':
          description: Sacred Zero triggered

  /earth/check:
    post:
      summary: Check environmental impact
      description: Assess planetary harm and trigger Sacred Zero if needed
      operationId: checkEarthImpact
      tags:
        - Earth Protection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EarthImpactRequest'
      responses:
        '200':
          description: Environmental assessment complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarthImpactResponse'

  /stewardship_council/submit:
    post:
      summary: Submit to Stewardship Council
      description: Submit memory batch to Stewardship Council for attestation
      operationId: submitToStewardshipCouncil
      tags:
        - Stewardship Council
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StewardshipCouncilSubmission'
      responses:
        '200':
          description: Submission accepted by Stewardship Council

components:
  schemas:
    MemoryRequest:
      type: object
      required:
        - action
        - input_data
      properties:
        action:
          type: string
          description: Action being performed
        input_data:
          type: object
          description: Input data for the action
        context:
          $ref: '#/components/schemas/DecisionContext'
        environmental_check:
          type: boolean
          default: false
          description: Check for environmental impact

    MemoryResponse:
      type: object
      properties:
        memory_id:
          type: string
        classification:
          type: integer
          enum: [-1, 0, 1]
          description: |
            TML classification:
            -1: Refuse
             0: Sacred Zero
            +1: Proceed
        sacred_zero_trigger:
          type: string
        timestamp:
          type: string
          format: date-time
        stewardship_council_confirmations:
          type: array
          items:
            type: string

    MoralTraceLog:
      type: object
      required:
        - framework
        - creator_orcid
        - timestamp
        - classification
      properties:
        framework:
          type: string
          const: TML-AlwaysMemory-v5.0
        creator_orcid:
          type: string
          const: "0009-0006-5966-1243"
        timestamp:
          type: string
          format: date-time
        classification:
          type: integer
          enum: [-1, 0, 1]
        sacred_zero_trigger:
          type: string
        input_hash:
          type: string
          pattern: "^0x[a-f0-9]{64}$"
        output_hash:
          type: string
          pattern: "^0x[a-f0-9]{64}$"
        environmental_impact:
          $ref: '#/components/schemas/EnvironmentalImpact'
        goukassian_promise:
          $ref: '#/components/schemas/GoukassianPromise'

    DecisionContext:
      type: object
      properties:
        user_id:
          type: string
        session_id:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        metadata:
          type: object

    Location:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number

    SacredZeroEvent:
      type: object
      required:
        - trigger
        - context_hash
      properties:
        trigger:
          type: string
          examples:
            - protected_class_impact
            - medical_critical
            - environmental_harm
            - community_sovereignty
        context_hash:
          type: string
        human_review_required:
          type: boolean
          default: true

    EnvironmentalImpact:
      type: object
      properties:
        carbon_equiv:
          type: string
        water_consumed:
          type: string
        habitat_affected:
          type: string
        irreversibility_score:
          type: number
          minimum: 0.0
          maximum: 1.0
        alternative_rejected:
          type: string

    EarthImpactRequest:
      type: object
      required:
        - action
      properties:
        action:
          type: string
        location:
          $ref: '#/components/schemas/Location'
        resource_impact:
          type: object

    EarthImpactResponse:
      type: object
      properties:
        triggered:
          type: boolean
        harm_types:
          type: array
          items:
            type: string
        irreversibility_score:
          type: number
        sacred_zero_trigger:
          type: string
        community_affected:
          type: string

    StewardshipCouncilSubmission:
      type: object
      required:
        - batch_id
        - memories
      properties:
        batch_id:
          type: string
        memories:
          type: array
          items:
            $ref: '#/components/schemas/MoralTraceLog'
        tee_attestation:
          type: object

    GoukassianPromise:
      type: object
      required:
        - lantern
        - signature
        - license
      properties:
        lantern:
          type: boolean
          const: true
        signature:
          type: string
          const: "0009-0006-5966-1243"
        license:
          type: string
          const: MIT-Attribution-Required

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - ApiKeyAuth: []
```