openapi: 3.1.0
info: {title: Project Alpha and AlphaLedger Integration, version: 1.0.0}
servers: [{url: https://project-alpha.example}]
paths:
  /api/v1/integrations/alphaledger/manifest:
    get: {summary: Discover PA identity, business display defaults, and capabilities, responses: {'200': {description: Manifest containing business_id and optional business_name, timezone, and currency}}}
  /api/v1/integrations/alphaledger/installations:
    post: {summary: Register an AlphaLedger callback, responses: {'201': {description: Installation and webhook secret}}}
  /api/v1/integrations/alphaledger/changes:
    get: {summary: Pull ordered PA-owned changes, parameters: [{name: cursor, in: query, schema: {type: string}}], responses: {'200': {description: Events and next cursor}}}
  /api/v1/integrations/alphaledger/time-records/batch:
    post: {summary: Idempotently ingest approved time events, responses: {'200': {description: Per-event results}}}
  /api/v1/integrations/alphaledger/pay-accruals/batch:
    post: {summary: Idempotently ingest approved pay events, responses: {'200': {description: Per-event results}}}
  /api/v1/integrations/alphaledger/ledger-records/batch:
    post:
      summary: Ingest signed operational Ledger deltas or snapshot pages
      parameters:
        - {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 255}}
        - {name: X-AL-Timestamp, in: header, required: true, schema: {type: string, format: date-time}}
        - {name: X-AL-Signature, in: header, required: true, schema: {type: string, pattern: '^[a-f0-9]{64}$'}}
      responses:
        '200': {description: Per-record results and snapshot completion state}
        '401': {description: Invalid or expired direction-bound signature}
        '413': {description: Request exceeds one MiB}
        '422': {description: Strict schema validation failed}
  /api/v1/integrations/alphaledger/reconciliation:
    post: {summary: Request reconciliation, responses: {'202': {description: Accepted}}}
components:
  schemas:
    EventEnvelope:
      type: object
      required: [schema_version,event_id,event_type,occurred_at,installation_id,aggregate_id,revision,data]
      properties:
        schema_version: {const: '1.0'}
        event_id: {type: string, format: uuid}
        event_type: {type: string}
        occurred_at: {type: string, format: date-time}
        installation_id: {type: string}
        aggregate_id: {type: string}
        revision: {type: integer, minimum: 1}
        currency: {type: [string, 'null'], pattern: '^[A-Z]{3}$'}
        data: {type: object}
    OperationalLedgerRecord:
      type: object
      additionalProperties: false
      required: [event_id,entity_type,entity_id,revision,occurred_at,operation,data]
      properties:
        event_id: {type: string, format: uuid}
        entity_type: {enum: [employee,project,assignment,time_entry,break,revision,pay_accrual]}
        entity_id: {type: string, maxLength: 128}
        revision: {type: integer, minimum: 1}
        occurred_at: {type: string, format: date-time}
        operation: {enum: [upsert,tombstone]}
        data: {type: object}