> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niadra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pedir um caso de replay

> Um turno com o que o executor precisa para rodá-lo de novo dentro da sua empresa, depois que a build em execução confere os pinos.



## OpenAPI

````yaml openapi/pt/cell.json POST /v1/replay/cases
openapi: 3.1.0
info:
  title: API de dados da Niadra
  version: '1'
  description: >-
    Escrita, contexto, histórico, objetos, identidade, privacidade e governança
    de um espaço. Cada espaço tem um endereço estável, com o espaço e a região
    no nome.
servers:
  - url: https://{space}.{region}.api.niadra.com
    variables:
      space:
        default: acme-prod
        description: O espaço, que vem na chave de fonte.
      region:
        default: us-east-2
        description: A região do espaço, que também vem na chave.
security: []
paths:
  /v1/replay/cases:
    post:
      tags:
        - turns
      summary: Pedir um caso de replay
      description: >-
        Um turno com o que um executor precisa para rodá-lo de novo, depois que
        a build em execução confere os pinos dele.


        **Autenticação.** Chave de fonte com o escopo `replay`, ou token de
        pessoa do Console com o papel `integration`, `security` (ou admin). Só
        responde num espaço com a funcionalidade `turns` ligada (o documento
        `features`); num espaço sem ela, 404.
      operationId: replay_case_v1_replay_cases_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplayCaseRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReplayCase'
          description: Resposta de sucesso.
        '410':
          description: '`replay_expired`: o turno do cenário saiu do armazenamento.'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - sourceKey: []
        - personToken: []
      x-codeSamples:
        - lang: python
          label: Python
          source: >-
            from niadra.replay import Replayer


            # Runs each turn of the scenario 5 times inside your CI; tools
            answer from the record

            run = Replayer(niadra, build_agent, build=BUILD).run(["sc_01J9..."],
            runs=5)

            if run.regressed:
                raise SystemExit(1)
        - lang: typescript
          label: TypeScript
          source: >-
            import { Replayer } from "@niadra/sdk";


            // Runs each turn of the scenario 5 times inside your CI; tools
            answer from the record

            const run = await new Replayer(niadra, buildAgent, { build: BUILD
            }).run(["sc_01J9..."], { runs: 5 });

            if (run.verdict === "regression") process.exit(1);
components:
  schemas:
    ReplayCaseRequest:
      additionalProperties: false
      description: >-
        Um caso para um turno, sozinho ou como parte de um cenário. `build` é a
        build que o executor vai rodar; todo pino que a gravação exige precisa
        bater com o gravado, menos os pinos em `vary`, que a execução muda de
        propósito.
      properties:
        build:
          $ref: '#/components/schemas/TurnBuild'
        mode:
          default: hermetic_turn
          enum:
            - hermetic_turn
            - hermetic_conversation
            - era_memory
          title: Mode
          type: string
        scenario_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Scenario Id
        turn_id:
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
          title: Turn Id
          type: string
        vary:
          items:
            enum:
              - prompts
              - corpus_digest
              - model
              - assembler
              - tool_schemas
            type: string
          maxItems: 5
          title: Vary
          type: array
      required:
        - turn_id
        - build
      title: ReplayCaseRequest
      type: object
    ReplayCase:
      additionalProperties: false
      description: >-
        O que o executor de replay precisa para rodar um turno de novo dentro da
        empresa: o registro, com os valores guardados no modo `stored` e os
        ponteiros e digests nos demais; os pinos; o histórico mascarado da
        conversa até o turno, terminando na própria entrada dele; e as
        asserções. O contexto da época é o blob da leitura `pack` do registro.
      properties:
        assertions:
          items:
            $ref: '#/components/schemas/ReplayAssertion'
          title: Assertions
          type: array
        case_id:
          maxLength: 512
          minLength: 1
          title: Case Id
          type: string
        expires_at:
          description: Quando o turno sai do armazenamento; depois disso, `replay_expired`.
          format: date-time
          title: Expires At
          type: string
        history:
          items:
            $ref: '#/components/schemas/ReplayHistoryEntry'
          title: History
          type: array
        input:
          $ref: '#/components/schemas/ReplayInput'
        mode:
          enum:
            - hermetic_turn
            - hermetic_conversation
            - era_memory
          title: Mode
          type: string
        record:
          $ref: '#/components/schemas/TurnRecord'
        required_pins:
          items:
            enum:
              - prompts
              - corpus_digest
              - model
              - assembler
              - tool_schemas
            type: string
          title: Required Pins
          type: array
        scenario_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Scenario Id
        turn_id:
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
          title: Turn Id
          type: string
        vary:
          items:
            enum:
              - prompts
              - corpus_digest
              - model
              - assembler
              - tool_schemas
            type: string
          title: Vary
          type: array
      required:
        - case_id
        - turn_id
        - mode
        - record
        - required_pins
        - input
        - expires_at
      title: ReplayCase
      type: object
    Problem:
      additionalProperties: false
      description: >-
        Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de
        erros versionado.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    TurnBuild:
      additionalProperties: false
      properties:
        adapter:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: O adaptador de framework e a versão dele, se houver.
          title: Adapter
        pins:
          $ref: '#/components/schemas/TurnPins'
        sdk:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: Por exemplo `niadra-python/0.7.0`.
          title: Sdk
      title: TurnBuild
      type: object
    ReplayAssertion:
      additionalProperties: false
      description: >-
        Uma conferência estrutural sobre o registro do turno reproduzido,
        avaliada pelo executor. A especificação de replay fixa os `args` de cada
        tipo e como ele é avaliado; um tipo que o executor não consegue avaliar
        dá `not_checked`.
      properties:
        args:
          additionalProperties: true
          maxProperties: 20
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Args
          type: object
        id:
          pattern: ^[a-z0-9][a-z0-9_.-]{0,63}$
          title: Id
          type: string
        kind:
          enum:
            - tool_called
            - tool_not_called
            - hard_respected
            - no_denial_with_results
            - claims_traced
            - claims_match_state
            - no_promise_without_action
            - expected_in_topk
            - handoff_when
            - effect_once
            - budget
            - lexicon
            - tools_offered_match
          title: Kind
          type: string
        suggested:
          default: false
          description: Sugerida por regra a partir do turno gravado.
          title: Suggested
          type: boolean
        turn_id:
          anyOf:
            - pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
              type: string
            - type: 'null'
          description: O único turno do cenário a que ela se aplica; todos quando ausente.
          title: Turn Id
      required:
        - id
        - kind
      title: ReplayAssertion
      type: object
    ReplayHistoryEntry:
      additionalProperties: false
      properties:
        at:
          format: date-time
          title: At
          type: string
        role:
          enum:
            - customer
            - agent
            - human
          title: Role
          type: string
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
      required:
        - role
        - at
      title: ReplayHistoryEntry
      type: object
    ReplayInput:
      additionalProperties: false
      properties:
        kind:
          enum:
            - message
            - action
            - event
            - timer
          title: Kind
          type: string
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: A mensagem do cliente que abriu o turno, mascarada.
          title: Text
      required:
        - kind
      title: ReplayInput
      type: object
    TurnRecord:
      additionalProperties: false
      description: >-
        Um turno, da entrada dele (uma mensagem, uma ação de interface, um
        evento, um temporizador disparado) até a última coisa que emitiu ao
        cliente ou a um documento.
      properties:
        agent:
          $ref: '#/components/schemas/TurnAgent'
        blobs:
          maxProperties: 1000
          patternProperties:
            ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$:
              $ref: '#/components/schemas/TurnBlob'
          propertyNames:
            description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
          title: Blobs
          type: object
        build:
          $ref: '#/components/schemas/TurnBuild'
        calls:
          items:
            $ref: '#/components/schemas/TurnCall'
          maxItems: 500
          title: Calls
          type: array
        claims:
          items:
            $ref: '#/components/schemas/ClaimRecord'
          maxItems: 500
          title: Claims
          type: array
        completeness:
          default: complete
          enum:
            - complete
            - partial
            - incomplete
            - unknown
          title: Completeness
          type: string
        content_mode:
          enum:
            - stored
            - pointer
            - hash_only
          title: Content Mode
          type: string
        conversation_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Conversation Id
        coordination:
          items:
            $ref: '#/components/schemas/TurnCoordination'
          maxItems: 50
          title: Coordination
          type: array
        cost:
          anyOf:
            - $ref: '#/components/schemas/TurnCost'
            - type: 'null'
        effects:
          items:
            $ref: '#/components/schemas/TurnEffect'
          maxItems: 50
          title: Effects
          type: array
        ended_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Ended At
        fidelity:
          default: gold
          enum:
            - bronze
            - silver
            - gold
          title: Fidelity
          type: string
        flags:
          items:
            enum:
              - error
              - guard_acted
              - guard_budget_exceeded
              - handoff
              - assertion_failed
              - synthetic
              - incomplete
              - negative_feedback
              - truncated
            type: string
          maxItems: 20
          title: Flags
          type: array
        interactions:
          items:
            discriminator:
              mapping:
                attribute:
                  $ref: '#/components/schemas/Attribute'
                engaged:
                  $ref: '#/components/schemas/Engaged'
                feedback:
                  $ref: '#/components/schemas/Feedback'
                preference:
                  $ref: '#/components/schemas/Preference'
                presented:
                  $ref: '#/components/schemas/Presented'
                seen:
                  $ref: '#/components/schemas/Seen'
                unwatch:
                  $ref: '#/components/schemas/Unwatch'
                watch:
                  $ref: '#/components/schemas/Watch'
              propertyName: kind
            oneOf:
              - $ref: '#/components/schemas/Presented'
              - $ref: '#/components/schemas/Seen'
              - $ref: '#/components/schemas/Engaged'
              - $ref: '#/components/schemas/Feedback'
              - $ref: '#/components/schemas/Preference'
              - $ref: '#/components/schemas/Attribute'
              - $ref: '#/components/schemas/Watch'
              - $ref: '#/components/schemas/Unwatch'
          maxItems: 200
          title: Interactions
          type: array
        kind:
          default: message
          enum:
            - message
            - action
            - event
            - timer
          title: Kind
          type: string
        latency_ms:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Latency Ms
        output:
          $ref: '#/components/schemas/TurnOutput'
        reads:
          items:
            $ref: '#/components/schemas/TurnRead'
          maxItems: 20
          title: Reads
          type: array
        spec:
          const: turn-record.v0
          default: turn-record.v0
          title: Spec
          type: string
        started_at:
          format: date-time
          title: Started At
          type: string
        task_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Task Id
        turn_id:
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
          title: Turn Id
          type: string
      required:
        - turn_id
        - agent
        - started_at
        - content_mode
      title: TurnRecord
      type: object
    TurnPins:
      additionalProperties: false
      description: >-
        O que precisa ser igual para um replay reproduzir este turno. O
        documento de gravação diz quais são exigidos; um turno sem um deles é
        guardado, marcado como não reproduzível.
      properties:
        assembler:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: A versão do montador de contexto da própria empresa.
          title: Assembler
        corpus_digest:
          anyOf:
            - pattern: ^sha256:[0-9a-f]{64}$
              type: string
            - type: 'null'
          description: >-
            Digest dos arquivos que o agente consulta, calculado no SDK; nunca
            os arquivos.
          title: Corpus Digest
        model:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: O modelo exato que o agente chamou.
          title: Model
        niadra:
          anyOf:
            - $ref: '#/components/schemas/TurnCompilerPins'
            - type: 'null'
        prompts:
          additionalProperties:
            maxLength: 128
            minLength: 1
            type: string
          description: Nome do prompt -> versão, por exemplo `core` -> `v16`.
          maxProperties: 50
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Prompts
          type: object
        tool_schemas:
          additionalProperties:
            pattern: ^sha256:[0-9a-f]{64}$
            type: string
          description: Nome da ferramenta -> hash do esquema dela.
          maxProperties: 200
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Tool Schemas
          type: object
      title: TurnPins
      type: object
    TurnAgent:
      additionalProperties: false
      properties:
        name:
          description: O nome do agente dentro da fonte, como `closing`.
          maxLength: 256
          minLength: 1
          title: Name
          type: string
        parent_turn_id:
          anyOf:
            - pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
              type: string
            - type: 'null'
          description: >-
            O turno que abriu este como subturno (um subagente, um agente como
            ferramenta).
          title: Parent Turn Id
        role:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: Texto livre, como `specialist` ou `router`.
          title: Role
      required:
        - name
      title: TurnAgent
      type: object
    TurnCall:
      additionalProperties: false
      description: >-
        Uma chamada de ferramenta ou de modelo do turno, copiada por inteiro no
        momento em que aconteceu.
      properties:
        applied:
          anyOf:
            - $ref: '#/components/schemas/TurnConstraints'
            - type: 'null'
        args:
          anyOf:
            - description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
              pattern: ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$
              type: string
            - type: 'null'
          title: Args
        args_hash:
          anyOf:
            - pattern: ^sha256:[0-9a-f]{64}$
              type: string
            - type: 'null'
          description: Dos argumentos normalizados.
          title: Args Hash
        attempt:
          default: 1
          minimum: 1
          title: Attempt
          type: integer
        cache_hit:
          default: false
          title: Cache Hit
          type: boolean
        call_id:
          maxLength: 256
          minLength: 1
          title: Call Id
          type: string
        cost_units:
          additionalProperties:
            type: integer
          maxProperties: 20
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Cost Units
          type: object
        effect_key:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Effect Key
        kind:
          enum:
            - tool
            - model
          title: Kind
          type: string
        latency_ms:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          title: Latency Ms
        name:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: O nome da ferramenta, ou o do modelo numa chamada de modelo.
          title: Name
        observations:
          items:
            $ref: '#/components/schemas/TurnObservation'
          maxItems: 200
          title: Observations
          type: array
        parent_call_id:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Parent Call Id
        result_model:
          anyOf:
            - description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
              pattern: ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$
              type: string
            - type: 'null'
          description: O resultado como o modelo o viu.
          title: Result Model
        result_ui:
          anyOf:
            - description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
              pattern: ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$
              type: string
            - type: 'null'
          description: O resultado como a interface o recebeu.
          title: Result Ui
        status:
          default: ok
          enum:
            - ok
            - error
            - timeout
            - cancelled
          title: Status
          type: string
        synthetic:
          default: false
          title: Synthetic
          type: boolean
        tokens:
          anyOf:
            - $ref: '#/components/schemas/TurnTokens'
            - type: 'null'
        truncated:
          default: false
          description: Argumentos ou resultado chegaram cortados (OpenTelemetry).
          title: Truncated
          type: boolean
      required:
        - call_id
        - kind
      title: TurnCall
      type: object
    ClaimRecord:
      additionalProperties: false
      description: >-
        Uma afirmação que o SDK achou numa saída, como o registro do turno a
        leva: tipos, trechos e vereditos.
      properties:
        action:
          description: >-
            O que foi feito, decidido pela ação configurada no contrato:
            `rewrite_if_unequivocal` vira `rewrite` quando a reescrita é
            inequívoca e `warn` nos demais casos, `discard_anchor_and_count`
            vira `discard_anchor`, e uma afirmação que se sustenta (`matched`,
            `quoted_found`, `anchored`) é `none`.
          enum:
            - none
            - block
            - warn
            - count
            - rewrite
            - discard_anchor
          title: Action
          type: string
        category:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Category
          type: string
        class:
          anyOf:
            - enum:
                - money
                - percent
                - date
                - duration
                - quantity
                - count
                - dosage
              type: string
            - type: 'null'
          title: Class
        evidence:
          anyOf:
            - $ref: '#/components/schemas/ClaimEvidenceRef'
            - type: 'null'
        nature:
          anyOf:
            - enum:
                - computed
                - quoted
                - model
              type: string
            - type: 'null'
          title: Nature
        role:
          anyOf:
            - pattern: ^[a-z][a-z0-9_]{0,39}$
              type: string
            - type: 'null'
          title: Role
        span:
          description: Posições da afirmação na saída, em pontos de código, fim exclusivo.
          maxItems: 2
          minItems: 2
          prefixItems:
            - type: integer
            - type: integer
          title: Span
          type: array
        value:
          anyOf:
            - $ref: '#/components/schemas/ClaimValue'
            - type: 'null'
        verdict:
          enum:
            - matched
            - mismatch
            - stale
            - gap_not_stated
            - role_ambiguous
            - unsupported
            - no_evidence
            - quoted_found
            - quoted_missing
            - anchored
            - below_threshold
            - source_exists_claim_unverified
            - source_missing
            - not_checked
            - internal_text_found
          title: Verdict
          type: string
      required:
        - category
        - span
        - verdict
        - action
      title: ClaimRecord
      type: object
    TurnCoordination:
      additionalProperties: false
      properties:
        decision:
          enum:
            - allow
            - defer
            - deny
            - handoff_to
          title: Decision
          type: string
        decision_id:
          maxLength: 512
          minLength: 1
          title: Decision Id
          type: string
      required:
        - decision_id
        - decision
      title: TurnCoordination
      type: object
    TurnCost:
      additionalProperties: false
      properties:
        usd:
          minimum: 0
          title: Usd
          type: number
      required:
        - usd
      title: TurnCost
      type: object
    TurnEffect:
      additionalProperties: false
      properties:
        key:
          maxLength: 512
          minLength: 1
          title: Key
          type: string
        state:
          enum:
            - reserved
            - done
            - failed
            - unknown_outcome
          title: State
          type: string
      required:
        - key
        - state
      title: TurnEffect
      type: object
    Attribute:
      additionalProperties: false
      description: >-
        O que a pessoa é: um tamanho, uma rede preferida, uma dieta. Dito aqui;
        os desfechos do ciclo de vida (comprou, ficou, devolveu por tamanho)
        derivam o resto no servidor, nunca um agente.
      properties:
        category:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Category
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        kind:
          const: attribute
          title: Kind
          type: string
        name:
          pattern: ^[a-z][a-z0-9_]{0,63}(?:\.[a-z0-9_]{1,64}){0,3}$
          title: Name
          type: string
        source:
          default: stated
          enum:
            - stated
            - correction
          title: Source
          type: string
        system:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: 'O sistema de medida: `BR`, `EU`, `US`.'
          title: System
        value:
          anyOf:
            - type: boolean
            - type: integer
            - type: number
            - maxLength: 256
              type: string
          title: Value
      required:
        - kind
        - name
        - value
      title: Attribute
      type: object
    Engaged:
      additionalProperties: false
      properties:
        exposure_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Ausente num item de nenhuma lista.
          title: Exposure Id
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        how:
          enum:
            - click
            - detail
            - mention
            - add_to_cart
            - compare
            - share
            - other
          title: How
          type: string
        kind:
          const: engaged
          title: Kind
          type: string
        ref:
          pattern: ^[a-z][a-z0-9_]{0,39}:[^:\s]{1,256}:\S{1,512}$
          title: Ref
          type: string
      required:
        - kind
        - ref
        - how
      title: Engaged
      type: object
    Feedback:
      additionalProperties: false
      properties:
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        kind:
          const: feedback
          title: Kind
          type: string
        polarity:
          enum:
            - positive
            - negative
          title: Polarity
          type: string
        reason_attrs:
          items:
            pattern: ^[a-z][a-z0-9_]{0,39}\.[a-z][a-z0-9_]{0,63}$
            type: string
          maxItems: 10
          title: Reason Attrs
          type: array
        ref:
          pattern: ^[a-z][a-z0-9_]{0,39}:[^:\s]{1,256}:\S{1,512}$
          title: Ref
          type: string
      required:
        - kind
        - ref
        - polarity
      title: Feedback
      type: object
    Preference:
      additionalProperties: false
      description: >-
        O que a pessoa quer ou recusa, dito ou capturado dos argumentos de uma
        ferramenta; só isso vira restrição rígida.
      properties:
        attr:
          pattern: ^[a-z][a-z0-9_]{0,39}\.[a-z][a-z0-9_]{0,63}$
          title: Attr
          type: string
        category:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: Vale só nesta categoria do tipo.
          title: Category
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Expires At
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        kind:
          const: preference
          title: Kind
          type: string
        op:
          enum:
            - in
            - not_in
            - eq
            - ne
            - lt
            - lte
            - gt
            - gte
            - between
          title: Op
          type: string
        scope:
          default: session
          enum:
            - turn
            - session
            - persistent
          title: Scope
          type: string
        source:
          default: stated
          enum:
            - stated
            - tool_args
            - correction
          title: Source
          type: string
        strength:
          enum:
            - must
            - must_not
            - prefer
            - avoid
          title: Strength
          type: string
        values:
          items:
            anyOf:
              - type: boolean
              - type: integer
              - type: number
              - maxLength: 256
                type: string
          maxItems: 50
          minItems: 1
          title: Values
          type: array
      required:
        - kind
        - attr
        - op
        - values
        - strength
      title: Preference
      type: object
    Presented:
      additionalProperties: false
      description: >-
        Uma lista entregue à pessoa: a exposição. O momento canônico dela é
        `delivered_at`, quando a ponte da interface entregou a lista ao cliente,
        nunca quando uma ferramenta a devolveu ou o modelo a nomeou.
      properties:
        delivered_at:
          format: date-time
          title: Delivered At
          type: string
        exposure_id:
          format: uuid
          title: Exposure Id
          type: string
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        items:
          items:
            $ref: '#/components/schemas/PresentedItem'
          maxItems: 100
          minItems: 1
          title: Items
          type: array
        kind:
          const: presented
          title: Kind
          type: string
        list_id:
          maxLength: 256
          minLength: 1
          title: List Id
          type: string
        list_kind:
          default: results
          maxLength: 256
          minLength: 1
          title: List Kind
          type: string
        method:
          default: bridge
          description: >-
            `bridge` pela ponte da interface, `otel` por um span
            `niadra.exposure`, `tool_result` inferido do que uma ferramenta
            devolveu: rotulado, porque conta mais do que foi mostrado.
          enum:
            - bridge
            - otel
            - tool_result
          title: Method
          type: string
        offset:
          default: 0
          maximum: 10000
          minimum: 0
          title: Offset
          type: integer
        page:
          default: 1
          description: '"Ver mais" é a mesma lista com `page + 1`.'
          maximum: 1000
          minimum: 1
          title: Page
          type: integer
        parent_list_id:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Parent List Id
        visible_k:
          anyOf:
            - maximum: 100
              minimum: 1
              type: integer
            - type: 'null'
          description: Quantos dos primeiros itens estavam visíveis na entrega.
          title: Visible K
      required:
        - kind
        - exposure_id
        - list_id
        - items
        - delivered_at
      title: Presented
      type: object
    Seen:
      additionalProperties: false
      description: 'Um aviso do componente de lista: até onde a pessoa viu.'
      properties:
        exposure_id:
          format: uuid
          title: Exposure Id
          type: string
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        kind:
          const: seen
          title: Kind
          type: string
        max_index_seen:
          description: A maior `pos` que o componente mostrou.
          maximum: 10000
          minimum: 1
          title: Max Index Seen
          type: integer
      required:
        - kind
        - exposure_id
        - max_index_seen
      title: Seen
      type: object
    Unwatch:
      additionalProperties: false
      properties:
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        kind:
          const: unwatch
          title: Kind
          type: string
        ref:
          pattern: ^[a-z][a-z0-9_]{0,39}:[^:\s]{1,256}:\S{1,512}$
          title: Ref
          type: string
      required:
        - kind
        - ref
      title: Unwatch
      type: object
    Watch:
      additionalProperties: false
      description: >-
        Um "me avise quando" explícito: o único jeito de um interesse gerar um
        aviso.
      properties:
        condition:
          description: Uma expressão `niadra-expr` sobre os campos do objeto.
          maxLength: 500
          minLength: 1
          title: Condition
          type: string
        consent_event_key:
          maxLength: 512
          minLength: 1
          title: Consent Event Key
          type: string
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Expires At
        for:
          default: self
          pattern: ^(?:self|gift|beneficiary:[A-Za-z0-9_-]{1,64})$
          title: For
          type: string
        kind:
          const: watch
          title: Kind
          type: string
        ref:
          pattern: ^[a-z][a-z0-9_]{0,39}:[^:\s]{1,256}:\S{1,512}$
          title: Ref
          type: string
      required:
        - kind
        - ref
        - condition
        - consent_event_key
      title: Watch
      type: object
    TurnOutput:
      additionalProperties: false
      properties:
        document:
          anyOf:
            - description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
              pattern: ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$
              type: string
            - type: 'null'
          description: Um documento que o turno escreveu, pelo blob dele.
          title: Document
        event_keys:
          description: >-
            Os eventos que `track()` enviou com o que o turno disse: o texto
            nunca é repetido aqui.
          items:
            maxLength: 512
            minLength: 1
            type: string
          maxItems: 50
          title: Event Keys
          type: array
        handoff_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Handoff Id
        ui:
          anyOf:
            - description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
              pattern: ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$
              type: string
            - type: 'null'
          title: Ui
      title: TurnOutput
      type: object
    TurnRead:
      additionalProperties: false
      description: >-
        Uma leitura que o turno fez da Niadra, pela versão: o contexto pelo
        ETag, um bloco pela versão dele.
      properties:
        blob:
          anyOf:
            - description: A blob of this record, by its key in `blobs`, e.g. `b:1`.
              pattern: ^[a-z]{1,8}:[A-Za-z0-9_-]{1,32}$
              type: string
            - type: 'null'
          description: O conteúdo lido, quando a gravação o guarda.
          title: Blob
        etag:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          title: Etag
        receipt_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Receipt Id
        surface:
          enum:
            - pack
            - state
            - constraints
            - coordination
            - budget
            - history
            - agent_memory
            - agent_state
          title: Surface
          type: string
        version:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          title: Version
      required:
        - surface
      title: TurnRead
      type: object
    TurnCompilerPins:
      additionalProperties: false
      properties:
        compiler:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: A versão do compilador de contexto, do contexto lido.
          title: Compiler
        pack_hash:
          anyOf:
            - maxLength: 128
              minLength: 1
              type: string
            - type: 'null'
          description: O hash do contexto que este turno leu.
          title: Pack Hash
      title: TurnCompilerPins
      type: object
    TurnConstraints:
      additionalProperties: false
      description: >-
        O que o SDK mediu do bloco de restrições numa chamada de ferramenta:
        enviado, conferido, violado.
      properties:
        constraints:
          description: A versão do bloco de restrições aplicado.
          maxLength: 128
          minLength: 1
          title: Constraints
          type: string
        hard_sent:
          items:
            maxLength: 256
            minLength: 1
            type: string
          maxItems: 200
          title: Hard Sent
          type: array
        relaxed:
          anyOf:
            - enum:
                - declared
                - suspected
              type: string
            - type: 'null'
          title: Relaxed
        results_checked:
          minimum: 0
          title: Results Checked
          type: integer
        unverifiable:
          minimum: 0
          title: Unverifiable
          type: integer
        violations:
          minimum: 0
          title: Violations
          type: integer
      required:
        - constraints
        - results_checked
        - violations
        - unverifiable
      title: TurnConstraints
      type: object
    TurnObservation:
      additionalProperties: false
      description: >-
        Estado que o resultado de uma ferramenta mostrou, com proveniência por
        campo; sem proveniência é só para exibição.
      properties:
        fields:
          additionalProperties: true
          maxProperties: 200
          propertyNames:
            maxLength: 256
            minLength: 1
          title: Fields
          type: object
        provenance:
          anyOf:
            - $ref: '#/components/schemas/TurnProvenance'
            - type: 'null'
        ref:
          description: >-
            Um objeto como `<type>:<namespace>:<id>`, por exemplo
            `item_variant:store:991`.
          pattern: ^[a-z][a-z0-9_]{0,39}:[^:\s]{1,256}:\S{1,512}$
          title: Ref
          type: string
      required:
        - ref
        - fields
      title: TurnObservation
      type: object
    TurnTokens:
      additionalProperties: false
      properties:
        cached:
          default: 0
          minimum: 0
          title: Cached
          type: integer
        in:
          minimum: 0
          title: In
          type: integer
        out:
          minimum: 0
          title: Out
          type: integer
      required:
        - in
        - out
      title: TurnTokens
      type: object
    ClaimEvidenceRef:
      additionalProperties: false
      description: >-
        Onde está a evidência de uma afirmação no registro do turno: o campo de
        uma chamada, o campo de um objeto ou um documento.
      properties:
        anchor:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          description: O blob que guarda o texto citado.
          title: Anchor
        call_id:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          title: Call Id
        document:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          description: O documento que uma âncora cita.
          title: Document
        field:
          anyOf:
            - pattern: ^[a-z][a-z0-9_]{0,39}$
              type: string
            - type: 'null'
          title: Field
        ref:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          description: Um objeto, `type:namespace:id`.
          title: Ref
        score:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          description: A similaridade da âncora.
          title: Score
      title: ClaimEvidenceRef
      type: object
    ClaimValue:
      additionalProperties: false
      description: >-
        Um número lido pelo analisador, normalizado: uma quantia, ou uma faixa
        de `min` a `max`, com a unidade (o código da moeda, `%`, uma unidade de
        tempo, de medida ou de dose), ou uma data, ou uma faixa de datas.
      properties:
        amount:
          anyOf:
            - pattern: ^-?(?:0|[1-9][0-9]{0,17})(?:\.[0-9]{1,6})?$
              type: string
            - type: 'null'
          title: Amount
        date:
          anyOf:
            - pattern: >-
                ^(?:[0-9]{4}-[0-9]{2}(?:-[0-9]{2})?|--[0-9]{2}-[0-9]{2}|---[0-9]{2})$
              type: string
            - type: 'null'
          title: Date
        date_from:
          anyOf:
            - pattern: >-
                ^(?:[0-9]{4}-[0-9]{2}(?:-[0-9]{2})?|--[0-9]{2}-[0-9]{2}|---[0-9]{2})$
              type: string
            - type: 'null'
          title: Date From
        date_to:
          anyOf:
            - pattern: >-
                ^(?:[0-9]{4}-[0-9]{2}(?:-[0-9]{2})?|--[0-9]{2}-[0-9]{2}|---[0-9]{2})$
              type: string
            - type: 'null'
          title: Date To
        max:
          anyOf:
            - pattern: ^-?(?:0|[1-9][0-9]{0,17})(?:\.[0-9]{1,6})?$
              type: string
            - type: 'null'
          title: Max
        min:
          anyOf:
            - pattern: ^-?(?:0|[1-9][0-9]{0,17})(?:\.[0-9]{1,6})?$
              type: string
            - type: 'null'
          title: Min
        unit:
          anyOf:
            - maxLength: 16
              minLength: 1
              type: string
            - type: 'null'
          title: Unit
      title: ClaimValue
      type: object
    PresentedItem:
      additionalProperties: false
      properties:
        pos:
          description: Posição a partir de 1 na lista inteira, através das páginas.
          maximum: 10000
          minimum: 1
          title: Pos
          type: integer
        ref:
          pattern: ^[a-z][a-z0-9_]{0,39}:[^:\s]{1,256}:\S{1,512}$
          title: Ref
          type: string
        shown:
          description: >-
            Os valores que o item mostrou, nos campos que o tipo dele acompanha
            ou deixa afirmar; é contra eles que `changes_since_seen` compara
            depois.
          maxProperties: 32
          patternProperties:
            ^[a-z][a-z0-9_]{0,63}$:
              anyOf:
                - type: boolean
                - type: integer
                - type: number
                - maxLength: 256
                  type: string
                - type: 'null'
          title: Shown
          type: object
        team:
          anyOf:
            - enum:
                - a
                - b
              type: string
            - type: 'null'
          description: Qual das duas listas intercaladas contribuiu o item.
          title: Team
      required:
        - pos
        - ref
      title: PresentedItem
      type: object
    TurnProvenance:
      additionalProperties: false
      properties:
        scope:
          default: global
          enum:
            - global
            - customer
            - context
          title: Scope
          type: string
        source:
          enum:
            - live
            - snapshot
            - cache
          title: Source
          type: string
        source_observed_at:
          format: date-time
          title: Source Observed At
          type: string
      required:
        - source
        - source_observed_at
      title: TurnProvenance
      type: object
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...
    personToken:
      type: http
      scheme: bearer
      bearerFormat: JWT

````