apilabs.ai Super Contracts API Spec

# =============================================================================
# SUPERCONTRACTS™ MVP — DRAFT SPECIFICATION
# Copyright © API Labs. All rights reserved.
#
# STATUS: Draft / evolving specification. Not a finalized 1.0 standard.
# PURPOSE: Use this minimal spec for prototypes, developer onboarding, local
#          execution, basic API workflows, tests, policies, approvals, agents,
#          MCP exposure, and runtime evidence.
# SOURCE OF TRUTH: This file defines the supported minimal structure. Examples
#                  in documentation are illustrative and may omit required fields.
# GUIDANCE: Start here unless enterprise-grade controls, deep observability,
#           reusable policy domains, or advanced identity controls are required.
# =============================================================================

# -----------------------------------------------------------------------------
# CONTRACT METADATA
# WHEN TO USE: Always. Identifies the contract, version, owner, and purpose.
# Keep IDs stable; increment version when behavior, policy, or schema changes.
# -----------------------------------------------------------------------------
contract:
  spec: supercontracts
  spec_version: "1.0"
  id: order-processing
  version: "2.1.0"
  description: Create, retrieve, test, and govern customer orders.
  owner: fulfillment-platform
  tags: [orders, fulfillment]

# -----------------------------------------------------------------------------
# SERVICE DEFAULTS
# WHEN TO USE: Define shared protocol defaults such as timeout, content type,
# authentication, and the default execution environment.
# -----------------------------------------------------------------------------
service:
  name: Order Processing Service
  default_environment: development
  defaults:
    timeout: 30s
    content_type: application/json
    auth: order_bearer

# -----------------------------------------------------------------------------
# ENVIRONMENTS
# WHEN TO USE: Use whenever the same contract runs against development, staging,
# or production. Mark production explicitly and use secure tunnels for private APIs.
# -----------------------------------------------------------------------------
environments:
  production:
    base_url: https://api.fulfillment.io/v2
    production: true
  staging:
    base_url: https://staging-api.fulfillment.io/v2
  development:
    base_url: http://localhost:8080/v2
    secure_tunnel: true

# -----------------------------------------------------------------------------
# AUTHENTICATION AND SECRETS
# WHEN TO USE: Use for APIs requiring credentials. Reference external secret stores;
# never place raw tokens, passwords, or production keys directly in this file.
# -----------------------------------------------------------------------------
auth:
  order_bearer:
    type: bearer
    in: header
    header: Authorization
    secret:
      production: aws-sm://orders/prod/access-token
      staging: aws-sm://orders/staging/access-token
      development: env://ORDER_TOKEN
    redact: true

# -----------------------------------------------------------------------------
# SCHEMAS
# WHEN TO USE: Define reusable input, output, identifier, and error structures.
# Use schemas to validate requests and responses before and after execution.
# -----------------------------------------------------------------------------
schemas:
  OrderId:
    type: string
    pattern: '^ord_[A-Za-z0-9]{12}
#x27;

  Sku:
    type: string
    pattern: '^[A-Z]{3}-[A-Z]{3}-[0-9]{3}
#x27;
    minLength: 11
    maxLength: 11

  Quantity:
    type: integer
    minimum: 1
    maximum: 10

  Order:
    type: object
    additionalProperties: false
    required: [order_id, sku, quantity, status]
    properties:
      order_id: { $ref: '#/schemas/OrderId' }
      sku: { $ref: '#/schemas/Sku' }
      quantity: { $ref: '#/schemas/Quantity' }
      status:
        type: string
        enum: [pending, processing, shipped, cancelled]

  OrderCreate:
    type: object
    additionalProperties: false
    required: [sku, quantity]
    properties:
      sku: { $ref: '#/schemas/Sku' }
      quantity: { $ref: '#/schemas/Quantity' }

  Error:
    type: object
    additionalProperties: false
    required: [code, message, correlation_id]
    properties:
      code: { type: string }
      message: { type: string }
      correlation_id: { type: string }

# -----------------------------------------------------------------------------
# API OPERATIONS
# WHEN TO USE: Define each callable API action, including method, path, risk,
# authentication, inputs, responses, policies, and emitted events.
# -----------------------------------------------------------------------------
operations:
  place_order:
    method: POST
    path: /orders
    effect: write
    risk: medium
    auth: order_bearer
    request:
      body:
        required: true
        schema: { $ref: '#/schemas/OrderCreate' }
      headers:
        Idempotency-Key:
          required: true
          type: string
    responses:
      '201': { schema: { $ref: '#/schemas/Order' } }
      '400': { schema: { $ref: '#/schemas/Error' } }
      '401': { schema: { $ref: '#/schemas/Error' } }
      '409': { schema: { $ref: '#/schemas/Error' } }
    policies:
      - production_write_approval
      - place_order_rate_limit
      - redact_sensitive_data
      - capture_evidence
    emits: [order_created]

  get_order:
    method: GET
    path: /orders/{order_id}
    effect: read
    risk: low
    auth: order_bearer
    parameters:
      path:
        order_id:
          required: true
          schema: { $ref: '#/schemas/OrderId' }
    responses:
      '200': { schema: { $ref: '#/schemas/Order' } }
      '401': { schema: { $ref: '#/schemas/Error' } }
      '404': { schema: { $ref: '#/schemas/Error' } }
    policies:
      - order_lookup_retry
      - redact_sensitive_data
      - capture_evidence

# -----------------------------------------------------------------------------
# WORKFLOWS
# WHEN TO USE: Use for multi-step business actions with dependencies, saved state,
# assertions, retries, conditional behavior, or escalation paths.
# -----------------------------------------------------------------------------
workflows:
  order_lifecycle:
    description: Create an order and verify that it can be retrieved.
    input: { $ref: '#/schemas/OrderCreate' }
    initial_state:
      order_exists: false
    steps:
      - id: submit
        uses: operation.place_order
        with:
          body: $input
          headers.Idempotency-Key: $context.idempotency_key
        save:
          order_id: $response.body.order_id
          order_status: $response.body.status
        assert:
          status: 201
          body.status: pending

      - id: inspect
        uses: operation.get_order
        with:
          path.order_id: $state.order_id
        retry: order_lookup_retry
        assert:
          status: 200
          body.order_id: $state.order_id
          body.sku: $input.sku
          body.quantity: $input.quantity
          body.status: pending
        on_failure:
          emit: order_lookup_failed
          action: escalate

    success:
      state:
        order_exists: true
        order_status: pending

# -----------------------------------------------------------------------------
# POLICIES
# WHEN TO USE: Use to enforce approvals, retries, rate limits, redaction, and
# evidence capture consistently across operations and workflows.
# -----------------------------------------------------------------------------
policies:
  defaults:
    fail_closed: true
    deny_unlisted_operations: true

  production_write_approval:
    type: approval
    match:
      environments: [production]
      effects: [write, destructive]
    require:
      approver_group: fulfillment-operations
      timeout: 15m
      on_timeout: reject
    evidence: [requester, approver, decision, reason, timestamp]

  order_lookup_retry:
    type: retry
    match:
      operation: get_order
      status: 404
    attempts: 3
    delay: 1s
    backoff: exponential
    max_delay: 5s

  place_order_rate_limit:
    type: rate_limit
    match:
      operation: place_order
    limit: 10
    window: 1m
    key: $actor.id
    on_exceed: block

  redact_sensitive_data:
    type: redaction
    paths:
      - $request.headers.authorization
      - $request.body.pii
      - $response.body.pii
    replacement: '[REDACTED]'

  capture_evidence:
    type: evidence
    capture:
      - actor
      - environment
      - request
      - response
      - policy_decisions
      - approvals
      - state_changes
      - assertions
      - retries
      - timestamps
      - execution_trace
    exclude:
      - secrets
      - authorization_tokens
      - hidden_model_reasoning

# -----------------------------------------------------------------------------
# AI AGENT GUARDRAILS
# WHEN TO USE: Use when an AI agent can call operations or workflows. Explicitly
# allow approved actions and environments; deny everything else by default.
# -----------------------------------------------------------------------------
agents:
  order_assistant:
    description: Support agent for creating and tracking orders.
    allow:
      operations: [place_order, get_order]
      workflows: [order_lifecycle]
      environments: [development, staging, production]
    deny:
      - unlisted_operations
      - direct_database_access
      - secret_access
    constraints:
      production_writes: approval_required
      max_quantity: 10
      max_actions_per_request: 1
      require_idempotency_for_writes: true
      require_post_write_verification: true
      prevent_duplicate_orders: true
    escalate_on:
      - approval_rejected
      - retry_exhausted
      - policy_blocked
    interfaces:
      slack:
        enabled: true
        bot_handle: '@OrderBot'
        allowed_channels: ['#support-ops', '#order-triage']
        require_thread_context: true
        require_actor_identity: true

tests:
  fixtures:
    valid_order: { sku: APP-YKM-992, quantity: 3 }

  cases:
    order_lifecycle_smoke:
      target: workflow.order_lifecycle
      environment: staging
      input: $fixtures.valid_order
      expect:
        status: success
        steps: { submit: 201, inspect: 200 }
        state: { order_exists: true, order_status: pending }

    reject_quantity_above_limit:
      target: operation.place_order
      environment: staging
      input: { sku: APP-YKM-992, quantity: 11 }
      expect: { status: 400 }

    require_production_approval:
      target: operation.place_order
      environment: production
      input: $fixtures.valid_order
      expect: { policy_decision: approval_required }

  generate:
    from: [schemas, operations, workflows, policies]
    categories: [edge, negative, schema, security, workflow]
    require_review: true

events:
  order_created:
    when: { operation: place_order, status: 201 }
    publish:
      topic: orders.created
      payload:
        order_id: $response.body.order_id
        status: $response.body.status
        correlation_id: $context.correlation_id

  order_lookup_failed:
    when: { workflow: order_lifecycle, step: inspect, condition: retry_exhausted }
    publish:
      topic: orders.lookup.failed
      payload:
        order_id: $state.order_id
        correlation_id: $context.correlation_id

runtime:
  correlation_id:
    generate: true
    response_header: X-Correlation-ID
  evidence:
    path: .supercontracts/runs/$run.id
    outputs:
      run: run.json
      state: state.json
      steps: steps.json
      events: events.jsonl
      io: io.json
      ai_context: ai_context.md
    integrity:
      hash_artifacts: true
      append_only_events: true
  ai_context:
    include:
      - execution_summary
      - policy_decisions
      - approval_history
      - failed_assertions
      - retry_history
      - final_state
      - remediation_hint
    exclude: [secrets, authorization_headers, hidden_model_reasoning]

mcp:
  server:
    name: order-service-mcp
    version: "1.0.0"
  tools:
    place_order: { uses: operation.place_order, risk: medium }
    get_order: { uses: operation.get_order, risk: low }
    run_order_lifecycle: { uses: workflow.order_lifecycle, risk: medium }
  safety:
    strict_mode: true
    deny_unlisted_tools: true
    validate_inputs: true
    validate_outputs: true
    enforce_agent_permissions: true
    enforce_environment_policies: true
  ide:
    cursor:
      enabled: true
      capabilities: [discover, execute, test, audit]
      evidence_path: .supercontracts/runs
      expose_decision_summary: true
      expose_hidden_model_reasoning: false

infrastructure:
  references:
    orders: { type: dynamodb, resource: orders }
    fulfillment: { type: sqs, resource: order-processing }