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

# replace_file

> Replace a file's content atomically. Cost class: **job**.

The replacement is atomic from a reader's perspective: the old version is
stamped ``replaced_at`` and the new version is live in the same commit.

Re-ingests only if the file was ingested before (``ingestion_status``
becomes ``stale``); a never-ingested file returns to ``discovered``.
The actual cascade (retiring outputs, queuing re-ingestion) is the
``dispatch`` seam in the job service.



## OpenAPI

````yaml /openapi.json put /v1/workspaces/{workspace_id}/files/{file_id}
openapi: 3.1.0
info:
  description: >-
    Document intelligence: parse, split, classify, extract, and ground files, or
    build a searchable workspace. Authenticate with ``X-API-Key``.
  title: NDI Platform API
  version: 0.1.0
servers:
  - url: https://ndi-api.nace.ai
security: []
tags: []
paths:
  /v1/workspaces/{workspace_id}/files/{file_id}:
    put:
      tags:
        - files
      summary: replace_file
      description: >-
        Replace a file's content atomically. Cost class: **job**.


        The replacement is atomic from a reader's perspective: the old version
        is

        stamped ``replaced_at`` and the new version is live in the same commit.


        Re-ingests only if the file was ingested before (``ingestion_status``

        becomes ``stale``); a never-ingested file returns to ``discovered``.

        The actual cascade (retiring outputs, queuing re-ingestion) is the

        ``dispatch`` seam in the job service.
      operationId: replace_file_v1_workspaces__workspace_id__files__file_id__put
      parameters:
        - in: path
          name: file_id
          required: true
          schema:
            format: uuid
            title: File Id
            type: string
        - description: Workspace identifier.
          in: path
          name: workspace_id
          required: true
          schema:
            description: Workspace identifier.
            format: uuid
            title: Workspace Id
            type: string
        - description: >-
            Bounded inline wait. 0 (the default) returns 202 immediately. Above
            0 the route returns 200 with a terminal job if the work finished in
            time, and 202 with the still-running job if it did not. Either way,
            read `status`.
          in: query
          name: wait_seconds
          required: false
          schema:
            default: 0
            description: >-
              Bounded inline wait. 0 (the default) returns 202 immediately.
              Above 0 the route returns 200 with a terminal job if the work
              finished in time, and 202 with the still-running job if it did
              not. Either way, read `status`.
            maximum: 300
            minimum: 0
            title: Wait Seconds
            type: integer
        - description: >-
            Replaying a request with the same key returns the original job with
            200, never a second job.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - maxLength: 200
                type: string
              - type: 'null'
            description: >-
              Replaying a request with the same key returns the original job
              with 200, never a second job.
            title: Idempotency-Key
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_replace_file_v1_workspaces__workspace_id__files__file_id__put
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
          description: Successful Response
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: Gateway Timeout
        default:
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  detail: null
                  message: >-
                    Request body has extra fields that this operation does not
                    accept.
                  request_id: req-01j9k2n3p4q5r6s7t8v9
                  retryable: false
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          description: >-
            Typed error envelope used by every 4xx and 5xx. ``error.code``
            distinguishes the failure; HTTP status is a consequence of the code.
      security:
        - APIKeyHeader: []
components:
  schemas:
    Body_replace_file_v1_workspaces__workspace_id__files__file_id__put:
      properties:
        file:
          anyOf:
            - contentMediaType: application/octet-stream
              type: string
            - type: 'null'
          title: File
        metadata:
          anyOf:
            - type: string
            - type: 'null'
          description: JSON-encoded ReplaceFileRequest. Required for multipart uploads.
          title: Metadata
      title: Body_replace_file_v1_workspaces__workspace_id__files__file_id__put
      type: object
    Job:
      additionalProperties: false
      description: >-
        Every slow method returns one of these (spec 12 §1.4).


        There is no ``/parse`` + ``/parse_async`` pair: every job-creating route

        returns ``202`` with a queued job and accepts ``?wait_seconds=``,
        returning

        ``200`` with a terminal job if the work finished inside the window. The

        caller's code path is the same either way — read ``status``.
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        deleted_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When the caller hid this run from listings, via `delete_job`. A soft
            delete: the job still reads by id and still counts toward `GET
            /v1/usage` — what it stops doing is appearing in `GET /v1/jobs`.
          title: Deleted At
        effort:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Which implementation ran this job, for the one kind whose request
            carries an effort (intelligent_search): 'fast' is fact-search,
            'deep' (or the legacy 'balanced') is deep-search and the console's
            QA chat — a deep-search run under another surface, not a fourth
            implementation, so this field cannot tell those two apart. Null for
            every other kind. Read from the stored request, so it rides the same
            retention path as `query` and `result`: null once `result_state`
            leaves `available`.
          title: Effort
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
          description: Present only on failed.
        finished_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Finished At
        force:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            The request's own `force` flag, echoed regardless of outcome.
            Present for kinds whose request carries one (e.g. kg_build, where a
            true value cleared the durable store before the job ran) so a caller
            can tell that apart from a build that failed leaving the prior store
            untouched — `result` alone cannot, since it is absent on failure
            either way.
          title: Force
        idempotency_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Idempotency Key
        job_id:
          format: uuid
          title: Job Id
          type: string
        kind:
          $ref: '#/components/schemas/JobKind'
        name:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Caller-chosen display name (the console's 'project'). Mutable via
            PATCH /v1/jobs/{job_id}.
          title: Name
        payload_expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Payload Expires At
        progress:
          anyOf:
            - $ref: '#/components/schemas/JobProgress'
            - type: 'null'
          description: Absent until running.
        project_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            Caller-minted grouping id shared by jobs submitted together.
            Filterable on GET /v1/jobs.
          title: Project Id
        query:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The question this job was asked, for the search kinds that carry one
            (intelligent_search, qa_file, qa_tables, filtered_search); null for
            every other kind. Read from the stored request, so it rides the same
            retention path as `result`: null once `result_state` leaves
            `available`. Narrow by design — the frozen access context never
            reaches the wire. File scope is summarised separately as
            `query_scope`.
          title: Query
        query_scope:
          anyOf:
            - discriminator:
                mapping:
                  file:
                    $ref: '#/components/schemas/FileQueryScope'
                  files:
                    $ref: '#/components/schemas/FilesQueryScope'
                  path_prefix:
                    $ref: '#/components/schemas/PathPrefixQueryScope'
                  workspace:
                    $ref: '#/components/schemas/WorkspaceQueryScope'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/WorkspaceQueryScope'
                - $ref: '#/components/schemas/FileQueryScope'
                - $ref: '#/components/schemas/PathPrefixQueryScope'
                - $ref: '#/components/schemas/FilesQueryScope'
            - type: 'null'
          description: >-
            Where this search ran, summarised for history UIs: the whole
            workspace, one file path, one folder prefix, or a count of files.
            Null for non-query jobs, filtered-search page continuations, and
            once `result_state` leaves `available`. Never lists multiple
            filenames, never the raw request, and never the frozen API-key id.
          title: Query Scope
        result:
          anyOf:
            - discriminator:
                mapping:
                  categorize:
                    $ref: >-
                      #/components/schemas/ndi_service__app__platform_api__results__CategorizeResult
                  classify:
                    $ref: '#/components/schemas/ClassifyResult'
                  deep_search_v2:
                    $ref: '#/components/schemas/DeepSearchV2Result'
                  extract:
                    $ref: >-
                      #/components/schemas/ndi_service__app__platform_api__results__ExtractResult
                  file_delete:
                    $ref: '#/components/schemas/DeleteFileResult'
                  file_replace:
                    $ref: '#/components/schemas/ReplaceFileResult'
                  file_upload:
                    $ref: '#/components/schemas/UploadFileResult'
                  filtered_search:
                    $ref: '#/components/schemas/FilteredSearchResult'
                  ground:
                    $ref: >-
                      #/components/schemas/ndi_service__app__platform_api__results__GroundResult
                  ingestion:
                    $ref: '#/components/schemas/IngestionResult'
                  intelligent_search:
                    $ref: '#/components/schemas/IntelligentSearchResult'
                  je_testing:
                    $ref: '#/components/schemas/JetResult'
                  kg_build:
                    $ref: '#/components/schemas/KnowledgeGraphBuildResult'
                  parse:
                    $ref: >-
                      #/components/schemas/ndi_service__app__platform_api__results__ParseResult
                  qa_file:
                    $ref: '#/components/schemas/QaFileResult'
                  qa_tables:
                    $ref: '#/components/schemas/QaTablesResult'
                  reconciliation:
                    $ref: '#/components/schemas/ReconciliationResult'
                  split:
                    $ref: '#/components/schemas/SplitResult'
                  workspace_delete:
                    $ref: '#/components/schemas/WorkspaceDeleteResult'
                propertyName: result_type
              oneOf:
                - $ref: >-
                    #/components/schemas/ndi_service__app__platform_api__results__ParseResult
                - $ref: '#/components/schemas/SplitResult'
                - $ref: '#/components/schemas/ClassifyResult'
                - $ref: >-
                    #/components/schemas/ndi_service__app__platform_api__results__CategorizeResult
                - $ref: >-
                    #/components/schemas/ndi_service__app__platform_api__results__ExtractResult
                - $ref: >-
                    #/components/schemas/ndi_service__app__platform_api__results__GroundResult
                - $ref: '#/components/schemas/IngestionResult'
                - $ref: '#/components/schemas/ReconciliationResult'
                - $ref: '#/components/schemas/KnowledgeGraphBuildResult'
                - $ref: '#/components/schemas/UploadFileResult'
                - $ref: '#/components/schemas/ReplaceFileResult'
                - $ref: '#/components/schemas/DeleteFileResult'
                - $ref: '#/components/schemas/WorkspaceDeleteResult'
                - $ref: '#/components/schemas/IntelligentSearchResult'
                - $ref: '#/components/schemas/QaFileResult'
                - $ref: '#/components/schemas/QaTablesResult'
                - $ref: '#/components/schemas/FilteredSearchResult'
                - $ref: '#/components/schemas/JetResult'
                - $ref: '#/components/schemas/DeepSearchV2Result'
            - type: 'null'
          description: Present only on succeeded, and only while retained.
          title: Result
        result_state:
          $ref: '#/components/schemas/ResultState'
          default: available
        source:
          anyOf:
            - discriminator:
                mapping:
                  parse_result:
                    $ref: '#/components/schemas/ParseResultSource'
                  upload:
                    $ref: '#/components/schemas/UploadSource'
                  url:
                    $ref: '#/components/schemas/UrlSource'
                  workspace_file:
                    $ref: '#/components/schemas/WorkspaceFileSource'
                propertyName: type
              oneOf:
                - $ref: '#/components/schemas/UploadSource'
                - $ref: '#/components/schemas/UrlSource'
                - $ref: '#/components/schemas/WorkspaceFileSource'
                - $ref: '#/components/schemas/ParseResultSource'
            - type: 'null'
          description: >-
            What this job read, for the document operations that take a single
            `source` (parse, split, classify, extract, ground); null for every
            other kind. Together with `workspace_id` this is what lets a caller
            re-open the document a past run was about — a `workspace_file`
            source stays readable after the run, while an `upload` is single-use
            and its bytes are gone. Read from the stored request, so it rides
            the same retention path as `query` and `result`: null once
            `result_state` leaves `available`.
          title: Source
        started_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Started At
        status:
          $ref: >-
            #/components/schemas/ndi_service__app__platform_api__contracts__JobStatus
        units:
          default: 0
          title: Units
          type: integer
        workspace_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The workspace this job reads. Null for a document operation whose
            source is an upload, a URL, or a prior parse result.
          title: Workspace Id
      required:
        - job_id
        - kind
        - status
        - created_at
      title: Job
      type: object
    ErrorEnvelope:
      description: Every non-2xx body on ``/v1``.
      example:
        error:
          code: invalid_request
          detail: null
          message: Request body has extra fields that this operation does not accept.
          request_id: req-01j9k2n3p4q5r6s7t8v9
          retryable: false
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      title: ErrorEnvelope
      type: object
    Error:
      description: The error object, per spec 12 §1.8.
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: Structured payload, when the code carries one.
          title: Detail
        message:
          description: Human- and model-readable; says what to do differently.
          title: Message
          type: string
        request_id:
          description: Per-request correlation id; matches the ``X-Request-Id`` header.
          title: Request Id
          type: string
        retryable:
          description: Whether retrying the identical request could succeed.
          title: Retryable
          type: boolean
      required:
        - code
        - message
        - retryable
        - request_id
      title: Error
      type: object
    JobKind:
      description: What a job is doing. Open enum — a new member is additive.
      enum:
        - parse
        - split
        - classify
        - categorize
        - extract
        - ground
        - ingestion
        - reconciliation
        - kg_build
        - file_upload
        - file_replace
        - upload_session_complete
        - file_delete
        - workspace_delete
        - intelligent_search
        - qa_file
        - qa_tables
        - filtered_search
        - je_testing
        - deep_search_v2
      title: JobKind
      type: string
    JobProgress:
      additionalProperties: false
      description: Absent until the job is ``running``.
      properties:
        items_done:
          default: 0
          title: Items Done
          type: integer
        items_failed:
          default: 0
          description: >-
            Quarantined after exhausting retries, for batch kinds. Excluded from
            items_done.
          title: Items Failed
          type: integer
        items_total:
          anyOf:
            - type: integer
            - type: 'null'
          description: Files, for batch kinds.
          title: Items Total
        stage:
          anyOf:
            - type: string
            - type: 'null'
          description: Current pipeline stage, for display only.
          title: Stage
        units_done:
          default: 0
          title: Units Done
          type: integer
        units_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Units Total
      title: JobProgress
      type: object
    FileQueryScope:
      additionalProperties: false
      description: The question ran against one workspace-relative file.
      properties:
        path:
          maxLength: 1024
          minLength: 1
          title: Path
          type: string
        type:
          const: file
          default: file
          title: Type
          type: string
      required:
        - path
      title: FileQueryScope
      type: object
    FilesQueryScope:
      additionalProperties: false
      description: The question ran against several files; only the count is public.
      properties:
        count:
          minimum: 2
          title: Count
          type: integer
        type:
          const: files
          default: files
          title: Type
          type: string
      required:
        - count
      title: FilesQueryScope
      type: object
    PathPrefixQueryScope:
      additionalProperties: false
      description: The question ran against one folder subtree.
      properties:
        prefix:
          maxLength: 1024
          minLength: 1
          title: Prefix
          type: string
        type:
          const: path_prefix
          default: path_prefix
          title: Type
          type: string
      required:
        - prefix
      title: PathPrefixQueryScope
      type: object
    WorkspaceQueryScope:
      additionalProperties: false
      description: The question ran against the whole workspace.
      properties:
        type:
          const: workspace
          default: workspace
          title: Type
          type: string
      title: WorkspaceQueryScope
      type: object
    ndi_service__app__platform_api__results__CategorizeResult:
      additionalProperties: false
      properties:
        assignments:
          items:
            $ref: '#/components/schemas/CategoryAssignment'
          title: Assignments
          type: array
        result_type:
          const: categorize
          default: categorize
          title: Result Type
          type: string
        units:
          title: Units
          type: integer
      required:
        - assignments
        - units
      title: CategorizeResult
      type: object
    ClassifyResult:
      additionalProperties: false
      properties:
        result_type:
          const: classify
          default: classify
          title: Result Type
          type: string
        units:
          items:
            $ref: '#/components/schemas/ClassifyUnit'
          title: Units
          type: array
      required:
        - units
      title: ClassifyResult
      type: object
    DeepSearchV2Result:
      additionalProperties: false
      description: >-
        The result of one source-level deep-search run
        (``JobKind.DEEP_SEARCH_V2``).


        Field-for-field the JET shape — answer, reasoning, evidences, the run's

        ``sql_receipts``, the tool-call trace, session handle, usage, exhaustion
        —

        under its own discriminator: the two kinds share one agent chassis and
        one

        fold, and a second field list here would only be a place for them to
        drift.

        On this surface a receipt's ``rows`` are the statement's bounded
        preview;

        the full result is retained server-side and re-queryable through the

        ``res_…`` handle appearing in any statement that pages it.
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The direct, grounded answer to the request. Null only on a run that
            exhausted its budget before authoring one.
          title: Answer
        binding:
          anyOf:
            - $ref: '#/components/schemas/LedgerBindingWire'
            - type: 'null'
          description: >-
            The definitional layer the run committed and computed under — which
            column is the period, which values mean posted, which clock a timing
            test was verbed on. Null on a run that answered without binding a
            ledger, which is only possible before any statement ran.
        confidence:
          anyOf:
            - $ref: '#/components/schemas/ConfidenceLevel'
            - type: 'null'
          description: >-
            The agent's self-graded confidence in the answer — how well the
            evidence and executed statements support it, on the shared six-level
            scale (certain / very_high / high / medium / low / speculative).
            Null on exhausted runs and on results stored before the field
            existed.
        degraded:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Why this result is degraded, when it is. The run broke before it
            could finalize an answer but had already computed real working, so
            what is published is that working — `sql_receipts` and `binding` —
            with `figures` empty and `answer` saying so. Null on every run that
            finished normally, exhausted ones included.
          title: Degraded
        discrepancies:
          description: >-
            Where the data contradicted the request's premise or a figure it
            stated. Empty when nothing did — the run is asked for this
            explicitly, so an empty list is an answer rather than an omission.
          items:
            type: string
          title: Discrepancies
          type: array
        evidences:
          description: >-
            The material the answer cites, each resolved to the caller's own
            uploaded file.
          items:
            $ref: '#/components/schemas/SearchEvidence'
          title: Evidences
          type: array
        exhausted:
          default: false
          description: >-
            Step budget hit before the run was satisfied. A successful response,
            not a failure.
          title: Exhausted
          type: boolean
        figures:
          description: >-
            One entry per criterion tested, each linked to the receipts its
            figures are readable out of. Empty on a run that answered without
            testing anything, or that exhausted its budget first.
          items:
            $ref: '#/components/schemas/JetFigure'
          title: Figures
          type: array
        population_statement:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The population every figure was computed over — file, period, layer,
            status, basis, grain — in the run's own words. Null only on a run
            that never authored an answer.
          title: Population Statement
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          description: How the receipted statements chain together into the answer.
          title: Reasoning
        result_type:
          const: deep_search_v2
          default: deep_search_v2
          title: Result Type
          type: string
        session_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The conversation this run belongs to. Send it back as the request's
            `session_id` to ask a follow-up in the same thread.
          title: Session Id
        sql_receipts:
          description: >-
            Every statement the run executed, in execution order — the answer's
            working.
          items:
            $ref: '#/components/schemas/SqlReceipt'
          title: Sql Receipts
          type: array
        steps_used:
          default: 0
          title: Steps Used
          type: integer
        tool_calls:
          items:
            $ref: '#/components/schemas/ToolCallTrace'
          title: Tool Calls
          type: array
        usage:
          anyOf:
            - $ref: '#/components/schemas/SearchLlmUsage'
            - type: 'null'
          description: >-
            What this run spent on LLM calls. Present only when the request
            asked for it; null means nothing was measured, not that nothing was
            spent.
      title: DeepSearchV2Result
      type: object
    ndi_service__app__platform_api__results__ExtractResult:
      additionalProperties: false
      properties:
        data:
          additionalProperties: true
          title: Data
          type: object
        fields:
          items:
            $ref: '#/components/schemas/ExtractedField'
          title: Fields
          type: array
        result_type:
          const: extract
          default: extract
          title: Result Type
          type: string
        schema_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Schema Id
        schema_version:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          title: Schema Version
        units:
          title: Units
          type: integer
        warnings:
          description: >-
            Non-fatal notes about the request, e.g. instructions no schema field
            can satisfy.
          items:
            type: string
          title: Warnings
          type: array
      required:
        - fields
        - units
      title: ExtractResult
      type: object
    DeleteFileResult:
      additionalProperties: false
      description: Counts exist so the cascade is auditable rather than assumed.
      properties:
        file_id:
          format: uuid
          title: File Id
          type: string
        index_documents_deleted:
          default: 0
          title: Index Documents Deleted
          type: integer
        jobs_cancelled:
          items:
            format: uuid
            type: string
          title: Jobs Cancelled
          type: array
        kg_edges_deleted:
          default: 0
          title: Kg Edges Deleted
          type: integer
        kg_nodes_deleted:
          default: 0
          title: Kg Nodes Deleted
          type: integer
        outputs_deleted:
          default: 0
          title: Outputs Deleted
          type: integer
        result_type:
          const: file_delete
          default: file_delete
          title: Result Type
          type: string
        verified:
          description: False is a failed cascade and must alert.
          title: Verified
          type: boolean
      required:
        - file_id
        - verified
      title: DeleteFileResult
      type: object
    ReplaceFileResult:
      additionalProperties: false
      properties:
        file:
          $ref: '#/components/schemas/File'
        previous_version:
          title: Previous Version
          type: integer
        result_type:
          const: file_replace
          default: file_replace
          title: Result Type
          type: string
      required:
        - file
        - previous_version
      title: ReplaceFileResult
      type: object
    UploadFileResult:
      additionalProperties: false
      description: |-
        Also the result of ``JobKind.UPLOAD_SESSION_COMPLETE``.

        A chunked upload's completion produces exactly this shape — the file it
        landed, and whether it deduplicated — so it deliberately reuses this
        result rather than minting a near-identical discriminated variant whose
        ``result_type`` would just be a second name for the same two fields.
      properties:
        deduplicated:
          description: Identical bytes were already present.
          title: Deduplicated
          type: boolean
        file:
          $ref: '#/components/schemas/File'
        result_type:
          const: file_upload
          default: file_upload
          title: Result Type
          type: string
      required:
        - file
        - deduplicated
      title: UploadFileResult
      type: object
    FilteredSearchResult:
      additionalProperties: false
      description: >-
        The typed outcome of one filtered-search execution (or one page of it).


        ``exhaustive`` is the coarse completeness signal: when it is false,
        returned

        matches are valid, but "all"-style claims, ``total_matches`` as a
        census,

        and zero-match conclusions are not guaranteed. It is scope-wide and

        all-or-nothing, so it cannot say *what* was incomplete;

        ``field_readability`` is its per-field companion, naming the filtered

        fields the extraction could not fully read — the difference between "no

        component matched" and "the column you filtered on was largely
        unreadable".

        Pagination is LIVE — each page re-executes against the current catalog,
        so

        concurrent ingestion, deletion, or relabeling may shift later pages
        (rows

        can repeat or be skipped across page boundaries); ``catalog_drifted``
        says

        the scope changed since the query was first validated.
      properties:
        applied_query:
          anyOf:
            - type: string
            - type: 'null'
          description: Server-rendered display form of the published query.
          title: Applied Query
        candidates_seen:
          default: 0
          title: Candidates Seen
          type: integer
        catalog_drifted:
          default: false
          description: The catalog changed since the query was validated.
          title: Catalog Drifted
          type: boolean
        clarification:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Non-null exactly when the run asked a clarifying question instead of
            executing — only possible when the initial query set
            `allow_clarification`: no rows, no applied_query, no interpretation,
            exhaustive false. Filtered search keeps no session; answer it by
            issuing a new initial query.
          title: Clarification
        columns:
          items:
            $ref: '#/components/schemas/CatalogColumnDescriptor'
          title: Columns
          type: array
        confidence:
          anyOf:
            - $ref: '#/components/schemas/ConfidenceLevel'
            - type: 'null'
          description: >-
            The agent's self-graded confidence in the published result — how
            well the catalog evidence supports its interpretation of the
            request, on the shared six-level scale (certain / very_high / high /
            medium / low / speculative). Null on runs rejected with a
            `clarification`, on page requests, and on results stored before the
            field existed.
        content_evidences:
          description: >-
            Residual content condition passages, server-verified; present only
            on residual queries.
          items:
            $ref: '#/components/schemas/ContentEvidence'
          title: Content Evidences
          type: array
        coverage:
          $ref: '#/components/schemas/Coverage'
        evidences:
          description: >-
            Referent-resolution evidence: the file passages that turned a role
            or relative referent in the query ('the CEO') into the concrete
            filter value the published query uses. Agent-cited, then resolved
            server-side to the caller's own uploaded file exactly like search
            evidence — an entry that cannot be resolved to a visible file is
            dropped, never published. Distinct from content_evidences, which are
            server-verified residual matches. Empty on pure catalog queries.
          items:
            $ref: '#/components/schemas/SearchEvidence'
          title: Evidences
          type: array
        executed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When this page's snapshot was read.
          title: Executed At
        exhausted:
          default: false
          description: Step budget hit before the agent finished. A success, not a failure.
          title: Exhausted
          type: boolean
        exhaustive:
          default: false
          description: >-
            True only when every eligible component was completely cataloged and
            evaluated — the scope-wide completeness signal. False whenever
            coverage is partial or a residual content condition was applied.
          title: Exhaustive
          type: boolean
        field_readability:
          description: >-
            Filtered fields the extraction could not fully read,
            server-computed. An empty list is an answer — every field the query
            filtered on was fully readable — rather than an omission.
          items:
            $ref: '#/components/schemas/FieldReadability'
          title: Field Readability
          type: array
        interpretation:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The agent's reading of the request — assumptions, thresholds, any
            common-currency assumption.
          title: Interpretation
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Opaque cursor for the next page — POST it back as {type: 'page',
            cursor}. Null on the last page.
          title: Next Cursor
        result_type:
          const: filtered_search
          default: filtered_search
          title: Result Type
          type: string
        rows:
          items:
            $ref: '#/components/schemas/FilteredSearchRow'
          title: Rows
          type: array
        steps_used:
          default: 0
          title: Steps Used
          type: integer
        tool_calls:
          items:
            $ref: '#/components/schemas/ToolCallTrace'
          title: Tool Calls
          type: array
        total_matches:
          default: 0
          description: >-
            Qualifying components of the full result, before any page or top-N
            cut.
          title: Total Matches
          type: integer
        truncated:
          default: false
          description: A structural cap degraded this result; matches shown remain valid.
          title: Truncated
          type: boolean
      title: FilteredSearchResult
      type: object
    ndi_service__app__platform_api__results__GroundResult:
      additionalProperties: false
      properties:
        result_type:
          const: ground
          default: ground
          title: Result Type
          type: string
        targets:
          items:
            $ref: '#/components/schemas/GroundTargetResult'
          title: Targets
          type: array
        transcript_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Storage URL of the MediaTimeline JSON used for grounding.
          title: Transcript Url
        units:
          title: Units
          type: integer
      required:
        - targets
        - units
      title: GroundResult
      type: object
    IngestionResult:
      additionalProperties: false
      properties:
        files_failed:
          title: Files Failed
          type: integer
        files_ingested:
          title: Files Ingested
          type: integer
        files_skipped:
          title: Files Skipped
          type: integer
        kg_build_job_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The knowledge-graph build this ingestion chained, when the workspace
            auto-builds. Poll it to know when the graph covers these files; null
            means no build was chained (auto-build off, or a pending build
            already covers them).
          title: Kg Build Job Id
        outcomes:
          items:
            $ref: '#/components/schemas/IngestedFileOutcome'
          title: Outcomes
          type: array
        result_type:
          const: ingestion
          default: ingestion
          title: Result Type
          type: string
        units_total:
          title: Units Total
          type: integer
      required:
        - outcomes
        - files_ingested
        - files_skipped
        - files_failed
        - units_total
      title: IngestionResult
      type: object
    IntelligentSearchResult:
      additionalProperties: false
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A direct answer to the query, grounded in the evidences. Always
            present on a newly finalized run that answered; null when the run
            rejected the query with a `clarification`, and on results stored
            before answers became unconditional (the evidence-only mode).
          title: Answer
        candidates_seen:
          default: 0
          title: Candidates Seen
          type: integer
        clarification:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Non-null exactly when the run rejected the query as genuinely
            ambiguous instead of answering — only possible when the request set
            `allow_clarification`: one direct question back to the caller, with
            `answer`, `interpretation` and `reasoning` null and `evidences`
            empty. Answer it by re-asking in the same thread via the result's
            `session_id`.
          title: Clarification
        confidence:
          anyOf:
            - $ref: '#/components/schemas/ConfidenceLevel'
            - type: 'null'
          description: >-
            The agent's self-graded confidence in the answer — how well the
            evidence it retrieved supports it, on the shared six-level scale
            (certain / very_high / high / medium / low / speculative). Null on
            runs rejected with a `clarification` and on results stored before
            the field existed.
        coverage:
          $ref: '#/components/schemas/Coverage'
        evidences:
          description: The evidence the agent found for the query, in order of importance.
          items:
            $ref: '#/components/schemas/SearchEvidence'
          title: Evidences
          type: array
        exhausted:
          default: false
          description: >-
            Budget hit before the loop was satisfied. A successful response, not
            a failure. When the agent authored no answer or reasoning, reasoning
            carries an actionable briefing and answer stays null so presentation
            does not treat the briefing as an answer.
          title: Exhausted
          type: boolean
        interpretation:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The agent's reading of the query — its assumptions, how it resolved
            ambiguous terms, the period or scope it took as implied. Stated on
            every answered run, even one that took the query at face value; null
            on runs rejected with a `clarification` and on results stored before
            the field existed.
          title: Interpretation
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The agent's account of how the pieces of evidence chain together to
            address the query. The agent's reading of the query itself —
            assumptions, resolved ambiguities, implied period or scope — is
            stated in `interpretation`, not here.
          title: Reasoning
        result_type:
          const: intelligent_search
          default: intelligent_search
          title: Result Type
          type: string
        session_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The conversation this run belongs to. Send it back as the request's
            `session_id` to ask a follow-up in the same thread. Null only on
            results finalized before sessions existed.
          title: Session Id
        steps_used:
          default: 0
          title: Steps Used
          type: integer
        tool_calls:
          items:
            $ref: '#/components/schemas/ToolCallTrace'
          title: Tool Calls
          type: array
        usage:
          anyOf:
            - $ref: '#/components/schemas/SearchLlmUsage'
            - type: 'null'
          description: >-
            What this run spent on LLM calls. Present only when the request
            asked for it; null means nothing was measured, not that nothing was
            spent.
      title: IntelligentSearchResult
      type: object
    JetResult:
      additionalProperties: false
      description: >-
        The result of one journal-entry-testing run (``JobKind.JE_TESTING``).


        Shape-compatible with :class:`IntelligentSearchResult` for the retrieval

        core — evidences, reasoning, answer, the tool-call trace, the session

        handle, usage and exhaustion all mean exactly what they mean there —
        plus

        ``sql_receipts``: the statements behind the answer.


        ``figures`` is the answer's checkable half: one entry per criterion,
        each

        naming the receipts its figures are readable out of. There is no
        ``coverage``

        block — v1 runs on tables the caller selected, and an honest coverage
        number

        needs an orientation pass that reports what was *not* selected.
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The direct, grounded answer to the request. Null only on a run that
            exhausted its budget before authoring one.
          title: Answer
        binding:
          anyOf:
            - $ref: '#/components/schemas/LedgerBindingWire'
            - type: 'null'
          description: >-
            The definitional layer the run committed and computed under — which
            column is the period, which values mean posted, which clock a timing
            test was verbed on. Null on a run that answered without binding a
            ledger, which is only possible before any statement ran.
        confidence:
          anyOf:
            - $ref: '#/components/schemas/ConfidenceLevel'
            - type: 'null'
          description: >-
            The agent's self-graded confidence in the answer — how well the
            evidence and executed statements support it, on the shared six-level
            scale (certain / very_high / high / medium / low / speculative).
            Null on exhausted runs and on results stored before the field
            existed.
        degraded:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Why this result is degraded, when it is. The run broke before it
            could finalize an answer but had already computed real working, so
            what is published is that working — `sql_receipts` and `binding` —
            with `figures` empty and `answer` saying so. Null on every run that
            finished normally, exhausted ones included.
          title: Degraded
        discrepancies:
          description: >-
            Where the data contradicted the request's premise or a figure it
            stated. Empty when nothing did — the run is asked for this
            explicitly, so an empty list is an answer rather than an omission.
          items:
            type: string
          title: Discrepancies
          type: array
        evidences:
          description: >-
            The material the answer cites, each resolved to the caller's own
            uploaded file.
          items:
            $ref: '#/components/schemas/SearchEvidence'
          title: Evidences
          type: array
        exhausted:
          default: false
          description: >-
            Step budget hit before the run was satisfied. A successful response,
            not a failure.
          title: Exhausted
          type: boolean
        figures:
          description: >-
            One entry per criterion tested, each linked to the receipts its
            figures are readable out of. Empty on a run that answered without
            testing anything, or that exhausted its budget first.
          items:
            $ref: '#/components/schemas/JetFigure'
          title: Figures
          type: array
        population_statement:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The population every figure was computed over — file, period, layer,
            status, basis, grain — in the run's own words. Null only on a run
            that never authored an answer.
          title: Population Statement
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          description: How the receipted statements chain together into the answer.
          title: Reasoning
        result_type:
          const: je_testing
          default: je_testing
          title: Result Type
          type: string
        session_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The conversation this run belongs to. Send it back as the request's
            `session_id` to ask a follow-up in the same thread.
          title: Session Id
        sql_receipts:
          description: >-
            Every statement the run executed, in execution order — the answer's
            working.
          items:
            $ref: '#/components/schemas/SqlReceipt'
          title: Sql Receipts
          type: array
        steps_used:
          default: 0
          title: Steps Used
          type: integer
        tool_calls:
          items:
            $ref: '#/components/schemas/ToolCallTrace'
          title: Tool Calls
          type: array
        usage:
          anyOf:
            - $ref: '#/components/schemas/SearchLlmUsage'
            - type: 'null'
          description: >-
            What this run spent on LLM calls. Present only when the request
            asked for it; null means nothing was measured, not that nothing was
            spent.
      title: JetResult
      type: object
    KnowledgeGraphBuildResult:
      additionalProperties: false
      description: >-
        The corpus-level graph build: what one snapshot covered.


        The graph is a property of the whole corpus, not a per-file derivative,
        so

        this reports totals rather than per-file outcomes — with one exception:

        ``files_failed`` is per-file because a build now finishes without the
        files it

        could not process, and "which files is this graph blind to" is otherwise

        unanswerable from the outside. A file listed there is excluded from

        ``files_covered`` and stays marked as needing a rebuild.


        ``snapshot_id`` is the new graph's cache key — the same value
        ``kg_info``

        returns — so a caller can tell the build actually advanced the served
        graph.
      properties:
        edge_count:
          default: 0
          title: Edge Count
          type: integer
        files_covered:
          description: >-
            Source files whose ledger version matched the build-time corpus at
            finalize; files replaced during the build are excluded and will show
            as needing a rebuild.
          title: Files Covered
          type: integer
        files_failed:
          description: >-
            Files quarantined after exhausting their retries. Not in the graph,
            and not marked covered.
          items:
            $ref: '#/components/schemas/KnowledgeGraphFileFailure'
          title: Files Failed
          type: array
        node_count:
          default: 0
          title: Node Count
          type: integer
        rebuilt:
          default: false
          description: True when a force build cleared the prior store first.
          title: Rebuilt
          type: boolean
        result_type:
          const: kg_build
          default: kg_build
          title: Result Type
          type: string
        snapshot_id:
          title: Snapshot Id
          type: string
      required:
        - snapshot_id
        - files_covered
      title: KnowledgeGraphBuildResult
      type: object
    ndi_service__app__platform_api__results__ParseResult:
      additionalProperties: false
      properties:
        converted_pdf_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Converted Pdf Url
        document:
          $ref: '#/components/schemas/ParseDocument'
        file_name:
          title: File Name
          type: string
        lane:
          title: Lane
          type: string
        ocr_applied:
          title: Ocr Applied
          type: boolean
        result_type:
          const: parse
          default: parse
          title: Result Type
          type: string
        units:
          title: Units
          type: integer
      required:
        - file_name
        - lane
        - document
        - ocr_applied
        - units
      title: ParseResult
      type: object
    QaFileResult:
      additionalProperties: false
      description: >-
        One qa-file run, stored whole so the answer can be reopened.


        Every field past ``exhausted`` arrived with job-backed history; rows
        written

        before it carry only the two receipt fields and still validate, so
        nothing

        needs backfilling. A reopened run answers the same question over the
        same

        scope: ``scope_path`` and ``scope_component`` are what the caller asked

        about, not where the answer came from.
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          description: The prose the run returned. Null only on a pre-history row.
          title: Answer
        citations:
          items:
            $ref: '#/components/schemas/Evidence'
          title: Citations
          type: array
        confidence:
          anyOf:
            - $ref: '#/components/schemas/ConfidenceLevel'
            - type: 'null'
          description: The engine's self-graded confidence; None when it could not grade.
        engine:
          anyOf:
            - enum:
                - recursive_llm
                - vision
                - agent
              type: string
            - type: 'null'
          title: Engine
        exhausted:
          default: false
          description: >-
            The agent's step budget ran out before it completed an answer. A
            successful run, not a failure.
          title: Exhausted
          type: boolean
        result_type:
          const: qa_file
          default: qa_file
          title: Result Type
          type: string
        scope_component:
          anyOf:
            - type: string
            - type: 'null'
          description: The component (tab / section) the ask was narrowed to.
          title: Scope Component
        scope_path:
          anyOf:
            - type: string
            - type: 'null'
          description: The uploaded file the question was asked about.
          title: Scope Path
        steps_used:
          default: 0
          title: Steps Used
          type: integer
        timed_out:
          default: false
          description: >-
            A guard fired before the engine answered. The body holds the
            partial-answer wording, not a failure.
          title: Timed Out
          type: boolean
        unavailable:
          items:
            $ref: '#/components/schemas/UnavailableTable'
          title: Unavailable
          type: array
      title: QaFileResult
      type: object
    QaTablesResult:
      additionalProperties: false
      description: >-
        One query-tables run, stored whole so the answer can be reopened.


        As with :class:`QaFileResult`, everything past ``exhausted`` arrived
        with

        job-backed history and is optional, so receipt-only rows still validate.

        Both lanes land in this one shape: the SQL lane fills ``tables`` and

        ``result_files``, the agent lane fills ``answer`` and ``citations``
        only.
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          description: The prose the run returned. Null only on a pre-history row.
          title: Answer
        citations:
          items:
            $ref: '#/components/schemas/Evidence'
          title: Citations
          type: array
        confidence:
          anyOf:
            - $ref: '#/components/schemas/ConfidenceLevel'
            - type: 'null'
          description: The engine's self-graded confidence; None when it could not grade.
        error:
          anyOf:
            - type: string
            - type: 'null'
          description: The engine's own reported trouble on an otherwise 200 run.
          title: Error
        exhausted:
          default: false
          description: >-
            The agent's step budget ran out before it completed an answer. A
            successful run, not a failure.
          title: Exhausted
          type: boolean
        result_files:
          items:
            $ref: '#/components/schemas/QaTableResultFile'
          title: Result Files
          type: array
        result_materialization_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Result Materialization Error
        result_type:
          const: qa_tables
          default: qa_tables
          title: Result Type
          type: string
        source_components:
          description: The named tabs among those selections.
          items:
            type: string
          title: Source Components
          type: array
        source_paths:
          description: The table selections the question was asked over.
          items:
            type: string
          title: Source Paths
          type: array
        steps_used:
          default: 0
          title: Steps Used
          type: integer
        tables:
          items:
            $ref: '#/components/schemas/QueryTablePreview'
          title: Tables
          type: array
        timed_out:
          default: false
          title: Timed Out
          type: boolean
        unavailable:
          items:
            $ref: '#/components/schemas/UnavailableTable'
          title: Unavailable
          type: array
      title: QaTablesResult
      type: object
    ReconciliationResult:
      additionalProperties: false
      description: Reconciliation only ever *detects*; ingestion is what acts.
      properties:
        discovered:
          description: In storage, absent from the ledger.
          items:
            format: uuid
            type: string
          title: Discovered
          type: array
        files_scanned:
          title: Files Scanned
          type: integer
        ingestion_job_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Set when auto_ingest was requested.
          title: Ingestion Job Id
        marked_stale:
          description: observed_hash != ingested_hash.
          items:
            format: uuid
            type: string
          title: Marked Stale
          type: array
        orphans_removed:
          description: In the ledger, absent from storage.
          items:
            format: uuid
            type: string
          title: Orphans Removed
          type: array
        result_type:
          const: reconciliation
          default: reconciliation
          title: Result Type
          type: string
      required:
        - files_scanned
      title: ReconciliationResult
      type: object
    SplitResult:
      additionalProperties: false
      properties:
        file_name:
          title: File Name
          type: string
        lane:
          title: Lane
          type: string
        page_count:
          title: Page Count
          type: integer
        result_type:
          const: split
          default: split
          title: Result Type
          type: string
        segments:
          items:
            $ref: '#/components/schemas/SplitSegment'
          title: Segments
          type: array
        units:
          title: Units
          type: integer
      required:
        - file_name
        - lane
        - page_count
        - segments
        - units
      title: SplitResult
      type: object
    WorkspaceDeleteResult:
      additionalProperties: false
      description: 'Hard tenant deletion: storage prefix, indexes, and graph.'
      properties:
        files_deleted:
          default: 0
          title: Files Deleted
          type: integer
        index_documents_deleted:
          default: 0
          title: Index Documents Deleted
          type: integer
        kg_nodes_deleted:
          default: 0
          title: Kg Nodes Deleted
          type: integer
        prefix_deleted:
          default: false
          title: Prefix Deleted
          type: boolean
        result_type:
          const: workspace_delete
          default: workspace_delete
          title: Result Type
          type: string
        verified:
          default: false
          title: Verified
          type: boolean
        workspace_id:
          format: uuid
          title: Workspace Id
          type: string
      required:
        - workspace_id
      title: WorkspaceDeleteResult
      type: object
    ResultState:
      description: >-
        Why ``Job.result`` is null.


        ``available`` with a null result means the job has not succeeded yet;

        ``expired`` means retention dropped it; ``not_retained`` means the
        client is

        provisioned ``zero_retention`` and already had its one chance to read
        it.

        A late poll returns the job with a state, never a 404 — "this expired"
        and

        "this never existed" are a scheduling problem and a bug respectively,
        and a

        404 makes them identical.
      enum:
        - available
        - expired
        - not_retained
      title: ResultState
      type: string
    ParseResultSource:
      additionalProperties: false
      description: >-
        A prior Parse job whose parsed artifact can be reused by downstream
        methods.
      properties:
        job_id:
          format: uuid
          title: Job Id
          type: string
        type:
          const: parse_result
          default: parse_result
          title: Type
          type: string
      required:
        - job_id
      title: ParseResultSource
      type: object
    UploadSource:
      additionalProperties: false
      description: Bytes staged through ``POST /v1/uploads``. Single-use, TTL-bound.
      properties:
        type:
          const: upload
          default: upload
          title: Type
          type: string
        upload_id:
          format: uuid
          title: Upload Id
          type: string
      required:
        - upload_id
      title: UploadSource
      type: object
    UrlSource:
      additionalProperties: false
      description: A public or presigned HTTPS location we fetch server-side.
      properties:
        file_name:
          maxLength: 512
          title: File Name
          type: string
        type:
          const: url
          default: url
          title: Type
          type: string
        url:
          maxLength: 2048
          pattern: ^https://
          title: Url
          type: string
      required:
        - url
        - file_name
      title: UrlSource
      type: object
    WorkspaceFileSource:
      additionalProperties: false
      description: >-
        A file already in a workspace.


        The single seam between the two contexts: a granular operation may read
        a

        workspace file and still write nothing back. The file need **not** be

        ingested — granular operations read source bytes, not representations.
      properties:
        file_id:
          format: uuid
          title: File Id
          type: string
        type:
          const: workspace_file
          default: workspace_file
          title: Type
          type: string
        workspace_id:
          format: uuid
          title: Workspace Id
          type: string
      required:
        - workspace_id
        - file_id
      title: WorkspaceFileSource
      type: object
    ndi_service__app__platform_api__contracts__JobStatus:
      description: >-
        ``cancelled`` is a first-class terminal status, not a ``failed``
        variant.


        Conflating them makes error-rate metrics lie and forces every client to

        string-match an error code.
      enum:
        - queued
        - running
        - succeeded
        - failed
        - cancelled
      title: JobStatus
      type: string
    ErrorCode:
      description: |-
        Every error the ``/v1`` surface can return.

        Clients must treat this as an **open** enum: a new member is an additive
        change (spec 12 §9), and a client that crashes on an unknown code makes
        every future error a breaking change.
      enum:
        - invalid_request
        - unsupported_file_type
        - file_too_large
        - invalid_schema
        - invalid_sql
        - invalid_path_prefix
        - command_not_permitted
        - batch_too_large
        - domain_validation_failed
        - default_label_required
        - wait_required_for_zero_retention
        - workspace_not_found
        - file_not_found
        - job_not_found
        - upload_not_found
        - node_not_found
        - schema_not_found
        - domain_not_found
        - session_not_found
        - access_label_not_found
        - path_conflict
        - schema_version_conflict
        - access_label_name_taken
        - workspace_name_taken
        - access_label_in_use
        - upload_expired
        - file_not_ingested
        - workspace_deleting
        - workspace_not_deletable
        - ingestion_in_progress
        - job_not_cancellable
        - confirmation_required
        - domain_not_published
        - domain_in_use
        - reserved_domain_slug
        - kg_not_built
        - kg_build_in_progress
        - session_busy
        - range_not_satisfiable
        - result_expired
        - access_denied
        - access_backstop_violation
        - access_mode_not_implemented
        - rate_limited
        - concurrency_limit_reached
        - quota_exceeded
        - corrupt_file
        - zero_byte_file
        - encrypted_file
        - parse_failed
        - ocr_failed
        - conversion_failed
        - sheetless_workbook
        - unplayable_media
        - unclassified_pages
        - job_cancelled
        - job_timeout
        - upstream_unavailable
        - internal_error
        - unauthorized
        - not_implemented
      title: ErrorCode
      type: string
    CategoryAssignment:
      additionalProperties: false
      properties:
        alternatives:
          items:
            $ref: '#/components/schemas/ScoredCategory'
          title: Alternatives
          type: array
        category:
          anyOf:
            - type: string
            - type: 'null'
          description: Null when nothing cleared the threshold.
          title: Category
        confidence:
          title: Confidence
          type: number
        evidence:
          anyOf:
            - $ref: '#/components/schemas/Evidence'
            - type: 'null'
        file_name:
          title: File Name
          type: string
        source_index:
          description: Index into the request's sources list.
          title: Source Index
          type: integer
      required:
        - source_index
        - file_name
        - confidence
      title: CategoryAssignment
      type: object
    ClassifyUnit:
      additionalProperties: false
      properties:
        granularity:
          default: document
          enum:
            - document
            - page
          title: Granularity
          type: string
        labels:
          items:
            $ref: '#/components/schemas/ClassifyLabel'
          title: Labels
          type: array
        page_range:
          anyOf:
            - $ref: '#/components/schemas/ClassifyPageRange'
            - type: 'null'
        unknown:
          title: Unknown
          type: boolean
      required:
        - unknown
        - labels
      title: ClassifyUnit
      type: object
    LedgerBindingWire:
      additionalProperties: false
      description: >-
        The definitional layer a run committed, echoed for the caller to read.


        This is the answer to "on what definitions does this figure rest" — the

        question the prose relay of the old playbook could not answer, and the
        reason

        the binding is a validated artifact rather than a paragraph. Every pin
        was

        checked against the tables' own profiles before the run was allowed to

        compute anything: the columns exist with compatible types, the period
        roles

        partition the observed domain, each clock's declared grain matches its

        column, and every encoding value occurs in its column.


        Published as flat slot listings rather than as a mirror of the internal

        model's tree. Two reasons, both practical: a reader wants "which column
        is

        the approval clock" answered in one place rather than by walking a
        nested

        object, and a slot the design adds later becomes another row here
        instead of

        a change to this contract.
      properties:
        columns:
          description: Every column pinned to a slot, in slot order.
          items:
            $ref: '#/components/schemas/BoundColumn'
          title: Columns
          type: array
        notes:
          description: Deviations the run observed while orienting.
          items:
            type: string
          title: Notes
          type: array
        periods:
          description: The period domain, in period order, with roles.
          items:
            $ref: '#/components/schemas/BoundPeriod'
          title: Periods
          type: array
        policy_sheets:
          description: >-
            Documents the run treated as settling parameters (a sequence policy,
            a topside register).
          items:
            type: string
          title: Policy Sheets
          type: array
        revised_because:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Why the binding was replaced mid-run, when it was. Null on a run
            that bound once.
          title: Revised Because
        tables:
          items:
            $ref: '#/components/schemas/BoundTable'
          title: Tables
          type: array
        value_sets:
          description: >-
            Encoding candidates and layer memberships. More than one entry under
            'encodings.manual' means the run kept both readings and resolved
            them per test.
          items:
            $ref: '#/components/schemas/BoundValueSet'
          title: Value Sets
          type: array
      title: LedgerBindingWire
      type: object
    ConfidenceLevel:
      description: How well the retrieved evidence supports the answer, worst-case wins.
      enum:
        - certain
        - very_high
        - high
        - medium
        - low
        - speculative
      title: ConfidenceLevel
      type: string
    SearchEvidence:
      additionalProperties: false
      description: >-
        One piece of evidence the search agent cited, named as the caller's own
        file.


        The agent retrieves from workspace-internal ingestion derivatives, but
        those

        are an implementation detail the caller never addresses: every citation
        is

        resolved server-side, through the caller's access gate, to the uploaded
        file

        it belongs to (``source_path`` + ``source_file_id``). A citation that
        cannot be

        resolved to a visible file — hallucinated, deleted mid-run, or
        access-refused —

        is dropped rather than published under a path the caller cannot use.


        No locator: pinning a quote to a region of the original document is a

        separate ``ground`` call the caller makes on the file at ``source_path``

        (``source_file_id``) with ``quote`` as the target text — and, for a
        quote

        taken from a spreadsheet, ``component`` as the target's ``sheet``.
      properties:
        component:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Public component of the file the quote came from — the tab name for
            a spreadsheet, the section for a split document; the same vocabulary
            file-metadata lists. Pass it as the ground target's sheet when
            grounding a spreadsheet quote. None for a single-component file or
            when attribution was unavailable.
          title: Component
        derivation:
          anyOf:
            - $ref: '#/components/schemas/DerivationTrace'
            - type: 'null'
          description: >-
            Computation DAG for derived answers; None when the evidence is a
            direct extraction or the run recorded no dependency edges.
        page:
          anyOf:
            - type: integer
            - type: 'null'
          description: 1-based page number, when the agent saw one.
          title: Page
        queries:
          description: >-
            The SQL the run executed over this evidence's table, with a bounded
            preview of each result — server-recorded from the run's tables
            engine, never model-authored. Attached whenever the run queried the
            cited table (or the row extraction of the same spreadsheet tab), so
            a verbatim quote from a queried sheet carries the computation trail
            alongside it; empty when the run never queried the cited file's
            tables.
          items:
            $ref: '#/components/schemas/TableQueryGrounding'
          title: Queries
          type: array
        quote:
          description: The key passage, as retrieved from the file.
          title: Quote
          type: string
        relevance:
          description: The agent's one-sentence account of how this supports the query.
          title: Relevance
          type: string
        source_file_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The id of the file at source_path, resolved server-side. Always set
            on newly finalized results; null only on results stored before
            unresolvable citations were dropped.
          title: Source File Id
        source_path:
          description: >-
            The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'.
            This is the file to ground the quote against.
          title: Source Path
          type: string
      required:
        - source_path
        - quote
        - relevance
      title: SearchEvidence
      type: object
    JetFigure:
      additionalProperties: false
      description: >-
        One criterion the run tested, and the statements its figures come from.


        The answer's structure on the wire. ``JetResult.answer`` is prose a
        person

        reads; this is the same content a reviewer can *check*: the definition
        the

        figure was computed under, the population it was computed over, the spec
        that

        pinned both, and the ``sql_receipts`` entries the figures are readable
        out of.


        Every ``result_id`` here names a receipt on the same result, so a reader

        follows a figure to its statement and its rows without leaving the
        payload.

        ``exception_listing_result_id`` is the one worth opening: an unfiltered
        count

        grounds correctly but points at every row, while an exception listing
        points

        at the rows that failed.
      properties:
        band_group:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Set when this figure is one band of a family that partitions a
            population — the same name on every band of the family, whose counts
            sum to that population.
          title: Band Group
        breakdown:
          anyOf:
            - $ref: '#/components/schemas/JetBreakdown'
            - type: 'null'
          description: >-
            The tabular result behind this figure, attached by the server from
            the receipt it cites — the exception listing where there is one,
            otherwise the single cited statement that returned more than one
            row. Null when no cited statement holds a table, and on a criterion
            that could not be performed.
        cannot_be_performed:
          default: false
          description: >-
            The workspace does not hold the material this criterion needs.
            `result_ids` then name the probes that establish the absence rather
            than the figures.
          title: Cannot Be Performed
          type: boolean
        count:
          description: Members of the population that met the criterion.
          minimum: 0
          title: Count
          type: integer
        criterion:
          description: What was tested, in the caller's terms.
          title: Criterion
          type: string
        definition:
          description: >-
            The definition it was tested under: which column and values encoded
            the term, which clock, which basis, which threshold and where it
            came from.
          title: Definition
          type: string
        exception_listing_result_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The receipt that lists the exceptions themselves, when one was
            produced.
          title: Exception Listing Result Id
        population:
          description: >-
            The denominator — rows at this test's grain that the criterion ran
            over.
          minimum: 0
          title: Population
          type: integer
        result_ids:
          description: >-
            `sql_receipts[].result_id` of every statement this figure is
            readable out of.
          items:
            type: string
          title: Result Ids
          type: array
        spec_id:
          description: The run's committed TestSpec this figure was computed under.
          title: Spec Id
          type: string
        value:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The exceptions' value as text, so a decimal survives the wire. Null
            for a count-only criterion.
          title: Value
      required:
        - criterion
        - definition
        - spec_id
        - population
        - count
      title: JetFigure
      type: object
    SqlReceipt:
      additionalProperties: false
      description: >-
        One SQL statement a journal-entry-testing run executed, with its result.


        The audit trail of a JET answer: every headline figure is meant to be

        readable out of one of these. Unlike

        :class:`TableQueryGrounding` — whose SQL is written by a sub-agent and

        published as supporting detail — the statement here is the deliverable's

        own working, so it is published whole rather than digested.


        ``rows`` is bounded (``JET_RECEIPT_MAX_ROWS``) and ``truncated`` says

        whether the bound cut anything, so an "every exception is listed"
        reading

        is never made from a silently capped table. ``result_row_count`` is the

        figure that reading actually needs: the statement's whole result is
        stored,

        and this is its size, whatever the bound carried below.
      properties:
        columns:
          description: Result column names, in result order.
          items:
            type: string
          title: Columns
          type: array
        executor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The named executor that generated this statement
            (`reconcile_movement`, `test_timing`, `find_duplicates`), when one
            did. Null on a statement the agent wrote itself.
          title: Executor
        grounding_status:
          anyOf:
            - enum:
                - exact
                - unavailable
                - zero_result
              type: string
            - type: 'null'
          description: >-
            Whether this statement's stored result already carried proof of
            which source rows it read when the receipt was recorded. 'exact'
            means it did; 'unavailable' means the proof could not be read;
            'zero_result' means there were no rows to ground. Null when nothing
            had been captured yet — the ordinary case for a lane that captures
            at publication time, so this is a record of what execution happened
            to know and NOT a prediction of whether the receipt can be grounded.
            What was actually proven is published as `grounding_status` on the
            matching evidence query, beside the `regions` it earned.
          title: Grounding Status
        handle:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Content-addressed key of this statement's stored result, derived
            from the statement text. Server-side identity: it is what lets the
            run's own publication find the stored result and its capture-time
            provenance, and it is NOT an address an agent may query or chain
            from — `result_id` is the identity the caller and the row pager use.
            Null on a run that stored no result for the statement.
          title: Handle
        parameters:
          additionalProperties:
            type: string
          description: >-
            The executor's resolved call, flattened to text — the clock and its
            true grain, the window's day offsets, the signature, the tolerance,
            the population. Empty on a statement no executor generated. This is
            what makes a figure trace to a named, parameterized computation
            rather than to SQL alone.
          title: Parameters
          type: object
        result_id:
          description: >-
            Stable per-run identity of this statement, in execution order (e.g.
            'sql_3').
          title: Result Id
          type: string
        result_row_count:
          default: 0
          description: >-
            Rows in the statement's complete stored result. Equal to `row_count`
            when nothing was cut; the number a total or an exception count must
            be read from when `truncated` is set.
          title: Result Row Count
          type: integer
        row_count:
          default: 0
          description: Rows carried below — not the statement's unbounded result size.
          title: Row Count
          type: integer
        rows:
          description: >-
            Result rows, values rendered as text so a decimal, a date and a NULL
            all survive the wire.
          items:
            additionalProperties:
              type: string
            type: object
          title: Rows
          type: array
        saved_as:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The session view this statement was registered as, when it was.
            Every name in another receipt's ``views_used`` appears here on
            exactly one receipt, so the run's receipts define every view they
            cite.
          title: Saved As
        sql:
          description: The statement as executed, verbatim.
          title: Sql
          type: string
        table_bindings:
          description: >-
            The tables this statement registered, each with the view name it was
            referenced by.
          items:
            $ref: '#/components/schemas/SqlTableBinding'
          title: Table Bindings
          type: array
        truncated:
          default: false
          description: Whether rows past the stored cap were cut from this receipt.
          title: Truncated
          type: boolean
        view_sql:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The definition registered under `saved_as`, when it is not this
            statement itself. Null on an ordinary `save_as`, where `sql` IS the
            definition. Set by `build_journal_view`, which registers the
            per-journal frame and runs a bounded probe over it rather than
            materializing the whole frame — so the definition every later
            `views_used` refers to is still published by exactly one receipt.
          title: View Sql
        views_used:
          description: >-
            Session views registered when this statement ran, in definition
            order — the registry snapshot it executed under. A statement naming
            a view is replayable only against these, which is what makes named
            views admissible where chaining a previous call's result handle is
            not.
          items:
            type: string
          title: Views Used
          type: array
        warnings:
          description: >-
            Pre-execution lint notes attached to this statement — non-blocking,
            and published as part of its working.
          items:
            type: string
          title: Warnings
          type: array
      required:
        - result_id
        - sql
      title: SqlReceipt
      type: object
    ToolCallTrace:
      additionalProperties: false
      description: >-
        Carries an argument digest rather than raw arguments.


        Raw arguments would be a side channel around ``Coverage``: a caller
        could

        read back what the loop searched for on its behalf.
      properties:
        arguments_digest:
          title: Arguments Digest
          type: string
        duration_ms:
          title: Duration Ms
          type: integer
        hits:
          title: Hits
          type: integer
        tool:
          title: Tool
          type: string
      required:
        - tool
        - arguments_digest
        - hits
        - duration_ms
      title: ToolCallTrace
      type: object
    SearchLlmUsage:
      additionalProperties: false
      description: >-
        What answering one search query cost in LLM work.


        Present only when the run was asked to account for itself *and* spend
        reached its

        ledger; ``null`` otherwise, so a caller can tell "nothing was measured"
        from

        "nothing was spent". An empty ledger publishes ``null`` rather than a
        zeroed

        object for that reason: zeros would claim a measured run cost nothing,
        when what

        an empty ledger most likely records is accounting that never landed.


        The totals cover **every** LLM call the run made, at any depth: the
        agent's own

        turns, and the calls the retrieval tools made on its behalf — a document
        read by

        the recursive-LLM engine, a scan cracked by the vision engine, a tables
        question

        answered by the SQL agent. That is the number a per-query cost figure
        needs, and it

        is invariably several times the agent's own turn count.


        ``by_model`` is the same spend split by the model that served it,
        because a run

        legitimately spends on several at different prices — a total alone
        cannot be turned

        into money. The totals are the sum of ``by_model`` and are published
        anyway so the

        common case needs no arithmetic.


        Retried work is included: a provider timeout that cost tokens before
        failing was

        still paid for, and a cost figure that hid it would understate exactly
        the runs

        worth looking at.
      properties:
        by_model:
          description: The same spend per model that served it, highest first.
          items:
            $ref: '#/components/schemas/ModelLlmUsage'
          title: By Model
          type: array
        cached_input_tokens:
          default: 0
          description: >-
            The share of input_tokens served from a provider prompt cache —
            billed at a reduced rate, so it is reported separately rather than
            subtracted.
          title: Cached Input Tokens
          type: integer
        input_tokens:
          default: 0
          description: Prompt tokens across every request, cached ones included.
          title: Input Tokens
          type: integer
        output_tokens:
          default: 0
          description: Completion tokens across every request.
          title: Output Tokens
          type: integer
        requests:
          default: 0
          description: Completed LLM requests, tool-internal ones included.
          title: Requests
          type: integer
      title: SearchLlmUsage
      type: object
    ExtractedField:
      additionalProperties: false
      description: >-
        One field an extraction looked for.


        ``not_found`` is a real outcome with an entry, not a missing key: an

        extraction that silently omits what it could not find is
        indistinguishable

        from one that never looked.
      properties:
        citations:
          items:
            $ref: '#/components/schemas/Citation'
          title: Citations
          type: array
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
        path:
          description: JSON pointer into the schema.
          title: Path
          type: string
        status:
          enum:
            - found
            - not_found
            - ambiguous
          title: Status
          type: string
        value:
          anyOf:
            - type: string
            - type: integer
            - type: number
            - type: boolean
            - type: 'null'
          title: Value
      required:
        - path
        - status
      title: ExtractedField
      type: object
    File:
      additionalProperties: false
      description: >-
        A source file. The derived tree is platform-owned and has no CRUD
        surface.
      properties:
        access_label:
          anyOf:
            - type: string
            - type: 'null'
          description: Exactly one label, or null when the workspace declares none.
          title: Access Label
        access_label_source:
          anyOf:
            - $ref: '#/components/schemas/AccessLabelSource'
            - type: 'null'
        category:
          anyOf:
            - type: string
            - type: 'null'
          description: Null until categorised.
          title: Category
        created_at:
          format: date-time
          title: Created At
          type: string
        expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When derived material for this file ages out.
          title: Expires At
        file_id:
          format: uuid
          title: File Id
          type: string
        file_name:
          title: File Name
          type: string
        file_type:
          title: File Type
          type: string
        graph_inclusion:
          default: auto
          description: >-
            This file's knowledge-graph inclusion policy, not its effective
            membership. 'auto' defers to the workspace's KG exclusion rules;
            'include'/'exclude' override them for this one file. A file excluded
            by a workspace rule still reads 'auto' here, so this does not on its
            own tell an excluded file from one whose graph is not built yet —
            read representations.knowledge_graph for whether a build has covered
            it.
          enum:
            - auto
            - include
            - exclude
          title: Graph Inclusion
          type: string
        ingested_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Ingested At
        ingested_hash:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Content hash at the last successful ingestion. Null with ingested_at
            means never ingested.
          title: Ingested Hash
        ingestion_status:
          $ref: '#/components/schemas/IngestionStatus'
        labels:
          additionalProperties:
            type: string
          description: Caller-supplied metadata.
          title: Labels
          type: object
        observed_hash:
          title: Observed Hash
          type: string
        path:
          title: Path
          type: string
        size_bytes:
          title: Size Bytes
          type: integer
        updated_at:
          format: date-time
          title: Updated At
          type: string
        version:
          description: Starts at 1; increments on every content replacement.
          title: Version
          type: integer
        workspace_id:
          format: uuid
          title: Workspace Id
          type: string
      required:
        - file_id
        - workspace_id
        - path
        - file_name
        - file_type
        - size_bytes
        - observed_hash
        - ingestion_status
        - version
        - created_at
        - updated_at
      title: File
      type: object
    CatalogColumnDescriptor:
      additionalProperties: false
      description: One extracted field the result's rows may carry.
      properties:
        description:
          default: ''
          title: Description
          type: string
        field:
          title: Field
          type: string
        filtered:
          default: false
          description: >-
            The published query filtered on this column — or ranked by it under
            a top-N LIMIT, where ranking decides membership (server-extracted
            from the SQL, never model-authored). These are the values the
            matches hinge on, and the first cells worth grounding against their
            source documents.
          title: Filtered
          type: boolean
        kind:
          enum:
            - text
            - date
            - money
            - number
            - boolean
          title: Kind
          type: string
        repeated:
          default: false
          description: Several values may exist per row (parties, signatories).
          title: Repeated
          type: boolean
      required:
        - field
        - kind
      title: CatalogColumnDescriptor
      type: object
    ContentEvidence:
      additionalProperties: false
      description: >-
        One passage that satisfied the residual content condition,
        server-verified.
      properties:
        component:
          anyOf:
            - type: string
            - type: 'null'
          title: Component
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
        quote:
          title: Quote
          type: string
        source_file_id:
          format: uuid
          title: Source File Id
          type: string
        source_path:
          title: Source Path
          type: string
      required:
        - source_path
        - source_file_id
        - quote
      title: ContentEvidence
      type: object
    Coverage:
      additionalProperties: false
      description: >-
        What the access gate withheld, in counts and label names only.


        Never a name, path, or fragment of withheld content. Naming the labels

        leaks nothing the caller cannot already read from the workspace config,
        and

        it turns "some results were withheld" into an actionable request.
      properties:
        labels_required:
          description: Which labels would have been needed to see the withheld candidates.
          items:
            type: string
          title: Labels Required
          type: array
        request_access_hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Access Hint
        restricted_candidates:
          default: 0
          title: Restricted Candidates
          type: integer
      title: Coverage
      type: object
    FieldReadability:
      additionalProperties: false
      description: >-
        How much of one filtered field the extraction could actually read.


        Only a ``found`` observation materializes a value, so a comparison
        against a

        field the extraction did not resolve silently drops those components:
        the

        query is correct and the result is empty for a reason that has nothing
        to do

        with the caller's question. Reported per field the query filtered on,
        and

        only when ``readable < in_scope`` — a fully readable field says nothing.


        Read it with ``total_matches``: when ``readable`` is 0 the empty result

        carries no information about the population, and when the unreadable

        remainder is large next to ``total_matches`` the matches shown are a
        floor,

        not a census.
      properties:
        field:
          description: The extracted field the query filtered on.
          title: Field
          type: string
        in_scope:
          description: Components in scope whose document type carries this field.
          title: In Scope
          type: integer
        readable:
          description: >-
            Of those, how many had a resolved value the predicate could
            evaluate.
          title: Readable
          type: integer
      required:
        - field
        - in_scope
        - readable
      title: FieldReadability
      type: object
    FilteredSearchRow:
      additionalProperties: false
      description: One matching logical component, named as the caller's own uploaded file.
      properties:
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        cells:
          items:
            $ref: '#/components/schemas/FilteredSearchCell'
          title: Cells
          type: array
        component:
          description: >-
            Public component name — the tab or document section, matching the
            component= argument of the file tools (qa-file, read-file,
            query-tables). Several document rows can share one section name;
            page_start/page_end distinguish them. A media row's name is the
            recording stem, display-only (file tools take the whole file).
          title: Component
          type: string
        component_kind:
          enum:
            - document
            - sheet
            - media
          title: Component Kind
          type: string
        document_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Document Type
        page_end:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page End
        page_start:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Start
        source_file_id:
          format: uuid
          title: Source File Id
          type: string
        source_path:
          description: The uploaded file the component belongs to.
          title: Source Path
          type: string
        subcategory:
          anyOf:
            - type: string
            - type: 'null'
          title: Subcategory
        summary:
          default: ''
          title: Summary
          type: string
      required:
        - source_path
        - source_file_id
        - component
        - component_kind
      title: FilteredSearchRow
      type: object
    GroundTargetResult:
      additionalProperties: false
      properties:
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        id:
          title: Id
          type: string
        matches:
          items:
            $ref: '#/components/schemas/GroundMatch'
          title: Matches
          type: array
        status:
          enum:
            - found
            - not_found
            - failed
          title: Status
          type: string
      required:
        - id
        - status
      title: GroundTargetResult
      type: object
    IngestedFileOutcome:
      additionalProperties: false
      description: >-
        Per-file, because one corrupt file in a folder of 400 must not fail the
        run.
      properties:
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
        file_id:
          format: uuid
          title: File Id
          type: string
        lane:
          anyOf:
            - type: string
            - type: 'null'
          title: Lane
        path:
          title: Path
          type: string
        status:
          enum:
            - ingested
            - skipped_unchanged
            - failed
          title: Status
          type: string
        units:
          default: 0
          title: Units
          type: integer
      required:
        - file_id
        - path
        - status
      title: IngestedFileOutcome
      type: object
    KnowledgeGraphFileFailure:
      additionalProperties: false
      description: One source file the build could not get into the graph.
      properties:
        error:
          description: The verbatim final cause, as the failing step reported it.
          title: Error
          type: string
        path:
          title: Path
          type: string
        phase:
          description: 'Where it failed: ''classifying'' (never registered) or ''extracting''.'
          enum:
            - classifying
            - extracting
          title: Phase
          type: string
      required:
        - path
        - phase
        - error
      title: KnowledgeGraphFileFailure
      type: object
    ParseDocument:
      additionalProperties: false
      description: The parsed document payload under ``ParseResult.document``.
      properties:
        blocks:
          anyOf:
            - items:
                $ref: '#/components/schemas/ParsedBlock'
              type: array
            - type: 'null'
          title: Blocks
        chunks:
          items:
            $ref: '#/components/schemas/ParseChunk'
          title: Chunks
          type: array
        markdown:
          anyOf:
            - type: string
            - type: 'null'
          title: Markdown
        ocr:
          anyOf:
            - $ref: '#/components/schemas/ParseOcrData'
            - type: 'null'
        page_count:
          title: Page Count
          type: integer
        spreadsheet:
          anyOf:
            - $ref: '#/components/schemas/ParseSpreadsheet'
            - type: 'null'
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
      required:
        - page_count
      title: ParseDocument
      type: object
    Evidence:
      additionalProperties: false
      description: >-
        The citation primitive.


        Every result that asserts something about a document or the corpus
        carries

        it. A synthesised sentence with no evidence behind it is a bug, not a

        degraded mode.


        ``path`` is always the uploaded **source** path — that is what every
        external

        audience (``/v1`` bodies, the console, the search-agent result) is
        shown. The

        two ``exclude=True`` fields below are the host's internal twin of it,
        for the

        audience that must not see source paths at all (the agent's tools
        address

        ingestion derivatives); they are never serialized, so the ``/v1`` wire
        shape

        is exactly what it was before they existed.


        ``component`` closes the loop from a hit back to the file tools: it is
        the

        public component name of the hit — exactly the vocabulary
        ``file-metadata``

        lists and ``qa-file`` / ``read-file`` accept as ``component=`` (the tab
        name

        for a spreadsheet, the section/subcategory for a split document).
        ``None``

        means a single-component file or that attribution was unavailable.


        ``locator`` is present only when the producer actually located the
        snippet.

        ``None`` is not a degraded mode: an engine that answered from a whole

        component (the QA agent's quotes, the DuckDB agent's SQL receipts)
        asserts

        the file and ``component``, nothing finer. Pinning such a snippet to a

        region — a page bbox, a sheet cell range — is a separate ``ground`` call
        on

        ``path`` with ``snippet`` as the target text (and ``component`` as the

        ``sheet`` hint when the file is a spreadsheet).
      properties:
        component:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Public component of the hit, in the vocabulary file-metadata lists
            and qa-file/read-file accept as component= (tab name for
            spreadsheets, section for split documents); None for a
            single-component file or when attribution is unavailable.
          title: Component
        file_id:
          format: uuid
          title: File Id
          type: string
        locator:
          anyOf:
            - discriminator:
                mapping:
                  audio_range:
                    $ref: '#/components/schemas/AudioRange'
                  json_pointer:
                    $ref: '#/components/schemas/JsonPointer'
                  jsonl_record:
                    $ref: '#/components/schemas/JsonlRecord'
                  row_range:
                    $ref: '#/components/schemas/RowRange'
                  spreadsheet_range:
                    $ref: '#/components/schemas/SpreadsheetRange'
                  text_range:
                    $ref: '#/components/schemas/TextRange'
                  visual_region:
                    $ref: '#/components/schemas/VisualRegion'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/TextRange'
                - $ref: '#/components/schemas/VisualRegion'
                - $ref: '#/components/schemas/SpreadsheetRange'
                - $ref: '#/components/schemas/JsonlRecord'
                - $ref: '#/components/schemas/JsonPointer'
                - $ref: '#/components/schemas/AudioRange'
                - $ref: '#/components/schemas/RowRange'
            - type: 'null'
          description: >-
            Where the snippet sits, when the producer located it. None means the
            citation is component-level: ground the snippet against path
            (sheet=component for spreadsheets) to place it.
          title: Locator
        page:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The 1-based page the producer attributed the snippet to when it
            produced no locator; None when unknown or when the locator already
            carries the page.
          title: Page
        path:
          title: Path
          type: string
        relevance_score:
          title: Relevance Score
          type: number
        snippet:
          title: Snippet
          type: string
        why:
          description: Which retrieval leg matched, or which graph path led here.
          title: Why
          type: string
      required:
        - file_id
        - path
        - relevance_score
        - snippet
        - why
      title: Evidence
      type: object
    UnavailableTable:
      additionalProperties: false
      description: >-
        A requested path (or one of its ingested sheets) that could not be
        queried.


        ``error_kind`` is ``None`` only when the failure happened before ingest

        could even classify it (an access or resolution error, which raises as a

        typed HTTP error instead of reaching this list).


        Lives here rather than beside the tool responses because a stored job

        result reports the same unusable inputs the synchronous response did —
        one

        definition, so a reopened run cannot describe them differently.
      properties:
        error:
          title: Error
          type: string
        error_kind:
          anyOf:
            - enum:
                - conversion_rejected
                - conversion_failed
                - profile_rejected
                - profile_failed
              type: string
            - type: 'null'
          title: Error Kind
        path:
          title: Path
          type: string
      required:
        - path
        - error
      title: UnavailableTable
      type: object
    QaTableResultFile:
      additionalProperties: false
      description: >-
        A Parquet result this run retained, addressable in the caller's
        workspace.


        The canonical ``s3://`` / ``file://`` location is deliberately absent:
        it is

        kept privately alongside the stored result (``StoredQaTablesResult``),
        and

        every read mints a fresh, expiring pair of URLs from it. A stored URL
        would

        be expired by the time anyone reopened the run.
      properties:
        download_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Minted on read; null when the artifact is gone.
          title: Download Url
        download_url_expires_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Download Url Expires At
        file_id:
          format: uuid
          title: File Id
          type: string
        file_name:
          title: File Name
          type: string
        format:
          const: parquet
          default: parquet
          title: Format
          type: string
        grounding:
          anyOf:
            - $ref: '#/components/schemas/TableQueryGrounding'
            - type: 'null'
          description: >-
            Exact source regions and bounded receipt data when capture-time
            provenance was available.
        handle:
          title: Handle
          type: string
        path:
          title: Path
          type: string
        preview_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Minted on read; null when the artifact is gone.
          title: Preview Url
        row_count:
          title: Row Count
          type: integer
        source_paths:
          items:
            type: string
          title: Source Paths
          type: array
        sql:
          title: Sql
          type: string
      required:
        - file_id
        - handle
        - path
        - file_name
        - row_count
        - sql
      title: QaTableResultFile
      type: object
    QueryTablePreview:
      additionalProperties: false
      description: One retained result table with a bounded inline preview.
      properties:
        columns:
          default: []
          items:
            $ref: '#/components/schemas/QueryTableColumn'
          maxItems: 50
          title: Columns
          type: array
        handle:
          title: Handle
          type: string
        path:
          anyOf:
            - type: string
            - type: 'null'
          title: Path
        preview_truncated:
          default: false
          title: Preview Truncated
          type: boolean
        row_count:
          title: Row Count
          type: integer
        rows:
          default: []
          items:
            additionalProperties:
              type: string
            type: object
          maxItems: 20
          title: Rows
          type: array
      required:
        - handle
        - row_count
      title: QueryTablePreview
      type: object
    SplitSegment:
      additionalProperties: false
      properties:
        artifacts:
          items:
            $ref: '#/components/schemas/SplitArtifact'
          title: Artifacts
          type: array
        boundary_confidence:
          $ref: '#/components/schemas/SplitConfidence'
        class:
          anyOf:
            - $ref: '#/components/schemas/SplitSegmentCategory'
            - type: 'null'
        classes:
          anyOf:
            - items:
                $ref: '#/components/schemas/SplitSegmentCategory'
              type: array
            - type: 'null'
          title: Classes
        classification_confidence:
          $ref: '#/components/schemas/SplitConfidence'
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
        end_page:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          title: End Page
        id:
          title: Id
          type: string
        instance:
          anyOf:
            - $ref: '#/components/schemas/SplitInstance'
            - type: 'null'
        json_pointer:
          anyOf:
            - pattern: ^(?:$|/)
              type: string
            - type: 'null'
          title: Json Pointer
        sequence:
          minimum: 0
          title: Sequence
          type: integer
        sheet_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Sheet Name
        start_page:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          title: Start Page
        status:
          enum:
            - matched
            - unclassified
          title: Status
          type: string
        warnings:
          items:
            type: string
          title: Warnings
          type: array
      required:
        - id
        - sequence
        - status
      title: SplitSegment
      type: object
    ScoredCategory:
      additionalProperties: false
      properties:
        category:
          title: Category
          type: string
        confidence:
          title: Confidence
          type: number
      required:
        - category
        - confidence
      title: ScoredCategory
      type: object
    ClassifyLabel:
      additionalProperties: false
      properties:
        class_id:
          title: Class Id
          type: string
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
        label:
          title: Label
          type: string
        rank:
          minimum: 1
          title: Rank
          type: integer
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        subclass_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Subclass Id
      required:
        - class_id
        - label
        - rank
      title: ClassifyLabel
      type: object
    ClassifyPageRange:
      additionalProperties: false
      properties:
        end:
          minimum: 1
          title: End
          type: integer
        start:
          minimum: 1
          title: Start
          type: integer
      required:
        - start
        - end
      title: ClassifyPageRange
      type: object
    BoundColumn:
      additionalProperties: false
      description: One column the run pinned to a definitional slot.
      properties:
        column:
          title: Column
          type: string
        component:
          anyOf:
            - type: string
            - type: 'null'
          title: Component
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            What the slot additionally states about this column — a clock's true
            grain, that a basis is the one the trial balance ties to, what a
            calendar date means.
          title: Detail
        path:
          title: Path
          type: string
        slot:
          description: >-
            The slot this column fills, dotted: 'journal_key', 'clocks.created',
            'amount_bases[reporting].debit', 'accounts.fsli'.
          title: Slot
          type: string
        table_name:
          title: Table Name
          type: string
      required:
        - slot
        - path
        - table_name
        - column
      title: BoundColumn
      type: object
    BoundPeriod:
      additionalProperties: false
      description: >-
        One value of the period axis and the role the run gave it, in period
        order.
      properties:
        role:
          description: '''opening'', ''month'', ''year_end_adj'' or ''total_row''.'
          title: Role
          type: string
        value:
          title: Value
          type: string
      required:
        - value
        - role
      title: BoundPeriod
      type: object
    BoundTable:
      additionalProperties: false
      description: One table of the package, and the role the run bound it to.
      properties:
        component:
          anyOf:
            - type: string
            - type: 'null'
          description: The tab, when the file contributed more than one table.
          title: Component
        path:
          description: The uploaded file, e.g. 'ledger/journal.xlsx'.
          title: Path
          type: string
        role:
          description: >-
            The slot it fills: 'journal_lines', 'journal_headers',
            'trial_balance', ….
          title: Role
          type: string
        table_name:
          description: The view name this run's SQL referenced it by.
          title: Table Name
          type: string
      required:
        - role
        - path
        - table_name
      title: BoundTable
      type: object
    BoundValueSet:
      additionalProperties: false
      description: >-
        One column-and-values pin: an encoding candidate, or a layer's
        membership.


        Named even when its slot carries only one, because the name is what a
        test

        cites when a slot carries two — which is a state this binding may
        legitimately

        be in. Two candidates of ``encodings.manual`` published here means the
        run

        kept both readings of "manual" alive and chose between them per test,
        which is

        what the answer's own working will say.
      properties:
        column:
          title: Column
          type: string
        component:
          anyOf:
            - type: string
            - type: 'null'
          title: Component
        name:
          description: The candidate's name, as a test spec cites it.
          title: Name
          type: string
        note:
          default: ''
          description: >-
            Where this reading came from — a policy sheet, a flag column, a
            profiled domain.
          title: Note
          type: string
        path:
          title: Path
          type: string
        slot:
          description: '''encodings.posted'', ''encodings.manual'', ''layers.book'', ….'
          title: Slot
          type: string
        table_name:
          title: Table Name
          type: string
        values:
          description: The values of that column which mean this.
          items:
            type: string
          title: Values
          type: array
      required:
        - slot
        - name
        - path
        - table_name
        - column
      title: BoundValueSet
      type: object
    DerivationTrace:
      additionalProperties: false
      description: >-
        The answer's computation DAG when evidence is derived rather than
        extracted.
      properties:
        steps:
          items:
            $ref: '#/components/schemas/DerivationStep'
          title: Steps
          type: array
      title: DerivationTrace
      type: object
    TableQueryGrounding:
      additionalProperties: false
      description: >-
        One SQL query executed against the caller's tables while answering.


        The grounding behind a computed evidence: when the agent answers a

        count/sum/join question it runs a SQL agent over the uploaded tables,
        and

        this is the receipt — the query text and a bounded preview of what it

        returned. Attached to the evidence it grounds rather than published

        globally, so a computed figure and its computation travel together.


        ``source_paths`` name uploaded files, resolved server-side through the

        caller's access gate exactly like ``source_path`` on the evidence
        itself.
      properties:
        columns:
          items:
            $ref: '#/components/schemas/TableQueryColumn'
          title: Columns
          type: array
        grounding_reason:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Qualification on grounding_status, when present. Set for
            'unavailable' (explains why proof was not possible) and for 'exact'
            when capture succeeded but the source regions are broader than the
            minimal contributing set (e.g.
            'regions_broad:narrowing_specs_unavailable'). None when grounding is
            fully exact or absent.
          title: Grounding Reason
        grounding_status:
          anyOf:
            - enum:
                - exact
                - unavailable
                - zero_result
              type: string
            - type: 'null'
          description: >-
            Capture-time provenance status behind this query's regions. 'exact':
            the exact-provenance sidecar proved every row the query read, so its
            'provenance'-basis regions are trustworthy (source regions may be
            broader than the minimal contributing set when grounding_reason
            carries a 'regions_broad:…' qualifier). 'unavailable': no exact
            proof could be captured (a legacy result, or a statement shape the
            capturer cannot instrument) — no 'provenance'-basis regions are
            attached, never a guessed whole-table span. 'zero_result': the query
            matched no rows, so there is nothing to ground. None on legacy
            payloads and on a query with no unclaimed table left to ground.
          title: Grounding Status
        preview_truncated:
          default: false
          description: Whether the preview cut rows or columns.
          title: Preview Truncated
          type: boolean
        regions:
          description: >-
            Original-file coordinates for the verified claims whose source file
            has an addressable grid.
          items:
            discriminator:
              mapping:
                row_range:
                  $ref: '#/components/schemas/RowRangeQueryRegion'
                sheet:
                  $ref: '#/components/schemas/SheetQueryRegion'
              propertyName: kind
            oneOf:
              - $ref: '#/components/schemas/SheetQueryRegion'
              - $ref: '#/components/schemas/RowRangeQueryRegion'
          title: Regions
          type: array
        result_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Stable identity of the stored query result behind this receipt. Lets
            the grounding-rows endpoint replay this exact query for matched-row
            pages beyond the regions' inline runs.
          title: Result Id
        row_count:
          default: 0
          description: Rows in the query's full result, not in the preview below.
          title: Row Count
          type: integer
        rows:
          description: >-
            Leading result rows, values rendered as text — a bounded preview,
            never the full result.
          items:
            additionalProperties:
              type: string
            type: object
          title: Rows
          type: array
        source_paths:
          description: >-
            The uploaded table files this query read — directly, or through a
            prior result it built on — e.g. 'planning/FS GF Custom.xlsx'.
          items:
            type: string
          title: Source Paths
          type: array
        sql:
          title: Sql
          type: string
        supports_answer:
          default: true
          description: >-
            False for exploratory SQL the tables engine ran but did not mark as
            part of the answer's calculation trail.
          title: Supports Answer
          type: boolean
        verified:
          default: false
          description: >-
            True when at least one claim behind this query passed mechanical
            verification against the source data. Independent of 'regions': a
            source without an addressable grid verifies but cannot be pointed
            at, so an empty 'regions' never means unverified.
          title: Verified
          type: boolean
      required:
        - sql
      title: TableQueryGrounding
      type: object
    JetBreakdown:
      additionalProperties: false
      description: >-
        The tabular result behind one figure, attached by the server.


        What a caller asking "by FSLI and month" or "top 10 preparers" wanted,
        in the

        shape the question implies. The rows are NOT model-authored and never
        were:

        they are the cited receipt's own result, stringified and capped here,
        attached

        at finalize from :class:`SqlReceipt` rows the run already published.
        That is

        the whole design — a figure's table costs the model no output tokens and

        cannot carry a cell no statement returned — and it is why there is no

        reshaping either: the receipt's shape IS the breakdown, so a matrix the
        SQL

        never grouped by month is a wrong statement rather than a rendering
        problem.


        ``result_id`` names the receipt the rows came from, which is always one
        of the

        figure's own citations — either on ``result_ids`` or its
        ``exception_listing_result_id``,

        the two id sets the console makes openable — so the breakdown is a
        convenience

        over the payload's own working, never a second source of truth, and a
        reader who

        wants the statement, the whole bounded result or its row provenance
        follows that

        id. (When the model names a listing it did not also list in
        ``receipt_ids``, that

        id reaches the figure through ``exception_listing_result_id`` rather
        than

        ``result_ids``; both render as receipt buttons, so the table stays one
        click away

        either way.)
      properties:
        columns:
          description: Column names, in the statement's own result order.
          items:
            type: string
          title: Columns
          type: array
        result_id:
          description: '`sql_receipts[].result_id` of the statement these rows are.'
          title: Result Id
          type: string
        rows:
          description: >-
            Rows in receipt order, cells as text so a decimal, a date and a NULL
            all survive the wire. At most 200; a longer result sets `truncated`
            and stays whole on its receipt.
          items:
            items:
              type: string
            type: array
          title: Rows
          type: array
        truncated:
          default: false
          description: >-
            Whether rows were cut — either by this table's own cap or already on
            the receipt it came from. A capped breakdown is never read as the
            complete listing.
          title: Truncated
          type: boolean
      required:
        - result_id
      title: JetBreakdown
      type: object
    SqlTableBinding:
      additionalProperties: false
      description: >-
        One table a receipted statement registered, in both namespaces at once.


        ``path`` (plus ``component`` for one tab of a workbook) is the caller's
        own

        uploaded file; ``table_name`` is the view name the statement referenced
        it

        by. Both halves are load-bearing: view names are settled per run, so SQL

        that hardcodes one is only replayable alongside the mapping that
        produced

        it — a statement published without its bindings cannot be re-run.
      properties:
        component:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The tab of that workbook, when the file contributed more than one
            table. Null for a single-table file.
          title: Component
        path:
          description: The uploaded table file this view read, e.g. 'ledger/journal.xlsx'.
          title: Path
          type: string
        table_name:
          description: The view name the SQL referenced this table by, for THIS run.
          title: Table Name
          type: string
      required:
        - path
        - table_name
      title: SqlTableBinding
      type: object
    ModelLlmUsage:
      description: >-
        One model's share of a run's LLM spend.


        Per model rather than per run alone because a single run legitimately
        spends

        on several: a search agent's own turns, the vision engine that cracked a

        scan, the sub-model an RLM read used. They are priced differently, so a

        total without this breakdown cannot be turned into money.
      properties:
        cached_input_tokens:
          default: 0
          description: >-
            The share of input_tokens served from the provider's prompt cache —
            billed at a reduced rate, so pricing needs it separated out rather
            than subtracted.
          title: Cached Input Tokens
          type: integer
        input_tokens:
          default: 0
          description: Prompt tokens sent to this model, cached ones included.
          title: Input Tokens
          type: integer
        model:
          description: >-
            Model identifier as the provider reported it, or as the caller asked
            for it.
          title: Model
          type: string
        output_tokens:
          default: 0
          description: Completion tokens this model generated.
          title: Output Tokens
          type: integer
        requests:
          default: 0
          description: Completed LLM requests served by this model.
          title: Requests
          type: integer
      required:
        - model
      title: ModelLlmUsage
      type: object
    Citation:
      additionalProperties: false
      description: Where an extracted value was found, with optional quoted source text.
      properties:
        location:
          discriminator:
            mapping:
              json_pointer:
                $ref: '#/components/schemas/JsonPointer'
              page_region:
                $ref: '#/components/schemas/PageRegion'
              row_range:
                $ref: '#/components/schemas/RowRange'
              sheet_range:
                $ref: '#/components/schemas/SheetRange'
              table_region:
                $ref: '#/components/schemas/TableRegion'
              text_span:
                $ref: '#/components/schemas/TextSpan'
            propertyName: kind
          oneOf:
            - $ref: '#/components/schemas/PageRegion'
            - $ref: '#/components/schemas/SheetRange'
            - $ref: '#/components/schemas/TextSpan'
            - $ref: '#/components/schemas/RowRange'
            - $ref: '#/components/schemas/TableRegion'
            - $ref: '#/components/schemas/JsonPointer'
          title: Location
        source_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Text
      required:
        - location
      title: Citation
      type: object
    AccessLabelSource:
      description: |-
        Which mechanism produced a document's label.

        The ``default_label`` fallback records as ``inherited``, so an audit can
        tell a real classification from a fallback.
      enum:
        - inherited
        - classified
        - mirrored
      title: AccessLabelSource
      type: string
    IngestionStatus:
      description: >-
        The only thing that says whether a file is searchable.


        ``expired`` cannot be derived from the hash pair: retention clears

        ``ingested_hash``, so an aged-out file and a never-ingested file look

        identical. They call for different customer actions, so the status
        carries

        the distinction the hashes cannot.
      enum:
        - discovered
        - queued
        - ingesting
        - ingested
        - stale
        - expired
        - failed
        - not_required
      title: IngestionStatus
      type: string
    FilteredSearchCell:
      additionalProperties: false
      description: >-
        One extracted field value on one row, with its evidence (D10).


        ``status`` is value-level data honesty: ``not_found`` means the
        component

        was examined and the field is absent; ``ambiguous`` means present but
        not

        normalizable (e.g. money without a currency); ``unexamined`` means the

        extraction could not say.
      properties:
        citation:
          anyOf:
            - $ref: '#/components/schemas/Citation'
            - type: 'null'
          description: Where the value was found, with quoted source text.
        field:
          title: Field
          type: string
        item_index:
          default: 0
          description: Position for repeated fields; 0 for scalars.
          title: Item Index
          type: integer
        status:
          enum:
            - found
            - not_found
            - ambiguous
            - unexamined
          title: Status
          type: string
        value:
          anyOf:
            - discriminator:
                mapping:
                  boolean:
                    $ref: '#/components/schemas/BooleanCell'
                  date:
                    $ref: '#/components/schemas/DateCell'
                  money:
                    $ref: '#/components/schemas/MoneyCell'
                  number:
                    $ref: '#/components/schemas/NumberCell'
                  text:
                    $ref: '#/components/schemas/TextCell'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/MoneyCell'
                - $ref: '#/components/schemas/TextCell'
                - $ref: '#/components/schemas/DateCell'
                - $ref: '#/components/schemas/NumberCell'
                - $ref: '#/components/schemas/BooleanCell'
            - type: 'null'
          title: Value
      required:
        - field
        - status
      title: FilteredSearchCell
      type: object
    GroundMatch:
      additionalProperties: false
      properties:
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
        cropped_image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Cropped Image Url
        location:
          anyOf:
            - discriminator:
                mapping:
                  json_pointer:
                    $ref: '#/components/schemas/JsonPointer'
                  page_region:
                    $ref: '#/components/schemas/PageRegion'
                  row_range:
                    $ref: '#/components/schemas/RowRange'
                  sheet_range:
                    $ref: '#/components/schemas/SheetRange'
                  table_region:
                    $ref: '#/components/schemas/TableRegion'
                  text_span:
                    $ref: '#/components/schemas/TextSpan'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/PageRegion'
                - $ref: '#/components/schemas/SheetRange'
                - $ref: '#/components/schemas/TextSpan'
                - $ref: '#/components/schemas/RowRange'
                - $ref: '#/components/schemas/TableRegion'
                - $ref: '#/components/schemas/JsonPointer'
            - discriminator:
                mapping:
                  audio_range:
                    $ref: '#/components/schemas/AudioRange'
                  json_pointer:
                    $ref: '#/components/schemas/JsonPointer'
                  jsonl_record:
                    $ref: '#/components/schemas/JsonlRecord'
                  row_range:
                    $ref: '#/components/schemas/RowRange'
                  spreadsheet_range:
                    $ref: '#/components/schemas/SpreadsheetRange'
                  text_range:
                    $ref: '#/components/schemas/TextRange'
                  visual_region:
                    $ref: '#/components/schemas/VisualRegion'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/TextRange'
                - $ref: '#/components/schemas/VisualRegion'
                - $ref: '#/components/schemas/SpreadsheetRange'
                - $ref: '#/components/schemas/JsonlRecord'
                - $ref: '#/components/schemas/JsonPointer'
                - $ref: '#/components/schemas/AudioRange'
                - $ref: '#/components/schemas/RowRange'
          title: Location
        match_method:
          enum:
            - exact
            - normalized
            - semantic
          title: Match Method
          type: string
        matched_text:
          title: Matched Text
          type: string
        rank:
          minimum: 1
          title: Rank
          type: integer
      required:
        - rank
        - matched_text
        - match_method
        - location
      title: GroundMatch
      type: object
    ParsedBlock:
      additionalProperties: false
      description: One structural unit of a parsed document.
      properties:
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          title: Confidence
        content:
          title: Content
          type: string
        id:
          title: Id
          type: string
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Crop URL when output.include_images is true and this block is a
            figure region.
          title: Image Url
        location:
          anyOf:
            - discriminator:
                mapping:
                  json_pointer:
                    $ref: '#/components/schemas/JsonPointer'
                  page_region:
                    $ref: '#/components/schemas/PageRegion'
                  row_range:
                    $ref: '#/components/schemas/RowRange'
                  sheet_range:
                    $ref: '#/components/schemas/SheetRange'
                  table_region:
                    $ref: '#/components/schemas/TableRegion'
                  text_span:
                    $ref: '#/components/schemas/TextSpan'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/PageRegion'
                - $ref: '#/components/schemas/SheetRange'
                - $ref: '#/components/schemas/TextSpan'
                - $ref: '#/components/schemas/RowRange'
                - $ref: '#/components/schemas/TableRegion'
                - $ref: '#/components/schemas/JsonPointer'
            - type: 'null'
          title: Location
        type:
          title: Type
          type: string
      required:
        - id
        - type
        - content
      title: ParsedBlock
      type: object
    ParseChunk:
      additionalProperties: false
      description: >-
        One RAG-oriented chunk produced when ``chunking.strategy`` is not
        ``none``.
      properties:
        content:
          title: Content
          type: string
        id:
          title: Id
          type: string
        location:
          anyOf:
            - discriminator:
                mapping:
                  json_pointer:
                    $ref: '#/components/schemas/JsonPointer'
                  page_region:
                    $ref: '#/components/schemas/PageRegion'
                  row_range:
                    $ref: '#/components/schemas/RowRange'
                  sheet_range:
                    $ref: '#/components/schemas/SheetRange'
                  table_region:
                    $ref: '#/components/schemas/TableRegion'
                  text_span:
                    $ref: '#/components/schemas/TextSpan'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/PageRegion'
                - $ref: '#/components/schemas/SheetRange'
                - $ref: '#/components/schemas/TextSpan'
                - $ref: '#/components/schemas/RowRange'
                - $ref: '#/components/schemas/TableRegion'
                - $ref: '#/components/schemas/JsonPointer'
            - type: 'null'
          title: Location
      required:
        - id
        - content
      title: ParseChunk
      type: object
    ParseOcrData:
      additionalProperties: false
      description: Optional inline OCR geometry requested by the caller.
      properties:
        lines:
          items:
            $ref: '#/components/schemas/OcrElement'
          title: Lines
          type: array
        words:
          items:
            $ref: '#/components/schemas/OcrElement'
          title: Words
          type: array
      title: ParseOcrData
      type: object
    ParseSpreadsheet:
      additionalProperties: false
      description: Spreadsheet-specific Parse artifacts.
      properties:
        sheets:
          items:
            $ref: '#/components/schemas/ParseSpreadsheetSheet'
          title: Sheets
          type: array
      title: ParseSpreadsheet
      type: object
    AudioRange:
      additionalProperties: false
      properties:
        end_ms:
          title: End Ms
          type: integer
        kind:
          const: audio_range
          default: audio_range
          title: Kind
          type: string
        start_ms:
          title: Start Ms
          type: integer
      required:
        - start_ms
        - end_ms
      title: AudioRange
      type: object
    JsonPointer:
      additionalProperties: false
      description: An RFC 6901 pointer into a JSON source; an empty string means the root.
      properties:
        kind:
          const: json_pointer
          default: json_pointer
          title: Kind
          type: string
        pointer:
          pattern: ^(?:$|/)
          title: Pointer
          type: string
      required:
        - pointer
      title: JsonPointer
      type: object
    JsonlRecord:
      additionalProperties: false
      properties:
        column:
          anyOf:
            - type: string
            - type: 'null'
          title: Column
        kind:
          const: jsonl_record
          default: jsonl_record
          title: Kind
          type: string
        row_offset:
          title: Row Offset
          type: integer
      required:
        - row_offset
      title: JsonlRecord
      type: object
    RowRange:
      additionalProperties: false
      description: A 0-based inclusive row run on a parquet table.
      properties:
        column:
          anyOf:
            - type: string
            - type: 'null'
          title: Column
        end_row:
          minimum: 0
          title: End Row
          type: integer
        kind:
          const: row_range
          default: row_range
          title: Kind
          type: string
        start_row:
          minimum: 0
          title: Start Row
          type: integer
      required:
        - start_row
        - end_row
      title: RowRange
      type: object
    SpreadsheetRange:
      additionalProperties: false
      properties:
        a1_range:
          title: A1 Range
          type: string
        kind:
          const: spreadsheet_range
          default: spreadsheet_range
          title: Kind
          type: string
        sheet:
          title: Sheet
          type: string
      required:
        - sheet
        - a1_range
      title: SpreadsheetRange
      type: object
    TextRange:
      additionalProperties: false
      description: >-
        A character span in a derivative's text, with the page(s) it falls on.


        ``pages`` is every page the span overlaps — a chunk that straddles a
        page

        marker belongs to both, and a reader handed only the first would miss
        the

        part of the span that carries the match. ``page`` is the first of them,

        kept because most producers and consumers only ever deal in one page.
      properties:
        char_end:
          title: Char End
          type: integer
        char_start:
          title: Char Start
          type: integer
        kind:
          const: text_range
          default: text_range
          title: Kind
          type: string
        page:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page
        pages:
          items:
            type: integer
          title: Pages
          type: array
      required:
        - char_start
        - char_end
      title: TextRange
      type: object
    VisualRegion:
      additionalProperties: false
      properties:
        bbox:
          maxItems: 4
          minItems: 4
          prefixItems:
            - type: number
            - type: number
            - type: number
            - type: number
          title: Bbox
          type: array
        kind:
          const: visual_region
          default: visual_region
          title: Kind
          type: string
        page:
          title: Page
          type: integer
      required:
        - page
        - bbox
      title: VisualRegion
      type: object
    QueryTableColumn:
      additionalProperties: false
      description: One public column in a retained result preview.
      properties:
        data_type:
          title: Data Type
          type: string
        name:
          title: Name
          type: string
      required:
        - name
        - data_type
      title: QueryTableColumn
      type: object
    SplitArtifact:
      additionalProperties: false
      properties:
        url:
          title: Url
          type: string
      required:
        - url
      title: SplitArtifact
      type: object
    SplitConfidence:
      additionalProperties: false
      properties:
        band:
          default: unavailable
          enum:
            - unavailable
            - low
            - medium
            - high
          title: Band
          type: string
        score:
          anyOf:
            - type: number
            - type: 'null'
          title: Score
      title: SplitConfidence
      type: object
    SplitSegmentCategory:
      additionalProperties: false
      properties:
        description:
          default: ''
          title: Description
          type: string
        id:
          title: Id
          type: string
        label:
          title: Label
          type: string
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
        subcategory_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Subcategory Id
      required:
        - id
        - label
      title: SplitSegmentCategory
      type: object
    SplitInstance:
      additionalProperties: false
      properties:
        key:
          title: Key
          type: string
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
      required:
        - key
      title: SplitInstance
      type: object
    DerivationStep:
      additionalProperties: false
      description: One SQL step in a table-QA derivation DAG.
      properties:
        kind:
          enum:
            - extraction
            - transformation
          title: Kind
          type: string
        label:
          title: Label
          type: string
        preview_rows:
          items:
            additionalProperties:
              type: string
            type: object
          title: Preview Rows
          type: array
        reads:
          description: result_ids this step depends on.
          items:
            type: string
          title: Reads
          type: array
        result_id:
          title: Result Id
          type: string
        sql:
          title: Sql
          type: string
      required:
        - result_id
        - sql
        - kind
        - label
      title: DerivationStep
      type: object
    TableQueryColumn:
      additionalProperties: false
      description: One column of an executed SQL query's result preview.
      properties:
        data_type:
          title: Data Type
          type: string
        name:
          title: Name
          type: string
      required:
        - name
        - data_type
      title: TableQueryColumn
      type: object
    RowRangeQueryRegion:
      additionalProperties: false
      description: >-
        A verified region on a pageable tabular artifact, addressed by row
        number.


        A parquet upload stored as-is uses its own row order. A jsonl or parquet

        derivative uses the queried artifact's row order; ``derivative_path``
        names

        that artifact when it differs from the caller-facing ``source_path``.
      properties:
        basis:
          default: verified
          description: >-
            How this region was established. 'verified': a claim whose cited
            value was mechanically re-computed from exactly these rows.
            'inputs': one table's contribution to a derived (multi-table) figure
            — the rows were verified to match the claim's filters, but the
            figure itself is not re-computable from this table alone.
            'provenance': no claim covered this query, so the region records
            what the query's captured provenance proved it read — never a
            whole-table guess. Absent on legacy payloads, which are all
            'verified'.
          enum:
            - verified
            - inputs
            - provenance
          title: Basis
          type: string
        bounding:
          default: false
          description: >-
            True when this is a bounding range over a large match set rather
            than exact runs.
          title: Bounding
          type: boolean
        columns:
          description: Cited column names, in table order.
          items:
            type: string
          title: Columns
          type: array
        derivative_path:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pageable derivative (parquet or jsonl) when it is not the uploaded
            source itself.
          title: Derivative Path
        end_row:
          description: Last row of the run, 0-based and inclusive.
          title: End Row
          type: integer
        filter_columns:
          description: >-
            Columns the verified claim filtered on to select these rows, minus
            any already in columns. Empty on legacy payloads.
          items:
            type: string
          title: Filter Columns
          type: array
        kind:
          const: row_range
          default: row_range
          title: Kind
          type: string
        matched_rows:
          default: 0
          description: How many source rows the region covers.
          title: Matched Rows
          type: integer
        read_columns:
          description: >-
            Columns the query read from this table (output lineage), minus any
            already in columns or filter_columns. Populated on a
            'provenance'-basis region only; empty otherwise and on legacy
            payloads.
          items:
            type: string
          title: Read Columns
          type: array
        region_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            Opaque identity for paging this exact region when a receipt has
            several regions on one file.
          title: Region Id
        runs:
          description: >-
            Exact matched-row runs inside the span, so a bounding range stays
            pageable as matches only. May cover fewer than matched_rows when the
            verifier truncated its run list; empty on legacy payloads.
          items:
            $ref: '#/components/schemas/ArtifactRowRun'
          title: Runs
          type: array
        runs_replayable:
          default: false
          description: >-
            True only when grounding-rows can reconstruct this exact region
            predicate for pages beyond runs. Regions without a safe replay fail
            closed instead of returning broader rows.
          title: Runs Replayable
          type: boolean
        runs_truncated:
          default: false
          description: >-
            True when runs is an exact ordered prefix of matched islands and
            more matched rows exist. Later pages require guarded replay; false
            when the runs are complete or on legacy payloads.
          title: Runs Truncated
          type: boolean
        scan_index:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Which scan of the query read these rows, when the region records one
            scan rather than the whole table. A query can read one file more
            than once — a narrow CTE and a broad one, say — and each such scan
            grounds separately, so this identifies the scan to replay for
            further row pages. Absent on a whole-table span, on verified
            regions, and on legacy payloads.
          title: Scan Index
        scan_label:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The scan named the way the query spells it: 'main query', 'CTE
            <name>', or 'subquery <n>'. Present exactly when scan_index is.
          title: Scan Label
        source_path:
          description: Uploaded file path this region belongs to.
          title: Source Path
          type: string
        start_row:
          description: First row of the run, 0-based and inclusive.
          title: Start Row
          type: integer
      required:
        - source_path
        - start_row
        - end_row
      title: RowRangeQueryRegion
      type: object
    SheetQueryRegion:
      additionalProperties: false
      description: >-
        A verified region on a source file with an addressable grid.


        Coordinates are expressed in the caller's uploaded workbook or CSV,
        never

        in the internal parquet derivative.
      properties:
        a1_range:
          description: A1 range on the original sheet, e.g. 'B12:D15'.
          title: A1 Range
          type: string
        basis:
          default: verified
          description: >-
            How this region was established. 'verified': a claim whose cited
            value was mechanically re-computed from exactly these rows.
            'inputs': one table's contribution to a derived (multi-table) figure
            — the rows were verified to match the claim's filters, but the
            figure itself is not re-computable from this table alone.
            'provenance': no claim covered this query, so the region records
            what the query's captured provenance proved it read — never a
            whole-table guess. Absent on legacy payloads, which are all
            'verified'.
          enum:
            - verified
            - inputs
            - provenance
          title: Basis
          type: string
        bounding:
          default: false
          description: >-
            True when this is a bounding box over a large match set rather than
            exact runs.
          title: Bounding
          type: boolean
        kind:
          const: sheet
          default: sheet
          title: Kind
          type: string
        matched_rows:
          default: 0
          description: How many source rows the region covers.
          title: Matched Rows
          type: integer
        scan_index:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Which scan of the query read these rows, when the region records one
            scan rather than the whole table. A query can read one file more
            than once — a narrow CTE and a broad one, say — and each such scan
            grounds separately, so this identifies the scan to replay for
            further row pages. Absent on a whole-table span, on verified
            regions, and on legacy payloads.
          title: Scan Index
        scan_label:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The scan named the way the query spells it: 'main query', 'CTE
            <name>', or 'subquery <n>'. Present exactly when scan_index is.
          title: Scan Label
        sheet_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Workbook tab, when applicable.
          title: Sheet Name
        source_path:
          description: Uploaded file path this region points at.
          title: Source Path
          type: string
      required:
        - source_path
        - a1_range
      title: SheetQueryRegion
      type: object
    PageRegion:
      additionalProperties: false
      description: A region on a 1-based page. A bbox is a 4-point polygon.
      properties:
        kind:
          const: page_region
          default: page_region
          title: Kind
          type: string
        page:
          minimum: 1
          title: Page
          type: integer
        polygons:
          items:
            items:
              maxItems: 2
              minItems: 2
              prefixItems:
                - type: number
                - type: number
              type: array
            minItems: 3
            type: array
          title: Polygons
          type: array
      required:
        - page
      title: PageRegion
      type: object
    SheetRange:
      additionalProperties: false
      description: A cell range on a spreadsheet sheet.
      properties:
        a1_range:
          title: A1 Range
          type: string
        kind:
          const: sheet_range
          default: sheet_range
          title: Kind
          type: string
        sheet:
          title: Sheet
          type: string
      required:
        - sheet
        - a1_range
      title: SheetRange
      type: object
    TableRegion:
      additionalProperties: false
      description: >-
        Rows and columns from a Parquet source, with reproducible SQL
        provenance.
      properties:
        columns:
          items:
            type: string
          title: Columns
          type: array
        exact:
          title: Exact
          type: boolean
        kind:
          const: table_region
          default: table_region
          title: Kind
          type: string
        matched_rows:
          default: 0
          minimum: 0
          title: Matched Rows
          type: integer
        row_ranges:
          items:
            $ref: '#/components/schemas/TableRowRange'
          title: Row Ranges
          type: array
        source_file_name:
          title: Source File Name
          type: string
        sql:
          title: Sql
          type: string
      required:
        - source_file_name
        - sql
        - exact
      title: TableRegion
      type: object
    TextSpan:
      additionalProperties: false
      description: A character span in derived text (optional page when known).
      properties:
        char_end:
          minimum: 0
          title: Char End
          type: integer
        char_start:
          minimum: 0
          title: Char Start
          type: integer
        kind:
          const: text_span
          default: text_span
          title: Kind
          type: string
        page:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          title: Page
      required:
        - char_start
        - char_end
      title: TextSpan
      type: object
    BooleanCell:
      additionalProperties: false
      properties:
        kind:
          const: boolean
          default: boolean
          title: Kind
          type: string
        value:
          title: Value
          type: boolean
      required:
        - value
      title: BooleanCell
      type: object
    DateCell:
      additionalProperties: false
      properties:
        date:
          description: ISO 8601 calendar date.
          title: Date
          type: string
        kind:
          const: date
          default: date
          title: Kind
          type: string
      required:
        - date
      title: DateCell
      type: object
    MoneyCell:
      additionalProperties: false
      description: >-
        An amount with its original ISO currency — never converted or normalized
        (D9).


        Mixed-currency comparison and aggregation are unsupported in this
        version:

        results assume the compared records share a currency and always show it.
      properties:
        amount:
          description: Decimal-as-string, 2 decimal places.
          title: Amount
          type: string
        currency:
          description: ISO 4217 code as stated by the source.
          title: Currency
          type: string
        currency_source:
          default: stated
          description: >-
            How the currency was arrived at: 'stated' when the source named it,
            'assumed' when the workspace's default currency disambiguated a
            symbol the source left open (e.g. a bare '$'). Never a conversion —
            the amount is always the figure the document showed.
          enum:
            - stated
            - assumed
          title: Currency Source
          type: string
        kind:
          const: money
          default: money
          title: Kind
          type: string
      required:
        - amount
        - currency
      title: MoneyCell
      type: object
    NumberCell:
      additionalProperties: false
      properties:
        kind:
          const: number
          default: number
          title: Kind
          type: string
        number:
          description: Decimal-as-string.
          title: Number
          type: string
      required:
        - number
      title: NumberCell
      type: object
    TextCell:
      additionalProperties: false
      properties:
        kind:
          const: text
          default: text
          title: Kind
          type: string
        text:
          title: Text
          type: string
      required:
        - text
      title: TextCell
      type: object
    OcrElement:
      additionalProperties: false
      description: One inline OCR word or line.
      properties:
        bbox:
          $ref: '#/components/schemas/OcrBoundingBox'
        chunk_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Chunk Index
        confidence:
          title: Confidence
          type: number
        rotation:
          default: 0
          title: Rotation
          type: integer
        text:
          title: Text
          type: string
      required:
        - text
        - bbox
        - confidence
      title: OcrElement
      type: object
    ParseSpreadsheetSheet:
      additionalProperties: false
      description: Cell-map sidecar for one rendered spreadsheet sheet.
      properties:
        cell_map_url:
          title: Cell Map Url
          type: string
        sheet_name:
          title: Sheet Name
          type: string
      required:
        - sheet_name
        - cell_map_url
      title: ParseSpreadsheetSheet
      type: object
    ArtifactRowRun:
      additionalProperties: false
      description: One inclusive 0-based run of matched rows in the pageable artifact.
      properties:
        end:
          description: Last matched row of the run, 0-based and inclusive.
          title: End
          type: integer
        start:
          description: First matched row of the run, 0-based and inclusive.
          title: Start
          type: integer
      required:
        - start
        - end
      title: ArtifactRowRun
      type: object
    TableRowRange:
      additionalProperties: false
      description: Inclusive 0-based row range in a table source.
      properties:
        end:
          minimum: 0
          title: End
          type: integer
        start:
          minimum: 0
          title: Start
          type: integer
      required:
        - start
        - end
      title: TableRowRange
      type: object
    OcrBoundingBox:
      additionalProperties: false
      description: Normalized top-left OCR geometry for one page.
      properties:
        height:
          title: Height
          type: number
        left:
          title: Left
          type: number
        original_page:
          title: Original Page
          type: integer
        page:
          title: Page
          type: integer
        top:
          title: Top
          type: number
        width:
          title: Width
          type: number
      required:
        - left
        - top
        - width
        - height
        - page
        - original_page
      title: OcrBoundingBox
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey

````