relayfile-v1.openapi.yaml

openapi: 3.1.0
info:
  title: RelayFile API
  version: 1.0.0
  summary: Secure filesystem-over-REST contract for RelayFile
  description: |
    RelayFile exposes a workspace-scoped virtual filesystem with optimistic
    concurrency, async write-back operations, and event feeds.

    Security model:
    - Agent and service access uses Bearer JWT with workspace and scope claims.
    - Internal relay-cloud -> relayfile ingress uses HMAC-signed requests.
    - Correlation IDs are required for traceability and audit.
servers:
  - url: https://relayfile.agent-relay.com
    description: Production
  - url: https://relayfile.staging.agent-relay.com
    description: Staging
tags:
  - name: Filesystem
  - name: Forks
  - name: Events
  - name: Operations
  - name: Sync
  - name: Internal
  - name: Admin
security:
  - BearerAuth: []
paths:
  /health:
    get:
      tags: [Admin]
      operationId: healthCheck
      summary: Health check endpoint
      description: Returns a simple status indicator for load balancers and monitoring.
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [status]
                properties:
                  status:
                    type: string
                    enum: [ok]

  /v1/workspaces/{workspaceId}/fs/tree:
    get:
      tags: [Filesystem]
      operationId: listTree
      summary: List filesystem entries under a path
      description: |
        Lists entries visible to the caller under a base path.
        File entries include semantic counters (`propertyCount`, `relationCount`,
        `permissionCount`, `commentCount`).

        Visibility is permission-aware:
        - inherited `.relayfile.acl` marker files on ancestor directories
        - target file `semantics.permissions`
        - deny rules override allow rules
      security:
        - BearerAuth: [fs:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: path
          in: query
          required: false
          schema:
            type: string
            default: /
            pattern: '^/.*'
        - name: depth
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - $ref: '#/components/parameters/ForkId'
      responses:
        '200':
          description: Tree listing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreeResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/fs/ws:
    get:
      tags: [Events]
      operationId: fileEventsWebSocket
      summary: WebSocket stream of real-time filesystem change events
      description: |
        Opens a WebSocket connection that streams filesystem events for the
        workspace in real time. Authentication is via a `token` query parameter
        containing a valid JWT (same format as the Bearer token).

        The server sends JSON messages with `type`, `path`, `revision`, and
        `timestamp` fields. The client may send `{"type":"ping"}` to keep the
        connection alive; the server responds with `{"type":"pong"}`.

        Updated clients should pass `from=now` for live-only subscriptions, or
        an exclusive `cursor` event id to catch up only events after that
        cursor. Repeated `path` query parameters restrict both catch-up and
        live delivery to exact path/glob filters. Legacy clients that omit
        `from`, `cursor`, and `path` keep the historical recent-event catch-up
        behavior.
      security:
        - BearerAuth: [fs:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: token
          in: query
          required: true
          description: JWT token for authentication (same as Bearer token value)
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Use `now` to skip historical catch-up and subscribe only to live events.
          schema:
            type: string
            enum: [now]
        - name: cursor
          in: query
          required: false
          description: Exclusive filesystem event id cursor for bounded reconnect catch-up.
          schema:
            type: string
        - name: path
          in: query
          required: false
          description: Exact path or trailing-`**`/single-segment-`*` path filter. Repeat to subscribe to multiple paths.
          schema:
            type: array
            items:
              type: string
              pattern: '^/.*'
          style: form
          explode: true
      responses:
        '101':
          description: WebSocket upgrade successful
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'

  /v1/workspaces/{workspaceId}/fs/bulk:
    post:
      tags: [Filesystem]
      operationId: bulkWriteFiles
      summary: Write multiple files in a single request
      description: |
        Writes multiple files atomically within a workspace. Each file is
        individually permission-checked; files that fail permission checks are
        reported in the `errors` array while permitted files are written.
      security:
        - BearerAuth: [fs:write]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/ForkId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkWriteRequest'
      responses:
        '202':
          description: Bulk write accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkWriteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/fs/export:
    get:
      tags: [Filesystem]
      operationId: exportWorkspace
      summary: Export all visible files in a workspace
      description: |
        Exports all files visible to the caller under effective permission rules.
        Supports multiple output formats: JSON (default), tar (gzipped tarball),
        or patch (unified diff format).
      security:
        - BearerAuth: [fs:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/ForkId'
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, tar, patch]
            default: json
        - name: path
          in: query
          required: false
          description: Export only files under this workspace path prefix
          schema:
            type: string
            default: /
            pattern: '^/.*'
      responses:
        '200':
          description: Export data in requested format
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileReadResponse'
            application/gzip:
              schema:
                type: string
                format: binary
            text/plain:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/fs/file:
    get:
      tags: [Filesystem]
      operationId: readFile
      summary: Read file contents at a path
      description: |
        Reads a file if effective permission rules allow access.
        Effective permissions include inherited `.relayfile.acl` marker rules and
        target file `semantics.permissions`. Deny rules override allow rules.
      security:
        - BearerAuth: [fs:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: '^/.*'
        - $ref: '#/components/parameters/ForkId'
      responses:
        '200':
          description: File read success
          headers:
            ETag:
              description: Current file revision identifier
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileReadResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      tags: [Filesystem]
      operationId: writeFile
      summary: Write file content with optimistic concurrency
      description: |
        Writes file content with optimistic concurrency (`If-Match`).
        Permission checks are applied before mutation:
        - existing file updates/deletes use effective permissions on the target file
        - new-file creates use inherited directory permission markers
      security:
        - BearerAuth: [fs:write]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/IfMatch'
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: '^/.*'
        - $ref: '#/components/parameters/ForkId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileWriteRequest'
      responses:
        '202':
          description: Write accepted and queued for provider write-back
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteQueuedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      tags: [Filesystem]
      operationId: deleteFile
      summary: Delete a file with optimistic concurrency
      description: |
        Deletes a file with optimistic concurrency (`If-Match`) after effective
        permission checks. Effective permissions include inherited
        `.relayfile.acl` marker rules and target file `semantics.permissions`.
      security:
        - BearerAuth: [fs:write]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - $ref: '#/components/parameters/IfMatch'
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: '^/.*'
        - $ref: '#/components/parameters/ForkId'
      responses:
        '202':
          description: Delete accepted and queued for provider write-back
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WriteQueuedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/fs/events:
    get:
      tags: [Events]
      operationId: listFilesystemEvents
      summary: Read ordered filesystem change events from a cursor
      security:
        - BearerAuth: [fs:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: provider
          in: query
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 200
        - name: direction
          in: query
          required: false
          description: |
            Iteration direction. `asc` (default) walks events newer than
            `cursor` oldest-first — the normal incremental sync path.
            `desc` walks newest-first and is intended for callers that just
            need the tail of the feed (e.g. `direction=desc&limit=1` to
            seed an events cursor without paginating the whole history).
          schema:
            type: string
            enum: [asc, desc]
            default: asc
      responses:
        '200':
          description: Event feed page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventFeedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/fs/query:
    get:
      tags: [Filesystem]
      operationId: queryFiles
      summary: Query files by path, provider, and semantic filters
      description: |
        Returns files that match path/provider/semantic filters and are visible to
        the caller under effective permission rules.

        Permission filter behavior:
        - `permission` query filter is matched against effective permissions
        - effective permissions include inherited `.relayfile.acl` markers plus
          target file `semantics.permissions`
        - deny rules override allow rules
      security:
        - BearerAuth: [fs:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: path
          in: query
          required: false
          schema:
            type: string
            pattern: '^/.*'
        - name: provider
          in: query
          required: false
          schema:
            type: string
        - name: relation
          in: query
          required: false
          schema:
            type: string
        - name: permission
          in: query
          required: false
          schema:
            type: string
        - name: comment
          in: query
          required: false
          schema:
            type: string
        - name: property.<key>
          in: query
          required: false
          description: |
            Property equality filter. Replace `<key>` with the semantic property
            name. Example: `property.stage=active`.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - $ref: '#/components/parameters/ForkId'
      responses:
        '200':
          description: Matching files page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/forks:
    post:
      tags: [Forks]
      operationId: createFork
      summary: Create a fork (isolated copy) of the workspace for staged proposals
      description: |
        Creates a fork of the workspace state that can be read and written
        independently without affecting the main workspace. Fork writes are
        committed atomically via the commit endpoint or discarded entirely.

        An optional `proposalId` may be supplied to make fork creation
        idempotent: a second call with the same `proposalId` returns 409 instead
        of creating a duplicate. An optional `ttlSeconds` controls how long the
        fork lives before it expires (server default applies when omitted).
      security:
        - BearerAuth: [fs:write]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                proposalId:
                  type: string
                  description: Idempotency key — reusing the same value returns 409 if a fork already exists for this proposal.
                ttlSeconds:
                  type: integer
                  format: int64
                  minimum: 0
                  description: Fork lifetime in seconds. Omit to use the server default.
      responses:
        '200':
          description: Fork created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkHandle'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: A fork for this proposalId already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/forks/{forkId}:
    delete:
      tags: [Forks]
      operationId: discardFork
      summary: Discard a fork and all staged changes
      description: |
        Permanently deletes the fork and all files staged within it.
        This action is irreversible. Use when a proposal is rejected or
        no longer needed.
      security:
        - BearerAuth: [fs:write]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: forkId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '204':
          description: Fork discarded
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/forks/{forkId}/commit:
    post:
      tags: [Forks]
      operationId: commitFork
      summary: Commit staged fork changes into the main workspace
      description: |
        Atomically merges all files staged in the fork into the main workspace.
        Each file in the fork is permission-checked against the caller's JWT
        claims (path scope and permission policy) before the commit proceeds.

        Returns a conflict if any parent directory was moved since the fork was
        created (`parent_moved`), or 410 Gone if the fork has expired.
      security:
        - BearerAuth: [fs:write]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: forkId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Fork committed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkCommitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Commit denied by path scope or permission policy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict — a parent directory was moved since the fork was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkCommitConflictResponse'
        '410':
          description: Fork has expired and can no longer be committed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/ops/{opId}:
    get:
      tags: [Operations]
      operationId: getWritebackOperation
      summary: Get write-back operation status
      security:
        - BearerAuth: [ops:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: opId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Operation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/ops:
    get:
      tags: [Operations]
      operationId: listWritebackOperations
      summary: List write-back operations with optional status filtering
      security:
        - BearerAuth: [ops:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, running, succeeded, failed, dead_lettered, canceled]
        - name: action
          in: query
          required: false
          schema:
            type: string
            enum: [file_upsert, file_delete]
        - name: provider
          in: query
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Operation list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationFeedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/ops/{opId}/replay:
    post:
      tags: [Operations]
      operationId: replayWritebackOperation
      summary: Replay a workspace write-back operation
      security:
        - BearerAuth: [ops:replay]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: opId
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '202':
          description: Replay accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Operation is not replayable in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/status:
    get:
      tags: [Sync]
      operationId: getSyncStatus
      summary: Get provider sync health and cursor state for a workspace
      security:
        - BearerAuth: [sync:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: provider
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Sync status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/ingress:
    get:
      tags: [Sync]
      operationId: getSyncIngressStatus
      summary: Get webhook ingress queue and drop counters for a workspace
      security:
        - BearerAuth: [sync:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: provider
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Webhook ingress status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/dead-letter:
    get:
      tags: [Sync]
      operationId: getSyncDeadLetters
      summary: List failed webhook envelopes that exhausted retries
      security:
        - BearerAuth: [sync:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: provider
          in: query
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
      responses:
        '200':
          description: Dead-letter envelope list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeadLetterFeedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/dead-letter/{envelopeId}/replay:
    post:
      tags: [Sync]
      operationId: replaySyncDeadLetter
      summary: Replay a failed envelope from workspace dead-letter queue
      security:
        - BearerAuth: [sync:trigger]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: envelopeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Replay accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/dead-letter/{envelopeId}/ack:
    post:
      tags: [Sync]
      operationId: acknowledgeSyncDeadLetter
      summary: Acknowledge and clear a failed envelope from workspace dead-letter queue
      security:
        - BearerAuth: [sync:trigger]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: envelopeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dead-letter acknowledged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AckResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/dead-letter/{envelopeId}:
    get:
      tags: [Sync]
      operationId: getSyncDeadLetterById
      summary: Get a single failed envelope from the workspace dead-letter queue
      security:
        - BearerAuth: [sync:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: envelopeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dead-letter envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeadLetterItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/sync/refresh:
    post:
      tags: [Sync]
      operationId: triggerSyncRefresh
      summary: Trigger a provider refresh/reconciliation job
      security:
        - BearerAuth: [sync:trigger]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncRefreshRequest'
      responses:
        '202':
          description: Refresh job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/internal/webhook-envelopes:
    post:
      tags: [Internal]
      operationId: ingestWebhookEnvelope
      summary: Internal relay-cloud ingestion endpoint for normalized envelopes
      description: |
        Internal endpoint intended for relay-cloud only.
        Request must be HMAC signed and timestamp bounded to prevent replay.
      security:
        - InternalHmacAuth: []
      parameters:
        - $ref: '#/components/parameters/InternalTimestamp'
        - $ref: '#/components/parameters/InternalSignature'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEnvelopeRequest'
      responses:
        '202':
          description: Envelope accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Duplicate envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          description: Ingress queue full, retry with backoff and jitter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/admin/backends:
    get:
      tags: [Admin]
      operationId: getBackendStatus
      summary: Get active state and queue backend implementations
      security:
        - BearerAuth: [admin:read]
        - BearerAuth: [admin:replay]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: Backend status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackendStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/admin/ingress:
    get:
      tags: [Admin]
      operationId: getAdminIngressStatus
      summary: Get webhook ingress status map across workspaces
      security:
        - BearerAuth: [admin:read]
        - BearerAuth: [admin:replay]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - name: workspaceId
          in: query
          required: false
          schema:
            type: string
        - name: provider
          in: query
          required: false
          schema:
            type: string
        - name: alertProfile
          in: query
          required: false
          schema:
            type: string
            enum: [strict, balanced, relaxed]
            default: balanced
        - name: pendingThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 100
        - name: deadLetterThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: staleThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: dropRateThreshold
          in: query
          required: false
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
            default: 0.05
        - name: nonZeroOnly
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: maxAlerts
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 200
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 200
        - name: includeWorkspaces
          in: query
          required: false
          schema:
            type: boolean
            default: true
        - name: includeAlerts
          in: query
          required: false
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Workspace ingress status map
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngressStatusMapResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/admin/sync:
    get:
      tags: [Admin]
      operationId: getAdminSyncStatus
      summary: Get sync status map and failure aggregates across workspaces
      security:
        - BearerAuth: [admin:read]
        - BearerAuth: [admin:replay]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - name: workspaceId
          in: query
          required: false
          schema:
            type: string
        - name: provider
          in: query
          required: false
          schema:
            type: string
        - name: nonZeroOnly
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 200
        - name: includeWorkspaces
          in: query
          required: false
          schema:
            type: boolean
            default: true
        - name: statusErrorThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: lagSecondsThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 30
        - name: deadLetteredEnvelopesThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: deadLetteredOpsThreshold
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: maxAlerts
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 200
        - name: includeAlerts
          in: query
          required: false
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Workspace sync status map
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSyncStatusMapResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/admin/replay/envelope/{envelopeId}:
    post:
      tags: [Admin]
      operationId: replayEnvelope
      summary: Replay a previously ingested envelope from durable storage
      security:
        - BearerAuth: [admin:replay]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - name: envelopeId
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Replay accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/admin/replay/op/{opId}:
    post:
      tags: [Admin]
      operationId: replayOperation
      summary: Replay a dead-lettered write-back operation
      security:
        - BearerAuth: [admin:replay]
      parameters:
        - $ref: '#/components/parameters/CorrelationId'
        - name: opId
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Replay accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Operation is not replayable in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/webhooks/ingest:
    post:
      tags: [Sync]
      operationId: ingestGenericWebhook
      summary: Ingest a generic webhook payload
      description: |
        Accepts a generic webhook payload from any provider.
        This is a provider-agnostic webhook ingestion endpoint that accepts
        envelopes in a standard format. The provider name and event type
        are specified in the payload, allowing any external service to
        submit webhook events for processing.
      security:
        - BearerAuth: [sync:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider, event_type, path]
              properties:
                provider:
                  type: string
                  description: Name of the provider (e.g., "salesforce", "slack", "github")
                  example: salesforce
                event_type:
                  type: string
                  description: Type of event (e.g., "file.updated", "file.deleted")
                  example: file.updated
                path:
                  type: string
                  description: Virtual filesystem path
                  pattern: '^/.*'
                  example: /documents/page123.md
                data:
                  type: object
                  description: Provider-specific payload data
                  example:
                    content: "# Updated Page"
                    title: "Page 123"
                delivery_id:
                  type: string
                  description: Optional delivery ID for deduplication
                  example: evt_123
                timestamp:
                  type: string
                  format: date-time
                  description: Event timestamp (defaults to now if not provided)
                headers:
                  type: object
                  additionalProperties:
                    type: string
                  description: Optional provider-specific headers
      responses:
        '202':
          description: Webhook accepted and queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueuedResponse'
        '400':
          description: Invalid webhook payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          description: Queue full, retry after specified delay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/writeback/pending:
    get:
      tags: [Sync]
      operationId: listPendingWritebacks
      summary: List pending writeback items
      description: |
        Retrieves all pending writeback items in the queue for this workspace.
        Writeback items are generated when files are modified and need to be
        propagated back to the source provider.
      security:
        - BearerAuth: [sync:read]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
      responses:
        '200':
          description: List of pending writeback items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WritebackPendingItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/writeback/{itemId}/ack:
    post:
      tags: [Sync]
      operationId: acknowledgeWriteback
      summary: Acknowledge a writeback item as processed
      description: |
        Marks a writeback item as successfully processed by the provider.
        Should be called after the writeback has been applied to the source system.
      security:
        - BearerAuth: [sync:trigger]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [success]
              properties:
                success:
                  type: boolean
                  description: Whether the writeback was successfully applied
                error:
                  type: string
                  description: Optional error message if success is false
                externalId:
                  type: string
                  description: |
                    Provider-assigned id of the created/updated object (e.g.
                    the Slack message ts). When present on a successful ack,
                    the service reconciles the agent-authored draft file per
                    the draftFile() rename contract: the draft is renamed to
                    the canonical id, or removed when the canonical record
                    already materialized. The mutation is classification-exempt
                    (it can never enqueue a new writeback) and is announced to
                    subscribers as system-origin file events.
                canonicalPath:
                  type: string
                  description: |
                    Optional canonical projection path for the draft rename.
                    Must stay under the same provider root as the draft;
                    otherwise the service falls back to the externalId-derived
                    name next to the draft.
      responses:
        '200':
          description: Acknowledgment accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [acknowledged]
                  id:
                    type: string
                  correlationId:
                    type: string
                  success:
                    type: boolean
                  draft:
                    type: object
                    description: |
                      Disposition of the agent-authored draft file. Present
                      only when the ack was successful and carried an
                      externalId.
                    properties:
                      action:
                        type: string
                        enum: [renamed, removed, none]
                      from:
                        type: string
                      to:
                        type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/workspaces/{workspaceId}/writeback/sweep-drafts:
    post:
      tags: [Sync]
      operationId: sweepWritebackDrafts
      summary: Drain accumulated writeback draft residue
      description: |
        One-time residue sweep (issue #242) for agent-authored writeback
        drafts that were delivered before the rename-at-ack contract existed
        and therefore accumulate forever at canonical provider roots.

        Matching is strictly name-shape based: the built-in draftFile()
        space-uuid form (`<resource> <uuid>.json`) always applies; hand-named
        drafts (e.g. `wb-*.json`) are only matched by explicitly supplied
        basename globs. Files linked to a provider object and drafts with a
        pending or running writeback are never touched.

        Dry run unless `apply` is true. Removals are classification-exempt:
        they can never enqueue new writebacks (no provider delete fanout) and
        are announced to subscribers as system-origin file.deleted events.
      security:
        - BearerAuth: [sync:trigger]
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pathPrefix:
                  type: string
                  description: Restrict the sweep to a subtree
                patterns:
                  type: array
                  items:
                    type: string
                  description: Basename globs for hand-named drafts, e.g. wb-*.json
                apply:
                  type: boolean
                  default: false
                  description: Execute removals; when false the sweep is a dry run
      responses:
        '200':
          description: Sweep result
          content:
            application/json:
              schema:
                type: object
                properties:
                  dryRun:
                    type: boolean
                  scanned:
                    type: integer
                  removed:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        reason:
                          type: string
                          enum: [space-uuid-draft, pattern]
                  skipped:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        reason:
                          type: string
                          enum: [pending-writeback, provider-linked]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT must include workspace and agent claims.
        Required claims:
        - workspace_id
        - agent_name
        - scopes
        - exp
        - aud=relayfile
    InternalHmacAuth:
      type: apiKey
      in: header
      name: X-Relay-Signature
      description: |
        HMAC SHA-256 signature of canonical request body using shared internal secret.
        Must be accompanied by X-Relay-Timestamp and replay window checks.

  parameters:
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    CorrelationId:
      name: X-Correlation-Id
      in: header
      required: true
      schema:
        type: string
        minLength: 8
        maxLength: 128
    ForkId:
      name: forkId
      in: query
      required: false
      description: |
        When provided, operations read from or write to this fork rather than
        the main workspace. Obtain a forkId by calling `POST /forks`.
      schema:
        type: string
        minLength: 1
    IfMatch:
      name: If-Match
      in: header
      required: true
      schema:
        type: string
        minLength: 1
      description: Required optimistic concurrency token (revision/etag).
    InternalTimestamp:
      name: X-Relay-Timestamp
      in: header
      required: true
      schema:
        type: string
        format: date-time
      description: Request timestamp validated against replay window.
    InternalSignature:
      name: X-Relay-Signature
      in: header
      required: true
      schema:
        type: string
        minLength: 16
      description: HMAC signature of request payload.

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Authorization failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Revision conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConflictErrorResponse'
    PreconditionFailed:
      description: Missing or invalid precondition header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: Request payload exceeds configured size limit
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Gone:
      description: Resource has expired and is no longer available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    TreeEntry:
      type: object
      additionalProperties: false
      required: [path, type, revision]
      properties:
        path:
          type: string
        type:
          type: string
          enum: [file, dir]
        revision:
          type: string
        contentHash:
          type: string
          description: SHA-256 hash of the decoded file bytes; omitted for directories
        provider:
          type: string
        providerObjectId:
          type: string
        size:
          type: integer
          minimum: 0
        updatedAt:
          type: string
          format: date-time
        propertyCount:
          type: integer
          minimum: 0
        relationCount:
          type: integer
          minimum: 0
        permissionCount:
          type: integer
          minimum: 0
        commentCount:
          type: integer
          minimum: 0

    FileSemantics:
      type: object
      additionalProperties: false
      properties:
        properties:
          type: object
          additionalProperties:
            type: string
        relations:
          type: array
          items:
            type: string
        permissions:
          type: array
          description: |
            Permission rules supporting:
            - `public` or `*`
            - `scope:<scope>`
            - `agent:<agentName>`
            - `workspace:<workspaceId>`
            Optional `allow:`/`deny:` prefixes are supported and deny wins.
          items:
            type: string
        comments:
          type: array
          items:
            type: string

    TreeResponse:
      type: object
      additionalProperties: false
      required: [path, entries]
      properties:
        path:
          type: string
        entries:
          type: array
          items:
            $ref: '#/components/schemas/TreeEntry'
        nextCursor:
          type: string
          nullable: true

    FileReadResponse:
      type: object
      additionalProperties: false
      required: [path, revision, contentType, content]
      properties:
        path:
          type: string
        revision:
          type: string
        contentHash:
          type: string
          description: SHA-256 hash of the decoded file bytes
        contentType:
          type: string
        content:
          type: string
        encoding:
          type: string
          description: Content encoding, e.g. "base64" for binary data
        provider:
          type: string
        providerObjectId:
          type: string
        lastEditedAt:
          type: string
          format: date-time
        semantics:
          $ref: '#/components/schemas/FileSemantics'

    FileWriteRequest:
      type: object
      additionalProperties: false
      required: [content]
      properties:
        contentType:
          type: string
          default: text/markdown
        content:
          type: string
        encoding:
          type: string
          description: Content encoding, e.g. "base64" for binary data
        semantics:
          $ref: '#/components/schemas/FileSemantics'

    FileQueryItem:
      type: object
      additionalProperties: false
      required: [path, revision, contentType, size]
      properties:
        path:
          type: string
        revision:
          type: string
        contentType:
          type: string
        provider:
          type: string
        providerObjectId:
          type: string
        lastEditedAt:
          type: string
          format: date-time
        size:
          type: integer
          minimum: 0
        properties:
          type: object
          additionalProperties:
            type: string
        relations:
          type: array
          items:
            type: string
        permissions:
          type: array
          items:
            type: string
        comments:
          type: array
          items:
            type: string

    FileQueryResponse:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileQueryItem'
        nextCursor:
          type: string
          nullable: true

    WriteQueuedResponse:
      type: object
      additionalProperties: false
      required: [opId, status, targetRevision]
      properties:
        opId:
          type: string
        status:
          type: string
          enum: [queued, pending]
        targetRevision:
          type: string
        writeback:
          type: object
          additionalProperties: false
          properties:
            provider:
              type: string
            state:
              type: string
              enum: [pending, succeeded, failed, dead_lettered]

    FilesystemEvent:
      type: object
      additionalProperties: false
      required: [eventId, type, path, revision, origin, correlationId, timestamp]
      properties:
        eventId:
          type: string
        type:
          type: string
          enum:
            - file.created
            - file.updated
            - file.deleted
            - dir.created
            - dir.deleted
            - sync.error
            - sync.ignored
            - sync.suppressed
            - sync.stale
            - writeback.failed
            - writeback.succeeded
        path:
          type: string
        revision:
          type: string
        contentHash:
          type: string
          description: SHA-256 hash of the decoded file bytes for create/update events
        origin:
          type: string
          enum: [provider_sync, agent_write, system]
        provider:
          type: string
        correlationId:
          type: string
        timestamp:
          type: string
          format: date-time

    EventFeedResponse:
      type: object
      additionalProperties: false
      required: [events]
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/FilesystemEvent'
        nextCursor:
          type: string
          nullable: true

    BackendStatusResponse:
      type: object
      additionalProperties: false
      required:
        - backendProfile
        - stateBackend
        - envelopeQueue
        - envelopeQueueDepth
        - envelopeQueueCapacity
        - writebackQueue
        - writebackQueueDepth
        - writebackQueueCapacity
      properties:
        backendProfile:
          type: string
        stateBackend:
          type: string
        envelopeQueue:
          type: string
        envelopeQueueDepth:
          type: integer
          minimum: 0
        envelopeQueueCapacity:
          type: integer
          minimum: 0
        writebackQueue:
          type: string
        writebackQueueDepth:
          type: integer
          minimum: 0
        writebackQueueCapacity:
          type: integer
          minimum: 0

    IngressStatusMapResponse:
      type: object
      additionalProperties: false
      required:
        - generatedAt
        - alertProfile
        - effectiveAlertProfile
        - workspaceCount
        - returnedWorkspaceCount
        - workspaceIds
        - pendingTotal
        - deadLetterTotal
        - acceptedTotal
        - droppedTotal
        - dedupedTotal
        - coalescedTotal
        - suppressedTotal
        - staleTotal
        - thresholds
        - alertTotals
        - alertsTruncated
        - alerts
        - workspaces
      properties:
        generatedAt:
          type: string
          format: date-time
        alertProfile:
          type: string
          enum: [strict, balanced, relaxed]
        effectiveAlertProfile:
          type: string
          enum: [strict, balanced, relaxed, custom]
        workspaceCount:
          type: integer
          minimum: 0
        returnedWorkspaceCount:
          type: integer
          minimum: 0
        workspaceIds:
          type: array
          items:
            type: string
        nextCursor:
          type: string
          nullable: true
        pendingTotal:
          type: integer
          minimum: 0
        deadLetterTotal:
          type: integer
          minimum: 0
        acceptedTotal:
          type: integer
          minimum: 0
        droppedTotal:
          type: integer
          minimum: 0
        dedupedTotal:
          type: integer
          minimum: 0
        coalescedTotal:
          type: integer
          minimum: 0
        suppressedTotal:
          type: integer
          minimum: 0
        staleTotal:
          type: integer
          minimum: 0
        thresholds:
          $ref: '#/components/schemas/AdminIngressAlertThresholds'
        alertTotals:
          $ref: '#/components/schemas/AdminIngressAlertTotals'
        alertsTruncated:
          type: boolean
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/AdminIngressAlert'
        workspaces:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/IngressStatusResponse'

    AdminIngressAlert:
      type: object
      additionalProperties: false
      required: [workspaceId, type, severity, value, threshold, message]
      properties:
        workspaceId:
          type: string
        type:
          type: string
          enum: [dead_letters, pending_backlog, drop_rate, stale_events]
        severity:
          type: string
          enum: [warning, critical]
        value:
          type: number
          format: float
        threshold:
          type: number
          format: float
        message:
          type: string

    AdminIngressAlertThresholds:
      type: object
      additionalProperties: false
      required: [pending, deadLetter, stale, dropRate]
      properties:
        pending:
          type: integer
          minimum: 1
        deadLetter:
          type: integer
          minimum: 1
        stale:
          type: integer
          minimum: 1
        dropRate:
          type: number
          format: float
          minimum: 0
          maximum: 1

    AdminIngressAlertTotals:
      type: object
      additionalProperties: false
      required: [total, critical, warning, byType]
      properties:
        total:
          type: integer
          minimum: 0
        critical:
          type: integer
          minimum: 0
        warning:
          type: integer
          minimum: 0
        byType:
          type: object
          additionalProperties:
            type: integer
            minimum: 0

    AdminSyncAlert:
      type: object
      additionalProperties: false
      required: [workspaceId, provider, type, severity, value, threshold, message]
      properties:
        workspaceId:
          type: string
        provider:
          type: string
        type:
          type: string
          enum: [status_error, lag_seconds, dead_lettered_envelopes, dead_lettered_ops]
        severity:
          type: string
          enum: [warning, critical]
        value:
          type: number
          format: float
        threshold:
          type: number
          format: float
        message:
          type: string

    AdminSyncAlertThresholds:
      type: object
      additionalProperties: false
      required: [statusError, lagSeconds, deadLetteredEnvelopes, deadLetteredOps]
      properties:
        statusError:
          type: integer
          minimum: 1
        lagSeconds:
          type: integer
          minimum: 1
        deadLetteredEnvelopes:
          type: integer
          minimum: 1
        deadLetteredOps:
          type: integer
          minimum: 1

    AdminSyncAlertTotals:
      type: object
      additionalProperties: false
      required: [total, critical, warning, byType]
      properties:
        total:
          type: integer
          minimum: 0
        critical:
          type: integer
          minimum: 0
        warning:
          type: integer
          minimum: 0
        byType:
          type: object
          additionalProperties:
            type: integer
            minimum: 0

    AdminSyncStatusMapResponse:
      type: object
      additionalProperties: false
      required:
        - generatedAt
        - workspaceCount
        - returnedWorkspaceCount
        - workspaceIds
        - providerStatusCount
        - healthyCount
        - laggingCount
        - errorCount
        - pausedCount
        - deadLetteredEnvelopesTotal
        - deadLetteredOpsTotal
        - thresholds
        - alertTotals
        - alertsTruncated
        - alerts
        - failureCodes
        - workspaces
      properties:
        generatedAt:
          type: string
          format: date-time
        workspaceCount:
          type: integer
          minimum: 0
        returnedWorkspaceCount:
          type: integer
          minimum: 0
        workspaceIds:
          type: array
          items:
            type: string
        nextCursor:
          type: string
          nullable: true
        providerStatusCount:
          type: integer
          minimum: 0
        healthyCount:
          type: integer
          minimum: 0
        laggingCount:
          type: integer
          minimum: 0
        errorCount:
          type: integer
          minimum: 0
        pausedCount:
          type: integer
          minimum: 0
        deadLetteredEnvelopesTotal:
          type: integer
          minimum: 0
        deadLetteredOpsTotal:
          type: integer
          minimum: 0
        thresholds:
          $ref: '#/components/schemas/AdminSyncAlertThresholds'
        alertTotals:
          $ref: '#/components/schemas/AdminSyncAlertTotals'
        alertsTruncated:
          type: boolean
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/AdminSyncAlert'
        failureCodes:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
        workspaces:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SyncStatusResponse'

    OperationStatusResponse:
      type: object
      additionalProperties: false
      required: [opId, status, attemptCount]
      properties:
        opId:
          type: string
        path:
          type: string
        revision:
          type: string
        action:
          type: string
          enum: [file_upsert, file_delete]
        provider:
          type: string
        status:
          type: string
          enum: [pending, running, succeeded, failed, dead_lettered, canceled]
        attemptCount:
          type: integer
          minimum: 0
        nextAttemptAt:
          type: string
          format: date-time
          nullable: true
        lastError:
          type: string
          nullable: true
        providerResult:
          type: object
          additionalProperties: true
        contentIdentity:
          $ref: '#/components/schemas/ContentIdentity'
        correlationId:
          type: string
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the operation was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the operation was last updated
        completedAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the operation reached a terminal state (succeeded/failed/dead_lettered)

    OperationFeedResponse:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OperationStatusResponse'
        nextCursor:
          type: string
          nullable: true

    SyncRefreshRequest:
      type: object
      additionalProperties: false
      required: [provider]
      properties:
        provider:
          type: string
        reason:
          type: string
          maxLength: 1000

    SyncStatusResponse:
      type: object
      additionalProperties: false
      required: [workspaceId, providers]
      properties:
        workspaceId:
          type: string
        providers:
          type: array
          items:
            type: object
            additionalProperties: false
            required: [provider, status]
            properties:
              provider:
                type: string
              status:
                type: string
                enum: [healthy, lagging, error, paused]
              cursor:
                type: string
                nullable: true
              watermarkTs:
                type: string
                format: date-time
                nullable: true
              lagSeconds:
                type: integer
                minimum: 0
              lastError:
                type: string
                nullable: true
              failureCodes:
                type: object
                additionalProperties:
                  type: integer
                  minimum: 0
              deadLetteredEnvelopes:
                type: integer
                minimum: 0
              deadLetteredOps:
                type: integer
                minimum: 0

    IngressStatusResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - queueDepth
        - queueCapacity
        - queueUtilization
        - pendingTotal
        - oldestPendingAgeSeconds
        - deadLetterTotal
        - deadLetterByProvider
        - acceptedTotal
        - droppedTotal
        - dedupedTotal
        - coalescedTotal
        - dedupeRate
        - coalesceRate
        - suppressedTotal
        - staleTotal
        - ingressByProvider
      properties:
        workspaceId:
          type: string
        queueDepth:
          type: integer
          minimum: 0
        queueCapacity:
          type: integer
          minimum: 1
        queueUtilization:
          type: number
          format: float
          minimum: 0
          maximum: 1
        pendingTotal:
          type: integer
          minimum: 0
        oldestPendingAgeSeconds:
          type: integer
          minimum: 0
        deadLetterTotal:
          type: integer
          minimum: 0
        deadLetterByProvider:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
        acceptedTotal:
          type: integer
          minimum: 0
        droppedTotal:
          type: integer
          minimum: 0
        dedupedTotal:
          type: integer
          minimum: 0
        coalescedTotal:
          type: integer
          minimum: 0
        dedupeRate:
          type: number
          format: float
          minimum: 0
          maximum: 1
        coalesceRate:
          type: number
          format: float
          minimum: 0
          maximum: 1
        suppressedTotal:
          type: integer
          minimum: 0
        staleTotal:
          type: integer
          minimum: 0
        ingressByProvider:
          type: object
          additionalProperties:
            type: object
            additionalProperties: false
            required:
              - acceptedTotal
              - droppedTotal
              - dedupedTotal
              - coalescedTotal
              - pendingTotal
              - oldestPendingAgeSeconds
              - suppressedTotal
              - staleTotal
              - dedupeRate
              - coalesceRate
            properties:
              acceptedTotal:
                type: integer
                minimum: 0
              droppedTotal:
                type: integer
                minimum: 0
              dedupedTotal:
                type: integer
                minimum: 0
              coalescedTotal:
                type: integer
                minimum: 0
              pendingTotal:
                type: integer
                minimum: 0
              oldestPendingAgeSeconds:
                type: integer
                minimum: 0
              suppressedTotal:
                type: integer
                minimum: 0
              staleTotal:
                type: integer
                minimum: 0
              dedupeRate:
                type: number
                format: float
                minimum: 0
                maximum: 1
              coalesceRate:
                type: number
                format: float
                minimum: 0
                maximum: 1

    DeadLetterFeedResponse:
      type: object
      additionalProperties: false
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DeadLetterItem'
        nextCursor:
          type: string
          nullable: true

    DeadLetterItem:
      type: object
      additionalProperties: false
      required:
        - envelopeId
        - workspaceId
        - provider
        - deliveryId
        - failedAt
        - attemptCount
        - lastError
      properties:
        envelopeId:
          type: string
        workspaceId:
          type: string
        provider:
          type: string
        deliveryId:
          type: string
        correlationId:
          type: string
        failedAt:
          type: string
          format: date-time
        attemptCount:
          type: integer
          minimum: 1
        lastError:
          type: string

    WebhookEnvelopeRequest:
      type: object
      additionalProperties: false
      required:
        - envelopeId
        - workspaceId
        - provider
        - deliveryId
        - receivedAt
        - payload
        - correlationId
      properties:
        envelopeId:
          type: string
        workspaceId:
          type: string
        provider:
          type: string
        deliveryId:
          type: string
        receivedAt:
          type: string
          format: date-time
        headers:
          type: object
          additionalProperties:
            type: string
        payload:
          type: object
          additionalProperties: true
        correlationId:
          type: string

    QueuedResponse:
      type: object
      additionalProperties: false
      required: [status, id]
      properties:
        status:
          type: string
          enum: [queued]
        id:
          type: string
        correlationId:
          type: string

    AckResponse:
      type: object
      additionalProperties: false
      required: [status, id]
      properties:
        status:
          type: string
          enum: [acknowledged]
        id:
          type: string
        correlationId:
          type: string

    ErrorResponse:
      type: object
      additionalProperties: false
      required: [code, message, correlationId]
      properties:
        code:
          type: string
        message:
          type: string
        correlationId:
          type: string
        details:
          type: object
          additionalProperties: true

    WritebackDeadLetterError:
      type: object
      additionalProperties: false
      required: [code, message, attempts, firstAttemptAt, lastAttemptAt, opId]
      properties:
        code:
          type: string
          description: Dead-letter classification code
          enum: [schema_violation, provider_4xx, provider_5xx_exhausted, timeout]
        message:
          type: string
          description: Human-readable failure details
        providerStatus:
          type: integer
          description: HTTP status returned by the provider, when available
        providerResponse:
          type: object
          additionalProperties: true
          description: Provider error response body, when available
        attempts:
          type: integer
          minimum: 1
          description: Number of delivery attempts; must be at least 1 when first/last attempt timestamps are present
        firstAttemptAt:
          type: string
          format: date-time
          description: Timestamp of the first delivery attempt
        lastAttemptAt:
          type: string
          format: date-time
          description: Timestamp of the most recent delivery attempt
        opId:
          type: string
          description: Operation ID associated with the failed writeback

    WritebackPendingItem:
      type: object
      additionalProperties: false
      required: [id, workspaceId, path, revision, correlationId]
      properties:
        id:
          type: string
          description: Operation ID for this pending writeback
        workspaceId:
          type: string
          description: Workspace identifier
        path:
          type: string
          description: Virtual filesystem path
          pattern: '^/.*'
        revision:
          type: string
          description: Current file revision
        correlationId:
          type: string
          description: Correlation ID for tracing
        contentIdentity:
          $ref: '#/components/schemas/ContentIdentity'

    WritebackItem:
      type: object
      additionalProperties: false
      required: [id, workspaceId, path, revision, correlationId, state]
      properties:
        id:
          type: string
          description: Operation ID for this writeback
        workspaceId:
          type: string
          description: Workspace identifier
        path:
          type: string
          description: Virtual filesystem path
          pattern: '^/.*'
        revision:
          type: string
          description: Current file revision
        correlationId:
          type: string
          description: Correlation ID for tracing
        state:
          type: string
          description: Writeback queue state, when returned by stateful list endpoints
          enum: [pending, succeeded, failed, dead_lettered, dead]
        opId:
          type: string
          description: Operation ID alias used by legacy/detail payloads
        provider:
          type: string
          description: Provider responsible for applying this writeback
        action:
          type: string
          description: Provider writeback action name
        ts:
          type: string
          format: date-time
          description: Event timestamp associated with the writeback
        code:
          type: string
          description: Dead-letter or provider failure classification
        message:
          type: string
          description: Human-readable failure details
        providerStatus:
          type: integer
          description: HTTP status returned by the provider, when available
        providerResponse:
          type: object
          additionalProperties: true
          description: Provider error response body, when available
        attempts:
          type: integer
          minimum: 0
          description: Number of delivery attempts
        attemptCount:
          type: integer
          minimum: 0
          description: Legacy alias for attempts
        firstAttemptAt:
          type: string
          format: date-time
          description: Timestamp of the first delivery attempt
        enqueuedAt:
          type: string
          format: date-time
          description: Timestamp when the writeback entered the queue
        createdAt:
          type: string
          format: date-time
          description: Legacy alias for enqueuedAt
        lastAttemptAt:
          type: string
          format: date-time
          description: Timestamp of the most recent delivery attempt
        error:
          $ref: '#/components/schemas/WritebackDeadLetterError'

    BulkWriteRequest:
      type: object
      additionalProperties: false
      required: [files]
      properties:
        files:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/BulkWriteFile'

    BulkWriteFile:
      type: object
      additionalProperties: false
      required: [path, contentType, content]
      properties:
        path:
          type: string
          pattern: '^/.*'
        contentType:
          type: string
        content:
          type: string
        encoding:
          type: string
          description: Content encoding, e.g. "base64" for binary data
        contentIdentity:
          $ref: '#/components/schemas/ContentIdentity'

    ContentIdentity:
      type: object
      additionalProperties: false
      required: [kind, key]
      properties:
        kind:
          type: string
          minLength: 1
          description: Dedupe namespace for this write identity
        key:
          type: string
          minLength: 1
          description: Caller-provided idempotency key within the namespace
        ttlSeconds:
          type: integer
          minimum: 0
          description: Optional lifetime for the dedupe identity in seconds

    BulkWriteError:
      type: object
      additionalProperties: false
      required: [path, code, message]
      properties:
        path:
          type: string
        code:
          type: string
        message:
          type: string

    BulkWriteResponse:
      type: object
      additionalProperties: false
      required: [written, errorCount, errors, correlationId]
      properties:
        written:
          type: integer
          minimum: 0
        errorCount:
          type: integer
          minimum: 0
        errors:
          type: array
          items:
            $ref: '#/components/schemas/BulkWriteError'
        correlationId:
          type: string

    ForkHandle:
      type: object
      additionalProperties: false
      required: [forkId, proposalId, workspaceId, expiresAt, parentRevision]
      properties:
        forkId:
          type: string
          description: Unique identifier for this fork. Pass as the `forkId` query parameter on filesystem endpoints.
        proposalId:
          type: string
          description: Idempotency key supplied at creation time (empty string if none was provided).
        workspaceId:
          type: string
        expiresAt:
          type: string
          format: date-time
          description: UTC time after which the fork expires and can no longer be committed.
        parentRevision:
          type: string
          description: Workspace revision at the time the fork was created.

    ForkCommitResponse:
      type: object
      additionalProperties: false
      required: [revision, writtenCount, deletedCount]
      properties:
        revision:
          type: string
          description: New workspace revision after the commit.
        writtenCount:
          type: integer
          minimum: 0
          description: Number of files written to the workspace.
        deletedCount:
          type: integer
          minimum: 0
          description: Number of files deleted from the workspace.

    ForkCommitConflictResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          additionalProperties: false
          required: [currentRevision]
          properties:
            currentRevision:
              type: string
              description: Current revision of the moved parent directory.

    ConflictErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          additionalProperties: false
          required: [expectedRevision, currentRevision]
          properties:
            expectedRevision:
              type: string
            currentRevision:
              type: string
            currentContentPreview:
              type: string
              maxLength: 4000