openapi: 3.0.3
info:
  title: PowerContext API
  description: Remote PowerContext transport. Runtime behavior is reported by /v1/capabilities.
  version: 0.0.1
security:
  - BearerAuth: []
  - {}
paths:
  /health/live:
    get:
      security: []
      tags: [health]
      summary: Get process liveness
      operationId: get_liveness
      responses:
        "200":
          description: The API process is alive.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
  /health/ready:
    get:
      security: []
      tags: [health]
      summary: Get deployment readiness
      operationId: get_readiness
      responses:
        "200":
          description: Required Server bindings are ready; optional capabilities may be degraded.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadinessResponse"
        "503":
          description: Required Server bindings are not ready.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadinessResponse"
  /v1/capabilities:
    get:
      tags: [capabilities]
      summary: Get runtime capabilities
      operationId: get_capabilities
      responses:
        "200":
          description: Behavior enabled by the assembled runtime.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Capabilities"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /v1/sources/content:
    post:
      tags: [sources]
      summary: Capture durable ContentSource evidence
      description: Accept raw content as an idempotent Source without synchronously deriving Artifacts.
      operationId: capture_content_source
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CaptureContentSourceRequest"
      responses:
        "202":
          description: The Source is durably stored for later processing.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CaptureContentSourceResponse"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/context/prepare:
    post:
      tags: [context]
      summary: Prepare bounded context for an Agent turn
      description: Prepare final, ephemeral context from Runtime-owned sources without persisting or injecting it.
      operationId: prepare_context
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrepareContextRequest"
      responses:
        "200":
          description: Final context ready for direct injection, or a normal empty result.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreparedContext"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff/activate:
    post:
      tags: [handoff]
      summary: Activate Handoff generation at a Source boundary
      description: Evaluate the standard Handoff Trigger and synchronously execute any emitted PrepareHandoff Action.
      operationId: activate_handoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ActivateHandoffRequest"
      responses:
        "200":
          description: A generated inspectable Draft, or an ignored boundary that was already consumed.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffActivation"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff/prepare:
    post:
      tags: [handoff]
      summary: Generate an inspectable Handoff Draft
      operationId: prepare_handoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrepareHandoffRequest"
      responses:
        "200":
          description: An uncommitted Draft generated from the selected exact evidence.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffDraft"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff/finalize:
    post:
      tags: [handoff]
      summary: Finalize an inspected Handoff Draft
      operationId: finalize_handoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FinalizeHandoffRequest"
      responses:
        "200":
          description: A temporary Handoff ready for direct transfer or explicit commit.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreparedHandoff"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff/commit:
    post:
      tags: [handoff]
      summary: Commit an explicit Handoff milestone
      operationId: commit_handoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommitHandoffRequest"
      responses:
        "200":
          description: The committed immutable Handoff Revision.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommittedHandoff"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff/continue:
    post:
      tags: [handoff]
      summary: Resolve a Handoff as untrusted historical input
      operationId: continue_handoff
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContinueHandoffRequest"
      responses:
        "200":
          description: Resolved content and per-statement evidence availability.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffResolution"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/flush:
    post:
      tags: [memory]
      summary: Process the pending Source window into Memory
      description: Run one bounded Source-to-Memory activation for operational control and testing.
      operationId: flush_memory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FlushMemoryRequest"
      responses:
        "200":
          description: The activation completed or found no pending Sources.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FlushMemoryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/remember:
    post:
      tags: [memory]
      summary: Remember explicit Memory content
      description: Save one already-curated Memory entry without creating a Source or invoking extraction.
      operationId: remember_memory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RememberMemoryRequest"
      responses:
        "200":
          description: The explicit Memory mutation completed.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryMutationResponse"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/search:
    post:
      tags: [memory]
      summary: Search active Memory entries
      description: Retrieve relevant active Memory entries within one explicit application scope.
      operationId: search_memory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchMemoryRequest"
      responses:
        "200":
          description: Matching Memory entries, or an empty result when the scope has no Memory.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchMemoryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/entries/list:
    post:
      tags: [memory]
      summary: List Memory entries
      description: >-
        Read active entries from the current Memory head. Inactive entries are available only when explicitly
        requested for audit.
      operationId: list_memory_entries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListMemoryEntriesRequest"
      responses:
        "200":
          description: The selected entries from the current Memory head.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListMemoryEntriesResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/entries/get:
    post:
      tags: [memory]
      summary: Get an exact Memory entry version
      description: Resolve an immutable entry citation within one Memory Revision.
      operationId: get_memory_entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetMemoryEntryRequest"
      responses:
        "200":
          description: The exact Memory entry version.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryEntry"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/entries/revise:
    post:
      tags: [memory]
      summary: Revise an exact Memory entry
      description: Replace active entry content against an explicit current Memory Revision.
      operationId: revise_memory_entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReviseMemoryEntryRequest"
      responses:
        "200":
          description: The Memory entry revision completed.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryMutationResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/entries/retire:
    post:
      tags: [memory]
      summary: Retire an exact Memory entry
      description: Deactivate an entry against an explicit current Memory Revision without deleting history.
      operationId: retire_memory_entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetireMemoryEntryRequest"
      responses:
        "200":
          description: The Memory entry retirement completed.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MemoryMutationResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/memory/changes:
    post:
      tags: [memory]
      summary: List Memory Revision changes
      description: Read compact entry changes without expanding entry bodies.
      operationId: list_memory_changes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListMemoryChangesRequest"
      responses:
        "200":
          description: Compact changes through the selected Memory Revision.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListMemoryChangesResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/experience/propose:
    post:
      tags: [experience]
      summary: Propose Experience content
      description: Persist a pending Experience Candidate without creating an Artifact Revision.
      operationId: propose_experience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProposeExperienceRequest"
      responses:
        "201":
          description: The pending Experience Candidate.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidate"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/experience/generate:
    post:
      tags: [experience]
      summary: Generate an Experience Candidate
      description: Use the configured model and caller-selected exact evidence; persist only a schema-valid pending Candidate.
      operationId: generate_experience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateExperienceRequest"
      responses:
        "200":
          description: A pending Candidate or an explicit semantic no-op.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratedCandidateResponse"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/experience/get:
    post:
      tags: [experience]
      summary: Get an exact Experience Revision
      description: Read approved Experience content and its exact direct evidence.
      operationId: get_experience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetExperienceRequest"
      responses:
        "200":
          description: The exact approved Experience Revision.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExperienceArtifact"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/skill/propose:
    post:
      tags: [skill]
      summary: Propose managed Skill content
      description: Persist a pending managed Skill Candidate without creating an Artifact Revision.
      operationId: propose_skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProposeSkillRequest"
      responses:
        "201":
          description: The pending managed Skill Candidate.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidate"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/skill/generate:
    post:
      tags: [skill]
      summary: Generate a managed Skill Candidate
      description: Use the configured model with an explicit provenance shape; persist only a schema-valid pending Candidate.
      operationId: generate_skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateSkillRequest"
      responses:
        "200":
          description: A pending Candidate or an explicit semantic no-op.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratedCandidateResponse"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/skill/get:
    post:
      tags: [skill]
      summary: Get an exact managed Skill Revision
      description: Read approved managed Skill content and its exact direct evidence.
      operationId: get_skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetSkillRequest"
      responses:
        "200":
          description: The exact approved managed Skill Revision.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SkillArtifact"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/external-skills/scan:
    post:
      tags: [skill]
      summary: Scan configured external Skill roots
      description: Replace the current host-local Registry projection without copying or rewriting package content.
      operationId: scan_external_skills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScanExternalSkillsRequest"
      responses:
        "200":
          description: The rebuildable provider snapshot.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanExternalSkillsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/external-skills/list:
    post:
      tags: [skill]
      summary: List external Skills visible on this host
      description: Return live local resolutions; unavailable registrations are omitted unless explicitly requested.
      operationId: list_external_skills
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListExternalSkillsRequest"
      responses:
        "200":
          description: External Skills resolved against the current Agent, host, scope, and fingerprint.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListExternalSkillsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/external-skills/resolve:
    post:
      tags: [skill]
      summary: Resolve an exact external Skill fingerprint
      description: Resolve only the registered local package version requested by the caller; never install or fall back.
      operationId: resolve_external_skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResolveExternalSkillRequest"
      responses:
        "200":
          description: The live exact-resolution result, which may be unavailable.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExternalSkillResolution"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/external-skills/import:
    post:
      tags: [skill]
      summary: Import or fork an external Skill into Review
      description: Capture one exact local snapshot and use the configured model to propose a new managed Skill Candidate.
      operationId: import_external_skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportExternalSkillRequest"
      responses:
        "200":
          description: A pending managed Skill Candidate or an explicit semantic no-op.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GeneratedCandidateResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/artifact-candidates/list:
    post:
      tags: [review]
      summary: List Artifact Candidates
      description: Page current Candidate heads; pending is the default Review Inbox view.
      operationId: list_artifact_candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListArtifactCandidatesRequest"
      responses:
        "200":
          description: The selected current Candidate heads.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidatePage"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/artifact-candidates/get:
    post:
      tags: [review]
      summary: Get an Artifact Candidate
      description: Read the current head and exact immutable proposal version.
      operationId: get_artifact_candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetArtifactCandidateRequest"
      responses:
        "200":
          description: The current Candidate head.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidate"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/artifact-candidates/approve:
    post:
      tags: [review]
      summary: Approve an Artifact Candidate
      description: Commit the reviewed proposal and mark the Candidate approved in one transaction.
      operationId: approve_artifact_candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApproveArtifactCandidateRequest"
      responses:
        "200":
          description: The approved Candidate and exact result Artifact.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidate"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/artifact-candidates/reject:
    post:
      tags: [review]
      summary: Reject an Artifact Candidate
      description: Move the exact pending version to its rejected terminal state without writing an Artifact.
      operationId: reject_artifact_candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RejectArtifactCandidateRequest"
      responses:
        "200":
          description: The rejected Candidate.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidate"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/artifact-candidates/revise:
    post:
      tags: [review]
      summary: Revise an Artifact Candidate
      description: Append a complete replacement proposal as the next immutable pending version.
      operationId: revise_artifact_candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReviseArtifactCandidateRequest"
      responses:
        "200":
          description: The next pending Candidate version.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactCandidate"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/stats:
    get:
      tags: [stats]
      summary: Get scoped product statistics
      operationId: get_stats
      parameters:
        - name: scope_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 256
            pattern: '.*\S.*'
        - name: period
          in: query
          required: false
          schema:
            $ref: "#/components/schemas/StatsPeriod"
      responses:
        "200":
          description: Current inventory, model usage, and recall token estimates for the scope.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
            Cache-Control:
              description: Prevent caches from retaining scoped statistics.
              schema:
                type: string
                enum: [no-store]
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScopedStats"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/projects/create:
    post:
      tags: [handoff-reports]
      summary: Create a Handoff Report Project
      operationId: create_handoff_report_project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateHandoffReportProjectRequest"
      responses:
        "201":
          description: The created Report Project.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDescriptor"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/projects/list:
    post:
      tags: [handoff-reports]
      summary: List Handoff Report Projects
      operationId: list_handoff_report_projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListHandoffReportProjectsRequest"
      responses:
        "200":
          description: A cursor-paginated page of Report Projects.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectPage"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/projects/get:
    post:
      tags: [handoff-reports]
      summary: Get a Handoff Report Project
      operationId: get_handoff_report_project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetHandoffReportProjectRequest"
      responses:
        "200":
          description: The exact current Report Project descriptor.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDescriptor"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/projects/update:
    post:
      tags: [handoff-reports]
      summary: Update a Handoff Report Project
      operationId: update_handoff_report_project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateHandoffReportProjectRequest"
      responses:
        "200":
          description: The updated Report Project descriptor.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDescriptor"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/workstreams/register:
    post:
      tags: [handoff-reports]
      summary: Register a Handoff Report Workstream
      operationId: register_handoff_report_workstream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegisterHandoffReportWorkstreamRequest"
      responses:
        "201":
          description: The registered Report Workstream.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkstreamDescriptor"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/workstreams/list:
    post:
      tags: [handoff-reports]
      summary: List Handoff Report Workstreams
      operationId: list_handoff_report_workstreams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListHandoffReportWorkstreamsRequest"
      responses:
        "200":
          description: A cursor-paginated page of Report Workstreams.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkstreamPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/workstreams/update:
    post:
      tags: [handoff-reports]
      summary: Update a Handoff Report Workstream
      operationId: update_handoff_report_workstream
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateHandoffReportWorkstreamRequest"
      responses:
        "200":
          description: The updated Report Workstream descriptor.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkstreamDescriptor"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/get:
    post:
      tags: [handoff-reports]
      summary: Generate a Handoff Report
      operationId: get_handoff_report
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetHandoffReportRequest"
      responses:
        "200":
          description: A canonical JSON report, optionally accompanied by Markdown.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
            Cache-Control:
              description: Prevent caches from retaining scoped report data.
              schema:
                type: string
                enum: [no-store]
            X-PowerContext-Selection-Digest:
              description: Digest of the exact report selection.
              schema:
                type: string
                pattern: '^sha256:[0-9a-f]{64}$'
            X-PowerContext-Report-Digest:
              description: Digest of the selected output projection.
              schema:
                type: string
                pattern: '^sha256:[0-9a-f]{64}$'
            Content-Disposition:
              description: Safe attachment filename when download is true.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffReportResponse"
            text/markdown:
              schema:
                type: string
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "413":
          $ref: "#/components/responses/ReportTooLarge"
        "503":
          $ref: "#/components/responses/Unavailable"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/activities/record:
    post:
      tags: [handoff-reports]
      summary: Record a Handoff Report Activity
      operationId: record_handoff_report_activity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordHandoffReportActivityRequest"
      responses:
        "201":
          description: The idempotently recorded Report Activity.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoredHandoffReportActivity"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/activities/list:
    post:
      tags: [handoff-reports]
      summary: List Handoff Report Activities
      operationId: list_handoff_report_activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ListHandoffReportActivitiesRequest"
      responses:
        "200":
          description: A frozen cursor page of Report Activities.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffReportActivityPage"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/activities/purge:
    post:
      tags: [handoff-reports]
      summary: Purge Handoff Report Activities
      operationId: purge_handoff_report_activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PurgeHandoffReportActivitiesRequest"
      responses:
        "200":
          description: The number of deleted Report-owned Activity rows.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PurgeHandoffReportActivitiesResponse"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/workspace-bindings/get:
    post:
      tags: [handoff-reports]
      summary: Get a Handoff Report Workspace Binding
      operationId: get_handoff_report_workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetHandoffReportWorkspaceRequest"
      responses:
        "200":
          description: The confirmed Workspace binding.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffReportWorkspaceBinding"
        "404":
          $ref: "#/components/responses/NotFound"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/workspace-bindings/attach:
    post:
      tags: [handoff-reports]
      summary: Attach a Handoff Report Workspace Binding
      operationId: attach_handoff_report_workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttachHandoffReportWorkspaceRequest"
      responses:
        "200":
          description: The confirmed Workspace binding.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffReportWorkspaceBinding"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
  /v1/handoff-reports/workspace-bindings/detach:
    post:
      tags: [handoff-reports]
      summary: Detach a Handoff Report Workspace Binding
      operationId: detach_handoff_report_workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DetachHandoffReportWorkspaceRequest"
      responses:
        "200":
          description: The detached Workspace binding record.
          headers:
            X-PowerContext-Request-ID:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HandoffReportWorkspaceBinding"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/InvalidRequest"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Static bearer token used when local Server authentication is enabled.
  headers:
    BearerChallenge:
      description: Authentication scheme required by the Server.
      schema:
        type: string
        example: Bearer
    RequestId:
      description: Opaque identifier for correlating one request.
      schema:
        type: string
  responses:
    Unauthorized:
      description: A valid bearer token is required by this Server deployment.
      headers:
        WWW-Authenticate:
          $ref: "#/components/headers/BearerChallenge"
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Conflict:
      description: The command conflicts with current immutable state.
      headers:
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InvalidRequest:
      description: The request violates the transport or application contract.
      headers:
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ReportTooLarge:
      description: The selected Handoff Report exceeds the deterministic output limit.
      headers:
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: The requested immutable Memory value was not found.
      headers:
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unavailable:
      description: A required Runtime binding or dependency is unavailable.
      headers:
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: The Server failed without exposing internal details.
      headers:
        X-PowerContext-Request-ID:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    ActivateHandoffRequest:
      type: object
      additionalProperties: false
      required: [scope_id, boundary_source, objective]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        boundary_source:
          $ref: "#/components/schemas/SourceReference"
        objective:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        evidence:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffCitation"
          default: []
        max_bytes:
          type: integer
          minimum: 512
          maximum: 32768
          default: 8000
    ArtifactReference:
      type: object
      additionalProperties: false
      required: [family, artifact_id, revision]
      properties:
        family:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        artifact_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        revision:
          type: integer
          minimum: 1
    ArtifactCandidate:
      type: object
      additionalProperties: false
      required:
        - candidate_id
        - version
        - family
        - status
        - proposal
        - source_refs
        - artifact_refs
        - target
        - reason
        - result_artifact
        - decision_reason
      properties:
        candidate_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        version:
          type: integer
          minimum: 1
        family:
          $ref: "#/components/schemas/CandidateFamily"
        status:
          $ref: "#/components/schemas/CandidateStatus"
        proposal:
          oneOf:
            - $ref: "#/components/schemas/ExperienceProposal"
            - $ref: "#/components/schemas/SkillProposal"
        source_refs:
          type: array
          maxItems: 32
          description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          maxItems: 32
          description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/ArtifactReference"
        target:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
        result_artifact:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        decision_reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    ArtifactCandidatePage:
      type: object
      additionalProperties: false
      required: [candidates, next_cursor]
      properties:
        candidates:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactCandidate"
        next_cursor:
          type: string
          nullable: true
    ApproveArtifactCandidateRequest:
      type: object
      additionalProperties: false
      required: [scope_id, candidate_id, expected_version]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        candidate_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        expected_version:
          type: integer
          minimum: 1
    Capabilities:
      type: object
      additionalProperties: false
      required:
        [source_types, artifact_families, memory_extraction, handoff_generation, search_modes, context_versions]
      properties:
        source_types:
          type: array
          items:
            type: string
        artifact_families:
          type: array
          items:
            type: string
        memory_extraction:
          type: boolean
          description: Whether pending Sources can be extracted into Memory.
        experience_generation:
          type: boolean
          default: false
          description: Whether the configured model can generate reviewed Experience Candidates.
        managed_skill_generation:
          type: boolean
          default: false
          description: Whether the configured model can generate reviewed managed Skill Candidates.
        external_skill_registry:
          type: boolean
          default: false
          description: Whether host-local external Skill discovery and exact resolution are configured.
        handoff_generation:
          type: boolean
          description: Whether exact evidence can be generated into an inspectable Handoff Draft.
        search_modes:
          type: array
          items:
            $ref: "#/components/schemas/MemorySearchMode"
        context_versions:
          type: array
          items:
            $ref: "#/components/schemas/PreparedContextSchema"
    FamilyCount:
      type: object
      additionalProperties: false
      required: [family, total]
      properties:
        family:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        total:
          type: integer
          minimum: 0
    CandidateFamilyCount:
      type: object
      additionalProperties: false
      required: [family, total, pending, approved, rejected]
      properties:
        family:
          $ref: "#/components/schemas/CandidateFamily"
        total:
          type: integer
          minimum: 0
        pending:
          type: integer
          minimum: 0
        approved:
          type: integer
          minimum: 0
        rejected:
          type: integer
          minimum: 0
    MemoryKindCount:
      type: object
      additionalProperties: false
      required: [kind, total, active, inactive]
      properties:
        kind:
          type: string
          minLength: 1
          maxLength: 128
        total:
          type: integer
          minimum: 0
        active:
          type: integer
          minimum: 0
        inactive:
          type: integer
          minimum: 0
    SourceInventoryStatistics:
      type: object
      additionalProperties: false
      required: [total, memory_processed, memory_pending]
      properties:
        total:
          type: integer
          minimum: 0
        memory_processed:
          type: integer
          minimum: 0
        memory_pending:
          type: integer
          minimum: 0
    ArtifactInventoryStatistics:
      type: object
      additionalProperties: false
      required: [total, by_family]
      properties:
        total:
          type: integer
          minimum: 0
        by_family:
          type: array
          items:
            $ref: "#/components/schemas/FamilyCount"
    CandidateInventoryStatistics:
      type: object
      additionalProperties: false
      required: [total, pending, approved, rejected, by_family]
      properties:
        total:
          type: integer
          minimum: 0
        pending:
          type: integer
          minimum: 0
        approved:
          type: integer
          minimum: 0
        rejected:
          type: integer
          minimum: 0
        by_family:
          type: array
          items:
            $ref: "#/components/schemas/CandidateFamilyCount"
    MemoryEntryInventoryStatistics:
      type: object
      additionalProperties: false
      required: [total, active, inactive, by_kind]
      properties:
        total:
          type: integer
          minimum: 0
        active:
          type: integer
          minimum: 0
        inactive:
          type: integer
          minimum: 0
        by_kind:
          type: array
          items:
            $ref: "#/components/schemas/MemoryKindCount"
    MemoryInventoryStatistics:
      type: object
      additionalProperties: false
      required: [entries]
      properties:
        entries:
          $ref: "#/components/schemas/MemoryEntryInventoryStatistics"
    InventoryStatistics:
      type: object
      additionalProperties: false
      required: [sources, artifacts, candidates, memory]
      properties:
        sources:
          $ref: "#/components/schemas/SourceInventoryStatistics"
        artifacts:
          $ref: "#/components/schemas/ArtifactInventoryStatistics"
        candidates:
          $ref: "#/components/schemas/CandidateInventoryStatistics"
        memory:
          $ref: "#/components/schemas/MemoryInventoryStatistics"
    ModelUsageValue:
      type: object
      additionalProperties: false
      required: [requests, input_tokens, output_tokens]
      properties:
        requests:
          type: integer
          minimum: 0
        input_tokens:
          type: integer
          minimum: 0
          nullable: true
        output_tokens:
          type: integer
          minimum: 0
          nullable: true
    ModelUsageStatistics:
      type: object
      additionalProperties: false
      required: [generation, embedding]
      properties:
        generation:
          $ref: "#/components/schemas/ModelUsageValue"
        embedding:
          $ref: "#/components/schemas/ModelUsageValue"
    ModelUsagePurposeBreakdown:
      type: object
      additionalProperties: false
      required: [purpose, generation, embedding]
      properties:
        purpose:
          type: string
          minLength: 1
          maxLength: 64
        generation:
          $ref: "#/components/schemas/ModelUsageValue"
        embedding:
          $ref: "#/components/schemas/ModelUsageValue"
    ModelUsageDay:
      type: object
      additionalProperties: false
      required: [date, generation, embedding, by_purpose]
      properties:
        date:
          type: string
          format: date
        generation:
          $ref: "#/components/schemas/ModelUsageValue"
        embedding:
          $ref: "#/components/schemas/ModelUsageValue"
        by_purpose:
          type: array
          maxItems: 16
          items:
            $ref: "#/components/schemas/ModelUsagePurposeBreakdown"
    ResolvedUsagePeriod:
      type: object
      additionalProperties: false
      required: [preset, start_date, end_date, timezone]
      properties:
        preset:
          $ref: "#/components/schemas/StatsPeriod"
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        timezone:
          type: string
          enum: [UTC]
    UsageStatistics:
      type: object
      additionalProperties: false
      required: [period, totals, by_purpose, daily]
      properties:
        period:
          $ref: "#/components/schemas/ResolvedUsagePeriod"
        totals:
          $ref: "#/components/schemas/ModelUsageStatistics"
        by_purpose:
          type: array
          maxItems: 16
          items:
            $ref: "#/components/schemas/ModelUsagePurposeBreakdown"
        daily:
          type: array
          maxItems: 30
          items:
            $ref: "#/components/schemas/ModelUsageDay"
    TokenEstimatorProfile:
      type: object
      additionalProperties: false
      required: [estimator_id, version]
      properties:
        estimator_id:
          type: string
          minLength: 1
          maxLength: 128
        version:
          type: string
          minLength: 1
          maxLength: 64
    RecallTokenValue:
      type: object
      additionalProperties: false
      required: [preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction]
      properties:
        preparations:
          type: integer
          minimum: 0
        ready_preparations:
          type: integer
          minimum: 0
        comparable_preparations:
          type: integer
          minimum: 0
        baseline_tokens:
          type: integer
          minimum: 0
        recalled_tokens:
          type: integer
          minimum: 0
        token_reduction:
          type: integer
    RecallTokenDay:
      type: object
      additionalProperties: false
      required: [date, preparations, ready_preparations, comparable_preparations, baseline_tokens, recalled_tokens, token_reduction]
      properties:
        date:
          type: string
          format: date
        preparations:
          type: integer
          minimum: 0
        ready_preparations:
          type: integer
          minimum: 0
        comparable_preparations:
          type: integer
          minimum: 0
        baseline_tokens:
          type: integer
          minimum: 0
        recalled_tokens:
          type: integer
          minimum: 0
        token_reduction:
          type: integer
    RecallTokenStatistics:
      type: object
      additionalProperties: false
      required: [period, estimator, totals, daily]
      properties:
        period:
          $ref: "#/components/schemas/ResolvedUsagePeriod"
        estimator:
          $ref: "#/components/schemas/TokenEstimatorProfile"
          nullable: true
        totals:
          $ref: "#/components/schemas/RecallTokenValue"
        daily:
          type: array
          maxItems: 30
          items:
            $ref: "#/components/schemas/RecallTokenDay"
    ScopedStats:
      type: object
      additionalProperties: false
      required: [scope_id, as_of, inventory, usage, recall]
      properties:
        scope_id:
          type: string
        as_of:
          type: string
          format: date-time
        inventory:
          $ref: "#/components/schemas/InventoryStatistics"
        usage:
          $ref: "#/components/schemas/UsageStatistics"
        recall:
          $ref: "#/components/schemas/RecallTokenStatistics"
    GetStatsRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        period:
          $ref: "#/components/schemas/StatsPeriod"
          default: 30d
    CaptureContentSourceRequest:
      type: object
      additionalProperties: false
      required: [scope_id, source_id, content]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        source_id:
          type: string
          minLength: 1
          maxLength: 256
        content:
          type: string
          minLength: 1
          maxLength: 200000
        metadata:
          type: object
          additionalProperties: true
          nullable: true
    CaptureContentSourceResponse:
      type: object
      additionalProperties: false
      required: [status, source, position]
      properties:
        status:
          $ref: "#/components/schemas/CaptureStatus"
        source:
          $ref: "#/components/schemas/SourceReference"
        position:
          type: integer
          minimum: 1
    CommitHandoffRequest:
      type: object
      additionalProperties: false
      required: [scope_id, handoff]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        handoff:
          $ref: "#/components/schemas/PreparedHandoff"
    CommittedHandoff:
      type: object
      additionalProperties: false
      required: [reference, content, source_refs, artifact_refs]
      properties:
        reference:
          $ref: "#/components/schemas/ArtifactReference"
        content:
          $ref: "#/components/schemas/HandoffContent"
        source_refs:
          type: array
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactReference"
    ContinueHandoffRequest:
      type: object
      additionalProperties: false
      required: [scope_id, selection]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        selection:
          $ref: "#/components/schemas/HandoffSelection"
        prepared:
          $ref: "#/components/schemas/PreparedHandoff"
          nullable: true
        revision:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
    FinalizeHandoffRequest:
      type: object
      additionalProperties: false
      required: [scope_id, draft]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        draft:
          $ref: "#/components/schemas/HandoffDraft"
    HandoffArtifactCitation:
      type: object
      additionalProperties: false
      required: [kind, artifact_ref]
      properties:
        kind:
          type: string
          enum: [artifact]
        artifact_ref:
          $ref: "#/components/schemas/ArtifactReference"
    HandoffActivation:
      type: object
      additionalProperties: false
      required: [status, boundary_source, previous_position, current_position, draft]
      properties:
        status:
          $ref: "#/components/schemas/HandoffActivationStatus"
        boundary_source:
          $ref: "#/components/schemas/SourceReference"
        previous_position:
          type: integer
          minimum: 0
        current_position:
          type: integer
          minimum: 0
        draft:
          $ref: "#/components/schemas/HandoffDraft"
          nullable: true
    HandoffCitation:
      oneOf:
        - $ref: "#/components/schemas/HandoffSourceCitation"
        - $ref: "#/components/schemas/HandoffArtifactCitation"
        - $ref: "#/components/schemas/HandoffMemoryCitation"
      discriminator:
        propertyName: kind
        mapping:
          source: "#/components/schemas/HandoffSourceCitation"
          artifact: "#/components/schemas/HandoffArtifactCitation"
          memory: "#/components/schemas/HandoffMemoryCitation"
    HandoffContent:
      type: object
      additionalProperties: false
      required: [schema, objective, state, disposition, next_action, omissions]
      properties:
        schema:
          $ref: "#/components/schemas/HandoffSchema"
        objective:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        state:
          type: array
          minItems: 1
          maxItems: 64
          items:
            $ref: "#/components/schemas/HandoffStatement"
        disposition:
          $ref: "#/components/schemas/HandoffDisposition"
        next_action:
          $ref: "#/components/schemas/HandoffStatement"
          nullable: true
        omissions:
          type: array
          maxItems: 64
          items:
            $ref: "#/components/schemas/HandoffOmission"
    HandoffDraft:
      type: object
      additionalProperties: false
      required: [objective, state, disposition, next_action, omissions]
      properties:
        objective:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        state:
          type: array
          minItems: 1
          maxItems: 64
          items:
            $ref: "#/components/schemas/HandoffStatement"
        disposition:
          $ref: "#/components/schemas/HandoffDisposition"
        next_action:
          $ref: "#/components/schemas/HandoffStatement"
          nullable: true
        omissions:
          type: array
          maxItems: 64
          items:
            $ref: "#/components/schemas/HandoffOmission"
    HandoffEvidenceCheck:
      type: object
      additionalProperties: false
      required: [claim, state_index, status, unavailable_evidence]
      properties:
        claim:
          $ref: "#/components/schemas/HandoffClaim"
        state_index:
          type: integer
          minimum: 0
          nullable: true
        status:
          $ref: "#/components/schemas/HandoffEvidenceStatus"
        unavailable_evidence:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffCitation"
    HandoffMemoryCitation:
      type: object
      additionalProperties: false
      required: [kind, memory_citation]
      properties:
        kind:
          type: string
          enum: [memory]
        memory_citation:
          $ref: "#/components/schemas/MemoryCitation"
    HandoffOmission:
      type: object
      additionalProperties: false
      required: [text, citation]
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        citation:
          $ref: "#/components/schemas/HandoffCitation"
          nullable: true
    HandoffResolution:
      type: object
      additionalProperties: false
      required:
        [trust, status, scope_id, content, selection, selected_revision, current_revision, evidence_checks]
      properties:
        trust:
          type: string
          enum: [untrusted_history]
        status:
          $ref: "#/components/schemas/HandoffResolutionStatus"
        scope_id:
          type: string
        content:
          $ref: "#/components/schemas/HandoffContent"
          nullable: true
        selection:
          $ref: "#/components/schemas/HandoffSelection"
          nullable: true
        selected_revision:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        current_revision:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        evidence_checks:
          type: array
          maxItems: 65
          items:
            $ref: "#/components/schemas/HandoffEvidenceCheck"
    HandoffSourceCitation:
      type: object
      additionalProperties: false
      required: [kind, source_ref]
      properties:
        kind:
          type: string
          enum: [source]
        source_ref:
          $ref: "#/components/schemas/SourceReference"
    HandoffStatement:
      type: object
      additionalProperties: false
      required: [text, citations]
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        citations:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffCitation"
    PrepareHandoffRequest:
      type: object
      additionalProperties: false
      required: [scope_id, objective, evidence]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        objective:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        evidence:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffCitation"
        max_bytes:
          type: integer
          minimum: 512
          maximum: 32768
          default: 8000
    PreparedHandoff:
      type: object
      additionalProperties: false
      required: [schema, scope_id, base, content]
      properties:
        schema:
          $ref: "#/components/schemas/PreparedHandoffSchema"
        scope_id:
          type: string
        base:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        content:
          $ref: "#/components/schemas/HandoffContent"
    PreparedContext:
      type: object
      additionalProperties: false
      required: [schema, status, content, content_bytes]
      properties:
        schema:
          $ref: "#/components/schemas/PreparedContextSchema"
        status:
          $ref: "#/components/schemas/PreparedContextStatus"
        content:
          type: string
          nullable: true
        content_bytes:
          type: integer
          minimum: 0
    EntryChange:
      type: object
      additionalProperties: false
      required: [op, entry_id, from_entry_version_id, to_entry_version_id, reason]
      properties:
        op:
          $ref: "#/components/schemas/EntryChangeOperation"
        entry_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        from_entry_version_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
          nullable: true
        to_entry_version_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
          nullable: true
        reason:
          type: string
          nullable: true
    ExperienceArtifact:
      type: object
      additionalProperties: false
      required: [artifact, content, source_refs, artifact_refs]
      properties:
        artifact:
          $ref: "#/components/schemas/ArtifactReference"
        content:
          $ref: "#/components/schemas/ExperienceProposal"
        source_refs:
          type: array
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactReference"
    ExperienceProposal:
      type: object
      additionalProperties: false
      required: [situation, action, outcome, lesson]
      properties:
        situation:
          type: string
          minLength: 1
          maxLength: 8000
          pattern: '.*\S.*'
        action:
          type: string
          minLength: 1
          maxLength: 8000
          pattern: '.*\S.*'
        outcome:
          type: string
          minLength: 1
          maxLength: 8000
          pattern: '.*\S.*'
        lesson:
          type: string
          minLength: 1
          maxLength: 8000
          pattern: '.*\S.*'
    SkillArtifact:
      type: object
      additionalProperties: false
      required: [artifact, content, source_refs, artifact_refs]
      properties:
        artifact:
          $ref: "#/components/schemas/ArtifactReference"
        content:
          $ref: "#/components/schemas/SkillProposal"
        source_refs:
          type: array
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactReference"
    SkillProposal:
      type: object
      additionalProperties: false
      required: [name, description, instructions, validation]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^\S(?:.*\S)?$'
        description:
          type: string
          minLength: 1
          maxLength: 2000
          pattern: '^\S(?:.*\S)?$'
        instructions:
          type: string
          minLength: 1
          maxLength: 32000
          pattern: '.*\S.*'
        validation:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: "#/components/schemas/SkillValidationItem"
    SkillValidationItem:
      type: string
      minLength: 1
      maxLength: 2000
      pattern: '^\S(?:.*\S)?$'
    ExternalSkillRegistration:
      type: object
      additionalProperties: false
      required:
        - external_skill_id
        - provider
        - agent_kind
        - host_id
        - installation_scope
        - locator
        - fingerprint
        - name
        - description
      properties:
        external_skill_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        provider:
          type: string
          enum: [codex]
        agent_kind:
          type: string
          enum: [codex]
        host_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^\S(?:.*\S)?$'
        installation_scope:
          $ref: "#/components/schemas/ExternalSkillInstallationScope"
        locator:
          type: string
          minLength: 1
          maxLength: 2000
          pattern: '^\S(?:.*\S)?$'
          description: Host-local locator; not a cross-Agent or cross-host contract.
        fingerprint:
          type: string
          pattern: '^[0-9a-f]{64}$'
        name:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^\S(?:.*\S)?$'
        description:
          type: string
          minLength: 1
          maxLength: 2000
          pattern: '^\S(?:.*\S)?$'
    ExternalSkillResolution:
      type: object
      additionalProperties: false
      required: [registration, status, entrypoint]
      properties:
        registration:
          $ref: "#/components/schemas/ExternalSkillRegistration"
        status:
          $ref: "#/components/schemas/ExternalSkillResolutionStatus"
        entrypoint:
          type: string
          nullable: true
          description: Host-local SKILL.md path; present only when the exact fingerprint is available.
    ScanExternalSkillsResponse:
      type: object
      additionalProperties: false
      required: [registrations, skipped]
      properties:
        registrations:
          type: array
          items:
            $ref: "#/components/schemas/ExternalSkillRegistration"
        skipped:
          type: integer
          minimum: 0
    ListExternalSkillsResponse:
      type: object
      additionalProperties: false
      required: [skills]
      properties:
        skills:
          type: array
          items:
            $ref: "#/components/schemas/ExternalSkillResolution"
    ErrorDetail:
      type: object
      additionalProperties: false
      required: [code, message, details]
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
          additionalProperties: true
          nullable: true
    ErrorResponse:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          $ref: "#/components/schemas/ErrorDetail"
    FlushMemoryRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
    FlushMemoryResponse:
      type: object
      additionalProperties: false
      required: [status, previous_cursor, current_cursor, high_watermark, processed_source_count]
      properties:
        status:
          $ref: "#/components/schemas/FlushStatus"
        previous_cursor:
          type: integer
          minimum: 0
        current_cursor:
          type: integer
          minimum: 0
        high_watermark:
          type: integer
          minimum: 0
        processed_source_count:
          type: integer
          minimum: 0
        memory:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
    GetMemoryEntryRequest:
      type: object
      additionalProperties: false
      required: [scope_id, citation]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        citation:
          $ref: "#/components/schemas/MemoryCitation"
    GetArtifactCandidateRequest:
      type: object
      additionalProperties: false
      required: [scope_id, candidate_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        candidate_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
    GetExperienceRequest:
      type: object
      additionalProperties: false
      required: [scope_id, artifact]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        artifact:
          $ref: "#/components/schemas/ArtifactReference"
    GetSkillRequest:
      type: object
      additionalProperties: false
      required: [scope_id, artifact]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        artifact:
          $ref: "#/components/schemas/ArtifactReference"
    CreateHandoffReportProjectRequest:
      type: object
      additionalProperties: false
      required: [project_key, title]
      properties:
        project_key:
          type: string
          minLength: 1
          maxLength: 64
        title:
          type: string
          minLength: 1
          maxLength: 256
        description:
          type: string
          maxLength: 2000
          nullable: true
        default_locale:
          $ref: "#/components/schemas/ReportLocale"
          default: zh-CN
        timezone:
          type: string
          minLength: 1
          maxLength: 256
          default: UTC
    ListHandoffReportProjectsRequest:
      type: object
      additionalProperties: false
      properties:
        cursor:
          type: string
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        include_archived:
          type: boolean
          default: false
    GetHandoffReportProjectRequest:
      type: object
      additionalProperties: false
      required: [project_id]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
    UpdateHandoffReportProjectRequest:
      type: object
      additionalProperties: false
      required: [project, expected_version]
      properties:
        project:
          $ref: "#/components/schemas/ProjectDescriptor"
        expected_version:
          type: integer
          minimum: 1
    RegisterHandoffReportWorkstreamRequest:
      type: object
      additionalProperties: false
      required: [project_id, scope_id, title, kind]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
        key:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        title:
          type: string
          minLength: 1
          maxLength: 256
        kind:
          $ref: "#/components/schemas/WorkstreamKind"
        catalog_state:
          $ref: "#/components/schemas/ReportCatalogState"
          default: included
        external_refs:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffReportExternalReference"
          default: []
        labels:
          type: array
          maxItems: 32
          items:
            type: string
            minLength: 1
            maxLength: 128
          default: []
    ListHandoffReportWorkstreamsRequest:
      type: object
      additionalProperties: false
      required: [project_id]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        cursor:
          type: string
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        include_archived:
          type: boolean
          default: false
    UpdateHandoffReportWorkstreamRequest:
      type: object
      additionalProperties: false
      required: [workstream, expected_version]
      properties:
        workstream:
          $ref: "#/components/schemas/WorkstreamDescriptor"
        expected_version:
          type: integer
          minimum: 1
    GetHandoffReportRequest:
      type: object
      additionalProperties: false
      required: [project_id]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        locale:
          $ref: "#/components/schemas/ReportLocale"
          nullable: true
        include_evidence_checks:
          type: boolean
          default: true
        format:
          $ref: "#/components/schemas/ReportFormat"
          default: markdown
        include_archived:
          type: boolean
          default: false
        download:
          type: boolean
          default: false
        period:
          $ref: "#/components/schemas/HandoffReportPeriodRequest"
          nullable: true
    HandoffReportPeriodRequest:
      type: object
      additionalProperties: false
      required: [start, end]
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        timezone:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        compare_to_previous_period:
          type: boolean
          default: false
    HandoffReportResponse:
      type: object
      additionalProperties: false
      required: [format, report, markdown, selection_digest, report_digest]
      properties:
        format:
          $ref: "#/components/schemas/ReportFormat"
        report:
          type: object
          additionalProperties: true
          nullable: true
        markdown:
          type: string
          nullable: true
        selection_digest:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
        report_digest:
          type: string
          pattern: '^sha256:[0-9a-f]{64}$'
    ReportActivitySource:
      type: string
      enum: [handoff_observation, git_commit, git_worktree, coding_session, other]
    ReportTimeBasis:
      type: string
      enum: [source_reported, host_observed, first_seen, current_only, unknown]
    HandoffReportActivityAgent:
      type: object
      additionalProperties: false
      properties:
        provider:
          type: string
          minLength: 1
          maxLength: 64
          nullable: true
        label:
          type: string
          minLength: 1
          maxLength: 128
          nullable: true
    HandoffReportActivityVcsContext:
      type: object
      additionalProperties: false
      properties:
        branch:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        head_revision:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
    RecordHandoffReportActivityRequest:
      type: object
      additionalProperties: false
      required: [project_id, source, source_event_id, time_basis]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        source:
          $ref: "#/components/schemas/ReportActivitySource"
        source_event_id:
          type: string
          minLength: 1
          maxLength: 256
        source_ref:
          $ref: "#/components/schemas/HandoffReportExternalReference"
          nullable: true
        occurred_at:
          type: string
          format: date-time
          nullable: true
        time_basis:
          $ref: "#/components/schemas/ReportTimeBasis"
        title:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        summary:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
        agent:
          $ref: "#/components/schemas/HandoffReportActivityAgent"
          nullable: true
        session_id:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        vcs_context:
          $ref: "#/components/schemas/HandoffReportActivityVcsContext"
          nullable: true
        evidence_refs:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffReportExternalReference"
          default: []
    HandoffReportActivity:
      type: object
      additionalProperties: false
      required: [schema, event_id, project_id, scope_id, source, source_event_id, source_ref, occurred_at, observed_at, time_basis, title, summary, agent, session_id, vcs_context, evidence_refs, trust]
      properties:
        schema:
          type: string
          enum: [powercontext.handoff-report-activity.v1]
        event_id:
          type: string
          minLength: 1
          maxLength: 256
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        source:
          $ref: "#/components/schemas/ReportActivitySource"
        source_event_id:
          type: string
          minLength: 1
          maxLength: 256
        source_ref:
          $ref: "#/components/schemas/HandoffReportExternalReference"
          nullable: true
        occurred_at:
          type: string
          format: date-time
          nullable: true
        observed_at:
          type: string
          format: date-time
        time_basis:
          $ref: "#/components/schemas/ReportTimeBasis"
        title:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        summary:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
        agent:
          $ref: "#/components/schemas/HandoffReportActivityAgent"
          nullable: true
        session_id:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        vcs_context:
          $ref: "#/components/schemas/HandoffReportActivityVcsContext"
          nullable: true
        evidence_refs:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffReportExternalReference"
        trust:
          type: string
          enum: [untrusted_observation]
    StoredHandoffReportActivity:
      type: object
      additionalProperties: false
      required: [cursor, event]
      properties:
        cursor:
          type: integer
          minimum: 1
        event:
          $ref: "#/components/schemas/HandoffReportActivity"
    ListHandoffReportActivitiesRequest:
      type: object
      additionalProperties: false
      required: [project_id]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        period_start:
          type: string
          format: date-time
          nullable: true
        period_end:
          type: string
          format: date-time
          nullable: true
        sources:
          type: array
          maxItems: 5
          items:
            $ref: "#/components/schemas/ReportActivitySource"
          nullable: true
        after_cursor:
          type: integer
          minimum: 0
          default: 0
        through_cursor:
          type: integer
          minimum: 0
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
    HandoffReportActivityPage:
      type: object
      additionalProperties: false
      required: [items, next_cursor, high_watermark]
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/HandoffReportActivity"
        next_cursor:
          type: integer
          minimum: 1
          nullable: true
        high_watermark:
          type: integer
          minimum: 0
    PurgeHandoffReportActivitiesRequest:
      type: object
      additionalProperties: false
      required: [project_id, observed_before]
      properties:
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        observed_before:
          type: string
          format: date-time
    PurgeHandoffReportActivitiesResponse:
      type: object
      additionalProperties: false
      required: [deleted_count]
      properties:
        deleted_count:
          type: integer
          minimum: 0
    HandoffReportRepositoryRef:
      type: object
      additionalProperties: false
      required: [provider, repository_id, normalized_remote, subpath]
      properties:
        provider:
          type: string
          enum: [github, gitlab, local, other]
        repository_id:
          type: string
          minLength: 1
          maxLength: 256
          nullable: true
        normalized_remote:
          type: string
          minLength: 1
          maxLength: 2048
          nullable: true
        subpath:
          type: string
          minLength: 1
          maxLength: 1024
          nullable: true
    HandoffReportWorkspaceBinding:
      type: object
      additionalProperties: false
      required: [schema, workspace_instance_id, project_id, repository_ref, state, confirmed_at, version]
      properties:
        schema:
          type: string
          enum: [powercontext.workspace-binding.v1]
        workspace_instance_id:
          type: string
          minLength: 1
          maxLength: 256
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        repository_ref:
          $ref: "#/components/schemas/HandoffReportRepositoryRef"
        state:
          type: string
          enum: [confirmed, detached]
        confirmed_at:
          type: string
          format: date-time
        version:
          type: integer
          minimum: 1
    GetHandoffReportWorkspaceRequest:
      type: object
      additionalProperties: false
      required: [workspace_instance_id]
      properties:
        workspace_instance_id:
          type: string
          minLength: 1
          maxLength: 256
    AttachHandoffReportWorkspaceRequest:
      type: object
      additionalProperties: false
      required: [workspace_instance_id, project_id, repository_ref, expected_version]
      properties:
        workspace_instance_id:
          type: string
          minLength: 1
          maxLength: 256
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        repository_ref:
          $ref: "#/components/schemas/HandoffReportRepositoryRef"
        expected_version:
          type: integer
          minimum: 1
          nullable: true
    DetachHandoffReportWorkspaceRequest:
      type: object
      additionalProperties: false
      required: [workspace_instance_id, expected_version]
      properties:
        workspace_instance_id:
          type: string
          minLength: 1
          maxLength: 256
        expected_version:
          type: integer
          minimum: 1
    ProjectDescriptor:
      type: object
      additionalProperties: false
      required: [schema, project_id, project_key, title, description, default_locale, timezone, catalog_state, version]
      properties:
        schema:
          type: string
          enum: [powercontext.project.v1]
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        project_key:
          type: string
          minLength: 1
          maxLength: 64
        title:
          type: string
          minLength: 1
          maxLength: 256
        description:
          type: string
          maxLength: 2000
          nullable: true
        default_locale:
          $ref: "#/components/schemas/ReportLocale"
        timezone:
          type: string
          minLength: 1
          maxLength: 256
        catalog_state:
          $ref: "#/components/schemas/ReportCatalogState"
        version:
          type: integer
          minimum: 1
    ProjectPage:
      type: object
      additionalProperties: false
      required: [items, next_cursor]
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ProjectDescriptor"
        next_cursor:
          type: string
          nullable: true
    WorkstreamDescriptor:
      type: object
      additionalProperties: false
      required: [schema, scope_id, project_id, key, title, kind, catalog_state, external_refs, labels, version]
      properties:
        schema:
          type: string
          enum: [powercontext.workstream.v1]
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
        project_id:
          type: string
          minLength: 1
          maxLength: 256
        key:
          type: string
          maxLength: 64
          nullable: true
        title:
          type: string
          minLength: 1
          maxLength: 256
        kind:
          $ref: "#/components/schemas/WorkstreamKind"
        catalog_state:
          $ref: "#/components/schemas/ReportCatalogState"
        external_refs:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/HandoffReportExternalReference"
        labels:
          type: array
          maxItems: 32
          items:
            type: string
            minLength: 1
            maxLength: 128
        version:
          type: integer
          minimum: 1
    WorkstreamPage:
      type: object
      additionalProperties: false
      required: [items, next_cursor]
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/WorkstreamDescriptor"
        next_cursor:
          type: string
          nullable: true
    HandoffReportExternalReference:
      type: object
      additionalProperties: false
      required: [kind, provider, external_id, url]
      properties:
        kind:
          type: string
          enum: [issue, task, pull_request, branch, feature, release, program, other]
        provider:
          type: string
          minLength: 1
          maxLength: 64
        external_id:
          type: string
          minLength: 1
          maxLength: 256
        url:
          type: string
          maxLength: 2048
          nullable: true
    ReportLocale:
      type: string
      enum: [zh-CN, en]
    ReportFormat:
      type: string
      enum: [json, markdown]
    ReportCatalogState:
      type: string
      enum: [included, archived]
    WorkstreamKind:
      type: string
      enum: [feature, bug, refactor, operations, research, other]
    HealthResponse:
      type: object
      additionalProperties: false
      required: [status]
      properties:
        status:
          type: string
    ListMemoryChangesRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        since_revision:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            Exclusive lower bound; 0 requests complete history from Revision 1.
            Positive nonexistent revisions are errors.
    ListMemoryChangesResponse:
      type: object
      additionalProperties: false
      required: [revisions]
      properties:
        memory:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        revisions:
          type: array
          items:
            $ref: "#/components/schemas/MemoryRevisionChanges"
    ListMemoryEntriesRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        include_inactive:
          type: boolean
          default: false
          description: Include inactive entries from the current Memory head for explicit audit.
    ListMemoryEntriesResponse:
      type: object
      additionalProperties: false
      required: [entries]
      properties:
        memory:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        entries:
          type: array
          items:
            $ref: "#/components/schemas/MemoryEntry"
    ListArtifactCandidatesRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        status:
          $ref: "#/components/schemas/CandidateStatus"
          default: pending
        family:
          $ref: "#/components/schemas/CandidateFamily"
          nullable: true
        cursor:
          type: string
          minLength: 1
          maxLength: 128
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
    ListExternalSkillsRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        include_unavailable:
          type: boolean
          default: false
    MemoryEntry:
      type: object
      additionalProperties: false
      required:
        - citation
        - version
        - kind
        - text
        - state
        - source_refs
        - artifact_refs
      properties:
        citation:
          $ref: "#/components/schemas/MemoryCitation"
        version:
          type: integer
          minimum: 1
        kind:
          type: string
        text:
          type: string
        state:
          $ref: "#/components/schemas/MemoryEntryState"
        source_refs:
          type: array
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactReference"
    MemoryMutationResponse:
      type: object
      additionalProperties: false
      required: [memory]
      properties:
        memory:
          $ref: "#/components/schemas/ArtifactReference"
        entry:
          $ref: "#/components/schemas/MemoryEntry"
          nullable: true
    MemoryCitation:
      type: object
      additionalProperties: false
      required: [memory_ref, entry_id, entry_version_id]
      properties:
        memory_ref:
          $ref: "#/components/schemas/ArtifactReference"
        entry_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        entry_version_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
    MemoryRevisionChanges:
      type: object
      additionalProperties: false
      required: [memory_ref, changes]
      properties:
        memory_ref:
          $ref: "#/components/schemas/ArtifactReference"
        changes:
          type: array
          items:
            $ref: "#/components/schemas/EntryChange"
    PrepareContextRequest:
      type: object
      additionalProperties: false
      required: [scope_id, query]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        query:
          type: string
          minLength: 1
          maxLength: 8192
          pattern: '.*\S.*'
        max_bytes:
          type: integer
          minimum: 512
          maximum: 32768
          default: 8000
    ProposeExperienceRequest:
      type: object
      additionalProperties: false
      required: [scope_id, proposal, source_refs, artifact_refs]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        proposal:
          $ref: "#/components/schemas/ExperienceProposal"
        source_refs:
          type: array
          maxItems: 32
          description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          maxItems: 32
          description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/ArtifactReference"
        target:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    GenerateExperienceRequest:
      type: object
      additionalProperties: false
      required: [scope_id, source_refs, artifact_refs]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        source_refs:
          type: array
          maxItems: 32
          description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          maxItems: 32
          description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/ArtifactReference"
        target:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    ProposeSkillRequest:
      type: object
      additionalProperties: false
      required: [scope_id, proposal, source_refs, artifact_refs]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        proposal:
          $ref: "#/components/schemas/SkillProposal"
        source_refs:
          type: array
          maxItems: 32
          description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          maxItems: 32
          description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/ArtifactReference"
        target:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    SkillGenerationOrigin:
      type: string
      enum: [experience, source, usage]
      description: The operation-specific direct provenance shape required for managed Skill generation.
    GenerateSkillRequest:
      type: object
      additionalProperties: false
      required: [scope_id, origin, source_refs, artifact_refs]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        origin:
          $ref: "#/components/schemas/SkillGenerationOrigin"
        source_refs:
          type: array
          maxItems: 32
          description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          maxItems: 32
          description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/ArtifactReference"
        target:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    GeneratedCandidateStatus:
      type: string
      enum: [pending, no_op]
    GeneratedCandidateResponse:
      type: object
      additionalProperties: false
      required: [status, candidate]
      properties:
        status:
          $ref: "#/components/schemas/GeneratedCandidateStatus"
        candidate:
          $ref: "#/components/schemas/ArtifactCandidate"
          nullable: true
    ReadinessResponse:
      type: object
      additionalProperties: false
      required: [status, checks]
      properties:
        status:
          $ref: "#/components/schemas/ReadinessStatus"
        checks:
          type: object
          additionalProperties:
            type: string
    ReadinessStatus:
      type: string
      enum: [ready, degraded, not_ready]
    RememberMemoryRequest:
      type: object
      additionalProperties: false
      required: [scope_id, kind, text]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        kind:
          type: string
          minLength: 1
          maxLength: 128
        text:
          type: string
          minLength: 1
          description: Must not exceed 8192 UTF-8 bytes after normalization.
        reason:
          type: string
          maxLength: 512
          nullable: true
        expected_revision:
          type: integer
          minimum: 1
          nullable: true
    RetireMemoryEntryRequest:
      type: object
      additionalProperties: false
      required: [scope_id, citation]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        citation:
          $ref: "#/components/schemas/MemoryCitation"
        reason:
          type: string
          maxLength: 512
          nullable: true
    RejectArtifactCandidateRequest:
      type: object
      additionalProperties: false
      required: [scope_id, candidate_id, expected_version, reason]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        candidate_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        expected_version:
          type: integer
          minimum: 1
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          pattern: '.*\S.*'
    ReviseArtifactCandidateRequest:
      type: object
      additionalProperties: false
      required: [scope_id, candidate_id, expected_version, proposal, source_refs, artifact_refs]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        candidate_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        expected_version:
          type: integer
          minimum: 1
        proposal:
          oneOf:
            - $ref: "#/components/schemas/ExperienceProposal"
            - $ref: "#/components/schemas/SkillProposal"
        source_refs:
          type: array
          maxItems: 32
          description: Exact Source evidence. Counted with artifact_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/SourceReference"
        artifact_refs:
          type: array
          maxItems: 32
          description: Exact Artifact evidence. Counted with source_refs toward a combined maximum of 32 references.
          items:
            $ref: "#/components/schemas/ArtifactReference"
        target:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    ReviseMemoryEntryRequest:
      type: object
      additionalProperties: false
      required: [scope_id, citation, kind, text]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        citation:
          $ref: "#/components/schemas/MemoryCitation"
        kind:
          type: string
          minLength: 1
          maxLength: 128
        text:
          type: string
          minLength: 1
          description: Must not exceed 8192 UTF-8 bytes after normalization.
        reason:
          type: string
          maxLength: 512
          nullable: true
    SearchMemoryHit:
      type: object
      additionalProperties: false
      required: [citation, text, score, matched_by]
      properties:
        citation:
          $ref: "#/components/schemas/MemoryCitation"
        text:
          type: string
        score:
          type: number
          minimum: 0
          maximum: 1
        matched_by:
          type: array
          items:
            $ref: "#/components/schemas/MemoryMatchedBy"
    SearchMemoryRequest:
      type: object
      additionalProperties: false
      required: [scope_id, query]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        query:
          type: string
          minLength: 1
          maxLength: 8192
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        mode:
          $ref: "#/components/schemas/MemorySearchMode"
          default: auto
    ScanExternalSkillsRequest:
      type: object
      additionalProperties: false
      required: [scope_id]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
    ResolveExternalSkillRequest:
      type: object
      additionalProperties: false
      required: [scope_id, external_skill_id, fingerprint]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        external_skill_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        fingerprint:
          type: string
          pattern: '^[0-9a-f]{64}$'
    ExternalSkillImportMode:
      type: string
      enum: [import, fork]
    ImportExternalSkillRequest:
      type: object
      additionalProperties: false
      required: [scope_id, external_skill_id, fingerprint, mode]
      properties:
        scope_id:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '.*\S.*'
        external_skill_id:
          type: string
          minLength: 1
          maxLength: 128
          pattern: '^[\x21-\x7E]+$'
        fingerprint:
          type: string
          pattern: '^[0-9a-f]{64}$'
          description: Exact package fingerprint captured into Source lineage.
        mode:
          $ref: "#/components/schemas/ExternalSkillImportMode"
        reason:
          type: string
          minLength: 1
          maxLength: 2000
          nullable: true
    SearchMemoryResponse:
      type: object
      additionalProperties: false
      required: [hits]
      properties:
        memory:
          $ref: "#/components/schemas/ArtifactReference"
          nullable: true
        mode:
          $ref: "#/components/schemas/MemoryUsedSearchMode"
          nullable: true
        hits:
          type: array
          items:
            $ref: "#/components/schemas/SearchMemoryHit"
    SourceReference:
      type: object
      additionalProperties: false
      required: [name, source_id]
      properties:
        name:
          type: string
          description: Stable Source type.
        source_id:
          type: string
    CaptureStatus:
      type: string
      enum: [accepted]
    StatsPeriod:
      type: string
      enum: [today, 7d, 30d]
    CandidateFamily:
      type: string
      enum: [experience, skill]
    ExternalSkillInstallationScope:
      type: string
      enum: [user, project, plugin]
    ExternalSkillResolutionStatus:
      type: string
      enum: [available, unavailable]
    CandidateStatus:
      type: string
      enum: [pending, approved, rejected]
    PreparedContextSchema:
      type: string
      enum: [powercontext.prepared-context.v1]
    PreparedContextStatus:
      type: string
      enum: [ready, empty]
    EntryChangeOperation:
      type: string
      enum: [add, revise, deactivate, reactivate]
    FlushStatus:
      type: string
      enum: [idle, processed]
    MemoryEntryState:
      type: string
      enum: [active, inactive]
    MemoryMatchedBy:
      type: string
      enum: [fts, vector]
    MemorySearchMode:
      type: string
      enum: [auto, fts, vector, hybrid]
    MemoryUsedSearchMode:
      type: string
      enum: [fts, vector, hybrid]
    HandoffClaim:
      type: string
      enum: [state, next_action]
    HandoffActivationStatus:
      type: string
      enum: [generated, ignored]
    HandoffDisposition:
      type: string
      enum: [continuable, blocked, complete]
    HandoffEvidenceStatus:
      type: string
      enum: [available, unavailable]
    HandoffResolutionStatus:
      type: string
      enum: [empty, resolved]
    HandoffSchema:
      type: string
      enum: [powercontext.handoff.v1]
    HandoffSelection:
      type: string
      enum: [prepared, exact, latest]
    PreparedHandoffSchema:
      type: string
      enum: [powercontext.prepared-handoff.v1]