search.yaml

# Generated by `devtools render openapi`. Do not edit by hand.
# Source models: polylogue.surfaces.payloads query envelopes and polylogue.daemon.web_auth.
openapi: 3.1.0
info:
  title: Polylogue Search API
  version: '1'
  description: Local daemon HTTP API exposing typed query envelopes shared across CLI JSON, MCP, and the Python API. This
    document is generated from Pydantic models in `polylogue.surfaces.payloads` and `polylogue.daemon.web_auth`; do not edit
    by hand. Run `devtools render openapi` to regenerate.
servers:
- url: http://127.0.0.1:{port}
  description: Local Polylogue daemon (loopback only).
  variables:
    port:
      default: '8765'
      description: Daemon HTTP port; see `polylogued status`.
paths:
  /api/web-auth/session:
    post:
      summary: Bootstrap or rotate a first-party web credential
      description: Loopback, exact-origin browser bootstrap. The opaque credential is returned only in an HttpOnly SameSite=Strict
        cookie; the JSON body contains lifecycle metadata, scopes, and expiry but never credential bytes.
      operationId: bootstrapWebCredential
      security: []
      responses:
        '201':
          description: Credential issued and protected cookie set.
          headers:
            Set-Cookie:
              description: Protected HttpOnly first-party credential transport.
              schema:
                type: string
                writeOnly: true
            X-Polylogue-Web-Credential-State:
              schema:
                type: string
                const: ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCredentialBootstrapPayload'
        '400':
          description: Credential-shaped query parameters are forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorPayload'
        '403':
          description: Bootstrap origin was not the daemon's authority.
          headers:
            X-Polylogue-Web-Credential-State:
              schema:
                type: string
                enum: &id001
                - web_credential_missing
                - web_credential_invalid
                - web_credential_expired
                - web_credential_revoked
                - web_credential_wrong_origin
                - web_credential_insufficient_scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCredentialFailurePayload'
      x-polylogue-recoverable-states: *id001
    delete:
      summary: Revoke the current first-party web credential
      operationId: revokeWebCredential
      security:
      - webCredentialCookie: []
      responses:
        '200':
          description: Credential revoked and browser cookie expired.
          headers:
            Set-Cookie:
              description: Expires the protected first-party credential cookie.
              schema:
                type: string
                writeOnly: true
            X-Polylogue-Web-Credential-State:
              schema:
                type: string
                const: web_credential_revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCredentialRevocationPayload'
        '400':
          description: Credential-shaped query parameters are forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorPayload'
        '401':
          description: Credential is missing, invalid, expired, or revoked.
          headers:
            X-Polylogue-Web-Credential-State:
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCredentialFailurePayload'
        '403':
          description: Credential origin or scope is not admitted.
          headers:
            X-Polylogue-Web-Credential-State:
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebCredentialFailurePayload'
      x-polylogue-recoverable-states: *id001
  /api/sessions:
    get:
      summary: Ranked session search and list
      description: When ``query`` is supplied, returns a ranked search envelope (``SearchEnvelope``) with per-hit match evidence
        and pagination handles. When ``query`` is omitted, returns ``SessionListResponse``. Ranked search exposes the opaque
        ``next_cursor`` handle; the current list mode remains offset-based.
      operationId: searchSessions
      security:
      - machineBearer: []
      - webCredentialCookie: []
      parameters:
      - name: query
        in: query
        description: FTS5 search query string.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Page size (default 50).
        required: false
        schema:
          type: integer
          minimum: 1
          default: 50
      - name: offset
        in: query
        description: Row offset. Best-effort for ranked search; use ``next_cursor`` for stable pagination.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: provider
        in: query
        description: Provider name filter.
        required: false
        schema:
          type: string
      - name: since
        in: query
        description: ISO 8601 lower bound on session date.
        required: false
        schema:
          type: string
          format: date-time
      - name: retrieval_lane
        in: query
        description: 'Retrieval lane: ``auto``, ``dialogue``, ``actions``, ``hybrid``, ``semantic``.'
        required: false
        schema:
          type: string
          enum:
          - auto
          - dialogue
          - actions
          - hybrid
          - semantic
          default: auto
      - name: cursor
        in: query
        description: Opaque keyset cursor previously returned as ``next_cursor`` on a search response. Stable across archive
          growth and daemon restart (#1268). MUST be passed back unchanged. Rejected with 400 when malformed or when the retrieval
          lane no longer matches.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Ranked search envelope (when ``query`` is supplied) or session list envelope.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SearchEnvelope'
                - $ref: '#/components/schemas/SessionListResponse'
        '400':
          description: Malformed query or credential-shaped query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorPayload'
        '401':
          description: Machine bearer or web credential was not accepted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
        '403':
          description: Host, origin, or web credential scope was not admitted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
      x-polylogue-page:
        iterator: search
        initial_required_parameters:
        - query
        response_schemas:
        - SearchEnvelope
        items_property: hits
        cursor_property: next_cursor
        cursor_parameter: cursor
        continuation_request: merge
        reset_parameters:
        - offset
        coverage:
          total_property: total
          exactness_property: exactness
          exact_values:
          - exact
          default_exact: true
          qualified_values:
          - capped
          - sampled
          - estimate
  /api/query-units:
    get:
      summary: Terminal query-unit rows
      description: Returns terminal row results for explicit ``messages/actions/blocks/assertions/files/runs/observed-events/context-snapshots/delegations
        where ...`` expressions. This endpoint shares the query-unit row and aggregate envelope contracts with CLI JSON output,
        MCP ``query_units``, and ``Polylogue.query_units()``.
      operationId: queryUnits
      security:
      - machineBearer: []
      - webCredentialCookie: []
      parameters:
      - name: expression
        in: query
        description: 'Explicit unit-source expression for the first page. Omit it when passing an opaque ``continuation``.
          Examples: ``messages where session.repo:polylogue AND role:assistant AND text:timeout``; ``actions where session.repo:polylogue
          AND tool:bash AND text:pytest``; ``blocks where session.origin:codex-session AND type:code AND text:timeout``; ``assertions
          where kind:decision AND status:active AND text:review``; ``files where session.repo:polylogue AND action:file_edit
          AND path:archive/query``; ``runs where session.repo:polylogue AND role:main``; ``observed-events where kind:tool_finished
          AND status:failed | group by tool | count``; ``context-snapshots where boundary:session_start``; ``delegations where
          mapping_state:resolved AND instruction:review``.'
        required: false
        schema:
          type: string
      - name: continuation
        in: query
        description: Opaque QueryTransaction continuation returned by the previous page. Pass it back unchanged and without
          any other query parameters.
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Page size (default 50).
        required: false
        schema:
          type: integer
          minimum: 1
          default: 50
      - name: offset
        in: query
        description: Row offset for terminal query-unit pagination.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: origin
        in: query
        description: Optional session-origin scope for terminal row results.
        required: false
        schema:
          type: string
      - name: tag
        in: query
        description: Optional session tag scope for terminal row results.
        required: false
        schema:
          type: string
      - name: exclude_tag
        in: query
        description: Optional comma-separated session tags to exclude from terminal row results.
        required: false
        schema:
          type: string
      - name: repo
        in: query
        description: Optional comma-separated repo-name scope for terminal row results.
        required: false
        schema:
          type: string
      - name: has_type
        in: query
        description: Optional comma-separated block types required on the containing session.
        required: false
        schema:
          type: string
      - name: referenced_path
        in: query
        description: Optional comma-separated referenced paths required on the containing session.
        required: false
        schema:
          type: string
      - name: cwd_prefix
        in: query
        description: Optional working-directory prefix required on the containing session.
        required: false
        schema:
          type: string
      - name: tool
        in: query
        description: Optional comma-separated tool names required on the containing session.
        required: false
        schema:
          type: string
      - name: exclude_tool
        in: query
        description: Optional comma-separated tool names excluded from the containing session.
        required: false
        schema:
          type: string
      - name: action
        in: query
        description: Optional comma-separated action kinds required on the containing session.
        required: false
        schema:
          type: string
      - name: exclude_action
        in: query
        description: Optional comma-separated action kinds excluded from the containing session.
        required: false
        schema:
          type: string
      - name: action_sequence
        in: query
        description: Optional action sequence required on the containing session.
        required: false
        schema:
          type: string
      - name: action_text
        in: query
        description: Optional action text required on the containing session.
        required: false
        schema:
          type: string
      - name: title
        in: query
        description: Optional session-title substring scope for terminal row results.
        required: false
        schema:
          type: string
      - name: since
        in: query
        description: Optional session lower time bound, using the shared query date parser.
        required: false
        schema:
          type: string
      - name: until
        in: query
        description: Optional session upper time bound, using the shared query date parser.
        required: false
        schema:
          type: string
      - name: has_tool_use
        in: query
        description: Restrict terminal rows to sessions with tool-use evidence.
        required: false
        schema:
          type: boolean
          default: false
      - name: has_paste_evidence
        in: query
        description: Restrict terminal rows to sessions with paste evidence.
        required: false
        schema:
          type: boolean
          default: false
      - name: has_thinking
        in: query
        description: Restrict terminal rows to sessions with thinking blocks.
        required: false
        schema:
          type: boolean
          default: false
      - name: typed_only
        in: query
        description: Restrict terminal rows to typed sessions without paste evidence.
        required: false
        schema:
          type: boolean
          default: false
      - name: min_messages
        in: query
        description: Restrict terminal rows to sessions with at least this many messages.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: max_messages
        in: query
        description: Restrict terminal rows to sessions with at most this many messages.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: min_words
        in: query
        description: Restrict terminal rows to sessions with at least this many words.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: max_words
        in: query
        description: Restrict terminal rows to sessions with at most this many words.
        required: false
        schema:
          type: integer
          minimum: 0
      - name: message_type
        in: query
        description: Restrict terminal rows by session message-type evidence.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Terminal query-unit row or aggregate result envelope.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/QueryUnitEnvelope'
                - $ref: '#/components/schemas/QueryUnitAggregateEnvelope'
        '400':
          description: Malformed query or non-terminal session expression.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorPayload'
        '401':
          description: Machine bearer or web credential was not accepted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
        '403':
          description: Host, origin, or web credential scope was not admitted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
      x-polylogue-page:
        iterator: query
        initial_required_parameters:
        - expression
        response_schemas:
        - QueryUnitEnvelope
        - QueryUnitAggregateEnvelope
        items_property: items
        cursor_property: continuation
        cursor_parameter: continuation
        continuation_request: cursor_only
        query_ref_property: query_ref
        result_ref_property: result_ref
        coverage:
          total_property: total
          kind: qualified
          qualification: page
  /api/sessions/{session_id}/read:
    get:
      summary: Execute a session read-view
      description: Executes one supported single-session read profile and returns the stable ``SessionReadViewEnvelope``.
        Supported profiles currently include ``messages``, ``raw``, ``context``, ``context-image``, ``neighbors``, ``correlation``.
        The envelope shape is stable; individual ``payload`` content is the shared DTO for the selected read profile.
      operationId: readSessionView
      security:
      - machineBearer: []
      - webCredentialCookie: []
      parameters:
      - name: session_id
        in: path
        description: Resolved Polylogue session id.
        required: true
        schema:
          type: string
      - name: view
        in: query
        description: Read-view id from /api/read-view-profiles.
        required: false
        schema:
          type: string
          enum:
          - messages
          - raw
          - context
          - context-image
          - neighbors
          - correlation
          default: messages
      - name: format
        in: query
        description: Output format accepted by the selected read view.
        required: false
        schema:
          type: string
          enum:
          - json
          default: json
      - name: limit
        in: query
        required: false
        description: Messages/neighbor page size where applicable.
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        description: Message offset for the messages view.
        schema:
          type: integer
          minimum: 0
      - name: related_limit
        in: query
        required: false
        description: Number of related sessions to include in the context view.
        schema:
          type: integer
          minimum: 1
          default: 5
      - name: include_messages
        in: query
        required: false
        description: Include message excerpts in context-image payloads.
        schema:
          type: boolean
          default: true
      - name: max_tokens
        in: query
        required: false
        description: Token budget for the compiled context image; over-budget segments are omitted.
        schema:
          type: integer
          minimum: 1
      - name: no_redact
        in: query
        required: false
        description: Return unredacted context-image path/provenance details where available.
        schema:
          type: boolean
          default: false
      - name: window_hours
        in: query
        required: false
        description: Neighbor discovery window in hours.
        schema:
          type: integer
          minimum: 1
          default: 24
      - name: confidence_threshold
        in: query
        required: false
        description: Minimum confidence for correlation evidence.
        schema:
          type: number
          minimum: 0
          maximum: 1
          default: 0.3
      - name: repo_path
        in: query
        required: false
        description: Repository path for correlation evidence.
        schema:
          type: string
      - name: since_hours
        in: query
        required: false
        description: Correlation scan window on each side of the session.
        schema:
          type: integer
          minimum: 1
          default: 2
      responses:
        '200':
          description: Executed read-view envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionReadViewEnvelope'
        '400':
          description: Unsupported view/format or credential-shaped query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorPayload'
        '404':
          description: Session not found.
        '401':
          description: Machine bearer or web credential was not accepted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
        '403':
          description: Host, origin, or web credential scope was not admitted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
  /api/assertions:
    get:
      summary: List assertion-backed overlay claims
      description: Returns assertion claims through the stable ``AssertionClaimListPayload`` shared by the web workbench,
        Python API, and MCP assertion-read surface. Defaults to active and candidate claims; use ``status=all`` for an explicit
        full lifecycle read.
      operationId: listAssertionClaims
      security:
      - machineBearer: []
      - webCredentialCookie: []
      parameters:
      - name: target_ref
        in: query
        description: Optional target object ref, such as ``session:<id>``.
        required: false
        schema:
          type: string
      - name: scope_ref
        in: query
        description: Optional assertion scope object ref, such as ``repo:polylogue``.
        required: false
        schema:
          type: string
      - name: kind
        in: query
        description: Assertion kind filter. May be repeated or comma-separated.
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Lifecycle status filter. Defaults to active,candidate; ``all`` includes every persisted status.
        required: false
        schema:
          type: string
      - name: context_inject
        in: query
        description: Restrict by assertion context_policy.inject.
        required: false
        schema:
          type: boolean
      - name: limit
        in: query
        description: Maximum claims returned.
        required: false
        schema:
          type: integer
          minimum: 1
          default: 50
      responses:
        '200':
          description: Assertion claim list envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssertionClaimListPayload'
        '400':
          description: Malformed or credential-shaped query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorPayload'
        '401':
          description: Machine bearer or web credential was not accepted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
        '403':
          description: Host, origin, or web credential scope was not admitted.
          headers:
            X-Polylogue-Web-Credential-State:
              description: Present when the first-party web credential was evaluated.
              schema:
                type: string
                enum: *id001
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/QueryErrorPayload'
                - $ref: '#/components/schemas/WebCredentialFailurePayload'
components:
  schemas:
    ActionAffordancePayload:
      additionalProperties: false
      description: Shared static action-affordance contract for public action surfaces.
      properties:
        id:
          title: Id
          type: string
        path:
          items:
            type: string
          title: Path
          type: array
        effect:
          enum:
          - read
          - write
          - destructive
          - stream
          - ops
          - config
          - import
          title: Effect
          type: string
        target:
          enum:
          - none
          - selection
          - session
          - path
          - config
          - runtime
          - candidate
          title: Target
          type: string
        input:
          $ref: '#/components/schemas/ActionInputPayload'
        execution:
          $ref: '#/components/schemas/ActionExecutionPayload'
        output:
          $ref: '#/components/schemas/ActionOutputPayload'
        safety:
          $ref: '#/components/schemas/ActionSafetyPayload'
        availability:
          $ref: '#/components/schemas/ActionAvailabilityPayload'
      required:
      - id
      - path
      - effect
      - target
      - input
      - execution
      - output
      - safety
      - availability
      title: ActionAffordancePayload
      type: object
    ActionAvailabilityPayload:
      additionalProperties: false
      description: Availability and next-action posture for an affordance.
      properties:
        disabled_reason:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Disabled Reason
        estimated_cost:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Estimated Cost
        next_actions:
          default: []
          items:
            type: string
          title: Next Actions
          type: array
      title: ActionAvailabilityPayload
      type: object
    ActionExecutionPayload:
      additionalProperties: false
      description: Execution constraints for an affordance before the action runs.
      properties:
        cardinality_state:
          enum:
          - any
          - singleton
          - explicit_multi
          - destructive_multi
          title: Cardinality State
          type: string
        guards:
          default: []
          items:
            type: string
          title: Guards
          type: array
        requires_daemon:
          title: Requires Daemon
          type: boolean
      required:
      - cardinality_state
      - requires_daemon
      title: ActionExecutionPayload
      type: object
    ActionInputPayload:
      additionalProperties: false
      description: Input side of an action affordance. Keeps selection/query input explicit.
      properties:
        unit:
          enum:
          - none
          - query_result_set
          - session
          - path
          - config
          - runtime
          - assertion_candidate
          title: Unit
          type: string
        completion_context:
          anyOf:
          - enum:
            - config_key
            - filesystem_path
            - query_expression
            - session_id
            type: string
          - type: 'null'
          default: null
          title: Completion Context
      required:
      - unit
      title: ActionInputPayload
      type: object
    ActionOutputPayload:
      additionalProperties: false
      description: Output contract for an affordance.
      properties:
        destination_support:
          items:
            enum:
            - terminal
            - stdout
            - browser
            - clipboard
            - file
            - api
            - mcp
            type: string
          title: Destination Support
          type: array
        format_support:
          items:
            enum:
            - human
            - json
            - ndjson
            type: string
          title: Format Support
          type: array
        default_format:
          enum:
          - human
          - json
          - ndjson
          title: Default Format
          type: string
        machine_envelope:
          enum:
          - result_set
          - item
          - mutation
          - error
          - stream_item
          title: Machine Envelope
          type: string
      required:
      - destination_support
      - format_support
      - default_format
      - machine_envelope
      title: ActionOutputPayload
      type: object
    ActionSafetyPayload:
      additionalProperties: false
      description: Safety and confirmation posture for an affordance.
      properties:
        safety_level:
          enum:
          - safe
          - mutating
          - destructive
          - operational
          title: Safety Level
          type: string
        confirmation_command:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Confirmation Command
        selection_command:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Selection Command
      required:
      - safety_level
      title: ActionSafetyPayload
      type: object
    QueryMissDiagnosticsPayload:
      additionalProperties: false
      description: Shared diagnostics payload for zero-result queries.
      properties:
        message:
          title: Message
          type: string
        filters:
          items:
            type: string
          title: Filters
          type: array
        reasons:
          items:
            $ref: '#/components/schemas/QueryMissReasonPayload'
          title: Reasons
          type: array
        archive_session_count:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Archive Session Count
        raw_session_count:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Raw Session Count
      required:
      - message
      - filters
      - reasons
      title: QueryMissDiagnosticsPayload
      type: object
    QueryMissReasonPayload:
      additionalProperties: false
      description: Shared reason entry explaining why a query produced no results.
      properties:
        code:
          title: Code
          type: string
        severity:
          title: Severity
          type: string
        summary:
          title: Summary
          type: string
        detail:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Detail
        count:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Count
      required:
      - code
      - severity
      - summary
      title: QueryMissReasonPayload
      type: object
    ReaderActionAvailabilityPayload:
      additionalProperties: false
      description: 'Per-target reader action availability with explicit disabled reason.


        Reader actions surface seven distinct states (see :data:`ReaderActionState`)

        so the UI can render "disabled because X" / "loading" / "dangerous"

        without conflating them under a single boolean (#1488). ``enabled`` is the

        compact actionability bit consumed by current reader clients; ``state`` is

        the richer reason category.'
      properties:
        enabled:
          default: true
          title: Enabled
          type: boolean
        state:
          default: enabled
          enum:
          - enabled
          - disabled
          - partial
          - dangerous
          - loading
          - target
          - unavailable
          title: State
          type: string
        disabled_reason:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Disabled Reason
        repair_path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Repair Path
        inspect_path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Inspect Path
      title: ReaderActionAvailabilityPayload
      type: object
    RouteReadinessPayload:
      additionalProperties: false
      description: 'Route-visible readiness state for a web reader panel.


        ``total=0`` can mean an empty archive, a scoped no-result query, or a

        degraded backend that cannot compute results. This payload lets browserless

        tests and the web shell distinguish those states without guessing from

        counters alone (#2304).'
      properties:
        state:
          enum:
          - ready
          - loading
          - empty
          - no_results
          - stale
          - degraded
          - failed
          - budget_exceeded
          title: State
          type: string
        route:
          title: Route
          type: string
        reason:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Reason
        component:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Component
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Generated At
        stale_available:
          default: false
          title: Stale Available
          type: boolean
      required:
      - state
      - route
      title: RouteReadinessPayload
      type: object
    SessionSearchHitPayload:
      additionalProperties: false
      description: Search-hit payload with summary identity and match evidence.
      properties:
        session:
          $ref: '#/components/schemas/SessionSummaryEnvelope'
        match:
          $ref: '#/components/schemas/SessionSearchMatchPayload'
      required:
      - session
      - match
      title: SessionSearchHitPayload
      type: object
    SessionSearchMatchPayload:
      additionalProperties: false
      description: "Evidence explaining why a session appeared in search results.\n\n``score_kind`` describes the meaning\
        \ of ``score`` so consumers don't\nhave to guess at ordering or comparability:\n\n- ``\"bm25\"`` — SQLite FTS5 raw\
        \ BM25 (lower magnitude = better match;\n  values typically negative; never comparable across queries).\n- ``\"rrf\"\
        `` — Reciprocal Rank Fusion (higher = stronger consensus;\n  ``score_components`` carries per-lane ``*_rank`` and\
        \ ``*_rrf``\n  contributions).\n- ``\"vector_distance\"`` — semantic distance (lower = closer).\n- ``None`` — no numeric\
        \ score (e.g. attachment-identity lane)."
      properties:
        rank:
          title: Rank
          type: integer
        retrieval_lane:
          title: Retrieval Lane
          type: string
        match_surface:
          title: Match Surface
          type: string
        target_ref:
          anyOf:
          - $ref: '#/components/schemas/TargetRefPayload'
          - type: 'null'
          default: null
        anchor:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Anchor
        actions:
          additionalProperties:
            $ref: '#/components/schemas/ReaderActionAvailabilityPayload'
          title: Actions
          type: object
        message_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Message Id
        snippet:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Snippet
        score:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Score
        score_kind:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Score Kind
        matched_terms:
          default: []
          items:
            type: string
          title: Matched Terms
          type: array
        score_components:
          additionalProperties:
            type: number
          title: Score Components
          type: object
        lane_rank:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          description: Rank within the primary contributing lane, when known.
          title: Lane Rank
        lane_contribution:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          description: Primary lane contribution to the public score, when known.
          title: Lane Contribution
        raw_score:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          description: Backend-native score before public interpretation.
          title: Raw Score
      required:
      - rank
      - retrieval_lane
      - match_surface
      title: SessionSearchMatchPayload
      type: object
    SessionSummaryEnvelope:
      additionalProperties: false
      description: Compact session envelope derived from ``SessionSummary``.
      properties:
        id:
          title: Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          default: null
          title: Title
          type: string
        title_source:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title Source
        title_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title Ref
        title_confidence:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Title Confidence
        message_count:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Message Count
        target_ref:
          anyOf:
          - $ref: '#/components/schemas/TargetRefPayload'
          - type: 'null'
          default: null
        anchor:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Anchor
        actions:
          additionalProperties:
            $ref: '#/components/schemas/ReaderActionAvailabilityPayload'
          title: Actions
          type: object
        created_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          title: Created At
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          title: Updated At
      required:
      - id
      - origin
      title: SessionSummaryEnvelope
      type: object
    TargetRefPayload:
      additionalProperties: false
      description: Stable reader target reference for selectable archive objects.
      properties:
        target_type:
          enum:
          - session
          - message
          title: Target Type
          type: string
        target_id:
          title: Target Id
          type: string
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Session Id
        message_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Message Id
        block_index:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Block Index
        identity_key:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Identity Key
      required:
      - target_type
      - target_id
      title: TargetRefPayload
      type: object
    SearchEnvelope:
      additionalProperties: false
      description: "Typed ranked-result envelope shared across CLI, MCP, API, and daemon HTTP.\n\nThis is the canonical search\
        \ response shape (#1266). The same envelope\nis emitted from every read surface so downstream consumers — shell\n\
        pipelines, LLM tool-use harnesses, web clients — see one stable\ncontract regardless of which surface produced the\
        \ result.\n\nFields:\n\n- ``hits``: ordered tuple of :class:`SessionSearchHitPayload`\n  (already evidence-bearing\
        \ — see #873).\n- ``total``: total number of matching sessions. Every read surface\n  (CLI, MCP, daemon HTTP, Python\
        \ API) computes this via the shared\n  ``spec.count()`` so the field carries a concrete count uniformly\n  (#1749).\
        \ ``None`` is reserved for the genuine no-spec case where a\n  surface emits a hits list with no backing query spec\
        \ to count from.\n- ``limit``: applied page size.\n- ``offset``: applied byte/row offset (offset-based pagination\
        \ is\n  \"best-effort, not stable\" for ranked results; prefer ``next_cursor``).\n- ``next_offset``: convenience pointer\
        \ for offset-based clients; only\n  set when more results are likely available.\n- ``next_cursor``: opaque keyset\
        \ cursor encoding (rank, session_id)\n  for stable rank-first pagination. Pass back unchanged in the\n  following\
        \ request.\n- ``query``: the search query text actually applied (after CLI/MCP/HTTP\n  coercion). Empty string when\
        \ there is no FTS query.\n- ``sort``: applied sort field, e.g. ``\"rank\"`` (default for ranked\n  search), ``\"date\"\
        ``, ``\"messages\"``. ``None`` when no explicit sort\n  was requested and the underlying lane order is preserved.\n\
        - ``retrieval_lane``: the *resolved* per-hit ranking lane — one of\n  ``\"dialogue\"``, ``\"actions\"``, ``\"hybrid\"\
        ``, ``\"semantic\"``,\n  ``\"auto\"``. This is distinct from the *request* ``retrieval_lane``\n  input parameter,\
        \ whose closed accepted vocabulary is only\n  ``QUERY_RETRIEVAL_LANES`` (``\"auto\"``/``\"dialogue\"``/``\"actions\"\
        ``/\n  ``\"hybrid\"``) — ``\"semantic\"`` is never a request lane (a vector-only\n  run is driven by ``similar_text``)\
        \ but IS reported here as the\n  resolved lane for vector hits (#1749). ``auto`` means the surface\n  left the lane\
        \ to the planner.\n- ``ranking_policy``: policy identifier the lane used to order hits.\n  Currently always :data:`RANKING_POLICY_MIXED`.\n\
        - ``ranking_policy_version``: numeric version of the ranking policy\n  so external consumers can detect ordering changes.\n\
        - ``action_affordances``: query-result actions clients may offer after\n  receiving this result set. This is intentionally\
        \ top-level so it is not\n  confused with per-hit reader actions in ``hit.match.actions``.\n- ``diagnostics``: optional\
        \ zero-result explanation when the query\n  produced no hits but filters were applied."
      properties:
        hits:
          items:
            $ref: '#/components/schemas/SessionSearchHitPayload'
          title: Hits
          type: array
        total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Next Offset
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Next Cursor
        query:
          title: Query
          type: string
        sort:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Sort
        retrieval_lane:
          title: Retrieval Lane
          type: string
        ranking_policy:
          default: mixed-bm25-rrf-vector
          title: Ranking Policy
          type: string
        ranking_policy_version:
          default: '1'
          title: Ranking Policy Version
          type: string
        action_affordances:
          default: []
          items:
            $ref: '#/components/schemas/ActionAffordancePayload'
          title: Action Affordances
          type: array
        diagnostics:
          anyOf:
          - $ref: '#/components/schemas/QueryMissDiagnosticsPayload'
          - type: 'null'
          default: null
        route_state:
          anyOf:
          - $ref: '#/components/schemas/RouteReadinessPayload'
          - type: 'null'
          default: null
        query_run_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Query Run Ref
        query_hash:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Query Hash
        result_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Result Fingerprint
        exactness:
          anyOf:
          - enum:
            - exact
            - capped
            - sampled
            - estimate
            type: string
          - type: 'null'
          default: null
          title: Exactness
      required:
      - hits
      - total
      - limit
      - offset
      - query
      - retrieval_lane
      title: SearchEnvelope
      type: object
    SessionFlagsPayload:
      additionalProperties: false
      description: Boolean flags summarizing session content characteristics.
      properties:
        has_tool_use:
          default: false
          title: Has Tool Use
          type: boolean
        has_thinking:
          default: false
          title: Has Thinking
          type: boolean
        has_paste_evidence:
          default: false
          title: Has Paste Evidence
          type: boolean
      title: SessionFlagsPayload
      type: object
    SessionListEnvelope:
      additionalProperties: false
      description: Session list-row envelope derived from ``Session``.
      properties:
        id:
          title: Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          default: null
          title: Title
          type: string
        title_source:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title Source
        title_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title Ref
        title_confidence:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Title Confidence
        target_ref:
          anyOf:
          - $ref: '#/components/schemas/TargetRefPayload'
          - type: 'null'
          default: null
        anchor:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Anchor
        actions:
          additionalProperties:
            $ref: '#/components/schemas/ReaderActionAvailabilityPayload'
          title: Actions
          type: object
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Created At
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Updated At
        message_count:
          default: 0
          title: Message Count
          type: integer
        tags:
          default: []
          items:
            type: string
          title: Tags
          type: array
        summary:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Summary
        words:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Words
        repo:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Repo
        cwd_display:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cwd Display
        flags:
          anyOf:
          - $ref: '#/components/schemas/SessionFlagsPayload'
          - type: 'null'
          default: null
        parent_refs:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          default: null
          title: Parent Refs
        child_refs:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          default: null
          title: Child Refs
        continuation:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Continuation
      required:
      - id
      - origin
      title: SessionListEnvelope
      type: object
    SessionListResponse:
      additionalProperties: false
      description: 'Shared response envelope for list and search results.


        All read surfaces (daemon HTTP, MCP, CLI JSON output) adapt this shape.'
      properties:
        items:
          items:
            $ref: '#/components/schemas/SessionListEnvelope'
          title: Items
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        query_description:
          items:
            type: string
          title: Query Description
          type: array
        diagnostics:
          anyOf:
          - $ref: '#/components/schemas/QueryMissDiagnosticsPayload'
          - type: 'null'
          default: null
        route_state:
          anyOf:
          - $ref: '#/components/schemas/RouteReadinessPayload'
          - type: 'null'
          default: null
      required:
      - items
      - total
      - limit
      - offset
      title: SessionListResponse
      type: object
    ActionQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for normalized tool/action evidence.
      properties:
        unit:
          const: action
          default: action
          title: Unit
          type: string
        session_id:
          title: Session Id
          type: string
        message_id:
          title: Message Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        tool_use_block_id:
          title: Tool Use Block Id
          type: string
        tool_result_block_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Result Block Id
        tool_name:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Name
        semantic_type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Semantic Type
        tool_command:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Command
        tool_path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Path
        occurred_at_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Occurred At Ms
        output_text:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Output Text
        is_error:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Is Error
        exit_code:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Exit Code
        followup_class:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Followup Class
        followup_message_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Followup Message Ref
      required:
      - session_id
      - message_id
      - origin
      - tool_use_block_id
      title: ActionQueryRowPayload
      type: object
    AssertionKind:
      description: 'Closed vocabulary for ``user.db`` assertion rows.


        The unified assertions table collapses the old user-tier overlay

        mini-systems. The SQLite column is stored as ``TEXT`` so the vocabulary can

        grow without forcing a user-tier schema bump; this enum is the typed

        runtime and surface boundary.'
      enum:
      - mark
      - highlight
      - annotation
      - correction
      - suppression
      - tag
      - metadata
      - saved_query
      - recall_pack
      - workspace_note
      - note
      - decision
      - caveat
      - lesson
      - blocker
      - handoff
      - judgment
      - run_state
      - prompt_eval
      - ontology_candidate
      - ontology_governance
      - transform_candidate
      - pathology
      - finding
      - secret_candidate
      - excision_record
      - excision_request
      - comparative_judgment
      title: AssertionKind
      type: string
    AssertionQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for user-tier assertions.
      properties:
        unit:
          const: assertion
          default: assertion
          title: Unit
          type: string
        assertion_id:
          title: Assertion Id
          type: string
        target_ref:
          title: Target Ref
          type: string
        scope_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Scope Ref
        kind:
          $ref: '#/components/schemas/AssertionKind'
        key:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Key
        body_text:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Body Text
        value:
          title: Value
        author_ref:
          title: Author Ref
          type: string
        author_kind:
          title: Author Kind
          type: string
        status:
          $ref: '#/components/schemas/AssertionStatus'
        visibility:
          $ref: '#/components/schemas/AssertionVisibility'
        evidence_refs:
          items:
            type: string
          title: Evidence Refs
          type: array
        staleness:
          title: Staleness
        context_policy:
          title: Context Policy
        created_at_ms:
          title: Created At Ms
          type: integer
        updated_at_ms:
          title: Updated At Ms
          type: integer
      required:
      - assertion_id
      - target_ref
      - kind
      - value
      - author_ref
      - author_kind
      - status
      - visibility
      - evidence_refs
      - staleness
      - context_policy
      - created_at_ms
      - updated_at_ms
      title: AssertionQueryRowPayload
      type: object
    AssertionStatus:
      description: Closed lifecycle state vocabulary for assertion rows.
      enum:
      - active
      - candidate
      - accepted
      - rejected
      - deferred
      - superseded
      - deleted
      - inactive
      title: AssertionStatus
      type: string
    AssertionVisibility:
      description: Closed visibility vocabulary for assertion rows.
      enum:
      - private
      - team
      - public
      title: AssertionVisibility
      type: string
    BlockQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for archive content blocks.
      properties:
        unit:
          const: block
          default: block
          title: Unit
          type: string
        block_id:
          title: Block Id
          type: string
        message_id:
          title: Message Id
          type: string
        session_id:
          title: Session Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        block_type:
          title: Block Type
          type: string
        position:
          title: Position
          type: integer
        text:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Text
        tool_name:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Name
        semantic_type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Semantic Type
        tool_command:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Command
        tool_path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Tool Path
      required:
      - block_id
      - message_id
      - session_id
      - origin
      - block_type
      - position
      title: BlockQueryRowPayload
      type: object
    ContextSnapshotQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for runtime-transform context snapshots.
      properties:
        unit:
          const: context-snapshot
          default: context-snapshot
          title: Unit
          type: string
        snapshot_ref:
          title: Snapshot Ref
          type: string
        session_id:
          title: Session Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        run_ref:
          title: Run Ref
          type: string
        boundary:
          title: Boundary
          type: string
        inheritance_mode:
          title: Inheritance Mode
          type: string
        segment_refs:
          items:
            type: string
          title: Segment Refs
          type: array
        evidence_refs:
          items:
            type: string
          title: Evidence Refs
          type: array
        metadata:
          additionalProperties:
            type: string
          title: Metadata
          type: object
      required:
      - snapshot_ref
      - session_id
      - origin
      - run_ref
      - boundary
      - inheritance_mode
      - segment_refs
      - evidence_refs
      - metadata
      title: ContextSnapshotQueryRowPayload
      type: object
    DelegationQueryRowPayload:
      additionalProperties: false
      description: Bounded terminal-query row for one delegation attempt.
      properties:
        unit:
          const: delegation
          default: delegation
          title: Unit
          type: string
        delegation_ref:
          title: Delegation Ref
          type: string
        parent_session_id:
          title: Parent Session Id
          type: string
        child_session_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Child Session Id
        parent_origin:
          title: Parent Origin
          type: string
        mapping_state:
          enum:
          - resolved
          - unresolved
          - edge_only
          - quarantined
          title: Mapping State
          type: string
        evidence_basis:
          enum:
          - action
          - edge
          title: Evidence Basis
          type: string
        instruction_message_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Instruction Message Id
        instruction_tool_use_block_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Instruction Tool Use Block Id
        instruction_preview:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Instruction Preview
        instruction_sha256:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Instruction Sha256
        instruction_truncated:
          default: false
          title: Instruction Truncated
          type: boolean
        artifact_block_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Artifact Block Id
        artifact_preview:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Artifact Preview
        artifact_sha256:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Artifact Sha256
        artifact_truncated:
          default: false
          title: Artifact Truncated
          type: boolean
        dispatch_turn_model:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Dispatch Turn Model
        requested_model:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Requested Model
        child_session_dominant_model:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Child Session Dominant Model
        result_is_error:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Result Is Error
        result_exit_code:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Result Exit Code
        result_status:
          enum:
          - ok
          - error
          - unknown
          title: Result Status
          type: string
        link_confidence:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Link Confidence
        link_method:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Link Method
        inheritance:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Inheritance
        evidence_refs:
          default: []
          items:
            type: string
          title: Evidence Refs
          type: array
      required:
      - delegation_ref
      - parent_session_id
      - parent_origin
      - mapping_state
      - evidence_basis
      - result_status
      title: DelegationQueryRowPayload
      type: object
    FileQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for affected file-path evidence.
      properties:
        unit:
          const: file
          default: file
          title: Unit
          type: string
        session_id:
          title: Session Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        path:
          title: Path
          type: string
        action_count:
          title: Action Count
          type: integer
        first_message_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: First Message Id
        first_tool_use_block_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: First Tool Use Block Id
        last_tool_use_block_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Tool Use Block Id
        first_seen_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: First Seen Ms
        last_seen_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Last Seen Ms
      required:
      - session_id
      - origin
      - path
      - action_count
      title: FileQueryRowPayload
      type: object
    MessageQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for archive messages.
      properties:
        unit:
          const: message
          default: message
          title: Unit
          type: string
        message_id:
          title: Message Id
          type: string
        session_id:
          title: Session Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        role:
          title: Role
          type: string
        message_type:
          title: Message Type
          type: string
        material_origin:
          default: unknown
          title: Material Origin
          type: string
        occurred_at_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Occurred At Ms
        position:
          title: Position
          type: integer
        word_count:
          title: Word Count
          type: integer
        text:
          title: Text
          type: string
      required:
      - message_id
      - session_id
      - origin
      - role
      - message_type
      - position
      - word_count
      - text
      title: MessageQueryRowPayload
      type: object
    ObservedEventQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for runtime-transform observed events.
      properties:
        unit:
          const: observed-event
          default: observed-event
          title: Unit
          type: string
        event_ref:
          title: Event Ref
          type: string
        session_id:
          title: Session Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        kind:
          title: Kind
          type: string
        summary:
          title: Summary
          type: string
        delivery_state:
          title: Delivery State
          type: string
        subject_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Subject Ref
        object_refs:
          items:
            type: string
          title: Object Refs
          type: array
        evidence_refs:
          items:
            type: string
          title: Evidence Refs
          type: array
      required:
      - event_ref
      - session_id
      - origin
      - kind
      - summary
      - delivery_state
      - object_refs
      - evidence_refs
      title: ObservedEventQueryRowPayload
      type: object
    RunQueryRowPayload:
      additionalProperties: false
      description: Shared terminal-query row for runtime-transform runs.
      properties:
        unit:
          const: run
          default: run
          title: Unit
          type: string
        run_ref:
          title: Run Ref
          type: string
        session_id:
          title: Session Id
          type: string
        origin:
          title: Origin
          type: string
        title:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Title
        native_session_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Native Session Id
        native_parent_session_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Native Parent Session Id
        parent_run_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Parent Run Ref
        agent_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Agent Ref
        lineage_refs:
          items:
            type: string
          title: Lineage Refs
          type: array
        provider_origin:
          title: Provider Origin
          type: string
        harness:
          title: Harness
          type: string
        role:
          title: Role
          type: string
        cwd:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cwd
        git_branch:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Git Branch
        status:
          title: Status
          type: string
        confidence:
          title: Confidence
          type: string
        transcript_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Transcript Ref
        evidence_refs:
          items:
            type: string
          title: Evidence Refs
          type: array
        context_snapshot_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Context Snapshot Ref
      required:
      - run_ref
      - session_id
      - origin
      - lineage_refs
      - provider_origin
      - harness
      - role
      - status
      - confidence
      - evidence_refs
      title: RunQueryRowPayload
      type: object
    QueryUnitEnvelope:
      additionalProperties: false
      description: Shared envelope for explicit terminal unit-source query results.
      properties:
        mode:
          const: query-unit
          default: query-unit
          title: Mode
          type: string
        unit:
          enum:
          - message
          - action
          - block
          - assertion
          - file
          - run
          - observed-event
          - context-snapshot
          - delegation
          title: Unit
          type: string
        query:
          title: Query
          type: string
        items:
          items:
            anyOf:
            - $ref: '#/components/schemas/MessageQueryRowPayload'
            - $ref: '#/components/schemas/ActionQueryRowPayload'
            - $ref: '#/components/schemas/BlockQueryRowPayload'
            - $ref: '#/components/schemas/AssertionQueryRowPayload'
            - $ref: '#/components/schemas/FileQueryRowPayload'
            - $ref: '#/components/schemas/RunQueryRowPayload'
            - $ref: '#/components/schemas/ObservedEventQueryRowPayload'
            - $ref: '#/components/schemas/ContextSnapshotQueryRowPayload'
            - $ref: '#/components/schemas/DelegationQueryRowPayload'
          title: Items
          type: array
        pipeline:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Pipeline
        pipeline_stages:
          default: []
          items:
            additionalProperties: true
            properties:
              kind:
                enum:
                - session_scope
                - sort
                - limit
                - offset
                - group
                - count
                type: string
              predicate:
                type: object
              sort:
                type: object
              value:
                type: integer
              field:
                type: string
              metric:
                enum:
                - count
                type: string
            required:
            - kind
            type: object
          title: Pipeline Stages
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Next Offset
        query_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Query Ref
        result_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Result Ref
        continuation:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Continuation
      required:
      - unit
      - query
      - items
      - total
      - limit
      - offset
      title: QueryUnitEnvelope
      type: object
    QueryUnitAggregateRowPayload:
      additionalProperties: false
      description: Grouped aggregate row over a terminal query-unit result set.
      properties:
        unit:
          enum:
          - message
          - action
          - block
          - assertion
          - file
          - run
          - observed-event
          - context-snapshot
          - delegation
          title: Unit
          type: string
        group_by:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Group By
        group_key:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Group Key
        count:
          title: Count
          type: integer
        metrics:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: number
              - type: integer
              - type: 'null'
            type: object
          - type: 'null'
          default: null
          title: Metrics
      required:
      - unit
      - count
      title: QueryUnitAggregateRowPayload
      type: object
    QueryUnitAggregateEnvelope:
      additionalProperties: false
      description: Shared envelope for terminal query-unit aggregate results.
      properties:
        mode:
          const: query-unit-aggregate
          default: query-unit-aggregate
          title: Mode
          type: string
        unit:
          enum:
          - message
          - action
          - block
          - assertion
          - file
          - run
          - observed-event
          - context-snapshot
          - delegation
          title: Unit
          type: string
        query:
          title: Query
          type: string
        items:
          items:
            $ref: '#/components/schemas/QueryUnitAggregateRowPayload'
          title: Items
          type: array
        pipeline:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Pipeline
        pipeline_stages:
          default: []
          items:
            additionalProperties: true
            properties:
              kind:
                enum:
                - session_scope
                - sort
                - limit
                - offset
                - group
                - count
                type: string
              predicate:
                type: object
              sort:
                type: object
              value:
                type: integer
              field:
                type: string
              metric:
                enum:
                - count
                type: string
            required:
            - kind
            type: object
          title: Pipeline Stages
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Next Offset
        query_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Query Ref
        result_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Result Ref
        continuation:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Continuation
      required:
      - unit
      - query
      - items
      - total
      - limit
      - offset
      title: QueryUnitAggregateEnvelope
      type: object
    SessionReadViewEnvelope:
      additionalProperties: false
      description: Stable daemon envelope for one executed session read-view.
      properties:
        session_id:
          title: Session Id
          type: string
        view:
          title: View
          type: string
        format:
          title: Format
          type: string
        target_refs:
          items:
            type: string
          title: Target Refs
          type: array
        object_refs:
          default: []
          items:
            type: string
          title: Object Refs
          type: array
        evidence_refs:
          default: []
          items:
            type: string
          title: Evidence Refs
          type: array
        caveats:
          default: []
          items:
            type: string
          title: Caveats
          type: array
        lossiness:
          title: Lossiness
          type: string
        evidence_policy:
          title: Evidence Policy
          type: string
        privacy_policy:
          title: Privacy Policy
          type: string
        actions:
          additionalProperties:
            $ref: '#/components/schemas/ReaderActionAvailabilityPayload'
          title: Actions
          type: object
        payload:
          description: Profile-specific JSON payload for the selected read view.
          title: Payload
      required:
      - session_id
      - view
      - format
      - target_refs
      - lossiness
      - evidence_policy
      - privacy_policy
      - payload
      title: SessionReadViewEnvelope
      type: object
    AssertionClaimPayload:
      additionalProperties: false
      description: Shared payload for assertion-backed lifecycle claims.
      properties:
        assertion_id:
          title: Assertion Id
          type: string
        scope_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Scope Ref
        target_ref:
          title: Target Ref
          type: string
        key:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Key
        kind:
          $ref: '#/components/schemas/AssertionKind'
        value:
          anyOf:
          - {}
          - type: 'null'
          default: null
          title: Value
        body_text:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Body Text
        author_ref:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Author Ref
        author_kind:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Author Kind
        evidence_refs:
          default: []
          items:
            type: string
          title: Evidence Refs
          type: array
        status:
          anyOf:
          - $ref: '#/components/schemas/AssertionStatus'
          - type: 'null'
          default: null
        visibility:
          anyOf:
          - $ref: '#/components/schemas/AssertionVisibility'
          - type: 'null'
          default: null
        confidence:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Confidence
        staleness:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Staleness
        context_policy:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Context Policy
        supersedes:
          default: []
          items:
            type: string
          title: Supersedes
          type: array
        created_at_ms:
          title: Created At Ms
          type: integer
        updated_at_ms:
          title: Updated At Ms
          type: integer
      required:
      - assertion_id
      - target_ref
      - kind
      - created_at_ms
      - updated_at_ms
      title: AssertionClaimPayload
      type: object
    AssertionClaimListPayload:
      additionalProperties: false
      description: Shared list envelope for assertion-backed lifecycle claims.
      properties:
        items:
          items:
            $ref: '#/components/schemas/AssertionClaimPayload'
          title: Items
          type: array
        total:
          title: Total
          type: integer
        limit:
          title: Limit
          type: integer
        statuses:
          anyOf:
          - items:
              $ref: '#/components/schemas/AssertionStatus'
            type: array
          - type: 'null'
          default: null
          title: Statuses
        kinds:
          anyOf:
          - items:
              $ref: '#/components/schemas/AssertionKind'
            type: array
          - type: 'null'
          default: null
          title: Kinds
      required:
      - items
      - total
      - limit
      title: AssertionClaimListPayload
      type: object
    WebCredentialReadyPayload:
      additionalProperties: false
      description: Public lifecycle metadata; the credential itself stays in Set-Cookie.
      properties:
        state:
          const: ready
          default: ready
          title: State
          type: string
        expires_at:
          format: date-time
          title: Expires At
          type: string
        scopes:
          items:
            enum:
            - read
            - user_state
            - events
            type: string
          title: Scopes
          type: array
      required:
      - expires_at
      - scopes
      title: WebCredentialReadyPayload
      type: object
    WebCredentialBootstrapPayload:
      additionalProperties: false
      properties:
        ok:
          const: true
          default: true
          title: Ok
          type: boolean
        credential:
          $ref: '#/components/schemas/WebCredentialReadyPayload'
      required:
      - credential
      title: WebCredentialBootstrapPayload
      type: object
    WebCredentialRevokedPayload:
      additionalProperties: false
      properties:
        state:
          const: web_credential_revoked
          default: web_credential_revoked
          title: State
          type: string
      title: WebCredentialRevokedPayload
      type: object
    WebCredentialRevocationPayload:
      additionalProperties: false
      properties:
        ok:
          const: true
          default: true
          title: Ok
          type: boolean
        credential:
          $ref: '#/components/schemas/WebCredentialRevokedPayload'
      required:
      - credential
      title: WebCredentialRevocationPayload
      type: object
    WebCredentialFailurePayload:
      additionalProperties: false
      description: Typed subset of the daemon error envelope returned by this contract.
      properties:
        ok:
          const: false
          default: false
          title: Ok
          type: boolean
        error:
          enum:
          - web_credential_missing
          - web_credential_invalid
          - web_credential_expired
          - web_credential_revoked
          - web_credential_wrong_origin
          - web_credential_insufficient_scope
          title: Error
          type: string
        detail:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Detail
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Field
      required:
      - error
      title: WebCredentialFailurePayload
      type: object
    QueryErrorPayload:
      additionalProperties: false
      description: 'Shared error payload for daemon HTTP, MCP, and other surfaces.


        Compatible with daemon HTTP''s ``{"ok": False, "error": ..., "detail": ...}``

        shape and MCP''s ``MCPErrorPayload``.'
      properties:
        ok:
          const: false
          default: false
          title: Ok
          type: boolean
        error:
          title: Error
          type: string
        detail:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Detail
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Field
      required:
      - error
      title: QueryErrorPayload
      type: object
    QueryBoolPredicateAst:
      additionalProperties: false
      description: N-ary Boolean operator over predicate subtrees.
      properties:
        kind:
          enum:
          - and
          - or
          title: Kind
          type: string
        children:
          items:
            discriminator:
              mapping:
                and: '#/components/schemas/QueryBoolPredicateAst'
                exists: '#/components/schemas/QueryExistsPredicateAst'
                field: '#/components/schemas/QueryFieldPredicateAst'
                fts: '#/components/schemas/QueryTextPredicateAst'
                lineage: '#/components/schemas/QueryLineagePredicateAst'
                not: '#/components/schemas/QueryNotPredicateAst'
                or: '#/components/schemas/QueryBoolPredicateAst'
                semantic: '#/components/schemas/QuerySemanticPredicateAst'
                sequence: '#/components/schemas/QuerySequencePredicateAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryFieldPredicateAst'
            - $ref: '#/components/schemas/QueryNotPredicateAst'
            - $ref: '#/components/schemas/QueryBoolPredicateAst'
            - $ref: '#/components/schemas/QueryExistsPredicateAst'
            - $ref: '#/components/schemas/QuerySequencePredicateAst'
            - $ref: '#/components/schemas/QueryTextPredicateAst'
            - $ref: '#/components/schemas/QuerySemanticPredicateAst'
            - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Children
          type: array
      required:
      - kind
      title: QueryBoolPredicateAst
      type: object
    QueryExistsPredicateAst:
      additionalProperties: false
      description: Correlated structural predicate over a child archive unit.
      properties:
        kind:
          const: exists
          default: exists
          title: Kind
          type: string
        unit:
          enum:
          - message
          - action
          - block
          - assertion
          - file
          - run
          - observed-event
          - context-snapshot
          - delegation
          title: Unit
          type: string
        child:
          discriminator:
            mapping:
              and: '#/components/schemas/QueryBoolPredicateAst'
              exists: '#/components/schemas/QueryExistsPredicateAst'
              field: '#/components/schemas/QueryFieldPredicateAst'
              fts: '#/components/schemas/QueryTextPredicateAst'
              lineage: '#/components/schemas/QueryLineagePredicateAst'
              not: '#/components/schemas/QueryNotPredicateAst'
              or: '#/components/schemas/QueryBoolPredicateAst'
              semantic: '#/components/schemas/QuerySemanticPredicateAst'
              sequence: '#/components/schemas/QuerySequencePredicateAst'
            propertyName: kind
          oneOf:
          - $ref: '#/components/schemas/QueryFieldPredicateAst'
          - $ref: '#/components/schemas/QueryNotPredicateAst'
          - $ref: '#/components/schemas/QueryBoolPredicateAst'
          - $ref: '#/components/schemas/QueryExistsPredicateAst'
          - $ref: '#/components/schemas/QuerySequencePredicateAst'
          - $ref: '#/components/schemas/QueryTextPredicateAst'
          - $ref: '#/components/schemas/QuerySemanticPredicateAst'
          - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Child
      required:
      - unit
      - child
      title: QueryExistsPredicateAst
      type: object
    QueryExpressionAstNodeAst:
      additionalProperties: false
      description: 'Mirrors ``_ast_payload()``''s dict shape: one entry-tagged AST node.'
      properties:
        entry:
          enum:
          - json
          - reference_pipeline
          - unit_source
          - boolean
          - compact
          title: Entry
          type: string
        clauses:
          anyOf:
          - items:
              $ref: '#/components/schemas/QueryExpressionClauseAst'
            type: array
          - type: 'null'
          default: null
          title: Clauses
        predicate:
          anyOf:
          - discriminator:
              mapping:
                and: '#/components/schemas/QueryBoolPredicateAst'
                exists: '#/components/schemas/QueryExistsPredicateAst'
                field: '#/components/schemas/QueryFieldPredicateAst'
                fts: '#/components/schemas/QueryTextPredicateAst'
                lineage: '#/components/schemas/QueryLineagePredicateAst'
                not: '#/components/schemas/QueryNotPredicateAst'
                or: '#/components/schemas/QueryBoolPredicateAst'
                semantic: '#/components/schemas/QuerySemanticPredicateAst'
                sequence: '#/components/schemas/QuerySequencePredicateAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryFieldPredicateAst'
            - $ref: '#/components/schemas/QueryNotPredicateAst'
            - $ref: '#/components/schemas/QueryBoolPredicateAst'
            - $ref: '#/components/schemas/QueryExistsPredicateAst'
            - $ref: '#/components/schemas/QuerySequencePredicateAst'
            - $ref: '#/components/schemas/QueryTextPredicateAst'
            - $ref: '#/components/schemas/QuerySemanticPredicateAst'
            - $ref: '#/components/schemas/QueryLineagePredicateAst'
          - type: 'null'
          default: null
          title: Predicate
        unit_source:
          anyOf:
          - $ref: '#/components/schemas/QueryUnitSourceAst'
          - type: 'null'
          default: null
        reference_pipeline:
          anyOf:
          - $ref: '#/components/schemas/ReferenceQueryPipelineAst'
          - type: 'null'
          default: null
      required:
      - entry
      title: QueryExpressionAstNodeAst
      type: object
    QueryExpressionClauseAst:
      additionalProperties: false
      description: Mirrors ``QueryExpressionExplainClause.to_payload()``.
      properties:
        kind:
          enum:
          - field
          - count
          - count_range
          - date
          - date_range
          - text
          - json
          title: Kind
          type: string
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Field
        value:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Value
        negated:
          default: false
          title: Negated
          type: boolean
        quoted:
          default: false
          title: Quoted
          type: boolean
        op:
          anyOf:
          - enum:
            - '='
            - '>'
            - '>='
            - <
            - <=
            type: string
          - type: 'null'
          default: null
          title: Op
        number:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Number
        min_number:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Min Number
        max_number:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Max Number
        min_value:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Min Value
        max_value:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Max Value
      required:
      - kind
      title: QueryExpressionClauseAst
      type: object
    QueryFieldPredicateAst:
      additionalProperties: false
      description: Leaf predicate over one supported session-query field.
      properties:
        kind:
          const: field
          default: field
          title: Kind
          type: string
        field:
          title: Field
          type: string
        op:
          default: '='
          enum:
          - '='
          - '>'
          - '>='
          - <
          - <=
          title: Op
          type: string
        values:
          items:
            type: string
          title: Values
          type: array
        field_ref:
          anyOf:
          - $ref: '#/components/schemas/QueryFieldRefAst'
          - type: 'null'
          default: null
      required:
      - field
      title: QueryFieldPredicateAst
      type: object
    QueryFieldRefAst:
      additionalProperties: false
      description: Validated field identity carried by a field-predicate leaf.
      properties:
        scope:
          enum:
          - session
          - unit
          title: Scope
          type: string
        name:
          title: Name
          type: string
        source_name:
          title: Source Name
          type: string
        unit:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Unit
      required:
      - scope
      - name
      - source_name
      title: QueryFieldRefAst
      type: object
    QueryLineagePredicateAst:
      additionalProperties: false
      description: Session-topology predicate selecting the seed's logical lineage.
      properties:
        kind:
          const: lineage
          default: lineage
          title: Kind
          type: string
        unit:
          const: session
          default: session
          title: Unit
          type: string
        seed_session_id:
          title: Seed Session Id
          type: string
      required:
      - seed_session_id
      title: QueryLineagePredicateAst
      type: object
    QueryLoweringPlanAst:
      additionalProperties: false
      description: Mirrors ``_lowering_plan_payload()``.
      properties:
        lowerer:
          title: Lowerer
          type: string
        selected_units:
          items:
            type: string
          title: Selected Units
          type: array
        execution_legs:
          items:
            type: string
          title: Execution Legs
          type: array
        plan_description:
          items:
            type: string
          title: Plan Description
          type: array
        compatibility_selector:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Compatibility Selector
        pipeline:
          anyOf:
          - $ref: '#/components/schemas/QueryUnitPipelineAst'
          - type: 'null'
          default: null
        pipeline_stages:
          anyOf:
          - items:
              discriminator:
                mapping:
                  count: '#/components/schemas/QueryUnitCountStageAst'
                  group: '#/components/schemas/QueryUnitGroupStageAst'
                  limit: '#/components/schemas/QueryUnitLimitStageAst'
                  offset: '#/components/schemas/QueryUnitOffsetStageAst'
                  session_scope: '#/components/schemas/QueryUnitSessionScopeStageAst'
                  sort: '#/components/schemas/QueryUnitSortStageAst'
                  terminal: '#/components/schemas/QueryUnitTerminalStageAst'
                  transform: '#/components/schemas/QueryUnitTransformStageAst'
                propertyName: kind
              oneOf:
              - $ref: '#/components/schemas/QueryUnitSessionScopeStageAst'
              - $ref: '#/components/schemas/QueryUnitSortStageAst'
              - $ref: '#/components/schemas/QueryUnitLimitStageAst'
              - $ref: '#/components/schemas/QueryUnitOffsetStageAst'
              - $ref: '#/components/schemas/QueryUnitGroupStageAst'
              - $ref: '#/components/schemas/QueryUnitCountStageAst'
              - $ref: '#/components/schemas/QueryUnitTransformStageAst'
              - $ref: '#/components/schemas/QueryUnitTerminalStageAst'
            type: array
          - type: 'null'
          default: null
          title: Pipeline Stages
        reference_lineage:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          default: null
          title: Reference Lineage
      required:
      - lowerer
      title: QueryLoweringPlanAst
      type: object
    QueryNotPredicateAst:
      additionalProperties: false
      description: Boolean negation over a predicate subtree.
      properties:
        kind:
          const: not
          default: not
          title: Kind
          type: string
        child:
          discriminator:
            mapping:
              and: '#/components/schemas/QueryBoolPredicateAst'
              exists: '#/components/schemas/QueryExistsPredicateAst'
              field: '#/components/schemas/QueryFieldPredicateAst'
              fts: '#/components/schemas/QueryTextPredicateAst'
              lineage: '#/components/schemas/QueryLineagePredicateAst'
              not: '#/components/schemas/QueryNotPredicateAst'
              or: '#/components/schemas/QueryBoolPredicateAst'
              semantic: '#/components/schemas/QuerySemanticPredicateAst'
              sequence: '#/components/schemas/QuerySequencePredicateAst'
            propertyName: kind
          oneOf:
          - $ref: '#/components/schemas/QueryFieldPredicateAst'
          - $ref: '#/components/schemas/QueryNotPredicateAst'
          - $ref: '#/components/schemas/QueryBoolPredicateAst'
          - $ref: '#/components/schemas/QueryExistsPredicateAst'
          - $ref: '#/components/schemas/QuerySequencePredicateAst'
          - $ref: '#/components/schemas/QueryTextPredicateAst'
          - $ref: '#/components/schemas/QuerySemanticPredicateAst'
          - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Child
      required:
      - child
      title: QueryNotPredicateAst
      type: object
    QuerySemanticPredicateAst:
      additionalProperties: false
      description: Semantic vector predicate over session message/block text.
      properties:
        kind:
          const: semantic
          default: semantic
          title: Kind
          type: string
        unit:
          const: session
          default: session
          title: Unit
          type: string
        text:
          title: Text
          type: string
      required:
      - text
      title: QuerySemanticPredicateAst
      type: object
    QuerySequenceConstraintAst:
      additionalProperties: false
      description: Constraint on the edge between two action-sequence steps.
      properties:
        kind:
          default: ordered
          enum:
          - ordered
          - next
          - within
          title: Kind
          type: string
        within_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Within Ms
      title: QuerySequenceConstraintAst
      type: object
    QuerySequencePredicateAst:
      additionalProperties: false
      description: Ordered action-sequence predicate over a session.
      properties:
        kind:
          const: sequence
          default: sequence
          title: Kind
          type: string
        unit:
          const: action
          default: action
          title: Unit
          type: string
        steps:
          items:
            discriminator:
              mapping:
                and: '#/components/schemas/QueryBoolPredicateAst'
                exists: '#/components/schemas/QueryExistsPredicateAst'
                field: '#/components/schemas/QueryFieldPredicateAst'
                fts: '#/components/schemas/QueryTextPredicateAst'
                lineage: '#/components/schemas/QueryLineagePredicateAst'
                not: '#/components/schemas/QueryNotPredicateAst'
                or: '#/components/schemas/QueryBoolPredicateAst'
                semantic: '#/components/schemas/QuerySemanticPredicateAst'
                sequence: '#/components/schemas/QuerySequencePredicateAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryFieldPredicateAst'
            - $ref: '#/components/schemas/QueryNotPredicateAst'
            - $ref: '#/components/schemas/QueryBoolPredicateAst'
            - $ref: '#/components/schemas/QueryExistsPredicateAst'
            - $ref: '#/components/schemas/QuerySequencePredicateAst'
            - $ref: '#/components/schemas/QueryTextPredicateAst'
            - $ref: '#/components/schemas/QuerySemanticPredicateAst'
            - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Steps
          type: array
        constraints:
          items:
            $ref: '#/components/schemas/QuerySequenceConstraintAst'
          title: Constraints
          type: array
        actions:
          items:
            type: string
          title: Actions
          type: array
      title: QuerySequencePredicateAst
      type: object
    QueryTextPredicateAst:
      additionalProperties: false
      description: Lexical FTS predicate over session message/block text.
      properties:
        kind:
          const: fts
          default: fts
          title: Kind
          type: string
        unit:
          const: session
          default: session
          title: Unit
          type: string
        text:
          title: Text
          type: string
      required:
      - text
      title: QueryTextPredicateAst
      type: object
    QueryUnitCountStageAst:
      additionalProperties: false
      properties:
        kind:
          const: count
          default: count
          title: Kind
          type: string
        metric:
          const: count
          default: count
          title: Metric
          type: string
      title: QueryUnitCountStageAst
      type: object
    QueryUnitGroupStageAst:
      additionalProperties: false
      properties:
        kind:
          const: group
          default: group
          title: Kind
          type: string
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Field
        fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          default: null
          title: Fields
      title: QueryUnitGroupStageAst
      type: object
    QueryUnitLimitStageAst:
      additionalProperties: false
      properties:
        kind:
          const: limit
          default: limit
          title: Kind
          type: string
        value:
          title: Value
          type: integer
      required:
      - value
      title: QueryUnitLimitStageAst
      type: object
    QueryUnitOffsetStageAst:
      additionalProperties: false
      properties:
        kind:
          const: offset
          default: offset
          title: Kind
          type: string
        value:
          title: Value
          type: integer
      required:
      - value
      title: QueryUnitOffsetStageAst
      type: object
    QueryUnitPipelineAst:
      additionalProperties: false
      description: Mirrors ``QueryUnitPipeline.to_payload()``.
      properties:
        source:
          $ref: '#/components/schemas/QueryUnitPipelineSourceAst'
        stages:
          items:
            discriminator:
              mapping:
                count: '#/components/schemas/QueryUnitCountStageAst'
                group: '#/components/schemas/QueryUnitGroupStageAst'
                limit: '#/components/schemas/QueryUnitLimitStageAst'
                offset: '#/components/schemas/QueryUnitOffsetStageAst'
                session_scope: '#/components/schemas/QueryUnitSessionScopeStageAst'
                sort: '#/components/schemas/QueryUnitSortStageAst'
                terminal: '#/components/schemas/QueryUnitTerminalStageAst'
                transform: '#/components/schemas/QueryUnitTransformStageAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryUnitSessionScopeStageAst'
            - $ref: '#/components/schemas/QueryUnitSortStageAst'
            - $ref: '#/components/schemas/QueryUnitLimitStageAst'
            - $ref: '#/components/schemas/QueryUnitOffsetStageAst'
            - $ref: '#/components/schemas/QueryUnitGroupStageAst'
            - $ref: '#/components/schemas/QueryUnitCountStageAst'
            - $ref: '#/components/schemas/QueryUnitTransformStageAst'
            - $ref: '#/components/schemas/QueryUnitTerminalStageAst'
          title: Stages
          type: array
        session_scope:
          anyOf:
          - discriminator:
              mapping:
                and: '#/components/schemas/QueryBoolPredicateAst'
                exists: '#/components/schemas/QueryExistsPredicateAst'
                field: '#/components/schemas/QueryFieldPredicateAst'
                fts: '#/components/schemas/QueryTextPredicateAst'
                lineage: '#/components/schemas/QueryLineagePredicateAst'
                not: '#/components/schemas/QueryNotPredicateAst'
                or: '#/components/schemas/QueryBoolPredicateAst'
                semantic: '#/components/schemas/QuerySemanticPredicateAst'
                sequence: '#/components/schemas/QuerySequencePredicateAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryFieldPredicateAst'
            - $ref: '#/components/schemas/QueryNotPredicateAst'
            - $ref: '#/components/schemas/QueryBoolPredicateAst'
            - $ref: '#/components/schemas/QueryExistsPredicateAst'
            - $ref: '#/components/schemas/QuerySequencePredicateAst'
            - $ref: '#/components/schemas/QueryTextPredicateAst'
            - $ref: '#/components/schemas/QuerySemanticPredicateAst'
            - $ref: '#/components/schemas/QueryLineagePredicateAst'
          - type: 'null'
          default: null
          title: Session Scope
        result:
          anyOf:
          - $ref: '#/components/schemas/QueryUnitPipelineResultAst'
          - type: 'null'
          default: null
      required:
      - source
      title: QueryUnitPipelineAst
      type: object
    QueryUnitPipelineResultAst:
      additionalProperties: false
      properties:
        sort:
          anyOf:
          - $ref: '#/components/schemas/QueryUnitSortSpecAst'
          - type: 'null'
          default: null
        group_by:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Group By
        aggregate:
          anyOf:
          - const: count
            type: string
          - type: 'null'
          default: null
          title: Aggregate
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Limit
        offset:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Offset
      title: QueryUnitPipelineResultAst
      type: object
    QueryUnitPipelineSourceAst:
      additionalProperties: false
      properties:
        unit:
          enum:
          - message
          - action
          - block
          - assertion
          - file
          - run
          - observed-event
          - context-snapshot
          - delegation
          title: Unit
          type: string
        predicate:
          discriminator:
            mapping:
              and: '#/components/schemas/QueryBoolPredicateAst'
              exists: '#/components/schemas/QueryExistsPredicateAst'
              field: '#/components/schemas/QueryFieldPredicateAst'
              fts: '#/components/schemas/QueryTextPredicateAst'
              lineage: '#/components/schemas/QueryLineagePredicateAst'
              not: '#/components/schemas/QueryNotPredicateAst'
              or: '#/components/schemas/QueryBoolPredicateAst'
              semantic: '#/components/schemas/QuerySemanticPredicateAst'
              sequence: '#/components/schemas/QuerySequencePredicateAst'
            propertyName: kind
          oneOf:
          - $ref: '#/components/schemas/QueryFieldPredicateAst'
          - $ref: '#/components/schemas/QueryNotPredicateAst'
          - $ref: '#/components/schemas/QueryBoolPredicateAst'
          - $ref: '#/components/schemas/QueryExistsPredicateAst'
          - $ref: '#/components/schemas/QuerySequencePredicateAst'
          - $ref: '#/components/schemas/QueryTextPredicateAst'
          - $ref: '#/components/schemas/QuerySemanticPredicateAst'
          - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Predicate
      required:
      - unit
      - predicate
      title: QueryUnitPipelineSourceAst
      type: object
    QueryUnitSessionScopeStageAst:
      additionalProperties: false
      properties:
        kind:
          const: session_scope
          default: session_scope
          title: Kind
          type: string
        predicate:
          discriminator:
            mapping:
              and: '#/components/schemas/QueryBoolPredicateAst'
              exists: '#/components/schemas/QueryExistsPredicateAst'
              field: '#/components/schemas/QueryFieldPredicateAst'
              fts: '#/components/schemas/QueryTextPredicateAst'
              lineage: '#/components/schemas/QueryLineagePredicateAst'
              not: '#/components/schemas/QueryNotPredicateAst'
              or: '#/components/schemas/QueryBoolPredicateAst'
              semantic: '#/components/schemas/QuerySemanticPredicateAst'
              sequence: '#/components/schemas/QuerySequencePredicateAst'
            propertyName: kind
          oneOf:
          - $ref: '#/components/schemas/QueryFieldPredicateAst'
          - $ref: '#/components/schemas/QueryNotPredicateAst'
          - $ref: '#/components/schemas/QueryBoolPredicateAst'
          - $ref: '#/components/schemas/QueryExistsPredicateAst'
          - $ref: '#/components/schemas/QuerySequencePredicateAst'
          - $ref: '#/components/schemas/QueryTextPredicateAst'
          - $ref: '#/components/schemas/QuerySemanticPredicateAst'
          - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Predicate
      required:
      - predicate
      title: QueryUnitSessionScopeStageAst
      type: object
    QueryUnitSortSpecAst:
      additionalProperties: false
      description: Mirrors ``QueryUnitSort`` (field/direction).
      properties:
        field:
          enum:
          - time
          - count
          - key
          title: Field
          type: string
        direction:
          default: asc
          enum:
          - asc
          - desc
          title: Direction
          type: string
      required:
      - field
      title: QueryUnitSortSpecAst
      type: object
    QueryUnitSortStageAst:
      additionalProperties: false
      properties:
        kind:
          const: sort
          default: sort
          title: Kind
          type: string
        sort:
          $ref: '#/components/schemas/QueryUnitSortSpecAst'
      required:
      - sort
      title: QueryUnitSortStageAst
      type: object
    QueryUnitSourceAst:
      additionalProperties: false
      description: Mirrors the ``unit_source`` branch of ``_ast_payload()``.
      properties:
        unit:
          enum:
          - message
          - action
          - block
          - assertion
          - file
          - run
          - observed-event
          - context-snapshot
          - delegation
          title: Unit
          type: string
        predicate:
          discriminator:
            mapping:
              and: '#/components/schemas/QueryBoolPredicateAst'
              exists: '#/components/schemas/QueryExistsPredicateAst'
              field: '#/components/schemas/QueryFieldPredicateAst'
              fts: '#/components/schemas/QueryTextPredicateAst'
              lineage: '#/components/schemas/QueryLineagePredicateAst'
              not: '#/components/schemas/QueryNotPredicateAst'
              or: '#/components/schemas/QueryBoolPredicateAst'
              semantic: '#/components/schemas/QuerySemanticPredicateAst'
              sequence: '#/components/schemas/QuerySequencePredicateAst'
            propertyName: kind
          oneOf:
          - $ref: '#/components/schemas/QueryFieldPredicateAst'
          - $ref: '#/components/schemas/QueryNotPredicateAst'
          - $ref: '#/components/schemas/QueryBoolPredicateAst'
          - $ref: '#/components/schemas/QueryExistsPredicateAst'
          - $ref: '#/components/schemas/QuerySequencePredicateAst'
          - $ref: '#/components/schemas/QueryTextPredicateAst'
          - $ref: '#/components/schemas/QuerySemanticPredicateAst'
          - $ref: '#/components/schemas/QueryLineagePredicateAst'
          title: Predicate
        session_predicate:
          anyOf:
          - discriminator:
              mapping:
                and: '#/components/schemas/QueryBoolPredicateAst'
                exists: '#/components/schemas/QueryExistsPredicateAst'
                field: '#/components/schemas/QueryFieldPredicateAst'
                fts: '#/components/schemas/QueryTextPredicateAst'
                lineage: '#/components/schemas/QueryLineagePredicateAst'
                not: '#/components/schemas/QueryNotPredicateAst'
                or: '#/components/schemas/QueryBoolPredicateAst'
                semantic: '#/components/schemas/QuerySemanticPredicateAst'
                sequence: '#/components/schemas/QuerySequencePredicateAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryFieldPredicateAst'
            - $ref: '#/components/schemas/QueryNotPredicateAst'
            - $ref: '#/components/schemas/QueryBoolPredicateAst'
            - $ref: '#/components/schemas/QueryExistsPredicateAst'
            - $ref: '#/components/schemas/QuerySequencePredicateAst'
            - $ref: '#/components/schemas/QueryTextPredicateAst'
            - $ref: '#/components/schemas/QuerySemanticPredicateAst'
            - $ref: '#/components/schemas/QueryLineagePredicateAst'
          - type: 'null'
          default: null
          title: Session Predicate
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Limit
        offset:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Offset
        sort:
          anyOf:
          - $ref: '#/components/schemas/QueryUnitSortSpecAst'
          - type: 'null'
          default: null
        group_by:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Group By
        aggregate:
          anyOf:
          - const: count
            type: string
          - type: 'null'
          default: null
          title: Aggregate
        pipeline_stages:
          items:
            discriminator:
              mapping:
                count: '#/components/schemas/QueryUnitCountStageAst'
                group: '#/components/schemas/QueryUnitGroupStageAst'
                limit: '#/components/schemas/QueryUnitLimitStageAst'
                offset: '#/components/schemas/QueryUnitOffsetStageAst'
                session_scope: '#/components/schemas/QueryUnitSessionScopeStageAst'
                sort: '#/components/schemas/QueryUnitSortStageAst'
                terminal: '#/components/schemas/QueryUnitTerminalStageAst'
                transform: '#/components/schemas/QueryUnitTransformStageAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryUnitSessionScopeStageAst'
            - $ref: '#/components/schemas/QueryUnitSortStageAst'
            - $ref: '#/components/schemas/QueryUnitLimitStageAst'
            - $ref: '#/components/schemas/QueryUnitOffsetStageAst'
            - $ref: '#/components/schemas/QueryUnitGroupStageAst'
            - $ref: '#/components/schemas/QueryUnitCountStageAst'
            - $ref: '#/components/schemas/QueryUnitTransformStageAst'
            - $ref: '#/components/schemas/QueryUnitTerminalStageAst'
          title: Pipeline Stages
          type: array
        pipeline:
          $ref: '#/components/schemas/QueryUnitPipelineAst'
      required:
      - unit
      - predicate
      - pipeline
      title: QueryUnitSourceAst
      type: object
    QueryUnitTerminalStageAst:
      additionalProperties: false
      properties:
        kind:
          const: terminal
          default: terminal
          title: Kind
          type: string
        action:
          title: Action
          type: string
        args:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          default: null
          title: Args
      required:
      - action
      title: QueryUnitTerminalStageAst
      type: object
    QueryUnitTransformStageAst:
      additionalProperties: false
      properties:
        kind:
          const: transform
          default: transform
          title: Kind
          type: string
        name:
          title: Name
          type: string
        args:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          default: null
          title: Args
      required:
      - name
      title: QueryUnitTransformStageAst
      type: object
    RefOperandAst:
      additionalProperties: false
      description: Mirrors ``RefOperand.to_payload()``.
      properties:
        kind:
          const: ref_operand
          default: ref_operand
          title: Kind
          type: string
        reference:
          title: Reference
          type: string
        reference_kind:
          title: Reference Kind
          type: string
        evaluation_mode:
          enum:
          - re-evaluate
          - retained
          - resolver-defined
          title: Evaluation Mode
          type: string
        grain:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Grain
      required:
      - reference
      - reference_kind
      - evaluation_mode
      title: RefOperandAst
      type: object
    ReferenceQueryPipelineAst:
      additionalProperties: false
      description: Mirrors ``ReferenceQueryPipeline.to_payload()``.
      properties:
        source:
          $ref: '#/components/schemas/RefOperandAst'
        stages:
          items:
            type: string
          title: Stages
          type: array
      required:
      - source
      title: ReferenceQueryPipelineAst
      type: object
    QueryExpressionExplanationAst:
      additionalProperties: false
      description: 'Canonical, versioned projection of ``QueryExpressionExplanation.to_payload()``.


        This is the schema published in ``docs/openapi/search.yaml`` and the

        documented shape of the MCP ``explain`` operation''s ``kind="query"``

        result (``polylogue.mcp.server_cutover:explain`` ->

        ``Polylogue.explain_query_expression``). It is deliberately additive over

        history: every field already existed in the hand-rolled payload dict this

        module validates against; ``schema_version`` is the only new key.'
      properties:
        schema_version:
          const: polylogue.query-explain-ast.v1
          default: polylogue.query-explain-ast.v1
          title: Schema Version
          type: string
        source_text:
          title: Source Text
          type: string
        clauses:
          items:
            $ref: '#/components/schemas/QueryExpressionClauseAst'
          title: Clauses
          type: array
        predicate:
          anyOf:
          - discriminator:
              mapping:
                and: '#/components/schemas/QueryBoolPredicateAst'
                exists: '#/components/schemas/QueryExistsPredicateAst'
                field: '#/components/schemas/QueryFieldPredicateAst'
                fts: '#/components/schemas/QueryTextPredicateAst'
                lineage: '#/components/schemas/QueryLineagePredicateAst'
                not: '#/components/schemas/QueryNotPredicateAst'
                or: '#/components/schemas/QueryBoolPredicateAst'
                semantic: '#/components/schemas/QuerySemanticPredicateAst'
                sequence: '#/components/schemas/QuerySequencePredicateAst'
              propertyName: kind
            oneOf:
            - $ref: '#/components/schemas/QueryFieldPredicateAst'
            - $ref: '#/components/schemas/QueryNotPredicateAst'
            - $ref: '#/components/schemas/QueryBoolPredicateAst'
            - $ref: '#/components/schemas/QueryExistsPredicateAst'
            - $ref: '#/components/schemas/QuerySequencePredicateAst'
            - $ref: '#/components/schemas/QueryTextPredicateAst'
            - $ref: '#/components/schemas/QuerySemanticPredicateAst'
            - $ref: '#/components/schemas/QueryLineagePredicateAst'
          - type: 'null'
          default: null
          title: Predicate
        ast:
          anyOf:
          - $ref: '#/components/schemas/QueryExpressionAstNodeAst'
          - type: 'null'
          default: null
        lowerer:
          title: Lowerer
          type: string
        lowering_plan:
          anyOf:
          - $ref: '#/components/schemas/QueryLoweringPlanAst'
          - type: 'null'
          default: null
        selected_units:
          items:
            type: string
          title: Selected Units
          type: array
        execution_legs:
          items:
            type: string
          title: Execution Legs
          type: array
        plan_description:
          items:
            type: string
          title: Plan Description
          type: array
        unsupported_nodes:
          items:
            type: string
          title: Unsupported Nodes
          type: array
      required:
      - source_text
      - lowerer
      title: QueryExpressionExplanationAst
      type: object
  securitySchemes:
    machineBearer:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Machine-client token configured by --api-auth-token.
    webCredentialCookie:
      type: apiKey
      in: cookie
      name: polylogue_web_credential
      description: 'Short-lived, origin-bound HttpOnly credential issued by bootstrapWebCredential. Browser clients use credentials:
        same-origin and never read the cookie value.'
  x-polylogue-ranking-policy:
    default: mixed-bm25-rrf-vector
    version: '1'
    description: The ``ranking_policy`` and ``ranking_policy_version`` fields on ``SearchEnvelope`` declare the ordering semantics
      in use. Consumers should pin a known version and treat any change as a contract event.
x-polylogue-route-contracts:
- method: GET
  pattern: /
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: text/html web shell
  notes: HTML bootstrap only; shell JavaScript obtains an HttpOnly first-party credential before /api calls.
- method: GET
  pattern: /app
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: semantic archive overview HTML
  notes: SSR-first WebUI v2 strangler mount; Preact enhances only bounded continuation controls.
- method: GET
  pattern: /app/observability
  kind: browser_shell
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: semantic observability HTML
  notes: SSR-first registry and status projection; credentials protect embedded insight evidence when configured.
- method: GET
  pattern: /app/cost
  kind: browser_shell
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: semantic cost/usage HTML
  notes: SSR-first registry-driven cost rollup, usage timeline, and session drill-down; credentials protect embedded spend
    evidence when configured.
- method: GET
  pattern: /app/sessions
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: semantic session list HTML
  notes: SSR-first origin/date/repo faceted session list; Preact enhances only bounded pagination.
- method: GET
  pattern: /app/sessions/:session_id
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: semantic session read HTML
  notes: 'SSR-first session shell: header, lineage banner, and a simple message-flow placeholder Preact enhances with paging.'
- method: GET
  pattern: /app/search
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: semantic search results HTML
  notes: SSR-first ranked search over the shared SearchEnvelope; Preact enhances only cursor-based pagination.
- method: GET
  pattern: /app/assets/:asset
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: manifest-governed immutable Vite asset
  notes: Only content-hashed files named by the packaged Vite manifest are served.
- method: GET
  pattern: /s/:session_id
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: text/html web shell
  notes: Session deep-link bootstrap.
- method: GET
  pattern: /w/:mode
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: text/html web shell
  notes: Workspace shell bootstrap for registered workspace modes.
- method: GET
  pattern: /p
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: text/html paste browser
  notes: Standalone reader page; archive API calls remain authenticated.
- method: GET
  pattern: /a
  kind: browser_shell
  stability: shell_supported
  auth_policy: unauthenticated_loopback
  response_contract: text/html attachment library
  notes: Standalone reader page; archive API calls remain authenticated.
- method: GET
  pattern: /healthz/live
  kind: operational
  stability: operational
  auth_policy: unauthenticated_loopback
  response_contract: health liveness JSON
  notes: Unauthenticated for systemd/docker/kubernetes probes.
- method: GET
  pattern: /healthz/ready
  kind: operational
  stability: operational
  auth_policy: unauthenticated_loopback
  response_contract: health readiness JSON
  notes: Unauthenticated for systemd/docker/kubernetes probes.
- method: GET
  pattern: /metrics
  kind: operational
  stability: operational
  auth_policy: unauthenticated_loopback
  response_contract: Prometheus text exposition
  notes: Unauthenticated for Prometheus scrapers; no raw archive content.
- method: POST
  pattern: /api/web-auth/session
  kind: browser_shell
  stability: shell_supported
  auth_policy: first_party_same_origin
  response_contract: WebCredentialBootstrapPayload
  notes: Rotates a scoped HttpOnly credential; no credential bytes appear in the response body.
- method: DELETE
  pattern: /api/web-auth/session
  kind: browser_shell
  stability: shell_supported
  auth_policy: first_party_same_origin
  response_contract: WebCredentialRevocationPayload
  notes: Revokes the current first-party credential and expires its cookie.
- method: GET
  pattern: /api/health/check
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: JSON
- method: GET
  pattern: /api/health
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: JSON
- method: GET
  pattern: /api/status
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: Daemon status JSON
- method: GET
  pattern: /api/webui/observability
  kind: observability
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: WebUI observability projection
  notes: Registry descriptor fields, bounded rows, and the status-component snapshot adapter.
- method: GET
  pattern: /api/webui/freshness
  kind: observability
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: NamedSourceFreshness projection
  notes: Requires one explicit source path and rejects archive-wide scans.
- method: GET
  pattern: /api/overview
  kind: read_query
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: bounded cockpit overview
  notes: Privacy-safe landing aggregates, readiness, and a fixed recent-session page.
- method: GET
  pattern: /api/dev-loop
  kind: operational
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: DevLoopDebugPayload
  notes: Branch-local launcher metadata for the web shell; allowlisted fields only, no raw environment dump.
- method: GET
  pattern: /api/events
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: SSE or JSON event poll
- method: GET
  pattern: /api/agents/coordination
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: AgentCoordinationPayload
  notes: Shared coordination envelope used by CLI, MCP, and the web mission-control projection.
- method: GET
  pattern: /api/sessions
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: SearchEnvelope / SessionListResponse with route_state
- method: POST
  pattern: /api/cli/query
  kind: read_query
  stability: private
  auth_policy: credential_if_configured
  response_contract: SearchEnvelope / SessionListResponse with route_state
  notes: Local UDS-only root-request parameter envelope; daemon owns query compilation.
- method: POST
  pattern: /api/maintenance/rebuild-index
  kind: maintenance
  stability: operational
  auth_policy: bearer_if_configured_and_same_origin
  response_contract: RebuildIndexReceipt
  notes: Runs exactly one source snapshot replay through the daemon write coordinator.
- method: GET
  pattern: /api/facets
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: FacetsResponse with route-state metadata
  notes: Repo and action facet families are deferred from first paint unless explicitly requested.
- method: GET
  pattern: /api/query-units
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: QueryUnitResultEnvelope
- method: GET
  pattern: /api/provider-usage
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: ProviderUsageReport
  notes: Usage-accounting diagnostics; separates provider events, cumulative counters, transcript words, and model rollups.
- method: GET
  pattern: /api/archive-debt
  kind: operational
  stability: stable
  auth_policy: credential_if_configured
  response_contract: ArchiveDebtListPayload
  notes: Unified archive debt rows shared by CLI, Python API, MCP, and daemon clients.
- method: GET
  pattern: /api/import/explain
  kind: operational
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: ImportExplainPayload
  notes: Local import/source evidence explanation; paths are redacted unless explicitly requested.
- method: GET
  pattern: /api/refs/resolve
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: PublicRefResolutionPayload
- method: GET
  pattern: /api/query-completions
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: query completion metadata
- method: GET
  pattern: /api/action-affordances
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: ActionAffordanceListPayload
  notes: Shared query-action affordance inventory for CLI, daemon, and automation clients.
- method: GET
  pattern: /api/read-view-profiles
  kind: read_query
  stability: stable
  auth_policy: credential_if_configured
  response_contract: read-view profile metadata
- method: GET
  pattern: /api/assertions
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: AssertionClaimListPayload
  notes: Read-only assertion-backed overlay claims shared by the web workbench and API clients.
- method: GET
  pattern: /api/sources
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: source list JSON
- method: GET
  pattern: /api/sessions/:id
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: Session detail JSON
- method: GET
  pattern: /api/sessions/:id/messages
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: session messages JSON
- method: GET
  pattern: /api/sessions/:id/read
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: SessionReadViewEnvelope
  notes: Executes supported single-session read profiles over shared DTO/facade payload helpers.
- method: GET
  pattern: /api/sessions/:id/raw
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: raw session payload JSON
  notes: Raw preview is opt-in and authenticated.
- method: GET
  pattern: /api/sessions/:id/cost
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: cost JSON
- method: GET
  pattern: /api/sessions/:id/evidence-summary
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: bounded session evidence summary
  notes: Structural tool outcome counts, cost projection, and capped lineage refs for the transcript header.
- method: GET
  pattern: /api/sessions/:id/provenance
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: provenance envelope
  notes: Raw bytes require the include_raw query parameter.
- method: GET
  pattern: /api/sessions/:id/topology
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: topology envelope
- method: GET
  pattern: /api/sessions/:id/topology/parent-chain
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: parent-chain topology envelope
- method: GET
  pattern: /api/sessions/:id/similar
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: similar-session envelope
- method: GET
  pattern: /api/sessions/:id/attachments
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: session attachment envelope
- method: GET
  pattern: /api/insights/sessions/:id
  kind: read_detail
  stability: stable
  auth_policy: credential_if_configured
  response_contract: session insights envelope
- method: GET
  pattern: /api/webui/insights/:name
  kind: observability
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: Single WebUI insight descriptor projection
  notes: The daemon owns query construction and descriptor accessors; clients receive a bounded panel only.
- method: GET
  pattern: /api/raw_artifacts/:id
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: raw artifact preview
  notes: Authenticated raw preview helper for the local shell.
- method: GET
  pattern: /api/thread-continue-templates
  kind: read_detail
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: thread continuation templates
- method: GET
  pattern: /api/paste-browser
  kind: read_query
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: paste browser JSON
- method: GET
  pattern: /api/attachments
  kind: read_query
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: attachment library JSON
- method: GET
  pattern: /api/stack
  kind: workspace
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: stack workspace JSON
- method: GET
  pattern: /api/compare
  kind: workspace
  stability: shell_supported
  auth_policy: credential_if_configured
  response_contract: compare workspace JSON
- method: GET
  pattern: /api/user/marks
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: marks JSON
- method: GET
  pattern: /api/user/annotations
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: annotations JSON
- method: GET
  pattern: /api/user/annotations/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: annotation JSON
- method: GET
  pattern: /api/user/saved-views
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: saved views JSON
- method: GET
  pattern: /api/user/saved-views/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: saved view JSON
- method: GET
  pattern: /api/user/recall-packs
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: recall packs JSON
- method: GET
  pattern: /api/user/recall-packs/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: recall pack JSON
- method: GET
  pattern: /api/user/workspaces
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: workspaces JSON
- method: GET
  pattern: /api/user/workspaces/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_if_configured
  response_contract: workspace JSON
- method: GET
  pattern: /api/maintenance/operations
  kind: maintenance
  stability: stable
  auth_policy: credential_if_configured
  response_contract: maintenance operations JSON
- method: GET
  pattern: /api/maintenance/status/:id
  kind: maintenance
  stability: stable
  auth_policy: credential_if_configured
  response_contract: maintenance operation status JSON
- method: POST
  pattern: /api/telemetry/mcp-calls
  kind: operational
  stability: private
  auth_policy: bearer_if_configured_and_same_origin
  response_contract: MCP call-log receipt
  notes: Machine-client telemetry; persisted by the daemon writer with bounded retention.
- method: POST
  pattern: /api/reset
  kind: maintenance
  stability: stable
  auth_policy: bearer_if_configured_and_same_origin
  response_contract: reset result JSON
- method: POST
  pattern: /api/ingest
  kind: maintenance
  stability: stable
  auth_policy: bearer_if_configured_and_same_origin
  response_contract: ingest result JSON
- method: POST
  pattern: /api/maintenance/plan
  kind: maintenance
  stability: stable
  auth_policy: bearer_if_configured_and_same_origin
  response_contract: maintenance operation preview
- method: POST
  pattern: /api/maintenance/run
  kind: maintenance
  stability: stable
  auth_policy: bearer_if_configured_and_same_origin
  response_contract: maintenance operation result
- method: POST
  pattern: /api/user/marks
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: POST
  pattern: /api/user/annotations
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: POST
  pattern: /api/user/saved-views
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: POST
  pattern: /api/user/recall-packs
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: POST
  pattern: /api/user/workspaces
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: DELETE
  pattern: /api/user/marks
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: DELETE
  pattern: /api/user/annotations/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: DELETE
  pattern: /api/user/saved-views/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: DELETE
  pattern: /api/user/recall-packs/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
- method: DELETE
  pattern: /api/user/workspaces/:id
  kind: user_overlay
  stability: stable
  auth_policy: credential_and_same_origin
  response_contract: mutation envelope
x-polylogue-query-ast:
  schema_version: polylogue.query-explain-ast.v1
  schema: '#/components/schemas/QueryExpressionExplanationAst'
  description: Canonical, versioned projection of the query DSL's compiled predicate tree, unit-source pipeline, and lowering
    plan. Every query DSL expression -- fielded compact queries, ``sessions where ...`` Boolean expressions, terminal unit
    sources (``actions where ...``), and durable-reference pipelines (``from result-set:... | ...``) -- lowers to this one
    documented shape. Obtain it via the MCP ``explain`` operation (``kind="query"``) or ``Polylogue.explain_query_expression(expression)``;
    there is no separate HTTP route yet (tracked as a future extension of this schema's live surface).